fusion/docs/spawn-agent-approval-evaluation.md

spawn_agent approval-governance evaluation (FN-3973)

Decision

Keep fn_spawn_agent under the existing generic runtime action-gate category (task_agent_mutation) and do not move it under projectSettings.agentProvisioning.

Current behavior (verified)

• fn_spawn_agent is implemented in TaskExecutor.createSpawnAgentTool() (packages/engine/src/executor.ts).
• Spawned children are created via AgentStore.createAgent() with metadata.type = "spawned" and reportsTo = <parentTaskId>.
• Child worktrees are derived from the parent task worktree, child sessions are started immediately, and children are tracked in executor in-memory maps.
• Parent end/cleanup paths call terminateChildAgents(...); spawned ephemeral agents are terminated/deleted with parent lifecycle teardown.
• Tool-level runtime classification includes fn_spawn_agent in ACTION_GATE_TASK_AGENT_MANAGEMENT_TOOLS, so policy disposition comes from permanent-agent action gate (task_agent_mutation) rather than provisioning policy.

Why not agentProvisioning

agentProvisioning (from FN-3791) is purpose-built for durable fn_agent_create/fn_agent_delete with mailbox approval workflows and deferred execution on /api/approvals/:id/decision. spawn_agent differs materially:

• Persistence: spawned agents are ephemeral runtime workers.
• Ownership: children are task-scoped to a parent run, not independent hires.
• Reversibility: teardown is automatic with parent completion/termination.
• Blast radius: bounded to parent-task worktree lineage and configured spawn limits.

Forcing spawn_agent into durable provisioning policy would conflate two different risk models and create approval UX friction for intentionally short-lived parallelization.

Rejected alternatives

1. Reuse agentProvisioning for spawn — rejected; wrong policy surface for ephemeral lifecycle and would overfit mailbox deferred-provisioning UX.
2. New spawn-specific policy today — rejected for now; no demonstrated gap requiring an additional setting surface.
3. Bypass approval entirely — rejected; current action-gate path already provides configurable allow/block/approval behavior for permanent callers.

Approval UX, pause/resume, and audit implications

• fn_spawn_agent remains governed by runtime action-gate decisions (task_agent_mutation) for permanent agents.
• If configured as require-approval, existing action-gate approval flow applies (request creation, task/agent pause with awaiting-approval, resume on approval decision route).
• This path uses existing approval APIs and mailbox approvals; no new approval endpoint or queue is required.
• No runtime behavior change is required by this decision.

Migration/follow-up impact

• No code migration required.
• Documentation was aligned so future implementers do not route spawn into durable provisioning by default.

Non-goals

• Reworking spawn_agent runtime lifecycle.
• Introducing a new spawnAgentProvisioning settings block.
• Changing current approval infrastructure endpoints or mailbox behavior.