@khorsheed/dsh-local-agent-claude-code 0.2.0-rc.3 → 0.2.0

package/CHANGELOG.md

@@ -1,8 +1,24 @@
 # 变更记录
+## 0.2.0（2026-10-26）
+
+rc.3 之后到正式版的变化：
+
+- **一次 API 调用就是一条请求、用量只算一次**：Claude 对一条消息的每个内容块各发一个事件并重复带同一份用量，子会话镜像原来把一次调用拆成好几条、每条都显示同样的数字；现在按消息 id 合成一步，用量挂在这次调用的最后一行，且每次调用都带自己的用量（原来只有整轮最后一条有）。live 路等调用结束（`message_delta`）后才落盘，用最终用量，跨工具结果的调用也不再重复计数。Context Lens 里每次请求的 token 因此准确。
+- **修复工具发现循环在子会话里显示不全**：`ToolSearch` 的结果原来接不上，收尾时多出一个假的「已中断」占位，整轮写入还挤在结尾一次落盘；现在如实折叠。
+- **修复子会话步骤乱序、重启后被判损坏**：live 镜像改为写入时才编号、一次只开一个步骤，先开始的先落盘。
+- **修复取消后日志不可读**：取消后迟到的 CLI 中断提示不再写到这一轮结束之后。
+- CLI 注入的文本（技能正文、命令输出）不再被当成回答镜像出来。
+- 协作间的桥接调用最长可等 30 分钟（`MCP_TOOL_TIMEOUT`），供成员等你回答问题。
+- **README 重写**：改为大白话说明，完整参考移到 `docs/`。
+- **版本号去掉 rc**:社区包不再发 prerelease 版本(docs/publishing.md「版本号规则」),家族各包同版 0.2.0;本节原记为 0.2.0-rc.4。
+- **缓存命中 0 与未上报可区分**：用量带任一缓存字段时 `cacheReadTokens` 恒写（读到 0 就写 0)——读日志的一方（Context Lens）不再分不清「命中 0」与「没上报」。
+- **子会话日志写入 `request/header`**：子会话的配置事实（模型 + 推理强度）原来无处记录，Context Lens 整卡「未记录」。现在每轮写入宿主原生 `request/header`（只在变化时记录）——exec 路用 init 事件的观测 model（回退到启动参数）,live 路用会话配置；claude 的 wire 从不携带 effort,provider 自己设置的 env 参数即权威来源。
+- **修复成员推理强度整体不可用**：端点目录的 effort 解析只读模型条目的顶层 `effort` 字段，而端点把它嵌在 `capabilities.effort` 下（openproxy 中继 2026-10-22 实测形状；官方 API 同形）——目录条目自此重新带上推理档位，成员对话框的推理强度恢复可选（两个字段位置都认，顶层优先）。
+- **成员会话的模型对话框与「可用模型」短名单严格一致**：成员的模型目录原来会混入配置与历史附加项，与卡片短名单不一致。现在成员对话框的候选即短名单（按名单顺序），名单外只保留成员当前绑定的模型（避免既有绑定显示空白）；卡片的添加对话框只列端点真实供应的模型，配置/历史附加项不再混入。
 
 ## 0.2.0-rc.3（2026-10-22）
 
-（版本号说明：家族的 dsh-headless 包 0.2.0-rc.2 曾被发布后又撤回，npm 永久烧掉该版本号；为守住家族「同一版本线」纪律（check:release-groups），本波家族整体上移 rc.3，内容即 rc.2 计划稿。）
+（版本号说明：家族的 dsh-headless 包 0.2.0-rc.2 版本号已被 npm 发布流水线占用（重复利用被 409 拒绝：「Cannot stage previously published version」——曾发布后被撤回或曾被暂存，外部无法区分，结果相同：该号不可复用）；为守住家族「同一版本线」纪律（check:release-groups），本波家族整体上移 rc.3，内容即 rc.2 计划稿。）
 
 - **BREAKING：OAuth 网页授权整体移除，端点凭据成为唯一认证方式**。部署级凭据为插件配置 `baseUrl` / `apiKey` / `authToken` 三元组（`apiKey` 以 `ANTHROPIC_API_KEY`、`authToken` 以 `ANTHROPIC_AUTH_TOKEN` 发出，中转的两种认法都兼容）；每个作用域可再以 `<作用域目录>/endpoint-auth.json`（0600）按字段覆盖——优先级就是「scope 文件 > profile 配置」。**升级前必须配好端点凭据**，否则升级后读作未认证（README 带迁移说明）；官方订阅（Pro/Max）的 OAuth 路径随之消失，失效 OAuth 残留由 provision 启动时清扫，换 key 下一轮生效、无需重载。
 - **设置卡新增端点凭据表单与「验证端点并获取模型」按钮**：卡片编辑的正是默认 scope 的 endpoint-auth.json；验证即带解析出的凭据探测 `GET <baseUrl>/v1/models`，保存成功翻转认证状态点。凭据等级语义不变：key 在场读 present-unverified，跑通一轮升 verified，一轮 401 打 rejected，重写凭据文件即恢复手势。

package/README.en.md

@@ -2,134 +2,46 @@
 
 English | [中文](README.md)
 
-Delegate coding tasks to the Claude Code on this machine — thinking, tool calls, and replies stream back live, and your personal `~/.claude` is never touched.
+Hand coding tasks to the Claude Code on your machine: its thinking, tool calls, and replies stream back live, and you can keep the conversation going.
 
-Any dsh agent preset that names this package's `./tool` composition entry (e.g. dev mode) can delegate: the child session is visible end to end — abortable, resumable — and every round's accounting (the actual model, token usage, tool-call count) reads back for real. Authentication is endpoint-key based (`baseUrl` + `apiKey`/`authToken`), scope-isolated: the plugin only ever manages the one directory `$DSH_HOME/local-agent/claude-code`, so your personal installation and credentials stay out of it from start to finish. There is no OAuth web flow: a container round uses the same credential as a host round, with nothing to authorize inside the container. The Claude Code harness of the [local-agent family](../local-agent/README.md).
+Getting Claude Code to help used to mean opening a terminal, pasting things in, and carrying the result back yourself. With this plugin you say "give this to Claude Code" in a session, and the agent hands the task to Claude Code on your machine. Its thinking, tool calls, and replies show up live in a sub-session, and the result comes back to you. The tokens each call used and the model that actually ran are recorded as real numbers. Claude Code runs in its own separate folder; your existing `~/.claude` config and sign-in are never touched.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/08-local-agent.png" width="640" alt="the Local Agent family cards under Settings → Plugins → plugin configuration, the Claude Code row's status dot showing its auth state">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/local-agent-claude.png" width="560" alt="The expanded Claude Code section: Claude Code signed in with its version, endpoint, API key, Auth Token and the available-models list">
 
-## Features
+## What it does
 
