Agent: Hooks

The agent hook endpoints manage the lifecycle hooks that fire shell commands on agent session events. The hook system is session-scoped: every operation takes a live session_id, and write operations (upsert, delete, toggle, set_disabled) additionally require a single-use nonce minted by the begin-write route. Use these endpoints when you want to inspect the live hook state, define or remove hooks, toggle individual hooks, test-fire a hook command, reload the on-disk configuration, disable all hooks at once, or acknowledge the hook-trust prompt.

All endpoints live under the agent container’s public hostname of the form https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com. Requests must reach the agent through the Hoody proxy — direct container connections are rejected with forbidden.

Note

Hook writes are guarded by a two-step nonce handshake. Before calling upsert, delete, toggle, or set_disabled, first POST to begin-write with the matching op and scope; the returned nonce is bound to that session+op+scope tuple and is single-use. A nonce minted for op:toggle is not accepted by upsert, and vice versa.

Listing hooks

GET /api/v1/agent/hooks

Returns the live and on-disk hook summaries, the per-scope settings files, and the execution-trust probe. hooks.list is session-scoped — supply session_id in the body or as the ?session_id query alias (the body value wins). The daemon payload is surfaced verbatim, so this is not a paginated envelope.

Parameters

Name	In	Type	Required	Description
session_id	query	string	No	Live session id (hooks are session-scoped; required by the daemon RPC). Query alias of the body session_id (the body value wins).
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

Field	Type	Required	Description
session_id	string	No	Live session id (hooks are session-scoped). May be supplied here OR as the ?session_id query alias; the body value wins.

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4"
}

Response

200

{
  "live": [
    {
      "name": "format-on-pre-tool",
      "description": "Run prettier on files before any tool call",
      "event": "PreToolUse",
      "matcher": "Write|Edit",
      "enabled": true,
      "command": "npx prettier --write \"$HOODY_FILE_PATH\"",
      "timeout": 15000
    }
  ],
  "session": {
    "id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
    "scope": "project"
  },
  "stale": [],
  "files": [
    {
      "scope": "project",
      "path": "/repo/.hoody/settings.json",
      "hook_count": 1
    }
  ],
  "trust": {
    "pending": false,
    "acknowledged_at": "2026-01-15T18:22:04Z"
  }
}

400

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

403

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

429

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

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

SDK Usage

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4" }'

TypeScript SDK

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.hooks.listHooks({ session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4' });

Beginning a hook write

POST /api/v1/agent/hooks/begin-write

Issues the two-step write nonce required before every guarded hook mutation. Pass the live session_id, the target op (one of upsert, delete, toggle, set_disabled), and the scope path. The returned nonce binds to that session + op + scope tuple and is single-use; the nonce for op:toggle is not accepted by upsert, and so on.

Parameters

Name	In	Type	Required	Description
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

Field	Type	Required	Description
session_id	string	Yes	Live session id (hooks are session-scoped).
op	string	Yes	The write the nonce authorizes; one of upsert, delete, toggle, set_disabled. The nonce is rejected by any other op.
scope	string	Yes	Scope of the settings file the write targets (e.g. project, user); the nonce binds to its resolved path.

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
  "op": "upsert",
  "scope": "project"
}

Response

200

{
  "nonce": "nb_nE4kM2xR8pWq3vT7sJ9aB6cF1dL5hY",
  "op": "upsert",
  "scope": "project",
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
  "expires_at": "2026-01-15T18:27:04Z"
}

400

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

403

{
  "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 reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

404

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

{
  "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 before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

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

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

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

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks/begin-write" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4", "op": "upsert", "scope": "project" }'

TypeScript SDK

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.hooks.beginHookWrite({
  session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4',
  op: 'upsert',
  scope: 'project'
});

Upserting a hook

PUT /api/v1/agent/hooks

Creates or updates a hook (hooks.upsert). Requires the begin-write nonce for op:upsert and a live session_id. Defining a hook persists an arbitrary command that fires on lifecycle events.

Caution

Creating a NEW hook requires non-empty name and description; the daemon rejects an undocumented create. Updating an existing hook may omit them to preserve the current values.

Parameters

Name	In	Type	Required	Description
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

Field	Type	Required	Description
session_id	string	Yes	Live session id (hooks are session-scoped).
nonce	string	Yes	The single-use write nonce from beginHookWrite minted for op:upsert + this scope; the RPC fails closed without it.
scope	string	No	Scope of the settings file to write (must match the nonce’s scope).
event	string	No	Lifecycle event the hook fires on.
matcher	string	No	Matcher selecting when the hook fires.
command	string	No	Command to run when the hook fires.
timeout	integer	No	Per-fire timeout (optional).
name	string	No	Short human label shown in the Hooks tab (required when creating a new hook; omit to preserve on update).
description	string	No	Short description of what the hook does (required when creating a new hook; omit to preserve on update).

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
  "nonce": "nb_nE4kM2xR8pWq3vT7sJ9aB6cF1dL5hY",
  "scope": "project",
  "event": "PreToolUse",
  "matcher": "Write|Edit",
  "command": "npx prettier --write \"$HOODY_FILE_PATH\"",
  "timeout": 15000,
  "name": "format-on-pre-tool",
  "description": "Run prettier on files before any tool call"
}

Response

200

{
  "ok": true,
  "hook": {
    "name": "format-on-pre-tool",
    "description": "Run prettier on files before any tool call",
    "event": "PreToolUse",
    "matcher": "Write|Edit",
    "enabled": true,
    "command": "npx prettier --write \"$HOODY_FILE_PATH\"",
    "timeout": 15000,
    "scope": "project"
  }
}

400

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

403

{
  "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 reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

404

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

{
  "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 before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

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

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

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

SDK Usage

cURL

curl -X PUT "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
    "nonce": "nb_nE4kM2xR8pWq3vT7sJ9aB6cF1dL5hY",
    "scope": "project",
    "event": "PreToolUse",
    "matcher": "Write|Edit",
    "command": "npx prettier --write \"$HOODY_FILE_PATH\"",
    "timeout": 15000,
    "name": "format-on-pre-tool",
    "description": "Run prettier on files before any tool call"
  }'

TypeScript SDK

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.hooks.upsertHook({
  session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4',
  nonce: 'nb_nE4kM2xR8pWq3vT7sJ9aB6cF1dL5hY',
  scope: 'project',
  event: 'PreToolUse',
  matcher: 'Write|Edit',
  command: 'npx prettier --write "$HOODY_FILE_PATH"',
  timeout: 15000,
  name: 'format-on-pre-tool',
  description: 'Run prettier on files before any tool call'
});

Deleting a hook

DELETE /api/v1/agent/hooks

Deletes a hook (hooks.delete). Requires the begin-write nonce minted by beginHookWrite for op:delete plus a live session_id.

Parameters

Name	In	Type	Required	Description
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

Field	Type	Required	Description
session_id	string	Yes	Live session id (hooks are session-scoped).
nonce	string	Yes	The single-use write nonce from beginHookWrite minted for op:delete + this scope; the RPC fails closed without it.
scope	string	No	Scope of the settings file to write (must match the nonce’s scope).

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
  "nonce": "nb_Z8rQ5yN1kP4tV9wX3mC7sL2bH6jF0dG",
  "scope": "project"
}

Response

200

{
  "ok": true,
  "deleted": "format-on-pre-tool",
  "scope": "project"
}

400

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

403

{
  "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 reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

404

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

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

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

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

SDK Usage

cURL

curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
    "nonce": "nb_Z8rQ5yN1kP4tV9wX3mC7sL2bH6jF0dG",
    "scope": "project"
  }'

TypeScript SDK

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.hooks.deleteHook({
  session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4',
  nonce: 'nb_Z8rQ5yN1kP4tV9wX3mC7sL2bH6jF0dG',
  scope: 'project'
});

Toggling a single hook

POST /api/v1/agent/hooks/toggle

Toggles a single hook’s enabled state (hooks.toggle). This is a guarded write: it requires the begin-write nonce minted for op:toggle (the daemon RPC fails closed without it) plus a live session_id.

Parameters

Name	In	Type	Required	Description
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

Field	Type	Required	Description
session_id	string	Yes	Live session id (hooks are session-scoped).
nonce	string	Yes	The single-use write nonce from beginHookWrite minted for op:toggle + this scope; the RPC fails closed without it.
scope	string	No	Scope of the settings file to write (must match the nonce’s scope).

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
  "nonce": "nb_T3gH7vL2mK9pQ5wX4nR1sJ8bC6dF0yN",
  "scope": "project"
}

Response

200

