navori 0.6.0 → 0.6.1

package/dist/assets/core/core-assets/agents/auditor.md

@@ -35,7 +35,7 @@ If there's a recent audit of the same scope and the code hasn't changed, read it
 ## Protocol
 
 ### 1. Startup
-Read `CLAUDE.md` (project rules + the orchestrator block) and the `user-section` below. Set the scope: **targeted** (1 file/feature/module) or **full** (all of `src/`).
+`CLAUDE.md` (project rules + the orchestrator block) is already in your context when your host injects it — read it from disk ONLY if your host did not inject it. Read the `user-section` below. Set the scope: **targeted** (1 file/feature/module) or **full** (all of `src/`).
 
 ### 2. Context gathering
 Explore **yourself** — you are a subagent and cannot launch others (`Agent` does not nest). For broad scope: `Glob` the structure, `Grep` the risk patterns, and read in full only the candidate files. Don't read generated/lock artifacts or library `ui`.

package/dist/assets/core/core-assets/agents/commit-pr-pilot.md

@@ -186,10 +186,22 @@ Never open the PR with the gate red.
 
 If the repo defines its own template (`.github/pull_request_template.md`), read it and match its structure instead of the default.
 
+### Always-on delta — a number in the body, never a gate
+
+Whatever template you follow: when the shipping diff changes the **always-on layer** — the harness context every session pays for up front, i.e. the rendered `CLAUDE.md` — the body states its byte delta, measured against the same base as the PR diff:
+
+```bash
+git show origin/{{prTarget}}:CLAUDE.md 2>/dev/null | wc -c   # before (0 if the file is new)
+wc -c CLAUDE.md                                  # after
+```
+
+- **It is a number, never a gate.** Nothing blocks on it and no automatic limit judges it: a non-deterministic check wired into the gate only teaches everyone to ignore the gate. A ceiling, if the repo wants one, belongs in an explicit deterministic cap of its own — not in this line and not in the PR flow.
+- **Growth is not a veto.** State the delta AND its counterpart: what those bytes buy — payload they remove from every session, a duplicated block they retire, a failure mode they close. Bytes added up front to save a multiple of them per session is a good trade; the point is that the trade is on the record, not that the number stays small. A delta reported without its counterpart is half the measurement.
+- Silent when the diff leaves that file alone. A "Δ 0" bullet is noise, not rigor.
+
 ## Hard rules
 
 - ❌ Never push with `--force` to `{{branchBase}}` or another protected branch.
-- ❌ Never commit `.claude/` or `CLAUDE.md` (gitignored by convention).
 - ❌ Never skip hooks (`--no-verify`) unless the user explicitly asks.
 - ❌ Never ask for a merge / approve the PR yourself. Your job ends with the URL.
 - ❌ Never `gh pr checks --watch`: it takes no timeout and would hang the turn before the URL reaches the user.

package/dist/assets/core/core-assets/agents/explorer.md

@@ -23,7 +23,7 @@ If the question is specific ("where is X?"), it's not you — it's `researcher`.
 
 ## Protocol
 
-1. Read `CLAUDE.md` to understand the repo's conventions.
+1. `CLAUDE.md` carries the repo's conventions — it is already in your context when your host injects it; read it from disk ONLY if your host did not inject it.
 2. Define the scope: a folder, a logical module, a file pattern. The orchestrator should hand it to you precisely; if it arrives ambiguous, return `blocked` naming the options (folder X / module Y / pattern Z) so it re-sends it scoped — don't guess.
 3. Walk from the entry points (routes, module root exports, `index.ts`) toward the leaves. For each level, list files and their brief role. Apply `.claude/skills/structural-search/SKILL.md` to locate shapes and entry points without reading whole files.
 4. Identify reverse dependencies: which external modules consume this module? That indicates the "blast radius" of changing something here.

package/dist/assets/core/core-assets/agents/implementer.md

@@ -12,7 +12,7 @@ You execute **a single** task from start to verification. You don't orchestrate,
 
 ## Protocol
 
