@scotthuang/agent-knock-knock 0.2.47 → 0.2.49

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

@@ -50,14 +50,14 @@ Natural-language forms:
 - `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, 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 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 the managed conversation ID required to bind later screen approval to the current message and process; 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 uses the adapter's interrupt key (`Control-C` for Codex or `Escape` for Claude Code) and leaves the tmux pane open.
 - `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 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 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`. Codex and Claude Code both use the current visible prompt; Claude screen approval is limited to a strict one-time `Yes` Bash dialog in the current AKK-managed turn and never uses automatic approval. 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, expired, ambiguous, persistent-permission, or changed requests must never be approved. Codex visible-prompt approval can also work without managed state; Claude requires the managed conversation returned 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:
@@ -93,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 agent pane, monitors adapter and structured hook 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 local terminal state, and sends OpenClaw callbacks when it has reliable evidence.
 
 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.
 
@@ -123,10 +109,10 @@ The required routing is:
 
 1. OpenClaw starts delegation with `agent_knock_knock_delegate`.
 2. Agent Knock Knock sends the bootstrap prompt and task to the selected Codex, Claude, or Cursor session through ACPX, or sends only the user-facing task text to a terminal-control bridge session.
-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.
+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 reports approvals and sends completion callbacks only when that adapter has reliable completion evidence.
 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
 
@@ -161,7 +147,7 @@ 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.
+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. AKK does not install or require Claude hooks. A background send creates a managed turn that can report a strictly recognized, one-time Bash approval prompt; show the redacted excerpt and require the exact fingerprint plus explicit user confirmation. Claude screen approval is best-effort terminal automation, expires quickly, is revalidated immediately before Enter, and never participates in automatic approval. Hook-free completion comes from a strictly correlated, local Claude transcript turn and may fail closed for unknown schemas, background work, or ambiguous identity. Never report completion merely because the pane looks idle; rely on the AKK callback or use `status` and inspect the terminal when monitoring becomes `stalled`.
 
 Do not present `fork` as a standalone command or standalone feature. It is a takeover strategy.
 
@@ -180,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 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.
+`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 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.