@acryldev/plugin-context 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/LICENSE +21 -0
  2. package/docs/README.md +160 -0
  3. package/docs/delivery/local-live.md +113 -0
  4. package/docs/delivery/marketplace.md +16 -0
  5. package/docs/docs.json +2836 -0
  6. package/docs/extending/agent-preset.md +37 -0
  7. package/docs/extending/chat-command.md +28 -0
  8. package/docs/extending/client-slot.md +135 -0
  9. package/docs/extending/config-schema.md +7 -0
  10. package/docs/extending/cordis-core.md +63 -0
  11. package/docs/extending/desktop-app.md +53 -0
  12. package/docs/extending/desktop-main.md +25 -0
  13. package/docs/extending/event-hook.md +14 -0
  14. package/docs/extending/host-route.md +33 -0
  15. package/docs/extending/llm-adapter.md +38 -0
  16. package/docs/extending/packaging.md +53 -0
  17. package/docs/extending/prompt-contribution.md +9 -0
  18. package/docs/extending/service.md +13 -0
  19. package/docs/extending/skill-provider.md +9 -0
  20. package/docs/extending/state-and-persistence.md +71 -0
  21. package/docs/extending/three-role-capability.md +33 -0
  22. package/docs/extending/tool-plugin.md +24 -0
  23. package/docs/extending/tui-command.md +8 -0
  24. package/docs/extending/tui-components.md +61 -0
  25. package/docs/extending/ui-branding.md +43 -0
  26. package/docs/extending/ui-components.md +56 -0
  27. package/docs/extending/ui-customization.md +41 -0
  28. package/docs/extending/ui-library.md +66 -0
  29. package/docs/extending/ui-theme.md +55 -0
  30. package/docs/extending/workspace-tab.md +50 -0
  31. package/docs/maps/events.md +108 -0
  32. package/docs/maps/mount-points.md +154 -0
  33. package/docs/maps/slot-contracts.md +3376 -0
  34. package/docs/maps/taxonomy.md +306 -0
  35. package/docs/maps/theme-tokens.md +115 -0
  36. package/docs/maps/ui-components.md +26 -0
  37. package/docs/reference/cookbook/adding-a-package.md +174 -0
  38. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  39. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  40. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  41. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  42. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  43. package/docs/reference/cordis-api/context.md +366 -0
  44. package/docs/reference/cordis-api/events.md +209 -0
  45. package/docs/reference/cordis-api/fiber.md +377 -0
  46. package/docs/reference/cordis-api/inherited.md +40 -0
  47. package/docs/reference/cordis-api/registry.md +154 -0
  48. package/docs/reference/cordis-api/service.md +104 -0
  49. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  50. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  51. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  52. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  53. package/docs/reference/harness/agent-lifecycle.md +93 -0
  54. package/docs/reference/harness/architecture.md +168 -0
  55. package/docs/reference/harness/capability-seams.md +675 -0
  56. package/docs/reference/harness/config-catalog.md +4523 -0
  57. package/docs/reference/harness/cordis-primer.md +47 -0
  58. package/docs/reference/harness/defensive-patterns.md +35 -0
  59. package/docs/reference/harness/event-producer-consumer.md +111 -0
  60. package/docs/reference/harness/glossary.md +47 -0
  61. package/docs/reference/harness/tool-catalog.md +2721 -0
  62. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  63. package/docs/reference/subsystems/README.md +75 -0
  64. package/docs/reference/subsystems/agent-team.md +233 -0
  65. package/docs/reference/subsystems/approval.md +172 -0
  66. package/docs/reference/subsystems/attachment.md +363 -0
  67. package/docs/reference/subsystems/boot.md +324 -0
  68. package/docs/reference/subsystems/browser-use.md +69 -0
  69. package/docs/reference/subsystems/client-modules.md +186 -0
  70. package/docs/reference/subsystems/client-resources.md +94 -0
  71. package/docs/reference/subsystems/commands.md +225 -0
  72. package/docs/reference/subsystems/compaction.md +286 -0
  73. package/docs/reference/subsystems/computer-use.md +58 -0
  74. package/docs/reference/subsystems/conversation.md +287 -0
  75. package/docs/reference/subsystems/core.md +1107 -0
  76. package/docs/reference/subsystems/credentials.md +497 -0
  77. package/docs/reference/subsystems/deliverables.md +180 -0
  78. package/docs/reference/subsystems/extensions.md +386 -0
  79. package/docs/reference/subsystems/feedback.md +402 -0
  80. package/docs/reference/subsystems/filesystem.md +532 -0
  81. package/docs/reference/subsystems/goal.md +315 -0
  82. package/docs/reference/subsystems/invariants.md +90 -0
  83. package/docs/reference/subsystems/jobs.md +501 -0
  84. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  85. package/docs/reference/subsystems/lsp.md +204 -0
  86. package/docs/reference/subsystems/mcp.md +141 -0
  87. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  88. package/docs/reference/subsystems/otel.md +46 -0
  89. package/docs/reference/subsystems/permission-presets.md +169 -0
  90. package/docs/reference/subsystems/persistence.md +418 -0
  91. package/docs/reference/subsystems/plan.md +89 -0
  92. package/docs/reference/subsystems/product-telemetry.md +81 -0
  93. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  94. package/docs/reference/subsystems/sandbox.md +223 -0
  95. package/docs/reference/subsystems/schedule.md +545 -0
  96. package/docs/reference/subsystems/scope.md +61 -0
  97. package/docs/reference/subsystems/session-projection.md +358 -0
  98. package/docs/reference/subsystems/session-query.md +511 -0
  99. package/docs/reference/subsystems/session-reference.md +226 -0
  100. package/docs/reference/subsystems/session-telemetry.md +214 -0
  101. package/docs/reference/subsystems/session-title.md +206 -0
  102. package/docs/reference/subsystems/session.md +1300 -0
  103. package/docs/reference/subsystems/settings.md +157 -0
  104. package/docs/reference/subsystems/shell.md +316 -0
  105. package/docs/reference/subsystems/sidebar-right.md +160 -0
  106. package/docs/reference/subsystems/skills.md +354 -0
  107. package/docs/reference/subsystems/slots.md +201 -0
  108. package/docs/reference/subsystems/spill.md +126 -0
  109. package/docs/reference/subsystems/ssh.md +137 -0
  110. package/docs/reference/subsystems/storage.md +262 -0
  111. package/docs/reference/subsystems/subagent.md +762 -0
  112. package/docs/reference/subsystems/subprocess.md +323 -0
  113. package/docs/reference/subsystems/system-prompt.md +226 -0
  114. package/docs/reference/subsystems/terminal.md +186 -0
  115. package/docs/reference/subsystems/todo.md +34 -0
  116. package/docs/reference/subsystems/token-meter.md +108 -0
  117. package/docs/reference/subsystems/tools.md +749 -0
  118. package/docs/reference/subsystems/typert.md +489 -0
  119. package/docs/reference/subsystems/user-questions.md +309 -0
  120. package/docs/reference/subsystems/voice-input.md +166 -0
  121. package/docs/reference/subsystems/web-client.md +102 -0
  122. package/docs/reference/subsystems/web-server.md +228 -0
  123. package/docs/reference/subsystems/web.md +208 -0
  124. package/docs/reference/subsystems/webhook.md +72 -0
  125. package/docs/reference/subsystems/workflow.md +280 -0
  126. package/docs/reference/subsystems/workspace.md +661 -0
  127. package/docs/start-here/blueprints.md +33 -0
  128. package/docs/start-here/this-runtime.md +84 -0
  129. package/docs/start-here/troubleshooting.md +29 -0
  130. package/docs/start-here/trust-and-safety.md +39 -0
  131. package/docs/start-here/verify-before-done.md +46 -0
  132. package/example-plugins/README.md +45 -0
  133. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  134. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  135. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  137. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  138. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  141. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  144. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  145. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  146. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  147. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  148. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  149. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  150. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  151. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  152. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  153. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  154. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  155. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  159. package/example-plugins/packages/client-theme-override/client.js +52 -0
  160. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  161. package/example-plugins/packages/client-theme-override/index.js +9 -0
  162. package/example-plugins/packages/client-theme-override/package.json +30 -0
  163. package/example-plugins/packages/client-tool-view/client.js +47 -0
  164. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  165. package/example-plugins/packages/client-tool-view/index.js +24 -0
  166. package/example-plugins/packages/client-tool-view/package.json +34 -0
  167. package/example-plugins/packages/client-ui-components/client.js +77 -0
  168. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  169. package/example-plugins/packages/client-ui-components/index.js +9 -0
  170. package/example-plugins/packages/client-ui-components/package.json +31 -0
  171. package/example-plugins/packages/client-ui-library/client.js +715 -0
  172. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  173. package/example-plugins/packages/client-ui-library/index.js +9 -0
  174. package/example-plugins/packages/client-ui-library/package.json +37 -0
  175. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  176. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  177. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  178. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  179. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  180. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  181. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  182. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  183. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  184. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  185. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  186. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  187. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  188. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  189. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  190. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  191. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  192. package/example-plugins/packages/host-route-basic/index.js +20 -0
  193. package/example-plugins/packages/host-route-basic/package.json +29 -0
  194. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  195. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  196. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  197. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  201. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  204. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  205. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  206. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  207. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  208. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  209. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  210. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  211. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  212. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  213. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  214. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  215. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  216. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  217. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  218. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  219. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  220. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  221. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  222. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  223. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  224. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  225. package/example-plugins/packages/state-host-store/client.js +57 -0
  226. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  227. package/example-plugins/packages/state-host-store/index.js +90 -0
  228. package/example-plugins/packages/state-host-store/package.json +31 -0
  229. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  230. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  231. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  232. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  233. package/example-plugins/packages/tool-basic/index.js +25 -0
  234. package/example-plugins/packages/tool-basic/package.json +25 -0
  235. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  236. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  237. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  238. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  239. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  240. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  241. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  242. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  243. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  244. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  245. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  246. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  247. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  248. package/example-plugins/packages/web-page-branding/index.js +31 -0
  249. package/example-plugins/packages/web-page-branding/package.json +22 -0
  250. package/example-plugins/scenarios.json +11 -0
  251. package/index.js +384 -0
  252. package/lib/blend-apply.js +107 -0
  253. package/lib/blend-capture.js +249 -0
  254. package/lib/blend-ledger.js +76 -0
  255. package/lib/contract.js +5 -0
  256. package/lib/install.js +516 -0
  257. package/lib/lookup.js +67 -0
  258. package/lib/manifest.js +56 -0
  259. package/lib/pack-root.js +22 -0
  260. package/lib/provenance.js +110 -0
  261. package/lib/publish.js +64 -0
  262. package/lib/reconcile.js +83 -0
  263. package/lib/router.js +55 -0
  264. package/lib/scopes.js +82 -0
  265. package/lib/skills.js +54 -0
  266. package/lib/stage.js +157 -0
  267. package/lib/verify.js +77 -0
  268. package/package.json +56 -3
  269. package/scripts/lib/indexes.mjs +45 -0
  270. package/scripts/lib/manifest.mjs +127 -0
  271. package/scripts/lib/maps.mjs +482 -0
  272. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  273. package/skills/acryl-add-ui/SKILL.md +18 -0
  274. package/skills/acryl-build-plugin/SKILL.md +21 -0
  275. package/skills/acryl-change-plugin/SKILL.md +16 -0
  276. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  277. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  278. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  279. package/skills/acryl-improve-ui/SKILL.md +10 -0
  280. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  281. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  282. package/skills/acryl-share-plugin/SKILL.md +23 -0
  283. package/skills/acryl-tui-ui/SKILL.md +12 -0
  284. package/README.md +0 -3
@@ -0,0 +1,762 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/subagent.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Subagent
4
+
5
+ English | [中文](subagent.zh.md)
6
+
7
+ The subagent seam lets an agent delegate work to a child agent. Like [bash](shell.md), it is **one optional capability**, not part of the agent loop, so its types live here rather than in [core.md](core.md). It differs from the other capability seams because **multiple provider implementations coexist** in one context, registered by name (`ctx.subagents`), while bash allows only one executor. Its registry follows the [LLM adapter registry](llm-streaming.md), not the single-service bash executor.
8
+
9
+ Service Definition: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Service Providers are sibling packages (`dsh-subagent-spawn-in-process`, `dsh-subagent-fork-in-process`, `dsh-subagent-acp`, `dsh-subagent-codex`, `dsh-subagent-claude-code`, `dsh-subagent-dsh-sdk`); the model-facing Consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation) and [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager, direct-child discovery through the parent catalog, and recursive descendant discovery through parent catalogs. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), and [the adjacent-Agent messaging Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.md); [the archived list-identity-projection record](../../.agents/notes/archived/architecture/2026-08-06-subagent-list-identity-projection.md) documents the original list-identity decision.
10
+
11
+ Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
12
+
13
+ The `subagentCatalog` projection exposes `SubagentCatalogEntry[]` in parent event order through Session observations and client snapshots. Each entry contains the child id, creation time, mode, and mode-dependent label; fork-inherited catalog facts are excluded. [The subagent package](../../packages/subagent/subagent/README.md) owns catalog creation and persistence semantics. Historical children with unavailable descriptors have `mode: 'unknown'`; their header identity remains discoverable without granting continuation capabilities.
14
+
15
+ ## Two kinds of capability, discovered two ways
16
+
17
+ A provider advertises its **start-time** features on a static descriptor the service checks BEFORE a one-shot run exists; a request that needs one the provider lacks is rejected loud (`SubagentError('UNSUPPORTED_CAPABILITY')`), never accepted-then-ignored. Those flags describe only the one-shot [`start()`](#the-provider-contract-subagentprovider) path, where the provider composes the child. **Continuable** children are composed by the continuation manager itself, so they are gated by one optional method whose presence IS the capability, with TS narrowing as the discovery mechanism: [`SubagentProvider.prepareContinuable`](#the-provider-contract-subagentprovider).
18
+
19
+ ```ts type-equiv
20
+ /**
21
+ * Which START-TIME features a provider supports. Checked by the service before delegating to
22
+ * {@link SubagentProvider.start}: a request that needs a capability the chosen provider lacks
23
+ * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent
24
+ * degradation" rule). These flags describe the ONE-SHOT
25
+ * {@link SubagentProvider.start} path, where the provider composes the child;
26
+ * continuable children are composed by the continuation manager itself and are
27
+ * gated by {@link SubagentProvider.prepareContinuable} instead. Each flag
28
+ * corresponds one-to-one to a {@link SubagentStartRequest} option: `depthLimit`
29
+ * to `maxDepth`; the other names match.
30
+ */
31
+ interface SubagentCapabilities {
32
+ readonly agentOptions: boolean
33
+ readonly outputSchema: boolean
34
+ readonly depthLimit: boolean
35
+ readonly toolFilter: boolean
36
+ readonly persona: boolean
37
+ }
38
+ ```
39
+
40
+ ## The one-shot start request
41
+
42
+ The tool layer builds this request from the model input and its own config; the service validates it against the named provider before `start`. Required `parent` supplies the session cwd, lineage, and delegation depth. Optional Agent provider, model, reasoning-effort, and token overrides, output schema, depth, tool filter, and persona require matching capability flags. In-process backends merge `agentOptions` over the parent Agent's options, scope filters and personas to child creation, and implement the supported object-rooted schema with a forced capture tool. The DSH SDK backend merges the four Agent route fields over its instance defaults and validates them in the child runtime's initialization; ACP, Codex, and Claude Code reject `agentOptions` before starting their transports.
43
+
44
+ ```ts type-equiv
45
+ /**
46
+ * What a caller asks for when starting a ONE-SHOT subagent. The tool layer
47
+ * builds this from the model's `{ description, prompt }` plus its own config;
48
+ * the service validates {@link SubagentCapabilities} against the named provider
49
+ * and resolves the durable descriptor before dispatching to
50
+ * {@link SubagentProvider.start}.
51
+ */
52
+ interface SubagentStartRequest {
53
+ /** Optional short display label persisted with a session-backed child. */
54
+ readonly label?: string
55
+ /** Content delivered as the child's user message. */
56
+ readonly prompt: ContentBlock[]
57
+ /**
58
+ * The spawning agent. In-process providers derive workspace, lineage, and
59
+ * delegation depth from its durable session state. ACP reads only its cwd,
60
+ * and only when no deployment `cwd` override is configured.
61
+ */
62
+ readonly parent: Agent
63
+ /**
64
+ * Cancellation signal from the spawning context (the tool's `exec.signal`).
65
+ * This is the canonical cancellation channel both before and after startup:
66
+ * a provider rejects `start()` after cleaning partial resources when it
67
+ * fires before the run is published, and cancels the published run's
68
+ * remaining turn work when it fires afterward.
69
+ */
70
+ readonly signal: AbortSignal
71
+ /**
72
+ * Optional host-Agent provider, model, reasoning-effort, and output-token
73
+ * overrides. Requires {@link SubagentCapabilities.agentOptions}; in-process
74
+ * providers merge them over the parent Agent's options when they create the
75
+ * child, while the DSH SDK provider merges them over its instance defaults
76
+ * before initializing the separate child runtime.
77
+ */
78
+ readonly agentOptions?: AgentOptions
79
+ /**
80
+ * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
81
+ * unsupported schemas or providers without the capability. Data must be plain host-realm JSON;
82
+ * a successful child returns the matching value as {@link SubagentResult.structured}.
83
+ */
84
+ readonly outputSchema?: ObjectJsonSchema
85
+ /**
86
+ * Optional absolute delegation-depth cap for the child being started: its
87
+ * computed depth must be less than or equal to this non-negative safe
88
+ * integer. Requires {@link SubagentCapabilities.depthLimit}; rejected at
89
+ * start otherwise.
90
+ */
91
+ readonly maxDepth?: number
92
+ /**
93
+ * Optional child tool scoping. Requires {@link SubagentCapabilities.toolFilter};
94
+ * rejected at start otherwise. In-process backends apply it as a scoped
95
+ * `tools.restrict()` in the child's creation window: the named tools vanish
96
+ * from the child's prompt AND refuse to execute (one visibility), with loud
97
+ * unknown-name validation.
98
+ */
99
+ readonly toolFilter?: ToolRestriction
100
+ /**
101
+ * Optional per-child persona. Requires {@link SubagentCapabilities.persona};
102
+ * rejected at start otherwise. In-process backends register it as a scoped
103
+ * `deployment:persona-prefix` section on the child, SHADOWING the deployment's
104
+ * persona for this child alone - same template semantics as the deployment
105
+ * persona (strict `{{…}}` interpolation against the registered variables).
106
+ */
107
+ readonly persona?: string
108
+ }
109
+ ```
110
+
111
+ `signal` is the single cancellation channel before and after readiness. The [subagent composition-controls Agent Note](../../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md) owns the persona, live global-tool filter, absolute-depth, and visibility-not-authority rationale.
112
+
113
+ The caller-facing request does not carry catalog format details or continuation state. `SubagentRuntime.start()` resolves the detached one-shot descriptor after capability checks, then passes this provider-facing request to the selected transport; a continuable child never reaches `SubagentProvider.start()`:
114
+
115
+ ```ts type-equiv
116
+ /**
117
+ * Provider-facing one-shot request after {@link SubagentRuntime.start} resolves
118
+ * the durable child descriptor.
119
+ */
120
+ interface ResolvedSubagentStartRequest extends SubagentStartRequest {
121
+ /** Detached descriptor a session-backed provider persists in the child log. */
122
+ readonly descriptor: SubagentDescriptorData
123
+ }
124
+ ```
125
+
126
+ ## Continuable children and activations
127
+
128
+ A **continuable background subagent** is one durable child Session with at most one process-local **Activation**, the period when a reconstructed child Agent is resident. An Activation is not a request, result, cancellation, or Task: it may execute many FIFO turns and stays resident while descendants it created are still running. The continuation manager owns activation admission, direct-parent authorization, the live ownership graph, cold resume, and child-first disposal; the Agent loop owns all turn ordering and execution. No continuable path creates a Task or an intermediate result-bearing wrapper.
129
+
130
+ ```text
131
+ persisted Session
132
+ -> optional live Activation
133
+ -> one retained AgentHandle
134
+ -> Agent inbox as the only turn FIFO
135
+ -> zero or more owned child Activations
136
+ ```
137
+
138
+ `SubagentRuntime.startContinuable()` reserves the stable child id, snapshots the versioned `subagent/descriptor` payload, asks the named provider for its detached `ContinuableCreateSpec`, creates the child Agent through a private activation-owner scope, establishes any continuable-parent ownership, and submits the initial prompt. It resolves with `{ childId, messageId }` when inbox acceptance yields the message id - without waiting for the turn to start or for the message to enter the Session log. Every failure before that acceptance rejects with neither id, disposing any created handle and rolling back the Activation and parent ownership.
139
+
140
+ `SubagentRuntime.sendMessage()` is the sole model-authored message operation. It accepts the exact live sender plus a target id, permits only a direct parent or direct continuable child, derives sender attribution itself, and routes a direct-child target by Activation residency:
141
+
142
+ | Target Activation state | `sendMessage` |
143
+ |---|---|
144
+ | `running` | steer the nearest step in the same Activation |
145
+ | `waiting` | wake and steer the same Activation |
146
+ | no Activation | cold-resume a new Activation, then steer it |
147
+
148
+ `running` means the Agent has an active driver or maintenance task; `waiting` means no Agent activity is active but its Inbox is nonempty or it owns at least one child Activation that has not completed disposal; `settled` means no Agent activity is active, the Inbox is empty, and every owned child is disposed, at which point the manager disposes the [`AgentHandle`](core.md#creation-and-ownership) and removes the Activation. The manager derives these internal conditions from `Agent.whenIdle()`, `Agent.inbox.hasPending`, the owned-child set, and an Activation generation that invalidates stale observations, rather than maintaining a second execution state machine. After the final Session flush, the child-lock decision uses the synchronous task entry of `Agent.runMaintenance()` to claim the idle phase and close admission in the same JavaScript turn. This conservative rule does not distinguish delivery modes: context parked by `Agent.inject()` can keep an idle Activation and its live ancestors resident until a waking delivery claims it, a queue mutation removes it, or manager teardown discards it.
149
+
150
+ The Agent inbox is the only queue. Every Agent message uses `Agent.steer()`: an idle target starts a turn, while a running target claims it at the nearest step boundary. The browser `subagent.prompt` Remote separately carries `delivery: 'queue' | 'steer'` through the same internal admission path; Queue opens a later FIFO turn, while Steer retains the Agent loop's best-effort nearest-step behavior and the message's human source. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/inserted`, `agent/inbox/claimed`, and `agent/inbox/discarded` events remain the message-lifecycle observations, and the continuation layer defines no second queue.
151
+
152
+ Authority comes from the exact live sender. Parent-to-child delivery requires the target's `SessionHeader.parentSession` to name the sender; child-to-parent delivery requires the sender's resident Activation to name the target. Siblings, ancestors beyond one edge, self-targets, stale Agent objects, and one-shot children are rejected. Each accepted message is framed as `Agent <sender-id> sent a message:` and records `AgentMessageSource`; the source records the sender but grants no authority.
153
+
154
+ For `startContinuable()`, `sendMessage()`, and browser prompt delivery, the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child. The public subagent service exposes no caller-selected Agent-message scheduling; browser human Queue and Steer remain internal adapter choices.
155
+
156
+ Live queue occurrence mutation remains in the Session domain. `session.updateQueue` admits ordinary Edit, Remove, and QueueDock Steer for a live subagent-owned Agent only when its current projected identity is continuable and its descriptor sequence is in that child's own non-seed suffix. The identity projection folds descriptors last-wins so a child descriptor supersedes descriptors retained from fork lineage; the own-suffix sequence check prevents a seed-only ancestor identity from authorizing mutation. One-shot, missing, unknown, corrupt, or cold children remain rejected, and queue mutation never cold-resumes a child. The target Session id is the human authority for these mutations, including pending `nextStep` steering or injected context. Steer requires a queued `MessageId` and an Agent that reports running when the command begins; cancellation after admission uses the Agent's accepted waking `nextTurn` fallback. Edit rewrites content under the same `MessageId`, and both Edit and Steer complete their Inbox work synchronously, so settlement observes only the final state. `agent/inbox/claimed` and `agent/inbox/discarded` wake the watcher to re-read whether any pending occurrence remains; this lets direct Agent delivery resume parked work and lets removing the last parked occurrence settle an idle child. The [human inbox-control Agent Note](../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md) owns these semantics.
157
+
158
+ `SubagentRuntime.interrupt(targetSessionId, authority)` is the one public stop: it authorizes synchronously, issues `Agent.cancel(cause, { keepInbox: true })` on the live target, and returns without awaiting quiescence. The Activation, its unclaimed pending inbox work, and published descendants are untouched; work already claimed into the interrupted turn is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target - unknown, one-shot, or already settled - and a manager-less composition are accepted no-ops. For a live target, a mismatched parent address or caller outside its live ancestry rejects with `UNAUTHORIZED`; stale ancestor objects and self-targeting ancestor requests reject before target lookup.
159
+
160
+ ```ts type-equiv
161
+ /**
162
+ * Authority under which one interrupt request is admitted. `user` carries the
163
+ * durable direct-parent address a human client presented; `ancestor` carries
164
+ * the exact live Agent object whose recorded lineage must contain the caller.
165
+ */
166
+ type SubagentInterruptAuthority =
167
+ | { readonly kind: 'user'; readonly parentSessionId: SessionId }
168
+ | { readonly kind: 'ancestor'; readonly agent: Agent }
169
+ ```
170
+
171
+ Every Activation owns its `AgentHandle` and an `ownedChildren: Set<SessionId>`; because one Session has at most one live Activation, the child Session id identifies the live child without another runtime-incarnation reference. Starting a child or submitting parent-originated work registers the child in a continuation-managed parent's set before the child can run, and that parent cannot settle while the set is non-empty. A top-level or other non-continuation Agent has no Activation and stays outside the waiting graph. Child release happens only after the child has no active Agent work, its Inbox is empty, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal.
172
+
173
+ Final settlement awaits `ctx.sessions.flush(session)` but ignores its participation boolean because an arbitrary listener cannot prove that a persistence backend stored the state. Rejection is logged without failing the Activation, and the manager still disposes the handle and releases ownership; the persisted child state may then be missing or stale on a later resume. Manager unload invokes an internal manager-wide drain that closes admission and disposes every live forest; `drainContinuableDescendants(parents)` closes admission only below exact live host-owned Agents and disposes their continuable descendants while unrelated forests remain live. Both await already-admitted materializations in their scope, propagate cancellation top-down, release handles child-first, and await every selected branch despite individual failures. Durable child Sessions survive that process-local teardown.
174
+
175
+ ```ts type-equiv
176
+ /** Durable attribution for one model-authored message between adjacent Agents. */
177
+ interface AgentMessageSource {
178
+ readonly kind: 'agent-message'
179
+ /** A message another agent addressed to this one (`relay` context form). */
180
+ readonly form: 'relay'
181
+ /** Session id of the Agent whose tool call produced the message. */
182
+ readonly senderSessionId: SessionId
183
+ }
184
+ ```
185
+
186
+ ```ts type-equiv
187
+ /** Options for one model-authored message between adjacent Agents. */
188
+ interface SubagentSendMessageOptions {
189
+ /** Caller cancellation, owning the operation only until inbox acceptance. */
190
+ readonly signal: AbortSignal
191
+ }
192
+ ```
193
+
194
+ ```ts type-equiv
195
+ /** Identities returned once a continuable child accepted its initial prompt. */
196
+ interface ContinuableStart {
197
+ /** The durable child session id, stable across activations. */
198
+ readonly childId: SessionId
199
+ /** The accepted initial prompt's inbox message id. */
200
+ readonly messageId: MessageId
201
+ }
202
+ ```
203
+
204
+ When a resident Activation settles, the manager delivers one notice to the child's durable direct parent describing how that epoch ended and carrying the nonempty text blocks from its final assistant output, or `It left no closing message.` when none remain. That delivery is unconditional for every child whose id a caller received, happens before the ownership release that would let the parent be judged settled, and reaches a resident parent through the same waking Agent delivery as an Agent message. A parent whose own lineage is already tearing down receives it without a wake, because waking an idle Agent starts a turn rather than queueing work. Its source has a distinct kind so a transcript never presents a runtime account as something the child wrote.
205
+
206
+ ```ts type-equiv
207
+ /**
208
+ * Durable attribution for the runtime's own account of a continuable child
209
+ * settling. Deliberately a different kind from
210
+ * {@link AgentMessageSource}: an Agent message is content the sender chose,
211
+ * while this message is the manager stating what became of the child, and a
212
+ * transcript that merged them would credit the child with words it never wrote.
213
+ */
214
+ interface SubagentSettledMessageSource {
215
+ readonly kind: 'subagent-settled'
216
+ /** A runtime account shown without expanding the row (`notice` context form). */
217
+ readonly form: 'notice'
218
+ /** One-line account of how the child ended. */
219
+ readonly summary: string
220
+ /** Session id of the child that settled. */
221
+ readonly senderSessionId: SessionId
222
+ }
223
+ ```
224
+
225
+ The provider participates only in preparing the initial creation spec, where `spawn` and `fork` differ. Its returned spec carries only detached provider-specific creation inputs - the optional parent-history seed - and no Agent, `AgentHandle`, prompt delivery, result, disposal, or resume operation. Cold resume does not dispatch through a provider at all: the manager folds the generic descriptor, calls `ctx.agents.resume()` through the same activation-owner scope, and submits the waiting turn.
226
+
227
+ ```ts type-equiv
228
+ /**
229
+ * What the continuation manager asks a provider for while materializing one
230
+ * continuable child's FIRST activation. The manager has already reserved the
231
+ * durable child identity and owns every later operation, so this request
232
+ * carries only what distinguishes a fresh child from one seeded with parent
233
+ * history.
234
+ */
235
+ interface ContinuableCreateRequest {
236
+ /** The reserved durable child session id, for provider diagnostics. */
237
+ readonly sessionId: SessionId
238
+ /** The delegating parent agent whose history a seeding provider reads. */
239
+ readonly parent: Agent
240
+ /**
241
+ * Caller cancellation, which owns preparation only until the manager accepts
242
+ * the initial prompt into the child's inbox.
243
+ */
244
+ readonly signal: AbortSignal
245
+ }
246
+ ```
247
+
248
+ ```ts type-equiv
249
+ /**
250
+ * A provider's detached contribution to one continuable child's creation. This
251
+ * is DATA, never a capability: it carries no Agent, `AgentHandle`, prompt
252
+ * delivery, result, disposal, or resume operation, because the continuation
253
+ * manager owns the child's whole lifecycle after preparation.
254
+ */
255
+ interface ContinuableCreateSpec {
256
+ /**
257
+ * Completed-turn prefix of the parent's log to seed the child session with,
258
+ * or absent for a fresh child. Same durable contract as
259
+ * `CreateAgentOptions.seed`: contiguous from seq 0, lossless JSON, balanced.
260
+ */
261
+ readonly seed?: readonly SessionEvent[]
262
+ }
263
+ ```
264
+
265
+ The descriptor (`SubagentDescriptorData` in [descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts)) is a mode-discriminated durable identity for every session-backed subagent. Both modes carry the provider name. A `one-shot` descriptor optionally carries a caller-owned display `label`; a `continuable` descriptor requires the delegation `description` as its durable creation label and additionally snapshots resolved child `agentOptions.provider`/`model`/`reasoningEffort` and optional `persona`/`toolFilter` for cold resume. It never snapshots the merge-extensible `AgentOptions` object, so an unrelated extension value cannot break continuation and a later composition input is a deliberate version change. It omits `subagentDepth` (cold resume trusts the persisted header's `delegationDepth` as the monotone floor) and `outputSchema` (one run or Activation's result contract, not durable identity).
266
+
267
+ A local one-shot provider appends the descriptor inside the child's initial turn before its first request. The continuation manager appends the descriptor after any provider-supplied lineage and before the initial prompt is admitted; `Session.inheritedEventCount` remains the fork-lineage boundary: resume-time descriptor authority reads the child's own suffix, while the identity projection folds `subagent/descriptor` last-wins so the child's own descriptor overrides a fork-seeded ancestor's. The event is log-only: no `surfaceOp`, never in model history, and retained across compaction by the append-only log. Malformed current-version descriptors are corrupt; unsupported versions cannot be classified by this runtime.
268
+
269
+ ## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
270
+
271
+ The model-facing `list_agents` adapter reports current activity as `running` or `inactive`. These values do not describe task completion or guarantee that `send_message` will succeed.
272
+
273
+ `SubagentRuntime.listChildren(parentSessionId, signal?)` reads the parent's `subagentCatalog` view through a live-preferred Session observation and releases that observation on success or failure. It returns direct-child entries in parent event order without reading child logs or enumerating the Session corpus. Query failures propagate; a missing catalog projection fails explicitly. Browser rows derive membership from the shared projection store and add activity from Session status; the control stream pushes complete catalog updates. `listDescendants()` recursively reads those catalogs and derives `hasChildren` from each child catalog. [The parent-catalog Agent Note](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns creation, fork isolation, ordering, and persistence costs.
274
+
275
+ `SubagentRuntime.listDescendants(rootSessionId)` recursively calls the same catalog reader in stable pre-order, preserving each parent's event order. One-shot and unknown-mode entries remain traversal nodes; unknown modes produce `unsupported` diagnostics. An unreadable child catalog produces `corrupt` or `unavailable` and stops only that branch. Root read failures, missing services or projections, and cancellation reject the listing. Each reachable catalog is observed once and released before the next read; repeated ids and cycles are skipped. Sessions absent from reachable catalogs are not discovered, including ordinary Session forks and any subagents below those forks. Each row carries its catalog parent and root-relative depth:
276
+
277
+ ```ts type-equiv
278
+ /** One catalog descendant with its direct parent and edge distance from the requested root. */
279
+ type SubagentDescendantListEntry = SubagentListEntry & {
280
+ /** Parent whose catalog contains this child. */
281
+ readonly parentId: SessionId
282
+ /** Edge distance from the requested root; direct children are `1`. */
283
+ readonly depth: number
284
+ }
285
+ ```
286
+
287
+
288
+ ## The terminal result: `SubagentResult`
289
+
290
+ The outcome of a one-shot run, resolved by `SubagentRun.result`. `structured` is present only after a requested `outputSchema` was successfully satisfied; requesting a schema does not guarantee it, and a provider may return `stopReason: 'error'` when the child fails or finishes without a valid capture. A provider may attach a safe, non-assistant `diagnostic` to a non-`completed` result; the provider removes tool inputs, file contents, environment values, credentials, and raw protocol payloads and limits the complete value to 4096 UTF-8 bytes before consumers present it separately from `output`. A non-`completed` `stopReason` means `output` may be partial - the consumer maps it to an `isError` tool result rather than reporting partial output as success.
291
+
292
+ ```ts type-equiv
293
+ /**
294
+ * The terminal outcome of a subagent run, resolved by {@link SubagentRun.result}.
295
+ */
296
+ interface SubagentResult {
297
+ /**
298
+ * The child's final assistant output is the content of its last non-empty
299
+ * assistant message. Empty-content messages, including usage-only messages,
300
+ * are skipped. Without a non-empty message, the output is its accumulated
301
+ * assistant text stream, or `[]` when the child produced neither.
302
+ */
303
+ readonly output: readonly ContentBlock[]
304
+ /**
305
+ * The structured result after a requested `outputSchema` was successfully
306
+ * satisfied. Requesting a schema does not guarantee presence: a provider can
307
+ * end with `stopReason: 'error'` when the child fails or finishes without a
308
+ * valid capture. The structured value is validated against the requested
309
+ * output schema by the provider; `unknown` here because the seam is
310
+ * schema-agnostic.
311
+ */
312
+ readonly structured?: unknown
313
+ /**
314
+ * Provider-authored, non-assistant failure detail for a non-`completed`
315
+ * result. Providers keep this text free of tool inputs, file contents,
316
+ * environment values, credentials, and raw protocol payloads, and limit it
317
+ * to 4096 UTF-8 bytes. Consumers present it separately from {@link output}.
318
+ */
319
+ readonly diagnostic?: string
320
+ /** Why the run ended. A non-`completed` reason means `output` may be partial. */
321
+ readonly stopReason: SubagentStopReason
322
+ }
323
+ ```
324
+
325
+ `SubagentStopReason` is a [merge-extensible derived union](core.md#the-map--derived-union-pattern) - a backend may add variants, so consumers branch on the known cases and treat an unknown terminal reason as a failure:
326
+
327
+ ```ts type-equiv
328
+ /**
329
+ * Why a subagent run ended. Merge-extensible (a backend may add variants);
330
+ * consumers branch on the known cases and fall through `default`. The known
331
+ * cases mirror the harness turn-end vocabulary so the tool layer can map a
332
+ * non-`completed` result to an `isError` tool result.
333
+ */
334
+ interface SubagentStopReasonMap {
335
+ /** The child finished its turn normally. */
336
+ completed: 'completed'
337
+ /** Cancelled through the request signal or disposal. */
338
+ aborted: 'aborted'
339
+ /** Model or transport failure. */
340
+ error: 'error'
341
+ /** The child hit its token ceiling before finishing. */
342
+ 'max-tokens': 'max-tokens'
343
+ /** The child declined the task. */
344
+ refusal: 'refusal'
345
+ }
346
+ ```
347
+
348
+ ## A one-shot run: `SubagentRun`
349
+
350
+ `SubagentRun` is the consumer-owned handle for a published one-shot child - one disposable foreground delegation with one result, never a durable child handle. Prompt submission, turn work, and infrastructure faults after publication belong to `result`. Consumers await that result and always dispose the run to reach quiescence. Child failures resolve with a non-completed stop reason; only unrepresentable infrastructure faults reject. A run has no steering and no resume: continuable conversations have no run at all, because the continuation manager holds their `AgentHandle` directly and orders every turn through the child's own inbox.
351
+
352
+ ```ts type-equiv
353
+ /**
354
+ * ONE-SHOT child handle returned after publication. Prompt submission, turn
355
+ * work, and infrastructure faults after that boundary belong to {@link result}.
356
+ * Consumers await that result and must always {@link dispose} to cancel
357
+ * remaining work and reach quiescence. A run is one disposable foreground
358
+ * delegation with one result; continuable conversations have no run - the
359
+ * continuation manager holds their `AgentHandle` directly and orders every
360
+ * turn through the child's own inbox.
361
+ */
362
+ interface SubagentRun {
363
+ /**
364
+ * Parent-scoped run id. For a local run, this MUST equal the published child
365
+ * session id, whose `parentSession` records `request.parent.session.id`; a
366
+ * remote provider mints an id unique in the parent namespace.
367
+ */
368
+ readonly id: SessionId
369
+ /**
370
+ * The exact published in-process child, or `undefined` for a remote run.
371
+ * When present, its id is {@link id}; the provider retains no ownership
372
+ * implication beyond the run's ordinary {@link dispose} contract.
373
+ */
374
+ readonly localAgent: Agent | undefined
375
+ /**
376
+ * Resolves with the child's terminal {@link SubagentResult} when the run
377
+ * settles. Does NOT reject on a child-level failure - a model/transport
378
+ * failure resolves with `stopReason: 'error'` so the consumer maps it to an
379
+ * `isError` tool result. Rejects on an infrastructure fault the seam cannot
380
+ * represent as a stop reason.
381
+ */
382
+ readonly result: Promise<SubagentResult>
383
+ /**
384
+ * Cancel remaining work, reach child quiescence, and release resources.
385
+ * Idempotent.
386
+ */
387
+ dispose(): Promise<void>
388
+ }
389
+ ```
390
+
391
+ A local one-shot run MUST publish an ordinary child agent/session before `start()` fulfills, return that child session id as `SubagentRun.id`, expose the exact child as `localAgent`, record `request.parent.session.id` in the child's `parentSession` header, and append the resolved descriptor inside the child's initial turn before its first request. Runtime ownership may place the child under the parent, provider, or root scope. A remote provider instead returns a parent-scoped lifecycle id and `localAgent: undefined`; without a local child Session, it is absent from durable enumeration.
392
+
393
+ ## The provider contract: `SubagentProvider`
394
+
395
+ Each provider is a named child-agent transport, and multiple providers may coexist. The service validates requested start-time capabilities before `start()`, and rejects a continuable start on a provider without `prepareContinuable`. `inheritsParentContext` describes only conversation seeding (`fork`: true; `spawn` and `acp`: false), allowing consumers to generate accurate model-facing wording without implying inherited tools, services, or authority. A provider whose one-shot route has static provider-owned defaults publishes optional immutable `agentRouteDefaults`, allowing a Consumer to merge model/tool overrides against the correct baseline before preflight.
396
+
397
+ ```ts type-equiv
398
+ /**
399
+ * One registered transport for running child agents. Providers are trusted
400
+ * same-process implementations; callers treat descriptors and returned values
401
+ * as borrowed immutable data. The service may call one provider concurrently
402
+ * for distinct children. Providers isolate operation-local mutable state; a
403
+ * shared capacity controller may delay an operation but must not couple its
404
+ * settlement or cleanup to a sibling.
405
+ */
406
+ interface SubagentProvider {
407
+ /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */
408
+ readonly name: string
409
+ /** The start-time features this provider supports (see {@link SubagentCapabilities}). */
410
+ readonly capabilities: SubagentCapabilities
411
+ /**
412
+ * Whether the child sees the parent's completed-turn prefix. This is descriptive, not a
413
+ * service-validated start capability: the model-facing tool derives truthful wording from it.
414
+ * It says nothing about tool registration, injected services, or authority inheritance.
415
+ */
416
+ readonly inheritsParentContext: boolean
417
+ /**
418
+ * Optional static provider-owned provider/model route for one-shot Agent
419
+ * options. Consumers merge tool/model overrides over these values before
420
+ * preflight; providers whose route derives from the parent omit it. The value
421
+ * is detached immutable data and requires `agentOptions` support.
422
+ */
423
+ readonly agentRouteDefaults?: Readonly<{ provider: string; model: string }>
424
+ /**
425
+ * Establish a ONE-SHOT child and return its handle after publication.
426
+ * The service has already validated that every requested start-time
427
+ * capability is supported and resolved `request.descriptor`, so a
428
+ * session-backed implementation appends that descriptor inside the child's
429
+ * initial turn. Before fulfillment, the provider owns setup and cleans any
430
+ * unpublished partial resources before rejecting. Ownership transfers on
431
+ * fulfillment; subsequent turn or infrastructure failure settles through
432
+ * the returned run. Distinct starts may overlap; cancellation, failure,
433
+ * result settlement, and disposal remain independent for each run.
434
+ */
435
+ start(request: ResolvedSubagentStartRequest): Promise<SubagentRun>
436
+ /**
437
+ * OPTIONAL (continuable-creation capability): contribute the detached
438
+ * creation inputs that distinguish this provider's continuable children -
439
+ * only whether the child session is seeded with parent history. Method
440
+ * presence IS the capability: the service rejects continuable starts on
441
+ * providers without it, while a provider that has it may still serve
442
+ * ordinary one-shot delegations.
443
+ *
444
+ * This is the provider's ONLY participation in a continuable child. The
445
+ * continuation manager owns identity reservation, composition, Agent
446
+ * creation, prompt delivery, cold resume, ownership, and disposal, so a
447
+ * provider never sees the child's Agent, handle, turns, or teardown.
448
+ * Distinct preparations may overlap; each follows its own signal and returns
449
+ * data belonging only to `request.sessionId`.
450
+ */
451
+ prepareContinuable?(request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>
452
+ }
453
+ ```
454
+
455
+ Provider `start()` fulfills with a published run. The service mints a unique `runId`, snapshots `local` from the provider's exact `localAgent`, observes the result, emits `subagent/start`, and returns the same run; a `start()` rejection implies cleanup of unpublished resources and emits no lifecycle pair, while a post-publication result rejection closes the emitted pair. Each continuable Activation emits the same observe-only pair for its residency epoch, so a cold resume is a new epoch with its own `runId`. The paired `subagent/end` carries the same identity and the final output or infrastructure failure. Both events are observe-only and contain listener exceptions. Their `provider` field names the provider that started the run or Activation epoch; it does not claim that the provider remains registered when the edge is emitted.
456
+
457
+ ## In-process backends: permission, depth, and seed
458
+
459
+ The spawn and fork backends create an ordinary one-shot agent through `parent.ctx`, pass cancellation into core creation, and dispose through `AgentHandle`; a continuable child is instead created by the continuation manager through its own activation-owner scope. Provider removal blocks new starts without revoking accepted runs. Each child gets a new flat scope rather than inheriting parent registrations. Permission, depth, and fork seeding reuse existing Session vocabulary:
460
+
461
+ - **Delegated permission** is captured before the first await. Auto and Full access parents append their captured `permission/preset` identity to the fresh child after fork seeding and sandbox/approval overrides. One-shot and continuable children share this path; cold resume reads only the child log. Read Only and Workspace Write retain the inherited sandbox override plus `approval: never`, so unmatched bundles remain `custom`. Each Auto child call is reviewed independently using existing `parentSession`, creation prompt, and authenticated human/direct-parent messages. The [Auto review decision](../../.agents/notes/implemented/feature/2026-08-28-auto-review.md) defines low/medium/high semantics; no delegation records, receipt, Header field, descriptor field, or Session format is added.
462
+
463
+ - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields - the loop neither sets nor reads them - so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
464
+ - **Fork seeding** uses [`CreateAgentOptions.seed`](core.md#creation-and-ownership) (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log - the parent's events up to and including its last `turn/end` - so the seed is contiguous-from-0 and the [invariants](../../packages/runtime-diagnostics/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
465
+
466
+ `SubagentCatalogEntry` describes a direct child with complete or unknown-mode discovery information; `SubagentCatalogState` is the host-only projection state. `listChildren()` owns a live-preferred parent observation without opening child logs. Browser consumers read `subagentCatalog` through the shared Session projection store and combine membership with Session-list activity. `SubagentCatalogRow` belongs to recursive catalog listing. [The parent-catalog decision](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns the persistent facts and read semantics.
467
+
468
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
469
+
470
+ <a id="cordis-surface"></a>
471
+
472
+ ## Cordis API
473
+
474
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
475
+
476
+ <a id="ctxsubagentmodelselection--subagentmodelselectionconfig"></a>
477
+
478
+ ### `ctx.subagentModelSelection` - `SubagentModelSelectionConfig`
479
+
480
+ Singleton settings owner read when delegation tools are composed for a Session.
481
+
482
+ ```ts cordis-catalog
483
+ /**
484
+ * Read a detached selection preference for the next eligible Session composition.
485
+ * @returns the enabled state and exact allowed routes.
486
+ */
487
+ current(): SubagentModelSelectionSettings
488
+ ```
489
+
490
+ Source: [`packages/subagent/tool-subagent/src/model-selection-settings.ts`](../../packages/subagent/tool-subagent/src/model-selection-settings.ts)
491
+
492
+ <a id="ctxsubagents--subagentruntime"></a>
493
+
494
+ ### `ctx.subagents` - `SubagentRuntime`
495
+
496
+ Named provider registry with one-shot runs, durable discovery, and continuable-child operations.
497
+
498
+ ```ts cordis-catalog
499
+ /**
500
+ * Resolve a delegation tool's depth policy against the current user setting.
501
+ * @param configured - Explicit tool limit, or provider-managed for external delegation.
502
+ * @returns The numeric limit, or undefined when the provider owns depth enforcement.
503
+ */
504
+ resolveMaxDepth(configured?: number | 'provider-managed'): number | undefined
505
+
506
+ /**
507
+ * Establish one durable continuable child and deliver its initial prompt.
508
+ * Resolves when the child's inbox accepts that prompt, without waiting for the
509
+ * turn to start or for the message to reach the Session log; any earlier
510
+ * failure rejects with no ids and rolls back the child entirely.
511
+ * @param spec - provider, delegation request, and caller cancellation.
512
+ * @returns the durable child id and the accepted prompt's message id.
513
+ * @throws when continuation services are unavailable or materialization fails.
514
+ */
515
+ async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
516
+
517
+ /**
518
+ * Steer one model-authored message to the sender's direct parent or direct
519
+ * continuable child. A running target admits it at the nearest step boundary;
520
+ * an idle target starts a turn, and an absent direct child cold-resumes from
521
+ * persistence. The service derives durable sender attribution from the exact
522
+ * live sender. Caller cancellation stops only pre-acceptance work.
523
+ * @param sender - exact live Agent authorizing and originating the message.
524
+ * @param targetId - durable direct-parent or direct-child session id.
525
+ * @param content - model-authored content to deliver.
526
+ * @param options - caller cancellation before inbox acceptance.
527
+ * @returns the accepted message's inbox id.
528
+ * @throws when continuation services are unavailable, adjacency is rejected,
529
+ * or the message was not admitted.
530
+ */
531
+ async sendMessage( sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions, ): Promise<MessageId>
532
+
533
+ /**
534
+ * Interrupt one live continuable child's current turn under a human parent
535
+ * address or an exact live ancestor Agent. Fire-and-return: the cancel
536
+ * signal is issued before this returns, but the target may keep running
537
+ * until it observes the signal. Unclaimed pending inbox work, the Activation,
538
+ * and published descendants are preserved; claimed work is not requeued.
539
+ * Once the interrupted driver is idle, a waking send resumes the parked FIFO
540
+ * queue. An absent target - including a one-shot or unknown id -
541
+ * is an accepted no-op, as is a manager-less composition, which cannot own a
542
+ * live Activation.
543
+ * @param targetSessionId - the durable child session id to interrupt.
544
+ * @param authority - the human parent address or exact live ancestor Agent.
545
+ * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
546
+ * live target.
547
+ */
548
+ interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
549
+
550
+ /**
551
+ * Close continuable admission below exact live parent Agents, stop only their
552
+ * visible descendant Activations synchronously, then await admitted scoped
553
+ * materializations and release those forests child-first. The scoped cutoff
554
+ * lasts until each exact parent leaves the registry; unrelated parent trees
555
+ * remain live.
556
+ * @param parents - exact host-owned parent Agents entering teardown.
557
+ * @returns once every retained descendant Activation released its `AgentHandle`.
558
+ * @throws an aggregate error after all branches settle when any failed.
559
+ */
560
+ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
561
+
562
+ /**
563
+ * Release selected resident continuable direct children of one exact live
564
+ * parent. Other children of the same parent remain admitted and resident.
565
+ * Absent targets and a manager-less composition are accepted no-ops.
566
+ * @param parent - exact live direct parent authorizing the selected release.
567
+ * @param childIds - durable direct-child ids to release when resident.
568
+ * @returns once every selected Activation released its `AgentHandle`.
569
+ * @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
570
+ * different parent or the supplied parent identity is stale.
571
+ */
572
+ async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>
573
+
574
+ /**
575
+ * Read the parent's durable direct-child catalog without loading or resuming an Agent.
576
+ * The service owns and releases the live-preferred Session observation.
577
+ * @param parentSessionId - parent whose direct children are requested.
578
+ * @param signal - cancellation forwarded to the Session query.
579
+ * @returns catalog children in parent event order.
580
+ * @throws {@link SubagentError} when query or catalog projection is unavailable.
581
+ * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
582
+ */
583
+ listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>
584
+
585
+ /**
586
+ * Recursively list reachable parent catalogs in stable pre-order, preserving
587
+ * each catalog's event order. Each row carries its catalog parent and depth;
588
+ * one-shot and unknown-mode children remain traversal nodes. Unknown modes
589
+ * produce unsupported diagnostics. Unreadable child catalogs produce corrupt
590
+ * or unavailable diagnostics and stop only that branch. Root read failures,
591
+ * missing services or projections, and cancellation reject the whole listing.
592
+ * Each catalog is observed once and released before the next read. No Agent
593
+ * is loaded or resumed; Sessions absent from reachable catalogs are omitted.
594
+ * @param rootSessionId - session whose catalog starts descendant discovery.
595
+ * @param signal - cancellation forwarded to and checked around each catalog read.
596
+ * @returns children and branch diagnostics in parent-catalog pre-order.
597
+ * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.
598
+ * @throws SessionQueryError when the root catalog cannot be read.
599
+ */
600
+ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
601
+
602
+ /**
603
+ * Deliver one browser-authored message to a continuable child through the
604
+ * exact live direct parent, retaining the caller-minted request identity and
605
+ * validated browser zone on the accepted message. Success identifies the
606
+ * message the child's inbox accepted; later execution is independent of this
607
+ * call. Queue delivery targets a later turn; steer delivery targets the
608
+ * nearest step and retains the Agent loop's best-effort fallback semantics.
609
+ * Image parts are admitted and persisted through the attachment store
610
+ * before delivery, and the child's model must accept image input.
611
+ * Cold resume at capacity rejects with `subagent/delivery-unavailable`.
612
+ * @param request - durable address, delivery, minted identity, content, and optional browser zone.
613
+ * @param signal - carrier cancellation, owning the call until inbox acceptance.
614
+ * @returns the accepted message's inbox identity.
615
+ * @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
616
+ * `subagent/invalid-time-zone`, `subagent/parent-unavailable`,
617
+ * `subagent/not-resumable`, `subagent/unauthorized`,
618
+ * `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
619
+ */
620
+ @Remote('prompt') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>
621
+
622
+ /**
623
+ * Remote face of {@link interrupt} under one durable parent address. No
624
+ * catalog, history, persistence, or parent Agent lookup runs: the core
625
+ * primitive alone authorizes the address against the live Activation, which
626
+ * is what keeps a live child interruptible while its parent Agent is offline.
627
+ * Absent, idle, and already-completed targets are accepted no-ops there.
628
+ * @param childSessionId - durable child session id to interrupt.
629
+ * @param parentSessionId - durable direct parent whose authority is claimed.
630
+ * @param mode - required continuable-address discriminator.
631
+ * @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
632
+ * @throws {RemoteError} `gateway/bad-request` for an empty id,
633
+ * `subagent/unauthorized` when the address does not own the live target,
634
+ * otherwise `gateway/internal`.
635
+ */
636
+ @Remote('interruptByParent') interruptByParent( childSessionId: SessionId, parentSessionId: SessionId, mode: 'continuable', ): SubagentInterruptReceipt
637
+
638
+ /**
639
+ * Register a provider under its name. Registration is effect-scoped and HMR
640
+ * safe; removing a provider blocks new starts but does not revoke runs that
641
+ * were already returned to their holders.
642
+ * @param provider - the trusted provider implementation.
643
+ * @returns the exact Cordis effect disposer.
644
+ */
645
+ registerProvider(provider: SubagentProvider): () => void
646
+
647
+ /**
648
+ * Look up a provider by name.
649
+ * @param name - the provider name.
650
+ * @returns the provider, or undefined when absent.
651
+ */
652
+ getProvider(name: string): SubagentProvider | undefined
653
+
654
+ /**
655
+ * List registered provider names in insertion order.
656
+ * @returns the registered names.
657
+ */
658
+ list(): string[]
659
+
660
+ /**
661
+ * Establish a published child on the named provider. Capability and semantic
662
+ * checks run before delegation. Provider ownership lasts until its promise
663
+ * fulfills; a rejection therefore has no run for the caller to dispose and
664
+ * emits no run lifecycle events. Post-publication turn and infrastructure
665
+ * failures settle through the returned run.
666
+ * A catalog append failure disposes the run and handles its result rejection;
667
+ * the caller receives the catalog error even if disposal also fails.
668
+ * @param name - the provider to use.
669
+ * @param request - child label, prompt, parent, signal, and optional capabilities.
670
+ * @returns the published holder-owned run.
671
+ */
672
+ async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
673
+ ```
674
+
675
+ Types: [Agent](core.md) · [ContentBlock](llm-streaming.md) · [MessageId](llm-streaming.md) · [SessionId](core.md)
676
+
677
+ Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
678
+
679
+ <a id="subagent-events"></a>
680
+
681
+ ### `subagent/*` events
682
+
683
+ <a id="subagentend--emit"></a>
684
+
685
+ #### `subagent/end` - emit
686
+
687
+ A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as `subagent/start`, so the lifecycle pair reaches the same scoped audience.
688
+
689
+ ```ts cordis-catalog
690
+ /**
691
+ * A published child settled. Scope-filtered dispatch uses the same delegating
692
+ * parent carrier as `subagent/start`, so the lifecycle pair reaches the
693
+ * same scoped audience.
694
+ * @param info - the run identity and terminal outcome.
695
+ * @dshScopeScan unsupported
696
+ * @mode emit
697
+ */
698
+ 'subagent/end'(this: Scoped<SubagentRuntime>, info: SubagentRunEndInfo): void
699
+ ```
700
+
701
+ Types: [Scoped](scope.md)
702
+
703
+ Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
704
+
705
+ <a id="subagentprovider-added--emit"></a>
706
+
707
+ #### `subagent/provider-added` - emit
708
+
709
+ A provider became resolvable in the registry.
710
+
711
+ ```ts cordis-catalog
712
+ /**
713
+ * A provider became resolvable in the registry.
714
+ * @param provider - the registered provider.
715
+ * @mode emit
716
+ */
717
+ 'subagent/provider-added'(provider: SubagentProvider): void
718
+ ```
719
+
720
+ Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
721
+
722
+ <a id="subagentprovider-removed--emit"></a>
723
+
724
+ #### `subagent/provider-removed` - emit
725
+
726
+ A provider left the registry. Accepted runs remain holder-owned.
727
+
728
+ ```ts cordis-catalog
729
+ /**
730
+ * A provider left the registry. Accepted runs remain holder-owned.
731
+ * @param name - the provider name that no longer resolves.
732
+ * @mode emit
733
+ */
734
+ 'subagent/provider-removed'(name: string): void
735
+ ```
736
+
737
+ Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
738
+
739
+ <a id="subagentstart--emit"></a>
740
+
741
+ #### `subagent/start` - emit
742
+
743
+ A provider established a published child. For in-process providers, `ctx.agents.get(info.id)` resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with `subagent/end`.
744
+
745
+ ```ts cordis-catalog
746
+ /**
747
+ * A provider established a published child. For in-process providers,
748
+ * `ctx.agents.get(info.id)` resolves during this notification.
749
+ * Scope-filtered dispatch keys the carrier by the delegating parent, so a
750
+ * parent-scoped listener observes only its own delegations. Paired with
751
+ * `subagent/end`.
752
+ * @param info - the provider and published child identity.
753
+ * @dshScopeScan unsupported
754
+ * @mode emit
755
+ */
756
+ 'subagent/start'(this: Scoped<SubagentRuntime>, info: SubagentRunInfo): void
757
+ ```
758
+
759
+ Types: [Scoped](scope.md)
760
+
761
+ Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
762
+ <!-- END GENERATED cordis-surface -->