Thanks for the thoughtful writeup — the core observation is valid: in multi-agent orchestration, knowing which agent executed a task matters for audit trails, and we don't track that today.

How this maps to the existing schema system

Rather than adding instructions to CLAUDE.md (which gets loaded into every request regardless of relevance), the task-orchestrator already has a mechanism that fits this exactly: composable traits in .taskorchestrator/config.yaml.

Traits are opt-in note requirements that get attached to work items via tags. They're gate-enforced — advance_item won't let a work item progress past a phase unless the required notes are filled. This means attribution isn't advisory, it's structurally enforced.

Proposed: needs-agent-attribution trait

traits:
 needs-agent-attribution:
 notes:
 - key: agent-attribution
 role: work
 required: true
 description: "Identity of the agent that executed this work item."
 guidance: >
 Record agent identity metadata when starting work on this item.
 Structure:
 - **Agent ID**: persistent identifier (env var, MCP credential, or configured value)
 - **Session ID**: current session or container identifier
 - **Timestamp**: ISO 8601 start time
 - **Auth token reference**: JWT jti or equivalent claim ID (if available)
 Do NOT embed raw secrets or full tokens — only references/identifiers.

Why this works

1. Composable — operators opt in by tagging specific items with needs-agent-attribution, not globally on every item
2. Gate-enforced — items can't advance past the work phase without filling the note, unlike CLAUDE.md which is purely advisory
3. Zero code changes — pure config addition, works with the current release
4. Extensible — AgentLair users populate the guidance fields with JWT claims; operators without AgentLair use session IDs, container names, or whatever identity signal they have
5. Context-efficient — the guidance is only loaded when get_context or advance_item evaluates gates for tagged items, not on every request

This also complements the existing delegation-metadata note (orchestrator-side, records which model/isolation mode was used) — the trait adds the agent-side self-report.

Layered enforcement with hooks

The schema gate catches missing attribution at transition time — but that's late. The agent has already done all the work and only then discovers the note is missing. A SubagentStart hook layers enforcement earlier by reminding agents to write attribution before they start implementation:

{
 "hooks": [
 {
 "type": "command",
 "event": "SubagentStart",
 "command": "node hooks/inject-attribution-reminder.js",
 "description": "Remind subagents to fill agent-attribution note before starting work"
 }
 ]
}

The script checks whether the delegation prompt references an item tagged with needs-agent-attribution, and if so, injects additionalContext telling the agent to write the note first. Two enforcement layers:

• Hook (proactive) — "write your attribution note before you start"
• Schema gate (reactive) — blocks advance_item if they still forgot

JWT-based credential handoff

The vault/credential handoff aspect of AgentLair (storing shared credentials, subagents fetching at runtime) would require deeper integration beyond what the config schema can express — that would involve composing AgentLair's MCP server alongside task-orchestrator at the transport level, which is a user-side architecture decision rather than something we'd build into the schema system directly.

The trait system is exactly the right level to solve this — schema-enforced attribution is fundamentally different from advisory CLAUDE.md instructions. An agent that skips attribution in CLAUDE.md just leaves a gap; a gate that blocks advance_item makes the gap impossible to miss. The two-layer pattern (SubagentStart hook for proactive, gate for reactive) is clean.

The mapping to AgentLair fields is direct:

• Agent ID → AGENTLAIR_AGENT_ID env var (persistent, survives container restarts)
• Auth token reference → JWT jti claim from the AAT (references the issued token without embedding it — matches your guidance exactly)
• Session ID → jti doubles as session identifier, or container hostname for non-AAT setups

I will test this with an actual AgentLair session: stand up the trait, pick a task, populate the note with a real jti, and advance past the gate. I will post the working example here — config + note output — so you have something concrete before any docs consideration.

One ask: if it works as expected, would you be open to a mention in the AgentLair integration docs? Something like "task-orchestrator natively supports agent attribution via composable traits" with a link to this discussion. No reciprocal linking required on your end.

The identity gap you're describing gets even more interesting when you add fleet-wide learning to the picture.
In our setup (28 agents, OpenClaw-based), identity isn't just for audit — it's the foundation for correction propagation. When Agent-7 makes a mistake and gets corrected, we need to know:

1. WHO made the mistake (identity)
2. WHAT the correction was (content)
3. WHO ELSE might make the same mistake (fleet propagation)

The trait system @jpicklyk described is the right layer for #1. What we found missing in most frameworks is #3 — taking a correction applied to one agent and propagating it to others with similar roles or working on similar tasks.
We built this as a 4-layer memory system in Corellis (https://github.com/CorellisOrg/corellis): per-agent → per-team → fleet-wide → organizational. The fleet-wide layer is where corrections live after they're generalized. It's conceptually similar to what AgentLair does for identity, but for learned behaviors.