@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/plugins/trailhead/hooks/mod/work-state-view.ts

@@ -1,6 +1,7 @@
 // Pure view logic of the trailhead mod: parse the work state file, build the
 // status line and the pipeline stages. No engine calls here, so it is easy to test.
-import type { WorkState } from '../../types'
+import type { AutoRun, RunCounts, WorkState } from '../../types'
+import { RESUME_HINT_STATUS, runLabel, runParts } from './auto-run-view'
 
 export const STEPS = ['discuss', 'plan', 'execute', 'verify', 'resolve', 'paused'] as const
 export const STAGES = ['discuss', 'plan', 'execute', 'verify'] as const
@@ -11,6 +12,7 @@ export type Stage = { name: StageName; status: StageStatus }
 export type Pipeline = { stages: readonly Stage[]; isPaused: boolean }
 
 const ELLIPSIS = '…'
+export const ELSEWHERE = 'in another session'
 
 // Cuts by code point, so a surrogate pair (an emoji in an issue title) is never split.
 export const fit = (text: string, room: number): string => {
@@ -66,17 +68,48 @@ const stableJson = (value: unknown): string => {
   return `{${keys.map(k => `${JSON.stringify(k)}:${stableJson(obj[k])}`).join(',')}}`
 }
 
+// The state belongs to this session (a state with no session counts as its own, like the orphan rule).
+const isOwn = (state: WorkState | null, session: string): boolean =>
+  state !== null && (state.session === null || state.session === session)
+
+// The ticket this session owns across a work-state file shared with other sessions. A state it wrote
+// sets it; one another session wrote leaves it; a missing file clears it only when the last state read
+// was this session's (its own Resolve), so another session's cleanup never drops the mark.
+export const nextOwnTicket = (
+  prev: number | null,
+  lastState: WorkState | null,
+  nextState: WorkState | null,
+  session: string,
+): number | null => {
+  if (nextState !== null) return isOwn(nextState, session) ? nextState.ticket : prev
+  return isOwn(lastState, session) ? null : prev
+}
+
 export const sameValue = (a: unknown, b: unknown): boolean => stableJson(a) === stableJson(b)
 
-export const statusLine = (state: WorkState | null, isOrphaned: boolean): string | undefined => {
-  if (state === null || state.ticket === null) return undefined
+// What the autonomous run adds to the status: the run found beside the main checkout, its scope counts, and
+// whether the resume hint shows. `elsewhere`: the foreign state's session is not known gone, so the
+// status words it neutrally instead of offering to resume it.
+export type RunInfo = { run: AutoRun | null; counts: RunCounts | null; hint: boolean; elsewhere?: boolean }
+
+export const statusLine = (state: WorkState | null, isOrphaned: boolean, info?: RunInfo): string | undefined => {
+  const hint = info?.hint === true ? RESUME_HINT_STATUS : null
+  if (state === null || state.ticket === null) {
+    // Nessuno stato proprio: il run (slot senza sessione) o il suggerimento di ripresa, se ce ne sono.
+    if (hint !== null) return hint
+    return info?.run == null ? undefined : runLabel(info.run, info.counts)
+  }
   const where = state.map === null ? 'whiteboard' : `map #${state.map}`
   const ticket = state.title === null ? `#${state.ticket}` : `#${state.ticket} ${state.title}`
   // No own "trailhead" prefix: the engine already prefixes a plugin's status with its name.
   const parts = [where, ticket]
   if (state.step !== null) parts.push(state.step)
-  if (state.auto) parts.push(`auto ${state.autoDone} done`)
-  if (isOrphaned) parts.push('orphaned, resume?')
+  if (state.auto) {
+    const [first, ...rest] = runParts(info?.run ?? { done: state.autoDone }, info?.counts ?? null)
+    parts.push(`auto ${first}`, ...rest)
+  }
+  if (isOrphaned) parts.push(info?.elsewhere === true ? ELSEWHERE : 'orphaned, resume?')
+  if (hint !== null) parts.push(hint)
   return parts.join(' · ')
 }
 

package/plugins/trailhead/hooks/mod/worktree-porcelain.ts

@@ -0,0 +1,17 @@
+// Foglia senza import, condivisa da work-state-locate e dal run autonomo: il parser di
+// `git worktree list --porcelain` e il tetto dei fallimenti di fila.
+
+// Quanti fallimenti di fila tengono l'ultimo risultato noto prima di azzerarlo.
+export const MAX_FAILURES = 3
+
+// Path and full branch ref of each checkout in `git worktree list --porcelain` (null: detached or bare).
+export const parseWorktreeBranches = (porcelain: string): { path: string; branch: string | null }[] =>
+  porcelain
+    .split(/\n\s*\n/)
+    .map(block => block.split('\n'))
+    .filter(lines => lines.some(line => line.startsWith('worktree /')))
+    .map(lines => {
+      const path = (lines.find(line => line.startsWith('worktree ')) as string).slice('worktree '.length).replace(/(.)\/+$/, '$1')
+      const branch = lines.find(line => line.startsWith('branch '))
+      return { path, branch: branch === undefined ? null : branch.slice('branch '.length) }
+    })

package/plugins/trailhead/hooks/trailhead-bash-guards.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // trailhead-bash-guards.js: PreToolUse(Bash) hook.
-// One process for the five Bash guards (commit, secret, install, search, body)
-// instead of five: each Bash call pays a single node start-up. The guards keep
+// One process for the six Bash guards (commit, secret, install, search, body, labels)
+// instead of six: each Bash call pays a single node start-up. The guards keep
 // their own modules and verdicts; this runner only calls each one's pure
-// evaluate(cmd) in a fixed order (commit, secret, install, search, body).
+// evaluate(cmd) in a fixed order (commit, secret, install, search, body, labels).
 //   - First block wins: its payload goes to stdout and the hook exits 2; later
 //     guards do not run. An earlier advisory keeps its stderr line.
 //   - No block: advisories (secret-guard's "could not scan") surface on stderr
@@ -11,9 +11,9 @@
 //   - Failure posture is unchanged per guard: a throwing guard counts as allow
 //     and the others still run; a guard module that fails to load is skipped
 //     with a one-line stderr warning.
-//   - --guards=<name,...> picks the guards (default: all five). The Codex install
-//     ships no search-guard and registers --guards=commit,secret,install,body.
-//     A missing, empty, malformed or unknown-name list falls back to all five, so
+//   - --guards=<name,...> picks the guards (default: all six). The Codex install
+//     ships no search-guard and registers --guards=commit,secret,install,body,labels.
+//     A missing, empty, malformed or unknown-name list falls back to all six, so
 //     a config typo never disables a guard.
 //   - TRAILHEAD_MOD_GUARDS=<name,...>@<epoch-ms>: the mod (which has ported those
 //     guards) stamps the guards it already ran; a stamp no older than
@@ -22,7 +22,7 @@
 // Crash-safe: unparseable input or any internal error -> exit 0.
 // Self-contained, no dependencies. Pure functions are exported for tests.
 
-const GUARD_ORDER = ['commit', 'secret', 'install', 'search', 'body'];
+const GUARD_ORDER = ['commit', 'secret', 'install', 'search', 'body', 'labels'];
 const MOD_GUARDS_FRESH_MS = 5000;
 const MOD_GUARDS_RE = /^([a-z][a-z0-9-]*(?:,[a-z][a-z0-9-]*)*)@(\d+)$/;
 
@@ -37,7 +37,7 @@ function parseModGuards(value, now = Date.now()) {
 }
 
 // Guards selected by --guards=<name,...>, in canonical order. Anything but a
-// well-formed list of known names means all five.
+// well-formed list of known names means all six.
 function parseGuardsArg(argv) {
   const arg = argv.find((a) => a.startsWith('--guards='));
   if (!arg) return GUARD_ORDER;

package/plugins/trailhead/hooks/trailhead-bash-guards.test.js

@@ -17,8 +17,8 @@ const ok = (name, cond) => { assert.ok(cond, name); passed++; };
 const eq = (name, actual, expected) => { assert.deepStrictEqual(actual, expected, name); passed++; };
 
 // Run the merged hook end-to-end: tool_input JSON on stdin, capture {code, out, err}.
-function runHook(command, { env = {}, args = [], hook = HOOK } = {}) {
-  const input = JSON.stringify({ tool_input: { command } });
+function runHook(command, { env = {}, args = [], hook = HOOK, cwd } = {}) {
+  const input = JSON.stringify({ tool_input: { command }, ...(cwd ? { cwd } : {}) });
   const r = spawnSync('node', [hook, ...args], { input, env: { ...process.env, ...env } });
   return { code: r.status, out: r.stdout.toString(), err: r.stderr.toString() };
 }
@@ -30,9 +30,10 @@ const BAD_SECRET = 'gh issue comment 5 --body "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012
 const BAD_INSTALL = 'npm install left-pad';
 const BAD_SEARCH = 'cd x && grep y z';
 const BAD_BODY = 'gh issue edit 5 --body ""';
+const BAD_LABELS = 'gh issue create --title x --body y --label trailhead:bug';
 
 // --- unit: constants ---
-eq('guard order is fixed', GUARD_ORDER, ['commit', 'secret', 'install', 'search', 'body']);
+eq('guard order is fixed', GUARD_ORDER, ['commit', 'secret', 'install', 'search', 'body', 'labels']);
 ok('freshness window is 5s', MOD_GUARDS_FRESH_MS === 5000);
 
 // --- unit: parseModGuards ---
@@ -48,10 +49,10 @@ for (const bad of ['commit', '@123', 'commit@abc', ',@1', '', undefined, 'commit
 eq('unknown names are ignored', [...parseModGuards(`commit,bogus@${NOW}`, NOW)], ['commit']);
 
 // --- unit: parseGuardsArg ---
-eq('no --guards -> all five', parseGuardsArg([]), GUARD_ORDER);
+eq('no --guards -> all six', parseGuardsArg([]), GUARD_ORDER);
 eq('valid subset keeps canonical order', parseGuardsArg(['--guards=body,commit']), ['commit', 'body']);
-eq('empty --guards -> all five', parseGuardsArg(['--guards=']), GUARD_ORDER);
-eq('malformed --guards -> all five', parseGuardsArg(['--guards=commit,,body']), GUARD_ORDER);
+eq('empty --guards -> all six', parseGuardsArg(['--guards=']), GUARD_ORDER);
+eq('malformed --guards -> all six', parseGuardsArg(['--guards=commit,,body']), GUARD_ORDER);
 eq('any unknown name invalidates the whole list', parseGuardsArg(['--guards=commit,secert']), GUARD_ORDER);
 
 // --- unit: runGuards with fake evaluators ---
@@ -65,7 +66,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
     evaluators: {
       commit: spy('commit', () => { throw new Error('boom'); }),
       secret: spy('secret', allow), install: spy('install', blocker('I')),
-      search: spy('search', blocker('S')), body: spy('body', allow),
+      search: spy('search', blocker('S')), body: spy('body', allow), labels: spy('labels', allow),
     },
   });
   eq('a throwing guard counts as allow and the next one still blocks', r.code, 2);
@@ -75,7 +76,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
 {
   const r = runGuards('x', {
     now: NOW, env: { TRAILHEAD_MOD_GUARDS: `commit@${NOW}` },
-    evaluators: { commit: blocker('C'), secret: allow, install: allow, search: allow, body: allow },
+    evaluators: { commit: blocker('C'), secret: allow, install: allow, search: allow, body: allow, labels: allow },
   });
   eq('a fresh stamp skips the listed guard', r.code, 0);
 }
@@ -83,7 +84,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
   const adv = (t) => () => ({ kind: 'advise', stderr: `${t}\n`, payload: { hookSpecificOutput: { additionalContext: t } } });
   const r = runGuards('x', {
     now: NOW, env: {},
-    evaluators: { commit: adv('a'), secret: adv('b'), install: allow, search: allow, body: allow },
+    evaluators: { commit: adv('a'), secret: adv('b'), install: allow, search: allow, body: allow, labels: allow },
   });
   eq('advisories exit 0', r.code, 0);
   eq('advisory stderr lines are all written', r.stderr, 'a\nb\n');
@@ -96,9 +97,10 @@ const { evaluate: evSecret } = require('./trailhead-secret-guard.js');
 const { evaluate: evInstall } = require('./trailhead-install-guard.js');
 const { evaluate: evSearch } = require('./trailhead-search-guard.js');
 const { evaluate: evBody } = require('./trailhead-body-guard.js');
+const { evaluate: evLabels } = require('./trailhead-labels-guard.js');
 for (const [name, cmd, ev] of [
   ['commit', BAD_COMMIT, evCommit], ['secret', BAD_SECRET, evSecret], ['install', BAD_INSTALL, evInstall],
-  ['search', BAD_SEARCH, evSearch], ['body', BAD_BODY, evBody],
+  ['search', BAD_SEARCH, evSearch], ['body', BAD_BODY, evBody], ['labels', BAD_LABELS, evLabels],
 ]) {
   const r = runHook(cmd);
   const want = ev(cmd);
@@ -169,19 +171,19 @@ for (const [name, cmd, ev] of [
     const hook = path.join(tmp, 'trailhead-bash-guards.js');
     fs.rmSync(path.join(tmp, 'trailhead-search-guard.js'));
 
-    const codex = runHook(BAD_SEARCH, { hook, args: ['--guards=commit,secret,install,body'] });
+    const codex = runHook(BAD_SEARCH, { hook, args: ['--guards=commit,secret,install,body,labels'] });
     eq('--guards without search never loads search-guard', codex.code, 0);
     eq('--guards without search: no warning', codex.err, '');
-    const still = runHook(BAD_INSTALL, { hook, args: ['--guards=commit,secret,install,body'] });
+    const still = runHook(BAD_INSTALL, { hook, args: ['--guards=commit,secret,install,body,labels'] });
     eq('--guards subset still blocks with its guards', still.code, 2);
     const only = runHook(BAD_INSTALL, { hook, args: ['--guards=commit'] });
     eq('unselected guards do not run', only.code, 0);
 
     for (const bad of ['--guards=', '--guards=commit,secert', '--guards=commit,,body']) {
       const r = runHook(BAD_INSTALL, { hook, args: [bad] });
-      eq(`${bad}: falls back to all five (install blocks)`, r.code, 2);
+      eq(`${bad}: falls back to all six (install blocks)`, r.code, 2);
       const clean = runHook('git status', { hook, args: [bad] });
-      ok(`${bad}: all five are selected (the missing search module is reported)`, /search/.test(clean.err));
+      ok(`${bad}: all six are selected (the missing search module is reported)`, /search/.test(clean.err));
     }
 
     const missing = runHook(`${BAD_BODY} && ${BAD_SEARCH}`, { hook });
@@ -212,12 +214,16 @@ for (const [name, cmd, ev] of [
 }
 
 // --- every existing guard suite, re-run through the merged hook ---
-for (const name of ['commit', 'secret', 'install', 'search', 'body']) {
+// Run from a scratch dir outside any trailhead repo: those suites open unlabelled issues, which
+// the labels guard (rightly) blocks inside a trailhead repo.
+const SUITE_CWD = fs.mkdtempSync(path.join(os.tmpdir(), 'tb-suites-'));
+for (const name of ['commit', 'secret', 'install', 'search', 'body', 'labels']) {
   const file = path.join(__dirname, `trailhead-${name}-guard.test.js`);
-  const r = spawnSync('node', [file], { env: { ...process.env, TRAILHEAD_GUARD_HOOK: HOOK } });
+  const r = spawnSync('node', [file], { cwd: SUITE_CWD, env: { ...process.env, TRAILHEAD_GUARD_HOOK: HOOK } });
   if (r.status !== 0) process.stderr.write(r.stdout.toString() + r.stderr.toString());
   eq(`${name}-guard suite passes through the merged hook`, r.status, 0);
 }
+fs.rmSync(SUITE_CWD, { recursive: true, force: true });
 
 // --- registration: one Bash entry, one command (the merged hook) ---
 {

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

@@ -8,14 +8,28 @@
 // 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 (incl. evaluate) exported for tests
+// 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|$)/;
 
 // Per-ecosystem: the binaries that own it, and the install verbs that fetch a
@@ -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;
@@ -147,10 +279,10 @@ function blockVerdict(hit) {
 
 // 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) {
+function evaluate(cmd, opts) {
   try {
     if (isVerified(cmd)) return { kind: 'allow' }; // agent has vetted these
-    const hit = detectInstall(cmd);
+    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
@@ -160,12 +292,15 @@ function evaluate(cmd) {
 
 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
   }
-  const v = evaluate(cmd);
+  const v = evaluate(cmd, { cwd });
   if (v.kind === 'block') {
     process.stdout.write(JSON.stringify(v.payload));
     process.exit(2);