cleveragents-core/docs/reference/automation_profiles.md

Automation Profiles

Automation Profiles control how much autonomy the CleverAgents system has at each phase of plan execution. Each profile defines a set of threshold values and safety requirements that determine when the system may proceed automatically versus when it must wait for human approval.

Threshold Semantics

Each threshold field is a float in the range [0.0, 1.0]:

Value	Meaning
0.0	Fully automatic — no human gate required
1.0	Always requires human approval
0.0 < v < 1.0	Probabilistic — the system may proceed if its confidence exceeds the threshold

Threshold Fields

Field	Category	Description
auto_strategize	Phase transition	Gate before entering the strategy phase
auto_execute	Phase transition	Gate before entering the execution phase
auto_apply	Phase transition	Gate before applying changes
auto_decisions_strategize	Decision autonomy	Gate for decisions during strategy
auto_decisions_execute	Decision autonomy	Gate for decisions during execution
auto_validation_fix	Self-repair	Gate for automatic validation fixes
auto_strategy_revision	Self-repair	Gate for automatic strategy revision
auto_reversion_from_apply	Self-repair	Gate for reverting from the apply phase
auto_child_plans	Child plans	Gate for spawning child plans
auto_retry_transient	Retry	Gate for retrying transient failures
auto_checkpoint_restore	Checkpoint	Gate for automatic checkpoint restoration

Safety Fields

Field	Type	Default	Description
require_sandbox	bool	true	Execution must happen in a sandbox
require_checkpoints	bool	true	Checkpoints must be created before writes
allow_unsafe_tools	bool	false	Tools flagged as unsafe may be invoked

Built-in Profiles

Eight profiles ship with every CleverAgents installation:

Flag	manual	review	supervised	cautious	trusted	auto	ci	full-auto
auto_strategize	1.0	0.0	0.0	0.7	0.0	0.0	0.0	0.0
auto_execute	1.0	0.0	1.0	0.7	0.0	0.0	0.0	0.0
auto_apply	1.0	1.0	1.0	1.0	1.0	1.0	0.0	0.0
auto_decisions_strategize	1.0	1.0	0.0	0.6	0.0	0.0	0.0	0.0
auto_decisions_execute	1.0	1.0	1.0	0.8	0.0	0.0	0.0	0.0
auto_validation_fix	1.0	1.0	1.0	0.7	0.0	0.0	0.0	0.0
auto_strategy_revision	1.0	1.0	1.0	0.8	1.0	0.0	0.0	0.0
auto_reversion_from_apply	1.0	1.0	1.0	0.9	1.0	1.0	0.0	0.0
auto_child_plans	1.0	0.0	1.0	0.7	0.0	0.0	0.0	0.0
auto_retry_transient	1.0	0.0	0.0	0.0	0.0	0.0	0.0	0.0
auto_checkpoint_restore	1.0	1.0	1.0	0.6	1.0	0.0	0.0	0.0
require_sandbox	true	true	true	true	true	true	true	false
require_checkpoints	true	true	true	true	true	true	true	false
allow_unsafe_tools	false	false	false	false	false	false	false	true

Profile Descriptions

• manual — Human approves every action. Maximum safety, minimum autonomy.
• review — Strategy and execution proceed automatically; human reviews before apply. Good default for development.
• supervised — Human reviews strategy and execution decisions. Strategy creation itself is automatic.
• cautious — Probabilistic gates on most actions. The system proceeds when confident, asks when unsure.
• trusted — Automatic for most phases, but human approval required for apply and reversion. Suitable for experienced teams.
• auto — Fully automatic except reversion from apply. Suitable for well-tested pipelines.
• ci — Designed for CI/CD pipelines. All thresholds at 0.0 but sandbox and checkpoints remain required.
• full-auto — No gates, no sandbox, no checkpoints, unsafe tools allowed. Use with extreme caution.

Resolution Precedence

When determining which profile applies to a given plan execution, the system resolves profiles in the following order (highest priority first):

1. Plan-level override — A profile specified directly on the plan.
2. Project-level setting — The default profile configured for the project.
3. Organization-level default — The organization's default profile.
4. System default — Falls back to the review built-in profile.

At each level, the profile may be specified by:

• A built-in name (e.g. cautious)
• A namespaced custom profile (e.g. acme/strict)

