claude-dev-env 8.54.0 → 8.54.1

package/hooks/features/README.md

@@ -0,0 +1,32 @@
+# Hook feature map
+
+Open this map before changing, debugging, or adding a hook. Pick the family that owns the behavior, then use its registration and proof command to check the change.
+
+## Where hooks run
+
+- Claude hook registrations live in [`hooks.json`](../hooks.json). The four `ALL_*HOSTED_HOOK_ENTRIES` rosters in [`hooks_constants/`](../hooks_constants/) name scripts run inside dispatchers. The Write and Edit dispatcher also calls `blocking/state_description_blocker.py` directly.
+- Policy lint loads several modules under `hooks/blocking/` through [`adapter_detectors.py`](../../scripts/policy_lint/adapter_detectors.py) and [`adapter_pairing.py`](../../scripts/policy_lint/adapter_pairing.py). A module in that directory is not necessarily a Claude hook.
+- Reinstall pruning comes from `FOLDED_HOOK_RELATIVE_PATHS`, `POST_FOLDED_HOOK_RELATIVE_PATHS`, and `RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS` in [`bin/install.mjs`](../../bin/install.mjs).
+- Git hook entry points and their tests live in [`hooks/git-hooks/`](../git-hooks/).
+
+## Feature entry contract
+
+Each family page starts with a title and an agent-facing behavior summary. Its four sections appear in order. `Checks` names each registered script once, `When it fires` gives the event, matcher, timeout, and hosted tool names, `Proving it` pairs an input with a repository-root command and expected observation, and `Gotchas` records traps near that family.
+
+## Conventions
+
+- Script paths in `Checks` start at `hooks/`. Commands in `Proving it` start at the repository root.
+- The dispatcher is the registration point for each hosted script. Use its roster to check which tool names reach the script.
+- A command that runs pytest uses the named adjacent test file. Read that test before changing the behavior it covers.
+- `hooks/hooks.json` and the four hosted rosters decide membership. The map test checks that every registered script appears once.
+
+## Families
+
+- [Write and Edit blocking](./write-edit-blocking.md) covers the mutation dispatcher, edit advisors, and description gate.
+- [Bash dispatchers](./bash-dispatchers.md) covers command rewriting and the post-call reminder.
+- [Post-write validation](./post-write-validation.md) covers the after-write dispatcher and formatter.
+- [Conduct gates](./conduct-gates.md) covers chat replies, edit markers, step notes, checked claims, and the pull request lifecycle skill.
+- [Session context](./session-context.md) covers skill reminders, startup guidance, and the auto mode denial quick fix.
+- [Spawn routing](./spawn-routing.md) covers spawn readiness, pacing, and model selection.
+- [Observability](./observability.md) covers instruction loads, edited files, and investigation resets.
+- [Lifecycle cleanup](./lifecycle-cleanup.md) covers nested checkouts, worktree setup, and session cleanup.

package/hooks/features/bash-dispatchers.md

