Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

23.4 KB
Raw Blame
/**
 * The risk lists (design 4.11, spec 10).
 *
 * Never save (never-save.ts, kept off the PreToolUse fast path): a command a
 * skill may never hold, so a run with one gives no skill at all.
 *
 * Gated: a step that can't be undone (publish, push to prod or main, deploy,
 * `gh pr merge`, migrations, `docker system prune`) or that logs in to a
 * service (D93: `npm login`, `gh auth login`, `aws sso login`, ...). It stays
 * in the skill, marked, and Claude Code asks the person right before it runs.
 *
 * The agent guard: commands only the person may run (turn skills or offers
 * on, keep a held skill) and Trail's hook scripts run by hand, which would
 * forge a hook payload. Turning things off is open to anyone.
 *
 * Agents wrap commands (`bash -c`, `env`, `xargs`, `find -exec`, `eval`,
 * `{ }`, `if`, `for`), put flags anywhere (`git push origin main --force`,
 * `npm --registry x publish`) and leave the branch implicit (`git push`), so
 * the lists read the whole text, quotes included, and a target the skill
 * can't know (a variable, a {param}, the current branch) counts as the risky
 * one.
 *
 * The PreToolUse fast path imports this file: besides types it loads only
 * `shell.ts`, which loads only its lexer.
 */
import type { GatedKind } from '../trace/types.js';
import { hookUnrun, quotedTextHit, simpleCommands } from '../trace/shell.js';

export const MAX_RUN_LINES = 12;
export const MAX_STEP_CHARS = 300;

/** The words after a program, to the end of its command (an unquoted-looking `;`, `&`, `|`, `)`, newline or backtick), quotes dropped. */
/** How far past a program word its arguments are read: a call's own arguments, never the rest of a 2 MB command. */
const ARGS_MAX = 4096;

/**
 * The words after `from`, up to the end of that call. `until` is where the next match of the same program starts
 * (callers pass it), so `git push git push …` reads each call once and the whole scan stays linear (g7 review).
 */
export function argsAfter(text: string, from: number, until = text.length): string[] {
  // `$(git rev-parse HEAD)` is one word to the shell, not the end of the command.
  const rest = text.slice(from, Math.min(until, from + ARGS_MAX)).replace(/\$\([^()]*\)/g, '$X');
  const end = rest.search(/[;&|)\n`]/);
  return (end < 0 ? rest : rest.slice(0, end)).split(/\s+/).map((w) => w.replace(/^['"]+|['"]+$/g, '')).filter(Boolean);
}
/** Where a program word starts: not inside another word or path name (`/bin/rm` counts, `git-rm` doesn't). */
export const word = (name: string) => new RegExp(String.raw`(?<![\w./-])(?:[\w./-]*\/)?${name}(?=\s|$)`, 'g');

const PROD = new Set(['main', 'master', 'prod', 'production']);
const GIT_PUSH = /(?<![\w./-])(?:[\w./-]*\/)?git((?:\s+(?:-C|-c|--git-dir|--work-tree|--namespace)\s+\S+|\s+(?!(?:-C|-c|--git-dir|--work-tree|--namespace)\s)-[\w-]+(?:=\S+)?)*)\s+push(?=\s|$|[;&|)'"])/g;

/** One `git push`: forced or not, where it went (`<current>` for the checked-out branch, `<unknown>` for a variable or {param}, `<all>`), and from what. */
export interface Push { force: boolean; dsts: string[]; srcs: string[] }

export function pushes(text: string): Push[] {
  const out: Push[] = [];
  const calls = [...text.matchAll(GIT_PUSH)];
  for (const [i, m] of calls.entries()) {
    const words = argsAfter(text, m.index! + m[0].length, calls[i + 1]?.index);
    let force = false;
    let all = false;
    let tags = false;
    let flagsDone = false;
    const pos: string[] = [];
    for (let i = 0; i < words.length; i++) {
      const w = words[i]!;
      if (!flagsDone && w === '--') flagsDone = true;
      else if (flagsDone || !w.startsWith('-')) pos.push(w);
      else if (/^--force(?:-with-lease)?(?:=.*)?$/.test(w) || /^-[a-zA-Z]*f[a-zA-Z]*$/.test(w)) force = true;
      else if (w === '--mirror') force = all = true;
      else if (w === '--all' || w === '--branches') all = true;
      else if (w === '--tags') tags = true;
      else if (/^(?:-o|--push-option|--repo|--receive-pack|--exec)$/.test(w)) i++;
    }
    const refspecs = pos.slice(1);
    const dsts: string[] = [];
    const srcs: string[] = [];
    for (const r of refspecs) {
      if (r.startsWith('+')) force = true;
      const x = r.replace(/^\+/, '');
      const colon = x.lastIndexOf(':');
      const src = colon < 0 ? x : x.slice(0, colon);
      const dst = (colon < 0 ? x : x.slice(colon + 1)).replace(/^refs\/heads\//, '');
      srcs.push(src);
      dsts.push(dst === 'HEAD' || dst === '@' ? '<current>' : /[$`{}]/.test(dst) || !dst ? '<unknown>' : dst);
    }
    if (all) dsts.push('<all>');
    else if (!refspecs.length && !tags) dsts.push('<current>');
    out.push({ force, dsts, srcs });
  }
  return out;
}
export const unknownDst = (d: string) => d.startsWith('<');
const pushProd = (c: string) => pushes(c).some((p) => p.dsts.some((d) => PROD.has(d.toLowerCase()) || unknownDst(d)));

