@scotthuang/agent-knock-knock 0.12.4 → 0.12.5

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

@@ -35,6 +35,8 @@ Core slash-command forms:
 
 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. A natural-language tool call may preserve a selector explicitly named by the user; otherwise use a list-prefilled action or omit the target and require a unique pane. Never pass a selector as `session_id` or `turn_id`. A send action with `session_id` is session-scoped and must remain pinned to that exact native context. A listed follow-current send is terminal-scoped: preserve its exact full terminal `selector` and fresh `expected_terminal_token` together so AKK can safely absorb a verified, quiescent human thread switch. Never add that token to `session_id`, infer it, copy it to another row, or reuse it after another terminal action. Native-thread slash commands are stricter: copy the full `terminal_id` returned by `/akk list`, not its `@short-ref`. The slash handler reads a fresh lifecycle snapshot and immediately supplies its compare-and-swap binding token internally; the human never copies that token. Plugin actions prefill the authoritative arguments for ordinary send and the exact `turn_id` for respond and managed controls. The same raw terminal row may advertise status, approval, cancellation, or orphan-close with its own prefilled `conversation_id` compatibility selector. Use only the exact returned action; never infer, copy, or reuse compatibility selectors. For every send, AKK must revalidate the selected agent PID and provider-owned terminal identity, confirm that the process and pane working directories match, and verify the idle prompt.
 
+v11 adds one narrow first-task path for Codex. When a row has only a status-card-only Session, exact local evidence proves a verified zero rollout, and `list` advertises a terminal-scoped ordinary `send`, copy that action's exact full `selector` and fresh `expected_terminal_token`. Under the terminal lock, AKK isolates the old Session, creates a separate zero-UUID provisional Session and Turn, sends only the real task, and binds the new Session from the fresh rollout produced after submission. The resulting native UUID may match or differ from the status card; it is never merged back into the old Session. Until that promotion commits, the provisional binding has no managed control or callback authority: strict `session_id` send, `respond`, `approve`, `cancel`, native lifecycle, and `native_inspect` remain unavailable and require the exact native UUID binding or pre-input status proof. If dispatch, acceptance, or post-submit binding is uncertain, do not retry automatically.
+
 AKK discovers eligible panes across workspaces. When more than one target matches, use a selector returned by `AKK list`; never guess based on a workspace name or path.
 
 Natural-language forms:
@@ -66,8 +68,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 authoritative arguments, supply every `missing_required` field, and consult the top-level v10 `action_contracts` for optional fields. 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, preserve the complete action unchanged, and refresh the list immediately afterward.
-5. For an existing managed Session, use `send` with its prefilled `session_id`; it creates a new Turn strictly in that Session's native context. If the selected row instead advertises a follow-current `send`, preserve its full terminal `selector` and `expected_terminal_token` exactly and add the text as `request`; this action may adopt a safe human-driven handoff before creating the Turn. Legacy first attach may use a discovery selector explicitly named by the user or the selected unmanaged raw-terminal row's prefilled `selector`. Never infer or reuse a selector or token. Use `respond` with its prefilled `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 authoritative arguments, supply every `missing_required` field, and consult the top-level v11 `action_contracts` for optional fields. 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, preserve the complete action unchanged, and refresh the list immediately afterward.
+5. For an existing managed Session, use `send` with its prefilled `session_id`; it creates a new Turn strictly in that Session's native context. If the selected row instead advertises a follow-current `send`, preserve its full terminal `selector` and `expected_terminal_token` exactly and add the text as `request`; this action may adopt a safe human-driven handoff or execute the advertised Codex status-card-only first-task path before creating the Turn. Legacy first attach may use a discovery selector explicitly named by the user or the selected unmanaged raw-terminal row's prefilled `selector`. Never infer or reuse a selector or token. Use `respond` with its prefilled `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.
@@ -79,8 +81,9 @@ For native status inspection:
 1. Use only a current `available_actions.native_inspect` entry. Its structured arguments are authoritative and complete; never construct or reuse them.
 2. Supported exact profiles are Codex 0.146.0/0.146.1/0.147.0 and Claude Code 2.1.218/2.1.226 `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 requires an idle empty composer, fresh binding token, exact PID/process/pane/cwd/version identity, and no conflicting Turn, transition, dispatch, approval, or owner.
-4. 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.
-5. Native inspection creates no AKK Session, Turn, receipt, monitor, callback, or response round.
+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 other strict operations that must know the UUID before terminal input. An otherwise eligible terminal-scoped ordinary first task does not run `/status` and does not 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.
+6. Native inspection creates no AKK Session, Turn, receipt, monitor, callback, or response round.
 
 For native-thread lifecycle discovery or mutation:
 
@@ -164,7 +167,7 @@ A trusted, default-disabled plugin `autoApprove` policy may independently approv
 
 `agent_knock_knock_list` is terminal-first: every eligible already-running Codex or Claude Code pane appears once in `terminals[]`, even when retained managed Turns reference it. The resource chain is terminal → verified native session → managed AKK `session_id` → Turns. `process_state` reports process liveness and `activity_state` reports the parsed screen state. `managed.current_turn` is the authoritative active Turn for that terminal; otherwise `managed.recent_turn` shows the newest retained context. 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` or retained unavailable history is needed. By default, `unavailable_managed_turns[]` contains attention-needed records whose terminal is unavailable.
 
-The top-level v10 `action_contracts` summarizes each tool's managed target and its narrow compatibility inputs; `available_actions` is the authoritative current-action source after listing except for the explicitly modeled nested handoff decision and `blocking_turns[].recovery_action`. Both require explicit user confirmation and a fresh list after success; the handoff decision is additionally snapshot-bound. An existing managed Session's strict `send` targets `session_id` and starts a new managed Turn without following a replacement context in the pane. An adoptable human handoff instead advertises `send` with the exact terminal `selector` and fresh `expected_terminal_token`; preserving both expresses terminal-scoped follow-current intent and allows adoption only inside that fenced send. Legacy first attach may still use a discovery selector explicitly named by the user or the exact selector prefilled by an unmanaged raw-terminal row; no selector may be passed as `session_id`. `respond` and every managed control target `turn_id`; `respond` is offered only for a Turn waiting on OpenClaw. The read-only `list_resumable_threads` action is advertised on the terminal row, requires only its full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows. The `new_thread` mutation is advertised on the terminal row and requires that terminal ID and token; each resumable candidate row advertises its own `resume_thread` mutation with the same snapshot token, its complete `native_thread_id`, and its opaque `candidate_token`. A conflict-only `reconcile_binding` action remains available as low-level recovery for one safely detachable exact binding; it preserves the listed Session revision, binding token, and terminal token, then CAS-detaches the old binding without adopting the live thread, sending terminal input, or creating a Turn. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request. Number, short ID, and snapshot handle fields are human-facing navigation only; never pass them to the exact resume tool. Lifecycle discovery and mutations never create a Turn. A raw terminal may be controlled only through the exact action that its own row advertises; prefilled compatibility selectors, lifecycle IDs, and tokens must never be inferred, copied from another row, or reused from another snapshot. Start with the prefilled full argument, supply all `missing_required` fields, and use a returned `@short-ref` only for human-facing ordinary-send selection. Availability is a snapshot, so AKK revalidates it before side effects.
+The top-level v11 `action_contracts` summarizes each tool's managed target and its narrow compatibility inputs; `available_actions` is the authoritative current-action source after listing except for the explicitly modeled nested handoff decision and `blocking_turns[].recovery_action`. Both require explicit user confirmation and a fresh list after success; the handoff decision is additionally snapshot-bound. An existing managed Session's strict `send` targets `session_id` and starts a new managed Turn without following a replacement context in the pane. An adoptable human handoff instead advertises `send` with the exact terminal `selector` and fresh `expected_terminal_token`; preserving both expresses terminal-scoped follow-current intent and allows adoption only inside that fenced send. Legacy first attach may still use a discovery selector explicitly named by the user or the exact selector prefilled by an unmanaged raw-terminal row; no selector may be passed as `session_id`. `respond` and every managed control target `turn_id`; `respond` is offered only for a Turn waiting on OpenClaw. The read-only `list_resumable_threads` action is advertised on the terminal row, requires only its full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows. The `new_thread` mutation is advertised on the terminal row and requires that terminal ID and token; each resumable candidate row advertises its own `resume_thread` mutation with the same snapshot token, its complete `native_thread_id`, and its opaque `candidate_token`. A conflict-only `reconcile_binding` action remains available as low-level recovery for one safely detachable exact binding; it preserves the listed Session revision, binding token, and terminal token, then CAS-detaches the old binding without adopting the live thread, sending terminal input, or creating a Turn. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request. Number, short ID, and snapshot handle fields are human-facing navigation only; never pass them to the exact resume tool. Lifecycle discovery and mutations never create a Turn. A raw terminal may be controlled only through the exact action that its own row advertises; prefilled compatibility selectors, lifecycle IDs, and tokens must never be inferred, copied from another row, or reused from another snapshot. Start with the prefilled full argument, supply all `missing_required` fields, and use a returned `@short-ref` only for human-facing ordinary-send selection. Availability is a snapshot, so AKK revalidates it before side effects.
 
 Before every terminal operation, AKK revalidates the expected agent PID and 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.