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`	HTTP decision or `approval.decision` frame
Client-hosted tool	`requires_action`	`client_tool.requested`	HTTP result or `client_tool.result` frame

Decide an approval

HTTP approve
HTTP deny
WebSocket

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

{"decision":"approve"}

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

{"decision":"deny"}

Reply on the active /live connection with the response and approval IDs issued by Harnest:

{"type":"approval.decision","responseId":"resp_...","approvalId":"approval_...","decision":"approve"}

Harnest commits the decision, sends approval.resolved, and only then resumes execution on that socket. Use decision: "deny" to reject the action.

The HTTP endpoint remains available when the approving interface does not own the live socket. Both paths apply the same user, response, approval, expiry, and one-time-use checks.

Approval outcomes

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.

Recover a response

Every neutral JSON, SSE, and WebSocket invocation has a response ID. Poll it with the same authenticated user and session:

GET /responses/{responseId}?sessionId={sessionId}

Read the returned state and, for requires_action, its approval or client-tool ID. Do not infer task identity from chat messages. Completed responses survive restarts with a Harnest-owned checkpointer. Pending approvals and client-tool exchanges must return to their owning process. Advanced mode cannot guarantee recovery across native boundaries you replace.

Submit a client-tool result

HTTP
WebSocket

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. For @client_input, the action also includes privateInput: true and inputSchema. Send the private form through the same HTTP output field or WebSocket result frame. Harnest delivers it only to the application handler and returns the separately authored public response. Keep the submitted value out of client transcripts and telemetry. AG-UI clients use an explicit interrupt resume.

Human approval authoring

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

Client-hosted tools

Declare typed work owned by the connected client.

Development stores are process-local. Durable terminal recovery needs a Harnest-owned checkpointer; resuming an unfinished action also needs the process that owns that suspension.

Overview

Get started

Harnest Studio

Guides

API reference

Approvals and client tools

Decide an approval

Approval outcomes

Recover a response

Submit a client-tool result

Human approval authoring

Client-hosted tools

​Decide an approval

​Approval outcomes

​Recover a response

​Submit a client-tool result

Human approval authoring

Client-hosted tools

Decide an approval

Approval outcomes

Recover a response

Submit a client-tool result