@marcomigozzi/trailhead 0.5.0 → 0.5.1

package/bin/trailhead.js

@@ -172,10 +172,11 @@ function claudePaths(configDir) {
     commands: path.join(configDir, 'commands', 'trailhead'),
     hooksDir: path.join(configDir, 'hooks'),
     templates: path.join(configDir, 'trailhead', 'templates'),
+    agents: path.join(configDir, 'agents'),
     settings: path.join(configDir, 'settings.json'),
   };
 }
-const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-check-update.js'];
+const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-check-update.js'];
 // Runtime libs the hook scripts require (trailhead-commit-guard.js does
 // require('./lib/commit-message-check.js')). Copied by name, never a recursive
 // sweep: the Claude hooks/lib dir is shared with other plugins, so we must not
@@ -217,6 +218,43 @@ function place(src, dest, symlink) {
   else fs.cpSync(src, dest, { recursive: true });
 }
 
+// The committed engine agents (plugins/trailhead/agents/trailhead-*.md). On a
+// Claude install they must register as user subagent types under
+// <configDir>/agents/, so the engine can dispatch each technique to its
+// trailhead-<technique> agent and honour config.models.<key>; without them
+// every technique falls back to running inline on the session model (the
+// per-technique model split silently never applies). The agents dir is shared
+// with the user's own agents and other plugins, so touch trailhead's own files
+// by name only, never the whole dir (mirrors the skills/hooks discipline).
+function agentFileNames() {
+  const dir = path.join(SRC, 'agents');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.startsWith('trailhead-') && f.endsWith('.md'));
+}
+function sweepTrailheadAgents(agentsDir) {
+  if (!fs.existsSync(agentsDir)) return;
+  for (const f of fs.readdirSync(agentsDir)) {
+    if (f.startsWith('trailhead-') && f.endsWith('.md')) rmrf(path.join(agentsDir, f));
+  }
+}
+// Place the engine agents into destAgentsDir by name (copy, or per-file symlink
+// under a --symlink dev install so agent edits are live). Returns the names
+// placed. rmrf each dest first so a reinstall over a file or symlink never
+// hits EEXIST.
+function copyAgentFiles(destAgentsDir, { useSymlink = false } = {}) {
+  const names = agentFileNames();
+  if (!names.length) return names;
+  ensure(destAgentsDir);
+  for (const f of names) {
+    const src = path.join(SRC, 'agents', f);
+    const dest = path.join(destAgentsDir, f);
+    rmrf(dest);
+    if (useSymlink) fs.symlinkSync(src, dest, 'file');
+    else fs.copyFileSync(src, dest);
+  }
+  return names;
+}
+
 function addHook(s, event, matcher, command) {
   s.hooks = s.hooks || {};
   s.hooks[event] = s.hooks[event] || [];
@@ -239,6 +277,9 @@ function uninstallClaude(configDir) {
   // layout left that this package no longer ships), never the shared dir itself.
   sweepTrailheadSkills(path.join(configDir, 'skills'));
   [P.commands, path.join(configDir, 'trailhead')].forEach(rmrf);
+  // Remove trailhead's own agents by name; the agents dir is shared, so never
+  // rmrf the whole dir (same discipline as skills/hooks).
+  sweepTrailheadAgents(P.agents);
   HOOK_FILES.forEach((f) => rmrf(path.join(P.hooksDir, f)));
   // Remove only trailhead's own lib files by name: the hooks/lib dir is shared
   // with other plugins, so never rmrf the whole dir.
@@ -246,6 +287,7 @@ function uninstallClaude(configDir) {
   const s = readJSON(P.settings);
   stripHook(s, 'PreToolUse', 'trailhead-commit-guard.js');
   stripHook(s, 'PreToolUse', 'trailhead-secret-guard.js');
+  stripHook(s, 'PreToolUse', 'trailhead-install-guard.js');
   stripHook(s, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
   stripHook(s, 'SessionStart', 'trailhead-check-update.js');
   writeJSON(P.settings, s);
@@ -271,6 +313,14 @@ function installClaude(configDir, { useSymlink }) {
   place(path.join(SRC, 'commands'), P.commands, useSymlink);
   place(path.join(SRC, 'templates'), P.templates, useSymlink);
   copyHookScripts(P.hooksDir, { useSymlink });
+  // Register the engine agents as Claude subagents: sweep any stale
+  // trailhead-*.md first (a removed/renamed agent), then place the current set
+  // by name. This is what makes config.models.<key> take effect on the
+  // skills/npm channel; without it every technique runs inline (see
+  // agentFileNames above). The agents dir is shared, so only our names are
+  // touched.
+  sweepTrailheadAgents(P.agents);
+  const agentFiles = copyAgentFiles(P.agents, { useSymlink });
   // version marker: serve al check-update hook per la versione installata (canale npm)
   const pkgVersion = (readJSON(path.join(SRC, '.claude-plugin', 'plugin.json')).version || '').trim();
   if (pkgVersion) {
@@ -282,6 +332,7 @@ function installClaude(configDir, { useSymlink }) {
   const added = [
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-commit-guard.js')),
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-secret-guard.js')),
+    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-install-guard.js')),
     addHook(s, 'PostToolUse', 'Bash', hookCmd('trailhead-issue-injection-scanner.js')),
     addHook(s, 'SessionStart', '', hookCmd('trailhead-check-update.js')),
   ].some(Boolean);
@@ -290,6 +341,7 @@ function installClaude(configDir, { useSymlink }) {
   console.log(`✓ trailhead installed for Claude Code → ${configDir}`);
   console.log(`  skills    → ${path.join(configDir, 'skills')}/  (${skillDirs.join(', ')})${useSymlink ? '  (symlink)' : ''}`);
   console.log(`  commands  → ${P.commands}  (/trailhead:*)`);
+  console.log(`  agents    → ${P.agents}/  (${agentFiles.length} agent(s): trailhead-*)${useSymlink ? '  (symlink)' : ''}`);
   console.log(`  hooks     → ${P.hooksDir}/  (${added ? 'registered' : 'already present'} in settings.json)`);
   console.log(`  templates → ${P.templates}`);
   console.log('\nRestart or reload your agent to pick up the commands, then run /trailhead to start.');
@@ -349,6 +401,39 @@ function readCommandVerbs() {
     .sort((a, b) => a.verb.localeCompare(b.verb));
 }
 
+// Unquote a YAML double-quoted scalar (unlike commands/*.md, the agent .md
+// frontmatter wraps `description:` in double quotes). Leaves a plain/
+// unquoted scalar untouched, so this is safe to apply unconditionally.
+function unquoteYamlScalar(v) {
+  if (typeof v !== 'string' || v.length < 2 || v[0] !== '"' || v[v.length - 1] !== '"') return v;
+  return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+
+// Read the 7 committed agent sources from plugins/trailhead/agents/*.md: each
+// file's basename is the agent's name; frontmatter description/tools ride
+// along, and `body` is the markdown after the closing frontmatter `---`.
+// Single-sources the Codex agent-TOML projection so it never drifts from the
+// committed agent prose. Mirrors readCommandVerbs's shape. Pure fs; kept out
+// of codex-projection.js, which must stay fs-free.
+function readAgentDefs() {
+  const dir = path.join(SRC, 'agents');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.startsWith('trailhead-') && f.endsWith('.md'))
+    .map((f) => {
+      const raw = fs.readFileSync(path.join(dir, f), 'utf8');
+      const fm = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/.exec(raw);
+      const body = fm ? raw.slice(fm[0].length) : raw;
+      return {
+        name: f.slice(0, -3),
+        description: unquoteYamlScalar(fmValue(raw, 'description')),
+        tools: fmValue(raw, 'tools'),
+        body,
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
 // Extract one frontmatter scalar's raw value verbatim (an already-valid YAML
 // scalar re-serialises unchanged). Looks only inside the leading ---...--- block.
 // Returns undefined when the key is absent or its value is empty.
@@ -464,9 +549,13 @@ function installCodex(configDir, { useSymlink }) {
     featureManual = true;
   }
 
-  // Per-technique model pins: project models.codex.* (merged project + global
-  // config) into trailhead-<technique>.toml under the real ~/.codex/agents/
-  // dir. Sweep only trailhead's own files first, so a stale pin from a prior
+  // Per-technique agent registry: project ALL 7 committed agents
+  // (readAgentDefs, sourced from plugins/trailhead/agents/*.md) as
+  // trailhead-<technique>.toml under the real ~/.codex/agents/ dir, uniformly.
+  // A keyed technique (plan/execute/research/review/debug) carries its
+  // models.codex.<key> pin (merged project + global config) when set, else is
+  // pin-less; the 2 keyless agents (fix, codebase-map) are always pin-less.
+  // Sweep only trailhead's own files first, so a stale pin from a prior
   // install (or a removed technique) never lingers, without touching the
   // user's other custom-agent TOMLs.
   const codexModels = readCodexModels(configDir);
@@ -474,16 +563,15 @@ function installCodex(configDir, { useSymlink }) {
   for (const f of fs.readdirSync(L.codexAgentsDir)) {
     if (/^trailhead-.*\.toml$/.test(f)) rmrf(path.join(L.codexAgentsDir, f));
   }
-  const plan = codexAgentTomlPlan(configDir, codexModels);
+  const plan = codexAgentTomlPlan(configDir, codexModels, readAgentDefs());
   for (const w of plan.writes) fs.writeFileSync(w.path, w.content);
 
   // Feature flag: Codex gates per-subagent model pinning behind
-  // features.multi_agent_v2 = true. Enable it ONLY when we actually projected
-  // pins: with no models.codex.* set, base multi_agent already fans out and the
-  // adapter's §D runtime detection expects no trailhead agent_type registry, so
-  // leaving v2 off keeps that contract sound. (A reinstall that drops all pins
-  // sweeps the TOMLs above but leaves any prior v2 flag in place; harmless, as
-  // no trailhead-* agents remain for the runtime to dispatch to.)
+  // features.multi_agent_v2 = true. All 7 agent TOMLs are normally projected
+  // (pinned or pin-less), so v2 is enabled on every healthy Codex install: the
+  // adapter's §D runtime detection expects a trailhead agent_type registry,
+  // pins or not. Still guarded on writes so a degenerate case (no agent .md
+  // found, zero writes) never flips the flag on with an empty registry.
   let featureManualV2 = false;
   if (plan.writes.length > 0) {
     const updatedTomlV2 = enableCodexMultiAgentV2Feature(current);
@@ -500,10 +588,12 @@ function installCodex(configDir, { useSymlink }) {
   console.log(`  templates → ${L.templatesDir}/`);
   console.log(`  verb skills → ${L.skillsRoot}/trailhead-<verb>/  (${verbSkillPlan.dirs.length} discoverability skills: invoke $trailhead-<verb>)`);
   console.log(`  hooks     → ${L.hooksScriptsDir}/  (registered in hooks.json)`);
-  if (plan.writes.length > 0) {
-    console.log(`  agents    → ${L.codexAgentsDir}/  (${plan.writes.length} model pin(s): ${plan.writes.map((w) => w.name + '.toml').join(', ')})`);
-  } else {
-    console.log('  agents    → no models.codex.* set, subagents inherit the session model');
+  {
+    const pinned = plan.writes.filter((w) => w.content.includes('\nmodel = '));
+    const pinsNote = pinned.length > 0
+      ? `${pinned.length} pinned: ${pinned.map((w) => w.name + '.toml').join(', ')}`
+      : 'no models.codex.* set, all pin-less (session model)';
+    console.log(`  agents    → ${L.codexAgentsDir}/  (${plan.writes.length} agent(s) projected; ${pinsNote})`);
   }
   console.log('\nRestart or reload Codex to pick up the skill, then run $trailhead to start.');
   // The trust prompt only fires once the feature flag is on. When we could not
@@ -545,6 +635,7 @@ function uninstallCodex(configDir) {
     const h = readJSON(L.hooksJson);
     stripHook(h, 'PreToolUse', 'trailhead-commit-guard.js');
     stripHook(h, 'PreToolUse', 'trailhead-secret-guard.js');
+    stripHook(h, 'PreToolUse', 'trailhead-install-guard.js');
     stripHook(h, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
     stripHook(h, 'SessionStart', 'trailhead-check-update.js');
     writeJSON(L.hooksJson, h);

package/bin/trailhead.test.js

@@ -131,11 +131,19 @@ ok('codex: skills/trailhead/hooks/lib/commit-message-check.js exists (commit-gua
 const codexConfigTomlPath = path.join(codexDir, 'config.toml');
 ok('codex: config.toml exists', fs.existsSync(codexConfigTomlPath));
 ok('codex: config.toml enables hooks feature', fs.readFileSync(codexConfigTomlPath, 'utf8').includes('hooks = true'));
-// v2 is gated on projected pins: this install (repoRoot, no models.codex.*)
-// projects none, so multi_agent_v2 stays OFF (base multi_agent still fans out;
-// adapter §D expects no trailhead agent_type registry in the no-pins case).
-ok('codex: config.toml does NOT enable multi_agent_v2 when no models.codex.* pins are projected',
-  !fs.readFileSync(codexConfigTomlPath, 'utf8').includes('multi_agent_v2 = true'));
+// All 7 agents are always projected uniformly (pinned or pin-less), so
+// multi_agent_v2 is ON even with no models.codex.* set (this install,
+// repoRoot, sets none): the adapter §D registry is always present.
+ok('codex: config.toml enables multi_agent_v2 even with no models.codex.* pins projected',
+  fs.readFileSync(codexConfigTomlPath, 'utf8').includes('multi_agent_v2 = true'));
+
+const codexAgentsDirPath = path.join(codexDir, 'agents');
+const noPinFixTomlPath = path.join(codexAgentsDirPath, 'trailhead-fix.toml');
+const noPinMapTomlPath = path.join(codexAgentsDirPath, 'trailhead-codebase-map.toml');
+ok('codex: trailhead-fix.toml is projected with no models.codex.* set', fs.existsSync(noPinFixTomlPath));
+ok('codex: trailhead-codebase-map.toml is projected with no models.codex.* set', fs.existsSync(noPinMapTomlPath));
+ok('codex: trailhead-fix.toml is pin-less (no model = line) with no models.codex.* set',
+  fs.existsSync(noPinFixTomlPath) && !/^model = /m.test(fs.readFileSync(noPinFixTomlPath, 'utf8')));
 
 // --- codex --symlink: link verbatim artifacts (hooks + templates), keep skills projected ---
 const codexSymDir = mktmp();
@@ -161,12 +169,21 @@ ok('codex copy: hooks are regular files (not symlinks)',
 ok('codex copy: templates is a regular dir (not a symlink)',
   !fs.lstatSync(path.join(codexDir, 'skills', 'trailhead', 'templates')).isSymbolicLink());
 
-// --- codex agent TOML projection (#38) -----------------------------------------
+// --- codex agent TOML projection (#38, #88) -------------------------------------
 // repoRoot's own .trailhead/config.json has no models.codex.*, so a plain
-// install (cwd: repoRoot, no models.codex anywhere) projects no agent TOMLs.
-ok('codex: no trailhead-*.toml under agents/ when models.codex.* is unset',
-  !fs.existsSync(path.join(codexDir, 'agents')) ||
-  !fs.readdirSync(path.join(codexDir, 'agents')).some((f) => /^trailhead-.*\.toml$/.test(f)));
+// install (cwd: repoRoot, no models.codex anywhere) still projects all 7
+// agents pin-less (uniform projection, #88), never zero.
+ok('codex: all 7 trailhead-*.toml exist under agents/ even with models.codex.* unset', (() => {
+  const dir = path.join(codexDir, 'agents');
+  if (!fs.existsSync(dir)) return false;
+  const tomls = fs.readdirSync(dir).filter((f) => /^trailhead-.*\.toml$/.test(f));
+  return tomls.length === 7;
+})());
+ok('codex: every trailhead-*.toml is pin-less when models.codex.* is unset', (() => {
+  const dir = path.join(codexDir, 'agents');
+  const tomls = fs.readdirSync(dir).filter((f) => /^trailhead-.*\.toml$/.test(f));
+  return tomls.every((f) => !/^model = /m.test(fs.readFileSync(path.join(dir, f), 'utf8')));
+})());
 
 // --- codex migration (#46): install over old prompt shims sweeps them --------
 const migCodexDir = mktmp();
@@ -236,6 +253,20 @@ ok('claude: trailhead-commit-guard.js loads without MODULE_NOT_FOUND', (() => {
 })());
 ok('claude: SKILL.md does not start with the codex adapter header', !fs.readFileSync(claudeSkillPath, 'utf8').startsWith('<codex_skill_adapter>'));
 
+// --- claude: engine agents registered as user subagents -----------------------
+// Without these under <configDir>/agents/, every technique dispatch fails and
+// falls back to running inline on the session model, so the per-technique
+// config.models.* split silently never applies.
+const claudeAgentsDir = path.join(claudeDir, 'agents');
+const expectedAgents = ['trailhead-plan', 'trailhead-executor', 'trailhead-research', 'trailhead-code-review', 'trailhead-debug', 'trailhead-fix', 'trailhead-codebase-map'];
+for (const a of expectedAgents) {
+  ok(`claude: agents/${a}.md placed`, fs.existsSync(path.join(claudeAgentsDir, `${a}.md`)));
+}
+ok('claude: agent file registers its subagent name in frontmatter',
+  fs.readFileSync(path.join(claudeAgentsDir, 'trailhead-executor.md'), 'utf8').startsWith('---\nname: trailhead-executor\n'));
+ok('claude: agents are real files on a copy install (not symlinks)',
+  !fs.lstatSync(path.join(claudeAgentsDir, 'trailhead-plan.md')).isSymbolicLink());
+
 // --- claude --symlink: dev install links hooks live too (not just skills/commands) ---
 const symDir = mktmp();
 runInstaller([`--claude`, `--symlink`, `--dir=${symDir}`]);
@@ -260,6 +291,11 @@ ok('claude symlink: a symlinked commit-guard still loads its lib (no MODULE_NOT_
 runInstaller([`--claude`, `--symlink`, `--dir=${symDir}`]);
 ok('claude symlink: reinstall over existing symlinks succeeds',
   fs.lstatSync(path.join(symDir, 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
+ok('claude symlink: agents/trailhead-plan.md is a symlink',
+  fs.lstatSync(path.join(symDir, 'agents', 'trailhead-plan.md')).isSymbolicLink());
+ok('claude symlink: agent symlink resolves into the package source',
+  fs.realpathSync(path.join(symDir, 'agents', 'trailhead-plan.md')) ===
+  fs.realpathSync(path.join(repoRoot, 'plugins', 'trailhead', 'agents', 'trailhead-plan.md')));
 // Default (copy) install keeps hooks as real files, not symlinks.
 ok('claude copy: hooks/trailhead-secret-guard.js is a regular file (not a symlink)',
   !fs.lstatSync(path.join(claudeDir, 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
@@ -283,6 +319,14 @@ ok('claude migration: stale trailhead-legacy cluster swept on reinstall', !fs.ex
 ok('claude migration: co-tenant skill preserved (only trailhead names swept)', fs.existsSync(path.join(migClaudeDir, 'skills', 'other-plugin')));
 ok('claude migration: current dispatcher present after reinstall', fs.existsSync(path.join(migClaudeDir, 'skills', 'trailhead', 'SKILL.md')));
 ok('claude migration: current cluster present after reinstall', fs.existsSync(path.join(migClaudeDir, 'skills', 'trailhead-work', 'SKILL.md')));
+// The agents dir gets the same name-only sweep on reinstall: a stale trailhead
+// agent (renamed/removed) is swept, a co-tenant agent left alone.
+fs.writeFileSync(path.join(migClaudeDir, 'agents', 'trailhead-oldagent.md'), '---\nname: trailhead-oldagent\n---\n');
+fs.writeFileSync(path.join(migClaudeDir, 'agents', 'other-plugin-agent.md'), '---\nname: other-plugin-agent\n---\n');
+runInstaller([`--claude`, `--dir=${migClaudeDir}`]);
+ok('claude migration: stale trailhead-oldagent.md swept on reinstall', !fs.existsSync(path.join(migClaudeDir, 'agents', 'trailhead-oldagent.md')));
+ok('claude migration: co-tenant agent preserved on reinstall', fs.existsSync(path.join(migClaudeDir, 'agents', 'other-plugin-agent.md')));
+ok('claude migration: engine agents present after reinstall', fs.existsSync(path.join(migClaudeDir, 'agents', 'trailhead-executor.md')));
 
 // Uninstall also sweeps a stale trailhead-owned dir the current package no
 // longer ships (monolith), not just the current engineSkillDirs() set.
@@ -305,6 +349,17 @@ runInstaller([`--claude`, `--dir=${coTenantDir}`, '--uninstall']);
 ok('claude uninstall: trailhead lib removed', !fs.existsSync(path.join(coTenantDir, 'hooks', 'lib', 'commit-message-check.js')));
 ok('claude uninstall: co-tenant lib preserved (no recursive wipe)', fs.existsSync(coTenantLib));
 
+// The agents dir is shared too: a co-tenant's own agent survives uninstall,
+// while trailhead's are removed by name.
+const coTenantAgentDir = mktmp();
+runInstaller([`--claude`, `--dir=${coTenantAgentDir}`]);
+const foreignAgent = path.join(coTenantAgentDir, 'agents', 'other-plugin-agent.md');
+fs.writeFileSync(foreignAgent, '---\nname: other-plugin-agent\n---\n');
+ok('claude: engine agent present before uninstall', fs.existsSync(path.join(coTenantAgentDir, 'agents', 'trailhead-plan.md')));
+runInstaller([`--claude`, `--dir=${coTenantAgentDir}`, '--uninstall']);
+ok('claude uninstall: trailhead agents removed by name', !fs.existsSync(path.join(coTenantAgentDir, 'agents', 'trailhead-plan.md')));
+ok('claude uninstall: co-tenant agent preserved (no recursive wipe)', fs.existsSync(foreignAgent));
+
 // Uninstall removes every split skill (dispatcher + clusters + _shared) by name.
 const splitDir = mktmp();
 runInstaller([`--claude`, `--dir=${splitDir}`]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues. Map-based onboarding + a discuss→plan→execute→verify engine, all on the Issues. Installs the trailhead skill, commands, and hooks into your agent's config dir.",
   "bin": {
     "trailhead": "bin/trailhead.js"

package/plugins/trailhead/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trailhead",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues, resolving one at a time. Map-based onboarding + a discuss→plan→execute→verify engine with atomic commits, all on the Issues. Ships as a dispatcher plus cohesion-clustered skills over a shared core; depends on nothing beyond an authenticated gh CLI.",
   "author": {
     "name": "Marco Migozzi",

package/plugins/trailhead/agents/trailhead-code-review.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-code-review
+description: "trailhead code-review subagent: adversarially reviews a ticket's diff and reports; never edits or commits."
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's code-review subagent. Review the ticket's diff adversarially on the Code review technique's axes, verifying each finding before reporting. Do not defer to a convention or a settled-decision memory.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/code-review.md`); follow that, not any embedded copy. Read-only by policy: it reviews and reports into trailhead's `VERIFY` comment, it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.review` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/agents/trailhead-codebase-map.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-codebase-map
+description: "trailhead codebase-map reader subagent: maps one non-overlapping facet of the repo. Read-only."
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's codebase-map reader subagent. Map ONE non-overlapping facet of the repo for the distilled `trailhead:codebase` issue; do not read another reader's territory.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/codebase-map.md`); follow that, not any embedded copy. Read-only by policy: read-only by construction. Model-agnostic by design: the engine passes the session model at spawn (no dedicated model key), so config stays authoritative.

package/plugins/trailhead/agents/trailhead-debug.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-debug
+description: "trailhead debug subagent: finds a defect's root cause by the scientific method."
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's debug subagent. Find the root cause of the ticket's defect by the scientific method: reproduce, localise, falsifiable hypotheses, confirm cause, verify.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/debug.md`); follow that, not any embedded copy. Full tools by policy: it adds instrumentation and regression tests, so it needs Write. Model-agnostic by design: the engine passes the `config.models.debug` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/agents/trailhead-executor.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-executor
+description: "trailhead execute subagent: implements an approved PLAN with atomic conventional commits (each carrying a Refs: #<n> trailer)."
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's execute subagent. Implement the approved PLAN for a build ticket with atomic conventional commits, each carrying a `Refs: #<n>` trailer for the ticket, following the repo's `trailhead:conventions`.
+
+The full protocol is injected at spawn from the trailhead skill's single source (the Execute step in `trailhead-work/references/ticket-engines.md`); follow that, not any embedded copy. Full tools by policy: it can Edit/Write/commit. Model-agnostic by design: the engine passes the `config.models.execute` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/agents/trailhead-fix.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-fix
+description: "trailhead fix subagent: implements a bug fix with atomic commits (each carrying a Refs: #<n> trailer)."
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's fix subagent. Implement the correction for a bug ticket with atomic conventional commits, each carrying a `Refs: #<n>` trailer for the ticket, following the repo's `trailhead:conventions`; where sensible, a test that fails before and passes after.
+
+The full protocol is injected at spawn from the trailhead skill's single source (the Fix step in `trailhead-work/references/ticket-engines.md`); follow that, not any embedded copy. Full tools by policy: it can Edit/Write/commit. Model-agnostic by design: the engine passes the `config.models.execute` model as the spawn-time override (fix tracks the execute key), so config stays authoritative.

package/plugins/trailhead/agents/trailhead-plan.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-plan
+description: "trailhead planning subagent: produces a build ticket's PLAN (steps, seams, files touched, verification criteria). Read-only, never implements."
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's planning subagent. Produce the PLAN for a build ticket: the steps, the seams, the files touched, and the verification criteria, applying TDD per the ticket's config.
+
+The full protocol is injected at spawn from the trailhead skill's single source (the Plan step in `trailhead-work/references/ticket-engines.md`); follow that, not any embedded copy. Read-only by policy: plan, do not implement or commit. Model-agnostic by design: the engine passes the `config.models.plan` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/agents/trailhead-research.md

@@ -0,0 +1,9 @@
+---
+name: trailhead-research
+description: "trailhead research subagent: gathers a decision-ready fact from primary sources."
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's research subagent. Gather the decision-ready fact a ticket waits on from primary sources, recording findings with citations to a throwaway `research/<name>` branch; change no product code beyond the research artifact.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/research.md`); follow that, not any embedded copy. Full tools by policy: it needs Write for the research artifact. Model-agnostic by design: the engine passes the `config.models.research` model as the spawn-time override, so config stays authoritative.

package/plugins/trailhead/hooks/hooks.json

@@ -11,6 +11,10 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/trailhead-secret-guard.js\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/trailhead-install-guard.js\""
           }
         ]
       }

package/plugins/trailhead/hooks/trailhead-install-guard.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// trailhead-install-guard.js: PreToolUse(Bash) hook.
+// Slopsquatting barrier. trailhead's executor/fix agents can install packages
+// (npm / PyPI / crates.io / Go / RubyGems) while resolving a ticket, so a
+// hallucinated or typosquatted package NAME could be fetched silently. This gate
+// BLOCKS any public-registry install that names a package until the agent has
+// vetted the name, then instructs it to verify legitimacy (typosquat similarity,
+// package age, download counts, repo metadata) and checkpoint the human on a
+// suspicious result (block-and-ask). A vetted install proceeds by re-running the
+// command prefixed with the sentinel `TRAILHEAD_VERIFIED_INSTALL=1`.
+// Only a NAMED install is gated: lockfile/manifest installs (bare `npm install`,
+// `npm ci`, `pip install -r`, `cargo build`, `go mod download`, `bundle install`)
+// and local paths / URLs / VCS refs carry no typed name and pass through.
+// Blocks with exit 2 + {"decision":"block",...}; allows everything else.
+// Crash-safe: any error → exit 0 (never wedge the user's workflow).
+// Self-contained, no dependencies. Pure functions exported for tests; runs as a
+// hook when executed directly.
+
+const SENTINEL = /(?:^|\s)TRAILHEAD_VERIFIED_INSTALL=1(?:\s|$)/;
+
+// Per-ecosystem: the binaries that own it, and the install verbs that fetch a
+// named package. `add` covers pnpm/yarn/bun/uv/poetry/cargo; `install`/`i` npm
+// and pip; `get`/`install` go.
+const ECOSYSTEMS = {
+  npm: { bins: ['npm', 'pnpm', 'yarn', 'bun'], verbs: ['install', 'i', 'add'] },
+  pip: { bins: ['pip', 'pip3', 'pipx', 'uv', 'poetry'], verbs: ['install', 'add'] },
+  crates: { bins: ['cargo'], verbs: ['add', 'install'] },
+  go: { bins: ['go'], verbs: ['get', 'install'] },
+  gem: { bins: ['gem'], verbs: ['install'] },
+};
+
+// Flags that consume a SEPARATE-TOKEN value (a file, url, or dir), so that value
+// is never mistaken for a package name (e.g. `pip install -r requirements.txt`).
+const VALUE_FLAGS = new Set([
+  '-r', '--requirement', '-c', '--constraint', '-e', '--editable',
+  '-i', '--index-url', '--extra-index-url', '-f', '--find-links',
+  '-t', '--target', '--prefix', '--root', '--python', '-d', '--dest',
+  '-w', '--workspace', '--registry', '-C', '--directory', '--chdir',
+  '--no-binary', '--only-binary',
+]);
+
+function basename(p) {
+  const s = String(p).split('/');
+  return s[s.length - 1];
+}
+
+// A positional that is NOT a public-registry name: local path, url, vcs ref, or a
+// file artifact. Go module paths (example.com/foo) look url-ish but ARE the named
+// module, so for go only a leading . / ~ disqualifies.
+function isLocalOrUrl(t, ecosystem) {
+  if (t.startsWith('.') || t.startsWith('/') || t.startsWith('~')) return true;
+  if (ecosystem === 'go') return false; // a bare module path is the name; gate it
+  if (t.includes('://')) return true;
+  if (/^(?:git\+|file:|https?:|hg\+|svn\+|bzr\+)/.test(t)) return true;
+  if (/\.(?:tgz|tar\.gz|whl|gz|zip|txt|toml|lock|cfg)$/.test(t)) return true;
+  return false;
+}
+
+// Best-effort bare name for the human-facing reason (detection does not depend on
+// this being exact). Strips pip version specifiers / extras and npm @version.
+function bareName(t) {
+  let n = t.split(/[=<>~!\[]/)[0]; // pip: pkg==1, pkg>=1, pkg[extra]
+  if (n.startsWith('@')) {
+    const at = n.indexOf('@', 1); // scoped @scope/pkg@1 → cut the version @
+    if (at !== -1) n = n.slice(0, at);
+  } else {
+    const at = n.indexOf('@'); // npm pkg@1.2.3
+    if (at !== -1) n = n.slice(0, at);
+  }
+  return n;
+}
+
+// Detect a public-registry install that NAMES at least one package, in a single
+// shell segment. Returns { ecosystem, packages: [names] } or null.
+function detectSegment(cmd) {
+  const toks = String(cmd).trim().split(/\s+/).filter(Boolean);
+  let i = 0;
+  while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i])) i++; // env prefix
+  if (i >= toks.length) return null;
+
+  const bin = basename(toks[i]);
+  let ecosystem = null;
+  for (const [name, spec] of Object.entries(ECOSYSTEMS)) {
+    if (spec.bins.includes(bin)) { ecosystem = name; break; }
+  }
+  // `python -m pip install …` → treat as pip.
+  if (!ecosystem && /^python3?$/.test(bin)) {
+    if (toks[i + 1] === '-m' && /^pip3?$/.test(toks[i + 2] || '')) {
+      ecosystem = 'pip';
+      i += 2; // land on `pip`
+    } else {
+      return null;
+    }
+  }
+  if (!ecosystem) return null;
+  i++; // past the binary (or the `pip` peeled above)
+
+  // `uv pip install …` → peel the `pip`.
+  if (bin === 'uv' && toks[i] === 'pip') i++;
+
+  const verb = toks[i];
+  if (!ECOSYSTEMS[ecosystem].verbs.includes(verb)) return null;
+  i++;
+
+  const packages = [];
+  for (let j = i; j < toks.length; j++) {
+    const t = toks[j];
+    if (t.startsWith('-')) {
+      if (VALUE_FLAGS.has(t)) j++; // consume its separate-token value
+      continue;
+    }
+    if (isLocalOrUrl(t, ecosystem)) continue;
+    packages.push(bareName(t));
+  }
+  if (packages.length === 0) return null; // lockfile/manifest install: nothing typed
+  return { ecosystem, packages };
+}
+
+// Agents chain commands (`cd app && npm install foo`), so check every shell
+// segment, not just the first. Split on the common separators (&& || ; | and
+// newlines); a registry name never contains one, so a stray split is harmless.
+// Returns the first segment's hit, or null.
+function detectInstall(cmd) {
+  for (const seg of String(cmd).split(/&&|\|\||;|\n|\|/)) {
+    const hit = detectSegment(seg);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+// The agent's "I have vetted these" acknowledgement.
+function isVerified(cmd) {
+  return SENTINEL.test(String(cmd));
+}
+
+function block(hit) {
+  const list = hit.packages.join(', ');
+  const reason =
+    `trailhead: this ${hit.ecosystem} install names package(s) not yet vetted (${list}). ` +
+    'Guard against slopsquatting before installing: verify each package is legitimate, weighing ' +
+    'name / typosquat similarity to popular packages, package age / first-seen date, download counts / popularity, ' +
+    'and repository metadata (present and matching). ' +
+    'STOP and ask the human on anything suspicious (block-and-ask): do not install on your own judgement. ' +
+    'Once vetted, re-run the exact command prefixed with `TRAILHEAD_VERIFIED_INSTALL=1` to proceed.';
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'UNVETTED_PACKAGE_INSTALL', reason }));
+  process.exit(2);
+}
+
+function run(data) {
+  let cmd = '';
+  try {
+    cmd = (JSON.parse(data).tool_input || {}).command || '';
+  } catch {
+    process.exit(0); // unparseable input: nothing to gate
+  }
+  try {
+    if (isVerified(cmd)) process.exit(0); // agent has vetted these
+    const hit = detectInstall(cmd);
+    if (hit) block(hit);
+  } catch {
+    // fall through to allow: a guard must never wedge the workflow
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends → give up
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { detectInstall, isVerified };