cleveragents-core/docs/autonomy.md

Autonomy Hardening

Milestone: v3.5.0 — Autonomy Hardening

CleverAgents v3.5.0 introduces comprehensive autonomy hardening, enabling the system to autonomously execute large-scale tasks using hierarchical plan decomposition, parallel execution, and validation-gated apply.

---

Overview

Autonomy hardening provides the infrastructure for safe, scalable autonomous task execution:

• Hierarchical decomposition — Plans decompose into 4+ levels of subplans
• Parallel execution — 10+ concurrent subplans execute simultaneously
• Guard enforcement — Denylist, budget caps, and tool call limits protect against runaway execution
• Automation profiles — Configurable precedence (plan > action > global) controls autonomy level
• A2A protocol — Agent-to-Agent facade enables session and plan lifecycle operations via CLI
• Event queue — Publish/subscribe system coordinates asynchronous agent communication

Note on Server Stubs: Server stubs previously scoped to this milestone have been moved to M9 (v3.8.0) following the ACP to A2A protocol adoption (ADR-047) and server architecture redesign (ADR-048). TUI features were moved to M8 (v3.7.0).

---

A2A Protocol (Agent-to-Agent)

The A2A (Agent-to-Agent) protocol provides a standardized facade for session and plan lifecycle operations.

Overview

A2A replaces the earlier ACP (Agent Communication Protocol) following ADR-047. It provides:

• Standardized session management across agent boundaries
• Plan lifecycle operations (create, start, execute, apply, correct)
• Event-driven communication via publish/subscribe
• Type-safe message schemas

A2A Facade CLI

The A2A facade exposes session and plan lifecycle operations via the agents CLI:

# Start an A2A session
agents session start --profile semi-auto

# List active sessions
agents session list

# Execute a plan via A2A facade
agents plan execute PLAN_ID --session SESSION_ID

# Subscribe to plan events
agents events subscribe --plan PLAN_ID

Session Lifecycle

CREATE --> ACTIVE --> SUSPENDED --> TERMINATED
              |
              v
           ERRORED

Sessions are created with an automation profile that governs the autonomy level for all plans within the session.

References

• ADR-026: Agent-to-Agent Protocol (A2A)
• ADR-047: A2A Standard Adoption

---

Event Queue

The event queue provides asynchronous publish/subscribe communication between agents and plan lifecycle components.

Architecture

Publisher                Event Queue              Subscriber
   |                         |                        |
   |-- publish(event) -----> |                        |
   |                         |-- deliver(event) ----> |
   |                         |                        |

Event Types

Event	Description
PLAN_CREATED	A new plan was created
STRATEGIZE_STARTED	Strategy phase began
STRATEGIZE_COMPLETE	Strategy phase completed
EXECUTE_STARTED	Execute phase began
EXECUTE_COMPLETE	Execute phase completed
APPLY_STARTED	Apply phase began
APPLY_COMPLETE	Apply phase completed
CORRECTION_APPLIED	A decision correction was applied
INVARIANT_VIOLATED	An invariant violation was detected
SUBPLAN_STARTED	A subplan began execution
SUBPLAN_COMPLETE	A subplan completed
SUBPLAN_FAILED	A subplan failed
GUARD_TRIGGERED	A guard condition was triggered

Subscribe to Events

# Subscribe to all events for a plan
agents events subscribe --plan PLAN_ID

# Subscribe to specific event types
agents events subscribe --plan PLAN_ID --type SUBPLAN_COMPLETE,SUBPLAN_FAILED

# Subscribe with timeout
agents events subscribe --plan PLAN_ID --timeout 300

Publish Custom Events

# Publish a custom event
agents events publish --plan PLAN_ID --type CUSTOM --data '{"key": "value"}'

---

Guard Enforcement

Guards protect against runaway autonomous execution by enforcing configurable limits.

Guard Types

Denylist Guard

Prevents execution of specific tools, commands, or operations:

[guards.denylist]
tools = ["shell_exec", "file_delete"]
commands = ["rm -rf", "sudo", "chmod 777"]
file_patterns = ["/etc/**", "/sys/**", "~/.ssh/**"]

Budget Cap Guard

Limits resource consumption during autonomous execution:

[guards.budget]
max_llm_tokens = 1000000        # 1M tokens per plan
max_llm_cost_usd = 10.00        # $10 per plan
max_wall_time_seconds = 3600    # 1 hour per plan
max_file_writes = 1000          # 1000 file writes per plan

Tool Call Limit Guard

Limits the number of tool calls during execution:

[guards.tool_limits]
max_tool_calls_per_subplan = 100
max_tool_calls_per_plan = 10000
max_consecutive_failures = 5

Guard Enforcement Behavior

When a guard is triggered:

1. The current subplan is halted
2. A GUARD_TRIGGERED event is published
3. The plan transitions to ERRORED state
4. A detailed guard violation report is generated

Guard Configuration Precedence

Guards can be configured at multiple levels, with more specific configurations taking precedence:

Tool-level > Subplan-level > Plan-level > Global

---

Automation Profiles

Automation profiles control the level of autonomy during plan execution.

Built-in Profiles

Profile	Description	Human Approval Required
manual	All decisions require human approval	Every decision
semi-auto	High-risk decisions require approval	Destructive operations
auto	Fully autonomous execution	None (guards only)
supervised	Periodic checkpoints for human review	At checkpoints

Profile Precedence

Automation profiles are resolved with the following precedence (highest to lowest):

1. Plan-level — Set via agents plan create --profile PROFILE
2. Action-level — Set via agents action create --profile PROFILE
3. Global — Set in .cleveragents/config.toml under [automation]

# Global default
[automation]
default_profile = "semi-auto"

