@haposoft/cafekit 0.18.2 → 0.18.4

package/src/claude/hooks/__tests__/spec-gate.test.js

@@ -4,7 +4,7 @@
 // a real subprocess: a Stop payload is piped to stdin; we assert exit code and
 // whether stdout carries {"decision":"block",...}. The hook resolves its own
 // state directory; running from source that is a temp directory rather than the
-// source tree, and it is shared, so each test seeds/clears it deliberately.
+// source tree, so each test seeds/clears it deliberately.
 
 const { test, beforeEach, after } = require('node:test');
 const assert = require('node:assert');
@@ -14,6 +14,11 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+// Hooks run from source keep state under os.tmpdir(); a private one per test process
+// keeps a parallel run of this file from reading or clearing this run's state.
+const PRIVATE_TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-spec-gate-tmp-'));
+for (const key of ['TMPDIR', 'TMP', 'TEMP']) process.env[key] = PRIVATE_TMP;
+
 const HOOK = path.join(__dirname, '..', 'spec-gate.cjs');
 const { hookStateDir } = require(path.join(__dirname, '..', 'lib', 'hook-state-dir.cjs'));
 const CACHE = path.join(hookStateDir(), 'spec-gate-last.json');
@@ -291,6 +296,7 @@ beforeEach(() => {
 
 after(() => {
   clearCache();
+  fs.rmSync(PRIVATE_TMP, { recursive: true, force: true });
 });
 
 test('1. newly-done task WITHOUT receipt → block, reason names task path', () => {
@@ -462,32 +468,6 @@ test('4. stop_hook_active: true → exit 0 silent even with violating task', ()
   }
 });
 
-test('4b. done task before explicit closeout without receipt blocks', () => {
-  const dir = makeFixture({ evidence: 'missing-evidence', phase: 'implementation' });
-  try {
-    const { code, stdout } = runHook({}, dir);
-    assert.strictEqual(code, 0);
-    const body = parseBlock(stdout);
-    assert.strictEqual(body?.decision, 'block');
-    assert.match(body.reason, new RegExp(TASK_REL));
-    assert.strictEqual(fs.existsSync(path.join(dir, 'specs', FEATURE, 'feature-receipt.md')), false);
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('4c. done task before explicit closeout with valid task receipt is silent', () => {
-  const dir = makeFixture({ evidence: 'valid', phase: 'implementation' });
-  try {
-    const { code, stdout } = runHook({}, dir);
-    assert.strictEqual(code, 0);
-    assert.strictEqual(stdout, '');
-    assert.strictEqual(fs.existsSync(path.join(dir, 'specs', FEATURE, 'feature-receipt.md')), false);
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
 test('5. first run (no cache) with done-without-receipt → block (cache is not truth)', () => {
   const dir = makeFixture({ evidence: 'missing-evidence' });
   try {
@@ -895,27 +875,6 @@ test('25. placeholder tokens Command: TODO / Base: TBD / artifact sha256 empty m
   fs.rmSync(dir2, { recursive: true, force: true });
 });
 
-test('26. explicit failure outcomes Tests failed / Result FAIL and multiple Results must block', () => {
-  const cases = [
-    { evidence: ['Verification: PASS','Command: pnpm test','Exit: 0','Base: a','Head: b','Tests failed: 1'].join('\n'), desc: 'Tests failed: 1' },
-    { evidence: ['Verification: PASS','Command: pnpm test','Exit: 0','Base: a','Head: b','Result: FAIL','Result: PASS'].join('\n'), desc: 'Result FAIL then PASS' },
-    { evidence: ['Verification: PASS','Command: pnpm test','Exit: 0','Base: a','Head: b','0 tests passed'].join('\n'), desc: '0 tests' },
-  ];
-  for (const { evidence, desc } of cases) {
-    const dir = tmpDir();
-    const featureDir = path.join(dir, 'specs', FEATURE);
-    fs.mkdirSync(featureDir, { recursive: true });
-    fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Demo plan\n');
-    fs.mkdirSync(path.join(featureDir, 'tasks'), { recursive: true });
-    fs.writeFileSync(path.join(dir, 'specs', FEATURE, TASK_REL), ['# Task','','Status: done','','## Dependencies', '', '- none', '', '## Verification Plan', '', '- Command: pnpm test', '', '## Receipt','','' + evidence,'```','pass','```'].join('\n'));
-    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
-    const body = parseBlock(runHook({}, dir).stdout);
-    assert.ok(body, `explicit failure ${desc} should block`);
-    assert.strictEqual(body.decision, 'block');
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
 test('27. task markdown symlink outside feature must be rejected (check a)', () => {
   const dir = tmpDir();
   const featureDir = path.join(dir, 'specs', FEATURE);
@@ -1997,3 +1956,82 @@ test('a packet holding both plan.md and spec.json is read as process-first and i
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+// Head is sha256 over one JSON line per path with the file bytes as base64. It is now streamed instead of built, and
+// must stay byte-identical: every receipt already written carries a Head computed the old way.
+function referenceHead(dir) {
+  const git = (...args) => spawnSync('git', ['-C', dir, ...args], { encoding: 'buffer' }).stdout;
+  const split = (buffer) => buffer.toString('utf8').split('\0').filter(Boolean);
+  const raw = split(git('status', '--porcelain=v1', '-z', '--untracked-files=all'));
+  const statuses = new Map();
+  for (let index = 0; index < raw.length; index += 1) {
+    const xy = raw[index].slice(0, 2);
+    const first = raw[index].slice(3);
+    if (xy.includes('R') || xy.includes('C')) {
+      const next = raw[++index];
+      statuses.set(first, { xy, role: 'rename-source', counterpart: next });
+      statuses.set(next, { xy, role: 'rename-target', counterpart: first });
+    } else statuses.set(first, { xy, role: xy === '??' || xy === '!!' ? 'untracked' : 'tracked' });
+  }
+  const paths = [...new Set([...split(git('ls-files', '-z', '--cached')), ...split(git('ls-tree', '-r', '-z', '--name-only', 'HEAD')), ...statuses.keys()])]
+    .filter((relative) => !relative.startsWith('specs/') && !PROVENANCE.RUNTIME_STATE_ROOTS.some((root) => relative === root || relative.startsWith(`${root}/`)))
+    .sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+  const hash = crypto.createHash('sha256').update('cafekit-provenance\0');
+  for (const relative of paths) {
+    const absolute = path.join(dir, relative);
+    const status = statuses.get(relative) || null;
+    let stat;
+    try { stat = fs.lstatSync(absolute); } catch {
+      hash.update(`${JSON.stringify({ path: relative, type: 'deleted', mode: '0000', status, content: null })}\n`);
+      continue;
+    }
+    const type = stat.isSymbolicLink() ? 'symlink' : stat.isFile() ? 'file' : 'directory';
+    const content = type === 'symlink' ? Buffer.from(fs.readlinkSync(absolute), 'utf8') : type === 'file' ? fs.readFileSync(absolute) : Buffer.alloc(0);
+    const mode = (stat.mode & 0o7777).toString(8).padStart(4, '0');
+    hash.update(`${JSON.stringify({ path: relative, type, mode, status, content: content.toString('base64') })}\n`);
+  }
+  return hash.digest('hex');
+}
+
+function provenanceFixture() {
+  const dir = fs.realpathSync(tmpDir());
+  fs.mkdirSync(path.join(dir, 'specs', FEATURE), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'specs', FEATURE, 'plan.md'), '# Demo plan\n');
+  return dir;
+}
+
+test('Head is unchanged by streaming: files around the 3 MB chunk edge, symlink, rename, deletion, quoted names', () => {
+  const dir = provenanceFixture();
+  try {
+    const chunk = 3 * 1024 * 1024;
+    for (const size of [0, 1, 2, 4, chunk - 1, chunk, chunk + 1, 2 * chunk + 2]) {
+      fs.writeFileSync(path.join(dir, `bin-${size}.dat`), crypto.randomBytes(size));
+    }
+    fs.writeFileSync(path.join(dir, 'tiếng "việt" \\ name.txt'), 'x');
+    fs.writeFileSync(path.join(dir, 'run.sh'), '#!/bin/sh\n');
+    fs.chmodSync(path.join(dir, 'run.sh'), 0o755);
+    fs.writeFileSync(path.join(dir, 'gone.txt'), 'g');
+    fs.writeFileSync(path.join(dir, 'old-name.txt'), 'r');
+    for (const args of [['add', '-A'], ['commit', '-qm', 'files']]) assert.strictEqual(spawnSync('git', ['-C', dir, ...args]).status, 0);
+    fs.unlinkSync(path.join(dir, 'gone.txt'));
+    assert.strictEqual(spawnSync('git', ['-C', dir, 'mv', 'old-name.txt', 'new-name.txt']).status, 0);
+    fs.symlinkSync('run.sh', path.join(dir, 'link'));
+    fs.writeFileSync(path.join(dir, 'untracked.bin'), crypto.randomBytes(1000));
+    assert.strictEqual(workflowRuntimeContext(dir).head, referenceHead(dir));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('a checkout whose files exceed the longest string V8 can hold still yields a Head', () => {
+  const dir = provenanceFixture();
+  try {
+    // Sparse: 600 MB of zeros on disk costs nothing, but its base64 alone (800M characters) is past V8's string limit.
+    const descriptor = fs.openSync(path.join(dir, 'large-asset.bin'), 'w');
+    fs.ftruncateSync(descriptor, 600 * 1024 * 1024);
+    fs.closeSync(descriptor);
+    assert.match(workflowRuntimeContext(dir).head, /^[0-9a-f]{64}$/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/claude/hooks/__tests__/state.test.js

@@ -485,6 +485,27 @@ test('SubagentStop saves the assistant summary and omits secret-related content'
   });
 });
 
+test('a symlinked session-state path is refused and nothing is written outside the project', () => {
+  inSessionStateFixture(({ invoke, stateRoot }) => {
+    // A repository can commit either the shared state folder or one session folder as a link.
+    for (const link of [stateRoot, savedSession(stateRoot)]) {
+      const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-state-outside-'));
+      try {
+        fs.rmSync(stateRoot, { recursive: true, force: true });
+        fs.mkdirSync(path.dirname(link), { recursive: true });
+        fs.symlinkSync(outside, link);
+        invoke({ hook_event_name: 'Stop', session_id: 'robust-session', last_assistant_message: 'Linked snapshot' });
+        assert.deepStrictEqual(fs.readdirSync(outside), [], `${path.basename(link)} link must not receive state`);
+      } finally {
+        fs.rmSync(stateRoot, { recursive: true, force: true });
+        fs.rmSync(outside, { recursive: true, force: true });
+      }
+    }
+    invoke({ hook_event_name: 'Stop', session_id: 'robust-session', last_assistant_message: 'Plain snapshot' });
+    assert.ok(fs.existsSync(path.join(savedSession(stateRoot), 'latest.md')), 'a plain state folder still saves');
+  });
+});
+
 test('a fresh state write lock skips the snapshot without changing existing bytes', () => {
   inSessionStateFixture(({ invoke, stateRoot }) => {
     const dir = savedSession(stateRoot);

package/src/claude/hooks/agent.cjs

@@ -45,12 +45,15 @@ try {
   const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
   const payload    = normalizeHookPayload(JSON.parse(stdin));
   const root = projectRoot(payload);
-  const runtime = readRuntime(root);
+  // An npx install always has runtime.json; under the plugin it is optional.
+  // Loaded only under the plugin, so npx installs need no extra hook file.
+  const plugin = process.env.CLAUDE_PLUGIN_ROOT ? require('./lib/plugin-options.cjs') : null;
+  const runtime = readRuntime(root) || (plugin ? {} : null);
   if (runtime === null) process.exit(0);
 
   // Language config from runtime.json
   const thinkLang    = runtime.locale?.thinkingLanguage || '';
-  const respondLang  = runtime.locale?.responseLanguage || '';
+  const respondLang  = runtime.locale?.responseLanguage || (plugin ? plugin.pluginOption('response_language') : '');
   // Default thinking to 'en' when only response language is set
   const effectThink  = thinkLang || (respondLang ? 'en' : '');
 

package/src/claude/hooks/inspect-block.cjs

@@ -60,7 +60,9 @@ function denyWithReason(reason) {
   const root      = projectRoot(data);
   const runtime   = readRuntime(root);
 
-  if (runtime.scout?.enabled === false || runtime.inspect?.enabled === false) process.exit(0);
+  // A plugin is trusted once for every repository, so a repository cannot switch it off.
+  const disabled = runtime.scout?.enabled === false || runtime.inspect?.enabled === false;
+  if (disabled && !require('./lib/plugin-options.cjs').isPlugin()) process.exit(0);
 
   const result = inspectInput(toolName, toolInput, {
     cwd, projectRoot: root

package/src/claude/hooks/lib/hook-state-dir.cjs

@@ -29,11 +29,29 @@ function isSourceTree(dir) {
   return String(dir || '').includes(SOURCE_MARKER);
 }
 
+/**
+ * State root for hooks running from the Claude Code plugin, or null outside it.
+ * The plugin root is replaced on every update and the project must stay clean,
+ * so plugin state lives in CLAUDE_PLUGIN_DATA, or the OS temp directory when the
+ * host gives no usable data directory.
+ */
+function pluginStateRoot() {
+  if (!process.env.CLAUDE_PLUGIN_ROOT) return null;
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (data && path.isAbsolute(data)) return data;
+  // Per-user name so accounts sharing /tmp do not collide; this is a fallback
+  // only, since the host sets CLAUDE_PLUGIN_DATA for plugin hooks.
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 'user';
+  return path.join(os.tmpdir(), `cafekit-plugin-${uid}`);
+}
+
 /** Absolute directory for hook-generated state; create it before writing. */
 function hookStateDir() {
+  const pluginRoot = pluginStateRoot();
+  if (pluginRoot) return path.join(pluginRoot, '.logs');
   return isSourceTree(HOOKS_DIR)
     ? path.join(os.tmpdir(), 'cafekit-hook-logs', require('./runtime-dir.cjs').runtimeDirName().slice(1))
     : path.join(HOOKS_DIR, '.logs');
 }
 
-module.exports = { hookStateDir, isSourceTree };
+module.exports = { hookStateDir, isSourceTree, pluginStateRoot };

package/src/claude/hooks/lib/plugin-options.cjs

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * Claude Code plugin options for the hooks.
+ *
+ * The plugin's userConfig values reach hooks as CLAUDE_PLUGIN_OPTION_<KEY> and are
+ * injected into model context verbatim, so each one is reduced to a single short
+ * line: no control, bidi, or zero-width characters or line breaks that could open a
+ * new section or disguise the text, and
+ * at most 64 characters so the core stays inside the host's context budget.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_OPTION_LENGTH = 64;
+
+/**
+ * True when the hook runs from the Claude Code plugin rather than an npx install.
+ * The variable alone is not enough: an npx hook can inherit it from a parent process,
+ * so this file must really live under that plugin root.
+ */
+function isPlugin() {
+  const declared = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!declared) return false;
+  try {
+    return fs.realpathSync(declared) === fs.realpathSync(path.resolve(__dirname, '..', '..'));
+  } catch {
+    return false;
+  }
+}
+
+/** One short plain line: no control, bidi, or zero-width characters; at most 64 characters. */
+function sanitizeLine(raw) {
+  if (typeof raw !== 'string') return '';
+  return [...raw.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]+/g, ' ').replace(/\s+/g, ' ').trim()]
+    .slice(0, MAX_OPTION_LENGTH)
+    .join('')
+    .trim();
+}
+
+/** Sanitized option value, or '' when unset. `key` is the userConfig key, e.g. `response_language`. */
+function pluginOption(key) {
+  return sanitizeLine(process.env[`CLAUDE_PLUGIN_OPTION_${key.toUpperCase()}`]);
+}
+
+module.exports = { MAX_OPTION_LENGTH, isPlugin, pluginOption, sanitizeLine };

package/src/claude/hooks/lib/privacy-command-analysis.cjs

@@ -35,6 +35,8 @@ const SED_OPTION_VALUE = new Set(['-e', '--expression', '-f', '--file']);
 const AWK_OPTION_VALUE = new Set(['-f', '--file', '-v', '--assign', '-F', '--field-separator']);
 const XARGS_OPTION_VALUE = new Set(['-a', '--arg-file', '-d', '--delimiter', '-E', '--eof', '-I', '--replace', '-L', '--max-lines', '-n', '--max-args', '-P', '--max-procs', '-s', '--max-chars']);
 
+const IDENTIFIER = /[A-Za-z_][A-Za-z0-9_]*/y;
+
 function expansionAt(source, index) {
   const next = source[index + 1];
   return Boolean(next && (next === '{' || next === '('
@@ -107,18 +109,28 @@ function scanShell(command) {
   const source = String(command).replace(/\\\r?\n/g, '');
   const segments = [];
   const nested = [];
-  const recordNested = command => nested.push({ command, segment: segments.length });
+  // Each nested command is also kept on the word it sits in, so an operand built from $(...) carries its literals.
+  const recordNested = command => { nested.push({ command, segment: segments.length }); (word.nested ||= []).push(command); };
   let words = [];
   let word = { text: '', activeExpansion: false, started: false };
   let quote = null;
   let escaped = false;
   let malformed = false;
   const append = (value) => { word.text += value; word.started = true; };
+  // `$NAME` is written as `${NAME}` so a quote that ends the name (`.en"$Y"v`) still ends it after the quotes go.
+  const appendName = (index) => {
+    IDENTIFIER.lastIndex = index + 1;
+    const match = IDENTIFIER.exec(source);
+    if (!match) return index;
+    append(`{${match[0]}}`);
+    return index + match[0].length;
+  };
   const flushWord = () => {
     if (word.started || word.text) words.push(word);
     word = { text: '', activeExpansion: false, started: false };
   };
-  const flushSegment = () => { flushWord(); if (words.length) segments.push(words); words = []; };
+  // `link` is how the segment ends: 'pipe' for a single |, anything else for ;, &&, ||, &, newline and parentheses.
+  const flushSegment = (link = 'end') => { flushWord(); if (words.length) { words.link = link; segments.push(words); } words = []; };
 
   for (let index = 0; index < source.length; index += 1) {
     const ch = source[index];
@@ -136,7 +148,7 @@ function scanShell(command) {
           recordNested(source.slice(index + 2, end));
           append('()');
           index = end;
-        }
+        } else index = appendName(index);
         continue;
       }
       if (ch === '\x60') {
@@ -168,7 +180,7 @@ function scanShell(command) {
         recordNested(source.slice(index + 2, end));
         append('()');
         index = end;
-      }
+      } else index = appendName(index);
       continue;
     }
     if (ch === '\x60') {
@@ -190,7 +202,11 @@ function scanShell(command) {
       continue;
     }
     if ((ch === '~' && !word.text) || '*?{['.includes(ch)) { word.activeExpansion = true; append(ch); continue; }
-    if (';|&\n()'.includes(ch)) { flushSegment(); continue; }
+    if (';|&\n()'.includes(ch)) {
+      const pipe = ch === '|' && source[index + 1] !== '|' && source[index - 1] !== '|' && source[index + 1] !== '&';
+      flushSegment(pipe ? 'pipe' : 'other');
+      continue;
+    }
     if (ch === '<') {
       const descriptor = /^[0-9]+$/.test(word.text);
       flushWord();
@@ -233,9 +249,17 @@ function skipOption(words, index, valueOptions = WRAPPER_OPTION_VALUE) {
   return valueOptions.has(value) ? index + 2 : index + 1;
 }
 
+// Words that open or continue a compound command; the command they lead into is still the one that runs.
+const KEYWORDS = new Set(['if', 'then', 'elif', 'else', 'while', 'until', 'do', '{', '!', 'time', 'coproc', 'function']);
+
 function unwrap(words) {
   let index = 0;
-  while (index < words.length && assignment(words[index])) index += 1;
+  while (index < words.length && (assignment(words[index]) || KEYWORDS.has(words[index].text))) {
+    index += 1;
+    if (words[index - 1].text === 'time') while (words[index]?.text.startsWith('-')) index += 1;
+    // `function f { cat .env; }`: the word after `function` is the name being defined, not a command.
+    if (words[index - 1].text === 'function') index += 1;
+  }
   for (let depth = 0; depth < 12 && index < words.length; depth += 1) {
     const name = commandName(words[index]);
     if (!WRAPPERS.has(name)) return { index, name };
@@ -260,8 +284,19 @@ function unwrap(words) {
 
 function addOperand(result, word) {
   if (!word) return;
-  if (word.activeExpansion) result.dynamic = true;
-  else if (word.text && word.text !== '-') result.paths.add(word.text);
+  if (word.activeExpansion) {
+    result.dynamic = true;
+    // Kept for the path resolver: the raw text, the directory a tracked `cd` left, and the literal words of every
+    // command substitution inside it. The assignments it can see are attached when its segment finishes.
+    result.expansions.push({ text: word.text, directory: result.directory === undefined ? '.' : result.directory,
+      literals: (word.nested || []).flatMap(literalWords) });
+  } else if (word.text && word.text !== '-') result.paths.add(word.text);
+}
+
+// The literal words of a command line: no expansion, no option.
+function literalWords(command) {
+  return scanShell(command).segments.flat().filter((word) => !word.activeExpansion && word.text && !word.text.startsWith('-'))
+    .map((word) => word.text);
 }
 
 function genericOperands(words, start, result, {
@@ -292,6 +327,9 @@ function merge(target, source) {
   target.searches.push(...source.searches);
   source.writes.forEach(value => target.writes.add(value));
   source.unknownWrites.forEach(value => target.unknownWrites.add(value));
+  target.expansions.push(...source.expansions);
+  target.pipeNames.push(...source.pipeNames);
+  target.decodedRead ||= source.decodedRead;
   target.dynamic ||= source.dynamic;
   target.malformed ||= source.malformed;
 }
@@ -432,6 +470,7 @@ function commandWrites(words, start, name, result, directory) {
 }
 
 function analyzeWords(words, result, depth, directory = '.') {
+  result.directory = directory;
   for (const index of words.redirects || []) writeTarget(words[index], result, directory);
   for (let index = 0; index + 1 < words.length; index += 1) {
     if (words[index].text === '<') addOperand(result, words[index + 1]);
@@ -489,10 +528,16 @@ function analyzeWords(words, result, depth, directory = '.') {
     return;
   }
   if (name === 'find') {
+    // A name test that selects a secret, handed to a reader through -exec, reads it.
+    const names = [];
+    for (let index = start; index + 1 < words.length; index += 1) {
+      if (['-name', '-iname', '-path', '-ipath', '-wholename', '-iwholename'].includes(words[index].text)) names.push(words[index + 1].text);
+    }
     for (let index = start; index < words.length; index += 1) {
       if (words[index].text !== '-exec' && words[index].text !== '-execdir') continue;
       const nested = [];
       for (index += 1; index < words.length && ![';', '+'].includes(words[index].text); index += 1) nested.push(words[index]);
+      if (READS.has(unwrap(nested).name)) result.pipeNames.push(...names);
       analyzeWords(nested, result, depth + 1, directory);
     }
     return;
@@ -528,15 +573,29 @@ function analyzeWords(words, result, depth, directory = '.') {
 }
 
 function analyzeCommand(command, depth = 0, directory = '.') {
-  const result = { paths: new Set(), dynamic: false, malformed: false, searches: [], writes: new Set(), unknownWrites: new Set() };
+  const result = { paths: new Set(), dynamic: false, malformed: false, searches: [], writes: new Set(), unknownWrites: new Set(),
+    expansions: [], pipeNames: [], decodedRead: false };
   if (depth > MAX_DEPTH) { result.dynamic = true; return result; }
   const parsed = scanShell(command);
   result.malformed = parsed.malformed;
   let currentDirectory = directory;
   const directories = [];
-  for (const words of parsed.segments) {
+  const assignments = [];
+  const visibleAt = [];
+  // Every operand found while analysing a segment -- its own, or one from a nested eval, `bash -c` or $(...) -- sees the
+  // assignments of the earlier segments. `f=.env cat $f` does not: the shell expands $f before that prefix applies.
+  const scope = (from, segmentIndex) => {
+    for (const expansion of result.expansions.slice(from)) {
+      expansion.scopes = [{ list: assignments, count: visibleAt[segmentIndex] }, ...(expansion.scopes || [])];
+    }
+  };
+  for (const [segmentIndex, words] of parsed.segments.entries()) {
     directories.push(currentDirectory);
+    visibleAt.push(assignments.length);
+    recordAssignments(words, assignments);
+    const from = result.expansions.length;
     analyzeWords(words, result, depth, currentDirectory);
+    scope(from, segmentIndex);
     const info = unwrap(words);
     if (['cd', 'pushd'].includes(info.name)) {
       const target = words.slice(info.index + 1).find(word => word.text && !word.text.startsWith('-'));
@@ -545,9 +604,12 @@ function analyzeCommand(command, depth = 0, directory = '.') {
       else if (currentDirectory !== null) currentDirectory = `${currentDirectory}/${target.text}`;
     }
   }
+  analyzePipelines(parsed.segments, result);
   for (const nested of parsed.nested) {
     const nestedDirectory = directories[nested.segment] === undefined ? directory : directories[nested.segment];
+    const from = result.expansions.length;
     merge(result, analyzeCommand(nested.command, depth + 1, nestedDirectory));
+    if (visibleAt[nested.segment] !== undefined) scope(from, nested.segment);
   }
   if (result.malformed && parsed.segments.some((words) => {
     const commandInfo = unwrap(words);
@@ -558,10 +620,67 @@ function analyzeCommand(command, depth = 0, directory = '.') {
   return result;
 }
 
+const ASSIGNING = new Set(['export', 'declare', 'typeset', 'local', 'readonly']);
+
+// A segment that only assigns (`f=.env`), or an export/declare/local/typeset/readonly. The value keeps its expansions
+// (`f="$PWD/.env"`, `G=$F`); the resolver substitutes them in order.
+function recordAssignments(words, out) {
+  const bare = words.every(assignment);
+  const builtin = ASSIGNING.has(commandName(words[0]));
+  if (!bare && !builtin) return;
+  for (const word of words.slice(bare ? 0 : 1)) {
+    if (!assignment(word)) continue;
+    const at = word.text.indexOf('=');
+    out.push({ name: word.text.slice(0, at), value: word.text.slice(at + 1) });
+  }
+}
+
+const DECODERS = (words) => {
+  const name = commandName(words[unwrap(words).index]);
+  const flags = words.map((word) => word.text);
+  if (name === 'base64' || name === 'basenc') return flags.some((flag) => ['-d', '-D', '--decode'].includes(flag));
+  if (name === 'openssl') return flags.some((flag) => ['base64', 'enc'].includes(flag)) && flags.includes('-d');
+  if (name === 'xxd') return flags.includes('-r') || flags.includes('-revert');
+  if (name === 'gpg') return flags.some((flag) => ['-d', '--decrypt'].includes(flag));
+  return ['uudecode', 'b64decode'].includes(name);
+};
+const READS = new Set([...SIMPLE_READERS, ...GREP_READERS, ...AWK_READERS, 'sed', 'source', '.']);
+
+// A pipeline whose decoder feeds a shell, eval or xargs runs what it decoded; xargs handing a reader the literal words of
+// an earlier stage (`printf .env | xargs cat`, `find . -name .env | xargs cat`) reads those words. One pass: each stage
+// is looked at once, and each earlier word is handed over at most once.
+function analyzePipelines(segments, result) {
+  let decoded = false;
+  let first = true;
+  let words = [];
+  let handed = 0;
+  for (const stage of segments) {
+    const info = unwrap(stage);
+    if (info.index >= 0 && !first) {
+      if (decoded && (SHELLS.has(info.name) || ['eval', 'xargs', 'source', '.'].includes(info.name))) result.decodedRead = true;
+      if (info.name === 'xargs') {
+        let index = info.index + 1;
+        while (index < stage.length && stage[index].text.startsWith('-')) index = skipOption(stage, index, XARGS_OPTION_VALUE);
+        const reader = unwrap(stage.slice(index)).name;
+        if (READS.has(reader) || SHELLS.has(reader)) {
+          result.pipeNames.push(...words.slice(handed));
+          handed = words.length;
+        }
+      }
+    }
+    if (DECODERS(stage)) decoded = true;
+    for (const word of stage.slice(info.index + 1)) if (word.text && !word.text.startsWith('-')) words.push(word.text);
+    first = stage.link !== 'pipe';
+    if (first) { decoded = false; words = []; handed = 0; }
+  }
+}
+
 function commandAccess(command) {
   const result = analyzeCommand(command);
   return { paths: [...result.paths], dynamic: result.dynamic, malformed: result.malformed, searches: result.searches,
-    writes: [...result.writes], unknownWrites: [...result.unknownWrites] };
+    writes: [...result.writes], unknownWrites: [...result.unknownWrites],
+    expansions: result.expansions.map(({ text, directory, literals, scopes }) => ({ text, directory, literals, scopes: scopes || [] })),
+    pipeNames: [...new Set(result.pipeNames)], decodedRead: result.decodedRead };
 }
 
 module.exports = { DYNAMIC_READ_PATH, commandAccess };