Custom Profiles

Custom profiles use a namespace/name naming convention:

name: acme/strict
description: Strict profile for production deployments
schema_version: "1.0"

auto_strategize: 0.9
auto_execute: 0.9
auto_apply: 1.0
auto_decisions_strategize: 0.8
auto_decisions_execute: 0.9
auto_validation_fix: 0.5
auto_strategy_revision: 0.9
auto_reversion_from_apply: 1.0
auto_child_plans: 0.8
auto_retry_transient: 0.3
auto_checkpoint_restore: 0.7

require_sandbox: true
require_checkpoints: true
allow_unsafe_tools: false

See docs/schema/automation_profile.schema.yaml for the full YAML schema and examples/profiles/ for example configurations.

Automation Guards

Guards are optional enforcement hooks attached to a profile that gate tool invocations at runtime. They operate independently of the phase-transition thresholds and provide fine-grained control over tool usage.

Guard Fields

Field	Type	Default	Description
max_tool_calls_per_step	int | None	None	Maximum tool invocations per step before requiring approval
max_total_cost	float | None	None	Budget cap before requiring approval
tool_allowlist	list[str] | None	None	Only these tools can be called automatically
tool_denylist	list[str] | None	None	These tools always require approval
require_approval_for_writes	bool	false	Require human approval for write operations
require_approval_for_apply	bool	false	Require human approval before apply phase

Guard Evaluation Order

When check_guard() is called, guards are evaluated in this order:

1. Denylist — If the tool is on the denylist, it is blocked immediately.
2. Allowlist — If an allowlist is set and the tool is not on it, it is blocked.
3. Max tool calls — If the call count has reached the limit, approval is required.
4. Cost budget — If the cumulative cost has reached the cap, approval is required.
5. Write approval — If the operation is a write and write approval is required.
6. Apply approval — If the tool name is __apply__ and apply approval is required.

If no guard blocks the invocation, it is allowed.

GuardResult

The result of a guard evaluation is a GuardResult with three fields:

• allowed (bool) — Whether the tool invocation may proceed.
• reason (str | None) — Human-readable explanation when blocked.
• requires_approval (bool) — Whether human approval can unblock the invocation.

Example YAML with Guards

name: acme/guarded
description: Profile with guard constraints
schema_version: "1.0"
auto_strategize: 0.7
auto_execute: 0.7
auto_apply: 1.0

guards:
  max_tool_calls_per_step: 10
  max_total_cost: 5.0
  tool_denylist:
    - shell_exec
    - file_delete
  require_approval_for_writes: true
  require_approval_for_apply: true

CLI Commands

The agents automation-profile command group manages automation profiles from the terminal.

automation-profile add

Register a custom profile from a YAML configuration file:

agents automation-profile add --config ./profiles/strict.yaml
agents automation-profile add --config ./profiles/strict.yaml --update
agents automation-profile add --config ./profiles/strict.yaml --format json

Options:

• --config / -c — Path to the YAML configuration file (required).
• --update — Overwrite an existing custom profile instead of raising a conflict error.
• --format / -f — Output format: json, yaml, plain, table, or rich (default: rich).

automation-profile remove

Remove a custom profile by name (built-in profiles cannot be removed):

agents automation-profile remove acme/strict --yes
agents automation-profile remove acme/strict --yes --format json

Options:

• --yes / -y — Skip the interactive confirmation prompt.
• --format / -f — Output format.

automation-profile list

List all profiles with optional filtering:

agents automation-profile list
agents automation-profile list --namespace acme
agents automation-profile list "caut.*"
agents automation-profile list --format json

Options:

• regex (positional) — Optional regex pattern to filter profile names.
• --namespace / -n — Filter by the namespace portion of namespaced names.
• --format / -f — Output format.

automation-profile show

Display full details for a single profile:

agents automation-profile show manual
agents automation-profile show acme/strict --format yaml

Options:

• --format / -f — Output format.

Deprecation: --automation-level

The --automation-level option on plan use and the plan set-automation-level command are deprecated and will be removed in a future release.

Legacy automation levels are mapped to built-in profiles:

Legacy level	Built-in profile
manual	manual
supervised	supervised
auto	auto
full_auto	full-auto

Use --automation-profile <name> instead of --automation-level.