docs(isolation): frame strategies as user-protection security boundary

docs/architecture/domain-model.md

@@ -164,14 +164,18 @@ A World may host a single agent in splendid isolation, or it may be a shared env
 - **Isolated World** - one agent, one Gateway. The agent has full run of the environment. Common for personal assistants or security-sensitive workloads.
 - **Shared World** - multiple agents on the same Gateway. Agents share the infrastructure but have separate workspaces, sessions, and memory. Communication between co-located agents is local and fast.
 
-### Agent Execution Strategies
+### Agent Isolation Strategies
 
-How an agent runs within its World is determined by its execution strategy (configured via the Descriptor). This controls the isolation boundary between the agent's code and the Gateway process:
+How an agent runs within its World is determined by its isolation strategy (configured via the Descriptor). **Isolation is a security boundary that protects the user from the agent** — it bounds what the agent can reach, do, and leak. Agents act on the user's behalf but cannot be fully trusted: they may be prompt-injected by hostile tool output, may make mistakes, or may simply be wrong. The isolation strategy determines the blast radius if any of those things happen, and it is the platform's primary defense against an agent accessing data it should not see or taking actions the user did not sanction.
 
-- **In-Process** - the agent runs directly inside the Gateway process. Fastest, no isolation. The default for simple deployments.
-- **Sandbox** - the agent runs in a restricted process with limited permissions. A middle ground between speed and safety.
-- **Container** - the agent runs in a Docker container. Strong isolation, suitable for untrusted or resource-intensive agents.
-- **Remote** - the agent delegates to a remote service. The Instance is a proxy; the real work happens elsewhere.
+The strategy spectrum runs from fastest/least-isolated to slowest/most-isolated:
+
+- **In-Process** - the agent runs directly inside the Gateway process. No security boundary; the agent shares memory, file handles, and OS identity with the Gateway. Fastest. The default for development and trusted single-user deployments.
+- **Sandbox** - the agent runs in a separate OS process communicating over IPC, confined by OS-level controls (reduced privileges, restricted file system view, syscall filtering). Protects the host process from agent crashes and limits what the agent can read or write directly. *Planned.*
+- **Container** - the agent runs in a Docker container. The agent sees only the volumes and network it is granted; the host file system and other agents are invisible. Suitable for untrusted agents and multi-tenant hosts. *Planned.*
+- **Remote** - the agent runs on a remote machine over HTTP/gRPC. The strongest isolation from user-local resources — local files, credentials, and processes are invisible unless explicitly forwarded. Appropriate for sensitive data domains and centrally-managed agent fleets. *Planned.*
+
+Additional strategies (e.g., hardened container runtimes like gVisor or Firecracker) may be added later via the same interface.
 
 Satellite nodes - remote processes that extend a World's capabilities without being full Worlds themselves - are considered part of the World they serve. A coding agent container spawned by a Gateway is a satellite of that Gateway's World, not a separate World.
 

docs/architecture/overview.md

@@ -179,7 +179,7 @@ Agents reference Locations by name (`@repo-botnexus`) rather than raw paths. Thi
 | Extension Point | Interface | Purpose |
 |----------------|-----------|---------|
 | **Channel Adapters** | `IChannelAdapter` | Connect to communication systems (SignalR, Telegram, TUI) |
-| **Isolation Strategies** | `IIsolationStrategy` | Agent execution environments (in-process, container, remote) |
+| **Isolation Strategies** | `IIsolationStrategy` | Security boundary between agent and user — controls agent blast radius (in-process, sandbox, container, remote) |
 | **Tools** | `IAgentTool` | Agent capabilities (file ops, web, MCP, skills, memory) |
 | **Hooks** | `IHookHandler` | Intercept tool execution (validation, audit, policy) |
 | **Prompt Sections** | `IPromptSection` | Customize system prompts |

docs/architecture/principles.md

@@ -393,19 +393,21 @@ AgentCore and Providers are **independent libraries** — they have no knowledge
 
 ### ADR-005: InProcess Default Isolation
 
-**Decision:** Default isolation strategy is in-process (shared memory).
+**Decision:** Default isolation strategy is in-process (shared memory). Other strategies — sandbox (separate OS process with IPC), container (Docker), and remote (HTTP/gRPC to another machine) — are planned and selected per-agent via `AgentDescriptor.IsolationStrategy`.
 
-**Rationale:**
+**Framing:** Isolation is a **security boundary that protects the user from the agent**. The strategy controls the blast radius if an agent is prompt-injected, executes hostile tool output, or simply makes a mistake. Stricter strategies reduce user exposure at the cost of speed and operational complexity.
+
+**Rationale for in-process as the default:**
 
 - Fastest (<10ms startup)
 - Simplest deployment (no Docker, no network)
-- Suitable for trusted agents
+- Suitable for trusted agents in single-user setups (e.g., a developer's local machine)
 
 **Implications:**
 
-- Security: agents share memory (not suitable for untrusted code)
-- Scaling: limited by single-process resources
-- Future: container/remote isolation for multi-tenancy
+- **Security:** in-process agents share memory and OS identity with the Gateway — they can reach anything the Gateway can. Not suitable for untrusted code or agents that handle data the user must not leak.
+- Scaling: limited by single-process resources.
+- For untrusted agents, multi-tenancy, or sensitive workloads, switch to `sandbox`, `container`, or `remote`.
 
 ---
 

src/gateway/BotNexus.Gateway.Abstractions/README.md

@@ -23,7 +23,7 @@ This is a leaf dependency — it references no other BotNexus packages.
 | `IChannelAdapter` | Channels | Pluggable adapter for external communication channels (Telegram, Discord, TUI, etc.). |
 | `IChannelDispatcher` | Channels | Callback interface for channel adapters to dispatch inbound messages into routing. |
 | `IChannelManager` | Channels | Read-only registry for looking up registered channel adapters. |
-| `IIsolationStrategy` | Isolation | Defines an execution environment for running agents (in-process, sandbox, container, remote). |
+| `IIsolationStrategy` | Isolation | Security boundary between agent and user — bounds what the agent can reach and leak (in-process, sandbox, container, remote). |
 | `IMessageRouter` | Routing | Routes inbound messages to the appropriate agent(s) based on targeting, session, and defaults. |
 | `IGatewayAuthHandler` | Security | Authenticates API and WebSocket requests; returns a caller identity. |
 | `ISessionStore` | Sessions | Persistence interface for gateway sessions (get, create, save, delete, list). |

src/gateway/BotNexus.Gateway.Contracts/Isolation/IIsolationStrategy.cs

@@ -4,23 +4,44 @@
 namespace BotNexus.Gateway.Abstractions.Isolation;
 
 /// <summary>
-/// Defines an execution environment strategy for running agent instances.
-/// Each strategy controls how an agent's code and state are isolated.
+/// Defines the execution boundary that contains an agent instance.
+/// Isolation is the security boundary between an agent and the user's environment —
+/// it controls what the agent can reach, do, and exfiltrate.
 /// </summary>
 /// <remarks>
+/// <para><b>Why isolation matters.</b> Agents act on behalf of users but cannot be
+/// fully trusted: they may be prompt-injected, may execute attacker-controlled tool
+/// output, or may simply make mistakes. The isolation strategy is the platform's
+/// primary defense — it determines blast radius if an agent is compromised. A
+/// stricter strategy reduces the user's exposure at the cost of speed and complexity.</para>
+///
 /// <para>Isolation strategies are registered by name and selected per-agent via
-/// <see cref="AgentDescriptor.IsolationStrategy"/>.</para>
-/// <para>Built-in strategies:</para>
+/// <see cref="AgentDescriptor.IsolationStrategy"/>. The strategy spectrum runs from
+/// fastest/least-isolated to slowest/most-isolated:</para>
+///
 /// <list type="bullet">
-///   <item><b>in-process</b> — Runs the agent directly in the Gateway process.
-///   Fastest, no isolation. Default for development and simple deployments.</item>
-///   <item><b>sandbox</b> — Runs the agent in a restricted AppDomain or process
-///   with limited permissions. Stub — Phase 2.</item>
-///   <item><b>container</b> — Runs the agent in a Docker container.
-///   Stub — Phase 2.</item>
-///   <item><b>remote</b> — Delegates to a remote agent service via HTTP/gRPC.
-///   Stub — Phase 2.</item>
+///   <item><b>in-process</b> — Runs the agent inside the Gateway process. No security
+///   boundary; the agent shares memory, file handles, and OS identity with the Gateway.
+///   Fastest. Default for development and trusted single-user deployments.</item>
+///
+///   <item><b>sandbox</b> — Runs the agent in a separate OS process communicating
+///   over IPC, confined by OS-level controls (e.g., reduced privileges, restricted
+///   file system view, syscall filtering). Protects the host process from agent
+///   crashes and limits what the agent can read/write directly. Planned.</item>
+///
+///   <item><b>container</b> — Runs the agent in a Docker container. The agent sees
+///   only the volumes and network it is granted; the host file system and other
+///   agents are invisible. Suitable for untrusted agents and multi-tenant hosts.
+///   Planned.</item>
+///
+///   <item><b>remote</b> — Delegates execution to a remote machine via HTTP/gRPC.
+///   The agent never runs on the user's machine at all. Strongest isolation from
+///   user-local resources; appropriate when the agent must not see local files or
+///   credentials. Planned.</item>
 /// </list>
+///
+/// <para>Additional strategies (e.g., hardened-container runtimes such as gVisor or
+/// Firecracker) may be added later via the same interface.</para>
 /// </remarks>
 public interface IIsolationStrategy
 {

src/gateway/BotNexus.Gateway/Isolation/ContainerIsolationStrategy.cs

@@ -5,11 +5,17 @@
 namespace BotNexus.Gateway.Isolation;
 
 /// <summary>
-/// Container isolation strategy — runs an agent in a Docker container.
+/// Container isolation strategy — runs the agent in a Docker container. The container
+/// boundary protects the user by hiding the host file system, network, and other agents;
+/// the agent sees only the volumes and ports explicitly granted to it.
 /// </summary>
 /// <remarks>
-/// Phase 2 stub. When implemented, this will pull/build an image, mount volumes for agent context,
-/// and communicate with the isolated agent process over gRPC/HTTP.
+/// Planned. When implemented, this will pull/build an image, mount only the volumes the
+/// agent needs (workspace, mounted secrets), restrict network egress per agent policy,
+/// and communicate with the isolated agent process over gRPC/HTTP. Suitable for untrusted
+/// agents, multi-tenant hosts, and workloads where a clean blast radius is required.
+/// Hardened container runtimes (e.g., gVisor, Firecracker, Kata Containers) may be exposed
+/// as separate strategies or as a configuration option on this strategy.
 /// </remarks>
 public sealed class ContainerIsolationStrategy : IIsolationStrategy
 {

src/gateway/BotNexus.Gateway/Isolation/InProcessIsolationStrategy.cs

@@ -38,12 +38,16 @@
 namespace BotNexus.Gateway.Isolation;
 
 /// <summary>
-/// In-process isolation strategy ΓÇö runs agents directly in the Gateway process
-/// by wrapping <see cref="BotNexus.Agent.Core.Agent"/>.
+/// In-process isolation strategy — runs the agent directly inside the Gateway process
+/// by wrapping <see cref="BotNexus.Agent.Core.Agent"/>. No security boundary: the agent
+/// shares memory, file handles, and OS identity with the Gateway and can reach anything
+/// the Gateway can reach.
 /// </summary>
 /// <remarks>
-/// This is the default and fastest strategy. No process or container boundaries.
-/// Suitable for development, testing, and trusted agent deployments.
+/// The default and fastest strategy. Appropriate for development, testing, and trusted
+/// single-user deployments where the operator and the agent are in the same trust domain.
+/// For untrusted agents, multi-tenant hosts, or workloads that handle data the user must
+/// not leak, choose <c>sandbox</c>, <c>container</c>, or <c>remote</c> instead.
 /// </remarks>
 public sealed class InProcessIsolationStrategy : IIsolationStrategy
 {

src/gateway/BotNexus.Gateway/Isolation/RemoteIsolationStrategy.cs

@@ -5,11 +5,18 @@
 namespace BotNexus.Gateway.Isolation;
 
 /// <summary>
-/// Remote isolation strategy — delegates execution to a remote agent service via HTTP/gRPC.
+/// Remote isolation strategy — delegates execution to a remote machine over HTTP/gRPC.
+/// The strongest isolation from user-local resources: the agent never runs on the user's
+/// machine, so local files, credentials, processes, and network surfaces are invisible
+/// to it unless explicitly forwarded.
 /// </summary>
 /// <remarks>
-/// Phase 2 stub. When implemented, this will forward prompts to a remote Gateway endpoint
-/// and relay remote responses and streaming events back to local callers.
+/// Planned. When implemented, this will forward prompts to a remote Gateway endpoint,
+/// relay streaming events back to local callers, and enforce that any resource the
+/// remote agent needs (workspace files, credentials, tool endpoints) be granted
+/// explicitly. Appropriate when the user requires that an agent never touch their
+/// machine — for sensitive data domains, or when delegating to a centrally-managed
+/// agent fleet.
 /// </remarks>
 public sealed class RemoteIsolationStrategy : IIsolationStrategy
 {

src/gateway/BotNexus.Gateway/Isolation/SandboxIsolationStrategy.cs

@@ -5,11 +5,17 @@
 namespace BotNexus.Gateway.Isolation;
 
 /// <summary>
-/// Sandbox isolation strategy — runs agents in a restricted process with limited permissions.
+/// Sandbox isolation strategy — runs the agent in a separate OS process communicating
+/// over IPC, confined by OS-level controls. The security boundary protects the user
+/// from agent crashes, restricts what the agent can read or write on the host, and
+/// limits the impact of prompt-injection or malicious tool output.
 /// </summary>
 /// <remarks>
-/// Phase 2 stub. When implemented, this will spawn a child process with reduced privileges,
-/// restricted file system access, and memory/CPU limits. Suitable for untrusted agents.
+/// Planned. When implemented, this will spawn a child process with reduced privileges,
+/// a restricted file-system view, memory/CPU limits, and syscall filtering (seccomp /
+/// AppArmor on Linux; Job Objects / AppContainer on Windows). Suitable for agents that
+/// should not share the Gateway's memory or full host access but do not need the
+/// overhead of a container.
 /// </remarks>
 public sealed class SandboxIsolationStrategy : IIsolationStrategy
 {

src/gateway/BotNexus.Gateway/README.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-This package implements the core BotNexus Gateway runtime. It orchestrates agent instances, manages message routing, handles session persistence, broadcasts activity events, and enforces isolation strategies. All functionality is exposed via interfaces in `BotNexus.Gateway.Abstractions`.
+This package implements the core BotNexus Gateway runtime. It orchestrates agent instances, manages message routing, handles session persistence, broadcasts activity events, and enforces isolation boundaries that protect users from agent actions. All functionality is exposed via interfaces in `BotNexus.Gateway.Abstractions`.
 
 This package depends on abstractions, session management, channel adapters, and agent providers, but contains no ASP.NET Core concerns — those are in `BotNexus.Gateway.Api`.
 

src/gateway/README.md

@@ -36,7 +36,7 @@ External Channel (Slack, Discord, etc.)
    └──────────┬──────────────┘
               ↓
    IIsolationStrategy
-   (in-process/sandbox/container)
+   (security boundary: in-process/sandbox/container/remote)
               ↓
    Agent executes with LLM provider
               ↓
@@ -49,7 +49,7 @@ External Channel (Slack, Discord, etc.)
 The Gateway is **fully extensible** through pluggable interfaces:
 
 ### 1. IIsolationStrategy
-Controls how agent code is executed and isolated.
+Controls the security boundary between the agent and the user's environment. Agents cannot be fully trusted (prompt-injection, hostile tool output, mistakes), so the isolation strategy bounds what the agent can reach and what it can leak. Pick a stricter strategy as the trust in the agent decreases.
 
 ```csharp
 public interface IIsolationStrategy
@@ -62,11 +62,11 @@ public interface IIsolationStrategy
 }
 ```
 
-**Built-in strategies:**
-- **in-process** — Runs agent directly in Gateway process (default, fastest)
-- **sandbox** — Restricted AppDomain or process with limited permissions (Phase 2)
-- **container** — Docker container isolation (Phase 2)
-- **remote** — HTTP/gRPC delegation to remote service (Phase 2)
+**Built-in strategies (fastest → most isolated):**
+- **in-process** — Runs agent directly in Gateway process. No security boundary; shared memory and OS identity. Default, fastest. Suitable for trusted single-user deployments.
+- **sandbox** — Separate OS process with IPC and OS-level confinement (reduced privileges, restricted file system, syscall filtering). Planned.
+- **container** — Docker container. Host file system, network, and other agents invisible unless granted. Planned.
+- **remote** — Agent runs on a remote machine via HTTP/gRPC. Strongest isolation from user-local resources. Planned.
 
 **To add a custom strategy:**
 1. Implement `IIsolationStrategy`