-1. **Read** `CLAUDE.md`. Identify the repo's conventions and the "Project rules" (the orchestrator's section in `CLAUDE.md`). Then read whatever prior artifact your scope names — `.claude/progress/audit_ticket_<ID>.md`, `solution_<scope>.md`, `explore_*.md`: that context was already paid for in tokens, and a solution artifact means the approach is DECIDED. You implement it; you don't redesign it. If you believe the design is wrong, say so in your report and stop — don't quietly build something else.
+1. **Ground yourself in** `CLAUDE.md` — it is already in your context when your host injects it; identify the repo's conventions and the "Project rules" (the orchestrator's section) from there, and read it from disk ONLY if your host did not inject it (e.g. an engine without automatic injection). Then read whatever prior artifact your scope names — `.claude/progress/audit_ticket_<ID>.md`, `solution_<scope>.md`, `explore_*.md`: that context was already paid for in tokens, and a solution artifact means the approach is DECIDED. You implement it; you don't redesign it. If you believe the design is wrong, say so in your report and stop — don't quietly build something else.
 2. **Note** in `.claude/progress/impl_<feature>.md` (your working file; on close it becomes the report):
    - `Task: <brief description>`
    - `Root cause: <file:line + why>` (only if the task is a bugfix; you can't touch code without this).

package/dist/assets/core/core-assets/agents/leader.md

@@ -14,7 +14,7 @@ Your only job as orchestrator is to **decompose and coordinate**, never to imple
 
 ## Startup protocol
 
-1. Read `CLAUDE.md` (stack, conventions, quality gate).
+1. `CLAUDE.md` (stack, conventions, quality gate) is already in your context when your host injects it; read it from disk ONLY if your host did not inject it (e.g. an engine without automatic injection).
 2. The catalog of subagents and skills is in `CLAUDE.md` (`## Available agents`, `## Available skills`).
 3. Read `progress/current.md` (repo root) if it exists — the previous session's state.
 4. Identify the task's scope against the "Project rules" below (legacy paths, critical areas, repo conventions).
@@ -96,6 +96,7 @@ Expected files:
 - `.claude/progress/plan_<scope>.md` — the `auditor`'s prioritized plan that accompanies a deep audit
 - `.claude/progress/explore_<topic>.md` — broad map (`explorer`)
 - `.claude/progress/research_<question>.md` — scoped question (`researcher`)
+- `.claude/progress/solution_<scope>.md` — the design pass's decision record (`solution-design` skill), plus `solution_review_<scope>.md` for its fresh-context challenge (`researcher`)
 - `.claude/progress/impl_<feature>.md` — the `implementer`'s report (includes its `Status: DONE | BLOCKED`)
 - `.claude/progress/review_<feature>.md` — the `reviewer`'s verdict
 - `.claude/progress/receipt.txt` — the `reviewer`'s content receipt on `APPROVED` (binds the diff to the reviewed bytes; consumed by `commit-pr-pilot`)

package/dist/assets/core/core-assets/agents/researcher.md

@@ -34,7 +34,7 @@ hypothetical future abstractions or optional edge cases as BLOCKER.
 
 ## Protocol
 
-1. Read `CLAUDE.md` to understand the repo's context.
+1. `CLAUDE.md` carries the repo's context — it is already in your context when your host injects it; read it from disk ONLY if your host did not inject it.
 2. Work on ONE scoped question (the orchestrator already handed you the scope). If you discover it's actually >2 independent questions, return them as a list so the orchestrator distributes them across parallel researchers — don't chain them in series yourself.
 3. Run the search:
    - Primary method: the native `Grep` (content) and `Glob` (files by name/pattern) tools. They're read-only, fast (ripgrep), and don't ask for permission.

package/dist/assets/core/core-assets/agents/reviewer.md

@@ -14,7 +14,7 @@ You are a strict reviewer. Your only function is to **approve or reject**. You d
 
 ### Setup (common to both passes)
 
-1. Read `CLAUDE.md`, `.claude/progress/impl_<feature>.md`, `.claude/progress/audit_ticket_<ID>.md` and `.claude/progress/solution_<scope>.md` (whichever exist). When there IS a solution artifact, the diff is judged against the approach it records — an implementation that quietly took a different path is a `SPEC_MISS`, even if the code is good. You do NOT re-open the design itself: whether that approach was the right one was settled in its own phase; your question is whether the code did what was agreed.
+1. Ground yourself in `CLAUDE.md` — already in your context when your host injects it; read it from disk ONLY if your host did not inject it. Then read `.claude/progress/impl_<feature>.md`, `.claude/progress/audit_ticket_<ID>.md` and `.claude/progress/solution_<scope>.md` (whichever exist). When there IS a solution artifact, the diff is judged against the approach it records — an implementation that quietly took a different path is a `SPEC_MISS`, even if the code is good. You do NOT re-open the design itself: whether that approach was the right one was settled in its own phase; your question is whether the code did what was agreed.
 2. Identify modified files. Diff against `{{prTarget}}` (the PR's target
    branch), **not** against the fork point: it's the EXACT diff GitHub will show and
    the one commit-pr-pilot reviews. `{{branchBase}}` and `{{prTarget}}` are usually

package/dist/assets/core/core-assets/agents/ticket-audit.md

@@ -14,7 +14,7 @@ Your first job is NOT to plan the implementation — it is to establish **what t
 
 ## When to trigger
 
-- Bug in a critical feature (auth, RBAC, payments, data integrity, areas listed in `{{project.criticalAreas}}`).
+- Bug in a critical feature (`{{project.criticalAreas}}`).
 - Before a structural migration (legacy → new backend, monolith → microservices, etc.).
 - New feature that crosses >3 layers (service → adapter → component → store).
 - Bug described in natural language with no clear hint of where to look.
@@ -41,9 +41,11 @@ ls .claude/progress/audit_ticket_*.md 2>/dev/null
 
 If you find a recent audit for the same ticket, read it first. Don't re-audit if the context hasn't changed.
 
+**Scoped to ONE area?** When the orchestrator fans the intake's phase 2 out (the fan-out row of the orchestration table's signal→mechanism lookup), your encargo names ONE area: audit that area only, write `audit_ticket_<ID-area>.md` — e.g. `audit_ticket_BTBS-138-webapp.md` — so parallel auditors never overwrite one file, and issue the verdict FOR YOUR AREA. Don't reconcile it with the sibling areas: that synthesis is the orchestrator's, and its result is what lands in `audit_ticket_<ID>.md`.
+
 ## Flow
 
-1. **Read**: `CLAUDE.md` (project rules + the orchestrator's role).
+1. **Ground**: `CLAUDE.md` (project rules + the orchestrator's role) — already in your context when your host injects it; read it from disk ONLY if your host did not inject it.
 2. **Curate repo context** for your analysis:
    - Literal text of the ticket (don't paraphrase).
    - Grep for the ticket's keywords → candidate files.
@@ -141,6 +143,8 @@ One line:
 done -> .claude/progress/audit_ticket_<ID>.md
 ```
 
+(`audit_ticket_<ID-area>.md` when your scope was one area of a fan-out.)
+
 The leader reads the audit from disk and decomposes from there.
 
 <!-- navori:user-section -->

package/dist/assets/core/core-assets/hooks/_partials/extract-cmd.sh

@@ -3,19 +3,31 @@
 # of truth for the sibling gate scripts; DO NOT copy this body back into a hook
 # by hand (that is the drift #225/#261 removed).
 #
-# PreToolUse(Bash) passes the tool input on stdin. Extract .tool_input.command
+# PreToolUse(Bash) passes the tool input on stdin. Read one field out of it
 # WITHOUT hard-depending on jq (NOT preinstalled on macOS): try jq, then node
-# (Claude Code's own runtime), then a best-effort sed unwrap. No command
-# extracted → empty $cmd, and each caller decides what that means (the gate
-# scripts scan defensively; guard-destructive waves the command through).
+# (Claude Code's own runtime), then a best-effort sed unwrap on the leaf key.
+# Nothing extracted → empty output, and each caller decides what that means (the
+# gate scripts scan defensively; guard-destructive waves the command through).
+#
+# $1 is a dotted path written HERE, never user input — the payload is the data.
+# Generic on purpose: `.cwd` feeds the worktree resolver of #454 through the
+# SAME hardened cascade instead of a second copy of it.
+#
+# $2 overrides the sed fallback's capture. `.*` (greedy, to the last quote on the
+# line) is right for `command`, whose value can itself contain escaped quotes and
+# which Claude Code sends LAST. Every other field takes the default `[^"]*` run,
+# so a value with more JSON after it is not swallowed whole.
 payload=$(cat)
-extract_cmd() {
+payload_field() {
   if command -v jq >/dev/null 2>&1; then
-    printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null && return 0
+    printf '%s' "$payload" | jq -r ".$1 // empty" 2>/dev/null && return 0
   fi
   if command -v node >/dev/null 2>&1; then
-    printf '%s' "$payload" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{try{process.stdout.write(String(JSON.parse(s)?.tool_input?.command??""))}catch{}})' 2>/dev/null && return 0
+    printf '%s' "$payload" | node -e 'let s="";const p=process.argv[1].split(".");process.stdin.on("data",c=>s+=c).on("end",()=>{try{let v=JSON.parse(s);for(const k of p)v=v?.[k];process.stdout.write(String(v??""))}catch{}})' "$1" 2>/dev/null && return 0
   fi
-  printf '%s' "$payload" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\(.*\)".*/\1/p'
+  printf '%s' "$payload" | sed -n "s/.*\"${1##*.}\"[[:space:]]*:[[:space:]]*\"\(${2:-[^\"]*}\)\".*/\1/p"
+}
+extract_cmd() {
+  payload_field tool_input.command '.*'
 }
 cmd=$(extract_cmd)

package/dist/assets/core/core-assets/hooks/_partials/gate-trigger.sh

@@ -15,15 +15,20 @@
 # does NOT trigger it. Known limitation: it cannot see through `sh -c`, `eval`,
 # or obfuscation — a seatbelt, not a sandbox.
 is_scan_trigger() {
-  local input="$1" segment
+  # Pre-expanded newline: zsh does NOT expand $'\n' in the REPLACEMENT of
+  # ${var//pat/repl} (it inserts the literal characters), so an inline $'\n'
+  # left compound commands unsplit there and the gate silently skipped
+  # `cd x && git commit` (#391). A plain variable expands identically in
+  # bash and zsh. ($'\n' in PATTERN position expands fine in both.)
+  local input="$1" segment nl=$'\n'
   # FIX B: join `\<newline>` continuations into a space FIRST, so a command
   # split across lines with a trailing backslash stays ONE logical segment
   # (otherwise the subcommand/flag lands in a segment not starting with git).
   input="${input//\\$'\n'/ }"
-  input="${input//&&/$'\n'}"
-  input="${input//||/$'\n'}"
-  input="${input//;/$'\n'}"
-  input="${input//|/$'\n'}"
+  input="${input//&&/$nl}"
+  input="${input//||/$nl}"
+  input="${input//;/$nl}"
+  input="${input//|/$nl}"
   # `<<<` feeds the already-expanded value as data — no re-evaluation — so a
   # command that contains backticks/$() is inspected, never executed.
   while IFS= read -r segment; do

package/dist/assets/core/core-assets/hooks/_partials/resolve-worktree.sh

@@ -0,0 +1,150 @@
+# Shared worktree resolver — inlined into each gate hook at render time (see the
+# include directive in the source scripts + lib/hook-includes.ts). Requires the
+# `extract-cmd` partial to have run first ($payload and $cmd in scope).
+#
+# WHY (#454): settings.json invokes these hooks as
+# `bash "$CLAUDE_PROJECT_DIR/.claude/scripts/check-semgrep.sh"`, so the hook
+# PROCESS starts in the MAIN repo even when the commit happens inside an agent
+# worktree under `.claude/worktrees/`. The old `cd "$(git rev-parse
+# --show-toplevel)"` therefore resolved the main repo — whose tree is clean — so
+# `git diff --name-only main` returned 0 files and the gate exited 0. Not a false
+# negative from the scanner: the scanner never ran. A `cd` to an arbitrary tree
+# is exactly the bug, so nothing below ever guesses: every candidate must prove
+# it is a git working tree, or the next one is tried — and the one the COMMAND
+# names must additionally prove it is part of the repository being protected
+# (see the same-repository constraint in `navori_worktree`).
+#
+# `navori_worktree` prints the absolute root of the working tree the gated git
+# command will act on, or nothing when none resolves. It is a FUNCTION, not a
+# top-level assignment, because `quality-gate-pre-commit` inlines this partial on
+# a path that runs on EVERY Bash tool call: callers pay the git/jq probes only
+# after their own trigger matched.
+
+# First shell token of $1: a leading single/double-quoted string (so a path with
+# spaces survives) or an unquoted run of non-space characters.
+navori_first_token() {
+  local s="$1"
+  case "$s" in
+    \"*) s="${s#\"}"; printf '%s' "${s%%\"*}" ;;
+    \'*) s="${s#\'}"; printf '%s' "${s%%\'*}" ;;
+    *) printf '%s' "${s%%[[:space:]]*}" ;;
+  esac
+}
+
+# Directory named by the command itself, if any. Two shapes, both real in this
+# harness: `git -C <dir> commit …` (git names its own tree) and
+# `cd <dir> && git commit …` (how an agent commits into its worktree from a
+# session anchored elsewhere). Prints the raw token; the caller resolves it.
+#
+# TODO(scope): only the FIRST segment is inspected for `cd`. A `cd` buried
+# mid-chain (`pnpm build && cd sub && git commit`) falls through to the payload
+# cwd, which is right whenever that `cd` stays inside the same repo. Walk the
+# segments if a real command shows up where it does not.
+navori_cmd_dir() {
+  local text="$1" rest="" head=""
+  case "$text" in
+    *"git -C "*)
+      rest="${text#*git -C }"
+      ;;
+    *)
+      head="${text%%&&*}"
+      head="${head#"${head%%[![:space:]]*}"}"
+      case "$head" in
+        "cd "*) rest="${head#cd }" ;;
+      esac
+      ;;
+  esac
+  [ -n "$rest" ] || return 1
+  rest="${rest#"${rest%%[![:space:]]*}"}"
+  # A token that needs the shell to expand it ($VAR, `sub`, ~, globs) is NOT
+  # resolved here: guessing wrong points the scan at the wrong tree, which is
+  # the very failure this partial exists to kill. Ignoring it just falls through
+  # to the next candidate.
+  case "$rest" in
+    ""|*'$'*|*'`'*|*'*'*|*'?'*|"~"*) return 1 ;;
+  esac
+  navori_first_token "$rest"
+}
+
+# Absolute, symlink-resolved path of a working tree's SHARED git dir, or nothing
+# when $1 is not inside a git working tree. `--git-common-dir` names the `.git`
+# of the MAIN checkout, so every linked worktree of one repository — and every
+# subdirectory of it — reports the SAME value, while a different repository
+# reports its own and a submodule reports `<main>/.git/modules/<name>`. That
+# makes it an identity test for "same repository", which `--show-toplevel` (one
+# per working tree) and `--git-dir` (one per worktree) are not.
+navori_repo_id() {
+  local dir="$1" common=""
+  common=$(git -C "$dir" rev-parse --git-common-dir 2>/dev/null) || return 1
+  [ -n "$common" ] || return 1
+  # `git -C <dir>` chdirs to <dir> first, so a relative answer (`.git`,
+  # `../../.git`) is relative to <dir>. `pwd -P` canonicalises both sides the
+  # same way, which also settles macOS's /var vs /private/var symlink.
+  (cd "$dir" && cd "$common" && pwd -P) 2>/dev/null
+}
+
+# First argument that resolves to a git working tree; prints its root.
+navori_first_tree() {
+  local candidate toplevel
+  for candidate in "$@"; do
+    [ -n "$candidate" ] || continue
+    [ -d "$candidate" ] || continue
+    toplevel=$(git -C "$candidate" rev-parse --show-toplevel 2>/dev/null) || continue
+    [ -n "$toplevel" ] || continue
+    printf '%s' "$toplevel"
+    return 0
+  done
+  return 1
+}
+
+# Resolution, most specific first:
+#   1. the directory the command names (`git -C` / a leading `cd`), ONLY when it
+#      belongs to the same repository as the anchor (see the constraint below);
+#   2. the payload's `.cwd` — Claude Code sends the CURRENT working directory of
+#      the tool call, a documented field distinct from $CLAUDE_PROJECT_DIR (the
+#      project root). In an agent worktree these differ; that gap IS #454;
+#   3. the hook process's own cwd — the pre-#454 behaviour, still correct for a
+#      plain terminal or git-hook invocation.
+navori_worktree() {
+  local payload_cwd anchor named anchor_repo="" named_repo=""
+  payload_cwd=$(payload_field cwd)
+  # A relative `cd sub` resolves against the shell's cwd, which is the payload's
+  # when Claude Code sends one and the hook process's otherwise.
+  anchor="$payload_cwd"
+  [ -d "$anchor" ] || anchor="$PWD"
+  named=$(navori_cmd_dir "$cmd" || true)
+  case "$named" in
+    "") ;;
+    /*) ;;
+    *) named="$anchor/$named" ;;
+  esac
+  # SAME-REPOSITORY CONSTRAINT — DO NOT REMOVE (#454, review finding).
+  # Candidate 1 is the only one the COMMAND controls, and it is tried first, so
+  # accepting any git tree it happens to name lets that command OVERRIDE the
+  # trustworthy candidates below it: `git -C <other-repo> log && git commit`,
+  # `cd <other> && cd <wt> && git commit`, `cd <sub> && cd .. && git commit`, or
+  # merely the bytes `git -C <path>` inside a commit MESSAGE, all aimed the scan
+  # at a foreign tree with nothing to scan — exit 0 with the scanner never run,
+  # which is the very failure #454 is about (and, for a commit in the main repo,
+  # strictly worse than not resolving worktrees at all).
+  # So a directory the command names is accepted only when it is part of the
+  # repository the hook is protecting, i.e. the anchor's. Linked worktrees share
+  # the main checkout's git dir, so every legitimate agent worktree passes; a
+  # different repository and a submodule (its own git dir under
+  # `<main>/.git/modules/`) do not, and fall through to the payload cwd — the
+  # stricter direction. An unresolvable anchor drops candidate 1 for the same
+  # reason: nothing to check it against.
+  # Ceiling: two linked worktrees of the SAME repository are indistinguishable
+  # this way, so naming a sibling worktree still beats the payload cwd. Both are
+  # trees of the repo being protected, so the scan stays inside it. Walk the
+  # segments to the one that actually carries the `git commit` if a real command
+  # shows up where that is not enough.
+  if [ -n "$named" ]; then
+    anchor_repo=$(navori_repo_id "$anchor" || true)
+    named_repo=$(navori_repo_id "$named" || true)
+    if [ -z "$anchor_repo" ] || [ "$named_repo" != "$anchor_repo" ]; then
+      named=""
+    fi
+  fi
+  navori_first_tree "$named" "$payload_cwd" "$PWD" || true
+}

package/dist/assets/core/core-assets/hooks/guard-destructive.sh

@@ -8,7 +8,9 @@
 # devices. Exit 2 in a PreToolUse hook is evaluated BEFORE permission rules, so
 # this is the strongest line of defense — it overrides even an `allow` match.
 #
-# KNOWN, ACCEPTED LIMITATION: matching is regex-based over the command string.
+# KNOWN, ACCEPTED LIMITATION: matching is regex-based over the command string —
+# over the part of it the shell will actually INTERPRET, since #462 (see "INERT
+# CONTENT" below: a heredoc body or a `-m`/`--body` value is data, not a call).
 # A compound command is split into one segment per line first, so each rule only
 # ever matches WITHIN a segment (see "SEGMENTS" below) — that is what keeps a
 # `git commit` in one segment from being paired with a flag in another.
@@ -42,6 +44,221 @@ block() {
   exit 2
 }
 
+# Pre-expanded newline, shared by the inert-content pass and the segment split.
+# zsh does NOT expand $'\n' in the REPLACEMENT of ${var//pat/repl} (it inserts
+# the literal characters), so an inline $'\n' left compound commands unsplit
+# there and the rules below fail-open (#391). A plain variable expands
+# identically in bash and zsh.
+_nl=$'\n'
+
+# INERT CONTENT (#462) — what the shell EXECUTES vs what it merely WRITES.
+#
+# Every rule below reads the command as TEXT, so a PR body or a commit message
+# that QUOTES a destructive command was blocked even though nothing ran. That
+# fires on every security change, because documenting a fix means quoting the
+# attack it defends against: #403 could not write its own PR body, and a commit
+# message naming a recursive delete of HOME needed the `git commit -F <file>`
+# detour.
+#
+# `live` is `$cmd` minus its INERT spans — the text the shell hands to a program
+# as DATA and never interprets as a command. `$cmd` stays intact for the
+# messages; the rules read `live` (directly, or through `scan`).
+#
+# INERT (dropped before matching):
+#   · a heredoc BODY — `cat > body.md <<'EOF' … EOF` is file content.
+#   · the quoted VALUE of a message/body flag (`-m`, `--body`, …) — it lands in
+#     a commit object or in a PR, the shell never runs it.
+#
+# NOT inert. This is the line the decision draws — stated as the FRONTIER it
+# actually is, denylist included, because an unstated denylist reads as coverage:
+#   · a heredoc whose opener names a SCRIPT path (`cat > run.sh <<'EOF'`) — that
+#     is step 1 of write-then-execute, not documentation. The extension list is
+#     matched case-INSENSITIVELY; an unlisted or absent extension (`Makefile`,
+#     `.mk`, `.lua`, `.awk`, `cat > /tmp/payload`) reads as documentation, and
+#     only the execution tell below can still catch it.
+#   · ANY command that also EXECUTES something. Precisely: a KNOWN interpreter
+#     (`_hd_run`) in COMMAND POSITION — optionally behind `VAR=v` and the simple
+#     prefixes of `_hd_pre` WITH their arguments (`sudo -u me`, `env FOO=1`,
+#     `timeout 5`), and behind the wrappers the tell normalizes away (`(…)`,
+#     `{ …; }`, `\bash`, `"bash"`, `command bash`) —, or a path in command
+#     position (`./x`, `/x`, `~/x`), or a `$(…)`/backtick substitution the shell
+#     would expand (`git commit -m "$(rm -rf ~)"` really does run it). Such a
+#     command is scanned WHOLE, exactly as before #462.
+#     ANY OTHER RUNNER ESCAPES, and that is the accepted trade, not an oversight:
+#     `npx tsx f`, `lua f`, `make -f f`, `find … -exec bash {} \;`, a runner
+#     reached through a shell function or an alias, and one named by a BRACED
+#     variable (`${SH} f` — the wrapper normalization collapses `{` to a space,
+#     so it reaches the tell as `$ SH`; the plain `$SHELL f` IS caught). A word
+#     split by escapes (`b\ash f`) escapes too, as it already does the rules in
+#     the pre-#462 guard. A denylist is never complete;
+#     widening it is cheap per entry, but each entry ALSO drags a legitimate
+#     `… && make build` sitting next to a prose heredoc back into a full scan —
+#     back into the exact false positive #462 exists to kill. Same class as the
+#     `sh -c` / `eval` limitation the header states: a seatbelt, not a sandbox.
+#   · a `<<` that merely sits inside a string (`echo "a << b"`) — it opens no
+#     heredoc, so it can never be used to swallow the next real command. A line
+#     whose quotes do not pair up (`echo "a \" << EOF"`) counts as a NON-opener
+#     for the same reason: inventing a heredoc there would elide the real
+#     commands that follow, the one way this pass could scan LESS than before.
+# Unchanged scope: a deliberate adversary (`sh -c`, `eval`, base64) already had
+# simpler doors and is still out of reach. This is a seatbelt, not a sandbox.
+_hd_q='@navoriQ@'   # marks a QUOTED heredoc delimiter (`<<'EOF'`: no expansion)
+skeleton=""
+_hd_delim=""
+_hd_inert=0
+_hd_expand=0
+while IFS= read -r _line; do
+  if [ -n "$_hd_delim" ]; then
+    # Inside a heredoc body. The terminator is compared whitespace-trimmed (a
+    # `<<-` terminator may be indented); trimming can only end the body EARLIER
+    # than the shell would, i.e. scan more, never less.
+    _t="${_line#"${_line%%[![:space:]]*}"}"
+    _t="${_t%"${_t##*[![:space:]]}"}"
+    if [ "$_t" = "$_hd_delim" ]; then
+      _hd_delim=""
+      continue
+    fi
+    if [ "$_hd_inert" = 0 ]; then
+      skeleton="${skeleton}${_line}${_nl}"
+      continue
+    fi
+    # An UNQUOTED delimiter (`<<EOF`) still runs `$(…)`/backticks inside the
+    # body — plain prose there is inert, a substitution is a real invocation.
+    # Keeping exactly those lines feeds the whole-command fallback below.
+    if [ "$_hd_expand" = 1 ]; then
+      case "$_line" in
+        *'$('* | *'`'*) skeleton="${skeleton}${_line}${_nl}" ;;
+      esac
+    fi
+    continue
+  fi
+  skeleton="${skeleton}${_line}${_nl}"
+  # Fast path: no `<<`, no heredoc — a PreToolUse hook runs on EVERY Bash call,
+  # so the sed probes below are worth paying only on the lines that can open one.
+  case "$_line" in
+    *'<<'*) ;;
+    *) continue ;;
+  esac
+  # Heredoc opener? The probe marks the DELIMITER's own quotes first, then drops
+  # every other quoted span, so `cat <<'EOF'` is told apart from a `<<` inside a
+  # string; `<<<` (here-string) is neutralized so it can't pose as `<<`.
+  _probe=$(printf '%s' "$_line" | sed -E \
+    -e "s/<<(-?)[[:space:]]*'([A-Za-z_][A-Za-z0-9_]*)'/<<\1${_hd_q}\2/g" \
+    -e "s/<<(-?)[[:space:]]*\"([A-Za-z_][A-Za-z0-9_]*)\"/<<\1${_hd_q}\2/g" \
+    -e "s/<<(-?)[[:space:]]*\\\\([A-Za-z_][A-Za-z0-9_]*)/<<\1${_hd_q}\2/g" \
+    -e "s/'[^']*'//g" -e "s/\"[^\"]*\"//g" -e "s/<<</ /g")
+  # A quote left over in the probe means those two `sed` passes paired the quotes
+  # somewhere the shell would not (an escaped `\"`, an odd count): the `<<` may
+  # well sit inside a string, and INVENTING a heredoc here is the one failure
+  # mode of this whole pass that scans LESS — it would elide every following line,
+  # real commands included (`echo "a \" << EOF"` + a real `rm -rf ~/`). Treat the
+  # line as a NON-opener; worst case the body is scanned, which is what the guard
+  # did before #462.
+  case "$_probe" in
+    *'"'* | *"'"*) continue ;;
+  esac
+  # `^[^<]*` anchors on the FIRST `<` of the line: no match (a `<` redirect
+  # before the heredoc) simply leaves the body under the rules.
+  _open=$(printf '%s' "$_probe" \
+    | sed -nE "s/^[^<]*(<<-?[[:space:]]*(${_hd_q})?[A-Za-z_][A-Za-z0-9_]*).*/\1/p")
+  if [ -z "$_open" ]; then continue; fi
+  _hd_delim=$(printf '%s' "$_open" | sed -E "s/^<<-?[[:space:]]*(${_hd_q})?//")
+  _hd_inert=1
+  _hd_expand=0
+  case "$_open" in
+    *"${_hd_q}"*) ;;
+    *) _hd_expand=1 ;;
+  esac
+  # Writing a SCRIPT is not documenting: keep `cat > run.sh <<'EOF'` visible.
+  # Case-INSENSITIVE (`-i`): macOS ships a case-insensitive filesystem, so
+  # `cat > /tmp/p.SH` writes and runs the same file as `p.sh`.
+  if printf '%s' "$_line" \
+    | grep -qiE "\.(sh|bash|zsh|ksh|fish|py|rb|pl|js|jsx|mjs|cjs|ts|tsx|command|bat|ps1|scpt)([[:space:]]|[\"'\`]|\$)"; then
+    _hd_inert=0
+  fi
+done <<< "$cmd"
+
+# A `$(…)`/backtick substitution outside single quotes RUNS: `git commit -m
+# "$(rm -rf ~)"` is an invocation wearing a message's clothes. This check must
+# read the skeleton BEFORE the flag values are elided below — eliding first
+# swallowed the `$(` and let exactly that command through.
+#
+# TWO probes, OR'd, because neither alone is enough:
+#   · single-quoted spans dropped — catches a `$(` sitting outside every quote.
+#   · the double-quoted spans ALONE — inside them an apostrophe is LITERAL, so
+#     the first probe pairs `it's … it's` as if it were a quoted span and deletes
+#     the `$(` between them. That is ordinary punctuation in the very messages
+#     #462 exists to allow (`-m "it's fine $(rm -rf / ) it's"`), and it disarmed
+#     the only check that catches an invocation disguised as a message.
+# Over-reading here only falls back to scanning the whole command, i.e. to the
+# pre-#462 behaviour: the safe side.
+_hd_whole=0
+if printf '%s' "$skeleton" | sed -E "s/'[^']*'//g" | grep -qE '\$\(|`'; then
+  _hd_whole=1
+else
+  # Fast path, same idea as the `<<` one above: probe 2 costs two processes on
+  # EVERY Bash call, and it can only ever fire when a substitution is present
+  # somewhere in the first place.
+  case "$skeleton" in
+    *'$('* | *'`'*)
+      if printf '%s' "$skeleton" | grep -oE '"[^"]*"' | grep -qE '\$\(|`'; then
+        _hd_whole=1
+      fi
+      ;;
+  esac
+fi
+
+# Message/body flag VALUES. The flag itself stays so rule 1 still sees the shape
+# of the invocation (`git commit -m "" --no-verify` is still a skip-flag), and
+# `--body-file` is untouched: `([[:space:]]+|=)` can't match its `-`.
+_hd_flags='-m|--message|--body|--title|--description|--notes'
+skeleton=$(printf '%s' "$skeleton" | sed -E \
+  -e "s/(^|[[:space:]])(${_hd_flags})([[:space:]]+|=)'[^']*'/\1\2 ''/g" \
+  -e "s/(^|[[:space:]])(${_hd_flags})([[:space:]]+|=)\"[^\"]*\"/\1\2 \"\"/g")
+
+# The elision holds ONLY while nothing in the command can run what was written.
+# A segment that STARTS with an interpreter or with a path is an execution, and
+# reverts to the whole command — which is why `cat > x <<'EOF' … EOF; bash x` is
+# still blocked. Anything else keeps only what the shell will interpret.
+#
+# `_hd_pre` — the runner may sit behind simple prefixes, WITH their own arguments:
+# `sudo -u me bash x`, `env FOO=1 bash x`, `timeout 5 bash x`. Matching only a
+# prefix glued to the interpreter turned every one of those into a free pass.
+_hd_pre='(sudo|doas|env|command|nohup|timeout|time|nice|ionice|stdbuf|setsid)'
+_hd_pre="${_hd_pre}([[:space:]]+(-[^[:space:]]+([[:space:]]+[^-[:space:]][^[:space:]]*)?"
+_hd_pre="${_hd_pre}|[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*|[0-9][^[:space:]]*))*[[:space:]]+"
+_hd_run='bash|sh|zsh|ksh|dash|ash|fish|tcsh|csh|source|eval|exec|xargs'
+_hd_run="${_hd_run}|python[0-9.]*|node|deno|bun|perl|ruby|osascript"
+_hd_exec='(^|[;&|])[[:space:]]*([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*'
+_hd_exec="${_hd_exec}(${_hd_pre})*"
+# `\$[A-Za-z_]` covers a runner named by a plain VARIABLE (`$SHELL x`). The
+# BRACED form (`${SH} x`) is NOT covered and is one of the declared escapes: the
+# same wrapper normalization that puts `{ bash x; }` back in command position
+# collapses `{` to a space, so `${SH}` reaches the tell as `$ SH`. Catching it
+# would mean teaching that normalization about `$`-prefixed braces — a change to
+# a security-sensitive transform, worth its own unit.
+# Why catching the plain form is safe: a variable in command position is never a
+# legitimate WRITER, so the false-positive cost is ~0 and the declared frontier
+# stays complete — which is what the denylist trade-off rests on (#462).
+_hd_exec="${_hd_exec}((${_hd_run})([[:space:]]|\$)|\.[[:space:]]|[.~]?/|\\\$[A-Za-z_])"
+# The tell reads a NORMALIZED copy, never the raw skeleton: `_hd_exec` anchors on
+# `^`/`;&|`, so any wrapper between the boundary and the interpreter used to hide
+# it. The transforms are FIX C's (below) plus quote REMOVAL, which is what puts
+# `(bash x)`, `{ bash x; }`, `\bash x`, `"bash" x` and `command bash x` back in
+# command position. Unquoting is safe HERE and not below: its only effect is
+# deciding whether to fall back to the whole command, i.e. to the pre-#462
+# behaviour — it never reaches the rules, so a quoted skip-flag is untouched.
+if [ "$_hd_whole" = 1 ] || printf '%s' "$skeleton" | sed -E \
+  -e "s/(^|[;&|]|[[:space:]])command[[:space:]]+/\1/g" \
+  -e "s/\\\\([A-Za-z])/ \1/g" \
+  -e "s/[(){}]/ /g" \
+  -e "s/'([^']*)'/\1/g" \
+  -e 's/"([^"]*)"/\1/g' | grep -qE "$_hd_exec"; then
+  live="$cmd"
+else
+  live="$skeleton"
+fi
+
 # Normalized copy used ONLY by the rules below. `$cmd` stays intact for the
 # messages. The transforms only add boundaries / drop noise, so they always push
 # toward MORE blocking:
