@scotthuang/agent-knock-knock 0.12.13 → 0.12.15

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

@@ -23,7 +23,7 @@ Use the `/akk` command for slash-command syntax. Use the Agent Knock Knock plugi
 
 Core slash-command forms:
 
-- `/akk <task>`: send a new task only when exactly one eligible idle coding-agent pane exists across all workspaces.
+- `/akk <task>`: send a new task only when exactly one send-ready coding-agent pane exists across all workspaces.
 - `/akk <selector>: <message>`: resolve one exact eligible AKK session and create a new Turn for the message.
 - `/akk list`: list live coding-agent terminals, their current or recent managed-turn context, and durable Terminal Watches.
 - `/akk watch <exact-terminal-id>`: observe one exact supported task that the human already started in the TUI, without sending input or creating a Session or Turn.
@@ -35,7 +35,7 @@ Core slash-command forms:
 - `/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 terminal pane.
 
-For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`, `only`, `latest`, or an `@short-ref` returned by `AKK list`. These selectors are only a resolution layer and fail closed when the target is missing or ambiguous. The v18 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. `send({session_id,request})` is strict `session_exact`; `send({terminal_id,request})` is `terminal_follow_current`; the two targets are mutually exclusive, and both may be omitted only when AKK must prove one unique eligible pane. Native-thread actions use the full `terminal_id`, never an `@short-ref`. Managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` after explicit user confirmation. The trusted plugin/CLI derives terminal, binding, candidate, prompt, handoff, and compare-and-swap fences privately, then revalidates them under the canonical terminal and Store locks. Never ask the user or model to copy a token, fingerprint, revision, binding ID/generation, or handoff-only live native UUID from an action; `native_thread_id` is the intentional semantic UUID for resume. For every side effect, AKK must revalidate the selected agent PID and provider-owned terminal identity, confirm that the process and pane working directories match, and revalidate the relevant composer or approval prompt.
+For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`, `only`, `latest`, or an `@short-ref` returned by `AKK list`. These selectors are only a resolution layer and fail closed when the target is missing or ambiguous. The v19 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. `send({session_id,request})` is strict `session_exact`; `send({terminal_id,request})` is either managed `terminal_follow_current` or user-priority `terminal_user_explicit`, exactly as advertised; the two target fields are mutually exclusive, and both may be omitted only when AKK must prove one unique send-ready pane. `terminal_user_explicit` depends on the exact live terminal/process, verified non-blocked approval state, and exact empty composer—not AKK Store, Turn, Session, transfer, transition, ledger, ownership, or activity state. AKK tries managed delivery first; if internal preparation fails before any input, it sends once without a callback Turn and then releases stale management best-effort. With runtime durability, an omitted target binds its `message_id` to the first selected physical terminal and existing or uncertain same-ID evidence rejects replay. If fresh durability is unavailable, user priority wins: AKK proceeds with a warning, and the degraded result must not be automatically retried. Refresh list and use Watch for that task. The only non-ordinary Send form is an exact `send({turn_id})` copied unchanged from a current `available_actions.retry_submission`; it accepts no request text or other target and requires explicit user confirmation. Native-thread actions use the full `terminal_id`, never an `@short-ref`. Other managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` after explicit user confirmation. The trusted plugin/CLI derives terminal, binding, candidate, prompt, handoff, and compare-and-swap fences privately. Never ask the user or model to copy a token, fingerprint, revision, binding ID/generation, or handoff-only live native UUID from an action; `native_thread_id` is the intentional semantic UUID for resume. For every side effect, AKK must revalidate the selected agent PID and provider-owned terminal identity and revalidate the relevant composer or approval prompt.
 
 The human-priority Codex path may proceed when the pane/process and complete open-rollout candidate inventory are exact even though no single foreground UUID can be selected, including a supported manual `/clear` whose new logical thread appears before its rollout materializes. The complete exact inventory domain binds the provider terminal, PID and process birth, workspace and canonical endpoint, and every open rollout's UUID, descriptor, device, inode, canonical path, and pre-submit byte offset. A `/clear` resume hint is advisory only, never routing or acceptance authority. Under the terminal lock, AKK isolates the predecessor, creates a separate zero-UUID provisional Session and Turn, sends the real task once, and binds only the single candidate rollout that durably accepts that exact request. A rollout-backed Codex row therefore advertises `terminal_follow_current` with `terminal_id`, not `session_exact`; a cached strict Session attempt rejects before task text and never downgrades itself. Only released predecessor Turn history from a strictly earlier binding epoch is excluded from current-send authority; unresolved current-epoch state still blocks. Use only the freshly listed semantic-ID action. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. If delivery or acceptance is uncertain, do not retry automatically. Terminal-scoped manual Codex approval likewise exposes only `terminal_id`, requires explicit confirmation, leaves managed identity unchanged, never participates in auto-approval, and must not be retried blindly after an uncertain result.
 
@@ -45,13 +45,14 @@ AKK discovers eligible panes across workspaces. When more than one target matche
 
 Natural-language forms:
 
-- `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one eligible idle pane exists.
+- `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one send-ready pane exists; parsed activity and broken AKK management state do not veto an otherwise exact empty physical prompt.
 - `AKK Codex: <task>`: list first, require one exact eligible Codex row, then call `agent_knock_knock_send` with that row's `terminal_id` and `request=<task>`.
 - `AKK Claude: <task>`: list first, require one exact eligible Claude row, then call `agent_knock_knock_send` with that row's `terminal_id` and `request=<task>`.
 - Requests to list AKK or local coding-agent work: call `agent_knock_knock_list`.
 - Requests to observe work the human started directly in the Codex or Claude Code TUI: first call `agent_knock_knock_list`, then call `agent_knock_knock_watch` only from that exact active terminal row's freshly advertised `watch` action. Pass its complete `terminal_id`; AKK resolves and revalidates the current binding authority internally, so no binding token crosses the model-facing Watch boundary.
 - Requests to inspect an existing Terminal Watch: call `agent_knock_knock_status` with its authoritative `watch_id`. Requests to stop observing it: call `agent_knock_knock_unwatch` with that same `watch_id`. Never substitute a Session, Turn, terminal selector, or short reference.
 - Requests to continue in the current terminal context after the human may have run `/clear`, `/new`, `/resume`, or an equivalent native operation: first call `agent_knock_knock_list`, then use only that exact terminal row's advertised `send({terminal_id,request})`; do not substitute the stale `session_id`.
+- Requests to recover an AKK submission reported as uncertain: refresh `agent_knock_knock_list`. Only if the current exact Turn advertises `retry_submission`, explain that AKK will revalidate the immutable original request and may either press one Enter for the exact existing draft or retransmit that original text once after structured no-Enter proof and a positively empty composer. Require explicit user confirmation, then call the prefilled `agent_knock_knock_send({turn_id})` unchanged. Never add `request`, terminal/Session IDs, timeout fields, or callback route data, and never retry it automatically.
 - Requests for the coding agent's native Codex status card or Claude Status panel: first call `agent_knock_knock_list`, then call `agent_knock_knock_native_inspect({terminal_id,inspection:"status"})` only when the exact terminal row advertises it; do not substitute AKK Turn status or ordinary send.
 - 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({terminal_id})` only from an advertised `new_thread` action.
