@scotthuang/agent-knock-knock 0.13.12 → 0.13.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.13.12",
+  "version": "0.13.13",
   "description": "Control local Codex and Claude Code from OpenClaw or compatible controller Hosts through shared terminals.",
   "license": "MIT",
   "type": "module",
@@ -87,7 +87,8 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "docs/codex-0.158.0-compatibility.md"
+    "docs/codex-0.158.0-compatibility.md",
+    "docs/codex-0.159.0-compatibility.md"
   ],
   "publishConfig": {
     "access": "public"

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

@@ -42,13 +42,13 @@ For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`,
 
 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.
 
-For an exact-empty idle Codex pane whose native identity is ambiguous, List may advertise `identify_foreground` and `identify_and_send`. `agent_knock_knock_identify_foreground({terminal_id})` is explicit and Codex-only: it mutates no Store record but does send `/status` and Enter exactly once to the visible pane. Its 30-second proof is diagnostic, never reusable authority; do not feed its UUID or expiry into another tool. `agent_knock_knock_identify_and_send({terminal_id,request})` keeps one terminal lock across the probe and task and is the only actionable consumer of that observation. It still binds a durable Session/Turn only from unique exact request acceptance. A changed or uncertain probe sends no task and must not be retried automatically. Never invoke either action unless the current terminal row advertises it. List and Status do not run `/status`. Ordinary Send must not be redirected through these explicit identification tools implicitly; Codex 0.158.0 uses its separate closed `/status` transaction for exact paginated Watch binding.
+For an exact-empty idle Codex pane whose native identity is ambiguous, List may advertise `identify_foreground` and `identify_and_send`. `agent_knock_knock_identify_foreground({terminal_id})` is explicit and Codex-only: it mutates no Store record but does send `/status` and Enter exactly once to the visible pane. Its 30-second proof is diagnostic, never reusable authority; do not feed its UUID or expiry into another tool. `agent_knock_knock_identify_and_send({terminal_id,request})` keeps one terminal lock across the probe and task and is the only actionable consumer of that observation. It still binds a durable Session/Turn only from unique exact request acceptance. A changed or uncertain probe sends no task and must not be retried automatically. Never invoke either action unless the current terminal row advertises it. List and Status do not run `/status`. Ordinary Send must not be redirected through these explicit identification tools implicitly; Codex 0.158.0/0.159.0 uses its separate closed `/status` transaction for exact paginated Watch binding.
 
 The private approval fence remains prompt-scoped. It binds the adapter-isolated exact unredacted approval region plus terminal/process identity, decision keys and label, prompt kind, working directory, reason/detail, and request or policy evidence. The whole-screen digest and redacted excerpt are diagnostic only: output outside the approval region may continue scrolling without invalidating the same reviewed prompt. After explicit user confirmation, the plugin/CLI retains a private confirmation offer and recaptures the region under lock. Any change inside the exact region—including a command or otherwise identically redacted secret—rejects and sends zero approval keys. Never expose, persist as public action data, log, infer, or reconstruct the raw prompt evidence or its opaque fingerprint.
 
 Coding-agent versions distinguish missing verification from known protocol incompatibility. A merely unverified complete Codex or Claude Code `x.y.z` version keeps otherwise eligible actions advertised; preserve and surface its compatibility warning, then let runtime structure and postcondition checks decide success. Never suppress an action solely because its exact version lacks a regression-tested AKK profile. Known incompatible protocols disable their affected actions before input. Codex 0.157.0/0.157.1 create new durable TUI sessions with paginated history and may use a shared background server; AKK cannot yet bind that history to an exact managed task. Managed completion callbacks, native thread lifecycle actions, and automated native status dispatch remain unavailable; visible status cards can still be parsed. Explicit terminal Send and warning-bearing `terminal_activity` Watch remain available subject to native UI safety checks; that Watch reports best-effort activity notifications without proving exact task completion or granting question-response authority. `--no-daemon` does not restore legacy JSONL history for new sessions. Use only currently advertised mutation actions, and if input may already have occurred and the result is unproven, report the uncertainty and never retry automatically.
 
-Codex 0.158.0 physical Send uses an exact paginated task Watch instead of a legacy managed Session/Turn. Before Send, AKK attempts a closed `/status` transaction in the available main Composer to bind the foreground thread. When an exact Watch attaches, retain its `watch_id` for Status, question responses, and completion callbacks; do not invent a `turn_id`. If binding or Watch attachment fails, report the receipt's callback limitation. This adapter does not establish managed session-only dispatch or native new/resume for paginated threads. Async responses offer only `steer_current_turn`, never `queue_next_turn`. A first Watch requested while a blocking modal already owns input cannot establish this binding and falls back to activity observation with manual question handling.
+Codex 0.158.0/0.159.0 physical Send uses an exact paginated task Watch instead of a legacy managed Session/Turn. Before Send, AKK attempts a closed `/status` transaction in the available main Composer to bind the foreground thread. When an exact Watch attaches, retain its `watch_id` for Status, question responses, and completion callbacks; do not invent a `turn_id`. If binding or Watch attachment fails, report the receipt's callback limitation. This adapter does not establish managed session-only dispatch or native new/resume for paginated threads. Async responses offer only `steer_current_turn`, never `queue_next_turn`. A first Watch requested while a blocking modal already owns input cannot establish this binding and falls back to activity observation with manual question handling.
 
 AKK discovers eligible panes across workspaces. When more than one target matches, choose one exact listed `terminal_id` for a structured tool or a listed selector for a human slash command; never guess based on a workspace name or path.
 
@@ -78,9 +78,9 @@ Natural-language forms:
 
 ## Sessions and Turns
 
-AKK's identity hierarchy is terminal → native Codex or Claude Code session → AKK session → Turns. `session_id` is the strict ordinary-send target for one exact native context. `terminal_id` is the deliberately different follow-current target that lets the user hand the pane's currently verified context back to AKK after a safe human-driven switch. Each accepted managed Send creates a distinct `turn_id` without clearing the native agent context; Codex 0.158.0 physical Send instead returns an independent task Watch when observation can be attached. A `turn_id` is used for history, callbacks, respond, status, approval, cancellation, renewal, callback retry, close, and the explicitly advertised submission-retry form of Send.
+AKK's identity hierarchy is terminal → native Codex or Claude Code session → AKK session → Turns. `session_id` is the strict ordinary-send target for one exact native context. `terminal_id` is the deliberately different follow-current target that lets the user hand the pane's currently verified context back to AKK after a safe human-driven switch. Each accepted managed Send creates a distinct `turn_id` without clearing the native agent context; Codex 0.158.0/0.159.0 physical Send instead returns an independent task Watch when observation can be attached. A `turn_id` is used for history, callbacks, respond, status, approval, cancellation, renewal, callback retry, close, and the explicitly advertised submission-retry form of Send.
 
-Use `agent_knock_knock_send` with `request` and neither `session_id` nor `terminal_id` only when the target is unspecified. AKK must resolve exactly one eligible Codex or Claude Code pane across all workspaces and use its currently advertised Send path. Managed delivery attaches or discovers its AKK session and verifies idle before input; Codex 0.158.0 physical Send does not require a managed Session and follows its terminal input-safety checks. If no eligible pane exists, report AKK's setup guidance; do not substitute another execution path.
+Use `agent_knock_knock_send` with `request` and neither `session_id` nor `terminal_id` only when the target is unspecified. AKK must resolve exactly one eligible Codex or Claude Code pane across all workspaces and use its currently advertised Send path. Managed delivery attaches or discovers its AKK session and verifies idle before input; Codex 0.158.0/0.159.0 physical Send does not require a managed Session and follows its terminal input-safety checks. If no eligible pane exists, report AKK's setup guidance; do not substitute another execution path.
 
 On first attach, the target terminal must be explicitly named by the user; never guess which already-running pane should receive the task.
 
@@ -99,11 +99,11 @@ Do not treat ordinary Send's whole-draft Composer replacement as a native conver
 
 ## Terminal Watch
 
-Terminal Watch follows the exact terminal selected by the user. Codex 0.158.0 exact Watch creation uses a closed `/status` transaction in an available main Composer to bind its foreground paginated task; subsequent observation is read-only. Answering a supported native interaction later is a separate explicit, owner-bound mutation. 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.
+Terminal Watch follows the exact terminal selected by the user. Codex 0.158.0/0.159.0 exact Watch creation uses a closed `/status` transaction in an available main Composer to bind its foreground paginated task; subsequent observation is read-only. Answering a supported native interaction later is a separate explicit, owner-bound mutation. 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.
 
-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 subsequent observation sends no input and does not adopt, replace, close, reserve, block, interrupt, approve, or otherwise mutate that Turn, Session, terminal, or task. Codex 0.158.0 exact Watch creation separately types the closed `/status` transaction described above. 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. Once exact request acceptance, terminal identity, owner, and one current supported native interaction are established, that Watch may emit an idempotent `interaction_required` callback. The callback itself is notification only; call `agent_knock_knock_status({watch_id})` in the owning controller conversation to obtain the single-use private response offer, and respond only when its projection says `capabilities.respond=true`. When exact response authority cannot be proven, AKK emits `interaction_manual_required` instead; that state and every terminal-activity Watch remain notify-only with `capabilities.interaction_respond=false`, so the human must answer in the live TUI.
+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 subsequent observation sends no input and does not adopt, replace, close, reserve, block, interrupt, approve, or otherwise mutate that Turn, Session, terminal, or task. Codex 0.158.0/0.159.0 exact Watch creation separately types the closed `/status` transaction described above. 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. Once exact request acceptance, terminal identity, owner, and one current supported native interaction are established, that Watch may emit an idempotent `interaction_required` callback. The callback itself is notification only; call `agent_knock_knock_status({watch_id})` in the owning controller conversation to obtain the single-use private response offer, and respond only when its projection says `capabilities.respond=true`. When exact response authority cannot be proven, AKK emits `interaction_manual_required` instead; that state and every terminal-activity Watch remain notify-only with `capabilities.interaction_respond=false`, so the human must answer in the live TUI.
 
-At creation, AKK first tries to build a privacy-safe exact provider task anchor. Codex 0.158.0 binds the exact foreground paginated thread and native task; older supported Codex versions bind 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"`. Legacy anchors invalidate on process, endpoint, native-thread, file identity, truncation/replacement, boundary, successor-task, or fingerprint drift. Codex 0.158.0 retains the original accepted native turn even when an unrelated later task starts; it never follows that later task or loses the original completion merely because a successor exists.
+At creation, AKK first tries to build a privacy-safe exact provider task anchor. Codex 0.158.0/0.159.0 binds the exact foreground paginated thread and native task; older supported Codex versions bind 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"`. Legacy anchors invalidate on process, endpoint, native-thread, file identity, truncation/replacement, boundary, successor-task, or fingerprint drift. Codex 0.158.0/0.159.0 retains the original accepted native turn even when an unrelated later task starts; it never follows that later task or loses the original completion merely because a successor exists.
 
 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.
 
@@ -130,9 +130,9 @@ 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/0.155.1/0.158.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.
+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/0.155.1/0.158.0/0.159.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. Legacy terminal-scoped ordinary tasks may send once and bind from exact native acceptance afterward without running `/status` or failing merely because the pane is narrow. Codex 0.158.0 attempts its separate closed `/status` binding before physical Send; if an exact callback Watch cannot be prepared, the Send receipt must state that limitation.
+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. Legacy terminal-scoped ordinary tasks may send once and bind from exact native acceptance afterward without running `/status` or failing merely because the pane is narrow. Codex 0.158.0/0.159.0 attempts its separate closed `/status` binding before physical Send; if an exact callback Watch cannot be prepared, the Send receipt must state that limitation.
 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.
 
@@ -232,7 +232,7 @@ 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`: create or stop durable terminal observation; Codex 0.158.0 exact creation performs the closed `/status` transaction, while subsequent observation is read-only.
+- `watch` / `unwatch`: create or stop durable terminal observation; Codex 0.158.0/0.159.0 exact creation performs the closed `/status` transaction, while subsequent observation is read-only.
 - `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.