@@ -0,0 +1,40 @@
+# Bash dispatchers
+
+This family rewrites a Git Bash command when path conversion would change a revision argument. After shell calls, it can inject a pull request checklist into the agent's context.
+
+## Checks
+
+- `blocking/bash_pre_tool_use_dispatcher.py` combines hosted shell decisions and forwards an updated command when a hosted rewriter allows it.
+- `blocking/msys_rev_path_rewriter.py` adds a narrow `MSYS2_ARG_CONV_EXCL` prefix for affected revision and path tokens.
+- `blocking/headless_claude_broker_gate.py` denies a headless `claude -p` or `claude --print` call and names the broker command to run instead.
+- `blocking/gh_global_account_switch_gate.py` denies `gh auth switch`, `gh auth login`, and `gh auth logout` and names the per-command `GH_TOKEN` form to run instead.
+- `blocking/bash_post_call_dispatcher.py` runs hosted observers and joins their context output without blocking the call.
+- `advisory/pr_done_reminder.py` adds a pull request checklist after a successful push or pull request creation.
+
+## When it fires
+
+- `blocking/bash_pre_tool_use_dispatcher.py` runs on `PreToolUse`, matcher `Bash`, timeout `60` seconds in `hooks.json`.
+- `blocking/msys_rev_path_rewriter.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds. `ALL_BASH_HOSTED_HOOK_ENTRIES` selects the `Bash` tool.
+- `blocking/headless_claude_broker_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
+- `blocking/gh_global_account_switch_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
+- `blocking/bash_post_call_dispatcher.py` runs on `PostToolUse`, matcher `Bash|PowerShell`, timeout `60` seconds in `hooks.json`.
+- `advisory/pr_done_reminder.py` runs inside that dispatcher on `PostToolUse`, matcher `Bash|PowerShell`, timeout `60` seconds. `ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES` selects `Bash` and `PowerShell`.
+
+## Proving it
+
+Preconditions:
+
+- Run each command from the repository root with Python and pytest available. The test fixtures isolate shell payloads.
+
+- **Pre-call dispatch.** Input is a clean Bash command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_bash_pre_tool_use_dispatcher.py -q`. The adjacent test observes the combined decision and hosted precedence.
+- **Revision rewrite.** Input is a Git command with `origin/main:.claude/settings.json`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_msys_rev_path_rewriter.py -q`. The adjacent test observes the `origin/main:` exclusion prefix.
+- **Broker gate.** Input is a `claude -p task` command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_headless_claude_broker_gate.py -q`. The adjacent test observes a denial that names the broker command.
+- **Post-call dispatch.** Input is a Bash call that yields hosted context. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_bash_post_call_dispatcher.py -q`. The adjacent test observes a joined context payload and exit code zero.
+- **Pull request reminder.** Input is a completed push or pull request creation. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_pr_done_reminder.py -q`. The adjacent test checks the reminder trigger and checklist verdict.
+
+## Gotchas
+
+- The pre-call dispatcher stops after a denial. It continues after ask and allow decisions so a later hosted hook can deny.
+- The post-call dispatcher runs every hosted observer and passes only context. Its name avoids a substring collision in `bin/install.test.mjs`.
+- The post-call roster includes `PowerShell`; the reminder script checks both tool names even though its docstring describes Bash calls.
+- `bin/install.mjs` includes folded and retired shell hook paths for registration cleanup.

package/hooks/features/conduct-gates.md

@@ -0,0 +1,45 @@
+# Conduct gates
+
+This family stops a chat reply, edited message, or tool call when its payload breaks a session rule. Each gate gives the agent a reason it can act on.
+
+## Checks
+
+- `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, and requires a readable link when the text names a pull request number.
+- `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
+- `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
+- `blocking/session_title_stop_gate.py` blocks a turn end once when no session title call succeeded in that turn.
+- `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
+- `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
+- `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
+
+## When it fires
+
+- `blocking/reply_length_gate.py` runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message`, timeout `10` seconds in `hooks.json`.
+- `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
+- `blocking/session_title_format_gate.py` runs on `PreToolUse`, matcher `mcp__.*__set_session_title`, timeout `10` seconds in `hooks.json`.
+- `blocking/session_title_stop_gate.py` runs on `Stop`, no matcher, timeout `10` seconds in `hooks.json`.
+- `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
+- `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
+- `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)`, timeout `10` seconds in `hooks.json`.
+
+## Proving it
+
+Preconditions:
+
+- Run each command from the repository root with Python and pytest available. The tests create transcript and payload fixtures.
+
+- **Reply length.** Input is a reply with four sentences or a plain pull request number. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count or link reason.
+- **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
+- **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.
+- **Title at turn end.** Input is a remote session transcript whose last turn set no title. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_stop_gate.py -q`. The adjacent test observes a block; a turn with a successful title call passes.
+- **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
+- **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
+- **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
+
+## Gotchas
+
+- `blocking/step_note_gate.py` is off by default and polls for the transcript record. Subagent calls and unreadable records pass.
+- `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
+- The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.
+- The edit marker gate scans replacement cards as well as the message text.
+- The lifecycle gate counts only invocations after the last compaction, so a compacted session invokes `pr-lifecycle` again. A missing or unreadable transcript allows the call.

package/hooks/features/lifecycle-cleanup.md

@@ -0,0 +1,40 @@
+# Lifecycle cleanup
+
+This family runs nested checkout hooks, refreshes a worktree base, and clears stale session files. Its cleanup paths let the agent start and end a session without leftover hook state.
+
+## Checks
+
+- `lifecycle/nested_project_hooks.py` runs hook registrations from checkouts nested one level below a session directory.
+- `lifecycle/enter_worktree_origin_prefetch.py` fetches the default branch before a fresh worktree is created.
+- `lifecycle/session_end_cleanup.py` removes old context cache files, temporary files, and transcript backups at session end.
+- `session/plugin_data_dir_cleanup.py` removes empty plugin data directories at session start.
+- `session/session_env_cleanup.py` clears the current Windows session environment directory and stale siblings at session start.
+- `session/session_edit_tracker_cleanup.py` clears this session's edit tracker on a fresh start or session end.
+
+## When it fires
+
+- `lifecycle/nested_project_hooks.py` runs on `PreToolUse` matcher `*` at `120` seconds and `SessionStart` matcher empty at `1800` seconds in `hooks.json`.
+- `lifecycle/enter_worktree_origin_prefetch.py` runs on `PreToolUse`, matcher `EnterWorktree`, timeout `25` seconds in `hooks.json`.
+- `lifecycle/session_end_cleanup.py` runs on `SessionEnd`, matcher empty, timeout `3` seconds in `hooks.json`.
+- `session/plugin_data_dir_cleanup.py` and `session/session_env_cleanup.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.
+- `session/session_edit_tracker_cleanup.py` runs on `SessionStart`, matcher empty, timeout `10` seconds and `SessionEnd`, matcher empty, timeout `3` seconds in `hooks.json`.
+
+## Proving it
+
+Preconditions:
+
+- Run each command from the repository root with Python and pytest available. The tests and direct cache probe use disposable directories.
+
+- **Nested checkout hooks.** Input is a session started above a child checkout with its own hooks. Run `python -m pytest packages/claude-dev-env/hooks/lifecycle/test_nested_project_hooks.py -q`. The adjacent test observes the child hook running in its checkout.
+- **Worktree fetch.** Input is an `EnterWorktree` call without a path. Run `python -m pytest packages/claude-dev-env/hooks/lifecycle/test_enter_worktree_origin_prefetch.py -q`. The adjacent test observes a fetch attempt and a zero exit even when a remote is absent.
+- **Session-end cache.** Input is an aged `claude-ctx-` cache file in a disposable directory. Run `python -c 'import os, runpy, tempfile; from pathlib import Path; directory=tempfile.TemporaryDirectory(); root=Path(directory.name); entry=root/"claude-ctx-old.json"; entry.write_text("{}"); os.utime(entry,(0,0)); module=runpy.run_path("packages/claude-dev-env/hooks/lifecycle/session_end_cleanup.py"); module["purge_old_entries"](str(root),7); assert not entry.exists(); directory.cleanup(); print("stale cache entry removed")'`. The command prints `stale cache entry removed`. This script has no adjacent behavior test.
+- **Plugin data cleanup.** Input is an empty plugin data directory. Run `python -m pytest packages/claude-dev-env/hooks/session/test_plugin_data_dir_cleanup.py -q`. The adjacent test observes its removal and preserves directories with files.
+- **Session environment cleanup.** Input is a current Windows session environment directory or an aged sibling. Run `python -m pytest packages/claude-dev-env/hooks/session/test_session_env_cleanup.py -q`. The adjacent test observes removal while recent siblings remain.
+- **Edit tracker cleanup.** Input is a fresh SessionStart or SessionEnd payload. Run `python -m pytest packages/claude-dev-env/hooks/session/test_session_edit_tracker_cleanup.py -q`. The adjacent test observes removal for that session and preservation on resume.
+
+## Gotchas
+
+- The nested checkout runner forwards child denials and asks. It drops child allow decisions so a child cannot widen permission.
+- Worktree prefetch applies to fresh creation and exits zero after a failed fetch.
+- Session-end cleanup has no adjacent behavior test. Its direct probe calls `purge_old_entries` with an isolated directory.
+- The session edit tracker survives a compact or resume. Cleanup targets the current session only.

package/hooks/features/observability.md

@@ -0,0 +1,31 @@
+# Observability
+
+This family records instruction loads and file edits for later checks. Delegation also clears the lead session's investigation timer so the agent can continue its investigation.
+
+## Checks
+
+- `observability/instructions_loaded_logger.py` writes selected instruction-load fields to a JSONL log.
+- `observability/session_file_edit_tracker.py` records edited file paths in a per-session tracker for the stage gate.
+- `workflow/investigation_tracker_reset.py` clears the investigation tracker after delegation.
+
+## When it fires
+
+- `observability/instructions_loaded_logger.py` runs on `InstructionsLoaded`, matcher `session_start|nested_traversal|path_glob_match|include|compact`, timeout `10` seconds in `hooks.json`.
+- `observability/session_file_edit_tracker.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `30` seconds in `hooks.json`.
+- `workflow/investigation_tracker_reset.py` runs on `PostToolUse`, matcher `Agent|Task|TeamCreate`, timeout `30` seconds in `hooks.json`.
+
+## Proving it
+
+Preconditions:
+
+- Run each command from the repository root with Python and pytest available. The tests redirect log and tracker paths to disposable directories.
+
+- **Instruction log.** Input is an `InstructionsLoaded` payload with a file path and load reason. Run `python -m pytest packages/claude-dev-env/hooks/observability/test_instructions_loaded_logger.py -q`. The adjacent test observes one JSONL record with the selected fields.
+- **Edit tracker.** Input is a Write payload with a file path and session ID. Run `python -m pytest packages/claude-dev-env/hooks/observability/test_session_file_edit_tracker.py -q`. The adjacent test observes the resolved path in that session's tracker.
+- **Investigation reset.** Input is a completed Agent, Task, or TeamCreate call. Run `python -m pytest packages/claude-dev-env/hooks/workflow/test_investigation_tracker_reset.py -q`. The adjacent test observes removal of the tracker file.
+
+## Gotchas
+
+- The instruction logger keeps only selected payload fields. It exits zero if logging fails.
+- The edit tracker never blocks a tool call. Its per-session file is read later by the stage gate.
+- The investigation reset applies to delegation tools. Its companion investigation gate lives outside this Claude hook registration map.

package/hooks/features/post-write-validation.md

@@ -0,0 +1,28 @@
+# Post-write validation
+
+This family checks a completed Write or Edit call and formats eligible new source files. The agent receives a combined block decision if a hosted check blocks.
+
+## Checks
+
+- `validation/post_tool_use_dispatcher.py` runs the post-write roster in order and combines any block reasons.
+- `workflow/auto_formatter.py` formats eligible untracked source files after a Write and never blocks the write.
+
+## When it fires
+
+- `validation/post_tool_use_dispatcher.py` runs on `PostToolUse`, matcher `Write|Edit`, timeout `180` seconds in `hooks.json`.
+- `workflow/auto_formatter.py` runs inside that dispatcher on `PostToolUse`, matcher `Write|Edit`, timeout `180` seconds, as named by `ALL_POST_HOSTED_HOOK_ENTRIES`. Its eligibility check accepts only a Write of an untracked source file.
+
+## Proving it
+
+Preconditions:
+
+- Run each command from the repository root with Python and pytest available. The formatter tests make disposable repositories.
+
+- **Post-write dispatch.** Input is an Edit of plain text. Run `python -m pytest packages/claude-dev-env/hooks/validation/test_post_tool_use_dispatcher.py -q`. The adjacent test observes an allow result and the hosted formatter's selection.
+- **Formatter eligibility.** Input is a Write of an untracked source file. Run `python -m pytest packages/claude-dev-env/hooks/workflow/test_auto_formatter.py -q`. The adjacent test observes formatting for eligible writes and no edit of a tracked file.
+
+## Gotchas
+
+- The current post-write roster contains only `workflow/auto_formatter.py`. The dispatcher's docstring mentions other hosted work from an older roster, so use the roster for membership.
+- The formatter can change the file after the original Write. A later hosted script would read the formatted file because the dispatcher preserves roster order.
+- Formatter eligibility protects the hook tree and checks whether the file is tracked.

package/hooks/features/session-context.md

