@blastin-dev/clocktopus-cli 0.2.0 → 0.2.1

package/dist/src/commands/agent/setup.js

@@ -1,45 +1,62 @@
 import { existsSync } from "node:fs";
 import { hostname } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { findShadowedExports, maskToken, resolveHookCommand, } from "../../lib/agent-config.js";
 import { verifyReceiver } from "../../lib/agent-receiver.js";
+import { isConfigParseError, surveyAgents } from "../../lib/agents.js";
 import { ApiError, get, post } from "../../lib/api.js";
-import { applyTelemetrySettings, claudeConfigDir, readInstalledTelemetry, readSettings, SettingsParseError, writeSettings, } from "../../lib/claude-settings.js";
 import { isLoggedIn, setAgentConfig } from "../../lib/config.js";
 import { labelled } from "../../lib/format.js";
 import { fetchRepoStatus, renderRepoBlock } from "../../lib/repo-guidance.js";
 import { AgentEndpointSchema, IngestTokenSchema, UserSchema, } from "../../lib/validators.js";
 /**
- * Configures this machine to report agent spend to Clocktopus.
+ * Configures this machine's coding agents to report spend to Clocktopus.
  *
- * Everything lands in one file — `~/.claude/settings.json` — holding both
- * the exporter's environment and the session hooks. A single source of
- * truth is not a tidiness preference: it is what makes `agent doctor` able
- * to say which value is in force. Configuration spread over `.envrc`, a
- * shell profile and a CLI config file can be reported on but never
- * resolved, and this project already lost real spend to exactly that (one
- * session split across two accounts, silently, because two files disagreed
- * about the token).
+ * One command, however many agents are installed. It looks for each
+ * supported CLI on PATH and configures what it finds — silently when
+ * there is only one, after a prompt when there are several, and from
+ * `--agent` when there is neither a person nor a terminal to ask.
+ *
+ * Everything for a given agent lands in that agent's own config, and
+ * nowhere else. A single source of truth per agent is not a tidiness
+ * preference: it is what makes `agent doctor` able to say which value is in
+ * force. Configuration spread over `.envrc`, a shell profile and a CLI
+ * config file can be reported on but never resolved, and this project
+ * already lost real spend to exactly that (one session split across two
+ * accounts, silently, because two files disagreed about the token).
  *
  * Idempotent by default. Re-running repairs the hooks and refreshes the
  * endpoint while keeping the existing token, so the common case — "did my
- * setup drift?" — costs nothing. `--force` mints a replacement instead.
+ * setup drift?" — costs nothing, and adding a newly-installed agent later
+ * reuses the token the first one already has. `--force` mints a
+ * replacement instead.
  */
 export async function setupCommand(options) {
     if (!isLoggedIn()) {
         console.error("Not logged in. Run 'clocktopus login' first.");
         process.exit(1);
     }
-    let installed;
-    try {
-        installed = readInstalledTelemetry();
+    const survey = surveyAgents();
+    const unreadable = survey.filter((entry) => entry.unreadable);
+    if (unreadable.length > 0) {
+        for (const entry of unreadable)
+            console.error(`✗ ${entry.unreadable}`);
+        process.exit(1);
     }
-    catch (error) {
-        if (error instanceof SettingsParseError) {
-            console.error(`✗ ${error.message}`);
-            process.exit(1);
-        }
-        throw error;
+    const installed = survey.filter((entry) => entry.installed);
+    if (installed.length === 0) {
+        console.error("No supported coding agent found on PATH.");
+        console.error(`\nClocktopus can track: ${survey
+            .map((entry) => `${entry.agent.label} (${entry.agent.binary})`)
+            .join(", ")}.`);
+        console.error("Install one, or re-run with --agent <id> if yours lives somewhere PATH\ncannot see.");
+        process.exit(1);
+    }
+    const selected = await selectAgents(survey, installed, options.agent);
+    if (selected.length === 0) {
+        console.log("Nothing selected — no configuration was changed.");
+        return;
     }
     let email = null;
     let endpoint;
@@ -55,14 +72,15 @@ export async function setupCommand(options) {
         reportApiFailure(error, "Failed to reach Clocktopus");
         return;
     }
-    // Reuse before minting. Every mint leaves another live token on the
-    // account, and a machine that already has a working one has nothing to
-    // gain from a second — the reason to re-run setup is almost always a
-    // broken hook path, not a bad token.
-    let token = installed.env.CLOCKTOPUS_INGEST_TOKEN ?? null;
+    // One machine, one token, however many agents. Reuse before minting:
+    // every mint leaves another live token on the account, and a machine that
+    // already has a working one has nothing to gain from a second — the
+    // reason to re-run setup is almost always a broken hook path or a newly
+    // installed agent, not a bad token.
+    let token = options.force ? null : findExistingToken(survey);
     let tokenId = null;
     let minted = false;
-    if (token && !options.force) {
+    if (token) {
         const check = await verifyReceiver(endpoint, token);
         if (!check.ok) {
             console.log(check.reason === "invalid_token"
@@ -71,13 +89,10 @@ export async function setupCommand(options) {
             token = null;
         }
     }
-    else if (options.force) {
-        token = null;
-    }
     if (!token) {
         try {
             const response = await post("/api/agent/ingest-token", {
-                name: options.name ?? `${hostname()} (claude code)`,
+                name: options.name ?? hostname(),
             }).then((data) => IngestTokenSchema.parse(data));
             token = response.token;
             tokenId = response.tokenId;
@@ -89,19 +104,30 @@ export async function setupCommand(options) {
             return;
         }
     }
-    const hook = resolveHookCommand();
-    let backupPath = null;
-    try {
-        const current = readSettings();
-        const next = applyTelemetrySettings(current.settings, {
-            token,
-            endpoint,
-            hookCommand: hook.command,
-        });
-        ({ backupPath } = writeSettings(next, current.path));
+    const configured = [];
+    for (const entry of selected) {
+        const hook = resolveHookCommand(entry.agent.provider);
+        try {
+            const { backupPaths } = entry.agent.apply({
+                token,
+                endpoint,
+                hookCommand: hook.command,
+            });
+            configured.push({
+                entry,
+                hookCommand: hook.command,
+                hookUsesAbsolutePath: hook.usesAbsolutePath,
+                backupPaths,
+            });
+        }
+        catch (error) {
+            // One agent failing must not strand the others half-configured, so
+            // the loop continues and the failure is reported in the summary.
+            console.error(`✗ ${entry.agent.label}: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
     }
-    catch (error) {
-        console.error(`✗ Could not write ${installed.path}: ${error instanceof Error ? error.message : "unknown error"}`);
+    if (configured.length === 0) {
+        console.error("\nNothing was configured.");
         process.exit(1);
     }
     setAgentConfig({
@@ -116,10 +142,15 @@ export async function setupCommand(options) {
         console.log(labelled("Account", email));
     console.log(labelled("Receiver", endpoint));
     console.log(labelled("Token", `${maskToken(token)}${minted ? "  (new)" : "  (reused)"}`));
-    console.log(labelled("Settings", installed.path));
-    console.log(labelled("Hook", `${hook.command}  (SessionStart, SessionEnd)`));
-    if (backupPath)
-        console.log(labelled("Backup", backupPath));
+    for (const { entry, hookCommand, backupPaths } of configured) {
+        console.log(`\n${entry.agent.label} ${entry.version ?? ""}`.trimEnd());
+        for (const path of entry.agent.paths()) {
+            console.log(labelled("Config", path));
+        }
+        console.log(labelled("Hook", `${hookCommand}  (SessionStart, SessionEnd)`));
+        for (const backup of backupPaths)
+            console.log(labelled("Backup", backup));
+    }
     console.log("");
     console.log(check.ok
         ? "✓ The receiver accepted this token."
@@ -133,43 +164,151 @@ export async function setupCommand(options) {
         for (const line of renderRepoBlock(repoStatus))
             console.log(line);
     }
-    for (const warning of collectWarnings({
-        hookUsesAbsolutePath: hook.usesAbsolutePath,
-    })) {
+    for (const warning of collectWarnings(configured)) {
         console.log(`\n${warning}`);
     }
     // The single most common reason a correct setup appears dead. Both the
-    // OTLP exporter and the hook read their configuration once, when the
-    // process starts, so a session already running will never see any of this.
-    console.log("\nRestart Claude Code — the exporter and the hook read their configuration\nonce, at process start.");
+    // exporter and the hook read their configuration once, when the process
+    // starts, so a session already running will never see any of this.
+    console.log(`\nRestart ${labelList(configured.map((c) => c.entry.agent.label))} — the exporter and the hook\nread their configuration once, at process start.`);
+    // Agent-specific steps a person still has to take, most importantly
+    // Codex's hook trust prompt, which no command can answer for them.
+    for (const { entry } of configured) {
+        for (const action of entry.agent.pendingActions()) {
+            console.log(`\n→ ${entry.agent.label}: ${action}`);
+        }
+    }
     console.log("\nThen confirm it end to end:  clocktopus agent status");
 }
-function collectWarnings(input) {
+/**
+ * Decides which agents to configure, asking only when the answer is
+ * genuinely ambiguous.
+ *
+ * The precedence is about respecting what the caller already told us:
+ * `--agent` is an explicit instruction, a lone install has no decision in
+ * it, and a non-interactive shell has nobody to ask — so only a person at a
+ * terminal with a real choice ever sees a prompt.
+ */
+async function selectAgents(survey, installed, requested) {
+    if (requested && requested.length > 0) {
+        const ids = requested.flatMap((value) => value.split(",").map((part) => part.trim().toLowerCase()));
+        const chosen = survey.filter((entry) => ids.includes(entry.agent.id));
+        const unknown = ids.filter((id) => !survey.some((entry) => entry.agent.id === id));
+        if (unknown.length > 0) {
+            console.error(`Unknown agent: ${unknown.join(", ")}. Valid ids: ${survey
+                .map((entry) => entry.agent.id)
+                .join(", ")}.`);
+            process.exit(1);
+        }
+        // Deliberately not filtered by `installed`: --agent is an instruction,
+        // and someone pointing it at an agent PATH cannot see has said what they
+        // want. Setup writes the config; the agent picks it up when it appears.
+        for (const entry of chosen) {
+            if (!entry.installed) {
+                console.log(`⚠ ${entry.agent.label} was not found on PATH — configuring it anyway.`);
+            }
+        }
+        return chosen;
+    }
+    if (installed.length === 1)
+        return installed;
+    if (!process.stdin.isTTY) {
+        console.log(`Configuring every agent found: ${labelList(installed.map((entry) => entry.agent.label))}.\nPass --agent <id> to narrow it.`);
+        return installed;
+    }
+    console.log("\nAgents on this machine\n");
+    installed.forEach((entry, index) => {
+        const state = entry.configured ? "already configured" : "not configured";
+        console.log(`  ${index + 1}  ${entry.agent.label.padEnd(14)}${(entry.version ?? "").padEnd(10)}${state}`);
+    });
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question("\nWhich should report to Clocktopus? [all]: ")).trim();
+        if (answer === "" || answer.toLowerCase() === "all")
+            return installed;
+        const picked = answer
+            .split(/[,\s]+/)
+            .filter(Boolean)
+            .flatMap((part) => {
+            const index = Number(part);
+            if (Number.isInteger(index) && index >= 1 && index <= installed.length)
+                return [installed[index - 1]];
+            const byId = installed.find((entry) => entry.agent.id === part.toLowerCase() ||
+                entry.agent.binary === part.toLowerCase());
+            return byId ? [byId] : [];
+        });
+        return [...new Set(picked)];
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * The token this machine already has, from whichever agent holds one.
+ *
+ * Reading across agents is what makes "install Codex next month and re-run
+ * setup" cost nothing: the new agent inherits the token the old one has
+ * been using rather than minting a second one against the same machine.
+ */
+function findExistingToken(survey) {
+    for (const entry of survey) {
+        try {
+            const token = entry.agent.read().token;
+            if (token)
+                return token;
+        }
+        catch (error) {
+            if (!isConfigParseError(error))
+                throw error;
+        }
+    }
+    return null;
+}
+function collectWarnings(configured) {
     const warnings = [];
-    const shadowed = findShadowedExports();
-    if (shadowed.length > 0) {
-        const lines = shadowed
-            .map(({ path, keys }) => `    ${path} — ${keys.join(", ")}`)
-            .join("\n");
-        warnings.push(`⚠ These files export the same variables:\n${lines}\n` +
-            "  settings.json is applied over the inherited environment, so those\n" +
-            "  exports are now ignored inside Claude Code. Remove them — two\n" +
-            "  sources that disagree is how spend ends up on the wrong account.");
-    }
-    // A versioned settings.json means the ingest token is about to be
+    // Only Claude Code applies config `env` over the inherited environment,
+    // so only Claude Code can silently shadow a shell export. Codex reads its
+    // token straight out of config.toml and has nothing to shadow.
+    if (configured.some(({ entry }) => entry.agent.id === "claude")) {
+        const shadowed = findShadowedExports();
+        if (shadowed.length > 0) {
+            const lines = shadowed
+                .map(({ path, keys }) => `    ${path} — ${keys.join(", ")}`)
+                .join("\n");
+            warnings.push(`⚠ These files export the same variables:\n${lines}\n` +
+                "  settings.json is applied over the inherited environment, so those\n" +
+                "  exports are now ignored inside Claude Code. Remove them — two\n" +
+                "  sources that disagree is how spend ends up on the wrong account.");
+        }
+    }
+    // A versioned config directory means the ingest token is about to be
     // committed. Worth saying plainly; the CLI cannot prevent it.
-    if (existsSync(join(claudeConfigDir(), ".git"))) {
-        warnings.push(`⚠ ${claudeConfigDir()} is a git repository, and settings.json now holds\n` +
-            "  your ingest token in plaintext. Ignore the file, or revoke with\n" +
+    const versioned = new Set();
+    for (const { entry } of configured) {
+        for (const path of entry.agent.paths()) {
+            const dir = dirname(path);
+            if (existsSync(join(dir, ".git")))
+                versioned.add(dir);
+        }
+    }
+    for (const dir of versioned) {
+        warnings.push(`⚠ ${dir} is a git repository, and its config now holds your ingest\n` +
+            "  token in plaintext. Ignore the file, or revoke with\n" +
             "  'clocktopus agent disable --revoke' if it gets committed.");
     }
-    if (input.hookUsesAbsolutePath) {
+    const absolute = configured.filter((c) => c.hookUsesAbsolutePath);
+    if (absolute.length > 0) {
         warnings.push("⚠ 'clocktopus' is not on PATH as this executable, so the hook was\n" +
             "  installed with an absolute path. Reinstalling the CLI elsewhere will\n" +
             "  break it — re-run 'clocktopus agent setup' if that happens.");
     }
     return warnings;
 }
+function labelList(labels) {
+    if (labels.length <= 1)
+        return labels[0] ?? "";
+    return `${labels.slice(0, -1).join(", ")} and ${labels[labels.length - 1]}`;
+}
 function describeCheck(check) {
     switch (check.reason) {
         case "invalid_token":

package/dist/src/commands/agent/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/status.ts"],"names":[],"mappings":"AA8BA,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAoFnD"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/status.ts"],"names":[],"mappings":"AA2BA,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAoFnD"}

package/dist/src/commands/agent/status.js

@@ -1,7 +1,7 @@
 import { differenceInMilliseconds, parseISO } from "date-fns";
 import { readLastRun } from "../../lib/agent-hook-state.js";
+import { isConfigParseError, surveyAgents } from "../../lib/agents.js";
 import { ApiError, get } from "../../lib/api.js";
-import { readInstalledTelemetry, SettingsParseError, } from "../../lib/claude-settings.js";
 import { isLoggedIn } from "../../lib/config.js";
 import { formatAgo, labelled, microUsdToDisplay } from "../../lib/format.js";
 import { AgentStatusSchema } from "../../lib/validators.js";
@@ -9,13 +9,13 @@ import { AgentStatusSchema } from "../../lib/validators.js";
  * Answers "is agent telemetry actually connected?" from received data.
  *
  * Deliberately server-first. Local configuration is a claim — the files can
- * be perfect while nothing arrives, because the exporter reads its
- * environment once at process start, Claude Code swallows OTLP transport
+ * be perfect while nothing arrives, because an exporter reads its
+ * configuration once at process start, agents swallow OTLP transport
  * errors, and a revoked token produces a 401 nobody sees.
  *
  * The two lanes are reported separately because they fail separately, and
- * the asymmetric failure is the expensive one: hooks landing while metrics
- * do not produces sessions with a repository, a branch and no spend, which
+ * the asymmetric failure is the expensive one: hooks landing while spend
+ * does not produces sessions with a repository, a branch and no cost, which
  * reads as cheap work rather than a severed pipeline. A single "connected"
  * line would hide precisely the case worth surfacing.
  */
@@ -55,7 +55,7 @@ export async function statusCommand() {
     if (status.hookLane.attributed === false) {
         console.log(labelled("", "not attributed to a project — see 'agent doctor'", 14));
     }
-    console.log(labelled("Metrics lane", `${mark(metricsAge)}  ${formatAgo(status.metricsLane.lastExportReceivedAt)}`, 14));
+    console.log(labelled("Spend lane", `${mark(metricsAge)}  ${formatAgo(status.metricsLane.lastExportReceivedAt)}`, 14));
     if (status.metricsLane.lastModel) {
         console.log(labelled("", status.metricsLane.lastModel, 14));
     }
@@ -109,15 +109,15 @@ function diagnose(input) {
     if (hookLive && !metricsLive) {
         return [
             "⚠ Sessions are arriving with repository context, but no spend is.\n" +
-                "  The OTLP exporter is not reaching the receiver — every session will\n" +
-                "  show $0.00, which is indistinguishable from cheap work. Check the\n" +
-                "  OTEL_* values with 'clocktopus agent doctor'.",
+                "  The telemetry exporter is not reaching the receiver — every session\n" +
+                "  will show $0.00, which is indistinguishable from cheap work. Check\n" +
+                "  the exporter config with 'clocktopus agent doctor'.",
         ];
     }
     if (metricsLive && !hookLive) {
         return [
             "⚠ Spend is arriving, but no repository context is. The SessionStart /\n" +
-                "  SessionEnd hook is not running, and the metric stream carries no path\n" +
+                "  SessionEnd hook is not running, and no telemetry stream carries path\n" +
                 "  data at all — so these sessions cannot be attributed to a project.\n" +
                 "  Check the hook with 'clocktopus agent doctor'.",
         ];
@@ -126,21 +126,32 @@ function diagnose(input) {
 }
 function readLocalSummary() {
     const lines = [];
-    try {
-        const installed = readInstalledTelemetry();
-        if (!installed.exists || Object.keys(installed.env).length === 0) {
-            lines.push(labelled("Config", "not set up here — run 'clocktopus agent setup'"));
-            return lines;
+    // Every agent, not just the configured ones: an installed agent that is
+    // *not* reporting is the thing worth seeing here, and it is invisible in
+    // the server-side lanes above — its sessions simply never arrive.
+    const survey = surveyAgents().filter((entry) => entry.installed || entry.configured || entry.unreadable);
+    if (survey.length === 0) {
+        lines.push(labelled("Agents", "none found on PATH"));
+        return lines;
+    }
+    let anyConfigured = false;
+    for (const entry of survey) {
+        if (entry.unreadable) {
+            lines.push(labelled(entry.agent.label, "config unreadable — see 'agent doctor'"));
+            continue;
         }
-        lines.push(labelled("Config", installed.path));
-    }
-    catch (error) {
-        if (error instanceof SettingsParseError) {
-            lines.push(labelled("Config", `unreadable — ${error.message}`));
-            return lines;
+        if (!entry.configured) {
+            lines.push(labelled(entry.agent.label, `not reporting — run 'clocktopus agent setup --agent ${entry.agent.id}'`));
+            continue;
         }
-        throw error;
-    }
+        anyConfigured = true;
+        const pending = safePendingActions(entry.agent);
+        lines.push(labelled(entry.agent.label, pending.length > 0
+            ? "configured, waiting on approval — see 'agent doctor'"
+            : "configured"));
+    }
+    if (!anyConfigured)
+        return lines;
     // The hook's own receipt of its last run. It cannot print or warn during a
     // session, so this is the only place a 401 or a connection failure from
     // the machine's side becomes visible.
@@ -151,10 +162,21 @@ function readLocalSummary() {
             : lastRun.status >= 200 && lastRun.status < 300
                 ? `HTTP ${lastRun.status}`
                 : `HTTP ${lastRun.status} — rejected`;
-        lines.push(labelled("Last hook", `${formatAgo(lastRun.at)} (${lastRun.event ?? "?"}) ${outcome}`));
+        lines.push(labelled("Last hook", `${formatAgo(lastRun.at)} (${lastRun.event ?? "?"}${lastRun.provider ? `, ${lastRun.provider}` : ""}) ${outcome}`));
     }
     else {
         lines.push(labelled("Last hook", "has not run since setup"));
     }
     return lines;
 }
+/** `pendingActions` reads config; a broken file must not fail `status`. */
+function safePendingActions(agent) {
+    try {
+        return agent.pendingActions();
+    }
+    catch (error) {
+        if (isConfigParseError(error))
+            return [];
+        throw error;
+    }
+}

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AA4IA,wBAAgB,GAAG,IAAI,IAAI,CAE1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAyKA,wBAAgB,GAAG,IAAI,IAAI,CAE1B"}

package/dist/src/index.js

@@ -16,6 +16,10 @@ const parsedJson = z
     .object({ version: z.string() })
     .safeParse(require("../../package.json"));
 const version = parsedJson.success ? parsedJson.data.version : "0.0.0";
+/** Lets `--agent` be repeated as well as comma-separated. */
+function collect(value, previous = []) {
+    return [...previous, value];
+}
 const program = new Command();
 program
     .name("clocktopus")
@@ -71,9 +75,10 @@ const agent = program
     .description("Track AI agent spend from this machine");
 agent
     .command("setup")
-    .description("Point Claude Code at Clocktopus and install the session hooks")
+    .description("Point your coding agents at Clocktopus and install the session hooks")
     .option("--name <name>", "Label for this machine's ingest token")
     .option("--force", "Mint a replacement token instead of reusing the existing one")
+    .option("-a, --agent <ids>", "Configure only these agents (claude, codex). Repeatable or comma-separated.", collect)
     .action((options) => setupCommand(options));
 agent
     .command("status")
@@ -87,14 +92,23 @@ agent
     .command("disable")
     .description("Remove this machine's telemetry configuration")
     .option("--revoke", "Also revoke the ingest token, everywhere")
+    .option("-a, --agent <ids>", "Remove only these agents (claude, codex). Repeatable or comma-separated.", collect)
     .action((options) => disableCommand(options));
-// Invoked by Claude Code, never by a person: it reads the hook payload from
+// Invoked by an agent, never by a person: it reads the hook payload from
 // stdin and must not write to stdout. Hidden so it does not read as
 // something to run by hand.
+//
+// `--provider` is not a convenience. Claude Code and Codex send byte-identical
+// hook payloads, so the flag baked into the installed command is the only
+// thing that says which agent is calling.
 agent
     .command("hook", { hidden: true })
-    .description("Internal: Claude Code SessionStart/SessionEnd hook")
-    .action(hookCommand);
+    .description("Internal: SessionStart/SessionEnd hook")
+    .option("--provider <provider>", "Which agent installed this hook")
+    // Set only by the hook when it re-spawns itself for an agent that will
+    // not background it. Marks the copy that does the work.
+    .option("--detached", "Internal: this is the backgrounded copy")
+    .action((options) => hookCommand(options));
 export function run() {
     program.parse();
 }

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

@@ -1,3 +1,4 @@
+import type { AgentId, AgentProviderId } from "./agents.js";
 /**
  * Where the ingest credentials come from, and what shadows what.
  *
@@ -8,6 +9,13 @@
  * shell profile, silently. That is the failure this resolver is built to
  * make visible rather than to paper over: it reports the source alongside
  * the value so `doctor` can name the file that is winning.
+ *
+ * Codex is the mirror image and needs its own branch. It injects nothing
+ * into the hook's environment, so `~/.codex/config.toml` is not one source
+ * among several — it is the only one, and the token has to be read back out
+ * of the exporter's `Authorization` header. Nothing shadows it, which is
+ * why the Codex path cannot produce the split-brain failure the Claude path
+ * is written to detect.
  */
 export type CredentialSource = "environment" | "settings" | "none";
 export type ResolvedAgentCredentials = {
@@ -15,8 +23,10 @@ export type ResolvedAgentCredentials = {
     endpoint: string | null;
     tokenSource: CredentialSource;
     endpointSource: CredentialSource;
+    /** The file `settings` refers to, so `doctor` can name it. */
+    sourcePath: string;
 };
-export declare function resolveAgentCredentials(): ResolvedAgentCredentials;
+export declare function resolveAgentCredentials(agent?: AgentId): ResolvedAgentCredentials;
 /** Masks a token for display: never print more than the stored prefix. */
 export declare function maskToken(token: string): string;
 export declare function findShadowedExports(cwd?: string): Array<{
@@ -24,7 +34,7 @@ export declare function findShadowedExports(cwd?: string): Array<{
     keys: string[];
 }>;
 /**
- * The command to write into settings.json for the hook.
+ * The command to write into an agent's hook configuration.
  *
  * Prefers the bare name, but only after confirming that `clocktopus` on
  * PATH resolves to *this* executable. Hooks run through a shell whose PATH
@@ -32,8 +42,13 @@ export declare function findShadowedExports(cwd?: string): Array<{
  * resolve there fails silently — the session runs fine and every bit of
  * repository context is lost. An absolute path is uglier and survives that;
  * `doctor` checks it still exists.
+ *
+ * The provider is baked into the command because the two agents send
+ * *identical* hook payloads — same field names, same event spellings, no
+ * marker of any kind. Which agent is calling can only be known from how the
+ * hook was installed.
  */
-export declare function resolveHookCommand(): {
+export declare function resolveHookCommand(provider: AgentProviderId): {
     command: string;
     usesAbsolutePath: boolean;
     binaryPath: string | null;

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

@@ -1 +1 @@
-{"version":3,"file":"agent-config.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-config.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAEnE,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,cAAc,EAAE,gBAAgB,CAAC;CAClC,CAAC;AAEF,wBAAgB,uBAAuB,IAAI,wBAAwB,CA2BlE;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAmBD,wBAAgB,mBAAmB,CAAC,GAAG,SAAgB,GAAG,KAAK,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC,CA+BD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CA8BA"}
+{"version":3,"file":"agent-config.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-config.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAK5D;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAEnE,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,cAAc,EAAE,gBAAgB,CAAC;IACjC,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,KAAK,GAAE,OAAkB,GACxB,wBAAwB,CA0C1B;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAmBD,wBAAgB,mBAAmB,CAAC,GAAG,SAAgB,GAAG,KAAK,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC,CA+BD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAgCA"}