Approvals and client tools

Approvals and client-hosted tools suspend the current invocation before external input is needed.

Required action	JSON	SSE or WebSocket	Resume with
Human approval	`requires_action`	`approval.requested`	`POST /approvals/{approvalId}`
Client-hosted tool	`requires_action`	`client_tool.requested`	HTTP result or `client_tool.result` frame

Decide an approval

POST /approvals/{approvalId}
Content-Type: application/json

{"decision":"approve"}

POST /approvals/{approvalId}
Content-Type: application/json

{"decision":"deny"}

Outcome	Runtime behavior
Approved	Resume the suspended task
Denied or expired	Do not run protected code
Reused decision	Reject the consumed approval
Binding changed	Reject the mismatched approval
Later protected block	Create another request

Harnest does not restart the tool or replay earlier work.

POST /client-tools/{requestId}
Content-Type: application/json

{"output":{"title":"Harnest documentation"}}

Reply to client_tool.requested with a client_tool.result frame using the same request ID.

Submitted output is identity-bound, consumed once, and validated before execution resumes.

Choose always-on or dynamic approval and bind it to the exact operation.

Declare typed work owned by the connected client.

Development stores are process-local. Restart recovery needs durable storage and a resumable framework boundary.