@@ -0,0 +1,40 @@
+# Session context
+
+This family injects reminders and task guidance when an agent starts, resumes, submits a prompt, spawns a helper, or hits an auto mode denial. The startup scripts leave the session quiet when their opt-in conditions fail.
+
+## Checks
+
+- `session/skill_loaded_reminder.py` injects a poteto-mode reminder when the skill needs loading or reloading.
+- `session/task_tool_prompt.py` injects a task tracking directive at session start.
+- `session/working_style_prompt.py` injects the session's working style at session start.
+- `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
+- `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
+- `session/issue_tracker_session_starter.py` injects issue tracker guidance when enabled for a registered repository.
+- `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
+
+## When it fires
+
+- `session/skill_loaded_reminder.py` runs on `PreToolUse` matcher `Agent|Task` at `10` seconds, `UserPromptSubmit` matcher empty at `10` seconds, `SessionStart` matcher `compact` at `10` seconds, and `SubagentStart` matcher `workflow-subagent` at `10` seconds in `hooks.json`.
+- `session/task_tool_prompt.py`, `session/working_style_prompt.py`, `session/advisor_rules_prompt.py`, `session/orchestrator_auto_starter.py`, and `session/issue_tracker_session_starter.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.
+- `advisory/auto_mode_denial_quick_fix.py` runs on `PermissionDenied`, matcher `*`, timeout `10` seconds in `hooks.json`.
+
+## Proving it
+
+Preconditions:
+
+- Run each command from the repository root with Python and pytest available. Enable opt-in flags only inside the tests.
+
+- **Skill reminder.** Input is a helper spawn whose prompt lacks poteto-mode. Run `python -m pytest packages/claude-dev-env/hooks/session/test_skill_loaded_reminder.py -q`. The adjacent test observes the reminder and leaves an already prepared prompt unchanged.
+- **Task tracking.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_task_tool_prompt.py -q`. The adjacent test observes a `SessionStart` context directive that names the task tool.
+- **Working style.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_working_style_prompt.py -q`. The adjacent test observes the fixed context text.
+- **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
+- **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
+- **Issue tracker start.** Input is SessionStart with its opt-in flag and a registered checkout. Run `python -m pytest packages/claude-dev-env/hooks/session/test_issue_tracker_session_starter.py -q`. The adjacent test observes issue tracker context.
+- **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
+
+## Gotchas
+
+- `session/skill_loaded_reminder.py` has four registration points. Its tests cover helper prompt rewriting and repeated prompt suppression.
+- The advisor prompt depends on settings and an environment disable flag. The two starter scripts each use separate opt-in checks.
+- The issue tracker starter requires the checkout to appear in the project path registry.
+- `advisory/auto_mode_denial_quick_fix.py` lives under `advisory/` but belongs here because its only output is agent context and a one-line user message.

package/hooks/features/spawn-routing.md

@@ -0,0 +1,34 @@
+# Spawn routing
+
+This family reminds the agent to gather context before a spawn, adjusts thread requests when usage exceeds pace, and selects an allowed subagent model.
+
+## Checks
+
+- `routing/spawn_readiness_hook.py` adds context to a spawn that comes before a read step, or before an answered question or a settled-scope line. The spawn still runs.
+- `routing/thread_spawn_pace_hook.py` reshapes a thread request when usage is over pace or unreadable.
+- `routing/subagent_model_pin_hook.py` moves every Agent and Task subagent to Opus. A spawn that names Opus or Fable runs unchanged.
+- `routing/subagent_model_routing.mjs` allows a selected Luna model, remaps eligible requests, and denies unsupported model routing.
+
+## When it fires
+
+- `routing/spawn_readiness_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, and `mcp__hearthbot__start_thread_session`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
+- `routing/thread_spawn_pace_hook.py` runs on `PreToolUse`, matcher `mcp__hearthbot__start_thread_session`, timeout `30` seconds in `hooks.json`.
+- `routing/subagent_model_pin_hook.py` runs on `PreToolUse`, matcher `Agent|Task`, timeout `10` seconds in `hooks.json`.
+- `routing/subagent_model_routing.mjs` runs on `PreToolUse`, matcher `multi_agent_v1__spawn_agent`, timeout `10` seconds through the quoted Node command in `hooks.json`.
+
+## Proving it
+
+Preconditions:
+
+- Run each command from the repository root. Python and pytest cover the two Python scripts; Node covers the model router.
+
+- **Spawn readiness.** Input is a spawn after a read, a question, and its answer. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_readiness_hook.py -q`. The adjacent test observes no output for a ready spawn and reminder context for each missing step.
+- **Thread pace.** Input is a thread spawn with usage over pace. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_thread_spawn_pace_hook.py -q`. The adjacent test observes updated tool input with the selected model, effort, and advisor line.
+- **Model pin.** Input is an Agent spawn that names a Sonnet model. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_subagent_model_pin_hook.py -q`. The adjacent test observes updated tool input with model `opus`.
+- **Model routing.** Input is a `multi_agent_v1__spawn_agent` payload with a model choice. Run `node --test packages/claude-dev-env/hooks/routing/subagent_model_routing.test.mjs`. The adjacent test observes an allow or deny decision with the routed model.
+
+## Gotchas
+
+- `routing/spawn_readiness_hook.py` also runs after the pace hook on thread spawns. A reshaped request still gets the readiness check.
+- The readiness hook emits `additionalContext` only, so it never blocks. It passes subagent calls, read-only helper types, a non-object tool input, and unreadable transcripts.
+- The model router allows an advisor flag to bypass the Luna restriction. Its ordinary path denies unresolved or unsupported models.

