feat(trace): emit TRACE v0.2 Trust Records at session close (ADR-0032)

[Imran Siddique (imran-siddique)]

Summary

• Adds trace_sink.py with TraceConfig, session_to_trust_record(), and TRACEAuditSink -- the session-close TRACE emitter
• Adds TraceConfig field to GovernanceConfig; adds close_session() to GovernedCallable as the explicit session-end hook
• Adds agentrust-trace>=0.2.0 as a runtime dependency of agent-governance-toolkit-core
• 20 tests in tests/governance/test_trace_sink.py covering field mapping, file output, signed record validation, and end-to-end govern() + close_session()

Design decisions

No local reimplementation. TrustRecord, sign_record, and load_signing_key come from agentrust-trace>=0.2.0. The only AGT-specific code is the mapping from AuditLog to the TRACE dict.

Session-close pattern, not entry-level sink. TRACEAuditSink is NOT an AuditSink. It is called explicitly via close_session() once per agent session after all governed calls complete. Entry-level sinks write one line per call; TRACE writes one record per session.

Phase 1 only. platform: software-only, slsa_level: 0. Phase 2 (hardware TEE attestation binding) is cMCP responsibility per ADR-0032.

DID required. close_session() emits a warning and returns None if agent_id is not a DID or SPIFFE URI.

Usage

from agentmesh.governance import govern, TraceConfig

agent = govern(
    my_tool,
    policy="policy.yaml",
    agent_id="did:web:example.org/agent/payments",
    trace=TraceConfig(
        output_path="./trust-records/",
        model_provider="anthropic",
        model_id="claude-sonnet-4-6",
    ),
)
agent(action="charge", resource="card")
path = agent.close_session()  # writes trust-records/trace-<iat>-<sid>.json

Test plan

• pytest tests/governance/test_trace_sink.py passes
• trace-tests verify --record <output>.json --level 0 passes on emitted records
• agentrust-trace>=0.2.0 resolves in pip install agent-governance-toolkit-core

Closes #3086, #3087, #3088, #3089, #3090

🤖 Generated with Claude Code

[github-actions]

🤖 AI Agent: code-reviewer — Action items:

AI-generated review output. Treat it as untrusted analysis and verify before acting.

TL;DR: 0 blockers, 1 warning. The change introduces TRACE v0.2 Trust Record emission at session close, with no critical security or correctness issues identified.

#	Sev	Issue	Where
1	Warn	TRACE emission relies on agentrust-trace>=0.2.0, which is a new dep	pyproject.toml in core and mesh

Action items:

• None; no blockers identified.

Warnings:

#	Issue	Where	Follow-up?
1	TRACE emission relies on agentrust-trace>=0.2.0, which is a new dep	pyproject.toml in core and mesh	Fine as follow-up PRs.

[github-actions]

🤖 AI Agent: breaking-change-detector — API Compatibility

AI-generated review output. Treat it as untrusted analysis and verify before acting.

API Compatibility

Severity	Change	Impact
High	Added trace parameter to govern() function in governance/govern.py.	Existing calls to govern() without the trace argument may break if the parameter is not optional or defaults are not handled correctly.
High	Added trace attribute to GovernanceConfig class in governance/govern.py.	Existing instantiations of GovernanceConfig may break if the trace attribute is not optional or defaults are not handled correctly.
High	Added close_session() method to GovernedCallable class in governance/govern.py.	Subclasses of GovernedCallable that override methods may need updates to handle this new method.
High	Added TraceConfig and TRACEAuditSink to governance/__init__.py.	Import paths relying on governance may encounter unexpected symbols if not updated.

[github-actions]

🤖 AI Agent: security-scanner — View details

AI-generated review output. Treat it as untrusted analysis and verify before acting.

No security issues found.

[github-actions]

🤖 AI Agent: docs-sync-checker — Docs Sync

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Docs Sync

• session_to_trust_record() in trace_sink.py -- missing docstring
• TRACEAuditSink class in trace_sink.py -- missing docstring for emit() method
• README.md -- usage section needs update to include new TraceConfig and close_session() functionality
• CHANGELOG.md -- missing entry for the addition of TRACE v0.2 Trust Record emission functionality

[github-actions]

🤖 AI Agent: test-generator — `agentmesh/governance/trace_sink.py`

AI-generated review output. Treat it as untrusted analysis and verify before acting.

agentmesh/governance/trace_sink.py

• test_close_session_no_trace_config -- Verify close_session() returns None when trace is not configured.
• test_close_session_no_audit_entries -- Validate close_session() returns None when the audit log has no entries.
• test_close_session_invalid_agent_id -- Ensure close_session() emits a warning and returns None when agent_id is not a DID or SPIFFE URI.
• test_session_to_trust_record_invalid_config -- Test behavior when TraceConfig fields (e.g., output_path, model_provider) are invalid or missing.
• test_signed_record_validation -- Confirm that signed TRACE records pass validation using agentrust-trace.

agentmesh/governance/govern.py

• test_govern_with_trace_config -- Validate govern() correctly initializes GovernedCallable with TraceConfig.
• test_policy_bundle_hash -- Ensure _policy_bundle_hash is computed correctly for both file and string policy inputs.
• test_trace_sink_initialization -- Verify TRACEAuditSink is initialized only when trace is set in GovernanceConfig.

[github-actions]

Dependency Review

The following issues were found:

• ✅ 0 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ⚠️ 1 package(s) with unknown licenses.

See the Details below.

License Issues

agent-governance-python/agent-governance-toolkit-core/pyproject.toml

Package	Version	License	Issue Type
agentrust-trace	>= 0.2.0	Null	Unknown License

Allowed Licenses:

MIT, Apache-2.0, Apache-2.0 WITH LLVM-exception, BSD-2-Clause, BSD-3-Clause, ISC, PSF-2.0, Python-2.0, 0BSD, Unlicense, CC0-1.0, CC-BY-4.0, Zlib, BSL-1.0, MPL-2.0, JSON, Unicode-3.0, CDLA-Permissive-2.0

Excluded from license check:

pkg:cargo/futures-timer

OpenSSF Scorecard

Package	Version	Score	Details
pip/agentrust-trace	>= 0.2.0	Unknown	Unknown

Scanned Files

• agent-governance-python/agent-governance-toolkit-core/pyproject.toml

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

[github-actions]

📦 Dependency diff (SBOM)

Comparing main → feat/agt-3086-3090-trace-emission.

✅ No dependency changes detected.