@scotthuang/agent-knock-knock 0.12.37 → 0.13.1

package/dist/src/openclaw-plugin-command-adapter.js

@@ -6,9 +6,10 @@ import { executorDefinitionForKind } from "./executors.js";
 import { isTerminalApprovalDecision } from "./terminal-agent-adapter.js";
 import { isRecord, nonBlankString as stringValue } from "./value-guards.js";
 import { AKK_CALLBACK_METHOD, akkUsageText, buildAkkCommandCliArgs, formatAkkListCommandResult, formatAkkRespondCommandResult, formatAkkTerminalWatchHint, formatAkkThreadsCommandResult, formatAkkThreadTransitionCommandResult, formatAkkUnwatchCommandResult, formatAkkWatchCommandResult, formatAkkWatchStatusCommandResult, isAkkModelFacingDiagnosticField, isAkkModelFacingPrivateAuthorityField, isAkkNativeSubmissionAccepted, isAkkThreadTransitionSuccess, normalizeAkkModelFacingFieldName, parseAkkCommand, resolvePluginStoreDir, sanitizeAkkModelFacingDiagnosticText, sanitizeAkkModelFacingLegacyAuthorityInstructionText } from "./openclaw-plugin-helpers.js";
-import { approveParameters, cancelParameters, closeParameters, listParameters, listResumableThreadsParameters, nativeInspectParameters, newThreadParameters, reconcileBindingParameters, renewParameters, respondInteractionParameters, respondParameters, resumeThreadParameters, retryCallbackParameters, sendParameters, statusParameters, unwatchParameters, watchParameters } from "./openclaw-plugin-schemas.js";
-import { consumeOpenClawPrivateAuthorityOffer, openClawApprovalAuthorityOfferKey, openClawInteractionAuthorityOfferKey, rememberOpenClawPrivateAuthorityOffer } from "./openclaw-private-authority-offers.js";
-import { TERMINAL_INTERACTION_LIMITS, validateTerminalInteractionProjection, validateTerminalInteractionResponse } from "./terminal-interaction-protocol.js";
+import { approveParameters, cancelParameters, closeParameters, identifyAndSendParameters, identifyForegroundParameters, listParameters, listResumableThreadsParameters, nativeInspectParameters, newThreadParameters, reconcileBindingParameters, renewParameters, respondInteractionParameters, respondParameters, resumeThreadParameters, retryCallbackParameters, sendParameters, statusParameters, unwatchParameters, watchParameters } from "./openclaw-plugin-schemas.js";
+import { consumeOpenClawPrivateAuthorityOffer, invalidateOpenClawInteractionAuthorityOffersForSubject, openClawApprovalAuthorityOfferKey, openClawInteractionAuthorityOfferKey, rememberOpenClawPrivateAuthorityOffer } from "./openclaw-private-authority-offers.js";
+import { TERMINAL_INTERACTION_LIMITS, TERMINAL_INTERACTION_SUBJECT_VERSION, terminalInteractionSubjectId, validateAnyTerminalInteractionProjection, validateAnyTerminalInteractionResponse } from "./terminal-interaction-protocol.js";
+import { normalizedTerminalSendResultContract, terminalSendEnterDispatched } from "./terminal-dispatch-presenter.js";
 const MAX_DISPLAYED_RESUME_SNAPSHOTS = 512;
 const OPENCLAW_HANDOFF_AUTHORITY_KIND = "handoff";
 const OPENCLAW_RECONCILE_BINDING_AUTHORITY_KIND = "reconcile_binding";
@@ -167,6 +168,7 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
             return args;
         }
     });
+    registerForegroundIdentificationTools(api);
     registerCliTool(api, {
         name: "agent_knock_knock_new_thread",
         description: "Start and verify a clean native coding-agent thread in the exact terminal_id after explicit user intent. A valid unverified agent version remains callable with a compatibility warning. AKK refreshes lifecycle authority privately. Never send /clear as ordinary task text. This creates a new AKK Session but no Turn.",
@@ -274,7 +276,7 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
         async execute(_toolCallId, params, signal) {
             return withHostBridgeInvocationSignal(signal, async () => {
                 try {
-                    const result = await runHostAwareCli(api, buildStatusCliArgs(api, isRecord(params) ? params : {}));
+                    const result = await runStatusRequest(api, params, toolContext);
                     const rendered = toolResult(result);
                     rememberDisplayedApprovalOffer(api, toolContext?.sessionKey, toolContext?.sessionId, result);
                     rememberDisplayedInteractionOffer(api, toolContext?.sessionKey, toolContext?.sessionId, result);
@@ -289,7 +291,7 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
     api.registerTool((toolContext) => ({
         label: "AKK Send",
         name: "agent_knock_knock_send",
-        description: "Start a new AKK Turn, use one advertised terminal_user_explicit user-priority send, or explicitly recover one current uncertain submission only through its advertised retry_submission action. Ordinary send requires request and may use session_id or terminal_id exactly as advertised. terminal_user_explicit requires one exact live physical terminal/process and a scanned, non-blocked approval state; parsed working activity and Codex Composer visibility, stability, or exactness do not veto it. Codex physical fallback sends C-u once to replace the current Composer, injects the request, waits through the paste window, and dispatches Enter exactly once without a post-text Composer veto; Claude Code remains exact-empty-only. The managed fast path may require exact empty before input, but after user-explicit Codex text injection it follows the same no-Composer-veto Enter rule. If broken internal AKK state prevents managed delivery before input, AKK delivers once as unmanaged work with no managed callback Turn, then best-effort attaches an exact Terminal Watch callback and releases stale management. Watch attachment failure never changes a successful Send and is reported in the delivery result. Once the mutation sequence begins, an uncertain result must not be automatically retried. Retry submission is the mutually exclusive exact {turn_id} form and cannot change request text or routing. Draft text, composer digests, and opaque freshness authority stay private. A Turn id is never an ordinary-send destination. Managed acceptance is asynchronous: yield and wait for its callback or an explicit status request.",
+        description: "Start a new AKK Turn, use one advertised terminal_user_explicit user-priority send, or explicitly recover one current uncertain submission only through its advertised retry_submission action. Ordinary send requires request and may use session_id or terminal_id exactly as advertised. terminal_user_explicit requires one exact live physical terminal/process, a scanned non-blocked approval state, and no active native questionnaire; parsed working activity, Codex rollout ambiguity, AKK management state, and Codex Composer visibility, stability, or exactness do not veto physical delivery. Codex physical fallback sends C-u once to replace the current Composer, injects the request, waits through the paste window, and dispatches Enter exactly once without a post-text Composer veto; Claude Code remains exact-empty-only. A source-less Codex terminal freezes all current rollout roots before input, then promotes a provisional Session/Turn only when exactly one anchored or newly opened rollout durably accepts the exact request hash; zero matches remain pending and ambiguity becomes uncertain without replay. If managed preparation fails before input, AKK still delivers once as unmanaged work, then best-effort attaches an exact Terminal Watch callback. After exact request acceptance and terminal attribution, a supported questionnaire on that Watch may expose owner-bound response authority through Status and its watch_id; terminal-activity observations and manual_required interactions remain notification-only. Read terminal_input_dispatched, agent_acceptance, management_mode, observation_mode, and capabilities independently. Watch attachment failure never changes a successful Send. Once the mutation sequence begins, an uncertain result must not be automatically retried. Retry submission is the mutually exclusive exact {turn_id} form and cannot change request text or routing. Draft text, composer digests, and opaque freshness authority stay private. A Turn id is never an ordinary-send destination. Managed acceptance is asynchronous: yield and wait for its callback or an explicit status request.",
         parameters: sendParameters,
         async execute(toolCallId, params, signal) {
             return withHostBridgeInvocationSignal(signal, async () => {
@@ -335,7 +337,7 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
     });
     registerCliTool(api, {
         name: "agent_knock_knock_respond_interaction",
-        description: "Answer exactly one current native questionnaire step shown by agent_knock_knock_status in this controller conversation. Supply only the exact turn_id, interaction_id, and one typed semantic answer: single_select uses selected_option_ids with one advertised option_id; free_text uses text; confirm uses confirm. AKK consumes the displayed private offer and revalidates the exact discriminator-specific shape, prompt, owner, and terminal authority before any input. A displayed expiry is a freshness boundary: after it passes, AKK must prove the same exact live questionnaire again instead of rejecting an otherwise live prompt. Raw keys, menu indexes, rendered labels, fingerprints, versions, and terminal commands are never accepted. An uncertain response must never be retried blindly.",
+        description: "Answer exactly one current native questionnaire step shown by agent_knock_knock_status in this controller conversation. Supply exactly one authoritative subject target: turn_id for a managed Turn or watch_id for an interactive Terminal Watch, plus interaction_id and one typed semantic answer. single_select uses selected_option_ids with one advertised option_id; free_text uses text; confirm uses confirm. AKK consumes only that subject's displayed private offer and revalidates the exact discriminator-specific shape, prompt, owner, task attribution, and terminal authority before any input. A displayed expiry is a freshness boundary: after it passes, AKK must prove the same exact live questionnaire again instead of rejecting an otherwise live prompt. Raw keys, menu indexes, rendered labels, fingerprints, versions, and terminal commands are never accepted. An uncertain response must never be retried blindly.",
         parameters: respondInteractionParameters,
         buildArgs: (params, toolContext) => buildPrivateInteractionResponseArgs(api, params, {
             sessionKey: requiredOpenClawSessionKey(toolContext?.sessionKey),
@@ -407,6 +409,70 @@ export function registerOpenClawCommands(api, displayedResumeSnapshots) {
         }
     });
 }
+function registerForegroundIdentificationTools(api) {
+    registerCliTool(api, {
+        name: "agent_knock_knock_identify_foreground",
+        description: "Explicitly identify the foreground Codex native thread in one exact idle terminal by issuing the closed /status probe once. The result is a short-lived diagnostic bound to the current pane, process, cwd, and screen generation; it creates no Session or Turn and grants no later response, approval, lifecycle, or send authority. Ordinary list/status never runs this probe.",
+        parameters: identifyForegroundParameters,
+        normalizeTurnIdentity: false,
+        buildArgs: async (params) => {
+            const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+            const terminalId = requiredString(params.terminal_id, "terminal_id");
+            const action = await privateTerminalActionArguments(api, terminalId, "agent_knock_knock_identify_foreground", { reconcile: false });
+            const args = [
+                "identify-foreground",
+                "--terminal",
+                terminalId,
+                "--expected-terminal-token",
+                requiredString(action.expected_terminal_token, "current internal foreground-identification terminal authority")
+            ];
+            pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+            pushOptional(args, "--codex-home", stringValue(config.codexHome));
+            return args;
+        }
+    });
+    registerCliTool(api, {
+        name: "agent_knock_knock_identify_and_send",
+        description: "Explicitly identify the foreground Codex native thread with one closed /status probe, then dispatch one task while retaining the same terminal lock. This is an optional managed-attachment enhancement, not a prerequisite for ordinary human Send. The short-lived status observation never becomes durable identity: only the rollout that uniquely accepts the exact task may own the resulting Session/Turn. If the probe or boundary becomes uncertain, AKK does not send or retry the task.",
+        parameters: identifyAndSendParameters,
+        isErrorResult: isSubmissionError,
+        buildArgs: async (params, toolContext, toolCallId) => {
+            const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+            const terminalId = requiredString(params.terminal_id, "terminal_id");
+            const action = await privateTerminalActionArguments(api, terminalId, "agent_knock_knock_identify_and_send", { reconcile: false });
+            const openclawSession = stringValue(toolContext?.sessionKey) ?? "agent:main:main";
+            const args = [
+                "send",
+                "--conversation",
+                terminalId,
+                "--expected-terminal-token",
+                requiredString(action.expected_terminal_token, "current internal identify-and-send terminal authority"),
+                "--identify-foreground",
+                "--message",
+                requiredString(params.request, "request"),
+                "--background"
+            ];
+            pushOptional(args, "--message-id", terminalMessageIdForToolCall({
+                toolCallId,
+                sessionKey: openclawSession,
+                sessionId: toolContext?.sessionId,
+                toolName: "agent_knock_knock_identify_and_send"
+            }));
+            pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+            pushOptional(args, "--idle-timeout-minutes", numberString(params.idleTimeoutMinutes) ??
+                numberString(config.idleTimeoutMinutes));
+            pushOptional(args, "--agent-timeout-minutes", numberString(params.agentTimeoutMinutes) ??
+                numberString(config.agentTimeoutMinutes));
+            pushOptional(args, "--agent-hard-timeout-minutes", numberString(params.agentHardTimeoutMinutes) ??
+                numberString(config.agentHardTimeoutMinutes));
+            pushOptional(args, "--openclaw-session", openclawSession);
+            pushOptional(args, "--gateway-method", CALLBACK_METHOD);
+            pushOptional(args, "--gateway-session", openclawSession);
+            pushOptional(args, "--openclaw-bin", stringValue(config.openclawBin));
+            return args;
+        }
+    });
+}
 function resumeSelectionScope(sessionKey, sessionId) {
     const key = requiredString(sessionKey, "Controller session identity is required for snapshot-bound Resume");
     const incarnation = stringValue(sessionId) ?? null;
@@ -459,15 +525,11 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
             }, {
                 sessionKey: ctx.sessionKey
             });
-            if (result.scope === "terminal_user_explicit") {
-                return {
-                    text: formatSendCommandResult(result),
-                    isError: sendCommandResultIsError(result)
-                };
-            }
             return {
-                text: formatDelegateCommandResult(result),
-                isError: result.status !== "async_pending"
+                text: result.scope === "terminal_user_explicit"
+                    ? formatSendCommandResult(result)
+                    : formatDelegateCommandResult(result),
+                isError: sendCommandResultIsError(result)
             };
         }
         const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
@@ -546,13 +608,15 @@ async function handleAkkCommand(api, ctx, displayedResumeSnapshots) {
     }
 }
 function sendCommandResultIsError(result) {
-    return result.delivered === true &&
-        result.scope === "terminal_user_explicit"
+    return isSuccessfulTerminalDispatch(result)
         ? false
         : terminalSubmissionReported(result)
             ? !isAkkNativeSubmissionAccepted(result)
             : result.status === "delivered_unfenced";
 }
+function isSuccessfulTerminalDispatch(result) {
+    return isRecord(result) && terminalSendEnterDispatched(result);
+}
 async function handleAkkLifecycleCommand(api, ctx, parsed, config, displayedResumeSnapshots) {
     const selectionScope = resumeSelectionScope(ctx.sessionKey, ctx.sessionId);
     const snapshotCacheKey = resumeSnapshotCacheKey(ctx.sessionKey, ctx.sessionId, parsed.terminalId);
@@ -857,48 +921,66 @@ function formatRetryCallbackCommandResult(result) {
         `attempts: ${result.conversation?.callback_delivery?.attempts ?? "unknown"}`
     ].join("\n");
 }
-function formatSendCommandResult(result) {
-    if (result.scope === "terminal_user_explicit") {
-        const unmanaged = result.delivered_unmanaged === true;
-        const replayed = result.replayed === true;
-        const watchCallback = unmanaged &&
-            result.callback_expected === true &&
-            result.callback_mode === "terminal_watch" &&
-            typeof result.watch_id === "string"
-            ? result.watch_id
-            : undefined;
-        if (result.delivered !== true) {
-            return [
-                "AKK already dispatched this managed terminal Send; native acceptance is still pending.",
-                `terminal: ${result.terminal_id ?? "unknown"}`,
-                `message: ${result.message_id ?? "unknown"}`,
-                "delivery: Enter dispatched; do not resend this message id.",
-                "next: inspect AKK status or the terminal; wait for the existing managed Turn."
-            ].join("\n");
-        }
+function formatUnconfirmedTerminalUserExplicitSendResult(result) {
+    const terminalInputDispatched = result.terminal_input_dispatched === true;
+    const enterDispatched = terminalSendEnterDispatched(result);
+    if (!enterDispatched) {
         return [
-            unmanaged
-                ? replayed
-                    ? "AKK confirmed this direct terminal Send was already delivered."
-                    : "AKK delivered the user's request directly to the coding agent."
-                : replayed
-                    ? "AKK confirmed this managed terminal Send was already delivered."
-                    : "AKK delivered the user's terminal Send through managed routing.",
+            terminalInputDispatched
+                ? "AKK started this terminal Send, but could not prove that Enter was dispatched."
+                : "AKK stopped this terminal Send before any terminal input was proven.",
             `terminal: ${result.terminal_id ?? "unknown"}`,
             `message: ${result.message_id ?? "unknown"}`,
-            `delivery: ${unmanaged ? "unmanaged fallback" : "managed"}`,
-            ...(unmanaged
-                ? [watchCallback
-                        ? `callback: Terminal Watch ${watchCallback}; no managed AKK Turn was created.`
-                        : "callback: unavailable; no managed AKK Turn was created."]
-                : []),
-            unmanaged
-                ? watchCallback
-                    ? "next: wait for the Terminal Watch callback; watch-status is the recovery path."
-                    : "next: refresh AKK list and use Watch to observe the still-running coding-agent task."
-                : "next: refresh AKK list; do not resend this message id."
+            terminalInputDispatched
+                ? "delivery: text input may be present; do not resend this message id."
+                : "delivery: no terminal input proven.",
+            "next: inspect AKK status and the terminal before deciding whether to continue."
         ].join("\n");
     }
+    return [
+        "AKK already dispatched this managed terminal Send; native acceptance is still pending.",
+        `terminal: ${result.terminal_id ?? "unknown"}`,
+        `message: ${result.message_id ?? "unknown"}`,
+        "delivery: Enter dispatched; do not resend this message id.",
+        "next: inspect AKK status or the terminal; wait for the existing managed Turn."
+    ].join("\n");
+}
+function formatTerminalUserExplicitSendResult(result) {
+    if (!terminalSendEnterDispatched(result)) {
+        return formatUnconfirmedTerminalUserExplicitSendResult(result);
+    }
+    const unmanaged = result.delivered_unmanaged === true;
+    const replayed = result.replayed === true;
+    const watchCallback = unmanaged &&
+        result.callback_expected === true &&
+        result.callback_mode === "terminal_watch" &&
+        typeof result.watch_id === "string"
+        ? result.watch_id
+        : undefined;
+    return [
+        unmanaged
+            ? replayed
+                ? "AKK confirmed this direct terminal Send was already delivered."
+                : "AKK delivered the user's request directly to the coding agent."
+            : replayed
+                ? "AKK confirmed this managed terminal Send was already delivered."
+                : "AKK delivered the user's terminal Send through managed routing.",
+        `terminal: ${result.terminal_id ?? "unknown"}`,
+        `message: ${result.message_id ?? "unknown"}`,
+        `delivery: ${unmanaged ? "unmanaged fallback" : "managed"}`,
+        ...(unmanaged
+            ? [watchCallback
+                    ? `callback: Terminal Watch ${watchCallback}; no managed AKK Turn was created.`
+                    : "callback: unavailable; no managed AKK Turn was created."]
+            : []),
+        unmanaged
+            ? watchCallback
+                ? "next: wait for the Terminal Watch callback; watch-status is the recovery path."
+                : "next: refresh AKK list and use Watch to observe the still-running coding-agent task."
+            : "next: refresh AKK list; do not resend this message id."
+    ].join("\n");
+}
+function formatManagedSendCommandResult(result) {
     const conversation = result.conversation ?? {};
     const conversationId = conversation.conversation_id ?? result.conversation_id ?? "unknown";
     const sessionId = conversation.session_id ?? result.session_id ?? conversationId;
@@ -979,6 +1061,11 @@ function formatSendCommandResult(result) {
             : `launched: ${result.launched === true ? "yes" : "no"}`
     ].join("\n");
 }
+function formatSendCommandResult(result) {
+    return result.scope === "terminal_user_explicit"
+        ? formatTerminalUserExplicitSendResult(result)
+        : formatManagedSendCommandResult(result);
+}
 function formatCancelCommandResult(result) {
     const conversation = result.conversation ?? {};
     const { sessionId, turnId } = publicTurnIdentity(result);
@@ -1066,7 +1153,7 @@ function publicTurnIdentity(result) {
             "unknown"
     };
 }
-function buildStatusCliArgs(api, params) {
+function buildStatusCliArgs(api, params, toolContext) {
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
     if (Object.hasOwn(params, "watch_id")) {
         if (Object.hasOwn(params, "turn_id") ||
@@ -1077,7 +1164,9 @@ function buildStatusCliArgs(api, params) {
         const watchArgs = [
             "watch-status",
             "--watch",
-            watchId
+            watchId,
+            "--openclaw-session",
+            requiredOpenClawSessionKey(toolContext?.sessionKey)
         ];
         pushOptional(watchArgs, "--store-dir", resolvePluginStoreDir(config));
         return watchArgs;
@@ -1095,6 +1184,12 @@ function buildStatusCliArgs(api, params) {
     }
     return args;
 }
+async function runStatusRequest(api, params, toolContext) {
+    const statusParams = isRecord(params) ? params : {};
+    const statusArgs = buildStatusCliArgs(api, statusParams, toolContext);
+    invalidateRequestedInteractionOffers(api, toolContext?.sessionKey, toolContext?.sessionId, statusParams);
+    return runHostAwareCli(api, statusArgs);
+}
 function terminalScreenExcerpt(result) {
     const screen = result.terminal_screen;
     const text = typeof screen === "string"
@@ -1126,7 +1221,11 @@ async function runSendRequest(api, params, toolContext, messageId) {
         const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
         const args = ["send", "--turn", turnId];
         pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-        return runHostAwareCli(api, args);
+        const result = await runHostAwareCli(api, args);
+        return {
+            ...result,
+            ...normalizedTerminalSendResultContract(result)
+        };
     }
     const requestedType = Object.hasOwn(params, "type")
         ? stringValue(params.type)
@@ -1160,6 +1259,9 @@ async function runSendRequest(api, params, toolContext, messageId) {
     const expectedTerminalToken = terminalAction
         ? requiredString(terminalAction.expected_terminal_token, "current internal terminal send authority")
         : undefined;
+    const expectedManagedTerminalToken = terminalAction
+        ? stringValue(terminalAction.expected_managed_terminal_token)
+        : undefined;
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
     const openclawSession = stringValue(toolContext?.sessionKey) ??
         "agent:main:main";
@@ -1173,6 +1275,7 @@ async function runSendRequest(api, params, toolContext, messageId) {
         args.push("--conversation", requiredString(terminalId, "terminal_id"));
     }
     pushOptional(args, "--expected-terminal-token", expectedTerminalToken);
+    pushOptional(args, "--expected-managed-terminal-token", expectedManagedTerminalToken);
     args.push("--message", requiredString(params.request, "request"), "--background");
     pushOptional(args, "--type", stringValue(params.type));
     pushOptional(args, "--message-id", messageId);
@@ -1187,7 +1290,11 @@ async function runSendRequest(api, params, toolContext, messageId) {
     pushOptional(args, "--gateway-method", CALLBACK_METHOD);
     pushOptional(args, "--gateway-session", openclawSession);
     pushOptional(args, "--openclaw-bin", stringValue(config.openclawBin));
-    return runHostAwareCli(api, args);
+    const result = await runHostAwareCli(api, args);
+    return {
+        ...result,
+        ...normalizedTerminalSendResultContract(result)
+    };
 }
 function toolResult(result, { submissionErrors = false, normalizeTurnIdentity = true, forceError = false } = {}) {
     const normalized = normalizeTurnIdentity ? withTurnIdentity(result) : result;
@@ -1204,9 +1311,11 @@ function toolResult(result, { submissionErrors = false, normalizeTurnIdentity =
         ...(submissionError || forceError ? { isError: true } : {})
     };
 }
-async function privateList(api) {
+async function privateList(api, options = {}) {
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-    const args = ["list", "--reconcile"];
+    const args = ["list"];
+    if (options.reconcile !== false)
+        args.push("--reconcile");
     pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
     pushOptional(args, "--idle-timeout-minutes", numberString(config.idleTimeoutMinutes));
     return runHostAwareCli(api, args);
@@ -1222,15 +1331,16 @@ async function privateThreadDiscovery(api, terminalId) {
     pushOptional(args, "--codex-home", stringValue(config.codexHome));
     return runHostAwareCli(api, args);
 }
-async function privateTerminalActionArguments(api, terminalId, tool) {
+async function privateTerminalActionArguments(api, terminalId, tool, options = {}) {
     return privateActionArguments(api, {
         tool,
         terminalId,
+        reconcile: options.reconcile,
         matches: (argumentsValue) => stringValue(argumentsValue.terminal_id) === terminalId
     });
 }
 async function privateActionArguments(api, input) {
-    const result = await privateList(api);
+    const result = await privateList(api, { reconcile: input.reconcile });
     const terminals = input.terminalId
         ? terminalRows(result).filter((terminal) => stringValue(terminal.id) === input.terminalId)
         : terminalRows(result);
@@ -1299,29 +1409,90 @@ function rememberDisplayedInteractionOffer(api, sessionKeyValue, sessionIdValue,
     const sessionId = stringValue(sessionIdValue);
     if (!sessionKey || !sessionId || !isRecord(result))
         return;
-    const terminalStatus = isRecord(result.terminal_status)
-        ? result.terminal_status
-        : undefined;
-    const fingerprint = stringValue(terminalStatus?.interaction_prompt_fingerprint);
+    const displayed = displayedInteractionStatus(result);
+    if (!displayed)
+        return;
+    const expectedSubjectId = stringValue(displayed.expectedSubjectId);
+    if (!expectedSubjectId || expectedSubjectId === "unknown")
+        return;
+    invalidateOpenClawInteractionAuthorityOffersForSubject(api, sessionKey, sessionId, displayed.expectedSubjectKind, expectedSubjectId);
+    const fingerprint = stringValue(displayed.fields.interaction_prompt_fingerprint);
     if (!isExactInteractionFingerprint(fingerprint))
         return;
     let interactionState;
     try {
-        interactionState = validateTerminalInteractionProjection(terminalStatus?.interaction_state);
+        interactionState = validateAnyTerminalInteractionProjection(displayed.fields.interaction_state);
     }
     catch {
         return;
     }
+    const subject = interactionProjectionSubject(interactionState);
     if (interactionState.state !== "pending" ||
         interactionState.capabilities.respond !== true ||
-        publicTurnIdentity(result).turnId !== interactionState.turn_id) {
+        subject.kind !== displayed.expectedSubjectKind ||
+        subject.id !== expectedSubjectId ||
+        (interactionState.version === TERMINAL_INTERACTION_SUBJECT_VERSION &&
+            (interactionState.response_authority !== "executable" ||
+                interactionState.prompt_fingerprint !== fingerprint))) {
         return;
     }
-    rememberOpenClawPrivateAuthorityOffer(api, openClawInteractionAuthorityOfferKey(sessionKey, sessionId, interactionState.turn_id, interactionState.interaction_id), {
+    rememberOpenClawPrivateAuthorityOffer(api, openClawInteractionAuthorityOfferKey(sessionKey, sessionId, subject.kind, subject.id, interactionState.interaction_id), {
         fingerprint,
         interaction_state: interactionState
     });
 }
+function invalidateRequestedInteractionOffers(api, sessionKeyValue, sessionIdValue, params) {
+    const sessionKey = stringValue(sessionKeyValue);
+    const sessionId = stringValue(sessionIdValue);
+    if (!sessionKey || !sessionId)
+        return;
+    const watchId = stringValue(params.watch_id);
+    if (watchId) {
+        invalidateOpenClawInteractionAuthorityOffersForSubject(api, sessionKey, sessionId, "terminal_watch", watchId);
+        return;
+    }
+    const turnId = stringValue(params.turn_id);
+    if (!turnId)
+        return;
+    invalidateOpenClawInteractionAuthorityOffersForSubject(api, sessionKey, sessionId, "managed_turn", turnId);
+}
+function displayedInteractionStatus(result) {
+    const watch = isRecord(result.watch) ? result.watch : undefined;
+    if (watch) {
+        return {
+            fields: watch,
+            expectedSubjectKind: "terminal_watch",
+            expectedSubjectId: stringValue(watch.watch_id)
+        };
+    }
+    const terminalStatus = isRecord(result.terminal_status)
+        ? result.terminal_status
+        : undefined;
+    if (terminalStatus) {
+        return {
+            fields: terminalStatus,
+            expectedSubjectKind: "managed_turn",
+            expectedSubjectId: publicTurnIdentity(result).turnId
+        };
+    }
+    if (result.interaction_state === undefined)
+        return undefined;
+    const watchId = stringValue(result.watch_id);
+    return {
+        fields: result,
+        expectedSubjectKind: watchId ? "terminal_watch" : "managed_turn",
+        expectedSubjectId: watchId ?? publicTurnIdentity(result).turnId
+    };
+}
+function interactionProjectionSubject(projection) {
+    if (projection.version === TERMINAL_INTERACTION_SUBJECT_VERSION) {
+        return {
+            kind: projection.subject.kind,
+            id: terminalInteractionSubjectId(projection.subject)
+        };
+    }
+    return { kind: "managed_turn", id: projection.turn_id };
+}
 function approvalTargetFromStatus(result) {
     const conversationId = stringValue(result.conversation_id);
     if (stringValue(result.source) === "terminal_control" ||
@@ -1470,26 +1641,28 @@ async function buildPrivateApprovalArgs(api, params, { sessionKey, sessionId })
 }
 function buildPrivateInteractionResponseArgs(api, params, { sessionKey, sessionId }) {
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-    const turnId = requiredTerminalInteractionIdentifier(params.turn_id, "turn_id");
+    const requestedSubject = requestedInteractionSubject(params);
     const interactionId = requiredTerminalInteractionIdentifier(params.interaction_id, "interaction_id");
-    const offered = consumeOpenClawPrivateAuthorityOffer(api, openClawInteractionAuthorityOfferKey(sessionKey, sessionId, turnId, interactionId));
+    const offered = consumeOpenClawPrivateAuthorityOffer(api, openClawInteractionAuthorityOfferKey(sessionKey, sessionId, requestedSubject.kind, requestedSubject.id, interactionId));
     const fingerprint = stringValue(offered?.fingerprint);
     if (!isExactInteractionFingerprint(fingerprint) ||
         offered?.interaction_state === undefined) {
         throw new Error("respond_interaction requires a current pending interaction shown by agent_knock_knock_status in this controller conversation; refresh status, review the current questions, and respond again");
     }
-    const projection = validateTerminalInteractionProjection(offered.interaction_state);
-    const response = validateTerminalInteractionResponse(params, projection, {
-        // This consumes a still-live, session/incarnation-bound private offer. The
-        // CLI/bridge path always performs exact live terminal recaptures before it
-        // can reserve or dispatch input, so projection expiry is a recheck trigger
-        // here rather than proof that the native questionnaire disappeared.
+    const projection = validateAnyTerminalInteractionProjection(offered.interaction_state);
+    assertInteractionSubjectMatchesProjection(requestedSubject, projection);
+    const responseInput = interactionResponseForProjection(params, projection);
+    const response = validateAnyTerminalInteractionResponse(responseInput, projection, {
+        // This consumes a still-live, session/incarnation-bound private offer.
+        // The CLI/bridge path always performs exact live terminal recaptures
+        // before it can reserve or dispatch input, so projection expiry is a
+        // recheck trigger rather than proof that the questionnaire disappeared.
         allowExpiredForLiveRecapture: true
     });
     const args = [
         "respond-interaction",
-        "--turn",
-        response.turn_id,
+        requestedSubject.cliOption,
+        requestedSubject.id,
         "--interaction",
         response.interaction_id,
         "--response-json",
@@ -1504,6 +1677,43 @@ function buildPrivateInteractionResponseArgs(api, params, { sessionKey, sessionI
     pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
     return args;
 }
+function requestedInteractionSubject(params) {
+    const hasTurn = Object.hasOwn(params, "turn_id");
+    const hasWatch = Object.hasOwn(params, "watch_id");
+    if (hasTurn === hasWatch) {
+        throw new Error("respond_interaction requires exactly one of turn_id or watch_id");
+    }
+    return hasTurn
+        ? {
+            kind: "managed_turn",
+            id: requiredTerminalInteractionIdentifier(params.turn_id, "turn_id"),
+            cliOption: "--turn"
+        }
+        : {
+            kind: "terminal_watch",
+            id: requiredTerminalInteractionIdentifier(params.watch_id, "watch_id"),
+            cliOption: "--watch"
+        };
+}
+function assertInteractionSubjectMatchesProjection(requested, projection) {
+    const projected = interactionProjectionSubject(projection);
+    if (requested.kind !== projected.kind || requested.id !== projected.id) {
+        throw new Error("respond_interaction target does not match the displayed interaction subject; refresh status and respond to its exact turn_id or watch_id");
+    }
+}
+function interactionResponseForProjection(params, projection) {
+    if (projection.version !== TERMINAL_INTERACTION_SUBJECT_VERSION) {
+        return params;
+    }
+    return {
+        interaction_id: params.interaction_id,
+        subject: projection.subject,
+        ...(projection.subject.kind === "managed_turn"
+            ? { turn_id: params.turn_id }
+            : {}),
+        answers: params.answers
+    };
+}
 function isExactApprovalFingerprint(value) {
     return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
 }
@@ -1577,7 +1787,7 @@ function sanitizeModelFacingValue(value, parentKey, path = []) {
         }
         if (key === "interaction_state") {
             try {
-                output[key] = validateTerminalInteractionProjection(item);
+                output[key] = sanitizeModelFacingValue(validateAnyTerminalInteractionProjection(item), undefined, [...path, key]);
             }
             catch {
                 continue;
@@ -1641,8 +1851,7 @@ function isSubmissionError(result) {
     if (!isRecord(result)) {
         return false;
     }
-    if (result.delivered === true &&
-        result.scope === "terminal_user_explicit") {
+    if (isSuccessfulTerminalDispatch(result)) {
         return false;
     }
     if (terminalSubmissionReported(result)) {
@@ -1751,7 +1960,10 @@ async function runDelegate(api, params, toolContext) {
         // A uniquely delegated user-priority Send may deliberately complete
         // without creating a managed Turn. Preserve that terminal receipt for the
         // shared Send formatter instead of inventing Session/Turn identity.
-        return parsed;
+        return {
+            ...parsed,
+            ...normalizedTerminalSendResultContract(parsed)
+        };
     }
     const conversationId = stringValue(parsed.conversation_id) ??
         (isRecord(parsed.conversation)
@@ -1831,6 +2043,7 @@ async function runDelegate(api, params, toolContext) {
         callback_method: hostBridgePresentationApis.has(api)
             ? "command_json_v1"
             : CALLBACK_METHOD,
+        ...normalizedTerminalSendResultContract(parsed),
         ...(submissionUnfenced
             ? {
                 submission_outcome: "submitted",
@@ -1918,7 +2131,8 @@ function registerCliTool(api, { name, description, parameters, buildArgs, normal
                 try {
                     const result = await runHostAwareCli(api, await buildArgs(isRecord(params) ? params : {}, toolContext, toolCallId));
                     const rendered = toolResult(result, {
-                        submissionErrors: name === "agent_knock_knock_respond",
+                        submissionErrors: name === "agent_knock_knock_respond" ||
+                            name === "agent_knock_knock_identify_and_send",
                         normalizeTurnIdentity,
                         forceError: typeof isErrorResult === "function" && isErrorResult(result) === true
                     });