[alexandre-vl]

Part of #1003 (Claude Code only).

Settings → Providers gets a Native subagents switch for Claude Code, per device. Off, a top-level chat starts Claude Code without its own subagent tools, and Zeron's MCP server tells the agent to delegate through side chats instead. A side chat keeps its subagents: delegation is one level deep, so it can't create chats of its own. On is the default and nothing changes for it. Codex isn't offered yet (see Known limits).

What changes

• Setting. The device's engine keeps the harnesses switched off in harness-prefs.json (nativeSubagentsOff, crates/engine/src/registry.rs:605, :624) and serves them over two new RPCs, GetNativeSubagents and SetNativeSubagents (crates/engine/src/rpc.rs:2553). Both forward to a remote device like the other provider settings (forwardable, rpc.rs:2037). Only Claude Code is switchable (crates/harness/src/lib.rs:719).
• Which chats. Only a chat without a parent runs side-chats-only (crates/engine/src/sessions.rs:2151). A side chat can't create chats (crates/mcp/src/tools.rs:939-948, and its instructions say so, crates/mcp/src/jsonrpc.rs:52), so it launches with its subagent tools, and its Zeron server adds no delegation rule.
• A run that outruns its row. A run can reach its host before the chat's workspace row, by peer relay for one: the host then claims a row with no parent (crates/engine/src/doc_host.rs:5580-5583), and a side chat created on another device would run its first turn side-chats-only. Until the chat's createChat lands, which records parentChatId either way (a null for none), such a chat keeps its subagents (crates/engine/src/workspace_host.rs:725, crates/doc/src/registry.rs:1335). Once it lands, the switch applies from the next turn.
• Claude Code. A side-chats-only run launches with --disallowedTools=Agent,Task,Workflow (crates/harness/src/claude/mod.rs:374). A bare tool name "removes the matching tools from Claude's context" (CLI reference), so the model never calls them. Denying calls at run time instead would leave each refused call running forever (claude: rejected Agent call shows as a running subagent forever #893). The model calls the spawn tool Agent, while 2.1.310's init frame still lists it under its former name, Task; either name alone removes it.
• Workflow. Claude Code's Workflow tool runs agents of its own (Feature request: show Claude Code Workflow runs and their agents live #804), and [Feature]: Provider setting to turn off native subagents (Claude Code, Codex) and delegate through side chats #1003's Agent,Task leaves it in place. [Feature]: Provider setting to turn off native subagents (Claude Code, Codex) and delegate through side chats #1003 suggested a second switch for it. Its agents are native subagents too, the ones Off replaces with side chats, so the same switch removes it.
• Agent guidance. The switch rides the run's Zeron MCP server as ZERON_SIDE_CHATS_ONLY=1 (docs/mcp.md:25-30). The drivers read it from the request. The server reads it once at start, with the chat and device ids (crates/mcp/src/zeron.rs:53), and adds one sentence to its initialize instructions: delegate with create_chats where you would start a subagent (crates/mcp/src/jsonrpc.rs:65-71, :190). An engine that serves no IPC port stamps no Zeron server, so its runs keep their subagents (crates/engine/src/sessions.rs:2177, noted at the run's flag, :199-203).
• When it applies. A session parked between turns that started the other way is replaced before its next turn, like one whose CLI was updated in place, with the same guards: never during a turn, never while it holds background work (crates/engine/src/sessions.rs:1200). So each chat picks the change up at its next turn once its background work is done, as the row now says (crates/ui/src/settings/delegation.rs:13). The check asks dispatch's question, so a parked side chat stays warm. The startup-crash retry now takes the request before the MCP stamp, so its own dispatch stamps it with the setting of its time (sessions.rs:3436).
• UI. An expanded Claude Code row gets a Delegation section with the switch. The switch moves at once. While the device answers, another flip waits, as in commit credit (delegation.rs:98, crates/ui/src/settings/worktrees.rs:199): the server runs each request in its own task (crates/rpc/src/server.rs:49), so a second one could land first. A refused change shows the device's error and reloads. A device that can't answer keeps the section, its switch inert at the default, with the reason as its line. An engine that predates the RPCs gets "Update Zeron on the selected device to change this.", commit credit's wording (worktrees.rs:173-174), and any other error shows as is (delegation.rs:18, :120). A Cloud target hides the section: its machines use the defaults (delegation.rs:35).
• CI. scripts/ci/test-core.sh:27 now runs the engine's side_chats tests, right after restart_resume; no CI job ran them. Fork: settle the running subagent chips a fork copies #1045 adds the same change, so the two merge in either order.

Testing

• macOS 27.0, rustc 1.99.0, cargo test --locked: -p zeron-engine --lib --test side_chats --test restart_resume --test e2e gives 631 passed (5 ignored), 7, 13 (1 ignored) and 29 (2 ignored). -p zeron-harness --lib --test claude --test codex: 445, 35 (3 ignored) and 46 (4 ignored). -p zeron-mcp --lib: 36. -p zeron-ui --lib -- --test-threads=1 settings::: 171.
• cargo check --locked --workspace --all-targets is clean, examples and every test target included. Of the targets the suites above skip, CI's voice job runs two: -p zeron-engine --test device_routing gives 11 passed, -p zeron-rpc --test device_room 13 (1 ignored).
• New tests, each failing with its fix reverted:
  • a_side_chat_keeps_its_subagent_tools_when_native_subagents_are_off (crates/engine/tests/side_chats.rs:892): the real Claude driver on the fake CLI, switch off. A top-level chat launches with Bash only and a side-chats-only server; a side chat with Bash, Task and Workflow, and a server without the rule; so does a chat whose row its run claimed. It fails at side_chats.rs:992 without the parent check (left: [(["Bash"], "side chats only"), (["Bash"], "side chats only"), (["Bash"], "side chats only")]), without the unknown-parent check (left: [(["Bash"], "side chats only"), (["Bash", "Task", "Workflow"], "native subagents"), (["Bash"], "side chats only")]), and with [Feature]: Provider setting to turn off native subagents (Claude Code, Codex) and delegate through side chats #1003's Agent,Task (left: [(["Bash", "Task", "Workflow"], "side chats only"), …]).
  • a_parked_side_chat_stays_warm_when_native_subagents_switch (crates/engine/tests/restart_resume.rs:703): with a replacement check that ignores the parent, the side chat's warm child is replaced (restart_resume.rs:754, left: 2, right: 1).
  • switched_native_subagents_replace_the_parked_session (restart_resume.rs:649): the same setting keeps the warm child; a switched one starts a new child whose Zeron server is side-chats-only.
  • a_side_chats_only_run_launches_without_subagent_tools (crates/harness/tests/claude.rs:228): the fake CLI lists Bash, Task and Workflow, then only Bash under the flag. With [Feature]: Provider setting to turn off native subagents (Claude Code, Codex) and delegate through side chats #1003's Agent,Task it fails at claude.rs:257 (left: [["Bash", "Task", "Workflow"], ["Bash", "Task", "Workflow"]]).
  • a_side_chats_only_thread_starts_without_agent_tools (crates/harness/tests/codex.rs:2142): the Codex driver's thread/start carries the three keys only for a side-chats-only server.
  • side_chats_only_instructions_add_the_delegation_rule (crates/mcp/src/jsonrpc.rs:266).
  • native_subagents_switch_off_per_harness_and_persist (crates/engine/src/registry.rs:1460): only Claude Code is switchable, Codex is refused, and the choice persists. With Codex back in the gate it fails at registry.rs:1468 (left: [ClaudeCode, Codex]).
  • native_subagents_show_for_switchable_agents_and_switch_at_once (crates/ui/src/settings/delegation.rs:226): without the in-flight guard, a flip during a switch goes through (delegation.rs:255, assertion failed: page.native_subagents.ready().unwrap().off.is_empty()).
  • native_subagents_say_why_a_device_cannot_switch (delegation.rs:264): it fails at :266 without the UnknownMethod wording (left: "unknown method: GetNativeSubagents"), at :281 when an error hides the row (left: None), and at :285 with Codex back in the gate (left: Some((true, false, "Update Zeron on the selected device to change this."))).
• Changed tests:
  • title_run_preserves_read_only_and_replaces_coding_instructions (crates/harness/tests/codex.rs:1621): the fake Codex now checks the three agent keys in the title run's config, which now comes from the shared AGENT_TOOLS list (crates/harness/src/codex/mod.rs:128, :1325). Without them it fails at codex.rs:1643 (error: Some("title restriction missing")).
  • old_harness_preferences_default_to_automatic_titles (crates/engine/src/registry.rs:1555): one assert added, an older harness-prefs.json turns nothing off.
  • initialize_and_list_over_jsonrpc (crates/mcp/src/tools.rs:2939): initialize carries the delegation rule exactly when the server's origin is side-chats-only. With initialize ignoring the origin it fails at tools.rs:2957 (left: false, right: true).
