@scotthuang/agent-knock-knock 0.2.46 → 0.2.48

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

@@ -5,7 +5,7 @@ description: Delegate OpenClaw tasks to local Codex, Claude Code, and Cursor age
 
 # Agent Knock Knock
 
-Use this skill when the user says `AKK`, `akk`, `Agent Knock Knock`, asks OpenClaw to delegate coding work to Codex, Claude, or Cursor, asks what agent tasks are running, asks what a listed AKK/Codex session is about, sends a follow-up to an agent task, lists existing local coding-agent sessions, takes over an existing native Codex session, recovers an unavailable agent session, cancels a running agent task, or closes an agent task.
+Use this skill when the user says `AKK`, `akk`, `Agent Knock Knock`, asks OpenClaw to delegate coding work to Codex, Claude, or Cursor, asks what agent tasks are running, asks what a listed AKK, Codex, or Claude session is about, sends a follow-up to an agent task, lists existing local coding-agent sessions, takes over an existing native Codex session, recovers an unavailable agent session, cancels a running agent task, or closes an agent task.
 
 Treat `AKK` and `akk` the same way.
 
@@ -35,7 +35,7 @@ Slash command forms:
 - `/akk cursor <task>`: delegate to Cursor.
 - `/akk list`: list open AKK sessions.
 - `/akk status <conversation-id>`: inspect one AKK session.
-- `/akk describe <conversation-id>`: summarize what one AKK-managed, native Codex, or terminal-controlled Codex session is about.
+- `/akk describe <conversation-id>`: summarize what one AKK-managed, native, or terminal-controlled session is about.
 - `/akk send <conversation-id> <message>`: send a follow-up to one open AKK session.
 - `/akk cancel <conversation-id>`: request cooperative cancellation of the current in-flight prompt for one AKK session without closing it.
 - `/akk recover <conversation-id>`: recover a session that is waiting for a recovery decision by starting a new agent session with AKK's saved protocol history summary.
@@ -47,17 +47,17 @@ Natural-language forms:
 - `AKK Codex: <task>`: call `agent_knock_knock_delegate` with `agent="codex"`.
 - `AKK Claude: <task>`: call `agent_knock_knock_delegate` with `agent="claude"`.
 - `AKK Cursor: <task>`: call `agent_knock_knock_delegate` with `agent="cursor"`.
-- `AKK list`, `akk list`, questions such as "what AKK sessions are open", "which Codex sessions are currently running", "terminal-controlled Codex sessions", or requests to list active local coding-agent work: call `agent_knock_knock_list`.
+- `AKK list`, `akk list`, questions such as "what AKK sessions are open", "which Codex or Claude sessions are currently running", "terminal-controlled sessions", or requests to list active local coding-agent work: call `agent_knock_knock_list`.
 - `AKK status <conversation-id>` or requests to view current output, execution result, terminal screen, or "what is it doing now": call `agent_knock_knock_status`. For `terminal_controlled` entries, status internally captures the terminal pane and returns `terminal_screen`; do not call tmux or shell commands directly to inspect the pane unless AKK status fails.
