balladeer 1.0.14 → 1.0.16

package/dist/headless-agent.d.ts

@@ -0,0 +1,166 @@
+import { type KillGroup, type SpawnLike } from "./owned-process.js";
+/**
+ * The customer's own coding agent, run once, headless, on the subscription the
+ * person already signed in with.
+ *
+ * Balladeer holds no model key and asks for none. Everything a map or a judge
+ * costs is spent through Claude Code or Codex on this laptop, under the login
+ * that laptop's owner already has, so the only thing this module verifies
+ * before it spends anything is that such a login exists: Claude Code signed in
+ * through claude.ai, or Codex signed in with ChatGPT. Every environment
+ * variable that could redirect the run to an API key or another provider is
+ * removed, the way `scripts/client-compatibility/run.mjs` and
+ * `scripts/guidance-acceptance/runner.ts` remove them.
+ *
+ * The run is private: no saved session, no hooks, no MCP servers, no project or
+ * user settings, no slash commands, an explicit tool list and nothing outside
+ * it. Output is bounded and the whole process group is killed at the deadline.
+ */
+export type HeadlessClient = "claude" | "codex";
+export type LoginCheck = Readonly<{
+    client: HeadlessClient;
+    verified: boolean;
+    /** `claude.ai` or `ChatGPT` when verified. Never an account identifier. */
+    method?: string;
+}>;
+export type HeadlessAgentOptions = Readonly<{
+    client: HeadlessClient | "auto";
+    cwd: string;
+    prompt: string;
+    /**
+     * Claude Code's permission rules: built-in tool names, or narrower rules such
+     * as `Bash(git diff:*)` when `tools` names the tools themselves. Codex takes
+     * its sandbox instead.
+     */
+    allowedTools: readonly string[];
+    /**
+     * The built-in tools Claude Code makes available, when that is not the same
+     * list as the permission rules. With it, a rule narrower than a whole tool
+     * (only some shell commands) is what is allowed, and everything else the tool
+     * could do is refused by the permission mode.
+     */
+    tools?: readonly string[];
+    timeoutMs: number;
+    /** The caller's environment. Provider and key variables are removed from it. */
+    env: NodeJS.ProcessEnv;
+    /** When true, the last JSON object in the final message is parsed out. */
+    jsonOutput: boolean;
+    /** For `auto`: the client that started the hook, tried first. */
+    prefer?: HeadlessClient;
+    /** Codex's sandbox. Read-only unless the run has to execute tests. */
+    sandbox?: "read-only" | "workspace-write";
+    /** Claude Code permission rules refused outright, such as `Bash(git push:*)`. */
+    disallowedTools?: readonly string[];
+    /** Fires when the caller's budget runs out; the run is stopped, not failed. */
+    signal?: AbortSignal;
+    spawn?: SpawnLike;
+    killGroup?: KillGroup;
+    /** A login already verified by the caller, so a batch checks it once. */
+    login?: LoginCheck;
+    maxOutputBytes?: number;
+    /** Where the private settings directory is made. Defaults to the system temp directory. */
+    scratch?: string;
+}>;
+export type HeadlessAgentResult = Readonly<{
+    ok: boolean;
+    /** The agent's final message. */
+    text: string;
+    /** The last JSON object in that message, when one was asked for and found. */
+    json?: Record<string, unknown>;
+    client: HeadlessClient | "none";
+    model?: string;
+    durationMs: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    exitCode: number | null;
+    stderrTail: string;
+    timedOut: boolean;
+    aborted: boolean;
+    /** Why `ok` is false, as a code a caller can branch on. */
+    reason?: "no_verified_login" | "spawn_failed" | "timed_out" | "aborted" | "output_bounded" | "exit_nonzero" | "no_answer" | "no_json";
+}>;
+/** Set on every run this module starts, so a hook inside it knows not to judge again. */
+export declare const JUDGE_ACTIVE_VARIABLE = "BALLADEER_JUDGE_ACTIVE";
+export declare function agentEnvironment(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Which binary runs each client. An override is read before the environment is stripped. */
+export declare function clientBinary(client: HeadlessClient, env: NodeJS.ProcessEnv): string;
+/**
+ * Claude Code's arguments, all flags, prompt on standard input.
+ *
+ * The prompt goes in on stdin rather than as an argument: a promise and its map
+ * can run to kilobytes, an argument is visible to every process listing on the
+ * machine, and `--allowedTools` takes a variable number of values, which is the
+ * argument-position failure the compatibility README records.
+ */
+export declare function claudeArguments(input: Readonly<{
+    settingsPath: string;
+    allowedTools: readonly string[];
+    disallowedTools?: readonly string[];
+    tools?: readonly string[];
+}>): string[];
+/** Codex's arguments. `-` reads the prompt from standard input. */
+export declare function codexArguments(input: Readonly<{
+    cwd: string;
+    sandbox: "read-only" | "workspace-write";
+}>): string[];
+/**
+ * Whether this laptop has the subscription login the client needs.
+ *
+ * Only the verdict and the method leave this function. The account, the email
+ * and the organization the status command prints are read to decide and then
+ * dropped, the same way the compatibility canary treats them.
+ */
+export declare function verifyLogin(client: HeadlessClient, options: Readonly<{
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    spawn?: SpawnLike;
+    killGroup?: KillGroup;
+}>): Promise<LoginCheck>;
+/**
+ * The client to run, or none. `auto` tries the hook's own client first, then
+ * Claude Code, then Codex, and takes the first whose login verifies.
+ */
+export declare function resolveClient(requested: HeadlessClient | "auto", options: Readonly<{
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    prefer?: HeadlessClient;
+    spawn?: SpawnLike;
+    killGroup?: KillGroup;
+}>): Promise<LoginCheck | undefined>;
+/**
+ * The last JSON object in a piece of text.
+ *
+ * An agent asked for one object sometimes wraps it in a fence, sometimes adds a
+ * sentence after it, and sometimes quotes an example before it. Every balanced,
+ * string-aware `{...}` at the top level is tried, and the last one that parses
+ * to an object is the answer.
+ */
+export declare function extractLastJsonObject(text: string): Record<string, unknown> | undefined;
+type Parsed = Readonly<{
+    text: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    isError: boolean;
+}>;
+/**
+ * Claude Code's `--output-format json` answer: one result object.
+ *
+ * Input tokens are counted the way a subscription spends them, cache reads and
+ * cache writes included, because a judge that re-reads the same files is not
+ * free just because the provider cached them. The model is the one that wrote
+ * the most output, which is the one that did the judging.
+ */
+export declare function parseClaudeOutput(stdout: string): Parsed | undefined;
+/** Codex's `--json` event stream: the last agent message, and usage summed over turns. */
+export declare function parseCodexOutput(stdout: string): Parsed | undefined;
+/**
+ * Run the prompt once on the person's own agent and return its final message.
+ *
+ * Never throws for anything the agent or the machine does: a missing login, a
+ * binary that is not installed, a timeout and an answer with no JSON in it all
+ * come back as `ok: false` with a reason, because the callers of this are hooks
+ * that must answer something truthful whatever happened.
+ */
+export declare function runHeadlessAgent(options: HeadlessAgentOptions): Promise<HeadlessAgentResult>;
+export {};

package/dist/headless-agent.js

@@ -0,0 +1,416 @@
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { runOwnedProcess, tail, } from "./owned-process.js";
+/**
+ * Variables that would send a run somewhere other than the person's own
+ * subscription, or hand it a credential it was not meant to have. The union of
+ * the two harnesses' lists, plus Balladeer's own so a nested command never
+ * reads this machine's connection.
+ */
+const STRIPPED = /API_KEY|AUTH_TOKEN|ACCESS_TOKEN|BEARER|BASE_URL|ENDPOINT|^AWS_|^AZURE_|^GOOGLE_|^ANTHROPIC_|^OPENAI_|^CLAUDE_CODE_USE_|^CLAUDECODE|^BALLADEER_|^CODEX_API|^GOOGLE_APPLICATION_CREDENTIALS$/;
+/** Set on every run this module starts, so a hook inside it knows not to judge again. */
+export const JUDGE_ACTIVE_VARIABLE = "BALLADEER_JUDGE_ACTIVE";
+export function agentEnvironment(parent) {
+    const env = {};
+    for (const [key, value] of Object.entries(parent)) {
+        if (value === undefined || STRIPPED.test(key))
+            continue;
+        env[key] = value;
+    }
+    env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
+    env.ENABLE_CLAUDEAI_MCP_SERVERS = "false";
+    env[JUDGE_ACTIVE_VARIABLE] = "1";
+    return env;
+}
+/** Which binary runs each client. An override is read before the environment is stripped. */
+export function clientBinary(client, env) {
+    if (client === "claude")
+        return env.BALLADEER_CLAUDE_BIN?.trim() || env.CLAUDE_BIN?.trim() || "claude";
+    return env.BALLADEER_CODEX_BIN?.trim() || env.CODEX_BIN?.trim() || "codex";
+}
+/**
+ * Claude Code's arguments, all flags, prompt on standard input.
+ *
+ * The prompt goes in on stdin rather than as an argument: a promise and its map
+ * can run to kilobytes, an argument is visible to every process listing on the
+ * machine, and `--allowedTools` takes a variable number of values, which is the
+ * argument-position failure the compatibility README records.
+ */
+export function claudeArguments(input) {
+    const tools = (input.tools ?? input.allowedTools).join(",");
+    // Rules narrower than a tool carry spaces (`Bash(git diff:*)`), so they go
+    // in as separate values rather than as one comma list.
+    const allowed = input.tools === undefined ? [tools] : [...input.allowedTools];
+    return [
+        "--print",
+        "--output-format",
+        "json",
+        "--no-session-persistence",
+        "--strict-mcp-config",
+        "--mcp-config",
+        '{"mcpServers":{}}',
+        "--settings",
+        input.settingsPath,
+        "--setting-sources",
+        "",
+        "--disable-slash-commands",
+        "--permission-mode",
+        "dontAsk",
+        "--tools",
+        tools,
+        "--allowedTools",
+        ...allowed,
+        ...((input.disallowedTools ?? []).length > 0
+            ? ["--disallowedTools", ...(input.disallowedTools ?? [])]
+            : []),
+    ];
+}
+/** Codex's arguments. `-` reads the prompt from standard input. */
+export function codexArguments(input) {
+    return [
+        "exec",
+        "--ephemeral",
+        "--ignore-rules",
+        "--ignore-user-config",
+        "--sandbox",
+        input.sandbox,
+        "-C",
+        input.cwd,
+        "--json",
+        "-c",
+        'approval_policy="never"',
+        "--disable",
+        "hooks",
+        "-",
+    ];
+}
+/**
+ * Whether this laptop has the subscription login the client needs.
+ *
+ * Only the verdict and the method leave this function. The account, the email
+ * and the organization the status command prints are read to decide and then
+ * dropped, the same way the compatibility canary treats them.
+ */
+export async function verifyLogin(client, options) {
+    const env = agentEnvironment(options.env);
+    const run = await runOwnedProcess({
+        command: clientBinary(client, options.env),
+        args: client === "claude" ? ["auth", "status", "--json"] : ["login", "status"],
+        cwd: options.cwd,
+        env,
+        timeoutMs: 15_000,
+        maxOutputBytes: 64 * 1024,
+        ...(options.spawn === undefined ? {} : { spawn: options.spawn }),
+        ...(options.killGroup === undefined ? {} : { killGroup: options.killGroup }),
+    });
+    if (run.spawnError !== undefined || run.exitCode !== 0)
+        return { client, verified: false };
+    if (client === "claude") {
+        try {
+            const status = JSON.parse(run.stdout);
+            const verified = status.loggedIn === true && status.authMethod === "claude.ai";
+            return verified ? { client, verified, method: "claude.ai" } : { client, verified: false };
+        }
+        catch {
+            return { client, verified: false };
+        }
+    }
+    const verified = /Logged in using ChatGPT/.test(`${run.stdout}\n${run.stderr}`);
+    return verified ? { client, verified, method: "ChatGPT" } : { client, verified: false };
+}
+/**
+ * The client to run, or none. `auto` tries the hook's own client first, then
+ * Claude Code, then Codex, and takes the first whose login verifies.
+ */
+export async function resolveClient(requested, options) {
+    const order = requested !== "auto"
+        ? [requested]
+        : options.prefer === "codex"
+            ? ["codex", "claude"]
+            : ["claude", "codex"];
+    for (const client of order) {
+        const check = await verifyLogin(client, options);
+        if (check.verified)
+            return check;
+    }
+    return undefined;
+}
+/**
+ * The last JSON object in a piece of text.
+ *
+ * An agent asked for one object sometimes wraps it in a fence, sometimes adds a
+ * sentence after it, and sometimes quotes an example before it. Every balanced,
+ * string-aware `{...}` at the top level is tried, and the last one that parses
+ * to an object is the answer.
+ */
+export function extractLastJsonObject(text) {
+    let found;
+    let index = 0;
+    while (index < text.length) {
+        const start = text.indexOf("{", index);
+        if (start < 0)
+            break;
+        const end = matchingBrace(text, start);
+        if (end < 0) {
+            index = start + 1;
+            continue;
+        }
+        try {
+            const value = JSON.parse(text.slice(start, end + 1));
+            if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+                found = value;
+                index = end + 1;
+                continue;
+            }
+        }
+        catch {
+            /* Not JSON at this brace; an inner one may be. */
+        }
+        index = start + 1;
+    }
+    return found;
+}
+function matchingBrace(text, start) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let at = start; at < text.length; at += 1) {
+        const char = text[at];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"')
+            inString = true;
+        else if (char === "{")
+            depth += 1;
+        else if (char === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return at;
+        }
+    }
+    return -1;
+}
+const count = (value) => typeof value === "number" && Number.isFinite(value) ? value : 0;
+/**
+ * Claude Code's `--output-format json` answer: one result object.
+ *
+ * Input tokens are counted the way a subscription spends them, cache reads and
+ * cache writes included, because a judge that re-reads the same files is not
+ * free just because the provider cached them. The model is the one that wrote
+ * the most output, which is the one that did the judging.
+ */
+export function parseClaudeOutput(stdout) {
+    let body;
+    try {
+        body = JSON.parse(stdout.trim());
+    }
+    catch {
+        const last = extractLastJsonObject(stdout);
+        if (last === undefined)
+            return undefined;
+        body = last;
+    }
+    const text = typeof body.result === "string" ? body.result : "";
+    let model;
+    let inputTokens;
+    let outputTokens;
+    const usageByModel = body.modelUsage;
+    if (usageByModel !== null && typeof usageByModel === "object") {
+        let most = -1;
+        inputTokens = 0;
+        outputTokens = 0;
+        for (const [name, usage] of Object.entries(usageByModel)) {
+            const row = (usage ?? {});
+            const out = count(row.outputTokens);
+            inputTokens +=
+                count(row.inputTokens) +
+                    count(row.cacheReadInputTokens) +
+                    count(row.cacheCreationInputTokens);
+            outputTokens += out;
+            if (out > most) {
+                most = out;
+                model = name;
+            }
+        }
+    }
+    else if (body.usage !== null && typeof body.usage === "object") {
+        const usage = body.usage;
+        inputTokens =
+            count(usage.input_tokens) +
+                count(usage.cache_read_input_tokens) +
+                count(usage.cache_creation_input_tokens);
+        outputTokens = count(usage.output_tokens);
+    }
+    return {
+        text,
+        isError: body.is_error === true,
+        ...(model === undefined ? {} : { model }),
+        ...(inputTokens === undefined ? {} : { inputTokens }),
+        ...(outputTokens === undefined ? {} : { outputTokens }),
+    };
+}
+/** Codex's `--json` event stream: the last agent message, and usage summed over turns. */
+export function parseCodexOutput(stdout) {
+    let text;
+    let model;
+    let inputTokens;
+    let outputTokens;
+    let isError = false;
+    let events = 0;
+    for (const line of stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        events += 1;
+        if (typeof event.model === "string")
+            model = event.model;
+        const item = event.item;
+        if (event.type === "item.completed" &&
+            item?.type === "agent_message" &&
+            typeof item.text === "string")
+            text = item.text;
+        if (event.type === "turn.completed") {
+            const usage = (event.usage ?? {});
+            inputTokens = (inputTokens ?? 0) + count(usage.input_tokens);
+            outputTokens = (outputTokens ?? 0) + count(usage.output_tokens);
+        }
+        if (event.type === "turn.failed" || event.type === "error")
+            isError = true;
+    }
+    if (events === 0)
+        return undefined;
+    return {
+        text: text ?? "",
+        isError: isError && text === undefined,
+        ...(model === undefined ? {} : { model }),
+        ...(inputTokens === undefined ? {} : { inputTokens }),
+        ...(outputTokens === undefined ? {} : { outputTokens }),
+    };
+}
+/**
+ * Run the prompt once on the person's own agent and return its final message.
+ *
+ * Never throws for anything the agent or the machine does: a missing login, a
+ * binary that is not installed, a timeout and an answer with no JSON in it all
+ * come back as `ok: false` with a reason, because the callers of this are hooks
+ * that must answer something truthful whatever happened.
+ */
+export async function runHeadlessAgent(options) {
+    const started = Date.now();
+    const login = options.login ??
+        (await resolveClient(options.client, {
+            env: options.env,
+            cwd: options.cwd,
+            ...(options.prefer === undefined ? {} : { prefer: options.prefer }),
+            ...(options.spawn === undefined ? {} : { spawn: options.spawn }),
+            ...(options.killGroup === undefined ? {} : { killGroup: options.killGroup }),
+        }));
+    if (login === undefined || !login.verified) {
+        return {
+            ok: false,
+            text: "",
+            client: "none",
+            durationMs: Date.now() - started,
+            exitCode: null,
+            stderrTail: "",
+            timedOut: false,
+            aborted: false,
+            reason: "no_verified_login",
+        };
+    }
+    const client = login.client;
+    const privateRoot = realpathSync(mkdtempSync(join(options.scratch ?? tmpdir(), "balladeer-agent-")));
+    try {
+        const env = agentEnvironment(options.env);
+        let args;
+        if (client === "claude") {
+            const settingsPath = join(privateRoot, "settings.json");
+            writeFileSync(settingsPath, JSON.stringify({ disableAllHooks: true }), { mode: 0o600 });
+            args = claudeArguments({
+                settingsPath,
+                allowedTools: options.allowedTools,
+                ...(options.tools === undefined ? {} : { tools: options.tools }),
+                ...(options.disallowedTools === undefined
+                    ? {}
+                    : { disallowedTools: options.disallowedTools }),
+            });
+        }
+        else {
+            // A private configuration home holding only a link to the existing
+            // login, so no user configuration, trust entry, MCP server or hook of
+            // the person's comes along. The link is removed with the directory.
+            const codexHome = join(privateRoot, "codex");
+            mkdirSync(codexHome, { mode: 0o700 });
+            const auth = join(options.env.CODEX_HOME?.trim() || join(homedir(), ".codex"), "auth.json");
+            if (existsSync(auth))
+                symlinkSync(auth, join(codexHome, "auth.json"));
+            env.CODEX_HOME = codexHome;
+            args = codexArguments({ cwd: options.cwd, sandbox: options.sandbox ?? "read-only" });
+        }
+        const run = await runOwnedProcess({
+            command: clientBinary(client, options.env),
+            args,
+            cwd: options.cwd,
+            env,
+            input: options.prompt,
+            timeoutMs: options.timeoutMs,
+            ...(options.maxOutputBytes === undefined ? {} : { maxOutputBytes: options.maxOutputBytes }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.spawn === undefined ? {} : { spawn: options.spawn }),
+            ...(options.killGroup === undefined ? {} : { killGroup: options.killGroup }),
+        });
+        const parsed = client === "claude" ? parseClaudeOutput(run.stdout) : parseCodexOutput(run.stdout);
+        const base = {
+            text: parsed?.text ?? "",
+            client,
+            durationMs: Date.now() - started,
+            exitCode: run.exitCode,
+            stderrTail: tail(run.stderr),
+            timedOut: run.timedOut,
+            aborted: run.aborted,
+            ...(parsed?.model === undefined ? {} : { model: parsed.model }),
+            ...(parsed?.inputTokens === undefined ? {} : { inputTokens: parsed.inputTokens }),
+            ...(parsed?.outputTokens === undefined ? {} : { outputTokens: parsed.outputTokens }),
+        };
+        const failed = (reason) => ({
+            ...base,
+            ok: false,
+            reason,
+        });
+        if (run.spawnError !== undefined)
+            return failed("spawn_failed");
+        if (run.aborted)
+            return failed("aborted");
+        if (run.timedOut)
+            return failed("timed_out");
+        if (run.bounded)
+            return failed("output_bounded");
+        if (run.exitCode !== 0)
+            return failed("exit_nonzero");
+        if (parsed === undefined || parsed.isError || parsed.text.trim() === "")
+            return failed("no_answer");
+        if (!options.jsonOutput)
+            return { ...base, ok: true };
+        const json = extractLastJsonObject(parsed.text);
+        if (json === undefined)
+            return failed("no_json");
+        return { ...base, ok: true, json };
+    }
+    finally {
+        rmSync(privateRoot, { recursive: true, force: true });
+    }
+}

