@scotthuang/agent-knock-knock 0.1.2 → 0.2.1

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, sends a follow-up to an agent task, recovers or restarts 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, sends a follow-up to an agent task, discovers 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.
 
@@ -38,7 +38,6 @@ Slash command forms:
 - `/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.
-- `/akk restart <conversation-id>`: restart a session that is waiting for a recovery decision by starting a new agent session with only the pending message.
 - `/akk close <conversation-id> [reason]`: close one AKK session.
 
 Natural-language forms:
@@ -52,15 +51,20 @@ Natural-language forms:
 - `AKK send <conversation-id>: <message>` or follow-up requests for an existing open agent session: call `agent_knock_knock_send`.
 - `AKK cancel <conversation-id>` or requests to stop the current running work without closing the session: call `agent_knock_knock_cancel`.
 - `AKK recover <conversation-id>`: call `agent_knock_knock_recover`.
-- `AKK restart <conversation-id>`: call `agent_knock_knock_restart`.
 - `AKK close <conversation-id>`: call `agent_knock_knock_close`.
+- `AKK Codex sessions`, `AKK Codex history`, or requests to list existing native Codex sessions outside AKK: call `agent_knock_knock_agent_discover` with `agent="codex"` and `scope="sessions"`.
+- `AKK Codex active` or requests to list currently running local Codex CLI processes: call `agent_knock_knock_agent_discover` with `agent="codex"` and `scope="active"`.
+- `AKK Codex capabilities` or requests to inspect Codex takeover support: call `agent_knock_knock_agent_discover` with `agent="codex"` and `scope="capabilities"`.
+- `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 safe resume Codex <session-id>` or requests to resume only after the original Codex CLI has already exited: call `agent_knock_knock_agent_takeover` with `agent="codex"` and `strategy="safe_resume"`.
+- `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:
 
 - If the user asks to continue, add, follow up, "send another task", "let it also", "tell it", "ask Codex/Claude/Cursor to also", "再让它", "继续让它", "给刚才那个", or otherwise refers to an existing AKK agent, reuse the most recent matching open AKK session instead of creating a new delegation.
 - When the user gives a follow-up without a `conversation_id`, first call `agent_knock_knock_list`, choose the most recent open session that matches the requested agent if one is named, and then call `agent_knock_knock_send` with that `conversation_id`.
 - `idle` means the agent completed the previous round but the AKK session is still open and should be reused for follow-ups.
-- `needs_recovery` means AKK could not reach the previous coding-agent session and must not automatically replay history or start a new session. Ask the user to choose `AKK recover <conversation-id>`, `AKK restart <conversation-id>`, or `AKK close <conversation-id>`.
+- `send` automatically falls back to AKK replay recovery when the previous coding-agent session is unavailable. If AKK still reports `needs_recovery`, ask the user to choose `AKK recover <conversation-id>`, `AKK close <conversation-id>`, or starting a new independent AKK delegation.
 - Call `agent_knock_knock_delegate` only when the user clearly asks for a new independent AKK task/session, names a different agent that does not already have a suitable open session, or there is no matching open session to reuse.
 
 Useful examples:
@@ -75,8 +79,10 @@ akk send task-20260618T010203Z-abcdef12: continue with the smaller implementatio
 再让刚才那个 Codex 分析 ~/chrome-debug 为什么占空间
 akk cancel task-20260618T010203Z-abcdef12
 akk recover task-20260618T010203Z-abcdef12
-akk restart task-20260618T010203Z-abcdef12
 akk close task-20260618T010203Z-abcdef12
+akk codex sessions
+akk codex active
+akk takeover codex 019ee559-7bb8-7fd1-970c-0f7b6978c44e
 ```
 
 ## Start A Conversation
@@ -118,15 +124,37 @@ If the plugin tool and delegation script are unavailable, stop and report that A
 
 ## Recovery Decisions
 
-When AKK reports that a conversation is `needs_recovery`, do not automatically recover, replay history, restart, or close it. Explain the options and let the user choose:
+`AKK send <conversation-id>: <message>` automatically falls back to AKK replay recovery when the previous ACPX session is unavailable. This starts a fresh ACPX session, gives the coding agent AKK's saved protocol history summary, and includes the pending message.
+
+When AKK still reports that a conversation is `needs_recovery`, do not automatically recover, start a replacement task, or close it. Explain the options and let the user choose:
 
 - `AKK recover <conversation-id>`: use `agent_knock_knock_recover` to start a new coding-agent session with AKK's saved protocol history summary plus the pending message.
-- `AKK restart <conversation-id>`: use `agent_knock_knock_restart` to start a new coding-agent session with only the pending message.
 - `AKK close <conversation-id>`: use `agent_knock_knock_close` to close the task.
+- Start a new independent `AKK <task>` delegation if the old task should not be recovered.
 
 Make clear that `recover` is AKK replay recovery, not guaranteed native coding-agent session resume.
 
-Cursor uses this conservative recovery flow by default when AKK cannot reach its previous ACPX session. Do not automatically recover or restart Cursor work without the user's explicit choice.
+Do not start a replacement task without the user's explicit choice.
+
+## Native Session Takeover
+
+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.
+
+Use `agent_knock_knock_agent_discover`, not `agent_knock_knock_list`, when the user asks about native Codex sessions outside AKK:
+
+- `scope="sessions"` lists historical native Codex sessions from the local Codex store.
+- `scope="active"` lists currently running local Codex CLI processes that AKK can identify.
+- `scope="capabilities"` explains the supported takeover strategies.
+
+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:
+
+- `safe_resume`: allowed only when no active Codex CLI matches the session. If the result is `ready`, explain that this is safe to resume because AKK did not find an active conflicting CLI. If the user confirms attaching it to AKK, call again with `createConversation=true`, then use the returned `conversation_id` for `AKK send`, `AKK status`, and `AKK close`.
+- `terminate_then_resume`: use when the user wants to take over an active native Codex CLI. The first call is side-effect-free. If the result is `requires_confirmation`, explain the exact pid, cwd, and session that would be stopped. Only after explicit user confirmation, call `agent_knock_knock_agent_takeover` again with `strategy="terminate_then_resume"`, `createConversation=true`, `confirmTerminate=true`, and `expectedPid=<confirmed pid>`. AKK will re-scan before terminating and will only stop an exact session match. If Codex does not expose a session id and the user still explicitly confirms a specific pid in the target cwd, you may add `allowCwdOnly=true`; explain that this is higher risk because it relies on pid and cwd rather than a visible session id.
+- `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.
+
+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.
 
 ## Message Rules