-- `AKK describe <conversation-id>`, `AKK summary <conversation-id>`, or requests such as "what is this session about", "what was this task doing", "remind me what this drawing/session is for", or "这个会话/绘画大概在做什么": call `agent_knock_knock_describe`. Prefer this over direct terminal/tmux inspection because AKK can combine saved conversation history, Codex rollout history, cwd-matched history, and terminal-screen fallback with explicit confidence.
-- `AKK send <conversation-id>: <message>` or follow-up requests for an existing open agent session: call `agent_knock_knock_send`. Also use `agent_knock_knock_send` when the user says to send/tell/ask/forward/add/continue a message or task to a listed AKK session, a listed Codex session, a terminal-controlled entry, a tmux target such as `my-work:0.1`, or "the one from the list". If the target comes from a `terminal_controlled` entry in `AKK list`, use that entry's `id` directly; AKK will type the message into the controlled terminal pane and submit it. Do not call `agent_knock_knock_delegate` for these requests unless the user explicitly asks for a new independent session.
-- `AKK cancel <conversation-id>` or requests to stop the current running work without closing the session: call `agent_knock_knock_cancel`. If the target comes from a `terminal_controlled` entry in `AKK list`, use that entry's `id` directly; AKK sends Control-C to the controlled terminal pane.
+- `AKK describe <conversation-id>`, `AKK summary <conversation-id>`, or requests such as "what is this session about", "what was this task doing", "remind me what this drawing/session is for", or "这个会话/绘画大概在做什么": call `agent_knock_knock_describe`. Prefer this over direct terminal/tmux inspection because AKK can combine saved conversation history, agent-specific structured history when available, and terminal-screen fallback with explicit confidence.
+- `AKK send <conversation-id>: <message>` or follow-up requests for an existing open agent session: call `agent_knock_knock_send`. Also use `agent_knock_knock_send` when the user says to send/tell/ask/forward/add/continue a message or task to a listed AKK session, a listed native session, a terminal-controlled entry, a tmux target such as `my-work:0.1`, or "the one from the list". If the target comes from a `terminal_controlled` entry in `AKK list`, use that entry's `id` directly; AKK submits only when the pane is at a verified idle prompt. For Claude Code, this background send returns a managed conversation ID and creates the lease required for structured approvals and completion callbacks; use that returned ID for subsequent actions. Do not call `agent_knock_knock_delegate` for these requests unless the user explicitly asks for a new independent session.
+- `AKK cancel <conversation-id>` or requests to stop the current running work: call `agent_knock_knock_cancel`. If the target is terminal-controlled, use its listed `id` directly. AKK denies a pending structured Claude permission request; otherwise it uses the adapter's interrupt key (`Control-C` for Codex or `Escape` for Claude Code). If a Claude permission dialog cannot be revalidated, AKK sends no key and it must be resolved manually in the terminal.
 - `AKK renew <conversation-id>` or requests to extend/restart monitoring for a stalled but still-live terminal task: call `agent_knock_knock_renew`. This is only for an AKK-managed terminal bridge conversation already marked `stalled`; it does not send a message or key to Codex. Pass `minutes` only when the user requests a specific new inactivity timeout.
 - `AKK recover <conversation-id>`: call `agent_knock_knock_recover`.
 - `AKK close <conversation-id>`: call `agent_knock_knock_close`.
 - `AKK takeover Codex <session-id>` or requests to take over an active Codex CLI session: call `agent_knock_knock_agent_takeover` with `agent="codex"` and `strategy="terminate_then_resume"`.
 - `AKK terminal takeover Codex <session-id>` or requests to take over a Codex CLI that is running inside a controllable terminal provider without stopping it: call `agent_knock_knock_agent_takeover` with `agent="codex"` and `strategy="terminal_control"`.
-- `AKK approve <conversation-id>` or requests to approve the current visible Codex permission/command prompt for a terminal-controlled session: first call `agent_knock_knock_status` for that conversation and show the terminal screen excerpt to the user. Only after the user explicitly approves that prompt, call `agent_knock_knock_approve` with the exact `approval_state.fingerprint` as `expected_approval_fingerprint`. If an AKK callback says a terminal bridge session is waiting for approval, pass its approval fingerprint the same way; deny or stop that request with `agent_knock_knock_cancel`. If the target comes from a `terminal_controlled` entry in `AKK list`, use that entry's `id` directly; it does not need an AKK-managed state file before status or approval.
+- `AKK approve <conversation-id>` or requests to approve a terminal-controlled permission or command prompt: first call `agent_knock_knock_status` and show the detected request details to the user. Only after the user explicitly approves that exact request, call `agent_knock_knock_approve` with its `approval_state.fingerprint` as `expected_approval_fingerprint`. Claude Code uses the structured `PermissionRequest` hook; Codex uses the current visible prompt. If an AKK callback says a terminal bridge session is waiting for approval, pass its fingerprint the same way; deny it with `agent_knock_knock_cancel`. Unknown, stale, ambiguous, or changed requests must never be approved. Status works directly for every listed `terminal_controlled` ID. Codex visible-prompt approval can also work without managed state; Claude approval requires the managed lease created by a prior background send.
 - `AKK takeover Codex <session-id> with fork`, `AKK fork takeover Codex <session-id>`, or requests to take over without stopping the original Codex CLI: call `agent_knock_knock_agent_takeover` with `agent="codex"` and `strategy="fork"`.
 
 Session reuse rule:
@@ -80,6 +80,7 @@ akk list
 akk describe task-20260618T010203Z-abcdef12
 akk send task-20260618T010203Z-abcdef12: continue with the smaller implementation
 akk send terminal:v2:tmux:codex:my-work:0.1:38140: hello 测试一下通信
+akk send terminal:v2:tmux:claude:claude-work:0.1:29466: review the current changes
 给 AKK list 里的 my-work:0.1 发一条消息：继续刚才的任务
 再让刚才那个 Codex 分析 ~/chrome-debug 为什么占空间
 akk cancel task-20260618T010203Z-abcdef12
@@ -92,29 +93,15 @@ akk approve task-20260618T010203Z-abcdef12
 
 ## Start A Conversation
 
-Prefer the OpenClaw plugin tool `agent_knock_knock_delegate`. It starts the selected coding agent in the background, creates durable conversation state, embeds the OpenClaw callback command, and returns protocol metadata.
+Use the OpenClaw plugin tool `agent_knock_knock_delegate`. It starts the selected coding agent in the background, creates durable conversation state, embeds a token-free OpenClaw callback command, and returns protocol metadata.
 
-If the plugin tool is unavailable, run these commands from the `agent-knock-knock` repository root, or from a workspace where `scripts/bidirectional-delegate.sh` is available.
-
-Start a managed Claude delegation through the legacy script:
-
-```bash
-scripts/bidirectional-delegate.sh --send \
-  --token '<gateway-token>' \
-  --request '<user task>'
-```
-
-If you only want to inspect the payload before sending:
-
-```bash
-scripts/bidirectional-delegate.sh --request '<user task>'
-```
+If the plugin tool is unavailable, stop and report that Agent Knock Knock must be installed or repaired. Never request, print, or place an OpenClaw Gateway token in a delegated prompt or custom callback command.
 
 ## Communication Contract
 
 Do not use OpenClaw's internal session tools, such as `sessions_send`, to send the task or follow-up messages directly to Codex, Claude, or Cursor.
 
-All OpenClaw-to-agent task delivery must go through the Agent Knock Knock plugin tools, `scripts/bidirectional-delegate.sh`, or an equivalent `agent-knock-knock delegate` command. Standard ACPX delegation builds the required bootstrap prompt, embeds the OpenClaw callback command, creates durable conversation state, and records the initial task message. Terminal-control bridge conversations are different: AKK types only the user-facing message into the tmux Codex pane, monitors Codex rollout/terminal state, and sends the OpenClaw callback itself.
+All OpenClaw-to-agent task delivery must go through the Agent Knock Knock plugin tools. Standard ACPX delegation builds the required bootstrap prompt, embeds the OpenClaw callback command, creates durable conversation state, and records the initial task message. Terminal-control bridge conversations are different: AKK types only the user-facing message into the tmux agent pane, monitors adapter and structured hook state, and sends the OpenClaw callback itself.
 
 For standard ACPX delegation, the coding agent must communicate back to OpenClaw by executing the callback command included in its bootstrap prompt. For terminal-control bridge conversations, AKK owns callback delivery. The coding agent should not rely on OpenClaw's session tools, chat memory, or an out-of-band reply path.
 
@@ -125,7 +112,7 @@ The required routing is:
 3. The coding agent sends `question`, `progress`, `blocked`, `done`, or `error` messages back by running the provided callback command; for terminal-control bridge sessions, AKK observes completion and sends the callback.
 4. OpenClaw answers `question` or `blocked` messages with structured `answer` messages through the same protocol path.
 
-If the plugin tool and delegation script are unavailable, stop and report that Agent Knock Knock is not available. Do not fall back to direct `sessions_send` delivery.
+If the plugin tool is unavailable, stop and report that Agent Knock Knock is not available. Do not fall back to direct `sessions_send` delivery.
 
 ## Recovery Decisions
 
@@ -142,17 +129,17 @@ Make clear that `recover` is AKK replay recovery, not guaranteed native coding-a
 
 Do not start a replacement task without the user's explicit choice.
 
-## Native Session Takeover
+## Native and tmux Sessions
 
-Native session takeover is for Codex sessions that were created outside AKK, such as a user-run terminal Codex CLI. It is separate from AKK managed conversation recovery.
+Native stop/resume and fork takeover are for Codex sessions created outside AKK. tmux terminal control supports both Codex and Claude Code and is separate from AKK managed conversation recovery.
 
-Use `agent_knock_knock_list` when the user asks about current active native Codex sessions, terminal-controlled Codex sessions, or which local coding-agent work is currently open. The list result separates:
+Use `agent_knock_knock_list` when the user asks about current native Codex sessions, terminal-controlled Codex or Claude Code sessions, or which local coding-agent work is currently open. The list result separates:
 
 - `delegated`: AKK-managed tasks.
 - `native`: discovered local native sessions that AKK cannot directly control.
 - `terminal_controlled`: discovered local native sessions in a controllable terminal provider. The current provider is tmux.
 
-Use `agent_knock_knock_describe` when the user asks what a listed session is about. AKK-managed sessions use durable AKK conversation history. Native and terminal-controlled Codex sessions use exact Codex rollout history when a session id is available, fall back to cwd-matched rollout history when needed, and otherwise return visible terminal/process context with lower confidence. Do not use raw tmux, shell, or peek tools for this summary unless `agent_knock_knock_describe` is unavailable or fails.
+Use `agent_knock_knock_describe` when the user asks what a listed session is about. AKK-managed sessions use durable AKK conversation history. Terminal adapters use agent-specific structured history when available and otherwise return visible terminal/process context with lower confidence. Do not use raw tmux, shell, or peek tools for this summary unless `agent_knock_knock_describe` is unavailable or fails.
 
 Use `agent_knock_knock_agent_takeover` when the user wants AKK to take over an existing native Codex session. By default this tool is side-effect-free and returns a plan. When the plan is ready and the user explicitly wants AKK to manage the session, call it with `createConversation=true` to create an AKK conversation bound to the native session:
 
@@ -160,6 +147,8 @@ Use `agent_knock_knock_agent_takeover` when the user wants AKK to take over an e
 - `terminal_control`: use when the target Codex CLI is running inside a controllable terminal provider and the user wants AKK to operate the existing TUI without stopping or resuming it. The first call is side-effect-free. If the result is `requires_confirmation`, show the exact terminal target, pid, cwd, and current terminal-control metadata. Only after explicit user confirmation, call again with `strategy="terminal_control"`, `createConversation=true`, `confirmTerminal=true`, and `terminalTarget=<confirmed target>`. Follow-up `AKK send` messages will be typed into the terminal pane as concise user-facing task text; AKK monitors the Codex rollout/terminal state and sends the callback to OpenClaw itself. `AKK cancel` sends Control-C to the controlled terminal pane. Terminal-controlled entries from `AKK list` can be sent to, cancelled, approved, and inspected directly with their `id`; use `agent_knock_knock_status` to inspect the current terminal screen or execution result. Before `agent_knock_knock_approve`, show the user the latest terminal excerpt and pass its fingerprint as `expected_approval_fingerprint`.
 - `fork`: use when the user wants to avoid stopping the original Codex CLI. First call returns a bounded context package plus `summaryPrompt` and `nextAction`; use that prompt to summarize as OpenClaw, ask the user to confirm, and do not inject raw full rollout history directly. After the user confirms the summary, call `agent_knock_knock_agent_takeover` again with `strategy="fork"`, `createConversation=true`, and `forkSummary=<approved summary>` to create the forked AKK-managed session. Then use the returned `conversation_id` with `AKK send` for follow-up work.
 
+Claude Code terminal entries are controlled directly by their `terminal:v2:tmux:claude:...` ids; do not offer Codex-only stop/resume or fork strategies for them. Treat the structured completion or error callback as authoritative. Do not report completion merely because the pane looks idle: AKK emits one completion from Claude's `Stop.last_assistant_message` only after background tasks and scheduled jobs are empty, and maps `StopFailure` to an error. If the Claude hooks are unavailable, AKK deliberately keeps completion and approval conservative.
+
 Do not present `fork` as a standalone command or standalone feature. It is a takeover strategy.
 
 Do not use `resume-anyway` or start a second live client on the same native Codex session while another Codex CLI is active. That can create mixed session history where multiple clients do not see each other's live context until a later resume.
@@ -177,7 +166,7 @@ Use structured JSON messages with these types:
 - `error`: runtime, tool, or protocol failure
 - `control`: budget warning or lifecycle control
 
-`cancel` is lifecycle control outside the agent message protocol. For delegated sessions, it asks ACPX to cooperatively cancel the current in-flight prompt for the existing Codex, Claude, or Cursor session. For terminal-controlled sessions, it sends Control-C to the controlled terminal pane. It does not close the AKK session; use `close` only when the session should no longer be reused.
+`cancel` is lifecycle control outside the agent message protocol. For delegated sessions, it asks ACPX to cooperatively cancel the current in-flight prompt. For terminal-controlled sessions, it denies a pending structured permission when safe or uses the adapter's interrupt action, then marks that AKK task cancelled while leaving the tmux pane open.
 
 Only messages with `requires_response=true` consume response rounds.