@logicseek/hello-cc 1.0.1 → 1.0.2

package/docs/native.md

@@ -0,0 +1,295 @@
+# Native workers
+
+Native mode runs background workers that HCC creates and owns. HCC keeps the
+shared peer, task, message, lock, and handoff model; each provider adapter owns
+its execution connection and reports structured lifecycle events.
+
+| Provider | Connection | Session identity | Busy-worker input |
+| --- | --- | --- | --- |
+| Codex | Owned `codex app-server` over stdio JSON-RPC | Codex thread ID | Adapter supports `turn/steer` with the active turn precondition |
+| Claude | Optional Claude Agent SDK, persistent streaming input | Claude session ID confirmed by SDK initialization | One submission at a time; steering is unsupported |
+| DeepSeek Harness | Owned `dsh --profile acp` process | ACP session ID | One submission at a time; steering is unsupported |
+
+The HCC host currently dispatches one inbox message at a time to each worker,
+including for Codex. Adapter support for steering does not mean the host sends
+multiple pending inbox messages into the same turn. ACP resume and session close
+depend on the extensions the provider advertises. HCC does not claim that an ACP
+resume replays the original conversation transcript.
+
+## Requirements
+
+Use Node.js 24 or later and a provider installed and authenticated in the same
+environment as HCC. Native mode preserves authentication configuration and does
+not rewrite accounts, provider settings, or the user's home directory.
+
+Codex needs an app-server-compatible CLI. DeepSeek Harness uses its ACP profile;
+the implementation targets `@deepseek-ai/dsh-acp@0.2.0-rc.2`. This mode does not
+connect to a running dsh Web service.
+
+Claude's SDK remains optional and is loaded only when a Claude worker opens.
+For a checkout of this repository, install the documented SDK version explicitly:
+
+```sh
+npm install --no-save --package-lock=false @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+For a global HCC installation, install that version into the same npm prefix:
+
+```sh
+npm install -g @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+Alternatively, install the optional SDK in the worker's project:
+
+```sh
+cd /absolute/path/to/worker-project
+npm install --no-save --package-lock=false @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+The default loader first checks HCC's installation, then the worker project's
+node_modules, so a global HCC can use a project-local SDK. HCC never installs
+packages automatically. Missing SDKs produce installation guidance; errors from
+a found SDK's exports or dependencies retain their original cause. A separate
+real Web approval receipt (source checkout: `docs/verification/2026-10-02-native-web-claude-default-sdk.json`)
+exercises this default project lookup without injecting a query function. It
+does not verify a published package or an employee installation.
+
+## CLI
+
+Run commands from the project you want the workers to share, or select it with
+the existing global `--root` and `--db` options.
+
+```sh
+hcc native up
+hcc native start --peer codex-reviewer --provider codex
+hcc native start --peer claude-reviewer --provider claude
+hcc native start --peer dsh-reviewer --provider dsh
+hcc native send --peer codex-reviewer --from coordinator --body "Review the current changes and report concrete findings."
+hcc native status
+hcc native deliveries --peer codex-reviewer
+hcc native events --peer codex-reviewer --after 0
+hcc native requests --peer codex-reviewer
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision accept
+hcc msg inbox --peer coordinator
+```
+
+`start` starts the project's native runtime when needed. Workers share its HCC
+message bus even when `--cwd DIR` selects another working directory. `--model
+MODEL` selects a provider-supported model. `--binary PATH` overrides the Codex
+or dsh executable. Claude uses the SDK and rejects `--binary`.
+
+| Command | Options / behavior |
+| --- | --- |
+| `hcc native up` | Start or reuse the project's background runtime |
+| `hcc native status` | Inspect persisted worker state and runtime identity |
+| `hcc native start` | Required `--peer NAME --provider codex\|claude\|dsh`; optional `--cwd DIR --model MODEL --resume last`; `--binary PATH` is available only for Codex and dsh |
+| `hcc native send` | Required `--peer NAME --body TEXT`; optional `--from NAME --task ID`; returns a durable message/submission receipt |
+| `hcc native deliveries` | Optional `--peer NAME`; inspect delivery receipts |
+| `hcc native events` | Required `--peer NAME`; optional `--after ID`; inspect a bounded event history |
+| `hcc native requests` | Requires `--peer NAME`; inspect pending requests bound to this executor, session and turn |
+| `hcc native respond` | Requires `--peer NAME --request ID --decision accept\|decline\|cancel`; use `--response-file JSON` for permission subsets or answers |
+| `hcc native interrupt` | Required `--peer NAME`; optional `--turn ID`; request interruption of the active turn |
+| `hcc native close` | Required `--peer NAME`; close that worker's owned connection/process |
+| `hcc native down` | Request worker closure and runtime shutdown; returns a stop-request receipt |
+
+The `native down` receipt confirms the stop request, not completed shutdown.
+Inspect `native status` to check the outcome. If provider shutdown fails, HCC
+retains runtime ownership and reports the error in `status.shutdown_error`;
+resolve the reported problem and retry `native down`.
+
+Worker events retain semantic output and completion evidence; token deltas are
+not persisted as delivery receipts. The runtime keeps local state under
+`<project>/.hello-cc/native/` and coordination records in the selected HCC
+database. Runtime control is a local authenticated API, separate from the
+browser terminal transport. Treat its local runtime pointer and log as private
+project state.
+
+## Reading delivery receipts
+
+A successful `native send` queues a message. It does not mean the provider has
+read it, completed it, or returned a business result.
+
+| State | Meaning |
+| --- | --- |
+| `queued` | Stored on HCC's message bus, waiting for dispatch |
+| `dispatching` | HCC started handing the submission to its adapter; provider admission is still pending |
+| `submitted` | The adapter queued/wrote the prompt, without a provider admission receipt |
+| `accepted` | Provider-confirmed admission or matching provider output establishes that this submission/turn is being processed; work is still pending |
+| `completed` | An authoritative matching main-turn result reports success; HCC acknowledges the message and can write an automatic reply for a non-reply message |
+| `failed` | A definitive rejection or unsuccessful main-turn result; not a successful acknowledgement |
+| `uncertain` | A timeout, lost process/connection, or runtime restart left the outcome unknown; automatic retry could duplicate work |
+
+An SDK consuming an input iterator proves transport submission, not provider
+acceptance or a completed model turn. Claude advances from `submitted` to
+`accepted` after matching assistant output is observed. Claude reports its
+actual session ID on initialization, so a freshly
+opened worker can legitimately have a null session ID until its first prompt.
+An interrupt request does not cancel an SDK input that is still queued and does
+not itself complete a delivery. Only a matching main-turn result settles it.
+
+An inbox message with `kind: 'reply'` is still delivered as context and
+acknowledged after its main turn succeeds. Its output remains in `events`, but
+HCC does not automatically generate another reply, preventing reply loops.
+For other message kinds, a successful main turn with output writes an automatic
+reply to the sender.
+
+For an uncertain delivery, inspect `deliveries`, `events`, and provider state
+before sending a replacement. HCC leaves uncertain deliveries out of automatic
+retries. Runtime restart records in-flight work as uncertain rather than
+pretending it failed or completed.
+
+## Ownership, hooks, and permissions
+
+Resume an HCC-owned saved session with the same peer and provider:
+
+```sh
+hcc native close --peer codex-reviewer
+hcc native start --peer codex-reviewer --provider codex --resume last
+```
+
+An explicit saved ID is accepted only when it matches HCC's record for that peer
+and provider. Resume restores a conversation through a newly owned connection;
+it does not attach to an existing live TUI or desktop instance. HCC cannot prove
+that an external application has independently opened the same saved session,
+so do not open the same conversation concurrently outside the owned runtime.
+
+Native workers receive a worker-specific `HCC_ROOT`, `HCC_DB`, `HCC_PEER`, and
+`HCC_NATIVE_OWNER`. A provider hook must match the peer's native transport owner.
+Its native hook path only heartbeats that owner and renews its locks. It does
+not change provider bindings or process identity, inject another copy of the
+inbox, acknowledge messages, or block a Stop hook. Mismatched owner markers fail
+without falling back to normal terminal-hook delivery.
+
+Providers keep their permission checks. HCC-hosted workers wait for an explicit
+response from the current Web controller or the local CLI when an operation
+requires approval. Closing Web leaves both the worker and its pending requests
+available to the local CLI. Requests expire when their turn ends, interruption
+is accepted, the provider resolves them, or the worker closes. A late request
+from an interrupted turn cannot reopen approval. Direct adapters without a
+hosted responder retain conservative denial.
+
+| Provider | Hosted interaction |
+| --- | --- |
+| Codex | Command/file approval, requested filesystem/network permission subsets with explicit turn/session duration, questions including freeform/secret input, and one-call empty-form MCP tool approvals |
+| Claude | SDK tool permission callback; approval grants the original tool input once without rewriting it |
+| dsh ACP | Offered permission choices; approval selects only `allow_once`, never `allow_always` |
+
+rc.2 may send only a tool-call ID in an ACP approval request. The adapter correlates same-session/turn tool updates to show the operation input. Missing or truncated input still allows rejection; acceptance returns `NATIVE_APPROVAL_CONTEXT_MISSING`. See dsh installed acceptance (source checkout: `docs/verification/2026-10-02-dsh-cordis-native.md`).
+
+Hosted interactive Codex threads explicitly enable
+`features.default_mode_request_user_input` and `features.request_permissions_tool`
+in their private start/resume configuration. Web-owned start/resume/fork uses
+the same switches. These experimental capabilities were exercised in Codex
+0.144.6; they do not write global configuration or grant filesystem/network
+permissions. Approval remains on-request with the user as reviewer.
+Noninteractive direct adapters retain their defaults. The permission form
+shows mirrored legacy and current path entries once, preserving distinct
+access choices, original request indices and denial rules.
+
+Claude keeps `permissionMode: 'default'`; tools already permitted by that mode
+can run. Approval responses are fenced by the runtime generation, worker owner,
+provider, session, turn and request ID. Web observers cannot submit responses;
+a browser that loses control cannot answer with its old control epoch. Direct
+answers, including secrets, are omitted from HCC snapshots, events, delivery
+receipts and browser storage; form drafts remain in browser memory only.
+
+For Codex permissions/questions, use a response file. These are separate
+examples; paths, question IDs and answer labels must match the pending request:
+
+```json
+{"permissions":{"fileSystem":{"read":["/requested/read/path"]}},"scope":"turn"}
+```
+
+```json
+{"answers":{"question-id":{"answers":["An offered label or permitted freeform answer"]}}}
+```
+
+```sh
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision accept --response-file ./response.json
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision cancel
+```
+
+Only `permissions`, `scope` and `answers` are accepted in that file. Permissions
+can narrow the request but cannot add paths or network access; requested deny
+entries must be retained when granting filesystem access. Answer every question
+explicitly. Truncated requests can only be declined or cancelled. Arbitrary MCP
+forms, URL authentication, dynamic tools and account-token refresh requests are
+outside this responder's supported interaction set.
+
+## Current boundaries
+
+- Existing Codex/Claude/dsh terminal sessions remain on their original transport;
+  attaching to or taking over an existing TUI/Desktop session is not implemented.
+- Web discovers existing native workers in the same project and exposes messages,
+  delivery receipts, interruption, and explicit closure. Closing the page or Web
+  runtime preserves the independent native worker. Human responses are bound to
+  the current executor and turn. See the [Web handoff guide](web-handoff.zh-CN.md).
+- Codex, Claude and dsh native workers receive project- and peer-scoped HCC MCP
+  configuration. Writes still require provider permission and HCC ownership checks.
+- Provider-internal `SendMessage`, subagent/team discovery, and Codex delegation
+  tools are not exposed as one cross-vendor protocol. HCC routes cross-provider
+  messages through its own durable bus and adapters.
+- Task claiming, file locks, handoffs, and completion checks remain explicit HCC
+  coordination operations; successful prompt execution alone does not prove a
+  task's business acceptance.
+- Adapter tests cover protocol and interaction boundaries. The authenticated
+  checks below provide separate evidence for model execution and scoped MCP;
+  packaged-client installation and business acceptance remain unverified.
+
+
+## Authenticated acceptance on October 2, 2026
+
+Independent temporary projects and provider state directories were used for real
+model calls with Codex 0.144.6, Claude Agent SDK 0.3.287 and DSH 0.2.0-rc.2. The
+session lifecycle receipt (source checkout: `docs/verification/2026-10-02-native-live-lifecycle.json`)
+covers correlated replies and ACKs, idempotent queueing, continuing context,
+owned close/resume and active interruption. A real Codex command approval was
+declined, and its test write outside the allowed sandbox did not occur.
+
+The cross-provider receipt (source checkout: `docs/verification/2026-10-02-native-live-communication.json`)
+covers actual model calls to the scoped HCC MCP message tool along
+`Codex → Claude → dsh → Codex`, receiver model replies, reply consumption and ACK,
+and the absence of automatic reply loops. It also verifies discovery and sending
+through the Web bridge, original provider binding preservation and worker
+survival after closing that bridge. These receipts are separate source snapshots.
+
+Codex MCP tool approvals use `mcpServer/elicitation/request`. HCC submits the
+official action/content response for explicit tool confirmations without
+persisting session/always authorization. Approving arbitrary form fields or URL
+authentication is unsupported; decline and cancel remain available.
+
+The local validation receipt (source checkout: `docs/verification/2026-10-02-native-live-validation.json`)
+records the unit suite (785 passed, one platform-dependent skip), a 63-module
+static audit, the 13-stage regression and offline harness failure cleanup.
+Each check retains its own execution time and evidence digest.
+
+The opt-in `scripts/native-live-acceptance.mjs` harness defaults to help. It calls
+models and consumes the caller's provider quota only with `--run-live`:
+
+```sh
+node scripts/native-live-acceptance.mjs --run-live --provider all \
+  --codex-bin /absolute/path/to/codex \
+  --dsh-bin /absolute/path/to/dsh \
+  --claude-sdk /absolute/path/to/claude-agent-sdk/sdk.mjs \
+  --permission-probe --cross-provider \
+  --output /absolute/path/to/receipt.json
+```
+
+Use `--communication-only` for the cross-provider test alone. The explicit SDK
+entry was used for Claude acceptance; this does not prove repository-default SDK
+resolution or package installation. The script installs no dependencies, never
+attaches to existing conversations, and closes owned test processes and removes
+credential copies on exit. Web evidence covers its service/bridge control layer,
+not a full browser interaction or published-client acceptance. Real business task
+acceptance remains a separate check.
+
+
+For real model and browser interactions, use
+`scripts/web-native-interaction-acceptance.mjs`. It defaults to help; only
+`--run-live --provider codex|claude|all` invokes models. Set
+`HCC_ACCEPTANCE_PLAYWRIGHT` and optionally `HCC_ACCEPTANCE_CHROME`.
+`--claude-package DIR` links an installed SDK package into the isolated worker
+project for default resolution, without injecting its query function. The
+harness checks explicit approval and rejection and continuing the original
+session. It uses existing authentication/quota, cleans test provider homes and
+processes, and never attaches to existing user conversations.

package/docs/native.zh-CN.md

@@ -0,0 +1,253 @@
+# Native 后台 worker
+
+Native 模式运行由 HCC 创建并持有的后台 worker。共享 peer、任务、消息、锁和交接
+仍由 HCC 管理；每个 provider adapter 管理自己的执行连接，并报告结构化生命周期
+事件。
+
+| Provider | 连接方式 | 会话身份 | 忙碌时的新输入 |
+| --- | --- | --- | --- |
+| Codex | HCC 持有的 `codex app-server`，stdio JSON-RPC | Codex thread ID | adapter 支持带活动 turn 前置条件的 `turn/steer` |
+| Claude | 可选 Claude Agent SDK，持久双向输入流 | SDK 初始化确认的 Claude session ID | 一次一个 submission，暂不支持 steer |
+| DeepSeek Harness | HCC 持有的 `dsh --profile acp` 进程 | ACP session ID | 一次一个 submission，暂不支持 steer |
+
+当前 HCC host 对每个 worker 逐条投递 inbox 消息，Codex 也一样。adapter 支持 steer
+不代表 host 会把多条待处理消息塞进同一个 turn。ACP 的 resume 和 session close
+取决于 provider 声明的扩展；不能把 ACP resume 等同于重放原始会话历史。
+
+## 环境准备
+
+需要 Node.js 24 或更新版本，并在运行 HCC 的同一环境中安装、登录对应 provider。
+Native 模式保留身份认证配置，不改写账号、provider 设置或用户主目录。
+
+Codex 需要支持 app-server 的 CLI。DeepSeek Harness 使用 ACP profile，实现基线为
+`@deepseek-ai/dsh-acp@0.2.0-rc.2`；此模式不连接已有 dsh Web service。
+
+Claude SDK 保持可选，只在打开 Claude worker 时动态加载。在本仓库 checkout 中，
+手动安装文档指定版本：
+
+```sh
+npm install --no-save --package-lock=false @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+如果 HCC 通过 npm 全局安装，在同一个 npm prefix 中安装 SDK：
+
+```sh
+npm install -g @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+也可以只在 worker 的项目目录中安装 SDK：
+
+```sh
+cd /absolute/path/to/worker-project
+npm install --no-save --package-lock=false @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+默认加载器先查 HCC 安装位置，再查 worker 项目的依赖；因此全局 HCC 也可使用项目内
+安装的 SDK。HCC 不会自动安装包。找不到 SDK 时给出安装提示；SDK 已找到但导出或
+内部依赖损坏时保留真实错误，避免误报“未安装”。默认路径的真实 Web 工具审批
+已有独立回执 (源码目录: `docs/verification/2026-10-02-native-web-claude-default-sdk.json`)，不代表
+发布包或员工设备已完成安装验收。
+
+## CLI 使用
+
+在需要共享状态的项目目录中运行，或使用已有全局 `--root`、`--db` 指定项目和数据库。
+
+```sh
+hcc native up
+hcc native start --peer codex-reviewer --provider codex
+hcc native start --peer claude-reviewer --provider claude
+hcc native start --peer dsh-reviewer --provider dsh
+hcc native send --peer codex-reviewer --from coordinator --body "审查当前修改，报告具体问题和证据。"
+hcc native status
+hcc native deliveries --peer codex-reviewer
+hcc native events --peer codex-reviewer --after 0
+hcc native requests --peer codex-reviewer
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision accept
+hcc msg inbox --peer coordinator
+```
+
+`start` 会按需启动本项目的 native runtime。`--cwd DIR` 可以指定 worker 工作目录，
+它仍共享 host 所选项目的 HCC 消息总线。`--model MODEL` 选择 provider 支持的模型；
+`--binary PATH` 覆盖 Codex 或 dsh 可执行文件。Claude 使用 SDK，传入 `--binary`
+会直接报错。
+
+| 命令 | 参数与作用 |
+| --- | --- |
+| `hcc native up` | 启动或复用本项目后台 runtime |
+| `hcc native status` | 查看持久化 worker 状态和 runtime 身份 |
+| `hcc native start` | 必须 `--peer NAME --provider codex\|claude\|dsh`；可选 `--cwd DIR --model MODEL --resume last`；`--binary PATH` 仅适用于 Codex 和 dsh |
+| `hcc native send` | 必须 `--peer NAME --body TEXT`；可选 `--from NAME --task ID`；返回持久消息/submission 回执 |
+| `hcc native deliveries` | 可选 `--peer NAME`，查看投递回执 |
+| `hcc native events` | 必须 `--peer NAME`；可选 `--after ID`，查看有界事件历史 |
+| `hcc native requests` | 必须 `--peer NAME`；查看与该执行器、会话、turn 绑定的待处理请求 |
+| `hcc native respond` | 必须 `--peer NAME --request ID --decision accept\|decline\|cancel`；权限子集或问题答案通过 `--response-file JSON` 提交 |
+| `hcc native interrupt` | 必须 `--peer NAME`；可选 `--turn ID`，请求中断活动 turn |
+| `hcc native close` | 必须 `--peer NAME`，关闭该 worker 持有的连接或进程 |
+| `hcc native down` | 请求关闭 worker 和停止 runtime，返回停止请求回执 |
+
+`native down` 的回执只确认停止请求，不证明关闭已完成。需要检查 `native status`
+确认结果。若 provider 关闭失败，HCC 保留 runtime owner，并在
+`status.shutdown_error` 报告错误；处理所报问题后，再次执行 `native down`。
+
+事件保留语义输出和完成证据，不把 token delta 持久化为投递回执。runtime 状态位于
+`<project>/.hello-cc/native/`，协作记录仍写入所选 HCC 数据库。控制接口是独立于 Web
+终端传输的本地认证 API；其 runtime pointer 和日志属于项目私有状态。
+
+## 如何理解投递回执
+
+`native send` 成功只代表消息已入队，不能据此声称 provider 已读、执行完成或产出
+真实业务结果。
+
+| 状态 | 含义 |
+| --- | --- |
+| `queued` | 已写入 HCC 消息总线，等待投递 |
+| `dispatching` | HCC 开始把 submission 交给 adapter，provider admission 尚未确认 |
+| `submitted` | adapter 已把 prompt 写入或排入输入流，尚无 provider admission 回执 |
+| `accepted` | provider admission 回执或对应 provider 输出证明该 submission/turn 已开始处理，工作仍未完成 |
+| `completed` | 对应的主 turn 权威结果报告成功，HCC ACK 该消息；非 reply 消息可以自动写回回复 |
+| `failed` | 明确拒绝或不成功的主 turn 结果，不代表成功 ACK |
+| `uncertain` | 超时、进程/连接丢失或 runtime 重启后结果不明，自动重试可能重复执行 |
+
+SDK 消费输入迭代器只能证明传输提交，不代表 provider 已接受或模型 turn 已完成。
+Claude 观察到对应 assistant 输出后，才从 `submitted` 升为 `accepted`。Claude 在初始化事件
+中确认真实 session ID；刚打开 worker、尚未发送首条 prompt 时，session ID 可以为
+null。中断请求本身不会完成投递，也不一定取消还在 SDK 队列中的输入；需要对应主
+turn 结果才能归结。
+
+inbox 中 `kind: 'reply'` 的消息仍作为 context 投递，主 turn 成功后才 ACK。其输出
+保留在 `events` 中，但 HCC 不再自动生成 reply，避免回复回路。其他 kind 的消息在
+主 turn 成功且有输出时，自动向发送方写回 reply。
+
+出现 `uncertain` 时，先检查 `deliveries`、`events` 和 provider 状态，再决定是否发送
+替代消息。HCC 不自动重投 uncertain 记录；runtime 重启会把在途状态记为 uncertain，
+不会假定已经失败或完成。
+
+## 会话所有权、hooks 和权限
+
+使用同一个 peer、同一个 provider 恢复 HCC 保存的会话：
+
+```sh
+hcc native close --peer codex-reviewer
+hcc native start --peer codex-reviewer --provider codex --resume last
+```
+
+显式 session ID 也必须与 HCC 保存的该 peer/provider 记录一致。resume 通过新持有
+的连接恢复会话历史，不是附着已有的活动 TUI 或桌面实例。HCC 无法证明外部应用
+没有独立打开同一个保存会话，因此不要同时在 owned runtime 外写入该会话。
+
+worker 获得明确的 `HCC_ROOT`、`HCC_DB`、`HCC_PEER`、`HCC_NATIVE_OWNER`。provider hook
+必须匹配该 peer 的 native transport owner。native hook 路径只刷新 owner 心跳和续
+期其锁，不覆盖 provider binding 或进程身份、不再次注入 inbox、不 ACK 消息，也
+不阻塞 Stop hook。owner 标记不匹配时直接拒绝，不回退到普通终端 hook 投递。
+
+provider 保留各自的权限检查。runtime 托管的请求等待当前 Web 控制窗口或本地 CLI
+明确应答；关闭 Web 后，worker 和待处理请求仍可由本地 CLI 继续处理。应答同时
+检查 runtime generation、worker owner、provider、executor、session、turn 和 request
+ID。观察窗口不能应答，控制权切换后旧窗口的 epoch 失效。
+
+| Provider | 已接入的人工交互 |
+| --- | --- |
+| Codex | 命令/文件审批、所请求文件与网络权限的子集、明确的 turn/session 有效期、选项/自由输入/敏感问题，以及单次空表单 MCP 工具确认 |
+| Claude | SDK 工具权限 callback，批准原始输入本次执行，不改写工具参数 |
+| dsh ACP | 选择 provider 提供的 `allow_once`，不自动选择 `allow_always` |
+
+rc.2 的 ACP 审批可能只携带工具 ID。适配器会关联同一 session/turn 的工具更新以展示操作输入；等待后仍缺输入或输入被截断时可以拒绝，允许会返回 `NATIVE_APPROVAL_CONTEXT_MISSING`。实际安装与拒绝证明见 dsh 验收 (源码目录: `docs/verification/2026-10-02-dsh-cordis-native.md`)。
+
+Codex 交互会话在 thread start/resume 的私有配置中显式开启
+`features.default_mode_request_user_input` 和 `features.request_permissions_tool`，
+使执行模式下的模型能够调用提问和权限请求工具。Web 专用 App Server 的 start、resume、
+fork 也使用同一配置。它们是已验收 Codex 0.144.6 中的实验能力，不写全局配置，
+不预先授予文件或网络权限，审批仍使用 `on-request` 和用户审核。未托管且未开启
+interactive 的 adapter 保留原默认值。权限表单合并新旧协议字段中的同一路径，
+保留不同权限、原字段索引与禁止规则。
+
+turn 完成、中断成功、provider 自行解决请求或 worker 关闭时，待处理请求会失效。
+中断后的迟到请求也保持取消，直到下一轮任务开始。直接使用未托管 adapter 时仍
+保持拒绝。Claude 使用 `permissionMode: 'default'`，该模式本来允许的工具仍可执行。
+
+问题的直接答案不会写入 HCC 状态快照、事件、投递回执或浏览器存储。表单草稿仅
+存在当前页面内存，状态刷新会保留输入与焦点；页面关闭后不保留敏感答案。
+
+本地处理 Codex 权限或问题时，先用 `native requests` 读取原请求，再通过 JSON 文件
+提交。以下是两个独立示例，路径、问题 ID 和选项文本必须与原请求一致：
+
+```json
+{"permissions":{"fileSystem":{"read":["/requested/read/path"]}},"scope":"turn"}
+```
+
+```json
+{"answers":{"question-id":{"answers":["原请求中的选项或允许的自由答复"]}}}
+```
+
+```sh
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision accept --response-file ./response.json
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision cancel
+```
+
+响应文件只允许 `permissions`、`scope`、`answers`。不能添加原请求没有的路径或
+网络权限；授予文件权限时必须保留原请求的 deny 条目。所有问题都需明确回答；
+请求参数被截断时，只能拒绝或取消。动态工具与账号 token 刷新尚未接入。
+
+Codex MCP 工具审批使用 `mcpServer/elicitation/request`，与命令/文件审批的返回结构
+不同。HCC 对显式 MCP 工具确认提交单次 action/content，不写入 session/always 授权。
+任意表单字段和 URL 身份认证尚不支持批准，可明确拒绝或取消。
+
+## 当前边界
+
+- 尚未实现接管或 attach 已有 Codex/Claude/dsh TUI、桌面会话；这些会话继续使用原
+  transport。
+- Web 可发现并控制同一项目的现有 native worker，提供消息、回执、中断和明确关闭。
+  关闭页面或 Web runtime 保留独立 native worker；支持与当前执行器、turn 绑定的人工应答。
+  使用方式见 [Web 继续本地任务](web-handoff.zh-CN.md#本地-native-worker-接手)。
+- Codex、Claude 和 dsh native worker 自动获得项目与 peer 受限的 HCC MCP；
+  发信等写入仍须满足 provider 权限与 HCC 所有权检查。
+- provider 内置 `SendMessage`、subagent/team discovery、Codex delegation 工具没有
+  被暴露为统一的跨厂商协议；跨 provider 消息仍由 HCC 持久总线和 adapter 路由。
+- 任务领取、文件锁、交接、完成核验仍是显式 HCC 协作操作；一次 prompt 成功不能
+  证明任务已获业务验收。
+- adapter 和 stdio fixture 测试验证协议与交互边界；下方真实模型回执单独证明
+  模型执行和 MCP 通信。已发布客户端安装、真实业务任务验收仍需独立证据。
+
+
+## 真实模型验收（2026-10-02）
+
+已在独立临时项目、独立 provider 状态目录中，用现有认证分别完成：
+
+- Codex 0.144.6、Claude Agent SDK 0.3.287、DSH 0.2.0-rc.2 的真实消息往返、回复关联、ACK、重复 submission 去重、连续上下文、关闭后恢复，以及活跃 turn 中断。
+- Codex 实际命令审批被拒绝后，权限边界外的测试文件没有创建。
+- 模型通过受限 HCC MCP 发信的 `Codex → Claude → dsh → Codex` 三段链路：接收方模型回复、回信消费及 ACK，不生成自动回复循环。
+- Web bridge 发现真实 native worker、通过原 runtime 发信、保留原 provider binding；关闭 bridge 后 worker 继续运行。Claude 延迟初始化的恢复状态已有回归测试。
+
+会话生命周期回执 (源码目录: `docs/verification/2026-10-02-native-live-lifecycle.json`) 与
+跨 provider 通信回执 (源码目录: `docs/verification/2026-10-02-native-live-communication.json`)
+分别记录验证时间、调用数量、源码摘要、真实 session/turn 和清理结果。它们是两个
+独立快照；协议模拟测试、真实模型回执、发布安装与业务任务验收各有自己的边界。
+
+本地验证汇总 (源码目录: `docs/verification/2026-10-02-native-live-validation.json`)记录全量单测
+（785 项通过、1 项平台条件跳过）、63 个模块静态检查、13 阶段回归与脚本失败路径清理。
+这些记录保留各次执行的时间与摘要。
+
+可重复脚本为 `scripts/native-live-acceptance.mjs`。默认只显示帮助，不调用模型；
+显式加 `--run-live` 后才使用现有认证，测试过程会调用模型并消耗相应额度：
+
+```sh
+node scripts/native-live-acceptance.mjs --run-live --provider all \
+  --codex-bin /absolute/path/to/codex \
+  --dsh-bin /absolute/path/to/dsh \
+  --claude-sdk /absolute/path/to/claude-agent-sdk/sdk.mjs \
+  --permission-probe --cross-provider \
+  --output /absolute/path/to/receipt.json
+```
+
+仅测试跨 provider 通信可加 `--communication-only`。Claude SDK 路径用于显式加载
+已安装的独立 SDK；本次真实验收用了此注入路径，没有代替默认安装位置的验收。
+脚本不安装依赖、不接管现有会话；结束时关闭测试进程并移除测试凭据副本。
+Web 验证覆盖服务与 bridge 控制接口，尚不等于完整浏览器操作或已发布客户端验收。
+
+
+真实模型与浏览器人工交互可使用 `scripts/web-native-interaction-acceptance.mjs`。
+默认只显示帮助；`--run-live --provider codex|claude|all` 才调用模型。
+设置 `HCC_ACCEPTANCE_PLAYWRIGHT`，以及按需设置 `HCC_ACCEPTANCE_CHROME`。
+`--claude-package DIR` 可将已经安装的 SDK 包链接到隔离 worker 项目，由默认加载器
+解析，不注入 query 函数。脚本验证明确批准与拒绝、原会话续接，退出后关闭测试
+进程并清理临时 provider home；使用现有认证和调用额度。它不连接现有用户会话。

package/docs/web-handoff.zh-CN.md

@@ -0,0 +1,53 @@
+# Web 继续本地任务
+
+项目仍以 CLI/tmux 作为默认接入。它适合继续已经托管的本地 Codex/Claude/shell：Web 打开同一个 pane，不另起执行器。
+
+运行 `hcc web` 后选择已有会话。选中项和未发送草稿按项目保存于当前浏览器；刷新会恢复原位置。第一个 Web 连接取得控制，其他窗口可观察，点击“接管浏览器控制”后才可写入。服务端检查控制 epoch，旧窗口不能继续输入、改变终端尺寸、修改该 peer 或处理审批。本地 tmux client 仍可直接输入，Web 会显示其连接状态。
+
+终端草稿“发送 + Enter”收到回执，只代表运行时已接受字节。若连接中断或没有回执，草稿保留且不自动重发；先核对终端再决定是否补发。浏览器存储不可用时退回内存，关闭浏览器后未必保留。
+
+关闭页面或“释放控制”不会终止本地执行器。“暂停 Web 接管”使 tmux 保持运行，并保存暂停状态，自动发现和 runtime 重启不会立即重新接入。需要恢复时显式连接已有终端，例如 `hcc peer attach codex-a --pane %1`。暂停不是释放 task owner 或项目锁。选择终止 tmux 的复选框才会同时结束它；PTY 和 App Server 的“终止执行器”会结束对应子进程。
+
+## Codex 结构化界面
+
+新建会话时选择 Codex，再把“Codex 接入方式”切换为“结构化 App Server（显式启用）”。需要本地已安装且支持 App Server 的 `codex`，登录和模型环境来自启动 hello-cc 的进程。hello-cc 不自动登录、不更改信任配置、不探测未公开的 TUI 内部 endpoint。
+
+可先运行 `hcc doctor --codex --json` 查看只读诊断。它分别报告已安装版本、CLI help 声明的 App Server 启动参数、hooks 配置与项目中的 hook 调用记录；这些事实不等于完整 RPC 能力、hooks 已受信任、stdout 投递成功或模型已接收。版本/help 探测使用独立临时 HOME/CODEX_HOME 并清理，防止 Codex 启动文件触碰用户目录；hooks 配置仍从原路径只读检查。没有充分回执的状态显示 `unknown`，不会自动触发 hook 或修改 trust。普通 `hcc doctor` 仍只检查数据库。
+
+结构化界面提供消息、当前 turn 状态、追加指令、轮次中断、计划、差异和人工交互。命令/文件审批以及空表单 MCP 工具确认由当前控制窗口明确批准本次或拒绝。文件与网络权限可逐项勾选，并明确选择本轮或会话有效期；只能授予原请求的子集。问题支持选项、其他/自由输入和敏感答案，需逐题明确填写。接管控制本身不会批准工具。
+
+表单输入与焦点会跨状态刷新保留，直接答案不写入 HCC 状态、事件、回执或浏览器存储。原 turn 完成、中断成功、provider 解决请求或执行器关闭后，请求卡片失效；旧控制窗口不能用过期 epoch 应答。参数被截断时只能拒绝或取消。任意 MCP 表单字段、URL 登录、动态工具及账号 token 刷新尚未接入。
+
+运行中发消息使用 steer；空闲时开始新 turn。中断当前轮与终止执行器是不同操作。turn 完成不自动把 hcc task 标记为验收完成。
+
+要恢复一个旧 Codex thread，先停止旧执行器，选择 resume 并填写真实 thread ID，再勾选交接确认。后端仍会验证旧 owner 状态；活跃或证据不明时拒绝恢复。不能把它当作正在运行的 CLI 任务无缝迁移。原 thread 已绑定 hcc peer 时，保留原 peer/task 身份；正在运行的命令和未持久化事件不会迁移。
+
+提交先持久记录 submission ID。重复 ID、断线和超时不会触发自动重发。若读取历史仍不能明确确认接收结果，界面阻止新 turn；停止旧执行器后再恢复保存的 thread。历史清理保留用于去重的最小提交记录。
+
+关闭浏览器后 App Server 仍由 hello-cc runtime 管理；停止 runtime 会关闭它。新 runtime 不会自动重启 App Server 或重放未确认消息，可以从已保存 thread 显式恢复。
+
+## 本地 native worker 接手
+
+先用 `hcc native start --peer codex-worker --provider codex` 启动后台任务，再打开 Web 的同一项目。Web 自动发现实际仍由 native runtime 持有的 worker，显示其原 peer/session、事件和投递回执；发送、中断和明确关闭都通过原 runtime 执行，不新建 provider 子进程。Claude/dsh worker 也走这条路径，按实际能力显示中断操作。
+
+发送成功先显示队列回执；执行器接收、运行和完成分别使用实际投递状态。断线或不确定结果保留 submission ID，刷新不会重放消息。native runtime 重启或 worker 被替换时，旧 Web 视图及其控制凭证失效，重新发现当前 worker 后才能操作。
+
+关页面或停止 Web runtime 不会停止独立 native runtime/worker。界面的“终止执行器”才会明确关闭该 worker。Codex native worker 提供同一套权限与问题表单，并在会话内显式启用相应的实验工具开关；Claude 通过 SDK 工具 callback 批准原始输入本次执行，dsh ACP 只选择 provider 提供的 allow_once。所有请求均绑定当前执行器/session/turn，不自动批准。
+
+回到本地后，用 `hcc native requests --peer codex-worker` 查看待处理请求，再用 `hcc native respond --peer codex-worker --request REQUEST_ID --decision accept|decline|cancel` 应答。权限或问题答复通过 `--response-file JSON` 提交，格式见 [Native 指南](native.zh-CN.md#会话所有权hooks-和权限)。
+
+## 历史、协作工具与结果审阅
+
+项目栏“Codex 历史”可分页浏览当前项目已保存的 thread，读取上下文，再显式恢复或分叉。恢复仍要求旧执行器已确认停止；分叉生成新的 thread/peer，原任务 owner 不变。有正在托管的源会话时，分叉也必须取得该会话的浏览器控制。历史读取不会启动模型 turn。
+
+Web 专用 Codex App Server，以及由 HCC 托管的 Codex/Claude/dsh native worker，自动接入 [项目与 peer 受限的 MCP 协作工具](mcp.zh-CN.md)。配置只传给对应执行器或 worker，不写全局 provider 配置；关闭 worker 前撤销其临时权限。模型可查询任务与 inbox、领取任务、发送消息、写 handoff、获取/释放自己的资源锁和记录本地证据；不替用户执行发布或业务验收。
+
+会话栏“结果审阅”汇总结构化 command 的退出码与输出、turn 差异、模型通过 MCP 提交的本地证据，以及人工添加的验收记录。命令退出成功仅说明该命令成功；人工填写“通过”必须附证据引用。界面分别展示本地验证、发布部署、业务验收，并注明记录来源。turn 完成、测试记录或人工验收均不自动改变 hcc task 状态。记录保存于项目数据库 events 中，`gc --history` 保留结果审计记录和最小提交去重凭据。
+
+## 验收边界
+
+本地验证包含真实 SQLite/HTTP、模拟交互请求、隔离 tmux 与桌面/手机浏览器。安装版 Codex 0.144.6 的协议验收另行覆盖 initialize、thread/start/list、10 个 MCP 工具发现和实际 `hcc_state` 读回；此协议检查不调用模型，可用 `node scripts/web-handoff-installed-acceptance.mjs` 重现。
+
+真实模型验收已在隔离项目和 Codex home 中完成“本地 → Web → 本地”三段文件任务，全程保持原 Codex 进程和 thread；关闭 Web runtime 后仍可继续。可用 `scripts/web-native-model-acceptance.mjs` 在明确需要真实模型调用时重现。三种 provider 的真实生命周期、模型 MCP 发信、回复/ACK 和无回复循环另有独立回执。交互表单另有 11 项模拟 provider 浏览器检查。真实 Codex 已经完成“提问 → Web 答复 → 指定文件权限 → 本轮授权 → 写入所选答案 → 后续请求拒绝 → 本地继续”的验收；默认加载的 Claude SDK 已完成真实 Write 工具批准、拒绝和本地续接。dsh 的真实权限弹窗尚无本轮浏览器验收。完整结果与运行条件见 本地验收记录 (源码目录: `docs/verification/2026-10-02-web-local-task-handoff.md`)。
+
+任意未托管 TUI/普通终端的活动执行器迁移、私有 daemon endpoint、任意协议版本的完整兼容矩阵，以及发布安装和真实业务验收仍在本次证据范围之外。