Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* hook-launcher.ts — the trusted-directory launcher that the per-turn hooks
* `gbrain setup <claude-code|codex>` and the turn-rule lane write run gbrain
* through (#8424).
*
* Why: the script-mode install (`bun install -g`, `bun link`) maps the
* `gbrain` bin to src/cli.ts, so Bun reads the working directory's
* bunfig.toml (a top-level `preload` runs before any gbrain code) and its
* .env files. Harnesses start hooks in the session's directory, so a hook
* that ran gbrain directly would run a cloned repository's code as the user
* on every prompt, with nothing for the user to approve.
*
* The launcher is a POSIX sh script at <config dir>/hook-launcher/gbrain-hook.
* It records the session directory in GBRAIN_HOOK_CWD, moves into its own
* directory and execs its arguments (the absolute gbrain binary and the hook
* subcommand) there. That directory holds only the launcher: when anything
* else is in it, the launcher refuses (exit 1, one stderr line) instead of
* starting Bun next to a file gbrain did not write. `gbrain hook` reads the
* session directory from GBRAIN_HOOK_CWD where it used process.cwd().
*
* The script-mode gbrain starts with `#!/usr/bin/env bun`, and a harness may
* start the launcher with a PATH that has no bun on it (the Codex desktop app,
* a GUI launcher), so the launcher of a script-mode install puts the directory
* of the Bun that wrote it first on PATH (GST-2784). A compiled gbrain needs no
* Bun, and its launcher stays the plain one.
*/
import { randomBytes } from 'node:crypto';
import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
import { basename, dirname, isAbsolute, join, win32 } from 'node:path';
import { configDir } from '../config.ts';
import { isScriptRuntime } from '../cli-preflight.ts';
import { msysToNativePath } from '../path-confine.ts';
export const HOOK_LAUNCHER_NAME = 'gbrain-hook';
export const HOOK_LAUNCHER_DIR = 'hook-launcher';
export const HOOK_LAUNCHER_SCRIPT = `#!/bin/sh
# gbrain hook launcher v1, written by gbrain setup (#8424); gbrain setup rewrites it.
# Bun reads bunfig.toml and .env from the working directory before gbrain runs,
# so hooks start gbrain from this directory, which holds only this file, and
# pass the session directory on in GBRAIN_HOOK_CWD.
GBRAIN_HOOK_CWD=$PWD
export GBRAIN_HOOK_CWD
case $0 in
/*/${HOOK_LAUNCHER_NAME}) d=\${0%/*} ;;
*) echo "gbrain hook launcher: run it by its absolute path, not $0" >&2; exit 1 ;;
esac
cd "$d" || exit 1
for f in * .*; do
case $f in .|..|${HOOK_LAUNCHER_NAME}) continue ;; esac
if [ -e "$f" ] || [ -L "$f" ]; then
echo "gbrain hook launcher: refused: $d holds $f, which gbrain did not write and Bun would read. Remove it, then run: gbrain doctor --only harness_wiring" >&2
exit 1
fi
done
exec "$@"
`;
const shellSingleQuote = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
const RUNTIME_LINE = /^PATH='((?:[^']|'\\'')*)':\$PATH$/m;
/** The launcher text: the plain one, or for a script-mode install the same with `runtimeDir` (a shell path) put first on PATH before gbrain starts. */
export function hookLauncherScript(runtimeDir: string | null): string {
if (runtimeDir === null) return HOOK_LAUNCHER_SCRIPT;
return HOOK_LAUNCHER_SCRIPT.replace('exec "$@"\n', () => `# gbrain runs under the Bun gbrain setup ran under, so a harness started without bun on PATH still starts it.
PATH=${shellSingleQuote(runtimeDir)}:$PATH
export PATH
exec "$@"
`);
}
const sameFile = (a: string, b: string) => { try { return realpathSync(a) === realpathSync(b); } catch { return false; } };
/**
* The directory of the Bun this gbrain runs under, as a hook shell path; null for a compiled gbrain, which needs none.
* The bun on PATH wins when it is this same Bun: execPath is the resolved file, which for Homebrew, mise or asdf sits in
* a per-version directory that a Bun upgrade deletes, while the PATH entry survives it.
*/
export function launcherRuntimeDir(searchPath?: string): string | null {
if (!isScriptRuntime() || typeof Bun === 'undefined') return null;
const self = /^bun(\.exe)?$/i.test(basename(process.execPath)) ? process.execPath : null;
const onPath = Bun.which('bun', searchPath === undefined ? undefined : { PATH: searchPath });
const bun = onPath && isAbsolute(onPath) && (self === null || sameFile(onPath, self)) ? onPath : self;
return bun ? hookShellPath(dirname(bun)) : null;
}
const bunIn = (dir: string) => join(msysToNativePath(dir), process.platform === 'win32' ? 'bun.exe' : 'bun');
/** The launcher path for an install whose config dir is `home` (default: this process's). */
export function hookLauncherPath(home: string = configDir()): string {
return join(home, HOOK_LAUNCHER_DIR, HOOK_LAUNCHER_NAME);
}
export type HookLauncherState = 'current' | 'missing' | 'stale' | 'foreign';
/**
* Files only. `foreign`: the launcher's directory holds something gbrain did not write, so the launcher refuses to run.
* `runtimeDir`: the Bun directory this gbrain needs (null for a compiled gbrain); a launcher that names a Bun that is
* gone, or none when one is needed, is stale.
*/
export function hookLauncherState(path: string, runtimeDir: string | null = launcherRuntimeDir()): { state: HookLauncherState; detail: string } {
let names: string[];
try { names = readdirSync(dirname(path)); } catch { return { state: 'missing', detail: `no hook launcher at ${path}` }; }
const other = names.find((n) => n !== HOOK_LAUNCHER_NAME);
if (other !== undefined) return { state: 'foreign', detail: `${dirname(path)} holds ${other}, which gbrain did not write, so the hook launcher refuses to start gbrain there` };
try {
const st = lstatSync(path);
if (!st.isFile()) return { state: 'stale', detail: `${path} is not a regular file` };
const text = readFileSync(path, 'utf8');
const recorded = RUNTIME_LINE.exec(text)?.[1]?.replace(/'\\''/g, "'") ?? null;
if (text !== hookLauncherScript(recorded)) return { state: 'stale', detail: `${path} differs from the launcher this gbrain writes` };
if ((st.mode & 0o100) === 0) return { state: 'stale', detail: `${path} is not executable` };
if (recorded !== null && !existsSync(bunIn(recorded))) return { state: 'stale', detail: `${path} starts gbrain with ${bunIn(recorded)}, which is no longer there, so a harness started without bun on PATH cannot start gbrain` };
if (recorded === null && runtimeDir !== null) return { state: 'stale', detail: `${path} does not record where bun is, so a harness started without bun on PATH (the Codex app, a GUI launcher) cannot start gbrain` };
} catch { return { state: 'missing', detail: `no hook launcher at ${path}` }; }
return { state: 'current', detail: `hook launcher ${path}` };
}
/**
* Write (or refresh) the launcher and return its path. Throws when its
* directory holds anything else: gbrain never deletes a file it did not write,
* and a hook routed through that directory would refuse anyway. A script-mode
* gbrain rewrites a launcher that records another Bun, so it starts under this one.
*/
export function ensureHookLauncher(path: string = hookLauncherPath(), runtimeDir: string | null = launcherRuntimeDir()): string {
const dir = dirname(path);
mkdirSync(dir, { recursive: true, mode: 0o700 });
chmodSync(dir, 0o700);
const other = readdirSync(dir).find((n) => n !== HOOK_LAUNCHER_NAME);
if (other !== undefined) throw new Error(`${dir} holds ${other}, which gbrain did not write; the hook launcher runs gbrain from that directory, so remove it, then run this again`);
if (hookLauncherState(path, runtimeDir).state === 'current' && (runtimeDir === null || readFileSync(path, 'utf8') === hookLauncherScript(runtimeDir))) return path;
// The temp file sits beside the directory, never in it: a hook running meanwhile would refuse to start next to it.
const tmp = join(dirname(dir), `.${HOOK_LAUNCHER_DIR}.tmp-${randomBytes(6).toString('hex')}`);
try {
writeFileSync(tmp, hookLauncherScript(runtimeDir), { mode: 0o700 });
chmodSync(tmp, 0o700);
renameSync(tmp, path);
} catch (e) {
rmSync(tmp, { force: true });
throw e;
}
return path;
}
/**
* Split a hook command into shell words the way /bin/sh would at its top
* level: single quotes, double quotes and backslash escapes, so a path the
* builders quoted (`'/a/o'\''b/x'`) comes back as the path. Null for an
* unterminated quote.
*/
export function shellWords(command: string): string[] | null {
const words: string[] = [];
let word: string | null = null;
for (let i = 0; i < command.length; i++) {
const c = command[i]!;
if (c === ' ' || c === '\t' || c === '\n') { if (word !== null) words.push(word); word = null; continue; }
word ??= '';
if (c === "'") {
const close = command.indexOf("'", i + 1);
if (close < 0) return null;
word += command.slice(i + 1, close);
i = close;
} else if (c === '"') {
let j = i + 1;
for (; j < command.length && command[j] !== '"'; j++) {
if (command[j] === '\\' && j + 1 < command.length && '$`"\\\n'.includes(command[j + 1]!)) j++;
word += command[j];
}
if (j >= command.length) return null;
i = j;
} else if (c === '\\' && i + 1 < command.length) {
word += command[++i];
} else {
word += c;
}
}
if (word !== null) words.push(word);
return words;
}
/** An absolute path (POSIX, or on Windows a drive or UNC path) shaped like a hook launcher (<config dir>/hook-launcher/gbrain-hook). */
export function isHookLauncherPath(path: string, platform: NodeJS.Platform = process.platform): boolean {
return (path.startsWith('/') || (platform === 'win32' && win32.isAbsolute(path))) && path.replace(/\\/g, '/').endsWith(`/${HOOK_LAUNCHER_DIR}/${HOOK_LAUNCHER_NAME}`);
}
/** A path as a hook command names it: Claude Code runs hooks through Git Bash on Windows, which (like the launcher's own check) wants /c/... for C:\... */
export function hookShellPath(path: string): string {
const drive = /^([A-Za-z]):[\\/](.*)$/.exec(path);
return drive ? `/${drive[1]!.toLowerCase()}/${drive[2]!.replace(/\\/g, '/')}` : path;
}
/** The launcher a hook command runs gbrain through, as a path this platform's file calls can read, or null for a command that starts gbrain in the session directory. */
export function hookLauncherInCommand(command: string, platform: NodeJS.Platform = process.platform): string | null {
const launcher = shellWords(command)?.find((word) => isHookLauncherPath(word, platform));
return launcher ? msysToNativePath(launcher, platform) : null;
}
export { HOOK_CWD_ENV, captureHookSessionCwd, hookSessionCwd } from '../session-cwd.ts';