@blastin-dev/clocktopus-cli 0.2.0 → 0.3.0

package/dist/src/lib/claude-settings.js

@@ -1,20 +1,16 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-/**
- * Reads and edits `~/.claude/settings.json` on the user's behalf.
- *
- * Two rules govern everything here, both of them about not destroying a file
- * we do not own:
- *
- * 1. **Never write over JSON we could not parse.** A malformed settings file
- *    is far more likely to be a half-finished edit than something to
- *    overwrite, and overwriting it would lose the user's own hooks,
- *    permissions and MCP servers. Parse failures raise instead.
- * 2. **Only ever touch keys we put there.** Merging into `env` and appending
- *    to `hooks` leaves everything else untouched, and removal matches our
- *    own hook command rather than clearing the arrays.
- */
+// Reads and edits `~/.claude/settings.json` on the user's behalf.
+//
+// Two rules govern everything here, both about not destroying a file we do not own:
+//
+// 1. Never write over JSON we could not parse. A malformed settings file is far more
+//    likely to be a half-finished edit than something to overwrite, and overwriting
+//    would lose the user's own hooks, permissions and MCP servers.
+// 2. Only ever touch keys we put there. Merging into `env` and appending to `hooks`
+//    leaves everything else alone, and removal matches our own hook command rather
+//    than clearing the arrays.
 export const SETTINGS_FILENAME = "settings.json";
 /** Env keys `clocktopus agent setup` owns — and the only ones it removes. */
 export const TELEMETRY_ENV_KEYS = [
@@ -28,22 +24,14 @@ export const TELEMETRY_ENV_KEYS = [
     "CLOCKTOPUS_INGEST_TOKEN",
     "CLOCKTOPUS_OTEL_ENDPOINT",
 ];
-/**
- * How often Claude Code's exporter ships metrics.
- *
- * Also the resolution of every "last export received" answer the status
- * command can give — a session that started 30s ago has genuinely not
- * exported yet, which is why status treats silence under one interval as
- * "waiting" rather than "broken".
- */
+// How often Claude Code's exporter ships metrics — and the resolution of every "last
+// export received" answer status can give, which is why silence under one interval
+// reads as "waiting" rather than "broken".
 export const METRIC_EXPORT_INTERVAL_MS = 60_000;
-/**
- * Seconds Claude Code will wait for the hook before giving up on it.
- *
- * Comfortably above the hook's own 4s request timeout, so a slow network
- * produces the hook's own recorded failure — which `agent doctor` can read
- * back — rather than a kill from the host, which leaves no trace anywhere.
- */
+// Seconds Claude Code will wait for the hook. Comfortably above the hook's own 4s
+// request timeout, so a slow network produces the hook's own recorded failure — which
+// `agent doctor` can read back — rather than a kill from the host, which leaves no
+// trace.
 export const HOOK_TIMEOUT_SECONDS = 10;
 export class SettingsParseError extends Error {
     path;
@@ -54,8 +42,8 @@ export class SettingsParseError extends Error {
     }
 }
 export function claudeConfigDir() {
-    // Claude Code honours CLAUDE_CONFIG_DIR; following it means setup writes
-    // where that installation actually reads.
+    // Claude Code honours CLAUDE_CONFIG_DIR; following it means setup writes where that
+    // installation actually reads.
     return process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
 }
 export function settingsPath() {
@@ -67,8 +55,8 @@ export function readSettings(path = settingsPath()) {
     }
     const raw = readFileSync(path, "utf8");
     const modifiedAt = statSync(path).mtime;
-    // An empty file is a normal state (some installers touch it) and is safe
-    // to treat as an empty object; anything else that fails to parse is not.
+    // An empty file is a normal state (some installers touch it) and is safe to treat as
+    // an empty object; anything else that fails to parse is not.
     if (raw.trim() === "") {
         return { path, exists: true, modifiedAt, settings: {} };
     }
@@ -90,13 +78,9 @@ export function readSettings(path = settingsPath()) {
         throw new SettingsParseError(path);
     }
 }
-/**
- * Writes settings, keeping a one-deep backup of what was there before.
- *
- * The rename is what makes it atomic: a crash midway leaves either the old
- * file or the new one, never a truncated file that Claude Code would refuse
- * to start with.
- */
+// Writes settings, keeping a one-deep backup. The rename is what makes it atomic: a
+// crash midway leaves either the old file or the new one, never a truncated file
+// Claude Code would refuse to start with.
 export function writeSettings(settings, path = settingsPath()) {
     mkdirSync(dirname(path), { recursive: true });
     let backupPath = null;
@@ -117,13 +101,12 @@ export function buildTelemetryEnv(input) {
     return {
         CLAUDE_CODE_ENABLE_TELEMETRY: "1",
         OTEL_METRICS_EXPORTER: "otlp",
-        // The receiver answers protobuf with an explicit 415 rather than a
-        // parse error, but only JSON actually works.
+        // The receiver answers protobuf with an explicit 415, but only JSON actually works.
         OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
         OTEL_EXPORTER_OTLP_ENDPOINT: endpoint,
         OTEL_EXPORTER_OTLP_HEADERS: `Authorization=Bearer ${input.token}`,
-        // Without the session id the metric stream cannot be joined to the hook
-        // stream, and every session loses its repository and branch.
+        // Without the session id the metric stream cannot be joined to the hook stream, and
+        // every session loses its repository and branch.
         OTEL_METRICS_INCLUDE_SESSION_ID: "true",
         OTEL_METRIC_EXPORT_INTERVAL: String(METRIC_EXPORT_INTERVAL_MS),
         // The hook's own channel. Same token, different transport.
@@ -132,15 +115,10 @@ export function buildTelemetryEnv(input) {
     };
 }
 const HOOK_EVENTS = ["SessionStart", "SessionEnd"];
-/**
- * Recognises a hook entry as ours, across every spelling we have shipped.
- *
- * The `claude-hook.mjs` clause matters for upgrades: before this command
- * existed the hook was a script inside a checkout of the Clocktopus repo,
- * and anyone who set that up by hand still has it. Failing to recognise it
- * would leave it installed next to the new one and POST every SessionStart
- * twice.
- */
+// Recognises a hook entry as ours, across every spelling we have shipped. The
+// `claude-hook.mjs` clause matters for upgrades: before this command existed the hook
+// was a script inside a checkout of this repo, and anyone who set that up by hand
+// still has it. Failing to recognise it would POST every SessionStart twice.
 function isClocktopusHook(entry) {
     const command = typeof entry.command === "string" ? entry.command : "";
     if (/claude-hook\.mjs/.test(command))
@@ -157,8 +135,8 @@ function withoutOurHooks(matchers) {
         ...matcher,
         hooks: (matcher.hooks ?? []).filter((entry) => !isClocktopusHook(entry)),
     }))
-        // A matcher group that only ever held our hook is ours to remove; one
-        // that still has entries belongs to the user and stays.
+        // A matcher group that only ever held our hook is ours to remove; one that still has
+        // entries belongs to the user and stays.
         .filter((matcher) => (matcher.hooks ?? []).length > 0));
 }
 export function applyTelemetrySettings(settings, input) {
@@ -174,9 +152,8 @@ export function applyTelemetrySettings(settings, input) {
         : {};
     const hooks = { ...existingHooks };
     for (const event of HOOK_EVENTS) {
-        // Remove-then-append rather than append: re-running setup after a
-        // reinstall must not leave two hooks firing per session, which would
-        // double every SessionStart POST.
+        // Remove-then-append rather than append: re-running setup after a reinstall must not
+        // leave two hooks firing per session, which would double every SessionStart POST.
         hooks[event] = [
             ...withoutOurHooks(asMatchers(existingHooks[event])),
             {
@@ -184,10 +161,8 @@ export function applyTelemetrySettings(settings, input) {
                     {
                         type: "command",
                         command: input.hookCommand,
-                        // Both fields are about not making the user wait on telemetry.
-                        // The hook does network I/O — its own POST, plus a sweep of
-                        // abandoned sessions at SessionStart — and running it inline
-                        // would add that latency to the start of every session.
+                        // Both fields are about not making the user wait on telemetry: the hook does network
+                        // I/O, and running it inline would add that latency to the start of every session.
                         timeout: HOOK_TIMEOUT_SECONDS,
                         async: true,
                     },

package/dist/src/lib/codex-config.d.ts

@@ -0,0 +1,87 @@
+export declare const CODEX_CONFIG_FILENAME = "config.toml";
+export declare const CODEX_HOOKS_FILENAME = "hooks.json";
+export declare const CODEX_LOGS_PATH = "/v1/logs";
+export declare const CODEX_HOOK_TIMEOUT_SECONDS: {
+    SessionStart: number;
+    SessionEnd: number;
+};
+declare const HOOK_EVENTS: readonly ["SessionStart", "SessionEnd"];
+/** Exported so callers can tell "none approved" from "some approved". */
+export declare const HOOK_EVENT_COUNT: 2;
+type HookEvent = (typeof HOOK_EVENTS)[number];
+type TomlTable = Record<string, unknown>;
+export declare class CodexConfigParseError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+export declare function codexConfigDir(): string;
+export declare function codexConfigPath(): string;
+export declare function codexHooksPath(): string;
+export declare function readCodexConfig(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    text: string;
+    config: TomlTable;
+};
+export declare function buildCodexOtel(input: {
+    token: string;
+    endpoint: string;
+}): TomlTable;
+export declare function spliceOtelSection(text: string, otel: TomlTable | null): string;
+export declare function writeCodexConfig(input: {
+    path?: string;
+    previousText: string;
+    previousConfig: TomlTable;
+    nextText: string;
+}): {
+    backupPath: string | null;
+};
+/** What config.toml currently declares, for `status` and `doctor`. */
+export declare function readCodexTelemetry(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    token: string | null;
+    /** The receiver base, with `/v1/logs` stripped back off. */
+    endpoint: string | null;
+    protocol: string | null;
+    logUserPrompt: boolean | null;
+};
+export declare function applyCodexOtel(current: {
+    text: string;
+    config: TomlTable;
+}, input: {
+    token: string;
+    endpoint: string;
+}): string;
+export declare function removeCodexOtel(current: {
+    text: string;
+    config: TomlTable;
+}): {
+    nextText: string;
+    removedKeys: string[];
+};
+export declare function readCodexHooks(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    file: Record<string, unknown>;
+    commands: Partial<Record<HookEvent, string>>;
+};
+export declare function applyCodexHooks(file: Record<string, unknown>, input: {
+    hookCommand: string;
+}): Record<string, unknown>;
+export declare function removeCodexHooks(file: Record<string, unknown>): {
+    file: Record<string, unknown>;
+    removed: boolean;
+};
+export declare function writeCodexHooks(file: Record<string, unknown>, path?: string): {
+    backupPath: string | null;
+};
+export declare function readCodexHookTrust(path?: string): {
+    trusted: HookEvent[];
+    untrusted: HookEvent[];
+};
+export {};
+//# sourceMappingURL=codex-config.d.ts.map

package/dist/src/lib/codex-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-config.d.ts","sourceRoot":"","sources":["../../../src/lib/codex-config.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/codex-config.js

@@ -0,0 +1,399 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+// Reads and edits Codex CLI's configuration on the user's behalf.
+//
+// Codex splits what Claude Code keeps in one file: telemetry in
+// `~/.codex/config.toml` under `[otel]`, hooks in `~/.codex/hooks.json`. Both follow
+// the same two rules as `claude-settings.ts` — never write over something we could
+// not parse, only ever touch keys we put there — plus a third that TOML forces:
+//
+// Splice, don't re-serialise. A round trip through a TOML parser throws away every
+// comment and blank line, and `config.toml` is hand-written and annotated. Only the
+// `[otel]` region is replaced textually; `writeCodexConfig` re-parses the result and
+// refuses to write if anything outside `[otel]` moved, which is what makes that safe.
+//
+// Two Codex behaviours matter here:
+//
+// - `otel.exporter` is the *log* exporter, and Codex POSTs to the URL verbatim — it
+//   does not append `/v1/logs` the way the OTel SDK does. The path is part of the
+//   configured endpoint, and `readCodexTelemetry` strips it back off.
+// - Codex will not run a `hooks.json` it has not been shown: the first session after
+//   this file changes prompts "Hooks need review" and persists the answer under
+//   `[hooks.state]`. Setup cannot do that for the user, so it tells them — see
+//   `setup.ts`.
+export const CODEX_CONFIG_FILENAME = "config.toml";
+export const CODEX_HOOKS_FILENAME = "hooks.json";
+// The receiver path Codex's log exporter is pointed at. Load-bearing both ways:
+// written onto the endpoint because Codex sends to the literal URL, and stripped when
+// reading because the hook and `/v1/verify` need the base.
+export const CODEX_LOGS_PATH = "/v1/logs";
+// Seconds Codex will wait for each hook. SessionEnd is 3 rather than 10 because Codex
+// hard-clamps it to 3 and otherwise prints a warning on every session start — a
+// permanent warning about a value we chose is worse than the shorter budget, and the
+// hook's own request timeout is 4s.
+export const CODEX_HOOK_TIMEOUT_SECONDS = { SessionStart: 10, SessionEnd: 3 };
+const HOOK_EVENTS = ["SessionStart", "SessionEnd"];
+/** Exported so callers can tell "none approved" from "some approved". */
+export const HOOK_EVENT_COUNT = HOOK_EVENTS.length;
+export class CodexConfigParseError extends Error {
+    path;
+    constructor(path, detail) {
+        super(`${path} is not valid ${path.endsWith(".json") ? "JSON" : "TOML"} (${detail}). Fix or move it, then run 'clocktopus agent setup' again.`);
+        this.path = path;
+        this.name = "CodexConfigParseError";
+    }
+}
+export function codexConfigDir() {
+    // Codex honours CODEX_HOME; following it means setup writes where that installation
+    // actually reads.
+    return process.env.CODEX_HOME || join(homedir(), ".codex");
+}
+export function codexConfigPath() {
+    return join(codexConfigDir(), CODEX_CONFIG_FILENAME);
+}
+export function codexHooksPath() {
+    return join(codexConfigDir(), CODEX_HOOKS_FILENAME);
+}
+export function readCodexConfig(path = codexConfigPath()) {
+    if (!existsSync(path)) {
+        return { path, exists: false, modifiedAt: null, text: "", config: {} };
+    }
+    const text = readFileSync(path, "utf8");
+    const modifiedAt = statSync(path).mtime;
+    try {
+        const parsed = parseToml(text);
+        return { path, exists: true, modifiedAt, text, config: parsed };
+    }
+    catch (error) {
+        throw new CodexConfigParseError(path, error instanceof Error ? error.message : "unknown error");
+    }
+}
+function asTable(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** The `[otel]` keys `clocktopus agent setup` owns — and the only ones it removes. */
+const OWNED_OTEL_KEYS = ["exporter", "log_user_prompt"];
+export function buildCodexOtel(input) {
+    const endpoint = `${input.endpoint.replace(/\/$/, "")}${CODEX_LOGS_PATH}`;
+    return {
+        // The receiver answers protobuf with an explicit 415, and only JSON actually works.
+        // Codex's default for this exporter is `binary`.
+        exporter: {
+            "otlp-http": {
+                endpoint,
+                protocol: "json",
+                headers: { Authorization: `Bearer ${input.token}` },
+            },
+        },
+        // Already the default, set explicitly anyway. It does not cover tool output — Codex
+        // has a single log exporter and no switch for that, which is why the receiver's
+        // allowlist, not this line, is what actually holds.
+        log_user_prompt: false,
+    };
+}
+// Replaces the `[otel]` region of a TOML document, preserving everything else.
+// Region detection is deliberately dumb — table headers only — and `writeCodexConfig`
+// verifies by re-parsing, so a document this misreads is refused rather than mangled.
+export function spliceOtelSection(text, otel) {
+    const rendered = otel && Object.keys(otel).length > 0
+        ? stringifyToml({ otel }).trimEnd()
+        : null;
+    const lines = text.split("\n");
+    const isOurHeader = (line) => /^\s*\[\s*otel\s*\]/.test(line) || /^\s*\[\s*otel\s*\./.test(line);
+    const isAnyHeader = (line) => /^\s*\[/.test(line);
+    let start = -1;
+    let end = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (start === -1) {
+            if (isOurHeader(line))
+                start = i;
+            continue;
+        }
+        if (isAnyHeader(line) && !isOurHeader(line)) {
+            end = i;
+            break;
+        }
+    }
+    if (start === -1) {
+        if (!rendered)
+            return text;
+        const body = text.trimEnd();
+        return body ? `${body}\n\n${rendered}\n` : `${rendered}\n`;
+    }
+    const before = lines.slice(0, start);
+    const after = lines.slice(end);
+    const middle = rendered ? rendered.split("\n") : [];
+    // Drop the blank line that separated a removed section from what follows, so repeated
+    // add/remove cycles cannot pile up empty lines.
+    if (!rendered) {
+        while (before.length > 0 && before[before.length - 1]?.trim() === "")
+            before.pop();
+        if (before.length > 0 && after.length > 0)
+            before.push("");
+    }
+    return `${[...before, ...middle, ...after].join("\n").trimEnd()}\n`;
+}
+// Writes config.toml, keeping a one-deep backup and verifying the splice.
+//
+// The verification is the point: it re-parses what is about to be written and compares
+// every top-level key except `otel` against what was there before. If the splice
+// disturbed anything else, the write is refused with the user's file still intact.
+export function writeCodexConfig(input) {
+    const path = input.path ?? codexConfigPath();
+    let nextConfig;
+    try {
+        nextConfig = parseToml(input.nextText);
+    }
+    catch (error) {
+        throw new Error(`Refusing to write ${path}: the edit did not produce valid TOML (${error instanceof Error ? error.message : "unknown error"}). Nothing was changed.`);
+    }
+    for (const key of new Set([
+        ...Object.keys(input.previousConfig),
+        ...Object.keys(nextConfig),
+    ])) {
+        if (key === "otel")
+            continue;
+        if (JSON.stringify(input.previousConfig[key]) !==
+            JSON.stringify(nextConfig[key])) {
+            throw new Error(`Refusing to write ${path}: editing [otel] would have changed [${key}] as well. ` +
+                "Nothing was changed — please add the [otel] section by hand, or move the file aside.");
+        }
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    let backupPath = null;
+    if (existsSync(path)) {
+        backupPath = `${path}.clocktopus-backup`;
+        copyFileSync(path, backupPath);
+    }
+    // Rename rather than write in place: a crash midway leaves either the old file or the
+    // new one, never a truncated config Codex would refuse to start with.
+    const temporaryPath = `${path}.clocktopus-tmp`;
+    writeFileSync(temporaryPath, input.nextText, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    renameSync(temporaryPath, path);
+    return { backupPath };
+}
+/** What config.toml currently declares, for `status` and `doctor`. */
+export function readCodexTelemetry(path = codexConfigPath()) {
+    const { exists, modifiedAt, config } = readCodexConfig(path);
+    const otel = asTable(config.otel);
+    const http = asTable(asTable(otel.exporter)["otlp-http"]);
+    const headers = asTable(http.headers);
+    const authorization = typeof headers.Authorization === "string"
+        ? headers.Authorization
+        : typeof headers.authorization === "string"
+            ? headers.authorization
+            : null;
+    const rawEndpoint = typeof http.endpoint === "string" ? http.endpoint : null;
+    return {
+        path,
+        exists,
+        modifiedAt,
+        token: authorization?.replace(/^Bearer\s+/i, "").trim() || null,
+        endpoint: rawEndpoint
+            ? rawEndpoint.replace(new RegExp(`${CODEX_LOGS_PATH}/?$`), "")
+            : null,
+        protocol: typeof http.protocol === "string" ? http.protocol : null,
+        logUserPrompt: typeof otel.log_user_prompt === "boolean" ? otel.log_user_prompt : null,
+    };
+}
+export function applyCodexOtel(current, input) {
+    const merged = {
+        ...asTable(current.config.otel),
+        ...buildCodexOtel(input),
+    };
+    return spliceOtelSection(current.text, merged);
+}
+export function removeCodexOtel(current) {
+    const otel = { ...asTable(current.config.otel) };
+    const removedKeys = [];
+    for (const key of OWNED_OTEL_KEYS) {
+        if (key in otel) {
+            delete otel[key];
+            removedKeys.push(key);
+        }
+    }
+    return {
+        nextText: spliceOtelSection(current.text, Object.keys(otel).length > 0 ? otel : null),
+        removedKeys,
+    };
+}
+export function readCodexHooks(path = codexHooksPath()) {
+    if (!existsSync(path)) {
+        return {
+            path,
+            exists: false,
+            modifiedAt: null,
+            file: {},
+            commands: {},
+        };
+    }
+    const raw = readFileSync(path, "utf8");
+    const modifiedAt = statSync(path).mtime;
+    let file = {};
+    if (raw.trim() !== "") {
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error("expected an object");
+            }
+            file = parsed;
+        }
+        catch (error) {
+            throw new CodexConfigParseError(path, error instanceof Error ? error.message : "unknown error");
+        }
+    }
+    const hooks = asTable(file.hooks);
+    const commands = {};
+    for (const event of HOOK_EVENTS) {
+        for (const group of asGroups(hooks[event])) {
+            const ours = (group.hooks ?? []).find(isClocktopusHook);
+            if (ours?.command) {
+                commands[event] = ours.command;
+                break;
+            }
+        }
+    }
+    return { path, exists: true, modifiedAt, file, commands };
+}
+function isClocktopusHook(entry) {
+    const command = typeof entry.command === "string" ? entry.command : "";
+    return /clocktopus/i.test(command) && /agent\s+hook/.test(command);
+}
+function asGroups(value) {
+    return Array.isArray(value) ? value : [];
+}
+function withoutOurHooks(groups) {
+    return groups
+        .map((group) => ({
+        ...group,
+        hooks: (group.hooks ?? []).filter((entry) => !isClocktopusHook(entry)),
+    }))
+        .filter((group) => (group.hooks ?? []).length > 0);
+}
+export function applyCodexHooks(file, input) {
+    const existing = asTable(file.hooks);
+    const hooks = { ...existing };
+    for (const event of HOOK_EVENTS) {
+        // Remove-then-append rather than append: re-running setup must not leave two hooks
+        // firing per session, which would double every SessionStart POST.
+        hooks[event] = [
+            ...withoutOurHooks(asGroups(existing[event])),
+            {
+                hooks: [
+                    {
+                        type: "command",
+                        command: input.hookCommand,
+                        timeout: CODEX_HOOK_TIMEOUT_SECONDS[event],
+                        // No `async` key, deliberately. Codex 0.147 *skips* an async SessionStart outright —
+                        // costing every session its repository context — and every version so far still runs
+                        // an async SessionEnd synchronously and warns once per session. `agent hook`
+                        // backgrounds itself instead, which is correct and quiet on all of them.
+                    },
+                ],
+            },
+        ];
+    }
+    return {
+        // Codex shows this string when it asks the user to trust the file, so it is the one
+        // chance to say where it came from.
+        description: typeof file.description === "string" && file.description
+            ? file.description
+            : "Clocktopus agent telemetry",
+        ...file,
+        hooks,
+    };
+}
+export function removeCodexHooks(file) {
+    const existing = asTable(file.hooks);
+    const hooks = { ...existing };
+    let removed = false;
+    for (const event of HOOK_EVENTS) {
+        const before = asGroups(existing[event]);
+        const after = withoutOurHooks(before);
+        if (JSON.stringify(before) !== JSON.stringify(after))
+            removed = true;
+        if (after.length > 0)
+            hooks[event] = after;
+        else
+            delete hooks[event];
+    }
+    const next = { ...file };
+    if (Object.keys(hooks).length > 0)
+        next.hooks = hooks;
+    else
+        delete next.hooks;
+    return { file: next, removed };
+}
+export function writeCodexHooks(file, path = codexHooksPath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    let backupPath = null;
+    if (existsSync(path)) {
+        backupPath = `${path}.clocktopus-backup`;
+        copyFileSync(path, backupPath);
+    }
+    const temporaryPath = `${path}.clocktopus-tmp`;
+    writeFileSync(temporaryPath, `${JSON.stringify(file, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    renameSync(temporaryPath, path);
+    return { backupPath };
+}
+// Which of our hooks Codex has been shown and told to run.
+//
+// Trust is recorded per hook *entry*, not per file, keyed
+// `<path>:<event>:<group index>:<hook index>` with the event in snake_case:
+//
+//   [hooks.state."/home/you/.codex/hooks.json:session_end:0:0"]
+//   trusted_hash = "sha256:…"
+//
+// Per-entry granularity is why this reports each event rather than a single boolean:
+// partial trust is a real state, and the one that matters. A machine whose SessionEnd
+// is trusted and whose SessionStart is not records spend with no repository attached.
+//
+// The hash is Codex's own and is not recomputed here; changing `hooks.json`
+// invalidates it and Codex re-prompts, which is the behaviour we want.
+export function readCodexHookTrust(path = codexConfigPath()) {
+    let config;
+    try {
+        ({ config } = readCodexConfig(path));
+    }
+    catch {
+        return { trusted: [], untrusted: [...HOOK_EVENTS] };
+    }
+    const state = asTable(asTable(config.hooks).state);
+    const prefix = `${codexHooksPath()}:`;
+    const trusted = new Set();
+    for (const [key, value] of Object.entries(state)) {
+        if (!key.startsWith(prefix))
+            continue;
+        // `enabled` is optional and version-dependent: 0.147 wrote `enabled = true` next to
+        // the hash, 0.148 persists `trusted_hash` alone. Requiring it read a freshly approved
+        // 0.148 install as pending forever. Absent means approved; only an explicit `false`
+        // counts as untrusted.
+        const entry = asTable(value);
+        if (entry.enabled === false || typeof entry.trusted_hash !== "string")
+            continue;
+        // `<path>:<event>:<group>:<index>` — sliced by prefix length rather than split, since
+        // a path could in principle contain a colon.
+        const event = key.slice(prefix.length).split(":")[0];
+        const match = HOOK_EVENTS.find((candidate) => toSnakeCase(candidate) === event);
+        if (match)
+            trusted.add(match);
+    }
+    return {
+        trusted: HOOK_EVENTS.filter((event) => trusted.has(event)),
+        untrusted: HOOK_EVENTS.filter((event) => !trusted.has(event)),
+    };
+}
+function toSnakeCase(event) {
+    return event.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}

package/dist/src/lib/codex-config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codex-config.test.d.ts.map

package/dist/src/lib/codex-config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-config.test.d.ts","sourceRoot":"","sources":["../../../src/lib/codex-config.test.ts"],"names":[],"mappings":""}