Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.5 KB
Raw Blame
/**
 * turn-hook-check.ts — is the per-turn brain-first hook wired, and does it
 * load? Read by doctor's harness_wiring check (`inspectTurnHook`, files only)
 * and by every install path (`verifyTurnHook`, which also runs the hook or
 * the harness's own inspect command), so an install whose hook cannot load
 * fails loudly with the command that shows why.
 *
 * Native inspect commands, per harness:
 *   Claude Code  /hooks inside a session (lists UserPromptSubmit hooks)
 *   Codex        /hooks inside a session (trust a hook there)
 *   OpenClaw     openclaw plugins inspect gbrain-turn-rule --runtime --json
 *   Hermes       hermes hooks doctor
 */
import { existsSync, readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import type { Action } from '../agent-output.ts';
import { bunSpawnSync } from '../spawn.ts';
import { codexHookCensus, codexHookGroupRuns, codexHookTrustHash } from '../bootstrap/codex-hooks.ts';
import { readCodexTomlTable } from '../bootstrap/codex-toml.ts';
import { classifyHarnessHook, hookEntryHash } from '../bootstrap/hooks.ts';
import { localSetupRecords } from './local-receipts.ts';
import { CLAUDE_SETTINGS_FILE_RELPATH, GBRAIN_HOOK_MARKER_KEY, GBRAIN_SETUP_MARKER_VALUE, claudeManagedSettingsPaths, claudeUserSettingsPath, codexConfigPath, codexHooksPath } from '../bootstrap/host-specs.ts';
import { hookLauncherInCommand, hookLauncherState, type HookLauncherState } from './hook-launcher.ts';
import type { LauncherLane } from './launcher-lanes.ts';
import { enabledPluginLanes } from '../bootstrap/plugin-lanes.ts';
import { brainFirstTarget, openclawConfigPath, parseJson5ish, readBrainFirstLedger } from './brain-first.ts';
import { inspectHermesTurnHook } from './hermes-turn-hook.ts';
import { OPENCLAW_TURN_PLUGIN_ID, openclawTurnPluginDir } from './openclaw-turn-plugin.ts';
import { isSkillResolverEntry } from './skill-resolver-lane.ts';
import { isOtherGbrainEntry, isTurnRuleEntry, isTurnRuleHarness, removeTurnRuleHook, syncTurnRuleHook, type TurnHookOutcome, type TurnHookPaths } from './turn-hook.ts';

export const TURN_HOOK_NATIVE_INSPECT: Record<string, string> = {
  'claude-code': '/hooks (inside a Claude Code session)',
  codex: '/hooks (inside a Codex session)',
  openclaw: `openclaw plugins inspect ${OPENCLAW_TURN_PLUGIN_ID} --runtime --json`,
  hermes: 'hermes hooks doctor',
};

export interface TurnHookState {
  harness: string;
  /** wired: a per-turn hook is configured; untrusted: configured but the harness will not run it yet; missing: none; not_supported: the harness has no per-turn hook gbrain can install. */
  state: 'wired' | 'untrusted' | 'missing' | 'not_supported';
  /** Which lane carries it. */
  via?: 'setup' | 'bootstrap' | 'turn-rule' | 'plugin' | 'native';
  detail: string;
  /** The hook command gbrain can run to prove it (Claude Code and Codex, not plugin lanes). */
  command?: string;
  /** The file the command came from. */
  source?: string;
  native_inspect?: string;
}

function readJson(path: string): Record<string, unknown> | null {
  if (!existsSync(path)) return null;
  try { return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>; } catch { return null; }
}

function claudeEntries(path: string): Array<Record<string, unknown>> {
  const groups = (readJson(path)?.hooks as Record<string, unknown> | undefined)?.UserPromptSubmit;
  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');
}

const isGbrainPromptEntry = (e: Record<string, unknown>) =>
  !isSkillResolverEntry(e) && (isTurnRuleEntry(e) || typeof e[GBRAIN_HOOK_MARKER_KEY] === 'string' || !!classifyHarnessHook(e, 'UserPromptSubmit', 'any'));

/** Files only, no process run. `projectDir`: a project-scope Claude Code install's directory; `managedDir`: Claude Code's managed-settings directory (default: the system one). */
export function inspectTurnHook(harness: string, opts: { projectDir?: string; managedDir?: string } = {}): TurnHookState {
  const native_inspect = TURN_HOOK_NATIVE_INSPECT[harness];
  const plugin = enabledPluginLanes('gbrain').find((l) => l.harness === harness);
  if (harness === 'claude-code') {
    const owned = setupReceiptHashes('claude-code').owned;
    const files = [claudeUserSettingsPath(), ...(opts.projectDir ? [join(opts.projectDir, '.claude', 'settings.local.json'), join(opts.projectDir, '.claude', 'settings.json')] : []), ...claudeManagedSettingsPaths(opts.managedDir)];
    for (const path of files) {
      const committed = !!opts.projectDir && path === join(opts.projectDir, '.claude', 'settings.json');
      // #9505: Claude Code can rewrite the file without the _gbrain marker; setup still owns its entry by hash.
      const setupOwned = (e: Record<string, unknown>) => !committed && owned.has(hookEntryHash(e) ?? '');
      const entries = claudeEntries(path).filter((e) => isTurnRuleEntry(e) || isOtherGbrainEntry(e, committed) || setupOwned(e));
      const effective = entries.find((e) => !isTurnRuleEntry(e)) ?? entries[0];
      if (effective) return { harness, state: 'wired', via: isTurnRuleEntry(effective) ? 'turn-rule' : effective[GBRAIN_HOOK_MARKER_KEY] === GBRAIN_SETUP_MARKER_VALUE || setupOwned(effective) ? 'setup' : 'bootstrap', detail: `UserPromptSubmit hook in ${path}`, command: String(effective.command), source: path, native_inspect };
    }
    if (plugin) return { harness, state: 'wired', via: 'plugin', detail: `the '${plugin.plugin}' plugin declares the UserPromptSubmit hook`, native_inspect };
    return { harness, state: 'missing', detail: `no gbrain UserPromptSubmit hook in ${files.join(' or ')}`, native_inspect };
  }
  if (harness === 'codex') {
    let groups: ReturnType<typeof codexHookCensus> = [];
    try { groups = codexHookCensus(codexHooksPath()).filter((g) => g.event === 'UserPromptSubmit' && g.lane !== 'other'); } catch { /* unparseable: Codex skips it too */ }
    const g = groups.find((x) => x.lane !== 'turn-rule') ?? groups[0];
    if (g) {
      const command = g.commands[0]!;
      const key = `${codexHooksPath()}:user_prompt_submit:${g.index}:0`;
      let table: { trusted_hash?: unknown } | undefined;
      try { table = readCodexTomlTable(codexConfigPath(), ['hooks', 'state', key]) as typeof table; } catch { table = undefined; }
      const trusted = table?.trusted_hash === codexHookTrustHash('user_prompt_submit', command, 15) && (g.lane === 'turn-rule' || codexHookGroupRuns(codexHooksPath(), codexConfigPath(), g));
      return { harness, state: trusted ? 'wired' : 'untrusted', via: g.lane as TurnHookState['via'], command, native_inspect,
        detail: trusted ? `UserPromptSubmit hook in ${codexHooksPath()}, trusted in ${codexConfigPath()}` : `UserPromptSubmit hook in ${codexHooksPath()} has no matching trust entry in ${codexConfigPath()}, so Codex does not run it` };
    }
    if (plugin) return { harness, state: 'wired', via: 'plugin', detail: `the '${plugin.plugin}' plugin declares the UserPromptSubmit hook (Codex runs it once you trust it in /hooks)`, native_inspect };
    return { harness, state: 'missing', detail: `no gbrain UserPromptSubmit hook in ${codexHooksPath()}`, native_inspect };
  }
  if (harness === 'openclaw') {
    const dir = openclawTurnPluginDir();
    const cfg = existsSync(openclawConfigPath()) ? parseJson5ish(readFileSync(openclawConfigPath(), 'utf8')) as { plugins?: { entries?: Record<string, { enabled?: unknown; hooks?: { allowConversationAccess?: unknown } }> } } | undefined : undefined;
    const entry = cfg?.plugins?.entries?.[OPENCLAW_TURN_PLUGIN_ID];
    if (!existsSync(join(dir, 'index.js'))) return { harness, state: 'missing', detail: `no per-turn rule plugin at ${dir}`, native_inspect };
    if (!entry || entry.enabled === false) return { harness, state: 'missing', detail: `${dir} exists but ${openclawConfigPath()} does not enable ${OPENCLAW_TURN_PLUGIN_ID}`, native_inspect };
    if (entry.hooks?.allowConversationAccess !== true) return { harness, state: 'untrusted', via: 'native', detail: `${OPENCLAW_TURN_PLUGIN_ID} is enabled without plugins.entries.${OPENCLAW_TURN_PLUGIN_ID}.hooks.allowConversationAccess, so OpenClaw skips its before_prompt_build hook`, native_inspect };
    return { harness, state: 'wired', via: 'native', detail: `${OPENCLAW_TURN_PLUGIN_ID} (before_prompt_build) enabled in ${openclawConfigPath()}`, native_inspect };
  }
  if (harness === 'hermes') {
    const target = brainFirstTarget('hermes');
    const soul = 'error' in target ? '' : target.path;
    const recorded = readBrainFirstLedger().find((e) => e.harness === harness && e.path === soul && e.status === 'installed');
    const h = inspectHermesTurnHook(soul ? dirname(soul) : '', recorded?.access);
    if (h.state === 'absent') return { harness, state: 'missing', detail: `no gbrain pre_llm_call hook in ${h.path}`, native_inspect };
    if (h.state === 'unapproved') return { harness, state: 'untrusted', via: 'native', detail: `the gbrain pre_llm_call hook in ${h.path} is not in Hermes's shell-hooks-allowlist.json, so Hermes does not run it`, native_inspect };
    return { harness, state: 'wired', via: 'native', detail: `pre_llm_call hook in ${h.path}, approved`, native_inspect };
  }
  return { harness, state: 'not_supported', detail: `${harness} has no per-turn hook gbrain can install; the rule reaches it only through its instruction file` };
}

/**
 * A hook the setup or turn-rule lane wrote that would let the session
 * directory's bunfig.toml or .env load (#8424): its command starts gbrain in
 * the session's directory (written before the hook launcher existed), or the
 * launcher it names is missing, changed, or shares its directory with a file
 * gbrain did not write.
 */
export interface HookLauncherProblem {
  harness: 'claude-code' | 'codex' | 'opencode';
  /** setup and turn-rule: hooks; mcp, harness and bootstrap: the other lanes (launcher-lanes.ts), which carry their own rerun. */
  lane: 'setup' | 'turn-rule' | LauncherLane;
  /** The settings or hooks file holding the entry. */
  source: string;
  /** session_cwd: no launcher in the command; otherwise the launcher's state. */
  reason: 'session_cwd' | Exclude<HookLauncherState, 'current'>;
  detail: string;
  /** A setup entry the user edited after setup wrote it: setup keeps it as is, so only the user can move it. */
  edited?: boolean;
  /** The other lanes: the command that rewrites the entry, where to run it, and whether it is setup's own (an agent may run it). */
  rerun?: string[];
  rerunFrom?: string;
  setupOwned?: boolean;
  owner?: 'setup' | 'bootstrap' | 'none';
  /** The setup receipt that owns the hook, when its hash is recorded. */
  receiptPath?: string;
}

/** The hook hashes a harness's setup receipts own and the ones they record as edited by the user: Claude Code can drop the `_gbrain` marker on a rewrite, and setup owns its entries by hash. */
function setupReceiptHashes(harness: 'claude-code' | 'codex'): { owned: Map<string, string>; edited: Map<string, string> } {
  const owned = new Map<string, string>();
  const edited = new Map<string, string>();
  for (const r of localSetupRecords().filter((x) => x.harness === harness)) {
    const hooks = (readJson(r.path) as { hooks?: { owned?: Record<string, unknown>; pending?: Record<string, unknown>; edited?: Record<string, unknown> } } | null)?.hooks;
    for (const h of [...Object.values(hooks?.owned ?? {}), ...Object.values(hooks?.pending ?? {})]) if (typeof h === 'string') owned.set(h, r.path);
    for (const h of Object.values(hooks?.edited ?? {})) if (typeof h === 'string') edited.set(h, r.path);
  }
  return { owned, edited };
}

type LaneCommand = { lane: 'setup' | 'turn-rule'; command: string; edited?: boolean; receiptPath?: string };

function claudeLaneCommands(path: string, setup: { owned: Map<string, string>; edited: Map<string, string> }): LaneCommand[] {
  const hooks = readJson(path)?.hooks;
  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return [];
  const out: LaneCommand[] = [];
  for (const groups of Object.values(hooks as Record<string, unknown>)) {
    if (!Array.isArray(groups)) continue;
    for (const e of groups.flatMap((g) => (Array.isArray((g as { hooks?: unknown })?.hooks) ? (g as { hooks: unknown[] }).hooks : []))) {
      if (!e || typeof e !== 'object' || typeof (e as Record<string, unknown>).command !== 'string') continue;
      const entry = e as Record<string, unknown>;
      const hash = hookEntryHash(entry) ?? '';
      if (isTurnRuleEntry(entry)) out.push({ lane: 'turn-rule', command: entry.command as string });
      else if (setup.edited.has(hash)) out.push({ lane: 'setup', command: entry.command as string, edited: true, receiptPath: setup.edited.get(hash) });
      else if (entry[GBRAIN_HOOK_MARKER_KEY] === GBRAIN_SETUP_MARKER_VALUE || setup.owned.has(hash)) out.push({ lane: 'setup', command: entry.command as string, receiptPath: setup.owned.get(hash) });
    }
  }
  return out;
}

/** Files only. Every event's setup and turn-rule entries, user scope plus `projectDir`'s settings.local.json (Claude Code). */
export function hookLauncherProblem(harness: 'claude-code' | 'codex', opts: { projectDir?: string } = {}): HookLauncherProblem | null {
  const found: Array<LaneCommand & { source: string }> = [];
  const setup = setupReceiptHashes(harness);
  if (harness === 'claude-code') {
    for (const source of [claudeUserSettingsPath(), ...(opts.projectDir ? [join(opts.projectDir, CLAUDE_SETTINGS_FILE_RELPATH)] : [])]) {
      found.push(...claudeLaneCommands(source, setup).map((c) => ({ ...c, source })));
    }
  } else {
    try {
      for (const g of codexHookCensus(codexHooksPath())) {
        if (g.lane === 'setup' || g.lane === 'turn-rule') found.push(...g.commands.map((command) => ({ lane: g.lane as 'setup' | 'turn-rule', command, source: codexHooksPath(), ...(setup.edited.has(g.hash) ? { edited: true } : {}), receiptPath: setup.owned.get(g.hash) ?? setup.edited.get(g.hash) })));
      }
    } catch { /* unparseable: Codex runs none of it */ }
  }
  for (const f of found) {
    const launcher = hookLauncherInCommand(f.command);
    if (!launcher) {
      return { harness, lane: f.lane, source: f.source, reason: 'session_cwd', ...(f.edited ? { edited: true } : {}), ...(f.receiptPath ? { receiptPath: f.receiptPath } : {}),
        detail: `gbrain's ${f.lane} hook in ${f.source} starts gbrain in the session's directory, so Bun loads that directory's bunfig.toml and .env before gbrain runs${f.edited ? '; it was edited after setup wrote it, so setup keeps it as is' : ''}` };
    }
    const s = hookLauncherState(launcher);
    if (s.state !== 'current') return { harness, lane: f.lane, source: f.source, reason: s.state, ...(f.receiptPath ? { receiptPath: f.receiptPath } : {}), detail: `gbrain's ${f.lane} hook in ${f.source} runs through ${launcher}, but ${s.detail}` };
  }
  return null;
}

type Run = (argv: string[], stdin?: string) => { ok: boolean; output: string };
/** Only what a hook needs to find the brain and the rule; never provider keys. */
function hookEnv(): Record<string, string> {
  return Object.fromEntries(Object.entries(process.env).filter((e): e is [string, string] => e[1] !== undefined && /^(HOME|PATH|USER|LANG|TMPDIR|XDG_CONFIG_HOME|CLAUDE_CONFIG_DIR|CODEX_HOME|GBRAIN_HOME|GBRAIN_AGENT_INSTRUCTIONS|GBRAIN_HOOKS)$/.test(e[0])));
}
const defaultRun: Run = (argv, stdin) => {
  try {
    // From the home directory: a project's own gbrain hook would make the turn-rule lane yield there.
    const r = bunSpawnSync(argv, { stdin: stdin === undefined ? 'ignore' : Buffer.from(stdin), stdout: 'pipe', stderr: 'pipe', env: hookEnv(), cwd: process.env.HOME || undefined, timeout: 60_000 });
    return { ok: r.exitCode === 0, output: `${r.stdout.toString()}${r.stderr.toString()}` };
  } catch (e) { return { ok: false, output: (e as Error).message }; }
};
const which = (bin: string): string | null => { try { return Bun.which(bin, { PATH: process.env.PATH ?? '' }); } catch { return null; } };

export interface TurnHookVerdict { ok: boolean; state: TurnHookState; reason: string; message: string }

/**
 * Install-time proof that the hook loads: Claude Code and Codex run the
 * configured command once and look for the rule in its output; OpenClaw runs
 * its runtime inspect; Hermes runs `hermes hooks doctor`. A harness binary
 * that is not on PATH leaves the file-level answer standing.
 */
export function verifyTurnHook(harness: string, opts: { projectDir?: string; run?: Run; which?: (bin: string) => string | null } = {}): TurnHookVerdict {
  const run = opts.run ?? defaultRun;
  const find = opts.which ?? which;
  const state = inspectTurnHook(harness, opts);
  const fail = (reason: string, message: string): TurnHookVerdict => ({ ok: false, state, reason, message });
  if (state.state === 'not_supported') return { ok: true, state, reason: 'not_supported', message: state.detail };
  if (state.state === 'missing') return fail('missing', state.detail);
  if (state.state === 'untrusted') return fail('untrusted', state.detail);
  if (state.via === 'plugin') return { ok: true, state, reason: 'plugin_lane', message: `${state.detail}; check it with ${state.native_inspect}` };
  if ((harness === 'claude-code' || harness === 'codex') && state.command) {
    // A command from a project's settings file is the repo's, not the user's: never run it.
    if (harness === 'claude-code' && state.source !== claudeUserSettingsPath()) return { ok: true, state, reason: 'project_unverified', message: `${state.detail}; a hook outside the user settings file (project or managed) is not run here, so check it with ${state.native_inspect}` };
    const r = run(['sh', '-c', state.command], JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt: '', session_id: 'gbrain-install-check' }));
    if (!r.ok) return fail('hook_failed', `the UserPromptSubmit hook exited non-zero (${r.output.trim().split('\n').at(-1) || 'no output'})`);
    if (!r.output.includes('GBrain: before answering')) return fail('no_rule', 'the UserPromptSubmit hook ran but did not add the brain-first rule (is the brain-first block installed for this harness?)');
    return { ok: true, state, reason: 'ran', message: `${state.detail}; it ran and added the rule` };
  }
  if (harness === 'openclaw') {
    const bin = find('openclaw');
    if (!bin) return { ok: true, state, reason: 'native_unavailable', message: `${state.detail}; openclaw is not on PATH, so run ${state.native_inspect} on the OpenClaw host` };
    const r = run([bin, 'plugins', 'inspect', OPENCLAW_TURN_PLUGIN_ID, '--runtime', '--json']);
    const loaded = r.ok && r.output.includes('before_prompt_build') && /"(?:status)"\s*:\s*"loaded"|"imported"\s*:\s*true/.test(r.output) && !/"status"\s*:\s*"(?:error|disabled)"/.test(r.output);
    return loaded ? { ok: true, state, reason: 'ran', message: `${state.detail}; openclaw loads it with before_prompt_build` }
      : fail('not_loaded', `\`${state.native_inspect}\` does not show ${OPENCLAW_TURN_PLUGIN_ID} loaded with before_prompt_build`);
  }
  if (harness === 'hermes') {
    const bin = find('hermes');
    if (!bin) return { ok: true, state, reason: 'native_unavailable', message: `${state.detail}; hermes is not on PATH, so run ${state.native_inspect} on the Hermes host` };
    const r = run([bin, 'hooks', 'doctor']);
    const block = r.output.split(/\n(?=\s*\[)/).find((b) => /\[pre_llm_call\]/.test(b) && b.includes('GBrain'));
    if (!r.ok || !block) return fail('not_loaded', `\`hermes hooks doctor\` does not list gbrain's pre_llm_call hook`);
    if (/✗|⚠/.test(block)) return fail('not_loaded', `\`hermes hooks doctor\` reports a problem with gbrain's pre_llm_call hook: ${block.split('\n').filter((l) => /✗|⚠/.test(l)).map((l) => l.trim()).join(' ')}`);
    return { ok: true, state, reason: 'ran', message: `${state.detail}; hermes hooks doctor reports it healthy` };
  }
  return { ok: true, state, reason: 'wired', message: state.detail };
}