package/dist/hook-trust.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Knowing when a host has not run the hooks this command last wrote, so the
+ * person is told to approve them whenever that is true, not only at setup.
+ *
+ * Robert, 29 September 2026: hooks will change from release to release, and
+ * most releases arrive through the background update, which says nothing to
+ * anybody. Codex trusts a hook by the hash of its definition and skips a new
+ * or changed one until the person trusts it under /hooks, so a laptop can
+ * update itself into silence. Two small marks settle it without reading
+ * anything of the host's: when this command last wrote a host's hooks, and
+ * when one of that host's hooks last ran. Written after fired means the
+ * current hooks have never run, and the host's own session is where the
+ * person hears it.
+ */
+export type TrustingHost = "codex";
+/** Hosts that run a hook only after the person has approved it. */
+export declare const HOSTS_REQUIRING_TRUST: readonly TrustingHost[];
+/**
+ * This command wrote or changed the host's hooks, or found them in place with
+ * no record that it ever had: either way, from now the host has to have run
+ * them once before anybody assumes it does.
+ */
+export declare function noteHooksWritten(environment: NodeJS.ProcessEnv, host: TrustingHost, changed: boolean, now?: number): void;
+/** One of the host's hooks ran, which it does only once they are trusted. */
+export declare function noteHookFired(environment: NodeJS.ProcessEnv, host: TrustingHost, now?: number): void;
+/** True while the hooks last written for this host have never run in it. */
+export declare function hooksAwaitingTrust(environment: NodeJS.ProcessEnv, host: TrustingHost): boolean;
+/** The host a session belongs to, from the name it gave when it said hello. */
+export declare function trustingHost(clientName: unknown): TrustingHost | undefined;
+/** What the agent is asked to pass on, once, in the host where the approval happens. */
+export declare const HOOKS_AWAITING_TRUST_NOTICE = "Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. Ask them to type /hooks in Codex and trust Balladeer's three hooks; until then Codex has Balladeer's tools without its session-start guidance or its updates.";