# Plan-level override (highest precedence)
agents plan create --profile auto "Port the Firefox codebase to Rust"

Custom Profiles

Custom profiles can be defined in .cleveragents/profiles/:

# .cleveragents/profiles/strict.toml
[profile]
name = "strict"
description = "Strict profile for sensitive codebases"
base = "semi-auto"

[profile.overrides]
require_approval_for = ["file_write", "git_commit", "shell_exec"]
max_consecutive_auto_decisions = 3

Profile Resolution

The _resolve_profile_for_plan function in PlanLifecycleService resolves the effective profile for a plan. If the plan's configured profile name is not a known built-in profile, a ValidationError is raised with an actionable error message listing available profiles.

---

Hierarchical Plan Decomposition

CleverAgents v3.5.0 supports hierarchical plan decomposition with 4+ levels of subplans.

Decomposition Model

Plan (Level 0)
  |
  +-- Subplan A (Level 1)
  |     |
  |     +-- Subplan A.1 (Level 2)
  |     |     |
  |     |     +-- Subplan A.1.1 (Level 3)
  |     |     |     |
  |     |     |     +-- Subplan A.1.1.1 (Level 4)
  |     |     |
  |     |     +-- Subplan A.1.2 (Level 3)
  |     |
  |     +-- Subplan A.2 (Level 2)
  |
  +-- Subplan B (Level 1)
        |
        +-- Subplan B.1 (Level 2)

Decomposition Strategy

The strategy actor decomposes plans based on:

1. Dependency analysis — Identifies independent work units that can execute in parallel
2. Complexity estimation — Estimates effort for each subplan to balance load
3. Risk assessment — Groups high-risk operations for sequential execution
4. Resource constraints — Respects available compute and memory limits

Decision Correction with Subtree Recomputation

When a decision correction is applied, only the affected subtree is recomputed:

Plan
  |
  +-- Subplan A (complete)
  |
  +-- Subplan B (correction applied here)
  |     |
  |     +-- Subplan B.1 (RECOMPUTED)
  |     |
  |     +-- Subplan B.2 (RECOMPUTED)
  |
  +-- Subplan C (unaffected, not recomputed)

This selective recomputation minimizes wasted work when corrections are needed.

---

Parallel Execution

CleverAgents v3.5.0 scales parallel execution to 10+ concurrent subplans.

Execution Model

SubplanExecutionService
  |
  +-- ThreadPoolExecutor (max_workers=N)
        |
        +-- Worker 1: Subplan A.1
        +-- Worker 2: Subplan A.2
        +-- Worker 3: Subplan B.1
        +-- Worker 4: Subplan B.2
        +-- Worker 5: Subplan C.1
        ...
        +-- Worker N: Subplan X.Y

Fail-Fast Cancellation

When fail_fast=True and a subplan fails:

1. The stop_flag is set
2. Queued subplans are cancelled before starting
3. In-flight subplans that complete after stop_flag is set are overridden to CANCELLED
4. The merge output excludes cancelled subplan results

Parallel Execution Configuration

[execution]
max_parallel_subplans = 10      # Maximum concurrent subplans
fail_fast = true                 # Cancel remaining subplans on first failure
subplan_timeout_seconds = 600   # 10 minutes per subplan

Monitoring Parallel Execution

# Watch parallel execution in real-time
agents plan tree PLAN_ID --watch

# View execution metrics
agents plan show PLAN_ID --format json | jq '.execution_metrics'

---

Large-Scale Autonomous Task Execution

CleverAgents v3.5.0 is validated against realistic large-scale porting tasks.

Acceptance Criteria

The following acceptance criteria were validated for v3.5.0:

• A2A facade session and plan lifecycle operations functional via CLI
• Event queue publish/subscribe operational
• Guard enforcement works (denylist, budget caps, tool call limits)
• Automation profile resolution precedence correct (plan > action > global)
• Full autonomy acceptance flow with hierarchical decomposition (4+ levels)
• Parallel execution scales to 10+ concurrent subplans
• A realistic porting task completes autonomously
• nox passes with coverage >= 97% including large-project suites

Example: Autonomous Codebase Porting

# Create a plan for a large-scale porting task
agents plan create --profile auto \
  "Port the Firefox rendering engine from C++ to Rust, \
   maintaining all existing test coverage and API compatibility"

# Link the source project
agents plan link PLAN_ID --resource firefox-source

# Execute autonomously
agents plan execute PLAN_ID

# Monitor progress
agents plan tree PLAN_ID --watch

Performance at Scale

Metric	v3.4.0	v3.5.0
Max parallel subplans	4	10+
Max decomposition depth	2	4+
Decision correction scope	Full recompute	Subtree only
Large project support	10K files	50K+ files

---

Troubleshooting

Guard Violations

If a guard is triggered unexpectedly:

1. Check the guard violation report: agents plan show PLAN_ID --format json | jq '.guard_violations'
2. Review guard configuration: agents config show guards
3. Adjust guard limits if appropriate: agents config set guards.budget.max_llm_tokens 2000000

Automation Profile Errors

If you see ValidationError: unknown automation profile:

• This was fixed in v3.5.0 (automation profile silent fallback fix)
• Ensure you are using a built-in profile: manual, semi-auto, auto, or supervised
• Custom profiles must be defined in .cleveragents/profiles/

Parallel Execution Failures

If parallel subplans are not being cancelled on failure:

• This was fixed in v3.5.0 (SubplanExecutionService fail_fast cancellation fix)
• Ensure you are running v3.5.0 or later
• Check fail_fast configuration: agents config show execution.fail_fast

---

See also: A2A Protocol API Reference | Actor System | ADR-047: A2A Standard Adoption