@@ -65,7 +66,7 @@ Natural-language forms:
 
 ## Sessions and Turns
 
-AKK's identity hierarchy is terminal → native Codex or Claude Code session → AKK session → Turns. `session_id` is the strict ordinary-send target for one exact native context. `terminal_id` is the deliberately different follow-current target that lets the user hand the pane's currently verified context back to AKK after a safe human-driven switch. Each accepted send creates a distinct `turn_id` without clearing the native agent context. A `turn_id` is only for history, callbacks, respond, status, approval, cancellation, renewal, callback retry, and close.
+AKK's identity hierarchy is terminal → native Codex or Claude Code session → AKK session → Turns. `session_id` is the strict ordinary-send target for one exact native context. `terminal_id` is the deliberately different follow-current target that lets the user hand the pane's currently verified context back to AKK after a safe human-driven switch. Each accepted ordinary send creates a distinct `turn_id` without clearing the native agent context. A `turn_id` is used for history, callbacks, respond, status, approval, cancellation, renewal, callback retry, close, and the explicitly advertised submission-retry form of Send.
 
 Use `agent_knock_knock_send` with `request` and neither `session_id` nor `terminal_id` only when the target is unspecified. AKK must resolve exactly one eligible Codex or Claude Code pane across all workspaces, attach or discover its AKK session, and verify that it is idle immediately before writing the request. If no eligible pane exists, report AKK's setup guidance; do not substitute another execution path.
 
@@ -76,8 +77,8 @@ For ordinary send or an in-flight answer:
 1. Reuse an AKK session only when the user's reference uniquely identifies its verified native session and terminal incarnation.
 2. If no ID is supplied and more than one eligible pane may exist, call `agent_knock_knock_list`.
 3. Treat `terminals[]` as the primary resource list. Its managed context exposes `session_id`; `managed.current_turn` is the only current AKK owner, while `managed.recent_turn` and `managed.history` are retained Turn history. Records in `unavailable_managed_turns[]` have no live pane in this snapshot.
-4. Read the selected resource's `available_actions`. Use only an action present there, start with its prefilled semantic IDs, supply every `missing_required` field, and consult the top-level v18 `action_contracts`. The only additional action sources are a terminal row's `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`: use either only after explicit user confirmation and refresh the list immediately afterward.
-5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context. If the selected row instead advertises follow-current send, call `agent_knock_knock_send({terminal_id,request})`; this action may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. The status-card-only first-task path remains the zero-rollout special case. Never construct or pass an opaque fence. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
+4. Read the selected resource's `available_actions`. Use only an action present there, start with its prefilled semantic IDs, supply every `missing_required` field, and consult the top-level v19 `action_contracts`. The only additional action sources are a terminal row's `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`: use either only after explicit user confirmation and refresh the list immediately afterward.
+5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context. If the selected row advertises terminal-scoped send, call `agent_knock_knock_send({terminal_id,request})`. `terminal_follow_current` may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. `terminal_user_explicit` instead preserves the user's Send when internal AKK state is broken: managed delivery is attempted first, but a proven zero-input failure falls back to one unmanaged delivery with no callback Turn. Refresh list and use Watch afterward. The status-card-only first-task path remains the zero-rollout special case. `send({turn_id})` is never an ordinary target: use it only for a fresh `retry_submission` action after explicit confirmation, with no other field. Never construct or pass an opaque fence. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
 6. If multiple terminals match, show their `short_ref`, agent, provider, and terminal target, then ask the user to choose. If a human switch has an unresolved Turn, ambiguous ownership, or unverifiable identity and no follow-current send is advertised, report that blocker and ask the user which context to resolve; never guess, supersede active work, or bypass the fence.
 
 An idle pane is at a verified ready prompt, with no current work or unresolved permission request. A previously completed managed turn alone is not proof that the pane is still idle.
@@ -96,12 +97,12 @@ Its authority is the exact terminal endpoint and process incarnation, native thr
 
 Approval is notification-only. Show the user that the watched TUI needs attention and tell them to inspect and decide there. Never call an approve tool for a Watch, send approval keys, or apply `autoApprove`; a new exact approval fingerprint is notified once while the Watch remains active. Terminal outcomes settle once. The durable outbox uses deterministic notification IDs/idempotency and leased retry, so startup and periodic supervision can safely recover callback delivery after AKK, OpenClaw, or Gateway restart.
 
-The current plugin registers 16 OpenClaw tools and list action-contract v18. Every structured model action carries semantic IDs only; opaque fences are derived and revalidated privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
+The current plugin registers 16 OpenClaw tools and list action-contract v19. Every structured model action carries semantic IDs only; opaque fences are derived and revalidated privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
 
 For native status inspection:
 
 1. Use only a current `available_actions.native_inspect({terminal_id,inspection:"status"})` entry. Those semantic arguments are complete; never add a command or authority field.
