@scotthuang/agent-knock-knock 0.14.2 → 0.14.4

package/docs/claude-cli-direct.md

@@ -0,0 +1,60 @@
+# Claude Code direct control
+
+AKK **0.14.3** adds basic control of an already-open Claude Code CLI without tmux or Herdr. No Claude plugin, hook, special launch argument, replacement agent, or restart is required.
+
+The initial live-tested combination is **Claude Code `2.1.296` on macOS**, using native peer protocol `1`. This is a tested version, not a claimed minimum or a promise that every newer version works. Discovery checks the running CLI's registry, native session UUID, PID/start time, and socket identity. A compatible runtime contract is required; unknown identity or protocol is not guessed.
+
+AKK uses a small **Python 3 helper on the controller side** to verify macOS Unix-socket peer credentials. Python 3 must be available to AKK. This is not installed into Claude Code and does not change its login, proxy, permissions, or settings. Other operating systems do not yet have this direct adapter; existing supported terminal routes remain available.
+
+## What works
+
+| Capability | Direct connection |
+| --- | --- |
+| Discover and select an existing CLI | Exact native session and process identity; separate sessions in the same directory remain separate |
+| Send a task | Allowed when the selected CLI is verified idle; Send creates its own durable Watch |
+| Status | Native activity plus bounded public text and tool-action summaries from the exact input's local transcript |
+| Watch an existing task | Requires a verified, currently active root input; no prompt insertion |
+| Completion and exit observation | Parent-chain and tool-result evidence; an idle state alone is not success |
+| Recovery | Inspect/reconcile an existing Watch, explicitly renew it, stop observation, close Send management, and retry a known retryable callback |
+| Approvals and blocking questions | Registry waiting hints only; no direct approval or answer submission, and no promise of comprehensive interaction notifications |
+| Models, permissions, cancellation, new/clear/resume | Unavailable through this direct connection |
+
+For an unsupported operation, return to the original Claude Code terminal. If that same session also has an eligible tmux/Herdr connection, AKK can route an already-supported special operation through its terminal adapter. This does not add terminal capabilities for unreviewed versions or unsupported dialogs. Core operations still prefer the direct connection.
+
+The terminal and direct paths must agree on the native UUID, PID and process start; matching a directory or a title is insufficient. Busy, blocked, refused, or uncertain sends do not trigger a second send through a terminal.
+
+## Use it
+
+Keep the authenticated Claude Code CLI open and ask your controller to refresh `agent_knock_knock_list`. Select its exact conversation ID from the returned actions. A task request can be as simple as:
+
+> Use AKK to ask Claude Code in my-project to inspect the failing tests. Tell me when it finishes.
+
+Save the `watch_id` returned by Send. It already identifies the completion monitor; do not add another Watch for that task. Use Status on the conversation for its latest input, or on the Watch for its exact saved input. For a task started manually in the CLI, explicitly ask the controller to Watch it.
+
+The usual `CLAUDE_CONFIG_DIR` is respected. AKK does not modify Claude's inbound-message policy: if the session holds or refuses peer messages, the result remains held/refused rather than being bypassed with terminal input. Busy Send is rejected because Claude can absorb an inbound message into the task already running.
+
+## Read the result correctly
+
+- `delivered` and `agent_acceptance: proven` require the submitted input UUID, peer message ID and actual sender PID in the native transcript. A successful socket write alone does not prove acceptance.
+- `native_thread_id` is the Claude session UUID. `native_input_id` identifies a user input, with `task_anchor_kind: native_input_uuid`; it is not a fabricated native turn ID.
+- `completed`, `interrupted`, `failed`, and `exited` are different outcomes. Completion means the exact native task finished, not that its requested objective or every tool call succeeded. If the original process exits, a later process resuming the same history is not substituted.
+- A registry permission/input wait can be shown as a manual-action hint. Requests have not been exhaustively scanned: `pending_interaction_count: null` means unknown, not zero.
+- `callback_expected` describes pending/future controller delivery. It normally becomes false after the completed callback has been accepted. Controller acceptance does not prove delivery to a downstream chat channel.
+
+Status limits its public progress body to **800 Unicode code points**, after redaction and at complete grapheme boundaries. It excludes hidden reasoning, raw long tool output, full arguments and diffs. The final public result is also bounded and reports truncation. `read_at` is the read time; `latest_item_at` comes from a native record or is null. List does not include progress or final-result bodies.
+
+Reads are bounded to the most recent 16 MiB of the exact session transcript. A missing old anchor, conflicting parent chain, replaced transcript, unsupported asynchronous/background work, or unavailable native record produces an explicit unknown/read error. AKK does not borrow a later task's result or treat idle as completion. Resumed histories can contain old record replays; only the selected input's proven causal chain is used.
+
+## Monitoring and recovery
+
+Send and explicit Watch share the **720-minute default hard deadline**, with a two-second observation interval. The deadline is separate from a terminal-managed task's 60-minute inactivity window. Expiration stops that observation; it does not cancel Claude's task or silently create another Watch.
+
+Use an explicit renewal on the existing Watch only when the same native input is still active. A completed, failed, interrupted, or exited task cannot renew. `recover` reconciles saved state; it neither resends the prompt nor extends the deadline. `close` ends AKK's management of a Send, while `unwatch` stops observation. Neither cancels Claude. Callback retry is restricted to a known retryable delivery failure; accepted or uncertain notifications are not blindly replayed. See [Backend Recovery](backend-task-recovery.md) for the shared concepts.
+
+AKK persists the exact acceptance anchor, monitor deadline and callback outbox. It polls the native records instead of relying on Claude's session-level idle notification, whose subscriptions can replace one another and which does not identify an independently completed task.
+
+## Protocol and verification boundary
+
+This adapter uses Claude's local agent registry, Unix-domain inbox and native transcript. The complete peer wire format and transcript schema are version-sensitive implementation details, not a guarantee of a permanently stable public API. AKK checks the contract and fails closed on unverifiable identities and task outcomes; it does not attach to a new SDK/headless process and call that control of the original CLI.
+
+The isolated research and implementation checks cover native discovery, exact sender/input acceptance, public result observation, same-directory separation, rejected busy sends and uncertain outcomes. Synthetic regressions additionally cover transcript replay/compaction history, identity conflicts, late receipt races, task isolation, callback deduplication and recovery. Broader operating-system support and all native interaction/control APIs remain outside this first direct adapter.

package/docs/codex-0.162.1-compatibility.md

@@ -6,6 +6,10 @@ new numeric minimum or a promise that future Codex versions use the same UI.
 The [CLI direct-control guide](codex-cli-native-compatibility.md) describes the
 separate shared-backend route, which does not need tmux or Herdr.
 
+The empty-thread initialization change below ships in **AKK 0.14.4**. Its dedicated
+2026-10-12 verification is recorded separately from the earlier 0.14.2 release
+matrix.
+
 ## Native status and error contract
 
 Codex changed the `/status` informational usage link from
@@ -92,10 +96,10 @@ envelope, with no automatic duplicate response.
 
 The upstream resume path in both reviewed versions requires persisted history.
 A newly loaded, idle, empty thread may expose live metadata before any rollout
-exists. AKK preserves that verified identity as
-`history_state: "unmaterialized"`, but does not advertise Send or permission
-actions that require a native subscription. Status and native inspection can
-return the fresh idle metadata with
+exists. AKK 0.14.2 preserved that verified identity as
+`history_state: "unmaterialized"` but withheld Send and permission actions because
+its Send preflight required a history subscription. Status and native inspection
+can return the fresh idle metadata with
 `subscription_state: "unavailable_unmaterialized_history"` and
 `observation_error: "native_subscription_unmaterialized"`. Its
 `interaction_requests_scanned: false` and null pending-interaction count mean
@@ -103,6 +107,57 @@ requests were not scanned, rather than proving that no question or approval
 exists. This diagnostic fallback requires the exact missing-rollout condition
 and a fresh same-thread idle/empty read; it does not accept unrelated failures.
 
+### First task in an existing empty thread (AKK 0.14.4)
+
+The direct adapter now distinguishes submission from history subscription.
+An exact, loaded main CLI thread with paginated history, idle state, no turns
+and no pending interactions can accept its first task via `turn/start` on that
+same owner. A typed missing-history subscription error and a fresh empty-thread
+read permit this path; arbitrary subscription failures do not. It does not
+create, resume, fork or cold-load another conversation, and it does not change
+the thread's permissions. Permission and interaction controls remain unavailable
+until their native subscription is usable.
+
+AKK saves the submission identity before dispatch and verifies the returned
+turn against its persisted user input. A native ACK alone is reported as
+`submission_state: "acknowledged"` with `native_receipt_turn_id`, while the exact
+anchor and `agent_acceptance` remain unproven until history is verified. The
+existing Watch observes that same submission; an observation delay is not a
+reason to send again or add another Watch. Unknown acceptance never causes
+automatic redispatch or a terminal fallback. List's linked terminal Send/Watch
+offers now reflect the selected backend's capabilities without removing
+terminal-only model or recovery operations.
+
+Materialization happens when the first user input is recorded, not when its
+task completes. A user does not need to finish a manual first round to initialize
+an already loaded, eligible thread.
+
+Before submission, a failed preflight is persisted under the same message-ID
+lock as the send reservation. Concurrent calls reuse whichever outcome was
+reserved first; a late preflight failure cannot replace an accepted submission.
+The failed record reports `failure_stage: "native_preflight"`,
+`request_dispatched: false`, `delivery_receipt: "not_sent"` and no active
+observation or callback. It is an audit record, not a running native task;
+replaying that message ID never submits it later.
+
+Dedicated live verification on 2026-10-12 used macOS Codex CLI **0.162.1** and
+shared backend **0.162.1**, two new CLI sessions launched through the existing
+proxy wrapper, and an isolated AKK store with a local notification collector:
+
+| Case | Observed result |
+| --- | --- |
+| First task with no previous user input | Verified loaded idle thread, unmaterialized history and null latest turn before Send; the original thread accepted exactly one task, displayed its result in the original CLI and produced one local completion acknowledgement. |
+| First task immediately requesting command approval | The original empty thread accepted the task; AKK identified the exact approval, allowed the dedicated harmless `printf` command once, verified exit code 0 and its output, and produced one interaction notification plus one completion acknowledgement. |
+| Duplicate Send and observer reconnect | Both cases retained the same task ID and deadline, one native turn, and one completion notification after repeating the same message ID and reconnecting observation. |
+
+The PTYs only hosted the dedicated CLIs; tasks and approval responses used the
+native backend. No user work conversation, Gateway or real messaging channel
+was used. Both test CLIs were stopped afterward. The live cases exercised the
+built native runtime, task service and local outbox; terminal-alias routing and
+public tool projections are covered by fast regressions. Lost ACKs, delayed
+history, concurrent preflight failures and pending-request replay also have
+isolated regression coverage; no live fault-injection claim is made.
+
 ## Version and route boundaries
 
 | Route | Compatibility rule |
@@ -129,7 +184,7 @@ evidence. The formal release gate also passed as recorded below.
 | Earlier 0.14.1 targeted live proof | macOS CLI 0.162.1 + shared app-server 0.162.1: bounded public progress during an active task, 720-minute Send monitoring, one local completion acknowledgement and idempotent Send. |
 | Dedicated frontend/backend pair | macOS CLI 0.162.1 + shared app-server 0.162.1, launched through the existing `mycodes --remote` wrapper in a dedicated test session. |
 | Native status, exact identity and List | Passed: the closed native `/status` transaction proved the exact thread and enabled alias coalescing; subsequent materialized-thread backend Status read the same target. |
-| Unmaterialized empty thread | Passed in a separate dedicated 0.162.1/0.162.1 CLI: List withheld Send/permission offers, Status/native inspection retained verified idle identity with unscanned requests and a null pending count, and an attempted semantic Send was rejected before a native turn, Watch or callback was created. The thread stayed empty and global configuration was unchanged. |
+| Unmaterialized empty thread, 0.14.2 behavior | Passed in a separate dedicated 0.162.1/0.162.1 CLI: List withheld Send/permission offers, Status/native inspection retained verified idle identity with unscanned requests and a null pending count, and an attempted semantic Send was rejected before a native turn, Watch or callback was created. This is historical rejection evidence, not verification of the AKK 0.14.4 first-task initialization path. |
 | Model discovery | Passed: the public model-options operation read seven native models and restored the composer. Model mutation was intentionally not exercised because the existing terminal setter persists defaults; its scope remains covered by source review and regressions. |
 | Backend permissions | Passed: Default, Full Access and Read Only round trips retained the selected native thread. This is backend permission evidence, not a terminal menu round-trip claim. |
 | Routed Send, Status, Watch and completion | Passed: Send through the terminal alias selected the native backend, proved acceptance and a 720-minute deadline; Status using the returned native conversation ID and Watch ID read the same active turn and bounded progress. The exact turn completed with one local callback acknowledgement; idempotent Send retained the original Watch and deadline. Reading the old Watch after later turns still returned its original task's progress without later-task text. |
@@ -174,11 +229,11 @@ monitoring state. Unwatch is not native cancellation or task completion.
 - Direct CLI model control and cancellation still require an eligible verified
   terminal capability. Native new/clear/resume remains unsupported for these
   paginated versions; adding a version profile does not enable lifecycle work.
-- A newly loaded CLI thread with no materialized history is not automatically
-  writable through the direct adapter: upstream `thread/resume` requires stored
-  history. Reading its live metadata is different from acquiring a task/response
-  channel. Such a thread must not be advertised as Send-ready solely because it
-  is loaded and idle.
+- The AKK 0.14.4 first-task path requires an exact loaded main CLI owner and
+  the strict empty-thread conditions above. A title, directory, unloaded history
+  or mere idle indicator is insufficient. Submission and subscription readiness
+  are separate; the initialization path does not enable unsupported lifecycle
+  operations or permission control before a verified subscription.
 - The Status public body remains bounded to 800 Unicode code points, with
   redaction, grapheme-safe truncation and exact-turn freshness/error reporting.
   List gains no progress body or pagination changes in this release.

package/docs/codex-cli-native-compatibility.md

@@ -57,6 +57,27 @@ For native Watch and response commands, use the exact returned Watch or
 interaction ID. Watch IDs can be UUIDs or deterministic submission hashes;
 they are opaque, not values to construct.
 
+### First task in a new, already open CLI thread (AKK 0.14.4)
+
+AKK 0.14.4 permits Send to an exactly identified, loaded,
+idle main CLI thread before its first task has created paginated history.
+AKK submits to that original thread, then connects its existing Send Watch as
+the task history becomes available. No manual first message or completed round
+is required. This is not support for creating or cold-loading a conversation.
+
+Approval and permission controls still require a usable native subscription;
+before then, Status keeps pending-interaction count unknown rather than claiming
+zero requests. A Send receipt with `submission_state: "acknowledged"` and
+`native_receipt_turn_id` means Codex returned a task receipt but AKK is still
+verifying the exact input in history. Follow the returned Watch, without resending
+the task or adding another Watch. Only verified history produces
+`agent_acceptance: "proven"`. Connection or identity errors do not authorize
+switching transports after a possibly submitted task.
+
+See the [0.162.1 report](codex-0.162.1-compatibility.md#first-task-in-an-existing-empty-thread-akk-0144)
+for the distinction between the earlier released rejection behavior and the
+0.14.4 first-task behavior.
+
 ## Automatic conversation routing (2026-10-10)
 
 For conversation operations, select the conversation and requested action,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.14.2",
-  "description": "Control Codex CLI through its shared backend, Codex Desktop through native IPC, and Codex or Claude Code through terminals from OpenClaw or compatible controller Hosts.",
+  "version": "0.14.4",
+  "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",
   "homepage": "https://github.com/scotthuang/agent-knock-knock#readme",

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

@@ -1,13 +1,13 @@
 ---
 name: agent-knock-knock
-description: Discover and control loaded Codex CLI threads, existing Codex Desktop conversations, or Codex and Claude Code tmux/Herdr terminals with Agent Knock Knock.
+description: Use Agent Knock Knock to discover, send tasks to, and observe existing Codex CLI, Codex Desktop, or Claude Code conversations through their supported direct or terminal connections.
 ---
 
 # Agent Knock Knock
 
 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 conversation listed by AKK.
 
-AKK supports loaded local Codex CLI threads through their shared backend, existing local Codex Desktop conversations, and Codex or Claude Code already running inside tmux or local Herdr `0.8.0`. It never launches a replacement coding agent. The controller Host, AKK, the coding agent, and its Desktop app or terminal host must run as the same OS user.
+AKK supports loaded local Codex CLI threads through their shared backend, existing local Codex Desktop conversations, compatible already-open Claude Code CLIs through their native inbox, and Codex or Claude Code already running inside tmux or local Herdr `0.8.0`. It never launches a replacement coding agent. The controller Host, AKK, the coding agent, and its Desktop app or terminal host must run as the same OS user.
 
 Treat `AKK` and `akk` the same way.
 
@@ -19,9 +19,9 @@ 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[]` and `desktop_sessions[]` for compatibility and private authority, but do not present these again as extra conversations when `conversations[]` exists.
+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.
 
-AKK prefers the reachable Codex backend only when it proves the exact current native 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.
+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.
 
 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.
 
@@ -49,6 +49,16 @@ A `conversations[]` row with `source="codex_cli"` uses an exact `codex-cli:v1:..
 
 Use AKK's advertised actions and read the actual operation result after backend upgrades. A missing backend method fails that operation with an unsupported-capability diagnostic; it does not justify sending UI input to a guessed terminal. Existing terminal and Desktop capabilities retain their own limits. Model selection and native thread lifecycle operations are not added to this direct route.
 
+## 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.
+
+- 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.
+- Watch a manually started active task using the conversation action. Keep the returned Watch through task changes. Idle is not success; `exited` means the original process ended without proof of completion. A new process resuming the same history is not silently substituted.
+- Use the advertised Recover, Unwatch, Close and retry-callback actions on the original task. Explicit Renew requires that same input still active; settled or exited tasks cannot renew. Accepted or uncertain callbacks are not replayed. Callback acceptance proves delivery to the controller, not to a downstream chat channel.
+- Direct approvals, question answers, models, permissions, cancellation and lifecycle commands are unavailable. Registry waiting hints may indicate manual attention, but `pending_interaction_count: null` means unknown and interaction notification is not guaranteed. Report `manual_required` and return to the original Claude terminal. If an exact eligible tmux/Herdr counterpart exists, AKK retains its advertised special controls automatically; their original version and safety limits still apply.
+
 ## 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.