cleveragents-core/docs/subplans.md

Subplans and Checkpoints

CleverAgents supports decomposing complex plans into coordinated subplans and capturing checkpoints of sandbox state for rollback. These features are part of the v3.3.0 (Corrections + Subplans + Checkpoints) milestone.

For detailed API references see:

• reference/subplans.md — Execution modes and merge strategies
• reference/subplan_service.md — Spawn workflow and lifecycle
• reference/checkpointing.md — Checkpoint and rollback

---

Subplans

Overview

A subplan is a child plan spawned from a parent plan during the Strategize phase. Subplans allow a parent plan to decompose work into coordinated child plans, each running in its own sandbox. Results are merged back into the parent plan using a configurable merge strategy.

Subplans are created when the Strategize actor records a subplan_spawn or subplan_parallel_spawn decision. The SubplanService then handles the spawn workflow: validating resource scopes, creating child plan statuses, and returning spawn metadata.

Execution Modes

Mode	Description
sequential	Execute one subplan at a time in order
parallel	Execute concurrently (up to max_parallel, default 5)
dependency_ordered	Respect DAG dependencies via topological sort

Sequential mode stops on the first failure (even without fail_fast).

Parallel mode runs subplans concurrently. When fail_fast is enabled, remaining subplans are cancelled on first failure.

Dependency-ordered mode sorts subplans topologically. Independent subplans within the same wave run concurrently. Circular dependencies raise a ValueError.

Merge Strategies

After subplans complete, their sandbox outputs are merged:

Strategy	Description
git_three_way	Three-way merge via git merge-file
sequential_apply	Apply changes in completion order
fail_on_conflict	Raise MergeConflictError on any conflict
last_wins	Final subplan's output overwrites earlier ones

Configuration

subplan_config:
  execution_mode: parallel        # sequential | parallel | dependency_ordered
  merge_strategy: git_three_way   # git_three_way | sequential_apply | fail_on_conflict | last_wins
  max_parallel: 5                 # 1-50, for parallel mode
  fail_fast: false                # stop all on first failure
  timeout_per_subplan_seconds: ~  # optional per-subplan timeout
  retry_failed: true              # auto-retry failed subplans
  max_retries: 2                  # 0-5, max retry attempts

Failure Handling

• fail_fast: Stop all subplans on first failure (any mode).
• Retry: Retriable errors (TimeoutError, ValidationError, TemporaryResourceError, MergeConflictError) are retried up to max_retries.
• Non-retriable: ConfigurationError, AuthenticationError, MissingResourceError, CircularDependencyError are never retried.

Spawn Validation

Before any child plan is created, the SubplanService validates:

1. All target_resources exist in the available resources set.
2. A merge_strategy is defined on SubplanConfig.
3. In PARALLEL mode, spawn count does not exceed max_parallel.
4. Each entry has a non-empty action_name.
5. Each entry's decision is subplan_spawn or subplan_parallel_spawn.

---

Checkpoints

Overview

A checkpoint is an immutable record of sandbox state at a point in time. Checkpoints allow operators to snapshot the sandbox during plan execution and restore it later — useful for recovering from mistakes, reverting tool side-effects, and supporting the decision-correction revert flow.

Checkpoint Types

Type	When Created
pre_write	Before a write-tool execution
post_step	After a write-tool execution
manual	Explicitly via CheckpointService.create_checkpoint()

Automatic Checkpoint Triggers (v3.8.0+)

The execution engine creates checkpoints automatically on four triggers:

Trigger	When	Component
on_tool_write	Before each write-tool execution	ToolRunner
on_tool_write_complete	After each write-tool execution	ToolRunner
on_subplan_spawn	Before first subplan execution attempt	SubplanExecutionService
on_error	When the Execute phase fails	PlanExecutor

Configure which triggers are active:

[core.checkpoints]
auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]

To disable all automatic checkpoints:

[core.checkpoints]
auto_create_on = []

Retention Policy

By default, up to 50 checkpoints are kept per plan. When auto_prune is enabled (default: true) and the limit is exceeded, the oldest interior checkpoints are removed. The first (earliest) and most recent checkpoints are always preserved.

Field	Default	Range
max_checkpoints	50	1–100
auto_prune	true

Rollback to a Checkpoint

Use agents plan rollback to restore sandbox state to a previously captured checkpoint:

# Rollback with confirmation prompt
agents plan rollback 01HPLAN... 01HCHECKPOINT...

# Rollback without confirmation (for scripts)
agents plan rollback --yes 01HPLAN... 01HCHECKPOINT...

# JSON output
agents plan rollback --yes 01HPLAN... 01HCHECKPOINT... --format json

Guards: Rollback is blocked if:

• The plan has already reached the applied terminal state.
• The sandbox has been cleaned up.

JSON output envelope:

{
  "rollback_summary": {
    "plan_id": "...",
    "from_checkpoint_id": "...",
    "restored_files_count": 3
  },
  "changes_reverted": ["path/to/file1.py", "path/to/file2.py"],
  "impact": {
    "files_affected": 3
  },
  "post_rollback_state": {
    "active_checkpoint": "...",
    "plan_id": "..."
  },
  "timing": {
    "elapsed_seconds": 0.042
  },
  "messages": ["Rollback completed successfully."]
}

Checkpoint Metadata

Each checkpoint stores structured metadata for auditability:

Field	Description
checkpoint_id	Unique ULID
plan_id	The plan that owns this checkpoint
sandbox_ref	Reference to sandbox state (e.g., git commit hash)
decision_id	Optional decision ULID this checkpoint is aligned to
checkpoint_type	pre_write, post_step, or manual
created_at	UTC timestamp
metadata	Audit metadata: reason, source tool, phase

---

Relationship Between Subplans and Checkpoints

Checkpoints and subplans work together in the execution engine:

1. Before the first subplan execution attempt, an on_subplan_spawn checkpoint is automatically created (if the trigger is enabled).
2. This checkpoint can be used to roll back the entire parent plan's sandbox state if subplan execution fails catastrophically.
3. The CorrectionService accepts an optional checkpoint_service parameter as an integration point: once wired, the correction revert flow will delegate sandbox restoration to the checkpoint rollback mechanism.

---

Related References

Document	Description
reference/subplans.md	Execution modes, merge strategies, and service API
reference/subplan_service.md	Spawn workflow, validation, and lifecycle
reference/checkpointing.md	Checkpoint model, rollback, and database schema
reference/decision_correction.md	Correction subsystem integration
adr/ADR-015-sandbox-and-checkpoint.md	Architecture decision record
cli.md	CLI quick reference for all v3.2.0 and v3.3.0 commands

---

Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor