---
title: "Set agent hooks"
method: PUT
path: "/v1/agents/{id}/hooks"
---

# Set agent hooks

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

## Request

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

Replace the agent's hooks document as one unit, the way a Claude Code settings file is saved. `http` header values are moved into the organization vault; send `<redacted>` for a header to keep the value already stored for that URL and header name. Every `mcp_tool` handler's `server` must be the `app` namespace of a Custom MCP integration on this agent. Returns the stored document with header values redacted. Returns 404 when the agent is not found or its provider does not run hooks, 403 when agent hooks are not enabled for the organization, and 422 with per-field `issues` when the document is invalid.

## Path parameters

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

## Request body

- AgentHooksSetRequest
  - `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.

## 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

- `403`: Default Response
- `404`: Default Response
- `422`: 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)