@scotthuang/agent-knock-knock 0.2.44 → 0.2.47

package/dist/src/cli.js

@@ -5,21 +5,47 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { createCodexTerminalAgentAdapter, detectCodexDurableCompletion } from "./codex-terminal-agent-adapter.js";
+import { createClaudeTerminalAgentAdapter } from "./claude-terminal-agent-adapter.js";
+import { ClaudeHookStore, ClaudeHookStoreError, defaultClaudeHookStoreDir } from "./claude-hook-store.js";
+import { claudePermissionHookOutput } from "./claude-hook-protocol.js";
+import { defaultClaudeSettingsPath, installClaudeHooks, loadTrustedClaudeTokenjuiceLaunchers } from "./claude-hook-installer.js";
 import { CodexLocalSessionProvider } from "./codex-local-session-provider.js";
 import { CodexStoreAdapter } from "./codex-store-adapter.js";
 import { applyMessageToConversation, budgetAction, createConversation, createMessage, executorForConversation, extractStructuredMessage, parseMessageJson, resolveExecutor } from "./protocol.js";
 import { EXECUTOR_KINDS, acpxCommandForExecutor, executorDefinitionForKind, modelEnvForExecutor, normalizeModelForExecutor, proxyEnvForExecutor } from "./executors.js";
 import { executorBootstrapPrompt } from "./bootstrap.js";
-import { redactString, writeRuntimeLog } from "./runtime-log.js";
+import { writeRuntimeLog } from "./runtime-log.js";
 import { formatTranscript, readNdjsonLog } from "./transcript.js";
 import { appendEvent, defaultStoreDir, listConversations, logPathForStatePath, loadConversationById, loadState, messageEvent, pathsForConversation, pathsForConversationDir, saveState, statePathForConversationId } from "./store.js";
 import { planFork, planTakeover } from "./session-takeover-planner.js";
-import { StaticTerminalControlProvider, TmuxTerminalControlProvider, enrichActiveProcessesWithTerminalControl, terminalRefFromPane } from "./terminal-control-provider.js";
+import { StaticTerminalControlProvider, TmuxTerminalControlProvider } from "./terminal-control-provider.js";
+import { parseTerminalConversationId } from "./terminal-agent-adapter.js";
+import { createProductionTerminalAgentRegistry } from "./terminal-agent-registry.js";
+import { StaticTerminalProcessSource, SystemTerminalProcessSource } from "./terminal-process-source.js";
+import { TerminalAgentBridge } from "./terminal-agent-bridge.js";
 const DEFAULT_IDLE_TIMEOUT_MINUTES = 10080;
 const DEFAULT_AGENT_TIMEOUT_MINUTES = 60;
 const DEFAULT_AGENT_HARD_TIMEOUT_MINUTES = 720;
 const DEFAULT_MONITOR_POLL_INTERVAL_MS = 5000;
+const CALLBACK_RETRY_DELAYS_MS = [5000, 15000, 60000, 60000];
 const DEFAULT_CODEX_ACPX_AGENT_COMMAND = "npx -y @agentclientprotocol/codex-acp@^1.1.0";
+const CONVERSATION_STATUSES = new Set([
+    "created",
+    "running",
+    "waiting_for_agent",
+    "waiting_for_openclaw",
+    "idle",
+    "stalled",
+    "needs_recovery",
+    "needs_model_selection",
+    "callback_pending",
+    "callback_failed",
+    "failed",
+    "closed",
+    "cancelled",
+    "cancelling"
+]);
 class InlineCodexSessionAdapter {
     threads;
     processes;
@@ -121,12 +147,21 @@ async function runCommand(commandName, options) {
     else if (commandName === "install-openclaw") {
         runInstallOpenClaw(options);
     }
+    else if (commandName === "install-claude-hooks") {
+        runInstallClaudeHooks(options);
+    }
+    else if (commandName === "claude-hook") {
+        await runClaudeHook(options);
+    }
     else if (commandName === "doctor") {
         runDoctor(options);
     }
     else if (commandName === "callback") {
         runCallback(options);
     }
+    else if (commandName === "retry-callback") {
+        runRetryCallback(options);
+    }
     else if (commandName === "monitor") {
         await runMonitor(options);
     }
@@ -188,6 +223,88 @@ function runInstallOpenClaw(options) {
             : "Agent Knock Knock is installed. Try: AKK list"
     });
 }
