[feat] Record the agent each workflow step ran as #1176

Parent: #818

Goal

A run record says a step ran as reviewer. That is the name of the agent definition the step selected (records.ts:173), not the agent that did the work. The work came from a composition: the definition, if any, and how the tool applied it; the tool and its version; the model and effort; the team config delivered to that checkout; and the project commit. Two passes of the same step can differ in any of these, and today the record cannot tell them apart.

Record that composition for every pass, as observed, so a result can be traced to what produced it and two results can be compared.

From this issue on, agent in run records, labels and stats means this composition. The YAML key agent: on a step keeps its meaning: it selects a definition.

Shape

/** What one pass of a step ran as. Every field is best effort: absent when not observed, never inferred. */
type AgentObservation = {
  v: 1;
  definition?: { name: string; applied?: 'main' | 'prompt' | 'subagent' };
  tool: { name: string; version?: string };
  model?: { requested?: string; reported?: string; alias?: string };
  effort?: { requested?: string; reported?: string };
  team?: { revision: string; localChanges: boolean };
  project?: { commit: string; dirty: boolean };
  teamai: string;
  driver: string;
  fingerprint?: string;
};

When team is left out. A pull record does not always name one revision. A partial or inherited delivery keeps the earlier rev and adds the newer one to pushBaseRevs while updating delivered (pull.ts). Leave team out when the entry is missing, its rev is empty, it has no delivered, or its pushBaseRevs is not empty.

Fingerprint. The sha256 of the canonical JSON (sorted keys, no whitespace) of { v, definition, tool, model, effort, team } as recorded, so a requested-only model and a reported one never hash alike. Write it only when tool.name, a model and team are present and team.localChanges is false. It claims only that these recorded parts are equal, not that the whole environment was: the project's own config, the member's own config and hook context are outside it. project, teamai and driver are not hashed. The project commit changes with every unrelated change, so it is published next to the fingerprint for readers who need to split by it.

What gets published. The observation crosses into public records. Keep only the keys above, and drop any tool.version, model or effort value that is not shaped like a name, the way MODEL_NAME already filters models (records.ts:40-45). A path or free text sent by a driver is dropped, not published.

Scope

