@scotthuang/agent-knock-knock 0.16.6 → 0.16.8

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

@@ -25,7 +25,9 @@ A Codex `Folder access` / `Trust this folder?` dialog is a persistent local trus
 
 Present `conversations[]` as **CLI** or **Desktop** using `surface`, and keep Codex/Claude Code as the agent type. Select the displayed `conversation_id` and its advertised operation; AKK chooses the connection internally. Do not make separate user-facing backend and terminal lists, repeat raw discovery arrays, or count Watches as additional conversations or tasks. Preserve unavailable actions, current questions/approvals, and management/recovery records. Scoped controls, when present, are operations on exact targets within a row, not extra conversations.
 
-Explain each row's `usage` in the user's language: `summary` says whether it can be used now, `available` says what for, `limitations` explains what is unavailable, and `next_steps` gives concrete actions. Do not merely show missing capability switches or internal error codes. Guidance is recomputed from current actions, activity and blockers; it neither grants authority nor overrides `available_actions`. An idle native Claude conversation without Watch is still usable when Send is offered: send the requested task and retain its automatically created Turn or Watch. A terminal-only Watch observes terminal activity, not exact native task completion.
+Default List defers detailed approval, composer and native task scans. `detail_scan: deferred` or `approval_state.scanned: false` means the detail was not checked, not that no approval or input blocker exists. Use the advertised Status action for details; an explicit detailed scan is available through `noApprovalScan: false` (CLI `--approval-scan`). Send and other mutations still validate fresh target identity, input ownership and blockers before execution; List observations never authorize cached input.
+
+Explain each row's observed state and offered actions in the user's language. Compact List v5 omits derived `usage`; use its readable state values, capability booleans, `available_actions`, dynamic `action_inputs` and current exceptions such as `manual_action`, and read exact Status when more explanation is needed. In v4, `usage.summary`, `available`, `limitations` and `next_steps` also provide display guidance. Guidance never grants authority or overrides `available_actions`; missing `usage` does not mean missing capability or monitoring. Keep `unknown`, `null`, `false` and `deferred` distinct: an unknown state is not idle, a null interaction count is not zero, and an unscanned detail is not proof of no blocker. An idle native Claude conversation without Watch is still usable when Send is offered: send the requested task and retain its automatically created Turn or Watch. A terminal-only Watch observes terminal activity, not exact native task completion.
 
 An unresolved Claude terminal receives one additional fresh reader check during List, shared across unresolved panes in that scan, without terminal input. A separate read-only check can explain that the foreground window is in the background-session interface only when its owned registry and live process incarnation verify that role. This role does not mean the window cannot receive input. When its real `terminal_user_explicit` Send is offered, explain: 可以向此窗口发送任务。AKK 会输入文字并提交，但目前无法可靠确认后台任务的接受和完成状态；请在窗口中查看执行结果。 Without that physical action, the user can continue manually or start an ordinary foreground conversation and refresh List. Reopening the same background conversation does not add native acceptance or completion proof. This diagnostic never binds a background worker, grants actions, or authorizes daemon/claim-socket access.
 
@@ -215,7 +217,7 @@ Approval attention is notification-only for every Watch: never call an approval
 
 DSH restart recovery, when the Host provides persistent Session recovery and flushing, retains callback ownership for the original profile, Store, and Session generation while rotating the private IPC channel. A delivered notification means durable inbox admission, not that the model consumed it. Historical process-private DSH routes require explicit operator adoption of the exact Watch and original Host Profile; never rewrite Store routes or infer ownership from a decoded session ID. A successful Host restart or reconciliation sweep alone does not prove Watch settlement or callback delivery. Check those separately. Unknown activity must remain pending, and terminal-activity idle remains best-effort evidence.
 
