Python: isolate FIDES security state per session

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

FIDES middleware currently stores cumulative labels, hidden variables, audit records, and pending policy approvals on reusable middleware instances. Hosts that share one agent across conversations can therefore leak security state between sessions. This layer moves FIDES state into the owning AgentSession boundary while preserving standalone middleware behavior.

Description & Review Guide

• What are the major changes? Introduces session-scoped FIDES state and variable storage, binds label tracking and policy enforcement to each invocation's session, preserves configured middleware options when creating scoped instances, and updates the security samples to pass explicit sessions.
• What is the impact of these changes? Concurrent and restored conversations no longer share confidentiality, integrity, hidden variables, audit logs, or approval state through a reused agent instance.
• What do you want reviewers to focus on? Please focus on session restoration, omitted-session isolation, and preservation of caller-supplied middleware configuration.

Related Issue

Part of #7455. This is the bottom layer of a four-PR FIDES hardening stack.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and the title prefix in sync automatically.

[github-code-quality]

Code Coverage Overview

Languages: Python

Python / code-coverage/python

The overall line coverage in commit 124779d in the python-fides-session... branch is 91%. Line coverage data for the main branch is not yet available.

Show a line coverage summary of the most covered files.

File	main	python-fides-session... 124779d	+/-
packages/core/a...work/_skills.py	—	95%	—
packages/core/a...ework/_tools.py	—	94%	—
packages/core/a.../_compaction.py	—	94%	—
packages/core/a...rk/_sessions.py	—	94%	—
packages/core/a...ework/_types.py	—	93%	—
packages/core/a...bservability.py	—	93%	—
packages/openai..._chat_client.py	—	92%	—
packages/core/a...amework/_mcp.py	—	91%	—
packages/ag-ui/...i/_agent_run.py	—	91%	—
packages/core/a...ork/security.py	—	82%	—

---

_{Updated September 08, 2026 14:01 UTC}

[Copilot]

🔵 Needs a closer look

Security-critical state ownership, persistence, and approval replay behavior warrant final human validation.

Pull request overview

Moves FIDES security state into AgentSession to isolate conversations while supporting restoration and standalone middleware use.

Changes:

• Adds session-backed labels, variables, audit logs, and approvals.
• Uses task-local middleware and durable state serialization.
• Updates tests, documentation, and samples for explicit sessions.

File summaries

File	Description
python/packages/core/agent_framework/security.py	Implements session-scoped FIDES state.
python/packages/core/tests/test_security.py	Tests isolation, restoration, concurrency, and serialization.
python/samples/02-agents/security/repo_confidentiality_example.py	Uses an explicit session for auditing.
python/samples/02-agents/security/email_security_example.py	Reads the session-specific audit log.
python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md	Documents session-scoped state APIs.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (2 commit(s)): e912fce745d4, 53e1ce19f123
Model: gpt-5.6-sol-fast

Overview

The PR moves cumulative labels, hidden variables, audit records, and policy approvals into session-owned state, with strong owner checks, opaque JSON encoding, occurrence-aware approval binding, and explicit A/B/A restoration tests. The remaining risks are lifecycle gaps where session state is replaced or implicitly generated, unreclaimed terminal approvals, and compatibility failures for values that the previous standalone store or the framework's public Content contract permits.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
5 verified findings remained after source verification (5 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/security.py