Docs search: /hooks / Claude Code source intelligence

Intercept and control agent behavior with hooks Claude Code CLI · path agent-sdk/hooks

How the agent loop works Claude Code CLI · in the page agent-sdk/agent-loop …o Claude for the next decision. You can use [hooks](/docs/en/agent-sdk/hooks.md) to intercept, modify, or block tool calls before they run. 4. **Repeat.** Steps 2 and 3 repeat as a cycle. Each full cy…

Use Claude Code features in the SDK Claude Code CLI · in the page agent-sdk/claude-code-features …hooks you'd configure for [interactive Claude Code sessions](/docs/en/hooks-guide.md). * **Programmatic hooks:** callback functions passed directly to `query()`. These run in your application process…

Connect to external tools with MCP Claude Code CLI · in the page agent-sdk/mcp …ns.allow` rule in the `settings` option. An [`mcp_tool` hook](/docs/en/hooks#mcp-tool-hook-fields) also names the server it calls when you configure it on a prompt-submission, tool-use, permission, su…

Modifying system prompts Claude Code CLI · in the page agent-sdk/modifying-system-prompts …se. [Skills](/docs/en/agent-sdk/skills.md), [hooks](/docs/en/agent-sdk/hooks.md), and [permissions](/docs/en/agent-sdk/permissions.md) also shape behavior outside the system prompt and are covered on…

Observability with OpenTelemetry Claude Code CLI · in the page agent-sdk/observability …tion`). * **`claude_code.hook`:** wraps each [hook](/docs/en/agent-sdk/hooks.md) execution. Requires detailed beta tracing (`ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT`), a pair that a…

Configure permissions Claude Code CLI · in the page agent-sdk/permissions …rmissions in this order: **1. Hooks** Run [hooks](/docs/en/agent-sdk/hooks.md) first. A hook can deny the call outright or pass it on. A hook that returns `allow` doesn't skip the deny and ask rules…

Agent SDK reference - Python Claude Code CLI · in the page agent-sdk/python …To gate every tool call, use a [`PreToolUse` hook](/docs/en/agent-sdk/hooks) instead. An allow rule doesn't pre-approve the [actions no mode auto-approves](/docs/en/permission-modes.md#actions-no-mo…

Quickstart Claude Code CLI · in the page agent-sdk/quickstart …agent can do and when it needs approval * **[Hooks](/docs/en/agent-sdk/hooks.md)**: run custom code before or after tool calls * **[Sessions](/docs/en/agent-sdk/sessions.md)**: build multi-turn agents…

