dsh-agent-teams-model-override

A small, fail-closed extension for DeepSeek Harness Agent Teams that adds:

1. Model selection when a teammate is created — spawn_teammate_with_model accepts provider, model, and reasoning_effort; the teammate keeps that route across later turns and cold resume. The roster reports the session's real model instead of the profile default.
2. Real nested teams — a manager can create its own workers with a genuine Session.header.parentSession = manager, share the Lead's task board, delegate work inside its own zone, and interrupt its own workers. Nested transcripts open from the Team panel.
3. Model switching for a live teammate — switch_teammate_model changes the route of an existing teammate on its next request without creating a new member or losing its history.

It is a thin extension of the official Agent Teams bundle. It does not implement a second orchestrator, copy board transitions, or replace the native continuable-subagent lifecycle. When the official spawn_teammate learns these arguments itself, this package can go away.

Status: 1.6.0. 201 tests pass against DSH 0.2.1-rc.2. The creation/model paths are live-verified. The 1.6.0 manager-interrupt and nested-transcript paths are covered by contract tests against the installed runtime; a live UI pass is still pending, so treat those two paths as release-candidate behavior.

---

Requirements

Requirement	Value
DeepSeek Harness	Desktop 0.2.1-rc.2 (tested), 0.2.0-rc.2 also supported
Official bundle	Agent Teams installed and enabled
Node.js	22+ (development only; the installed Host provides its own runtime)
Profile	any; the package is a normal DSH bundle

The plugin checks private runtime seams before installing. If the installed DSH no longer matches the contracts it was written against, the affected component refuses to install and writes the reason to the Host log instead of failing in the middle of a turn.

---

Install

From the DSH Plugin Manager (recommended)

1. Make sure the official Agent Teams bundle is installed and enabled.

2. Open Plugin Manager in Creator Mode and choose Install bundle.

3. Enter the GitHub spec:

   github:funk80rus/dsh-agent-teams-model-override
   

4. Enable dsh-agent-teams-model-override. Three component rows appear in Components; each row has its own toggle:

   Component	What it adds
   agent-teams-model-override	spawn_teammate_with_model, accurate roster model
   agent-teams-manager	spawn_team_worker, zone task delegation, manager interrupt, nested transcripts
   agent-teams-teammate-model	switch_teammate_model for a running teammate

The committed runtime/<hash>/ graph is what the Host loads. A GitHub install does not need a build step.

From the command line

DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
PROFILE="$DSH_HOME/profiles/<profile>"          # e.g. desktop
cd "$PROFILE"

pnpm add github:funk80rus/dsh-agent-teams-model-override

Then enable the bundle through the Plugin Manager UI, or from a DSH session:

plugin_manager { action: "set_bundle", target: "dsh-agent-teams-model-override", enabled: true }

If pnpm refuses a fresh git dependency because of a release-age policy, install it through the Plugin Manager instead, or pass --config.minimumReleaseAge=0 for that one command.

The package is not published to npm and is marked "private": true; GitHub is the distribution channel.

---

Usage

Pick a model for a new teammate

Ask the Host which routes are eligible first:

list_subagent_models({})
list_subagent_models({ provider: "opencode-go" })
list_subagent_models({ provider: "opencode-go", model: "glm-5.3-flash" })

Then create the teammate:

spawn_teammate_with_model({
  name: "reviewer",
  description: "Independent review of the implementation",
  prompt: "Review the implementation and report concrete defects.",
  context: "fresh",
  provider: "opencode-go",
  model: "glm-5.3-flash"
})

• provider and model must be supplied together. reasoning_effort is optional and is validated against the efforts that model actually advertises.
• Omit all three to inherit the delegating agent's route exactly as official spawn_teammate does.
• A route that is unknown or not allowed by the profile's subagent model allowlist is refused with an explicit error; it never silently falls back to the parent model.
• The model choice grants no additional delegation authority. Limits, depth, member slots, and tool permissions are unchanged.

Create a real manager/worker hierarchy

// Lead: create a manager with the normal or model-aware tool
spawn_teammate({ name: "mg-1", description: "Release manager", prompt: "..." })

