Tianyi Cui
8bb8ac8b3c
The background-task change repeated its lifecycle design across implemented RFCs, package READMEs, JSDoc, test commentary, and model-visible schemas. That repetition obscured the contracts that maintainers must preserve and added avoidable prompt tokens. Rewrite the implemented RFCs around the current design, keep authorization, exact-owner cleanup, wait/abort ordering, producer quiescence, and teardown-failure guarantees at their owning surfaces, and remove peer surveys, review history, control-flow narration, and emphatic restatement. Shorten the task and subagent schema wording, synchronize the bilingual tool cookbook, and regenerate the config, service, RFC, tool, and replay snapshot derivatives. Runtime behavior is unchanged; test edits update prose-only assertions and descriptions.
52 lines
4.0 KiB
Markdown
52 lines
4.0 KiB
Markdown
# @deepseek-ai/dsh-tool-subagent
|
|
|
|
The model-facing delegation tool over one configured `ctx.subagents` provider. Changing the provider changes transport without changing the execution contract.
|
|
|
|
## Provider selection and lifecycle
|
|
|
|
Each plugin instance binds one `provider` to one `toolName`; the model receives no provider selector. Load another distinctly named instance to expose another transport. The tool registers only while its provider exists, avoiding sibling load-order and provider-reload dependencies. Its description follows `provider.inheritsParentContext`: fresh children require standalone prompts, while forked children already see completed parent turns.
|
|
|
|
A foreground call passes the execution signal through startup and execution, awaits `run.result`, and always awaits `run.dispose()` before returning. Only `completed` returns final text; abort, refusal, token limit, and other failures become errored tool results without partial output.
|
|
|
|
With `run_in_background: true`, the tool registers the parent-owned task before starting the provider. A task-owned signal covers pending startup and the child after the starting call returns. `task_kill` and owner disposal abort it. Settlement awaits startup rollback or child disposal, then maps completed final text, abort to `killed`, and other failures to `failed`. The task has no incremental read; generic task tools own later status, collection, cancellation, and notices. See the [background subagent RFC](../../../docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md).
|
|
|
|
`toolFilter` changes the child's global tool layer but is not a parent-derived authority ceiling. See the [agent-scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
|
|
|
|
## Config
|
|
|
|
| Key | Meaning |
|
|
|---|---|
|
|
| `provider` (required) | Provider name (`spawn`, `fork`, `acp`, ...). |
|
|
| `toolName` | Model-facing name, default `subagent`; distinct for every loaded instance. |
|
|
| `enableRunInBackground` | Exposes background mode, default `true`; disabling also rejects forced background calls. |
|
|
| `agentOptions` | Default child options, currently including `model`. |
|
|
| `persona` | Per-child persona; requires provider `persona` capability. |
|
|
| `toolFilter` | Per-child global-tool restriction; requires `toolFilter` capability. |
|
|
| `maxDepth` | Absolute delegation-depth cap; requires `depthLimit` capability. |
|
|
|
|
## Model Experience
|
|
|
|
### Tool schema
|
|
|
|
**What the model sees**: The generated default [`subagent` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent) under this instance's configured name while its provider exists. Provider context inheritance changes the tool and prompt descriptions; enabled background mode adds `run_in_background`.
|
|
|
|
**Token effect**: Fixed schema cost per parent request; each provider instance adds one schema.
|
|
|
|
### Foreground result
|
|
|
|
**What the model sees**: The call retains the description and prompt. Success contains only the child's final text; other outcomes become `Error: <message>`. Intermediate child steps stay out of the parent.
|
|
|
|
**Token effect**: The prompt and result remain in parent history until compaction; child working context remains in the child.
|
|
|
|
### Background task result
|
|
|
|
**What the model sees**: Start returns exactly `started background subagent task <id>`. The generic task surface provides later status, final output, cancellation responses, and notices.
|
|
|
|
**Token effect**: The acknowledgement is retained; final output enters parent history only when collected or injected.
|
|
|
|
## Known Limitations and Deferred Work
|
|
|
|
- **Background runs expose final output only** — intermediate child steps stay in the child session.
|
|
- **Duplicate names across waiting instances are detected late** (`TODO(subagent-dup-toolname)`) — preventing provider-registration rollback requires a registry of intended names.
|
|
- **Child policy is fixed per instance** — another model, persona, tool filter, or depth cap requires another distinctly named tool.
|