-The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v35. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v4 and point here for the static contract; the CLI keeps the complete operator/debug action contract. 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`.
+The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v35. Updated OpenClaw, Pi, and DeepSeek Harness Lists default to compact projection v5 (explicit v4 remains available) and point here for the static contract; the CLI keeps the complete operator/debug action contract. 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 Codex permission changes, first call `agent_knock_knock_permission_options({terminal_id})` from the current row’s advertised action. This sends closed `/status` and `/permissions` inspection input but leaves permissions unchanged; the terminal must be idle, its Composer empty, and its physical and native thread identities verifiable. Use `current`, `scope`, and the returned choice descriptions to select the requested or authorized mode. Then call `agent_knock_knock_set_permissions({terminal_id,mode})` using its exact returned semantic ID in the same controller conversation. Full Access is an ordinary option and needs no additional user confirmation. AKK automatically handles its exact native confirmation inside this permission transaction; do not pause to ask the user to confirm Full Access or call generic `approve` for that dialog. Ordinary Send does not change permissions. Codex 0.160 may report `current="workspace_granular"`; this is a current-only native default, not a selectable mode. Select only an ID actually returned in `choices`. Only currently displayed built-in modes are supported: do not invent `read_only` when the picker omits it, supply a named/custom profile, or pass commands, labels, menu indexes, keys, tokens, or scope overrides. Changes affect the current session/thread, may be retained on Resume, and leave global defaults unchanged. Send the intended task only after `outcome="changed"` or `"already_effective"` with matching `effective.mode`; `"uncertain"` means stop and do not retry automatically. Refresh the catalog after any change or consumed attempt.
 
@@ -328,17 +330,21 @@ The model-facing `agent_knock_knock_list` presents `conversations[]` once. Exact
 
 ### Compact controller-Host List projection
 
-The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=4`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, static action `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Bounded per-conversation `usage` is additive display guidance for Codex CLI, Codex Desktop, Claude and terminal-only rows, derived from current evidence; it keeps projection v4. Action contract v35 adds a no-existing-stash prerequisite to Claude physical Send, narrowing eligibility from v34; `physical_send_readiness` explains draft, stash, legacy-marker, foreground-turn and footer blockers without changing public call parameters or projection v4. The extra reader recheck and foreground background-view diagnosis are Claude-only. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
+Host List returns `projection.schema="agent-knock-knock/host-list-compact"`, `projection.skill="agent-knock-knock"`, a projection version and the CLI action-contract version. Updated first-party OpenClaw, Pi and DeepSeek Harness connectors default to v5; generic SDK and MCP callers default to v4. Set `listProjectionVersion: 5` to opt in, or `listProjectionVersion: 4` for the v4 shape. An explicit parameter takes precedence; `terminalDebug: true` without an explicit version defaults to v4. Read `projection.version` before interpreting the response. For an unfamiliar version, make a fresh read-only List request for v4 or inspect an already known exact target with Status; do not infer write authority from unfamiliar fields.
+
+Both formats omit repeated static `action_contracts`, static action `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, historical requests, completion text, screens and event/file paths from the normal view. V5 additionally removes the derived per-conversation `usage` and a row's `id` when it equals `conversation_id`; use `conversation_id` when that redundant `id` is absent. Distinct IDs, readable enums, booleans, capabilities, current actions and dynamic inputs, exceptions and manual-action instructions retain their v4 meanings. A Claude row also retains structured `physical_send_readiness` (`ready`, `reason`, `message`) from its single exactly associated folded terminal control, preserving draft/stash/marker reasons previously explained only in `usage`. Explicit row-level facts take precedence; multiple controls do not select an assumed window. This adds no action authority. There are no integer codes, codebook or extra dictionary reads. Use this Skill for general guidance and exact Status for current details; bounded dynamic failure messages and scan errors remain visible.
+
+The schema/catalog and Skill digests change for the new format, but action contract v35 remains unchanged: its no-existing-stash prerequisite still narrows Claude physical Send eligibility, and `physical_send_readiness` still explains draft, stash, legacy-marker, foreground-turn and footer blockers. Mutation parameters and guards are unchanged. The extra reader recheck and foreground background-view diagnosis are Claude-only. Use Status for one selected conversation, Turn or Watch and `/akk doctor` or the CLI for operator diagnostics.
 
 **Conversation-only List:** List returns currently discoverable conversations, including Desktop sidebar entries with unconfirmed live owners. It never includes Watch inventories or retained managed history. Keep current ownership, blockers and advertised approvals; do not interpret missing Watch fields as missing Send monitoring. Use `agent_knock_knock_watches` or `/akk watches` to inspect observations. Legacy `listView="history"/"all"`, `all=true` and CLI `list --all` return a migration error.
 
-Every Host List page has a total row limit (`listLimit`, default 40, maximum 100), a 24 KiB UTF-8 JSON ceiling and a conservative 12,000 weighted-character budget (ASCII 1, other code points 16), including metadata. Follow `pagination.next_args` unchanged while `has_more=true`. Desktop catalog pagination is separate: finish the Host pages, then use `desktop_scan.next_cursor` with the same Desktop filters and a fresh Host cursor. Discovery pages are live snapshots; restart if membership changes invalidate the cursor. No progress body is added to List. Oversized rows retain exact IDs and a Status entry point; their guidance says details were omitted and directs the user to Status, rather than describing those operations as unsupported. Refresh exact Status before acting.
+Every Host List page has a total row limit (`listLimit`, default 40, maximum 100), a 24 KiB UTF-8 JSON ceiling and a conservative 12,000 weighted-character budget (ASCII 1, other code points 16), including metadata. This is not a token count or a native-read budget. Follow `pagination.next_args` unchanged while `has_more=true`; cursors are projection-version-bound, so start a fresh List rather than continuing across v4/v5. Desktop catalog pagination is separate: finish the Host pages, then use `desktop_scan.next_cursor` with the same Desktop filters and a fresh Host cursor. Discovery pages are live snapshots; restart if membership changes invalidate the cursor. No progress body is added to List. Oversized rows retain exact IDs, `details_omitted` and a Status entry point, without reintroducing `usage` in v5; omitted actions on those rows are not unsupported actions. Refresh exact Status before acting.
 
 **Watch inventory:** `agent_knock_knock_watches` / `/akk watches` / CLI `watches` is a read-only Store query, defaulting to the most recent 24 hours, 40 rows per page (maximum 100), with a whole-response budget. `hours` accepts 1–48. Active or unresolved observations older than the window remain visible as `outside_window`; terminal managed Turns are a distinct section. Follow the returned pagination arguments. The query does not create/renew monitoring, reconcile or resend notifications. Use exact Status for actionable questions, approvals, callback recovery or full results. Native completion, controller acceptance and chat delivery are separate; `callback_expected=false` alone is neither failure nor delivery proof.
 
 Healthy completed Watch bodies are eligible for bounded background cleanup after 48 hours. Active, pending-interaction and unresolved callback records are retained. Cleanup preserves minimal deduplication tombstones; an exact expired record reports `watch_history_expired` and forbids replay. Never resend an old task because its body was pruned. Managed Turns, Sessions and native history are not deleted. See `docs/list-output.md` for retention and migration details.
 
-For every resource, `available_actions` is an object whose keys are the exact current semantic action names and whose values are `true`. `action_inputs` contains only dynamic semantic values that cannot be derived from the parent resource, plus scope, permitted decision values, and fields listed by `missing_required`; it does not repeat the same terminal/Session/Turn/Watch ID for every action. The parent `conversation_id` is the target for Send, Status, Watch and supported conversation settings; AKK chooses the operation route. For capability-specific terminal actions, the terminal `id` remains the full `terminal_id`; managed and Watch records expose their own `session_id`, `turn_id`, or `watch_id`. `features` is only a compact capability-status summary and never authorizes an action. Never infer an absent action. The compact display is not the enforcement boundary: the plugin caches the complete private offer before projection, and the CLI re-observes and revalidates the live pane under its action lock before every mutation.
+For every resource, `available_actions` is an object whose keys are the exact current semantic action names and whose values are `true`. `action_inputs` contains only dynamic semantic values that cannot be derived from the parent resource, plus scope, permitted decision values, and fields listed by `missing_required`; it does not repeat the same terminal/Session/Turn/Watch ID for every action. The parent `conversation_id` is the target for Send, Status, Watch and supported conversation settings; AKK chooses the operation route. V5 may omit an equal duplicate `id`, never the authoritative `conversation_id`. Capability-specific terminal controls retain their own exact `terminal_id`/`id`; managed and Watch records expose their own `session_id`, `turn_id`, or `watch_id`. `features` is only a compact capability-status summary and never authorizes an action. Never infer an absent action. The compact display is not the enforcement boundary: the plugin caches the complete private offer before projection, and the CLI re-observes and revalidates the live pane under its action lock before every mutation.
 
 Action-name glossary: