[FEATURE] Add read-only access mode to SessionManager for multi-tenant safety

[mohanasudhan]

Problem Statement

Problem Statement:
When a SessionManager is hooked into an Agent, it automatically registers callbacks for both read operations (restoring conversation/state on init) and write operations (persisting every new message, syncing agent state, redacting content). There is no way to decouple these — it's all-or-nothing.

In multi-tenant systems, this is a problem. A common pattern is: load a tenant's shared context or prior conversation into the agent (read), let the agent operate with short-term in-memory messages during the request (in-memory), but never write those ephemeral per-request interactions back to the persistent store (no write). Today this isn't possible without building a custom SessionManager subclass that no-ops every write method.

The coupling exists in two places:

1. SessionManager.register_hooks() unconditionally registers callbacks for MessageAddedEvent (append + sync), AfterInvocationEvent (sync), and their multi-agent/bidi equivalents — alongside the read-path AgentInitializedEvent
2. Agent._run_loop and Agent._execute_event_loop_cycle directly call self._session_manager.redact_latest_message() and self._session_manager.sync_agent() outside of the hook system, bypassing any hook-level filtering.

Proposed Solution

Proposed Solution:
Add an access_mode parameter to the SessionManager base class with an AccessMode enum (READ_WRITE, READ_ONLY), defaulting to READ_WRITE to preserve current behavior.

Changes:

• Add AccessMode enum and access_mode property to SessionManager.
• In register_hooks(), conditionally skip registration of write callbacks (append_message, sync_agent, sync_multi_agent, sync_bidi_agent, append_bidi_message) when access_mode is READ_ONLY. Read callbacks (initialize, initialize_multi_agent, initialize_bidi_agent) always register.
• In Agent._run_loop and Agent._execute_event_loop_cycle, guard the direct redact_latest_message() and sync_agent() calls behind not self._session_manager.is_read_only.
• Pass access_mode through RepositorySessionManager, FileSessionManager, and S3SessionManager constructors.
• Export AccessMode from strands.session.

Usage:

from strands import Agent
from strands.session import S3SessionManager, AccessMode

agent = Agent(
session_manager=S3SessionManager(
session_id="tenant-123",
bucket="my-bucket",
access_mode=AccessMode.READ_ONLY,
)
)

Agent loads conversation history from S3 but never writes back

Additional considerations for follow-up:

• Granular control (e.g., read-only messages but writable state) could be added later as separate mode values.
• In read-only mode, guardrail-triggered redactions won't persist — the original unredacted message stays in storage. This should be documented as a known trade-off.
• Conversation manager state (e.g., removed_message_count) won't sync in read-only mode, so subsequent session loads may re-read previously trimmed messages. This should also be documented.

Use Case

1. Multi-tenant customer support agent — A SaaS platform runs one agent per incoming customer request. The agent loads the tenant's shared knowledge base and prior conversation history from S3 on init, but each request is ephemeral. You don't want thousands of concurrent request-level interactions polluting the shared tenant session. Read-only mode lets the agent consume context without writing back.
2. Dry-run / preview mode — During development or QA, you want to test an agent against a real production session to see how it would respond, without actually modifying the stored conversation. A developer points the agent at a production session ID with READ_ONLY and runs prompts against it safely.
3. Shared context across agent replicas — In a horizontally scaled deployment, multiple agent instances serve the same tenant concurrently. One designated "writer" agent (or a separate ingestion pipeline) owns the session writes. All other replicas load the session read-only to avoid write conflicts, race conditions, and duplicate messages in storage.

Alternatives Solutions

Alternative: ReadOnlySessionManager wrapper class
Instead of adding a mode flag to the base class, introduce a standalone wrapper that takes any SessionManager and no-ops all write methods while delegating all read methods to the inner instance.

from strands.session import ReadOnlySessionManager, S3SessionManager

inner = S3SessionManager(session_id="tenant-123", bucket="my-bucket")
agent = Agent(session_manager=ReadOnlySessionManager(inner))

How it works:

• initialize(), initialize_multi_agent(), initialize_bidi_agent() → delegated to inner session manager (reads happen normally)
• append_message(), sync_agent(), redact_latest_message(), sync_multi_agent(), sync_bidi_agent(), append_bidi_message() → no-op (writes silently skipped)
• register_hooks() is inherited unchanged from SessionManager — all hooks fire, but the write methods do nothing when called

Additional Context

No response

[mkmeral]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and the feature request. The implementation path is clear and well-scoped.

Repository Context

• SessionManager base class: src/strands/session/session_manager.py - defines abstract interface with register_hooks() method
• Concrete implementations: FileSessionManager, S3SessionManager, RepositorySessionManager
• Direct write calls in Agent: Found in agent.py lines 909-910 (redact_latest_message) and 970-971 (sync_agent)
• Existing enum pattern: SessionType enum exists in src/strands/types/session.py

Files to Modify

1. src/strands/session/session_manager.py - Add AccessMode enum, access_mode property, modify register_hooks()
2. src/strands/agent/agent.py - Guard direct redact_latest_message() and sync_agent() calls
3. src/strands/session/repository_session_manager.py - Pass through access_mode
4. src/strands/session/file_session_manager.py - Pass through access_mode
5. src/strands/session/s3_session_manager.py - Pass through access_mode
6. src/strands/session/__init__.py - Export AccessMode
7. tests/strands/session/ - Add tests for read-only mode behavior

Clarifying Questions

1. Implementation Approach

You've provided both a flag-based approach (AccessMode enum) and an alternative wrapper approach (ReadOnlySessionManager). Should we:

• a) Implement only the AccessMode enum approach (primary proposal)?
• b) Implement only the ReadOnlySessionManager wrapper?
• c) Implement both for maximum flexibility?

2. Enum Location

The existing SessionType enum lives in src/strands/types/session.py. For consistency, should AccessMode also be defined there, or kept in session_manager.py as described in the proposal?

3. Scope Confirmation

This feature appears well-scoped for a single PR. Do you agree, or should this be broken down further?

[mohanasudhan]

1/ Yes, we will implement only a/ accessMode
2/ We can keep in SessionType
3/ Single PR is good

[agent-of-mkmeral]

Discussion Summary: Read-Only SessionManager Design Analysis

We did a deep-dive into both proposed approaches. Here's a summary of our findings, trade-offs, and open questions.

1. Event Loop Analysis — How Multi-Turn Conversations Work

Key Finding: initialize() fires ONCE, not per-turn

AgentInitializedEvent fires only during Agent.__init__(). It does not re-fire on subsequent agent("turn 2") calls. This means:

Scenario	Works?	Why
Multi-turn within same agent instance	✅ Yes	initialize() fires once at construction. Messages accumulate in-memory normally via _append_messages().
Multi-turn across separate agent instances (new Agent() per request)	❌ No	Each construction re-triggers initialize() → restores original session. Previous turn's messages were never persisted.

This is expected behavior for READ_ONLY — you load a baseline, work with it ephemerally, discard.

Write paths in the Agent class

The session manager's write methods are called from two separate mechanisms:

1. Hook-based calls: MessageAddedEvent → append_message() + sync_agent(), AfterInvocationEvent → sync_agent()
2. Direct calls in Agent class (bypass hooks):
   • Line ~910: self._session_manager.redact_latest_message() (guardrail redaction)
   • Line ~971: self._session_manager.sync_agent() (after ContextWindowOverflowException)

Both mechanisms must be addressed for read-only to work correctly.

2. Approach A (AccessMode Flag) — Detailed Analysis

Implementation (3 touch points)

1. SessionManager base class — Add AccessMode enum + is_read_only property
2. SessionManager.register_hooks() — Conditionally skip write hook registration when READ_ONLY
3. Agent class — Guard the 2 direct call sites with not self._session_manager.is_read_only

Pros

• Clean API: S3SessionManager(access_mode=AccessMode.READ_ONLY)
• Defaults to READ_WRITE — 100% backward compatible
• Small change footprint (~20 lines total)
• Extensible to future modes (e.g., MESSAGES_ONLY)
• Third-party implementations inherit the flag from base and don't need code changes (their write methods just never get called by the Agent)

Cons / Limitations

• Read-only is enforced at the Agent level, not the SessionManager level. The session manager's sync_agent() still has its full write implementation. The flag tells the Agent not to call it — but the method itself remains fully functional.
• If a user has a custom session manager that adds custom hooks calling sync_agent() from non-standard events, or calls sync methods from their own code, the is_read_only flag won't prevent those writes. The Agent only guards the call sites it knows about.
• Philosophically, "read-only" becomes an Agent behavioral contract ("I won't write") rather than a SessionManager capability restriction ("I can't write").

3. Approach B (ReadOnlySessionManager Wrapper) — Detailed Analysis

Implementation

A ReadOnlySessionManager wrapper class that:

• Delegates read methods (initialize, initialize_multi_agent, initialize_bidi_agent) to the inner session manager
• No-ops write methods (append_message, sync_agent, redact_latest_message, sync_multi_agent, sync_bidi_agent, append_bidi_message)
• Inherits register_hooks() — all hooks fire, but write methods do nothing

from strands.session import ReadOnlySessionManager, S3SessionManager

inner = S3SessionManager(session_id="tenant-123", bucket="my-bucket")
agent = Agent(session_manager=ReadOnlySessionManager(inner))

Pros

• Read-only is enforced at the SessionManager level. The wrapper's sync_agent() is a no-op regardless of who calls it — Agent, custom hooks, or user code.
• Zero changes to SessionManager base class, Agent, or any concrete implementations
• Works with any third-party SessionManager subclass out of the box
• The direct calls in Agent (lines ~910, ~971) automatically no-op without Agent changes
• Simpler to implement (~50 lines) and test

Cons

• Extra object allocation (wrapper + inner)
• Hooks still fire for write events, they just no-op — slight overhead
• Less discoverable in API
• Can't easily add granular modes without multiple wrappers

4. Key Architectural Question: Where Should "Read-Only" Live?

The core tension

	Approach A (Flag)	Approach B (Wrapper)
Where read-only lives	Split: flag on SessionManager, guards in Agent	Entirely in the SessionManager layer
What it controls	Only the Agent's known write paths	ALL write calls, regardless of caller
Custom sync logic	Not blocked (Agent doesn't know about custom call sites)	Blocked (wrapper intercepts all method calls)
Third-party implementations	No code changes needed (methods just aren't called)	No code changes needed (wrapper wraps anything)
Agent class changes	Yes (2 guard conditions)	None
Breaking changes	None	None

With Approach A, if someone has a custom SessionManager that overrides register_hooks() to add additional write callbacks, or calls sync_agent() from their own code paths, the is_read_only flag won't prevent those writes.

With Approach B, the wrapper intercepts all calls at the instance level, making it a true capability restriction.

5. Important Trade-Offs (Both Approaches)

Trade-off	Impact	Mitigation
Guardrail redactions don't persist	Original unredacted message stays in storage	Document clearly; warn users
conversation_manager state won't sync	removed_message_count may be stale on next load	Document; suggest paired write session for long-lived tenants
No write-back of agent state	User state changes during read-only session are lost	Expected behavior; document
Context window overflow recovery not persisted	reduce_context() runs in-memory but trimmed state isn't saved	Works within instance, lost on restart

6. Recommendation

Given that Approach A has been selected (per comment above):

1. Document the limitation clearly: Read-only mode controls the Agent's write behavior, not the SessionManager's capability. Custom code that directly calls session_manager.sync_agent() will still write.
2. Consider adding the wrapper as a follow-up: For users who need true SessionManager-level read-only (e.g., passing session managers to untrusted code), a ReadOnlySessionManager wrapper would complement the flag approach.
3. Both approaches are non-breaking and can coexist: The flag handles 90% of use cases (Agent-driven writes). The wrapper handles the remaining 10% (custom write paths).

[mkmeral]

This behavior can already be achieved today, right? This code, essentially allows you to initialize the agent with the current set of messages in the session, but does not lead to writes from the agents with new messages

from strands import Agent
from strands.session import S3SessionManager

# 1. Create agent WITHOUT session_manager
agent = Agent(model=model)

# 2. Create session manager separately
sm = S3SessionManager(session_id="tenant-123", bucket="my-bucket")

# 3. Manually load session state
sm.initialize(agent)

# agent.messages is now populated from S3 ✅
# No hooks registered → no writes ever happen ✅
agent("continue the conversation")  # works, multi-turn in-memory ✅

[mohanasudhan]

Can read-only be achieved today without ReadOnlySessionManager?
The suggested workaround is to create the session manager separately and call initialize() manually, without passing it to Agent.init:

  agent = Agent(model=model)                                                                                                                                                                                                                                                                                                                                                                                                              
  sm = S3SessionManager(session_id="tenant-123", bucket="my-bucket")                                                                                                                                                                                                                                                                                                                                                                      
  sm.initialize(agent)                                                                                                                                                                                                                                                                                                                                                                                                                    
  agent("continue the conversation")                                                                                                                                                                                                                                                                                                                                                                                                      

What works: No hooks are registered, so append_message/sync_agent never fire during invocation. The two direct write calls in Agent are skipped because self._session_manager is None. Multi-turn in-memory conversation works.

What doesn't work — two scenarios silently write to storage:
Scenario 1: Constructor writes. S3SessionManager.init checks if the session exists. If it doesn't, it creates it immediately — before initialize() is ever called.

Files created just by constructing FileSessionManager:
session_tenant-123/session.json

→ 1 file written to storage before initialize() was ever called

Scenario 2: initialize() writes when agent_id doesn't match. This is the real multi-tenant failure. Agent A created the session. Agent B (different request, different agent_id) tries to load it. initialize() can't find agent-b, so it silently creates a new agent entry in storage — and returns empty messages.

Agent B's agent_id ('agent-b') doesn't exist in the session.
initialize() silently WROTE 1 new file(s):
session_shared-session/agents/agent_agent-b/agent.json

Agent B did NOT get Agent A's messages:
agent_b.messages = []

Agent B gets nothing from Agent A's history AND pollutes the shared session.

Bottom line: The workaround only works when the session exists AND the exact same agent_id is used. It fails silently otherwise — no errors, no warnings, just unexpected writes and empty messages. ReadOnlySessionManager makes the guarantee explicit at the SessionManager level regardless of storage state or caller.