Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* codex-hooks.ts — the codex `hooks.json` writer (SessionEnd capture lane).
*
* SPEC TARGET (verified): codex-cli 0.147.0, observation run 2026-08-25
* (live captures + openai/codex source at tag rust-v0.147.0). The facts this
* writer is built on, none of them guesses:
*
* - File: $CODEX_HOME/hooks.json. TOP-LEVEL DENY-UNKNOWN-FIELDS: any extra
* top-level key makes codex skip the WHOLE file with only a stderr
* warning — so ownership rides the one legal metadata slot
* (`description`) plus a command-substring token, never a `_gbrain` key.
* - Schema: {description?, hooks: {SessionEnd: [{matcher?, hooks:
* [{type:'command', command:<shell string via $SHELL -lc>, timeout:<sec>,
* async?, …}]}]}} — PascalCase event names.
* - TRUST GATE (fail-closed, SILENT): a user-layer hook runs ONLY when
* $CODEX_HOME/config.toml carries
* [hooks.state."<abs hooks.json path>:session_end:<group>:<handler>"]
* trusted_hash = "sha256:" + sha256hex(compact canonical JSON, keys
* sorted recursively, of the normalized identity {event_name, matcher?,
* hooks:[{type, command, timeout, async, …}]}, None fields omitted).
* Without it the hook is listed and NEVER EXECUTED, with zero warnings in
* `codex exec` output. So this writer writes TWO files, and any command
* edit re-hashes.
* - SessionEnd handlers are hard-killed at 3s — the command captures stdin
* to a temp file and detaches a grandchild (`nohup … &`) that runs the
* real `gbrain hook session-end --harness codex`, so ingest time never
* races the kill.
* - Deliberately NO GBRAIN_SOURCE in the command [OV2]: hooks.json is
* user-global; a baked source would stamp every codex session on the
* machine with the last-bootstrapped repo. session-end resolves everything
* from the payload (cwd/transcript_path/session_id) at runtime — and it
* reads no GBRAIN_SOURCE at all, so the ambient-env tier [EV4] cannot
* misattribute this lane either.
* - Index sensitivity (documented residual): the trust key embeds our
* group's index in the SessionEnd array. A fresh install APPENDS last; a
* re-run REPLACES our group IN PLACE — so writing never shifts a FOREIGN
* group's index (append-after-strip would shift every foreign group that
* sat after ours, silently staling THEIR trust entries). If the user later
* reorders/removes their own groups, OUR entry can go stale — the hook
* then silently stops, which is exactly what doctor's
* codex-wired-but-zero-receipts rung exists to name. Uninstall does shift
* foreign groups after ours (array removal is inherently index-shifting);
* removeCodexHooks says so in its notes when that happens.
* - Version sensitivity: all of this is pinned to 0.147.0 with no upstream
* stability promise — re-run the observation gate on codex version bumps.
*/
import { createHash } from 'node:crypto';
import { chmodSync, copyFileSync, existsSync, readFileSync, statSync } from 'node:fs';
import { atomicWriteTextFile } from './atomic-write.ts';
import { ownedEntryFingerprint } from './adopted-connections.ts';
import { readCodexTomlTable } from './codex-toml.ts';
import type { HostSpecTarget } from './host-specs.ts';
import { CODEX_HOOK_EVENTS, codexConfigPath, codexHooksPath } from './host-specs.ts';
export const CODEX_HOOKS_SPEC_TARGET: HostSpecTarget = {
id: 'codex-hooks-2026-08',
status: 'verified',
verifiedAt: '2026-08-25',
references: [
'codex-cli 0.147.0 observation run 2026-08-25 (live SessionEnd payload + trust-gate captures)',
'openai/codex tag rust-v0.147.0: hooks/discovery.rs, hooks/fingerprint.rs, config_rules.rs',
],
note:
'hooks.json is top-level deny-unknown-fields (description is the one legal metadata slot); ' +
'user-layer hooks are trust-gated via [hooks.state."<path>:session_end:<g>:<h>"].trusted_hash ' +
'in config.toml (silent non-execution without it); SessionEnd budget 3s hard-kill; payload ' +
'{session_id, transcript_path, cwd, hook_event_name, reason:"other" always}; fires on normal/' +
'API-error exit + SIGINT, never SIGKILL; rollout flushed before the hook.',
};
/** Substring that marks a SessionEnd handler as gbrain-owned (the command
* string is the only marker surface deny-unknown-fields leaves us). */
export const CODEX_HOOK_OWNERSHIP_TOKEN = 'hook session-end --harness codex';
const GBRAIN_DESCRIPTION =
'gbrain session-end capture — the SessionEnd entry whose command mentions "gbrain" is managed by `gbrain bootstrap` (re-runs rewrite it; `gbrain bootstrap uninstall` deletes it)';
const TRUST_BLOCK_BEGIN = '# --- gbrain:codex-hooks-trust (managed block — do not edit; gbrain bootstrap rewrites it) ---';
const TRUST_BLOCK_END = '# --- /gbrain:codex-hooks-trust ---';
/** The hooks.json event key this lane manages — derived from host-specs so
* the declared event list and the writer can never drift apart. */
const SESSION_END_EVENT: string = CODEX_HOOK_EVENTS[0];
/** Strip the managed trust block (and trailing blank lines) out of a
* config.toml text — THE one implementation for write and remove, so a
* marker or CRLF-handling change can never half-propagate. */
function stripTrustBlock(text: string): { remainder: string[]; crlf: boolean; found: boolean } {
const crlf = text.includes('\r\n');
const lines = text.replace(/\r\n/g, '\n').split('\n');
const begin = lines.indexOf(TRUST_BLOCK_BEGIN);
const end = lines.indexOf(TRUST_BLOCK_END);
const found = begin >= 0 && end > begin;
const remainder = found ? [...lines.slice(0, begin), ...lines.slice(end + 1)] : [...lines];
while (remainder.length > 0 && remainder[remainder.length - 1]!.trim() === '') remainder.pop();
return { remainder, crlf, found };
}
/** SessionEnd is hard-clamped to 3s by codex; declare exactly that. */
const SESSION_END_TIMEOUT_SEC = 3;
function shellQuote(arg: string): string {
if (/^[A-Za-z0-9_.:/@=-]+$/.test(arg)) return arg;
return `'${arg.replace(/'/g, "'\\''")}'`;
}
/**
* The SessionEnd command: capture stdin, detach a grandchild, exit within the
* 3s budget. Codex hands this string to `$SHELL -lc`, and $SHELL can be a
* non-POSIX shell (fish, csh) where bare `var=value` assignments and `$( )`
* are syntax errors — so the TOP level is a single `sh -c '<script>' <bin>`
* invocation and only /bin/sh ever parses the POSIX script. The outer sh's
* $0 is the gbrain binary (no nested quoting of the path); the grandchild
* inherits GBRAIN_BIN/GBRAIN_PAYLOAD through the env-prefix assignments.
* With `launcher` (src/core/setup/hook-launcher.ts) the outer $0 is the
* launcher and $1 the binary, so the grandchild starts gbrain from the
* launcher's directory instead of the session's.
*/
export function buildCodexSessionEndCommand(gbrainBin: string, launcher?: string): string {
const script = launcher
? 't="$(mktemp)"; cat >"$t"; GBRAIN_PAYLOAD="$t" GBRAIN_HOOK_LAUNCHER="$0" GBRAIN_BIN="$1" nohup sh -c ' +
`'"$GBRAIN_HOOK_LAUNCHER" "$GBRAIN_BIN" ${CODEX_HOOK_OWNERSHIP_TOKEN} <"$GBRAIN_PAYLOAD"; rm -f "$GBRAIN_PAYLOAD"' >/dev/null 2>&1 &`
: 't="$(mktemp)"; cat >"$t"; GBRAIN_PAYLOAD="$t" GBRAIN_BIN="$0" nohup sh -c ' +
`'"$GBRAIN_BIN" ${CODEX_HOOK_OWNERSHIP_TOKEN} <"$GBRAIN_PAYLOAD"; rm -f "$GBRAIN_PAYLOAD"' >/dev/null 2>&1 &`;
// Embed the script into an outer single-quoted argument: ' → '\'' works
// identically in POSIX shells AND fish (escaped-quote outside quotes).
return `sh -c '${script.replace(/'/g, "'\\''")}' ${[...(launcher ? [launcher] : []), gbrainBin].map(shellQuote).join(' ')}`;
}
/** Compact JSON with recursively-sorted keys — codex's canonical form. */
function canonicalJson(v: unknown): string {
if (Array.isArray(v)) return `[${v.map(canonicalJson).join(',')}]`;
if (typeof v === 'object' && v !== null) {
const entries = Object.entries(v as Record<string, unknown>)
.filter(([, val]) => val !== undefined)
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
.map(([k, val]) => `${JSON.stringify(k)}:${canonicalJson(val)}`);
return `{${entries.join(',')}}`;
}
return JSON.stringify(v);
}
/**
* Codex's trust hash for one matcher-less command handler: `event_name` is the
* snake_case state label (`session_end`, `session_start`, `user_prompt_submit`),
* the timeout is the normalized one (re-checked against openai/codex
* rust-v0.162.1 `hooks/src/engine/discovery.rs` `hook_hash` +
* `config/src/fingerprint.rs` `version_for_toml`).
*/
export function codexHookTrustHash(eventName: string, command: string, timeout: number): string {
const identity = { event_name: eventName, hooks: [{ type: 'command', command, timeout, async: false }] };
return 'sha256:' + createHash('sha256').update(canonicalJson(identity), 'utf8').digest('hex');
}
/** The trust hash for OUR SessionEnd handler shape (matcher/None fields omitted). */
export function codexTrustHash(command: string): string {
return codexHookTrustHash('session_end', command, SESSION_END_TIMEOUT_SEC);
}
interface HooksJson {
description?: string;
hooks?: Record<string, Array<{ matcher?: unknown; hooks?: Array<{ type?: unknown; command?: unknown; [k: string]: unknown }> }>>;
[k: string]: unknown;
}
/** A bootstrap-lane group: carries the ownership token and is not a `gbrain setup` group (those are owned by hash). */
function isOurGroup(group: { hooks?: Array<{ command?: unknown }> }): boolean {
return (group.hooks ?? []).some((h) => typeof h.command === 'string' && h.command.includes(CODEX_HOOK_OWNERSHIP_TOKEN) && !h.command.includes(CODEX_SETUP_LANE_TOKEN));
}
export interface WriteCodexHooksResult {
ok: boolean;
hooksPath: string;
configPath: string;
trustKey?: string;
replacedPrior?: boolean;
reason?: 'hooks_json_unparseable' | 'foreign_trust_entry' | 'config_toml_unreadable';
notes: string[];
}
/**
* Write (or rewrite) gbrain's SessionEnd entry + its trust-state entry.
* Fail-closed: a hooks.json that exists but does not parse is NEVER touched
* (codex itself would skip it; overwriting could destroy the user's own
* hooks), and a foreign [hooks.state] entry for our exact key outside our
* managed block is a refusal, not an overwrite.
*/
export function writeCodexHooks(opts: {
gbrainBin: string;
/** The trusted-directory launcher the capture starts gbrain through (src/core/setup/hook-launcher.ts), never the session's directory (#8428). */
hookLauncher?: string;
hooksPath?: string;
configPath?: string;
}): WriteCodexHooksResult {
const hooksPath = opts.hooksPath ?? codexHooksPath();
const configPath = opts.configPath ?? codexConfigPath();
const notes: string[] = [];
// 1. hooks.json — parse (fail-closed), strip ours, append ours LAST.
let doc: HooksJson = {};
let existed = false;
if (existsSync(hooksPath)) {
existed = true;
try {
doc = JSON.parse(readFileSync(hooksPath, 'utf8')) as HooksJson;
if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) throw new Error('not an object');
} catch {
return { ok: false, hooksPath, configPath, reason: 'hooks_json_unparseable', notes: [`${hooksPath} exists but does not parse as a JSON object — fix or remove it (codex skips it too), then re-run.`] };
}
}
const hooks = (doc.hooks && typeof doc.hooks === 'object' && !Array.isArray(doc.hooks) ? doc.hooks : {}) as NonNullable<HooksJson['hooks']>;
const sessionEnd = Array.isArray(hooks[SESSION_END_EVENT]) ? hooks[SESSION_END_EVENT]! : [];
const command = buildCodexSessionEndCommand(opts.gbrainBin, opts.hookLauncher);
const ourGroup = { hooks: [{ type: 'command', command, timeout: SESSION_END_TIMEOUT_SEC }] };
// Fresh install appends LAST; a re-run replaces our group IN PLACE — a
// strip-then-append would shift every foreign group sitting after ours
// down one index, silently staling THEIR codex trust entries.
const priorIdx = sessionEnd.findIndex(isOurGroup);
const replacedPrior = priorIdx >= 0;
const withoutDupes = sessionEnd.filter((g, i) => i === priorIdx || !isOurGroup(g));
if (withoutDupes.length !== sessionEnd.length) {
notes.push(
`${sessionEnd.length - withoutDupes.length} duplicate gbrain SessionEnd group(s) dropped — foreign groups after them shift down; re-trust any of your own entries that stop firing.`,
);
}
const nextSessionEnd = replacedPrior ? withoutDupes.map((g, i) => (i === priorIdx ? ourGroup : g)) : [...withoutDupes, ourGroup];
const ourGroupIndex = replacedPrior ? priorIdx : nextSessionEnd.length - 1;
const nextDoc: HooksJson = {
...doc,
...(doc.description === undefined ? { description: GBRAIN_DESCRIPTION } : {}),
hooks: { ...hooks, [SESSION_END_EVENT]: nextSessionEnd },
};
// 2. config.toml trust entry — OUR entries live inside the managed marker
// block; everything outside survives byte-for-byte.
const trustKey = `${hooksPath}:session_end:${ourGroupIndex}:0`;
let configText = '';
if (existsSync(configPath)) {
try {
configText = readFileSync(configPath, 'utf8');
} catch {
return { ok: false, hooksPath, configPath, reason: 'config_toml_unreadable', notes: [`${configPath} exists but is unreadable — fix permissions and re-run.`] };
}
}
const { remainder, crlf } = stripTrustBlock(configText);
// Foreign-ownership guard: our table header outside our block would become
// a duplicate-table hard parse error that bricks codex entirely. TOLERANT
// match — any [hooks.state.…] header line mentioning our key, in either
// TOML string spelling and any interior whitespace, not just our exact
// JSON.stringify rendering.
const header = `[hooks.state.${JSON.stringify(trustKey)}]`;
const headerRe = /^\s*\[\s*hooks\s*\.\s*state\s*[.\]]/;
if (remainder.some((l) => headerRe.test(l) && l.includes(trustKey))) {
return {
ok: false, hooksPath, configPath, reason: 'foreign_trust_entry',
notes: [`${configPath} already defines a [hooks.state] entry for ${trustKey} outside the gbrain-managed block — refusing to double-define it (a hard TOML parse error). Remove that entry and re-run.`],
};
}
const block = [
TRUST_BLOCK_BEGIN,
`${header}`,
`trusted_hash = ${JSON.stringify(codexTrustHash(command))}`,
TRUST_BLOCK_END,
];
const nextConfig = [...(remainder.length ? [...remainder, ''] : []), ...block, ''].join('\n');
// 3. Write both, hooks.json first (a trust entry for a missing file is
// inert; a hooks file without trust is silently skipped — either partial
// state is safe, this order just minimizes the skipped window).
if (existed) {
copyFileSync(hooksPath, `${hooksPath}.bak`);
chmodSync(`${hooksPath}.bak`, 0o600);
}
atomicWriteTextFile(hooksPath, JSON.stringify(nextDoc, null, 2) + '\n', { freshMode: 0o600, forceMode: 0o600 });
if (configText) {
// DISTINCT suffix: config.toml.bak is the MCP block writer's rollback
// anchor (harness lane [X5] restores it on a failed smoke) — reusing it
// here would clobber that anchor and make the rollback restore THIS
// write's post-state instead of the pre-run config.
copyFileSync(configPath, `${configPath}.hooks.bak`);
chmodSync(`${configPath}.hooks.bak`, statSync(configPath).mode & 0o777);
}
atomicWriteTextFile(configPath, crlf ? nextConfig.replace(/\n/g, '\r\n') : nextConfig, { freshMode: 0o600 });
const foreignCount = nextSessionEnd.length - 1;
if (foreignCount > 0) {
notes.push(
`${foreignCount} foreign SessionEnd group(s) preserved at their original indexes (${replacedPrior ? "gbrain's entry replaced in place" : "gbrain's entry appended last"}) so their trust-state entries never go stale.`,
);
}
return { ok: true, hooksPath, configPath, trustKey, replacedPrior, notes };
}
export interface RemoveCodexHooksResult {
hooksPath: string;
configPath: string;
removed: boolean;
notes: string[];
}
/** Strip gbrain's SessionEnd entry + managed trust block. Foreign content
* survives byte-for-byte; an unparseable hooks.json is left untouched. */
export function removeCodexHooks(opts: { hooksPath?: string; configPath?: string } = {}): RemoveCodexHooksResult {
const hooksPath = opts.hooksPath ?? codexHooksPath();
const configPath = opts.configPath ?? codexConfigPath();
const notes: string[] = [];
let removed = false;
if (existsSync(hooksPath)) {
try {
const doc = JSON.parse(readFileSync(hooksPath, 'utf8')) as HooksJson;
const hooks = (doc.hooks ?? {}) as NonNullable<HooksJson['hooks']>;
const sessionEnd = Array.isArray(hooks[SESSION_END_EVENT]) ? hooks[SESSION_END_EVENT]! : [];
const ourIdx = sessionEnd.findIndex(isOurGroup);
const foreign = sessionEnd.filter((g) => !isOurGroup(g));
let changed = false;
if (foreign.length !== sessionEnd.length) {
changed = true;
if (foreign.length > 0) hooks[SESSION_END_EVENT] = foreign;
else delete hooks[SESSION_END_EVENT];
// Removal is inherently index-shifting for anything AFTER ours — the
// user's own trust entries for those groups go stale (silent
// non-execution). Say so instead of leaving them to find out.
if (ourIdx >= 0 && ourIdx < sessionEnd.length - 1) {
notes.push(
`${sessionEnd.length - 1 - ourIdx} of your own SessionEnd group(s) sat after gbrain's — their index just shifted down, so codex will treat their config.toml trust entries as stale. Re-trust them (codex prompts on next run) or update the [hooks.state] indexes.`,
);
}
}
// Same only-if-we-wrote-it discipline as the writer: the description is
// deleted only when it is byte-identical to ours.
if (doc.description === GBRAIN_DESCRIPTION) {
delete doc.description;
changed = true;
}
if (changed) {
removed = true;
atomicWriteTextFile(hooksPath, JSON.stringify({ ...doc, hooks }, null, 2) + '\n', { freshMode: 0o600, forceMode: 0o600 });
}
} catch {
notes.push(`${hooksPath} does not parse — left untouched (nothing gbrain wrote survives a hand-mangled file; remove it manually).`);
}
}
if (existsSync(configPath)) {
const raw = readFileSync(configPath, 'utf8');
const { remainder, crlf, found } = stripTrustBlock(raw);
if (found) {
removed = true;
const next = remainder.length ? remainder.join('\n') + '\n' : '';
atomicWriteTextFile(configPath, crlf ? next.replace(/\n/g, '\r\n') : next, { forceMode: statSync(configPath).mode & 0o777 });
}
}
return { hooksPath, configPath, removed, notes };
}
// ── `gbrain setup codex` lane: owned by exact hash, never by token ──────────
//
// Setup's groups carry `GBRAIN_HOOK_LANE=setup` so the bootstrap lane above
// (token-owned) never claims or strips them; setup itself recognizes its
// groups only by the sha256 fingerprint its connection receipt recorded
// (src/core/setup/codex.ts), so an edited group is preserved, never removed.
export const CODEX_SETUP_LANE_TOKEN = 'GBRAIN_HOOK_LANE=setup';
const TURN_RULE_LANE_TOKEN = 'GBRAIN_HOOK_LANE=turn-rule';
const SKILL_RESOLVER_LANE_TOKEN = 'GBRAIN_HOOK_LANE=skill-resolver';
export const CODEX_SETUP_EVENTS = ['SessionStart', 'UserPromptSubmit', 'SessionEnd'] as const;
export type CodexSetupEvent = (typeof CODEX_SETUP_EVENTS)[number];
/** State label, normalized timeout and `gbrain hook` subcommand per event. The
* context events run synchronously within 15s (above session-start's own
* deadline); SessionEnd keeps the detached 3s capture command. */
const SETUP_EVENT_SPECS: Record<CodexSetupEvent, { stateName: string; timeout: number; subcommand: string }> = {
SessionStart: { stateName: 'session_start', timeout: 15, subcommand: 'session-start' },
UserPromptSubmit: { stateName: 'user_prompt_submit', timeout: 15, subcommand: 'user-prompt' },
SessionEnd: { stateName: 'session_end', timeout: SESSION_END_TIMEOUT_SEC, subcommand: 'session-end' },
};
export interface CodexHookGroup { hooks: Array<{ type: 'command'; command: string; timeout: number }> }
/** Setup's group for one event (or the turn-rule lane's, src/core/setup/turn-hook.ts). `env` is POSIX `env` (any $SHELL parses it); the values pin this install. `launcher`: the trusted-directory hook launcher gbrain starts through (src/core/setup/hook-launcher.ts). */
export function codexSetupHookGroup(gbrainBin: string, event: CodexSetupEvent, env: { GBRAIN_HOME?: string; GBRAIN_SOURCE?: string }, lane = 'setup', launcher?: string): CodexHookGroup {
const assignments = [`GBRAIN_HOOK_LANE=${lane}`, ...(env.GBRAIN_HOME ? [`GBRAIN_HOME=${env.GBRAIN_HOME}`] : []), ...(env.GBRAIN_SOURCE ? [`GBRAIN_SOURCE=${env.GBRAIN_SOURCE}`] : [])];
const spec = SETUP_EVENT_SPECS[event];
const command = event === 'SessionEnd'
? ['env', ...assignments].map(shellQuote).join(' ') + ' ' + buildCodexSessionEndCommand(gbrainBin, launcher)
: ['env', ...assignments, ...(launcher ? [launcher] : []), gbrainBin, 'hook', spec.subcommand, '--harness', 'codex'].map(shellQuote).join(' ');
return { hooks: [{ type: 'command', command, timeout: spec.timeout }] };
}
/** The `[hooks.state."<key>"]` entry that trusts `group` at `index` of `event` in `hooksPath`. */
export function codexSetupTrustEntry(hooksPath: string, event: CodexSetupEvent, index: number, group: CodexHookGroup): { key: string; trusted_hash: string } {
const { stateName } = SETUP_EVENT_SPECS[event];
const handler = group.hooks[0]!;
return { key: `${hooksPath}:${stateName}:${index}:0`, trusted_hash: codexHookTrustHash(stateName, handler.command, handler.timeout) };
}
export interface CodexHookCensusGroup { event: string; index: number; hash: string; lane: 'setup' | 'bootstrap' | 'turn-rule' | 'other'; commands: string[] }
function loadHooksJson(hooksPath: string): { doc: HooksJson; hooks: NonNullable<HooksJson['hooks']> } {
if (!existsSync(hooksPath)) return { doc: {}, hooks: {} };
const text = readFileSync(hooksPath, 'utf8');
if (text.trim() === '') return { doc: {}, hooks: {} };
let doc: HooksJson;
try {
doc = JSON.parse(text) as HooksJson;
if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) throw new Error('not an object');
} catch {
throw new Error(`${hooksPath} does not parse as a JSON object; setup never rewrites a file it cannot parse (codex skips it too). Fix it by hand, then run setup again.`);
}
if (doc.hooks !== undefined && (typeof doc.hooks !== 'object' || doc.hooks === null || Array.isArray(doc.hooks))) {
throw new Error(`${hooksPath} has a "hooks" key that is not an object; setup leaves it untouched.`);
}
return { doc, hooks: (doc.hooks ?? {}) as NonNullable<HooksJson['hooks']> };
}
const CONTEXT_LANE_TOKENS = ['hook session-start --harness codex', 'hook user-prompt --harness codex', CODEX_HOOK_OWNERSHIP_TOKEN];
/** Every matcher group under setup's events, fingerprinted. Throws on an unparseable file. */
export function codexHookCensus(hooksPath: string): CodexHookCensusGroup[] {
const { hooks } = loadHooksJson(hooksPath);
const out: CodexHookCensusGroup[] = [];
for (const event of CODEX_SETUP_EVENTS) {
const groups = hooks[event];
if (!Array.isArray(groups)) continue;
groups.forEach((group, index) => {
const commands = (Array.isArray(group?.hooks) ? group.hooks : []).map((h) => h?.command).filter((c): c is string => typeof c === 'string');
// The skill-resolver lane (setup/skill-resolver-lane.ts) wires UserPromptSubmit with the context command shape but adds only its skills block: never a context lane.
const lane = commands.some((c) => c.includes(SKILL_RESOLVER_LANE_TOKEN)) ? 'other'
: commands.some((c) => c.includes(CODEX_SETUP_LANE_TOKEN)) ? 'setup'
: commands.some((c) => c.includes(TURN_RULE_LANE_TOKEN)) ? 'turn-rule'
: commands.some((c) => CONTEXT_LANE_TOKENS.some((t) => c.includes(t))) ? 'bootstrap' : 'other';
out.push({ event, index, hash: ownedEntryFingerprint(group), lane, commands });
});
}
return out;
}
/**
* Whether Codex runs gbrain's handler in group `index` of a context event
* (SessionStart, UserPromptSubmit): its `[hooks.state."<hooksPath>:<state>:
* <index>:<handler>"]` entry in `configPath` is not `enabled = false` and its
* `trusted_hash` equals the hash of the handler as written (gbrain's shape: no
* matcher, not async, an unset timeout normalized to 600). Codex never runs an
* untrusted or disabled user-layer hook. Throws on an unparseable file.
*/
export function codexHookGroupRuns(hooksPath: string, configPath: string, group: { event: string; index: number }): boolean {
if (group.event !== 'SessionStart' && group.event !== 'UserPromptSubmit') return false;
const { stateName } = SETUP_EVENT_SPECS[group.event];
const handlers = loadHooksJson(hooksPath).hooks[group.event]?.[group.index]?.hooks;
if (!Array.isArray(handlers)) return false;
const states = readCodexTomlTable(configPath, ['hooks', 'state']) as Record<string, { enabled?: unknown; trusted_hash?: unknown } | undefined> | undefined;
return handlers.some((h, i) => {
const command = h?.command;
if (typeof command !== 'string' || !(command.includes(CODEX_SETUP_LANE_TOKEN) || CONTEXT_LANE_TOKENS.some((t) => command.includes(t)))) return false;
const state = states?.[`${hooksPath}:${stateName}:${group.index}:${i}`];
if (!state || state.enabled === false) return false;
return state.trusted_hash === codexHookTrustHash(stateName, command, typeof h.timeout === 'number' ? Math.max(1, h.timeout) : 600);
});
}
/**
* Converge setup's groups in hooks.json: for each event, a group whose
* fingerprint is in `owned` (or equals the wanted one) is replaced IN PLACE by
* the wanted group (extra owned copies dropped), else the wanted group is
* appended; an unwanted event loses only its owned groups. Events in
* `preserve` (edited by the user) get no write. Foreign and edited groups are
* never touched. Returns each wanted group's final index (the trust key).
*/
export function writeCodexSetupHooks(hooksPath: string, opts: {
want: Partial<Record<CodexSetupEvent, CodexHookGroup>>;
owned: ReadonlySet<string>;
preserve: ReadonlySet<string>;
dryRun?: boolean;
}): { changed: boolean; indexes: Partial<Record<CodexSetupEvent, number>>; notes: string[] } {
const { doc, hooks } = loadHooksJson(hooksPath);
const notes: string[] = [];
const indexes: Partial<Record<CodexSetupEvent, number>> = {};
const nextHooks: NonNullable<HooksJson['hooks']> = { ...hooks };
let changed = false;
for (const event of CODEX_SETUP_EVENTS) {
const groups = Array.isArray(hooks[event]) ? hooks[event]! : [];
const wanted = opts.preserve.has(event) ? undefined : opts.want[event];
const wantedHash = wanted ? ownedEntryFingerprint(wanted) : null;
const ours = groups.flatMap((g, i) => {
const h = ownedEntryFingerprint(g);
return opts.owned.has(h) || h === wantedHash ? [i] : [];
});
let next: typeof groups;
if (wanted) {
const first = ours[0];
next = first === undefined ? [...groups, wanted] : groups.flatMap<(typeof groups)[number]>((g, i) => (i === first ? [wanted] : ours.includes(i) ? [] : [g]));
indexes[event] = first ?? next.length - 1;
if (first !== undefined && ownedEntryFingerprint(groups[first]) === wantedHash && ours.length === 1) continue;
} else {
if (ours.length === 0) continue;
next = groups.filter((_, i) => !ours.includes(i));
}
const lastDropped = Math.max(-1, ...ours.filter((i) => !(wanted && i === ours[0])));
if (lastDropped >= 0 && lastDropped < groups.length - 1) {
notes.push(`${event}: removing setup's group shifted the ${groups.length - 1 - lastDropped} group(s) after it down one index, so codex treats their trust entries as stale; re-trust them in codex (/hooks) if they stop firing.`);
}
changed = true;
if (next.length > 0) nextHooks[event] = next;
else delete nextHooks[event];
}
if (changed && !opts.dryRun) atomicWriteTextFile(hooksPath, `${JSON.stringify({ ...doc, hooks: nextHooks }, null, 2)}\n`, { freshMode: 0o600 });
return { changed, indexes, notes };
}