Troubleshoot the Agent SDK Claude Code CLI · in the page agent-sdk/troubleshooting …sage` not appearing in output | [Fix common issues](/docs/en/agent-sdk/hooks.md#fix-common-issues) on the hooks page | | An agent that works on your machine fails in a deployed service or container |…

Agent SDK reference - TypeScript Claude Code CLI · in the page agent-sdk/typescript …sponseMessage` only when a hook [that runs in the background](/docs/en/hooks.md#run-hooks-in-the-background) finishes | | `includePartialMessages` | `boolean` | `false` | Include partial message event…

Handle approvals and user input Claude Code CLI · in the page agent-sdk/user-input …onably stay running, register a [`PreToolUse` hook](/docs/en/agent-sdk/hooks) that returns the [`defer` decision](/docs/en/hooks#defer-a-tool-call-for-later) instead of waiting in the callback, so the…

Orchestrate teams of Claude Code sessions Claude Code CLI · in the page agent-teams …y on disk. ### Enforce quality gates with hooks Use [hooks](/docs/en/hooks.md) to enforce rules when teammates finish work or tasks are created or completed: * [`TeammateIdle`](/docs/en/hooks#teamm…

Manage multiple agents with agent view Claude Code CLI · in the page agent-view …as the rest of Claude Code and fire the [`Notification` hook](/docs/en/hooks#notification) with the `agent_needs_input` or `agent_completed` type. Background sessions don't need any terminal open to…

Configure auto mode Claude Code CLI · in the page auto-mode-config …that inspects the full command text, add a [PreToolUse hook](/docs/en/hooks.md#pretooluse). Pick the mechanism that matches how firm the boundary needs to be: | Boundary | Mechanism | Behavior in a…

Best practices for Claude Code Claude Code CLI · in the page best-practices …aluation-works). * **As a deterministic gate**: a [Stop hook](/docs/en/hooks.md#stop) runs your check as a script and blocks the turn from ending until it passes. [Stop input](/docs/en/hooks.md#stop-i…

Champion kit Claude Code CLI · in the page champion-kit …notification when a long-running task completes. See [Hooks](/docs/en/hooks-guide.md). | | Recover from an incorrect result | Rather than rephrasing the request, paste the failing test or stack trace…

Claude Code changelog Claude Code CLI · in the page changelog …ry packages * Changed list screens (`/artifacts`, `/mcp`, `/skills`, `/hooks` and others) to always line up each row's details in one column after the names * Changed the overflow rows of lists to rea…

Use Claude Code in the cloud Claude Code CLI · in the page claude-code-on-the-web …call, or in response to GitHub events * [Hooks configuration](/docs/en/hooks.md): run scripts at session lifecycle events * [All settings](/docs/en/settings-reference.md): all configuration options *…

Explore the .claude directory Claude Code CLI · in the page claude-directory …e <C>.claude/</C></>, <>Git-only: if you configure a <A href="/docs/en/hooks#worktreecreate">WorktreeCreate hook</A> for a different VCS, this file is not read. Copy files inside your hook script inst…

CLI reference Claude Code CLI · in the page cli-reference …t` | Run [Setup hooks](/docs/en/hooks#setup) with the `init` matcher before the session (print mode only)…

Configure cloud environments Claude Code CLI · in the page cloud-environments …a `command` hook after 600 seconds unless you set [`timeout`](/docs/en/hooks#common-fields), in seconds, on the hook entry. Claude Code doesn't enforce the timeout on a hook you run with [`async: true…

Commands Claude Code CLI · in the page commands …share`. After a successful add, your [`DirectoryAdded` hooks](/docs/en/hooks#directoryadded) run. When you run it while Claude is responding, Claude Code asks you to confirm the directory right away,…

Common workflows Claude Code CLI · in the page common-workflows …it in project and local settings. Your [`PreToolUse` hooks](/docs/en/hooks#pretooluse) don't run when Claude Code includes a file you reference with `@`, because it makes no tool call. If you rely o…

Communications kit Claude Code CLI · in the page communications-kit …cript and wire it up. 📖 Hooks guide → https://code.claude.com/docs/en/hooks-guide ``` ### Day-to-day development **Screenshots and images** ```markdown theme={null} 📸 *Tip: Stop describing the err…

Explore the context window Claude Code CLI · in the page context-window …ile; Claude gets a preview and the file path instead.', link: '/en/hooks-guide' }, { t: 0.62, kind: 'claude', label: 'Edit auth.test.ts', tokens: 600, color: '#D97757', v…

Manage costs effectively Claude Code CLI · in the page costs …. ### Offload processing to hooks and skills Custom [hooks](/docs/en/hooks.md) can preprocess data before Claude sees it. Instead of Claude reading a 10,000-line log file to find errors, a hook can…

Message your other Claude Code sessions Claude Code CLI · in the page cross-session-messaging …is prefixed with `uds:`. * Claude Code exports it to [hooks](/docs/en/hooks.md) and Bash commands as the [`CLAUDE_CODE_MESSAGING_SOCKET`](/docs/en/env-vars#variables) environment variable: * In a s…

Debug your configuration Claude Code CLI · in the page debug-your-config …, MCP servers, or skills aren't taking effect. Use /context, /doctor, /hooks, and /mcp to see what actually loaded. When Claude ignores an instruction or a feature you configured doesn't appear, the…

Desktop application Claude Code CLI · in the page desktop …A hook that answers**: configure a [`PermissionRequest` hook](/docs/en/hooks#permissionrequest) in `~/.claude/settings.json` on the remote machine to allow or deny requests in your place * **A hook th…

Environment variables Claude Code CLI · in the page env-vars …Code spawns (Bash and PowerShell tools, tmux sessions, [hook](/docs/en/hooks) commands, [status line](/docs/en/statusline) commands, stdio [MCP server](/docs/en/mcp) subprocesses). IDE extensions also…

Error reference Claude Code CLI · in the page errors …ssion rules](/docs/en/permissions.md#mcp) and [hook matchers](/docs/en/hooks.md#match-mcp-tools). * If a [plugin bundles the server](/docs/en/mcp.md#plugin-provided-mcp-servers), the tool's full name…

Feature availability Claude Code CLI · in the page feature-availability …md) extensions * [Subagents](/docs/en/sub-agents.md), [hooks](/docs/en/hooks-guide.md), [commands](/docs/en/commands.md), and [skills](/docs/en/skills.md) * [CLAUDE.md memory](/docs/en/memory.md), [pl…

Extend Claude Code Claude Code CLI · in the page features-overview …ss a message from one of your sessions to another * **[Hooks](/docs/en/hooks-guide.md)** run your script, HTTP request, MCP tool call, prompt, or subagent when Claude Code reaches a lifecycle event *…

Fullscreen rendering Claude Code CLI · in the page fullscreen …s) * Deny or ask rules that a [hook or SDK permission update](/docs/en/hooks.md#permission-update-entries) added for this session only In that case Claude Code prints [`Cannot switch renderers in thi…

Glossary Claude Code CLI · in the page glossary …ok handler**: what runs Learn more: [Get started with hooks](/docs/en/hooks-guide.md) · [Hooks reference](/docs/en/hooks.md) ## M ### Managed settings Settings enforced org-wide by IT or DevOps, d…

Keep Claude working toward a goal Claude Code CLI · in the page goal …u stop it, or Claude decides the work is done | | [Stop hook](/docs/en/hooks-guide.md#prompt-based-hooks) | The previous turn finishes | Your own script or prompt decides | `/goal` and a Stop hook bo…

Run Claude Code programmatically Claude Code CLI · in the page headless …is still running. Claude Code then runs [`SessionEnd` hooks](/docs/en/hooks#sessionend) and exits. While exiting, Claude Code starts no new tool call, sends no new model request, and runs no hook oth…

Hooks reference Claude Code CLI · in the page hooks …kstart guide with examples, see [Automate actions with hooks](/docs/en/hooks-guide.md). Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute a…

Automate actions with hooks Claude Code CLI · in the page hooks-guide …ike async hooks and MCP tool hooks, see the [Hooks reference](/docs/en/hooks.md). ## Set up your first hook To create a hook, add a `hooks` block to a [settings file](#configure-hook-location). This…

How Claude Code works Claude Code CLI · in the page how-claude-code-works …with [MCP](/docs/en/mcp.md), automate workflows with [hooks](/docs/en/hooks.md), and offload tasks to [subagents](/docs/en/sub-agents.md). These extensions form a layer on top of the core agentic loo…

Interactive mode Claude Code CLI · in the page interactive-mode …**The continuation is blocked**: a [`UserPromptSubmit` hook](/docs/en/hooks#userpromptsubmit) that blocks the continuation prompt, or a failure before it reaches the model, ends the wait. Claude Code…

JetBrains IDEs Claude Code CLI · in the page jetbrains …to configure. If your organization uses a [`PreToolUse` hook](/docs/en/hooks#pretooluse) to allowlist MCP tools, though, you'll need to know it exists. **Selection and open-file context.** While conn…

Set up Claude Code in a monorepo or large codebase Claude Code CLI · in the page large-codebases …* **Add a Stop hook that proposes updates**: a [`Stop` hook](/docs/en/hooks#stop) receives the path to the session transcript when Claude finishes responding, so a script can review the session and p…

Connect Claude Code to tools via MCP Claude Code CLI · in the page mcp …ld](/docs/en/sub-agents#available-tools), or a [hook matcher](/docs/en/hooks.md#match-mcp-tools). A hook matcher written against the bare server key, such as `mcp__database-tools__.*`, never fires for…

How Claude remembers your project Claude Code CLI · in the page memory …on regardless of what Claude decides, use a [PreToolUse hook](/docs/en/hooks-guide.md) instead. The more specific and concise your instructions, the more consistently Claude follows them. | | CLAUDE.…

Model configuration Claude Code CLI · in the page model-config …If you or your organization configure [PreModelSwitch hooks](/docs/en/hooks.md#premodelswitch), they run before a requested switch applies and can block it or ask you to confirm. When Claude Code ca…