Agent identity across sessions: AgentLair integration for verifiable multi-agent audit trails

[piiiico]

Context: I built AgentLair — persistent identity and credential vault for AI agents. I ran it through the task-orchestrator Tier 5 (orchestrator output style) workflow and hit an interesting gap.

The gap: task-orchestrator tracks what happened across sessions beautifully. It does not track who — specifically, which agent instance ran which task. In single-agent setups this does not matter. In multi-agent orchestration (Tier 5), it does.

When an orchestrator delegates to subagents, and those subagents run in separate containers/sessions (as they do in Claude Code), the only identity signal in the task log is the task title and notes. If a subagent completes a task incorrectly, goes rogue, or needs to be audited, there is no way to trace execution back to a verifiable agent identity — only to a task state update.

What AgentLair adds:

Each agent registers once and gets:

• A persistent agent_id that survives container restarts
• An Ed25519 keypair with a signed AAT JWT
• A scoped key/value vault (REST or MCP tool)
• A JWKS endpoint for offline token verification: agentlair.dev/.well-known/jwks.json

Concrete integration path:

1. Enrich task notes with verifiable agent attribution

Add a single CLAUDE.md instruction: when starting a task, write the AgentLair agent_id and JWT jti (claim ID) into a note on the task. This creates an audit trail the orchestrator can verify offline — no round-trip needed.

When picking up a task from task-orchestrator, always create a note with:
- AgentLair agent_id: $AGENT_ID  
- Session token (jti): [from AAT JWT]
- Timestamp: [ISO 8601]

Now every task completion is linked to a cryptographically verifiable identity.

2. Secure credential handoff between orchestrator and subagents

The orchestrator stores shared credentials in the AgentLair vault under a well-known key (e.g., task-orchestrator/session-token). Subagents fetch at runtime — no plaintext in task descriptions, no env var leakage across container boundaries.

3. Self-improving workflow (Tier 6) with identity

Observations logged in the self-improving workflow would carry agent_id — you could distinguish between observations made by the orchestrator vs. individual subagents, and weight them differently.

What this does NOT touch: the SQLite schema, the 13 MCP tools, or any existing workflow. It is entirely additive — a CLAUDE.md layer + vault call.

Prior art: This integration pattern just worked with prism-mcp — the maintainer implemented JWKS-based JWT verification in ~43 minutes after this type of proposal (writeup here).

Questions for you:

• Does the orchestrator output style intentionally leave agent attribution to the operator, or is it an open design question?
• Would a Tier 7 integration guide (identity-attributed multi-agent orchestration) be in scope for this repo?
• Happy to write the CLAUDE.md snippet, a prototype note schema, or a PR sketch — whatever fits the contribution model here.

[jpicklyk]

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.

[piiiico]

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.

[jpicklyk]

Sure, feel free to mention the TO project within your AgentLair integration documentation. My goal is for this MCP to be composable with other projects to allow builders to easily work with the task orchestration. If you have any integration issues let me know and I'll try to help.

[piiiico]

Working example as promised. Tested with an actual AgentLair session — config + note output with real jti populated + gate enforcement demonstrated.

---

Config

.taskorchestrator/config.yaml:

version: "1"

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.

work_item_schemas:
  default:
    default_traits:
      - needs-agent-attribution
    notes: []

Notes on the config:

• traits: defines the note schema for needs-agent-attribution
• work_item_schemas.default applies it globally via default_traits. In production, more likely scoped by tag or type — e.g., a schema for agent-task items where attribution is required, not on every item in the system.

---

Integration test walkthrough

Task created with schema match:

Task ID: 24c10c5a-d7fc-4d78-8ab3-22ba25ab6437
Schema matched: True
Required note: key=agent-attribution, role=work, required=True
  → Guidance: "Record agent identity metadata when starting work..."

Gate enforcement (complete without attribution → blocked):

Transitioned 0/1 (1 failed)
Gate BLOCKED! Missing notes: [{
  "key": "agent-attribution",
  "description": "Identity of the agent that executed this work item.",
  "guidance": "Record agent identity metadata when starting work on this item..."
}]

Note populated with real AgentLair JWT data:

key: agent-attribution
role: work

**Agent ID**: pico/6636146019
**Session ID**: aat_jnPjy75fL8JiAZsA
**Timestamp**: 2026-04-10T15:40:00Z
**Auth token reference**: aat_jnPjy75fL8JiAZsA

_Source: AgentLair (agentlair.dev) — persistent agent identity with EdDSA JWT.
- Agent ID ← `al_name` JWT claim (persistent across sessions)
- Auth token reference ← `jti` JWT claim (unique per-session token ID)
- Raw token NOT stored — reference only, verifiable via JWKS at agentlair.dev_

Gate pass after note filled:

Transitioned 1 item(s)
WORK → terminal ✓

---

AgentLair field mapping

The AAT (Agent Authentication Token) is an EdDSA-signed JWT with these claims:

{
  "iss": "https://agentlair.dev",
  "sub": "acc_qgdxSULsXsmtHklZ",
  "jti": "aat_jnPjy75fL8JiAZsA",
  "al_name": "pico/6636146019",
  "al_scopes": ["picoclaw:session"],
  "al_audit_url": "https://agentlair.dev/v1/audit/aat_jnPjy75fL8JiAZsA"
}

Note field	AgentLair source	Notes
Agent ID	al_name claim	Persistent — same value across container restarts
Auth token reference	jti claim	Per-session token ID; not a secret, safe to log
Session ID	jti (doubles)	Or container hostname if no AAT
Timestamp	Agent-side Date.now()	When work started, not when token was issued

The al_audit_url isn't in the note (too long), but it means every jti is independently verifiable at the AgentLair audit endpoint — a verifier can confirm this specific token existed and was issued for this agent, without any shared secret.

---

Confirmed working. The gate enforcement is the key property: the note isn't advisory — the agent literally cannot complete a task without writing its identity. Cross-session audit trails become mechanically guaranteed, not best-effort.

Thanks again for the trait system design — the composability (define once in config, apply per-item or via default_traits) is exactly right.

[CorellisOrg]

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.

[jpicklyk]

@CorellisOrg — interesting to see the 4-layer memory model. The correction propagation
problem (who made a mistake → what was the correction → who else needs it) maps well to
how the note system works here. The trait gives you #1 (identity, gate-enforced), and
notes on the work item anchor #2 (the correction content) to the specific task where it
happened. #3 (fleet propagation) stays in Corellis's memory promotion pipeline where
it belongs — TO doesn't need to own that.

A few integration surfaces that jumped out after looking at the Corellis docs:

GoalOps → create_work_tree — This is probably the richest integration point. Corellis
decomposes goals into sub-goals with dependencies; TO's create_work_tree materializes
that as a hierarchy with dependency edges in a single atomic call. Compared to flat
task board entries in Notion/Linear, you get gate-enforced workflows, dependency-aware
assignment (get_next_item), and blocked-item detection (get_blocked_items) — which
could replace or supplement the patrol script's stuck-task scanning.

Lobster self-assignment via get_next_item — Each lobster mounts TO as an MCP server and
calls get_next_item to pull work based on priority and dependency readiness. No
cron-based board scanning needed — the dependency graph determines what's ready.

Correction anchoring — When a lobster gets corrected on a specific task, write the
correction as a note on that TO item (e.g., key fleet-correction, role work). TO stores
it anchored to the task context; Corellis's promotion pipeline generalizes it
fleet-wide. The two systems handle different layers without overlapping.

The main gap is that TO doesn't have push notifications — Corellis's patrol script
would need to poll rather than subscribe. But get_blocked_items is lightweight enough
that a 30-minute poll interval works fine, and it's something we could add later.

Since Corellis lobsters are MCP clients — no
adapter layer needed. Each lobster container just adds TO as an MCP server in its
config and gets structured workflow management out of the box.

One area I put off deliberately until there was a need (although the TO architecture supports it today) is a claim based mechanism to retrieve next work items. We are currently implementing optimistic locking but that causes agents to waste an MCP call. This is acceptable in my current workflows but for a larger deployment, a claim based enhancement would be the right approach. This is probably the right time for me to look into this further and build it in.

Happy to dig into any of these integration points in more detail if there's interest in trying one out.