@marcomigozzi/trailhead 0.5.0 → 0.5.1

package/README.it.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+![trailhead](assets/social-preview.png)
+
 # Trailhead
 
 🇬🇧 [English](README.md) · 🇮🇹 **Italiano**
@@ -24,7 +26,7 @@ Due approcci al lavoro di progetto guidato dagli agenti risolvono ciascuno una m
 
 Lavorando su entrambi, uno schema continuava a ripresentarsi: **usa una mappa e un onboarding in stile Wayfinder per decidere la forma del lavoro, poi un motore in stile GSD per costruire ogni pezzo, senza mai lasciare l'issue tracker.** `trailhead` è quello schema trasformato in un'unica skill, una sua interpretazione autonoma di entrambe le idee anziché un wrapper attorno all'una o all'altra.
 
-> **trailhead è self-contained.** Wayfinder e GSD sono *ispirazione*, non dipendenze. Ogni tecnica che quei sistemi impacchettano come skill separata (grilling, TDD, debugging sistematico, codebase mapping, code review) è **integrata qui come protocollo inline**. Il core di trailhead non invoca nessun'altra skill; i suoi subagent (research, codebase-map, review) usano i subagent nativi dell'host (il tool `Agent` integrato di Claude Code, oppure il toolkit `multi_agent` di Codex). L'unica cosa da installare è trailhead stesso. C'è un'unica eccezione opt-in: la modalità mockup hosted. Quando abilitata, `claude.ai/design` costruisce il mockup su claude.ai/design (solo Claude): per default una canvas (la skill integrata `/design` pubblicata come Artifact, o un progetto creato a mano nella web app, non guidato da MCP) o, per una libreria di componenti condivisa, un progetto design-system tramite DesignSync (l'MCP `claude-design` più la skill `/design-sync`, l'unica superficie guidata da MCP). Una terza modalità, `stitch`, usa l'MCP Google Stitch e funziona sia su **Claude Code sia su Codex**, quindi è l'opzione hosted cross-host. Se l'MCP della modalità configurata non è connesso, offre un'installazione una tantum e ripiega sui mockup su disco locale se rifiuti; su Codex, dove `claude.ai/design` non è disponibile, offre di passare a `stitch` prima di ripiegare sul disco locale.
+> **trailhead è self-contained** nel senso che ha **zero dipendenze da plugin esterni**: gli agent di trailhead e i built-in dell'host vanno bene, e nessun'altra skill o plugin è richiesta. Wayfinder e GSD sono *ispirazione*, non dipendenze. Ogni tecnica che quei sistemi impacchettano come skill separata (grilling, TDD, debugging sistematico, codebase mapping, code review) è **integrata qui come protocollo inline**. Il core di trailhead non invoca nessun'altra skill; ogni tecnica del motore dispatcha al **proprio agent `trailhead-*`** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, più `trailhead-fix` e `trailhead-codebase-map`), scritto una volta come file `agents/trailhead-*.md` versionato e **proiettato su ogni host** (su Codex diventa `~/.codex/agents/trailhead-*.toml` generato dalla stessa sorgente). Questi agent sono **thin** (identità + tool policy + un modello guidato dalla config, con il protocollo della tecnica iniettato allo spawn) e girano sul toolkit di subagent nativo dell'host (il tool `Agent` integrato di Claude Code, oppure il toolkit `multi_agent` di Codex). L'unica cosa da installare è trailhead stesso. C'è un'unica eccezione opt-in: la modalità mockup hosted. Quando abilitata, `claude.ai/design` costruisce il mockup su claude.ai/design (solo Claude): per default una canvas (la skill integrata `/design` pubblicata come Artifact, o un progetto creato a mano nella web app, non guidato da MCP) o, per una libreria di componenti condivisa, un progetto design-system tramite DesignSync (l'MCP `claude-design` più la skill `/design-sync`, l'unica superficie guidata da MCP). Una terza modalità, `stitch`, usa l'MCP Google Stitch e funziona sia su **Claude Code sia su Codex**, quindi è l'opzione hosted cross-host. Se l'MCP della modalità configurata non è connesso, offre un'installazione una tantum e ripiega sui mockup su disco locale se rifiuti; su Codex, dove `claude.ai/design` non è disponibile, offre di passare a `stitch` prima di ripiegare sul disco locale.
 
 Le scelte di design che ne derivano:
 
