@blastin-dev/clocktopus-cli 0.2.0 → 0.2.1

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

@@ -0,0 +1,166 @@
+/**
+ * Reads and edits Codex CLI's configuration on the user's behalf.
+ *
+ * Codex splits what Claude Code keeps in one file: telemetry goes in
+ * `~/.codex/config.toml` under `[otel]`, hooks go in a separate
+ * `~/.codex/hooks.json`. Both are edited here under the same two rules as
+ * `claude-settings.ts` — never write over something we could not parse, and
+ * only ever touch keys we put there — plus a third that TOML forces on us:
+ *
+ * **Splice, don't re-serialise.** A round trip through a TOML parser throws
+ * away every comment and blank line in the file. `config.toml` is a file
+ * people hand-write and annotate, so only the `[otel]` region is replaced
+ * textually; everything else survives byte for byte. `writeCodexConfig`
+ * re-parses the spliced result and refuses to write if anything outside
+ * `[otel]` moved, which is what makes the textual approach safe.
+ *
+ * ## What Codex does with these, and why it matters 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 therefore part of the configured endpoint, and
+ *   `readCodexTelemetry` strips it back off to recover the receiver base.
+ * - 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 instead — see `setup.ts`.
+ */
+export declare const CODEX_CONFIG_FILENAME = "config.toml";
+export declare const CODEX_HOOKS_FILENAME = "hooks.json";
+/**
+ * The receiver path Codex's log exporter is pointed at.
+ *
+ * Load-bearing in both directions: 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 declare 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
+ * prints `warning: clamping SessionEnd hook timeout to 3s` on every single
+ * session start otherwise — a permanent warning about a value we chose is
+ * worse than the shorter budget, and the hook's own request timeout is 4s.
+ */
+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;
+/**
+ * Replaces the `[otel]` region of a TOML document, preserving everything else.
+ *
+ * Returns the new text. Region detection is deliberately dumb — table
+ * headers only — and `writeCodexConfig` verifies the result by re-parsing,
+ * so a document this misreads is refused rather than mangled.
+ */
+export declare function spliceOtelSection(text: string, otel: TomlTable | null): string;
+/**
+ * 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 textual splice disturbed anything else — an exotic layout
+ * the region scanner misread — the write is refused with the user's file
+ * still intact.
+ */
+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;
+};
+/**
+ * Which of our hooks Codex has been shown and told to run.
+ *
+ * Trust is recorded **per hook entry**, not per file:
+ *
+ * ```toml
+ * [hooks.state."/home/you/.codex/hooks.json:session_end:0:0"]
+ * trusted_hash = "sha256:…"
+ * ```
+ *
+ * The key is `<path>:<event>:<group index>:<hook index>`, with the event in
+ * snake_case. 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 to it — which is exactly
+ * what an `async: true` SessionStart used to produce on Codex 0.147, since
+ * the hook was skipped before it could ever be offered for approval.
+ *
+ * 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 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":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AACnD,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,aAAa,CAAC;AAE1C;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;CAAsC,CAAC;AAE9E,QAAA,MAAM,WAAW,yCAA0C,CAAC;AAE5D,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,GAAqB,CAAC;AACnD,KAAK,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzC,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,MAAM,EAAE,MAAM;CAOjB;AAED,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAMD,wBAAgB,eAAe,CAAC,IAAI,SAAoB,GAAG;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,CAAC;CACnB,CAiBA;AAWD,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,SAAS,CAoBZ;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,GAAG,IAAI,GACrB,MAAM,CA6CR;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,SAAS,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiDhC;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,IAAI,SAAoB,GAAG;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B,CA4BA;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,EAC5C,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzC,MAAM,CAMR;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAkBA;AASD,wBAAgB,cAAc,CAAC,IAAI,SAAmB,GAAG;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;CAC9C,CA2CA;AAoBD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuCzB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC/D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB,CAkBA;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,SAAmB,GACtB;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiB/B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,SAAoB,GAAG;IAC5D,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,SAAS,EAAE,SAAS,EAAE,CAAC;CACxB,CAuCA"}

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

@@ -0,0 +1,441 @@
+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 goes in
+ * `~/.codex/config.toml` under `[otel]`, hooks go in a separate
+ * `~/.codex/hooks.json`. Both are edited here under the same two rules as
+ * `claude-settings.ts` — never write over something we could not parse, and
+ * only ever touch keys we put there — plus a third that TOML forces on us:
+ *
+ * **Splice, don't re-serialise.** A round trip through a TOML parser throws
+ * away every comment and blank line in the file. `config.toml` is a file
+ * people hand-write and annotate, so only the `[otel]` region is replaced
+ * textually; everything else survives byte for byte. `writeCodexConfig`
+ * re-parses the spliced result and refuses to write if anything outside
+ * `[otel]` moved, which is what makes the textual approach safe.
+ *
+ * ## What Codex does with these, and why it matters 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 therefore part of the configured endpoint, and
+ *   `readCodexTelemetry` strips it back off to recover the receiver base.
+ * - 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 instead — 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 in both directions: 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
+ * prints `warning: clamping SessionEnd hook timeout to 3s` on every single
+ * session start otherwise — 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);
+}
+/* -------------------------------------------------------------------------
+ * config.toml
+ * ---------------------------------------------------------------------- */
+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: the receiver never reads
+        // the `prompt` attribute, but not sending it at all is one fewer thing
+        // in flight. 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.
+ *
+ * Returns the new text. Region detection is deliberately dumb — table
+ * headers only — and `writeCodexConfig` verifies the result 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 textual splice disturbed anything else — an exotic layout
+ * the region scanner misread — 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 hook outright — costing every session its
+                        // repository context, with only a startup warning to say so —
+                        // and every version so far still runs an async SessionEnd
+                        // synchronously and warns about it once per session. `agent
+                        // hook` backgrounds itself instead, which is correct on all of
+                        // them 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:
+ *
+ * ```toml
+ * [hooks.state."/home/you/.codex/hooks.json:session_end:0:0"]
+ * trusted_hash = "sha256:…"
+ * ```
+ *
+ * The key is `<path>:<event>:<group index>:<hook index>`, with the event in
+ * snake_case. 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 to it — which is exactly
+ * what an `async: true` SessionStart used to produce on Codex 0.147, since
+ * the hook was skipped before it could ever be offered for approval.
+ *
+ * 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: Codex 0.147 wrote
+        // `enabled = true` next to the hash, 0.148 persists `trusted_hash`
+        // alone (its `HookStateToml` has no such field) and leaves any older
+        // key untouched. Requiring it read a freshly approved 0.148 install as
+        // pending forever. Absent means approved; only an explicit `false`
+        // — a hook the user disabled — counts as untrusted.
+        const entry = asTable(value);
+        if (entry.enabled === false || typeof entry.trusted_hash !== "string")
+            continue;
+        // `<path>:<event>:<group>:<index>` — the event is the segment after the
+        // path, which may itself contain colons on no sane platform but is
+        // sliced by prefix length rather than split, just in case.
+        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":""}