Skip to content

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

7.4 KB
Raw Blame
/**
 * The agent guard under attack (g7-hooks review): commands only the person
 * may run (turn skills or offers on, keep a held skill) and Trail's hook
 * scripts run by hand, through a renamed or copied binary, a word held in a
 * variable, xargs, a line continuation, a glob, or the hook modules
 * imported straight from the package; and a command built to make the
 * guard's own regexes run past the hook's 5 s timeout, after which Claude
 * Code runs the command anyway. Each form must also get past the inline
 * prefilter, or the guard never loads. Turning things off stays open.
 */
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { agentGuard } from '../src/skills/risk.js';
import { skillsPrefilter } from '../src/claude/pre-bash.js';
import { preBashSkills } from '../src/claude/pre-bash-skills.js';
import { timeBar } from './machine-speed.js';

const ENV = { HOME: '/tmp/g7-guard-home', TRAIL_HOME: '/tmp/g7-guard-home/.trail' };
const input = (command: string) => ({ session_id: 'sess-guard', tool_name: 'Bash', tool_input: { command } });

const DENIED: Array<[string, string]> = [
  // A renamed, copied or linked CLI: no Trail word in front of `skills`.
  ['node /tmp/t.js skills on', 'skills-on'],
  ['/tmp/t skills offers on', 'offers-on'],
  ['node dist/cli.js skills keep release-npm', 'keep-held'],
  ['./bin/x skills --json on', 'skills-on'],
  // The word `skills` or the switch held in a variable or a substitution.
  ['s=skills; trail $s on', 'skills-on'],
  ['trail $(echo skills) on', 'skills-on'],
  ['trail ${S:-skills} keep x', 'keep-held'],
  ['trail `echo skills` offers on', 'offers-on'],
  // The switch from stdin.
  ['echo on | xargs trail skills', 'skills-on'],
  ['xargs -I{} trail skills {} <<< on', 'skills-on'],
  ['printf "on" | xargs -n1 /tmp/t skills', 'skills-on'],
  // A line continuation inside a word: the shell joins it with nothing.
  ['tr\\\nail skills on', 'skills-on'],
  ['trail skills o\\\nn', 'skills-on'],
  // Hook scripts: globs, a name the shell works out, the package's hook modules imported by hand.
  ['node .claude/helpers/t*-hooks.cjs prompt < f.json', 'hook-script'],
  ['node .claude/helpers/trail-hook?.cjs stop', 'hook-script'],
  ['node .claude/helpers/$(ls .claude/helpers | head -1) prompt', 'hook-script'],
  ['cat .claude/helpers/* > /tmp/h.cjs', 'hook-script'],
  ['node ~/.claude/helpers/*.cjs session-start', 'hook-script'],
  ['node -e "import(\'/x/node_modules/@trailhq/trail-code/dist/claude/hooks.js\').then((m) => m.main(\'prompt\'))"', 'hook-script'],
  ['node node_modules/@nanonets/graft/dist/claude/pre-bash.js < forged.json', 'hook-script'],
  ['echo {} | node dist/claude/hooks.js', 'hook-script'],
];

const OPEN = [
  'trail skills off', 'trail skills offers off', 'trail skills offers off --here', 'trail skills off release-npm', 'trail skills',
  'trail skills show release-npm', 'trail skills draft r-1027-3f9a --print', 'trail forget release-npm', 'echo x | xargs trail skills show',
  'npm run skills; echo on', "git commit -m 'skills: offer once'", 'ls .claude/helpers', 'cat .claude/settings.json', 'git log -- .husky/pre-commit',
  'npm test -- --grep hooks', 'ls src/claude', 'node --test test/claude-hooks.test.ts',
];

test('the agent guard denies the person-only switches and the hook scripts in every form above, and each gets past the prefilter', async () => {
  for (const [cmd, hit] of DENIED) {
    assert.equal(agentGuard(cmd)?.hit, hit, cmd);
    assert.equal(skillsPrefilter(input(cmd), cmd, ENV), true, `prefilter: ${cmd}`);
    const d = await preBashSkills(input(cmd), '/tmp', ENV, cmd);
    assert.equal(d?.permissionDecision, 'deny', cmd);
  }
});

