fix(core): preserve permission context when loading legacy v1 session state

[Letter2025]

fix(core): preserve permission context when loading legacy v1 session state

Closes #2768

Problem

ReActAgent.loadOrCreateAgentStateForSlot(...) loads a session's state in this order:

1. a new-format agent_state entry from the AgentStateStore,
2. else v1 legacy session keys (memory_messages / toolkit_activeGroups) via
   LegacyStateLoader,
3. else a fresh state built from the caller's parameters (freshState(permCtx, ...)).

Step 2 is leaky: LegacyStateLoader reconstructs the AgentState with only the legacy
conversation context (+ tool activation groups) and never sets permissionContext. Legacy
keys cannot carry one — the concept did not exist in v1 — so the reconstructed state silently
falls back to the default DEFAULT permission mode. This happens even though the caller
explicitly supplied a non-default permission context (for example BYPASS) that step 3 would
have preserved, and even though permCtx is already in scope at the call site.

Affected sessions: any session that still has v1-era keys but no new-format agent_state yet —
typically the first turn after a 1.x → 2.0 migration. The caller-configured permission mode is
silently downgraded, weakening permission semantics.

Change

• LegacyStateLoader.loadFromLegacySession(...) / loadFromLegacySessionWithPresence(...):
  new overloads accepting a PermissionContextState; when non-null it is attached to the
  reconstructed AgentState. The existing overloads are kept and delegate with null, so
  behaviour for callers without a specific permission context is unchanged.
• ReActAgent.loadOrCreateAgentStateForSlot(...): pass the in-scope permCtx into the legacy
  load, exactly like freshState already does.

Tests

LegacyStateLoaderTest (5 tests):

• supplied permission context is preserved (presence + non-presence variants);
• no permission context keeps the default mode (old overload behaviour);
• legacy messages and tool activation groups survive reconstruction alongside the permission
  context;
• no legacy keys reports found=false.

Checklist

• Conventional Commit message
• Unit tests included
• Backward compatible, no API breakage (old overloads kept)
• Full build verified locally (blocked by sandbox; CI runs mvn clean verify on Linux + Windows)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[dailingtao]

LGTM. The legacy v1 session loading path now correctly preserves the caller-supplied permission context while keeping the existing overload behavior backward compatible. The tests cover permission propagation, default behavior, and preservation of legacy session data.