package/dist/hook-trust.js

@@ -0,0 +1,63 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configHome } from "./store.js";
+/** Hosts that run a hook only after the person has approved it. */
+export const HOSTS_REQUIRING_TRUST = ["codex"];
+const FILE = "hook-trust.json";
+function read(environment) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(configHome(environment), FILE), "utf8"));
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function write(environment, marks) {
+    try {
+        mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
+        writeFileSync(join(configHome(environment), FILE), JSON.stringify(marks) + "\n", {
+            mode: 0o600,
+        });
+    }
+    catch {
+        /* A mark that cannot be written costs a notice, never a session. */
+    }
+}
+/**
+ * This command wrote or changed the host's hooks, or found them in place with
+ * no record that it ever had: either way, from now the host has to have run
+ * them once before anybody assumes it does.
+ */
+export function noteHooksWritten(environment, host, changed, now = Date.now()) {
+    const marks = read(environment);
+    if (!changed && marks[host]?.writtenAt !== undefined)
+        return;
+    write(environment, { ...marks, [host]: { ...marks[host], writtenAt: now } });
+}
+/** One of the host's hooks ran, which it does only once they are trusted. */
+export function noteHookFired(environment, host, now = Date.now()) {
+    const marks = read(environment);
+    const mark = marks[host];
+    // Nothing to settle, or already settled: no write on the session's path.
+    if (mark?.firedAt !== undefined && mark.firedAt >= (mark.writtenAt ?? 0))
+        return;
+    write(environment, { ...marks, [host]: { ...mark, firedAt: now } });
+}
+/** True while the hooks last written for this host have never run in it. */
+export function hooksAwaitingTrust(environment, host) {
+    const mark = read(environment)[host];
+    if (mark?.writtenAt === undefined)
+        return false;
+    return mark.firedAt === undefined || mark.firedAt < mark.writtenAt;
+}
+/** The host a session belongs to, from the name it gave when it said hello. */
+export function trustingHost(clientName) {
+    return typeof clientName === "string" && clientName.toLowerCase().startsWith("codex")
+        ? "codex"
+        : undefined;
+}
+/** What the agent is asked to pass on, once, in the host where the approval happens. */
+export const HOOKS_AWAITING_TRUST_NOTICE = "Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. Ask them to type /hooks in Codex and trust Balladeer's three hooks; until then Codex has Balladeer's tools without its session-start guidance or its updates.";