20 ファイル変更+341-42
この更新の概要
TypeScript SDKに設定を解決するためのresolveSettings関数と権限拒否イベントの通知機能が追加されました。オートモードの設定に、ユーザーの意図や例外設定でも上書きできない強力な制限を設けるhard_denyオプションが導入されています。CLIコマンドでは/clearでの名前指定保存やLo-Fiラジオを再生する/radioが追加されたほか、組織ポリシーによるルーチンの無効化制御も可能になりました。
@@ -282,7 +282,7 @@ options = ClaudeAgentOptions(
}
```
For HTTP (non-streaming), use `"type": "http"` instead.
For the streamable HTTP transport, use `"type": "http"` instead. In `.mcp.json` and other JSON config files, `"streamable-http"` is accepted as an alias for `"http"`. The programmatic `mcpServers` option accepts only `"http"`.
### SDK MCP servers
@@ -2285,7 +2285,9 @@ Asks the user clarifying questions during execution. See [Handle approvals and u
"multiSelect": bool, # Set to true to allow multiple selections
}
],
"answers": dict | None, # User answers populated by the permission system
"answers": dict[str, str | list[str]] | None,
# User answers populated by the permission system. Multi-select
# answers may be a list of labels or a comma-joined string
}
```
SDKから直接設定を確認できるresolveSettings関数と、権限拒否を即座に検知するSDKPermissionDeniedMessageが追加されました。
@@ -305,6 +305,55 @@ function tagSession(
| `tag` | `string \| null` | required | Tag string, or `null` to clear |
| `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories |
### `resolveSettings()`
Resolves the effective Claude Code settings for a given directory using the same merge engine as the CLI, without spawning the Claude CLI. Use it to inspect what configuration a `query()` call would see before invoking one.
This function is alpha and its API may change before stabilization. It reads MDM sources, including macOS plist and Windows HKLM/HKCU, for parity with CLI startup, but does not execute the admin-configured `policyHelper` subprocess. The `permissions.defaultMode` field is returned as-is from all tiers including project settings. The trust filter the CLI applies before honoring escalating permission modes is not applied.
```typescript
function resolveSettings(
options?: ResolveSettingsOptions
): Promise<ResolvedSettings>;
```
#### Parameters
`resolveSettings()` accepts a single options object. All fields are optional.
| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `options.cwd` | `string` | `process.cwd()` | Directory to resolve project and local settings relative to |
| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | All sources | Which filesystem sources to load. Pass `[]` to skip user, project, and local settings. Managed policy settings load in all cases |
| `options.managedSettings` | `Settings` | `undefined` | Restrictive policy-tier settings merged at the managed-policy precedence level. Non-restrictive keys such as `model` are silently dropped |
| `options.serverManagedSettings` | `Settings` | `undefined` | Server-managed settings payload from `/api/claude_code/settings`. Non-restrictive keys pass through unfiltered |
#### Return type: `ResolvedSettings`
`resolveSettings()` returns an object describing the merged settings and the source that contributed each key.
| Property | Type | Description |
| :- | :- | :- |
| `effective` | `Settings` | Merged settings after applying all enabled sources in precedence order |
| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | For each top-level key in `effective`, which source supplied the value |
| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | Per-source raw settings, ordered from lowest to highest precedence |
#### Example
The example below resolves settings for a project directory and prints the source that controls the cleanup period.
```typescript
import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
const { effective, provenance } = await resolveSettings({
cwd: "/path/to/project",
settingSources: ["user", "project", "local"],
});
console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);
```
## Types
### `Options`
@@ -859,6 +908,7 @@ type SDKMessage =
| SDKFilesPersistedEvent
| SDKToolUseSummaryMessage
| SDKRateLimitEvent
| SDKPermissionDeniedMessage
| SDKPromptSuggestionMessage;
```
@@ -1047,6 +1097,36 @@ type SDKPluginInstallMessage = {
};
```
### `SDKPermissionDeniedMessage`
Stream event emitted when the permission system auto-denies a tool call without an interactive prompt. Use it to render the denial in your UI as it happens, rather than only observing the `is_error` tool result that follows. The interactive ask path reaches your application separately through the [`canUseTool`](#canusetool) callback. Denials issued by a `PreToolUse` hook are not reported through this event.
This event requires Claude Code v2.1.136 or later.
```typescript
type SDKPermissionDeniedMessage = {
type: "system";
subtype: "permission_denied";
tool_name: string;
tool_use_id: string;
agent_id?: string;
decision_reason_type?: string;
decision_reason?: string;
message: string;
uuid: UUID;
session_id: string;
};
```
| Field | Type | Description |
| - | - | - |
| `tool_name` | `string` | Name of the tool that was denied |
| `tool_use_id` | `string` | ID of the `tool_use` block this denial answers |
| `agent_id` | `string` | Subagent ID when the denied call originated inside a subagent. Mirrors the field on `can_use_tool` for host-side routing |
| `decision_reason_type` | `string` | Discriminator for the component that decided, such as `"rule"`, `"mode"`, `"classifier"`, or `"asyncAgent"` |
| `decision_reason` | `string` | Human-readable reason from the deciding component, when available |
| `message` | `string` | Rejection message returned to the model in the `tool_result` |
### `SDKPermissionDenial`
Information about a denied tool use.
@@ -423,7 +423,7 @@ Build the `answers` object as a record where each key is the `question` text and
| `question` field (e.g., `"How should I format the output?"`) | Key |
| Selected option's `label` field (e.g., `"Summary"`) | Value |
For multi-select questions, join multiple labels with `", "`. If you [support free-text input](#support-free-text-input), use the user's custom text as the value.
For multi-select questions, pass an array of labels or join them with `", "`. If you [support free-text input](#support-free-text-input), use the user's custom text as the value.
```python Python theme={null}
return PermissionResultAllow(
@@ -431,7 +431,7 @@ return PermissionResultAllow(
"questions": input_data.get("questions", []),
"answers": {
"How should I format the output?": "Summary",
"Which sections should I include?": "Introduction, Conclusion",
"Which sections should I include?": ["Introduction", "Conclusion"],
},
}
)
@@ -529,7 +529,7 @@ Return an `answers` object mapping each question's `question` field to the selec
| `questions` | Pass through the original questions array (required for tool processing) |
| `answers` | Object where keys are question text and values are selected labels |
For multi-select questions, join multiple labels with `", "`. For free-text input, use the user's custom text directly.
For multi-select questions, pass an array of labels or join them with `", "`. For free-text input, use the user's custom text directly.
```json
{
@@ -538,7 +538,7 @@ For multi-select questions, join multiple labels with `", "`. For free-text inpu
],
"answers": {
"How should I format the output?": "Summary",
"Which sections should I include?": "Introduction, Conclusion"
"Which sections should I include?": ["Introduction", "Conclusion"]
}
}
```
@@ -38,7 +38,7 @@ For rules that apply across projects, such as trusted infrastructure or organiza
The classifier does not read `autoMode` from shared project settings in `.claude/settings.json`, so a checked-in repo cannot inject its own allow rules.
Entries from each scope are combined. A developer can extend `environment`, `allow`, and `soft_deny` with personal entries but cannot remove entries that managed settings provide. Because allow rules act as exceptions to block rules inside the classifier, a developer-added `allow` entry can override an organization `soft_deny` entry: the combination is additive, not a hard policy boundary.
Entries from each scope are combined. A developer can extend `environment`, `allow`, `soft_deny`, and `hard_deny` with personal entries but cannot remove entries that managed settings provide. Because allow rules act as exceptions to soft block rules inside the classifier, a developer-added `allow` entry can override an organization `soft_deny` entry: the combination is additive, not a hard policy boundary.
The classifier is a second gate that runs after the [permissions system](/en/permissions). For actions that must never run regardless of user intent or classifier configuration, use `permissions.deny` in managed settings, which blocks the action before the classifier is consulted and cannot be overridden.
@@ -96,17 +96,18 @@ You don't need to fill everything in at once. A reasonable rollout: start with t
## Override the block and allow rules
Two additional fields let you replace the classifier's built-in rule lists: `autoMode.soft_deny` controls what gets blocked, and `autoMode.allow` controls which exceptions apply. Each is an array of prose descriptions, read as natural-language rules. There is no `autoMode.deny` field; to hard-block an action regardless of intent, use [`permissions.deny`](/en/permissions), which runs before the classifier.
Three additional fields let you replace the classifier's built-in rule lists: `autoMode.hard_deny` for unconditional security boundaries, `autoMode.soft_deny` for destructive actions that user intent can clear, and `autoMode.allow` for exceptions. Each is an array of prose descriptions, read as natural-language rules. For tool-pattern-based hard blocks that run before the classifier, use [`permissions.deny`](/en/permissions).
Inside the classifier, precedence works in three tiers:
Inside the classifier, precedence works in four tiers:
- `soft_deny` rules block first
- `allow` rules then override matching blocks as exceptions
- Explicit user intent overrides both: if the user's message directly and specifically describes the exact action Claude is about to take, the classifier allows it even when a `soft_deny` rule matches
- `hard_deny` rules block unconditionally. User intent and `allow` exceptions do not apply.
- `soft_deny` rules block next. User intent and `allow` exceptions can override these.
- `allow` rules then override matching `soft_deny` rules as exceptions.
- Explicit user intent overrides the remaining soft blocks: if the user's message directly and specifically describes the exact action Claude is about to take, the classifier allows it even when a `soft_deny` rule matches.
General requests don't count as explicit intent. Asking Claude to "clean up the repo" does not authorize force-pushing, but asking Claude to "force-push this branch" does.
To loosen, add to `allow` when the classifier repeatedly flags a routine pattern the default exceptions don't cover. To tighten, add to `soft_deny` for risks specific to your environment that the defaults miss. To keep the built-in rules while adding your own, include the literal string `"$defaults"` in the array. The default rules are spliced in at that position, so your custom rules can go before or after them, and you continue to inherit updates as the built-in list changes across releases.
To loosen, add to `allow` when the classifier repeatedly flags a routine pattern the default exceptions don't cover. To tighten, add to `soft_deny` for destructive risks specific to your environment that the defaults miss, or to `hard_deny` for security boundaries that must never be crossed. To keep the built-in rules while adding your own, include the literal string `"$defaults"` in the array. The default rules are spliced in at that position, so your custom rules can go before or after them, and you continue to inherit updates as the built-in list changes across releases.
```json
{
@@ -124,20 +125,24 @@ To loosen, add to `allow` when the classifier repeatedly flags a routine pattern
"$defaults",
"Never run database migrations outside the migrations CLI, even against dev databases",
"Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"
],
"hard_deny": [
"$defaults",
"Never send repository contents to third-party code-review APIs"
]
}
}
```
Setting any of `environment`, `allow`, or `soft_deny` without `"$defaults"` replaces the entire default list for that section. If you set `soft_deny` with a single entry and omit `"$defaults"`, every built-in block rule is discarded: force push, data exfiltration, `curl | bash`, production deploys, and all other default block rules become allowed. Only omit `"$defaults"` when you intend to take full ownership of the list. In that case, run `claude auto-mode defaults` to print the built-in rules, copy them into your settings file, then review each rule against your own pipeline and risk tolerance.
Setting any of `environment`, `allow`, `soft_deny`, or `hard_deny` without `"$defaults"` replaces the entire default list for that section. A `soft_deny` array without `"$defaults"` discards every built-in soft block rule, including force push, `curl | bash`, and production deploys. A `hard_deny` array without `"$defaults"` discards the built-in data exfiltration and safety-check bypass rules.
Each section is evaluated independently, so setting `environment` alone leaves the default `allow` and `soft_deny` lists intact.
Each section is evaluated independently, so setting `environment` alone leaves the default `allow`, `soft_deny`, and `hard_deny` lists intact. Only omit `"$defaults"` when you intend to take full ownership of the list. To do that safely, run `claude auto-mode defaults` to print the built-in rules, copy them into your settings file, then review each rule against your own pipeline and risk tolerance.
## Inspect the defaults and your effective config
Three CLI subcommands help you inspect and validate your configuration.
Print the built-in `environment`, `allow`, and `soft_deny` rules as JSON:
Print the built-in `environment`, `allow`, `soft_deny`, and `hard_deny` rules as JSON:
```bash
claude auto-mode defaults
@@ -149,7 +154,7 @@ Print what the classifier actually uses as JSON, with your settings applied wher
claude auto-mode config
```
Get AI feedback on your custom `allow` and `soft_deny` rules:
Get AI feedback on your custom `allow`, `soft_deny`, and `hard_deny` rules:
```bash
claude auto-mode critique
@@ -45,11 +45,11 @@ Not every command appears for every user. Availability depends on your platform,
| `/btw <question>` | Ask a quick [side question](/en/interactive-mode#side-questions-with-%2Fbtw) without adding to the conversation |
| `/chrome` | Configure [Claude in Chrome](/en/chrome) settings |
| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/en/skills#bundled-skills).** Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Managed Agents reference. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports `anthropic` or `@anthropic-ai/sdk`. Run `/claude-api migrate` to upgrade existing Claude API code to a newer model: Claude asks which files to scan and which model to target, then updates model IDs, thinking configuration, and other parameters that changed between versions. Run `/claude-api managed-agents-onboard` for an interactive walkthrough that creates a new Managed Agent from scratch |
| `/clear` | Start a new conversation with empty context. The previous conversation stays available in `/resume`. To free up context while continuing the same conversation, use `/compact` instead. Aliases: `/reset`, `/new` |
| `/clear [name]` | Start a new conversation with empty context. The previous conversation stays available in `/resume`. Pass a name to label the previous conversation in the `/resume` picker. To free up context while continuing the same conversation, use `/compact` instead. Aliases: `/reset`, `/new` |
| `/color [color\|default]` | Set the prompt bar color for the current session. Available colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` to reset, or run with no argument to pick a random color. When [Remote Control](/en/remote-control) is connected, the color syncs to claude.ai/code |
| `/compact [instructions]` | Free up context by summarizing the conversation so far. Optionally pass focus instructions for the summary. See [how compaction handles rules, skills, and memory files](/en/context-window#what-survives-compaction) |
| `/config` | Open the [Settings](/en/settings) interface to adjust theme, model, [output style](/en/output-styles), and other preferences. Alias: `/settings` |
| `/context` | Visualize current context usage as a colored grid. Shows optimization suggestions for context-heavy tools, memory bloat, and capacity warnings |
| `/context [all]` | Visualize current context usage as a colored grid. Shows optimization suggestions for context-heavy tools, memory bloat, and capacity warnings. In [fullscreen mode](/en/fullscreen) the per-item breakdown is collapsed to keep the grid visible. Pass `all` to expand it |
| `/copy [N]` | Copy the last assistant response to clipboard. Pass a number `N` to copy the Nth-latest response: `/copy 2` copies the second-to-last. When code blocks are present, shows an interactive picker to select individual blocks or the full response. Press `w` in the picker to write the selection to a file instead of the clipboard, which is useful over SSH |
| `/cost` | Alias for `/usage` |
| `/debug [description]` | **[Skill](/en/skills#bundled-skills).** Enable debug logging for the current session and troubleshoot issues by reading the session debug log. Debug logging is off by default unless you started with `claude --debug`, so running `/debug` mid-session starts capturing logs from that point forward. Optionally describe the issue to focus the analysis |
@@ -87,6 +87,7 @@ Not every command appears for every user. Availability depends on your platform,
| `/powerup` | Discover Claude Code features through quick interactive lessons with animated demos |
| `/pr-comments [PR]` | Removed in v2.1.91. Ask Claude directly to view pull request comments instead. On earlier versions, fetches and displays comments from a GitHub pull request; automatically detects the PR for the current branch, or pass a PR URL or number. Requires the `gh` CLI |
| `/privacy-settings` | View and update your privacy settings. Only available for Pro and Max plan subscribers |
| `/radio` | Open Claude FM lo-fi radio in your browser. Prints the stream URL when no browser is available. Not available on Bedrock, Vertex, or Foundry |
| `/recap` | Generate a one-line summary of the current session on demand. See [Session recap](/en/interactive-mode#session-recap) for the automatic recap that appears after you've been away |
| `/release-notes` | View the changelog in an interactive version picker. Select a specific version to see its release notes, or choose to show all versions |
| `/reload-plugins` | Reload all active [plugins](/en/plugins) to apply pending changes without restarting. Reports counts for each reloaded component and flags any load errors |
@@ -117,6 +117,7 @@ Claude Code supports the following environment variables to control its behavior
| `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_NATIVE_CURSOR` | Set to `1` to show the terminal's own cursor at the input caret instead of a drawn block. The cursor respects the terminal's blink, shape, and focus settings |
| `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 |
@@ -192,6 +193,7 @@ Claude Code supports the following environment variables to control its behavior
| `DISABLE_TELEMETRY` | Set to `1` to opt out of telemetry. Telemetry events do not include user data like code, file paths, or bash commands |
| `DISABLE_UPDATES` | Set to `1` to block all updates including manual `claude update` and `claude install`. Stricter than `DISABLE_AUTOUPDATER`. Use when distributing Claude Code through your own channels and users should not self-update |
| `DISABLE_UPGRADE_COMMAND` | Set to `1` to hide the `/upgrade` command |
| `DO_NOT_TRACK` | Set to `1` to opt out of telemetry. Equivalent to setting `DISABLE_TELEMETRY`. Honored as the [standard cross-tool convention](https://consoledonottrack.com/) |
| `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to disable [claude.ai MCP servers](/en/mcp#use-mcp-servers-from-claude-ai) in Claude Code. Enabled by default for logged-in users |
| `ENABLE_PROMPT_CACHING_1H` | Set to `1` to request a 1-hour prompt cache TTL instead of the default 5 minutes. Intended for API key, [Bedrock](/en/amazon-bedrock), [Vertex](/en/google-vertex-ai), and [Foundry](/en/microsoft-foundry) users. Subscription users receive 1-hour TTL automatically. 1-hour cache writes are billed at a higher rate |
| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Deprecated. Use `ENABLE_PROMPT_CACHING_1H` instead |
@@ -30,6 +30,7 @@ Match the message you see in your terminal to a section below.
| `Not logged in · Please run /login` | [Authentication](#not-logged-in) |
| `Invalid API key` | [Authentication](#invalid-api-key) |
| `This organization has been disabled` | [Authentication](#this-organization-has-been-disabled) |
| `Routines are disabled by your organization's policy` | [Authentication](#routines-are-disabled-by-your-organizations-policy) |
| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |
| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |
| `Unable to connect to API` | [Network](#unable-to-connect-to-api) |
@@ -251,6 +252,21 @@ Environment variables take precedence over `/login`, so a key exported in your s
- Run `/status` afterward to confirm the active credential is your subscription
- If no environment variable is set and the error persists, the disabled organization is the one tied to your `/login`. Contact support or sign in with a different account.
### Routines are disabled by your organization's policy
Your Team or Enterprise admin has turned off routines at the organization level. The error appears when you try to create or run a routine, including from `/schedule` and the [Routines](/en/routines) UI on claude.ai/code.
```text
Routines are disabled by your organization's policy.
```
This is a server-side setting, so it cannot be overridden from local settings, environment variables, or CLI flags.
**What to do:**
- Ask your admin to enable the **Routines** toggle at [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)
- For one-off scheduled work that does not require organization-level routines, see [scheduled tasks](/en/scheduled-tasks)
### OAuth token revoked or expired
Your saved login is no longer valid. A revoked token means you signed out everywhere or an admin removed access; an expired token means the automatic refresh failed mid-session.
@@ -284,7 +284,7 @@ When you first open a session, a grayed-out example command appears in the promp
After Claude responds, suggestions continue to appear based on your conversation history, such as a follow-up step from a multi-part request or a natural continuation of your workflow.
- Press **Tab** or **Right arrow** to accept the suggestion, or press **Enter** to accept and submit
- Press **Tab** or **Right arrow** to place the suggestion in the prompt input, then **Enter** to submit
- Start typing to dismiss it
The suggestion runs as a background request that reuses the parent conversation's prompt cache, so the additional cost is minimal. Claude Code skips suggestion generation when the cache is cold to avoid unnecessary cost.
@@ -54,6 +54,8 @@ claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
```
When configuring MCP servers via JSON in `.mcp.json`, `~/.claude.json`, or `claude mcp add-json`, the `type` field accepts `streamable-http` as an alias for `http`. The MCP specification uses the name `streamable-http` for this transport, so configurations copied from server documentation work without modification.
### Option 2: Add a remote SSE server
The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available.
@@ -201,6 +201,13 @@ Examples:
- `Edit(//tmp/scratch.txt)`: edits the absolute path `/tmp/scratch.txt`
- `Read(src/**)`: reads from `<current-directory>/src/`
A rule only matches files under its anchor, so the anchor determines how far a deny rule reaches. Bare filenames follow gitignore semantics and match at any depth, so `Read(.env)` and `Read(**/.env)` are equivalent:
| Deny rule | Blocks | Does not block |
| - | - | - |
| `Read(.env)` or `Read(**/.env)` | any `.env` at or under the current directory | `.env` in a parent directory or another project |
| `Read(//**/.env)` | any `.env` anywhere on the filesystem | nothing; the rule is anchored at the filesystem root |
In gitignore patterns, `*` matches files in a single directory while `**` matches recursively across directories. To allow all file access, use just the tool name without parentheses: `Read`, `Edit`, or `Write`.
When Claude accesses a symlink, permission rules check two paths: the symlink itself and the file it resolves to. Allow and deny rules treat that pair differently: allow rules fall back to prompting you, while deny rules block outright.
@@ -418,7 +418,7 @@ agent `agent-creator` for the plugin with name `plugin-dev` will appear as
| Field | Type | Description | Example |
| :- | :- | :- | :- |
| `skills` | string\|array | Custom skill directories containing `<name>/SKILL.md` (replaces default `skills/`) | `"./custom/skills/"` |
| `skills` | string\|array | Custom skill directories containing `<name>/SKILL.md` (in addition to default `skills/`) | `"./custom/skills/"` |
| `commands` | string\|array | Custom flat `.md` skill files or directories (replaces default `commands/`) | `"./custom/cmd.md"` or `["./cmd1.md"]` |
| `agents` | string\|array | Custom agent files (replaces default `agents/`) | `"./custom/agents/reviewer.md"` |
| `hooks` | string\|array\|object | Hook config paths or inline config | `"./my-extra-hooks.json"` |
@@ -505,12 +505,17 @@ The `server` field is required and must match a key in the plugin's `mcpServers`
### Path behavior rules
For `skills`, `commands`, `agents`, `outputStyles`, `experimental.themes`, and `experimental.monitors`, a custom path replaces the default. If the manifest specifies `skills`, the default `skills/` directory is not scanned; if it specifies `experimental.monitors`, the default `monitors/monitors.json` is not loaded. [Hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers) have different semantics for handling multiple sources.
Whether a custom path replaces or extends the plugin's default directory depends on the field:
- **Replaces the default**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. For example, when the manifest specifies `commands`, the default `commands/` directory is not scanned. To keep the default and add more, list it explicitly: `"commands": ["./commands/", "./extras/"]`
- **Adds to the default**: `skills`. The default `skills/` directory is always scanned, and directories listed in `skills` are loaded alongside it
- **Own merge rules**: [hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers). See each section for how multiple sources combine
For all path fields:
- All paths must be relative to the plugin root and start with `./`
- Components from custom paths use the same naming and namespacing rules
- Multiple paths can be specified as arrays
- To keep the default directory and add more paths for skills, commands, agents, or output styles, include the default in your array: `"skills": ["./skills/", "./extras/"]`
- When a skill path points to a directory that contains a `SKILL.md` directly, for example `"skills": ["./"]` pointing to the plugin root, the frontmatter `name` field in `SKILL.md` determines the skill's invocation name. This gives a stable name regardless of the install directory. If `name` is not set in the frontmatter, the directory basename is used as a fallback.
**Path examples**:
@@ -297,6 +297,12 @@ When a routine hits the daily cap or your subscription usage limit, organization
One-off runs do not count against the daily routine cap. They draw down your regular subscription usage like any other session, but they are exempt from the per-account daily routine run allowance.
## Troubleshooting
### "Routines are disabled by your organization's policy"
Your Team or Enterprise admin has likely turned off the **Routines** toggle at [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code). This is a server-side organization setting, so it cannot be overridden from your local configuration. Contact your admin to request that routines be enabled for your organization.
## Related resources
- [`/loop` and in-session scheduling](/en/scheduled-tasks): schedule local tasks within an open CLI session
@@ -60,7 +60,7 @@ For full details, please review our [Commercial Terms of Service](https://www.an
- **Network request approval**: Tools that make network requests require user approval by default
- **Isolated context windows**: Web fetch uses a separate context window to avoid injecting potentially malicious prompts
- **Trust verification**: First-time codebase runs and new MCP servers require trust verification
- Note: Trust verification is disabled when running non-interactively with the `-p` flag
- Note: Trust verification is disabled when running non-interactively with the `-p` flag. The exception is [`--worktree`](/en/worktrees), which still requires that trust has been accepted for the directory
- **Command injection detection**: Suspicious bash commands require manual approval even if previously allowlisted
- **Fail-closed matching**: Unmatched commands default to requiring manual approval
- **Natural language descriptions**: Complex bash commands include explanations for user understanding
@@ -36,7 +36,7 @@ If your devices are enrolled in an MDM or endpoint management solution, endpoint
In [Claude.ai](https://claude.ai), navigate to **Admin Settings > Claude Code > Managed settings**.
Add your configuration as JSON. All [settings available in `settings.json`](/en/settings#available-settings) are supported, including [hooks](/en/hooks), [environment variables](/en/env-vars), and [managed-only settings](/en/permissions#managed-only-settings) like `allowManagedPermissionRulesOnly`.
Add your configuration as JSON. All [settings available in `settings.json`](/en/settings#available-settings) are supported except those restricted to OS-level policy delivery; see [Current limitations](#current-limitations) for that short list. This includes [hooks](/en/hooks), [environment variables](/en/env-vars), and [managed-only settings](/en/permissions#managed-only-settings) like `allowManagedPermissionRulesOnly`.
This example enforces a permission deny list, prevents users from bypassing permissions, and restricts permission rules to those defined in managed settings:
@@ -88,7 +88,7 @@ To configure the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mo
}
```
Because hooks execute shell commands, users see a [security approval dialog](#security-approval-dialogs) before they're applied. See [Configure auto mode](/en/auto-mode-config) for how the `autoMode` entries affect what the classifier blocks and important warnings about the `allow` and `soft_deny` fields.
Because hooks execute shell commands, users see a [security approval dialog](#security-approval-dialogs) before they're applied. See [Configure auto mode](/en/auto-mode-config) for how the `autoMode` entries affect what the classifier blocks and important warnings about the `environment`, `allow`, `soft_deny`, and `hard_deny` fields.
Save your changes. Claude Code clients receive the updated settings on their next startup or hourly polling cycle.
@@ -115,6 +115,7 @@ Server-managed settings have the following limitations:
- Settings apply uniformly to all users in the organization. Per-group configurations are not yet supported.
- [MCP server configurations](/en/mcp#managed-mcp-configuration) cannot be distributed through server-managed settings.
- Settings restricted to OS-level policy sources, such as `policyHelper` and `wslInheritsWindowsSettings`, are not honored. Deploy them through MDM or a system `managed-settings.json` file instead.
## Settings delivery
@@ -167,7 +167,7 @@ The published schema is updated periodically and may not include settings added
| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts an absolute path or a `~/`-prefixed path. Accepted from policy and user settings, and from the `--settings` flag. Not accepted from project or local settings, since a cloned repository could supply either file to redirect memory writes to sensitive locations | `"~/my-memory-dir"` |
| `autoMemoryEnabled` | Enable [auto memory](/en/memory#enable-or-disable-auto-memory). When `false`, Claude does not read from or write to the auto memory directory. Default: `true`. You can also toggle this with `/memory` during a session. To disable via environment variable, set [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/en/env-vars) in `env` | `false` |
| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/en/auto-mode-config). Not read from shared project settings | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |
| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, `soft_deny`, and `hard_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/en/auto-mode-config). Not read from shared project settings | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |
| `autoScrollEnabled` | In [fullscreen rendering](/en/fullscreen), follow new output to the bottom of the conversation. Default: `true`. Appears in `/config` as **Auto-scroll**. Permission prompts still scroll into view when this is off | `false` |
| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release. To disable auto-updates entirely, set [`DISABLE_AUTOUPDATER`](/en/setup#disable-auto-updates) in `env` | `"stable"` |
| `availableModels` | Restrict which models users can select via `/model`, `--model`, or `ANTHROPIC_MODEL`. Does not affect the Default option. See [Restrict model selection](/en/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |
@@ -213,6 +213,7 @@ The published schema is updated periodically and may not include settings added
| `permissions` | See table below for structure of permissions. | |
| `plansDirectory` | Customize where plan files are stored. Path is relative to project root. Default: `~/.claude/plans` | `"./plans"` |
| `pluginTrustMessage` | (Managed settings only) Custom message appended to the plugin trust warning shown before installation. Use this to add organization-specific context, for example to confirm that plugins from your internal marketplace are vetted. | `"All plugins from our marketplace are approved by IT"` |
| `policyHelper` | Admin-deployed executable that computes managed settings dynamically at startup. Only honored from MDM or a system `managed-settings.json` file. See [Compute managed settings with a policy helper](#compute-managed-settings-with-a-policy-helper). Requires Claude Code v2.1.136 or later | `{"path": "/usr/local/bin/claude-policy"}` |
| `preferredNotifChannel` | Method for task-complete and permission-prompt notifications: `"auto"`, `"terminal_bell"`, `"iterm2"`, `"iterm2_with_bell"`, `"kitty"`, `"ghostty"`, or `"notifications_disabled"`. Default: `"auto"`, which sends a desktop notification in iTerm2, Ghostty, and Kitty and does nothing in other terminals. Set `"terminal_bell"` to ring the bell character in any terminal. Appears in `/config` as **Notifications**. See [Get a terminal bell or notification](/en/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |
| `prefersReducedMotion` | Reduce or disable UI animations (spinners, shimmer, flash effects) for accessibility | `true` |
| `prUrlTemplate` | URL template for the PR badge shown in the footer and in tool-result summaries. Substitutes `{host}`, `{owner}`, `{repo}`, `{number}`, and `{url}` from the `gh`-reported PR URL. Use to point PR links at an internal code-review tool instead of `github.com`. Does not affect `#123` autolinks in Claude's prose | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |
@@ -464,6 +465,32 @@ Limit which environment variable names HTTP hooks can interpolate into header va
}
```
### Compute managed settings with a policy helper
The `policyHelper` setting points at an executable that computes managed settings at startup, so admins can derive policy from device posture, identity, or a remote service instead of a static file. Configure it from MDM or a system `managed-settings.json` file. Claude Code ignores `policyHelper` when it appears in any other scope, including user settings, project settings, the HKCU registry hive, and [server-managed settings](/en/server-managed-settings).
The setting accepts these keys:
| Key | Type | Description |
| - | - | - |
| `path` | string | Absolute path to the helper executable |
| `timeoutMs` | number | How long to wait for the helper before treating the run as failed |
| `refreshIntervalMs` | number | How often to re-run the helper in the background. Set to `0` to disable refresh, or to at least `60000` |
The helper writes a JSON envelope to stdout. Put the settings under a `managedSettings` key rather than at the top level, since a bare settings object parses with `managedSettings` undefined and applies nothing:
```json
{
"managedSettings": {
"permissions": { "deny": ["Read(//etc/secrets/**)"] }
},
"claudeMd": "# Organization context\n...",
"appendSystemPrompt": "Always cite the internal style guide."
}
```
When the helper emits `managedSettings`, that object replaces the file-based managed settings for the run. When the helper exits non-zero at startup, Claude Code prints the error and refuses to start, so a helper that needs outage resilience should serve from its own cache and exit `0`.
### Settings precedence
Settings apply in order of precedence. From highest to lowest:
@@ -5,7 +5,7 @@ source: https://code.claude.com/docs/en/whats-new/2026-w16.md
# Week 16 · April 13–17, 2026
> Claude Opus 4.7 with the new xhigh effort level, Routines on Claude Code on the web, /ultrareview cloud code review, a /usage breakdown that shows what's driving your limits, and native binaries replacing the bundled JavaScript.
> Claude Opus 4.7 with the new xhigh effort level, Routines on Claude Code on the web, mobile push notifications that ping your phone when Claude needs you, a /usage breakdown that shows what's driving your limits, and native binaries replacing the bundled JavaScript.
Releases v2.1.105 → v2.1.113
5 features · April 13–17
@@ -50,24 +50,18 @@ Run it any time:
Commands reference
/ultrareview
v2.1.111
Mobile push notifications
mobile
Comprehensive code review in the cloud. Ultrareview fans your branch out across parallel reviewers on Claude Code on the web, runs an adversarial critique pass over each finding, and returns a verified findings report while your terminal stays free. Call it with no arguments to review your current branch, or pass a PR number to fetch and review that PR. The launch dialog now shows a diffstat so you know what's going up before you confirm.
With Remote Control connected, Claude can send a push notification to your phone when a long task finishes or it needs a decision to keep going. Turn it on with "Push when Claude decides" in /config, or ask for one in your prompt. Useful when you kick off a long agent run and want to step away from the terminal.
Review the branch you're on:
Ask Claude to ping you when it's done:
```text Claude Code theme={null}
> /ultrareview
> notify me when the tests pass
```
Or point it at a PR:
```text Claude Code theme={null}
> /ultrareview 1234
```
Ultrareview guide
Remote Control: mobile push notifications
Native binaries
v2.1.113
@@ -85,10 +79,10 @@ Setup guide
Other wins
New /ultrareview: comprehensive code review in the cloud using parallel multi-agent analysis and an adversarial critique pass. Run it bare to review your current branch, or /ultrareview \<PR#> for a specific PR
Auto mode is now available for Max subscribers on Opus 4.7, and the --enable-auto-mode flag is no longer required
Session recap shows a one-line summary of what happened while you were away; run /recap on demand or turn it off from /config
New /tui command and tui setting switch between classic and flicker-free rendering mid-conversation; focus view moved from Ctrl+O to its own /focus command
Push notification tool: with Remote Control connected and "Push when Claude decides" enabled, Claude can ping your phone when it needs you
Plugins can ship background watchers via a top-level monitors manifest key that auto-arms at session start or on skill invoke
"Auto (match terminal)" option in /theme follows your terminal's dark/light mode
/fewer-permission-prompts scans your transcripts for common read-only Bash and MCP calls and proposes an allowlist for .claude/settings.json
@@ -0,0 +1,92 @@
---
title: 2026-w18
source: https://code.claude.com/docs/en/whats-new/2026-w18.md
---
# Week 18 · April 27 – May 1, 2026
> Claude Code on Windows runs without Git Bash, claude auth login accepts a pasted OAuth code when the browser callback can't reach localhost, claude project purge cleans up local state per project, and pasting a PR URL into /resume finds the session that created it.
Releases v2.1.120 → v2.1.126
4 features · April 27 – May 1
Sign in without a browser callback
v2.1.126
claude auth login now accepts the OAuth code pasted directly into the terminal when the browser callback can't reach localhost. That covers WSL2, SSH sessions, and containers, where the redirect to a local port doesn't work. The same release also fixes login timeouts on slow or proxied connections and in IPv6-only devcontainers.
Sign in, then paste the code from the browser:
```bash theme={null}
claude auth login
```
CLI reference
claude project purge
v2.1.126
Delete all Claude Code state for a project: transcripts, tasks, file history, and the project's config entry. Supports `--dry-run` to preview, `-y`/`--yes` to skip confirmation, `-i`/`--interactive` to choose, and `--all` to clear every project.
Preview what would be removed:
```bash theme={null}
claude project purge --dry-run
```
Then run it for real:
```bash theme={null}
claude project purge
```
CLI reference
Resume by PR URL
v2.1.122
When you create a pull request with gh pr create, Claude Code links it to the session that produced it. Now you can get back to that session from the PR URL alone, without remembering its name.
Open the session picker:
```text Claude Code theme={null}
> /resume
```
Paste the PR URL into the picker. The first character of the paste drops you into search mode, and the list filters to the session that created that PR. Press Enter to resume it. GitHub, GitHub Enterprise, GitLab, and Bitbucket pull and merge request URLs all work.
```text Claude Code theme={null}
https://github.com/your-org/your-repo/pull/1234
```
To skip the picker, pass the PR number on the command line instead:
```bash theme={null}
claude --from-pr 1234
```
Sessions: use the session picker
Windows without Git Bash
Windows
Git for Windows is no longer required. When Bash is absent, Claude Code uses PowerShell as the shell tool, and when the PowerShell tool is enabled it is treated as the primary shell. PowerShell 7 installed via the Microsoft Store, MSI without PATH, or a .NET global tool is now detected automatically.
Setup guide
Other wins
MCP servers can opt out of tool-search deferral with alwaysLoad: true in their config so all of that server's tools are always available
New claude plugin prune removes orphaned auto-installed plugin dependencies, and plugin uninstall --prune cascades
/skills now has a type-to-filter search box so you can find a skill in a long list without scrolling
PostToolUse hooks can replace tool output for any tool via hookSpecificOutput.updatedToolOutput, not only MCP tools
New claude ultrareview subcommand runs /ultrareview non-interactively from CI or scripts: prints findings to stdout (--json for raw output) and exits 0 on completion or 1 on failure
\--dangerously-skip-permissions now bypasses prompts for writes to .claude/, .git/, .vscode/, shell config files, and other previously protected paths, while catastrophic removal commands still prompt as a safety net
The /model picker can list models from your gateway's /v1/models endpoint when ANTHROPIC\_BASE\_URL points at an Anthropic-compatible gateway; opt in with CLAUDE\_CODE\_ENABLE\_GATEWAY\_MODEL\_DISCOVERY=1 since v2.1.129
MCP servers that hit a transient error during startup now auto-retry up to 3 times instead of staying disconnected
ANTHROPIC\_BEDROCK\_SERVICE\_TIER selects a Bedrock service tier: default, flex, or priority
/terminal-setup enables iTerm2's clipboard access setting so /copy works, including from tmux
Vertex AI now supports X.509 certificate-based Workload Identity Federation (mTLS ADC)
Significant memory leak fixes: image-heavy sessions, /usage on large transcript histories, and long-running tools without progress events
[Full changelog for v2.1.120–v2.1.126 →](/en/changelog#2-1-120)
@@ -0,0 +1,47 @@
---
title: 2026-w19
source: https://code.claude.com/docs/en/whats-new/2026-w19.md
---
# Week 19 · May 4–8, 2026
> Load plugins from .zip archives and URLs, search command history across every project with Ctrl+R, branch new worktrees from local HEAD or the remote default, and block actions unconditionally with auto mode hard deny rules.
Releases v2.1.128 → v2.1.136
2 features · May 4–8
Plugins from .zip archives and URLs
`--plugin-dir` now accepts a .zip plugin archive in addition to a directory, and the new `--plugin-url` flag fetches a plugin archive from a URL for the current session. Useful for trying a plugin before adding it to a marketplace, or for shipping internal plugins from an artifact store.
Load a plugin straight from a URL:
```bash terminal theme={null}
claude --plugin-url https://example.com/my-plugin.zip
```
Plugins guide
History search across all your projects
v2.1.129
Ctrl+R reverse-search now defaults to all prompts across every project, restoring the behavior from before v2.1.124. Press Ctrl+S while searching to narrow back to the current project or session. Handy when you remember a command you ran in another repo last week and don't want to go digging for it.
Interactive mode: command history
Other wins
New worktree.baseRef setting (fresh | head) controls whether --worktree, the EnterWorktree tool, and agent-isolation worktrees branch from the remote default branch or local HEAD; the default fresh keeps unpushed commits out of new worktrees
New settings.autoMode.hard\_deny rules block matching actions unconditionally in auto mode, regardless of allow exceptions, for actions that should never run automatically even when broader allow rules apply
Hooks now receive the active effort level via the `effort.level` JSON input field and the `$CLAUDE_EFFORT` environment variable, and Bash tool commands can read $CLAUDE\_EFFORT
CLAUDE\_CODE\_DISABLE\_ALTERNATE\_SCREEN=1 opts out of the fullscreen alternate-screen renderer and keeps the conversation in the terminal's native scrollback
CLAUDE\_CODE\_PACKAGE\_MANAGER\_AUTO\_UPDATE lets Homebrew or WinGet installations run the upgrade in the background and prompt to restart
CLAUDE\_CODE\_SESSION\_ID is now in the Bash tool subprocess environment, matching the session\_id passed to hooks
/mcp now shows the tool count for connected servers and flags servers that connected with 0 tools
\--channels now works with console (API key) authentication
Subprocesses such as Bash, hooks, MCP, and LSP no longer inherit OTEL\_\* environment variables, so OTEL-instrumented apps run via the Bash tool no longer pick up the CLI's own OTLP endpoint
Sub-agent progress summaries now hit the prompt cache, cutting cache\_creation token cost by roughly 3x
Several OAuth and credential reliability fixes: parallel sessions no longer dead-end at 401 after a refresh-token race, MCP OAuth refresh tokens are no longer lost when multiple servers refresh concurrently, and a rare login loop from a concurrent credential write is fixed
New parentSettingsBehavior admin key lets admins opt SDK managedSettings into the policy merge
[Full changelog for v2.1.128–v2.1.136 →](/en/changelog#2-1-128)
@@ -9,6 +9,18 @@ source: https://code.claude.com/docs/en/whats-new/index.md
The weekly dev digest highlights the features most likely to change how you work. Each entry includes runnable code, a short demo, and a link to the full docs. For every bug fix and minor improvement, see the [changelog](/en/changelog).
**Plugins load from `.zip` archives and URLs**: `--plugin-dir` now accepts `.zip` files, and `--plugin-url` fetches a plugin archive for the current session.
Also this week: **`worktree.baseRef`** chooses whether new worktrees branch from the remote default or local `HEAD`; **auto mode hard deny rules** block actions unconditionally regardless of allow exceptions; and **hooks see the active effort level** via `effort.level` and `$CLAUDE_EFFORT`.
[Read the Week 19 digest →](/en/whats-new/2026-w19)
**Windows without Git Bash**: Git for Windows is no longer required, and Claude Code uses PowerShell as the shell tool when Bash is absent.
Also this week: **`claude ultrareview`** brings cloud code review to CI and scripts; **`claude project purge`** cleans up local state for a project; and pasting a **PR URL into `/resume`** finds the session that created it.
[Read the Week 18 digest →](/en/whats-new/2026-w18)
**`/ultrareview`** opens as a public research preview: a fleet of bug-hunting agents runs in the cloud and findings land back in your CLI or Desktop automatically.
Also this week: **session recap** shows you what happened while a terminal was unfocused; **custom themes** let you build and ship color palettes from `/theme` or a plugin; and **Claude Code on the web** gets a redesign with a new sessions sidebar and drag-and-drop layout.
@@ -17,7 +29,7 @@ Also this week: **session recap** shows you what happened while a terminal was u
**Claude Opus 4.7** lands as the new default on Max and Team Premium, with a new `xhigh` effort level that's the recommended setting for most coding work and an interactive `/effort` slider to dial it in.
Also this week: **Routines** on Claude Code on the web fire templated cloud agents from a schedule, GitHub event, or API call; `/ultrareview` runs parallel multi-agent code review in the cloud; `/usage` shows what's driving your limits; and the CLI moves to native binaries.
Also this week: **Routines** on Claude Code on the web fire templated cloud agents from a schedule, GitHub event, or API call; **mobile push notifications** ping your phone when a long task finishes or Claude needs you; `/usage` shows what's driving your limits; and the CLI moves to native binaries.
[Read the Week 16 digest →](/en/whats-new/2026-w16)