Skip to content

feat(subagents): builtin override documents retune shipped delegates - #1365

Open
shabhui wants to merge 1 commit into
vastsa:mainfrom
shabhui:feat/subagent-builtin-overrides
Open

shabhui wants to merge 1 commit into
vastsa:mainfrom
shabhui:feat/subagent-builtin-overrides

Conversation

@shabhui

@shabhui shabhui commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

What happened

The five shipped builtin subagents (explorer, code-reviewer, test-runner, fixer, ui-designer) could only be switched on or off (ADR 0270). A user who wanted test-runner pinned to a cheaper model, or fixer with a stricter write policy, had no supported path: copying the builtin into ~/.agents/subagents creates a second Settings row that claims the same handle, and the two enablement switches then disagree.

What this adds

An app-owned override directory, <data>/subagent-overrides/*.md, whose Markdown documents retune a shipped builtin by name (ADR 0319):

  • an override replaces the named builtin's definition in the catalog; it never adds a delegate or a Settings row — a name no builtin uses is a load diagnostic, not a new delegate;
  • overrides parse as builtin source, so the ADR 0270 Settings switch still governs the retuned definition and Settings renders one row;
  • user documents keep outranking overrides, which keep outranking the shipped constants;
  • the directory is re-read on every session launch and every subagent/catalog request, so an edit reaches every session — open ones included — on its next prompt;
  • Electron main wires builtinOverridesDir(dataDir); the loader stays directory-agnostic and testable.

Example: a <data>/subagent-overrides/test-runner.md with a different model: pin changes which model the shipped test-runner delegate uses, with no second row anywhere.

Docs

  • new ADR 0319 (context, decision, alternatives), ADR 0062 status line + §1 amendment, ADR README index
  • 03-runtime/02-agent-runtime.md §5f catalog paragraph (en + zh)
  • 04-ux/06-settings-ia.md Built-in group note (en + zh)
  • 06-delivery/04-e2e-test-plan.md E2E-1175 journey

Verification (Windows 11, Node 24, Pi 1.0.1 baseline = current main)

  • agent-runtime vitest subagent-definitions + subagent: 65/65 pass (25 new override cases: merge order, unknown-name diagnostic, user-document precedence, disabled-builtin interplay, re-read per launch)
  • desktop node:test subagent-builtin-overrides.test.mjs: pass (session-launch wiring reads <data>/subagent-overrides)
  • biome check on all six touched source files: pass
  • tsc --noEmit agent-runtime + desktop: pass

App version: main @ c79b6ca
OS: Windows 11 26220.9587

User-authored ~/.agents/subagents/*.md files that share a builtin definition id now replace that builtin instead of being appended as duplicates. The registry resolves user overrides first, keeps builtin entries otherwise, and session launch re-reads the directory per launch.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant