docs/specification.md

@@ -46531,11 +46531,11 @@ New backends are registered via configuration:
 
 The sandbox layer supports custom isolation strategies for specialized resource types:
 
-<div class="highlight"><pre><code><span style="color: magenta; font-weight: 600;">class</span> <span style="color: cyan; font-weight: 600;">SandboxStrategy</span>(<span style="color: cyan;">Protocol</span>):
+<div class="highlight"><pre><code><span style="color: magenta; font-weight: 600;">class</span> <span style="color: cyan; font-weight: 600;">SandboxStrategyProtocol</span>(<span style="color: cyan;">Protocol</span>):
     <span style="color: #888;">"""Interface for sandbox isolation strategies."""</span>
     <span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">create</span>(<span style="color: cyan;">self</span>, plan_id: <span style="color: cyan;">str</span>, resource: Resource) -> SandboxRef: ...
     <span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">read</span>(<span style="color: cyan;">self</span>, ref: SandboxRef, path: <span style="color: cyan;">str</span>) -> <span style="color: cyan;">bytes</span>: ...
-    <span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">write</span>(<span style="color: cyan;">self</span>, ref: SandboxRef, path: <span style="color: cyan;">str</span>, content: <span style="color: cyan;">bytes</span>) -> Change: ...
+    <span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">write</span>(<span style="color: cyan;">self</span>, ref: SandboxRef, path: <span style="color: cyan;">str</span>, content: <span style="color: cyan;">bytes</span>) -> DiffEntry: ...
     <span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">diff</span>(<span style="color: cyan;">self</span>, ref: SandboxRef) -> DiffView: ...
     <span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">commit</span>(<span style="color: cyan;">self</span>, ref: SandboxRef) -> <span style="color: cyan;">None</span>: ...
     <span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">rollback</span>(<span style="color: cyan;">self</span>, ref: SandboxRef) -> <span style="color: cyan;">None</span>: ...
@@ -46544,7 +46544,31 @@ The sandbox layer supports custom isolation strategies for specialized resource
     <span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">cleanup</span>(<span style="color: cyan;">self</span>, ref: SandboxRef) -> <span style="color: cyan;">None</span>: ...
 </code></pre></div>
 
-Custom strategies are mapped to resource types via the resource type configuration's `sandbox_strategy` field, or globally via `sandbox.strategy` config.
+Custom strategies are registered via configuration and then referenced by name in the resource type's `sandbox_strategy` field:
+
+```toml
+# config.toml — register the custom strategy
+[sandbox.custom_strategies.my-strategy]
+module = "cleveragents.extensions.my_module"
+class  = "MySandboxClass"
+```
+
+!!! warning "Module prefix security guard"
+    The sandbox plugin loader only imports modules whose fully-qualified
+    name starts with an allowed prefix. The default allowlist is
+    `("cleveragents.",)`, so the example above uses a
+    `cleveragents.extensions.*` module. If you need to load strategies
+    from another namespace (for example, `mycompany.sandbox.*`), extend
+    the registry's `allowed_prefixes` configuration per
+    [Development › Custom Sandbox Strategy Registration](development/custom_sandbox_strategy.md).
+    Otherwise the loader raises a `PluginLoadError` at startup.
+
+```yaml
+# resource-types/my-resource.yaml — reference the strategy by name
+resource_type:
+  name: local/my-resource
+  sandbox_strategy: my-strategy
+```
 
 #### ACMS Extensions