@marcomigozzi/trailhead 0.13.0 → 0.15.0

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

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Tests for trailhead-bash-guards.js. Run: node trailhead-bash-guards.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const HOOK = path.join(__dirname, 'trailhead-bash-guards.js');
+const {
+  parseModGuards, parseGuardsArg, runGuards, MOD_GUARDS_FRESH_MS, GUARD_ORDER,
+} = require('./trailhead-bash-guards.js');
+
+let passed = 0;
+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 } });
+  const r = spawnSync('node', [hook, ...args], { input, env: { ...process.env, ...env } });
+  return { code: r.status, out: r.stdout.toString(), err: r.stderr.toString() };
+}
+const codeOf = (r) => (r.out ? JSON.parse(r.out).code : undefined);
+
+// One command per guard that it (and only it) blocks.
+const BAD_COMMIT = 'git commit -m "not conventional"';
+const BAD_SECRET = 'gh issue comment 5 --body "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789xx"';
+const BAD_INSTALL = 'npm install left-pad';
+const BAD_SEARCH = 'cd x && grep y z';
+const BAD_BODY = 'gh issue edit 5 --body ""';
+
+// --- unit: constants ---
+eq('guard order is fixed', GUARD_ORDER, ['commit', 'secret', 'install', 'search', 'body']);
+ok('freshness window is 5s', MOD_GUARDS_FRESH_MS === 5000);
+
+// --- unit: parseModGuards ---
+const NOW = 1_700_000_000_000;
+eq('fresh stamp lists the guards', [...parseModGuards(`commit,search@${NOW - 100}`, NOW)].sort(), ['commit', 'search']);
+eq('age 0 is fresh', [...parseModGuards(`commit@${NOW}`, NOW)], ['commit']);
+eq('age exactly the window is fresh', [...parseModGuards(`commit@${NOW - MOD_GUARDS_FRESH_MS}`, NOW)], ['commit']);
+eq('age window+1 is stale', parseModGuards(`commit@${NOW - MOD_GUARDS_FRESH_MS - 1}`, NOW).size, 0);
+eq('future-dated stamp is ignored', parseModGuards(`commit@${NOW + 1}`, NOW).size, 0);
+for (const bad of ['commit', '@123', 'commit@abc', ',@1', '', undefined, 'commit,@1', 'commit@1@2', 'commit@-5']) {
+  eq(`malformed ${JSON.stringify(bad)} skips nothing`, parseModGuards(bad, 1).size, 0);
+}
+eq('unknown names are ignored', [...parseModGuards(`commit,bogus@${NOW}`, NOW)], ['commit']);
+
+// --- unit: parseGuardsArg ---
+eq('no --guards -> all five', 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('any unknown name invalidates the whole list', parseGuardsArg(['--guards=commit,secert']), GUARD_ORDER);
+
+// --- unit: runGuards with fake evaluators ---
+const allow = () => ({ kind: 'allow' });
+const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block', code, reason: 'r' } });
+{
+  const calls = [];
+  const spy = (n, f) => (c, o) => { calls.push(n); return f(c, o); };
+  const r = runGuards('x', {
+    now: NOW, env: {},
+    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),
+    },
+  });
+  eq('a throwing guard counts as allow and the next one still blocks', r.code, 2);
+  eq('the first block wins', JSON.parse(r.stdout).code, 'I');
+  eq('later guards are not run after a block', calls, ['commit', 'secret', 'install']);
+}
+{
+  const r = runGuards('x', {
+    now: NOW, env: { TRAILHEAD_MOD_GUARDS: `commit@${NOW}` },
+    evaluators: { commit: blocker('C'), secret: allow, install: allow, search: allow, body: allow },
+  });
+  eq('a fresh stamp skips the listed guard', r.code, 0);
+}
+{
+  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 },
+  });
+  eq('advisories exit 0', r.code, 0);
+  eq('advisory stderr lines are all written', r.stderr, 'a\nb\n');
+  eq('advisories are joined in one context', JSON.parse(r.stdout).hookSpecificOutput.additionalContext, 'a\nb');
+}
+
+// --- end to end: each guard's block, exact payload, exit 2 ---
+const { evaluate: evCommit } = require('./trailhead-commit-guard.js');
+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');
+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],
+]) {
+  const r = runHook(cmd);
+  const want = ev(cmd);
+  ok(`${name}: evaluator blocks the probe`, want.kind === 'block');
+  eq(`${name}: exit 2`, r.code, 2);
+  eq(`${name}: exact payload on stdout`, r.out, JSON.stringify(want.payload));
+}
+
+// --- end to end: clean, unparseable, stdin shapes ---
+{
+  const r = runHook('git status');
+  eq('clean command: exit 0', r.code, 0);
+  eq('clean command: empty stdout', r.out, '');
+  eq('clean command: empty stderr', r.err, '');
+  const bad = spawnSync('node', [HOOK], { input: 'not json {{' });
+  eq('unparseable input: exit 0', bad.status, 0);
+  const nul = spawnSync('node', [HOOK], { input: 'null' });
+  eq('null input: exit 0', nul.status, 0);
+}
+
+// --- end to end: first block wins ---
+{
+  const r = runHook(`${BAD_COMMIT} && ${BAD_SEARCH}`);
+  ok('the probe trips both commit and search', evSearch(`${BAD_COMMIT} && ${BAD_SEARCH}`).kind === 'block');
+  eq('first block wins: exit 2', r.code, 2);
+  eq('first block wins: commit payload', codeOf(r) !== 'SEARCH_HYGIENE_VIOLATION', true);
+  eq('first block wins: single payload', r.out, JSON.stringify(evCommit(`${BAD_COMMIT} && ${BAD_SEARCH}`).payload));
+}
+
+// --- end to end: TRAILHEAD_MOD_GUARDS ---
+{
+  const fresh = runHook(BAD_COMMIT, { env: { TRAILHEAD_MOD_GUARDS: `commit@${Date.now()}` } });
+  eq('fresh stamp lets the skipped guard through', fresh.code, 0);
+  const stale = runHook(BAD_COMMIT, { env: { TRAILHEAD_MOD_GUARDS: `commit@${Date.now() - 60000}` } });
+  eq('stale stamp blocks', stale.code, 2);
+  const junk = runHook(BAD_COMMIT, { env: { TRAILHEAD_MOD_GUARDS: 'commit' } });
+  eq('malformed stamp blocks', junk.code, 2);
+  const multi = `${BAD_INSTALL} && ${BAD_SEARCH}`;
+  const part = runHook(multi, { env: { TRAILHEAD_MOD_GUARDS: `commit,search@${Date.now()}` } });
+  eq('a fresh list skips exactly the listed guards: install still blocks', codeOf(part), 'UNVETTED_PACKAGE_INSTALL');
+  const all = runHook(multi, { env: { TRAILHEAD_MOD_GUARDS: `install,search@${Date.now()}` } });
+  eq('both listed guards skipped: passes', all.code, 0);
+}
+
+// --- end to end: failure posture ---
+{
+  const env = { TRAILHEAD_SECRETGUARD_THROW: '1' };
+  const alone = runHook('gh issue comment 5 --body "hello"', { env });
+  eq('secret advisory alone: exit 0', alone.code, 0);
+  ok('secret advisory alone: stderr names the failed scan', /could not scan this issue write/.test(alone.err));
+  ok('secret advisory alone: additionalContext on stdout',
+    /could NOT complete its scan/.test(JSON.parse(alone.out).hookSpecificOutput.additionalContext));
+  const both = runHook('gh issue edit 5 --body ""', { env });
+  eq('a faulted guard does not stop the next from blocking', both.code, 2);
+  eq('later block payload on stdout', codeOf(both), 'EMPTY_ISSUE_BODY_WRITE');
+  ok('earlier advisory stderr survives the later block', /could not scan this issue write/.test(both.err));
+  ok('advisory stdout is dropped on block', !/hookSpecificOutput/.test(both.out));
+}
+
+// --- end to end: --guards selection and module loading, on a throwaway copy ---
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'tb-guards-'));
+  try {
+    fs.cpSync(__dirname, tmp, {
+      recursive: true,
+      filter: (src) => path.basename(src) !== 'mod' && !src.endsWith('.test.js'),
+    });
+    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'] });
+    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'] });
+    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);
+      const clean = runHook('git status', { hook, args: [bad] });
+      ok(`${bad}: all five are selected (the missing search module is reported)`, /search/.test(clean.err));
+    }
+
+    const missing = runHook(`${BAD_BODY} && ${BAD_SEARCH}`, { hook });
+    eq('a module that fails to load is skipped, the others still block', codeOf(missing), 'EMPTY_ISSUE_BODY_WRITE');
+    ok('a load failure is a one-line stderr warning naming the guard',
+      missing.err.trim().split('\n').length === 1 && /search/.test(missing.err));
+    const clean = runHook('git status', { hook });
+    eq('a load failure alone still exits 0', clean.code, 0);
+    ok('a load failure reaches the session as an advisory naming the guard',
+      /could NOT load the search guard/.test(JSON.parse(clean.out).hookSpecificOutput.additionalContext));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// --- #227: unmodelled constructs through the merged runner ---
+{
+  const r1 = runHook('alias g=gh; g issue comment 1 --body x');
+  eq('secret-guard blocks a hidden gh write behind an alias', [r1.code, codeOf(r1)], [2, 'SECRET_GUARD_UNMODELLED_CONSTRUCT']);
+  const r2 = runHook('echo ${ gh issue comment 1 --body x; }');
+  eq('secret-guard blocks a write inside a function substitution', [r2.code, codeOf(r2)], [2, 'SECRET_GUARD_UNMODELLED_CONSTRUCT']);
+  const r3 = runHook("gh api -X PATCH repos/o/r/issues/1 -f 'body'=\"\"");
+  eq('body-guard blocks a quoted api body key with an empty body', [r3.code, codeOf(r3)], [2, 'BODY_GUARD_UNMODELLED_CONSTRUCT']);
+  const r4 = runHook('printf -v B %s x; gh issue edit 1 --body-file ~/nonexistent-227.md');
+  eq('a state construct before a tilde body file blocks', r4.code, 2);
+  eq('a plain alias passes', runHook("alias ll='ls -l'").code, 0);
+  eq('a literal write after source passes', runHook(". venv/bin/activate && gh issue edit 1 --body 'hello'").code, 0);
+}
+
+// --- every existing guard suite, re-run through the merged hook ---
+for (const name of ['commit', 'secret', 'install', 'search', 'body']) {
+  const file = path.join(__dirname, `trailhead-${name}-guard.test.js`);
+  const r = spawnSync('node', [file], { 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);
+}
+
+// --- registration: one Bash entry, one command (the merged hook) ---
+{
+  const reg = JSON.parse(fs.readFileSync(path.join(__dirname, 'hooks.json'), 'utf8'));
+  const bashGroups = reg.hooks.PreToolUse.filter((g) => g.matcher === 'Bash');
+  eq('hooks.json has exactly one PreToolUse entry with matcher Bash', bashGroups.length, 1);
+  eq('that entry holds exactly one command', bashGroups[0].hooks.length, 1);
+  ok('and it is the merged hook', bashGroups[0].hooks[0].command.includes('trailhead-bash-guards.js'));
+  ok('no legacy guard script is registered anywhere in hooks.json',
+    !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(JSON.stringify(reg)));
+}
+
+console.log(`trailhead-bash-guards.test.js: ${passed} checks passed`);

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

@@ -9,6 +9,17 @@
 // backstop: it hard-blocks a `gh issue edit` / `gh pr edit` / `gh api` write
 // that would set a body to empty or whitespace-only, protecting the existing
 // body from a degraded read.
+// The command is not required to START with `gh`: the shared statement walk
+// (ghWrites in secret-guard: `;` `&&` `||` `|` newline, subshells, if/then,
+// leading NAME=v) finds every `gh` write, and each one is checked on its own;
+// ANY provably empty body blocks. Opaque writes (eval, sh -c, ...) are ignored
+// (fail-open). After a cd the working directory is unknown, so a relative
+// --body-file / api `@path` is unknowable and never blocks.
+// A construct it cannot interpret with certainty (eval, source / `.`, a bash 5.3
+// `${ cmd; }`, printf -v, a function definition, an alias, a quoted or split `gh api`
+// body key, a backslash-newline inside a word) is not emulated: as a FINAL gate, after
+// the empty-body verdict, it blocks with BODY_GUARD_UNMODELLED_CONSTRUCT when a body
+// write hides behind it or follows it (lib/unmodelled.js is the one closed list; #227).
 // Blocks with exit 2 + {"decision":"block",...}; allows everything else.
 // Fail-OPEN on any error (exit 0): this is a cheap backstop, not a hard
 // dependency, and a crash here must never block a legitimate write.
@@ -17,7 +28,9 @@
 
 const fs = require('fs');
 const os = require('os');
+const path = require('path');
 const { parseGhSubcommand } = require('./lib/gh-subcommand.js');
+const { words, parseRedirects, flagValues, expandWord, STDIN_PATHS } = require('./lib/body-sources.js');
 
 // Is the resolved body text clearly empty or whitespace-only?
 function isEmptyBody(text) {
@@ -44,8 +57,11 @@ function expandHome(p) {
 // Read a --body-file (or api `@file`) target, mirroring secret-guard's
 // bodyFileText: sliced to ~1MB. Throws (ENOENT etc.) are the caller's
 // problem to catch.
-function readBodyFile(filePath) {
-  return fs.readFileSync(expandHome(filePath), 'utf8').slice(0, 1_000_000);
+function readBodyFile(filePath, cwdKnown = true) {
+  const p = expandHome(filePath);
+  // Unknown cwd (after a cd): a relative path may point anywhere, so refuse to guess.
+  if (!cwdKnown && !path.isAbsolute(p)) throw new Error('relative path with unknown cwd');
+  return fs.readFileSync(p, 'utf8').slice(0, 1_000_000);
 }
 
 // Strip one matching pair of surrounding quotes (an artifact of parsing a
@@ -64,47 +80,48 @@ function stripQuotedPair(val) {
   return val;
 }
 
-// Resolve the body for a `gh issue edit` / `gh pr edit` command. Returns:
-//   undefined -> no body param present at all (not a body-carrying write)
+// Resolve the body for a `gh issue edit` / `gh pr edit` command, the way gh
+// does (pflag keeps the LAST occurrence of a repeated flag; pkg/cmd/{issue,pr}/
+// edit rejects --body together with --body-file, and --body counts as provided
+// whenever it appears, while --body-file counts only if its last value is
+// non-empty). Flags are parsed with the shared body-sources helpers. Returns:
+//   undefined -> no body param present at all, or gh would reject the command
+//                        (both --body and a non-empty --body-file: no write)
 //   { body: string } -> known body text
 //   { body: null }   -> a body param IS present but its text is unknowable
 //                        (shell expansion, stdin/process-substitution path,
 //                        or an unreadable --body-file): never block on this.
-function resolveEditBody(cmd) {
-  // --body-file <path> / its short alias -F (quoted or bare; bare stops at
-  // whitespace/shell metacharacters, same tokenizer approach as
-  // secret-guard's bodyFileText). The `(?<![-\w])` guard on -F mirrors
-  // secret-guard's bodyFileText: it stops -F matching when embedded inside
-  // a longer token, and keeps --body-file from being double-matched.
-  const fileMatch = cmd.match(
-    /(?:--body-file|(?<![-\w])-F)(?:=|\s+)(?:"([^"]+)"|'([^']+)'|([^\s"';|&()<>`]+))/
-  );
-  if (fileMatch) {
-    const p = fileMatch[1] || fileMatch[2] || fileMatch[3];
-    if (p === '-' || p.startsWith('<')) return { body: null }; // stdin / process substitution
+function resolveEditBody(cmd, cwdKnown = true) {
+  const { args } = parseRedirects(words(cmd));
+  const files = flagValues(args, '--body-file', '-F');
+  const bodies = flagValues(args, '--body', '-b');
+
+  // Last --body-file value; an empty expanded value means "not provided".
+  let filePath;
+  if (files.length) {
+    const r = expandWord(files[files.length - 1], {}, { HOME: os.homedir() });
+    if (r.unresolved) return { body: null }; // may or may not be empty: unknowable
+    if (r.value !== '') filePath = r.value;
+  }
+
+  if (filePath !== undefined && bodies.length) return undefined; // gh errors, nothing is written
+
+  if (filePath !== undefined) {
+    // Normalise only for this test (/dev//stdin, /dev/./stdin): the read below keeps the raw
+    // path, since the kernel resolves `..` after symlinks, not lexically.
+    if (STDIN_PATHS.has(path.posix.normalize(filePath)) || filePath.startsWith('<')) return { body: null }; // stdin / process substitution
     try {
-      return { body: readBodyFile(p) };
+      return { body: readBodyFile(filePath, cwdKnown) };
     } catch {
       return { body: null }; // unreadable: unknowable, not provably empty
     }
   }
 
-  // Inline --body <val> / --body=<val> / its short alias -b, quoted or
-  // bare. The `(?<![-\w])` guard on -b keeps it from matching the "-b"
-  // that appears inside "--body" itself.
-  const inlineMatch = cmd.match(
-    /(?:--body|(?<![-\w])-b)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S*))/
-  );
-  if (inlineMatch) {
-    const val =
-      inlineMatch[1] !== undefined
-        ? inlineMatch[1]
-        : inlineMatch[2] !== undefined
-        ? inlineMatch[2]
-        : inlineMatch[3];
-    if (val === undefined) return { body: null };
-    if (isShellExpansion(val)) return { body: null };
-    return { body: val };
+  if (bodies.length) {
+    // Empty env: any $VAR, $(...) or backtick is unresolved, hence unknowable.
+    const r = expandWord(bodies[bodies.length - 1], {}, {});
+    if (r.unresolved) return { body: null };
+    return { body: r.value };
   }
 
   return undefined; // no body param at all
@@ -117,7 +134,7 @@ function resolveEditBody(cmd) {
 // unknowable) and a bare value carrying literal surrounding quotes (e.g.
 // `-f body=""`, where the shell hasn't run yet so the quote characters are
 // still in the raw command text).
-function resolveApiBody(cmd) {
+function resolveApiBody(cmd, cwdKnown = true) {
   let raw;
   let m = cmd.match(/(?:-f|-F|--field|--raw-field)\s+"body=([^"]*)"/);
   if (m) raw = m[1];
@@ -137,7 +154,7 @@ function resolveApiBody(cmd) {
     const ref = val.slice(1);
     if (ref === '-') return null; // @- : stdin, unknowable
     try {
-      return readBodyFile(ref);
+      return readBodyFile(ref, cwdKnown);
     } catch {
       return null; // unreadable: unknowable, not provably empty
     }
@@ -153,27 +170,51 @@ function resolveApiBody(cmd) {
 // the resolved text (string), or null when present-but-unknowable. Only
 // `gh issue edit` / `gh pr edit` / `gh api ... body=` are recognised: `create`
 // and `comment` add new content rather than overwrite an existing body, so
-// they are out of scope for this guard.
-function ghBodyWrite(cmd) {
+// they are out of scope for this guard. Handles ONE statement; see
+// ghBodyWrites for a whole (possibly compound) command.
+function ghBodyWrite(cmd, { cwdKnown = true } = {}) {
   const parsed = parseGhSubcommand(cmd);
   if (!parsed) return null;
   const { sub, verb } = parsed;
 
   if ((sub === 'issue' || sub === 'pr') && verb === 'edit') {
-    const resolved = resolveEditBody(cmd);
+    const resolved = resolveEditBody(cmd, cwdKnown);
     if (resolved === undefined) return null; // no body param: not this guard's concern
     return { kind: sub, body: resolved.body };
   }
   if (sub === 'api' && /(?:^|\s)(?:-f|-F|--field|--raw-field)\s+['"]?body=/.test(cmd)) {
-    return { kind: 'api', body: resolveApiBody(cmd) };
+    return { kind: 'api', body: resolveApiBody(cmd, cwdKnown) };
   }
   return null;
 }
 
-function block(kind) {
+// Every body-clobbering write in a whole command: the shared statement walk
+// finds each `gh` write, then each statement is resolved on its own with the
+// cwd state at that point. Opaque writes are skipped. If the walk cannot load
+// (a partial install), fall back to the single-statement check so a leading
+// empty-body write still blocks.
+function ghBodyWrites(cmd) {
+  let ghWrites;
+  try {
+    ({ ghWrites } = require('./trailhead-secret-guard.js'));
+  } catch {
+    const hit = ghBodyWrite(cmd);
+    return hit ? [hit] : [];
+  }
+  const hits = [];
+  for (const w of ghWrites(cmd, {})) {
+    if (w.kind === 'opaque') continue;
+    const hit = ghBodyWrite(w.text, { cwdKnown: w.cwdKnown });
+    if (hit) hits.push(hit);
+  }
+  return hits;
+}
+
+function blockVerdict(kind) {
   const label = kind === 'api' ? 'GitHub API write' : `gh ${kind} edit`;
-  process.stdout.write(
-    JSON.stringify({
+  return {
+    kind: 'block',
+    payload: {
       decision: 'block',
       code: 'EMPTY_ISSUE_BODY_WRITE',
       reason:
@@ -182,30 +223,73 @@ function block(kind) {
         'pre-write read returned an empty or degraded body (e.g. a transient HTTP 5xx on `gh issue view --json body`). ' +
         'Aborting to protect the existing body: re-read the current body (treat a non-200 or empty read as a hard ' +
         'error, retry once with backoff), rebuild it, then write again.',
-    })
-  );
-  process.exit(2);
+    },
+  };
 }
 
-function run(data) {
+// The final gate (#227): a construct the guard cannot interpret (eval, source / `.`, a
+// bash 5.3 `${ cmd; }`, printf -v, a function definition, an alias, a quoted or split
+// `gh api` body key, a backslash-newline inside a word) is blocked, not emulated, when
+// it can matter here: its payload, its later calls, a write after it or its own
+// statement is a body write by ghBodyWrites (a quoted api key only when the body it sets is
+// empty or unknowable).
+// Returns a block verdict or null.
+function unmodelledGate(cmd) {
+  const { findUnmodelled, firstRelevant, unmodelledReason } = require('./lib/unmodelled.js');
+  const hits = findUnmodelled(cmd);
+  // A quoted api key is no gap when the body it sets is known and not empty
+  // (`-f 'body'=@file` is read like the plain form); only an empty or unknowable one is.
+  const emptyOrUnknown = (h) => ghBodyWrites(h.payload).some((w) => w.body === null || w.body === undefined || isEmptyBody(w.body));
+  const hit = firstRelevant(hits, (text) => ghBodyWrites(text).length > 0, ['api-field']) ||
+    hits.find((h) => h.id === 'api-field' && emptyOrUnknown(h));
+  if (!hit) return null;
+  let redact; // the secret-guard's redactor; without it the message omits the sample
   try {
-    let cmd = '';
-    try {
-      cmd = (JSON.parse(data).tool_input || {}).command || '';
-    } catch {
-      process.exit(0); // unparseable input: nothing meaningful to say
-    }
-    const hit = ghBodyWrite(cmd);
-    if (!hit || hit.body === null || hit.body === undefined) {
-      process.exit(0); // not a body write, or a body we cannot prove empty
-    }
-    if (isEmptyBody(hit.body)) {
-      block(hit.kind);
+    ({ redact } = require('./trailhead-secret-guard.js'));
+  } catch {
+    redact = undefined;
+  }
+  return {
+    kind: 'block',
+    payload: {
+      decision: 'block',
+      code: 'BODY_GUARD_UNMODELLED_CONSTRUCT',
+      reason: unmodelledReason('body-guard', 'that it does not overwrite a body with an empty one', hit, redact),
+    },
+  };
+}
+
+// Pure verdict for one command: {kind:'allow'} or {kind:'block', payload}. Never
+// exits or writes; any internal error falls through to allow (a crash here must
+// never block a legitimate write). The unmodelled-construct gate runs last, so an
+// empty body found above keeps its own verdict.
+function evaluate(cmd) {
+  try {
+    for (const hit of ghBodyWrites(cmd)) {
+      if (hit.body === null || hit.body === undefined) continue; // a body we cannot prove empty
+      if (isEmptyBody(hit.body)) return blockVerdict(hit.kind);
     }
-    process.exit(0);
+    const gate = unmodelledGate(cmd);
+    if (gate) return gate;
   } catch {
-    process.exit(0); // never let a crash here block a legitimate write
+    // never let a crash here block a legitimate write
+  }
+  return { kind: 'allow' };
+}
+
+function run(data) {
+  let cmd = '';
+  try {
+    cmd = (JSON.parse(data).tool_input || {}).command || '';
+  } catch {
+    process.exit(0); // unparseable input: nothing meaningful to say
+  }
+  const v = evaluate(cmd);
+  if (v.kind === 'block') {
+    process.stdout.write(JSON.stringify(v.payload));
+    process.exit(2);
   }
+  process.exit(0);
 }
 
 if (require.main === module) {
@@ -218,4 +302,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { ghBodyWrite, isEmptyBody, resolveEditBody, resolveApiBody };
+module.exports = { ghBodyWrite, ghBodyWrites, isEmptyBody, resolveEditBody, resolveApiBody, evaluate };