@scotthuang/agent-knock-knock 0.13.2 → 0.13.3

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

@@ -5,15 +5,15 @@ description: Control local Codex and Claude Code through shared tmux or Herdr te
 
 # Agent Knock Knock
 
-Use this skill when the user explicitly invokes `AKK`, `akk`, or `Agent Knock Knock`, or asks OpenClaw to inspect or control a coding-agent terminal listed by AKK.
+Use this skill when the user explicitly invokes `AKK`, `akk`, or `Agent Knock Knock`, or asks a supported controller Host to inspect or control a coding-agent terminal listed by AKK.
 
-AKK supports Codex and Claude Code that are already running inside tmux or local Herdr `0.8.0`. It never launches a coding agent. OpenClaw, the terminal host, AKK, and the coding agent must run as the same OS user.
+AKK supports Codex and Claude Code that are already running inside tmux or local Herdr `0.8.0`. It never launches a coding agent. The controller Host, terminal host, AKK, and coding agent must run as the same OS user.
 
 Treat `AKK` and `akk` the same way.
 
 ## Role
 
-OpenClaw interprets the user's request, sends the requested work into the selected shared terminal, handles actionable callbacks, and reports the outcome. The coding agent performs the engineering work in its existing tmux or Herdr terminal.
+The controller Host interprets the user's request, sends the requested work into the selected shared terminal, handles actionable callbacks, and reports the outcome. The coding agent performs the engineering work in its existing tmux or Herdr terminal.
 
 Keep the user's requested scope and approval boundaries. Do not expand a task, approve a permission, interrupt a process, or close a managed record unless the user request or an explicit trusted policy authorizes that action.
 
@@ -29,13 +29,16 @@ Core slash-command forms:
 - `/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 models <exact-terminal-id>`: inspect the exact native model and reasoning-effort catalog for one verified idle terminal.
+- `/akk repair-model-control <exact-terminal-id>`: dismiss only a currently advertised exact stale Codex 0.154 `/model` Composer surface or open native model picker and prove an empty Composer.
+- `/akk set-model <exact-terminal-id> <advertised-model-id> <advertised-reasoning-effort>`: consume that displayed catalog once and change only the advertised semantic tuple.
 - `/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> [uuid|previous|number|@short-id]`: 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|terminal-watch-id]`: inspect one live terminal, exact managed Turn, or exact Terminal Watch.
 - `/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 v25 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. Codex `terminal_user_explicit` depends on the exact live terminal/process, a scanned non-blocked approval state, and no active input-owning questionnaire/editor—not ordinary main-Composer visibility, stability, exactness, parsed working activity, or AKK Store, Turn, Session, transfer, transition, ledger, or ownership. Codex 0.154's exact collapsed async-question summary leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. It applies `replace_current_composer_and_submit`: physical fallback sends `C-u` once to replace the current Composer, injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. Claude Code remains exact-empty-only. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after user-explicit Codex text injection, that path follows the same no-Composer-veto Enter rule. A source-less Codex terminal with zero, one, or many pre-existing rollout roots freezes that full candidate set before input and binds only the unique rollout that later persists the exact request hash; a unique stale root is never assumed to be foreground. If managed preparation still fails before input, AKK sends once without a managed callback Turn, then best-effort attaches an exact request-bound Terminal Watch callback and releases stale management. Watch failure is a warning and never revokes or retries a successful Send. Native inspection and native lifecycle input remain exact-empty-only. 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. Once the Codex mutation sequence begins, an uncertain result must not be automatically retried. Read Send results as orthogonal facts: `terminal_input_dispatched`, `agent_acceptance`, `management_mode`, `observation_mode`, and `capabilities` distinguish physical dispatch from durable native acceptance and callback/interaction authority; do not infer one from another. If the result returns `observation_mode="terminal_watch"`, wait for that callback and retain `watch-status` as the recovery path. 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, composer, handoff, and compare-and-swap fences privately. Never ask the user or model to copy draft text, a composer digest, 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 approval prompt; Composer revalidation remains action-specific and is not Codex user-explicit Send authority.
+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 v28 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. Codex `terminal_user_explicit` depends on the exact live terminal/process, a scanned non-blocked approval state, and no active input-owning questionnaire/editor—not ordinary main-Composer visibility, stability, exactness, parsed working activity, or AKK Store, Turn, Session, transfer, transition, ledger, or ownership. Codex 0.154's exact collapsed async-question summary leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. It applies `replace_current_composer_and_submit`: physical fallback sends `C-u` once to replace the current Composer, injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. Claude Code remains exact-empty-only. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after user-explicit Codex text injection, that path follows the same no-Composer-veto Enter rule. A source-less Codex terminal with zero, one, or many pre-existing rollout roots freezes that full candidate set before input and binds only the unique rollout that later persists the exact request hash; a unique stale root is never assumed to be foreground. If managed preparation still fails before input, AKK sends once without a managed callback Turn, then best-effort attaches an exact request-bound Terminal Watch callback and releases stale management. Watch failure is a warning and never revokes or retries a successful Send. Native inspection and native lifecycle input remain exact-empty-only. 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. Once the Codex mutation sequence begins, an uncertain result must not be automatically retried. Read Send results as orthogonal facts: `terminal_input_dispatched`, `agent_acceptance`, `management_mode`, `observation_mode`, and `capabilities` distinguish physical dispatch from durable native acceptance and callback/interaction authority; do not infer one from another. If the result returns `observation_mode="terminal_watch"`, wait for that callback and retain `watch-status` as the recovery path. 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, composer, handoff, and compare-and-swap fences privately. Never ask the user or model to copy draft text, a composer digest, 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 approval prompt; Composer revalidation remains action-specific and is not Codex user-explicit Send authority.
 
 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.
 
@@ -84,7 +87,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`. 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 v25 `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.
+4. Read the selected resource's `available_actions`. In the compact Host projection its keys are the exact current action names and each value is `true`; `action_inputs`, when present, carries only dynamic semantic arguments, `missing_required`, and scope. For every mutation, use only an advertised action, start with those semantic inputs, supply every `missing_required` field, and follow this skill's action rules. 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. For source-less Codex sends, zero exact acceptors remains pending for monitor recovery, one promotes the provisional Session/Turn, and multiple acceptors or identity drift becomes uncertain without replay. 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.
 
@@ -108,12 +111,24 @@ Hard creation failure is limited to an absent exact terminal, inability to ident
 
 Approval attention is notification-only for every Watch: never call an approval tool for a `watch_id`, send approval keys, or apply `autoApprove`. Questionnaire attention is different. An automatic exact request-bound Watch created by `terminal_user_explicit` unmanaged fallback can, after exact request acceptance and attribution, emit `interaction_required`; call Status with its exact `watch_id`, show the projected question to the user, and use `respond_interaction({watch_id,...})` only when that fresh owner-bound projection advertises `capabilities.respond=true`. A terminal-activity Watch or `interaction_manual_required` callback remains notify-only: tell the user to inspect and answer in the live TUI, and send no questionnaire input. Each new exact attention 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 19 OpenClaw tools and list action-contract v25. 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 22 semantic AKK tools and list action-contract v28. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v1 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 native model control, first call `agent_knock_knock_model_options({terminal_id})` only from the current terminal row's advertised action. This is explicit current-snapshot authority for one exact physical pane/process: Codex 0.154 may use either one exact current native Session or a verified-zero-rollout pane, where `identify_foreground` is diagnostic rather than a prerequisite; Claude Code still requires one exact current native Session. The pane must have no active Turn, approval, questionnaire/editor, or read-only viewer. It normally requires an idle empty Composer; when List advertises `model_options` for one exact stable Codex 0.154 `/model` residual, AKK may continue only that residual into read-only catalog discovery. Show the returned `scope`, current selection, and semantic model/effort catalog to the user. Then call `agent_knock_knock_set_model({terminal_id,model,reasoning_effort})` with an exact required tuple from that same result in the same controller conversation. Codex scope is always `current_and_new_sessions`: a successful selection persists the model and an ordinary effort (including `max`) for future sessions, but `ultra` is current-session-only and Codex chooses a non-Ultra future fallback. Always read `effective` and `new_session_defaults` separately. Claude Code scope is always `current_session`. There is no caller-selectable scope. Never pass a display label, menu index, slash command, raw key, token, or fingerprint. A stale or consumed catalog must be refreshed, and `outcome="uncertain"` must never be retried automatically.
+
+If the current List also advertises `repair_model_control`, it is the explicit
+cleanup-only alternative: call
+`agent_knock_knock_repair_model_control({terminal_id})` or the matching
+`/akk repair-model-control <exact-terminal-id>` only when the user wants the
+residual cleared instead of continuing discovery. For an already-open exact
+native picker this is the only model-control action List may advertise: it may
+dismiss the picker but has no Enter authority. It accepts no raw text or keys,
+never presses Enter, and must prove an empty Composer. Refresh List after
+success; never retry an uncertain repair automatically.
 
 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/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267 `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/0.151.0/0.153.0/0.153.4/0.154.0 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267 `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 inspection tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, raw `/model`, `/compact`, and arbitrary slash commands remain unavailable; model changes use only the typed model-control tools above. 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.
@@ -135,6 +150,8 @@ Useful examples:
 /akk @a1b2c3d4: run the focused tests
 /akk list
 /akk threads terminal:v2:tmux:codex:akk-work:0.0:1234
+/akk models terminal:v2:tmux:codex:akk-work:0.0:1234
+/akk set-model terminal:v2:tmux:codex:akk-work:0.0:1234 gpt-6-astra ultra
 /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
@@ -146,7 +163,7 @@ Useful examples:
 
 ## Terminal Communication Contract
 
-All OpenClaw-to-agent task delivery must go through Agent Knock Knock plugin tools. Do not use OpenClaw internal session tools, raw terminal-provider commands, shell commands, or another messaging path to bypass AKK's terminal checks.
+All controller-to-agent task delivery must go through Agent Knock Knock plugin tools. Do not use Host-internal session tools, raw terminal-provider commands, shell commands, or another messaging path to bypass AKK's terminal checks.
 
 AKK:
 
@@ -154,11 +171,11 @@ AKK:
 2. Revalidates the expected agent PID and provider-owned terminal identity, confirms that the process and pane working directories match, and verifies the idle prompt.
 3. Types only the user-facing task into the shared terminal.
 4. Creates a unique managed `turn_id` bound to the AKK `session_id`, terminal incarnation, and message.
-5. Monitors reliable local evidence and sends callbacks to the originating OpenClaw session.
+5. Monitors reliable local evidence and sends callbacks to the originating controller session.
 
 The coding agent does not run an AKK callback command and does not require an AKK-specific hook or plugin.
 
-After an asynchronous send operation is accepted, end the OpenClaw turn. Wait for AKK's callback unless the user explicitly requests status.
+After an asynchronous send operation is accepted, end the controller turn. Wait for AKK's callback unless the user explicitly requests status.
 
 ## Status
 
@@ -203,7 +220,33 @@ 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. Read `screen_state` as bounded live-TUI evidence, `native_identity_state` as foreground native-session resolution, and `durable_activity_state` as exact artifact-backed task activity. The legacy `activity_state` is a conservative compatibility projection and may remain `unknown` while `screen_state="idle"`; none of these diagnostic fields replaces `available_actions` authority. `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 v25 `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. A native questionnaire response instead requires the current `interaction_state` returned by Status in the same controller conversation. Approval, questionnaire response, handoff takeover, and `reconcile_binding` require explicit user intent and fresh source state. Model-facing shapes are: `watch({terminal_id})`; `send({session_id|terminal_id,request})`, with the targets mutually exclusive; `identify_foreground({terminal_id})`; `identify_and_send({terminal_id,request})`; `respond_interaction({turn_id|watch_id,interaction_id,answers})`, with exactly one subject id and only projected question/option ids; managed `approve({turn_id,decision})` or approve-once-only 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, interaction-fingerprint, 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 is 7; Terminal Watch schema remains 3.
+### Compact controller-Host List projection
+
+The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=1`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, explanatory `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. 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.
+
+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 terminal `id` is 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.
+
+Action-name glossary:
+
+- `status`: inspect one terminal, Turn, or Watch; it sends no native slash command.
+- `send`: deliver a new request, or perform the separately advertised immutable `retry_submission` form.
+- `watch` / `unwatch`: start or stop durable read-only terminal observation.
+- `list_resumable_threads`, `new_thread`, and `resume_thread`: inspect or change native thread context through their closed lifecycle protocols.
+- `native_inspect`: run only an advertised closed native inspection such as `status`.
+- `model_options`, `repair_model_control`, and `set_model`: discover the current native catalog, clear only a proven model-control residue, or consume one catalog offer.
+- `identify_foreground` / `identify_and_send`: diagnose Codex foreground identity, or keep that diagnosis and one Send atomic.
+- `reconcile_binding`: detach only the exact listed stale/conflicting AKK binding after explicit user confirmation.
+- `respond`: answer ordinary text inside the current managed Turn.
+- `respond_interaction`: answer one current native questionnaire step obtained from fresh Status.
+- `approve`: apply only an explicitly confirmed advertised semantic approval decision.
+- `cancel`: interrupt the selected active Turn without closing the terminal.
+- `renew`: extend monitoring for an eligible stalled Turn without terminal input.
+- `retry_callback`: retry delivery of an eligible failed callback without terminal input.
+- `close`: release AKK management for the selected Turn without stopping the coding agent or closing the pane.
+
+The tool name is normally `agent_knock_knock_<action-name>`. The sole List alias is `retry_submission`, which invokes `agent_knock_knock_send` with its listed `turn_id` only after explicit confirmation. Nested `handoff_decision.choices.take_over_current.action` and `blocking_turns[].recovery_action` carry their explicit tool/action name and semantic arguments; the explanatory choice and recovery text is defined here rather than repeated in every List row.
+
+`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. A native questionnaire response instead requires the current `interaction_state` returned by Status in the same controller conversation. Approval, questionnaire response, handoff takeover, and `reconcile_binding` require explicit user intent and fresh source state. Model-facing shapes include `model_options({terminal_id})`, the separately advertised Codex-only `repair_model_control({terminal_id})`, and `set_model({terminal_id,model,reasoning_effort})`; `watch({terminal_id})`; `send({session_id|terminal_id,request})`, with the targets mutually exclusive; `identify_foreground({terminal_id})`; `identify_and_send({terminal_id,request})`; `respond_interaction({turn_id|watch_id,interaction_id,answers})`, with exactly one subject id and only projected question/option ids; managed `approve({turn_id,decision})` or approve-once-only 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, catalog, candidate, composer, handoff, approval, interaction-fingerprint, 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 is 7; Terminal Watch schema remains 3.
 
 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 and no proven input-owning native editor or read-only viewer. Ordinary main-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.