/**
 * The operator-protocol fix for a hook that is missing or does not load:
 * re-run the install that writes it, then verify with the harness's own
 * inspect command (OpenClaw, Hermes) or doctor (Claude Code, Codex, whose
 * inspect is the in-session /hooks menu).
 */
export function turnHookFix(harness: string, rerun: string[]): Action {
  const native = TURN_HOOK_NATIVE_INSPECT[harness];
  const verify = harness === 'openclaw' ? ['openclaw', 'plugins', 'inspect', OPENCLAW_TURN_PLUGIN_ID, '--runtime', '--json']
    : harness === 'hermes' ? ['hermes', 'hooks', 'doctor'] : ['gbrain', 'doctor', '--only', 'harness_wiring', '--json'];
  return { argv: rerun, consent: ['persistent_install'], actor: 'agent', requires_exclusive: false, verify: { argv: verify },
    why: `Writes the per-turn hook that puts "check gbrain first" next to every turn; without it agents rarely use the brain. ${native ? `The harness's own check: ${native}.` : ''}`.trim() };
}

/**
 * The installer lanes' per-turn hook (`gbrain connect --install`, the hosted
 * harness install, `gbrain bootstrap harness`): with the brain-first block
 * accepted, install the turn-rule hook unless another gbrain lane already
 * carries the rule, then prove it loads; declined, remove it. opencode and
 * other clients get `not_supported` (no per-turn hook to install).
 */
export function installerTurnHook(opts: { harness: string; accepted: boolean; gbrainBin: string | null; gbrainHome?: string; paths?: TurnHookPaths; rerun: string; verify?: boolean }): { outcome: TurnHookOutcome; verdict: TurnHookVerdict | null } {
  const { harness } = opts;
  if (!isTurnRuleHarness(harness)) {
    return { outcome: { harness, action: 'skip', path: '', detail: `${harness} has no per-turn hook gbrain can install; the rule reaches it through its instruction file only` }, verdict: null };
  }
  if (!opts.accepted) return { outcome: removeTurnRuleHook({ harness, paths: opts.paths }), verdict: null };
  if (process.env.GBRAIN_HOOKS === '0') return { outcome: { harness, action: 'skip', path: '', detail: 'GBRAIN_HOOKS=0 is set: no per-turn hook installed' }, verdict: null };
  const carried = opts.paths ? null : inspectTurnHook(harness);
  const outcome = carried && carried.state !== 'missing' && carried.via !== 'turn-rule'
    ? { harness, action: 'skip' as const, path: '', detail: `per-turn rule already carried: ${carried.detail}` }
    : syncTurnRuleHook({ harness, gbrainBin: opts.gbrainBin, gbrainHome: opts.gbrainHome, paths: opts.paths, rerun: opts.rerun });
  // Nothing was installed and the outcome names the step that does it: reported, never a failed install.
  if (outcome.action === 'print') return { outcome, verdict: null };
  return { outcome, verdict: opts.verify === false || opts.paths ? null : verifyTurnHook(harness) };
}