Agent roles and storage

Guide: Install · Sources · Resources · Services · Translation · Settings · Workspace · Agent roles · Layout audit

Installed suites and user entries appear together in the Skills, Commands and Agent personas tabs. Source filters distinguish them; entries retain unique identities even when names match. A managed suite entry is read-only — content edits are refused because the suite owns the file, so an upstream refresh can replace it freely. An agent persona is the one exception: its pencil opens the routing form alone (provider, model, reasoning effort) and the server accepts exactly that frontmatter diff; skills and commands offer only the enable switch. External local source files are displayed but remain read-only; create a user entry to customize one.

Agent persona details put linked provider and model dropdowns above the Markdown editor. Providers come from DSH’s live LLM registry; models load only for the selected provider. Select inheritance to use the parent session. Unavailable saved values are preserved until changed, and failed directory requests can be retried. The form warns when the stored routing declaration is one the executor would ignore, and it no longer edits tools / disallowedTools — those keys stay in the frontmatter, preserved by the raw editor, but the form has no control for a field that has no effect. Unknown keys, arrays and comments are preserved. Example:

---
name: reviewer
description: Review implementation changes
model: my-provider/my-model
reasoning_effort: high
tools: [read_file, search_files]
---
Review correctness and report concrete evidence.

Routing is exact-or-inherited. Omit model, or use inherit, to run the child on the parent’s route. An explicit provider and model together select that route, and it is validated against the live LLM adapter before the child starts. Every other declaration — a bare model ID, a provider/model string, a Claude alias such as sonnet, a lone provider — is ignored with a diagnostic and the child inherits the parent route. tools and disallowedTools are preserved in the file and stay editable, but they are not applied.

reasoning_effort sets the model’s reasoning intensity; reasoningEffort is also accepted, but conflicting values are rejected. Use an effort ID supported by the selected DSH model. The reasoning-effort selector loads the selected model's advertised levels and default through DSH. Selecting Automatic removes the explicit effort. Changing the provider or model through the controls clears the old effort; an unavailable saved value remains visible until changed. Inherited or unresolved models offer Automatic and any saved value, without guessing supported levels. Loading failures offer retry. Selecting a level saves reasoning_effort and removes the camelCase alias, while preserving unrelated frontmatter and Markdown. An omitted effort inherits the parent’s latest request effort only when the effective provider/model route is unchanged; changing the route uses the new model’s default effort. The host LLM runtime validates the effective provider, model and effort before a child starts. When a declared route or effort is unsupported, the whole declaration is dropped and the child inherits the parent route, with a diagnostic.

The subagent-catalog follows DSH’s skills catalog mechanism: every agent/pre-step reads a current role snapshot, hashes the published entries, and compares them with the latest visible catalog in the session log. The first nonempty catalog is injected once; changes publish a complete replacement; removing all roles publishes an explicit empty catalog. Restore and fork use durable entries, and compaction that hides a catalog causes it to be republished. Incomplete reads do not publish partial replacements. The model-facing catalog is a reminder that renders each readable role name in backticks with its description only; role titles, configured routes and full persona bodies are not part of it. Change detection covers the name, the durable role identity, the description and the configured route, so renaming a title alone does not republish. Opaque source-qualified IDs remain in the durable source for execution, not in the model-facing prose.

GET /api/agent-plugins/model-catalog?provider=<id>&model=<id> resolves only that exact model through llm.resolveModelInfo. The response adds reasoning: { efforts: [{ id, name, description? }], defaultEffort? }; models without advertised reasoning return an empty effort list. Omitting model keeps the provider/model-list behavior. Adapter waits are bounded to ten seconds, and failures return HTTP 503.

Delegation modes

Without Agent Teams, call subagent_role with the exact catalog agent and a self-contained prompt. Omitted or true run_in_background returns { kind: 'continuable', subagentId } immediately; false waits for { kind: 'foreground', runId, output }. There is no tracked-job channel or action parameter. The child does not inherit the parent conversation.

With Agent Teams, call spawn_teammate_role(agent, name, description, prompt). Optional provider, model and reasoning_effort preserve the call-over-card routing rules; provider means the LLM route, not the Team transport. Only the Lead creates members, after an explicit user request for Team work. Members start fresh with no foreground/fork parameter. The result carries target, role identity and effective model route; native Team tools own messaging, interruption, roster and shared tasks. Reuse members for follow-up tasks. Multiple members can share a role, but member names cannot be reused.

The model-visible directory is titled subagent-catalog in both modes, and role-tool parameters refer to that exact title. In Team mode it remains a compact list for discovery and selection: match a specialty before using the enhanced entry, or use native creation for no match or a required fork. Only the Lead sees the catalog and the enhanced creation tool; members and non-Team subagents cannot see or call that tool. The execution-time Lead check remains in place. Mode or guidance-text changes publish one replacement on the next step even when role names are unchanged; earlier history is retained. Late Team activation withdraws the standalone entry; enhanced creation still needs sessions, session query and system-prompt services. Missing dependencies do not fall back to invisible standalone children.

A separate Team coordination system section serves both native and role-created members, even with an empty or filtered role catalog. It requires only agents, Agent Teams and system-prompt services. After the user authorizes Team work, the Lead is guided to delegate independent research, broad exploration, implementation and verification early while retaining user clarification, scope decisions, direction updates and final acceptance. Members receive their actual Team name, the reserved Lead address target: "lead" and guidance for reporting blockers, evidence and outcomes. This is workflow guidance, not new permission or a replacement for host policy.

The coordination section is resolved for the exact live Agent at each prompt assembly, so it remains available after compaction or member resume without adding another catalog message. It discourages status polling and blocking merely to collect results: progress updates do not claim completion, and final delivery still requires the necessary member results and verification. Shared task updates and messages carry user corrections to existing members; overlapping work needs an explicit handoff. Enhanced creation also puts the readable role name and Team identity into its initial context message; opaque role IDs stay in durable metadata.

Role instructions and the validated route are fixed before the first request and persisted in a plugin-owned message source through the host inbox. Cold resume and plugin reload use that creation snapshot, not an edited role card. Keep the plugin installed to restore its composition. The native rc.2 roster is not a route readout: a role member carries the role route on its own Agent while it is resident, so the running row matches, and an idle member without a live Agent falls back to the Lead’s model. Take the effective route from this tool’s result, not from list_agents. Calls incur normal provider usage.

Roles are not skills or slash commands. Project discovery follows the calling directory and scanProjectLayouts. Edits and switches affect later steps/new members, not already accepted work or member snapshots. External discovery uses scan-cache TTL or manual refresh, without a file watcher. tools and disallowedTools are preserved but do not enforce permissions. Verify child reports before relaying them.

Plugin state is under $DSH_HOME/agent-plugins (default ~/.dsh/agent-plugins): checkouts in .sources, installation state in state.json, and mutable suite data/configuration in data. The entries you author live in the shared Agent layout root, ~/.agents/{skills,commands,agents}/, next to the ~/.agents/mcp.json and ~/.agents/lsp.json service declarations. Former userRoot and dataRoot settings are migration inputs only. Startup migrates old roots, agent-plugins-data, data/user, user/<kind> entries and the old mcp-servers.json / lsp-servers.json declarations. Conflicting files remain untouched and block activation with their paths; resolve conflicts before restarting. Project-dimension and externally registered local source directories retain their existing in-place semantics.

Model routing was informed by DSH Subagent Model Router; frontmatter follows Claude Code subagent conventions.