@marcomigozzi/trailhead 0.7.0 → 0.8.0

package/plugins/trailhead/hooks/lib/shell-scan.js

@@ -0,0 +1,247 @@
+'use strict';
+// shell-scan.js: shared quote-aware shell scanning helpers, extracted from
+// trailhead-search-guard.js (#135 follow-up) so trailhead's Bash-command
+// guards share ONE tokenizer/statement-splitter instead of drifting copies.
+// trailhead-secret-read-guard.js's original Bash leg used a naive
+// `.split(/\s+/)` tokenizer over the WHOLE command string, which let glued
+// shell metacharacters (`cat .env|grep KEY`, `cat .env;echo done`) slip past
+// detection entirely (a false negative in a security guard) and let a bare
+// `.env` inside multi-word quoted prose (`"document .env usage"`) trip a
+// false positive. This module's `splitStatements` + `tokenize` fix both: the
+// former is quote-aware and splits on operator characters regardless of
+// surrounding whitespace, the latter keeps a multi-word quoted phrase as ONE
+// opaque token instead of splitting it into separate words.
+//
+// Consumers: trailhead-search-guard.js and trailhead-secret-read-guard.js.
+// Self-contained, no external dependencies. Best-effort, like the guards that
+// use it: not a full shell parser, just enough to close their known gaps.
+
+// --- path helpers ------------------------------------------------------------
+
+function basename(p) {
+  const s = String(p).split('/');
+  return s[s.length - 1];
+}
+
+// --- quoting -----------------------------------------------------------------
+
+// Strip a single pair of enclosing quotes: the WHOLE token must start AND end
+// with the same quote character. A multi-word quoted phrase kept as one token
+// by tokenize() (below) round-trips through this to its bare content
+// (spaces and all) - callers testing that bare content against a basename
+// pattern then correctly see prose, not a path, unless the phrase IS exactly
+// a path (e.g. `".env"` -> `.env`, still flagged by design).
+function stripQuotes(t) {
+  const s = String(t);
+  if ((s.startsWith('"') && s.endsWith('"') && s.length >= 2) ||
+      (s.startsWith("'") && s.endsWith("'") && s.length >= 2)) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+// --- heredoc bodies ------------------------------------------------------------
+
+// Matches a heredoc introducer anywhere it can appear on a line: `<<TAG`,
+// `<<'TAG'`, `<<"TAG"`, and `<<-TAG` (which also allows the terminator line to
+// be indented with leading tabs). Captures the operator's `-` and the tag
+// (quoted or bare) separately.
+const HEREDOC_RE = /<<(-?)\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z0-9_]+))/;
+
+// A heredoc BODY is literal data (e.g. a script being written to a file), not
+// shell statements executed in the current shell. Scan the command line by
+// line; whenever a line introduces a heredoc, skip every following line up to
+// and including the matching terminator line before it ever reaches the
+// statement splitter below. Handles multiple heredocs on the same command and
+// both quoted and unquoted tags. Best-effort: not a full shell parser.
+function stripHeredocBodies(cmd) {
+  const lines = String(cmd).split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    out.push(line);
+    let m;
+    // A single line can introduce more than one heredoc (`cmd <<A <<B`); walk
+    // left to right and skip each body in turn.
+    while ((m = HEREDOC_RE.exec(line))) {
+      const dashStrip = m[1] === '-';
+      const tag = m[2] || m[3] || m[4];
+      line = line.slice(m.index + m[0].length); // keep scanning the rest of this line for more `<<TAG`s
+      if (!tag) break;
+      // Skip lines until the terminator: an exact match, or (for `<<-`) the
+      // tag preceded only by tabs.
+      while (i + 1 < lines.length) {
+        i++;
+        const body = lines[i];
+        const term = dashStrip ? body.replace(/^\t+/, '') : body;
+        if (term === tag) break; // terminator line: consumed, not a candidate statement either
+        // else: heredoc data line, deliberately NOT pushed to `out` - it must
+        // never become a candidate statement.
+      }
+    }
+  }
+  return out.join('\n');
+}
+
+// --- statement splitting -------------------------------------------------------
+
+// Split a shell string into top-level statements on `&&`, `||`, `;`, `|`, and
+// newlines, respecting single/double quotes (so a separator INSIDE a quoted
+// argument, e.g. a grep pattern, does not fracture the statement). Heredoc
+// bodies are stripped first (see stripHeredocBodies) so literal data written
+// via `<<TAG` is never mistaken for statements. Splitting is purely
+// character-driven (not whitespace-driven), so a glued separator with no
+// surrounding spaces (`cat .env|grep KEY`, `cat .env;echo done`) still splits
+// correctly. Best-effort: not a full shell parser, just enough to avoid the
+// common false splits.
+function splitStatements(cmd) {
+  const s = stripHeredocBodies(String(cmd));
+  const stmts = [];
+  let cur = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inSingle) {
+      cur += c;
+      if (c === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      cur += c;
+      if (c === '\\' && i + 1 < s.length) { cur += s[++i]; continue; } // escaped char stays literal
+      if (c === '"') inDouble = false;
+      continue;
+    }
+    if (c === "'") { inSingle = true; cur += c; continue; }
+    if (c === '"') { inDouble = true; cur += c; continue; }
+    if (c === '\\' && i + 1 < s.length) { cur += c + s[++i]; continue; }
+    if (c === '&' && s[i + 1] === '&') { stmts.push(cur); cur = ''; i++; continue; }
+    if (c === '|' && s[i + 1] === '|') { stmts.push(cur); cur = ''; i++; continue; }
+    if (c === ';' || c === '|' || c === '\n') { stmts.push(cur); cur = ''; continue; }
+    cur += c;
+  }
+  stmts.push(cur);
+  return stmts.map((t) => t.trim()).filter(Boolean);
+}
+
+// --- tokenizing ----------------------------------------------------------------
+
+// Quote-aware whitespace tokenizer: splits a statement on UNQUOTED
+// whitespace, keeping a `"..."`/`'...'` span - even a MULTI-WORD one - as a
+// single opaque token (quotes are kept in the token; stripQuotes() unwraps
+// them). This is what keeps quoted prose like `"document .env usage"` safe:
+// the whole phrase is one token, so a bare `.env` glued mid-phrase is never a
+// separate candidate token, while a lone quoted path like `".env"` still
+// round-trips to the bare `.env` via stripQuotes for basename testing.
+// Mirrors splitStatements' escape handling (`\"` inside a double-quoted span
+// stays literal, never closes the quote early). Best-effort: not a full shell
+// parser (a real shell also strips quotes/joins adjacent quoted+bare runs
+// into one word; this keeps the surrounding quotes intact instead, which is
+// enough for the callers' basename tests).
+function tokenize(stmt) {
+  const s = String(stmt).trim();
+  const tokens = [];
+  let cur = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inSingle) {
+      cur += c;
+      if (c === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      cur += c;
+      if (c === '\\' && i + 1 < s.length) { cur += s[++i]; continue; }
+      if (c === '"') inDouble = false;
+      continue;
+    }
+    if (c === "'") { inSingle = true; cur += c; continue; }
+    if (c === '"') { inDouble = true; cur += c; continue; }
+    if (c === '\\' && i + 1 < s.length) { cur += c + s[++i]; continue; }
+    if (/\s/.test(c)) {
+      if (cur) { tokens.push(cur); cur = ''; }
+      continue;
+    }
+    cur += c;
+  }
+  if (cur) tokens.push(cur);
+  return tokens;
+}
+
+function skipEnvPrefix(tokens) {
+  let i = 0;
+  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
+  return i;
+}
+
+// --- search-verb argument scanning ----------------------------------------
+
+// grep/rg/ag/sed/awk take a PATTERN (or script/program) as their first
+// positional. Shared between the search guard (which skips the pattern before
+// flagging a relative FILE arg) and the secret-read guard (which skips the
+// pattern before flagging a SECRET FILE arg), so e.g. `grep ".env" config.txt`
+// is never mistaken for a `.env` read: the FILE operand is config.txt, the
+// PATTERN just happens to look like a secret path.
+const GREP_VALUE_FLAGS = new Set([
+  '-e', '-f', '-A', '-B', '-C', '-m', '-D',
+  '--include', '--exclude', '--exclude-dir', '--exclude-from',
+  '--after-context', '--before-context', '--context', '--max-count',
+]);
+
+// ripgrep has several value-taking flags GNU grep doesn't (glob/type filters,
+// column limits); without these, scanning treats their value as a plain
+// positional and misattributes it as the pattern/file in the block reason.
+const RG_VALUE_FLAGS = new Set([
+  ...GREP_VALUE_FLAGS,
+  '-g', '--glob', '-t', '--type', '-T', '--type-not', '-M', '--max-columns',
+]);
+
+const SEARCH_VERB_CONFIG = {
+  grep: { patternFirst: true, valueFlags: GREP_VALUE_FLAGS, patternFlags: new Set(['-e']) },
+  rg: { patternFirst: true, valueFlags: RG_VALUE_FLAGS, patternFlags: new Set(['-e']) },
+  ag: { patternFirst: true, valueFlags: GREP_VALUE_FLAGS, patternFlags: new Set(['-e']) },
+  sed: { patternFirst: true, valueFlags: new Set(['-e', '-f']), patternFlags: new Set(['-e']) },
+  awk: { patternFirst: true, valueFlags: new Set(['-f', '-v']), patternFlags: new Set() },
+};
+
+// Walk a verb's argument tokens (verb itself already stripped), skipping
+// flags (and their separate-token values), an explicit `--` end-of-options
+// marker (which must not itself swallow the next real positional), and the
+// leading pattern/script positional when the verb has one (`config.patternFirst`).
+// Returns the first token for which `isMatch(token)` is true, or null.
+// Generic over the predicate so both guards can drive it with their own
+// notion of "interesting" (a relative file arg vs. a secret path arg).
+function scanArgsSkippingPattern(args, config, isMatch) {
+  let patternConsumed = !config.patternFirst;
+  let afterDashDash = false; // once seen, every remaining token is positional, never a flag
+  for (let j = 0; j < args.length; j++) {
+    const t = args[j];
+    if (!afterDashDash && t === '--') { afterDashDash = true; continue; }
+    if (!afterDashDash && t.startsWith('-') && t !== '-') {
+      if (config.valueFlags.has(t)) {
+        j++; // consume its separate-token value
+        if (config.patternFlags && config.patternFlags.has(t)) patternConsumed = true;
+      }
+      continue;
+    }
+    if (!patternConsumed) { patternConsumed = true; continue; } // leading pattern/script positional
+    if (isMatch(t)) return t;
+  }
+  return null;
+}
+
+module.exports = {
+  basename,
+  stripQuotes,
+  stripHeredocBodies,
+  splitStatements,
+  tokenize,
+  skipEnvPrefix,
+  GREP_VALUE_FLAGS,
+  RG_VALUE_FLAGS,
+  SEARCH_VERB_CONFIG,
+  scanArgsSkippingPattern,
+};

package/plugins/trailhead/hooks/lib/shell-scan.test.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Tests for shell-scan.js. Run: node shell-scan.test.js
+const assert = require('assert');
+const {
+  basename,
+  stripQuotes,
+  splitStatements,
+  tokenize,
+  scanArgsSkippingPattern,
+  SEARCH_VERB_CONFIG,
+} = require('./shell-scan.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- basename ---
+ok('basename strips leading dirs', basename('a/b/.env') === '.env');
+ok('basename passes through a bare name', basename('.env') === '.env');
+
+// --- stripQuotes ---
+ok('stripQuotes unwraps a double-quoted token', stripQuotes('".env"') === '.env');
+ok('stripQuotes unwraps a single-quoted token', stripQuotes("'.env'") === '.env');
+ok('stripQuotes leaves a bare token alone', stripQuotes('.env') === '.env');
+
+// --- splitStatements: glued metacharacters (no surrounding whitespace) ---
+ok('splitStatements splits a glued pipe', JSON.stringify(splitStatements('cat .env|grep KEY')) === JSON.stringify(['cat .env', 'grep KEY']));
+ok('splitStatements splits a glued semicolon', JSON.stringify(splitStatements('cat .env;echo done')) === JSON.stringify(['cat .env', 'echo done']));
+ok('splitStatements splits a glued &&', JSON.stringify(splitStatements('cat .env&&echo done')) === JSON.stringify(['cat .env', 'echo done']));
+ok('splitStatements keeps a quoted separator intact', JSON.stringify(splitStatements('grep "a;b" f.txt')) === JSON.stringify(['grep "a;b" f.txt']));
+
+// --- tokenize: quoted multi-word phrase stays ONE token ---
+ok('tokenize keeps a multi-word double-quoted phrase as one token',
+  JSON.stringify(tokenize('git commit -m "document .env usage"')) ===
+  JSON.stringify(['git', 'commit', '-m', '"document .env usage"']));
+ok('tokenize keeps a multi-word single-quoted phrase as one token',
+  JSON.stringify(tokenize("echo 'a b c'")) === JSON.stringify(['echo', "'a b c'"]));
+ok('tokenize round-trips a lone quoted path via stripQuotes',
+  stripQuotes(tokenize('cat ".env"')[1]) === '.env');
+ok('tokenize handles an escaped quote inside a double-quoted span without closing early',
+  JSON.stringify(tokenize('grep "a\\"b" f.txt')) === JSON.stringify(['grep', '"a\\"b"', 'f.txt']));
+
+// --- scanArgsSkippingPattern: search-verb pattern-positional skipping ---
+const isDotEnv = (t) => stripQuotes(t) === '.env';
+ok('scanArgsSkippingPattern skips the pattern positional (grep ".env" config.txt allows)',
+  scanArgsSkippingPattern(['".env"', 'config.txt'], SEARCH_VERB_CONFIG.grep, isDotEnv) === null);
+ok('scanArgsSkippingPattern still finds a secret FILE operand after the pattern',
+  scanArgsSkippingPattern(['-n', 'KEY', '.env'], SEARCH_VERB_CONFIG.grep, isDotEnv) === '.env');
+
+console.log(`✓ shell-scan: ${passed} assertions passed`);

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

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// trailhead-search-guard.js: PreToolUse(Bash) hook.
+// Structural fix for the recurring #132 -> #133 -> #134 defect: the prose
+// search-command-hygiene ban (never `cd` then read/search a RELATIVE path) is
+// present in every engine agent and in `_shared/techniques.md`, but a subagent
+// under load still emits the banned shape, and the resulting relative read is
+// non-static, so a `Read()` deny rule under bypass permissions falls back to a
+// manual approval prompt (defeating headless operation). Prose hardening keeps
+// regressing, so this hook makes the shape structurally impossible instead of
+// merely discouraged.
+//
+// Blocks a SINGLE Bash command string that both:
+//   (a) changes the working directory - a `cd <dir>`, `pushd <dir>`, or
+//       `env -C <dir>` statement - joined to other statements via `&&`, `;`,
+//       `|`, or a newline (i.e. NOT the sole statement); AND
+//   (b) a later statement in that same command reads/searches a RELATIVE path
+//       via a read/search verb (grep, rg, ag, cat, head, tail, wc, nl, sed,
+//       awk, less, more, or `git grep`/`git log`/`git show`/`git diff`
+//       without a `-C`).
+//
+// KNOWN LIMITATION (do not try to catch this here): a *standalone* `cd <abs>`
+// in one Bash call followed by a relative read in a LATER, separate call
+// relies on the shell's persisted cwd, which this stateless per-call hook
+// cannot see. Blocking a lone `cd` would be far too aggressive (a legitimate,
+// common shape) so it is deliberately left to the prose directive.
+//
+// Blocks with exit 2 + {"decision":"block","code":...,"reason":...}; 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 functions exported for tests; runs as a hook
+// when executed directly.
+
+// --- tokenizing -------------------------------------------------------------
+// The quote-aware tokenizer/statement-splitter (splitStatements, tokenize,
+// stripQuotes, basename) and the search-verb pattern-positional-skipping
+// machinery (SEARCH_VERB_CONFIG, scanArgsSkippingPattern) are shared with
+// trailhead-secret-read-guard.js via lib/shell-scan.js (#135 follow-up), so
+// the two guards can never drift into two divergent tokenizers.
+const {
+  basename,
+  stripQuotes,
+  splitStatements,
+  tokenize,
+  skipEnvPrefix,
+  SEARCH_VERB_CONFIG,
+  scanArgsSkippingPattern,
+} = require('./lib/shell-scan.js');
+
+// A leading grouping/keyword token that can precede the "real" first word of a
+// statement without itself being that word: `(cd app && ...)`, `{ cd app; ... }`,
+// `do cd "$d" && ...` (loop body), `then cd x`, `else cd x`. Stripping these
+// (and a `(`/`{` glued directly onto the next token, e.g. `(cd`) lets the
+// `cd`/`pushd`/read-verb checks below see the actual command even when it's
+// wrapped in a subshell, brace group, or loop/conditional body.
+const LEADING_GROUP_TOKENS = new Set(['(', '{', 'do', 'then', 'else']);
+// A trailing grouping/keyword token (or glued punctuation) that can follow the
+// real last word of a statement: `grep ... foo.txt)`, `grep ... foo.txt;`,
+// `grep ... foo.txt }`, `... ; fi`, `... ; done`.
+const TRAILING_GROUP_TOKENS = new Set([')', '}', ';', 'fi', 'done']);
+
+// Strip a single leading grouping/keyword token and a single trailing
+// grouping/keyword token (or glued punctuation) from an already-tokenized
+// statement, so subshells, brace groups, and loop/conditional bodies don't
+// hide a `cd`/read-verb from the checks that follow. Best-effort: handles the
+// common shapes, not a full shell parser.
+function normalizeStatementTokens(tokens) {
+  let t = tokens;
+  if (t.length && LEADING_GROUP_TOKENS.has(t[0])) {
+    t = t.slice(1);
+  } else if (t.length && (t[0][0] === '(' || t[0][0] === '{') && t[0].length > 1) {
+    t = [t[0].slice(1), ...t.slice(1)];
+  }
+  if (t.length) {
+    const last = t[t.length - 1];
+    if (TRAILING_GROUP_TOKENS.has(last)) {
+      t = t.slice(0, -1);
+    } else {
+      const stripped = last.replace(/[)};]+$/, '');
+      if (stripped !== last) {
+        t = stripped ? [...t.slice(0, -1), stripped] : t.slice(0, -1);
+      }
+    }
+  }
+  return t;
+}
+
+// A relative-path FILE argument: not absolute, not stdin (`-`), not a dynamic
+// value we cannot resolve statically (fail open on those, same posture as the
+// commit-guard's UNEXPANDABLE handling).
+function isRelativeFileArg(t) {
+  const bare = stripQuotes(t);
+  if (!bare || bare === '-') return false;
+  if (bare.startsWith('/')) return false;
+  if (bare.startsWith('$') || bare.includes('$(') || bare.includes('`')) return false;
+  return true;
+}
+
+// --- per-verb argument scanning ---------------------------------------------
+
+// grep/rg/ag/sed/awk (the pattern-first search verbs) come from the shared
+// lib (see lib/shell-scan.js); cat/head/tail/wc/nl/less/more take only FILE
+// positionals and are specific to this guard's read-hygiene check.
+const VERB_CONFIG = {
+  ...SEARCH_VERB_CONFIG,
+  cat: { patternFirst: false, valueFlags: new Set() },
+  head: { patternFirst: false, valueFlags: new Set(['-n', '-c']) },
+  tail: { patternFirst: false, valueFlags: new Set(['-n', '-c']) },
+  wc: { patternFirst: false, valueFlags: new Set() },
+  nl: { patternFirst: false, valueFlags: new Set() },
+  less: { patternFirst: false, valueFlags: new Set() },
+  more: { patternFirst: false, valueFlags: new Set() },
+};
+
+// Walk a verb's argument tokens (verb itself already stripped) for the first
+// relative FILE argument found, via the shared pattern/flag-skipping walker.
+function scanArgsForRelativeFile(args, config) {
+  return scanArgsSkippingPattern(args, config, isRelativeFileArg);
+}
+
+// `git grep`/`git log`/`git show`/`git diff` WITHOUT a `-C` (or --work-tree):
+// git grep has a pattern positional like plain grep; log/show/diff don't, so
+// only their pathspec after an explicit `--` is checked (the common idiom),
+// keeping this conservative rather than guessing at ref vs. path tokens.
+function detectGitRelativeRead(tokens) {
+  let i = 1; // tokens[0] === 'git'
+  let hasC = false;
+  while (i < tokens.length && tokens[i].startsWith('-')) {
+    if ((tokens[i] === '-C' || tokens[i] === '--work-tree') && !tokens[i].includes('=')) {
+      hasC = true;
+      i += 2;
+      continue;
+    }
+    if (tokens[i].startsWith('--work-tree=') || tokens[i].startsWith('--git-dir=')) {
+      if (tokens[i].startsWith('--work-tree=')) hasC = true;
+      i++;
+      continue;
+    }
+    i++;
+  }
+  if (hasC) return null; // already path-explicit
+  const sub = tokens[i];
+  if (!['grep', 'log', 'show', 'diff'].includes(sub)) return null;
+  i++;
+  if (sub === 'grep') {
+    return scanArgsForRelativeFile(tokens.slice(i), VERB_CONFIG.grep);
+  }
+  const dashIdx = tokens.indexOf('--', i);
+  if (dashIdx === -1) return null;
+  return scanArgsForRelativeFile(tokens.slice(dashIdx + 1), { patternFirst: false, valueFlags: new Set() });
+}
+
+// Is this statement itself a read/search verb call with a relative file arg?
+function readViolationInStatement(stmt) {
+  const tokens = normalizeStatementTokens(tokenize(stmt));
+  const i = skipEnvPrefix(tokens);
+  const rest = tokens.slice(i);
+  if (rest.length === 0) return null;
+  const bin = basename(rest[0]);
+  if (bin === 'git') {
+    const file = detectGitRelativeRead(rest);
+    return file ? { verb: `git ${rest[1] || ''}`.trim(), file } : null;
+  }
+  const config = VERB_CONFIG[bin];
+  if (!config) return null;
+  const file = scanArgsForRelativeFile(rest.slice(1), config);
+  return file ? { verb: bin, file } : null;
+}
+
+// Does this statement change the shell's persistent cwd (`cd`/`pushd`)? `env
+// -C` is deliberately excluded here: it changes the directory only for the ONE
+// command it wraps, not the rest of the script, so it's handled separately
+// as a same-statement check, not this cross-statement sticky flag.
+function isCdOrPushdStatement(stmt) {
+  const tokens = normalizeStatementTokens(tokenize(stmt));
+  const i = skipEnvPrefix(tokens);
+  const bin = tokens[i];
+  return bin === 'cd' || bin === 'pushd';
+}
+
+// `env -C <dir> <cmd> …`: the directory change and the read live in the SAME
+// statement (env execs its argument as a single command with that cwd), so
+// this is checked independently of the cross-statement `cwdChanged` flag.
+function envDashCRelativeRead(stmt) {
+  const tokens = tokenize(stmt);
+  let i = skipEnvPrefix(tokens);
+  if (basename(tokens[i]) !== 'env') return null;
+  i++;
+  let foundC = false;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (t === '-C') { foundC = true; i += 2; break; }
+    if (t.startsWith('--chdir=')) { foundC = true; i += 1; break; }
+    if (t.startsWith('-')) { i++; continue; } // some other env flag, best-effort skip
+    break; // reached the wrapped command
+  }
+  if (!foundC) return null;
+  const rest = tokens.slice(i);
+  if (rest.length === 0) return null;
+  const bin = basename(rest[0]);
+  if (bin === 'git') {
+    const file = detectGitRelativeRead(rest);
+    return file ? { verb: 'git', file } : null;
+  }
+  const config = VERB_CONFIG[bin];
+  if (!config) return null;
+  const file = scanArgsForRelativeFile(rest.slice(1), config);
+  return file ? { verb: bin, file } : null;
+}
+
+// --- top-level detection -----------------------------------------------------
+
+// Detect the banned shape across the whole command. Returns
+// { verb, file } on a hit, or null. Pure, exported for tests.
+// KNOWN NARROWER GAP (deliberately not implemented): `cd app && grep -rn TODO`
+// with no path argument at all implicitly searches the (now-relative) cwd,
+// but adding that case risks false-positiving on legitimate stdin-reading
+// commands, so it is left to the prose directive.
+function detectSearchHygieneViolation(cmd) {
+  const statements = splitStatements(cmd);
+  let cwdChanged = false;
+  for (let idx = 0; idx < statements.length; idx++) {
+    const stmt = statements[idx];
+
+    const envHit = envDashCRelativeRead(stmt);
+    if (envHit) return envHit;
+
+    if (cwdChanged) {
+      const hit = readViolationInStatement(stmt);
+      if (hit) return hit;
+    }
+
+    // A `cd`/`pushd` only counts when it is joined to a LATER statement (not
+    // the sole statement) - a lone standalone `cd` is the known limitation
+    // above and must never be blocked here.
+    if (isCdOrPushdStatement(stmt) && idx < statements.length - 1) {
+      cwdChanged = true;
+    }
+  }
+  return null;
+}
+
+function block(hit) {
+  const reason =
+    "trailhead search-hygiene: a 'cd <dir>' (or pushd/env -C) followed by a relative " +
+    `${hit.verb} read (\`${hit.file}\`) makes the read target non-static, which trips the ` +
+    'Read() deny rule under bypass permissions (prompting for manual approval instead of ' +
+    'running headless). Pass explicit paths instead and never cd first: ' +
+    'grep -niE "<patterns>" <abs>/<file>, git -C <abs> ..., or use the Grep/Read tools.';
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'SEARCH_HYGIENE_VIOLATION', 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 {
+    const hit = detectSearchHygieneViolation(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 = { detectSearchHygieneViolation };