Agent: Tasks

Inspect a session’s background task snapshot, read a task’s transcript, and cancel one or all background tasks. The task endpoints serve from a unified catalog that merges the live in-memory registry with the persisted per-session task store, so completed tasks remain readable after a session goes dormant or the daemon restarts. Cancellation routes require a live session and are handled at the server layer so they work mid-turn.

All routes are active-realm-scoped: a per-request X-Hoody-Realm header (or ?realm= alias) is rejected with realm_scope_unsupported.

List and Inspect

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

Returns the session’s background-subagent task catalog inline. The catalog is the union of the live registry and the persisted per-session task store, keyed by task id with the live entry winning. The live registry evicts completed tasks at spawn time, so a finished task can leave memory while its transcript is still durable. session_live reports whether a live session backed this read.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Session 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.
`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://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y/tasks' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.tasks.listTasks('sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y');

200 OK

Task catalog.

{
  "items": [
    {
      "id": "task_01HZ3M4N5P6Q7R8S9T0V1W2X3Y",
      "name": "code-review",
      "status": "done",
      "kind": "code_review",
      "prompt": "Review the diff for the auth refactor",
      "started_at": "2026-01-15T10:23:00.000Z",
      "updated_at": "2026-01-15T10:24:18.000Z",
      "tool_calls": 7,
      "elapsed_ms": 78421,
      "output_preview": "Reviewed 12 files, found 2 issues."
    },
    {
      "id": "task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z",
      "name": "test-runner",
      "status": "running",
      "kind": "tests",
      "prompt": "Run unit tests on the payment module",
      "started_at": "2026-01-15T10:24:50.000Z",
      "tool_calls": 2,
      "elapsed_ms": 12500
    }
  ],
  "meta": { "total": 2 },
  "session_live": true
}

400 Bad request

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

403 Forbidden

{
  "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 (for example `hoody agent …` → platform → proxy), not by connecting to the container directly.

404 Not found

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

429 Too many 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.

500 Internal error

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

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

Returns a background subagent task’s transcript inline — entries, the task’s TaskInfo, and the cursor state. A task that reached a terminal state is persisted per session, so its transcript is readable for a dormant session and after a daemon restart. A task still running when the daemon died is not recoverable (persistence happens at terminal status) and reads 404.

source is live when served from the live registry and store when served from the persisted task store. complete reports whether this response reflects a terminal projection durably committed to that store. after_seq is an int64 upsert-poll cursor, exclusive, except that a still-open entry is re-sent even when its seq is at or below the cursor (viewers upsert by seq). Omitting after_seq returns the whole transcript from the beginning, which is distinct from after_seq=0 — that value is exclusive and skips a closed seq-0 entry.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Session identifier.
`tid`	path	string	Yes	Task identifier.
`after_seq`	query	integer	No	Exclusive int64 upsert-poll cursor: entries with seq strictly greater than it, plus any still-open entry regardless of its seq. Omit for the whole transcript (distinct from `0`, which skips a closed seq-0 entry). Negative/non-integer = 400.
`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.
`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://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y/tasks/task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z/transcript?after_seq=7' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

// Read the transcript from the beginning.
await client.agent.tasks.getTaskTranscript('sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y', 'task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z');

// Resume polling past seq 7.
await client.agent.tasks.getTaskTranscript(
  'sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y',
  'task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z',
  { after_seq: 7 }
);

200 OK

Task transcript.

{
  "session_id": "sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y",
  "task_id": "task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z",
  "task": {
    "id": "task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z",
    "name": "test-runner",
    "status": "running",
    "kind": "tests",
    "prompt": "Run unit tests on the payment module",
    "started_at": "2026-01-15T10:24:50.000Z",
    "updated_at": "2026-01-15T10:25:01.000Z",
    "tool_calls": 2,
    "elapsed_ms": 11000
  },
  "entries": [
    { "seq": 0, "kind": "text", "text": "Running pytest on /srv/app/payment", "open": false },
    { "seq": 1, "kind": "tool_call", "tool": "exec", "text": "pytest -q payment/", "open": false },
    { "seq": 2, "kind": "tool_result", "tool": "exec", "is_error": false, "text": "42 passed in 3.21s", "open": false },
    { "seq": 3, "kind": "note", "text": "Streaming follow-up...", "open": true }
  ],
  "trimmed": false,
  "after_seq": 7,
  "complete": false,
  "source": "live",
  "session_live": true
}

400 Bad request

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

403 Forbidden

{
  "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 (for example `hoody agent …` → platform → proxy), not by connecting to the container directly.

404 Not found

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

429 Too many 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.

500 Internal error

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

Cancel Tasks

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

Cancels one background subagent task on a live session (session.task_cancel). Handled at the server layer so it works mid-turn.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Session identifier.
`tid`	path	string	Yes	Task 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.
`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.

This endpoint takes no request body.

curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y/tasks/task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z/cancel' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.tasks.cancelTask('sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y', 'task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z');

200 OK

Cancel requested. The body is the verbatim daemon reply — fields are those of the forwarded daemon action.

{
  "cancelled": true,
  "task_id": "task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z",
  "status": "cancelled"
}

400 Bad request

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

403 Forbidden

{
  "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 (for example `hoody agent …` → platform → proxy), not by connecting to the container directly.

404 Not found

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

413 Payload too large

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

429 Too many 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.

500 Internal error

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

503 Service unavailable

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

Cancels all background subagent tasks on a live session (session.task_cancel with an empty task id cancels all).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Session 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.
`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.

This endpoint takes no request body.

curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y/tasks/cancel' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.tasks.cancelAllTasks('sess_01HZ3M4N5P6Q7R8S9T0V1W2X3Y');

200 OK

Cancel-all requested. The body is the verbatim daemon reply — fields are those of the forwarded daemon action.

{
  "cancelled": 3,
  "task_ids": [
    "task_01HZ3M4N5P6Q7R8S9T0V1W2X3Y",
    "task_01HZ3M4N5P6Q7R8S9T0V1W2X3Z",
    "task_01HZ3M4N5P6Q7R8S9T0V1W2X40"
  ]
}

400 Bad request

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

403 Forbidden

{
  "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 (for example `hoody agent …` → platform → proxy), not by connecting to the container directly.

404 Not found

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

413 Payload too large

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

429 Too many 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.

500 Internal error

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

503 Service unavailable

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