@marcomigozzi/trailhead 0.13.0 → 0.15.0

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

@@ -8,13 +8,27 @@
 // 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.
+// Only a NAMED install is gated: installs with no typed name (bare `npm install`,
+// `npm ci`, `install --frozen-lockfile` / `--immutable` with no package, `pip install -r`,
+// `cargo build`, `go mod download`, `bundle install`) and local paths / URLs /
+// VCS refs carry no typed name and pass through. A file-like name (`foo.txt`,
+// `x.tgz`) passes only when it is a path (`./x`, `sub/x`, `/x`, `~/x`) or exists
+// on disk (relative to the command's cwd); otherwise it is a typed name and is gated.
+// The on-disk check resolves against the hook's cwd; it does not follow a
+// preceding `cd` in the same command. Command wrappers (`sudo`, `time`, `env`,
+// `nohup`, `xargs`, `timeout`, `nice`, `stdbuf`, `setsid`, `ionice`, `doas`,
+// `command`, `exec`) are peeled, with their own flags, so `sudo npm install foo`
+// is gated like the bare form. Parsing is quote-aware (shared
+// lib/shell-scan.js): text inside quotes or a heredoc (`echo "x; npm i foo"`) is
+// never a command, and redirections (`2>&1`, `> log`) are never package names.
 // 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.
+// Self-contained (its only dependency is the sibling lib/ module). Pure functions (incl. evaluate) exported for tests
+// and the merged trailhead-bash-guards.js; runs as a hook when executed directly.
+
+const fs = require('fs');
+const path = require('path');
+const { basename, splitStatements, tokenize, stripQuotes, stripRedirections } = require('./lib/shell-scan.js');
 
 const SENTINEL = /(?:^|\s)TRAILHEAD_VERIFIED_INSTALL=1(?:\s|$)/;
 
@@ -37,22 +51,129 @@ const VALUE_FLAGS = new Set([
   '-t', '--target', '--prefix', '--root', '--python', '-d', '--dest',
   '-w', '--workspace', '--registry', '-C', '--directory', '--chdir',
   '--no-binary', '--only-binary',
+  '--filter', '-F', // pnpm workspace selector: its value is a project, not a package
 ]);
 
-function basename(p) {
-  const s = String(p).split('/');
-  return s[s.length - 1];
+// Command wrappers that run the rest of the line as a command, mapped to the
+// flags that consume a SEPARATE-TOKEN value (so it is not read as the command).
+// Attached forms (`-uroot`, `--user=root`, GNU xargs `-i`/`-e`/`-l`) need no entry.
+const WRAPPERS = {
+  sudo: new Set([
+    '-u', '--user', '-g', '--group', '-h', '--host', '-p', '--prompt', '-C', '--close-from',
+    '-U', '--other-user', '-r', '--role', '-t', '--type', '-D', '--chdir', '-R', '--chroot',
+    '-T', '--command-timeout',
+  ]),
+  env: new Set(['-u', '--unset', '-C', '--chdir', '-a', '--argv0']), // -S handled apart
+  time: new Set(['-f', '--format', '-o', '--output']),
+  nohup: new Set(),
+  xargs: new Set([
+    '-n', '--max-args', '-I', '-a', '--arg-file', '-d', '--delimiter', '-E', '-L', '--max-lines',
+    '-P', '--max-procs', '-s', '--max-chars',
+  ]),
+  timeout: new Set(['-s', '--signal', '-k', '--kill-after']), // + one DURATION operand
+  nice: new Set(['-n', '--adjustment']),
+  stdbuf: new Set(['-i', '-o', '-e', '--input', '--output', '--error']),
+  setsid: new Set(),
+  ionice: new Set(['-c', '--class', '-n', '--classdata']),
+  doas: new Set(['-a', '-C', '-u']),
+  command: new Set(), // -v / -V only look a name up: see isLookupFlag
+  exec: new Set(['-a']),
+};
+const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+// How a wrapper flag consumes its value. Returns { next } (value is the NEXT
+// token), { attached } (value is inside this token) or {} (flagless). A short
+// cluster is read like getopt: the first value-taking letter ends it, so `-nu root`
+// takes the next token and `-uroot` carries its value attached.
+function flagValue(f, valueFlags) {
+  if (f.startsWith('--')) {
+    const eq = f.indexOf('=');
+    if (eq !== -1) return { attached: f.slice(eq + 1) };
+    return valueFlags.has(f) ? { next: true } : {};
+  }
+  for (let k = 1; k < f.length; k++) {
+    if (!valueFlags.has('-' + f[k])) continue;
+    return k === f.length - 1 ? { next: true } : { attached: f.slice(k + 1) };
+  }
+  return {};
+}
+
+// `env -S` / `--split-string`: its payload IS the command line, not a flag value.
+function isSplitFlag(f) {
+  if (f.startsWith('--')) return f === '--split-string' || f.startsWith('--split-string=');
+  for (let k = 1; k < f.length; k++) {
+    if (f[k] === 'S') return true;
+    if ('uCa'.includes(f[k])) return false; // value letter first: S is part of its value
+  }
+  return false;
+}
+
+// `command -v` / `-V` (also inside a cluster like `-pv`) only describe a name and
+// execute nothing, so nothing follows that can be an install.
+function isLookupFlag(f) {
+  return !f.startsWith('--') && /[vV]/.test(f);
+}
+
+// The text of an `env -S` payload token. A double-quoted payload (outer quotes
+// stripped) also loses its bash escapes (`\$`, `\``, `\"`, `\\`); single-quoted
+// text is literal. Local on purpose: the shared stripQuotes is left as is.
+function payloadText(payload) {
+  const p = payload || '';
+  const stripped = stripQuotes(p);
+  const dq = p.length >= 2 && p.startsWith('"') && p.endsWith('"');
+  return dq ? stripped.replace(/\\([$`"\\])/g, '$1') : stripped;
+}
+
+// The real command, past leading `NAME=value` assignments and any (nested) wrapper
+// with its flags. Returns { toks, i }: toks may be rewritten when an `env -S`
+// payload is re-tokenized; i is toks.length when nothing is left.
+function skipWrappers(input) {
+  let toks = input;
+  let i = 0;
+  for (;;) {
+    while (i < toks.length && ENV_ASSIGN.test(toks[i])) i++;
+    const wrapper = basename(toks[i] || '');
+    const valueFlags = WRAPPERS[wrapper];
+    if (!valueFlags) return { toks, i };
+    i++; // past the wrapper
+    while (i < toks.length && toks[i].startsWith('-')) {
+      const f = toks[i++];
+      if (f === '--') break; // end of the wrapper's options
+      if (wrapper === 'env' && isSplitFlag(f)) {
+        const eq = f.indexOf('=');
+        const sIdx = f.indexOf('S');
+        let payload;
+        if (f.startsWith('--')) payload = eq !== -1 ? f.slice(eq + 1) : toks[i++];
+        else payload = sIdx === f.length - 1 ? toks[i++] : f.slice(sIdx + 1);
+        toks = [...tokenize(payloadText(payload)), ...toks.slice(i)];
+        i = 0; // the payload and the rest now form the command line
+        break;
+      }
+      if (wrapper === 'command' && isLookupFlag(f)) return { toks, i: toks.length };
+      if (flagValue(f, valueFlags).next) i++; // consume its separate-token value
+    }
+    if (wrapper === 'timeout' && i < toks.length) i++; // the DURATION operand
+  }
+}
+
+// A file-like name is local only when it is a path or exists on disk. A leading
+// `@` is a scoped npm name, never a path.
+function isLocalFile(t, opts) {
+  if (t.startsWith('@')) return false;
+  if (t.includes('/')) return true;
+  const exists = (opts && opts.exists) || fs.existsSync;
+  return exists(path.resolve((opts && opts.cwd) || process.cwd(), t));
 }
 
 // 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) {
+function isLocalOrUrl(t, ecosystem, opts) {
   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;
+  if (/\.(?:tgz|tar\.gz|whl|gz|zip|txt|toml|lock|cfg)$/.test(t)) return isLocalFile(t, opts);
   return false;
 }
 
@@ -70,12 +191,29 @@ function bareName(t) {
   return n;
 }
 
+// Positional package names among the arguments after the verb (redirections
+// already removed). Quotes are stripped so `"lodash"` is the name `lodash`.
+function collectPackages(args, ecosystem, opts) {
+  const packages = [];
+  for (let j = 0; j < args.length; j++) {
+    const t = args[j];
+    if (t.startsWith('-')) {
+      if (VALUE_FLAGS.has(t)) j++; // consume its separate-token value
+      continue;
+    }
+    const name = stripQuotes(t);
+    if (!name || name === '&' || isLocalOrUrl(name, ecosystem, opts)) continue;
+    const bare = bareName(name);
+    if (bare) packages.push(bare);
+  }
+  return packages;
+}
+
 // 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
+// shell statement. Returns { ecosystem, packages: [names] } or null.
+function detectSegment(stmt, opts) {
+  const { toks, i: start } = skipWrappers(tokenize(stmt));
+  let i = start; // env prefix + sudo/time/env/nohup/xargs
   if (i >= toks.length) return null;
 
   const bin = basename(toks[i]);
@@ -102,27 +240,21 @@ function detectSegment(cmd) {
   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));
-  }
+  const args = stripRedirections(toks.slice(i));
+  // A lockfile install (`--frozen-lockfile`, `--immutable`) carries no positional,
+  // so it yields no package here; a flag never excuses a name typed beside it.
+  const packages = collectPackages(args, ecosystem, opts);
   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);
+// statement, not just the first. splitStatements is quote- and heredoc-aware, so
+// a separator or install text inside quotes / a heredoc body is not a statement.
+// Returns the first statement's hit, or null.
+function detectInstall(cmd, opts) {
+  for (const stmt of splitStatements(cmd)) {
+    const hit = detectSegment(stmt, opts);
     if (hit) return hit;
   }
   return null;
@@ -133,7 +265,7 @@ function isVerified(cmd) {
   return SENTINEL.test(String(cmd));
 }
 
-function block(hit) {
+function blockVerdict(hit) {
   const list = hit.packages.join(', ');
   const reason =
     `trailhead: this ${hit.ecosystem} install names package(s) not yet vetted (${list}). ` +
@@ -142,23 +274,36 @@ function block(hit) {
     '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);
+  return { kind: 'block', payload: { decision: 'block', code: 'UNVETTED_PACKAGE_INSTALL', reason } };
+}
+
+// Pure verdict for one command: {kind:'allow'} or {kind:'block', payload}. Never
+// exits or writes; any internal error falls through to allow.
+function evaluate(cmd, opts) {
+  try {
+    if (isVerified(cmd)) return { kind: 'allow' }; // agent has vetted these
+    const hit = detectInstall(cmd, { cwd: opts && opts.cwd });
+    if (hit) return blockVerdict(hit);
+  } catch {
+    // fall through to allow: a guard must never wedge the workflow
+  }
+  return { kind: 'allow' };
 }
 
 function run(data) {
   let cmd = '';
+  let cwd;
   try {
-    cmd = (JSON.parse(data).tool_input || {}).command || '';
+    const input = JSON.parse(data);
+    cmd = (input.tool_input || {}).command || '';
+    cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : undefined;
   } 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
+  const v = evaluate(cmd, { cwd });
+  if (v.kind === 'block') {
+    process.stdout.write(JSON.stringify(v.payload));
+    process.exit(2);
   }
   process.exit(0);
 }
@@ -173,4 +318,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { detectInstall, isVerified };
+module.exports = { detectInstall, isVerified, evaluate };

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

@@ -4,9 +4,12 @@
 const assert = require('assert');
 const { execFileSync } = require('child_process');
 const path = require('path');
+const fs = require('fs');
+const os = require('os');
 
-const HOOK = path.join(__dirname, 'trailhead-install-guard.js');
-const { detectInstall, isVerified } = require('./trailhead-install-guard.js');
+// TRAILHEAD_GUARD_HOOK re-runs this suite through the merged trailhead-bash-guards.js.
+const HOOK = process.env.TRAILHEAD_GUARD_HOOK || path.join(__dirname, 'trailhead-install-guard.js');
+const { detectInstall, isVerified, evaluate } = require('./trailhead-install-guard.js');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
@@ -85,6 +88,176 @@ ok('detects install after ; chain', (() => { const d = detectInstall('echo hi; p
 ok('detects install in a piped tail', (() => { const d = detectInstall('true | cargo add serde'); return d && d.packages.includes('serde'); })());
 ok('compound with no install stays null', detectInstall('cd app && npm run build && ls') === null);
 
+// --- unit: lockfile installs, redirections, quoted text (#239) ---
+const heredocDoc = ['cat > /tmp/x.md <<\'EOF\'', '| `pnpm install a 2>&1` | x |', 'EOF'].join('\n');
+const neg239 = [
+  'pnpm install --frozen-lockfile --offline 2>&1',
+  'cd app && pnpm install --frozen-lockfile --offline 2>&1 | tail -5',
+  'pnpm install --frozen-lockfile > /tmp/log',
+  'pnpm install --frozen-lockfile --filter web',
+  'pnpm install --frozen-lockfile',
+  'yarn install --immutable',
+  'bun install --frozen-lockfile',
+  'yarn install --frozen-lockfile',
+  'npm install 2>&1',
+  'echo "done; pnpm install lodash"',
+  'echo "a && npm install foo"',
+  'echo "next: pnpm install then build"',
+  'git commit -m "fix: pnpm install guard | npm i x"',
+  heredocDoc,
+];
+for (const cmd of neg239) {
+  ok(`ignores: ${cmd.split('\n')[0]}`, detectInstall(cmd) === null);
+}
+
+// Redirections and quoting must not hide a real named install, nor leak into the name.
+const pos239 = [
+  ['npm install lodash 2>&1', 'npm', ['lodash']],
+  ['pnpm add vite > /tmp/log', 'npm', ['vite']],
+  ['npm install "lodash"', 'npm', ['lodash']],
+  ['echo ok && npm install lodash', 'npm', ['lodash']],
+  ['echo ok; pip install requests', 'pip', ['requests']],
+  ['pnpm add --filter web vite', 'npm', ['vite']],
+];
+for (const [cmd, eco, names] of pos239) {
+  const d = detectInstall(cmd);
+  ok(`detects exactly: ${cmd}`, d && d.ecosystem === eco && JSON.stringify(d.packages) === JSON.stringify(names));
+}
+
+// A lockfile flag never excuses a typed name: the named package is still gated.
+const posLock = [
+  ['npm i --frozen-lockfile evilpkg', 'evilpkg'],
+  ['pnpm install --frozen-lockfile evilpkg', 'evilpkg'],
+  ['yarn install --immutable evilpkg', 'evilpkg'],
+  ['npm install evilpkg --frozen', 'evilpkg'],
+];
+for (const [cmd, name] of posLock) {
+  const d = detectInstall(cmd);
+  ok(`detects despite lockfile flag: ${cmd}`, d && d.packages.includes(name));
+  const r = runHook(cmd);
+  ok(`blocks despite lockfile flag: ${cmd}`, r.code === 2 && new RegExp(name).test(r.out));
+}
+
+// A bare `&` (background) is never listed as a package name.
+ok('background & is not a package', JSON.stringify((detectInstall('npm install lodash &') || {}).packages) === JSON.stringify(['lodash']));
+
+// --- unit: wrapped installs and file-like names (#255) ---
+const posWrap = [
+  ['sudo npm install lodash', 'lodash'],
+  ['time pip install requests', 'requests'],
+  ['env FOO=1 npm i lodash', 'lodash'],
+  ['nohup npm install lodash', 'lodash'],
+  ['xargs npm install lodash', 'lodash'],
+  ['sudo -u bob npm install lodash', 'lodash'],   // flag with a separate-token value
+  ['sudo -- npm i lodash', 'lodash'],
+  ['sudo -E npm i lodash', 'lodash'],
+  ['env -u HOME npm i lodash', 'lodash'],
+  ['env -C /tmp FOO=1 npm i lodash', 'lodash'],
+  ['time -p pip install requests', 'requests'],
+  ['time -o /tmp/t pip install requests', 'requests'],
+  ['xargs -n 1 npm install lodash', 'lodash'],
+  ['xargs -I {} pip install requests', 'requests'],
+  ['xargs --max-args=1 npm i lodash', 'lodash'],
+  ['sudo env FOO=1 nohup npm i lodash', 'lodash'],   // chain
+  ['FOO=1 sudo -u root time -p pip install requests', 'requests'],
+  ['cd app && sudo npm install lodash', 'lodash'],
+  ['/usr/bin/sudo npm install lodash', 'lodash'],
+  ['sudo -nu root npm i lodash', 'lodash'],      // bundled short flags, value flag last
+  ['sudo -Eu bob npm i lodash', 'lodash'],
+  ['sudo -iu root npm i lodash', 'lodash'],
+  ['sudo -uroot npm i lodash', 'lodash'],        // attached value
+  ['sudo -nE npm i lodash', 'lodash'],           // cluster with no value flag
+  ['env -S "npm i lodash"', 'lodash'],           // split-string payload is the command
+  ['env -S npm i lodash', 'lodash'],
+  ["env -S 'npm i lodash'", 'lodash'],
+  ['env --split-string="npm i lodash"', 'lodash'],
+  ['env --split-string npm i lodash', 'lodash'],
+  ['env -a name npm i lodash', 'lodash'],        // argv0 value, command follows
+  ['env -S "FOO=1 sudo npm i lodash"', 'lodash'],
+];
+for (const [cmd, name] of posWrap) {
+  const d = detectInstall(cmd);
+  ok(`detects wrapped: ${cmd}`, d && d.packages.includes(name));
+}
+const negWrap = [
+  'sudo npm install',
+  'sudo npm ci',
+  'time npm install --frozen-lockfile',
+  'env FOO=1 npm install',
+  'xargs echo npm install foo',     // xargs runs echo
+  'sudo -u bob ls',
+  'sudo',
+  'env',
+  'sudo -u',
+  'sudo -nu root ls',
+  'env -S "ls -la"',
+  'env -S "npm install"',
+];
+for (const cmd of negWrap) {
+  ok(`ignores wrapped: ${cmd}`, detectInstall(cmd) === null);
+}
+
+// A file-like suffix is local only for a path or an existing file.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'install-guard-'));
+fs.writeFileSync(path.join(tmp, 'foo.tgz'), '');
+const inTmp = { cwd: tmp };
+const posFile = ['pip install foo.txt', 'npm install left-pad.toml', 'npm install nope.tgz', 'pip install pkg.whl'];
+for (const cmd of posFile) {
+  const d = detectInstall(cmd, inTmp);
+  ok(`gates absent file-like name: ${cmd}`, d && d.packages.length === 1);
+}
+const negFile = [
+  'pip install ./foo.txt',
+  'pip install sub/req.txt',
+  'pip install /abs/req.txt',
+  'pip install ~/req.txt',
+  'npm install foo.tgz',            // exists in cwd
+];
+for (const cmd of negFile) {
+  ok(`allows path or existing file: ${cmd}`, detectInstall(cmd, inTmp) === null);
+}
+ok('existing file resolved against cwd, not process cwd', detectInstall('npm install foo.tgz', { cwd: os.tmpdir() }) !== null);
+ok('injectable exists check', detectInstall('npm install x.tgz', { exists: () => true }) === null);
+ok('scoped name is never a path', (() => { const d = detectInstall('npm install @scope/pkg.zip', inTmp); return d && d.packages[0] === '@scope/pkg.zip'; })());
+ok('evaluate tolerates null opts', evaluate('npm install lodash', null).kind === 'block');
+const wf = evaluate('npm install foo.tgz', { cwd: tmp });
+ok('evaluate threads cwd (existing file allowed)', wf.kind === 'allow');
+ok('evaluate blocks absent file-like name', evaluate('pip install foo.txt', { cwd: tmp }).kind === 'block');
+const wrapRun = runHook('sudo npm install lodash');
+ok('blocks a sudo-wrapped install end-to-end (exit 2)', wrapRun.code === 2 && /lodash/.test(wrapRun.out));
+const cwdRun = (() => {
+  const input = JSON.stringify({ cwd: tmp, tool_input: { command: 'npm install foo.tgz' } });
+  try { return { code: 0, out: execFileSync('node', [HOOK], { input }).toString() }; } catch (e) { return { code: e.status }; }
+})();
+ok('hook honours input.cwd for the on-disk check (exit 0)', cwdRun.code === 0);
+fs.rmSync(tmp, { recursive: true, force: true });
+
+// Wrappers peeled with their flags: timeout (+ DURATION), nice, stdbuf, setsid, ionice, doas, command, exec.
+const wrapHits = [
+  'timeout 10 npm i x', 'timeout -s KILL 10 npm i x', 'timeout --signal=KILL 5s npm i x',
+  'timeout -k 1 10 npm i x', 'nice npm i x', 'nice -n 5 npm i x', 'nice -n5 npm i x', 'nice -5 npm i x',
+  'command npm i x', 'command -p npm i x', 'exec npm i x', 'exec -a foo npm i x',
+  'doas npm i x', 'doas -u root npm i x', 'setsid npm i x', 'setsid -w npm i x',
+  'ionice -c 3 npm i x', 'stdbuf -oL npm i x', 'stdbuf -o L npm i x',
+  'sudo timeout 10 nice npm i x', 'xargs timeout 10 npm i x', 'timeout -- 10 npm i x',
+  'env -S "env -S \\"npm i lodash\\""',
+  'env -S "env -S \\"env -S \\\\\\"npm i lodash\\\\\\"\\""',
+  "env -S 'npm i lodash'",
+];
+for (const c of wrapHits) ok(`wrapper hit: ${c}`, detectInstall(c) && detectInstall(c).packages.length > 0);
+const wrapMisses = [
+  'timeout 10 ls', 'nice ls', 'command -v npm', 'command -v npm i x', 'command -V npm i x',
+  'command -pv npm i x', 'exec 3>&1', 'exec -a npm ls', 'doas ls',
+  "env -S 'echo \"npm i lodash\"'", 'env -S "echo \\"npm i lodash\\""',
+];
+for (const c of wrapMisses) ok(`wrapper miss: ${c}`, detectInstall(c) === null);
+
+// Known unmodelled gaps (documented, NOT asserted): this guard reads one plain
+// command per statement plus the wrappers it peels, so an install behind
+// `bash -c "..."` / `sh -c "..."`, `$( )`, `eval`, other wrappers (`chrt`,
+// `taskset`, `flock`, `su -c`), or a GNU long-option prefix abbreviation
+// taking a separate value (`timeout --sig KILL 5 ...`) is not seen.
+
 // --- unit: isVerified ---
 ok('sentinel recognised', isVerified('TRAILHEAD_VERIFIED_INSTALL=1 npm install lodash'));
 ok('no sentinel', !isVerified('npm install lodash'));
@@ -106,6 +279,13 @@ ok('non-install allowed (exit 0)', a3.code === 0 && a3.out.trim() === '');
 const a4 = runHook('pip install -r requirements.txt');
 ok('requirements-file install allowed (exit 0)', a4.code === 0 && a4.out.trim() === '');
 
+const a5 = runHook('cd app && pnpm install --frozen-lockfile --offline 2>&1 | tail -5');
+ok('lockfile install with redirection allowed (exit 0)', a5.code === 0 && a5.out.trim() === '');
+const a6 = runHook('echo "done; pnpm install lodash"');
+ok('install text inside echo allowed (exit 0)', a6.code === 0 && a6.out.trim() === '');
+const b3 = runHook('npm install lodash 2>&1');
+ok('named install with redirection still blocks (exit 2)', b3.code === 2 && /lodash/.test(b3.out));
+
 // --- end-to-end: unparseable stdin allowed ---
 const u = (() => {
   try {

package/plugins/trailhead/hooks/trailhead-mockup-link-guard.js

@@ -7,7 +7,14 @@
 // practice (an approval asked with only the project's name, no URL), so this
 // hook blocks an AskUserQuestion that is a mockup-approval ask when the
 // assistant prose immediately before it (no tool call in between) holds no
-// URL or file path.
+// URL or file path. A link carried by the approval question itself (question,
+// header, option label or description) is accepted too.
+// Transcript timing: Claude Code writes the CURRENT assistant message (its
+// text and tool_use blocks) to the transcript only after the tool call
+// completes, so at PreToolUse the prose carrying the link is usually not
+// there yet. The prose check therefore runs only when the pending ask is
+// found in the transcript (by tool_use_id, or as the identical tail ask);
+// otherwise the guard cannot judge and allows.
 // Blocks with exit 2 + {"decision":"block",...}; allows everything else.
 // Fail-OPEN on any error (exit 0): a missing/unreadable transcript or an
 // unexpected shape must never wedge the workflow.
@@ -16,7 +23,7 @@
 // Pure functions are exported for tests; runs as a hook when executed directly.
 
 const fs = require('fs');
-const { hasLink, isMockupApprovalAsk, BLOCK_REASON } = require('./lib/mockup-link.js');
+const { hasLink, isMockupApprovalAsk, askHasLink, BLOCK_REASON } = require('./lib/mockup-link.js');
 
 // Only the transcript tail matters: the prose sits right before the ask.
 const TAIL_BYTES = 512 * 1024;
@@ -25,14 +32,41 @@ const blocksOf = (e) => (Array.isArray(e.message && e.message.content) ? e.messa
 const isPendingAsk = (e) => e.type === 'assistant'
   && blocksOf(e).some((b) => b.type === 'tool_use' && b.name === 'AskUserQuestion');
 
+const mainChain = (entries) => entries.filter((e) => e && (e.type === 'assistant' || e.type === 'user') && !e.isSidechain);
+
+// Index (in the main chain) of the entry holding the pending ask being
+// judged, or -1 when it is not in the transcript yet. With a tool_use id:
+// the assistant entry carrying that id. Without: the last entry, only if it
+// is a pending AskUserQuestion whose input equals toolInput.
+function pendingAskIndex(entries, toolUseId, toolInput) {
+  const main = mainChain(entries);
+  if (toolUseId) {
+    return main.findIndex((e) => e.type === 'assistant'
+      && blocksOf(e).some((b) => b.type === 'tool_use' && b.id === toolUseId));
+  }
+  const i = main.length - 1;
+  if (i < 0 || !isPendingAsk(main[i])) return -1;
+  const same = blocksOf(main[i]).some((b) => b.type === 'tool_use' && b.name === 'AskUserQuestion'
+    && JSON.stringify(b.input) === JSON.stringify(toolInput));
+  return same ? i : -1;
+}
+
 // The assistant prose right before the ask: walk the main-chain entries back
-// from the end, skip the pending AskUserQuestion entries, and collect text
-// blocks until anything else (a user turn, a tool result, another tool call).
-function proseBeforeAsk(entries) {
-  const main = entries.filter((e) => e && (e.type === 'assistant' || e.type === 'user') && !e.isSidechain);
-  let i = main.length - 1;
-  while (i >= 0 && isPendingAsk(main[i])) i--;
+// from the anchor entry (default: the end), skip the pending AskUserQuestion
+// entries (keeping the text that precedes the tool_use inside the anchor
+// entry itself), and collect text blocks until anything else (a user turn, a tool
+// result, another tool call).
+function proseBeforeAsk(entries, anchor) {
+  const main = mainChain(entries);
+  let i = anchor === undefined ? main.length - 1 : anchor;
   const texts = [];
+  // Text blocks in the same entry, before its tool_use, are prose too.
+  if (i >= 0 && main[i] && isPendingAsk(main[i])) {
+    const blocks = blocksOf(main[i]);
+    const firstTool = blocks.findIndex((b) => b.type === 'tool_use');
+    blocks.slice(0, firstTool).filter((b) => b.type === 'text').forEach((b) => texts.push(b.text || ''));
+  }
+  while (i >= 0 && isPendingAsk(main[i])) i--;
   for (; i >= 0; i--) {
     const e = main[i];
     if (e.type !== 'assistant') break;
@@ -73,9 +107,12 @@ function run(data) {
     const payload = JSON.parse(data);
     if (payload.tool_name && payload.tool_name !== 'AskUserQuestion') process.exit(0);
     if (!isMockupApprovalAsk(payload.tool_input)) process.exit(0);
+    if (askHasLink(payload.tool_input)) process.exit(0);
     if (!payload.transcript_path) process.exit(0);
-    const prose = proseBeforeAsk(parseEntries(readTail(payload.transcript_path)));
-    if (!hasLink(prose)) block();
+    const entries = parseEntries(readTail(payload.transcript_path));
+    const idx = pendingAskIndex(entries, payload.tool_use_id, payload.tool_input);
+    if (idx < 0) process.exit(0); // current message not flushed yet: cannot judge
+    if (!hasLink(proseBeforeAsk(entries, idx))) block();
   } catch {
     // fall through to allow: a guard must never wedge the workflow
   }
@@ -92,4 +129,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { isMockupApprovalAsk, hasLink, proseBeforeAsk };
+module.exports = { isMockupApprovalAsk, hasLink, askHasLink, proseBeforeAsk, pendingAskIndex };