Autonomy
Explicit operator control, coordinator handoff, task leases, review gates, and safe spawn.
Autonomy in CompozyOS lets managed agent sessions discover work and delegate bounded child sessions. The daemon owns task state, leases, review verdicts, and spawn authority.
In this section
Coordinator handoff and configuration
Understand when the daemon starts one workspace coordinator, how provider/model settings resolve, and where manual control remains explicit.
Claim, heartbeat, complete, fail, and release
Use the session-bound task API correctly and keep raw lease credentials out of read models, logs, and prompts.
Typed task execution profiles
Steer coordinator guidance, worker selection, reviewer routing, participant policy, and worktree selection through one typed task-owned overlay.
Post-terminal review gate
Request reviews after terminal runs, route reviewers, persist typed verdicts, and create bounded continuation runs with missing-work guidance.
Task status cursors and reconnects
Inspect durable task-status projection progress and resume event streams without gaps.
Bounded child sessions
Spawn workers with TTL, lineage, caps, and permission narrowing through the daemon-owned safe spawn contract.
The MVP flow
| Step | What happens | Starts execution? | Starts a coordinator? |
|---|---|---|---|
compozy task create or API create | Stores durable task intent. The task can be draft, blocked, or ready. | No | No |
compozy task publish, compozy task start, compozy task approve, UI start, or equivalent API | Enqueues a durable task run. | Yes | Yes, if coordinator auto-start is enabled and no healthy workspace coordinator exists |
compozy task next | A managed agent session atomically claims one eligible queued run and receives a safe lease summary. | Claim only; start separately | No |
compozy spawn | A validated parent session asks the daemon to create a bounded child session. | Creates a child session only | No coordinator child sessions in the MVP |
The durable execution boundary is the run enqueue boundary, not task creation. The same boundary is used by manual operator starts, publish/approval flows, automation approvals, and coordinator-created follow-up tasks.
Which command owns what
The autonomy surface is exposed both as the dedicated compozy__autonomy tool family and as the
parallel compozy task CLI. Both routes call the same task service writers.
| Surface | Use it for | Do not use it for |
|---|---|---|
compozy me and compozy me context | Inspect the caller session, workspace, capabilities, and active leases. | Claiming or changing task-run state. |
compozy__task_run_claim_next | Claim and start the next eligible worker run, including dedicated-session handoff when required. | Listing arbitrary tasks or writing progress notes. |
compozy task next | Claim the next eligible run for an operator-managed explicit start flow. | Assuming execution has started or a worktree was materialized. |
compozy__task_run_heartbeat, compozy__task_run_complete, compozy__task_run_fail, compozy__task_run_release | Extend or finish the current session-bound claim by run_id. | Conversation, review requests, or handoffs. |
compozy spawn | Create a narrowed child session with TTL and lineage. | Starting a second coordinator or widening parent permissions. |
Manual and autonomous work coexist
Operators can still create tasks, start sessions, prompt sessions directly, and run counter-checks without involving autonomy. User-started sessions are normal root sessions. They may claim work when their capabilities match, but they can also be prompted directly through the session surface.
Coordinator sessions and spawned worker sessions are normal managed sessions with additional lineage and TTL metadata. They do not bypass task-run leases, hooks, permissions, workspace boundaries, or configured execution policy.
What is not in the MVP
The autonomy docs describe only the implemented local MVP. They do not promise:
- cross-daemon swarm coordination or leader election
- autonomy dashboards, lease dashboards, or spawn lineage trees in the web UI
- eval/replay harnesses
- a separate autonomous task queue
- relaxing the one-active-lease-per-session invariant
Related pages
- Task CLI Reference lists exact task commands and flags for the parallel CLI surface.
- Tool CLI Reference documents the operator commands that inspect the registry and the
compozy__autonomytool family. - Sessions explains session types, state, stop behavior, and persistence.
- config.toml documents
[roles.coordinator]and[task.orchestration]. - Task Execution Profiles documents the typed task-owned overlay used for coordinator guidance, worker selection, reviewer routing, participant policy, and worktree selection.
- Review Gate documents the post-terminal review gate, reviewer routing, verdict semantics, and continuation runs.
- Notification Cursors documents task-status projection progress and SSE resume seeding.
- Hook Event Catalog lists
coordinator.*,task.run.*, andspawn.*hook events.