> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent domain and delegation

> How Pioneer models agent identities, executions, authored work, and bounded delegation between agent contexts.

Pioneer treats an agent as a durable participant in the work graph, not as a string attached to a message. A task run has an execution identity, an action history, and an authorization context. This lets clients explain who performed work and lets the gateway constrain what one agent may ask another agent to do.

The public contracts live in `crates/protocol/src/agent_authorship.rs`, `agent_action.rs`, `agent_route.rs`, and the task actor types. Persistence and admission are implemented in `crates/gateway/src/authorization`, `crates/gateway/src/message`, and the agent-domain repositories.

## Identity, execution, and actor

These concepts are intentionally separate:

| Concept | Meaning |
| - | - |
| Agent identity | A stable named identity such as a reviewer or research agent. It has a display name, nickname, avatar revision, role label, source, and status. |
| Agent execution | One run under an identity. It has its own execution id, policy generation, and lifecycle. |
| Actor reference | The type of actor that authored a durable record. It can point to a principal, an agent execution, or the system. |
| Auth subject | The subject used for authorization. It distinguishes principals, agent executions, services, and system work. |
| Agent action | A typed operation performed by an execution, such as sending a message, starting a task, or reviewing a result. |

Agent identities can come from a native Pioneer agent, a configured CLI runtime instance, or an ephemeral execution. Retired identities remain useful for interpreting old records, while new work cannot silently reuse their active role.

Agent ids are stable ASCII identifiers. Nicknames are lowercase ASCII tokens. Display names, role labels, and avatars are presentation data with bounded sizes. The timeline stores an `AgentPresentationSnapshot` when work is authored, so changing an agent's current name or avatar does not rewrite history.

## Work graph

The work graph connects:

```text theme={null}
principal or system
  -> agent identity
    -> agent execution
      -> action
        -> task, turn, review, or delivery
```

A task run may create a child thread and several turns. Each turn can contain work items and can create more task runs. The gateway records the actor and execution lineage on the durable rows and projects that lineage into timeline and task responses.

This is different from a task tree. The task tree describes parent and child task lifecycle. The agent work graph describes who authored or performed each operation. A task can be owned by a user thread while its execution is attributed to an agent identity.

## Authored presentation

Timeline rows use the presentation snapshot captured at authorship time. The snapshot includes:

* agent identity id;
* execution id;
* source kind and source revision;
* display name and nickname;
* avatar revision;
* role presentation.

Clients should render the snapshot attached to the row. They should not look up the current agent profile and replace historical authors. This preserves an accurate record when an agent is renamed, retired, or assigned a new avatar.

## Delegation routes

An agent does not inherit all of the initiating principal's permissions when it delegates. The gateway creates an explicit `AgentDelegationRoute` with:

* source execution and destination thread;
* execution-bound or identity-bound route kind;
* a finite action list;
* disclosure policy for text, artifacts, context, user input, and result return;
* source and destination policy generations;
* hop count and maximum hop count;
* grant fingerprint and expiry;
* optional destination identity, profile, and return route.

Supported actions are `send_message`, `start_agent`, `create_task`, `schedule_task`, `review_task_result`, and `deliver_result`. Result return is independent of ordinary text disclosure. Allowing a message does not implicitly allow a full task result to cross the route.

Route creation validates the source and destination workspace and gateway, action uniqueness, non-empty disclosure, expiry, generation, hop boundaries, and return-route compatibility. The graph validator rejects cycles and excessive edges. A route is usable only while its status is `active`, its lease is valid, and the admission-time policy facts still match.

## Admission and revalidation

The gateway checks an agent action at the point where it can create an effect. This matters for delayed tasks and detached work because the principal, workspace membership, thread visibility, or permission cap may have changed since the route was created.

Admission combines:

1. the authenticated principal or parent execution;
2. the stored agent identity and execution actor;
3. the route action and disclosure policy;
4. the destination workspace and thread authorization;
5. the current policy generation and execution limits;
6. the task, turn, artifact, and delivery contract.

The result is a typed rejection or an admitted action. It is not a client hint. Clients may use capability snapshots to hide controls, but the gateway remains authoritative.

## Failure and lifecycle rules

An identity can be active or retired. A route can be prepared, active, expired, or revoked. An execution can finish independently of its parent task, but it cannot use a stale route after authorization changes. The gateway records route revocations and task or turn termination reasons so recovery does not accidentally resume work under an obsolete actor.

When agent work appears in the UI, clients should combine task and turn projections. Use the task tree for lifecycle and result state, timeline rows for authored presentation, and capability snapshots for controls. Do not infer an agent's access from its nickname or role label.

## Related pages

* [Identity, authentication, and authorization](https://docs.getpioneer.dev/architecture/identity-and-authorization.md) explains principal and session access.
* [Tasks architecture](https://docs.getpioneer.dev/architecture/tasks.md) explains child runs, review, delivery, and write locks.
* [Permission system](https://docs.getpioneer.dev/architecture/permissions.md) explains turn-level policy caps.
* [Agent domain API](https://docs.getpioneer.dev/protocol/agent-domain.md) lists route methods and public projections.
* [CLI runtime architecture](https://docs.getpioneer.dev/architecture/cli-runtime.md) explains runtime-backed agent identities.
* [Timeline and turns](https://docs.getpioneer.dev/protocol/turns.md) explains how authored work reaches clients.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.