Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.6 KB
Raw Blame
/**
 * turn-hook.ts — the per-turn brain-first rule on install paths that do not
 * run `gbrain setup`'s own hooks: `gbrain connect --install` (a remote brain),
 * `gbrain connect --harness … --install` (a hosted grant),
 * `gbrain bootstrap harness` (Codex, and Claude Code when its own hooks are off) and
 * `gbrain setup <claude-code|codex> --instructions-only` (a bare `mcp add`
 * registration gbrain did not write).
 *
 * Why: harness evals found the brain is used when "check gbrain first" reaches
 * the model on every turn (a per-turn hook: 80 of 80) and almost never when it
 * rides only the MCP tool list (2 of 99) or a startup file (0 of 80).
 *
 * The hook is one UserPromptSubmit entry running
 * `env GBRAIN_HOOK_LANE=turn-rule <launcher> <gbrain> hook user-prompt`, where
 * <launcher> starts gbrain from its own directory so the session directory's
 * bunfig.toml and .env never load (#8424, hook-launcher.ts). In that lane the
 * hook adds only the rule (read from the brain-first ledger, so an opt-out or
 * GBRAIN_AGENT_INSTRUCTIONS=0 silences it) and never reads local context: the
 * connection may point at another brain. It yields when another gbrain lane
 * (setup, bootstrap) wires the same event, so a turn gets the rule once; a
 * gbrain plugin yields to it the same way.
 *
 * Ownership: Claude Code entries carry the `turn-rule-v1` marker, and the
 * command (lane token + `hook user-prompt`) identifies them when Claude Code
 * dropped the marker on a rewrite. Codex groups are identified by the lane
 * token; the trust entry Codex requires is written beside the group and owned
 * by its hash. Nothing else in either file is touched.
 *
 * `inspectTurnHook` (doctor) and `verifyTurnHook` (install time) answer
 * whether a per-turn hook is wired and loads, naming the harness's own
 * inspect command when it does not.
 */
import { existsSync, mkdirSync, readFileSync } from 'node:fs';
import { dirname, join, win32 } from 'node:path';
import { bunSpawnSync } from '../spawn.ts';
import { ownedEntryFingerprint } from '../bootstrap/adopted-connections.ts';
import { codexHookCensus, codexHookGroupRuns, codexHookTrustHash, codexSetupHookGroup, codexSetupTrustEntry, writeCodexSetupHooks, type CodexHookGroup } from '../bootstrap/codex-hooks.ts';
import { appendCodexTomlTable, readCodexTomlTable, removeCodexTomlTable } from '../bootstrap/codex-toml.ts';
import { buildClaudeHookCommand, classifyHarnessHook, hookEntryHash, removeClaudeHooksAt, writeClaudeHooksAt } from '../bootstrap/hooks.ts';
import { CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS, GBRAIN_HOOK_MARKER_KEY, claudeManagedSettingsPaths, claudeUserSettingsPath, codexConfigPath, codexHooksPath } from '../bootstrap/host-specs.ts';
import { ensureHookLauncher, hookLauncherPath, hookLauncherState, hookShellPath } from './hook-launcher.ts';
import { isSkillResolverEntry } from './skill-resolver-lane.ts';

export const TURN_RULE_LANE = 'turn-rule';
export const TURN_RULE_MARKER = 'turn-rule-v1';
export const TURN_RULE_LANE_TOKEN = 'GBRAIN_HOOK_LANE=turn-rule';
const EVENT = 'UserPromptSubmit';
const TRUST_STATE = 'user_prompt_submit';

export type TurnRuleHarness = 'claude-code' | 'codex';
export function isTurnRuleHarness(h: string): h is TurnRuleHarness { return h === 'claude-code' || h === 'codex'; }

export interface TurnHookPaths {
  /** Claude Code settings.json (default: the user settings file). */
  claudeSettings?: string;
  /** Codex hooks.json and config.toml (default: CODEX_HOME's). */
  codexHooks?: string;
  codexConfig?: string;
  /** The trusted-directory hook launcher (default: this install's, hook-launcher.ts). */
  hookLauncher?: string;
}

export interface TurnHookOutcome {
  harness: string;
  action: 'write' | 'keep' | 'remove' | 'skip' | 'print';
  path: string;
  detail: string;
  /** For `print`: the one command that wires it. */
  next?: string;
}

const claudePath = (p: TurnHookPaths) => p.claudeSettings ?? claudeUserSettingsPath();
const codexPaths = (p: TurnHookPaths) => ({ hooks: p.codexHooks ?? codexHooksPath(), config: p.codexConfig ?? codexConfigPath() });

