2026年7月21日 09:26

22 ファイル変更+370-67

この更新の概要

Agent SDKにおけるPythonおよびTypeScriptのサポートが強化され、SDKにClaude Codeバイナリが同梱されるようになりました。ツール検索（Tool Search）機能がデフォルトで有効化され、多数のツールを定義する際のコンテキスト消費を抑制できるよう改善されています。OpenTelemetryの属性長制限（CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH）や、サブプロセスを識別するための環境変数（CLAUDE_PID）など、新しい設定オプションが追加されました。

agent-sdk/agent-loop+1-1

autoモードにおいて、個々のツール実行ではなく許可プロンプトをモデル分類器で判断する旨の記述に変更されています。

@@ -205,7 +205,7 @@ The permission mode option (`permission_mode` in Python, `permissionMode` in Typ

| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules |

| `"plan"` | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback |

| `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/en/settings#permission-settings) run; everything else is denied. `AskUserQuestion`, connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and MCP tools marked [`requiresUserInteraction`](/en/mcp#require-approval-for-a-specific-tool) are denied even if you've allowed them |

| `"auto"` | Uses a model classifier to approve or deny each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior |

| `"auto"` | Uses a model classifier to approve or deny permission prompts. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior |

| `"bypassPermissions"` | Runs all allowed tools without asking, except tools matched by an explicit [`ask` rule](/en/settings#permission-settings), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction; see [How permissions are evaluated](/en/agent-sdk/permissions#how-permissions-are-evaluated) for the precedence order. Cannot be used when running as root on Unix. Use only in isolated environments where the agent's actions cannot affect systems you care about |

For interactive applications, use `"default"` with a tool approval callback to surface approval prompts. For autonomous agents on a dev machine, `"acceptEdits"` auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) while still gating other `Bash` commands behind allow rules. Reserve `"bypassPermissions"` for CI, containers, or other isolated environments. See [Permissions](/en/agent-sdk/permissions) for full details.

agent-sdk/custom-tools+8-2

ツール検索機能がデフォルトで有効になったことや、特定のツールの全スキーマを常に読み込むためのalwaysLoadオプションの詳細が追記されています。

@@ -167,11 +167,13 @@ for await (const message of query({

}

```

Combine this snippet with the tool and server definitions from the [weather tool example](#weather-tool-example) in one file, then run it with `python weather.py` for Python or `npx tsx weather.ts` for TypeScript. Claude calls `get_temperature` and the script prints a one-line answer with the current temperature in San Francisco.

### Add more tools

A server holds as many tools as you list in its `tools` array. With more than one tool on a server, you can list each one in `allowedTools` individually or use the wildcard `mcp__weather__*` to cover every tool the server exposes.

The example below adds a second tool, `get_precipitation_chance`, to the `weatherServer` from the [weather tool example](#weather-tool-example) and rebuilds it with both tools in the array.

The example below defines a second tool, `get_precipitation_chance`, and replaces the `weatherServer` definition from the [weather tool example](#weather-tool-example) with one that lists both tools in the array.

```python Python theme={null}

# Define a second tool for the same server

@@ -251,7 +253,7 @@ const weatherServer = createSdkMcpServer({

});

```

Every tool in this array consumes context window space on every turn. If you're defining dozens of tools, see [tool search](/en/agent-sdk/tool-search) to load them on demand instead.

[Tool search](/en/agent-sdk/tool-search) is on by default and defers SDK MCP tools: Claude sees each tool's name in a compact list and loads its full schema on demand. With tool search disabled, every tool in this array consumes context window space on every turn. In TypeScript, pass `alwaysLoad: true` in the `extras` argument of [`tool()`](/en/agent-sdk/typescript#tool) or in the options of [`createSdkMcpServer()`](/en/agent-sdk/typescript#createsdkmcpserver) to keep a tool's full schema in the initial prompt.

### Add tool annotations

@@ -339,6 +341,7 @@ The example below catches two kinds of failures inside the handler and composes

import json

import httpx

from typing import Any

from claude_agent_sdk import tool

@@ -446,6 +449,7 @@ An image block carries the image bytes inline, encoded as base64. There is no UR

```python Python theme={null}

import base64

import httpx

from claude_agent_sdk import tool

@@ -733,6 +737,8 @@ const converterServer = createSdkMcpServer({

Once the server is defined, pass it to `query` the same way as the weather example. This example sends three different prompts in a loop to show the same tool handling different unit types. For each response, it inspects `AssistantMessage` objects (which contain the tool calls Claude made during that turn) and prints each `ToolUseBlock` before printing the final `ResultMessage` text. This lets you see when Claude is using the tool versus answering from its own knowledge.

Because [tool search](/en/agent-sdk/tool-search) is on by default, the output may also include a `ToolSearch` call as Claude loads the deferred tool schema.

```python Python theme={null}

import asyncio

from claude_agent_sdk import (

agent-sdk/overview+36-7

Python SDKにもClaude Codeバイナリが同梱されるようになった点や、TypeScriptプロジェクトの初期化手順が具体的に記載されています。

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

> Build production AI agents with Claude Code as a library

Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript. For other languages, [run the CLI programmatically](/en/headless) with the `-p` flag and `--output-format json`. For the thinking behind agent harness design, see [A harness for every task: dynamic workflows in Claude Code](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code) on the blog.

```python Python theme={null}

import asyncio

@@ -43,9 +43,14 @@ Email assistant, research agent, and more

## Get started

```bash theme={null}

npm init -y

npm pkg set type=module

npm install @anthropic-ai/claude-agent-sdk

npm install --save-dev tsx

```

Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly. In an existing CommonJS project, skip the first two commands and name your script `agent.mts` instead of `agent.ts`.

[uv](https://docs.astral.sh/uv/) is a fast Python package manager that handles virtual environments automatically:

```bash theme={null}

@@ -75,7 +80,7 @@ If PowerShell blocks `Activate.ps1` with an execution policy error, run `Set-Exe

The Python package requires Python 3.10 or later. If pip reports `No matching distribution found for claude-agent-sdk`, your interpreter is older than 3.10. Run `python3 --version` on macOS or Linux, or `py --version` on Windows, to check.

The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately.

Both the TypeScript and Python SDKs bundle a native Claude Code binary for your platform, so you don't need to install Claude Code separately.

Get an API key from the [Console](https://platform.claude.com/), then set it as an environment variable.

@@ -130,6 +135,26 @@ for await (const message of query({

}

```

Save the example as `agent.py` or `agent.ts`, then run it. The agent prints a short summary of the files in the directory.

```bash theme={null}

npx tsx agent.ts

```

If you named your script `agent.mts` for a CommonJS project, run `npx tsx agent.mts` instead.

```bash theme={null}

uv run agent.py

```

With the virtual environment activated, on macOS or Linux:

```bash theme={null}

python3 agent.py

```

On Windows, run `python agent.py`.

**Ready to build?** Follow the [Quickstart](/en/agent-sdk/quickstart) to create an agent that finds and fixes bugs in minutes.

## Capabilities

@@ -200,7 +225,7 @@ async def log_file_change(input_data, tool_use_id, context):

async def main():

async for message in query(

prompt="Refactor utils.py to improve readability",

prompt="Create a file named hello.py that prints a greeting",

options=ClaudeAgentOptions(

allowed_tools=["Read", "Edit"],

permission_mode="acceptEdits",

@@ -228,7 +253,7 @@ const logFileChange: HookCallback = async (input) => {

};

for await (const message of query({

prompt: "Refactor utils.py to improve readability",

prompt: "Create a file named hello.ts that prints a greeting",

options: {

allowedTools: ["Read", "Edit"],

permissionMode: "acceptEdits",

@@ -241,6 +266,8 @@ for await (const message of query({

}

```

After the agent finishes, run `cat audit.log` to see the recorded file changes.

[Learn more about hooks →](/en/agent-sdk/hooks)

Spawn specialized agents to handle focused subtasks. Your main agent delegates work, and subagents report back with results.

@@ -309,7 +336,8 @@ async def main():

options=ClaudeAgentOptions(

mcp_servers={

"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}

}

allowed_tools=["mcp__playwright__*"],

if hasattr(message, "result"):

@@ -326,7 +354,8 @@ for await (const message of query({

options: {

mcpServers: {

playwright: { command: "npx", args: ["@playwright/mcp@latest"] }

}

allowedTools: ["mcp__playwright__*"]

}

})) {

if ("result" in message) console.log(message.result);

@@ -460,7 +489,7 @@ The Claude Platform offers multiple ways to build with Claude. Here's how the Ag

The [Anthropic Client SDK](https://platform.claude.com/docs/en/api/client-sdks) gives you direct API access: you send prompts and implement tool execution yourself. The **Agent SDK** gives you Claude with built-in tool execution.

With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it:

With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it. This simplified pseudocode shows the difference:

```python Python theme={null}

# Client SDK: You implement the tool loop

agent-sdk/permissions+1-1

autoモードの判定対象が許可プロンプト（permission prompts）であることを明示するように修正されました。

@@ -94,7 +94,7 @@ The SDK supports these permission modes:

| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved |

| `bypassPermissions` | Bypass permission checks | Tools run without permission prompts, except tools matched by an explicit [`ask` rule](#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction (use with caution) |

| `plan` | Planning mode | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback |

| `auto` | Model-classified approvals | A model classifier approves or denies each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability |

| `auto` | Model-classified approvals | A model classifier approves or denies permission prompts. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability |

**Subagent inheritance:** Subagents inherit the parent session's permission mode. An [`AgentDefinition`'s `permissionMode`](/en/agent-sdk/typescript#agentdefinition) can override it, except when the parent uses `bypassPermissions`, `acceptEdits`, or `auto`: those modes apply to every subagent and can't be overridden per subagent.

agent-sdk/python+20-6

モデル切り替え履歴を保持するmodelsUsedフィールドの追加や、非推奨となった設定項目の注釈、ダイアログの新しい注釈プロパティが定義されています。

@@ -2393,9 +2393,10 @@ Documentation of input/output schemas for all built-in Claude Code tools. While

"prompt": str, # The task for the agent to perform

"subagent_type": str | None, # The type of specialized agent to use

"model": "sonnet" | "opus" | "haiku" | "fable" | None, # Model override for this agent

"run_in_background": bool | None, # Launch the agent in the background

"run_in_background": bool | None, # Agents run in the background by default; set to False to run synchronously

"name": str | None, # Name for the spawned agent

"team_name": str | None, # Deprecated; ignored

"isolation": "worktree" | "remote" | None, # Isolation mode for the agent's changes

}

```

@@ -2416,7 +2417,8 @@ Launches a new agent to handle complex, multi-step tasks autonomously.

"citations": list | None,

}

"resolvedModel": str | None, # Model the subagent actually ran on

"resolvedModel": str | None, # Model the subagent started on

"modelsUsed": list[str] | None, # Models used in order, with consecutive repeats collapsed

"totalToolUseCount": int, # Number of tool calls the agent made

"totalDurationMs": int, # Execution duration in milliseconds

"totalTokens": int, # Total tokens used

@@ -2456,7 +2458,8 @@ Launches a new agent to handle complex, multi-step tasks autonomously.

"isAsync": bool | None, # True on background launches

"agentId": str, # ID of the launched agent

"description": str, # The task description

"resolvedModel": str | None, # Model the subagent runs on

"resolvedModel": str | None, # Model in use at the backgrounding transition

"modelsUsed": list[str] | None, # Models used before backgrounding, in order, with consecutive repeats collapsed

"prompt": str, # The prompt the agent runs

"outputFile": str, # File path where the agent's output is written

"canReadOutputFile": bool | None, # Whether the output file can be read directly

@@ -2478,7 +2481,7 @@ Launches a new agent to handle complex, multi-step tasks autonomously.

Returns the result from the subagent. The output is discriminated on the `status` field: `"completed"` for finished tasks, `"async_launched"` for background tasks, and `"remote_launched"` for tasks Claude Code dispatched to a remote cloud session, where `sessionUrl` links to that session and `taskId` identifies it. Worktree-isolated runs include `worktreePath` and `worktreeBranch` on the `completed` variant.

The `resolvedModel` field on the `completed` and `async_launched` variants names the model the subagent actually ran on, which can differ from the requested `model` input when [`availableModels`](/en/model-config#restrict-model-selection) or another override applies. This field requires Claude Code v2.1.174 or later.

On the `completed` variant, `resolvedModel` names the model the subagent started on, which can differ from the requested `model` input when [`availableModels`](/en/model-config#restrict-model-selection) or another override applies. This field requires Claude Code v2.1.174 or later. On the `async_launched` variant, `resolvedModel` names the model in use when the agent moved to the background, so a swap that happened before backgrounding is reflected there. The `modelsUsed` field on both variants lists the models used in order, with consecutive repeats collapsed; it's set only when the model was swapped mid-run. `modelsUsed` and the backgrounding-time `resolvedModel` behavior require Claude Code v2.1.212 or later.

### AskUserQuestion

@@ -2498,6 +2501,7 @@ Asks the user clarifying questions during execution. See [Handle approvals and u

{

"label": str, # Display text for this option (1-5 words)

"description": str, # Explanation of what this option means

"preview": str | None, # Preview content rendered when the option is focused

}

"multiSelect": bool, # Set to true to allow multiple selections

@@ -2507,6 +2511,11 @@ Asks the user clarifying questions during execution. See [Handle approvals and u

# User answers populated by the permission system. Multi-select

# answers are a comma-joined string of the selected labels; a

# list of labels is accepted on input and coerced to that form

"annotations": dict[str, dict] | None,

# Per-question annotations from the user, keyed by question text.

# Each value can carry "preview" (the selected option's preview

# content) and "notes" (free-text notes on the selection)

"metadata": dict | None, # Analytics metadata, such as {"source": "remember"}; not displayed to the user

}

```

@@ -2518,12 +2527,17 @@ Asks the user clarifying questions during execution. See [Handle approvals and u

{

"question": str,

"header": str,

"options": [{"label": str, "description": str}],

"options": [{"label": str, "description": str, "preview": str | None}],

"multiSelect": bool,

}

"answers": dict[str, str], # Maps question text to answer string

# Multi-select answers are comma-separated

"response": str | None,

# Freeform reply typed instead of answering the questions; when set,

# Claude receives "The user responded: ..." in place of the answer list

"annotations": dict[str, dict] | None, # Per-question "preview" and "notes" from the user's selections

"afkTimeoutMs": int | None, # Set when the dialog auto-resolved after this many milliseconds of user inactivity; absent when the user answered

}

```

agent-sdk/quickstart+2-2

両方のSDKにバイナリが同梱される点と、autoモードの動作説明の表現が更新されています。

@@ -76,7 +76,7 @@ pip install claude-agent-sdk

If PowerShell blocks `Activate.ps1` with an execution policy error, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first.

The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately.

Both the TypeScript and Python SDKs bundle a native Claude Code binary for your platform, so you don't need to install Claude Code separately.

Get an API key from the [Claude Console](https://platform.claude.com/), then set it as an environment variable in the shell where you'll run your agent:

@@ -306,7 +306,7 @@ With `Bash` enabled, try: `"Write unit tests for utils.py, run them, and fix any

| `acceptEdits` | Auto-approves file edits and common filesystem commands, asks for other actions | Trusted development workflows |

| `plan` | Runs read-only tools; file edits are never auto-approved and reach your `canUseTool` callback | Scoping a task before approving execution |

| `dontAsk` | Denies anything not in `allowedTools`; connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools) and tools that require user interaction are denied even if you've listed them | Locked-down headless agents |

| `auto` | A model classifier approves or denies each tool call | Autonomous agents with safety guardrails |

| `auto` | A model classifier approves or denies permission prompts | Autonomous agents with safety guardrails |

| `bypassPermissions` | Runs every tool without prompting, except tools matched by an explicit [`ask` rule](/en/agent-sdk/permissions#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction. In the TypeScript SDK, also requires `allowDangerouslySkipPermissions: true` in `options` | Sandboxed CI, fully trusted environments |

| `default` | Requires a `canUseTool` callback to handle approval | Custom approval flows |

agent-sdk/typescript+6-2

tool定義やMCPサーバー設定におけるsearchHintおよびalwaysLoadオプションの定義が追加されました。

@@ -120,7 +120,7 @@ function tool<Schema extends AnyZodRawShape>(

description: string,

inputSchema: Schema,

handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,

extras?: { annotations?: ToolAnnotations }

extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }

): SdkMcpToolDefinition<Schema>;

```

@@ -132,7 +132,7 @@ function tool<Schema extends AnyZodRawShape>(

| `description` | `string` | A description of what the tool does |

| `inputSchema` | `Schema extends AnyZodRawShape` | Zod schema defining the tool's input parameters (supports both Zod 3 and Zod 4) |

| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Async function that executes the tool logic |

| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Optional MCP tool annotations providing behavioral hints to clients |

| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | Optional extras. `annotations` provides MCP behavioral hints to clients. `searchHint` is a one-line capability phrase shown in the deferred-tool list when [tool search](/en/agent-sdk/tool-search) is active. `alwaysLoad: true` keeps this tool's full schema in the initial prompt instead of deferring it |

#### `ToolAnnotations`

@@ -169,7 +169,9 @@ Creates an MCP server instance that runs in the same process as your application

function createSdkMcpServer(options: {

name: string;

version?: string;

instructions?: string;

tools?: Array<SdkMcpToolDefinition<any>>;

alwaysLoad?: boolean;

}): McpSdkServerConfigWithInstance;

```

@@ -179,7 +181,9 @@ function createSdkMcpServer(options: {

| :- | :- | :- |

| `options.name` | `string` | The name of the MCP server |

| `options.version` | `string` | Optional version string |

| `options.instructions` | `string` | Optional server instructions, returned from `initialize` and surfaced to the model as an MCP instructions block |

| `options.tools` | `Array<SdkMcpToolDefinition>` | Array of tool definitions created with [`tool()`](#tool) |

| `options.alwaysLoad` | `boolean` | When `true`, every tool from this server stays in the initial prompt and is never deferred behind [tool search](/en/agent-sdk/tool-search). Combines with per-tool `alwaysLoad` in [`tool()`](#tool) |

### `listSessions()`

agent-view+3-2

バックグラウンドセッションでMCP設定や認証が必要になった際の「Needs input」ステータスの挙動と履歴が詳述されています。

@@ -92,7 +92,7 @@ Each row starts with an icon whose color and animation show the session's state:

| State | Icon shows as | What it means |

| :- | :- | :- |

| Working | Animated | Claude is actively running tools or generating a response |

| Needs input | Yellow | Claude is waiting on something only you can provide: an answer to a question, a permission decision, a [sandbox](/en/sandboxing) prompt to allow a network host, an MCP server's [request for input](/en/mcp#respond-to-mcp-elicitation-requests), or a managed-settings prompt |

| Idle | Dimmed | The session has nothing to do and is ready for your next prompt |

| Completed | Green | The task finished successfully |

| Failed | Red | The task ended with an error |

@@ -173,7 +173,8 @@ Press `Enter` or `→` on a selected row to attach. Agent view is replaced by th

While attached, the session behaves like any other Claude Code session: [commands](/en/commands), keyboard shortcuts, and features all work, with the exceptions below.

A background session refuses `/install-github-app` and the [`/mcp`](/en/mcp) settings list, including its authentication actions, whether you're attached or replying from the peek panel. The message directs you to a regular `claude` session, and `/mcp reconnect <server>`, `/mcp enable`, and `/mcp disable` still work.

While you're attached, `/install-github-app` and the [`/mcp`](/en/mcp) settings list work normally, since a human at the terminal can complete their dialogs. When nobody is attached, these commands can't open their dialogs, so the session appears under `Needs input` in agent view with a row such as `open this session to manage MCP servers`, and the transcript reply says the same. Attach and run the command again to continue; the needs-input row clears when you attach. `/mcp reconnect <server>`, `/mcp enable`, and `/mcp disable` work without attaching either way.

Before v2.1.216, these commands were refused in a background session with a message telling you to attach and run the command again; from v2.1.208 through v2.1.212 they were refused even while a terminal was attached.

Attached sessions always render in [fullscreen mode](/en/fullscreen), regardless of your `tui` setting, because a background session has no terminal scrollback to append to. Scroll with `PgUp`, `PgDn`, or the mouse wheel, and press `Ctrl+O` for transcript mode. Your terminal's native scroll and tmux copy mode show only the current viewport, the same as when you run any fullscreen application.

claude-directory+1-1

インストールされたプラグインの古いバージョンが削除されるまでの猶予期間が7日から14日に変更されました。

@@ -25,7 +25,7 @@ The explorer covers files you author and edit. A few related files live elsewher

| - | - | - |

| `managed-settings.json` | System-level, varies by OS | Enterprise-enforced settings that you can't override. See [server-managed settings](/en/server-managed-settings). |

| `CLAUDE.local.md` | Project root | Your private preferences for this project, loaded alongside CLAUDE.md. Create it manually and add it to `.gitignore`. |

| Installed plugins | `~/.claude/plugins` | Cloned marketplaces, installed plugin versions, and per-plugin data, managed by `claude plugin` commands. Orphaned versions are deleted 7 days after a plugin update or uninstall. See [plugin caching](/en/plugins-reference#plugin-caching-and-file-resolution). |

| Installed plugins | `~/.claude/plugins` | Cloned marketplaces, installed plugin versions, and per-plugin data, managed by `claude plugin` commands. Orphaned versions are deleted 14 days after a plugin update or uninstall. See [plugin caching](/en/plugins-reference#plugin-caching-and-file-resolution). |

`~/.claude` also holds data Claude Code writes as you work: transcripts, prompt history, file snapshots, caches, and logs. See [application data](#application-data) below.

env-vars+4-1

テレメトリのコンテンツ最大長を制御する変数や、親プロセスIDを識別するCLAUDE_PIDなどの新しい環境変数が追加されています。

@@ -257,6 +257,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien

| `CLAUDE_CODE_OAUTH_SCOPES` | Space-separated OAuth scopes the refresh token was issued with, such as `"user:profile user:inference user:sessions:claude_code"`. Required when `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` is set |

| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth access token for Claude.ai authentication. Alternative to `/login` for SDK and automated environments. Takes precedence over keychain-stored credentials. Generate one with [`claude setup-token`](/en/authentication#generate-a-long-lived-token) |

| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | Removed in v2.1.160 and now a no-op. Previously pinned [fast mode](/en/fast-mode) to Claude Opus 4.6 instead of the current default. Opus 4.6 no longer supports fast mode |

| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | Maximum length of content-bearing OpenTelemetry attributes (model responses, tool content, system prompts, raw API bodies), truncation marker included, in UTF-16 code units (default: 61440, i.e. 60 KB). Raise it only if your telemetry backend accepts attribute values larger than 64 KB, or lower it to cut telemetry volume. Requires Claude Code v2.1.214 or later. See [Monitoring](/en/monitoring-usage) |

| `CLAUDE_CODE_OTEL_DIAG_STDERR` | Set to `1` to write OpenTelemetry exporter diagnostic errors to stderr. By default these errors only appear with `--debug`, so a misconfigured exporter such as a Prometheus port collision otherwise fails silently. Requires Claude Code v2.1.179 or later. See [Monitoring](/en/monitoring-usage) |

| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | Timeout in milliseconds for flushing pending OpenTelemetry spans (default: 5000). See [Monitoring](/en/monitoring-usage) |

| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) |

@@ -325,6 +326,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien

| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Set to `1` to enable the byte-level streaming idle watchdog on Amazon Bedrock `vnd.amazon.eventstream` responses. Off by default. Configure the timeout with `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |

| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Set to `0` to force-disable the event-level streaming idle watchdog, or set to `1` to force-enable it. When unset, the watchdog is on by default for all providers. Before v2.1.196, the unset default was server-controlled on the direct Anthropic API and off on other providers. As of v2.1.169, providers other than the direct Anthropic API and Claude Platform on AWS also have a default-on 5-minute body idle timeout independent of this variable; see `API_FORCE_IDLE_TIMEOUT`. On Amazon Bedrock, you can also enable the independent byte-level watchdog with `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`; the two run together when both are set. 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), [Setup](/en/hooks#setup), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |

| `CLAUDE_PID` | Claude Code sets this to its own process ID in the subprocesses it spawns: Bash and PowerShell tool commands and hook commands. On Linux, the Bash tool's shell integration uses it to refuse a `pkill` pattern that would match the Claude Code process itself; see [the error reference](/en/errors#pkill-pattern-matches-the-claude-code-process). Read it from your own scripts to identify or signal the parent Claude Code process deliberately. Requires Claude Code v2.1.214 or later |

| `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. When you set this variable explicitly, the minimum is `300000` (5 minutes); lower values are silently clamped to absorb extended thinking pauses and proxy buffering. When unset, the event-level watchdog defaults to 300 seconds and the byte-level watchdog defaults to 180 seconds on direct Anthropic API connections (300 seconds on Claude Platform on AWS and other providers). The unset 180-second byte-watchdog default is a separate value and is not subject to the 5-minute clamp. The body idle timeout described under `API_FORCE_IDLE_TIMEOUT` applies independently. On Amazon Bedrock, also applies when `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |

| `DEBUG` | Set to `1` to enable debug mode, equivalent to launching with [`--debug`](/en/cli-reference#cli-flags). Debug logs are written to `~/.claude/debug/<session-id>.txt`, or to the path set by `CLAUDE_CODE_DEBUG_LOGS_DIR`. Only the truthy values `1`, `true`, `yes`, and `on` enable debug mode, so namespace patterns like `DEBUG=express:*` set for other tools do not trigger it |

@@ -374,8 +376,9 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien

| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup (default: 30000, or 30 seconds) |

| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution (default: 100000000, about 28 hours). For an HTTP, SSE, or claude.ai connector server, each request also times out after 60 seconds by default; set this variable, or the per-server `timeout`, above 60000 to raise that per-request limit. A lower value still shortens the overall tool-execution timeout but leaves the per-request limit at 60 seconds. Stdio and WebSocket servers have no per-request timer. A per-server `timeout` field in `.mcp.json` overrides this for that server. A per-server `timeout` of at least 1000 also sets the minimum idle window for that server's tool calls, so `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` never aborts them sooner; this floor requires Claude Code v2.1.203 or later. For the env variable, values below 1000 are floored to one second; for the per-server field, values below 1000 are ignored |

| `NO_PROXY` | List of domains and IPs to which requests will be directly issued, bypassing proxy |

| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | Standard OpenTelemetry SDK limit on attribute value length. Claude Code caps content-bearing telemetry attributes at the smaller of this and `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`, so the truncation marker stays within the SDK limit. Claude Code reads the `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` and `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` variants the same way, and the smallest set value applies to all signals. Requires Claude Code v2.1.214 or later. See [Monitoring](/en/monitoring-usage#common-configuration-variables) |

| `OTEL_LOG_ASSISTANT_RESPONSES` | Set to `1` to include the model's response text on `assistant_response` OpenTelemetry log events. When unset, the value of `OTEL_LOG_USER_PROMPTS` is used instead. Set to `0` to keep responses redacted even when `OTEL_LOG_USER_PROMPTS` is set. Requires Claude Code v2.1.193 or later. See [Monitoring](/en/monitoring-usage#assistant-response-event) |

| `OTEL_LOG_RAW_API_BODIES` | Emit Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events. Set to `1` for inline bodies truncated at 60 KB, or `file:<dir>` to write untruncated bodies to disk and emit a `body_ref` path instead. Disabled by default; bodies include the entire conversation history. See [Monitoring](/en/monitoring-usage#api-request-body-event) |

| `OTEL_LOG_RAW_API_BODIES` | Emit Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events. Set to `1` for inline bodies truncated at the content limit, or `file:<dir>` to write untruncated bodies to disk and emit a `body_ref` path instead. `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` configures the content limit, 60 KB by default. Disabled by default; bodies include the entire conversation history. See [Monitoring](/en/monitoring-usage#api-request-body-event) |

| `OTEL_LOG_TOOL_CONTENT` | Set to `1` to include tool input and output content in OpenTelemetry span events. Disabled by default to protect sensitive data. See [Monitoring](/en/monitoring-usage) |

| `OTEL_LOG_TOOL_DETAILS` | Set to `1` to include tool input arguments, MCP server names, user-authored workflow names, raw error strings on tool failures, the refusal `category` on `api_refusal` events, and other tool details in OpenTelemetry traces and logs. Disabled by default to protect PII. See [Monitoring](/en/monitoring-usage) |

| `OTEL_LOG_USER_PROMPTS` | Set to `1` to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). See [Monitoring](/en/monitoring-usage) |

errors+197-7

エラーコードの定義やトラブルシューティングに関する情報が大幅に拡充されました。

(差分が大きいため省略しています)

hooks+9-7

サブエージェント実行時のモデル切り替えを追跡するmodelsUsedの解説と、デバッグ出力例の更新が行われています。

@@ -1411,15 +1411,16 @@ In `PostToolUse`, `tool_response` for a completed Agent call carries the subagen

| `status` | string | `"completed"` | `"completed"` for foreground subagents, `"async_launched"` for background subagents. As of v2.1.198, subagents run in the background by default, so an omitted `run_in_background` also produces `"async_launched"` |

| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | The subagent's final text blocks |

| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Models used in order, with consecutive repeats collapsed; set only when the model was swapped mid-run. Requires Claude Code v2.1.212 or later |

| `usage` | object | `{"input_tokens": 8320, ...}` | Per-type token breakdown: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

For background subagents, the tool returns immediately after launching, so `tool_response` carries no usage fields. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`.

For background subagents, the tool returns when the task moves to the background, so `tool_response` carries no usage fields: a background launch returns immediately, and a foreground task that Claude Code backgrounds mid-run returns at that transition. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`.

The `resolvedModel` field names the model the subagent actually runs on, which can differ from the `model` value in `tool_input`, such as when `availableModels` or another override applies. It requires Claude Code v2.1.174 or later.

On a `completed` response, `resolvedModel` names the model the subagent started on, which can differ from the `model` value in `tool_input`, such as when `availableModels` or another override applies. It requires Claude Code v2.1.174 or later. On an `async_launched` response, `resolvedModel` names the model in use when the agent moved to the background, so a swap that happened before backgrounding is reflected there. `modelsUsed` and the backgrounding-time `resolvedModel` behavior require Claude Code v2.1.212 or later.

##### AskUserQuestion

@@ -3032,11 +3033,12 @@ The example below shows a `settings.json` hook that runs a project script with t

Hook execution details, including which hooks matched, their exit codes, and full stdout and stderr, are written to the debug log file. Start Claude Code with `claude --debug-file <path>` to write the log to a known location, or run `claude --debug` and read the log at `~/.claude/debug/<session-id>.txt`. The `--debug` flag doesn't print to the terminal.

For example, a `PostToolUse` hook on `Write` whose command prints `hook-ran` produces entries like:

```text

[DEBUG] Executing hooks for PostToolUse:Write

[DEBUG] Found 1 hook commands to execute

[DEBUG] Executing hook command: <Your command> with timeout 600000ms

[DEBUG] Hook command completed with status 0: <Your stdout>

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text

2026-07-19T02:03:24.382Z [DEBUG] Hook PostToolUse:Write (PostToolUse) success:

hook-ran

```

For more granular hook matching details, set `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` to see additional log lines such as hook matcher counts and query matching.

large-codebases+12-9

/contextコマンドでのメモリファイル確認方法や、特定パッケージを除外する設定例が具体化されました。

@@ -106,7 +106,7 @@ API routes are in src/routes/. Each route file exports an Express router.

Database queries use Knex in src/db/. Never write raw SQL strings in route handlers.

```

When you start Claude from `packages/api/`, it loads both `packages/api/CLAUDE.md` and the root `CLAUDE.md`. Claude sees the local instructions alongside the repository-wide rules, with no instructions from `packages/web/` in context. The same holds for any subdirectory in a non-monorepo tree.

A few ways to keep the files current as the codebase and models change:

@@ -133,23 +133,22 @@ When you start Claude from the repository root, each subdirectory's CLAUDE.md lo

Use this for directories you never work in, such as other teams' packages, legacy code, or vendored subtrees. The exclusion list is static, not a per-task switch. To focus on one package today and another tomorrow, [start Claude from that package's directory](#choose-where-to-start-claude) instead of editing exclusions.

If you only want these exclusions for yourself, put the setting in `.claude/settings.local.json`. Claude Code gitignores that file when it creates it; since you're creating it by hand here, add it to your gitignore. Patterns use glob syntax matched against absolute file paths, so start relative-style patterns with `**/` to match anywhere in the tree. The example below excludes packages owned by other teams:

```json .claude/settings.local.json theme={null}

{

"claudeMdExcludes": [

"**/packages/admin-dashboard/**",

"**/packages/legacy-*/**"

"**/packages/web/**"

]

}

```

This skips every CLAUDE.md and rules file under those packages. The root CLAUDE.md and the packages you do work in still load normally.

This skips every CLAUDE.md and rules file under that package. The root CLAUDE.md and the packages you do work in still load normally.

These patterns cover other common cases:

- `"**/packages/*/CLAUDE.md"`: excludes every package's CLAUDE.md while keeping the root

- `"**/packages/web/**"`: excludes everything under the web package, including rules

- `"**/packages/legacy-*/**"`: excludes every package whose name matches the glob, including rules

- `"/home/user/monorepo/legacy/CLAUDE.md"`: excludes one specific file by absolute path

Managed policy CLAUDE.md files cannot be excluded, so organization-wide instructions always apply. You can set `claudeMdExcludes` at any [settings scope](/en/settings#configuration-scopes): user, project, local, or managed. Arrays merge across scopes, so a team can set project-level defaults while individuals add local overrides.

@@ -193,7 +192,7 @@ Deny rules cover Claude's built-in file tools and recognized Bash file commands,

In a large codebase, finding where a symbol is defined or used can cost many file reads and grep calls. [Code intelligence plugins](/en/discover-plugins#code-intelligence) connect Claude to a language server so it can jump to definitions, find references, and surface type errors directly instead of scanning the tree.

The official marketplace has plugins for TypeScript, Python, Go, Rust, and other common languages. The example below installs the TypeScript plugin:

The official marketplace has plugins for TypeScript, Python, Go, Rust, and other common languages. Run the command below inside a Claude Code session to install the TypeScript plugin:

```shell

/plugin install typescript-lsp@claude-plugins-official

@@ -215,7 +214,11 @@ These settings control what's on disk in worktrees and which directories Claude

The `--worktree` flag starts a session in a new git worktree so changes stay isolated from your main checkout. By default it checks out the entire repository. In a large repository, the `worktree.sparsePaths` setting uses git sparse-checkout to write only the listed directories plus root-level files to disk, so worktrees start faster and use less space.

If everyone working in this directory needs the same paths, commit the setting to `.claude/settings.json`. To add paths for yourself, use `.claude/settings.local.json`: the lists merge across scopes, so a local file can add paths to the committed list but not remove them. The example below shows the committed file:

The JSON examples on this page show one setting at a time. If your `.claude/settings.json` already contains other keys, such as the `permissions.deny` rules above, add the `worktree` key alongside them rather than replacing the file. [Put it together](#put-it-together) shows the combined result.

The example below shows the committed file:

```json .claude/settings.json theme={null}

{

@@ -268,7 +271,7 @@ When you start Claude from `packages/api/`, it can read and write files within t

The `additionalDirectories` setting in `.claude/settings.json` gives Claude access to directories outside the working directory. The example below grants access to two sibling packages:

```json .claude/settings.json theme={null}

```json packages/api/.claude/settings.json theme={null}

{

"permissions": {

"additionalDirectories": [

memory+12-8

外部インポートの承認ダイアログの仕様変更や、既存のCursor/Copilotルールを読み込む/initコマンドの拡張機能について記載されています。

@@ -67,7 +67,7 @@ For large projects, you can break instructions into topic-specific files using [

### Set up a project CLAUDE.md

A project CLAUDE.md can be stored in either `./CLAUDE.md` or `./.claude/CLAUDE.md`. Create this file and add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows. These instructions are shared with your team through version control, so focus on project-level standards rather than personal preferences.

Run `/init` to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, `/init` suggests improvements rather than overwriting it. Refine from there with instructions Claude wouldn't discover on its own.

@@ -106,7 +106,7 @@ See @README for project overview and @package.json for available npm commands fo

- git workflow @docs/git-instructions.md

```

For private per-project preferences that shouldn't be checked into version control, create a `CLAUDE.local.md` at the project root. It loads alongside `CLAUDE.md` and is treated the same way. Add `CLAUDE.local.md` to your `.gitignore` so it isn't committed; running `/init` and choosing the personal option does this for you.

For private per-project preferences that shouldn't be checked into version control, create a `CLAUDE.local.md` at the project root. It loads alongside `CLAUDE.md` and is treated the same way. Add `CLAUDE.local.md` to your `.gitignore` so it isn't committed. With `CLAUDE_CODE_NEW_INIT=1` set, running `/init` and choosing the personal option does this for you.

If you work across multiple git worktrees of the same repository, a gitignored `CLAUDE.local.md` only exists in the worktree where you created it. To share personal instructions across worktrees, import a file from your home directory instead:

@@ -115,7 +115,9 @@ If you work across multiple git worktrees of the same repository, a gitignored `

- @~/.claude/my-project-instructions.md

```

The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the files. If you decline, the imports stay disabled and the dialog does not appear again.

An import in a project-level memory file is external when its path resolves outside your working directory, like the home directory import above. The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the files. If you decline, the imports stay disabled and the dialog doesn't appear again.

The dialog protects you from files other people commit to a shared project. Imports in user-scope memory files, such as `~/.claude/CLAUDE.md` and `~/.claude/rules/`, are files you wrote yourself, so they load without the dialog and carry the same trust as the rest of your personal configuration.

For a more structured approach to organizing instructions, see [`.claude/rules/`](#organize-rules-with-claude/rules/).

@@ -137,9 +139,11 @@ A symlink also works if you don't need to add Claude-specific content:

ln -s AGENTS.md CLAUDE.md

```

The command prints no output on success. In your next session, run `/context` and confirm `CLAUDE.md` appears under **Memory files**.

On Windows, creating a symlink requires Administrator privileges or Developer Mode, so use the `@AGENTS.md` import instead.

Running [`/init`](/en/commands) in a repo that already has an `AGENTS.md` reads it and incorporates the relevant parts into the generated `CLAUDE.md`. It also reads other tool configs like `.cursorrules`, `.devin/rules/`, and `.windsurfrules`.

Running [`/init`](/en/commands) reads Cursor rules, in `.cursor/rules/` or `.cursorrules`, and Copilot rules, in `.github/copilot-instructions.md`, and incorporates the relevant parts into the generated `CLAUDE.md`. With `CLAUDE_CODE_NEW_INIT=1` set, `/init` also reads `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` or `.windsurfrules`, and `.clinerules`.

### How CLAUDE.md files load

@@ -322,7 +326,7 @@ Auto memory lets Claude accumulate knowledge across sessions without you writing

### Enable or disable auto memory

Auto memory is on by default. To toggle it, open `/memory` in a session and use the auto memory toggle, or set `autoMemoryEnabled` in your project settings:

Auto memory is on by default. To toggle it, open `/memory` in a session and use the auto memory toggle, which saves `autoMemoryEnabled` to your user settings at `~/.claude/settings.json`. To turn it off for a single project, set `autoMemoryEnabled` in that project's settings:

```json

{

@@ -374,7 +378,7 @@ Topic files like `debugging.md` or `patterns.md` are not loaded at startup. Clau

The main conversation's auto memory isn't loaded into [subagents](/en/sub-agents#what-loads-at-startup); the exception is a [fork](/en/sub-agents#fork-the-current-conversation), which inherits the parent conversation and system prompt. A subagent's own auto memory, enabled with the subagent `memory` field, is a separate directory.

Claude reads and writes memory files during your session. When you see "Writing memory" or "Recalled memory" in the Claude Code interface, Claude is actively updating or reading from `~/.claude/projects/<project>/memory/`.

Claude reads and writes memory files during your session. When you see messages like "Saved 2 memories" or "Recalled 2 memories" in the Claude Code interface, Claude is actively updating or reading from `~/.claude/projects/<project>/memory/`.

### Audit and edit your memory

@@ -382,7 +386,7 @@ Auto memory files are plain markdown you can edit or delete at any time. Run [`/

## View and edit with `/memory`

The `/memory` command lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes, lets you toggle auto memory on or off, and provides an option to open the auto memory folder. Select any file to open it in your editor. To check which files actually loaded into the current session, run `/context`.

The `/memory` command lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes, including user and project CLAUDE.md entries for files that don't exist yet. It also lets you toggle auto memory on or off and provides an option to open the auto memory folder. Select any file to open it in your editor; selecting one that doesn't exist yet creates it first. To check which files actually loaded into the current session, run `/context`.

When you ask Claude to remember something, like "always use pnpm, not npm" or "remember that the API tests require a local Redis instance," Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly, like "add this to CLAUDE.md," or edit the file yourself via `/memory`.

@@ -396,7 +400,7 @@ CLAUDE.md content is delivered as a user message after the system prompt, not as

To debug:

- Run `/context` to verify your CLAUDE.md and CLAUDE.local.md files loaded. If a file is missing from the breakdown, Claude can't see it. Use `/memory` to open and edit the files.

- Run `/context` and check the list under **Memory files** to verify your CLAUDE.md and CLAUDE.local.md files loaded. If a file is missing there, Claude can't see it. Use `/memory` to open and edit the files.

- Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see [Choose where to put CLAUDE.md files](#choose-where-to-put-claude-md-files)).

- Make instructions more specific. "Use 2-space indentation" works better than "format code nicely."

- Look for conflicting instructions across CLAUDE.md files. If two files give different guidance for the same behavior, Claude may pick one arbitrarily.

permissions+4-2

Bash実行時のラッパーコマンド除去対象にzshのnoglobなどが追加され、環境変数割り当て時のマッチング挙動が詳しく説明されています。

@@ -176,9 +176,11 @@ Claude Code is aware of shell operators, so a rule like `Bash(safe-cmd *)` won't

When you approve a compound command with "Yes, don't ask again", Claude Code saves a separate rule for each subcommand that requires approval, rather than a single rule for the full compound string. For example, approving `git status && npm test` saves a rule for `npm test`, so future `npm test` invocations are recognized regardless of what precedes the `&&`. Subcommands like `cd` into a subdirectory generate their own Read rule for that path. Up to 5 rules may be saved for a single compound command.

#### Process wrappers

Wrappers

Before matching Bash rules, Claude Code strips a fixed set of process wrappers so a rule like `Bash(npm test *)` also matches `timeout 30 npm test`. The recognized wrappers are `timeout`, `time`, `nice`, `nohup`, and `stdbuf`.

Before matching Bash rules, Claude Code strips a fixed set of wrappers, so a rule like `Bash(npm test *)` also matches `timeout 30 npm test`. The stripped wrappers are `timeout`, `time`, `nice`, `nohup`, and `stdbuf`, plus the shell builtins `command` and `builtin`, and zsh's `noglob`. Each runs its argument as the actual command. Two related forms aren't stripped: the query form `command -v`, which looks up a command rather than running one, and zsh's `nocorrect`.

Claude Code also strips a leading assignment of certain known-safe environment variables, so `Bash(npm test *)` matches `NODE_ENV=test npm test`. An allow rule won't match past an assignment of any other variable. A deny or ask rule matches past any leading assignment, so `Bash(rm *)` in deny still matches `FOO=bar rm -rf tmp/`.

Bare `xargs` is also stripped, so `Bash(grep *)` matches `xargs grep pattern`. Stripping applies only when `xargs` has no flags: an invocation like `xargs -n1 grep pattern` is matched as an `xargs` command, so rules written for the inner command do not cover it.

plugins-reference+2-2

プラグインの更新後に旧バージョンのディレクトリが保持される期間が2週間に延長されました。

@@ -681,7 +681,7 @@ In hook commands, use [exec form](/en/hooks#exec-form-and-shell-form) with `args

}

```

`${CLAUDE_PLUGIN_ROOT}` changes when the plugin updates. The previous version's directory remains on disk for about seven days after an update before cleanup, but treat it as ephemeral and don't write state there.

`${CLAUDE_PLUGIN_ROOT}` changes when the plugin updates. The previous version's directory remains on disk for about two weeks after an update before cleanup, but treat it as ephemeral and don't write state there.

When a plugin updates mid-session, hook commands, monitors, MCP servers, and LSP servers keep using the previous version's path. Run `/reload-plugins` to switch hooks, MCP servers, and LSP servers to the new path; monitors require a session restart.

@@ -743,7 +743,7 @@ Plugins are specified in one of two ways:

For security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`) rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files.

Each installed version is a separate directory in the cache. When you update or uninstall a plugin, the previous version directory is marked as orphaned and removed automatically 7 days later. The grace period lets concurrent Claude Code sessions that already loaded the old version keep running without errors.

Each installed version is a separate directory in the cache. When you update or uninstall a plugin, the previous version directory is marked as orphaned and removed automatically 14 days later. The grace period lets concurrent Claude Code sessions that already loaded the old version keep running without errors.

Claude's Glob and Grep tools skip orphaned version directories during searches, so file results don't include outdated plugin code.

remote-control+2-2

リモートコントロールの開始場所に関するワークスペースの信頼についての注意点や、通知メッセージの表示条件が変更されています。

@@ -29,7 +29,7 @@ Before using Remote Control, confirm that your environment meets these condition

- **Subscription**: available on Pro, Max, Team, and Enterprise plans. API keys are not supported. On Team and Enterprise, an Owner must first enable the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).

- **Authentication**: run `claude` and use `/login` to sign in through claude.ai if you haven't already. Without an eligible login, `claude remote-control` exits with an error, while `claude --remote-control` still starts an interactive session and shows a Remote Control failure notification shortly after launch.

- **API endpoint**: not available on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. As of v2.1.196, Remote Control is also disabled when [`ANTHROPIC_BASE_URL`](/en/env-vars) points at a host other than `api.anthropic.com`, such as an [LLM gateway](/en/llm-gateway) or proxy. Unset the variable to use Remote Control.

- **Workspace trust**: run `claude` in your project directory at least once to accept the workspace trust dialog.

- **Workspace trust**: run `claude` in your project directory at least once to accept the workspace trust dialog. The startup trust dialog never saves trust for your home directory, so start Remote Control from a project directory.

## Start a Remote Control session

@@ -112,7 +112,7 @@ While Remote Control is connected, Claude Code reminds you of the session URL at

- **Long turn**: when a turn runs longer than a server-tuned threshold, a **Still working** notification with a **Check in from your phone** link appears, so you can follow the turn from your phone or browser instead of waiting at the terminal. Claude Code removes it when the turn ends.

- **Repeated permission prompts**: after you answer several [permission prompts](/en/permissions) in a session, an **Approve tool calls from your phone** notification shows the session URL. Claude Code removes it when your next turn starts.

You only see the reminders in sessions where you turned on Remote Control yourself, and Claude Code shows each one a few times in total across sessions rather than at every opportunity. You can't configure or turn them off; each clears on its own.

The reminders can appear in any connected session, including ones where Remote Control [connects automatically](#enable-remote-control-for-all-sessions). They don't appear every time these conditions occur, and each one appears only a few times in total across sessions. You can't configure or turn them off; each clears on its own.

### Connect from another device

routines+2-0

ルーチンのプロンプトが事前承認されたタスクとして扱われ、バックグラウンドでの拒否が発生しにくくなった仕様変更が説明されています。

@@ -59,6 +59,8 @@ Visit [claude.ai/code/routines](https://claude.ai/code/routines) and click **New

Give the routine a descriptive name and write the prompt Claude runs each time. The prompt is the most important part: the routine runs autonomously, so the prompt must be self-contained and explicit about what to do and what success looks like.

When a trigger fires, the session receives the routine's saved prompt as its assigned task and carries it out, rather than treating it as untrusted content that arrived mid-conversation. The trigger attests only that the prompt was stored ahead of time by an authorized session on your account, so the fired prompt is not live user input and can't act as approval or consent for actions during the run. Content the session fetches during the run keeps its normal handling. Before v2.1.214, the session received the same prompt framed as an untrusted background notification and could refuse to act on it.

The prompt input includes a model selector. Claude uses the selected model on every run.

Add one or more GitHub repositories for Claude to work in. Each repository is cloned at the start of a run, starting from the default branch. Claude creates `claude/`-prefixed branches for its changes.

skills+17-1

スキルのパスを変数で指定するCLAUDE_SKILL_DIRが、allowed-tools内のBashルールでも置換可能になったことが示されています。

@@ -272,7 +272,23 @@ Skills support string substitution for dynamic values in the skill content:

| `${CLAUDE_SKILL_DIR}` | The directory containing the skill's `SKILL.md` file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |

| `${CLAUDE_PROJECT_DIR}` | The project root directory. This is the same path [hooks](/en/hooks#reference-scripts-by-path) and MCP servers receive as `CLAUDE_PROJECT_DIR`. Use this to reference project-local scripts or files, such as `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`, independent of where the skill is installed. |

The `${CLAUDE_PROJECT_DIR}` substitution requires Claude Code v2.1.196 or later. It applies to both the skill body and the [`allowed-tools`](#frontmatter-reference) frontmatter, so a permission rule like `Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)` resolves to the same path the skill body uses.

Claude Code substitutes `${CLAUDE_SKILL_DIR}` and `${CLAUDE_PROJECT_DIR}` in two places: the skill's markdown content, and Bash rules in the [`allowed-tools`](#frontmatter-reference) frontmatter. Using the same variable in both places lets a skill run a bundled script without a permission prompt. The following skill shows the pattern:

```yaml

---

name: render-chart

description: Render a chart from a CSV file

allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)

---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

```

If this skill is installed at `~/.claude/skills/render-chart/`, both occurrences of `${CLAUDE_SKILL_DIR}` expand to that directory. The `allowed-tools` rule then matches the exact command the skill body tells Claude to run, so the script runs without prompting.

The `allowed-tools` substitution for `${CLAUDE_SKILL_DIR}` requires Claude Code v2.1.129 or later. On earlier versions the rule stays a literal `${CLAUDE_SKILL_DIR}` string and never matches, so the command still prompts for permission.

The `${CLAUDE_PROJECT_DIR}` substitution requires Claude Code v2.1.196 or later.

Indexed arguments use shell-style quoting, so wrap multi-word values in quotes to pass them as a single argument. For example, `/my-skill "hello world" second` makes `$0` expand to `hello world` and `$1` to `second`. The `$ARGUMENTS` placeholder always expands to the full argument string as typed.

statusline+15-3

ステータスライン更新スクリプトが実行される具体的なタイミングと条件が整理されました。

@@ -123,9 +123,19 @@ Claude Code runs your script and pipes [JSON session data](#available-data) to i

**When it updates**

Your script runs after each new assistant message, after `/compact` finishes, when the permission mode changes, or when vim mode toggles. Updates are debounced at 300ms, meaning rapid changes batch together and your script runs once things settle. If a new update triggers while your script is still running, the in-flight execution is cancelled. If you edit your script, the changes won't appear until your next interaction with Claude Code triggers an update.

Your script runs once when a session starts, including when you resume one. After that, it runs again when:

These triggers can go quiet when the main session is idle, for example while a coordinator waits on background subagents. To keep time-based or externally-sourced segments current during idle periods, set [`refreshInterval`](#manually-configure-a-status-line) to also re-run the command on a fixed timer.

- A new assistant message arrives

- `/compact` finishes

- The permission mode changes

- Vim mode toggles

- A [`refreshInterval`](#manually-configure-a-status-line) timer elapses, if you set one

Before v2.1.216, resuming a session ran the command twice in quick succession, so the first result could flicker before being replaced.

Claude Code debounces updates at 300ms, so rapid changes batch together and your script runs once after the changes stop. If a new update triggers while your script is still running, Claude Code cancels the in-flight script. If you edit your script, the changes appear the next time an update trigger re-runs it.

The event-driven triggers can go quiet when the main session is idle, for example while a coordinator waits on background subagents. To keep time-based or externally-sourced segments current during idle periods, set [`refreshInterval`](#manually-configure-a-status-line) to also re-run the command on a fixed timer.

**What your script can output**

@@ -960,10 +970,12 @@ The `subagentStatusLine` setting renders a custom row body for each [subagent](/

}

```

The command runs once per refresh tick with all visible subagent rows passed as a single JSON object on stdin. The input includes the [base hook fields](/en/hooks#common-input-fields), a `columns` field with the usable row width, and a `tasks` array. Each task has `id`, `name`, `type`, `status`, `description`, `label`, `startTime`, `model`, `contextWindowSize`, `tokenCount`, `tokenSamples`, and `cwd`.

The command runs once per refresh tick and receives all visible subagent rows as a single JSON object on stdin. The input includes the [base hook fields](/en/hooks#common-input-fields), a `columns` field with the usable row width, and a `tasks` array. Each task has `id`, `name`, `type`, `status`, `description`, `label`, `startTime`, `model`, `effort`, `contextWindowSize`, `tokenCount`, `tokenSamples`, and `cwd`.

The per-task `model` field is the resolved model ID the task runs on. `contextWindowSize` is that model's context window in tokens, computed the same way as the main status line's `context_window.context_window_size`, so you can render a per-row percentage from `tokenCount`. Both fields require Claude Code v2.1.205 or later and are omitted for a task whose model isn't resolved yet.

The per-task `effort` field is the reasoning effort set for that subagent, in its [definition frontmatter](/en/sub-agents#supported-frontmatter-fields) or on the individual invocation. The value is either one of the effort level strings `low`, `medium`, `high`, `xhigh`, or `max`, or a numeric token budget. The field reports the configured value as written: if the model doesn't support that level, the effort Claude Code actually applies may differ. The field requires Claude Code v2.1.214 or later and is absent when the subagent inherits the session's effort level.

Write one JSON line to stdout per row you want to override, in the form `{"id": "<task id>", "content": "<row body>"}`. The `content` string is rendered as-is, including ANSI colors and OSC 8 hyperlinks. Omit a task's `id` to keep the default rendering for that row; emit an empty `content` string to hide it.

The same trust and `disableAllHooks` gates that apply to `statusLine` apply here. Plugins can ship a default `subagentStatusLine` in their [`settings.json`](/en/plugins-reference#standard-plugin-layout).

troubleshoot-install+13-0

インストールのトラブルシューティングに関する新しいセクションが追加されました。

@@ -34,6 +34,7 @@ Match the error message or symptom you're seeing to a fix:

| `cannot execute binary file: Exec format error` in WSL | [WSL1 native-binary regression](#exec-format-error-on-wsl1) |

| PowerShell installer completes but `claude` is not found or shows an old version | [Add the install directory to your PATH](#verify-your-path), then open a new terminal |

| `dyld: cannot load`, `dyld: Symbol not found`, or `Abort trap` on macOS | [Binary incompatibility](#dyld-cannot-load-on-macos) |

| `claude update` hangs after `Checking for updates`, or `claude doctor` hangs with no output | [Move the directory at a shell config path](#claude-update-or-claude-doctor-hangs) |

| `Invoke-Expression: Missing argument in parameter list` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |

| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |

| `unable to get local issuer certificate` | [Configure corporate CA certificates](#tls-or-ssl-connection-errors) |

@@ -553,6 +554,18 @@ When installing Claude Code in a Docker container, installing as root into `/` c

docker build --memory=4g .

```

### `claude update` or `claude doctor` hangs

`claude update` and `claude doctor` scan your shell configuration files for an outdated `claude` alias: `~/.zshrc`, `~/.bashrc`, and `~/.config/fish/config.fish`, plus on macOS the first of `~/.bash_profile`, `~/.bash_login`, or `~/.profile` that exists. If you set `ZDOTDIR`, the Zsh file is `$ZDOTDIR/.zshrc` instead. When one of those paths is a directory, Claude Code skips it and both commands complete normally. Before v2.1.214, a directory at one of those paths made both commands hang and left the System diagnostics section of `/status` blank. `claude doctor` hung with no output; `claude update` hung right after printing `Checking for updates`.

If you hit the hang on an earlier version, find the directory. In this command's output, a line starting with `d` marks that path as a directory. A `No such file or directory` line means nothing exists at that path and isn't the cause:

```bash

ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

```

Move the directory aside, or update to v2.1.214 or later. Since `claude update` hangs on the affected versions, update by rerunning the [install script](/en/setup#install-claude-code) instead.

### Claude Desktop overrides the `claude` command on Windows

If you installed an older version of Claude Desktop, it may register a `Claude.exe` in the `WindowsApps` directory that takes PATH priority over Claude Code CLI. Running `claude` opens the Desktop app instead of the CLI.

ultrareview+3-1

レビュー機能に関する軽微な説明の更新が行われました。

@@ -29,6 +29,8 @@ Start a review from any git repository in the Claude Code CLI.

Without arguments, ultrareview reviews the diff between your current branch and the default branch, including any uncommitted and staged changes in your working tree. Claude Code bundles the repository state and uploads it to a remote sandbox for the review. To compare against a different base, such as on a repository whose integration branch is `develop` or `trunk`, pass the branch name instead: `/code-review ultra develop`. A base branch that exists only on `origin` is fetched, and a name with a typo gets a closest-branch suggestion. Both behaviors require Claude Code v2.1.212 or later.

If your branch shares no merge base with the base branch, for example when the two histories are unrelated, Claude Code offers to review every tracked file in the repository instead. The whole-repository fallback requires a full clone and applies the same size limits as a branch review. Before v2.1.214, `/code-review ultra` refused to run without a merge base.

To review a GitHub pull request instead, pass the PR number.

```text

@@ -84,7 +86,7 @@ claude ultrareview 1234

claude ultrareview origin/main

```

Without arguments, the subcommand reviews the diff between your current branch and the default branch. Pass a PR number to review a pull request, or pass a base branch to review the diff against that branch instead. Invoking the subcommand counts as consent for the billing and terms prompt that the interactive command shows.

Without arguments, the subcommand reviews the diff between your current branch and the default branch, with the same [whole-repository fallback](#run-ultrareview-from-the-cli) as `/code-review ultra` when no merge base exists. Pass a PR number to review a pull request, or pass a base branch to review the diff against that branch instead. Invoking the subcommand counts as consent for the whole-repository fallback and for the billing and terms prompt that the interactive command shows, so the run starts without waiting for input.

If the base branch you pass exists on `origin` but not in your local clone, Claude Code fetches it and continues. If the name matches no branch, the error message suggests the closest branch name. Before v2.1.212, both cases failed with a not-a-branch error.