research-document
Agent identity and provenance
Agent identity and provenance
Praxis records who or what produced each meaningful piece of work: an agent, a human, or an automated non-agent process. It also records which run did it. Attribution does not come from Git authorship, prose, or inference.
The records live in three places, all extensions of the existing Praxis architecture:
| Record | Where | What it answers |
|---|---|---|
| Execution identity | .ros/telemetry/executions/EXE-*.json → identity (now with actorKind) |
Which run, which agent, provider, model, runtime, and session |
| Action provenance | .ros/events/events.jsonl → actor on every work event; artifact.contributed events |
Who performed a transition or contribution, when, in which execution, and on which state |
| Artifact provenance | front matter provenance.contributions on canonical artifacts (requirements, decisions, evidence, …) |
Original creator, every later contributor, and each contributor's execution, reason, and evidence |
Requirements for this capability: RQ-ROS-2026-A001 through RQ-ROS-2026-A012
(research/requirements/). Decision: DF-ROS-2026-A036.
Why
A repository shared by several agents and humans needs to answer these questions without anyone's memory:
- who created a requirement and who changed it since;
- which execution produced a finding, a decision, or some evidence;
- whether the result came from an agent, a human, or CI;
- whether a human corrected an agent's work, or one agent revised another's.
Metrics over agents need the same records: output, rework, defects, validation failures, cost and duration by agent, model, or provider. See Metrics.
Identity, execution, and actor
Praxis records identity at two levels that it keeps separate.
-
Stable identity: the actor. This identifies who, and it is the same across runs. It is a small, portable object:
{"kind":"agent","id":"openai/codex","provider":"openai","model":"gpt-5-codex","runtime":"codex"}kindisagent,human,automation(CI or another deterministic non-agent process), orunknown. A namespacedx-...extension is also allowed.idis the stable identifier:- an explicit
--agent/--actor/PRAXIS_ACTORvalue always wins; - otherwise a non-human actor whose provider and runtime are both known
is identified as
provider/runtime; - otherwise the id is
unknown.
- an explicit
provider,model, andruntimeare present for every non-human actor, as the literal"unknown"when not known. They are omitted for a human, because they do not apply. "Unknown" and "not applicable" are never conflated.
-
Execution identity: the run. This identifies which run. It is the existing
EXE-<timestamp>-<random>telemetry execution ID, created bywork begin. Two runs of the same agent always get two execution IDs, and everything produced in one run carries that run's ID.
A contribution is keyed by the execution that produced it. Contributions from
two runs of the same agent therefore share an actor id but have different
keys. They never merge, and neither is ever mistaken for the other.
How an agent establishes identity: once per execution
-
Start the execution. Run
./praxis work begin --id ID --occurred-at NOW.Identity is discovered from a small whitelist of non-secret environment variables, and explicit declarations always win:
Source Examples Flags on work begin/resume/block/complete,add, andtelemetry start--actor-kind,--agent,--actor,--provider,--model,--runtimeEnvironment variables set once per session PRAXIS_ACTOR_KIND,PRAXIS_ACTOR,PRAXIS_TELEMETRY_PROVIDER,PRAXIS_TELEMETRY_MODEL, …Known agent runtimes Codex, Claude Code, Gemini CLI, Copilot Known CI GitHub Actions resolves as automationThe legacy
ROS_*names of these variables still work; thePRAXIS_*name wins when both are set.Nothing is guessed. A local model server (
OLLAMA_HOST) proves nothing about who is acting, so it implies no actor kind. -
Check who you will be recorded as. Run
./praxis provenance identity. It prints the resolved actor, the mechanism that determined it, and the active executions. -
Work normally. Work events carry the actor automatically. To attribute an artifact you created or materially changed, run:
./praxis provenance record --path research/requirements/RQ-...md --operation created \ [--reason "why"] [--evidence EV-...] [--derived-from ID]The command inherits the actor from the active execution record, so the agent does not repeat its identity.
-
Finish.
./praxis work complete …then./praxis validate, which catches missing or broken provenance.
A recording inherits the execution's identity only when the recording process is plausibly that same run. Praxis never attributes a contribution to another actor's execution, or to another run of the same agent. The rules are:
- The process must have an identity of its own. The identity can come from
a flag, from
PRAXIS_ACTOR/PRAXIS_ACTOR_KIND, or from a detected agent runtime. A process with no identity at all, such as a plain terminal, never inherits an execution implicitly: it must declare itself, or name the execution with--execution. - The identity must agree with the execution's actor.
- Session and run IDs must match. When both sides know a session, conversation, or CI run ID, the two must be equal. A second Claude Code session, a second Codex thread, or a second CI run is a different run.
- Implicit inheritance needs positive evidence. A shared run key, or the
same known stable actor id, must show the process is that run. Declaring
only
PRAXIS_ACTOR_KIND=agentagrees with every agent, so it proves nothing. --executionis an explicit assertion. Naming an execution means "I am acting within this run". A declared process must still agree with that execution. A process with no identity is taken at its word, so only the actor actually running the execution should use it; everyone else should declare themselves.- An agent must record inside its own execution.
- Several active executions. Praxis picks the one that matches the recording
process, or asks for
--execution. - Outside any execution. A declared human or automation acting outside any
execution (for example, a human approving while an agent is mid-run)
contributes under a
CTB-<UTC day>-<actor digest>key. One actor's recordings on one day form a single entry that merges operations and advanceslast, exactly like an execution's entry.
Identity is provenance, not authentication
Everything described here is self-reported provenance. A record saying
provider: openai does not prove that OpenAI produced anything, and
kind: human, id: kevin does not authenticate Kevin. Praxis guards against
accidental misattribution:
- it resolves identity only from the current process;
- it never inherits another run's actor. The legacy "last actor" field in
.ros/context/current.jsonis not provenance and is never used for it; - it cross-checks every contribution against its execution record;
- it refuses re-attribution.
Praxis does not defend against a malicious process that lies about itself.
The model leaves room for stronger attestation later, without redesign:
- Each contribution is a keyed mapping entry, so a future signer can add
fields such as
attestationorsignature.provenance recordedits the front matter surgically and never re-renders another contributor's entry, so unknown fields survive. The test suite covers this. - The execution record is the natural place for an external execution receipt
or CI attestation (GitHub Actions OIDC, a GitHub App installation identity, a
signed run manifest). The actor already distinguishes
automationfromagent. - Events carry
previous.sha256andcurrent.sha256content digests, which a signature can cover.
Signed events, verified execution receipts, and key management are deferred.
They belong behind the adapter boundary or in an attestation service, not in
Praxis core; see DF-ROS-2026-A036.
Remote execution: requester, executor, and principal
A remote request can come from a cloud agent without a local Praxis
runtime; see remote-protocol.md and
DF-ROS-2026-A041. When it does, the process that runs Praxis is a runner,
for example a GitHub Actions job, acting on the agent's behalf. Three
different facts are recorded, and none of them is ever collapsed into
another:
- Requester (the actor). This is the actor the request asserts. It
becomes the execution's
identityand the actor on its events. The execution marks it withidentity.assurance: "asserted-by-request".- If the request does not name an actor, every field is
unknown. It is never recorded as the runner.
- If the request does not name an actor, every field is
- Executor. These are the facts the runner observed about itself: its
kind, run ID and attempt, workflow ref, repository, host, and the Praxis
version it ran. They are recorded as the execution's
executorblock, markedassurance: "observed-by-executor".- The runner's run ID belongs to the executor, not to the agent. It is
never copied into
identity.runId.
- The runner's run ID belongs to the executor, not to the agent. It is
never copied into
- Transport principal. This is the account the transport authenticated,
such as the GitHub user who triggered the run. It is recorded as
executor.principal. It is who asked the runner, which can differ from the actor who did the work.
The command runs in a child process whose environment is derived, not
inherited (RemoteIdentity.childEnvironment):
- Every variable that identity discovery reads is removed, so the runner's
own markers cannot be read as the agent's identity. These include
GITHUB_ACTIONS,GITHUB_RUN_ID, an agent session variable, and a strayPRAXIS_ACTOR. - The requester's actor is set explicitly, with
unknownfor anything it did not state. - Only an allow-list of operational variables survives, such as
PATH,HOMEand the locale. Tokens and provider credentials never reach the command, its telemetry, or its diagnostics.
A local execution has no executor block and no assurance field. Its
identity is self-reported by the local process, exactly as before.
Continuing another actor's work
A work transition links only executions that the acting process may
continue (ActorResolution.mayContinue). That means the same actor, and
nothing known about the run (session, conversation, or CI run) differing.
Two cases follow:
- When a different agent resumes a work item, it gets a new execution whose
identity.parentExecutionIdnames the predecessor. - When the same agent resumes in a new session, the same happens.
A predecessor's still-active execution is never linked to the successor's events or recovered for it. The one exception is completing the work item, which still finalizes every active execution for that item.
The item's timeline events (work.blocked, work.resumed) are still
recorded on every active execution as clock facts about the item. Such an
event records when the item changed state. It does not attribute the
successor's work to the predecessor.
Remote requests follow the same rule. A request whose execution.id names
an execution the requester may not continue is refused as domain-rejected.
Artifact provenance
Canonical serialization
provenance:
contributions:
EXE-20260925T194000000Z-ab12cd34: # the execution that contributed
operations: [created, modified]
at: 2026-09-25T19:40:00.000Z # first operation by this execution
last: 2026-09-25T20:05:00.000Z # optional: its latest recorded operation
actor:
kind: agent
id: anthropic/claude-code
provider: anthropic
model: unknown
runtime: claude-code
reason: "Initial capture"
evidence: [EV-ROS-2026-A049]
CTB-20260926T090000000Z-5f2e19aa: # a human, outside any execution
operations: [approved]
at: 2026-09-26T09:00:00.000Z
actor:
kind: human
id: kevin
derived_from: [EV-ROS-2026-A049] # lineage (existing reference field)
Why a mapping and not a list. Contributions are a mapping keyed by
execution (EXE-…) or contribution (CTB-…) ID. The repository's front-matter
reader supports nested mappings but not lists of mappings. The keyed form also
makes "one entry per execution" a structural property.
Operations. created, modified, reviewed, approved, superseded,
and migrated, plus x-... extensions. At most one contribution may claim
created, and nothing may precede it.
Timestamps. at is an ISO-8601 UTC timestamp.
Registries. Generated registries (registries/*.json) project the whole
block, so provenance is queryable without parsing Markdown.
How contributors accumulate
- Additive only.
provenance recordappends a new entry, or merges a new operation into the same execution's own entry. It never replaces or rewrites another contributor's entry. - Idempotent. Re-recording an identical call changes nothing and writes no
event. This also covers a human's
CTBcontribution. A later recording by the same execution updates that entry'slasttimestamp, so every recorded modification stays visible even when the execution had already recorded the same operation. This matters when an agent commits several times within one execution. - Refused edits.
- It refuses to re-attribute an execution to a different actor.
- It refuses a second
created, and acreatedrecorded after existing history. - It refuses to touch provenance that is already malformed.
- It refuses to rewrite a
derived_fromvalue it could not write back unchanged.
- Verified before writing. Before writing, it re-reads the result and proves
four things: the provenance reads back as intended,
derived_fromreads back as exactly the existing list plus the new references, no other front-matter field changed, and the document body is byte-for-byte unchanged, including line endings. - Reasons. A reason is a single line; line breaks become spaces.
- Evented. Every recorded change also appends an
artifact.contributedevent carrying:- the actor and the execution;
- the operation, reason, and evidence;
derivedFrom;- the artifact's id, path, and
version; previous.sha256andcurrent.sha256, which record the state the contribution operated on and the state it produced.
Human and agent involvement
./praxis provenance show ID derives involvement from the recorded contributions,
never from "last modifier":
| Label | Meaning |
|---|---|
agent-created |
an agent created it; nothing since |
human-created, agent-modified |
a human created it; an agent changed it |
agent-created, human-approved |
an agent created it; a human approved it |
agent-created, agent-modified |
another agent revised it (agentToAgentRevision: true) |
agent-created, human-modified |
human correction of agent work (humanCorrectionOfAgentWork: true) |
origin-unknown, … |
contributions exist but none records the creation (legacy artifact later modified) |
unattributed |
no provenance recorded (legacy); nothing is inferred |
Derived artifacts: authorship versus lineage
When agent B writes an artifact based on agent A's artifact, the two facts are recorded separately:
- Authorship. B's execution is the
createdcontribution of the new artifact. - Lineage. The new artifact's existing
derived_fromreference field names A's artifact. Use--derived-fromonprovenance record.
provenance show resolves each lineage source to its own originator, and lists
the reverse direction as derivatives. It never merges the source's authors
into the derivative's. Lineage may name a foreign, namespaced reference from
another system (for example ordo:resolution/r-17), so lineage crosses
integration boundaries.
Validation
./praxis validate includes provenance.
- Errors fail validation.
- Warnings are printed (and emitted with
"severity":"warning"in--json) but do not fail validation. - Informational findings appear only in
./praxis provenance audit.
| Situation | Severity |
|---|---|
Malformed provenance block (unknown kind or operation, bad timestamp, agent without an execution key, an agent actor missing provider/model/runtime, duplicate or late created) |
error |
| A contribution's actor contradicts its execution record (impersonation or copy-paste) | error |
| Contribution evidence names a non-existent artifact ID | error |
Enforced policy: artifact created on or after requiredFrom with no provenance |
error |
Enforced policy: requirement (RQ, configurable) created on or after requiredFrom without a created contribution |
error |
Enforced policy: new artifact whose updated date is more than one day after its latest contribution (unattributed modification; the one-day tolerance absorbs local-date versus UTC skew) |
error |
Enforced policy: new artifact changed since the base revision while its contributions did not change (unattributed modification, detected from Git independently of dates; the base is the working tree against HEAD, or everything since PRAXIS_BASE_REF in CI) |
error |
Invalid ros.json provenance block (enforced without a date) |
error |
Malformed actor on an event |
error |
| Contribution names an execution with no local record (imported, pruned, or mistyped) | warning |
Enforced policy: new non-requirement artifact without a created contribution |
warning |
Legacy artifact updated on or after requiredFrom without a recorded contribution |
warning |
| Legacy artifact changed since the base revision without a recorded contribution | warning |
Legacy artifact (created before requiredFrom) with no provenance, including any self-declared author_agent/created_by_agent/owner_agent/source_author |
info |
| Legacy event that records executions but no actor | info |
Policy and legacy repositories
Provenance is enforced per repository in ros.json:
"provenance": {"version": "1.0.0", "enforce": true, "requiredFrom": "2026-09-25", "requireOriginator": ["RQ"]}
- No
provenanceblock. Nothing is required, so an upgraded repository keeps validating exactly as before. Any provenance that is present is still checked structurally. - Enforced.
- Every canonical artifact whose
createddate is on or afterrequiredFrommust be attributed. - Artifacts created earlier are legacy. They stay valid and readable, and are never required to acquire invented history.
- Legacy authorship fields such as
author_agentare free-text, self-declared, and unverified.auditandshowreport them under that label; Praxis never converts them into structured provenance.
- Every canonical artifact whose
Migration is deliberately a no-op. Praxis does not rewrite history and does
not infer authorship from style, timestamps, filenames, or Git metadata. A
legacy artifact gains provenance only when a real contributor records a real
contribution: its first modification after the policy date adds an
origin-unknown history whose later entries are known.
Legacy records elsewhere.
- Execution records written before
identity.actorKindexisted are projected from the discovery mechanism the record itself preserved (provenance.sources), which is recorded evidence, or else asunknown. - Events written before
actorexisted remain valid. - Backlog items without
createdByActorremain valid.
Integrations and export
Provenance travels with data rather than being stripped at a boundary.
- Work adapter publication.
./praxis adapter publishcopies events verbatim, so the external work system receivesactoron work events and the fullartifact.contributedrecords. - Registries. Generated registries include each artifact's
provenanceblock andderived_from. - Portable files. The artifact file itself carries its contributors, so copying it to another repository or system keeps its origin. A receiving repository without the originating execution records reports those contributions as a warning, not an error, and keeps them intact.
- Ordo. Ordo resolution observations already carry
provider{id, model, …}, and assessments carry a provider-neutralassessor. Praxis preserves raw Ordo records verbatim../praxis ordo handoffaddsproducedBy: {actor, execution}: the packaging actor in canonical form and its execution when exactly one active execution is evidently the same run (otherwisenull, never a guess), so the receiving agent or system keeps the handoff's origin. - Installation. The
ROS-INSTALL-*bookkeeping event that both installers write is attributed to the installer itself,{"kind":"automation","id":"ros-bootstrap","runtime":"ros-bootstrap"}, so no event in a fresh repository lacks an actor. - Other Echelon systems. Vigila, Aegis, Dokimos, Percepta, and EDF
experiments can adopt the same actor object
(
schemas/provenance-actor.schema.json) and contribution shape (schemas/artifact-provenance.schema.json). There is no dependency on any of them: Praxis remains independently usable, and those systems need only the JSON shapes. - Git host neutrality. Nothing here assumes GitHub.
github-actionsis one whitelisted automation runtime among others, and a future attestation from a GitHub App or OIDC token would be one attestation source among others.
Metrics
This work adds no analytics subsystem. It records the facts that later analysis needs.
./praxis provenance audit --json emits:
- one row per (artifact, contribution): artifact id, kind, path, contribution key, execution, operations, time, actor, and whether it is the origin;
- per-actor summaries: artifacts, created, modified, reviewed or approved, and executions;
- coverage counts for artifacts, events, executions, and backlog items;
collaboration: the artifacts where one agent revised another agent's work (agentToAgentRevisions), where a human corrected agent work (humanCorrectionsOfAgentWork), where a human approved agent work (humanApprovedAgentWork), andhotspots(artifacts with more than one contribution, most first). Each is derived from the artifact's recorded involvement, never from the last modifier.
Joined with telemetry execution records (cost, duration, and tokens by execution) and with defect or validation data by path or ID, these rows support the following analyses by agent, model, or provider:
- requirements created or modified;
- findings;
- rework and modification hotspots;
- human corrections of agent work and agent-to-agent revisions;
- evidence generated;
- cost, duration, and outcomes.
Examples
Two agents and a human on one requirement.
# Claude Code session (identity discovered from CLAUDE_CODE_SESSION_ID)
./praxis work begin --id FEAT-9 --occurred-at "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"
./praxis provenance record --id RQ-APP-2026-A007 --operation created --reason "From customer interview" --derived-from EV-APP-2026-A002
./praxis work complete --id FEAT-9 --occurred-at … --evidence implementation=… --evidence tests=…
# Codex session, later (identity discovered from CODEX_SESSION_ID)
./praxis work begin --id FEAT-12 --occurred-at …
./praxis provenance record --id RQ-APP-2026-A007 --operation modified --reason "Tighten acceptance criteria"
# A human reviewer, outside any execution
PRAXIS_ACTOR_KIND=human PRAXIS_ACTOR=kevin ./praxis provenance record --id RQ-APP-2026-A007 --operation approved
./praxis provenance show RQ-APP-2026-A007
# involvement: agent-created, agent-modified, human-approved
A local or future agent with no whitelisted environment declares itself once:
export PRAXIS_ACTOR_KIND=agent PRAXIS_ACTOR=acme-planner PRAXIS_TELEMETRY_PROVIDER=acme PRAXIS_TELEMETRY_RUNTIME=acme-cli
./praxis work begin --id FEAT-3 --occurred-at … # model left unset: recorded as "unknown", never invented
CI automation needs no declaration. Under GitHub Actions the actor resolves
as {"kind":"automation","id":"github/github-actions",…}, and a CI job that
records provenance is attributed to automation, not to an agent.
Continuation and handoff between executors
Continuity never depends on a provider's chat history (DF-ROS-2026-A042).
When an executor disappears, the successor inherits nothing but the
repository and Praxis state:
- Recovery. The successor reads the latest durable checkpoint: the exact commit, branch, completed work, and next action. Praxis re-verifies it against the remote.
- Its own execution. The successor runs
work continueunder its own identity. The new execution recordsparentExecutionIdas the predecessor's execution: lineage, not authorship. - The predecessor stays as it was. The predecessor's execution record is
never edited. A
work.continuedevent, attributed to the successor, records the predecessor's disposition asinterrupted, observed by the successor. The predecessor is never marked successful, and the successor never claims its work. - Checkpoints are attributed. Each checkpoint carries the actor and the execution that recorded it. In a handoff from A to B, A's checkpoints stay A's and B's stay B's.
Any pair of executors works the same way, because each keeps its own identity:
- agent to agent, across providers (for example Claude to Codex, or Codex to Gemini);
- agent to human, and human to agent;
- automation to either.
A process with no declared identity cannot continue work. A successor can never continue as another executor.