/** A value written out in the command, not read from a variable or a {param} (`$PW`, `"${PW:?set PW}"`, `{password}`, `<pw>`). */
export const written = (v: string) => {
  const u = v.replace(/^['"]+|['"]+$/g, '');
  return u.length >= 4 && !/^\$|^\{[A-Za-z_]\w*\}$|^<[^>]*>$|^\*+$|^-/.test(u);
};
/** The end of a branch name: not more of a name (`main-fix`, `main/x`, `main.old`). */
const SEP_END = String.raw`(?![\w:-])`;

/**
 * The gated patterns, built once (they ran on every call: a 2 MB command split into pieces built them per piece). Every
 * span inside a call is bounded, and migrate's flags can't be read two ways, so no command makes them backtrack (g7 review).
 */
const PUBLISH_RE = new RegExp(String.raw`\b(?:npm|pnpm|yarn|bun)\b(?:\s+[^\s;&|]+){0,12}?\s+(?:publish|pub)(?![\w:.-])|\b(?:changeset|lerna)\s+publish\b|\bnpx\s+np(?![\w-])|\b(?:poetry|uv|flit|hatch|deno|jsr|vsce|ovsx)\s+publish\b|\bcargo\s+publish\b|\btwine\s+upload\b|\bgem\s+push\b|\b(?:docker|podman)\s+(?:image\s+)?push\b|\bdocker\s+buildx\s+build\b[^;&|\n]{0,300}\s--push\b|\bdotnet\s+nuget\s+push\b|\bpod\s+trunk\s+push\b|\b(?:flutter|dart)\s+pub\s+publish\b|\bmix\s+hex\.publish\b|\bmvn\b[^;&|\n]{0,300}\sdeploy\b|\bgradlew?\b[^;&|\n]{0,300}\spublish\w*\b`, 'i');
const DEPLOY_RE = new RegExp(String.raw`\bvercel\b[^;&|\n]{0,300}\s--prod\b|\bvercel\s+(?:deploy|promote|rollback)\b|\bvercel\s+alias\s+set\b|\bnetlify(?:-cli)?\s+deploy\b[^;&|\n]{0,300}\s--prod\b|\bfly(?:ctl)?\s+deploy\b|\bkubectl\b[^;&|\n]{0,300}?\s(?:apply|create|replace|patch|delete|scale|set|edit|rollout\s+(?:restart|undo))(?![\w-])|\bhelm\b[^;&|\n]{0,300}?\s(?:upgrade|install|uninstall|rollback|delete)(?![\w-])|\b(?:terraform|tofu)\b(?:\s+-chdir=\S+)?\s+(?:apply|destroy)\b|\bwrangler\b[^;&|\n]{0,300}\s(?:deploy|publish)\b|\bgcloud\b[^;&|\n]{0,300}\sdeploy\b|\b(?:serverless|sls|cdk|sam)\s+deploy\b|\bpulumi\s+up\b|\bfirebase\s+deploy\b|\brailway\s+up\b|\bheroku\s+(?:releases:rollback|container:release)\b|\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?deploy(?:[:-]prod(?:uction)?)?${SEP_END}|\bmake\s+deploy(?:-prod(?:uction)?)?${SEP_END}`, 'i');
const MIGRATE_RE = new RegExp(String.raw`\bprisma\s+(?:migrate\s+deploy|db\s+push)\b|\bsupabase\s+(?:db\s+push|migration\s+up)\b|\bknex\s+migrate:latest\b|\balembic\s+upgrade\b|\bdb:migrate\b|\bmanage\.py\s+migrate\b|\becto\.migrate\b|\bflyway\s+migrate\b|\bliquibase\s+update\b|\bdbmate\s+(?:up|migrate)\b|\bdrizzle-kit\s+(?:push|migrate)\b|\bgoose\b[^;&|\n]{0,300}\sup\b|\batlas\s+migrate\s+apply\b|(?:^|[\s/])migrat\w*(?:\s+-{1,2}\w[\w-]*(?:=\S+|\s+(?!-)(?!(?:up|deploy|apply|run)\b)\S+)?){0,16}\s+(?:up|deploy|apply|run)\b|\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:db:)?migrat\w*(?::(?:up|deploy|prod|latest))?${SEP_END}`, 'i');
/**
 * D93: logging in to a service, wherever it sits in the call (`script -q /dev/null npm login`, `env … npm login`,
 * `npx vercel login`). Flags before npm's command are read only as `--flag` or `--flag=value` (a value after a space
 * would let every word be either, which costs a second on 2 MB of `npm --a `); aws's flags take a value either way,
 * a flag word starting with `-` and a value not. Every span is bounded.
 */
const LOGIN_RE = new RegExp([
  String.raw`\b(?:npm|pnpm)(?:\s+-{1,2}[\w-]{1,64}(?:=[^\s;&|]{0,256})?){0,6}\s+(?:login|adduser|add-user)(?![\w:.-])`,
  String.raw`\byarn(?:\s+npm)?\s+login(?![\w:.-])`,
  String.raw`\bgh\s+auth\s+login\b`,
  String.raw`\bvercel\s+login\b`,
  String.raw`\b(?:docker|podman)\s+login\b`,
  String.raw`\baws(?:\s+--[\w-]{1,64}(?:=[^\s;&|]{0,256}|\s+(?!-)[^\s;&|]{1,256})?){0,6}\s+(?:configure(?![\w-])(?!\s+(?:get|list|list-profiles|export-credentials)\b)|sso\s+login\b)`,
  String.raw`\bgcloud\s+auth\s+(?:application-default\s+)?login\b`,
  String.raw`\bfirebase(?:-tools)?\s+login\b`,
  String.raw`\bheroku\s+(?:auth:)?login\b`,
  String.raw`\baz\s+login\b`,
].join('|'), 'i');
const GATED: Array<[GatedKind, (c: string) => boolean]> = [
  ['publish', (c) => PUBLISH_RE.test(c)],
  ['push-prod', pushProd],
  ['deploy', (c) => DEPLOY_RE.test(c)],
  ['merge', (c) => /\bgh\s+pr\s+merge\b|\bglab\s+mr\s+merge\b/i.test(c)
    || (/\bgh\s+api\b/i.test(c) && /(?:-X|--method)[\s=]+(?:PUT|POST)\b/i.test(c) && /\/pulls\/[^/\s'"]+\/merge\b|\/merges\b/i.test(c))],
  ['migrate', (c) => MIGRATE_RE.test(c)],
  ['prune', (c) => /\b(?:docker|podman)\s+(?:system|volume|image|container)\s+prune\b|\b(?:docker|podman)\s+volume\s+rm\b/i.test(c)],
  ['login', (c) => LOGIN_RE.test(c)],
];

/** `--dry-run`, `--dry-run=client`: changes nothing. `--dry-run=false` and kubectl's `--dry-run=none` do. */
const DRY = /(?:^|\s)--dry-run(?:=(?!(?:false|0|none)\b)\S+)?(?=\s|$|[;&|)])/;

/** Every gated kind whose pattern appears anywhere in `cmd`, dry run or not: linear, for a command too long to split (3.3). */
export function gatedAnywhere(cmd: string): Set<GatedKind> {
  const c = String(cmd ?? '');
  return new Set(GATED.filter(([, hit]) => hit(c)).map(([kind]) => kind));
}

export function gatedKind(cmd: string): GatedKind | null {
  const c = String(cmd ?? '');
  // A dry run changes nothing: only the commands without one count.
  const parts = DRY.test(c) ? simpleCommands(c).filter((x) => !DRY.test(x)) : [c];
  for (const p of parts) for (const [kind, hit] of GATED) if (hit(p)) return kind;
  return null;
}

const REGISTRY: Array<[RegExp, string]> = [
  [/\bcargo\s+publish\b/i, 'crates.io'], [/\btwine\s+upload\b|\b(?:poetry|uv|flit|hatch)\s+publish\b/i, 'PyPI'], [/\bgem\s+push\b/i, 'RubyGems'],
  [/\b(?:docker|podman)\b/i, 'the image registry'], [/\b(?:vsce|ovsx)\s+publish\b/i, 'the extension marketplace'],
];
const SHA = /^[0-9a-f]{7,40}$/;
/** Which service a login step logs in to, for its ask. */
const LOGIN_TO: Array<[RegExp, string]> = [
  [/\b(?:npm|pnpm|yarn)\b/i, 'npm'], [/\bgh\s+auth\b/i, 'GitHub'], [/\bvercel\b/i, 'Vercel'], [/\b(?:docker|podman)\s+login\b/i, 'the image registry'],
  [/\baws\b/i, 'AWS'], [/\bgcloud\b/i, 'Google Cloud'], [/\bfirebase/i, 'Firebase'], [/\bheroku\b/i, 'Heroku'], [/\baz\s+login\b/i, 'Azure'],
];

/** D116 item 5: the login a command runs, as the person would type it (flags dropped), and the service; null when none. */
export function loginOf(cmd: string): { service: string; login: string } | null {
  const m = LOGIN_RE.exec(String(cmd ?? ''));
  if (!m) return null;
  const login = m[0].replace(/\s+-{1,2}[\w-]+(?:=\S*)?/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
  return { service: LOGIN_TO.find(([re]) => re.test(m[0]))?.[1] ?? 'the service', login };
}

/** "publishes 0.22.1 to npm", "moves prod to 4e1c9a2", ... (4.11). */
export function gatedWhat(kind: GatedKind, cmd: string, values: Record<string, string>): string {
  // A value worked out when it runs (`$(git rev-parse HEAD)`) reads as a variable.
  const fill = (t: string) => t.replace(/\{([A-Za-z_]\w*)\}/g, (m, k: string) => (values[k] === undefined ? m : /[$`]/.test(values[k]!) ? '$X' : values[k]!));
  const c = fill(String(cmd ?? ''));
  if (kind === 'publish') {
    const where = REGISTRY.find(([re]) => re.test(c))?.[1] ?? 'npm';
    const v = values.version;
    return `publishes ${v && !v.includes('$') ? v : 'a new version'} to ${where}`;
  }
  if (kind === 'push-prod') {
    for (const p of pushes(c)) {
      const i = p.dsts.findIndex((d) => PROD.has(d.toLowerCase()));
      if (i >= 0) {
        const src = p.srcs[i] ?? '';
        const to = SHA.test(src) ? src.slice(0, 7) : !src || /[$`{}]/.test(src) || src === 'HEAD' || src === p.dsts[i] ? 'HEAD' : src;
        return `moves ${p.dsts[i]} to ${to}`;
      }
      if (p.dsts.includes('<all>')) return 'pushes every branch';
      if (p.dsts.includes('<current>')) return 'pushes the current branch';
      if (p.dsts.includes('<unknown>')) return 'pushes to a branch named when it runs';
    }
    // A branch the skill fills in when it runs: not a branch name to show.
    if (c !== String(cmd ?? '') && pushes(String(cmd).replace(/\{[A-Za-z_]\w*\}/g, '$X')).some((p) => p.dsts.includes('<unknown>'))) {
      return 'pushes to a branch named when it runs';
    }
    return 'moves prod';
  }
  if (kind === 'deploy') return 'deploys to production';
  if (kind === 'merge') {
    const pr = values.pr ?? /\bmerge\s+#?(\d+)\b|\/pulls\/(\d+)\/merge\b/.exec(c)?.slice(1).find(Boolean);
    return pr && /^\d+$/.test(pr) ? `merges PR #${pr}` : 'merges a PR';
  }
  if (kind === 'migrate') return 'runs a database migration';
  if (kind === 'login') return `logs in to ${LOGIN_TO.find(([re]) => re.test(c))?.[1] ?? 'a service'}`;
  return 'deletes unused Docker data';
}

/** Consecutive steps of one gated kind form one group; one host ask covers a group (3.3). */
export function gatedGroups(steps: Array<{ n: number; gated: GatedKind | null }>): Array<{ kind: GatedKind; steps: number[] }> {
  const out: Array<{ kind: GatedKind; steps: number[] }> = [];
  let prev: GatedKind | null = null;
  for (const s of steps) {
    if (s.gated && s.gated === prev) out[out.length - 1]!.steps.push(s.n);
    else if (s.gated) out.push({ kind: s.gated, steps: [s.n] });
    prev = s.gated;
  }
  return out;
}

/** Phase 2 (P28): `restore-version`, an older version of a skill brought back. */
export type GuardHit = 'skills-on' | 'offers-on' | 'keep-held' | 'hook-script' | 'restore-version';

/** A Trail program word anywhere in the call: named, through a package, an alias or a variable (`t=trail`). */
const TRAIL_WORD = /(?<![\w./-])(?:trail|graft|trail-code)(?![\w./-])|@trailhq\/trail-code\b|@nanonets\/graft\b|\bbin\/(?:trail|graft)\.js\b/i;
/**
 * Flags between `skills` and the switch. Bounded, like every quantifier below: the guard reads commands of up to
 * 2 MB on the 5 s PreToolUse budget, after which Claude Code runs the command anyway (g7 review).
 */
const FL = String.raw`(?:-[^\s]{1,64}\s+){0,8}`;
const REASONS: Record<GuardHit, string> = {
  'offers-on': 'Only the person turns skill offers on, in their own terminal: trail skills offers on. Tell the person; don\'t run it for them.',
  'skills-on': 'Only the person turns skills on, in their own terminal: trail skills on. Tell the person; don\'t run it for them.',
  'keep-held': 'Keeping a held skill is the person\'s yes, so only the person runs trail skills keep, in their own terminal. Tell the person; don\'t run it for them.',
  'hook-script': 'Trail\'s hook scripts run only from the host\'s hooks, never by hand. If something about Trail looks wrong, tell the person.',
  'restore-version': 'Only the person brings back an older version of a skill, in their own terminal: trail skills restore {name} --version {n}. Tell the person; don\'t run it for them.',
};

/**
 * The person-only switches after `skills`, whatever runs them: a Trail binary, a renamed or copied one
 * (`node /tmp/t.js skills on`), an alias or a variable (`T=trail; $T skills on`). Printing them is denied too.
 */
const SWITCH: Array<[GuardHit, RegExp]> = [
  ['offers-on', new RegExp(String.raw`\bskills\s+${FL}offers\s+${FL}on\b`, 'i')],
  ['skills-on', new RegExp(String.raw`\bskills\s+${FL}on\b`, 'i')],
  ['keep-held', new RegExp(String.raw`\bskills\s+${FL}keep\b`, 'i')],
];
/** With a Trail word in the call: the switch not written out (`trail skills $x`, `trail skills $(echo on)`). */
const DYNAMIC_SWITCH: Array<[GuardHit, RegExp]> = [
  ['offers-on', new RegExp(String.raw`\bskills\s+${FL}offers\s+${FL}[$\x60]`, 'i')],
  ['skills-on', new RegExp(String.raw`\bskills\s+${FL}[$\x60]`, 'i')],
];
/** With a Trail word in the call: the word `skills` not written out (`trail $s on`, `trail $(echo skills) on`). */
const AFTER = String.raw`\s+${FL}(?:(offers)\s+${FL}on|(on)|(keep))\b`;
const DYNAMIC_WORD: Array<[RegExp, RegExp]> = [
  [/\$\w/, new RegExp(String.raw`\$\w{1,64}${AFTER}`, 'i')],
  [/\$\{/, new RegExp(String.raw`\}${AFTER}`, 'i')],
  [/\$\(/, new RegExp(String.raw`\)${AFTER}`, 'i')],
  [/\x60/, new RegExp(String.raw`\x60${AFTER}`, 'i')],
];
/** xargs or parallel supplying the switch from stdin: `skills` ends the call or a placeholder follows it. */
const XARGS = /\b(?:xargs|parallel)\b/i;
const XARGS_SKILLS = /\bskills(?:\s+-[^\s]{1,64}){0,8}\s*(?:$|\{\}|%)/i;
/**
 * P28: `skills restore <name> --version <n>`, read per command (split on `; & | newline`, one pass, so a flag
 * any distance after the verb is found and a 2 MB command stays linear). With a Trail word in the call, also the
 * forms that don't write it out: the flag or the verb from a variable or a substitution, or `skills` itself.
 */
const RESTORE_AT = new RegExp(String.raw`\bskills\s+${FL}restore\b`, 'i');
const RESTORE_SKILLS_DYNAMIC = new RegExp(String.raw`\bskills\s+${FL}[$\x60]`, 'i');
const RESTORE_WORD_DYNAMIC = new RegExp(String.raw`(?:\$\w{1,64}|[})\x60])\s+${FL}restore\b`, 'i');
const VERSION_FLAG = /(?<![\w-])--version(?![\w-])/;
function restoreVersionIn(c: string, trailWord: boolean): boolean {
  if (!/restore|--version/i.test(c)) return false;
  for (const seg of c.split(/[;&|\n]/)) {
    const m = RESTORE_AT.exec(seg);
    const rest = m ? seg.slice(m.index + m[0].length) : '';
    if (m && VERSION_FLAG.test(rest)) return true;
    if (!trailWord) continue;
    if (m && /[$\x60]/.test(rest)) return true;
    if (VERSION_FLAG.test(seg) && (RESTORE_SKILLS_DYNAMIC.test(seg) || RESTORE_WORD_DYNAMIC.test(seg))) return true;
  }
  return false;
}
/**
 * Trail's hook scripts and hook modules: the shims by name or by a glob (`t*-hooks.cjs`, `trail-hook?.cjs`), a
 * helpers path the shell works out (`.claude/helpers/*`, `.claude/helpers/$(ls …)`), and the package's
 * `dist/claude/<module>.js` run or imported by hand.
 */
const HOOK_SCRIPT = [
  /\b(?:trail|graft)-hooks?[\w*?[\]-]{0,64}(?:\.cjs\b|\*)/i,
  /hooks?[*?[\]]{0,8}\.cjs\b/i,
  /\.claude\/helpers\/[^\s/]{0,64}[*?[$\x60]/i,
  /(?:@trailhq\/trail-code|@nanonets\/graft|\bdist)\/(?:dist\/)?claude\/[\w-]{1,64}\.js\b/i,
];

/** What `shellWords` drops: a line continuation, then any quote or backslash. */
const UNSAID = /\\\n|["'\\]/g;

/** The words the shell runs: quotes and backslashes don't change them, and a line continuation joins with nothing. */
export function shellWords(cmd: string): string {
  const s = String(cmd ?? '');
  // Slices between the few dropped characters; past 4,096 of them, one pass over char codes (two regex
  // replaces cost 20+ ms on 2 MB of `"a" `; a copy of a 2 MB command with a few quotes costs 13).
  let r = '';
  let last = 0;
  let n = 0;
  UNSAID.lastIndex = 0;
  for (let m = UNSAID.exec(s); m; m = UNSAID.exec(s)) {
    r += s.slice(last, m.index);
    last = m.index + m[0].length;
    if (++n > 4096) return r + dropUnsaid(s, last);
  }
  return last ? r + s.slice(last) : s;
}

function dropUnsaid(s: string, from: number): string {
  const out = new Uint16Array(s.length - from);
  let k = 0;
  for (let i = from; i < s.length; i++) {
    const c = s.charCodeAt(i);
    if (c === 34 || c === 39) continue;
    if (c === 92) {
      if (s.charCodeAt(i + 1) === 10) i++;
      continue;
    }
    out[k++] = c;
  }
  let r = '';
  for (let i = 0; i < k; i += 8192) r += String.fromCharCode.apply(null, out.subarray(i, Math.min(k, i + 8192)) as unknown as number[]);
  return r;
}

function hitOf(m: RegExpExecArray): GuardHit {
  return m[1] ? 'offers-on' : m[2] ? 'skills-on' : 'keep-held';
}

/** Past this a command is read whole: any switch denies, wherever it sits (the lexer on 2 MB takes seconds). */
const TEXT_MAX = 64 * 1024;

/** The switch written out, as the shell's words read: `skills on`, `skills offers on`, `skills keep`. */
function staticSwitch(c: string): GuardHit | null {
  if (!/skills/i.test(c)) return null;
  for (const [hit, re] of SWITCH) if (re.test(c)) return hit;
  return restoreVersionIn(c, false) ? 'restore-version' : null;
}

/** The switch or the word `skills` not written out, with a Trail word in the call, and xargs supplying it. */
function dynamicSwitch(c: string, trailWord: boolean): GuardHit | null {
  if (trailWord && restoreVersionIn(c, true)) return 'restore-version';
  if (trailWord) {
    for (const [hit, re] of DYNAMIC_SWITCH) if (re.test(c)) return hit;
    for (const [has, re] of DYNAMIC_WORD) {
      const m = has.test(c) ? re.exec(c) : null;
      if (m) return hitOf(m);
    }
  }
  if (XARGS.test(c)) {
    for (const seg of c.split(/[;&|\n]/)) if (XARGS.test(seg) && XARGS_SKILLS.test(seg)) return 'skills-on';
  }
  return null;
}

/**
 * D89: a switch found in the text is denied where the shell runs it, not where it is only words: inside quoted
 * arguments of grep, rg, git commit or log, echo or printf not fed to a shell, sed, awk patterns, cat. Over
 * TEXT_MAX, or when no one command carries it, the whole text decides.
 */
function runsSwitch(cmd: string, whole: GuardHit, find: (c: string) => GuardHit | null): GuardHit | null {
  if (cmd.length > TEXT_MAX) return whole;
  return quotedTextHit(cmd, (t) => find(shellWords(t)), whole);
}

const hookNamed = (t: string) => (HOOK_SCRIPT.some((re) => re.test(shellWords(t))) ? true : null);

const namesHook = (t: string) => hookNamed(t) === true;
/** fix-lab5: a command only naming a hook script leaves it unrun (shell-words' hookUnrun: a read, a delete, a check, an edit of another file). */
const leavesHookUnrun = <T>(head: string, bodies: string[], hitOf: (text: string) => T | null) => hookUnrun(head, bodies, hitOf, namesHook);

/** D116 item 2: the hook script is run, not only read (an argument of grep, sed, cat, a pager, head, git log) or named (fix-lab5). */
function runsHookScript(raw: string): boolean {
  if (raw.length > TEXT_MAX) return true;
  return quotedTextHit(raw, hookNamed, true, 0, leavesHookUnrun) !== null;
}

/** P28's words, with the person's own command when the name and version are written out (else `<name>`, `<n>`). */
function restoreReason(c: string): string {
  const m = /\bskills\s+restore\s+([a-z0-9][a-z0-9-]{0,63})\s+--version[=\s]([1-9]\d{0,5})(?![\w-])/i.exec(c)
    ?? /\bskills\s+restore\s+--version[=\s]([1-9]\d{0,5})\s+([a-z0-9][a-z0-9-]{0,63})(?![\w-])/i.exec(c);
  const [name, n] = m ? (/^\d/.test(m[1]!) ? [m[2]!, m[1]!] : [m[1]!, m[2]!]) : ['<name>', '<n>'];
  return REASONS['restore-version'].replace('{name}', name).replace('{n}', n);
}

/** 4.11 agent guard: commands only the person may run, and Trail's hook scripts run by hand. Linear in the command. */
export function agentGuard(cmd: string): { hit: GuardHit; reason: string } | null {
  const raw = String(cmd ?? '');
  const c = shellWords(raw);
  const found = (hit: GuardHit) => ({ hit, reason: hit === 'restore-version' ? restoreReason(c) : REASONS[hit] });
  const fixed = staticSwitch(c);
  const ran = fixed && runsSwitch(raw, fixed, staticSwitch);
  if (ran) return found(ran);
  if (HOOK_SCRIPT.some((re) => re.test(c)) && runsHookScript(raw)) return found('hook-script');
  const trailWord = TRAIL_WORD.test(c);
  const dynamic = dynamicSwitch(c, trailWord);
  const ranDynamic = dynamic && runsSwitch(raw, dynamic, (t) => dynamicSwitch(t, trailWord));
  return ranDynamic ? found(ranDynamic) : null;
}