• Add src/agent-observation.ts with the type, its Zod schema, a function that builds the observation for a launch, the fingerprint, and a reader that turns an older string agent into { definition: { name } }. That reader returns a partial value, not a full observation. The module lives outside src/workflow/ because [Proposal] Score agent sessions and run benchmarks as workflows #1137 captures sessions with the same function.
• In the local driver, build the observation right before adapter.run (local-driver.ts:293), after the definition is loaded, and add model.reported and effort.reported from the result. A failed attempt reports its observation too. A step that launches no AI tool gets none.
• Add agent to the fields a report carries (step-state.ts, report), persisted with the pass like tool and model. Passes moved to passes or run.archive (feat(workflow): bounded loops, parallel for_each and list expressions #1148) keep theirs.
• Accept agent from any driver's report, filtered as above. The engine sets definition.name, teamai and driver itself and ignores a driver's values for them.
• In the run record, each step entry's agent becomes the observation of that pass. Keep the flat tool and model on the entry for current readers.
• Stop mixing requested and reported in the flat model: local-driver.ts:316 falls back from result.model to the definition's model. Report only what the tool reported. Update workflow-local-driver.test.ts:126-155, which asserts the fallback.
• Stop the background pull from changing a prepared step's checkout while it runs. A tool the local driver launches starts its own session, and its session-start hook runs teamai pull (pullHandler, hook-handlers.ts:113). Set TEAMAI_LAUNCHED_BY=workflow in the tool's environment, next to TEAMAI_WORKFLOW_RESULT (local-tool-adapter.ts:272). When it is set, pullHandler skips the pull only if the checkout's pull record shows a complete delivery for the tool being launched: a non-empty rev, a delivered baseline, no pushBaseRevs, and targets that include the tool. Otherwise it pulls as today, root seeding included, so a new worktree or a newly enabled tool still gets the team's assets, and the observation has no team. A newer commit on origin does not count as incomplete. [Proposal] Score agent sessions and run benchmarks as workflows #1137's judge sets the same variable to scorer, which always skips the pull.
• docs/guide/workflow.md and docs/guide/zh-CN/workflow.md: describe agent in the run records list.

Acceptance criteria

1. teamai workflow start <name> --driver local with a prompt step agent: reviewer on Claude publishes a run record whose entry for that pass has agent.definition { name: "reviewer", applied: "main" }, agent.tool.name claude, agent.tool.version equal to the number claude --version prints, agent.team.revision equal to the full commit of the checkout's last pulled revision, and agent.model.requested equal to the model in the deployed agent file.
2. The same step on Codex has applied: "prompt" and model.requested equal to the --model value the adapter passed.
3. A prompt step without agent: has no definition.
4. A tool output that names no model gives an entry with no agent.model.reported and no flat model, while agent.model.requested is still there.
5. After editing a delivered skill file in the checkout, the next run records team.localChanges: true and no fingerprint. After editing the deployed agent file's model, model.requested is absent.
6. A pull record with a non-empty pushBaseRevs, or without delivered, gives no team and no fingerprint.
7. Two runs of the same step, with the same tool, model and team revision and no local changes, have the same fingerprint. Changing the model gives a different one. A checkout with no pull record gives none.
8. With a new commit on the team repo's origin, a run in a checkout with a complete delivery record for its tool leaves lastPullRev and the delivered files unchanged. A worktree with no record, a record left incomplete by a pull, and a record whose targets omit the tool still go through the existing delivery when the tool starts, and their observation has no team or fingerprint.
9. A step a loop ran three times has three entries, each with its own agent.
10. A run record published before this change, with a string agent, still merges, and its agent reads as { definition: { name } }.
11. An external driver's report whose agent sets teamai, or a tool.version that is a file path, publishes the engine's teamai and no version.
12. A record written by this change is merged by the previous release's reports merge (mergeRecord keeps unknown values as they are, records.ts:227-230). Check it once by hand with npx teamai-cli@<previous> against the same reports branch, and note it in the PR. Resuming a run with an older CLI is not covered: its state schema drops unknown fields.

Test plan

• Unit tests for the observation builder with a temp checkout, a real state.json pull record and a fake tool executable that prints a version.
• Fingerprint tests: key order does not matter, each missing input removes it, requested and reported hash differently.
• Extend workflow-local-driver.test.ts for criteria 1 to 6 and 9, and the record tests for 10 and 11.
• E2E: extend workflow-records-reports-branch-1083.test.ts to read agent from the record on origin.
• One real-CLI run for the PR body with Claude: teamai pull, teamai workflow start <name> --driver local, then criterion 1 checked on the published record.

Watch out for

• [feat] Define the team revision once for run records, labels and snapshots #1163 and this issue both edit records.ts. Rebase onto whichever merges first.
• [feat] Tell a driver which payload fields next and report ignored #1164 lists the payload fields a driver sent and the engine ignored. Whichever of the two merges second adds agent to the accepted report fields.
• [feat] Add workflow workspaces, branches, and session continuation #1080 runs steps in worktrees. If its manager prepares each worktree through pull before the tool starts, as its comment on the worktree hook suggests, that worktree has a complete record and the tool's own pull is skipped. The mere existence of a record is not preparation. Either issue can merge first.
• [feat] Publish and resume complete workflow state across machines #1084 publishes state snapshots. The observation has no paths and nothing about the member's own config, so it can be published as it is.

Out of scope

• The member's own config (the tool's user instruction file and user MCP config). It is private, and nothing reads it yet.
• The text context hooks add at session start.
• Sessions outside workflows and showing the data ([Proposal] Score agent sessions and run benchmarks as workflows #1137).
• Telling a driver which model to use ([feat] Let a workflow choose the model of its prompt steps #1177).

Dependencies

• Blocked by: none
• Unblocks: [feat] Score a finished session on demand #1178, [feat] Run benchmark suites as workflows #1180