@deepseek-ai/dsh-experimental-subagent-oar 0.0.0-stage → 0.2.2-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE-OAR

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,67 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/experimental/subagent-oar/README.md
+/:
+  en: e2a966cf2f6d7f5f
+  zh: e19b979aeef0d29a
+/deepseek-ai-dsh-experimental-subagent-oar:
+  en: fef097906f8c0a35
+  zh: 3fb2737b8974edc0
+/deepseek-ai-dsh-experimental-subagent-oar/summary:
+  en: 75bc60daa998f16a
+  zh: 31f09b5ed600232d
+/deepseek-ai-dsh-experimental-subagent-oar/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 8d1e20b826450ffe
+/deepseek-ai-dsh-experimental-subagent-oar/use-this-package:
+  en: bbff250eba0f1b89
+  zh: 0a618f05cc88ee2b
+/deepseek-ai-dsh-experimental-subagent-oar/use-this-package/compose-a-profile:
+  en: 60804c44d0c2bb40
+  zh: 74471620c96b8c78
+/deepseek-ai-dsh-experimental-subagent-oar/use-this-package/what-you-get:
+  en: e4b715738e3f238d
+  zh: 0c6d561b99d4b07e
+/deepseek-ai-dsh-experimental-subagent-oar/use-this-package/configure-a-runtime-instance:
+  en: cfc28b43567604a6
+  zh: 04ef0d698c3b47f7
+/deepseek-ai-dsh-experimental-subagent-oar/understand-the-implementation:
+  en: 19b537fd24aa1dfd
+  zh: fee12542bb2fc1a6
+/deepseek-ai-dsh-experimental-subagent-oar/further-exploration:
+  en: 089fe63b9b457247
+  zh: 482382e68e5c4e2e
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience/child-request:
+  en: 1796fa78833bfc2b
+  zh: b78af12284632249
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience/child-request/what-the-model-sees:
+  en: 16dd6345fbe5b557
+  zh: adbd8e9b2f4d247f
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience/child-request/token-effect:
+  en: 51b1a72453170ef9
+  zh: 521ff4e9e9a84186
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience/child-request/kv-cache-effect:
+  en: 26a77ed7165e7414
+  zh: 61d802041b7663c6
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience/parent-results-indirectly:
+  en: cc55ad2a7e04a064
+  zh: e7d3d72a5b1e80e3
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience/parent-results-indirectly/what-the-model-sees:
+  en: 2d1cdcc92211fdec
+  zh: 016169e5fb65eb86
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience/parent-results-indirectly/token-effect:
+  en: 99d04595c61a32fc
+  zh: 47f6253729070269
+/deepseek-ai-dsh-experimental-subagent-oar/model-experience/parent-results-indirectly/kv-cache-effect:
+  en: ba649995f08b9e09
+  zh: a153047f0c25645a
+/deepseek-ai-dsh-experimental-subagent-oar/known-limitations-and-deferred-work:
+  en: 8eec39a3eb58a185
+  zh: 68feb7901d4b50b9
+/deepseek-ai-dsh-experimental-subagent-oar/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 8ec3e73528ddb1a6

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+---
+description: "Add experimental one-shot coding-agent delegation through OAR with per-call runtime selection."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-experimental-subagent-oar
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Compose this experimental provider with the `subagent_oar` tool to delegate standalone text tasks to Codex and Claude Code in the selected workspace. The provider embeds the OAR library, so no separate OAR CLI installation is required. Codex and Claude Code use their installed native CLIs, authentication, and settings.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+### Compose a profile
+
+Install and authenticate the native Codex and Claude Code CLIs before delegating to them. Their executables must be available to the DSH Host. The provider starts no native session until a delegation is accepted.
+
+Declare this provider and `@deepseek-ai/dsh-experimental-tool-subagent-oar` as dependencies of your composition, then add these rows through a profile patch:
+
+```yaml
+- insert:
+    - id: experimental-subagent-oar-codex
+      name: '@deepseek-ai/dsh-experimental-subagent-oar'
+      config:
+        runtime: codex
+        providerName: oar-codex
+        launchArgs:
+          - -c
+          - sandbox_mode="workspace-write"
+    - id: experimental-subagent-oar-claude
+      name: '@deepseek-ai/dsh-experimental-subagent-oar'
+      config:
+        runtime: claude
+        providerName: oar-claude
+        launchArgs:
+          - --permission-mode
+          - dontAsk
+          - --permission-prompts
+          - none
+    - id: tool-subagent-oar
+      name: '@deepseek-ai/dsh-experimental-tool-subagent-oar'
+      config:
+        providers:
+          codex: oar-codex
+          claude: oar-claude
+```
+
+Launch the completed composition through a `dsh` profile. The example assigns each provider a distinct name and fixes its native permission arguments before the model can delegate work.
+
+### What you get
+
+The separate [`subagent_oar` tool](../tool-subagent-oar/README.md) selects a configured runtime for each call. Its package documents the arguments and parent-facing notices.
+
+| `runtime` | Provider | Native permissions in the example |
+|---|---|---|
+| `codex` | `oar-codex` | Codex `workspace-write` sandbox; no approval prompts |
+| `claude` | `oar-claude` | Claude Code `dontAsk`; permission prompts disabled |
+
+Each delegation starts one native session for one text task. The parent Session retains the external task identity and terminal result; this provider creates no DSH child Session and exposes no follow-up or resume operation.
+
+### Configure a runtime instance
+
+Each provider instance selects one OAR runtime and registers a unique `providerName`. To expose another runtime, add its provider row and extend the [external tool's provider mapping](../tool-subagent-oar/README.md#use-this-package). Later profile layers can override these configurations. An unknown OAR runtime id fails when its provider loads.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `runtime` | required | Runtime id in OAR's default registry |
+| `providerName` | `oar` | Name registered with the DSH subagent service |
+| `model` | native settings | Optional native model selection |
+| `effort` | native settings | Optional native reasoning effort, where supported by the runtime |
+| `launchArgs` | `[]` | Native runtime arguments, including permission settings |
+| `env` | `{}` | Explicit environment overrides after ambient credential and DSH-variable scrubbing; `null` removes a variable |
+| `timeoutMs` | none | Optional turn deadline after startup; omission uses parent cancellation only |
+
+For Claude, select the native permission mode explicitly in `launchArgs` and retain `--permission-prompts none` for unattended work. A Claude instance with no permission-mode argument inherits OAR's permission bypass default. Replacing the example's argument array also replaces its explicit permission settings.
+
+The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-subagent-oar) owns accepted fields and validation. A child that needs an API credential from an environment variable must receive it through `env`; native account files remain available through the native runtime's settings.
+
+OAR's pinned default registry includes `antigravity`, `claude`, `codex`, `grok`, `kimi`, `opencode`, and `pi`. Provider configuration accepts every registered runtime id. Codex and Claude have native e2e coverage. Other runtimes need an explicit provider and tool mapping and remain unverified.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The example mounts two instances of the same provider and the [external delegation tool](../tool-subagent-oar/README.md). [`src/index.ts`](src/index.ts) registers providers; the tool package owns runtime selection and task presentation. The provider uses OAR's runtime registry and session API for startup, one prompt, answer collection, cancellation, and disposal. OAR owns native processes; these sessions do not use the DSH subprocess provider.
+
+The dependency patch applies environment overrides to native installation probes. It permits Claude's explicit `--permission-mode` and suppresses OAR's forced permission bypass when that argument is present. The example passes `--permission-mode dontAsk --permission-prompts none`. Codex receives `-c sandbox_mode="workspace-write"`. OAR sets Codex approval policy to `never`. Neither path forwards native approval requests to a DSH interaction UI. Codex startup failure stops app-server and waits for its exit, including a response without a thread id.
+
+Only root assistant text contributes to the answer. When OAR supplies message ids, the last nonempty message is selected; otherwise root text is concatenated. Native reasoning, tool events, and transcript history do not enter the parent Session. Native history follows the selected runtime's own persistence behavior. Provider errors retain native causes for local debugging; default logs emit only safe stage and category summaries because native causes can contain credentials.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Experimental packages](../README.md) — experimental status and optional delivery.
+- [Subagent service](../../subagent/subagent/README.md) — provider lifecycle and terminal results.
+- [OAR subagent tool](../tool-subagent-oar/README.md) — runtime selection and parent-facing behavior.
+- [Subagent subsystem](../../../docs/subsystems/subagent.md) — parent scheduling and completion notices.
+- [Architecture](../../../docs/architecture.md) — profile layer composition.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Child request
+
+#### What the model sees
+
+The selected native runtime receives the text from `prompt` with `cwd` set to the resolved child directory. Its own model, tools, configuration, and history determine the child request; instance configuration supplies any model, effort, arguments, and environment overrides.
+
+#### Token effect
+
+The native runtime pays for an independent context and turn. Child reasoning and tool traffic are not added to the parent context.
+
+#### KV Cache effect
+
+The child request is independent of the parent's cached prefix. Native runtime behavior determines child cache reuse.
+
+### Parent results, indirectly
+
+#### What the model sees
+
+Through the [external subagent tool](../tool-subagent-oar/README.md#model-experience), the parent receives this provider's selected root answer or failure notice. The consumer owns the tool schema and acknowledgement.
+
+#### Token effect
+
+The terminal notice adds the selected answer or failure detail to the parent context.
+
+#### KV Cache effect
+
+Provider results append through the shared subagent service. The [consumer](../tool-subagent-oar/README.md#model-experience) owns tool-schema changes that affect the parent's cached prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Experimental runtime coverage:** only Codex and Claude Code have native e2e coverage. Other registered runtimes can be selected but have not been validated by DSH.
+- **Native setup:** this provider does not install, authenticate, or upgrade native agents. Missing executables and native configuration failures surface when delegation starts.
+- **Unattended permissions:** native permission modes apply without a DSH approval UI. Claude needs a CLI version that supports `--permission-prompts none`; the provider does not expose a tool-restriction feature. OAR records unexpected Codex approval or user-input requests without answering them. If the runtime waits, cancel the task or configure `timeoutMs`.
+- **Startup cancellation:** OAR does not expose immediate cancellation while a session is opening. Cancellation waits for that operation and disposes a late session; an explicitly configured `timeoutMs` starts only after opening succeeds.
+- **Process and history ownership:** OAR handles native processes, and native runtimes can retain transcripts. DSH does not apply its subprocess sandbox or managed descendant cleanup to those processes.
+- **One-shot text:** no continuation, resume, structured output, progress stream, or side-effect rollback is provided. Native changes made before cancellation remain in place.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,174 @@
+---
+description: "通过 OAR 添加实验性单次编程智能体委派，并允许每次调用选择运行时。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-subagent-oar
+
+[English](README.md) | 中文
+
+## 概述
+
+将此实验性提供方与 `subagent_oar` 工具组合，即可在选定的工作区中向 Codex 和 Claude Code 委派独立文本任务。提供方内嵌 OAR 库，因此无需单独安装 OAR CLI。Codex 和 Claude Code 使用已安装的原生 CLI、认证和设置。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待完善事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+### 组合 Profile
+
+委派前，请先安装并认证原生 Codex 和 Claude Code CLI。DSH Host 必须能访问它们的可执行文件。提供方在接受委派之前不会启动原生会话。
+
+在组合中将此提供方和 `@deepseek-ai/dsh-experimental-tool-subagent-oar` 声明为依赖，然后通过 Profile 补丁添加这些行：
+
+```yaml
+- insert:
+    - id: experimental-subagent-oar-codex
+      name: '@deepseek-ai/dsh-experimental-subagent-oar'
+      config:
+        runtime: codex
+        providerName: oar-codex
+        launchArgs:
+          - -c
+          - sandbox_mode="workspace-write"
+    - id: experimental-subagent-oar-claude
+      name: '@deepseek-ai/dsh-experimental-subagent-oar'
+      config:
+        runtime: claude
+        providerName: oar-claude
+        launchArgs:
+          - --permission-mode
+          - dontAsk
+          - --permission-prompts
+          - none
+    - id: tool-subagent-oar
+      name: '@deepseek-ai/dsh-experimental-tool-subagent-oar'
+      config:
+        providers:
+          codex: oar-codex
+          claude: oar-claude
+```
+
+通过 `dsh` Profile 启动完成后的组合。此示例为每个提供方分配不同名称，并在模型可以委派任务之前固定原生权限参数。
+
+### 提供的能力
+
+独立的 [`subagent_oar` 工具](../tool-subagent-oar/README.zh.md)为每次调用选择已配置的运行时。其包文档定义参数和父智能体可见的通知。
+
+| `runtime` | 提供方 | 示例中的原生权限 |
+|---|---|---|
+| `codex` | `oar-codex` | Codex `workspace-write` 沙箱；不弹出审批提示 |
+| `claude` | `oar-claude` | Claude Code `dontAsk`；禁用权限提示 |
+
+每次委派都会启动一个原生会话，执行一个文本任务。父 Session 保留外部任务标识和最终结果；此提供方不创建 DSH 子 Session，也不提供后续输入或恢复操作。
+
+### 配置运行时实例
+
+每个提供方实例选择一个 OAR 运行时，并注册唯一的 `providerName`。要暴露另一个运行时，请添加提供方行并扩展[外部工具的提供方映射](../tool-subagent-oar/README.zh.md#use-this-package)。后续 Profile 层可以覆盖这些配置。未知 OAR 运行时 id 会在其提供方加载时失败。
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `runtime` | 必填 | OAR 默认注册表中的运行时 id |
+| `providerName` | `oar` | 向 DSH 子智能体服务注册的名称 |
+| `model` | 原生设置 | 可选的原生模型选择 |
+| `effort` | 原生设置 | 可选的原生推理强度，由运行时决定是否支持 |
+| `launchArgs` | `[]` | 原生运行时参数，包括权限设置 |
+| `env` | `{}` | 清理环境中的凭据和 DSH 变量后应用的显式环境覆盖；`null` 移除变量 |
+| `timeoutMs` | 无 | 可选的启动后轮次时限；省略时仅由父会话取消 |
+
+对于 Claude，请在 `launchArgs` 中显式选择原生权限模式，并保留 `--permission-prompts none` 以便无人值守运行。Claude 实例如果不提供权限模式参数，会继承 OAR 默认的权限绕过。替换示例的参数数组也会替换其中显式设置的权限。
+
+[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-subagent-oar)定义接受的字段和校验规则。如果子进程需要环境变量中的 API 凭据，必须通过 `env` 提供；原生账户文件仍可通过原生运行时设置访问。
+
+固定版本的 OAR 默认注册表包含 `antigravity`、`claude`、`codex`、`grok`、`kimi`、`opencode` 和 `pi`。提供方配置接受每个已注册的运行时 id。Codex 和 Claude 有原生 e2e 覆盖。其他运行时需要显式添加提供方和工具映射，且仍未经验证。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部细节 — 点击展开</summary>
+
+此示例挂载同一提供方的两个实例和[外部委派工具](../tool-subagent-oar/README.zh.md)。[`src/index.ts`](src/index.ts)注册提供方；工具包负责运行时选择和任务展示。提供方使用 OAR 的运行时注册表和会话 API 完成启动、单次提示、答复收集、取消及释放。OAR 负责原生进程；这些会话不使用 DSH 子进程提供方。
+
+依赖补丁对原生安装探测应用环境覆盖，并允许 Claude 显式使用 `--permission-mode`，并在存在该参数时关闭 OAR 强制的权限绕过。示例传入 `--permission-mode dontAsk --permission-prompts none`。Codex 接收 `-c sandbox_mode="workspace-write"`。OAR 将 Codex 审批策略设为 `never`。两条路径均不将原生审批请求转发到 DSH 交互界面。Codex 启动失败时会停止 app-server 并等待其退出，包括响应中缺少线程 id 的情况。
+
+只有根智能体文本参与答复。当 OAR 提供消息 id 时，选择最后一条非空消息；否则拼接根文本。原生推理、工具事件和转录历史不会进入父 Session。原生历史遵循所选运行时自身的持久化行为。提供方错误保留原生原因供本地调试；默认日志仅输出安全的阶段和类别摘要，因为原生原因可能包含凭据。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [实验性包](../README.zh.md) — 实验性状态与可选交付。
+- [子智能体服务](../../subagent/subagent/README.zh.md) — 提供方生命周期和最终结果。
+- [OAR 子智能体工具](../tool-subagent-oar/README.zh.md) — 运行时选择和父智能体可见行为。
+- [子智能体子系统](../../../docs/subsystems/subagent.zh.md) — 父智能体调度和完成通知。
+- [架构](../../../docs/architecture.zh.md) — Profile 层组合。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 子请求
+
+#### 模型看到什么
+
+所选原生运行时接收 `prompt` 中的文本，`cwd` 设为解析后的子任务目录。其自身的模型、工具、配置和历史决定子请求；实例配置提供模型、推理强度、参数和环境覆盖。
+
+#### Token 影响
+
+原生运行时承担独立上下文和轮次的 token。子智能体推理和工具流量不会添加到父上下文。
+
+#### KV Cache 影响
+
+子请求独立于父请求的缓存前缀。原生运行时行为决定子请求的缓存复用。
+
+### 父智能体结果（间接）
+
+#### 模型看到什么
+
+通过[OAR 子智能体工具](../tool-subagent-oar/README.zh.md#model-experience)，父智能体收到此提供方选中的根答复或失败通知。消费者负责工具 schema 和确认消息。
+
+#### Token 影响
+
+最终通知将选中的答复或失败详情加入父上下文。
+
+#### KV Cache 影响
+
+提供方结果通过共享子智能体服务追加。[消费者](../tool-subagent-oar/README.zh.md#model-experience)负责会影响父请求缓存前缀的工具 schema 变更。
+
+## 已知限制与待完善事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **实验性运行时覆盖：** 只有 Codex 和 Claude Code 有原生 e2e 覆盖。其他已注册运行时可以选择，但尚未由 DSH 验证。
+- **原生配置：** 此提供方不安装、认证或升级原生智能体。缺少可执行文件和原生配置错误会在委派启动时呈现。
+- **无人值守权限：** 原生权限模式生效，但没有 DSH 审批界面。Claude 需要支持 `--permission-prompts none` 的 CLI 版本；此提供方不提供工具限制功能。OAR 会记录意外的 Codex 审批或用户输入请求，但不会回答。如果运行时等待输入，请取消任务或配置 `timeoutMs`。
+- **启动取消：** OAR 不提供会话打开期间的即时取消。取消操作会等待打开完成并释放迟到的会话；显式配置的 `timeoutMs` 仅在成功打开后开始计时。
+- **进程与历史所有权：** OAR 处理原生进程，原生运行时可能保留转录记录。DSH 不对这些进程应用其子进程沙箱或受管理的后代进程清理。
+- **单次文本：** 不提供继续、恢复、结构化输出、进度流或副作用回滚。取消前的原生更改会保留。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+无。
+
+</details>

package/icon.svg

@@ -0,0 +1 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="14.9893" y="15.1877" width="12.2365" height="12.2365" rx="2" fill="url(#dsh_plugin_art_R0a)" fill-opacity="0.8"></rect><rect x="8.87109" y="9.0697" width="12.2365" height="12.2365" rx="2" fill="url(#dsh_plugin_art_R0b)" fill-opacity="0.8"></rect><defs><linearGradient id="dsh_plugin_art_R0a" x1="21.1075" y1="15.1877" x2="21.1075" y2="27.4243" gradientUnits="userSpaceOnUse"><stop stop-color="#45E7A4"></stop><stop offset="1" stop-color="#05909D"></stop></linearGradient><linearGradient id="dsh_plugin_art_R0b" x1="14.9894" y1="9.0697" x2="14.9894" y2="21.3063" gradientUnits="userSpaceOnUse"><stop stop-color="#69B9FF"></stop><stop offset="1" stop-color="#324DE2"></stop></linearGradient></defs></svg>