Skip to content

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

6.5 KB
Raw Blame
/**
 * D116 item 2: the hook-script guard blocks running Trail's hook script by
 * hand, never reading it. An agent looking into Trail's wiring greps, seds,
 * cats, pages or heads `.claude/helpers/trail-hooks.cjs`; that is a read.
 * Running it stays denied whatever runs it: node, a shell, `./`, xargs, a
 * substitution, npx, an env prefix, or a read piped into one of them.
 * Made-up repos and paths only.
 */
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { agentGuard } from '../src/skills/risk.js';
import { preBashSkills } from '../src/claude/pre-bash-skills.js';
import { tamperOf } from '../src/trace/tamper.js';

const ENV = { HOME: '/tmp/hook-read-home', TRAIL_HOME: '/tmp/hook-read-home/.trail' };
const input = (command: string) => ({ session_id: 'sess-hook-read', tool_name: 'Bash', tool_input: { command } });
const CTX = { trailHome: '/home/dev/.trail', transcriptPath: '/home/dev/.claude/projects/-home-dev-shop/s.jsonl', home: '/home/dev', folder: '/home/dev/shop' };
const H = '.claude/helpers/trail-hooks.cjs';

const READS = [
  // The lab's two reads (H2, H4), in synthetic form.
  `grep -n "skillsGate\\|preBash" ${H}`,
  `sed -n '1,400p' ${H} | grep -n "prompt"`,
  `cat ${H}`,
  `less ${H}`,
  `head -40 ${H}`,
  `tail -n 20 ${H} | wc -l`,
  `wc -l ${H} /home/dev/shop/.claude/helpers/graft-hooks.cjs`,
  `cd /home/dev/shop && grep -c main ${H}`,
  `grep "skills on" .claude/trail-hooks.cjs`,
  `cat .claude/helpers/* | grep -n require`,
  `rg -n "stop" ${H} > /dev/null && echo found`,
  `git log --oneline -- ${H}`,
  `git diff -- ${H}`,
];

const RUNS = [
  `node ${H} stop < payload.json`,
  `sh ${H} prompt`,
  `bash ${H} session-start`,
  `./${H} prompt`,
  `echo ${H} | xargs node`,
  `ls ${H} | xargs -I{} node {} stop`,
  `node -e "$(cat ${H})"`,
  `$(cat ${H}) stop`,
  `npx node ${H} stop`,
  `env CLAUDE_PROJECT_DIR=/home/dev/shop node ${H} stop`,
  `FOO=1 node ${H} stop`,
  `cat ${H} | node - stop`,
  `cat ${H} | sh`,
  `head -100 ${H} > /tmp/h.cjs`,
  `cat .claude/helpers/* > /tmp/h.cjs`,
  `grep -n x $(node ${H} stop)`,
  `less '+!node ${H} stop' README.md`,
  `head -1 ${H}; node ${H} stop`,
  `sed -i 's/a/b/' ${H}`,
  `rg --pre node stop ${H}`,
  `find .claude -name trail-hooks.cjs -exec node {} stop \\;`,
  `cat <(node ${H} stop)`,
];

test('reading the hook script (grep, sed, cat, less, head, tail, wc, git log) is not running it: no deny, no tamper mark', async () => {
  for (const cmd of READS) {
    assert.equal(agentGuard(cmd), null, cmd);
    const d = await preBashSkills(input(cmd), '/tmp', ENV, cmd);
    assert.notEqual(d?.permissionDecision, 'deny', cmd);
    assert.equal(tamperOf('Bash', { command: cmd }, cmd, CTX), null, cmd);
  }
});

test('running the hook script stays denied, through node, a shell, ./, xargs, a substitution, npx, env, a pipe or a copy', async () => {
  for (const cmd of RUNS) {
    assert.equal(agentGuard(cmd)?.hit, 'hook-script', cmd);
    const d = await preBashSkills(input(cmd), '/tmp', ENV, cmd);
    assert.equal(d?.permissionDecision, 'deny', cmd);
    assert.match(tamperOf('Bash', { command: cmd }, cmd, CTX) ?? '', /^Bash /, cmd);
  }
});

