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

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 变更记录
 
+## 0.2.0-rc.3（2026-10-22）
+
+（版本号说明：家族的 dsh-headless 包 0.2.0-rc.2 曾被发布后又撤回，npm 永久烧掉该版本号；为守住家族「同一版本线」纪律（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，重写凭据文件即恢复手势。
+- **「可用模型」有序短名单取代默认模型字段**：持久化为 `<作用域目录>/models.json`，首项即默认模型；添加弹窗的候选全部来自端点当前供应的目录（勾选添加、拖拽排序），任何本地残留别名都混不进选择器。名单为空时完整回退既有链；成员的模型在首轮即绑定，改名单只影响新成员，不会换掉对话中的成员。
+- **模型目录改为端点供给**：目录 = 所配端点实际供应的模型（探测预算 20 秒，传输错误保留上次成功数据）——本地 CLI 的词汇表不再给一把失效 key 打掩护。
+- **设置卡并入「本机 Agent 委派」家族卡**：Plugins 页的 per-harness 卡折叠为一张家族卡、按 harness 分节呈现，本包卡读作「本机 Claude Code 委派」；家族卡随后修复为无条件注册——原先的命名空间门控让它在 prod 上永不挂载（2026-10-21）。与旧版家族核混装时回落为独立卡。
+- **适配宿主 0.2.1 线**：委派链路迁移到 subagent `startActivation`（宿主 0.2.1 删除旧的 `ctx.subagents.start()`）；加宽 `@deepseek-ai/dsh-*` peer 区间以覆盖宿主 0.2.1。
+
+## 0.2.0-rc.1（2026-09-30）
+
+- **家族折叠：委派工具收进本包**。新增 `./tool` 组合入口（`src/tool.ts`）——`subagent_claude_code` 委派工具由 agent 预设点名 `name: '@khorsheed/dsh-local-agent-claude-code/tool'` 按会话授予，Config 两字段（`provider` / `toolName`）全部可选、默认即本包取值，预设行无需配置；行 id `tool-subagent-claude-code-local` 不变。bundle patch 不再插 profile 根工具行（官方 `tool-subagent-claude-code` 行的停用覆盖保留），本包自挂载恰好一行（provider 行）。实现共享自家族核 `@khorsheed/dsh-local-agent` 的 `./tool-factory` 导出；对 `@khorsheed/dsh-local-agent-tool-subagent` 的依赖移除（该包退役）。
+
 ## 0.1.0-rc.8（2026-09-30）
 
 家族同版联动：加宽 `@deepseek-ai/dsh-*` peer 区间以覆盖宿主 0.2.0（0.2.0 的兼容闸会禁用 peer 区间不覆盖宿主版本的已装插件）。无功能变更。

package/README.en.md

@@ -4,15 +4,15 @@ 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.
 
-Any dsh agent preset can delegate: the family tool mounts once at the profile root, 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. Login is 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. The Claude Code harness of the [local-agent family](../local-agent/README.md).
+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).
 
 <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">
 
 ## Features
 
-- **Delegate from any preset** — the tool mounts once at the profile root; no per-preset variants.
+- **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.
-- **Guided login, one command** — `/claude-code login` answers with the exact command to run in your own terminal (claude ≥2.1 prints its OAuth URL only on a TTY, so the host no longer spawns and scrapes) and watches the scoped home for the credential; `sessions`/`status`/`logout` and a Settings → 本地 Agent panel complete the family.
+- **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.
@@ -27,13 +27,13 @@ Prerequisites: a running dsh profile, and the Claude Code CLI (`claude`) on `PAT
 dsh plugin --profile web add @khorsheed/dsh-local-agent @khorsheed/dsh-local-agent-claude-code
 ```
 
-Restart the web instance to activate, then run `/claude-code login` once from a session. Uninstall:
+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
 ```
 
-The scoped home is kept on uninstall so a reinstall needs no fresh login; delete `$DSH_HOME/local-agent/claude-code` to remove every trace.
+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
 
@@ -41,24 +41,32 @@ 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` — sets `ANTHROPIC_BASE_URL` for the child CLI (e.g. a self-hosted router or proxy); absent, the child inherits the host process environment. Config wins over environment.
-- `proxyUrl` — an HTTP proxy for the child CLI's own traffic (model calls AND OAuth refresh), 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).
+- `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** — live runs always consume incremental output. The old `liveMirrorGranularity: event | token` key is accepted for existing profiles but ignored; changing it never changes a running process. Exec remains available for evaluation. Final provider items remain authoritative, including tool history and usage.
+> **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.
 
-### Default model (`model`)
+> **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.
 
-**Absent = today's behavior.** Without this key the plugin adds no model flag to the argv at all: the scoped `settings.json`'s `model` decides which model runs, and claude's own default decides when that is missing too (the plugin never guesses what it is).
+### Available models (models.json)
 
-**Set = every delegation round starts the CLI with it.** All four argv variants — fresh and resume, one-shot and resident (`live: true`) — carry `--model <model>`, placed before the member channel's `--allowedTools … --`: that flag is variadic and everything after its `--` is the task text.
+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.
 
-One-shot (exec) rounds never rewrite the scoped `settings.json`: `--model` overrules it per round and the file stays exactly as you edited it. A resident (live) spawn scratches the member's 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; the "CLI config" layer that status and the settings card report is always the value you configured, never a member's scratch.
+**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.
 
-The settings card's "Default model" writes the provider setting for subsequent rounds. Its shared picker displays the scoped model directory, discovery source and completeness, plus an explicit model-ID input when needed. Clearing the selection follows the effective configuration/default chain. Saving does not interrupt an active round and requires no reload. If the shared picker is unavailable, the card retains its text-input fallback. Per-member model and effort changes use the durable controls described below.
+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).
 
-The model surface now also reads Claude's native `initialize` directory, preserving selection aliases, display labels, resolved names and supported effort levels. It shares the core cache and refresh subscription, retains successful data after a failed refresh, and labels historical suggestions separately. This scoped control probe sends no user task and writes no model settings. An older CLI without this directory reports unsupported; native candidates do not establish account entitlement. The shared model picker and member effort controls are connected. 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.
+
+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.
 
@@ -66,20 +74,19 @@ The model surface now also reads Claude's native `initialize` directory, preserv
 
 **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 scoped login's OAuth token is sent to whatever `baseUrl` points at. Prefer `normal` when a delegation needs confinement; point `baseUrl` only at endpoints you trust.
+⚠️ `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 order — the config item wins over the host environment's `ANTHROPIC_BASE_URL`; hostname only), 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.
+**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.
 
 ## 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.
-- source line (deepseek-harness master): ✅ (verifiedHost: 0.1.5-rc.1)
+- 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
 
-- **macOS logout is config-only** — the keychain entry is left for the CLI's own `claude auth logout`; a fresh login rewrites the same slot, so the stale entry is harmless.
-- **One grant cannot be shared between a host round and a container round** — the two use different stores on macOS, and a rotation on either side invalidates the other's token family. A containerized condition takes its own named scope; see Container delegation.
-- **Linux credentials are not isolated** (upstream bug #47661) — claude reads the default `~/.claude/.credentials.json` even when the scoped home has none.
+- **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.
 
@@ -92,22 +99,22 @@ The model surface now also reads Claude's native `initialize` directory, preserv
 
 **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.
 
-**Named scopes.** `/claude-code login --scope <name>` opens a second `CLAUDE_CONFIG_DIR` at `<homesRoot>/claude-code@<name>`, and the login argv is built from the directory BEING logged in (`env CLAUDE_CONFIG_DIR=… claude auth login` — that assignment outranks the spawn env, so a hard-coded default would authorize the wrong directory under `--scope`). claude's keychain item is keyed by the config directory's path, so a named scope gets its own keychain item for free — the one credential store among the four harnesses that is path-isolated by nature. A scoped delegation runs `claude -p` against that directory, reconciles keychain↔file there, and reads back from there; exec-only.
+**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".
 
-**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. Measured on claude 2.1.272 inside the evaluation image, the in-container CLI reads AND writes `<CLAUDE_CONFIG_DIR>/.credentials.json`, and its whole state tree (`projects/`, `sessions/`, …) lands there too; the older upstream-#47661 behavior (Linux writes the scoped dir but reads the default home) does not describe that version. The credential reconcile before every spawn still runs against the **host** scoped home, so a refreshed grant reaches the container through the mount — and it is **newer-wins, not a mirror**, because the unit is a SECOND WRITER to that same file. The CLI inside a unit has no keychain, so it rotates the grant in the mounted file; an unconditional keychain→file mirror would then hand the next run a refresh token the unit already spent, the endpoint rejects it, and the CLI answers by CLEARING the file — which logs the whole instance out, because that file is the instance's credential. The reconcile therefore writes the keychain blob only when it is not older than the file's (access-token expiry decides; an undefined expiry on either side keeps the keychain writing, and an unusable file never wins). The mount stays read-write for a second reason as well: 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.
+**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.
 
-**A container round needs its OWN scope, and the discipline is not optional.** claude is the only harness here with two credential stores, and measured on macOS 2.1.274 they do not have one reader: the HOST CLI reads and writes the KEYCHAIN, while the CLI inside a unit — Linux, no keychain — reads and writes the mounted file. One grant refreshed from both is one grant refreshed twice, and the endpoint rotates single-use refresh tokens by invalidating the whole token FAMILY: whichever side did not refresh last is left holding a dead token. Measured end to end — a container round rotated the file, and the next host round answered `OAuth session expired and could not be refreshed` although the file's own access token was still hours from expiry, recoverable only by a fresh login. Newer-wins keeps the FILE side correct, which is what the unit and every status probe read, but nothing can write the unit's rotation back into the keychain (`security add-generic-password` would put the secret in argv, so it is refused). So the container side and the host side must be two INDEPENDENT grants: give every containerized claude condition its own named scope, authorize it once with `/claude-code login --scope <name>`, and never run a host-side claude round in that scope. The evaluation refuses a plan that breaks this before it acquires a unit. **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.
+**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 and file-based logout
-src/records.ts              auth probe and session-record listing from the scoped home
+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 (`@khorsheed/dsh-local-agent-tool-subagent`): the official subset (`description`/`prompt`) plus an optional `resume` parameter.
-
-**Scope isolation.** On macOS the real credential lives in the OS keychain under a hashed entry (`Claude Code-credentials-<sha256(configDir)[:8]>`) keyed to the scoped home path — file-based logout cannot reach it, but a fresh login rewrites the same slot. Which store the CLI itself uses is VERSION-dependent and was measured, not assumed: 2.1.236 wrote the keychain and read the file (the split this mirror exists for), while 2.1.274 on macOS reads and writes the keychain, and 2.1.272 on Linux reads and writes the scoped file. The file therefore stays authoritative for this package's own probes and for a container round; the keychain is what a host CLI on current macOS actually uses. Auth detection is a light file check of the scoped `.claude.json`'s `oauthAccount` — the CLI is never spawned just to probe. The probe also reconciles the two stores, so it obeys the same newer-wins rule as the spawn sites: it runs on every status read and every readiness check, and an unconditional mirror there would undo a containerized round's refresh just as surely.
+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.
 
@@ -117,9 +124,9 @@ The bundle patch registers the `claude-code` harness into the family core (`@kho
 
 **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 an optional `baseUrl` override) is injected — the global `~/.claude` is never touched and no `auth` verb ever runs.
+**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.** The host environment is a startup-time snapshot — a later `export ANTHROPIC_BASE_URL` in another shell has no effect until the host restarts; check the host's environment, not your current shell, when diagnosing routing. Every delegation logs the effective endpoint at info level (`subagent-claude: delegating via <endpoint>`), and a failed run's error text names it. `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.
+**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>
 

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: 1e4a67d84884dfd32c539207ad5bacbdafacadc0
-packages/local-agent-claude-code/README.md: 5e3eba982069f58e4f84a7e970b7bae2b684f3f1
+packages/local-agent-claude-code/README.en.md: 812398d9ac14b7cb0d77a584af9c7f510c716c3f
+packages/local-agent-claude-code/README.md: e026c9163886617cc80553db90f76e76ad4246c2

package/README.md

@@ -4,15 +4,15 @@
 
 把编码任务委派给本机的 Claude Code——思考、工具调用与回复实时流回，你的私人 `~/.claude` 分文不动。
 
-任意 dsh agent preset 都能发起委派：家族工具在 profile 根只挂一次，子会话全程可见、可中止、可续聊，每轮的账目（实际模型、token 用量、工具调用数）都真实回读。登录是作用域隔离的——插件只管理 `$DSH_HOME/local-agent/claude-code` 这一份目录，你的个人安装与凭据自始至终置身事外。[local-agent 家族](../local-agent/README.md) 的 Claude Code harness。
+点名本包 `./tool` 组合入口的 agent preset（如开发模式）即可发起委派：子会话全程可见、可中止、可续聊，每轮的账目（实际模型、token 用量、工具调用数）都真实回读。认证是端点凭据制（`baseUrl` + `apiKey`/`authToken`），作用域隔离——插件只管理 `$DSH_HOME/local-agent/claude-code` 这一份目录，你的个人安装与凭据自始至终置身事外。没有 OAuth 网页授权：容器轮与宿主轮用同一套凭据，容器里不需要再授权一次。[local-agent 家族](../local-agent/README.md) 的 Claude Code harness。
 
 <img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/08-local-agent.png" width="640" alt="设置 → 插件 → 插件配置里的 Local Agent 家族卡片，Claude Code 一行的状态点显示授权状态">
 
 ## 特性
 
-- **任意 preset 都能委派**——工具只在 profile 根挂载一次，无需逐 preset 变体。
+- **按会话授予的委派**——`subagent_claude_code` 工具是本包的 `./tool` 组合入口，由点名它的 agent 预设授予该预设的会话，无需逐 preset 变体。
 - **作用域隔离**——每个 Claude 进程都以 `$DSH_HOME/local-agent/claude-code` 为 `CLAUDE_CONFIG_DIR` 运行；你的个人 `~/.claude` 置身事外。
-- **一条命令完成登录指引**——`/claude-code login` 在会话中给出需要在你自己终端运行的完整命令（claude ≥2.1 只在 TTY 打印 OAuth URL，宿主不再 spawn 抓取），并监听作用域目录识别登录完成；`sessions`/`status`/`logout` 与 设置 → 本地 Agent 面板构成完整一族。
+- **端点凭据，没有网页授权**——在 bundle 行配好 `baseUrl` + `apiKey`（或 `authToken`）即已认证，状态面板直接显示已认证；每个命名 scope 可用自己的 `endpoint-auth.json` 覆盖部署级配置。`sessions`/`status`/`logout` 与 设置 → 本地 Agent 面板构成完整一族。
 - **续聊委派**——把结果自述的 `resume` 句柄传回，即可继续同一个 Claude 会话，并按轮记账。
 - **实时流镜像**——子会话实时镜像 Claude 的思考、工具调用与回复；中止会保留部分转写与真实 token 用量。
 - **模型回读与独立工作目录**——每轮从 stream-json 的 system/init 回读实际模型，写进委派记录；编排器可用 `cwd` 选项给每格独立目录，resume 换目录即拒绝。
@@ -27,13 +27,13 @@
 dsh plugin --profile web add @khorsheed/dsh-local-agent @khorsheed/dsh-local-agent-claude-code
 ```
 
-重启 web 实例后生效，然后在会话里运行一次 `/claude-code login`。卸载：
+重启 web 实例后，打开 设置 → 插件 里本包的卡片，在「认证」区填端点与 key 即可（也可预配在 profile 的本包配置行）；都不配则状态为未认证。卸载：
 
 ```sh
 dsh plugin --profile web remove @khorsheed/dsh-local-agent-claude-code
 ```
 
-作用域目录在卸载时刻意保留，重装无需重新登录；删除 `$DSH_HOME/local-agent/claude-code` 即可清除全部痕迹。
+作用域目录在卸载时刻意保留——`endpoint-auth.json` 与会话记录都在其中；删除 `$DSH_HOME/local-agent/claude-code` 即可清除全部痕迹。
 
 ## 配置
 
@@ -41,24 +41,28 @@ bundle 行接受这些可选字段：
 
 - `permissionMode`——`skip`（默认）传 `--dangerously-skip-permissions`，子代理写文件无需审批；`normal` 不传，需审批的动作（如写文件）被拒绝。
 - `model`——每轮委派以它起 CLI（`claude -p --model <模型>`）；不写就一个模型参数都不传。见下。
-- `baseUrl`——为子 CLI 设置 `ANTHROPIC_BASE_URL`（例如自部署路由器或代理）；缺省继承宿主进程环境。配置优先于环境。
-- `proxyUrl`——子 CLI 自身流量（模型调用与 OAuth 续期）的 HTTP 代理，provision 进作用域 `settings.json` 的 env 块；宿主进程环境不带代理时（例如 supervisor 拉起的实例不继承 shell export）用这项。
+- `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 分钟）。
 
-> **迁移说明**——live 轮次统一消费增量输出；旧 `liveMirrorGranularity: event | token` 配置键继续兼容读取，但不再影响行为，也不会改变运行中的进程。评测继续保留 exec；最终内容仍以 provider 完成项为准，包括工具记录和用量。
+> **迁移说明（下一发布线，破坏性变更）**——OAuth 网页授权整体移除：`/claude-code login` 不再存在，钥匙串/`.credentials.json` 协调随之删除；升级后首次启动会清扫作用域目录里残留的 OAuth 文件（`.credentials.json` 与 `.claude.json` 的 `oauthAccount` 标记），实测 claude 2.1.296 在两者并存时本就优先采用环境变量凭据。升级前先在设置卡或 profile 行配好 `baseUrl` + `apiKey`（官方端点的 console key 同样可用），否则升级即未认证。旧 `liveMirrorGranularity: event | token` 配置键继续兼容读取，但不再影响行为。
 
-### 默认模型（`model`）
+> **每个 scope 的覆盖**——`<作用域目录>/endpoint-auth.json`（0600）按字段覆盖，两层生效顺序：**scope 文件 > profile 的 YAML 行**，缺哪个字段就回落到配置值。一个只写 `apiKey` 的文件等于给这个 scope 换 key。设置卡「认证」区编辑的就是默认 scope 的这份文件（经家族 gateway 的 `endpointAuth`/`configureEndpoint` Remote，会话不在场也能读写）。`/claude-code logout` 清除的也是这个文件；凭据完全来自配置行时 logout 会拒绝并提示去改 profile。
 
-**不写 = 今天的表现。** 没有这个键时，本插件在 argv 上一个模型参数都不加：跑哪个模型由作用域 `settings.json` 的 `model` 决定，它也没有时由 claude 自己的默认决定（本插件从不猜它是什么）。
+### 可用模型（models.json）
 
-**写了 = 每轮委派以它起 CLI。** 新起一轮与续接（resume）、一次性与常驻（`live: true`）四种 argv 都带上 `--model <模型>`，位置在成员通道的 `--allowedTools …--` 之前——那个旗标是变长的，`--` 之后就是任务文本。
+设置卡「可用模型」区维护一份**有序模型短名单**：点「添加模型」从端点当前供应的目录（`GET /v1/models`）里勾选加入，所以列表里只会有端点真实供应的模型；拖动行调整顺序。**第一个模型就是默认模型**——每轮委派以它起 CLI（`claude -p --model <模型>`，常驻模式同一个旗标），优先级只低于成员会话级覆盖与委派级指定。列表保存在作用域目录的 `models.json`（每个命名 scope 可各有一份，与端点凭据同一套文件机制），编辑即保存，下一轮委派生效。
 
-一次性（exec）轮不改写作用域 `settings.json`——`--model` 每轮覆盖它，文件仍是你编辑的样子。常驻（live）spawn 会把成员的生效模型暂写进该文件（`--resume` 重挂时 CLI 认文件里的模型而不认 `--model` 旗标），绑定空模型的 spawn 前再还原；状态页与设置卡读到的「CLI 配置」层永远是你自己配的值，不会读到某个成员留下的暂写。
+**留空 = 既有行为。** 列表为空时，模型照旧由这些层决定：插件配置或设置的 `model` 键 → 作用域 `settings.json` 的 `model` → CLI 内置默认（本插件从不猜它是什么）。一次性（exec）轮不改写作用域 `settings.json`；常驻（live）spawn 会把生效模型暂写进该文件（`--resume` 重挂认文件不认旗标），绑定空模型的 spawn 前再还原。
 
-设置卡「默认模型」修改后续轮次使用的 provider 配置。共享选择器展示当前作用域的模型目录、发现来源和完整性，并保留按需填写模型 ID 的入口。清空选择后跟随有效配置及默认值链。保存不会打断当前轮次，也无需重载；共享选择器不可用时，卡片保留文本输入兜底。成员级模型和推理强度修改使用下文的持久控制面。
+**评测快照（effectiveSettings）** 的 model 字段同一条解析链：名单第一项 → `model` 键 → 作用域文件；名单进不了快照（它是偏好不是公平性旋钮），回读的 `observedModel` 才是实测证据。run 冻结条件后中途改名单，下一轮的模型回读会发现声明 ≠ 实测并判 misattributed（冻结决策 5）。
 
-模型读面现已读取 Claude 原生 `initialize` 目录，保留选择别名、显示名、解析名称和支持的 effort 值。目录共用 core 缓存和刷新订阅，刷新失败保留成功数据，并独立标识历史建议。此 scoped 控制查询不发送用户任务、不写模型设置。旧 CLI 缺少目录时显示不支持；原生候选不证明账号权限。共用模型菜单和成员 effort 控制已接入。运行中选择排到下一完整轮次（含工具续跑）；core 统一持有当前/待生效配置、撤销与重试，冻结评测成员禁止变更。
+成员会话里的 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` 在新进程上续起。
 
@@ -66,20 +70,19 @@ bundle 行接受这些可选字段：
 
 **这不是评测的缺口。** 评测 run 的条件在建立时冻结：run 跑到一半改这个键，下一轮的模型回读会发现声明模型 ≠ 实测模型，run 直接判为 misattributed 而失败（冻结决策 5）。「切了新 run 照新走、进行中的 run 不被悄悄换掉」是设计出来的，不是漏掉的。
 
-⚠️ `skip` 没有 OS 级沙箱——子进程可以写宿主用户能写的任何地方，包括工作区之外；作用域登录的 OAuth token 会发送给 `baseUrl` 指向的端点。委派需要限制时改用 `normal`；`baseUrl` 只指向你信任的地址。
+⚠️ `skip` 没有 OS 级沙箱——子进程可以写宿主用户能写的任何地方，包括工作区之外；端点凭据会发送给 `baseUrl` 指向的端点。委派需要限制时改用 `normal`；`baseUrl` 只指向你信任的地址。
 
-**评测快照（effectiveSettings）。** 本 harness 向注册表声明一份实时读取的公平性设置快照，供评测条件哈希使用：drive（exec/live）、permissionMode（skip/normal，插件配置）、端点是否固定（按 provider 的解析顺序——配置项优先于宿主进程环境的 `ANTHROPIC_BASE_URL`，只报主机名）、已配置模型（先看插件配置的 `model` 键——它每轮覆盖文件；没有才读作用域 `settings.json` 的 `model`；CLI 自身的默认模型由 CLI 决定，绝不猜值，都没有就不给字段）、CLI 版本（`claude --version`，按可执行文件路径+mtime 缓存；探测不到即字段缺位）。`/claude-code status` 与 `LocalAgentStatus` Remote 附带同一份快照。
+**评测快照（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 附带同一份快照。
 
 ## Compatibility
 
-- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：✅ 公开 API 兼容。生成中的内容走 local-agent 瞬时 Remote 与公开 Conversation 节点；增量耐久恢复检查点负责落盘，最终原生消息保留转写与用量语义。浏览器 P95 验收由 room 协调者提案跟踪。minHost 0.1.5-rc.1——更旧宿主请停留在前一发布线。
-- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.5-rc.1）
+- 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 改为每次执行唯一。
 
 ## 已知限制
 
-- **macOS logout 只删配置**——keychain 条目留给 CLI 自己的 `claude auth logout`；下次登录会重写同一槽位，残留无害。
-- **同一次授权不能被宿主轮与容器轮共用**——macOS 上两者用的是不同存储，任一侧轮换都会作废另一侧的 token family。容器化的条件用自己的命名 scope，见「容器内委派」。
-- **Linux 凭据不隔离**（上游 bug #47661）——即使作用域目录没有凭据，claude 也会读默认 `~/.claude/.credentials.json`。
+- **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` 可通过挂载工具行的组合委派。
 
@@ -92,22 +95,22 @@ bundle 行接受这些可选字段：
 
 **工具调用计数。** 每轮 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}}`，与镜像出的工具卡片逐个对得上。
 
-**命名 scope。** `/claude-code login --scope <名>` 在 `<homesRoot>/claude-code@<名>` 里另开一份 `CLAUDE_CONFIG_DIR`：登录的 argv 由**被登录的那份目录**现算（`env CLAUDE_CONFIG_DIR=… claude auth login` 的赋值压过 spawn env，写死缺省目录会让 `--scope` 登错地方）。claude 的 keychain 项按配置目录路径哈希，命名 scope 因此自动拿到自己的 keychain 项——四家里唯一天然按路径隔离的凭据。带 scope 的委派用该目录跑 `claude -p`、按它做 keychain↔文件协调、从它回读；只走 exec。
+**端点凭据模型。** 认证只有一种形态：`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 时代「重新登录改写标记」语义一一对应。
 
-**容器内委派。** 编排器可以经门面 `DelegationCallOptions.exec`（`{ container, workdir, env? }`）让本轮跑在一个**已取得的容器**里：argv 变成 `docker exec -w <workdir> [-e NAME…] <container> claude -p …`，其余（stream-json 解析、settle、记录）逐字节不变。`env` 必须给出容器内的 `CLAUDE_CONFIG_DIR`，调用方把宿主作用域目录 rw bind 到那条路径上。实测评测镜像里的 claude 2.1.272：容器内的 CLI **读写 `<CLAUDE_CONFIG_DIR>/.credentials.json`**，它整棵状态树（`projects/`、`sessions/` 等）也落在那里；上游 #47661 那种「Linux 写作用域目录、读默认 home」的老行为不描述这个版本。每次 spawn 前的凭据协调照常在**宿主**作用域目录上跑，续期结果因此经挂载对容器可见——而且它是**新者胜，不是单向镜像**，因为单元是同一个文件的**第二个写者**。单元里的 CLI 没有 keychain，只能在挂进去的文件里就地轮换凭证；此时若无条件地把 keychain 盖到文件上，下一轮拿到的就是单元已经用掉的 refresh token，端点拒绝，CLI 随即**清空该文件**——整台实例随之登出，因为那个文件就是实例的凭据。所以协调只在 keychain 那份不比文件旧时才写（以 access token 过期时间为准；任一侧没有过期时间就仍由 keychain 写，不可用的文件永远不会赢）。挂载保持读写还有第二个理由：本轮的会话记录落在同一目录的 `projects/` 下，评测的模型回读正是从这条挂载的宿主侧解析它们。容器轮固定走 exec 一次性驱动，且不声明成员桥。
+**命名 scope。** 每个命名 scope 在 `<homesRoot>/claude-code@<名>` 另开一份 `CLAUDE_CONFIG_DIR`：自己的 `endpoint-auth.json`、自己的会话记录、自己的凭据等级。scope 文件缺省即跟随部署级配置——这正是一次配置、全部 scope 可用的来源。带 scope 的委派用该目录跑 `claude -p`、从它回读；只走 exec。
 
-**容器轮必须用自己的 scope，这条纪律不是可选项。** claude 是这几家里唯一有两个凭据存储的，而实测 macOS 2.1.274 它们并没有同一个读者：**宿主 CLI 读写 keychain**，而单元里的 CLI——Linux、没有 keychain——读写挂进去的文件。同一次授权被两个存储各续一次，就是被续了两次；服务端轮换一次性 refresh token 的做法是把整个 **token family 作废**，于是没有最后续到的那一侧手里就是一个死 token。端到端实测过：容器轮轮换了文件，紧接着的宿主轮报 `OAuth session expired and could not be refreshed`，而文件自己的 access token 离过期还有好几个小时，只能重登才能恢复。新者胜保住的是**文件那一侧**（单元与所有状态探针读的就是它），但没有任何东西能把单元的轮换写回 keychain（`security add-generic-password` 只能把密文放进 argv，因此否决）。所以容器侧与宿主侧必须是**两次独立授权**：每个容器化的 claude 条件用自己的命名 scope，用 `/claude-code login --scope <名>` 授权一次，且**永不**在该 scope 上跑宿主轮。评测会在取单元之前就拒绝违反这条的计划。**注意作用域 `settings.json` 里的宿主专用项**：实测那里给宿主守护进程用的 `https_proxy` 在容器内指向不存在的地址，本轮当场 `Connection refused`——挂进去的目录要由调用方备好。
+**容器内委派。** 编排器可以经门面 `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 与基于文件的 logout
-src/records.ts              认证探测与作用域目录的会话记录列表
+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` 工具是家族自有工具（`@khorsheed/dsh-local-agent-tool-subagent`）：官方子集（`description`/`prompt`）加一个可选 `resume` 参数。
-
-**作用域隔离。** macOS 上真实凭据在系统 keychain 的哈希条目里（`Claude Code-credentials-<sha256(configDir)[:8]>`，以作用域目录路径为键）——基于文件的 logout 够不到它，但下次登录会重写同一个槽位。**CLI 自己用哪个存储是随版本变的，且由实测而非假定确定**：2.1.236 写 keychain、读文件（这个镜像正是为那条分裂而存在），而 2.1.274 在 macOS 上读写 keychain，2.1.272 在 Linux 上读写作用域文件。因此文件对本包自己的探针与容器轮仍是权威；keychain 才是当前 macOS 上宿主 CLI 真正用的那个。认证探测只做轻量文件检查——看作用域 `.claude.json` 的 `oauthAccount`，绝不为了探测而 spawn CLI。该探测同样会协调两个存储，因此遵守与 spawn 点一致的新者胜规则：它在每次状态读与每次就绪检查时都会跑，那里若是无条件镜像，同样会把容器轮的续期抹掉。
+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` 字段），绝不取自目录名。设置面板呈现同一份列表并收窄到当前工作区。
 
@@ -117,9 +120,9 @@ bundle patch 把 `claude-code` harness 注册进家族 core（`@khorsheed/dsh-lo
 
 **模型体验。** 子会话是委派会话工作区内一个全新的一次性 `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`（与可选的 `baseUrl` 覆盖），绝不碰全局 `~/.claude`，绝不执行任何 `auth` 命令。
+**长驻驱动（`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` 命令。
 
-**配置注意。** 宿主环境是启动时的快照——之后在别的 shell 里 `export ANTHROPIC_BASE_URL` 对运行中的进程无效，除非重启宿主；排查路由异常时检查宿主的实际环境而非你当前的 shell。每次委派在 info 级别记录有效端点（`subagent-claude: delegating via <endpoint>`），失败运行的报错文本会点名它。`skip` 作为默认是因为一次性 CLI 子代理没有审批面；委派需要被限制时，给宿主自身套沙箱（例如在沙箱化工作区内运行 dsh 宿主）。
+**配置注意。** 每次委派在 info 级别记录有效端点（`subagent-claude: delegating via <endpoint>`），失败运行的报错文本会点名它；排查路由异常时看这份日志与 profile 行，而不是你当前 shell 的环境。`skip` 作为默认是因为一次性 CLI 子代理没有审批面；委派需要被限制时，给宿主自身套沙箱（例如在沙箱化工作区内运行 dsh 宿主）。
 
 </details>
 

package/cordis.patch.yml

@@ -8,25 +8,24 @@
 # installed explicitly alongside this bundle, or this provider stays pending.
 # No other patch inserts the core row id.
 #
-# Two rows are inserted:
-#   - local-agent-claude-code: this bundle's plugin registers the
-#     `claude-code` harness (CLAUDE_CONFIG_DIR scoped home,
-#     `claude auth login` browser flow, project-file session records).
-#   - tool-subagent-claude-code-local: the family-owned delegation tool
-#     (schema description/prompt plus optional resume) over the `claude-local`
-#     provider. The toolName is `subagent_claude_code` — the family takes the
-#     model-facing name: the official preset row of that name ships
-#     `disabled: true`, and this patch disables it too (below) so a community
-#     install can never register two `subagent_claude_code` tools. A user who
-#     deliberately re-enables the official row in their own preset layer gets
-#     a loud duplicate-name conflict — by design, they must choose one. The
-#     family tool adds continuation: a later round may pass the dsh child
-#     session id returned by the first delegation to continue the same claude
-#     conversation.
+# Exactly ONE row is inserted: the provider (this bundle's plugin registers the
+# `claude-code` harness — CLAUDE_CONFIG_DIR scoped home, `claude auth login`
+# browser flow, project-file session records). The `subagent_claude_code`
+# delegation tool is no longer a profile-root row: since the family fold it
+# ships as this package's `./tool` composition entry
+# (`name: '@khorsheed/dsh-local-agent-claude-code/tool'` in an agent preset),
+# granted per session — the dev preset's `tool-subagent-claude-code-local` row
+# is the grant point. The family keeps the official model-facing name
+# `subagent_claude_code`: the official preset row of that name ships
+# `disabled: true`, and this patch disables the profile-root row too (below)
+# so a community install can never register two `subagent_claude_code` tools.
+# A user who deliberately re-enables the official row in their own preset
+# layer gets a loud duplicate-name conflict — by design, they must choose one.
+# The family tool keeps its continuation parameter: a later round may pass the
+# dsh child session id returned by the first delegation to continue the same
+# claude conversation.
 #
-# The tool mounts at the profile root, so every agent preset can delegate
-# without per-preset variants. The provider starts no claude process until a
-# tool call or /claude-code login.
+# The provider starts no claude process until a tool call or /claude-code login.
 
 - id: tool-subagent-claude-code
   disabled: true
@@ -34,9 +33,3 @@
 - insert:
     - id: local-agent-claude-code
       name: '@khorsheed/dsh-local-agent-claude-code'
-
-    - id: tool-subagent-claude-code-local
-      name: '@khorsheed/dsh-local-agent-tool-subagent'
-      config:
-        provider: claude-local
-        toolName: subagent_claude_code