@scotthuang/agent-knock-knock 0.14.2 → 0.14.3

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

@@ -1,13 +1,13 @@
 ---
 name: 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.
+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.
 ---
 
 # 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, 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, 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.
 
 Treat `AKK` and `akk` the same way.
 
@@ -19,9 +19,9 @@ 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[]` and `desktop_sessions[]` for compatibility and private authority, but do not present these again as extra conversations when `conversations[]` exists.
+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.
 
-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.
+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.
 
 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.
 
@@ -49,6 +49,16 @@ A `conversations[]` row with `source="codex_cli"` uses an exact `codex-cli:v1:..
 
 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.
 
+## 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.
+
+- 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.
+- Watch a manually started active task using the conversation action. Keep the returned Watch through task changes. Idle is not success; `exited` means the original process ended without proof of completion. A new process resuming the same history is not silently substituted.
+- Use the advertised Recover, Unwatch, Close and retry-callback actions on the original task. Explicit Renew requires that same input still active; settled or exited tasks cannot renew. Accepted or uncertain callbacks are not replayed. Callback acceptance proves delivery to the controller, not to a downstream chat channel.
+- Direct approvals, question answers, models, permissions, cancellation and lifecycle commands are unavailable. Registry waiting hints may indicate manual attention, but `pending_interaction_count: null` means unknown and interaction notification is not guaranteed. Report `manual_required` and return to the original Claude terminal. If an exact eligible tmux/Herdr counterpart exists, AKK retains its advertised special controls automatically; their original version and safety limits still apply.
+
 ## 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.