dsh-subagent

Usage tutorial

1. Open the Subagents settings page

Open Settings → Subagents. The initial profiles are:

Profile	Backend	Model route	Reasoning	Child context
fast	spawn	Follow conversation	Custom low	Independent context
reviewer	fork	Follow conversation	Custom high	Inherits the completed parent conversation

These are editable user profiles supplied as initial plugin settings, not read-only DSH system profiles.

2. Configure a profile

Select Edit on a profile and choose:

1. Backend — spawn or fork.
2. Model configuration — follow the current conversation or select a custom Provider and Model.
3. Reasoning configuration — follow the conversation/model default or select a custom effort.
4. Description — explains the profile's intended work to the model.

Custom routing always stores Provider and Model together. If the selected route disappears from the live model catalog, the UI shows the stale value and blocks saving until a valid route is selected.

3. Create a specialized profile

Select New subagent, enter a lower-case identifier such as deep-research, and configure its backend and policies. Profile names must match:

^[a-z][a-z0-9_-]{0,23}$

The profile immediately creates a tool named subagent_deep-research for each live root Agent.

4. Use a profile in a conversation

Ask the Agent to delegate work to the named profile, for example:

Use the reviewer subagent to inspect this change for correctness and test gaps.

The Agent can call subagent_reviewer; routing choices are fixed by the saved profile and are not exposed as tool-call arguments.

Configuration format

The Settings page and custom_subagent tool write the same dsh-subagent settings namespace. A representative settings.yaml section is:

dsh-subagent:
  profiles:
    - name: fast
      description: Quick lookups and lightweight checks.
      backend: spawn
      modelRouting:
        mode: follow-conversation
      reasoning:
        mode: custom
        effort: low
    - name: reviewer
      description: Review changes with a dedicated model.
      backend: fork
      modelRouting:
        mode: custom
        provider: openai-codex
        model: gpt-5.6-luna
      reasoning:
        mode: custom
        effort: high

modelRouting is either { mode: 'follow-conversation' } or an atomic custom { mode: 'custom', provider, model } record. reasoning independently follows the conversation or stores { mode: 'custom', effort }.

The plugin does not read the retired $DSH_HOME/custom-subagents.json file. Flat provider, model, and reasoningEffort fields belong to an obsolete pre-release format and are rejected.