@scotthuang/agent-knock-knock 0.14.5 → 0.14.7

package/docs/codex-desktop-compatibility.md

@@ -18,16 +18,19 @@ version and build. It is not a minimum-version promise:
 | macOS Desktop application | Send to live owner / Status / Watch | Native approvals, answers, model/permission changes, cancellation | New conversation |
 | --- | --- | --- | --- |
 | `26.1002.52244` / `13536` | Existing verified adapter | Existing verified adapter | Not enabled |
-| `26.1007.30912` / `20156` | Send profile for the new-conversation workflow; read-only observation retains exact owner/turn checks | Not enabled: these operations have not been reverified on this build | Available in AKK 0.14.5; see the creation boundary below |
+| `26.1007.30912` / `20156` | Send profile for the new-conversation workflow; read-only observation retains exact owner/turn checks | AKK 0.14.7 adds command/file approvals: allow once or reject. Answers, model/permission changes, and cancellation remain unavailable | Available in AKK 0.14.5; see the creation boundary below |
 | Other builds | Compatible read-only observations may work; no native writes are advertised | Not enabled | Not enabled |
 
-The `20156` profile does not inherit the old build's native-control approval.
-List and Status keep pending question/approval content visible when it can be
-read reliably, but expose no executable Respond/Approve action and direct the
-user to Desktop. Watch attention notifications follow the same boundary.
+The `20156` profile does not inherit the old build's full native controls.
+AKK 0.14.6 exposes pending interactions but requires handling them in
+Desktop. AKK 0.14.7 adds an Approve action for recognized
+command/file requests, with explicit `approve_once` or `reject` decisions.
+Question replies and other unsupported controls still direct the user to
+Desktop. Watch attention notifications follow the same per-operation boundary.
 `desktop_scan.send_contract_verified` reports the Send profile;
+`approval_contract_verified` reports the per-build approval profile;
 `write_contract_verified` continues to mean the full native-control profile.
-The new profile and creation workflow are available starting in AKK 0.14.5.
+The Send profile and creation workflow are available starting in AKK 0.14.5.
 
 The original fully reviewed application is macOS Codex Desktop `26.1002.52244`, build `13536`,
 bundle ID `com.openai.codex`, installed as `/Applications/ChatGPT.app`. These
@@ -76,6 +79,40 @@ No Desktop operation types a slash command or uses terminal activity as exact
 completion evidence. Existing terminal capabilities remain separate and retain
 their previous checks.
 
+## Approval validation on build 20156
+
+The 2026-10-14 validation for AKK 0.14.7 uses macOS Desktop `26.1007.30912`,
+build `20156`, and one dedicated test conversation.
+
+Real semantic Send, Status and Approve calls passed four cases:
+
+- Command allowed once: the original item completed with exit code 0 and the
+  expected output marker.
+- Command rejected: the original item became `declined`; its target file was
+  never created.
+- File change allowed once: the original item completed and the dedicated file
+  contained exactly the expected text.
+- File change rejected: the original item became `declined`; its target file
+  was never created.
+
+All four responses reached `confirmed` with `exact_approval_item_advanced` and
+one dispatch attempt. Both conversation and exact Watch targets were exercised.
+Repeated consumed semantic approval actions were rejected without another
+dispatch. Approval-attention and completion callbacks were accepted once each by
+an isolated local receiver. The conversation finished idle, with no pending
+interaction and its original read-only/on-request settings unchanged.
+An IPC acknowledgement alone is not confirmation.
+
+Approval responses retain exact thread, turn, owner, and typed request identity
+checks. A repeated response uses its durable record; a possibly submitted
+response is observed without resending. The supported decisions do not grant
+persistent permission or change the conversation's permission mode. This run
+does not establish support for question replies, settings, cancellation, or
+external-channel notification delivery on this build. Network-form command
+approvals share the existing typed request path but were not separately
+live-tested; persistent approvals and permission-request approvals remain
+outside this operation's supported decisions.
+
 ## New-conversation boundary
 
 Use `agent_knock_knock_desktop_create` or the `desktop-create` CLI command; see
@@ -102,9 +139,10 @@ No external channel delivery or newer-build native controls were exercised.
 This route is intentionally separate from loading or replacing an existing
 conversation. A failed or uncertain create/load/send stage must preserve its
 record and exact identities; it must not silently create another conversation
