Update docs: delegation API, scoping, Z3 redesign, security checklist

- ARCHITECTURE.md: container crate now four API layers (Task, Delegation,
  Builder, Forge) with key types updated
- README.md: delegation code example, system_prompt_fragment, is_scoped_within
- SECURITY.md: delegation security checklist (forward_api_key opt-in,
  is_scoped_within for privilege escalation, narrow_is_sufficient,
  tool name validation)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bryanegan

README.md

@@ -289,31 +289,36 @@ The `gleisner-lacerta` crate includes a Z3-powered policy lattice module (behind
 
 ## Container Library
 
-`gleisner-container` provides three API tiers:
+`gleisner-container` provides four API layers:
 
 ```rust
-// Task API — for agents and automation (declare needs, get minimal sandbox)
-let sb = TaskSandbox::new("/workspace")
+// Task API — declare needs, sandbox derives itself
+let task = TaskSandbox::new("/workspace")
     .needs_tools(["claude", "git"])
-    .needs_network(["api.anthropic.com"])
-    .build()?;
-
-// One-liner for Claude Code
-let sb = claude_code_sandbox("/workspace")?;
-
-// Builder API — for explicit control
+    .needs_network(["api.anthropic.com"]);
+println!("{}", task.explain());           // audit: why each permission
+println!("{}", task.system_prompt_fragment()); // for inner agent
+let sb = task.build()?;
+
+// Delegation API — Claude-to-Claude coordination
+let result = Delegation::to("/workspace")
+    .task("Fix the auth bug in src/auth.rs")
+    .context("JWT expiry check skipped on line 42")
+    .allow_tools(["cargo", "git"])
+    .forward_api_key()
+    .timeout(Duration::from_secs(300))
+    .build()?.execute()?;
+
+// Builder API — explicit control
 let mut sb = Sandbox::new();
-sb.rootfs()
-    .bind_ro_all(["/usr", "/lib"])
-    .project_dir("/workspace")
-    .allow_domains(["api.anthropic.com"])
-    .seccomp(SeccompPreset::Nodejs);
+sb.rootfs().project_dir("/workspace")
+    .allow_domains(["api.anthropic.com"]);
 
 // Forge API — auto-configure from package metadata
 let sb = ForgeComposition::new(report, project_dir).sandbox()?;
 ```
 
-Key capabilities: `explain()` audits why each permission was granted, `narrow()` compares declared vs observed usage to suggest tighter configs, `merge()` combines multi-agent requirements.
+Key capabilities: `explain()` audits grants, `narrow()` tightens configs from observed usage, `merge()` combines multi-agent needs, `is_scoped_within()` proves delegation safety, `system_prompt_fragment()` generates boundary-aware prompts for inner agents.
 
 ## Documentation
 

docs/ARCHITECTURE.md

@@ -64,7 +64,7 @@ The project is a Cargo workspace with ten crates. All version numbers and lint c
 | `gleisner-scapes` | Event infrastructure. Audit event types, broadcast channel event bus, JSONL audit log writer. | `EventBus`, `EventPublisher`, `AuditEvent`, `EventKind`, `JsonlWriter` |
 | `gleisner-forge` | Nickel package evaluation for minimal.dev. Content-addressed evaluation, topological dependency ordering, sandbox policy composition, Lean 4 proof verification (via `lake build`), CycloneDX 1.6 SBOM with proof-carrying Declarations, attestation metadata extraction. | `ForgeConfig`, `EvalContext`, `ComposedEnvironment`, `VerifyConfig`, `PackageVerification`, `PolicyComplianceProof` |
 | `gleisner-bridger` | SBOM generation. Cargo.lock parsing, CycloneDX 1.6 JSON output. | `Sbom`, `Component` |
-| `gleisner-container` | Container library with three API tiers: **Task API** (`TaskSandbox` — declare what the task needs, sandbox derives itself), **Builder API** (`Sandbox` — explicit mounts, namespaces, Landlock, seccomp), **Forge API** (`ForgeComposition` — auto-configure from package metadata). Features: `rootfs()` auto-discovery, `bind_ro_all()` batch mounts, `Stdio` control, timeouts, signal detection, `explain()` capability auditing, `narrow()` runtime tightening, `merge()` for multi-agent sandboxes, `claude_code_sandbox()` one-liner. Optional features: `forge` (package-aware), `lattice` (Z3 policy verification), `attestation`. | `TaskSandbox`, `Sandbox`, `Command`, `Output`, `Stdio`, `ForgeComposition`, `CapabilityExplanation`, `NarrowingReport`, `ObservedCapabilities` |
+| `gleisner-container` | Container library with four API layers: **Task API** (`TaskSandbox` — declare needs, sandbox derives itself; `explain()`/`narrow()`/`merge()`/`system_prompt_fragment()`), **Delegation API** (`Delegation` — Claude-to-Claude coordination with `is_scoped_within()` scope verification, `forward_api_key()` opt-in, context file injection), **Builder API** (`Sandbox` — explicit `rootfs()`/`bind_ro_all()`/`project_dir()`, `Stdio` control, timeouts, signal detection), **Forge API** (`ForgeComposition` — auto-configure from package metadata). Optional features: `forge`, `lattice` (Z3 verification), `audit` (JSONL observer), `attestation`. | `TaskSandbox`, `Delegation`, `Sandbox`, `Command`, `Output`, `ForgeComposition`, `ObservedCapabilities` |
 
 ### Dependency Graph
 

docs/SECURITY.md

@@ -529,6 +529,15 @@ Practical steps for users setting up Gleisner in a new environment.
       either task alone.
 - [ ] **Use Z3 `verify_against_policy()`** (with `lattice` feature) to
       formally prove a container config satisfies your security baseline.
+- [ ] **Use `is_scoped_within()`** before delegation to prove the inner
+      sandbox can't do anything the outer sandbox can't. Catches privilege
+      escalation in multi-agent setups.
+- [ ] **Use `Delegation` with `.forward_api_key()`** only when needed.
+      API key forwarding is opt-in — the inner process could exfiltrate it.
+- [ ] **Use `narrow_is_sufficient()`** to verify a tighter config still
+      covers observed behavior before deploying it.
+- [ ] **Validate tool names** — the task API rejects `/`, `\`, `;`, `'`,
+      backtick, and null characters in tool names to prevent injection.
 
 ### Verification