@scotthuang/agent-knock-knock 0.10.3 → 0.11.0

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

@@ -28,7 +28,7 @@ Core slash-command forms:
 - `/akk list`: list live coding-agent terminals with their current or recent managed-turn context.
 - `/akk threads <exact-terminal-id>`: list verified native threads that may be resumed in one exact terminal.
 - `/akk new-thread <exact-terminal-id>` or `/akk clear-thread <exact-terminal-id>`: switch that idle terminal to a verified clean native context without creating a Turn.
-- `/akk resume-thread <exact-terminal-id> [native-thread-uuid]`: list candidates when the UUID is omitted, or resume one exact returned native thread without creating a Turn.
+- `/akk resume-thread <exact-terminal-id> [uuid|previous|number|@short-id|snapshot-handle]`: list candidates when the selection is omitted, or resume one exact snapshot-bound choice without creating a Turn. `previous` also accepts the human phrase `刚才那个`.
 - `/akk status [turn-selector]`: inspect one live terminal or exact managed Turn.
 - `/akk respond <turn-selector>: <answer>`: answer a coding-agent question inside a `waiting_for_openclaw` Turn.
 - `/akk cancel <turn-selector>`: interrupt the exact Turn without closing its tmux pane.
@@ -45,7 +45,7 @@ Natural-language forms:
 - Requests to list AKK or local coding-agent work: call `agent_knock_knock_list`.
 - Requests to list resumable native threads for an exact terminal: call `agent_knock_knock_list_resumable_threads` with the terminal row's prefilled `terminal_id`.
 - Explicit requests to start a new thread or clear context: call `agent_knock_knock_new_thread` only from an advertised `new_thread` action, preserving its exact `terminal_id` and `expected_binding_token`.
-- Explicit requests to resume prior native context: first call `agent_knock_knock_list_resumable_threads`; then call `agent_knock_knock_resume_thread` with the same exact `terminal_id`, the complete UUID and opaque `candidate_token` from one `resumable=true` row, and the `expected_binding_token` from that same result.
+- Explicit requests to resume prior native context: first call `agent_knock_knock_list_resumable_threads`; then call `agent_knock_knock_resume_thread` with the same exact `terminal_id`, the complete UUID and opaque `candidate_token` from one `resumable=true` row, and the `expected_binding_token` from that same result. For “previous” / “刚才那个”, proceed only when that fresh result contains `previous.available_actions.resume_thread`, and use that exact action; never substitute the newest row.
 - Requests to inspect current output or ask what a task is doing: call `agent_knock_knock_status`.
 - A later request for an existing listed AKK session: call `agent_knock_knock_send` with its authoritative `session_id` and `request=<message>`; this creates a new Turn in the same native context.
 - Requests to continue the current thread are ordinary sends, not lifecycle actions.
@@ -75,7 +75,7 @@ For native-thread lifecycle discovery or mutation:
 
 1. Start from the exact terminal row's currently advertised `list_resumable_threads` or `new_thread` action. Listing is read-only, requires only the full `terminal_id`, and creates no Turn.
 2. Before either mutation, `new_thread` or `resume_thread`, the terminal must be verified idle and have no active or unresolved Turn. Preserve the exact `expected_binding_token` from the same current terminal action or lifecycle-list result. Never construct, guess, or reuse it after another terminal action.
-3. For resume, list candidates first and invoke only the `resume_thread` action advertised by one candidate row with `resumable=true`. Preserve that row's complete `native_thread_id` and opaque `candidate_token`; never select by title, preview, recency, or a partial UUID, and never combine values from different snapshots.
+3. For resume, list candidates first and invoke only the `resume_thread` action advertised by one candidate row with `resumable=true`. Preserve that row's complete `native_thread_id` and opaque `candidate_token`; never select by title, preview, recency, or a partial UUID, and never combine values from different snapshots. Structured tool calls always use the exact full action. Human slash-command numbers and collision-safe short IDs refer only to the latest candidate snapshot displayed in that same OpenClaw session; an opaque handle names one exact snapshot, and all expire or fail after relevant terminal state changes. If the user says “previous” or “刚才那个”, use only an advertised `previous` action derived from the latest committed transition; if absent, explain that AKK cannot prove it and ask the user to list/select instead.
 4. Treat mutation success as a Session/native-context transition, not as task delivery. It creates or activates an AKK `session_id`, advances the terminal binding generation, and creates no `turn_id`. The next ordinary send creates the first Turn in that context.
 5. If the agent/version is unsupported, a candidate is ambiguous or active elsewhere, the token is stale, or post-transition identity cannot be verified, fail closed and report the error. Do not fall back to raw terminal commands.
 