test('turning things off, listing, and commands that only mention the words stay open', () => {
  for (const cmd of OPEN) assert.equal(agentGuard(cmd), null, cmd);
});

test('a command built to make the guard backtrack is still read well inside the hook timeout', () => {
  // In a child process: a regex that backtracks blocks the event loop, so a test timeout can't stop it in here.
  const probe = `
    const { agentGuard } = await import(${JSON.stringify(new URL('../src/skills/risk.ts', import.meta.url).href)});
    const { skillsPrefilter } = await import(${JSON.stringify(new URL('../src/claude/pre-bash.ts', import.meta.url).href)});
    const big = 1900000;
    const cases = [
      'trail skills on; ' + 'trail '.repeat(big / 6),
      'trail skills keep x; ' + 'graft x '.repeat(big / 8),
      'node .claude/trail-hooks.cjs prompt; ' + 'trail-hooks-'.repeat(big / 12),
      'trail skills on; ' + '$('.repeat(big / 2),
      'trail skills on; ' + 'skills -a '.repeat(big / 10),
      'trail skills on; ' + 'xargs '.repeat(big / 6),
      'trail skills on; ' + '.claude/helpers/'.repeat(big / 16),
    ];
    const out = cases.map((c) => {
      const t = Date.now();
      const hit = agentGuard(c)?.hit ?? null;
      const pre = skillsPrefilter({}, c, {});
      return { hit, pre, ms: Date.now() - t };
    });
    process.stdout.write(JSON.stringify(out));`;
  const r = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', probe], { encoding: 'utf8', timeout: 30_000 });
  assert.equal(r.signal, null, 'the guard ran past 30 s');
  const rows = JSON.parse(r.stdout) as Array<{ hit: string | null; pre: boolean; ms: number }>;
  const bar = timeBar(1500, 4500);
  for (const row of rows) {
    assert.ok(row.hit && row.pre, JSON.stringify(row));
    assert.ok(row.ms < bar, `${JSON.stringify(row)} over ${bar} ms`);
  }
});

import { tamperOf } from '../src/trace/tamper.js';

test('every hook-script form the guard denies also marks the session as one that touched Trail\'s files (4.9: tamper if it got through)', () => {
  const ctx = { trailHome: '/home/dev/.trail', transcriptPath: '/home/dev/.claude/projects/-home-dev-shop/s.jsonl', home: '/home/dev', folder: '/home/dev/shop' };
  for (const [cmd, hit] of DENIED) {
    if (hit !== 'hook-script') continue;
    assert.match(tamperOf('Bash', { command: cmd }, cmd, ctx) ?? '', /^Bash /, cmd);
  }
  assert.equal(tamperOf('Bash', { command: 'ls .claude/helpers' }, 'ls .claude/helpers', ctx), null);
});

test('the gated patterns read a long command in linear time: no span inside a call backtracks, and migrate\'s flags parse one way', () => {
  const probe = `
    const { gatedKind, gatedAnywhere } = await import(${JSON.stringify(new URL('../src/skills/risk.ts', import.meta.url).href)});
    const units = ['git push ', 'vercel ', 'netlify deploy ', 'kubectl ', 'helm ', 'mvn ', 'gradle ', 'wrangler ', 'gcloud ', 'goose ',
      'docker buildx build ', 'migrate --a ', 'migrate --a b ', 'a/', '/a/a/', 'rm -rf ', 'find . '];
    const out = units.map((u) => {
      const c = u.repeat(Math.floor(400000 / u.length));
      const t = Date.now();
      gatedKind(c);
      gatedAnywhere(c);
      return { u, ms: Date.now() - t };
    });
    const flags = 'migrate ' + '--a '.repeat(24) + 'x';
    const t = Date.now();
    gatedKind(flags);
    out.push({ u: 'migrate with 24 flags', ms: Date.now() - t });
    process.stdout.write(JSON.stringify(out));`;
  const r = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', probe], { encoding: 'utf8', timeout: 60_000 });
  assert.equal(r.signal, null, 'the gated patterns ran past 60 s');
  const bar = timeBar(1500, 4500);
  for (const row of JSON.parse(r.stdout) as Array<{ u: string; ms: number }>) assert.ok(row.ms < bar, `${JSON.stringify(row)} over ${bar} ms`);
});