Agent: Tasks

The Tasks endpoints inspect and manage background subagent tasks on a live agent session. Use these routes to ask a session to emit its task snapshot, request a task’s transcript from an upsert-poll cursor, or cancel one or all background tasks. All routes are request-response RPCs that forward an action to the daemon and return a plain JSON ack — task snapshots and transcripts arrive on the session’s WS/SSE stream, not in the HTTP response body. Background tasks survive session.cancel but are not restartable.

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

Request the session’s task snapshot. The daemon has no synchronous task-list response, so the snapshot (a tasks_snapshot event) is emitted on the session’s WS/SSE stream.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST `/todos`; `createTodo` also accepts a body cwd).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves (HoodyPaths).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent): `"global"` or a 24-hex id. Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.

curl -X GET "https://proj-c1-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/sessions/sess_01HZX3F4K7P8QCJR2VA9NMDYBW/tasks" \
  -H "X-Hoody-Container: c1"

await client.agent.tasks.listTasks("sess_01HZX3F4K7P8QCJR2VA9NMDYBW");

{
  "ok": true,
  "sessionId": "sess_01HZX3F4K7P8QCJR2VA9NMDYBW",
  "snapshotPending": 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, 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)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. `hoody agent …` → platform → 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; 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.

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

`GET /api/v1/agent/sessions/{id}/tasks/{tid}/transcript`

Request a task’s transcript from an after_seq upsert-poll cursor. The endpoint returns a plain JSON ack; the transcript arrives on the session’s stream as a task_transcript event. after_seq is an int64 UPSERT-POLL cursor (the open entry is re-sent at/below after_seq) — distinct from the gateway’s int64 stream seq and the daemon’s uint64 log seq; it is NOT a monotonic replay cursor.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`tid`	path	string	Yes	Path identifier.
`after_seq`	query	integer	No	int64 upsert-poll cursor; entries at/below it are re-sent (default 0).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST `/todos`; `createTodo` also accepts a body cwd).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves (HoodyPaths).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent): `"global"` or a 24-hex id. Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.

curl -X GET "https://proj-c1-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/sessions/sess_01HZX3F4K7P8QCJR2VA9NMDYBW/tasks/tsk_01HZX3F4NA7XQ9B5YC8VP6JKMT/transcript?after_seq=42" \
  -H "X-Hoody-Container: c1"

await client.agent.tasks.requestTaskTranscript(
  "sess_01HZX3F4K7P8QCJR2VA9NMDYBW",
  "tsk_01HZX3F4NA7XQ9B5YC8VP6JKMT",
  { after_seq: 42 }
);

{
  "ok": true,
  "sessionId": "sess_01HZX3F4K7P8QCJR2VA9NMDYBW",
  "taskId": "tsk_01HZX3F4NA7XQ9B5YC8VP6JKMT",
  "afterSeq": 42
}

{
  "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)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. `hoody agent …` → platform → 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; 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.

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

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

Cancel a single background subagent task on a live session. The request is handled at the server layer so it works mid-turn.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`tid`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST `/todos`; `createTodo` also accepts a body cwd).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves (HoodyPaths).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent): `"global"` or a 24-hex id. Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.

curl -X POST "https://proj-c1-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/sessions/sess_01HZX3F4K7P8QCJR2VA9NMDYBW/tasks/tsk_01HZX3F4NA7XQ9B5YC8VP6JKMT/cancel" \
  -H "X-Hoody-Container: c1"

await client.agent.tasks.cancelTask(
  "sess_01HZX3F4K7P8QCJR2VA9NMDYBW",
  "tsk_01HZX3F4NA7XQ9B5YC8VP6JKMT"
);

{
  "ok": true,
  "sessionId": "sess_01HZX3F4K7P8QCJR2VA9NMDYBW",
  "taskId": "tsk_01HZX3F4NA7XQ9B5YC8VP6JKMT",
  "canceled": 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, 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)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. `hoody agent …` → platform → 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). The gateway rejects an oversized body at the edge (`http.MaxBytesReader`) before the handler reads it — a well-formed-but-large body is a size violation, not a JSON syntax error.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

Cancel all background subagent tasks on a live session. Internally this is session.task_cancel with an empty task id, which the daemon interprets as a cancel-all.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST `/todos`; `createTodo` also accepts a body cwd).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves (HoodyPaths).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent): `"global"` or a 24-hex id. Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.

curl -X POST "https://proj-c1-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/sessions/sess_01HZX3F4K7P8QCJR2VA9NMDYBW/tasks/cancel" \
  -H "X-Hoody-Container: c1"

await client.agent.tasks.cancelAllTasks("sess_01HZX3F4K7P8QCJR2VA9NMDYBW");

{
  "ok": true,
  "sessionId": "sess_01HZX3F4K7P8QCJR2VA9NMDYBW",
  "cancelAll": 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, 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)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. `hoody agent …` → platform → 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). The gateway rejects an oversized body at the edge (`http.MaxBytesReader`) before the handler reads it — a well-formed-but-large body is a size violation, not a JSON syntax error.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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