[Feature]: Provider-neutral multi-agent research orchestration

[bobo-xxx]

Preflight checklist

• I searched existing issues and discussions and this hasn't been proposed yet.

What problem does this solve?

Open Science already has most of the primitives needed for an effective research orchestrator:

• pluggable ACP backends for Claude Code, Codex, and OpenCode;
• durable projects and sessions;
• per-session permission profiles;
• model and reasoning-effort configuration;
• persistent Python, R, and REPL kernels;
• managed artifacts and previews;
• scientific skills and connectors;
• a clean-context reviewer with a bounded correction loop;
• headless, browser, CLI, and SDK entry points.

What is missing is a provider-neutral coordinator above those primitives. Today, users can run multiple independent sessions, but one session cannot safely divide a scientific task into isolated tracks, supervise those tracks, collect structured results, and preserve the relationship between the resulting work.

Backend-native subagents are not a sufficient abstraction because their availability, lifecycle semantics, tool permissions, persistence, and result formats vary by framework. Orchestration should remain stable when the user switches from Claude Code to Codex or OpenCode.

This feature also advances capabilities already identified in the roadmap: multi-agent fan-out, per-agent routing, artifact provenance, reproducible environments, and asynchronous research tasks.

Proposed solution

Add an application-owned orchestration layer that lets one Open Science session coordinate isolated child agents across Claude Code, Codex, and OpenCode backends.

The orchestrator should be implemented in the Open Science main process and exposed to agents through a dedicated MCP tool surface. It must not depend on a framework-specific subagent feature. Prompts should explain when and how to delegate, while application code enforces child lifecycle, isolation, permissions, budgets, persistence, and result delivery.

Deliver the capability in two stages:

1. Core multi-agent runtime: durable child sessions, parallel delegation, supervision, artifact handoff, permissions, model/profile selection, and recovery.
2. Scientific workflow orchestration: approval-gated plans, desired outputs, parallel plan tracks, progress claims, nested delegation, review integration, provenance, and context boundaries.

Goals

• Provide the same orchestration semantics on every supported ACP backend.
• Allow genuinely independent research tracks to run concurrently.
• Give each child a fresh context and isolated working directory.
• Pass only explicit task context to a child, never the parent's entire transcript by default.
• Support child-specific agent profile, provider/model, and reasoning effort.
• Make file handoff explicit through managed artifact references.
• Keep permission decisions human-controlled and auditable.
• Persist the session tree and recover useful state after application restart or backend failure.
• Support structured child outputs as well as ordinary prose.
• Make child activity, status, costs, artifacts, and failures inspectable in the UI.
• Build a foundation for approval-gated scientific plans and reviewer-driven correction.

Non-goals

• Do not copy another application's proprietary prompts or internal implementation.
• Do not expose backend-native child-agent APIs directly to the renderer or model.
• Do not share mutable kernel memory or a writable working directory between parent and child sessions.
• Do not permit a parent agent to approve a child's permission request on the user's behalf.
• Do not implement unrestricted recursive spawning; delegation depth and fan-out must be bounded.
• Do not require all providers to support the same model identifiers or reasoning-effort levels.
• Do not make a multi-user collaborative editor part of this issue.
• Do not add Slurm or cloud-GPU scheduling as part of the orchestrator; existing compute targets remain an orthogonal execution facility.

Design principles

Application-owned semantics

Open Science owns the orchestration contract. ACP backends execute individual sessions, but they do not define parent-child relationships, budgets, result collection, or plan progress.

Prompts guide; the host enforces

Agent instructions should describe appropriate delegation behavior, but all security- and correctness-critical properties must be enforced in the main process:

• maximum depth and fan-out;
• child ownership and communication topology;
• permission ceilings;
• workspace isolation;
• artifact-reference validation;
• model availability;
• result-schema validation;
• cancellation and timeout behavior;
• durable state transitions.

Explicit context transfer

A new child receives:

• a required task;
• an optional concise context summary;
• explicit artifact references;
• inherited desired outputs when applicable;
• assigned plan steps when applicable;
• an optional structured-output schema.

It does not automatically receive the parent's full transcript, hidden prompts, kernel state, or arbitrary filesystem paths.

Artifact-mediated handoff

Files cross session boundaries through stable managed artifact identifiers. Relative paths and parent-workspace absolute paths are not valid handoff mechanisms.

Human-controlled permissions

A child's effective permission profile may be equal to or narrower than its parent's profile. Escalation beyond the parent ceiling requires an explicit user decision. A parked child remains parked until the user responds.

Architecture

Renderer / Web UI / CLI / SDK
              │
              ▼
      Orchestrator IPC/API
              │
              ▼
  Main-process OrchestratorService
    ├── SessionTreeRepository
    ├── DelegationBudgetPolicy
    ├── ChildContextBuilder
    ├── ArtifactHandoffResolver
    ├── PermissionCeilingPolicy
    ├── ChildResultRepository
    └── CompletionNotificationBus
              │
              ▼
       AcpRuntimeCoordinator
       ├── Claude Code runtime
       ├── Codex runtime
       └── OpenCode runtime
              │
              ▼
 Dedicated open-science-orchestrator MCP server
 exposed only to delegation-capable sessions

OrchestratorService

The main-process service is the authoritative lifecycle manager. It creates child sessions, records their relationship to the parent, dispatches work through the appropriate ACP runtime, and normalizes terminal results.

The service should not be embedded directly into AcpRuntime. Runtime code remains responsible for one backend connection and its sessions; orchestration composes runtimes through AcpRuntimeCoordinator.

Orchestrator MCP server

Expose a dedicated MCP server only to sessions whose orchestration capability is enabled. Suggested tools:

delegate(request: DelegateRequest | DelegateRequest[], options?: DelegateOptions)
collect(children: ChildHandle[], options?: CollectOptions)
children()
stop_child(children: ChildHandle | ChildHandle[], reason?: string)
send_message(target: ChildHandle | "parent", message: string, kind?: MessageKind)
delegation_stats()

The MCP adapter performs schema validation and calls OrchestratorService. It contains no lifecycle logic of its own.

Session tree

Extend persisted sessions with optional orchestration metadata:

type SessionOrchestrationMetadata = {
  rootSessionId: string
  parentSessionId?: string
  depth: number
  delegationName?: string
  delegatedByMessageId?: string
  taskPreview?: string
  childState?: ChildLifecycleState
  requestedProfile?: string
  effectivePermissionProfile?: PermissionProfileId
  pinnedProviderId?: string
  pinnedModel?: string
  pinnedReasoningEffort?: string
  outputSchema?: JsonSchema
  planClaim?: PlanDelegationClaim
}

Recommended child lifecycle:

created
  → dispatching
  → running
  → waiting-permission | waiting-user
  → completed | failed | cancelled

Every transition should be idempotent and persisted before broadcasting UI state.

Child working directory

Create a dedicated child workspace under application-managed session storage. Parent and child workspaces must not be the same directory.

Child sessions may read:

• artifacts explicitly included in the task;
• project files allowed by the existing project/file policy;
• connector results obtained through their own permitted calls.

They may not assume access to unsaved parent working files. The orchestrator should reject unresolved artifact identifiers before creating the child.

Context construction

The initial child prompt should be assembled from typed fields rather than concatenated ad hoc throughout the runtime:

type DelegateRequest = {
  task: string
  name?: string
  contextSummary?: string
  agentProfile?: string
  providerId?: string
  model?: string
  reasoningEffort?: string
  artifactIds?: string[]
  outputSchema?: JsonSchema
}

The ChildContextBuilder should add application-owned sections for:

• task and context summary;
• desired final outputs;
• assigned plan steps;
• artifact reference instructions;
• structured-output submission instructions;
• parent-contact and permission semantics.

Framework-specific prompt transport remains the responsibility of each framework adapter.

Model and backend selection

A child may:

1. explicitly pin a configured provider/model compatible with an installed backend;
2. explicitly select an agent profile whose backend policy resolves the provider/model;
3. inherit the parent's configured subagent default;
4. fall back to the parent's active backend/model when no subagent default exists.

Resolution must happen before child creation. An unavailable required model fails visibly; it must not silently run a different model.

Permission policy

Calculate the effective child profile as an intersection of:

• parent's effective permission ceiling;
• requested child profile;
• connector/tool policies;
• project and compute-host restrictions.

A child request that needs user action transitions to a waiting state and presents the existing approval UI in the originating project/session context. Parent-agent messages cannot approve the request. Sending an informational message to a parked child must not be treated as user authorization.

Results

Normalize terminal child output:

type ChildResult = {
  childSessionId: string
  name?: string
  status: "completed" | "failed" | "cancelled" | "running"
  response?: string
  structuredOutput?: JsonValue
  structuredOutputSatisfied?: boolean
  artifactIds?: string[]
  error?: string
  usage?: UsageSummary
}

If an output schema is provided, validate the submitted object in the main process. A validation failure should return a bounded correction opportunity to the child rather than accepting malformed data silently.

collect is the sole result channel for non-blocking delegation. Completion notifications may say that a child is ready to collect, but should not inject a large result directly into the coordinator context.

Communication topology

Allow direct parent-child communication only:

• parent → direct child: steer, clarify, or resume;
• child → direct parent: report, ask a question, or request coordination.

Reject sibling, grandparent, arbitrary-session, and cross-project sends. Multi-hop communication must be relayed explicitly by each parent.

Stage 1 — Core multi-agent runtime

Scope

Stage 1 should deliver a complete, useful delegation loop without requiring formal Plan Mode.

Runtime

• Add OrchestratorService and durable parent-child session metadata.
• Add the orchestrator MCP server and typed shared contracts.
• Support single and batch delegation.
• Spawn batch children concurrently with all-or-none preflight validation.
• Support blocking, deadline-bounded, and non-blocking delegation.
• Add bounded collect, children, stop_child, send_message, and delegation_stats operations.
• Support explicit child profile/provider/model/reasoning-effort selection.
• Support optional JSON Schema output contracts.
• Resolve and validate artifact handoffs before dispatch.
• Enforce depth, fan-out, per-task spawn, and global concurrency limits.
• Persist child lifecycle and terminal results.
• Recover or accurately mark children after restart or runtime disconnect.

Permissions and safety

• Apply a permission ceiling inherited from the parent.
• Route child approval requests to the user.
• Prevent parent-agent approval impersonation.
• Isolate child workspaces and built-in tool access.
• Restrict communication to direct parent-child edges.
• Redact credentials from task previews, logs, and UI summaries using existing secret-scrubbing facilities.

UI

• Show child sessions beneath their parent or in an orchestration panel.
• Display name, profile, model, state, elapsed time, and artifact count.
• Allow the user to open a child's complete transcript and activity history.
• Provide user controls to stop a child and answer its approval/input cards.
• Distinguish independent parallel sessions from delegated children.
• Keep large child results out of the parent transcript until explicitly collected.

Headless/API

• Expose child state and results through the existing daemon API, CLI, and SDK.
• Preserve the same authorization and permission behavior as desktop/web.
• Emit lifecycle events suitable for external task monitoring.

Stage 1 acceptance criteria

• A coordinator can dispatch at least three independent child tasks concurrently.
• The same API works with Claude Code, Codex, and OpenCode when each backend is configured.
• Different children can pin different configured models where backend compatibility permits.
• A child receives only its explicit task/context package and authorized artifacts.
• Parent and child writes cannot overwrite one another through a shared working directory.
• A child approval request is shown to the user and cannot be approved by an agent message.
• Non-blocking delegation returns handles immediately; collect later returns normalized results.
• Cancelling one child does not cancel unrelated siblings.
• Restarting the app preserves the session tree and produces an accurate state for every child.
• Structured output is rejected when it does not satisfy the requested schema.
• Spawn/depth/concurrency limits are enforced in the main process and covered by tests.
• The user can inspect every delegated child's transcript, tool activity, artifacts, and terminal status.

Stage 2 — Scientific workflow orchestration

Scope

Stage 2 adds a formal research workflow above the Stage 1 primitives.

Plan Mode

• Add an explicit per-session Plan Mode toggle.
• Require feasibility assessment before generating a plan.
• Ask for clarification only when answers change scope or methodology.
• Ask for desired final deliverables and persist them with the root session.
• Save each plan as a versioned managed artifact.
• Present the plan for user approval before code execution or delegation begins.
• Treat edits as new versions of the same plan and require renewed approval.

Suggested plan shape:

type ResearchPlan = {
  version: 1
  taskSummary: string
  feasibility: {
    confidence: "high" | "medium" | "low"
    rationale: string
  }
  desiredOutputs: string[]
  phases: Array<{
    id: string
    name: string
    delegations: Array<{
      id: string
      name: string
      steps: Array<{
        id: string
        title: string
        description: string
      }>
    }>
  }>
}

Plan execution

• Automatically require multiple delegations in one phase to run through Stage 1 child sessions.
• Use delegation names as stable links between plan tracks and child sessions.
• Claim each track exactly once and persist the claim before dispatch.
• Inject inherited desired outputs and only the assigned steps into each child.
• Require exact step identifiers for progress updates.
• Permit coordinator-executed work only for single-track phases or explicit synthesis/cleanup steps.
• Support configurable nested delegation depth while keeping reviewer sessions as leaves.
• Add a wave boundary after all children in a phase resolve so context compaction cannot split orchestration state mid-wave.

Review and correction

• Allow auto-review to audit coordinator and child turns independently.
• Give reviewers read-only access to the relevant plan claim, transcript, execution log, and artifacts.
• Flag required plan deliverables that are missing.
• Route a bounded correction request to the child that produced the questionable result when possible.
• Preserve reviewer independence: reviewers cannot delegate, mutate artifacts directly, or approve permissions.
• Surface unresolved findings to the coordinator before final synthesis.

Provenance and reproducibility

• Link child-created artifacts to the producing child, plan phase, delegation, step, code cell, input artifacts, environment, and model metadata.
• Add artifact versioning and environment snapshot/export before claiming full reproducibility.
• Export the plan, session tree, model assignments, step states, reviews, and artifact lineage as an orchestration manifest.
• Include deterministic seeds and loadable checkpoints when provided by the execution environment.

Stage 2 acceptance criteria

• Plan Mode prevents execution and delegation until the current plan version is approved.
• Desired outputs persist at the root and are visible to every assigned child.
• A phase with multiple tracks creates one child per track and runs them concurrently.
• Every plan track has exactly one durable owner claim.
• Progress updates map to stable step IDs and survive restart.
• Revising an approved plan creates a new version and pauses execution for approval.
• The coordinator can synthesize results only after required tracks reach a terminal state or the user explicitly accepts partial completion.
• Reviewer findings remain scoped to the producing turn/child and can trigger a bounded correction loop.
• Required but missing deliverables are reported before final completion.
• The exported orchestration manifest is sufficient to identify the plan version, session tree, models, environments, inputs, outputs, and reviews.

Failure handling

Preflight failures

Validate the complete batch before spawning any children:

• request shape;
• model/backend compatibility;
• agent profile existence;
• artifact resolution;
• output schema;
• permission ceiling;
• spawn and depth budget.

If any request fails preflight, spawn none and return indexed validation errors.

Dispatch failures

If failure occurs after child records are created, transition affected children to failed with a normalized error. Do not delete them; the failed record is part of the audit trail.

Runtime disconnects

On reconnect:

• resume a backend session when supported;
• otherwise create a fresh backend session and replay the child's explicit task package, not the parent's transcript;
• mark potentially duplicated side effects and require user attention when idempotency cannot be established.

Parent termination

Closing or cancelling a coordinator should offer the user explicit choices:

• stop all running descendants;
• let descendants finish and notify later;
• cancel only the coordinator while preserving collectable child results.

Never silently orphan children.

Partial completion

Batch results preserve input order and return terminal results alongside running/failed entries. A failed child must not erase successful sibling results.

Testing strategy

Unit tests

• session-tree transition reducer;
• depth/fan-out/concurrency budget policy;
• permission-ceiling intersection;
• context builder and transcript non-leakage;
• artifact-reference validation;
• provider/model compatibility resolution;
• structured-output validation and bounded correction;
• direct-edge communication topology;
• plan validation, versioning, and track claims;
• result normalization across ACP backends.

Integration tests

• parallel children on a fake ACP backend;
• mixed terminal outcomes in one batch;
• child waiting on permission while siblings complete;
• parent cancellation with each user-selected descendant policy;
• restart during running, parked, and completed children;
• model switch between parent and children;
• artifact handoff parent → child → parent;
• non-blocking dispatch followed by bounded collection;
• plan revision and approval invalidation;
• reviewer correction routed to the producing child.

Backend contract tests

Run the same orchestrator conformance suite against Claude Code, Codex, and OpenCode adapters. Framework-specific behavior may differ internally, but the application-facing result and lifecycle contract must remain consistent.

Security tests

• child cannot read an unreferenced parent working file;
• child cannot message a sibling or unrelated session;
• parent-agent text cannot satisfy a child approval card;
• child cannot exceed the parent's permission ceiling;
• unresolved or cross-project artifact IDs are rejected;
• hidden prompts, credentials, and secret values do not enter task previews or event payloads;
• reviewer cannot receive delegation tools.

UI tests

• tree/status rendering for large child sets;
• approval card routing to the correct child;
• stop and inspect actions;
• reload restoration;
• accessible status announcements;
• responsive behavior in desktop and localhost web modes.

Observability

Add structured lifecycle events without logging task contents by default:

orchestrator.child.created
orchestrator.child.dispatched
orchestrator.child.waiting
orchestrator.child.completed
orchestrator.child.failed
orchestrator.child.cancelled
orchestrator.result.collected
orchestrator.plan.approved
orchestrator.plan.revised
orchestrator.review.correction_requested

Useful fields include root session, parent session, child session, depth, provider/backend, model, duration, token usage, artifact count, and normalized failure class. Task text, prompt text, credentials, and raw artifact content should be excluded.

Suggested implementation order

Stage 1

1. Shared contracts and persisted session-tree metadata.
2. OrchestratorService with a fake runtime adapter.
3. Workspace isolation and artifact handoff.
4. Permission ceilings and user-input parking.
5. Orchestrator MCP server.
6. ACP runtime coordinator integration.
7. Renderer tree, supervision controls, and transcript inspection.
8. Headless API/CLI/SDK lifecycle events.
9. Cross-backend conformance and restart-recovery tests.

Stage 2

1. Versioned plan domain model and approval UI.
2. Desired-output persistence and child injection.
3. Track claiming, step progress, and parallel-phase dispatch.
4. Nested delegation and phase boundaries.
5. Reviewer/child correction routing.
6. Artifact provenance, environment snapshots, and orchestration export.
7. End-to-end scientific workflow certification tests.

Documentation requirements

• Explain when delegation improves a task and when a single agent is preferable.
• Document blocking, deadline-bounded, and non-blocking execution.
• Document fresh-context behavior and artifact-based handoff.
• Explain child model/profile selection and compatibility errors.
• Explain permission ceilings and parked approvals.
• Provide examples for desktop, web, CLI, and SDK users.
• Clearly label Stage 1 as durable orchestration, not complete scientific reproducibility.

Definition of done

The feature is complete only when Open Science owns a backend-independent, durable, inspectable orchestration contract. A successful demo on one model or a prompt that asks an agent to imitate delegation is not sufficient.

Stage 1 is done when a coordinator can safely supervise isolated children across all supported ACP backends and recover their state and results.

Stage 2 is done when an approved, versioned scientific plan can drive parallel child tracks through verified artifacts and reviews, with enough provenance to export and audit the complete workflow.

Alternatives considered

Backend-native subagents only

Relying directly on Claude Code, Codex, or OpenCode subagent features would produce different lifecycle, persistence, permission, and result semantics for each backend.

Prompt-only orchestration

Prompts can guide delegation decisions, but they cannot reliably enforce isolation, permission ceilings, budgets, durable state transitions, or recovery.

Manually managed independent sessions

Users can already open several sessions, but manual sessions do not provide a supervised session tree, structured result collection, plan-track ownership, or artifact lineage.

Ship the complete workflow in one stage

A single release would couple the foundational runtime to Plan Mode, review routing, and provenance. The proposed two-stage delivery makes the core delegation contract independently testable and useful.

Additional context

This proposal is deliberately provider-neutral and application-owned. It adapts established coordinator/child-agent patterns to Open Science's ACP architecture without requiring or copying another application's private implementation.

The two stages are intended as separate milestones: Stage 1 remains useful for ordinary single-agent sessions and ad hoc delegation; Stage 2 adds approval-gated scientific planning and reproducibility semantics.

[bobo-xxx]

design in claude sciecne claude-science-multi-agent-prompts.md