release: v3.1.0 — domain knowledge sync + ask permissions

Watch-upstream pass against code.claude.com/docs (covers v2.1.70-2.1.109).

Domain rules:
- hook-architecture.md: 27 → 31 events, 3 lifecycle cadences,
  +InstructionsLoaded/Elicitation/PreCompact-blockable
- hook-events.md: PreCompact blockability, MCP elicitation
- permission-model.md: enterprise managed settings (managed-settings.d/,
  allowManagedHooksOnly, allowedChannelPlugins) + dynamic permissions API
  (addRules/replaceRules/setMode/addDirectories from hook output)
- model-ids.md: default effort medium → high (v2.1.94)

Template:
- settings.json.tmpl: +ask: list (18 entries) for risky-but-legitimate
  commands (rm, chmod, npm/pip install, docker, k8s, gcloud/aws/terraform,
  git push/rebase)
- block-destructive.sh: verified safe vs compound-bash bypass class fixed
  in v2.1.98 (uses grep -qiE over full command — catches `ls && rm -rf /`
  by design). Documented known limits + sandbox.enabled defense-in-depth.

Practices: 8 accepted (inbox → active), 3 rejected (auto-stubs).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: luiseiman

.claude/rules/domain/hook-architecture.md

@@ -2,22 +2,25 @@
 globs: "**/*.sh,**/settings.json,**/settings.json.partial"
 description: "Hook system design patterns and safety requirements"
 domain: claude-code-engineering
-last_verified: 2026-04-07
+last_verified: 2026-04-15
 ---
 
 # Hook Architecture
 
-## Events (27 total, verified v2.1.92)
-
-Core: SessionStart, SessionEnd, Stop, StopFailure
-Tool lifecycle: PreToolUse, PostToolUse, PostToolUseFailure
-User: UserPromptSubmit
-Permissions: PermissionRequest, PermissionDenied
-Elicitation: Elicitation, ElicitationResult
-Agent: SubagentStart, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted
-Context: PreCompact, PostCompact, CwdChanged, FileChanged, InstructionsLoaded
-System: ConfigChange, Notification
-Worktree: WorktreeCreate, WorktreeRemove
+## Events (31 total, verified v2.1.108 — code.claude.com/docs/en/hooks)
+
+Three lifecycle cadences:
+
+**Session-level** (once per session): SessionStart, SessionEnd, InstructionsLoaded
+**Turn-level** (once per user prompt): UserPromptSubmit, Stop, StopFailure
+**Tool-loop** (every tool call): PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied
+**Async/side**: Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, TeammateIdle, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult
+
+`InstructionsLoaded` fires when CLAUDE.md or `.claude/rules/*.md` loads. `load_reason` field: `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact`. Observability-only — no decision control.
+
+`PreCompact` is **blockable** since v2.1.105 (exit 2 prevents compaction). Was non-blocking before.
+
+`Elicitation`/`ElicitationResult` fire during MCP tool execution when an MCP server requests structured user input. Support `accept`/`decline`/`cancel` actions and field overrides.
 
 ## Exit codes, types, and decisions
 

.claude/rules/domain/hook-events.md

@@ -2,7 +2,7 @@
 globs: "**/*.sh,**/settings.json"
 description: "Hook event payloads and per-event behavior details"
 domain: claude-code-engineering
-last_verified: 2026-04-07
+last_verified: 2026-04-15
 ---
 
 # Hook Event Details
@@ -11,10 +11,11 @@ last_verified: 2026-04-07
 
 - PostCompact command: `trigger` ("auto"/"manual") + `compact_summary` (full text)
 - PostCompact SDK: `compactType` + `messageCountBefore` + `messageCountAfter`
-- PreCompact: `compactType` + `messageCount` — NON-BLOCKING, exit code ignored
+- PreCompact: `compactType` + `messageCount` — **BLOCKABLE since v2.1.105** (exit 2 prevents compaction)
 - SessionStart `source`: "startup", "resume", "compact", "clear"
 - CwdChanged: fires on directory change, supports CLAUDE_ENV_FILE
 - FileChanged: fires on external file modification — use for auto-reload
