docs(rules): apply Claude Code changelog review 2.1.76 → 2.1.138

.claude-code-version-check.json

@@ -1,8 +1,45 @@
 {
-  "lastCheckedVersion": "2.1.76",
-  "lastCheckedDate": "2026-03-17",
+  "lastCheckedVersion": "2.1.138",
+  "lastCheckedDate": "2026-05-11",
   "changelogUrl": "https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/CHANGELOG.md",
   "reviewedChanges": [
+    {
+      "version": "2.1.138",
+      "date": "2026-05-11",
+      "relevantChanges": [
+        "New PermissionDenied hook event (2.1.89)",
+        "New TaskCreated hook event (2.1.89)",
+        "New defer decision for PreToolUse via -p --resume (2.1.89)",
+        "PostToolUse updatedToolOutput for ALL tools (2.1.121)",
+        "Hooks receive effort.level in JSON input (2.1.133)",
+        "Skills reference CLAUDE_EFFORT (2.1.120)",
+        "PreCompact can block compaction (2.1.105)",
+        "duration_ms in PostToolUse inputs (2.1.119)",
+        "UserPromptSubmit can set sessionTitle (2.1.94)",
+        "permissions.deny overrides ask decision (2.1.101)",
+        "Agent frontmatter hooks fire via --agent (2.1.116)",
+        "Agent frontmatter mcpServers loaded via --agent (2.1.117)",
+        "Subagents discover skills via Skill tool (2.1.133)",
+        "worktree.baseRef controls EnterWorktree base (2.1.133)",
+        "EnterWorktree gained path parameter (2.1.105)",
+        "Plugins ship executables under bin/ (2.1.91)",
+        "Plugin manifest experimental wrapper (2.1.129)",
+        "autoMode.hard_deny added (2.1.136)",
+        "CLAUDE_CODE_SESSION_ID in Bash subprocess (2.1.132)",
+        "sandbox.network.deniedDomains added (2.1.113)",
+        "Fixed PermissionRequest updatedInput (2.1.110)",
+        "Fixed plugin hooks on cache cleanup (2.1.136)",
+        "BREAKING: skills entry fix (2.1.136)"
+      ],
+      "actionsRequired": [
+        "Updated hooks-reference.md",
+        "Updated skill-development.md",
+        "Updated agent-development.md",
+        "Updated plugin-structure.md",
+        "Updated agentic-permissions.md",
+        "Updated sandbox-guidance.md"
+      ]
+    },
     {
       "version": "2.1.76",
       "date": "2026-03-17",

.claude/rules/agent-development.md

@@ -106,6 +106,7 @@ tools: Agent(worker, researcher), Read, Bash
 ```
 
 This is an allowlist — only `worker` and `researcher` can be spawned. To allow any subagent without restriction, use `Agent` without parentheses. If `Agent` is omitted, the agent cannot spawn any subagents.
+> **Note (2.1.116+)**: Agent frontmatter `hooks:` and `mcpServers:` are active when the agent runs as a main-thread session via `claude --agent`, not just as subagents.
 
 ## Model Selection for Agents
 
@@ -169,6 +170,17 @@ For filesystem-level isolation, give agents their own git worktree so they work
 | `isolation: worktree` | Git worktree | Filesystem + Git | Implementation, commits |
 | Manual worktree | `git worktree add` | Filesystem + Git | Complex multi-issue parallel work |
 
+### `worktree.baseRef` Setting (2.1.133+)
+
+Controls the branch base for `--worktree`, `EnterWorktree`, and agent-isolation worktrees:
+
+| Value | Base Branch | Notes |
+|-------|-------------|-------|
+| `fresh` (default) | `origin/default-branch` | Unpushed local commits NOT included |
+| `head` | Local `HEAD` | Includes unpushed commits; pre-2.1.133 default |
+
+Set `worktree.baseRef: head` to keep unpushed commits in new worktrees.
+
 ## Preloading Skills into Agents
 
 Use the `skills` field to inject full skill content into an agent's context at startup. Unlike the main session where skill descriptions are loaded and full content loads on invocation, preloaded skills are fully injected immediately.
@@ -185,6 +197,7 @@ Implement API endpoints. Follow the conventions and patterns from the preloaded
 ```
 
 Agents do **not** inherit skills from the parent session — they must be listed explicitly.
+> **Note (2.1.133+)**: Subagents can discover project, user, and plugin skills via the `Skill` tool. Skills listed in `skills:` frontmatter are preloaded; the `Skill` tool discovers others on demand.
 
 ---
 
@@ -510,3 +523,5 @@ See `git-repo-agent/docs/adr/004` for full context.
 - `.claude/rules/agentic-permissions.md` — Granular tool permission patterns
 - `.claude/rules/skill-development.md` — Skill creation (use when agent is not needed)
 - `.claude/rules/agentic-optimization.md` — CLI output optimization for agent consumption
+
+

.claude/rules/agentic-permissions.md

@@ -234,6 +234,21 @@ For projects using plugins with these patterns, recommend adding to `.claude/set
 ```
 
 These narrow rules carry over into auto mode and skip the classifier. Avoid broad patterns like `Bash(*)` or `Bash(python*)` — auto mode drops them at runtime, and they reduce safety in `default`/`acceptEdits`.
+### `autoMode.hard_deny` (2.1.136+)
+
+Rules in `autoMode.hard_deny` block unconditionally -- the classifier cannot override them regardless of user intent or allow exceptions:
+
+```json
+{
+  "permissions": {
+    "autoMode": {
+      "hard_deny": ["Bash(rm -rf *)"]
+    }
+  }
+}
+```
+
+Use `hard_deny` for security-critical operations that must never run in auto mode even when the user explicitly permits them. Contrast with `autoMode.soft_deny`, which the classifier can override for good reason.
 
 ## Context Section Patterns
 
@@ -275,3 +290,5 @@ Use `find` for file/directory discovery (succeeds with empty output when no matc
 - [ ] Context commands use `find` for file/directory discovery
 - [ ] Only necessary permissions are granted
 - [ ] Matches a standard permission set or documents why custom set is needed
+
+

.claude/rules/hooks-reference.md

@@ -154,7 +154,8 @@ Set timeout explicitly even though the default is now 10 minutes — explicit ti
   "transcript_path": "/path/to/conversation.json",
   "cwd": "/current/working/directory",
   "permission_mode": "default",
-  "hook_event_name": "PreToolUse"
+  "hook_event_name": "PreToolUse",
+  "effort": {"level": "high"}
 }
 ```
 
@@ -166,7 +167,8 @@ Set timeout explicitly even though the default is now 10 minutes — explicit ti
   "tool_input": {
     "command": "npm test"
   },
-  "tool_response": { }
+  "tool_response": { },
+  "duration_ms": 1234
 }
 ```
 `tool_response` is only present for `PostToolUse` and `PostToolUseFailure`.
@@ -349,7 +351,20 @@ Optionally modify the tool input before execution:
 }
 ```
 
-### PermissionRequest — Auto Approve/Deny (2.1.50+)
+### PostToolUse -- Replace Tool Output (2.1.121+)
+
+`PostToolUse` hooks can replace tool output for any tool via `hookSpecificOutput.updatedToolOutput`:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "updatedToolOutput": "Filtered or modified tool output"
+  }
+}
+```
+
+### PermissionRequest -- Auto Approve/Deny (2.1.50+)
 
 ```json
 {
@@ -849,3 +864,4 @@ MCP tools use the naming pattern `mcp__<server>__<tool>`. Match them with regex
 | `ElicitationResult` | MCP | 2.1.76 |
 | `Notification` | Misc | |
 | `ConfigChange` | Misc | 2.1.50 |
+

.claude/rules/plugin-structure.md

@@ -20,6 +20,7 @@ plugin-name/
 │   └── skill-name/
 │       └── SKILL.md         # Skills (user-invocable and auto-discovered)
 ├── agents/                   # Agent definitions (optional)
+├── bin/                       # Compiled binaries or executables (optional)
 ├── README.md                 # Plugin documentation
 └── CHANGELOG.md              # Auto-generated by release-please
 ```
@@ -59,10 +60,16 @@ plugin-name/
   "agents": ["./agents", "./specialized-agents"],
   "hooks": "./config/hooks.json",
   "mcpServers": "./.mcp.json",
-  "lspServers": { ... }
+  "lspServers": { ... },
+  "experimental": {
+    "themes": ["./themes"],
+    "monitors": ["./monitors"]
+  }
 }
 ```
 
+> **Note (2.1.136+)**: Adding a `skills` entry in `plugin.json` no longer hides the default `skills/` directory. Previously, specifying `skills` would hide auto-discovery of the default path.
+
 ## Field Validation Rules
 
 | Field | Rule |
@@ -151,3 +158,5 @@ By default, Claude discovers components in standard directories. Override with e
 Versions are managed automatically by release-please. Use conventional commits to trigger version bumps.
 
 See `.claude/rules/release-please.md` for details.
+
+

.claude/rules/sandbox-guidance.md

@@ -64,6 +64,21 @@ The web sandbox enforces a **"Limited" network allowlist**. Skills must only dow
 Network access mode is configured in the Claude Code web UI settings — not via code. If a skill requires access beyond the "Limited" allowlist, document this requirement explicitly and instruct users to enable "Full" network access in their web session settings.
 
 ---
+### Denied Domains
+
+`sandbox.network.deniedDomains` blocks specific domains even when a broader allowedDomains wildcard permits them (2.1.113+):
+
+```json
+{
+  "sandbox": {
+    "network": {
+      "deniedDomains": ["evil.example.com", "*.tracking.io"]
+    }
+  }
+}
+```
+
+Use to carve out exceptions from broad allow wildcards without restricting other traffic.
 
 ## Filesystem
 
@@ -128,6 +143,7 @@ The web sandbox base image includes standard language runtimes and system tools
 | `CLAUDE_PROJECT_DIR` | Always | Project root directory |
 | `CLAUDE_PLUGIN_ROOT` | Frontmatter hooks only | Root of the loaded plugin |
 | `CLAUDE_CODE_DISABLE_CRON` | Set to stop scheduled cron jobs mid-session (2.1.72+) | Session cron management |
+| `CLAUDE_CODE_SESSION_ID` | Always | Session ID matching hook `session_id` -- available in Bash tool subprocesses (2.1.132+) |
 
 ### Persisting Environment Variables
 
@@ -314,3 +330,6 @@ pypi.org
 - `.claude/rules/hooks-reference.md` — complete hook event reference and `CLAUDE_CODE_REMOTE` definition
 - `.claude/rules/shell-scripting.md` — safe shell patterns for hook scripts
 - `.claude/rules/skill-development.md` — skill creation patterns
+
+
+

.claude/rules/skill-development.md

@@ -97,6 +97,7 @@ Skills support these dynamic variables in content:
 | `$N` | Shorthand for `$ARGUMENTS[N]` (e.g., `$0` first, `$1` second) |
 | `${CLAUDE_SESSION_ID}` | Current session ID — useful for logging and session-specific files |
 | `${CLAUDE_SKILL_DIR}` | Directory containing the skill's `SKILL.md` file — use for bundled scripts |
+| `${CLAUDE_EFFORT}` | Current effort level (`low`, `medium`, `high`, `max`) — use for effort-aware behavior |
 | `${CLAUDE_PLUGIN_ROOT}` | Root of the loaded plugin (hooks only) |
 
 **Examples:**
@@ -291,3 +292,5 @@ git commit -m "docs(blueprint-plugin): update skill README"
 | `chore` | Metadata updates (plugin.json, marketplace.json) |
 
 PR titles must also follow this format — they become the squash-merge commit message that drives release-please version bumps.
+
+