@scotthuang/agent-knock-knock 0.13.17 → 0.14.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-knock-knock",
   "name": "Agent Knock Knock",
   "categories": ["developer-tools"],
-  "description": "Control local Codex and Claude Code through shared tmux or Herdr terminals, with closed native status inspection, model switching, and Codex permission control, compatibility warnings for unverified versions, native-thread lifecycle controls, managed monitoring, durable Terminal Watch, approvals, and human takeover.",
+  "description": "Select a conversation once; AKK prefers its verified backend, coalesces only exact terminal associations and preserves eligible terminal fallback without replaying uncertain input. Control loaded Codex CLI threads directly through their backend for discovery, tasks, exact completion callbacks, approvals, answers and permission settings without tmux or Herdr. Discover Codex Desktop persisted expanded sidebar members or explicitly search history, retain unconnected rows, send tasks to live owners, watch exact completion, approve or reject command/file requests, answer blocking and asynchronous questions, adjust current-conversation permissions and model settings, and cancel exact tasks. Control Codex and Claude Code through shared tmux or Herdr terminals, with closed native status inspection, model and permission control, compatibility warnings, native-thread lifecycle controls, managed monitoring, durable Terminal Watch, approvals, and human takeover.",
   "activation": {
     "onStartup": true,
     "onCommands": ["akk"]
@@ -35,6 +35,7 @@
       "agent_knock_knock_respond",
       "agent_knock_knock_respond_interaction",
       "agent_knock_knock_renew",
+      "agent_knock_knock_recover",
       "agent_knock_knock_retry_callback",
       "agent_knock_knock_cancel",
       "agent_knock_knock_close",
@@ -102,6 +103,9 @@
     "agent_knock_knock_renew": {
       "optional": true
     },
+    "agent_knock_knock_recover": {
+      "optional": true
+    },
     "agent_knock_knock_retry_callback": {
       "optional": true
     },
@@ -124,7 +128,7 @@
     "properties": {
       "storeDir": {
         "type": "string",
-        "description": "Stable AKK Store root. Defaults to ~/.agent-knock-knock/store and contains the compatibility manifest, authoritative managed Sessions and Turns, plus durable Terminal Watch records."
+        "description": "Stable AKK Store root. Defaults to ~/.agent-knock-knock/store and contains the compatibility manifest, authoritative managed Sessions and Turns, plus durable terminal and Desktop Watch records."
       },
       "openclawBin": {
         "type": "string",
@@ -132,7 +136,7 @@
       },
       "codexHome": {
         "type": "string",
-        "description": "Optional CODEX_HOME path used to correlate Codex session metadata with eligible terminal panes."
+        "description": "Optional CODEX_HOME path used for Codex terminal metadata and local Desktop conversation discovery and IPC."
       },
       "idleTimeoutMinutes": {
         "type": "number",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.13.17",
-  "description": "Control local Codex and Claude Code from OpenClaw or compatible controller Hosts through shared terminals.",
+  "version": "0.14.0",
+  "description": "Control Codex CLI through its shared backend, Codex Desktop through native IPC, and Codex or Claude Code through terminals from OpenClaw or compatible controller Hosts.",
   "license": "MIT",
   "type": "module",
   "homepage": "https://github.com/scotthuang/agent-knock-knock#readme",
@@ -79,20 +79,14 @@
     "assets/icon.png",
     "docs/assets/agent-knock-knock-cover.jpg",
     "docs/assets/agent-knock-knock-icon.png",
-    "docs/quickstart-herdr.md",
-    "docs/quickstart-tmux.md",
-    "docs/codex-0.157.1-compatibility.md",
-    "docs/host-bridge-profiles.md",
     "openclaw.plugin.json",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "docs/codex-0.158.0-compatibility.md",
-    "docs/codex-0.159.0-compatibility.md",
-    "docs/codex-0.159.2-compatibility.md",
-    "docs/claude-2.1.285-compatibility.md",
-    "docs/callback-compatibility.md",
-    "docs/codex-permissions.md"
+    "docs/**/*.md",
+    "CONTRIBUTING.md",
+    "connectors/pi/README.md",
+    "connectors/deepseek-harness/README.md"
   ],
   "publishConfig": {
     "access": "public"

package/templates/openclaw-skills/agent-knock-knock/SKILL.md

@@ -1,22 +1,72 @@
 ---
 name: agent-knock-knock
-description: Control local Codex and Claude Code through shared tmux or Herdr terminals with Agent Knock Knock.
+description: Discover and control loaded Codex CLI threads, existing Codex Desktop conversations, or Codex and Claude Code tmux/Herdr terminals with Agent Knock Knock.
 ---
 
 # Agent Knock Knock
 
-Use this skill when the user explicitly invokes `AKK`, `akk`, or `Agent Knock Knock`, or asks a supported controller Host to inspect or control a coding-agent terminal listed by AKK.
+Use this skill when the user explicitly invokes `AKK`, `akk`, or `Agent Knock Knock`, or asks a supported controller Host to inspect or control a coding-agent conversation listed by AKK.
 
-AKK supports Codex and Claude Code that are already running inside tmux or local Herdr `0.8.0`. It never launches a coding agent. The controller Host, terminal host, AKK, and coding agent must run as the same OS user.
+AKK supports loaded local Codex CLI threads through their shared backend, existing local Codex Desktop conversations, and Codex or Claude Code already running inside tmux or local Herdr `0.8.0`. It never launches a replacement coding agent. The controller Host, AKK, the coding agent, and its Desktop app or terminal host must run as the same OS user.
 
 Treat `AKK` and `akk` the same way.
 
 ## Role
 
-The controller Host interprets the user's request, sends the requested work into the selected shared terminal, handles actionable callbacks, and reports the outcome. The coding agent performs the engineering work in its existing tmux or Herdr terminal.
+The controller Host interprets the user's request, sends the requested work into the selected conversation, handles actionable callbacks, and reports the outcome. The coding agent performs the engineering work in its existing CLI backend thread, Desktop conversation, or tmux/Herdr terminal.
 
 Keep the user's requested scope and approval boundaries. Do not expand a task, approve a permission, interrupt a process, or close a managed record unless the user request or an explicit trusted policy authorizes that action.
 
+## Choose a conversation
+
+Use `conversations[]` from List as the primary collection and select by title, project and current identity. Choose the row's exact conversation and advertised operation; AKK chooses the route, including Status, Send, Watch and permission controls. Callers do not select between a backend and a terminal. For a proven terminal/backend match, `terminal_controls[]` preserves that terminal’s managed Turns, recovery and capability-specific actions inside the conversation row; these are controls for the same conversation, not extra tasks. The raw CLI retains `terminals[]`, `codex_cli_sessions[]` and `desktop_sessions[]` for compatibility and private authority, but do not present these again as extra conversations when `conversations[]` exists.
+
+AKK prefers the reachable Codex backend only when it proves the exact current native thread. A terminal and backend row merge only with exact identity evidence, never matching cwd, title, newest history or version alone. Unresolved representations may remain separate; do not assume they are different tasks or send twice. The routing diagnostics describe available evidence, not authority to skip a guard. An unavailable backend may retain an eligible terminal path; a busy, blocked or mismatched native task is not an excuse to try terminal input. For a selected physical terminal without a proven native anchor, targeted conversation operations, including Status, may run an advertised idle-only `/status` identity inspection when backend candidates exist. This can display a native status card but submits no user task; a working or blocked terminal is not interrupted. List sends no terminal input. If a dispatch is uncertain, keep its receipt and inspect it instead of retrying another route.
+
+Use the returned `watch_id` or `turn_id` for that task's follow-up. Existing Watches and pending interactions keep their task and route. After a question or approval callback, refresh that exact Status and copy the current interaction action; do not translate its IDs to another transport. Permission operations prefer the verified backend. Backend task recovery retains the original task identity and provider. Terminal binding/menu recovery, model and lifecycle operations retain their separately advertised capability; the caller does not pick a transport. The route-specific guidance below explains those capabilities and result boundaries, not an additional route-selection step.
+
+## Recover a backend task
+
+For direct Codex CLI and Desktop, use the exact returned `watch_id` or Send `turn_id`; never substitute a conversation ID or guess its latest task. The Host supplies the owning controller identity. Read `task_kind`, `management_state`, `observation_state`, and the advertised actions separately.
+
+- `recover({watch_id})` rechecks the original thread/task and original submission receipt, updates persisted evidence and restarts eligible monitoring. It does not resend work, change the task anchor, extend a deadline, or resume explicitly stopped observation.
+- `renew({watch_id,minutes})` verifies the original task and extends its observation deadline. It can resume an expired or unwatched task; a task already finished returns its actual outcome. Closed management cannot be reopened.
+- `unwatch({watch_id})` stops observation and withdraws unsent notifications. It does not release a managed Send or cancel Codex work.
+- `close({turn_id})` ends Send management and stops its observation. It also releases an unresolved Send reservation without claiming that the native send failed. A standalone Watch is not a managed Send: use Unwatch for it.
+- `retry_callback({watch_id,notification_id})` retries one eligible recorded callback using its original notification ID, payload and controller target. Omit `notification_id` only when exactly one callback is eligible. Accepted, in-flight, uncertain and obsolete callbacks are not replayed; a pending interaction must be revalidated. This does not rerun the task or fix a later WeChat/channel failure.
+
+Callbacks already in flight cannot be recalled by Close or Unwatch. `accepted` proves controller acceptance, not user-visible channel delivery. Terminal-specific `reconcile_binding`, `identify_foreground` and `repair_model_control` retain their original terminal semantics; backend Recover performs exact task reconciliation instead.
+
+## Direct Codex CLI
+
+A `conversations[]` row with `source="codex_cli"` uses an exact `codex-cli:v1:...` conversation ID. This route addresses the existing loaded backend thread and works without tmux or Herdr. It never starts a replacement CLI or treats saved history as a live owner. Embedded CLI sessions without a reachable shared backend continue to use the terminal route. Desktop uses its separate route below.
+
+- Select by the returned title, working directory and native thread identity. Copy the advertised action; do not construct IDs, infer thread ownership from the newest same-directory history, or substitute another target. Unresolved physical terminal and direct thread rows can refer to the same work; select one conversation and send once.
+- Send with `agent_knock_knock_send({conversation_id,request})`. AKK preserves current settings, submits once and returns `codex-cli-watch:...` for the accepted native task. Keep the receipt if acceptance is uncertain; refresh its Status instead of blindly sending again.
+- Read the current thread with `agent_knock_knock_status({conversation_id})`. Watch an already-running exact task with `agent_knock_knock_watch({conversation_id})`; use `agent_knock_knock_status({watch_id})` for that task's result. A later idle state or different completed task is not evidence that the watched task succeeded. `agent_knock_knock_unwatch({watch_id})` only stops observation.
+- When a callback reports a question or approval, refresh Status for that exact conversation or Watch and present the current request. Use `agent_knock_knock_respond_interaction` with that same `conversation_id` or `watch_id`, the current `interaction_id`, and the advertised typed `answers`. Blocking questions and async questions are supported; async delivery is `steer_current_turn` only. For authorized command/file approval, use `agent_knock_knock_approve` with the same target, exact `interaction_id`, and the advertised `approve_once` or `reject` decision. The backend revalidates the native request and task; no terminal tokens, raw keys or menu indexes are needed.
+- Inspect permissions using `agent_knock_knock_permission_options({conversation_id})`, then apply the requested or authorized `read-only`, `default`, or `full-access` with `agent_knock_knock_set_permissions({conversation_id,mode})`. Full Access is a normal option with no additional confirmation. AKK waits for the effective thread setting before reporting success; global defaults stay unchanged and no task is created. Send permission-dependent work only after the setting is verified.
+
+Use AKK's advertised actions and read the actual operation result after backend upgrades. A missing backend method fails that operation with an unsupported-capability diagnostic; it does not justify sending UI input to a guessed terminal. Existing terminal and Desktop capabilities retain their own limits. Model selection and native thread lifecycle operations are not added to this direct route.
+
+## Codex Desktop
+
+Desktop rows in `conversations[]` have `source="codex_desktop"` and a full `desktop:v1:...` conversation ID. Their owner identity is separate from terminal selectors, managed Sessions, and managed Turns. The terminal-specific instructions below do not grant Desktop input authority.
+
+- List defaults to `desktop_view: "sidebar"`: persisted expanded sidebar membership, including eligible pinned threads and expanded project members. This is not a live screen or scroll-viewport snapshot. Present all returned rows, including unconnected conversations, and distinguish them from rows that can receive tasks. Report `desktop_scan` limitations when the saved layout cannot be reconstructed; do not silently substitute the historical catalog.
+- Find the intended row by title and project. Use `desktopSearch`, `desktopProject`, `desktopLimit`, and returned pagination cursor as `desktopCursor` within the same view. Use `desktop_view: "history"` explicitly to search the broader saved catalog for an older or hidden conversation. Do not assume the first page is complete or treat `live_count` as a count across unreturned pages. If several rows match, show their titles and project paths; do not invent IDs or ask for a deep link when List can discover the target.
+- Sidebar and historical metadata can include unloaded conversations and entries whose original creator is unknown or was a CLI. Membership does not prove a current Desktop owner or task. Use the row's live state and advertised actions; keep an unavailable row visible rather than silently substituting another conversation. Desktop cannot open, load, resume, or create a conversation. If it has no verified live owner, tell the user to open that exact conversation in Desktop and refresh List before Send.
+- Send a new task with `agent_knock_knock_send({conversation_id,request})`, using the exact listed Desktop ID and no `session_id`, `terminal_id`, or `turn_id`. The trusted Host supplies the stable message identity. AKK requires a freshly verified idle thread with no pending question, approval, or unconfirmed input, preserves its current settings, and attempts task submission once. It never sends a task through a replacement CLI, steers known active work, or retries uncertain input. Use the returned `watch_id` for follow-up; delivery uncertainty is not proof of acceptance or failure.
+- Inspect the conversation with `agent_knock_knock_status({conversation_id})`. For an exact task's outcome use `agent_knock_knock_status({watch_id})`; a conversation becoming idle is not proof that the watched task succeeded. Each Desktop Watch remains bound to its original native task even when another task starts later.
+- Observe an already-running Desktop task with `agent_knock_knock_watch({conversation_id})`. This requires one exact active native task; an idle or unknown conversation does not fall back to terminal-activity observation. Keep its `desktop-watch:...` ID. `agent_knock_knock_unwatch({watch_id})` stops observation without interrupting work.
+- Desktop asynchronous questions appear in fresh Status as `interaction_state` with `kind: "async_question"`. A Watch notification prompts the controller to refresh Status, show the question and options, and wait for the user’s answer. Refresh again, then call `agent_knock_knock_respond_interaction` with that exact conversation or Watch and its advertised interaction/question/option IDs. Only the same active task can receive an answer (`steer_current_turn`); do not turn an expired question into a new task. Receipts are durable: inspect later Status `response_state` to recover them without resending. `sent` is an acknowledgement, while `confirmed` includes native answer evidence. Never replay an uncertain answer.
+- Desktop blocking questions use the same `respond_interaction` tool with every advertised question answered in one response; omit `delivery_mode`. Command and file approvals use `approve` with the exact conversation or Watch, current `interaction_id`, and explicit user decision `approve_once` or `reject`. Refresh Status in the same controller conversation before acting. Native requests outside these supported forms remain manual. A notification does not authorize choosing an answer or granting permission.
+- For an idle Desktop conversation, use `permission_options({conversation_id})` and `set_permissions({conversation_id,mode})` for `read-only`, `default`, or `full-access`. Full Access is an ordinary user-selectable preset without a second confirmation. This affects only the selected conversation; ordinary Send preserves its settings. Read `applied` and `effective`: a native acknowledgement alone is not proof that settings changed.
+- `model_options({conversation_id})` reads the current model, reasoning effort, and Plan/default mode. Desktop does not expose a model catalog (`catalog_available=false`). Use `set_model({conversation_id,model,reasoning_effort,collaboration_mode?})` only with an explicitly requested model ID; optional `collaboration_mode` is `plan` or `default`. Omitting it preserves the existing mode. Effective settings do not prove a model is available to the account. An unconfirmed update must be inspected, not blindly replayed.
+- Cancel with `cancel({watch_id})` for the exact watched task, or `cancel({conversation_id,expected_native_turn_id})` using the native task ID advertised by fresh Status. A late cancel must never interrupt a newer task. `unwatch` only stops observation. New conversations and cold loading/resume remain unsupported.
+
+Desktop control is reviewed for macOS Codex Desktop `26.1002.52244` build `13536` through private local IPC. Read the actual capability and error result after an app update; never downgrade to raw UI input or relax identity checks. The native protocol has no atomic idle-and-send operation, so concurrent human input can make acceptance uncertain. Preserve the returned Watch and reconcile it instead of repeating the task.
+
 ## Chat Routing
 
 Use the `/akk` command for slash-command syntax. Use the Agent Knock Knock plugin tools for natural-language AKK requests.
@@ -25,7 +75,7 @@ Core slash-command forms:
 
 - `/akk <task>`: send a new task only when exactly one send-ready coding-agent pane exists across all workspaces.
 - `/akk <selector>: <message>`: resolve one exact eligible AKK session and create a new Turn for the message.
-- `/akk list`: list live coding-agent terminals, their current or recent managed-turn context, and durable Terminal Watches.
+- `/akk list`: list coding-agent conversations, their managed-turn context, persisted expanded Desktop sidebar members, and durable Watches, coalescing only exact terminal/backend matches. Use the semantic tools above for Desktop history discovery and task operations.
 - `/akk watch <exact-terminal-id>`: observe one exact user-selected terminal without submitting a task or creating a Session or Turn; prefer an exact task anchor and otherwise use a clearly labeled best-effort terminal-activity Watch.
 - `/akk unwatch <watch-id>`: cancel only that observation; do not interrupt or otherwise change the TUI task.
 - `/akk threads <exact-terminal-id>`: list verified native threads that may be resumed in one exact terminal.
@@ -44,7 +94,7 @@ For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`,
 
 The human-priority Codex path may proceed when the pane/process and complete open-rollout candidate inventory are exact even though no single foreground UUID can be selected, including a supported manual `/clear` whose new logical thread appears before its rollout materializes. The complete exact inventory domain binds the provider terminal, PID and process birth, workspace and canonical endpoint, and every open rollout's UUID, descriptor, device, inode, canonical path, and pre-submit byte offset. A `/clear` resume hint is advisory only, never routing or acceptance authority. Under the terminal lock, AKK isolates the predecessor, creates a separate zero-UUID provisional Session and Turn, sends the real task once, and binds only the single candidate rollout that durably accepts that exact request. A rollout-backed Codex row therefore advertises `terminal_follow_current` with `terminal_id`, not `session_exact`; a cached strict Session attempt rejects before task text and never downgrades itself. Only released predecessor Turn history from a strictly earlier binding epoch is excluded from current-send authority; unresolved current-epoch state still blocks. Use only the freshly listed semantic-ID action. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. If delivery or acceptance is uncertain, do not retry automatically. Terminal-scoped manual Codex approval likewise exposes only `terminal_id`, requires explicit confirmation, leaves managed identity unchanged, never participates in auto-approval, and must not be retried blindly after an uncertain result.
 
-For an exact-empty idle Codex pane whose native identity is ambiguous, List may advertise `identify_foreground` and `identify_and_send`. `agent_knock_knock_identify_foreground({terminal_id})` is explicit and Codex-only: it mutates no Store record but does send `/status` and Enter exactly once to the visible pane. Its 30-second proof is diagnostic, never reusable authority; do not feed its UUID or expiry into another tool. `agent_knock_knock_identify_and_send({terminal_id,request})` keeps one terminal lock across the probe and task and is the only actionable consumer of that observation. It still binds a durable Session/Turn only from unique exact request acceptance. A changed or uncertain probe sends no task and must not be retried automatically. Never invoke either action unless the current terminal row advertises it. List and Status do not run `/status`. Ordinary Send must not be redirected through these explicit identification tools implicitly; Codex 0.158.0 and later stable semantic versions may attempt their separate closed `/status` transaction for exact paginated Watch binding when the actual UI and read contract can be proven.
+For an exact-empty idle Codex pane whose native identity is ambiguous, List may advertise `identify_foreground` and `identify_and_send`. `agent_knock_knock_identify_foreground({terminal_id})` is explicit and Codex-only: it mutates no Store record but does send `/status` and Enter exactly once to the visible pane. Its 30-second proof is diagnostic, never reusable authority; do not feed its UUID or expiry into another tool. `agent_knock_knock_identify_and_send({terminal_id,request})` keeps one terminal lock across the probe and task and is the only actionable consumer of that observation. It still binds a durable Session/Turn only from unique exact request acceptance. A changed or uncertain probe sends no task and must not be retried automatically. Never invoke either action unless the current terminal row advertises it. List does not run `/status`. Targeted conversation Status may use the separate idle routing inspection above, not this diagnostic-only action. Ordinary Send must not be redirected through these explicit identification tools implicitly; Codex 0.158.0 and later stable semantic versions may attempt their separate closed `/status` transaction for exact paginated Watch binding when the actual UI and read contract can be proven.
 
 The private approval fence remains prompt-scoped. It binds the adapter-isolated exact unredacted approval region plus terminal/process identity, decision keys and label, prompt kind, working directory, reason/detail, and request or policy evidence. The whole-screen digest and redacted excerpt are diagnostic only: output outside the approval region may continue scrolling without invalidating the same reviewed prompt. After explicit user confirmation, the plugin/CLI retains a private confirmation offer and recaptures the region under lock. Any change inside the exact region—including a command or otherwise identically redacted secret—rejects and sends zero approval keys. Never expose, persist as public action data, log, infer, or reconstruct the raw prompt evidence or its opaque fingerprint.
 
@@ -57,7 +107,7 @@ AKK discovers eligible panes across workspaces. When more than one target matche
 Natural-language forms:
 
 - `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one send-ready pane exists. A scanned blocked approval or proven input-owning questionnaire, editor, menu, or read-only viewer vetoes physical Send; parsed working activity and an existing draft do not. Unreviewed Codex frontends require the styled-Composer checks above; reviewed physical Send paths do not require ordinary main-Composer visibility. Codex replaces the current Composer with `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request and submits exactly once. Broken or stale AKK management activity records do not veto that independently verified live terminal/process.
-- `AKK Codex: <task>`: list first, require one exact eligible Codex row, then call `agent_knock_knock_send` with that row's `terminal_id` and `request=<task>`.
+- `AKK Codex: <task>`: list first and identify one exact eligible Codex conversation. For a direct CLI or Desktop row, copy its advertised Send with `conversation_id`; for a terminal row use its `terminal_id`. Send `request=<task>` once through that route. Do not count duplicate representations of the same proven thread as separate tasks.
 - `AKK Claude: <task>`: list first, require one exact eligible Claude row, then call `agent_knock_knock_send` with that row's `terminal_id` and `request=<task>`.
 - Requests to list AKK or local coding-agent work: call `agent_knock_knock_list`.
 - Requests to observe an exact Codex or Claude Code terminal: normally call `agent_knock_knock_list` and copy that row's advertised `watch` action, then pass its complete `terminal_id`. If the user explicitly selected a complete exact terminal ID, missing `available_actions.watch` is not a veto: Watch may still be called with that ID. Never guess, shorten, or substitute a selector. AKK prefers an exact task anchor and otherwise records warnings and observes the terminal/process activity epoch.
@@ -80,7 +130,7 @@ Natural-language forms:
 
 ## Sessions and Turns
 
-AKK's identity hierarchy is terminal → native Codex or Claude Code session → AKK session → Turns. `session_id` is the strict ordinary-send target for one exact native context. `terminal_id` is the deliberately different follow-current target that lets the user hand the pane's currently verified context back to AKK after a safe human-driven switch. Each accepted managed Send creates a distinct `turn_id` without clearing the native agent context; Codex paginated physical Send instead returns an independent exact-task or terminal-activity Watch when observation can be attached. A `turn_id` is used for history, callbacks, respond, status, approval, cancellation, renewal, callback retry, close, and the explicitly advertised submission-retry form of Send.
+For terminal resources, AKK's identity hierarchy is terminal → native Codex or Claude Code session → AKK session → Turns. Direct Codex CLI uses its `conversation_id` and independent `codex-cli-watch:...` records; Desktop uses `conversation_id` and `desktop-watch:...`, as described above. `session_id` is the strict terminal ordinary-send target for one exact native context. `terminal_id` is the deliberately different follow-current target that lets the user hand the pane's currently verified context back to AKK after a safe human-driven switch. Each accepted managed Send creates a distinct `turn_id` without clearing the native agent context; Codex paginated physical Send instead returns an independent exact-task or terminal-activity Watch when observation can be attached. A `turn_id` is used for history, callbacks, respond, status, approval, cancellation, renewal, callback retry, close, and the explicitly advertised submission-retry form of Send.
 
 Use `agent_knock_knock_send` with `request` and neither `session_id` nor `terminal_id` only when the target is unspecified. AKK must resolve exactly one eligible Codex or Claude Code pane across all workspaces and use its currently advertised Send path. Managed delivery attaches or discovers its AKK session and verifies idle before input; Codex paginated physical Send does not require a managed Session and follows its terminal input-safety checks. If no eligible pane exists, report AKK's setup guidance; do not substitute another execution path.
 
@@ -90,9 +140,9 @@ For ordinary send or an in-flight answer:
 
 1. Reuse an AKK session only when the user's reference uniquely identifies its verified native session and terminal incarnation.
 2. If no ID is supplied and more than one eligible pane may exist, call `agent_knock_knock_list`.
-3. Treat `terminals[]` as the primary resource list. Its managed context exposes `session_id`; `managed.current_turn` is the only current AKK owner, while `managed.recent_turn` and `managed.history` are retained Turn history. Records in `unavailable_managed_turns[]` have no live pane in this snapshot.
+3. Treat `conversations[]` as the primary resource list; older raw CLI output may expose `terminals[]` instead. For a terminal-backed row, its managed context exposes `session_id`; `managed.current_turn` is the only current AKK owner, while `managed.recent_turn` and `managed.history` are retained Turn history. Records in `unavailable_managed_turns[]` have no live pane in this snapshot.
 4. Read the selected resource's `available_actions`. In the compact Host projection its keys are the exact current action names and each value is `true`; `action_inputs`, when present, carries only dynamic semantic arguments, `missing_required`, and scope. For every mutation, use only an advertised action, start with those semantic inputs, supply every `missing_required` field, and follow this skill's action rules. User-selected Watch is the exception: explicit user intent plus one complete exact `terminal_id` is sufficient even when `available_actions.watch` is absent. The only additional mutation sources are a terminal row's `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`: use either only after explicit user confirmation and refresh the list immediately afterward.
-5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context and may require exact empty before input. If the selected row advertises terminal-scoped send, call `agent_knock_knock_send({terminal_id,request})`. `terminal_follow_current` may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. `terminal_user_explicit` instead preserves the user's Send when internal AKK state is broken: Codex replaces the current Composer with `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the new request and submits exactly once without a post-text Composer veto. For source-less Codex sends, zero exact acceptors remains pending for monitor recovery, one promotes the provisional Session/Turn, and multiple acceptors or identity drift becomes uncertain without replay. Managed delivery is attempted where eligible, but a proven zero-input failure falls back to one unmanaged delivery with no managed callback Turn. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Wait for an attached Watch callback or use its status as recovery. The status-card-only first-task path remains the zero-rollout special case. `send({turn_id})` is never an ordinary target: use it only for a fresh `retry_submission` action after explicit confirmation, with no other field. Never construct or pass an opaque fence or composer authority. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
+5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context and may require exact empty before input. For an ordinary selected conversation, call `agent_knock_knock_send({conversation_id,request})`; terminal-scoped rows also accept legacy `terminal_id`. The following physical-input rules apply only if AKK selects terminal delivery. `terminal_follow_current` may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. `terminal_user_explicit` instead preserves the user's Send when internal AKK state is broken: Codex replaces the current Composer with `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the new request and submits exactly once without a post-text Composer veto. For source-less Codex sends, zero exact acceptors remains pending for monitor recovery, one promotes the provisional Session/Turn, and multiple acceptors or identity drift becomes uncertain without replay. Managed delivery is attempted where eligible, but a proven zero-input failure falls back to one unmanaged delivery with no managed callback Turn. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Wait for an attached Watch callback or use its status as recovery. The status-card-only first-task path remains the zero-rollout special case. `send({turn_id})` is never an ordinary target: use it only for a fresh `retry_submission` action after explicit confirmation, with no other field. Never construct or pass an opaque fence or composer authority. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
 6. If multiple terminals match, show their `short_ref`, agent, provider, and terminal target, then ask the user to choose. If a human switch has an unresolved Turn, ambiguous ownership, or unverifiable identity and no follow-current send is advertised, report that blocker and ask the user which context to resolve; never guess, supersede active work, or bypass the fence.
 
 An idle pane is at a verified ready prompt, with no current work or unresolved permission request. A previously completed managed turn alone is not proof that the pane is still idle.
@@ -117,7 +167,7 @@ Approval attention is notification-only for every Watch: never call an approval
 
 The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v30. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v1 and point here for the static contract; the CLI keeps the complete operator/debug action contract. Every structured model action carries semantic IDs only; opaque fences, Composer digests, and draft text are derived or retained privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
 
-For Codex permission changes, first call `agent_knock_knock_permission_options({terminal_id})` from the current row’s advertised action. This sends closed `/status` and `/permissions` inspection input but leaves permissions unchanged; the terminal must be idle, its Composer empty, and its physical and native thread identities verifiable. Use `current`, `scope`, and the returned choice descriptions to select the requested or authorized mode. Then call `agent_knock_knock_set_permissions({terminal_id,mode})` using its exact returned semantic ID in the same controller conversation. Full Access is an ordinary option and needs no additional user confirmation. AKK automatically handles its exact native confirmation inside this permission transaction; do not pause to ask the user to confirm Full Access or call generic `approve` for that dialog. Ordinary Send does not change permissions. Only currently displayed built-in modes are supported: do not invent `read_only` when the picker omits it, supply a named/custom profile, or pass commands, labels, menu indexes, keys, tokens, or scope overrides. Changes affect the current session/thread, may be retained on Resume, and leave global defaults unchanged. Send the intended task only after `outcome="changed"` or `"already_effective"` with matching `effective.mode`; `"uncertain"` means stop and do not retry automatically. Refresh the catalog after any change or consumed attempt.
+For Codex permission changes, first call `agent_knock_knock_permission_options({terminal_id})` from the current row’s advertised action. This sends closed `/status` and `/permissions` inspection input but leaves permissions unchanged; the terminal must be idle, its Composer empty, and its physical and native thread identities verifiable. Use `current`, `scope`, and the returned choice descriptions to select the requested or authorized mode. Then call `agent_knock_knock_set_permissions({terminal_id,mode})` using its exact returned semantic ID in the same controller conversation. Full Access is an ordinary option and needs no additional user confirmation. AKK automatically handles its exact native confirmation inside this permission transaction; do not pause to ask the user to confirm Full Access or call generic `approve` for that dialog. Ordinary Send does not change permissions. Codex 0.160 may report `current="workspace_granular"`; this is a current-only native default, not a selectable mode. Select only an ID actually returned in `choices`. Only currently displayed built-in modes are supported: do not invent `read_only` when the picker omits it, supply a named/custom profile, or pass commands, labels, menu indexes, keys, tokens, or scope overrides. Changes affect the current session/thread, may be retained on Resume, and leave global defaults unchanged. Send the intended task only after `outcome="changed"` or `"already_effective"` with matching `effective.mode`; `"uncertain"` means stop and do not retry automatically. Refresh the catalog after any change or consumed attempt.
 
 For native model control, first call `agent_knock_knock_model_options({terminal_id})` only from the current terminal row's advertised action. This is explicit current-snapshot authority for one exact physical pane/process: Profiled Codex 0.154.0/0.155.1 may use either one exact current native Session or a verified-zero-rollout pane, where `identify_foreground` is diagnostic rather than a prerequisite; Claude Code still requires one exact current native Session. The pane must have no active Turn, approval, questionnaire/editor, or read-only viewer. It normally requires an idle empty Composer; when List advertises `model_options` for one exact stable profiled Codex 0.154.0/0.155.1 `/model` residual, AKK may continue only that residual into read-only catalog discovery. Show the returned `scope`, current selection, and semantic model/effort catalog to the user. Then call `agent_knock_knock_set_model({terminal_id,model,reasoning_effort})` with an exact required tuple from that same result in the same controller conversation. Codex scope is always `current_and_new_sessions`: a successful selection persists the model and an ordinary effort (including `max`) for future sessions, but `ultra` is current-session-only and Codex chooses a non-Ultra future fallback. Always read `effective` and `new_session_defaults` separately. Claude Code scope is always `current_session`. There is no caller-selectable scope. Never pass a display label, menu index, slash command, raw key, token, or fingerprint. A stale or consumed catalog must be refreshed, and `outcome="uncertain"` must never be retried automatically.
 
@@ -134,7 +184,7 @@ success; never retry an uncertain repair automatically.
 For native status inspection:
 
 1. Use only a current `available_actions.native_inspect({terminal_id,inspection:"status"})` entry. Those semantic arguments are complete; never add a command or authority field.
-2. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1/0.158.0/0.159.0/0.159.2 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267/2.1.285 `inspection="status"`. Other complete `x.y.z` versions remain callable through the generic runtime profile and add a compatibility warning; actual incompatible UI or schema evidence fails at runtime and is not automatically retried. Claude success includes parsing and safely dismissing the newly opened Status panel. The inspection tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, raw `/model`, `/compact`, and arbitrary slash commands remain unavailable; model changes use only the typed model-control tools above. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
+2. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1/0.158.0/0.159.0/0.159.2/0.159.3/0.160.0 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267/2.1.285 `inspection="status"`. Other complete `x.y.z` versions remain callable through the generic runtime profile and add a compatibility warning; actual incompatible UI or schema evidence fails at runtime and is not automatically retried. Claude success includes parsing and safely dismissing the newly opened Status panel. The inspection tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, raw `/model`, `/compact`, and arbitrary slash commands remain unavailable; model changes use only the typed model-control tools above. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
 3. Treat this as terminal input even though the native command is read-only. AKK privately derives a fresh binding fence and requires an idle empty composer, exact PID/process/pane/cwd/version identity, and no conflicting Turn, transition, dispatch, approval, or owner.
 4. Codex `/status` requires an exact viewport of at least 80 columns so the full Session UUID can be proven. That pre-UUID gate applies to native inspection, lifecycle, and strict Session operations that must know the UUID before terminal input. Legacy terminal-scoped ordinary tasks may send once and bind from exact native acceptance afterward without running `/status` or failing merely because the pane is narrow. Codex paginated read-contract candidates attempt their separate closed `/status` binding before physical Send. If an exact callback Watch cannot be prepared safely, AKK may prepare terminal-activity observation; report the receipt's actual callback mode and limitation.
 5. The result is valid only when AKK proves one fresh bounded native status result and the pane returns to idle. On an uncertain or unproven submission, do not retry, send Enter, clear the composer, or bypass AKK with raw terminal input.
@@ -224,19 +274,19 @@ A trusted, default-disabled plugin `autoApprove` policy may independently approv
 
 ## Terminal Sessions
 
-`agent_knock_knock_list` is terminal-first: every eligible already-running Codex or Claude Code pane appears once in `terminals[]`, even when retained managed Turns reference it. The resource chain is terminal → verified native session → managed AKK `session_id` → Turns; independent observation-only records appear in `terminal_watches[]` and are addressed only by `watch_id`. `process_state` reports process liveness. Read `screen_state` as bounded live-TUI evidence, `native_identity_state` as foreground native-session resolution, and `durable_activity_state` as exact artifact-backed task activity. The legacy `activity_state` is a conservative compatibility projection and may remain `unknown` while `screen_state="idle"`; none of these diagnostic fields replaces `available_actions` authority. `managed.current_turn` is the authoritative active Turn for that terminal; otherwise `managed.recent_turn` shows the newest retained context. A human-driven thread mismatch remains `management_state="conflict"`; `handoff_state="external_handoff_adoptable"` authorizes only the exact fenced `send` advertised on that row, while `external_handoff_blocked` means do not send or guess a recovery. Listing itself never adopts the new context. Request `all=true` only when older `managed.history`, settled Terminal Watches, or retained unavailable history is needed. By default, `unavailable_managed_turns[]` contains attention-needed records whose terminal is unavailable.
+The model-facing `agent_knock_knock_list` presents `conversations[]` once. Exact matched Codex terminal/backend representations are coalesced; unproven matches remain separate, and unconnected Desktop candidates stay visible. Raw CLI output retains the provider arrays for diagnostics. Terminal-backed rows still include retained managed context without duplicating the pane. The terminal resource chain is terminal → verified native session → managed AKK `session_id` → Turns; independent terminal observation records appear in `terminal_watches[]` and are addressed only by `watch_id`. `process_state` reports process liveness. Read `screen_state` as bounded live-TUI evidence, `native_identity_state` as foreground native-session resolution, and `durable_activity_state` as exact artifact-backed task activity. The legacy `activity_state` is a conservative compatibility projection and may remain `unknown` while `screen_state="idle"`; none of these diagnostic fields replaces `available_actions` authority. `managed.current_turn` is the authoritative active Turn for that terminal; otherwise `managed.recent_turn` shows the newest retained context. A human-driven thread mismatch remains `management_state="conflict"`; `handoff_state="external_handoff_adoptable"` authorizes only the exact fenced `send` advertised on that row, while `external_handoff_blocked` means do not send or guess a recovery. Listing itself never adopts the new context. Request `all=true` only when older `managed.history`, settled Terminal Watches, or retained unavailable history is needed. By default, `unavailable_managed_turns[]` contains attention-needed records whose terminal is unavailable.
 
 ### Compact controller-Host List projection
 
 The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=1`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, explanatory `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
 
-For every resource, `available_actions` is an object whose keys are the exact current semantic action names and whose values are `true`. `action_inputs` contains only dynamic semantic values that cannot be derived from the parent resource, plus scope, permitted decision values, and fields listed by `missing_required`; it does not repeat the same terminal/Session/Turn/Watch ID for every action. The parent terminal `id` is the full `terminal_id`; managed and Watch records expose their own `session_id`, `turn_id`, or `watch_id`. `features` is only a compact capability-status summary and never authorizes an action. Never infer an absent action. The compact display is not the enforcement boundary: the plugin caches the complete private offer before projection, and the CLI re-observes and revalidates the live pane under its action lock before every mutation.
+For every resource, `available_actions` is an object whose keys are the exact current semantic action names and whose values are `true`. `action_inputs` contains only dynamic semantic values that cannot be derived from the parent resource, plus scope, permitted decision values, and fields listed by `missing_required`; it does not repeat the same terminal/Session/Turn/Watch ID for every action. The parent `conversation_id` is the target for Send, Status, Watch and supported conversation settings; AKK chooses the operation route. For capability-specific terminal actions, the terminal `id` remains the full `terminal_id`; managed and Watch records expose their own `session_id`, `turn_id`, or `watch_id`. `features` is only a compact capability-status summary and never authorizes an action. Never infer an absent action. The compact display is not the enforcement boundary: the plugin caches the complete private offer before projection, and the CLI re-observes and revalidates the live pane under its action lock before every mutation.
 
 Action-name glossary:
 
 - `status`: inspect one terminal, Turn, or Watch; it sends no native slash command.
 - `send`: deliver a new request, or perform the separately advertised immutable `retry_submission` form.
-- `watch` / `unwatch`: create or stop durable terminal observation; Codex 0.158.0/0.159.0/0.159.2 exact creation performs the closed `/status` transaction, while subsequent observation is read-only.
+- `watch` / `unwatch`: create or stop durable terminal observation; Codex 0.158.0/0.159.0/0.159.2/0.159.3/0.160.0 exact creation performs the closed `/status` transaction, while subsequent observation is read-only.
 - `list_resumable_threads`, `new_thread`, and `resume_thread`: inspect or change native thread context through their closed lifecycle protocols.
 - `native_inspect`: run only an advertised closed native inspection such as `status`.
 - `model_options`, `repair_model_control`, and `set_model`: discover the current native catalog, clear only a proven model-control residue, or consume one catalog offer.
@@ -247,9 +297,10 @@ Action-name glossary:
 - `respond_interaction`: answer one current native interaction step obtained from fresh Status; an `async_question` defaults to advertised `steer_current_turn` or accepts explicit advertised `queue_next_turn` as `delivery_mode`, while a blocking `questionnaire` omits it.
 - `approve`: apply only an explicitly confirmed advertised semantic approval decision.
 - `cancel`: interrupt the selected active Turn without closing the terminal.
-- `renew`: extend monitoring for an eligible stalled Turn without terminal input.
-- `retry_callback`: retry delivery of an eligible failed callback without terminal input.
-- `close`: release AKK management for the selected Turn without stopping the coding agent or closing the pane.
+- `renew`: extend an eligible stalled terminal Turn, or renew an exact backend task observation after identity verification.
+- `retry_callback`: retry an eligible persisted callback without terminal input, retaining its original notification identity.
+- `close`: release AKK management for the selected Send Turn without stopping the coding agent or closing its conversation.
+- `recover`: reconcile an exact backend task and its receipt without resending work or changing its anchor.
 
 The tool name is normally `agent_knock_knock_<action-name>`. The sole List alias is `retry_submission`, which invokes `agent_knock_knock_send` with its listed `turn_id` only after explicit confirmation. Nested `handoff_decision.choices.take_over_current.action` and `blocking_turns[].recovery_action` carry their explicit tool/action name and semantic arguments; the explanatory choice and recovery text is defined here rather than repeated in every List row.