@platless/axom-cli 0.1.0 → 0.3.13

package/dist/workstation/acp/acpSession.js

@@ -36,18 +36,17 @@
  * the server's turn-end / replay-end flush is what closes a message.
  */
 import { randomUUID } from 'node:crypto';
+import { certifiedRuntime, ForegroundOutputBoundary } from '../qoderAdapter/foregroundOutput.js';
+import { BackgroundTerminalRepair, nativeTerminalHistoryPath } from '../qoderAdapter/backgroundTerminal.js';
+import { SubworkBoundary, supportsSubworkMeta } from '../qoderAdapter/subwork.js';
 import { methods } from '@agentclientprotocol/sdk';
 import { jsonRpcErrorCode } from './acpClient.js';
 import { settleUpdates } from './adoption.js';
 import { mapSessionUpdate, SessionMapperState } from './sessionUpdateMapper.js';
+import { SessionMapperScopes } from './sessionScope.js';
+import { newSessionMetaFor } from './activityReporting.js';
+import { buildSessionMcpServers } from './delegationMcp.js';
 import { flatChoicesOf, modesAlreadyRepresented, normalizeConfigOptions, SYNTHESIZED_MODES_CONFIG_ID } from './configOptions.js';
-/**
- * A few ACP adapters reply to `session/prompt` before their last `session/update` notifications
- * have arrived. Those trailing chunks have no following turn boundary to synthesize
- * `agent_message`, so the server would keep them buffered until the reader sent another message.
- * This short quiet period lets a burst remain one message while ensuring it is rendered on its own.
- */
-const LATE_MESSAGE_SETTLE_MS = 250;
 /**
  * Points the connection's diverted-update stream at the session that owns it.
  *
@@ -76,6 +75,15 @@ function bindDivertedUpdates(connection, ownSessionId, session) {
  * {@link AcpConnection.supportsSteering} first.
  */
 const STEER_METHOD = '_session/steering';
+/**
+ * The adapter's *stop one background task* extension method. **Not an ACP method** either — it is
+ * `claude-agent-acp`'s own `ASYNC_TASK_STOP_METHOD` (`acp-agent.js@0.79.0:165`), whose own comment
+ * reads *"Stops one Claude background task without cancelling the parent prompt turn."*
+ * `codex-acp@1.12.0` registers the same literal name with the same params
+ * (`dist/index.js:31608`, `:35126-35129`, `:32395-32406`). Reached through the untyped `request`
+ * overload, for the reason {@link STEER_METHOD} documents.
+ */
+const ASYNC_TASK_STOP_METHOD = '_session/async_task/stop';
 /**
  * Narrow a `_session/steering` response onto {@link SteerOutcome}, or throw.
  *
@@ -119,6 +127,14 @@ export function mapSteerOutcome(result) {
  * sent over the wire to any agent, so no real option id can ever equal it in practice.
  */
 const ABANDONED_ANSWER = `__acp_session_abandoned_${randomUUID()}__`;
+/**
+ * The value `registerPendingElicitation`'s resolver receives when nobody is ever going to answer.
+ * Unlike {@link ABANDONED_ANSWER}, this needs no randomized sentinel: `CreateElicitationResponse`'s
+ * `action` union already has `'cancel'` as a real ACP outcome meaning exactly this ("the client
+ * will not provide a response"), so there is no risk of it colliding with a real user answer the
+ * way a fixed permission-option-id literal would.
+ */
+const ABANDONED_ELICITATION_ANSWER = { action: 'cancel' };
 /** ACP's `StopReason` (`end_turn | max_tokens | max_turn_requests | refusal | cancelled`) → the wire's `TurnStopReason`. `'cancelled'` is handled by the caller (it forces `status: 'interrupted'` instead, which carries no `stopReason` — see {@link AcpSession.finishTurn}), so it never actually reaches this function; the arm is kept so the switch stays exhaustive over every literal `StopReason` can hold. */
 function mapStopReason(reason) {
     switch (reason) {
@@ -169,6 +185,47 @@ async function steerRequest(connection, sessionId, blocks, priority) {
     });
     return mapSteerOutcome(result);
 }
+/**
+ * One `_session/async_task/stop` round trip, shared by {@link AcpSession.open} and
+ * {@link AcpSession.attach} exactly as {@link steerRequest} is — the two differ only in where the
+ * session id comes from.
+ *
+ * The request shape is the adapter's own `parseAsyncTaskStopRequest`
+ * (`claude-agent-acp@0.79.0` `dist/acp-agent.js:166-173`): a non-empty `sessionId` and a non-empty
+ * `asyncTaskId`, both trimmed strings, and nothing else. `codex-acp@1.12.0` parses the identical
+ * pair (`dist/index.js:35126-35129`, a zod object with `.trim().min(1)` on both), so there is one
+ * shape here, not a per-vendor branch. The response is `{ stopped: boolean }` on both
+ * (`acp-agent.js:1784-1798`, `index.js:32395-32406`), which this layer deliberately does **not**
+ * turn into a verdict: `stopped: false` only means the adapter had no live task under that id
+ * right now, and the platform's real answer
+ * — did the background task actually end — arrives as the agent's own next `async_task_state_update`
+ * for this `(sessionId, asyncTaskId)`. Reporting `false` as a failure would make the server show an
+ * error for a task that is, by then, already settled.
+ *
+ * Reached through the untyped `request` overload for the same reason {@link steerRequest} is: this
+ * is an adapter extension in ACP's `_`-prefixed namespace, not an ACP method — `grep async_task`
+ * over the pinned SDK's `types.gen.d.ts` returns nothing.
+ */
+async function asyncTaskStopRequest(connection, sessionId, asyncTaskId) {
+    const result = await connection.connection.agent.request(ASYNC_TASK_STOP_METHOD, {
+        sessionId,
+        asyncTaskId,
+    });
+    if (result?.stopped !== true) {
+        // Logged, never thrown: see this function's own doc for why `stopped: false` is not a failure.
+        console.warn(`[acp] ${ASYNC_TASK_STOP_METHOD} reported no live task '${asyncTaskId}' on session ${sessionId}`);
+    }
+}
+async function providerTaskStopRequest(connection, sessionId, taskId, requestId) {
+    const result = await connection.connection.agent.request('_axom/task/stop', {
+        sessionId, taskId, requestId,
+    });
+    if (result?.state === 'accepted')
+        return 'accepted';
+    if (result?.state === 'unknown')
+        return 'unknown';
+    throw new Error('Provider task stop was rejected');
+}
 /**
  * One `session/set_config_option` (`SetSessionConfigOptionRequest`, `types.gen.d.ts:5102-5132`) or
  * — for the daemon's synthesized {@link SYNTHESIZED_MODES_CONFIG_ID} — `session/set_mode`
@@ -286,6 +343,7 @@ class AttachedQueue {
 }
 export class AcpSession {
     session;
+    connection;
     outbox = [];
     /**
      * This session's `toolCallId → name` memory, for the `tool_call_update`s ACP lets arrive with
@@ -295,9 +353,23 @@ export class AcpSession {
      * is: one `AcpSession` is one ACP session, and a registry shared between two of them would let
      * one session's tool call name a different session's update.
      */
-    mapperState = new SessionMapperState();
+    rootRuntimeId = randomUUID();
+    scopes = new SessionMapperScopes((scope) => new SessionMapperState((raw) => { if (scope.nativeSessionId === this.session.sessionId)
+        this.reportActivity(raw); }));
+    mapperFor(nativeSessionId) {
+        return this.scopes.get({ rootRuntimeId: this.rootRuntimeId, nativeSessionId });
+    }
     eventSink = null;
     turnSink = null;
+    backgroundWriterUnconfirmed = false;
+    exactExecutionUnconfirmed = false;
+    /**
+     * This session's latest agent-reported activity-state consumer — `agentSessions.ts`, via
+     * `AcpAgentSession.onActivity`. Kept apart from {@link eventSink} on purpose: an activity push is
+     * a level, not an edge (see the `agent_session_state` frame's own doc comment), so it must never
+     * pass through the `WireEvent`/journal/seq machinery {@link eventSink} feeds.
+     */
+    activitySink = null;
     draining = false;
     /**
      * Every turn this session has started and not yet reported a result for, oldest first.
@@ -319,15 +391,19 @@ export class AcpSession {
      * per-prompt attribution would need an id ACP does not put on `session/update` either.
      */
     inFlightTurns = [];
-    /** Timer which closes assistant text that an adapter sent after it had already ended the turn. */
-    lateMessageFlushTimer = null;
     /**
      * Whether a `session/prompt` round trip is outstanding on the agent **right now**.
      *
      * This is the turn's ground truth: {@link inFlightTurns} is pushed when the prompt goes out and
      * shifted when the agent answers, so it says what the agent is doing rather than what anything
-     * else recorded about it. The daemon's own `TaskRegistry` bracket is bookkeeping over the same
-     * events and can outlive them (a steer on an idle session, a bracket never closed); this cannot.
+     * else recorded about it. `TaskRegistry.snapshot()` reads this getter directly, live, on every
+     * call -- there is no bracket of started/finished events kept elsewhere on the daemon side that
+     * could go stale or outlive it (that bookkeeping set is gone; see the design doc's §4.1/§4.2).
+     * The signal that *can* now outlive the events it describes is the agent's own self-reported
+     * activity (`lastActivityRaw`): a vendor that says `running` and then falls silent stays
+     * "running" until it says otherwise, by deliberate policy (no invented timeout; §4.4). This
+     * getter has no equivalent failure mode -- it cannot outlive the round trip it is asking about,
+     * because it *is* that round trip, sampled live rather than recorded.
      */
     get turnRunning() {
         return this.inFlightTurns.length > 0;
@@ -336,6 +412,9 @@ export class AcpSession {
     get readable() {
         return this.readLoopDead === null;
     }
+    nativeTerminalRepair;
+    foregroundOutput;
+    subworkBoundary;
     closed = false;
     connectionAborted = false;
     /**
@@ -348,10 +427,18 @@ export class AcpSession {
      * joins the same silence. Two of the consequences live outside this file, which is why no
      * per-file review caught them:
      *
-     * - `agentSessions.ts` adds the ref to `TaskRegistry`'s `agentTasks` on every `agent_prompt` and
-     *   only `onAgentTurnDone` takes it out again, so one hung prompt pins `canUpdate()` to `false`
-     *   for the rest of this process's life — the daemon refuses **every** self-update until that
-     *   session is explicitly closed or swept.
+     * - `TaskRegistry.canUpdate()` samples {@link turnRunning} live off {@link inFlightTurns} rather
+     *   than accumulating a bracketed ref (2026-09-21 rewrite — the old `agentTasks` Set could go
+     *   stale on its own, holding a ref no real condition still justified; live sampling means a mark
+     *   can no longer outlive the condition that set it). That does not make this concern go away,
+     *   because the condition here would be real, not stale bookkeeping: {@link inFlightTurns} is
+     *   still pushed unconditionally at the bottom of this method, and only {@link finishTurn} pops
+     *   it. A prompt sent into a connection nobody is reading gets no `session/update`, so nothing
+     *   would ever call {@link finishTurn} for that entry — the turn is genuinely, permanently
+     *   unfinished, so live sampling faithfully reports it and pins `turnRunning` to `true`, and with
+     *   it `canUpdate()` to `false`, for the rest of this process's life. Same failure mode as the old
+     *   leak, one call frame earlier: a busy mark nothing will ever clear. This flag's early return is
+     *   what pairs that push with an immediate {@link finishTurn} instead of leaving it stuck.
      * - Each retry `touch()`es the session, so retrying keeps `lastActivityAt` fresh and `sweepIdle`
      *   never reclaims it either.
      *
@@ -371,16 +458,62 @@ export class AcpSession {
      * process forever. `permission.ts` is the only thing that populates it, via
      * {@link registerPendingApproval}; nothing in this file does.
      */
+    connectionGeneration = randomUUID();
+    permissionsInterrupted = false;
+    permissionOrigins = new Set();
+    // One parent per exact native ID, including edges whose parent has not arrived yet.
+    permissionParents = new Map();
+    unresolvedPermissionOrigins = new Set();
     pendingApprovals = new Map();
+    settledApprovals = new Map();
+    callbacksComplete = true;
+    publishCallbacks() {
+        this.connection.publishCallbacks?.({ rootSessionId: this.session.sessionId,
+            connectionGeneration: this.connectionGeneration, complete: this.callbacksComplete,
+            pending: this.callbacksComplete ? [...this.pendingApprovals].map(([requestId, entry]) => ({ requestId,
+                originNativeSessionId: entry.originNativeSessionId, rpcRequestId: entry.rpcRequestId })) : [],
+            settled: this.callbacksComplete ? [...this.settledApprovals].map(([requestId, reason]) => ({ requestId, reason })) : [] });
+    }
+    /**
+     * `requestId` → the resolver for one outstanding `elicitation/create` round trip. Parallel to
+     * {@link pendingApprovals}, and drained the same way for the same reason — `close()` and the
+     * connection-abort branch of `runReadLoop` must not leave the agent process blocked inside
+     * `elicitation/create` forever. A separate map rather than reusing `pendingApprovals`, because the
+     * resolved value differs in kind: a `CreateElicitationResponse` object, not a bare option-id
+     * string — see `AgentFrame.AgentElicitationAnswer`'s KDoc for why the two frames (and so the two
+     * maps) do not collapse into one.
+     */
+    pendingElicitations = new Map();
     readLoopDone;
-    constructor(session, connectionSignal) {
+    constructor(session, connectionSignal, connection) {
         this.session = session;
+        this.connection = connection;
         if (connectionSignal.aborted)
             this.connectionAborted = true;
         else
-            connectionSignal.addEventListener('abort', () => (this.connectionAborted = true), { once: true });
+            connectionSignal.addEventListener('abort', () => {
+                this.connectionAborted = true;
+                this.nativeTerminalRepair?.close();
+            }, { once: true });
+        if (certifiedRuntime(connection.agentInfo))
+            this.foregroundOutput = new ForegroundOutputBoundary(this.session.sessionId);
+        if (supportsSubworkMeta(connection.agentInfo))
+            this.subworkBoundary = new SubworkBoundary(this.session.sessionId);
         this.readLoopDone = this.runReadLoop();
     }
+    /** Only actual hosted sessions enable the certified Qoder boundary; probes never read history. */
+    enableBackgroundTerminalRepair(cwd, historyHome, restoreCalls = false) {
+        if (this.closed || this.connectionAborted || this.readLoopDead || this.nativeTerminalRepair)
+            return;
+        const path = nativeTerminalHistoryPath(this.connection.agentInfo, this.session.sessionId, cwd, historyHome);
+        if (!path)
+            return;
+        this.nativeTerminalRepair = new BackgroundTerminalRepair({
+            includeProcess: this.subworkBoundary !== undefined,
+            path, cwd, restoreCalls, nativeSessionId: this.session.sessionId, emit: event => this.emitEvent(event),
+        });
+        this.nativeTerminalRepair.start();
+    }
     /**
      * Open a new ACP session via `session/new` and start driving it.
      *
@@ -390,7 +523,18 @@ export class AcpSession {
      * degraded to `null` here rather than trusted at face value.
      */
     static async open(connection, options) {
-        const activeSession = await connection.connection.agent.buildSession(options.cwd).start();
+        // Opts into claude-agent-acp's raw-SDK-message channel (design §5.1/§2.1) for exactly the
+        // session that needs it — `undefined` for every other agent, in which case `buildSession` keeps
+        // taking the plain `cwd` string it always has when no MCP server is configured. The explicit
+        // request path carries the same MCP list as session/load, including any scoped delegation lease.
+        const meta = newSessionMetaFor(connection.agentInfo?.name);
+        const mcpServers = buildSessionMcpServers(options.mcpServers, options.delegationMcp);
+        if (options.delegationMcp)
+            connection.redactStderrSecret(Object.values(options.delegationMcp.headers)[0]);
+        const builder = meta || mcpServers.length > 0
+            ? connection.connection.agent.buildSession({ cwd: options.cwd, mcpServers, ...(meta ? { _meta: meta } : {}) })
+            : connection.connection.agent.buildSession(options.cwd);
+        const activeSession = await builder.start();
         // `NewSessionResponse` (`acp.d.ts:329`'s `newSessionResponse` getter) carries both halves
         // `normalizeConfigOptions` needs: `configOptions` (`types.gen.d.ts:2546`) and `modes` (`:2542`).
         const response = activeSession.newSessionResponse;
@@ -408,8 +552,16 @@ export class AcpSession {
             cancel: () => connection.connection.agent.notify(methods.agent.session.cancel, { sessionId: activeSession.sessionId }),
             steer: (blocks, priority) => steerRequest(connection, activeSession.sessionId, blocks, priority),
             setConfigOption: setConfigOptionRequest(connection, activeSession.sessionId, () => snapshot, (next) => (snapshot = next)),
+            stopAsyncTask: (asyncTaskId) => asyncTaskStopRequest(connection, activeSession.sessionId, asyncTaskId),
+            providerTaskStop: (taskId, requestId) => providerTaskStopRequest(connection, activeSession.sessionId, taskId, requestId),
         };
-        const session = new AcpSession(drivenSession, connection.connection.signal);
+        const session = new AcpSession(drivenSession, connection.connection.signal, connection);
+        // Claude's activity-state notification arrives on the connection, not on this session's own
+        // `session/update` stream (see `activityReporting.ts` and `AcpConnection.bindActivity`'s doc
+        // comment for why `extNotification` cannot be routed the way `session/update` is). Bound
+        // unconditionally: a connection whose agent never sends `_claude/sdkMessage` simply never
+        // invokes this sink.
+        connection.bindActivity((raw) => session.reportActivity(raw));
         const nativeSessionId = activeSession.sessionId.length > 0 ? activeSession.sessionId : null;
         bindDivertedUpdates(connection, activeSession.sessionId, session);
         return { session, nativeSessionId, configOptions: snapshot };
@@ -453,6 +605,22 @@ export class AcpSession {
      * array forever. `current()` instead re-reads `initial.configOptions` every time, until a real
      * `setConfigOption` call produces a snapshot of its own — so a caller that populates `initial`
      * (a mutable object) after construction is still seen.
+     *
+     * ### Opts claude into activity reporting exactly as {@link AcpSession.open} does
+     *
+     * `AcpSession.open` sends `_meta.claudeCode.emitRawSDKMessages` on `session/new` and calls
+     * `connection.bindActivity(...)` right after constructing its session (`:596`, `:631`). This method
+     * used to do neither, permanently losing activity reporting for every reconnect and every
+     * adoption of a claude session, even though `agentInfo.name` still made it report
+     * `reportsActivity: true` on `agent_opened` — see `protocol/agent.ts`'s `reportsActivity` field doc
+     * for how that gap was measured and closed. The `_meta` half is now sent by the caller: this
+     * method does not issue `session/load` itself (see this method's own opening paragraph — the
+     * caller already did, before calling this), but `adoption.ts`'s `replayNativeSession` — the
+     * function that does issue it — sends the exact same opt-in `AcpSession.open` sends, via the same
+     * `newSessionMetaFor` filter, so there is exactly one place that decides which agents opt in. This
+     * method's own half is `bindActivity` below, called unconditionally right after construction, the
+     * same as `open` — a connection whose agent never sends `_claude/sdkMessage` simply never invokes
+     * the sink.
      */
     static attach(connection, sessionId, updates, initial) {
         const agent = connection.connection.agent;
@@ -508,12 +676,17 @@ export class AcpSession {
             cancel: () => agent.notify(methods.agent.session.cancel, { sessionId }),
             steer: (blocks, priority) => steerRequest(connection, sessionId, blocks, priority),
             setConfigOption: setConfigOptionRequest(connection, sessionId, current, (next) => (snapshot = next)),
+            stopAsyncTask: (asyncTaskId) => asyncTaskStopRequest(connection, sessionId, asyncTaskId),
             dispose: () => {
                 unsubscribe();
                 queue.fail(new Error(`[acp] session ${sessionId} was disposed`));
             },
         };
-        const attached = new AcpSession(driven, connection.connection.signal);
+        const attached = new AcpSession(driven, connection.connection.signal, connection);
+        // Same wiring `AcpSession.open` does right after constructing its session (`:631`) — see this
+        // method's own doc comment ("Opts claude into activity reporting exactly as `AcpSession.open`
+        // does") for why this half was missing and what closes it.
+        connection.bindActivity((raw) => attached.reportActivity(raw));
         bindDivertedUpdates(connection, sessionId, attached);
         return attached;
     }
@@ -527,7 +700,7 @@ export class AcpSession {
      * `PromptCapabilities.image` (`AcpConnection.capabilities.promptImage`, surfaced to callers as
      * `AcpAgentSession.supportsImageInput`), and enforcing that is the caller's job, not this method's.
      */
-    prompt(blocks) {
+    prompt(blocks, platformTurnId) {
         // Checked ahead of `closed`, and the reason this branch exists at all: a session can outlive its
         // read loop without anyone having closed it (a dead connection, an unmappable update), and then
         // nothing but this call is left to end the turn. Registered as a turn and finished on the spot,
@@ -535,7 +708,7 @@ export class AcpSession {
         // path exactly as it does on the live one — `agentSessions.ts` unblocks `TaskRegistry` and the
         // server closes the round off `onTurnDone` and nothing else. See {@link readLoopDead}.
         if (this.readLoopDead !== null) {
-            this.inFlightTurns.push({ interrupted: false });
+            this.inFlightTurns.push({ interrupted: false, platformTurnId });
             this.finishTurn('failed', undefined, this.readLoopDead);
             return;
         }
@@ -543,13 +716,16 @@ export class AcpSession {
             console.warn('[acp] dropping prompt for a session that is no longer running');
             return;
         }
-        // An adapter may have ended the preceding prompt before delivering its final chunks. Do not let
-        // those chunks borrow this prompt's completion marker: that makes the old answer appear only
-        // after the reader submits a new message.
-        this.flushLateMessageCompletion();
+        if (this.exactExecutionUnconfirmed || (this.inFlightTurns.length > 0 && (platformTurnId !== undefined ||
+            this.inFlightTurns.some((turn) => turn.platformTurnId !== undefined)))) {
+            throw new Error('An exact platform turn is still running; overlapping prompts are unavailable');
+        }
+        this.permissionsInterrupted = false;
         // One turn per prompt, always — see {@link inFlightTurns} for why an overlapping prompt must not
         // fold into the turn already running.
-        this.inFlightTurns.push({ interrupted: false });
+        this.inFlightTurns.push({ interrupted: false, platformTurnId });
+        if (platformTurnId !== undefined)
+            this.exactExecutionUnconfirmed = true;
         // The `.catch(() => {})` is not error handling — `ActiveSession.prompt()` already routes this
         // same rejection onto the `nextUpdate()` queue internally (see the file doc comment), and
         // `runReadLoop`'s catch branch is what turns it into a `TurnResult`. It exists only so the
@@ -590,25 +766,65 @@ export class AcpSession {
     async setConfigOption(configId, value) {
         return this.session.setConfigOption(configId, value);
     }
+    /**
+     * Stop **one** background task on this session, leaving the running turn alone — the
+     * `_session/async_task/stop` extension; see {@link asyncTaskStopRequest}.
+     *
+     * No {@link inFlightTurns} bookkeeping, for the same reason {@link steer} does none: this does not
+     * create a turn and, unlike {@link interrupt}, it does not end one either. The adapter's own
+     * comment is explicit that the parent prompt turn keeps running.
+     *
+     * Throws on a closed session rather than warning-and-returning the way {@link interrupt} does: a
+     * dropped interrupt still leaves the turn marked interrupted locally, so the caller's picture
+     * stays true, whereas a dropped stop leaves a background task running with the server told
+     * nothing — the exact silence this whole path exists to remove.
+     */
+    async stopAsyncTask(asyncTaskId) {
+        if (this.closed)
+            throw new Error('[acp] cannot stop a background task on a session that is no longer running');
+        return this.session.stopAsyncTask(asyncTaskId);
+    }
+    async providerTaskStop(taskId, requestId) {
+        if (this.closed)
+            throw new Error('[acp] cannot stop a provider task on a closed session');
+        return this.session.providerTaskStop?.(taskId, requestId) ?? Promise.reject(new Error('Provider task stop unavailable'));
+    }
     /**
      * Resolve one pending `session/request_permission` round trip. Unknown/already-answered
      * `requestId`s are silently ignored, matching the deleted Claude Code bridge's `answer()` — a
      * platform relaying a stale answer must not throw.
      */
     answer(requestId, outcome) {
-        const resolve = this.pendingApprovals.get(requestId);
-        if (!resolve)
+        this.settleApproval(requestId, outcome, 'answered');
+    }
+    cancelPendingApproval(requestId, outcome) {
+        this.settleApproval(requestId, outcome, 'canceled');
+    }
+    settleApproval(requestId, outcome, reason) {
+        const entry = this.pendingApprovals.get(requestId);
+        if (!entry || entry.connectionGeneration !== this.connectionGeneration)
             return;
         this.pendingApprovals.delete(requestId);
-        resolve(outcome);
+        if (this.settledApprovals.size >= 64)
+            this.callbacksComplete = false;
+        else
+            this.settledApprovals.set(requestId, reason);
+        this.publishCallbacks();
+        entry.resolve(outcome);
     }
     /**
      * Register a pending `session/request_permission` round trip. `permission.ts` calls this from its
      * `session/request_permission` handler and resolves the registered callback once the user (or
      * `close()`) answers it; nothing in this file calls it.
      */
-    registerPendingApproval(requestId, resolve) {
-        if (this.closed) {
+    registerPendingApproval(requestId, resolve, address) {
+        const origin = address?.originNativeSessionId ?? this.session.sessionId;
+        if (!origin.trim() || (origin !== this.session.sessionId && !this.permissionOrigins.has(origin))) {
+            console.error(JSON.stringify({ component: 'acp', error: 'invalid_permission_origin', origin, rootRuntimeId: this.rootRuntimeId }));
+            resolve(ABANDONED_ANSWER);
+            return;
+        }
+        if (this.closed || this.readLoopDead !== null || this.connectionAborted || this.permissionsInterrupted) {
             // A permission request that reaches us after our own close() has nobody left to answer it —
             // review finding (task-5, item 2): registering it anyway would park a card `close()`'s own
             // drain already ran past, and the agent would wait forever for a response nothing will send.
@@ -617,7 +833,44 @@ export class AcpSession {
             resolve(ABANDONED_ANSWER);
             return;
         }
-        this.pendingApprovals.set(requestId, resolve);
+        if ([requestId, origin, address?.rpcRequestId ?? requestId].some((value) => !value.trim() || Buffer.byteLength(value, 'utf8') > 256 || /[\x00-\x1f\x7f]/.test(value)) ||
+            this.pendingApprovals.size >= 64 || this.pendingApprovals.has(requestId) || this.settledApprovals.has(requestId)) {
+            this.callbacksComplete = false;
+            this.publishCallbacks();
+            resolve(ABANDONED_ANSWER);
+            return;
+        }
+        this.pendingApprovals.set(requestId, {
+            connectionGeneration: this.connectionGeneration, rootRuntimeId: this.rootRuntimeId,
+            originNativeSessionId: origin, rpcRequestId: address?.rpcRequestId ?? requestId, resolve,
+        });
+        this.publishCallbacks();
+    }
+    /**
+     * Resolve one pending `elicitation/create` round trip. Same contract as {@link answer}: an
+     * unknown or already-answered `requestId` is silently ignored, because a stale elicitation answer
+     * for a request that already settled must not throw.
+     */
+    answerElicitation(requestId, response) {
+        const resolve = this.pendingElicitations.get(requestId);
+        if (!resolve)
+            return;
+        this.pendingElicitations.delete(requestId);
+        resolve(response);
+    }
+    /**
+     * Register a pending `elicitation/create` round trip. Same contract as
+     * {@link registerPendingApproval}: once this session is closed, there is nobody left to answer,
+     * so the resolver settles immediately (`{action: 'cancel'}`, ACP's own real cancellation outcome
+     * — unlike a permission option id, there is no collision to guard against here) instead of ever
+     * being stored.
+     */
+    registerPendingElicitation(requestId, resolve) {
+        if (this.closed) {
+            resolve(ABANDONED_ELICITATION_ANSWER);
+            return;
+        }
+        this.pendingElicitations.set(requestId, resolve);
     }
     /**
      * Emit a wire event that did not come from `session/update` — `permission.ts` calls this from its
@@ -629,12 +882,78 @@ export class AcpSession {
      * comment) instead of racing a second, independent path a consumer would have to merge itself.
      */
     emitEvent(event) {
+        this.nativeTerminalRepair?.observe(event);
         if (this.closed) {
             // Same reasoning as `registerPendingApproval` above: once closed, nothing is left reading the
             // outbox on the other end that could still make sense of a fresh card.
             return;
         }
-        this.enqueue({ kind: 'event', event });
+        const payload = { ...event.payload };
+        if (event.eventName === 'permission_request') {
+            delete payload.callbackContext;
+            const callbackContext = this.callbackContextFor(event);
+            if (callbackContext)
+                payload.callbackContext = callbackContext;
+            const call = payload.toolCall;
+            const meta = call && typeof call === 'object' && !Array.isArray(call)
+                ? call._meta : undefined;
+            const sdkCallback = meta && typeof meta === 'object' && !Array.isArray(meta) &&
+                Object.prototype.hasOwnProperty.call(meta, 'qoderSdk');
+            if (sdkCallback && !callbackContext) {
+                if (typeof payload.requestId === 'string')
+                    this.cancelPendingApproval(payload.requestId, ABANDONED_ANSWER);
+                return;
+            }
+        }
+        const normalized = { ...event, payload,
+            ...(event.acpSessionId === this.session.sessionId ? { acpSessionId: undefined } : {}) };
+        for (const mapped of this.subworkBoundary?.map(normalized) ?? [normalized]) {
+            this.observePermissionOrigin(mapped);
+            this.enqueue({ kind: 'event', event: mapped });
+        }
+    }
+    callbackContextFor(event) {
+        if (event.eventName !== 'permission_request' || event.acpSessionId !== this.session.sessionId)
+            return;
+        const diagnostics = this.connection.runtimeDiagnostics;
+        const profile = diagnostics.profile;
+        const callbacks = diagnostics.callbacks;
+        const requestId = event.payload.requestId;
+        const toolCall = event.payload.toolCall;
+        if (!diagnostics.available || profile?.mode !== 'sdk-adapter' || profile.initialized !== true ||
+            profile.rootConfirmed !== true || profile.rootSessionId !== this.session.sessionId ||
+            !profile.runtimeGeneration || callbacks?.complete !== true ||
+            callbacks.rootSessionId !== this.session.sessionId ||
+            typeof requestId !== 'string' || !this.pendingApprovals.has(requestId) ||
+            !toolCall || typeof toolCall !== 'object' || Array.isArray(toolCall))
+            return;
+        const call = toolCall;
+        const sdkMeta = call._meta && typeof call._meta === 'object' && !Array.isArray(call._meta)
+            ? call._meta.qoderSdk : undefined;
+        if (!sdkMeta || typeof sdkMeta !== 'object' || Array.isArray(sdkMeta))
+            return;
+        const sdk = sdkMeta;
+        const origin = sdk.origin;
+        if (sdk.version !== 1 || sdk.blockingScope !== 'root' || sdk.callbackOnly !== true ||
+            typeof sdk.requestId !== 'string' || !/^[0-9a-f-]{36}$/i.test(sdk.requestId) ||
+            !origin || typeof origin !== 'object' || Array.isArray(origin))
+            return;
+        const source = origin;
+        const toolUseId = call.toolCallId;
+        const agentId = source.agentId;
+        if (source.rootSessionId !== this.session.sessionId || source.runtimeGeneration !== profile.runtimeGeneration ||
+            typeof toolUseId !== 'string' || source.toolUseId !== toolUseId ||
+            !toolUseId || Buffer.byteLength(toolUseId, 'utf8') > 256 ||
+            (agentId !== undefined && (typeof agentId !== 'string' || !agentId || Buffer.byteLength(agentId, 'utf8') > 256)))
+            return;
+        const pending = callbacks.pending.find((entry) => entry.requestId === requestId &&
+            entry.originNativeSessionId === this.session.sessionId);
+        if (!pending || callbacks.pending.length > 64 || this.pendingApprovals.get(requestId)?.rpcRequestId !== pending.rpcRequestId)
+            return;
+        return { rootSessionId: this.session.sessionId, hostGeneration: diagnostics.generation,
+            connectionGeneration: callbacks.connectionGeneration, requestId,
+            runtimeGeneration: profile.runtimeGeneration, toolUseId,
+            ...(agentId ? { agentId } : {}), independent: false };
     }
     /**
      * Applies one `session/update` the transport diverted before the SDK could destroy it.
@@ -654,10 +973,10 @@ export class AcpSession {
      * on the connection, not just this one.
      */
     applyDivertedUpdate(diverted) {
-        const isChild = diverted.reason === 'foreign-session';
+        const isChild = diverted.sessionId !== this.session.sessionId;
         let events;
         try {
-            events = mapSessionUpdate(diverted.update, this.mapperState);
+            events = mapSessionUpdate(diverted.update, this.mapperFor(diverted.sessionId));
         }
         catch (err) {
             // An unmapped variant is a contract gap worth naming, not worth killing a session over. The
@@ -688,6 +1007,9 @@ export class AcpSession {
         // after the user pressed Stop.
         for (const turn of this.inFlightTurns)
             turn.interrupted = true;
+        this.permissionsInterrupted = true;
+        this.drainPendingApprovals();
+        this.drainPendingElicitations();
         try {
             await this.session.cancel();
         }
@@ -714,8 +1036,9 @@ export class AcpSession {
     async close() {
         if (!this.closed) {
             this.closed = true;
-            this.cancelLateMessageCompletion();
+            this.nativeTerminalRepair?.close();
             this.drainPendingApprovals();
+            this.drainPendingElicitations();
             try {
                 await this.session.cancel();
             }
@@ -725,6 +1048,10 @@ export class AcpSession {
             this.session.dispose();
         }
         await this.readLoopDone;
+        this.scopes.clear();
+        this.permissionOrigins.clear();
+        this.permissionParents.clear();
+        this.unresolvedPermissionOrigins.clear();
     }
     /**
      * Resolve every still-pending permission request with {@link ABANDONED_ANSWER} and clear the map.
@@ -735,9 +1062,18 @@ export class AcpSession {
      * connection ever calls `close()`.
      */
     drainPendingApprovals() {
-        for (const resolve of this.pendingApprovals.values())
-            resolve(ABANDONED_ANSWER);
+        const pending = [...this.pendingApprovals.values()];
         this.pendingApprovals.clear();
+        this.callbacksComplete = false;
+        this.publishCallbacks();
+        for (const entry of pending)
+            entry.resolve(ABANDONED_ANSWER);
+    }
+    /** {@link pendingElicitations}' half of {@link drainPendingApprovals} — same callers, same reason. */
+    drainPendingElicitations() {
+        for (const resolve of this.pendingElicitations.values())
+            resolve(ABANDONED_ELICITATION_ANSWER);
+        this.pendingElicitations.clear();
     }
     onEvent(cb) {
         this.eventSink = cb;
@@ -747,6 +1083,21 @@ export class AcpSession {
         this.turnSink = cb;
         this.drain();
     }
+    /** Registers this session's activity-state consumer. See {@link activitySink}. */
+    onActivity(cb) {
+        this.activitySink = cb;
+    }
+    /**
+     * Feeds one agent-reported activity-state push into this session's sink — the join point for both
+     * collection paths: codex-acp's `session_info_update._meta.codex.threadStatus`, via
+     * {@link scopes}' injected callback, and claude-agent-acp's `_claude/sdkMessage`
+     * extNotification, wired directly onto the connection in `AcpSession.open` (see there for why
+     * that registration cannot live inside `mapSessionUpdate`'s ordinary flow: the notification is not
+     * a `session/update` at all).
+     */
+    reportActivity(raw) {
+        this.activitySink?.(raw);
+    }
     // `backfill?()` is deliberately not implemented here: replaying an existing native session's
     // history is `session/load`, which is `adoption.ts`'s job ("领养"), not this file's. Not
     // `session/resume(replayFrom)`, as the plan text and an earlier version of this comment said —
@@ -777,6 +1128,7 @@ export class AcpSession {
                     // the manager's onTurnDone would never fire for it. All of them, not just the oldest: the
                     // queue is permanently failed, so no further stop message is ever coming for the rest.
                     this.readLoopDead = errorMessage(err);
+                    this.nativeTerminalRepair?.close();
                     this.finishAllTurns('interrupted', errorMessage(err));
                     return;
                 }
@@ -792,7 +1144,8 @@ export class AcpSession {
                 // branch below has always depended on that).
                 // `err` itself, not its message: this is the only frame in which the agent's JSON-RPC code
                 // still exists. `errorMessage(err)` on the same line is what destroyed it before.
-                this.finishTurn('failed', undefined, errorMessage(err), !this.connectionAborted, jsonRpcErrorCode(err));
+                const peerErrorCode = jsonRpcErrorCode(err);
+                this.finishTurn('failed', undefined, errorMessage(err), !this.connectionAborted, peerErrorCode, !this.connectionAborted && peerErrorCode !== undefined);
                 if (this.connectionAborted) {
                     // The connection died out from under us without our own close() ever running. Same
                     // reasoning as the `this.closed` branch above: the queue is now permanently failed, so no
@@ -803,16 +1156,18 @@ export class AcpSession {
                     // which is what {@link readLoopDead} gives it — finishing the turns open right now says
                     // nothing about the retry the user sends ten seconds from now.
                     this.readLoopDead = errorMessage(err);
+                    this.nativeTerminalRepair?.close();
                     this.finishAllTurns('failed', errorMessage(err));
                     // Nothing will drain pendingApprovals otherwise (review finding, task-5 item 5).
                     this.drainPendingApprovals();
+                    this.drainPendingElicitations();
                     return; // the connection itself is gone; further reads would just spin
                 }
                 continue;
             }
             if (message.kind === 'session_update') {
                 try {
-                    for (const event of mapSessionUpdate(message.update, this.mapperState))
+                    for (const event of mapSessionUpdate(message.update, this.mapperFor(this.session.sessionId)))
                         this.routeMappedEvent(event);
                 }
                 catch (err) {
@@ -848,6 +1203,7 @@ export class AcpSession {
                     // turn with the shared cause, drain the approvals, stop reading.
                     console.error(`[acp] unmappable session/update; ending this session's turns: ${errorMessage(err)}`);
                     this.readLoopDead = errorMessage(err);
+                    this.nativeTerminalRepair?.close();
                     this.finishAllTurns('failed', errorMessage(err));
                     this.drainPendingApprovals();
                     return;
@@ -858,10 +1214,88 @@ export class AcpSession {
                 // own interrupt() was never called (a defensive backstop, not the primary path — see
                 // `finishTurn`'s interrupted-flag handling for that).
                 const status = message.stopReason === 'cancelled' ? 'interrupted' : 'completed';
-                this.finishTurn(status, message.stopReason);
+                this.finishTurn(status, message.stopReason, undefined, false, undefined, true);
+            }
+        }
+    }
+    /** Host-owned load history restores addresses, never actionable interactions or live events. */
+    observeReplayEvent(event) {
+        this.nativeTerminalRepair?.observe(event);
+        this.observePermissionOrigin(event);
+        this.observeBackgroundWriter(event);
+    }
+    observeBackgroundWriter(event) {
+        const input = event.payload.rawInput;
+        if (input && typeof input === 'object' && !Array.isArray(input) &&
+            input.run_in_background === true) {
+            // An explicitly requested detached writer has no authenticated termination signal here.
+            this.backgroundWriterUnconfirmed = true;
+        }
+        const output = event.payload.rawOutput;
+        if (output && typeof output === 'object' && !Array.isArray(output)) {
+            const evidence = output;
+            if (evidence.backgrounded === true && (typeof evidence.taskId === 'string' || typeof evidence.pid === 'number')) {
+                this.backgroundWriterUnconfirmed = true;
             }
         }
     }
+    /** Connection-local relations grant approval eligibility only after a complete path to our root. */
+    observePermissionOrigin(event) {
+        if (event.eventName !== 'subagent_spawned')
+            return;
+        const parent = event.acpSessionId ?? this.session.sessionId;
+        const child = event.payload.subagentSessionId;
+        const reject = (reason) => console.warn(JSON.stringify({
+            component: 'acp', error: 'invalid_permission_relation', reason,
+            parent, child, rootRuntimeId: this.rootRuntimeId,
+        }));
+        if (typeof parent !== 'string' || !parent.trim() || typeof child !== 'string' || !child.trim()) {
+            reject('invalid_native_id');
+            return;
+        }
+        if (child === parent || child === this.session.sessionId) {
+            reject(child === parent ? 'self_parent' : 'root_reparent');
+            return;
+        }
+        const existing = this.permissionParents.get(child);
+        if (existing !== undefined) {
+            if (existing !== parent)
+                reject('conflicting_parent');
+            return;
+        }
+        // Include unresolved edges: otherwise two untrusted parents could first form a cycle and
+        // become eligible later when one is named by the root. Rejected edges never enter the graph.
+        for (let ancestor = parent; ancestor !== undefined; ancestor = this.permissionParents.get(ancestor)) {
+            if (ancestor === child) {
+                reject('cycle');
+                return;
+            }
+        }
+        const trusted = parent === this.session.sessionId || this.permissionOrigins.has(parent);
+        if (!trusted && this.unresolvedPermissionOrigins.size >= 1024) {
+            reject('unresolved_capacity');
+            return;
+        }
+        this.permissionParents.set(child, parent);
+        if (!trusted) {
+            this.unresolvedPermissionOrigins.add(child);
+            return;
+        }
+        this.permissionOrigins.add(child);
+        // A bounded fixed-point walk handles arbitrarily reversed arrival order, including replay.
+        // Only relation events run it; ordinary event/approval traffic never scans these edges.
+        let promoted;
+        do {
+            promoted = false;
+            for (const candidate of this.unresolvedPermissionOrigins) {
+                if (this.permissionOrigins.has(this.permissionParents.get(candidate))) {
+                    this.unresolvedPermissionOrigins.delete(candidate);
+                    this.permissionOrigins.add(candidate);
+                    promoted = true;
+                }
+            }
+        } while (promoted);
+    }
     /**
      * Routes one mapped `WireEvent` to the outbox, tracking `agent_message_chunk`/`agent_thought_chunk`
      * on the way through so `agent_message` can be synthesized at the right moments — the one per-turn
@@ -871,17 +1305,18 @@ export class AcpSession {
      * event, and the server folds it.
      */
     routeMappedEvent(event) {
-        const isAssistantChunk = event.eventName === 'agent_message_chunk' || event.eventName === 'agent_thought_chunk';
-        if (isAssistantChunk) {
-            this.trackMessageBoundary(event);
+        if (this.foregroundOutput && !this.foregroundOutput.accept(event))
+            return;
+        this.nativeTerminalRepair?.observe(event);
+        for (const mapped of this.subworkBoundary?.map(event) ?? [event]) {
+            this.observePermissionOrigin(mapped);
+            this.observeBackgroundWriter(mapped);
+            if ((!this.subworkBoundary || !mapped.acpSessionId || mapped.acpSessionId === this.session.sessionId) &&
+                (mapped.eventName === 'agent_message_chunk' || mapped.eventName === 'agent_thought_chunk')) {
+                this.trackMessageBoundary(mapped);
+            }
+            this.enqueue({ kind: 'event', event: mapped });
         }
-        this.enqueue({ kind: 'event', event });
-        // `finishTurn` has already consumed the normal boundary. If an adapter emits content after it,
-        // give the rest of that burst a short chance to arrive, then synthesize the missing boundary
-        // ourselves. Without this, CoworkEngine correctly buffers the delta but can only flush it when
-        // an unrelated later user message happens to append an item.
-        if (isAssistantChunk && !this.turnRunning)
-            this.scheduleLateMessageCompletion();
     }
     /**
      * Notes that assistant content/thought is streaming, and — if a *different* `messageId` from the
@@ -912,26 +1347,6 @@ export class AcpSession {
         this.sawMessageContent = false;
         this.currentMessageId = null;
     }
-    /** Debounce a late chunk burst into one synthetic `agent_message` marker. */
-    scheduleLateMessageCompletion() {
-        this.cancelLateMessageCompletion();
-        this.lateMessageFlushTimer = setTimeout(() => {
-            this.lateMessageFlushTimer = null;
-            if (!this.closed && !this.turnRunning)
-                this.flushMessageCompleted();
-        }, LATE_MESSAGE_SETTLE_MS);
-    }
-    /** Flush a late tail before its contents can be mistaken for a later prompt's answer. */
-    flushLateMessageCompletion() {
-        this.cancelLateMessageCompletion();
-        this.flushMessageCompleted();
-    }
-    cancelLateMessageCompletion() {
-        if (this.lateMessageFlushTimer === null)
-            return;
-        clearTimeout(this.lateMessageFlushTimer);
-        this.lateMessageFlushTimer = null;
-    }
     /**
      * Terminate every turn still in flight — for the one path (a permanently failed read queue) where
      * no further stop message can arrive for any of them.
@@ -956,12 +1371,14 @@ export class AcpSession {
      * `agentRefused` — the single `if` below is what keeps the code and the attribution from ever
      * disagreeing, rather than two conditions someone can later edit apart.
      */
-    finishTurn(status, stopReason, error, agentRefused = false, errorCode) {
+    finishTurn(status, stopReason, error, agentRefused = false, errorCode, executionEnded = false) {
         // The oldest unfinished turn, popped: one stop message (or one prompt rejection) ends exactly
         // one turn, so a second overlapping turn keeps its own result instead of being swallowed.
         const turn = this.inFlightTurns.shift();
         if (!turn)
             return;
+        if (this.inFlightTurns.length === 0)
+            this.foregroundOutput?.endTurn();
         // Must land before the TurnResult below. Unconditionally safe to call — a no-op when nothing
         // was accumulated — so every path that can end a turn (a normal stop, an interrupt, a failed
         // request, or close() mid-turn) goes through exactly this one place rather than each needing to
@@ -971,7 +1388,18 @@ export class AcpSession {
         // A turn this session itself interrupted always reports 'interrupted', regardless of what the
         // agent's own response claims — mirrors the deleted Claude Code bridge's finishTurn.
         const resolved = turn.interrupted ? 'interrupted' : status;
+        if (resolved === 'interrupted') {
+            this.permissionsInterrupted = true;
+            this.drainPendingApprovals();
+            this.drainPendingElicitations();
+        }
         const result = { status: resolved };
+        if (turn.platformTurnId !== undefined)
+            result.platformTurnId = turn.platformTurnId;
+        if (executionEnded && this.inFlightTurns.length === 0 && !this.backgroundWriterUnconfirmed) {
+            result.executionEnded = true;
+            this.exactExecutionUnconfirmed = false;
+        }
         if (resolved === 'completed' && stopReason && stopReason !== 'cancelled') {
             result.stopReason = mapStopReason(stopReason);
         }