relay-dsh-plugin-claude 0.1.3 → 0.1.4

package/README.md

@@ -6,23 +6,36 @@
 [![GitHub stars](https://img.shields.io/github/stars/yangbobo2021/relay-dsh-plugin-claude?style=flat)](https://github.com/yangbobo2021/relay-dsh-plugin-claude/stargazers)
 [![MIT license](https://img.shields.io/github/license/yangbobo2021/relay-dsh-plugin-claude)](LICENSE)
 [![DSH compatibility](https://img.shields.io/badge/DSH-0.1.1--rc.2-2f7d68)](https://github.com/deepseek-ai/deepseek-harness)
-[![npm provenance](https://img.shields.io/badge/npm_provenance-verified-2f9e44)](https://www.npmjs.com/package/relay-dsh-plugin-claude/v/0.1.1-rc.2)
+[![npm provenance](https://img.shields.io/badge/npm_provenance-verified-2f9e44)](https://www.npmjs.com/package/relay-dsh-plugin-claude/v/0.1.4)
 
 English | [中文](README.zh.md)
 
 **npm package:** [`relay-dsh-plugin-claude`](https://www.npmjs.com/package/relay-dsh-plugin-claude)
 · [All Relay DSH plugins](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/dsh-plugins.md)
 
-[![Live npm-installed Relay plugins in official DSH](https://raw.githubusercontent.com/yangbobo2021/Relay/codex/relay-foundation/docs/media/dsh-plugin-suite-demo.gif)](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/dsh-plugins.md)
+**Run Claude Code inside official DeepSeek Harness without switching interfaces
+or maintaining a DSH fork.**
 
-*Real npm-installed demo on official DSH: live Codex and Claude replies, a
-workspace file preview, and an executed terminal command. [Watch the H.264
-MP4](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/media/dsh-plugin-suite-demo.mp4?raw=1).*
+`relay-dsh-plugin-claude` adds **Claude Code as a native conversation backend**
+to the official [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+(DSH) Web UI. You keep DSH's workspace, conversation history, composer,
+approvals, questions, and tool display while each DSH Session continues one
+Claude Agent SDK session. The plugin installs independently; no Relay checkout
+is required.
 
-`relay-dsh-plugin-claude` adds **Claude Code as a conversation backend** to the
-official [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
-(DSH) Web UI. After installation, **Claude Code** appears in DSH's New Session
-mode menu. One DSH Session is bound to one Claude Agent SDK session.
+## Try It on Official DSH
+
+Complete normal Claude Code authentication with `claude` before the first
+Session. The install requires Node.js 22.13 or newer and `pnpm` on `PATH`. Then
+stop DSH Web, install the tested release candidate, and restart DSH:
+
+```bash
+npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add relay-dsh-plugin-claude@next
+npx @deepseek-ai/dsh@0.1.1-rc.2 web
+```
+
+Open **New Session**, select a workspace, choose **Claude Code** from the mode
+menu, and send a message.
 
 ![Codex and Claude Code in the DSH New Session mode menu](docs/images/dsh-new-session-backends.jpg)
 
@@ -30,6 +43,13 @@ The screenshot was captured from official DSH `0.1.1-rc.2` with the Codex and
 Claude plugins installed. If you install only this plugin, only **Claude Code**
 is added.
 
+[Review all Relay DSH plugins](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/dsh-plugins.md)
+· [report an install result](https://github.com/yangbobo2021/relay-dsh-plugin-claude/issues)
+
+If this removes an interface switch from your DSH workflow,
+[star this plugin](https://github.com/yangbobo2021/relay-dsh-plugin-claude).
+That signal helps other DSH users find a tested Claude Code backend.
+
 ## Do I Need This Plugin?
 
 Install it when you want to:
@@ -45,7 +65,7 @@ Install it when you want to:
 You do not need it to use DSH's standard agents. It also does not add Relay
 Events, file browsing, or a terminal panel. Those are separate optional plugins.
 
-## Quick Start With Official DSH
+## Complete Setup and Compatibility
 
 The steps below were validated with:
 
@@ -89,7 +109,7 @@ Use `@latest` to install the current stable release:
 npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add relay-dsh-plugin-claude@latest
 ```
 
-At the time of writing, `latest` resolves to stable version `0.1.0`. The linked
+At the time of writing, `latest` resolves to stable version `0.1.4`. The linked
 npm page is the source of truth for the current version.
 
 #### npm prerelease (recommended during DSH preview)
@@ -102,7 +122,7 @@ contains the latest model-selection synchronization fix:
 npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add relay-dsh-plugin-claude@next
 ```
 
-At the time of writing, `next` resolves to `0.1.1-rc.2`.
+At the time of writing, `next` resolves to `0.1.4`.
 
 #### GitHub development build
 
@@ -116,7 +136,7 @@ npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add github:yangbobo2021/rel
 full Commit SHA instead. For example:
 
 ```bash
-npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add github:yangbobo2021/relay-dsh-plugin-claude#v0.1.1-rc.2
+npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add github:yangbobo2021/relay-dsh-plugin-claude#v0.1.4
 ```
 
 The official DSH CLI initializes the `web` Profile if it does not exist, asks
@@ -151,6 +171,31 @@ at startup, so restarting after installation, update, or removal is required.
 There is no separate activation command. A successful install plus a DSH restart
 activates the bundle and registers the managed **Claude Code** mode automatically.
 
+### 5. Import an existing Claude terminal Session
+
+1. Open the target Workspace or one of its Sessions in DSH.
+2. Select **Import Claude Sessions** below the Workspace list.
+3. Review the full Session IDs, titles, source paths, activity times, and import
+   status. Select one, several, or all Sessions.
+4. Select **Import selected**, then open the imported DSH Session.
+5. Send the next message and confirm that it continues the same native Claude
+   Session.
+
+The selector uses the Claude Agent SDK's public Session APIs and matches the
+terminal `/resume` scope. It excludes worktrees, SDK/headless Sessions,
+already-bound Sessions, and Sessions outside the exact registered Workspace.
+The imported history is a one-time presentation snapshot of user text, visible
+assistant text and thinking, and completed textual tool activity. Unknown or
+private blocks are skipped; Claude's source transcript is never modified.
+
+The SDK inventory does not expose a durable running/idle status. Avoid writing
+the same Session from another Claude client while continuing it in DSH. If
+resume fails, DSH keeps the exact imported binding for retry and never silently
+creates a replacement Session. Import is unavailable with the CLI fallback.
+See
+[`docs/spec/claude-native-session-import.md`](docs/spec/claude-native-session-import.md)
+for the complete contract and delivery cases.
+
 ## What Works
 
 - One persistent Claude Agent SDK session per DSH Session
@@ -161,7 +206,47 @@ activates the bundle and registers the managed **Claude Code** mode automaticall
   final answer
 - DSH approval and user-question flows
 - Interruption and session continuation
+- Selective import and exact-ID continuation of existing Claude terminal Sessions
 - Generic DSH tools exposed through an in-process Claude SDK MCP server
+- Dedicated native Claude `Glob` and `Grep` search tools on every SDK query
+- Pre-persistence redaction of sensitive environment values from tool output
+
+### Sensitive environment output
+
+Before each new or resumed SDK turn, the plugin resolves Claude's effective
+environment and classifies credential-bearing variable names such as `SECRET`,
+`TOKEN`, `PASSWORD`, and `API_KEY`. Exact occurrences of those values in tool
+results are replaced before the result reaches Claude, DSH activity, or the
+native Claude JSONL transcript. Variables explicitly listed in Claude sandbox
+credential settings are protected as well. Ordinary environment values and
+successful tool outputs without a match are left unchanged.
+
+This protection covers successful tool results; it does not rewrite user
+prompts, tool inputs, arbitrary values that are not identifiable from host
+configuration, or SDK execution failures without a replaceable tool output.
+See
+[`docs/spec/claude-tool-output-redaction.md`](docs/spec/claude-tool-output-redaction.md)
+for the complete contract and acceptance cases.
+
+### Explicit local Claude plugins
+
+Trusted Host configuration can load an uninstalled local Claude plugin into
+business conversations by setting `claudePlugins` on this DSH plugin:
+
+```yaml
+config:
+  claudePlugins:
+    - type: local
+      path: /absolute/path/to/plugin
+```
+
+The order and optional `skipMcpDiscovery` Boolean are forwarded to every new and
+resumed Claude Agent SDK query. Hidden title-generation Sessions use no local
+plugins. A non-empty list is rejected when the CLI fallback is active because
+the CLI backend cannot honor this SDK option. Local plugins execute as the DSH
+user, so configure only reviewed paths. See
+[`docs/spec/claude-local-plugins.md`](docs/spec/claude-local-plugins.md) for the
+full contract and acceptance cases.
 
 Tools execute through the owning Agent's DSH tool runtime and remain subject to
 DSH permissions and Claude approval behavior. The tool bridge requires the

package/README.zh.md

@@ -6,29 +6,48 @@
 [![GitHub Stars](https://img.shields.io/github/stars/yangbobo2021/relay-dsh-plugin-claude?style=flat)](https://github.com/yangbobo2021/relay-dsh-plugin-claude/stargazers)
 [![MIT 许可证](https://img.shields.io/github/license/yangbobo2021/relay-dsh-plugin-claude)](LICENSE)
 [![DSH 兼容版本](https://img.shields.io/badge/DSH-0.1.1--rc.2-2f7d68)](https://github.com/deepseek-ai/deepseek-harness)
-[![npm 来源证明](https://img.shields.io/badge/npm_provenance-verified-2f9e44)](https://www.npmjs.com/package/relay-dsh-plugin-claude/v/0.1.1-rc.2)
+[![npm 来源证明](https://img.shields.io/badge/npm_provenance-verified-2f9e44)](https://www.npmjs.com/package/relay-dsh-plugin-claude/v/0.1.4)
 
 [English](README.md) | 中文
 
 **npm 包名：** [`relay-dsh-plugin-claude`](https://www.npmjs.com/package/relay-dsh-plugin-claude)
 · [全部 Relay DSH 插件](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/dsh-plugins.zh.md)
 
-[![在官方 DSH 中实装运行的 Relay 插件](https://raw.githubusercontent.com/yangbobo2021/Relay/codex/relay-foundation/docs/media/dsh-plugin-suite-demo.gif)](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/dsh-plugins.zh.md)
-
-*演示来自官方 DSH 上的真实 npm 安装：Codex 与 Claude 返回真实回复，Files
-预览工作区文件，Terminal 实际执行命令。[观看 H.264
-MP4](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/media/dsh-plugin-suite-demo.mp4?raw=1)。*
+**无需切换界面或维护 DSH Fork，直接在官方 DeepSeek Harness 中运行 Claude
+Code。**
 
 `relay-dsh-plugin-claude` 为官方
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）Web
-界面增加 **Claude Code 对话后端**。安装后，DSH 的新建会话模式菜单中会出现
-**Claude Code**。每个 DSH Session 会绑定一个 Claude Agent SDK Session。
+界面增加原生 **Claude Code 对话后端**。你可以继续使用 DSH 的工作区、对话
+历史、输入框、审批、提问和工具展示；每个 DSH Session 会持续绑定一个 Claude
+Agent SDK Session。本插件可独立安装，不需要下载 Relay 仓库。
+
+## 在官方 DSH 中立即试用
+
+首次创建 Session 前，请先运行 `claude` 完成 Claude Code 的正常认证。安装
+要求 Node.js 22.13 或更高版本，并且 `pnpm` 已加入 `PATH`。然后停止 DSH Web，
+安装经过测试的候选版本并重新启动：
+
+```bash
+npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add relay-dsh-plugin-claude@next
+npx @deepseek-ai/dsh@0.1.1-rc.2 web
+```
+
+打开 **New Session**，选择工作区，再从模式菜单中选择 **Claude Code** 并发送
+消息。
 
 ![DSH 新建会话菜单中的 Codex 和 Claude Code](docs/images/dsh-new-session-backends.jpg)
 
 上图来自安装了 Codex 和 Claude 插件的官方 DSH `0.1.1-rc.2`。如果只安装
 本插件，菜单中只会新增 **Claude Code**。
 
+[查看全部 Relay DSH 插件](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/dsh-plugins.zh.md)
+· [反馈安装结果](https://github.com/yangbobo2021/relay-dsh-plugin-claude/issues)
+
+如果它能让你少切换一个界面，欢迎
+[Star 本插件](https://github.com/yangbobo2021/relay-dsh-plugin-claude)。
+这些真实信号能帮助更多 DSH 用户找到经过验证的 Claude Code 后端。
+
 ## 什么情况下需要这个插件？
 
 以下情况适合安装：
@@ -44,7 +63,7 @@ MP4](https://github.com/yangbobo2021/Relay/blob/codex/relay-foundation/docs/medi
 使用 DSH 标准 Agent 不需要安装本插件。本插件也不提供 Relay Events、文件
 浏览和终端面板，这些能力由其他可选插件提供。
 
-## 基于官方 DSH 的快速安装
+## 完整安装与兼容性说明
 
 以下步骤已经在这些版本上实际验证：
 
@@ -85,7 +104,7 @@ claude
 npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add relay-dsh-plugin-claude@latest
 ```
 
-本文更新时，`latest` 指向稳定版 `0.1.0`。最新版本请以链接中的 npm 页面
+本文更新时，`latest` 指向稳定版 `0.1.4`。最新版本请以链接中的 npm 页面
 为准。
 
 #### npm 预发布版（DSH 预览阶段推荐）
@@ -97,7 +116,7 @@ npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add relay-dsh-plugin-claude
 npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add relay-dsh-plugin-claude@next
 ```
 
-本文更新时，`next` 指向 `0.1.1-rc.2`。
+本文更新时，`next` 指向 `0.1.4`。
 
 #### GitHub 开发版
 
@@ -111,7 +130,7 @@ npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add github:yangbobo2021/rel
 SHA。例如：
 
 ```bash
-npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add github:yangbobo2021/relay-dsh-plugin-claude#v0.1.1-rc.2
+npx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add github:yangbobo2021/relay-dsh-plugin-claude#v0.1.4
 ```
 
 官方 DSH CLI 会在需要时初始化 `web` Profile，通过 `pnpm` 安装所选软件包和
@@ -143,6 +162,27 @@ npx @deepseek-ai/dsh@0.1.1-rc.2 web
 插件不需要单独的激活命令。安装成功并重启 DSH 后，Bundle 会自动激活，
 并注册由插件管理的 **Claude Code** 模式。
 
+### 5. 导入已有的 Claude 终端会话
+
+1. 在 DSH 中打开目标工作区或其中一个 Session。
+2. 点击工作区列表下方的 **导入 Claude 会话**。
+3. 检查完整 Session ID、标题、源路径、活动时间和导入状态，然后选择一个、
+   多个或全部会话。
+4. 点击 **导入所选会话**，再打开导入后的 DSH Session。
+5. 发送下一条消息，确认它继续的是同一个原生 Claude Session。
+
+选择器只使用 Claude Agent SDK 的公开 Session API，其范围与终端 `/resume`
+一致。它会排除 worktree、SDK/headless、已经绑定以及不属于当前精确注册工作区
+的 Session。导入历史是一次性的展示快照，包含用户文本、可见的助手文本与
+thinking，以及已有结果的文本工具活动。未知或私有块会被跳过，Claude 源转录
+不会被修改。
+
+SDK 列表不提供持久的 running/idle 状态。通过 DSH 继续会话时，应避免另一个
+Claude 客户端同时写入同一个 Session。如果恢复失败，DSH 会保留原始绑定供
+重试，绝不会静默创建替代 Session。CLI fallback 不支持导入。完整契约和交付
+用例见
+[`docs/spec/claude-native-session-import.md`](docs/spec/claude-native-session-import.md)。
+
 ## 支持的能力
 
 - 每个 DSH Session 持续绑定一个 Claude Agent SDK Session
@@ -152,7 +192,40 @@ npx @deepseek-ai/dsh@0.1.1-rc.2 web
 - 在对话中持久展示 Claude 最终回答所引用的工作区图片
 - DSH 原生审批和用户提问流程
 - 中断和会话延续
+- 选择性导入已有 Claude 终端会话，并通过原始 ID 继续
 - 通过进程内 Claude SDK MCP Server 提供通用 DSH 工具
+- 在每次 SDK 查询中启用 Claude 原生 `Glob` 与 `Grep` 专用搜索工具
+- 在工具结果持久化前脱敏其中的敏感环境变量值
+
+### 敏感环境变量输出脱敏
+
+每次新建或恢复 SDK turn 前，插件都会解析 Claude 的有效环境，并识别变量名中
+含有 `SECRET`、`TOKEN`、`PASSWORD`、`API_KEY` 等凭据特征的值。工具结果中
+与这些值完全相同的内容，会在进入 Claude、DSH activity 或 Claude 原生 JSONL
+转录之前替换。Claude sandbox 凭据设置中显式列出的环境变量也会受到保护。
+普通环境值及没有命中的成功工具输出保持不变。
+
+该保护仅覆盖成功工具结果，不会改写用户消息、工具输入、无法从 Host 配置
+识别的任意内容，或 SDK 未提供可替换输出的执行失败。完整契约与验收用例见
+[`docs/spec/claude-tool-output-redaction.md`](docs/spec/claude-tool-output-redaction.md)。
+
+### 显式加载本地 Claude 插件
+
+可信的 Host 配置可以通过本 DSH 插件的 `claudePlugins` 字段，将未安装的
+本地 Claude 插件加载到业务对话中：
+
+```yaml
+config:
+  claudePlugins:
+    - type: local
+      path: /absolute/path/to/plugin
+```
+
+插件顺序和可选的 Boolean 字段 `skipMcpDiscovery` 会传递给每次新建及恢复的
+Claude Agent SDK 查询。标题生成等隐藏辅助 Session 不加载这些插件。CLI
+fallback 无法实现该 SDK 能力，因此非空列表会被明确拒绝。因为本地插件以
+DSH 用户身份运行，只应配置经过审查的路径。完整契约和验收用例见
+[`docs/spec/claude-local-plugins.md`](docs/spec/claude-local-plugins.md)。
 
 工具通过当前 Agent 的 DSH 工具运行时执行，并继续受到 DSH 权限和 Claude
 审批机制约束。工具桥接依赖默认 SDK 后端。如果开发者明确选择 CLI fallback，

package/docs/spec/claude-local-plugins.md

@@ -0,0 +1,56 @@
+# Claude Local Plugin Loading
+
+## Contract
+
+The DSH host configuration may provide `claudePlugins`, an ordered array of
+Claude Agent SDK local-plugin descriptors:
+
+```yaml
+config:
+  claudePlugins:
+    - type: local
+      path: /absolute/path/to/plugin
+      skipMcpDiscovery: false
+```
+
+Each descriptor must contain `type: local` and a non-empty `path`.
+`skipMcpDiscovery`, when present, must be Boolean. Unknown fields are rejected.
+Relative paths remain relative and are interpreted by the Claude Agent SDK.
+Relay does not check path existence before the SDK starts, avoiding a separate
+check/use result from the SDK's authoritative load.
+
+The configuration is trusted startup configuration: a local Claude plugin can
+load instructions, hooks, agents, commands, Skills, and MCP definitions with the
+same operating-system access as the Claude process. It is not accepted from a
+conversation message or model output.
+
+## Session behavior
+
+- A configured list is cloned into every new business Claude SDK Session.
+- A linked DSH Session resumed after a Host restart receives the current Host
+  list, including when its older link record predates this option.
+- Every query for that Claude Session carries the same ordered list, including
+  resumed queries.
+- Message-level plugin replacement is rejected before `query()`; conversation
+  input and model output cannot introduce a local plugin path.
+- An explicit empty list disables configured plugins for that Session.
+- Hidden auxiliary Sessions, including title generation, always use an explicit
+  empty list. They must not run user plugin hooks or discover user plugin Skills.
+- With no configured list, Relay omits the SDK `plugins` option and preserves
+  existing behavior.
+- The CLI backend cannot load SDK local-plugin paths. It rejects a non-empty list
+  with `CLAUDE_LOCAL_PLUGINS_REQUIRE_SDK` instead of silently dropping it.
+
+## Delivery acceptance
+
+| ID | Scenario | Required result |
+| --- | --- | --- |
+| LP1 | New Session | Runtime creation and first SDK query receive the exact ordered descriptors. |
+| LP2 | Continued Session | A later query uses `resume` and receives the same descriptors. |
+| LP3 | Host restart | Runtime resume receives the current configured descriptors without relying on the persisted link record. |
+| LP4 | No configuration | Runtime and SDK options do not gain a `plugins` property. |
+| LP5 | Auxiliary Session | Runtime creation receives `plugins: []`. |
+| LP6 | Invalid configuration | Relay fails before creating a Session or invoking `query()`. |
+| LP7 | CLI backend | A non-empty descriptor list fails explicitly and spawns no process. |
+| LP8 | Real SDK load | With no CLI installation or setting source, SDK init reports the target plugin and namespaced Skill exactly once. |
+| LP9 | Message injection | A message-level `plugins` field fails before SDK `query()` and does not alter the Session list. |

package/docs/spec/claude-native-session-import.md

@@ -0,0 +1,114 @@
+# Native Claude Session Import
+
+This specification defines how `relay-dsh-plugin-claude` discovers an existing
+Claude terminal Session, creates its DSH presentation, and continues the exact
+same native Session. It is the delivery contract for migration case
+`CLD-SES-004`.
+
+## Supported backend and source boundary
+
+Import is available only when the active Claude Agent SDK exposes the public
+`listSessions`, `getSessionInfo`, and `getSessionMessages` functions. The Host
+must call those APIs and must not parse Claude's private JSONL storage. The CLI
+fallback reports `CLAUDE_SESSION_IMPORT_UNAVAILABLE`; it must not return an empty
+or fabricated inventory.
+
+The scan calls `listSessions` with the exact registered DSH Workspace path,
+`includeWorktrees: false`, and `includeProgrammatic: false`. This matches the
+Claude terminal `/resume` inventory: SDK/headless, daemon, worktree, sidechain,
+and other-Workspace Sessions are not import candidates. Every returned `cwd` is
+canonicalized and checked again by the plugin because SDK filtering alone is not
+the authorization boundary.
+
+The public SDK inventory is a point-in-time snapshot. It does not expose a
+durable running/idle field, so DSH must not label a candidate as completed or
+promise that another Claude client is no longer writing it.
+
+## Inventory and selection
+
+Each candidate exposes the full native Session ID, deterministic title, source
+path, source `lastModified`, and either `ready` or `recoverable` status. The
+ordering is descending source activity time with Session ID as a deterministic
+tie-breaker. Already-bound Sessions remain in aggregate counts but are not
+selectable or disclosed as candidates. Sessions outside the exact Workspace are
+neither counted nor disclosed.
+
+The UI defaults to every eligible candidate and supports selecting one, several,
+all, or none. An empty selection cannot be submitted. The request carries the
+exact selected `sessionIds`. Before creating or mutating a DSH Session, the Host
+rescans and validates the entire selection. Empty, malformed, duplicate,
+unknown, cross-Workspace, stale, or already-bound IDs reject the selection
+without partial mutation. Omitting `sessionIds` retains the Host's import-all
+API behavior; an explicit empty array is invalid.
+
+After selection validation, an individual persistence or DSH composition
+failure may produce a partial batch result. Its durable import state remains
+recoverable and retrying the same source must continue that transaction instead
+of creating a second DSH Session.
+
+## History projection
+
+The Host reads the selected source again with `getSessionInfo` and
+`getSessionMessages` immediately before reserving its binding. The source ID and
+canonical `cwd` must still match. DSH receives a deterministic presentation seed
+containing:
+
+- top-level user text, whether the public SDK returns it as a string or text blocks;
+- visible assistant text and SDK `thinking` blocks as DSH reasoning;
+- a tool call only when its matching tool result exists;
+- textual tool-result content and its error flag.
+
+Malformed messages, pre-turn assistant content, system/private blocks, unmatched
+tool calls or results, non-text tool-result blocks, and unknown future block
+types are skipped and counted. They must never be converted into explanatory
+model text. The source transcript is read-only and is never changed by import.
+
+The initial DSH title comes from `customTitle`, `summary`, or `firstPrompt`, and
+the DSH list recency comes from the source timestamps. History projection and
+title persistence must complete before Workspace attachment is committed.
+
+Import creates a one-time DSH presentation snapshot. It does not poll the source
+or merge turns written later by a second Claude client. Turns sent through DSH
+after import are persisted normally by DSH and the native Claude Session.
+
+## Binding and recovery
+
+One DSH Session binds at most one native Claude Session, and one native Claude
+Session binds at most one DSH Session. Imported DSH IDs are deterministic from
+the complete source Session ID. The binding and the monotonic transaction states
+`reserved`, `session-created`, `hydrated`, `attached`, and `committed` are
+persisted before the next state is attempted.
+
+Restart, duplicate request, concurrent request, and retry must converge on the
+same DSH Session and native Session. Opening or sending the next DSH turn resumes
+the exact imported native Session ID. If resume fails because the source is busy,
+missing, or temporarily unavailable, the plugin reports
+`CLAUDE_IMPORTED_SESSION_RESUME_FAILED`, keeps the binding, and creates no
+replacement Session.
+
+## Web route
+
+The Host exposes one exact POST route at `/api/relay/claude/import`. It accepts
+JSON only, bounds request size, resolves the requested path through DSH's
+registered Workspace service, and returns no-store responses. Loopback requests
+are accepted. A non-loopback caller requires a constant-time checked Bearer token
+configured by `claudeImportToken` or `RELAY_CLAUDE_IMPORT_TOKEN`.
+
+## Delivery acceptance
+
+Delivery requires all of the following evidence:
+
+1. The historical plugin revision reproduces the absence of native Session
+   discovery/import for the same source fixture.
+2. Focused tests cover SDK capability failure, exact inventory options,
+   Workspace isolation, deterministic ordering, selection atomicity, source
+   revalidation, projection, one-to-one durability, concurrency, retry, and the
+   no-replacement resume rule.
+3. Client tests cover Workspace choice, selection, request payloads, chunked
+   NDJSON progress, error handling, disabled empty submission, and refresh order.
+4. A real installed SDK lists and reads a native terminal Session using only the
+   public APIs.
+5. Official DSH imports that Session, displays the projected history and title,
+   and sends the next turn to the same complete native Session ID.
+6. Typecheck, the full repository test suite, build, package-content inspection,
+   and remote CI all pass.

package/docs/spec/claude-search-tools.md

@@ -0,0 +1,40 @@
+# Claude Search Tool Contract
+
+## Scope
+
+The Claude Agent SDK backend exposes Claude's dedicated `Glob` and `Grep`
+tools on every business and auxiliary query. This contract does not apply to
+the text-only CLI fallback.
+
+## Availability
+
+Native Claude builds may otherwise provide filename and content search only
+through Bash. The plugin must opt into `Glob` and `Grep` through the SDK's
+`allowedTools` option so both dedicated tools are present without an approval
+round trip. It must do so for new and resumed Sessions and whether or not the
+owning DSH turn contributes tools.
+
+The bare allow entries intentionally auto-approve only these two native,
+read-only search tools, so the SDK does not call `canUseTool` for them. They do
+not grant any mutation tool. The plugin still registers the permission callback
+for every tool that is not otherwise allowed, and the SDK remains authoritative
+for search path resolution and access enforcement.
+
+The search entries augment the allowlist. They must never replace an
+`mcp__dsh__*` entry created by the DSH tool bridge or alter the configured
+permission mode, permission callback, working directory, plugins, or Session
+continuation options.
+
+## Delivery Acceptance
+
+1. A query without DSH-contributed tools allows exactly the dedicated `Glob`
+   and `Grep` additions and does not create a DSH MCP server.
+2. A query with DSH-contributed tools preserves every generated
+   `mcp__dsh__*` allow entry after `Glob` and `Grep`.
+3. A fresh real SDK Session uses native `Glob` followed by native `Grep` to
+   find a precommitted unique path and marker, with no Bash fallback, approval,
+   or workspace mutation.
+4. The same run returns the exact expected path and marker, and the recorded
+   SDK initialization advertises both tool names.
+5. Existing SDK option, interaction, image, plugin, and DSH tool-bridge tests
+   remain green.

package/docs/spec/claude-tool-output-redaction.md

@@ -0,0 +1,68 @@
+# Claude Tool-Output Redaction
+
+## Status
+
+This document defines the plugin-owned secret-redaction contract for the
+default Claude Agent SDK backend. It is the tracked delivery specification for
+`CLD-ENV-003` and GitHub Issue #29.
+
+## Contract
+
+The plugin must resolve the effective Claude settings before every new or
+resumed turn, using the same workspace and `settingSources` passed to the SDK.
+The effective environment is the SDK process environment overlaid with the
+resolved settings environment.
+
+An environment value is sensitive when its non-empty variable name contains a
+credential-bearing segment such as `SECRET`, `TOKEN`, `PASSWORD`, `PASSWD`,
+`API_KEY`, `ACCESS_KEY`, `PRIVATE_KEY`, or `CREDENTIALS`. A variable explicitly
+listed under `sandbox.credentials.envVars` is also sensitive, regardless of its
+name. If multiple sensitive names have the same value, the lexicographically
+first name supplies the deterministic replacement marker.
+
+Before a successful tool result is delivered to the model, SDK consumers, or
+native Session persistence, the plugin must run a synchronous SDK `PostToolUse`
+callback. Every exact occurrence of a sensitive value in a string anywhere in
+the structured tool response is replaced with
+`[REDACTED_ENV:<VARIABLE_NAME>]`. Longer values are processed first so an
+overlapping shorter value cannot partially expose them.
+
+The callback must not return `updatedToolOutput` when no configured value
+occurs. This preserves the original object and avoids an identity rewrite that
+could compete with another legitimate output-rewriting hook.
+
+The redacted result, not the raw result, must be visible in both normalized SDK
+activity and the native Claude JSONL transcript. Tool execution status and
+non-sensitive output remain unchanged.
+
+## Boundaries
+
+This contract protects tool output containing values from the effective Claude
+environment. It does not rewrite user prompts, tool inputs, arbitrary values
+that cannot be classified from host configuration, files created by tools, or
+errors for which the SDK emits `PostToolUseFailure` without a replaceable tool
+output. It applies to the SDK backend; the explicit CLI fallback does not offer
+the required pre-persistence hook contract.
+
+The implementation must use the supported SDK result-replacement lifecycle.
+Post-hoc edits to Claude JSONL files are forbidden because they are racy and can
+damage Session continuation.
+
+Claude treats output rewrites from multiple synchronous hooks as competing
+replacements. A trusted administrator who installs another `PostToolUse` hook
+that supersedes this plugin's redacted result must ensure that replacement does
+not reintroduce a protected value; the plugin cannot sanitize output created
+after its callback has returned.
+
+## Delivery Acceptance
+
+1. The historical `CLD-ENV-003` probe reproduces the pre-fix leak while the
+   Bash tool completes successfully.
+2. The same probe against the fixed plugin executes Bash exactly once, keeps
+   the expected final marker, and finds zero raw-secret occurrences in SDK
+   activity, the native transcript, diagnostics, and final text.
+3. Focused tests cover sensitive-name detection, explicit credential names,
+   nested structured output, ordinary values, no-op output, and both new and
+   resumed turns.
+4. Typecheck, the complete test suite, build, package dry-run, a real SDK probe,
+   and an official DSH end-to-end run all pass.