Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

tests: per-turn hook on every install path and its loud failure; print is not a failure

garrytanc978d17601d6
diff --git a/src/commands/setup.ts b/src/commands/setup.ts
index d4e10e08b6..46fd533d61 100644
--- a/src/commands/setup.ts
+++ b/src/commands/setup.ts
@@ -27,7 +27,7 @@ import { dirname, join } from 'node:path';
import { removeHermesTurnHook, syncHermesTurnHook } from '../core/setup/hermes-turn-hook.ts';
import { removeOpenclawTurnPlugin, syncOpenclawTurnPlugin } from '../core/setup/openclaw-turn-plugin.ts';
import { isTurnRuleHarness, removeTurnRuleHook, syncTurnRuleHook, type TurnHookOutcome, type TurnRuleHarness } from '../core/setup/turn-hook.ts';
-import { inspectTurnHook, turnHookFix, verifyTurnHook, type TurnHookVerdict } from '../core/setup/turn-hook-check.ts';
+import { inspectTurnHook, TURN_HOOK_NATIVE_INSPECT, turnHookFix, verifyTurnHook, type TurnHookVerdict } from '../core/setup/turn-hook-check.ts';
import { opError, OperationError } from '../core/ops/contract.ts';
import { cliRenderContext, renderCliError, renderNotice, type Action, type Notice } from '../core/agent-output.ts';
import { writeCliNotices } from '../core/interop-notices.ts';
@@ -792,7 +792,7 @@ function turnRuleHookFor(harness: TurnRuleHarness, off: boolean, flags: SetupFla
function turnHookNotLoaded(harness: string, check: TurnHookVerdict, rerun: string[]): OperationError {
const fix = turnHookFix(harness, rerun);
- return opError('turn_hook_not_loaded', `The per-turn gbrain hook for ${harness} is not active: ${check.message}.`, fix.why, { reason: check.reason, docs: 'docs/guides/repair.md#turn-hook-not-loaded', fix });
+ return opError('turn_hook_not_loaded', `The per-turn gbrain hook for ${harness} is not active: ${check.message}.${TURN_HOOK_NATIVE_INSPECT[harness] ? ` The harness's own check: ${TURN_HOOK_NATIVE_INSPECT[harness]}.` : ''}`, fix.why, { reason: check.reason, docs: 'docs/guides/repair.md#turn-hook-not-loaded', fix });
}
async function finish(out: Out, doc: {
diff --git a/src/core/setup/turn-hook-check.ts b/src/core/setup/turn-hook-check.ts
index 52f4fd557e..9a82a0bf48 100644
--- a/src/core/setup/turn-hook-check.ts
+++ b/src/core/setup/turn-hook-check.ts
@@ -137,7 +137,7 @@ export function verifyTurnHook(harness: string, opts: { projectDir?: string; run
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) {
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.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` };
}
@@ -192,6 +192,7 @@ export function installerTurnHook(opts: { harness: string; accepted: boolean; gb
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 });
- if (outcome.action === 'print') return { outcome, verdict: { ok: false, state: { harness, state: 'missing', detail: outcome.detail }, reason: 'missing', message: outcome.detail } };
+ // 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) };
}
diff --git a/test/bootstrap-harness.serial.test.ts b/test/bootstrap-harness.serial.test.ts
index 6fc9bf9acf..941c69f9dd 100644
--- a/test/bootstrap-harness.serial.test.ts
+++ b/test/bootstrap-harness.serial.test.ts
@@ -486,6 +486,18 @@ describe('full apply', () => {
expect(readFileSync(join(dirname(g.codexConfig), 'hooks.json'), 'utf8')).toContain('hook session-end --harness codex');
});
+ test('codex lane wires the per-turn rule hook, trusted, beside the brain-first block; the consent block names it', async () => {
+ const f = makeFake();
+ expect(await applyHarness(flags(['--harness', 'codex']), f.deps)).toBe(0);
+ expect(f.out.join('\n')).toContain('The per-turn brain-first rule hook (UserPromptSubmit');
+ const hooks = readFileSync(join(dirname(f.codexConfig), 'hooks.json'), 'utf8');
+ expect(hooks).toContain('GBRAIN_HOOK_LANE=turn-rule');
+ expect(hooks).toContain('hook user-prompt');
+ expect(readFileSync(f.codexConfig, 'utf8')).toContain('user_prompt_submit');
+ expect(await removeHarness(flags(['--remove', '--harness', 'codex']), f.deps)).toBe(0);
+ expect(existsSync(join(dirname(f.codexConfig), 'hooks.json')) ? readFileSync(join(dirname(f.codexConfig), 'hooks.json'), 'utf8') : '').not.toContain('GBRAIN_HOOK_LANE=turn-rule');
+ });
+
test('--project must exist [F4]', async () => {
const f = makeFake();
const code = await applyHarness(flags(['--project', '/definitely/not/a/dir']), f.deps);
diff --git a/test/connect.test.ts b/test/connect.test.ts
index 9a40ce5ed3..d32e2e5374 100644
--- a/test/connect.test.ts
+++ b/test/connect.test.ts
@@ -538,6 +538,16 @@ describe('runConnect --install', () => {
expect(all).toContain(REDACTED);
});
+ test('a per-turn hook that does not load fails the install loudly (turn_hook_not_loaded)', async () => {
+ const r = await runWithExitCapture(
+ ['https://brain.example.com/mcp', '--token', 'gbrain_tok', '--install', '--yes'],
+ installDeps({ writeTurnHook: () => ({ lines: ['error turn_hook_not_loaded (hook_failed): the per-turn gbrain hook is not active'], ok: false }) }),
+ );
+ expect(r.exitCode).toBe(1);
+ expect(r.err.join('\n')).toContain('turn_hook_not_loaded');
+ expect(r.err.join('\n')).toMatch(/Verified/);
+ });
+
test('missing claude binary fails fast', async () => {
const r = await runWithExitCapture(
['https://brain.example.com/mcp', '--token', 'tok', '--install', '--yes'],
diff --git a/test/turn-hook-install-paths.test.ts b/test/turn-hook-install-paths.test.ts
new file mode 100644
index 0000000000..cd8c93ea90
--- /dev/null
+++ b/test/turn-hook-install-paths.test.ts
@@ -0,0 +1,193 @@
+/**
+ * The per-turn rule hook on every install path (src/core/setup/turn-hook.ts,
+ * turn-hook-check.ts), and the loud failure when it cannot load:
+ * - setup <claude-code|codex> --instructions-only (a plain `mcp add`) writes the
+ * turn-rule hook, runs it once and exits 0; a hook that fails or adds no rule
+ * exits 1 with turn_hook_not_loaded; with no absolute binary it prints the step;
+ * - the installer lanes (connect --install, the hosted harness install,
+ * bootstrap harness) share installerTurnHook;
+ * - OpenClaw and Hermes verify through their own inspect commands.
+ * Spawns `bun src/cli.ts setup` against a temp HOME / GBRAIN_HOME.
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { runCli } from './helpers/cli-spawn.ts';
+import { withEnv } from './helpers/with-env.ts';
+import { installerTurnHook, verifyTurnHook } from '../src/core/setup/turn-hook-check.ts';
+import { TURN_RULE_LANE_TOKEN, TURN_RULE_MARKER } from '../src/core/setup/turn-hook.ts';
+import { syncHermesTurnHook } from '../src/core/setup/hermes-turn-hook.ts';
+import { openclawTurnPluginDir, openclawTurnPluginFiles } from '../src/core/setup/openclaw-turn-plugin.ts';
+
+const CLI = resolve(import.meta.dir, '..', 'src', 'cli.ts');
+const roots: string[] = [];
+afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true }); });
+
+function box() {
+ const root = mkdtempSync(join(tmpdir(), 'gbrain-turn-hook-'));
+ roots.push(root);
+ const home = join(root, 'home');
+ const project = join(root, 'project');
+ mkdirSync(home, { recursive: true });
+ mkdirSync(project, { recursive: true });
+ mkdirSync(join(root, 'bin'));
+ const script = (name: string, body: string) => { const p = join(root, 'bin', name); writeFileSync(p, `#!/bin/sh\n${body}\n`); chmodSync(p, 0o755); return p; };
+ const bin = script('gbrain', `exec '${process.execPath}' --no-env-file '${CLI}' "$@"`);
+ const env: Record<string, string | undefined> = {
+ HOME: home, GBRAIN_HOME: home, PATH: '/usr/bin:/bin', CLAUDE_CONFIG_DIR: undefined, CODEX_HOME: undefined, XDG_CONFIG_HOME: undefined,
+ OPENCLAW_STATE_DIR: undefined, OPENCLAW_WORKSPACE_DIR: undefined, OPENCLAW_PROFILE: undefined, OPENCLAW_CONFIG_PATH: undefined, HERMES_HOME: undefined,
+ GBRAIN_AGENT_INSTRUCTIONS: undefined, GBRAIN_SURFACE: undefined, GBRAIN_SOURCE: undefined, GBRAIN_HOOKS: undefined, GBRAIN_HOOK_LANE: undefined,
+ CLAUDECODE: undefined, CLAUDE_CODE_ENTRYPOINT: undefined, CODEX_SANDBOX: undefined, CODEX_CI: undefined,
+ };
+ return { root, home, project, bin, script, env };
+}
+type Box = ReturnType<typeof box>;
+
+async function setup(b: Box, args: string[]) {
+ const r = await runCli(['setup', ...args], { env: b.env, cwd: b.project });
+ let doc: any = null;
+ try { doc = JSON.parse(r.stdout); } catch { doc = null; }
+ return { ...r, doc };
+}
+const readJson = (p: string) => JSON.parse(readFileSync(p, 'utf8'));
+const claudePromptEntries = (b: Box) => (readJson(join(b.home, '.claude', 'settings.json')).hooks?.UserPromptSubmit ?? []).flatMap((g: any) => g.hooks);
+
+describe('setup --instructions-only after a plain mcp add', () => {
+ test('claude-code: writes the turn-rule hook, runs it and passes; a re-run keeps one entry', async () => {
+ const b = box();
+ const r = await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', b.bin, '--json']);
+ expect(r.exitCode).toBe(0);
+ expect(r.doc.turn_hook).toMatchObject({ harness: 'claude-code', action: 'write' });
+ expect(r.doc.turn_hook_check).toMatchObject({ ok: true, reason: 'ran' });
+ const entries = claudePromptEntries(b);
+ expect(entries).toEqual([expect.objectContaining({ _gbrain: TURN_RULE_MARKER })]);
+ expect(entries[0].command).toContain(TURN_RULE_LANE_TOKEN);
+ expect(entries[0].command).toContain(`${b.bin} hook user-prompt`);
+ expect((await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', b.bin, '--json'])).exitCode).toBe(0);
+ expect(claudePromptEntries(b)).toHaveLength(1);
+ });
+
+ test('codex: writes the hooks.json group and its config.toml trust entry, runs it and passes', async () => {
+ const b = box();
+ const r = await setup(b, ['codex', '--instructions-only', '--gbrain-bin', b.bin, '--json']);
+ expect(r.exitCode).toBe(0);
+ expect(r.doc.turn_hook_check).toMatchObject({ ok: true, reason: 'ran' });
+ expect(readFileSync(join(b.home, '.codex', 'hooks.json'), 'utf8')).toContain(TURN_RULE_LANE_TOKEN);
+ expect(readFileSync(join(b.home, '.codex', 'config.toml'), 'utf8')).toContain('user_prompt_submit');
+ });
+
+ test('a hook that fails to run exits 1 with turn_hook_not_loaded and names the native check', async () => {
+ const b = box();
+ const broken = b.script('gbrain-broken', 'exit 3');
+ const json = await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', broken, '--json']);
+ expect(json.exitCode).toBe(1);
+ expect(json.doc.turn_hook_check).toMatchObject({ ok: false, reason: 'hook_failed' });
+ const text = await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', broken]);
+ expect(text.exitCode).toBe(1);
+ expect(text.stderr + text.stdout).toContain('turn_hook_not_loaded');
+ expect(text.stderr + text.stdout).toContain("The harness's own check: /hooks (inside a Claude Code session).");
+ expect(text.stderr + text.stdout).toContain('exited non-zero (no output)');
+ });
+
+ test('a hook that runs but adds no rule exits 1 (no_rule)', async () => {
+ const b = box();
+ const silent = b.script('gbrain-silent', 'exit 0');
+ const r = await setup(b, ['codex', '--instructions-only', '--gbrain-bin', silent, '--json']);
+ expect(r.exitCode).toBe(1);
+ expect(r.doc.turn_hook_check).toMatchObject({ ok: false, reason: 'no_rule' });
+ });
+
+ test('no absolute gbrain binary: nothing is installed, the one-line next step is printed, exit 0', async () => {
+ const b = box();
+ const r = await setup(b, ['claude-code', '--instructions-only', '--json']);
+ expect(r.exitCode).toBe(0);
+ expect(r.doc.turn_hook).toMatchObject({ action: 'print', next: 'gbrain setup claude-code --instructions-only' });
+ expect(r.doc.turn_hook_check).toBeUndefined();
+ expect(existsSync(join(b.home, '.claude', 'settings.json'))).toBe(false);
+ });
+
+ test('--no-instructions removes the turn-rule hook with the block', async () => {
+ const b = box();
+ await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', b.bin, '--json']);
+ expect(claudePromptEntries(b)).toHaveLength(1);
+ expect((await setup(b, ['claude-code', '--instructions-only', '--no-instructions', '--json'])).exitCode).toBe(0);
+ expect(claudePromptEntries(b)).toHaveLength(0);
+ });
+});
+
+describe('installer lanes (connect --install, hosted harness install, bootstrap harness)', () => {
+ test('installerTurnHook writes the hook beside a pointed-at config, removes it on decline, and never fails a print', async () => {
+ const b = box();
+ const paths = { claudeSettings: join(b.root, 'cfg', 'settings.json') };
+ await withEnv(b.env, async () => {
+ const wrote = installerTurnHook({ harness: 'claude-code', accepted: true, gbrainBin: b.bin, paths, rerun: 'gbrain setup claude-code --instructions-only' });
+ expect(wrote.outcome.action).toBe('write');
+ expect(readFileSync(paths.claudeSettings, 'utf8')).toContain(TURN_RULE_LANE_TOKEN);
+ expect(installerTurnHook({ harness: 'claude-code', accepted: false, gbrainBin: b.bin, paths, rerun: '' }).outcome.action).toBe('remove');
+ expect(readFileSync(paths.claudeSettings, 'utf8')).not.toContain(TURN_RULE_LANE_TOKEN);
+ const printed = installerTurnHook({ harness: 'codex', accepted: true, gbrainBin: null, rerun: 'gbrain setup codex --instructions-only' });
+ expect(printed.outcome).toMatchObject({ action: 'print', next: 'gbrain setup codex --instructions-only' });
+ expect(printed.verdict).toBeNull();
+ expect(installerTurnHook({ harness: 'opencode', accepted: true, gbrainBin: b.bin, rerun: '' }).outcome.action).toBe('skip');
+ });
+ });
+
+ test('a written hook that does not load fails the install with a verdict (default paths)', async () => {
+ const b = box();
+ const broken = b.script('gbrain-broken', 'exit 3');
+ await withEnv(b.env, async () => {
+ const r = installerTurnHook({ harness: 'claude-code', accepted: true, gbrainBin: broken, rerun: 'gbrain setup claude-code --instructions-only' });
+ expect(r.outcome.action).toBe('write');
+ expect(r.verdict).toMatchObject({ ok: false, reason: 'hook_failed' });
+ });
+ });
+});
+
+describe('OpenClaw and Hermes verify with their own inspect commands', () => {
+ const access = { kind: 'mcp', server: 'gbrain' } as const;
+
+ function openclaw(b: Box, entry: Record<string, unknown>) {
+ const state = join(b.root, 'openclaw');
+ const env = { ...b.env, OPENCLAW_STATE_DIR: state };
+ return withEnv(env, async () => {
+ const dir = openclawTurnPluginDir();
+ mkdirSync(dir, { recursive: true });
+ for (const [name, body] of Object.entries(openclawTurnPluginFiles(access))) writeFileSync(join(dir, name), body);
+ writeFileSync(join(state, 'openclaw.json'), JSON.stringify({ plugins: { entries: { 'gbrain-turn-rule': entry } } }));
+ }).then(() => env);
+ }
+
+ test('openclaw: loaded with before_prompt_build passes; an error status fails not_loaded; no allowConversationAccess is untrusted', async () => {
+ const b = box();
+ const env = await openclaw(b, { enabled: true, hooks: { allowConversationAccess: true } });
+ const which = () => '/usr/local/bin/openclaw';
+ await withEnv(env, async () => {
+ const seen: string[][] = [];
+ const loaded = verifyTurnHook('openclaw', { which, run: (argv) => { seen.push(argv); return { ok: true, output: '{"id":"gbrain-turn-rule","status":"loaded","imported":true,"hooks":["before_prompt_build"]}' }; } });
+ expect(loaded).toMatchObject({ ok: true, reason: 'ran' });
+ expect(seen[0]).toEqual(['/usr/local/bin/openclaw', 'plugins', 'inspect', 'gbrain-turn-rule', '--runtime', '--json']);
+ expect(verifyTurnHook('openclaw', { which, run: () => ({ ok: true, output: '{"id":"gbrain-turn-rule","status":"error","hooks":["before_prompt_build"]}' }) })).toMatchObject({ ok: false, reason: 'not_loaded' });
+ });
+ const untrusted = await openclaw(box(), { enabled: true });
+ await withEnv(untrusted, async () => {
+ expect(verifyTurnHook('openclaw', { which, run: () => ({ ok: true, output: '' }) })).toMatchObject({ ok: false, reason: 'untrusted' });
+ });
+ });
+
+ test('hermes: a healthy hooks doctor block passes; a ✗ line fails not_loaded', async () => {
+ const b = box();
+ const hermesHome = join(b.root, 'hermes');
+ mkdirSync(hermesHome, { recursive: true });
+ writeFileSync(join(hermesHome, 'SOUL.md'), 'You are a careful assistant.\n');
+ const env = { ...b.env, HERMES_HOME: hermesHome };
+ await withEnv(env, async () => {
+ expect(syncHermesTurnHook({ hermesHome, access, dryRun: false }).action).toBe('write');
+ const which = () => '/usr/local/bin/hermes';
+ const doctor = (mark: string) => () => ({ ok: true, output: `Shell hooks\n [pre_llm_call] /bin/echo '{"context":"GBrain: before answering this turn"}'\n ${mark}\n [post_tool_call] /bin/true\n ✓ allowlisted\n` });
+ expect(verifyTurnHook('hermes', { which, run: doctor('✓ allowlisted, script present') })).toMatchObject({ ok: true, reason: 'ran' });
+ expect(verifyTurnHook('hermes', { which, run: doctor('✗ not allowlisted') })).toMatchObject({ ok: false, reason: 'not_loaded' });
+ expect(verifyTurnHook('hermes', { which: () => null })).toMatchObject({ ok: true, reason: 'native_unavailable' });
+ });
+ });
+});