@scotthuang/agent-knock-knock 0.2.46 → 0.2.48

package/dist/src/terminal-agent-bridge.d.ts

@@ -1,5 +1,5 @@
 import type { ExecutorKind } from "./executors.js";
-import { type ActiveTerminalProcess, type TerminalAgentAdapter, type TerminalAgentAdapterCapabilities, type TerminalAgentAdapterRegistry, type TerminalCompletionEvidence, type TerminalControlRef, type TerminalDurableCompletionRequest, type TerminalProcessSnapshot, type TerminalScreenInspection } from "./terminal-agent-adapter.js";
+import { type ActiveTerminalProcess, type TerminalAgentAdapter, type TerminalAgentAdapterCapabilities, type TerminalAgentAdapterRegistry, type TerminalCompletionEvidence, type TerminalControlRef, type TerminalDurableCompletionRequest, type TerminalProcessSnapshot, type TerminalRuntimeIdentity, type TerminalScreenInspection } from "./terminal-agent-adapter.js";
 import { type TerminalControlProvider } from "./terminal-control-provider.js";
 export interface TerminalBridgeStatus {
     provider: "tmux";
@@ -18,8 +18,13 @@ export interface TerminalBridgeStatus {
         label?: string;
         prompt_kind?: string;
         command?: string;
+        cwd?: string;
+        tool_name?: string;
+        request_detail?: string;
         reason?: string;
         fingerprint?: string;
+        decision_mode?: "keys" | "structured";
+        request_id?: string;
     };
     screen: {
         excerpt?: string;
@@ -45,8 +50,33 @@ export interface TerminalApprovalExecution {
     label?: string;
     promptKind?: string;
     command?: string;
+    cwd?: string;
+    toolName?: string;
+    requestDetail?: string;
     fingerprint?: string;
     screenExcerpt?: string;
+    decisionMode?: "keys" | "structured";
+    requestId?: string;
+}
+export interface TerminalIdentityVerificationRequest {
+    agent: ExecutorKind;
+    pid: number;
+    terminalControl: TerminalControlRef;
+}
+export interface TerminalIdentityVerificationResult {
+    terminalControl?: TerminalControlRef;
+}
+export type TerminalIdentityVerifier = (request: TerminalIdentityVerificationRequest) => Promise<TerminalIdentityVerificationResult | void>;
+export interface TerminalApprovalAuthorizationContext {
+    agent: ExecutorKind;
+    terminalControl: TerminalControlRef;
+    inspection: TerminalScreenInspection;
+    fingerprint?: string;
+    runtime?: TerminalRuntimeIdentity;
+}
+export interface TerminalApprovalAuthorizationDecision {
+    approved: boolean;
+    reason?: string;
 }
 export interface TerminalMonitorPoll {
     status: TerminalBridgeStatus;
@@ -57,29 +87,44 @@ export interface TerminalMonitorPoll {
 export declare class TerminalAgentBridge {
     readonly registry: TerminalAgentAdapterRegistry;
     readonly terminalProvider: TerminalControlProvider;
+    private readonly verifyIdentity?;
     constructor(options: {
         registry: TerminalAgentAdapterRegistry;
         terminalProvider: TerminalControlProvider;
+        verifyIdentity?: TerminalIdentityVerifier;
     });
     adapterFor(agent: ExecutorKind | string): TerminalAgentAdapter;
     listProcesses(snapshots: readonly TerminalProcessSnapshot[], agents?: readonly ExecutorKind[]): Promise<ActiveTerminalProcess[]>;
     discoverProcesses(snapshots: readonly TerminalProcessSnapshot[], agents?: readonly ExecutorKind[]): Promise<ActiveTerminalProcess[]>;
-    attachProcesses<T extends ActiveTerminalProcess>(agent: ExecutorKind, processes: T[]): Promise<T[]>;
+    attachProcesses<T extends ActiveTerminalProcess>(agent: ExecutorKind, processes: T[], options?: {
+        processTree?: readonly TerminalProcessSnapshot[];
+    }): Promise<T[]>;
     terminalConversationId(process: Pick<ActiveTerminalProcess, "agent" | "pid" | "terminalControl">): string;
     resolveConversationId(conversationId: string | undefined): Promise<ResolvedTerminalConversation | undefined>;
     status(agent: ExecutorKind, terminalControl: TerminalControlRef, options?: {
         scrollbackLines?: number;
+        runtime?: TerminalRuntimeIdentity;
     }): Promise<TerminalBridgeStatus>;
-    send(agent: ExecutorKind, terminalControl: TerminalControlRef, text: string): Promise<void>;
-    cancel(agent: ExecutorKind, terminalControl: TerminalControlRef): Promise<{
+    send(agent: ExecutorKind, terminalControl: TerminalControlRef, text: string, options?: {
+        runtime?: TerminalRuntimeIdentity;
+    }): Promise<void>;
+    cancel(agent: ExecutorKind, terminalControl: TerminalControlRef, options?: {
+        runtime?: TerminalRuntimeIdentity;
+        scrollbackLines?: number;
+    }): Promise<{
         cancelRequested: boolean;
         key?: string;
         keys?: readonly string[];
         reason?: string;
+        deniedApproval?: boolean;
+        requestId?: string;
     }>;
     approve(agent: ExecutorKind, terminalControl: TerminalControlRef, options?: {
         expectedFingerprint?: string;
         scrollbackLines?: number;
+        runtime?: TerminalRuntimeIdentity;
+        requiredDecisionMode?: "keys" | "structured";
+        authorize?: (context: TerminalApprovalAuthorizationContext) => TerminalApprovalAuthorizationDecision | Promise<TerminalApprovalAuthorizationDecision>;
     }): Promise<TerminalApprovalExecution>;
     monitorPoll(options: {
         agent: ExecutorKind;
@@ -89,9 +134,11 @@ export declare class TerminalAgentBridge {
             requestText?: string;
             screenChangedSinceSend?: boolean;
             maxExcerptLength?: number;
+            runtime?: TerminalRuntimeIdentity;
         };
         durableRequest?: TerminalDurableCompletionRequest;
     }): Promise<TerminalMonitorPoll>;
     private captureInspection;
+    private verifyTerminalIdentity;
 }
 export declare function terminalApprovalFingerprint(agent: ExecutorKind, terminalControl: Pick<TerminalControlRef, "target">, inspection: TerminalScreenInspection): string | undefined;

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

@@ -4,9 +4,11 @@ import { enrichActiveProcessesWithTerminalControl, terminalRefFromPane } from ".
 export class TerminalAgentBridge {
     registry;
     terminalProvider;
+    verifyIdentity;
     constructor(options) {
         this.registry = options.registry;
         this.terminalProvider = options.terminalProvider;
+        this.verifyIdentity = options.verifyIdentity;
     }
     adapterFor(agent) {
         return this.registry.require(agent);
@@ -24,17 +26,21 @@ export class TerminalAgentBridge {
                 .map((snapshot) => adapter.classifyProcess(snapshot))
                 .filter((process) => process !== undefined)
                 .map((process) => ({ ...process, agent: adapter.agent }));
-            discovered.push(...await this.attachProcesses(adapter.agent, classified));
+            discovered.push(...await enrichActiveProcessesWithTerminalControl(classified, this.terminalProvider, {
+                capabilities: terminalControlCapabilitiesForAdapter(adapter),
+                processTree: snapshots
+            }));
         }
         return discovered;
     }
     async discoverProcesses(snapshots, agents) {
         return this.listProcesses(snapshots, agents);
     }
-    async attachProcesses(agent, processes) {
+    async attachProcesses(agent, processes, options = {}) {
         const adapter = this.registry.require(agent);
         return enrichActiveProcessesWithTerminalControl(processes, this.terminalProvider, {
-            capabilities: terminalControlCapabilitiesForAdapter(adapter)
+            capabilities: terminalControlCapabilitiesForAdapter(adapter),
+            processTree: options.processTree
         });
     }
     terminalConversationId(process) {
@@ -55,27 +61,46 @@ export class TerminalAgentBridge {
         }
         const adapter = this.registry.require(parsed.agent);
         const panes = await this.terminalProvider.listPanes();
-        const pane = panes.find((candidate) => candidate.kind === parsed.kind && candidate.target === parsed.target);
-        if (!pane) {
+        const candidates = panes.filter((candidate) => candidate.kind === parsed.kind && candidate.target === parsed.target);
+        const verified = this.verifyIdentity
+            ? (await Promise.all(candidates.map(async (pane) => {
+                const terminalControl = terminalRefFromPane(pane, terminalControlCapabilitiesForAdapter(adapter));
+                try {
+                    const verifiedTerminalControl = await this.verifyTerminalIdentity(adapter.agent, terminalControl, { pid: parsed.pid });
+                    return { pane, terminalControl: verifiedTerminalControl };
+                }
+                catch {
+                    return undefined;
+                }
+            }))).filter((candidate) => candidate !== undefined)
+            : candidates.slice(0, 1).map((pane) => ({
+                pane,
+                terminalControl: terminalRefFromPane(pane, terminalControlCapabilitiesForAdapter(adapter))
+            }));
+        if (verified.length === 0) {
             throw new Error(`terminal-controlled session ${parsed.conversationId} is no longer available`);
         }
+        if (verified.length > 1) {
+            throw new Error(`terminal-controlled session ${parsed.conversationId} matches multiple active panes`);
+        }
         return {
             conversationId: parsed.conversationId,
             agent: parsed.agent,
             pid: parsed.pid,
             legacy: parsed.legacy,
             adapter,
-            terminalControl: terminalRefFromPane(pane, terminalControlCapabilitiesForAdapter(adapter))
+            terminalControl: verified[0].terminalControl
         };
     }
     async status(agent, terminalControl, options = {}) {
         const adapter = this.registry.require(agent);
-        if (!adapter.capabilities.screenStatus) {
+        if (!adapter.capabilities.screenStatus ||
+            !terminalControl.capabilities.includes("screen_status")) {
             return unsupportedScreenStatus(adapter, terminalControl);
         }
         try {
-            const { inspection } = await this.captureInspection(adapter, terminalControl, options);
-            return statusFromInspection(adapter, terminalControl, inspection);
+            const captured = await this.captureInspection(adapter, terminalControl, options);
+            return statusFromInspection(adapter, captured.terminalControl, captured.inspection);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -97,7 +122,7 @@ export class TerminalAgentBridge {
             };
         }
     }
-    async send(agent, terminalControl, text) {
+    async send(agent, terminalControl, text, options = {}) {
         const adapter = this.registry.require(agent);
         if (!terminalControl.capabilities.includes("send_keys")) {
             throw new Error(`${adapter.displayName} terminal input is not supported`);
@@ -106,23 +131,82 @@ export class TerminalAgentBridge {
         if (!normalized) {
             throw new Error("terminal message is empty");
         }
-        await this.terminalProvider.sendText(terminalControl.target, normalized, {
-            socketPath: terminalControl.socketPath
+        const verifiedForText = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
+        await this.terminalProvider.sendText(verifiedForText.target, normalized, {
+            socketPath: verifiedForText.socketPath
         });
-        await this.terminalProvider.sendKeys(terminalControl.target, ["C-m"], {
-            socketPath: terminalControl.socketPath
+        // Text and Enter are separate tmux operations. Revalidate between them; if the
+        // identity changed, clear the line best-effort and never submit it.
+        let verifiedForEnter;
+        try {
+            verifiedForEnter = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
+        }
+        catch (error) {
+            try {
+                await this.terminalProvider.sendKeys(verifiedForText.target, ["C-u"], {
+                    socketPath: verifiedForText.socketPath
+                });
+            }
+            catch {
+                // Best effort only: preserving the identity failure is more important than cleanup.
+            }
+            throw error;
+        }
+        await this.terminalProvider.sendKeys(verifiedForEnter.target, ["C-m"], {
+            socketPath: verifiedForEnter.socketPath
         });
     }
-    async cancel(agent, terminalControl) {
+    async cancel(agent, terminalControl, options = {}) {
         const adapter = this.registry.require(agent);
-        if (!adapter.capabilities.cancellation || adapter.cancelKeys.length === 0) {
+        if (adapter.capabilities.terminalApproval &&
+            adapter.resolveApproval &&
+            terminalControl.capabilities.includes("terminal_approval") &&
+            adapter.capabilities.screenStatus &&
+            terminalControl.capabilities.includes("screen_status")) {
+            const captured = await this.captureInspection(adapter, terminalControl, options);
+            const { inspection } = captured;
+            if (inspection.approval.approvable && inspection.approval.action.mode === "structured") {
+                const fingerprint = terminalApprovalFingerprint(adapter.agent, captured.terminalControl, inspection);
+                if (!fingerprint) {
+                    return {
+                        cancelRequested: false,
+                        reason: `${adapter.displayName} structured approval has no fingerprint`
+                    };
+                }
+                await this.verifyTerminalIdentity(adapter.agent, captured.terminalControl, options.runtime);
+                const decision = await adapter.resolveApproval({
+                    decision: "deny",
+                    expectedFingerprint: fingerprint,
+                    actualFingerprint: fingerprint,
+                    inspection,
+                    runtime: options.runtime,
+                    interrupt: true
+                });
+                return {
+                    cancelRequested: decision.resolved,
+                    deniedApproval: decision.resolved,
+                    requestId: decision.requestId,
+                    reason: decision.reason
+                };
+            }
+            if (inspection.approval.blocked && !inspection.approval.approvable) {
+                return {
+                    cancelRequested: false,
+                    reason: inspection.approval.reason
+                };
+            }
+        }
+        if (!adapter.capabilities.cancellation ||
+            adapter.cancelKeys.length === 0 ||
+            !terminalControl.capabilities.includes("terminal_cancel")) {
             return {
                 cancelRequested: false,
                 reason: `${adapter.displayName} terminal cancellation is not supported`
             };
         }
-        await this.terminalProvider.sendKeys(terminalControl.target, adapter.cancelKeys, {
-            socketPath: terminalControl.socketPath
+        const verifiedForCancel = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
+        await this.terminalProvider.sendKeys(verifiedForCancel.target, adapter.cancelKeys, {
+            socketPath: verifiedForCancel.socketPath
         });
         return {
             cancelRequested: true,
@@ -132,14 +216,17 @@ export class TerminalAgentBridge {
     }
     async approve(agent, terminalControl, options = {}) {
         const adapter = this.registry.require(agent);
-        if (!adapter.capabilities.terminalApproval) {
+        if (!adapter.capabilities.terminalApproval ||
+            !terminalControl.capabilities.includes("terminal_approval")) {
             return {
                 approved: false,
                 blocked: true,
                 reason: `${adapter.displayName} terminal approval is not supported`
             };
         }
-        const { inspection } = await this.captureInspection(adapter, terminalControl, options);
+        const captured = await this.captureInspection(adapter, terminalControl, options);
+        const { inspection } = captured;
+        const activeTerminalControl = captured.terminalControl;
         if (!inspection.approval.approvable) {
             return {
                 approved: false,
@@ -150,7 +237,22 @@ export class TerminalAgentBridge {
                 screenExcerpt: inspection.screenExcerpt
             };
         }
-        if (inspection.approval.action.keys.length === 0) {
+        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),
+                screenExcerpt: inspection.screenExcerpt,
+                decisionMode,
+                requestId: inspection.approval.action.requestId
+            };
+        }
+        if (decisionMode === "keys" && inspection.approval.action.keys.length === 0) {
             return {
                 approved: false,
                 blocked: true,
@@ -161,7 +263,7 @@ export class TerminalAgentBridge {
                 screenExcerpt: inspection.screenExcerpt
             };
         }
-        const fingerprint = terminalApprovalFingerprint(adapter.agent, terminalControl, inspection);
+        const fingerprint = terminalApprovalFingerprint(adapter.agent, activeTerminalControl, inspection);
         if (options.expectedFingerprint && options.expectedFingerprint !== fingerprint) {
             return {
                 approved: false,
@@ -175,33 +277,175 @@ export class TerminalAgentBridge {
                 promptKind: inspection.approval.promptKind,
                 command: inspection.approval.command,
                 fingerprint,
-                screenExcerpt: inspection.screenExcerpt
+                screenExcerpt: inspection.screenExcerpt,
+                decisionMode,
+                requestId: inspection.approval.action.requestId
             };
         }
-        await this.terminalProvider.sendKeys(terminalControl.target, inspection.approval.action.keys, { socketPath: terminalControl.socketPath });
+        if (options.authorize) {
+            const authorization = await options.authorize({
+                agent: adapter.agent,
+                terminalControl: activeTerminalControl,
+                inspection,
+                fingerprint,
+                runtime: options.runtime
+            });
+            if (!authorization.approved) {
+                return {
+                    approved: false,
+                    blocked: true,
+                    reason: authorization.reason ?? "approval was not authorized",
+                    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,
+                    toolName: inspection.approval.toolName,
+                    requestDetail: inspection.approval.requestDetail,
+                    fingerprint,
+                    screenExcerpt: inspection.screenExcerpt,
+                    decisionMode,
+                    requestId: inspection.approval.action.requestId
+                };
+            }
+        }
+        if (decisionMode === "structured") {
+            if (!options.expectedFingerprint) {
+                return {
+                    approved: false,
+                    blocked: true,
+                    reason: "structured approval requires the latest expected fingerprint",
+                    label: inspection.approval.action.label,
+                    promptKind: inspection.approval.promptKind,
+                    command: inspection.approval.command,
+                    fingerprint,
+                    screenExcerpt: inspection.screenExcerpt,
+                    decisionMode,
+                    requestId: inspection.approval.action.requestId
+                };
+            }
+            if (!fingerprint || !adapter.resolveApproval) {
+                return {
+                    approved: false,
+                    blocked: true,
+                    reason: `${adapter.displayName} structured approval resolver is unavailable`,
+                    fingerprint,
+                    screenExcerpt: inspection.screenExcerpt,
+                    decisionMode,
+                    requestId: inspection.approval.action.requestId
+                };
+            }
+            await this.verifyTerminalIdentity(adapter.agent, activeTerminalControl, options.runtime);
+            const resolved = await adapter.resolveApproval({
+                decision: "allow",
+                expectedFingerprint: options.expectedFingerprint,
+                actualFingerprint: fingerprint,
+                inspection,
+                runtime: options.runtime
+            });
+            return {
+                approved: resolved.resolved,
+                blocked: !resolved.resolved,
+                reason: resolved.reason,
+                label: inspection.approval.action.label,
+                promptKind: inspection.approval.promptKind,
+                command: inspection.approval.command,
+                fingerprint,
+                screenExcerpt: inspection.screenExcerpt,
+                decisionMode,
+                requestId: resolved.requestId ?? inspection.approval.action.requestId
+            };
+        }
+        const recaptured = await this.captureInspection(adapter, activeTerminalControl, options);
+        const recapturedInspection = recaptured.inspection;
+        if (!recapturedInspection.approval.approvable) {
+            return {
+                approved: false,
+                blocked: true,
+                reason: "approval prompt is no longer approvable after authorization",
+                promptKind: recapturedInspection.approval.promptKind,
+                command: recapturedInspection.approval.command,
+                cwd: recapturedInspection.approval.cwd,
+                toolName: recapturedInspection.approval.toolName,
+                requestDetail: recapturedInspection.approval.requestDetail,
+                screenExcerpt: recapturedInspection.screenExcerpt
+            };
+        }
+        const recapturedDecisionMode = recapturedInspection.approval.action.mode ?? "keys";
+        const recapturedFingerprint = terminalApprovalFingerprint(adapter.agent, recaptured.terminalControl, recapturedInspection);
+        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]
+                    : undefined,
+                keys: recapturedInspection.approval.action.keys,
+                label: recapturedInspection.approval.action.label,
+                promptKind: recapturedInspection.approval.promptKind,
+                command: recapturedInspection.approval.command,
+                cwd: recapturedInspection.approval.cwd,
+                toolName: recapturedInspection.approval.toolName,
+                requestDetail: recapturedInspection.approval.requestDetail,
+                fingerprint: recapturedFingerprint,
+                screenExcerpt: recapturedInspection.screenExcerpt,
+                decisionMode: recapturedDecisionMode,
+                requestId: recapturedInspection.approval.action.requestId
+            };
+        }
+        if (recapturedFingerprint !== fingerprint) {
+            return {
+                approved: false,
+                blocked: true,
+                reason: "approval fingerprint changed after authorization",
+                key: recapturedInspection.approval.action.keys.length === 1
+                    ? recapturedInspection.approval.action.keys[0]
+                    : undefined,
+                keys: recapturedInspection.approval.action.keys,
+                label: recapturedInspection.approval.action.label,
+                promptKind: recapturedInspection.approval.promptKind,
+                command: recapturedInspection.approval.command,
+                cwd: recapturedInspection.approval.cwd,
+                toolName: recapturedInspection.approval.toolName,
+                requestDetail: recapturedInspection.approval.requestDetail,
+                fingerprint: recapturedFingerprint,
+                screenExcerpt: recapturedInspection.screenExcerpt,
+                decisionMode: recapturedDecisionMode,
+                requestId: recapturedInspection.approval.action.requestId
+            };
+        }
+        const verifiedForApproval = await this.verifyTerminalIdentity(adapter.agent, recaptured.terminalControl, options.runtime);
+        await this.terminalProvider.sendKeys(verifiedForApproval.target, recapturedInspection.approval.action.keys, { socketPath: verifiedForApproval.socketPath });
         return {
             approved: true,
             blocked: false,
-            key: inspection.approval.action.keys.length === 1
-                ? inspection.approval.action.keys[0]
+            key: recapturedInspection.approval.action.keys.length === 1
+                ? recapturedInspection.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
+            keys: recapturedInspection.approval.action.keys,
+            label: recapturedInspection.approval.action.label,
+            promptKind: recapturedInspection.approval.promptKind,
+            command: recapturedInspection.approval.command,
+            cwd: recapturedInspection.approval.cwd,
+            fingerprint: recapturedFingerprint,
+            screenExcerpt: recapturedInspection.screenExcerpt,
+            decisionMode: recapturedDecisionMode,
+            requestId: recapturedInspection.approval.action.requestId
         };
     }
     async monitorPoll(options) {
         const adapter = this.registry.require(options.agent);
         let inspection;
         let status = unsupportedScreenStatus(adapter, options.terminalControl);
-        if (adapter.capabilities.screenStatus) {
+        if (adapter.capabilities.screenStatus &&
+            options.terminalControl.capabilities.includes("screen_status")) {
             try {
                 const captured = await this.captureInspection(adapter, options.terminalControl, options.screenOptions);
                 inspection = captured.inspection;
-                status = statusFromInspection(adapter, options.terminalControl, inspection);
+                status = statusFromInspection(adapter, captured.terminalControl, inspection);
             }
             catch (error) {
                 status = failedScreenStatus(adapter, options.terminalControl, error);
@@ -210,14 +454,17 @@ export class TerminalAgentBridge {
         let durableCompletion;
         let durableError;
         try {
-            durableCompletion = adapter.capabilities.durableCompletion && options.durableRequest
+            durableCompletion = adapter.capabilities.durableCompletion &&
+                options.terminalControl.capabilities.includes("durable_completion") &&
+                options.durableRequest
                 ? await adapter.detectDurableCompletion?.(options.durableRequest)
                 : undefined;
         }
         catch (error) {
             durableError = error instanceof Error ? error.message : String(error);
         }
-        const screenCompletion = adapter.capabilities.screenCompletion
+        const screenCompletion = adapter.capabilities.screenCompletion &&
+            options.terminalControl.capabilities.includes("screen_completion")
             ? inspection?.completion
             : undefined;
         const limitations = [
@@ -237,25 +484,43 @@ export class TerminalAgentBridge {
         };
     }
     async captureInspection(adapter, terminalControl, options = {}) {
-        const screen = await this.terminalProvider.capture(terminalControl.target, {
+        const verifiedTerminalControl = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
+        const screen = await this.terminalProvider.capture(verifiedTerminalControl.target, {
             scrollbackLines: options.scrollbackLines ?? 120,
-            socketPath: terminalControl.socketPath
+            socketPath: verifiedTerminalControl.socketPath
         });
         return {
+            terminalControl: verifiedTerminalControl,
             screen,
             inspection: adapter.inspectScreen({
                 screen,
                 requestText: options.requestText,
                 screenChangedSinceSend: options.screenChangedSinceSend,
-                maxExcerptLength: options.maxExcerptLength
+                maxExcerptLength: options.maxExcerptLength,
+                runtime: options.runtime
             })
         };
     }
+    async verifyTerminalIdentity(agent, terminalControl, runtime) {
+        if (!this.verifyIdentity) {
+            return terminalControl;
+        }
+        if (!Number.isInteger(runtime?.pid) || Number(runtime?.pid) <= 0) {
+            throw new Error(`refusing terminal access for ${agent}:${terminalControl.target} without an exact agent pid; reattach this legacy tmux session before controlling it`);
+        }
+        const result = await this.verifyIdentity({
+            agent,
+            pid: Number(runtime?.pid),
+            terminalControl
+        });
+        return result?.terminalControl ?? terminalControl;
+    }
 }
 export function terminalApprovalFingerprint(agent, terminalControl, inspection) {
     if (!inspection.approval.approvable) {
         return undefined;
     }
+    const decisionMode = inspection.approval.action.mode ?? "keys";
     return createHash("sha256")
         .update(JSON.stringify({
         agent,
@@ -265,7 +530,12 @@ export function terminalApprovalFingerprint(agent, terminalControl, inspection)
         label: inspection.approval.action.label,
         prompt_kind: inspection.approval.promptKind,
         command: inspection.approval.command,
-        screen_excerpt: inspection.screenExcerpt
+        cwd: inspection.approval.cwd,
+        tool_name: inspection.approval.toolName,
+        request_detail: inspection.approval.requestDetail,
+        screen_excerpt: decisionMode === "structured" ? undefined : inspection.screenExcerpt,
+        decision_mode: decisionMode,
+        request_id: inspection.approval.action.requestId
     }))
         .digest("hex");
 }
@@ -291,8 +561,13 @@ function statusFromInspection(adapter, terminalControl, inspection) {
             label: approval.approvable ? approval.action.label : undefined,
             prompt_kind: approval.promptKind,
             command: approval.command,
+            cwd: approval.cwd,
+            tool_name: approval.toolName,
+            request_detail: approval.requestDetail,
             reason: approval.approvable ? undefined : approval.reason,
-            fingerprint
+            fingerprint,
+            decision_mode: approval.approvable ? approval.action.mode ?? "keys" : undefined,
+            request_id: approval.approvable ? approval.action.requestId : undefined
         },
         screen: {
             excerpt: inspection.screenExcerpt,
@@ -326,7 +601,10 @@ function approvalOutput(approval) {
             approvable: false,
             reason: approval.reason,
             promptKind: approval.promptKind,
-            command: approval.command
+            command: approval.command,
+            cwd: approval.cwd,
+            toolName: approval.toolName,
+            requestDetail: approval.requestDetail
         };
     }
     return {
@@ -336,7 +614,12 @@ function approvalOutput(approval) {
         keys: approval.action.keys,
         label: approval.action.label,
         promptKind: approval.promptKind,
-        command: approval.command
+        command: approval.command,
+        cwd: approval.cwd,
+        toolName: approval.toolName,
+        requestDetail: approval.requestDetail,
+        decisionMode: approval.action.mode ?? "keys",
+        requestId: approval.action.requestId
     };
 }
 function unsupportedScreenStatus(adapter, terminalControl) {