@marcomigozzi/trailhead 0.16.1 → 0.17.0

package/plugins/trailhead/hooks/lib/issue-body.test.js

@@ -126,6 +126,87 @@ const EMPTY_DECISIONS = ['Intro line for the map, long enough.', '', '## Decisio
   ok('remove: missing section is an error', typeof miss.error === 'string');
 }
 
+// --- applyOp: remove on numbered lists ---------------------------------------
+{
+  const rm = (body, match) => applyOp(body, { kind: 'remove', section: 'Not yet specified', match });
+  const sec = (...l) => ['Intro line for the map, long enough.', '', '## Not yet specified', ...l, ''].join('\n');
+  const repro = rm('## Not yet specified\n1. **Repo to checkout resolution**: x\n2. **Other**: y\n', 'Repo to checkout resolution');
+  ok('remove numbered: ticket repro removes the entry and renumbers', repro.changed === true && repro.body === '## Not yet specified\n1. **Other**: y\n');
+  ok('remove numbered: summary unchanged', repro.summary === 'removed 1 entry from "Not yet specified"');
+  const mid = rm(sec('1. a', '2. b', '3. c'), 'b');
+  ok('remove numbered: following items renumbered', mid.body === sec('1. a', '2. c'));
+  const last = rm(sec('1. a', '2. b'), 'b');
+  ok('remove numbered: removing the last entry renumbers nothing', last.body === sec('1. a'));
+  const start = rm(sec('3. a', '4. b', '5. c'), 'a');
+  ok('remove numbered: start number preserved', start.body === sec('3. b', '4. c'));
+  const paren = rm(sec('1) a', '2) b', '3) c'), 'a');
+  ok('remove numbered: ) delimiter handled and kept', paren.body === sec('1) b', '2) c'));
+  const cont = rm(sec('1. a', '   detail of a', '2. b', '   detail of b', '3. c'), 'detail of a');
+  ok('remove numbered: 3-space continuation removed with its entry', cont.body === sec('1. b', '   detail of b', '2. c'));
+  const nested = rm(sec('1. a', '   1. nested', '2. b'), 'a');
+  ok('remove numbered: an indented number is a continuation, not an entry', nested.body === sec('1. b'));
+  const amb = rm(sec('1. a x', '2. b x'), 'x');
+  ok('remove numbered: more than one match is ambiguous', typeof amb.error === 'string' && /ambiguous/.test(amb.error));
+  const body = sec('1. a', '2. b');
+  const none = rm(body, 'zzz');
+  ok('remove numbered: zero matches is a no-op', !none.error && none.changed === false && none.body === body);
+  const mixed = rm(sec('- bullet', '1. a', '2. b', '3. c'), 'a');
+  ok('remove numbered: bullet before the hit untouched, run after renumbered', mixed.body === sec('- bullet', '1. b', '2. c'));
+  const stop = rm(sec('1. a', '2. b', '- bullet', '3. c'), 'a');
+  ok('remove numbered: renumbering stops at a bullet', stop.body === sec('1. b', '- bullet', '3. c'));
+  const delim = rm(sec('1. a', '2. b', '3) c', '4) d'), 'a');
+  ok('remove numbered: renumbering stops at a different delimiter', delim.body === sec('1. b', '3) c', '4) d'));
+  const dec = rm(sec('1.5 x', '2. y'), 'y');
+  ok('remove numbered: 1.5 is not an item', dec.changed === true && dec.body === sec('1.5 x'));
+  const bullet = rm(sec('- a', '- b'), 'a');
+  ok('remove bullet: unchanged behaviour in a bullet section', bullet.body === sec('- b'));
+
+  // loose lists (blank lines between items)
+  const loose = sec('1. a', '', '2. b', '', '3. c', '', '4. d');
+  ok('remove loose: first item, numbering continues and no blank under the heading', rm(loose, 'a').body === sec('1. b', '', '2. c', '', '3. d'));
+  ok('remove loose: middle item, no double blank', rm(loose, 'b').body === sec('1. a', '', '2. c', '', '3. d'));
+  ok('remove loose: last item, no double blank', rm(loose, 'd').body === sec('1. a', '', '2. b', '', '3. c'));
+  const spaced = sec('', '1. a', '', '2. b', '', '3. c');
+  ok('remove loose: first item keeps the blank after the heading', rm(spaced, 'a').body === sec('', '1. b', '', '2. c'));
+  const half = rm(sec('1. a', '2. b', '', '3. c', '4. d'), 'a');
+  ok('remove loose: a run split by a blank line is renumbered across it', half.body === sec('1. b', '', '2. c', '3. d'));
+  ok('remove loose: tight neighbour before a blank keeps its spacing', rm(sec('1. a', '2. b', '', '3. c'), 'b').body === sec('1. a', '', '2. c'));
+
+  // loose items with an indented continuation paragraph
+  const para3 = '## Not yet specified\n\n1. a\n\n   cont para\n\n2. b\n\n3. c';
+  ok('remove loose: item with a continuation paragraph removed whole, rest renumbered', rm(para3, 'a').body === '## Not yet specified\n\n1. b\n\n2. c');
+  ok('remove loose: matching the continuation paragraph removes the whole item', rm(para3, 'cont para').body === '## Not yet specified\n\n1. b\n\n2. c');
+  ok('remove loose: the item after a continuation paragraph is removed cleanly', rm(para3, 'b').body === '## Not yet specified\n\n1. a\n\n   cont para\n\n2. c');
+  const bpara = '## Not yet specified\n\n- a\n\n  cont para\n\n- b\n';
+  ok('remove loose: bullet with a continuation paragraph removed whole', rm(bpara, 'cont para').body === '## Not yet specified\n\n- b\n');
+
+  // the only item of a spaced section before the next heading
+  ok('remove loose: sole numbered item leaves a single blank before the next heading', rm('## Not yet specified\n\n1. a\n\n## Next', 'a').body === '## Not yet specified\n\n## Next');
+  ok('remove loose: sole bullet leaves a single blank before the next heading', rm('## Not yet specified\n\n- a\n\n## Next', 'a').body === '## Not yet specified\n\n## Next');
+
+  // CRLF
+  const crlf = rm(sec('1. a', '2. b', '3. c').replace(/\n/g, '\r\n'), 'a');
+  ok('remove numbered: CRLF preserved and renumbered', crlf.body === sec('1. b', '2. c').replace(/\n/g, '\r\n'));
+
+  // width changes
+  const wide = rm(sec('9. a', '10. b', '11. c'), 'a');
+  ok('remove numbered: renumbering across a width change', wide.body === sec('9. b', '10. c'));
+  const ten = rm(sec(...Array.from({ length: 10 }, (_, k) => `${k + 1}. item${k + 1}`)), '1. item1');
+  ok('remove numbered: a list reaching 10 items renumbered', ten.body === sec(...Array.from({ length: 9 }, (_, k) => `${k + 1}. item${k + 2}`)));
+
+  // run boundaries
+  const para = rm(sec('1. a', '2. b', '', 'A paragraph.', '3. c'), 'a');
+  ok('remove numbered: a paragraph ends the run, later numbering untouched', para.body === sec('1. b', '', 'A paragraph.', '3. c'));
+  const para2 = rm(sec('1. a', '', '2. b', '', 'A paragraph.', '', '3. c'), 'a');
+  ok('remove numbered: a paragraph after blank lines ends the run', para2.body === sec('1. b', '', 'A paragraph.', '', '3. c'));
+
+  // numbering style
+  const padded = rm(sec('09. a', '10. b', '11. c'), 'a');
+  ok('remove numbered: zero padding width kept', padded.body === sec('09. b', '10. c'));
+  const lazy = rm(sec('1. a', '1. b', '1. c'), 'a');
+  ok('remove numbered: an all-same-number list is not renumbered', lazy.body === sec('1. b', '1. c'));
+}
+
 // --- fake tracker ------------------------------------------------------------
 function makeTracker(init = {}) {
   const t = {
@@ -396,6 +477,9 @@ function writeTmp(text) {
   const t3 = makeTracker();
   const r3 = runMain(['remove', '--issue', '7', '--section', 'Decisions so far', '--match', '#'], t3);
   ok('remove ambiguous: exit 1, nothing written', r3.code === 1 && /ambiguous/.test(r3.out) && t3.writes.length === 0);
+  const tn = makeTracker({ body: '## Not yet specified\n1. **Repo to checkout resolution**: x\n2. **Other**: y\n' });
+  const rn = runMain(['remove', '--issue', '7', '--section', 'Not yet specified', '--match', 'Repo to checkout resolution'], tn);
+  ok('remove numbered via main: entry removed and rest renumbered', rn.code === 0 && /removed 1 entry/.test(rn.out) && tn.writes.length === 1 && tn.writes[0] === '## Not yet specified\n1. **Other**: y\n');
   const t4 = makeTracker();
   const r4 = runMain(['replace', '--issue', '7', '--section', 'Not yet specified', '--file', writeTmp('- only this\n')], t4);
   ok('replace via main: summary and write', r4.code === 0 && /replaced "Not yet specified"/.test(r4.out) && t4.writes[0].includes('- only this'));

package/plugins/trailhead/hooks/lib/model-defaults-review.js

@@ -16,6 +16,7 @@ const path = require('path');
 const DATA_FILE = path.join(__dirname, 'model-defaults.json');
 const HOSTS = ['claude', 'codex'];
 const TIERS = ['strong', 'standard', 'fast'];
+const { isInheritSession } = require('./inherit-session.js');
 
 // Host: la lib viene copiata byte-per-byte su Codex (sotto
 // <codexHome>/skills/trailhead/hooks/lib), quindi l'host si deduce dal path
@@ -94,7 +95,7 @@ function findTier(data, host, id, current) {
 }
 
 function isSkippable(id) {
-  return !id || typeof id !== 'string' || id.trim() === '' || id === 'inherit session';
+  return !id || typeof id !== 'string' || id.trim() === '' || isInheritSession(id);
 }
 
 // Valuta un singolo pin (id) per un host e ritorna { from, to } se stale,
@@ -206,6 +207,23 @@ function effectiveModels(layers) {
   return { config: { models: outModels }, sources };
 }
 
+// Un valore "impostato" per il fallback di grill: non null/undefined/stringa vuota.
+const isSetValue = (v) => v !== undefined && v !== null && !(typeof v === 'string' && v.trim() === '');
+
+// #323: una layer di config che imposta plan ma non grill imposta implicitamente
+// grill = plan per quella layer, PRIMA del merge progetto-su-globale (cosi' un
+// progetto che ha scelto i suoi modelli fa grilling sul suo plan, anche se il
+// globale fissa un grill). Vale per models.* e per models.codex.*. Funzione
+// pura: non muta l'input; usata solo dal routing e dalla proiezione Codex,
+// mai dalla review dei pin (un grill implicito non e' un pin dell'utente).
+function withImplicitGrill(models) {
+  if (!isPlainObject(models)) return models;
+  const imply = (obj) => (isSetValue(obj.plan) && !isSetValue(obj.grill) ? { ...obj, grill: obj.plan } : obj);
+  const out = imply(models);
+  if (isPlainObject(models.codex)) return { ...out, codex: imply(models.codex) };
+  return out;
+}
+
 function reviewOffer({ config, data, ack, sources, host }) {
   const current = currentEntry(data);
   if (!current) return null;
@@ -395,6 +413,8 @@ module.exports = {
   applyUpdate,
   semverLt,
   effectiveModels,
+  withImplicitGrill,
+  isInheritSession,
   reviewOffer,
   reviewNotice,
   detectHost,
@@ -403,6 +423,7 @@ module.exports = {
   globalConfigDir,
   globalConfigFile,
   globalAckFile,
+  loadGlobalConfig,
   readAckFile,
   writeAckFile,
   readAck,

package/plugins/trailhead/hooks/lib/model-defaults-review.test.js

@@ -34,6 +34,8 @@ const {
   globalAckFile,
   readAckFile,
   writeAckFile,
+  withImplicitGrill,
+  isInheritSession,
 } = require('./model-defaults-review.js');
 
 const LIB_PATH = path.join(__dirname, 'model-defaults-review.js');
@@ -295,6 +297,67 @@ ok('claude-haiku-5-5 itself is not stale',
       `models.codebase-map: claude-haiku-4-5-20251001 -> claude-haiku-5-5 (new default; from the project config, ${cfgPath})`));
 }
 
+// --- #323: i pin grill sono valutati come ogni altra chiave (caratterizzazione) ---
+{
+  const config = { models: { grill: 'claude-opus-5', codex: { grill: { model: 'gpt-5.5-sol', effort: 'high' } } } };
+  const stale = stalePins(config, data);
+  ok('stale models.grill pin is flagged and updated to the strong default',
+    stale.some((s) => s.key === 'models.grill' && s.from === 'claude-opus-5' && s.to === 'claude-opus-5-5'));
+  const next = applyUpdate({ models: { grill: 'claude-opus-5' } }, stalePins({ models: { grill: 'claude-opus-5' } }, data));
+  ok('applyUpdate rewrites models.grill', next.models.grill === 'claude-opus-5-5');
+  const codexStale = stalePins({ models: { codex: { grill: { model: 'gpt-5.6-terra', effort: 'high' } } } }, data);
+  ok('models.codex.grill at the current default is not flagged', codexStale.length === 0);
+}
+
+// --- #323: una config senza grill (chiave nata dopo) non genera nulla per grill ---
+{
+  const sevenOld = { plan: 'claude-opus-5-5', execute: 'claude-sonnet-5-5', research: 'claude-sonnet-5-5', review: 'claude-sonnet-5-5',
+    debug: 'claude-sonnet-5-5', verify: 'claude-sonnet-5-5', 'codebase-map': 'claude-haiku-5-5',
+    codex: { plan: { model: 'gpt-5.6-sol', effort: 'high' }, execute: 'gpt-5.6-terra' } };
+  const cfg = { models: sevenOld };
+  ok('seven old keys and no grill: no stale pin names grill', stalePins(cfg, data).every((s) => !/grill/.test(s.key)));
+  ok('seven old keys at current defaults: the review offers nothing', reviewOffer({ config: cfg, data, ack: null }) === null);
+  const stale = { models: { ...sevenOld, plan: 'claude-opus-5' } };
+  const offer = reviewOffer({ config: stale, data, ack: null });
+  ok('a stale plan pin is flagged but the notice never mentions grill', offer !== null && !offer.notice.includes('grill'));
+  ok('applyUpdate does not invent a grill key', !('grill' in applyUpdate(stale, stalePins(stale, data)).models));
+}
+
+{
+  const mod = require('./inherit-session.js');
+  const src = fs.readFileSync(path.join(__dirname, 'inherit-session.js'), 'utf8');
+  ok('inherit-session.js is dependency-free (no require)', !/require\(/.test(src));
+  ok('model-defaults-review re-exports the same isInheritSession', mod.isInheritSession === isInheritSession);
+  const projSrc = fs.readFileSync(path.join(__dirname, '..', '..', '..', '..', 'bin', 'lib', 'codex-projection.js'), 'utf8');
+  ok('codex-projection requires the dependency-free module, not model-defaults-review',
+    projSrc.includes("hooks/lib/inherit-session.js") && !projSrc.includes('model-defaults-review'));
+  ok('isSkippable semantics: an inherit session pin is never flagged stale',
+    stalePins({ models: { plan: ' Inherit Session ' } }, data).length === 0);
+}
+
+// --- #323: isInheritSession e' l'unico riconoscimento di "inherit session" ---
+ok('isInheritSession: bare string, trimmed, any case',
+  isInheritSession('inherit session') && isInheritSession('  Inherit Session ') && isInheritSession('INHERIT SESSION'));
+ok('isInheritSession: the model field of an object pin', isInheritSession({ model: 'inherit session', effort: 'high' }) && isInheritSession({ model: ' Inherit Session' }));
+ok('isInheritSession: real ids and non-strings are not inherit',
+  !isInheritSession('gpt-5.6-sol') && !isInheritSession({ model: 'gpt-5.6-sol' }) && !isInheritSession(null) && !isInheritSession(undefined) && !isInheritSession({}) && !isInheritSession(3));
+
+// --- #323: una layer che imposta plan ma non grill imposta grill = plan ---
+{
+  const src = { plan: 'p', codex: { plan: 'cp' }, execute: 'e' };
+  const out = withImplicitGrill(src);
+  ok('withImplicitGrill: plan without grill implies grill (claude and codex)', out.grill === 'p' && out.codex.grill === 'cp');
+  ok('withImplicitGrill: does not mutate the input', !('grill' in src) && !('grill' in src.codex));
+  ok('withImplicitGrill: an explicit grill is kept', withImplicitGrill({ plan: 'p', grill: 'g' }).grill === 'g');
+  ok('withImplicitGrill: null or blank grill counts as unset', withImplicitGrill({ plan: 'p', grill: null }).grill === 'p' && withImplicitGrill({ plan: 'p', grill: ' ' }).grill === 'p');
+  ok('withImplicitGrill: no plan, no implied grill', !('grill' in withImplicitGrill({ execute: 'e' })));
+  ok('withImplicitGrill: a blank plan implies nothing', !('grill' in withImplicitGrill({ plan: '' })));
+  ok('withImplicitGrill: inherit session plan implies an inherit grill', withImplicitGrill({ plan: 'inherit session' }).grill === 'inherit session');
+  ok('withImplicitGrill: non-objects pass through', withImplicitGrill(null) === null && withImplicitGrill('x') === 'x');
+  const stale = { models: { plan: 'claude-opus-5' } };
+  ok('the pinned model review does not use the implicit grill', stalePins(stale, data).every((s) => s.key !== 'models.grill'));
+}
+
 // --- effectiveModels (pure merge, no mutation) --------------------------------
 {
   const globalModels = { plan: 'g-plan', execute: 'g-exec', codex: { plan: { model: 'g-gpt', effort: 'high' } } };
@@ -498,7 +561,7 @@ ok('stalePins: a non-object models.codex yields no codex pins (not an exception)
   const codexHome = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-codexhome-'));
   const libDir = path.join(codexHome, 'skills', 'trailhead', 'hooks', 'lib');
   fs.mkdirSync(libDir, { recursive: true });
-  for (const f of ['model-defaults-review.js', 'model-defaults.json']) {
+  for (const f of ['model-defaults-review.js', 'model-defaults.json', 'inherit-session.js']) {
     fs.copyFileSync(path.join(__dirname, f), path.join(libDir, f));
   }
   fs.mkdirSync(path.join(codexHome, 'trailhead'), { recursive: true });

package/plugins/trailhead/hooks/lib/model-route.js

@@ -0,0 +1,207 @@
+'use strict';
+// model-route.js: decide dove gira un'attivita' legata a una chiave models.*
+// (inline nella sessione oppure dispatch a un subagent), per host. #323.
+// Funzione pura route() piu' una CLI che carica la config effettiva (globale
+// poi progetto, uniti da effectiveModels di model-defaults-review.js).
+// Per la chiave grill, un valore non impostato segue models.plan (e su Codex
+// models.codex.plan): non ha un default Balanced proprio. #323.
+// E' il router di ogni step del motore (plan, execute, fix via execute, review,
+// verify, research, debug, codebase-map, grill): il paragrafo canonico e'
+// "Route every step through model-route.js" in skills/_shared/techniques.md. #325.
+//
+// CLI:
+//   node model-route.js <key> --session <id completo|unknown> [--session-effort <e>]
+//        [--host claude|codex] [--no-subagents] [<dir>]
+// Stampa una riga JSON {"route","agent","model","alias","suggest","warning"}.
+// Exit 2 (errore JSON su stderr, niente su stdout) se manca --session o e'
+// vuoto, con un flag sconosciuto, un host o una chiave sconosciuti.
+
+const fs = require('fs');
+const path = require('path');
+const mdr = require('./model-defaults-review.js');
+const { isInheritSession } = require('./inherit-session.js');
+
+const UNKNOWN_SESSION = 'unknown'; // valore riservato: non e' mai uguale a un id
+const HOSTS = ['claude', 'codex'];
+const ALIASES = ['opus', 'sonnet', 'haiku', 'fable'];
+
+// Chiave -> nome dell'agent, per host. Su Codex i nomi sono quelli che la
+// proiezione TOML emette (codexAgentTomlPlan); su Claude quelli sotto agents/.
+const AGENT_OF = Object.freeze({
+  claude: Object.freeze({
+    plan: 'trailhead-plan',
+    execute: 'trailhead-executor',
+    research: 'trailhead-research',
+    review: 'trailhead-code-review',
+    debug: 'trailhead-debug',
+    verify: 'trailhead-verify',
+    'codebase-map': 'trailhead-codebase-map',
+    grill: 'trailhead-grill',
+  }),
+  codex: Object.freeze({
+    plan: 'trailhead-plan',
+    execute: 'trailhead-execute',
+    research: 'trailhead-research',
+    review: 'trailhead-review',
+    debug: 'trailhead-debug',
+    verify: 'trailhead-verify',
+    'codebase-map': 'trailhead-codebase-map',
+    grill: 'trailhead-grill',
+  }),
+});
+
+// Riga Balanced della tabella dei profili (configuration-reference.md), senza
+// grill (un grill non impostato segue plan); il test la tiene allineata.
+const BALANCED = Object.freeze({
+  plan: 'strong',
+  execute: 'standard',
+  research: 'standard',
+  review: 'standard',
+  debug: 'standard',
+  verify: 'standard',
+  'codebase-map': 'fast',
+});
+
+// Famiglia (alias accettato da Agent su Claude Code) dell'id, o null.
+function familyAlias(id) {
+  if (typeof id !== 'string') return null;
+  return ALIASES.find((a) => id.toLowerCase().includes(a)) || null;
+}
+
+// Id dei tier dell'host dall'entry corrente di model-defaults.json.
+function loadTierIds(host) {
+  const current = mdr.currentEntry(mdr.loadData());
+  return (current && current[host]) || {};
+}
+
+// Toglie un suffisso finale `[...]` (es. la finestra di contesto `[1m]`): lo
+// stesso modello con o senza suffisso resta lo stesso modello.
+const stripSuffix = (id) => (typeof id === 'string' ? id.replace(/\[[^\]]*\]\s*$/, '').trim() : id);
+
+const isUnset = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+const result = (fields) => ({ route: 'inline', agent: null, model: null, alias: null, suggest: null, warning: null, ...fields });
+
+// Grill non impostato segue plan (valore risolto di models.plan, o il default
+// Balanced di plan): ritorna { raw, tierKey } per la chiave data.
+function resolveRaw(source, key) {
+  const own = source ? source[key] : undefined;
+  if (key === 'grill' && isUnset(own)) return { raw: source ? source.plan : undefined, tierKey: 'plan' };
+  return { raw: own, tierKey: key };
+}
+
+function routeClaude({ key, models, sessionModel, subagents, tierIds }) {
+  const { raw, tierKey } = resolveRaw(models, key);
+  if (isInheritSession(raw)) return result({});
+  const id = stripSuffix(isUnset(raw) ? (tierIds || {})[BALANCED[tierKey]] : raw);
+  if (typeof id !== 'string' || id.trim() === '') return result({ warning: 'unknown-id' });
+  const sameAsSession = sessionModel !== UNKNOWN_SESSION && id === sessionModel;
+
+  if (subagents === false) {
+    return result({ model: id, suggest: sameAsSession ? null : id });
+  }
+  if (sameAsSession) return result({ model: id });
+  const alias = familyAlias(id);
+  if (!alias) return result({ model: id, warning: 'unknown-id' });
+  return result({ route: 'dispatch', agent: AGENT_OF.claude[key], model: id, alias });
+}
+
+function routeCodex({ key, models, sessionModel, sessionEffort, subagents }) {
+  const codexModels = models && models.codex && typeof models.codex === 'object' && !Array.isArray(models.codex) ? models.codex : {};
+  const { raw } = resolveRaw(codexModels, key);
+  if (isUnset(raw) || isInheritSession(raw)) return result({});
+  let pin = typeof raw === 'object' ? raw : { model: raw };
+  if (typeof pin.model !== 'string' || pin.model.trim() === '') return result({});
+  pin = { ...pin, model: stripSuffix(pin.model) };
+
+  const sameModel = sessionModel !== UNKNOWN_SESSION && pin.model === sessionModel;
+  if (subagents === false) return result({ model: pin.model, suggest: sameModel ? null : pin.model });
+  // Solo il TOML proiettato onora model_reasoning_effort: a parita' di modello
+  // si resta inline solo se non c'e' un effort pinnato, o se coincide con quello di sessione.
+  if (sameModel) {
+    if (!pin.effort) return result({ model: pin.model });
+    if (sessionEffort && sessionEffort === pin.effort) return result({ model: pin.model });
+  }
+  return result({ route: 'dispatch', agent: AGENT_OF.codex[key], model: pin.model });
+}
+
+function route({ key, host, models, sessionModel, sessionEffort, subagents, tierIds } = {}) {
+  if (!HOSTS.includes(host)) throw new Error(`unknown host: ${host}`);
+  if (!Object.prototype.hasOwnProperty.call(AGENT_OF[host], key)) throw new Error(`unknown key: ${key}`);
+  const args = { key, models, sessionModel: stripSuffix(sessionModel), sessionEffort, subagents, tierIds };
+  return host === 'codex' ? routeCodex(args) : routeClaude(args);
+}
+
+// --- CLI -------------------------------------------------------------------
+function parseArgs(argv) {
+  const opts = { key: null, session: null, sessionEffort: null, host: null, subagents: true, dir: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--no-subagents') {
+      opts.subagents = false;
+    } else if (a === '--session' || a === '--session-effort' || a === '--host') {
+      const v = argv[i + 1];
+      if (v === undefined || v.startsWith('--')) throw new Error(`${a} needs a value`);
+      opts[a === '--session' ? 'session' : a === '--host' ? 'host' : 'sessionEffort'] = v;
+      i++;
+    } else if (a.startsWith('--')) {
+      throw new Error(`unknown flag: ${a}`);
+    } else if (opts.key === null) {
+      opts.key = a;
+    } else if (opts.dir === null) {
+      opts.dir = a;
+    } else {
+      throw new Error(`unexpected argument: ${a}`);
+    }
+  }
+  if (!opts.key) throw new Error('a key is required');
+  if (opts.session === null || opts.session.trim() === '') throw new Error('--session <full model id|unknown> is required');
+  if (opts.host !== null && !HOSTS.includes(opts.host)) throw new Error(`unknown host: ${opts.host}`);
+  return opts;
+}
+
+// Config effettiva: globale poi progetto (il progetto vince chiave per chiave).
+function effectiveConfig(host, dir) {
+  // Ogni layer: plan senza grill implica grill = plan, prima del merge (#323).
+  const implied = (config) => (config && config.models ? { ...config, models: mdr.withImplicitGrill(config.models) } : config);
+  const layers = [{ layer: 'global', file: mdr.globalConfigFile(host), config: implied(mdr.loadGlobalConfig(host)) }];
+  const projectRoot = mdr.findProjectRoot(dir);
+  if (projectRoot) {
+    const file = path.join(projectRoot, '.trailhead', 'config.json');
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      layers.push({ layer: 'project', file, config: parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? implied(parsed) : {} });
+    } catch {
+      /* config di progetto illeggibile: vale come assente */
+    }
+  }
+  return mdr.effectiveModels(layers).config;
+}
+
+function main(argv, io = {}) {
+  const stdout = io.stdout || process.stdout;
+  const stderr = io.stderr || process.stderr;
+  let out;
+  try {
+    const opts = parseArgs(argv);
+    const host = opts.host || mdr.detectHost();
+    const models = effectiveConfig(host, opts.dir || process.cwd()).models;
+    out = route({
+      key: opts.key,
+      host,
+      models,
+      sessionModel: opts.session,
+      sessionEffort: opts.sessionEffort,
+      subagents: opts.subagents,
+      tierIds: loadTierIds('claude'),
+    });
+  } catch (e) {
+    stderr.write(`${JSON.stringify({ error: e.message })}\n`);
+    return 2;
+  }
+  stdout.write(`${JSON.stringify({ route: out.route, agent: out.agent, model: out.model, alias: out.alias, suggest: out.suggest, warning: out.warning })}\n`);
+  return 0;
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = { route, parseArgs, main, effectiveConfig, familyAlias, loadTierIds, AGENT_OF, BALANCED };