Agent: Sessions

Download Page (.md)

Sessions are the persistent containers for Hoody’s LLM-driven workflows. Each session holds a conversation history, a frozen start binding (realm, container, cwd, tool mode, dir scope, backend), and an attached event stream. This page covers every operation on a session: discovery, lifecycle, turn dispatch, gate handling, live configuration, and per-session workflow input. Use these endpoints to wire a UI or backend service into the Hoody agent.

Discovery

`GET /api/v1/agent/sessions`

List persisted sessions for the requesting cwd (open and closed), with an Attached flag for live sessions. Pagination is honored via ?page=N&limit=M; omit limit to receive the full set.

SDK: client.agent.sessions.listSessionsIterator()

Parameters

Name	In	Type	Required	Description
`include_system`	query	boolean	No	When true, also include daemon-owned system/resident sessions in the listing.
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Responses

{
  "items": [
    {
      "id": "5f9a8b2c3d4e5f6a7b8c9d0e",
      "title": "Refactor auth middleware",
      "model": "claude-opus-4-6",
      "agent": "build",
      "cwd": "/home/user/projects/api",
      "attached": true,
      "created_at": "2025-01-15T10:23:45Z",
      "updated_at": "2025-01-15T10:42:11Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy: its source IP is private/local. Authorization is owned by hoody-proxy.	Reach the agent through hoody-proxy (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "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.

{
  "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 persistent, inspect the daemon logs.

const iterator = await client.agent.sessions.listSessionsIterator({
  includeSystem: false,
  page: 1,
  limit: 20
});

`GET /api/v1/agent/sessions/{id}`

Return the persisted summary for a session (live or closed). A live session also surfaces its frozen start binding (realm, container, modes) and attached: true.

SDK: client.agent.sessions.getSession()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Responses

{
  "id": "5f9a8b2c3d4e5f6a7b8c9d0e",
  "title": "Refactor auth middleware",
  "model": "claude-opus-4-6",
  "agent": "build",
  "tool_mode": "code",
  "dir_scope": "home",
  "cwd": "/home/user/projects/api",
  "attached": true,
  "pending_gate": null,
  "created_at": "2025-01-15T10:23:45Z",
  "updated_at": "2025-01-15T10:42:11Z"
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

const session = await client.agent.sessions.getSession({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e"
});

`GET /api/v1/agent/sessions/{id}/replay`

Return the gateway’s buffered event tail for a LIVE session (the daemon’s full viewport snapshot already streamed into the replay ring), with min_seq/max_seq for resume. For a non-live session, attach to receive the daemon’s event.replay.

SDK: client.agent.sessions.replaySession()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Responses

{
  "events": [
    {
      "seq": 12,
      "type": "agent_text",
      "data": {
        "text": "I'll start by reading the auth middleware file."
      }
    },
    {
      "seq": 13,
      "type": "agent_tool_call",
      "data": {
        "name": "read_file",
        "args": { "path": "/src/auth/middleware.ts" }
      }
    }
  ],
  "min_seq": 1,
  "max_seq": 13
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor Retry-After and retry.

const replay = await client.agent.sessions.replaySession({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e"
});

`GET /api/v1/agent/sessions/{id}/stream`

WebSocket (primary) or SSE attach to a live session’s full event.* taxonomy. Events carry a gateway-stamped monotonic int64 seq; ?since=<seq> / Last-Event-ID resume from the 1024-event replay ring. A slow client is dropped lagged and never backpressures the daemon. WS clients may post inline answer frames (confirm/answer/cancel/workflow_message).

SDK: client.agent.sessions.streamSession()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`since`	query	integer	No	Resume from this gateway int64 seq (also accepted as the `Last-Event-ID` header).
`Last-Event-ID`	header	string	No	SSE resume cursor — the gateway int64 seq to resume from; sent automatically by an SSE client on reconnect.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Responses

WebSocket upgrade accepted (WS transport). No body; the connection switches to the WS frame protocol.

Event stream (SSE transport):

event: agent_text
id: 14
data: {"text":"Reading the auth middleware file..."}

event: agent_tool_call
id: 15
data: {"name":"read_file","args":{"path":"/src/auth/middleware.ts"}}

{
  "code": "realm_scope_unsupported",
  "message": "realm scope not supported on this route"
}

Error Code	Title	Description	Resolution
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm/container header contradicts the session’s frozen binding.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

const stream = await client.agent.sessions.streamSession({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  since: 13
});

`GET /api/v1/agent/sessions/cwds`

Return the distinct working directories across all persisted sessions, most-recent first.

SDK: client.agent.sessions.listSessionCwds()

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Responses

{
  "cwds": [
    "/home/user/projects/api",
    "/home/user/projects/web",
    "/home/user/notes"
  ]
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

const cwds = await client.agent.sessions.listSessionCwds();

Lifecycle

`POST /api/v1/agent/sessions`

Open a new agent session (or fork/attach an existing one), freezing realm/container/cwd/tool_mode/dir_scope/backend at start. BYOA: backend:"acp" + delegated_agent delegates the session to an external CLI agent.

SDK: client.agent.sessions.createSession()

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`realm`	string	No	Realm selector to scope the session (frozen at start).
`container`	string	No	Container id/selector to run tools on (frozen at start).
`cwd`	string	No	Working directory for the session (frozen at start).
`config_dir`	string	No	Config directory override.
`model`	string	No	Initial model id.
`agent`	string	No	Initial chat-agent name.
`tool_mode`	string	No	Initial tool mode (frozen at start).
`dir_scope`	string	No	Initial directory-access scope: `home`\|`full` (frozen at start).
`attach`	string	No	`attach_session_id` — attach to an existing session instead of creating one.
`fork`	string	No	`fork_session_id` — fork from an existing session.
`fork_turn_idx`	integer	No	Turn index to fork at (with `fork`).
`backend`	string	No	Session backend: `""` (Hoody LLM) or `acp` (BYOA delegated agent).
`delegated_agent`	string	No	BYOA agent when `backend:"acp"`: `codex`\|`claude`\|`gemini`\|`opencode`.
`headless`	boolean	No	Start the session in headless posture.

Responses

{
  "id": "5f9a8b2c3d4e5f6a7b8c9d0e",
  "attached": true,
  "model": "claude-opus-4-6",
  "agent": "build",
  "cwd": "/home/user/projects/api",
  "tool_mode": "code",
  "dir_scope": "home",
  "backend": ""
}

{
  "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_blocked`	Realm blocked	The requested realm is blocked or corrupt; the request fails closed before dispatch.	Select a valid, reachable realm.
`realm_corrupt`	Realm record corrupt	The attach target’s persisted realm binding is corrupt; the session cannot be re-bound and the request fails closed.	Recreate the session in a valid realm.
`realm_conflict`	Realm conflict	The supplied realm conflicts with the parent’s (fork) or the session’s frozen (attach) realm binding.	Omit the realm header to inherit, or match the existing binding.
`invalid_realm`	Invalid realm selector	The realm selector is malformed (not `""`/`"global"`/a 24-hex id).	Pass a valid realm selector.
`container_conflict`	Container conflict	The supplied container conflicts with the parent’s (fork) or the session’s frozen (attach) container binding.	Omit the container header to inherit, or match the existing binding.
`delegated_agent_invalid`	Delegated agent invalid	The `delegated_agent` value (for `backend:"acp"`) is not a known BYOA backend.	Use one of `codex` \| `claude` \| `gemini` \| `opencode`.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "code": "session_busy",
  "message": "session is already live in another connection"
}

Error Code	Title	Description	Resolution
`session_busy`	Session busy	The session is already live in another connection (single-writer-per-session).	Close the other attach, or attach a fork instead.
`session_not_attachable`	Session not attachable	The attach target is a daemon-managed session (e.g. a todo worker) and cannot be attached over HTTP.	Attach a user session, or fork the target instead of attaching it.

{
  "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 configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "cwd_not_found",
  "message": "working directory does not exist"
}

Error Code	Title	Description	Resolution
`cwd_not_found`	Working directory not found	The requested working directory does not exist on the daemon host.	Create the directory or pass an existing cwd.
`container_gone`	Bound container no longer exists	The session’s frozen REMOTE container no longer exists in its realm.	Start a new session and pick another container (or this computer).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

const session = await client.agent.sessions.createSession({
  data: {
    realm: "global",
    cwd: "/home/user/projects/api",
    model: "claude-opus-4-6",
    agent: "build",
    tool_mode: "code",
    dir_scope: "home"
  }
});

`POST /api/v1/agent/sessions/{id}/close`

Tear the session down (the daemon cancels it and removes it from the live map).

SDK: client.agent.sessions.closeSession()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

This endpoint takes no parameters beyond the path and headers.

Responses

{
  "id": "5f9a8b2c3d4e5f6a7b8c9d0e",
  "closed": true
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.closeSession({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e"
});

`POST /api/v1/agent/sessions/{id}/cancel`

Stop the active turn at the server layer; spares the session and background tasks (distinct from close). Also aborts an in-flight in-session direct tool run (e.g. POST /sessions/{id}/tools/{name}:run) — it holds the same serial turn slot.

SDK: client.agent.sessions.cancelSession()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

This endpoint takes no parameters beyond the path and headers.

Responses

{
  "id": "5f9a8b2c3d4e5f6a7b8c9d0e",
  "cancelled": true
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.cancelSession({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e"
});

`DELETE /api/v1/agent/sessions/{id}`

Close the live session connection (the daemon cancels the session). ?hard=true also removes the persisted record. A hard delete resolves the persisted record under the request’s X-Hoody-Config-Dir header (not a body field) — to hard-delete a session that was CREATED with a body config_dir override, send the same directory as X-Hoody-Config-Dir, otherwise the delete resolves the home sessions dir, finds nothing, and returns 404.

SDK: client.agent.sessions.deleteSession()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`hard`	query	boolean	No	When true, also remove the persisted session record (not just the live connection).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

This endpoint takes no request body.

Responses

{
  "id": "5f9a8b2c3d4e5f6a7b8c9d0e",
  "closed": true,
  "hard": true
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.
`invalid_realm`	Invalid realm selector	The realm selector is malformed (not `""`/`"global"`/a 24-hex id).	Pass a valid realm selector.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.deleteSession({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  hard: true
});

Turn Dispatch

`POST /api/v1/agent/sessions/{id}/messages`

Dispatch a user turn and return {job_id}; observe agent_done on the session’s stream. Refuses a new turn when the session already has a parked gate (409 gate_parked, the parked gate under details.pending_gate) or a turn is already running (409 turn_in_flight) — single-writer, no duplicate parked turns.

SDK: client.agent.sessions.postSessionMessage()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`text`	string	No	The user message text for this turn.
`tool_mode`	string	No	Optional per-turn tool mode override.
`dir_scope`	string	No	Optional per-turn directory-access scope override: `home`\|`full`.

Responses

{
  "job_id": "job-7c4f2a1b9d3e8f5c",
  "session_id": "5f9a8b2c3d4e5f6a7b8c9d0e"
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "code": "gate_parked",
  "message": "a gate is parked on this session",
  "details": {
    "pending_gate": {
      "generation": 3,
      "id": "gate-3",
      "type": "confirm"
    }
  }
}

Error Code	Title	Description	Resolution
`gate_parked`	Gate parked	A confirm/question gate is parked on this session, so a new turn/workflow run is refused until it is answered. The parked gate is surfaced under `details.pending_gate`.	Answer the parked gate (`/confirm` or `/answer`) and retry; read it via `GET /sessions/{id}` or `details.pending_gate`.
`turn_in_flight`	Turn in flight	A turn is already running on this session; the single serial turn slot is occupied, so a new turn/workflow run is refused.	Wait for the running turn to finish (observe `agent_done` on the session stream), then retry.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

const { jobId } = await client.agent.sessions.postSessionMessage({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: {
    text: "Refactor the auth middleware to use async/await."
  }
});

`POST /api/v1/agent/sessions/{id}/prompt:stream`

Dispatch a turn and stream the resulting events over SSE from the seq captured just before the dispatch — only this turn’s events, not the whole retained ring. The explicit X-Hoody-Gate-Policy: auto_approve header (or ?policy=auto_approve) auto-answers confirm gates with approved=true for the life of the stream — off by default.

SDK: client.agent.sessions.promptStream()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`policy`	query	string	No	`auto_approve` auto-answers confirm gates for the life of the stream (alias of the `X-Hoody-Gate-Policy` header); off by default.
`X-Hoody-Gate-Policy`	header	string	No	Confirm-gate posture (§6): `auto_approve` adopts the headless auto-answer posture (off by default; the in-query alias is `?policy=`). Any other value is rejected 400.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`text`	string	No	The user message text for this turn.
`tool_mode`	string	No	Optional per-turn tool mode override.
`dir_scope`	string	No	Optional per-turn directory-access scope override: `home`\|`full`.

Responses

Event stream (SSE):

event: agent_text
id: 14
data: {"text":"Reading the auth middleware file..."}

event: agent_tool_call
id: 15
data: {"name":"read_file","args":{"path":"/src/auth/middleware.ts"}}

event: agent_done
id: 16
data: {"status":"done"}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "code": "gate_parked",
  "message": "a gate is parked on this session",
  "details": {
    "pending_gate": {
      "generation": 3,
      "id": "gate-3",
      "type": "confirm"
    }
  }
}

Error Code	Title	Description	Resolution
`gate_parked`	Gate parked	A confirm/question gate is parked on this session, so a new turn/workflow run is refused until it is answered. The parked gate is surfaced under `details.pending_gate`.	Answer the parked gate (`/confirm` or `/answer`) and retry; read it via `GET /sessions/{id}` or `details.pending_gate`.
`turn_in_flight`	Turn in flight	A turn is already running on this session; the single serial turn slot is occupied, so a new turn/workflow run is refused.	Wait for the running turn to finish (observe `agent_done` on the session stream), then retry.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	Pre-stream dispatch failure (transport error before SSE opens).	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

const stream = await client.agent.sessions.promptStream({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  policy: "auto_approve",
  data: {
    text: "Refactor the auth middleware to use async/await."
  }
});

`POST /api/v1/agent/sessions/{id}/prompt:sync`

Dispatch a turn and block until agent_done. By default (interactive posture) it returns {pending_gate} the moment a turn parks — it never auto-approves implicitly. Repeated prompt:sync against a parked session returns the same pending_gate (no duplicate parked turns). The explicit X-Hoody-Gate-Policy: auto_approve header (or ?policy=auto_approve) adopts the headless posture and auto-answers confirm gates with approved=true — off by default.

SDK: client.agent.sessions.promptSync()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`policy`	query	string	No	`auto_approve` adopts the headless auto-answer posture (alias of the `X-Hoody-Gate-Policy` header); off by default.
`X-Hoody-Gate-Policy`	header	string	No	Confirm-gate posture (§6): `auto_approve` adopts the headless auto-answer posture (off by default; the in-query alias is `?policy=`). Any other value is rejected 400.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`text`	string	No	The user message text for this turn.
`tool_mode`	string	No	Optional per-turn tool mode override.
`dir_scope`	string	No	Optional per-turn directory-access scope override: `home`\|`full`.

Responses

{
  "status": "done",
  "text": "I refactored the auth middleware. All 12 tests pass.",
  "usage": {
    "input_tokens": 4521,
    "output_tokens": 312
  }
}

A pending_gate is returned the moment a turn parks (interactive posture), status:"error" when the turn surfaced a fatal error, status:"canceled" when a concurrent /cancel (or WS cancel frame) stopped the turn, or status:"quit" on /exit.

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "code": "turn_in_flight",
  "message": "a turn is already running on this session"
}

Error Code	Title	Description	Resolution
`turn_in_flight`	Turn in flight	A turn is already running on this session; the single serial turn slot is occupied, so a new turn/workflow run is refused.	Wait for the running turn to finish (observe `agent_done` on the session stream), then retry.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

const result = await client.agent.sessions.promptSync({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: {
    text: "Refactor the auth middleware to use async/await."
  }
});

Gate Handling

`POST /api/v1/agent/sessions/{id}/confirm`

Approve or deny a parked tool/dir confirmation. 409 no_pending_gate when nothing is parked; 409 stale_gate / gate_already_answered on mismatch — the gateway never fires a command that would be silently dropped.

SDK: client.agent.sessions.confirmGate()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`gate_id`	string	No	Optional echo of the parked gate id (stale/mismatch → 409).
`generation`	integer	No	Optional echo of the parked gate generation.
`approved`	boolean	No	`true` to approve, `false` to deny (defaults to `true` if omitted).
`persist_dirs`	boolean	No	Persist an approved directory grant to `settings.json` (WS↔REST parity).

Responses

{
  "gate_id": "gate-3",
  "generation": 3,
  "approved": true
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "code": "no_pending_gate",
  "message": "no gate is parked for this session"
}

Error Code	Title	Description	Resolution
`no_pending_gate`	No pending gate	No confirm/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 via `GET /sessions/{id}`.
`stale_gate`	Stale gate	The supplied `gate_id`/`generation` does not match the currently parked gate.	Re-read the pending gate and answer the current id/generation.
`gate_already_answered`	Gate already answered	The parked gate was already answered by an earlier request (first valid answer wins).	Wait for the next gate; do not re-answer.
`gate_type_mismatch`	Gate type mismatch	The parked gate is a different type than this endpoint answers (e.g. answering a question gate via `/confirm`).	Use the endpoint matching the parked gate type (`/confirm` for a confirm gate, `/answer` for a question gate).

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

await client.agent.sessions.confirmGate({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: {
    gate_id: "gate-3",
    generation: 3,
    approved: true,
    persist_dirs: true
  }
});

`POST /api/v1/agent/sessions/{id}/answer`

Answer a parked ask-the-user question. 409 no_pending_gate / stale_gate / gate_already_answered / gate_type_mismatch on mismatch.

SDK: client.agent.sessions.answerQuestion()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`gate_id`	string	No	Optional echo of the parked gate id (stale/mismatch → 409).
`generation`	integer	No	Optional echo of the parked gate generation.
`answer`	string	No	Free-form answer text.
`text`	string	No	Alternate answer text field (forwarded alongside `answer`).
`answers`	object	No	Structured per-field answers for a multi-field question.

Responses

{
  "gate_id": "gate-4",
  "generation": 4,
  "answered": true
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "code": "no_pending_gate",
  "message": "no gate is parked for this session"
}

Error Code	Title	Description	Resolution
`no_pending_gate`	No pending gate	No confirm/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 via `GET /sessions/{id}`.
`stale_gate`	Stale gate	The supplied `gate_id`/`generation` does not match the currently parked gate.	Re-read the pending gate and answer the current id/generation.
`gate_already_answered`	Gate already answered	The parked gate was already answered by an earlier request (first valid answer wins).	Wait for the next gate; do not re-answer.
`gate_type_mismatch`	Gate type mismatch	The parked gate is a different type than this endpoint answers (e.g. answering a question gate via `/confirm`).	Use the endpoint matching the parked gate type (`/confirm` for a confirm gate, `/answer` for a question gate).

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

await client.agent.sessions.answerQuestion({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: {
    gate_id: "gate-4",
    generation: 4,
    answer: "Use PostgreSQL with a connection pool of 10."
  }
});

`POST /api/v1/agent/sessions/{id}/answer:assist`

Run a one-shot helper-model call that proposes answers for the parked question (event.question_suggestion). The real answer still travels via /answer — the daemon never answers itself. 409 no_pending_gate when no question is parked.

SDK: client.agent.sessions.answerAssist()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`mode`	string	No	Suggestion mode (default `suggest`).
`model`	string	No	Helper model override; empty uses the configured helper.
`gen`	integer	No	Generation counter to correlate the suggestion event.

Responses

{
  "job_id": "job-assist-9a1b2c3d",
  "session_id": "5f9a8b2c3d4e5f6a7b8c9d0e"
}

Suggestion job dispatched; observe its result via GET /jobs/{id}/result.

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "code": "no_pending_gate",
  "message": "no gate is parked for this session"
}

Error Code	Title	Description	Resolution
`no_pending_gate`	No pending gate	No confirm/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 via `GET /sessions/{id}`.
`assist_in_flight`	Assist in flight	An `answer:assist` suggestion job is already running for this session; only one in-flight assist per session is allowed.	Wait for the prior suggestion (observe `event.question_suggestion` / poll the job), then retry.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

const { jobId } = await client.agent.sessions.answerAssist({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { mode: "suggest" }
});

Session Configuration

`PATCH /api/v1/agent/sessions/{id}/model`

Live model switch (echoed as an event).

SDK: client.agent.sessions.setSessionModel()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`model`	string	No	Model id to switch to.

Responses

{
  "model": "claude-opus-4-6"
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.setSessionModel({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { model: "claude-opus-4-6" }
});

`PATCH /api/v1/agent/sessions/{id}/effort`

Live reasoning-effort change (low|medium|high|xhigh, or "" for the model default).

SDK: client.agent.sessions.setSessionEffort()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`effort`	string	No	`low`\|`medium`\|`high`\|`xhigh`, or `""` for the model default.

Responses

{
  "effort": "high"
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.setSessionEffort({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { effort: "high" }
});

`PATCH /api/v1/agent/sessions/{id}/verbosity`

Live verbosity change (normal|concise|terse|minimal).

SDK: client.agent.sessions.setSessionVerbosity()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`level`	string	No	`normal`\|`concise`\|`terse`\|`minimal`.

Responses

{
  "level": "concise"
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.setSessionVerbosity({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { level: "concise" }
});

`PATCH /api/v1/agent/sessions/{id}/agent`

Live chat-agent switch (echoed as an event).

SDK: client.agent.sessions.setSessionAgent()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`agent`	string	No	Chat-agent name to switch to.

Responses

{
  "agent": "build"
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.setSessionAgent({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { agent: "build" }
});

`PATCH /api/v1/agent/sessions/{id}/auto-reply`

Arm or disarm the self-driving auto-reply loop (rounds, replier model, write opt-in).

SDK: client.agent.sessions.setSessionAutoReply()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`armed`	boolean	No	`true` to arm the auto-reply loop, `false` to disarm.
`rounds`	integer	No	Number of auto-reply rounds budgeted.
`model`	string	No	Replier model override.
`allow_writes`	boolean	No	Opt in to write-class actions during auto-reply.

Responses

{
  "armed": true,
  "rounds": 5,
  "allow_writes": false
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.setSessionAutoReply({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { armed: true, rounds: 5, allow_writes: false }
});

`PATCH /api/v1/agent/sessions/{id}/auto-reply/writes`

Flip the write-class opt-in on an already-armed auto-reply loop WITHOUT re-arming (no budget reset).

SDK: client.agent.sessions.setSessionAutoReplyWrites()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`allow_writes`	boolean	No	New write-class opt-in state.

Responses

{
  "allow_writes": true
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.setSessionAutoReplyWrites({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { allow_writes: true }
});

`PATCH /api/v1/agent/sessions/{id}/hoody-env`

Live toggle of the session’s HOODY_* shell-env contract for the bash tool.

SDK: client.agent.sessions.setSessionHoodyEnv()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`enabled`	boolean	No	Whether to inject the `HOODY_*` shell-env contract.

Responses

{
  "enabled": true
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.setSessionHoodyEnv({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { enabled: true }
});

Workflow & History

`POST /api/v1/agent/sessions/{id}/trim`

Truncate the session’s conversation history to (and including) the given turn index.

SDK: client.agent.sessions.trimSession()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`turn_idx`	integer	No	Turn index to truncate history to (and including).

Responses

{
  "trimmed_to": 4,
  "remaining_turns": 5
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.trimSession({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { turn_idx: 4 }
});

`POST /api/v1/agent/sessions/{id}/workflow/messages`

Inject user feedback/input into a running workflow (maps to session.workflow_message → workflowMsgChan, not commandChan).

SDK: client.agent.sessions.postWorkflowMessage()

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`text`	string	No	Feedback/input text fed to the running workflow.

Responses

{
  "delivered": true
}

{
  "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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "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.

{
  "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 configured size cap.	Reduce the request body below the configured limit (default 8 MiB).

{
  "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.	Honor the Retry-After header and retry; reduce the request rate.

{
  "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 persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor Retry-After and retry.

await client.agent.sessions.postWorkflowMessage({
  id: "5f9a8b2c3d4e5f6a7b8c9d0e",
  data: { text: "Skip the file upload step." }
});