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
/**
* Whether Codex trusts Trail's hook entries (design 4.17, HC8), read only, and
* the words Trail says about Codex (`CODEX_COPY`).
*
* Codex runs a non-managed hook only when `config.toml` holds a trust record
* for it whose hash matches the entry: `[hooks.state."<key>"]` with a
* `trusted_hash`, where the key is the hooks.json path, the event's label
* (`pre_tool_use`, ...), the group's index and the handler's index (the
* open-source Codex's `hook_key`; HC8 confirms it on the installed build). The
* person makes that record in Codex's `/hooks`. Trail never writes it, never
* passes a flag that skips it (rule 8), and never guesses: a form it doesn't
* know reads as `unknown`.
*
* `trusted` means every Trail entry has a trust record that is on; the hash in
* it is not recomputed here (Codex's own identity hash), so an entry changed
* since it was trusted would still read as trusted. Trail's entries are
* byte-stable from 0.26.0 on (P33), which is when that can happen once (D125).
*/
import { readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';
import { codexHome } from '../trace/codex.js';
import { CODEX_TIER } from '../trace/host.js';
import { hostTier } from '../skills/host-facts.js';
import type { HookOut } from '../skills/types.js';
/** The words Trail says about Codex. Each is checked by the words test. */
export const CODEX_COPY: Readonly<Record<'trust' | 'sandbox' | 'notTierA' | 'ephemeral', string>> = Object.freeze({
trust: "Codex runs Trail's hooks only after you trust them: in Codex, type /hooks and trust the Trail entries (graft-hooks.cjs).",
sandbox: 'Trail keeps skills in ~/.trail, outside this folder, so Codex may ask the person to let this command write there.',
notTierA: "Trail brings back your skills in Codex, but it doesn't offer to keep new ones there yet: its checks of Codex aren't done.",
ephemeral: "This Codex session isn't kept on disk, so Trail only brings back skills here and keeps nothing new from it.",
});
/** A `trail skills` command that writes to ~/.trail, which Codex runs inside its sandbox (4.17). */
const WRITES_TRAIL = /\btrail skills (?:add|lesson|update)\b/;
/**
* P36: on Codex, a directive or Stop reason that names a command writing to ~/.trail also says the sandbox may ask
* the person first, so a sandbox prompt or refusal is no surprise. Once, at the end; other hosts and other text as
* they are.
*/
export function withCodexSandbox(out: HookOut, host: string): HookOut {
if (host !== 'codex') return out;
const add = (t: string | undefined) => (t && WRITES_TRAIL.test(t) && !t.includes(CODEX_COPY.sandbox) ? `${t} ${CODEX_COPY.sandbox}` : t);
const next: HookOut = { ...out };
if (out.context !== undefined) next.context = add(out.context);
if (out.block !== undefined) next.block = add(out.block);
return next;
}
/** Codex's event names to the labels its trust keys use (`hook_event_key_label`). */
const LABELS: Readonly<Record<string, string>> = Object.freeze({
PreToolUse: 'pre_tool_use', PermissionRequest: 'permission_request', PostToolUse: 'post_tool_use', PreCompact: 'pre_compact',
PostCompact: 'post_compact', SessionStart: 'session_start', SessionEnd: 'session_end', UserPromptSubmit: 'user_prompt_submit',
SubagentStart: 'subagent_start', SubagentStop: 'subagent_stop', Stop: 'stop', Interrupt: 'interrupt',
});
const TRAIL_SHIM = /(?:graft|trail)-hooks\.cjs/;
const MAX_BYTES = 1024 * 1024;
function readSmall(path: string): string | null {
try {
const st = statSync(path);
if (!st.isFile() || st.size > MAX_BYTES) return null;
return readFileSync(path, 'utf8');
} catch {
return null;
}
}
/** The trust key of every Trail handler in CODEX_HOME/hooks.json, in file order; null when it can't be read. */
function keysOf(env: NodeJS.ProcessEnv): { path: string; keys: string[] } | null {
const path = join(codexHome(env), 'hooks.json');
const text = readSmall(path);
if (text === null) return null;
let root: unknown;
try {
root = JSON.parse(text);
} catch {
return null;
}
const hooks = root && typeof root === 'object' ? (root as { hooks?: unknown }).hooks : undefined;
if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return null;
const keys: string[] = [];
for (const [event, groups] of Object.entries(hooks as Record<string, unknown>)) {
const label = LABELS[event];
if (!label || !Array.isArray(groups)) continue;
groups.forEach((g, gi) => {
const handlers = g && typeof g === 'object' ? (g as { hooks?: unknown }).hooks : undefined;
if (!Array.isArray(handlers)) return;
handlers.forEach((h, hi) => {
const c = h && typeof h === 'object' ? (h as { command?: unknown }).command : undefined;
if (typeof c === 'string' && TRAIL_SHIM.test(c)) keys.push(`${path}:${label}:${gi}:${hi}`);
});
});
}
return { path, keys };
}
/** Trail's trust keys as Codex forms them for this CODEX_HOME (for the lab's HC8 and the tests). */
export function trailHookKeys(env: NodeJS.ProcessEnv = process.env): string[] {
return keysOf(env)?.keys ?? [];
}
/** A TOML basic or literal string at the start of `s`: its value and the rest, or null. */
function tomlString(s: string): { value: string; rest: string } | null {
if (s.startsWith("'")) {
const end = s.indexOf("'", 1);
return end < 0 ? null : { value: s.slice(1, end), rest: s.slice(end + 1) };
}
if (!s.startsWith('"')) return null;
let out = '';
for (let i = 1; i < s.length; i++) {
const ch = s[i]!;
if (ch === '"') return { value: out, rest: s.slice(i + 1) };
if (ch !== '\\') { out += ch; continue; }
const nx = s[++i];
if (nx === 'u' || nx === 'U') {
const n = nx === 'u' ? 4 : 8;
const hex = s.slice(i + 1, i + 1 + n);
if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length !== n) return null;
out += String.fromCodePoint(parseInt(hex, 16));
i += n;
continue;
}
const esc: Record<string, string> = { '"': '"', '\\': '\\', n: '\n', t: '\t', r: '\r', b: '\b', f: '\f' };
if (nx === undefined || !(nx in esc)) return null;
out += esc[nx];
}
return null;
}
interface Record_ { hash: string | null; enabled: boolean | null }
interface Parsed { records: Map<string, Record_>; unplaced: boolean }
/** `trusted_hash = "..."` and `enabled = true|false` in `body` (a table's lines or an inline table's inside). */
function fields(body: string, rec: Record_): boolean {
let ok = true;
for (const m of body.matchAll(/\b(trusted_hash|enabled)\s*=\s*([^,}\n]*)/g)) {
const v = m[2]!.trim();
if (m[1] === 'trusted_hash') {
const s = tomlString(v);
if (s) rec.hash = s.value;
else ok = false;
} else if (v === 'true' || v === 'false') rec.enabled = v === 'true';
else ok = false;
}
return ok;
}
/** The `[hooks.state]` records in config.toml, in both forms Codex's writer may use. */
function parseState(text: string): Parsed {
const records = new Map<string, Record_>();
let unplaced = false;
let current: Record_ | null = null;
let inState = false;
// A multi-line string's lines are its text, never tables or keys (a `[hooks.state...]` line in a prompt included).
let ml: string | null = null;
for (const raw of text.split(/\r?\n/)) {
if (ml) {
if (raw.includes(ml)) ml = null;
continue;
}
ml = ['"""', "'''"].find((q) => (raw.split(q).length - 1) % 2 === 1) ?? null;
const line = raw.trim();
if (!line || line.startsWith('#')) continue;
if (line.startsWith('[')) {
current = null;
inState = false;
const sub = /^\[\s*hooks\.state\.(.+)\]\s*(?:#.*)?$/.exec(line);
if (sub) {
const key = tomlString(sub[1]!.trim());
if (key && key.rest.trim() === '') {
current = records.get(key.value) ?? { hash: null, enabled: null };
records.set(key.value, current);
} else unplaced = true;
} else if (/^\[\s*hooks\.state\s*\]/.test(line)) inState = true;
continue;
}
if (current) {
if (!fields(line, current)) unplaced = true;
continue;
}
if (inState) {
const key = tomlString(line);
const inline = key ? /^\s*=\s*\{(.*)\}\s*(?:#.*)?$/.exec(key.rest) : null;
if (key && inline) {
const rec = records.get(key.value) ?? { hash: null, enabled: null };
records.set(key.value, rec);
if (!fields(inline[1]!, rec)) unplaced = true;
} else if (/trusted_hash|enabled/.test(line)) unplaced = true;
continue;
}
if (/trusted_hash/.test(line)) unplaced = true;
}
return { records, unplaced };
}
/** A key in the form Trail knows: `<path>:<label>:<group>:<handler>`. */
const KEY_FORM = new RegExp(`:(?:${Object.values(LABELS).join('|')}):\\d+:\\d+$`);
/**
* Whether Codex will run Trail's hook entries (HC8), from CODEX_HOME's hooks.json and config.toml, read only.
* `untrusted` lists the trust keys of Trail's entries with no record, no hash, or turned off.
*/
export function codexTrust(env: NodeJS.ProcessEnv = process.env): { state: 'trusted' | 'untrusted' | 'unknown'; untrusted: string[] } {
const unknown = { state: 'unknown' as const, untrusted: [] };
try {
const found = keysOf(env);
if (!found || !found.keys.length) return unknown;
const cfgPath = join(codexHome(env), 'config.toml');
let text = '';
try {
statSync(cfgPath);
const t = readSmall(cfgPath);
if (t === null) return unknown;
text = t;
} catch (e) {
if ((e as NodeJS.ErrnoException).code !== 'ENOENT') return unknown;
}
const parsed = parseState(text);
if (parsed.unplaced) return unknown;
const keys = [...parsed.records.keys()];
if (keys.some((k) => !KEY_FORM.test(k))) return unknown;
const untrusted = found.keys.filter((k) => {
const r = parsed.records.get(k);
return !r || !r.hash || r.enabled === false;
});
return { state: untrusted.length ? 'untrusted' : 'trusted', untrusted };
} catch {
return unknown;
}
}
/** For `trail init` and `trail status` (c8): the trust line, when Codex is here with Trail's entries and they aren't sure to be trusted. */
export function codexTrustLine(env: NodeJS.ProcessEnv = process.env): string | null {
if (!trailHookKeys(env).length) return null;
return codexTrust(env).state === 'trusted' ? null : CODEX_COPY.trust;
}
/**
* `trail status` (c8, D137): with Trail's Codex hooks in place, the trust line until each entry is trusted, and while
* Codex is tier B the line on why Trail only brings skills back there. Read only. The ephemeral line is a session's,
* said at that session's start, never here.
*/
export function codexStatusLines(env: NodeJS.ProcessEnv = process.env): string[] {
try {
if (!trailHookKeys(env).length) return [];
const trust = codexTrustLine(env);
return [...(trust ? [trust] : []), ...(hostTier('codex', CODEX_TIER, env) === 'A' ? [] : [CODEX_COPY.notTierA])];
} catch {
return [];
}
}