@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/permission.js

@@ -35,20 +35,29 @@
  *
  * `elicitation/create`'s `mode` union is **open** (`"form" | "url" | string`, per
  * `CreateElicitationRequest`'s schema comment: "Custom or future elicitation mode" — a bare `string`
- * arm, unlike `session/update`'s closed 15-member union). Axom's wire vocabulary now *has* the
+ * arm, unlike `session/update`'s closed 15-member union). Axom's wire vocabulary has the
  * `elicitation_request`/`elicitation` pair (Plan B renamed the platform's own interaction events onto
- * ACP's words). The two names are not in the same state: `elicitation_request` (`InteractionRequested`)
- * still has no bridge decode path — `TimelineEventWire.decode` has no branch for it, so a bridge
- * emitting it is rejected outright — but bare `elicitation` (`UserInteractionRequested`) has had a named
- * decode branch since `TimelineEventWire.kt:127`, and it is answerable end to end: decode rebuilds the
- * typed event, `CoworkEngine` lands a `USER_INTERACTION` item and parks the turn, and once the user
- * answers, `ExternalAgentSessionRuntime.execute` forwards the reply through `channel.prompt(runId,
- * context.userText, ...)`. `'form'` still declines — it ships an arbitrary JSON-Schema
- * `requestedSchema` (`ElicitationSchema`) that nothing on Axom's wire translates into that fixed Q&A
- * shape — and the open `default` arm still declines everything else the SDK or a nonstandard agent
- * might send, for the same reason: neither has anywhere to go yet, and declining is what keeps them
- * defensible — it never hangs the agent and it never fabricates a user's consent for input nobody was
- * ever shown.
+ * ACP's words); both are answerable end to end now, but along different paths. `elicitation_request`
+ * (`TimelineEvent.ElicitationRequested`) is what {@link handleFormElicitation} raises for `'form'`
+ * mode (this task, Task 18) — `TimelineEventWire.decodeElicitationRequested` rebuilds it, lands a
+ * `WorkItemKind.USER_INTERACTION` item, parks the run, and the user's answer travels back over its own
+ * frame, `AgentFrame.AgentElicitationAnswer` (Task 17), through `AcpSession.answerElicitation`. Bare
+ * `elicitation` (`UserInteractionRequested`) is the *platform's own* agents asking a question — a
+ * named decode branch since `TimelineEventWire.kt:127` — and answers through `ExternalAgentSessionRuntime
+ * .execute` forwarding the reply as a normal `channel.prompt(runId, context.userText, ...)`; a bridged
+ * agent's `elicitation/create` never produces this one.
+ *
+ * `'form'`'s wire capability (`acpClient.ts`'s `clientCapabilities.elicitation.form`) is what makes the
+ * whole thing reachable in the first place: `claude-agent-acp` puts `AskUserQuestion` into
+ * `disallowedTools` (`dist/acp-agent.js:5959`) unless it is declared, so before that line existed the
+ * model had no tool to call `elicitation/create` from at all. {@link handleFormElicitation} answers it
+ * following {@link handleRequestPermission}'s own shape — see that function's doc comment for the
+ * four properties carried over deliberately, and {@link handleFormElicitation}'s own doc comment for
+ * the one place the two diverge (a schema outside Axom's profile still raises the card before
+ * declining, rather than being refused in silence the way an empty form is). The open `default` arm
+ * still declines everything the SDK or a nonstandard agent sends outside `'form'`/`'url'`, for the
+ * same reason it always has: it has nowhere to go, and declining is what keeps it defensible — it
+ * never hangs the agent and it never fabricates a user's consent for input nobody was ever shown.
  *
  * `'url'` is different: it is the shape some agents use to hand a sign-in link to the reader (Codex's
  * device-code flow reaches it through `elicitation/create` once `elicitation.url` is declared in
@@ -113,10 +122,9 @@ function toolCallPayload(toolCall) {
  * ACP `RequestPermissionRequest` (`types.gen.d.ts:108`) on Axom's wire: `{toolCall, options}` plus
  * `requestId`.
  *
- * `requestId` is the one admitted extension — ACP correlates the answer through the JSON-RPC request
- * id, which lives in the envelope (`ClientRequestContext.requestId`), and an event stream has no
- * envelope. `sessionId`, ACP's third field (`:112`), is deliberately not carried: the event is
- * already being delivered on a specific run.
+ * `requestId` is a host-derived resolver token — {@link permissionRequestId}, the same on the live
+ * path and in the ACP processor. The raw JSON-RPC ID stays local to its connection; exact `sessionId`
+ * travels in the wire event's `acpSessionId` origin field.
  *
  * **`toolCall` is nested, not flattened.** The flattened version lifted the tool's
  * `name`/`title`/`kind`/`arguments` to the top level, which put `name` (the tool's programmatic name,
@@ -127,9 +135,10 @@ function toolCallPayload(toolCall) {
  * `toolCall.title`, and the renderer computes it from the same field now
  * (`WorkTimelineInteractions.foldPermission`) instead of storing a second, drifting copy.
  */
-function buildPermissionRequestedEvent(input) {
+export function buildPermissionRequestedEvent(input) {
     return {
         eventName: 'permission_request',
+        ...(input.sessionId !== undefined ? { acpSessionId: input.sessionId } : {}),
         payload: {
             requestId: input.requestId,
             toolCall: toolCallPayload(input.toolCall),
@@ -155,7 +164,7 @@ function buildPermissionRequestedEvent(input) {
  * `sink.answer` — the agent gave up on this specific request, so nothing should still expect an
  * answer for it. Session-level abandonment (the session closing, or the connection dying) is instead
  * `AcpSession`'s own job (`registerPendingApproval` resolving immediately when already closed, and
- * `runReadLoop` draining on an aborted connection) — see `acpSession.ts`.
+ * `runReadLoop` draining on an aborted connection) — see the old `acpSession.ts` (deleted in Task 29).
  *
  * The eventual answer is whatever string reaches `sink`'s registered resolver: normally one of
  * `input.options`' own `optionId`s (relayed from the user through `AcpSession.answer`), but both
@@ -194,14 +203,17 @@ export async function handleRequestPermission(input, sink) {
         };
         sink.registerPendingApproval(input.requestId, (outcome) => {
             settle(optionIds.has(outcome) ? { outcome: 'answered', optionId: outcome } : { outcome: 'rejected' });
-        });
+        }, input.sessionId === undefined ? undefined : { originNativeSessionId: input.sessionId, rpcRequestId: input.rpcRequestId ?? input.requestId });
+        if (settled)
+            return;
         input.signal?.addEventListener('abort', () => {
             settle({ outcome: 'rejected' });
             // Purge the now-moot pending entry so a stray later answer doesn't linger against a request
             // the agent already gave up on. The `settle` above has already fixed this promise's outcome
             // (the `settled` guard makes the resolver this triggers a no-op), so the value passed here
             // only has to avoid accidentally matching a real option id.
-            sink.answer(input.requestId, unmatchableAnswerFor(input.options));
+            const cancel = sink.cancelPendingApproval?.bind(sink) ?? sink.answer.bind(sink);
+            cancel(input.requestId, unmatchableAnswerFor(input.options));
         }, { once: true });
         sink.emitEvent(event);
     });
@@ -211,26 +223,35 @@ function declineElicitation() {
     return { action: 'decline' };
 }
 /**
- * Answer `elicitation/create`. `'url'` accepts and hands the URL out through `deps.present` **only
- * when both hold**: the request itself actually carries a string `elicitationId`/`url` (a
- * nonconforming agent that omits either gets declined, never `present(undefined, undefined)`), and a
- * real `deps.present` is wired (see {@link PresentElicitationUrl}'s doc comment — its absence means
- * declining, not accepting into a void). Every other arm still declines — see the class doc comment
- * for why. Accepting here does **not** mean the user finished anything; it means "the URL has been put
+ * Answer `elicitation/create`, dispatching on `request.mode`. `'url'` accepts and hands the URL out
+ * through `ctx.present` **only when both hold**: the request itself actually carries a string
+ * `elicitationId`/`url` (a nonconforming agent that omits either gets declined, never
+ * `present(undefined, undefined)`), and a real `ctx.present` is wired (see
+ * {@link PresentElicitationUrl}'s doc comment — its absence means declining, not accepting into a
+ * void). Accepting here does **not** mean the user finished anything; it means "the URL has been put
  * in front of them", matching ACP's own `accept` semantics for this mode — which is exactly why both
- * guards exist: an `accept` this module cannot back with a shown URL would make that claim false.
+ * guards exist: an `accept` this module cannot back with a shown URL would make that claim false. This
+ * branch, and this doc paragraph, are unchanged by Task 18 — only `'form'` moved.
+ *
+ * `'form'` is answered by {@link handleFormElicitation} — see its own doc comment, which is also
+ * where the four properties it deliberately carries over from {@link handleRequestPermission} are
+ * listed, and the one place it diverges.
  *
  * The `switch` has a real `default`, not just `'form'`/`'url'` cases, because `CreateElicitationRequest['mode']`
  * is `"form" | "url" | string` — an **open** union (unlike `session/update`'s closed 15-member one).
  * Falling through with no default would mean the client's response is `undefined` for any mode the SDK
  * or a nonstandard agent invents next, sending a malformed JSON-RPC result the agent may wait on
  * forever instead of a clean, immediate decline.
+ *
+ * `sink` is threaded through every mode uniformly (`registerPermissionHandlers` always has one, one
+ * per connection — see `PermissionSink`'s own doc comment) even though only `'form'` reads it; passing
+ * it unconditionally here is simpler than a second entry point that exists solely to omit an unused
+ * parameter, and every arm below is still free to ignore it.
  */
-export function handleCreateElicitation(request, deps) {
+export async function handleCreateElicitation(request, ctx, sink) {
     switch (request.mode) {
         case 'form':
-            // No form-rendering UI exists on Axom's wire yet — see the class doc comment.
-            return declineElicitation();
+            return handleFormElicitation(request, ctx, sink);
         case 'url': {
             const { elicitationId, url } = request;
             if (typeof elicitationId !== 'string' || typeof url !== 'string') {
@@ -239,13 +260,13 @@ export function handleCreateElicitation(request, deps) {
                 // path. The elicitation still gets answered (declined), never left to hang.
                 return declineElicitation();
             }
-            if (!deps.present) {
+            if (!ctx.present) {
                 // Nobody to show it to yet — see `PresentElicitationUrl`'s doc comment. Declining here is
                 // what an agent (or an MCP server proxied through one) raising this mid-turn can actually
                 // act on, unlike an `accept` that then goes nowhere.
                 return declineElicitation();
             }
-            deps.present(elicitationId, url);
+            ctx.present(elicitationId, url);
             return { action: 'accept' };
         }
         default:
@@ -255,6 +276,241 @@ export function handleCreateElicitation(request, deps) {
             return declineElicitation();
     }
 }
+/**
+ * Is `key` a free-text companion the server will *fold away* (`<key>_custom`,
+ * `ElicitationRequest.CUSTOM_SUFFIX` on the Kotlin side, `claude-agent-acp`'s own
+ * `question_<n>_custom` shape) rather than something the reader gets a row for? A folded companion
+ * must not be counted when deciding whether a schema has anything to draw at all.
+ *
+ * **The suffix alone is not the rule — the owner has to exist.** This used to return `true` for any
+ * `_custom`-suffixed key, which matched a server that *dropped* an ownerless one. Task 9 (ruling
+ * R15) changed that: `elicitationRequestFromPayload` now lands an ownerless `_custom` key as a
+ * read-only `UNPRESENTABLE` entry instead of discarding it, so a schema made *entirely* of such keys
+ * decodes into a real (if all-read-only) card. Measured against the real decoder: `{"foo_custom":
+ * {"type":"string"}}` alone → `fields=[foo_custom:UNPRESENTABLE]`, not `null`. With the old
+ * suffix-only rule this function returned `[]` for that schema and {@link handleFormElicitation}'s
+ * empty-form guard declined it **without ever raising a card** — the card silently never appears and
+ * the agent gets a decline it did not earn, which is the "too narrow" half of the drift R24 is about.
+ *
+ * Checking that the owner is *also a property* is deliberately weaker than the server's own rule
+ * (which additionally requires the owner to be a single-/multi-select, ruling R13), and the weakness
+ * only ever runs in the safe direction: it can under-count fields (a `_custom` key whose owner is a
+ * scalar is folded here but is a read-only row server-side) and never over-count. Under-counting
+ * cannot wrongly reach zero — for it to fold a key away, the owner has to be a property, and that
+ * owner is itself counted. Zero here therefore still means zero server-side, which is the only thing
+ * the empty-form guard reads.
+ */
+function isFoldedCompanionKey(key, properties) {
+    if (!key.endsWith('_custom'))
+        return false;
+    const owner = key.slice(0, -'_custom'.length);
+    return owner.length > 0 && Object.prototype.hasOwnProperty.call(properties, owner);
+}
+/**
+ * The property keys of a `'form'` request's `requestedSchema.properties` that the reader will
+ * actually get a row for — `[]` for anything that isn't a legible `{properties: {...}}` object,
+ * including a missing `requestedSchema` altogether. This alone decides
+ * {@link handleFormElicitation}'s empty-form guard: zero keys here is the same "nothing legible
+ * could ever be raised" shape as `handleRequestPermission`'s `options.length === 0`, regardless of
+ * *why* there are zero (no schema, an empty `properties`, or a `properties` that is entirely folded
+ * companions).
+ *
+ * All three of those are the shapes the server-side decoder still drops outright — measured, not
+ * inferred: `{"properties":{}}`, `properties` that isn't an object, and a missing `requestedSchema`
+ * each return `null` from `elicitationRequestFromPayload`, because `MODE_FORM` requires
+ * `fields.isNotEmpty()`. Everything else it now decodes (see {@link handleFormElicitation}).
+ */
+export function elicitationFieldKeys(requestedSchema) {
+    const properties = requestedSchema?.properties;
+    if (properties === null || typeof properties !== 'object' || Array.isArray(properties))
+        return [];
+    const record = properties;
+    return Object.keys(record).filter((key) => !isFoldedCompanionKey(key, record));
+}
+/**
+ * Kotlin's `String.isBlank()`, restated: empty, or entirely whitespace. `validate.ts`'s
+ * `nonEmptyString` (`.length > 0`) does **not** catch `"   "` — `ElicitationRequest.init`'s
+ * `require(message.isNotBlank())` does, and so must this: a blank
+ * `message` throws inside `elicitationRequestFromPayload`'s `runCatching`. It is a **request-level**
+ * invariant, so unlike a malformed property it has no read-only fallback to degrade into — the whole
+ * request is dropped server-side, which is why this check survived Task 9's removal of the
+ * per-property profile predicate (see the ruling-R24 block below).
+ */
+export function isBlank(value) {
+    return value.trim().length === 0;
+}
+/**
+ * **Ruling R24, restated after Task 9 (D5′) — the predicate this block used to hold is gone because
+ * the server-side gap it predicted is gone.**
+ *
+ * There used to be an `isAxomProfileProperty`/`isAxomProfileSchema` pair here, a hand-written mirror
+ * of every `error()`/`require()` on `elicitationRequestFromPayload`'s answerable path. It existed
+ * because **one** malformed property took down the **whole** `elicitation_request` server-side: the
+ * throw escaped to that function's outer `runCatching`, the event was dropped, and the agent blocked
+ * on `elicitation/create` forever with nothing on screen to explain it. Declining before sending was
+ * the lesser evil — the agent at least unblocked — but it bought that by making the card never
+ * appear, which is the *other* silent failure.
+ *
+ * Task 9 removed the cause. Every one of those shapes now degrades to a single read-only
+ * `UNPRESENTABLE` entry inside an otherwise normal card (`ElicitationField`'s new kind; the
+ * per-property `runCatching` in `elicitationRequestFromPayload`), so there is nothing left at the
+ * *property* level for this client to predict. **Measured against the real Kotlin decoder, not read
+ * off the parser** — every payload `permission.test.ts` exercises was run through
+ * `elicitationRequestFromPayload` and only these still return `null`, all of them request-level and
+ * all of them already covered by the two guards {@link handleFormElicitation} keeps:
+ *
+ * | shape | verdict | guard that still catches it |
+ * |---|---|---|
+ * | **whitespace-only** `message` (`"   "`) | `null` (`ElicitationRequest.init`) | {@link isBlank}, emit-then-decline |
+ * | **empty** `message` (`""`) | `null`, same requirement | `validateWireEvent` rejects the event first → decline, **no card** |
+ * | `properties: {}` | `null` (`MODE_FORM` needs `fields.isNotEmpty()`) | {@link elicitationFieldKeys} → `[]` |
+ * | `properties` not an object | `null`, same requirement | {@link elicitationFieldKeys} → `[]` |
+ * | `requestedSchema` absent | `null`, same requirement | {@link elicitationFieldKeys} → `[]` |
+ *
+ * Final review F7 split that first row in two, because merging them wrote the verdict backwards for
+ * half of it: `""` never reaches emit-then-decline at all. {@link validateWireEvent} runs first
+ * (`decodeElicitationRequested`'s `nonEmptyString`, `validate.ts:164`) and rejects the event, so the
+ * reader gets **no card** — precisely the outcome emit-then-decline exists to avoid. Only
+ * *whitespace* makes it past that gate and into the path this table describes; the {@link isBlank}
+ * KDoc had the reason right all along (`nonEmptyString` does not see `"   "`), it was this row that
+ * folded the two cases into one sentence.
+ *
+ * Everything else decodes, including every shape this file used to decline: duplicate `const`s, a
+ * blank option `title`, a candidate-less `type: "array"`, an unknown or `_`-prefixed `type`, a
+ * scalar carrying candidates or a malformed `oneOf`/`items`/`anyOf`, a duplicate untitled `enum`
+ * value, a property that isn't an object at all, a blank property key, and an ownerless `_custom`
+ * key. Each becomes a visible read-only row; the reader can answer the rest of the card and submit,
+ * or press Skip (ruling D4/R19) to send `{action: 'decline'}` themselves.
+ *
+ * **The rule itself has not changed, only the answer it currently produces.** It is keyed on server
+ * behaviour: whenever whatever decodes a `CreateElicitationRequest` server-side starts *rejecting* a
+ * shape this client forwards, a predicate has to come back here in the same commit — otherwise the
+ * agent parks on `elicitation/create` forever waiting for an answer that cannot be produced. And if
+ * a reintroduced predicate is ever narrower than the decoder, the card silently never appears and
+ * the agent gets a decline it did not earn. Both directions have shipped bugs (Task 8, Task 8.5);
+ * measure them against the real decoder rather than against a reading of this file.
+ */
+/**
+ * ACP `CreateElicitationRequest`'s `'form'` arm folded onto Axom's `elicitation_request` wire shape —
+ * the mirror of `buildPermissionRequestedEvent` above, and the payload
+ * `TimelineEventWire.decodeElicitationRequested`/`elicitationRequestFromPayload` expect.
+ *
+ * `requestId` is `ctx.requestId` — the JSON-RPC envelope id — not ACP's own optional
+ * `ElicitationRequestScope.requestId` field on `request`, for the identical reason
+ * `buildPermissionRequestedEvent` reads its `requestId` off `PermissionRequestInput` rather than the
+ * request body: ACP correlates the eventual answer through the envelope, and an event stream has none.
+ *
+ * `requestedSchema` is forwarded **verbatim** — Global Constraint 3, "transport, not translation" (see
+ * `toolCallPayload`'s doc comment for the same rule applied to `ToolCallUpdate`): this function does
+ * not narrow a field to fit Axom's profile, and it does not strip a field outside it either. The wire
+ * event always carries exactly what the agent asked; {@link handleFormElicitation} is what decides,
+ * from that same schema, whether to wait for an answer or decline right after raising the card.
+ */
+export function buildElicitationRequestedEvent(request, requestId) {
+    return {
+        eventName: 'elicitation_request',
+        payload: {
+            requestId,
+            ...(typeof request.toolCallId === 'string' ? { toolCallId: request.toolCallId } : {}),
+            request: {
+                mode: request.mode,
+                message: request.message,
+                requestedSchema: request.requestedSchema,
+            },
+            answer: null,
+        },
+    };
+}
+/**
+ * `'form'`-mode `elicitation/create` — the counterpart to {@link handleRequestPermission} this
+ * module's class doc comment promises. Four properties carried over deliberately:
+ *
+ * 1. **Every path settles.** The `Promise` below always resolves — including the two guard clauses
+ *    above it, both still inside this `async function` — because the agent is blocked on
+ *    `session/prompt` until it does.
+ * 2. **An empty form is refused before it is raised**, mirroring `handleRequestPermission`'s
+ *    `options.length === 0` hard refusal: a `requestedSchema` with zero answerable fields (missing
+ *    entirely, `properties: {}`, or `properties` that is entirely `_custom` companions — see
+ *    {@link elicitationFieldKeys}) is a card nobody could ever answer, which is worse than no card.
+ * 3. **`ctx.signal` aborting settles `{action: 'cancel'}` and purges the pending entry** — ACP's own
+ *    real cancellation outcome (see `AcpSession`'s `ABANDONED_ELICITATION_ANSWER` doc comment for why
+ *    this needs no randomized sentinel the way `handleRequestPermission`'s purge value does), so a
+ *    card nobody is listening to answer does not linger in `AcpSession`'s pending map.
+ * 4. **The open `default` arm stays reachable** — one level up, in {@link handleCreateElicitation}'s
+ *    own `switch`, not repeated here.
+ *
+ * **Where this diverges from the template**, deliberately: a blank `message` ({@link isBlank}) still
+ * **raises the card** before declining — the question is legible, `ElicitationRequest.init` just
+ * rejects the message server-side. It declines only *after* raising, instead of the guard-clause
+ * silence `handleRequestPermission` uses for its one hard-refusal case. Dropping the event here
+ * instead would leave the user seeing neither the question the agent asked nor any reason nothing
+ * happened (spec §12 D5′). This is the *opposite* of the empty-form case above, which has nothing
+ * legible to draw at all — raising a card for it would show the user a form with no fields on it,
+ * not a degraded but real question.
+ *
+ * **A schema with fields Axom cannot render no longer takes this exit** (Task 9, ruling R24): those
+ * decode into read-only rows server-side, so this handler waits for a real answer — which the reader
+ * supplies either by answering the rest of the card or by pressing Skip (`{action: 'decline'}`,
+ * ruling D4). See the ruling-R24 block above for the measured list of what still fails to decode.
+ */
+async function handleFormElicitation(request, ctx, sink) {
+    const requestId = ctx.requestId;
+    if (!sink || !requestId) {
+        // Defensive only: `registerPermissionHandlers` — the one real caller — always supplies both,
+        // reading `requestId` off the JSON-RPC envelope. Nothing to raise a card through or correlate an
+        // answer with, so there is nothing left to do but decline, same as the empty-form case below.
+        return declineElicitation();
+    }
+    if (ctx.signal?.aborted) {
+        // Mirrors `handleRequestPermission`'s identical early check: a listener added *after* `abort()`
+        // already fired never sees it (`AbortSignal` does not replay past events), so without this guard
+        // the mid-flight listener below would never fire and this would hang forever instead of settling.
+        return { action: 'cancel' };
+    }
+    const fieldKeys = elicitationFieldKeys(request.requestedSchema);
+    if (fieldKeys.length === 0) {
+        return declineElicitation();
+    }
+    const event = buildElicitationRequestedEvent(request, requestId);
+    const rejection = validateWireEvent(event);
+    if (rejection) {
+        // Defensive only, same reasoning as `handleRequestPermission`'s identical check: every field here
+        // is derived from ACP's own typed request, so a conforming agent can never actually trip this.
+        console.error(`[acp] refusing to raise an elicitation card that fails validateWireEvent: ${rejection.reason}`);
+        return declineElicitation();
+    }
+    if (isBlank(request.message)) {
+        // Legible, just not collectible here — raise it, then decline. See this function's own doc
+        // comment for why this is not the same as the empty-form guard above. A blank `message` is the
+        // **only** reason left for this branch: `ElicitationRequest.init`'s `require(message.isNotBlank())`
+        // is a request-level invariant, so the throw takes the whole request down with no read-only
+        // fallback to catch it, and `validate.ts`'s own `nonEmptyString` (`.length > 0`) does not see
+        // `"   "`. Every *property*-level reason that used to route here now decodes into a read-only row
+        // instead — see the ruling-R24 block above for the measured table.
+        sink.emitEvent(event);
+        return declineElicitation();
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (response) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(response);
+        };
+        sink.registerPendingElicitation(requestId, settle);
+        ctx.signal?.addEventListener('abort', () => {
+            settle({ action: 'cancel' });
+            // Purge the now-moot pending entry, exactly like `handleRequestPermission`'s own purge call —
+            // the `settled` guard above already makes a later real answer a no-op for this promise, but
+            // without this the entry would linger in `AcpSession.pendingElicitations` forever. `'cancel'`
+            // is ACP's own real cancellation outcome, so — unlike `handleRequestPermission`'s
+            // `unmatchableAnswerFor` — there is no collision to guard against here.
+            sink.answerElicitation(requestId, { action: 'cancel' });
+        }, { once: true });
+        sink.emitEvent(event);
+    });
+}
 /**
  * `elicitation/complete` fires only for an elicitation the client previously accepted — now the `'url'`
  * mode, once the agent considers that round trip finished. This turns it into a `dismiss` call so
@@ -265,6 +521,35 @@ export function handleCreateElicitation(request, deps) {
 export function handleElicitationComplete(notification, deps) {
     deps.dismiss(notification.elicitationId);
 }
+/**
+ * The card id of one `session/request_permission`: `perm:<hostGeneration>:<JSON agent id>` (spec
+ * 2026-10-11 §5.4).
+ *
+ * ## Why derived, not random
+ *
+ * It used to be `randomUUID()` per invocation. A card id the server is already showing must still
+ * resolve after the daemon restarts underneath a live adapter, and a random id cannot: the re-presented
+ * request would get a new one, `settleApproval` ignores unknown ids, and the user's answer to the
+ * visible card would be lost (analysis A §4). Derived from the request itself, the same request gets
+ * the same id in every daemon generation, and the ACP processor — which may not draw randomness at
+ * all (`processor/guard.test.ts`) — computes it with this very function.
+ *
+ * ## Why it is still unique
+ *
+ * - `hostGeneration` identifies one adapter process: the keeper's `spawnId` on the processor path,
+ *   `AgentRuntimeDiagnostics.generation` (fresh per `connectAgent`) on today's live path — the same
+ *   value published as `callbackContext.hostGeneration`. A reconnect is a new process, so a new
+ *   generation: the agent's ids restart at 0 there without colliding with an earlier card.
+ * - Within one process the agent never reuses a pending JSON-RPC id. `JSON.stringify` keeps the
+ *   number `1` and the string `"1"` apart.
+ *
+ * Kept short enough for `AcpSession.registerPendingApproval`'s 256-byte rule for every id a real
+ * adapter sends; a pathological id longer than ~200 bytes is refused there, as an overlong
+ * `rpcRequestId` already was.
+ */
+export function permissionRequestId(hostGeneration, agentRequestId) {
+    return `perm:${hostGeneration}:${JSON.stringify(agentRequestId)}`;
+}
 /**
  * Register this module's three handlers onto `app`. Must run inside `connectAgent`'s `configure`
  * hook — see the file doc comment for why a post-connect `.onRequest`/`.onNotification` would compile
@@ -278,16 +563,23 @@ export function handleElicitationComplete(notification, deps) {
  * the call site instead. Its own `present` may still be omitted (see {@link PresentElicitationUrl}) —
  * that is `acpAgents.ts`'s session connection saying, on purpose, that a `url` elicitation raised
  * outside a login has nowhere to go, and it declines rather than accepting into nothing.
+ *
+ * `connection.generation` is the adapter process's generation — `connectAgent` hands it to its
+ * `configure` hook — and scopes the card ids {@link permissionRequestId} derives.
  */
-export function registerPermissionHandlers(app, sink, elicitationDeps) {
+export function registerPermissionHandlers(app, sink, elicitationDeps, connection) {
     app
         .onRequest(methods.client.session.requestPermission, async (ctx) => {
-        const decision = await handleRequestPermission({ requestId: String(ctx.requestId), toolCall: ctx.params.toolCall, options: ctx.params.options, signal: ctx.signal }, sink);
+        if (typeof ctx.params.sessionId !== 'string' || !ctx.params.sessionId.trim()) {
+            console.error(JSON.stringify({ component: 'acp', error: 'invalid_permission_origin', rpcRequestId: String(ctx.requestId) }));
+            return { outcome: { outcome: 'cancelled' } };
+        }
+        const decision = await handleRequestPermission({ requestId: permissionRequestId(connection.generation, ctx.requestId), rpcRequestId: String(ctx.requestId), sessionId: ctx.params.sessionId, toolCall: ctx.params.toolCall, options: ctx.params.options, signal: ctx.signal }, sink);
         return {
             outcome: decision.outcome === 'answered' ? { outcome: 'selected', optionId: decision.optionId } : { outcome: 'cancelled' },
         };
     })
-        .onRequest(methods.client.elicitation.create, (ctx) => handleCreateElicitation(ctx.params, elicitationDeps))
+        .onRequest(methods.client.elicitation.create, (ctx) => handleCreateElicitation(ctx.params, { present: elicitationDeps.present, requestId: String(ctx.requestId), signal: ctx.signal }, sink))
         .onNotification(methods.client.elicitation.complete, (ctx) => handleElicitationComplete(ctx.params, elicitationDeps));
 }
 /**
@@ -309,8 +601,14 @@ export function createDeferredPermissionSink() {
     return {
         sink: {
             emitEvent: (event) => requireBound().emitEvent(event),
-            registerPendingApproval: (requestId, resolve) => requireBound().registerPendingApproval(requestId, resolve),
+            registerPendingApproval: (requestId, resolve, address) => requireBound().registerPendingApproval(requestId, resolve, address),
+            cancelPendingApproval: (requestId, outcome) => {
+                const target = requireBound();
+                (target.cancelPendingApproval?.bind(target) ?? target.answer.bind(target))(requestId, outcome);
+            },
             answer: (requestId, outcome) => requireBound().answer(requestId, outcome),
+            registerPendingElicitation: (requestId, resolve) => requireBound().registerPendingElicitation(requestId, resolve),
+            answerElicitation: (requestId, response) => requireBound().answerElicitation(requestId, response),
         },
         bind(target) {
             // Review finding (task-5, item 4): silently replacing an already-bound sink on a second call

package/dist/workstation/acp/processor/checkpoint.js

@@ -0,0 +1,87 @@
+/**
+ * Processor checkpoints (spec 2026-10-11 §5.5): the state after record `offset`, as JSON.
+ *
+ * ## Two versions, two questions
+ *
+ * - `schema` answers "can this daemon **read** it?". An unknown schema throws
+ *   {@link CheckpointUnreadableError}; the caller then replays from the session's start (outbox and
+ *   watermark cover the frames already sent), or, if the log was truncated, marks the session
+ *   degraded and switches it at the next open (§5.5.6). Readability of older schemas is a test-guarded
+ *   promise: never change the meaning of an existing field without bumping `schema` and adding a
+ *   reader for the old one.
+ * - `processorVersion` answers "would **this** code have produced the same frames?". Bump it whenever
+ *   `step` can emit different output for the same records. A readable checkpoint from another
+ *   processor version is still restored — that is the whole point of cutting a head checkpoint at
+ *   upgrade — but the caller must not count replay-vs-outbox differences as divergence then.
+ *
+ * Checkpoints are cut only on record boundaries (a synchronous `step` leaves no half-processed record)
+ * and carry no secrets (`state.ts`).
+ */
+import { PROCESSOR_STATE_SCHEMA } from './state.js';
+/**
+ * Bump when `step`'s output for the same records changes. 2: Task 17a (turns, cards, `seq`; prompt
+ * methods refused by `rpc.request`). 3: Task 17b (`session/update` mapped, the open session bound
+ * from its response, config/steer/levels; events validated before numbering). 4: commands carry
+ * their `spawnId`; `processor.history_end` carries `droppedCount`; a prompt closes open history.
+ * 5: Task 17c (the callback snapshot in the runtime diagnostics and its revision bumps; Qoder SDK
+ * cards carry a `callbackContext`; the Qoder adapter boundaries; side-channel notes). 6: a process call's
+ * result waits for its child's first status; ended/delivered calls keep no dead data.
+ * 7: Task 20 — the `agent_install_outcome` note becomes a `step` event (it was an unknown note).
+ * 8: Task 21 — a level update after a load's response is folded live, not as history; the `agent_output_gap` note is a `step`.
+ */
+export const PROCESSOR_VERSION = 8;
+export const CHECKPOINT_SCHEMA = 1;
+export class CheckpointUnreadableError extends Error {
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** A detached copy of `state`, so later steps cannot reach into a checkpoint already handed out. */
+export function checkpointOf(state) {
+    return { schema: CHECKPOINT_SCHEMA, processorVersion: PROCESSOR_VERSION, offset: state.offset, state: clone(state) };
+}
+export function encodeCheckpoint(checkpoint) {
+    return JSON.stringify(checkpoint);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Parse and check a checkpoint blob (string or already-parsed JSON). */
+export function decodeCheckpoint(blob) {
+    let value = blob;
+    if (typeof blob === 'string') {
+        try {
+            value = JSON.parse(blob);
+        }
+        catch {
+            throw new CheckpointUnreadableError('checkpoint is not JSON');
+        }
+    }
+    if (!isRecord(value))
+        throw new CheckpointUnreadableError('checkpoint is not an object');
+    if (value.schema !== CHECKPOINT_SCHEMA)
+        throw new CheckpointUnreadableError(`unknown checkpoint schema ${JSON.stringify(value.schema)}`);
+    const { processorVersion, offset, state } = value;
+    if (typeof processorVersion !== 'number' || !Number.isInteger(processorVersion))
+        throw new CheckpointUnreadableError('checkpoint has no processorVersion');
+    if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < -1)
+        throw new CheckpointUnreadableError('checkpoint offset is invalid');
+    if (!isRecord(state) || state.schema !== PROCESSOR_STATE_SCHEMA)
+        throw new CheckpointUnreadableError('checkpoint state schema is unknown');
+    if (state.offset !== offset)
+        throw new CheckpointUnreadableError('checkpoint offset disagrees with its state');
+    for (const key of ['process', 'initialize', 'outbound', 'inbound', 'diagnostics', 'permissions', 'elicitations',
+        'permissionOrigins', 'permissionParents', 'unresolvedPermissionOrigins', 'open', 'mapperScopes', 'message', 'steers',
+        'asyncTasks', 'runtime', 'callbacks', 'boundaries']) {
+        if (!isRecord(state[key]))
+            throw new CheckpointUnreadableError(`checkpoint state has no ${key}`);
+    }
+    if (typeof state.seq !== 'number' || !Array.isArray(state.turns) || !Array.isArray(state.settledPermissions)) {
+        throw new CheckpointUnreadableError('checkpoint state has no session layer (seq/turns)');
+    }
+    if (!Array.isArray(state.steered) || !('configOptions' in state) || !('delegation' in state) || !('history' in state)
+        || !('activity' in state)) {
+        throw new CheckpointUnreadableError('checkpoint state has no open-session layer (Task 17b)');
+    }
+    return { schema: CHECKPOINT_SCHEMA, processorVersion, offset, state: clone(state) };
+}

package/dist/workstation/acp/processor/commands.js

@@ -0,0 +1,35 @@
+/** The line to write for `command`: `fill`ed from `resolve`, or `undefined` if its blocks are gone. */
+export function materializeLine(command, resolve) {
+    if (command.fill === undefined)
+        return command.line;
+    const blocks = resolve?.(command.fill.blocksRef);
+    if (blocks === undefined)
+        return undefined;
+    const message = JSON.parse(command.line);
+    // Assigning an existing key keeps its position: the line keeps the SDK's key order.
+    message.params.prompt = blocks;
+    return JSON.stringify(message);
+}
+export function executeDownCommands(sink, commands, resolve) {
+    const written = [];
+    const dropped = [];
+    const refused = [];
+    const unresolved = [];
+    for (const command of commands) {
+        if (sink.hasDown(command.cause)) {
+            dropped.push(command);
+            continue;
+        }
+        const line = materializeLine(command, resolve);
+        if (line === undefined) {
+            unresolved.push(command);
+            continue;
+        }
+        const { fill: _fill, ...rest } = command;
+        if (sink.writeDown({ ...rest, line }) === 'refused')
+            refused.push(command);
+        else
+            written.push(command);
+    }
+    return { written, dropped, refused, unresolved };
+}