Subagents & roles

An agent rarely works alone within a session. It spawns helpers — a searcher, a planner, a reviewer — each doing a slice of the job. OAK records each one as its own agent, attributes its edits to it, and labels it by the job it was given.

Subagent

A subagent is an agent a session spawned inside itself. It writes its own transcript (a sidechain), appears nested under its parent in the fleet, and carries its own timeline, metrics, and role. Its edits are attributed to it and reviewed like any others — so a parent agent's change map and a subagent's stay distinct.

Role

A role is the job a spawn was given, not a kind of agent — Explore, Plan, general-purpose, code-reviewer, fork. It rides the spawning tool call as its subagent_type, and the observatory shows it in its own column on each subagent and workflow row. The same model wears many roles; the role says which one this instance was asked to play — so a fan-out reads as the mix of jobs it is, rather than a list of identical agents.

Spawn

Start a peer agent in herdr or use oak agent start --kind claude or codex. The editors’ New Session action uses the same API. A peer you start remains distinct from a worker spawned by an existing conversation.