19 ファイル変更 +79 -80
この更新の概要
Agent SDKの計画モード（plan mode）が更新され、ソースファイルの編集は行わないものの読み取り専用ツールの実行が可能になりました。設定ソース（settingSources）のデフォルト挙動がCLIと一致するように変更され、明示的に空配列を指定しない限りローカル設定が読み込まれるようになっています。プラグインスキルの命名規則に名前空間が導入されたほか、ウェブ環境でのセットアップ制限やTLS証明書ストアに関するネットワーク設定の解説が詳細化されました。
カスタムツールの並列実行を有効にするためのreadOnlyHint属性の設定方法と、planモードにおける読み取り専用ツールの動作について追記されました。
@@ -136,7 +136,7 @@ When a tool is denied, Claude receives a rejection message as the tool result an
When Claude requests multiple tool calls in a single turn, both SDKs can run them concurrently or sequentially depending on the tool. Read-only tools (like `Read`, `Glob`, `Grep`, and MCP tools marked as read-only) can run concurrently. Tools that modify state (like `Edit`, `Write`, and `Bash`) run sequentially to avoid conflicts.
Custom tools default to sequential execution. To enable parallel execution for a custom tool, mark it as read-only in its annotations: `readOnly` in [TypeScript](/en/agent-sdk/typescript#tool) or `readOnlyHint` in [Python](/en/agent-sdk/python#tool).
Custom tools default to sequential execution. To enable parallel execution for a custom tool, set `readOnlyHint` in its annotations. Both the [TypeScript](/en/agent-sdk/typescript#tool) and [Python](/en/agent-sdk/python#tool) SDKs use this field name from the MCP SDK.
## Control how the loop runs
@@ -167,7 +167,7 @@ If you don't set `effort`, the Python SDK leaves the parameter unset and defers
`effort` trades latency and token cost for reasoning depth within each response. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is a separate feature that produces visible chain-of-thought blocks in the output. They are independent: you can set `effort: "low"` with extended thinking enabled, or `effort: "max"` without it.
Use lower effort for agents doing simple, well-scoped tasks (like listing files or running a single grep) to reduce cost and latency. `effort` is set at the top-level `query()` options, not per-subagent.
Use lower effort for agents doing simple, well-scoped tasks (like listing files or running a single grep) to reduce cost and latency. Set `effort` in the top-level `query()` options for the whole session, or per subagent with the `effort` field on [`AgentDefinition`](/en/agent-sdk/subagents#agentdefinition-configuration) to override the session level.
### Permission mode
@@ -177,7 +177,7 @@ The permission mode option (`permission_mode` in Python, `permissionMode` in Typ
| :- | :- |
| `"default"` | Tools not covered by allow rules trigger your approval callback; no callback means deny |
| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules |
| `"plan"` | No tool execution; Claude produces a plan for review |
| `"plan"` | Read-only tools run; Claude explores and produces a plan without editing your source files |
| `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/en/settings#permission-settings) run, everything else is denied |
| `"auto"` (TypeScript only) | 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 |
| `"bypassPermissions"` | Runs all allowed tools without asking. 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 |
SDKのデフォルト設定がリバートされ、設定ソースを省略した際にCLIと同様にローカル設定が読み込まれる仕様へ変更されたことが明記されました。
@@ -200,28 +200,19 @@ async for message in query(
**Why this changed:** Provides better control and isolation for SDK applications. You can now build agents with custom behavior without inheriting Claude Code's CLI-focused instructions.
### Settings Sources No Longer Loaded by Default
### Settings sources default
**What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default.
This default was briefly changed in v0.1.0 and then reverted, so no migration action is needed.
**Migration:**
**Current behavior:** Omitting `settingSources` on `query()` loads user, project, and local filesystem settings, matching the CLI. This includes `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, CLAUDE.md files, and custom commands.
To run isolated from filesystem settings, pass an empty array:
```typescript TypeScript theme={null}
// BEFORE (v0.0.x) - Loaded all settings automatically
const result = query({ prompt: "Hello" });
// Would read from:
// - ~/.claude/settings.json (user)
// - .claude/settings.json (project)
// - .claude/settings.local.json (local)
// - CLAUDE.md files
// - Custom slash commands
// AFTER (v0.1.0) - No settings loaded by default
// To get the old behavior:
const result = query({
prompt: "Hello",
options: {
settingSources: ["user", "project", "local"]
settingSources: [] // No filesystem settings loaded
}
});
@@ -235,23 +226,11 @@ const result = query({
```
```python Python theme={null}
# BEFORE (v0.0.x) - Loaded all settings automatically
async for message in query(prompt="Hello"):
print(message)
# Would read from:
# - ~/.claude/settings.json (user)
# - .claude/settings.json (project)
# - .claude/settings.local.json (local)
# - CLAUDE.md files
# - Custom slash commands
# AFTER (v0.1.0) - No settings loaded by default
# To get the old behavior:
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=["user", "project", "local"]),
options=ClaudeAgentOptions(setting_sources=[]), # No filesystem settings loaded
):
print(message)
@@ -265,14 +244,9 @@ async for message in query(
print(message)
```
**Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for:
- **CI/CD environments** - Consistent behavior without local customizations
- **Deployed applications** - No dependency on filesystem settings
- **Testing** - Isolated test environments
- **Multi-tenant systems** - Prevent settings leakage between users
Isolation is especially important for CI/CD pipelines, deployed applications, test environments, and multi-tenant systems where local customizations should not leak in.
Current SDK releases have reverted this default for `query()`: omitting the option once again loads user, project, and local settings, matching the CLI. Pass `settingSources: []` in TypeScript or `setting_sources=[]` in Python if your application depends on the isolated behavior described above. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`.
SDK v0.1.0 briefly defaulted to no settings loaded; this was reverted in subsequent releases. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`.
## Why the Rename?
許可モードのplanにおける読み取り専用ツールの実行権限と、Python SDKでのClaudeSDKClientを使用した新しい実装例が追加されました。
@@ -15,7 +15,7 @@ This page covers permission modes and rules. To build interactive approval flows
When Claude requests a tool, the SDK checks permissions in this order:
Run [hooks](/en/agent-sdk/hooks) first, which can allow, deny, or continue to the next step
Run [hooks](/en/agent-sdk/hooks) first. A hook can deny the call outright or pass it on. A hook that returns `allow` does not skip the deny and ask rules below; those are evaluated regardless of the hook result.
Check `deny` rules (from `disallowed_tools` and [settings.json](/en/settings#permission-settings)). If a deny rule matches, the tool is blocked, even in `bypassPermissions` mode.
@@ -66,7 +66,7 @@ The SDK supports these permission modes:
| `dontAsk` | Deny instead of prompting | Anything not pre-approved by `allowed_tools` or rules is denied; `canUseTool` is never called |
| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved |
| `bypassPermissions` | Bypass all permission checks | All tools run without permission prompts (use with caution) |
| `plan` | Planning mode | No tool execution; Claude plans without making changes |
| `plan` | Planning mode | Read-only tools run; Claude analyzes and plans without editing your source files |
| `auto` (TypeScript only) | 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 |
**Subagent inheritance:** When the parent uses `bypassPermissions`, `acceptEdits`, or `auto`, all subagents inherit that mode and it cannot be overridden per subagent. Subagents may have different system prompts and less constrained behavior than your main agent, so inheriting `bypassPermissions` grants them full, autonomous system access without any approval prompts.
@@ -117,23 +117,23 @@ Call `set_permission_mode()` (Python) or `setPermissionMode()` (TypeScript) to c
```python Python theme={null}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
async def main():
q = query(
prompt="Help me refactor this code",
async with ClaudeSDKClient(
options=ClaudeAgentOptions(
permission_mode="default", # Start in default mode
),
)
)
) as client:
await client.query("Help me refactor this code")
# Change mode dynamically mid-session
await q.set_permission_mode("acceptEdits")
# Change mode dynamically mid-session
await client.set_permission_mode("acceptEdits")
# Process messages with the new permission mode
async for message in q:
if hasattr(message, "result"):
print(message.result)
# Process messages with the new permission mode
async for message in client.receive_response():
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
```
@@ -194,7 +194,7 @@ Use with extreme caution. Claude has full system access in this mode. Only use i
#### Plan mode (`plan`)
Prevents tool execution entirely. Claude can analyze code and create plans but cannot make changes. Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for handling these prompts.
Restricts Claude to read-only tools. Claude can read files and run read-only shell commands to explore the codebase but does not edit your source files. Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for handling these prompts.
**Use when:** you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they're made.
@@ -1020,7 +1020,7 @@ Permission modes for controlling tool execution.
PermissionMode = Literal[
"default", # Standard permission behavior
"acceptEdits", # Auto-accept file edits
"plan", # Planning mode - no execution
"plan", # Planning mode - read-only tools only
"dontAsk", # Deny anything not pre-approved instead of prompting
"bypassPermissions", # Bypass all permission checks (use with caution)
]
@@ -87,7 +87,7 @@ class StreamEvent:
```typescript TypeScript theme={null}
type SDKPartialAssistantMessage = {
type: "stream_event";
event: RawMessageStreamEvent; // From Anthropic SDK
event: BetaRawMessageStreamEvent; // From Anthropic SDK
parent_tool_use_id: string | null;
uuid: UUID;
session_id: string;
@@ -57,11 +57,11 @@ for await (const message of query({
```
```python Python theme={null}
from claude_agent_sdk import query, AssistantMessage, ToolUseBlock
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
async for message in query(
prompt="Optimize my React app performance and track progress with todos",
options={"max_turns": 15},
options=ClaudeAgentOptions(max_turns=15),
):
# Todo updates are reflected in the message stream
if isinstance(message, AssistantMessage):
@@ -130,7 +130,7 @@ await tracker.trackQuery("Build a complete authentication system with todos");
```
```python Python theme={null}
from claude_agent_sdk import query, AssistantMessage, ToolUseBlock
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
from typing import List, Dict
class TodoTracker:
@@ -164,7 +164,7 @@ class TodoTracker:
print(f"{i + 1}. {icon} {text}")
async def track_query(self, prompt: str):
async for message in query(prompt=prompt, options={"max_turns": 20}):
async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
@@ -621,7 +621,7 @@ type PermissionMode =
| "default" // Standard permission behavior
| "acceptEdits" // Auto-accept file edits
| "bypassPermissions" // Bypass all permission checks
| "plan" // Planning mode - no execution
| "plan" // Planning mode - read-only tools only
| "dontAsk" // Don't prompt for permissions, deny if not pre-approved
| "auto"; // Use a model classifier to approve or deny each tool call
```
@@ -174,6 +174,8 @@ apt update && apt install -y gh
If the script exits non-zero, the session fails to start. Append `|| true` to non-critical commands to avoid blocking the session on an intermittent install failure.
Keep the script's total runtime under roughly five minutes so the [environment cache](#environment-caching) can build. Run independent installs in parallel with `&` and `wait`. If a single download won't fit in the five-minute limit, move it to a [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) that launches it in the background.
Setup scripts that install packages need network access to reach registries. The default **Trusted** network access allows connections to [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io. Scripts will fail to install packages if your environment uses **None** network access.
### Environment caching
@@ -61,7 +61,7 @@ Claude Code supports the following environment variables to control its behavior
| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Set to `0` to omit the attribution block (client version and prompt fingerprint) from the start of the system prompt. Disabling it improves prompt-cache hit rates when routing through an [LLM gateway](/en/llm-gateway). Anthropic API caching is unaffected |
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for [extended context](/en/model-config#extended-context) models. Use a lower value like `500000` on a 1M model to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window |
| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Override automatic [IDE connection](/en/vs-code). By default, Claude Code connects automatically when launched inside a supported IDE's integrated terminal. Set to `false` to prevent this. Set to `true` to force a connection attempt when auto-detection fails, such as when tmux obscures the parent terminal |
| `CLAUDE_CODE_CERT_STORE` | Comma-separated list of CA certificate sources for TLS connections. `bundled` is the Mozilla CA set shipped with Claude Code. `system` is the operating system trust store. Default is `bundled,system`. The native binary distribution is required for system store integration. On the Node.js runtime, only the bundled set is used regardless of this value |
| `CLAUDE_CODE_CERT_STORE` | Comma-separated list of CA certificate sources for TLS connections. `bundled` is the Mozilla CA set shipped with Claude Code. `system` is the operating system trust store. Default is `bundled,system` |
| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |
| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |
| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |
@@ -306,7 +306,7 @@ Common causes include no internet access, a VPN that blocks `api.anthropic.com`,
- Ensure your firewall allows the hosts listed in [Network access requirements](/en/network-config#network-access-requirements)
- Intermittent failures are [retried automatically](#automatic-retries); persistent failures point to a local network issue
If `curl` succeeds but Claude Code still fails, the cause is usually something between Node.js and the network rather than the network itself:
If `curl` succeeds but Claude Code still fails, the cause is usually something between the runtime and the network rather than the network itself:
- On Linux and WSL, check `/etc/resolv.conf` for an unreachable nameserver. WSL in particular can inherit a broken resolver from the host.
- On macOS, a VPN client that was disconnected or uninstalled can leave a tunnel interface or routing rule behind. Check `ifconfig` for stale `utun` interfaces and remove the VPN's network extension in System Settings.
@@ -314,7 +314,7 @@ If `curl` succeeds but Claude Code still fails, the cause is usually something b
### SSL certificate errors
A proxy or security appliance on your network is intercepting TLS traffic with its own certificate, and Node.js does not trust it.
A proxy or security appliance on your network is intercepting TLS traffic with its own certificate, and Claude Code does not trust it.
```text
Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates
@@ -323,7 +323,7 @@ Unable to connect to API: Self-signed certificate detected
**What to do:**
- Export your organization's CA bundle and point Node at it with `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`
- Export your organization's CA bundle and point Claude Code at it with `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`
- See [Network configuration](/en/network-config#custom-ca-certificates) for full setup instructions
- Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0`, which disables certificate validation entirely
@@ -127,6 +127,7 @@ Enable vim-style editing via `/config` → Editor mode.
| Command | Action |
| :- | :- |
| `h`/`j`/`k`/`l` | Move left/down/up/right |
| `Space` | Move right |
| `w` | Next word |
| `e` | End of word |
| `b` | Previous word |
@@ -50,8 +50,6 @@ For proxies requiring advanced authentication (NTLM, Kerberos, etc.), consider u
By default, Claude Code trusts both its bundled Mozilla CA certificates and your operating system's certificate store. Enterprise TLS-inspection proxies such as CrowdStrike Falcon and Zscaler work without additional configuration when their root certificate is installed in the OS trust store.
System CA store integration requires the native Claude Code binary distribution. When running on the Node.js runtime, the system CA store is not merged automatically. In that case, set `NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem` to trust an enterprise root CA.
`CLAUDE_CODE_CERT_STORE` accepts a comma-separated list of sources. Recognized values are `bundled` for the Mozilla CA set shipped with Claude Code and `system` for the operating system trust store. The default is `bundled,system`.
To trust only the bundled Mozilla CA set:
@@ -103,6 +101,7 @@ Claude Code requires access to the following URLs. Allowlist these in your proxy
| `downloads.claude.ai` | Plugin executable downloads; native installer and native auto-updater |
| `storage.googleapis.com` | Native installer and native auto-updater on versions prior to 2.1.116 |
| `bridge.claudeusercontent.com` | [Claude in Chrome](/en/chrome) extension WebSocket bridge |
| `raw.githubusercontent.com` | Changelog feed for [`/release-notes`](/en/commands) and the release notes shown after updating; plugin marketplace install counts |
If you install Claude Code through npm or manage your own binary distribution, end users may not need access to `downloads.claude.ai` or `storage.googleapis.com`.
@@ -37,7 +37,7 @@ Claude Code supports several permission modes that control how tools are approve
| :- | :- |
| `default` | Standard behavior: prompts for permission on first use of each tool |
| `acceptEdits` | Automatically accepts file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) for paths in the working directory or `additionalDirectories` |
| `plan` | Plan Mode: Claude can analyze but not modify files or execute commands |
| `plan` | Plan Mode: Claude reads files and runs read-only shell commands to explore but does not edit your source files |
| `auto` | Auto-approves tool calls with background safety checks that verify actions align with your request. Currently a research preview |
| `dontAsk` | Auto-denies tools unless pre-approved via `/permissions` or `permissions.allow` rules |
| `bypassPermissions` | Skips all permission prompts. Root and home directory removals such as `rm -rf /` still prompt as a circuit breaker |
@@ -285,7 +285,7 @@ Use both for defense-in-depth:
- Permission deny rules block Claude from even attempting to access restricted resources
- Sandbox restrictions prevent Bash commands from reaching resources outside defined boundaries, even if a prompt injection bypasses Claude's decision-making
- Filesystem restrictions in the sandbox use Read and Edit deny rules, not separate sandbox configuration
- Filesystem restrictions in the sandbox combine the [`sandbox.filesystem`](/en/sandboxing) settings with Read and Edit deny rules; both are merged into the final sandbox boundary
- Network restrictions combine WebFetch permission rules with the sandbox's `allowedDomains` and `deniedDomains` lists
When sandboxing is enabled with `autoAllowBashIfSandboxed: true`, which is the default, sandboxed Bash commands run without prompting even if your permissions include `ask: Bash(*)`. The sandbox boundary substitutes for the per-command prompt. Explicit deny rules still apply, and `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a prompt. See [sandbox modes](/en/sandboxing#sandbox-modes) to change this behavior.
@@ -22,7 +22,7 @@ Choose a platform based on how you like to work and where your project lives.
| [Web](/en/claude-code-on-the-web) | Long-running tasks that don't need much steering, or work that should continue when you're offline | Anthropic-managed cloud, continues after you disconnect |
| Mobile | Starting and monitoring tasks while away from your computer | Cloud sessions from the Claude app for iOS and Android, [Remote Control](/en/remote-control) for local sessions, [Dispatch](/en/desktop#sessions-from-dispatch) to Desktop on Pro and Max |
The CLI is the most complete surface for terminal-native work: scripting, third-party providers, and the Agent SDK are CLI-only. Desktop and the IDE extensions trade some CLI-only features for visual review and tighter editor integration. The web runs in Anthropic's cloud, so tasks keep going after you disconnect. Mobile is a thin client into those same cloud sessions or into a local session via Remote Control, and can send tasks to Desktop with Dispatch.
The CLI is the most complete surface for terminal-native work: scripting and the Agent SDK are CLI-only. Third-party providers also work in [VS Code](/en/vs-code#use-third-party-providers). Enterprise [Desktop](/en/desktop) deployments support Vertex AI and gateway providers; for Bedrock or Foundry, use the CLI or VS Code instead of Desktop. Desktop and the IDE extensions trade some CLI-only features for visual review and tighter editor integration. The web runs in Anthropic's cloud, so tasks keep going after you disconnect. Mobile is a thin client into those same cloud sessions or into a local session via Remote Control, and can send tasks to Desktop with Dispatch.
You can mix surfaces on the same project. Configuration, project memory, and MCP servers are shared across the local surfaces.
@@ -24,7 +24,7 @@ Once your marketplace is live, you can update it by pushing changes to your repo
## Walkthrough: create a local marketplace
This example creates a marketplace with one plugin: a `/quality-review` skill for code reviews. You'll create the directory structure, add a skill, create the plugin manifest and marketplace catalog, then install and test it.
This example creates a marketplace with one plugin: a `quality-review` skill for code reviews. You'll create the directory structure, add a skill, create the plugin manifest and marketplace catalog, then install and test it.
```bash theme={null}
mkdir -p my-marketplace/.claude-plugin
@@ -32,7 +32,7 @@ mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review
```
Create a `SKILL.md` file that defines what the `/quality-review` skill does.
Create a `SKILL.md` file that defines what the `quality-review` skill does.
```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}
---
@@ -54,7 +54,7 @@ Create a `plugin.json` file that describes the plugin. The manifest goes in the
```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}
{
"name": "quality-review-plugin",
"description": "Adds a /quality-review skill for quick code reviews",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0"
}
```
@@ -73,7 +73,7 @@ Create the marketplace catalog that lists your plugin.
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a /quality-review skill for quick code reviews"
"description": "Adds a quality-review skill for quick code reviews"
}
]
}
@@ -86,10 +86,10 @@ Add the marketplace and install the plugin.
/plugin install quality-review-plugin@my-plugins
```
Select some code in your editor and run your new skill.
Select some code in your editor and run your new skill. Plugin skills are namespaced with the plugin name.
```shell theme={null}
/quality-review
/quality-review-plugin:quality-review
```
To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see [Plugins](/en/plugins).
@@ -260,7 +260,7 @@ LSP integration provides:
| :- | :- | :- |
| `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` |
| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
| `rust-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |
| `rust-analyzer-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |
Install the language server first, then install the plugin from the marketplace.
@@ -28,7 +28,7 @@ To mitigate risks in agentic systems:
- **Sandboxed bash tool**: [Sandbox](/en/sandboxing) bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Enable with `/sandbox` to define boundaries where Claude Code can work autonomously
- **Write access restriction**: Claude Code can only write to the folder where it was started and its subfolders—it cannot modify files in parent directories without explicit permission. While Claude Code can read files outside the working directory (useful for accessing system libraries and dependencies), write operations are strictly confined to the project scope, creating a clear security boundary
- **Prompt fatigue mitigation**: Support for allowlisting frequently used safe commands per-user, per-codebase, or per-organization
- **Accept Edits mode**: Batch accept multiple edits while maintaining permission prompts for commands with side effects
- **Accept Edits mode**: Auto-approves file edits and a fixed set of filesystem Bash commands like `mkdir`, `touch`, `rm`, `mv`, `cp`, and `sed` for paths in the working directory. Other Bash commands and out-of-scope paths still prompt
### User responsibility
@@ -546,8 +546,10 @@ Plugin-related settings in `settings.json`:
},
"extraKnownMarketplaces": {
"acme-tools": {
"source": "github",
"repo": "acme-corp/claude-plugins"
"source": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
}
}
}
@@ -659,7 +661,7 @@ Use `source: 'settings'` to declare a small set of plugins inline without settin
- Only available in managed settings (`managed-settings.json`)
- Cannot be overridden by user or project settings (highest precedence)
- Enforced BEFORE network/filesystem operations (blocked sources never execute)
- Uses exact matching for source specifications (including `ref`, `path` for git sources), except `hostPattern`, which uses regex matching
- Uses exact matching for source specifications (including `ref`, `path` for git sources), except `hostPattern` and `pathPattern`, which use regex matching
**Allowlist behavior**:
@@ -669,7 +671,7 @@ Use `source: 'settings'` to declare a small set of plugins inline without settin
**All supported source types**:
The allowlist supports multiple marketplace source types. Most sources use exact matching, while `hostPattern` uses regex matching against the marketplace host.
The allowlist supports multiple marketplace source types. Most sources use exact matching, while `hostPattern` and `pathPattern` use regex matching against the marketplace host and filesystem path respectively.
1. **GitHub repositories**:
@@ -747,6 +749,17 @@ Host extraction by source type:
- `url`: extracts hostname from the URL
- `npm`, `file`, `directory`: not supported for host pattern matching
8. **Path pattern matching**:
```json
{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }
```
Fields: `pathPattern` (required: regex pattern matched against the `path` field of `file` and `directory` sources)
Use path pattern matching to allow filesystem-based marketplaces alongside `hostPattern` restrictions for network sources. Set `".*"` to allow all local paths, or a narrower pattern to restrict to specific directories.
**Configuration examples**:
Example: allow specific marketplaces only:
@@ -169,6 +169,16 @@ The setup script exited with a non-zero status, which blocks the session from st
To debug, add `set -x` at the top of the script to see which command failed. For non-critical commands, append `|| true` so they don't block session start.
### New sessions hang or time out during setup
If new sessions stall on the setup script step or fail with a generic container error before the script finishes, the script is likely exceeding the roughly five-minute time budget for building the [environment cache](/en/claude-code-on-the-web#environment-caching). Heavy steps such as pulling large Docker images, syncing full dependency trees, or downloading model weights often push the total over the limit, especially when they run one after another.
To fix this, trim the script so it reliably finishes in under five minutes:
- Run independent installs in parallel with `&` and a final `wait` instead of running them serially.
- Move the largest downloads out of the setup script and into a [SessionStart hook](/en/claude-code-on-the-web#setup-scripts-vs-sessionstart-hooks) that launches them in the background, so the session becomes usable while they finish.
- Remove long retry sleeps from the setup script, since a stalled retry loop counts against the budget.
### Session keeps running after closing the tab
This is by design. Closing the tab or navigating away doesn't stop the session. It continues running in the background until Claude finishes the current task, then idles. From the sidebar, you can [archive a session](/en/claude-code-on-the-web#archive-sessions) to hide it from your list, or [delete it](/en/claude-code-on-the-web#delete-sessions) to remove it permanently.