@marcomigozzi/trailhead 0.13.0 → 0.14.0

package/README.it.md

@@ -6,7 +6,7 @@
 
 🇬🇧 [English](README.md) · 🇮🇹 **Italiano**
 
-[![sito](https://img.shields.io/badge/sito-trailhead.marcomigozzi.it-3C7A5A?style=flat-square)](https://trailhead.marcomigozzi.it) [![CI sito](https://img.shields.io/github/actions/workflow/status/ToRvaLDz/trailhead/site-ci.yml?branch=main&style=flat-square&label=CI%20sito)](https://github.com/ToRvaLDz/trailhead/actions/workflows/site-ci.yml) [![npm](https://img.shields.io/npm/v/@marcomigozzi/trailhead?style=flat-square&label=npm&color=CB3837)](https://www.npmjs.com/package/@marcomigozzi/trailhead) [![license](https://img.shields.io/github/license/ToRvaLDz/trailhead?style=flat-square&color=3C7A5A)](LICENSE) ![host](https://img.shields.io/badge/host-Claude%20Code%20%C2%B7%20Codex-1E2A54?style=flat-square) ![comandi](https://img.shields.io/badge/comandi-23%20verbi-0e8a16?style=flat-square) ![guardrail](https://img.shields.io/badge/guardrail-7%20hook-e8710a?style=flat-square)
+[![sito](https://img.shields.io/badge/sito-trailhead.marcomigozzi.it-3C7A5A?style=flat-square)](https://trailhead.marcomigozzi.it) [![CI sito](https://img.shields.io/github/actions/workflow/status/ToRvaLDz/trailhead/site-ci.yml?branch=main&style=flat-square&label=CI%20sito)](https://github.com/ToRvaLDz/trailhead/actions/workflows/site-ci.yml) [![npm](https://img.shields.io/npm/v/@marcomigozzi/trailhead?style=flat-square&label=npm&color=CB3837)](https://www.npmjs.com/package/@marcomigozzi/trailhead) [![license](https://img.shields.io/github/license/ToRvaLDz/trailhead?style=flat-square&color=3C7A5A)](LICENSE) ![host](https://img.shields.io/badge/host-Claude%20Code%20%C2%B7%20Codex-1E2A54?style=flat-square) ![comandi](https://img.shields.io/badge/comandi-24%20verbi-0e8a16?style=flat-square) ![guardrail](https://img.shields.io/badge/guardrail-7%20hook-e8710a?style=flat-square)
 
 </div>
 
@@ -70,7 +70,7 @@ npx @marcomigozzi/trailhead --dir=<path> # punta a una config dir specifica
 ```
 Su **Claude Code** copia la skill (+ le sue `references/`), i comandi `/trailhead:*`, gli hook (in `hooks/`, registrati in `settings.json`) incluso un **update check** al SessionStart, e i template di label-guard + statusline, in modo idempotente.
 
-Su **Codex CLI** (`--codex`) proietta una skill nativa Codex invocata come **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), una skill sottile **`$trailhead-<verb>`** per ogni verbo per la discoverability, le sei guardrail come **hook** nativi di Codex (`~/.codex/hooks.json`, abilitando `features.hooks`; la search guard è solo per Claude Code e non è proiettata su Codex), e i pin di modello per-tecnica da **`models.codex.*`** in `~/.codex/agents/`. Serve Codex **0.145.0+** (l'installer fa un gate su `codex --version`). La modalità mockup `artifacts` (il tool `Artifact` di Claude Code) non è disponibile su Codex; lì l'opzione hosted è la modalità cross-host `design: stitch` (MCP Google Stitch), con il disco locale come ripiego.
+Su **Codex CLI** (`--codex`) proietta una skill nativa Codex invocata come **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), una skill sottile **`$trailhead-<verb>`** per ogni verbo per la discoverability, le sei guardrail come **hook** nativi di Codex (`~/.codex/hooks.json`, abilitando `features.hooks`; i quattro guard Bash condividono un solo processo dietro una singola registrazione; la search guard è solo per Claude Code e non è proiettata su Codex), e i pin di modello per-tecnica da **`models.codex.*`** in `~/.codex/agents/`. Serve Codex **0.145.0+** (l'installer fa un gate su `codex --version`). La modalità mockup `artifacts` (il tool `Artifact` di Claude Code) non è disponibile su Codex; lì l'opzione hosted è la modalità cross-host `design: stitch` (MCP Google Stitch), con il disco locale come ripiego.
 
 Ri-esegui l'install per aggiornare, oppure esegui **`/trailhead:update`** (Claude) / **`$trailhead update`** (Codex) da dentro l'agente: rileva come trailhead è stato installato e installa la versione più recente dove è sicuro farlo (un `git pull` per un dev-symlink, una ri-esecuzione `npx` per npm, o `/plugin update` per il plugin). Quando esiste una versione più recente, la statusline mostra un flag `⬆ trailhead <version>` (Claude).
 
@@ -185,6 +185,27 @@ Ogni verbo è anche un comando con namespace (`/trailhead:new`, `/trailhead:work
 | `/trailhead:grill [topic]` | esegue una sessione di grilling autonoma su una decision/topic |
 | `/trailhead:map` | mostra la mappa a bassa risoluzione (destination, decisions, frontier, fog) |
 | `/trailhead:dashboard` | mostra la dashboard del repo: l'indice pinnato di ogni mappa aperta, la whiteboard, e i conteggi live |
+| `/trailhead:panel` | apre o chiude il pannello live della mappa: i ticket aperti della mappa attiva per stato, con un pulsante `work` per ogni ticket della frontier (**solo Claude Code**: richiede la mod di trailhead, 2.1.287+) |
+
+### 🖥️ A schermo in Claude Code
+
+La mod di trailhead (Claude Code 2.1.287+) è inclusa nel plugin e disegna il lavoro accanto alla conversazione. Codex mantiene gli hook dei comandi e non ha un pannello.
+
+![Il pannello della mappa affiancato al transcript: mappe aperte, frontier con un pulsante work per ticket, in corso, bloccati e un footer con refresh e close](assets/screenshots/map-panel.png)
+
+Il pannello della mappa elenca le mappe aperte da consultare, la frontier con un pulsante `work` per ogni ticket che pulisce il contesto e avvia il ticket, chi tiene cosa e cosa è bloccato. Il footer ha `refresh` e `close`. `/trailhead:panel` lo apre e lo chiude, e si apre da solo una volta in fullscreen.
+
+![Il pannello che mostra un'altra mappa, con l'intestazione viewing e active e il pulsante back to active](assets/screenshots/map-panel-viewing.png)
+
+Un click mostra soltanto una mappa, e `back to active` torna a quella attiva. La mappa attiva cambia quando lavori uno dei suoi ticket.
+
+![La sezione Burn-down del pannello: riga dei conteggi e grafico dei ticket aperti nel tempo](assets/screenshots/burndown.png)
+
+Il burn-down mostra i ticket aperti nel tempo, dal primo ticket della mappa a oggi, con chiusi e rimossi contati a parte.
+
+![La pipeline band sopra il prompt e la voce di stato trailhead sotto](assets/screenshots/work-state-band.png)
+
+La pipeline band sopra il prompt e la voce di stato sotto mostrano il ticket in gioco e il suo step.
 
 ### Capture: zero attrito, una riga di conferma, non risolve nulla
 
@@ -351,9 +372,13 @@ Oltre alle istruzioni della skill, trailhead include otto hook propri (in `hooks
 - **Search guard** (`PreToolUse` su `Bash`): un backstop strutturale per la regola di igiene dei comandi di ricerca (mai `cd` seguito da una lettura/ricerca su percorso relativo). Blocca in modo netto un singolo comando Bash che sia insieme un cambio di directory (`cd`/`pushd`/`env -C`) e, in un'istruzione unita o successiva, una lettura/ricerca su percorso relativo (`grep`/`rg`/`ag`/`cat`/`head`/`tail`/`wc`/`nl`/`sed`/`awk`/`less`/`more`, o `git grep`/`log`/`show`/`diff` senza `-C`), così la forma che fa scattare una regola di deny su `Read()` sotto bypass permissions (ripiegando su un prompt di approvazione manuale invece di girare headless) non viene mai eseguita, anziché essere solo scoraggiata nella prosa dell'agente. Solo Claude Code; non è proiettata su Codex, che non ha una regola di deny su `Read()`.
 - **Body guard** (`PreToolUse` sulle scritture `gh` di body issue/PR): blocca in modo netto una scrittura `gh issue edit` / `gh pr edit` / `gh api` che imposterebbe il body di un issue a vuoto o solo spazi, così un read-modify-write la cui lettura è tornata con un body vuoto/degradato (es. un HTTP 5xx transitorio su `gh issue view --json body`) non può mai cancellare il body esistente.
 - **Secret-read guard** (`PreToolUse` su `Read|Bash`): blocca in modo netto la lettura di `.env`/`.env.*`/`.secrets`, sia tramite il tool Read sia tramite un comando Bash (un operando file, il valore di un'opzione, o un target di redirect `<`). È una decisione `deny` a livello di hook anziché una regola di permesso su `Read()`, quindi i segreti restano illeggibili senza attivare il prompt di approvazione `cd-compound-read` di Claude Code 2.1.259.
-- **Mockup-link guard** (`PreToolUse` su `AskUserQuestion`): rete di sicurezza strutturale per la regola della tecnica Prototype secondo cui la richiesta di approvazione di un mockup porta con sé il link al mockup. Blocca un `AskUserQuestion` che chiede di approvare un mockup (o di scegliere tra varianti) quando il testo della risposta subito prima non contiene un URL o un path, così l'agente mette il link cliccabile nel messaggio prima di richiedere. Su Codex, che non ha il tool `AskUserQuestion` e pone le domande come elenco numerato in testo, il gemello `mockup-link-stop` gira su `Stop`: se la risposta finale chiede quell'approvazione senza link, Codex fa proseguire il turno e l'agente riscrive la domanda col link.
+- **Mockup-link guard** (`PreToolUse` su `AskUserQuestion`): rete di sicurezza strutturale per la regola della tecnica Prototype secondo cui la richiesta di approvazione di un mockup porta con sé il link al mockup. Blocca un `AskUserQuestion` che chiede di approvare un mockup (o di scegliere tra varianti) quando né il testo della risposta subito prima né la domanda di approvazione stessa contengono un URL o un path (se il messaggio corrente non è ancora nel transcript, la guardia non può giudicare e lascia passare), così l'agente mette il link cliccabile nel messaggio prima di richiedere. Su Codex, che non ha il tool `AskUserQuestion` e pone le domande come elenco numerato in testo, il gemello `mockup-link-stop` gira su `Stop`: se la risposta finale chiede quell'approvazione senza link, Codex fa proseguire il turno e l'agente riscrive la domanda col link.
 - **Issue injection scanner** (`PostToolUse` sulle letture `gh`): trailhead legge testo di issue/PR/commenti scritto da chiunque abbia accesso al repo, cioè input non fidato. Quando quel testo contiene frasi di prompt-injection, l'hook inietta un avviso che ricorda all'agente di trattarlo come dati, mai come comandi. Solo advisory: non blocca mai.
 
+I guard di commit, secret, install, search e body girano in **un solo processo**: una singola registrazione `trailhead-bash-guards.js` li valuta in quell'ordine, così una chiamata Bash paga un solo avvio di node invece di cinque (tre processi hook per chiamata Bash in tutto: l'hook unificato, il secret-read guard e l'injection scanner). Restano cinque guard distinti con verdetti invariati; vince il primo blocco, e un guard che va in errore consente da solo senza fermare gli altri. Anche un guard il cui modulo manca o è rotto viene saltato, ma mai in silenzio: l'hook segnala alla sessione quale guard non ha controllato il comando, così un'installazione parziale non passa inosservata. Su Codex lo stesso hook è registrato con `--guards=commit,secret,install,body`, perché lì non c'è la search guard.
+
+I guard secret, body e secret-read **falliscono in modo chiuso sui costrutti shell che non sanno interpretare con certezza** (`eval`, `source` / `.`, un `${ cmd; }` di bash 5.3, `printf -v`, la definizione di una funzione, un alias, una chiave body di `gh api` quotata, un backslash-a-capo dentro una parola): quando uno di questi può nascondere o precedere una scrittura (o sta accanto a un path segreto) il comando viene bloccato con un messaggio "riscrivilo in forma semplice" invece di essere emulato; gli stessi costrutti senza scritture o segreti vicini passano.
+
 Tutti e otto sono crash-safe (qualsiasi errore → allow) e attivi ogni volta che il plugin è installato. I guard di commit, secret, install, search, body e secret-read quindi si applicano in **ogni** repo, non solo nei progetti trailhead: intenzionale, dato che i conventional commit, niente `Co-Authored-By`, nessun segreto leakato, nessuna installazione non verificata, niente `cd`-poi-lettura-relativa, nessun body issue cancellato, e niente `.env`/`.secrets` leggibili sono regole permanenti di trailhead. Per fare opt-out, disabilita gli hook del plugin nelle impostazioni di Claude Code.
 
 ---

package/README.md

@@ -6,7 +6,7 @@
 
 🇬🇧 **English** · 🇮🇹 [Italiano](README.it.md)
 
-[![website](https://img.shields.io/badge/website-trailhead.marcomigozzi.it-3C7A5A?style=flat-square)](https://trailhead.marcomigozzi.it) [![site CI](https://img.shields.io/github/actions/workflow/status/ToRvaLDz/trailhead/site-ci.yml?branch=main&style=flat-square&label=site%20CI)](https://github.com/ToRvaLDz/trailhead/actions/workflows/site-ci.yml) [![npm](https://img.shields.io/npm/v/@marcomigozzi/trailhead?style=flat-square&label=npm&color=CB3837)](https://www.npmjs.com/package/@marcomigozzi/trailhead) [![license](https://img.shields.io/github/license/ToRvaLDz/trailhead?style=flat-square&color=3C7A5A)](LICENSE) ![hosts](https://img.shields.io/badge/hosts-Claude%20Code%20%C2%B7%20Codex-1E2A54?style=flat-square) ![commands](https://img.shields.io/badge/commands-23%20verbs-0e8a16?style=flat-square) ![guardrails](https://img.shields.io/badge/guardrails-7%20hooks-e8710a?style=flat-square)
+[![website](https://img.shields.io/badge/website-trailhead.marcomigozzi.it-3C7A5A?style=flat-square)](https://trailhead.marcomigozzi.it) [![site CI](https://img.shields.io/github/actions/workflow/status/ToRvaLDz/trailhead/site-ci.yml?branch=main&style=flat-square&label=site%20CI)](https://github.com/ToRvaLDz/trailhead/actions/workflows/site-ci.yml) [![npm](https://img.shields.io/npm/v/@marcomigozzi/trailhead?style=flat-square&label=npm&color=CB3837)](https://www.npmjs.com/package/@marcomigozzi/trailhead) [![license](https://img.shields.io/github/license/ToRvaLDz/trailhead?style=flat-square&color=3C7A5A)](LICENSE) ![hosts](https://img.shields.io/badge/hosts-Claude%20Code%20%C2%B7%20Codex-1E2A54?style=flat-square) ![commands](https://img.shields.io/badge/commands-24%20verbs-0e8a16?style=flat-square) ![guardrails](https://img.shields.io/badge/guardrails-7%20hooks-e8710a?style=flat-square)
 
 </div>
 
@@ -70,7 +70,7 @@ npx @marcomigozzi/trailhead --dir=<path> # target a specific config dir
 ```
 On **Claude Code** it copies the skill (+ its `references/`), the `/trailhead:*` commands, the hooks (into `hooks/`, registered in `settings.json`) including a SessionStart **update check**, and the label-guard + statusline templates, idempotently.
 
-On **Codex CLI** (`--codex`) it projects a native Codex skill invoked as **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), one thin **`$trailhead-<verb>`** skill per verb for discoverability, the six guardrails as native Codex **hooks** (`~/.codex/hooks.json`, enabling `features.hooks`; the search guard is Claude-Code-only and isn't projected to Codex), and per-technique subagent model pins from **`models.codex.*`** into `~/.codex/agents/`. Codex **0.145.0+** is required (the installer gates on `codex --version`). The `artifacts` mockup mode (Claude Code's `Artifact` tool) isn't available on Codex; the cross-host `design: stitch` mode (Google Stitch MCP) is the hosted option there, with local disk as the fallback.
+On **Codex CLI** (`--codex`) it projects a native Codex skill invoked as **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), one thin **`$trailhead-<verb>`** skill per verb for discoverability, the six guardrails as native Codex **hooks** (`~/.codex/hooks.json`, enabling `features.hooks`; the four Bash guards share one process behind a single registration; the search guard is Claude-Code-only and isn't projected to Codex), and per-technique subagent model pins from **`models.codex.*`** into `~/.codex/agents/`. Codex **0.145.0+** is required (the installer gates on `codex --version`). The `artifacts` mockup mode (Claude Code's `Artifact` tool) isn't available on Codex; the cross-host `design: stitch` mode (Google Stitch MCP) is the hosted option there, with local disk as the fallback.
 
 Re-run the install to update, or run **`/trailhead:update`** (Claude) / **`$trailhead update`** (Codex) from inside the agent: it detects how trailhead was installed and installs the newer version where that is safe (a `git pull` for a dev-symlink, an `npx` re-run for npm, or `/plugin update` for the plugin). When a newer version exists, the statusline shows a `⬆ trailhead <version>` flag (Claude).
 
@@ -185,6 +185,27 @@ Every verb is also a namespaced command (`/trailhead:new`, `/trailhead:work`, `/
 | `/trailhead:grill [topic]` | run a standalone grilling session on a decision/topic |
 | `/trailhead:map` | show the low-res map (destination, decisions, frontier, fog) |
 | `/trailhead:dashboard` | show the repo dashboard: the pinned index of every open map, the whiteboard, and live counts |
+| `/trailhead:panel` | open or close the live map panel: the active map's open tickets by state, with a `work` button per frontier ticket (**Claude Code only**: needs the trailhead mod, 2.1.287+) |
+
+### 🖥️ On screen in Claude Code
+
+The trailhead mod (Claude Code 2.1.287+) ships inside the plugin and draws the work beside the conversation. Codex keeps the command hooks and has no panel.
+
+![The map panel docked beside the transcript: open maps, frontier with a work button per ticket, in progress, blocked, and a footer with refresh and close](assets/screenshots/map-panel.png)
+
+The map panel lists the open maps to view, the frontier with a `work` button per ticket that clears the context and starts the ticket, who holds what, and what is blocked. The footer has `refresh` and `close`. `/trailhead:panel` toggles it, and it opens by itself once in fullscreen.
+
+![The panel viewing another map, with a viewing and active header and a back to active button](assets/screenshots/map-panel-viewing.png)
+
+A click only views a map, and `back to active` returns to the active one. The active map changes when you work one of its tickets.
+
+![The Burn-down section of the panel: counts line and a chart of open tickets over time](assets/screenshots/burndown.png)
+
+The burn-down shows the open tickets over time, from the map's first ticket to now, with done and removed counted apart.
+
+![The pipeline band above the prompt and the trailhead status entry under it](assets/screenshots/work-state-band.png)
+
+The pipeline band above the prompt and the status entry under it show the ticket in play and its step.
 
 ### Capture: zero friction, one confirmation line, resolves nothing
 
@@ -217,6 +238,15 @@ The three that trip people up are **idea, seed, todo**, so here they are spelled
 
 The two cuts that matter: **idea vs seed** is waiting on *clarity* vs waiting on a *condition* (both land "later", for different reasons); **seed vs todo** is committed *later* vs committed *now*. Below all three sits **`note`** (raw text to remember, maybe never work), and off to the side is **`bug`** (a defect, not a commitment tier). The test for idea vs ticket is always: **can you phrase the question precisely now?** Yes → a ticket (`todo` if takeable, `seed` if gated); no → the fog (`idea`).
 
+### Manage: keep the install and the maps healthy
+
+| Command | What it does |
+|---|---|
+| `/trailhead:config [get\|set …]` | guided menu setup; `get` prints the effective config, `set <key> <value>` writes one key (see Configuration below) |
+| `/trailhead:update` | check for a newer trailhead and install it where that is safe |
+| `/trailhead:prune [map]` | reclaim a map's sub-issue slots under GitHub's 100-cap (drops closed/orphan edges, keeps references) |
+| `/trailhead:audit [map] [--all]` | audit closed tickets for regressions against today's code, plus duplicate and groupable open ones; read-only until you confirm |
+
 ---
 
 ## 🎫 Ticket types and their engines
@@ -305,6 +335,7 @@ The **📊 statusline** step offers to install trailhead's Claude Code status ba
 | `ticket.language` | an ISO 639-1 code (**`en`**) | the language trailhead **writes** its GitHub prose & commit descriptions in, decoupled from the language it converses in |
 | `models.{plan,execute,research,review,debug,verify,codebase-map}` | a full **versioned** model id (**inherit session**) | which model runs each activity; `plan` and `execute` are always set separately |
 | `design` | **`disk`** \| `artifacts` \| `stitch` | where UI mockups go: local throwaway HTML, a Design canvas **Artifact** on claude.ai (Claude Code only), or Google Stitch (cross-host, via the Stitch MCP). The legacy `claude.ai/design` value is read as `artifacts` |
+| `design.project` | canvas Artifact URL / Stitch project id | `artifacts` and `stitch` only: the canvas or Stitch project the mockups land on; set at the first UI screen (pick, paste or create), not by hand. A leftover claude.ai/design project is not reused |
 | `design.surface` | **`canvas`** \| `design-system` | `stitch` only: a Stitch project of screens (default) or a shared Stitch design system |
 | `design.system` | Design System Artifact URL | `artifacts` only: the design system installed on the mockup canvas (asked at the first screen if unset) |
 | `design.approval` | **`explicit`** \| `auto` | wait for mockup approval before UI code, or proceed without blocking |
@@ -351,9 +382,13 @@ Beyond the skill's instructions, trailhead ships eight of its own hooks (in `hoo
 - **Search guard** (`PreToolUse` on `Bash`): structural backstop for the search-command-hygiene rule (never `cd` then read/search a relative path). It hard-blocks a single Bash command that both changes directory (`cd`/`pushd`/`env -C`) and, in a joined or later statement, reads/searches a relative path (`grep`/`rg`/`ag`/`cat`/`head`/`tail`/`wc`/`nl`/`sed`/`awk`/`less`/`more`, or `git grep`/`log`/`show`/`diff` without a `-C`), so the shape that trips a `Read()` deny rule under bypass permissions (falling back to a manual approval prompt instead of running headless) never runs at all, rather than merely being discouraged in the agent's own prose. Claude Code only; not projected to Codex, which has no such `Read()` deny rule.
 - **Body guard** (`PreToolUse` on `gh` issue/PR body writes): hard-blocks a `gh issue edit` / `gh pr edit` / `gh api` write that would set an issue body to empty or whitespace-only, so a read-modify-write whose read returned an empty/degraded body (e.g. a transient HTTP 5xx on `gh issue view --json body`) can never clobber the existing body.
 - **Secret-read guard** (`PreToolUse` on `Read|Bash`): denies reads of `.env`/`.env.*`/`.secrets`, whether via the Read tool or a Bash command (a file operand, an option value, or a `<` redirect target). This is a hook `deny` decision rather than a `Read()` permission rule, so secrets stay unreadable without arming Claude Code 2.1.259's `cd-compound-read` approval prompt.
-- **Mockup-link guard** (`PreToolUse` on `AskUserQuestion`): structural backstop for the Prototype rule that a mockup approval ask carries the mockup's link. It hard-blocks an `AskUserQuestion` that asks to approve a mockup (or pick between mockup variants) when the reply text right before it holds no URL or file path, so the agent puts the clickable link in the message before asking again. On Codex, which has no `AskUserQuestion` tool and asks as a plain-text numbered list, its twin `mockup-link-stop` runs on `Stop`: when the final reply asks for that approval without a link, Codex continues the turn so the agent rewrites the ask with it.
+- **Mockup-link guard** (`PreToolUse` on `AskUserQuestion`): structural backstop for the Prototype rule that a mockup approval ask carries the mockup's link. It hard-blocks an `AskUserQuestion` that asks to approve a mockup (or pick between mockup variants) when neither the reply text right before it nor the approval question itself holds a URL or file path (when the current message is not yet in the transcript, the guard cannot judge and allows), so the agent puts the clickable link in the message before asking again. On Codex, which has no `AskUserQuestion` tool and asks as a plain-text numbered list, its twin `mockup-link-stop` runs on `Stop`: when the final reply asks for that approval without a link, Codex continues the turn so the agent rewrites the ask with it.
 - **Issue injection scanner** (`PostToolUse` on `gh` reads): trailhead reads issue/PR/comment text written by anyone with repo access, i.e. untrusted input. When that text contains prompt-injection phrases, the hook injects an advisory reminding the agent to treat it as data, never as commands. Advisory only: it never blocks.
 
+The commit, secret, install, search, and body guards run in **one process**: a single `trailhead-bash-guards.js` registration evaluates them in that order, so a Bash call pays one node start-up instead of five (three hook processes per Bash call in all: the merged hook, the secret-read guard, and the injection scanner). They remain five distinct guards with unchanged verdicts; the first block wins, and a guard that errors allows on its own without stopping the others. A guard whose module is missing or broken is skipped too, but never silently: the hook tells the session which guard did not check the command, so a partial install shows up. On Codex the same hook is registered with `--guards=commit,secret,install,body`, since there is no search guard there.
+
+The secret, body, and secret-read guards also **fail closed on shell constructs they cannot interpret with certainty** (`eval`, `source` / `.`, a bash 5.3 `${ cmd; }`, `printf -v`, a function definition, an alias, a quoted `gh api` body key, a backslash-newline inside a word): when one can hide or precede a write (or sits next to a secret path), the command is blocked with a "rewrite it in a simple form" message instead of being emulated; the same constructs with no write or secret nearby pass.
+
 All eight are crash-safe (any error → allow) and active whenever the plugin is installed. The commit, secret, install, search, body, and secret-read guards therefore apply in **every** repo, not only trailhead projects: intentional, since conventional commits, no `Co-Authored-By`, no leaked secrets, no unvetted installs, no `cd`-then-relative-read, no clobbered issue bodies, and no readable `.env`/`.secrets` are trailhead's standing rules. To opt out, disable the plugin's hooks in your Claude Code settings.
 
 ---

package/bin/lib/codex-projection.js

@@ -113,7 +113,7 @@ Codex has a subagent toolkit: the multi_agent tools (\`spawn_agent\`, \`send_inp
 The engine's \`/clear\` is Codex's \`/new\` (start a fresh session). Command references in a handoff use the skill form (\`$trailhead work <n>\`).
 
 ## F. Lifecycle hooks (native Codex hooks)
-Codex has a hook bus, so trailhead's guardrails run as **real Codex hooks**, not degraded prose. The installer registers them in \`~/.codex/hooks.json\`: commit-guard, secret-guard, install-guard and body-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs, secret-read-guard as a \`PreToolUse\` (matcher \`Read|Bash\`) hook that denies reads of \`.env\`/\`.env.*\`/\`.secrets\`, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, mockup-link-stop as a \`Stop\` hook (when your final reply asks to approve a mockup without carrying its link, it continues the turn so you rewrite the ask with the URL or file path in the prose), and check-update as a \`SessionStart\` hook. On Codex, file reads happen through shell commands rather than a native Read-tool event, so the secret-read guard's enforcement here runs via its **Bash** arm (protection is not lost); the \`Read\` half of its matcher is a Claude-Code-native path, registered on Codex too only so it fires without changes if a future Codex version adds an equivalent event. search-guard is Claude-Code-specific (it only prevents arming Claude's \`Read()\` deny rule under bypass permissions, a mechanism Codex lacks), so it is not projected to Codex at all. They use the same wire format they use on Claude Code (JSON on stdin, a \`decision\`/\`permissionDecision\` verdict on stdout), which Codex accepts. The host-independent git \`commit-msg\` hook is still installed at repo first-use as well (defence in depth), exactly as on Claude. Codex gates hooks behind \`features.hooks = true\` and reviews them for trust on first start: the installer enables the flag, and Codex will ask you to trust trailhead's hooks the next time it starts.
+Codex has a hook bus, so trailhead's guardrails run as **real Codex hooks**, not degraded prose. The installer registers them in \`~/.codex/hooks.json\`: commit-guard, secret-guard, install-guard and body-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs (the four run in one process, a single \`trailhead-bash-guards.js --guards=commit,secret,install,body\` registration, so a Bash call pays one start-up instead of four), secret-read-guard as a \`PreToolUse\` (matcher \`Read|Bash\`) hook that denies reads of \`.env\`/\`.env.*\`/\`.secrets\`, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, mockup-link-stop as a \`Stop\` hook (when your final reply asks to approve a mockup without carrying its link, it continues the turn so you rewrite the ask with the URL or file path in the prose), and check-update as a \`SessionStart\` hook. On Codex, file reads happen through shell commands rather than a native Read-tool event, so the secret-read guard's enforcement here runs via its **Bash** arm (protection is not lost); the \`Read\` half of its matcher is a Claude-Code-native path, registered on Codex too only so it fires without changes if a future Codex version adds an equivalent event. search-guard is Claude-Code-specific (it only prevents arming Claude's \`Read()\` deny rule under bypass permissions, a mechanism Codex lacks), so it is not projected to Codex at all. They use the same wire format they use on Claude Code (JSON on stdin, a \`decision\`/\`permissionDecision\` verdict on stdout), which Codex accepts. The host-independent git \`commit-msg\` hook is still installed at repo first-use as well (defence in depth), exactly as on Claude. Codex gates hooks behind \`features.hooks = true\` and reviews them for trust on first start: the installer enables the flag, and Codex will ask you to trust trailhead's hooks the next time it starts.
 
 ## G. Design / UI mockups: artifacts -> stitch offer, else local disk
 The \`artifacts\` mockup mode (a Design canvas Artifact built with Claude Code's \`Artifact\` tool; the legacy \`claude.ai/design\` value means the same) does not exist on Codex: there is no \`Artifact\` tool here. When \`config.design\` names it, follow the Prototype technique's fallback: **offer once to switch this project to \`design: stitch\`** (the Google Stitch MCP runs on Codex too), and only on decline produce a throwaway static HTML mockup next to the code (\`disk\`), link it from the ticket, and say why. Never try to create or edit an Artifact on Codex. \`config.design.approval\` still applies unchanged: \`explicit\` waits for the user's go-ahead before any UI code, \`auto\` surfaces the mockup and proceeds.
@@ -323,6 +323,11 @@ policy:
 `;
 }
 
+// --- CODEX_MOD_ONLY_VERBS --------------------------------------------------
+// Verbs only the Claude Code mod answers (commands/<verb>.md exists for the
+// namespaced command, but nothing on Codex can draw it): never projected.
+const CODEX_MOD_ONLY_VERBS = ['panel'];
+
 // --- codexVerbSkillPlan ----------------------------------------------------
 // Given the resolved verb list (each { verb, description? }, or a bare string
 // verb; normally read from plugins/trailhead/commands/*.md by the installer),
@@ -340,6 +345,7 @@ function codexVerbSkillPlan(codexHome, verbs) {
     const v = entry && typeof entry === 'object' ? entry.verb : entry;
     if (v == null || String(v).trim() === '') continue;
     const verb = String(v).trim();
+    if (CODEX_MOD_ONLY_VERBS.includes(verb)) continue;
     const description = entry && typeof entry === 'object' ? entry.description : undefined;
     const skillDir = path.join(skillsRoot, `trailhead-${verb}`);
     dirs.push(skillDir);
@@ -358,10 +364,13 @@ function codexVerbSkillPlan(codexHome, verbs) {
 }
 
 // --- codexHookEntries -----------------------------------------------------
-// The six guardrail hooks trailhead registers on Codex, as {event, matcher,
-// command} records. Commands run the copied guard scripts under hooksScriptsDir
-// via node, matching Claude's `node "<path>"` form. PreToolUse guards (commit,
-// secret, install, body, secret-read) can veto; the injection-scanner
+// The guardrail hooks trailhead registers on Codex, as {event, matcher,
+// command} records. Commands run the copied hook scripts under hooksScriptsDir
+// via node, matching Claude's `node "<path>"` form. The four Bash guards
+// (commit, secret, install, body) are ONE registration, the merged
+// trailhead-bash-guards.js with `--guards=commit,secret,install,body` (a single
+// node process per Bash call); secret-read is a separate PreToolUse hook. All
+// PreToolUse guards can veto; the injection-scanner
 // is a PostToolUse advisory; check-update runs at SessionStart. Reused by the
 // installer, which merges them into ~/.codex/hooks.json (same shape as
 // Claude's settings.json hooks block).
@@ -372,10 +381,7 @@ function codexVerbSkillPlan(codexHome, verbs) {
 function codexHookEntries(hooksScriptsDir) {
   const cmd = (name) => `node "${path.join(hooksScriptsDir, name)}"`;
   return [
-    { event: 'PreToolUse', matcher: 'Bash', command: cmd('trailhead-commit-guard.js') },
-    { event: 'PreToolUse', matcher: 'Bash', command: cmd('trailhead-secret-guard.js') },
-    { event: 'PreToolUse', matcher: 'Bash', command: cmd('trailhead-install-guard.js') },
-    { event: 'PreToolUse', matcher: 'Bash', command: cmd('trailhead-body-guard.js') },
+    { event: 'PreToolUse', matcher: 'Bash', command: `${cmd('trailhead-bash-guards.js')} --guards=commit,secret,install,body` },
     { event: 'PreToolUse', matcher: 'Read|Bash', command: cmd('trailhead-secret-read-guard.js') },
     { event: 'PostToolUse', matcher: 'Bash', command: cmd('trailhead-issue-injection-scanner.js') },
     { event: 'Stop', matcher: '', command: cmd('trailhead-mockup-link-stop.js') },
@@ -447,6 +453,7 @@ module.exports = {
   codexVerbSkillContent,
   codexVerbSkillAgentsYaml,
   codexVerbSkillPlan,
+  CODEX_MOD_ONLY_VERBS,
   codexHookEntries,
   enableCodexFeatureFlag,
   enableCodexHooksFeature,

package/bin/lib/codex-projection.test.js

@@ -15,6 +15,7 @@ const {
   codexVerbSkillContent,
   codexVerbSkillAgentsYaml,
   codexVerbSkillPlan,
+  CODEX_MOD_ONLY_VERBS,
   codexHookEntries,
   enableCodexHooksFeature,
   enableCodexMultiAgentV2Feature,
@@ -160,19 +161,22 @@ ok('codexVerbSkillPlan: accepts a bare-string verb and skips empty/invalid', (()
 })());
 ok('codexVerbSkillPlan: null verbs yields nothing', codexVerbSkillPlan('/c', null).dirs.length === 0 && codexVerbSkillPlan('/c').dirs.length === 0);
 
+// #208: a verb only the Claude Code mod answers (the map panel) has no Codex projection.
+ok('CODEX_MOD_ONLY_VERBS names exactly the panel verb', Array.isArray(CODEX_MOD_ONLY_VERBS) && CODEX_MOD_ONLY_VERBS.length === 1 && CODEX_MOD_ONLY_VERBS[0] === 'panel');
+ok('codexVerbSkillPlan: never projects a mod-only verb, object or bare string', (() => {
+  const plan = codexVerbSkillPlan('/c', [{ verb: 'panel', description: 'x' }, 'panel', { verb: 'map' }]);
+  return plan.dirs.length === 1 && plan.dirs[0] === '/c/skills/trailhead-map' && !plan.writes.some((w) => /panel/.test(w.path));
+})());
+
 // --- codexHookEntries ---
 const entries = codexHookEntries('/h');
-ok('codexHookEntries returns 8 entries', Array.isArray(entries) && entries.length === 8);
-ok('codexHookEntries: commit-guard is PreToolUse/Bash', entries.some((e) =>
-  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-commit-guard.js') && e.command.includes('/h')));
-ok('codexHookEntries: secret-guard is PreToolUse/Bash', entries.some((e) =>
-  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-secret-guard.js')));
-ok('codexHookEntries: install-guard is PreToolUse/Bash', entries.some((e) =>
-  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-install-guard.js')));
-ok('codexHookEntries: search-guard is absent (Claude-Code-only, not projected to Codex)',
-  entries.every((e) => !e.command.includes('trailhead-search-guard.js')));
-ok('codexHookEntries: body-guard is PreToolUse/Bash', entries.some((e) =>
-  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-body-guard.js')));
+ok('codexHookEntries returns 5 entries', Array.isArray(entries) && entries.length === 5);
+const bashEntries = entries.filter((e) => e.event === 'PreToolUse' && e.matcher === 'Bash');
+ok('codexHookEntries: exactly one PreToolUse/Bash registration', bashEntries.length === 1);
+ok('codexHookEntries: the Bash entry is the merged hook with exactly --guards=commit,secret,install,body',
+  bashEntries[0].command === 'node "/h/trailhead-bash-guards.js" --guards=commit,secret,install,body');
+ok('codexHookEntries: no per-guard script is registered on its own', entries.every((e) =>
+  !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(e.command)));
 ok('codexHookEntries: secret-read-guard is PreToolUse/Read|Bash', entries.some((e) =>
   e.event === 'PreToolUse' && e.matcher === 'Read|Bash' && e.command.includes('trailhead-secret-read-guard.js')));
 ok('codexHookEntries: injection-scanner is PostToolUse/Bash', entries.some((e) =>
@@ -402,4 +406,28 @@ ok('convertToCodex projects the anchor positives to Codex forms', (() => {
     !out.includes('/trailhead:work') && !out.includes('/clear');
 })());
 
+// #205: the work state helper and its session env var survive the projection;
+// the projected work skill and handoff carry the set/clear calls.
+ok('convertToCodex keeps the trailhead-work-state.js filename',
+  convertToCodex('node <templates>/trailhead-work-state.js set').includes('<templates>/trailhead-work-state.js set'));
+ok('convertToCodex keeps CLAUDE_CODE_SESSION_ID intact',
+  convertToCodex('session from CLAUDE_CODE_SESSION_ID when set').includes('CLAUDE_CODE_SESSION_ID'));
+{
+  const skillsDir = path.join(__dirname, '../../plugins/trailhead/skills');
+  const workSkill = convertToCodex(fs.readFileSync(path.join(skillsDir, 'trailhead-work', 'SKILL.md'), 'utf8'));
+  ok('projected work skill carries the work-start set call',
+    workSkill.includes('trailhead-work-state.js set --repo <working-root> --map <n> --ticket <n> --title "<title>" --step discuss'));
+  const handoff = convertToCodex(fs.readFileSync(path.join(skillsDir, '_shared', 'session-handoff.md'), 'utf8'));
+  ok('projected session handoff carries the work state clear call',
+    handoff.includes('trailhead-work-state.js clear --repo <working-root>'));
+  const teamwork = convertToCodex(fs.readFileSync(path.join(skillsDir, '_shared', 'teamwork.md'), 'utf8'));
+  ok('projected teamwork carries the step change call',
+    teamwork.includes('trailhead-work-state.js set --repo <working-root> --step <step>'));
+  ok('projected teamwork carries the autoDone counter flag',
+    teamwork.includes('--auto true --auto-done <n>'));
+  const autoRef = convertToCodex(fs.readFileSync(path.join(skillsDir, 'trailhead-work', 'references', 'auto.md'), 'utf8'));
+  ok('projected auto reference carries the autoDone counter flag',
+    autoRef.includes('--auto true --auto-done <n>'));
+}
+
 console.log(`✓ codex-projection: ${passed} assertions passed`);

package/bin/lib/install-verify.js

@@ -135,6 +135,9 @@ function readRegistry(registryFile) {
 // token expands to exactly hooksDir/<f>, OR an unresolved token's basename is
 // <f> (stays warning-only, never also missing).
 function checkRegisteredTargets(spec, missing, unverified) {
+  // Shipped files (hookFiles) may include modules that are only require()d;
+  // the files that must be registered are the entrypoints (default: all shipped).
+  const entrypoints = spec.entrypointFiles || spec.hookFiles;
   const registry = readRegistry(spec.registryFile);
   const registryName = path.basename(spec.registryFile);
   const events = (registry && typeof registry.hooks === 'object' && registry.hooks) ? registry.hooks : {};
@@ -168,7 +171,7 @@ function checkRegisteredTargets(spec, missing, unverified) {
     }
   }
 
-  for (const f of spec.hookFiles) {
+  for (const f of entrypoints) {
     if (!registeredExact.has(f) && !registeredViaUnresolved.has(f)) {
       missing.push(`hook registration ${f} (${registryName})`);
     }
@@ -185,8 +188,8 @@ function checkAgents(spec, missing) {
 }
 
 // --- verifyInstall --------------------------------------------------------------
-// spec = { skillsRoot, skillDirs, sharedFiles, hooksDir, hookFiles,
-//          hookLibFiles, registryFile, agentsDir, agentPattern, env, home }
+// spec = { skillsRoot, skillDirs, sharedFiles, hooksDir, hookFiles (shipped),
+//          entrypointFiles (registered; defaults to hookFiles), hookLibFiles, registryFile, agentsDir, agentPattern, env, home }
 function verifyInstall(spec) {
   const missing = [];
   const unverified = [];
@@ -199,13 +202,14 @@ function verifyInstall(spec) {
 }
 
 // --- spec builders ---------------------------------------------------------
-function claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env, home }) {
+function claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, entrypointFiles, hookLibFiles, env, home }) {
   return {
     skillsRoot: path.join(configDir, 'skills'),
     skillDirs,
     sharedFiles,
     hooksDir: path.join(configDir, 'hooks'),
     hookFiles,
+    entrypointFiles,
     hookLibFiles,
     registryFile: path.join(configDir, 'settings.json'),
     agentsDir: path.join(configDir, 'agents'),
@@ -215,7 +219,7 @@ function claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLi
   };
 }
 
-function codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env, home }) {
+function codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, entrypointFiles, hookLibFiles, env, home }) {
   const L = codexLayout(configDir);
   return {
     skillsRoot: L.skillsRoot,
@@ -223,6 +227,7 @@ function codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLib
     sharedFiles,
     hooksDir: L.hooksScriptsDir,
     hookFiles,
+    entrypointFiles,
     hookLibFiles,
     registryFile: L.hooksJson,
     agentsDir: L.codexAgentsDir,

package/bin/lib/install-verify.test.js

@@ -359,6 +359,57 @@ function buildCodexFixture() {
     r.unverified.some((u) => u.includes('CLAUDE_PLUGIN_ROOT undefined')));
 }
 
+// --- shipped files vs registered entrypoints (#207) ---------------------------
+// The guard modules are shipped (they must exist) but only require()d by the
+// merged hook, so they are never required to be registered.
+function buildMergedFixture(host) {
+  const configDir = mktmp();
+  const skillDirs = ['trailhead', '_shared'];
+  const sharedFiles = ['load-first.md'];
+  const modules = ['trailhead-commit-guard.js', 'trailhead-body-guard.js'];
+  const entrypointFiles = ['trailhead-bash-guards.js'];
+  const hookFiles = [...modules, ...entrypointFiles];
+  const hooksDir = host === 'codex' ? path.join(configDir, 'skills', 'trailhead', 'hooks') : path.join(configDir, 'hooks');
+  write(path.join(configDir, 'skills', 'trailhead', 'SKILL.md'), 'x');
+  write(path.join(configDir, 'skills', '_shared', 'load-first.md'), 'x');
+  for (const f of hookFiles) write(path.join(hooksDir, f), 'x');
+  write(path.join(configDir, 'agents', host === 'codex' ? 'trailhead-execute.toml' : 'trailhead-execute.md'), 'x');
+  const registry = { hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+    { type: 'command', command: `node "${path.join(hooksDir, 'trailhead-bash-guards.js')}"${host === 'codex' ? ' --guards=commit,body' : ''}` },
+  ] }] } };
+  write(path.join(configDir, host === 'codex' ? 'hooks.json' : 'settings.json'), JSON.stringify(registry, null, 2));
+  const build = host === 'codex' ? codexVerifySpec : claudeVerifySpec;
+  const spec = build(configDir, { skillDirs, sharedFiles, hookFiles, entrypointFiles, hookLibFiles: [], env: {}, home: H });
+  return { configDir, spec, hooksDir };
+}
+for (const host of ['claude', 'codex']) {
+  {
+    const { spec } = buildMergedFixture(host);
+    const r = verifyInstall(spec);
+    ok(`${host}: passes with the guard modules shipped but unregistered`, r.missing.length === 0 && r.unverified.length === 0);
+  }
+  {
+    const { spec, hooksDir } = buildMergedFixture(host);
+    fs.rmSync(path.join(hooksDir, 'trailhead-commit-guard.js'));
+    const r = verifyInstall(spec);
+    ok(`${host}: a shipped guard module that is missing is still reported`, r.missing.includes('hook script trailhead-commit-guard.js'));
+  }
+  {
+    const { configDir, spec } = buildMergedFixture(host);
+    write(path.join(configDir, host === 'codex' ? 'hooks.json' : 'settings.json'), JSON.stringify({ hooks: {} }));
+    const r = verifyInstall(spec);
+    ok(`${host}: fails when the registered entrypoint is not registered`,
+      r.missing.some((m) => m.startsWith('hook registration trailhead-bash-guards.js')));
+  }
+  {
+    const { spec, hooksDir } = buildMergedFixture(host);
+    fs.rmSync(path.join(hooksDir, 'trailhead-bash-guards.js'));
+    const r = verifyInstall(spec);
+    ok(`${host}: fails when the registered entrypoint file is missing`,
+      r.missing.includes('hook script trailhead-bash-guards.js') && r.missing.some((m) => m.startsWith('registered hook target')));
+  }
+}
+
 // --- formatters --------------------------------------------------------------
 {
   const out = formatVerifyFailure('Claude Code', '/c/dir', { missing: ['skill trailhead-work/SKILL.md'], unverified: ['/x/trailhead-y.js (PreToolUse, settings.json: $Y undefined)'] });

package/bin/trailhead.js

@@ -243,18 +243,27 @@ function claudePaths(configDir) {
     settings: path.join(configDir, 'settings.json'),
   };
 }
-const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-secret-read-guard.js', 'trailhead-body-guard.js', 'trailhead-mockup-link-guard.js', 'trailhead-mockup-link-stop.js', 'trailhead-check-update.js'];
+// The five Bash guard modules. They are shipped, but only require()d by the
+// merged trailhead-bash-guards.js (one process per Bash call), never registered
+// on their own. Legacy installs registered each one; the installers strip those.
+const BASH_GUARD_MODULES = ['trailhead-commit-guard.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-body-guard.js'];
+// Every hook script copied into the hooks dir (shipped runtime files).
+const HOOK_FILES = [...BASH_GUARD_MODULES, 'trailhead-bash-guards.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-read-guard.js', 'trailhead-mockup-link-guard.js', 'trailhead-mockup-link-stop.js', 'trailhead-check-update.js'];
+// The registered entrypoints: the shipped files that must appear in
+// settings.json / hooks.json (everything but the require()d guard modules).
+const ENTRYPOINT_FILES = HOOK_FILES.filter((f) => !BASH_GUARD_MODULES.includes(f));
 // Runtime libs the hook scripts require (trailhead-commit-guard.js does
 // require('./lib/commit-message-check.js'); trailhead-search-guard.js and
 // trailhead-secret-read-guard.js both do require('./lib/shell-scan.js'), #135
 // follow-up; trailhead-body-guard.js and trailhead-secret-guard.js both do
-// require('./lib/gh-subcommand.js'), #153 follow-up; trailhead-check-update.js
+// require('./lib/gh-subcommand.js'), #153 follow-up; trailhead-secret-guard.js
+// also does require('./lib/body-sources.js'), #210; trailhead-check-update.js
 // does require('./lib/model-defaults-review.js'), which in turn reads the
 // sibling model-defaults.json, #186; both mockup-link hooks do
 // require('./lib/mockup-link.js')). Copied by name, never a recursive
 // sweep: the Claude hooks/lib dir is shared with other plugins, so we must
 // not clobber a co-tenant's lib nor ship our own *.test.js files.
-const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js', 'model-defaults-review.js', 'model-defaults.json', 'mockup-link.js'];
+const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js', 'body-sources.js', 'unmodelled.js', 'model-defaults-review.js', 'model-defaults.json', 'mockup-link.js'];
 // search-guard is Claude-Code-specific (#169), and so is mockup-link-guard
 // (it gates the AskUserQuestion tool, which Codex lacks): excluded from both
 // the Codex hook copy and the Codex verify spec's expected hookFiles, so a
@@ -264,6 +273,10 @@ const CODEX_HOOK_EXCLUDE = ['trailhead-search-guard.js', 'trailhead-mockup-link-
 // Claude Code gates the AskUserQuestion call instead, so it is neither copied
 // nor expected on a Claude install.
 const CLAUDE_HOOK_EXCLUDE = ['trailhead-mockup-link-stop.js'];
+const claudeShippedHooks = () => HOOK_FILES.filter((f) => !CLAUDE_HOOK_EXCLUDE.includes(f));
+const claudeEntrypoints = () => ENTRYPOINT_FILES.filter((f) => !CLAUDE_HOOK_EXCLUDE.includes(f));
+const codexShippedHooks = () => HOOK_FILES.filter((f) => !CODEX_HOOK_EXCLUDE.includes(f));
+const codexEntrypoints = () => ENTRYPOINT_FILES.filter((f) => !CODEX_HOOK_EXCLUDE.includes(f));
 
 // Copy the hook scripts and their runtime libs into a destination hooks dir
 // (Claude's ~/.claude/hooks or Codex's skills/trailhead/hooks). Shared by both
@@ -357,6 +370,12 @@ function stripHook(s, event, substr) {
   s.hooks[event] = s.hooks[event].filter((g) => (g.hooks || []).length);
 }
 
+// Drop the per-guard PreToolUse registrations an earlier install made (and the
+// pre-#169 Codex search-guard one): the merged entrypoint replaces all of them.
+function stripLegacyBashGuards(s) {
+  for (const f of BASH_GUARD_MODULES) stripHook(s, 'PreToolUse', f);
+}
+
 function uninstallClaude(configDir) {
   const P = claudePaths(configDir);
   // Sweep every trailhead-owned skill dir (current set + any stale dir a prior
@@ -371,12 +390,9 @@ function uninstallClaude(configDir) {
   // with other plugins, so never rmrf the whole dir.
   HOOK_LIB_FILES.forEach((f) => rmrf(path.join(P.hooksDir, 'lib', f)));
   const s = readJSON(P.settings);
-  stripHook(s, 'PreToolUse', 'trailhead-commit-guard.js');
-  stripHook(s, 'PreToolUse', 'trailhead-secret-guard.js');
-  stripHook(s, 'PreToolUse', 'trailhead-install-guard.js');
-  stripHook(s, 'PreToolUse', 'trailhead-search-guard.js');
+  stripLegacyBashGuards(s);
+  stripHook(s, 'PreToolUse', 'trailhead-bash-guards.js');
   stripHook(s, 'PreToolUse', 'trailhead-secret-read-guard.js');
-  stripHook(s, 'PreToolUse', 'trailhead-body-guard.js');
   stripHook(s, 'PreToolUse', 'trailhead-mockup-link-guard.js');
   stripHook(s, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
   stripHook(s, 'SessionStart', 'trailhead-check-update.js');
@@ -419,12 +435,11 @@ function installClaude(configDir, { useSymlink }) {
   }
 
   const s = readJSON(P.settings);
+  // Migration: an earlier install registered each Bash guard on its own; the
+  // merged entrypoint below replaces all five.
+  stripLegacyBashGuards(s);
   const added = [
-    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-commit-guard.js')),
-    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-secret-guard.js')),
-    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-install-guard.js')),
-    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-search-guard.js')),
-    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-body-guard.js')),
+    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-bash-guards.js')),
     addHook(s, 'PreToolUse', 'Read|Bash', hookCmd('trailhead-secret-read-guard.js')),
     addHook(s, 'PreToolUse', 'AskUserQuestion', hookCmd('trailhead-mockup-link-guard.js')),
     addHook(s, 'PostToolUse', 'Bash', hookCmd('trailhead-issue-injection-scanner.js')),
@@ -438,7 +453,8 @@ function installClaude(configDir, { useSymlink }) {
   const spec = claudeVerifySpec(configDir, {
     skillDirs: shippedSkillDirs(),
     sharedFiles: readSharedCoreFiles(),
-    hookFiles: HOOK_FILES.filter((f) => !CLAUDE_HOOK_EXCLUDE.includes(f)),
+    hookFiles: claudeShippedHooks(),
+    entrypointFiles: claudeEntrypoints(),
     hookLibFiles: HOOK_LIB_FILES,
     env: process.env,
     home: os.homedir(),
@@ -653,7 +669,7 @@ function installCodex(configDir, { useSymlink }) {
   // Migration: strip a pre-#169 search-guard registration. Its target is
   // always gone now (search-guard is never copied to Codex), so a prior
   // install's stale entry would otherwise fail the post-install check below.
-  stripHook(h, 'PreToolUse', 'trailhead-search-guard.js');
+  stripLegacyBashGuards(h);
   for (const e of codexHookEntries(L.hooksScriptsDir)) addHook(h, e.event, e.matcher, e.command);
   writeJSON(L.hooksJson, h);
 
@@ -709,7 +725,8 @@ function installCodex(configDir, { useSymlink }) {
   const spec = codexVerifySpec(configDir, {
     skillDirs: shippedSkillDirs(),
     sharedFiles: readSharedCoreFiles(),
-    hookFiles: HOOK_FILES.filter((f) => !CODEX_HOOK_EXCLUDE.includes(f)),
+    hookFiles: codexShippedHooks(),
+    entrypointFiles: codexEntrypoints(),
     hookLibFiles: HOOK_LIB_FILES,
     env: process.env,
     home: os.homedir(),
@@ -772,16 +789,11 @@ function uninstallCodex(configDir) {
   // settings.json flags alone.
   if (fs.existsSync(L.hooksJson)) {
     const h = readJSON(L.hooksJson);
-    stripHook(h, 'PreToolUse', 'trailhead-commit-guard.js');
-    stripHook(h, 'PreToolUse', 'trailhead-secret-guard.js');
-    stripHook(h, 'PreToolUse', 'trailhead-install-guard.js');
-    // search-guard is no longer projected to Codex (#169: it is
-    // Claude-Code-specific), so it is never registered by a current install;
-    // this strip is retained only to clean up a stale entry left by a
-    // pre-#169 install that did register it.
-    stripHook(h, 'PreToolUse', 'trailhead-search-guard.js');
+    // The merged Bash guard entry, plus every legacy per-guard registration
+    // (commit, secret, install, body, and the pre-#169 search-guard one).
+    stripHook(h, 'PreToolUse', 'trailhead-bash-guards.js');
+    stripLegacyBashGuards(h);
     stripHook(h, 'PreToolUse', 'trailhead-secret-read-guard.js');
-    stripHook(h, 'PreToolUse', 'trailhead-body-guard.js');
     stripHook(h, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
     stripHook(h, 'Stop', 'trailhead-mockup-link-stop.js');
     stripHook(h, 'SessionStart', 'trailhead-check-update.js');