@scotthuang/agent-knock-knock 0.2.22 → 0.2.23

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.23 - 2026-07-04
+
+### Fixed
+
+- Declared `agent_knock_knock_describe` in the OpenClaw plugin contract and metadata so OpenClaw exposes the new describe tool.
+- Updated the installed AKK skill routing rules to use `agent_knock_knock_describe` for session-content summary requests instead of falling back to direct terminal inspection.
+
 ## 0.2.22 - 2026-07-04
 
 ### Added

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "agent-knock-knock",
   "name": "Agent Knock Knock",
-  "description": "Agent Knock Knock (AKK/akk) delegates OpenClaw coding work to local Codex, Claude, or Cursor agents. Use this plugin when the user says AKK, akk, Agent Knock Knock, asks to hand work to Codex, Claude, or Cursor, asks what agent tasks are running, sends a follow-up to an agent task, recovers an unavailable agent session, cancels a running agent task, or closes an agent task. Default delegation target comes from plugin config defaultAgent and falls back to Codex when unset; explicit user agent requests override it.",
+  "description": "Agent Knock Knock (AKK/akk) delegates OpenClaw coding work to local Codex, Claude, or Cursor agents. Use this plugin when the user says AKK, akk, Agent Knock Knock, asks to hand work to Codex, Claude, or Cursor, asks what agent tasks are running, asks what an AKK/Codex session is about, sends a follow-up to an agent task, recovers an unavailable agent session, cancels a running agent task, or closes an agent task. Default delegation target comes from plugin config defaultAgent and falls back to Codex when unset; explicit user agent requests override it.",
   "activation": {
     "onStartup": true
   },
@@ -13,6 +13,7 @@
       "agent_knock_knock_delegate",
       "agent_knock_knock_list",
       "agent_knock_knock_status",
+      "agent_knock_knock_describe",
       "agent_knock_knock_send",
       "agent_knock_knock_cancel",
       "agent_knock_knock_recover",
@@ -32,6 +33,9 @@
     "agent_knock_knock_status": {
       "optional": true
     },
+    "agent_knock_knock_describe": {
+      "optional": true
+    },
     "agent_knock_knock_send": {
       "optional": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "OpenClaw plugin bridge for delegating work to local coding agents through ACPX.",
   "license": "MIT",
   "type": "module",

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, 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 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,6 +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 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.
@@ -48,6 +49,7 @@ Natural-language forms:
 - `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 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`. 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 press Enter.
 - `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 recover <conversation-id>`: call `agent_knock_knock_recover`.
@@ -73,6 +75,7 @@ AKK Codex: review the current branch and propose a small fix
 AKK Claude: review the latest commit
 AKK Cursor: fix the flaky UI test
 akk list
+akk describe task-20260618T010203Z-abcdef12
 akk send task-20260618T010203Z-abcdef12: continue with the smaller implementation
 再让刚才那个 Codex 分析 ~/chrome-debug 为什么占空间
 akk cancel task-20260618T010203Z-abcdef12
@@ -144,6 +147,8 @@ Use `agent_knock_knock_list` when the user asks about current active native Code
 - `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_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:
 
 - `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.