• Live, Claude Code 2.1.310 with Haiku, stream-json in bypass mode, the init frame's tools under each --disallowedTools value. None: Task, ListAgents, SendMessage, TaskStop, Workflow. Agent,Task,Workflow: ListAgents, SendMessage, TaskStop. Agent,Task, Agent or Task alone: those three and Workflow.
• Live, on a headless engine built from this branch before its last fixes (the Codex gate, the unknown-parent check, the UI guard, the MCP origin), switched over IPC (SetNativeSubagents). Those fixes don't change these steps: the Claude Code flag and env are the same, and each chat's row came before its run.
  • Switch off, a new chat asked for a subagent to run ls. Per ps, its Claude process ran with --disallowedTools=Agent,Task,Workflow, and its Zeron server's env held ZERON_SIDE_CHATS_ONLY=1. Its sessionStarted (journal seq 1) listed none of Agent, Task and Workflow. The agent said its subagent tools were off, called create_chat, and the side chat ran ls.
  • That side chat ran with neither the flag nor the env var. Its sessionStarted listed Task and Workflow, and its server's initialize kept the one-level rule without the delegation rule (the parent's has both).
  • Switch back on, a second turn in the same chat: the engine logged native subagents switched; replacing the parked session, the new process resumed the session without the flag, its sessionStarted (seq 623) listed Task and Workflow, and the agent's Agent call returned pong.
  • A build with [Feature]: Provider setting to turn off native subagents (Claude Code, Codex) and delegate through side chats #1003's Agent,Task and without the parent check, same scenario: switched off, sessionStarted seq 1 lacked Agent and Task but listed Workflow, and its side chat's seq 1 lacked Task.