+- InstructionsLoaded: fires when CLAUDE.md or `.claude/rules/*.md` loads. `load_reason`: `session_start` | `nested_traversal` | `path_glob_match` | `include` | `compact`. Observability-only, no decision control.
 
 ## Tool events
 
@@ -33,3 +34,9 @@ last_verified: 2026-04-07
 
 - SubagentStart: inject additionalContext into spawned subagent via stdout
 - TeammateIdle: fires when a team member has no pending work
+
+## MCP elicitation events (v2.1.76+)
+
+- Elicitation: fires when an MCP server requests structured user input mid-tool-call. Hook can return `action: "accept" | "decline" | "cancel"` and override field values via `content: {field: "new_value"}`
+- ElicitationResult: fires after the user (or hook) responds. Observability + audit
+- Combined with `disableSkillShellExecution` and managed settings, lets enterprises pre-validate MCP form submissions before they reach the server

.claude/rules/domain/model-ids.md

@@ -2,7 +2,7 @@
 globs: "**/agents/*.md,**/CLAUDE.md"
 description: "Model IDs and agent defaults for Claude Code subagent instantiation"
 domain: claude-code
-last_verified: 2026-04-05
+last_verified: 2026-04-15
 ---
 
 # Model IDs (April 2026)
@@ -15,5 +15,14 @@ last_verified: 2026-04-05
 
 Default agents: opus → architect, security-auditor. sonnet → implementer, code-reviewer, session-reviewer. haiku → researcher, test-runner.
 
+## Default effort (changed v2.1.94, 2026-04-07)
+
+Global default is now `effort: high` (was `medium`). Implication:
+
+- Skills/agents WITHOUT explicit `effort:` consume more tokens and run slower
+- Pin `effort: low` in `agents/researcher.md` and `agents/test-runner.md` to keep them cheap
+- Benchmark baselines computed before 2026-04-07 are no longer comparable
+- For deterministic transformations (rename, reformat) explicit `effort: low` is recommended
+
 > Claude 3 Haiku deprecated — retiring April 19, 2026. Use claude-haiku-4-5 only.
 > Update this table when Anthropic releases new model versions.

.claude/rules/domain/permission-model.md

@@ -2,7 +2,7 @@
 globs: "**/settings.json,**/settings.local.json,**/settings.json.partial"
 description: "Permission modes, evaluation cascade, deny list requirements"
 domain: claude-code-engineering
-last_verified: 2026-04-05
+last_verified: 2026-04-15
 ---
 
 # Permission Model
@@ -32,6 +32,38 @@ last_verified: 2026-04-05
 
 Managed (enterprise) > Local (.claude/settings.local.json) > Project (.claude/settings.json) > Global (~/.claude/settings.json)
 
+## Enterprise managed settings (v2.1.83+)
+
+- `managed-settings.d/` drop-in directory: every `*.json` inside merges with the main `managed-settings.json`. Lets ops ship modular policy files.
+- `allowManagedHooksOnly: true` — blocks ALL user/project/plugin hooks. Only managed-scope hooks (and hooks from plugins force-enabled by managed settings) run. Under this policy `.claude/hooks/` is inert at runtime — audit scoring should reflect runtime applicability, not file presence.
+- `allowedChannelPlugins` — restricts which plugins activate via `--channels`.
+- `forceRemoteSettingsRefresh` — fail-closed: blocks startup until remote settings fetched (v2.1.92).
+
+## Dynamic permissions from hooks (v2.1.84+)
+
+`PreToolUse` and `PermissionRequest` hooks can mutate runtime permission state via JSON output:
+
+```json
+{
+  "hookSpecificOutput": {
+    "decision": {
+      "behavior": "allow|deny",
+      "updatedInput": { "...": "..." },
+      "updatedPermissions": [
+        { "type": "addRules",          "rules": ["Bash(make *)"] },
+        { "type": "replaceRules",      "rules": ["..."] },
+        { "type": "removeRules",       "rules": ["..."] },
+        { "type": "setMode",           "mode": "auto|default|plan|acceptEdits" },
+        { "type": "addDirectories",    "directories": ["/tmp/build"] },
+        { "type": "removeDirectories", "directories": ["..."] }
+      ]
+    }
+  }
+}
+```
+
+Use cases: a behavior self-elevates its allowlist for a session, a safety hook downgrades to `plan` mode after detecting risk, or a build hook whitelists a temporary directory. Static deny rules still enforce — a hook cannot remove a managed deny.
+
 ## Bash prefix detection
 
 - Separate LLM call (fast model) extracts command prefixes

VERSION

@@ -1 +1 @@
-3.0.4
+3.1.0

docs/changelog.md

@@ -4,6 +4,29 @@
 >
 > Historial de versiones. Las entradas usan español/inglés mixto según la evolución del proyecto. Los términos técnicos son universales.
 
+## v3.1.0 (2026-04-15)
+
+### Domain knowledge sync — Claude Code v2.1.108
+
+Watch-upstream pass against `code.claude.com/docs` (covers v2.1.70 → v2.1.109). Eight practices accepted, three rejected (auto-stubs).
+
+#### Domain rule updates
+
+- `domain/hook-architecture.md` — events count corrected 27 → **31**, restructured around three lifecycle cadences (session-level, turn-level, tool-loop, async/side). Added `InstructionsLoaded` (with `load_reason` field), `Elicitation`/`ElicitationResult`, and `PreCompact` blockability since v2.1.105.
+- `domain/hook-events.md` — `PreCompact` flagged as blockable, `InstructionsLoaded` payload documented, new MCP elicitation events section.
+- `domain/permission-model.md` — new sections: **Enterprise managed settings** (`managed-settings.d/`, `allowManagedHooksOnly`, `allowedChannelPlugins`, `forceRemoteSettingsRefresh`) and **Dynamic permissions from hooks** (`addRules`/`replaceRules`/`removeRules`/`setMode`/`addDirectories`/`removeDirectories` via `hookSpecificOutput.decision.updatedPermissions`).
+- `domain/model-ids.md` — documented v2.1.94 default effort change `medium → high`. Recommends pinning `effort: low` on `researcher`/`test-runner` agents.
+
+#### Template
+
+- `template/settings.json.tmpl` — added `ask:` permission list (18 entries) covering risky-but-legitimate commands: `rm *`, `chmod *`, `npm/pip install/uninstall`, `docker run`, `kubectl apply/delete`, `gcloud`/`aws`/`terraform apply/destroy`, `git push/rebase/cherry-pick`. Bridges the gap between unrestricted `allow:` and total `deny:`.
+- `template/hooks/block-destructive.sh` — added compound-bash safety verification block. Hook is **not vulnerable** to the v2.1.98 bypass class (the Claude Code core fix was about its own permission rule prefix matching; this hook uses `grep -qiE` over the full command string and catches `ls && rm -rf /`-style compound forms by design). Documented known limitations: indirect execution (`eval $(curl)`, `bash <(curl)`), encoded payloads, hostile env vars — defense-in-depth via `sandbox.enabled`.
+
+#### Practices
+
+- 8 practices moved `inbox/ → active/`, frontmatter `incorporated_in: [v3.1.0]`.
+- 3 auto-stub session-changes practices rejected (no actionable content).
+
 ## v3.0.4 (2026-04-14)
 
 ### Skills catalog — `skills/index.yaml` + CI validation

…ox/2026-04-13-boris-cherny-tips-scout.md …ve/2026-04-13-boris-cherny-tips-scout.mdpractices/inbox/2026-04-13-boris-cherny-tips-scout.md renamed to practices/active/2026-04-13-boris-cherny-tips-scout.md practices/inbox/2026-04-13-boris-cherny-tips-scout.md renamed to practices/active/2026-04-13-boris-cherny-tips-scout.md

@@ -1,11 +1,11 @@
 ---
 id: boris-cherny-tips-scout
 source: scout:shanraisshan/claude-code-best-practice/tips
-status: inbox
+status: active
 captured: 2026-04-13
 tags: [scout, boris-cherny, workflow, gaps]
 tested_in: []
-incorporated_in: []
+incorporated_in: [v3.1.0]
 ---
 
 # Boris Cherny tips — scout digest

…x/2026-04-13-granular-ask-permissions.md …e/2026-04-13-granular-ask-permissions.mdpractices/inbox/2026-04-13-granular-ask-permissions.md renamed to practices/active/2026-04-13-granular-ask-permissions.md practices/inbox/2026-04-13-granular-ask-permissions.md renamed to practices/active/2026-04-13-granular-ask-permissions.md

@@ -1,11 +1,11 @@
 ---
 id: granular-ask-permissions
 source: scout:shanraisshan/claude-code-best-practice
-status: inbox
+status: active
 captured: 2026-04-13
 tags: [permissions, settings, safety, template]
 tested_in: []
-incorporated_in: []
+incorporated_in: [v3.1.0]
 ---
 
 # Granular `ask:` permission list for template settings

…-13-v3-clear-creates-session-boundary.md …-13-v3-clear-creates-session-boundary.mdpractices/inbox/2026-04-13-v3-clear-creates-session-boundary.md renamed to practices/active/2026-04-13-v3-clear-creates-session-boundary.md practices/inbox/2026-04-13-v3-clear-creates-session-boundary.md renamed to practices/active/2026-04-13-v3-clear-creates-session-boundary.md

@@ -4,10 +4,10 @@ title: "/clear creates a new session_id, abandoning all session-scoped behavior
 source: "dotforge v3 Phase 1 live smoke test in ~/tmp-v3-live"
 source_type: experience
 discovered: 2026-04-13
-status: inbox
+status: active
 tags: [v3, behavior-governance, session-lifecycle, runtime, audit-gap]
 tested_in: tmp-v3-live
-incorporated_in: []
+incorporated_in: [v3.1.0]
 replaced_by: null
 ---
 

practices/active/2026-04-15-block-destructive-compound-bash.md

@@ -0,0 +1,46 @@
+---
+id: block-destructive-compound-bash
+source: watch:code.claude.com/docs/en/changelog
+status: active
+captured: 2026-04-15
+tags: [security, hooks, block-destructive, audit, high-priority]
+tested_in: []
+incorporated_in: [v3.1.0]
+---
+
+# Audit block-destructive.sh against compound-bash bypass (CVE-class fix in v2.1.98)
+
+## Observation
+
+Changelog v2.1.98 (2026-04-09) explicitly mentions:
+> Fixed Bash tool permission bypass vulnerability
+> Fixed compound Bash commands bypassing permission prompts
+
+This means before v2.1.98, commands like `ls && rm -rf /tmp/foo` or
+`echo ok; rm -rf *` could slip past pattern-based hooks that only matched the
+first token. The Claude Code core was patched, but **dotforge's
+`template/hooks/block-destructive.sh`** uses its own pattern matching and may
+have the same blind spot.
+
+## Required verification
+
+1. Read `template/hooks/block-destructive.sh`
+2. Confirm it matches destructive patterns ANYWHERE in the command string,
+   not just at the start
+3. Test cases that MUST be blocked:
+   - `ls && rm -rf /`
+   - `echo ok; rm -rf *`
+   - `cd /tmp && git push --force origin main`
+   - `(cd / && DROP TABLE users)`
+   - `true || rm -rf $HOME`
+4. If any pass, harden the regex / split on `&&`, `||`, `;`, `|`, `\``, `$()`
+
+## Action
+
+After verification:
+- If hook is already safe → document it in a comment block in the script
+- If gap found → patch + add tests under `tests/hooks/` + bump dotforge version
+
+## Affected files
+- `template/hooks/block-destructive.sh` (and any stack-specific copies)
+- Possibly `tests/hooks/block-destructive.test.sh` (new)