@scotthuang/agent-knock-knock 0.12.29 → 0.12.30

package/dist/src/terminal-agent-bridge.js

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
-import { formatTerminalConversationId, parseTerminalConversationId, terminalControlCapabilitiesForAdapter } from "./terminal-agent-adapter.js";
+import { formatTerminalConversationId, parseTerminalConversationId, terminalControlCapabilitiesForAdapter, terminalApprovalActionForDecision, terminalApprovalChoices } from "./terminal-agent-adapter.js";
 import { enrichActiveProcessesWithTerminalControl, TerminalControlInputNotSentError } from "./terminal-control-provider.js";
 import { hasCanonicalTerminalEndpoint, sameTerminalControlIncarnation, terminalEndpointFromControlRef, terminalEndpointIdentityKey } from "./terminal-control-ref.js";
 import { CLAUDE_INJECTED_PASTE_FRAME_PROFILE, claudeInjectedPasteProofEligible, revalidateClaudeComposerProof, settleClaudeInjectedPasteComposer } from "./claude-injected-paste-proof.js";
+import { TERMINAL_INTERACTION_SCHEMA, TERMINAL_INTERACTION_VERSION, validateTerminalInteractionProjection, validateTerminalInteractionResponse } from "./terminal-interaction-protocol.js";
+import { inspectNativeQuestionnaire } from "./terminal-questionnaire-adapter.js";
 // Verified Codex profiles through 0.153.0 keep Enter in paste/newline mode for
 // 120ms after burst input. Cross that boundary rather than landing on it, and
 // also require observable composer stability instead of treating this delay
@@ -140,6 +142,9 @@ const CLAUDE_NATIVE_STATUS_SETTLE_BY_PROFILE = {
     }
 };
 const CODEX_LARGE_PASTE_CHAR_THRESHOLD = 1_000;
+const TERMINAL_INTERACTION_TTL_MS = 10 * 60 * 1_000;
+const TERMINAL_INTERACTION_IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const TERMINAL_INTERACTION_FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/u;
 /** A terminal send failed at a boundary that proves input never started. */
 export class TerminalInputNotStartedError extends Error {
     code = "AKK_TERMINAL_INPUT_NOT_STARTED";
@@ -214,6 +219,20 @@ export class NativeInspectionDismissalError extends Error {
         this.name = "NativeInspectionDismissalError";
     }
 }
+/**
+ * A response reservation or terminal input may already have happened. The
+ * same interaction must never be dispatched automatically after this error.
+ */
+export class TerminalInteractionDispatchReservedError extends Error {
+    stage;
+    code = "AKK_TERMINAL_INTERACTION_DISPATCH_RESERVED";
+    doNotRetry = true;
+    constructor(stage, message, options = {}) {
+        super(message, options);
+        this.stage = stage;
+        this.name = "TerminalInteractionDispatchReservedError";
+    }
+}
 function terminalSendComposerRequirements(agent, multiline, options) {
     const exactEmptyRetryAuthority = options.requireExactEmptyComposerAfterBeforeText;
     const requireExactEmptyComposerBeforeText = options.requireExactEmptyComposerBeforeText === true;
@@ -272,11 +291,152 @@ function throwPostTextHookFailureAfterUserEnter(enabled, error) {
         return;
     throw new TerminalEnterDispatchReservedError("user-explicit Codex Enter was dispatched but post-text bookkeeping failed; do not retry", { cause: error });
 }
+function terminalApprovalPreflight(input) {
+    const { adapter, inspection, decision } = input;
+    if (!inspection.approval.approvable) {
+        return { ready: false, result: {
+                approved: false,
+                blocked: inspection.approval.blocked,
+                reason: inspection.approval.reason,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                screenExcerpt: inspection.screenExcerpt
+            } };
+    }
+    if (decision === "approve_once" &&
+        (inspection.approval.action.mode ?? "keys") === "keys" &&
+        inspection.approval.action.keys.length === 0) {
+        return { ready: false, result: {
+                approved: false,
+                blocked: true,
+                decision,
+                reason: `${adapter.displayName} approval action has no keys`,
+                label: inspection.approval.action.label,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                screenExcerpt: inspection.screenExcerpt
+            } };
+    }
+    const action = terminalApprovalActionForDecision(inspection.approval, decision);
+    if (!action) {
+        return { ready: false, result: {
+                approved: false,
+                blocked: true,
+                decision,
+                reason: `${adapter.displayName} does not expose the ${decision} decision for this exact approval prompt`,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                screenExcerpt: inspection.screenExcerpt
+            } };
+    }
+    const decisionMode = action.mode ?? "keys";
+    const canonicalFingerprint = terminalApprovalFingerprint(adapter.agent, input.activeTerminalControl, inspection, { screen: input.screen, runtime: input.runtime, decision });
+    if (input.requiredDecisionMode &&
+        decisionMode !== input.requiredDecisionMode) {
+        return { ready: false, result: {
+                approved: false,
+                blocked: true,
+                reason: `${adapter.displayName} approval mode ${decisionMode} is not eligible for this decision`,
+                decision,
+                label: action.label,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                fingerprint: canonicalFingerprint,
+                screenExcerpt: inspection.screenExcerpt,
+                decisionMode,
+                requestId: action.requestId
+            } };
+    }
+    if (decisionMode === "keys" && action.keys.length === 0) {
+        return { ready: false, result: {
+                approved: false,
+                blocked: true,
+                reason: `${adapter.displayName} approval action has no keys`,
+                decision,
+                label: action.label,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                screenExcerpt: inspection.screenExcerpt
+            } };
+    }
+    if (!isTerminalApprovalPromptEvidence(inspection.approval.promptEvidence)) {
+        return { ready: false, result: {
+                approved: false,
+                blocked: true,
+                reason: `${adapter.displayName} approval prompt has no adapter-verified prompt evidence`,
+                decision,
+                label: action.label,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                screenExcerpt: inspection.screenExcerpt,
+                decisionMode,
+                requestId: action.requestId
+            } };
+    }
+    const legacyFingerprint = hasCanonicalTerminalEndpoint(input.terminalControl)
+        ? undefined
+        : terminalApprovalFingerprint(adapter.agent, input.terminalControl, inspection, { screen: input.screen, runtime: input.runtime, decision });
+    const useLegacyFingerprint = Boolean(input.expectedFingerprint &&
+        input.expectedFingerprint === legacyFingerprint);
+    const fingerprintControl = useLegacyFingerprint
+        ? input.terminalControl
+        : input.activeTerminalControl;
+    const fingerprint = useLegacyFingerprint
+        ? legacyFingerprint
+        : canonicalFingerprint;
+    if (adapter.agent === "claude" &&
+        !input.expectedFingerprint) {
+        return { ready: false, result: {
+                approved: false,
+                blocked: true,
+                reason: "screen approval requires the latest expected fingerprint",
+                decision,
+                key: action.keys.length === 1 ? action.keys[0] : undefined,
+                keys: action.keys,
+                label: action.label,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                cwd: inspection.approval.cwd,
+                toolName: inspection.approval.toolName,
+                requestDetail: inspection.approval.requestDetail,
+                fingerprint,
+                screenExcerpt: inspection.screenExcerpt,
+                decisionMode,
+                requestId: action.requestId
+            } };
+    }
+    if (input.expectedFingerprint &&
+        input.expectedFingerprint !== fingerprint) {
+        return { ready: false, result: {
+                approved: false,
+                blocked: true,
+                reason: "approval fingerprint changed before execution",
+                decision,
+                key: action.keys.length === 1 ? action.keys[0] : undefined,
+                keys: action.keys,
+                label: action.label,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                fingerprint,
+                screenExcerpt: inspection.screenExcerpt,
+                decisionMode,
+                requestId: action.requestId
+            } };
+    }
+    return {
+        ready: true,
+        action,
+        decisionMode,
+        fingerprintControl,
+        fingerprint
+    };
+}
 export class TerminalAgentBridge {
     registry;
     terminalProvider;
     verifyIdentity;
     nowMs;
+    now;
     sleep;
     diagnosticLog;
     constructor(options) {
@@ -284,6 +444,7 @@ export class TerminalAgentBridge {
         this.terminalProvider = options.terminalProvider;
         this.verifyIdentity = options.verifyIdentity;
         this.nowMs = options.nowMs ?? (() => performance.now());
+        this.now = options.now ?? (() => new Date());
         this.sleep = options.sleep ?? terminalSettleDelay;
         this.diagnosticLog = options.diagnosticLog;
     }
@@ -405,7 +566,8 @@ export class TerminalAgentBridge {
             const captured = await this.captureInspection(adapter, terminalControl, options);
             return statusFromInspection(adapter, captured.terminalControl, captured.inspection, {
                 screen: captured.screen,
-                runtime: options.runtime
+                runtime: options.runtime,
+                now: this.now()
             });
         }
         catch (error) {
@@ -1791,6 +1953,7 @@ export class TerminalAgentBridge {
     }
     async approve(agent, terminalControl, options = {}) {
         const adapter = this.registry.require(agent);
+        const decision = options.decision ?? "approve_once";
         if (!adapter.capabilities.terminalApproval ||
             !terminalControl.capabilities.includes("terminal_approval")) {
             return {
@@ -1812,124 +1975,27 @@ export class TerminalAgentBridge {
         const captured = await this.captureInspection(adapter, terminalControl, options);
         const { inspection } = captured;
         const activeTerminalControl = captured.terminalControl;
-        if (!inspection.approval.approvable) {
-            return {
-                approved: false,
-                blocked: inspection.approval.blocked,
-                reason: inspection.approval.reason,
-                promptKind: inspection.approval.promptKind,
-                command: inspection.approval.command,
-                screenExcerpt: inspection.screenExcerpt
-            };
-        }
-        const decisionMode = inspection.approval.action.mode ?? "keys";
-        if (options.requiredDecisionMode && decisionMode !== options.requiredDecisionMode) {
-            return {
-                approved: false,
-                blocked: true,
-                reason: `${adapter.displayName} approval mode ${decisionMode} is not eligible for this decision`,
-                label: inspection.approval.action.label,
-                promptKind: inspection.approval.promptKind,
-                command: inspection.approval.command,
-                fingerprint: terminalApprovalFingerprint(adapter.agent, activeTerminalControl, inspection, {
-                    screen: captured.screen,
-                    runtime: options.runtime
-                }),
-                screenExcerpt: inspection.screenExcerpt,
-                decisionMode,
-                requestId: inspection.approval.action.requestId
-            };
-        }
-        if (decisionMode === "keys" && inspection.approval.action.keys.length === 0) {
-            return {
-                approved: false,
-                blocked: true,
-                reason: `${adapter.displayName} approval action has no keys`,
-                label: inspection.approval.action.label,
-                promptKind: inspection.approval.promptKind,
-                command: inspection.approval.command,
-                screenExcerpt: inspection.screenExcerpt
-            };
-        }
-        if (decisionMode === "keys" &&
-            !isTerminalApprovalPromptEvidence(inspection.approval.promptEvidence)) {
-            return {
-                approved: false,
-                blocked: true,
-                reason: `${adapter.displayName} approval prompt has no adapter-verified prompt evidence`,
-                label: inspection.approval.action.label,
-                promptKind: inspection.approval.promptKind,
-                command: inspection.approval.command,
-                screenExcerpt: inspection.screenExcerpt,
-                decisionMode,
-                requestId: inspection.approval.action.requestId
-            };
-        }
-        const canonicalFingerprint = terminalApprovalFingerprint(adapter.agent, activeTerminalControl, inspection, {
+        const preflight = terminalApprovalPreflight({
+            adapter,
+            terminalControl,
+            activeTerminalControl,
+            inspection,
             screen: captured.screen,
+            decision,
+            expectedFingerprint: options.expectedFingerprint,
+            requiredDecisionMode: options.requiredDecisionMode,
             runtime: options.runtime
         });
-        const legacyFingerprint = hasCanonicalTerminalEndpoint(terminalControl)
-            ? undefined
-            : terminalApprovalFingerprint(adapter.agent, terminalControl, inspection, {
-                screen: captured.screen,
-                runtime: options.runtime
-            });
-        const useLegacyFingerprint = Boolean(options.expectedFingerprint &&
-            options.expectedFingerprint === legacyFingerprint);
-        const fingerprintControl = useLegacyFingerprint
-            ? terminalControl
-            : activeTerminalControl;
-        const fingerprint = useLegacyFingerprint
-            ? legacyFingerprint
-            : canonicalFingerprint;
-        if (adapter.agent === "claude" &&
-            decisionMode === "keys" &&
-            !options.expectedFingerprint) {
-            return {
-                approved: false,
-                blocked: true,
-                reason: "screen approval requires the latest expected fingerprint",
-                key: inspection.approval.action.keys.length === 1
-                    ? inspection.approval.action.keys[0]
-                    : undefined,
-                keys: inspection.approval.action.keys,
-                label: inspection.approval.action.label,
-                promptKind: inspection.approval.promptKind,
-                command: inspection.approval.command,
-                cwd: inspection.approval.cwd,
-                toolName: inspection.approval.toolName,
-                requestDetail: inspection.approval.requestDetail,
-                fingerprint,
-                screenExcerpt: inspection.screenExcerpt,
-                decisionMode,
-                requestId: inspection.approval.action.requestId
-            };
-        }
-        if (options.expectedFingerprint && options.expectedFingerprint !== fingerprint) {
-            return {
-                approved: false,
-                blocked: true,
-                reason: "approval fingerprint changed before execution",
-                key: inspection.approval.action.keys.length === 1
-                    ? inspection.approval.action.keys[0]
-                    : undefined,
-                keys: inspection.approval.action.keys,
-                label: inspection.approval.action.label,
-                promptKind: inspection.approval.promptKind,
-                command: inspection.approval.command,
-                fingerprint,
-                screenExcerpt: inspection.screenExcerpt,
-                decisionMode,
-                requestId: inspection.approval.action.requestId
-            };
-        }
+        if (!preflight.ready)
+            return preflight.result;
+        const { action, decisionMode, fingerprintControl, fingerprint } = preflight;
         if (options.authorize) {
             const authorization = await options.authorize({
                 agent: adapter.agent,
                 terminalControl: activeTerminalControl,
                 inspection,
                 fingerprint,
+                decision,
                 runtime: options.runtime
             });
             if (!authorization.approved) {
@@ -1937,11 +2003,12 @@ export class TerminalAgentBridge {
                     approved: false,
                     blocked: true,
                     reason: authorization.reason ?? "approval was not authorized",
-                    key: inspection.approval.action.keys.length === 1
-                        ? inspection.approval.action.keys[0]
+                    decision,
+                    key: action.keys.length === 1
+                        ? action.keys[0]
                         : undefined,
-                    keys: inspection.approval.action.keys,
-                    label: inspection.approval.action.label,
+                    keys: action.keys,
+                    label: action.label,
                     promptKind: inspection.approval.promptKind,
                     command: inspection.approval.command,
                     toolName: inspection.approval.toolName,
@@ -1949,7 +2016,7 @@ export class TerminalAgentBridge {
                     fingerprint,
                     screenExcerpt: inspection.screenExcerpt,
                     decisionMode,
-                    requestId: inspection.approval.action.requestId
+                    requestId: action.requestId
                 };
             }
         }
@@ -1968,21 +2035,34 @@ export class TerminalAgentBridge {
                 screenExcerpt: recapturedInspection.screenExcerpt
             };
         }
-        const recapturedDecisionMode = recapturedInspection.approval.action.mode ?? "keys";
+        const recapturedAction = terminalApprovalActionForDecision(recapturedInspection.approval, decision);
+        if (!recapturedAction) {
+            return {
+                approved: false,
+                blocked: true,
+                decision,
+                reason: `the ${decision} decision is no longer available after authorization`,
+                promptKind: recapturedInspection.approval.promptKind,
+                screenExcerpt: recapturedInspection.screenExcerpt
+            };
+        }
+        const recapturedDecisionMode = recapturedAction.mode ?? "keys";
         const recapturedFingerprint = terminalApprovalFingerprint(adapter.agent, fingerprintControl, recapturedInspection, {
             screen: recaptured.screen,
-            runtime: options.runtime
+            runtime: options.runtime,
+            decision
         });
         if (recapturedDecisionMode !== decisionMode) {
             return {
                 approved: false,
                 blocked: true,
                 reason: "approval decision mode changed after authorization",
-                key: recapturedInspection.approval.action.keys.length === 1
-                    ? recapturedInspection.approval.action.keys[0]
+                decision,
+                key: recapturedAction.keys.length === 1
+                    ? recapturedAction.keys[0]
                     : undefined,
-                keys: recapturedInspection.approval.action.keys,
-                label: recapturedInspection.approval.action.label,
+                keys: recapturedAction.keys,
+                label: recapturedAction.label,
                 promptKind: recapturedInspection.approval.promptKind,
                 command: recapturedInspection.approval.command,
                 cwd: recapturedInspection.approval.cwd,
@@ -1991,7 +2071,7 @@ export class TerminalAgentBridge {
                 fingerprint: recapturedFingerprint,
                 screenExcerpt: recapturedInspection.screenExcerpt,
                 decisionMode: recapturedDecisionMode,
-                requestId: recapturedInspection.approval.action.requestId
+                requestId: recapturedAction.requestId
             };
         }
         if (recapturedFingerprint !== fingerprint) {
@@ -1999,11 +2079,12 @@ export class TerminalAgentBridge {
                 approved: false,
                 blocked: true,
                 reason: "approval fingerprint changed after authorization",
-                key: recapturedInspection.approval.action.keys.length === 1
-                    ? recapturedInspection.approval.action.keys[0]
+                decision,
+                key: recapturedAction.keys.length === 1
+                    ? recapturedAction.keys[0]
                     : undefined,
-                keys: recapturedInspection.approval.action.keys,
-                label: recapturedInspection.approval.action.label,
+                keys: recapturedAction.keys,
+                label: recapturedAction.label,
                 promptKind: recapturedInspection.approval.promptKind,
                 command: recapturedInspection.approval.command,
                 cwd: recapturedInspection.approval.cwd,
@@ -2012,7 +2093,7 @@ export class TerminalAgentBridge {
                 fingerprint: recapturedFingerprint,
                 screenExcerpt: recapturedInspection.screenExcerpt,
                 decisionMode: recapturedDecisionMode,
-                requestId: recapturedInspection.approval.action.requestId
+                requestId: recapturedAction.requestId
             };
         }
         const verifiedForApproval = await this.verifyTerminalIdentity(adapter.agent, recaptured.terminalControl, options.runtime);
@@ -2030,11 +2111,13 @@ export class TerminalAgentBridge {
             terminalControl: verifiedForApproval,
             inspection: recapturedInspection,
             fingerprint: recapturedFingerprint,
-            keys: recapturedInspection.approval.action.keys,
+            decision,
+            keys: recapturedAction.keys,
             runtime: options.runtime
         });
         let dispatchTerminalControl = verifiedForApproval;
         let dispatchInspection = recapturedInspection;
+        let dispatchAction = recapturedAction;
         if (options.beforeKeyDispatch) {
             const afterReservation = await this.captureInspection(adapter, verifiedForApproval, options);
             const afterReservationInspection = afterReservation.inspection;
@@ -2051,22 +2134,35 @@ export class TerminalAgentBridge {
                     screenExcerpt: afterReservationInspection.screenExcerpt
                 };
             }
-            const afterReservationMode = afterReservationInspection.approval.action.mode ?? "keys";
+            const afterReservationAction = terminalApprovalActionForDecision(afterReservationInspection.approval, decision);
+            if (!afterReservationAction) {
+                return {
+                    approved: false,
+                    blocked: true,
+                    decision,
+                    reason: `the ${decision} decision is no longer available after dispatch reservation`,
+                    promptKind: afterReservationInspection.approval.promptKind,
+                    screenExcerpt: afterReservationInspection.screenExcerpt
+                };
+            }
+            const afterReservationMode = afterReservationAction.mode ?? "keys";
             const afterReservationFingerprint = terminalApprovalFingerprint(adapter.agent, fingerprintControl, afterReservationInspection, {
                 screen: afterReservation.screen,
-                runtime: options.runtime
+                runtime: options.runtime,
+                decision
             });
             if (afterReservationMode !== "keys" ||
                 afterReservationFingerprint !== recapturedFingerprint) {
                 return {
                     approved: false,
                     blocked: true,
+                    decision,
                     reason: "approval fingerprint changed after dispatch reservation",
-                    key: afterReservationInspection.approval.action.keys.length === 1
-                        ? afterReservationInspection.approval.action.keys[0]
+                    key: afterReservationAction.keys.length === 1
+                        ? afterReservationAction.keys[0]
                         : undefined,
-                    keys: afterReservationInspection.approval.action.keys,
-                    label: afterReservationInspection.approval.action.label,
+                    keys: afterReservationAction.keys,
+                    label: afterReservationAction.label,
                     promptKind: afterReservationInspection.approval.promptKind,
                     command: afterReservationInspection.approval.command,
                     cwd: afterReservationInspection.approval.cwd,
@@ -2075,11 +2171,12 @@ export class TerminalAgentBridge {
                     fingerprint: afterReservationFingerprint,
                     screenExcerpt: afterReservationInspection.screenExcerpt,
                     decisionMode: afterReservationMode,
-                    requestId: afterReservationInspection.approval.action.requestId
+                    requestId: afterReservationAction.requestId
                 };
             }
             dispatchTerminalControl = afterReservation.terminalControl;
             dispatchInspection = afterReservationInspection;
+            dispatchAction = afterReservationAction;
         }
         if (!dispatchInspection.approval.approvable) {
             return {
@@ -2094,22 +2191,108 @@ export class TerminalAgentBridge {
         if (!sameTerminalControlIdentity(dispatchTerminalControl, verifiedImmediatelyBeforeSend)) {
             throw new Error("terminal control identity changed after the final approval capture");
         }
-        await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(verifiedImmediatelyBeforeSend), dispatchApproval.action.keys);
+        await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(verifiedImmediatelyBeforeSend), dispatchAction.keys);
         return {
-            approved: true,
+            approved: decision === "approve_once",
+            decisionDispatched: true,
+            decision,
             blocked: false,
-            key: dispatchApproval.action.keys.length === 1
-                ? dispatchApproval.action.keys[0]
+            key: dispatchAction.keys.length === 1
+                ? dispatchAction.keys[0]
                 : undefined,
-            keys: dispatchApproval.action.keys,
-            label: dispatchApproval.action.label,
+            keys: dispatchAction.keys,
+            label: dispatchAction.label,
             promptKind: dispatchApproval.promptKind,
             command: dispatchApproval.command,
             cwd: dispatchApproval.cwd,
             fingerprint: recapturedFingerprint,
             screenExcerpt: dispatchInspection.screenExcerpt,
             decisionMode: recapturedDecisionMode,
-            requestId: dispatchApproval.action.requestId
+            requestId: dispatchAction.requestId
+        };
+    }
+    async respondInteraction(agent, terminalControl, response, options) {
+        const runtime = {
+            ...options.runtime,
+            agentVersion: options.agentVersion
+        };
+        const optionReason = terminalInteractionOptionPreflightReason(options, runtime);
+        if (optionReason) {
+            return blockedTerminalInteractionResponse(response, optionReason);
+        }
+        const first = await this.captureTerminalInteractionOffer(agent, terminalControl, runtime, options.scrollbackLines).catch((error) => error);
+        if (first instanceof Error) {
+            return blockedTerminalInteractionResponse(response, first.message);
+        }
+        const firstReason = terminalInteractionOfferPreflightReason(first.offer, options);
+        if (firstReason || !first.offer) {
+            return blockedTerminalInteractionResponse(response, firstReason ?? "native questionnaire has no safe interaction offer", first.offer);
+        }
+        const validatedResponse = validateTerminalInteractionResponse(response, first.offer.projection, { now: this.now() });
+        const planReason = terminalInteractionPlanPreflightReason(validatedResponse, first.offer.actionPlan);
+        if (planReason) {
+            return blockedTerminalInteractionResponse(validatedResponse, planReason, first.offer);
+        }
+        const capabilityReason = terminalInteractionCapabilityReason(this.terminalProvider, first.terminalControl, first.offer.actionPlan);
+        if (capabilityReason) {
+            return blockedTerminalInteractionResponse(validatedResponse, capabilityReason, first.offer);
+        }
+        const authorization = await authorizeTerminalInteraction(options.authorize, interactionHookContext(agent, first.terminalControl, first.offer, validatedResponse, runtime));
+        if (!authorization.approved) {
+            return blockedTerminalInteractionResponse(validatedResponse, authorization.reason ?? "terminal interaction response was not authorized", first.offer);
+        }
+        const afterAuthorization = await this.captureTerminalInteractionOffer(agent, first.terminalControl, runtime, options.scrollbackLines).catch((error) => error);
+        if (afterAuthorization instanceof Error) {
+            return blockedTerminalInteractionResponse(validatedResponse, afterAuthorization.message, first.offer);
+        }
+        if (!sameTerminalInteractionOffer(first, afterAuthorization)) {
+            return blockedTerminalInteractionResponse(validatedResponse, "native questionnaire changed after authorization", first.offer);
+        }
+        await reserveTerminalInteractionDispatch(options.beforeDispatch, interactionHookContext(agent, afterAuthorization.terminalControl, afterAuthorization.offer, validatedResponse, runtime));
+        const finalCapture = await this.captureTerminalInteractionOffer(agent, afterAuthorization.terminalControl, runtime, options.scrollbackLines).catch((error) => {
+            if (options.beforeDispatch) {
+                throw terminalInteractionReservedError("reservation_uncertain", error, "cannot recapture native questionnaire after dispatch reservation");
+            }
+            return error;
+        });
+        if (finalCapture instanceof Error) {
+            return blockedTerminalInteractionResponse(validatedResponse, finalCapture.message, first.offer);
+        }
+        if (!sameTerminalInteractionOffer(afterAuthorization, finalCapture)) {
+            if (options.beforeDispatch) {
+                throw new TerminalInteractionDispatchReservedError("reservation_uncertain", "native questionnaire changed after dispatch reservation");
+            }
+            return blockedTerminalInteractionResponse(validatedResponse, "native questionnaire changed before dispatch", first.offer);
+        }
+        const verified = await this.verifyTerminalIdentity(agent, finalCapture.terminalControl, runtime).catch((error) => {
+            throw terminalInteractionReservedError(options.beforeDispatch ? "reservation_uncertain" : "key_uncertain", error, "terminal identity could not be verified immediately before interaction dispatch");
+        });
+        if (!sameTerminalControlIdentity(finalCapture.terminalControl, verified)) {
+            throw new TerminalInteractionDispatchReservedError(options.beforeDispatch ? "reservation_uncertain" : "key_uncertain", "terminal identity changed after the final questionnaire capture");
+        }
+        const answer = validatedResponse.answers[0];
+        const outcome = await dispatchTerminalInteractionAnswer({
+            agent,
+            provider: this.terminalProvider,
+            terminalControl: verified,
+            actionPlan: finalCapture.offer.actionPlan,
+            answer,
+            sleep: this.sleep,
+            reverifyTerminalIdentity: async (currentControl) => {
+                const reverified = await this.verifyTerminalIdentity(agent, currentControl, runtime);
+                if (!sameTerminalControlIdentity(currentControl, reverified)) {
+                    throw new Error("terminal identity changed between interaction text and Enter");
+                }
+                return reverified;
+            }
+        });
+        return {
+            responded: true,
+            blocked: false,
+            interactionId: validatedResponse.interaction_id,
+            questionId: answer.question_id,
+            responseKind: answer.response_kind,
+            outcome
         };
     }
     async monitorPoll(options) {
@@ -2126,7 +2309,8 @@ export class TerminalAgentBridge {
                 inspection = captured.inspection;
                 status = statusFromInspection(adapter, captured.terminalControl, inspection, {
                     screen: captured.screen,
-                    runtime: options.screenOptions?.runtime
+                    runtime: options.screenOptions?.runtime,
+                    now: this.now()
                 });
             }
             catch (error) {
@@ -2181,6 +2365,25 @@ export class TerminalAgentBridge {
             })
         };
     }
+    async captureTerminalInteractionOffer(agent, terminalControl, runtime, scrollbackLines) {
+        const adapter = this.registry.require(agent);
+        const captured = await this.captureInspection(adapter, terminalControl, {
+            scrollbackLines,
+            runtime
+        });
+        return {
+            terminalControl: captured.terminalControl,
+            inspection: captured.inspection,
+            offer: terminalInteractionBridgeOffer({
+                agent,
+                terminalControl: captured.terminalControl,
+                inspection: captured.inspection,
+                screen: captured.screen,
+                runtime,
+                now: this.now()
+            })
+        };
+    }
     async verifyTerminalIdentity(agent, terminalControl, runtime) {
         let verifiedControl = terminalControl;
         if (this.verifyIdentity) {
@@ -2914,7 +3117,13 @@ export function terminalApprovalFingerprint(agent, terminalControl, inspection,
     if (!inspection.approval.approvable) {
         return undefined;
     }
-    const decisionMode = inspection.approval.action.mode ?? "keys";
+    const decision = options.decision ?? "approve_once";
+    const choices = terminalApprovalChoices(inspection.approval);
+    const action = terminalApprovalActionForDecision(inspection.approval, decision);
+    if (!action) {
+        return undefined;
+    }
+    const decisionMode = action.mode ?? "keys";
     const promptEvidence = inspection.approval.promptEvidence;
     if (decisionMode === "keys" &&
         !isTerminalApprovalPromptEvidence(promptEvidence)) {
@@ -2968,8 +3177,16 @@ export function terminalApprovalFingerprint(agent, terminalControl, inspection,
             message_id: options.runtime?.messageId,
             terminal_target: options.runtime?.terminalTarget
         },
-        keys: inspection.approval.action.keys,
-        label: inspection.approval.action.label,
+        decision,
+        keys: action.keys,
+        label: action.label,
+        available_choices: choices.map((choice) => ({
+            decision: choice.decision,
+            keys: choice.keys,
+            label: choice.label,
+            mode: choice.mode ?? "keys",
+            request_id: choice.requestId
+        })),
         prompt_kind: inspection.approval.promptKind,
         command: inspection.approval.command,
         cwd: inspection.approval.cwd,
@@ -2992,7 +3209,7 @@ export function terminalApprovalFingerprint(agent, terminalControl, inspection,
             }
             : undefined,
         decision_mode: decisionMode,
-        request_id: inspection.approval.action.requestId
+        request_id: action.requestId
     }))
         .digest("hex");
 }
@@ -3006,12 +3223,396 @@ function isTerminalApprovalPromptEvidence(value) {
         typeof evidence.sha256 === "string" &&
         /^[0-9a-f]{64}$/u.test(evidence.sha256);
 }
+function terminalInteractionTurnId(runtime) {
+    // Questionnaire mutation is managed-Turn-only. A raw terminal's
+    // conversationId is a discovery label, not durable response authority.
+    const candidate = runtime?.turnId;
+    return typeof candidate === "string" &&
+        TERMINAL_INTERACTION_IDENTIFIER_PATTERN.test(candidate)
+        ? candidate
+        : undefined;
+}
+function terminalInteractionExpiry(now) {
+    const nowMs = now.getTime();
+    if (!Number.isFinite(nowMs)) {
+        return undefined;
+    }
+    const windowStart = Math.floor(nowMs / TERMINAL_INTERACTION_TTL_MS) *
+        TERMINAL_INTERACTION_TTL_MS;
+    return new Date(windowStart + TERMINAL_INTERACTION_TTL_MS).toISOString();
+}
+function terminalInteractionQuestion(question) {
+    const common = {
+        question_id: question.question_id,
+        prompt: question.prompt,
+        required: question.required
+    };
+    if (question.response_kind === "single_select" ||
+        question.response_kind === "multi_select") {
+        return {
+            ...common,
+            response_kind: question.response_kind,
+            options: question.options ?? []
+        };
+    }
+    return {
+        ...common,
+        response_kind: question.response_kind
+    };
+}
+function terminalInteractionCanonicalIdentity(terminalControl, runtime) {
+    if (!hasCanonicalTerminalEndpoint(terminalControl)) {
+        return undefined;
+    }
+    const terminal = terminalEndpointFromControlRef(terminalControl);
+    if (!Number.isInteger(terminal.processAnchorPid) ||
+        Number(terminal.processAnchorPid) <= 0) {
+        return undefined;
+    }
+    return {
+        terminal_identity: terminalEndpointIdentityKey(terminal),
+        terminal_process_anchor_pid: terminal.processAnchorPid,
+        agent_pid: runtime.pid,
+        native_session_id: runtime.nativeSessionId,
+        native_process_uuid: runtime.nativeProcessUuid,
+        native_process_birth: runtime.nativeProcessBirth,
+        native_process_started_at: runtime.nativeProcessStartedAt,
+        native_rollout: runtime.nativeRollout
+    };
+}
+function terminalInteractionBridgeOffer(input) {
+    const turnId = terminalInteractionTurnId(input.runtime);
+    const agentVersion = input.runtime?.agentVersion;
+    const expiry = terminalInteractionExpiry(input.now);
+    const canonicalIdentity = input.runtime
+        ? terminalInteractionCanonicalIdentity(input.terminalControl, input.runtime)
+        : undefined;
+    if (!turnId ||
+        typeof agentVersion !== "string" ||
+        agentVersion.length === 0 ||
+        !expiry ||
+        !canonicalIdentity ||
+        input.inspection.approval.blocked) {
+        return undefined;
+    }
+    const nativeInspection = inspectNativeQuestionnaire({
+        agent: input.agent,
+        version: agentVersion,
+        screen: input.screen
+    });
+    if (nativeInspection.status === "none") {
+        return undefined;
+    }
+    const authorityMaterial = JSON.stringify({
+        version: 1,
+        agent: input.agent,
+        turn_id: turnId,
+        terminal: canonicalIdentity,
+        profile: nativeInspection.profile,
+        prompt_sha256: nativeInspection.prompt_evidence.sha256
+    });
+    const promptFingerprint = createHash("sha256")
+        .update(`terminal-interaction-authority\0${authorityMaterial}`, "utf8")
+        .digest("hex");
+    const interactionId = `ti_${createHash("sha256")
+        .update(`terminal-interaction-public\0${authorityMaterial}`, "utf8")
+        .digest("hex")
+        .slice(0, 40)}`;
+    const question = terminalInteractionQuestion(nativeInspection.question);
+    const executable = nativeInspection.status === "actionable" &&
+        nativeInspection.action_plan.kind !== "manual_only";
+    const responseUncertain = input.runtime?.interactionDispatchState === "reserved" ||
+        input.runtime?.interactionDispatchState === "uncertain";
+    const projection = validateTerminalInteractionProjection({
+        schema: TERMINAL_INTERACTION_SCHEMA,
+        version: TERMINAL_INTERACTION_VERSION,
+        interaction_id: interactionId,
+        turn_id: turnId,
+        agent: input.agent,
+        kind: "questionnaire",
+        state: responseUncertain
+            ? "response_uncertain"
+            : executable
+                ? "pending"
+                : "manual_required",
+        step: {
+            index: nativeInspection.current_step,
+            total: nativeInspection.total_steps
+        },
+        questions: [question],
+        expires_at: expiry,
+        capabilities: {
+            respond: executable && !responseUncertain,
+            batch_response: false,
+            free_text: question.response_kind === "free_text",
+            multi_select: question.response_kind === "multi_select"
+        }
+    });
+    return {
+        projection,
+        promptFingerprint,
+        actionPlan: nativeInspection.action_plan,
+        nativeInspection
+    };
+}
+function terminalInteractionOptionPreflightReason(options, runtime) {
+    if (typeof options.agentVersion !== "string" ||
+        !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/u.test(options.agentVersion)) {
+        return "an exact semantic agent version is required";
+    }
+    if (options.runtime?.agentVersion !== undefined &&
+        options.runtime.agentVersion !== options.agentVersion) {
+        return "runtime agent version does not match the requested interaction profile";
+    }
+    if (!terminalInteractionTurnId(runtime)) {
+        return "a protocol-safe exact Turn id is required";
+    }
+    if (!TERMINAL_INTERACTION_FINGERPRINT_PATTERN.test(options.expectedFingerprint)) {
+        return "a valid interaction prompt fingerprint is required";
+    }
+    if (!Number.isFinite(Date.parse(options.expectedExpiresAt))) {
+        return "a valid interaction expiry is required";
+    }
+    return undefined;
+}
+function terminalInteractionOfferPreflightReason(offer, options) {
+    if (!offer) {
+        return "native questionnaire has no identity-fenced interaction offer";
+    }
+    if (offer.projection.state !== "pending" ||
+        !offer.projection.capabilities.respond ||
+        offer.actionPlan.kind === "manual_only") {
+        return `native questionnaire requires manual response: ${offer.nativeInspection.status === "manual_required"
+            ? offer.nativeInspection.reason
+            : "unsupported action plan"}`;
+    }
+    if (offer.promptFingerprint !== options.expectedFingerprint) {
+        return "native questionnaire fingerprint changed before execution";
+    }
+    if (offer.projection.expires_at !== options.expectedExpiresAt) {
+        return "native questionnaire expiry changed before execution";
+    }
+    return undefined;
+}
+function terminalInteractionCapabilityReason(provider, terminalControl, plan) {
+    const requiresText = plan.kind === "free_text";
+    const missing = [
+        !terminalControl.capabilities.includes("screen_status")
+            ? "terminal:screen_status"
+            : undefined,
+        !terminalControl.capabilities.includes("send_keys")
+            ? "terminal:send_keys"
+            : undefined,
+        !provider.providerCapabilities.includes("stable_resource_resolution")
+            ? "provider:stable_resource_resolution"
+            : undefined,
+        !provider.providerCapabilities.includes("screen_capture")
+            ? "provider:screen_capture"
+            : undefined,
+        !provider.providerCapabilities.includes("key_delivery")
+            ? "provider:key_delivery"
+            : undefined,
+        requiresText && !provider.providerCapabilities.includes("text_delivery")
+            ? "provider:text_delivery"
+            : undefined
+    ].filter((value) => value !== undefined);
+    return missing.length > 0
+        ? `terminal interaction capability preflight failed: ${missing.join(", ")}`
+        : undefined;
+}
+function terminalInteractionPlanPreflightReason(response, plan) {
+    const answer = response.answers[0];
+    if (plan.kind !== "free_text" || answer?.response_kind !== "free_text") {
+        return undefined;
+    }
+    const textStage = plan.stages[0];
+    if (textStage?.kind !== "answer_text" ||
+        !Number.isSafeInteger(textStage.max_characters) ||
+        textStage.max_characters < 1) {
+        return "native free-text interaction has no verified input limit";
+    }
+    return answer.text.length <= textStage.max_characters
+        ? undefined
+        : `free-text answer exceeds the verified native limit of ${textStage.max_characters} characters`;
+}
+function blockedTerminalInteractionResponse(response, reason, offer) {
+    const answer = Array.isArray(response.answers) ? response.answers[0] : undefined;
+    return {
+        responded: false,
+        blocked: true,
+        reason,
+        interactionId: response.interaction_id,
+        questionId: answer?.question_id ?? offer?.projection.questions[0]?.question_id,
+        responseKind: answer?.response_kind
+    };
+}
+function interactionHookContext(agent, terminalControl, offer, response, runtime) {
+    return {
+        agent,
+        terminalControl,
+        fingerprint: offer.promptFingerprint,
+        projection: offer.projection,
+        response,
+        runtime
+    };
+}
+async function authorizeTerminalInteraction(authorize, context) {
+    return authorize ? authorize(context) : { approved: true };
+}
+async function reserveTerminalInteractionDispatch(beforeDispatch, context) {
+    if (!beforeDispatch) {
+        return;
+    }
+    try {
+        await beforeDispatch(context);
+    }
+    catch (error) {
+        throw terminalInteractionReservedError("reservation_uncertain", error, "terminal interaction dispatch reservation failed");
+    }
+}
+function sameTerminalInteractionOffer(left, right) {
+    return Boolean(left.offer &&
+        right.offer &&
+        sameTerminalControlIdentity(left.terminalControl, right.terminalControl) &&
+        left.offer.promptFingerprint === right.offer.promptFingerprint &&
+        JSON.stringify(left.offer.projection) === JSON.stringify(right.offer.projection) &&
+        JSON.stringify(left.offer.actionPlan) === JSON.stringify(right.offer.actionPlan));
+}
+function terminalInteractionReservedError(stage, error, message) {
+    if (error instanceof TerminalInteractionDispatchReservedError) {
+        return error;
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    return new TerminalInteractionDispatchReservedError(stage, `${message}: ${detail}`, { cause: error });
+}
+function terminalInteractionChoiceAction(plan, answer) {
+    const choice = plan.choices.find((candidate) => candidate.option_id === answer.selected_option_ids[0]);
+    const stage = choice?.stages[0];
+    if (!choice ||
+        choice.stages.length !== 1 ||
+        stage?.kind !== "key" ||
+        !/^[1-5]$/u.test(stage.key)) {
+        throw new Error("single-select interaction has no closed adapter action");
+    }
+    return {
+        key: stage.key,
+        outcome: choice.outcome === "open_custom_text"
+            ? "custom_text_opened"
+            : "submitted_or_advanced"
+    };
+}
+function terminalInteractionConfirmKey(plan, answer) {
+    const stages = answer.confirm ? plan.confirm_stages : plan.cancel_stages;
+    const stage = stages[0];
+    if (stages.length !== 1 ||
+        stage?.kind !== "key" ||
+        !["C-m", "Escape", "1", "2"].includes(stage.key) ||
+        JSON.stringify(plan.confirm_stages) === JSON.stringify(plan.cancel_stages)) {
+        throw new Error("confirmation interaction has no closed adapter action");
+    }
+    return stage.key;
+}
+async function sendTerminalInteractionKeys(provider, terminalControl, keys) {
+    try {
+        await provider.sendKeys(provider.endpoint(terminalControl), keys);
+    }
+    catch (error) {
+        throw terminalInteractionReservedError("key_uncertain", error, "terminal interaction key dispatch is uncertain");
+    }
+}
+async function dispatchTerminalInteractionFreeText(input) {
+    const [textStage, enterStage] = input.plan.stages;
+    if (input.plan.stages.length !== 2 ||
+        textStage?.kind !== "answer_text" ||
+        textStage.single_line !== true ||
+        textStage.max_characters < input.answer.text.length ||
+        enterStage?.kind !== "key" ||
+        enterStage.key !== "C-m") {
+        throw new TerminalInteractionDispatchReservedError("reservation_uncertain", "free-text interaction has no closed adapter action");
+    }
+    try {
+        await input.provider.sendText(input.provider.endpoint(input.terminalControl), input.answer.text);
+    }
+    catch (error) {
+        throw terminalInteractionReservedError("text_uncertain", error, "terminal interaction text dispatch is uncertain");
+    }
+    if (input.agent === "codex") {
+        try {
+            await input.sleep(CODEX_PASTE_ENTER_SETTLE_MS);
+        }
+        catch (error) {
+            throw terminalInteractionReservedError("text_uncertain", error, "terminal interaction paste-settle outcome is uncertain");
+        }
+    }
+    let enterControl;
+    try {
+        enterControl = await input.reverifyTerminalIdentity(input.terminalControl);
+        if (!sameTerminalControlIdentity(input.terminalControl, enterControl)) {
+            throw new Error("terminal identity changed between interaction text and Enter");
+        }
+    }
+    catch (error) {
+        throw terminalInteractionReservedError("text_uncertain", error, "terminal identity after interaction text dispatch is uncertain");
+    }
+    await sendTerminalInteractionKeys(input.provider, enterControl, [enterStage.key]);
+    return "submitted_or_advanced";
+}
+async function dispatchTerminalInteractionAnswer(input) {
+    if (input.actionPlan.kind === "single_select" &&
+        input.answer.response_kind === "single_select") {
+        const action = terminalInteractionChoiceAction(input.actionPlan, input.answer);
+        await sendTerminalInteractionKeys(input.provider, input.terminalControl, [action.key]);
+        return action.outcome;
+    }
+    if (input.actionPlan.kind === "confirm" &&
+        input.answer.response_kind === "confirm") {
+        const key = terminalInteractionConfirmKey(input.actionPlan, input.answer);
+        await sendTerminalInteractionKeys(input.provider, input.terminalControl, [key]);
+        return input.answer.confirm ? "confirmed" : "cancelled";
+    }
+    if (input.actionPlan.kind === "free_text" &&
+        input.answer.response_kind === "free_text") {
+        return dispatchTerminalInteractionFreeText({
+            agent: input.agent,
+            provider: input.provider,
+            terminalControl: input.terminalControl,
+            plan: input.actionPlan,
+            answer: input.answer,
+            reverifyTerminalIdentity: input.reverifyTerminalIdentity,
+            sleep: input.sleep
+        });
+    }
+    throw new TerminalInteractionDispatchReservedError("reservation_uncertain", "terminal interaction answer does not have a closed adapter action");
+}
 function statusFromInspection(adapter, terminalControl, inspection, options = {}) {
     const approval = dispatchableApprovalInspection(adapter, inspection.approval);
     const fingerprint = terminalApprovalFingerprint(adapter.agent, terminalControl, {
         ...inspection,
         approval
     }, options);
+    const choices = approval.approvable
+        ? terminalApprovalChoices(approval).flatMap((choice) => {
+            if (!choice.decision) {
+                return [];
+            }
+            const choiceFingerprint = terminalApprovalFingerprint(adapter.agent, terminalControl, { ...inspection, approval }, { ...options, decision: choice.decision });
+            return choiceFingerprint ? [{
+                    decision: choice.decision,
+                    label: choice.label,
+                    fingerprint: choiceFingerprint
+                }] : [];
+        })
+        : [];
+    const interaction = options.screen === undefined
+        ? undefined
+        : terminalInteractionBridgeOffer({
+            agent: adapter.agent,
+            terminalControl,
+            inspection: { ...inspection, approval },
+            screen: options.screen,
+            runtime: options.runtime,
+            now: options.now ?? new Date()
+        });
     return {
         provider: terminalControl.kind,
         target: terminalControl.target,
@@ -3036,6 +3637,7 @@ function statusFromInspection(adapter, terminalControl, inspection, options = {}
             request_detail: approval.requestDetail,
             reason: approval.approvable ? undefined : approval.reason,
             fingerprint,
+            choices: choices.length > 0 ? choices : undefined,
             decision_mode: approval.approvable ? approval.action.mode ?? "keys" : undefined,
             request_id: approval.approvable ? approval.action.requestId : undefined,
             policy_evidence: approval.approvable && approval.policyEvidence
@@ -3054,7 +3656,11 @@ function statusFromInspection(adapter, terminalControl, inspection, options = {}
                 ? undefined
                 : createHash("sha256").update(options.screen).digest("hex"),
             approval: approvalOutput(approval)
-        }
+        },
+        ...(interaction === undefined ? {} : {
+            interaction_state: interaction.projection,
+            interaction_prompt_fingerprint: interaction.promptFingerprint
+        })
     };
 }
 function dispatchableApprovalInspection(adapter, approval) {
@@ -3117,6 +3723,10 @@ function approvalOutput(approval) {
         cwd: approval.cwd,
         toolName: approval.toolName,
         requestDetail: approval.requestDetail,
+        choices: terminalApprovalChoices(approval).map((choice) => ({
+            decision: choice.decision,
+            label: choice.label
+        })),
         policyEvidence: approval.policyEvidence
             ? {
                 source: approval.policyEvidence.source,