export function claudeTurnRuleCommand(gbrainBin: string, gbrainHome: string | undefined, launcher: string): string {
  return buildClaudeHookCommand(hookShellPath(gbrainBin), EVENT, { ...(gbrainHome ? { GBRAIN_HOME: gbrainHome } : {}), GBRAIN_HOOK_LANE: TURN_RULE_LANE }, hookShellPath(launcher));
}

export function codexTurnRuleGroup(gbrainBin: string, gbrainHome: string | undefined, launcher: string): CodexHookGroup {
  return codexSetupHookGroup(gbrainBin, EVENT, gbrainHome ? { GBRAIN_HOME: gbrainHome } : {}, TURN_RULE_LANE, launcher);
}

/** A Claude Code hook entry that is this lane's: marked, or (marker dropped) its command shape. */
export function isTurnRuleEntry(entry: unknown): boolean {
  if (!entry || typeof entry !== 'object') return false;
  const e = entry as Record<string, unknown>;
  if (e[GBRAIN_HOOK_MARKER_KEY] === TURN_RULE_MARKER) return true;
  return !Object.prototype.hasOwnProperty.call(e, GBRAIN_HOOK_MARKER_KEY) && typeof e.command === 'string'
    && e.command.includes(TURN_RULE_LANE_TOKEN) && /\shook user-prompt(?:\s|$)/.test(e.command);
}

function readJson(path: string): Record<string, unknown> | null {
  if (!existsSync(path)) return null;
  try {
    const v = JSON.parse(readFileSync(path, 'utf8')) as unknown;
    return v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : null;
  } catch { return null; }
}

/** Every command entry under UserPromptSubmit in a Claude Code settings file. */
function claudePromptEntries(path: string): Array<Record<string, unknown>> {
  const groups = (readJson(path)?.hooks as Record<string, unknown> | undefined)?.[EVENT];
  if (!Array.isArray(groups)) return [];
  return groups.flatMap((g) => (Array.isArray((g as { hooks?: unknown })?.hooks) ? (g as { hooks: unknown[] }).hooks : []))
    .filter((e): e is Record<string, unknown> => !!e && typeof e === 'object');
}

/** An entry another gbrain lane owns (setup, workspace bootstrap, bootstrap harness). A repo's committed settings.json counts only a command that parses as gbrain's hook, never a bare marker. */
export function isOtherGbrainEntry(e: Record<string, unknown>, committed = false): boolean {
  if (isTurnRuleEntry(e) || isSkillResolverEntry(e)) return false;
  return (!committed && typeof e[GBRAIN_HOOK_MARKER_KEY] === 'string') || !!classifyHarnessHook(e, EVENT, 'any');
}

/**
 * Runtime dedupe for the turn-rule lane: another gbrain lane already wires
 * UserPromptSubmit for this harness, and that hook adds the same rule.
 * Fail-open (an unreadable file counts as not wired).
 */
export function turnRuleHookYields(harness: string, cwd: string, managedDir?: string): boolean {
  if (harness === 'codex') {
    // Only a group Codex actually runs (trusted, enabled) carries the rule.
    try { return codexHookCensus(codexHooksPath()).some((g) => g.event === EVENT && (g.lane === 'setup' || g.lane === 'bootstrap') && codexHookGroupRuns(codexHooksPath(), codexConfigPath(), g)); } catch { return false; }
  }
  return claudePromptEntries(claudeUserSettingsPath()).some((e) => isOtherGbrainEntry(e))
    || claudePromptEntries(join(cwd, '.claude', 'settings.local.json')).some((e) => isOtherGbrainEntry(e))
    || claudePromptEntries(join(cwd, '.claude', 'settings.json')).some((e) => isOtherGbrainEntry(e, true))
    || claudeManagedSettingsPaths(managedDir).some((path) => claudePromptEntries(path).some((e) => isOtherGbrainEntry(e)));
}

/** Install or refresh the turn-rule hook. Never throws; anything it cannot write safely comes back as `print` with the command that wires it. */
export function syncTurnRuleHook(opts: { harness: TurnRuleHarness; gbrainBin: string | null; gbrainHome?: string; paths?: TurnHookPaths; dryRun?: boolean; rerun: string }): TurnHookOutcome {
  const paths = opts.paths ?? {};
  const where = opts.harness === 'codex' ? codexPaths(paths).hooks : claudePath(paths);
  const print = (why: string): TurnHookOutcome => ({ harness: opts.harness, action: 'print', path: where, detail: `per-turn rule hook not installed: ${why}`, next: opts.rerun });
  if (!opts.gbrainBin || !(opts.gbrainBin.startsWith('/') || win32.isAbsolute(opts.gbrainBin))) return print('no absolute gbrain binary was found (harnesses inherit no PATH); install gbrain globally or pass --gbrain-bin');
  if (opts.harness === 'codex' && !opts.gbrainBin.startsWith('/')) return print('Codex runs hook commands on Windows without a POSIX shell, so it cannot run gbrain\'s hook launcher');
  try {
    const launcher = paths.hookLauncher ?? hookLauncherPath();
    // The launcher goes down first: a hook that names it must find it.
    const launcherFresh = hookLauncherState(launcher).state === 'current';
    if (!opts.dryRun) ensureHookLauncher(launcher);
    const outcome = opts.harness === 'codex' ? syncCodex(opts.gbrainBin, opts.gbrainHome, launcher, codexPaths(paths), !!opts.dryRun, print)
      : syncClaude(opts.gbrainBin, opts.gbrainHome, launcher, claudePath(paths), !!opts.dryRun);
    return outcome.action === 'keep' && !launcherFresh ? { ...outcome, action: 'write', detail: `${outcome.detail}; hook launcher ${launcher}` } : outcome;
  } catch (e) {
    return print((e as Error).message);
  }
}

function syncClaude(bin: string, home: string | undefined, launcher: string, path: string, dryRun: boolean): TurnHookOutcome {
  const command = claudeTurnRuleCommand(bin, home, launcher);
  const want = { type: 'command', command, timeout: CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS[EVENT] };
  const wantHash = hookEntryHash(want)!;
  const ours = claudePromptEntries(path).filter(isTurnRuleEntry);
  const detail = `per-turn rule hook (UserPromptSubmit) in ${path}`;
  if (ours.length === 1 && hookEntryHash(ours[0]) === wantHash) return { harness: 'claude-code', action: 'keep', path, detail };
  if (dryRun) return { harness: 'claude-code', action: 'write', path, detail };
  mkdirSync(dirname(path), { recursive: true });
  const owned = new Set([wantHash, ...ours.map((e) => hookEntryHash(e)).filter((h): h is string => !!h)]);
  writeClaudeHooksAt(path, { gbrainBin: hookShellPath(bin), hookLauncher: hookShellPath(launcher), env: { ...(home ? { GBRAIN_HOME: home } : {}), GBRAIN_HOOK_LANE: TURN_RULE_LANE, GBRAIN_SEAT: '' },
    events: [EVENT], marker: TURN_RULE_MARKER, ownedEntryHashes: owned, freshMode: 0o600 });
  return { harness: 'claude-code', action: 'write', path, detail };
}

const trustPath = (key: string) => ['hooks', 'state', key];
const trustKey = (hooksPath: string, index: number) => `${hooksPath}:${TRUST_STATE}:${index}:0`;

/** Our groups in hooks.json with the trust table Codex would read for each. */
function codexOurs(paths: { hooks: string; config: string }) {
  return codexHookCensus(paths.hooks).filter((g) => g.event === EVENT && g.lane === 'turn-rule');
}

/** Remove the trust table at `key` only when it trusts exactly one of our commands. */
function dropOurTrust(config: string, key: string, commands: string[]): void {
  const table = readCodexTomlTable(config, trustPath(key)) as { trusted_hash?: unknown } | undefined;
  if (!table || !commands.some((c) => codexHookTrustHash(TRUST_STATE, c, 15) === table.trusted_hash)) return;
  removeCodexTomlTable(config, trustPath(key));
}

function syncCodex(bin: string, home: string | undefined, launcher: string, paths: { hooks: string; config: string }, dryRun: boolean, print: (why: string) => TurnHookOutcome): TurnHookOutcome {
  const group = codexTurnRuleGroup(bin, home, launcher);
  const hash = ownedEntryFingerprint(group);
  const ours = codexOurs(paths);
  const detail = `per-turn rule hook (UserPromptSubmit) in ${paths.hooks}, trusted in ${paths.config}`;
  const current = ours.length === 1 && ours[0]!.hash === hash;
  const { key, trusted_hash } = codexSetupTrustEntry(paths.hooks, EVENT, current ? ours[0]!.index : 0, group);
  const trusted = current && (readCodexTomlTable(paths.config, trustPath(key)) as { trusted_hash?: unknown } | undefined)?.trusted_hash === trusted_hash;
  if (current && trusted) return { harness: 'codex', action: 'keep', path: paths.hooks, detail };
  if (dryRun) return { harness: 'codex', action: 'write', path: paths.hooks, detail };
  mkdirSync(dirname(paths.hooks), { recursive: true, mode: 0o700 });
  const commands = ours.flatMap((g) => g.commands);
  for (const g of ours) dropOurTrust(paths.config, trustKey(paths.hooks, g.index), commands);
  const w = writeCodexSetupHooks(paths.hooks, { want: { [EVENT]: group }, owned: new Set(ours.map((g) => g.hash)), preserve: new Set() });
  const index = w.indexes[EVENT];
  if (index === undefined) return print(`${paths.hooks} did not take the hook`);
  const entry = codexSetupTrustEntry(paths.hooks, EVENT, index, group);
  const existing = readCodexTomlTable(paths.config, trustPath(entry.key)) as { trusted_hash?: unknown } | undefined;
  if (existing === undefined) appendCodexTomlTable(paths.config, trustPath(entry.key), { trusted_hash: entry.trusted_hash }, 'gbrain setup (turn-rule): trusts the per-turn brain-first rule hook; owned by its hash');
  else if (existing.trusted_hash !== entry.trusted_hash) return print(`${paths.config} already has a different [hooks.state."${entry.key}"]; trust gbrain's UserPromptSubmit hook in Codex's /hooks`);
  return { harness: 'codex', action: 'write', path: paths.hooks, detail };
}

/** This lane's own entry is present (Claude Code settings file, or Codex hooks.json); false for an unreadable file. */
export function hasTurnRuleHook(harness: TurnRuleHarness, paths: TurnHookPaths = {}): boolean {
  try { return harness === 'codex' ? codexOurs(codexPaths(paths)).length > 0 : claudePromptEntries(claudePath(paths)).some(isTurnRuleEntry); } catch { return false; }
}

/** Remove the turn-rule hook (opt-out or uninstall). Never throws. */
export function removeTurnRuleHook(opts: { harness: TurnRuleHarness; paths?: TurnHookPaths; dryRun?: boolean }): TurnHookOutcome {
  const paths = opts.paths ?? {};
  try {
    if (opts.harness === 'codex') {
      const p = codexPaths(paths);
      const ours = codexOurs(p);
      if (ours.length === 0) return { harness: 'codex', action: 'skip', path: p.hooks, detail: `no per-turn rule hook in ${p.hooks}` };
      if (!opts.dryRun) {
        const commands = ours.flatMap((g) => g.commands);
        for (const g of ours) dropOurTrust(p.config, trustKey(p.hooks, g.index), commands);
        const w = writeCodexSetupHooks(p.hooks, { want: {}, owned: new Set(ours.map((g) => g.hash)), preserve: new Set() });
        if (w.notes.length) return { harness: 'codex', action: 'remove', path: p.hooks, detail: `per-turn rule hook removed from ${p.hooks}; ${w.notes.join(' ')}` };
      }
      return { harness: 'codex', action: 'remove', path: p.hooks, detail: `per-turn rule hook removed from ${p.hooks}` };
    }
    const path = claudePath(paths);
    const ours = claudePromptEntries(path).filter(isTurnRuleEntry);
    if (ours.length === 0) return { harness: 'claude-code', action: 'skip', path, detail: `no per-turn rule hook in ${path}` };
    if (!opts.dryRun) removeClaudeHooksAt(path, TURN_RULE_MARKER, { ownedEntryHashes: new Set(ours.map((e) => hookEntryHash(e)).filter((h): h is string => !!h)) });
    return { harness: 'claude-code', action: 'remove', path, detail: `per-turn rule hook removed from ${path}` };
  } catch (e) {
    return { harness: opts.harness, action: 'skip', path: opts.harness === 'codex' ? codexPaths(paths).hooks : claudePath(paths), detail: `per-turn rule hook left as it is (${(e as Error).message})` };
  }
}

export function describeTurnHookOutcome(o: TurnHookOutcome, dryRun = false): string {
  const verb = dryRun && (o.action === 'write' || o.action === 'remove') ? `would ${o.action}` : o.action;
  return `  ${verb.padEnd(8)} ${'turn hook'.padEnd(7)} ${o.detail}${o.next ? `; wire it with: ${o.next}` : ''}`;
}