agents

Agent profiles and subagents

Local Operator has two different mechanisms. Do not treat them as interchangeable.

Persistent registered agents

A registered agent is a durable profile under the Local Operator configuration root. It can carry a provider/model, sampling settings, description, tags, categories, working directory, and persisted state.

List profiles only when a task may benefit from an existing specialist or the user asks about agents:

local-operator agents list
local-operator agents list --page 2 --perpage 10

Do not list the registry at every session start. Local Operator semantically compares the first task with descriptions, tags, and categories locally; when a profile may fit, it exposes this guide as a short hint without injecting the registry contents. Listing is the explicit action that reveals names and metadata.

Create a profile:

local-operator agents create research

Start an interactive session with it, or send it one headless task:

local-operator --agent research
local-operator exec "Review this evidence and return the supported findings" --agent research

--agent NAME creates a missing profile automatically, but explicit agents create is clearer when setup is intentional. exec --agent-id ID selects an exact existing profile and fails on a missing ID.

A registered profile is not automatically a live peer in the current process. Interact by starting a session or an exec run with that profile. Do not imply that a message was delivered to another live agent unless a tool actually reports delivery.

Ephemeral task subagents

Use the task tool when the current job contains an independent, well-bounded slice that can run concurrently or needs isolated context. A task subagent:

• inherits the parent model and reasoning effort, working directory, approval gate, and compaction budget. effort picks an operator-configured model TIER, not a reasoning level you choose: the tier names the child's model, and the operator may also give it a reasoning effort (subagents.models.hi: {model: provider/model, effort: xhigh}) that the child then runs at. Who may choose a tier is the OPERATOR's decision, not yours. subagents.model_choice decides that, and its default is operator: no tier is advertised to you and asking for one is refused — omit the field. model="inherit" can still bypass a role pin; exact model="provider/id" needs the model-choice arm. The way back is theirs to take (set subagents.model_choice=model in /settings, or lop config edit subagents.model_choice model); only then may effort name a tier they configured under subagents.models, and the task schema then lists exactly those. (An operator who wants one role on a stronger model does not need to hand you the picker at all: a role's own profile carries its effort pin, and the desktop profile editor writes it.)
• receives only the prompt passed to task; include every requirement and expected output
• reports through the parent session's jobs/events — the launch RESULT names the model each child will run on (on <provider/model>, or on this session's model (<provider/model>) when it inherits), and wait/jobs repeat it, so a delegated slice's model never has to be inferred
• has its model decided when it starts or resumes. A pinned child (an effort tier, or a role's own pin) re-resolves its tier from current config. An inheriting child takes the model of the nearest ancestor that decides one: a parent that is still running gives its current model; a parent that has finished gives its own pin if it had one, and otherwise the choice passes up to ITS parent; your session gives its current model. So a worker of a manager pinned to a cheaper tier resumes on that tier, not on your model, while a worker of an unpinned manager follows your own /model switch. hub op='resume' therefore does NOT bring a child back on the model it ran on before. The resume receipt names the model the same way the launch result does (on its parent's model (<provider/model>) when an ancestor decided it), and adds (its previous run was on <provider/model>) when it changed. If a nested child's lineage can no longer be read (an ancestor's record is gone, or was saved by an older version and shows no pin), it keeps its previous model; if it never recorded one, it runs on your session's model. The receipt says which, e.g. on <provider/model> (its parent's model could not be found; kept its previous model). Switching a parent's model — its own /model, or a switch sent from the phone or lop attach — does not change children already running; pause and resume one to move it.
• may itself delegate if and only if its role allows the task tool. A manager keeps task at any depth, so a manager's child is a manager too; a role that does not delegate (a reviewer, a coder, a scout) is never handed it and must do the work itself. A subagent launched with no role inherits its parent's allowance. When a child does delegate, its own children are listed in its page — in the TUI the roster re-scopes to them and you walk back up with p/Esc; the desktop UI walks the same tree with its back control and breadcrumbs.
• is ephemeral; it does not become a registered profile or keep durable specialist state
• Check actual owner/job state before handing off. A hub op='send' queue receipt is not running work: completed/paused/failed owners need explicit hub op='resume' on their latest job ID and existing history, with the work message. Never infer execution from delivery or spawn a duplicate actor.