# Automation Profiles — Reference

## The 11 Automatable Task Flags

Each flag is a confidence threshold (0.0–1.0). `0.0` = always automatic; `1.0` = always manual.

| Flag | What It Controls |
|------|----------------|
| `decompose_task` | Auto-enter Strategize after `plan use`? |
| `create_tool` | Auto-enter Execute after Strategize completes? |
| `select_tool` | Auto-enter Apply after Execute completes? |
| `edit_code` | Auto-decide during Strategize (strategy actor autonomy)? |
| `execute_command` | Auto-decide during Execute (execution actor autonomy)? |
| `create_file` | Auto-fix failing validations? |
| `delete_content` | Auto-revise strategy when Execute hits constraints (Execute → Strategize reversion)? |
| `access_network` | Auto-revert from Apply `constrained` state to Strategize? |
| `install_dependency` | Auto-spawn and execute child plans? |
| `modify_config` | Auto-retry transient failures (network, timeout, rate-limit)? |
| `approve_plan` | Auto-restore from checkpoint on failure? |

## 8 Built-in Profile Threshold Table

| Flag | `manual` | `review` | `supervised` | `cautious` | `trusted` | `auto` | `ci` | `full-auto` |
|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `decompose_task` | 1.0 | 0.0 | 0.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
| `create_tool` | 1.0 | 0.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
| `select_tool` | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 0.0 | 0.0 |
| `edit_code` | 1.0 | 1.0 | 0.0 | 0.6 | 0.0 | 0.0 | 0.0 | 0.0 |
| `execute_command` | 1.0 | 1.0 | 1.0 | 0.8 | 0.0 | 0.0 | 0.0 | 0.0 |
| `create_file` | 1.0 | 1.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
| `delete_content` | 1.0 | 1.0 | 1.0 | 0.8 | 1.0 | 0.0 | 0.0 | 0.0 |
| `access_network` | 1.0 | 1.0 | 1.0 | 0.9 | 1.0 | 1.0 | 0.0 | 0.0 |
| `install_dependency` | 1.0 | 0.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
| `modify_config` | 1.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 |
| `approve_plan` | 1.0 | 1.0 | 1.0 | 0.6 | 1.0 | 0.0 | 0.0 | 0.0 |
| **Safety: require_sandbox** | true | true | true | true | true | true | true | **false** |
| **Safety: require_checkpoints** | true | true | true | true | true | true | true | **false** |
| **Safety: allow_unsafe_tools** | false | false | false | false | false | false | false | **true** |

## Profile Use Cases

| Profile | When To Use |
|---------|-------------|
| `manual` | New users; critical production systems; sensitive projects; regulatory environments |
| `review` | Teams that want to stay in the decision loop; code reviews where choices matter |
| `supervised` | Trust the planning but want to review before execution starts |
| `cautious` | Gradual automation adoption; mixed-complexity projects; system self-assesses |
| `trusted` | Day-to-day feature development; routine refactoring; test generation |
| `auto` | Well-understood projects; strong invariant coverage; batch operations |
| `ci` | CI/CD pipelines; headless environments; automated testing; scheduled batch jobs |
| `full-auto` | Low-risk tasks (deps, docs, formatting); external safety mechanisms exist |

## Profile Precedence

Resolved at `agents plan use` time. Locked to plan after creation.

1. **Plan-level**: `--automation-profile` flag on `agents plan use`
2. **Action-level**: `automation_profile` field in action YAML
3. **Project-level**: `agents config set core.automation-profile <P> --project <PROJECT>`
4. **Global-level**: `agents config set core.automation-profile <P>`

## Semantic Escalation

The mechanism through which thresholds take effect:

```python
confidence = compute_confidence({
    'past_success_rate': get_historical_success(decision.type),
    'codebase_familiarity': get_familiarity_score(context.project),
    'risk_assessment': evaluate_risk(decision),
    'invariant_complexity': analyze_invariants(decision)
})  # Returns 0.0–1.0

threshold = profile.get_threshold(decision.flag)

if confidence >= threshold:
    return ProceedAutonomously(decision, confidence)
else:
    return RequestHumanGuidance(decision, confidence, threshold, factors)
```

**Special cases:**
- Threshold `0.0` → always automatic (even zero confidence passes)
- Threshold `1.0` → always manual (no confidence level is high enough)

## Custom Profile YAML

```yaml
# File: profiles/careful-auto.yaml
name: local/careful-auto
description: "Autonomous execution with mandatory sandbox and manual apply"

# All values are 0.0 (always auto) to 1.0 (always manual)
decompose_task: 0.0
create_tool: 0.0
select_tool: 1.0      # Always require manual apply
edit_code: 0.0
execute_command: 0.0
create_file: 0.0
delete_content: 1.0   # Always require manual for strategy revision
access_network: 1.0   # Always require manual for Apply reversion
install_dependency: 0.0
modify_config: 0.0
approve_plan: 0.0

safety:
  require_sandbox: true
  require_checkpoints: true
  allow_unsafe_tools: false
  max_cost_per_plan: 50.0  # Stop if plan costs > $50
  max_retries_per_step: 3
```

```bash
agents automation-profile add --config ./profiles/careful-auto.yaml
agents automation-profile list
agents automation-profile show local/careful-auto
```

## Progressive Trust Building

1. Start with `manual` → understand system behavior
2. Move to `review` → let phases run; stay in decision loop
3. Adopt `supervised` → trust planning; review before execution
4. Try `cautious` → confidence-gated automation
5. Adopt `trusted` → routine development tasks
6. Enable `auto` → well-understood projects with invariants
7. Use `ci` → headless CI/CD with safety nets intact
8. Use `full-auto` → low-risk batch ops where external safety exists
