From ae656f6fb82ec683446ae53f3eb77d9e3909febf Mon Sep 17 00:00:00 2001 From: Luong NGUYEN Date: Mon, 15 Jun 2026 07:54:49 +0200 Subject: [PATCH] docs: sync to Claude Code v2.1.176 (#141) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: sync to Claude Code v2.1.176 Fix the subagent-nesting self-contradiction in 04-subagents and document additive features shipped in v2.1.172-v2.1.176: - 04-subagents: subagents can now spawn subagents (up to 5 levels, v2.1.172), replacing the stale "no nested spawning" line; footer bumped to 2.1.176 - 07-plugins: /plugin marketplace search bar (v2.1.172) - 10-cli: new settings.json keys wheelScrollAccelerationEnabled, footerLinksRegexes, language (v2.1.174-v2.1.176) - 09-advanced-features: enforceAvailableModels managed setting (v2.1.175) - 06-hooks: if-condition tool-argument path matchers (verified against the official permissions reference) - claude_concepts_guide & CATALOG: subagent nesting note + VSCode /usage attribution breakdown (v2.1.174) * fix(10-cli): correct language setting scope and fix link-checker false positive - check_links.py: skip bare-hostname captures (no dot in host) that URL_RE truncates from regex strings in JSON config examples, e.g. "https://jira\\.example\\.com/.*" was captured as "https://jira" and flagged as a dead link in CI strict mode. Dotted hosts (real URLs) and SKIP_DOMAINS single-label hosts are unaffected, so no link coverage is lost. - 10-cli/README.md: language is Claude's general response/voice-dictation language setting (e.g. french/japanese), which v2.1.176 also wired to session-title generation — not a session-titles-only key. Updated the description and the JSON example value to match the official settings docs. * chore(idd): exempt docs-sync PRs from traceability Closes #N requirement Adds .gitissue.yml so 'docs: sync to Claude Code vX' PRs (which aren't tied to a single tracked issue) are not hard-blocked on a missing Closes #N — they opt in via a 'Type: docs' body line, matching how chore/refactor PRs work. The other three traceability checks still run. --- .gitissue.yml | 14 +++++++++++ 04-subagents/README.md | 7 +++--- 06-hooks/README.md | 45 ++++++++++++++++++++++++++++++++-- 07-plugins/README.md | 6 +++-- 09-advanced-features/README.md | 6 +++-- 10-cli/README.md | 26 ++++++++++++++++++-- CATALOG.md | 10 +++++--- claude_concepts_guide.md | 7 ++++-- scripts/check_links.py | 11 +++++++++ 9 files changed, 116 insertions(+), 16 deletions(-) create mode 100644 .gitissue.yml diff --git a/.gitissue.yml b/.gitissue.yml new file mode 100644 index 0000000..c3ede4d --- /dev/null +++ b/.gitissue.yml @@ -0,0 +1,14 @@ +# gitissue / IDD configuration for claude-howto +# +# This is a documentation/tutorial repo. Doc-sync PRs (e.g. "docs: sync to +# Claude Code vX") are not tied to a single tracked issue, so they are treated +# like chore/refactor PRs for traceability: they do not require a `Closes #N`. +# A PR opts in by including a `Type: docs` (or `Type: chore`/`Type: refactor`) +# line in its body. + +review: + # Add `docs` to the built-in refactor/chore exemption so documentation-sync + # PRs are not hard-blocked on a missing `Closes #N`. The other three + # traceability checks still run. + traceability_exempt_pattern: "^\\s*Type:\\s*(refactor|chore|docs)\\s*$" + traceability_exempt_labels: ["refactor", "chore", "documentation"] diff --git a/04-subagents/README.md b/04-subagents/README.md index 786804b..f79081d 100644 --- a/04-subagents/README.md +++ b/04-subagents/README.md @@ -901,7 +901,7 @@ graph TB ### Key Behaviors -- **No nested spawning** - Subagents cannot spawn other subagents +- **Nested spawning (up to 5 levels)** - As of v2.1.172, subagents can spawn their own subagents, nested up to 5 levels deep. Earlier versions did not allow any nesting. Use the `Agent(agent_type)` restriction syntax (see [Restrict Spawnable Subagents](#restrict-spawnable-subagents)) to control which subagents a given subagent may spawn - **Background permissions** - Background subagents auto-deny any permissions that are not pre-approved - **Backgrounding** - Press `Ctrl+B` to background a currently running task - **Transcripts** - Subagent transcripts are stored at `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl` @@ -1238,11 +1238,12 @@ See the OpenTelemetry section in [Advanced Features → Telemetry](../09-advance --- -**Last Updated**: June 2, 2026 -**Claude Code Version**: 2.1.160 +**Last Updated**: June 15, 2026 +**Claude Code Version**: 2.1.176 **Sources**: - https://code.claude.com/docs/en/sub-agents - https://code.claude.com/docs/en/agent-teams +- https://code.claude.com/docs/en/changelog#2-1-172 - https://github.com/anthropics/claude-code/releases/tag/v2.1.117 - https://github.com/anthropics/claude-code/releases/tag/v2.1.131 - https://github.com/anthropics/claude-code/releases/tag/v2.1.138 diff --git a/06-hooks/README.md b/06-hooks/README.md index 01eaffa..d5684ed 100644 --- a/06-hooks/README.md +++ b/06-hooks/README.md @@ -77,6 +77,45 @@ Hooks are configured in settings files with a specific structure: | `nested_traversal` | Instructions loaded during nested directory traversal | | `path_glob_match` | Instructions loaded via path glob pattern matching | +### Narrowing with `if` conditions (tool-argument paths) + +The `matcher` field selects a hook by **tool name** (`"Write"`, `"Edit|Write"`, `"*"`). To filter more narrowly by the tool's **arguments** — for example, to run a hook only when an edit touches `src/`, or to guard reads of secret files — add an `if` condition to an individual hook handler. This is distinct from the tool-name matcher: the `matcher` decides *which tool*, the `if` decides *which call*. + +`if` uses [permission-rule syntax](https://code.claude.com/docs/en/permissions) (`ToolName(pattern)`), evaluated against the tool name **and** its arguments together. For `Read`/`Edit`/`Write`, the path pattern follows gitignore semantics, with the same anchors as permission rules: a bare name like `.env` matches at any depth, `src/**` is relative to the current directory, `/src/**` to the project root, `~/...` to your home directory, and `//...` is an absolute filesystem path. + +The `if` field sits at the **hook-handler level** — a sibling of `type` and `command`, inside the `hooks` array — not on `matcher`: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Edit|Write", + "hooks": [ + { + "type": "command", + "if": "Edit(src/**)", + "command": "./hooks/lint-src.sh" + } + ] + }, + { + "matcher": "Read", + "hooks": [ + { + "type": "command", + "if": "Read(.env)", + "command": "./hooks/block-secret-read.sh" + } + ] + } + ] + } +} +``` + +Examples of valid `if` patterns: `Edit(src/**)` (edits under `src/`), `Read(~/.ssh/**)` (reads of any SSH key), `Read(.env)` (any `.env` at or below the current directory), `Bash(git push *)` (only `git push` subcommands). + ## Hook Types Claude Code supports five hook types: @@ -1460,11 +1499,13 @@ Edit `~/.claude/settings.json` or `.claude/settings.json` with the hook configur --- -**Last Updated**: June 10, 2026 -**Claude Code Version**: 2.1.170 +**Last Updated**: June 15, 2026 +**Claude Code Version**: 2.1.176 **Sources**: - https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/permissions - https://code.claude.com/docs/en/changelog +- https://code.claude.com/docs/en/changelog#2-1-176 - https://github.com/anthropics/claude-code/releases/tag/v2.1.139 - https://github.com/anthropics/claude-code/releases/tag/v2.1.145 - https://github.com/anthropics/claude-code/releases/tag/v2.1.152 diff --git a/07-plugins/README.md b/07-plugins/README.md index 7bfb8cc..802ebbd 100644 --- a/07-plugins/README.md +++ b/07-plugins/README.md @@ -525,6 +525,7 @@ Example `blockedMarketplaces` with host/path regex (v2.1.119): ### Additional Marketplace Features +- **Marketplace search bar (v2.1.172)**: When browsing a marketplace's plugins in `/plugin`, a search bar lets you filter the marketplace's plugins by name or keyword — handy for large marketplaces where scrolling the full list is slow. - **Default git timeout**: Increased from 30s to 120s for large plugin repositories - **Custom npm registries**: Plugins can specify custom npm registry URLs for dependency resolution - **Version pinning**: Lock plugins to specific versions for reproducible environments @@ -1115,10 +1116,11 @@ The following Claude Code features work together with plugins: --- -**Last Updated**: June 10, 2026 -**Claude Code Version**: 2.1.170 +**Last Updated**: June 15, 2026 +**Claude Code Version**: 2.1.176 **Sources**: - https://code.claude.com/docs/en/plugins +- https://code.claude.com/docs/en/changelog#2-1-172 - https://code.claude.com/docs/en/slash-commands - https://code.claude.com/docs/en/plugin-marketplaces - https://github.com/anthropics/claude-code/releases/tag/v2.1.117 diff --git a/09-advanced-features/README.md b/09-advanced-features/README.md index e2fd9a8..3ae0aba 100644 --- a/09-advanced-features/README.md +++ b/09-advanced-features/README.md @@ -1994,6 +1994,7 @@ Since v2.1.83, administrators can deploy multiple managed settings files into a |---------|-------------| | `disableBypassPermissionsMode` | Prevent users from enabling bypass permissions | | `availableModels` | Restrict which models users can select | +| `enforceAvailableModels` | (v2.1.175) When `true`, the `availableModels` allowlist *also* constrains the **Default** model — if the configured default is not in the list, Claude Code falls back to the first allowed model. User and project settings can no longer widen a managed `availableModels` list. | | `allowedChannelPlugins` | Control which channel plugins are permitted | | `autoMode.environment` | Configure trusted infrastructure for auto mode | | `wslInheritsWindowsSettings` | Windows/WSL only (v2.1.118+): when `true`, Claude Code running inside WSL inherits managed settings from the Windows host, so enterprise policies deployed via Registry/MDM apply uniformly across the Windows and WSL shells | @@ -2327,10 +2328,11 @@ For more information about Claude Code and related features: --- -**Last Updated**: June 10, 2026 -**Claude Code Version**: 2.1.170 +**Last Updated**: June 15, 2026 +**Claude Code Version**: 2.1.176 **Sources**: - https://code.claude.com/docs/en/troubleshooting +- https://code.claude.com/docs/en/changelog#2-1-175 - https://code.claude.com/docs/en/permission-modes - https://code.claude.com/docs/en/interactive-mode - https://code.claude.com/docs/en/settings diff --git a/10-cli/README.md b/10-cli/README.md index f201837..441e478 100644 --- a/10-cli/README.md +++ b/10-cli/README.md @@ -845,6 +845,26 @@ The "ultrathink" keyword in prompts activates deep reasoning. The `/effort` menu --- +## Settings.json Keys + +These keys live in a `settings.json` file (`~/.claude/settings.json` for user scope, `.claude/settings.json` for project scope) rather than being passed as flags or env vars. The table below covers a few recently added UI/UX keys; for the managed `enforceAvailableModels` key, see [Advanced Features → Managed Settings](../09-advanced-features/README.md#available-managed-settings). + +| Key | Description | +|-----|-------------| +| `wheelScrollAccelerationEnabled` | (v2.1.174) Set to `false` to disable mouse-wheel scroll acceleration in the fullscreen renderer. Useful when fast wheel flicks overshoot. | +| `footerLinksRegexes` | (v2.1.176) Array of regexes that render matched links as badges in the footer row. Configurable in user or managed settings. | +| `language` | Sets Claude's preferred response language and voice-dictation language (e.g. `"french"`, `"japanese"`). As of **v2.1.176** it also pins the language used for auto-generated session titles. | + +```json +{ + "wheelScrollAccelerationEnabled": false, + "language": "french", + "footerLinksRegexes": ["https://jira\\.example\\.com/.*"] +} +``` + +--- + ## Quick Reference ### Most Common Commands @@ -947,10 +967,12 @@ claude -p --output-format json "query" --- -**Last Updated**: June 10, 2026 -**Claude Code Version**: 2.1.170 +**Last Updated**: June 15, 2026 +**Claude Code Version**: 2.1.176 **Sources**: - https://code.claude.com/docs/en/cli-reference +- https://code.claude.com/docs/en/changelog#2-1-174 +- https://code.claude.com/docs/en/changelog#2-1-176 - https://code.claude.com/docs/en/settings - https://code.claude.com/docs/en/changelog - https://code.claude.com/docs/en/troubleshooting diff --git a/CATALOG.md b/CATALOG.md index ab395c4..3870bdf 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -82,7 +82,7 @@ Commands are user-invoked shortcuts that execute specific actions. | `/teleport` | Transfer session to another machine | Continue work remotely | | `/desktop` | Open Claude Desktop app | Switch to desktop interface | | `/theme` | Change color theme; v2.1.118 added custom named themes via `~/.claude/themes/.json` (plugins can ship a `themes/` dir) | Customize appearance | -| `/usage` | Canonical command for usage/cost/stats — merged `/cost` and `/stats` into a single tabbed view (v2.1.118); as of v2.1.149 the cost view breaks spending down by category (skills, subagents, plugins, per-MCP-server) | Monitor quota and costs | +| `/usage` | Canonical command for usage/cost/stats — merged `/cost` and `/stats` into a single tabbed view (v2.1.118); as of v2.1.149 the cost view breaks spending down by category (skills, subagents, plugins, per-MCP-server). In the **VSCode extension** (v2.1.174), the `/usage` (Account & usage) dialog adds an attribution breakdown — cache misses, long-context cost, subagents, and per-skill / per-agent / per-plugin / per-MCP usage over 24h and 7d windows | Monitor quota and costs | | `/focus` | Toggle focus view (distraction-free output display) | Reduce visual noise during long tasks | | `/fork` | Fork current conversation | Explore alternatives | | `/stats` | Shortcut alias that opens the stats tab of `/usage` (v2.1.118+) | Review session metrics | @@ -144,6 +144,8 @@ Claude Code supports 6 permission modes that control how tool use is authorized. Specialized AI assistants with isolated contexts for specific tasks. +> **Nested spawning (v2.1.172)**: Subagents can spawn their own subagents, nested up to 5 levels deep. Earlier versions did not allow nesting. See [04-subagents/README.md](04-subagents/README.md#restrict-spawnable-subagents) for the `Agent(agent_type)` syntax that restricts which subagents a given subagent may spawn. + ### Built-in Subagents | Agent | Description | Tools | Model | When to Use | @@ -543,12 +545,14 @@ chmod +x ~/.claude/hooks/*.sh --- -**Last Updated**: June 2, 2026 -**Claude Code Version**: 2.1.160 +**Last Updated**: June 15, 2026 +**Claude Code Version**: 2.1.176 **Sources**: - https://code.claude.com/docs/en/overview - https://code.claude.com/docs/en/commands - https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/changelog#2-1-172 +- https://code.claude.com/docs/en/changelog#2-1-174 - https://github.com/anthropics/claude-code/releases/tag/v2.1.145 - https://github.com/anthropics/claude-code/releases/tag/v2.1.154 - https://code.claude.com/docs/en/plugins diff --git a/claude_concepts_guide.md b/claude_concepts_guide.md index ffc7651..c27aa78 100644 --- a/claude_concepts_guide.md +++ b/claude_concepts_guide.md @@ -217,6 +217,8 @@ sequenceDiagram Subagents are specialized AI assistants with isolated context windows and customized system prompts. They enable delegated task execution while maintaining clean separation of concerns. +As of **v2.1.172**, subagents can spawn their own subagents, nested **up to 5 levels deep** — so the hierarchy is not limited to the single main → subagent layer shown below. Earlier versions did not allow any nesting. + ### Architecture Diagram ```mermaid @@ -3146,12 +3148,13 @@ Claude Code supports the following models with adaptive reasoning effort: - [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) --- -**Last Updated**: June 2, 2026 -**Claude Code Version**: 2.1.160 +**Last Updated**: June 15, 2026 +**Claude Code Version**: 2.1.176 **Sources**: - https://code.claude.com/docs/en/overview - https://code.claude.com/docs/en/hooks - https://code.claude.com/docs/en/model-config +- https://code.claude.com/docs/en/changelog#2-1-172 - https://platform.claude.com/docs/en/about-claude/models/overview - https://www.anthropic.com/news/claude-opus-4-8 - https://github.com/anthropics/claude-code/releases/tag/v2.1.154 diff --git a/scripts/check_links.py b/scripts/check_links.py index 487d623..1e55040 100644 --- a/scripts/check_links.py +++ b/scripts/check_links.py @@ -96,6 +96,17 @@ def main(strict: bool = False) -> int: # Strip trailing Markdown/punctuation characters the regex may over-capture # from link syntax like [text](https://url/) or **https://url)** clean_url = raw_url.rstrip(")>*_`':.,;").split("#")[0] + # Skip bare-hostname partials. URL_RE stops at backslashes, so a + # regex string inside a JSON config example like + # "footerLinksRegexes": ["https://jira\\.example\\.com/.*"] is + # captured as just "https://jira" — a hostname with no dot that is + # not a resolvable URL but a truncated pattern. Real public URLs + # have a dotted host; localhost-style single-label hosts are in + # SKIP_DOMAINS already, so dropping dotless hosts here loses no + # genuine link coverage. + host = clean_url.split("/", 3)[2] if "://" in clean_url else "" + if host and "." not in host.split(":", 1)[0]: + continue urls.setdefault(clean_url, []).append(str(file_path)) if not urls: