Spawn Reference

Platform detection (run once at session start):

• create_session tool exists → App mode → sub-sessions for commit-producing work
• runSubagent tool exists → VS Code mode → subagents
• task tool exists → CLI mode → task tool
• None available → work inline (last resort fallback)

Sub-Sessions (Copilot App Mode)

When create_session is available, spawn commit-producing agents as sub-sessions instead of tasks. Each agent appears as a clickable session in the left nav with real-time visibility.

When to use sub-sessions vs task:

• Sub-session (create_session): Agent produces commits, needs worktree isolation, or benefits from persistent session visibility
• Task (task tool): Pure analysis, coordination, read-only research, or quick one-shot work

Sub-session parameters:

• name: "{Name} {verb}ing {noun}" — 40-char max, sentence case (e.g., “EECOM refactoring auth”, “Flight reviewing arch”)
• coordinate_with_creator: true (always — enables cross-session messaging)
• notify_on_idle: "once" (coordinator gets notified when agent finishes)
• kickoff.prompt: The full agent prompt (same as task prompt below)
• kickoff.mode: "autopilot" (agents work autonomously)
• kickoff.model: "{resolved_model}"

Constraints:

• Max depth: 1 — no sub-sub-sessions. If an agent needs to delegate, it uses task tool.
• Concurrency cap: Maximum 4-5 simultaneous sub-sessions. Queue additional spawns.
• Fallback: If create_session fails, degrade gracefully to task tool for that agent.

Sub-session template:

Result collection: When notify_on_idle fires, the coordinator receives the session result via cross-session notification. No polling required.

Task Tool Spawn (CLI Mode)

Standard spawn via task tool — used in CLI, or as fallback when create_session is unavailable:

• agent_type: "general-purpose" (always — this gives agents full tool access)
• mode: "background" (default) or "sync" — use "background" for all parallelizable work; use "sync" only when the result is needed before the next step can proceed
• description: "{Name}: {brief task summary}" (e.g., "Ripley: Design REST API endpoints", "Dallas: Build login form") — this is what appears in the UI, so it MUST carry the agent’s name and what they’re doing
• prompt: The full agent prompt (see below)

⚡ Inline the charter. Before spawning, read the agent’s charter.md (resolve from team root: {team_root}/.squad/agents/{name}/charter.md) and paste its contents directly into the spawn prompt. This eliminates a tool call from the agent’s critical path. The agent still reads its own history.md and decisions.md.

Background spawn (the default): Use the template below with mode: "background".

Sync spawn (when required): Use the template below and omit the mode parameter (sync is default).

VS Code equivalent: Use runSubagent with the prompt content below. Drop agent_type, mode, model, and description parameters. Multiple subagents in one turn run concurrently. Sync is the default on VS Code.

Template for any agent (substitute {Name}, {Role}, {name}, and inline the charter):