@scotthuang/agent-knock-knock 0.13.18 → 0.14.0

package/docs/architecture/current-architecture.md

@@ -0,0 +1,313 @@
+# Current architecture and health budget
+
+Status: authoritative current architecture through the `0.13.17` refactor closeout.
+
+Historical opening snapshot: `main@0667537ac6efe116c5261fa33370a4190f2d2226`, package
+`0.13.3`, measured 2026-09-15. The machine-readable baseline and budgets are
+in [`config/architecture-health-budget.json`](../../config/architecture-health-budget.json).
+Run `npm run architecture:dashboard` to validate the budgets and print the
+current JSON dashboard. The `0.13.17` closeout below supersedes the earlier
+ratchet values; the opening and P2 measurements remain historical evidence.
+
+The stable [orchestration architecture index](./orchestration-refactor.md)
+routes readers to this current document or the immutable
+[Issue #126 historical ledger](./orchestration-refactor-history.md). That
+ledger and the [Issue #126 closeout report](./issue-126-final-report.md) are
+historical evidence; they do not describe current module sizes, protocols, or
+the current health budget.
+
+## Shape of the system
+
+Production dependencies flow inward:
+
+```text
+CLI / OpenClaw / Host connectors
+  -> typed command facades and composition
+  -> dispatch / lifecycle / callback / monitor / watch application services
+  -> pure authority, policy, and state-transition modules
+  -> domain records and ports
+
+tmux / Herdr / Codex / Claude / Store / Gateway adapters implement ports
+and point back toward the application boundary.
+```
+
+`src/cli.ts` is the sole production importer of `src/cli-core.ts`. The core is
+a compatibility command facade, not an owner of terminal, lifecycle, monitor,
+Watch, callback, or persistence state machines. Every production module has one
+domain owner in `config/production-module-ownership.json`; the compiler-AST
+architecture gate rejects missing ownership, computed production imports,
+dependency cycles, duplicated canonical status policies, and unapproved reverse
+imports into `cli-core.ts`.
+
+The canonical mutation lock order remains:
+
+```text
+terminal dispatch lock -> Store writer lease -> conversation state lock
+```
+
+Refactoring must preserve durable reservation before terminal input, exact
+terminal/process/cwd authority, execution-time revalidation, reverse-order lock
+release, and `uncertain + do_not_retry` after possible input with an unproven
+postcondition.
+
+## Issue #320 opening snapshot
+
+| Metric | Snapshot | Gate |
+| --- | ---: | --- |
+| Production modules | 155 | observed |
+| Production physical LOC | 144,726 | observed only |
+| Production functions | 5,926 | observed |
+| Production import edges | 1,004 | observed |
+| Production import cycles | 0 | must remain 0 |
+| Hard function violations (`>=500` LOC or `>=50` approximate complexity) | 0 | must remain 0 |
+| Default function violations (`>=100` LOC or `>=20` approximate complexity) | 338 | must not increase |
+| Production files over 2,000 LOC | 19 | must not increase |
+| OpenClaw / Host Bridge semantic tools | 24 each | must stay synchronized |
+| Pi / DSH catalog parity | Host Adapter capability handshake v1 | fail closed on catalog, registration, or Skill drift |
+| Canonical / generated Pi / generated DSH Skill documents | byte-identical | generated by a hash-gated sync step |
+
+Total production LOC is deliberately not a pass/fail budget. Typed safety
+checks, compatibility profiles, and evidence may legitimately add source. It is
+still reported with a delta from this snapshot so growth remains visible. The
+gate instead targets concentration, complexity, cycles, and duplicated public
+artifacts.
+
+The `cli-core.ts` ceiling is 1,839 LOC and can move downward without editing a
+manifest. Eight opening concentration paths have individual ratcheting budgets:
+
+| Path | Maximum physical LOC |
+| --- | ---: |
+| `src/terminal-command-cli-adapter.ts` | 10,421 |
+| `src/terminal-agent-bridge.ts` | 7,409 |
+| `src/terminal-list-cli-adapter.ts` | 5,093 |
+| `src/openclaw-plugin-command-adapter.ts` | 3,817 |
+| `src/terminal-watch-cli-adapter.ts` | 3,683 |
+| `src/claude-local-transcript-provider.ts` | 3,534 |
+| `src/terminal-monitor-state-cli-adapter.ts` | 3,478 |
+| `src/terminal-watch-store.ts` | 3,191 |
+
+These are ceilings, not desired final sizes. Removing or splitting a hotspot is
+allowed without changing its historical budget; the dashboard reports a removed
+path as `retired: true` with zero current LOC. Reusing that same path later still
+subjects it to its historical ceiling. Raising a baseline ceiling is rejected
+by the validator rather than normalized away in a routine feature PR.
+
+## P2 closeout ratchets
+
+Measured on 2026-09-15 at `main@9b4b007` before the closeout-budget commit:
+
+| Metric | P2 closeout | Opening delta |
+| --- | ---: | ---: |
+| Production modules | 212 | +57 responsibility-focused modules |
+| Production physical LOC | 150,684 | +5,958 observed-only LOC |
+| Production functions | 6,210 | +284 |
+| Production import edges | 1,382 | +378 |
+| Import cycles / hard function violations | 0 / 0 | unchanged |
+| Default function violations | 332 | -6 |
+| Production files over 2,000 LOC | 9 | -10 |
+| Largest production file | 3,635 LOC | below the new 5,000-LOC gate |
+
+The P2 closeout converted the achieved concentration reductions into executable
+non-regression gates. At that milestone the budget permitted no more than nine
+production files over 2,000 physical LOC, rejected every production file at
+5,000 LOC or larger, and lowered each tracked hotspot ceiling to its
+post-refactor size. The default function-violation ceiling was likewise lowered
+from the opening 338 to the measured closeout value. The `0.13.17` milestone
+tightens these ratchets again; it does not raise them to absorb feature growth.
+
+The separate 90-day goal of at most 250 default-threshold violations is not a
+claim about this P2 milestone. Reaching it requires function-level decomposition
+across callback, Watch, identity, transcript, and terminal-input policies rather
+than mechanical file movement. It remains visible follow-up work; the current
+ratchet neither weakens the `>=100` LOC / `>=20` approximate-complexity
+definition nor labels that longer-horizon target complete.
+
+Two other 90-day measures are longitudinal rather than static source gates:
+the typical production-file touch count for a new agent/version profile and
+`test:fast` p50/p95. They require evidence across multiple future changes or
+runs and are not inferred from a single P2 checkout.
+
+## 0.13.17 refactor closeout
+
+Measured on 2026-10-02 against the released `0.13.16` source at `d9e6b3f`.
+This phase covers the published backend, its test support, and release
+verification scripts. Uncommitted Control UI work from another checkout is
+outside this comparison.
+
+| Metric | 0.13.16 baseline | 0.13.17 closeout | Delta |
+| --- | ---: | ---: | ---: |
+| Production modules | 248 | 281 | +33 |
+| Production physical LOC | 161,601 | 163,877 | +2,276 |
+| Production functions | 6,922 | 6,965 | +43 |
+| Production import edges | 1,590 | 1,821 | +231 |
+| Import cycles / hard function violations | 0 / 0 | 0 / 0 | unchanged |
+| Default function violations | 332 | 330 | -2 |
+| Production files over 2,000 LOC | 9 | 4 | -5 |
+| Largest production file | 3,631 LOC | 3,534 LOC | -97 LOC |
+
+The decomposition gives Watch capture, fallback observation, interaction
+authority, and response execution separate owners; Monitor reconciliation and
+recovery likewise leave its CLI facade. Legacy Codex rollout file access,
+record parsing, human-started task observation, interaction evidence, and bound
+completion now have distinct modules. Native model-control execution and
+surface/input handling, Codex inventory, and native inspection proof are also
+separated from their existing public entry points.
+
+| Existing production entry point | Before LOC | After LOC |
+| --- | ---: | ---: |
+| `src/terminal-watch-cli-adapter.ts` | 3,631 | 651 |
+| `src/terminal-monitor-state-cli-adapter.ts` | 3,476 | 1,119 |
+| `src/terminal-submission-acceptance.ts` | 3,414 | 771 |
+| `src/native-thread-lifecycle-cli-adapter.ts` | 2,852 | 1,764 |
+| `src/terminal-model-control.ts` | 2,658 | 1,151 |
+| `src/codex-store-adapter.ts` | 1,795 | 744 |
+| `src/terminal-native-inspection-bridge.ts` | 1,956 | 1,080 |
+
+These are physical line counts, including comments and blank lines. Splitting
+modules and wrapping long descriptions adds explicit imports, interfaces, and
+lines: total production LOC increases about 1.4%. That growth is reported,
+not presented as code removal. The improvement is reduced responsibility
+concentration with unchanged dependency direction and public behavior.
+Production lines over 160, 200, and 300 characters fall from 192/118/63 to
+87/36/9 respectively; script lines over 160 characters fall from six to zero.
+This is targeted readability work, not a repository-wide formatting rewrite.
+
+Test and maintenance boundaries are preserved too. The 4,970-line Watch test
+file becomes a 9-line registration entry over eight behavior groups and shared
+fixtures; its 42 test definitions and 352 assertion calls are unchanged in
+static AST comparison. The 3,080-line no-rollout support file becomes a
+112-line export facade over 14 modules; all 62 functions and 86 assertions are
+retained, including the deliberate subprocess and crash/exit cases. The
+affected-test map records the new direct consumers without changing test-tier
+entry points. The 1,744-line refactor-evidence script and 1,339-line OpenClaw
+compatibility script become 50-line and 90-line entry points over domain
+modules. The compatibility flow retains all 72 assertions and the same
+Gateway cleanup boundary. Its full-host function now delegates lifecycle
+stages rather than owning the entire scenario inline.
+
+The bound-completion detector preserves acceptance and identity error
+precedence, diagnostic fields, the same open descriptor for reads and stat
+checks, and its `finally` close on every post-open return. Public facades retain
+their exports. Compiled comparison against the immutable `0.13.16` package
+confirms equal action-contract values, fresh nested contract objects, equal
+schema exports, and the same complete 24-tool catalog. Extracted descriptions
+and guidance retain their exact text; native approval and input checks are not
+relaxed. Long captured ANSI fixture data remains intact.
+
+The current executable ratchets now permit at most **330 default function
+violations** and **four production files over 2,000 LOC**. Watch, Monitor, and
+List hotspot ceilings are **651**, **1,119**, and **2,616** LOC respectively.
+The other hotspot ceilings remain as recorded in the budget manifest. Import
+cycles and hard function violations must remain zero, and the 4,999-LOC
+production-file ceiling remains unchanged. These values replace the earlier
+P2 allowances; the historical snapshot is not rewritten.
+
+Four production files still exceed 2,000 physical lines:
+
+| Remaining concentration | Physical LOC |
+| --- | ---: |
+| `src/claude-local-transcript-provider.ts` | 3,534 |
+| `src/terminal-agent-bridge.ts` | 2,641 |
+| `src/terminal-list-cli-adapter.ts` | 2,616 |
+| `src/terminal-acceptance-cli-adapter.ts` | 2,272 |
+
+Those files and the remaining 330 default-threshold function violations remain
+follow-up work. This closeout does not claim that all complexity is eliminated
+or that the longer-horizon 250-violation goal has been reached.
+
+Validation completed for publication: `npm run test:fast` passed all 2,434
+tests; `npm run test:release` passed all 2,949 full-suite tests, the isolated
+OpenClaw 2026.9.1 install/callback/update/uninstall scenario, ClawHub runtime
+inspection (zero breakages or warnings), and publication dry run. TypeScript
+no-emit checking, JavaScript syntax/module-link checking, architecture and
+refactor-evidence validators, static preservation review, and compiled
+public-contract parity also passed. All 27 changed production modules retain
+their previous runtime exports. No live terminal scenarios were executed;
+fixture coverage and package comparisons do not substitute for live verification.
+
+## Contract synchronization
+
+The canonical semantic tool contract remains
+`config/public-contract-witnesses.json`. Existing contract validation proves
+the exact OpenClaw list and the Host Bridge count. Pi and DeepSeek Harness no
+longer repeat that count or expose a source constant for the architecture gate
+to scrape. At startup they verify Host Adapter capability handshake v1: the
+contract version, ordered tool names and derived count, canonical catalog
+SHA-256, bundled Skill SHA-256, and their completed registration names must all
+agree. Missing, unknown, or drifted handshakes fail before AKK becomes ready.
+
+The only editable Skill source is:
+
+```text
+templates/openclaw-skills/agent-knock-knock/SKILL.md
+```
+
+The Pi and DeepSeek Harness package copies are generated artifacts and must not
+be edited directly. `npm run skill:sync` atomically regenerates both copies;
+`npm run skill:check` fails on a missing or byte-different artifact and reports
+the canonical SHA-256. Connector builds regenerate only their allowlisted copy,
+and build/prepack checks keep the packaged Skill byte-identical. The dashboard
+continues to report the canonical SHA-256 and every generated replica result.
+
+The architecture dashboard therefore reports only its directly witnessed
+OpenClaw/Host Bridge parity; connector parity is executable conformance rather
+than a regex over connector source. Connector release policy also has one
+engine. `npm run connectors:verify`
+runs its deterministic offline mode for Pi and DeepSeek Harness independently;
+the connector-local `release:check` wrappers add clean-main, upstream, unused
+npm version/tag, and explicit publish-confirmation checks. Ordinary root
+validation never queries published registry state.
+
+Host connectors and the shared semantic runtime depend only on the neutral
+`semantic-tool-*`, `semantic-private-authority-offers`, and
+`host-monitor-reconciliation` modules. OpenClaw's command, schema, helper,
+private-offer, and supervisor filenames are compatibility adapters over those
+owners; no Host or semantic-core module imports an `openclaw-*` implementation.
+This keeps the 24-tool schema/order/digest, owner-local offers, asynchronous
+relay, and one Host-owned lifecycle byte-compatible while making dependency
+direction executable in the fast contract tests and architecture evidence.
+
+## Refactor boundaries
+
+The Issue #320 sequence uses narrow strangler changes:
+
+1. P0 makes model-control availability and execution consume one decision and
+   makes managed Turn and Watch native-interaction responses consume one
+   transaction kernel.
+2. P1 decomposes the terminal command, List, and Bridge adapters along existing
+   use-case boundaries while retaining their public facades and single input
+   ledger boundary.
+3. P2 extracts reusable callback/Store kernels, makes the Host tool and Skill
+   catalogs single-source, and splits oversized tests and historical documents.
+
+Monitor and Watch share terminal observation and native-interaction execution,
+including blocking `questionnaire` and working-parallel Codex `async_question`
+offers. An async response defaults to advertised `steer_current_turn` or explicitly
+selects advertised `queue_next_turn`; a blocking questionnaire carries none. Both
+public paths remain semantic-ID-only and never expose raw keys or menu indexes.
+They do not share task-completion semantics or persistence ownership. Model
+control ordinary, residual-continuation, and repair authorities remain separate
+domains. Refactoring must not use file movement to collapse those distinctions.
+
+## Updating the dashboard
+
+Use the gate during each small refactor PR:
+
+```bash
+npm run test:fast
+npm run typecheck
+npm run build
+npm run validate:architecture
+npm run validate:refactor-evidence
+git diff --check
+```
+
+The architecture command exits nonzero before printing a successful dashboard
+when a budget or synchronization invariant fails. Normal P0/P1/P2 development
+uses only the fast test tier. Full/release tests follow repository policy and
+are not implied by updating this dashboard.
+
+Snapshot observation values are historical and are not rewritten after every
+feature. A hotspot or soft-complexity ceiling may be lowered after a completed
+refactor milestone. It must not be raised to make a regression green. New
+production modules still require an explicit owner and affected-test mapping.

package/docs/architecture/interactive-terminal-response.md

@@ -0,0 +1,276 @@
+# Interactive terminal response design
+
+Status: implemented public package contract
+
+## Problem
+
+AKK's terminal approval boundary historically exposes one operation: approve
+the adapter-proven first, one-time `Yes` choice. `cancel` interrupts the Turn;
+it is not a semantic `No` selection. Modern Claude Code and Codex TUI surfaces
+also ask ordinary questions with choices, optional free-form input, multiple
+steps, and a final confirmation. Treating every such surface as approval would
+conflate permission authority with task input and would make safe replay and
+auditing impossible.
+
+This design therefore keeps two boundaries:
+
+- **Permission decision**: a closed adapter-owned decision such as
+  `approve_once` or `reject`. Persistent authorization choices are never
+  offered. The caller never supplies terminal keys, menu indexes, or labels.
+- **Questionnaire response**: a versioned public projection containing opaque
+  question and option ids, plus typed answers. The terminal key plan and all
+  mutation authority remain owner-private.
+
+## Public model-facing contract
+
+AKK projects one currently visible interaction:
+
+```json
+{
+  "schema": "agent-knock-knock/terminal-interaction",
+  "version": 1,
+  "interaction_id": "opaque-id",
+  "turn_id": "turn-...",
+  "agent": "claude",
+  "kind": "questionnaire",
+  "state": "pending",
+  "step": { "index": 1, "total": 2 },
+  "questions": [
+    {
+      "question_id": "opaque-question-id",
+      "header": "Color",
+      "prompt": "Which color do you prefer?",
+      "required": true,
+      "response_kind": "single_select",
+      "options": [
+        { "option_id": "opaque-red-id", "label": "Red" },
+        { "option_id": "opaque-blue-id", "label": "Blue" }
+      ]
+    }
+  ],
+  "capabilities": {
+    "batch_response": false,
+    "free_text": false,
+    "multi_select": false
+  }
+}
+```
+
+The corresponding mutation accepts only the advertised semantic ids and typed
+answer shape:
+
+```json
+{
+  "interaction_id": "opaque-id",
+  "turn_id": "turn-...",
+  "answers": [
+    {
+      "question_id": "opaque-question-id",
+      "response_kind": "single_select",
+      "selected_option_ids": ["opaque-blue-id"]
+    }
+  ]
+}
+```
+
+The OpenClaw tool should be named
+`agent_knock_knock_respond_interaction`. It is deliberately separate from
+ordinary `respond({turn_id, request})`, which injects a new composer message,
+and from `approve({turn_id, decision})`, which resolves a permission prompt.
+
+The public implementation is step-oriented: one response call resolves only
+the currently projected step. The managed monitor recaptures the next native
+question, publishes a new `interaction_id`, and emits a new
+`interaction_required` callback for each supported actionable step. This makes
+multi-question and final-confirm flows explicit and avoids a blind batch of
+terminal input.
+
+The callback is a durable wake-up signal, not response authority. It contains
+only the public interaction projection and never the private prompt
+fingerprint or key plan. The owning OpenClaw conversation must call Status for
+the exact `turn_id`; displaying that fresh result creates the short-lived,
+conversation-bound private offer required by `respond_interaction`. A delayed
+or replayed callback therefore cannot authorize input by itself.
+
+## Private authority
+
+The Store may retain a private authority record binding all of the following:
+
+- exact Turn and owning OpenClaw session;
+- terminal endpoint, process incarnation, native thread, and binding
+  generation;
+- transcript/rollout source identity and bounded observation point when
+  available;
+- an exact unredacted prompt-region fingerprint;
+- the current native step and the adapter-owned semantic-id-to-input plan;
+- expiry, reservation, last proven stage, and uncertain-outcome state.
+
+None of those mutation fields are copied into the public projection. Labels
+and redacted excerpts are presentation only and never mutation authority.
+
+## Recognition and dispatch
+
+Every supported surface has a closed adapter/version profile. Detection must
+isolate one bottom-most complete prompt, prove its footer and frame, reject
+duplicate/out-of-order choices, and produce a digest before redaction.
+
+For each response AKK:
+
+1. acquires terminal, Store-writer, and Turn-state locks in canonical order;
+2. revalidates owner, Turn status, binding generation, process/native identity,
+   and the current private interaction offer; an elapsed displayed expiry
+   forces this live revalidation but does not claim the native prompt died;
+3. recaptures the screen and requires the same exact prompt fingerprint;
+4. resolves opaque semantic ids to an adapter-owned input plan;
+5. reserves the response durably before possible terminal input;
+6. dispatches one bounded native step;
+7. records an audit receipt without raw answer content and resumes the monitor;
+   and
+8. resumes the managed monitor, which recaptures the next native state, rotates
+   the interaction id when the exact prompt changes, and emits the next
+   supported-step callback. Status can always refresh the same projection
+   explicitly.
+
+If a failure occurs before terminal input, the response is safely rejected.
+If input may have occurred, the Turn becomes `response_uncertain`; AKK sends no
+automatic retry. Unknown versions, secret-input questions, ambiguous screens,
+unsupported option counts, changed prompts, or unprovable postconditions are
+`manual_required` and send zero input.
+
+## Native behavior profiles
+
+### Claude Code 2.1.263, 2.1.266, and 2.1.267
+
+Claude Code 2.1.263 was observed locally in an isolated tmux session; the
+versioned profiles retain this exact behavior contract:
+
+- single-select: digit selects and advances/submits;
+- multi-select: digits toggle checkboxes, then `Tab` advances to review;
+- Other/free text: select `Type something`, enter a single-line response below
+  Claude's 800-character paste-collapse threshold, then Enter;
+- multi-question: a tab header shows checked/unanswered sections;
+- final review: `Submit answers` / `Cancel` is a distinct confirmation step;
+- Bash permission prompt: the exact four-row form has one-time Yes as the
+  current row and `4. No`; `Escape` cancels the dialog and is not modeled as
+  semantic reject.
+
+The installed 2.1.266 binary and Anthropic's official 2.1.267 Darwin arm64
+artifact retain the same bounded questionnaire, collapsed-paste, and Status
+anchors. Each version has a distinct interaction profile so a durable offer
+cannot cross a client-version change. Claude Code 2.1.261 also introduced an
+optional `Organization policy` Status row when managed policy loading fails;
+the 2.1.263/2.1.266/2.1.267 profiles allow that exact field and redact its
+value.
+
+The initial public implementation executes exact single-select rows (including the transition into
+`Type something`), the recaptured single-line custom-text editor, and the
+separate final Submit/Cancel review. Custom text is capped at 799 characters;
+larger answers fail before dispatch reservation until the editor gains the
+same collapsed-paste proof as managed Send. It detects multi-select screens
+but keeps them `manual_required`: safely toggling several checkboxes requires
+a recapture after every toggle and is intentionally deferred. `Tab to amend`,
+persistent Yes, auto mode, resized/wrapped variants, and any changed menu shape
+also remain manual.
+
+### Codex 0.153.4, 0.154.0, and 0.155.1
+
+The installed client matches the current official TUI protocol:
+
+- `RequestUserInput` contains 1-3 questions with 2-3 options and automatic
+  Other;
+- numeric selection advances an ordinary choice question, but would bypass
+  Notes and submit the literal label for the native Other row;
+- the client-generated `None of the above` row is Codex's canonical Notes
+  carrier; when the model did not supply a `Type something.` alias, AKK derives
+  that separate semantic free-text choice beside the proven native row;
+- choosing the guarded or derived free-text choice moves to native Other with
+  bounded cursor movement and invokes Codex's native Accept action, which
+  opens Notes without submitting a literal label; choosing native Other itself
+  retains its distinct numeric direct-submit behavior;
+- the recaptured empty `Add notes` composer becomes a separate free-text
+  interaction step;
+- Codex submits that text as `user_note: ...` alongside `None of the above`;
+  it does not expose a Claude-style bare custom-answer value;
+- semantic free-text dispatch crosses the verified 121ms paste-suppression
+  window before its sole Enter;
+- the exact multi-question free-form footer is handled one current step at a
+  time;
+- unanswered-question confirmation is its own `Proceed` / `Go back` step.
+
+Codex does not currently expose a native multi-select question in this
+protocol. Any future or unrecognized shape remains manual until a new profile
+and tests are added.
+
+Codex 0.154.0 and 0.155.1 preserve those blocking `request_user_input` frames
+under separate version-bound profiles. Codex 0.154.0 also adds
+`request_user_input_async`; unlike a blocking `questionnaire`, its question is
+projected as `kind="async_question"` while the agent Turn remains `working`.
+The projection advertises semantic `delivery_modes`. A typed response defaults
+to advertised `steer_current_turn` or explicitly selects advertised `queue_next_turn`: `steer_current_turn` delivers the answer to
+the running turn, while `queue_next_turn` queues it for the next turn. Blocking
+questionnaires do not advertise and must reject that field.
+
+For async questions, the advertised native Other option opens a separate
+`free_text` step; it is not the blocking questionnaire's Notes workflow.
+An answer queued for the next turn uses the same exact question editor and
+must verify the injected answer before the final submit/queue key. If that
+editor closes or changes, input stops with an uncertain result and no retry.
+
+Collapsed async countdown redraws are not question changes: dispatch compares
+the independently parsed question, pending count, opening binding, subject and
+terminal identity, while retaining the rendered digest for evidence. A different
+question, count, input mode or binding still rejects before input.
+
+For managed user Send on profiled Codex 0.154.0/0.155.1 using Astra, animated
+empty Composer proof requires the full dim placeholder, styled marker and shared painted
+background, only the known decorated cells, and a complete supported footer.
+Activity, approval and input-owner checks run first. This proof does not grant
+native lifecycle or model-control authority. After the managed pre-text proof,
+user-explicit Send retains its one-paste/one-Enter contract without a post-text
+Composer veto.
+
+AKK still treats input ownership independently: an exact collapsed question
+summary leaves the main Composer sendable, while an expanded, clipped, or
+ambiguous async editor is a zero-input boundary so an explicit task cannot
+become a question answer. Response execution uses only semantic question and
+option identities; raw shortcut keys and menu indexes never cross the public
+contract. Codex 0.154.0 and 0.155.1 rely on exact version-bound TUI and durable
+task evidence. Notification and stable-question-identity response wrappers
+added on Codex main after 0.155.1 must not be assumed to exist in either
+release. The 0.154/0.155 active-writer `/resume` viewer is likewise read-only
+and receives no AKK terminal input.
+
+Codex 0.155.1 can also display native user-verification prompts for MCP
+requests. AKK classifies the exact prompt and waiting surfaces as blocked but
+never exposes them as approvable: completing platform user verification
+requires direct user presence and is outside terminal approval automation.
+
+## Delivery stages
+
+1. **Permission parity (implemented)**: expose `reject` only when an
+   adapter proves an exact safe native reject action; retain `approve_once`
+   compatibility.
+2. **Read-only projection (implemented)**: detect and report supported
+   questionnaire steps while changed or unsupported shapes remain manual.
+3. **Initial public response contract (implemented)**: enable one current
+   single-select, free-text, or confirmation step with pre-input fencing,
+   durable one-shot reservation, and uncertain-result audit.
+4. **Managed interaction callback (implemented)**: durably notify the owning
+   controller about each actionable current step, require a fresh Status call
+   before response, permanently fence a consumed prompt fingerprint from
+   replay, and notify the next distinct questionnaire step independently.
+5. **Expanded native coverage (not implemented)**: multi-select (tracked in
+   [#292](https://github.com/scotthuang/agent-knock-knock/issues/292)),
+   arbitrary per-option Notes, broader navigation, and more version profiles
+   only with captured fixtures and live regression evidence.
+6. **Host-native UX**: OpenClaw may render the projection using a future public
+   session-bound `requestUserInput` API. Until then, the structured AKK tool is
+   the authority boundary; a plugin must not use private Gateway methods.
+
+## Non-goals
+
+- no raw tmux keys, numeric menu indexes, or arbitrary labels in public tools;
+- no automatic permission decisions or persistent authorization grants;
+- no secret/password response relay;
+- no blind retry after possible input;
+- no attempt to emulate an arbitrary terminal UI.