fcbd9a4022
Documents the spawn agent approval evaluation policy by adding a new `docs/spawn-agent-approval-evaluation.md` (48 lines), updating `docs/agents.md` with related guidance, trimming `docs/architecture.md`, and bumping the agent delegation section in `AGENTS.md`. The new evaluation doc captures the FN Fusion-Task-Id: FN-3973
49 lines
3.1 KiB
Markdown
49 lines
3.1 KiB
Markdown
# `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.
|