// mg-1, from its own scope:
spawn_team_worker({ name: "w-1", description: "Worker", prompt: "..." })

// The worker is a teammate in the same team, but its durable parent is mg-1:
// list_agents, the shared task board, send_message and cold resume all see it.

The Lead can also choose the real parent explicitly:

spawn_teammate_with_model({ name: "w-2", ..., manager: "mg-1" })

Assign and track work:

team_task_assign({ subject: "Fix the parser", description: "...", owner: "w-1" })
team_task_list({})
team_task_update({ task_id: "task-7", expected_revision: 2, action: "complete" })
team_hierarchy({})

A manager may change tasks only inside its actual descendant zone (computed from durable parentSession headers, not from declared labels). Outside that zone the call fails with TEAM_TASK_OUT_OF_ZONE; claim is never widened, and the Lead is not affected.

Stop a worker

interrupt_agent({ target: "w-1" })

A manager may interrupt only its own descendants; the Lead may interrupt anyone. The native interrupt operation is still executed as the real Lead after the zone check, so the official semantics are preserved: the current turn stops, pending inbox/activation survive, and the next message starts the worker again. Self-interrupt returns TEAM_INTERRUPT_SELF; an unrelated target returns TEAM_INTERRUPT_OUT_OF_ZONE.

Switch the model of a running teammate

switch_teammate_model({
  target: "w-1",
  provider: "opencode-go",
  model: "qwen3.8-flash"
})

The member keeps its id, name, history, journal entry, and board tasks. Only its next request uses the new route. The official session controller appends the durable model/selection event, so the change survives cold resume. The response says which path was used:

• via: "session-controller" — committed immediately;
• via: "pending" — the teammate was unloaded; the route is applied when it next starts.

target: "lead" changes the Lead's own route. A manager may switch members of its own zone; a leaf teammate without a zone does not get the tool at all.

---

Components and configuration

All three rows are inserted by cordis.patch.yml and select the same immutable graph runtime/<hash>/, so component versions can never drift apart.

- insert:
    - id: agent-teams-model-override
      name: './runtime/<hash>/plugin.js'
      config: { force: false, rosterModel: true }
    - id: agent-teams-manager
      name: './runtime/<hash>/manager-component.js'
      config: { nestedTeams: true }
    - id: agent-teams-teammate-model
      name: './runtime/<hash>/teammate-model.js'
      config: { switchModel: true }

• force — install even when the route seam is missing (not recommended; the component will be unable to deliver a route).
• rosterModel — replace only the model field of roster rows with the session's effective model.
• nestedTeams — enable real nested managers/workers and the zone task/interrupt authority.
• switchModel — register switch_teammate_model.

Disabling a row removes its tools and shadows immediately. Disabling the manager row does not break already-created nested members while another row is still loaded; the read/recovery bridge is reference-counted.

Do not add these rows to the profile's own cordis.patch.yml. A profile-level insert would keep the plugin alive after set_bundle(enabled: false) and make the bundle impossible to disable cleanly. Use only the package's cordis.patch.yml, which the bundle loader applies.

---

How it works

A fuller description is in docs/ARCHITECTURE.md.

• Route injection is per call. The selected route lives in an AsyncLocalStorage store created by one tool call and is consumed exactly once by the first startContinuable / startActivation whose parent is that delegating agent. Nothing global is mutated.
• Nested creation reuses the official admission path. The bridge calls the original roster.spawn as the real Lead (name checks, member limit, journal root, provisioning), then rewrites request.parent to the manager immediately before the native start. The child gets a real parentSession, the manager's catalog, and the shared team journal/board.
• Zones come from actual lineage. Task and interrupt authority is computed from parentSession headers, not from decorative hierarchy records. A manager cannot grant itself authority over another manager's children.
• Nested transcript opening is a read-side repair. The Team panel asks for history with parent = Lead; for a nested worker the durable parent is the manager, so the Host rejects it as subagent/unauthorized. The component wraps only sessionController.page and follow: if the supplied parent is a real ancestor of the actual parent, the address is rewritten to the actual parent; otherwise the request is unchanged and the Host still refuses.
• Model switching uses the official commit path. selectForNextRequest on the session controller appends the durable selection and re-installs route listeners. If that method is unavailable, the tool reports via: "session-append" plus a warning instead of pretending the route changed.
• Delivery is versioned as a graph. npm run build hashes every file in lib/ into runtime/<hash>/; the package exports and the bundle patch always point at one complete graph. The Host never loads editable lib/ files directly.

