diff --git a/docs/harness/claudecode/claudecode-vertexai.md b/docs/harness/claudecode/claudecode-vertexai.md index 405aa16..eef8540 100644 --- a/docs/harness/claudecode/claudecode-vertexai.md +++ b/docs/harness/claudecode/claudecode-vertexai.md @@ -9,7 +9,7 @@ audit through Google Cloud. > login prompt still labels it **Google Vertex AI**, and its environment variables keep the `VERTEX` > name. > -> Verified against Claude Code 2.1.299 on 2026-10-14. +> Verified against Claude Code 2.1.302 on 2026-10-18. This page covers the minimum setup. Anthropic maintains the full procedure, including IAM, region rules, model pinning, and troubleshooting, in diff --git a/docs/skills/agent-creator-claudecode.md b/docs/skills/agent-creator-claudecode.md index 5925693..77bed55 100644 --- a/docs/skills/agent-creator-claudecode.md +++ b/docs/skills/agent-creator-claudecode.md @@ -6,7 +6,7 @@ conditions under which Claude Code silently skips a file, and tool and permissio - **Skill name:** `agent-creator-claudecode` - **Source:** [skills/agent-creator-claudecode](https://github.com/CowboyLogic/ai-dev/tree/main/skills/agent-creator-claudecode) -- **Claude Code version:** verified against [Claude Code 2.1.299](https://github.com/anthropics/claude-code/releases/tag/v2.1.299) (released 2026-10-14), last re-verified 2026-10-14 +- **Claude Code version:** verified against [Claude Code 2.1.302](https://github.com/anthropics/claude-code/releases/tag/v2.1.302) (released 2026-10-16), last re-verified 2026-10-18 --- diff --git a/docs/skills/client-config-claudecode.md b/docs/skills/client-config-claudecode.md index ca33c26..50954c6 100644 --- a/docs/skills/client-config-claudecode.md +++ b/docs/skills/client-config-claudecode.md @@ -6,7 +6,7 @@ MCP servers, model configuration, sandbox isolation, auto mode, voice, and plugi - **Skill name:** `client-config-claudecode` - **Source:** [skills/client-config-claudecode](https://github.com/CowboyLogic/ai-dev/tree/main/skills/client-config-claudecode) -- **Claude Code version:** verified against [Claude Code 2.1.299](https://github.com/anthropics/claude-code/releases/tag/v2.1.299) (released 2026-10-14), last re-verified 2026-10-14 +- **Claude Code version:** verified against [Claude Code 2.1.302](https://github.com/anthropics/claude-code/releases/tag/v2.1.302) (released 2026-10-16), last re-verified 2026-10-18 --- @@ -61,7 +61,7 @@ npx skills ls -g --agent claude-code In a benchmark run on 2026-04-26, the skill raised the assertion pass rate from 80% to 100%, with the gain concentrated on settings that postdate the model's training. That run -predates the 2026-09-24, 2026-10-11, 2026-10-13, and 2026-10-14 reference refreshes. The detail is in the [skill README](https://github.com/CowboyLogic/ai-dev/blob/main/skills/client-config-claudecode/README.md), +predates the 2026-09-24, 2026-10-11, 2026-10-13, 2026-10-14, and 2026-10-18 reference refreshes. The detail is in the [skill README](https://github.com/CowboyLogic/ai-dev/blob/main/skills/client-config-claudecode/README.md), and the version history is in the [CHANGELOG](https://github.com/CowboyLogic/ai-dev/blob/main/skills/client-config-claudecode/CHANGELOG.md). diff --git a/skills/agent-creator-claudecode/README.md b/skills/agent-creator-claudecode/README.md index a2f9863..f6b574a 100644 --- a/skills/agent-creator-claudecode/README.md +++ b/skills/agent-creator-claudecode/README.md @@ -3,13 +3,13 @@ A skill for creating and troubleshooting custom subagents for Claude Code. > [!NOTE] -> **Claude Code version:** verified against [Claude Code 2.1.299](https://github.com/anthropics/claude-code/releases/tag/v2.1.299) -> (released 2026-10-14; the npm `latest` and `next` tags on 2026-10-14, with `stable` at 2.1.287). +> **Claude Code version:** verified against [Claude Code 2.1.302](https://github.com/anthropics/claude-code/releases/tag/v2.1.302) +> (released 2026-10-16; the npm `latest` and `next` tags on 2026-10-18, with `stable` at 2.1.292). > Field behavior comes from , with failure > behavior from , checked against the changelog -> through 2.1.299. Where only the changelog supports a claim (`autoCompactWindow`, -> `CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL`, MCP server names containing `__` in `tools`), the -> reference says so. Last re-verified 2026-10-14. +> through 2.1.302. Where only the changelog supports a claim (`CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL`, +> MCP server names containing `__` in `tools`, fork mode defaulting on in `-p`, the Agent SDK, +> the desktop app and VS Code), the reference says so. Last re-verified 2026-10-18. > Re-verify when Claude Code ships a new release. ## Overview diff --git a/skills/agent-creator-claudecode/SKILL.md b/skills/agent-creator-claudecode/SKILL.md index 2aca35c..668a926 100644 --- a/skills/agent-creator-claudecode/SKILL.md +++ b/skills/agent-creator-claudecode/SKILL.md @@ -163,7 +163,7 @@ the same family, including any `[1m]` context suffix. | `color` | `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` | | `initialPrompt` | First user turn when the file runs as the main session agent | | `experimental` | `{cacheTtl: 5m \| 1h}` prompt cache lifetime | -| `autoCompactWindow` | Auto-compact earlier than the main conversation's window (v2.1.296; changelog only, not yet in the docs table) | +| `autoCompactWindow` | Auto-compact earlier than the main conversation's window: a token count from `100000` to `1000000` (v2.1.296+; `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, when set, wins) | Plugin agents ignore `hooks`, `mcpServers`, `permissionMode`, and `initialPrompt`. Copy the file into `.claude/agents/` if you need them. diff --git a/skills/agent-creator-claudecode/references/frontmatter-reference.md b/skills/agent-creator-claudecode/references/frontmatter-reference.md index 46e5d67..a2ede7b 100644 --- a/skills/agent-creator-claudecode/references/frontmatter-reference.md +++ b/skills/agent-creator-claudecode/references/frontmatter-reference.md @@ -3,12 +3,12 @@ Reference for the YAML frontmatter fields of Claude Code agent files. Load this file when writing, reviewing, or debugging agent frontmatter. -**Source (last verified 2026-10-14 against Claude Code 2.1.299; the docs page references -versions up to v2.1.292):** +**Source (last verified 2026-10-18 against Claude Code 2.1.302; the docs page references +versions up to v2.1.296):** -`autoCompactWindow` is the one field here that only the v2.1.296 changelog supports; the -docs table does not list it yet. +Every field in this file is in the docs table. Where a note below is labeled "changelog only", +the Claude Code changelog is its only source. Field names are camelCase and case-sensitive. **Unrecognized fields are ignored without an error**, so a misspelling looks exactly like a working file. @@ -45,7 +45,7 @@ color: blue initialPrompt: "Start by reading TODO.md" # main-session use only experimental: # v2.1.248+ cacheTtl: 5m -autoCompactWindow: 200000 # v2.1.296+ (changelog only) +autoCompactWindow: 200000 # v2.1.296+; 100000 to 1000000 --- ``` @@ -214,6 +214,14 @@ subagents in foreground or background"): when Claude needs the result before continuing. `background: true` keeps the agent in the background even then. +Changelog only (v2.1.302): fork mode is now also on by default in `claude -p`, the Agent SDK, +the desktop app and VS Code, so case 3 applies there; `CLAUDE_CODE_FORK_SUBAGENT=0` turns it +off, and `claude mcp serve` never offers forks. The desktop app and VS Code always run the +main conversation's subagents in the background, as the terminal does. The exception to +case 3 is a subagent's own Agent calls in `-p`, the Agent SDK, the desktop app and VS Code, +which run in the foreground by default. The sub-agents docs page still says fork mode is off for `-p` and the SDK (checked +2026-10-18), so case 4 as written above is the pre-2.1.302 behavior there. + A skill with `context: fork` follows the skills docs instead. Background agents get a smaller built-in tool set than foreground ones, except forks and resumed foreground agents. @@ -253,12 +261,15 @@ user prompt. Ignored for plugin agents. Does nothing when the file is used as a ### `autoCompactWindow` -Lets this agent auto-compact earlier than the main conversation's window (added in v2.1.296; -supported in frontmatter and `--agents` definitions). Same key name as the -`autoCompactWindow` setting, a token count, which the settings reference documents as 100000 -to 1000000. The v2.1.296 -changelog entry does not state the range or precedence for the frontmatter field, so verify -against the sub-agents docs page before relying on either. +Lets this agent auto-compact earlier than the main conversation's window (requires v2.1.296 +or later; supported in frontmatter and `--agents` definitions). A token count from `100000` +to `1000000`. If `CLAUDE_CODE_AUTO_COMPACT_WINDOW` is set to a positive integer, the agent +uses that variable's window and the field has no effect. + +Write a plain integer such as `200000`: in frontmatter `200k` is read as 200, which is out of +range. An out-of-range value is ignored (the agent still loads and compacts as if the field +were absent); search `claude --debug` output for `invalid autoCompactWindow` to confirm. +Source: ### `experimental` @@ -287,8 +298,7 @@ under `experimental`, not a top-level key. Not accepted in `--agents` JSON. Session-only agents, not saved to disk. Each top-level key is the name; the value takes `prompt` plus these fields: `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, -`effort`, `background`, `omitClaudeMd`, `isolation`, and (v2.1.296, changelog only) -`autoCompactWindow`. +`effort`, `background`, `omitClaudeMd`, `isolation`, and (v2.1.296+) `autoCompactWindow`. ```bash claude --agents '{ diff --git a/skills/agent-creator-claudecode/references/tools-reference.md b/skills/agent-creator-claudecode/references/tools-reference.md index 5753b51..317517d 100644 --- a/skills/agent-creator-claudecode/references/tools-reference.md +++ b/skills/agent-creator-claudecode/references/tools-reference.md @@ -74,13 +74,15 @@ same context. | Need | How | |---|---| | Start one yourself | `/subtask ` (v2.1.212+; `/fork` on v2.1.161 through v2.1.211, and `/fork` also starts one when agent view is turned off) | -| Fork mode default | On in interactive sessions (v2.1.232+); off with `-p` and in the Agent SDK | -| Force fork mode | `CLAUDE_CODE_FORK_SUBAGENT=1` on everywhere, `0` off everywhere | +| Fork mode default | On in interactive sessions (v2.1.232+); off with `-p` and in the Agent SDK per the docs page. Changelog only (v2.1.302): also on by default in `-p`, the Agent SDK, the desktop app and VS Code, and `claude mcp serve` never offers forks | +| Force fork mode | `CLAUDE_CODE_FORK_SUBAGENT=1` on, `0` off, in every kind of session except `claude mcp serve`, which never offers forks (changelog only, v2.1.302) | | Keep fork mode but stop Claude spawning forks | Deny the `fork` type: `Agent(fork)` in `permissions.deny` | | Isolate a fork's edits | Claude passes `isolation: "worktree"` on the Agent call | With fork mode on, Claude Code runs every subagent Claude spawns in the background, forks -and non-fork alike, and removes the Agent tool's `run_in_background` parameter. A fork cannot +and non-fork alike, and removes the Agent tool's `run_in_background` parameter (apart from the +cases that stay in the foreground; changelog only, v2.1.302: a subagent's own Agent calls in +`-p`, the Agent SDK, the desktop app and VS Code run in the foreground by default). A fork cannot spawn further forks. Source: . --- diff --git a/skills/agent-creator-claudecode/references/troubleshooting.md b/skills/agent-creator-claudecode/references/troubleshooting.md index 1c36d6a..d109537 100644 --- a/skills/agent-creator-claudecode/references/troubleshooting.md +++ b/skills/agent-creator-claudecode/references/troubleshooting.md @@ -122,7 +122,7 @@ Claude Code ignores unrecognized fields without any error. Check in this order: |---|---|---| | `Agent '' would be spawned with zero tools — refusing` | Every `tools` entry is **unrecognized** (typo such as `Grpe`), **not available to subagents** (`AskUserQuestion`, `Workflow`, `CronCreate` in the background), or **matched no tools in this session** (`mcp__github__*` with no GitHub server, `Agent` at the depth limit) | Fix each entry the error names. Or delete `tools` to inherit everything | | Agent has fewer tools than listed, no error | Some entries resolved and others were dropped (background filter, unconnected MCP server) | Check the foreground/background note below; verify MCP servers are connected | -| Works with `--agent` but not when delegated | Delegated agents run in the background by default, with a reduced tool set | Remove entries only foreground agents get, set `background: false` and ask for foreground, or turn fork mode off | +| Works with `--agent` but not when delegated | Delegated agents run in the background by default, with a reduced tool set | Remove entries only foreground agents get, set `background: false` and ask for foreground, or turn fork mode off (`CLAUDE_CODE_FORK_SUBAGENT=0`) | | `disallowedTools: Bash(git push *)` removed all of Bash | Specifiers remove the whole tool | Use a `permissions.deny` rule or a `PreToolUse` hook | | Agent can edit despite `tools: Read, Grep` | `memory` enables Read, Write, and Edit for the memory directory | Drop `memory` or accept that Write/Edit are scoped to memory files | | Agent cannot spawn subagents | `Agent` missing from `tools`, depth limit reached, or the tool is withheld at the limit | Add `Agent`; check `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | diff --git a/skills/agent-creator-claudecode/scripts/validate-agent.py b/skills/agent-creator-claudecode/scripts/validate-agent.py index 2abcd05..8c18c53 100755 --- a/skills/agent-creator-claudecode/scripts/validate-agent.py +++ b/skills/agent-creator-claudecode/scripts/validate-agent.py @@ -8,9 +8,8 @@ unknown or mis-cased fields, bad enum values, and fields ignored in a given scope. Requires PyYAML. Exit status is 1 when any error is found (or any warning with --strict). -Field list last verified 2026-10-14 against Claude Code 2.1.299: +Field list last verified 2026-10-18 against Claude Code 2.1.302: https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields -(`autoCompactWindow` comes from the v2.1.296 changelog; the docs table does not list it yet.) """ from __future__ import annotations @@ -62,7 +61,8 @@ "experimental": "v2.1.248", "autoCompactWindow": "v2.1.296", } -NAME_MAX_LENGTH = 256 # longer names are skipped (docs: "Subagent files Claude Code skips") +AUTO_COMPACT_WINDOW_RANGE = (100_000, 1_000_000) # docs: "a token count from 100000 to 1000000" +NAME_MAX_LENGTH = 256 # longer names are skipped (docs: "Subagent files Claude Code skips") SKILLS_PRELOAD_MAX = 32 # only the first 32 distinct names are preloaded TOOL_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\(.*\))?$") CASE_INSENSITIVE = {f.lower(): f for f in KNOWN_FIELDS} @@ -336,6 +336,9 @@ def validate(path: Path, plugin: bool) -> Report: acw = data.get("autoCompactWindow") if acw is not None and (isinstance(acw, bool) or not isinstance(acw, int) or acw < 1): rep.error("autoCompactWindow: must be a positive integer number of tokens") + elif acw is not None and not AUTO_COMPACT_WINDOW_RANGE[0] <= acw <= AUTO_COMPACT_WINDOW_RANGE[1]: + rep.warn(f"autoCompactWindow: {acw} is outside {AUTO_COMPACT_WINDOW_RANGE[0]} to " + f"{AUTO_COMPACT_WINDOW_RANGE[1]}; Claude Code ignores it and compacts as if it were absent") mcp = data.get("mcpServers") if mcp is not None: diff --git a/skills/client-config-claudecode/CHANGELOG.md b/skills/client-config-claudecode/CHANGELOG.md index 20bf2db..d4e3336 100644 --- a/skills/client-config-claudecode/CHANGELOG.md +++ b/skills/client-config-claudecode/CHANGELOG.md @@ -2,6 +2,40 @@ Changes to the `client-config-claudecode` skill, newest first. +## 2026-10-18 — v2.4 (verified against Claude Code 2.1.302) + +Basis: Claude Code 2.1.302 (released 2026-10-16; npm `latest` and `next`, `stable` is +2.1.292), the 2.1.300–2.1.302 changelog, and the `code.claude.com/docs` pages fetched +2026-10-18. Claims only the changelog supports are labeled "changelog only" in the references. + +- `references/permissions.md`: an MCP allow rule for a server whose name contains `__` or ends + in `_` is now documented upstream, so it is no longer labeled changelog only (deny and ask + rules still are); adds the auto mode classifier model (Sonnet 5 by default, with the fallbacks + the permission-modes page lists); changelog only: `CLAUDE_CODE_AUTO_MODE_MODEL` (v2.1.302), + server-side auto mode compacting a conversation too long for its safety check (v2.1.302), and + `claude -p`/Agent SDK sessions now starting in `default` on third-party providers, with + telemetry off, or on a fresh install (v2.1.302; the docs table still shows the earlier rule). +- `references/hooks.md`: the `prompt`/`agent` hook `model` default is now worded as the docs + give it (the model used for background functionality). Changelog only: agent hooks honor + `model` (v2.1.300), at most 12 prompt/agent hooks of one event run at once (v2.1.302), + `updatedInput` from `PreToolUse`/`PermissionRequest` hooks is validated (v2.1.300), a + `setMode` update in a `PermissionRequest` allow is ignored in Cowork cloud sessions + (v2.1.300), and plugin `WorktreeCreate`/`WorktreeRemove` hooks run with `--worktree` + (v2.1.300). +- `references/mcp.md`: adds the MCP docs page's rules for root-level `anyOf`/`oneOf`/`allOf` + schemas, invalid input schemas, and tool names over 128 characters; changelog only: a tool + whose schema the API still rejects is sent without parameters for the rest of the + conversation (v2.1.300). +- `references/settings-schema.md`: `advisorModel` notes `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` and + that the changelog adds `/advisor` on Claude Platform on AWS (v2.1.300) where the settings + reference still lists it as unavailable; `idleCompaction` notes the `/config` row (v2.1.302, + changelog only). +- Checked and unchanged: all 245 rows of the settings reference index are in the references and + the validator; every hook event in the hooks docs is covered; the Google Vertex AI page + claims hold. +- Evals: new `mcp-server-name-with-double-underscore` eval; not yet run (the README results + predate it). + ## 2026-10-14 — v2.3 (verified against Claude Code 2.1.299) Basis: Claude Code 2.1.299 (released 2026-10-14; npm `latest` and `next`, `stable` is diff --git a/skills/client-config-claudecode/README.md b/skills/client-config-claudecode/README.md index 2d208dc..0ffb79c 100644 --- a/skills/client-config-claudecode/README.md +++ b/skills/client-config-claudecode/README.md @@ -4,22 +4,23 @@ Evaluation results for the `client-config-claudecode` skill. The skill itself is [SKILL.md](SKILL.md), and its history is in [CHANGELOG.md](CHANGELOG.md). > [!NOTE] -> **Claude Code version:** verified against [Claude Code 2.1.299](https://github.com/anthropics/claude-code/releases/tag/v2.1.299) -> (released 2026-10-14; the npm `latest` and `next` tags on 2026-10-14, with `stable` at 2.1.287). +> **Claude Code version:** verified against [Claude Code 2.1.302](https://github.com/anthropics/claude-code/releases/tag/v2.1.302) +> (released 2026-10-16; the npm `latest` and `next` tags on 2026-10-18, with `stable` at 2.1.292). > References come from the `code.claude.com/docs` pages listed in -> [assets/sources.json](assets/sources.json), checked against the changelog through 2.1.299. +> [assets/sources.json](assets/sources.json), checked against the changelog through 2.1.302. > Where only the changelog supports a claim, the reference says so. Last re-verified -> 2026-10-14. Re-verify when Claude Code ships a new release. +> 2026-10-18. Re-verify when Claude Code ships a new release. ## Evaluation results Benchmark run: **2026-04-26 · iteration 1** · 3 scenarios · 6 total runs These results predate the 2026-09-24 v2.0 refresh, the 2026-10-11 v2.1 update, the -2026-10-13 v2.2 update, and the 2026-10-14 v2.3 update. -[evals/evals.json](evals/evals.json) holds the eval cases; it also includes four cases that +2026-10-13 v2.2 update, the 2026-10-14 v2.3 update, and the 2026-10-18 v2.4 update. +[evals/evals.json](evals/evals.json) holds the eval cases; it also includes five cases that this run did not cover: `default-mode-scope` (added in v2.0), `hook-fail-closed` (added in -v2.1), `stop-hook-loop-cap` (added in v2.2), and `idle-compaction` (added in v2.3). +v2.1), `stop-hook-loop-cap` (added in v2.2), `idle-compaction` (added in v2.3), and +`mcp-server-name-with-double-underscore` (added in v2.4). ### Overall diff --git a/skills/client-config-claudecode/evals/evals.json b/skills/client-config-claudecode/evals/evals.json index d651d80..88a9444 100644 --- a/skills/client-config-claudecode/evals/evals.json +++ b/skills/client-config-claudecode/evals/evals.json @@ -192,6 +192,26 @@ "description": "Mentions the alternative of raising CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS (default 200000, floor 100000) instead of turning it off" } ] + }, + { + "id": 8, + "name": "mcp-server-name-with-double-underscore", + "prompt": "I have an MCP server configured as reports__v2. I added \"mcp__reports__v2\" to permissions.allow in settings.json but Claude still prompts for every one of its tools. What's wrong?", + "expected_output": "Explains that the bare mcp__reports__v2 rule is not read as a rule for the reports__v2 server: under the mcp____ grammar it names server reports (and tool v2), so it does not match the reports__v2 server's tools, and gives mcp__reports__v2__* as the rule to write", + "assertions": [ + { + "id": "misread-rule", + "description": "Explains that mcp__reports__v2 (and mcp__reports) is parsed against a server named reports (for mcp__reports__v2, with v2 as a tool name) and so does not allow the reports__v2 server's tools" + }, + { + "id": "wildcard-form", + "description": "Gives mcp__reports__v2__* (the wildcard form with the whole server name) as the rule to write" + }, + { + "id": "name-ends-underscore", + "description": "Notes the same wildcard form is needed for a server name that ends in an underscore" + } + ] } ] } diff --git a/skills/client-config-claudecode/references/hooks.md b/skills/client-config-claudecode/references/hooks.md index 620f0f5..2b720d2 100644 --- a/skills/client-config-claudecode/references/hooks.md +++ b/skills/client-config-claudecode/references/hooks.md @@ -198,7 +198,7 @@ A hook process inherits Claude Code's environment, minus the `OTEL_*` exporter v } ``` -Optional `model` (defaults to a fast model). `$ARGUMENTS` is replaced by the hook input JSON; escape a literal `$` as `\$`. Model must return `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block, optionally with `"impossible": true` (on `Stop`/`SubagentStop` this lets the turn end instead of feeding the reason back). On `PreToolUse`, `ok: false` denies and ends the turn unless the handler sets `continueOnBlock: true`. +Optional `model` (defaults to the model Claude Code uses for background functionality). `$ARGUMENTS` is replaced by the hook input JSON; escape a literal `$` as `\$`. Model must return `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block, optionally with `"impossible": true` (on `Stop`/`SubagentStop` this lets the turn end instead of feeding the reason back). On `PreToolUse`, `ok: false` denies and ends the turn unless the handler sets `continueOnBlock: true`. ### `agent` (spawns a subagent verifier — experimental) @@ -212,6 +212,8 @@ Optional `model` (defaults to a fast model). `$ARGUMENTS` is replaced by the hoo Same response schema as `prompt`. Agent can use Read, Grep, Glob to inspect the codebase. +Changelog only: from v2.1.300 an agent hook honors its `model` (an alias such as `haiku` resolves, a subagent's own model no longer overrides it, and an unavailable model falls back to the caller's model instead of allowing the action). From v2.1.302 at most 12 `prompt` or `agent` hooks of one event run at a time; the rest wait their turn. + --- ## Hook input (stdin JSON) @@ -319,6 +321,8 @@ An **async** hook's JSON response must be alone on stdout or on one line of its `"defer"` — only honored in non-interactive mode (`-p`); ignored with a warning in interactive sessions or when Claude makes several tool calls in one turn. Exits with `stop_reason: "tool_deferred"` and the pending call in `deferred_tool_use` (id/name/input); an external process resumes with `claude -p --resume ` and the same tool call fires `PreToolUse` again so the hook can return `"allow"` with the answer in `updatedInput`. Typical use: `AskUserQuestion` answered by a host UI with no terminal. +`updatedInput` replaces the whole input object, so include the unchanged fields too. Changelog only (v2.1.300): the value from a `PreToolUse` or `PermissionRequest` hook is validated like Claude's own input: unknown keys are dropped, and input the tool rejects denies the call. + **Legacy note**: top-level `decision`/`reason` (`"approve"`/`"block"`) are deprecated for `PreToolUse` specifically — use `hookSpecificOutput.permissionDecision`. Other events (`PostToolUse`, `Stop`, etc.) still use top-level `decision`/`reason`. ### PermissionRequest (use `hookSpecificOutput.decision`) @@ -327,7 +331,7 @@ An **async** hook's JSON response must be alone on stdout or on one line of its { "hookSpecificOutput": { "hookEventName": "PermissionRequest", "decision": { "behavior": "allow", "updatedInput": { "command": "npm run lint" } } } } ``` -`decision.behavior`: `"allow"` | `"deny"`. No prompt reaches the user; runs even for background subagents in headless mode (denies by default if no hook decides). For `allow`, `updatedPermissions` can also add rules or change the session mode. Not run for a sandboxed command's network request. +`decision.behavior`: `"allow"` | `"deny"`. No prompt reaches the user; runs even for background subagents in headless mode (denies by default if no hook decides). For `allow`, `updatedPermissions` can also add rules or change the session mode. Not run for a sandboxed command's network request. Changelog only (v2.1.300): in Cowork cloud sessions a `setMode` update in a hook's `allow` is ignored; the rest of the approval still applies. ### PermissionDenied retry @@ -356,6 +360,8 @@ An **async** hook's JSON response must be alone on stdout or on one line of its echo "$HOME/.claude/worktrees/$NAME" ``` +Changelog only (v2.1.300): plugin `WorktreeCreate` and `WorktreeRemove` hooks now also run when Claude Code starts with `--worktree` (not yet with `--tmux`). + --- ## Common hook patterns diff --git a/skills/client-config-claudecode/references/mcp.md b/skills/client-config-claudecode/references/mcp.md index aba9df9..8b7a2f3 100644 --- a/skills/client-config-claudecode/references/mcp.md +++ b/skills/client-config-claudecode/references/mcp.md @@ -132,6 +132,7 @@ Tool search is on by default: a server's tools are deferred and found on demand. - **Client runtime**: Claude Code picks the v1 or v2 MCP client runtime at startup. `MCP_SDK_GENERATION` (`v1` | `v2`) forces one. `MCP_PROTOCOL_NEGOTIATION` (`auto` | `legacy`) decides whether Claude Code asks servers for protocol revision 2026-07-28; `legacy` keeps every server on the earlier handshake. - **URL elicitation** (changelog, v2.1.287): servers on the 2025-11-25 protocol can send URL prompts. A server that stops connecting after that update can be given `"bareElicitationCapability": true` in its config entry. This key is not in the MCP docs page. - **WebSocket limit** (changelog, v2.1.295): a `ws` message over 16 MiB is no longer parsed and closes the connection, the same limit the other transports already have. +- **Tool schemas and names** (MCP docs page): a tool whose input schema has `anyOf`, `oneOf` or `allOf` at the root is flattened into one object schema with a sentence prepended to its description (a `oneOf`/`anyOf` branch's `required` list is described, not enforced, so the server must keep validating the combination); on a deployment that does not receive the remote configuration enabling the rewrite, or when no valid schema can be produced, Claude Code skips that one tool and logs the reason. A tool with an invalid schema (a top-level property name outside 1–64 ASCII letters, digits, `_`, `.`, `-`, or, for a schema that declares no `$schema` or declares draft 2020-12, a failure of the draft 2020-12 meta-schema; a schema declaring another dialect skips that check but still gets the property-name check) is excluded and the reason goes to the server's log, so one bad tool does not break the server's other tools; the exclusion is switched on by a flag Claude Code fetches, so with flag fetching off the tool is still sent and the API answers with a 400. A tool whose full name is over 128 characters is left out. Changelog only (v2.1.300): when the API still rejects a tool's input schema, Claude Code sends that tool without parameters for the rest of the conversation instead of failing every turn with a 400. --- @@ -197,7 +198,7 @@ These control MCP behavior; the servers themselves are in `~/.claude.json` / `.m } ``` -Pattern: `mcp____` (bare `mcp__` also matches all its tools). Plugin-bundled servers use `mcp__plugin____`; claude.ai connectors use `mcp__claude_ai___`. Allow-rule globs need a literal `mcp____` prefix; `mcp__*` works only in deny/ask. +Pattern: `mcp____` (bare `mcp__` also matches all its tools, except for a server whose name contains `__` or ends in `_`: write `mcp____*`, see `permissions.md`). Plugin-bundled servers use `mcp__plugin____`; claude.ai connectors use `mcp__claude_ai___`. Allow-rule globs need a literal `mcp____` prefix; `mcp__*` works only in deny/ask. **Tools that force a prompt regardless of allow rules / permission mode:** diff --git a/skills/client-config-claudecode/references/permissions.md b/skills/client-config-claudecode/references/permissions.md index fde7372..d1f7a50 100644 --- a/skills/client-config-claudecode/references/permissions.md +++ b/skills/client-config-claudecode/references/permissions.md @@ -107,7 +107,7 @@ mcp__claude_ai___ → claude.ai connector tools An `mcp__` rule with parentheses (parameter match) is skipped when loaded from a settings file — use `--disallowedTools` for that. -Changelog only (v2.1.299): an MCP allow rule reaches only the server it names. `mcp__a` no longer allows a server named `a__b` or `a_`; for a server whose normalized name contains `__`, write `mcp____*`. Deny and ask rules for `mcp__` now also apply to such servers. The same holds for an agent's `tools:` list (see `agent-creator-claudecode`). +An MCP allow rule reaches only the server it names (v2.1.299; the permissions docs now state it). For a server whose normalized name contains `__` or ends in `_`, write `mcp____*`: for a server named `reports__v2` that is `mcp__reports__v2__*`, and the bare `mcp__reports__v2` or `mcp__reports` does not allow its tools. Changelog only (v2.1.299): deny and ask rules for `mcp__` now also apply to such servers. For a server whose name contains `__`, the same wildcard form holds for an agent's `tools:` list (changelog only; see `agent-creator-claudecode`, which does not cover a trailing `_` there). ### Tool-name wildcards @@ -188,8 +188,12 @@ One parameter per rule; `*` wildcard supported; omitted params never match. A to | Org HIPAA configuration applied and the session is eligible | `default` from v2.1.285 (auto mode stays available to switch to) | | Terminal or VS Code extension | `auto` from v2.1.283; earlier: `auto` on Pro/Max/Team in sessions that fetch flags, `default` otherwise | +Changelog only (v2.1.302): `claude -p` and Agent SDK sessions with no permission mode now start in `default` on third-party providers, with telemetry off, or on a fresh install, where the `-p` row above says `auto`; `--permission-mode auto` keeps `auto`. The permission-modes docs page still shows the earlier behavior. + When `auto` is selected but unavailable to the session (a settings file turned it off, an unsupported model, or Anthropic disabled it server-side), the session starts in Manual. The first session after an install or upgrade can choose its mode before flags arrive and so can differ from this table. +**Auto mode classifier model:** it runs on Claude Sonnet 5 by default, not on your `/model` choice, and a classifier model Anthropic configures server-side takes precedence. When the session model is Claude Sonnet 4.6, or `availableModels` excludes Sonnet 5, it runs on the session's model instead, or on an Opus model when the session runs on a Fable model. `CLAUDE_CODE_AUTO_MODE_MODEL` (v2.1.302, changelog only) picks the model for the client-side classifier; it does not change the model for server-side auto mode. From v2.1.302 (changelog only), a conversation too long for the server-side classifier's safety check is compacted instead of every checked tool call being denied. + **Actions no mode auto-approves** (even `bypassPermissions`): explicit `ask` rules; org connector tools set to `ask`; `AskUserQuestion` and MCP tools marked `requiresUserInteraction`; `rm`/`rmdir` targeting a critical path (circuit breaker — no allow rule or hook `"allow"` approves it; `dontAsk` denies it, `auto` sends it to the classifier); cross-session messaging safeguards; reads outside working dirs while `blockReadsOutsideWorkingDirectories` is on. --- diff --git a/skills/client-config-claudecode/references/settings-schema.md b/skills/client-config-claudecode/references/settings-schema.md index 4fb6ac9..3abf50a 100644 --- a/skills/client-config-claudecode/references/settings-schema.md +++ b/skills/client-config-claudecode/references/settings-schema.md @@ -66,7 +66,7 @@ Managed system dirs: macOS `/Library/Application Support/ClaudeCode/`, Linux/WSL | `modelPricing` | *(Managed only)* Contracted rates for cost display: `{multiplier?, overrides?}` (v2.1.242+) | see upstream | | `outputStyle` | Built-in or custom output style name | `"Explanatory"` | | `agent` | Run main thread as named subagent | `"code-reviewer"` | -| `advisorModel` | Model for the advisor tool: `"fable"`\|`"opus"`\|`"sonnet"` or a full ID (unset = advisor off) | `"opus"` | +| `advisorModel` | Model for the advisor tool: `"fable"`\|`"opus"`\|`"sonnet"` or a full ID (unset = advisor off). `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1` turns the advisor off and this key can't turn it back on. The settings reference lists Amazon Bedrock and Claude Platform on AWS as providers where the advisor is unavailable; the v2.1.300 changelog adds `/advisor` on Claude Platform on AWS (changelog only; the docs page has not caught up) | `"opus"` | | `fallbackModel` | Ordered fallback chain when primary is overloaded/unavailable; `"default"` expands to the default model. At most 3 distinct models kept; doesn't merge across files | `["claude-sonnet-5", "claude-haiku-4-5"]` | | `switchModelsOnFlag` | Default `true`. Auto-switch to fallback when a safety classifier flags a request | `false` | | `fastMode` | Turn on fast mode where available; `/fast` writes this | `true` | @@ -164,7 +164,7 @@ claude auto-mode critique # AI review of your custom rules | `autoMemoryDirectory` | Absolute or `~/` path (default `~/.claude/projects//memory/`) | `"~/my-memory-dir"` | | `autoCompactEnabled` | Auto-compact near context limit (default `true`) | `false` | | `autoCompactWindow` | Tokens before auto-compact, `100000`–`1000000`, capped at model window | `400000` | -| `idleCompaction` | Compact a long conversation that sat idle, shortly before its prompt cache expires (default `true`; v2.1.290+). Applies only to interactive terminal sessions on the one-hour cache TTL with feature flags fetched, once the context reaches 200,000 tokens (`CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` raises or lowers it; values below `100000` are raised to `100000`) and about 54 minutes have passed since the last request. `autoCompactEnabled: false` and `DISABLE_AUTO_COMPACT` also turn it off | `false` | +| `idleCompaction` | Compact a long conversation that sat idle, shortly before its prompt cache expires (default `true`; v2.1.290+). Applies only to interactive terminal sessions on the one-hour cache TTL with feature flags fetched, once the context reaches 200,000 tokens (`CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` raises or lowers it; values below `100000` are raised to `100000`) and about 54 minutes have passed since the last request. `autoCompactEnabled: false` and `DISABLE_AUTO_COMPACT` also turn it off. `/config` has an "Idle compaction" row for the same toggle, and the notice shown after an idle compaction says how to turn it off (v2.1.302, changelog only) | `false` | | `bashOutputMaxChars` | Inline Bash/PowerShell output limit, clamped `4000`–`128000` (default 30,000; v2.1.261+) | `60000` | | `claudeMdExcludes` | Globs/absolute paths of CLAUDE.md files to skip (not managed memory) | `["**/vendor/**/CLAUDE.md"]` | | `fileCheckpointingEnabled` | Snapshot files so `/rewind` can restore them (default `true`) | `false` |