Graduated Autonomy

CodeSpar uses a graduated autonomy system that lets you control exactly how much independence your agent has. From L0 (passive — only responds when asked) to L5 (full auto — acts within policy bounds), you choose the level of trust appropriate for your project and team.

Autonomy Levels

Level Details

L0 — Passive

The agent is completely silent unless directly mentioned with @codespar. It does not monitor events, does not send alerts, and does not take any action on its own.

Use case: Initial setup, sensitive environments, or when you want the agent to be available but invisible.

@codespar autonomy L0

L1 — Notify (Default)

The agent monitors CI/CD events (builds, PRs, deploys) and sends notifications to connected channels. It never takes action on its own — it only informs.

What it monitors:

• Build failures and successes
• New pull requests
• Deploy completions
• Error spikes

Example notification:

⚠️ Build Failed
─────────────────
Repo: codespar/codespar
Branch: feature/auth
Commit: abc1234 — "add OAuth flow"
Error: Test suite failed (3 failures)

View: https://github.com/codespar/codespar/actions/runs/123

L2 — Suggest

In addition to notifications, the agent proactively suggests actions when it detects relevant events. It presents the suggestion with an approval command so you can execute it with one click/message.

Example suggestion:

💡 Suggestion
─────────────────
Build failed on feature/auth — 3 test failures.

I can investigate and propose a fix.
To approve: @codespar approve sg-x1y2z3

L3 — Auto-Low

The agent automatically executes low-risk, read-only commands without asking for approval. It notifies you after execution.

Auto-executed commands:

• status — checking build/agent status
• help — showing command list
• logs — viewing activity history
• review — reviewing pull requests
• prs — listing pull requests
• context / memory — showing memory stats
• whoami — identity lookup

Example auto-execution:

🤖 Auto-Review — PR #42
─────────────────
Triggered by: new PR opened
Title: "feat: add rate limiting"
Author: @alice

Review Summary:
✅ Code quality: Good
⚠️ 1 suggestion: consider sliding window algorithm
🟢 Verdict: Approve with suggestion

(Auto-executed at L3 autonomy)

L4 — Auto-Med

Adds medium-risk commands to auto-execution. The agent can now autonomously investigate issues, execute coding tasks, and manage repository links.

Additional auto-executed commands:

• instruct — executing coding tasks
• fix — investigating and fixing issues
• link / unlink — managing repository connections
• register — identity registration
• autonomy — changing autonomy level (within bounds)

Example auto-execution:

🤖 Auto-Fix — Build Failure
─────────────────
Triggered by: build failure on main
Error: TypeError in src/auth/token.ts:42

Investigation: Token expiry uses local time instead of UTC.
Fix: PR #48 opened — "fix: use UTC for token expiry"

(Auto-executed at L4 autonomy)

L5 — Full Auto

The agent operates with maximum autonomy within safety policy bounds. It can deploy to staging and auto-approve certain actions.

Additional auto-executed commands:

• deploy staging — deploying to staging environments
• approve — approving pending actions (non-production)

Important: Even at L5, the safety guardrails still apply. See the Safety Guardrails section below.

Safety Guardrails

Regardless of autonomy level, CodeSpar agents NEVER auto-execute the following actions:

* Exception: users with the emergency_admin RBAC role can execute kill without approval at any autonomy level.

Risk Matrix

This table shows which commands require approval at each autonomy level:

Changing Autonomy Level

Via Chat Command

@codespar autonomy L3

Response:

🔧 Autonomy Updated
─────────────────
Previous: L1 (Notify)
Current: L3 (Auto-Low)

Auto-executing: status, help, logs, review, prs, context, whoami
Requires approval: instruct, fix, deploy, rollback, kill

Via API

curl -X POST http://localhost:8080/api/agents/agent-123/action \
  -H "Content-Type: application/json" \
  -d '{"action": "set_autonomy", "params": {"level": 3}}'

RBAC Interaction

Autonomy levels interact with RBAC roles. A user can only change the autonomy level if their role permits it:

If a user with operator role tries to set L5:

@codespar autonomy L5

❌ Permission Denied
─────────────────
Your role (operator) can set autonomy up to L4.
Contact a maintainer or owner to set L5.

Recommendations

Next Steps

• Command Reference — Full list of all 17 commands
• Security and RBAC — Role-based access control details
• Deploy Pipeline — How deployment approval works