-2. Supported exact profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0 and Claude Code 2.1.218/2.1.226/2.1.237 `inspection="status"`. Claude success includes parsing and safely dismissing the newly opened Status panel. The tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, `/model`, `/compact`, and unsupported versions remain unavailable. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
+2. Supported exact profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1 and Claude Code 2.1.218/2.1.226/2.1.237 `inspection="status"`. Claude success includes parsing and safely dismissing the newly opened Status panel. The tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, `/model`, `/compact`, and unsupported versions remain unavailable. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
 3. Treat this as terminal input even though the native command is read-only. AKK privately derives a fresh binding fence and requires an idle empty composer, exact PID/process/pane/cwd/version identity, and no conflicting Turn, transition, dispatch, approval, or owner.
 4. Codex `/status` requires an exact viewport of at least 80 columns so the full Session UUID can be proven. That pre-UUID gate applies to native inspection, lifecycle, and strict Session operations that must know the UUID before terminal input. An otherwise eligible terminal-scoped ordinary task may send once and bind from exact native acceptance afterward, so it does not run `/status` or fail merely because the pane is narrow.
 5. The result is valid only when AKK proves one fresh bounded native status result and the pane returns to idle. On an uncertain or unproven submission, do not retry, send Enter, clear the composer, or bypass AKK with raw terminal input.
@@ -160,7 +161,9 @@ Use `agent_knock_knock_renew` only when AKK marked the same live terminal Turn `
 
 Use `agent_knock_knock_retry_callback` only for a `callback_failed` managed turn, for example `/akk retry-callback @a1b2c3d4`.
 
-Use `agent_knock_knock_close` only when the user explicitly wants to close AKK's managed record. If `AKK list` reports an orphaned terminal dispatch or lifecycle transition, inspect the pane first and use the exact recovery action it returns. `expected_message_id` and `expected_transition_id` remain public because they identify durable entities; they are not authority tokens. If a terminal row exposes `blocking_turns[]`, do not send, inspect natively, or mutate lifecycle state; present the exact collateral blocking Turn and invoke its nested Store-only `recovery_action` only after explicit user confirmation, then refresh the list. An active human-handoff source Turn is deliberately excluded from this generic recovery list. If a verified human native-thread switch conflicts with one active Turn, do not redirect or close it automatically. Present `handoff_decision` to the user. Only after the user chooses takeover may you invoke `agent_knock_knock_close({turn_id,reason:"superseded_by_human_context_switch"})`. AKK privately resolves and revalidates the exact advertised handoff decision; the model does not carry a handoff token or live native UUID. This close sends no terminal input. Refresh `agent_knock_knock_list` afterward and use only its new follow-current send. If the user keeps the source Turn, make no AKK mutation; ask them to restore its native thread in the TUI and then refresh. Closing a managed record does not close the coding agent or terminal pane.
+Submission retry remains part of `agent_knock_knock_send`, not callback retry or renewal. Use its exact `{turn_id}` form only from a current advertised `retry_submission` action and only after explicit confirmation. AKK never accepts replacement text from the caller, never clears the composer, and never sends Control-C. It first checks for native acceptance and repairs state without input when possible. Otherwise it fails closed unless it can prove the exact existing draft for one Enter, or prove both that Enter was never attempted and that the live composer is positively empty before retransmitting the immutable original request once. Any terminal, identity, route, draft, modal, approval, working-state, or one-shot reservation drift sends no further input.
+
+Use `agent_knock_knock_close` only after the user explicitly asks to close the selected AKK Turn. That explicit choice has priority over stalled, deferred-transfer, Session, ledger, handoff, callback, or receipt conflicts: Close first records the Turn as closed and releases AKK management. It never sends terminal input, interrupts or stops the coding agent, or closes the terminal pane. Cleanup of linked AKK transfer, Session, ledger, and callback metadata is best-effort; preserve stale, malformed, or newer records and report warnings instead of refusing the user's Close. A callback attempt already in flight or accepted by the host may still arrive, but Close authorizes no new callback start or retry. Refresh `agent_knock_knock_list` afterward; if the coding agent is still working, use the newly advertised Watch action to observe it again. Orphan terminal-dispatch/lifecycle recovery with `expected_message_id` or `expected_transition_id` remains a separate raw-terminal operation.
 
 Use `/akk doctor` only for installation checks or troubleshooting.
 
@@ -187,9 +190,9 @@ 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; independent observation-only records appear in `terminal_watches[]` and are addressed only by `watch_id`. `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. A human-driven thread mismatch remains `management_state="conflict"`; `handoff_state="external_handoff_adoptable"` authorizes only the exact fenced `send` advertised on that row, while `external_handoff_blocked` means do not send or guess a recovery. Listing itself never adopts the new context. Request `all=true` only when older `managed.history`, settled Terminal Watches, or retained unavailable history is needed. By default, `unavailable_managed_turns[]` contains attention-needed records whose terminal is unavailable.
 
-The top-level v18 `action_contracts` summarizes each tool's semantic-ID inputs; `available_actions` is the authoritative current-action source after listing except for the explicitly modeled nested handoff decision and `blocking_turns[].recovery_action`. Approval, handoff takeover, and `reconcile_binding` require explicit user confirmation and a fresh list after success. Model-facing shapes are: `watch({terminal_id})`; `send({session_id|terminal_id,request})`, with the targets mutually exclusive; managed `approve({turn_id})` or terminal-scoped `approve({terminal_id})`; `native_inspect({terminal_id,inspection})`; `new_thread({terminal_id})`; `resume_thread({terminal_id,native_thread_id})`; and `reconcile_binding({terminal_id,conflicting_session_id})`. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request; human-facing numbers and short IDs remain slash-navigation aids and are never structured tool arguments. The model never carries terminal, binding, candidate, handoff, approval, revision, binding ID/generation, or handoff-only live-native-UUID fences; `native_thread_id` remains the semantic resume identity. AKK derives those private fences and revalidates them under lock before side effects. Orphan-close `expected_message_id` and `expected_transition_id` remain because they are entity IDs. Store format remains 1 and writer protocol remains 5.
+The top-level v19 `action_contracts` summarizes each tool's semantic-ID inputs; `available_actions` is the authoritative current-action source after listing except for the explicitly modeled nested handoff decision and `blocking_turns[].recovery_action`. Approval, handoff takeover, and `reconcile_binding` require explicit user confirmation and a fresh list after success. Model-facing shapes are: `watch({terminal_id})`; `send({session_id|terminal_id,request})`, with the targets mutually exclusive; managed `approve({turn_id})` or terminal-scoped `approve({terminal_id})`; `native_inspect({terminal_id,inspection})`; `new_thread({terminal_id})`; `resume_thread({terminal_id,native_thread_id})`; and `reconcile_binding({terminal_id,conflicting_session_id})`. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request; human-facing numbers and short IDs remain slash-navigation aids and are never structured tool arguments. The model never carries terminal, binding, candidate, handoff, approval, revision, binding ID/generation, or handoff-only live-native-UUID fences; `native_thread_id` remains the semantic resume identity. AKK derives those private fences and revalidates them before side effects. Orphan-close `expected_message_id` and `expected_transition_id` remain because they are entity IDs. Store format remains 1 and writer protocol remains 5.
 
-Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal 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 or Herdr session and continue directly at any time.
+Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal identity. Sending new work additionally requires an exactly empty composer and a verified non-blocked approval state; parsed `activity_state` alone never vetoes `terminal_user_explicit`. Humans can attach to the same tmux or Herdr session and continue directly at any time.
 
 Claude Code completion depends on a strictly correlated local transcript turn and fails closed for unknown schemas, background work, or ambiguous identity. Never report completion merely because the pane looks idle.