@scotthuang/agent-knock-knock 0.10.3 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.11.0 - 2026-08-07
+
+### Added
+
+- Add snapshot-bound native Resume navigation with deterministic numbers, collision-safe display-only short IDs, opaque five-minute handles, and a `previous` / `刚才那个` shortcut derived from the current Session's latest committed lifecycle transition.
+
+### Security
+
+- Resolve every Resume shortcut back to the complete UUID and exact evidence tuple, then fail closed if the terminal action generation, process, workspace, binding, ordered candidate snapshot, ownership, or TTL changed before native input.
+
+## 0.10.4 - 2026-08-07
+
+### Fixed
+
+- Recognize exact Codex multiline drafts across TUI-painted visual wraps before dispatching Enter once, while preserving authored newlines, indentation, repeated spaces, stable-capture checks, and fail-closed content drift detection.
+
 ## 0.10.3 - 2026-08-07
 
 ### Added

package/README.md

@@ -214,7 +214,7 @@ The core command surface is intentionally small:
 /akk threads <exact-terminal-id>
 /akk new-thread <exact-terminal-id>
 /akk clear-thread <exact-terminal-id>
-/akk resume-thread <exact-terminal-id> [native-thread-uuid]
+/akk resume-thread <exact-terminal-id> [uuid|previous|number|@short-id|snapshot-handle]
 /akk status [only|latest|codex|claude|@short-ref]
 /akk respond <turn-selector>: <answer>
 /akk cancel <turn-selector>
@@ -224,13 +224,13 @@ The core command surface is intentionally small:
 
 Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and `codex` or `claude` must identify exactly one eligible pane. These names and `@short-ref` are human-facing resolution inputs; a natural-language tool call may preserve one explicitly named by the user, but must not infer one. Managed JSON actions contain the authoritative full `session_id` or `turn_id`. For first attach, an unmanaged raw-terminal row's send action may instead contain its own prefilled `selector`; its advertised raw controls may contain that row's prefilled `conversation_id`. Neither compatibility selector may be guessed, copied from another row, or passed in an authoritative ID field. Before every terminal operation, AKK revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories still match; every send also revalidates the idle prompt immediately before typing.
 
-To change native context, first copy the full `terminal_id` from `/akk list`; lifecycle commands do not accept `@short-ref` or loose agent selectors. `/akk threads <exact-terminal-id>` lists exact, same-workspace resume candidates. `/akk resume-thread <exact-terminal-id>` without a UUID shows the same candidates and asks you to choose; with a complete returned UUID it performs the transition. `/akk new-thread` and its human alias `/akk clear-thread` start a clean context. For these slash forms, AKK reads a fresh lifecycle snapshot and immediately supplies its compare-and-swap binding token internally, so you do not copy the token yourself. AKK does not poll bindings in the background: if a recorded owner process exits, the next lifecycle listing can classify that sole historical binding as resumable, and the resume mutation compare-and-swap detaches it before touching the terminal. Live, stale-token, unsupported, busy, ambiguous, active-elsewhere, or unverifiable transitions fail closed. Do not send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, or `/btw`, Claude `/branch`, or any other first-line native slash command as an ordinary task or answer; use an advertised AKK action, express the request in natural language, or enter an unsupported native command manually in tmux.
+To change native context, first copy the full `terminal_id` from `/akk list`; lifecycle commands do not accept an ordinary-send `@short-ref` or loose agent selector. `/akk threads <exact-terminal-id>` lists exact, same-workspace candidates with a deterministic number, a collision-safe display-only `@short-id`, an opaque snapshot handle, and the complete UUID. `/akk resume-thread <exact-terminal-id>` without a selection shows that list. A complete UUID remains compatible. A number or short ID resolves only against the latest list displayed in the same OpenClaw session, while an opaque handle names its exact snapshot; all expire after five minutes and fail after terminal, process, workspace, binding, candidate-set, or relevant action changes. None is ever passed to Codex or Claude Code as native identity: AKK resolves the saved tuple back to its full UUID and fresh evidence tokens first. `previous` (or `刚才那个`) is advertised only when the current Session's latest committed lifecycle transition identifies exactly one currently verified resumable source; it never guesses from title, recency, or static lineage. `/akk new-thread` and its human alias `/akk clear-thread` start a clean context. AKK does not poll bindings in the background: if a recorded owner process exits, the next lifecycle listing can classify that sole historical binding as resumable, and the resume mutation compare-and-swap detaches it before touching the terminal. Live, stale, expired, unsupported, busy, ambiguous, active-elsewhere, or unverifiable transitions fail closed. Do not send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, or `/btw`, Claude `/branch`, or any other first-line native slash command as an ordinary task or answer; use an advertised AKK action, express the request in natural language, or enter an unsupported native command manually in tmux.
 
 For natural-language tool use, `agent_knock_knock_list` is terminal-first. Each live pane appears exactly once in `terminals[]`; `process_state` reports whether its coding-agent process is alive and `activity_state` reports the parsed screen state. `managed.session_id` identifies the continuing AKK session, `managed.current_turn` is its optional active Turn, and `managed.recent_turn` is retained history; retained Turns do not occupy the terminal. Pass `all=true` to include older entries in `managed.history`. By default, `unavailable_managed_turns[]` contains attention-needed records whose pane cannot be presented as a live terminal; `all=true` also includes retained unavailable history.
 
 Use only an `available_actions` entry returned in that snapshot, begin with its prefilled authoritative arguments, and supply every `missing_required` field. A managed Session's `send` uses its prefilled `session_id` and creates a new Turn. For first attach only, use a discovery selector explicitly named by the user or the unmanaged raw-terminal row's prefilled `selector`; do not infer or reuse one. `respond` is available only while a Turn is `waiting_for_openclaw`; it uses `turn_id` and keeps the answer inside that Turn. Managed status, approval, cancellation, renewal, callback retry, and close also use the exact `turn_id`. A raw terminal may be controlled only through the exact status, approval, cancellation, or orphan-close action that its own row advertises with a prefilled `conversation_id`; never construct or guess one. For an ordinary send, add only `request`—`timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK revalidates availability before every side effect.
 
-The top-level v5 `action_contracts` adds `list_resumable_threads`, `new_thread`, and `resume_thread`. The terminal row advertises `list_resumable_threads` and, when currently safe, `new_thread`. Listing is read-only, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` candidate row advertises its own `resume_thread` action. The `new_thread` and `resume_thread` mutations require that fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. A lifecycle result contains Session and native-thread identities but no `turn_id` because no work was sent.
+The top-level v5 `action_contracts` adds `list_resumable_threads`, `new_thread`, and `resume_thread`. The terminal row advertises `list_resumable_threads` and, when currently safe, `new_thread`. Listing is read-only with respect to Session/Turn state, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` row retains its complete UUID and exact prefilled `resume_thread` action. If `previous` is present, use only its exact prefilled action for a natural-language “刚才那个” request. Numbers, short IDs, and handles are human display/navigation aids, never tool arguments or authoritative native identity. The `new_thread` and `resume_thread` mutations require the fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. A lifecycle result contains Session and native-thread identities but no `turn_id` because no work was sent.
 
 Workspace is not a routing boundary. AKK can list, inspect, and control verified panes across projects; when more than one target matches, use a selector to choose one explicitly.
 

package/dist/src/cli.js

@@ -18,6 +18,7 @@ import { formatTranscript, readNdjsonLog } from "./transcript.js";
 import { appendEvent, assertStoreWriterCompatible, defaultStoreDir, ensureDir, ensureStoreWritable, inspectStoreCompatibility, listConversations, logPathForStatePath, loadConversationById, loadState, messageEvent, pathsForConversation, pathsForConversationDir, saveState, StoreLockTimeoutError, statePathForConversationId, withStoreWriterLease, withStoreWriterLeaseAsync } from "./store.js";
 import { createManagedSessionId, createNativeThreadTransitionId, isExactNativeThreadId, managedSessionBindingToken, nativeThreadCommandFingerprint, terminalBindingFrom, unmanagedTerminalBindingToken } from "./managed-session.js";
 import { classifyCodexLifecyclePostcondition, evaluateResumeCandidateAvailability, hasStrongCodexLifecycleIdentity, isFreshCodexPostProbeScreen } from "./native-thread-lifecycle-policy.js";
+import { createNativeThreadResumeSnapshot, nativeThreadCandidateSnapshotFingerprint, nativeThreadResumeSnapshotRowsMatchCandidates, resolveNativeThreadResumeSelection, saveNativeThreadResumeSnapshot, sortNativeThreadCandidates, terminalActionFingerprint, verifiedPreviousResumeCandidate } from "./native-thread-resume-snapshot.js";
 import { listManagedSessions, loadManagedSession, loadNativeThreadTransition, saveManagedSession, saveNativeThreadTransition, tryLoadManagedSession } from "./session-store.js";
 import { StaticTerminalControlProvider, TmuxTerminalControlProvider, terminalPaneContainsProcess } from "./terminal-control-provider.js";
 import { parseTerminalConversationId } from "./terminal-agent-adapter.js";
@@ -5219,7 +5220,7 @@ async function resumableThreadCandidates({ options, terminal, currentIdentity })
             });
         }
     }
-    return [...deduplicated.values()]
+    return sortNativeThreadCandidates([...deduplicated.values()]
         .map((candidate) => {
         const nativeThreadId = candidate.native_thread_id;
         const managed = managedByNativeId.get(nativeThreadId) ?? [];
@@ -5255,8 +5256,7 @@ async function resumableThreadCandidates({ options, terminal, currentIdentity })
                 ? new Date(Number(candidate.updated_at_ms)).toISOString()
                 : undefined
         };
-    })
-        .sort((left, right) => Number(right.updated_at_ms ?? 0) - Number(left.updated_at_ms ?? 0));
+    }));
 }
 function encodeThreadCandidateToken(token) {
     return Buffer.from(JSON.stringify(token), "utf8").toString("base64url");
@@ -5506,37 +5506,113 @@ async function runListResumableThreads(options) {
         terminal,
         currentIdentity: snapshot.identity
     });
+    const storeDir = storeDirFromOptions(options);
+    const workspace = path.resolve(terminal.terminalControl.currentPath ?? process.cwd());
+    const selectionScope = stringValue(options.selectionScope) ?? "cli:unscoped";
+    const resumeSnapshot = createNativeThreadResumeSnapshot({
+        storeDir,
+        selectionScope,
+        terminalId: terminal.conversationId,
+        agent: terminal.agent,
+        workspace,
+        terminalControl: terminal.terminalControl,
+        currentSessionId: snapshot.session?.session_id,
+        currentNativeThreadId: snapshot.identity?.sessionId ??
+            snapshot.session?.binding?.native_thread_id,
+        expectedBindingToken: snapshot.bindingToken,
+        terminalActionFingerprint: terminalActionFingerprint(loadTerminalBridgeDispatchLedger(terminal.terminalControl)),
+        candidates
+    });
+    saveNativeThreadResumeSnapshot(terminalBridgeRuntimeDir(), storeDir, resumeSnapshot);
+    const snapshotRows = new Map(resumeSnapshot.rows.map((row) => [row.native_thread_id, row]));
+    const resumeAction = (candidate) => ({
+        tool: "agent_knock_knock_resume_thread",
+        arguments: {
+            terminal_id: terminal.conversationId,
+            native_thread_id: candidate.native_thread_id,
+            expected_binding_token: snapshot.bindingToken,
+            ...(candidate.candidate_token
+                ? { candidate_token: candidate.candidate_token }
+                : {})
+        },
+        requires_user_intent: true
+    });
+    const previousCandidate = previousCommittedResumeCandidate({
+        storeDir,
+        terminal,
+        currentSession: snapshot.session,
+        candidates
+    });
+    const previousSnapshotRow = previousCandidate
+        ? snapshotRows.get(previousCandidate.native_thread_id)
+        : undefined;
     printJson({
         terminal_id: terminal.conversationId,
         agent: terminal.agent,
-        workspace: terminal.terminalControl.currentPath,
+        workspace,
         current_session_id: snapshot.session?.session_id ?? null,
         current_native_thread_id: snapshot.identity?.sessionId ??
             snapshot.session?.binding?.native_thread_id ??
             null,
         expected_binding_token: snapshot.bindingToken,
         capability: snapshot.capabilities,
+        selection_snapshot: {
+            schema: resumeSnapshot.schema,
+            version: resumeSnapshot.version,
+            snapshot_id: resumeSnapshot.snapshot_id,
+            created_at: resumeSnapshot.created_at,
+            expires_at: resumeSnapshot.expires_at,
+            scope: "exact selection snapshot, scope, and terminal",
+            display_only: true
+        },
+        ...(previousCandidate && previousSnapshotRow
+            ? {
+                previous: {
+                    keyword: "previous",
+                    native_thread_id: previousCandidate.native_thread_id,
+                    selection_number: previousSnapshotRow.selection_number,
+                    short_id: previousSnapshotRow.short_id,
+                    selection_handle: previousSnapshotRow.selection_handle,
+                    available_actions: {
+                        resume_thread: resumeAction(previousCandidate)
+                    }
+                }
+            }
+            : {}),
         threads: candidates.map((candidate) => ({
             ...candidate,
+            selection_number: snapshotRows.get(candidate.native_thread_id)?.selection_number,
+            short_id: snapshotRows.get(candidate.native_thread_id)?.short_id,
+            selection_handle: snapshotRows.get(candidate.native_thread_id)?.selection_handle,
+            selection_scope: "current_snapshot",
             available_actions: candidate.resumable
                 ? {
-                    resume_thread: {
-                        tool: "agent_knock_knock_resume_thread",
-                        arguments: {
-                            terminal_id: terminal.conversationId,
-                            native_thread_id: candidate.native_thread_id,
-                            expected_binding_token: snapshot.bindingToken,
-                            ...(candidate.candidate_token
-                                ? { candidate_token: candidate.candidate_token }
-                                : {})
-                        },
-                        requires_user_intent: true
-                    }
+                    resume_thread: resumeAction(candidate)
                 }
                 : {}
         }))
     });
 }
+function previousCommittedResumeCandidate({ storeDir, terminal, currentSession, candidates }) {
+    if (!currentSession?.last_transition_id) {
+        return undefined;
+    }
+    let transition;
+    try {
+        transition = loadNativeThreadTransition(storeDir, currentSession.last_transition_id);
+    }
+    catch {
+        return undefined;
+    }
+    return verifiedPreviousResumeCandidate({
+        terminalId: terminal.conversationId,
+        agent: terminal.agent,
+        workspace: terminal.terminalControl.currentPath ?? process.cwd(),
+        currentSession,
+        transition,
+        candidates
+    });
+}
 async function waitForVerifiedThreadTransition({ options, terminal, beforeIdentity, physicalBeforeIdentity, allowedCompanionIdentity, allowedAdditionalIdentities = [], operation, plan, initialScreenDigest }) {
     const bridge = createTerminalAgentBridge(options);
     let probeSent = false;
@@ -5812,15 +5888,96 @@ async function runNewThread(options) {
     });
 }
 async function runResumeThread(options) {
-    const nativeThreadId = required(stringValue(options.nativeThread ?? options.nativeThreadId), "--native-thread is required");
-    if (!isExactNativeThreadId(nativeThreadId)) {
-        throw new Error("--native-thread must be a complete native thread UUID");
+    const exactNativeThreadId = stringValue(options.nativeThread ?? options.nativeThreadId);
+    const hasSnapshotSelection = Boolean(options.selectionSnapshot ||
+        options.selectionNumber ||
+        options.selectionShortId ||
+        options.selectionHandle);
+    if (exactNativeThreadId && hasSnapshotSelection) {
+        throw new Error("--native-thread cannot be combined with a snapshot-bound selection");
+    }
+    if (exactNativeThreadId) {
+        if (!isExactNativeThreadId(exactNativeThreadId)) {
+            throw new Error("--native-thread must be a complete native thread UUID");
+        }
+        return runNativeThreadTransition(options, {
+            kind: "resume_thread",
+            nativeThreadId: exactNativeThreadId.toLowerCase()
+        });
     }
-    return runNativeThreadTransition(options, {
+    if (!hasSnapshotSelection) {
+        throw new Error("--native-thread or a snapshot-bound resume selection is required");
+    }
+    const terminal = await resolveLifecycleTerminal(options);
+    const storeDir = storeDirFromOptions(options);
+    const selectionScope = required(stringValue(options.selectionScope), "--selection-scope is required for snapshot-bound resume");
+    const rawSelectionNumber = options.selectionNumber;
+    if (rawSelectionNumber !== undefined &&
+        (typeof rawSelectionNumber !== "string" ||
+            !/^[1-9][0-9]*$/u.test(rawSelectionNumber))) {
+        throw new Error("--selection-number must be a positive integer");
+    }
+    const selectionNumber = rawSelectionNumber === undefined
+        ? undefined
+        : Number(rawSelectionNumber);
+    if (selectionNumber !== undefined &&
+        !Number.isSafeInteger(selectionNumber)) {
+        throw new Error("--selection-number must be a positive safe integer");
+    }
+    const selection = resolveNativeThreadResumeSelection({
+        runtimeDir: terminalBridgeRuntimeDir(),
+        storeDir,
+        terminalId: terminal.conversationId,
+        selectionScope,
+        snapshotId: stringValue(options.selectionSnapshot),
+        selectionNumber,
+        shortId: stringValue(options.selectionShortId),
+        selectionHandle: stringValue(options.selectionHandle)
+    });
+    assertResumeSnapshotMatchesTerminal(selection.snapshot, terminal);
+    assertResumeSnapshotActionFingerprint(selection.snapshot, terminal);
+    const selectedOptions = {
+        ...options,
+        expectedBindingToken: selection.snapshot.expected_binding_token,
+        candidateToken: selection.row.candidate_token
+    };
+    return runNativeThreadTransition(selectedOptions, {
         kind: "resume_thread",
-        nativeThreadId: nativeThreadId.toLowerCase()
+        nativeThreadId: selection.row.native_thread_id.toLowerCase(),
+        selectionSnapshot: selection.snapshot
     });
 }
+function assertResumeSnapshotMatchesTerminal(snapshot, terminal) {
+    const workspace = path.resolve(terminal.terminalControl.currentPath ?? process.cwd());
+    if (snapshot.terminal_id !== terminal.conversationId ||
+        snapshot.agent !== terminal.agent ||
+        path.resolve(snapshot.workspace) !== workspace ||
+        snapshot.terminal_control.target !== terminal.terminalControl.target ||
+        snapshot.terminal_control.socket_path !== terminal.terminalControl.socketPath ||
+        snapshot.terminal_control.pane_pid !== terminal.terminalControl.panePid) {
+        throw new Error("resume selection terminal, process, or workspace changed; run /akk threads again");
+    }
+}
+function assertResumeSnapshotActionFingerprint(snapshot, terminal) {
+    const current = terminalActionFingerprint(loadTerminalBridgeDispatchLedger(terminal.terminalControl));
+    if (current !== snapshot.terminal_action_fingerprint) {
+        throw new Error("terminal action history changed after the resume snapshot; run /akk threads again");
+    }
+}
+function assertResumeSnapshotCandidates(snapshot, candidates) {
+    if (nativeThreadCandidateSnapshotFingerprint(candidates) !==
+        snapshot.candidate_snapshot_fingerprint) {
+        throw new Error("resume candidates changed or reordered after the snapshot; run /akk threads again");
+    }
+    if (!nativeThreadResumeSnapshotRowsMatchCandidates(snapshot, candidates)) {
+        throw new Error("resume selection rows no longer match the exact candidate snapshot; run /akk threads again");
+    }
+}
+function assertResumeSnapshotNotExpired(snapshot) {
+    if (Date.parse(snapshot.expires_at) <= Date.now()) {
+        throw new Error("resume selection snapshot expired; run /akk threads again");
+    }
+}
 async function runNativeThreadTransition(options, operation) {
     const initiallyResolved = await resolveLifecycleTerminal(options);
     const storeDir = storeDirFromOptions(options);
@@ -5833,7 +5990,18 @@ async function runNativeThreadTransition(options, operation) {
                     terminalControlSelectorKey(initiallyResolved.terminalControl)) {
                 throw new Error("terminal identity changed while waiting for lifecycle control; refresh list");
             }
+            if (operation.kind === "resume_thread" && operation.selectionSnapshot) {
+                assertResumeSnapshotNotExpired(operation.selectionSnapshot);
+                assertResumeSnapshotMatchesTerminal(operation.selectionSnapshot, terminal);
+                assertResumeSnapshotActionFingerprint(operation.selectionSnapshot, terminal);
+            }
             await recoverLifecycleFenceBeforeMutation({ options, terminal });
+            if (operation.kind === "resume_thread" && operation.selectionSnapshot) {
+                // Recovery may resolve or otherwise rewrite a durable dispatch fence.
+                // A snapshot created before that mutation is stale even when the
+                // binding and candidate files themselves did not change.
+                assertResumeSnapshotActionFingerprint(operation.selectionSnapshot, terminal);
+            }
             const snapshot = await currentLifecycleSnapshot(options, terminal, { materialize: true });
             const expectedToken = required(stringValue(options.expectedBindingToken), "--expected-binding-token is required");
             if (expectedToken !== snapshot.bindingToken) {
@@ -5850,6 +6018,14 @@ async function runNativeThreadTransition(options, operation) {
                 snapshot.capabilities.resumeExact !== true) {
                 throw new Error(snapshot.capabilities.reason);
             }
+            if (operation.kind === "resume_thread" && operation.selectionSnapshot) {
+                const guardedCandidates = await resumableThreadCandidates({
+                    options,
+                    terminal,
+                    currentIdentity: snapshot.identity
+                });
+                assertResumeSnapshotCandidates(operation.selectionSnapshot, guardedCandidates);
+            }
             const plan = snapshot.adapter.planThreadLifecycle?.(operation, snapshot.capabilities);
             if (!plan) {
                 throw new Error("the agent adapter did not produce a lifecycle plan");
@@ -5960,6 +6136,13 @@ async function runNativeThreadTransition(options, operation) {
                     terminal,
                     currentIdentity: beforeIdentity
                 });
+                if (operation.selectionSnapshot) {
+                    // The Codex identity probe and other readiness checks above are
+                    // asynchronous. Rebind the whole displayed snapshot, not only its
+                    // selected UUID, after those checks and before any lifecycle state
+                    // is persisted.
+                    assertResumeSnapshotCandidates(operation.selectionSnapshot, candidates);
+                }
                 const candidate = candidates.find((entry) => entry.native_thread_id === operation.nativeThreadId);
                 if (!candidate) {
                     throw new Error(`native thread ${operation.nativeThreadId} is not a verified same-workspace candidate`);
@@ -6169,6 +6352,9 @@ async function runNativeThreadTransition(options, operation) {
                         terminalControl: terminal.terminalControl
                     });
                 }
+                if (operation.kind === "resume_thread" && operation.selectionSnapshot) {
+                    assertResumeSnapshotNotExpired(operation.selectionSnapshot);
+                }
                 inputStarted = true;
                 await bridge.send(terminal.agent, terminal.terminalControl, transitionStep.command, { runtime: beforeRuntime });
                 const submittedAt = new Date().toISOString();
@@ -18165,8 +18351,9 @@ function usage() {
   agent-knock-knock send [--session <session-id|selector>] [--conversation <selector>] --message <text> [--type task] [--agent-timeout-minutes <minutes>] [--agent-hard-timeout-minutes <minutes>]
   agent-knock-knock new-thread --terminal <exact-terminal-id> --expected-binding-token <token>
   agent-knock-knock clear-thread --terminal <exact-terminal-id> --expected-binding-token <token>
-  agent-knock-knock list-resumable-threads --terminal <exact-terminal-id>
+  agent-knock-knock list-resumable-threads --terminal <exact-terminal-id> [--selection-scope <opaque-scope>]
   agent-knock-knock resume-thread --terminal <exact-terminal-id> --native-thread <uuid> --expected-binding-token <token> --candidate-token <token>
+  agent-knock-knock resume-thread --terminal <exact-terminal-id> (--selection-handle <handle> | --selection-snapshot <id> (--selection-number <n> | --selection-short-id <@id>)) --selection-scope <opaque-scope>
   agent-knock-knock respond --turn <turn-id|selector> --message <text> [--conversation <selector>]
   agent-knock-knock approve [--turn <turn-id|selector>] [--conversation <selector>] --expected-approval-fingerprint <fingerprint>
   agent-knock-knock cancel [--turn <turn-id|selector>] [--conversation <selector>]