Skip to content

A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.

docs: sync to Claude Code v2.1.176 (#141)

Luong NGUYENae656f6fb82e
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/<name>.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: