2026年4月29日 09:27

22 ファイル変更 +965 -951

この更新の概要

新機能としてSetupフックが導入され、--init-onlyや-pオプション使用時の初期化処理を細かく制御できるようになりました。トラブルシューティング情報が大幅に整理され、インストールとログインに関する専用ページ(troubleshoot-install)が新設されています。環境変数にはCLAUDE_CODE_EXTRA_BODYやCLAUDE_CODE_MCP_ALLOWLIST_ENVなど、APIリクエストやMCPサーバーのセキュリティを細かく設定できる項目が追加されました。また、JetBrains IDEとの連携において、WSL2環境でのネットワーク設定やファイアウォール対応の詳細な手順が拡充されています。

admin-setup +1 -1

ログインに関するトラブルシューティングの参照先を、新設された専用ページに変更しています。

@@ -113,7 +113,7 @@ Share these resources to help developers get started:

- [Common workflows](/en/common-workflows): patterns for everyday tasks like code review, refactoring, and debugging

- [Claude 101](https://anthropic.skilljar.com/claude-101) and [Claude Code in Action](https://anthropic.skilljar.com/claude-code-in-action): self-paced Anthropic Academy courses

For login issues, point developers to [authentication troubleshooting](/en/troubleshooting#authentication-issues). The most common fixes are:

For login issues, point developers to [authentication troubleshooting](/en/troubleshoot-install#login-and-authentication). The most common fixes are:

- Run `/logout` then `/login` to switch accounts

- Run `claude update` if the enterprise auth option is missing

agent-sdk/plugins +1 -1

プラグインの読み込み設定において、typeフィールドにlocalを指定する必要があることを明記しています。

@@ -24,7 +24,7 @@ For complete information on plugin structure and how to create plugins, see [Plu

## Loading plugins

Load plugins by providing their local file system paths in your options configuration. The SDK supports loading multiple plugins from different locations.

Load plugins by providing their local file system paths in your options configuration. The `type` field must be `"local"`, the only value the SDK accepts. To use a plugin distributed through a [marketplace](/en/plugin-marketplaces) or remote repository, download it first and provide the local directory path. The SDK supports loading multiple plugins from different locations.

```typescript TypeScript theme={null}

import { query } from "@anthropic-ai/claude-agent-sdk";

authentication +1 -1

認証エラー時のヘルプ参照先を、新しく作成されたインストール・ログイン用トラブルシューティングページへ更新しています。

@@ -26,7 +26,7 @@ You can authenticate with any of these account types:

To log out and re-authenticate, type `/logout` at the Claude Code prompt.

If you're having trouble logging in, see [authentication troubleshooting](/en/troubleshooting#authentication-issues).

If you're having trouble logging in, see [authentication troubleshooting](/en/troubleshoot-install#login-and-authentication).

## Set up team authentication

cli-reference +3 -3

--init、--init-only、--maintenanceフラグの動作仕様と、フックとの連携方法が具体化されています。

@@ -66,13 +66,13 @@ Customize Claude Code's behavior with these command-line flags. `claude --help`

| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |

| `--from-pr` | Resume sessions linked to a specific pull request. Accepts a PR number, a GitHub or GitHub Enterprise PR URL, a GitLab merge request URL, or a Bitbucket pull request URL. Sessions are linked automatically when Claude creates the pull request | `claude --from-pr 123` |

| `--ide` | Automatically connect to IDE on startup if exactly one valid IDE is available | `claude --ide` |

| `--init` | Run initialization hooks and start interactive mode | `claude --init` |

| `--init-only` | Run initialization hooks and exit (no interactive session) | `claude --init-only` |

| `--init` | Run [Setup hooks](/en/hooks#setup) with the `init` matcher before the session (print mode only) | `claude -p --init "query"` |

| `--init-only` | Run [Setup](/en/hooks#setup) and `SessionStart` hooks, then exit without starting a conversation | `claude --init-only` |

| `--include-hook-events` | Include all hook lifecycle events in the output stream. Requires `--output-format stream-json` | `claude -p --output-format stream-json --include-hook-events "query"` |

| `--include-partial-messages` | Include partial streaming events in output. Requires `--print` and `--output-format stream-json` | `claude -p --output-format stream-json --include-partial-messages "query"` |

| `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |

| `--json-schema` | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [structured outputs](/en/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

| `--maintenance` | Run maintenance hooks and start interactive mode | `claude --maintenance` |

| `--maintenance` | Run [Setup hooks](/en/hooks#setup) with the `maintenance` matcher before the session (print mode only) | `claude -p --maintenance "query"` |

| `--max-budget-usd` | Maximum dollar amount to spend on API calls before stopping (print mode only) | `claude -p --max-budget-usd 5.00 "query"` |

| `--max-turns` | Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default | `claude -p --max-turns 3 "query"` |

| `--mcp-config` | Load MCP servers from JSON files or strings (space-separated) | `claude --mcp-config ./mcp.json` |

commands +1 -1

/heapdumpコマンドの出力先について、デスクトップフォルダがないLinux環境での動作説明が追加されました。

@@ -46,7 +46,7 @@ In the table below, `<arg>` indicates a required argument and `[arg]` indicates

| `/feedback [report]` | Submit feedback about Claude Code. Alias: `/bug` |

| `/fewer-permission-prompts` | **[Skill](/en/skills#bundled-skills).** Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project `.claude/settings.json` to reduce permission prompts |

| `/focus` | Toggle the focus view, which shows only your last prompt, a one-line tool-call summary with edit diffstats, and the final response. The selection persists across sessions. Only available in [fullscreen rendering](/en/fullscreen) |

| `/heapdump` | Write a JavaScript heap snapshot and a memory breakdown to `~/Desktop` for diagnosing high memory usage. See [troubleshooting](/en/troubleshooting#high-cpu-or-memory-usage) |

| `/heapdump` | Write a JavaScript heap snapshot and a memory breakdown to `~/Desktop`, or your home directory on Linux without a Desktop folder, for diagnosing high memory usage. See [troubleshooting](/en/troubleshooting#high-cpu-or-memory-usage) |

| `/help` | Show help and available commands |

| `/hooks` | View [hook](/en/hooks) configurations for tool events |

| `/ide` | Manage IDE integrations and show status |

common-workflows +3 -1

MCPサーバーがフォームを開く際のイベント(elicitation_dialog)など、より詳細なワークフローの状態が追加されています。

@@ -710,7 +710,9 @@ By default the hook fires on all notification types. To fire only for specific e

| `permission_prompt` | Claude needs you to approve a tool use |

| `idle_prompt` | Claude is done and waiting for your next prompt |

| `auth_success` | Authentication completes |

| `elicitation_dialog` | Claude is asking you a question |

| `elicitation_dialog` | An MCP server opens an elicitation form |

| `elicitation_complete` | An MCP elicitation form is submitted or dismissed |

| `elicitation_response` | An MCP elicitation response is sent back to the server |

Type `/hooks` and select `Notification` to confirm the hook appears. Selecting it shows the command that will run. To test it end-to-end, ask Claude to run a command that requires permission and switch away from the terminal, or ask Claude to trigger a notification directly.

debug-your-config +4 -3

設定デバッグ時の参照先を整理し、インストール関連とパフォーマンス関連で案内するページを分けています。

@@ -9,7 +9,7 @@ source: https://code.claude.com/docs/en/debug-your-config.md

When Claude ignores an instruction or a feature you configured doesn't appear, the cause is usually that the file didn't load, it loaded from a different location than you expected, or another file overrode it. This guide shows how to inspect what Claude Code actually loaded so you can narrow down which applies.

For installation, authentication, and connectivity problems, see [Troubleshooting](/en/troubleshooting) instead.

For installation, authentication, and connectivity problems, see [Troubleshoot installation and login](/en/troubleshoot-install) instead.

## See what loaded into context

@@ -77,7 +77,7 @@ Most configuration surprises trace back to a small set of location and syntax ru

| Skill appears in `/skills` but Claude never invokes it | Skill has `disable-model-invocation: true` in its frontmatter, or its description doesn't match how you phrase the request | Check the badge in `/skills`: a "user-only" label means Claude won't trigger it on its own. See [skill invocation](/en/skills). |

| Subdirectory `CLAUDE.md` instructions seem ignored | Subdirectory files load on demand, not at session start | They load when Claude reads a file in that directory with the Read tool, not at launch and not when writing or creating files there. See [how CLAUDE.md files load](/en/memory#how-claude-md-files-load). |

| Subagent ignores `CLAUDE.md` instructions | Subagents don't always inherit project memory | Put critical rules in the agent file body, which becomes the subagent's system prompt. See [subagent configuration](/en/sub-agents). |

| Cleanup logic never runs at session end | No `SessionEnd` hook configured | `SessionStart` and `SessionEnd` both exist. See the [hook events list](/en/hooks#hook-events). |

| Cleanup logic never runs at session end | No `SessionEnd` hook configured | Add a `SessionEnd` hook in `settings.json`. See the [hook events list](/en/hooks#hook-events). |

| MCP servers in `.mcp.json` never load | File is under `.claude/` or uses Claude Desktop's config format | Project MCP config goes at the repository root as `.mcp.json`, not inside `.claude/`. See [MCP configuration](/en/mcp). |

| Project MCP server added but doesn't appear | The one-time approval prompt was dismissed | Project-scoped servers require approval. Run `/mcp` to see status and approve. |

| MCP server fails to start from some directories | `command` or `args` uses a relative file path | Use absolute paths for local scripts. Executables on your `PATH` like `npx` or `uvx` work as-is. |

@@ -92,4 +92,5 @@ For full reference on each configuration surface, see the dedicated page:

- **[Settings](/en/settings)**: precedence order and the full key list

- **[Hooks reference](/en/hooks)**: event names, payloads, and `--debug hooks` output format

- **[MCP](/en/mcp)**: server configuration, approval, and `/mcp` output

- **[Troubleshooting](/en/troubleshooting)**: `claude doctor`, platform issues, and installation problems

- **[Troubleshoot installation and login](/en/troubleshoot-install)**: `command not found`, PATH, and authentication problems

- **[Troubleshooting](/en/troubleshooting)**: performance, hangs, and search issues

env-vars +5 -1

APIリクエストへのカスタムJSONマージや、MCPサーバーの環境変数分離など、4つの新しい環境変数が追加されています。

@@ -83,6 +83,7 @@ Claude Code supports the following environment variables to control its behavior

| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_FEEDBACK_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |

| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Set to `1` to disable the non-streaming fallback when a streaming request fails mid-stream. Streaming errors propagate to the retry layer instead. Useful when a proxy or gateway causes the fallback to produce duplicate tool execution |

| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | Set to `1` to skip automatic addition of the official plugin marketplace on first run |

| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Set to `1` to skip loading skills from the system-wide managed skills directory. Useful for container or CI sessions that should not load operator-provisioned skills |

| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |

| `CLAUDE_CODE_DISABLE_THINKING` | Set to `1` to force-disable [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) regardless of model support or other settings. More direct than `MAX_THINKING_TOKENS=0` |

| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Set to `1` to disable virtual scrolling in [fullscreen rendering](/en/fullscreen) and render every message in the transcript. Use this if scrolling in fullscreen mode shows blank regions where messages should appear |

@@ -95,6 +96,7 @@ Claude Code supports the following environment variables to control its behavior

| `CLAUDE_CODE_ENABLE_TELEMETRY` | Set to `1` to enable OpenTelemetry data collection for metrics and logging. Required before configuring OTel exporters. See [Monitoring](/en/monitoring-usage) |

| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Time in milliseconds to wait after the query loop becomes idle before automatically exiting. Useful for automated workflows and scripts using SDK mode |

| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Set to `1` to enable [agent teams](/en/agent-teams). Agent teams are experimental and disabled by default |

| `CLAUDE_CODE_EXTRA_BODY` | JSON object to merge into the top level of every API request body. Useful for passing provider-specific parameters that Claude Code does not expose directly |

| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads. Useful when you need to read larger files in full |

| `CLAUDE_CODE_FORK_SUBAGENT` | Set to `1` to enable [forked subagents](/en/sub-agents#fork-the-current-conversation). A forked subagent inherits the full conversation context from the main session instead of starting fresh. When enabled, `/fork` spawns a forked subagent rather than acting as an alias for [`/branch`](/en/commands), and all subagent spawns run in the background. Works in interactive mode and via the SDK or `claude -p` |

| `CLAUDE_CODE_GIT_BASH_PATH` | Windows only: path to the Git Bash executable (`bash.exe`). Use when Git Bash is installed but not in your PATH. See [Windows setup](/en/setup#set-up-on-windows) |

@@ -109,6 +111,7 @@ Claude Code supports the following environment variables to control its behavior

| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests. Defaults and caps vary by model; see [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Increasing this value reduces the effective context window available before [auto-compaction](/en/costs#reduce-token-usage) triggers. |

| `CLAUDE_CODE_MAX_RETRIES` | Override the number of times to retry failed API requests (default: 10) |

| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Maximum number of read-only tools and subagents that can execute in parallel (default: 10). Higher values increase parallelism but consume more resources |

| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Set to `1` to spawn stdio MCP servers with only a safe baseline environment plus the server's configured `env`, instead of inheriting your shell environment |

| `CLAUDE_CODE_NEW_INIT` | Set to `1` to make `/init` run an interactive setup flow. The flow asks which files to generate, including CLAUDE.md, skills, and hooks, before exploring the codebase and writing them. Without this variable, `/init` generates a CLAUDE.md automatically without prompting. |

| `CLAUDE_CODE_NO_FLICKER` | Set to `1` to enable [fullscreen rendering](/en/fullscreen), a research preview that reduces flicker and keeps memory flat in long conversations. Equivalent to the [`tui`](/en/settings#available-settings) setting; you can also switch with `/tui fullscreen` |

| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | OAuth refresh token for Claude.ai authentication. When set, `claude auth login` exchanges this token directly instead of opening a browser. Requires `CLAUDE_CODE_OAUTH_SCOPES`. Useful for provisioning authentication in automated environments |

@@ -150,12 +153,13 @@ Claude Code supports the following environment variables to control its behavior

| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/en/amazon-bedrock) |

| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) |

| `CLAUDE_CODE_USE_MANTLE` | Use the Bedrock [Mantle endpoint](/en/amazon-bedrock#use-the-mantle-endpoint) |

| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | Set to `1` to discover custom commands, subagents, and output styles using Node.js file APIs instead of ripgrep. Set this if the bundled ripgrep binary is unavailable or blocked in your environment. Does not affect the Grep or file search tools |

| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Controls the PowerShell tool. On Windows, the tool is rolling out progressively: set to `1` to opt in or `0` to opt out. On Linux, macOS, and WSL, set to `1` to enable it, which requires `pwsh` on your `PATH`. When enabled on Windows, Claude can run PowerShell commands natively instead of routing through Git Bash. See [PowerShell tool](/en/tools-reference#powershell-tool) |

| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/google-vertex-ai) |

| `CLAUDE_CONFIG_DIR` | Override the configuration directory (default: `~/.claude`). All settings, credentials, session history, and plugins are stored under this path. Useful for running multiple accounts side by side: for example, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Set to `1` to force-enable the byte-level streaming idle watchdog, or set to `0` to force-disable it. When unset, the watchdog is enabled by default for Anthropic API connections. The byte watchdog aborts a connection when no bytes arrive on the wire for the duration set by `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, with a minimum of 5 minutes, independent of the event-level watchdog |

| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Set to `1` to enable the event-level streaming idle watchdog. Off by default. For Bedrock, Vertex, and Foundry, this is the only idle watchdog available. Configure the timeout with `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |

| `CLAUDE_ENV_FILE` | Path to a shell script whose contents Claude Code runs before each Bash command in the same shell process, so exports in the file are visible to the command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart](/en/hooks#persist-environment-variables), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |

| `CLAUDE_ENV_FILE` | Path to a shell script whose contents Claude Code runs before each Bash command in the same shell process, so exports in the file are visible to the command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart](/en/hooks#persist-environment-variables), [Setup](/en/hooks#setup), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |

| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefix for auto-generated [Remote Control](/en/remote-control) session names when no explicit name is provided. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. The `--remote-control-session-name-prefix` CLI flag sets the same value for a single invocation |

| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Timeout in milliseconds before the streaming idle watchdog closes a stalled connection. For the byte-level watchdog on the Anthropic API: default and minimum `300000` (5 minutes); lower values are silently clamped to absorb extended thinking pauses and proxy buffering. For the event-level watchdog: default `90000` (90 seconds), no minimum. For third-party providers, requires `CLAUDE_ENABLE_STREAM_WATCHDOG=1` |

| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic background updates. Manual `claude update` still works. Use `DISABLE_UPDATES` to block both |

errors +7 -6

モデルが見つからない場合の優先順位の明示や、Vertex AI向けのトラブルシューティング案内が追加されました。

@@ -7,7 +7,7 @@ source: https://code.claude.com/docs/en/errors.md

> Look up Claude Code runtime error messages with what each one means and how to fix it.

This page lists runtime errors Claude Code displays and how to recover from each one, plus what to check when responses seem off without an error. For installation errors such as `command not found` or TLS failures during setup, see [Troubleshooting](/en/troubleshooting).

These errors and recovery commands apply across the CLI, the [Desktop app](/en/desktop), and [Claude Code on the web](/en/claude-code-on-the-web), since all three wrap the same Claude Code CLI. For surface-specific issues, see the troubleshooting section on that surface's page.

@@ -215,7 +215,7 @@ Not logged in · Please run /login

- For CI or automation where interactive login is not possible, configure an [`apiKeyHelper`](/en/settings#available-settings) script that fetches a key at startup

- See [Authentication precedence](/en/authentication#authentication-precedence) to understand which credential wins when several are present

If you are prompted to log in repeatedly, see [Not logged in or token expired](/en/troubleshooting#not-logged-in-or-token-expired) for system clock and macOS Keychain fixes.

If you are prompted to log in repeatedly, see [Not logged in or token expired](/en/troubleshoot-install#not-logged-in-or-token-expired) for system clock and macOS Keychain fixes.

### Invalid API key

@@ -264,8 +264,8 @@ API Error: 401 ... authentication_error

- Run `/login` to sign in again

- If the error returns within the same session after re-authenticating, run `/logout` first to fully clear the stored token, then `/login`

- For repeated prompts to log in across launches, see the system clock and macOS Keychain checks in [Troubleshooting](/en/troubleshooting#not-logged-in-or-token-expired)

- For other failures including `403 Forbidden` and OAuth browser issues, see [Permissions and authentication](/en/troubleshooting#permissions-and-authentication)

- For repeated prompts to log in across launches, see the system clock and macOS Keychain checks in [Troubleshooting](/en/troubleshoot-install#not-logged-in-or-token-expired)

- For other failures including `403 Forbidden` and OAuth browser issues, see [Login and authentication](/en/troubleshoot-install#login-and-authentication)

### OAuth scope requirement

@@ -442,7 +442,8 @@ There's an issue with the selected model (claude-...). It may not exist or you m

- Run `/model` to pick from models available to your account

- Use an alias such as `sonnet` or `opus` instead of a full versioned ID. Aliases track the latest release so they do not go stale. See [Model configuration](/en/model-config).

- See [Model not found](/en/troubleshooting#model-not-found-or-not-accessible) to locate where a stale ID is set across `--model`, `ANTHROPIC_MODEL`, and settings files

- If the wrong model keeps coming back, a stale ID is set somewhere. Check in [priority order](/en/model-config#setting-your-model): the `--model` flag, the `ANTHROPIC_MODEL` environment variable, then the `model` field in `.claude/settings.local.json`, your project's `.claude/settings.json`, and `~/.claude/settings.json`. Remove the stale value and Claude Code falls back to your account default.

- For Vertex AI deployments, see [Vertex AI troubleshooting](/en/google-vertex-ai#troubleshooting).

### Claude Opus is not available with the Claude Pro plan

@@ -524,7 +525,7 @@ This page covers errors from the Claude API. For errors from other Claude Code c

- MCP server failed to connect or authenticate: [MCP](/en/mcp)

- Hook script failed or blocked a tool: [Debug hooks](/en/hooks#debug-hooks)

- Permission denied or filesystem errors during install: [Troubleshooting](/en/troubleshooting)

- Permission denied or filesystem errors during install: [Troubleshoot installation and login](/en/troubleshoot-install)

If an error is not listed here or the suggested fix does not help:

fullscreen +1 -1

iTerm2でクリップボードアクセスを自動有効化するための/terminal-setupコマンドの案内が追加されています。

@@ -131,7 +131,7 @@ Fullscreen rendering is incompatible with iTerm2's tmux integration mode, which

Mouse capture is the most common friction point, especially over SSH or inside tmux. When Claude Code captures mouse events, your terminal's native copy-on-select stops working. The selection you make with click-and-drag exists inside Claude Code, not in your terminal's selection buffer, so tmux copy mode, Kitty hints, and similar tools don't see it.

Claude Code tries to write the selection to your clipboard, but the path it uses depends on your setup. Inside tmux it writes to the tmux paste buffer. Over SSH it falls back to OSC 52 escape sequences, which some terminals block by default. iTerm2 blocks them until you turn on Settings → General → Selection → Applications in terminal may access clipboard. Claude Code prints a toast after each copy telling you which path it used.

Claude Code tries to write the selection to your clipboard, but the path it uses depends on your setup. Inside tmux it writes to the tmux paste buffer. Over SSH it falls back to OSC 52 escape sequences, which some terminals block by default. iTerm2 blocks them until you turn on Settings → General → Selection → Applications in terminal may access clipboard. Running [`/terminal-setup`](/en/terminal-config) in iTerm2 enables this for you. Claude Code prints a toast after each copy telling you which path it used.

For a one-off native selection, hold your terminal's bypass modifier while you click and drag: `Option` in iTerm2, or `Shift` in most Linux and Windows terminals. The modifier tells your terminal to handle the selection itself instead of forwarding mouse events to Claude Code, so `Cmd+C` and your terminal's other copy shortcuts work on it.

hooks-guide +7 -3

Setupフックの導入に伴い、イベントの種類やサブエージェントの名称、終了コード2の挙動に関する説明が更新されました。

@@ -395,6 +395,7 @@ Hook events fire at specific lifecycle points in Claude Code. When an event fire

| Event | When it fires |

| :- | :- |

| `SessionStart` | When a session begins or resumes |

| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |

| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

| `PreToolUse` | Before a tool call executes. Can block it |

@@ -474,7 +475,7 @@ exit 0 # exit 0 = let it proceed

The exit code determines what happens next:

- **Exit 0**: the action proceeds. For `UserPromptSubmit`, `UserPromptExpansion`, and `SessionStart` hooks, anything you write to stdout is added to Claude's context.

- **Exit 2**: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust.

- **Exit 2**: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust. Some events cannot be blocked: for `SessionStart`, `Setup`, `Notification`, and others, exit 2 shows stderr to the user and execution continues. See [exit code 2 behavior per event](/en/hooks#exit-code-2-behavior-per-event) for the full list.

- **Any other exit code**: the action proceeds. The transcript shows a `<hook name> hook error` notice followed by the first line of stderr; the full stderr goes to the [debug log](/en/hooks#debug-hooks).

#### Structured JSON output

@@ -530,15 +531,18 @@ Without a matcher, a hook fires on every occurrence of its event. Matchers let y

The `"Edit|Write"` matcher fires only when Claude uses the `Edit` or `Write` tool, not when it uses `Bash`, `Read`, or any other tool. See [Matcher patterns](/en/hooks#matcher-patterns) for how plain names and regular expressions are evaluated.

Claude can also create or modify files by running shell commands through the `Bash` tool. If your hook must see every file change, such as for compliance scanning or audit logging, add a [`Stop`](/en/hooks#stop) hook that scans the working tree once per turn. For per-call coverage instead, also match `Bash` and have your script list modified and untracked files with `git status --porcelain`.

Each event type matches on a specific field:

| Event | What the matcher filters | Example matcher values |

| :- | :- | :- |

| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact` |

| `Setup` | which CLI flag triggered setup | `init`, `maintenance` |

| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |

| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` |

| `SubagentStart` | agent type | `Bash`, `Explore`, `Plan`, or custom agent names |

| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response` |

| `SubagentStart` | agent type | `general-purpose`, `Explore`, `Plan`, or custom agent names |

| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` |

| `SubagentStop` | agent type | same values as `SubagentStart` |

| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |

hooks +58 -7

Setupフックの詳細な仕様、matcherの設定値、およびJSON形式の入出力例が詳しく解説されています。

@@ -20,6 +20,7 @@ The table below summarizes when each event fires. The [Hook events](#hook-events