Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* PreToolUse on Bash: the hook that runs before every shell command the agent
* runs, as its own entry point.
*
* It must cost next to nothing, so the shim sends `pre-bash` here rather than
* to hooks.js, and this file imports nothing at load time: node:fs comes from
* `process.getBuiltinModule` (an ESM `import ... from 'node:fs'` alone costs
* Node several ms), and hook-layers.ts is loaded only when there is a decision
* to send. None of the graph, telemetry and learnings code the other hooks
* share. It fails open: bad stdin, an error, or a decision that isn't well
* formed all leave it silent with exit 0, so the command runs as if Trail
* weren't here. A check that can wedge every shell command is worse than none.
*
* The learned-skills part (the agent guard, the save gate, the one ask
* before a step that can't be undone) lives in pre-bash-skills.ts and is
* loaded only past `skillsPrefilter`: a command that says `skills` or names
* a Trail hook script, or a session with a gate file. It writes (receipts,
* asked marks), so only the copy that answers runs it: the repo's copy
* stands down first when the `~/.claude` copy covers the event. Every other
* command pays one regex and one stat. `preBash` (the kept guardrails)
* only decides: it writes nothing, and only a well-formed answer reaches
* the host.
*/
import type * as Fs from 'node:fs';
import type * as Path from 'node:path';
import type * as Os from 'node:os';
import type * as Crypto from 'node:crypto';
/** What the hook can answer: Claude Code's PreToolUse permission decision and its reason. */
export interface PreBashDecision {
permissionDecision: 'allow' | 'ask' | 'deny';
reason: string;
}
const DECISIONS = new Set(['allow', 'ask', 'deny']);
/**
* The decision for one Bash call, or null to let it run untouched. Phase 0:
* always null. Never throws.
*/
export function preBash(_input: unknown, _dir: string): PreBashDecision | null {
return null;
}
/** trace/host.ts's Cursor and Antigravity keys, which it checks before Codex's (a test holds the two checks together). */
const NOT_CODEX_KEYS = ['conversation_id', 'generation_id', 'cursor_version', 'workspace_roots', 'conversationId', 'artifactDirectoryPath', 'workspacePaths'];
/**
* detectHost(input).host === 'codex', without loading trace/host.ts (the fast path loads nothing it needn't). Read
* only for a decision about to be sent.
*/
export function codexPayload(input: unknown): boolean {
try {
if (!input || typeof input !== 'object' || Array.isArray(input)) return false;
const p = input as Record<string, unknown>;
const has = (k: string) => Object.prototype.hasOwnProperty.call(p, k) && p[k] !== undefined && p[k] !== null;
const raw = has('transcript_path') ? p.transcript_path : p.transcriptPath;
const path = typeof raw === 'string' ? raw.replace(/\\/g, '/') : '';
const file = path.slice(path.lastIndexOf('/') + 1);
if (NOT_CODEX_KEYS.some(has) || path.includes('/.cursor/') || path.includes('/agent-transcripts/') || path.includes('/.gemini/antigravity')) return false;
return has('turn_id') || /^rollout-.*\.jsonl(\.zst)?$/.test(file) || path.includes('/.codex/sessions/');
} catch {
return false;
}
}
/**
* The hook's stdout for `input`: the decision in Claude Code's PreToolUse
* shape, or '' when there is none, `decide` throws, or what it returns isn't
* a decision the host understands.
*
* Codex (P37, P38): its hooks can't ask (an `ask` fails the hook run and the
* command runs, D17), so an ask goes out as a deny with the same reason; and
* an `allow` without `updatedInput` drops the hook's whole output there, so
* Trail never sends one. The deny is the whole output.
*/
export function preBashOutput(input: unknown, dir: string, decide: (input: unknown, dir: string) => PreBashDecision | null = preBash): string {
try {
const d = decide(input, dir);
if (!d || typeof d !== 'object' || !DECISIONS.has(d.permissionDecision) || typeof d.reason !== 'string' || !d.reason) return '';
let decision = d.permissionDecision;
if (decision !== 'deny' && codexPayload(input)) {
if (decision === 'allow') return '';
decision = 'deny';
}
return JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision, permissionDecisionReason: d.reason } });
} catch {
return '';
}
}
/** Shell tools by host: Claude Code's Bash (and PowerShell), Cursor's Shell, Copilot CLI's bash. */
const SHELL_TOOLS = new Set(['bash', 'shell', 'powershell']);
/**
* The command of a shell call, in Claude Code's and Cursor's shape
* (`tool_name`, `tool_input.command`) or Copilot CLI's (`toolName`,
* `toolArgs` as JSON text or an object), or null when the payload isn't a
* shell call. Copilot may run this hook for every tool whatever the matcher
* says, so the hook checks for itself.
*/
export function shellCommand(input: unknown): string | null {
try {
if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
const p = input as Record<string, unknown>;
const name = typeof p.tool_name === 'string' ? p.tool_name : typeof p.toolName === 'string' ? p.toolName : '';
if (!SHELL_TOOLS.has(name.toLowerCase())) return null;
let args: unknown = p.tool_input ?? p.toolArgs;
if (typeof args === 'string') args = JSON.parse(args);
const command = args && typeof args === 'object' ? (args as { command?: unknown }).command : undefined;
return typeof command === 'string' && command ? command : null;
} catch {
return null;
}
}
/** node:fs without an ESM import of it: Node 20.16 and later hand it over for free. */
async function nodeFs(): Promise<typeof Fs> {
return typeof process.getBuiltinModule === 'function' ? process.getBuiltinModule('node:fs') : await import('node:fs');
}
/** The longest the payload may take to arrive. Hosts write it at once and close stdin; this bounds one that doesn't, well inside the 5 s the hook is given. */
export const STDIN_WAIT_MS = 2000;
/** A payload over this is read to its end and dropped: no shell command worth checking is this long. */
export const STDIN_MAX_BYTES = 2 * 1024 * 1024;
/**
* stdin to its end, or null for a terminal (a person, not a host), an
* oversized payload or a read error. A read that is still waiting after
* STDIN_WAIT_MS sits in a thread Node joins before exiting, so no timer or
* exit() gets past it: the process ends outright instead, and the command's
* `|| exit 0` (settings-merge.ts failOpen) makes that a clean exit.
*/
function readStdin(fs: typeof Fs): Promise<string | null> {
try {
if (fs.fstatSync(0).isCharacterDevice()) return Promise.resolve(null);
} catch {
return Promise.resolve(null);
}
return new Promise((done) => {
const chunks: Buffer[] = [];
const buf = Buffer.alloc(64 * 1024);
let size = 0;
const timer = setTimeout(() => process.kill(process.pid, 'SIGKILL'), STDIN_WAIT_MS);
const finish = (text: string | null) => {
clearTimeout(timer);
done(text);
};
const next = (): void => {
fs.read(0, buf, 0, buf.length, null, (err, n) => {
const code = (err as NodeJS.ErrnoException | null)?.code;
if (code === 'EAGAIN') return void setTimeout(next, 5);
if (err && code !== 'EOF') return finish(null);
if (err || !n) return finish(size > STDIN_MAX_BYTES ? null : Buffer.concat(chunks).toString('utf8'));
size += n;
if (size <= STDIN_MAX_BYTES) chunks.push(Buffer.from(buf.subarray(0, n)));
else chunks.length = 0;
next();
});
};
next();
});
}
/** The hook payload on stdin as an object, or null for anything else. */
async function readInput(): Promise<Record<string, unknown> | null> {
try {
const seam = process.env.GRAFT_TEST_STDIN;
const text = seam !== undefined ? seam : await readStdin(await nodeFs());
if (text === null) return null;
const input: unknown = JSON.parse(text);
return input && typeof input === 'object' && !Array.isArray(input) ? (input as Record<string, unknown>) : null;
} catch {
return null;
}
}
/**
* `trail keep` waits for the person's answer (init/keep-gate.ts). Its check
* is loaded only for a command that says `keep`, so no other shell command
* pays for it, and only in the copy that answers: it writes the receipt.
*/
async function keepReply(input: Record<string, unknown>, dir: string, standsDown: () => Promise<boolean>): Promise<string> {
const command = shellCommand(input);
if (command === null || !/\bkeep\b/.test(command)) return '';
// 1b (R11): the check writes the keep receipt, so the copy that stands down does so before it runs (1a rule 15).
if (await standsDown()) return '';
const [{ keepDecision }, { isTestHome }] = await Promise.all([import('../init/keep-gate.js'), import('../skills/host-facts.js')]);
// b7: the receipt's time is Trail's clock (TRAIL_TEST_NOW in a test home only, 0 rule 10), the one `trail keep` reads it with.
const fixed = process.env.TRAIL_TEST_NOW ? new Date(process.env.TRAIL_TEST_NOW) : null;
const now = fixed && !Number.isNaN(fixed.getTime()) && isTestHome(process.env) ? fixed : new Date();
return preBashOutput(input, dir, (i, d) => keepDecision(i, d, process.env, now));
}
/**
* What the agent guard reads as a Trail hook script (risk.ts HOOK_SCRIPT), widened: a shim by name or glob, a
* path under `.claude/helpers/`, a `claude/<module>.js` of the package. Every command the guard denies passes this
* (a test holds them together). Bounded quantifiers only: the command can be 2 MB.
*/
const HOOK_SCRIPT = /(?:trail|graft)-hooks?|hooks?[*?[\]]{0,8}\.cjs|\.claude\/helpers\/|claude\/[\w-]{1,64}\.js/i;
/**
* 1b (3.3): `timeout` with a duration, for the sure-fail guardrail. Design 3.3's `\btimeout\s+(-\S+\s+)*\d`, widened
* so a signal name after `-s` (`timeout -s KILL 5m x`) reaches the guard too. Bounded: the command can be 2 MB.
*/
const TIMEOUT_RUN = /\btimeout\s+(?:-\S{1,40}\s+(?:[A-Za-z]{2,10}\s+)?){0,8}\d/;
/** gate-file.ts gateFilePath without loading it: the same file name for the same id (a test holds them equal). */
export function gateFilePathFast(input: Record<string, unknown>, env: NodeJS.ProcessEnv): string | null {
const raw = [input.session_id, input.sessionId, input.conversation_id].find((v): v is string => typeof v === 'string' && v !== '');
if (raw === undefined) return null;
const path = process.getBuiltinModule('node:path') as typeof Path;
const os = process.getBuiltinModule('node:os') as typeof Os;
const crypto = process.getBuiltinModule('node:crypto') as typeof Crypto;
const id = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}$/.test(raw) ? raw : `h-${crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16)}`;
const home = env.TRAIL_HOME ? path.resolve(env.TRAIL_HOME) : path.join(os.homedir(), '.trail');
return path.join(home, 'sessions', `${id}.gate.json`);
}
/**
* Design 1.7: whether the skills part has anything to look at, decided without loading it. The command
* (read as the agent guard reads it: quotes and backslashes don't change the words) says `skills` or names a
* Trail hook script, or this session has a gate file (a run block with a step that can't be undone is live).
* Every other shell command pays one regex and one stat.
*/
export function skillsPrefilter(input: Record<string, unknown>, command: string, env: NodeJS.ProcessEnv = process.env): boolean {
try {
const words = command.replace(/\\\n/g, '').replace(/["'\\]/g, '');
if (/\bskills\b/i.test(words) || HOOK_SCRIPT.test(words) || TIMEOUT_RUN.test(words)) return true;
const gate = typeof process.getBuiltinModule === 'function' ? gateFilePathFast(input, env) : null;
return gate !== null && (process.getBuiltinModule('node:fs') as typeof Fs).existsSync(gate);
} catch {
return false;
}
}
/** The shim's entry: `node trail-hooks.cjs pre-bash`. Never rejects. `decide` is preBash; tests pass their own. */
export async function main(event = 'pre-bash', decide: (input: unknown, dir: string) => PreBashDecision | null = preBash): Promise<void> {
try {
// trail's own headless Claude calls run with this set, like every hook.
if (process.env.TRAIL_NO_HOOKS === '1') return;
const input = await readInput();
const command = input ? shellCommand(input) : null;
if (!input || command === null) return;
const cwd = typeof input.cwd === 'string' ? input.cwd : '';
const dir = process.env.CLAUDE_PROJECT_DIR || cwd || process.cwd();
// Registered in the repo and in ~/.claude, Claude Code runs both: one
// answers. Copilot CLI runs only the repo's, so the payload decides first.
const standsDown = async () => (await import('./hook-layers.js')).globalCopyCovers(event, process.argv[1], undefined, undefined, input);
if (skillsPrefilter(input, command)) {
// The skills part writes (receipts, asked marks): only the copy that answers runs it.
if (await standsDown()) return;
const { preBashSkills } = await import('./pre-bash-skills.js');
const decision = await preBashSkills(input, dir, process.env, command);
const reply = preBashOutput(input, dir, () => decision);
if (reply) return void process.stdout.write(reply);
}
const reply = preBashOutput(input, dir, decide) || (await keepReply(input, cwd, standsDown));
if (!reply || (await standsDown())) return;
process.stdout.write(reply);
} catch {
// Never stand in the way of a command over our own failure.
}
}