---

Limitations

These are known, tested limits—not guesses.

1. Private runtime seams. Nested teams depend on the installed Agent Teams/subagent internals (roster.spawnAdmitted, activation registry, delivery symbol, session controller). A future DSH that changes them makes the component fail closed with a reason in the Host log. It is not a promise of forward compatibility.
2. No teammate deletion or renaming. The official roster is append-only. A failed creation still consumes its name and slot. A Lead session has 16 teammate slots (the Lead is separate); context: "fresh" creates a new member, it does not reuse one.
3. No true context clear. /compact in the GUI summarizes history; it does not erase it. The only clean start is a new teammate with context: "fresh". There is no /clear tool for teammates in 1.6.0.
4. A nested worker replies to its manager, not to the Lead. That is the consequence of a real parentSession. Use an explicit send_message({ target: "lead" }) when the worker must answer the Lead.
5. Pending model switches are in memory. If the Host restarts between switch_teammate_model returning via: "pending" and the teammate's next start, repeat the switch.
6. context: "fork" plus a changed route can prevent the provider from reusing the inherited conversation prefix. This is the same trade-off as official subagent forking.
7. Manager authority is zone-scoped, not global. The manager can act only on actual descendants. It cannot claim another member's task, reassign across managers, or act on the Lead. team_hierarchy_set cannot physically reparent an existing session.
8. Two 1.6.0 UI paths still need a live pass. Manager interrupt and Team-panel nested transcript opening are tested against the installed roster and a fake session controller, but the final live UI check is pending (see Status above).

---

Troubleshooting

Symptom	Check
No new tools after enabling	Is the official Agent Teams bundle enabled? Is the package bundle enabled? Did the component log a runtimeSupportReport failure?
TEAM_LEAD_REQUIRED from a manager	The agent-teams-manager row is disabled or failed to install.
TEAM_INTERRUPT_OUT_OF_ZONE	The target is not a real descendant of the caller. Check team_hierarchy.
subagent/unauthorized when opening a nested transcript	Confirm agent-teams-manager is enabled at 1.6.0+; this is the read-side repair.
Model did not change	Look at via and warning in the response. session-append means the official commit path was unavailable.
Install fails in pnpm	Use the Plugin Manager, update Node to 22+, or retry without a release-age policy for the git dependency.
Tools disappeared after a DSH update	The private contracts changed; check the Host log for the fail-closed reason.

---

Development

npm test          # 201 tests; installed-runtime tests skip when DSH is not found
npm run build     # writes lib/ into runtime/<hash>/ and rewrites exports + patch
npm run verify    # build, then the full suite

• DSH_ASAR can point at a non-default app.asar; the test helpers otherwise look for /Applications/DeepSeek Harness.app/Contents/Resources/app.asar.
• Never edit runtime/<hash>/ by hand. It is content-addressed. Change lib/, run npm run build, then commit the new graph together with the updated package.json and cordis.patch.yml.
• The package has no runtime dependencies; tests use Node's built-in test runner.
• Keep local logs, profile snapshots, session ids, and absolute home paths out of commits. .gitignore already excludes .diagnostics/, docs/evidence/, docs/rollback/, and the author's internal notes.

Contributions are welcome; see CONTRIBUTING.md.

---

Privacy and security

The plugin runs inside the local DSH Host with the user's permissions. It makes no network requests of its own, has no telemetry, and does not read credentials or API keys. It reads local session headers and the official services to compute lineage, routes, and history addresses; that data stays on the machine.

It does hook private runtime seams, so treat it as privileged local code: install from a commit you trust, and read SECURITY.md before reporting a vulnerability.

---

License

MIT. See LICENSE. The upstream @deepseek-ai/dsh-* packages are also MIT; this package does not vendor their code.