@@ -73,7 +75,7 @@ Su **Codex CLI** (`--codex`) proietta una skill nativa Codex invocata come **`$t
 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).
 
 ### Dopo l'installazione
-Riavvia o ricarica il tuo agente così i comandi si registrano, poi esegui **`/trailhead`** per iniziare (smart entry), o `/trailhead:new "<idea>"` per tracciare una mappa. **Su Codex** la superficie è `$trailhead`: esegui **`$trailhead`** per lo smart entry, `$trailhead new "<idea>"` per tracciare, o una skill per-verbo `$trailhead-<verb>`. Nota: una volta installato, l'**hook di commit guard gira a ogni `git commit`** (imponendo i Conventional Commits e bloccando `Co-Authored-By`); disabilita gli hook del plugin nelle impostazioni se non lo vuoi. In ogni caso trailhead è self-contained: nessun'altra skill o plugin è richiesta, niente preflight, niente version drift.
+Riavvia o ricarica il tuo agente così i comandi si registrano, poi esegui **`/trailhead`** per iniziare (smart entry), o `/trailhead:new "<idea>"` per tracciare una mappa. **Su Codex** la superficie è `$trailhead`: esegui **`$trailhead`** per lo smart entry, `$trailhead new "<idea>"` per tracciare, o una skill per-verbo `$trailhead-<verb>`. Nota: una volta installato, l'**hook di commit guard gira a ogni `git commit`** (imponendo i Conventional Commits e bloccando `Co-Authored-By`); disabilita gli hook del plugin nelle impostazioni se non lo vuoi. In ogni caso trailhead è self-contained: nessuna skill o plugin esterna è richiesta, niente preflight, niente version drift.
 
 ---
 

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+![trailhead](assets/social-preview.png)
+
 # Trailhead
 
 🇬🇧 **English** · 🇮🇹 [Italiano](README.it.md)
@@ -24,7 +26,7 @@ Two approaches to agent-driven project work each nail one half of the problem:
 
 Working across both, one pattern kept recurring: **use a Wayfinder-style map and onboarding to decide the shape of the work, then a GSD-style engine to build each piece, without ever leaving the issue tracker.** `trailhead` is that pattern made into a set of cohesion-clustered skills over a shared core, its own self-contained take on both ideas rather than a wrapper around either.
 
-> **trailhead is self-contained.** Wayfinder and GSD are *inspiration*, not dependencies. Every technique those systems package as a separate skill (grilling, TDD, systematic debugging, codebase mapping, code review) is **built in here as an inline protocol**. trailhead's core invokes no other skill; its subagents (research, codebase-map, review) use the host's native subagents (Claude Code's built-in `Agent` tool, or Codex's `multi_agent` toolkit). The only thing to install is trailhead itself. There is one opt-in exception: hosted mockup mode. When enabled, `claude.ai/design` builds the mockup on claude.ai/design (Claude only): by default a canvas (the built-in `/design` skill published as an Artifact, or a hand-made web-app project, not MCP-driven) or, for a shared component library, a design-system project via DesignSync (the `claude-design` MCP plus the `/design-sync` skill, the only MCP-driven surface). A third mode, `stitch`, uses the Google Stitch MCP and works on **both Claude Code and Codex**, so it's the cross-host hosted option. If a hosted mode's MCP isn't connected, it offers a one-time install and falls back to local-disk mockups if you decline; on Codex, where `claude.ai/design` isn't available, it offers to switch to `stitch` before falling to local disk.
+> **trailhead is self-contained** in the sense that it has **zero external-plugin dependencies**: trailhead-owned agents and the host's built-ins are fine, and no other skill or plugin is required. Wayfinder and GSD are *inspiration*, not dependencies. Every technique those systems package as a separate skill (grilling, TDD, systematic debugging, codebase mapping, code review) is **built in here as an inline protocol**. trailhead's core invokes no other skill; each engine technique dispatches to **trailhead's own `trailhead-*` agent** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, plus `trailhead-fix` and `trailhead-codebase-map`), authored once as a committed `agents/trailhead-*.md` file and **projected to each host** (Codex gets `~/.codex/agents/trailhead-*.toml` generated from that same source). These agents are **thin** (identity + tool policy + a config-driven model, with the technique protocol injected at spawn) and run on the host's native subagent toolkit (Claude Code's built-in `Agent` tool, or Codex's `multi_agent` toolkit). The only thing to install is trailhead itself. There is one opt-in exception: hosted mockup mode. When enabled, `claude.ai/design` builds the mockup on claude.ai/design (Claude only): by default a canvas (the built-in `/design` skill published as an Artifact, or a hand-made web-app project, not MCP-driven) or, for a shared component library, a design-system project via DesignSync (the `claude-design` MCP plus the `/design-sync` skill, the only MCP-driven surface). A third mode, `stitch`, uses the Google Stitch MCP and works on **both Claude Code and Codex**, so it's the cross-host hosted option. If a hosted mode's MCP isn't connected, it offers a one-time install and falls back to local-disk mockups if you decline; on Codex, where `claude.ai/design` isn't available, it offers to switch to `stitch` before falling to local disk.
 
 The design choices that fall out of it:
 
@@ -73,7 +75,7 @@ On **Codex CLI** (`--codex`) it projects a native Codex skill invoked as **`$tra
 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).
 
 ### After installing
-Restart or reload your agent so the commands register, then run **`/trailhead`** to start (smart entry), or `/trailhead:new "<idea>"` to chart a map. **On Codex** the surface is `$trailhead` instead: run **`$trailhead`** for smart entry, `$trailhead new "<idea>"` to chart, or a per-verb `$trailhead-<verb>` skill. Note: once installed, the **commit guard hook runs on every `git commit`** (enforcing Conventional Commits and blocking `Co-Authored-By`); disable the plugin's hooks in settings if you don't want that. Either way trailhead is self-contained: no other skill or plugin is required, no preflight, no version drift.
+Restart or reload your agent so the commands register, then run **`/trailhead`** to start (smart entry), or `/trailhead:new "<idea>"` to chart a map. **On Codex** the surface is `$trailhead` instead: run **`$trailhead`** for smart entry, `$trailhead new "<idea>"` to chart, or a per-verb `$trailhead-<verb>` skill. Note: once installed, the **commit guard hook runs on every `git commit`** (enforcing Conventional Commits and blocking `Co-Authored-By`); disable the plugin's hooks in settings if you don't want that. Either way trailhead is self-contained: no external skill or plugin is required, no preflight, no version drift.
 
 ---
 

package/bin/lib/codex-projection.js

@@ -101,7 +101,7 @@ Codex has a subagent toolkit: the multi_agent tools (\`spawn_agent\`, \`send_inp
 
 **Never surrender the session to one open-ended \`wait_agent\`; poll instead.** \`wait_agent\` blocks until the subagent returns, so a single unconditional \`wait_agent\` on a long or stalling subagent freezes the whole session with nothing to check: this is the review / plan-review hang. Collect every delegated subagent through a **bounded wait in a poll loop**, not one open-ended blocking call. Give \`wait_agent\` a short timeout (30 to 60s); on each timeout, report a one-line "still running" progress note and loop again, so the session stays responsive and can be checked or interrupted between polls. The two **review** steps, **Code review** and **Cross-AI plan review**, always run this way: backgrounding and polling them (never a blind \`wait_agent\`) is the engine's hard cross-host default, not merely the case where it matters most. They are also the longest quiet activities in the cycle (a full-diff adversarial review, or an external CLI) and the ones most often seen to hang. If your Codex build's \`wait_agent\` exposes no timeout, poll the agent's status/output at intervals instead of blocking, or run the review as a **background job** and check back on it at intervals; the rule is the same either way. When several subagents run in parallel, poll them as a set, a bounded wait cycling across the outstanding handles, reporting which are still running.
 
-**Per-technique model pins (\`agent_type\` dispatch).** When \`models.codex.*\` is set, the installer projects one \`~/.codex/agents/trailhead-<technique>.toml\` per key (that technique's OpenAI model, plus its reasoning effort) and enables \`features.multi_agent_v2\`, so Codex exposes a per-technique agent registry. Detect that registry at runtime by introspecting the visible \`spawn_agent\` tool schema (GSD-style, never a config read): if its parameters expose an \`agent_type\` field, \`multi_agent_v2\` is live, so spawn each delegated activity as \`spawn_agent(agent_type="trailhead-<technique>", reasoning_effort=…)\` (\`trailhead-plan\` for the Plan step, \`trailhead-execute\` for Execute, likewise research/review/debug), which routes it onto its pinned model. If the \`spawn_agent\` schema exposes NO \`agent_type\` field (only base multi_agent v1 is present, or no \`models.codex.*\` pin was projected), spawn with base \`spawn_agent\` and the subagents inherit the one session model. Trust the tool surface you actually see and degrade gracefully: \`multi_agent_v2\` is still under development upstream, so v1 stays a supported runtime.
+**Per-technique agent registry (\`agent_type\` dispatch).** The installer always projects all 7 committed trailhead agents as \`~/.codex/agents/trailhead-<technique>.toml\` (one per technique) and enables \`features.multi_agent_v2\`, so Codex always exposes a per-technique agent registry. A TOML whose technique has a \`models.codex.<key>\` pin set carries that OpenAI model (plus its reasoning effort); every other TOML — an unpinned keyed technique, or one of the 2 keyless agents — is pin-less and its subagent inherits the session model. Detect the registry at runtime by introspecting the visible \`spawn_agent\` tool schema (GSD-style, never a config read): if its parameters expose an \`agent_type\` field, spawn each delegated activity as \`spawn_agent(agent_type="trailhead-<technique>", reasoning_effort=…)\` (\`trailhead-plan\` for the Plan step, \`trailhead-execute\` for Execute, likewise research/review/debug, plus the 2 keyless \`trailhead-fix\` and \`trailhead-codebase-map\` for the Fix and Codebase-map steps), which routes it onto that technique's pinned model when one is set, or the session model otherwise. If the \`spawn_agent\` schema exposes NO \`agent_type\` field at all (a Codex build with only base multi_agent v1), spawn with base \`spawn_agent\` and the subagents inherit the one session model. Trust the tool surface you actually see and degrade gracefully: \`multi_agent_v2\` is still under development upstream, so v1 stays a supported runtime.
 
 \`config.models.*\` (Claude model ids) still cannot take effect here regardless: Codex's subagent model registry is OpenAI-only, so a Claude id cannot run and those keys collapse to the session model. The honoured namespace on Codex is \`models.codex.*\` (above); the one-time models-collapse notice still applies while a stray \`models.*\` is set and \`models.codex.*\` is empty.
 
@@ -109,7 +109,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 and secret-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, and check-update as a \`SessionStart\` hook. 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 and install-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, and check-update as a \`SessionStart\` hook. 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 -> local disk
 The \`claude.ai/design\` mockup mode (DesignSync: the \`claude_design\` MCP + the \`/design-sync\` skill) does not exist on Codex, so it **collapses to local-disk mockups** here: whatever \`config.design\` says, the Prototype technique's \`disk\` path is the only one available. Produce a throwaway static HTML mockup next to the code, link it from the ticket, and never attempt DesignSync / claude.ai/design on Codex (there is no \`claude_design\` MCP or \`/design-sync\` skill to call). \`config.design.approval\` still applies unchanged: \`explicit\` waits for the user's go-ahead before any UI code, \`auto\` surfaces the mockup and proceeds.
@@ -165,47 +165,56 @@ policy:
 `;
 }
 
