docs/specification.md

@@ -46183,6 +46183,19 @@ The `agents diagnostics` command provides a real-time health check combining all
 
 CleverAgents implements a defense-in-depth security model addressing five concerns: sandbox isolation, access control, prompt injection mitigation, secret management, and audit logging. The security model differs between local mode (single-user, trusted environment) and server mode (multi-user, potentially untrusted environment).
 
+**Security mode initialization contract**: The deployment mode (local vs. server) MUST be determined **once at service initialization time** and cached — never re-read from environment variables on each permission check. Reading `CLEVERAGENTS_SERVER_MODE` (or equivalent) dynamically on every call creates a TOCTOU (Time of Check to Time of Use) vulnerability: if any code path can modify `os.environ` during a session, the security mode can be changed mid-session, bypassing permission enforcement. The `PermissionService` (and any other service that gates behavior on deployment mode) MUST cache the mode at construction time:
+
+```python
+class PermissionService:
+    def __init__(self, ...):
+        # Determine mode ONCE at initialization — never re-read from environment
+        self._is_local_mode: bool = not _read_server_mode_from_env()
+
+    @property
+    def is_local_mode(self) -> bool:
+        return self._is_local_mode  # Return cached value — immutable after init
+```
+
 #### Sandbox Isolation
 
 The sandbox is the primary safety mechanism preventing untested changes from reaching production resources. Every plan's Execute phase runs within an isolated sandbox unless explicitly disabled by the automation profile (`require_sandbox: false`).