Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* bootstrap/hooks.ts — Claude Code hook-settings writers + MCP registration
* argv builders (agent-bootstrap plan: G5, G1, CX2-17, CX-P1.4, ENG-7).
*
* settings.local.json has NO comment-marker boundary (it's JSON), so the
* managed-block idiom from frontmatter-install-hook.ts does not apply
* [CX2-17]. Instead this is a STRUCTURAL JSON merger: gbrain-owned hook
* entries are keyed by a `_gbrain` marker property on the command object
* (host-specs.ts owns the marker + every other format assumption), removal
* and dedupe match on the marker (surviving reordering and command-string
* drift), and foreign hooks / permissions / every other settings key are
* never touched. Writes are atomic (tmp + rename) with a `.bak` of the
* previous file; a parse-broken existing file ABORTS the write with
* fix-and-re-run instructions (fail-closed, matching removal's stance — a
* rewrite could drop permissions/allowlist entries gbrain cannot parse) [G5].
*
* MCP registration helpers BUILD ARGV ONLY — the bootstrap dispatcher execs
* them (and records the registration in the install receipt). Precedent:
* connect.ts `buildClaudeMcpAddArgv`/`buildCodexMcpAddArgv` [ENG-7] — those
* build the REMOTE-HTTP shape (`-t http <url>` + bearer token) and cannot
* express a local stdio serve with env bindings, so the local shape lives
* here rather than wrapping them. Env is explicit on the registration
* [CX-P1.4]: GUI-spawned serves inherit no shell env, so GBRAIN_SOURCE [G1]
* (and GBRAIN_HOME when isolated) ride the registration itself.
*/
import { createHash } from 'node:crypto';
import { copyFileSync, existsSync, readFileSync } from 'node:fs';
import { isAbsolute, join } from 'node:path';
import { atomicWriteTextFile } from './atomic-write.ts';
import { normalizeSeatLabel } from '../context/seat.ts';
import { detectExecutionEnvironment } from '../execution-env.ts';
import { stdioServeArgv } from '../mcp-registration.ts';
import { isHookLauncherPath } from '../setup/hook-launcher.ts';
import { SKILL_RESOLVER_MARKER } from '../setup/skill-resolver-lane.ts';
import type { McpSurface } from '../../mcp/surface.ts';
import type { HarnessReceipt, HarnessTarget } from './format.ts';
import {
CLAUDE_COMMITTED_SETTINGS_FILE_RELPATH,
CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS,
CLAUDE_HOOK_EVENTS,
CLAUDE_HOOK_SUBCOMMAND,
CLAUDE_SETTINGS_FILE_RELPATH,
GBRAIN_HARNESS_MARKER_VALUE,
GBRAIN_HOOK_MARKER_KEY,
GBRAIN_HOOK_MARKER_VALUE,
type ClaudeHookEvent,
} from './host-specs.ts';
// ── Types ───────────────────────────────────────────────────────────────────
/** Env vars embedded in each hook command string [G1, CX-P1.4]. */
export interface ClaudeHookEnv {
/** Workspace source binding so hook context is source-scoped [G1]. Omitted
* ONLY by the harness lane when a live PGLite serve hides which source it
* resolves: an unpinned hook names no source, so the serve answers with its
* own binding instead of rejecting a wrong claim as `source_mismatch`. The
* committed carrier (buildPortableClaudeHookCommand) always requires it. */
GBRAIN_SOURCE?: string;
/** Set only for --isolated installs (PARENT dir; config appends `.gbrain`). */
GBRAIN_HOME?: string;
/**
* 'harness' on #4043 harness-mode wiring: `gbrain hook` yields when the
* lane is harness AND the cwd carries a workspace bootstrap install, so
* the same event never fires twice (Claude Code merges settings scopes).
*/
GBRAIN_HOOK_LANE?: string;
/**
* #4618 seat label credited on captured sessions (`--seat`). Undefined
* keeps the seat a prior install of the same marker rendered; '' clears it
* (`--no-seat`). Local carriers only: the committed carrier travels between
* machines and never carries a seat.
*/
GBRAIN_SEAT?: string;
}
export interface WriteClaudeHooksOpts {
/** Absolute path to the gbrain binary (GUI hosts inherit no PATH) [CX-P1.4]. */
gbrainBin: string;
/** Absolute trusted-directory launcher each command starts gbrain through (src/core/setup/hook-launcher.ts). */
hookLauncher?: string;
env: ClaudeHookEnv;
/** Per-event timeout override (SECONDS — the settings-file unit). */
timeoutSecs?: Partial<Record<ClaudeHookEvent, number>>;
/** Subset of events to wire; default every event in CLAUDE_HOOK_EVENTS. */
events?: ClaudeHookEvent[];
/**
* Marker VALUE stamped on (and stripped from) our entries. Default is the
* workspace-install marker; harness mode passes GBRAIN_HARNESS_MARKER_VALUE
* so the two installs coexist and each removal strips only its own.
*/
marker?: string;
/**
* [D12] Events already owned by the COMMITTED settings carrier — the writer
* strips stale local copies of these but re-adds nothing for them, so one
* event never fires from both files. The workspace wrapper derives it from
* committedHookEvents(ws); path-parameterized callers pass their own.
*/
carriedEvents?: Set<ClaudeHookEvent>;
/**
* Backup strategy for the pre-write copy. 'fixed' (default) keeps the
* historical `.bak` sibling; 'timestamped' avoids the shared-slot problem
* when two writers touch the same file in one transaction.
*/
backupStrategy?: 'fixed' | 'timestamped';
/**
* Refuse when a gbrain entry with a DIFFERENT marker already wires one of
* our target events in this file (harness lane: a workspace install or a
* differently-scoped harness install owns it — double-wiring would fire the
* same hook twice per event) [C6].
*/
refuseOnForeignGbrainMarker?: boolean;
/**
* Mode for a FRESHLY-CREATED settings file (existing files keep their mode
* via the atomic writer). Harness user-scope writes pass 0o600 to match
* Claude Code's own convention for that file [X11].
*/
freshMode?: number;
/**
* Harness lane: unmarked entries whose command is exactly this identity's
* harness hook are replaced like marked ones (the host can drop the marker
* key); harness-looking entries outside it survive and get a note.
*/
identity?: HarnessHookIdentity;
/**
* Hash-keyed ownership (`gbrain setup`): when set, an entry is ours only
* when its `hookEntryHash` is in this set. A marker match alone never
* replaces or removes an entry, so a user-edited marked hook survives and
* is listed in `preserved`; an unmarked entry with an owned hash (the host
* dropped the marker) is still ours.
*/
ownedEntryHashes?: ReadonlySet<string>;
}
export interface WriteClaudeHooksResult {
settingsPath: string;
installed: Array<{ event: ClaudeHookEvent; command: string }>;
/** Prior marker-carrying entries replaced (idempotent re-run dedupe). */
removedPrior: number;
/** `.bak` of the pre-write file (null when no file existed). */
backupPath: string | null;
/** Always null since the fail-closed change (a parse-broken file now
* aborts the write instead of being moved aside). Kept for result-shape
* stability. */
brokenBackupPath: string | null;
notes: string[];
/** Seat label rendered into the new commands ('' for none). */
seat: string;
/** With `ownedEntryHashes`: marked entries kept because their hash is not owned. */
preserved: Array<{ event: string; hash: string }>;
}
export interface RemoveClaudeHooksResult {
settingsPath: string;
/** Entries removed (marked plus unmarked-but-ours). */
removed: number;
backupPath: string | null;
notes: string[];
/** Unmarked entries removed because their command is this install's harness hook. */
unmarked: Array<{ event: string; why: string }>;
/** Events holding a harness-looking entry that is not this install's; never deleted. */
unowned: string[];
/** With `ownedEntryHashes`: marked entries kept because their hash is not owned. */
preserved: Array<{ event: string; hash: string }>;
}
/** Who may claim an UNMARKED harness hook entry: the launchers, sources and
* seats this install (or its harness receipt) rendered. A `null` source is an
* unpinned hook (no GBRAIN_SOURCE); `seats` undefined accepts any seat label
* (the receipt recorded none). */
export interface HarnessHookIdentity {
launchers: string[];
sources: Array<string | null>;
seats?: string[];
}
export type HarnessHookOwnership = 'marked' | 'command' | 'unowned';
/** One command object inside a hook matcher group (host-specs shape). */
interface HookCommandEntry {
type: 'command';
command: string;
timeout?: number;
[key: string]: unknown;
}
interface HookMatcherGroup {
matcher?: string;
hooks?: unknown[];
[key: string]: unknown;
}
type SettingsObject = Record<string, unknown>;
// ── Helpers ─────────────────────────────────────────────────────────────────
export function claudeSettingsPath(workspaceDir: string): string {
return join(workspaceDir, CLAUDE_SETTINGS_FILE_RELPATH);
}
/**
* The ownership hash of one hook command entry: sha256 over its `type`,
* `command` and `timeout`, the keys the host keeps when it rewrites the
* file. The `_gbrain` marker and any other key are excluded, so a dropped
* marker keeps the hash and an edited command or timeout changes it. Null
* for anything that is not a command entry.
*/
export function hookEntryHash(entry: unknown): string | null {
if (typeof entry !== 'object' || entry === null) return null;
const e = entry as Record<string, unknown>;
if (e.type !== 'command' || typeof e.command !== 'string') return null;
return createHash('sha256').update(JSON.stringify([e.type, e.command, e.timeout ?? null])).digest('hex');
}
/**
* POSIX single-quote anything not already shell-safe (mirror of connect.ts's
* private shellQuote — same contract: `$()`/backticks in a value are inert
* literals). `=` is in the safe set so plain `K=V` env assignments stay bare.
*/
function shellQuote(arg: string): string {
if (/^[A-Za-z0-9_.:/@=-]+$/.test(arg)) return arg;
return `'${arg.replace(/'/g, "'\\''")}'`;
}
/** Render the hook command string: `env K=V… [<launcher>] <bin> hook <subcommand>`.
* `launcher` is the trusted-directory hook launcher (src/core/setup/hook-launcher.ts)
* the setup and turn-rule lanes start gbrain through. The harness lane
* recognizes its unmarked entries by parsing exactly this shape back
* (parseClaudeHookCommand), so the two change together. */
export function buildClaudeHookCommand(
gbrainBin: string,
event: ClaudeHookEvent,
env: ClaudeHookEnv,
launcher?: string,
): string {
const assignments: string[] = [];
if (env.GBRAIN_SOURCE !== undefined) assignments.push(`GBRAIN_SOURCE=${env.GBRAIN_SOURCE}`);
if (env.GBRAIN_HOME) assignments.push(`GBRAIN_HOME=${env.GBRAIN_HOME}`);
if (env.GBRAIN_HOOK_LANE) assignments.push(`GBRAIN_HOOK_LANE=${env.GBRAIN_HOOK_LANE}`);
if (env.GBRAIN_SEAT) assignments.push(`GBRAIN_SEAT=${env.GBRAIN_SEAT}`);
const parts = ['env', ...assignments, ...(launcher ? [launcher] : []), gbrainBin, 'hook', CLAUDE_HOOK_SUBCOMMAND[event]];
return parts.map(shellQuote).join(' ');
}
const HOOK_ENV_KEYS: ReadonlySet<string> = new Set(['GBRAIN_SOURCE', 'GBRAIN_HOME', 'GBRAIN_HOOK_LANE', 'GBRAIN_SEAT']);
/**
* The inverse of buildClaudeHookCommand: `env K=V… [<abs launcher>] <abs bin> hook <sub>` with
* nothing before or after, words split the way shellQuote joins them, env keys
* limited to the ones the builder writes (each at most once), and a final
* check that re-rendering the parse yields the exact input. Null for anything
* else (an appended pipe, an extra flag, hand quoting, a relative launcher).
*/
export function parseClaudeHookCommand(command: string): { gbrainBin: string; subcommand: string; env: ClaudeHookEnv; launcher?: string } | null {
const words: string[] = [];
const word = /([A-Za-z0-9_.:/@=-]+|'(?:[^']|'\\'')*')(?: |$)/y;
while (word.lastIndex < command.length) {
const m = word.exec(command);
if (!m) return null;
words.push(m[1]!.startsWith("'") ? m[1]!.slice(1, -1).replace(/'\\''/g, "'") : m[1]!);
}
if (words[0] !== 'env' || words.length < 4) return null;
const env: Record<string, string> = {};
let i = 1;
for (; i < words.length - 3; i++) {
const eq = words[i]!.indexOf('=');
if (eq < 0) break;
const key = words[i]!.slice(0, eq);
if (!HOOK_ENV_KEYS.has(key) || key in env) return null;
env[key] = words[i]!.slice(eq + 1);
}
const rest = words.slice(i);
const launcher = rest.length === 4 ? rest.shift()! : undefined;
const [gbrainBin, verb, subcommand] = rest as [string, string, string];
if (rest.length !== 3 || verb !== 'hook' || !isAbsolute(gbrainBin) || (launcher !== undefined && !isAbsolute(launcher))) return null;
const event = CLAUDE_HOOK_EVENTS.find((e) => CLAUDE_HOOK_SUBCOMMAND[e] === subcommand);
if (!event || buildClaudeHookCommand(gbrainBin, event, env, launcher) !== command) return null;
return { gbrainBin, subcommand, env, ...(launcher ? { launcher } : {}) };
}
/**
* Harness-lane ownership of one hook entry under `event`. Claude Code drops
* keys it does not know when it rewrites settings.json, so the `_gbrain`
* marker is advisory there and the command is the durable carrier:
* - `marked`: the entry carries the harness marker.
* - `command`: no marker key, the command is exactly the harness hook this
* event runs, and its launcher, source and seat belong to `identity` (with
* no GBRAIN_HOME: the harness lane never renders one). `'any'` skips the
* identity check, for guards that only ask whether a harness hook exists.
* - `unowned`: no marker key and it looks like a harness hook (lane token +
* `hook`) under an event gbrain wires, but it was edited or belongs to
* another install. Never deleted.
* Null for everything else (other markers, foreign hooks, events gbrain does
* not wire). `why` names the match, never the command text.
*/
export function classifyHarnessHook(
entry: unknown,
event: string,
identity: HarnessHookIdentity | 'any',
): { ownership: HarnessHookOwnership; why: string } | null {
if (typeof entry !== 'object' || entry === null) return null;
const e = entry as Record<string, unknown>;
if (e[GBRAIN_HOOK_MARKER_KEY] === GBRAIN_HARNESS_MARKER_VALUE) return { ownership: 'marked', why: 'carries the harness marker' };
if (Object.prototype.hasOwnProperty.call(e, GBRAIN_HOOK_MARKER_KEY) || typeof e.command !== 'string') return null;
const sub = (CLAUDE_HOOK_SUBCOMMAND as Record<string, string | undefined>)[event];
if (!sub || !/(?:^|[\s'])GBRAIN_HOOK_LANE=harness(?=[\s']|$)/.test(e.command) || !/\shook(?:\s|$)/.test(e.command)) return null;
const parsed = parseClaudeHookCommand(e.command);
if (!parsed || (parsed.launcher !== undefined && !isHookLauncherPath(parsed.launcher)) || parsed.env.GBRAIN_HOOK_LANE !== 'harness' || parsed.subcommand !== sub) {
return { ownership: 'unowned', why: `not the exact \`hook ${sub}\` command gbrain writes (edited or extended)` };
}
if (identity === 'any') return { ownership: 'command', why: 'harness hook command shape' };
if (parsed.env.GBRAIN_HOME !== undefined) return { ownership: 'unowned', why: 'carries GBRAIN_HOME, which this install never writes' };
if (!identity.launchers.includes(parsed.gbrainBin)) return { ownership: 'unowned', why: 'its launcher is not this install\'s' };
const source = parsed.env.GBRAIN_SOURCE ?? null;
if (!identity.sources.includes(source)) return { ownership: 'unowned', why: 'its source is not this install\'s' };
if (identity.seats && !identity.seats.includes(parsed.env.GBRAIN_SEAT ?? '')) return { ownership: 'unowned', why: 'its seat is not this install\'s' };
return {
ownership: 'command',
why: `no _gbrain marker; exact \`hook ${sub}\` command with this install's launcher and ${source === null ? 'no source pin' : `source '${source}'`}`,
};
}
/**
* The identity an unmarked harness entry must match: the current install's
* launcher/source/seat plus what the receipt recorded for `target` (its
* launcher and seat) and the receipt's source binding. Seats constrain only
* when the receipt recorded one.
*/
export function harnessHookIdentity(
receipt: Pick<HarnessReceipt, 'source_id' | 'source_pinned'> | null,
target: Pick<HarnessTarget, 'launcher' | 'seat'> | undefined,
current: { launcher?: string | null; source?: string | null; seat?: string },
): HarnessHookIdentity {
const launchers = [current.launcher, target?.launcher].filter((l): l is string => typeof l === 'string' && l !== '');
const sources: Array<string | null> = [];
if (current.source !== undefined) sources.push(current.source);
if (receipt) sources.push(receipt.source_pinned === false ? null : receipt.source_id);
if (target?.seat === undefined) return { launchers, sources };
return { launchers, sources, seats: [target.seat, ...(current.seat !== undefined ? [current.seat] : [])] };
}
/**
* `--seat <label>` / `--no-seat` → the hook env's GBRAIN_SEAT: the validated
* label, '' to clear a carried seat, or undefined to keep the installed one.
* With the workspace lane's `harness`, `note` says where a seat cannot be
* rendered into a hook command and how to set it instead.
*/
export function parseSeatFlags(rest: string[], harness?: string): { seat?: string; error?: string; note?: string } {
const noSeat = rest.includes('--no-seat');
const i = rest.indexOf('--seat');
if (i < 0) return noSeat ? { seat: '' } : {};
if (noSeat) return { error: 'pass --seat <label> OR --no-seat, not both' };
const raw = rest[i + 1];
const seat = raw === undefined || raw.startsWith('--') ? null : normalizeSeatLabel(raw);
if (seat === null) {
return {
error:
`invalid --seat '${raw ?? ''}': a seat label is 1-64 characters of a-z, 0-9, '.', '_' or '-', ` +
'starting with a letter or digit — re-run with a valid label, e.g. `--seat alice-desk`',
};
}
if (harness === 'codex') {
return { seat, note: `note: --seat applies to Claude Code hooks; codex sessions are credited to their CODEX_HOME seat (home-<hash>) unless GBRAIN_SEAT=${seat} is set in the environment codex runs in.` };
}
if (harness === 'opencode') return { seat, note: 'note: --seat has no effect for opencode — gbrain installs no opencode session-capture hooks.' };
if (harness === 'claude-code' && detectExecutionEnvironment() === 'cloud-sandbox') {
return { seat, note: `note: --seat is not written to the COMMITTED hook carrier (it travels with the repo) — set GBRAIN_SEAT=${seat} in this cloud environment's variables instead.` };
}
return { seat };
}
/** The seat a prior install of `marker` rendered into this file's hook
* commands: marked entries first, then unmarked entries `identity` owns. */
function installedSeat(hooks: Record<string, unknown>, marker: string, identity?: HarnessHookIdentity): string | undefined {
for (const claim of identity ? ['marked', 'command'] : ['marked']) {
for (const [event, groups] of Object.entries(hooks)) {
if (!Array.isArray(groups)) continue;
for (const group of groups) {
const entries = (group as HookMatcherGroup)?.hooks;
if (!Array.isArray(entries)) continue;
for (const entry of entries) {
const ours = claim === 'marked' ? isOurs(entry, marker) : classifyHarnessHook(entry, event, identity!)?.ownership === 'command';
if (!ours || typeof (entry as HookCommandEntry).command !== 'string') continue;
const m = /(?:^| )GBRAIN_SEAT=([a-z0-9][a-z0-9._-]{0,63})(?= )/.exec((entry as HookCommandEntry).command);
if (m) return m[1];
}
}
}
}
return undefined;
}
export function claudeCommittedSettingsPath(workspaceDir: string): string {
return join(workspaceDir, CLAUDE_COMMITTED_SETTINGS_FILE_RELPATH);
}
/**
* The COMMITTED carrier's command [D12]: PATH-resolved and fail-open. No
* absolute binary path — the committed file travels between machines and
* cloud sessions; wherever gbrain is not installed the hook exits 0 silently
* instead of erroring every turn.
*/
export function buildPortableClaudeHookCommand(event: ClaudeHookEvent, env: ClaudeHookEnv): string {
if (env.GBRAIN_SOURCE === undefined) {
throw new Error('the committed hook carrier must be source-scoped [G1] — GBRAIN_SOURCE is required');
}
const assignments: string[] = [`GBRAIN_SOURCE=${env.GBRAIN_SOURCE}`];
if (env.GBRAIN_HOME) assignments.push(`GBRAIN_HOME=${env.GBRAIN_HOME}`);
const invoke = ['env', ...assignments, 'gbrain', 'hook', CLAUDE_HOOK_SUBCOMMAND[event]]
.map(shellQuote)
.join(' ');
return `command -v gbrain >/dev/null 2>&1 && ${invoke} || exit 0`;
}
/** Events the COMMITTED settings file already carries with our marker [D12]
* — the local writer skips these so one event never fires from both files. */
/** Pull the GBRAIN_SOURCE value out of a rendered portable hook command so the
* exact-match check is agnostic to the (operator-chosen) source id. Returns
* null when the command isn't shaped like ours. */
function extractHookSource(command: string): string | null {
const m = /command -v gbrain >\/dev\/null 2>&1 && env GBRAIN_SOURCE=('[^']*'|[^ ]+) gbrain hook /.exec(command);
if (!m) return null;
const raw = m[1]!;
return raw.startsWith("'") ? raw.slice(1, -1).replace(/'\\''/g, "'") : raw;
}
export function committedHookEvents(workspaceDir: string): Set<ClaudeHookEvent> {
const carried = new Set<ClaudeHookEvent>();
try {
const raw = readFileSync(claudeCommittedSettingsPath(workspaceDir), 'utf8');
const parsed = JSON.parse(raw) as { hooks?: Record<string, unknown> };
const hooks = parsed?.hooks;
if (typeof hooks !== 'object' || hooks === null) return carried;
for (const event of CLAUDE_HOOK_EVENTS) {
const groups = (hooks as Record<string, unknown>)[event];
if (!Array.isArray(groups)) continue;
const ours = groups.some(
(g) =>
typeof g === 'object' && g !== null &&
Array.isArray((g as HookMatcherGroup).hooks) &&
((g as HookMatcherGroup).hooks as unknown[]).some(
(h) =>
isOurs(h) &&
// A committed file is repo-contributor-writable: a marker + a
// bare `includes('gbrain hook')` substring is spoofable
// (`evil; # gbrain hook` suppresses the real local install AND
// runs attacker code). Require the EXACT portable-command shape
// this event would render — the anchored `command -v gbrain …`
// guard + `|| exit 0` structure a foreign command can't fake.
typeof (h as HookCommandEntry).command === 'string' &&
(h as HookCommandEntry).command === buildPortableClaudeHookCommand(event, {
GBRAIN_SOURCE: extractHookSource((h as HookCommandEntry).command as string) ?? '',
}),
),
);
if (ours) carried.add(event);
}
} catch {
/* absent/corrupt committed file → nothing carried */
}
return carried;
}
function isOurs(entry: unknown, marker: string = GBRAIN_HOOK_MARKER_VALUE): boolean {
return (
typeof entry === 'object' &&
entry !== null &&
(entry as Record<string, unknown>)[GBRAIN_HOOK_MARKER_KEY] === marker
);
}
/** True when the entry carries the gbrain marker KEY with any OTHER value (the skill-resolver lane's never double-fires a context hook, so it never counts). */
function isForeignGbrainMarked(entry: unknown, marker: string): boolean {
if (typeof entry !== 'object' || entry === null) return false;
const v = (entry as Record<string, unknown>)[GBRAIN_HOOK_MARKER_KEY];
return typeof v === 'string' && v !== marker && v !== SKILL_RESOLVER_MARKER;
}
/**
* Strip marker-carrying command entries from one event's matcher-group array.
* Groups EMPTIED by the removal are dropped; groups that were already empty
* (foreign) survive untouched. Returns the surviving groups + removal count.
* The group-drop rule is marker-independent: it fires only when THIS call's
* filter emptied a previously non-empty group, so it can never drop a group a
* different marker still owns.
*/
function stripOurEntries(
groups: unknown[],
marker: string = GBRAIN_HOOK_MARKER_VALUE,
owned?: { event: string; identity: HarnessHookIdentity },
ownedHashes?: ReadonlySet<string>,
): { kept: unknown[]; removed: number; unmarked: string[]; unowned: number; preserved: string[] } {
const kept: unknown[] = [];
let removed = 0;
const unmarked: string[] = [];
let unowned = 0;
const preserved: string[] = [];
for (const group of groups) {
if (typeof group !== 'object' || group === null || !Array.isArray((group as HookMatcherGroup).hooks)) {
kept.push(group); // structurally foreign — never touch
continue;
}
const g = group as HookMatcherGroup;
const before = g.hooks!.length;
const filtered = g.hooks!.filter((h) => {
if (ownedHashes) {
const hash = hookEntryHash(h);
if (hash !== null && ownedHashes.has(hash)) return false;
if (hash !== null && isOurs(h, marker)) preserved.push(hash);
return true;
}
if (isOurs(h, marker)) return false;
if (!owned) return true;
const c = classifyHarnessHook(h, owned.event, owned.identity);
if (c?.ownership === 'unowned') unowned++;
if (c?.ownership !== 'command') return true;
unmarked.push(c.why);
return false;
});
removed += before - filtered.length;
if (filtered.length === 0 && before > 0 && filtered.length !== before) {
continue; // we emptied it → drop the husk
}
if (filtered.length !== before) {
kept.push({ ...g, hooks: filtered });
} else {
kept.push(group);
}
}
return { kept, removed, unmarked, unowned, preserved };
}
/**
* Atomic write (tmp + rename), creating parent dirs. Hardened for shared
* user-scope targets [C10]: the SYMLINK TARGET is resolved first so a
* dotfile-manager-linked settings file survives as a link (a bare rename
* would replace the link with a regular file); the tmp file uses a random
* suffix and inherits the existing file's mode (a 0600 file stays 0600 —
* the pid-suffixed umask-default tmp was fine for gitignored workspace files
* but not for user-global config).
*/
function atomicWriteJson(path: string, value: unknown, freshMode?: number): void {
// Shared bootstrap atomic writer (symlink-resolving, mode-inheriting) —
// fresh files take the caller's convention (user-scope → 0600) [X11].
atomicWriteTextFile(path, `${JSON.stringify(value, null, 2)}\n`, { freshMode });
}
/** Pre-write backup path per strategy; timestamped avoids the shared-slot loss. */
function backupPathFor(settingsPath: string, strategy: 'fixed' | 'timestamped'): string {
return strategy === 'timestamped' ? `${settingsPath}.bak-${Date.now()}` : `${settingsPath}.bak`;
}
interface LoadedSettings {
settings: SettingsObject;
existed: boolean;
brokenBackupPath: string | null;
notes: string[];
}
/**
* Parse the existing settings file. Absent/empty → `{}`. Parse error →
* THROW, fail-closed [G5]: the file may carry permissions/allowlist entries
* gbrain cannot see, so replacing it with a fresh file (the old behavior —
* backup + start clean) silently dropped the user's live settings. Removal
* (`removeClaudeHooks`) already refuses to touch what it cannot parse; the
* write path now matches that stance. The user fixes the JSON, re-runs, and
* the structural merge preserves everything.
*/
function loadSettings(path: string): LoadedSettings {
const notes: string[] = [];
if (!existsSync(path)) {
return { settings: {}, existed: false, brokenBackupPath: null, notes };
}
let raw: string;
try {
raw = readFileSync(path, 'utf8');
} catch (e) {
throw new Error(`cannot read ${path}: ${(e as Error).message}`);
}
if (raw.trim() === '') {
return { settings: {}, existed: true, brokenBackupPath: null, notes };
}
try {
const parsed = JSON.parse(raw) as unknown;
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
throw new Error('settings root is not a JSON object');
}
return { settings: parsed as SettingsObject, existed: true, brokenBackupPath: null, notes };
} catch (e) {
throw new Error(
`${path} is not valid JSON (${(e as Error).message}) — refusing to rewrite a settings file ` +
`gbrain cannot parse (it may carry your permissions/allowlist entries). Fix the JSON by ` +
`hand, then re-run \`gbrain bootstrap hooks --harness claude-code --repair\` ` +
`(the structural merge preserves your settings).`,
);
}
}
// ── Writers [G5, CX2-17] ────────────────────────────────────────────────────
/**
* Structural-merge gbrain's hook entries into an EXPLICIT settings file
* (workspace settings.local.json or user-scope ~/.claude/settings.json).
* Idempotent: prior same-marker entries are removed before the fresh set is
* appended (run twice → one entry per event). Foreign hooks, other-marker
* gbrain entries, permissions, and every other key survive byte-for-byte at
* the structural level.
*/
export function writeClaudeHooksAt(
settingsPath: string,
opts: WriteClaudeHooksOpts,
): WriteClaudeHooksResult {
if (!isAbsolute(opts.gbrainBin)) {
throw new Error(`gbrainBin must be an absolute path (GUI hosts inherit no PATH); got: ${opts.gbrainBin}`);
}
for (const [k, v] of Object.entries(opts.env)) {
if (typeof v === 'string' && /[\n\r\0]/.test(v)) {
throw new Error(`env ${k} contains control characters — refusing to embed in a hook command`);
}
}
const marker = opts.marker ?? GBRAIN_HOOK_MARKER_VALUE;
const backupStrategy = opts.backupStrategy ?? 'fixed';
const { settings, existed, brokenBackupPath, notes } = loadSettings(settingsPath);
// hooks key: merge into an object; a structurally-foreign value is backed
// up via the .bak below and replaced (we cannot merge into a non-object).
let hooks = settings.hooks as Record<string, unknown> | undefined;
if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
if (hooks !== undefined) {
notes.push(
`WARNING: existing "hooks" key was not an object (${JSON.stringify(hooks).slice(0, 80)}); ` +
`replaced — the original file is in the .bak backup.`,
);
}
hooks = {};
}
const events = opts.events ?? [...CLAUDE_HOOK_EVENTS];
// [C6] Same command double-fire guard: refuse when a gbrain entry carrying a
// DIFFERENT marker already wires one of our target events in this file —
// Claude Code would run both.
if (opts.refuseOnForeignGbrainMarker) {
for (const event of events) {
const groups = hooks[event];
if (!Array.isArray(groups)) continue;
for (const group of groups) {
const g = group as HookMatcherGroup;
if (!Array.isArray(g?.hooks)) continue;
for (const entry of g.hooks) {
if (isForeignGbrainMarked(entry, marker)) {
const foreign = (entry as Record<string, unknown>)[GBRAIN_HOOK_MARKER_KEY];
throw new Error(
`${settingsPath} already wires hooks.${event} under gbrain marker "${String(foreign)}" — ` +
`refusing to double-wire the same hook (both entries would fire every event). ` +
`Remove the other install first (gbrain bootstrap harness --remove, or gbrain bootstrap uninstall).`,
);
}
}
}
}
}
// [D12] Dedupe invariant: an event carried by the COMMITTED settings file
// never also fires from the local file. The caller supplies the carried set
// (the workspace wrapper reads it from committedHookEvents(ws); the harness
// --project lane does the same for its dirs) — this path-parameterized
// writer has no workspace to derive it from.
const carried = opts.carriedEvents ?? new Set<ClaudeHookEvent>();
// #4618: a re-install without --seat keeps the seat the prior install chose.
const env = opts.env.GBRAIN_SEAT === undefined
? { ...opts.env, GBRAIN_SEAT: installedSeat(hooks, marker, opts.identity) }
: opts.env;
let removedPrior = 0;
const installed: Array<{ event: ClaudeHookEvent; command: string }> = [];
const preserved: Array<{ event: string; hash: string }> = [];
// [X3] Convergence: strip OUR marker from EVERY event in the file first —
// not just the requested subset — so a re-run with fewer events (e.g.
// --no-capture dropping Stop/SessionEnd) removes the ones no longer wanted
// instead of leaving them live. Foreign and other-marker entries survive.
for (const event of Object.keys(hooks)) {
const groups = hooks[event];
if (!Array.isArray(groups)) continue; // structurally foreign — never touch
const { kept, removed, unowned, preserved: kept_ } = stripOurEntries(groups, marker, opts.identity && { event, identity: opts.identity }, opts.ownedEntryHashes);
preserved.push(...kept_.map((hash) => ({ event, hash })));
removedPrior += removed;
if (unowned > 0) {
notes.push(
`hooks.${event} in ${settingsPath} holds an entry that looks like gbrain's harness hook but is not this install's ` +
`exact command (code harness_hook_unowned); left in place — if it is a leftover it fires next to the new entry, so delete it by hand.`,
);
}
if (removed === 0) continue;
if (kept.length === 0) {
delete hooks[event]; // emptied by OUR removal — drop the key
} else {
hooks[event] = kept;
}
}
for (const event of events) {
let groups = hooks[event];
if (!Array.isArray(groups)) {
if (groups !== undefined) {
notes.push(
`WARNING: existing hooks.${event} was not an array; replaced — original in the .bak backup.`,
);
}
groups = [];
}
const kept = [...(groups as unknown[])];
if (carried.has(event)) {
notes.push(`${event}: carried by the committed .claude/settings.json — local entry skipped [D12]`);
if (kept.length === 0) delete hooks[event];
else hooks[event] = kept;
continue;
}
const command = buildClaudeHookCommand(opts.gbrainBin, event, env, opts.hookLauncher);
const timeout = opts.timeoutSecs?.[event] ?? CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS[event];
const entry: HookCommandEntry = {
type: 'command',
command,
timeout,
[GBRAIN_HOOK_MARKER_KEY]: marker,
};
kept.push({ hooks: [entry] });
hooks[event] = kept;
installed.push({ event, command });
}
settings.hooks = hooks;
let backupPath: string | null = null;
if (existed && brokenBackupPath === null) {
backupPath = backupPathFor(settingsPath, backupStrategy);
copyFileSync(settingsPath, backupPath);
}
atomicWriteJson(settingsPath, settings, opts.freshMode);
return { settingsPath, installed, removedPrior, backupPath, brokenBackupPath, notes, seat: env.GBRAIN_SEAT ?? '', preserved };
}
/**
* Workspace-lane wrapper (historical signature: `<ws>/.claude/settings.local.json`,
* bootstrap-v1 marker, fixed `.bak`). Supplies the [D12] carried-events set so
* an event owned by the committed carrier never also fires locally.
*/
export function writeClaudeHooks(
workspaceDir: string,
opts: WriteClaudeHooksOpts,
): WriteClaudeHooksResult {
return writeClaudeHooksAt(claudeSettingsPath(workspaceDir), {
carriedEvents: committedHookEvents(workspaceDir),
...opts,
});
}
/**
* Write hooks into the COMMITTED `.claude/settings.json` [D12] — the only
* carrier that survives into fresh cloud clones (hooks are snapshotted at
* session start; the gitignored local file never exists there). Commands are
* PATH-resolved and fail-open (buildPortableClaudeHookCommand). After the
* committed write, the same events are stripped from the LOCAL file so an
* event never fires from both carriers.
*/
export function writeCommittedClaudeHooks(
workspaceDir: string,
opts: { env: ClaudeHookEnv; events?: ClaudeHookEvent[]; timeoutSecs?: Partial<Record<ClaudeHookEvent, number>> },
): WriteClaudeHooksResult {
if (opts.env.GBRAIN_HOME) {
throw new Error(
'GBRAIN_HOME is machine-specific and must not be embedded in the COMMITTED hook carrier ' +
'(the file travels between machines) — isolated installs stay on the local carrier',
);
}
for (const [k, v] of Object.entries(opts.env)) {
if (typeof v === 'string' && /[\n\r\0]/.test(v)) {
throw new Error(`env ${k} contains control characters — refusing to embed in a hook command`);
}
}
const settingsPath = claudeCommittedSettingsPath(workspaceDir);
const { settings, existed, brokenBackupPath, notes } = loadSettings(settingsPath);
let hooks = settings.hooks as Record<string, unknown> | undefined;
if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
if (hooks !== undefined) {
notes.push(
`WARNING: existing "hooks" key was not an object (${JSON.stringify(hooks).slice(0, 80)}); ` +
`replaced — the original file is in the .bak backup.`,
);
}
hooks = {};
}
const events = opts.events ?? [...CLAUDE_HOOK_EVENTS];
let removedPrior = 0;
const installed: Array<{ event: ClaudeHookEvent; command: string }> = [];
for (const event of events) {
let groups = hooks[event];
if (!Array.isArray(groups)) {
if (groups !== undefined) {
notes.push(`WARNING: existing hooks.${event} was not an array; replaced — original in the .bak backup.`);
}
groups = [];
}
const { kept, removed } = stripOurEntries(groups as unknown[]);
removedPrior += removed;
const command = buildPortableClaudeHookCommand(event, opts.env);
const timeout = opts.timeoutSecs?.[event] ?? CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS[event];
const entry: HookCommandEntry = {
type: 'command',
command,
timeout,
[GBRAIN_HOOK_MARKER_KEY]: GBRAIN_HOOK_MARKER_VALUE,
};
kept.push({ hooks: [entry] });
hooks[event] = kept;
installed.push({ event, command });
}
settings.hooks = hooks;
let backupPath: string | null = null;
if (existed && brokenBackupPath === null) {
backupPath = `${settingsPath}.bak`;
copyFileSync(settingsPath, backupPath);
}
atomicWriteJson(settingsPath, settings);
// [D12] dedupe: the committed carrier now owns these events — remove any
// local copies so nothing double-fires on this machine.
const localCleanup = removeClaudeHooksAt(claudeSettingsPath(workspaceDir));
if (localCleanup.removed > 0) {
notes.push(
`removed ${localCleanup.removed} local settings.local.json entr${localCleanup.removed === 1 ? 'y' : 'ies'} — the committed carrier owns the events now [D12]`,
);
}
return { settingsPath, installed, removedPrior, backupPath, brokenBackupPath, notes, seat: '', preserved: [] };
}
/**
* Remove ONLY entries carrying the given marker [G5]. A parse-broken file is
* left untouched (removal must never destroy what it cannot read) — the note
* says so. Event arrays we emptied lose their key; an emptied hooks object
* loses its key; foreign structure (including other-marker gbrain entries)
* survives.
*/
export function removeClaudeHooksAt(
settingsPath: string,
marker: string = GBRAIN_HOOK_MARKER_VALUE,
opts: { identity?: HarnessHookIdentity; dryRun?: boolean; ownedEntryHashes?: ReadonlySet<string> } = {},
): RemoveClaudeHooksResult {
const nothing = (note: string): RemoveClaudeHooksResult =>
({ settingsPath, removed: 0, backupPath: null, notes: [note], unmarked: [], unowned: [], preserved: [] });
if (!existsSync(settingsPath)) return nothing('no settings file — nothing to remove');
let settings: SettingsObject;
try {
const raw = readFileSync(settingsPath, 'utf8');
if (raw.trim() === '') return nothing('settings file empty — nothing to remove');
const parsed = JSON.parse(raw) as unknown;
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
throw new Error('settings root is not a JSON object');
}
settings = parsed as SettingsObject;
} catch (e) {
return nothing(
`WARNING: ${settingsPath} is not valid JSON (${(e as Error).message}); ` +
`left untouched — remove gbrain hook entries by hand or fix the JSON and re-run.`,
);
}
const hooks = settings.hooks as Record<string, unknown> | undefined;
if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
return nothing('no hooks object — nothing to remove');
}
let removed = 0;
const unmarked: Array<{ event: string; why: string }> = [];
const unowned: string[] = [];
const preserved: Array<{ event: string; hash: string }> = [];
for (const event of Object.keys(hooks)) {
const groups = hooks[event];
if (!Array.isArray(groups)) continue; // structurally foreign — never touch
const strip = stripOurEntries(groups, marker, opts.identity && { event, identity: opts.identity }, opts.ownedEntryHashes);
const { kept, removed: n } = strip;
preserved.push(...strip.preserved.map((hash) => ({ event, hash })));
removed += n;
unmarked.push(...strip.unmarked.map((why) => ({ event, why })));
if (strip.unowned > 0) unowned.push(event);
if (n === 0) continue;
if (kept.length === 0) {
delete hooks[event]; // emptied by OUR removal — drop the key
} else {
hooks[event] = kept;
}
}
if (removed > 0 && Object.keys(hooks).length === 0) {
delete settings.hooks;
}
let backupPath: string | null = null;
if (removed > 0 && !opts.dryRun) {
backupPath = `${settingsPath}.bak`;
copyFileSync(settingsPath, backupPath);
atomicWriteJson(settingsPath, settings);
}
return { settingsPath, removed, backupPath, notes: [], unmarked, unowned, preserved };
}
/**
* Read-only census of one harness carrier: per wired event, how many entries
* are marked, unmarked-but-ours (`command`) and harness-looking but not ours
* (`unowned`). Doctor, `--status` and the cross-HOME `--project` guard use it;
* nothing is written.
*/
export function scanHarnessHookCarrier(
settingsPath: string,
identity: HarnessHookIdentity | 'any',
): { state: 'absent' | 'unparseable' | 'ok'; error?: string; events: Partial<Record<ClaudeHookEvent, Record<HarnessHookOwnership, number>>> } {
const events: Partial<Record<ClaudeHookEvent, Record<HarnessHookOwnership, number>>> = {};
if (!existsSync(settingsPath)) return { state: 'absent', events };
let hooks: unknown;
try {
const raw = readFileSync(settingsPath, 'utf8');
if (raw.trim() === '') return { state: 'ok', events };
const parsed = JSON.parse(raw) as unknown;
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new Error('settings root is not a JSON object');
hooks = (parsed as SettingsObject).hooks;
} catch (e) {
return { state: 'unparseable', error: (e as Error).message, events };
}
if (typeof hooks !== 'object' || hooks === null) return { state: 'ok', events };
for (const event of CLAUDE_HOOK_EVENTS) {
const groups = (hooks as Record<string, unknown>)[event];
if (!Array.isArray(groups)) continue;
for (const group of groups) {
const entries = (group as HookMatcherGroup)?.hooks;
if (!Array.isArray(entries)) continue;
for (const entry of entries) {
const c = classifyHarnessHook(entry, event, identity);
if (!c) continue;
const counts = (events[event] ??= { marked: 0, command: 0, unowned: 0 });
counts[c.ownership]++;
}
}
}
return { state: 'ok', events };
}
/** True when an event's matcher groups carry any gbrain hook: an entry with a
* `_gbrain` marker key, or an unmarked harness hook command (the host may have
* dropped its marker). hook_carrier_overlap counts carriers with this. */
export function groupsCarryGbrainHook(groups: unknown, event: string): boolean {
if (!Array.isArray(groups)) return false;
return groups.some((group) => {
const entries = (group as HookMatcherGroup)?.hooks;
return Array.isArray(entries) && entries.some((entry) =>
(typeof entry === 'object' && entry !== null && Object.prototype.hasOwnProperty.call(entry, GBRAIN_HOOK_MARKER_KEY)) ||
classifyHarnessHook(entry, event, 'any')?.ownership === 'command');
});
}
/**
* Workspace-lane removal — cleans BOTH carriers (local + committed [D12]);
* the returned settingsPath/backup describe the local one, with
* committed-file actions reported via notes.
*/
export function removeClaudeHooks(workspaceDir: string): RemoveClaudeHooksResult {
const local = removeClaudeHooksAt(claudeSettingsPath(workspaceDir));
const committed = removeClaudeHooksAt(claudeCommittedSettingsPath(workspaceDir));
const notes = [...local.notes];
if (committed.removed > 0) {
notes.push(`also removed ${committed.removed} entr${committed.removed === 1 ? 'y' : 'ies'} from the committed ${committed.settingsPath} [D12]`);
} else {
notes.push(...committed.notes.map((n) => `(committed carrier) ${n}`));
}
return {
settingsPath: local.settingsPath,
removed: local.removed + committed.removed,
backupPath: local.backupPath,
notes,
unmarked: [],
unowned: [],
preserved: [],
};
}
// ── permissions.allow writers (harness lane, #4043) ────────────────────────
export interface PermissionsAllowResult {
settingsPath: string;
/** add: entry appended this run. remove: number of occurrences removed. */
added?: boolean;
removed?: number;
backupPath: string | null;
notes: string[];
}
/**
* Append one entry to `permissions.allow` (set semantics — present means
* no-op). Stamps NO marker: permissions.allow is an array of plain strings,
* so ownership is recorded on the harness receipt (exact-string removal),
* never in the file — and a marker object here would false-positive
* status.ts's whole-file `hooksInstalled` substring probe. Foreign entries
* and every other settings key survive. Broken JSON aborts (user-scope
* discipline — this writer only ever targets user-scope files).
*/
export function addPermissionsAllowEntry(
settingsPath: string,
entry: string,
): PermissionsAllowResult {
const { settings, existed, notes } = loadSettings(settingsPath);
let permissions = settings.permissions as Record<string, unknown> | undefined;
if (typeof permissions !== 'object' || permissions === null || Array.isArray(permissions)) {
if (permissions !== undefined) {
// Fail CLOSED (same stance as broken JSON): "permissions" is the host's
// security policy — replacing a shape we don't understand could erase
// deny/ask rules or a future settings schema (ship-review P2).
throw new Error(
`${settingsPath}: existing "permissions" key is not an object ` +
`(${JSON.stringify(permissions).slice(0, 80)}) — refusing to rewrite security policy this writer ` +
`does not understand. Fix the file by hand, then re-run.`,
);
}
permissions = {};
}
let allow = permissions.allow as unknown[] | undefined;
if (!Array.isArray(allow)) {
if (allow !== undefined) {
throw new Error(
`${settingsPath}: existing permissions.allow is not an array — refusing to rewrite security policy ` +
`this writer does not understand. Fix the file by hand, then re-run.`,
);
}
allow = [];
}
if (allow.some((e) => e === entry)) {
return { settingsPath, added: false, backupPath: null, notes: [...notes, `${entry} already allowed — no change`] };
}
allow.push(entry);
permissions.allow = allow;
settings.permissions = permissions;
let backupPath: string | null = null;
if (existed) {
backupPath = backupPathFor(settingsPath, 'timestamped');
copyFileSync(settingsPath, backupPath);
}
atomicWriteJson(settingsPath, settings, 0o600); // user-scope-only writer [X11]
return { settingsPath, added: true, backupPath, notes };
}
/**
* Remove EXACTLY the given string from `permissions.allow`. Parse-broken file
* is left untouched (the removeClaudeHooks precedent — removal never destroys
* what it cannot read). Keys are dropped only when OUR removal emptied them.
* Honest edge (stated in consent copy): if the user had independently allowed
* the same string, this removes it too — set semantics carry no provenance.
*/
export function removePermissionsAllowEntry(
settingsPath: string,
entry: string,
): PermissionsAllowResult {
if (!existsSync(settingsPath)) {
return { settingsPath, removed: 0, backupPath: null, notes: ['no settings file — nothing to remove'] };
}
let loaded: LoadedSettings;
try {
loaded = loadSettings(settingsPath);
} catch (e) {
return {
settingsPath,
removed: 0,
backupPath: null,
notes: [
`WARNING: ${settingsPath} is not valid JSON (${(e as Error).message}); ` +
`left untouched — remove the "${entry}" permissions.allow entry by hand or fix the JSON and re-run.`,
],
};
}
const { settings, notes } = loaded;
const permissions = settings.permissions as Record<string, unknown> | undefined;
if (typeof permissions !== 'object' || permissions === null || Array.isArray(permissions)) {
return { settingsPath, removed: 0, backupPath: null, notes: ['no permissions object — nothing to remove'] };
}
const allow = permissions.allow as unknown[] | undefined;
if (!Array.isArray(allow)) {
return { settingsPath, removed: 0, backupPath: null, notes: ['no permissions.allow array — nothing to remove'] };
}
const kept = allow.filter((e) => e !== entry);
const removed = allow.length - kept.length;
if (removed === 0) {
return { settingsPath, removed: 0, backupPath: null, notes: [...notes, `${entry} not present — nothing to remove`] };
}
if (kept.length > 0) {
permissions.allow = kept;
} else {
delete permissions.allow; // emptied by OUR removal — drop the key
}
if (Object.keys(permissions).length === 0) {
delete settings.permissions;
}
const backupPath = backupPathFor(settingsPath, 'timestamped');
copyFileSync(settingsPath, backupPath);
atomicWriteJson(settingsPath, settings, 0o600); // user-scope-only writer [X11]
return { settingsPath, removed, backupPath, notes };
}
// ── MCP registration argv builders [G1, CX-P1.4, ENG-7] ────────────────────
export interface ClaudeMcpRegistration {
/** MCP server name; default 'gbrain'. */
name?: string;
/** Absolute path to the gbrain binary. */
gbrainBin: string;
/** Registration scope — a consent question, never a default the user didn't pick [G16/D1]. */
scope: 'project' | 'user';
/** Workspace source slug [G1] — agent writes must land in the workspace source. */
sourceId: string;
/** PARENT dir for --isolated installs (config appends `.gbrain`) [CX2-8]. */
gbrainHome?: string;
/** The serve surface; default REGISTRATION_SURFACE, `null` = bare `serve` (never-narrow carry-over). */
surface?: McpSurface | null;
/** `serve --advertise`; null lists the whole surface (registrationAdvertise decides). */
advertise?: McpSurface | null;
/** The trusted-directory launcher serve starts through (src/core/setup/hook-launcher.ts): the harness starts stdio servers in the session's directory (#8426). User scope only; a project file travels. */
hookLauncher?: string;
}
export type CodexMcpRegistration = Omit<ClaudeMcpRegistration, 'scope'>;
/**
* `claude mcp add` argv for a LOCAL stdio serve. Returns command argv arrays
* (binary first) — the dispatcher execs them; nothing here touches the
* filesystem or the network. Shape per TARGETS['claude-code-2026-08'].
*
* The serve argv comes from `stdioServeArgv`: `--surface starter` by default
* (REGISTRATION_SURFACE; bootstrap's contract — put_page, get_page,
* add_timeline_entry, search, query — stays callable, and a pre-existing `mcp_surface: verbs` config row cannot
* narrow a pinned registration), listing the memory verbs and request_tools
* when `advertise` is 'verbs'; `surface`/`advertise` carry an existing
* entry's form over on replacement or apply `--surface`.
*/
export function registerClaudeMcp(p: ClaudeMcpRegistration): string[][] {
if (!isAbsolute(p.gbrainBin)) {
throw new Error(`gbrainBin must be an absolute path; got: ${p.gbrainBin}`);
}
const name = p.name ?? 'gbrain';
const argv = [
'claude', 'mcp', 'add', name,
'--scope', p.scope,
'-e', `GBRAIN_SOURCE=${p.sourceId}`,
];
if (p.gbrainHome) argv.push('-e', `GBRAIN_HOME=${p.gbrainHome}`);
argv.push('--', ...(p.hookLauncher ? [p.hookLauncher] : []), ...stdioServeArgv(p.gbrainBin, p.surface, p.advertise ?? null));
return [argv];
}
/**
* `codex mcp add` argv for a LOCAL stdio serve (writes ~/.codex/config.toml
* itself — no TOML writer needed in v1, see TARGETS['codex-2026-08']).
* Codex registrations are user-global; there is no scope flag. The serve
* argv comes from `stdioServeArgv` (see registerClaudeMcp).
*/
export function registerCodexMcp(p: CodexMcpRegistration): string[][] {
if (!isAbsolute(p.gbrainBin)) {
throw new Error(`gbrainBin must be an absolute path; got: ${p.gbrainBin}`);
}
const name = p.name ?? 'gbrain';
const argv = ['codex', 'mcp', 'add', name, '--env', `GBRAIN_SOURCE=${p.sourceId}`];
if (p.gbrainHome) argv.push('--env', `GBRAIN_HOME=${p.gbrainHome}`);
argv.push('--', ...(p.hookLauncher ? [p.hookLauncher] : []), ...stdioServeArgv(p.gbrainBin, p.surface, p.advertise ?? null));
return [argv];
}