Autonomy

Autonomy in AGH is the runtime path that lets managed agent sessions discover work, coordinate through task-bound channels, and delegate bounded child sessions. It is additive: the same tasks, runs, sessions, hooks, and network channels are used by manual and autonomous flows.

In this section

Coordinator

Coordinator handoff and configuration

Understand when the daemon starts one workspace coordinator, how provider/model settings resolve, and where manual control remains explicit.

Run enqueue

Task Runs

Claim, heartbeat, complete, fail, and release

Use the session-bound task API correctly and keep raw lease credentials out of read models, logs, and channels.

Ownership

Channels

Task-run coordination channels

Use channel messages for conversation and correlation while keeping task ownership and terminal status in the task service.

Conversation

Spawn

Bounded child sessions

Spawn workers with TTL, lineage, caps, and permission narrowing through the daemon-owned safe spawn contract.

Delegation

The MVP flow

Step	What happens	Starts execution?	Starts a coordinator?
`agh task create` or API create	Stores durable task intent. The task can be draft, blocked, or ready.	No	No
`agh task publish`, `agh task start`, `agh task approve`, UI start, or equivalent API	Enqueues an executable task run. Workspace-scoped coordinated runs receive a stable coordination channel.	Yes	Yes, if coordinator auto-start is enabled and no healthy workspace coordinator exists
`agh task next`	A managed agent session atomically claims one eligible queued run and receives a safe lease summary.	It owns the claimed run	No
`agh ch send`, `agh ch recv`, `agh ch reply`	Agents exchange status, requests, blockers, handoffs, results, and review requests.	No	No
`agh 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 agh__autonomy tool family and as the parallel agh task CLI. Both routes call the same task service writers.

Surface	Use it for	Do not use it for
`agh me` and `agh me context`	Inspect the caller session, workspace, capabilities, active leases, active coordination channel, inbox summary, and limits.	Claiming or changing task-run state.
`agh__task_run_claim_next` (CLI: `agh task next`)	Atomically claim the next eligible run for the current managed session.	Listing arbitrary tasks or announcing progress to peers.
`agh__task_run_heartbeat`, `agh__task_run_complete`, `agh__task_run_fail`, `agh__task_run_release`	Extend or finish the current session-bound claim by `run_id`.	Conversation, review requests, or handoffs.
`agh ch list`, `recv`, `send`, `reply`	Operational conversation in channels visible to the current session.	Task ownership, lease extension, or terminal task status.
`agh 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 also normal managed sessions with additional lineage and TTL metadata. They do not bypass task-run leases, hooks, session permissions, workspace boundaries, or network-channel access rules.

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
broad peer/channel memory extraction
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

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 agh__autonomy tool family.
Sessions explains session types, state, stop behavior, and persistence.
Network Channels explains channel and peer behavior.
config.toml documents [autonomy.coordinator].
Hook Event Catalog lists coordinator.*, task.run.*, and spawn.* hook events.