Skip to main content
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: 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:
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.