@scotthuang/agent-knock-knock 0.12.19 → 0.12.21

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

@@ -26,7 +26,7 @@ Core slash-command forms:
 - `/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 structurally validated task that the human already started in the TUI, without sending input or creating a Session or Turn.
+- `/akk watch <exact-terminal-id>`: observe one exact user-selected terminal without sending input or creating a Session or Turn; prefer an exact task anchor and otherwise use a clearly labeled best-effort terminal-activity Watch.
 - `/akk unwatch <watch-id>`: cancel only that observation; do not interrupt or otherwise change the TUI task.
 - `/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.
@@ -51,7 +51,7 @@ Natural-language forms:
 - `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 observe an exact Codex or Claude Code terminal: normally call `agent_knock_knock_list` and copy that row's advertised `watch` action, then pass its complete `terminal_id`. If the user explicitly selected a complete exact terminal ID, missing `available_actions.watch` is not a veto: Watch is read-only and may still be called with that ID. Never guess, shorten, or substitute a selector. AKK prefers an exact task anchor and otherwise records warnings and observes the terminal/process activity epoch.
 - 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.
@@ -79,7 +79,7 @@ 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 v23 `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.
+4. Read the selected resource's `available_actions`. For every mutation, use only an action present there, start with its prefilled semantic IDs, supply every `missing_required` field, and consult the top-level v23 `action_contracts`. Read-only Watch is the exception: explicit user intent plus one complete exact `terminal_id` is sufficient even when `available_actions.watch` is absent. The only additional mutation 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 and may require exact empty before input. 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: Codex replaces the current Composer with the new request and submits exactly once without a post-text Composer veto; Claude remains exact-empty-only. Managed delivery is attempted where eligible, but a proven zero-input failure falls back to one unmanaged delivery with no managed callback Turn. After Enter, AKK best-effort attaches a Terminal Watch callback; Watch failure never changes the successful Send. Once Codex mutation begins, an uncertain result must not be retried automatically. Wait for an attached Watch callback or use its status as recovery. 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 or composer authority. 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.
 
@@ -89,22 +89,26 @@ Do not treat ordinary send as native clear, new-session, fork, branch, side thre
 
 ## Terminal Watch
 
-The manual Terminal Watch action is only for one task that the human started directly in the live TUI. The required sequence is human starts the task in Codex or Claude Code → fresh `agent_knock_knock_list` or `/akk list` while it is working or awaiting approval → copy only that row's complete advertised `watch` action → retain the returned `watch_id` for status or unwatch. The slash form `/akk watch <exact-terminal-id>` performs its own fresh list lookup and requires that exact row to still advertise `watch`. A successful `terminal_user_explicit` unmanaged fallback may separately return an automatic Watch for the exact request AKK just sent; retain that returned `watch_id` and use status for recovery.
+Terminal Watch is read-only and user-intent-first. The normal sequence is user selects a Codex or Claude Code terminal → fresh `agent_knock_knock_list` or `/akk list` → copy its complete `terminal_id` and, when present, its advertised `watch` action → retain the returned `watch_id` for status or unwatch. Advertisement is discovery help, not Watch authorization. If the user explicitly supplies one complete exact terminal ID, call `agent_knock_knock_watch({terminal_id})` even when that row does not advertise Watch. Never infer a terminal or use a selector/short ID.
 
-Never suggest or call Terminal Watch for an active AKK-managed Turn. List and status omit the Watch prompt for that Turn, and a direct Watch attempt is rejected; use its existing managed monitor, status, and callback path instead.
+Managed ownership is not a veto. Prefer an existing managed Turn monitor when exact Turn attribution is wanted, but an explicit Watch may coexist because it sends no input and does not adopt, replace, close, reserve, block, interrupt, approve, or otherwise mutate that Turn, Session, terminal, or task. A successful `terminal_user_explicit` unmanaged fallback may separately return an automatic exact request-bound Watch after AKK sends; retain that `watch_id` and use status for recovery.
 
-The Watch is an independent durable schema-v2 aggregate, not a Conversation, Session, Turn, dispatch receipt, monitor owner, or terminal-input authority. The Watch itself neither sends input nor adopts, claims, reserves, blocks, interrupts, or continues a task. Manual Watch observes external human work; automatic fallback Watch is attached only after AKK has already sent the exact user request. `unwatch` marks only the Watch `cancelled`; it does not press a key or stop the coding agent.
+At creation, AKK first tries to build a privacy-safe exact provider task anchor. Codex binds rollout identity and request/turn byte boundaries; Claude binds transcript identity, root prompt, and current-turn byte boundaries. Success returns `watch_mode="exact_task"`, `confidence="exact"`. Later process, endpoint, native-thread, file identity, truncation/replacement, boundary, successor-task, or fingerprint drift invalidates that exact Watch rather than silently following another task.
 
-Its authority is the exact terminal endpoint and process incarnation, native thread/task, exact captured agent version, and privacy-safe provider anchor captured at creation. A missing regression-tested profile produces a warning but is not a Watch veto. Codex binds the exact rollout file plus the current human task's request/turn byte boundaries. Claude binds the exact transcript file, root prompt, and current-turn byte boundaries. Process, endpoint, native-thread, file identity, truncation/replacement, boundary, successor-task, version, fingerprint, missing-evidence, or ambiguity drift invalidates the Watch. Never follow the pane's current task or reconstruct a new anchor.
+Missing or mismatched agent-version evidence is always a warning and does not weaken an otherwise usable exact task anchor. If no unique usable anchor can be established because artifact, native-task, or boundary evidence is unavailable or incompatible, do not reject. AKK records those diagnostics in `warnings` and creates `watch_mode="terminal_activity"`, `confidence="best_effort"`. Binding metadata, managed ownership, and missing action advertisement likewise remain non-veto warnings. This fallback follows only the selected terminal/process activity epoch. It must first observe `working` or `awaiting_approval`, then stable `idle` across consecutive supervision sweeps. Starting at `idle` or `unknown` never settles immediately; later activity must be observed first.
 
-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.
+Treat a terminal-activity completion-shaped callback exactly as labeled: it means the observed terminal activity became idle. It is not proof that one exact task completed or succeeded, and it carries no exact-task completion text. State that limitation plainly to the user. Do not silently upgrade it to managed or exact-task attribution.
+
+Hard creation failure is limited to an absent exact terminal, inability to identify its endpoint/process, absence of both a durable exact-task anchor and a read-only screen-status activity path, or inability to create/write the durable Watch Store. Existing identical active observation may return its current `watch_id` instead of failing as a duplicate.
+
+Approval is notification-only in either manual Watch mode. 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 v23. Every structured model action carries semantic IDs only; opaque fences, Composer digests, and draft text are derived or retained 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. Regression-tested 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"`. Other complete `x.y.z` versions remain callable through the generic runtime profile and add a compatibility warning; actual incompatible UI or schema evidence fails at runtime and is not automatically retried. 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 arbitrary slash commands remain unavailable. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
+2. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1 and Claude Code 2.1.218/2.1.226/2.1.237 `inspection="status"`. Other complete `x.y.z` versions remain callable through the generic runtime profile and add a compatibility warning; actual incompatible UI or schema evidence fails at runtime and is not automatically retried. 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 arbitrary slash commands 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.
@@ -153,7 +157,7 @@ After an asynchronous send operation is accepted, end the OpenClaw turn. Wait fo
 
 ## Status
 
-For managed terminal entries, `agent_knock_knock_status` captures AKK Turn state plus a bounded terminal screen and returns `terminal_screen`. With `watch_id`, it returns the exact durable Terminal Watch and describes it as observed external work; it must not imply AKK sent or adopted the task. Neither form actively executes the coding agent's native `/status`. Use `agent_knock_knock_native_inspect` only for a terminal row's advertised, version-scoped native status action. Do not inspect the pane with raw provider or shell commands unless the relevant AKK inspection is unavailable or fails.
+For managed terminal entries, `agent_knock_knock_status` captures AKK Turn state plus a bounded terminal screen and returns `terminal_screen`. With `watch_id`, it returns the exact durable Terminal Watch record, including `watch_mode`, `confidence`, and any warnings. It must not imply that an exact task completed when a `terminal_activity` Watch only observed stable idle, or that Watch sent/adopted the task. Neither form actively executes the coding agent's native `/status`. Use `agent_knock_knock_native_inspect` only for a terminal row's advertised, version-scoped native status action. Do not inspect the pane with raw provider or shell commands unless the relevant AKK inspection is unavailable or fails.
 
 ## Cancellation and Recovery
 
@@ -165,7 +169,7 @@ Use `agent_knock_knock_retry_callback` only for a `callback_failed` managed turn
 
 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 `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, explicitly Watch its exact `terminal_id` whether or not that row advertises the convenience action. 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.
 
@@ -192,11 +196,11 @@ 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 v23 `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, composer, handoff, approval, revision, binding ID/generation, or handoff-only live-native-UUID fences; it never receives draft text or composer digests. `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 6.
+The top-level v23 `action_contracts` summarizes each tool's semantic-ID inputs. `available_actions` is the authoritative current-action source for mutations after listing except for the explicitly modeled nested handoff decision and `blocking_turns[].recovery_action`; read-only `watch({terminal_id})` deliberately honors an exact user-selected terminal even without advertisement. 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, composer, handoff, approval, revision, binding ID/generation, or handoff-only live-native-UUID fences; it never receives draft text or composer digests. `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 6.
 
 Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal identity. Native inspection, lifecycle input, and every Claude Code Send additionally require an exactly empty Composer; managed Send may require exact empty before input. Codex `terminal_user_explicit` instead requires a scanned, non-blocked approval state. Composer visibility, stability, exactness, and parsed working activity do not veto this user-priority path, and after text injection no Composer observation may veto Enter. 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.
+Exact-task Claude Code completion depends on a strictly correlated local transcript turn and fails closed for unknown schemas, background work, or ambiguous identity. A `terminal_activity` Watch may separately notify that the selected terminal became stably idle only after observed activity; always label that callback best-effort and never report it as exact task completion or success.
 
 ## Final User Reply