Agent: Session gates and approvals
Section titled “Agent: Session gates and approvals”A gate parks a turn until it is answered. Use these endpoints to list question and confirm gates, answer them, request answer suggestions, and manage a session’s approval mode, lock, permission rules, and YOLO auto-approve state.
In the Hub, open the chat and answer its waiting approval with Allow once or Deny. To change its approval mode, open Details, Session, Approvals and choose Default or Strict while the chat is idle; Auto-approve is in the same section.
Inspect gates and policy
Section titled “Inspect gates and policy”GET /api/v1/agent/gates
Section titled “GET /api/v1/agent/gates”Lists the gates waiting for a human. The response covers the same sessions visible to GET /api/v1/agent/sessions, including each live session’s own gate and, for a helper_gates session, its helpers’ gates.
A gate is listed only while this gateway holds its session live. A session held only by another client is not listed until it is attached here. Bot runtime gates, including bot.dispatch, bot.peek, and bot.answer_gate frames, are answered by the Bot runtime and are not listed or counted.
Each item contains the daemon’s redacted gate description. A gate that resolves or changes while the list is being read is omitted and counted in meta.omitted. Results are ordered by oldest parked first, then session_id, then generation.
The realm query parameter selects one realm, and realm=all selects every realm served by the login. A computer header is not supported. The response uses Cache-Control: no-store.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
include_system | query | boolean | No | When true, also list gates from daemon-owned system and resident sessions. |
realm | query | string | No | Realm to list: "global", a 24-hex realm id, or "all" for every realm served by the login. Also accepted through X-Hoody-Realm, except for "all". |
page | query | integer | No | 1-based page number. An invalid page is a 400 bad_request. |
limit | query | integer | No | Maximum items per page. An omitted or zero limit, or a value above 100, is served as 100. meta.limit echoes the value used. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Realm | header | string | No | Per-request realm selector: "global" or a 24-hex realm id. |
Examples
Section titled “Examples”curl --get 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/gates' \ --data-urlencode 'include_system=false' \ --data-urlencode 'realm=global' \ --data-urlencode 'page=1' \ --data-urlencode 'limit=50'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
for await (const item of client.agent.gates.listIterator({ include_system: false, agentRealm: 'global', page: 1, limit: 50})) { console.log(item);}Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
items | array | Yes | Pending gates returned on this page. |
items[].session_id | string | No | Session that owns the gate. |
items[].realm | string | No | Session realm. |
items[].gate_id | string | No | Answerable gate id. |
items[].generation | integer | No | Gateway’s gate generation. |
items[].kind | string | No | Gate kind: confirm or question. |
items[].helper_id | string | No | Helper that parked the gate. |
items[].parent_tool_call_id | string | No | Lead tool call that started the helper. |
items[].task_id | string | No | Background helper task id. |
items[].agent | string | No | Session agent. |
items[].parked_at | string | No | RFC3339 time the gateway parked the gate. |
items[].rules | object | No | Tool-call rules that asked for the gate. |
items[].gate | object | No | Daemon’s redacted gate description. |
meta | object | Yes | Pagination metadata. |
meta.total | integer | No | Number of gates parked when the list was read, across all pages. |
meta.page | integer | No | 1-based page served. |
meta.limit | integer | No | Page size used, at most 100. |
meta.omitted | integer | No | Gates that changed or resolved during the read and were left out. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "items": [ { "agent": "builder", "gate": { "gate_cause": "rules", "gate_id": 3, "generation": 0, "human_only": false, "lease_required": false, "params": { "command": "git push origin main" }, "risk": "unknown", "rules": { "outcome": "ask", "rule_ids": [ "ask-git" ] }, "status": "parked", "tool_name": "bash", "type": "confirm" }, "gate_id": "gate-9f2c4e1ab07d3355-3", "generation": 3, "kind": "confirm", "parked_at": "2026-09-28T10:15:04.512Z", "realm": "global", "rules": { "outcome": "ask", "rule_ids": [ "ask-git" ] }, "session_id": "9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55" } ], "meta": { "limit": 100, "omitted": 0, "page": 1, "total": 1 }}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
GET /api/v1/agent/sessions/{id}/approval
Section titled “GET /api/v1/agent/sessions/{id}/approval”Returns the session’s effective approval policy, including the default or always mode, monotonic lock, policy revision, waiver posture, session permission rules, and approver lease state.
The response ETag is the policy revision. Send that value as If-Match when updating the policy. event.permission_rules frames on the event stream are snapshots of the same rule set. Each frame follows a successful durable write, so clients should converge on the frame contents rather than assume that the frame acknowledges their own request.
This endpoint works for live and persisted sessions and returns Cache-Control: no-store.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Examples
Section titled “Examples”curl 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/approval' \ -H 'X-Hoody-Realm: global'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const approval = await client.agent.sessions.approval.get('9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55');console.log(approval.data);Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
mode | string | No | Effective mode: default or always. |
locked | boolean | No | Whether the policy is frozen for the session lifetime. |
revision | integer | No | Monotonic policy revision and ETag value. |
yolo | boolean | No | Whether YOLO auto-approve is armed. |
auto_write | boolean | No | Whether automatic file-write permission is on. |
auto_dir_access | boolean | No | Whether automatic directory access is on. |
backend_auto_approving | boolean | No | Whether a delegated backend auto-approves its own tools. |
rules | array | No | Session permission rules. |
rules[].tool | string | Yes | Tool name or tool:action rule key. |
rules[].decision | string | Yes | Rule decision: allow or deny. |
lease | object | No | Approver lease state. The capability itself is not returned. |
epoch | string | No | Opaque daemon execution epoch. |
changed | boolean | No | Whether an update changed anything. |
capabilities | object | No | Approval features supported by the daemon. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "mode": "default", "locked": false, "revision": 3, "yolo": false, "auto_write": false, "auto_dir_access": false, "backend_auto_approving": false, "rules": [ { "tool": "bash", "decision": "deny" } ], "lease": {}, "epoch": "epoch-7f3a", "capabilities": {}}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
GET /api/v1/agent/sessions/{id}/rules/applies
Section titled “GET /api/v1/agent/sessions/{id}/rules/applies”Returns the tool-call rules that a live session checks for one agent’s calls. The selection matches the rule checker: a rule without tools skips read-only tools, a rule with tools covers only those tools, and a rule with agents covers only those agents’ calls.
The agent parameter defaults to the session’s own agent. The tool parameter limits the checked rules to the rules sent for that call. Without tool, the response includes every checked rule that covers the agent’s calls to at least one tool. Guidance and playbook rules are also returned with applies_as: prompt, and count includes both checked and prompt rules.
A rule’s when value is a list of condition atoms. Each atom starts with + or - and names tools, for example +edit_file|write_file or -bash(command=go test):success. It is not a prose condition.
fail_closed_reason indicates when all covered calls currently fail closed. A dormant session returns 404 not_found. The response uses Cache-Control: no-store.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
agent | query | string | No | Agent to ask about. Defaults to the session’s own agent. |
tool | query | string | No | Tool to ask about. Defaults to any tool. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Examples
Section titled “Examples”curl --get 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/rules/applies' \ --data-urlencode 'agent=builder' \ --data-urlencode 'tool=bash' \ -H 'X-Hoody-Realm: global'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const applicable = await client.agent.sessions.listApplicableRules( '9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55', { agent: 'builder', tool: 'bash' });console.log(applicable.data);Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
agent | string | No | Agent whose calls were evaluated. |
tool | string | No | Tool named in the request. |
read_only | boolean | No | Whether the named tool is read-only. |
active | boolean | No | Whether the session checks any covering rules. |
count | integer | No | Number of checked and prompt rules. |
rules | array | No | Rules that apply to the agent, in settings order. |
rules[].id | string | No | Rule id. |
rules[].text | string | No | Rule in plain words. |
rules[].kind | string | No | Rule kind: limit, check_in, guidance, or playbook. |
rules[].applies_as | string | No | checked or prompt. |
rules[].tools | array | No | Tools covered by the rule. |
rules[].agents | array | No | Agents covered by the rule. |
rules[].when | array | No | Rule condition atoms. |
rules[].source | string | No | Settings file that declared the rule. |
rules[].scope | string | No | Settings scope: user, project, or local. |
rules[].folder | string | No | Folder associated with a project or local rule. |
prompt_off | boolean | No | Whether the team-rules prompt block is disabled. |
prompt_bytes | integer | No | Size of the rule lines included in the prompt. |
prompt_budget_bytes | integer | No | Maximum prompt size, 8192 bytes. |
prompt_over_budget | array | No | Covered prompt rules excluded by the byte budget. |
prompt_over_budget[].id | string | No | Rule id. |
prompt_over_budget[].text | string | No | Rule in plain words. |
prompt_over_budget[].kind | string | No | Rule kind: limit, check_in, guidance, or playbook. |
prompt_over_budget[].applies_as | string | No | checked or prompt. |
prompt_over_budget[].tools | array | No | Tools covered by the rule. |
prompt_over_budget[].agents | array | No | Agents covered by the rule. |
prompt_over_budget[].when | array | No | Rule condition atoms. |
prompt_over_budget[].source | string | No | Settings file that declared the rule. |
prompt_over_budget[].scope | string | No | Settings scope: user, project, or local. |
prompt_over_budget[].folder | string | No | Folder associated with a project or local rule. |
fail_closed_reason | string | No | trust_hold, jev_disabled, or jev_no_key when every covered call fails closed. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "agent": "builder", "tool": "bash", "read_only": false, "active": true, "count": 1, "rules": [ { "id": "ask-bash", "text": "Ask before running bash commands.", "kind": "check_in", "applies_as": "checked", "tools": [ "bash" ], "agents": [], "source": "settings.json", "scope": "project", "folder": "/workspace/project" } ], "prompt_off": false, "prompt_bytes": 41, "prompt_budget_bytes": 8192, "prompt_over_budget": []}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
Answer gates
Section titled “Answer gates”POST /api/v1/agent/sessions/{id}/answer
Section titled “POST /api/v1/agent/sessions/{id}/answer”Answers a parked question gate. Send answer or text for a free-form response, or answers for a structured multi-field question. A body with none of these values is rejected and the question stays parked.
For a workflow question with options, answer must name one option case-insensitively. text carries the input for an option that accepts user input. Any other option name is rejected with 400 bad_request, and the question remains parked.
A retry that names an already answered question with the same answer receives the original acknowledgement. A different answer receives 409 gate_already_answered and is not applied. If the turn was cancelled while the answer was in flight, the endpoint returns 409 gate_cancelled; the answer was not applied and must not be retried.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Request body
Section titled “Request body”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
gate_id | string | No | Echo of the parked gate id. A mismatch is 409 stale_gate. | |
generation | integer | No | Echo of the parked gate generation. | |
answer | string | No | Free-form answer text. If blank, text is used instead. A view frame request accepts a JSON-encoded view object. | |
text | string | No | Answer text used when answer is absent or blank. For an option with user input, this is the option’s input. | |
answers | object | No | Map of structured per-field answers. Each value is a string. |
Examples
Section titled “Examples”curl -X POST 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/answer' \ -H 'Content-Type: application/json' \ -H 'X-Hoody-Realm: global' \ --data '{ "gate_id": "gate-9f2c4e1ab07d3355-3", "generation": 3, "answer": "Use the staging environment." }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const answered = await client.agent.gates.answer( '9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55', { gate_id: 'gate-9f2c4e1ab07d3355-3', generation: 3, answer: 'Use the staging environment.' });console.log(answered.data);Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
status | string | No | "ok" on success. |
resolved | object | No | Daemon’s gate resolution. |
replayed | boolean | No | Whether the response replays an earlier acknowledgement. |
session_scope_applied | boolean | No | Whether a session-wide grant could not be applied. |
note | string | No | Explanation accompanying session_scope_applied. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "status": "ok", "resolved": { "outcome": "answered" }, "replayed": false}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "stale_gate", "message": "the gate id/generation does not match the parked gate", "details": { "gate_id": "gate-3f9a1c2b7d4e6f80-2", "generation": 2, "type": "question" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
no_pending_gate | No pending gate | No confirm or question gate is parked for this session, so there is nothing to answer. | Dispatch a turn and answer the gate it parks. Check the pending gate through GET /api/v1/agent/sessions/{id}. |
stale_gate | Stale gate | The supplied gate id or generation does not match the currently parked gate. | Answer the gate named in details, or re-read the pending gate when details is absent. |
gate_already_answered | Gate already answered | The parked gate was already answered, or it resolved with a different answer. Only an identical retry receives the original acknowledgement. | If details is present, another answer resolved the gate and this answer was not applied. Without details, retry the same answer later. |
gate_type_mismatch | Gate type mismatch | The parked gate is a different type than this endpoint answers. | Use /confirm for a confirm gate and /answer for a question gate. |
gate_cancelled | Gate cancelled | The gate resolved without consuming this answer because the turn was cancelled or the session ended. The answer was not applied. | Do not retry this answer. Re-read the session state and answer the gate parked there, if any. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the limit and split large payloads into smaller requests. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "decision_unconfirmed", "message": "the daemon did not acknowledge the decision within the wait", "details": { "gate_id": "gate-9f2c4e1ab07d3355-3", "generation": 3 }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
decision_unconfirmed | Decision unconfirmed | The decision was forwarded, but the daemon acknowledged neither consumption nor refusal within the wait. The answer may still apply. | Retry the identical decision with the original gate_id and generation. A 200 confirms that it applied. A 409 identifies whether another answer won or whether the gate ended without retaining an acknowledgement. |
POST /api/v1/agent/sessions/{id}/answer:assist
Section titled “POST /api/v1/agent/sessions/{id}/answer:assist”Runs a one-shot helper-model call that proposes answers for a parked question. The proposal is published through event.question_suggestion; it is not applied to the gate. The real answer must still be sent to POST /api/v1/agent/sessions/{id}/answer.
The endpoint returns a job id immediately. Fetch the completed result from GET /api/v1/agent/jobs/{id}/result. Only one assist job can run for a session at a time. If the session’s realm is not usable by the login, the assist is refused before it starts. A refusal discovered after the 202 fails the job with the corresponding error code.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Request body
Section titled “Request body”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
mode | string | No | "suggest" | Suggestion mode. |
model | string | No | Helper model override. An empty value uses the configured helper. | |
gen | integer | No | Generation counter echoed as event.question_suggestion.gen. |
Examples
Section titled “Examples”curl -X POST 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/answer:assist' \ -H 'Content-Type: application/json' \ -H 'X-Hoody-Realm: global' \ --data '{ "mode": "suggest", "gen": 1 }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const assist = await client.agent.gates.suggest('{session_id}', { mode: 'suggest', gen: 1 });const jobId = assist.data.job_id;Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
job_id | string | No | Gateway-minted id for the helper job. |
session_id | string | No | Session whose parked question is being answered. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "job_id": "job-7f3a2d9c", "session_id": "9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55"}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "realm_not_allowed", "message": "realm 0123456789abcdef01234567 is not allowed for this realm-limited login"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_not_allowed | Realm not allowed for this login | The login is limited to realms that do not include this session’s realm, or the session belongs to the global scope. The session can still be read, but no assist runs. | Continue in a session whose realm the login serves, or log in with a token that covers this session’s realm. |
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "assist_in_flight", "message": "an answer:assist job is already running for this session"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
no_pending_gate | No pending gate | No confirm or question gate is parked for this session, so there is nothing to assist. | Dispatch a turn and answer the gate it parks. Check the pending gate through GET /api/v1/agent/sessions/{id}. |
assist_in_flight | Assist in flight | An assist job is already running for this session. Only one in-flight assist is allowed per session. | Wait for the prior suggestion, then retry. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the limit and split large payloads into smaller requests. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it runs no work in any session until it can. | Retry after the restriction is readable. |
POST /api/v1/agent/sessions/{id}/confirm
Section titled “POST /api/v1/agent/sessions/{id}/confirm”Approves or denies a parked tool or directory confirmation. A 200 means the agent consumed this exact decision. A gate that was already answered, cancelled, timed out, auto-approved by YOLO, or ended with an earlier connection returns 409 gate_already_resolved, and the submitted decision was not applied.
A decision whose outcome is not known returns 409 gate_decision_pending. Retry the same decision with the gate id to learn its outcome. 409 no_pending_gate means nothing is parked, and 409 stale_gate means the supplied gate id or generation does not name the parked gate. A decision without gate_id is rejected when several confirm gates are parked.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
X-Hoody-Approver-Lease | header | string | No | Approver lease capability. Required on decisions for an always session after its lease has been minted. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Request body
Section titled “Request body”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
gate_id | string | No | Echo of the parked gate id. Required on an always session. | |
generation | integer | No | Echo of the parked gate generation. Required and nonzero on an always session. | |
approved | boolean | Yes | true approves the call. false denies it. | |
reason | string | No | Denial reason, at most 500 characters. Accepted only with approved: false. | |
persist_dirs | boolean | No | Persist an approved directory grant to settings.json. | |
remember | boolean | No | With approval, false applies only to this call. Omitted or true may allow later changes to the same file. | |
superseded | boolean | No | Declines the call because the user sent a new message instead of answering. | |
session_scope | boolean | No | Remembers the decision for the rest of the session. Only offer it when the gate permits a session-wide allowance. | |
trust_computer | boolean | No | Accepts the gate’s execution trust offer. | |
request_id | string | No | Caller’s decision id, at most 64 characters from A-Z, a-z, 0-9, ., _, and -. | |
lease_generation | integer | No | Approver lease generation under which the decision was made. |
Examples
Section titled “Examples”curl -X POST 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/confirm' \ -H 'Content-Type: application/json' \ -H 'X-Hoody-Realm: global' \ -H 'X-Hoody-Approver-Lease: approver-lease-capability' \ --data '{ "gate_id": "gate-9f2c4e1ab07d3355-3", "generation": 3, "approved": true, "remember": false, "request_id": "ui-7f3a" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const confirmed = await client.agent.gates.approve( '9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55', { gate_id: 'gate-9f2c4e1ab07d3355-3', generation: 3, request_id: 'ui-7f3a' });console.log(confirmed.data);client.agent.gates.approve(id, data, options?)setsapprovedtotrue.client.agent.gates.deny(id, data, options?)setsapprovedtofalse.
Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
status | string | No | "ok" on success. |
resolved | object | No | Daemon’s gate resolution that consumed the decision. |
session_scope_applied | boolean | No | Whether a session-wide grant could not be applied. |
note | string | No | Explanation accompanying session_scope_applied. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "status": "ok", "resolved": {}}Media type: application/json
{ "code": "approved_required", "message": "/confirm must carry approved: true to approve or false to deny"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
approved_required | Decision missing | The confirmation did not carry a boolean approved value. The gate stays parked. | Send approved: true to approve or approved: false to deny. |
upgrade_required | Unsupported field name | The request uses a retired field name and is refused. details.renamed lists each {from, to} pair. | Send the new name from details.renamed. Update the Hoody CLI and SDK if they still send the old name. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "gate_decision_pending", "message": "a decision for this gate is in flight and its outcome is not known yet; retry naming the gate to learn it", "details": { "gate_id": "gate-9f2c4e1ab07d3355-3", "generation": 3 }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
gate_decision_pending | Gate decision pending | A decision for this gate is in flight and its outcome is unknown. Another caller may have sent it, the agent may not have answered within the wait, or the connection may have been lost. | Retry the same decision naming the gate. |
gate_already_resolved | Gate already resolved | The gate already ended, so this decision was not applied. details.outcome identifies how it ended, and details.decision identifies a consumed decision when known. | Do not resend the decision. Read details.decision, then re-read the session state and answer any current gate. |
no_pending_gate | No pending gate | No confirm or question gate is parked for this session, so there is nothing to answer. | Dispatch a turn and answer the gate it parks. Check the pending gate through GET /api/v1/agent/sessions/{id}. |
stale_gate | Stale gate | The supplied gate id or generation does not match the currently parked gate. | Answer the gate named in details, or re-read the pending gate when details is absent. |
gate_type_mismatch | Gate type mismatch | The parked gate is a different type than this endpoint answers. | Use /confirm for a confirm gate and /answer for a question gate. |
decision_incomplete | Decision incomplete | The session uses always approval, so the decision must carry an explicit approved, the exact gate_id, and its generation. Nothing was decided. | Resend the confirmation with all three values. |
approver_lease_required | Approver lease required | The session’s approver lease has been minted, so every decision must present the current capability in X-Hoody-Approver-Lease. | Acquire the session’s approver lease and reissue the confirmation with it. |
approver_lease_invalid | Approver lease invalid | The presented capability does not verify for this session because it belongs to another session, has a fenced generation, or predates a daemon restart. | Reacquire the session’s approver lease. |
Media type: application/json
{ "code": "approver_lease_expired", "message": "the approver lease expired"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approver_lease_expired | Approver lease expired | The presented lease expired and cannot authorize a decision. | Reacquire the session’s approver lease. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the limit and split large payloads into smaller requests. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
Configure the approval policy
Section titled “Configure the approval policy”PUT /api/v1/agent/sessions/{id}/approval
Section titled “PUT /api/v1/agent/sessions/{id}/approval”Changes the session’s approval mode and lock. Send If-Match with the ETag returned by GET /api/v1/agent/sessions/{id}/approval to make the change conditional. * or an absent If-Match makes the request unconditional. An omitted body field keeps its current value.
The always mode requires an explicit decision for each side-effecting invocation, including bash, writes and deletes, non-GET web_fetch, fleet actions, non-read-only MCP tools, image generation, and notifications. memory_save, todo mutators, and propose_cron_entry remain ungated. Reads, grep, glob, and task tools are never gated.
Under always, executors that cannot park a decision are refused, including subagents, workflow runs and resumes, the orchestrator, foreign CLIs, run_todo, and test_hook. Configured hook commands are skipped and disclosed, configured MCP servers are not started, and stdin to a background bash process is refused. Machine-confirmed execution paths that perform side effects are also refused, while reads continue.
Switching to always arms the approver lease requirement but does not mint a lease. Every later decision must present an acquired lease and name the exact gate_id and generation. See Holding the right to answer a session’s gates for the approver lease.
The lock freezes the mode and all waiver aliases for the session lifetime. It is monotonic and cannot be removed. The policy can change only when the session is idle. A stale If-Match returns 412, a locked policy returns 409 approval_policy_locked, an unsupported mode returns 409 approval_policy_unsatisfiable, and a busy session returns 409 session_busy.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
If-Match | header | string | No | ETag from the approval-policy response, such as "3", or *. A mismatch is 412 precondition_failed. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Request body
Section titled “Request body”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
mode | string | No | Approval mode: default or always. Omit to keep the current mode. | |
locked | boolean | No | Freezes the policy for the session lifetime. Omit to keep the current lock. |
Examples
Section titled “Examples”curl -X PUT 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/approval' \ -H 'Content-Type: application/json' \ -H 'If-Match: "3"' \ -H 'X-Hoody-Realm: global' \ --data '{ "mode": "always", "locked": true }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const updated = await client.agent.sessions.approval.update( '9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55', { mode: 'always', locked: true }, { ifMatch: '"3"' });console.log(updated.data);Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
mode | string | No | Effective mode: default or always. |
locked | boolean | No | Whether the policy is frozen for the session lifetime. |
revision | integer | No | New monotonic policy revision and ETag value. |
yolo | boolean | No | Whether YOLO auto-approve is armed. |
auto_write | boolean | No | Whether automatic file-write permission is on. |
auto_dir_access | boolean | No | Whether automatic directory access is on. |
backend_auto_approving | boolean | No | Whether a delegated backend auto-approves its own tools. |
rules | array | No | Session permission rules. |
rules[].tool | string | Yes | Tool name or tool:action rule key. |
rules[].decision | string | Yes | Rule decision: allow or deny. |
lease | object | No | Approver lease state. The capability itself is not returned. |
epoch | string | No | Opaque daemon execution epoch. |
changed | boolean | No | Whether the request changed anything. |
capabilities | object | No | Approval features supported by the daemon. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "mode": "always", "locked": true, "revision": 4, "yolo": false, "auto_write": false, "auto_dir_access": false, "backend_auto_approving": false, "rules": [ { "tool": "bash", "decision": "deny" } ], "lease": {}, "epoch": "epoch-7f3a", "changed": true, "capabilities": {}}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "approval_policy_locked", "message": "the approval policy is locked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approval_policy_locked | Approval policy locked | The session’s approval policy is locked for its lifetime. Its mode, lock, allow rules, session-scoped remembered approvals, and automatic-reply arming cannot be changed, and YOLO cannot be armed. Turning YOLO off remains allowed. | Create a new session with the required posture. A locked policy is never unlocked. |
approval_policy_unsatisfiable | Approval policy unsatisfiable | The requested mode is unknown, or always is unsupported by this session. | Send default or always. If always is unsupported, use a session that supports it. |
session_busy | Session busy | The session has a turn in flight, queued turns, a parked gate, background children, or running interactive shells. The policy only changes at quiescence. | Wait for the session to become idle, then retry. |
Media type: application/json
{ "code": "precondition_failed", "message": "the approval policy revision changed; refetch and retry with the current ETag", "details": { "revision": 4 }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
precondition_failed | Precondition failed | If-Match named a policy revision that is no longer current. The response ETag carries the current revision, also under details.revision. | Refetch the approval policy and retry with the current ETag. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the limit and split large payloads into smaller requests. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "policy_commit_failed", "message": "the approval policy could not be persisted; nothing was acknowledged"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
policy_commit_failed | Policy commit failed | The daemon could not durably write the policy, so the change was not acknowledged. | Retry. If the problem persists, check the daemon’s session store and permissions. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
PUT /api/v1/agent/sessions/{id}/approval/rules/{tool}
Section titled “PUT /api/v1/agent/sessions/{id}/approval/rules/{tool}”Upserts one session permission rule for tool. Send one object, not an array. A deny rule is always accepted. An allow rule is refused with 409 approval_policy_locked on a locked policy and 409 approval_policy_active under always, because allow rules are not consulted there.
Send If-Match with the current policy ETag to make the change conditional. A stale value returns 412 and the response carries the current ETag. Successful writes emit event.permission_rules and event.approval_policy_changed.
The write is durable or nothing. If the durable write fails, the rule is rolled back and no policy events are broadcast. Every event.permission_rules frame therefore carries persisted rules. The frame remains a snapshot to converge on, not proof that the request that produced it succeeded.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
tool | path | string | Yes | Tool whose permission rule is being set. |
If-Match | header | string | No | ETag from the approval-policy response, such as "3", or *. A mismatch is 412 precondition_failed. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Request body
Section titled “Request body”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
decision | string | Yes | Permission decision: allow or deny. |
Examples
Section titled “Examples”curl -X PUT 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/approval/rules/bash' \ -H 'Content-Type: application/json' \ -H 'If-Match: "3"' \ -H 'X-Hoody-Realm: global' \ --data '{ "decision": "deny" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const rules = await client.agent.sessions.approval.setRule( '9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55', 'bash', { decision: 'deny' }, { ifMatch: '"3"' });console.log(rules.data);Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
status | string | No | "ok" on success. |
rules | array | No | Full session permission-rule set after the change. |
rules[].tool | string | Yes | Tool name or tool:action rule key. |
rules[].decision | string | Yes | Rule decision: allow or deny. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "status": "ok", "rules": [ { "tool": "bash", "decision": "deny" } ]}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "approval_policy_locked", "message": "the approval policy is locked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approval_policy_locked | Approval policy locked | The session’s approval policy is locked for its lifetime. Its mode, lock, allow rules, session-scoped remembered approvals, and automatic-reply arming cannot be changed, and YOLO cannot be armed. Turning YOLO off remains allowed. | Create a new session with the required posture. A locked policy is never unlocked. |
approval_policy_active | Approval policy active | The session requires an explicit decision on every action, so an allow rule is refused because allow rules are not consulted. | Answer each gate through POST /api/v1/agent/sessions/{id}/confirm, or change the policy first if it is not locked. |
Media type: application/json
{ "code": "precondition_failed", "message": "the approval policy revision changed; refetch and retry with the current ETag", "details": { "revision": 4 }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
precondition_failed | Precondition failed | If-Match named a policy revision that is no longer current. The response ETag carries the current revision, also under details.revision. | Refetch the approval policy and retry with the current ETag. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the limit and split large payloads into smaller requests. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "policy_commit_failed", "message": "the approval policy could not be persisted; nothing was acknowledged"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
policy_commit_failed | Policy commit failed | The daemon could not durably write the policy, so the change was not acknowledged. | Retry. If the problem persists, check the daemon’s session store and permissions. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
PATCH /api/v1/agent/sessions/{id}/yolo
Section titled “PATCH /api/v1/agent/sessions/{id}/yolo”Turns the session’s YOLO auto-approve state on or off. This is the same capability as the TUI’s YOLO toggle. A caller that can reach this endpoint is treated as having permission to perform the requested change.
Arming YOLO is refused with 409 approval_policy_locked on a locked policy and 409 approval_policy_active under always. Disarming YOLO remains permitted under either policy. The response contains the applied yolo state, and the change emits event.yolo_mode.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Request body
Section titled “Request body”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | boolean | Yes | true arms auto-approve. false disarms it. |
Examples
Section titled “Examples”curl -X PATCH 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/yolo' \ -H 'Content-Type: application/json' \ -H 'X-Hoody-Realm: global' \ --data '{ "enabled": true }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const yolo = await client.agent.sessions.disableYolo( '9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55', {});console.log(yolo.data);client.agent.sessions.disableYolo(id, data, options?)setsenabledtofalse.client.agent.sessions.enableYolo(id, data, options?)setsenabledtotrue.
Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
status | string | No | "ok" on success. |
yolo | boolean | No | Applied auto-approve state. |
forwarded | boolean | No | Whether the command was delivered without an acknowledgement within the wait. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "status": "ok", "yolo": false, "forwarded": false}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "approval_policy_active", "message": "this session requires approval on every action; auto_approve is refused"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approval_policy_locked | Approval policy locked | The session’s approval policy is locked for its lifetime. Its mode, lock, allow rules, session-scoped remembered approvals, and automatic-reply arming cannot be changed, and YOLO cannot be armed. Turning YOLO off remains allowed. | Create a new session with the required posture. A locked policy is never unlocked. |
approval_policy_active | Approval policy active | The session requires an explicit decision on every action, so arming YOLO is refused. | Answer each gate through POST /api/v1/agent/sessions/{id}/confirm, or change the policy first if it is not locked. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the limit and split large payloads into smaller requests. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
DELETE /api/v1/agent/sessions/{id}/approval/rules/{tool}
Section titled “DELETE /api/v1/agent/sessions/{id}/approval/rules/{tool}”Clears the session permission rule for tool, restoring the per-call prompt for that tool. The operation is refused with 409 approval_policy_locked when the policy is locked.
Send If-Match with the current policy ETag to make the removal conditional. A stale value returns 412 and the response carries the current ETag. Successful writes emit event.permission_rules and event.approval_policy_changed.
The write is durable or nothing. If the durable write fails, the removal is rolled back and no policy events are broadcast. Every event.permission_rules frame therefore carries persisted rules. The frame remains a snapshot to converge on, not proof that the request that produced it succeeded.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Session id. |
tool | path | string | Yes | Tool whose permission rule is being removed. |
If-Match | header | string | No | ETag from the approval-policy response, such as "3", or *. A mismatch is 412 precondition_failed. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. The value must be valid UTF-8. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. The value must be valid UTF-8. |
X-Hoody-Computer | header | string | No | Bound remote computer. Omit for the local computer. |
X-Hoody-Realm | header | string | No | Session realm selector: "global" or a 24-hex realm id. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. "all" is not accepted. |
Examples
Section titled “Examples”curl -X DELETE 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55/approval/rules/bash' \ -H 'If-Match: "3"' \ -H 'X-Hoody-Realm: global'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const rules = await client.agent.sessions.approval.deleteRule( '9f2c4e1a-5b7d-4c3e-8a21-6d0f3b9e7c55', 'bash', { ifMatch: '"3"' });console.log(rules.data);Response fields
Section titled “Response fields”| Field | Type | Required | Description |
|---|---|---|---|
status | string | No | "ok" on success. |
rules | array | No | Full session permission-rule set after the removal. |
rules[].tool | string | Yes | Tool name or tool:action rule key. |
rules[].decision | string | Yes | Rule decision: allow or deny. |
Error responses use code and message, with an optional details object.
Responses
Section titled “Responses”Media type: application/json
{ "status": "ok", "rules": []}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "global" or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "approval_policy_locked", "message": "the approval policy is locked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approval_policy_locked | Approval policy locked | The session’s approval policy is locked for its lifetime. Its mode, lock, allow rules, session-scoped remembered approvals, and automatic-reply arming cannot be changed, and YOLO cannot be armed. Turning YOLO off remains allowed. | Create a new session with the required posture. A locked policy is never unlocked. |
Media type: application/json
{ "code": "precondition_failed", "message": "the approval policy revision changed; refetch and retry with the current ETag", "details": { "revision": 4 }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
precondition_failed | Precondition failed | If-Match named a policy revision that is no longer current. The response ETag carries the current revision, also under details.revision. | Refetch the approval policy and retry with the current ETag. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the problem persists, inspect the daemon logs. |
Media type: application/json
{ "code": "policy_commit_failed", "message": "the approval policy could not be persisted; nothing was acknowledged"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
policy_commit_failed | Policy commit failed | The daemon could not durably write the policy, so the change was not acknowledged. | Retry. If the problem persists, check the daemon’s session store and permissions. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |