Custom agent preset mounting subagent tool outside an isolate group fails to mount → agent loses subagent spawn capability

[quocnm102]

Description

Environment

• DeepSeek Harness (dsh), desktop app build
• Custom agent preset produced by authoring a composition modeled on the shipped standard preset

Summary

When switching an agent session from the built-in standard preset to a custom preset, the subagent tool is not exposed in the session's tool list. The session only has list_agents, send_message, and interrupt_agent. As a result, the agent cannot spawn nested subagents (spawn-tool-unavailable), which breaks multi-agent orchestration flows that rely on nested delegation.

Root cause (tentative)

The custom preset mounts the subagent delegation tool at the top level of the composition, i.e. without the wrapping cordis:group that carries the isolate: { workflowEngine: true } realm.

The shipped standard preset (and the cordis preset) mount the subagent delegation toolset inside such a group:

- id: delegation
  name: cordis:group
  group: true
  isolate:
    workflowEngine: true
  config:
    - id: tool-subagent-control
      name: '@deepseek-ai/dsh-tool-subagent-control'

    - id: tool-subagent-list-agents
      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'

    - id: tool-subagent
      name: '@deepseek-ai/dsh-tool-subagent'
      config:
        provider: spawn
        toolName: subagent
        modelSelectionSettings: true
        backgroundMode: continuable
    # ... fork, codex, claude-code, workflow, ralph ...

The custom preset instead mounts it directly:

- id: tool-subagent
  name: '@deepseek-ai/dsh-tool-subagent'
  config:
    provider: spawn
    toolName: subagent
    modelSelectionSettings: true
    backgroundMode: continuable
- id: tool-subagent-control
  name: '@deepseek-ai/dsh-tool-subagent-control'
- id: tool-subagent-list-agents
  name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'

The standard/agent.cordis.yml header documents this constraint explicitly:

A service row here MUST sit inside a group carrying an isolate realm. Without one it publishes into the root realm, where it is process-global — another preset publishing the same name collides, and a host reader would resolve one preset's instance for every session; dsh-agent-presets rejects that at mount.

And in the delegation section:

The subagents registry and its spawn/fork backends live in the HOST composition: the registry is a process singleton ... workflows is different — nothing outside an agent reads it — so every row that reaches it shares one entry-local realm here.

So the hypothesis is: mounting tool-subagent at the root realm (without the isolate group) causes a mount-time collision that dsh-agent-presets rejects, leaving the session without the subagent tool. list_agents/send_message/interrupt_agent still appear because those control tools mounted fine, but the actual spawn tool is missing.

Expected behavior

A custom preset modeled on standard should be able to expose the subagent spawn tool when the delegation toolset is mounted with the same isolate: { workflowEngine: true } grouping as the shipped presets — or, failing that, the mount rejection should fail loudly at preset load time with a clear diagnostic (rather than silently omitting the tool from the session's tool list, which surfaces only later as an opaque "tool not available" at the point the agent tries to delegate).

Steps to reproduce

1. Copy the standard preset into a new preset directory and author a custom persona/instructions (keep the rest, including the delegation group, intact in this first step).
2. In the custom preset, move the tool-subagent row (and its siblings) out of the delegation cordis:group / isolate block so they sit at the composition top level.
3. Switch the session's agent preset to this custom preset (default preset mapping).
4. Start a session and ask the agent to delegate to a subagent.
5. Observe the agent's tool list contains only list_agents / send_message / interrupt_agent, not subagent.

Impact

Multi-agent orchestrator flows that delegate through nested subagent spawn fail with "tool subagent not exposed in session tool list", blocking the entire workflow. The failure only appears at delegation time, making it hard to trace back to the preset composition.

Possible improvements

1. Fail loudly at mount time — dsh-agent-presets should emit a noticeable error/warning when a subagent (or other registry-backed) tool row is mounted outside its required isolate realm, instead of silently leaving the tool absent.
2. Document the constraint — the standard/agent.cordis.yml header already states it; consider surfacing it in the public docs on authoring custom presets (a "delegation must live inside an isolate: workflowEngine group" note), since presets are the official customization path.

[quocnm102]

Update / follow-up — possible core-side improvement (fail-closed on preset mount failure)

After digging into the shipped runtime (@deepseek-ai/dsh-agent-presets/lib/types/mount.js), the mount path does already throw a clear diagnostic when a preset publishes a process-global service:

row(s) published process-global service(s) [subagent]; a preset service must
sit behind an `isolate` realm or move to the host composition

i.e. mountPreset rejects with RemoteError('agent-preset/invalid', ...) and names the leaked service(s). So the reject itself is loud in the library.

What we observed at the session level, however, is different: the session starts and runs normally, but the tool list is simply missing subagent (only list_agents / send_message / interrupt_agent remain). That suggests the mount rejection is surfaced only at preset authoring/selection time, but when the same invalid preset is later applied to a concrete session, the failure may be swallowed (or downgraded to a warning) higher up in the boot/join path — letting the session come up with a partially-mounted composition rather than failing closed.

Request for the team: please confirm (or fix) the behavior so that a preset that fails to mount is surfaced fail-closed to the user when they select/apply it, rather than silently producing a session that runs without the missing tool. Concretely:

1. When a chosen/selected agent preset fails to mount (e.g. agent-preset/invalid), the session should refuse to start — or at minimum show a prominent, blocking error to the user — instead of starting with a tool silently absent.
2. The diagnostic should carry the preset id + the leaked service name(s) to the UI (the library already computes both: preset.id and leakedServices(...)).
3. If the roster/pre-selection path already surfaces this (e.g. the agent-preset/selected event or authoring-time validation), it would help to document/verify that the runtime apply path surfaces the same error, since the observed behavior suggests it does not.

This keeps the isolate realm constraint intact (which is clearly intentional and enforced in code) and instead closes the UX gap: an invalid custom preset should never fail silently, only loudly.

[PerryLink]

Your tentative root cause is correct, and here is the shipped shape it should match.

packages/bundle/web-app/presets/standard.patch.yml:80-91 mounts exactly what you describe - the delegation toolset inside a group that carries the realm:

- id: delegation
  name: cordis:group
  group: true
  isolate:
    workflowEngine: true
  config:
    - id: tool-subagent-control
      name: '@deepseek-ai/dsh-tool-subagent-control'
    - id: tool-subagent-list-agents
      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
    - id: tool-subagent
      name: '@deepseek-ai/dsh-tool-subagent'

(then tool-subagent-fork, -codex, -claude-code, ... as further rows in the same group). The isolate key maps the service name to true, which is what gives the group its own realm and its own service instance - per the composition reference, "a preset plugin that provides a service isolates the provider and all consumers together".

Why mounting outside the group loses the capability rather than raising a visible error. The registry enforces a realm invariant for preset services, in two places:

packages/preset/agent-preset-registry/src/invariant.ts:41
  'a preset service must sit behind an `isolate` realm or move to the host composition'
packages/preset/agent-preset-registry/src/mount.ts:263
  throw new Error(`Preset services require isolate realms: ${leaked.join(', ')}`)

and mount.ts:77-79 states the consequence precisely: a provider without an isolate realm stores its implementation under the root realm, while one inside a realm stores under a realm-private symbol. So a delegation tool mounted at the top level resolves the wrong instance - or none - and the tool simply is not in the session's list. Your symptom (list_agents/send_message/interrupt_agent present, subagent absent) is exactly the shape of "the consumer is there, the provider's realm is not".

The fix is a copy: wrap your delegation rows in the same cordis:group with the same isolate: { workflowEngine: true } that lines 80-84 use. Nothing else about your preset needs to change.

On your follow-up: the registry already contains an activation failure rather than letting it escape - agent-preset-registry/tests/registry.spec.ts:137 covers a plugin activation failure being refused, and mount.ts:263 throws a named error. What is missing is what you actually asked for: that refusal being surfaced as a preset mount failure instead of showing up as a quietly missing tool. That is a fair ask and worth keeping in the thread.

Boundary: read from the committed tree at 00102833df (dsh-v0.1.7-alpha.2). I did not run a custom preset, so the last mile - whether your preset's other rows introduce a second problem - is untested on my side.