{
  "ok": true,
  "toggled": "format-on-pre-tool",
  "enabled": false,
  "scope": "project"
}

400

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

403

{
  "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 reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

404

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

{
  "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 before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

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

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

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

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks/toggle" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
    "nonce": "nb_T3gH7vL2mK9pQ5wX4nR1sJ8bC6dF0yN",
    "scope": "project"
  }'

TypeScript SDK

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.hooks.toggleHook({
  session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4',
  nonce: 'nb_T3gH7vL2mK9pQ5wX4nR1sJ8bC6dF0yN',
  scope: 'project'
});

Disabling all hooks

POST /api/v1/agent/hooks/disable-all

Disables (or re-enables) all hooks at once (hooks.set_disabled). This is a guarded write: it requires the begin-write nonce minted by beginHookWrite for op:set_disabled (the daemon RPC fails closed without it) plus a live session_id.

Parameters

Name	In	Type	Required	Description
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

Field	Type	Required	Description
session_id	string	Yes	Live session id (hooks are session-scoped).
nonce	string	Yes	The single-use write nonce from beginHookWrite minted for op:set_disabled + this scope; the RPC fails closed without it.
scope	string	No	Scope of the settings file to write (must match the nonce’s scope).

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
  "nonce": "nb_D1sA6bF8cJ2kM4nP7qR5tV9wX3yL0hG",
  "scope": "project"
}

Response

200

{
  "ok": true,
  "disabled": true,
  "scope": "project",
  "affected_hooks": 3
}

400

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

403

{
  "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 reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

404

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

{
  "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 before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

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

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

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

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks/disable-all" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4",
    "nonce": "nb_D1sA6bF8cJ2kM4nP7qR5tV9wX3yL0hG",
    "scope": "project"
  }'

TypeScript SDK

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.hooks.disableAllHooks({
  session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4',
  nonce: 'nb_D1sA6bF8cJ2kM4nP7qR5tV9wX3yL0hG',
  scope: 'project'
});

Reloading hooks from disk

POST /api/v1/agent/hooks/reload

Reloads the hook configuration from disk (hooks.reload). Pass a live session_id in the body to also receive the reloaded summary.

Parameters

Name	In	Type	Required	Description
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

This endpoint takes no parameters.

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4"
}

Response

200

{
  "ok": true,
  "reloaded_from": [
    "/repo/.hoody/settings.json"
  ],
  "summary": {
    "live_count": 4,
    "stale_count": 0
  }
}

400

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

403

{
  "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 reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

404

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

{
  "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 before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

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

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

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

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks/reload" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4" }'

TypeScript SDK

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.hooks.reloadHooks({ session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4' });

Test-firing a hook

POST /api/v1/agent/hooks/test

Test-fires a hook command (hooks.test) — this EXECUTES an arbitrary command now. Requires a live session_id (hooks are session-scoped).

Danger

This endpoint runs the hook’s command immediately. Only call it after you have inspected the hook definition and trust the source.

Parameters

Name	In	Type	Required	Description
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

This endpoint takes no parameters.

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4"
}

Response

200

{
  "ok": true,
  "hook": "format-on-pre-tool",
  "exit_code": 0,
  "stdout": "src/index.ts 120ms\n",
  "stderr": "",
  "duration_ms": 612
}

400

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

403

{
  "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 reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

404

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

{
  "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 before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

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

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

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

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks/test" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4" }'

TypeScript SDK

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.hooks.testHook({ session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4' });

Acknowledging hook trust

POST /api/v1/agent/hooks/trust/ack

Acknowledges the hook-trust prompt (hooks.trust_ack). Requires a live session_id (hooks are session-scoped). Call this after the user has reviewed the pending hook changes and agreed to let them run.

Parameters

Name	In	Type	Required	Description
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.
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected with 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 with 400 realm_scope_unsupported on active-only routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

This endpoint takes no parameters.

{
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4"
}

Response

200

{
  "ok": true,
  "acknowledged_at": "2026-01-15T18:31:12Z",
  "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4"
}

400

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

403

{
  "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 reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

404

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

{
  "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 before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

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

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

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

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/hooks/trust/ack" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sess_8f3c2a1b9d4e5f60a1b2c3d4" }'

TypeScript SDK

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.hooks.ackHookTrust({ session_id: 'sess_8f3c2a1b9d4e5f60a1b2c3d4' });