@@ -53,7 +270,7 @@ block() {
 #           `\git …` and `(git …)` read as a plain `git …`.
 # `scan` keeps quoted spans intact, so a quoted skip-flag (`git commit
 # "--no-verify"`) is still caught — stripping the quotes there was a real bypass.
-scan="$cmd"
+scan="$live"
 scan="${scan//\\$'\n'/ }"     # FIX B: join line continuations
 scan="${scan//$'\n'/;}"       # FIX B: flatten remaining newlines to a boundary
 scan=$(printf '%s' "$scan" | sed -E \
@@ -77,10 +294,10 @@ scan=$(printf '%s' "$scan" | sed -E \
 # `(`, `\` and `command ` wrappers were already neutralized by FIX C above.
 segments=""
 _split="$scan"
-_split="${_split//&&/$'\n'}"
-_split="${_split//||/$'\n'}"
-_split="${_split//;/$'\n'}"
-_split="${_split//|/$'\n'}"
+_split="${_split//&&/$_nl}"
+_split="${_split//||/$_nl}"
+_split="${_split//;/$_nl}"
+_split="${_split//|/$_nl}"
 while IFS= read -r _seg; do
   _seg="${_seg#"${_seg%%[![:space:]]*}"}"                 # strip leading ws
   while [[ "$_seg" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do     # strip VAR=val prefixes
@@ -182,13 +399,14 @@ if printf '%s' "$segments" \
   block "recursive rm over a variable / root / home"
 fi
 
-# 4. Fork bomb.
-if printf '%s' "$cmd" | grep -qE ':\(\)[[:space:]]*\{[[:space:]]*:\|:'; then
+# 4. Fork bomb. Reads `live`, not `scan`: FIX C turns `(` into a space, which
+#    would defuse the very pattern this rule looks for.
+if printf '%s' "$live" | grep -qE ':\(\)[[:space:]]*\{[[:space:]]*:\|:'; then
   block "fork bomb"
 fi
 
 # 5. Writing to a raw block device (wipes a disk/partition).
-if printf '%s' "$cmd" | grep -qE '(of=/dev/(sd|nvme|disk|hd)|>[[:space:]]*/dev/(sd|nvme|disk|hd))'; then
+if printf '%s' "$live" | grep -qE '(of=/dev/(sd|nvme|disk|hd)|>[[:space:]]*/dev/(sd|nvme|disk|hd))'; then
   block "direct write to a block device"
 fi