+function runInstallClaudeHooks(options) {
+    const configuredExecutable = stringValue(options.executablePath ?? options.binPath);
+    let executablePath;
+    if (configuredExecutable) {
+        executablePath = path.resolve(expandHome(configuredExecutable));
+    }
+    else {
+        try {
+            executablePath = resolveExecutable("agent-knock-knock");
+        }
+        catch {
+            executablePath = path.resolve(process.argv[1]);
+        }
+    }
+    const result = installClaudeHooks({
+        executablePath,
+        settingsPath: expandHome(options.settingsPath ?? options.settings),
+        dryRun: options.dryRun === true
+    });
+    printJson({
+        installed: result.written || !result.changed,
+        ...result,
+        executablePath,
+        next: result.dryRun
+            ? "Run again without --dry-run to install the Claude Code hooks."
+            : "Claude Code hooks are configured. Existing sessions pick them up through settings reload; start a new session if needed."
+    });
+}
+async function runClaudeHook(options) {
+    const rawInput = fs.readFileSync(0, "utf8");
+    let input;
+    try {
+        input = JSON.parse(rawInput);
+    }
+    catch {
+        throw new Error("Claude hook input must be valid JSON");
+    }
+    const agentRows = loadClaudeAgentRows(options);
+    const claudePid = inferClaudeAncestorPid(agentRows);
+    const store = createClaudeHookStore(options);
+    const record = store.record(input, {
+        ...(claudePid === undefined ? {} : { claudePid })
+    });
+    if (record.event.input.hook_event_name !== "PermissionRequest" || !record.permission) {
+        return;
+    }
+    const permission = record.permission;
+    const requestedTimeout = options.permissionWaitTimeoutMs ?? options.timeoutMs;
+    const timeoutMs = requestedTimeout === undefined
+        ? undefined
+        : Math.max(0, Number(requestedTimeout));
+    try {
+        const decision = await store.waitForPermissionDecision({
+            sessionId: permission.sessionId,
+            requestId: permission.requestId,
+            fingerprint: permission.fingerprint,
+            conversationId: permission.conversationId,
+            messageId: permission.messageId,
+            ...(timeoutMs === undefined ? {} : { timeoutMs })
+        });
+        process.stdout.write(`${JSON.stringify(decision?.hookOutput ?? claudePermissionHookOutput({
+            behavior: "deny",
+            interrupt: false,
+            message: "Agent Knock Knock approval timed out. Review the request and retry the task."
+        }))}\n`);
+    }
+    catch (error) {
+        if (error instanceof ClaudeHookStoreError && [
+            "PERMISSION_EXPIRED",
+            "PERMISSION_CONSUMED",
+            "PERMISSION_ALREADY_DECIDED"
+        ].includes(error.code)) {
+            process.stdout.write(`${JSON.stringify(claudePermissionHookOutput({
+                behavior: "deny",
+                interrupt: false,
+                message: "Agent Knock Knock approval expired before a safe decision was received."
+            }))}\n`);
+            return;
+        }
+        throw error;
+    }
+}
 function installOpenClawPlugin(openclawBin, root) {
     const linked = spawnSync(openclawBin, ["plugins", "install", "--link", root], {
         encoding: "utf8",
@@ -549,7 +666,7 @@ function selectTerminateTarget({ plan, session, activeSessions, expectedPid, all
 }
 async function listActiveSessionsWithTerminalControl(provider, options, terminalProvider = createTerminalControlProvider(options)) {
     const activeSessions = await provider.listActiveSessions();
-    return enrichActiveProcessesWithTerminalControl(activeSessions, terminalProvider);
+    return createTerminalAgentBridge(options, terminalProvider).attachProcesses(provider.agent, activeSessions);
 }
 function createTerminalControlProvider(options) {
     if (options.terminalsJson || options.terminalScreensJson || options.processesJson) {
@@ -560,6 +677,161 @@ function createTerminalControlProvider(options) {
     }
     return new TmuxTerminalControlProvider();
 }
+function createTerminalProcessSource(options) {
+    if (options.processesJson) {
+        return new StaticTerminalProcessSource(parseJsonOption(options.processesJson, "--processes-json"));
+    }
+    return new SystemTerminalProcessSource();
+}
+function createClaudeHookStore(options = {}) {
+    const configuredRoot = stringValue(options.claudeHookStoreDir);
+    return new ClaudeHookStore({
+        rootDir: expandHome(configuredRoot ?? defaultClaudeHookStoreDir())
+    });
+}
+function loadClaudeAgentRows(options = {}) {
+    let value;
+    if (options.claudeAgentsJson !== undefined) {
+        value = typeof options.claudeAgentsJson === "string"
+            ? parseJsonOption(options.claudeAgentsJson, "--claude-agents-json")
+            : options.claudeAgentsJson;
+    }
+    else if (options.processesJson || options.terminalsJson || options.terminalScreensJson) {
+        return [];
+    }
+    else {
+        const claudeExecutable = resolveOptionalExecutable("claude");
+        if (!claudeExecutable) {
+            return [];
+        }
+        const result = spawnSync(claudeExecutable, ["agents", "--json", "--all"], {
+            encoding: "utf8",
+            maxBuffer: 1024 * 1024 * 10,
+            timeout: 10_000
+        });
+        if (result.error || result.status !== 0) {
+            runtimeLog("warn", "claude_agents_list_failed", {
+                status: result.status ?? null,
+                error: result.error?.message,
+                stderr: textSummary(cleanProcessText(result.stderr))
+            });
+            return [];
+        }
+        try {
+            value = JSON.parse(result.stdout);
+        }
+        catch {
+            runtimeLog("warn", "claude_agents_list_invalid_json", {
+                stdout: textSummary(result.stdout)
+            });
+            return [];
+        }
+    }
+    const rows = Array.isArray(value)
+        ? value
+        : isRecord(value) && Array.isArray(value.agents)
+            ? value.agents
+            : [];
+    return rows.flatMap((row) => {
+        if (!isRecord(row) || !Number.isInteger(Number(row.pid))) {
+            return [];
+        }
+        return [{
+                pid: Number(row.pid),
+                ...(stringValue(row.cwd) ? { cwd: stringValue(row.cwd) } : {}),
+                ...(stringValue(row.kind) ? { kind: stringValue(row.kind) } : {}),
+                ...(stringValue(row.sessionId) ? { sessionId: stringValue(row.sessionId) } : {}),
+                ...(stringValue(row.status) ? { status: stringValue(row.status) } : {})
+            }];
+    });
+}
+function inferClaudeAncestorPid(agentRows, startingPid = process.ppid) {
+    const interactivePids = new Set(agentRows
+        .filter((row) => row.kind === undefined || row.kind === "interactive")
+        .map((row) => row.pid)
+        .filter((pid) => Number.isInteger(pid)));
+    let pid = startingPid;
+    const visited = new Set();
+    for (let depth = 0; depth < 16 && Number.isInteger(pid) && pid > 1 && !visited.has(pid); depth += 1) {
+        visited.add(pid);
+        const processRow = spawnSync("ps", ["-p", String(pid), "-o", "pid=,ppid=,command="], {
+            encoding: "utf8",
+            timeout: 2_000
+        });
+        if (processRow.error || processRow.status !== 0) {
+            return undefined;
+        }
+        const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/u.exec(String(processRow.stdout).trim());
+        if (!match) {
+            return undefined;
+        }
+        const currentPid = Number(match[1]);
+        const parentPid = Number(match[2]);
+        const commandText = match[3];
+        if (interactivePids.has(currentPid) || isClaudeProcessCommand(commandText)) {
+            return currentPid;
+        }
+        pid = parentPid;
+    }
+    return undefined;
+}
+function isClaudeProcessCommand(commandText) {
+    const executable = commandText.trim().split(/\s+/u, 1)[0];
+    return path.basename(executable) === "claude" ||
+        /[\\/]\.local[\\/]share[\\/]claude[\\/]versions[\\/][^\\/\s]+$/u.test(executable);
+}
+function createRuntimeTerminalAgentRegistry(options) {
+    return createProductionTerminalAgentRegistry({
+        overrides: [
+            createCodexTerminalAgentAdapter({
+                async detectDurableCompletion(request) {
+                    const runtime = isRecord(request.context) ? request.context : undefined;
+                    const conversation = runtime?.conversation;
+                    const nativeTakeover = isRecord(runtime?.nativeTakeover)
+                        ? runtime?.nativeTakeover
+                        : undefined;
+                    if (!isRecord(conversation)) {
+                        return undefined;
+                    }
+                    const contextMatch = await loadCodexTerminalContext({
+                        conversation,
+                        nativeTakeover,
+                        options
+                    });
+                    if (!contextMatch?.context) {
+                        return undefined;
+                    }
+                    const evidence = detectCodexDurableCompletion({
+                        ...request,
+                        context: contextMatch.context
+                    });
+                    return evidence
+                        ? {
+                            ...evidence,
+                            confidence: contextMatch.confidence,
+                            metadata: {
+                                ...evidence.metadata,
+                                context_match: contextMatch.match,
+                                session: contextMatch.context.source
+                            }
+                        }
+                        : undefined;
+                }
+            }),
+            createClaudeTerminalAgentAdapter({
+                agentRows: loadClaudeAgentRows(options),
+                hookStore: createClaudeHookStore(options),
+                trustedTokenjuiceLaunchers: loadTrustedClaudeTokenjuiceLaunchers(expandHome(options.claudeSettingsPath ?? defaultClaudeSettingsPath()))
+            })
+        ]
+    });
+}
+function createTerminalAgentBridge(options, terminalProvider = createTerminalControlProvider(options)) {
+    return new TerminalAgentBridge({
+        registry: createRuntimeTerminalAgentRegistry(options),
+        terminalProvider
+    });
+}
 function planTerminalControlTakeover(session, activeSessions) {
     const matched = activeSessions
         .filter((process) => process.kind === "codex_cli" &&
@@ -609,6 +881,9 @@ function terminalControlFromTakeover(nativeTakeover) {
     if (!target || !session || !Number.isInteger(window) || !Number.isInteger(pane) || !Number.isInteger(panePid)) {
         return undefined;
     }
+    const storedCapabilities = Array.isArray(terminalControl.capabilities)
+        ? terminalControl.capabilities.filter(isTerminalControlCapability)
+        : [];
     return {
         kind: "tmux",
         target,
@@ -619,181 +894,47 @@ function terminalControlFromTakeover(nativeTakeover) {
         currentCommand: stringValue(terminalControl.currentCommand),
         currentPath: stringValue(terminalControl.currentPath),
         socketPath: stringValue(terminalControl.socketPath),
-        capabilities: ["screen_status", "send_keys", "terminal_approval"]
-    };
-}
-function detectCodexApprovalPrompt(screen) {
-    const prompt = codexApprovalPromptRegion(screen);
-    if (!prompt.visible) {
-        return {
-            approvable: false,
-            reason: prompt.reason
-        };
-    }
-    for (const line of prompt.region.split(/\r?\n/)) {
-        const match = /^[\s›]*1\.\s+(Yes,[^(]+)\(([^)]+)\)/u.exec(line.trim());
-        if (!match) {
-            continue;
-        }
-        const key = match[2].trim();
-        if (key !== "y") {
-            return {
-                approvable: false,
-                reason: `primary approval shortcut is ${key}, not y`,
-                ...approvalCandidateFromPrompt(prompt.marker, prompt.region)
-            };
-        }
-        return {
-            approvable: true,
-            key,
-            label: match[1].trim(),
-            ...approvalCandidateFromPrompt(prompt.marker, prompt.region)
-        };
-    }
-    return {
-        approvable: false,
-        reason: "no primary approve option with a shortcut was detected",
-        ...approvalCandidateFromPrompt(prompt.marker, prompt.region)
-    };
-}
-function isCodexApprovalPromptVisible(screen) {
-    return codexApprovalPromptRegion(screen).visible;
-}
-function codexApprovalPromptRegion(screen) {
-    const approvalMarkers = [
-        "Would you like to run the following command?",
-        "Would you like to make the following edits?",
-        "Would you like to grant these permissions?",
-        "needs your approval."
-    ];
-    const lines = screen.split(/\r?\n/);
-    let markerIndex = -1;
-    let matchedMarker = "";
-    for (let index = lines.length - 1; index >= 0; index -= 1) {
-        const marker = approvalMarkers.find((candidate) => lines[index].includes(candidate));
-        if (marker) {
-            markerIndex = index;
-            matchedMarker = marker;
-            break;
-        }
-    }
-    if (markerIndex < 0) {
-        return {
-            visible: false,
-            reason: "no Codex approval prompt was detected in the terminal screen"
-        };
-    }
-    const regionLines = lines.slice(markerIndex);
-    const staleLine = regionLines.slice(1).find((line) => isPostApprovalActivityLine(line));
-    if (staleLine) {
-        return {
-            visible: false,
-            reason: `Codex approval prompt appears stale after later terminal activity: ${staleLine.trim()}`
-        };
-    }
-    return {
-        visible: true,
-        region: regionLines.join("\n"),
-        marker: matchedMarker
-    };
-}
-function approvalCandidateFromPrompt(marker, region) {
-    const promptKind = marker === "Would you like to run the following command?"
-        ? "run_command"
-        : marker === "Would you like to make the following edits?"
-            ? "file_edit"
-            : marker === "Would you like to grant these permissions?"
-                ? "grant_permissions"
-                : "unknown";
-    return {
-        promptKind,
-        command: promptKind === "run_command" ? commandFromApprovalRegion(region) : undefined
+        // State written before adapter capabilities were persisted always represented Codex.
+        capabilities: storedCapabilities.length > 0
+            ? storedCapabilities
+            : [
+                "screen_status",
+                "send_keys",
+                "terminal_approval",
+                "screen_completion",
+                "durable_completion",
+                "terminal_cancel"
+            ]
     };
 }
-function commandFromApprovalRegion(region) {
-    const lines = region.split(/\r?\n/);
-    const commandStart = lines.findIndex((line) => /^\s*\$\s+/u.test(line));
-    if (commandStart < 0) {
-        return undefined;
-    }
-    const parts = [];
-    for (let index = commandStart; index < lines.length; index += 1) {
-        const line = lines[index];
-        if (index > commandStart && (!line.trim() || /^[\s›]*\d+\.\s+/u.test(line) || /Press enter to confirm/u.test(line))) {
-            break;
-        }
-        parts.push(index === commandStart ? line.replace(/^\s*\$\s+/u, "").trim() : line.trim());
-    }
-    const command = parts.filter(Boolean).join(" ").trim();
-    return command ? redactString(command) : undefined;
-}
-function isPostApprovalActivityLine(line) {
-    const trimmed = line.trim();
-    if (!trimmed) {
-        return false;
-    }
-    if (/^✔\s+You approved\b/u.test(trimmed)) {
-        return true;
-    }
-    if (/^›\s+(?!1\.)\S/u.test(trimmed)) {
-        return true;
-    }
-    if (/^•\s+(Working|Ran|Explored|Edited|Read|Called|Searching|Planning|Updated|Added|Deleted|Modified|Running|Thinking)\b/u.test(trimmed)) {
-        return true;
-    }
-    return /^─\s*Worked for\b/u.test(trimmed);
-}
-function detectCodexActivityState(screen, approval = detectCodexApprovalPrompt(screen)) {
-    if (approval.approvable || isCodexApprovalPromptVisible(screen)) {
-        return {
-            state: "awaiting_approval",
-            reason: "current Codex approval prompt is visible"
-        };
-    }
-    const tailLines = screen.trimEnd().split(/\r?\n/).slice(-30);
-    const workingLine = tailLines.find((line) => isCodexWorkingLine(line));
-    if (workingLine) {
-        return {
-            state: "working",
-            reason: `Codex working marker detected: ${workingLine.trim()}`
-        };
-    }
-    const idleLine = tailLines
-        .slice(-6)
-        .map((line) => line.trim())
-        .find((line) => isCodexIdlePromptLine(line));
-    if (idleLine) {
-        return {
-            state: "idle",
-            reason: `Codex input prompt detected: ${idleLine}`
-        };
-    }
+function terminalRuntimeIdentityForConversation(conversation, terminalControl) {
+    const nativeTakeover = isRecord(conversation?.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const nativeSessionId = stringValue(nativeTakeover?.native_session_id);
+    const terminalIdentity = parseTerminalConversationId(nativeSessionId);
+    const explicitSessionId = stringValue(nativeTakeover?.terminal_agent_session_id) ??
+        (terminalIdentity ? undefined : nativeSessionId);
     return {
-        state: "unknown",
-        reason: "no current Codex working, idle, or approval marker was detected in the terminal screen"
+        pid: Number.isInteger(Number(nativeTakeover?.terminal_agent_pid))
+            ? Number(nativeTakeover?.terminal_agent_pid)
+            : terminalIdentity?.pid,
+        sessionId: explicitSessionId,
+        cwd: stringValue(nativeTakeover?.source_cwd) ?? terminalControl.currentPath,
+        conversationId: stringValue(conversation?.conversation_id),
+        messageId: stringValue(nativeTakeover?.terminal_bridge_message_id),
+        terminalTarget: terminalControl.target
     };
 }
-function isCodexWorkingLine(line) {
-    const trimmed = line.trim();
-    if (!trimmed) {
-        return false;
-    }
-    if (/^•\s+Working\b/u.test(trimmed) && (/\besc to interrupt\b/u.test(trimmed) || trimmed === "• Working")) {
-        return true;
-    }
-    if (/^•\s+Waiting for background terminals?\b(?:\s*·|$)/u.test(trimmed)) {
-        return true;
-    }
-    return /^\d+\s+background terminals? running\b/u.test(trimmed) && /\/(?:ps|stop)\b/u.test(trimmed);
-}
-function isCodexIdlePromptLine(line) {
-    const trimmed = line.trim();
-    return /^›(?:\s|$)/u.test(trimmed) && !/^›\s*1\./u.test(trimmed);
-}
-function screenExcerpt(screen, maxLength = 4000) {
-    const lines = screen.trimEnd().split(/\r?\n/);
-    const excerpt = lines.slice(Math.max(0, lines.length - 80)).join("\n");
-    return redactString(excerpt).slice(-maxLength);
+function isTerminalControlCapability(value) {
+    return typeof value === "string" && [
+        "screen_status",
+        "send_keys",
+        "terminal_approval",
+        "screen_completion",
+        "durable_completion",
+        "terminal_cancel"
+    ].includes(value);
 }
 function createForkConversation({ agent, strategy, session, contextPackage, forkSummary, modelInfo, options }) {
     const workspace = session.cwd;
@@ -1336,7 +1477,7 @@ function startExecutorMonitor({ statePath, logPath, pid, outputPath, agentTimeou
     child.unref();
     return child;
 }
-function startTerminalBridgeMonitor({ statePath, logPath, agentTimeoutMinutes, agentHardTimeoutMinutes, pollIntervalMs, codexHome }) {
+function startTerminalBridgeMonitor({ statePath, logPath, agentTimeoutMinutes, agentHardTimeoutMinutes, pollIntervalMs, codexHome, claudeHookStoreDir }) {
     const args = [
         new URL(import.meta.url).pathname,
         "monitor",
@@ -1355,6 +1496,9 @@ function startTerminalBridgeMonitor({ statePath, logPath, agentTimeoutMinutes, a
     if (codexHome) {
         args.push("--codex-home", codexHome);
     }
+    if (claudeHookStoreDir) {
+        args.push("--claude-hook-store-dir", claudeHookStoreDir);
+    }
     const child = spawn(process.execPath, args, {
         detached: true,
         stdio: "ignore",
@@ -1381,7 +1525,8 @@ function startTerminalBridgeMonitorForConversation({ conversation, statePath, lo
             nativeTakeover?.["terminal_bridge_hard_timeout_minutes"] ??
             DEFAULT_AGENT_HARD_TIMEOUT_MINUTES),
         pollIntervalMs: Number(options.monitorPollIntervalMs ?? DEFAULT_MONITOR_POLL_INTERVAL_MS),
-        codexHome: options.codexHome
+        codexHome: options.codexHome,
+        claudeHookStoreDir: options.claudeHookStoreDir ?? nativeTakeover?.["claude_hook_store_dir"]
     });
 }
 function terminalBridgeEnabled(conversation) {
@@ -1404,6 +1549,7 @@ function withTerminalBridgeState({ conversation, message, startedAt, agentTimeou
             terminal_bridge_request_text: String(message.body ?? ""),
             terminal_bridge_request_hash: terminalBridgeRequestFingerprint(message.body),
             terminal_bridge_pre_send_screen_fingerprint: preSendScreenFingerprint,
+            terminal_bridge_completion_claim: undefined,
             terminal_bridge_monitor_started_at: startedAt,
             terminal_bridge_last_activity_at: startedAt,
             terminal_bridge_inactivity_timeout_minutes: agentTimeoutMinutes,
@@ -1414,6 +1560,165 @@ function withTerminalBridgeState({ conversation, message, startedAt, agentTimeou
         updated_at: startedAt
     };
 }
+function activateClaudeHookLease({ options, conversation, message, terminalControl, expiresAt }) {
+    const runtime = terminalRuntimeIdentityForConversation(conversation, terminalControl);
+    const pid = runtime.pid;
+    const agentRow = pid === undefined
+        ? undefined
+        : loadClaudeAgentRows(options).find((row) => row.pid === pid && (row.kind === undefined || row.kind === "interactive"));
+    const sessionId = agentRow?.sessionId ?? runtime.sessionId;
+    const cwd = agentRow?.cwd ?? runtime.cwd ?? terminalControl.currentPath;
+    if (!cwd || (pid === undefined && !sessionId)) {
+        runtimeLog("warn", "claude_hook_lease_unavailable", {
+            conversation_id: conversation.conversation_id,
+            terminal_target: terminalControl.target,
+            reason: "exact Claude pid/session identity is unavailable"
+        });
+        return undefined;
+    }
+    const store = createClaudeHookStore(options);
+    try {
+        const previous = store.resolveLease({
+            ...(sessionId === undefined ? {} : { sessionId }),
+            ...(pid === undefined ? {} : { pid }),
+            cwd,
+            requireUnique: true
+        });
+        if (previous && (previous.lease.conversationId !== conversation.conversation_id ||
+            previous.lease.messageId !== message.id)) {
+            store.releaseLease({ leaseId: previous.lease.id });
+        }
+        const lease = store.activateLease({
+            ...(sessionId === undefined ? {} : { sessionId }),
+            ...(pid === undefined ? {} : { pid }),
+            cwd,
+            conversationId: conversation.conversation_id,
+            messageId: message.id,
+            terminalTarget: terminalControl.target,
+            expiresAt
+        });
+        runtimeLog("info", "claude_hook_lease_activated", {
+            conversation_id: conversation.conversation_id,
+            message_id: message.id,
+            terminal_target: terminalControl.target,
+            lease_id: lease.id,
+            pid,
+            session_id: sessionId,
+            expires_at: lease.expiresAt
+        });
+        return {
+            lease,
+            storeDir: store.rootDir,
+            ...(pid === undefined ? {} : { pid }),
+            ...(sessionId === undefined ? {} : { sessionId })
+        };
+    }
+    catch (error) {
+        runtimeLog("warn", "claude_hook_lease_unavailable", {
+            conversation_id: conversation.conversation_id,
+            terminal_target: terminalControl.target,
+            reason: error instanceof Error ? error.message : String(error)
+        });
+        return undefined;
+    }
+}
+function withClaudeHookLeaseState(conversation, state) {
+    const nativeTakeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : {};
+    return {
+        ...conversation,
+        native_session_takeover: {
+            ...nativeTakeover,
+            claude_hook_mode: "enabled",
+            claude_hook_store_dir: state.storeDir,
+            claude_hook_lease_id: state.lease.id,
+            terminal_agent_pid: state.pid,
+            terminal_agent_session_id: state.sessionId
+        }
+    };
+}
+function releaseClaudeHookLease(conversation) {
+    const nativeTakeover = isRecord(conversation?.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const leaseId = stringValue(nativeTakeover?.claude_hook_lease_id);
+    if (!leaseId || nativeTakeover?.agent !== "claude") {
+        return;
+    }
+    const storeDir = stringValue(nativeTakeover.claude_hook_store_dir) ?? defaultClaudeHookStoreDir();
+    try {
+        const released = new ClaudeHookStore({ rootDir: storeDir }).releaseLease({ leaseId });
+        runtimeLog("info", "claude_hook_lease_released", {
+            conversation_id: conversation.conversation_id,
+            message_id: released?.messageId,
+            lease_id: leaseId
+        });
+    }
+    catch (error) {
+        runtimeLog("warn", "claude_hook_lease_release_failed", {
+            conversation_id: conversation.conversation_id,
+            lease_id: leaseId,
+            reason: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+function renewClaudeHookLease(conversation, expiresAt) {
+    const nativeTakeover = isRecord(conversation?.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    if (nativeTakeover?.agent !== "claude") {
+        return undefined;
+    }
+    const conversationId = stringValue(conversation.conversation_id);
+    const messageId = stringValue(nativeTakeover.terminal_bridge_message_id);
+    const terminalControl = terminalControlFromTakeover(nativeTakeover);
+    const cwd = stringValue(nativeTakeover.source_cwd) ?? terminalControl?.currentPath;
+    const pid = Number.isInteger(Number(nativeTakeover.terminal_agent_pid))
+        ? Number(nativeTakeover.terminal_agent_pid)
+        : undefined;
+    const sessionId = stringValue(nativeTakeover.terminal_agent_session_id);
+    if (!conversationId || !messageId || !terminalControl || !cwd || (pid === undefined && !sessionId)) {
+        return undefined;
+    }
+    const storeDir = stringValue(nativeTakeover.claude_hook_store_dir) ?? defaultClaudeHookStoreDir();
+    try {
+        return new ClaudeHookStore({ rootDir: storeDir }).activateLease({
+            ...(sessionId === undefined ? {} : { sessionId }),
+            ...(pid === undefined ? {} : { pid }),
+            cwd,
+            conversationId,
+            messageId,
+            terminalTarget: terminalControl.target,
+            expiresAt
+        });
+    }
+    catch (error) {
+        runtimeLog("warn", "claude_hook_lease_renew_failed", {
+            conversation_id: conversationId,
+            message_id: messageId,
+            reason: error instanceof Error ? error.message : String(error)
+        });
+        return undefined;
+    }
+}
+function releaseClaudeHookLeasesForTerminal({ storeDir, terminalControl, replacementConversationId }) {
+    for (const candidate of listConversations(storeDir)) {
+        if (candidate.conversation_id === replacementConversationId) {
+            continue;
+        }
+        const nativeTakeover = isRecord(candidate.native_session_takeover)
+            ? candidate.native_session_takeover
+            : undefined;
+        const candidateControl = terminalControlFromTakeover(nativeTakeover);
+        if (nativeTakeover?.agent === "claude" &&
+            nativeTakeover?.terminal_bridge === true &&
+            candidateControl?.target === terminalControl.target &&
+            candidateControl?.socketPath === terminalControl.socketPath) {
+            releaseClaudeHookLease(candidate);
+        }
+    }
+}
 function uniqueDelegateSessionName(kind) {
     const { sessionPrefix } = executorDefinitionForKind(kind || "claude");
     const timestamp = new Date().toISOString().replace(/\D/g, "").slice(0, 14);
@@ -1535,57 +1840,59 @@ async function buildNativeListGroups({ options, agentFilter, statusFilter }) {
             }
         };
     }
-    if (agentFilter && agentFilter !== "codex") {
+    const registry = createRuntimeTerminalAgentRegistry(options);
+    const adapters = agentFilter
+        ? [registry.get(agentFilter)].filter((adapter) => adapter !== undefined)
+        : registry.list();
+    if (agentFilter && adapters.length === 0) {
         return {
             ...empty,
             summary: {
                 enabled: true,
                 agents: [],
-                skipped: `native active discovery is not implemented for ${agentFilter}`
+                skipped: `terminal agent adapter is not registered for ${agentFilter}`
             }
         };
     }
+    const terminalProvider = createTerminalControlProvider(options);
+    const bridge = new TerminalAgentBridge({ registry, terminalProvider });
+    const terminalScan = options.terminalDebug ? await terminalControlDiagnostics(terminalProvider) : undefined;
+    const terminalControlled = [];
+    const native = [];
+    let activeCount = 0;
+    const errors = [];
     try {
-        const provider = createAgentSessionProvider("codex", options);
-        const terminalProvider = createTerminalControlProvider(options);
-        const terminalScan = options.terminalDebug ? await terminalControlDiagnostics(terminalProvider) : undefined;
-        const activeSessions = await listActiveSessionsWithTerminalControl(provider, options, terminalProvider);
+        const processSource = createTerminalProcessSource(options);
+        const snapshots = await processSource.listProcessSnapshots((snapshot) => adapters.some((adapter) => adapter.capabilities.processDiscovery && adapter.classifyProcess(snapshot) !== undefined));
+        const activeSessions = await bridge.listProcesses(snapshots, adapters.map((adapter) => adapter.agent));
+        activeCount = activeSessions.length;
         const rootSessions = rootActiveProcesses(activeSessions);
-        const terminalControlled = [];
-        const native = [];
         for (const session of rootSessions) {
             if (session.terminalControl) {
-                terminalControlled.push(await terminalControlledListEntry(session, activeSessions, options));
+                terminalControlled.push(await terminalControlledListEntry(session, activeSessions, options, bridge));
             }
             else {
                 native.push(nativeListEntry(session, activeSessions));
             }
         }
-        return {
-            native,
-            terminalControlled,
-            summary: {
-                enabled: true,
-                agents: ["codex"],
-                active_count: activeSessions.length,
-                native_count: native.length,
-                terminal_controlled_count: terminalControlled.length,
-                approval_scan: options.noApprovalScan ? "disabled" : "enabled",
-                terminal_scan: terminalScan
-            }
-        };
     }
     catch (error) {
-        return {
-            native: [],
-            terminalControlled: [],
-            summary: {
-                enabled: true,
-                agents: ["codex"],
-                error: error instanceof Error ? error.message : String(error)
-            }
-        };
+        errors.push(error instanceof Error ? error.message : String(error));
     }
+    return {
+        native,
+        terminalControlled,
+        summary: {
+            enabled: true,
+            agents: adapters.map((adapter) => adapter.agent),
+            active_count: activeCount,
+            native_count: native.length,
+            terminal_controlled_count: terminalControlled.length,
+            approval_scan: options.noApprovalScan ? "disabled" : "enabled",
+            terminal_scan: terminalScan,
+            error: errors.length > 0 ? errors.join("; ") : undefined
+        }
+    };
 }
 async function terminalControlDiagnostics(provider) {
     if (provider instanceof TmuxTerminalControlProvider) {
@@ -1612,9 +1919,9 @@ function delegatedListEntry(task) {
 }
 function nativeListEntry(session, activeSessions) {
     return {
-        id: `native:codex:${session.pid}`,
+        id: `native:${session.agent}:${session.pid}`,
         source: "native_active",
-        agent: "codex",
+        agent: session.agent,
         status: "active",
         pid: session.pid,
         child_pids: childPidsForRoot(session, activeSessions),
@@ -1637,16 +1944,21 @@ function nativeListEntry(session, activeSessions) {
         }
     };
 }
-async function terminalControlledListEntry(session, activeSessions, options) {
+async function terminalControlledListEntry(session, activeSessions, options, bridge = createTerminalAgentBridge(options)) {
     const terminalControl = session.terminalControl;
     if (!terminalControl) {
         throw new Error(`process ${session.pid} is not terminal-controlled`);
     }
-    const terminalState = await listStateForTerminal(terminalControl, options);
+    const terminalState = await listStateForTerminal(session.agent, terminalControl, options, bridge, {
+        pid: session.pid,
+        sessionId: session.sessionId,
+        cwd: session.cwd,
+        terminalTarget: terminalControl.target
+    });
     return {
-        id: `terminal:${terminalControl.kind}:${terminalControl.target}:${session.pid}`,
+        id: bridge.terminalConversationId(session),
         source: "terminal_control",
-        agent: "codex",
+        agent: session.agent,
         status: "active",
         pid: session.pid,
         child_pids: childPidsForRoot(session, activeSessions),
@@ -1663,14 +1975,15 @@ async function terminalControlledListEntry(session, activeSessions, options) {
         activity_reason: terminalState.activity_reason,
         commands: {
             send: true,
-            approve: terminalState.approval_state.approvable === true,
+            approve: terminalControl.capabilities.includes("terminal_approval") &&
+                terminalState.approval_state.approvable === true,
             status: true,
-            cancel: true,
+            cancel: terminalControl.capabilities.includes("terminal_cancel"),
             close: false
         }
     };
 }
-async function listStateForTerminal(terminalControl, options) {
+async function listStateForTerminal(agent, terminalControl, options, bridge = createTerminalAgentBridge(options), runtime) {
     if (options.noApprovalScan) {
         return {
             approval_state: {
@@ -1684,27 +1997,18 @@ async function listStateForTerminal(terminalControl, options) {
         };
     }
     try {
-        const screen = await createTerminalControlProvider(options).capture(terminalControl.target, {
+        const status = await bridge.status(agent, terminalControl, {
             scrollbackLines: Number(options.scrollbackLines ?? 120),
-            socketPath: terminalControl.socketPath
+            runtime
         });
-        const approval = detectCodexApprovalPrompt(screen);
-        const blocked = isCodexApprovalPromptVisible(screen);
-        const activity = detectCodexActivityState(screen, approval);
         return {
             approval_state: {
-                scanned: true,
-                blocked,
-                approvable: approval.approvable,
-                key: approval.approvable ? approval.key : undefined,
-                label: approval.approvable ? approval.label : undefined,
-                prompt_kind: approval.promptKind,
-                command: approval.command,
-                reason: approval.approvable ? undefined : approval.reason,
-                screen_excerpt: blocked ? screenExcerpt(screen, 1000) : undefined
+                ...status.approval_state,
+                screen_excerpt: status.approval_state.blocked ? status.screen.excerpt?.slice(-1000) : undefined
             },
-            activity_state: activity.state,
-            activity_reason: activity.reason
+            activity_state: status.activity_state,
+            activity_reason: status.activity_reason,
+            capability_limitation: status.capability_limitation
         };
     }
     catch (error) {
@@ -1721,11 +2025,13 @@ async function listStateForTerminal(terminalControl, options) {
     }
 }
 function rootActiveProcesses(processes) {
-    const pids = new Set(processes.map((process) => process.pid));
-    const roots = processes.filter((process) => !process.ppid || !pids.has(process.ppid));
+    const pids = new Set(processes.map((process) => `${process.agent}:${process.pid}`));
+    const roots = processes.filter((process) => !process.ppid || !pids.has(`${process.agent}:${process.ppid}`));
     const seenTerminalTargets = new Set();
     return roots.filter((process) => {
-        const terminalTarget = process.terminalControl?.target;
+        const terminalTarget = process.terminalControl?.target
+            ? `${process.agent}:${process.terminalControl.target}`
+            : undefined;
         if (!terminalTarget) {
             return true;
         }
@@ -1738,50 +2044,14 @@ function rootActiveProcesses(processes) {
 }
 function childPidsForRoot(root, processes) {
     return processes
-        .filter((process) => process.ppid === root.pid)
+        .filter((process) => process.agent === root.agent && process.ppid === root.pid)
         .map((process) => process.pid);
 }
 function canSendDelegated(status) {
     return !["failed", "closed", "cancelled"].includes(status);
 }
 async function resolveTerminalConversationFromOptions(options) {
-    const parsed = parseTerminalConversationId(stringValue(options.conversation));
-    if (!parsed) {
-        return undefined;
-    }
-    const provider = createTerminalControlProvider(options);
-    const panes = await provider.listPanes();
-    const pane = panes.find((candidate) => candidate.kind === parsed.kind &&
-        candidate.target === parsed.target);
-    if (!pane) {
-        throw new Error(`terminal-controlled session ${parsed.conversationId} is no longer available`);
-    }
-    return {
-        conversationId: parsed.conversationId,
-        terminalControl: terminalRefFromPane(pane)
-    };
-}
-function parseTerminalConversationId(conversationId) {
-    const prefix = "terminal:tmux:";
-    if (!conversationId?.startsWith(prefix)) {
-        return undefined;
-    }
-    const rest = conversationId.slice(prefix.length);
-    const pidSeparator = rest.lastIndexOf(":");
-    if (pidSeparator <= 0 || pidSeparator === rest.length - 1) {
-        throw new Error(`invalid terminal-controlled conversation id: ${conversationId}`);
-    }
-    const target = rest.slice(0, pidSeparator);
-    const pid = Number(rest.slice(pidSeparator + 1));
-    if (!target || !Number.isInteger(pid)) {
-        throw new Error(`invalid terminal-controlled conversation id: ${conversationId}`);
-    }
-    return {
-        conversationId,
-        kind: "tmux",
-        target,
-        pid
-    };
+    return createTerminalAgentBridge(options).resolveConversationId(stringValue(options.conversation ?? options.conversationId));
 }
 function parseNativeConversationId(conversationId) {
     const prefix = "native:codex:";
@@ -1802,7 +2072,11 @@ async function runStatus(options) {
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const terminalConversation = await resolveTerminalConversationFromOptions(options);
     if (terminalConversation) {
-        const terminalStatus = await terminalStatusForControl(terminalConversation.terminalControl, options);
+        const terminalStatus = await terminalStatusForControl(terminalConversation.agent, terminalConversation.terminalControl, options, {
+            pid: terminalConversation.pid,
+            cwd: terminalConversation.terminalControl.currentPath,
+            terminalTarget: terminalConversation.terminalControl.target
+        });
         printJson({
             conversation_id: terminalConversation.conversationId,
             source: "terminal_control",
@@ -1832,8 +2106,9 @@ async function runStatus(options) {
     }
     const terminalControl = terminalControlFromTakeover(isRecord(conversation.native_session_takeover) ? conversation.native_session_takeover : undefined);
     if (terminalControl) {
+        const executor = executorForConversation(conversation);
         result.terminal_control = terminalControl;
-        result.terminal_status = await terminalStatusForControl(terminalControl, options);
+        result.terminal_status = await terminalStatusForControl(executor.kind, terminalControl, options, terminalRuntimeIdentityForConversation(conversation, terminalControl));
         result.terminal_screen = result.terminal_status.screen;
     }
     printJson(result);
@@ -1851,8 +2126,31 @@ async function runDescribe(options) {
     const conversationId = required(options.conversation ?? options.conversationId, "--conversation is required");
     const terminalConversation = await resolveTerminalConversationFromOptions(options);
     if (terminalConversation) {
-        const terminalStatus = await terminalStatusForControl(terminalConversation.terminalControl, options);
-        const process = await activeCodexProcessForPid(options, parseTerminalConversationId(conversationId)?.pid);
+        const terminalStatus = await terminalStatusForControl(terminalConversation.agent, terminalConversation.terminalControl, options, {
+            pid: terminalConversation.pid,
+            cwd: terminalConversation.terminalControl.currentPath,
+            terminalTarget: terminalConversation.terminalControl.target
+        });
+        if (terminalConversation.agent !== "codex") {
+            const adapter = createRuntimeTerminalAgentRegistry(options).require(terminalConversation.agent);
+            printJson({
+                conversation_id: conversationId,
+                source: "terminal_control",
+                agent: terminalConversation.agent,
+                confidence: terminalStatus.reachable ? "medium" : "low",
+                about: terminalStatus.reachable
+                    ? `${adapter.displayName} is attached through ${terminalConversation.terminalControl.kind}:${terminalConversation.terminalControl.target}.`
+                    : `${adapter.displayName} terminal status is unavailable.`,
+                evidence: {
+                    terminal_status: terminalStatus,
+                    terminal_screen: terminalStatus.screen
+                },
+                limitations: ["Historical session context is not available for this terminal adapter."],
+                terminal_control: terminalConversation.terminalControl
+            });
+            return;
+        }
+        const process = await activeCodexProcessForPid(options, terminalConversation.pid);
         printJson(await describeNativeCodexSession({
             id: conversationId,
             source: "terminal_control",
@@ -1877,7 +2175,9 @@ async function runDescribe(options) {
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
     const events = readExistingEvents(logPath);
     const terminalControl = terminalControlFromTakeover(isRecord(conversation.native_session_takeover) ? conversation.native_session_takeover : undefined);
-    const terminalStatus = terminalControl ? await terminalStatusForControl(terminalControl, options) : undefined;
+    const terminalStatus = terminalControl
+        ? await terminalStatusForControl(executorForConversation(conversation).kind, terminalControl, options, terminalRuntimeIdentityForConversation(conversation, terminalControl))
+        : undefined;
     printJson({
         conversation_id: conversation.conversation_id,
         source: "akk_managed",
@@ -1895,110 +2195,93 @@ async function runDescribe(options) {
         event_log_path: logPath
     });
 }
-async function terminalStatusForControl(terminalControl, options) {
-    try {
-        const screen = await createTerminalControlProvider(options).capture(terminalControl.target, {
-            scrollbackLines: Number(options.scrollbackLines ?? 120),
-            socketPath: terminalControl.socketPath
-        });
-        const approval = detectCodexApprovalPrompt(screen);
-        const blocked = isCodexApprovalPromptVisible(screen);
-        const activity = detectCodexActivityState(screen, approval);
-        return {
-            provider: terminalControl.kind,
-            target: terminalControl.target,
-            reachable: true,
-            activity_state: activity.state,
-            activity_reason: activity.reason,
-            approval_state: {
-                scanned: true,
-                blocked,
-                approvable: approval.approvable,
-                key: approval.approvable ? approval.key : undefined,
-                label: approval.approvable ? approval.label : undefined,
-                prompt_kind: approval.promptKind,
-                command: approval.command,
-                reason: approval.approvable ? undefined : approval.reason
-            },
-            screen: {
-                excerpt: screenExcerpt(screen),
-                approval
-            }
-        };
-    }
-    catch (error) {
-        return {
-            provider: terminalControl.kind,
-            target: terminalControl.target,
-            reachable: false,
-            activity_state: "unknown",
-            activity_reason: error instanceof Error ? error.message : String(error),
-            approval_state: {
-                scanned: false,
-                blocked: false,
-                approvable: false
-            },
-            screen: {
-                error: error instanceof Error ? error.message : String(error)
-            }
-        };
-    }
+async function terminalStatusForControl(agent, terminalControl, options, runtime) {
+    return createTerminalAgentBridge(options).status(agent, terminalControl, {
+        scrollbackLines: Number(options.scrollbackLines ?? 120),
+        runtime
+    });
 }
 function terminalBridgeApprovalFingerprint({ terminalControl, terminalStatus }) {
     const approval = isRecord(terminalStatus?.approval_state) ? terminalStatus.approval_state : {};
+    const adapterFingerprint = stringValue(approval.fingerprint);
+    if (adapterFingerprint) {
+        return adapterFingerprint;
+    }
     const screen = isRecord(terminalStatus?.screen) ? terminalStatus.screen : {};
     return createHash("sha256")
         .update(JSON.stringify({
         target: terminalControl.target,
-        key: approval.key,
+        keys: approval.keys ?? (approval.key ? [approval.key] : undefined),
         label: approval.label,
         prompt_kind: approval.prompt_kind,
         command: approval.command,
+        tool_name: approval.tool_name,
+        request_detail: approval.request_detail,
         excerpt: screen.excerpt
     }))
-        .digest("hex")
-        .slice(0, 16);
+        .digest("hex");
 }
-function terminalBridgeApprovalFingerprintForScreen({ terminalControl, screen, approval }) {
-    return terminalBridgeApprovalFingerprint({
-        terminalControl,
-        terminalStatus: {
-            approval_state: {
-                key: approval.key,
-                label: approval.label,
-                prompt_kind: approval.promptKind,
-                command: approval.command
-            },
-            screen: {
-                excerpt: screenExcerpt(screen)
-            }
-        }
-    });
+function assertSafeClaudeTerminalSend(terminalStatus) {
+    const approval = isRecord(terminalStatus?.approval_state)
+        ? terminalStatus.approval_state
+        : undefined;
+    if (terminalStatus?.reachable !== true) {
+        throw new Error("Claude Code terminal status is unavailable");
+    }
+    if (approval?.blocked === true) {
+        throw new Error(stringValue(approval.reason) ?? "Claude Code is waiting at a permission dialog");
+    }
+    if (terminalStatus.activity_state !== "idle") {
+        throw new Error(`Claude Code terminal is ${stringValue(terminalStatus.activity_state) ?? "unknown"}, not idle`);
+    }
 }
 function terminalBridgeApprovalInstructions({ conversation, terminalControl, terminalStatus }) {
     const approval = isRecord(terminalStatus?.approval_state) ? terminalStatus.approval_state : {};
     const screen = isRecord(terminalStatus?.screen) ? terminalStatus.screen : {};
-    const label = stringValue(approval.label) || "the current Codex approval prompt";
-    const key = stringValue(approval.key) || "the detected approve key";
+    const executor = executorForConversation(conversation);
+    const agentName = executorDefinitionForKind(executor.kind).displayName;
+    const label = stringValue(approval.label) || `the current ${agentName} approval prompt`;
+    const keys = Array.isArray(approval.keys)
+        ? approval.keys.filter((value) => typeof value === "string")
+        : [];
+    const decisionMode = stringValue(approval.decision_mode);
+    const keyDescription = decisionMode === "structured"
+        ? "structured one-time Hook decision"
+        : keys.length > 0
+            ? keys.join(" then ")
+            : stringValue(approval.key) || "the detected approve key sequence";
+    const fingerprint = stringValue(approval.fingerprint);
+    const promptKind = stringValue(approval.prompt_kind);
+    const command = stringValue(approval.command);
+    const toolName = stringValue(approval.tool_name);
+    const requestDetail = stringValue(approval.request_detail);
+    const requestId = stringValue(approval.request_id);
     const excerpt = stringValue(screen.excerpt) || "(No terminal excerpt was available.)";
     return [
-        "Codex is waiting for approval in a terminal-controlled AKK session.",
+        `${agentName} is waiting for approval in a terminal-controlled AKK session.`,
         "",
         `Conversation: ${conversation.conversation_id}`,
         `Terminal: ${terminalControl.kind}:${terminalControl.target}`,
-        `Approval option: ${label} (${key})`,
+        `Approval option: ${label} (${keyDescription})`,
+        promptKind ? `Request kind: ${promptKind}` : undefined,
+        toolName ? `Tool: ${toolName}` : undefined,
+        requestDetail ? `Request: ${requestDetail}` : undefined,
+        command ? `Command: ${command}` : undefined,
+        requestId ? `Structured request id: ${requestId}` : undefined,
         "",
         "Safe terminal excerpt:",
         "```text",
         excerpt,
         "```",
         "",
-        "Ask the user whether to approve or deny this Codex request.",
+        `Ask the user whether to approve or deny this ${agentName} request.`,
         "",
         "If the user approves, call `agent_knock_knock_approve` with:",
         `- conversation_id: ${conversation.conversation_id}`,
+        `- expected_approval_fingerprint: ${fingerprint ?? "(missing; refresh status before approval)"}`,
         "",
-        "Equivalent user command: `AKK approve " + conversation.conversation_id + "`",
+        "Equivalent user command: `AKK approve " + conversation.conversation_id +
+            (fingerprint ? ` --expected-approval-fingerprint ${fingerprint}` : "") + "`",
         "",
         "If the user denies or wants to stop this request, call `agent_knock_knock_cancel` with:",
         `- conversation_id: ${conversation.conversation_id}`,
@@ -2006,7 +2289,7 @@ function terminalBridgeApprovalInstructions({ conversation, terminalControl, ter
         "Equivalent user command: `AKK cancel " + conversation.conversation_id + "`",
         "",
         "Do not use raw tmux, shell, or manual key presses for this approval. Do not approve without explicit user confirmation."
-    ].join("\n");
+    ].filter((line) => line !== undefined).join("\n");
 }
 function recordTerminalBridgeApprovalNotification({ statePath, logPath, terminalControl, terminalStatus, fingerprint }) {
     const releaseLock = acquireFileLock(`${statePath}.lock`);
@@ -2068,6 +2351,8 @@ async function runSend(options) {
             const managed = createManagedTerminalConversationFromRawId({
                 options,
                 conversationId: terminalConversation.conversationId,
+                agent: terminalConversation.agent,
+                pid: terminalConversation.pid,
                 messageBody,
                 terminalControl: terminalConversation.terminalControl
             });
@@ -2087,6 +2372,8 @@ async function runSend(options) {
         await runTerminalConversationSend({
             options,
             conversationId: terminalConversation.conversationId,
+            agent: terminalConversation.agent,
+            pid: terminalConversation.pid,
             messageBody,
             terminalControl: terminalConversation.terminalControl
         });
@@ -2450,7 +2737,9 @@ async function runApprove(options) {
         await runTerminalConversationApprove({
             options,
             conversationId: terminalConversation.conversationId,
-            terminalControl: terminalConversation.terminalControl
+            agent: terminalConversation.agent,
+            terminalControl: terminalConversation.terminalControl,
+            pid: terminalConversation.pid
         });
         return;
     }
@@ -2462,36 +2751,32 @@ async function runApprove(options) {
     if (!terminalControl) {
         throw new Error(`conversation ${conversation.conversation_id} is not controlled through a terminal`);
     }
-    const provider = createTerminalControlProvider(options);
-    const screen = await provider.capture(terminalControl.target, {
-        scrollbackLines: Number(options.scrollbackLines ?? 120),
-        socketPath: terminalControl.socketPath
-    });
-    const approval = detectCodexApprovalPrompt(screen);
-    if (!approval.approvable) {
-        printJson({
-            conversation,
-            approved: false,
-            blocked: true,
-            reason: approval.reason,
-            terminal_control: terminalControl,
-            screen_excerpt: screenExcerpt(screen)
-        });
-        return;
-    }
-    const expectedFingerprint = stringValue(options.expectedApprovalFingerprint);
-    const actualFingerprint = terminalBridgeApprovalFingerprintForScreen({ terminalControl, screen, approval });
+    const executor = executorForConversation(conversation);
+    const monitoredApproval = isRecord(nativeTakeover?.["terminal_bridge_approval"])
+        ? nativeTakeover.terminal_bridge_approval
+        : undefined;
+    const expectedFingerprint = stringValue(options.expectedApprovalFingerprint) ??
+        stringValue(monitoredApproval?.fingerprint);
     const autoApproved = options.autoApproved === true;
     const policyRuleId = stringValue(options.policyRuleId);
     const policyFingerprint = stringValue(options.policyFingerprint);
-    if (expectedFingerprint && actualFingerprint !== expectedFingerprint) {
+    const approval = await createTerminalAgentBridge(options).approve(executor.kind, terminalControl, {
+        expectedFingerprint,
+        scrollbackLines: Number(options.scrollbackLines ?? 120),
+        runtime: terminalRuntimeIdentityForConversation(conversation, terminalControl),
+        requiredDecisionMode: autoApproved && executor.kind === "claude"
+            ? "structured"
+            : undefined
+    });
+    const actualFingerprint = approval.fingerprint;
+    if (!approval.approved) {
         if (autoApproved) {
             appendEvent(logPath, {
                 ts: new Date().toISOString(),
                 conversation_id: conversation.conversation_id,
                 event: "terminal_auto_approval_decision",
                 action: "rejected",
-                reason: "approval fingerprint changed before execution",
+                reason: approval.reason,
                 terminal_control: terminalControl,
                 expected_fingerprint: expectedFingerprint,
                 actual_fingerprint: actualFingerprint,
@@ -2502,25 +2787,25 @@ async function runApprove(options) {
         printJson({
             conversation,
             approved: false,
-            blocked: true,
-            reason: "approval fingerprint changed before execution",
+            blocked: approval.blocked,
+            reason: approval.reason,
             terminal_control: terminalControl,
             expected_approval_fingerprint: expectedFingerprint,
             actual_approval_fingerprint: actualFingerprint,
-            screen_excerpt: screenExcerpt(screen)
+            screen_excerpt: approval.screenExcerpt
         });
         return;
     }
-    await provider.sendKeys(terminalControl.target, [approval.key], {
-        socketPath: terminalControl.socketPath
-    });
     appendEvent(logPath, {
         ts: new Date().toISOString(),
         conversation_id: conversation.conversation_id,
         event: "terminal_approval_send",
         terminal_control: terminalControl,
         key: approval.key,
+        keys: approval.keys,
         label: approval.label,
+        decision_mode: approval.decisionMode,
+        request_id: approval.requestId,
         approval_fingerprint: actualFingerprint,
         auto_approved: autoApproved,
         policy_rule_id: policyRuleId,
@@ -2542,7 +2827,10 @@ async function runApprove(options) {
         conversation_id: conversation.conversation_id,
         terminal_target: terminalControl.target,
         key: approval.key,
+        keys: approval.keys,
         label: approval.label,
+        decision_mode: approval.decisionMode,
+        request_id: approval.requestId,
         approval_fingerprint: actualFingerprint,
         auto_approved: autoApproved,
         policy_rule_id: policyRuleId,
@@ -2571,12 +2859,28 @@ async function runApprove(options) {
         terminal_bridge_hard_deadline_at: deadlineAt(stringValue(nativeTakeoverForUpdate.terminal_bridge_started_at) ?? approvalResolvedAt, agentHardTimeoutMinutes)
     };
     delete nextNativeTakeover.terminal_bridge_approval;
-    const nextConversation = {
+    let nextConversation = {
         ...conversation,
         status: terminalBridgeEnabled(conversation) ? "waiting_for_agent" : conversation.status,
         native_session_takeover: nextNativeTakeover,
         updated_at: approvalResolvedAt
     };
+    const approvalLeaseDeadlines = [
+        stringValue(nextNativeTakeover.terminal_bridge_inactivity_deadline_at),
+        stringValue(nextNativeTakeover.terminal_bridge_hard_deadline_at)
+    ].filter((value) => Boolean(value));
+    if (approvalLeaseDeadlines.length > 0) {
+        const renewedLease = renewClaudeHookLease(nextConversation, new Date(Math.min(...approvalLeaseDeadlines.map((value) => Date.parse(value)))).toISOString());
+        if (renewedLease) {
+            nextConversation = {
+                ...nextConversation,
+                native_session_takeover: {
+                    ...nextNativeTakeover,
+                    claude_hook_lease_id: renewedLease.id
+                }
+            };
+        }
+    }
     saveState(statePath, nextConversation);
     const bridgeMonitor = startTerminalBridgeMonitorForConversation({
         conversation: nextConversation,
@@ -2607,40 +2911,47 @@ async function runApprove(options) {
         approved: true,
         terminal_control: terminalControl,
         key: approval.key,
+        keys: approval.keys,
         label: approval.label,
+        decision_mode: approval.decisionMode,
+        request_id: approval.requestId,
         approval_fingerprint: actualFingerprint,
         auto_approved: autoApproved,
         policy_rule_id: policyRuleId,
         monitor_pid: bridgeMonitor?.pid ?? null
     });
 }
-async function runTerminalConversationApprove({ options, conversationId, terminalControl }) {
-    const provider = createTerminalControlProvider(options);
-    const screen = await provider.capture(terminalControl.target, {
+async function runTerminalConversationApprove({ options, conversationId, agent, terminalControl, pid }) {
+    const approval = await createTerminalAgentBridge(options).approve(agent, terminalControl, {
+        expectedFingerprint: stringValue(options.expectedApprovalFingerprint),
         scrollbackLines: Number(options.scrollbackLines ?? 120),
-        socketPath: terminalControl.socketPath
+        runtime: {
+            pid,
+            cwd: terminalControl.currentPath,
+            terminalTarget: terminalControl.target
+        }
     });
-    const approval = detectCodexApprovalPrompt(screen);
-    if (!approval.approvable) {
+    if (!approval.approved) {
         printJson({
             conversation_id: conversationId,
             source: "terminal_control",
             approved: false,
-            blocked: true,
+            blocked: approval.blocked,
             reason: approval.reason,
             terminal_control: terminalControl,
-            screen_excerpt: screenExcerpt(screen)
+            screen_excerpt: approval.screenExcerpt
         });
         return;
     }
-    await provider.sendKeys(terminalControl.target, [approval.key], {
-        socketPath: terminalControl.socketPath
-    });
     runtimeLog("info", "terminal_approval_send", {
         conversation_id: conversationId,
+        agent,
         terminal_target: terminalControl.target,
         key: approval.key,
-        label: approval.label
+        keys: approval.keys,
+        label: approval.label,
+        decision_mode: approval.decisionMode,
+        request_id: approval.requestId
     });
     printJson({
         conversation_id: conversationId,
@@ -2648,20 +2959,31 @@ async function runTerminalConversationApprove({ options, conversationId, termina
         approved: true,
         terminal_control: terminalControl,
         key: approval.key,
-        label: approval.label
+        keys: approval.keys,
+        label: approval.label,
+        approval_fingerprint: approval.fingerprint,
+        decision_mode: approval.decisionMode,
+        request_id: approval.requestId
     });
 }
-async function runTerminalConversationSend({ options, conversationId, messageBody, terminalControl }) {
-    const provider = createTerminalControlProvider(options);
+async function runTerminalConversationSend({ options, conversationId, agent, pid, messageBody, terminalControl }) {
     const terminalPayload = terminalSubmissionPayload(String(messageBody));
-    await provider.sendText(terminalControl.target, terminalPayload, {
-        socketPath: terminalControl.socketPath
-    });
-    await provider.sendKeys(terminalControl.target, ["C-m"], {
-        socketPath: terminalControl.socketPath
-    });
+    const terminalBridge = createTerminalAgentBridge(options);
+    if (agent === "claude") {
+        const status = await terminalBridge.status(agent, terminalControl, {
+            scrollbackLines: Number(options.scrollbackLines ?? 120),
+            runtime: {
+                pid,
+                cwd: terminalControl.currentPath,
+                terminalTarget: terminalControl.target
+            }
+        });
+        assertSafeClaudeTerminalSend(status);
+    }
+    await terminalBridge.send(agent, terminalControl, terminalPayload);
     runtimeLog("info", "terminal_message_send", {
         conversation_id: conversationId,
+        agent,
         terminal_target: terminalControl.target,
         message: textSummary(messageBody)
     });
@@ -2705,7 +3027,7 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
             releaseTerminalLock();
         }
     }
-    const provider = createTerminalControlProvider(options);
+    const terminalBridge = createTerminalAgentBridge(options);
     const bridgeStartedAt = new Date().toISOString();
     const agentTimeoutMinutes = Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES);
     const agentHardTimeoutMinutes = positiveMinutes(options.agentHardTimeoutMinutes ?? DEFAULT_AGENT_HARD_TIMEOUT_MINUTES, "--agent-hard-timeout-minutes");
@@ -2719,25 +3041,60 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
             forkTakeover: undefined
         }))
         : terminalSubmissionPayload(String(message.body ?? ""));
+    const preSendRuntime = {
+        ...terminalRuntimeIdentityForConversation(nextConversation, terminalControl),
+        messageId: message.id
+    };
     let preSendScreenFingerprint;
     if (bridge) {
         try {
-            const screen = await provider.capture(terminalControl.target, {
+            const status = await terminalBridge.status(executor.kind, terminalControl, {
                 scrollbackLines: Number(options.scrollbackLines ?? 120),
-                socketPath: terminalControl.socketPath
+                runtime: preSendRuntime
             });
-            preSendScreenFingerprint = terminalBridgeScreenFingerprint(screenExcerpt(screen));
+            if (executor.kind === "claude") {
+                assertSafeClaudeTerminalSend(status);
+            }
+            preSendScreenFingerprint = terminalBridgeScreenFingerprint(status.screen.excerpt);
         }
-        catch {
-            // Delivery can still succeed when capture is unavailable; prompt matching remains the fallback boundary.
+        catch (error) {
+            if (executor.kind === "claude") {
+                throw new Error(`refusing to send to Claude Code without a verified idle terminal: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Codex delivery can still use its established fallback when capture is unavailable.
         }
     }
-    await provider.sendText(terminalControl.target, terminalPayload, {
-        socketPath: terminalControl.socketPath
-    });
-    await provider.sendKeys(terminalControl.target, ["C-m"], {
-        socketPath: terminalControl.socketPath
-    });
+    if (bridge && executor.kind === "claude") {
+        releaseClaudeHookLeasesForTerminal({
+            storeDir: storeDirFromOptions(options),
+            terminalControl,
+            replacementConversationId: conversation.conversation_id
+        });
+        releaseClaudeHookLease(nextConversation);
+    }
+    const claudeHookLeaseState = bridge && executor.kind === "claude"
+        ? activateClaudeHookLease({
+            options,
+            conversation: nextConversation,
+            message,
+            terminalControl,
+            expiresAt: deadlineAt(bridgeStartedAt, agentTimeoutMinutes > 0
+                ? Math.min(agentTimeoutMinutes, agentHardTimeoutMinutes)
+                : agentHardTimeoutMinutes)
+        })
+        : undefined;
+    const conversationWithHookLease = claudeHookLeaseState
+        ? withClaudeHookLeaseState(nextConversation, claudeHookLeaseState)
+        : nextConversation;
+    try {
+        await terminalBridge.send(executor.kind, terminalControl, terminalPayload);
+    }
+    catch (error) {
+        if (claudeHookLeaseState) {
+            releaseClaudeHookLease(conversationWithHookLease);
+        }
+        throw error;
+    }
     const supersededConversationIds = bridge
         ? supersedeTerminalBridgeConversations({
             storeDir: storeDirFromOptions(options),
@@ -2765,7 +3122,7 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
     });
     const bridgeConversation = bridge
         ? withTerminalBridgeState({
-            conversation: nextConversation,
+            conversation: conversationWithHookLease,
             message,
             startedAt: bridgeStartedAt,
             agentTimeoutMinutes,
@@ -2827,12 +3184,12 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
 function terminalSubmissionPayload(payload) {
     return payload.replace(/[\r\n]+$/u, "");
 }
-function createManagedTerminalConversationFromRawId({ options, conversationId, messageBody, terminalControl }) {
+function createManagedTerminalConversationFromRawId({ options, conversationId, agent, pid, messageBody, terminalControl }) {
     const workspace = terminalControl.currentPath ?? process.cwd();
     const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
     cleanupIdleConversations(storeDir, options);
     const executor = resolveExecutor({
-        kind: "codex",
+        kind: agent,
         session: conversationId
     });
     const now = new Date();
@@ -2858,6 +3215,9 @@ function createManagedTerminalConversationFromRawId({ options, conversationId, m
             gatewaySession: options.gatewaySession,
             openclawBin: options.openclawBin ?? resolveOptionalExecutable("openclaw")
         });
+    const claudeAgent = agent === "claude"
+        ? loadClaudeAgentRows(options).find((row) => row.pid === pid)
+        : undefined;
     const attachedConversation = withStoragePaths({
         ...conversation,
         executor,
@@ -2870,12 +3230,14 @@ function createManagedTerminalConversationFromRawId({ options, conversationId, m
         gateway_session: options.gatewaySession ?? options.openclawSession ?? "agent:main:main",
         openclaw_bin: options.openclawBin ?? resolveOptionalExecutable("openclaw"),
         executor_all_proxy: proxyForExecutor(executor, options),
-        executor_model: options.model ?? options.codexModel,
+        executor_model: options.model ?? (agent === "codex" ? options.codexModel : undefined),
         native_session_takeover: {
-            agent: "codex",
+            agent,
             native_session_id: conversationId,
+            terminal_agent_pid: pid,
+            terminal_agent_session_id: claudeAgent?.sessionId,
             source_cwd: workspace,
-            source_title: `Terminal-controlled Codex ${terminalControl.target}`,
+            source_title: `Terminal-controlled ${executor.display_name} ${terminalControl.target}`,
             strategy: "terminal_control",
             attached_at: now.toISOString(),
             takeover_match_kind: "raw_terminal_send",
@@ -2890,7 +3252,7 @@ function createManagedTerminalConversationFromRawId({ options, conversationId, m
         conversation_id: attachedConversation.conversation_id,
         event: "raw_terminal_session_attached",
         source_conversation_id: conversationId,
-        agent: "codex",
+        agent,
         terminal_control: terminalControl,
         executor
     });
@@ -2978,14 +3340,16 @@ function supersedeTerminalBridgeConversations({ storeDir, terminalControl, repla
                 continue;
             }
             const now = new Date().toISOString();
-            saveState(candidateStatePath, {
+            const closedConversation = {
                 ...current,
                 status: "closed",
                 closed_at: now,
                 close_reason: "terminal bridge superseded by a newer task on the same terminal",
                 superseded_by_conversation_id: replacementConversationId,
                 updated_at: now
-            });
+            };
+            saveState(candidateStatePath, closedConversation);
+            releaseClaudeHookLease(closedConversation);
             appendEvent(logPathForStatePath(candidateStatePath), {
                 ts: now,
                 conversation_id: current.conversation_id,
@@ -3415,17 +3779,37 @@ async function runRenew(options) {
         throw new Error(`cannot renew ${conversation.conversation_id}; terminal bridge hard lifetime of ${hardTimeoutMinutes} minutes has elapsed`);
     }
     const now = new Date().toISOString();
+    const currentMessageId = stringValue(nativeTakeover?.terminal_bridge_message_id);
+    const hardDeadline = deadlineAt(startedAt ?? now, hardTimeoutMinutes) ??
+        new Date(Date.now() + hardTimeoutMinutes * 60 * 1000).toISOString();
+    const inactivityDeadline = deadlineAt(now, inactivityTimeoutMinutes) ??
+        new Date(Date.now() + inactivityTimeoutMinutes * 60 * 1000).toISOString();
+    const renewedLease = executorForConversation(conversation).kind === "claude" && currentMessageId
+        ? activateClaudeHookLease({
+            options,
+            conversation,
+            message: { id: currentMessageId },
+            terminalControl,
+            expiresAt: new Date(Math.min(Date.parse(hardDeadline), Date.parse(inactivityDeadline))).toISOString()
+        })
+        : undefined;
+    const renewedBase = renewedLease
+        ? withClaudeHookLeaseState(conversation, renewedLease)
+        : conversation;
+    const renewedNativeTakeover = isRecord(renewedBase.native_session_takeover)
+        ? renewedBase.native_session_takeover
+        : nativeTakeover;
     const renewed = {
-        ...conversation,
+        ...renewedBase,
         status: "waiting_for_agent",
         native_session_takeover: {
-            ...nativeTakeover,
+            ...renewedNativeTakeover,
             terminal_bridge_monitor_started_at: now,
             terminal_bridge_last_activity_at: now,
             terminal_bridge_inactivity_timeout_minutes: inactivityTimeoutMinutes,
             terminal_bridge_hard_timeout_minutes: hardTimeoutMinutes,
-            terminal_bridge_inactivity_deadline_at: deadlineAt(now, inactivityTimeoutMinutes),
-            terminal_bridge_hard_deadline_at: deadlineAt(startedAt ?? now, hardTimeoutMinutes),
+            terminal_bridge_inactivity_deadline_at: inactivityDeadline,
+            terminal_bridge_hard_deadline_at: hardDeadline,
             terminal_bridge_renewed_at: now
         },
         updated_at: now
@@ -3496,7 +3880,9 @@ async function runCancel(options) {
         await runTerminalConversationCancel({
             options,
             conversationId: terminalConversation.conversationId,
-            terminalControl: terminalConversation.terminalControl
+            agent: terminalConversation.agent,
+            terminalControl: terminalConversation.terminalControl,
+            pid: terminalConversation.pid
         });
         return;
     }
@@ -3514,6 +3900,7 @@ async function runCancel(options) {
             conversation,
             statePath,
             logPath,
+            agent: executorForConversation(conversation).kind,
             terminalControl
         });
         return;
@@ -3576,53 +3963,90 @@ async function runCancel(options) {
         budget: budgetAction(nextConversation)
     });
 }
-async function runTerminalConversationCancel({ options, conversationId, terminalControl }) {
-    const provider = createTerminalControlProvider(options);
-    await provider.sendKeys(terminalControl.target, ["C-c"], {
-        socketPath: terminalControl.socketPath
+async function runTerminalConversationCancel({ options, conversationId, agent, terminalControl, pid }) {
+    const cancellation = await createTerminalAgentBridge(options).cancel(agent, terminalControl, {
+        runtime: {
+            pid,
+            cwd: terminalControl.currentPath,
+            terminalTarget: terminalControl.target
+        },
+        scrollbackLines: Number(options.scrollbackLines ?? 120)
     });
     runtimeLog("info", "terminal_cancel_requested", {
         conversation_id: conversationId,
+        agent,
         terminal_target: terminalControl.target,
-        key: "C-c"
+        key: cancellation.key,
+        keys: cancellation.keys,
+        denied_approval: cancellation.deniedApproval,
+        request_id: cancellation.requestId,
+        cancel_requested: cancellation.cancelRequested,
+        reason: cancellation.reason
     });
     printJson({
         conversation_id: conversationId,
         source: "terminal_control",
-        cancel_requested: true,
+        cancel_requested: cancellation.cancelRequested,
+        reason: cancellation.reason,
         terminal_control: terminalControl,
-        key: "C-c"
+        key: cancellation.key,
+        keys: cancellation.keys,
+        denied_approval: cancellation.deniedApproval,
+        request_id: cancellation.requestId
     });
 }
-async function runTerminalControlCancel({ options, conversation, statePath, logPath, terminalControl }) {
-    const provider = createTerminalControlProvider(options);
-    await provider.sendKeys(terminalControl.target, ["C-c"], {
-        socketPath: terminalControl.socketPath
+async function runTerminalControlCancel({ options, conversation, statePath, logPath, agent, terminalControl }) {
+    const cancellation = await createTerminalAgentBridge(options).cancel(agent, terminalControl, {
+        runtime: terminalRuntimeIdentityForConversation(conversation, terminalControl),
+        scrollbackLines: Number(options.scrollbackLines ?? 120)
     });
+    if (!cancellation.cancelRequested) {
+        printJson({
+            conversation,
+            cancel_requested: false,
+            reason: cancellation.reason,
+            terminal_control: terminalControl,
+            budget: budgetAction(conversation)
+        });
+        return;
+    }
     const now = new Date().toISOString();
     appendEvent(logPath, {
         ts: now,
         conversation_id: conversation.conversation_id,
         event: "terminal_cancel_requested",
         terminal_control: terminalControl,
-        key: "C-c"
+        key: cancellation.key,
+        keys: cancellation.keys,
+        denied_approval: cancellation.deniedApproval,
+        request_id: cancellation.requestId
     });
     runtimeLog("info", "terminal_cancel_requested", {
         conversation_id: conversation.conversation_id,
+        agent,
         terminal_target: terminalControl.target,
-        key: "C-c"
+        key: cancellation.key,
+        keys: cancellation.keys,
+        denied_approval: cancellation.deniedApproval,
+        request_id: cancellation.requestId
     });
     const nextConversation = {
         ...conversation,
+        status: "cancelled",
+        cancelled_at: now,
         terminal_cancel_requested_at: now,
         updated_at: now
     };
     saveState(statePath, nextConversation);
+    releaseClaudeHookLease(nextConversation);
     printJson({
         conversation: nextConversation,
         cancel_requested: true,
         terminal_control: terminalControl,
-        key: "C-c",
+        key: cancellation.key,
+        keys: cancellation.keys,
+        denied_approval: cancellation.deniedApproval,
+        request_id: cancellation.requestId,
         budget: budgetAction(nextConversation)
     });
 }
@@ -3804,6 +4228,7 @@ function runClose(options) {
         updated_at: now
     };
     saveState(statePath, closed);
+    releaseClaudeHookLease(closed);
     appendEvent(logPath, {
         ts: now,
         conversation_id: conversation.conversation_id,
@@ -3824,6 +4249,9 @@ function runClose(options) {
     });
 }
 async function runMonitor(options) {
+    if (options.callbackRetry) {
+        return runCallbackRetryMonitor(options);
+    }
     if (options.terminalBridge) {
         return await runTerminalBridgeMonitor(options);
     }
@@ -3955,6 +4383,72 @@ async function runMonitor(options) {
         sleepSync(pollIntervalMs);
     }
 }
+function startCallbackRetryMonitor({ statePath }) {
+    const child = spawn(process.execPath, [
+        new URL(import.meta.url).pathname,
+        "monitor",
+        "--callback-retry",
+        "--state",
+        statePath
+    ], {
+        detached: true,
+        stdio: "ignore",
+        cwd: process.cwd(),
+        env: process.env
+    });
+    child.unref();
+    return child;
+}
+function runCallbackRetryMonitor(options) {
+    const statePath = expandHome(required(options.state, "--state is required"));
+    while (true) {
+        const conversation = loadState(statePath);
+        const callbackDelivery = isRecord(conversation.callback_delivery)
+            ? conversation.callback_delivery
+            : undefined;
+        const attempts = Number(callbackDelivery?.attempts ?? 0);
+        if (conversation.status !== "callback_failed" || !isRecord(callbackDelivery?.message)) {
+            return;
+        }
+        if (attempts > CALLBACK_RETRY_DELAYS_MS.length) {
+            return;
+        }
+        const delayMs = CALLBACK_RETRY_DELAYS_MS[Math.max(0, attempts - 1)];
+        sleepSync(delayMs);
+        const releaseLock = acquireFileLock(`${statePath}.lock`);
+        try {
+            const current = loadState(statePath);
+            const currentDelivery = isRecord(current.callback_delivery)
+                ? current.callback_delivery
+                : undefined;
+            if (current.status !== "callback_failed" || !isRecord(currentDelivery?.message)) {
+                return;
+            }
+            try {
+                runLockedCallback({
+                    statePath,
+                    messageJson: JSON.stringify(currentDelivery.message),
+                    gatewayMethod: stringValue(currentDelivery.gateway_method) ?? current.gateway_method,
+                    gatewaySession: stringValue(currentDelivery.gateway_session) ?? current.gateway_session,
+                    openclawSession: current.openclaw_session,
+                    openclawBin: stringValue(currentDelivery.openclaw_bin) ?? current.openclaw_bin,
+                    gatewayUrl: stringValue(currentDelivery.gateway_url) ?? current.gateway_url,
+                    token: current.gateway_token,
+                    closeTerminalBridgeOnDone: currentDelivery.close_terminal_bridge_on_done === true,
+                    retryPending: true,
+                    disableCallbackRetry: true
+                });
+                return;
+            }
+            catch {
+                // The failed attempt is persisted by runLockedCallback; continue with bounded backoff.
+            }
+        }
+        finally {
+            releaseLock();
+        }
+    }
+}
 async function runTerminalBridgeMonitor(options) {
     const statePath = expandHome(required(options.state, "--state is required"));
     const logPath = expandHome(options.log ?? logPathForStatePath(statePath));
@@ -3977,9 +4471,10 @@ async function runTerminalBridgeMonitor(options) {
     const activityPersistIntervalMs = terminalBridgeActivityPersistIntervalMs(timeoutMinutes, pollIntervalMs);
     const preSendScreenFingerprint = stringValue(initialNativeTakeover?.["terminal_bridge_pre_send_screen_fingerprint"]);
     let previousScreenFingerprint = preSendScreenFingerprint;
-    let previousRolloutFingerprint;
+    let previousDurableFingerprint;
     let persistedActivityReason = stringValue(initialNativeTakeover?.["terminal_bridge_last_activity_reason"]);
     const executor = executorForConversation(conversation);
+    const terminalBridge = createTerminalAgentBridge(options);
     appendEvent(logPath, {
         ts: new Date().toISOString(),
         conversation_id: conversation.conversation_id,
@@ -4062,8 +4557,126 @@ async function runTerminalBridgeMonitor(options) {
             });
             return;
         }
-        const terminalStatus = await terminalStatusForControl(terminalControl, options);
+        const requestText = String(nativeTakeover?.["terminal_bridge_request_text"] ?? conversation.user_request ?? "");
+        const startedAt = stringValue(nativeTakeover?.["terminal_bridge_started_at"]);
+        const terminalRuntime = terminalRuntimeIdentityForConversation(conversation, terminalControl);
+        const screenChangedSinceSend = preSendScreenFingerprint !== undefined &&
+            previousScreenFingerprint !== undefined &&
+            previousScreenFingerprint !== preSendScreenFingerprint;
+        const poll = await terminalBridge.monitorPoll({
+            agent: executor.kind,
+            terminalControl,
+            screenOptions: {
+                scrollbackLines: Number(options.scrollbackLines ?? 120),
+                requestText,
+                screenChangedSinceSend,
+                runtime: terminalRuntime
+            },
+            durableRequest: {
+                sessionId: terminalRuntime.sessionId,
+                cwd: stringValue(nativeTakeover?.["source_cwd"]),
+                requestText,
+                requestHash: stringValue(nativeTakeover?.["terminal_bridge_request_hash"]),
+                startedAt,
+                context: {
+                    conversation,
+                    nativeTakeover,
+                    ...terminalRuntime
+                }
+            }
+        });
+        const terminalStatus = poll.status;
         const approval = terminalStatus.approval_state;
+        if (isRecord(approval) && approval.blocked === true && approval.approvable !== true) {
+            const approvalReason = stringValue(approval.reason) ??
+                "Claude Code permission state cannot be safely resolved through AKK";
+            appendEvent(logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: conversation.conversation_id,
+                event: "terminal_bridge_approval_not_approvable",
+                terminal_control: terminalControl,
+                activity_state: terminalStatus.activity_state,
+                reason: approvalReason
+            });
+            if (/waiting for hook consumption/iu.test(approvalReason)) {
+                sleepSync(pollIntervalMs);
+                continue;
+            }
+            const fingerprint = terminalBridgeApprovalFingerprint({ terminalControl, terminalStatus });
+            const notification = recordTerminalBridgeApprovalNotification({
+                statePath,
+                logPath,
+                terminalControl,
+                terminalStatus,
+                fingerprint
+            });
+            if (notification.duplicate) {
+                printJson({
+                    conversation: notification.conversation,
+                    monitored: true,
+                    terminal_bridge: true,
+                    awaiting_approval: true,
+                    approvable: false,
+                    duplicate: true,
+                    reason: approvalReason,
+                    terminal_control: terminalControl,
+                    terminal_status: terminalStatus
+                });
+                return;
+            }
+            const callbackMessage = createMessage({
+                conversation: notification.conversation,
+                from: executor.actor,
+                to: "openclaw",
+                type: "blocked",
+                requiresResponse: true,
+                body: [
+                    `${executor.display_name} is waiting at a permission state that AKK cannot safely approve.`,
+                    approvalReason,
+                    "",
+                    `Conversation: ${notification.conversation.conversation_id}`,
+                    `Terminal: ${terminalControl.target}`,
+                    "Review and resolve this dialog in the terminal manually. AKK intentionally sends no key when the request identity cannot be revalidated."
+                ].join("\n"),
+                metadata: {
+                    source: "terminal_bridge",
+                    reason: "approval_not_approvable",
+                    terminal_control: terminalControl,
+                    terminal_status: terminalStatus,
+                    approval_fingerprint: fingerprint
+                }
+            });
+            if (notification.conversation.gateway_method) {
+                runLockedCallback({
+                    ...options,
+                    statePath,
+                    log: logPath,
+                    messageJson: JSON.stringify(callbackMessage),
+                    gatewayMethod: notification.conversation.gateway_method,
+                    gatewaySession: notification.conversation.gateway_session,
+                    openclawSession: notification.conversation.openclaw_session,
+                    openclawBin: notification.conversation.openclaw_bin,
+                    gatewayUrl: stringValue(notification.conversation.gateway_token)
+                        ? notification.conversation.gateway_url
+                        : undefined,
+                    token: stringValue(notification.conversation.gateway_token)
+                });
+                return;
+            }
+            printJson({
+                conversation: notification.conversation,
+                monitored: true,
+                terminal_bridge: true,
+                awaiting_approval: true,
+                approvable: false,
+                delivered: false,
+                message: callbackMessage,
+                reason: "gateway_method_missing",
+                terminal_control: terminalControl,
+                terminal_status: terminalStatus
+            });
+            return;
+        }
         if (isRecord(approval) && approval.blocked === true) {
             const fingerprint = terminalBridgeApprovalFingerprint({ terminalControl, terminalStatus });
             appendEvent(logPath, {
@@ -4117,7 +4730,7 @@ async function runTerminalBridgeMonitor(options) {
                         terminalStatus,
                         fingerprint
                     }),
-                    approve_command: `AKK approve ${notification.conversation.conversation_id}`,
+                    approve_command: `AKK approve ${notification.conversation.conversation_id} --expected-approval-fingerprint ${fingerprint}`,
                     deny_command: `AKK cancel ${notification.conversation.conversation_id}`,
                     approve_tool: "agent_knock_knock_approve",
                     deny_tool: "agent_knock_knock_cancel"
@@ -4155,40 +4768,22 @@ async function runTerminalBridgeMonitor(options) {
         const screenChanged = previousScreenFingerprint !== undefined &&
             screenFingerprint !== undefined &&
             screenFingerprint !== previousScreenFingerprint;
-        const screenChangedSinceSend = preSendScreenFingerprint !== undefined &&
-            screenFingerprint !== undefined &&
-            screenFingerprint !== preSendScreenFingerprint;
         previousScreenFingerprint = screenFingerprint;
-        const contextMatch = await terminalBridgeCodexContext({
-            conversation,
-            nativeTakeover,
-            options
-        });
-        const startedAt = stringValue(nativeTakeover?.["terminal_bridge_started_at"]);
-        const rolloutCompletion = contextMatch?.context
-            ? latestCompletedRolloutTurn({
-                context: contextMatch.context,
-                conversation,
-                nativeTakeover,
-                startedAt
-            })
-            : undefined;
-        const assistantMessage = contextMatch?.context
-            ? latestAssistantAfter(contextMatch.context, startedAt)
-            : undefined;
-        const rolloutFingerprint = rolloutCompletion || assistantMessage
+        const durableCompletion = poll.durableCompletion;
+        const durableFingerprint = durableCompletion
             ? terminalBridgeActivityFingerprint(JSON.stringify({
-                text: rolloutCompletion?.text ?? assistantMessage?.text,
-                timestamp: rolloutCompletion?.timestamp ?? assistantMessage?.timestamp,
-                turn_id: rolloutCompletion?.turnId
+                text: durableCompletion.text,
+                timestamp: durableCompletion.timestamp,
+                id: durableCompletion.id,
+                metadata: durableCompletion.metadata
             }))
             : undefined;
-        const rolloutChanged = rolloutFingerprint !== undefined && rolloutFingerprint !== previousRolloutFingerprint;
-        previousRolloutFingerprint = rolloutFingerprint;
+        const durableChanged = durableFingerprint !== undefined && durableFingerprint !== previousDurableFingerprint;
+        previousDurableFingerprint = durableFingerprint;
         const activityReasons = [
             terminalStatus.activity_state === "working" ? terminalStatus.activity_reason : undefined,
             screenChanged ? "terminal screen changed" : undefined,
-            rolloutChanged ? "Codex rollout assistant output changed" : undefined
+            durableChanged ? "durable completion evidence changed" : undefined
         ].filter((value) => Boolean(value));
         if (activityReasons.length > 0) {
             const observedAtMs = Date.now();
@@ -4213,77 +4808,118 @@ async function runTerminalBridgeMonitor(options) {
                 }
             }
         }
-        const terminalIdle = terminalStatus.activity_state === "idle";
-        const screenMessage = !rolloutCompletion && !assistantMessage && terminalIdle
-            ? terminalBridgeScreenMessage({
-                conversation,
-                nativeTakeover,
-                terminalStatus,
-                screenChangedSinceSend
-            })
+        const completion = poll.completion;
+        const completionMetadata = isRecord(completion?.metadata) ? completion.metadata : {};
+        const completionMatch = completion
+            ? stringValue(completionMetadata.match) ??
+                (completion.source === "screen" ? "terminal_screen" : "durable_completion")
             : undefined;
-        const completion = rolloutCompletion ?? (terminalIdle ? assistantMessage ?? screenMessage : undefined);
-        const completionMatch = rolloutCompletion
-            ? "rollout_task_complete"
-            : assistantMessage
-                ? contextMatch?.match
-                : "terminal_screen";
         const completionFingerprint = completion
             ? createHash("sha256")
                 .update(JSON.stringify({
                 text: completion.text,
                 timestamp: completion.timestamp,
                 match: completionMatch,
-                turn_id: rolloutCompletion?.turnId,
+                source: completion.source,
+                id: completion.id,
                 message_id: currentMessageId
             }))
                 .digest("hex")
             : undefined;
         const completionStable = completionFingerprint !== undefined && completionFingerprint === idleCompletionFingerprint;
         idleCompletionFingerprint = completionFingerprint;
-        if (completion && completionStable) {
-            appendEvent(logPath, {
-                ts: new Date().toISOString(),
-                conversation_id: conversation.conversation_id,
-                event: "terminal_bridge_completion_detected",
-                terminal_control: terminalControl,
-                match: completionMatch,
-                codex_session: contextMatch?.context.source,
-                assistant_timestamp: completion?.timestamp,
-                rollout_turn_id: rolloutCompletion?.turnId,
-                terminal_bridge_message_id: currentMessageId
+        if (completion && completionStable && completionFingerprint) {
+            const completionOutcome = completion.outcome === "failure" ? "failure" : "success";
+            const callbackMessageId = deterministicTerminalCallbackMessageId({
+                conversationId: conversation.conversation_id,
+                terminalMessageId: currentMessageId,
+                completionFingerprint,
+                outcome: completionOutcome
             });
-            const callbackMessage = createMessage({
-                conversation,
-                from: executor.actor,
-                to: "openclaw",
-                type: "done",
-                requiresResponse: false,
-                body: completion?.text ?? "",
-                metadata: {
-                    source: "terminal_bridge",
+            const claim = claimTerminalBridgeCompletion({
+                statePath,
+                logPath,
+                terminalMessageId: currentMessageId,
+                completionFingerprint,
+                completionId: completion.id,
+                callbackMessageId,
+                outcome: completionOutcome
+            });
+            if (!claim.claimed) {
+                printJson({
+                    conversation: claim.conversation,
+                    monitored: true,
+                    terminal_bridge: true,
+                    completed: false,
+                    duplicate: true,
+                    reason: claim.reason
+                });
+                return;
+            }
+            try {
+                conversation = claim.conversation;
+                appendEvent(logPath, {
+                    ts: new Date().toISOString(),
+                    conversation_id: conversation.conversation_id,
+                    event: "terminal_bridge_completion_detected",
                     terminal_control: terminalControl,
-                    codex_session: contextMatch?.context.source,
-                    confidence: rolloutCompletion || assistantMessage ? contextMatch?.confidence : "screen_only",
                     match: completionMatch,
+                    completion_source: completion.source,
+                    completion_outcome: completionOutcome,
+                    completion_id: completion.id,
+                    terminal_session: completionMetadata.session,
+                    context_match: completionMetadata.context_match,
                     assistant_timestamp: completion?.timestamp,
-                    rollout_turn_id: rolloutCompletion?.turnId,
-                    terminal_bridge_message_id: currentMessageId
-                }
-            });
-            runLockedCallback({
-                ...options,
-                statePath,
-                log: logPath,
-                closeTerminalBridgeOnDone: true,
-                messageJson: JSON.stringify(callbackMessage),
-                gatewayMethod: conversation.gateway_method,
-                gatewaySession: conversation.gateway_session,
-                openclawSession: conversation.openclaw_session,
-                openclawBin: conversation.openclaw_bin,
-                gatewayUrl: stringValue(conversation.gateway_token) ? conversation.gateway_url : undefined,
-                token: stringValue(conversation.gateway_token)
-            });
+                    rollout_turn_id: completion.source === "durable" ? completion.id : undefined,
+                    terminal_bridge_message_id: currentMessageId,
+                    callback_message_id: callbackMessageId
+                });
+                const callbackMessage = {
+                    ...createMessage({
+                        conversation,
+                        from: executor.actor,
+                        to: "openclaw",
+                        type: completionOutcome === "failure" ? "error" : "done",
+                        requiresResponse: false,
+                        body: completion.text,
+                        metadata: {
+                            source: "terminal_bridge",
+                            terminal_control: terminalControl,
+                            ...completionMetadata,
+                            completion_source: completion.source,
+                            completion_outcome: completionOutcome,
+                            completion_id: completion.id,
+                            terminal_session: completionMetadata.session,
+                            confidence: completion.confidence,
+                            match: completionMatch,
+                            assistant_timestamp: completion?.timestamp,
+                            rollout_turn_id: completion.source === "durable" ? completion.id : undefined,
+                            terminal_bridge_message_id: currentMessageId
+                        }
+                    }),
+                    id: callbackMessageId
+                };
+                runLockedCallback({
+                    ...options,
+                    statePath,
+                    log: logPath,
+                    closeTerminalBridgeOnDone: completionOutcome === "success",
+                    trackCallbackDelivery: true,
+                    recoverTerminalCompletion: claim.resumed === true,
+                    preserveMessageId: true,
+                    messageJson: JSON.stringify(callbackMessage),
+                    gatewayMethod: conversation.gateway_method,
+                    gatewaySession: conversation.gateway_session,
+                    openclawSession: conversation.openclaw_session,
+                    openclawBin: conversation.openclaw_bin,
+                    gatewayUrl: stringValue(conversation.gateway_token) ? conversation.gateway_url : undefined,
+                    token: stringValue(conversation.gateway_token)
+                });
+            }
+            finally {
+                releaseClaudeHookLease(conversation);
+                claim.release();
+            }
             return;
         }
         // A concrete approval or completion observed on this poll wins over a timeout boundary.
@@ -4334,7 +4970,7 @@ async function runTerminalBridgeMonitor(options) {
                     detail: {
                         terminal_bridge: true,
                         terminal_control: terminalControl,
-                        match: contextMatch?.match,
+                        match: completionMetadata.context_match,
                         terminal_activity_state: terminalStatus.activity_state,
                         last_activity_at: new Date(lastActivityAtMs).toISOString(),
                         inactivity_deadline_at: new Date(lastActivityAtMs + timeoutMinutes * 60 * 1000).toISOString(),
@@ -4387,6 +5023,111 @@ function terminalBridgeRequestFingerprint(value) {
     const text = String(value ?? "").replace(/\s+/gu, " ").trim();
     return text ? createHash("sha256").update(text).digest("hex") : undefined;
 }
+function deterministicTerminalCallbackMessageId({ conversationId, terminalMessageId, completionFingerprint, outcome }) {
+    const digest = createHash("sha256")
+        .update(JSON.stringify({
+        conversation_id: conversationId,
+        terminal_message_id: terminalMessageId,
+        completion_fingerprint: completionFingerprint,
+        outcome
+    }))
+        .digest("hex")
+        .slice(0, 32);
+    return `msg-terminal-${digest}`;
+}
+function claimTerminalBridgeCompletion({ statePath, logPath, terminalMessageId, completionFingerprint, completionId, callbackMessageId, outcome }) {
+    const release = acquireFileLock(`${statePath}.lock`);
+    try {
+        const conversation = loadState(statePath);
+        const nativeTakeover = isRecord(conversation.native_session_takeover)
+            ? conversation.native_session_takeover
+            : {};
+        if (!isWaitingForAgent(conversation.status)) {
+            release();
+            return {
+                claimed: false,
+                conversation,
+                reason: "conversation_no_longer_waiting"
+            };
+        }
+        if (stringValue(nativeTakeover.terminal_bridge_message_id) !== terminalMessageId) {
+            release();
+            return {
+                claimed: false,
+                conversation,
+                reason: "terminal_bridge_task_replaced"
+            };
+        }
+        const existing = isRecord(nativeTakeover.terminal_bridge_completion_claim)
+            ? nativeTakeover.terminal_bridge_completion_claim
+            : undefined;
+        if (existing) {
+            if (existing.callback_message_id === callbackMessageId &&
+                existing.terminal_bridge_message_id === terminalMessageId &&
+                existing.completion_fingerprint === completionFingerprint &&
+                existing.outcome === outcome) {
+                appendEvent(logPath, {
+                    ts: new Date().toISOString(),
+                    conversation_id: conversation.conversation_id,
+                    event: "terminal_bridge_completion_claim_resumed",
+                    terminal_bridge_message_id: terminalMessageId,
+                    completion_fingerprint: completionFingerprint,
+                    callback_message_id: callbackMessageId,
+                    outcome
+                });
+                return {
+                    claimed: true,
+                    resumed: true,
+                    conversation,
+                    release
+                };
+            }
+            release();
+            return {
+                claimed: false,
+                conversation,
+                reason: "terminal_bridge_completion_claim_conflict"
+            };
+        }
+        const claimedAt = new Date().toISOString();
+        const claimedConversation = {
+            ...conversation,
+            native_session_takeover: {
+                ...nativeTakeover,
+                terminal_bridge_completion_claim: {
+                    terminal_bridge_message_id: terminalMessageId,
+                    completion_fingerprint: completionFingerprint,
+                    completion_id: completionId,
+                    callback_message_id: callbackMessageId,
+                    outcome,
+                    claimed_at: claimedAt
+                }
+            },
+            updated_at: claimedAt
+        };
+        saveState(statePath, claimedConversation);
+        appendEvent(logPath, {
+            ts: claimedAt,
+            conversation_id: conversation.conversation_id,
+            event: "terminal_bridge_completion_claimed",
+            terminal_bridge_message_id: terminalMessageId,
+            completion_fingerprint: completionFingerprint,
+            completion_id: completionId,
+            callback_message_id: callbackMessageId,
+            outcome
+        });
+        return {
+            claimed: true,
+            resumed: false,
+            conversation: claimedConversation,
+            release
+        };
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+}
 function terminalBridgeActivityPersistIntervalMs(timeoutMinutes, pollIntervalMs) {
     if (!Number.isFinite(timeoutMinutes) || timeoutMinutes <= 0) {
         return 5 * 60 * 1000;
@@ -4415,6 +5156,13 @@ function persistTerminalBridgeActivity({ conversation, statePath, logPath, obser
         const inactivityDeadlineAt = Number.isFinite(timeoutMinutes) && timeoutMinutes > 0
             ? new Date(observedAtMs + timeoutMinutes * 60 * 1000).toISOString()
             : undefined;
+        const hardDeadlineAt = stringValue(nativeTakeover.terminal_bridge_hard_deadline_at);
+        const leaseDeadlineAt = inactivityDeadlineAt && hardDeadlineAt
+            ? new Date(Math.min(Date.parse(inactivityDeadlineAt), Date.parse(hardDeadlineAt))).toISOString()
+            : inactivityDeadlineAt ?? hardDeadlineAt;
+        const renewedLease = leaseDeadlineAt
+            ? renewClaudeHookLease(currentConversation, leaseDeadlineAt)
+            : undefined;
         const nextConversation = {
             ...currentConversation,
             native_session_takeover: {
@@ -4423,7 +5171,8 @@ function persistTerminalBridgeActivity({ conversation, statePath, logPath, obser
                 terminal_bridge_last_activity_reason: reason,
                 terminal_bridge_inactivity_deadline_at: inactivityDeadlineAt,
                 terminal_bridge_inactivity_timeout_minutes: timeoutMinutes,
-                terminal_bridge_hard_timeout_minutes: hardTimeoutMinutes
+                terminal_bridge_hard_timeout_minutes: hardTimeoutMinutes,
+                claude_hook_lease_id: renewedLease?.id ?? nativeTakeover.claude_hook_lease_id
             },
             updated_at: observedAt
         };
@@ -4465,12 +5214,15 @@ function terminalBridgeApprovalCandidate({ executor, terminalControl, terminalSt
         agent: executor.kind,
         kind: stringValue(approval.prompt_kind) ?? "unknown",
         command: stringValue(approval.command),
+        tool_name: stringValue(approval.tool_name),
+        request_detail: stringValue(approval.request_detail),
         cwd: terminalControl.currentPath,
         fingerprint,
-        terminal_target: terminalControl.target
+        terminal_target: terminalControl.target,
+        decision_mode: stringValue(approval.decision_mode)
     };
 }
-async function terminalBridgeCodexContext({ conversation, nativeTakeover, options }) {
+async function loadCodexTerminalContext({ conversation, nativeTakeover, options }) {
     const provider = createAgentSessionProvider("codex", options);
     const nativeSessionId = stringValue(nativeTakeover?.["native_session_id"]);
     const startedAtMs = Date.parse(String(nativeTakeover?.["terminal_bridge_started_at"] ?? ""));
@@ -4526,146 +5278,6 @@ async function terminalBridgeCodexContext({ conversation, nativeTakeover, option
         confidence: sessions.length === 1 ? "medium" : "low"
     };
 }
-function latestAssistantAfter(context, startedAt) {
-    const threshold = startedAt ? Date.parse(startedAt) : undefined;
-    return [...visibleRolloutMessages(context)]
-        .reverse()
-        .find((message) => {
-        if (message.role !== "assistant") {
-            return false;
-        }
-        if (!Number.isFinite(threshold)) {
-            return true;
-        }
-        const messageTime = message.timestamp ? Date.parse(message.timestamp) : NaN;
-        return Number.isFinite(messageTime) && messageTime >= Number(threshold);
-    });
-}
-function latestCompletedRolloutTurn({ context, conversation, nativeTakeover, startedAt }) {
-    const threshold = validTimestampMs(startedAt);
-    const expectedRequestHash = stringValue(nativeTakeover?.["terminal_bridge_request_hash"]) ??
-        terminalBridgeRequestFingerprint(nativeTakeover?.["terminal_bridge_request_text"] ?? conversation.user_request);
-    if (threshold === undefined || !expectedRequestHash) {
-        return undefined;
-    }
-    const turn = [...(context.turns ?? [])]
-        .reverse()
-        .find((candidate) => {
-        const userTimestamp = validTimestampMs(candidate.userTimestamp);
-        const completedAt = validTimestampMs(candidate.completedAt);
-        return candidate.userTextHash === expectedRequestHash &&
-            userTimestamp !== undefined &&
-            completedAt !== undefined &&
-            userTimestamp >= threshold &&
-            completedAt >= userTimestamp &&
-            Boolean(candidate.lastAssistantMessage);
-    });
-    if (!turn?.lastAssistantMessage) {
-        return undefined;
-    }
-    return {
-        role: "assistant",
-        text: turn.lastAssistantMessage,
-        timestamp: turn.completedAt,
-        turnId: turn.turnId,
-        userTimestamp: turn.userTimestamp
-    };
-}
-function terminalBridgeScreenMessage({ conversation, nativeTakeover, terminalStatus, screenChangedSinceSend }) {
-    const excerpt = stringValue(terminalStatus?.screen?.excerpt);
-    if (!excerpt) {
-        return undefined;
-    }
-    const request = String(nativeTakeover?.["terminal_bridge_request_text"] ?? conversation.user_request ?? "").trim();
-    const promptEnd = request ? whitespaceInsensitiveMatchEnd(excerpt, request) : undefined;
-    const afterPrompt = promptEnd === undefined ? undefined : excerpt.slice(promptEnd);
-    const completionBoundary = afterPrompt === undefined
-        ? undefined
-        : terminalBridgeCompletionBoundary(afterPrompt);
-    const completionText = afterPrompt === undefined
-        ? screenChangedSinceSend
-            ? terminalBridgeLatestCompletedSegment(excerpt)
-            : undefined
-        : completionBoundary === undefined
-            ? afterPrompt
-            : afterPrompt.slice(0, completionBoundary);
-    if (completionText === undefined) {
-        return undefined;
-    }
-    const cleaned = cleanTerminalBridgeScreenText(completionText);
-    const hasCompletionEvidence = promptEnd === undefined || completionBoundary !== undefined || /[•└]/u.test(cleaned ?? "");
-    if (!cleaned || cleaned.length < 40 || !hasCompletionEvidence) {
-        return undefined;
-    }
-    return {
-        role: "assistant",
-        text: truncateText(cleaned, 4000),
-        timestamp: undefined
-    };
-}
-function whitespaceInsensitiveMatchEnd(text, expected) {
-    const normalizedExpected = expected.replace(/\s/gu, "");
-    if (!normalizedExpected) {
-        return undefined;
-    }
-    let normalizedText = "";
-    const sourceEnds = [];
-    for (let index = 0; index < text.length;) {
-        const codePoint = text.codePointAt(index);
-        if (codePoint === undefined) {
-            break;
-        }
-        const character = String.fromCodePoint(codePoint);
-        if (!/\s/u.test(character)) {
-            normalizedText += character;
-            for (let codeUnit = 0; codeUnit < character.length; codeUnit += 1) {
-                sourceEnds.push(index + character.length);
-            }
-        }
-        index += character.length;
-    }
-    const matchIndex = normalizedText.lastIndexOf(normalizedExpected);
-    if (matchIndex < 0) {
-        return undefined;
-    }
-    return sourceEnds[matchIndex + normalizedExpected.length - 1];
-}
-function terminalBridgeLatestCompletedSegment(text) {
-    const matches = [...text.matchAll(/^[ \t]*[─━-]+\s+Worked for\b.*$/gmu)];
-    const completion = matches.at(-1);
-    if (completion?.index === undefined) {
-        return undefined;
-    }
-    const previousCompletion = matches.at(-2);
-    let start = previousCompletion?.index === undefined
-        ? 0
-        : previousCompletion.index + previousCompletion[0].length;
-    const beforeCompletion = text.slice(0, completion.index);
-    const prompts = [...beforeCompletion.matchAll(/^[ \t]*›(?:\s|$).*$/gmu)];
-    const latestPrompt = prompts.at(-1);
-    if (latestPrompt?.index !== undefined && latestPrompt.index >= start) {
-        start = latestPrompt.index + latestPrompt[0].length;
-    }
-    return text.slice(start, completion.index);
-}
-function terminalBridgeCompletionBoundary(text) {
-    const matches = [...text.matchAll(/^[ \t]*[─━-]+\s+Worked for\b.*$/gmu)];
-    return matches.at(-1)?.index;
-}
-function cleanTerminalBridgeScreenText(text) {
-    const lines = text
-        .split(/\r?\n/)
-        .map((line) => line.replace(/\s+$/u, ""))
-        .filter((line) => {
-        const trimmed = line.trim();
-        return trimmed &&
-            !trimmed.startsWith("› Use /skills") &&
-            !/^gpt-[\w.-]+/u.test(trimmed) &&
-            !/^[-\w.]+ default ·/u.test(trimmed);
-    });
-    const cleaned = lines.join("\n").trim();
-    return cleaned || undefined;
-}
 function resolveExecutable(command) {
     if (command.includes(path.sep)) {
         return command;
@@ -4784,19 +5396,66 @@ function runCallback(options) {
         releaseLock();
     }
 }
+function runRetryCallback(options) {
+    const { conversation, statePath } = loadConversationFromOptions(options);
+    const callbackDelivery = isRecord(conversation.callback_delivery)
+        ? conversation.callback_delivery
+        : undefined;
+    if (!["callback_pending", "callback_failed"].includes(conversation.status)) {
+        throw new Error(`cannot retry callback for ${conversation.conversation_id}; conversation is ${conversation.status}`);
+    }
+    if (!callbackDelivery || !isRecord(callbackDelivery.message)) {
+        throw new Error(`cannot retry callback for ${conversation.conversation_id}; pending callback is missing`);
+    }
+    const releaseLock = acquireFileLock(`${statePath}.lock`);
+    try {
+        runLockedCallback({
+            ...options,
+            statePath,
+            messageJson: JSON.stringify(callbackDelivery.message),
+            gatewayMethod: stringValue(callbackDelivery.gateway_method) ?? conversation.gateway_method,
+            gatewaySession: stringValue(callbackDelivery.gateway_session) ?? conversation.gateway_session,
+            openclawSession: conversation.openclaw_session,
+            openclawBin: stringValue(callbackDelivery.openclaw_bin) ?? conversation.openclaw_bin,
+            gatewayUrl: stringValue(callbackDelivery.gateway_url) ?? conversation.gateway_url,
+            token: stringValue(callbackDelivery.gateway_token) ?? conversation.gateway_token,
+            closeTerminalBridgeOnDone: callbackDelivery.close_terminal_bridge_on_done === true,
+            retryPending: true
+        });
+    }
+    finally {
+        releaseLock();
+    }
+}
 function runLockedCallback(options) {
     const messageInput = required(options.messageJson, "--message-json is required");
     const logPath = expandHome(options.log ?? logPathForStatePath(options.statePath));
     const conversation = loadState(options.statePath);
     const executor = executorForConversation(conversation);
-    const message = extractStructuredMessage({
-        conversation,
-        input: messageInput,
-        defaultFrom: executor.actor,
-        defaultTo: "openclaw"
-    });
+    const message = options.retryPending === true || options.preserveMessageId === true
+        ? parseMessageJson(messageInput)
+        : extractStructuredMessage({
+            conversation,
+            input: messageInput,
+            defaultFrom: executor.actor,
+            defaultTo: "openclaw"
+        });
+    if (message.conversation_id !== conversation.conversation_id) {
+        throw new Error(`message.conversation_id ${message.conversation_id} does not match conversation ${conversation.conversation_id}`);
+    }
     const existingEvents = readExistingEvents(logPath);
-    if (isDuplicateMessage(existingEvents, message)) {
+    const callbackDelivery = isRecord(conversation.callback_delivery)
+        ? conversation.callback_delivery
+        : undefined;
+    const retryingPending = options.retryPending === true &&
+        isRecord(callbackDelivery?.message) &&
+        callbackDelivery.message.id === message.id &&
+        ["pending", "failed"].includes(String(callbackDelivery.status ?? ""));
+    const duplicateMessage = isDuplicateMessage(existingEvents, message);
+    const recoveringTerminalCompletion = options.recoverTerminalCompletion === true &&
+        duplicateMessage &&
+        isWaitingForAgent(conversation.status);
+    if (duplicateMessage && !retryingPending && !recoveringTerminalCompletion) {
         runtimeLog("info", "callback_duplicate", {
             conversation_id: conversation.conversation_id,
             agent: executor.kind,
@@ -4816,19 +5475,56 @@ function runLockedCallback(options) {
         });
         return;
     }
-    let nextConversation = applyMessageToConversation(conversation, message);
-    if (message.type === "done" && options.closeTerminalBridgeOnDone === true) {
+    const closeTerminalBridgeOnDone = message.type === "done" &&
+        options.closeTerminalBridgeOnDone === true;
+    const trackCallbackDelivery = closeTerminalBridgeOnDone ||
+        options.trackCallbackDelivery === true ||
+        callbackDelivery?.track_delivery === true;
+    const requiresDelivery = Boolean(options.gatewayMethod) || options.recordOnly !== true;
+    const deliveryAttempt = Number(callbackDelivery?.attempts ?? 0) + 1;
+    let nextConversation = retryingPending
+        ? conversation
+        : applyMessageToConversation(conversation, message);
+    const storedFinalStatus = stringValue(callbackDelivery?.final_status);
+    const finalStatus = storedFinalStatus &&
+        CONVERSATION_STATUSES.has(storedFinalStatus)
+        ? storedFinalStatus
+        : nextConversation.status;
+    if (!retryingPending && !recoveringTerminalCompletion) {
+        appendEvent(logPath, messageEvent(message));
+    }
+    if (trackCallbackDelivery && requiresDelivery) {
         const now = new Date().toISOString();
         nextConversation = {
             ...nextConversation,
-            status: "closed",
-            closed_at: now,
-            close_reason: "terminal bridge task completed",
+            status: "callback_pending",
+            callback_delivery: {
+                status: "pending",
+                message,
+                attempts: deliveryAttempt,
+                created_at: stringValue(callbackDelivery?.created_at) ?? now,
+                last_attempt_at: now,
+                gateway_method: options.gatewayMethod,
+                gateway_session: options.gatewaySession ?? options.openclawSession ?? conversation.openclaw_session,
+                gateway_url: options.gatewayUrl ?? conversation.gateway_url,
+                openclaw_bin: options.openclawBin ?? conversation.openclaw_bin,
+                close_terminal_bridge_on_done: closeTerminalBridgeOnDone,
+                track_delivery: true,
+                final_status: finalStatus
+            },
             updated_at: now
         };
         delete nextConversation.idle_since;
+        delete nextConversation.closed_at;
+        delete nextConversation.close_reason;
+        appendEvent(logPath, {
+            ts: now,
+            conversation_id: conversation.conversation_id,
+            event: retryingPending ? "callback_delivery_retry_started" : "callback_delivery_pending",
+            message_id: message.id,
+            attempt: deliveryAttempt
+        });
     }
-    appendEvent(logPath, messageEvent(message));
     saveState(options.statePath, nextConversation);
     runtimeLog("info", "callback_received", {
         conversation_id: conversation.conversation_id,
@@ -4843,13 +5539,120 @@ function runLockedCallback(options) {
         event_log_path: logPath,
         message: textSummary(message.body)
     });
-    const result = {
-        conversation: nextConversation,
-        message,
-        budget: budgetAction(nextConversation),
-        delivered: false,
-        duplicate: false
-    };
+    if (options.recordOnly) {
+        runtimeLog("info", "callback_recorded_only", {
+            conversation_id: conversation.conversation_id,
+            status: nextConversation.status
+        });
+        printJson({
+            conversation: nextConversation,
+            message,
+            budget: budgetAction(nextConversation),
+            delivered: false,
+            duplicate: false
+        });
+        return;
+    }
+    try {
+        const deliveryKind = deliverCallbackToOpenClaw({
+            options,
+            statePath: options.statePath,
+            logPath,
+            conversation: nextConversation,
+            message
+        });
+        const deliveredAt = new Date().toISOString();
+        let deliveredConversation = nextConversation;
+        if (trackCallbackDelivery) {
+            const deliveredStatus = closeTerminalBridgeOnDone ? "closed" : finalStatus;
+            deliveredConversation = {
+                ...nextConversation,
+                status: deliveredStatus,
+                ...(closeTerminalBridgeOnDone
+                    ? {
+                        closed_at: deliveredAt,
+                        close_reason: "terminal bridge task completed"
+                    }
+                    : {}),
+                callback_delivery: {
+                    ...(isRecord(nextConversation.callback_delivery) ? nextConversation.callback_delivery : {}),
+                    status: "delivered",
+                    delivered_at: deliveredAt,
+                    last_error: undefined
+                },
+                updated_at: deliveredAt
+            };
+            delete deliveredConversation.idle_since;
+            saveState(options.statePath, deliveredConversation);
+            appendEvent(logPath, {
+                ts: deliveredAt,
+                conversation_id: conversation.conversation_id,
+                event: "callback_delivery_succeeded",
+                message_id: message.id,
+                attempt: deliveryAttempt,
+                status: deliveredStatus
+            });
+        }
+        printJson({
+            conversation: deliveredConversation,
+            message,
+            budget: budgetAction(deliveredConversation),
+            delivered: true,
+            duplicate: false,
+            delivery: deliveryKind
+        });
+    }
+    catch (error) {
+        if (trackCallbackDelivery) {
+            const failedAt = new Date().toISOString();
+            const failedConversation = {
+                ...nextConversation,
+                status: "callback_failed",
+                callback_delivery: {
+                    ...(isRecord(nextConversation.callback_delivery) ? nextConversation.callback_delivery : {}),
+                    status: "failed",
+                    failed_at: failedAt,
+                    last_error: error instanceof Error ? error.message : String(error)
+                },
+                updated_at: failedAt
+            };
+            saveState(options.statePath, failedConversation);
+            appendEvent(logPath, {
+                ts: failedAt,
+                conversation_id: conversation.conversation_id,
+                event: "callback_delivery_failed",
+                message_id: message.id,
+                attempt: deliveryAttempt,
+                error: failedConversation.callback_delivery.last_error
+            });
+            if (options.retryPending !== true &&
+                options.disableCallbackRetry !== true &&
+                deliveryAttempt <= CALLBACK_RETRY_DELAYS_MS.length) {
+                const retryMonitor = startCallbackRetryMonitor({ statePath: options.statePath });
+                const retryDelayMs = CALLBACK_RETRY_DELAYS_MS[Math.max(0, deliveryAttempt - 1)];
+                const retryState = {
+                    ...failedConversation,
+                    callback_delivery: {
+                        ...failedConversation.callback_delivery,
+                        retry_monitor_pid: retryMonitor.pid ?? null,
+                        next_attempt_at: new Date(Date.now() + retryDelayMs).toISOString()
+                    }
+                };
+                saveState(options.statePath, retryState);
+                appendEvent(logPath, {
+                    ts: new Date().toISOString(),
+                    conversation_id: conversation.conversation_id,
+                    event: "callback_retry_monitor_launched",
+                    message_id: message.id,
+                    pid: retryMonitor.pid ?? null,
+                    next_attempt_at: retryState.callback_delivery.next_attempt_at
+                });
+            }
+        }
+        throw error;
+    }
+}
+function deliverCallbackToOpenClaw({ options, statePath, logPath, conversation, message }) {
     if (options.gatewayMethod) {
         const delivery = deliverToGatewayMethod({
             method: options.gatewayMethod,
@@ -4857,30 +5660,19 @@ function runLockedCallback(options) {
             gatewayUrl: options.gatewayUrl,
             token: options.token,
             sessionKey: options.gatewaySession ?? options.openclawSession ?? conversation.openclaw_session,
-            statePath: options.statePath,
+            statePath,
             logPath,
-            conversation: nextConversation,
+            conversation,
             message
         });
-        appendEvent(logPath, {
-            ts: new Date().toISOString(),
-            conversation_id: conversation.conversation_id,
+        recordCallbackProcessDelivery({
+            logPath,
+            conversation,
+            message,
             event: "callback_gateway_method_delivery",
-            from: message.from,
-            to: "openclaw",
-            round: message.round,
-            method: options.gatewayMethod,
-            status: delivery.status,
-            stdout: delivery.stdout,
-            stderr: delivery.stderr
-        });
-        runtimeLog("info", "callback_gateway_method_delivery", {
-            conversation_id: conversation.conversation_id,
-            method: options.gatewayMethod,
-            status: delivery.status,
-            failure_kind: classifyProcessFailure(delivery),
-            stdout: textSummary(delivery.stdout),
-            stderr: textSummary(delivery.stderr)
+            runtimeEvent: "callback_gateway_method_delivery",
+            delivery,
+            detail: { method: options.gatewayMethod }
         });
         if (delivery.status !== 0) {
             throw new Error(delivery.stderr || delivery.stdout || `gateway method delivery failed with status ${delivery.status}`);
@@ -4888,84 +5680,47 @@ function runLockedCallback(options) {
         const gatewayPayload = parseOptionalJson(delivery.stdout);
         const chatSendParams = isRecord(gatewayPayload?.chat_send) ? gatewayPayload.chat_send : undefined;
         const sessionSendParams = isRecord(gatewayPayload?.session_send) ? gatewayPayload.session_send : undefined;
-        let chatSendDelivery;
-        let sessionSendDelivery;
         if (chatSendParams) {
-            chatSendDelivery = deliverToChatSend({
+            const chatSendDelivery = deliverToChatSend({
                 openclawBin: options.openclawBin,
                 gatewayUrl: options.gatewayUrl,
                 token: options.token,
                 params: chatSendParams
             });
-            appendEvent(logPath, {
-                ts: new Date().toISOString(),
-                conversation_id: conversation.conversation_id,
+            recordCallbackProcessDelivery({
+                logPath,
+                conversation,
+                message,
                 event: "callback_chat_send_delivery",
-                from: message.from,
-                to: "openclaw",
-                round: message.round,
-                status: chatSendDelivery.status,
-                stdout: chatSendDelivery.stdout,
-                stderr: chatSendDelivery.stderr
-            });
-            runtimeLog("info", "callback_chat_send_delivery", {
-                conversation_id: conversation.conversation_id,
-                status: chatSendDelivery.status,
-                failure_kind: classifyProcessFailure(chatSendDelivery),
-                stdout: textSummary(chatSendDelivery.stdout),
-                stderr: textSummary(chatSendDelivery.stderr)
+                runtimeEvent: "callback_chat_send_delivery",
+                delivery: chatSendDelivery
             });
             if (chatSendDelivery.status !== 0) {
                 throw new Error(chatSendDelivery.stderr || chatSendDelivery.stdout || `chat callback delivery failed with status ${chatSendDelivery.status}`);
             }
+            return "gateway_method+chat_send";
         }
-        else if (sessionSendParams) {
-            sessionSendDelivery = deliverToSessionSend({
+        if (sessionSendParams) {
+            const sessionSendDelivery = deliverToSessionSend({
                 openclawBin: options.openclawBin,
                 gatewayUrl: options.gatewayUrl,
                 token: options.token,
                 params: sessionSendParams
             });
-            appendEvent(logPath, {
-                ts: new Date().toISOString(),
-                conversation_id: conversation.conversation_id,
+            recordCallbackProcessDelivery({
+                logPath,
+                conversation,
+                message,
                 event: "callback_session_send_delivery",
-                from: message.from,
-                to: "openclaw",
-                round: message.round,
-                status: sessionSendDelivery.status,
-                stdout: sessionSendDelivery.stdout,
-                stderr: sessionSendDelivery.stderr
-            });
-            runtimeLog("info", "callback_session_send_delivery", {
-                conversation_id: conversation.conversation_id,
-                status: sessionSendDelivery.status,
-                failure_kind: classifyProcessFailure(sessionSendDelivery),
-                stdout: textSummary(sessionSendDelivery.stdout),
-                stderr: textSummary(sessionSendDelivery.stderr)
+                runtimeEvent: "callback_session_send_delivery",
+                delivery: sessionSendDelivery
             });
             if (sessionSendDelivery.status !== 0) {
                 throw new Error(sessionSendDelivery.stderr || sessionSendDelivery.stdout || `session callback delivery failed with status ${sessionSendDelivery.status}`);
             }
+            return "gateway_method+sessions_send";
         }
-        printJson({
-            ...result,
-            delivered: true,
-            delivery: chatSendDelivery
-                ? "gateway_method+chat_send"
-                : sessionSendDelivery
-                    ? "gateway_method+sessions_send"
-                    : "gateway_method"
-        });
-        return;
-    }
-    if (options.recordOnly) {
-        runtimeLog("info", "callback_recorded_only", {
-            conversation_id: conversation.conversation_id,
-            status: nextConversation.status
-        });
-        printJson(result);
-        return;
+        return "gateway_method";
     }
     const gatewayUrl = options.gatewayUrl ?? conversation.gateway_url;
     const token = options.token ?? conversation.gateway_token;
@@ -4980,37 +5735,48 @@ function runLockedCallback(options) {
         throw new Error("--openclaw-session is required unless state has openclaw_session");
     }
     const delivery = deliverToOpenClaw({ gatewayUrl, token, openclawSession, message });
+    recordCallbackProcessDelivery({
+        logPath,
+        conversation,
+        message,
+        event: "callback_delivery",
+        runtimeEvent: "callback_delivery",
+        delivery
+    });
+    if (delivery.status !== 0) {
+        throw new Error(delivery.stderr || delivery.stdout || `callback delivery failed with status ${delivery.status}`);
+    }
+    return "acpx";
+}
+function recordCallbackProcessDelivery({ logPath, conversation, message, event, runtimeEvent, delivery, detail = {} }) {
     appendEvent(logPath, {
         ts: new Date().toISOString(),
         conversation_id: conversation.conversation_id,
-        event: "callback_delivery",
+        event,
         from: message.from,
         to: "openclaw",
         round: message.round,
+        ...detail,
         status: delivery.status,
         stdout: delivery.stdout,
         stderr: delivery.stderr
     });
-    runtimeLog("info", "callback_delivery", {
+    runtimeLog("info", runtimeEvent, {
         conversation_id: conversation.conversation_id,
+        ...detail,
         status: delivery.status,
         failure_kind: classifyProcessFailure(delivery),
         stdout: textSummary(delivery.stdout),
         stderr: textSummary(delivery.stderr)
     });
-    if (delivery.status !== 0) {
-        throw new Error(delivery.stderr || delivery.stdout || `callback delivery failed with status ${delivery.status}`);
-    }
-    printJson({
-        ...result,
-        delivered: true
-    });
 }
 function acquireFileLock(lockPath, { timeoutMs = 5000, retryMs = 50 } = {}) {
     const started = Date.now();
     while (true) {
         try {
             const fd = fs.openSync(lockPath, "wx");
+            fs.writeFileSync(fd, `${process.pid}\n`, "utf8");
+            fs.fsyncSync(fd);
             fs.closeSync(fd);
             return () => {
                 fs.rmSync(lockPath, { force: true });
@@ -5020,6 +5786,10 @@ function acquireFileLock(lockPath, { timeoutMs = 5000, retryMs = 50 } = {}) {
             if (error.code !== "EEXIST") {
                 throw error;
             }
+            if (staleFileLock(lockPath)) {
+                fs.rmSync(lockPath, { force: true });
+                continue;
+            }
             if (Date.now() - started >= timeoutMs) {
                 throw new Error(`timed out waiting for file lock: ${lockPath}`);
             }
@@ -5027,6 +5797,26 @@ function acquireFileLock(lockPath, { timeoutMs = 5000, retryMs = 50 } = {}) {
         }
     }
 }
+function staleFileLock(lockPath) {
+    try {
+        const stat = fs.statSync(lockPath);
+        const ownerText = fs.readFileSync(lockPath, "utf8").trim();
+        const ownerPid = Number(ownerText);
+        if (Number.isSafeInteger(ownerPid) && ownerPid > 1) {
+            try {
+                process.kill(ownerPid, 0);
+                return false;
+            }
+            catch (error) {
+                return isRecord(error) && error.code === "ESRCH";
+            }
+        }
+        return Date.now() - stat.mtimeMs > 30_000;
+    }
+    catch (error) {
+        return isRecord(error) && error.code === "ENOENT";
+    }
+}
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -5589,6 +6379,7 @@ function markConversationStalled({ statePath, logPath, reason, detail = {} }) {
             updated_at: now
         };
         saveState(statePath, stalledConversation);
+        releaseClaudeHookLease(stalledConversation);
         appendEvent(logPath, {
             ts: now,
             conversation_id: conversation.conversation_id,
@@ -6297,9 +7088,11 @@ function usage() {
   agent-knock-knock approve --conversation <id>
   agent-knock-knock cancel --conversation <id> [--all-proxy <url>]
   agent-knock-knock renew --conversation <id> [--minutes <inactivity-minutes>]
+  agent-knock-knock retry-callback --conversation <id> [--store-dir <dir>]
   agent-knock-knock recover --conversation <id> [--session <name>] [--all-proxy <url>]
   agent-knock-knock close --conversation <id> [--reason <text>]
   agent-knock-knock install-openclaw [--openclaw-bin <path>] [--skill-path <path>] [--skill-only] [--no-restart]
+  agent-knock-knock install-claude-hooks [--settings-path <path>] [--executable-path <path>] [--dry-run]
   agent-knock-knock doctor
   agent-knock-knock agent takeover --agent codex --session-id <id> --strategy terminate_then_resume|terminal_control|fork [--create-conversation]
   agent-knock-knock callback --state <file> --message-json <json> [--record-only]