commandmate 0.22.2 → 0.23.0

package/dist/server/src/lib/hooks/sources/opencode/turn-gate.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Deciding which frames are a turn's real boundaries (Issue #1763).
+ *
+ * opencode repeats both of the frames CommandMate reads as one-off facts, and
+ * in both cases the repeat is byte-identical to the original. A source that
+ * mapped frames one-to-one would therefore report the same event several times,
+ * and the status layer — which reads only the *newest* event — would turn that
+ * into a wrong verdict. This module tells the first from the rest.
+ *
+ * ## `session.idle` — the end of a turn
+ *
+ * It is opencode's `Stop`: #1758 §5.3.1 held a session on an approval dialog
+ * for 10 minutes 19 seconds and not one `session.idle` arrived for it, so the
+ * event really does mean "the turn finished" rather than "the agent is not
+ * busy". `commandmate wait` may key off it. What it may not do is count them:
+ *
+ *  - **Abnormal endings fire twice.** An abort emitted `session.idle` at
+ *    08:15:00.416 and again at 08:15:00.435 — 19 ms apart, same session, same
+ *    turn (§5.3.2). Provider errors do the same. Normal endings fire once.
+ *  - **The payload has no turn identifier.** It is `{ "sessionID": "ses_…" }`
+ *    and nothing else, so two idles cannot be told apart by looking at them
+ *    (§5.3.3). Claude's `Stop` carried `prompt_id`; this does not.
+ *  - **An idle can arrive for a turn this connection never watched start** — a
+ *    stream opened mid-session, a resubscribe after a restart — and treating
+ *    that as a completion resolves a `wait` for work that is not over.
+ *
+ * So: **arm on `session.status(busy)`, complete on the first `session.idle`
+ * after arming, drop the rest.** `session.status(idle)` is deliberately inert —
+ * it is emitted in the same millisecond as `session.idle` and is the same
+ * signal, so honouring both would double every turn (§5.3.2 rule 4).
+ *
+ * ## `message.updated` — the start of a turn
+ *
+ * `user_prompt_submit` has no event of its own; it is `message.updated` with
+ * `info.role === "user"`. That frame is **re-emitted for the same message
+ * several times per turn, including after `session.idle`** — measured live on
+ * 1.18.3 while implementing this Issue:
+ *
+ * ```
+ * 13:53:14.251  session.idle
+ * 13:53:14.297  message.updated  role=user  id=msg_ffb668eec001WToZ7VW0lQgmoa
+ * ```
+ *
+ * Both copies carry `time: { created: … }` and nothing else, so nothing in the
+ * payload distinguishes them. Mapped one-to-one, the newest event after a
+ * finished turn is `user_prompt_submit`, which `status-mapping` reads as
+ * **`running`** — so `commandmate wait` would hang on every completed opencode
+ * turn until the 30-minute staleness bound expired. The fix has the same shape:
+ * **announce the first `message.updated` for a message id, suppress the
+ * repeats.**
+ *
+ * Unlike the arming state, announced ids **survive a reconnect**. A genuinely
+ * new prompt always carries a new id, so keeping them costs nothing and closes
+ * the window where a reconnect lands between a turn's end and its trailing
+ * repeat.
+ *
+ * The gate is a pure state machine over frame types so it can be driven from
+ * fixtures. The subscription owns one per connection.
+ *
+ * @module lib/hooks/sources/opencode/turn-gate
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TRACKED_USER_MESSAGES = exports.MAX_TRACKED_TURN_SESSIONS = void 0;
+exports.createTurnGate = createTurnGate;
+const event_mapper_1 = require("../event-mapper");
+/**
+ * Cap on remembered sessions.
+ *
+ * One opencode server can host several sessions (#1758 §5.6.1) and a long-lived
+ * TUI accumulates them, so the map is bounded. The oldest is dropped, which at
+ * worst re-arms an ancient session — the failure mode of forgetting is a
+ * suppressed idle, never a spurious completion.
+ */
+exports.MAX_TRACKED_TURN_SESSIONS = 64;
+/**
+ * Cap on remembered user-message ids.
+ *
+ * Larger than the session cap because it counts prompts rather than sessions,
+ * and because these survive reconnects. Forgetting the oldest costs one
+ * re-announced `user_prompt_submit` for a prompt from thousands of turns ago.
+ */
+exports.MAX_TRACKED_USER_MESSAGES = 512;
+/** `properties.sessionID`, or null. */
+function sessionIdOf(payload) {
+    const properties = (0, event_mapper_1.isPlainObject)(payload.properties) ? payload.properties : {};
+    return (0, event_mapper_1.readNestedString)(properties, ['sessionID']);
+}
+/** `properties.status.type` for `session.status`. */
+function statusType(payload) {
+    const properties = (0, event_mapper_1.isPlainObject)(payload.properties) ? payload.properties : {};
+    return (0, event_mapper_1.readNestedString)(properties, ['status', 'type']);
+}
+/** `properties.error.name` for `session.error` — `MessageAbortedError`, `APIError`, … */
+function errorName(payload) {
+    const properties = (0, event_mapper_1.isPlainObject)(payload.properties) ? payload.properties : {};
+    return (0, event_mapper_1.readNestedString)(properties, ['error', 'name']);
+}
+/** `properties.info.role` / `properties.info.id` for `message.updated`. */
+function messageInfo(payload) {
+    const properties = (0, event_mapper_1.isPlainObject)(payload.properties) ? payload.properties : {};
+    return {
+        role: (0, event_mapper_1.readNestedString)(properties, ['info', 'role']),
+        id: (0, event_mapper_1.readNestedString)(properties, ['info', 'id']),
+    };
+}
+/** Drop the oldest entries until the collection fits. */
+function trim(keys, max) {
+    // Both Map and Set iterate in insertion order, so the head is the oldest.
+    while (keys.size > max) {
+        const oldest = keys.keys().next();
+        if (oldest.done)
+            break;
+        keys.delete(oldest.value);
+    }
+}
+/**
+ * Build a gate.
+ *
+ * @param maxSessions - Cap on remembered sessions; defaults to
+ *   {@link MAX_TRACKED_TURN_SESSIONS}
+ * @param maxUserMessages - Cap on remembered user-message ids; defaults to
+ *   {@link MAX_TRACKED_USER_MESSAGES}
+ */
+function createTurnGate(maxSessions = exports.MAX_TRACKED_TURN_SESSIONS, maxUserMessages = exports.MAX_TRACKED_USER_MESSAGES) {
+    const phases = new Map();
+    const announced = new Set();
+    const remember = (sessionId, phase) => {
+        phases.delete(sessionId);
+        phases.set(sessionId, phase);
+        trim(phases, maxSessions);
+    };
+    return {
+        observe(type, payload) {
+            if (type === 'message.updated') {
+                const { role, id } = messageInfo(payload);
+                // Only the user's own message is `user_prompt_submit`; the assistant's
+                // updates carry the reply and map to nothing.
+                if (role !== 'user' || id === null)
+                    return { kind: 'ignored' };
+                const sessionId = sessionIdOf(payload) ?? '';
+                if (announced.has(id)) {
+                    return { kind: 'suppressed', sessionId, reason: 'already-announced' };
+                }
+                announced.add(id);
+                trim(announced, maxUserMessages);
+                return { kind: 'announced', sessionId, messageId: id };
+            }
+            if (type === 'session.status') {
+                // Only `busy` arms. `idle` here is the same signal as `session.idle`,
+                // emitted in the same millisecond, and honouring both would count every
+                // turn twice (#1758 §5.3.2 rule 4).
+                if (statusType(payload) !== 'busy')
+                    return { kind: 'ignored' };
+                const sessionId = sessionIdOf(payload);
+                if (sessionId === null)
+                    return { kind: 'ignored' };
+                remember(sessionId, 'busy');
+                return { kind: 'armed', sessionId };
+            }
+            if (type === 'session.error') {
+                const sessionId = sessionIdOf(payload);
+                if (sessionId === null)
+                    return { kind: 'ignored' };
+                // Not a completion: the idle that follows is. Reported so the caller can
+                // tell "finished" from "gave up" — `session.idle` alone cannot (§5.3.3
+                // requirement 3).
+                return { kind: 'failed', sessionId, errorName: errorName(payload) };
+            }
+            if (type !== 'session.idle')
+                return { kind: 'ignored' };
+            const sessionId = sessionIdOf(payload);
+            if (sessionId === null)
+                return { kind: 'ignored' };
+            const phase = phases.get(sessionId);
+            if (phase === undefined) {
+                return { kind: 'suppressed', sessionId, reason: 'never-armed' };
+            }
+            if (phase === 'idle') {
+                return { kind: 'suppressed', sessionId, reason: 'already-completed' };
+            }
+            remember(sessionId, 'idle');
+            return { kind: 'completed', sessionId };
+        },
+        isArmed(sessionId) {
+            return phases.get(sessionId) === 'busy';
+        },
+        reset() {
+            phases.clear();
+            // `announced` is deliberately kept — see the module comment.
+        },
+    };
+}

package/dist/server/src/lib/hooks/sources/pending-decisions.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * The in-flight decisions a push source is holding, and the one call a receiver
+ * makes to answer one (Issue #1759, constraint C2).
+ *
+ * A hook is answered in the body of the request it arrived on. opencode is
+ * answered by `POST`ing to a different URL, minutes later if need be, on a
+ * connection the event never travelled over (#1758 §5.5). Those are not two
+ * spellings of one operation, and a receiver that branched on which it was
+ * dealing with would be a receiver that knows the tool — the thing this whole
+ * abstraction exists to remove.
+ *
+ * {@link answerPendingDecision} is the seam. It opens a slot, hands the
+ * decision to {@link AgentEventSource.decide}, and returns whatever body the
+ * source left behind — `{}` when the source answered out of band, because there
+ * is then nothing for the response to carry. A push source fills the slot
+ * synchronously; a pull source ignores it and calls REST. The caller writes the
+ * returned object either way.
+ *
+ * The open slots are also what {@link AgentEventSource.listPending} answers with
+ * for push sources (C7): a hook that has not been replied to yet is the only
+ * pending state a push transport has, and a hook that was dropped is simply
+ * gone — there is no `GET /permission` to re-read it from.
+ *
+ * @module lib/hooks/sources/pending-decisions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_OPEN_DECISIONS_PER_INSTANCE = void 0;
+exports.openDecisionSlot = openDecisionSlot;
+exports.closeDecisionSlot = closeDecisionSlot;
+exports.listOpenDecisions = listOpenDecisions;
+exports.fillDecisionSlot = fillDecisionSlot;
+exports.resetPendingDecisions = resetPendingDecisions;
+exports.answerPendingDecision = answerPendingDecision;
+const auto_yes_state_1 = require("../../../lib/auto-yes-state");
+const logger_1 = require("../../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/pending-decisions');
+const pendingByInstance = (globalThis.__agentSourcePendingDecisions ??= new Map());
+/**
+ * Cap on simultaneously open slots for one instance.
+ *
+ * An agent asks one thing at a time, so anything above a handful means slots
+ * are leaking rather than that a human is very busy. The oldest is dropped
+ * rather than the newest refused: the newest is the one somebody is waiting on.
+ */
+exports.MAX_OPEN_DECISIONS_PER_INSTANCE = 16;
+function keyOf(ref) {
+    return (0, auto_yes_state_1.buildCompositeKey)(ref.worktreeId, ref.cliToolId, ref.instanceId);
+}
+/** Register a decision as in flight. Always paired with {@link closeDecisionSlot}. */
+function openDecisionSlot(ref, decision) {
+    const key = keyOf(ref);
+    const slot = { key, ref, decision, body: null };
+    const open = pendingByInstance.get(key) ?? [];
+    open.push(slot);
+    while (open.length > exports.MAX_OPEN_DECISIONS_PER_INSTANCE)
+        open.shift();
+    pendingByInstance.set(key, open);
+    return slot;
+}
+/**
+ * Remove a slot and take whatever the source wrote into it.
+ *
+ * @returns The response body, or `{}` when the source answered out of band —
+ *   which is also, and not by accident, the byte-for-byte no-decision body
+ *   every hook-based tool reads as "carry on" (#1721 D5).
+ */
+function closeDecisionSlot(slot) {
+    const open = pendingByInstance.get(slot.key);
+    if (open) {
+        const index = open.indexOf(slot);
+        if (index >= 0)
+            open.splice(index, 1);
+        if (open.length === 0)
+            pendingByInstance.delete(slot.key);
+    }
+    return slot.body ?? {};
+}
+/** The decisions currently in flight for one instance. */
+function listOpenDecisions(ref) {
+    return (pendingByInstance.get(keyOf(ref)) ?? []).map((slot) => slot.decision);
+}
+/** Fill the slot a push source is answering, if it is still open. */
+function fillDecisionSlot(ref, decisionId, body) {
+    const open = pendingByInstance.get(keyOf(ref));
+    if (!open)
+        return false;
+    const slot = open.find((candidate) => candidate.decision.id === decisionId);
+    if (!slot)
+        return false;
+    slot.body = body;
+    return true;
+}
+/** Drop every open slot. For tests; production only ever closes what it opened. */
+function resetPendingDecisions() {
+    pendingByInstance.clear();
+}
+/**
+ * Answer one decision, whichever way this source answers things.
+ *
+ * The single call a receiver route makes. It does not know — and after this
+ * function exists, cannot find out without going out of its way — whether the
+ * verdict left through the response body or through a second HTTP call.
+ *
+ * @returns The body to write. `{}` means "nothing to say here", which for a
+ *   hook is the measured no-decision reply and for a pull source is simply the
+ *   ack of a request whose answer went elsewhere.
+ */
+async function answerPendingDecision(source, ref, decision, verdict) {
+    const slot = openDecisionSlot(ref, decision);
+    try {
+        await source.decide(ref, decision, verdict);
+    }
+    catch (error) {
+        // Closed even when `decide` throws: a source that failed to deliver must
+        // still not leave the receiver holding a slot, and the empty body that then
+        // comes back is the fail-open answer for every push tool.
+        logger.warn('agent-source-decide-failed', {
+            worktreeId: ref.worktreeId,
+            cliToolId: ref.cliToolId,
+            instanceId: ref.instanceId ?? ref.cliToolId,
+            decisionId: decision.id,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return closeDecisionSlot(slot);
+}

package/dist/server/src/lib/hooks/sources/registry.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Which {@link AgentEventSource} speaks for which CLI tool (Issue #1759).
+ *
+ * The lookup that replaces "assume Claude". A receiver holds a
+ * {@link CLIToolType} — it came off the hook URL or the request body — and asks
+ * here; it never imports a tool's module and never compares against a tool id.
+ *
+ * ## Held on `globalThis`
+ *
+ * Not decoration. `agent-event-state` documents what happened the last time a
+ * shared map lived in module scope (#1736): under `next dev` every route
+ * handler is bundled separately, so `/api/hooks/agent-event` and
+ * `/api/hooks/permission-request` each got their own copy of the module, one
+ * wrote and the other read, and every field came back null — with no error, no
+ * warning and a perfectly well-formed response. A registry has the same shape
+ * of failure available to it: a source registered in one bundle would be absent
+ * in another, and the fallback below would silently take over. So the map is
+ * process-wide, and the registration is idempotent.
+ *
+ * ## Unregistered tools
+ *
+ * {@link getAgentEventSource} always answers. A tool with no source gets the
+ * compatibility source from `./legacy-relay`, which preserves the pre-#1759
+ * receiver behaviour for the hand-configured hooks of #1549. Ask
+ * {@link hasAgentEventSource} when the distinction matters.
+ *
+ * @module lib/hooks/sources/registry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAgentEventSource = registerAgentEventSource;
+exports.hasAgentEventSource = hasAgentEventSource;
+exports.getAgentEventSource = getAgentEventSource;
+exports.listAgentEventSources = listAgentEventSources;
+exports.unregisterAgentEventSource = unregisterAgentEventSource;
+const legacy_relay_1 = require("./legacy-relay");
+const source_1 = require("./claude/source");
+const source_2 = require("./copilot/source");
+const source_3 = require("./gemini/source");
+const source_4 = require("./antigravity/source");
+const source_5 = require("./codex/source");
+const source_6 = require("./opencode/source");
+const registered = (globalThis.__agentEventSources ??= new Map());
+/** Memoised compatibility sources, so repeated lookups return one object. */
+const legacy = (globalThis.__agentEventLegacySources ??= new Map());
+/**
+ * Add or replace a tool's source.
+ *
+ * @param source - The implementation; its own `cliToolId` is the key
+ */
+function registerAgentEventSource(source) {
+    registered.set(source.cliToolId, source);
+    // A tool that has a real source must not keep answering from the
+    // compatibility one anywhere — including from a memo taken before it was
+    // registered, which is reachable in `next dev` where registration order
+    // across bundles is not fixed.
+    legacy.delete(source.cliToolId);
+}
+/** Whether this tool has a real implementation, as opposed to the fallback. */
+function hasAgentEventSource(cliToolId) {
+    return registered.has(cliToolId);
+}
+/**
+ * The source for one tool. Never null.
+ *
+ * @returns The registered implementation, or the compatibility source that
+ *   keeps a hand-configured #1549 hook working until this tool has one
+ */
+function getAgentEventSource(cliToolId) {
+    const source = registered.get(cliToolId);
+    if (source)
+        return source;
+    const existing = legacy.get(cliToolId);
+    if (existing)
+        return existing;
+    const fallback = (0, legacy_relay_1.createLegacyRelaySource)(cliToolId);
+    legacy.set(cliToolId, fallback);
+    return fallback;
+}
+/** Every tool with a real implementation. Ordered by registration. */
+function listAgentEventSources() {
+    return [...registered.values()];
+}
+/**
+ * Undo a registration. For tests — production only ever adds.
+ *
+ * The mutation "take Claude out of the registry" that Issue #1759 asks to be
+ * proved lethal is spelled with this.
+ */
+function unregisterAgentEventSource(cliToolId) {
+    registered.delete(cliToolId);
+    legacy.delete(cliToolId);
+}
+// ---------------------------------------------------------------------------
+// Built-in registrations
+// ---------------------------------------------------------------------------
+//
+// Statically imported and registered on load, rather than through a
+// side-effecting `import './claude'` somewhere else: an import a bundler is
+// free to consider unused is a registration that disappears in a production
+// build, and "the source is silently absent" is the exact failure this module's
+// globalThis comment is about.
+//
+// Phase 4-2…4-5 adds one line here per tool. That, plus the tool's own file, is
+// the whole of "adding a tool" — see docs/design/agent-event-source-interface.md.
+registerAgentEventSource(source_1.claudeAgentEventSource);
+registerAgentEventSource(source_2.copilotAgentEventSource);
+registerAgentEventSource(source_3.geminiAgentEventSource);
+registerAgentEventSource(source_4.antigravityAgentEventSource);
+registerAgentEventSource(source_5.codexAgentEventSource);
+registerAgentEventSource(source_6.opencodeAgentEventSource);

package/dist/server/src/lib/hooks/sources/types.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * `AgentEventSource` — the one seam every agent CLI plugs its lifecycle events
+ * into (Issue #1759, Phase 4-1 of Epic #1720).
+ *
+ * Phases 1-3 left the *consuming* half of the structured-event pipeline already
+ * tool-agnostic: `agent-event-state`, `permission-decision-service`,
+ * `current-output-builder`, `status-mapping` and `prompt-waiting-composition`
+ * all key off `(worktreeId, cliToolId, instanceId)` and branch on nothing else.
+ * What stayed Claude-shaped is the half that *produces* the events and the half
+ * that *answers* them. This module is the contract for that half, so Phase
+ * 4-2…4-5 adds a tool by adding a file rather than by copying Claude's seams.
+ *
+ * Every type below exists because a measurement demanded it. The two spikes
+ * that took those measurements are the specification:
+ *
+ *  - `docs/design/agent-hooks-phase4-live-verification.md` (#1757) — codex /
+ *    copilot / gemini / antigravity, five push-mode hook implementations that
+ *    disagree with each other about spelling, casing, correlation keys, config
+ *    location and — most importantly — what silence means.
+ *  - `docs/design/opencode-server-live-verification.md` (#1758) — opencode,
+ *    which is not a hook implementation at all: CommandMate subscribes to *its*
+ *    HTTP server over SSE and answers with a separate REST call. §9.1 of that
+ *    report lists eight constraints (C1…C8) and §9.2 sketches this interface;
+ *    the shapes here follow it.
+ *
+ * Three of those constraints are worth restating at the top of the file,
+ * because getting them wrong is silent:
+ *
+ *  - **C1 — the direction of travel is not fixed.** Hooks push into
+ *    `POST /api/hooks/agent-event`. opencode has to be *subscribed to*. So a
+ *    source has a lifecycle (`subscribe` / `Subscription.close`), even when
+ *    the push implementations make it a no-op.
+ *  - **C2 — the reply channel is not fixed.** A hook is answered in the body of
+ *    the request it arrived on; opencode is answered by `POST`ing to a
+ *    different URL entirely. {@link AgentEventSource.decide} hides which.
+ *  - **C3 — silence does not mean the same thing twice.** Claude / codex /
+ *    copilot walk on when nobody answers (fail-open). antigravity reads an
+ *    empty object as *deny* and stops every tool call. opencode waits forever
+ *    (10m19s measured, no timeout). {@link NoDecisionBehavior} is a declared
+ *    field for exactly this reason: "we abstain, which is the safe default" is
+ *    a sentence that is only true for some of the tools.
+ *
+ * @module lib/hooks/sources/types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server/src/lib/session/agent-session-lifecycle.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * The one call every agent's `startSession` makes when it creates a pane
+ * (Issue #1759, seam S8).
+ *
+ * `beginAgentEventGeneration` fences a recreated session off from the previous
+ * process's events: the state is keyed by (worktree, tool, instance), a key the
+ * new session reuses verbatim, so without the fence the *old* process's last
+ * `user_prompt_submit` reads as the new one's and a freshly started session
+ * publishes `running` before anybody has typed into it (#1723).
+ *
+ * Before this Issue there was exactly one call to it in the entire codebase —
+ * `claude-session.ts`, on the creation path. Every other tool starts through
+ * its own `startSession` in `src/lib/cli-tools/<tool>.ts` and has no fence at
+ * all. That was invisible while Claude was the only tool emitting events, and
+ * becomes a real defect the moment Phase 4-2 lands: codex would inherit the
+ * previous codex process's verdict on every restart.
+ *
+ * So the fence is a helper a `startSession` can call without knowing anything
+ * about the event system, and Claude's call now goes through it. Adding a tool
+ * means adding this one line to that tool's creation path — see
+ * `docs/design/agent-event-source-interface.md`.
+ *
+ * ## Where it goes in `startSession`
+ *
+ * On the **creation** path only, and **before** the pane is created:
+ *
+ *  - not on the reuse path — a `startSession` that finds a healthy session and
+ *    returns is the same generation, and fencing there would throw away a
+ *    still-valid verdict on every reconnect;
+ *  - before creation, so there is no window in which a live pane is judged
+ *    against a stale generation;
+ *  - unconditionally, even if the launch then fails — falling back to the
+ *    screen scraper is always safe, and trusting a dead session's events is
+ *    not.
+ *
+ * @module lib/session/agent-session-lifecycle
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.beginAgentSession = beginAgentSession;
+exports.prepareAgentLaunch = prepareAgentLaunch;
+const sources_1 = require("../../lib/hooks/sources");
+const agent_event_state_1 = require("../../lib/session/agent-event-state");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/session/agent-session-lifecycle');
+/**
+ * Open a new event generation for an agent instance that is about to start.
+ *
+ * Safe to call for a tool that emits nothing: the fence is a timestamp, and a
+ * tool with no events simply never has any to fence.
+ *
+ * @param target - The instance being created
+ * @param at - Epoch ms; defaults to now
+ */
+function beginAgentSession(target, at = Date.now()) {
+    (0, agent_event_state_1.beginAgentEventGeneration)(target.worktreeId, target.cliToolId, target.instanceId, at);
+    const source = (0, sources_1.getAgentEventSource)(target.cliToolId);
+    logger.info('agent-session-generation-begun', {
+        worktreeId: target.worktreeId,
+        cliToolId: target.cliToolId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        transport: source.transport,
+    });
+}
+/**
+ * The command that starts this agent, with whatever config it needs written
+ * first (S3 / S4).
+ *
+ * A thin pass-through to the tool's source, and the reason a session module
+ * does not import a settings generator: which file gets written, and whether
+ * one gets written at all, is the source's business.
+ *
+ * Never throws — see {@link AgentEventSource.prepareLaunch}. A tool whose
+ * config could not be written starts bare, which is the pre-#1722 status quo.
+ *
+ * @param target - The instance being started
+ * @param executablePath - Resolved path to the agent CLI
+ * @returns The command line, and the config file when one was written
+ */
+function prepareAgentLaunch(target, executablePath) {
+    return (0, sources_1.getAgentEventSource)(target.cliToolId).prepareLaunch(target, executablePath);
+}

package/dist/server/src/lib/session/claude-session.js

@@ -26,7 +26,8 @@ const promises_1 = require("fs/promises");
 const logger_1 = require("../../lib/logger");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
 const types_1 = require("../../lib/cli-tools/types");
-const hook_settings_generator_1 = require("../../lib/hooks/hook-settings-generator");
+const sources_1 = require("../../lib/hooks/sources");
+const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
 const agent_event_state_1 = require("../../lib/session/agent-event-state");
 const session_start_error_1 = require("../../lib/session/session-start-error");
 const logger = (0, logger_1.createLogger)('claude-session');
@@ -566,7 +567,10 @@ async function startClaudeSession(options) {
     // live pane is matched against a stale generation. Bumped even if the start
     // then fails: falling back to the scraper is always safe, trusting a dead
     // session's events is not.
-    (0, agent_event_state_1.beginAgentEventGeneration)(worktreeId, 'claude', instanceId);
+    // Issue #1759: through the shared helper, which is the one call every
+    // tool's `startSession` makes. Claude's was the only fence in the codebase;
+    // making it the helper's job is what lets Phase 4-2…4-5 have one too.
+    (0, agent_session_lifecycle_1.beginAgentSession)({ worktreeId, cliToolId: sources_1.CLAUDE_CLI_TOOL_ID, instanceId });
     try {
         // Create tmux session. Scrollback depth comes from the shared
         // TMUX_HISTORY_LIMIT default (Issue #1624) — do not re-hardcode it here.
@@ -594,7 +598,10 @@ async function startClaudeSession(options) {
         //
         // Falls back to the bare path on any failure; a session that starts without
         // hooks is the pre-#1722 status quo, and a session that fails to start is not.
-        const launchCommand = (0, hook_settings_generator_1.buildClaudeLaunchCommand)(claudePath, { worktreeId, instanceId });
+        // Issue #1759: which config file gets written, and whether one is written
+        // at all, belongs to the tool's `AgentEventSource` (S3/S4). Claude's
+        // delegates to `buildClaudeLaunchCommand`, unchanged.
+        const launchCommand = (0, agent_session_lifecycle_1.prepareAgentLaunch)({ worktreeId, cliToolId: sources_1.CLAUDE_CLI_TOOL_ID, instanceId }, claudePath).command;
         // Start Claude CLI in interactive mode using dynamically resolved path
         await (0, tmux_1.sendKeys)(sessionName, launchCommand, true);
         // Wait for Claude to initialize with dynamic detection (OCP-001)