From 6313b49607c1a8b47ea2508df608963337a1ecf5 Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:06:45 -0500 Subject: [PATCH 01/10] docs(client-config-claudecode): refresh against Claude Code 2.1.302 Add the 2.1.300-2.1.302 changes to the permissions, hooks, MCP and settings references, labeling claims only the changelog supports. Document the MCP schema and name rules and the auto mode classifier model from the upstream docs. Add the mcp-server-name-with-double- underscore eval, and stamp the README and CHANGELOG (v2.4). Co-Authored-By: Claude Sonnet 5.5 --- skills/client-config-claudecode/CHANGELOG.md | 34 +++++++++++++++++++ skills/client-config-claudecode/README.md | 15 ++++---- .../client-config-claudecode/evals/evals.json | 20 +++++++++++ .../references/hooks.md | 10 ++++-- .../references/mcp.md | 1 + .../references/permissions.md | 6 +++- .../references/settings-schema.md | 4 +-- 7 files changed, 78 insertions(+), 12 deletions(-) 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..3ce9121 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 read as a rule for a server named reports, 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 read as a rule for a server named reports 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..edc0c1f 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 stays available; Claude Code flattens it into one object schema and prepends a sentence to the description (a `oneOf`/`anyOf` branch's `required` list is described, not enforced, so the server must keep validating the combination). A tool with an invalid schema (a top-level property name outside 1–64 ASCII letters, digits, `_`, `.`, `-`, or a schema that fails the JSON Schema draft 2020-12 meta-schema) 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. --- diff --git a/skills/client-config-claudecode/references/permissions.md b/skills/client-config-claudecode/references/permissions.md index fde7372..4b89b61 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. The same naming holds for an agent's `tools:` list (see `agent-creator-claudecode`). ### 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` | From fd5ad146d70128aecf4b61934b01f1fe52e2f66e Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:06:45 -0500 Subject: [PATCH 02/10] docs(agent-creator-claudecode): verify against Claude Code 2.1.302 autoCompactWindow is now in the sub-agents docs table, so drop its "changelog only" label and document its range and precedence. The validator warns on a value outside 100000-1000000. Note the 2.1.302 fork mode and foreground/background default changes as changelog only, since the docs page still describes the earlier behavior. Co-Authored-By: Claude Sonnet 5.5 --- skills/agent-creator-claudecode/README.md | 10 +++--- skills/agent-creator-claudecode/SKILL.md | 2 +- .../references/frontmatter-reference.md | 36 ++++++++++++------- .../references/tools-reference.md | 2 +- .../references/troubleshooting.md | 2 +- .../scripts/validate-agent.py | 9 +++-- 6 files changed, 37 insertions(+), 24 deletions(-) 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..eff1fda 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, and a subagent's own +Agent calls in `-p`, the Agent SDK, the desktop app and VS Code 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..24569fc 100644 --- a/skills/agent-creator-claudecode/references/tools-reference.md +++ b/skills/agent-creator-claudecode/references/tools-reference.md @@ -74,7 +74,7 @@ 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 | +| 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 everywhere, `0` off everywhere | | 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 | 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: From 4dd56297f7929f624854c10c6889fc18d7847a3b Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:06:45 -0500 Subject: [PATCH 03/10] docs(claudecode): re-stamp skill pages and the Vertex AI page for 2.1.302 Every claim on the Vertex AI page was re-checked against the live Google Cloud Agent Platform docs page; only the verification stamp changed. Co-Authored-By: Claude Sonnet 5.5 --- docs/harness/claudecode/claudecode-vertexai.md | 2 +- docs/skills/agent-creator-claudecode.md | 2 +- docs/skills/client-config-claudecode.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) 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). From 75799b91131276905dd3bb896d522d1b093380c6 Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:10:40 -0500 Subject: [PATCH 04/10] fix(client-config-claudecode): note the remote-config exception for root-level schema combinators On a deployment without the remote configuration, Claude Code skips a tool with a root-level anyOf/oneOf/allOf instead of flattening it. Co-Authored-By: Claude Sonnet 5.5 --- skills/client-config-claudecode/references/mcp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/client-config-claudecode/references/mcp.md b/skills/client-config-claudecode/references/mcp.md index edc0c1f..b375d7e 100644 --- a/skills/client-config-claudecode/references/mcp.md +++ b/skills/client-config-claudecode/references/mcp.md @@ -132,7 +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 stays available; Claude Code flattens it into one object schema and prepends a sentence to the description (a `oneOf`/`anyOf` branch's `required` list is described, not enforced, so the server must keep validating the combination). A tool with an invalid schema (a top-level property name outside 1–64 ASCII letters, digits, `_`, `.`, `-`, or a schema that fails the JSON Schema draft 2020-12 meta-schema) 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. +- **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 a schema that fails the JSON Schema draft 2020-12 meta-schema) 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. --- From 92e6a7fc97aaf3caceeeac0505b4c703684bdaa1 Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:10:40 -0500 Subject: [PATCH 05/10] fix(client-config-claudecode): limit the draft 2020-12 schema check to schemas without another dialect Claude Code applies the meta-schema check only when $schema is absent or draft 2020-12; other dialects still get the property-name check. Co-Authored-By: Claude Sonnet 5.5 --- skills/client-config-claudecode/references/mcp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/client-config-claudecode/references/mcp.md b/skills/client-config-claudecode/references/mcp.md index b375d7e..e73ae6b 100644 --- a/skills/client-config-claudecode/references/mcp.md +++ b/skills/client-config-claudecode/references/mcp.md @@ -132,7 +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 a schema that fails the JSON Schema draft 2020-12 meta-schema) 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. +- **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. --- From 03be9e249fa3a6d5d875d7d27933792cb5f74969 Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:10:40 -0500 Subject: [PATCH 06/10] fix(agent-creator-claudecode): reconcile fork-mode background guidance with nested Agent calls The 2.1.302 changelog runs a subagent's own Agent calls in the foreground by default; qualify the "every subagent in the background" statements. Co-Authored-By: Claude Sonnet 5.5 --- .../references/frontmatter-reference.md | 6 +++--- .../agent-creator-claudecode/references/tools-reference.md | 4 +++- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/skills/agent-creator-claudecode/references/frontmatter-reference.md b/skills/agent-creator-claudecode/references/frontmatter-reference.md index eff1fda..a2ede7b 100644 --- a/skills/agent-creator-claudecode/references/frontmatter-reference.md +++ b/skills/agent-creator-claudecode/references/frontmatter-reference.md @@ -217,9 +217,9 @@ subagents in foreground or background"): 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, and a subagent's own -Agent calls in `-p`, the Agent SDK, the desktop app and VS Code run in the foreground by -default. The sub-agents docs page still says fork mode is off for `-p` and the SDK (checked +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 diff --git a/skills/agent-creator-claudecode/references/tools-reference.md b/skills/agent-creator-claudecode/references/tools-reference.md index 24569fc..2ac33f2 100644 --- a/skills/agent-creator-claudecode/references/tools-reference.md +++ b/skills/agent-creator-claudecode/references/tools-reference.md @@ -80,7 +80,9 @@ same context. | 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: . --- From e52dfd17ba7dbfb8f7c93cd8cc513447b41c5d63 Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:10:40 -0500 Subject: [PATCH 07/10] fix(client-config-claudecode): narrow the agent tools: naming note to names containing __ The agent-creator references document only the __ case for tools:, so don't extend the trailing-underscore rule to it. Co-Authored-By: Claude Sonnet 5.5 --- skills/client-config-claudecode/references/permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/client-config-claudecode/references/permissions.md b/skills/client-config-claudecode/references/permissions.md index 4b89b61..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. -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. The same naming 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 From b11803e0e949131c15c64b1c4c9721b336186b26 Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:14:16 -0500 Subject: [PATCH 08/10] fix(client-config-claudecode): qualify the bare mcp__ rule for special server names Names containing __ or ending in _ need the wildcard form with the whole name; the generic MCP permission pattern said the bare rule matches all. Co-Authored-By: Claude Sonnet 5.5 --- skills/client-config-claudecode/references/mcp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/client-config-claudecode/references/mcp.md b/skills/client-config-claudecode/references/mcp.md index e73ae6b..8b7a2f3 100644 --- a/skills/client-config-claudecode/references/mcp.md +++ b/skills/client-config-claudecode/references/mcp.md @@ -198,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:** From fe61e9c44ae77d9f09845eb0173cdc58c8546c5c Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:14:16 -0500 Subject: [PATCH 09/10] fix(agent-creator-claudecode): except claude mcp serve from the fork mode override The changelog says claude mcp serve never offers forks, so the CLAUDE_CODE_FORK_SUBAGENT row can't claim to enable them everywhere. Co-Authored-By: Claude Sonnet 5.5 --- skills/agent-creator-claudecode/references/tools-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/agent-creator-claudecode/references/tools-reference.md b/skills/agent-creator-claudecode/references/tools-reference.md index 2ac33f2..317517d 100644 --- a/skills/agent-creator-claudecode/references/tools-reference.md +++ b/skills/agent-creator-claudecode/references/tools-reference.md @@ -75,7 +75,7 @@ same context. |---|---| | 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 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 everywhere, `0` off everywhere | +| 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 | From b369c07459c357dc6f79f1569843f9d27e3f5651 Mon Sep 17 00:00:00 2001 From: MRSchexnayder Date: Sun, 18 Oct 2026 08:24:48 -0500 Subject: [PATCH 10/10] fix(client-config-claudecode): make the double-underscore eval accept the server/tool parse mcp__reports__v2 parses as server reports and tool v2 under the mcp____ grammar; the assertion no longer requires the looser "rule for a server named reports" wording. Co-Authored-By: Claude Sonnet 5.5 --- skills/client-config-claudecode/evals/evals.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/client-config-claudecode/evals/evals.json b/skills/client-config-claudecode/evals/evals.json index 3ce9121..88a9444 100644 --- a/skills/client-config-claudecode/evals/evals.json +++ b/skills/client-config-claudecode/evals/evals.json @@ -197,11 +197,11 @@ "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 read as a rule for a server named reports, so it does not match the reports__v2 server's tools, and gives mcp__reports__v2__* as the rule to write", + "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 read as a rule for a server named reports and so does not allow the reports__v2 server's tools" + "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",