@marcomigozzi/trailhead 0.7.0 → 0.8.0

package/plugins/trailhead/hooks/trailhead-search-guard.test.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Tests for trailhead-search-guard.js. Run: node trailhead-search-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const HOOK = path.join(__dirname, 'trailhead-search-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Run the hook end-to-end: pipe tool_input JSON on stdin, capture {code, out}.
+function runHook(command) {
+  const input = JSON.stringify({ tool_input: { command } });
+  try {
+    const out = execFileSync('node', [HOOK], { input });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString(), err: (e.stderr || '').toString() };
+  }
+}
+
+// --- ticket #134: the exact regression command must be BLOCKED ---
+const ticketCmd = String.raw`cd app && grep -n "go_router" pubspec.yaml pubspec.lock | head; echo "=== router file ==="; grep -rln "GoRouter(" lib/ ; echo "=== /who route def ==="; grep -rn "'/who'\|\"/who\"\|/profile/manage\|path: '/home'" lib/ | head -30`;
+const rTicket = runHook(ticketCmd);
+ok('ticket #134 exact command is blocked (exit 2)', rTicket.code === 2 && /SEARCH_HYGIENE_VIOLATION|search-hygiene/.test(rTicket.out));
+
+// --- BLOCK cases ---
+const r1 = runHook('cd app && grep -n "go_router" pubspec.yaml');
+ok('cd <relative> && grep <relative> is blocked (exit 2)', r1.code === 2 && /search-hygiene/.test(r1.out));
+
+const r2 = runHook('cd /abs/app; grep -rln "GoRouter(" lib/');
+ok('cd <abs>; grep <relative> is blocked (exit 2)', r2.code === 2 && /search-hygiene/.test(r2.out));
+
+const r3 = runHook('pushd app && cat file.txt');
+ok('pushd <dir> && cat <relative> is blocked (exit 2)', r3.code === 2 && /search-hygiene/.test(r3.out));
+
+const r4 = runHook('cd app && wc -l foo.txt');
+ok('cd <dir> && wc -l <relative> is blocked (exit 2)', r4.code === 2 && /search-hygiene/.test(r4.out));
+
+const r5 = runHook('cd app &&\ngrep -n "x" foo.txt\n');
+ok('cd <dir> && then relative grep on a later line (newline-joined) is blocked (exit 2)', r5.code === 2 && /search-hygiene/.test(r5.out));
+
+const r6 = runHook('cd app; echo hi; grep -n "x" foo.txt');
+ok('cd <dir>; ...; relative grep several statements later is blocked (exit 2)', r6.code === 2 && /search-hygiene/.test(r6.out));
+
+const r7 = runHook('env -C app grep -n "x" foo.txt');
+ok('env -C <dir> grep <relative> (single statement) is blocked (exit 2)', r7.code === 2 && /search-hygiene/.test(r7.out));
+
+const r8 = runHook('cd app && git log -- foo.txt');
+ok('cd <dir> && git log without -C on a relative path is blocked (exit 2)', r8.code === 2 && /search-hygiene/.test(r8.out));
+
+const r9 = runHook('cd app && rg "TODO" foo.txt');
+ok('cd <dir> && rg <relative> is blocked (exit 2)', r9.code === 2 && /search-hygiene/.test(r9.out));
+
+// --- ALLOW cases (no false positives) ---
+const a1 = runHook('grep -n "x" /abs/app/pubspec.yaml');
+ok('path-explicit grep with no cd is allowed (exit 0)', a1.code === 0 && a1.out.trim() === '');
+
+const a2 = runHook('git -C /abs/app grep "x"');
+ok('git -C <abs> grep is allowed (exit 0)', a2.code === 0 && a2.out.trim() === '');
+
+const a3 = runHook('cd /abs && npm test');
+ok('cd <abs> && npm test (no read/search verb) is allowed (exit 0)', a3.code === 0 && a3.out.trim() === '');
+
+const a4 = runHook('cd /abs && ls -la');
+ok('cd <abs> && ls (not a Read()-denied verb) is allowed (exit 0)', a4.code === 0 && a4.out.trim() === '');
+
+const a5 = runHook('cd /abs/app');
+ok('a bare standalone cd <abs> alone is allowed (exit 0) - known limitation, never block a lone cd', a5.code === 0 && a5.out.trim() === '');
+
+const a6 = runHook('grep "cd foo" /abs/file');
+ok('grep whose pattern happens to contain "cd" but path is absolute is allowed (exit 0)', a6.code === 0 && a6.out.trim() === '');
+
+const a7 = runHook('grep -n "x" file --with-something');
+ok('command with no cd at all is allowed regardless of relative path (exit 0)', a7.code === 0 && a7.out.trim() === '');
+
+const a8 = runHook('cd /abs/app && grep -n "x" /abs/app/foo.txt');
+ok('cd <abs> && grep with an absolute-path argument is allowed (exit 0)', a8.code === 0 && a8.out.trim() === '');
+
+const a9 = runHook('cd /abs/app && grep -n "x" -r --include=*.js');
+ok('cd <abs> && grep with only flags/patterns (no file arg) is allowed (exit 0)', a9.code === 0 && a9.out.trim() === '');
+
+// --- #134 follow-up: Finding 1 - heredoc bodies are DATA, not statements ---
+const h1 = runHook(`cat > setup.sh <<'EOF'\ncd /some/dir\ngrep -n pattern file.txt\nEOF\n`);
+ok('heredoc body (cd + grep as literal data) is allowed, not parsed as statements (exit 0)', h1.code === 0 && h1.out.trim() === '');
+
+const h2 = runHook(`bash -c 'cat' <<EOF\ncd app\ngrep -n x foo.txt\nEOF\n`);
+ok('heredoc fed to a command is allowed, its body is data not executed statements (exit 0)', h2.code === 0 && h2.out.trim() === '');
+
+const h3 = runHook(`cat > setup.sh <<'EOF'\nsome literal data\nEOF\ncd app && grep -n x foo.txt`);
+ok('a REAL cd + grep violation outside a heredoc on the same command still blocks (exit 2)', h3.code === 2 && /search-hygiene/.test(h3.out));
+
+// --- #134 follow-up: Finding 2 - grouping containers must not hide the violation ---
+const g1 = runHook('(cd app && grep -n x foo.txt)');
+ok('subshell-wrapped cd + grep is blocked (exit 2)', g1.code === 2 && /search-hygiene/.test(g1.out));
+
+const g2 = runHook('{ cd app; grep -n x foo.txt; }');
+ok('brace-group-wrapped cd + grep is blocked (exit 2)', g2.code === 2 && /search-hygiene/.test(g2.out));
+
+const g3 = runHook('for d in */; do cd "$d" && grep -n x foo.txt; cd ..; done');
+ok('loop-body cd + grep is blocked (exit 2)', g3.code === 2 && /search-hygiene/.test(g3.out));
+
+const g4 = runHook('(cd /abs && npm test)');
+ok('subshell-wrapped cd <abs> && npm test (no read verb) is still allowed (exit 0)', g4.code === 0 && g4.out.trim() === '');
+
+// --- #134 follow-up: Finding 3 - `--` end-of-options marker must not swallow the file ---
+const d1 = runHook('cd app && grep -- -x foo.txt');
+ok('cd + grep -- -x <relative file> is blocked (exit 2), `--` must not eat the file arg', d1.code === 2 && /search-hygiene/.test(d1.out) && /foo\.txt/.test(d1.out));
+
+// --- #134 follow-up: Finding 4 - rg-specific value flags must not misattribute the file ---
+const f1 = runHook('cd app && rg -g "*.js" TODO src/foo.js');
+ok('cd + rg -g <glob> <pattern> <relative file> reports the real file, not the pattern (exit 2)', f1.code === 2 && /search-hygiene/.test(f1.out) && /src\/foo\.js/.test(f1.out) && !/`TODO`/.test(f1.out));
+
+console.log(`✓ search-guard: ${passed} assertions passed`);

package/plugins/trailhead/hooks/trailhead-secret-read-guard.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+// trailhead-secret-read-guard.js: PreToolUse(Read|Bash) hook.
+// Restores the `.env`/`.secrets` read protection that three `Read()` deny
+// permission rules used to provide, before they were removed (#135). A
+// `Read()` deny rule is a PERMISSION rule: under bypass permissions it still
+// falls back to a manual approval prompt on Claude Code 2.1.259's new
+// `cd-compound-read` check (the same headless-breaking prompt that
+// trailhead-search-guard.js exists to route around, see #132-#134). This hook
+// gets the same outcome — a secret file can never be read — as a HOOK `deny`
+// decision instead, which does not arm that permission-layer prompt at all.
+//
+// Denies:
+//   (a) a Read tool call whose `file_path` basename is a secret pattern; and
+//   (b) a Bash command that touches a secret path as a plain positional file
+//       operand, an option value (`--file=.env`, `-f .env`, glued `-f.env`),
+//       or a `<` (or glued `<file`) redirect target.
+// A "secret pattern" is a basename that is exactly `.env`, exactly
+// `.secrets`, or matches `.env.<anything>` (e.g. `.env.local`,
+// `.env.production`), matched CASE-INSENSITIVELY (`.ENV`/`.SECRETS` are the
+// same file on macOS/Windows). Matched on basename, so `app/.env` and
+// `./.env.local` are caught the same as a bare `.env`.
+//
+// #135 follow-up (adversarial review found real false negatives/positives in
+// the original naive `.split(/\s+/)` Bash tokenizer):
+//   - Finding 1 (glued shell metacharacters, e.g. `cat .env|grep KEY`,
+//     `cat .env;echo done`, `cat .env&&echo done`) is fixed by scanning
+//     QUOTE-AWARE, STATEMENT-BASED top-level statements (splitStatements),
+//     which split on operator characters regardless of surrounding
+//     whitespace. `bash -c "cat .env"` / `eval "cat .env"` are fixed by
+//     recursing into the quoted sub-command's text as a nested command.
+//   - Finding 2 (glued short-option value, `cat -f.env`) is fixed by also
+//     testing a value-flag's glued suffix (`token.slice(2)`).
+//   - Finding 3 (bare `.env` inside quoted prose, e.g. `git commit -m
+//     "document .env usage"`) is fixed by a quote-aware tokenizer that keeps
+//     a multi-word quoted phrase as ONE opaque token, never splitting it into
+//     separate words.
+//   - Finding 4 (a quoted grep PATTERN that happens to look like a secret
+//     path, e.g. `grep ".env" config.txt`) is fixed by routing search verbs
+//     (grep/rg/ag/sed/awk) through the shared pattern-positional-skipping
+//     walk, so the pattern is never mistaken for the file operand.
+//   - Finding 5 (case sensitivity) is fixed by lowercasing the basename
+//     before the pattern test.
+// The quote-aware tokenizer/statement-splitter and the search-verb handling
+// are shared with trailhead-search-guard.js via lib/shell-scan.js, so the two
+// guards can never drift into two divergent tokenizers again.
+//
+// Deliberately best-effort on the Bash leg, like the sibling guards: not a
+// full shell parser. It does not care about `cd` shape at all (that is
+// trailhead-search-guard.js's job) — it only asks "does any token here
+// resolve to a secret path", so `cd app && grep x pubspec.yaml` is allowed
+// (no secret token present) regardless of the `cd`.
+//
+// Denies with exit 2 + {"decision":"block","code":...,"reason":...} — same
+// wire shape the sibling guards use for a block, which the PreToolUse hook
+// contract treats as a deny. Allows everything else. Crash-safe: any error ->
+// exit 0 (never wedge the user's workflow). Self-contained (its own
+// dependency is the sibling lib/ module, no external packages). Pure
+// function exported for tests; runs as a hook when executed directly.
+
+const {
+  basename,
+  stripQuotes,
+  splitStatements,
+  tokenize,
+  SEARCH_VERB_CONFIG,
+  scanArgsSkippingPattern,
+} = require('./lib/shell-scan.js');
+
+// --- path helpers ------------------------------------------------------------
+
+// A basename is a "secret pattern" when it is exactly `.env`, exactly
+// `.secrets`, or `.env.<something>` (e.g. `.env.local`, `.env.production`),
+// matched case-insensitively (`.ENV`/`.Secrets` are the same file on a
+// case-insensitive filesystem). Near-misses like `env.sample` (no leading
+// dot) or `.environment` (no dot after `.env`) must NOT match.
+function isSecretBasename(name) {
+  if (!name) return false;
+  const lower = String(name).toLowerCase();
+  if (lower === '.env' || lower === '.secrets') return true;
+  return /^\.env\..+$/.test(lower);
+}
+
+function isSecretPathArg(t) {
+  const bare = stripQuotes(t);
+  if (!bare) return false;
+  return isSecretBasename(basename(bare));
+}
+
+// --- Bash leg: quote-aware, statement-based scan -----------------------------
+
+// Flags that take a separate-token value which could itself be the secret
+// path (`-f .env`, `--file .env`), or (finding #2) a GLUED value on a short
+// flag (`-f.env`). Kept small and generic: this hook doesn't need to model
+// every tool's flag surface, just the common file-value shapes.
+const VALUE_FLAGS = new Set(['-f', '--file']);
+
+// The pattern-first search verbs (grep/rg/ag/sed/awk), shared with
+// trailhead-search-guard.js. Their first positional is a PATTERN, not a file
+// operand, so it must be skipped before scanning for a secret FILE argument
+// (finding #4: `grep ".env" config.txt` reads config.txt, not `.env`).
+const SEARCH_VERBS = new Set(Object.keys(SEARCH_VERB_CONFIG));
+
+// `bash -c "<cmd>"` / `sh -c "<cmd>"` / `zsh -c "<cmd>"` / `eval "<cmd>"`: the
+// secret read hides inside that quoted string, invisible to a plain
+// positional/flag scan (finding #1), so these are recursed into as a nested
+// command.
+const SHELL_DASH_C_VERBS = new Set(['bash', 'sh', 'zsh', 'ksh']);
+
+// A token can still end with a glued shell metacharacter that splitStatements
+// doesn't split on (grouping punctuation left over from a subshell/brace
+// group, or a stray backtick closing a command substitution). Strip a run of
+// these from the token's tail before basename-testing it, so e.g. the last
+// token of `(cat .env)` (`.env)`) still resolves to `.env`.
+const TRAILING_PUNCT_RE = /[|;&`)}]+$/;
+function stripTrailingPunct(t) {
+  return String(t).replace(TRAILING_PUNCT_RE, '');
+}
+
+// Scan one already-tokenized statement's argument tokens (verb NOT stripped)
+// for a secret path used as a plain positional, an option value
+// (`--file=.env`, `-f .env`, glued `-f.env`), or a `<` (or glued `<file`)
+// redirect target. Returns the offending token or null.
+function scanTokensForSecretPath(tokens) {
+  for (let i = 0; i < tokens.length; i++) {
+    const t = stripTrailingPunct(tokens[i]);
+    if (!t) continue;
+
+    // `<` redirect: glued (`<.secrets`) or separate-token (`< .secrets`).
+    // Never confuse with a heredoc `<<TAG` (already stripped out by
+    // splitStatements upstream, but be defensive).
+    if (t.startsWith('<') && !t.startsWith('<<')) {
+      const glued = t.slice(1);
+      if (glued) {
+        if (isSecretPathArg(glued)) return glued;
+        continue;
+      }
+      const next = i + 1 < tokens.length ? stripTrailingPunct(tokens[i + 1]) : null;
+      if (next && isSecretPathArg(next)) return next;
+      continue;
+    }
+
+    if (t.startsWith('-') && t !== '-') {
+      // `--flag=value` form.
+      const eq = t.indexOf('=');
+      if (eq > 0) {
+        const val = t.slice(eq + 1);
+        if (isSecretPathArg(val)) return val;
+        continue;
+      }
+      // `-f value` / `--file value` (separate-token value).
+      if (VALUE_FLAGS.has(t)) {
+        const next = i + 1 < tokens.length ? stripTrailingPunct(tokens[i + 1]) : null;
+        if (next && isSecretPathArg(next)) return next;
+        continue;
+      }
+      // Glued short-option value (`-f.env`, finding #2): a single-dash flag
+      // whose flag letter is a known value flag, with the value glued
+      // directly onto it.
+      if (!t.startsWith('--') && t.length > 2) {
+        const shortFlag = t.slice(0, 2);
+        if (VALUE_FLAGS.has(shortFlag)) {
+          const glued = t.slice(2);
+          if (isSecretPathArg(glued)) return glued;
+        }
+      }
+      continue; // some other flag: not itself a file operand
+    }
+
+    // Plain positional (file operand or search pattern token).
+    if (isSecretPathArg(t)) return t;
+  }
+  return null;
+}
+
+// Does `stmtTokens` invoke `bash -c "<cmd>"` / `sh -c "<cmd>"` / `eval
+// "<cmd>"` (etc.)? If so, return the inner command TEXT (quotes stripped, not
+// yet re-tokenized) so the caller can recurse into it as a nested command.
+// Best-effort: only the common single-quoted-argument idiom, not every way a
+// shell can be told to execute a string.
+function extractNestedCommand(stmtTokens) {
+  if (!stmtTokens.length) return null;
+  const bin = basename(stmtTokens[0]);
+  if (bin === 'eval') {
+    const rest = stmtTokens.slice(1);
+    if (!rest.length) return null;
+    return stripQuotes(rest.join(' '));
+  }
+  if (SHELL_DASH_C_VERBS.has(bin)) {
+    const cIdx = stmtTokens.indexOf('-c');
+    if (cIdx === -1 || cIdx + 1 >= stmtTokens.length) return null;
+    return stripQuotes(stmtTokens.slice(cIdx + 1).join(' '));
+  }
+  return null;
+}
+
+// Scan a single top-level statement for a secret path. Recurses into a
+// bash -c/eval quoted sub-command first (finding #1), routes grep/rg/ag/sed/
+// awk through the shared pattern-skipping walk (finding #4), and falls back
+// to the plain per-token walk for everything else (cat, head, redirects,
+// etc.).
+function scanStatementForSecretPath(stmt) {
+  const tokens = tokenize(stmt);
+  if (!tokens.length) return null;
+
+  const nested = extractNestedCommand(tokens);
+  if (nested) {
+    const hit = scanBashForSecretPath(nested);
+    if (hit) return hit;
+    // fall through: also scan the wrapper statement's own tokens (e.g. a
+    // stray `-f .env` on the wrapper itself) for defence in depth.
+  }
+
+  const bin = basename(tokens[0]);
+  if (SEARCH_VERBS.has(bin)) {
+    return scanArgsSkippingPattern(tokens.slice(1), SEARCH_VERB_CONFIG[bin], isSecretPathArg);
+  }
+  return scanTokensForSecretPath(tokens);
+}
+
+// Walk the command's top-level statements (quote-aware; `|`, `;`, `&&`,
+// `||`, and newlines all split, even with no surrounding whitespace, e.g.
+// `cat .env|grep KEY`) looking for a secret path used as a plain positional,
+// an option value, or a `<` redirect target. Returns the offending token
+// (quotes/punctuation not necessarily stripped) or null. Best-effort: not a
+// full shell parser.
+function scanBashForSecretPath(cmd) {
+  const statements = splitStatements(cmd);
+  for (const stmt of statements) {
+    const hit = scanStatementForSecretPath(stmt);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+// --- top-level detection -----------------------------------------------------
+
+// Detect a secret-file read across a Read or Bash tool call. Returns
+// { path } on a hit, or null. Pure, exported for tests.
+function detectSecretRead(toolName, toolInput) {
+  const input = toolInput || {};
+  if (toolName === 'Read') {
+    const p = input.file_path;
+    if (p && isSecretPathArg(String(p))) return { path: String(p) };
+    return null;
+  }
+  if (toolName === 'Bash') {
+    const cmd = input.command || '';
+    const hit = scanBashForSecretPath(cmd);
+    return hit ? { path: hit } : null;
+  }
+  return null;
+}
+
+function block(hit) {
+  const reason =
+    `trailhead secret-read guard: blocked a read of secret file \`${hit.path}\` ` +
+    '(.env / .env.* / .secrets). This replaces the Read() deny permission rules ' +
+    "removed in #135 with a hook-level deny, so secrets stay unreadable without " +
+    "arming Claude Code 2.1.259's cd-compound-read approval prompt. If this file " +
+    'genuinely needs inspecting, do so outside the agent session.';
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'SECRET_READ_BLOCKED', reason }));
+  process.exit(2);
+}
+
+function run(data) {
+  let parsed;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    process.exit(0); // unparseable input: nothing to gate
+  }
+  try {
+    const hit = detectSecretRead(parsed.tool_name, parsed.tool_input);
+    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 = { detectSecretRead };

package/plugins/trailhead/hooks/trailhead-secret-read-guard.test.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Tests for trailhead-secret-read-guard.js. Run: node trailhead-secret-read-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+const { detectSecretRead } = require('./trailhead-secret-read-guard.js');
+
+const HOOK = path.join(__dirname, 'trailhead-secret-read-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Run the hook end-to-end: pipe {tool_name, tool_input} JSON on stdin, capture {code, out}.
+function runHook(toolName, toolInput) {
+  const input = JSON.stringify({ tool_name: toolName, tool_input: toolInput });
+  try {
+    const out = execFileSync('node', [HOOK], { input });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString(), err: (e.stderr || '').toString() };
+  }
+}
+
+// --- pure seam: detectSecretRead ---
+
+// --- DENY cases ---
+ok('Read .env is denied', !!detectSecretRead('Read', { file_path: '.env' }));
+ok('Read config/.env.local is denied', !!detectSecretRead('Read', { file_path: 'config/.env.local' }));
+ok('Read .secrets is denied', !!detectSecretRead('Read', { file_path: '.secrets' }));
+ok('Bash cat .env is denied', !!detectSecretRead('Bash', { command: 'cat .env' }));
+ok('Bash cat < .secrets is denied', !!detectSecretRead('Bash', { command: 'cat < .secrets' }));
+ok('Bash grep -n KEY .env.production is denied', !!detectSecretRead('Bash', { command: 'grep -n KEY .env.production' }));
+ok('Bash cat app/.env.local is denied', !!detectSecretRead('Bash', { command: 'cat app/.env.local' }));
+ok('Bash cat --file=.env is denied', !!detectSecretRead('Bash', { command: 'cat --file=.env' }));
+
+// --- ALLOW cases (no false positives) ---
+ok('Read src/app.ts is allowed', !detectSecretRead('Read', { file_path: 'src/app.ts' }));
+ok('Bash grep -n x pubspec.yaml is allowed', !detectSecretRead('Bash', { command: 'grep -n x pubspec.yaml' }));
+ok('Bash cat README.md is allowed', !detectSecretRead('Bash', { command: 'cat README.md' }));
+ok('Bash cd app && grep x pubspec.yaml is allowed (not a secret; search-guard governs the cd shape)',
+  !detectSecretRead('Bash', { command: 'cd app && grep x pubspec.yaml' }));
+ok('Read env.sample (near-miss) is allowed', !detectSecretRead('Read', { file_path: 'env.sample' }));
+ok('Read .environment (near-miss) is allowed', !detectSecretRead('Read', { file_path: '.environment' }));
+
+// --- #135 follow-up: Finding 1 - glued shell metacharacters must not bypass detection ---
+ok('Bash cat .env|grep KEY is denied (glued pipe)', !!detectSecretRead('Bash', { command: 'cat .env|grep KEY' }));
+ok('Bash cat .env;echo done is denied (glued semicolon)', !!detectSecretRead('Bash', { command: 'cat .env;echo done' }));
+ok('Bash cat .env&&echo done is denied (glued &&)', !!detectSecretRead('Bash', { command: 'cat .env&&echo done' }));
+ok('Bash bash -c "cat .env" is denied (quoted sub-command)', !!detectSecretRead('Bash', { command: 'bash -c "cat .env"' }));
+ok('Bash eval "cat .env" is denied (quoted sub-command)', !!detectSecretRead('Bash', { command: 'eval "cat .env"' }));
+
+// --- #135 follow-up: Finding 2 - glued short-option value must not bypass detection ---
+ok('Bash cat -f.env is denied (glued short-flag value)', !!detectSecretRead('Bash', { command: 'cat -f.env' }));
+
+// --- #135 follow-up: Finding 3 - bare .env inside quoted prose must not false-positive ---
+ok('Bash git commit -m "document .env usage" is allowed (quoted prose, not a file operand)',
+  !detectSecretRead('Bash', { command: 'git commit -m "document .env usage"' }));
+ok('Bash echo "See .env for config" >> README.md is allowed (quoted prose)',
+  !detectSecretRead('Bash', { command: 'echo "See .env for config" >> README.md' }));
+ok('Bash cat ".env" is still denied (a quoted LONE path is still a secret path)',
+  !!detectSecretRead('Bash', { command: 'cat ".env"' }));
+
+// --- #135 follow-up: Finding 4 - quoted grep pattern must not false-positive ---
+ok('Bash grep ".env" config.txt is allowed (the read target is config.txt, not the pattern)',
+  !detectSecretRead('Bash', { command: 'grep ".env" config.txt' }));
+ok("Bash grep '.env' config.txt is allowed (single-quoted pattern)",
+  !detectSecretRead('Bash', { command: "grep '.env' config.txt" }));
+ok('Bash grep -n KEY .env.production is still denied (secret is the FILE operand, not the pattern)',
+  !!detectSecretRead('Bash', { command: 'grep -n KEY .env.production' }));
+
+// --- #135 follow-up: Finding 5 - case-insensitivity (same file on macOS/Windows) ---
+ok('Read .ENV is denied (case-insensitive)', !!detectSecretRead('Read', { file_path: '.ENV' }));
+ok('Bash cat .SECRETS is denied (case-insensitive)', !!detectSecretRead('Bash', { command: 'cat .SECRETS' }));
+ok('Read ENV.SAMPLE (near-miss) is still allowed regardless of case', !detectSecretRead('Read', { file_path: 'ENV.SAMPLE' }));
+ok('Read .ENVIRONMENT (near-miss) is still allowed regardless of case', !detectSecretRead('Read', { file_path: '.ENVIRONMENT' }));
+
+// --- end-to-end hook wire format ---
+const d1 = runHook('Read', { file_path: '.env' });
+ok('hook denies Read(.env) end-to-end (exit 2, block decision)', d1.code === 2 && /"decision":"block"/.test(d1.out));
+
+const d2 = runHook('Bash', { command: 'cat .env' });
+ok('hook denies Bash(cat .env) end-to-end (exit 2, block decision)', d2.code === 2 && /"decision":"block"/.test(d2.out));
+
+const a1 = runHook('Read', { file_path: 'src/app.ts' });
+ok('hook allows Read(src/app.ts) end-to-end (exit 0, no output)', a1.code === 0 && a1.out.trim() === '');
+
+const a2 = runHook('Bash', { command: 'cd app && grep x pubspec.yaml' });
+ok('hook allows Bash(cd app && grep x pubspec.yaml) end-to-end (exit 0, no output)', a2.code === 0 && a2.out.trim() === '');
+
+// --- crash safety ---
+const crash1 = runHook('Read', undefined);
+ok('missing tool_input never crashes (exit 0)', crash1.code === 0);
+
+console.log(`✓ secret-read-guard: ${passed} assertions passed`);

package/plugins/trailhead/skills/_shared/configuration-reference.md

@@ -74,6 +74,8 @@ On **trivial/small** the engine surfaces **one consolidated skip offer** and act
 
 **Never in the offer** (always kept, whatever the size or the answer): atomic `Refs:` commits, running the tests / the plan's verification criterion, the post-commit self-check, `bug`'s Diagnose (a confirmed root cause is mandatory before Fix), and Resolve. `effort` scales *redundant heavy* work to the change; it never drops a correctness check.
 
+**`auto` has no config surface.** The autonomous run (`/trailhead:auto`, `../trailhead-work/references/auto.md`) takes no key here, by decision: it changes neither `effort` nor `models.*` (orthogonal to both). Its safety rail is hardcoded always-on, never a toggle, and its stop/go boundary is the same `choices.md` one-line test every other engine step uses (delegate options run without the confirm gate; a human-necessary choice is always set aside), so there is nothing to configure separately.
+
 Example `config.json` (same shape for the project `.trailhead/config.json` and the global `~/.claude/trailhead/config.json`):
 ```json
 { "models": { "plan": "claude-opus-4-8", "execute": "claude-sonnet-5" }, "tdd": "seams", "acceptance": { "browser": "auto" } }

package/plugins/trailhead/skills/_shared/substrate-commands.md

@@ -153,7 +153,7 @@ gh issue list --label "trailhead:map-<n>" --state open --json number --jq 'lengt
 gh issue view <map> --json body --jq .body
 ```
 
-**When to refresh the body.** On structural events: a map is charted or exhausted (a map appears or disappears), a whiteboard ticket is born or resolved. And on demand via `/trailhead:dashboard`. NOT on every map-ticket resolve: that churns a pinned issue's notifications, and the native progress bar already tracks map-ticket progress on its own. The whiteboard has no native progress bar, so its ticket birth/close does refresh the dashboard.
+**When to refresh the body.** On structural events: a map is charted or exhausted (a map appears or disappears), a whiteboard ticket is born or resolved. And on demand via `/trailhead:dashboard`. NOT on every map-ticket resolve: that churns a pinned issue's notifications, and the native progress bar already tracks map-ticket progress on its own. The whiteboard has no native progress bar, so its ticket birth or close refreshes the dashboard, except a `quick`-born ticket (born and resolved in one session) refreshes at the handoff (Resolve, or pause), not at creation.
 
 ## First-use repo setup (do ALL THREE, every chart or adopt, never skip any)
 1. Create any missing labels with `gh label create` (all eighteen: `trailhead:map`, `trailhead:codebase`, `trailhead:conventions`, `trailhead:dashboard`, `trailhead:ticket`, the six type labels, `trailhead:blocked`, `trailhead:seed`, `trailhead:out-of-scope`, `trailhead:superseded`, `trailhead:unverified`, `trailhead:fog`, `trailhead:whiteboard`).

package/plugins/trailhead/skills/_shared/substrate.md

@@ -7,7 +7,7 @@ The tracker is GitHub via the `gh` CLI (already authenticated). **Never post a s
 | Map | an issue with label `trailhead:map`. **Not pinned** (the 3 pinned slots are the repo-scoped [dashboard](../trailhead-view/SKILL.md#render-the-dashboard-dashboard) + codebase + conventions): open maps are found via the `trailhead:map` label and listed in the pinned dashboard, so a repo's maps stay one click away without contending for a slot. **When a map is exhausted** (destination reached: no open tickets and no fog left), **ask the user whether to close the map issue**: on a yes, `gh issue close` it (a closed issue is still the durable record) and refresh the dashboard so it drops off; on a no, leave it open. Never close a map unprompted; there is no pin to free either way. Each map's **tickets** share a **`trailhead:map-<n>` label** (n = the map's issue number) that scopes its frontier; the map issue itself is found by its number and does not carry it. |
 | Codebase | a **single per-repo** issue with label `trailhead:codebase`: the distilled codebase map (architecture, stack, conventions, decisions embodied, risks, test/build). It's repo-scoped: **shared by every map of this repo, owned by none**, so it survives when a map is finished. Each map's Notes *links* it (never re-inlines it). Not a `trailhead:ticket`, so it's off the frontier. Written at adopt; a **greenfield map** (`/trailhead:new`) has no code to map at chart, so it's created **later, once the repo has substantial code** (e.g. after the first build tickets land), via the Codebase map technique. **Kept fresh at Resolve**: when a resolved `build`/`bug` ticket **materially changes** the map (a new module or layer, a new dependency/integration, a new seam, a changed build/test command, a new convention), **patch the affected facet of this issue in place** as part of Resolve, one or two lines, not a re-run of the fan-out. Cosmetic or in-facet changes leave it alone; a full re-map is only for major drift. |
 | Conventions | a **single per-repo** issue with label `trailhead:conventions`: the project's **way of working**, readable by everyone. Repo-scoped and linked from every map's Notes, like Codebase. It opens with a small machine-read header the engine obeys, then human prose. Header keys (defaults **bold**): `git:` **`main`** \| `pr` (commit straight to `main`, or feature branch + PR) · `release:` **`command`** \| `auto` (never release without an explicit command, or release automatically per the project's flow) · `isolation:` **`none`** \| `worktree` \| `clone` (work in the current checkout; or give each executing ticket its own `git worktree` + `trailhead/t<n>` branch; or a dedicated per-ticket **clone** at `../<repo>-t<n>` for **path-bound apps a worktree can't build**, e.g. React Native/Expo with a local `node_modules`; see [Working as a team](teamwork.md#working-as-a-team)). **`worktree`/`clone` imply a branch per ticket even under `git: main`** (git won't check the trunk out twice); the branch integrates to the trunk per `git:` at Resolve. Under **`none`** two in-progress tickets with overlapping `Scope:` **serialise** (the second holds at claim). Below the header: the standing "how we work here" notes. **Filled at chart/adopt by a brief conventions brainstorming** (see the Invocation modes), not a `trailhead:ticket`, off the frontier. |
-| Dashboard | a **single per-repo** issue with label `trailhead:dashboard`: the pinned index of the whole trailhead surface. Repo-scoped and permanent, like Codebase and Conventions, and it occupies the **fixed 3rd pinned slot** alongside them (`gh api graphql` `pinIssue` mutation on its node id). It holds: a link to **every open `trailhead:map`** (GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it does not recompute per-ticket progress), the **whiteboard** as a section (or a link to the `/trailhead:whiteboard` view), and dynamic **counts** (untriaged inbox, whiteboard frontier size). **Created and pinned at the first chart/adopt**, then **rewritten on structural events** (a map is charted or exhausted, i.e. a map appears or disappears; a whiteboard ticket is born or resolved) **and on demand** via `/trailhead:dashboard`. **Not rewritten on every *map* ticket resolve** (that would churn a pinned issue and its notifications; each map's native progress bar already tracks its per-ticket progress, but the whiteboard has no progress bar, so its ticket birth/close does refresh the dashboard). **An exhausted-but-open map** (destination reached, but its issue never closed) is flagged `exhausted · closeable` here via a cheap per-map `0 open scoped issues?` pre-filter confirmed against remaining fog, and the render offers to close it (recurring across the dashboard render and the read-only self-heal entry points, never auto-closing), so a missed exhaustion moment gets a second chance. See [The dashboard](../trailhead-view/SKILL.md#render-the-dashboard-dashboard). |
+| Dashboard | a **single per-repo** issue with label `trailhead:dashboard`: the pinned index of the whole trailhead surface. Repo-scoped and permanent, like Codebase and Conventions, and it occupies the **fixed 3rd pinned slot** alongside them (`gh api graphql` `pinIssue` mutation on its node id). It holds: a link to **every open `trailhead:map`** (GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it does not recompute per-ticket progress), the **whiteboard** as a section (or a link to the `/trailhead:whiteboard` view), and dynamic **counts** (untriaged inbox, whiteboard frontier size). **Created and pinned at the first chart/adopt**, then **rewritten on structural events** (a map is charted or exhausted, i.e. a map appears or disappears; a whiteboard ticket is born or resolved) **and on demand** via `/trailhead:dashboard`. **Not rewritten on every *map* ticket resolve** (that would churn a pinned issue and its notifications; each map's native progress bar already tracks its per-ticket progress, but the whiteboard has no progress bar, so a whiteboard ticket's birth or close refreshes the dashboard, with one timing exception: a `quick`-born ticket, born and resolved in one session, refreshes at its handoff (Resolve, or pause), not at creation). **An exhausted-but-open map** (destination reached, but its issue never closed) is flagged `exhausted · closeable` here via a cheap per-map `0 open scoped issues?` pre-filter confirmed against remaining fog, and the render offers to close it (recurring across the dashboard render and the read-only self-heal entry points, never auto-closing), so a missed exhaustion moment gets a second chance. See [The dashboard](../trailhead-view/SKILL.md#render-the-dashboard-dashboard). |
 | Ticket | a child issue with label `trailhead:ticket` + exactly one **type** label: `trailhead:decision` / `trailhead:research` / `trailhead:prototype` / `trailhead:build` / `trailhead:bug` / `trailhead:task`, plus its map's `trailhead:map-<n>` label and native sub-issue edge (see Child→map link). **A `trailhead:whiteboard` ticket carries none of the map wiring** (no `trailhead:map-<n>`, no sub-issue edge, no `Parent:`); see [The whiteboard](../trailhead-view/SKILL.md#render-the-whiteboard-whiteboard). |
 | Child→map link | three views of one fact, wired in the same pass (like a blocker): a `Parent: <map name>(link)` line in the ticket body (human-readable); a **native sub-issue** edge to the map (`gh api --method POST repos/{owner}/{repo}/issues/<map>/sub_issues -F sub_issue_id=<ticket .id>`, the structure GitHub renders); and the map's **`trailhead:map-<n>` label** on the ticket (the queryable key that scopes its map's frontier). See [Multiple maps on one repo](multi-map.md#multiple-maps-on-one-repo-parking--concurrency). **A whiteboard ticket has none of the three** (it belongs to no map). |
 | Path scope (monorepo) | an optional `Scope: <path>[, <path>…]` line in the ticket body naming the package/dir(s), or **submodule path(s)**, the ticket works in. It sharpens the [undeclared-coupling check](teamwork.md#working-as-a-team) (disjoint scopes parallelize safely), scopes build/test to the affected package, and scopes an `isolation: worktree` worktree's commits. **List every one it touches** (a ticket spanning two submodules names both). **Omit it in a single-package repo** (the whole tree is the scope); add it only where a repo has independent packages/subtrees or submodules. |

package/plugins/trailhead/skills/_shared/teamwork.md

@@ -44,7 +44,7 @@ Prefer `worktree` whenever more than one session may run on a single clone. On a
 
 ## Pausing & resuming
 Switching away from a ticket mid-work (to clear a blocker, chase an urgent bug, or just stop) must not lose the thread.
-- **Pause** (`/trailhead:pause [note]`): first commit any work-in-progress (atomic) so nothing is stranded, then post a **`PAUSED`** checkpoint comment: what's done, the exact next step, and any local state (branch, **worktree path under `isolation: worktree`**, how to run it). Keep the claim if you'll return soon; **release it** (unassign) if it's open-ended, so someone else can resume; the checkpoint is what makes that safe. If you release, also remove the `.trailhead/session-ticket` marker (SKILL.md Mode 2); if you keep the claim, leave it.
+- **Pause** (`/trailhead:pause [note]`): first commit any work-in-progress (atomic) so nothing is stranded, then post a **`PAUSED`** checkpoint comment: what's done, the exact next step, and any local state (branch, **worktree path under `isolation: worktree`**, how to run it). Keep the claim if you'll return soon; **release it** (unassign) if it's open-ended, so someone else can resume; the checkpoint is what makes that safe. If you release, also remove the `.trailhead/session-ticket` marker (SKILL.md Mode 2); if you keep the claim, leave it. **If the paused ticket is a `trailhead:whiteboard` quick that has deferred its dashboard refresh to a handoff it is not reaching this session** (born by `quick`, resolution refresh not yet done), refresh the dashboard now (full regeneration from the live tracker) so the unfinished quick shows on the pinned index: the read-only renders never rewrite the dashboard body, so pause is what surfaces it.
 - **Resume** (`/trailhead:resume [ticket]`): read the ticket's latest `PAUSED` checkpoint (and the `DISCUSS`/`PLAN` comments above it), then pick up at the recorded next step. Anyone may resume a *released* ticket; a still-claimed one, only its owner. **Re-write the `.trailhead/session-ticket` marker** at the working root (SKILL.md Mode 2 step 2) so the resumed session shows in tooling like the statusline (a released pause removed it); under `isolation: worktree`/`clone`, also re-enter the ticket's recorded workspace.
 - One ticket per session still holds: pausing A to work B ideally means B in a fresh session. If you must switch within one session, checkpoint A first; never leave it half-done and unrecorded.
 

package/plugins/trailhead/skills/_shared/techniques/acceptance-testing.md

@@ -8,7 +8,7 @@ Automated tests prove the code does what the *code* intended; acceptance testing
   - **On a failing step: stop, take note, open the closing ticket then and there.** A failed step is an acceptance finding, not a footnote: record expected-vs-seen, and immediately open the follow-up that will carry it to resolution: a `bug` ticket (with `Regression of:`/`Surfaced from:` as fits), or a fix on this ticket before it resolves if it's small and in-scope. Then ask the human whether to keep going through the remaining steps or stop here. Never silently log a fail and carry on to Resolve.
   - **When only some steps are runnable now** (e.g. a few need a backend deployed first), walk the runnable ones conversationally **now**, and mark the rest **explicitly pending** with what unblocks them, tracked as below. Don't defer the whole UAT just because part of it is blocked.
   - **When the human can only run it later** (on-device, hardware you don't have right now), record the full numbered checklist in the `VERIFY` comment as the durable artifact and mark UAT **explicitly pending**, but the walkthrough stays conversational **when they come to run it**: never shrink it to a vague one-liner ("just check it on the device"), and never let "automated passed" quietly stand in for it. Deferring *where/when* the human runs it is fine; replacing the live step-by-step with a self-serve checklist is not.
-  - **Pending UAT must stay tracked: a closed ticket is not tracking.** Don't resolve/close a user-facing ticket on unconfirmed acceptance and leave the checklist as a comment on the closed issue, where nobody will look. Either **keep the ticket open** until the human confirms the UAT passes (the default: closing on green you didn't see is a premature close), **or**, if the project deliberately batches on-device UAT, spin a follow-up **`task`** that carries the checklist and sits on the frontier until it's run. The pending check must be visible on the tracker, not buried.
+  - **Pending UAT must stay tracked: a closed ticket is not tracking.** Don't resolve/close a user-facing ticket on unconfirmed acceptance and leave the checklist as a comment on the closed issue, where nobody will look. The default is to **keep the ticket open** until the human confirms the UAT passes (closing on green you didn't see is a premature close). **If the human instead accepts closing now and running the UAT later**, you **must open a follow-up ticket before that close** that carries the pending UAT and links back to the parent with a `UAT of: <parent name>(link)` pointer in the body. Route it the way `../choices.md` routes a deferred choice: a **`trailhead:seed`** (kept blocked) when the run is gated on a future external trigger not yet true (hardware you don't have, a device out of reach), or a follow-up **`task`** on the frontier when it's just scheduled or batched work you could pick up any time. Either way the follow-up **carries the full numbered checklist and, when it comes to resolution, runs the guided conversational walkthrough above**, never a self-serve check-off. **Never close a user-facing ticket on deferred UAT with nothing opened**: the parent may close as agreed, but the owed UAT stays visible on the tracker as its own ticket, linked to the parent, until it is actually performed. The pending check must be visible on the tracker, not buried.
 
 Acceptance failures are findings like any other: a `bug` follow-up or a fix on this ticket before it resolves.
 

package/plugins/trailhead/skills/_shared/techniques/codebase-map.md

@@ -1,5 +1,8 @@
 # Codebase map (fan-out)
 One-time at project adoption. Fan out 5 read-only reader subagents in parallel (single message), each owning ONE non-overlapping facet; no facet reads another's territory. Dispatch each reader as the **`trailhead-codebase-map`** agent (read-only by construction); **never** an external-plugin mapper agent that another installed tool registered.
+
+**The repo to map may be handed in by absolute path** (the scan root), so **never assume the current working directory is that repo**: search and read it by absolute path and run git as `git -C <scan root> ...`, and **never `cd` (or `pushd`/`env -C`) into it in any shape** (no `cd <root> && grep <relative>`, no bare `cd <root>` line then a relative read, no heredoc/multi-statement block, and not as a standalone `cd <root>` in an earlier Bash call: the cwd persists across calls). This keeps every read target statically determinable, so a bypass-permissions scan of an out-of-tree repo runs without a manual approval prompt. See **Search-command hygiene** in `../techniques.md`.
+
 - **Architecture**: pattern, layers, data flow, entry points, module seams; where the deep modules live.
 - **Stack & dependencies**: languages, runtime, frameworks, manifests, build/config, external integrations (DBs, APIs, auth, webhooks).
 - **Decisions already embodied / conventions**: style, naming, error handling, the repo's documented standards; patterns a new change must match.

package/plugins/trailhead/skills/_shared/techniques.md

@@ -2,7 +2,7 @@
 
 The ticket engines call these by name. Each technique's full protocol lives in its own file under `techniques/`: **read that file the first time a session needs the technique**, so only the ones in play load into context (don't preload them). They are `trailhead`'s own, self-contained; each technique is dispatched to its **trailhead-owned agent** (`trailhead-<technique>`, shipped as committed `agents/trailhead-*.md`) via the `Agent` tool, with the technique's full protocol injected at spawn.
 
-**Dispatch each technique to its trailhead-owned agent.** Every technique subagent carries its full protocol in the prompt (from its `techniques/` file), so the agent definition stays **thin**: identity + tool policy, model-agnostic. Dispatch each technique to **its own `trailhead-<technique>` agent** (set `subagent_type` accordingly): the Plan step → `trailhead-plan`, Execute → `trailhead-executor`, Research → `trailhead-research`, Code review → `trailhead-code-review`, Debug → `trailhead-debug`, Fix → `trailhead-fix`, Codebase map → `trailhead-codebase-map`, Goal-backward verification → `trailhead-verify`. These agents ship with trailhead (committed `agents/trailhead-*.md`) and are registered wherever trailhead is installed as a Claude Code **plugin** (its `agents/` load automatically), or its agent files are otherwise present as subagent types. **If a `trailhead-<technique>` agent is NOT registered in the current environment** (the `Agent`/`Task` tool reports the type unknown, or it is absent from the available-agents list, as on a skills-only install that did not register the agents), **run that technique inline in the main session**, following its `techniques/` protocol directly. Do **not** divert to a host built-in (`general-purpose`/`Explore`) or any external-plugin agent as the engine target. Inline is a graceful degradation: the technique still runs, only on the session model rather than its `config.models.<key>` pin (the same inline path used when that model equals the session model). The dispatch rule is therefore: the real `trailhead-<technique>` agent when it is registered, else inline in the main session, never a foreign agent. **Pass the `config.models.<key>` model as the `Agent`-tool `model` override at spawn** so config stays authoritative (the `.md` is model-agnostic; the override wins), running inline instead when that model is unset or equals the session model. On Claude Code the `Agent` tool's `model` parameter accepts only the short family aliases (`opus` / `sonnet` / `haiku` / `fable`), not the full ids `config.models.*` stores, so **map the configured id to its family alias only for the literal `model` value passed at spawn**: `claude-opus-*` -> `opus`, `claude-sonnet-*` -> `sonnet`, `claude-haiku-*` -> `haiku`, `claude-fable-*` -> `fable`; if an id matches none of these, don't guess: warn and inherit the session model (per `configuration-reference.md`). The alias names a family, not a version, so the host resolves it to that family's current model: the exact version the id pinned cannot be conveyed to the `Agent` tool and is not honoured at subagent spawn. **Keep the inline-vs-subagent decision on the full id**, running inline only when `config.models.<key>` is unset or its full id equals the session model's, never on the alias, so a deliberate same-family but different-version pin (e.g. `claude-opus-5` under a `claude-opus-4-8` session) still dispatches instead of collapsing to inline. (Codex projects `models.codex.*`, OpenAI ids, separately and is unaffected by this.) **Never dispatch to an external-plugin agent** (a `gsd-*`, `*-reviewer`, `*-researcher`, `*-mapper`, or similarly named agent another installed tool registered): it follows *its own* protocol and artifact conventions (a foreign code-review agent writes its own review file, not trailhead's `VERIFY` ticket comment), silently swapping trailhead's engine for another tool's. Host built-ins (`Explore` / `general-purpose`) stay available in general but are **no longer the engine-dispatch target**. The tool policy is baked into each agent's `tools:` field, mirroring the old split: **read-only** (`trailhead-plan`, `trailhead-code-review`, `trailhead-codebase-map`, `trailhead-verify`: reads, searches, runs tests; no Edit/Write) vs **full** (`trailhead-executor`, `trailhead-research`, `trailhead-debug`, `trailhead-fix`: can Edit/Write/commit). On a `subagentToolkit == none` host there is no fan-out and this is moot: every technique runs inline in the one session. (Codex is **not** such a host: it has the native multi_agent toolkit, so techniques fan out there too, dispatched by `agent_type` to the projected `~/.codex/agents/trailhead-*.toml`; see the Codex adapter's §D.)
+**Dispatch each technique to its trailhead-owned agent.** Every technique subagent carries its full protocol in the prompt (from its `techniques/` file), so the agent definition stays **thin**: identity + tool policy, model-agnostic. Dispatch each technique to **its own `trailhead-<technique>` agent** (set `subagent_type` accordingly): the Plan step → `trailhead-plan`, Execute → `trailhead-executor`, Research → `trailhead-research`, Code review → `trailhead-code-review`, Debug → `trailhead-debug`, Fix → `trailhead-fix`, Codebase map → `trailhead-codebase-map`, Goal-backward verification → `trailhead-verify`. These agents ship with trailhead (committed `agents/trailhead-*.md`) and are registered wherever trailhead is installed as a Claude Code **plugin** (its `agents/` load automatically), or its agent files are otherwise present as subagent types. **If a `trailhead-<technique>` agent is NOT registered in the current environment** (the `Agent`/`Task` tool reports the type unknown, or it is absent from the available-agents list, as on a skills-only install that did not register the agents), **run that technique inline in the main session**, following its `techniques/` protocol directly. Do **not** divert to a host built-in (`general-purpose`/`Explore`) or any external-plugin agent as the engine target. Inline is a graceful degradation: the technique still runs, only on the session model rather than its `config.models.<key>` pin (the same inline path used when that model equals the session model). The dispatch rule is therefore: the real `trailhead-<technique>` agent when it is registered, else inline in the main session, never a foreign agent. **Pass the `config.models.<key>` model as the `Agent`-tool `model` override at spawn** so config stays authoritative (the `.md` is model-agnostic; the override wins), running inline instead when that model is unset or equals the session model. On Claude Code the `Agent` tool's `model` parameter accepts only the short family aliases (`opus` / `sonnet` / `haiku` / `fable`), not the full ids `config.models.*` stores, so **map the configured id to its family alias only for the literal `model` value passed at spawn**: `claude-opus-*` -> `opus`, `claude-sonnet-*` -> `sonnet`, `claude-haiku-*` -> `haiku`, `claude-fable-*` -> `fable`; if an id matches none of these, don't guess: warn and inherit the session model (per `configuration-reference.md`). The alias names a family, not a version, so the host resolves it to that family's current model: the exact version the id pinned cannot be conveyed to the `Agent` tool and is not honoured at subagent spawn. **Keep the inline-vs-subagent decision on the full id**, running inline only when `config.models.<key>` is unset or its full id equals the session model's, never on the alias, so a deliberate same-family but different-version pin (e.g. `claude-opus-5` under a `claude-opus-4-8` session) still dispatches instead of collapsing to inline. (Codex projects `models.codex.*`, OpenAI ids, separately and is unaffected by this.) **Never dispatch to an external-plugin agent** (a `gsd-*`, `*-reviewer`, `*-researcher`, `*-mapper`, or similarly named agent another installed tool registered): it follows *its own* protocol and artifact conventions (a foreign code-review agent writes its own review file, not trailhead's `VERIFY` ticket comment), silently swapping trailhead's engine for another tool's. Host built-ins (`Explore` / `general-purpose`) stay available in general but are **no longer the engine-dispatch target**. The tool policy is baked into each agent's `tools:` field, mirroring the old split: **read-only** (`trailhead-plan`, `trailhead-code-review`, `trailhead-codebase-map`, `trailhead-verify`: reads, searches, runs tests; no Edit/Write) vs **full** (`trailhead-executor`, `trailhead-research`, `trailhead-debug`, `trailhead-fix`: can Edit/Write/commit). **Search-command hygiene (every fan-out subagent, and any built-in `Explore`/`general-purpose` fan-out the engine leans on).** Prefer the Grep and Read tools over shelling out to search or read a file; when a Bash `grep`/read is genuinely needed, pass the path as an **explicit argument** (`grep -niE "<patterns>" <abs>/<file>`, `wc -l <abs>/<file>`) and run git as `git -C <abs> ...`. **Never `cd` (or `pushd`/`env -C`) into the target directory first, in any shape**: not `cd <abs> && grep <relative>`, not a bare `cd <abs>` line followed by a relative `grep`/`wc` on the next line or after a `;`, not inside a heredoc or any other multi-statement block, and not as its own separate Bash call or turn (the shell working directory persists across Bash calls, so a standalone `cd <abs>` still leaves a later relative read non-static). Any `cd` makes the post-`cd` working directory non-static, so under bypass permissions with a `Read()` deny rule the harness cannot resolve the read target against the allow rules and falls back to a manual approval prompt (defeating headless operation); a path-explicit target (absolute-path argument, `git -C`) stays statically determinable and runs uninterrupted regardless of how the statements are separated. When the engine spawns a built-in `Explore`/`general-purpose` search, state this rule in its spawn prompt. On a `subagentToolkit == none` host there is no fan-out and this is moot: every technique runs inline in the one session. (Codex is **not** such a host: it has the native multi_agent toolkit, so techniques fan out there too, dispatched by `agent_type` to the projected `~/.codex/agents/trailhead-*.toml`; see the Codex adapter's §D.)
 
 **Reviews never block the session (engine-wide, every host).** The three **review** techniques, **Code review** (build/bug Verify), **Goal-backward verification** (build/bug Verify), and **Cross-AI plan review** (build Plan), always run as a **background job collected by polling**, never a blind open-ended blocking wait. This is a hard default: not a `config` toggle, and not a Codex-only or fallback posture. Because trailhead works one ticket at a time and Resolve depends on the review's outcome, "background" here means a **poll loop with a one-line progress note, the session responsive and interruptible between polls**, the outcome always awaited; what is banned is the blind freeze, never "proceed without the result." On Claude Code the `Agent` tool already backgrounds the review and notifies on completion, so poll its progress instead of awaiting it blindly; on Codex, collect it through the §D bounded-wait poll loop (external plan-review CLIs via §H). **Acceptance testing is excluded**: it is interactive by design (guided UAT / browser-drive with the user in the loop), not a blind wait to background.