@scotthuang/agent-knock-knock 0.14.4 → 0.14.6

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

@@ -1,13 +1,13 @@
 ---
 name: agent-knock-knock
-description: Use Agent Knock Knock to discover, send tasks to, and observe existing Codex CLI, Codex Desktop, or Claude Code conversations through their supported direct or terminal connections.
+description: Use Agent Knock Knock to discover and control Codex CLI, Codex Desktop, or Claude Code conversations, and create Desktop conversations when its creation tool is available.
 ---
 
 # 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 conversation listed by AKK.
 
-AKK supports loaded local Codex CLI threads through their shared backend, existing local Codex Desktop conversations, compatible already-open Claude Code CLIs through their native inbox, 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.
+AKK supports loaded local Codex CLI threads through their shared backend, local Codex Desktop conversations (with explicit creation when the Desktop Create tool is available), compatible already-open Claude Code CLIs through their native inbox, 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.
 
@@ -19,9 +19,11 @@ Keep the user's requested scope and approval boundaries. Do not expand a task, a
 
 ## 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[]`, `claude_cli_sessions[]` and `desktop_sessions[]` for compatibility and private authority, but do not present these again as extra conversations when `conversations[]` exists.
+Present `conversations[]` as **CLI** or **Desktop** using `surface`, and keep Codex/Claude Code as the agent type. Select the displayed `conversation_id` and its advertised operation; AKK chooses the connection internally. Do not make separate user-facing backend and terminal lists, repeat raw discovery arrays, or count Watches as additional conversations or tasks. Preserve unavailable actions, current questions/approvals, and management/recovery records. Scoped controls, when present, are operations on exact targets within a row, not extra conversations.
 
-AKK prefers a reachable direct connection only when it proves the exact current native session and process or 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.
+Default CLI presentation folds one same-agent, same-project terminal/backend candidate pair into the original terminal row. This is display grouping only: the candidate contributes no identity, status or permissions, and does not authorize backend dispatch. Known conflicts or multiple candidates remain separate. Backend-only CLI conversations remain discoverable. If a particular connection is missing or ambiguous, use `terminalDebug: true` (CLI `list --terminal-debug`) to expand every unassociated connection and routing detail. A same-project embedded CLI and an independent direct CLI can share a default display row when their identities are unknown; the expanded view preserves both. Display entry counts are not proof of unique native tasks.
+
+AKK prefers a reachable direct connection only after proving the exact selected native session and process or thread. An unavailable backend may retain an eligible terminal path; busy/blocked state or identity conflict cannot authorize bypass. Targeted operations on an idle terminal can use the existing advertised `/status` inspection to learn its identity; working or blocked terminals are not interrupted. List itself sends no terminal input. Keep an uncertain dispatch receipt and inspect it instead of retrying through another connection.
 
 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.
 
@@ -39,7 +41,7 @@ Callbacks already in flight cannot be recalled by Close or Unwatch. `accepted` p
 
 ## 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.
+A direct Codex CLI conversation 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.
@@ -51,7 +53,7 @@ Use AKK's advertised actions and read the actual operation result after backend
 
 ## Direct Claude Code
 
-Rows with `source="claude_cli"` use `claude-cli:v1:...` IDs for an already-running native CLI. This path is live-tested on macOS with Claude Code `2.1.296` and peer protocol `1`; Python 3 is required on the AKK side. It needs no Claude plugin, hook, special launch arguments or replacement process. Use actual advertised capabilities after upgrades, not a version number alone.
+Direct Claude Code conversations use `claude-cli:v1:...` IDs for an already-running native CLI. This path is live-tested on macOS with Claude Code `2.1.296` and peer protocol `1`; Python 3 is required on the AKK side. It needs no Claude plugin, hook, special launch arguments or replacement process. Use actual advertised capabilities after upgrades, not a version number alone.
 
 - Send to a verified idle conversation. Keep its `claude-cli-watch:...` receipt: Send already creates completion monitoring with the shared 720-minute hard deadline. Do not add another Watch for that Send. Busy/blocked, held/refused or uncertain delivery must not be retried through terminal input.
 - Status on the conversation reads its latest input; Status on the Watch reads its original exact `native_input_id`. This is an input UUID, not a native turn ID. Public progress and tool-action summaries are bounded to 800 code points; List has no progress body. `agent_acceptance: proven` requires exact native sender/message/input evidence, not merely a socket write.
@@ -61,11 +63,11 @@ Rows with `source="claude_cli"` use `claude-cli:v1:...` IDs for an already-runni
 
 ## 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.
+Desktop rows in `conversations[]` have `surface="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.
+- 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. Existing historical conversations cannot be cold-loaded or resumed by this adapter. The separate Desktop Create tool only opens the new thread recorded by that creation operation. If an existing conversation 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.
@@ -73,9 +75,15 @@ Desktop rows in `conversations[]` have `source="codex_desktop"` and a full `desk
 - 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.
+- 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. Arbitrary cold loading/resume remains unsupported; explicit creation uses the separate tool below.
+
+Full Desktop control is reviewed for macOS Codex Desktop `26.1002.52244` build `13536` through private local IPC. The AKK 0.14.5 profile for `26.1007.30912` build `20156` enables creation and Send/Status/Watch, but approvals, answers, permission/model changes and cancellation remain unavailable; use Desktop for those actions. The interaction instructions above apply only when the current result advertises that action. 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.
+
+### Create a Desktop conversation
+
+When `agent_knock_knock_desktop_create` is available and the user asks for a new Desktop conversation, use it instead of terminal `new_thread`. Available starting in AKK 0.14.5. It needs no existing conversation ID. Pass an exact existing `project` name or native ID, optional `cwd` and `title`, and optional first-task `request`. Omit `project` for a projectless conversation; omit `request` for an empty conversation. A multi-root project needs an explicit directory inside one of its roots. Without a project or directory AKK uses its private Desktop work directory. Creation opens the new conversation in the Desktop UI; it does not submit a hidden bootstrap task or change existing work.
 
-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.
+Keep `operation_id`. If opening or uncertain, call the same tool with only that returned `operation_id`; do not issue a new creation or resend the task separately. AKK rejects unknown/foreign operations and preserves the original payload and callback route. `status: ready` proves Desktop ownership, not first-task acceptance: inspect `request_state`, `watch_id`, and `task_status` separately. No request means no task or completion Watch. A supplied request already receives exact automatic monitoring with the shared 720-minute default; retain its Watch and do not add another. An accepted callback proves controller acceptance, not delivery to the user's chat channel.
 
 ## Chat Routing