Middle ground for subagents: shared sandbox with distinct instructions

[aatosolavi]

What problem are you trying to solve?

eve currently forces a binary choice when delegating work:

Kind	Instructions	Sandbox / tools
Built-in agent tool	Always a copy of the parent	Shared live sandbox and tools
Declared subagent	Own instructions.{md,ts}	Isolated by default (own sandbox, tools, connections, etc.)

A common orchestration pattern needs both at once: a specialist role with its own system prompt, working on the same live filesystem as the parent (e.g. parent checks out or writes files, then a reviewer/researcher/coder with a different identity continues in that workspace).

Today:

• Built-in agent shares the workspace but cannot take a specialist system prompt (only the parent’s instructions).
• Declared subagents can have the right prompt, but by default cannot see the parent’s live sandbox.

Workarounds are weak: stuffing role text into message is unreliable and mixes identity with task context; re-declaring sandbox/workspace under every specialist duplicates config and creates separate filesystems.

What already addresses this (partly)

#626 — Allow declared subagents to inherit selected parent capabilities — is the right long-term shape for stable specialists: keep declared isolation by default, and opt into sharing the parent’s live sandbox (and optionally connections) via something like:

export default defineAgent({
  description: "Review this change for security risks.",
  inherit: {
    sandbox: true,
    connections: true,
  },
});

#639 implements that API (inherit.sandbox / inherit.connections) and the runtime plumbing (shared sandbox session, docs, eve info). As of this writing that PR is open but not merged (conflicts / needs a refresh against main).

That path closes the “declared specialist + shared filesystem” half of the gap. It does not by itself give the built-in agent copy a first-class way to override instructions for one-shot roles.

Proposed solution

Prefer completing #626 / #639 as the primary fix for durable specialists.

Optionally, as a complementary escape hatch for ad-hoc roles without a full subagents/<id>/ tree, extend the built-in agent tool input so a call can supply temporary instructions while still sharing sandbox/tools:

{
  message: string;
  outputSchema?: object;
  /** Optional; when set, this copy uses a different system prompt than the parent. */
  instructions?: string;
}

Suggested rules if that path is pursued:

• Default remains today’s behavior (full parent instructions).
• Override applies only to that child session’s prompt assembly; it does not mutate the parent.
• Sandbox, tools, and connections stay shared as they do for the built-in copy today.
• agent stays root-only; nesting rules unchanged.
• Docs should steer durable specialists to declared subagents + inherit (Allow declared subagents to inherit selected parent capabilities #626), and treat instructions on agent as the lightweight one-shot option.

Alternatives considered

• Encode role only in message. Fragile for long or strict identity prompts; confuses task content with system policy.
• Always use declared subagents without sandbox inherit. Forces separate workspaces or re-checkout; parent and child cannot collaborate on the same files in place.
• Only ship Allow declared subagents to inherit selected parent capabilities #626. Sufficient for most product agents; leave one-shot prompt override out unless demand shows up after inherit lands.

Related

• Allow declared subagents to inherit selected parent capabilities #626 — declared subagent capability inheritance (sandbox / connections)
• feat(subagents): support explicit capability inheritance #639 — implementation PR for Allow declared subagents to inherit selected parent capabilities #626
• Expose a code-side API for deterministic subagent orchestration #625 — code-side subagent invocation (orthogonal orchestration concern)