• Live again for the screenshots, on this branch's final build: the switch clicked off in the offscreen Shell, then the first and third steps. GetNativeSubagents answered {"off": ["claude-code"], "switchable": ["claude-code"]}. The first turn's Claude process had --disallowedTools=Agent,Task,Workflow in all 74 ps samples, and the agent delegated through create_chat. Switched back on over IPC, the engine logged the replacement, the second turn's new process ran without the flag (33 samples), and its Agent call returned pong.
• Rebased onto v0.2.124 (c04e3749) after these runs, with no conflict. Merged there with the other five PRs of this series (Claude subagents: count and open only this chat's spawns #1041, Claude subagents: forward a foreground subagent's text and thinking #1042, Claude subagents: give a typed /skill's fork a chip and a tab #1043, Claude subagents: fill a typed fork's tab while the CLI holds it #1044, Fork: settle the running subagent chips a fork copies #1045), it passes every suite above again, plus the rest of CI's selection, sync's mock-server tests, zeron-mcp and the UI's settings:: tests, each executable checked to be built from that merge. The one failure, preview's backgrounded_scrubbed_terminal_and_out_of_tree_servers_stay_attributed, fails the same way on v0.2.124 alone, on this Mac.
  • Live on that merged build, the same steps: switched off, the flag was in all 87 ps samples and the agent delegated through a side chat; switched back on, the parked session was replaced, and the next turn's Agent call returned pong.
• Not run: Codex live (its CLI doesn't start on this Mac); a cross-device run, including one that outruns its row (the local edge can't run here); Windows and Linux; the switch clicked by hand in the packaged app (the UI tests cover the row, and the screenshots' run clicked it in the offscreen Shell).

Known limits

• Codex isn't offered yet: switching it back on wouldn't reach a chat that ran a turn while it was off. Per Codex's source at rust-v0.153.4 (not run): a thread started with agents off records disabled in its session meta (session/session.rs:866), each turn records its mode (session/turn_context.rs:600), and a resume takes the recorded mode unless the config forces one (session/mod.rs:463-479, :692-694, history/src/lib.rs:418-446). The config can only force V2 or disabled (config/mod.rs:1533-1541), and a disabled mode leaves the agent tools out (tools/spec_plan.rs:647-649). The follow-up: when the switch goes back on, start such a chat on a fresh Codex thread with its history replayed, the way a provider switch does, behind a driver capability. The engine would have to record which Codex thread ran with the switch off, since an idle reap or a restart drops the parked session that knows today. The Codex driver already starts a side-chats-only thread without agent tools (crates/harness/src/codex/mod.rs:1342, tested at crates/harness/tests/codex.rs:2142); docs/research/codex-subagents.md:53-72 has the details.
• Side chats are one level deep (crates/mcp/src/tools.rs:939-948), where native subagents nest, and a side chat keeps its provider's own subagents. Each delegation starts a full provider process with a fresh context.
• Off doesn't keep forked skills away from [Bug]: Claude harness: forked skills and nested subagents count in the ● N badge but never show in the lanes card #999 and [Bug]: Claude harness: foreground subagent and forked-skill tabs lose their text and thinking #1000, which Claude subagents: count and open only this chat's spawns #1041 and Claude subagents: forward a foreground subagent's text and thinking #1042 fix. Live, switch off: a context: fork skill still ran as Claude's own forked subagent, its traffic tagged with its Skill call's id, while the two agents it starts became side chats.
• Other features built on Agent run without their workers while it's off: /batch, Explore, Plan. I haven't checked how each of them degrades.
• ListAgents, SendMessage and TaskStop stay listed. None of them starts an agent: the first two also reach your other Claude Code sessions, and TaskStop stops background tasks (tools reference). SendMessage can also resume a subagent by its id, so a session switched off after it ran subagents might still resume one of those; not tried.
• Side chats: move one into the sidebar as its own session #987 (move a side chat into the sidebar) clears the chat's parent, so the switch then applies to it. That matches the one-level rule, since a top-level chat may create chats, and its parked session is replaced before its next turn.
• Text conflicts with open PRs, beyond the ones each already has with main: Settings: choose when idle sessions close #960 (crates/engine/src/registry.rs, rpc.rs, and in crates/rpc/src/lib.rs inside the conflict Settings: choose when idle sessions close #960 already has there), Experimental: edit what the agent remembers, stop one command or subagent, and a system prompt #989 (registry.rs), Side chats: move one into the sidebar as its own session #987 and Session notes: a synced Markdown scratchpad per main chat #965 (crates/engine/tests/side_chats.rs), chat3: transcript plane behind a labs flag (8% of chat2's billed writes, paged history, stored tool outputs) #979 (crates/engine/src/workspace_host.rs: its labs-flag methods go right after WorkspaceHost::chat, where this PR adds parent_unknown, :725). Each is an addition at the same spot as one of this PR's: keep both.
• The engine's CI list is one line (scripts/ci/test-core.sh:27). Claude subagents: give a typed /skill's fork a chip and a tab #1043 adds claude_subagents to it, and Claude: show Workflow runs as subagents with live progress #784 (with Claude: open each Workflow agent's live transcript #785 on top) workflow_progress, so each conflicts with this PR there. Whichever lands second keeps every name.
• Add controls for MCP side-chat delegation and its default model #582 asks for the opposite switch, MCP side chats off. The two could become one three-way Delegation setting later.
• Settings search: find any setting from the sidebar, with ⌘F #1018 (settings search): whichever of the two lands second adds "subagents delegation" to the SettingsSection::Harnesses arm of page_terms.

Screenshots

Offscreen renders of the production Shell (Window::render_to_image), attached to a headless engine, both built from this branch; docs/media/native-subagents-setting/README.md says how they were made. The crops stop above the provider's Accounts section, and the session card's device name is blurred. The media are in their own commit, 63bd38d3, if you'd rather drop them before merging.

Default	Switched off

The live chat's session card: the side chat its first turn delegated to while the switch was off, and the Agent run of its second turn once it was back on.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[alexandre-vl]

CI on bad52c4: every job that runs on this PR has passed on this commit at least once, over four runs.

The latest run's only failure is offline-linux reaching its 45-minute limit while still compiling dependencies; it restored no Rust cache (job). It passed in the three runs before: 34m53s, 41m37s and 8m21s.

The other failures along the way:

• macos-native reaching its 45-minute limit: this PR changes crates/proto, so nearly the whole workspace rebuilds.
• The Windows cursor_shim flake that Cursor shim tests: give a shim's first frame time for node to start #1051 fixes.
• doc_host_delivery's nudge assertion, which fails the same way on main (684becf).

A re-run of the failed job would settle it without running the rest again.

[zeronsh]

Security audit: clean. No new dependencies, build scripts, workflow changes or network hosts. The feature only removes agent tools (--disallowedTools=Agent,Task,Workflow), and the two new RPCs use the existing forwardable provider-settings path. The demo PNGs have no trailing data.

Review: the setting persists in harness-prefs.json and defaults to on. It reaches Claude Code through the run's Zeron MCP server env and the CLI flag. It applies only to top-level chats, including once a claimed row's createChat lands, and a parked session is replaced at its next idle turn. The Delegation row reuses the Completion section's row, switch and theme tokens.

Maintainer changes: rebased onto current main. The only conflict was scripts/ci/test-core.sh, now the union with #1043/#1045. I also added a test, a_claimed_chat_knows_its_parent_once_its_create_lands, for the claimed-row transition.

Local (Linux, rebased head): engine side_chats/restart_resume/claude_subagents/device_routing/e2e, harness lib/claude/codex, mcp, doc, rpc and UI settings:: all pass, and cargo check --all-targets is clean. Clippy has no findings on the PR's lines. 4 engine lib tests fail identically on main because the Cloud machine's env leaks into them.