package/hooks/features/write-edit-blocking.md

@@ -0,0 +1,34 @@
+# Write and Edit blocking
+
+This family decides whether an agent's file mutation can run. It also warns about broad refactors and unsafe migration edits before the agent changes a file.
+
+## Checks
+
+- `blocking/pre_tool_use_dispatcher.py` combines hosted advisory output with its native description check and returns one permission decision.
+- `advisory/refactor_guard.py` warns when an Edit or MultiEdit appears to rename code beyond the current change.
+- `advisory/migration_safety_advisor.py` warns when an Edit or MultiEdit adds an unsafe Django migration operation.
+- `blocking/state_description_blocker.py` rejects historical or comparative prose in supported comments, docstrings, and Markdown.
+
+## When it fires
+
+- `blocking/pre_tool_use_dispatcher.py` runs on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds in `hooks.json`.
+- `advisory/refactor_guard.py` and `advisory/migration_safety_advisor.py` run inside that dispatcher on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. `ALL_HOSTED_HOOK_ENTRIES` selects `Edit` and `MultiEdit` for each.
+- `blocking/state_description_blocker.py` runs through the dispatcher's native evaluator on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. Its evaluator checks `Write`, `Edit`, and `MultiEdit` payloads and skips `apply_patch`.
+
+## Proving it
+
+Preconditions:
+
+- Run each command from the repository root with Python and pytest available. The tests use disposable paths where they need files.
+
+- **Dispatcher decision.** Input is a clean Write payload. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pre_tool_use_dispatcher.py -q`. The adjacent test checks that the dispatcher allows clean writes and carries denials from its checks.
+- **Refactor warning.** Input is a MultiEdit whose second edit renames a function. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_refactor_guard.py -q`. The adjacent test reports both function names in the warning.
+- **Migration warning.** Input is an Edit containing `migrations.RemoveField`. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_migration_safety_advisor.py -q`. The adjacent test observes an allow decision with a migration warning.
+- **Description gate.** Input is a Write containing historical prose in a Python comment. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_state_description_blocker.py -q`. The adjacent test observes a denial reason.
+
+## Gotchas
+
+- `ALL_HOSTED_HOOK_ENTRIES` lists only the two nonblocking advisors. The dispatcher calls the description evaluator through its native hook table.
+- The dispatcher runs hosted entries in roster order. A hosted advisory crash stays silent; a native blocking check can deny the write.
+- `scripts/policy_lint/adapter_detectors.py` also loads `blocking/state_description_blocker.py`. Check that adapter when changing its evaluator.
+- `bin/install.mjs` names folded and retired script paths so reinstall can remove stale registrations.

package/hooks/test_hook_feature_map.py

@@ -0,0 +1,109 @@
+"""Keep the hook feature map aligned with live registrations."""
+
+import json
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent
+if str(HOOKS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIRECTORY))
+
+from hooks_constants.bash_post_call_dispatcher_constants import (
+    ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES,
+)
+from hooks_constants.bash_pre_tool_use_dispatcher_constants import ALL_BASH_HOSTED_HOOK_ENTRIES
+from hooks_constants.post_tool_use_dispatcher_constants import ALL_POST_HOSTED_HOOK_ENTRIES
+from hooks_constants.pre_tool_use_dispatcher_constants import ALL_HOSTED_HOOK_ENTRIES
+
+
+FEATURES_DIRECTORY = HOOKS_DIRECTORY / "features"
+SCRIPT_PATTERN = re.compile(r"\$\{CLAUDE_PLUGIN_ROOT\}/hooks/([^\s\"]+)")
+CHECK_PATTERN = re.compile(r"^- `([^`]+)`", re.MULTILINE)
+FAMILY_LINK_PATTERN = re.compile(r"\]\(\./([a-z0-9-]+\.md)\)")
+SECTION_PATTERN = re.compile(r"^## (.+)$", re.MULTILINE)
+EXPECTED_SECTIONS = ["Checks", "When it fires", "Proving it", "Gotchas"]
+
+
+def registered_hook_commands() -> list[str]:
+    """Return every command string registered in hooks.json."""
+    registrations = json.loads((HOOKS_DIRECTORY / "hooks.json").read_text(encoding="utf-8"))
+    return [
+        hook["command"]
+        for all_groups in registrations["hooks"].values()
+        for group in all_groups
+        for hook in group["hooks"]
+    ]
+
+
+def registered_script_paths() -> set[str]:
+    """Return paths named by the hook registration and hosted rosters."""
+    script_paths = {"blocking/state_description_blocker.py"}
+    for command in registered_hook_commands():
+        matching_paths = SCRIPT_PATTERN.findall(command)
+        assert matching_paths, f"Hook command has no hooks/ script: {command}"
+        script_paths.update(matching_paths)
+
+    for roster in (
+        ALL_HOSTED_HOOK_ENTRIES,
+        ALL_BASH_HOSTED_HOOK_ENTRIES,
+        ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES,
+        ALL_POST_HOSTED_HOOK_ENTRIES,
+    ):
+        script_paths.update(entry.script_relative_path for entry in roster)
+    return script_paths
+
+
+def family_paths() -> list[Path]:
+    """Return the Markdown pages that hold script checks."""
+    return sorted(path for path in FEATURES_DIRECTORY.glob("*.md") if path.name != "README.md")
+
+
+def check_paths(family_path: Path) -> list[str]:
+    """Read script paths from one family's Checks section."""
+    page = family_path.read_text(encoding="utf-8")
+    checks = page.split("## Checks\n", 1)
+    assert len(checks) == 2, f"Missing Checks section in {family_path.name}"
+    checks_section = checks[1].split("\n## ", 1)[0]
+    return CHECK_PATTERN.findall(checks_section)
+
+
+def test_every_registered_hook_appears_once() -> None:
+    mapped_paths = Counter(path for family_path in family_paths() for path in check_paths(family_path))
+    registered_paths = registered_script_paths()
+    for script_path in sorted(registered_paths):
+        assert mapped_paths[script_path] == 1, (
+            f"Registered script {script_path} appears {mapped_paths[script_path]} times in Checks"
+        )
+    for script_path in sorted(mapped_paths):
+        assert script_path in registered_paths, f"Unregistered script {script_path} appears in Checks"
+
+
+def test_every_check_names_an_existing_hook() -> None:
+    hooks_root = HOOKS_DIRECTORY.resolve()
+    for family_path in family_paths():
+        for script_path in check_paths(family_path):
+            candidate = (hooks_root / script_path).resolve()
+            assert candidate.is_relative_to(hooks_root), f"Script escapes hooks/: {script_path}"
+            assert candidate.is_file(), f"Script does not exist under hooks/: {script_path}"
+
+
+def test_readme_lists_every_family_once() -> None:
+    readme = (FEATURES_DIRECTORY / "README.md").read_text(encoding="utf-8")
+    families = readme.split("## Families\n", 1)
+    assert len(families) == 2, "README.md is missing the Families section"
+    listed_names = FAMILY_LINK_PATTERN.findall(families[1])
+    listed_counts = Counter(listed_names)
+    existing_names = {path.name for path in family_paths()}
+    for family_name in sorted(existing_names | set(listed_names)):
+        assert listed_counts[family_name] == 1, (
+            f"Family {family_name} appears {listed_counts[family_name]} times in README.md"
+        )
+        assert family_name in existing_names, f"README.md names missing family {family_name}"
+
+
+def test_every_family_has_four_sections_in_order() -> None:
+    for family_path in family_paths():
+        headings = SECTION_PATTERN.findall(family_path.read_text(encoding="utf-8"))
+        assert headings == EXPECTED_SECTIONS, f"{family_path.name} has sections {headings}"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.54.0",
+    "version": "8.54.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {