@marcomigozzi/trailhead 0.16.0 → 0.17.0

package/bin/grill-model-docs.test.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Docs test per #323: Grilling gira su models.grill / trailhead-grill, con la sessione
+// principale come orchestratore HITL. Il protocollo e' scritto una volta (grilling.md);
+// i punti d'ingresso lo richiamano soltanto.
+// Run: node grill-model-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const skills = path.join(root, 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- Parte A: configuration-reference.md e configuration.md --------------------------
+{
+  const ref = read('_shared/configuration-reference.md');
+  const cfg = read('_shared/configuration.md');
+  const lines = ref.split('\n');
+  const rowStart = (prefix) => lines.find((l) => l.startsWith(prefix)) || '';
+  ok('A: models.{...} key-table row lists grill', /^\| `models\.\{[^}]*\bgrill\b[^}]*\}`/.test(rowStart('| `models.{')));
+  ok('A: models.codex.{...} key-table row lists grill', /^\| `models\.codex\.\{[^}]*\bgrill\b[^}]*\}`/.test(rowStart('| `models.codex.{')));
+  ok('A: Models bullet for grill', lines.some((l) => /^- `grill`:/.test(l) && l.includes('Grilling')));
+  ok('A: subagent bullet maps grill to trailhead-grill and says the session keeps asking the user',
+    lines.some((l) => /^- `grill`/.test(l) && l.includes('trailhead-grill') && /session (keeps|still) ask/.test(l)));
+  const header = lines.find((l) => l.startsWith('| profile |')) || '';
+  ok('A: profile table has a grill column', header.includes('| grill |'));
+  const col = (name) => {
+    const idx = header.split('|').map((c) => c.trim()).indexOf('grill');
+    const row = lines.find((l) => l.startsWith(`| **${name}** |`)) || '';
+    return row.split('|').map((c) => c.trim())[idx];
+  };
+  ok('A: grill column reads High strong, Balanced strong, Low standard',
+    col('High') === 'strong' && col('Balanced') === 'strong' && col('Low') === 'standard');
+  ok('A: a profile writes no grill entry, so grill keeps following plan',
+    ref.includes('a profile writes **no `grill` entry**') && ref.includes('keeps following `plan`'));
+  ok('A: the key rows say an unset grill follows plan',
+    rowStart('| `models.{').includes('unset `grill` follows `plan`') && rowStart('| `models.codex.{').includes('unset `grill` follows `models.codex.plan`'));
+  ok('A: Models bullet says unset grill is the same model as plan', lines.some((l) => /^- `grill`:/.test(l) && l.includes('Unset, it uses the same model as `plan`')));
+  ok('A: the unset-default paragraph names the grill exception',
+    ref.includes('the one exception is `grill`: unset, it follows the resolved `models.plan`'));
+  ok('A: Manual path offers grill with "same as plan (Recommended)" first, leaving the key unset',
+    ref.includes('**same as plan (Recommended)** as the first option') && ref.includes('leaves `models.grill` unset') &&
+    ref.includes('leaves `models.codex.grill` unset'));
+  ok('A: a layer that sets plan but not grill implies grill = plan before the merge',
+    ref.includes('a config layer that sets `plan` but not `grill` implicitly sets `grill` to that `plan` for that layer, before the project-over-global merge'));
+  ok('A: existing configs without grill need no action or notice',
+    ref.includes('An existing config with no `grill` key grills on its `plan` model with no action and no notice'));
+  const advanced = lines.filter((l) => l.includes('behind an "Advanced" option') || l.includes('behind Advanced'));
+  ok('A: Advanced lists name grill for Claude and Codex', advanced.length === 2 && advanced.every((l) => l.includes('`grill`')));
+  const everything = lines.find((l) => l.startsWith('**Everything else runs in the main session')) || '';
+  ok('A: Everything else paragraph no longer lists grilling', everything.length > 0 && !/grilling/i.test(everything.split("That's deliberate")[0]));
+  ok('A: Codex sentence (unset inherits, profile or pin brings strong, equal pin runs inline)',
+    /unset `models\.codex\.grill` follows `models\.codex\.plan` when that is pinned/.test(ref) &&
+    ref.includes('else inherits the session model') && ref.includes('an equal pin (same model as the session'));
+  ok('A: a spawn gets the family, not the exact version', ref.includes('A dispatched grill is guaranteed the family of the resolved id, not its exact version'));
+  ok('A: configuration.md names the grill exception to the Balanced default', cfg.includes('except `grill`, which follows `plan`'));
+  ok('A: configuration.md lists grill in the subagent list', /`research`, `review`, `debug`, `verify`, `codebase-map`, `grill`/.test(cfg));
+}
+
+// --- Parte B: grilling.md "Who runs a round" e techniques.md ---------------------------
+{
+  const grilling = read('_shared/techniques/grilling.md');
+  const techniques = read('_shared/techniques.md');
+  const at = grilling.indexOf('\n## Who runs a round');
+  ok('B: grilling.md has a Who runs a round section', at !== -1);
+  const sec = at === -1 ? '' : grilling.slice(at);
+  const has = (...needles) => needles.every((n) => sec.includes(n));
+  const gateAt = grilling.indexOf('**First, before any question: route the round.**');
+  const firstBullet = grilling.indexOf('\n- **Map the decision as a tree.**');
+  ok('B: the routing gate exists and precedes the first round bullet', gateAt !== -1 && firstBullet !== -1 && gateAt < firstBullet);
+  const gate = gateAt === -1 ? '' : grilling.slice(gateAt, firstBullet);
+  ok('B: the gate runs model-route.js grill --session with the session full model id and obeys route',
+    gate.includes('model-route.js grill --session <your full model id> <project root>') && gate.includes('obey its `route`'));
+  ok('B: the gate says where the model id comes from and when to pass unknown',
+    gate.includes('system prompt or environment') && gate.includes('The exact model ID is') && gate.includes('pass `unknown` only if it is truly absent'));
+  ok('B: the gate forbids hand decisions', gate.includes('Never decide inline versus dispatch by hand') && gate.includes('never skip the helper') && gate.includes('never read the config yourself'));
+  ok('B: on dispatch the session does not write the questions and relays the report',
+    gate.includes('you do not write the questions yourself') && gate.includes('spawn `agent` with model `alias`') && gate.includes('relay its report'));
+  ok('B: the gate points at Who runs a round and exempts the dispatched agent', gate.includes('**Who runs a round**') && gate.includes('If you are the `trailhead-grill` agent, skip this gate'));
+  ok('B: the route call, with --session-effort and unknown',
+    has('model-route.js grill --session', '--session-effort', 'unknown', '--no-subagents', '--host codex'));
+  ok('B: the helper is found with the same two-path lookup as model-defaults-review.js',
+    has('../../hooks/lib/', '../trailhead/hooks/lib/', 'model-defaults-review.js'));
+  ok('B: a context-window suffix on the session id is documented as ignored', has('a trailing `[...]` suffix such as `[1m]` is ignored'));
+  ok('B: the per-layer implicit grill rule', has('a config layer that sets `plan` but not `grill` implicitly sets `grill` to that `plan` for that layer, before the project-over-global merge'));
+  ok('B: an unset models.grill follows models.plan', has('`models.grill` unset follows `models.plan`'));
+  ok('B: use its agent and alias verbatim', has('use its `agent` and `alias` verbatim'));
+  ok('B: route inline with the suggest line', has('`route: inline`', '`suggest`', 'suggesting the user switch the session'));
+  ok('B: an unregistered agent runs inline', has('not registered', 'inline'));
+  ok('B: the report is checked with --technique grill', has('--technique grill'));
+  ok('B: the relay never answers on the user\'s behalf', has('relay', 'Never answer on the user\'s behalf', 'never proceed on silence'));
+  ok('B: re-dispatch with the full state', has('re-dispatch with the full state'));
+  ok('B: the orchestrator holds the review cap', has('The orchestrator caps reviews at two', 'accepted risk'));
+  ok('B: the apply/amend/keep menu is the orchestrator\'s', has('apply', 'amend', 'keep', 'AskUserQuestion'));
+  ok('B: the family-not-version note', has('the family of the resolved id, not its exact version'));
+  ok('B: an inline round writes no report', has('An inline round writes no report'));
+  ok('B: Codex semantics', has('unset `models.codex.grill` follows `models.codex.plan` when that is pinned', 'else inherits the session model', 'equal to the session model'));
+  ok('B: the protocol bullets above stay the agent\'s protocol', grilling.indexOf('Holistic review before the final confirmation') < at);
+
+  ok('B: grilling.md states that trailhead-grill output is always the report',
+    has('When it runs as `trailhead-grill`, its output is always the report', 'never asks the user live and never shows a menu'));
+  const agent = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'agents', 'trailhead-grill.md'), 'utf8');
+  ok('B: the agent follows the round bullets and its return contract, not the orchestrator section',
+    agent.includes('round bullets') && agent.includes('Return contract') && !agent.includes('Who runs a round'));
+
+  const dispatch = techniques.split('\n')[4] || '';
+  ok('B: techniques.md dispatch list maps Grilling to trailhead-grill', /Grilling → `trailhead-grill`/.test(dispatch));
+  ok('B: techniques.md read-only list includes trailhead-grill', /\*\*read-only\*\*[^)]*`trailhead-grill`/.test(dispatch));
+  const row = techniques.split('\n').find((l) => l.startsWith('| **Grilling** |')) || '';
+  ok('B: the Grilling index row names models.grill', row.includes('`models.grill`'));
+}
+
+// --- Parte C: i punti d'ingresso puntano a "Who runs a round" per nome -----------------
+{
+  const POINTER = 'Who runs a round';
+  const lineWith = (text, needle) => text.split('\n').find((l) => l.includes(needle)) || '';
+  const points = (label, line) => ok(`C: ${label} points at ${POINTER} with the imperative routing wording`, line.length > 0 && line.includes(POINTER) && line.includes('grilling.md') && line.includes('first run the routing step at the top of'));
+  const chart = read('trailhead-chart/SKILL.md');
+  const standalone = chart.slice(chart.indexOf('## Standalone grill'));
+  points('chart SKILL.md Standalone grill', lineWith(standalone, 'Run a standalone **Grilling**'));
+  const charting = read('trailhead-chart/references/charting.md');
+  points('charting.md Mode 1 Name the destination', lineWith(charting, '1. **Name the destination.**'));
+  points('charting.md Mode 1 Map the frontier', lineWith(charting, '2. **Map the frontier.**'));
+  points('charting.md Mode 1-bis Map the frontier of the remainder', lineWith(charting, '4. **Map the frontier of the remainder**'));
+  points('charting.md Mode 1-bis Name the destination of the remaining stretch', lineWith(charting, '2. **Name the destination of the remaining stretch.**'));
+  const engines = read('trailhead-work/references/ticket-engines.md');
+  points('ticket-engines.md build Discuss', lineWith(engines, '1. **Discuss**: **never auto-grill.**'));
+  points('ticket-engines.md Plan needs_input grill option', lineWith(engines, 'needs_input` -> ask the user the `questions:`'));
+  ok('C: the Plan needs_input pointer is about opting to grill the planner questions',
+    /opts? to grill/.test(lineWith(engines, 'needs_input` -> ask the user the `questions:`')));
+  points('ticket-engines.md decision Converge', lineWith(engines, '2. **Converge.**'));
+  const work = read('trailhead-work/SKILL.md');
+  points('work SKILL.md quick Grill only if needed', lineWith(work, '- **Grill only if needed** (Discuss)'));
+}
+
+// --- Parte D: README e README.it.md ---------------------------------------------------
+{
+  for (const file of ['README.md', 'README.it.md']) {
+    const text = fs.readFileSync(path.join(root, file), 'utf8');
+    const lines = text.split('\n');
+    const row = (prefix) => lines.find((l) => l.startsWith(prefix)) || '';
+    ok(`D: ${file} models.{...} row lists grill`, /^\| `models\.\{[^}]*codebase-map,grill\}`/.test(row('| `models.{')));
+    ok(`D: ${file} models.codex.{...} row lists grill`, /^\| `models\.codex\.\{[^}]*codebase-map,grill\}`/.test(row('| `models.codex.{')));
+    ok(`D: ${file} Models bullets carry a grill bullet`, lines.some((l) => /^- `grill`/.test(l) && l.includes('trailhead-grill')));
+    ok(`D: ${file} no longer says grilling runs on the session model`,
+      !/charting, grilling/.test(text));
+    ok(`D: ${file} says grill follows plan when unset`, lines.some((l) => /^- `grill`/.test(l) && l.includes('`plan`') && /unset|non impostat/.test(l)));
+  ok(`D: ${file} carries the Codex note`, text.includes('models.codex.grill') && /models\.codex\.plan/.test(lines.find((l) => l.includes('models.codex.grill') && !l.startsWith('|')) || ''));
+  }
+}
+
+console.log(`grill-model-docs.test.js: ${passed} checks passed`);

