---
title: "Get agent hooks"
method: GET
path: "/v1/agents/{id}/hooks"
---

# Get agent hooks

`GET /v1/agents/{id}/hooks`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/agents/{id}/hooks`
- Auth: HTTP bearer

Retrieve the agent's hooks document — the HTTP endpoints and Custom MCP tools Runbear calls when a thread starts (`SessionStart`), when a user message arrives (`UserPromptSubmit`), before and after each tool call (`PreToolUse`, `PostToolUse`) and when the reply is ready (`Stop`), in the Claude Code hooks schema. `http` header values are always returned as `<redacted>`. An agent without hooks returns `{ "hooks": {} }`. Returns 404 when the agent is not found or its provider does not run hooks.

## Path parameters

- `id` string, uuid, required: Agent ID

## Response `200`

Default Response

- AgentHooksDocument
  - `hooks` AgentHooksMap, required: Claude Code hooks document restricted to the events and handler types Runbear runs: event name → matcher groups → handlers. At most 8 handlers per event across all groups. Handlers for one event run in parallel; every `additionalContext` is kept in handler order, a single `block` blocks (on `PreToolUse` the strictest `permissionDecision` wins), and any one string is capped at 10,000 characters.
    - `SessionStart` AgentHookMatcherGroup[]: Runs once per thread, before the first reply. Returned context is added to the system prompt for the life of the thread. Always fails open.
      - `matcher` string: Which invocations the group applies to, evaluated the way Claude Code does: omitted, empty or `*` matches everything; `A|B` is an exact-name list; anything else is an unanchored regular expression. `SessionStart` matches on how the session started (always `startup` on Runbear); `PreToolUse` and `PostToolUse` match on the tool name as the model sees it; `UserPromptSubmit` and `Stop` have no matcher and a value there is ignored.
      - `hooks` AgentHookHandler[], required: Handlers to run when the matcher applies.
        - union
          - object: POSTs the hook input to your endpoint and reads a Claude Code JSON output from a 2xx response. An empty 2xx body is a no-op; any other status is a failure.
            - `type` 'http', required
            - `url` string, uri, required: Endpoint that receives the hook input as a JSON POST. Must be `https` and resolve to a public address; a private or loopback address is refused at call time.
            - `headers` object: Request headers (at most 16), typically an authorization token. Values are stored in the organization vault and never returned: reads show every value as `<redacted>`, and sending `<redacted>` back on PUT keeps the stored value for that URL and header name. `content-type`, `content-length`, `host` and `x-runbear-hook-event` cannot be overridden.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
          - object: Calls a tool on one of the agent's Custom MCP servers. The tool's text result is read as Claude Code JSON output when it looks like JSON, otherwise as plain additional context.
            - `type` 'mcp_tool', required
            - `server` string, required: Namespace (`app`) of one of the agent's Custom MCP integrations. Must exist on the agent when the document is written.
            - `tool` string, required: Name of the tool to call on that server.
            - `input` object: Arguments for the tool. String values may reference hook input fields as `${field}` (dot paths allowed, e.g. `${prompt}`, `${channel_user_id}`). A value that is exactly one placeholder keeps the referenced value's JSON type; a placeholder that resolves to nothing drops the key. Keys the tool does not declare are dropped.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
    - `UserPromptSubmit` AgentHookMatcherGroup[]: Runs for every user message, before the model. Returned context is placed next to that message and replayed on later turns; a `decision: "block"` stops the reply and shows `reason` to the user.
      - `matcher` string: Which invocations the group applies to, evaluated the way Claude Code does: omitted, empty or `*` matches everything; `A|B` is an exact-name list; anything else is an unanchored regular expression. `SessionStart` matches on how the session started (always `startup` on Runbear); `PreToolUse` and `PostToolUse` match on the tool name as the model sees it; `UserPromptSubmit` and `Stop` have no matcher and a value there is ignored.
      - `hooks` AgentHookHandler[], required: Handlers to run when the matcher applies.
        - union
          - object: POSTs the hook input to your endpoint and reads a Claude Code JSON output from a 2xx response. An empty 2xx body is a no-op; any other status is a failure.
            - `type` 'http', required
            - `url` string, uri, required: Endpoint that receives the hook input as a JSON POST. Must be `https` and resolve to a public address; a private or loopback address is refused at call time.
            - `headers` object: Request headers (at most 16), typically an authorization token. Values are stored in the organization vault and never returned: reads show every value as `<redacted>`, and sending `<redacted>` back on PUT keeps the stored value for that URL and header name. `content-type`, `content-length`, `host` and `x-runbear-hook-event` cannot be overridden.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
          - object: Calls a tool on one of the agent's Custom MCP servers. The tool's text result is read as Claude Code JSON output when it looks like JSON, otherwise as plain additional context.
            - `type` 'mcp_tool', required
            - `server` string, required: Namespace (`app`) of one of the agent's Custom MCP integrations. Must exist on the agent when the document is written.
            - `tool` string, required: Name of the tool to call on that server.
            - `input` object: Arguments for the tool. String values may reference hook input fields as `${field}` (dot paths allowed, e.g. `${prompt}`, `${channel_user_id}`). A value that is exactly one placeholder keeps the referenced value's JSON type; a placeholder that resolves to nothing drops the key. Keys the tool does not declare are dropped.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
    - `PreToolUse` AgentHookMatcherGroup[]: Runs before each tool call, with `tool_name` and `tool_input`. `hookSpecificOutput.permissionDecision` decides whether the call runs: `allow`, `deny` (the model receives `permissionDecisionReason` as the tool's error result), or `ask`, which is treated as `deny` because Runbear has no per-call approval prompt. `hookSpecificOutput.updatedInput` replaces the arguments. Across handlers the strictest decision wins. Server-side tools the model provider runs itself (Anthropic web search and code execution, Vertex `google_search` and `code_execution`) are not hookable. Honours `failClosed`.
      - `matcher` string: Which invocations the group applies to, evaluated the way Claude Code does: omitted, empty or `*` matches everything; `A|B` is an exact-name list; anything else is an unanchored regular expression. `SessionStart` matches on how the session started (always `startup` on Runbear); `PreToolUse` and `PostToolUse` match on the tool name as the model sees it; `UserPromptSubmit` and `Stop` have no matcher and a value there is ignored.
      - `hooks` AgentHookHandler[], required: Handlers to run when the matcher applies.
        - union
          - object: POSTs the hook input to your endpoint and reads a Claude Code JSON output from a 2xx response. An empty 2xx body is a no-op; any other status is a failure.
            - `type` 'http', required
            - `url` string, uri, required: Endpoint that receives the hook input as a JSON POST. Must be `https` and resolve to a public address; a private or loopback address is refused at call time.
            - `headers` object: Request headers (at most 16), typically an authorization token. Values are stored in the organization vault and never returned: reads show every value as `<redacted>`, and sending `<redacted>` back on PUT keeps the stored value for that URL and header name. `content-type`, `content-length`, `host` and `x-runbear-hook-event` cannot be overridden.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
          - object: Calls a tool on one of the agent's Custom MCP servers. The tool's text result is read as Claude Code JSON output when it looks like JSON, otherwise as plain additional context.
            - `type` 'mcp_tool', required
            - `server` string, required: Namespace (`app`) of one of the agent's Custom MCP integrations. Must exist on the agent when the document is written.
            - `tool` string, required: Name of the tool to call on that server.
            - `input` object: Arguments for the tool. String values may reference hook input fields as `${field}` (dot paths allowed, e.g. `${prompt}`, `${channel_user_id}`). A value that is exactly one placeholder keeps the referenced value's JSON type; a placeholder that resolves to nothing drops the key. Keys the tool does not declare are dropped.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
    - `PostToolUse` AgentHookMatcherGroup[]: Runs after each tool call that succeeded, with `tool_input` (the arguments the tool ran with) and `tool_response`; a call the runtime marked as an error is not hooked. Returned context is appended to the tool result the model reads; a `decision: "block"` cannot undo the call, so its `reason` is fed back to the model as guidance next to the result. Always fails open.
      - `matcher` string: Which invocations the group applies to, evaluated the way Claude Code does: omitted, empty or `*` matches everything; `A|B` is an exact-name list; anything else is an unanchored regular expression. `SessionStart` matches on how the session started (always `startup` on Runbear); `PreToolUse` and `PostToolUse` match on the tool name as the model sees it; `UserPromptSubmit` and `Stop` have no matcher and a value there is ignored.
      - `hooks` AgentHookHandler[], required: Handlers to run when the matcher applies.
        - union
          - object: POSTs the hook input to your endpoint and reads a Claude Code JSON output from a 2xx response. An empty 2xx body is a no-op; any other status is a failure.
            - `type` 'http', required
            - `url` string, uri, required: Endpoint that receives the hook input as a JSON POST. Must be `https` and resolve to a public address; a private or loopback address is refused at call time.
            - `headers` object: Request headers (at most 16), typically an authorization token. Values are stored in the organization vault and never returned: reads show every value as `<redacted>`, and sending `<redacted>` back on PUT keeps the stored value for that URL and header name. `content-type`, `content-length`, `host` and `x-runbear-hook-event` cannot be overridden.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
          - object: Calls a tool on one of the agent's Custom MCP servers. The tool's text result is read as Claude Code JSON output when it looks like JSON, otherwise as plain additional context.
            - `type` 'mcp_tool', required
            - `server` string, required: Namespace (`app`) of one of the agent's Custom MCP integrations. Must exist on the agent when the document is written.
            - `tool` string, required: Name of the tool to call on that server.
            - `input` object: Arguments for the tool. String values may reference hook input fields as `${field}` (dot paths allowed, e.g. `${prompt}`, `${channel_user_id}`). A value that is exactly one placeholder keeps the referenced value's JSON type; a placeholder that resolves to nothing drops the key. Keys the tool does not declare are dropped.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
    - `Stop` AgentHookMatcherGroup[]: Runs when the reply is ready, with `last_assistant_message`. A `decision: "block"` sends `reason` back to the agent and lets it continue once per turn; on that continuation `stop_hook_active` is `true` and a further block is ignored. Always fails open.
      - `matcher` string: Which invocations the group applies to, evaluated the way Claude Code does: omitted, empty or `*` matches everything; `A|B` is an exact-name list; anything else is an unanchored regular expression. `SessionStart` matches on how the session started (always `startup` on Runbear); `PreToolUse` and `PostToolUse` match on the tool name as the model sees it; `UserPromptSubmit` and `Stop` have no matcher and a value there is ignored.
      - `hooks` AgentHookHandler[], required: Handlers to run when the matcher applies.
        - union
          - object: POSTs the hook input to your endpoint and reads a Claude Code JSON output from a 2xx response. An empty 2xx body is a no-op; any other status is a failure.
            - `type` 'http', required
            - `url` string, uri, required: Endpoint that receives the hook input as a JSON POST. Must be `https` and resolve to a public address; a private or loopback address is refused at call time.
            - `headers` object: Request headers (at most 16), typically an authorization token. Values are stored in the organization vault and never returned: reads show every value as `<redacted>`, and sending `<redacted>` back on PUT keeps the stored value for that URL and header name. `content-type`, `content-length`, `host` and `x-runbear-hook-event` cannot be overridden.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.
          - object: Calls a tool on one of the agent's Custom MCP servers. The tool's text result is read as Claude Code JSON output when it looks like JSON, otherwise as plain additional context.
            - `type` 'mcp_tool', required
            - `server` string, required: Namespace (`app`) of one of the agent's Custom MCP integrations. Must exist on the agent when the document is written.
            - `tool` string, required: Name of the tool to call on that server.
            - `input` object: Arguments for the tool. String values may reference hook input fields as `${field}` (dot paths allowed, e.g. `${prompt}`, `${channel_user_id}`). A value that is exactly one placeholder keeps the referenced value's JSON type; a placeholder that resolves to nothing drops the key. Keys the tool does not declare are dropped.
            - `timeout` integer: Timeout in seconds. Defaults to 5 on `SessionStart`, 3 on `UserPromptSubmit`, 3 on `PreToolUse`, 3 on `PostToolUse`, 3 on `Stop`; at most 10. Every hook sits on the reply's critical path, so keep it short.
            - `failClosed` boolean: Block the operation when this handler fails (timeout, transport error, non-2xx response, malformed output) instead of ignoring the failure: the reply on `UserPromptSubmit`, the tool call on `PreToolUse`. Rejected on `SessionStart`, `PostToolUse` and `Stop`, which always fail open.

## Other responses

- `404`: Default Response

---

[API](https://skmtc.dev/runbear/apis/runbear-api.md) - [All operations](https://skmtc.dev/runbear/apis/runbear-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runbear/apis/runbear-api/revisions/c6a9c3066a5a?raw)