Plan IR

An agent plan is a typed, validated, executable description of what the agent will do. The plan IR is a closed discriminated union of 60+ operation kinds — every kind composes existing Vadyl typed ASTs. There is no ExecuteShellCommand, no ExecuteRawSql, no InvokeProviderSdkDirectly. That's by design (anti-pattern #51).

Operation categories

• Entity — read, create, update, delete, link, unlink, search.
• Schema — propose entity, propose field, propose relation, propose index.
• Branching — create branch, commit, sandbox, propose, merge, deploy.
• Automation — define automation, trigger run, register effect.
• Model — chat completion, embeddings, classification — all routed through capability-aware adapters.
• Memory — recall, supersede, namespace mutate.
• Connection — invoke a governed connection operation.
• Source authoring — propose source asset edit (handler, workflow, etc).
• Workflow — start, signal, query, await.
• Federation — request, grant, revoke cross-project access.
• Distribution — invalidate, signed-URL, drift-check.
• Analytics — execute report, materialize metric.
• Sub-agent spawn — start a sub-agent with narrowed grants.
• HITL — request human approval / clarification.
• Control flow — branch, loop, race, parallel.

13-stage validation

Every plan runs through 13 validation stages before any step executes. Failures fail closed:

1. Structural — well-formed plan IR.
2. PCG references — all referenced resources exist in the Plane Capability Graph.
3. Capability declarations — every operation is declared and granted.
4. Access enforcement — preview every operation against the access model.
5. DAG cycle — no cycles in the dependency graph.
6. Budget bounds — token + tool-call budgets are within limits.
7. Coherence — operations don't reference resources of incompatible kinds.
8. Protection — protected branches, frozen environments, production gates.
9. Schema compatibility — schema operations match the current entity model.
10. Federation — cross-project ops have active contracts.
11. Quotas — projected usage doesn't breach quotas.
12. Signatures — required approvals are in place.
13. Risk rollup — compute aggregate risk score.

Risk rollup is MAX

Plan-level risk is the maximum of step risks — never the average, never the median, never the minimum. A single high-risk step makes the entire plan high-risk. Cannot understate. Pinned byAgentRuntimeServicesBehavioralTests.Plan_RiskRollup_IsMaxOfSteps.

Risk-driven gating

approval: agent.approval.byRisk({
  low:    "auto",
  medium: "auto",
  high:   "humanInTheLoop",
  critical: "blocked",
}),

Plans above your project's risk threshold pause for explicit human approval before execution. The pause is durable — the plan survives restart and resumes when approved.

Inspecting a plan

vadyl agents runs show <runId>
# Output includes:
#   plan.steps:  [...]
#   plan.risks:  [low, medium, low, high, ...]
#   plan.maxRisk: high
#   plan.approval: humanInTheLoop
#   plan.diagnostics: [...]
vadyl explain agent-plan <runId>   # canonical reasoning trace