-- **Per-session delegation grant** — the `subagent_claude_code` tool is this package's `./tool` composition entry, granted to the sessions of an agent preset that names it; no per-preset variants.
-- **Scoped home** — every Claude process runs with `CLAUDE_CONFIG_DIR` under `$DSH_HOME/local-agent/claude-code`; your personal `~/.claude` stays out of it.
-- **Endpoint credentials, no web authorization** — configure `baseUrl` + `apiKey` (or `authToken`) on the bundle row and the harness is authenticated; the status panel reads authenticated immediately. Each named scope can override the deployment defaults with its own `endpoint-auth.json`. `sessions`/`status`/`logout` and a Settings → 本地 Agent panel complete the family.
-- **Resume a delegation** — pass back the result's `resume` handle to continue the same Claude session, with per-round accounting.
-- **Live stream mirror** — the child session mirrors Claude's thinking, tool calls, and replies live; aborting keeps the partial transcript and real token usage.
-- **Model readback and per-cell working directory** — every settled round reads back the model from stream-json's system/init into the delegation record; orchestrators pass a `cwd` per cell, and a resume in a different directory is rejected.
-
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/local-agent-claude-code-card.png" width="640" alt="the expanded Local Agent · Claude Code settings card: the authentication block, the default-model picker, and the resident-mode (live) switch">
+- **Hand it off in one sentence**: tell the agent which part goes to Claude Code; it writes up the brief, and the result comes back to your session.
+- **Streams back live**: thinking, tool calls, and replies appear in the sub-session as they happen; stop midway and the finished part and its usage are kept.
+- **Clear accounting**: each call's usage is recorded on its own in the sub-session, so Context Lens shows where every call's tokens went.
+- **Keep talking, no cold start**: have the agent follow up, or open the sub-session and message it yourself; it's the same Claude Code session.
+- **Paste a key and go**: enter the endpoint and API key (or Auth Token) on the settings card, press "Save credential", then "Verify endpoint & fetch models" to check it connects.
+- **Pick your models**: under "Available models", tick and drag to reorder; the top one is the default. You can also switch model and reasoning effort inside a sub-session.
+- **Resident mode is faster**: turn on "Resident mode (live)" and the Claude Code process stays up; stopping doesn't kill it, and after a crash it resumes the same session.
 
 ## Install
 
-Prerequisites: a running dsh profile, and the Claude Code CLI (`claude`) on `PATH` — the plugin does not install it. Install the family core together with this bundle (`dsh plugin add` reconciles only *direct* dependencies, so name both):
+First install the Claude Code CLI yourself (`claude` runs in your terminal); the plugin doesn't install it. Then in DSH, open Plugins → Add plugin, enter this package name, and press Install:
 
-```sh
-dsh plugin --profile web add @khorsheed/dsh-local-agent @khorsheed/dsh-local-agent-claude-code
 ```
-
-After restarting the web instance, open this package's card under Settings → Plugins and fill in the endpoint and a key in the Authentication block (or preconfigure them on this package's profile row); with neither, the status reads not authenticated. Uninstall:
-
-```sh
-dsh plugin --profile web remove @khorsheed/dsh-local-agent-claude-code
+@khorsheed/dsh-bundle-local-agent
 ```
 
-The scoped home is kept on uninstall — the `endpoint-auth.json` and the session records live there; delete `$DSH_HOME/local-agent/claude-code` to remove every trace.
-
-## Config
-
-Optional fields on the bundle row:
-
-- `permissionMode` — `skip` (default) passes `--dangerously-skip-permissions` so the child can write files without an approval prompt; `normal` runs without it, so approval-requiring actions (e.g. writing files) are denied.
-- `model` — every delegation round starts the CLI with it (`claude -p --model <model>`); absent passes no model flag at all. See below.
-- `baseUrl` — the deployment-level endpoint, sent to the child CLI as `ANTHROPIC_BASE_URL` (e.g. a relay such as `https://openproxy.to/claude`, or a self-hosted router); absent means Anthropic's own endpoint. A same-named variable exported in the host shell is NEVER read — the child environment is scrubbed on principle, and routing is decided by the config and the scope file alone. **Editable right on the settings card's Authentication block** — the card saves the default scope's `endpoint-auth.json` (mode 0600, local only, outranking this config row), and no key ever lands in the profile document.
-- `apiKey` — the deployment-level credential, sent as `ANTHROPIC_API_KEY` (the `x-api-key` header). Writable from the settings card (stored in the scope file, never echoed back); in a profile, keep it local and never commit it.
-- `authToken` — the other credential shape, sent as `ANTHROPIC_AUTH_TOKEN` (the `Authorization: Bearer` header) — some relays accept only Bearer. When both keys are set, the CLI's own precedence applies. Also card-editable.
-- `proxyUrl` — an HTTP proxy for the child CLI's own traffic, provisioned into the scoped `settings.json` env block; for when the host process environment carries no proxy (a supervisor-spawned instance does not inherit your shell exports). It is a local traffic forwarder — a different layer from `baseUrl`'s endpoint routing.
-- `live` — live driver: one resident stream-json process per member (`--input-format stream-json`), one stdin message per round (runtime-level graceful control interrupt, same-shape push stream); off — or a channel that cannot come up — means the one-shot `claude -p` path.
-- `liveIdleMs` — idle lifetime of a resident runtime before reclaim (default 30 min).
-
-> **Migration note (next release line — breaking)** — the OAuth web flow is removed wholesale: `/claude-code login` no longer exists, and the keychain/`.credentials.json` reconcile is gone with it; the first boot after the upgrade sweeps the scoped home's leftover OAuth artifacts (`.credentials.json` and the `.claude.json` `oauthAccount` marker) — measured, claude 2.1.296 prefers the environment credential over a stored one anyway. Configure `baseUrl` + `apiKey` on the settings card or the profile row BEFORE upgrading (an official console key against the default endpoint works too), or the upgraded instance reads unauthenticated. The old `liveMirrorGranularity: event | token` key is still accepted for existing profiles but ignored.
-
-> **Per-scope override** — `<scopedHome>/endpoint-auth.json` (mode 0600) overrides field by field, two layers: **the scope file > the profile's YAML row**, an absent field falling back to the config value. A file naming only `apiKey` is exactly "rotate this scope's key". The settings card's Authentication block edits exactly this file for the default scope (through the family gateway's `endpointAuth`/`configureEndpoint` Remotes — readable and writable with no session present). `/claude-code logout` clears the same file; when the credential comes from the config row alone, logout refuses and names the profile as the place to edit.
-
-### Available models (models.json)
-
-The settings card's "Available models" block maintains an **ordered model shortlist**: "Add model" checks entries off the endpoint's served catalog (`GET /v1/models`), so the list can only hold what the endpoint actually serves; drag rows to reorder. **The first entry is the default model** — every delegation round starts the CLI with it (`claude -p --model <model>`, the same flag in resident mode), outranked only by a member's session-level override and a delegation's own model. The list persists in the scoped home's `models.json` (each named scope can carry its own — the same file mechanism as the endpoint credential), saves on every edit, and applies to the next delegation round.
+Claude Code comes with the 「多Agent协作」 (multi-agent) suite; all the local agents share one core, so on its own it won't work. If you mostly write code, the Dev Suite `@khorsheed/dsh-dev-suite` includes it too. Restart DSH, then on the Plugins page open the 「本机 Agent 委派」 (Local Agent Delegation) card, expand the Claude Code section, and fill in the endpoint and key.
 
-**Empty = the previous behavior.** With an empty list the model is decided by the pre-list chain: the plugin-config/settings `model` key → the scoped `settings.json`'s `model` → the CLI's built-in default (the plugin never guesses what it is). One-shot (exec) rounds never rewrite the scoped `settings.json`; a resident (live) spawn scratches the effective model into that file (a `--resume` reattach honors the file's model over the `--model` flag) and restores the previous value before a spawn that binds none.
+Handing work to Claude Code happens in a mode that grants delegation, such as "开发模式" (dev mode): start a new session, pick that mode, and tell the agent "give this to Claude Code". Not seeing it in other modes is expected.
 
-The **evaluation snapshot (`effectiveSettings`)** reads the model down the same chain: the list's first entry → the `model` key → the scoped file; the list itself never enters the snapshot (it is a preference, not a fairness knob) — the round's `observedModel` read-back is the evidence. Change the list mid-run and the next round's read-back sees declared ≠ observed and fails the run as misattributed (frozen decision 5).
+## Known limitations
 
-**A delegation's own model outranks this key.** An orchestrator may name the model for ONE delegation through the facade's `DelegationCallOptions.model`, which sits above this key (the layer order is in the family core README). The first round's request is recorded and every resume round re-requests it — `resume` takes no model of its own. In resident mode a fresh delegation's model binds as the member's start model at the runtime's spawn: a runtime bound to a different model retires first, and the same CLI session resumes on the new process.
-
-**Session-level member switching.** The member composer's model picker writes a **session-level override** through the family gateway's `setMemberModel` — it outranks the delegation model and this key, lives in memory only, and deliberately neither survives a host restart nor enters the settings. A switch is refused while the member has a round in flight; with the live driver on, switching to a different model retires the member's resident runtime so the next round respawns onto the new model while resuming the SAME CLI session (the conversation carries over), and a same-model switch is a no-op.
-
-**This is not an evaluation gap.** A run freezes its condition at setup: change the key mid-run and the next round's model read-back sees declared ≠ observed and fails the run as misattributed (frozen decision 5). "A new run follows the new value, a running one is never switched underneath you" is the design, not an oversight.
-
-The model surface now lists **what the endpoint actually serves** (`GET <baseUrl>/v1/models` with the saved credential): the picker shows exactly what the endpoint can run, an invalid credential shows an empty list with the reason — a locally-known CLI vocabulary can never mask a dead key. The directory shares the core cache and refresh subscription; an endpoint or credential change re-probes (a rotation rides a short digest in the cache key, never the key itself), and a transport failure keeps the last good data and retries on schedule. Served effort capabilities become selectable levels. An off-list model id can still be typed by hand. The settings card's "verify endpoint & fetch models" button is the explicit form of the same probe (a session-less Remote, disabled while drafts are unsaved). Busy selections apply at the next complete turn boundary, including tool continuations; core owns current/pending state, cancellation and retry, while frozen evaluation members reject changes.
-
-**A delegation's own model outranks this key.** An orchestrator may name the model for ONE delegation through the facade's `DelegationCallOptions.model`, which sits above this key (the layer order is in the family core README). The first round's request is recorded and every resume round re-requests it — `resume` takes no model of its own. In resident mode a fresh delegation's model binds as the member's start model at the runtime's spawn: a runtime bound to a different model retires first, and the same CLI session resumes on the new process.
-
-**Session-level member switching.** The member composer's model picker writes a **session-level override** through the family gateway's `setMemberModel` — it outranks the delegation model and this key, lives in memory only, and deliberately neither survives a host restart nor enters the settings. A switch is refused while the member has a round in flight; with the live driver on, switching to a different model retires the member's resident runtime so the next round respawns onto the new model while resuming the SAME CLI session (the conversation carries over), and a same-model switch is a no-op.
-
-**This is not an evaluation gap.** A run freezes its condition at setup: change the key mid-run and the next round's model read-back sees declared ≠ observed and fails the run as misattributed (frozen decision 5). "A new run follows the new value, a running one is never switched underneath you" is the design, not an oversight.
-
-⚠️ `skip` has no OS-level sandbox — the child can write anywhere the host user can, including outside the workspace — and the endpoint credential is sent to whatever `baseUrl` points at. Prefer `normal` when a delegation needs confinement; point `baseUrl` only at endpoints you trust.
-
-**Evaluation snapshot (`effectiveSettings`).** The harness declares a live-read snapshot of its fairness-relevant settings for the evaluation condition hash: drive (exec/live), the permission mode (`skip`/`normal`, plugin config), whether a non-default endpoint is in force (following the provider's own resolution — the scope's `endpoint-auth.json` overrides the plugin config field by field; hostname only — key material never enters the snapshot, and the file's name matches the evaluation contract hash's credential denylist, so not even its digest enters a condition fingerprint), and the configured model (the plugin config's `model` key first — it overrules the file on every argv — then the scoped `settings.json`'s `model`; the CLI's own default model stays the CLI's business and is never guessed — neither key, no field), and the CLI version (`claude --version`, cached against the executable's path + mtime; absent when the CLI cannot be asked). `/claude-code status` and the `LocalAgentStatus` Remote attach the same snapshot.
+- Only an endpoint plus key is supported; there is no web sign-in.
+- With a wrong key, Claude Code keeps retrying first (about 8 minutes in testing) before it fails, and the card shows the credential as rejected only after that round ends.
+- The `/claude-code` commands only work in web sessions.
 
 ## Compatibility
 
-- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): ✅ public API compatible. Live generation uses the local-agent transient Remote and public Conversation nodes; incremental durable recovery checkpoints handle persistence, and native final messages retain transcript and usage semantics. Browser P95 acceptance is tracked by the room coordinator proposal. minHost is 0.1.5-rc.1 — older hosts stay on the previous release line. The settings card renders as a section of the core's「Local Agent Delegation」family card (the core's `plugins.item` entry on the Plugins page, 0.1.7-alpha.1+; on an older core this package falls back to its own `plugins.item` card), mounted through `configForms.whileServed` while the Host serves the `local-agent-claude-code` namespace; 0.1.5 renders no card (the host removed the `settings.plugin.item` seat) — every other surface is unchanged.
-- source line (deepseek-harness master): ✅ (verifiedHost: 0.2.1-rc.1) — host-021 wave: full build+test green against the 0.2.1-rc.1 tree; delegation moved to `ctx.subagents.startActivation` (managed activation), and run.id is now unique per execution.
-
-## Known Limitations
-
-- **Logout clears only the scope's own file** — a deployment-level credential from the plugin config is unaffected; edit the profile row to change it.
-- **A bad credential costs the retry budget** — a dead key makes the CLI retry up to its limit (measured ≈8 minutes) before the 401 surfaces; the status's `rejected` grade appears when that round settles.
-- **Interactive-session records may be missing** — under a custom `CLAUDE_CONFIG_DIR` the CLI may not write transcripts (upstream behavior).
-- **Headless caveat** — `/claude-code` commands need a Web session; `--profile headless` delegates through a composition that mounts the tool row.
-
-## How it works
-
-<details>
-<summary>Internals (click to expand)</summary>
-
-**Model readback and the cwd override.** After every settled round the provider reports the actual model from the stream-json `system` (init) event's `model` field (e.g. `claude-opus-5[1m]`, verbatim — context-variant suffixes included) through the `settled` run-progress event, and merges it into the delegation record's `observedModel` field; absence is recorded, never guessed. When no layer and no record names a model, the 默认 surface's last-observed hint reads the member's OWN transcript (`projects/<cwd-slug>/<sessionId>.jsonl`, or the tree's newest for the memberless card) — the history backstop for rounds that predate the settle channel; read-only, never a write into `delegations.jsonl`. An orchestrator may also pass a per-round working directory through the facade's `DelegationCallOptions.cwd` (recorded as the record's `cwd`); when a resume round resolves to a different directory than the recorded first round, it fails loud before any process spawns — a CLI session continues in the directory its first round ran in.
-
-**Tool-call accounting.** Every settled round also reports how many tool calls it made, on the `settled` run-progress event (`toolCalls: { count, byName }`). The count is taken in the `tool_use` branch the stream fold ALREADY walks, and `byName` keys are the block's own `name` (`Bash`, `Read`, `TodoWrite`, or an MCP tool's full `mcp__server__tool`), carried verbatim and never normalized across harnesses. `TodoWrite` counts too: the fold diverts it into the todo snapshot instead of the transcript, but the CLI still called it. One accounting per round, never cumulative; a round that called nothing carries no field at all (absent is not zero). Measured: a "read two files, then list the directory" round reads back `{count: 3, byName: {Read: 2, Bash: 1}}`, matching the mirrored tool cards one for one.
-
-**The endpoint credential model.** Authentication has exactly one form: `endpoint-auth.ts` merges the scope's `endpoint-auth.json` field by field over the plugin config triple (`baseUrl`/`apiKey`/`authToken`), and the provider, the live driver and the model catalog resolve and inject it (`ANTHROPIC_BASE_URL`/`ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN`) at every spawn — a key rotation takes effect on the next round, no reload. The settings card's credential form reads and writes the default scope's file through the family gateway's `endpointAuth`/`configureEndpoint` Remotes — a session-less channel where keys are neither echoed nor ever written into the profile patch document. Measured: claude 2.1.296 in a brand-new scoped home runs `claude -p` on these variables alone — the CLI scaffolds `.claude.json` itself, and headless mode has no onboarding or key-approval gate; with a stale OAuth grant sitting alongside, the environment credential wins just the same (provisioning still sweeps those leftovers on the first boot after an upgrade). The auth probe is a light file-plus-config check (a non-empty key is authenticated), and the CLI is never spawned just to probe; the `endpoint-auth.json` mtime serves as the credential stamp — a round's 401 grades the credential `rejected`, and rewriting the file (rotating the key) recovers it, one-to-one with the OAuth era's "a fresh login rewrites the marker".
-
-**Named scopes.** Each named scope opens another `CLAUDE_CONFIG_DIR` at `<homesRoot>/claude-code@<name>`: its own `endpoint-auth.json`, its own session records, its own credential grade. A scope without a file follows the deployment config — which is exactly how one configuration serves every scope. A scoped delegation runs `claude -p` against that directory and reads back from it; exec-only.
-
-**Container delegation.** An orchestrator may run the round inside an **already-acquired container** through the facade's `DelegationCallOptions.exec` (`{ container, workdir, env? }`): the argv becomes `docker exec -w <workdir> [-e NAME…] <container> claude -p …` and everything else (stream-json parse, settle, recording) is byte-for-byte unchanged. `env` must name the in-container `CLAUDE_CONFIG_DIR`, and the caller bind-mounts the host scoped home read-write onto that path. The endpoint credential crosses into the unit through the family's container forwarding: the provider's resolved `ANTHROPIC_*` variables ride NAME-ONLY `-e` flags whose values the docker client's own environment carries — the key never appears on an argv or in a process table, so a container round uses the SAME credential as a host round with zero authorization steps inside the unit. An API key neither refreshes nor rotates, so the OAuth era's two-store fork (host and container racing one grant's rotation) does not exist under endpoint credentials. The mount stays read-write because the round's transcripts land in `projects/` under the same directory, and the evaluation's model read-back parses them from the host side of that mount. A container round always takes the exec one-shot and declares no member bridge. **Mind the host-only entries in the scoped `settings.json`**: measured, the `https_proxy` there — meant for the host daemon — points at nothing inside the unit and the round dies with `Connection refused`. The caller stages what it mounts.
-
-```
-src/index.ts                harness registration, /claude-code command family, config schema
-src/endpoint-auth.ts        the endpoint credential: scope-file ↔ config merge, env construction, stamp and clearing
-src/claude-cli-provider.ts  one-shot provider: spawn, stream mirror, turn/token accounting
-src/provision.ts            scoped-home provisioning (the proxy env block)
-src/records.ts              session-record listing and transcript model read-back from the scoped home
-src/tool.ts                 the `./tool` composition entry: the `subagent_claude_code` delegation tool (preset-granted)
-```
-
-The bundle patch registers the `claude-code` harness into the family core (`@khorsheed/dsh-local-agent`, declared as a dependency — the claude bundle deliberately does not re-insert the core row, which would mount it twice) and mounts the `claude-local` provider, which spawns `claude -p --verbose --output-format stream-json` under the harness's scoped home. The `subagent_claude_code` tool is the family-owned tool (this package's `./tool` composition entry, sharing the family core's `./tool-factory` implementation), granted per session by an agent preset that names the row: the official subset (`description`/`prompt`) plus an optional `resume` parameter.
-
-**Session records.** `/claude-code sessions` lists the scoped home's `projects/<cwd-slug>/<uuid>.jsonl` session files — this agent's delegations, never your personal sessions. The slug is a lossy encoding of the workspace path, so the listed `workDir` comes from the file content (the first `user` event's `cwd` field), never the directory name. The Settings panel shows the same listing narrowed to the current workspace.
-
-**Resume security.** The handle never rides the prompt: it is read only from the `resume` parameter, and the localAgent registry resolves it only for the same parent session and provider that recorded the delegation — a forged handle (unknown child session, another parent's session, or the wrong provider) is rejected before any CLI process starts.
-
-**Stream mirror & accounting.** `thinking` blocks fold to `reasoning` blocks, `tool_use`/`tool_result` to tool lines (`[工具 Bash] <command> → output`), reply `text` to assistant text; resumed rounds append their own turn without duplication. Edit-family calls (Edit/Write/MultiEdit/NotebookEdit) fold into ApplyPatch-style cards — the path on the args line, the actual edit (old/new strings or the whole file body) as the card body, the same shape codex's fileChange mirror uses; server-side tools (`server_tool_use` web_search/web_fetch) pair with their results by id into visible WebSearch/WebFetch cards; a `redacted_thinking` block folds to a visible placeholder think line (the content is server-encrypted by design — the line says so); every other tool's input keeps its one-scalar summary, with a truncated JSON summary as the fallback instead of dropping. Every mirrored step is wrapped in a `step/start`–`step/end` pair at its own (turn, step) — the host's live conversation view registers steps only on those boundaries, so a boundary-less assistant message stays unrendered until a full rebuild. The provider opens `turn/start` at spawn and closes `turn/end` on settle — including failure and cancellation — so `subagentTiming` duration equals actual CLI runtime and no window stays open; the final `assistant/message` carries token usage parsed from the JSON result (`input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens` — Anthropic reports each separately).
-
-**Model experience.** The child is a fresh one-shot `claude -p` in the delegating session's workspace; the parent submits only the standalone task text and sees only the final answer or the exact error, plus the resume self-description on a fresh delegation — Claude commentary, tool activity, and workspace diffs are not copied over. Child tokens never enter the parent's context; the child pays for its own Claude context and turn (cache reuse depends only on the scoped installation's provider, model, and history); the parent's KV cache is unaffected.
-
-**Live driver (`live: true`).** Replaces the per-round spawn: the member's first delegation brings up one resident stream-json process (`claude -p --verbose --input-format stream-json --output-format stream-json`), the first stdin `user` message triggers `system/init` (the server-assigned session id becomes the delegation record's `cliSessionId`), and every later round is one stdin message. The event stream is byte-identical in shape to exec's stream-json, so each turn folds through the same `ClaudeStreamParser` (the last line held back until `result` carries usage, as in exec), and `cancel` lands as a `control_request interrupt` — the process survives and the session stays continuable. Reclaim is stdin EOF → SIGTERM; after a crash the next round reattaches with `--resume <session_id>`. A runtime binds the member's effective model at spawn (session-level override → delegation model → settings key) and scratches it into the scoped settings.json (a `--resume` reattach honors the file over the flag); a runtime whose bound model no longer matches the round's resolution retires before the respawn. A `permissionMode: normal` spawn omits `--dangerously-skip-permissions`, so the CLI's server→client control requests (the `can_use_tool` approval surface) are auto-answered with allow by the driver — a subagent has no approval surface, matching exec's effective behavior under skip; any other subtype gets an error answer instead of a silent hang. The auth discipline is byte-identical to exec: only the scoped `CLAUDE_CONFIG_DIR` plus the resolved endpoint credential variables are injected — the global `~/.claude` is never touched and no `auth` verb ever runs.
-
-**Config notes.** Every delegation logs the effective endpoint at info level (`subagent-claude: delegating via <endpoint>`), and a failed run's error text names it — diagnose routing from that log and the profile row, not from your current shell's environment. `skip` is the default because a one-shot CLI subagent has no approval surface; scope the host's own sandbox (e.g. run the host inside a sandboxed workspace) when a delegation needs confinement.
-
-</details>
+Needs DSH 0.1.5-rc.1 or later; verified on 0.2.1-rc.1.
 
-## Development
+## For developers
 
-Part of the [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo (`packages/local-agent-claude-code`). Issues and contributions welcome there.
+- Config keys, the available-models list, where the endpoint credential is stored, the live stream mirror, and usage read-back are in the [full reference](https://github.com/Khorsheed/dsh-plugins/blob/main/packages/local-agent-claude-code/docs/reference.en.md).
+- To install it alone, name the core too: `dsh plugin --profile web add @khorsheed/dsh-local-agent @khorsheed/dsh-local-agent-claude-code`; the delegation tool is granted by a mode and won't appear unless a mode names it.
+- Part of [dsh-plugins](https://github.com/Khorsheed/dsh-plugins); open issues and contributions there. Changes: [CHANGELOG.md](CHANGELOG.md).

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/local-agent-claude-code/README.en.md
-packages/local-agent-claude-code/README.en.md: 812398d9ac14b7cb0d77a584af9c7f510c716c3f
-packages/local-agent-claude-code/README.md: e026c9163886617cc80553db90f76e76ad4246c2
+packages/local-agent-claude-code/README.en.md: 22413d23e74d101e43dfe95b710e6af81c6701a7
+packages/local-agent-claude-code/README.md: 1355e6937b403ddd340fc10a5c0f0e0a76d4d88f

package/README.md

@@ -2,130 +2,46 @@
 
 [English](README.en.md) | 中文
 
-把编码任务委派给本机的 Claude Code——思考、工具调用与回复实时流回，你的私人 `~/.claude` 分文不动。
+把编码任务交给你电脑上的 Claude Code：思考、工具调用和回复实时流回来，还能接着聊。
 
-点名本包 `./tool` 组合入口的 agent preset（如开发模式）即可发起委派：子会话全程可见、可中止、可续聊，每轮的账目（实际模型、token 用量、工具调用数）都真实回读。认证是端点凭据制（`baseUrl` + `apiKey`/`authToken`），作用域隔离——插件只管理 `$DSH_HOME/local-agent/claude-code` 这一份目录，你的个人安装与凭据自始至终置身事外。没有 OAuth 网页授权：容器轮与宿主轮用同一套凭据，容器里不需要再授权一次。[local-agent 家族](../local-agent/README.md) 的 Claude Code harness。
+想让 Claude Code 帮一把，以前得自己开终端、复制粘贴、再把结果搬回来。装上之后，你在会话里说一句「这个交给 Claude Code」，agent 就把任务交给本机的 Claude Code；它的思考、工具调用和回复实时出现在子会话里，跑完把结果带回来。每一次调用用了多少 token、实际跑的是哪个模型，都按真实数字记下。Claude Code 在自己单独的目录里运行，你电脑上原来的 `~/.claude` 配置和登录一点不碰。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/08-local-agent.png" width="640" alt="设置 → 插件 → 插件配置里的 Local Agent 家族卡片，Claude Code 一行的状态点显示授权状态">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/local-agent-claude.png" width="560" alt="展开的 Claude Code 一节：已登录的 Claude Code 和版本号，端点地址、API Key、Auth Token 和可用模型名单">
 
-## 特性
+## 能做什么
 
-- **按会话授予的委派**——`subagent_claude_code` 工具是本包的 `./tool` 组合入口，由点名它的 agent 预设授予该预设的会话，无需逐 preset 变体。
-- **作用域隔离**——每个 Claude 进程都以 `$DSH_HOME/local-agent/claude-code` 为 `CLAUDE_CONFIG_DIR` 运行；你的个人 `~/.claude` 置身事外。
-- **端点凭据，没有网页授权**——在 bundle 行配好 `baseUrl` + `apiKey`（或 `authToken`）即已认证，状态面板直接显示已认证；每个命名 scope 可用自己的 `endpoint-auth.json` 覆盖部署级配置。`sessions`/`status`/`logout` 与 设置 → 本地 Agent 面板构成完整一族。
-- **续聊委派**——把结果自述的 `resume` 句柄传回，即可继续同一个 Claude 会话，并按轮记账。
-- **实时流镜像**——子会话实时镜像 Claude 的思考、工具调用与回复；中止会保留部分转写与真实 token 用量。
-- **模型回读与独立工作目录**——每轮从 stream-json 的 system/init 回读实际模型，写进委派记录；编排器可用 `cwd` 选项给每格独立目录，resume 换目录即拒绝。
-
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/local-agent-claude-code-card.png" width="640" alt="展开的「Local Agent · Claude Code」设置卡：认证块、默认模型选择与常驻模式（live）开关">
+- **一句话交出去**：告诉 agent 哪段活给 Claude Code，它会自己写好要求交过去，结果回到当前会话。
+- **过程实时流回**：思考、工具调用和回复边跑边出现在子会话里；中途停下，已经做完的部分和用量都留着。
+- **账算得清**：子会话里每一次调用的用量单独记录，在上下文透镜里能逐次看到花在哪。
+- **接着聊，不冷启动**：让 agent 追问，或者打开子会话直接发消息，继续的是同一个 Claude Code 会话。
+- **填好 key 就能用**：在设置卡片里填端点地址和 API Key（或 Auth Token），点「保存凭据」，再点「验证端点并获取模型」确认能连上。
+- **自己挑模型**：在「可用模型」里勾选、拖动排序，排第一的就是默认模型；子会话里也能临时换模型和推理强度。
+- **常驻模式更快**：打开「常驻模式（live）」，Claude Code 进程常驻，停下不杀进程，崩溃后自动续上原来的会话。
 
 ## 安装
 
-前置依赖：一个可运行的 dsh profile，以及 `PATH` 上的 Claude Code CLI（`claude`）——插件不负责安装。家族 core 与本包一起安装（`dsh plugin add` 只调和**直接**依赖，所以两个包都点名）：
+先在电脑上装好 Claude Code CLI（命令行里能运行 `claude`），插件不替你装。然后在 DSH 的「插件 → 添加插件」里输入下面的包名，点安装：
 
-```sh
-dsh plugin --profile web add @khorsheed/dsh-local-agent @khorsheed/dsh-local-agent-claude-code
 ```
-
-重启 web 实例后，打开 设置 → 插件 里本包的卡片，在「认证」区填端点与 key 即可（也可预配在 profile 的本包配置行）；都不配则状态为未认证。卸载：
-
-```sh
-dsh plugin --profile web remove @khorsheed/dsh-local-agent-claude-code
+@khorsheed/dsh-bundle-local-agent
 ```
 
-作用域目录在卸载时刻意保留——`endpoint-auth.json` 与会话记录都在其中；删除 `$DSH_HOME/local-agent/claude-code` 即可清除全部痕迹。
-
-## 配置
-
-bundle 行接受这些可选字段：
-
-- `permissionMode`——`skip`（默认）传 `--dangerously-skip-permissions`，子代理写文件无需审批；`normal` 不传，需审批的动作（如写文件）被拒绝。
-- `model`——每轮委派以它起 CLI（`claude -p --model <模型>`）；不写就一个模型参数都不传。见下。
-- `baseUrl`——部署级端点，为子 CLI 设置 `ANTHROPIC_BASE_URL`（例如 `https://openproxy.to/claude` 这类中转，或自部署路由器）；不写即 Anthropic 官方端点。宿主 shell 里 export 的同名变量**从不被读取**——宿主环境对子进程一律清洗，路由只由配置与 scope 文件决定。**也可在设置卡「认证」区直接填**——卡片保存的是默认 scope 的 `endpoint-auth.json`（0600，只存本机，优先于这里的配置行），密钥绝不写进 profile 文件。
-- `apiKey`——部署级凭据，以 `ANTHROPIC_API_KEY`（`x-api-key` 头）发给端点。设置卡可写（落 scope 文件，不回显）；写进 profile 时只放本地，绝不入库。
-- `authToken`——部署级凭据的另一形态，以 `ANTHROPIC_AUTH_TOKEN`（`Authorization: Bearer` 头）发出——部分中转只认 Bearer。两个键都配时优先级由 CLI 自己决定。同样可在设置卡填写。
-- `proxyUrl`——子 CLI 自身流量的 HTTP 代理，provision 进作用域 `settings.json` 的 env 块；宿主进程环境不带代理时（例如 supervisor 拉起的实例不继承 shell export）用这项。它是本地流量转发器，与 `baseUrl` 的端点路由是两个层面。
-- `live`——长驻驱动：每成员常驻一个 stream-json 进程（`--input-format stream-json`），按轮发 stdin 消息（runtime 级优雅中断 control interrupt、同形推送流）；关闭或通道不可用即回一次性 `claude -p`。
-- `liveIdleMs`——长驻 runtime 空闲回收时限（默认 30 分钟）。
-
-> **迁移说明（下一发布线，破坏性变更）**——OAuth 网页授权整体移除：`/claude-code login` 不再存在，钥匙串/`.credentials.json` 协调随之删除；升级后首次启动会清扫作用域目录里残留的 OAuth 文件（`.credentials.json` 与 `.claude.json` 的 `oauthAccount` 标记），实测 claude 2.1.296 在两者并存时本就优先采用环境变量凭据。升级前先在设置卡或 profile 行配好 `baseUrl` + `apiKey`（官方端点的 console key 同样可用），否则升级即未认证。旧 `liveMirrorGranularity: event | token` 配置键继续兼容读取，但不再影响行为。
-
-> **每个 scope 的覆盖**——`<作用域目录>/endpoint-auth.json`（0600）按字段覆盖，两层生效顺序：**scope 文件 > profile 的 YAML 行**，缺哪个字段就回落到配置值。一个只写 `apiKey` 的文件等于给这个 scope 换 key。设置卡「认证」区编辑的就是默认 scope 的这份文件（经家族 gateway 的 `endpointAuth`/`configureEndpoint` Remote，会话不在场也能读写）。`/claude-code logout` 清除的也是这个文件；凭据完全来自配置行时 logout 会拒绝并提示去改 profile。
-
-### 可用模型（models.json）
-
-设置卡「可用模型」区维护一份**有序模型短名单**：点「添加模型」从端点当前供应的目录（`GET /v1/models`）里勾选加入，所以列表里只会有端点真实供应的模型；拖动行调整顺序。**第一个模型就是默认模型**——每轮委派以它起 CLI（`claude -p --model <模型>`，常驻模式同一个旗标），优先级只低于成员会话级覆盖与委派级指定。列表保存在作用域目录的 `models.json`（每个命名 scope 可各有一份，与端点凭据同一套文件机制），编辑即保存，下一轮委派生效。
-
-**留空 = 既有行为。** 列表为空时，模型照旧由这些层决定：插件配置或设置的 `model` 键 → 作用域 `settings.json` 的 `model` → CLI 内置默认（本插件从不猜它是什么）。一次性（exec）轮不改写作用域 `settings.json`；常驻（live）spawn 会把生效模型暂写进该文件（`--resume` 重挂认文件不认旗标），绑定空模型的 spawn 前再还原。
-
-**评测快照（effectiveSettings）** 的 model 字段同一条解析链：名单第一项 → `model` 键 → 作用域文件；名单进不了快照（它是偏好不是公平性旋钮），回读的 `observedModel` 才是实测证据。run 冻结条件后中途改名单，下一轮的模型回读会发现声明 ≠ 实测并判 misattributed（冻结决策 5）。
-
-成员会话里的 composer 模型选择器写入的是**会话级覆盖**——它排在委派模型与名单之前，只存内存、刻意不跨宿主重启、也不写进设置或名单。切换进行中轮次的成员会被拒绝；live 下换到不同模型会退役该成员的常驻 runtime，下一轮以新模型重挂**同一个** CLI 会话（对话不丢），换成相同模型则什么都不发生。成员级模型和推理强度修改使用下文的持久控制面。
-
-模型读面来自**端点实际供应的模型**（`GET <baseUrl>/v1/models`，带已保存的凭据）——选择器列出的就是端点能跑的，凭据无效时列表为空并给出原因，绝不会用本地 CLI 的内置词汇表掩盖一个失效的 key。目录共用 core 缓存和刷新订阅；端点或凭据一变即重探（凭据轮换经短哈希进缓存键，密钥本体不进），传输错误保留上次成功数据并按计划重试。端点返回的 effort 能力会带上可选档位。目录外的模型 id 仍可手动输入。设置卡的「验证端点并获取模型」按钮是同一条探测的显式版本（无会话 Remote，未保存修改时禁用）。运行中选择排到下一完整轮次（含工具续跑）；core 统一持有当前/待生效配置、撤销与重试，冻结评测成员禁止变更。
-
-**委派级的模型优先。** 编排器可以经门面 `DelegationCallOptions.model` 给**某一次委派**点名模型，它排在这个键之前（顺序见家族核心 README 的层序）。首轮请求的值记进委派记录，resume 轮照它重发——resume 不接受 model 参数。常驻模式下，首轮点名的模型作为该成员的起始模型在 runtime spawn 时绑定：已绑定不同模型的 runtime 先退役，同一个 CLI 会话经 `--resume` 在新进程上续起。
-
-**成员会话级切换。** 成员会话的 composer 模型选择器经家族网关 `setMemberModel` 写入一个**会话级覆盖**——它排在委派模型与这个键之前，只存内存、刻意不跨宿主重启、也不写进设置。切换进行中轮次的成员会被拒绝；live 下换到不同模型会退役该成员的常驻 runtime，下一轮以新模型重挂**同一个** CLI 会话（对话不丢），换成相同模型则什么都不发生。
-
-**这不是评测的缺口。** 评测 run 的条件在建立时冻结：run 跑到一半改这个键，下一轮的模型回读会发现声明模型 ≠ 实测模型，run 直接判为 misattributed 而失败（冻结决策 5）。「切了新 run 照新走、进行中的 run 不被悄悄换掉」是设计出来的，不是漏掉的。
-
-⚠️ `skip` 没有 OS 级沙箱——子进程可以写宿主用户能写的任何地方，包括工作区之外；端点凭据会发送给 `baseUrl` 指向的端点。委派需要限制时改用 `normal`；`baseUrl` 只指向你信任的地址。
-
-**评测快照（effectiveSettings）。** 本 harness 向注册表声明一份实时读取的公平性设置快照，供评测条件哈希使用：drive（exec/live）、permissionMode（skip/normal，插件配置）、端点是否固定（按 provider 的解析顺序——scope 的 `endpoint-auth.json` 逐字段覆盖插件配置，只报主机名；key 材料永远不进快照，文件名命中评测契约哈希的凭据拒绝名单，连摘要都不进条件指纹）、已配置模型（名单第一项 → 插件配置的 `model` 键 → 作用域 `settings.json` 的 `model`；CLI 自身的默认模型由 CLI 决定，绝不猜值，都没有就不给字段）、CLI 版本（`claude --version`，按可执行文件路径+mtime 缓存；探测不到即字段缺位）。`/claude-code status` 与 `LocalAgentStatus` Remote 附带同一份快照。
+Claude Code 会跟着「多Agent协作」套件一起装好（各家本机 agent 共用同一个底座，单装用不起来）；如果你主要写代码，直接装开发套件 `@khorsheed/dsh-dev-suite` 也包含它。装完重启 DSH，到「插件」页的「本机 Agent 委派」卡片里，展开 Claude Code 一节填好端点和 key。
 
-## Compatibility
-
-- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：✅ 公开 API 兼容。生成中的内容走 local-agent 瞬时 Remote 与公开 Conversation 节点；增量耐久恢复检查点负责落盘，最终原生消息保留转写与用量语义。浏览器 P95 验收由 room 协调者提案跟踪。minHost 0.1.5-rc.1——更旧宿主请停留在前一发布线。设置卡渲染为 core「本机 Agent 委派」家族卡的一节（Plugins 页 core 的 `plugins.item` 条目，0.1.7-alpha.1+；旧版 core 上回落为本包自己的 `plugins.item` 卡），`configForms.whileServed` 随宿主服务的 `local-agent-claude-code` 命名空间挂载；0.1.5 线不再呈现卡片（宿主删除了 `settings.plugin.item` 席位），其余表面不变。
-- 源码线（deepseek-harness master）：✅（verifiedHost: 0.2.1-rc.1）——host-021 波对 0.2.1-rc.1 树全量 build+test 绿；委派迁移到 `ctx.subagents.startActivation`（受管 activation），run.id 改为每次执行唯一。
+把活交给 Claude Code 要在带委派的模式里进行，比如「开发模式」：开一个新会话、选这个模式，对 agent 说「把这个交给 Claude Code」。在其它模式里看不到它是正常的。
 
 ## 已知限制
 
-- **logout 只清 scope 自己的文件**——`endpoint-auth.json` 之外，来自插件配置的部署级凭据不受影响；要换它请编辑 profile 行。
-- **凭据错误的代价是重试时长**——一把失效的 key 会让 CLI 在端点前重试到上限（实测约 8 分钟）才报出 401；`/claude-code status` 的 `rejected` 等级在那一轮 settle 后才出现。
-- **交互会话记录可能缺失**——自定义 `CLAUDE_CONFIG_DIR` 下 CLI 可能不写转写（上游行为）。
-- **headless 注意**——`/claude-code` 命令需要 Web 会话；`--profile headless` 可通过挂载工具行的组合委派。
-
-## 实现原理
-
-<details>
-<summary>内部结构（点击展开）</summary>
-
-**模型回读与 cwd 覆盖。** 每轮 settle 后，provider 把 stream-json `system`（init）事件 `model` 字段里的实际模型（如 `claude-opus-5[1m]`，原样回读，上下文变体后缀照留）随 `settled` 进度事件上报，并合并进 `delegations.jsonl` 的 `observedModel` 字段；取不到即缺位，绝不猜测。当任何一层、任何记录都没有模型时，「默认」面的最近观测提示读成员**自己的**转录（`projects/<cwd-slug>/<sessionId>.jsonl`；无成员面读全树最新的那份）——这是为 settle 通道之前的旧轮次准备的历史兜底；只读，绝不回写 `delegations.jsonl`。编排器还可以经门面 `DelegationCallOptions.cwd` 给本轮指定工作目录（记录进 `cwd` 字段）；resume 轮解析出的目录若与首轮记录不一致，进程启动前即 fail loud——CLI 会话延续的是首轮所在目录的上下文。
+- 只支持端点和 key，没有网页登录。
+- key 填错时，Claude Code 会先反复重试（实测约 8 分钟）才报错，这一轮结束后卡片上才显示凭据被拒。
+- `/claude-code` 这组命令只能在网页会话里用。
 
-**工具调用计数。** 每轮 settle 时，provider 顺带数出本轮的工具调用，随 `settled` 进度事件上报（`toolCalls: { count, byName }`）。计数就在流解析**已经走过**的 `tool_use` 分支里，`byName` 的键是该块自己的 `name`（`Bash`、`Read`、`TodoWrite`，MCP 工具则是 `mcp__server__tool` 全名），原样保留、不跨家归一。`TodoWrite` 也计——折叠逻辑把它挪去了 todo 快照、不进 transcript，但 CLI 确实调了它。本轮一份，绝不累计；一次都没调用就整个字段缺位（缺席 ≠ 0）。实测：一轮「先 Read 两个文件再 Bash 列目录」回读 `{count: 3, byName: {Read: 2, Bash: 1}}`，与镜像出的工具卡片逐个对得上。
-
-**端点凭据模型。** 认证只有一种形态：`endpoint-auth.ts` 把作用域 `endpoint-auth.json` 逐字段合并到插件配置三元组（`baseUrl`/`apiKey`/`authToken`）之上，provider、长驻驱动与模型目录在每次 spawn 前现解现注（`ANTHROPIC_BASE_URL`/`ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN`），换 key 即下一轮生效，无需重载。设置卡的凭据表单经家族 gateway 的 `endpointAuth`/`configureEndpoint` Remote 读写默认 scope 的这份文件——无会话通道，密钥既不回显也绝不落进 profile patch 文档。已实测：claude 2.1.296 在全新作用域目录里仅凭这组环境变量即可跑通 `claude -p`——CLI 自行脚手架 `.claude.json`，headless 模式没有 onboarding 或 key 批准门槛；与陈旧的 OAuth 文件并存时同样优先采用环境变量凭据（provision 仍会在升级后首次启动清扫这些残留）。状态探针是轻量文件+配置检查（有非空 key 即认证），绝不为探测 spawn CLI；`endpoint-auth.json` 的 mtime 充任凭据戳记——一轮 401 把等级打成 `rejected`，重写该文件（换 key）即恢复，与 OAuth 时代「重新登录改写标记」语义一一对应。
-
-**命名 scope。** 每个命名 scope 在 `<homesRoot>/claude-code@<名>` 另开一份 `CLAUDE_CONFIG_DIR`：自己的 `endpoint-auth.json`、自己的会话记录、自己的凭据等级。scope 文件缺省即跟随部署级配置——这正是一次配置、全部 scope 可用的来源。带 scope 的委派用该目录跑 `claude -p`、从它回读；只走 exec。
-
-**容器内委派。** 编排器可以经门面 `DelegationCallOptions.exec`（`{ container, workdir, env? }`）让本轮跑在一个**已取得的容器**里：argv 变成 `docker exec -w <workdir> [-e NAME…] <container> claude -p …`，其余（stream-json 解析、settle、记录）逐字节不变。`env` 必须给出容器内的 `CLAUDE_CONFIG_DIR`，调用方把宿主作用域目录 rw bind 到那条路径上。端点凭据经家族的容器转发进入单元：provider 解析出的 `ANTHROPIC_*` 变量以**仅名字**的 `-e` 旗标转发，值由 docker 客户端进程环境携带——key 从不上 argv、不进进程表，容器轮因此**与宿主轮用同一套凭据，单元内没有任何授权步骤**。API key 无刷新无轮换，OAuth 时代「宿主与容器双写 refresh token 互杀」的问题在端点凭据下整体不存在。会话记录仍落在挂载目录的 `projects/` 下，评测的模型回读从宿主侧解析它们。容器轮固定走 exec 一次性驱动，且不声明成员桥。**注意作用域 `settings.json` 里的宿主专用项**：实测那里给宿主守护进程用的 `https_proxy` 在容器内指向不存在的地址，本轮当场 `Connection refused`——挂进去的目录要由调用方备好。
-
-```
-src/index.ts                harness 注册、/claude-code 命令族、config schema
-src/endpoint-auth.ts        端点凭据：scope 文件 ↔ 配置的合并、env 构造、戳记与清除
-src/claude-cli-provider.ts  一次性 provider:spawn、流镜像、turn/token 记账
-src/provision.ts            作用域目录 provisioning（proxy env 块）
-src/records.ts              作用域目录的会话记录列表与转写模型回读
-src/tool.ts                 `./tool` 组合入口：`subagent_claude_code` 委派工具（预设点名授予）
-```
-
-bundle patch 把 `claude-code` harness 注册进家族 core（`@khorsheed/dsh-local-agent`，声明为依赖——claude 包刻意不重复插入 core 行，重复会挂载两次），并挂载 `claude-local` provider，后者在 harness 作用域目录下 spawn `claude -p --verbose --output-format stream-json`。`subagent_claude_code` 工具是家族自有工具（本包的 `./tool` 组合入口，实现共享自家族 core 的 `./tool-factory`），由点名该行的 agent 预设按会话授予：官方子集（`description`/`prompt`）加一个可选 `resume` 参数。
-
-**会话记录。** `/claude-code sessions` 列出作用域目录下的 `projects/<cwd-slug>/<uuid>.jsonl` 会话文件——即本 agent 的委派，绝不是你的私人会话。slug 是工作区路径的有损编码，所以列出的 `workDir` 取自文件内容（第一条 `user` 事件的 `cwd` 字段），绝不取自目录名。设置面板呈现同一份列表并收窄到当前工作区。
-
-**续聊安全。** 句柄绝不进 prompt：它只从 `resume` 参数读取，localAgent registry 只对记录该委派的同一 parent 会话与 provider 解析句柄——伪造的句柄（未知子会话、他人 parent 的会话、或错误的 provider）在任何 CLI 进程启动前就被拒绝。
-
-**流镜像与记账。** `thinking` 块折叠为 `reasoning` 块、`tool_use`/`tool_result` 为工具行（`[工具 Bash] <command> → output`）、回复 `text` 为 assistant 文本；续聊轮各自追加自己的 turn，不会重复。编辑类调用（Edit/Write/MultiEdit/NotebookEdit）折叠为 ApplyPatch 式卡片——路径在参数行，真正的改动（旧/新串或整个文件体）在卡身，与 codex 的 fileChange 镜像同一形态；服务端工具（`server_tool_use` 的 web_search/web_fetch）与其结果按 id 配对成可见的 WebSearch/WebFetch 卡；`redacted_thinking` 折叠为一行可见的占位思考（内容按设计由服务端加密，不可见——行内注明）；其余工具的输入取单一标量摘要，取不到就给一份截断的 JSON 摘要而不是丢空。每个镜像 step 都包在同 (turn, step) 的 `step/start`–`step/end` 边界对内——宿主实时会话视图只在边界上登记 step，缺了边界 assistant 消息要等整页重建才渲染。provider 在 spawn 时开 `turn/start`、settle 时关 `turn/end`——失败与被取消同样关闭——因此 `subagentTiming` 时长等于实际 CLI 运行时长，不会留下未闭合窗口；最终 `assistant/message` 携带从 JSON 结果解析的 token 用量（`input_tokens`、`output_tokens`、`cache_read_input_tokens`、`cache_creation_input_tokens`——Anthropic 各桶独立上报）。
-
-**模型体验。** 子会话是委派会话工作区内一个全新的一次性 `claude -p`；父级只提交独立的任务文本，只看到最终回答或精确错误，以及首次委派时的续聊自述——Claude 的评论、工具活动、工作区 diff 不会复制进父级。子会话 token 永不进入父级上下文；子会话为独立的 Claude 上下文与回合付费（缓存复用只取决于作用域安装自身的 provider、模型与历史）；父级 KV cache 不受影响。
-
-**长驻驱动（`live: true`）。** 替代每轮 spawn：成员首轮委派拉起一个常驻 stream-json 进程（`claude -p --verbose --input-format stream-json --output-format stream-json`），第一条 stdin `user` 消息触发 `system/init`（server 分配 session id，即委派记录的 `cliSessionId`），之后每轮 = 一条 stdin 消息；事件流与 exec 的 stream-json **完全同形**，逐轮过同一个 `ClaudeStreamParser` 折叠（末行留置到 `result` 挂用量，与 exec 一致），`cancel` 落地为 `control_request interrupt`——进程不死、会话可续。回收阶梯是 stdin EOF → SIGTERM；崩溃后下一轮以 `--resume <session_id>` 重挂盘上会话。runtime 在 spawn 时绑定成员的生效模型（会话级覆盖 → 委派模型 → 设置键），并把它暂写进作用域 `settings.json`（`--resume` 重挂认文件不认旗标）；绑定模型与新一轮解析不一致的 runtime 先退役再重挂。`permissionMode: normal` 的 spawn 不带 `--dangerously-skip-permissions`，CLI 的 server→client 控制请求（`can_use_tool` 审批面）由驱动自动应答 allow——子代理没有审批面，与 exec 在 skip 下的有效行为一致；其余子类型应答 error 而不是沉默挂起。授权纪律与 exec 逐字一致：只注入作用域 `CLAUDE_CONFIG_DIR` 与解析出的端点凭据变量，绝不碰全局 `~/.claude`，绝不执行任何 `auth` 命令。
-
-**配置注意。** 每次委派在 info 级别记录有效端点（`subagent-claude: delegating via <endpoint>`），失败运行的报错文本会点名它；排查路由异常时看这份日志与 profile 行，而不是你当前 shell 的环境。`skip` 作为默认是因为一次性 CLI 子代理没有审批面；委派需要被限制时，给宿主自身套沙箱（例如在沙箱化工作区内运行 dsh 宿主）。
+## Compatibility
 
-</details>
+需要 DSH 0.1.5-rc.1 或更新版本，已在 0.2.1-rc.1 上验证。
 
-## 开发
+## 给开发者
 
-隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo（`packages/local-agent-claude-code`）。问题与贡献请移步该仓库。
+- 配置项、可用模型名单、端点凭据的存放、实时流镜像与用量回读等细节，都在[完整参考](https://github.com/Khorsheed/dsh-plugins/blob/main/packages/local-agent-claude-code/docs/reference.md)里。
+- 单独安装要连同底座一起点名：`dsh plugin --profile web add @khorsheed/dsh-local-agent @khorsheed/dsh-local-agent-claude-code`；委派工具由模式授予，没有模式点名时不会出现。
+- 隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins)，问题与贡献请到该仓库；变更见 [CHANGELOG.md](CHANGELOG.md)。