package/bin/grilling-holistic-review-docs.test.js

@@ -37,8 +37,12 @@ for (const frag of [
   'contradictions, gaps, choices that break each other or the destination',
   'by question number',
   'say so in one line and go straight to the confirmation',
-  'accept, amend or reject',
-  'reject keeps the choices as they were',
+  'Every non-working combination carries its fix',
+  'say why in one line and name where it goes',
+  'Accepting a combination as a risk is never the proposed fix',
+  'apply, amend or keep',
+  'apply (the first option, recommended) applies every proposed amendment and fix',
+  'keep leaves the choices as they were',
   'consciously accepted risk',
   'reopens that branch',
   'the review runs again on the new set',
@@ -60,7 +64,7 @@ const pointer = (name, text, startsWith) => {
   const l = text.split('\n').find((x) => x.startsWith(startsWith));
   ok(`${name} found`, !!l);
   ok(`${name} references the anchor`, l.includes(ANCHOR));
-  ok(`${name} does not restate the rule`, !l.includes('accepted risk') && !l.includes('reject keeps'));
+  ok(`${name} does not restate the rule`, !l.includes('accepted risk') && !l.includes('keep leaves'));
 };
 pointer('chart SKILL standalone grill', read('trailhead-chart/SKILL.md'), 'Run a standalone **Grilling**');
 const engines = read('trailhead-work/references/ticket-engines.md');

package/bin/lib/codex-projection.js

@@ -69,7 +69,14 @@ function convertToCodex(md) {
   // 2. Claude's /clear -> Codex's /new.
   out = out.replace(/\/clear\b/g, '/new');
 
-  // 3. Paths: anchored forms first, then the bare form.
+  // 3a. Espansione della config dir: CLAUDE_CONFIG_DIR -> CODEX_HOME per intero,
+  // prima dei path nudi (altrimenti resta CLAUDE_CONFIG_DIR con fallback ~/.codex).
+  out = out.replace(/\$\{CLAUDE_CONFIG_DIR:-(~|\$HOME)\/\.claude\}/g, '${CODEX_HOME:-$1/.codex}');
+  // Forme nude rimaste in prosa: $CLAUDE_CONFIG_DIR e ${CLAUDE_CONFIG_DIR} -> CODEX_HOME.
+  out = out.replace(/\$\{CLAUDE_CONFIG_DIR\}/g, '${CODEX_HOME}');
+  out = out.replace(/\$CLAUDE_CONFIG_DIR\b/g, '$CODEX_HOME');
+
+  // 3b. Paths: anchored forms first, then the bare form.
   out = out.replace(/\$HOME\/\.claude\b/g, '$HOME/.codex');
   out = out.replace(/~\/\.claude\b/g, '~/.codex');
   out = out.replace(/(?<![A-Za-z0-9_\-.\/~$])\.claude\//g, '.codex/');
@@ -101,11 +108,11 @@ Where the engine uses \`AskUserQuestion\`, pose the choice as a **plain-text num
 After presenting the numbered list, STOP and wait: the user's **next message** is the answer to this pending question, not a fresh unrelated turn. Resolve it by matching either the **number typed** (e.g. "2") or the option's **label text** back onto that option, then continue the engine exactly as it would from a native \`AskUserQuestion\` response (e.g. write the chosen config value, or proceed down the chosen branch). If the reply matches no option, ask again rather than guessing. Never silently pick a default and proceed.
 
 ## D. Subagents (native multi_agent)
-Codex has a subagent toolkit: the multi_agent tools (\`spawn_agent\`, \`send_input\`, \`wait_agent\`, \`resume_agent\`, \`close_agent\`), stable and on by default on supported Codex (the installer gates on the floor that guarantees them). Where the engine delegates to a subagent (research, codebase-map, review, plan, execute, debug), spawn a real Codex subagent with these tools and the technique's own protocol (each technique carries its full protocol in-prompt, so no specialised agent is needed; pass the ticket's \`Scope:\` when relevant). The Claude-only Explore-vs-general-purpose split does not apply: Codex has one subagent kind. A subagent runs as a FRESH session that receives a task prompt, not this conversation; run independent ones in parallel (e.g. the codebase-map readers) and \`wait_agent\` on them.
+Codex has a subagent toolkit: the multi_agent tools (\`spawn_agent\`, \`send_input\`, \`wait_agent\`, \`resume_agent\`, \`close_agent\`), stable and on by default on supported Codex (the installer gates on the floor that guarantees them). Where the engine delegates to a subagent (research, codebase-map, review, plan, execute, debug, grill), spawn a real Codex subagent with these tools and the technique's own protocol (each technique carries its full protocol in-prompt, so no specialised agent is needed; pass the ticket's \`Scope:\` when relevant). The Claude-only Explore-vs-general-purpose split does not apply: Codex has one subagent kind. A subagent runs as a FRESH session that receives a task prompt, not this conversation; run independent ones in parallel (e.g. the codebase-map readers) and \`wait_agent\` on them.
 
 **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 agent registry (\`agent_type\` dispatch).** The installer always projects all 8 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 the 1 keyless agent — 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/verify and \`trailhead-codebase-map\` for the Codebase-map step, plus the 1 keyless \`trailhead-fix\` for the Fix step), 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.
+**Per-technique agent registry (\`agent_type\` dispatch).** The installer always projects all 9 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 fix with execute unset) 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/verify \`trailhead-codebase-map\` for the Codebase-map step and \`trailhead-grill\` for a Grilling round, plus \`trailhead-fix\` for the Fix step, which tracks the Execute pin), which routes it onto that technique's pinned model when one is set, or the session model otherwise. An unpinned or session-equal grill runs inline in the main session (no spawn): the main session stays the HITL orchestrator and asks the user itself. 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.
 
@@ -184,10 +191,11 @@ function codexTechniqueKey(name) {
 }
 
 // --- MODEL_KEYS --------------------------------------------------------------
-// The 7 pinnable technique keys, mirroring the models.codex.* namespace. The
-// other committed agent (fix) has no pin key and is always
-// projected pin-less (session model).
-const MODEL_KEYS = new Set(['plan', 'execute', 'research', 'review', 'debug', 'verify', 'codebase-map']);
+// The 8 pinnable technique keys, mirroring the models.codex.* namespace. The
+// other committed agent (fix) has no pin key of its own: it tracks execute.
+// Riconoscimento condiviso di "inherit session" (stesso del router, hooks/lib); modulo senza dipendenze, la proiezione resta pura.
+const { isInheritSession } = require('../../plugins/trailhead/hooks/lib/inherit-session.js');
+const MODEL_KEYS = new Set(['plan', 'execute', 'research', 'review', 'debug', 'verify', 'codebase-map', 'grill']);
 
 // --- codexAgentToml ---------------------------------------------------------
 // Render one Codex custom-agent TOML. When `model` is empty/absent, the TOML
@@ -231,9 +239,10 @@ function codexAgentToml({ name, description, developerInstructions, model, effor
 // 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 8 project, always). A keyed agent (plan/execute/research/
-// review/debug/verify/codebase-map) carries its models.codex.<key> pin when set, else is
-// pin-less; the 1 keyless agent (fix) is always pin-less.
+// uniformly (all 9 project, always). A keyed agent (plan/execute/research/
+// review/debug/verify/codebase-map/grill) carries its models.codex.<key> pin when set, else is
+// pin-less; fix has no key and carries the models.codex.execute pin (same
+// string/object/effort/inherit-session handling), so no agent is keyless.
 // Iterates agentDefs in the given order (readAgentDefs sorts by name) so the
 // write order is deterministic.
 function codexAgentTomlPlan(codexHome, codexModels, agentDefs) {
@@ -249,13 +258,19 @@ function codexAgentTomlPlan(codexHome, codexModels, agentDefs) {
 
     let model = null;
     let effort = null;
-    if (MODEL_KEYS.has(key) && models[key] != null) {
-      const raw = models[key];
+    // grill non impostato segue models.codex.plan (come model-route.js).
+    // fix non ha chiave propria: segue models.codex.execute (come model-route.js).
+    let pinKey = key === 'grill' && (models.grill == null || (typeof models.grill === 'string' && models.grill.trim() === '')) ? 'plan' : key;
+    if (key === 'fix') pinKey = 'execute';
+    if ((MODEL_KEYS.has(key) || key === 'fix') && models[pinKey] != null) {
+      const raw = models[pinKey];
+      // "inherit session" e' il default Codex documentato: nessun pin.
+      const isInherit = isInheritSession;
       if (typeof raw === 'string') {
-        if (raw.trim() !== '') model = raw;
+        if (raw.trim() !== '' && !isInherit(raw)) model = raw;
       } else if (typeof raw === 'object') {
         const m = typeof raw.model === 'string' ? raw.model : '';
-        if (m.trim() !== '') {
+        if (m.trim() !== '' && !isInherit(m)) {
           model = m;
           effort = typeof raw.effort === 'string' ? raw.effort : null;
         }
@@ -450,6 +465,7 @@ module.exports = {
   codexClusterAgentsYaml,
   codexAgentToml,
   codexAgentTomlPlan,
+  MODEL_KEYS,
   codexVerbSkillContent,
   codexVerbSkillAgentsYaml,
   codexVerbSkillPlan,

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

@@ -96,6 +96,8 @@ ok('codexSkillAdapterHeader §D pins the exact agent_type dispatch call shape',
   header.includes('spawn_agent(agent_type="trailhead-<technique>"'));
 ok('codexSkillAdapterHeader §D keeps the base spawn_agent v1 fallback path',
   header.includes('base multi_agent v1') && header.includes('inherit the one session model'));
+ok('codexSkillAdapterHeader §D says all 9 committed agents, names trailhead-grill, and runs an unpinned grill inline',
+  header.includes('all 9 committed') && header.includes('trailhead-grill') && /unpinned or session-equal grill runs inline/.test(header));
 ok('codexSkillAdapterHeader §D warns against a single blocking wait_agent with a poll loop',
   header.includes('bounded wait') && header.includes('poll'));
 ok('codexSkillAdapterHeader §D offers a background-job fallback for a stalling review',
@@ -261,10 +263,10 @@ ok('codexAgentToml escapes a " and \\ in name/description so the TOML stays vali
 })());
 
 // --- codexAgentTomlPlan ---
-// 7-entry stub agentDefs mirroring the real plugins/trailhead/agents/*.md
-// sources: 6 keyed techniques (plan/execute/research/review/debug/codebase-map,
+// 8-entry stub agentDefs mirroring the real plugins/trailhead/agents/*.md
+// sources: 7 keyed techniques (plan/execute/research/review/debug/codebase-map/grill,
 // whose filenames derive from trailhead-executor -> execute and
-// trailhead-code-review -> review) + 1 always-keyless agent (fix).
+// trailhead-code-review -> review) + fix, which tracks the execute pin.
 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.' },
@@ -273,37 +275,76 @@ const STUB_AGENT_DEFS = [
   { 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.' },
+  { name: 'trailhead-grill', description: 'grill desc', tools: 'Read', body: 'Grill body.' },
 ];
 
-ok('codexAgentTomlPlan: 7 agentDefs -> 7 writes with only the pinned key carrying a model', (() => {
+ok('codexAgentTomlPlan: 8 agentDefs -> 8 writes with only execute (and fix, which tracks it) carrying a model', (() => {
   const plan = codexAgentTomlPlan('/c', { execute: 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
-  if (plan.writes.length !== 7) return false;
+  if (plan.writes.length !== 8) 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');
+  const fix = byName['trailhead-fix'];
+  if (!fix || !fix.content.includes('model = "gpt-5.6-terra"')) return false;
+  const others = plan.writes.filter((w) => w.name !== 'trailhead-execute' && w.name !== 'trailhead-fix');
   return others.length === 6 && others.every((w) => !/^model = /m.test(w.content));
 })());
 
-ok('codexAgentTomlPlan: keyless trailhead-fix stays pin-less; trailhead-codebase-map now pins on codebase-map', (() => {
-  const plan = codexAgentTomlPlan('/c', { fix: 'gpt-5.6-terra', 'codebase-map': 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
+ok('codexAgentTomlPlan: models.codex.grill pins trailhead-grill.toml; unset leaves it pin-less', (() => {
+  const pinned = codexAgentTomlPlan('/c', { grill: 'gpt-5.6-sol' }, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-grill');
+  const unset = codexAgentTomlPlan('/c', {}, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-grill');
+  return pinned && pinned.path === '/c/agents/trailhead-grill.toml' && pinned.content.includes('model = "gpt-5.6-sol"') &&
+    unset && !/^model = /m.test(unset.content);
+})());
+
+ok('codexAgentTomlPlan: an unset models.codex.grill follows models.codex.plan; a set grill wins', (() => {
+  const find = (m) => codexAgentTomlPlan('/c', m, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-grill');
+  const follow = find({ plan: { model: 'gpt-5.6-sol', effort: 'high' } });
+  const own = find({ plan: 'gpt-5.6-sol', grill: 'gpt-5.6-terra' });
+  const none = find({ execute: 'gpt-5.6-sol' });
+  const plan = codexAgentTomlPlan('/c', { plan: 'gpt-5.6-sol' }, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-plan');
+  return follow.content.includes('model = "gpt-5.6-sol"') && follow.content.includes('model_reasoning_effort = "high"') &&
+    own.content.includes('model = "gpt-5.6-terra"') && !/^model = /m.test(none.content) && plan.content.includes('model = "gpt-5.6-sol"');
+})());
+
+ok('codexAgentTomlPlan: a literal inherit session is pin-less for every key, and grill follows it', (() => {
+  const find = (m, n) => codexAgentTomlPlan('/c', m, STUB_AGENT_DEFS).writes.find((w) => w.name === n);
+  const pinned = (w) => /^model = /m.test(w.content);
+  const a = { plan: 'inherit session' };
+  const b = { plan: 'gpt-5.6-sol', grill: 'inherit session' };
+  const c = { execute: ' Inherit Session ', research: { model: 'inherit session', effort: 'high' } };
+  return !pinned(find(a, 'trailhead-plan')) && !pinned(find(a, 'trailhead-grill')) &&
+    !pinned(find(b, 'trailhead-grill')) && find(b, 'trailhead-plan').content.includes('model = "gpt-5.6-sol"') &&
+    !pinned(find(c, 'trailhead-execute')) && !pinned(find(c, 'trailhead-research')) &&
+    !find(c, 'trailhead-research').content.includes('model_reasoning_effort');
+})());
+
+ok('codexAgentTomlPlan: trailhead-fix carries the execute pin (not a fix key); trailhead-codebase-map pins on codebase-map', (() => {
+  const plan = codexAgentTomlPlan('/c', { execute: { model: 'gpt-5.6-sol', effort: 'high' }, fix: 'gpt-5.6-luna', '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) &&
+    fix.path === '/c/agents/trailhead-fix.toml' && fix.content.includes('model = "gpt-5.6-sol"') &&
+    fix.content.includes('model_reasoning_effort = "high"') && !fix.content.includes('gpt-5.6-luna') &&
     map.path === '/c/agents/trailhead-codebase-map.toml' && map.content.includes('model = "gpt-5.6-terra"');
 })());
 
-ok('codexAgentTomlPlan: empty models object -> 7 pin-less writes (not zero)', (() => {
+ok('codexAgentTomlPlan: trailhead-fix is pin-less when execute is unset or inherit session', (() => {
+  const find = (m) => codexAgentTomlPlan('/c', m, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-fix');
+  return ![{}, { plan: 'gpt-5.6-sol' }, { execute: 'inherit session' }, { execute: { model: ' Inherit Session ', effort: 'high' } }]
+    .some((m) => /^model = /m.test(find(m).content) || find(m).content.includes('model_reasoning_effort'));
+})());
+
+ok('codexAgentTomlPlan: empty models object -> 8 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));
+  return plan.writes.length === 8 && plan.writes.every((w) => !/^model = /m.test(w.content));
 })());
 
-ok('codexAgentTomlPlan: null models -> 7 pin-less writes (not zero)', (() => {
+ok('codexAgentTomlPlan: null models -> 8 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));
+  return plan.writes.length === 8 && plan.writes.every((w) => !/^model = /m.test(w.content));
 })());
 
 ok('codexAgentTomlPlan: object model value on the execute key carries model + model_reasoning_effort', (() => {
@@ -315,7 +356,7 @@ ok('codexAgentTomlPlan: object model value on the execute key carries model + mo
 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');
+  return plan.writes.length === 8 && !/^model = /m.test(execute.content) && !execute.content.includes('model_reasoning_effort');
 })());
 
 ok('codexAgentTomlPlan: description is routed through convertToCodex (host paths rewritten)', (() => {
@@ -441,22 +482,45 @@ ok('convertToCodex keeps CLAUDE_CODE_SESSION_ID intact',
     autoRef.includes('--auto true --auto-done <n>'));
 }
 
+// #319: l'espansione CLAUDE_CONFIG_DIR diventa CODEX_HOME, mai un ibrido che punta alla config di Claude.
+{
+  const a = convertToCodex('${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/templates/x');
+  const b = convertToCodex('${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/y');
+  ok('convertToCodex maps the ~ config-dir expansion to CODEX_HOME', a === '${CODEX_HOME:-~/.codex}/trailhead/templates/x');
+  ok('convertToCodex maps the $HOME config-dir expansion to CODEX_HOME', b === '${CODEX_HOME:-$HOME/.codex}/hooks/y');
+  ok('convertToCodex leaves no CLAUDE_CONFIG_DIR behind', !/CLAUDE_CONFIG_DIR/.test(a + b));
+  const c = convertToCodex('config dir = `$CLAUDE_CONFIG_DIR` or `~/.claude`; `${CLAUDE_CONFIG_DIR}/x`');
+  ok('convertToCodex maps the bare config-dir forms to CODEX_HOME',
+    c === 'config dir = `$CODEX_HOME` or `~/.codex`; `${CODEX_HOME}/x`');
+  ok('convertToCodex leaves a longer variable name untouched',
+    convertToCodex('$CLAUDE_CONFIG_DIRX') === '$CLAUDE_CONFIG_DIRX');
+
+  // Ogni .md reale proiettato non deve contenere CLAUDE_CONFIG_DIR.
+  const root = path.join(__dirname, '../../plugins/trailhead');
+  const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? walk(path.join(d, e.name)) : e.name.endsWith('.md') ? [path.join(d, e.name)] : []);
+  const files = ['skills', 'agents', 'commands'].flatMap((n) => walk(path.join(root, n)));
+  const leaks = files.filter((f) => /CLAUDE_CONFIG_DIR/.test(convertToCodex(fs.readFileSync(f, 'utf8'))));
+  ok('real plugin .md files were found', files.length > 0);
+  ok('no projected plugin .md keeps CLAUDE_CONFIG_DIR: ' + leaks.join(', '), leaks.length === 0);
+}
+
 // #248: the shared boundary blocks survive the Codex projection of every real agent.
 {
   const { parseSource } = require('../../scripts/sync-agent-blocks.js');
   const shared = parseSource(fs.readFileSync(path.join(__dirname, '../../scripts/agent-blocks.md'), 'utf8'));
   const agentsDir = path.join(__dirname, '../../plugins/trailhead/agents');
   const files = fs.readdirSync(agentsDir).filter((f) => /^trailhead-.*\.md$/.test(f));
-  ok('projection boundaries: found the eight real agents', files.length === 8);
+  ok('projection boundaries: found the nine real agents', files.length === 9);
   ok('projection boundaries: source has common and implementing blocks', !!shared.common && !!shared.implementing);
   // #249: every agent's projected TOML carries exactly its family block, whole.
   const familyOf = {
     'trailhead-verify': 'reviewing', 'trailhead-code-review': 'reviewing',
     'trailhead-executor': 'implementing', 'trailhead-fix': 'implementing',
     'trailhead-debug': 'investigating', 'trailhead-research': 'investigating', 'trailhead-codebase-map': 'investigating',
-    'trailhead-plan': 'plan',
+    'trailhead-plan': 'plan', 'trailhead-grill': 'grilling',
   };
-  const families = ['reviewing', 'implementing', 'investigating', 'plan'];
+  const families = ['reviewing', 'implementing', 'investigating', 'plan', 'grilling'];
   ok('projection boundaries: source has every family block', families.every((f) => !!shared[f]));
   for (const f of files) {
     const name = f.slice(0, -3);

package/bin/lib/host-descriptor.js

@@ -65,6 +65,8 @@ const HOSTS = Object.freeze({
     label: 'Claude Code',
     configDirEnv: 'CLAUDE_CONFIG_DIR',
     configDirDefault: '.claude',
+    // Prefisso con cui l'host invoca un verbo trailhead (vedi commandForm).
+    commandPrefix: '/trailhead:',
     axes: Object.freeze({
       commandSurface: 'slash-file',
       subagentToolkit: 'full',
@@ -93,6 +95,7 @@ const HOSTS = Object.freeze({
     label: 'Codex',
     configDirEnv: 'CODEX_HOME',
     configDirDefault: '.codex',
+    commandPrefix: '$trailhead ',
     axes: Object.freeze({
       commandSurface: 'skill',
       subagentToolkit: 'full',
@@ -168,6 +171,15 @@ function hyphenateCommand(name) {
   return String(name).trim().replace(/^\//, '').replace(/:/g, '-');
 }
 
+// --- Helper: commandForm ------------------------------------------------------
+// Forma di invocazione di un verbo per l'host: la scrittura da usare in ogni
+// testo runtime, mai un literal `/trailhead:<verb>` hardcoded.
+//   commandForm('claude', 'update') -> '/trailhead:update'
+//   commandForm('codex', 'update')  -> '$trailhead update'
+function commandForm(host, verb) {
+  return `${resolveHost(host).commandPrefix}${verb}`;
+}
+
 // --- Helper: emitsAgentToml ---------------------------------------------------
 function emitsAgentToml(host) {
   return resolveHost(host).emitsAgentToml;
@@ -184,7 +196,7 @@ function degradations(host) {
 
   if (descriptor.axes.subagentToolkit === 'none') {
     entries.push({
-      from: 'subagent fan-out (research, codebase-map, review, plan, execute)',
+      from: 'subagent fan-out (research, codebase-map, review, plan, execute, grill)',
       to: 'inline sequential execution in the main session',
     });
   }
@@ -275,7 +287,7 @@ function updateNotice(host, cache) {
   const installed = String(cache.installed || '').trim();
   const ver = latest ? ` ${latest}` : '';
   const from = installed ? ` (you have ${installed})` : '';
-  return `Heads up: trailhead${ver} is available${from}. Run /trailhead:update to install it.`;
+  return `Heads up: trailhead${ver} is available${from}. Run ${commandForm(host, 'update')} to install it.`;
 }
 
 // --- Codex version floor gate (decision #27) --------------------------------
@@ -390,6 +402,7 @@ module.exports = {
   getHost,
   configDirFor,
   hyphenateCommand,
+  commandForm,
   emitsAgentToml,
   degradations,
   modelsCollapseNotice,

package/bin/lib/host-descriptor.test.js

@@ -8,6 +8,7 @@ const {
   getHost,
   configDirFor,
   hyphenateCommand,
+  commandForm,
   emitsAgentToml,
   degradations,
   modelsCollapseNotice,
@@ -104,6 +105,12 @@ ok('modelsCollapseNotice(codex, models set) names the set keys', (() => {
   const msg = modelsCollapseNotice('codex', { models: { plan: 'x', execute: 'y' } });
   return typeof msg === 'string' && msg.includes('plan') && msg.includes('execute') && msg.includes('Codex');
 })());
+ok('modelsCollapseNotice(codex, models.grill set) names grill', (() => {
+  const msg = modelsCollapseNotice('codex', { models: { grill: 'claude-opus-5-5' } });
+  return typeof msg === 'string' && msg.includes('(grill)') && msg.includes('models.codex');
+})());
+ok('modelsCollapseNotice is null once models.codex.grill is set',
+  modelsCollapseNotice('codex', { models: { grill: 'claude-opus-5-5', codex: { grill: 'gpt-5.6-sol' } } }) === null);
 ok('modelsCollapseNotice(codex, undefined config) is null',
   modelsCollapseNotice('codex') === null);
 ok('modelsCollapseNotice(claude, models set) is null (Claude honours the keys)',
@@ -127,6 +134,23 @@ ok('modelsCollapseNotice: codex namespace with only empty/nullish values does no
   return typeof msg === 'string' && msg.includes('plan') && !msg.includes('codex)');
 })());
 
+// --- commandForm ---
+ok('commandForm(claude, update) is the slash form', commandForm('claude', 'update') === '/trailhead:update');
+ok('commandForm(codex, update) is the dollar form', commandForm('codex', 'update') === '$trailhead update');
+ok('commandForm throws on an unknown host', (() => { try { commandForm('nope', 'x'); return false; } catch { return true; } })());
+
+// Drift guard: la lib degli hook ha la propria copia di commandForm (non puo'
+// richiedere bin/ una volta installata); le due devono restare identiche.
+{
+  const lib = require('../../plugins/trailhead/hooks/lib/model-defaults-review.js');
+  for (const host of ['claude', 'codex']) {
+    for (const verb of ['config', 'update']) {
+      ok(`commandForm drift: hook lib matches host-descriptor (${host}, ${verb})`,
+        lib.commandForm(host, verb) === commandForm(host, verb));
+    }
+  }
+}
+
 // --- updateNotice ---
 // Both hosts now have a hook bus (hookBus !== 'none'), so updateNotice never
 // fires for either: the SessionStart hook + (on Codex) its stdout