Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* bootstrap/harness-hooks.ts — the harness lane's Claude Code hook entries
* after the host dropped their `_gbrain` marker (#6092, #6171). Claude Code
* rewrites settings.json through its own schema and can drop unknown keys, so
* an entry is this install's when it carries the marker OR its command is
* exactly the harness hook this install (or its receipt) rendered
* (hooks.ts classifyHarnessHook). This module holds the receipt-aware glue
* harness.ts calls: removal of one hooks target (with the `--dry-run`
* preview), the `harness_hook_unowned` notice, the cross-HOME `--project`
* guard probe and the `--status` carrier census.
*/
import { cliRenderContext, noticeBlock, renderNotice } from '../agent-output.ts';
import type { HarnessReceipt, HarnessTarget } from './format.ts';
import { GBRAIN_HARNESS_MARKER_VALUE } from './host-specs.ts';
import { harnessHookIdentity, removeClaudeHooksAt, scanHarnessHookCarrier } from './hooks.ts';
interface HookDeps {
userSettingsPath: string;
gbrainBin: string | null;
log: (line: string) => void;
logError: (line: string) => void;
}
const STATUS_ARGV = ['gbrain', 'bootstrap', 'harness', '--status'];
function carrierPath(t: HarnessTarget, d: Pick<HookDeps, 'userSettingsPath'>): string {
return t.scope === 'user' ? (t.path ?? d.userSettingsPath) : t.path!;
}
/** The agent-first block for harness-looking entries gbrain would not delete. */
export function harnessHookUnownedNotice(settingsPath: string, events: string[]): string {
const where = events.map((e) => `hooks.${e}`).join(', ');
const rendered = renderNotice({
code: 'harness_hook_unowned',
kind: 'safety',
why: `${where} in ${settingsPath} looks like gbrain's harness hook but is not this install's exact command ` +
'(edited, or written by another install or launcher), so gbrain left it in place and does not report the harness as removed.',
fix: {
argv: ['gbrain', 'bootstrap', 'harness', '--remove'],
consent: [],
actor: 'user',
requires_exclusive: false,
why: 'Only the user can say whether that entry is a leftover; once it is gone the removal completes and consumes the receipt.',
user_message: `Open ${settingsPath} and delete the ${where} entry that runs \`gbrain hook\` if you no longer want it ` +
'(keep it only if you added it on purpose), then run `gbrain bootstrap harness --remove` again.',
verify: { argv: STATUS_ARGV },
},
}, cliRenderContext());
return `${noticeBlock(rendered)}\nverify: ${STATUS_ARGV.join(' ')}`;
}
/**
* Remove one claude-code hooks target: marked entries plus unmarked entries
* whose command is this install's (receipt launcher/seat, receipt source, the
* running launcher). Logs each unmarked entry by event and why it matched.
* Throws when a harness-looking entry that is not ours survives, so the
* target stays failed on the receipt (`harness_hook_unowned`). `dryRun`
* reports the same lines and writes nothing.
*/
export function removeHarnessHooksTarget(t: HarnessTarget, receipt: HarnessReceipt, d: HookDeps, dryRun = false): void {
const settingsPath = carrierPath(t, d);
const r = removeClaudeHooksAt(settingsPath, t.marker ?? GBRAIN_HARNESS_MARKER_VALUE, {
identity: harnessHookIdentity(receipt, t, { launcher: d.gbrainBin }),
dryRun,
});
if (r.notes.some((n) => n.startsWith('WARNING'))) throw new Error(r.notes.join('; '));
const verb = dryRun ? 'would remove' : 'removed';
for (const u of r.unmarked) d.log(` ${verb} unmarked hooks.${u.event} entry: ${u.why}.`);
const entries = `${r.removed} harness hook entr${r.removed === 1 ? 'y' : 'ies'}`;
if (r.removed > 0) d.log(dryRun ? `would remove ${entries} from ${settingsPath}.` : `${entries} removed from ${settingsPath}.`);
if (r.unowned.length > 0) {
d.logError(harnessHookUnownedNotice(settingsPath, r.unowned));
throw new Error(
`harness_hook_unowned: ${r.unowned.map((e) => `hooks.${e}`).join(', ')} in ${settingsPath} looks like a gbrain harness hook ` +
'this install did not write — left in place; delete it by hand, then re-run `gbrain bootstrap harness --remove`',
);
}
if (r.removed === 0) d.log(`no harness hook entries in ${settingsPath}${dryRun ? '.' : ' — counted as removed.'}`);
}
/** `gbrain bootstrap harness --remove --dry-run`: what removal would do, with
* the unmarked hook entries listed; nothing is written and the receipt stays. */
export function previewHarnessRemoval(receipt: HarnessReceipt, d: HookDeps): number {
d.log('dry run: nothing is written; the receipt stays in place.');
let blocked = false;
for (const t of receipt.targets) {
if (t.host === 'claude-code' && t.kind === 'hooks') {
try {
removeHarnessHooksTarget(t, receipt, d, true);
} catch (e) {
blocked = true;
d.logError(`would fail ${t.host}/${t.kind}: ${e instanceof Error ? e.message : String(e)}`);
}
continue;
}
if (t.kind === 'permission' && t.mechanism === 'pre-existing') {
d.log(`would leave permissions.allow entry '${t.entry}' in place (it predates the harness install).`);
continue;
}
d.log(`would remove ${t.host}/${t.kind}${t.name ? ` '${t.name}'` : t.entry ? ` '${t.entry}'` : ''}${t.path ? ` (${t.path})` : ''}.`);
}
if (receipt.token.minted && receipt.token.id) d.log(`would revoke the harness token (id ${receipt.token.id}).`);
return blocked ? 1 : 0;
}
/** True when the user-scope settings carry any harness hook entry, marked or
* not, exact or edited (`unowned` by shape, W4.8), from any install —
* `--project` wiring would double-fire next to it. */
export function harnessHooksPresent(settingsPath: string): boolean {
const scan = scanHarnessHookCarrier(settingsPath, 'any');
return Object.values(scan.events).some((c) => c.marked + c.command + c.unowned > 0);
}
/** `--status` census of each receipt-named hook carrier (read-only). */
export function harnessHookCarrierStatus(receipt: HarnessReceipt, d: Pick<HookDeps, 'userSettingsPath' | 'gbrainBin'>): Array<{
path: string; state: string; ours: number; unmarked: number; duplicates: string[]; unowned: string[];
}> {
return receipt.targets.filter((t) => t.host === 'claude-code' && t.kind === 'hooks').map((t) => {
const path = carrierPath(t, d);
const scan = scanHarnessHookCarrier(path, harnessHookIdentity(receipt, t, { launcher: d.gbrainBin }));
const counts = Object.entries(scan.events);
return {
path,
state: scan.state,
ours: counts.reduce((n, [, c]) => n + c.marked + c.command, 0),
unmarked: counts.reduce((n, [, c]) => n + c.command, 0),
duplicates: counts.filter(([, c]) => c.marked + c.command > 1).map(([e]) => e),
unowned: counts.filter(([, c]) => c.unowned > 0).map(([e]) => e),
};
});
}