@@ -88,6 +88,8 @@ Useful examples:
 /akk list
 /akk threads terminal:v2:tmux:codex:akk-work:0.0:1234
 /akk new-thread terminal:v2:tmux:codex:akk-work:0.0:1234
+/akk resume-thread terminal:v2:tmux:codex:akk-work:0.0:1234 previous
+/akk resume-thread terminal:v2:tmux:codex:akk-work:0.0:1234 2
 /akk resume-thread terminal:v2:tmux:codex:akk-work:0.0:1234 11111111-1111-4111-8111-111111111111
 /akk status only
 /akk respond @a1b2c3d4: use the existing JSON format
@@ -151,7 +153,7 @@ A trusted, default-disabled plugin `autoApprove` policy may independently approv
 
 `agent_knock_knock_list` is terminal-first: every eligible already-running Codex or Claude Code pane appears once in `terminals[]`, even when retained managed Turns reference it. The resource chain is terminal → verified native session → managed AKK `session_id` → Turns. `process_state` reports process liveness and `activity_state` reports the parsed screen state. `managed.current_turn` is the authoritative active Turn for that terminal; otherwise `managed.recent_turn` shows the newest retained context. Request `all=true` only when older `managed.history` or retained unavailable history is needed. By default, `unavailable_managed_turns[]` contains attention-needed records whose terminal is unavailable.
 
-The top-level v5 `action_contracts` summarizes each tool's managed target and its narrow compatibility inputs; `available_actions` is the authoritative current-action source after listing. An existing managed Session's ordinary `send` targets `session_id` and starts a new managed Turn. On first attach only, `selector` may preserve a discovery target explicitly named by the user or the exact selector prefilled by an unmanaged raw-terminal row; it must never be passed as `session_id`. `respond` and every managed control target `turn_id`; `respond` is offered only for a Turn waiting on OpenClaw. The read-only `list_resumable_threads` action is advertised on the terminal row, requires only its full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows. The `new_thread` mutation is advertised on the terminal row and requires that terminal ID and token; each resumable candidate row advertises its own `resume_thread` mutation with the same snapshot token, its complete `native_thread_id`, and its opaque `candidate_token`. Lifecycle discovery and mutations never create a Turn. A raw terminal may be controlled only through the exact action that its own row advertises; prefilled compatibility selectors, lifecycle IDs, and tokens must never be inferred, copied from another row, or reused from another snapshot. Start with the prefilled full argument, supply all `missing_required` fields, and use a returned `@short-ref` only for human-facing ordinary-send selection. Availability is a snapshot, so AKK revalidates it before side effects.
+The top-level v5 `action_contracts` summarizes each tool's managed target and its narrow compatibility inputs; `available_actions` is the authoritative current-action source after listing. An existing managed Session's ordinary `send` targets `session_id` and starts a new managed Turn. On first attach only, `selector` may preserve a discovery target explicitly named by the user or the exact selector prefilled by an unmanaged raw-terminal row; it must never be passed as `session_id`. `respond` and every managed control target `turn_id`; `respond` is offered only for a Turn waiting on OpenClaw. The read-only `list_resumable_threads` action is advertised on the terminal row, requires only its full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows. The `new_thread` mutation is advertised on the terminal row and requires that terminal ID and token; each resumable candidate row advertises its own `resume_thread` mutation with the same snapshot token, its complete `native_thread_id`, and its opaque `candidate_token`. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request. Number, short ID, and snapshot handle fields are human-facing navigation only; never pass them to the exact resume tool. Lifecycle discovery and mutations never create a Turn. A raw terminal may be controlled only through the exact action that its own row advertises; prefilled compatibility selectors, lifecycle IDs, and tokens must never be inferred, copied from another row, or reused from another snapshot. Start with the prefilled full argument, supply all `missing_required` fields, and use a returned `@short-ref` only for human-facing ordinary-send selection. Availability is a snapshot, so AKK revalidates it before side effects.
 
 Before every terminal operation, AKK revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories match. Sending new work additionally requires a verified idle prompt. Humans can attach to the same tmux session and continue directly at any time.