-// --- CODEX_AGENT_TECHNIQUES ------------------------------------------------
-// Metadata for the 5 trailhead activities that can get a per-technique Codex
-// custom-agent TOML: a short UI description and the developer_instructions
-// that steer that subagent on Codex, pointing back at the projected skill.
-const CODEX_AGENT_TECHNIQUES = Object.freeze({
-  plan: Object.freeze({
-    description: "trailhead planning subagent: produces a build ticket's PLAN (steps, seams, files, verification)",
-    developerInstructions: "You are trailhead's planning subagent on Codex. Produce the PLAN for a trailhead build ticket: the steps, the seams, the files touched, and the verification criteria, applying TDD per the ticket's config. Follow the Plan step and the referenced technique in the trailhead skill at ~/.codex/skills/trailhead. Return the plan; do not implement.",
-  }),
-  execute: Object.freeze({
-    description: 'trailhead execute subagent: implements a PLAN with atomic commits',
-    developerInstructions: "You are trailhead's execute subagent on Codex. Implement the approved PLAN for a trailhead build ticket with atomic conventional commits, each carrying a Refs: #<n> trailer for the ticket, following the repo's conventions. Follow the Execute step in the trailhead skill at ~/.codex/skills/trailhead.",
-  }),
-  research: Object.freeze({
-    description: 'trailhead research subagent: gathers a decision-ready fact from primary sources',
-    developerInstructions: "You are trailhead's research subagent on Codex. Gather the decision-ready fact a ticket waits on from primary sources, per the Research technique in the trailhead skill at ~/.codex/skills/trailhead. Record findings with citations; change no product code beyond the research artifact.",
-  }),
-  review: Object.freeze({
-    description: "trailhead code-review subagent: adversarially reviews a ticket's diff",
-    developerInstructions: "You are trailhead's code-review subagent on Codex. Review the ticket's diff adversarially on the trailhead Code review technique's axes, verifying each finding before reporting, per the trailhead skill at ~/.codex/skills/trailhead. Do not defer to a convention or a settled-decision memory.",
-  }),
-  debug: Object.freeze({
-    description: "trailhead debug subagent: finds a defect's root cause by the scientific method",
-    developerInstructions: "You are trailhead's debug subagent on Codex. Find the root cause of the ticket's defect by the scientific method (reproduce, localise, falsifiable hypotheses, confirm, verify), per the Debug technique in the trailhead skill at ~/.codex/skills/trailhead.",
-  }),
+// --- CODEX_AGENT_NAME_ALIASES / codexTechniqueKey ---------------------------
+// The 7 committed agent sources (plugins/trailhead/agents/trailhead-*.md) are
+// keyed by their trailhead-<name>.md filename stem. Two of those stems don't
+// match the models.codex.<key> pin namespace, so alias them; every other
+// agent's key is just its name with the trailhead- prefix stripped.
+const CODEX_AGENT_NAME_ALIASES = Object.freeze({
+  'trailhead-executor': 'execute',
+  'trailhead-code-review': 'review',
 });
 
+function codexTechniqueKey(name) {
+  return CODEX_AGENT_NAME_ALIASES[name] || String(name).replace(/^trailhead-/, '');
+}
+
+// --- MODEL_KEYS --------------------------------------------------------------
+// The 5 pinnable technique keys, mirroring the models.codex.* namespace. The
+// other 2 committed agents (fix, codebase-map) have no pin key and are always
+// projected pin-less (session model).
+const MODEL_KEYS = new Set(['plan', 'execute', 'research', 'review', 'debug']);
+
 // --- codexAgentToml ---------------------------------------------------------
-// Render one Codex custom-agent TOML. model_reasoning_effort is emitted only
-// when effort is a non-empty string. developer_instructions is a TOML
-// multi-line literal block ('''...'''); a stray ''' inside the text (none of
-// ours has one, but be safe) is neutralised so it can't close the block early.
+// Render one Codex custom-agent TOML. When `model` is empty/absent, the TOML
+// is pin-less: no `model =` line (and so no model_reasoning_effort either),
+// so the subagent inherits the session model. When `model` is present,
+// model_reasoning_effort is emitted only when effort is a non-empty string.
+// developer_instructions is a TOML multi-line literal block ('''...'''); a
+// stray ''' inside the text (none of ours has one, but be safe) is
+// neutralised so it can't close the block early. The basic-string fields
+// (name/description/model/effort) are escaped so a stray " or \ in a source
+// value (description comes from the agent .md frontmatter) can't break the TOML.
+function tomlBasicString(s) {
+  return String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+}
+
 function codexAgentToml({ name, description, developerInstructions, model, effort }) {
   const safeInstructions = String(developerInstructions).split("'''").join("''");
   const lines = [
-    `name = "${name}"`,
-    `description = "${description}"`,
-    `model = "${model}"`,
+    `name = "${tomlBasicString(name)}"`,
+    `description = "${tomlBasicString(description)}"`,
   ];
-  if (typeof effort === 'string' && effort.trim() !== '') {
-    lines.push(`model_reasoning_effort = "${effort}"`);
+  if (typeof model === 'string' && model.trim() !== '') {
+    lines.push(`model = "${tomlBasicString(model)}"`);
+    if (typeof effort === 'string' && effort.trim() !== '') {
+      lines.push(`model_reasoning_effort = "${tomlBasicString(effort)}"`);
+    }
   }
   lines.push(`developer_instructions = '''\n${safeInstructions}\n'''`);
   return lines.join('\n') + '\n';
@@ -214,43 +223,54 @@ function codexAgentToml({ name, description, developerInstructions, model, effor
 // --- codexAgentTomlPlan ------------------------------------------------------
 // Given the resolved models.codex config (a plain object like
 // { plan: "gpt-5.6-terra", execute: { model: "gpt-5.6-sol", effort: "high" } },
-// or null/undefined/{}), return the set of trailhead-<technique>.toml writes
-// the installer should make. Skips unknown keys and empty values. Iterates
-// CODEX_AGENT_TECHNIQUES in declaration order (not the config's key order) so
-// the write order is deterministic regardless of how the config was authored.
-function codexAgentTomlPlan(codexHome, codexModels) {
+// or null/undefined/{}) and `agentDefs` (the array from the installer's
+// readAgentDefs(): every committed plugins/trailhead/agents/trailhead-*.md,
+// each { name, description, tools, body }), return the set of
+// trailhead-<technique>.toml writes the installer should make: ONE per agent,
+// uniformly (all 7 project, always). A keyed agent (plan/execute/research/
+// review/debug) carries its models.codex.<key> pin when set, else is
+// pin-less; the 2 keyless agents (fix, codebase-map) are always pin-less.
+// Iterates agentDefs in the given order (readAgentDefs sorts by name) so the
+// write order is deterministic.
+function codexAgentTomlPlan(codexHome, codexModels, agentDefs) {
   const models = codexModels && typeof codexModels === 'object' ? codexModels : {};
   const dir = codexLayout(codexHome).codexAgentsDir;
+  const defs = Array.isArray(agentDefs) ? agentDefs : [];
   const writes = [];
 
-  for (const technique of Object.keys(CODEX_AGENT_TECHNIQUES)) {
-    const raw = models[technique];
-    if (raw == null) continue;
+  for (const def of defs) {
+    const key = codexTechniqueKey(def.name);
+    const name = `trailhead-${key}`;
+    const filePath = path.join(dir, `${name}.toml`);
 
     let model = null;
     let effort = null;
-    if (typeof raw === 'string') {
-      if (raw.trim() !== '') model = raw;
-    } else if (typeof raw === 'object') {
-      const m = typeof raw.model === 'string' ? raw.model : '';
-      if (m.trim() !== '') {
-        model = m;
-        effort = typeof raw.effort === 'string' ? raw.effort : null;
+    if (MODEL_KEYS.has(key) && models[key] != null) {
+      const raw = models[key];
+      if (typeof raw === 'string') {
+        if (raw.trim() !== '') model = raw;
+      } else if (typeof raw === 'object') {
+        const m = typeof raw.model === 'string' ? raw.model : '';
+        if (m.trim() !== '') {
+          model = m;
+          effort = typeof raw.effort === 'string' ? raw.effort : null;
+        }
       }
     }
-    if (!model) continue;
 
-    const meta = CODEX_AGENT_TECHNIQUES[technique];
-    const name = `trailhead-${technique}`;
-    const filePath = path.join(dir, `${name}.toml`);
+    const lead = 'You are running on Codex CLI; the trailhead skill lives at ~/.codex/skills/trailhead.\n\n';
+    const developerInstructions = lead + convertToCodex(String(def.body || '')).trim();
+
     const content = codexAgentToml({
       name,
-      description: meta.description,
-      developerInstructions: meta.developerInstructions,
+      // Route the description through convertToCodex too (like the body), and
+      // default a missing frontmatter description to '' rather than "undefined".
+      description: convertToCodex(String(def.description || '')),
+      developerInstructions,
       model,
       effort,
     });
-    writes.push({ technique, name, path: filePath, content });
+    writes.push({ technique: key, name, path: filePath, content });
   }
 
   return { writes };
@@ -345,6 +365,7 @@ function codexHookEntries(hooksScriptsDir) {
   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: 'PostToolUse', matcher: 'Bash', command: cmd('trailhead-issue-injection-scanner.js') },
     { event: 'SessionStart', matcher: '', command: cmd('trailhead-check-update.js') },
   ];

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

@@ -143,11 +143,13 @@ ok('codexVerbSkillPlan: null verbs yields nothing', codexVerbSkillPlan('/c', nul
 
 // --- codexHookEntries ---
 const entries = codexHookEntries('/h');
-ok('codexHookEntries returns 4 entries', Array.isArray(entries) && entries.length === 4);
+ok('codexHookEntries returns 5 entries', Array.isArray(entries) && entries.length === 5);
 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: injection-scanner is PostToolUse/Bash', entries.some((e) =>
   e.event === 'PostToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-issue-injection-scanner.js')));
 ok('codexHookEntries: check-update is SessionStart', entries.some((e) =>
@@ -198,24 +200,110 @@ ok('codexAgentToml without effort omits model_reasoning_effort', (() => {
   });
   return out.includes('model = "gpt-5.6-terra"') && !out.includes('model_reasoning_effort');
 })());
+ok('codexAgentToml with no model emits a pin-less TOML (no model line, no effort line, keeps the rest)', (() => {
+  const out = codexAgentToml({
+    name: 'trailhead-fix',
+    description: 'desc',
+    developerInstructions: 'fix the thing',
+    model: null,
+    effort: null,
+  });
+  return out.includes('name = "trailhead-fix"') &&
+    out.includes('description = "desc"') &&
+    !/^model = /m.test(out) &&
+    !out.includes('model_reasoning_effort') &&
+    out.includes("developer_instructions = '''") &&
+    out.includes('fix the thing');
+})());
+
+ok('codexAgentToml escapes a " and \\ in name/description so the TOML stays valid', (() => {
+  const out = codexAgentToml({
+    name: 'trailhead-plan',
+    description: 'has a "quote" and a back\\slash',
+    developerInstructions: 'body',
+    model: null,
+    effort: null,
+  });
+  // The emitted basic string must carry escaped forms, never a raw " that
+  // would prematurely close the TOML string.
+  return out.includes('description = "has a \\"quote\\" and a back\\\\slash"');
+})());
 
 // --- codexAgentTomlPlan ---
-ok('codexAgentTomlPlan: string value produces one write with the right path/name/model', (() => {
-  const plan = codexAgentTomlPlan('/c', { execute: 'gpt-5.6-terra' });
-  return plan.writes.length === 1 &&
-    plan.writes[0].path === '/c/agents/trailhead-execute.toml' &&
-    plan.writes[0].name === 'trailhead-execute' &&
-    plan.writes[0].content.includes('model = "gpt-5.6-terra"');
+// 7-entry stub agentDefs mirroring the real plugins/trailhead/agents/*.md
+// sources: 5 keyed techniques (plan/execute/research/review/debug, whose
+// filenames derive from trailhead-executor -> execute and
+// trailhead-code-review -> review) + 2 always-keyless agents.
+const STUB_AGENT_DEFS = [
+  { name: 'trailhead-plan', description: 'plan desc', tools: 'Read', body: 'Plan body.' },
+  { name: 'trailhead-executor', description: 'execute desc', tools: 'Read, Write', body: 'Execute body.' },
+  { name: 'trailhead-research', description: 'research desc', tools: 'Read', body: 'Research body.' },
+  { name: 'trailhead-code-review', description: 'review desc', tools: 'Read', body: 'Review body.' },
+  { name: 'trailhead-debug', description: 'debug desc', tools: 'Read', body: 'Debug body.' },
+  { name: 'trailhead-fix', description: 'fix desc', tools: 'Read, Write', body: 'Fix body.' },
+  { name: 'trailhead-codebase-map', description: 'map desc', tools: 'Read', body: 'Map body.' },
+];
+
+ok('codexAgentTomlPlan: 7 agentDefs -> 7 writes with only the pinned key carrying a model', (() => {
+  const plan = codexAgentTomlPlan('/c', { execute: 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
+  if (plan.writes.length !== 7) return false;
+  const byName = Object.fromEntries(plan.writes.map((w) => [w.name, w]));
+  const execute = byName['trailhead-execute'];
+  if (!execute || execute.path !== '/c/agents/trailhead-execute.toml') return false;
+  if (!execute.content.includes('model = "gpt-5.6-terra"')) return false;
+  const others = plan.writes.filter((w) => w.name !== 'trailhead-execute');
+  return others.length === 6 && others.every((w) => !/^model = /m.test(w.content));
+})());
+
+ok('codexAgentTomlPlan: keyless trailhead-fix / trailhead-codebase-map are always pin-less', (() => {
+  const plan = codexAgentTomlPlan('/c', { fix: 'gpt-5.6-terra', 'codebase-map': 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
+  const byName = Object.fromEntries(plan.writes.map((w) => [w.name, w]));
+  const fix = byName['trailhead-fix'];
+  const map = byName['trailhead-codebase-map'];
+  return fix && map &&
+    fix.path === '/c/agents/trailhead-fix.toml' && !/^model = /m.test(fix.content) &&
+    map.path === '/c/agents/trailhead-codebase-map.toml' && !/^model = /m.test(map.content);
+})());
+
+ok('codexAgentTomlPlan: empty models object -> 7 pin-less writes (not zero)', (() => {
+  const plan = codexAgentTomlPlan('/c', {}, STUB_AGENT_DEFS);
+  return plan.writes.length === 7 && plan.writes.every((w) => !/^model = /m.test(w.content));
+})());
+
+ok('codexAgentTomlPlan: null models -> 7 pin-less writes (not zero)', (() => {
+  const plan = codexAgentTomlPlan('/c', null, STUB_AGENT_DEFS);
+  return plan.writes.length === 7 && plan.writes.every((w) => !/^model = /m.test(w.content));
+})());
+
+ok('codexAgentTomlPlan: object model value on the execute key carries model + model_reasoning_effort', (() => {
+  const plan = codexAgentTomlPlan('/c', { execute: { model: 'gpt-5.6-sol', effort: 'high' } }, STUB_AGENT_DEFS);
+  const execute = plan.writes.find((w) => w.name === 'trailhead-execute');
+  return execute.content.includes('model = "gpt-5.6-sol"') && execute.content.includes('model_reasoning_effort = "high"');
 })());
-ok('codexAgentTomlPlan: object value includes model + effort', (() => {
-  const plan = codexAgentTomlPlan('/c', { execute: { model: 'gpt-5.6-sol', effort: 'high' } });
-  const c = plan.writes[0].content;
-  return c.includes('model = "gpt-5.6-sol"') && c.includes('model_reasoning_effort = "high"');
+
+ok('codexAgentTomlPlan: a keyed key whose object value has no model stays pin-less', (() => {
+  const plan = codexAgentTomlPlan('/c', { execute: { effort: 'high' } }, STUB_AGENT_DEFS);
+  const execute = plan.writes.find((w) => w.name === 'trailhead-execute');
+  return plan.writes.length === 7 && !/^model = /m.test(execute.content) && !execute.content.includes('model_reasoning_effort');
+})());
+
+ok('codexAgentTomlPlan: description is routed through convertToCodex (host paths rewritten)', (() => {
+  const defs = [{ name: 'trailhead-plan', description: 'see ~/.claude/skills', tools: 'Read', body: 'b' }];
+  const plan = codexAgentTomlPlan('/c', {}, defs);
+  return plan.writes[0].content.includes('description = "see ~/.codex/skills"');
+})());
+
+ok('codexAgentTomlPlan: a missing description renders as an empty string, not "undefined"', (() => {
+  const defs = [{ name: 'trailhead-plan', tools: 'Read', body: 'b' }];
+  const plan = codexAgentTomlPlan('/c', {}, defs);
+  return plan.writes[0].content.includes('description = ""') && !plan.writes[0].content.includes('description = "undefined"');
+})());
+
+ok('codexAgentTomlPlan: empty/undefined agentDefs -> no writes (installer then leaves multi_agent_v2 off)', (() => {
+  return codexAgentTomlPlan('/c', {}, []).writes.length === 0 &&
+    codexAgentTomlPlan('/c', {}).writes.length === 0 &&
+    codexAgentTomlPlan('/c', {}, null).writes.length === 0;
 })());
-ok('codexAgentTomlPlan: empty object -> no writes', codexAgentTomlPlan('/c', {}).writes.length === 0);
-ok('codexAgentTomlPlan: null -> no writes', codexAgentTomlPlan('/c', null).writes.length === 0);
-ok('codexAgentTomlPlan: unknown key skipped', codexAgentTomlPlan('/c', { bogus: 'x' }).writes.length === 0);
-ok('codexAgentTomlPlan: object value with no model is skipped', codexAgentTomlPlan('/c', { execute: { effort: 'high' } }).writes.length === 0);
 
 // --- enableCodexMultiAgentV2Feature ---
 ok('enableCodexMultiAgentV2Feature: dotted form already true -> null',