// fix-lab5: the 1b lab's hook replay found 11 commands in Trail's own development that only mention a hook script:
// a python heredoc that edits source naming the shim, `cat >> notes <<EOF` prose, a hooks.json written from a heredoc.
// Also deleting a stale copy, a syntax check, an existence test and git bookkeeping. None of them runs it.
const MENTIONS = [
  `git diff -- ${H}`,
  `ls -la ${H}`,
  'rm -f /tmp/x/box/.claude/helpers/trail-hooks.cjs',
  'rm -rf /tmp/x/box/.claude/helpers/graft-hooks.cjs /tmp/x/box/.claude/helpers/graft-statusline.cjs',
  `node --check ${H}`,
  `node -c ${H} && echo ok`,
  `test -f ${H} && echo wired`,
  `[ -e ${H} ] || echo missing`,
  `git add ${H} src/claude/shim-template.ts`,
  `git checkout -- ${H}`,
  'git commit -q -m "docs: say trail-hooks.cjs fails open"',
  `cd /home/dev/trail && python3 - <<'EOF'\np='src/claude/hook-owner.ts'\ns=open(p).read()\ns=s.replace("if (!existsSync(join(dir, '.claude', 'helpers', 'graft-hooks.cjs'))) return false;", "if (!shimThere(dir)) return false;")\nopen(p,'w').write(s)\nEOF`,
  `python3 -I - <<'EOF'\np='test/hook-owner.test.ts'\ns=open(p).read()\ns=s.replace("writeFileSync(join(repo, '.claude', 'helpers', 'graft-hooks.cjs'), '// shim')", "writeShim(repo)")\nopen(p,'w').write(s)\nEOF`,
  `cat >> docs/notes.md <<'EOF'\n- The hook-script guard blocks running trail-hooks.cjs, never reading it.\nEOF`,
  `cat > hooks/hooks.json <<'EOF'\n{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"node \\"\${PLUGIN_ROOT}/scripts/hook.cjs\\" stop"}]}]}}\nEOF`,
  `node -e 'const s = require(process.argv[1]); console.log(Object.keys(s.hooks))' .claude/settings.json`,
  `cat >> test/settings-merge.test.ts <<'EOF'\nconst entry = { command: \`node "\${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/graft-hooks.cjs" stop\` };\nEOF`,
];

const STILL_RUNS = [
  `python3 - <<'EOF'\nimport subprocess\nsubprocess.run(['node', '.claude/helpers/trail-hooks.cjs', 'stop'])\nEOF`,
  `python3 -c "import os; os.system('node .claude/helpers/trail-hooks.cjs stop')"`,
  `node -e "require('./.claude/helpers/trail-hooks.cjs')"`,
  `node - <<'EOF'\nrequire('child_process').execFileSync(process.execPath, ['.claude/helpers/graft-hooks.cjs', 'prompt'])\nEOF`,
  `node -r ./.claude/helpers/trail-hooks.cjs app.js`,
  `cat > ${H} <<'EOF'\n// mine now\nEOF`,
  `rm -f ${H}.bak && node ${H} stop`,
  `node --check ${H} && node ${H} stop`,
  `rm -f $(node ${H} stop)`,
  `test -f ${H} && sh ${H} prompt`,
  `H=${H}; node $H stop`,
  `git add ${H} && git commit -m x && node ${H} stop`,
  `cat > /tmp/x/run.sh <<'EOF'\nnode .claude/helpers/trail-hooks.cjs stop\nEOF\nsh /tmp/x/run.sh`,
  `tee /tmp/x/run.cjs <<'EOF'\nrequire('/home/dev/shop/.claude/helpers/trail-hooks.cjs')\nEOF`,
];

test('a command that only mentions a hook script (edits other files, deletes a stale copy, checks it) is not denied (fix-lab5)', async () => {
  for (const cmd of MENTIONS) {
    assert.equal(agentGuard(cmd), null, cmd);
    const d = await preBashSkills(input(cmd), '/tmp', ENV, cmd);
    assert.notEqual(d?.permissionDecision, 'deny', cmd);
  }
});

test('running it stays denied, also from code an interpreter is given, a heredoc into the hook, or a chain after a mention', async () => {
  for (const cmd of STILL_RUNS) {
    assert.equal(agentGuard(cmd)?.hit, 'hook-script', cmd);
    const d = await preBashSkills(input(cmd), '/tmp', ENV, cmd);
    assert.equal(d?.permissionDecision, 'deny', cmd);
  }
});