From 30d5ad52bc5d0ecac24a5250ca812213566d47a0 Mon Sep 17 00:00:00 2001 From: Luong NGUYEN Date: Tue, 19 May 2026 07:08:33 +0200 Subject: [PATCH] docs: sync to Claude Code v2.1.143 (5 patches since v2.1.138) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps tutorial coverage from v2.1.138 → v2.1.143. Highlights: - /goal and /scroll-speed slash commands (v2.1.139) - claude agents Agent View (Research Preview) with 9 dispatch flags - claude plugin details and marketplace context-cost projection - Hook exec form (args), continueOnBlock on PostToolUse, terminalSequence - Stop hook 8-block safety cap + override env var - Fast Mode default flipped to Opus 4.7 (v2.1.142) - PowerShell tool default-on for Bedrock/Vertex/Foundry on Windows - API-key auth disables Remote Control, /schedule, claude.ai MCP, notifications - worktree.bgIsolation setting - CLAUDE_PROJECT_DIR for MCP stdio servers - Subagent OTEL headers + case-insensitive subagent_type matching - Root-level SKILL.md plugin pattern; Routines marketing name note Also bumps stale "28 hook events" counts in CATALOG/README to 29 and refreshes the metadata footer (Last Updated, Claude Code Version, Sources) on every modified file. --- 01-slash-commands/README.md | 27 ++++++++- 04-subagents/README.md | 27 ++++++++- 05-mcp/README.md | 26 +++++++- 06-hooks/README.md | 69 ++++++++++++++++++++- 07-plugins/README.md | 60 +++++++++++++++++- 09-advanced-features/README.md | 46 +++++++++++++- 10-cli/README.md | 40 +++++++++++- CATALOG.md | 7 ++- CHANGELOG.md | 108 +++++++++++++++++++++++++++++++++ README.md | 7 ++- 10 files changed, 395 insertions(+), 22 deletions(-) diff --git a/01-slash-commands/README.md b/01-slash-commands/README.md index ce1c790..9403560 100644 --- a/01-slash-commands/README.md +++ b/01-slash-commands/README.md @@ -42,8 +42,9 @@ Built-in commands are shortcuts for common actions. There are **60+ built-in com | `/export [filename]` | Export the current conversation to a file or clipboard | | `/extra-usage` | Configure extra usage for rate limits | | `/fast [on\|off]` | Toggle fast mode | -| `/feedback` | Submit feedback (alias: `/bug`) | +| `/feedback` | Submit feedback (alias: `/bug`). Since v2.1.141, can attach recent sessions (last 24h or 7d) so reports spanning more than one session include context. | | `/focus` | Toggle focus view (added v2.1.110; replaces `Ctrl+O` for focus toggle) | +| `/goal ` | Register a session-level completion condition; Claude keeps working until the goal is met. `/goal clear` removes it. Active goal appears in the status line, with a live overlay panel showing elapsed time, turn count, and token usage (added v2.1.139). | | `/help` | Show help | | `/hooks` | View hook configurations | | `/ide` | Manage IDE integrations | @@ -77,6 +78,7 @@ Built-in commands are shortcuts for common actions. There are **60+ built-in com | `/rewind` | Rewind conversation and/or code (alias: `/checkpoint`) | | `/sandbox` | Toggle sandbox mode | | `/schedule [description]` | Create/manage Cloud scheduled tasks | +| `/scroll-speed <+N\|-N>` | Tune mouse-wheel scroll speed of the TUI live-preview pane with a live preview. Persists per-machine to `~/.claude/preferences.json` (added v2.1.139). | | `/security-review` | Analyze branch for security vulnerabilities | | `/skills` | List available skills | | `/stats` | Typing-shortcut alias for `/usage` — opens the stats tab (daily usage, sessions, streaks) (v2.1.118+) | @@ -144,6 +146,23 @@ These skills ship with Claude Code and are invoked like slash commands: - `/ultrareview` added for comprehensive cloud-based multi-agent code review (v2.1.111) - `/less-permission-prompts` added to analyze Bash/MCP tool calls and reduce permission prompts via an allowlist in `.claude/settings.json` (v2.1.111) - Auto mode no longer requires the `--enable-auto-mode` flag for Max subscribers on Opus 4.7 (v2.1.112) +- `/goal` added — session-level completion condition that Claude works toward across turns; live overlay shows elapsed time, turn count, and token usage (v2.1.139) +- `/scroll-speed` added — tune mouse-wheel scroll speed of the TUI live-preview pane; persists per-machine (v2.1.139) + +### `/goal` — Session-Level Completion Condition + +> **New in v2.1.139** + +Use `/goal` to register a completion condition for the current session. Claude works toward it across turns, and an overlay panel shows elapsed time, turn count, and tokens used. Clear it with `/goal clear`. Works in interactive mode, `claude -p`, and Remote Control. + +``` +User: /goal Migrate the payments service from REST to gRPC and get the integration tests passing. +Claude: Goal registered. I'll work toward this until you clear it. +[Goal panel: ⏱ 0s · turns 0 · tokens 0] + +User: start by listing the REST endpoints +Claude: [does the work, panel updates] +``` ### `/team-onboarding` — Teammate Ramp-Up Guide @@ -601,14 +620,16 @@ If both exist with the same name, the **skill takes precedence**. Remove one or --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/slash-commands - https://code.claude.com/docs/en/interactive-mode - https://code.claude.com/docs/en/changelog - https://github.com/anthropics/claude-code/releases/tag/v2.1.118 - https://github.com/anthropics/claude-code/releases/tag/v2.1.116 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.141 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 *Part of the [Claude How To](../) guide series* diff --git a/04-subagents/README.md b/04-subagents/README.md index b3e623c..b368475 100644 --- a/04-subagents/README.md +++ b/04-subagents/README.md @@ -387,6 +387,8 @@ You can explicitly request a specific subagent: > Ask the debugger subagent to investigate this error ``` +> **Case- and separator-insensitive `subagent_type` matching (v2.1.140)**: `subagent_type` (in `Agent` tool calls or `--agent` flags) is matched case-insensitively and ignores separator style — `code-reviewer`, `Code Reviewer`, and `code_reviewer` all resolve to the same agent. This removes a long-standing footgun where minor capitalization differences silently fell back to the default agent. + ### @-Mention Invocation Use the `@` prefix to guarantee a specific subagent is invoked (bypasses automatic delegation heuristics): @@ -1206,6 +1208,25 @@ graph TD --- +## Observability + +> **Added in v2.1.139.** + +API requests originating from a subagent carry two extra HTTP headers so traces and logs can be correlated back to the dispatching session: + +| Header | Description | +|--------|-------------| +| `x-claude-code-agent-id` | UUID of the subagent making the request. | +| `x-claude-code-parent-agent-id` | UUID of the agent that dispatched this subagent (the main agent, or a higher-level subagent in a chain). | + +The same identifiers are exposed on `claude_code.llm_request` OpenTelemetry spans as the attributes `claude.code.agent.id` and `claude.code.agent.parent_id`. Use them to: + +- Attribute API spend to a specific subagent type rather than the parent session +- Reconstruct a chain of agent invocations after the fact (parent_id forms a tree) +- Alert on runaway subagents (e.g., one `agent.id` accounting for >50% of session spend) + +See the OpenTelemetry section in [Advanced Features → Telemetry](../09-advanced-features/README.md) for end-to-end exporter setup. + ## Additional Resources - [Official Subagents Documentation](https://code.claude.com/docs/en/sub-agents) @@ -1217,12 +1238,14 @@ graph TD --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/sub-agents - https://code.claude.com/docs/en/agent-teams - https://github.com/anthropics/claude-code/releases/tag/v2.1.117 - https://github.com/anthropics/claude-code/releases/tag/v2.1.131 - https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.140 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/05-mcp/README.md b/05-mcp/README.md index 0bbcb20..8e16937 100644 --- a/05-mcp/README.md +++ b/05-mcp/README.md @@ -97,6 +97,27 @@ claude mcp add --transport stdio myserver -- npx @myorg/mcp-server claude mcp add --transport stdio myserver --env KEY=value -- npx server ``` +#### `CLAUDE_PROJECT_DIR` for stdio servers (v2.1.139+) + +Every MCP stdio server is spawned with `CLAUDE_PROJECT_DIR=` already set in its environment — the same convention used for hooks. Plugin and project `.mcp.json` files can reference `${CLAUDE_PROJECT_DIR}` in the `command`, `args`, and `env` values, and the substitution happens before `execve()`: + +```json +{ + "mcpServers": { + "repo-tools": { + "type": "stdio", + "command": "node", + "args": ["${CLAUDE_PROJECT_DIR}/.claude/mcp/repo-tools.js"], + "env": { + "REPO_ROOT": "${CLAUDE_PROJECT_DIR}" + } + } + } +} +``` + +Use this when your stdio server needs to read files relative to the project root regardless of where Claude Code was launched. + ### SSE Transport (Deprecated) Server-Sent Events transport is deprecated in favor of `http` but still supported: @@ -1146,10 +1167,11 @@ export GITHUB_TOKEN="your_token" --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/mcp - https://code.claude.com/docs/en/changelog - https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/06-hooks/README.md b/06-hooks/README.md index 6e045cc..947e2cd 100644 --- a/06-hooks/README.md +++ b/06-hooks/README.md @@ -93,6 +93,22 @@ The default hook type. Executes a shell command and communicates via JSON stdin/ } ``` +#### Exec form (`args`) + +> Added in v2.1.139. + +Instead of the shell-form `"command": "..."`, a command hook can spawn a binary directly via `execve()` with an `args` array. There is no shell parsing, so path placeholders never need quoting and the configuration is immune to shell-injection bugs. + +```json +{ + "type": "command", + "args": ["python3", "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py", "--strict"], + "timeout": 60 +} +``` + +The two forms are **mutually exclusive** — a hook with both `command` and `args` set is rejected at config load. Use `command` when you need pipes, redirection, `&&` chaining, or shell expansions; use `args` when you are calling one binary with arguments. + ### HTTP Hooks > Added in v2.1.63. @@ -274,6 +290,31 @@ Runs immediately after tool completion. Use for verification, logging, or provid |-------|------|-------------| | `duration_ms` | number | Tool execution time in milliseconds. Excludes time spent in permission prompts and PreToolUse hook execution. Available on both `PostToolUse` and `PostToolUseFailure` hooks. | +#### Recoverable blocks (`continueOnBlock`, v2.1.139) + +By default, a `PostToolUse` hook that returns `"decision": "block"` aborts the current turn. Set `"continueOnBlock": true` on the hook to instead surface the rejection back to Claude as a `tool_result`, so the model can read the feedback and retry or adjust. + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/policy-check.py", + "continueOnBlock": true + } + ] + } + ] + } +} +``` + +Use this when the hook's `reason` is something Claude can act on (e.g., "this file is read-only; write somewhere else"); leave it off when a block must halt the turn entirely. + ### UserPromptSubmit Runs when user submits a prompt, before Claude processes it. @@ -326,6 +367,8 @@ Run when Claude finishes responding (Stop) or a subagent completes (SubagentStop } ``` +> **Safety cap on consecutive blocks (v2.1.143)**: If a `Stop` hook returns `"decision": "block"` (or sets `continue: false`) **8 times in a row** for the same turn, Claude Code short-circuits the loop and ends the session with a warning. Override the threshold with the env var `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=` (set to `0` to disable the cap entirely). This prevents a buggy Stop hook from looping the session forever. + ### SubagentStart Runs when a subagent begins execution. The matcher input is the agent type name, allowing hooks to target specific subagent types. @@ -537,6 +580,24 @@ All hooks receive JSON input via stdin: > } > ``` +#### `terminalSequence` (v2.1.141) + +Hooks can emit raw OSC (operating system command) escape sequences by setting `terminalSequence` in the JSON output. The host writes the sequence to its controlling terminal when the hook returns — useful for desktop notifications, window-title updates, and terminal bells without requiring a TTY of your own. + +| Field | Type | Description | +|-------|------|-------------| +| `terminalSequence` | string | Raw escape sequence (typically OSC 9 / OSC 0 / OSC 777). Written to the host terminal verbatim. | + +Example — fire an OSC 9 desktop notification when a long task completes: + +```json +{ + "terminalSequence": "]9;Task complete" +} +``` + +Configure it on a `Stop` hook so the notification fires when Claude finishes a turn. Sequence support is terminal-dependent; Kitty/iTerm2/Windows Terminal honor OSC 9. + ## Environment Variables | Variable | Availability | Description | @@ -549,6 +610,7 @@ All hooks receive JSON input via stdin: | `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | SessionEnd hooks | Configurable timeout in milliseconds for SessionEnd hooks (overrides default) | | `CLAUDE_CODE_SESSION_ID` | Bash tool subprocesses (v2.1.132+) | Session UUID; matches the `session_id` field in hook input JSON. Use to correlate bash logs with hook telemetry. | | `CLAUDE_EFFORT` | Bash tool subprocesses (v2.1.133+) | Active effort level (`low`/`medium`/`high`/`xhigh`/`max`); matches `effort.level` in hook input JSON. | +| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Process-wide (v2.1.143+) | Max consecutive Stop-hook blocks before the session ends with a warning (default `8`). Set to `0` to disable the cap. | ## Prompt-Based Hooks @@ -1371,12 +1433,15 @@ Edit `~/.claude/settings.json` or `.claude/settings.json` with the hook configur --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/hooks - https://code.claude.com/docs/en/changelog - https://github.com/anthropics/claude-code/releases/tag/v2.1.118 - https://github.com/anthropics/claude-code/releases/tag/v2.1.131 - https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.141 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.143 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/07-plugins/README.md b/07-plugins/README.md index 751df64..c566980 100644 --- a/07-plugins/README.md +++ b/07-plugins/README.md @@ -213,6 +213,23 @@ Once configured, LSP servers provide: - **Hover information** — type signatures and documentation on hover - **Symbol listing** — browse symbols in the current file or workspace +### `bin/` directory on `PATH` + +When a plugin is enabled, its `bin/` directory is prepended to the session's `PATH`. Any executable shipped there can be invoked directly from the Bash tool by name — no qualified path required. + +```bash +# In a plugin layout: +my-plugin/ +├── plugin.json +└── bin/ + └── my-tool # executable file (chmod +x) + +# Inside a Claude Code session with the plugin enabled: +$ my-tool --help +``` + +Use this for CLI helpers that hooks, skills, or commands inside the same plugin will shell out to. Mark the files executable in the plugin repo (`chmod +x`) — git preserves the bit. + ## Plugin Options (v2.1.83+) Plugins can declare user-configurable options in the manifest via `userConfig`. Values marked `sensitive: true` are stored in the system keychain rather than plain-text settings files: @@ -321,6 +338,8 @@ Use **standalone slash commands** for quick personal workflows. Use **plugins** > **`skills/` discovery (v2.1.136+)**: A `skills` entry in `plugin.json` no longer hides the plugin's default `skills/` directory. Skills declared in both places are merged, so you can list a few highlights in `plugin.json` without losing the rest. +> **Root-level `SKILL.md` plugins (v2.1.142+)**: A plugin with a top-level `SKILL.md` and **no `skills/` subdirectory** is itself surfaced as a single skill — the plugin *is* the skill. This is an additional pattern, not a replacement for the `skills/` directory or the `plugin.json` `skills` entry; use it for small single-skill plugins where the directory layout adds no value. + ## Practical Examples ### Example 1: PR Review Plugin @@ -507,6 +526,16 @@ Example `blockedMarketplaces` with host/path regex (v2.1.119): - **Default git timeout**: Increased from 30s to 120s for large plugin repositories - **Custom npm registries**: Plugins can specify custom npm registry URLs for dependency resolution - **Version pinning**: Lock plugins to specific versions for reproducible environments +- **Projected context cost in the browse pane (v2.1.143)**: The `/plugin` marketplace browser shows each plugin's projected per-turn context-token cost — the sum of always-loaded skills, hooks, and MCP server descriptors. Use it to size plugin adoption before installing. The same projection is available post-install via [`claude plugin details `](#claude-plugin-details-name-v21139). + +Example browse row with the cost column: + +```text +NAME VERSION AUTHOR CTX/TURN DESCRIPTION +code-reviewer 1.2.0 anthropic +1,420 Multi-agent PR review +devops-toolkit 0.4.1 acme +3,180 SRE playbooks, on-call helpers +docs-helper 0.9.0 community +610 Doc-style guide enforcement +``` ### Marketplace definition schema @@ -666,12 +695,30 @@ claude plugin validate # Validate plugin structure claude plugin tag # Create a release git tag with version validation (v2.1.118+) claude plugin prune # Remove orphaned auto-installed plugin dependencies (v2.1.121+) claude plugin uninstall --prune # Uninstall and cascade-clean orphaned dependencies (v2.1.121+) +claude plugin details # Show inventory + projected per-turn token cost (v2.1.139+) ``` Example: `claude plugin tag v0.3.0` validates the version format, creates the matching git tag, and is the recommended way to cut plugin releases for distribution. `claude plugin prune` is useful after installing or uninstalling marketplace plugins that pulled in their own dependencies — it removes any auto-installed plugins whose parent plugin has since been removed. `plugin uninstall --prune` does the same cascade in a single step. +> **Dependency enforcement (v2.1.143)**: `claude plugin disable ` **refuses** if another enabled plugin still depends on the target (the dependency graph would break). `claude plugin enable ` **force-enables transitive dependencies** after a single confirmation prompt rather than requiring a separate enable for each. Use `claude plugin prune` to clean up dependencies whose dependents were later removed. + +### `claude plugin details ` (v2.1.139+) + +`claude plugin details ` prints the plugin's full component inventory — skills, hooks, MCP servers, LSP servers, background monitors, slash commands — plus a **projected per-turn (and per-invocation) token cost**. Use it to size a plugin before adopting it, especially on context-constrained models. + +Example output (abbreviated): + +```text +plugin: code-reviewer (1.2.0) +skills: 3 hooks: 2 mcp: 1 lsp: 0 monitors: 0 +commands: /review, /security-review +projected ctx: +1,420 tokens per turn · +9,800 tokens per /review invocation +``` + +LSP servers were added to the details pane in v2.1.142. See also the marketplace browse pane's projected context cost (v2.1.143) covered in [Plugin Marketplace](#plugin-marketplace). + ## Installation Methods ### From Marketplace @@ -725,6 +772,7 @@ When auto-update runs, Claude Code: |----------|--------| | `DISABLE_AUTOUPDATER=1` | Disable all auto-updates (Claude Code + plugins) | | `DISABLE_AUTOUPDATER=1` + `FORCE_AUTOUPDATE_PLUGINS=1` | Keep plugin updates, disable Claude Code updates | +| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` | (v2.1.141+) Force `claude plugin install` to clone GitHub plugin sources over HTTPS instead of SSH, even when an SSH remote is available. Use in CI runners or containers without SSH keys. | ```bash # Disable all auto-updates @@ -733,6 +781,10 @@ export DISABLE_AUTOUPDATER=1 # Keep plugin auto-updates only export DISABLE_AUTOUPDATER=1 export FORCE_AUTOUPDATE_PLUGINS=1 + +# CI runner without SSH keys — force HTTPS for plugin installs +export CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 +claude plugin install code-reviewer@anthropic ``` ## When to Create a Plugin @@ -1053,8 +1105,8 @@ The following Claude Code features work together with plugins: --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/plugins - https://code.claude.com/docs/en/plugin-marketplaces @@ -1062,4 +1114,8 @@ The following Claude Code features work together with plugins: - https://github.com/anthropics/claude-code/releases/tag/v2.1.118 - https://github.com/anthropics/claude-code/releases/tag/v2.1.131 - https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.141 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.142 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.143 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/09-advanced-features/README.md b/09-advanced-features/README.md index 9b5e707..b53cf8a 100644 --- a/09-advanced-features/README.md +++ b/09-advanced-features/README.md @@ -732,6 +732,8 @@ done Scheduled Tasks let you run prompts automatically on a recurring schedule or as one-time reminders. Tasks are session-scoped — they run while Claude Code is active and are cleared when the session ends. Available since v2.1.72+. +> **Marketed as "Routines" on claude.com (2026-05-14)**: Anthropic's product blog introduces this surface as **Routines**. The CLI command stays `/schedule`; this guide uses the original "Scheduled Tasks" naming for continuity. If you see "Routines" in claude.com docs or the desktop app, it refers to the same feature. + ### The `/loop` command ```bash @@ -792,6 +794,8 @@ Cloud scheduled tasks persist across restarts and do not require Claude Code to export CLAUDE_CODE_DISABLE_CRON=1 ``` +> **`/schedule` auto-disabled by API-key tiers (v2.1.139)**: Cloud `/schedule` is silently unavailable when any of `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` is set — even if you are also logged in with claude.ai. The same condition disables [Remote Control](#disabling-remote-control-disableremotecontrol-v21128), claude.ai MCP connectors, and notification preferences. Unset the API key (or run on a Pro/Max OAuth tier) to use `/schedule`. Local `CronCreate` is unaffected. + ### Example: monitoring a deployment ``` @@ -825,6 +829,8 @@ Cycle through modes with `Shift+Tab` in the CLI. Set a default with the `--permi > **Windows shell detection (v2.1.120, v2.1.126)**: Git for Windows / Git Bash is no longer required. When Git Bash is absent, Claude Code uses PowerShell as the shell tool. From v2.1.126 PowerShell is the *primary* shell when the PowerShell tool is enabled, and detection covers PowerShell 7 installed via the Microsoft Store, MSI without PATH, or as a `.NET global tool`. +> **PowerShell tool enabled by default on Windows for Bedrock/Vertex/Foundry (v2.1.143)**: As of v2.1.143, the PowerShell tool is **enabled by default on Windows** for Bedrock, Vertex, and Foundry users. Claude Code invokes PowerShell with `-ExecutionPolicy Bypass` so scripts run even if the system policy is `Restricted`. To make Claude Code honor the system execution policy, set `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`. To disable the PowerShell tool entirely, set `CLAUDE_CODE_USE_POWERSHELL_TOOL=0`. + ### Activation Methods **Keyboard shortcut**: @@ -1569,6 +1575,14 @@ Admins on Team or Enterprise plans can block Remote Control entirely with the `d The setting is honored at the **managed/policy** scope (e.g., `/Library/Application Support/ClaudeCode/managed-settings.json` on macOS) so it cannot be overridden by individual users. Useful when local-only execution must be enforced organization-wide. +> **When Remote Control is auto-disabled by API-key tiers (v2.1.139)**: Remote Control is **silently disabled** whenever any of these are set, even if you are simultaneously logged in with claude.ai: +> +> - `ANTHROPIC_API_KEY` +> - `ANTHROPIC_AUTH_TOKEN` +> - `apiKeyHelper` (settings.json) +> +> The same condition disables [`/schedule`](#scheduled-tasks), claude.ai MCP connectors, and notification preferences — all four claude.ai-bridged surfaces are gated on the OAuth login being the active credential. Unset the API key (or run on a Pro/Max OAuth tier) to use these features. + --- ## Web Sessions @@ -1778,6 +1792,19 @@ Set in `~/.claude/settings.json`: { "worktree": { "baseRef": "head" } } ``` +### Background-Session Isolation (`worktree.bgIsolation`) + +**`worktree.bgIsolation`** (added v2.1.143) — controls whether background sessions (e.g., from `/bg`, `claude --bg`, or the Agent View) get their own worktree or edit the foreground working copy directly. + +- *(default)* — background sessions create an isolated worktree under `/.claude/worktrees/`, the same way `--worktree` does. +- `"none"` — background sessions edit the current working copy directly. Use this when worktrees are impractical (e.g., heavy native-build artifacts) or when a background agent must coordinate edits with the foreground session. + +```json +{ "worktree": { "bgIsolation": "none" } } +``` + +Trade-off: `"none"` removes the safety net of worktree isolation — concurrent edits from background and foreground sessions can produce merge conflicts in the live working copy. + ### Worktree Tools and Hooks | Item | Description | @@ -2069,6 +2096,16 @@ export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000 export CLAUDE_CODE_FORCE_SYNC_OUTPUT=1 # Force synchronous output for terminals where auto-detect misses (Emacs eat, etc.) export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 # Enable background upgrades for Homebrew/WinGet installs export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 # Opt in to /v1/models gateway discovery when ANTHROPIC_BASE_URL is set + +# Windows PowerShell tool (v2.1.143+) — default-on for Bedrock/Vertex/Foundry on Windows +export CLAUDE_CODE_USE_POWERSHELL_TOOL=0 # Disable the PowerShell tool entirely +export CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1 # Honor system ExecutionPolicy instead of `-ExecutionPolicy Bypass` + +# Workload identity federation (v2.1.141+) +export ANTHROPIC_WORKSPACE_ID=ws_abc123 # Scope the federated token to a specific workspace when the rule covers multiple + +# Stop hook safety cap (v2.1.143+) +export CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=8 # Max consecutive Stop-hook blocks before the session ends with a warning. Set 0 to disable the cap. ``` > **v2.1.108**: `ENABLE_PROMPT_CACHING_1H=1` — use a 1-hour prompt cache TTL instead of the default 5-minute TTL. Reduces cache misses in long, stable sessions. (v2.1.129 fixes a regression where the 1-hour TTL was silently downgraded to 5 minutes.) @@ -2230,13 +2267,18 @@ For more information about Claude Code and related features: --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/permission-modes - https://code.claude.com/docs/en/interactive-mode - https://code.claude.com/docs/en/settings +- https://code.claude.com/docs/en/cli-reference - https://www.anthropic.com/news/claude-opus-4-7 +- https://claude.com/blog/introducing-routines-in-claude-code - https://github.com/anthropics/claude-code/releases/tag/v2.1.117 - https://github.com/anthropics/claude-code/releases/tag/v2.1.118 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.141 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.143 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/10-cli/README.md b/10-cli/README.md index 6537f78..c334b1d 100644 --- a/10-cli/README.md +++ b/10-cli/README.md @@ -51,7 +51,7 @@ The older JavaScript bundle is still produced for Windows and for environments t | `/doctor` (slash command) | Diagnose installation, config, and plugin health. Since v2.1.116 it can be opened **while Claude is responding**, shows status icons inline, and accepts the `f` keypress to auto-fix detected issues | run `/doctor` inside the REPL | | `claude mcp` | Configure MCP servers | See [MCP documentation](../05-mcp/) | | `claude mcp serve` | Run Claude Code as an MCP server | `claude mcp serve` | -| `claude agents` | List all configured subagents | `claude agents` | +| `claude agents` | Open the **Agent View** (Research Preview, v2.1.139+) — multi-session manager listing every Claude Code session with its status. See [Agent View](#agent-view-claude-agents-v21139) below. | `claude agents` | | `claude auto-mode defaults` | Print auto mode default rules as JSON | `claude auto-mode defaults` | | `claude remote-control` | Start Remote Control server | `claude remote-control` | | `claude plugin` | Manage plugins (install, enable, disable) | `claude plugin install my-plugin` | @@ -462,6 +462,33 @@ When multiple agent definitions exist, they are loaded in this priority order: CLI-defined agents override both project and user agents for the session. Project-level agents override user-level agents when their names collide. See [Lesson 04 — Subagents](../04-subagents/README.md#file-locations) for the full priority table including plugin-level agents. +### Agent View (`claude agents`, v2.1.139+) + +> **Research Preview** — feature is stable enough for daily use but may change. + +`claude agents` opens the **Agent View** — a single list of every Claude Code session on the machine with its current status (`running`, `blocked on you`, `done`). It is the replacement for juggling multiple terminal tabs when you run background agents, scheduled tasks, or `--bg`-launched sessions. + +```bash +# Open the Agent View +claude agents +``` + +When you dispatch a session from the view (or via `claude --bg `), you can pass the same configuration flags you would pass to `claude` itself. Flags introduced for the Agent View dispatch path: + +| Flag | Since | Description | +|------|-------|-------------| +| `--cwd ` | v2.1.141 | Scope the session list (or new session) to a specific working directory | +| `--add-dir ` | v2.1.142 | Add directories to the dispatched session's workspace | +| `--settings ` | v2.1.142 | Use a specific `settings.json` for the dispatched session | +| `--mcp-config ` | v2.1.142 | Use a specific MCP config for the dispatched session | +| `--plugin-dir ` | v2.1.142 | Use a specific plugin directory for the dispatched session | +| `--permission-mode ` | v2.1.142 | Set permission mode (`plan`, `acceptEdits`, `auto`, etc.) for the dispatched session | +| `--model ` | v2.1.142 | Pin a model for the dispatched session | +| `--effort ` | v2.1.142 | Pin an effort level (`low`/`medium`/`high`/`xhigh`/`max`) | +| `--dangerously-skip-permissions` | v2.1.142 | Run the dispatched session without permission prompts (use only in sandboxes) | + +Sessions that finish their work but leave a background shell open move from "Working" to "Completed" (v2.1.141 fix). Within an attached agent session, `Shift+Tab` cycles through permission modes including auto mode (v2.1.143). + --- ## High-Value Use Cases @@ -736,6 +763,8 @@ claude --model opusplan "design and implement the API" /fast ``` +> **Fast Mode default flipped to Opus 4.7 (v2.1.142)**: As of v2.1.142, `/fast` runs Opus 4.7 by default (was Opus 4.6 before). To opt back into Opus 4.6 for Fast Mode, export `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`. + ### Effort Levels (Opus 4.7) Opus 4.7 supports adaptive reasoning with effort levels, ordered from lightest to heaviest: `low` (○), `medium` (◐), `high` (●), `xhigh` (default on Claude Code since Opus 4.7 launch, 2026-04-16), and `max` (Opus 4.7 only). On Opus 4.6 / Sonnet 4.6, the default effort for Pro/Max subscribers was raised from `medium` to `high` in v2.1.117. @@ -801,6 +830,7 @@ The "ultrathink" keyword in prompts activates deep reasoning. The `max` effort l | `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Set to `1` to force synchronous output for terminals where auto-detection misses (e.g., Emacs `eat`) (v2.1.129+) | | `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | Set to `1` to enable background upgrades for Homebrew/WinGet installs (which normally do not auto-update) (v2.1.129+) | | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Set to `1` to opt in to gateway `/v1/models` discovery when `ANTHROPIC_BASE_URL` is set. Without it, `/model` shows the built-in static list (v2.1.129+) | +| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | Set to `1` to pin Fast Mode (`/fast`) back to Opus 4.6. The default flipped to Opus 4.7 in v2.1.142. | > **`ENABLE_TOOL_SEARCH` on Vertex AI (v2.1.119+)**: Tool search is **disabled by default on Google Cloud Vertex AI** deployments. Users who want the tool-search capability on Vertex must explicitly opt in with `export ENABLE_TOOL_SEARCH=true`. On direct Anthropic API it remains enabled by default. @@ -908,8 +938,8 @@ claude -p --output-format json "query" --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/cli-reference - https://code.claude.com/docs/en/settings @@ -921,4 +951,8 @@ claude -p --output-format json "query" - https://github.com/anthropics/claude-code/releases/tag/v2.1.118 - https://github.com/anthropics/claude-code/releases/tag/v2.1.131 - https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.141 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.142 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.143 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/CATALOG.md b/CATALOG.md index 7079b62..d12b454 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -20,7 +20,7 @@ | **Skills** | 5 bundled | 6 | 11 | [03-skills/](03-skills/) | | **Plugins** | - | 3 | 3 | [07-plugins/](07-plugins/) | | **MCP Servers** | 1 | 8 | 9 | [05-mcp/](05-mcp/) | -| **Hooks** | 28 events | 8 | 8 | [06-hooks/](06-hooks/) | +| **Hooks** | 29 events | 8 | 8 | [06-hooks/](06-hooks/) | | **Memory** | 7 types | 3 | 3 | [02-memory/](02-memory/) | | **Total** | **99** | **47** | **121** | | @@ -530,11 +530,12 @@ chmod +x ~/.claude/hooks/*.sh --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/overview - https://code.claude.com/docs/en/commands - https://code.claude.com/docs/en/hooks - https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.143 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5 diff --git a/CHANGELOG.md b/CHANGELOG.md index f926f50..76ef4c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,113 @@ # Changelog +## [v2.1.143] — 2026-05-19 + +### Synced to Claude Code v2.1.143 + +Bumps tutorial coverage from Claude Code v2.1.138 → v2.1.143 (May 15, 2026 +release). Anthropic shipped five patches (v2.1.139–v2.1.143) since the last +sync. Highlights: `/goal` and `/scroll-speed` slash commands, the `claude +agents` Agent View (Research Preview) with a full dispatch flag set, a Stop +hook safety cap, hook exec form (`args`), `continueOnBlock` for PostToolUse, +hook `terminalSequence` output, Fast Mode defaulting to Opus 4.7, +PowerShell-by-default on Windows for Bedrock/Vertex/Foundry, and the +`worktree.bgIsolation` setting. + +### Added + +- `/goal ` slash command (v2.1.139) — registers a session-level + completion condition with a live overlay panel showing elapsed time, turn + count, and token usage. Documented in `01-slash-commands/README.md` and + cross-linked from `10-cli/README.md`. +- `/scroll-speed <±N>` slash command (v2.1.139) — tunes TUI live-preview + scroll speed; persists per-machine. Documented in + `01-slash-commands/README.md`. +- `claude agents` Agent View (Research Preview, v2.1.139) with dispatch flags + `--cwd` (v2.1.141), `--add-dir`, `--settings`, `--mcp-config`, + `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, + `--dangerously-skip-permissions` (v2.1.142). Documented in + `10-cli/README.md`. +- `claude plugin details ` (v2.1.139) — full plugin inventory plus + projected per-turn/per-invocation token-cost estimate. LSP servers added + to the details pane in v2.1.142. Documented in `07-plugins/README.md`. +- Marketplace context-cost projection in the `/plugin` browse pane (v2.1.143). + Documented in `07-plugins/README.md`. +- Hook **exec form** (`args: string[]`, v2.1.139) — direct `execve()` spawn + with no shell parsing; mutually exclusive with the shell-form `command` + field. Documented in `06-hooks/README.md`. +- Hook `continueOnBlock: true` field on PostToolUse (v2.1.139) — surfaces a + blocked tool result back to Claude as a `tool_result` instead of aborting + the turn. Documented in `06-hooks/README.md`. +- Hook `terminalSequence` JSON output field (v2.1.141) — emits raw OSC escape + sequences for desktop notifications, window titles, and bells. Documented + in `06-hooks/README.md`. +- `worktree.bgIsolation: "none"` setting (v2.1.143) — background sessions + edit the current working copy directly instead of an isolated worktree. + Documented in `09-advanced-features/README.md`. +- `CLAUDE_PROJECT_DIR` is now passed to every MCP stdio server's environment + (v2.1.139), and `${CLAUDE_PROJECT_DIR}` substitution is supported in plugin + and project `.mcp.json` `command`/`args`/`env` fields. Documented in + `05-mcp/README.md`. +- Subagent OTEL headers `x-claude-code-agent-id` and + `x-claude-code-parent-agent-id` (v2.1.139), exposed as + `agent_id` / `parent_agent_id` attributes on `claude_code.llm_request` + OTEL spans. Documented in `04-subagents/README.md`. +- `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1` (v2.1.142) — pin Fast Mode back + to Opus 4.6 after the v2.1.142 default flipped to Opus 4.7. Documented in + `10-cli/README.md`. +- `CLAUDE_CODE_USE_POWERSHELL_TOOL=0` and + `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1` (v2.1.143) — opt out of + the default-on PowerShell tool, or make it honor the system execution + policy instead of `-ExecutionPolicy Bypass`. Documented in + `09-advanced-features/README.md`. +- `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` (v2.1.143) — override the 8-consecutive- + blocks safety cap for Stop hooks (set `0` to disable). Documented in + `06-hooks/README.md` and `09-advanced-features/README.md`. +- `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` (v2.1.141) — force plugin installs to + clone GitHub plugin sources over HTTPS for CI runners without SSH keys. + Documented in `07-plugins/README.md`. +- `ANTHROPIC_WORKSPACE_ID` (v2.1.141) — scopes a federated workload-identity + token to a specific workspace. Documented in `09-advanced-features/README.md`. +- Root-level `SKILL.md` plugin pattern (v2.1.142) — a plugin with only a + top-level `SKILL.md` (no `skills/` subdirectory) is surfaced as a single + skill. Documented in `07-plugins/README.md`. +- Plugins marketing name **Routines** for `/schedule` (Anthropic blog, + 2026-05-14) — surfaced as a one-line note in + `09-advanced-features/README.md`; the CLI surface remains `/schedule`. + +### Behavior changes + +- **Fast Mode default flipped to Opus 4.7 (v2.1.142)**: `/fast` now runs Opus + 4.7 by default (was Opus 4.6). Set `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1` + to opt back in. +- **PowerShell tool enabled by default on Windows for Bedrock/Vertex/Foundry + (v2.1.143)**: Claude Code invokes PowerShell with `-ExecutionPolicy Bypass`. + Opt out with `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1` (honor + system policy) or `CLAUDE_CODE_USE_POWERSHELL_TOOL=0` (disable the tool). +- **Remote Control, `/schedule`, claude.ai MCP connectors, and notification + preferences auto-disabled when API-key auth is set (v2.1.139)**: setting + `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` disables all + four claude.ai-bridged surfaces, even if a claude.ai login is also active. +- **Stop hook block loops capped at 8 consecutive blocks (v2.1.143)**: the + session ends with a warning after 8 in a row, preventing buggy Stop hooks + from looping the session forever. Override with + `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`. +- **`subagent_type` matching is now case- and separator-insensitive (v2.1.140)**: + `code-reviewer`, `Code Reviewer`, and `code_reviewer` all resolve to the + same agent. Documented in `04-subagents/README.md`. + +### Changed + +- Root reference docs (`README.md`, `CATALOG.md`) updated from `28 hook + events` to `29 hook events` — matches `06-hooks/README.md` and + `LEARNING-ROADMAP.md` after the `Setup` hook landed in v2.1.138. + +### Notes for translators + +- Tutorial translations (`vi/`, `ja/`, `uk/`, `zh/`) follow English; sync + this round's deltas in module READMEs and the CHANGELOG above. Footers + must reflect `Last Updated: May 19, 2026` and `Claude Code Version: 2.1.143`. + ## [v2.1.138] — 2026-05-09 ### Synced to Claude Code v2.1.138 diff --git a/README.md b/README.md index 5b778dd..24a3c4c 100644 --- a/README.md +++ b/README.md @@ -482,7 +482,7 @@ Configure hooks in `~/.claude/settings.json`: **Usage**: Hooks execute automatically on events -**Hook Types** (5 types, 28 events): +**Hook Types** (5 types, 29 events): - **Tool Hooks**: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` - **Session Hooks**: `SessionStart`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop` - **Task Hooks**: `UserPromptSubmit`, `TaskCompleted`, `TaskCreated`, `TeammateIdle` @@ -871,12 +871,13 @@ MIT License - see [LICENSE](LICENSE). Free to use, modify, and distribute. The o --- -**Last Updated**: May 9, 2026 -**Claude Code Version**: 2.1.138 +**Last Updated**: May 19, 2026 +**Claude Code Version**: 2.1.143 **Sources**: - https://code.claude.com/docs/en/overview - https://code.claude.com/docs/en/changelog - https://github.com/anthropics/claude-code/releases/tag/v2.1.131 - https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.143 - https://github.com/anthropics/claude-code/releases/tag/v2.1.113 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5