-or replay a task. Native approvals and questions on build `20156` still need
-to be handled in Desktop. The broader native controls remain enabled only for
-build `13536`, where those effects were previously verified.
+or replay a task. AKK 0.14.7 supports the command/file approvals described
+above on build `20156`; question replies and the broader native controls remain
+unavailable there. Those remain
+enabled only for build `13536`, where their effects were previously verified.
 
 ## Find and select a conversation
 

package/docs/desktop-create.md

@@ -119,9 +119,11 @@ joining unrelated work.
 
 The 0.14.5 profile enables new-conversation creation and Desktop Send on
 macOS Desktop `26.1007.30912`, build `20156`. It preserves exact owner and task
-checks for Status/Watch. Native approvals, question replies, permission/model
-changes, and cancellation have not been reverified on this build and remain
-unavailable: handle those actions in Desktop.
+checks for Status/Watch. AKK 0.14.7 adds command/file approvals with explicit
+allow-once or reject decisions. Question replies,
+permission/model changes, and cancellation remain unavailable on this build;
+handle those actions in Desktop. Approval does not change the permissions
+inherited when the conversation was created.
 
 The existing full native-control profile for Desktop `26.1002.52244`, build
 `13536`, is unchanged; it does not enable this new creation workflow. These are

package/docs/operator-guide.md

@@ -53,13 +53,19 @@ Direct slash commands are available in every first-party Host integration:
 | `/akk respond <turn-id> <answer>` | Answer a question inside the same managed Turn. |
 | `/akk cancel <turn-id>` | Interrupt one exact active managed Turn. |
 
-AKK List presents one `conversations[]` collection. It merges terminal/backend
-rows only when their exact current native identities match. A matching project
-or title does not establish that link. Select a conversation and action; AKK
-chooses the supported transport. Bound task and interaction IDs retain their
-original provider, and an uncertain mutation is never retried through another
-transport. The [CLI backend guide](codex-cli-native-compatibility.md#automatic-conversation-routing-2026-10-10)
-describes backend preference and terminal fallback in detail.
+AKK List presents **CLI** and **Desktop** in one `conversations[]` collection,
+with Codex/Claude Code as the agent type. Choose the displayed conversation and
+action; AKK selects the connection. The default view groups a one-to-one
+same-agent/project terminal and direct candidate without changing the terminal's
+identity, status, actions or dispatch checks. Multiple candidates and known
+identity conflicts stay separate; direct-only CLI conversations remain visible.
+Use `terminalDebug: true` or `list --terminal-debug` for all unassociated
+connections and routing details. A display group is not proof that its candidates
+are the same native session, and neither rows nor Watches are a task count.
+Bound task and interaction IDs retain their original provider; uncertain input
+is never retried through another transport. The
+[CLI backend guide](codex-cli-native-compatibility.md#automatic-conversation-routing-2026-10-10)
+describes routing evidence and presentation boundaries.
 
 The terminal-specific commands in the table require a physical terminal;
 Desktop interaction, model, permission, and cancellation controls use their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.14.5",
+  "version": "0.14.7",
   "description": "Delegate to existing Codex CLI, Codex Desktop, and Claude Code sessions from OpenClaw or compatible controller Hosts, with native direct control and supported terminal fallbacks.",
   "license": "MIT",
   "type": "module",

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

@@ -19,9 +19,11 @@ Keep the user's requested scope and approval boundaries. Do not expand a task, a
 
 ## Choose a conversation
 
-Use `conversations[]` from List as the primary collection and select by title, project and current identity. Choose the row's exact conversation and advertised operation; AKK chooses the route, including Status, Send, Watch and permission controls. Callers do not select between a backend and a terminal. For a proven terminal/backend match, `terminal_controls[]` preserves that terminal’s managed Turns, recovery and capability-specific actions inside the conversation row; these are controls for the same conversation, not extra tasks. The raw CLI retains `terminals[]`, `codex_cli_sessions[]`, `claude_cli_sessions[]` and `desktop_sessions[]` for compatibility and private authority, but do not present these again as extra conversations when `conversations[]` exists.
+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.
 
-AKK prefers a reachable direct connection only when it proves the exact current native session and process or thread. A terminal and backend row merge only with exact identity evidence, never matching cwd, title, newest history or version alone. Unresolved representations may remain separate; do not assume they are different tasks or send twice. The routing diagnostics describe available evidence, not authority to skip a guard. An unavailable backend may retain an eligible terminal path; a busy, blocked or mismatched native task is not an excuse to try terminal input. For a selected physical terminal without a proven native anchor, targeted conversation operations, including Status, may run an advertised idle-only `/status` identity inspection when backend candidates exist. This can display a native status card but submits no user task; a working or blocked terminal is not interrupted. List sends no terminal input. If a dispatch is uncertain, keep its receipt and inspect it instead of retrying another route.
+Default CLI presentation folds one same-agent, same-project terminal/backend candidate pair into the original terminal row. This is display grouping only: the candidate contributes no identity, status or permissions, and does not authorize backend dispatch. Known conflicts or multiple candidates remain separate. Backend-only CLI conversations remain discoverable. If a particular connection is missing or ambiguous, use `terminalDebug: true` (CLI `list --terminal-debug`) to expand every unassociated connection and routing detail. A same-project embedded CLI and an independent direct CLI can share a default display row when their identities are unknown; the expanded view preserves both. Display entry counts are not proof of unique native tasks.
+
+AKK prefers a reachable direct connection only after proving the exact selected native session and process or thread. An unavailable backend may retain an eligible terminal path; busy/blocked state or identity conflict cannot authorize bypass. Targeted operations on an idle terminal can use the existing advertised `/status` inspection to learn its identity; working or blocked terminals are not interrupted. List itself sends no terminal input. Keep an uncertain dispatch receipt and inspect it instead of retrying through another connection.
 
 Use the returned `watch_id` or `turn_id` for that task's follow-up. Existing Watches and pending interactions keep their task and route. After a question or approval callback, refresh that exact Status and copy the current interaction action; do not translate its IDs to another transport. Permission operations prefer the verified backend. Backend task recovery retains the original task identity and provider. Terminal binding/menu recovery, model and lifecycle operations retain their separately advertised capability; the caller does not pick a transport. The route-specific guidance below explains those capabilities and result boundaries, not an additional route-selection step.
 
@@ -39,7 +41,7 @@ Callbacks already in flight cannot be recalled by Close or Unwatch. `accepted` p
 
 ## Direct Codex CLI
 
-A `conversations[]` row with `source="codex_cli"` uses an exact `codex-cli:v1:...` conversation ID. This route addresses the existing loaded backend thread and works without tmux or Herdr. It never starts a replacement CLI or treats saved history as a live owner. Embedded CLI sessions without a reachable shared backend continue to use the terminal route. Desktop uses its separate route below.
+A direct Codex CLI conversation uses an exact `codex-cli:v1:...` conversation ID. This route addresses the existing loaded backend thread and works without tmux or Herdr. It never starts a replacement CLI or treats saved history as a live owner. Embedded CLI sessions without a reachable shared backend continue to use the terminal route. Desktop uses its separate route below.
 
 - Select by the returned title, working directory and native thread identity. Copy the advertised action; do not construct IDs, infer thread ownership from the newest same-directory history, or substitute another target. Unresolved physical terminal and direct thread rows can refer to the same work; select one conversation and send once.
 - Send with `agent_knock_knock_send({conversation_id,request})`. AKK preserves current settings, submits once and returns `codex-cli-watch:...` for the accepted native task. Keep the receipt if acceptance is uncertain; refresh its Status instead of blindly sending again.
@@ -51,7 +53,7 @@ Use AKK's advertised actions and read the actual operation result after backend
 
 ## Direct Claude Code
 
-Rows with `source="claude_cli"` use `claude-cli:v1:...` IDs for an already-running native CLI. This path is live-tested on macOS with Claude Code `2.1.296` and peer protocol `1`; Python 3 is required on the AKK side. It needs no Claude plugin, hook, special launch arguments or replacement process. Use actual advertised capabilities after upgrades, not a version number alone.
+Direct Claude Code conversations use `claude-cli:v1:...` IDs for an already-running native CLI. This path is live-tested on macOS with Claude Code `2.1.296` and peer protocol `1`; Python 3 is required on the AKK side. It needs no Claude plugin, hook, special launch arguments or replacement process. Use actual advertised capabilities after upgrades, not a version number alone.
 
 - Send to a verified idle conversation. Keep its `claude-cli-watch:...` receipt: Send already creates completion monitoring with the shared 720-minute hard deadline. Do not add another Watch for that Send. Busy/blocked, held/refused or uncertain delivery must not be retried through terminal input.
 - Status on the conversation reads its latest input; Status on the Watch reads its original exact `native_input_id`. This is an input UUID, not a native turn ID. Public progress and tool-action summaries are bounded to 800 code points; List has no progress body. `agent_acceptance: proven` requires exact native sender/message/input evidence, not merely a socket write.
@@ -61,7 +63,7 @@ Rows with `source="claude_cli"` use `claude-cli:v1:...` IDs for an already-runni
 
 ## Codex Desktop
 
-Desktop rows in `conversations[]` have `source="codex_desktop"` and a full `desktop:v1:...` conversation ID. Their owner identity is separate from terminal selectors, managed Sessions, and managed Turns. The terminal-specific instructions below do not grant Desktop input authority.
+Desktop rows in `conversations[]` have `surface="desktop"` and a full `desktop:v1:...` conversation ID. Their owner identity is separate from terminal selectors, managed Sessions, and managed Turns. The terminal-specific instructions below do not grant Desktop input authority.
 
 - List defaults to `desktop_view: "sidebar"`: persisted expanded sidebar membership, including eligible pinned threads and expanded project members. This is not a live screen or scroll-viewport snapshot. Present all returned rows, including unconnected conversations, and distinguish them from rows that can receive tasks. Report `desktop_scan` limitations when the saved layout cannot be reconstructed; do not silently substitute the historical catalog.
 - Find the intended row by title and project. Use `desktopSearch`, `desktopProject`, `desktopLimit`, and returned pagination cursor as `desktopCursor` within the same view. Use `desktop_view: "history"` explicitly to search the broader saved catalog for an older or hidden conversation. Do not assume the first page is complete or treat `live_count` as a count across unreturned pages. If several rows match, show their titles and project paths; do not invent IDs or ask for a deep link when List can discover the target.
@@ -75,7 +77,7 @@ Desktop rows in `conversations[]` have `source="codex_desktop"` and a full `desk
 - `model_options({conversation_id})` reads the current model, reasoning effort, and Plan/default mode. Desktop does not expose a model catalog (`catalog_available=false`). Use `set_model({conversation_id,model,reasoning_effort,collaboration_mode?})` only with an explicitly requested model ID; optional `collaboration_mode` is `plan` or `default`. Omitting it preserves the existing mode. Effective settings do not prove a model is available to the account. An unconfirmed update must be inspected, not blindly replayed.
 - Cancel with `cancel({watch_id})` for the exact watched task, or `cancel({conversation_id,expected_native_turn_id})` using the native task ID advertised by fresh Status. A late cancel must never interrupt a newer task. `unwatch` only stops observation. Arbitrary cold loading/resume remains unsupported; explicit creation uses the separate tool below.
 
-Full Desktop control is reviewed for macOS Codex Desktop `26.1002.52244` build `13536` through private local IPC. The AKK 0.14.5 profile for `26.1007.30912` build `20156` enables creation and Send/Status/Watch, but approvals, answers, permission/model changes and cancellation remain unavailable; use Desktop for those actions. The interaction instructions above apply only when the current result advertises that action. Read the actual capability and error result after an app update; never downgrade to raw UI input or relax identity checks. The native protocol has no atomic idle-and-send operation, so concurrent human input can make acceptance uncertain. Preserve the returned Watch and reconcile it instead of repeating the task.
+Full Desktop control is reviewed for macOS Codex Desktop `26.1002.52244` build `13536` through private local IPC. The profile for `26.1007.30912` build `20156` supports creation and Send/Status/Watch; AKK 0.14.7 also supports command/file approvals with `approve_once` or `reject`. Answers, permission/model changes and cancellation remain unavailable on that build; handle them in Desktop. Use only the currently advertised action: approval support does not imply support for other interaction responses. Read the actual capability and error result after an app update; never downgrade to raw UI input or relax identity checks. The native protocol has no atomic idle-and-send operation, so concurrent human input can make acceptance uncertain. Preserve the returned Watch and reconcile it instead of repeating the task.
 
 ### Create a Desktop conversation