@scotthuang/agent-knock-knock 0.14.17 → 0.16.0

package/docs/claude-cli-direct.md

@@ -1,12 +1,16 @@
-# Claude Code direct control
+# Claude Code 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.
+AKK controls an already-open Claude Code CLI through its native connection or an exact supported terminal. Standard `claude` and wrappers such as `tclaude` use the same adapter; `tclaude` is an executable/configuration choice, not a prerequisite. The default executable is `claude`, with the usual `~/.claude` configuration home unless configured otherwise. Native control needs no tmux/Herdr, Claude plugin, hook, special launch argument, replacement agent, or restart.
 
-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.
+Starting with AKK **0.15.0**, new Claude Code sends automatically prefer a **managed terminal Turn** when AKK verifies a unique controllable tmux/Herdr counterpart for the exact native session and process. The result supplies a `turn_id` for monitoring and supported approvals or question responses; the caller does not select a transport or enable background management. Without that exact terminal, AKK uses the native inbox and returns a `claude-cli-watch:...` receipt. Codex CLI continues to prefer its shared backend. Existing Turns, Watches and send receipts retain their original provider and are never migrated or resent to adopt this policy.
+
+Live observations include **Claude Code `2.1.295` and `2.1.296` on macOS**, using native peer protocol `1`. These are tested versions, not minimum versions or a promise that every UI variant works. An unlisted, complete `x.y.z` version can use the compatible runtime contracts; absence from the regression matrix alone does not disable an otherwise eligible operation. Discovery checks the running CLI's registry, native session UUID, PID/start time, and socket identity. Unknown identity, protocol or UI structure 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
+## Native connection capabilities
+
+This table describes the native fallback when no exact controllable terminal is available. A managed terminal Send uses the existing managed-Turn contracts described below.
 
 | Capability | Direct connection |
 | --- | --- |
@@ -14,14 +18,18 @@ AKK uses a small **Python 3 helper on the controller side** to verify macOS Unix
 | 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 |
+| Completion and exit observation | Parent-chain and tool-result evidence, including successful Stop hook summaries; an idle state or hook summary 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 |
+| Approvals and blocking questions | An exact native Watch sends deduplicated notifications for its task's registry waiting-state changes; hints are notify-only (`requires_response=false`, `actionable=false`), with no direct approval or answer submission |
 | 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.
+If that same session has exactly one eligible tmux/Herdr connection, new Sends use its managed path, and the conversation's public `capabilities` and `available_actions` also expose supported cancellation, native inspection, model and thread lifecycle operations. These fields follow the adapter's runtime evidence, state and action eligibility. AKK revalidates the exact terminal counterpart before execution. Conversation reads and standalone Watches may still use the native connection; task operations follow the original `turn_id` or `watch_id`. An unverified version can attempt a supported runtime contract, but unsupported dialogs require manual handling in the original terminal.
+
+Claude approval support follows the managed `turn_id` with fresh approval evidence. On an approval callback, refresh that Turn's Status and use its advertised approval action for the authorized decision. New managed terminal sends create this task ownership automatically. A native peer Send creates a native Watch, which cannot inherit managed approval authority; its waiting notifications remain notify-only. Current terminal-managed questionnaires can advertise `respond_interaction` through the associated conversation, with the original Turn target and a required fresh Status before answering. Unlisted complete Claude versions may use the existing questionnaire parser when the full question, choices and footer match its supported structure. The response remains bound to the actual version, original Turn, current prompt and single-use offer; unknown or malformed dialogs, secret questions and multi-select questions remain manual. This does not claim live questionnaire verification on every version. AKK's current Claude native peer adapter does not implement question responses, and neither Claude route implements permission-mode switching. `set_permissions` and `permission_options` are not enabled merely because the terminal adapter detects approval prompts. The sender permission declaration below is separate from changing the receiver's permission mode.
 
-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.
+The terminal and direct paths must agree on the native UUID, PID and process start; matching a directory or a title is insufficient. An exact terminal that is busy, blocked, has conflicting ownership or an unavailable Store returns that blocker; AKK does not bypass it through native delivery. Identity conflicts and refused or uncertain sends likewise do not authorize switching connections. A previously selected task route remains fixed even if another connection later becomes available.
+
+Claude terminal model control has regression profiles for `2.1.266` and `2.1.285`; other complete `x.y.z` versions may attempt the same runtime contract through a profile bound to their actual version. List's `model_control.reason` identifies that unverified profile. Catalog discovery must recognize the live picker, choices and session-scope footer before selection becomes available. Model changes still require an empty idle Composer, exact session/process identity, a fresh catalog and a verified postcondition, and affect only the current session. Missing or malformed versions and unsupported picker layouts remain unavailable. A supported new-thread transition also supports Clear; Resume requires an eligible exact UUID from a fresh resumable-thread catalog. Cancellation support follows the exact terminal adapter and transport, while each currently offered action remains subject to runtime state checks.
 
 ## Use it
 
@@ -29,15 +37,24 @@ Keep the authenticated Claude Code CLI open and ask your controller to refresh `
 
 > 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.
+Save the task identity returned by Send: `turn_id` for managed terminal delivery, or `watch_id` for native inbox delivery. Monitoring starts automatically; do not add another Watch for that task. Use Status with that exact task identity for follow-up, including managed approvals. Conversation Status reads the latest input and must not replace the original task identity. For a task started manually in the CLI, explicitly ask the controller to Watch it.
+
+The usual `CLAUDE_CONFIG_DIR` is respected. For native inbox delivery, 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. Native busy Send is rejected because Claude can absorb an inbound message into the task already running.
 
-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.
+### Sender permission class
 
-## Read the result correctly
+For native inbox delivery, set `AKK_NATIVE_CLAUDE_SENDER_PERMISSION_CLASS` in the **AKK/controller Host's launch environment**, with `bypass` or `prompting`. AKK declares that value in the native `<cross-session-message from-mode="…">` envelope and escapes the supplied task text. Callers pass the plain task request; they do not construct the envelope. Managed terminal sends do not use this envelope. The declaration does not change the target's permissions or bypass its hold/refuse policy.
+
+This value describes the sender/controller's actual permission policy, as explicitly configured by its operator. Within an authorized setup task, use that policy or verified evidence about the sender to select the class. The target's process flags and permission mode can help diagnose why it held a message, but cannot establish the sender's class. Do not copy the receiver's mode or infer `bypass` from a headless controller. If the sender's policy cannot be established, leave the declaration unset. AKK itself consumes only the explicit sender configuration.
+
+Setting the variable only in Claude/tclaude or another shell does not update an already-running controller Host. Unset or empty means no declaration; an invalid value rejects a new Send before submission. Receipts expose `sender_permission_class` and `sender_permission_class_source` (`operator_configured` or `unspecified`), which are configuration diagnostics, not proof of acceptance. Changing the variable does not alter or resend a previously held or uncertain message. Inspect its original Watch and return to the original terminal when manual review is required; do not replay it automatically.
+
+## Read native results 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 successful `stop_hook_summary` allows completion when the exact input's final message and durable completion record agree. Nonempty `hookErrors` or `preventedContinuation=true` remain unsafe, leaving completion unproven. A hook summary alone does not settle a task.
 - 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.
 
@@ -47,9 +64,21 @@ Reads are bounded to the most recent 16 MiB of the exact session transcript. A m
 
 ## 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.
+Native Send and explicit native Watch share the **720-minute default hard deadline**, with a two-second observation interval. Managed terminal tasks use their existing Turn monitor and separate 60-minute inactivity window. Keep the original task's advertised recovery actions. Native Watch 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.
+For a native Watch, use an explicit renewal only when the same native input is still active. A completed, failed, interrupted, or exited native task cannot renew. `recover` reconciles saved state; it neither resends the prompt nor extends the deadline. `close` ends AKK's management of a native Send, while `unwatch` stops observation. Neither cancels Claude. Managed terminal tasks retain their existing Turn-specific approval, renewal, cancellation and close actions. 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 native concepts.
+
+If the native conversation's exact terminal is owned by another AKK Store, idle
+Claude does not authorize a managed Send or native fallback. Use only its fresh
+`transfer_store_authority` action when offered: the tool is
+`agent_knock_knock_reconcile_binding` with `operation:"transfer_store_authority"`
+and the action's physical `terminal_id`. This explicitly transfers settled Store
+authority without sending Claude input or creating a Turn. Legacy records may
+require the user to stop all source-Store Hosts and old writers and explicitly
+set `maintenance_acknowledgement:true`; the agent cannot infer that condition.
+Afterward refresh List and keep the original native `conversation_id` for Send.
+Ordinary binding reconciliation only detaches a local Session and cannot replace
+this transfer. See [terminal recovery](operator-guide.md#terminal-recovery-and-diagnostics).
 
 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.
 
@@ -57,4 +86,6 @@ AKK persists the exact acceptance anchor, monitor deadline and callback outbox.
 
 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.
 
+Transcript and Status readers validate supported record and panel structures instead of requiring a tested version floor. A transcript task still needs a consistent complete version and exact causal identity; mixed versions within its chain do not prove completion. Recognized Status diagnostics are bounded and parsed as data, including supported Auto mode fields; a new version number does not make an unknown panel safe.
+
 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/list-output.md

@@ -22,6 +22,14 @@ display grouping alone does not copy terminal permissions or redirect selectors.
 Multiple candidates, conflicts and terminals needing management recovery remain
 visible. Rows and connections are not a count of independent tasks.
 
+Presentation does not choose the Send transport. New Codex sends prefer the
+verified shared backend. New Claude sends automatically prefer a managed Turn
+through a unique controllable terminal with the same native session and process;
+without that exact terminal they use the native inbox and return a Watch.
+Busy/blocked state, identity conflicts and management failures do not authorize
+bypassing an existing terminal through native delivery. Follow the returned
+`turn_id` or `watch_id`; old tasks and receipts retain their original provider.
+
 Starting in AKK `0.14.16`, default List also folds unnamed, unstarted Codex
 candidates when there is exactly one established conversation in the same Codex
 home and project, no conflicting identity, and no evidence of multiple physical

package/docs/operator-guide.md

@@ -73,9 +73,16 @@ Use `terminalDebug: true` or `list --terminal-debug` for all 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
+is never retried through another transport. For new Sends, Codex prefers the
+verified shared backend; Claude automatically uses a managed Turn through a
+unique controllable exact terminal, or a native inbox Watch when no such
+terminal exists. Claude approvals follow the managed Send's original `turn_id`
+after fresh Status. Native Claude Watches provide notify-only waiting hints,
+without approval authority. A terminal's busy/blocked state, ownership or Store
+conflict does not authorize native bypass. The
 [CLI backend guide](codex-cli-native-compatibility.md#automatic-conversation-routing-2026-10-10)
-describes routing evidence and presentation boundaries.
+and [Claude control guide](claude-cli-direct.md) describe the respective 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
@@ -161,7 +168,9 @@ The user-priority `terminal_user_explicit` path requires one exact live
 physical terminal/process, a scanned non-blocked approval state, and no proven
 input-owning questionnaire, editor, menu, or read-only viewer. Broken AKK Turn,
 Session, transfer, transition, ledger, or Store state cannot veto the user's
-explicit Send. Neither can parsed working activity, an existing draft, or
+explicit Send within the same Store authority. A conflicting or unfinished
+cross-Store authority transfer still blocks input, including physical fallback.
+Neither can parsed working activity, an existing draft, or
 ordinary Composer visibility, stability, or exactness. Codex physical fallback
 sends `C-u` once. Claude Code physical fallback uses a sentinel-backed native
 `C-s` stash-clear transaction that is independent of the cursor position and
@@ -322,6 +331,11 @@ stale metadata.
 
 Send preserves the selected conversation's existing permission mode. Use an
 explicit advertised permission action to change it before sending a task.
+Claude Code's `default` mode (`⏸ manual mode on`), plan, accept-edits, and
+bypass modes do not prohibit submitting user task text. Managed Send injects
+the task and dispatches Enter without changing that mode; any subsequent tool
+approval remains a separate interaction. A real approval dialog or changed
+terminal identity still requires the corresponding interaction or recovery.
 The [CLI backend](codex-cli-native-compatibility.md) and
 [Desktop](codex-desktop-compatibility.md#settings-and-cancellation) adapters
 apply and verify the selected conversation's native settings. For a Codex
@@ -329,6 +343,18 @@ terminal, [Codex permissions](codex-permissions.md) covers the current native
 choices and exact idle-terminal checks. Full Access is an explicit supported
 choice; AKK handles its native confirmation without an additional prompt.
 
+Claude Code currently has no AKK `permission_options` or `set_permissions`
+operation. Supported managed approvals decide one current request; they do not
+change the session's permission mode. The native sender's `bypass` or
+`prompting` declaration is message metadata, not a permission-setting API.
+
+Host Send uses the dispatch stages' own lock, transport, and acceptance
+timeouts instead of the relay's generic 90-second deadline. Slow discovery
+must not kill the dispatcher between text injection and Enter. Explicit Host
+cancellation and explicitly supplied relay deadlines still apply. If a sender
+is interrupted, inspect its durable submission receipt before deciding what
+to do; an unproven receipt never authorizes an automatic resend or Enter.
+
 ## Safe model control
 
 This section describes terminal model control. Desktop settings use the
@@ -390,12 +416,19 @@ requires one exact current native Session. The pane
 must remain safely idle with an exactly empty Composer, except for the exact
 Codex residual continuation described above. An active Turn, working
 agent, approval, questionnaire or editor, read-only viewer, non-empty Composer,
-ambiguous or multi-rollout Codex identity, stale physical snapshot, unsupported
-version, or changed catalog fails closed
+ambiguous or multi-rollout Codex identity, stale physical snapshot, incompatible
+runtime contract, or changed catalog fails closed
 with no model-selection input. The private multi-step native sequence
 revalidates each frame and must return to the main Composer without submitting
 a task or answering a prompt.
 
+Claude Code model controls do not require an exact regression-tested version.
+Other complete `x.y.z` versions may attempt the supported picker contract, and
+`model_control.reason` identifies an unverified profile. The live picker,
+closed choices and session-scope footer must still be recognized. Missing or
+malformed versions and unknown UI layouts do not authorize model selection.
+Standard `claude` and configured wrappers such as `tclaude` share this behavior.
+
 Provider scope is explicit in both results:
 
 - Codex reports `scope="current_and_new_sessions"`. Its native model flow
@@ -540,6 +573,47 @@ state makes them meaningful. `reconcile_binding`, `identify_foreground`, and
 `repair_model_control` retain their physical-terminal requirements; backend
 Recover does not replace them.
 
+An idle coding-agent terminal can still belong to another AKK Store. A resolved
+dispatch means its task settled; it does not release that Store's native-thread
+authority. List reports this conflict and withholds managed Send. An exactly
+associated Claude native conversation can carry its terminal's recovery action;
+use that action's physical `terminal_id`, while retaining the native
+`conversation_id` for the later ordinary Send.
+
+The shared runtime stays at its existing configured location; recovery does not
+move the runtime or delete temporary Stores. Automatic recovery is limited to
+Stores explicitly created with `AKK_EPHEMERAL_STORE=1`, under a private, owned,
+non-symlink `akk-*` directory inside the system temporary directory. Every
+registered owner must be proven dead by its exact process incarnation, and the
+native session, physical terminal, idle state, and settled work must still be
+verified. A temporary pathname, elapsed time, or dead PID alone is insufficient.
+Persistent Stores require the advertised explicit transfer. A newer writer
+recording legacy authority preserves its incomplete owner coverage; later writes
+cannot make that legacy authority eligible for automatic recovery.
+
+There are two distinct binding-recovery operations:
+
+- `agent_knock_knock_reconcile_binding({terminal_id,conflicting_session_id})`
+  detaches one advertised stale binding in the current Store. It does not move
+  another Store's authority or adopt the live thread.
+- An advertised `transfer_store_authority` action uses
+  `agent_knock_knock_reconcile_binding({operation:"transfer_store_authority",terminal_id})`.
+  After explicit user confirmation, AKK rechecks the displayed authority and
+  transfers eligible settled native-thread authority to this Host's Store.
+  No coding-agent input is sent and no Turn is created. Refresh List before
+  continuing with the original native conversation's newly advertised Send.
+
+For legacy records whose previous Host/writer ownership cannot be proven, the
+action requires `maintenance_acknowledgement`. Stop every Host and old writer
+using the **source Store**, then explicitly confirm that condition and include
+`maintenance_acknowledgement:true`. The controller must never prefill this
+acknowledgement. An idle Claude/Codex prompt, completed task, resolved ledger, or
+elapsed timeout is insufficient evidence that those writers have stopped.
+Any observed live or unverifiable owner, unresolved work, or changed authority
+still prevents transfer. If no transfer action is advertised, use the reported
+owner/conflict diagnostics to resolve the source Host; do not delete a ledger,
+clear Store files, guess a Session ID, or supply a private authority token.
+
 | Command | Use |
 | --- | --- |
 | `/akk doctor` | Diagnose installation, Host, terminal, and coding-agent readiness. |

package/docs/storage-and-logging.md

@@ -16,22 +16,23 @@ remain private.
 - The Store manifest fences incompatible managed writers before managed
   terminal or callback mutations. An eligible explicit physical Send retains
   its separate runtime receipt and input-safety checks; it cannot mutate an
-  incompatible managed Store.
+  incompatible managed Store. Conflicting or unfinished cross-Store authority
+  also blocks physical fallback; a physical Send token cannot bypass that fence.
 
 ## Compatibility manifest
 
 The manifest checks storage format and writer behavior separately. An unknown
-`format_version` is not read. The current writer protocol is 10; writer
-protocols 1 through 9 are supported predecessors and inspection reports them
+`format_version` is not read. The current writer protocol is 11; writer
+protocols 1 through 10 are supported predecessors and inspection reports them
 as `upgradeable`.
 
 Upgrading protocol 1 or 2 validates predecessor Turn records,
 deterministically derives and durably materializes authoritative Session
 records, quarantines ambiguous Session bindings, and finishes by atomically
-publishing protocol 10. Existing Turn state, event logs, and the original
+publishing protocol 11. Existing Turn state, event logs, and the original
 manifest `created_at` remain unchanged.
 
-Protocols 3 through 9 already have Session authority, so their upgrade is an
+Protocols 3 through 10 already have Session authority, so their upgrade is an
 atomic manifest-only writer fence with no data migration. Protocol 6 prevents
 older writers from rejecting or damaging schema-v2 Terminal Watch records.
 Protocol 7 fences the `interaction_manual_required` notification kind from
@@ -44,6 +45,10 @@ normalized to `notify_only`; they never silently acquire terminal response
 authority. Downgrading after v3 records exist is not supported. Protocol 10 additionally requires deletion receipts before pruning completed Watch
 bodies, preventing older writers from recreating an expired Send. Do not manually
 lower the manifest for rollback: restore a coherent pre-upgrade backup instead.
+Protocol 11 additionally fences retired Session authority after a Store transfer.
+The source Session keeps a durable retirement record, and predecessor writers
+are refused before they can revive it. Store authority transfer uses a shared
+terminal lock and a resumable journal; it does not replay terminal input.
 Core
 Session/Turn data remains readable across a writer-protocol mismatch, while
 explicit reconciliation reports `skipped` and managed mutations fail before

package/docs/testing.md

@@ -233,8 +233,10 @@ replays terminal input while resolving that identity.
 The semantic
 `native_thread_id` remains public for resume. The plugin/CLI still derives and
 revalidates those private fences under lock. Store format remains 1 and the
-Terminal Watch schema is 3; writer protocol 10 fences capability-checked paginated task
-bindings, private native-question checkpoints and Watch deletion receipts from older writers. It retains
+Terminal Watch schema is 3; writer protocol 11 additionally fences retired Session
+authority after Store transfer so predecessor writers cannot revive the source
+Session. Earlier protocols fence capability-checked paginated task bindings,
+private native-question checkpoints and Watch deletion receipts from older writers. It retains
 the manual-interaction notification state and bounded callback metadata introduced
 in writer protocol 7. The Watch schema version fences the response aggregate.
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-knock-knock",
   "name": "Agent Knock Knock",
   "categories": ["developer-tools"],
-  "description": "Select a conversation once; AKK prefers its verified backend, coalesces only exact terminal associations and preserves eligible terminal fallback without replaying uncertain input. Control loaded Codex CLI threads directly through their backend for discovery, tasks, exact completion callbacks, approvals, answers and permission settings without tmux or Herdr. Discover Codex Desktop persisted expanded sidebar members or explicitly search history, retain unconnected rows, send tasks to live owners, watch exact completion, approve or reject command/file requests, answer blocking and asynchronous questions, adjust current-conversation permissions and model settings, and cancel exact tasks. Control Codex and Claude Code through shared tmux or Herdr terminals, with closed native status inspection, model and permission control, compatibility warnings, native-thread lifecycle controls, managed monitoring, durable Terminal Watch, approvals, and human takeover.",
+  "description": "Select a conversation once; AKK prefers the shared backend for Codex and an exact managed terminal for new Claude Code Sends, using the Claude native inbox when no controllable terminal exists. Existing tasks keep their original routes and uncertain input is never replayed. Control loaded Codex CLI threads directly for discovery, tasks, exact completion callbacks, approvals, answers and permission settings without tmux or Herdr. Discover Codex Desktop sidebar members or search history, send to live owners, observe exact completion, handle supported approvals and questions, change current-conversation settings, and cancel exact tasks. Standard Claude Code and configured wrappers such as tclaude share the same adapter. Eligible tmux or Herdr controls provide native inspection, model and thread lifecycle operations, managed monitoring, approvals and question responses; permission-mode switching remains Codex-only. Availability follows exact identity, runtime evidence and current action authority.",
   "activation": {
     "onStartup": true,
     "onCommands": ["akk"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.14.17",
+  "version": "0.16.0",
   "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

@@ -25,9 +25,9 @@ Present `conversations[]` as **CLI** or **Desktop** using `surface`, and keep Co
 
 Default CLI presentation prefers the verified backend entry for a one-to-one same-agent/project discovery pair without known identity conflicts. Use that returned conversation ID and its actions directly; do not search for or choose an alternative transport. Its title, state and actions belong to the selected backend. Presentation preference does not prove a terminal alias, copy terminal permissions, or redirect a previously selected terminal ID. Multiple candidates, conflicts and terminal attention/recovery records remain visible. Proven exact aliases still combine verified controls. Use `terminalDebug: true` (CLI `list --terminal-debug`) only when connection diagnostics are needed, not as a routine selection step. Unnamed, unstarted Codex candidates beside an established same-project conversation may be folded for display; `conversation_presentation.unstarted_candidates_omitted` reports their count and `diagnostic_query` expands them. This does not prove abandonment or an exact alias. If the requested new empty session is missing, use that query and its original exact ID; never substitute the established conversation. Sole or exactly associated new sessions remain visible, and a first task restores ordinary display.
 
-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.
+For new Codex sends, AKK prefers the verified shared backend and retains an eligible terminal path when that backend is unavailable. For new Claude Code sends, AKK automatically prefers a managed terminal Turn when a unique controllable tmux/Herdr counterpart proves the same native session and process; without that terminal it uses the native inbox and returns a native Watch. The controller selects the conversation, not the transport or management mode. Busy/blocked state, identity conflict, ownership conflict or a Store error cannot authorize bypass to native delivery. Targeted reads can still use the exact backend; an idle terminal may use the advertised `/status` inspection to learn its identity, while 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.
+Use the returned `watch_id` or `turn_id` for that task's follow-up. Existing Watches, Turns, send receipts and pending interactions keep their task and route, including native Claude Watches created before a terminal became available. After a question or approval callback, refresh that exact Status and copy the current interaction action; do not translate its IDs to another transport. Claude managed approvals follow the returned `turn_id`. Codex 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.
 
 ## Recover a backend task
 
@@ -55,13 +55,23 @@ Use AKK's advertised actions and read the actual operation result after backend
 
 ## Direct Claude Code
 
-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.
+Claude Code conversations use `claude-cli:v1:...` IDs for an already-running native CLI. Standard `claude` and configured wrappers such as `tclaude` share the same adapter; no wrapper is required. The default executable is `claude`, with the usual `~/.claude` home unless configured otherwise. Starting with AKK 0.15.0, an ordinary Send automatically uses a managed terminal Turn when an exact controllable tmux/Herdr counterpart exists; without that terminal, native inbox delivery remains available. Native live observations include macOS Claude Code `2.1.295` and `2.1.296` with peer protocol `1`; these are tested versions, not minimum versions. Python 3 is required on the AKK side. It needs no Claude plugin, hook, special launch arguments or replacement process. Use actual advertised capabilities and runtime evidence 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.
+For native inbox delivery to Claude Code or tclaude, check `AKK_NATIVE_CLAUDE_SENDER_PERMISSION_CLASS` in the actual AKK/controller Host launch environment. It accepts `bypass` or `prompting` and declares the sender's permission class in the native `<cross-session-message from-mode="…">` envelope. AKK generates that envelope and escapes task text; send only the task in `request`, never construct a `from-mode` wrapper yourself. Managed terminal sends do not use that envelope. This declaration does not change Claude's permissions or approve a held message.
+
+- Determine this class from the sender/controller's actual permission policy, explicitly configured by its operator, or verified evidence about the sender. Apply it only within an authorized setup task. The receiver's process flags and permission mode may explain a held message, but cannot establish the sender's class. Do not copy the receiver's mode or infer `bypass` from a headless controller. Leave the declaration unset if the sender's policy cannot be established.
+- Configure the chosen value on the process that actually sends AKK requests, using its existing launch configuration. Setting it only in the target Claude process or another shell does not update a running Host. AKK itself never infers the class from the target command, target permissions, task text, or lack of an interactive UI; it uses the explicit sender configuration.
+- Unset or empty means no declaration; an invalid value rejects a new Send before submission. The receipt reports `sender_permission_class` and `sender_permission_class_source` (`operator_configured` or `unspecified`). These describe the declaration, not acceptance. Keep held/refused/uncertain receipts and inspect the original Watch or terminal: changing the variable does not update or resend an old message, and it never authorizes automatic replay.
+
+- Send to the selected verified idle conversation. With an exact eligible terminal, AKK creates the managed Turn and starts monitoring automatically; retain its `turn_id` for Status, supported approvals and question responses. No extra background flag or separate Watch is needed. When no exact terminal is available, native Send returns `claude-cli-watch:...` and monitors the exact input with the shared 720-minute hard deadline. Read the actual receipt; never claim managed approval support for a native Watch. Busy/blocked, held/refused or uncertain delivery must not be retried through another connection.
+- Use `status({turn_id})` for a managed task and `status({watch_id})` for a native task. Conversation Status reads the latest native input and is not a replacement for the original task receipt. Native Watch Status reads its exact `native_input_id`, which 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. Native `agent_acceptance: proven` requires exact sender/message/input evidence, not merely a socket write.
+- A successful `stop_hook_summary` does not prevent completion when the exact input's final message and durable completion record agree. Nonempty `hookErrors` or `preventedContinuation=true` still leave the task unproven; the summary alone is not proof of completion.
 - 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.
+- Use the advertised recovery and monitoring actions on the original Turn or Watch. For a native Watch, 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.
+- Read the current `capabilities` and `available_actions` for cancellation, native inspection, model options and thread lifecycle controls. AKK exposes these existing terminal operations on the conversation only when one eligible tmux/Herdr counterpart matches its exact native session and process incarnation; it revalidates that counterpart at execution. Copy the advertised action and retain any model/lifecycle catalog result as required by the terminal guidance below. A missing counterpart or incompatible runtime contract/state does not grant input authority. An unlisted complete `x.y.z` version alone does not disable an otherwise eligible operation.
+- Claude terminal model selection has regression profiles for `2.1.266` and `2.1.285`; other complete `x.y.z` versions may attempt the supported runtime contract through a profile bound to the actual version. Surface the unverified-profile explanation in `model_control.reason`. The live picker, choices and session-scope footer must match before a catalog can authorize selection; exact session/process, idle empty Composer, fresh catalog and postcondition checks still apply. Missing or malformed versions and unknown picker layouts remain unavailable. Thread `clear` uses the supported new-thread transition; Resume uses the exact UUID from a fresh resumable-thread catalog.
+- An exact native Watch can notify the controller when its own task enters a registry waiting state; repeated observations of the same wait do not create duplicate notifications. These hints are notify-only (`requires_response=false`, `actionable=false`), and `pending_interaction_count: null` means the questions have not been exhaustively scanned. They do not supply response authority.
+- AKK's current Claude native peer adapter does not implement approvals or question answers, and neither Claude route implements permission-mode switching. Existing terminal-managed approvals and supported questionnaires retain their exact Turn requirements. A current managed questionnaire can advertise `respond_interaction` on the associated conversation; refresh the action's original `turn_id` with Status in the owning controller conversation and use the resulting current question/answer IDs. Do not apply its identifiers to a native Watch. Unlisted complete Claude versions may use the same strict questionnaire parser, with fingerprints bound to the actual version. Only a fully recognized current question, choices and footer can authorize a single choice, a supported custom-text step or final-review decision; secret, multi-select, unknown or malformed dialogs remain manual. A generic profile allows runtime validation; it does not establish that every UI on that version has been tested. When no current response/approval action is advertised, report `manual_required` and return to the original Claude terminal. The sender permission declaration above does not add `set_permissions` or `permission_options`.
 
 ## Codex Desktop
 
@@ -110,7 +120,9 @@ Core slash-command forms:
 - `/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 v31 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. The agent-neutral `terminal_user_explicit_composer_policy` advertises `replace_current_composer_and_submit`; the old Codex-named field is a v28 compatibility alias 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 and Claude Code `terminal_user_explicit` depend on the exact live terminal/process, a scanned non-blocked approval state, and no proven input-owning questionnaire, editor, menu, history search, or read-only viewer—not ordinary main-Composer visibility, stability, exactness, parsed working activity, existing draft contents, or AKK Store, Turn, Session, transfer, transition, ledger, or ownership. An unreviewed Codex frontend is the narrower exception: physical Send requires a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Profiled Codex 0.154.0/0.155.1 exact collapsed async-question summaries leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. Both advertise `replace_current_composer_and_submit`: Codex physical fallback sends `C-u` once; Claude Code physical fallback uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after either agent's user-explicit 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 the prepared exact request-bound or clearly labeled terminal-activity Watch and releases stale management. Watch persistence failure is a warning and never revokes or retries a successful Send; an unsafe or uncertain native probe still stops before task text. 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 clear or request input may have occurred, 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; unreviewed Codex frontends require the styled-Composer checks above.
+The `terminal_user_explicit` physical-delivery rules below describe retained legacy routes/receipts and other explicitly advertised fallback paths. New ordinary Claude sends use managed terminal delivery; Store or ownership failure does not degrade them to unmanaged work.
+
+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 v31 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. The agent-neutral `terminal_user_explicit_composer_policy` advertises `replace_current_composer_and_submit`; the old Codex-named field is a v28 compatibility alias 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. The following `terminal_user_explicit` rules apply to retained legacy receipts and other advertised physical fallback paths; new ordinary Claude Sends require a managed Turn and do not use Store or ownership failure to authorize unmanaged input. For those physical paths, Codex and Claude Code `terminal_user_explicit` depend on the exact live terminal/process, a scanned non-blocked approval state, and no proven input-owning questionnaire, editor, menu, history search, or read-only viewer—not ordinary main-Composer visibility, stability, exactness, parsed working activity, existing draft contents, or AKK Store, Turn, Session, transfer, transition, ledger, or ownership. An unreviewed Codex frontend is the narrower exception: physical Send requires a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Profiled Codex 0.154.0/0.155.1 exact collapsed async-question summaries leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. Both advertise `replace_current_composer_and_submit`: Codex physical fallback sends `C-u` once; Claude Code physical fallback uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after either agent's user-explicit 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 the prepared exact request-bound or clearly labeled terminal-activity Watch and releases stale management. Watch persistence failure is a warning and never revokes or retries a successful Send; an unsafe or uncertain native probe still stops before task text. 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 clear or request input may have occurred, 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; unreviewed Codex frontends require the styled-Composer checks above.
 
 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.
 
@@ -118,7 +130,7 @@ For an exact-empty idle Codex pane whose native identity is ambiguous, List may
 
 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.
+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; surface any supplied compatibility warning or diagnostic reason, 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 and later stable semantic versions may attempt an exact paginated task Watch instead of a legacy managed Session/Turn, including versions outside AKK's regression matrix. Before Send, AKK attempts a closed `/status` transaction in the available main Composer and validates the actual app-server read contract, Codex home, native thread, and task boundaries. A new version alone does not reject read-only observation. An existing exact Watch may continue across a compatible backend upgrade while retaining its original thread, turn, and request identity. When a Watch attaches, retain its `watch_id` for Status and callbacks; do not invent a `turn_id`. Read compatibility grants no native response authority: unreviewed frontend/backend pairs are notify-only, and backend drift withdraws existing executable question offers. Use fresh Status and its advertised capabilities before any response. This adapter does not establish managed session-only dispatch or native new/resume for paginated threads. Supported 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.
 
@@ -126,7 +138,7 @@ AKK discovers eligible panes across workspaces. When more than one target matche
 
 Natural-language forms:
 
-- `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one send-ready pane exists. A scanned blocked approval or proven input-owning questionnaire, editor, menu, or read-only viewer vetoes physical Send; parsed working activity and an existing draft do not. Unreviewed Codex frontends require the styled-Composer checks above; reviewed physical Send paths do not require ordinary main-Composer visibility. Codex replaces the current Composer with `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request and submits exactly once. Broken or stale AKK management activity records do not veto that independently verified live terminal/process.
+- `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one send-ready pane exists. A selected Claude terminal uses the managed path and refuses busy, ownership or Store blockers. On eligible physical fallback paths, a scanned blocked approval or proven input-owning questionnaire, editor, menu, or read-only viewer vetoes physical Send; parsed working activity and an existing draft do not. Unreviewed Codex frontends require the styled-Composer checks above; reviewed physical Send paths do not require ordinary main-Composer visibility. Codex replaces the current Composer with `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request and submits exactly once. Broken or stale AKK management activity records do not veto that independently verified live terminal/process.
 - `AKK Codex: <task>`: list first and identify one exact eligible Codex conversation. For a direct CLI or Desktop row, copy its advertised Send with `conversation_id`; for a terminal row use its `terminal_id`. Send `request=<task>` once through that route. Do not count duplicate representations of the same proven thread as separate tasks.
 - `AKK Claude: <task>`: list first, require one exact eligible Claude row, then call `agent_knock_knock_send` with that row's `terminal_id` and `request=<task>`.
 - Requests to list AKK or local coding-agent work: call `agent_knock_knock_list`.
@@ -140,6 +152,8 @@ Natural-language forms:
 - Requests to list resumable native threads for an exact terminal: call `agent_knock_knock_list_resumable_threads` with the terminal row's prefilled `terminal_id`.
 - Explicit requests to start a new thread or clear context: call `agent_knock_knock_new_thread({terminal_id})` only from an advertised `new_thread` action.
 - Explicit requests for low-level recovery of a listed binding conflict: after explicit user confirmation, call only the advertised `agent_knock_knock_reconcile_binding({terminal_id,conflicting_session_id})`. AKK derives its revision and binding fences privately, detaches the stale/conflicting binding without adopting the live thread, and requires a fresh list afterward. Do not use it in place of an advertised follow-current send.
+- Automatic Store authority recovery keeps the existing shared runtime location and never deletes temporary Store directories. It requires the source Store's explicit `AKK_EPHEMERAL_STORE=1` registration, a private owned non-symlink `akk-*` path inside the system temporary directory, every registered owner proven dead by exact process incarnation, settled work, and fresh matching native-session/terminal identity with idle non-blocked status. A temporary pathname, timeout or absent PID alone never grants takeover. Persistent Stores use the explicit transfer action below. When a newer writer records older legacy authority, incomplete legacy owner coverage remains recorded; later writes cannot turn it into an automatic takeover candidate. Conflicting or unfinished cross-Store authority also blocks physical fallback Send; do not use a native backend or physical token to bypass it.
+- Explicit requests to move a settled native thread's authority from another AKK Store to this Host: refresh List and use only `available_actions.transfer_store_authority`, including when it appears on a native Claude conversation row. Its tool is `agent_knock_knock_reconcile_binding({operation:"transfer_store_authority",terminal_id})`; keep the advertised physical `terminal_id` and obtain explicit user confirmation for the transfer. If `missing_required` includes `maintenance_acknowledgement`, the legacy record cannot prove the previous Host/writer has stopped: first require the user to stop every Host and old writer using the source Store and explicitly confirm that maintenance condition, then pass `maintenance_acknowledgement:true`. Never prefill or infer this from an idle terminal, a completed task, a resolved ledger, or an elapsed timeout. Visible live or unverifiable owners and unresolved work remain blocked. The transfer sends no coding-agent input and creates no Turn; refresh List afterward and use the same native conversation's newly advertised Send. Never delete ledger or Store files, invent a conflicting Session, pass private tokens/Store paths, or use binding-detach as an authority-transfer substitute.
 - Explicit requests to resume prior native context: first call `agent_knock_knock_list_resumable_threads`; then call `agent_knock_knock_resume_thread({terminal_id,native_thread_id})` for one `resumable=true` candidate using its complete UUID. For “previous” / “刚才那个”, proceed only when the fresh result advertises `previous.available_actions.resume_thread`; use that exact semantic-ID action and never substitute the newest row. Human-facing numbers and short IDs are resolved privately and are never structured tool arguments.
 - Requests to inspect current output or ask what a task is doing: call `agent_knock_knock_status`.
 - A later ordinary request: refresh `agent_knock_knock_list` and use only the selected terminal row's advertised send. Use `send({session_id,request})` for `session_exact` or `send({terminal_id,request})` for `terminal_follow_current`; never substitute a retained Session or Turn identity.
@@ -162,7 +176,7 @@ For ordinary send or an in-flight answer:
 2. If no ID is supplied and more than one eligible pane may exist, call `agent_knock_knock_list`.
 3. Treat `conversations[]` as the primary resource list; older raw CLI output may expose `terminals[]` instead. For a terminal-backed row, its managed context exposes `session_id`; `managed.current_turn` is the current AKK owner. Query `watches` for retained monitoring and managed Turn history, including unavailable-pane recovery.
 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. User-selected 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. For an ordinary selected conversation, call `agent_knock_knock_send({conversation_id,request})`; terminal-scoped rows also accept legacy `terminal_id`. The following physical-input rules apply only if AKK selects terminal delivery. `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 `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the new request and submits exactly once without a post-text Composer veto. 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. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, 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.
+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. For an ordinary selected conversation, call `agent_knock_knock_send({conversation_id,request})`; terminal-scoped rows also accept legacy `terminal_id`. The following physical-input rules describe retained legacy routes/receipts and other explicitly advertised physical fallback paths; new ordinary Claude sends retain the managed path and do not fall back to unmanaged delivery after a Store or ownership failure. `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 `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the new request and submits exactly once without a post-text Composer veto. 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. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, 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.
 
 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.
@@ -185,7 +199,7 @@ Hard creation failure includes an absent exact terminal, inability to identify i
 
 Approval attention is notification-only for every Watch: never call an approval tool for a `watch_id`, send approval keys, or apply `autoApprove`. Native-interaction 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 interaction 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 integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v32. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v4 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`.
+The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v33. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v4 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 Codex permission changes, first call `agent_knock_knock_permission_options({terminal_id})` from the current row’s advertised action. This sends closed `/status` and `/permissions` inspection input but leaves permissions unchanged; the terminal must be idle, its Composer empty, and its physical and native thread identities verifiable. Use `current`, `scope`, and the returned choice descriptions to select the requested or authorized mode. Then call `agent_knock_knock_set_permissions({terminal_id,mode})` using its exact returned semantic ID in the same controller conversation. Full Access is an ordinary option and needs no additional user confirmation. AKK automatically handles its exact native confirmation inside this permission transaction; do not pause to ask the user to confirm Full Access or call generic `approve` for that dialog. Ordinary Send does not change permissions. Codex 0.160 may report `current="workspace_granular"`; this is a current-only native default, not a selectable mode. Select only an ID actually returned in `choices`. Only currently displayed built-in modes are supported: do not invent `read_only` when the picker omits it, supply a named/custom profile, or pass commands, labels, menu indexes, keys, tokens, or scope overrides. Changes affect the current session/thread, may be retained on Resume, and leave global defaults unchanged. Send the intended task only after `outcome="changed"` or `"already_effective"` with matching `effective.mode`; `"uncertain"` means stop and do not retry automatically. Refresh the catalog after any change or consumed attempt.
 
@@ -321,6 +335,7 @@ Action-name glossary:
 - `permission_options` and `set_permissions`: inspect one idle Codex pane’s built-in permission modes, then consume one catalog for the requested or authorized change, including Full Access without an extra confirmation. Ordinary Send never increases permissions.
 - `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.
+- `transfer_store_authority`: explicitly transfer settled native-thread authority to this Host's Store through the `reconcile_binding` tool's `operation:"transfer_store_authority"` form; legacy maintenance acknowledgement must come from the user after source-Store Hosts and old writers have stopped.
 - `respond`: answer ordinary text inside the current managed Turn.
 - `respond_interaction`: answer one current native interaction step obtained from fresh Status; an `async_question` defaults to advertised `steer_current_turn` or accepts explicit advertised `queue_next_turn` as `delivery_mode`, while a blocking `questionnaire` omits it.
 - `approve`: apply only an explicitly confirmed advertised semantic approval decision.
@@ -330,9 +345,9 @@ Action-name glossary:
 - `close`: release AKK management for the selected Send Turn without stopping the coding agent or closing its conversation.
 - `recover`: reconcile an exact backend task and its receipt without resending work or changing its anchor.
 
-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.
+The tool name is normally `agent_knock_knock_<action-name>`. List aliases are `retry_submission`, which invokes `agent_knock_knock_send` with its listed `turn_id` only after explicit confirmation, and `transfer_store_authority`, which invokes `agent_knock_knock_reconcile_binding` with the explicit transfer operation. 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`; user-selected `watch({terminal_id})` deliberately honors an exact user-selected terminal even without advertisement. A native interaction response instead requires the current `interaction_state` returned by Status in the same controller conversation. Approval, native interaction response, handoff takeover, and `reconcile_binding` require explicit user intent and fresh source state. Model-facing shapes include `permission_options({terminal_id})` and `set_permissions({terminal_id,mode})`; `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,delivery_mode?})`, with exactly one subject id, only projected question/option ids, and `delivery_mode` present only for `async_question`; 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 10; Terminal Watch schema remains 3.
+`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`; user-selected `watch({terminal_id})` deliberately honors an exact user-selected terminal even without advertisement. A native interaction response instead requires the current `interaction_state` returned by Status in the same controller conversation. Approval, native interaction response, handoff takeover, and `reconcile_binding` require explicit user intent and fresh source state. Model-facing shapes include `permission_options({terminal_id})` and `set_permissions({terminal_id,mode})`; `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,delivery_mode?})`, with exactly one subject id, only projected question/option ids, and `delivery_mode` present only for `async_question`; 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})` or its separately advertised `{operation:"transfer_store_authority",terminal_id,maintenance_acknowledgement?:true}` form. 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 11; Terminal Watch schema remains 3. Protocol 11 fences retired Session authority so predecessor writers cannot revive a source Session after Store authority transfer.
 
 Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal identity. Native inspection and lifecycle input require an exactly empty Composer; managed Send may require exact empty before input. Codex and Claude Code `terminal_user_explicit` instead require a scanned non-blocked approval state and no proven input-owning questionnaire, editor, menu, or read-only viewer. Reviewed physical Send paths do not require ordinary main-Composer visibility, stability, or exactness. Unreviewed Codex frontends require a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Existing drafts and parsed working activity do not themselves veto the user-priority path, and after text injection no Composer observation may veto Enter. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Humans can attach to the same tmux or Herdr session and continue directly at any time.