diff --git a/.cargo/audit.toml b/.cargo/audit.toml
index fd61035..8468d24 100644
--- a/.cargo/audit.toml
+++ b/.cargo/audit.toml
@@ -8,4 +8,12 @@ ignore = [
     # rsa 0.9.10 Marvin Attack (timing sidechannel). No fix available. Transitive
     # dependency via sqlx-mysql — Hadrian doesn't use RSA keys for MySQL auth.
     "RUSTSEC-2023-0071",
+    # hickory-proto 0.25.2 NSEC3 unbounded loop and O(n²) name-compression DoS.
+    # Pulled in only by microsandbox-network (the `runtime-microsandbox` feature,
+    # off in every default profile) for in-microVM DNS resolution behind the
+    # sandbox egress allowlist. microsandbox 0.4.5 pins the hickory 0.25.x line
+    # (see the dependency comment in Cargo.toml); a fixed 0.26.x requires a
+    # microsandbox bump. Hadrian's own resolver uses hickory-resolver 0.26.1.
+    "RUSTSEC-2026-0118",
+    "RUSTSEC-2026-0119",
 ]
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c61009c..d789090 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,7 +31,7 @@ jobs:
         run: rustup install nightly && rustup component add rustfmt --toolchain nightly
 
       - name: Install dependencies
-        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev tesseract-ocr tesseract-ocr-eng
+        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev libcap-ng-dev tesseract-ocr tesseract-ocr-eng
 
       - name: Cache cargo
         uses: Swatinem/rust-cache@v2
@@ -85,7 +85,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Install dependencies
-        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev tesseract-ocr tesseract-ocr-eng
+        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev libcap-ng-dev tesseract-ocr tesseract-ocr-eng
 
       - name: Cache cargo
         uses: Swatinem/rust-cache@v2
@@ -202,7 +202,7 @@ jobs:
 
       - name: Install dependencies (Linux full)
         if: matrix.features == 'full' && runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev
+        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev libcap-ng-dev
 
       - name: Install dependencies (macOS)
         if: runner.os == 'macOS'
@@ -436,7 +436,7 @@ jobs:
       - name: Install build deps for samael
         run: |
           sudo apt-get update
-          sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev pkg-config libssl-dev
+          sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libcap-ng-dev pkg-config libssl-dev
 
       - name: Regenerate Hadrian OpenAPI spec
         run: cargo run --release -- openapi --output openapi/hadrian.openapi.json
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b8eff20..db0395c 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -166,7 +166,7 @@ jobs:
 
       - name: Install dependencies (Linux full/standard)
         if: runner.os == 'Linux' && (contains(matrix.features, 'full') || contains(matrix.features, 'standard'))
-        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev libssl-dev pkg-config
+        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev libcap-ng-dev libssl-dev pkg-config
 
       - name: Install dependencies (macOS)
         if: runner.os == 'macOS'
@@ -301,7 +301,7 @@ jobs:
           shared-key: publish
 
       - name: Install dependencies
-        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev tesseract-ocr tesseract-ocr-eng
+        run: sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev libxmlsec1-dev libclang-dev libcap-ng-dev tesseract-ocr tesseract-ocr-eng
 
       - name: Publish to crates.io
         run: cargo publish --no-default-features --features headless --allow-dirty
diff --git a/CLAUDE.md b/CLAUDE.md
index 08abf38..0661045 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,15 +19,18 @@ Read files in `agent_instructions/` for detailed guidance on specific tasks:
 
 - `adding_admin_endpoint.md` — Admin endpoints and pagination patterns
 - `adding_frontend_tool.md` — Frontend tools
-- `adding_provider.md` — LLM providers
-- `architecture.md` — Multi-tenancy, auth, RBAC, SSO, request flow, RAG, chat modes, caching
+- `adding_provider.md` — LLM providers (and how server-side tools rewrite)
+- `adding_runtime.md` — Shell-tool runtime backends (passthrough, microsandbox, opensandbox, …)
+- `architecture.md` — Multi-tenancy, auth, RBAC, SSO, request flow, RAG, chat modes, caching, server-side tools
 - `ci_cd.md` — CI, release, and deploy pipelines
 - `configuration.md` — Config sections, feature flags, provider options
+- `containers.md` — Responses-API containers, shell tool, lifecycle, file staging
 - `database_changes.md` — Database migrations and schema changes
 - `documentation.md` — Documentation site, writing guidelines, Storybook embeds
 - `frontend_conventions.md` — Frontend conventions, accessibility (WCAG 2.1 AA)
 - `key_files.md` — Comprehensive file listing by subsystem
 - `modifying_chat_ui.md` — Chat UI performance (stores, selectors, memoization)
+- `responses_pipeline.md` — Foreground/background streaming pipeline, server-tool loop
 - `testing.md` — Provider e2e tests (wiremock), university E2E tests
 - `wasm.md` — WASM build architecture and frontend development
 
@@ -47,6 +50,7 @@ cargo clippy                    # Lint
 cargo +nightly fmt              # Format (requires nightly)
 cargo run                       # Run with default config (hadrian.toml)
 cargo run -- --config path.toml # Run with custom config
+docker build -t hadrian:local . # Build gateway image first (compose files use hadrian:local)
 cd deploy/tests && pnpm test    # E2E tests with testcontainers
 ```
 
@@ -61,6 +65,17 @@ Hierarchical profiles (default: `full`):
 - **`headless`** — full without embedded assets
 - **`wasm`** — Browser-only build (see `agent_instructions/wasm.md`)
 
+Shell-tool runtime backends are gated by their own feature flags (off by default in every
+profile so the heavy SDKs are opt-in):
+
+- **`runtime-microsandbox`** — pulls in the microsandbox SDK + microVM dependencies for the
+  in-process `microsandbox` runtime.
+- **`runtime-opensandbox`** — pulls in the HTTP client glue for the Alibaba OpenSandbox
+  Lifecycle API. No new system dependencies.
+
+`passthrough_openai` and `client_passthrough` runtimes are always available; they require no
+extra cargo features. See `agent_instructions/containers.md`.
+
 ```bash
 cargo build --no-default-features --features tiny       # Smallest binary
 cargo build --no-default-features --features minimal    # Fast compile
@@ -128,7 +143,7 @@ See `agent_instructions/architecture.md` for details on RBAC, SSO, RAG, chat mod
 ## Testing
 
 - Unit tests: same file as code (`#[cfg(test)]`)
-- E2E tests: `cd deploy/tests && pnpm test`
+- E2E tests: `docker build -t hadrian:local .` (first), then `cd deploy/tests && pnpm test`
 - Test both SQLite and PostgreSQL paths
 - See `agent_instructions/testing.md` for provider and university E2E tests
 
diff --git a/Cargo.lock b/Cargo.lock
index 605e0c8..fc896d4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -54,6 +54,12 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "aliasable"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "250f629c0161ad8107cf89319e990051fae62832fd343083bea452d93e2205fd"
+
 [[package]]
 name = "aligned"
 version = "0.4.3"
@@ -244,6 +250,45 @@ dependencies = [
  "stable_deref_trait",
 ]
 
+[[package]]
+name = "asn1-rs"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5493c3bedbacf7fd7382c6346bbd66687d12bbaad3a89a2d2c303ee6cf20b048"
+dependencies = [
+ "asn1-rs-derive",
+ "asn1-rs-impl",
+ "displaydoc",
+ "nom 7.1.3",
+ "num-traits",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
+[[package]]
+name = "asn1-rs-derive"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "965c2d33e53cb6b267e148a4cb0760bc01f4904c1cd4bb4002a085bb016d1490"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+ "synstructure 0.13.2",
+]
+
+[[package]]
+name = "asn1-rs-impl"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b18050c2cd6fe86c3a76584ef5e0baf286d038cda203eb6223df2cc413565f7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "assert-json-diff"
 version = "2.0.2"
@@ -265,9 +310,9 @@ dependencies = [
 
 [[package]]
 name = "astral-tokio-tar"
-version = "0.6.1"
+version = "0.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4ce73b17c62717c4b6a9af10b43e87c578b0cac27e00666d48304d3b7d2c0693"
+checksum = "cb50a7aae84a03bf55b067832bc376f4961b790c97e64d3eacee97d389b90277"
 dependencies = [
  "filetime",
  "futures-core",
@@ -595,7 +640,7 @@ dependencies = [
  "lru",
  "percent-encoding",
  "regex-lite",
- "sha2",
+ "sha2 0.10.9",
  "tracing",
  "url",
 ]
@@ -718,7 +763,7 @@ dependencies = [
  "p256",
  "percent-encoding",
  "ring",
- "sha2",
+ "sha2 0.10.9",
  "subtle",
  "time",
  "tracing",
@@ -753,7 +798,7 @@ dependencies = [
  "md-5",
  "pin-project-lite",
  "sha1",
- "sha2",
+ "sha2 0.10.9",
  "tracing",
 ]
 
@@ -1015,7 +1060,7 @@ dependencies = [
  "rustc_version",
  "serde",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "tokio",
  "tracing",
  "typespec",
@@ -1116,7 +1161,7 @@ checksum = "53d0c374feba1b9a59042a7c1cf00ce7c34b977b9134fe7c42b08e5183729f66"
 dependencies = [
  "paste",
  "roman-numerals-rs",
- "strum",
+ "strum 0.27.2",
  "unicode-normalization",
  "unscanny",
 ]
@@ -1136,13 +1181,32 @@ dependencies = [
  "thiserror 2.0.18",
 ]
 
+[[package]]
+name = "bincode"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36eaf5d7b090263e8150820482d5d93cd964a81e4019913c972f4edcc6edb740"
+dependencies = [
+ "bincode_derive",
+ "unty",
+]
+
+[[package]]
+name = "bincode_derive"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf95709a440f45e986983918d0e8a1f30a9b1df04918fc828670606804ac3c09"
+dependencies = [
+ "virtue",
+]
+
 [[package]]
 name = "bindgen"
 version = "0.72.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "cexpr",
  "clang-sys",
  "itertools 0.13.0",
@@ -1192,6 +1256,12 @@ version = "0.10.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e4b40c7323adcfc0a41c4b88143ed58346ff65a288fc144329c5c45e05d70c6"
 
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
 [[package]]
 name = "bitflags"
 version = "2.11.1"
@@ -1245,6 +1315,15 @@ dependencies = [
  "generic-array",
 ]
 
+[[package]]
+name = "block-buffer"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdd35008169921d80bc60d3d0ab416eecb028c4cd653352907921d95084790be"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "block-padding"
 version = "0.3.3"
@@ -1262,7 +1341,7 @@ checksum = "ee04c4c84f1f811b017f2fbb7dd8815c976e7ca98593de9c1e2afad0f636bff4"
 dependencies = [
  "async-stream",
  "base64 0.22.1",
- "bitflags",
+ "bitflags 2.11.1",
  "bollard-buildkit-proto",
  "bollard-stubs",
  "bytes",
@@ -1452,6 +1531,25 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "bzip2"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "49ecfb22d906f800d4fe833b6282cf4dc1c298f5057ca0b5445e5c209735ca47"
+dependencies = [
+ "bzip2-sys",
+]
+
+[[package]]
+name = "bzip2-sys"
+version = "0.1.13+1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "225bff33b2141874fe80d71e07d6eec4f85c5c216453dd96388240f96e1acc14"
+dependencies = [
+ "cc",
+ "pkg-config",
+]
+
 [[package]]
 name = "calamine"
 version = "0.34.0"
@@ -1470,6 +1568,25 @@ dependencies = [
  "zip 7.2.0",
 ]
 
+[[package]]
+name = "capng"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a26766f93f07f7e8b8309ed2824fa2a68f5d12d219de855e24688e9fbe89e85"
+dependencies = [
+ "bitflags 1.3.2",
+ "libc",
+]
+
+[[package]]
+name = "caps"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd1ddba47aba30b6a889298ad0109c3b8dcb0e8fc993b459daa7067d46f865e0"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "caseless"
 version = "0.2.2"
@@ -1609,13 +1726,40 @@ dependencies = [
  "windows-link 0.1.3",
 ]
 
+[[package]]
+name = "ciborium"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"
+dependencies = [
+ "ciborium-io",
+ "ciborium-ll",
+ "serde",
+]
+
+[[package]]
+name = "ciborium-io"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"
+
+[[package]]
+name = "ciborium-ll"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"
+dependencies = [
+ "ciborium-io",
+ "half",
+]
+
 [[package]]
 name = "cipher"
 version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
 dependencies = [
- "crypto-common",
+ "crypto-common 0.1.7",
  "inout",
 ]
 
@@ -1667,7 +1811,7 @@ version = "4.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1110bd8a634a1ab8cb04345d8d878267d57c3cf1b38d91b71af6686408bbca6a"
 dependencies = [
- "heck",
+ "heck 0.5.0",
  "proc-macro2",
  "quote",
  "syn 2.0.117",
@@ -1746,6 +1890,8 @@ dependencies = [
  "compression-core",
  "flate2",
  "memchr",
+ "zstd",
+ "zstd-safe",
 ]
 
 [[package]]
@@ -1818,6 +1964,12 @@ version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 
+[[package]]
+name = "const-oid"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
+
 [[package]]
 name = "const-random"
 version = "0.1.18"
@@ -1838,12 +1990,42 @@ dependencies = [
  "tiny-keccak",
 ]
 
+[[package]]
+name = "const_format"
+version = "0.2.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4481a617ad9a412be3b97c5d403fef8ed023103368908b9c50af598ff467cc1e"
+dependencies = [
+ "const_format_proc_macros",
+ "konst",
+]
+
+[[package]]
+name = "const_format_proc_macros"
+version = "0.2.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d57c2eccfb16dbac1f4e61e206105db5820c9d26c3c472bc17c774259ef7744"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-xid",
+]
+
 [[package]]
 name = "constant_time_eq"
 version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b"
 
+[[package]]
+name = "convert_case"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "633458d4ef8c78b72454de2d54fd6ab2e60f9e02be22f3c6104cdc8a4e0fceb9"
+dependencies = [
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "cookie"
 version = "0.18.1"
@@ -1921,7 +2103,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2fd92aca2c6001b1bf5ba0ff84ee74ec8501b52bbef0cac80bf25a6c1d87a83d"
 dependencies = [
  "crc",
- "digest",
+ "digest 0.10.7",
  "rustversion",
  "spin 0.10.0",
 ]
@@ -1990,6 +2172,33 @@ version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
+[[package]]
+name = "crossterm"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b"
+dependencies = [
+ "bitflags 2.11.1",
+ "crossterm_winapi",
+ "derive_more",
+ "document-features",
+ "mio",
+ "parking_lot",
+ "rustix",
+ "signal-hook",
+ "signal-hook-mio",
+ "winapi",
+]
+
+[[package]]
+name = "crossterm_winapi"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "acdd7c62a3665c7f6830a51635d9ac9b23ed385797f70a83bb8bafe9c572ab2b"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "crunchy"
 version = "0.2.4"
@@ -2028,6 +2237,15 @@ dependencies = [
  "typenum",
 ]
 
+[[package]]
+name = "crypto-common"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77727bb15fa921304124b128af125e7e3b968275d1b108b379190264f4423710"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "csv"
 version = "1.4.0"
@@ -2208,13 +2426,54 @@ version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7eed2c4702fa172d1ce21078faa7c5203e69f5394d48cc436d25928394a867a2"
 
+[[package]]
+name = "defmt"
+version = "0.3.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0963443817029b2024136fc4dd07a5107eb8f977eaf18fcd1fdeb11306b64ad"
+dependencies = [
+ "defmt 1.1.0",
+]
+
+[[package]]
+name = "defmt"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6e524506490a1953d237cb87b1cfc1e46f88c18f10a22dfe0f507dc6bfc7f7f"
+dependencies = [
+ "bitflags 1.3.2",
+ "defmt-macros",
+]
+
+[[package]]
+name = "defmt-macros"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0a27770e9c8f719a79d8b638281f4d828f77d8fd61e0bd94451b9b85e576a0b"
+dependencies = [
+ "defmt-parser",
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "defmt-parser"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10d60334b3b2e7c9d91ef8150abfb6fa4c1c39ebbcf4a81c2e346aad939fee3e"
+dependencies = [
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "der"
 version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f1a467a65c5e759bce6e65eaf91cc29f466cdc57cb65777bd646872a8a1fd4de"
 dependencies = [
- "const-oid",
+ "const-oid 0.9.6",
  "zeroize",
 ]
 
@@ -2224,11 +2483,25 @@ version = "0.7.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb"
 dependencies = [
- "const-oid",
+ "const-oid 0.9.6",
  "pem-rfc7468",
  "zeroize",
 ]
 
+[[package]]
+name = "der-parser"
+version = "9.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cd0a5c643689626bec213c4d8bd4d96acc8ffdb4ad4bb6bc16abf27d5f4b553"
+dependencies = [
+ "asn1-rs",
+ "displaydoc",
+ "nom 7.1.3",
+ "num-bigint",
+ "num-traits",
+ "rusticata-macros",
+]
+
 [[package]]
 name = "deranged"
 version = "0.5.8"
@@ -2301,6 +2574,29 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "derive_more"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134"
+dependencies = [
+ "derive_more-impl",
+]
+
+[[package]]
+name = "derive_more-impl"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb"
+dependencies = [
+ "convert_case",
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "syn 2.0.117",
+ "unicode-xid",
+]
+
 [[package]]
 name = "dialoguer"
 version = "0.12.0"
@@ -2320,12 +2616,23 @@ version = "0.10.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
- "block-buffer",
- "const-oid",
- "crypto-common",
+ "block-buffer 0.10.4",
+ "const-oid 0.9.6",
+ "crypto-common 0.1.7",
  "subtle",
 ]
 
+[[package]]
+name = "digest"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
+dependencies = [
+ "block-buffer 0.12.0",
+ "const-oid 0.10.2",
+ "crypto-common 0.2.1",
+]
+
 [[package]]
 name = "dirs"
 version = "6.0.0"
@@ -2441,7 +2748,7 @@ dependencies = [
  "base16ct",
  "crypto-bigint 0.4.9",
  "der 0.6.1",
- "digest",
+ "digest 0.10.7",
  "ff",
  "generic-array",
  "group",
@@ -2476,12 +2783,30 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "endian-type"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c34f04666d835ff5d62e058c3995147c06f42fe86ff053337632bca83e42702d"
+
 [[package]]
 name = "entities"
 version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b5320ae4c3782150d900b79807611a59a99fc9a1d61d686faafc24b93fc8d7ca"
 
+[[package]]
+name = "enum-as-inner"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1e6a265c649f3f5979b601d26f1d05ada116434c87741c9493cb56218f76cbc"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "equator"
 version = "0.4.2"
@@ -2515,7 +2840,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -2973,6 +3298,18 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "getset"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9cf0fc11e47561d47397154977bc219f4cf809b2974facc3ccb3b89e2436f912"
+dependencies = [
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "gif"
 version = "0.14.2"
@@ -3121,7 +3458,7 @@ dependencies = [
  "google-cloud-metadata",
  "google-cloud-token",
  "home",
- "jsonwebtoken",
+ "jsonwebtoken 9.3.1",
  "reqwest 0.12.28",
  "serde",
  "serde_json",
@@ -3394,10 +3731,11 @@ dependencies = [
  "ipnet",
  "js-sys",
  "jsonschema",
- "jsonwebtoken",
+ "jsonwebtoken 9.3.1",
  "kreuzberg",
  "metrics",
  "metrics-exporter-prometheus",
+ "microsandbox",
  "once_cell",
  "open",
  "openssl",
@@ -3410,6 +3748,8 @@ dependencies = [
  "redis",
  "regex",
  "reqwest 0.12.28",
+ "reqwest 0.13.2",
+ "rmcp",
  "rstest",
  "rust-embed",
  "rust_decimal",
@@ -3419,7 +3759,7 @@ dependencies = [
  "serde-wasm-bindgen",
  "serde_json",
  "serial_test",
- "sha2",
+ "sha2 0.10.9",
  "sqlx",
  "subtle",
  "temp-env",
@@ -3449,7 +3789,7 @@ dependencies = [
  "vaultrs",
  "wasm-bindgen",
  "wasm-bindgen-futures",
- "wasm-streams",
+ "wasm-streams 0.4.2",
  "web-sys",
  "wiremock",
 ]
@@ -3465,6 +3805,15 @@ dependencies = [
  "zerocopy",
 ]
 
+[[package]]
+name = "hash32"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47d60b12902ba28e2730cd37e95b8c9223af2808df9e902d4df49588d1470606"
+dependencies = [
+ "byteorder",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.12.3"
@@ -3541,11 +3890,27 @@ dependencies = [
  "fearless_simd",
 ]
 
+[[package]]
+name = "heapless"
+version = "0.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25ba4bd83f9415b58b4ed8dc5714c76e626a105be4646c02630ad730ad3b5aa4"
+dependencies = [
+ "hash32",
+ "stable_deref_trait",
+]
+
 [[package]]
 name = "heck"
-version = "0.5.0"
+version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
 name = "hermit-abi"
@@ -3559,6 +3924,25 @@ version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
 
+[[package]]
+name = "hickory-client"
+version = "0.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c466cd63a4217d5b2b8e32f23f58312741ce96e3c84bf7438677d2baff0fc555"
+dependencies = [
+ "cfg-if",
+ "data-encoding",
+ "futures-channel",
+ "futures-util",
+ "hickory-proto 0.25.2",
+ "once_cell",
+ "radix_trie",
+ "rand 0.9.4",
+ "thiserror 2.0.18",
+ "tokio",
+ "tracing",
+]
+
 [[package]]
 name = "hickory-net"
 version = "0.26.1"
@@ -3571,7 +3955,7 @@ dependencies = [
  "futures-channel",
  "futures-io",
  "futures-util",
- "hickory-proto",
+ "hickory-proto 0.26.1",
  "idna",
  "ipnet",
  "jni 0.22.4",
@@ -3583,6 +3967,34 @@ dependencies = [
  "url",
 ]
 
+[[package]]
+name = "hickory-proto"
+version = "0.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8a6fe56c0038198998a6f217ca4e7ef3a5e51f46163bd6dd60b5c71ca6c6502"
+dependencies = [
+ "async-trait",
+ "bytes",
+ "cfg-if",
+ "data-encoding",
+ "enum-as-inner",
+ "futures-channel",
+ "futures-io",
+ "futures-util",
+ "idna",
+ "ipnet",
+ "once_cell",
+ "rand 0.9.4",
+ "ring",
+ "rustls",
+ "thiserror 2.0.18",
+ "tinyvec",
+ "tokio",
+ "tokio-rustls",
+ "tracing",
+ "url",
+]
+
 [[package]]
 name = "hickory-proto"
 version = "0.26.1"
@@ -3612,7 +4024,7 @@ dependencies = [
  "cfg-if",
  "futures-util",
  "hickory-net",
- "hickory-proto",
+ "hickory-proto 0.26.1",
  "ipconfig",
  "ipnet",
  "jni 0.22.4",
@@ -3644,7 +4056,7 @@ version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e"
 dependencies = [
- "digest",
+ "digest 0.10.7",
 ]
 
 [[package]]
@@ -3728,6 +4140,15 @@ dependencies = [
  "itoa",
 ]
 
+[[package]]
+name = "http-auth"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "150fa4a9462ef926824cf4519c84ed652ca8f4fbae34cb8af045b5cbcaf98822"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "http-body"
 version = "0.4.6"
@@ -3780,6 +4201,15 @@ version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
+[[package]]
+name = "hybrid-array"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9155a582abd142abc056962c29e3ce5ff2ad5469f4246b537ed42c5deba857da"
+dependencies = [
+ "typenum",
+]
+
 [[package]]
 name = "hyper"
 version = "1.9.0"
@@ -3831,7 +4261,7 @@ dependencies = [
  "tokio",
  "tokio-rustls",
  "tower-service",
- "webpki-roots",
+ "webpki-roots 1.0.6",
 ]
 
 [[package]]
@@ -4074,6 +4504,26 @@ dependencies = [
  "quick-error",
 ]
 
+[[package]]
+name = "imago"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae7cfee876c698a1a2ed9c705ab18f21acbed82110f19b51cc458de73426fe2c"
+dependencies = [
+ "async-trait",
+ "bincode",
+ "cfg-if",
+ "libc",
+ "miniz_oxide",
+ "nix",
+ "page_size",
+ "rustc_version",
+ "tokio",
+ "tracing",
+ "vm-memory 0.18.0",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "imgref"
 version = "1.12.0"
@@ -4112,6 +4562,17 @@ dependencies = [
  "cfb 0.7.3",
 ]
 
+[[package]]
+name = "inherent"
+version = "1.0.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c727f80bfa4a6c6e2508d2f05b6f4bfce242030bd88ed15ae5331c5b5d30fba7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "inout"
 version = "0.1.4"
@@ -4164,6 +4625,15 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "ipnetwork"
+version = "0.21.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf370abdafd54d13e54a620e8c3e1145f28e46cc9d704bc6d94414559df41763"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "iri-string"
 version = "0.7.12"
@@ -4241,7 +4711,7 @@ dependencies = [
  "portable-atomic",
  "portable-atomic-util",
  "serde_core",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -4412,6 +4882,21 @@ dependencies = [
  "simple_asn1",
 ]
 
+[[package]]
+name = "jsonwebtoken"
+version = "10.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eba32bfb4ffdeaca3e34431072faf01745c9b26d25504aa7a6cf5684334fc4fc"
+dependencies = [
+ "base64 0.22.1",
+ "getrandom 0.2.17",
+ "js-sys",
+ "serde",
+ "serde_json",
+ "signature 2.2.0",
+ "zeroize",
+]
+
 [[package]]
 name = "kamadak-exif"
 version = "0.6.1"
@@ -4421,6 +4906,21 @@ dependencies = [
  "mutate_once",
 ]
 
+[[package]]
+name = "konst"
+version = "0.2.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "128133ed7824fcd73d6e7b17957c5eb7bacb885649bd8c69708b2331a10bcefb"
+dependencies = [
+ "konst_macro_rules",
+]
+
+[[package]]
+name = "konst_macro_rules"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4933f3f57a8e9d9da04db23fb153356ecaf00cbd14aee46279c33dc80925c37"
+
 [[package]]
 name = "kreuzberg"
 version = "4.7.4"
@@ -4493,7 +4993,7 @@ version = "4.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7b3bd3fcf58d80f760e3abcafe4da1c0e2c9b61998eec6f8694baae436a30ca5"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "bytemuck",
  "chrono",
  "console_error_panic_hook",
@@ -4525,6 +5025,27 @@ dependencies = [
  "zip 8.5.1",
 ]
 
+[[package]]
+name = "kvm-bindings"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b3c06ff73c7ce03e780887ec2389d62d2a2a9ddf471ab05c2ff69207cd3f3b4"
+dependencies = [
+ "vmm-sys-util",
+]
+
+[[package]]
+name = "kvm-ioctls"
+version = "0.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "333f77a20344a448f3f70664918135fddeb804e938f28a99d685bd92926e0b19"
+dependencies = [
+ "bitflags 2.11.1",
+ "kvm-bindings",
+ "libc",
+ "vmm-sys-util",
+]
+
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -4594,7 +5115,7 @@ version = "0.1.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e02f3bb43d335493c96bf3fd3a321600bf6bd07ed34bc64118e9293bdffea46c"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "libc",
  "plain",
  "redox_syscall 0.7.4",
@@ -4622,6 +5143,15 @@ dependencies = [
  "vcpkg",
 ]
 
+[[package]]
+name = "linux-loader"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "870c3814345f050991f99869417779f6062542bcf4ed81db7a1b926ad1306638"
+dependencies = [
+ "vm-memory 0.16.2",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -4671,7 +5201,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "73fdcbab5b237a03984f83b1394dc534e0b1960675c7f3ec4d04dccc9032b56d"
 dependencies = [
  "aes",
- "bitflags",
+ "bitflags 2.11.1",
  "cbc",
  "chrono",
  "ecb",
@@ -4688,7 +5218,7 @@ dependencies = [
  "rand 0.10.1",
  "rangemap",
  "rayon",
- "sha2",
+ "sha2 0.10.9",
  "stringprep",
  "thiserror 2.0.18",
  "time",
@@ -4720,6 +5250,12 @@ dependencies = [
  "nalgebra",
 ]
 
+[[package]]
+name = "managed"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ca88d725a0a943b096803bd34e73a4437208b6077654cc4ecb2947a5f91618d"
+
 [[package]]
 name = "markup5ever"
 version = "0.39.0"
@@ -4779,7 +5315,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
 dependencies = [
  "cfg-if",
- "digest",
+ "digest 0.10.7",
 ]
 
 [[package]]
@@ -4797,6 +5333,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
 [[package]]
 name = "metrics"
 version = "0.24.3"
@@ -4844,6 +5389,202 @@ dependencies = [
  "sketches-ddsketch",
 ]
 
+[[package]]
+name = "microsandbox"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "81251b9d0124a70d95e6f5f7211f4c45a71bc24d5d2f92c4aa016d464d06e0cf"
+dependencies = [
+ "astral-tokio-tar",
+ "async-compression",
+ "bytes",
+ "chrono",
+ "crossterm",
+ "dirs",
+ "docker_credential",
+ "flate2",
+ "futures",
+ "hex",
+ "libc",
+ "microsandbox-db",
+ "microsandbox-filesystem",
+ "microsandbox-image",
+ "microsandbox-migration",
+ "microsandbox-network",
+ "microsandbox-protocol",
+ "microsandbox-runtime",
+ "microsandbox-utils",
+ "nix",
+ "rand 0.10.1",
+ "reqwest 0.13.2",
+ "scopeguard",
+ "sea-orm",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tar",
+ "tempfile",
+ "thiserror 2.0.18",
+ "tokio",
+ "tracing",
+ "typed-builder",
+ "ureq",
+ "which",
+]
+
+[[package]]
+name = "microsandbox-db"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e0cf4b1e42563a39975ec111d0c5ca3b2d2648dcc445a97be6cebc1c8155308"
+dependencies = [
+ "async-trait",
+ "sea-orm",
+ "sqlx",
+ "tokio",
+ "tracing",
+]
+
+[[package]]
+name = "microsandbox-filesystem"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "efdf0dbee927e3e828860eddc6a3b234a8e793ccc23636ed9962c25b3955121e"
+dependencies = [
+ "libc",
+ "microsandbox-utils",
+ "msb_krun",
+ "scopeguard",
+ "tempfile",
+ "tracing",
+]
+
+[[package]]
+name = "microsandbox-image"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e99be592e0bf911930b31ae52864217c7d5d9b54e83cadd3b93d065ad23bed8d"
+dependencies = [
+ "astral-tokio-tar",
+ "async-compression",
+ "futures",
+ "hex",
+ "libc",
+ "microsandbox-utils",
+ "oci-client",
+ "oci-spec",
+ "rustls-pemfile",
+ "scopeguard",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "thiserror 2.0.18",
+ "tokio",
+ "tokio-util",
+ "tracing",
+ "xattr",
+]
+
+[[package]]
+name = "microsandbox-migration"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b72e5b5b2c5bdea11a4d50b540c69d20466b828311466713ed03b2e1720718a"
+dependencies = [
+ "sea-orm-migration",
+]
+
+[[package]]
+name = "microsandbox-network"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c09d853c6828f36c0e951dbf4190fc850fc5d4d976ebf5fcf26301d51d2c137"
+dependencies = [
+ "bytes",
+ "core-foundation 0.9.4",
+ "crossbeam-queue",
+ "dirs",
+ "futures",
+ "hickory-client",
+ "hickory-proto 0.25.2",
+ "ipnetwork",
+ "libc",
+ "lru",
+ "microsandbox-protocol",
+ "microsandbox-utils",
+ "msb_krun",
+ "parking_lot",
+ "pem",
+ "rcgen",
+ "resolv-conf",
+ "rustls",
+ "rustls-native-certs",
+ "rustls-pemfile",
+ "serde",
+ "smoltcp",
+ "system-configuration",
+ "thiserror 2.0.18",
+ "time",
+ "tokio",
+ "tokio-rustls",
+ "tracing",
+]
+
+[[package]]
+name = "microsandbox-protocol"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d655a839bc767cadbd769a15f35b3cedd23aac8c67a53ba36188822e6af193d4"
+dependencies = [
+ "chrono",
+ "ciborium",
+ "serde",
+ "serde_bytes",
+ "thiserror 2.0.18",
+ "tokio",
+]
+
+[[package]]
+name = "microsandbox-runtime"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed9eb5b8015349c86daf7346d6bfb7199b809109831e5d6d5ef9f5729c627fe1"
+dependencies = [
+ "bytes",
+ "chrono",
+ "clap",
+ "crossbeam-queue",
+ "libc",
+ "microsandbox-db",
+ "microsandbox-filesystem",
+ "microsandbox-network",
+ "microsandbox-protocol",
+ "microsandbox-utils",
+ "msb_krun",
+ "nix",
+ "rustls",
+ "sea-orm",
+ "serde",
+ "serde_json",
+ "tempfile",
+ "thiserror 2.0.18",
+ "tokio",
+ "tracing",
+]
+
+[[package]]
+name = "microsandbox-utils"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d62293decc8415995915c95f45b5e2425316e518f3ff90a28c23beecf945108"
+dependencies = [
+ "dirs",
+ "libc",
+ "reflink-copy",
+ "scopeguard",
+ "ureq",
+]
+
 [[package]]
 name = "mime"
 version = "0.3.17"
@@ -4883,6 +5624,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1"
 dependencies = [
  "libc",
+ "log",
  "wasi",
  "windows-sys 0.61.2",
 ]
@@ -4914,6 +5656,171 @@ dependencies = [
  "pxfm",
 ]
 
+[[package]]
+name = "msb_krun"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c29ba9c9c8a38cd001c0c9af16bd3c75be328ab8c95a3aa933b125c1d93f41c"
+dependencies = [
+ "crossbeam-channel",
+ "kvm-bindings",
+ "kvm-ioctls",
+ "libc",
+ "libloading 0.8.9",
+ "log",
+ "msb_krun_devices",
+ "msb_krun_hvf",
+ "msb_krun_polly",
+ "msb_krun_utils",
+ "msb_krun_vmm",
+ "vm-memory 0.16.2",
+]
+
+[[package]]
+name = "msb_krun_arch"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5eb4327e3efe423f3bcdca0390589193834b9f73eb54bb13b90f48f1755b499e"
+dependencies = [
+ "kvm-bindings",
+ "kvm-ioctls",
+ "libc",
+ "msb_krun_arch_gen",
+ "msb_krun_smbios",
+ "msb_krun_utils",
+ "vm-memory 0.16.2",
+ "vmm-sys-util",
+]
+
+[[package]]
+name = "msb_krun_arch_gen"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4bc7dbc08509138172ccd3b40df5c1501ad498ba12f2643eb013320205f9c987"
+
+[[package]]
+name = "msb_krun_cpuid"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "03d88b81a52ae5b3fe1afb1692b0785a4fe946c77bbc9e43a030e84e90627819"
+dependencies = [
+ "kvm-bindings",
+ "kvm-ioctls",
+ "vmm-sys-util",
+]
+
+[[package]]
+name = "msb_krun_devices"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0f6d808b3c4d5a7c24fba02a64f2f704da973cf6820deedd2811c2ec795b9fc"
+dependencies = [
+ "bitflags 1.3.2",
+ "capng",
+ "caps",
+ "crossbeam-channel",
+ "imago",
+ "kvm-bindings",
+ "kvm-ioctls",
+ "libc",
+ "libloading 0.8.9",
+ "log",
+ "lru",
+ "msb_krun_arch",
+ "msb_krun_hvf",
+ "msb_krun_polly",
+ "msb_krun_utils",
+ "nix",
+ "rand 0.9.4",
+ "virtio-bindings",
+ "vm-fdt",
+ "vm-memory 0.16.2",
+]
+
+[[package]]
+name = "msb_krun_hvf"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bce2de785e2cceda28ce03f20a9eeb895ac947ab66b09db31077a070bd6dda86"
+dependencies = [
+ "crossbeam-channel",
+ "libloading 0.8.9",
+ "log",
+ "msb_krun_arch",
+]
+
+[[package]]
+name = "msb_krun_kernel"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2047a3f886330138dd6a681ef96b0b2257b494f295535bdd641841068f5847bc"
+dependencies = [
+ "msb_krun_utils",
+ "vm-memory 0.16.2",
+]
+
+[[package]]
+name = "msb_krun_polly"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db57f147c6e1aca9a14d137ada76b6df78b538a0673d86b33652be78e9784499"
+dependencies = [
+ "libc",
+ "msb_krun_utils",
+]
+
+[[package]]
+name = "msb_krun_smbios"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c0c3a0923f194852028fd0e809a8d26c5465bc550f59c08b25bae5dd9885457"
+dependencies = [
+ "vm-memory 0.16.2",
+]
+
+[[package]]
+name = "msb_krun_utils"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9fbae5590c539ee8b9ed0e2d4c50c6ee5b546f03f9eb2408b885628514ddb9a6"
+dependencies = [
+ "bitflags 1.3.2",
+ "crossbeam-channel",
+ "kvm-bindings",
+ "libc",
+ "log",
+ "nix",
+ "vmm-sys-util",
+]
+
+[[package]]
+name = "msb_krun_vmm"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bd62153e5ffe89a76b775c89b9c01b65d38c67a32ca8d516a910d4cb497d367"
+dependencies = [
+ "bzip2",
+ "crossbeam-channel",
+ "flate2",
+ "kvm-bindings",
+ "kvm-ioctls",
+ "libc",
+ "linux-loader",
+ "log",
+ "msb_krun_arch",
+ "msb_krun_arch_gen",
+ "msb_krun_cpuid",
+ "msb_krun_devices",
+ "msb_krun_hvf",
+ "msb_krun_kernel",
+ "msb_krun_polly",
+ "msb_krun_utils",
+ "nix",
+ "vm-memory 0.16.2",
+ "vmm-sys-util",
+ "zstd",
+]
+
 [[package]]
 name = "multer"
 version = "3.1.0"
@@ -5020,6 +5927,28 @@ version = "1.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
 
+[[package]]
+name = "nibble_vec"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77a5d83df9f36fe23f0c3648c6bbb8b0298bb5f1939c8f2704431371f4b84d43"
+dependencies = [
+ "smallvec",
+]
+
+[[package]]
+name = "nix"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6"
+dependencies = [
+ "bitflags 2.11.1",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+ "memoffset",
+]
+
 [[package]]
 name = "no_std_io2"
 version = "0.9.3"
@@ -5152,49 +6081,131 @@ version = "0.1.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
 dependencies = [
- "num-traits",
+ "num-traits",
+]
+
+[[package]]
+name = "num-iter"
+version = "0.1.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1429034a0490724d0075ebb2bc9e875d6503c3cf69e235a8941aa757d83ef5bf"
+dependencies = [
+ "autocfg",
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-rational"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
+dependencies = [
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+ "libm",
+]
+
+[[package]]
+name = "num_cpus"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91df4bbde75afed763b708b7eee1e8e7651e02d97f6d5dd763e89367e957b23b"
+dependencies = [
+ "hermit-abi",
+ "libc",
+]
+
+[[package]]
+name = "oauth2"
+version = "5.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "51e219e79014df21a225b1860a479e2dcd7cbd9130f4defd4bd0e191ea31d67d"
+dependencies = [
+ "base64 0.22.1",
+ "chrono",
+ "getrandom 0.2.17",
+ "http 1.4.0",
+ "rand 0.8.5",
+ "serde",
+ "serde_json",
+ "serde_path_to_error",
+ "sha2 0.10.9",
+ "thiserror 1.0.69",
+ "url",
 ]
 
 [[package]]
-name = "num-iter"
-version = "0.1.45"
+name = "oci-client"
+version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1429034a0490724d0075ebb2bc9e875d6503c3cf69e235a8941aa757d83ef5bf"
+checksum = "1b7f8deaffcd3b0e3baf93dddcab3d18b91d46dc37d38a8b170089b234de5bb3"
 dependencies = [
- "autocfg",
- "num-integer",
- "num-traits",
+ "bytes",
+ "chrono",
+ "futures-util",
+ "http 1.4.0",
+ "http-auth",
+ "jsonwebtoken 10.4.0",
+ "lazy_static",
+ "oci-spec",
+ "olpc-cjson",
+ "regex",
+ "reqwest 0.13.2",
+ "serde",
+ "serde_json",
+ "sha2 0.10.9",
+ "thiserror 2.0.18",
+ "tokio",
+ "tracing",
+ "unicase",
 ]
 
 [[package]]
-name = "num-rational"
-version = "0.4.2"
+name = "oci-spec"
+version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
+checksum = "e8445a2631507cec628a15fdd6154b54a3ab3f20ed4fe9d73a3b8b7a4e1ba03a"
 dependencies = [
- "num-bigint",
- "num-integer",
- "num-traits",
+ "const_format",
+ "derive_builder 0.20.2",
+ "getset",
+ "regex",
+ "serde",
+ "serde_json",
+ "strum 0.27.2",
+ "strum_macros",
+ "thiserror 2.0.18",
 ]
 
 [[package]]
-name = "num-traits"
-version = "0.2.19"
+name = "oid-registry"
+version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+checksum = "a8d8034d9489cdaf79228eb9f6a3b8d7bb32ba00d6645ebd48eef4077ceb5bd9"
 dependencies = [
- "autocfg",
- "libm",
+ "asn1-rs",
 ]
 
 [[package]]
-name = "num_cpus"
-version = "1.17.0"
+name = "olpc-cjson"
+version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91df4bbde75afed763b708b7eee1e8e7651e02d97f6d5dd763e89367e957b23b"
+checksum = "696183c9b5fe81a7715d074fd632e8bd46f4ccc0231a3ed7fc580a80de5f7083"
 dependencies = [
- "hermit-abi",
- "libc",
+ "serde",
+ "serde_json",
+ "unicode-normalization",
 ]
 
 [[package]]
@@ -5230,7 +6241,7 @@ version = "0.10.77"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bfe4646e360ec77dff7dde40ed3d6c5fee52d156ef4a62f53973d38294dad87f"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "cfg-if",
  "foreign-types",
  "libc",
@@ -5362,12 +6373,45 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
 
+[[package]]
+name = "ordered-float"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7bb71e1b3fa6ca1c61f383464aaf2bb0e2f8e772a1f01d486832464de363b951"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "org"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cfdf547b633735ad9d67353aba48b3e685ab5ffb3195aaa9a1b1d8613e11b98c"
 
+[[package]]
+name = "ouroboros"
+version = "0.18.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0f050db9c44b97a94723127e6be766ac5c340c48f2c4bb3ffa11713744be59"
+dependencies = [
+ "aliasable",
+ "ouroboros_macro",
+ "static_assertions",
+]
+
+[[package]]
+name = "ouroboros_macro"
+version = "0.18.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c7028bdd3d43083f6d8d4d5187680d0d3560d54df4cc9d752005268b41e64d0"
+dependencies = [
+ "heck 0.4.1",
+ "proc-macro2",
+ "proc-macro2-diagnostics",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "outref"
 version = "0.5.2"
@@ -5382,7 +6426,17 @@ checksum = "51f44edd08f51e2ade572f141051021c5af22677e42b7dd28a88155151c33594"
 dependencies = [
  "ecdsa",
  "elliptic-curve",
- "sha2",
+ "sha2 0.10.9",
+]
+
+[[package]]
+name = "page_size"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d5b2194ed13191c1999ae0704b7839fb18384fa22e49b57eeaa97d79ce40da"
+dependencies = [
+ "libc",
+ "winapi",
 ]
 
 [[package]]
@@ -5614,7 +6668,7 @@ version = "0.18.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "crc32fast",
  "fdeflate",
  "flate2",
@@ -5727,6 +6781,19 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "proc-macro2-diagnostics"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af066a9c399a26e020ada66a034357a868728e72cd426f3adcd35f80d88d88c8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+ "version_check",
+ "yansi",
+]
+
 [[package]]
 name = "profiling"
 version = "1.0.17"
@@ -5804,7 +6871,7 @@ version = "0.13.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7c3a14896dfa883796f1cb410461aef38810ea05f2b2c33c5aded3649095fdad"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "getopts",
  "memchr",
  "pulldown-cmark-escape",
@@ -5948,6 +7015,16 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
 
+[[package]]
+name = "radix_trie"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c069c179fcdc6a2fe24d8d18305cf085fdbd4f922c041943e203685d6a1c58fd"
+dependencies = [
+ "endian-type",
+ "nibble_vec",
+]
+
 [[package]]
 name = "rand"
 version = "0.8.5"
@@ -6114,7 +7191,7 @@ version = "11.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "498cd0dc59d73224351ee52a95fee0f1a617a2eae0e7d9d720cc622c73a54186"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
 ]
 
 [[package]]
@@ -6143,6 +7220,20 @@ dependencies = [
  "crossbeam-utils",
 ]
 
+[[package]]
+name = "rcgen"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75e669e5202259b5314d1ea5397316ad400819437857b90861765f24c4cf80a2"
+dependencies = [
+ "pem",
+ "ring",
+ "rustls-pki-types",
+ "time",
+ "x509-parser",
+ "yasna",
+]
+
 [[package]]
 name = "redis"
 version = "0.32.7"
@@ -6175,7 +7266,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
 ]
 
 [[package]]
@@ -6184,7 +7275,7 @@ version = "0.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f450ad9c3b1da563fb6948a8e0fb0fb9269711c9c73d9ea1de5058c79c8d643a"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
 ]
 
 [[package]]
@@ -6232,6 +7323,18 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "reflink-copy"
+version = "0.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13362233b147e57674c37b802d216b7c5e3dcccbed8967c84f0d8d223868ae27"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "rustix",
+ "windows",
+]
+
 [[package]]
 name = "regex"
 version = "1.12.3"
@@ -6323,9 +7426,9 @@ dependencies = [
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
- "wasm-streams",
+ "wasm-streams 0.4.2",
  "web-sys",
- "webpki-roots",
+ "webpki-roots 1.0.6",
 ]
 
 [[package]]
@@ -6336,9 +7439,11 @@ checksum = "ab3f43e3283ab1488b624b44b0e988d0acea0b3214e694730a055cb6b2efa801"
 dependencies = [
  "base64 0.22.1",
  "bytes",
+ "encoding_rs",
  "futures-channel",
  "futures-core",
  "futures-util",
+ "h2",
  "http 1.4.0",
  "http-body 1.0.1",
  "http-body-util",
@@ -6348,6 +7453,7 @@ dependencies = [
  "hyper-util",
  "js-sys",
  "log",
+ "mime",
  "native-tls",
  "percent-encoding",
  "pin-project-lite",
@@ -6362,12 +7468,14 @@ dependencies = [
  "tokio",
  "tokio-native-tls",
  "tokio-rustls",
+ "tokio-util",
  "tower",
  "tower-http",
  "tower-service",
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
+ "wasm-streams 0.5.0",
  "web-sys",
 ]
 
@@ -6437,6 +7545,30 @@ dependencies = [
  "syn 1.0.109",
 ]
 
+[[package]]
+name = "rmcp"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0810a9f717d9828f475fe1f629f4c305c8464b7f496c3a854b58d29e65f4058e"
+dependencies = [
+ "async-trait",
+ "chrono",
+ "futures",
+ "http 1.4.0",
+ "oauth2",
+ "pin-project-lite",
+ "reqwest 0.13.2",
+ "serde",
+ "serde_json",
+ "sse-stream",
+ "thiserror 2.0.18",
+ "tokio",
+ "tokio-stream",
+ "tokio-util",
+ "tracing",
+ "url",
+]
+
 [[package]]
 name = "rmp"
 version = "0.8.15"
@@ -6483,8 +7615,8 @@ version = "0.9.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8573f03f5883dcaebdfcf4725caa1ecb9c15b2ef50c43a07b816e06799bb12d"
 dependencies = [
- "const-oid",
- "digest",
+ "const-oid 0.9.6",
+ "digest 0.10.7",
  "num-bigint-dig",
  "num-integer",
  "num-traits",
@@ -6559,7 +7691,7 @@ checksum = "5bcdef0be6fe7f6fa333b1073c949729274b05f123a0ad7efcb8efd878e5c3b1"
 dependencies = [
  "globset",
  "mime_guess",
- "sha2",
+ "sha2 0.10.9",
  "walkdir",
 ]
 
@@ -6612,6 +7744,15 @@ dependencies = [
  "semver",
 ]
 
+[[package]]
+name = "rusticata-macros"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "faf0c4a6ece9950b9abdb62b1cfcf2a68b3b67a10ba445b3bb85be2a293d0632"
+dependencies = [
+ "nom 7.1.3",
+]
+
 [[package]]
 name = "rustify"
 version = "0.6.1"
@@ -6652,11 +7793,11 @@ version = "1.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -6687,6 +7828,15 @@ dependencies = [
  "security-framework",
 ]
 
+[[package]]
+name = "rustls-pemfile"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dce314e5fee3f39953d46bb63bb8a46d40c2f8fb7cc5a3b6cab2bde9721d6e50"
+dependencies = [
+ "rustls-pki-types",
+]
+
 [[package]]
 name = "rustls-pki-types"
 version = "1.14.0"
@@ -6715,7 +7865,7 @@ dependencies = [
  "security-framework",
  "security-framework-sys",
  "webpki-root-certs",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -6850,25 +8000,169 @@ dependencies = [
 name = "schemars_derive"
 version = "0.8.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32e265784ad618884abaea0600a9adf15393368d840e0222d101a072f3f7534d"
+checksum = "32e265784ad618884abaea0600a9adf15393368d840e0222d101a072f3f7534d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde_derive_internals",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "sdd"
+version = "3.0.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "490dcfcbfef26be6800d11870ff2df8774fa6e86d047e3e8c8a76b25655e41ca"
+
+[[package]]
+name = "sea-bae"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f694a6ab48f14bc063cfadff30ab551d3c7e46d8f81836c51989d548f44a2a25"
+dependencies = [
+ "heck 0.4.1",
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "sea-orm"
+version = "1.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2dc312fedd460a47ea563911761d254a84e7b51d8cc73ec92c929e78f33fa957"
+dependencies = [
+ "async-stream",
+ "async-trait",
+ "chrono",
+ "derive_more",
+ "futures-util",
+ "log",
+ "ouroboros",
+ "sea-orm-macros",
+ "sea-query",
+ "sea-query-binder",
+ "serde",
+ "sqlx",
+ "strum 0.26.3",
+ "thiserror 2.0.18",
+ "tracing",
+ "url",
+]
+
+[[package]]
+name = "sea-orm-cli"
+version = "1.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da80ebcdb44571e86f03a2bdcb5532136a87397f366f38bbce64673fc5e6a450"
+dependencies = [
+ "chrono",
+ "glob",
+ "regex",
+ "sea-schema",
+ "sqlx",
+ "tokio",
+ "tracing",
+ "tracing-subscriber",
+ "url",
+]
+
+[[package]]
+name = "sea-orm-macros"
+version = "1.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b9a3f90e336ec74803e8eb98c61bc98754c1adfba3b4f84d946237b752b1c88"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "sea-bae",
+ "syn 2.0.117",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sea-orm-migration"
+version = "1.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07c577f2959277e936c1d08109acd1e08fc36a95ef29ec028190ba82cad8f96e"
+dependencies = [
+ "async-trait",
+ "sea-orm",
+ "sea-orm-cli",
+ "sea-schema",
+ "tracing",
+ "tracing-subscriber",
+]
+
+[[package]]
+name = "sea-query"
+version = "0.32.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a5d1c518eaf5eda38e5773f902b26ab6d5e9e9e2bb2349ca6c64cf96f80448c"
+dependencies = [
+ "chrono",
+ "inherent",
+ "ordered-float",
+ "sea-query-derive",
+]
+
+[[package]]
+name = "sea-query-binder"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b0019f47430f7995af63deda77e238c17323359af241233ec768aba1faea7608"
+dependencies = [
+ "chrono",
+ "sea-query",
+ "sqlx",
+]
+
+[[package]]
+name = "sea-query-derive"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bae0cbad6ab996955664982739354128c58d16e126114fe88c2a493642502aab"
 dependencies = [
+ "darling 0.20.11",
+ "heck 0.4.1",
  "proc-macro2",
  "quote",
- "serde_derive_internals",
  "syn 2.0.117",
+ "thiserror 2.0.18",
 ]
 
 [[package]]
-name = "scopeguard"
-version = "1.2.0"
+name = "sea-schema"
+version = "0.16.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+checksum = "2239ff574c04858ca77485f112afea1a15e53135d3097d0c86509cef1def1338"
+dependencies = [
+ "futures",
+ "sea-query",
+ "sea-query-binder",
+ "sea-schema-derive",
+ "sqlx",
+]
 
 [[package]]
-name = "sdd"
-version = "3.0.10"
+name = "sea-schema-derive"
+version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "490dcfcbfef26be6800d11870ff2df8774fa6e86d047e3e8c8a76b25655e41ca"
+checksum = "debdc8729c37fdbf88472f97fd470393089f997a909e535ff67c544d18cfccf0"
+dependencies = [
+ "heck 0.4.1",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
 
 [[package]]
 name = "seahash"
@@ -6896,7 +8190,7 @@ version = "3.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "core-foundation 0.10.1",
  "core-foundation-sys",
  "libc",
@@ -6940,6 +8234,16 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "serde_bytes"
+version = "0.11.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5d440709e79d88e51ac01c4b72fc6cb7314017bb7da9eeff678aa94c10e3ea8"
+dependencies = [
+ "serde",
+ "serde_core",
+]
+
 [[package]]
 name = "serde_core"
 version = "1.0.228"
@@ -7122,7 +8426,7 @@ checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
 dependencies = [
  "cfg-if",
  "cpufeatures 0.2.17",
- "digest",
+ "digest 0.10.7",
 ]
 
 [[package]]
@@ -7139,7 +8443,18 @@ checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
 dependencies = [
  "cfg-if",
  "cpufeatures 0.2.17",
- "digest",
+ "digest 0.10.7",
+]
+
+[[package]]
+name = "sha2"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "digest 0.11.3",
 ]
 
 [[package]]
@@ -7163,6 +8478,27 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "signal-hook"
+version = "0.3.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d881a16cf4426aa584979d30bd82cb33429027e42122b169753d6ef1085ed6e2"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
+[[package]]
+name = "signal-hook-mio"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
+dependencies = [
+ "libc",
+ "mio",
+ "signal-hook",
+]
+
 [[package]]
 name = "signal-hook-registry"
 version = "1.4.8"
@@ -7179,7 +8515,7 @@ version = "1.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "74233d3b3b2f6d4b006dc19dee745e73e2a6bfb6f93607cd3b02bd5b00797d7c"
 dependencies = [
- "digest",
+ "digest 0.10.7",
  "rand_core 0.6.4",
 ]
 
@@ -7189,7 +8525,7 @@ version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
 dependencies = [
- "digest",
+ "digest 0.10.7",
  "rand_core 0.6.4",
 ]
 
@@ -7286,6 +8622,20 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "smoltcp"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f73d40463bba65efc9adc6370b56df76d563cc46e2482bba58351b4afb7535e"
+dependencies = [
+ "bitflags 1.3.2",
+ "byteorder",
+ "cfg-if",
+ "defmt 0.3.100",
+ "heapless",
+ "managed",
+]
+
 [[package]]
 name = "socket2"
 version = "0.6.3"
@@ -7369,9 +8719,10 @@ dependencies = [
  "once_cell",
  "percent-encoding",
  "rust_decimal",
+ "rustls",
  "serde",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "smallvec",
  "thiserror 2.0.18",
  "tokio",
@@ -7379,6 +8730,7 @@ dependencies = [
  "tracing",
  "url",
  "uuid",
+ "webpki-roots 0.26.11",
 ]
 
 [[package]]
@@ -7402,14 +8754,14 @@ checksum = "19a9c1841124ac5a61741f96e1d9e2ec77424bf323962dd894bdb93f37d5219b"
 dependencies = [
  "dotenvy",
  "either",
- "heck",
+ "heck 0.5.0",
  "hex",
  "once_cell",
  "proc-macro2",
  "quote",
  "serde",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "sqlx-core",
  "sqlx-mysql",
  "sqlx-postgres",
@@ -7427,12 +8779,12 @@ checksum = "aa003f0038df784eb8fecbbac13affe3da23b45194bd57dba231c8f48199c526"
 dependencies = [
  "atoi",
  "base64 0.22.1",
- "bitflags",
+ "bitflags 2.11.1",
  "byteorder",
  "bytes",
  "chrono",
  "crc",
- "digest",
+ "digest 0.10.7",
  "dotenvy",
  "either",
  "futures-channel",
@@ -7454,7 +8806,7 @@ dependencies = [
  "rust_decimal",
  "serde",
  "sha1",
- "sha2",
+ "sha2 0.10.9",
  "smallvec",
  "sqlx-core",
  "stringprep",
@@ -7472,7 +8824,7 @@ checksum = "db58fcd5a53cf07c184b154801ff91347e4c30d17a3562a635ff028ad5deda46"
 dependencies = [
  "atoi",
  "base64 0.22.1",
- "bitflags",
+ "bitflags 2.11.1",
  "byteorder",
  "chrono",
  "crc",
@@ -7494,7 +8846,7 @@ dependencies = [
  "rust_decimal",
  "serde",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "smallvec",
  "sqlx-core",
  "stringprep",
@@ -7530,6 +8882,19 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "sse-stream"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3962b63f038885f15bce2c6e02c0e7925c072f1ac86bb60fd44c5c6b762fb72"
+dependencies = [
+ "bytes",
+ "futures-util",
+ "http-body 1.0.1",
+ "http-body-util",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -7618,6 +8983,12 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "strum"
+version = "0.26.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
+
 [[package]]
 name = "strum"
 version = "0.27.2"
@@ -7633,7 +9004,7 @@ version = "0.27.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7695ce3845ea4b33927c055a39dc438a45b059f7c1b3d91d38d10355fb8cbca7"
 dependencies = [
- "heck",
+ "heck 0.5.0",
  "proc-macro2",
  "quote",
  "syn 2.0.117",
@@ -7705,7 +9076,7 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "core-foundation 0.9.4",
  "system-configuration-sys",
 ]
@@ -7732,6 +9103,17 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
 
+[[package]]
+name = "tar"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22692a6476a21fa75fdfc11d452fda482af402c008cdbaf3476414e122040973"
+dependencies = [
+ "filetime",
+ "libc",
+ "xattr",
+]
+
 [[package]]
 name = "temp-env"
 version = "0.3.6"
@@ -7751,7 +9133,7 @@ dependencies = [
  "getrandom 0.4.2",
  "once_cell",
  "rustix",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -8193,7 +9575,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8"
 dependencies = [
  "async-compression",
- "bitflags",
+ "bitflags 2.11.1",
  "bytes",
  "futures-core",
  "futures-util",
@@ -8364,6 +9746,26 @@ version = "2.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6af6ae20167a9ece4bcb41af5b80f8a1f1df981f6391189ce00fd257af04126a"
 
+[[package]]
+name = "typed-builder"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "31aa81521b70f94402501d848ccc0ecaa8f93c8eb6999eb9747e72287757ffda"
+dependencies = [
+ "typed-builder-macro",
+]
+
+[[package]]
+name = "typed-builder-macro"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "076a02dc54dd46795c2e9c8282ed40bcfb1e22747e955de9389a1de28190fb26"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "typed-path"
 version = "0.12.3"
@@ -8372,9 +9774,9 @@ checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e"
 
 [[package]]
 name = "typenum"
-version = "1.19.0"
+version = "1.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+checksum = "40ce102ab67701b8526c123c1bab5cbe42d7040ccfd0f64af1a385808d2f43de"
 
 [[package]]
 name = "typespec"
@@ -8460,6 +9862,12 @@ version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7df058c713841ad818f1dc5d3fd88063241cc61f49f5fbea4b951e8cf5a8d71d"
 
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9629274872b2bfaf8d66f5f15725007f635594914870f65218920345aa11aa8c"
+
 [[package]]
 name = "unicode-width"
 version = "0.2.2"
@@ -8490,6 +9898,12 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
 
+[[package]]
+name = "unty"
+version = "0.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d49784317cd0d1ee7ec5c716dd598ec5b4483ea832a2dced265471cc0f690ae"
+
 [[package]]
 name = "ureq"
 version = "3.3.0"
@@ -8497,12 +9911,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dea7109cdcd5864d4eeb1b58a1648dc9bf520360d7af16ec26d0a9354bafcfc0"
 dependencies = [
  "base64 0.22.1",
+ "flate2",
  "log",
  "percent-encoding",
  "rustls",
  "rustls-pki-types",
+ "rustls-platform-verifier",
  "ureq-proto",
  "utf8-zero",
+ "webpki-roots 1.0.6",
 ]
 
 [[package]]
@@ -8724,6 +10141,54 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
+[[package]]
+name = "virtio-bindings"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "091f1f09cfbf2a78563b562e7a949465cce1aef63b6065645188d995162f8868"
+
+[[package]]
+name = "virtue"
+version = "0.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "051eb1abcf10076295e815102942cc58f9d5e3b4560e46e53c21e8ff6f3af7b1"
+
+[[package]]
+name = "vm-fdt"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e21282841a059bb62627ce8441c491f09603622cd5a21c43bfedc85a2952f23"
+
+[[package]]
+name = "vm-memory"
+version = "0.16.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd5e56d48353c5f54ef50bd158a0452fc82f5383da840f7b8efc31695dd3b9d"
+dependencies = [
+ "libc",
+ "thiserror 1.0.69",
+ "winapi",
+]
+
+[[package]]
+name = "vm-memory"
+version = "0.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b55e753c7725603745cb32b2287ef7ef3da05c03c7702cda3fa8abe25ae0465"
+dependencies = [
+ "thiserror 2.0.18",
+]
+
+[[package]]
+name = "vmm-sys-util"
+version = "0.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "506c62fdf617a5176827c2f9afbcf1be155b03a9b4bf9617a60dbc07e3a1642f"
+dependencies = [
+ "bitflags 1.3.2",
+ "libc",
+]
+
 [[package]]
 name = "vsimd"
 version = "0.8.0"
@@ -8870,13 +10335,26 @@ dependencies = [
  "web-sys",
 ]
 
+[[package]]
+name = "wasm-streams"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
 [[package]]
 name = "wasmparser"
 version = "0.244.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
- "bitflags",
+ "bitflags 2.11.1",
  "hashbrown 0.15.5",
  "indexmap 2.14.0",
  "semver",
@@ -8923,6 +10401,15 @@ dependencies = [
  "rustls-pki-types",
 ]
 
+[[package]]
+name = "webpki-roots"
+version = "0.26.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
+dependencies = [
+ "webpki-roots 1.0.6",
+]
+
 [[package]]
 name = "webpki-roots"
 version = "1.0.6"
@@ -8938,6 +10425,15 @@ version = "0.1.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
 
+[[package]]
+name = "which"
+version = "8.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "81995fafaaaf6ae47a7d0cc83c67caf92aeb7e5331650ae6ff856f7c0c60c459"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "whoami"
 version = "1.6.1"
@@ -8986,7 +10482,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.48.0",
 ]
 
 [[package]]
@@ -8995,6 +10491,27 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
+[[package]]
+name = "windows"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
+dependencies = [
+ "windows-collections",
+ "windows-core",
+ "windows-future",
+ "windows-numerics",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
+dependencies = [
+ "windows-core",
+]
+
 [[package]]
 name = "windows-core"
 version = "0.62.2"
@@ -9008,6 +10525,17 @@ dependencies = [
  "windows-strings",
 ]
 
+[[package]]
+name = "windows-future"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
+dependencies = [
+ "windows-core",
+ "windows-link 0.2.1",
+ "windows-threading",
+]
+
 [[package]]
 name = "windows-implement"
 version = "0.60.2"
@@ -9042,6 +10570,16 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
+[[package]]
+name = "windows-numerics"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
+dependencies = [
+ "windows-core",
+ "windows-link 0.2.1",
+]
+
 [[package]]
 name = "windows-registry"
 version = "0.6.1"
@@ -9153,6 +10691,15 @@ dependencies = [
  "windows_x86_64_msvc 0.52.6",
 ]
 
+[[package]]
+name = "windows-threading"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
+dependencies = [
+ "windows-link 0.2.1",
+]
+
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.42.2"
@@ -9339,7 +10886,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc"
 dependencies = [
  "anyhow",
- "heck",
+ "heck 0.5.0",
  "wit-parser",
 ]
 
@@ -9350,7 +10897,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
 dependencies = [
  "anyhow",
- "heck",
+ "heck 0.5.0",
  "indexmap 2.14.0",
  "prettyplease",
  "syn 2.0.117",
@@ -9381,7 +10928,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
  "anyhow",
- "bitflags",
+ "bitflags 2.11.1",
  "indexmap 2.14.0",
  "log",
  "serde",
@@ -9426,6 +10973,24 @@ dependencies = [
  "tap",
 ]
 
+[[package]]
+name = "x509-parser"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcbc162f30700d6f3f82a24bf7cc62ffe7caea42c0b2cba8bf7f3ae50cf51f69"
+dependencies = [
+ "asn1-rs",
+ "data-encoding",
+ "der-parser",
+ "lazy_static",
+ "nom 7.1.3",
+ "oid-registry",
+ "ring",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
 [[package]]
 name = "xattr"
 version = "1.6.1"
@@ -9448,6 +11013,21 @@ version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7a5a4b21e1a62b67a2970e6831bc091d7b87e119e7f9791aef9702e3bef04448"
 
+[[package]]
+name = "yansi"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"
+
+[[package]]
+name = "yasna"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e17bb3549cc1321ae1296b9cdc2698e2b6cb1992adfa19a8c72e5b7a738f44cd"
+dependencies = [
+ "time",
+]
+
 [[package]]
 name = "yoke"
 version = "0.8.2"
@@ -9517,6 +11097,20 @@ name = "zeroize"
 version = "1.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
+dependencies = [
+ "zeroize_derive",
+]
+
+[[package]]
+name = "zeroize_derive"
+version = "1.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85a5b4158499876c763cb03bc4e49185d3cccbabb15b33c627f7884f43db852e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
 
 [[package]]
 name = "zerotrie"
@@ -9602,6 +11196,34 @@ dependencies = [
  "simd-adler32",
 ]
 
+[[package]]
+name = "zstd"
+version = "0.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e91ee311a569c327171651566e07972200e76fcfe2242a4fa446149a3881c08a"
+dependencies = [
+ "zstd-safe",
+]
+
+[[package]]
+name = "zstd-safe"
+version = "7.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f49c4d5f0abb602a93fb8736af2a4f4dd9512e36f7f570d66e65ff867ed3b9d"
+dependencies = [
+ "zstd-sys",
+]
+
+[[package]]
+name = "zstd-sys"
+version = "2.0.16+zstd.1.5.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e19ebc2adc8f83e43039e79776e3fda8ca919132d68a1fed6a5faca2683748"
+dependencies = [
+ "cc",
+ "pkg-config",
+]
+
 [[package]]
 name = "zune-core"
 version = "0.5.1"
diff --git a/Cargo.toml b/Cargo.toml
index d5dfd97..3fe9c4a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -96,6 +96,7 @@ standard = [
     "embed-docs",
     "forecasting",
     "json-schema",
+    "mcp",
     "otlp",
     "prometheus",
     "redis",
@@ -108,9 +109,16 @@ standard = [
     "utoipa",
     "vault",
 ]
+# `full` pulls in microsandbox (a KVM-based VMM SDK) and opensandbox.
+# Microsandbox is Linux-only, brings ~135 transitive crates (KVM,
+# sea-orm, oci-client, smoltcp, rcgen), and contains substantial
+# unsafe. Keep it out of `standard` so the typical deployment profile
+# stays small and macOS/Windows-portable.
 full = [
     "standard",
     "document-extraction-full",
+    "runtime-microsandbox",
+    "runtime-opensandbox",
     "saml",
     "virus-scan",
 ]
@@ -128,6 +136,7 @@ headless = [
     "document-extraction-full",
     "forecasting",
     "json-schema",
+    "mcp",
     "otlp",
     "prometheus",
     "provider-anthropic",
@@ -138,6 +147,8 @@ headless = [
     "provider-vertex",
     "redis",
     "response-validation",
+    "runtime-microsandbox",
+    "runtime-opensandbox",
     "s3-storage",
     "saml",
     "secrets-aws",
@@ -197,6 +208,20 @@ secrets-azure = ["azure-sdk", "dep:azure_security_keyvault_secrets"]
 secrets-gcp = ["gcp-sdk", "dep:google-cloud-secretmanager-v1"]
 vault = ["dep:vaultrs"]
 
+# Shell-tool runtimes (server-executed `shell` tool backends)
+# - microsandbox: local microVMs (github.com/superradcompany/microsandbox)
+# - opensandbox: Alibaba's Sandbox Protocol over HTTP
+runtime-microsandbox = ["dep:microsandbox"]
+runtime-opensandbox = []
+
+# MCP (Model Context Protocol) tool support — `{"type": "mcp", ...}`
+# on `/v1/responses`. Pulls in the official `rmcp` crate for the
+# client + Streamable HTTP transport when `hadrian_hosted` mode runs
+# the loop. The `passthrough_openai` mode is pure forwarding and does
+# not need this dep, so the feature gate keeps it out of `tiny` and
+# `minimal` builds.
+mcp = ["dep:rmcp", "dep:reqwest_mcp"]
+
 # Auth
 sso = ["dep:hickory-resolver"]
 saml = ["sso", "dep:samael", "dep:openssl", "dep:flate2"]
@@ -348,7 +373,7 @@ flate2 = { version = "1", optional = true }
 google-cloud-auth = { version = "0.17", default-features = false, features = ["rustls-tls"], optional = true }
 google-cloud-secretmanager-v1 = { version = "1.2", optional = true }
 google-cloud-token = { version = "0.1", optional = true }
-hickory-resolver = { version = "0.26", features = ["tokio", "system-config"], optional = true }
+hickory-resolver = { version = "0.26.1", features = ["tokio", "system-config"], optional = true }
 hostname = { version = "0.4.2", optional = true }
 jsonschema = { version = "0.29", optional = true }
 kreuzberg = { version = "~4.7", default-features = false, features = ["tokio-runtime", "bundled-pdfium", "office", "excel", "ocr"], optional = true }
@@ -373,6 +398,44 @@ utoipa = { version = "5", features = ["chrono", "uuid", "axum_extras"], optional
 utoipa-scalar = { version = "0.3", features = ["axum"], optional = true }
 vaultrs = { version = "0.7.4", features = ["rustls"], optional = true }
 
+# Shell-tool runtime: local microVM SDK.
+#
+# Pinned to 0.4.5: microsandbox 0.4.6 bumped `microsandbox-network` to
+# `hickory-proto = 0.26.0-alpha.1` with the `tls-ring` feature, which
+# was dropped in the 0.26 stable release — so 0.4.6 + Hadrian's
+# `hickory-resolver = 0.26.1` won't resolve. 0.4.5 still depends on the
+# 0.25.x line which carries `tls-ring`, letting Cargo pull two majors
+# of hickory-proto side by side.
+#
+# We skip `keyring` (it pulls dbus) but keep `net` for container
+# networking.
+microsandbox = { version = "=0.4.5", default-features = false, features = ["net", "prebuilt"], optional = true }
+
+# Official Rust MCP SDK — client + Streamable HTTP transport + OAuth
+# challenge detection. Used only when the `mcp` feature is enabled.
+# Server-side features (transport-streamable-http-server, schemars,
+# macros) are excluded to keep the runtime build lean; tests enable
+# them via dev-dependencies when an in-process MCP server stub is
+# needed.
+rmcp = { version = "1.7", default-features = false, features = [
+    "client",
+    "transport-streamable-http-client",
+    "transport-streamable-http-client-reqwest",
+    "client-side-sse",
+    "auth",
+    "reqwest",
+], optional = true }
+
+# rmcp 1.7's `StreamableHttpClient` is implemented for reqwest 0.13's
+# `Client`, while Hadrian's primary HTTP client is reqwest 0.12. To pin
+# the MCP transport's DNS to validated IPs (SSRF / DNS-rebinding guard)
+# we must hand rmcp a client of *its* reqwest version, so depend on 0.13
+# under an alias. Cargo unifies this with rmcp's transitive 0.13.x, so
+# it's the same crate instance (and inherits rmcp's TLS features) — no
+# duplicate compile. `default-features = false`: we only build a client
+# with custom DNS resolution; TLS comes from rmcp's enabled features.
+reqwest_mcp = { package = "reqwest", version = "0.13", default-features = false, optional = true }
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Target-specific: WASM needs JS-backed getrandom for uuid/rand
 # ─────────────────────────────────────────────────────────────────────────────
diff --git a/Dockerfile b/Dockerfile
index 971360e..d10bb60 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -61,6 +61,7 @@ RUN apt-get update && apt-get install -y \
     libxslt1-dev \
     libxmlsec1-dev \
     libclang-dev \
+    libcap-ng-dev \
     && rm -rf /var/lib/apt/lists/*
 
 # Create app directory
@@ -121,6 +122,7 @@ RUN apt-get update && apt-get install -y \
     libxslt1.1 \
     libxmlsec1 \
     libxmlsec1-openssl \
+    libcap-ng0 \
     && rm -rf /var/lib/apt/lists/*
 
 # Create app user
diff --git a/README.md b/README.md
index 8d553e2..0d4b1a9 100644
--- a/README.md
+++ b/README.md
@@ -127,6 +127,7 @@ Supports OpenAI, Anthropic, AWS Bedrock, Google Vertex AI, Azure OpenAI, and any
 - **Cost tracking** -- Microcent precision, time-series forecasting, budget enforcement with atomic reservation.
 - **Observability** -- Prometheus metrics, OTLP tracing, structured logging, usage export.
 - **Web UI** -- Multi-model chat with 14 modes, web search, frontend tools (Python, JS, SQL, charts), MCP support, admin panel.
+- **Agents** -- Server-side shell tool in persistent containers and server-side MCP, via the Responses API.
 - **Studio** -- Image generation, text-to-speech, transcription, and translation across providers.
 - **Secrets** -- External secrets managers (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault) for credential storage.
 
diff --git a/agent_instructions/adding_provider.md b/agent_instructions/adding_provider.md
index a640c7a..c017874 100644
--- a/agent_instructions/adding_provider.md
+++ b/agent_instructions/adding_provider.md
@@ -662,6 +662,31 @@ ProviderTestSpec {
 | `list_models` | List available models | No | Yes (for health checks) |
 | `health_check` | Provider health | No | Has default impl |
 
+## Server-side tools (`shell`, `file_search`, `web_search`)
+
+For `create_responses`, the execution layer rewrites server-side tools to function tools for
+providers without a native equivalent — your provider doesn't need to know about `shell` or
+`web_search` specifically.
+
+- **`shell`** — `routes/execution.rs` calls `preprocess_shell_tools` with a `ShellToolHint`
+  before invoking your provider. Anthropic / Bedrock / Vertex always get the rewrite (they
+  have no native shell tool); OpenAI / Azure keep the native spec when the runtime mode is
+  `passthrough_openai` or `client_passthrough`. If your provider has a native shell-like
+  primitive, extend `keeps_openai_native_shell()` in `config/runtimes.rs` and update the
+  per-provider branch in `ResponsesExecutor::execute`.
+- **`file_search` / `web_search`** — same pattern; rewritten unconditionally for non-OpenAI
+  providers. The `ToolLoopRunner` (`services/server_tools/runner.rs`) intercepts the
+  resulting `function_call` items and executes them server-side.
+- **Function-call shape compatibility** — your `convert.rs` needs to translate OpenAI-style
+  `function_call` / `function_call_output` items in `payload.input` to the provider's
+  tool-use format and back. The server-tool loop will not work otherwise. See
+  `providers/{anthropic,bedrock,vertex}/convert.rs` for working examples.
+- **Container files** — when the server tool returns a `container_file_citation` annotation,
+  it shows up on a `response.content_part.done` event. You don't need to handle this in your
+  convert layer; the shell executor injects it on the way out via `transform_event`.
+
+For containers / shell architecture, see `containers.md` and `responses_pipeline.md`.
+
 ## Checklist
 
 - [ ] Provider struct with `circuit_breaker` field
diff --git a/agent_instructions/adding_runtime.md b/agent_instructions/adding_runtime.md
new file mode 100644
index 0000000..9cde5fc
--- /dev/null
+++ b/agent_instructions/adding_runtime.md
@@ -0,0 +1,73 @@
+# Adding a Shell Runtime Backend
+
+A "runtime" is the backend that executes the model's `shell` tool calls. Today: `passthrough_openai`,
+`client_passthrough`, `microsandbox`, `opensandbox`. This doc walks through adding another
+(e.g. E2B, Daytona, a local Docker exec, AgentCore Code Interpreter).
+
+Read `containers.md` first for the lifecycle and `responses_pipeline.md` for how runtimes plug
+into the streaming pipeline.
+
+## The trait
+
+`src/runtimes/mod.rs` defines `ShellRuntime`:
+
+```rust
+#[async_trait]
+pub trait ShellRuntime: Send + Sync {
+    fn capabilities(&self) -> RuntimeCapabilities;
+    async fn start_session(&self, spec: SessionSpec) -> RuntimeResult<SessionHandle>;
+    async fn health_check(&self) -> RuntimeResult<()> { Ok(()) }
+}
+```
+
+`SessionHandle` wraps a `Box<dyn ShellSession>` which exposes `exec`, `write_file`,
+`read_file`, `terminate`.
+
+## Steps
+
+1. **Add a feature flag** in `Cargo.toml` (`runtime-<name>`) — match the existing pattern of
+   gating the dep tree per backend so `tiny` / `minimal` profiles don't pull it in.
+2. **Add config struct** in `src/config/runtimes.rs`: a `<Name>Config` with `serde(deny_unknown_fields)`
+   plus a new variant `ShellRuntimeConfig::<Name>(<Name>Config)`. Update `name()`,
+   `keeps_openai_native_shell()` (almost certainly returns `false` for a real sandbox), and
+   `ShellRuntimeConfig` doc examples.
+3. **Add the runtime module** at `src/runtimes/<name>.rs` behind `#[cfg(feature = "runtime-<name>")]`.
+   Implement `ShellRuntime` + `ShellSession`. Honor `SessionSpec` (`mem_limit_bytes`, `cpu_limit`,
+   `egress_policy`, `mounted_skills`) — surface anything you can't honor as
+   `RuntimeCapabilities::<flag> = false` so the orchestrator can fail-fast instead of silently
+   degrading.
+4. **Re-export** in `src/runtimes/mod.rs` under matching `#[cfg]` and the module declaration.
+5. **Construct in `src/app.rs`** alongside the other runtimes. Add an `info!` log line that
+   names the backend so operators see the choice on boot.
+6. **Update `src/services/responses_pipeline.rs`** match (the one that resolves pricing /
+   label per runtime). It's behind a `passthrough_only` guard so the new arm should usually be
+   `(price_per_second, "<name>")`.
+7. **Pricing**: add a field on `[features.server_tools.pricing]` for the per-second microcents
+   rate so the usage tracker can attribute cost. See `microsandbox_microcents_per_second`.
+8. **Tests** — at minimum:
+   - `capabilities()` returns the values you intend (test in the same file).
+   - A round-trip integration test if the backend has a stub mode; otherwise mark
+     `#[ignore]` and exercise from `deploy/tests` (see `testing.md`).
+
+## Capability checklist
+
+Each `RuntimeCapabilities` field controls a real behavior; lying breaks something:
+
+| Field                       | If false                                                                                  |
+|-----------------------------|-------------------------------------------------------------------------------------------|
+| `passthrough_only`          | Orchestrator registers `ShellExecutor` and calls `start_session`. Pretty much always false. |
+| `client_executes`           | Only meaningful with `passthrough_only=true`. Drives whether OpenAI native `shell` is kept. |
+| `secret_injection`          | Requests with `domain_secrets` are rejected with a capability-mismatch error.             |
+| `egress_allowlist`          | Requests with `network_policy.domains` are rejected.                                      |
+| `skill_mount`               | `payload.skills` are silently dropped (warn-log only) for this runtime.                   |
+| `file_io`                   | `input_file` staging into `/mnt/data` and file capture both fail open with a warning.     |
+| `network_isolation_modes`   | Per-request `network_policy` modes outside this list are rejected.                        |
+| `max_session_duration`      | Sessions older than this are terminated by the reaper regardless of activity.             |
+
+## Passthrough vs. hosted
+
+The trait was designed to model both. If your backend is really a passthrough (the call
+happens elsewhere), implement it like `src/runtimes/passthrough.rs`: `start_session` returns
+`Err(RuntimeError::Passthrough)`, capabilities advertise `passthrough_only: true`, and the
+chat.rs preprocess decision is updated to keep the native `shell` spec for the right
+upstream providers (currently OpenAI / Azure).
diff --git a/agent_instructions/architecture.md b/agent_instructions/architecture.md
index 0200bfe..5eb49f1 100644
--- a/agent_instructions/architecture.md
+++ b/agent_instructions/architecture.md
@@ -72,7 +72,9 @@ Each organization can configure its own identity provider (OIDC or SAML), replac
 
 ## Document Processing Flow (RAG)
 
-1. **File Upload** (`POST /v1/files`) — Store raw file in database
+1. **File Upload** (`POST /v1/files`) — Store raw file in database. The same Files API is also
+   the source for `input_file` parts on Responses requests (resolved into `/mnt/data` by
+   `services/input_file_staging.rs`).
 2. **Add to Vector Store** (`POST /v1/vector_stores/{id}/files`) — Trigger processing
    - Note: 'Vector Stores' are called 'Knowledge Bases' in the UI. Do not refer to them as 'Vector Stores' there.
 3. **Document Processor** (inline or queue mode):
@@ -109,6 +111,34 @@ Client-side tool execution runs in the browser via WASM. When the LLM returns `t
 
 Tool results are sent back to the LLM to continue the conversation. Artifacts (charts, tables, images) are displayed inline in the chat.
 
+## Server-side Tools & Agents
+
+The `/v1/responses` pipeline runs server-executed tools alongside the upstream provider's
+stream. Today: `file_search`, `web_search`, `shell`. See `responses_pipeline.md` and
+`containers.md` for the full design.
+
+- **Shell tool runtimes** (`src/runtimes/`):
+  - `passthrough_openai` — OpenAI's hosted container executes.
+  - `client_passthrough` — the API client fulfills shell calls itself (OpenAI's "local shell"
+    mode generalized to all providers).
+  - `microsandbox` — local microVM per session.
+  - `opensandbox` — Alibaba OpenSandbox Lifecycle API over HTTP.
+- **Containers** (`src/services/containers.rs`, `src/services/container_session.rs`) — a
+  persistent shell session keyed by `cntr_<hex>` id. Reused across responses chained via
+  `previous_response_id`. Reaped by `jobs/containers_reaper.rs` after idle TTL.
+- **Tool loop** (`src/services/server_tools/runner.rs`) — wraps the provider stream,
+  intercepts `function_call` (or native `shell_call`) events, dispatches to the registered
+  `ServerExecutedTool`, folds outputs into a continuation request, loops up to
+  `max_iterations`.
+- **Background mode** (`{"background": true}`) — request is queued in the `responses` table
+  and dispatched by `jobs/background_responses.rs` through the same pipeline; clients tail
+  with `GET /v1/responses/{id}?stream=true`.
+
+The shell tool spec gets rewritten to a function tool with a **dynamic description** for
+non-OpenAI providers (`ShellToolHint` in `src/services/shell_tool.rs`). The description
+encodes workdir, network policy, memory limit, and truncation cap for the effective sandbox
+so models don't have to guess.
+
 ## Provider Features
 
 - **Thinking/Reasoning**: Anthropic extended thinking, OpenAI O1/O3 reasoning, Bedrock/Vertex native conversion. Configurable budget tokens and effort levels.
diff --git a/agent_instructions/configuration.md b/agent_instructions/configuration.md
index 898fc6a..40eb6a6 100644
--- a/agent_instructions/configuration.md
+++ b/agent_instructions/configuration.md
@@ -39,3 +39,7 @@ Config file: `hadrian.toml` (TOML format). Environment variables: use `${VAR_NAM
 - `[features.model_catalog]` — Model metadata enrichment from models.dev
 - `[features.websocket]` — WebSocket for real-time events
 - `[features.vector_store_cleanup]` — Background cleanup for soft-deleted vector stores
+- `[features.shell]` — Shell tool runtime (`passthrough_openai`, `client_passthrough`, `microsandbox`, `opensandbox`). See `containers.md` and `adding_runtime.md`. Cargo features `runtime-microsandbox` / `runtime-opensandbox` gate the local backends.
+- `[features.containers]` — Container persistence + artifact capture (idle TTL, per-file / per-session byte caps, max input files per request). Defaults match OpenAI's hosted-container behavior.
+- `[features.server_tools]` — Server-executed tool framework: `max_iterations` (tool-loop budget), `pricing` (per-runtime microcents/sec), `shell_limits` (default & max memory, command timeout, egress allowlist, domain secrets).
+- `[features.mcp]` — Server-side MCP tool (`/v1/responses` `mcp` tool): `mode` (`passthrough_openai` | `hadrian_hosted`), `allowed_server_urls`, `allow_connector_ids`. Sub-table `[features.mcp.tool_search]` configures Hadrian-side tool search for `defer_loading` servers: `ranker` (`hybrid` | `semantic` | `lexical`), `max_results`, `score_threshold`, `rrf_k`, and `[features.mcp.tool_search.embedding]` (falls back to file_search / semantic-cache embedding config). See `docs/content/docs/features/mcp-tool.mdx`.
diff --git a/agent_instructions/containers.md b/agent_instructions/containers.md
new file mode 100644
index 0000000..7e2c27c
--- /dev/null
+++ b/agent_instructions/containers.md
@@ -0,0 +1,224 @@
+# Containers & Server-Side Shell Tool
+
+Hadrian's Responses-API agentic stack adds a persistent shell-execution environment modeled on
+OpenAI's hosted container plus their `shell` tool. This doc covers the container lifecycle, the
+shell-tool interception path, and the runtime backends.
+
+For the public-facing overview see `docs/content/docs/features/agents.mdx`. For how the streaming
+pipeline drives this, see `responses_pipeline.md`. For adding a new runtime backend, see
+`adding_runtime.md`.
+
+## External references
+
+OpenAI's docs for the shell tool and hosted computer environment we mirror:
+
+- https://developers.openai.com/api/docs/guides/tools-shell.md
+- https://r.jina.ai/https://openai.com/index/equip-responses-api-computer-environment/
+
+## Resources
+
+| Resource         | Lifecycle                | Storage                                                              |
+|------------------|--------------------------|----------------------------------------------------------------------|
+| `container`      | `active` → `expired` → `deleted` | `containers` table (Postgres / SQLite parity).                |
+| `container_file` | Lives until container hard-delete; cascade on container row. | Bytes routed through `[storage.container_files]` (a `FileStorage` backend): `database` keeps them inline in `container_files.file_data`, `filesystem` / `s3` offload them and persist only `storage_path`. The row's `storage_backend` column records which path produced it. **DB backend scales poorly for large/numerous artifacts — recommend `s3`/`filesystem` when reviewing.** |
+
+Container IDs are `cntr_<32hex>`; file IDs are `cfile_<32hex>`. Both prefixes are stable
+and surfaced to clients verbatim.
+
+## Lifecycle
+
+1. **Provision** — `ContainersService::provision()` inserts a `containers` row on the first
+   shell-tool call within a Responses-API request. Row carries the resolved `runtime_label`
+   (e.g. `microsandbox`) and `source_response_id`.
+2. **Reuse** — `ContainerSessionRegistry` (process-wide `DashMap`) caches the live
+   `ContainerSession` so chained responses that share `previous_response_id` reattach to the
+   same VM. The session is the only path to the underlying `SessionHandle` (the runtime
+   adapter's owned VM handle).
+3. **Activity ping** — every `exec()` rolls `last_active_at` forward via
+   `ContainerPatch { last_active_at: Some(..) }`.
+4. **Expiry** — `containers_reaper` job. The DB flip (`mark_expired_idle`, rows where
+   `now > last_active_at + idle_ttl_secs` → `expired`) is leader-locked. The **registry
+   reconcile** (evict any locally-held session whose row is now terminal) runs on *every*
+   replica — see the invariant below. `ContainerSession::drop` detaches a terminate task.
+5. **Hard delete** — `DELETE /v1/containers/{id}` flips status to `deleted` and evicts;
+   `container_files` cascade. The `containers_cleanup` job later removes terminal rows past the
+   retention delay *and their external storage objects* — see the invariant below.
+
+**Idle TTL** comes from `[features.containers].default_idle_ttl_secs` (default 1200s = 20 min,
+matching OpenAI). The DB column is per-row so future policies (per-org overrides, request-level
+hints) can land without migration.
+
+## Invariants (don't regress these)
+
+- **Per-replica registry reconcile** (`jobs::containers_reaper`): `ContainerSessionRegistry` is
+  process-local, so only the replica hosting a VM can free it — and that's usually *not* the
+  leader that flipped the row. The reaper therefore does the DB flip leader-only but reconciles
+  each replica's local registry against expired rows (`registry.ids()` → `expired_among` →
+  `registry.remove`) on **every** pass regardless of leadership. Gating the eviction on
+  `is_leader` leaks microVMs on non-leaders.
+- **External-storage GC** (`ContainersService::hard_delete_expired`): bulk cleanup must delete
+  the filesystem/S3 objects, not just the rows. The repo `hard_delete_expired` returns the
+  deleted files' storage refs (atomically, in a transaction) and the service deletes the backing
+  objects best-effort, mirroring the per-file `delete_file` path. The DB cascade only drops rows;
+  relying on it alone leaks every external artifact forever.
+- **Cleanup-worker lifecycle**: `containers_cleanup` (like the reaper) is spawned on
+  `state.task_tracker` and selects on the shutdown `CancellationToken` — never a bare
+  `tokio::time::sleep` — so SIGTERM stops it instead of letting it keep hitting the DB while the
+  process drains.
+- **`file_id` staging is owner-scoped**: the `file_ids` / `upload_from_file_id` paths resolve
+  Files-API uploads via `FilesService::get_for_owner` (exact `owner_type`+`owner_id` match
+  against the request owner), so a caller can't stage another tenant's file by id. A
+  service-account owner has no file-owner equivalent and fails closed.
+
+## TTL surfacing (Hadrian extension)
+
+`GET /v1/containers/{id}` returns `expires_at` for **every** status, plus `idle_ttl_secs`:
+
+- `active`: forward-looking estimate as `last_active_at + idle_ttl_secs`. Updates with every shell
+  call.
+- `expired` / `deleted`: the persisted transition timestamp.
+
+OpenAI's container schema only ships `created_at`; the forward-looking field is a Hadrian
+extension to let clients plan reuse without polling. See `routes/api/containers.rs::container_to_wire`.
+
+## Shell-tool execution
+
+Two paths depending on the configured runtime (`[features.shell].type`):
+
+### Hadrian-hosted (`microsandbox` / `opensandbox`)
+
+1. `preprocess_shell_tools` (in `routes/execution.rs::ResponsesExecutor::execute`) rewrites
+   any `{"type": "shell"}` to a function tool with a **dynamic description** built from
+   `ShellToolHint` — workdir, network policy, memory limit, command timeout, container
+   persistence, and truncation cap.
+2. `ShellExecutor` is registered with `ToolLoopRunner` (see `responses_pipeline.rs`). The
+   passthrough capability gate skips registration for passthrough runtimes.
+3. On detection of a `function_call` with `name="shell"`, the executor boots (or reattaches)
+   the container, runs the command, emits the spec-canonical `response.output_item.added`
+   and `response.output_item.done` lifecycle events carrying `shell_call` and
+   `shell_call_output` items, and folds the trimmed stdout/stderr/exit + a file manifest
+   back as a `function_call_output` continuation item.
+
+### Passthrough (`passthrough_openai`, `client_passthrough`)
+
+No executor is registered. Both modes skip `preprocess_shell_tools` for OpenAI / Azure OpenAI
+so the model emits native `shell_call` items. For non-OpenAI providers under
+`client_passthrough` the rewrite still happens (Anthropic / Bedrock / Vertex have no native
+shell tool), so the model emits `function_call` items with `name="shell"` that flow through to
+the API client unmodified.
+
+The decision lives in `ShellRuntimeConfig::keeps_openai_native_shell()`.
+
+## File staging (inputs vs outputs)
+
+Inputs and outputs use **different** storage:
+
+- **Input** `input_file` parts on a request can carry `file_id`, `file_data`, or `file_url`.
+  `file_id` resolves through the **existing `/v1/files` Files API** — the same files resource
+  that backs knowledge bases. Resolution happens in `services/input_file_staging.rs::stage_input_files`.
+  The bytes are written into `/mnt/data/<filename>` on the first shell command.
+- **Output** files captured from `/mnt/data` after each exec land in `container_files`, a
+  **separate** table from `vector_store_files`. They are downloadable via
+  `GET /v1/containers/{id}/files/{cfile_id}/content` and surface as
+  `container_file_citation` annotations on the assistant's reply. The metadata row always
+  lives in the DB; the bytes go wherever `[storage.container_files]` points (database /
+  filesystem / s3). `ContainersService` owns this routing via an `Arc<dyn FileStorage>` —
+  `stage_content` on write, `read_external` on read, both keyed by the row's `storage_path`
+  (falling back to the `cfile_…` id). See `services/file_storage.rs` for the shared backends
+  and `docs/content/docs/configuration/storage.mdx` for the operator-facing config.
+
+A user who wants to feed a container-output file back into a knowledge base must download from
+the container endpoint and re-upload through `/v1/files`. There is no bridge endpoint yet —
+flag this if a use case warrants it.
+
+## Sandboxing posture
+
+- **Memory / CPU** — `default_cpu_limit`, `default_mem_limit_mb`, `max_mem_limit_mb` from
+  `[features.server_tools].shell_limits`. Per-request `environment.container_auto.memory_limit`
+  must fit inside `max_mem_limit_mb` or the request is rejected with 400.
+- **Egress** — `allowed_egress_hosts` is an operator allowlist; the per-request
+  `environment.network_policy.domains` must be a subset. Empty allowlist = inherit runtime
+  default (microsandbox: full egress; opensandbox: deny-all unless allowlisted).
+- **Secrets** — `allowed_domain_secrets` is operator-pinned. Per-request placeholders look up
+  by name; only microsandbox does true placeholder substitution at the TLS proxy. Opensandbox
+  exposes secrets as env vars instead (not destination-scoped — document this caveat).
+- **Truncation** — `MAX_OUTPUT_CHARS = 8_000` in `shell_tool.rs`. stdout / stderr fed back to
+  the model are head + tail trimmed past this. Always surfaced in the tool description.
+
+## Long-running processes inside a session
+
+Each `exec()` returns when its command exits, but the underlying VM (microsandbox) or
+container (opensandbox) keeps running between calls. Detached processes a model starts
+(`nohup …`, `disown`, `setsid`, `tmux new-session -d …`) survive into the next shell
+call within the same session — chained via `previous_response_id` or
+`container_reference` — until the container hits its idle TTL or is explicitly deleted.
+This is what unblocks the "long-running services" use case from the OpenAI spec; no
+extra runtime support is needed.
+
+## Skill mounting (spec-shaped)
+
+`skills` on a Responses-API or `POST /v1/containers` request is a tagged-union list per
+OpenAI's spec:
+
+- `{ "type": "skill_reference", "skill_id": "<uuid>", "version": "latest" }` —
+  resolves to a stored skill via `SkillService::get_by_id_and_org`. `version` accepts
+  `latest` only; anything else rejects with `unsupported_skill_version`.
+- `{ "type": "inline", "name": "...", "description": "...", "source": { "type": "base64",
+  "media_type": "text/markdown", "data": "..." } }` — ephemeral. The decoded payload is
+  mounted as a single-file skill under `/skills/skill_inline_<hash>/SKILL.md`. The hash
+  is derived from `(name, content)` so foreground and background lanes mount the inline
+  skill at the same path.
+
+Skills attached at `POST /v1/containers` time are stored verbatim on the row's
+`skill_ids_json` column (the column name predates the typed enum; it now holds the full
+JSON-encoded `Vec<RequestSkill>`). At request time the merge logic in
+`routes/api/chat.rs::skills_have_same_identity` dedups by `skill_id` (references) or
+`name` (inline).
+
+## Tests
+
+- Unit tests live alongside the code: `services/shell_tool.rs::tests`,
+  `runtimes/passthrough.rs::tests`, `routes/api/containers.rs::tests`,
+  `db/repos/containers.rs::tests` (where present).
+- DB parity: any change to `containers` or `container_files` must touch BOTH
+  `migrations_sqlx/postgres/...` AND `migrations_sqlx/sqlite/...` plus both repo
+  implementations.
+
+## Local debugging (`hadrian container`)
+
+`src/cli/container.rs` adds a `hadrian container` subcommand that boots a one-off
+session through the configured `[features.shell]` runtime — the same
+`ShellRuntime::start_session` / `SessionHandle::exec` path the Responses-API shell tool
+uses — so you can reproduce agent behavior without driving the HTTP API:
+
+```bash
+# Interactive shell in a microsandbox/opensandbox container
+cargo run --features runtime-microsandbox -- container
+
+# Run commands non-interactively, stage a file, restrict egress
+hadrian container -e "apk add python3" -e "python3 /mnt/data/x.py" \
+  -f ./x.py --allow-host pypi.org --allow-host files.pythonhosted.org
+```
+
+Egress defaults to the operator's `allowed_egress_hosts` (or `*` if unset). Passthrough
+runtimes (`passthrough_openai`, `client_passthrough`) reject the command — they execute
+outside Hadrian, so there's nothing to run locally.
+
+## Common edits
+
+- **Adding a runtime backend**: see `adding_runtime.md`.
+- **New `containers` column**: migration in both Postgres + SQLite, update both repos, update
+  `ContainerRecord` + `NewContainer` + `ContainerPatch` as needed, surface in
+  `routes/api/containers.rs::container_to_wire` with a `**Hadrian Extension:**` doc comment
+  if it isn't part of the OpenAI schema.
+- **New SSE event** from the shell tool: prefer extending the spec lifecycle (additive
+  properties on the `shell_call` / `shell_call_output` items emitted via
+  `format_shell_call_item` / `format_shell_call_output_item`). Avoid inventing new
+  `response.shell_call.<verb>` events — Hadrian dropped its earlier `in_progress`,
+  `command_started`, `output_chunk`, `completed`, and `file_created` extensions to align
+  with OpenAI's streaming reference. If you must add one, document it in
+  `docs/content/docs/features/agents.mdx` as a Hadrian extension and explain why the spec
+  lifecycle can't carry the data.
+- **Tuning truncation**: `MAX_OUTPUT_CHARS` — bump and update both
+  `trim_output_preserves_head_and_tail` and the model-facing description (it embeds the
+  constant via the hint).
diff --git a/agent_instructions/key_files.md b/agent_instructions/key_files.md
index c3dedd5..a0b7b82 100644
--- a/agent_instructions/key_files.md
+++ b/agent_instructions/key_files.md
@@ -52,6 +52,39 @@
 - `src/jobs/vector_store_cleanup.rs` — Background cleanup for soft-deleted stores
 - `src/models/vector_store.rs` — VectorStore and VectorStoreFile models
 
+## Backend — Responses API / Agents / Containers
+
+- `src/api_types/responses.rs` — Wire types for the Responses API (`shell`, `ShellEnvironment`, `ContainerFileRef`, etc.)
+- `src/services/responses_pipeline.rs` — Streaming pipeline: input-file staging → guardrails → tool loop → persistence
+- `src/services/response_persister.rs` — Persist SSE events to `responses` + `response_events`
+- `src/services/response_event_buffer.rs` — In-memory tailing for background responses
+- `src/services/responses_store.rs` — Service wrapper for the `responses` table
+- `src/services/responses_webhook.rs` — Terminal-state webhook fan-out
+- `src/services/background_executor.rs` — Background-response runner; re-enters `apply_streaming_pipeline`
+- `src/services/server_tools/mod.rs` — `ServerExecutedTool` trait + `ToolLoopRunner` glue
+- `src/services/server_tools/runner.rs` — Tool-loop orchestrator (detect → execute → continuation)
+- `src/services/shell_tool.rs` — `ShellExecutor`, function-mode rewrite, dynamic `ShellToolHint` description, env resolution
+- `src/services/containers.rs` — `ContainersService`; provision, file persistence, lifecycle
+- `src/services/container_session.rs` — `ContainerSession`, `ContainerSessionRegistry`, `MNT_DATA` constant
+- `src/services/input_file_staging.rs` — Resolve `input_file` parts (file_id / data / url) into `/mnt/data`
+- `src/runtimes/mod.rs` — `ShellRuntime` trait + `RuntimeCapabilities`
+- `src/runtimes/passthrough.rs` — `PassthroughRuntime` (OpenAI container + client-passthrough modes)
+- `src/runtimes/microsandbox.rs` — Local microVM backend (feature `runtime-microsandbox`)
+- `src/runtimes/opensandbox.rs` — Alibaba OpenSandbox HTTP backend (feature `runtime-opensandbox`)
+- `src/config/runtimes.rs` — `ShellRuntimeConfig` enum, per-backend config structs
+- `src/config/features.rs` — `ContainersConfig`, `ServerToolsConfig`, `ShellLimitsConfig`
+- `src/routes/api/containers.rs` — `GET /v1/containers/{id}`, files, delete
+- `src/routes/api/responses_lookup.rs` — `GET /v1/responses/{id}` with tail-streaming
+- `src/db/repos/containers.rs` — `ContainersRepo`, `ContainerRecord`, `ContainerFileRecord`, `ContainerPatch`
+- `src/db/repos/responses.rs` — `ResponsesRepo`, `ResponseRecord`, owner / org scoping
+- `src/db/repos/response_events.rs` — Persisted SSE events
+- `src/db/{postgres,sqlite}/containers.rs` — Repo impls (keep in sync!)
+- `src/db/{postgres,sqlite}/responses.rs` / `response_events.rs` — Repo impls (keep in sync!)
+- `src/jobs/containers_reaper.rs` — Idle-TTL reaper for containers
+- `src/jobs/background_responses.rs` — Background-response dispatcher
+- `src/jobs/responses_cancel_poller.rs` — Honor cancellation on in-flight background responses
+- `src/jobs/responses_retention.rs` — Retention-driven deletion of `responses` rows
+
 ## Backend — Usage, Cost & Observability
 
 - `src/models/usage.rs` — `UsageLogEntry` with principal attribution fields
diff --git a/agent_instructions/responses_pipeline.md b/agent_instructions/responses_pipeline.md
new file mode 100644
index 0000000..c19702a
--- /dev/null
+++ b/agent_instructions/responses_pipeline.md
@@ -0,0 +1,142 @@
+# Responses API Streaming Pipeline
+
+`/v1/responses` requests run through `services::responses_pipeline::apply_streaming_pipeline`,
+which wraps the upstream provider's SSE stream with input-file staging, guardrails, server-tool
+execution, and DB persistence. This doc covers the order, the actors, and how
+background requests re-enter the same pipeline.
+
+For the broader Responses API + Containers feature, start with `containers.md`. For adding a
+new tool, mirror `services/web_search_tool.rs` or `services/shell_tool.rs`. For the runtime
+side, see `adding_runtime.md`. Server-side MCP support lives under `src/services/mcp/` and the
+MCP wire shape we expose tracks OpenAI's Responses-API MCP tool (see references below).
+
+Two server-executed tools come from the MCP subsystem, both registered in
+`apply_streaming_pipeline` only under `[features.mcp].mode = "hadrian_hosted"`:
+
+- `McpExecutor` (`src/services/mcp/executor.rs`) — intercepts the rewritten
+  `mcp_<label>__<tool>` function calls and runs `tools/call`.
+- `ToolSearchExecutor` (`src/services/mcp/tool_search/`) — for `mcp` entries with
+  `defer_loading: true`, the rewrite injects a single `tool_search` function tool instead of
+  the per-tool functions; this executor ranks the deferred catalog locally
+  (`tool_search/ranker.rs`: lexical / semantic / hybrid-RRF, reusing `cache::EmbeddingService`),
+  emits `tool_search_call` / `tool_search_output` items, and injects the matched function
+  definitions into the continuation so they become callable. Ranking is configured by
+  `[features.mcp.tool_search]` and overridable per request via the `tool_search` tool's
+  `ranker` extension. See `docs/content/docs/features/mcp-tool.mdx` ("Tool search").
+
+## External references
+
+OpenAI's MCP-tool docs we conform to, plus the cookbook walkthrough:
+
+- https://developers.openai.com/api/docs/mcp.md
+- https://developers.openai.com/api/docs/guides/tools-connectors-mcp.md — guide to using
+  remote MCP servers in the Responses API (listing tools, calling tools, approvals, auth).
+- https://r.jina.ai/openai.com/index/new-tools-and-features-in-the-responses-api/
+- https://raw.githubusercontent.com/openai/openai-cookbook/refs/heads/main/examples/mcp/mcp_tool_guide.ipynb
+- https://developers.openai.com/api/docs/guides/tools-tool-search.md
+- https://developers.openai.com/api/docs/guides/tools.md
+
+## Where it lives
+
+- **Entry point**: `routes/api/responses.rs::handle_create_response` for foreground;
+  `services/background_executor.rs::run_background` for background requests pulled off the
+  queue by the `background_responses` job.
+- **Pipeline body**: `services/responses_pipeline.rs::apply_streaming_pipeline`.
+- **Tool loop**: `services/server_tools/runner.rs::ToolLoopRunner`.
+
+## Order of operations (foreground)
+
+1. **Admission** (`routes/api/responses.rs`): auth, RBAC, budget, sovereignty checks. Resolve
+   the request's shell `environment` against `[features.server_tools].shell_limits` and fail
+   fast on cap overruns (`resolve_shell_environment` in `services/shell_tool.rs`).
+2. **Input-file staging** (`services/input_file_staging.rs`): walk `payload.input` for
+   `input_file` parts and resolve each via Files API lookup / base64 / HTTP fetch. Returns
+   `Vec<StagedFile>` ready to write into `/mnt/data`.
+3. **Provider dispatch**: `ResponsesExecutor::execute` runs `preprocess_file_search_tools`,
+   `preprocess_web_search_tools`, and (per-provider) `preprocess_shell_tools` with a
+   `ShellToolHint` built from the resolved environment, then calls the upstream provider for
+   a streaming response.
+4. **Output guardrails** wrap the stream (block / redact per
+   `[features.guardrails].output`).
+5. **Server tool loop** (`ToolLoopRunner`): for each SSE event, every registered tool runs
+   `detect`. Detected calls run in parallel via `execute()`; their `events` stream interleaves
+   into the client stream; their `ToolCallResult` continuation items go into the next
+   provider request. The loop iterates up to `[features.server_tools].max_iterations` (final
+   iteration strips that tool from `payload.tools` so the model has to produce text).
+6. **Response persister** (`services/response_persister.rs`): when persistence is enabled,
+   buffer the full SSE event stream and upsert into `responses` + `response_events` so
+   `/v1/responses/{id}` can replay.
+7. **Webhook fan-out** (`services/responses_webhook.rs`): terminal events fire optional
+   per-org webhooks.
+
+## Background variant
+
+`POST /v1/responses { "background": true }` skips the provider call inline. Instead:
+
+1. The route persists a `responses` row in `queued` state.
+2. `jobs/background_responses.rs` (leader-locked) pulls queued rows and hands them to
+   `services/background_executor.rs::run_background`.
+3. The executor reconstructs the request (auth context comes from the persisted `owner` and
+   `org_id` — see `db/repos/responses.rs`), then enters the *same* `apply_streaming_pipeline`
+   path. SSE events are captured into the `response_events` table rather than streamed to a
+   live client.
+4. `services/response_event_buffer.rs` lets clients stream the response via
+   `GET /v1/responses/{id}?stream=true`, replaying buffered events and tailing new ones.
+
+The skills used at background-execution time are resolved from the persisted owner, NOT the
+request-time principal — this matters when the principal rotates (e.g. API key revoked
+between queue and dispatch).
+
+## Adding a tool to the pipeline
+
+A `ServerExecutedTool` is the unit of work. To add one:
+
+1. Implement the trait (`services/server_tools/mod.rs`). Be careful in `detect()` — it runs
+   for every SSE event, must be cheap, and must use the **canonical detection event** for
+   that call type (e.g. `response.output_item.done`) to avoid duplicate fires on partial
+   events.
+2. Register it in `apply_streaming_pipeline` under whatever feature gate makes sense.
+3. Hook a `format_*` helper for any new SSE event types you emit; mirror existing
+   `response.<tool>.in_progress` / `.completed` shapes.
+4. Update `[features.server_tools].pricing` if there's a per-call cost dimension.
+
+## Invariants (don't regress these)
+
+- **Terminal-state transitions are DB-guarded.** Writing a terminal status
+  (`completed`/`failed`/`cancelled`/`incomplete`) goes through
+  `ResponsesRepo::complete_within_org`, whose UPDATE carries `WHERE status NOT IN (<terminal
+  set>)`. The webhook-once decision and lost-cancel prevention are driven off the affected-row
+  count — never a read-then-write. Without this a late `completed` from the persister clobbers
+  an earlier `cancelled`, and webhooks double-fire under concurrency. `ResponsesStore::cancel`
+  and `response_persister` both rely on this.
+- **Event-log ordering invariant** (`response_event_buffer.rs`): non-terminal events ride the
+  async drainer (`push`); the terminal event is committed synchronously (`insert_sync`), which
+  ratchets `last_sequence_number`. The persister **must** call `buf.flush().await` before the
+  terminal `insert_sync` so all buffered events land first — otherwise a reconnecting
+  `?stream=true` reader sees the terminal event, emits `[DONE]`, and drops the un-flushed tail.
+  The replay loop (`responses_lookup.rs`) treats the log as the truth source and stops on the
+  first terminal event type.
+- **In-progress heartbeat**: while a response streams, the persister stamps
+  `responses.last_heartbeat_at` (throttled). `reap_stuck_in_progress` compares against
+  `COALESCE(last_heartbeat_at, started_at)` so it force-`failed`s only genuinely dead workers,
+  not healthy long-running responses.
+- **Background-worker lifecycle**: the retention / reaper / background-response / cancel-poller /
+  cleanup workers are spawned on `state.task_tracker` (not raw `tokio::spawn`) and select on the
+  shutdown `CancellationToken` rather than a bare `sleep`. `drain_background_tasks` only awaits
+  the tracker, so an untracked worker is abandoned on SIGTERM and its in-flight `background=true`
+  response gets force-reaped as `worker_lost`. The per-execution task in
+  `background_responses.rs` is also tracked so it drains.
+- **Background retry** (`run_with_retry`): a failed attempt's partial events stay in
+  `response_events`; the next attempt re-loads the row and continues from
+  `last_sequence_number` (and bumps `started_at`/heartbeat so the reaper doesn't kill the retry).
+
+## Common edits
+
+- **Reorder pipeline stages**: only do this with a real reason. Guardrails-before-tools is
+  intentional (the guardrail can short-circuit before any tool spends money). Persister-last
+  is intentional (we persist what the client actually saw).
+- **Add an SSE transformer that changes existing events**: implement `transform_event` on the
+  tool. The runner calls it for every outgoing event. Use interior mutability for stateful
+  transforms (see `ShellExecutor::transform_event` for citation injection).
+- **Skip the pipeline entirely**: `has_enabled_tools()` returns false → the runner falls
+  through with the original stream unchanged. That's the right behavior when nothing applies.
diff --git a/agent_instructions/testing.md b/agent_instructions/testing.md
index e918bee..36d86d3 100644
--- a/agent_instructions/testing.md
+++ b/agent_instructions/testing.md
@@ -6,11 +6,25 @@ Unit tests go in the same file as the code (`#[cfg(test)]`). Test both SQLite an
 
 ## E2E Tests
 
+Build the gateway image first, then run the suite:
+
+```bash
+docker build -t hadrian:local .   # From repo root — builds the image the compose files reference
+cd deploy/tests && pnpm test      # Run all E2E tests
+```
+
+Uses TypeScript test suite with testcontainers. The docker-compose files
+(`deploy/docker-compose.*.yml`) reference `image: hadrian:local`, and the test
+harness rebuilds it on every `compose.up()` by default — which is slow. Pre-build
+it once with the command above and set `SKIP_BUILD=1` to reuse it:
+
 ```bash
-cd deploy/tests && pnpm test    # Run all E2E tests
+docker build -t hadrian:local .
+cd deploy/tests && SKIP_BUILD=1 pnpm test
 ```
 
-Uses TypeScript test suite with testcontainers.
+Rebuild the image when you want to test your latest changes; `SKIP_BUILD=1` runs
+against whatever `hadrian:local` currently points at.
 
 ## Provider Testing (Wiremock)
 
diff --git a/deny.toml b/deny.toml
index a23d696..86f02c1 100644
--- a/deny.toml
+++ b/deny.toml
@@ -24,6 +24,20 @@ ignore = [
     # `rand::rng()` during trace-level logging. Hadrian uses `tracing-subscriber`, so the
     # affected code path is unreachable. Pulled in transitively via augurs, kreuzberg, sqlx.
     { id = "RUSTSEC-2026-0097", reason = "unreachable: hadrian has no custom log::Log impl that invokes rand::rng()" },
+    # hickory-proto 0.25.2 NSEC3 closest-encloser unbounded loop. Pulled in only by
+    # microsandbox-network (the `runtime-microsandbox` feature) for in-microVM DNS
+    # resolution behind the sandbox egress allowlist. The vulnerable DnssecDnsHandle
+    # only compiles with the `dnssec-ring`/`dnssec-aws-lc-rs` features, which
+    # microsandbox-network does not enable, so the path is not built. No safe upgrade
+    # exists for 0.25.x; a fix requires a microsandbox bump (0.4.6 pins an
+    # incompatible hickory line — see the dependency comment in Cargo.toml). Hadrian's
+    # own resolver uses hickory-resolver 0.26.1. Mirrors .cargo/audit.toml.
+    { id = "RUSTSEC-2026-0118", reason = "unreachable: dnssec features not enabled on microsandbox-network's hickory-client; no 0.25.x fix" },
+    # hickory-proto 0.25.2 O(n²) name-compression CPU exhaustion. Same provenance as
+    # RUSTSEC-2026-0118: microsandbox-network's in-microVM DNS behind the egress
+    # allowlist. Fixed in hickory-proto 0.26.1, which microsandbox 0.4.5 cannot adopt.
+    # Mirrors .cargo/audit.toml.
+    { id = "RUSTSEC-2026-0119", reason = "limited reach: microsandbox-network in-microVM DNS only; no 0.25.x fix until microsandbox bump" },
 ]
 
 # Licenses - ensure all dependencies use acceptable licenses
@@ -32,6 +46,7 @@ confidence-threshold = 0.8
 allow = [
     "MIT",
     "MIT-0",
+    "0BSD",
     "Apache-2.0",
     "Apache-2.0 WITH LLVM-exception",
     "BSD-2-Clause",
diff --git a/deploy/tests/src/tests/shared/api-policy-enforcement.ts b/deploy/tests/src/tests/shared/api-policy-enforcement.ts
index 635b8f9..8827c8c 100644
--- a/deploy/tests/src/tests/shared/api-policy-enforcement.ts
+++ b/deploy/tests/src/tests/shared/api-policy-enforcement.ts
@@ -420,7 +420,7 @@ export function runApiPolicyEnforcementTests(
           body: JSON.stringify({
             model: "test/test-model",
             input: "Search the files for information about testing.",
-            tools: [{ type: "file_search" }],
+            tools: [{ type: "file_search", vector_store_ids: ["vs_test"] }],
           }),
         });
 
@@ -440,7 +440,7 @@ export function runApiPolicyEnforcementTests(
           body: JSON.stringify({
             model: "test/test-model",
             input: "Search the files for information about testing.",
-            tools: [{ type: "file_search" }],
+            tools: [{ type: "file_search", vector_store_ids: ["vs_test"] }],
           }),
         });
 
diff --git a/docs/components/quick-start-selector.tsx b/docs/components/quick-start-selector.tsx
index 39c36b5..0c8bc1e 100644
--- a/docs/components/quick-start-selector.tsx
+++ b/docs/components/quick-start-selector.tsx
@@ -65,6 +65,7 @@ const featureMatrix: { name: string; profiles: Profile[] }[] = [
   { name: "PostgreSQL", profiles: ["standard", "headless", "full"] },
   { name: "Redis caching", profiles: ["standard", "headless", "full"] },
   { name: "SSO (OIDC / OAuth)", profiles: ["standard", "headless", "full"] },
+  { name: "Server-side MCP", profiles: ["standard", "headless", "full"] },
   { name: "CEL RBAC", profiles: ["standard", "headless", "full"] },
   { name: "S3 storage", profiles: ["standard", "headless", "full"] },
   { name: "Secrets managers", profiles: ["standard", "headless", "full"] },
@@ -79,6 +80,8 @@ const featureMatrix: { name: string; profiles: Profile[] }[] = [
   { name: "SAML SSO", profiles: ["headless", "full"] },
   { name: "Kreuzberg OCR", profiles: ["headless", "full"] },
   { name: "ClamAV scanning", profiles: ["headless", "full"] },
+  { name: "Microsandbox containers", profiles: ["headless", "full"] },
+  { name: "OpenSandbox containers", profiles: ["headless", "full"] },
 ];
 
 function getInstallCommand(method: Method, os: OS, profile: Profile, libc: Libc): string {
diff --git a/docs/content/docs/configuration/index.mdx b/docs/content/docs/configuration/index.mdx
index 49853f8..405b589 100644
--- a/docs/content/docs/configuration/index.mdx
+++ b/docs/content/docs/configuration/index.mdx
@@ -30,5 +30,6 @@ api_key = "${OPENAI_API_KEY}"
   <Card title="Providers" href="/docs/configuration/providers" />
   <Card title="Authentication" href="/docs/configuration/auth" />
   <Card title="Features" href="/docs/configuration/features" />
+  <Card title="Storage" href="/docs/configuration/storage" />
   <Card title="Observability" href="/docs/configuration/observability" />
 </Cards>
diff --git a/docs/content/docs/configuration/meta.json b/docs/content/docs/configuration/meta.json
index 23d80be..0f1623e 100644
--- a/docs/content/docs/configuration/meta.json
+++ b/docs/content/docs/configuration/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "Configuration",
-  "pages": ["index", "builder", "server", "database", "providers", "auth", "features", "observability"]
+  "pages": ["index", "builder", "server", "database", "providers", "auth", "features", "storage", "observability"]
 }
diff --git a/docs/content/docs/configuration/storage.mdx b/docs/content/docs/configuration/storage.mdx
new file mode 100644
index 0000000..19df1df
--- /dev/null
+++ b/docs/content/docs/configuration/storage.mdx
@@ -0,0 +1,164 @@
+---
+title: Storage Configuration
+description: Where Hadrian stores file bytes — database, local filesystem, or S3-compatible object storage
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+The `[storage]` section controls where Hadrian persists the **bytes** of files. File
+_metadata_ (ids, names, sizes, ownership) always lives in the database; this section only
+governs where the raw content is written.
+
+There are two independent storage targets:
+
+| Section                     | Holds                                                                                                                                          |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[storage.files]`           | Files API objects (`/v1/files`) — the same resource that backs Knowledge Bases and Responses-API `input_file` references.                      |
+| `[storage.container_files]` | Container output files — artifacts the agentic shell tool captures under `/mnt/data` and serves from `/v1/containers/{id}/files/{id}/content`. |
+
+Both default to the `database` backend and are configured the same way, so you can keep
+small uploaded files inline in the database while routing bulky agent-generated artifacts to
+object storage.
+
+## Backends
+
+<Callout type="info">
+  Each target's `backend` is independent. A common production layout is `database` for
+  `[storage.files]` and `s3` for `[storage.container_files]`.
+</Callout>
+
+| Backend      | Where bytes live                              | Best for                                                                     |
+| ------------ | --------------------------------------------- | ---------------------------------------------------------------------------- |
+| `database`   | A `BYTEA` / `BLOB` column on the metadata row | Small deployments, quick start. Scales poorly for large or numerous files.   |
+| `filesystem` | Local disk under a configured directory       | Single-node deployments with large files.                                    |
+| `s3`         | An S3-compatible bucket                       | Production, multi-node deployments. Requires the `s3-storage` build feature. |
+
+<Callout type="warn">
+  The `database` backend stores file bytes directly in the database. This is simple but inflates
+  database size and backup time, and bottlenecks large reads/writes on the database connection pool.
+  For container artifacts in particular — which can be large and numerous — prefer `filesystem` or
+  `s3` in production.
+</Callout>
+
+## Database backend (default)
+
+No configuration is required. This is the behavior you get out of the box:
+
+```toml
+[storage.files]
+backend = "database"
+
+[storage.container_files]
+backend = "database"
+```
+
+## Filesystem backend
+
+Stores each file as `{path}/{file-id}`. Suitable for single-node deployments; for multi-node
+the directory must be a shared volume (NFS, EFS) reachable by every node.
+
+```toml
+[storage.container_files]
+backend = "filesystem"
+
+[storage.container_files.filesystem]
+path = "/var/hadrian/container-files"
+create_dir = true   # create the directory on startup if missing (default: true)
+file_mode = 384     # decimal for 0o600; Unix file permissions for new files
+dir_mode = 448      # decimal for 0o700; Unix directory permissions
+```
+
+| Setting      | Type   | Default       | Description                                                                             |
+| ------------ | ------ | ------------- | --------------------------------------------------------------------------------------- |
+| `path`       | string | _(required)_  | Base directory for stored files.                                                        |
+| `create_dir` | bool   | `true`        | Create `path` on startup if it does not exist.                                          |
+| `file_mode`  | int    | `384` (0o600) | Unix permission bits for new files. TOML has no octal literal — give the decimal value. |
+| `dir_mode`   | int    | `448` (0o700) | Unix permission bits for the created directory.                                         |
+
+<Callout type="info">
+  Reads, deletes, and existence checks are confined to `path`: any stored reference that resolves
+  outside the configured root (via `..`, an absolute path, or a symlink) is rejected. A tampered
+  database row cannot be used to read or delete arbitrary files on the host.
+</Callout>
+
+## S3 backend
+
+Works with AWS S3 and any S3-compatible service — MinIO, Cloudflare R2, DigitalOcean Spaces,
+Backblaze B2, and others. Requires building with the `s3-storage` feature (included in the
+`standard` and `full` profiles):
+
+```bash
+cargo build --features s3-storage
+```
+
+```toml
+[storage.container_files]
+backend = "s3"
+
+[storage.container_files.s3]
+bucket = "hadrian-container-artifacts"
+region = "us-east-1"
+key_prefix = "containers/"   # objects stored as containers/<file-id>
+# Credentials resolve from env (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY)
+# or the instance IAM role when omitted.
+```
+
+| Setting                  | Type   | Default       | Description                                                            |
+| ------------------------ | ------ | ------------- | ---------------------------------------------------------------------- |
+| `bucket`                 | string | _(required)_  | Bucket name.                                                           |
+| `region`                 | string | _(none)_      | AWS region. Required unless `endpoint` is set.                         |
+| `endpoint`               | string | _(none)_      | Custom endpoint URL for non-AWS services.                              |
+| `access_key_id`          | string | _(env / IAM)_ | Access key. Falls back to environment / IAM role when omitted.         |
+| `secret_access_key`      | string | _(env / IAM)_ | Secret key. Falls back to environment / IAM role when omitted.         |
+| `force_path_style`       | bool   | `false`       | Use path-style URLs. Required for MinIO and many self-hosted services. |
+| `key_prefix`             | string | _(none)_      | Prefix prepended to every object key. Useful when sharing a bucket.    |
+| `storage_class`          | string | _(none)_      | Object storage class (e.g. `STANDARD_IA`, `GLACIER`).                  |
+| `server_side_encryption` | table  | _(none)_      | Server-side encryption — see below.                                    |
+
+<Callout type="warn">
+  Prefer environment variables or an IAM role over inlining `access_key_id` / `secret_access_key` in
+  the config file. When present, these values are redacted from logs.
+</Callout>
+
+### S3-compatible endpoints
+
+```toml
+# MinIO
+[storage.container_files.s3]
+bucket = "hadrian"
+endpoint = "http://minio:9000"
+force_path_style = true
+access_key_id = "${MINIO_ACCESS_KEY}"
+secret_access_key = "${MINIO_SECRET_KEY}"
+
+# Cloudflare R2
+[storage.container_files.s3]
+bucket = "hadrian"
+endpoint = "https://<account-id>.r2.cloudflarestorage.com"
+region = "auto"
+```
+
+### Server-side encryption
+
+```toml
+# SSE-S3 (Amazon-managed keys)
+[storage.container_files.s3.server_side_encryption]
+type = "aes256"
+
+# SSE-KMS (AWS KMS keys)
+[storage.container_files.s3.server_side_encryption]
+type = "kms"
+key_id = "arn:aws:kms:us-east-1:123456789:key/abc123"
+```
+
+## How routing works
+
+The backend recorded for a target applies to files written **from that point forward**. Each
+stored file's row records which backend produced it, so reads continue to resolve correctly
+even after you switch backends — existing `database` rows keep serving their inline bytes
+while new files land in `filesystem` / `s3`. Switching backends does **not** migrate existing
+content; plan a one-off migration if you need every object in the new backend.
+
+## Related
+
+- [Agents & the shell tool](/docs/features/agents) — what produces container files.
diff --git a/docs/content/docs/features/agents.mdx b/docs/content/docs/features/agents.mdx
new file mode 100644
index 0000000..e97afe4
--- /dev/null
+++ b/docs/content/docs/features/agents.mdx
@@ -0,0 +1,383 @@
+---
+title: Agents & Shell Tool
+description: Run shell commands in a persistent container as part of a Responses API call. Works behind any LLM provider, with pluggable execution backends.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Hadrian extends the OpenAI-compatible `/v1/responses` API with an **agentic shell tool**:
+the model can execute shell commands, write and read files in a persistent workspace, and
+chain that work across multiple turns. Inspired by [OpenAI's Responses API computer
+environment](https://openai.com/index/equip-responses-api-computer-environment/) and modeled
+on the [shell tool spec](https://developers.openai.com/api/docs/guides/tools-shell.md),
+extended to **work behind any provider Hadrian supports** — not just OpenAI.
+
+## At a glance
+
+- **Containers** — every shell call runs in a persistent Linux container scoped by a
+  `cntr_<id>`. Reuse across responses via `previous_response_id`; reaped on idle TTL.
+- **Workspace** — `/mnt/data` is the writable workdir. Files you upload via `input_file`
+  parts land here; files the model writes here are captured and downloadable.
+- **Provider agnostic** — the shell tool spec is the same OpenAI-shaped
+  `{"type": "shell"}`. Hadrian rewrites it to a function tool for providers that don't have
+  a native equivalent (Anthropic, Bedrock, Vertex), so any model with tool-use support can
+  drive it.
+- **Pluggable runtimes** — choose how shell calls are executed: OpenAI's hosted container,
+  the API client itself, or a Hadrian-hosted sandbox (`microsandbox`, `opensandbox`).
+- **Background mode** — submit with `{"background": true}` and stream results later via
+  `GET /v1/responses/{id}?stream=true`.
+
+## Runtimes
+
+Configure under `[features.shell]` in `hadrian.toml`:
+
+| Runtime              | Where execution happens              | When to use                                                                                                           |
+| -------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `passthrough_openai` | OpenAI's hosted container            | You're using `gpt-5.2+` and want zero infrastructure.                                                                 |
+| `client_passthrough` | Your application code                | You want OpenAI's "local shell" UX behind any provider — Hadrian routes the call but doesn't execute it.              |
+| `microsandbox`       | Hadrian process, per-request microVM | You want isolated, hosted sandboxes without an external sandbox service. Behind cargo feature `runtime-microsandbox`. |
+| `opensandbox`        | Remote OpenSandbox Lifecycle API     | You're running a managed sandbox service (e.g. Alibaba OpenSandbox). Behind cargo feature `runtime-opensandbox`.      |
+
+```toml
+# Use OpenAI's hosted container
+[features.shell]
+type = "passthrough_openai"
+
+# Or have your client execute calls (works behind any provider)
+[features.shell]
+type = "client_passthrough"
+
+# Or host the sandbox yourself
+[features.shell]
+type = "microsandbox"
+image = "alpine"
+cpus = 1
+memory_mb = 512
+```
+
+`passthrough_openai` requires an OpenAI / Azure OpenAI upstream. Requests routed to any
+other provider (Anthropic, Bedrock, Vertex, etc.) reject with HTTP 400, error code
+`shell_passthrough_unsupported_provider`, and a message naming the provider that's
+unable to run the hosted shell tool. `client_passthrough` works behind **any** supported
+provider; non-OpenAI providers see a `function_call` with `name="shell"` instead of
+OpenAI's native `shell_call`, but the wire-level call data is the same.
+
+### Long-running services
+
+Each `exec()` returns when its own command exits, but the container's VM (or remote
+sandbox) keeps running between calls. A model that detaches a process — `nohup python
+server.py &`, `disown`, `setsid …`, a launched systemd-style supervisor — leaves that
+process alive in the container, observable from subsequent shell calls in the same
+session (i.e. the same `previous_response_id` chain or `container_reference`). The
+container's idle TTL still applies: a session that goes longer than
+`default_idle_ttl_secs` without a shell call is reaped and any detached processes go
+down with it.
+
+## Using the shell tool
+
+The wire format matches OpenAI's. Send a `/v1/responses` request with a `shell` tool
+declared and optional environment overrides:
+
+```json
+{
+  "model": "gpt-5.2",
+  "input": "Plot the residuals in residuals.csv and write the chart to /mnt/data/chart.png.",
+  "tools": [
+    {
+      "type": "shell",
+      "environment": {
+        "type": "container_auto",
+        "memory_limit": "1g",
+        "expires_after": { "anchor": "last_active_at", "minutes": 30 },
+        "network_policy": {
+          "type": "allowlist",
+          "allowed_domains": ["pypi.org", "files.pythonhosted.org"],
+          "domain_secrets": [
+            { "domain": "api.github.com", "name": "GITHUB_TOKEN", "value": "ghp_…" }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+To attach to an existing container (created via `POST /v1/containers` or
+chained from an earlier response), use `container_reference`:
+
+```json
+{
+  "model": "gpt-5.2",
+  "input": "Continue from where we left off.",
+  "tools": [
+    {
+      "type": "shell",
+      "environment": {
+        "type": "container_reference",
+        "container_id": "cntr_abc123…"
+      }
+    }
+  ]
+}
+```
+
+The `domain_secrets` array accepts either OpenAI's inline form
+(`{ domain, name, value }` — the raw secret travels with the request)
+or Hadrian's safer reference form (`{ placeholder, allowed_domains }`,
+matched against `[features.server_tools.shell_limits].allowed_domain_secrets`
+so the value never leaves the gateway).
+
+The model emits shell calls; Hadrian executes them and streams the spec-canonical output
+item lifecycle:
+
+- `response.output_item.added` carrying a `shell_call` item with `status: "in_progress"` —
+  fires before container boot, so SDKs see the item as soon as the request lands.
+- `response.output_item.added` carrying a placeholder `shell_call_output` item with
+  `status: "in_progress"` — paired with the call above.
+- `response.output_item.done` carrying the final `shell_call` item (status `completed` or
+  `incomplete`) with the resolved `environment.container_reference`.
+- `response.output_item.done` carrying the `shell_call_output` item — full stdout / stderr,
+  `outcome` (`{type: "exit", exit_code}` or `{type: "timeout"}`), plus the Hadrian-extension
+  `output_files` array listing every artifact captured under `/mnt/data`.
+
+OpenAI's Responses streaming spec has no per-delta event for the shell tool: stdout and
+stderr surface only on the terminal `output_item.done`, not as incremental chunks. SDKs
+typed against the API stream pick the lifecycle up generically.
+
+Output longer than 8&nbsp;000 characters is head + tail trimmed before being fed back to the
+model, so it should redirect long output to a file under `/mnt/data` and follow up with
+`grep` / `tail`. The function-mode tool description Hadrian sends to non-OpenAI providers
+embeds this guidance explicitly.
+
+## Files
+
+### Inputs
+
+Attach files to a request with `input_file` parts. Three source modes:
+
+```json
+{
+  "input": [
+    {
+      "role": "user",
+      "content": [
+        { "type": "input_text", "text": "Summarize this CSV." },
+        { "type": "input_file", "file_id": "file_abc123" },
+        { "type": "input_file", "file_url": "https://example.com/dataset.csv" },
+        { "type": "input_file", "file_data": "data:text/csv;base64,..." }
+      ]
+    }
+  ]
+}
+```
+
+- `file_id` — looks up a file already uploaded via the standard
+  [Files API](/docs/api). The same `/v1/files` resource that backs Knowledge Bases is
+  reused; you don't need a parallel uploads endpoint just for shell-tool inputs.
+- `file_url` — HTTPS fetch with SSRF protection.
+- `file_data` — inline base64 (data URL).
+
+All resolved files land at `/mnt/data/<filename>` before the first shell command runs.
+
+### Outputs
+
+Anything the model writes under `/mnt/data` is captured into the container's file store and
+surfaced two ways:
+
+1. Inline as `container_file_citation` annotations on the assistant's reply.
+2. Downloadable from `GET /v1/containers/{cntr_id}/files/{cfile_id}/content`.
+
+<Callout type="info">
+  Container output files are a **separate** resource from the Files API (`/v1/files`). To feed a
+  container output back into a knowledge base, download it from the container endpoint and re-upload
+  via `/v1/files`.
+</Callout>
+
+Where the captured bytes physically live is configurable. By default they sit inline in the
+database, which scales poorly for large or numerous artifacts; point
+`[storage.container_files]` at the local filesystem or an S3-compatible bucket to offload
+them. See [Storage configuration](/docs/configuration/storage).
+
+## Containers
+
+Every shell-tool response provisions a container. You can also create one explicitly with
+`POST /v1/containers` and bind future responses to it via
+`environment.type = "container_reference"`:
+
+```
+POST   /v1/containers                                  # Create an empty container
+GET    /v1/containers/{cntr_id}                        # Metadata + TTL
+DELETE /v1/containers/{cntr_id}                        # Tear down + cascade delete files
+POST   /v1/containers/{cntr_id}/files                  # Multipart upload into /mnt/data
+GET    /v1/containers/{cntr_id}/files                  # List files in /mnt/data
+GET    /v1/containers/{cntr_id}/files/{id}             # File metadata
+DELETE /v1/containers/{cntr_id}/files/{id}             # Remove a file
+GET    /v1/containers/{cntr_id}/files/{id}/content     # Raw bytes
+```
+
+`POST /v1/containers` accepts:
+
+```json
+{
+  "name": "my-workspace",
+  "memory_limit": "1g",
+  "expires_after": { "anchor": "last_active_at", "minutes": 60 },
+  "network_policy": {
+    "type": "allowlist",
+    "allowed_domains": ["pypi.org"]
+  },
+  "skills": [
+    { "type": "skill_reference", "skill_id": "<uuid>", "version": "latest" },
+    {
+      "type": "inline",
+      "name": "extract-csv",
+      "description": "Inline ephemeral skill",
+      "source": {
+        "type": "base64",
+        "media_type": "text/markdown",
+        "data": "IyBleHRyYWN0LWNzdgo="
+      }
+    }
+  ]
+}
+```
+
+`skill_reference` resolves to a stored skill by UUID. `inline` carries the bundle on
+the request itself — today only `media_type: "text/markdown"` is supported (decoded as
+the synthetic `SKILL.md`); multi-file (`application/zip`) inline skills reject with
+`unsupported_inline_skill_media_type`. `version` accepts `"latest"` only — passing
+anything else rejects with `unsupported_skill_version` so a future versioned-skills
+release doesn't silently downgrade requests that wanted a pin.
+
+Containers can also be enumerated:
+
+```
+GET /v1/containers?limit=20&after=<cntr_id>
+```
+
+Returns the OpenAI-shaped list envelope `{ "object": "list", "data": [...],
+"first_id": "...", "last_id": "...", "has_more": true }`, newest-first, scoped to the
+caller's org.
+
+The row is created with no live VM; the runtime boots on the first shell call that references
+it. Chain across responses by sending `previous_response_id` for implicit reuse, or
+`environment.type = "container_reference"` for explicit attachment.
+
+### TTL & expiry
+
+`GET /v1/containers/{id}` returns:
+
+- `created_at` — when the container was provisioned.
+- `last_active_at` — moves forward on every shell call.
+- `expires_at` — **Hadrian extension.** For active containers this is a forward-looking
+  estimate (`last_active_at + idle_ttl_secs`); for terminal statuses it's the actual
+  transition time. Lets you plan reuse without polling.
+- `idle_ttl_secs` — **Hadrian extension.** The TTL applied to this row, so you can recompute
+  `expires_at` yourself.
+
+A background reaper marks rows `expired` once `now > last_active_at + idle_ttl_secs`. The
+default TTL is 20 minutes (configurable as `[features.containers].default_idle_ttl_secs`),
+matching OpenAI's hosted-container behavior.
+
+## Sandboxing (Hadrian-hosted runtimes)
+
+For `microsandbox` and `opensandbox`, every request can request a narrower environment
+than the operator's defaults, but the request is bounded by what the operator pins in
+`[features.server_tools.shell_limits]`:
+
+- **Memory** — `default_mem_limit_mb`, `max_mem_limit_mb`. Per-request `memory_limit`
+  must fit inside the cap.
+- **Egress** — `allowed_egress_hosts` is an operator allowlist; per-request
+  `network_policy.allowed_domains` must be a subset. Empty allowlist = inherit the runtime
+  default (microsandbox: full network; opensandbox: deny-all).
+- **Domain secrets** — `allowed_domain_secrets` lets the operator pre-configure
+  placeholder secrets (e.g. `GITHUB_TOKEN`) that the model can refer to by name without
+  ever seeing the value. Per-request `network_policy.domain_secrets[].allowed_domains`
+  must be a subset.
+- **Command timeout** — `command_timeout_secs` caps each individual shell exec.
+
+## Context compaction
+
+OpenAI's Responses API supports a `context_management` directive that triggers server-side
+compaction when the rolling token estimate crosses a threshold. Hadrian forwards the
+directive **verbatim** to providers that support it natively (OpenAI, Azure OpenAI); for
+every other provider (Anthropic, Bedrock, Vertex) it runs a **gateway-side compactor**
+before dispatch.
+
+```json
+"context_management": [
+  {
+    "type": "compaction",
+    "compact_threshold": 8000,
+    "strategy": "llm",
+    "prompt": "Summarize prior turns in <= 200 words; preserve constraints + file paths."
+  }
+]
+```
+
+Two strategies, picked by the request's Hadrian-extension `strategy` field (defaulting to
+`[features.responses.compaction].default_strategy`):
+
+- **`truncate`** — Drop the oldest non-system items until the estimate falls under the
+  threshold, replacing them with a single Hadrian compaction marker message. Free, deterministic.
+- **`llm`** — Summarise the dropped items via a one-shot call to the same provider/model
+  (using the `prompt` field — or `default_prompt` — to drive the summariser), and replace
+  them with a system message carrying the summary.
+
+Operator defaults live under `[features.responses.compaction]`:
+
+```toml
+[features.responses.compaction]
+enabled = true                     # default false — opt in to gateway compaction
+default_strategy = "truncate"      # "llm" | "truncate"
+default_threshold_tokens = 12_000  # falls back to this when the request omits it
+keep_recent_items = 6              # most recent N items are never compacted
+default_prompt = "..."             # summarisation prompt for the llm strategy
+```
+
+## Background mode
+
+Long-running requests run asynchronously:
+
+```json
+{
+  "model": "gpt-5.2",
+  "background": true,
+  "input": "Run the full data pipeline.",
+  "tools": [{ "type": "shell" }]
+}
+```
+
+Returns immediately with a `resp_<id>`. Tail with:
+
+```
+GET /v1/responses/{resp_id}?stream=true
+```
+
+A background worker picks up the queued response, runs it through the same pipeline as
+foreground requests, and persists every SSE event so clients can resume the stream from any
+point — including reconnecting after the server restarts.
+
+Pass `?starting_after=N` alongside `?stream=true` to resume the SSE stream from a specific
+sequence number; events are emitted in OpenAI's named-SSE form (`event: <type>\ndata: <payload>`)
+so SDK clients pick up the typed events they expect.
+
+## How it compares
+
+| Capability                    | Hadrian                    | OpenAI Responses | Anthropic      | Bedrock AgentCore | Gemini |
+| ----------------------------- | -------------------------- | ---------------- | -------------- | ----------------- | ------ |
+| Persistent container handle   | ✓                          | ✓                | ✓ (30-day TTL) | ✓ (session VM)    | —      |
+| Reuse across turns            | ✓ (`previous_response_id`) | ✓                | ✓              | ✓                 | —      |
+| Client-executed mode          | ✓ (`client_passthrough`)   | ✓                | ✓ (bash tool)  | —                 | —      |
+| Per-request network allowlist | ✓                          | ✓                | — (no network) | configurable      | —      |
+| Files via existing Files API  | ✓                          | ✓                | ✓              | ✓ (S3 / EFS)      | ✓      |
+| Background / long-running     | ✓                          | ✓                | —              | ✓                 | —      |
+
+## See also
+
+- [Knowledge Bases](/docs/features/knowledge-bases) — for retrieval, not execution.
+- [Web Tools](/docs/features/web-tools) — server-side web search / URL fetch.
+- [MCP Tool](/docs/features/mcp-tool) — server-side `{"type": "mcp"}` tool on `/v1/responses`,
+  for calling remote Model Context Protocol servers (Atlassian, Notion, GitHub, …).
+- [Skills](/docs/features/skills) — mountable bundles available to the shell tool when
+  supported by the runtime.
diff --git a/docs/content/docs/features/mcp-tool.mdx b/docs/content/docs/features/mcp-tool.mdx
new file mode 100644
index 0000000..97fc7ef
--- /dev/null
+++ b/docs/content/docs/features/mcp-tool.mdx
@@ -0,0 +1,296 @@
+---
+title: MCP Tool (Responses API)
+description: Call remote Model Context Protocol servers from `/v1/responses` — either passthrough to OpenAI/Azure or run the client loop in the gateway via `rmcp`.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Hadrian's `/v1/responses` accepts OpenAI's [`mcp` tool](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) — `{"type": "mcp", server_url, server_label, authorization, ...}` — so a model can call tools exposed by any remote Model Context Protocol server (Atlassian, Notion, GitHub, HuggingFace, Vercel, …).
+
+<Callout type="info">
+  This page describes the **server-side** `mcp` tool on `/v1/responses`. For the browser-based MCP
+  client in the chat UI, see [MCP Integration](/docs/features/mcp). For coding agents bridged via
+  MCP, see [Agents via MCP](/docs/features/mcp-agents).
+</Callout>
+
+## Modes
+
+| Mode                 | Where the MCP loop runs                | Provider support          |
+| -------------------- | -------------------------------------- | ------------------------- |
+| `passthrough_openai` | OpenAI / Azure OpenAI servers          | OpenAI, Azure OpenAI only |
+| `hadrian_hosted`     | Hadrian gateway (via the `rmcp` crate) | All providers             |
+
+Both modes ship; pick one by setting `[features.mcp].mode`. `passthrough_openai` is zero-cost forwarding and gives you OpenAI's first-party MCP optimizations. `hadrian_hosted` makes MCP work behind any provider Hadrian supports (Anthropic, Bedrock, Vertex, Test) and gives the gateway visibility into every call — the tradeoff is one extra network hop per `tools/call`.
+
+## Enabling the feature
+
+Add an `[features.mcp]` section to `hadrian.toml`:
+
+```toml
+[features.mcp]
+enabled = true
+mode = "passthrough_openai"
+
+# Optional: restrict which remote MCP servers callers may target.
+# Omit to accept any URL the caller supplies (the caller already
+# controls Authorization, so this is defense-in-depth).
+# allowed_server_urls = ["https://mcp.atlassian.com/v1/mcp"]
+
+# Default false. Flip to true only when the upstream is OpenAI/Azure
+# AND the connector_id is known to work. Self-hosted gateways can't
+# reach OpenAI's first-party connector registry.
+allow_connector_ids = false
+
+# Default upper bound (seconds) on a single tools/call under
+# hadrian_hosted. rmcp/reqwest apply no timeout of their own, so without
+# this an unresponsive MCP server would hang the response. Override per
+# tool with the `call_timeout_secs` field on the mcp tool entry.
+call_timeout_secs = 300
+```
+
+## Wire format
+
+A `/v1/responses` request declares an `mcp` tool entry alongside any other tools:
+
+```json
+{
+  "model": "gpt-5.2",
+  "input": "What's the status of issue ENG-1234?",
+  "tools": [
+    {
+      "type": "mcp",
+      "server_label": "atlassian",
+      "server_url": "https://mcp.atlassian.com/v1/mcp",
+      "authorization": "Bearer ya29...",
+      "require_approval": "never",
+      "allowed_tools": ["jira_issue_get", "jira_search"]
+    }
+  ]
+}
+```
+
+The caller obtains the bearer token out-of-band (their own OAuth flow against Atlassian / GitHub / etc.). Hadrian forwards the `authorization` field verbatim and **never persists it** — clients must include it on every request.
+
+### Field reference
+
+| Field                       | Type                              | Required | Notes                                                                                                                                                                                                                                                                                                             |
+| --------------------------- | --------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`                      | `"mcp"`                           | yes      |                                                                                                                                                                                                                                                                                                                   |
+| `server_label`              | string                            | yes      | Stable identifier surfaced in `mcp_list_tools` / `mcp_call` items.                                                                                                                                                                                                                                                |
+| `server_url`                | string                            | one of   | URL of the remote MCP server (Streamable HTTP). Mutually exclusive with `connector_id`.                                                                                                                                                                                                                           |
+| `connector_id`              | string                            | one of   | OpenAI first-party connector id (e.g. `connector_googlecalendar`). Requires `allow_connector_ids = true`.                                                                                                                                                                                                         |
+| `server_description`        | string                            |          | Human-readable description surfaced to the model.                                                                                                                                                                                                                                                                 |
+| `authorization`             | string                            |          | Bearer or OAuth access token. Caller-supplied, never persisted.                                                                                                                                                                                                                                                   |
+| `headers`                   | `Record<string, string>`          |          | Extra HTTP headers sent with every JSON-RPC call (region / workspace selectors).                                                                                                                                                                                                                                  |
+| `require_approval`          | `"always"` \| `"never"` \| object |          | Object form mirrors OpenAI's `MCPToolApprovalFilter`: `{ "always": { "tool_names": ["x"] }, "never": { "tool_names": ["y"] } }` — gate the tools under `always`, exempt those under `never`.                                                                                                                      |
+| `allowed_tools`             | `string[]` or object              |          | Whitelist of tool names. Object form: `{ tool_names: ["..."] }`.                                                                                                                                                                                                                                                  |
+| `defer_loading`             | boolean                           |          | Discover this server's tools via [tool search](#tool-search-deferred-tools) rather than loading them all into the prompt. Under `hadrian_hosted`, Hadrian runs the search locally (works behind any provider).                                                                                                    |
+| `defer_loading_passthrough` | boolean                           |          | **Hadrian extension.** With `defer_loading`, forward the flag to the upstream's native tool search instead of running Hadrian-side search. OpenAI/Azure only; rejected (400 `mcp_defer_loading_passthrough_unsupported`) on other providers.                                                                      |
+| `call_timeout_secs`         | integer                           |          | **Hadrian extension.** Upper bound, in seconds, on a single `tools/call` round-trip under `hadrian_hosted`. Overrides the `[features.mcp].call_timeout_secs` deployment default (300s). On expiry the `mcp_call` terminates with `status="incomplete"` and a timeout `error`. Ignored under `passthrough_openai`. |
+
+### Item types
+
+Under `passthrough_openai`, OpenAI emits the canonical item lifecycle on the response stream:
+
+- `mcp_list_tools` — snapshot of tools the model could call against the server. Surfaces `error` inline when `tools/list` fails.
+- `mcp_call` — model-initiated invocation. Carries `name`, `arguments` JSON string, `status`, `output` / `error` (inlined per the OpenAI spec), and `approval_request_id` when the call was gated.
+- `mcp_approval_request` — emitted when `require_approval` gates a call.
+- `mcp_approval_response` — caller-supplied **input** item that resumes a parked call: `{ "type": "mcp_approval_response", "approval_request_id": "mcpr_...", "approve": true, "reason": "optional rationale" }`.
+- `tool_search_call` / `tool_search_output` — emitted when [tool search](#tool-search-deferred-tools) runs for a `defer_loading` server. The `tool_search_output` carries the `tools[]` the search surfaced.
+
+Hadrian recognizes all of these and round-trips them through the Responses-API pipeline.
+
+## hadrian_hosted mode
+
+When `mode = "hadrian_hosted"`, Hadrian itself runs the MCP client loop using the official [`rmcp`](https://github.com/modelcontextprotocol/rust-sdk) crate. On request entry, the gateway:
+
+1. Connects to each MCP server declared on the request (Streamable HTTP, caller-supplied bearer token).
+2. Calls `tools/list` and caches the catalog for 60 seconds.
+3. **Rewrites** every `{"type": "mcp", server_label, ...}` entry into N function tools named `mcp_<server_label>__<tool_name>`. The model sees a flat list of function tools.
+4. When the model calls one of those function tools, Hadrian's `McpExecutor` intercepts it, looks up the right pooled MCP client, and forwards the `tools/call`.
+5. The result is inlined onto the `mcp_call` item's `output` (or `error`) field on the response stream and folded back as a `function_call_output` item the model reads on the next turn.
+
+The same code path runs for every provider — Anthropic, Bedrock, Vertex, OpenAI, Azure, Test — so any tool-using model can drive it. Connections are pooled per `(server_url, auth_hash)` so chained calls in one response don't pay the `initialize` round-trip more than once.
+
+**Tool name handling.** The server label is sanitized to fit OpenAI's `[A-Za-z0-9_-]{1,64}` function-name regex (`My Co/Linear` becomes `My_Co_Linear`); the tool name is taken verbatim from `tools/list` so the round-trip back to the MCP server is exact. Tools whose names don't match the regex (`my.tool`, non-ASCII) are skipped at rewrite time with a warning.
+
+**Bad-gateway errors.** If `tools/list` fails (server unreachable, 5xx, TLS error) the request returns HTTP 502 with `error_code = "mcp_list_tools_failed"` and the underlying message — clients should retry with backoff. 401 errors from the MCP server are surfaced verbatim; the caller is expected to refresh their token and retry.
+
+## Tool search (deferred tools)
+
+OpenAI's `defer_loading` flag means "discover this tool via tool search rather than loading its definition into the prompt" — useful when a server exposes dozens of tools and dumping every schema into context would be wasteful. Under `passthrough_openai` the flag is forwarded verbatim and OpenAI runs its native tool search.
+
+Under `hadrian_hosted`, **Hadrian runs the tool search itself**, so deferral works behind every provider — including OpenAI-spec-compatible providers that don't implement the native `tool_search` tool. When a request marks an `mcp` entry with `defer_loading: true`:
+
+1. Hadrian fetches the catalog (as always) but keeps the per-tool definitions **out of the prompt**.
+2. It injects a single `tool_search` function tool listing the searchable servers.
+3. When the model calls `tool_search` with a `query`, Hadrian ranks the catalog locally, emits `tool_search_call` / `tool_search_output` items, and **injects the matched tool definitions** into the next turn so the model can call them.
+
+```json
+{
+  "model": "claude-sonnet-4-6",
+  "input": "Find and read issue ENG-1234",
+  "tools": [
+    {
+      "type": "mcp",
+      "server_label": "atlassian",
+      "server_url": "https://mcp.atlassian.com/v1/mcp",
+      "authorization": "Bearer ya29...",
+      "defer_loading": true
+    }
+  ]
+}
+```
+
+### Ranking
+
+The ranking strategy is set by `[features.mcp.tool_search]` and can be overridden per request via a `tool_search` tool entry's Hadrian-extension `ranker` field (request value wins):
+
+| Strategy   | Behavior                                                                  |
+| ---------- | ------------------------------------------------------------------------- |
+| `hybrid`   | **Default.** Fuses semantic + lexical relevance (Reciprocal Rank Fusion). |
+| `semantic` | Embedding cosine similarity only.                                         |
+| `lexical`  | Token/substring overlap. No embedding provider required.                  |
+
+```toml
+[features.mcp.tool_search]
+ranker = "hybrid"        # hybrid | semantic | lexical
+max_results = 20         # tools returned per search
+score_threshold = 0.0    # minimum relevance score
+rrf_k = 60               # RRF smoothing constant (hybrid)
+
+# Embedding config for semantic/hybrid. Falls back to
+# [features.file_search.embedding] then the semantic-cache embedding config.
+[features.mcp.tool_search.embedding]
+provider = "openai"
+model = "text-embedding-3-small"
+dimensions = 1536
+```
+
+Semantic and hybrid ranking need a resolvable embedding provider. If none resolves, a `hybrid` default **automatically falls back to lexical** (logged), so the feature keeps working. An explicit per-request `ranker: "semantic"` on a deployment with no embedding provider is a hard error — HTTP 400 with `error_code = "tool_search_ranker_unavailable"`.
+
+To opt out of Hadrian-side search and use the upstream's native tool search instead, set `defer_loading_passthrough: true` (OpenAI/Azure only).
+
+## Validation errors
+
+The gateway validates the `mcp` tool entry before dispatching the request. Failures return HTTP 400 with a stable `error_code`:
+
+| Error code                             | Cause                                                                                                                                                            |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mcp_disabled`                         | A request includes an `mcp` tool but `[features.mcp].enabled = false` (or the section is missing).                                                               |
+| `mcp_invalid_target`                   | Neither `server_url` nor `connector_id` is set, or both are.                                                                                                     |
+| `mcp_connector_id_not_allowed`         | `connector_id` is used but `[features.mcp].allow_connector_ids = false`, or `mode = hadrian_hosted` (which can't reach OpenAI's first-party connector registry). |
+| `mcp_server_url_not_allowed`           | `server_url` is not in `[features.mcp].allowed_server_urls`.                                                                                                     |
+| `mcp_passthrough_unsupported_provider` | `mode = passthrough_openai` but the resolved provider is not OpenAI/Azure (Anthropic, Bedrock, …).                                                               |
+| `mcp_hadrian_hosted_not_implemented`   | `mode = hadrian_hosted` but the gateway was built without the `mcp` cargo feature (e.g. `tiny` / `minimal` profiles).                                            |
+
+And the approval-resume errors (HTTP 400 for caller-shape problems, 502 for upstream failures):
+
+| Error code                        | Status | Cause                                                                                                                     |
+| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `mcp_resume_missing_tool_binding` | 400    | An `mcp_approval_response` with `approve: true` arrived but the request omits the `mcp` tool entry for the parked server. |
+| `mcp_resume_call_failed`          | 502    | Resumed call to the upstream MCP server failed (network, 5xx, 401).                                                       |
+| `mcp_resume_repo_error`           | 502    | Approvals-table lookup or delete failed.                                                                                  |
+
+And HTTP 502 from the upstream MCP dependency during the rewrite:
+
+| Error code                   | Cause                                                                                           |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- |
+| `mcp_list_tools_failed`      | `hadrian_hosted` rewrite couldn't reach the remote MCP server's `tools/list` endpoint.          |
+| `mcp_duplicate_server_label` | Two `mcp` tool entries on one request share a `server_label`; exactly one per label is allowed. |
+| `mcp_missing_server_url`     | `hadrian_hosted` requires `server_url` on every `mcp` tool entry (`connector_id` is rejected).  |
+
+## OpenAI connectors (`connector_id`)
+
+OpenAI's API exposes a curated set of first-party connectors (Dropbox, Gmail, Google Calendar, Google Drive, Microsoft Teams, Outlook Email, Outlook Calendar, SharePoint). These resolve through OpenAI's internal connector registry — there is no public endpoint a self-hosted gateway can call to enumerate, validate, or invoke them. As a result, Hadrian deliberately does **not** ship a per-connector allowlist: under `passthrough_openai` the `connector_id` is forwarded verbatim to OpenAI/Azure, and under `hadrian_hosted` it's rejected outright (`mcp_connector_id_not_allowed`) because the gateway can't reach the registry. Operators get a single coarse switch — `allow_connector_ids` — to admit or refuse the entire feature.
+
+If you need fine-grained gating, host the relevant service's MCP endpoint yourself (most providers, including the eight above, expose public MCP servers) and use `server_url` with `[features.mcp].allowed_server_urls` instead.
+
+## Rate limiting
+
+Hadrian's standard request- and token-rate limits apply to `/v1/responses` and therefore bound MCP traffic transitively. Beyond that, there is currently **no per-MCP-server call cap** — once a request is admitted, the model can chain `tools/call` invocations up to the global `[features.server_tools].max_iterations` ceiling (default 30 iterations). The agent loop is the hard backstop; runaway calls terminate when the iteration budget is exhausted.
+
+This matches OpenAI's documented behavior — the spec does not define a per-tool or per-server call cap on the Responses API side. If you need tighter bounds (e.g. "no more than 5 `tools/call` per response against `atlassian`"), the recommended approach today is:
+
+1. Lower `[features.server_tools].max_iterations` for the deployment.
+2. Use `require_approval = "always"` on sensitive servers so each call goes through the approval gate.
+3. Track call volume out-of-band via the persisted `mcp_call` items on the response store.
+
+A dedicated per-server cap is a candidate enhancement; until OpenAI publishes a matching field on the `mcp` tool, it would be a Hadrian-only extension.
+
+## Authentication
+
+Hadrian does not run the OAuth dance for the remote MCP server. The caller is responsible for:
+
+1. Registering an OAuth client with the MCP provider (Atlassian developer console, etc.).
+2. Completing the authorization-code flow to obtain an access token.
+3. Refreshing the token before expiry and re-sending it on each request.
+
+This mirrors OpenAI's own contract — the `authorization` field is opaque from the API's perspective. The gateway adds no value-add on top (no operator-pinned tokens, no gateway-side refresh).
+
+## Approval flow
+
+<Callout type="warn">
+  **`require_approval` defaults to `"always"`.** Matching OpenAI's spec, an `mcp` tool entry with no
+  `require_approval` field gates **every** call. Under `hadrian_hosted` the approval gate **fails
+  closed**: if the gateway can't park the call it refuses to run it and returns a failed `mcp_call`
+  instead. Parking requires all of:
+
+- a configured database (`mcp_pending_approvals` lives in Postgres/SQLite — the `tiny` profile has no DB),
+- `store: true` on the request (a parked call must be persisted so it can be resumed), and
+- an authenticated request with an organization scope (anonymous requests have nowhere to park).
+
+So a "just add an `mcp` tool" request with none of the above will see every call fail with an
+explanatory error. For unattended / non-sensitive servers, set `require_approval: "never"` (or list
+the safe tools under the object form's `never`). Only opt into gating when you have a DB, send
+`store: true`, and have a UI ready to collect the `mcp_approval_response`.
+
+</Callout>
+
+When `require_approval` matches a call, the upstream emits an `mcp_approval_request` item. The next `/v1/responses` request must carry an `mcp_approval_response` **input** item with the matching `approval_request_id`:
+
+```json
+{
+  "input": [
+    {
+      "type": "mcp_approval_response",
+      "approval_request_id": "mcpr_abc123",
+      "approve": true
+    }
+  ],
+  "previous_response_id": "resp_xyz",
+  "tools": [{ "type": "mcp", "server_label": "atlassian", "server_url": "..." }]
+}
+```
+
+## Approval persistence
+
+`require_approval` is honored under both modes:
+
+- **`passthrough_openai`** — OpenAI / Azure runs the approval loop itself.
+- **`hadrian_hosted`** — Hadrian parks gated calls in the `mcp_pending_approvals` table (Postgres or SQLite, mirrored). Persistence survives replica restarts and lets a user click "approve" minutes after the gateway emitted the request. The caller resumes by sending `{"type": "mcp_approval_response", "approval_request_id": "mcpr_...", "approve": true|false}` as an input item on a follow-up request (typically with `previous_response_id` chained back); Hadrian runs the call (on approve) or surfaces a refusal (on deny) and folds the result back as a `function_call_output` the model sees on its next turn.
+
+### Resuming an approved call
+
+The resume request **must include the matching `mcp` tool entry** with the `authorization` header set. The gateway never persists OAuth tokens, so it pulls the bearer back off the live request's `tools[]` block at resume time. Concretely:
+
+```json
+{
+  "previous_response_id": "resp_xyz",
+  "tools": [
+    {
+      "type": "mcp",
+      "server_label": "atlassian",
+      "server_url": "https://mcp.atlassian.com/v1/mcp",
+      "authorization": "Bearer ya29..."
+    }
+  ],
+  "input": [
+    { "type": "mcp_approval_response", "approval_request_id": "mcpr_a1b2c3", "approve": true }
+  ]
+}
+```
+
+If the `mcp` tool entry for the parked call's `server_label` is missing on the resume request, the gateway returns HTTP 400 with `error_code = "mcp_resume_missing_tool_binding"` and a message naming the server. **Refusals (`approve: false`) don't require the tool entry** — they short-circuit without hitting the upstream.
+
+When the gateway runs without a database, `require_approval` under `hadrian_hosted` degrades to **warn-and-run** — the operator log shows a clear "persistence unavailable" message and every call executes. Enable a database to gate approvals.
diff --git a/docs/content/docs/features/meta.json b/docs/content/docs/features/meta.json
index 795eb68..3baaac3 100644
--- a/docs/content/docs/features/meta.json
+++ b/docs/content/docs/features/meta.json
@@ -20,6 +20,8 @@
     "chat-modes",
     "frontend-tools",
     "web-tools",
+    "agents",
+    "mcp-tool",
     "guardrails",
     "mcp",
     "mcp-agents",
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
index ca61dfc..46c6d68 100644
--- a/docs/content/docs/index.mdx
+++ b/docs/content/docs/index.mdx
@@ -14,6 +14,7 @@ Hadrian is an **AI Gateway** that provides a unified OpenAI-compatible API for r
 - **Budget Enforcement** - Cost tracking and limits per project/user
 - **API Key & OIDC Auth** - Flexible authentication options
 - **RAG / Vector Stores** - File search with automatic document processing
+- **Agents & Shell Tool** - Server-side shell and MCP via the Responses API
 - **Observability** - Logging, metrics, and tracing
 
 ## Quick Start
diff --git a/migrations_sqlx/postgres/20250101000000_initial.sql b/migrations_sqlx/postgres/20250101000000_initial.sql
index 2b9e05e..4de5b8e 100644
--- a/migrations_sqlx/postgres/20250101000000_initial.sql
+++ b/migrations_sqlx/postgres/20250101000000_initial.sql
@@ -664,7 +664,13 @@ CREATE TABLE IF NOT EXISTS usage_records (
     tool_query TEXT,
     tool_url TEXT,
     tool_bytes_fetched BIGINT,
-    tool_results_count INTEGER
+    tool_results_count INTEGER,
+    -- Wall-clock runtime in seconds (only populated for shell tool records)
+    tool_runtime_seconds DOUBLE PRECISION,
+    -- Shell process exit code (only populated for shell tool records).
+    -- Kept separate from status_code (HTTP) so a shell that exits non-zero
+    -- inside a 200 response is observable in usage queries.
+    tool_exit_code INTEGER
 );
 
 -- API key indexes (partial: only index rows with api_key_id)
@@ -1291,3 +1297,218 @@ CREATE INDEX IF NOT EXISTS idx_oauth_authz_codes_code ON oauth_authorization_cod
 CREATE INDEX IF NOT EXISTS idx_oauth_authz_codes_user ON oauth_authorization_codes(user_id);
 -- Used by the periodic cleanup query to find expired/consumed codes
 CREATE INDEX IF NOT EXISTS idx_oauth_authz_codes_expires ON oauth_authorization_codes(expires_at);
+
+-- ======================================================================
+-- Responses (Responses API persistence)
+-- ======================================================================
+
+DO $$ BEGIN
+    CREATE TYPE response_owner_type AS ENUM ('organization', 'team', 'project', 'user', 'service_account');
+EXCEPTION
+    WHEN duplicate_object THEN null;
+END $$;
+
+-- See SQLite migration for documentation. Mirror schema.
+--
+-- `owner_type`/`owner_id` follow the same pattern as `skills` /
+-- `templates` / `conversations`: they record which scope a response
+-- belongs to (so it can be listed/retrieved as an org/team/project/
+-- user/service-account resource). `org_id` is the tenant boundary;
+-- the audit columns (`user_id`, `api_key_id`, `project_id`,
+-- `service_account_id`) record who actually made the call.
+CREATE TABLE IF NOT EXISTS responses (
+    id VARCHAR(64) PRIMARY KEY,
+    org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    owner_type response_owner_type NOT NULL,
+    owner_id UUID NOT NULL,
+    project_id UUID REFERENCES projects(id) ON DELETE SET NULL,
+    user_id UUID REFERENCES users(id) ON DELETE SET NULL,
+    api_key_id UUID REFERENCES api_keys(id) ON DELETE SET NULL,
+    service_account_id UUID REFERENCES service_accounts(id) ON DELETE SET NULL,
+    status VARCHAR(16) NOT NULL,
+    background BOOLEAN NOT NULL DEFAULT FALSE,
+    model VARCHAR(128) NOT NULL,
+    provider VARCHAR(128),
+    created_at TIMESTAMPTZ NOT NULL,
+    started_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ,
+    request_payload JSONB NOT NULL,
+    output JSONB,
+    usage JSONB,
+    error JSONB,
+    retention_expires_at TIMESTAMPTZ NOT NULL,
+    last_sequence_number BIGINT NOT NULL DEFAULT 0,
+    -- Liveness heartbeat for `in_progress` rows. The executing worker
+    -- stamps this periodically; the in-progress reaper compares against
+    -- COALESCE(last_heartbeat_at, started_at) so it only force-fails rows
+    -- whose worker has actually gone away, never a healthy long-running
+    -- response.
+    last_heartbeat_at TIMESTAMPTZ,
+    -- Container the shell-tool session for this response wrote files
+    -- into. Set when a `[features.shell]` runtime captures artifacts
+    -- under `/mnt/data`. Drives `previous_response_id`-based reuse:
+    -- a chained response looks here to find the container it should
+    -- reattach to.
+    container_id VARCHAR(48)
+);
+
+CREATE INDEX IF NOT EXISTS idx_responses_org_status ON responses(org_id, status);
+-- Gateway-wide background-worker queries (claim_queued, reap_stuck_in_progress,
+-- list_cancelled_among) filter on `status` without `org_id`, so the org-leading
+-- index above is unusable for them. This (status, created_at) index serves those
+-- polls without a full table scan + sort.
+CREATE INDEX IF NOT EXISTS idx_responses_status ON responses(status, created_at);
+CREATE INDEX IF NOT EXISTS idx_responses_owner_created ON responses(owner_type, owner_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_responses_retention ON responses(retention_expires_at);
+
+-- Append-only event log; see SQLite migration. The composite PRIMARY
+-- KEY already provides the (response_id, sequence_number) b-tree, so
+-- no extra index is needed.
+CREATE TABLE IF NOT EXISTS response_events (
+    response_id VARCHAR(64) NOT NULL REFERENCES responses(id) ON DELETE CASCADE,
+    sequence_number BIGINT NOT NULL,
+    event_type VARCHAR(64) NOT NULL,
+    payload JSONB NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL,
+    PRIMARY KEY (response_id, sequence_number)
+);
+
+-- ======================================================================
+-- Containers (shell-tool `/mnt/data` artifact persistence)
+-- ======================================================================
+
+-- A "container" is the persistent shell-tool session and the files it
+-- produced under `/mnt/data`. One row per session; today the session
+-- is response-scoped, and `previous_response_id` / `container_reference`
+-- chains can reuse a row across responses.
+--
+-- IDs are stored as TEXT (`cntr_<32hex>`) so the wire format and the
+-- DB key match — clients pass the same string they received in a
+-- `container_file_citation` annotation back as the URL segment.
+CREATE TABLE IF NOT EXISTS containers (
+    id VARCHAR(48) PRIMARY KEY,
+    org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    owner_type response_owner_type NOT NULL,
+    owner_id UUID NOT NULL,
+    -- 'active' | 'expired' | 'deleted'
+    status VARCHAR(16) NOT NULL,
+    -- Runtime that backed the session (`microsandbox`, `opensandbox`,
+    -- `passthrough_openai`). Stored as a label rather than a FK so
+    -- we can drop a runtime backend without rewriting history.
+    runtime_label VARCHAR(64) NOT NULL,
+    -- Response this container was originally provisioned for. Nullable
+    -- because `POST /v1/containers` creates a container unattached to
+    -- any response (it gets used by future responses via
+    -- `container_reference`).
+    source_response_id VARCHAR(64),
+    idle_ttl_secs BIGINT NOT NULL,
+    last_active_at TIMESTAMPTZ NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL,
+    expires_at TIMESTAMPTZ,
+    -- Optional display name supplied at `POST /v1/containers` time
+    -- (max 255 chars by OpenAI's convention).
+    name VARCHAR(255),
+    -- Memory ceiling stored at creation. Persisted so future reattach
+    -- requests can recompute the resolved env consistently. Nullable
+    -- when not specified (runtime default applies).
+    memory_limit_mb INTEGER,
+    -- JSON-encoded `network_policy` saved at creation time so reuse
+    -- through `container_reference` carries the original egress policy
+    -- (operator caps still apply per request).
+    network_policy_json TEXT,
+    -- JSON array of skill UUIDs bound to this container. Materialised
+    -- on every session boot.
+    skill_ids_json TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_containers_org_active
+    ON containers(org_id, status, last_active_at);
+-- Gateway-wide reaper queries (mark_expired_idle, hard_delete_expired) filter on
+-- `status` without `org_id` and order by `expires_at`; the org-leading index above
+-- can't serve them. This index avoids a sequential scan + sort on every poll.
+CREATE INDEX IF NOT EXISTS idx_containers_status_expires
+    ON containers(status, expires_at);
+CREATE INDEX IF NOT EXISTS idx_containers_source_response
+    ON containers(source_response_id)
+    WHERE source_response_id IS NOT NULL;
+
+-- One row per file currently tracked under `/mnt/data` for a given
+-- container. Reuses the same `file_storage_backend` enum + storage
+-- columns as the OpenAI Files API table so the same `FileStorage`
+-- trait can read both.
+--
+-- `path` is the absolute path inside the container (always under
+-- `/mnt/data/`). Unique per container so overwrites map to the same
+-- row — re-running a shell command that produces the same artifact
+-- doesn't grow the table unbounded.
+CREATE TABLE IF NOT EXISTS container_files (
+    id VARCHAR(48) PRIMARY KEY,
+    container_id VARCHAR(48) NOT NULL REFERENCES containers(id) ON DELETE CASCADE,
+    org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    path TEXT NOT NULL,
+    filename VARCHAR(255) NOT NULL,
+    size_bytes BIGINT NOT NULL,
+    content_type VARCHAR(128),
+    -- sha256 hex of content. 64 chars exactly.
+    content_hash VARCHAR(64) NOT NULL,
+    -- 'user' (staged from an input_file part) | 'assistant' (written
+    -- by the model during a shell command).
+    source VARCHAR(16) NOT NULL,
+    storage_backend file_storage_backend NOT NULL DEFAULT 'database',
+    file_data BYTEA,
+    storage_path TEXT,
+    -- Provenance: which response / shell call produced this version.
+    source_response_id VARCHAR(64),
+    source_call_id VARCHAR(128),
+    created_at TIMESTAMPTZ NOT NULL,
+    UNIQUE(container_id, path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_container_files_container_created
+    ON container_files(container_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_container_files_org
+    ON container_files(org_id);
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- mcp_pending_approvals
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Parked MCP tool calls waiting on a `mcp_approval_response` from the
+-- caller. Written when the executor's gating check (require_approval
+-- on the corresponding McpTool) blocks a model-initiated call; read
+-- by the preprocess in `routes/execution.rs` when a subsequent
+-- request includes a matching `mcp_approval_response` input item.
+--
+-- Scoped to a `response_id` so two concurrent responses can both park
+-- approvals without colliding; cleanup is best-effort via `expires_at`
+-- and the existing retention worker.
+CREATE TABLE IF NOT EXISTS mcp_pending_approvals (
+    -- `approval_request_id` surfaced on the `mcp_approval_request`
+    -- item the gateway emitted. The caller echoes it back on the
+    -- matching `mcp_approval_response` so the gateway can look up the
+    -- parked call by primary key.
+    id VARCHAR(64) PRIMARY KEY,
+    -- The response (turn) that emitted the approval request. The
+    -- approval response must arrive on a request whose
+    -- `previous_response_id` chains back here.
+    response_id VARCHAR(64) NOT NULL,
+    org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    -- `call_id` from the original `function_call` (rewritten MCP tool)
+    -- so we can synthesize a matching `function_call_output` on resume.
+    call_id VARCHAR(128) NOT NULL,
+    -- MCP server identity captured at park time. Persisted (not
+    -- re-derived from the request) so an in-flight credentials rotation
+    -- between park and resume can't lose the call.
+    server_label VARCHAR(128) NOT NULL,
+    server_url TEXT NOT NULL,
+    tool_name VARCHAR(128) NOT NULL,
+    -- Arguments the model originally proposed, as a JSON string
+    -- (matches the wire shape of `function_call.arguments`).
+    arguments_json TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL,
+    expires_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_pending_approvals_response
+    ON mcp_pending_approvals(response_id);
+CREATE INDEX IF NOT EXISTS idx_mcp_pending_approvals_expires
+    ON mcp_pending_approvals(expires_at);
diff --git a/migrations_sqlx/sqlite/20250101000000_initial.sql b/migrations_sqlx/sqlite/20250101000000_initial.sql
index 6d57b6a..0714d0b 100644
--- a/migrations_sqlx/sqlite/20250101000000_initial.sql
+++ b/migrations_sqlx/sqlite/20250101000000_initial.sql
@@ -618,7 +618,13 @@ CREATE TABLE IF NOT EXISTS usage_records (
     tool_query TEXT,
     tool_url TEXT,
     tool_bytes_fetched INTEGER,
-    tool_results_count INTEGER
+    tool_results_count INTEGER,
+    -- Wall-clock runtime in seconds (only populated for shell tool records)
+    tool_runtime_seconds REAL,
+    -- Shell process exit code (only populated for shell tool records).
+    -- Kept separate from status_code (HTTP) so a shell that exits non-zero
+    -- inside a 200 response is observable in usage queries.
+    tool_exit_code INTEGER
 );
 
 -- SQLite doesn't support partial indexes; use regular indexes
@@ -1044,3 +1050,185 @@ CREATE INDEX IF NOT EXISTS idx_oauth_authz_codes_code ON oauth_authorization_cod
 CREATE INDEX IF NOT EXISTS idx_oauth_authz_codes_user ON oauth_authorization_codes(user_id);
 -- Used by the periodic cleanup query to find expired/consumed codes
 CREATE INDEX IF NOT EXISTS idx_oauth_authz_codes_expires ON oauth_authorization_codes(expires_at);
+
+-- ======================================================================
+-- Responses (Responses API persistence)
+-- ======================================================================
+
+-- A persisted response from the Responses API. Stored when the
+-- client sends `store=true` (default per OpenAI spec). Allows clients
+-- to retrieve responses by ID, list their history, cancel in-progress
+-- background responses, and delete persisted records.
+--
+-- Status lifecycle: queued -> in_progress -> {completed | failed |
+-- cancelled | incomplete}.
+--
+-- `retention_expires_at` drives the cleanup worker that prunes old
+-- records (default 24h after the response reaches a terminal state).
+-- `request_payload`, `output`, `usage`, `error` are stored as JSON
+-- text — the schema is intentionally opaque so the API surface can
+-- evolve without further migrations.
+CREATE TABLE IF NOT EXISTS responses (
+    id TEXT PRIMARY KEY,
+    -- Tenancy. Org is required: anonymous-mode deployments still set a
+    -- synthetic default org via the auth middleware, so a NULL here
+    -- would indicate a bypass we want to reject at insert time.
+    org_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    -- Ownership. Matches the `skills` / `templates` / `conversations`
+    -- pattern — records which scope a response belongs to so it can
+    -- be listed/retrieved as an org/team/project/user/service-account
+    -- resource. Reads cascade through the org-scope filter; writes
+    -- and deletes follow the same cascade.
+    owner_type TEXT NOT NULL CHECK (owner_type IN ('organization','team','project','user','service_account')),
+    owner_id TEXT NOT NULL,
+    -- Audit columns. These record who actually made the call; they
+    -- are distinct from the owner above (an API key bound to a
+    -- project can submit a request whose owner is the user, etc.).
+    project_id TEXT REFERENCES projects(id) ON DELETE SET NULL,
+    user_id TEXT REFERENCES users(id) ON DELETE SET NULL,
+    api_key_id TEXT REFERENCES api_keys(id) ON DELETE SET NULL,
+    service_account_id TEXT REFERENCES service_accounts(id) ON DELETE SET NULL,
+    -- Lifecycle
+    status TEXT NOT NULL,
+    background INTEGER NOT NULL DEFAULT 0,
+    model TEXT NOT NULL,
+    provider TEXT,
+    created_at TEXT NOT NULL,
+    started_at TEXT,
+    completed_at TEXT,
+    -- Payload + result (JSON)
+    request_payload TEXT NOT NULL,
+    output TEXT,
+    usage TEXT,
+    error TEXT,
+    -- Retention
+    retention_expires_at TEXT NOT NULL,
+    -- Highest event sequence_number persisted by the event buffer for
+    -- this response. Used by the replay endpoint to detect "no more
+    -- events coming" without a separate join.
+    last_sequence_number INTEGER NOT NULL DEFAULT 0,
+    -- Liveness heartbeat for `in_progress` rows; the in-progress reaper
+    -- compares against COALESCE(last_heartbeat_at, started_at). See the
+    -- Postgres migration for the rationale.
+    last_heartbeat_at TEXT,
+    -- Container the shell-tool session for this response wrote files
+    -- into. See Postgres migration for the design rationale.
+    container_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_responses_org_status ON responses(org_id, status);
+-- Gateway-wide background-worker queries (claim_queued, reap_stuck_in_progress,
+-- list_cancelled_among) filter on `status` without `org_id`, so the org-leading
+-- index above is unusable for them. This (status, created_at) index serves those
+-- polls without a full table scan + sort.
+CREATE INDEX IF NOT EXISTS idx_responses_status ON responses(status, created_at);
+CREATE INDEX IF NOT EXISTS idx_responses_owner_created ON responses(owner_type, owner_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_responses_retention ON responses(retention_expires_at);
+
+-- Append-only event log for in-flight + completed responses. Powers
+-- `GET /v1/responses/{id}/events?starting_after=N` for clients that
+-- need to resume a dropped stream — they replay missed events from the
+-- log up to whatever sequence number they had when they disconnected,
+-- then continue with live events.
+--
+-- `sequence_number` is monotonic per response and assigned in the
+-- gateway (not derived from the upstream provider) so retries don't
+-- create gaps. ON DELETE CASCADE on `response_id` keeps the log in
+-- sync with `responses` cleanup. The composite PRIMARY KEY already
+-- provides the (response_id, sequence_number) b-tree, so no extra
+-- index is needed.
+CREATE TABLE IF NOT EXISTS response_events (
+    response_id TEXT NOT NULL REFERENCES responses(id) ON DELETE CASCADE,
+    sequence_number INTEGER NOT NULL,
+    event_type TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (response_id, sequence_number)
+);
+
+-- ======================================================================
+-- Containers (shell-tool `/mnt/data` artifact persistence)
+-- ======================================================================
+
+-- Mirror of the Postgres `containers` / `container_files` tables. See
+-- the Postgres migration for the design rationale. SQLite stores
+-- timestamps as TEXT (ISO-8601) — cursor pagination through these
+-- tables relies on millisecond-precision `created_at` values, so all
+-- inserts must use `truncate_to_millis(Utc::now())`.
+CREATE TABLE IF NOT EXISTS containers (
+    id TEXT PRIMARY KEY NOT NULL,
+    org_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    owner_type TEXT NOT NULL CHECK (owner_type IN ('organization', 'team', 'project', 'user', 'service_account')),
+    owner_id TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (status IN ('active', 'expired', 'deleted')),
+    runtime_label TEXT NOT NULL,
+    source_response_id TEXT,
+    idle_ttl_secs INTEGER NOT NULL,
+    last_active_at TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    expires_at TEXT,
+    -- POST /v1/containers fields (see postgres migration for rationale).
+    name TEXT,
+    memory_limit_mb INTEGER,
+    network_policy_json TEXT,
+    skill_ids_json TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_containers_org_active
+    ON containers(org_id, status, last_active_at);
+-- Gateway-wide reaper queries (mark_expired_idle, hard_delete_expired) filter on
+-- `status` without `org_id` and order by `expires_at`; the org-leading index above
+-- can't serve them. This index avoids a sequential scan + sort on every poll.
+CREATE INDEX IF NOT EXISTS idx_containers_status_expires
+    ON containers(status, expires_at);
+CREATE INDEX IF NOT EXISTS idx_containers_source_response
+    ON containers(source_response_id)
+    WHERE source_response_id IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS container_files (
+    id TEXT PRIMARY KEY NOT NULL,
+    container_id TEXT NOT NULL REFERENCES containers(id) ON DELETE CASCADE,
+    org_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    path TEXT NOT NULL,
+    filename TEXT NOT NULL,
+    size_bytes INTEGER NOT NULL,
+    content_type TEXT,
+    content_hash TEXT NOT NULL,
+    source TEXT NOT NULL CHECK (source IN ('user', 'assistant')),
+    storage_backend TEXT NOT NULL DEFAULT 'database' CHECK (storage_backend IN ('database', 'filesystem', 's3')),
+    file_data BLOB,
+    storage_path TEXT,
+    source_response_id TEXT,
+    source_call_id TEXT,
+    created_at TEXT NOT NULL,
+    UNIQUE(container_id, path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_container_files_container_created
+    ON container_files(container_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_container_files_org
+    ON container_files(org_id);
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- mcp_pending_approvals
+-- ─────────────────────────────────────────────────────────────────────────────
+-- See the Postgres mirror for full doc. Timestamps as TEXT (ISO 8601
+-- with millisecond precision — call `truncate_to_millis(Utc::now())`
+-- when writing, per `agent_instructions/database_changes.md`).
+CREATE TABLE IF NOT EXISTS mcp_pending_approvals (
+    id TEXT PRIMARY KEY NOT NULL,
+    response_id TEXT NOT NULL,
+    org_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    call_id TEXT NOT NULL,
+    server_label TEXT NOT NULL,
+    server_url TEXT NOT NULL,
+    tool_name TEXT NOT NULL,
+    arguments_json TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_pending_approvals_response
+    ON mcp_pending_approvals(response_id);
+CREATE INDEX IF NOT EXISTS idx_mcp_pending_approvals_expires
+    ON mcp_pending_approvals(expires_at);
diff --git a/openapi/hadrian.openapi.json b/openapi/hadrian.openapi.json
index d22897a..c0540f7 100644
--- a/openapi/hadrian.openapi.json
+++ b/openapi/hadrian.openapi.json
@@ -17555,6 +17555,688 @@
         ]
       }
     },
+    "/api/v1/containers": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers` — list containers in the caller's org,\nnewest-first. Matches OpenAI's cursor pagination shape.",
+        "operationId": "api_v1_containers_list",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Page size, clamped to 1..=100 (default 20)",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          },
+          {
+            "name": "after",
+            "in": "query",
+            "description": "Cursor: cntr_<hex> id of the last item from a prior page",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Containers in the org"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "post": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`POST /v1/containers` — create an unattached container.",
+        "operationId": "api_v1_containers_create",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateContainerRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "The created container metadata"
+          },
+          "400": {
+            "description": "Request rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/containers/{container_id}": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers/{container_id}` — retrieve a container.",
+        "operationId": "api_v1_containers_get",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "description": "Container ID (`cntr_<hex>`)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The container metadata"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Container not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "delete": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`DELETE /v1/containers/{container_id}` — soft-delete a container.",
+        "description": "Sets `status='deleted'` and evicts the matching in-memory session\nfrom the registry so the VM is torn down on the next Arc drop.\nThe underlying `container_files` rows cascade-delete with the\ncontainer row.",
+        "operationId": "api_v1_containers_delete",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Container deleted"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Container not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/containers/{container_id}/files": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers/{container_id}/files` — list files.",
+        "operationId": "api_v1_containers_list_files",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "description": "Container ID",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Page size, clamped to 1..=1000",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Files in the container"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Container not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "post": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`POST /v1/containers/{container_id}/files` — upload a file into a\ncontainer's `/mnt/data`. Accepts either:",
+        "description": "- `multipart/form-data` with a `file` part (required) and optional\n  `path` / `content_type` parts — streams bytes directly.\n- `application/json` with `{file_id: \"file_...\"}` — copies an\n  existing Files-API upload into the container (same resolver as\n  the `file_ids` array on `POST /v1/containers`).\n\nMatches OpenAI's upload contract.",
+        "operationId": "api_v1_containers_file_upload",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Uploaded file metadata"
+          },
+          "400": {
+            "description": "Request rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Container not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "413": {
+            "description": "Payload too large",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "415": {
+            "description": "Unsupported Content-Type",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/containers/{container_id}/files/{file_id}": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers/{container_id}/files/{file_id}` — file metadata.",
+        "operationId": "api_v1_containers_file_get",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "file_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The container file metadata"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "File not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "delete": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`DELETE /v1/containers/{container_id}/files/{file_id}` — remove\na file from a container.",
+        "operationId": "api_v1_containers_file_delete",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "file_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "File deleted"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "File not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/containers/{container_id}/files/{file_id}/content": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers/{container_id}/files/{file_id}/content` — raw bytes.",
+        "operationId": "api_v1_containers_file_content",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "file_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Raw file bytes; Content-Type comes from the row"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "File not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
     "/api/v1/embeddings": {
       "post": {
         "tags": [
@@ -18033,7 +18715,180 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateImageRequest"
+                "$ref": "#/components/schemas/CreateImageRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Image generated successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ImagesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/images/variations": {
+      "post": {
+        "tags": [
+          "Images"
+        ],
+        "summary": "Create image variations",
+        "description": "POST /v1/images/variations",
+        "operationId": "api_v1_images_variations",
+        "requestBody": {
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateImageVariationRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Image variations created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ImagesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/models": {
+      "get": {
+        "tags": [
+          "models"
+        ],
+        "summary": "List available models",
+        "description": "Lists all models available from all configured providers.",
+        "operationId": "api_v1_models",
+        "responses": {
+          "200": {
+            "description": "List of available models",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CombinedModelsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/responses": {
+      "post": {
+        "tags": [
+          "chat"
+        ],
+        "summary": "Create a response",
+        "description": "Creates a model response using the Responses API format.",
+        "operationId": "api_v1_responses",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateResponsesPayload"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Response object (streaming or non-streaming)"
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "502": {
+            "description": "Provider error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/responses/compact": {
+      "post": {
+        "tags": [
+          "responses"
+        ],
+        "summary": "Compact a context window via the provider's standalone compact\nendpoint.",
+        "description": "Stateless passthrough: forwards `model` + `input` (and any other\nfields the provider accepts) to the upstream `/responses/compact`\nendpoint and streams the compacted window back. Only OpenAI and\nAzure OpenAI implement this; routing to any other provider returns\n501 with `error_code = \"not_supported\"`.",
+        "operationId": "api_v1_responses_compact",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CompactRequest"
               }
             }
           },
@@ -18041,20 +18896,27 @@
         },
         "responses": {
           "200": {
-            "description": "Image generated successfully",
+            "description": "Compacted context window"
+          },
+          "400": {
+            "description": "Bad request",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ImagesResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           },
-          "400": {
-            "description": "Bad request"
-          },
-          "500": {
-            "description": "Internal server error"
+          "501": {
+            "description": "Provider does not support compaction",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         },
         "security": [
@@ -18064,40 +18926,87 @@
         ]
       }
     },
-    "/api/v1/images/variations": {
-      "post": {
+    "/api/v1/responses/{response_id}": {
+      "get": {
         "tags": [
-          "Images"
+          "responses"
         ],
-        "summary": "Create image variations",
-        "description": "POST /v1/images/variations",
-        "operationId": "api_v1_images_variations",
-        "requestBody": {
-          "content": {
-            "multipart/form-data": {
-              "schema": {
-                "$ref": "#/components/schemas/CreateImageVariationRequest"
-              }
+        "summary": "`GET /v1/responses/{response_id}` — retrieve a stored response.",
+        "description": "When `?stream=true` is set, returns the persisted event log as an\nSSE stream (matching OpenAI's retrieve-with-stream behavior). The\n`starting_after` query parameter resumes replay from a specific\nsequence number so a client reconnecting after a disconnect picks\nup exactly where it stopped.",
+        "operationId": "api_v1_responses_get",
+        "parameters": [
+          {
+            "name": "response_id",
+            "in": "path",
+            "description": "ID returned by POST /v1/responses",
+            "required": true,
+            "schema": {
+              "type": "string"
             }
           },
-          "required": true
-        },
+          {
+            "name": "stream",
+            "in": "query",
+            "description": "Stream the event log as SSE",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "starting_after",
+            "in": "query",
+            "description": "Resume cursor (stream mode)",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          }
+        ],
         "responses": {
           "200": {
-            "description": "Image variations created successfully",
+            "description": "Stored response (JSON) or SSE replay when stream=true"
+          },
+          "401": {
+            "description": "Authentication required",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ImagesResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           },
-          "400": {
-            "description": "Bad request"
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           },
-          "500": {
-            "description": "Internal server error"
+          "404": {
+            "description": "Response not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         },
         "security": [
@@ -18105,29 +19014,40 @@
             "api_key": []
           }
         ]
-      }
-    },
-    "/api/v1/models": {
-      "get": {
+      },
+      "delete": {
         "tags": [
-          "models"
+          "responses"
+        ],
+        "summary": "`DELETE /v1/responses/{response_id}` — remove a stored response.\nReturns the OpenAI-spec deletion confirmation shape.",
+        "operationId": "api_v1_responses_delete",
+        "parameters": [
+          {
+            "name": "response_id",
+            "in": "path",
+            "description": "ID of the response to delete",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
         ],
-        "summary": "List available models",
-        "description": "Lists all models available from all configured providers.",
-        "operationId": "api_v1_models",
         "responses": {
           "200": {
-            "description": "List of available models",
+            "description": "Deletion confirmation"
+          },
+          "401": {
+            "description": "Authentication required",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/CombinedModelsResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           },
-          "400": {
-            "description": "Bad request",
+          "403": {
+            "description": "Authorization denied",
             "content": {
               "application/json": {
                 "schema": {
@@ -18144,30 +19064,30 @@
         ]
       }
     },
-    "/api/v1/responses": {
+    "/api/v1/responses/{response_id}/cancel": {
       "post": {
         "tags": [
-          "chat"
+          "responses"
         ],
-        "summary": "Create a response",
-        "description": "Creates a model response using the Responses API format.",
-        "operationId": "api_v1_responses",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/CreateResponsesPayload"
-              }
+        "summary": "`POST /v1/responses/{response_id}/cancel` — cancel an in-progress\nbackground response. Per OpenAI's spec, returns 400 if the response\nis not in background mode. Idempotent for already-terminal rows.",
+        "operationId": "api_v1_responses_cancel",
+        "parameters": [
+          {
+            "name": "response_id",
+            "in": "path",
+            "description": "ID of the response to cancel",
+            "required": true,
+            "schema": {
+              "type": "string"
             }
-          },
-          "required": true
-        },
+          }
+        ],
         "responses": {
           "200": {
-            "description": "Response object (streaming or non-streaming)"
+            "description": "The cancelled response object"
           },
           "400": {
-            "description": "Bad request",
+            "description": "Response is not in background mode",
             "content": {
               "application/json": {
                 "schema": {
@@ -18176,8 +19096,28 @@
               }
             }
           },
-          "502": {
-            "description": "Provider error",
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Response not found",
             "content": {
               "application/json": {
                 "schema": {
@@ -20660,6 +21600,69 @@
           }
         }
       },
+      "CompactRequest": {
+        "type": "object",
+        "description": "Request body for `POST /v1/responses/compact`.\n\nMirrors OpenAI's `CompactResponseMethodPublicBody`: `model` is\nrequired; everything else is optional. Hadrian-specific extensions\n(`models`, `stream`, `sovereignty_requirements`) ride alongside\nbecause the gateway still routes, streams, and enforces sovereignty\nfor compaction requests just like the main `/responses` handler.",
+        "required": [
+          "model"
+        ],
+        "properties": {
+          "input": {
+            "type": "object",
+            "description": "Conversation history to compact. Accepts a plain string or the\ntyped item array used by `POST /responses`."
+          },
+          "instructions": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "System instructions threaded into the compaction prompt."
+          },
+          "model": {
+            "type": "string",
+            "description": "Model to compact with. Required by OpenAI; Hadrian also accepts\nit as the routing key when the gateway picks an upstream\nprovider."
+          },
+          "models": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "**Hadrian Extension:** alternate model list for multi-model\nrouting. The first entry the gateway resolves successfully wins."
+          },
+          "previous_response_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Continue compacting from a previously persisted response. Spec:\n`CompactResponseMethodPublicBody.previous_response_id`."
+          },
+          "prompt_cache_key": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "OpenAI prompt-cache key passthrough."
+          },
+          "sovereignty_requirements": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/SovereigntyRequirements",
+                "description": "**Hadrian Extension:** per-request data-sovereignty requirements.\nMerged with API-key-level requirements; the most restrictive\nwins."
+              }
+            ]
+          },
+          "stream": {
+            "type": "boolean",
+            "description": "**Hadrian Extension:** stream the compacted response as SSE.\nForwarded verbatim to the upstream provider when supported."
+          }
+        }
+      },
       "ComparisonFilter": {
         "type": "object",
         "description": "A comparison filter for attribute-based filtering.\n\nCompares a specific attribute key to a given value using a comparison operator.\n\n# Example\n\n```json\n{\n  \"type\": \"eq\",\n  \"key\": \"author\",\n  \"value\": \"John Doe\"\n}\n```\n\n# Supported Comparisons\n\n| Operator | Description |\n|----------|-------------|\n| `eq` | Equal to |\n| `ne` | Not equal to |\n| `gt` | Greater than |\n| `gte` | Greater than or equal to |\n| `lt` | Less than |\n| `lte` | Less than or equal to |",
@@ -20775,6 +21778,32 @@
           }
         }
       },
+      "ContainerExpiresAfter": {
+        "type": "object",
+        "description": "Container TTL hint. Mirrors OpenAI's `expires_after` shape — only\n`last_active_at` is honored today (the same anchor the operator's\nidle reaper uses), with `minutes` setting the per-container idle\nTTL.",
+        "required": [
+          "minutes"
+        ],
+        "properties": {
+          "anchor": {
+            "$ref": "#/components/schemas/ContainerExpiresAfterAnchor",
+            "description": "Anchor for the TTL countdown. Today only `\"last_active_at\"` is\nsupported; unknown anchors reject with 400."
+          },
+          "minutes": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Minutes after `anchor` when the container expires. Validated\nagainst `[features.containers].max_idle_ttl_secs / 60`.",
+            "minimum": 0
+          }
+        },
+        "additionalProperties": false
+      },
+      "ContainerExpiresAfterAnchor": {
+        "type": "string",
+        "enum": [
+          "last_active_at"
+        ]
+      },
       "ContentPart": {
         "oneOf": [
           {
@@ -21716,22 +22745,72 @@
             "format": "double",
             "description": "Sampling temperature (0.0 to 2.0)"
           },
-          "top_p": {
+          "top_p": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "format": "double",
+            "description": "Nucleus sampling probability (0.0 to 1.0)"
+          },
+          "user": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "User identifier for abuse detection"
+          }
+        }
+      },
+      "CreateContainerRequest": {
+        "type": "object",
+        "description": "Request body for `POST /v1/containers`.",
+        "properties": {
+          "expires_after": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/ContainerExpiresAfter",
+                "description": "Optional idle-TTL hint. Per OpenAI's spec: `{anchor:\n\"last_active_at\", minutes: N}`. Capped by\n`[features.containers].max_idle_ttl_secs / 60`."
+              }
+            ]
+          },
+          "file_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Files-API ids to copy into `/mnt/data` at container creation.\nSpec: `CreateContainerBody.file_ids`. Each id is resolved via\nthe Files API (same path as `input_file` parts on a response\nrequest) and the bytes are persisted into `container_files`\nso the model can read them on first attach."
+          },
+          "memory_limit": {
             "type": [
-              "number",
+              "string",
               "null"
             ],
-            "format": "double",
-            "description": "Nucleus sampling probability (0.0 to 1.0)"
+            "description": "Optional memory ceiling. Accepts OpenAI's `\"1g\"` / `\"512m\"`\nstrings; parsed case-insensitively. Capped by the operator's\n`[features.server_tools.shell_limits].max_mem_limit_mb`."
           },
-          "user": {
+          "name": {
             "type": [
               "string",
               "null"
             ],
-            "description": "User identifier for abuse detection"
+            "description": "Optional display name (max 255 chars)."
+          },
+          "network_policy": {
+            "type": "object",
+            "description": "Optional network policy (same shape as\n`tools.shell.environment.network_policy`). OpenAI types this as\na `oneOf { Disabled, Allowlist }` discriminated by `type`;\nHadrian represents it as a single flat object that validates\nthe same constraints at request resolution, so the schema is\nrendered as an opaque `object` to avoid spurious diffs."
+          },
+          "skills": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Skills to mount whenever a session is booted against this\ncontainer. Matches OpenAI's typed shape — see\n[`crate::api_types::RequestSkill`]."
           }
-        }
+        },
+        "additionalProperties": false
       },
       "CreateConversation": {
         "type": "object",
@@ -22702,6 +23781,13 @@
             ],
             "description": "Run in background"
           },
+          "context_management": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Context management directives. Forwarded verbatim to providers\nthat support server-side compaction (OpenAI, Azure OpenAI); for\nothers the field is ignored at the adapter layer. See OpenAI's\ncompaction guide for the schema; the canonical entry is\n`{\"type\": \"compaction\", \"compact_threshold\": <tokens>}`."
+          },
           "frequency_penalty": {
             "type": [
               "number",
@@ -22816,6 +23902,13 @@
             "type": "object",
             "description": "Service tier"
           },
+          "skills": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "**Hadrian Extension:** Skills to mount into the shell-tool\nsession. Hadrian treats skills as a top-level request field\nrather than threading them through the OpenAI shell-tool\n`environment` block, so they're accepted on every responses\nrequest regardless of whether the upstream provider has its own\nskills surface.\n\nMirrors OpenAI's typed shape — each entry is either a reference\nto a stored skill or an inline bundle:\n\n```json\n[\n  {\"type\": \"skill_reference\", \"skill_id\": \"<uuid>\", \"version\": \"latest\"},\n  {\"type\": \"inline\", \"name\": \"extract-csv\", \"description\": \"...\",\n   \"source\": {\"type\": \"base64\", \"media_type\": \"text/markdown\", \"data\": \"...\"}}\n]\n```\n\nFor `skill_reference`, `skill_id` is a Hadrian skill UUID\nowned by the caller's org. `version` is optional; only\n`\"latest\"` (the default) is supported today — pinned versions\nreject with 400 until version-pinning lands.\n\nFor `inline`, the decoded `source.data` is mounted as an\nephemeral skill bundle: `text/markdown` is treated as the\n`SKILL.md` content; other media types are rejected today.\n\nEach resolved skill's `SKILL.md` is prepended to `instructions`\nso the model knows the skill is available; all skill files are\nmaterialized under `/skills/<skill_id>/` inside the sandbox."
+          },
           "sovereignty_requirements": {
             "oneOf": [
               {
@@ -22855,9 +23948,12 @@
             "description": "Tool choice configuration"
           },
           "tools": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
-              "type": "object"
+              "$ref": "#/components/schemas/ResponsesToolDefinition"
             },
             "description": "Available tools"
           },
@@ -25677,6 +26773,61 @@
           }
         }
       },
+      "FileSearchTool": {
+        "type": "object",
+        "description": "File search tool for RAG in the Responses API.\nEnables semantic search across vector stores.",
+        "required": [
+          "type",
+          "vector_store_ids"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "filters": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Metadata filters to apply to the search."
+          },
+          "max_num_results": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Maximum number of results to return.",
+            "minimum": 0
+          },
+          "ranking_options": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Ranking options for controlling result relevance."
+          },
+          "type": {
+            "$ref": "#/components/schemas/FileSearchToolType"
+          },
+          "vector_store_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Vector store IDs to search across."
+          }
+        }
+      },
+      "FileSearchToolType": {
+        "type": "string",
+        "enum": [
+          "file_search"
+        ]
+      },
       "FileStatus": {
         "type": "string",
         "description": "File upload status (OpenAI Files API compatible)\n\nTracks the state of a file uploaded via the Files API.\nNote: This status is **deprecated** in OpenAI's API but still returned for compatibility.\n\n## State Transitions\n\n```text\n┌──────────┐     validation      ┌───────────┐\n│ uploaded │ ──────────────────▶ │ processed │\n└──────────┘     success         └───────────┘\n      │\n      │ validation failed\n      ▼\n┌──────────┐\n│  error   │\n└──────────┘\n```\n\n- `uploaded`: File received and stored, initial validation pending\n- `processed`: File validated and ready for use (e.g., adding to vector stores)\n- `error`: File validation failed (see `status_details` for reason)\n\n## Important\n\nThis is the **file upload** status, not the vector store processing status.\nWhen a file is added to a vector store, its processing status is tracked\nseparately via `VectorStoreFileStatus`.",
@@ -25747,6 +26898,64 @@
           }
         }
       },
+      "FunctionTool": {
+        "allOf": [
+          {
+            "type": "object",
+            "description": "Extra fields the gateway forwards verbatim (e.g. MCP `annotations`\non rewritten function tools). Not part of OpenAI's documented\nshape; preserved here so internal rewrite pipelines can attach\nprovider-specific metadata without losing it through round-trips."
+          },
+          {
+            "type": "object",
+            "required": [
+              "name"
+            ],
+            "properties": {
+              "defer_loading": {
+                "type": [
+                  "boolean",
+                  "null"
+                ],
+                "description": "Delay loading the function definition until the model discovers it\nvia tool search. On a caller-supplied function tool this is\nforwarded to the provider and treated as opaque. On the per-tool\nfunction tools the MCP rewrite synthesizes it is only set on the\nnative-passthrough path (`McpTool::defer_loading_passthrough` on an\nOpenAI/Azure upstream); the default `hadrian_hosted` path defers via\nHadrian-side tool search instead and does not set this flag."
+              },
+              "description": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Human-readable description surfaced to the model."
+              },
+              "name": {
+                "type": "string",
+                "description": "Function name. Must be `[A-Za-z0-9_-]{1,64}`."
+              },
+              "parameters": {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "description": "JSON Schema describing the function's parameters. Forwarded\nverbatim to the provider; the gateway treats it as opaque."
+              },
+              "strict": {
+                "type": [
+                  "boolean",
+                  "null"
+                ],
+                "description": "When true, the model is constrained to emit arguments that\nstrictly conform to `parameters`."
+              },
+              "type": {
+                "$ref": "#/components/schemas/FunctionToolType"
+              }
+            }
+          }
+        ],
+        "description": "Custom function tool. **Schema-only**: at the wire level the gateway\nkeeps `Function` as an opaque `serde_json::Value` so existing\nrewrite pipelines (web_search → function, shell → function, MCP →\nper-tool function) can construct/inspect it via JSON without\ntouching a typed struct. This struct exists purely to give the\nOpenAPI spec a typed shape for the function-tool variant."
+      },
+      "FunctionToolType": {
+        "type": "string",
+        "enum": [
+          "function"
+        ]
+      },
       "HealthStatus": {
         "type": "string",
         "description": "Status of a provider's health.",
@@ -26470,29 +27679,223 @@
               }
             ]
           },
-          "owner_id": {
+          "owner_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "uuid",
+            "description": "**Hadrian Extension:** Owner ID for multi-tenancy.\nWhen omitted along with `owner_type`, returns all accessible vector stores."
+          },
+          "owner_type": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Owner type for multi-tenancy (organization, team, project, or user).\nWhen omitted along with `owner_id`, returns all accessible vector stores."
+          }
+        }
+      },
+      "LogicalOperator": {
+        "type": "string",
+        "description": "Logical operators for compound filters.",
+        "enum": [
+          "and",
+          "or"
+        ]
+      },
+      "McpAllowedTools": {
+        "oneOf": [
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          {
+            "$ref": "#/components/schemas/McpToolFilter"
+          }
+        ],
+        "description": "Tool whitelist for an `McpTool`. Untagged so OpenAI's accepted\nshorthand `[\"tool_a\", \"tool_b\"]` round-trips as the `List` variant\nand the `{tool_names: [...], read_only?: bool}` object form picks\nup extra knobs."
+      },
+      "McpApprovalFilter": {
+        "type": "object",
+        "description": "Object form of `require_approval`. `always` lists tools that must\nbe gated; `never` lists tools that bypass the gate. Tools not named\nin either fall back to the default (gate). Mirrors OpenAI's\n`MCPToolApprovalFilter`.",
+        "properties": {
+          "always": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/McpToolFilter",
+                "description": "Tools that require approval."
+              }
+            ]
+          },
+          "never": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/McpToolFilter",
+                "description": "Tools exempt from approval."
+              }
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
+      "McpApprovalMode": {
+        "type": "string",
+        "enum": [
+          "always",
+          "never"
+        ]
+      },
+      "McpRequireApproval": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/McpApprovalMode"
+          },
+          {
+            "$ref": "#/components/schemas/McpApprovalFilter"
+          }
+        ],
+        "description": "Approval gating shape for the MCP tool. Accepts the spec's string\nshorthand (`\"always\"` / `\"never\"`) or an object with `always` / `never`\nfilters that opt subsets in or out of the approval gate."
+      },
+      "McpTool": {
+        "type": "object",
+        "description": "MCP tool — lets the model invoke tools exposed by a remote Model\nContext Protocol server (Atlassian, Notion, GitHub, HuggingFace, …).\n\nMirrors OpenAI's `mcp` tool. Two mutually-exclusive shapes: pointing\nat a remote server via `server_url`, or pointing at an OpenAI\nfirst-party connector via `connector_id`. The caller supplies any\n`authorization` bearer token directly on the tool entry; Hadrian\ndoes not persist or rewrite it.\n\nUnder `mode = passthrough_openai` the tool entry is forwarded\nverbatim to OpenAI / Azure OpenAI, and non-OpenAI providers reject\nwith `mcp_passthrough_unsupported_provider`. Under\n`mode = hadrian_hosted` the gateway runs the MCP client loop itself\nvia `rmcp` and rewrites the tool into per-tool function tools, so\nany provider can drive it.",
+        "required": [
+          "type",
+          "server_label"
+        ],
+        "properties": {
+          "allowed_tools": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/McpAllowedTools",
+                "description": "Restrict which tools from the server are exposed to the model.\nAccepts either a flat list of tool names or an object form for\nforward-compat with extra knobs."
+              }
+            ]
+          },
+          "authorization": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Bearer / OAuth access token. The caller obtains this\nout-of-band (OpenAI's API does not run the OAuth dance for the\nremote server, and neither does Hadrian). Sent verbatim to the\nMCP server's `Authorization` header. Hadrian does not persist\nthe value — clients must include it on every request."
+          },
+          "call_timeout_secs": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "**Hadrian Extension:** upper bound, in seconds, on a single\n`tools/call` round-trip to this MCP server under `hadrian_hosted`.\nOverrides the `[features.mcp].call_timeout_secs` deployment default\n(300s). On expiry the in-flight `mcp_call` terminates with\n`status=\"incomplete\"` and a timeout `error`. Not part of OpenAI's\nspec; ignored under `passthrough_openai` (the upstream owns the\ncall loop there).",
+            "minimum": 0
+          },
+          "connector_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Identifier for an OpenAI-maintained connector\n(e.g. `connector_googlecalendar`). Mutually exclusive with\n`server_url`. Only usable under `mode = passthrough_openai`;\n`hadrian_hosted` cannot reach OpenAI's connector registry."
+          },
+          "defer_loading": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Delay loading the tool definitions until the model discovers them\nvia tool search, rather than dumping the whole catalog into the\nprompt. Forwarded verbatim under `passthrough_openai` (OpenAI runs\nits native tool search). Under `hadrian_hosted` deferral is\nrealized by **Hadrian-side tool search**: the gateway exposes a\nsingle `tool_search` function tool, keeps the catalog server-side,\nand lazily injects matched per-tool function definitions as the\nmodel discovers them — so deferral works behind every provider,\nnot just OpenAI. The upstream `tools/list` catalog fetch always\nruns eagerly at rewrite time (it's needed to know what's\nsearchable); only the per-tool definitions are deferred."
+          },
+          "defer_loading_passthrough": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** opt out of Hadrian-side tool search and let\nthe upstream handle `defer_loading` natively. Only honored when\n`defer_loading` is set, the gateway is in `hadrian_hosted` mode,\nand the resolved provider is OpenAI / Azure OpenAI (which\nimplement native tool search); rejected with HTTP 400 otherwise.\nDefault/`None` keeps the provider-agnostic Hadrian-side path."
+          },
+          "headers": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Additional HTTP headers sent with every JSON-RPC call to the\nMCP server. Useful for region or workspace selectors.",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "propertyNames": {
+              "type": "string"
+            }
+          },
+          "require_approval": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/McpRequireApproval",
+                "description": "Approval gate. Spec default is `\"always\"` when omitted — under\n`hadrian_hosted` the executor enforces that default; under\n`passthrough_openai` the field is forwarded verbatim and OpenAI\napplies its own default."
+              }
+            ]
+          },
+          "server_description": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Human-readable description surfaced to the model."
+          },
+          "server_label": {
+            "type": "string",
+            "description": "Stable identifier surfaced in `mcp_list_tools` and `mcp_call`\nitems. Required even when using `connector_id` so output items\nhave a consistent label."
+          },
+          "server_url": {
             "type": [
               "string",
               "null"
             ],
-            "format": "uuid",
-            "description": "**Hadrian Extension:** Owner ID for multi-tenancy.\nWhen omitted along with `owner_type`, returns all accessible vector stores."
+            "description": "URL of the remote MCP server (Streamable HTTP). Mutually\nexclusive with `connector_id`."
           },
-          "owner_type": {
+          "type": {
+            "$ref": "#/components/schemas/McpToolType"
+          }
+        }
+      },
+      "McpToolFilter": {
+        "type": "object",
+        "description": "Spec `MCPToolFilter`: a set of tool names plus an optional\n`read_only` predicate that matches tools whose MCP `readOnlyHint`\nannotation is true. Either field is optional; both are AND-combined\n(tool name must be in `tool_names` *and* `read_only` must match if set).",
+        "properties": {
+          "read_only": {
             "type": [
-              "string",
+              "boolean",
               "null"
             ],
-            "description": "**Hadrian Extension:** Owner type for multi-tenancy (organization, team, project, or user).\nWhen omitted along with `owner_id`, returns all accessible vector stores."
+            "description": "Restrict to tools whose annotation `readOnlyHint == true`.\n`None` means don't filter on this property."
+          },
+          "tool_names": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "Tool names to include. Omit to match any name."
           }
-        }
+        },
+        "additionalProperties": false
       },
-      "LogicalOperator": {
+      "McpToolType": {
         "type": "string",
-        "description": "Logical operators for compound filters.",
         "enum": [
-          "and",
-          "or"
+          "mcp"
         ]
       },
       "MeResponse": {
@@ -29111,6 +30514,38 @@
         ],
         "description": "Response format for chat completion"
       },
+      "ResponsesToolDefinition": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/FileSearchTool"
+          },
+          {
+            "$ref": "#/components/schemas/WebSearchPreviewTool"
+          },
+          {
+            "$ref": "#/components/schemas/WebSearchPreview20250311Tool"
+          },
+          {
+            "$ref": "#/components/schemas/WebSearchTool"
+          },
+          {
+            "$ref": "#/components/schemas/WebSearch20250826Tool"
+          },
+          {
+            "$ref": "#/components/schemas/ShellTool"
+          },
+          {
+            "$ref": "#/components/schemas/McpTool"
+          },
+          {
+            "$ref": "#/components/schemas/ToolSearchTool"
+          },
+          {
+            "$ref": "#/components/schemas/FunctionTool"
+          }
+        ],
+        "description": "Tool definition - one of the supported tool variants. The schema\nemits a `oneOf` over the variants; each variant constrains its\n`type` field to a single literal, so consumers (and the OpenAPI\nconformance script) can match variants by `type`. The `Function`\nvariant stays as an opaque `serde_json::Value` at the data level\nso existing rewrite pipelines (web_search → function, shell →\nfunction, MCP → per-tool function) keep constructing it via JSON;\nthe schema reports it as a [`FunctionTool`] for documentation."
+      },
       "RollbackOrgRbacPolicy": {
         "type": "object",
         "description": "Request to rollback an RBAC policy to a previous version.",
@@ -29479,6 +30914,56 @@
           }
         }
       },
+      "ShellNetworkPolicy": {
+        "type": "object",
+        "description": "Per-domain egress policy. Matches OpenAI's `network_policy` shape:\n`{ \"type\": \"allowlist\", \"allowed_domains\": [...], \"domain_secrets\": [...] }`.",
+        "properties": {
+          "allowed_domains": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Hostnames or hostname patterns (`*.example.com`) the container\nmay make outbound requests to. Must be a subset of the\noperator's `allowed_egress_hosts`."
+          },
+          "domain_secrets": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Secrets injected for outbound traffic. Accepts either OpenAI's\ninline `{domain, name, value}` form or Hadrian's safer\n`{placeholder, allowed_domains}` reference form — see\n[`ShellDomainSecret`]."
+          },
+          "type": {
+            "type": "string",
+            "description": "Policy kind. Only `allowlist` is supported today; the field is\nhere for forward compatibility with future OpenAI additions."
+          }
+        },
+        "additionalProperties": false
+      },
+      "ShellTool": {
+        "type": "object",
+        "description": "Shell tool — instructs the model that it may call `shell` and the\ngateway will execute the resulting commands in a sandboxed runtime\n(or forward them to the upstream provider's hosted runtime if\nconfigured for passthrough).\n\nMirrors OpenAI's `shell` tool definition for GPT-5.2+. The\n`environment` block lets a caller request narrower constraints than\nthe operator's defaults — anything outside those defaults is\nrejected with `400` at request validation.",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "environment": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Runtime environment overrides. Every field is a **subset** of\nwhat `[features.server_tools.shell_limits]` permits; requests\nasking for more than the operator allows are rejected."
+          },
+          "type": {
+            "$ref": "#/components/schemas/ShellToolType"
+          }
+        }
+      },
+      "ShellToolType": {
+        "type": "string",
+        "enum": [
+          "shell"
+        ]
+      },
       "SimulateContext": {
         "type": "object",
         "description": "Context information for policy simulation",
@@ -31648,6 +33133,69 @@
           }
         }
       },
+      "ToolSearchExecution": {
+        "type": "string",
+        "description": "Whether a tool search ran on the server (Hadrian / OpenAI) or was\ndelegated to the client (BYOT). Hadrian only emits `Server`. Mirrors\nOpenAI's `ToolSearchExecutionType`.",
+        "enum": [
+          "server",
+          "client"
+        ]
+      },
+      "ToolSearchRankerKind": {
+        "type": "string",
+        "description": "Ranking strategy for Hadrian-side tool search over a deferred MCP\ncatalog. `Hybrid` fuses semantic + lexical relevance (RRF); `Semantic`\nis embedding cosine only; `Lexical` is token/substring scoring with no\nembedding dependency.",
+        "enum": [
+          "hybrid",
+          "semantic",
+          "lexical"
+        ]
+      },
+      "ToolSearchTool": {
+        "type": "object",
+        "description": "`tool_search` tool — OpenAI's `ToolSearchToolParam`. Configures\ndiscovery of deferred tools (`defer_loading: true`). Under\n`hadrian_hosted` a caller need not supply this: Hadrian synthesizes\nits own search tool whenever a deferred MCP server is present. A\ncaller may still include the entry to set the Hadrian-extension\n`ranker`; Hadrian reads that override and does not forward the entry\nto the model.",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "description": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Description shown to the model for a client-executed search tool."
+          },
+          "execution": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Whether the search executes server-side (hosted) or client-side\n(BYOT). Hadrian only supports server-side execution."
+          },
+          "parameters": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Parameter schema for a client-executed search tool. Opaque."
+          },
+          "ranker": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** per-request override of the ranking\nstrategy for Hadrian-side tool search. Takes precedence over the\n`[features.mcp.tool_search].ranker` deployment default. Requesting\n`semantic` on a deployment without an embedding provider returns\nHTTP 400 (`tool_search_ranker_unavailable`)."
+          },
+          "type": {
+            "$ref": "#/components/schemas/ToolSearchToolType"
+          }
+        }
+      },
+      "ToolSearchToolType": {
+        "type": "string",
+        "enum": [
+          "tool_search"
+        ]
+      },
       "ToolType": {
         "type": "string",
         "description": "Tool type",
@@ -34648,6 +36196,120 @@
           }
         }
       },
+      "WebSearch20250826Tool": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "filters": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "search_context_size": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/WebSearch20250826ToolType"
+          },
+          "user_location": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "WebSearch20250826ToolType": {
+        "type": "string",
+        "enum": [
+          "web_search_2025_08_26"
+        ]
+      },
+      "WebSearchPreview20250311Tool": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "search_context_size": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/WebSearchPreview20250311ToolType"
+          },
+          "user_location": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "WebSearchPreview20250311ToolType": {
+        "type": "string",
+        "enum": [
+          "web_search_preview_2025_03_11"
+        ]
+      },
+      "WebSearchPreviewTool": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "search_context_size": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/WebSearchPreviewToolType"
+          },
+          "user_location": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "WebSearchPreviewToolType": {
+        "type": "string",
+        "enum": [
+          "web_search_preview"
+        ]
+      },
       "WebSearchRequest": {
         "type": "object",
         "required": [
@@ -34705,6 +36367,48 @@
             "type": "string"
           }
         }
+      },
+      "WebSearchTool": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "filters": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "search_context_size": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/WebSearchToolType"
+          },
+          "user_location": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "WebSearchToolType": {
+        "type": "string",
+        "enum": [
+          "web_search"
+        ]
       }
     },
     "securitySchemes": {
diff --git a/scripts/openapi-conformance.py b/scripts/openapi-conformance.py
index 72b64e7..0179050 100755
--- a/scripts/openapi-conformance.py
+++ b/scripts/openapi-conformance.py
@@ -86,6 +86,28 @@
     ("/responses", "POST", "request", "version"): "OpenAI-specific version parameter",
     ("/responses", "POST", "request", "variables"): "OpenAI-specific variables parameter",
     ("/responses", "POST", "request", "context_management"): "OpenAI-specific context management",
+    # /responses tools[] - OpenAI-hosted tool variants not relevant to a gateway
+    ("/responses", "POST", "request", "tools[apply_patch]"): "OpenAI hosted apply_patch tool",
+    ("/responses", "POST", "request", "tools[code_interpreter]"): "OpenAI hosted code interpreter",
+    ("/responses", "POST", "request", "tools[computer]"): "OpenAI computer-use tool",
+    ("/responses", "POST", "request", "tools[computer_use_preview]"): "OpenAI computer-use preview tool",
+    ("/responses", "POST", "request", "tools[custom]"): "OpenAI custom tool (non-strict args)",
+    ("/responses", "POST", "request", "tools[image_generation]"): "OpenAI hosted image generation",
+    ("/responses", "POST", "request", "tools[local_shell]"): "OpenAI hosted local shell — Hadrian uses the `shell` variant",
+    ("/responses", "POST", "request", "tools[namespace]"): "OpenAI namespace tool",
+    ("/responses", "POST", "request", "tools[tool_search]"): "OpenAI tool-search feature",
+    # /responses/compact - OpenAI-specific fields
+    ("/responses/compact", "POST", "request", "prompt_cache_retention"): "OpenAI-specific cache retention",
+    ("/responses/compact", "POST", "request", "service_tier"): "OpenAI service tier selection (auto/default)",
+    # /responses/{response_id} - OpenAI-specific stored-response features
+    ("/responses/{response_id}", "GET", "param", "include"): "OpenAI stored-response include filters",
+    ("/responses/{response_id}", "GET", "param", "include_obfuscation"): "OpenAI internal obfuscation feature",
+    # /containers - OpenAI-specific list filters / pagination knobs
+    ("/containers", "GET", "param", "order"): "OpenAI sort-order param - Hadrian uses cursor pagination",
+    ("/containers", "GET", "param", "name"): "OpenAI name filter - not implemented",
+    ("/containers", "POST", "request", "type"): "Recursed from network_policy (opaque object in Hadrian's spec; discriminator only meaningful inside OpenAI's oneOf)",
+    ("/containers/{container_id}/files", "GET", "param", "order"): "OpenAI sort-order param - Hadrian uses cursor pagination",
+    ("/containers/{container_id}/files", "GET", "param", "after"): "OpenAI offset cursor - Hadrian uses opaque cursor pagination",
     # /vector_stores - OpenAI-specific features
     ("/vector_stores/{vector_store_id}/files", "POST", "request", "attributes"): "File attributes not implemented",
     ("/vector_stores/{vector_store_id}/files", "POST", "response", "static"): "Static file info not implemented",
@@ -164,6 +186,40 @@ class ConformanceReport:
     violations: list[Violation] = field(default_factory=list)
 
 
+def _is_array_type(schema: dict[str, Any]) -> bool:
+    """True if the schema declares `type: array` in either OpenAPI 3.0
+    (`"array"`) or 3.1 (`["array", "null"]`) form."""
+    if not isinstance(schema, dict):
+        return False
+    t = schema.get("type")
+    if t == "array":
+        return True
+    if isinstance(t, list) and "array" in t:
+        return True
+    return False
+
+
+def _extract_type_const(schema: dict[str, Any]) -> str | None:
+    """Pull the literal `type` value out of a tool-variant schema.
+
+    Returns the string when `schema.properties.type` constrains the
+    value to a single literal (via `enum: ["..."]` or `const: "..."`).
+    Returns `None` otherwise — caller treats the union as
+    non-discriminated and falls back to single-variant comparison.
+    """
+    if not isinstance(schema, dict):
+        return None
+    type_prop = schema.get("properties", {}).get("type")
+    if not isinstance(type_prop, dict):
+        return None
+    if isinstance(type_prop.get("const"), str):
+        return type_prop["const"]
+    enum_values = type_prop.get("enum")
+    if isinstance(enum_values, list) and len(enum_values) == 1 and isinstance(enum_values[0], str):
+        return enum_values[0]
+    return None
+
+
 class OpenAPIResolver:
     """Resolves $ref and allOf in OpenAPI schemas."""
 
@@ -189,13 +245,26 @@ def resolve_ref(self, ref: str) -> dict[str, Any]:
             else:
                 return {}
 
-        # Recursively resolve the result
+        # Pre-cache the raw schema so a recursive reference back to this
+        # ref (e.g. discriminated unions whose variants embed the parent
+        # type) short-circuits instead of looping. Once resolution
+        # completes we overwrite with the fully-resolved form.
+        self._cache[ref] = result if isinstance(result, dict) else {}
         resolved = self.resolve_schema(result)
         self._cache[ref] = resolved
         return resolved
 
     def resolve_schema(self, schema: dict[str, Any]) -> dict[str, Any]:
-        """Fully resolve a schema, handling $ref, allOf, oneOf, anyOf."""
+        """Fully resolve a schema, handling $ref, allOf, oneOf, anyOf.
+
+        For `oneOf`/`anyOf` with at least one variant whose `type`
+        property pins a literal value (e.g. `type.enum = ["mcp"]`), the
+        result keeps a `_union_variants` map keyed by that literal so
+        downstream code can compare each variant pairwise. Falls back
+        to the old "first option" behavior for unions without
+        discriminators (so generic shapes like `string | null` keep
+        working).
+        """
         if not isinstance(schema, dict):
             return schema
 
@@ -225,21 +294,42 @@ def resolve_schema(self, schema: dict[str, Any]) -> dict[str, Any]:
                     merged[key] = value
             return merged
 
-        # Handle oneOf/anyOf - return first option for simplicity (or could track all)
+        # Handle oneOf/anyOf. When every non-null variant pins a
+        # literal `type` value, keep the full union structure so
+        # `_compare_schemas` can match variants by discriminator across
+        # specs. Otherwise fall back to "first option" for primitive
+        # `string | null`-style unions.
         if "oneOf" in schema or "anyOf" in schema:
             options = schema.get("oneOf") or schema.get("anyOf", [])
-            # Filter out null types
             non_null_options = [
                 opt for opt in options
                 if not (isinstance(opt, dict) and opt.get("type") == "null")
             ]
-            if non_null_options:
-                resolved = self.resolve_schema(non_null_options[0])
-                # Mark as optional (since oneOf/anyOf implies it could be something else)
-                result = dict(resolved)
-                result["_nullable"] = True
-                return result
-            return {"type": "null", "_nullable": True}
+            if not non_null_options:
+                return {"type": "null", "_nullable": True}
+
+            resolved_variants = [self.resolve_schema(opt) for opt in non_null_options]
+            variant_map: dict[str, dict] = {}
+            for variant in resolved_variants:
+                type_value = _extract_type_const(variant)
+                if type_value is not None:
+                    variant_map[type_value] = variant
+
+            if variant_map:
+                # Discriminated union — keep all variants for pairwise
+                # comparison. Pick the first variant as the "fallback"
+                # shape for callers that don't understand `_union_variants`
+                # (matches the old behavior).
+                fallback = dict(resolved_variants[0])
+                fallback["_nullable"] = True
+                fallback["_union_variants"] = variant_map
+                return fallback
+
+            # Non-discriminated union — old behavior.
+            resolved = resolved_variants[0]
+            result = dict(resolved)
+            result["_nullable"] = True
+            return result
 
         # Resolve nested properties
         result = dict(schema)
@@ -297,6 +387,14 @@ class ConformanceChecker:
         "/vector_stores/{vector_store_id}/files/{file_id}": "/api/v1/vector_stores/{vector_store_id}/files/{file_id}",
         "/vector_stores/{vector_store_id}/search": "/api/v1/vector_stores/{vector_store_id}/search",
         "/responses": "/api/v1/responses",
+        "/responses/compact": "/api/v1/responses/compact",
+        "/responses/{response_id}": "/api/v1/responses/{response_id}",
+        "/responses/{response_id}/cancel": "/api/v1/responses/{response_id}/cancel",
+        "/containers": "/api/v1/containers",
+        "/containers/{container_id}": "/api/v1/containers/{container_id}",
+        "/containers/{container_id}/files": "/api/v1/containers/{container_id}/files",
+        "/containers/{container_id}/files/{file_id}": "/api/v1/containers/{container_id}/files/{file_id}",
+        "/containers/{container_id}/files/{file_id}/content": "/api/v1/containers/{container_id}/files/{file_id}/content",
     }
 
     # Endpoints out of scope for Hadrian
@@ -313,7 +411,6 @@ class ConformanceChecker:
         "/invites",
         "/users",
         "/projects",  # OpenAI projects, not Hadrian projects
-        "/containers",  # OpenAI container files feature
         "/conversations",  # OpenAI conversation API
         "/videos",  # OpenAI video generation
         "/chatkit",  # OpenAI chatkit feature
@@ -335,10 +432,7 @@ class ConformanceChecker:
         "/vector_stores/{vector_store_id}/file_batches/{batch_id}/files",
         "/vector_stores/{vector_store_id}/files/{file_id}/content",  # OpenAI file content
         "/responses/input_tokens",  # OpenAI-specific token endpoints
-        "/responses/compact",
-        "/responses/{response_id}",  # OpenAI stored responses management
-        "/responses/{response_id}/input_items",
-        "/responses/{response_id}/cancel",  # OpenAI response cancellation
+        "/responses/{response_id}/input_items",  # Not implemented (lookup returns the whole response)
     ]
 
     # Methods to exclude for specific paths
@@ -695,6 +789,114 @@ def _compare_schemas(
                 diffs.extend(nested_diffs)
                 violations.extend(nested_violations)
 
+            # Recurse into discriminated array<oneOf> shapes (e.g.
+            # `tools[]`, `input[]`, `output[]`). Each known `type`
+            # value is compared against its counterpart so
+            # variant-level differences (e.g. `tools[mcp].connector_id`)
+            # surface in the report. Handles OpenAPI 3.1's nullable
+            # form `type: ["array", "null"]` on either side.
+            if _is_array_type(openai_field) and _is_array_type(hadrian_field):
+                u_diffs, u_violations = self._compare_union_items(
+                    openai_field.get("items", {}),
+                    hadrian_field.get("items", {}),
+                    f"{context}.{field_name}[]",
+                    endpoint_path,
+                    method,
+                    location,
+                )
+                diffs.extend(u_diffs)
+                violations.extend(u_violations)
+
+        return diffs, violations
+
+    def _compare_union_items(
+        self,
+        openai_items: dict,
+        hadrian_items: dict,
+        context: str,
+        endpoint_path: str,
+        method: str,
+        location: str,
+    ) -> tuple[list[SchemaDiff], list[Violation]]:
+        """Compare two discriminated-union `items` schemas.
+
+        For each `type` literal present on either side, run
+        `_compare_schemas` on the matching variant pair. Variants only
+        on one side produce a single diff entry (missing or extension);
+        we do not recurse into them.
+        """
+        diffs: list[SchemaDiff] = []
+        violations: list[Violation] = []
+
+        openai_variants = openai_items.get("_union_variants") if isinstance(openai_items, dict) else None
+        hadrian_variants = hadrian_items.get("_union_variants") if isinstance(hadrian_items, dict) else None
+        if not openai_variants or not hadrian_variants:
+            return diffs, violations
+
+        # Strip the leading "<path> request"/" response" prefix the
+        # caller threaded through `context`, so the variant key matches
+        # the shape used in `DOCUMENTED_MISSING_FIELDS` (e.g.
+        # `tools[mcp]`, not `/responses request.tools[]<mcp>`).
+        short_context = context
+        for prefix in (f"{endpoint_path} request.", f"{endpoint_path} response."):
+            if short_context.startswith(prefix):
+                short_context = short_context[len(prefix):]
+                break
+        if short_context.endswith("[]"):
+            short_context = short_context[:-2]
+
+        all_type_values = set(openai_variants.keys()) | set(hadrian_variants.keys())
+        for type_value in sorted(all_type_values):
+            openai_variant = openai_variants.get(type_value)
+            hadrian_variant = hadrian_variants.get(type_value)
+            variant_key = f"{short_context}[{type_value}]"
+            variant_context = f"{context}<type={type_value}>"
+
+            if openai_variant is None:
+                diffs.append(SchemaDiff(
+                    path=context,
+                    field=type_value,
+                    diff_type=DiffType.HADRIAN_EXTENSION,
+                    hadrian_value="object",
+                    description=f"Variant '{type_value}' is a Hadrian extension",
+                ))
+                continue
+            if hadrian_variant is None:
+                diffs.append(SchemaDiff(
+                    path=context,
+                    field=type_value,
+                    diff_type=DiffType.MISSING_IN_HADRIAN,
+                    openai_value="object",
+                    description=f"Variant '{type_value}' missing in Hadrian",
+                ))
+                key = (endpoint_path, method, location, variant_key)
+                if key not in DOCUMENTED_MISSING_FIELDS:
+                    violations.append(Violation(
+                        violation_type="undocumented_missing",
+                        path=endpoint_path,
+                        method=method,
+                        field=variant_key,
+                        location=location,
+                        message=f"Union variant '{type_value}' at {short_context} missing in Hadrian",
+                    ))
+                continue
+
+            v_diffs, v_violations = self._compare_schemas(
+                openai_variant,
+                hadrian_variant,
+                variant_context,
+                endpoint_path,
+                method,
+                location,
+            )
+            # Tag each within-variant diff with its discriminator so
+            # `cache_control on file_search` reads as such in the
+            # report instead of an undifferentiated "Field 'cache_control'".
+            for d in v_diffs:
+                d.description = f"[{type_value}] {d.description}"
+            diffs.extend(v_diffs)
+            violations.extend(v_violations)
+
         return diffs, violations
 
     def _get_type_string(self, schema: dict) -> str:
diff --git a/src/api_types/mod.rs b/src/api_types/mod.rs
index 42077bf..2528d5b 100644
--- a/src/api_types/mod.rs
+++ b/src/api_types/mod.rs
@@ -15,4 +15,7 @@ pub use images::{
     CreateImageEditRequest, CreateImageRequest, CreateImageVariationRequest, ImageQuality,
     ImageSize,
 };
-pub use responses::{CreateResponsesPayload, ResponsesReasoningEffort};
+pub use responses::{
+    CompactRequest, CreateResponsesPayload, InlineSkill, InlineSkillSource, RequestSkill,
+    ResponsesReasoningEffort,
+};
diff --git a/src/api_types/responses.rs b/src/api_types/responses.rs
index 93da3eb..49c4dc6 100644
--- a/src/api_types/responses.rs
+++ b/src/api_types/responses.rs
@@ -484,6 +484,11 @@ pub struct FilePath {
 /// - **FilePath**: References a file generated during response creation
 ///   (e.g., by code_interpreter). Points to downloadable output files.
 ///
+/// - **ContainerFileCitation**: References a file written to the shell
+///   tool's `/mnt/data` workspace. Carries both the container and file
+///   IDs so the client can later download the bytes via the container
+///   files API.
+///
 /// ## Index Fields
 ///
 /// All annotation types include index fields indicating byte positions
@@ -525,6 +530,31 @@ pub enum ResponsesAnnotation {
         /// Byte offset where the file reference appears.
         index: u64,
     },
+    /// Citation to a file written to the shell tool's container
+    /// workspace (`/mnt/data`). Shape matches OpenAI's Responses API so
+    /// existing clients can render it without code changes.
+    ContainerFileCitation {
+        /// ID of the container the file lives in (`cntr_<uuid>`).
+        container_id: String,
+        /// Stable file identifier (`cfile_<uuid>`) usable with the
+        /// container files API to download the bytes.
+        file_id: String,
+        /// Display name of the file inside `/mnt/data`.
+        filename: String,
+        /// Byte offset where the cited range begins. Hadrian emits `0`
+        /// because we don't attempt to parse model output for filename
+        /// mentions; clients should render the annotation as a
+        /// whole-message reference.
+        #[serde(default)]
+        start_index: u64,
+        /// Byte offset where the cited range ends. Same caveat as
+        /// `start_index`.
+        #[serde(default)]
+        end_index: u64,
+        /// Optional single-position index. Hadrian emits `null`.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        index: Option<u64>,
+    },
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -705,6 +735,451 @@ pub struct FileSearchCallOutput {
     pub results: Option<Vec<FileSearchResultItem>>,
 }
 
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ShellCallType {
+    ShellCall,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ShellCallOutputItemType {
+    ShellCallOutput,
+}
+
+/// Status of a `shell_call` / `shell_call_output` item. Mirrors
+/// OpenAI's `LocalShellCallStatus` / `LocalShellCallOutputStatusEnum`.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum ShellCallStatus {
+    #[default]
+    InProgress,
+    Completed,
+    /// Call was abandoned mid-flight (cancelled, killed, or timed out
+    /// before the runtime reported an exit). Distinct from `completed`
+    /// with a non-zero exit — those still report `completed`.
+    Incomplete,
+}
+
+/// The `action` object on a `shell_call`. Mirrors OpenAI's
+/// `FunctionShellAction`: a list of shell command strings to run as a
+/// single script, plus optional per-call overrides.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ShellCallAction {
+    /// Shell command lines, joined with newlines and run as one script.
+    pub commands: Vec<String>,
+    /// Per-call timeout in milliseconds. Clamped by the operator's
+    /// `command_timeout_secs * 1000` cap.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout_ms: Option<u64>,
+    /// Per-call cap on stdout+stderr characters fed back to the model.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_output_length: Option<usize>,
+    /// **Hadrian Extension:** Per-call env vars. Not part of OpenAI's
+    /// `FunctionShellAction`; carried so non-OpenAI providers can drive
+    /// the same code path.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub env: Option<HashMap<String, String>>,
+    /// **Hadrian Extension:** Per-call working directory.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub working_directory: Option<String>,
+}
+
+/// Environment the shell call executed under. Mirrors OpenAI's union of
+/// `LocalEnvironmentResource` and `ContainerReferenceResource` on
+/// returned `shell_call` items.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ShellCallEnvironment {
+    /// Call ran against the API client's local environment (the spec's
+    /// `local` environment type).
+    Local,
+    /// Call ran against a managed container; `container_id` is the
+    /// `cntr_<hex>` of the workspace that executed it.
+    ContainerReference { container_id: String },
+}
+
+/// `shell_call` output item — the model-emitted request to run a shell
+/// command. Spec name: `FunctionShellCall`.
+///
+/// Paired with a [`ShellCallOutputItem`] carrying the result. The two
+/// items share a `call_id`; the `id` is the per-item identifier the
+/// API assigns when persisting the response.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ShellCall {
+    #[serde(rename = "type")]
+    pub type_: ShellCallType,
+    /// Per-item identifier assigned by the API when the response is
+    /// persisted. Not generated by the model.
+    pub id: String,
+    /// Model-generated call identifier. Pairs the shell_call with its
+    /// shell_call_output. Required by spec.
+    pub call_id: String,
+    /// Action object describing the commands and per-call overrides.
+    pub action: ShellCallAction,
+    /// Lifecycle status — `in_progress`, `completed`, or `incomplete`.
+    pub status: ShellCallStatus,
+    /// Environment the call executed under (or will execute under,
+    /// while `status == in_progress`).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub environment: Option<ShellCallEnvironment>,
+    /// **Hadrian Extension:** principal that authored the item
+    /// (`"model"`, `"gateway"`, `"client"`). Mirrors OpenAI's
+    /// `created_by` field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub created_by: Option<String>,
+}
+
+/// One content chunk in a [`ShellCallOutputItem`]. Spec name:
+/// `FunctionShellCallOutputContent`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ShellCallOutputContent {
+    /// Captured stdout for this chunk.
+    pub stdout: String,
+    /// Captured stderr for this chunk.
+    pub stderr: String,
+    /// What ended the call — either an exit code or a timeout.
+    pub outcome: ShellCallOutcome,
+    /// **Hadrian Extension:** principal that produced the chunk.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub created_by: Option<String>,
+}
+
+/// Discriminated outcome on a shell call output chunk. Spec union of
+/// `FunctionShellCallOutputExitOutcome` and
+/// `FunctionShellCallOutputTimeoutOutcome`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ShellCallOutcome {
+    /// Process exited normally with `exit_code`.
+    Exit { exit_code: i32 },
+    /// Call exceeded its configured time limit.
+    Timeout,
+}
+
+/// `shell_call_output` output item — the result of a [`ShellCall`].
+/// Spec name: `FunctionShellCallOutput`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ShellCallOutputItem {
+    #[serde(rename = "type")]
+    pub type_: ShellCallOutputItemType,
+    /// Per-item identifier assigned by the API when the response is
+    /// persisted.
+    pub id: String,
+    /// Matches the `call_id` of the paired [`ShellCall`].
+    pub call_id: String,
+    /// Lifecycle status — `in_progress`, `completed`, or `incomplete`.
+    pub status: ShellCallStatus,
+    /// Output content chunks. Currently a single entry per call; the
+    /// array form leaves room for the model to stream multi-chunk
+    /// transcripts in the future.
+    pub output: Vec<ShellCallOutputContent>,
+    /// Echoes the model-emitted `action.max_output_length` so clients
+    /// can see what the model asked for.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_output_length: Option<usize>,
+    /// **Hadrian Extension:** Files written to `/mnt/data` during this
+    /// command. Populated when the configured shell runtime supports
+    /// `file_io` and `[features.containers]` is enabled. Each entry's
+    /// `file_id` matches a `container_file_citation` annotation on the
+    /// assistant's reply.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub output_files: Vec<ContainerFileRef>,
+    /// **Hadrian Extension:** principal that authored the item.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub created_by: Option<String>,
+}
+
+/// Reference to one file produced or modified by a shell command.
+///
+/// Bytes are persisted in the `container_files` table so the
+/// `GET /v1/containers/{container_id}/files/{file_id}/content` endpoint
+/// can serve them; transient bytes also live in-process during a
+/// response for the active stream.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ContainerFileRef {
+    /// Container the file lives in (`cntr_<uuid>`).
+    pub container_id: String,
+    /// Stable identifier (`cfile_<uuid>`).
+    pub file_id: String,
+    /// Display name, taken from the path under `/mnt/data`.
+    pub filename: String,
+    /// Absolute path inside the container.
+    pub path: String,
+    /// Size in bytes.
+    pub bytes: u64,
+    /// Best-effort MIME type derived from the filename extension.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub content_type: Option<String>,
+    /// `"user"` if staged in from the request, `"assistant"` if written
+    /// by the model.
+    pub source: ContainerFileSource,
+}
+
+/// Origin of a captured container file.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ContainerFileSource {
+    /// File was staged into `/mnt/data` from an `input_file` part on
+    /// the request.
+    User,
+    /// File was written by the model during a shell command.
+    Assistant,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionItemType {
+    Compaction,
+}
+
+/// `compaction` output item — the marker the gateway (or upstream
+/// provider with native compaction) emits when conversation history
+/// is summarized to fit within the context window. Spec name:
+/// `CompactionBody`.
+///
+/// OpenAI's `/v1/responses/compact` endpoint returns this item type;
+/// it can also appear inline in a streamed response when
+/// `context_management` triggers a server-side compaction pass.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CompactionItem {
+    #[serde(rename = "type")]
+    pub type_: CompactionItemType,
+    /// Per-item identifier assigned by the API.
+    pub id: String,
+    /// Encrypted opaque blob produced by the compactor; replayed on
+    /// future turns to restore prior state. For OpenAI's native
+    /// compaction this is an encrypted token-efficient representation;
+    /// Hadrian's gateway-side compactor uses a plain-text fallback
+    /// (an English summary message) since we cannot mint encrypted
+    /// tokens the upstream model would understand. SDK consumers
+    /// treat the field opaquely.
+    pub encrypted_content: String,
+    /// **Hadrian Extension:** principal that authored the item.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub created_by: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum McpListToolsItemType {
+    McpListTools,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum McpItemStatus {
+    #[default]
+    InProgress,
+    /// HTTP request to the MCP server is in flight (after arguments are
+    /// finalized, before the terminal `completed` / `failed`).
+    Calling,
+    Completed,
+    Incomplete,
+    Failed,
+}
+
+/// Tool metadata advertised by a remote MCP server (one entry per tool
+/// exposed via the server's `tools/list` response). Surfaced in
+/// `mcp_list_tools` items so the model — and the persisted response —
+/// records what tool surface was available at call time.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct McpListedTool {
+    /// Tool name as exposed by the MCP server.
+    pub name: String,
+    /// Human-readable description forwarded from the server.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    /// JSON Schema describing the tool's parameters (forwarded verbatim
+    /// from the server's `inputSchema`). Opaque to Hadrian.
+    pub input_schema: serde_json::Value,
+    /// Optional annotations (read-only hints, idempotency, etc.) — kept
+    /// verbatim from the MCP server response.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub annotations: Option<serde_json::Value>,
+}
+
+/// `mcp_list_tools` output item — the snapshot of tools the model
+/// could call on a given MCP server during this response. Emitted once
+/// per server per response.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct McpListToolsItem {
+    #[serde(rename = "type")]
+    pub type_: McpListToolsItemType,
+    /// Per-item identifier assigned by the API.
+    pub id: String,
+    /// Matches the `server_label` on the requesting `McpTool`.
+    pub server_label: String,
+    /// Tool catalog returned by the server. Empty when `error` is set.
+    pub tools: Vec<McpListedTool>,
+    /// Populated when the `tools/list` call failed; carries the error
+    /// message verbatim so SDKs can surface it. Always serialized
+    /// (`null` on success) to match OpenAI's schema.
+    #[serde(default)]
+    pub error: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum McpCallItemType {
+    McpCall,
+}
+
+/// `mcp_call` output item — the model-initiated invocation of a
+/// remote MCP tool. Mirrors OpenAI's `MCPToolCall`: the result is
+/// carried inline (`output` / `error`) on the same item, not as a
+/// separate `mcp_call_output` item.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct McpCallItem {
+    #[serde(rename = "type")]
+    pub type_: McpCallItemType,
+    /// Per-item identifier assigned by the API.
+    pub id: String,
+    /// Matches the `server_label` on the requesting `McpTool`.
+    pub server_label: String,
+    /// Tool name as advertised on the remote server.
+    pub name: String,
+    /// Arguments as a serialized JSON string (mirrors the
+    /// `function_call.arguments` shape so SDKs can reuse helpers).
+    pub arguments: String,
+    /// Lifecycle status.
+    pub status: McpItemStatus,
+    /// Serialized tool result returned by the MCP server. `null` until
+    /// the call terminates successfully. Always serialized to match
+    /// OpenAI's schema.
+    #[serde(default)]
+    pub output: Option<String>,
+    /// Populated when the call failed (transport error, MCP protocol
+    /// error, or `isError=true` content block). `null` on success.
+    /// Always serialized to match OpenAI's schema.
+    #[serde(default)]
+    pub error: Option<String>,
+    /// `id` of the matching `mcp_approval_request` item when this call
+    /// was gated by `require_approval`. `null` for calls that ran
+    /// without approval. Always serialized to match OpenAI's schema.
+    #[serde(default)]
+    pub approval_request_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum McpApprovalRequestItemType {
+    McpApprovalRequest,
+}
+
+/// `mcp_approval_request` output item — emitted when the configured
+/// `require_approval` policy gates a model-initiated MCP call. The
+/// caller resumes execution by sending a matching
+/// [`McpApprovalResponseItem`] back on the next request's input.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct McpApprovalRequestItem {
+    #[serde(rename = "type")]
+    pub type_: McpApprovalRequestItemType,
+    /// Per-item identifier. The caller echoes this as
+    /// `approval_request_id` on their `mcp_approval_response`.
+    pub id: String,
+    /// Matches the `server_label` on the requesting `McpTool`.
+    pub server_label: String,
+    /// Tool name the model wants to call.
+    pub name: String,
+    /// Arguments the model proposed (JSON string, matching `McpCallItem`).
+    pub arguments: String,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum McpApprovalResponseItemType {
+    McpApprovalResponse,
+}
+
+/// `mcp_approval_response` input item — the caller's decision on a
+/// pending [`McpApprovalRequestItem`]. Sent on the next request's
+/// input to resume (or refuse) the parked MCP call.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct McpApprovalResponseItem {
+    #[serde(rename = "type")]
+    pub type_: McpApprovalResponseItemType,
+    /// Echoes the `id` of the prior `McpApprovalRequestItem`.
+    pub approval_request_id: String,
+    /// `true` to let the call proceed, `false` to refuse.
+    pub approve: bool,
+    /// Optional free-text rationale. Surfaced to the model in the
+    /// refusal payload so it can react to the reason.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reason: Option<String>,
+}
+
+/// Whether a tool search ran on the server (Hadrian / OpenAI) or was
+/// delegated to the client (BYOT). Hadrian only emits `Server`. Mirrors
+/// OpenAI's `ToolSearchExecutionType`.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum ToolSearchExecution {
+    #[default]
+    Server,
+    Client,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ToolSearchCallItemType {
+    ToolSearchCall,
+}
+
+/// `tool_search_call` output item — the model's request to search the
+/// deferred tool catalog. Mirrors OpenAI's `ToolSearchCall`. Under
+/// `hadrian_hosted` this is synthesized from the model's underlying
+/// `tool_search` function call; the raw function-call plumbing is
+/// suppressed so the stream carries only this spec-shaped item.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ToolSearchCallItem {
+    #[serde(rename = "type")]
+    pub type_: ToolSearchCallItemType,
+    /// Per-item identifier assigned by the API.
+    pub id: String,
+    /// Identifier the model assigned to the call. Always serialized
+    /// (`null` when absent) to match OpenAI's schema.
+    #[serde(default)]
+    pub call_id: Option<String>,
+    /// Whether the search ran server-side or client-side.
+    pub execution: ToolSearchExecution,
+    /// Arguments the model passed to the search (the query, optional
+    /// `server_label`). Carried as a JSON value, matching OpenAI.
+    pub arguments: serde_json::Value,
+    /// Lifecycle status.
+    pub status: ToolCallStatus,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ToolSearchOutputItemType {
+    ToolSearchOutput,
+}
+
+/// `tool_search_output` output item — the tool definitions the search
+/// surfaced for the matching `tool_search_call`. Mirrors OpenAI's
+/// `ToolSearchOutput`. The model can then call any of the returned
+/// tools; under `hadrian_hosted` those definitions are also injected
+/// into the continuation request so the call actually resolves.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ToolSearchOutputItem {
+    #[serde(rename = "type")]
+    pub type_: ToolSearchOutputItemType,
+    /// Per-item identifier assigned by the API.
+    pub id: String,
+    /// Echoes the `call_id` of the matching `tool_search_call`. Always
+    /// serialized (`null` when absent) to match OpenAI's schema.
+    #[serde(default)]
+    pub call_id: Option<String>,
+    /// Whether the search ran server-side or client-side.
+    pub execution: ToolSearchExecution,
+    /// The loaded tool definitions returned by the search.
+    pub tools: Vec<serde_json::Value>,
+    /// Lifecycle status.
+    pub status: ToolCallStatus,
+}
+
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
 pub enum ImageGenerationCallType {
@@ -733,6 +1208,15 @@ pub enum ResponsesInputItem {
     OutputFunctionCall(OutputItemFunctionCall),
     WebSearchCall(WebSearchCallOutput),
     FileSearchCall(FileSearchCallOutput),
+    ShellCall(ShellCall),
+    ShellCallOutput(ShellCallOutputItem),
+    McpListTools(McpListToolsItem),
+    McpCall(McpCallItem),
+    McpApprovalRequest(McpApprovalRequestItem),
+    McpApprovalResponse(McpApprovalResponseItem),
+    ToolSearchCall(ToolSearchCallItem),
+    ToolSearchOutput(ToolSearchOutputItem),
+    Compaction(CompactionItem),
     ImageGeneration(ImageGenerationCall),
 }
 
@@ -751,6 +1235,14 @@ pub enum ResponsesOutputItem {
     FunctionCall(OutputItemFunctionCall),
     WebSearchCall(WebSearchCallOutput),
     FileSearchCall(FileSearchCallOutput),
+    ShellCall(ShellCall),
+    ShellCallOutput(ShellCallOutputItem),
+    McpListTools(McpListToolsItem),
+    McpCall(McpCallItem),
+    McpApprovalRequest(McpApprovalRequestItem),
+    ToolSearchCall(ToolSearchCallItem),
+    ToolSearchOutput(ToolSearchOutputItem),
+    Compaction(CompactionItem),
     ImageGeneration(ImageGenerationCall),
 }
 
@@ -781,82 +1273,108 @@ pub struct WebSearchFilters {
 }
 
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(rename_all = "snake_case")]
 pub enum WebSearchPreviewToolType {
     WebSearchPreview,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub struct WebSearchPreviewTool {
     #[serde(rename = "type")]
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
     pub type_: WebSearchPreviewToolType,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<String>))]
     pub search_context_size: Option<ResponsesSearchContextSize>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub user_location: Option<WebSearchUserLocation>,
     /// **Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub cache_control: Option<CacheControl>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub enum WebSearchPreview20250311ToolType {
     #[serde(rename = "web_search_preview_2025_03_11")]
     WebSearchPreview20250311,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub struct WebSearchPreview20250311Tool {
     #[serde(rename = "type")]
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
     pub type_: WebSearchPreview20250311ToolType,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<String>))]
     pub search_context_size: Option<ResponsesSearchContextSize>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub user_location: Option<WebSearchUserLocation>,
     /// **Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub cache_control: Option<CacheControl>,
 }
 
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(rename_all = "snake_case")]
 pub enum WebSearchToolType {
     WebSearch,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub struct WebSearchTool {
     #[serde(rename = "type")]
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
     pub type_: WebSearchToolType,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub filters: Option<WebSearchFilters>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<String>))]
     pub search_context_size: Option<ResponsesSearchContextSize>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub user_location: Option<WebSearchUserLocation>,
     /// **Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub cache_control: Option<CacheControl>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub enum WebSearch20250826ToolType {
     #[serde(rename = "web_search_2025_08_26")]
     WebSearch20250826,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub struct WebSearch20250826Tool {
     #[serde(rename = "type")]
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
     pub type_: WebSearch20250826ToolType,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub filters: Option<WebSearchFilters>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<String>))]
     pub search_context_size: Option<ResponsesSearchContextSize>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub user_location: Option<WebSearchUserLocation>,
     /// **Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
     pub cache_control: Option<CacheControl>,
 }
 
@@ -865,6 +1383,7 @@ pub struct WebSearch20250826Tool {
 // ─────────────────────────────────────────────────────────────────────────────
 
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(rename_all = "snake_case")]
 pub enum FileSearchToolType {
     FileSearch,
@@ -895,74 +1414,753 @@ pub enum FileSearchFilterComparison {
     Lte,
 }
 
-/// A single comparison filter for file search.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
-pub struct FileSearchComparisonFilter {
-    #[serde(rename = "type")]
-    pub type_: FileSearchFilterComparison,
-    pub key: String,
-    pub value: serde_json::Value,
+/// A single comparison filter for file search.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+pub struct FileSearchComparisonFilter {
+    #[serde(rename = "type")]
+    pub type_: FileSearchFilterComparison,
+    pub key: String,
+    pub value: serde_json::Value,
+}
+
+/// Logical operator types for compound filters.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum FileSearchFilterLogicalType {
+    And,
+    Or,
+}
+
+/// A compound filter combining multiple filters with a logical operator.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+pub struct FileSearchCompoundFilter {
+    #[serde(rename = "type")]
+    pub type_: FileSearchFilterLogicalType,
+    pub filters: Vec<FileSearchFilter>,
+}
+
+/// File search filter - either a comparison or a compound filter.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(untagged)]
+pub enum FileSearchFilter {
+    Comparison(FileSearchComparisonFilter),
+    Compound(FileSearchCompoundFilter),
+}
+
+/// File search tool for RAG in the Responses API.
+/// Enables semantic search across vector stores.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+pub struct FileSearchTool {
+    #[serde(rename = "type")]
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
+    pub type_: FileSearchToolType,
+    /// Vector store IDs to search across.
+    pub vector_store_ids: Vec<String>,
+    /// Maximum number of results to return.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_num_results: Option<usize>,
+    /// Ranking options for controlling result relevance.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
+    pub ranking_options: Option<FileSearchRankingOptions>,
+    /// Metadata filters to apply to the search.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
+    pub filters: Option<FileSearchFilter>,
+    /// **Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
+    pub cache_control: Option<CacheControl>,
+}
+
+impl FileSearchTool {
+    /// Check if this is a file_search tool.
+    pub fn is_file_search(&self) -> bool {
+        matches!(self.type_, FileSearchToolType::FileSearch)
+    }
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum ShellToolType {
+    Shell,
+}
+
+/// Shell tool — instructs the model that it may call `shell` and the
+/// gateway will execute the resulting commands in a sandboxed runtime
+/// (or forward them to the upstream provider's hosted runtime if
+/// configured for passthrough).
+///
+/// Mirrors OpenAI's `shell` tool definition for GPT-5.2+. The
+/// `environment` block lets a caller request narrower constraints than
+/// the operator's defaults — anything outside those defaults is
+/// rejected with `400` at request validation.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+pub struct ShellTool {
+    #[serde(rename = "type")]
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
+    pub type_: ShellToolType,
+    /// Runtime environment overrides. Every field is a **subset** of
+    /// what `[features.server_tools.shell_limits]` permits; requests
+    /// asking for more than the operator allows are rejected.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
+    pub environment: Option<ShellEnvironment>,
+}
+
+/// Per-request runtime-environment overrides. Tagged on `type` per
+/// OpenAI's `shell` tool spec:
+///
+/// - `container_auto` — let the gateway provision a container, with
+///   optional `memory_limit`, `network_policy`, `file_ids`, and `skills`.
+/// - `container_reference` — attach to a specific `container_id`
+///   created earlier via `POST /v1/containers` (or chained via a prior
+///   response). Operator caps still apply at execution time.
+/// - `local` — the API client itself runs shell commands and returns
+///   `shell_call_output` items back. Requires the `client_passthrough`
+///   runtime; rejected with 400 otherwise.
+///
+/// Hadrian historically accepted a flat object with `container_auto`
+/// as a nested field plus environment-level `domain_secrets`; that
+/// shape is no longer accepted — the wire format must match OpenAI's
+/// SDK contract.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ShellEnvironment {
+    /// Provision a fresh (or reuse a chained) container with the
+    /// supplied policy. Equivalent to OpenAI's
+    /// `{"type": "container_auto", …}`.
+    ContainerAuto(ShellContainerAuto),
+    /// Attach to an existing container by id. Used when the caller
+    /// pre-created a container via `POST /v1/containers` and wants
+    /// every response to land in that workspace.
+    ContainerReference(ShellContainerReference),
+    /// API client runs shell commands locally and returns
+    /// `shell_call_output` items. Spec name: `LocalEnvironmentParam`.
+    Local(ShellLocalEnvironment),
+}
+
+impl ShellEnvironment {
+    /// True when the environment is the auto variant. Used by the
+    /// request-resolver to decide whether to consult container-level
+    /// fields like `memory_limit`.
+    pub fn is_auto(&self) -> bool {
+        matches!(self, ShellEnvironment::ContainerAuto(_))
+    }
+
+    /// True when the environment delegates execution to the API client.
+    pub fn is_local(&self) -> bool {
+        matches!(self, ShellEnvironment::Local(_))
+    }
+
+    /// Egress policy regardless of variant. `local` has no egress
+    /// policy (the client manages its own network).
+    pub fn network_policy(&self) -> Option<&ShellNetworkPolicy> {
+        match self {
+            ShellEnvironment::ContainerAuto(a) => a.network_policy.as_ref(),
+            ShellEnvironment::ContainerReference(r) => r.network_policy.as_ref(),
+            ShellEnvironment::Local(_) => None,
+        }
+    }
+
+    /// `container_id` when explicitly referenced.
+    pub fn container_reference_id(&self) -> Option<&str> {
+        match self {
+            ShellEnvironment::ContainerReference(r) => Some(r.container_id.as_str()),
+            _ => None,
+        }
+    }
+}
+
+/// Container auto-provisioning overrides (the OpenAI `container_auto`
+/// shape: `ContainerAutoParam`).
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ShellContainerAuto {
+    /// Memory ceiling for the container, e.g. `"512m"`, `"1g"`. Parsed
+    /// case-insensitively. Capped by the operator's `max_mem_limit_mb`.
+    /// Spec enumerates `1g | 4g | 16g | 64g` only; Hadrian accepts
+    /// arbitrary `<n>[k|m|g]` values for runtime-tuning flexibility.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub memory_limit: Option<String>,
+    /// Network policy applied to outbound traffic from the container.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub network_policy: Option<ShellNetworkPolicy>,
+    /// Pre-uploaded Files-API IDs to stage into `/mnt/data` at session
+    /// start. Spec: `ContainerAutoParam.file_ids`. Resolved via the
+    /// same Files-API path as `input_file` parts on the request.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub file_ids: Option<Vec<String>>,
+    /// Skills to mount for this session. Spec: `ContainerAutoParam.skills`.
+    /// Same type as the top-level `skills` field on the request — they
+    /// merge with whatever's defined at request scope.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub skills: Option<Vec<RequestSkill>>,
+    /// Per-request idle-TTL override. Spec: `ContainerAutoParam.expires_after`
+    /// — `{anchor: "last_active_at", minutes: N}`. Capped by
+    /// `[features.containers].max_idle_ttl_secs / 60`; omitted means
+    /// fall back to the container row's persisted TTL (when chained)
+    /// or `default_idle_ttl_secs` (for a fresh auto session).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub expires_after: Option<ContainerExpiresAfter>,
+}
+
+/// Reference to an existing container created via
+/// `POST /v1/containers`. Per OpenAI's spec, the network policy can
+/// still be tightened per-request; widening beyond the container's
+/// stored policy (or the operator caps) is rejected.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ShellContainerReference {
+    /// `cntr_<hex>` of the container to attach to. Must belong to the
+    /// caller's organization and be in `active` status.
+    pub container_id: String,
+    /// Network policy applied to outbound traffic from the session.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub network_policy: Option<ShellNetworkPolicy>,
+}
+
+/// Local-execution environment. Spec name: `LocalEnvironmentParam`.
+/// The model emits `shell_call` items and the API client (not the
+/// gateway) executes them and returns `shell_call_output` items.
+/// Hadrian routes the call through but doesn't execute it.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ShellLocalEnvironment {
+    /// Skills the client claims are mounted on its local filesystem.
+    /// Each entry carries the path on the client side so the model
+    /// can refer to it. Spec name: `LocalSkillParam`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub skills: Option<Vec<LocalSkill>>,
+}
+
+/// A skill mounted on the API client's local filesystem. Spec name:
+/// `LocalSkillParam`. Carries the client-side `path` rather than a
+/// gateway-resolvable id since the client owns the filesystem.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LocalSkill {
+    /// Display name surfaced to the model.
+    pub name: String,
+    /// Human-readable description.
+    pub description: String,
+    /// Path on the client where the skill bundle lives.
+    pub path: String,
+}
+
+/// Container TTL hint. Mirrors OpenAI's `expires_after` shape — only
+/// `last_active_at` is honored today (the same anchor the operator's
+/// idle reaper uses), with `minutes` setting the per-container idle
+/// TTL.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ContainerExpiresAfter {
+    /// Anchor for the TTL countdown. Today only `"last_active_at"` is
+    /// supported; unknown anchors reject with 400.
+    #[serde(default)]
+    pub anchor: ContainerExpiresAfterAnchor,
+    /// Minutes after `anchor` when the container expires. Validated
+    /// against `[features.containers].max_idle_ttl_secs / 60`.
+    pub minutes: u32,
+}
+
+#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum ContainerExpiresAfterAnchor {
+    #[default]
+    LastActiveAt,
+}
+
+/// Per-domain egress policy. Matches OpenAI's `network_policy` shape:
+/// `{ "type": "allowlist", "allowed_domains": [...], "domain_secrets": [...] }`.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ShellNetworkPolicy {
+    /// Policy kind. Only `allowlist` is supported today; the field is
+    /// here for forward compatibility with future OpenAI additions.
+    #[serde(default, rename = "type")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = String, rename = "type"))]
+    pub type_: ShellNetworkPolicyType,
+    /// Hostnames or hostname patterns (`*.example.com`) the container
+    /// may make outbound requests to. Must be a subset of the
+    /// operator's `allowed_egress_hosts`.
+    #[serde(default)]
+    pub allowed_domains: Vec<String>,
+    /// Secrets injected for outbound traffic. Accepts either OpenAI's
+    /// inline `{domain, name, value}` form or Hadrian's safer
+    /// `{placeholder, allowed_domains}` reference form — see
+    /// [`ShellDomainSecret`].
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Vec<Object>))]
+    pub domain_secrets: Vec<ShellDomainSecret>,
+}
+
+/// Discriminator on `network_policy.type`. Today only `allowlist` is
+/// defined; the `Other` catch-all preserves the upstream value so a
+/// future OpenAI addition (e.g. `denylist`) doesn't reject requests at
+/// the gateway. The shell executor still applies the allowlist policy
+/// regardless — operators get unknown types logged and treated as
+/// `allowlist`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case", untagged)]
+pub enum ShellNetworkPolicyType {
+    Known(KnownShellNetworkPolicyType),
+    /// Forward-compat: anything the gateway hasn't been taught yet.
+    Other(String),
+}
+
+impl Default for ShellNetworkPolicyType {
+    fn default() -> Self {
+        Self::Known(KnownShellNetworkPolicyType::Allowlist)
+    }
+}
+
+#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum KnownShellNetworkPolicyType {
+    #[default]
+    Allowlist,
+    /// Deny-all egress. Spec: `ContainerNetworkPolicyDisabledParam`.
+    /// `allowed_domains` and `domain_secrets` must be empty when this
+    /// is set; the resolver rejects requests that combine them.
+    Disabled,
+}
+
+/// One entry in `network_policy.domain_secrets`. Accepts two forms via
+/// untagged dispatch so OpenAI SDKs and Hadrian-aware callers both
+/// work:
+///
+/// - **Inline (OpenAI)** — `{ "domain": "...", "name": "...", "value": "..." }`
+///   the secret value travels on the wire. Useful for ad-hoc tokens
+///   the caller owns directly.
+/// - **Reference (Hadrian extension)** — `{ "placeholder": "...", "allowed_domains": [...] }`
+///   matches an operator-configured secret in
+///   `[features.server_tools.shell_limits].allowed_domain_secrets` so
+///   the raw value never leaves the gateway.
+///
+/// Reference form is parsed first so a `{placeholder, ...}` payload
+/// never accidentally matches the inline shape.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum ShellDomainSecret {
+    Reference(ShellDomainSecretRef),
+    Inline(ShellDomainSecretInline),
+}
+
+/// Hadrian-extension placeholder reference into the operator's
+/// pre-configured secret store.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ShellDomainSecretRef {
+    /// Placeholder name, matched against
+    /// `allowed_domain_secrets[<name>]` in operator config.
+    pub placeholder: String,
+    /// Hosts this secret may flow to. Must be a subset of the
+    /// operator-configured `allowed_hosts` for the placeholder; empty
+    /// means "all hosts the operator permits for this secret".
+    #[serde(default)]
+    pub allowed_domains: Vec<String>,
+}
+
+/// One entry in `skills` on a `/v1/responses` or `/v1/containers`
+/// request. Tagged per OpenAI's spec:
+///
+/// - `skill_reference` resolves a stored skill by UUID.
+/// - `inline` embeds an ephemeral skill bundle in the request itself.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum RequestSkill {
+    /// Mount a skill that was previously created via the skills API.
+    SkillReference(SkillReference),
+    /// Mount an ephemeral skill bundle carried inline on the request.
+    Inline(InlineSkill),
+}
+
+/// Reference to an existing skill resource (Hadrian skill UUID).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SkillReference {
+    /// Hadrian skill UUID. Must belong to the caller's org.
+    pub skill_id: String,
+    /// Version pin. Only `"latest"` is supported today; passing any
+    /// other value rejects the request with 400 so callers don't
+    /// silently get the latest when they asked for a pin.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub version: Option<String>,
+}
+
+/// Inline skill bundle. Mounted under `/skills/<synthetic-id>/` for
+/// the lifetime of the request (or the container, when supplied at
+/// container creation).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct InlineSkill {
+    /// Display name for the skill. Surfaced to the model in the
+    /// auto-prepended `instructions` preamble.
+    pub name: String,
+    /// Human-readable description. Also surfaced to the model.
+    pub description: String,
+    /// Encoded payload. `source.type = "base64"` only today.
+    pub source: InlineSkillSource,
+}
+
+/// Payload of an [`InlineSkill`]. Tagged so future encodings (e.g.
+/// `url`, `file_id`) slot in without breaking older clients.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
+pub enum InlineSkillSource {
+    /// Base64-encoded payload. `media_type` controls how the bytes are
+    /// interpreted: `text/markdown` ⇒ single `SKILL.md`. Other media
+    /// types reject with 400 until multi-file (zip) support lands.
+    Base64 { media_type: String, data: String },
+}
+
+/// OpenAI-compatible inline secret. The raw value travels with the
+/// request; the gateway scopes it to `domain` at egress.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ShellDomainSecretInline {
+    /// Host (or `*.suffix`) the secret may flow to.
+    pub domain: String,
+    /// Environment-variable name the secret is exposed as inside the
+    /// container.
+    pub name: String,
+    /// Raw secret value. Subject to the same operator host caps as the
+    /// reference form.
+    pub value: String,
+}
+
+impl ShellTool {
+    pub fn is_shell(&self) -> bool {
+        matches!(self.type_, ShellToolType::Shell)
+    }
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum McpToolType {
+    Mcp,
+}
+
+/// MCP tool — lets the model invoke tools exposed by a remote Model
+/// Context Protocol server (Atlassian, Notion, GitHub, HuggingFace, …).
+///
+/// Mirrors OpenAI's `mcp` tool. Two mutually-exclusive shapes: pointing
+/// at a remote server via `server_url`, or pointing at an OpenAI
+/// first-party connector via `connector_id`. The caller supplies any
+/// `authorization` bearer token directly on the tool entry; Hadrian
+/// does not persist or rewrite it.
+///
+/// Under `mode = passthrough_openai` the tool entry is forwarded
+/// verbatim to OpenAI / Azure OpenAI, and non-OpenAI providers reject
+/// with `mcp_passthrough_unsupported_provider`. Under
+/// `mode = hadrian_hosted` the gateway runs the MCP client loop itself
+/// via `rmcp` and rewrites the tool into per-tool function tools, so
+/// any provider can drive it.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+pub struct McpTool {
+    #[serde(rename = "type")]
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
+    pub type_: McpToolType,
+    /// Stable identifier surfaced in `mcp_list_tools` and `mcp_call`
+    /// items. Required even when using `connector_id` so output items
+    /// have a consistent label.
+    pub server_label: String,
+    /// URL of the remote MCP server (Streamable HTTP). Mutually
+    /// exclusive with `connector_id`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub server_url: Option<String>,
+    /// Identifier for an OpenAI-maintained connector
+    /// (e.g. `connector_googlecalendar`). Mutually exclusive with
+    /// `server_url`. Only usable under `mode = passthrough_openai`;
+    /// `hadrian_hosted` cannot reach OpenAI's connector registry.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub connector_id: Option<String>,
+    /// Human-readable description surfaced to the model.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub server_description: Option<String>,
+    /// Bearer / OAuth access token. The caller obtains this
+    /// out-of-band (OpenAI's API does not run the OAuth dance for the
+    /// remote server, and neither does Hadrian). Sent verbatim to the
+    /// MCP server's `Authorization` header. Hadrian does not persist
+    /// the value — clients must include it on every request.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub authorization: Option<String>,
+    /// Additional HTTP headers sent with every JSON-RPC call to the
+    /// MCP server. Useful for region or workspace selectors.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub headers: Option<HashMap<String, String>>,
+    /// Approval gate. Spec default is `"always"` when omitted — under
+    /// `hadrian_hosted` the executor enforces that default; under
+    /// `passthrough_openai` the field is forwarded verbatim and OpenAI
+    /// applies its own default.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub require_approval: Option<McpRequireApproval>,
+    /// Restrict which tools from the server are exposed to the model.
+    /// Accepts either a flat list of tool names or an object form for
+    /// forward-compat with extra knobs.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub allowed_tools: Option<McpAllowedTools>,
+    /// Delay loading the tool definitions until the model discovers them
+    /// via tool search, rather than dumping the whole catalog into the
+    /// prompt. Forwarded verbatim under `passthrough_openai` (OpenAI runs
+    /// its native tool search). Under `hadrian_hosted` deferral is
+    /// realized by **Hadrian-side tool search**: the gateway exposes a
+    /// single `tool_search` function tool, keeps the catalog server-side,
+    /// and lazily injects matched per-tool function definitions as the
+    /// model discovers them — so deferral works behind every provider,
+    /// not just OpenAI. The upstream `tools/list` catalog fetch always
+    /// runs eagerly at rewrite time (it's needed to know what's
+    /// searchable); only the per-tool definitions are deferred.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub defer_loading: Option<bool>,
+    /// **Hadrian Extension:** opt out of Hadrian-side tool search and let
+    /// the upstream handle `defer_loading` natively. Only honored when
+    /// `defer_loading` is set, the gateway is in `hadrian_hosted` mode,
+    /// and the resolved provider is OpenAI / Azure OpenAI (which
+    /// implement native tool search); rejected with HTTP 400 otherwise.
+    /// Default/`None` keeps the provider-agnostic Hadrian-side path.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub defer_loading_passthrough: Option<bool>,
+    /// **Hadrian Extension:** upper bound, in seconds, on a single
+    /// `tools/call` round-trip to this MCP server under `hadrian_hosted`.
+    /// Overrides the `[features.mcp].call_timeout_secs` deployment default
+    /// (300s). On expiry the in-flight `mcp_call` terminates with
+    /// `status="incomplete"` and a timeout `error`. Not part of OpenAI's
+    /// spec; ignored under `passthrough_openai` (the upstream owns the
+    /// call loop there).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub call_timeout_secs: Option<u64>,
+}
+
+impl McpTool {
+    pub fn is_mcp(&self) -> bool {
+        matches!(self.type_, McpToolType::Mcp)
+    }
+
+    /// True if exactly one of `server_url` / `connector_id` is set.
+    /// `McpTool` deliberately doesn't enforce this at deserialize time
+    /// so the preprocessor can surface a clean 400 error instead of a
+    /// serde error blob.
+    pub fn has_exactly_one_target(&self) -> bool {
+        self.server_url.is_some() ^ self.connector_id.is_some()
+    }
+}
+
+/// Closed enum of OpenAI's first-party connector ids. OpenAI's OpenAPI
+/// defines `connector_id` as an enum of exactly these values; we mirror
+/// the list so the preprocess can reject unknown ids early with a
+/// stable error code rather than waiting for the upstream to 4xx.
+pub const MCP_CONNECTOR_IDS: &[&str] = &[
+    "connector_dropbox",
+    "connector_gmail",
+    "connector_googlecalendar",
+    "connector_googledrive",
+    "connector_microsoftteams",
+    "connector_outlookcalendar",
+    "connector_outlookemail",
+    "connector_sharepoint",
+];
+
+/// True iff `id` matches one of [`MCP_CONNECTOR_IDS`].
+pub fn is_known_mcp_connector_id(id: &str) -> bool {
+    MCP_CONNECTOR_IDS.contains(&id)
+}
+
+/// Approval gating shape for the MCP tool. Accepts the spec's string
+/// shorthand (`"always"` / `"never"`) or an object with `always` / `never`
+/// filters that opt subsets in or out of the approval gate.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(untagged)]
+pub enum McpRequireApproval {
+    Mode(McpApprovalMode),
+    Filter(McpApprovalFilter),
 }
 
-/// Logical operator types for compound filters.
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
-#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(rename_all = "snake_case")]
-pub enum FileSearchFilterLogicalType {
-    And,
-    Or,
+pub enum McpApprovalMode {
+    Always,
+    Never,
 }
 
-/// A compound filter combining multiple filters with a logical operator.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
-pub struct FileSearchCompoundFilter {
-    #[serde(rename = "type")]
-    pub type_: FileSearchFilterLogicalType,
-    pub filters: Vec<FileSearchFilter>,
+/// Object form of `require_approval`. `always` lists tools that must
+/// be gated; `never` lists tools that bypass the gate. Tools not named
+/// in either fall back to the default (gate). Mirrors OpenAI's
+/// `MCPToolApprovalFilter`.
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(deny_unknown_fields)]
+pub struct McpApprovalFilter {
+    /// Tools that require approval.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub always: Option<McpToolFilter>,
+    /// Tools exempt from approval.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub never: Option<McpToolFilter>,
 }
 
-/// File search filter - either a comparison or a compound filter.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+/// Tool whitelist for an `McpTool`. Untagged so OpenAI's accepted
+/// shorthand `["tool_a", "tool_b"]` round-trips as the `List` variant
+/// and the `{tool_names: [...], read_only?: bool}` object form picks
+/// up extra knobs.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(untagged)]
-pub enum FileSearchFilter {
-    Comparison(FileSearchComparisonFilter),
-    Compound(FileSearchCompoundFilter),
+pub enum McpAllowedTools {
+    List(Vec<String>),
+    Filter(McpToolFilter),
 }
 
-/// File search tool for RAG in the Responses API.
-/// Enables semantic search across vector stores.
+/// Spec `MCPToolFilter`: a set of tool names plus an optional
+/// `read_only` predicate that matches tools whose MCP `readOnlyHint`
+/// annotation is true. Either field is optional; both are AND-combined
+/// (tool name must be in `tool_names` *and* `read_only` must match if set).
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(deny_unknown_fields)]
+pub struct McpToolFilter {
+    /// Tool names to include. Omit to match any name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tool_names: Option<Vec<String>>,
+    /// Restrict to tools whose annotation `readOnlyHint == true`.
+    /// `None` means don't filter on this property.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub read_only: Option<bool>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum ToolSearchToolType {
+    ToolSearch,
+}
+
+/// Ranking strategy for Hadrian-side tool search over a deferred MCP
+/// catalog. `Hybrid` fuses semantic + lexical relevance (RRF); `Semantic`
+/// is embedding cosine only; `Lexical` is token/substring scoring with no
+/// embedding dependency.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum ToolSearchRankerKind {
+    Hybrid,
+    Semantic,
+    Lexical,
+}
+
+/// `tool_search` tool — OpenAI's `ToolSearchToolParam`. Configures
+/// discovery of deferred tools (`defer_loading: true`). Under
+/// `hadrian_hosted` a caller need not supply this: Hadrian synthesizes
+/// its own search tool whenever a deferred MCP server is present. A
+/// caller may still include the entry to set the Hadrian-extension
+/// `ranker`; Hadrian reads that override and does not forward the entry
+/// to the model.
 #[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct FileSearchTool {
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+pub struct ToolSearchTool {
     #[serde(rename = "type")]
-    pub type_: FileSearchToolType,
-    /// Vector store IDs to search across.
-    pub vector_store_ids: Vec<String>,
-    /// Maximum number of results to return.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub max_num_results: Option<usize>,
-    /// Ranking options for controlling result relevance.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub ranking_options: Option<FileSearchRankingOptions>,
-    /// Metadata filters to apply to the search.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub filters: Option<FileSearchFilter>,
-    /// **Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub cache_control: Option<CacheControl>,
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
+    pub type_: ToolSearchToolType,
+    /// Whether the search executes server-side (hosted) or client-side
+    /// (BYOT). Hadrian only supports server-side execution.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<String>))]
+    pub execution: Option<ToolSearchExecution>,
+    /// Description shown to the model for a client-executed search tool.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    /// Parameter schema for a client-executed search tool. Opaque.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
+    pub parameters: Option<serde_json::Value>,
+    /// **Hadrian Extension:** per-request override of the ranking
+    /// strategy for Hadrian-side tool search. Takes precedence over the
+    /// `[features.mcp.tool_search].ranker` deployment default. Requesting
+    /// `semantic` on a deployment without an embedding provider returns
+    /// HTTP 400 (`tool_search_ranker_unavailable`).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<String>))]
+    pub ranker: Option<ToolSearchRankerKind>,
 }
 
-impl FileSearchTool {
-    /// Check if this is a file_search tool.
-    pub fn is_file_search(&self) -> bool {
-        matches!(self.type_, FileSearchToolType::FileSearch)
-    }
+#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum FunctionToolType {
+    #[default]
+    Function,
+}
+
+/// Custom function tool. **Schema-only**: at the wire level the gateway
+/// keeps `Function` as an opaque `serde_json::Value` so existing
+/// rewrite pipelines (web_search → function, shell → function, MCP →
+/// per-tool function) can construct/inspect it via JSON without
+/// touching a typed struct. This struct exists purely to give the
+/// OpenAPI spec a typed shape for the function-tool variant.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+pub struct FunctionTool {
+    #[serde(rename = "type", default)]
+    #[cfg_attr(feature = "utoipa", schema(rename = "type"))]
+    pub type_: FunctionToolType,
+    /// Function name. Must be `[A-Za-z0-9_-]{1,64}`.
+    pub name: String,
+    /// Human-readable description surfaced to the model.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    /// JSON Schema describing the function's parameters. Forwarded
+    /// verbatim to the provider; the gateway treats it as opaque.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Option<Object>))]
+    pub parameters: Option<serde_json::Value>,
+    /// When true, the model is constrained to emit arguments that
+    /// strictly conform to `parameters`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub strict: Option<bool>,
+    /// Delay loading the function definition until the model discovers it
+    /// via tool search. On a caller-supplied function tool this is
+    /// forwarded to the provider and treated as opaque. On the per-tool
+    /// function tools the MCP rewrite synthesizes it is only set on the
+    /// native-passthrough path (`McpTool::defer_loading_passthrough` on an
+    /// OpenAI/Azure upstream); the default `hadrian_hosted` path defers via
+    /// Hadrian-side tool search instead and does not set this flag.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub defer_loading: Option<bool>,
+    /// Extra fields the gateway forwards verbatim (e.g. MCP `annotations`
+    /// on rewritten function tools). Not part of OpenAI's documented
+    /// shape; preserved here so internal rewrite pipelines can attach
+    /// provider-specific metadata without losing it through round-trips.
+    #[serde(flatten)]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Object))]
+    pub extras: std::collections::HashMap<String, serde_json::Value>,
 }
 
-/// Tool definition - can be a function tool, web search tool, or file search tool
+/// Tool definition - one of the supported tool variants. The schema
+/// emits a `oneOf` over the variants; each variant constrains its
+/// `type` field to a single literal, so consumers (and the OpenAPI
+/// conformance script) can match variants by `type`. The `Function`
+/// variant stays as an opaque `serde_json::Value` at the data level
+/// so existing rewrite pipelines (web_search → function, shell →
+/// function, MCP → per-tool function) keep constructing it via JSON;
+/// the schema reports it as a [`FunctionTool`] for documentation.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(untagged)]
 pub enum ResponsesToolDefinition {
     FileSearch(FileSearchTool), // Must be before Function to match type field first
@@ -970,7 +2168,20 @@ pub enum ResponsesToolDefinition {
     WebSearchPreview20250311(WebSearchPreview20250311Tool),
     WebSearch(WebSearchTool),
     WebSearch20250826(WebSearch20250826Tool),
-    Function(serde_json::Value), // Must be last - matches any JSON object
+    Shell(ShellTool),
+    Mcp(McpTool),
+    ToolSearch(ToolSearchTool), // Must be before Function to match type field first
+    Function(FunctionTool),
+}
+
+impl FunctionTool {
+    /// Parse a JSON object into `FunctionTool`. Rejects on schema
+    /// mismatch — used by the various rewrite pipelines (web_search,
+    /// shell, file_search, mcp) that build function tools as JSON
+    /// before wrapping in the enum variant.
+    pub fn from_json(value: serde_json::Value) -> Result<Self, serde_json::Error> {
+        serde_json::from_value(value)
+    }
 }
 
 impl ResponsesToolDefinition {
@@ -998,6 +2209,45 @@ impl ResponsesToolDefinition {
         )
     }
 
+    /// Returns true if this is a shell tool.
+    pub fn is_shell(&self) -> bool {
+        matches!(self, ResponsesToolDefinition::Shell(_))
+    }
+
+    /// Returns the shell tool definition if this is a shell tool.
+    pub fn as_shell(&self) -> Option<&ShellTool> {
+        match self {
+            ResponsesToolDefinition::Shell(tool) => Some(tool),
+            _ => None,
+        }
+    }
+
+    /// Returns true if this is an MCP tool.
+    pub fn is_mcp(&self) -> bool {
+        matches!(self, ResponsesToolDefinition::Mcp(_))
+    }
+
+    /// Returns the MCP tool definition if this is an MCP tool.
+    pub fn as_mcp(&self) -> Option<&McpTool> {
+        match self {
+            ResponsesToolDefinition::Mcp(tool) => Some(tool),
+            _ => None,
+        }
+    }
+
+    /// Returns true if this is a tool_search tool.
+    pub fn is_tool_search(&self) -> bool {
+        matches!(self, ResponsesToolDefinition::ToolSearch(_))
+    }
+
+    /// Returns the tool_search tool definition if this is one.
+    pub fn as_tool_search(&self) -> Option<&ToolSearchTool> {
+        match self {
+            ResponsesToolDefinition::ToolSearch(tool) => Some(tool),
+            _ => None,
+        }
+    }
+
     /// Extracts `search_context_size` from any web_search tool variant.
     pub fn web_search_context_size(&self) -> Option<ResponsesSearchContextSize> {
         match self {
@@ -1045,12 +2295,51 @@ pub struct ResponsesWebSearchToolChoice {
     pub type_: WebSearchToolChoiceType,
 }
 
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ShellToolChoiceType {
+    Shell,
+}
+
+/// Force the model to call the shell tool. Spec name:
+/// `ToolChoiceShell` — `{"type": "shell"}`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ResponsesShellToolChoice {
+    #[serde(rename = "type")]
+    pub type_: ShellToolChoiceType,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum McpToolChoiceType {
+    Mcp,
+}
+
+/// Force the model to call a specific MCP tool. Mirrors OpenAI's
+/// `{"type": "mcp", "server_label": "...", "name": "..."}`. Under
+/// `hadrian_hosted` mode the rewrite turns this into a function-tool
+/// choice (`{"type": "function", "name": "mcp_<label>__<name>"}`)
+/// before the request reaches the provider; under passthrough this
+/// is forwarded verbatim.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ResponsesMcpToolChoice {
+    #[serde(rename = "type")]
+    pub type_: McpToolChoiceType,
+    pub server_label: String,
+    /// Tool name as advertised by the MCP server. Omit to mean "any
+    /// tool from this server" — matches OpenAI's documented shape.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum ResponsesToolChoice {
     String(ResponsesToolChoiceDefault),
-    Named(ResponsesNamedToolChoice),
     WebSearch(ResponsesWebSearchToolChoice),
+    Shell(ResponsesShellToolChoice),
+    Mcp(ResponsesMcpToolChoice),
+    Named(ResponsesNamedToolChoice),
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -1240,7 +2529,6 @@ pub struct CreateResponsesPayload {
 
     /// Available tools
     #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[cfg_attr(feature = "utoipa", schema(value_type = Vec<Object>))]
     pub tools: Option<Vec<ResponsesToolDefinition>>,
 
     /// Tool choice configuration
@@ -1366,6 +2654,113 @@ pub struct CreateResponsesPayload {
     /// Merged with API key requirements (most restrictive wins).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub sovereignty_requirements: Option<crate::config::SovereigntyRequirements>,
+
+    /// **Hadrian Extension:** Skills to mount into the shell-tool
+    /// session. Hadrian treats skills as a top-level request field
+    /// rather than threading them through the OpenAI shell-tool
+    /// `environment` block, so they're accepted on every responses
+    /// request regardless of whether the upstream provider has its own
+    /// skills surface.
+    ///
+    /// Mirrors OpenAI's typed shape — each entry is either a reference
+    /// to a stored skill or an inline bundle:
+    ///
+    /// ```json
+    /// [
+    ///   {"type": "skill_reference", "skill_id": "<uuid>", "version": "latest"},
+    ///   {"type": "inline", "name": "extract-csv", "description": "...",
+    ///    "source": {"type": "base64", "media_type": "text/markdown", "data": "..."}}
+    /// ]
+    /// ```
+    ///
+    /// For `skill_reference`, `skill_id` is a Hadrian skill UUID
+    /// owned by the caller's org. `version` is optional; only
+    /// `"latest"` (the default) is supported today — pinned versions
+    /// reject with 400 until version-pinning lands.
+    ///
+    /// For `inline`, the decoded `source.data` is mounted as an
+    /// ephemeral skill bundle: `text/markdown` is treated as the
+    /// `SKILL.md` content; other media types are rejected today.
+    ///
+    /// Each resolved skill's `SKILL.md` is prepended to `instructions`
+    /// so the model knows the skill is available; all skill files are
+    /// materialized under `/skills/<skill_id>/` inside the sandbox.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Vec<Object>))]
+    pub skills: Option<Vec<RequestSkill>>,
+
+    /// Context management directives. Forwarded verbatim to providers
+    /// that support server-side compaction (OpenAI, Azure OpenAI); for
+    /// others the field is ignored at the adapter layer. See OpenAI's
+    /// compaction guide for the schema; the canonical entry is
+    /// `{"type": "compaction", "compact_threshold": <tokens>}`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Vec<Object>))]
+    pub context_management: Option<Vec<ContextManagementItem>>,
+}
+
+/// Entry in `CreateResponsesPayload::context_management`.
+///
+/// Mirrors the OpenAI Responses API directive — we surface the
+/// `compaction` variant explicitly so callers get type-checked help
+/// when wiring it up. Unknown variants are accepted via the `Other`
+/// catch-all and forwarded to the upstream provider verbatim; we
+/// prefer that over `deny_unknown` so OpenAI's spec can grow new
+/// types without rejecting requests at the gateway.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ContextManagementItem {
+    /// Server-side compaction. When the rendered token count crosses
+    /// `compact_threshold`, the provider emits a compaction item in
+    /// the same response stream and prunes context before continuing
+    /// inference.
+    ///
+    /// For non-OpenAI providers Hadrian runs a **gateway-side**
+    /// compactor before dispatch. The Hadrian-extension `strategy`
+    /// and `prompt` fields let the caller pick the algorithm and
+    /// (when strategy is `llm`) override the default summarisation
+    /// prompt.
+    Compaction {
+        /// Token count that triggers a compaction pass. Provider
+        /// validates the range.
+        #[serde(
+            skip_serializing_if = "Option::is_none",
+            serialize_with = "serialize_as_integer"
+        )]
+        compact_threshold: Option<f64>,
+        /// **Hadrian Extension:** which compactor to run when behind a
+        /// provider without native server-side compaction (Anthropic,
+        /// Bedrock, Vertex). Omitting the field uses the operator
+        /// default from `[features.responses.compaction].default_strategy`.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        strategy: Option<CompactionStrategy>,
+        /// **Hadrian Extension:** override prompt for `strategy = llm`.
+        /// Empty / missing falls back to the operator default. Ignored
+        /// when strategy is `truncate` or the request is routed to a
+        /// provider with native compaction (forwarded verbatim).
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        prompt: Option<String>,
+    },
+    /// **Hadrian Extension:** Forward-compatibility catch-all for
+    /// `type` values Hadrian doesn't know about. The raw value is
+    /// preserved and forwarded to the upstream provider unchanged.
+    #[serde(other)]
+    Other,
+}
+
+/// **Hadrian Extension:** compactor strategy for non-OpenAI providers.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionStrategy {
+    /// Summarise older items via a single follow-up call to the
+    /// active provider; replace them with a `compaction` input item
+    /// carrying the summary. Higher quality, costs one extra inference.
+    Llm,
+    /// Drop oldest non-system items until under `compact_threshold`.
+    /// Deterministic and free; preserves no narrative.
+    Truncate,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -1413,6 +2808,47 @@ pub struct ResponsesUsage {
     pub cost_details: Option<ResponsesUsageCostDetails>,
 }
 
+impl ResponsesUsage {
+    /// Fold `other` into `self`, summing one server-tool loop turn's usage
+    /// into the running total. Token counts and cost components add; `cost`
+    /// and `cost_details.upstream_inference_cost` add when both present and
+    /// otherwise take the present value; `is_byok` is sticky-true (once any
+    /// turn was BYOK the whole response is marked BYOK, since the wire shape
+    /// has no per-turn breakdown).
+    pub fn accumulate(&mut self, other: &ResponsesUsage) {
+        self.input_tokens += other.input_tokens;
+        self.output_tokens += other.output_tokens;
+        self.total_tokens += other.total_tokens;
+        self.input_tokens_details.cached_tokens += other.input_tokens_details.cached_tokens;
+        self.output_tokens_details.reasoning_tokens += other.output_tokens_details.reasoning_tokens;
+        match (self.cost.as_mut(), other.cost) {
+            (Some(a), Some(b)) => *a += b,
+            (None, Some(b)) => self.cost = Some(b),
+            _ => {}
+        }
+        if other.is_byok == Some(true) {
+            self.is_byok = Some(true);
+        }
+        if let Some(add_details) = &other.cost_details {
+            let target = self.cost_details.get_or_insert(ResponsesUsageCostDetails {
+                upstream_inference_cost: None,
+                upstream_inference_input_cost: 0.0,
+                upstream_inference_output_cost: 0.0,
+            });
+            target.upstream_inference_input_cost += add_details.upstream_inference_input_cost;
+            target.upstream_inference_output_cost += add_details.upstream_inference_output_cost;
+            match (
+                target.upstream_inference_cost.as_mut(),
+                add_details.upstream_inference_cost,
+            ) {
+                (Some(a), Some(b)) => *a += b,
+                (None, Some(b)) => target.upstream_inference_cost = Some(b),
+                _ => {}
+            }
+        }
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ResponsesReasoningConfigOutput {
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -1427,6 +2863,57 @@ pub enum ResponseType {
     Response,
 }
 
+/// Request body for `POST /v1/responses/compact`.
+///
+/// Mirrors OpenAI's `CompactResponseMethodPublicBody`: `model` is
+/// required; everything else is optional. Hadrian-specific extensions
+/// (`models`, `stream`, `sovereignty_requirements`) ride alongside
+/// because the gateway still routes, streams, and enforces sovereignty
+/// for compaction requests just like the main `/responses` handler.
+#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+pub struct CompactRequest {
+    /// Model to compact with. Required by OpenAI; Hadrian also accepts
+    /// it as the routing key when the gateway picks an upstream
+    /// provider.
+    pub model: String,
+
+    /// Conversation history to compact. Accepts a plain string or the
+    /// typed item array used by `POST /responses`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Object))]
+    pub input: Option<ResponsesInput>,
+
+    /// Continue compacting from a previously persisted response. Spec:
+    /// `CompactResponseMethodPublicBody.previous_response_id`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub previous_response_id: Option<String>,
+
+    /// System instructions threaded into the compaction prompt.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub instructions: Option<String>,
+
+    /// OpenAI prompt-cache key passthrough.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_key: Option<String>,
+
+    /// **Hadrian Extension:** alternate model list for multi-model
+    /// routing. The first entry the gateway resolves successfully wins.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub models: Option<Vec<String>>,
+
+    /// **Hadrian Extension:** stream the compacted response as SSE.
+    /// Forwarded verbatim to the upstream provider when supported.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub stream: bool,
+
+    /// **Hadrian Extension:** per-request data-sovereignty requirements.
+    /// Merged with API-key-level requirements; the most restrictive
+    /// wins.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sovereignty_requirements: Option<crate::config::SovereigntyRequirements>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CreateResponsesResponse {
     pub id: String,
@@ -1685,3 +3172,474 @@ impl CreateResponsesPayload {
         m
     }
 }
+
+#[cfg(test)]
+mod context_management_tests {
+    use super::*;
+
+    #[test]
+    fn compaction_round_trip_matches_openai_spec() {
+        let raw = serde_json::json!([{"type": "compaction", "compact_threshold": 200000}]);
+        let items: Vec<ContextManagementItem> = serde_json::from_value(raw.clone()).unwrap();
+        assert_eq!(items.len(), 1);
+        match &items[0] {
+            ContextManagementItem::Compaction {
+                compact_threshold,
+                strategy,
+                prompt,
+            } => {
+                assert_eq!(compact_threshold.unwrap() as i64, 200000);
+                assert!(strategy.is_none());
+                assert!(prompt.is_none());
+            }
+            ContextManagementItem::Other => {
+                panic!("expected compaction variant, got Other");
+            }
+        }
+        // Re-serialize and confirm the threshold is emitted as an
+        // integer (matches OpenAI's wire format, not float) and the
+        // Hadrian-extension fields are omitted when absent.
+        let round = serde_json::to_value(&items).unwrap();
+        assert_eq!(round, raw);
+    }
+
+    #[test]
+    fn compaction_accepts_hadrian_extension_fields() {
+        let raw = serde_json::json!([{
+            "type": "compaction",
+            "compact_threshold": 8000,
+            "strategy": "llm",
+            "prompt": "Summarize the conversation so far in <= 200 words."
+        }]);
+        let items: Vec<ContextManagementItem> = serde_json::from_value(raw).unwrap();
+        match &items[0] {
+            ContextManagementItem::Compaction {
+                compact_threshold,
+                strategy,
+                prompt,
+            } => {
+                assert_eq!(compact_threshold.unwrap() as i64, 8000);
+                assert_eq!(*strategy, Some(CompactionStrategy::Llm));
+                assert!(prompt.as_deref().unwrap().starts_with("Summarize"));
+            }
+            ContextManagementItem::Other => panic!("expected compaction"),
+        }
+    }
+
+    #[test]
+    fn unknown_context_management_variant_is_accepted() {
+        // Forward-compatibility: unknown `type` values deserialize into
+        // the catch-all `Other` variant rather than failing the whole
+        // request, so OpenAI can add new context-management directives
+        // without breaking Hadrian.
+        let raw = serde_json::json!([{"type": "summarize", "compact_threshold": 1000}]);
+        let parsed: Vec<ContextManagementItem> =
+            serde_json::from_value(raw).expect("unknown variants should deserialize to Other");
+        assert!(matches!(parsed[0], ContextManagementItem::Other));
+    }
+}
+
+#[cfg(test)]
+mod usage_tests {
+    use super::*;
+
+    fn usage(input: i64, output: i64, cost: Option<f64>) -> ResponsesUsage {
+        ResponsesUsage {
+            input_tokens: input,
+            input_tokens_details: ResponsesUsageInputTokensDetails { cached_tokens: 1 },
+            output_tokens: output,
+            output_tokens_details: ResponsesUsageOutputTokensDetails {
+                reasoning_tokens: 2,
+            },
+            total_tokens: input + output,
+            cost,
+            is_byok: None,
+            cost_details: None,
+        }
+    }
+
+    #[test]
+    fn accumulate_sums_tokens_and_cost() {
+        let mut acc = usage(100, 50, Some(0.001));
+        acc.accumulate(&usage(200, 30, Some(0.002)));
+        assert_eq!(acc.input_tokens, 300);
+        assert_eq!(acc.output_tokens, 80);
+        assert_eq!(acc.total_tokens, 380);
+        assert_eq!(acc.input_tokens_details.cached_tokens, 2);
+        assert_eq!(acc.output_tokens_details.reasoning_tokens, 4);
+        assert!((acc.cost.unwrap() - 0.003).abs() < 1e-9);
+    }
+
+    #[test]
+    fn accumulate_takes_present_cost_and_is_sticky_byok() {
+        let mut acc = usage(1, 1, None);
+        let mut add = usage(1, 1, Some(0.5));
+        add.is_byok = Some(true);
+        acc.accumulate(&add);
+        assert_eq!(acc.cost, Some(0.5));
+        assert_eq!(acc.is_byok, Some(true));
+        // A later non-BYOK turn does not clear the sticky flag.
+        acc.accumulate(&usage(1, 1, None));
+        assert_eq!(acc.is_byok, Some(true));
+    }
+
+    #[test]
+    fn accumulate_merges_cost_details_componentwise() {
+        let mut acc = usage(1, 1, None);
+        let mut add = usage(1, 1, None);
+        add.cost_details = Some(ResponsesUsageCostDetails {
+            upstream_inference_cost: Some(0.9),
+            upstream_inference_input_cost: 0.4,
+            upstream_inference_output_cost: 0.5,
+        });
+        acc.accumulate(&add);
+        acc.accumulate(&add);
+        let d = acc.cost_details.unwrap();
+        assert!((d.upstream_inference_input_cost - 0.8).abs() < 1e-9);
+        assert!((d.upstream_inference_output_cost - 1.0).abs() < 1e-9);
+        assert!((d.upstream_inference_cost.unwrap() - 1.8).abs() < 1e-9);
+    }
+}
+
+#[cfg(test)]
+mod mcp_tool_tests {
+    use super::*;
+
+    #[test]
+    fn mcp_tool_with_server_url_round_trip() {
+        let raw = serde_json::json!({
+            "type": "mcp",
+            "server_label": "atlassian",
+            "server_url": "https://mcp.atlassian.com/v1/mcp",
+            "authorization": "Bearer ya29.example",
+            "require_approval": "always",
+            "allowed_tools": ["jira_search", "confluence_get"]
+        });
+        let tool: McpTool = serde_json::from_value(raw.clone()).expect("parses");
+        assert_eq!(tool.server_label, "atlassian");
+        assert_eq!(
+            tool.server_url.as_deref(),
+            Some("https://mcp.atlassian.com/v1/mcp")
+        );
+        assert!(tool.connector_id.is_none());
+        assert_eq!(tool.authorization.as_deref(), Some("Bearer ya29.example"));
+        assert!(matches!(
+            tool.require_approval,
+            Some(McpRequireApproval::Mode(McpApprovalMode::Always))
+        ));
+        assert!(matches!(
+            tool.allowed_tools,
+            Some(McpAllowedTools::List(ref v)) if v == &["jira_search".to_string(), "confluence_get".to_string()]
+        ));
+        assert!(tool.has_exactly_one_target());
+
+        // Round-trip back to JSON.
+        let reserialized = serde_json::to_value(&tool).expect("serializes");
+        assert_eq!(reserialized["type"], "mcp");
+        assert_eq!(
+            reserialized["server_url"],
+            "https://mcp.atlassian.com/v1/mcp"
+        );
+    }
+
+    #[test]
+    fn mcp_tool_with_connector_id() {
+        let raw = serde_json::json!({
+            "type": "mcp",
+            "server_label": "gcal",
+            "connector_id": "connector_googlecalendar",
+            "authorization": "Bearer xyz"
+        });
+        let tool: McpTool = serde_json::from_value(raw).expect("parses");
+        assert!(tool.server_url.is_none());
+        assert_eq!(
+            tool.connector_id.as_deref(),
+            Some("connector_googlecalendar")
+        );
+        assert!(tool.has_exactly_one_target());
+    }
+
+    #[test]
+    fn mcp_tool_rejects_no_target() {
+        // No server_url, no connector_id — accepts at deserialize time, fails
+        // the explicit `has_exactly_one_target()` check the preprocess uses.
+        let raw = serde_json::json!({"type": "mcp", "server_label": "broken"});
+        let tool: McpTool = serde_json::from_value(raw).expect("deserializes");
+        assert!(!tool.has_exactly_one_target());
+    }
+
+    #[test]
+    fn mcp_tool_rejects_both_targets() {
+        let raw = serde_json::json!({
+            "type": "mcp",
+            "server_label": "both",
+            "server_url": "https://x",
+            "connector_id": "connector_googlecalendar"
+        });
+        let tool: McpTool = serde_json::from_value(raw).expect("deserializes");
+        assert!(!tool.has_exactly_one_target());
+    }
+
+    #[test]
+    fn require_approval_parses_string_and_object() {
+        let s: McpRequireApproval = serde_json::from_value(serde_json::json!("never")).unwrap();
+        assert!(matches!(
+            s,
+            McpRequireApproval::Mode(McpApprovalMode::Never)
+        ));
+
+        let o: McpRequireApproval = serde_json::from_value(serde_json::json!({
+            "always": {"tool_names": ["a", "b"]},
+            "never": {"read_only": true}
+        }))
+        .unwrap();
+        match o {
+            McpRequireApproval::Filter(f) => {
+                let always = f.always.expect("always filter set");
+                assert_eq!(
+                    always.tool_names,
+                    Some(vec!["a".to_string(), "b".to_string()])
+                );
+                let never = f.never.expect("never filter set");
+                assert_eq!(never.read_only, Some(true));
+            }
+            other => panic!("expected Filter variant, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn allowed_tools_parses_list_and_object() {
+        let l: McpAllowedTools = serde_json::from_value(serde_json::json!(["x", "y"])).unwrap();
+        assert!(matches!(l, McpAllowedTools::List(ref v) if v.len() == 2));
+
+        let o: McpAllowedTools =
+            serde_json::from_value(serde_json::json!({"tool_names": ["x"], "read_only": true}))
+                .unwrap();
+        match o {
+            McpAllowedTools::Filter(f) => {
+                assert_eq!(f.tool_names, Some(vec!["x".to_string()]));
+                assert_eq!(f.read_only, Some(true));
+            }
+            other => panic!("expected Filter variant, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn responses_tool_definition_picks_mcp_variant() {
+        let raw = serde_json::json!({
+            "type": "mcp",
+            "server_label": "test",
+            "server_url": "https://x"
+        });
+        let def: ResponsesToolDefinition = serde_json::from_value(raw).expect("parses");
+        assert!(def.is_mcp());
+        assert!(!def.is_shell());
+        assert!(!def.is_function_tool_with_value());
+    }
+
+    #[test]
+    fn responses_tool_definition_picks_tool_search_variant() {
+        let raw = serde_json::json!({
+            "type": "tool_search",
+            "execution": "server",
+            "ranker": "semantic"
+        });
+        let def: ResponsesToolDefinition = serde_json::from_value(raw).expect("parses");
+        assert!(def.is_tool_search());
+        let t = def.as_tool_search().expect("tool_search");
+        assert_eq!(t.execution, Some(ToolSearchExecution::Server));
+        assert_eq!(t.ranker, Some(ToolSearchRankerKind::Semantic));
+    }
+
+    #[test]
+    fn tool_search_tool_minimal_round_trip() {
+        // Only `type` is required per OpenAI's ToolSearchToolParam.
+        let raw = serde_json::json!({ "type": "tool_search" });
+        let def: ResponsesToolDefinition = serde_json::from_value(raw).expect("parses");
+        let t = def.as_tool_search().expect("tool_search");
+        assert!(t.execution.is_none());
+        assert!(t.ranker.is_none());
+        // Round-trips without injecting null fields.
+        let back = serde_json::to_value(&def).expect("serializes");
+        assert_eq!(back, serde_json::json!({ "type": "tool_search" }));
+    }
+
+    #[test]
+    fn tool_search_call_and_output_items_round_trip() {
+        let call_raw = serde_json::json!({
+            "type": "tool_search_call",
+            "id": "ts_1",
+            "call_id": "call_abc",
+            "execution": "server",
+            "arguments": {"query": "search jira"},
+            "status": "completed"
+        });
+        let call: ToolSearchCallItem = serde_json::from_value(call_raw.clone()).expect("parses");
+        assert_eq!(call.id, "ts_1");
+        assert_eq!(call.call_id.as_deref(), Some("call_abc"));
+        assert_eq!(call.execution, ToolSearchExecution::Server);
+        assert_eq!(serde_json::to_value(&call).unwrap(), call_raw);
+
+        let out_raw = serde_json::json!({
+            "type": "tool_search_output",
+            "id": "tso_1",
+            "call_id": "call_abc",
+            "execution": "server",
+            "tools": [{"type": "function", "name": "mcp_atlassian__jira_search"}],
+            "status": "completed"
+        });
+        let out: ToolSearchOutputItem = serde_json::from_value(out_raw.clone()).expect("parses");
+        assert_eq!(out.tools.len(), 1);
+        assert_eq!(serde_json::to_value(&out).unwrap(), out_raw);
+
+        // Both round-trip through the untagged output-item enum.
+        let item: ResponsesOutputItem = serde_json::from_value(call_raw).expect("parses");
+        assert!(matches!(item, ResponsesOutputItem::ToolSearchCall(_)));
+        let item: ResponsesOutputItem = serde_json::from_value(out_raw).expect("parses");
+        assert!(matches!(item, ResponsesOutputItem::ToolSearchOutput(_)));
+    }
+
+    #[test]
+    fn mcp_tool_defer_loading_passthrough_extension_parses() {
+        let raw = serde_json::json!({
+            "type": "mcp",
+            "server_label": "atlassian",
+            "server_url": "https://x",
+            "defer_loading": true,
+            "defer_loading_passthrough": true
+        });
+        let def: ResponsesToolDefinition = serde_json::from_value(raw).expect("parses");
+        let mcp = def.as_mcp().expect("mcp");
+        assert_eq!(mcp.defer_loading, Some(true));
+        assert_eq!(mcp.defer_loading_passthrough, Some(true));
+    }
+
+    #[test]
+    fn mcp_list_tools_item_round_trip() {
+        let raw = serde_json::json!({
+            "type": "mcp_list_tools",
+            "id": "mcptl_1",
+            "server_label": "atlassian",
+            "tools": [{
+                "name": "jira_search",
+                "description": "Search Jira issues",
+                "input_schema": {"type": "object"}
+            }]
+        });
+        let item: McpListToolsItem = serde_json::from_value(raw).expect("parses");
+        assert_eq!(item.id, "mcptl_1");
+        assert_eq!(item.tools.len(), 1);
+        assert_eq!(item.tools[0].name, "jira_search");
+        assert!(item.error.is_none());
+    }
+
+    #[test]
+    fn mcp_list_tools_item_carries_error() {
+        let raw = serde_json::json!({
+            "type": "mcp_list_tools",
+            "id": "mcptl_err",
+            "server_label": "atlassian",
+            "tools": [],
+            "error": "503 from upstream"
+        });
+        let item: McpListToolsItem = serde_json::from_value(raw).expect("parses");
+        assert_eq!(item.error.as_deref(), Some("503 from upstream"));
+        assert!(item.tools.is_empty());
+    }
+
+    #[test]
+    fn mcp_call_inlines_output_and_error() {
+        let call_raw = serde_json::json!({
+            "type": "mcp_call",
+            "id": "mcpc_1",
+            "server_label": "atlassian",
+            "name": "jira_search",
+            "arguments": "{\"query\": \"bugs\"}",
+            "status": "completed",
+            "output": "{\"issues\": []}",
+            "approval_request_id": "mcpr_1"
+        });
+        let call: McpCallItem = serde_json::from_value(call_raw).expect("parses");
+        assert!(matches!(call.status, McpItemStatus::Completed));
+        assert_eq!(call.output.as_deref(), Some("{\"issues\": []}"));
+        assert!(call.error.is_none());
+        assert_eq!(call.approval_request_id.as_deref(), Some("mcpr_1"));
+
+        let failed_raw = serde_json::json!({
+            "type": "mcp_call",
+            "id": "mcpc_2",
+            "server_label": "atlassian",
+            "name": "jira_create",
+            "arguments": "{}",
+            "status": "failed",
+            "error": "timeout"
+        });
+        let failed: McpCallItem = serde_json::from_value(failed_raw).expect("parses");
+        assert!(matches!(failed.status, McpItemStatus::Failed));
+        assert_eq!(failed.error.as_deref(), Some("timeout"));
+        assert!(failed.output.is_none());
+    }
+
+    #[test]
+    fn mcp_item_status_round_trips_calling() {
+        // `calling` is part of the spec enum; make sure the deserializer
+        // accepts it round-trip.
+        let raw = serde_json::json!({
+            "type": "mcp_call",
+            "id": "mcpc_x",
+            "server_label": "x",
+            "name": "y",
+            "arguments": "{}",
+            "status": "calling"
+        });
+        let call: McpCallItem = serde_json::from_value(raw).expect("parses");
+        assert!(matches!(call.status, McpItemStatus::Calling));
+        let v = serde_json::to_value(&call).expect("serializes");
+        assert_eq!(v["status"], "calling");
+    }
+
+    #[test]
+    fn mcp_approval_request_and_response_round_trip() {
+        let req_raw = serde_json::json!({
+            "type": "mcp_approval_request",
+            "id": "mcpr_1",
+            "server_label": "atlassian",
+            "name": "jira_create",
+            "arguments": "{\"summary\":\"bug\"}"
+        });
+        let req: McpApprovalRequestItem = serde_json::from_value(req_raw).expect("parses");
+        assert_eq!(req.id, "mcpr_1");
+
+        let resp_raw = serde_json::json!({
+            "type": "mcp_approval_response",
+            "approval_request_id": "mcpr_1",
+            "approve": false,
+            "reason": "policy violation"
+        });
+        let resp: McpApprovalResponseItem = serde_json::from_value(resp_raw).expect("parses");
+        assert_eq!(resp.approval_request_id, "mcpr_1");
+        assert!(!resp.approve);
+        assert_eq!(resp.reason.as_deref(), Some("policy violation"));
+    }
+
+    #[test]
+    fn output_item_picks_mcp_variants() {
+        let raw = serde_json::json!({
+            "type": "mcp_call",
+            "id": "mcpc_1",
+            "server_label": "x",
+            "name": "y",
+            "arguments": "{}",
+            "status": "in_progress"
+        });
+        let item: ResponsesOutputItem = serde_json::from_value(raw).expect("parses as output item");
+        assert!(matches!(item, ResponsesOutputItem::McpCall(_)));
+    }
+}
+
+impl ResponsesToolDefinition {
+    #[cfg(test)]
+    fn is_function_tool_with_value(&self) -> bool {
+        matches!(self, ResponsesToolDefinition::Function(_))
+    }
+}
diff --git a/src/app.rs b/src/app.rs
index 4fe40c7..1112745 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -33,6 +33,8 @@ use crate::observability;
 #[cfg(feature = "utoipa")]
 use crate::openapi;
 #[cfg(feature = "server")]
+use crate::runtimes;
+#[cfg(feature = "server")]
 use crate::streaming;
 use crate::{
     auth, authz, cache, catalog, config, db, dlq, events, guardrails,
@@ -364,6 +366,46 @@ pub struct AppState {
     /// File search service for RAG (Retrieval Augmented Generation).
     /// Used by the file_search tool in the Responses API to search vector stores.
     pub file_search_service: Option<Arc<services::FileSearchService>>,
+    /// Shell tool runtime adapter. Constructed once at startup from
+    /// `[features.shell]` config. `None` when shell tool is disabled.
+    /// When the runtime advertises `passthrough_only`, the orchestrator
+    /// skips registering a ShellExecutor and the shell tool flows
+    /// through to the upstream provider unchanged.
+    #[cfg(feature = "server")]
+    pub shell_runtime: Option<Arc<dyn runtimes::ShellRuntime>>,
+    /// MCP-tool service. Holds the pooled MCP clients and tools-list
+    /// cache used by the `hadrian_hosted` mode. `None` when the `mcp`
+    /// cargo feature is off or `[features.mcp]` is not configured.
+    #[cfg(feature = "mcp")]
+    pub mcp_service: Option<services::mcp::McpService>,
+    /// Embedding service for Hadrian-side MCP tool search (semantic /
+    /// hybrid ranking). Resolved from `[features.mcp.tool_search.embedding]`
+    /// with a fallback to the file_search / semantic-cache embedding
+    /// config. `None` when no embedding provider resolves — tool search
+    /// then falls back to lexical ranking.
+    #[cfg(feature = "mcp")]
+    pub tool_search_embeddings: Option<Arc<cache::EmbeddingService>>,
+    /// Persisted Responses API store. Always present when a database
+    /// is configured; powers `GET/POST cancel/DELETE /v1/responses/{id}`
+    /// and the cancellation signal pipeline.
+    #[cfg(feature = "server")]
+    pub responses_store: Option<Arc<services::ResponsesStore>>,
+    /// Containers service. Present when a database is configured;
+    /// drives write-through persistence for the shell-tool
+    /// `/mnt/data` artifact pipeline and serves
+    /// `GET /v1/containers/*`.
+    #[cfg(feature = "server")]
+    pub containers_service: Option<Arc<services::containers::ContainersService>>,
+    /// In-memory registry of live container sessions, keyed by the
+    /// `cntr_…` id. Always present so cross-response container reuse
+    /// works even in DB-less deployments (it just stays empty there).
+    #[cfg(feature = "server")]
+    pub container_session_registry: Arc<services::container_session::ContainerSessionRegistry>,
+    /// Bounded-channel writer that batches `response_events` rows.
+    /// Constructed alongside `responses_store` so persistence and event
+    /// log share the same DB lifecycle.
+    #[cfg(feature = "server")]
+    pub response_event_buffer: Option<Arc<services::ResponseEventBuffer>>,
     /// Document processor for chunking and embedding files added to vector stores.
     /// Used by the Vector Store Files API to process uploaded files.
     #[cfg(any(
@@ -1039,6 +1081,154 @@ impl AppState {
         )
         .await;
 
+        // Initialize the persisted Responses API store when a database
+        // is available. Requests without a DB run stateless — shell
+        // tool retrieval/cancel/delete endpoints will 404.
+        #[cfg(feature = "server")]
+        let responses_store: Option<Arc<services::ResponsesStore>> = db.as_ref().map(|db| {
+            let mut store = services::ResponsesStore::new(
+                db.clone(),
+                std::time::Duration::from_secs(config.features.responses.retention_secs),
+            );
+            if let Some(ref hook) = config.features.responses.webhook {
+                let dispatcher = services::ResponsesWebhookDispatcher::spawn(
+                    hook.clone(),
+                    http_client.clone(),
+                    dlq.clone(),
+                );
+                store = store.with_webhook(dispatcher);
+                tracing::info!(url = %hook.url, "Responses webhook configured");
+            }
+            Arc::new(store)
+        });
+
+        // Event buffer writes batched response_events. Defaults: 100ms
+        // flush interval, batches of 64 events, channel of 1024.
+        #[cfg(feature = "server")]
+        let response_event_buffer: Option<Arc<services::ResponseEventBuffer>> =
+            db.as_ref().map(|db| {
+                Arc::new(services::ResponseEventBuffer::spawn(
+                    db.response_events(),
+                    64,
+                    std::time::Duration::from_millis(100),
+                    1024,
+                ))
+            });
+
+        // Containers service powers shell-tool `/mnt/data` artifact
+        // persistence and `/v1/containers/*`. Available whenever a DB
+        // is configured. Without it the live shell tool still works
+        // (the in-memory session capture path stays available), but
+        // the GET endpoints return 404 because no rows exist.
+        #[cfg(feature = "server")]
+        let containers_service: Option<Arc<services::containers::ContainersService>> =
+            match db.as_ref() {
+                Some(db) => {
+                    // Container artifacts get their own storage backend
+                    // (`[storage.container_files]`) so operators can offload
+                    // bulky `/mnt/data` outputs to filesystem / S3 while
+                    // keeping the Files API wherever they like.
+                    let container_file_storage =
+                        services::create_file_storage(&config.storage.container_files, db.clone())
+                            .await
+                            .map_err(|e| {
+                                format!("Failed to initialize container file storage: {}", e)
+                            })?;
+                    tracing::info!(
+                        backend = %container_file_storage.backend_name(),
+                        "Container file storage backend initialized"
+                    );
+                    Some(Arc::new(services::containers::ContainersService::new(
+                        db.clone(),
+                        container_file_storage,
+                    )))
+                }
+                None => None,
+            };
+
+        // Always construct a registry. In DB-less deployments it
+        // stays empty (sessions never get inserted), but wiring it in
+        // unconditionally keeps the rest of the pipeline's plumbing
+        // simple.
+        #[cfg(feature = "server")]
+        let container_session_registry: Arc<
+            services::container_session::ContainerSessionRegistry,
+        > = Arc::new(services::container_session::ContainerSessionRegistry::new());
+
+        // Initialize the shell tool runtime from [features.shell].
+        // Microsandbox / OpenSandbox / E2B adapters land in slice 1B; for
+        // now they return None and emit a clear startup error.
+        #[cfg(feature = "server")]
+        let shell_runtime: Option<Arc<dyn runtimes::ShellRuntime>> = match &config.features.shell {
+            config::ShellRuntimeConfig::None => None,
+            config::ShellRuntimeConfig::PassthroughOpenAI => {
+                tracing::info!("Shell tool runtime: passthrough_openai");
+                Some(Arc::new(
+                    runtimes::PassthroughRuntime::for_openai_container(),
+                ))
+            }
+            config::ShellRuntimeConfig::ClientPassthrough => {
+                tracing::info!(
+                    "Shell tool runtime: client_passthrough (API client fulfills shell calls)"
+                );
+                Some(Arc::new(runtimes::PassthroughRuntime::for_api_client()))
+            }
+            #[cfg(feature = "runtime-microsandbox")]
+            config::ShellRuntimeConfig::Microsandbox(cfg) => {
+                tracing::info!(
+                    image = %cfg.image,
+                    cpus = cfg.cpus,
+                    memory_mb = cfg.memory_mb,
+                    "Shell tool runtime: microsandbox"
+                );
+                Some(Arc::new(runtimes::MicrosandboxRuntime::new(cfg.clone())))
+            }
+            #[cfg(feature = "runtime-opensandbox")]
+            config::ShellRuntimeConfig::OpenSandbox(cfg) => {
+                tracing::info!(
+                    endpoint = %cfg.endpoint,
+                    "Shell tool runtime: opensandbox"
+                );
+                Some(Arc::new(runtimes::OpenSandboxRuntime::new(
+                    cfg.clone(),
+                    http_client.clone(),
+                )))
+            }
+        };
+
+        // MCP tool service. Built when `[features.mcp]` is configured;
+        // the executor + preprocess pick it up off AppState. The
+        // `hadrian_hosted` mode is the consumer; under
+        // `passthrough_openai` the service is constructed but unused.
+        #[cfg(feature = "mcp")]
+        let mcp_service: Option<services::mcp::McpService> = match &config.features.mcp {
+            Some(cfg) if cfg.enabled => {
+                tracing::info!(
+                    mode = ?cfg.mode,
+                    "MCP tool: enabled"
+                );
+                let approvals_repo = db.as_ref().map(|db| db.mcp_pending_approvals());
+                let url_validation_opts = crate::validation::UrlValidationOptions {
+                    allow_loopback: config.server.allow_loopback_urls,
+                    allow_private: config.server.allow_private_urls,
+                };
+                Some(services::mcp::McpService::with_approvals_repo(
+                    approvals_repo,
+                    url_validation_opts,
+                ))
+            }
+            _ => None,
+        };
+
+        // Resolve the embedding service for Hadrian-side MCP tool search.
+        #[cfg(feature = "mcp")]
+        let tool_search_embeddings = Self::init_tool_search_embeddings(
+            &config,
+            &circuit_breakers,
+            http_client.clone(),
+            file_search_service.as_ref(),
+        );
+
         // Initialize document processor for RAG file processing
         // This reuses the embedding service and vector store from file_search_service
         #[cfg(any(
@@ -1158,6 +1348,20 @@ impl AppState {
             output_guardrails,
             event_bus,
             file_search_service,
+            #[cfg(feature = "server")]
+            shell_runtime,
+            #[cfg(feature = "mcp")]
+            mcp_service,
+            #[cfg(feature = "mcp")]
+            tool_search_embeddings,
+            #[cfg(feature = "server")]
+            responses_store,
+            #[cfg(feature = "server")]
+            containers_service,
+            #[cfg(feature = "server")]
+            container_session_registry,
+            #[cfg(feature = "server")]
+            response_event_buffer,
             #[cfg(any(
                 feature = "document-extraction-basic",
                 feature = "document-extraction-full"
@@ -1446,6 +1650,88 @@ impl AppState {
     ///
     /// The embedding configuration is taken from the semantic caching config if available,
     /// since file search typically uses the same embedding model.
+    /// Resolve an embedding service for Hadrian-side MCP tool search.
+    ///
+    /// Only relevant under `hadrian_hosted`. Resolves the embedding config
+    /// with priority: `[features.mcp.tool_search.embedding]` →
+    /// `[features.file_search.embedding]` →
+    /// `[features.response_caching.semantic.embedding]`; failing that,
+    /// reuses the file_search embedding service if one was built. Returns
+    /// `None` when nothing resolves (tool search falls back to lexical
+    /// ranking). Logs loudly when the configured ranker is `semantic` but
+    /// no embeddings resolve.
+    #[cfg(feature = "mcp")]
+    fn init_tool_search_embeddings(
+        config: &config::GatewayConfig,
+        circuit_breakers: &providers::CircuitBreakerRegistry,
+        http_client: Client,
+        file_search_service: Option<&Arc<services::FileSearchService>>,
+    ) -> Option<Arc<cache::EmbeddingService>> {
+        let mcp_cfg = match &config.features.mcp {
+            Some(cfg) if cfg.enabled && cfg.is_hadrian_hosted() => cfg,
+            _ => return None,
+        };
+        let ts_cfg = &mcp_cfg.tool_search;
+
+        // Lexical ranking needs no embeddings.
+        if ts_cfg.ranker == crate::api_types::responses::ToolSearchRankerKind::Lexical {
+            return None;
+        }
+
+        let embedding_config = ts_cfg.embedding.as_ref().or_else(|| {
+            config
+                .features
+                .file_search
+                .as_ref()
+                .and_then(|fs| fs.embedding.as_ref())
+                .or_else(|| {
+                    config
+                        .features
+                        .response_caching
+                        .as_ref()
+                        .and_then(|rc| rc.semantic.as_ref())
+                        .map(|sc| &sc.embedding)
+                })
+        });
+
+        let resolved = embedding_config.and_then(|cfg| {
+            let provider_config = config.providers.get(&cfg.provider)?;
+            match cache::EmbeddingService::new(
+                cfg,
+                provider_config,
+                circuit_breakers,
+                http_client.clone(),
+            ) {
+                Ok(service) => Some(Arc::new(service)),
+                Err(e) => {
+                    tracing::error!(error = %e, "Failed to build embedding service for MCP tool search");
+                    None
+                }
+            }
+        });
+
+        // Last resort: reuse the file_search embedding service if present.
+        let resolved = resolved.or_else(|| file_search_service.map(|fs| fs.embedding_service()));
+
+        if resolved.is_none() {
+            // `hybrid` degrades to lexical; `semantic` was explicitly asked
+            // for and can't be honored — surface it loudly.
+            if ts_cfg.ranker == crate::api_types::responses::ToolSearchRankerKind::Semantic {
+                tracing::error!(
+                    "MCP tool search ranker is `semantic` but no embedding provider resolved; \
+                     configure [features.mcp.tool_search.embedding] (or file_search / semantic \
+                     cache embeddings). Falling back to lexical ranking."
+                );
+            } else {
+                tracing::info!(
+                    "MCP tool search: no embedding provider resolved; using lexical ranking"
+                );
+            }
+        }
+
+        resolved
+    }
+
     async fn init_file_search_service(
         config: &config::GatewayConfig,
         db: Option<&Arc<db::DbPool>>,
diff --git a/src/cache/embedding_service.rs b/src/cache/embedding_service.rs
index 5baa611..45721f4 100644
--- a/src/cache/embedding_service.rs
+++ b/src/cache/embedding_service.rs
@@ -273,6 +273,138 @@ impl EmbeddingService {
         }
     }
 
+    /// Generate embeddings for a batch of texts in a single request.
+    ///
+    /// Returns one vector per input, in the same order as `texts` (the
+    /// provider's `index` field is honored when present). Used by
+    /// Hadrian-side tool search to embed a deferred MCP catalog in one
+    /// round-trip. Returns an empty `Vec` for empty input without
+    /// contacting the provider.
+    pub async fn embed_batch(&self, texts: &[String]) -> Result<Vec<Vec<f64>>, EmbeddingError> {
+        if texts.is_empty() {
+            return Ok(Vec::new());
+        }
+
+        let embedding_payload = CreateEmbeddingPayload {
+            input: EmbeddingInput::TextArray(texts.to_vec()),
+            model: self.model.clone(),
+            encoding_format: None,
+            dimensions: Some(self.dimensions as i64),
+            user: None,
+            provider: None,
+            input_type: None,
+            sovereignty_requirements: None,
+        };
+
+        let start = Instant::now();
+        let response = self
+            .provider
+            .create_embedding(&self.http_client, embedding_payload)
+            .await;
+        let duration_secs = start.elapsed().as_secs_f64();
+
+        let status_label = |ok: bool| if ok { "success" } else { "error" };
+        let resp = match response {
+            Ok(resp) => resp,
+            Err(e) => {
+                record_embedding_generation(
+                    &self.provider_name,
+                    &self.model,
+                    status_label(false),
+                    duration_secs,
+                    None,
+                    texts.len() as u32,
+                );
+                return Err(e.into());
+            }
+        };
+
+        match self
+            .parse_embedding_batch_with_usage(resp, texts.len())
+            .await
+        {
+            Ok((embeddings, token_count)) => {
+                record_embedding_generation(
+                    &self.provider_name,
+                    &self.model,
+                    status_label(true),
+                    duration_secs,
+                    token_count,
+                    texts.len() as u32,
+                );
+                Ok(embeddings)
+            }
+            Err(e) => {
+                record_embedding_generation(
+                    &self.provider_name,
+                    &self.model,
+                    status_label(false),
+                    duration_secs,
+                    None,
+                    texts.len() as u32,
+                );
+                Err(e)
+            }
+        }
+    }
+
+    /// Parse a batch embedding response, returning vectors ordered by the
+    /// provider's `index` field (falling back to response order).
+    async fn parse_embedding_batch_with_usage(
+        &self,
+        response: axum::response::Response,
+        expected: usize,
+    ) -> Result<(Vec<Vec<f64>>, Option<u32>), EmbeddingError> {
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = axum::body::to_bytes(response.into_body(), 1024 * 1024)
+                .await
+                .unwrap_or_default();
+            let body_str = String::from_utf8_lossy(&body);
+            return Err(EmbeddingError::ParseError(format!(
+                "Provider returned error status {status}: {body_str}"
+            )));
+        }
+
+        let body = axum::body::to_bytes(response.into_body(), 50 * 1024 * 1024)
+            .await
+            .map_err(|e| {
+                EmbeddingError::ParseError(format!("Failed to read response body: {e}"))
+            })?;
+        let parsed: CreateEmbeddingResponse = serde_json::from_slice(&body)
+            .map_err(|e| EmbeddingError::ParseError(format!("Failed to parse response: {e}")))?;
+
+        let token_count = parsed.usage.as_ref().map(|u| u.total_tokens as u32);
+
+        if parsed.data.is_empty() {
+            return Err(EmbeddingError::EmptyResponse);
+        }
+
+        // Sort by `index` so the output order matches the input order even
+        // if the provider returns them out of order.
+        let mut data = parsed.data;
+        data.sort_by(|a, b| {
+            a.index
+                .unwrap_or(0.0)
+                .partial_cmp(&b.index.unwrap_or(0.0))
+                .unwrap_or(std::cmp::Ordering::Equal)
+        });
+
+        let embeddings: Vec<Vec<f64>> = data
+            .into_iter()
+            .map(|d| decode_embedding_vector(d.embedding))
+            .collect::<Result<_, _>>()?;
+
+        if embeddings.len() != expected {
+            return Err(EmbeddingError::ParseError(format!(
+                "expected {expected} embeddings, provider returned {}",
+                embeddings.len()
+            )));
+        }
+
+        Ok((embeddings, token_count))
+    }
+
     /// Convert a chat completion request to a normalized text representation.
     ///
     /// This creates a consistent text format for embedding that captures
@@ -354,32 +486,7 @@ impl EmbeddingService {
             .next()
             .ok_or(EmbeddingError::EmptyResponse)?;
 
-        let embedding = match embedding_data.embedding {
-            EmbeddingVector::Float(vec) => vec,
-            EmbeddingVector::Base64(b64) => {
-                // Decode base64 to f32 array, then convert to f64
-                let bytes =
-                    base64::Engine::decode(&base64::engine::general_purpose::STANDARD, &b64)
-                        .map_err(|e| {
-                            EmbeddingError::ParseError(format!("Invalid base64: {}", e))
-                        })?;
-
-                // Base64 encodes little-endian f32 values
-                if bytes.len() % 4 != 0 {
-                    return Err(EmbeddingError::ParseError(
-                        "Invalid base64 embedding length".to_string(),
-                    ));
-                }
-
-                bytes
-                    .chunks(4)
-                    .map(|chunk| {
-                        let arr: [u8; 4] = chunk.try_into().unwrap();
-                        f32::from_le_bytes(arr) as f64
-                    })
-                    .collect()
-            }
-        };
+        let embedding = decode_embedding_vector(embedding_data.embedding)?;
 
         Ok((embedding, token_count))
     }
@@ -400,6 +507,30 @@ impl EmbeddingService {
     }
 }
 
+/// Decode a provider embedding vector (float array or base64-packed
+/// little-endian f32) into `Vec<f64>`.
+fn decode_embedding_vector(vector: EmbeddingVector) -> Result<Vec<f64>, EmbeddingError> {
+    match vector {
+        EmbeddingVector::Float(vec) => Ok(vec),
+        EmbeddingVector::Base64(b64) => {
+            let bytes = base64::Engine::decode(&base64::engine::general_purpose::STANDARD, &b64)
+                .map_err(|e| EmbeddingError::ParseError(format!("Invalid base64: {e}")))?;
+            if bytes.len() % 4 != 0 {
+                return Err(EmbeddingError::ParseError(
+                    "Invalid base64 embedding length".to_string(),
+                ));
+            }
+            Ok(bytes
+                .chunks(4)
+                .map(|chunk| {
+                    let arr: [u8; 4] = chunk.try_into().unwrap();
+                    f32::from_le_bytes(arr) as f64
+                })
+                .collect())
+        }
+    }
+}
+
 /// Convert MessageContent to a plain string.
 fn message_content_to_string(content: &MessageContent) -> String {
     match content {
@@ -463,6 +594,56 @@ mod tests {
         }
     }
 
+    fn test_embedding_service() -> EmbeddingService {
+        let cfg = EmbeddingConfig {
+            provider: "test".to_string(),
+            model: "test-embed".to_string(),
+            dimensions: 64,
+        };
+        let test_cfg: crate::config::TestProviderConfig =
+            toml::from_str("").expect("default test provider config");
+        let provider_cfg = ProviderConfig::Test(test_cfg);
+        EmbeddingService::new(
+            &cfg,
+            &provider_cfg,
+            &CircuitBreakerRegistry::new(),
+            Client::new(),
+        )
+        .expect("test embedding service")
+    }
+
+    #[tokio::test]
+    async fn embed_batch_returns_one_vector_per_input_in_order() {
+        let svc = test_embedding_service();
+        let texts = vec![
+            "search jira issues".to_string(),
+            "create confluence page".to_string(),
+            "list github pull requests".to_string(),
+        ];
+        let vecs = svc.embed_batch(&texts).await.expect("embeds");
+        assert_eq!(vecs.len(), 3);
+        for v in &vecs {
+            assert_eq!(v.len(), 64);
+        }
+        // Distinct inputs with distinct words should not all be identical.
+        assert_ne!(vecs[0], vecs[1]);
+        // embed_batch of one input matches embed_text for the same text.
+        let single = svc
+            .embed_batch(&["search jira issues".to_string()])
+            .await
+            .unwrap();
+        let direct = svc.embed_text("search jira issues").await.unwrap();
+        assert_eq!(single.len(), 1);
+        assert_eq!(single[0], direct);
+    }
+
+    #[tokio::test]
+    async fn embed_batch_empty_input_is_noop() {
+        let svc = test_embedding_service();
+        let vecs = svc.embed_batch(&[]).await.expect("ok");
+        assert!(vecs.is_empty());
+    }
+
     #[test]
     fn test_normalize_simple_messages() {
         let messages = vec![
diff --git a/src/cli/container.rs b/src/cli/container.rs
new file mode 100644
index 0000000..a088646
--- /dev/null
+++ b/src/cli/container.rs
@@ -0,0 +1,227 @@
+//! `hadrian container` — boot a one-off shell container using the configured
+//! runtime (microsandbox / opensandbox), stage files, and run commands or an
+//! interactive shell. Mirrors how the Responses-API shell tool provisions a
+//! session so operators can reproduce and debug agent behavior locally.
+
+#![cfg(feature = "server")]
+
+use std::{
+    io::{Write, stderr, stdin, stdout},
+    sync::Arc,
+    time::Duration,
+};
+
+use futures_util::StreamExt;
+
+use super::resolve_config_path;
+use crate::{
+    config::{self, ShellRuntimeConfig},
+    runtimes::{EgressPolicy, ExecEvent, ExecRequest, NetworkMode, SessionSpec, ShellRuntime},
+};
+
+/// Entry point for the `container` subcommand.
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn run_container(
+    explicit_config_path: Option<&str>,
+    exec: Vec<String>,
+    files: Vec<String>,
+    allow_hosts: Vec<String>,
+    memory_mb: Option<u64>,
+    cpus: Option<f64>,
+    timeout_secs: u64,
+) {
+    let (config_path, _) = match resolve_config_path(explicit_config_path) {
+        Ok(v) => v,
+        Err(e) => {
+            eprintln!("Error: {e}");
+            std::process::exit(1);
+        }
+    };
+    let config = match config::GatewayConfig::from_file(&config_path) {
+        Ok(c) => c,
+        Err(e) => {
+            eprintln!("Failed to load config from {}: {e}", config_path.display());
+            std::process::exit(1);
+        }
+    };
+
+    let runtime = match build_runtime(&config.features.shell) {
+        Ok(rt) => rt,
+        Err(msg) => {
+            eprintln!("{msg}");
+            std::process::exit(1);
+        }
+    };
+
+    // Egress allowlist: explicit `--allow-host` wins, else the operator's
+    // configured ceiling, else `*` (the point of this command is debugging, so
+    // default to reachable rather than deny-all).
+    let limits = &config.features.server_tools.shell_limits;
+    let allow_hosts = if !allow_hosts.is_empty() {
+        allow_hosts
+    } else if !limits.allowed_egress_hosts.is_empty() {
+        limits.allowed_egress_hosts.clone()
+    } else {
+        vec!["*".to_string()]
+    };
+    let network_mode = if allow_hosts.iter().any(|h| h == "*") {
+        NetworkMode::Full
+    } else {
+        NetworkMode::AllowList
+    };
+
+    let spec = SessionSpec {
+        network_mode: Some(network_mode),
+        egress_policy: EgressPolicy {
+            allow_hosts: allow_hosts.clone(),
+            secrets: Vec::new(),
+        },
+        mounted_skills: Vec::new(),
+        cpu_limit: cpus.or(limits.default_cpu_limit),
+        mem_limit_bytes: memory_mb
+            .or_else(|| limits.default_mem_limit_mb.map(u64::from))
+            .map(|mb| mb * 1024 * 1024),
+        session_id_hint: None,
+    };
+
+    eprintln!(
+        "Starting {} container (egress: {})…",
+        config.features.shell.name(),
+        allow_hosts.join(", ")
+    );
+    let session = match runtime.start_session(spec).await {
+        Ok(s) => s,
+        Err(e) => {
+            eprintln!("Failed to start container: {e}");
+            std::process::exit(1);
+        }
+    };
+    eprintln!("Container ready: {}", session.session_id);
+
+    // Stage input files into /mnt/data, mirroring input_file staging.
+    for path in &files {
+        let bytes = match std::fs::read(path) {
+            Ok(b) => b,
+            Err(e) => {
+                eprintln!("Failed to read {path}: {e}");
+                continue;
+            }
+        };
+        let filename = std::path::Path::new(path)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("file");
+        let dest = format!("/mnt/data/{filename}");
+        match session.write_file(&dest, bytes.into()).await {
+            Ok(()) => eprintln!("Staged {path} → {dest}"),
+            Err(e) => eprintln!("Failed to stage {path}: {e}"),
+        }
+    }
+
+    let timeout = Duration::from_secs(timeout_secs);
+    let mut last_exit = 0;
+
+    if exec.is_empty() {
+        // Interactive shell: one command per line until EOF (Ctrl-D) or `exit`.
+        eprintln!("Interactive shell. Type `exit` or Ctrl-D to quit.\n");
+        loop {
+            print!("container$ ");
+            let _ = stdout().flush();
+            let mut line = String::new();
+            match stdin().read_line(&mut line) {
+                Ok(0) => break, // EOF
+                Ok(_) => {}
+                Err(e) => {
+                    eprintln!("stdin error: {e}");
+                    break;
+                }
+            }
+            let line = line.trim();
+            if line.is_empty() {
+                continue;
+            }
+            if line == "exit" || line == "quit" {
+                break;
+            }
+            last_exit = run_command(&session, line, timeout).await;
+        }
+    } else {
+        for cmd in &exec {
+            last_exit = run_command(&session, cmd, timeout).await;
+        }
+    }
+
+    if let Err(e) = session.terminate().await {
+        eprintln!("Warning: failed to terminate container cleanly: {e}");
+    }
+    std::process::exit(last_exit);
+}
+
+/// Build the runtime from `[features.shell]`. Passthrough runtimes don't
+/// execute locally (the model's client or OpenAI does), so they're rejected
+/// with a hint. Returns the human-facing error message on failure.
+fn build_runtime(shell: &ShellRuntimeConfig) -> Result<Arc<dyn ShellRuntime>, String> {
+    match shell {
+        ShellRuntimeConfig::None => Err(
+            "No shell runtime configured. Set `[features.shell]` to `microsandbox` or \
+             `opensandbox` in your config."
+                .to_string(),
+        ),
+        ShellRuntimeConfig::PassthroughOpenAI | ShellRuntimeConfig::ClientPassthrough => {
+            Err(format!(
+                "The `{}` runtime executes shell calls outside Hadrian (OpenAI's container or the \
+             API client), so there's nothing to run locally. Configure `microsandbox` or \
+             `opensandbox` to use this command.",
+                shell.name()
+            ))
+        }
+        #[cfg(feature = "runtime-microsandbox")]
+        ShellRuntimeConfig::Microsandbox(cfg) => Ok(Arc::new(
+            crate::runtimes::MicrosandboxRuntime::new(cfg.clone()),
+        )),
+        #[cfg(feature = "runtime-opensandbox")]
+        ShellRuntimeConfig::OpenSandbox(cfg) => Ok(Arc::new(
+            crate::runtimes::OpenSandboxRuntime::new(cfg.clone(), reqwest::Client::new()),
+        )),
+    }
+}
+
+/// Run one command, streaming stdout/stderr to the terminal. Returns the exit
+/// code (or 1 if the command couldn't be launched).
+async fn run_command(
+    session: &crate::runtimes::SessionHandle,
+    command: &str,
+    timeout: Duration,
+) -> i32 {
+    let handle = match session
+        .exec(ExecRequest {
+            command: command.to_string(),
+            stdin: None,
+            timeout: Some(timeout),
+        })
+        .await
+    {
+        Ok(h) => h,
+        Err(e) => {
+            eprintln!("exec failed: {e}");
+            return 1;
+        }
+    };
+
+    let mut output = handle.output;
+    let mut exit_code = 0;
+    while let Some(event) = output.next().await {
+        match event {
+            ExecEvent::Stdout(bytes) => {
+                let _ = stdout().write_all(&bytes);
+                let _ = stdout().flush();
+            }
+            ExecEvent::Stderr(bytes) => {
+                let _ = stderr().write_all(&bytes);
+                let _ = stderr().flush();
+            }
+            ExecEvent::Exit { code, .. } => exit_code = code,
+        }
+    }
+    exit_code
+}
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index a7d9c1d..f72df39 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1,4 +1,6 @@
 mod bootstrap;
+#[cfg(feature = "server")]
+mod container;
 mod features;
 #[cfg(feature = "server")]
 mod healthcheck;
@@ -116,6 +118,34 @@ enum Command {
         #[arg(long, default_value = "3")]
         timeout_secs: u64,
     },
+    /// Boot a one-off shell container for testing/debugging.
+    ///
+    /// Uses the configured `[features.shell]` runtime (microsandbox /
+    /// opensandbox) to start a sandbox the same way the Responses-API shell
+    /// tool does, stage files into `/mnt/data`, and run commands or an
+    /// interactive shell. Passthrough runtimes have nothing to run locally.
+    #[cfg(feature = "server")]
+    Container {
+        /// Command to run (repeatable). If omitted, opens an interactive shell.
+        #[arg(short = 'e', long = "exec")]
+        exec: Vec<String>,
+        /// File to stage into `/mnt/data` before running (repeatable).
+        #[arg(short = 'f', long = "file")]
+        file: Vec<String>,
+        /// Allowed egress host (repeatable; `*` for all). Defaults to the
+        /// operator's `allowed_egress_hosts`, or `*` if unset.
+        #[arg(long = "allow-host")]
+        allow_host: Vec<String>,
+        /// Memory limit in MB (overrides the runtime default).
+        #[arg(long)]
+        memory_mb: Option<u64>,
+        /// CPU limit in cores (overrides the runtime default).
+        #[arg(long)]
+        cpus: Option<f64>,
+        /// Per-command wall-clock timeout in seconds.
+        #[arg(long, default_value = "120")]
+        timeout_secs: u64,
+    },
 }
 
 /// Dispatch to the appropriate subcommand handler.
@@ -182,6 +212,26 @@ pub async fn dispatch(args: Args) {
         Some(Command::Healthcheck { url, timeout_secs }) => {
             healthcheck::run_healthcheck(args.config.as_deref(), url, timeout_secs).await;
         }
+        #[cfg(feature = "server")]
+        Some(Command::Container {
+            exec,
+            file,
+            allow_host,
+            memory_mb,
+            cpus,
+            timeout_secs,
+        }) => {
+            container::run_container(
+                args.config.as_deref(),
+                exec,
+                file,
+                allow_host,
+                memory_mb,
+                cpus,
+                timeout_secs,
+            )
+            .await;
+        }
         Some(Command::Serve) | None => {
             server::run_server(args.config.as_deref(), args.no_browser).await;
         }
diff --git a/src/cli/server.rs b/src/cli/server.rs
index 9da81e6..a6a5ad4 100644
--- a/src/cli/server.rs
+++ b/src/cli/server.rs
@@ -259,6 +259,66 @@ pub(crate) async fn run_server(explicit_config_path: Option<&str>, no_browser: b
         });
     }
 
+    // The shutdown token lives for the whole server lifetime and gets
+    // cancelled when the OS sends SIGTERM/SIGINT. Created here so the
+    // responses workers below can subscribe — without this, the
+    // workers loop forever holding an AppState clone, which keeps
+    // mpsc senders (usage_drain etc.) alive and stalls the tracked
+    // drainer shutdown.
+    let shutdown_token = CancellationToken::new();
+
+    // Start the Responses API retention worker. Always runs when a
+    // responses_store is configured; rate is governed by
+    // [features.responses] cleanup_interval_secs. Each pass also
+    // reaps `in_progress` rows older than `max_in_progress_secs`.
+    if let (Some(db), Some(store)) = (state.db.clone(), state.responses_store.clone()) {
+        let interval =
+            std::time::Duration::from_secs(config.features.responses.cleanup_interval_secs);
+        let max_in_progress =
+            std::time::Duration::from_secs(config.features.responses.max_in_progress_secs);
+        let cancel = shutdown_token.clone();
+        state.task_tracker.spawn(async move {
+            jobs::start_responses_retention_worker(store, db, interval, max_in_progress, cancel)
+                .await;
+        });
+    }
+
+    // Start the idle-container reaper. Marks containers whose
+    // `last_active_at + idle_ttl_secs` has elapsed as `expired` and
+    // evicts them from the in-memory registry. Always runs when a
+    // containers_service is configured.
+    if let (Some(db), Some(containers)) = (state.db.clone(), state.containers_service.clone()) {
+        let registry = state.container_session_registry.clone();
+        // Run at 1/4 of the default idle TTL, clamped to [10s, 5min].
+        let raw = config.features.containers.default_idle_ttl_secs / 4;
+        let interval = std::time::Duration::from_secs(raw.clamp(10, 300));
+        let cancel = shutdown_token.clone();
+        state.task_tracker.spawn(async move {
+            jobs::start_containers_reaper_worker(containers, registry, db, interval, cancel).await;
+        });
+    }
+
+    // Start the background response worker — claims rows queued by
+    // `POST /v1/responses` with `background=true` and runs them
+    // through the LLM pipeline.
+    if state.responses_store.is_some() && state.db.is_some() {
+        let worker_state = state.clone();
+        let cancel = shutdown_token.clone();
+        state.task_tracker.spawn(async move {
+            jobs::start_background_response_worker(worker_state, cancel).await;
+        });
+    }
+
+    // Start the cross-replica cancel poller. One task, one DB
+    // round-trip per cycle for the whole replica's in-flight set —
+    // replaces the previous per-execution polling.
+    if let Some(store) = state.responses_store.clone() {
+        let cancel = shutdown_token.clone();
+        state.task_tracker.spawn(async move {
+            jobs::start_responses_cancel_poller(store, cancel).await;
+        });
+    }
+
     // Start vector store cleanup worker if configured and database is available
     if let Some(db) = state.db.clone() {
         let cleanup_config = config.features.vector_store_cleanup.clone();
@@ -274,6 +334,18 @@ pub(crate) async fn run_server(explicit_config_path: Option<&str>, no_browser: b
         });
     }
 
+    // Start the container cleanup worker if configured and a containers
+    // service + database are available. Hard-deletes `expired` / `deleted`
+    // container rows (and their captured files) past the configured delay so
+    // terminal rows don't accumulate forever.
+    if let (Some(db), Some(containers)) = (state.db.clone(), state.containers_service.clone()) {
+        let cleanup_config = config.features.containers_cleanup.clone();
+        let cancel = shutdown_token.clone();
+        state.task_tracker.spawn(async move {
+            jobs::start_containers_cleanup_worker(containers, db, cleanup_config, cancel).await;
+        });
+    }
+
     // Start model catalog sync worker if enabled
     {
         let catalog_config = config.features.model_catalog.clone();
@@ -379,13 +451,9 @@ pub(crate) async fn run_server(explicit_config_path: Option<&str>, no_browser: b
         None
     };
 
-    // CancellationToken for long-running background tasks that hold an
-    // AppState clone. Without this, an infinite-loop tokio::spawn'd task
-    // (like the refresh below) keeps a clone of `usage_drain`'s mpsc::Sender
-    // alive forever, which prevents the tracked drainer worker's
-    // `rx.recv().await` from ever seeing `None`. Tripped when the OS shutdown
-    // signal arrives.
-    let shutdown_token = CancellationToken::new();
+    // (CancellationToken `shutdown_token` was created earlier so the
+    // responses workers could subscribe; reuse it for the cache
+    // refresher below.)
 
     // Refresh the static models cache periodically in the background
     // (initial warming already happened in AppState::new)
@@ -412,6 +480,7 @@ pub(crate) async fn run_server(explicit_config_path: Option<&str>, no_browser: b
     } else {
         None
     };
+    let response_event_buffer = state.response_event_buffer.clone();
     let app = build_app(&config, state);
 
     let bind_addr = format!("{}:{}", config.server.host, config.server.port);
@@ -491,7 +560,13 @@ pub(crate) async fn run_server(explicit_config_path: Option<&str>, no_browser: b
         std::process::exit(1);
     }
 
-    drain_background_tasks(task_tracker, usage_buffer_handle, shutdown_config).await;
+    drain_background_tasks(
+        task_tracker,
+        usage_buffer_handle,
+        response_event_buffer,
+        shutdown_config,
+    )
+    .await;
 }
 
 async fn wait_for_shutdown_signal() {
@@ -531,6 +606,7 @@ async fn drain_background_tasks(
         Arc<usage_buffer::UsageLogBuffer>,
         tokio::task::JoinHandle<()>,
     )>,
+    response_event_buffer: Option<Arc<crate::services::ResponseEventBuffer>>,
     shutdown_config: crate::config::ShutdownConfig,
 ) {
     task_tracker.close();
@@ -549,6 +625,20 @@ async fn drain_background_tasks(
         }
     }
 
+    if let Some(buffer) = response_event_buffer {
+        // 5s is generous: the drainer flushes every 100ms by default
+        // and any in-flight events get a final flush. Bound it so a
+        // wedged DB doesn't hold up shutdown indefinitely.
+        if tokio::time::timeout(std::time::Duration::from_secs(5), buffer.shutdown())
+            .await
+            .is_err()
+        {
+            tracing::warn!("Timeout waiting for response event buffer to flush");
+        } else {
+            tracing::info!("Response event buffer flushed successfully");
+        }
+    }
+
     let wait_result = tokio::time::timeout(
         std::time::Duration::from_secs(shutdown_config.drain_secs),
         task_tracker.wait(),
diff --git a/src/config/features.rs b/src/config/features.rs
index 135271f..b47a71f 100644
--- a/src/config/features.rs
+++ b/src/config/features.rs
@@ -1,6 +1,9 @@
+use std::collections::HashMap;
+
 use serde::{Deserialize, Serialize};
 
 use super::{CircuitBreakerConfig, RetryConfig};
+use crate::api_types::responses::ToolSearchRankerKind;
 
 /// Feature flags for optional capabilities.
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
@@ -37,6 +40,12 @@ pub struct FeaturesConfig {
     #[serde(default)]
     pub vector_store_cleanup: VectorStoreCleanupConfig,
 
+    /// Container cleanup job configuration.
+    /// Hard-deletes `expired` / `deleted` containers (and their captured
+    /// files) after a configurable delay so terminal rows don't accumulate.
+    #[serde(default)]
+    pub containers_cleanup: ContainersCleanupConfig,
+
     /// File processing configuration for RAG document ingestion.
     /// Controls how uploaded files are chunked and embedded into vector stores.
     #[serde(default)]
@@ -62,6 +71,562 @@ pub struct FeaturesConfig {
     /// Caches model lists from config-file providers to avoid per-request latency.
     #[serde(default)]
     pub static_models_cache: StaticModelsCacheConfig,
+
+    /// Shared configuration for server-executed tools (file_search, web_search,
+    /// future: shell). Controls the global per-request iteration budget across
+    /// all such tools. Replaces the per-tool `max_iterations` fields on
+    /// `[features.file_search]` and `[features.web_search]`, which are
+    /// deprecated and emit a warning at startup if set to a non-default value.
+    #[serde(default)]
+    pub server_tools: ServerToolsConfig,
+
+    /// Shell tool runtime configuration. Selects which backend executes
+    /// `shell` tool calls (passthrough_openai, microsandbox, etc.).
+    /// Defaults to `None` — shell tool disabled.
+    #[serde(default)]
+    pub shell: super::ShellRuntimeConfig,
+
+    /// Container / `/mnt/data` artifact capture settings. Controls how
+    /// files written by the shell tool are persisted and surfaced back
+    /// to the conversation as `container_file_citation` annotations.
+    #[serde(default)]
+    pub containers: ContainersConfig,
+
+    /// Persistence settings for the Responses API.
+    #[serde(default)]
+    pub responses: ResponsesPersistenceConfig,
+
+    /// MCP (Model Context Protocol) tool configuration. When set,
+    /// `/v1/responses` accepts `{"type": "mcp", ...}` tool entries and
+    /// either forwards them to OpenAI/Azure (`mode = passthrough_openai`)
+    /// or runs the MCP client loop locally (`mode = hadrian_hosted`).
+    /// Defaults to `None` — MCP tool disabled.
+    #[serde(default)]
+    pub mcp: Option<McpConfig>,
+}
+
+/// MCP tool configuration.
+///
+/// Two execution modes:
+///
+/// - `passthrough_openai` — `mcp` tools are forwarded verbatim to
+///   OpenAI / Azure OpenAI, which runs the MCP client loop and emits
+///   the canonical `mcp_*` items. Other providers reject with
+///   `mcp_passthrough_unsupported_provider`.
+/// - `hadrian_hosted` — Hadrian runs the MCP client loop itself
+///   using `rmcp` and rewrites `mcp` into per-tool function tools,
+///   so any provider can drive the loop.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct McpConfig {
+    /// Master enable. `false` makes the gateway behave as if MCP isn't
+    /// configured at all (no preprocess, no executor) even when other
+    /// fields are set.
+    #[serde(default = "default_mcp_enabled")]
+    pub enabled: bool,
+    /// Execution mode.
+    #[serde(default)]
+    pub mode: McpMode,
+    /// Operator allowlist of remote MCP server URLs. `None` = any URL
+    /// the caller supplies is accepted (the caller already controls
+    /// `Authorization`, so this is a defense-in-depth knob, not an
+    /// auth check). When `Some`, the caller's `server_url` must match
+    /// at least one entry exactly.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub allowed_server_urls: Option<Vec<String>>,
+    /// When `false` (the default), requests using `connector_id` —
+    /// OpenAI's first-party connector handles — are rejected. Self-
+    /// hosted gateways usually can't reach OpenAI's connector registry,
+    /// so the safe default is "off"; flip to `true` only when the
+    /// upstream is OpenAI/Azure and the connector is known to work.
+    #[serde(default = "default_mcp_allow_connector_ids")]
+    pub allow_connector_ids: bool,
+    /// Hadrian-side tool search for deferred tools (`defer_loading`).
+    /// Only relevant under `hadrian_hosted`.
+    #[serde(default)]
+    pub tool_search: ToolSearchConfig,
+    /// Deployment default upper bound, in seconds, on a single MCP
+    /// `tools/call` round-trip under `hadrian_hosted`. `rmcp` applies no
+    /// request timeout of its own and the underlying reqwest client sets
+    /// none either, so without this a server that accepts the connection
+    /// and then never responds would hang the response indefinitely.
+    /// Overridable per tool via the `mcp` tool's `call_timeout_secs`
+    /// Hadrian extension. Default 300s (5 min).
+    #[serde(default = "default_mcp_call_timeout_secs")]
+    pub call_timeout_secs: u64,
+}
+
+/// Settings for Hadrian-side tool search over a deferred MCP catalog.
+///
+/// Engages under `hadrian_hosted` when a request marks an `mcp` tool
+/// entry with `defer_loading: true` (and does not opt into native
+/// passthrough). Hadrian exposes a single `tool_search` function tool,
+/// keeps the catalog server-side, and injects matched per-tool function
+/// definitions as the model discovers them.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ToolSearchConfig {
+    /// Deployment default ranking strategy. Overridable per-request via
+    /// the `tool_search` tool's `ranker` extension field. `hybrid` (the
+    /// default) fuses semantic + lexical relevance; `semantic` requires a
+    /// resolvable embedding provider (validated at startup); `lexical`
+    /// needs no embeddings.
+    #[serde(default = "default_tool_search_ranker")]
+    pub ranker: ToolSearchRankerKind,
+    /// Maximum number of tools a single search returns.
+    #[serde(default = "default_tool_search_max_results")]
+    pub max_results: usize,
+    /// Minimum relevance score (0.0–1.0) a tool must reach to be
+    /// returned. Applies only to the `lexical` and `semantic` rankers,
+    /// whose scores are normalized to this range. The default `hybrid`
+    /// ranker fuses ranks via RRF and produces a small ranking-only score
+    /// (not a 0–1 relevance), so the threshold is *ignored* for it —
+    /// otherwise any non-zero value would drop every result. Use
+    /// `max_results` to bound hybrid output.
+    #[serde(default = "default_tool_search_score_threshold")]
+    pub score_threshold: f64,
+    /// Embedding configuration for semantic/hybrid ranking. When omitted,
+    /// resolution falls back to the `file_search` then semantic-cache
+    /// embedding config; if none resolve, `hybrid` degrades to `lexical`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub embedding: Option<EmbeddingConfig>,
+    /// RRF smoothing constant `k` for `hybrid` fusion (default 60, per the
+    /// original RRF paper).
+    #[serde(default = "default_tool_search_rrf_k")]
+    pub rrf_k: u32,
+}
+
+impl Default for ToolSearchConfig {
+    fn default() -> Self {
+        Self {
+            ranker: default_tool_search_ranker(),
+            max_results: default_tool_search_max_results(),
+            score_threshold: default_tool_search_score_threshold(),
+            embedding: None,
+            rrf_k: default_tool_search_rrf_k(),
+        }
+    }
+}
+
+fn default_tool_search_ranker() -> ToolSearchRankerKind {
+    ToolSearchRankerKind::Hybrid
+}
+
+fn default_tool_search_max_results() -> usize {
+    20
+}
+
+fn default_tool_search_score_threshold() -> f64 {
+    0.0
+}
+
+fn default_tool_search_rrf_k() -> u32 {
+    60
+}
+
+impl McpConfig {
+    /// True when MCP is enabled *and* the gateway runs the client loop
+    /// itself (`hadrian_hosted`). This is the single predicate the
+    /// route handler (non-streaming bridge), the approval-resume gate,
+    /// and the pipeline executor registration all key off — keep it in
+    /// one place so the three sites can't drift apart.
+    pub fn is_hadrian_hosted(&self) -> bool {
+        self.enabled && matches!(self.mode, McpMode::HadrianHosted)
+    }
+
+    pub fn validate(&self) -> Result<(), String> {
+        // A zero call timeout would expire every `tools/call` immediately;
+        // a zero tool-search cap would return nothing from `tool_search`.
+        if self.call_timeout_secs == 0 {
+            return Err("[features.mcp] call_timeout_secs must be > 0".into());
+        }
+        if self.tool_search.max_results == 0 {
+            return Err("[features.mcp.tool_search] max_results must be > 0".into());
+        }
+        Ok(())
+    }
+}
+
+impl Default for McpConfig {
+    fn default() -> Self {
+        Self {
+            enabled: default_mcp_enabled(),
+            mode: McpMode::default(),
+            allowed_server_urls: None,
+            allow_connector_ids: default_mcp_allow_connector_ids(),
+            tool_search: ToolSearchConfig::default(),
+            call_timeout_secs: default_mcp_call_timeout_secs(),
+        }
+    }
+}
+
+fn default_mcp_enabled() -> bool {
+    true
+}
+
+fn default_mcp_call_timeout_secs() -> u64 {
+    300
+}
+
+fn default_mcp_allow_connector_ids() -> bool {
+    false
+}
+
+/// Where the MCP client loop runs.
+#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum McpMode {
+    /// Forward `mcp` tool entries to OpenAI / Azure OpenAI. Other
+    /// providers reject. The default — zero gateway overhead.
+    #[default]
+    PassthroughOpenai,
+    /// Hadrian runs the MCP client loop itself via `rmcp` and rewrites
+    /// `mcp` tools into per-tool function tools. Requires the `mcp`
+    /// cargo feature.
+    HadrianHosted,
+}
+
+/// Persistence and retention settings for the Responses API.
+///
+/// When `store=true` (the OpenAI default) is set on a request, Hadrian
+/// writes a row to the `responses` table that can later be retrieved
+/// via `GET /v1/responses/{id}` or cancelled via
+/// `POST /v1/responses/{id}/cancel`. Records past
+/// `retention_secs` are removed by the cleanup worker.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ResponsesPersistenceConfig {
+    /// How long a terminal response is kept before pruning.
+    /// Default 86400 (24h). Must be > 0.
+    #[serde(default = "default_responses_retention_secs")]
+    pub retention_secs: u64,
+    /// Interval at which the retention worker scans for expired
+    /// records. Default 3600 (1h). Must be > 0.
+    #[serde(default = "default_responses_cleanup_interval_secs")]
+    pub cleanup_interval_secs: u64,
+    /// Max concurrent in-flight background-mode responses **per
+    /// replica**. Each `background=true` request claims a row and runs
+    /// the LLM stream in its own task; without a cap a burst can pin
+    /// the whole replica. Default 8.
+    #[serde(default = "default_responses_worker_concurrency")]
+    pub worker_concurrency: usize,
+    /// Maximum wall-clock time a response is allowed to remain in
+    /// `status='in_progress'`. The retention worker reaps rows that
+    /// exceed this (mark Failed with `code="worker_lost"`), covering
+    /// the case where a worker crashed mid-execution. Should be
+    /// generously larger than the longest expected execution — a
+    /// real workload should finish well within this. Default 3600
+    /// (1h). Must be > 0.
+    #[serde(default = "default_responses_max_in_progress_secs")]
+    pub max_in_progress_secs: u64,
+    /// Retry policy for background-mode responses. Foreground
+    /// streaming requests don't use this — the client owns the retry.
+    #[serde(default)]
+    pub retry: ResponsesRetryConfig,
+    /// Optional webhook fired on terminal-state transitions
+    /// (`completed`, `failed`, `cancelled`, `incomplete`). Disabled
+    /// when unset.
+    #[serde(default)]
+    pub webhook: Option<ResponsesWebhookConfig>,
+
+    /// Gateway-side context compaction for non-OpenAI providers (the
+    /// canonical OpenAI compaction directive is otherwise forwarded
+    /// verbatim). Disabled by default.
+    #[serde(default)]
+    pub compaction: ResponsesCompactionConfig,
+}
+
+/// Operator-side defaults for the gateway compactor. When a request
+/// includes `context_management = [{type: "compaction", ...}]` and the
+/// upstream provider does not natively support server-side compaction
+/// (i.e. anything other than OpenAI / Azure OpenAI), Hadrian runs the
+/// compactor before dispatch.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ResponsesCompactionConfig {
+    /// Master switch. When false, gateway-side compaction never runs
+    /// regardless of request directives; non-OpenAI providers still
+    /// see the unedited payload (matching pre-compactor behaviour).
+    #[serde(default = "default_compaction_enabled")]
+    pub enabled: bool,
+    /// Strategy used when the request didn't specify one. Picks
+    /// `truncate` so the default behaviour is deterministic + free.
+    #[serde(default = "default_compaction_default_strategy")]
+    pub default_strategy: ResponsesCompactionStrategy,
+    /// Fallback `compact_threshold` (in tokens) when the request
+    /// didn't specify one. The default 12_000 leaves headroom under
+    /// the smaller non-OpenAI context windows (Bedrock claude-haiku
+    /// ~200k, but typical app prompts stay well below the limit).
+    #[serde(default = "default_compaction_threshold")]
+    pub default_threshold_tokens: u32,
+    /// Number of most-recent items the compactor must keep intact.
+    /// Older items are dropped (truncate) or replaced by a summary
+    /// (llm). Default 6.
+    #[serde(default = "default_compaction_keep_recent")]
+    pub keep_recent_items: usize,
+    /// Default prompt the `llm` strategy uses to summarise dropped
+    /// items. Overridden per-request via
+    /// `context_management.compaction.prompt`. Includes a placeholder
+    /// describing what the summary will be inserted as.
+    #[serde(default = "default_compaction_prompt")]
+    pub default_prompt: String,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum ResponsesCompactionStrategy {
+    /// Summarise dropped items via the active provider.
+    Llm,
+    /// Drop oldest non-system items until the rolling token estimate
+    /// falls under the threshold.
+    #[default]
+    Truncate,
+}
+
+impl Default for ResponsesCompactionConfig {
+    fn default() -> Self {
+        Self {
+            enabled: default_compaction_enabled(),
+            default_strategy: default_compaction_default_strategy(),
+            default_threshold_tokens: default_compaction_threshold(),
+            keep_recent_items: default_compaction_keep_recent(),
+            default_prompt: default_compaction_prompt(),
+        }
+    }
+}
+
+fn default_compaction_enabled() -> bool {
+    false
+}
+
+fn default_compaction_default_strategy() -> ResponsesCompactionStrategy {
+    ResponsesCompactionStrategy::Truncate
+}
+
+fn default_compaction_threshold() -> u32 {
+    12_000
+}
+
+fn default_compaction_keep_recent() -> usize {
+    6
+}
+
+fn default_compaction_prompt() -> String {
+    "Summarize the prior conversation in <= 250 words. Preserve concrete decisions, \
+     user-stated constraints, file paths and IDs, and unresolved questions. Drop \
+     redundant pleasantries. Output a single paragraph; the result will be inserted \
+     as system context for the model to consult in the remaining turns."
+        .to_string()
+}
+
+impl Default for ResponsesPersistenceConfig {
+    fn default() -> Self {
+        Self {
+            retention_secs: default_responses_retention_secs(),
+            cleanup_interval_secs: default_responses_cleanup_interval_secs(),
+            worker_concurrency: default_responses_worker_concurrency(),
+            max_in_progress_secs: default_responses_max_in_progress_secs(),
+            retry: ResponsesRetryConfig::default(),
+            webhook: None,
+            compaction: ResponsesCompactionConfig::default(),
+        }
+    }
+}
+
+impl ResponsesPersistenceConfig {
+    pub fn validate(&self) -> Result<(), String> {
+        if self.retention_secs == 0 {
+            return Err("[features.responses] retention_secs must be > 0".into());
+        }
+        if self.cleanup_interval_secs == 0 {
+            return Err("[features.responses] cleanup_interval_secs must be > 0".into());
+        }
+        if self.max_in_progress_secs == 0 {
+            return Err("[features.responses] max_in_progress_secs must be > 0".into());
+        }
+        self.retry.validate()?;
+        Ok(())
+    }
+}
+
+fn default_responses_worker_concurrency() -> usize {
+    8
+}
+
+fn default_responses_max_in_progress_secs() -> u64 {
+    3_600
+}
+
+/// Retry policy for background-mode responses.
+///
+/// Foreground `/v1/responses` requests are streamed back to the
+/// client — retries are the client's responsibility. Background
+/// requests have no client connected during execution, so the
+/// worker handles transient failures (provider 5xx, network blips,
+/// transient DB errors) by re-running the row with exponential
+/// backoff until either the call succeeds or `max_attempts` is hit.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ResponsesRetryConfig {
+    /// Master switch. Default `true`.
+    #[serde(default = "default_responses_retry_enabled")]
+    pub enabled: bool,
+    /// Maximum number of execution attempts, including the first.
+    /// `1` means no retry. Default 3.
+    #[serde(default = "default_responses_retry_max_attempts")]
+    pub max_attempts: u32,
+    /// Initial backoff before the second attempt, in milliseconds.
+    /// Default 500ms.
+    #[serde(default = "default_responses_retry_initial_backoff_ms")]
+    pub initial_backoff_ms: u64,
+    /// Backoff multiplier between attempts. Default 2.0.
+    #[serde(default = "default_responses_retry_multiplier")]
+    pub multiplier: f64,
+    /// Cap on a single backoff interval, in milliseconds. Default
+    /// 30000 (30s).
+    #[serde(default = "default_responses_retry_max_backoff_ms")]
+    pub max_backoff_ms: u64,
+}
+
+impl Default for ResponsesRetryConfig {
+    fn default() -> Self {
+        Self {
+            enabled: default_responses_retry_enabled(),
+            max_attempts: default_responses_retry_max_attempts(),
+            initial_backoff_ms: default_responses_retry_initial_backoff_ms(),
+            multiplier: default_responses_retry_multiplier(),
+            max_backoff_ms: default_responses_retry_max_backoff_ms(),
+        }
+    }
+}
+
+impl ResponsesRetryConfig {
+    pub fn validate(&self) -> Result<(), String> {
+        if self.max_attempts == 0 {
+            return Err("[features.responses.retry] max_attempts must be >= 1".into());
+        }
+        if self.multiplier < 1.0 {
+            return Err("[features.responses.retry] multiplier must be >= 1.0".into());
+        }
+        if self.initial_backoff_ms == 0 {
+            return Err("[features.responses.retry] initial_backoff_ms must be > 0".into());
+        }
+        if self.max_backoff_ms < self.initial_backoff_ms {
+            return Err(
+                "[features.responses.retry] max_backoff_ms must be >= initial_backoff_ms".into(),
+            );
+        }
+        Ok(())
+    }
+
+    /// Compute the next backoff interval for `attempt` (1-indexed
+    /// after the first try). Caps at `max_backoff_ms`.
+    pub fn backoff_for_attempt(&self, attempt: u32) -> std::time::Duration {
+        let exp = attempt.saturating_sub(1).min(31) as i32;
+        let ms = (self.initial_backoff_ms as f64) * self.multiplier.powi(exp);
+        let clamped = ms.min(self.max_backoff_ms as f64).max(0.0) as u64;
+        std::time::Duration::from_millis(clamped)
+    }
+}
+
+fn default_responses_retry_enabled() -> bool {
+    true
+}
+
+fn default_responses_retry_max_attempts() -> u32 {
+    3
+}
+
+fn default_responses_retry_initial_backoff_ms() -> u64 {
+    500
+}
+
+fn default_responses_retry_multiplier() -> f64 {
+    2.0
+}
+
+fn default_responses_retry_max_backoff_ms() -> u64 {
+    30_000
+}
+
+/// Webhook delivery settings.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ResponsesWebhookConfig {
+    /// Target URL. Validated for SSRF at config-load time via
+    /// `validate_base_url` (no private/loopback/metadata addresses by
+    /// default).
+    pub url: String,
+    /// Optional bearer token sent in the `Authorization` header. As
+    /// with other secret-bearing config fields, treat this value as
+    /// sensitive: don't log it and prefer routing through the secrets
+    /// manager URI scheme rather than embedding the literal token.
+    #[serde(default)]
+    pub bearer_token: Option<String>,
+    /// Optional HMAC signing secret. When set, every delivery carries
+    /// an `X-Hadrian-Signature: t=<unix>,v1=<hex>` header where the
+    /// hex digest is `HMAC-SHA256(secret, "<unix>.<body>")`. Receivers
+    /// reject requests whose timestamp is too old (defends against
+    /// replay) and recompute the digest to verify the body.
+    #[serde(default)]
+    pub signing_secret: Option<String>,
+    /// Per-request timeout in seconds. Default 10s.
+    #[serde(default = "default_webhook_timeout_secs")]
+    pub timeout_secs: u64,
+    /// Maximum concurrent in-flight deliveries. A slow target won't
+    /// hold up new deliveries beyond this cap; additional events
+    /// queue in the bounded retry channel. Default 32.
+    #[serde(default = "default_webhook_max_concurrent")]
+    pub max_concurrent_deliveries: usize,
+    /// Bounded retry queue capacity. When full, new events are
+    /// dropped (with a `webhook_dropped_total` counter increment) so
+    /// the gateway doesn't grow memory unboundedly when the target
+    /// is wedged. Default 1000.
+    #[serde(default = "default_webhook_retry_capacity")]
+    pub retry_queue_capacity: usize,
+}
+
+impl ResponsesWebhookConfig {
+    /// Validate the webhook URL against Hadrian's SSRF rules. Called
+    /// from `FeaturesConfig::validate()` at startup so misconfigured
+    /// hooks fail loudly instead of silently sending traffic to
+    /// internal endpoints.
+    pub fn validate(&self, allow_loopback: bool) -> Result<(), String> {
+        crate::validation::validate_base_url(&self.url, allow_loopback).map_err(|e| {
+            format!(
+                "[features.responses.webhook] url failed SSRF validation: {}",
+                e
+            )
+        })
+    }
+}
+
+fn default_webhook_timeout_secs() -> u64 {
+    10
+}
+
+fn default_webhook_max_concurrent() -> usize {
+    32
+}
+
+fn default_webhook_retry_capacity() -> usize {
+    1000
+}
+
+fn default_responses_retention_secs() -> u64 {
+    86_400
+}
+
+fn default_responses_cleanup_interval_secs() -> u64 {
+    3_600
 }
 
 impl FeaturesConfig {
@@ -70,10 +635,348 @@ impl FeaturesConfig {
         if let Some(ref file_search) = self.file_search {
             file_search.validate()?;
         }
+        // Surface deprecation warnings for per-tool iteration limits.
+        if let Some(ref file_search) = self.file_search
+            && file_search.max_iterations != default_file_search_max_iterations()
+        {
+            tracing::warn!(
+                "[features.file_search] max_iterations is deprecated; \
+                 use [features.server_tools] max_iterations instead. \
+                 The global value ({}) will be used.",
+                self.server_tools.max_iterations
+            );
+        }
+        if let Some(ref web_search) = self.web_search
+            && web_search.max_iterations != default_web_search_max_iterations()
+        {
+            tracing::warn!(
+                "[features.web_search] max_iterations is deprecated; \
+                 use [features.server_tools] max_iterations instead. \
+                 The global value ({}) will be used.",
+                self.server_tools.max_iterations
+            );
+        }
+        self.responses.validate()?;
+        self.containers.validate()?;
+        self.containers_cleanup.validate()?;
+        if let Some(ref mcp) = self.mcp {
+            mcp.validate()?;
+        }
+        Ok(())
+    }
+}
+
+/// Configuration shared by all server-executed tools.
+///
+/// Server-executed tools (`file_search`, `web_search`, etc.) run inside the
+/// gateway in a multi-turn loop. This config gates the total number of
+/// iterations a single request can drive, across **all** tools — preventing
+/// runaway sessions where the model keeps requesting new tool calls.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ServerToolsConfig {
+    /// Maximum number of provider continuation requests in one response.
+    ///
+    /// Counts all server-executed tool iterations together (file_search +
+    /// web_search + shell + …). On the final iteration the tools strip
+    /// their own definitions from the continuation payload so the model
+    /// is forced to produce a text response.
+    ///
+    /// Default: 10.
+    #[serde(default = "default_server_tools_max_iterations")]
+    pub max_iterations: usize,
+
+    /// Pricing for runtime time consumed by the shell tool.
+    ///
+    /// Local runtimes (microsandbox) are billed by wall-clock seconds.
+    /// Passthrough mode (where the upstream provider runs the container)
+    /// is billed by that provider and remains 0 here.
+    #[serde(default)]
+    pub pricing: ServerToolsPricingConfig,
+
+    /// Shell-tool execution limits.
+    #[serde(default)]
+    pub shell_limits: ShellLimitsConfig,
+}
+
+impl Default for ServerToolsConfig {
+    fn default() -> Self {
+        Self {
+            max_iterations: default_server_tools_max_iterations(),
+            pricing: ServerToolsPricingConfig::default(),
+            shell_limits: ShellLimitsConfig::default(),
+        }
+    }
+}
+
+fn default_server_tools_max_iterations() -> usize {
+    10
+}
+
+/// Limits enforced on every shell-tool invocation. Sets soft ceilings
+/// on wall-clock time and resource use so a runaway model can't pin
+/// VM resources indefinitely, and the upper bound for what a
+/// per-request `environment` block may ask for.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ShellLimitsConfig {
+    /// Per-command timeout in seconds. The runtime aborts the exec
+    /// once this elapses; the persister records the partial output.
+    /// Default 300 (5 min).
+    #[serde(default = "default_shell_command_timeout_secs")]
+    pub command_timeout_secs: u64,
+    /// Default vCPU limit applied when the SessionSpec doesn't
+    /// specify one. The runtime backend's own default applies when
+    /// this is `None`.
+    #[serde(default)]
+    pub default_cpu_limit: Option<f64>,
+    /// Default memory limit (MB) applied when the request didn't
+    /// supply a `container_auto.memory_limit`. The runtime backend's
+    /// own default applies when this is `None`.
+    #[serde(default)]
+    pub default_mem_limit_mb: Option<u32>,
+    /// Hard ceiling for the per-request `container_auto.memory_limit`
+    /// override. Requests asking for more than this are rejected with
+    /// `400`. `None` (the default) means requests can ask for any
+    /// value the backend supports.
+    #[serde(default)]
+    pub max_mem_limit_mb: Option<u32>,
+    /// Hostnames (or `*.suffix` patterns) requests may put in
+    /// `network_policy.domains`. Empty (the default) means requests
+    /// cannot widen egress beyond whatever the runtime allows by
+    /// default; use `["*"]` to permit any host.
+    #[serde(default)]
+    pub allowed_egress_hosts: Vec<String>,
+    /// Operator-pre-configured secrets the request may reference by
+    /// `placeholder` in `domain_secrets`. The raw value never leaves
+    /// the gateway — the model sees only the placeholder, and the
+    /// runtime substitutes the value at egress to the permitted hosts.
+    #[serde(default)]
+    pub allowed_domain_secrets: HashMap<String, AllowedDomainSecret>,
+    /// Maximum number of characters of stdout/stderr fed back to the
+    /// model per shell call. Output longer than this is head + tail
+    /// trimmed with a `... N chars truncated ...` marker so the model
+    /// still sees both ends. The full stream remains in the response
+    /// event log; operators can raise this for token-rich models or
+    /// lower it to bound context spend. Default 8000.
+    #[serde(default = "default_shell_max_output_chars")]
+    pub max_output_chars: usize,
+    /// Free-text description of the container environment, appended to the
+    /// shell tool's description the model sees. Use it to explain which
+    /// toolchains are available and how to install packages, so the model
+    /// doesn't waste turns probing. Defaults to instructions for the default
+    /// `alpine` image (how to `apk add` curl, uv, pnpm, etc.); set to `""` to
+    /// append nothing, or override it to match a different image.
+    #[serde(default = "default_environment_description")]
+    pub environment_description: Option<String>,
+}
+
+/// Default shell-tool environment notes, written for the default `alpine`
+/// microsandbox image. Override when using a different base image.
+pub fn default_environment_description() -> Option<String> {
+    Some(
+        "Alpine Linux (musl libc), minimal base image. Install what you need at the start of a \
+         session; nothing beyond busybox + a shell is guaranteed. **Always try `apk` first** — \
+         most tools are packaged and it's the fastest, most reliable option: `apk add --no-cache \
+         <pkg>`, e.g. `apk add --no-cache curl git python3 py3-pip nodejs npm build-base uv pnpm` \
+         (uv and pnpm are in the Alpine community repo on recent releases). Only if a package \
+         isn't available via apk, fall back to a language-specific installer: uv via `curl -LsSf \
+         https://astral.sh/uv/install.sh | sh`, pnpm via `npm install -g pnpm`, Python libs via \
+         `uv pip`/`pip`, Node libs via `pnpm`/`npm`, Rust crates via `cargo`. Installs need \
+         network egress to be allowed."
+            .to_string(),
+    )
+}
+
+impl Default for ShellLimitsConfig {
+    fn default() -> Self {
+        Self {
+            command_timeout_secs: default_shell_command_timeout_secs(),
+            default_cpu_limit: None,
+            default_mem_limit_mb: None,
+            max_mem_limit_mb: None,
+            allowed_egress_hosts: Vec::new(),
+            allowed_domain_secrets: HashMap::new(),
+            max_output_chars: default_shell_max_output_chars(),
+            environment_description: default_environment_description(),
+        }
+    }
+}
+
+fn default_shell_max_output_chars() -> usize {
+    8_000
+}
+
+/// One operator-pinned secret the request may reference via
+/// `ShellDomainSecretRef`. The literal value can be a plaintext token
+/// or a secrets-manager URI; resolution is the runtime's
+/// responsibility.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct AllowedDomainSecret {
+    /// Literal value or `secret://…` reference. Never logged. Never
+    /// returned in API responses.
+    pub value: String,
+    /// Hostnames the runtime is permitted to send this secret to. A
+    /// request's `allowed_domains` must be a subset; empty in the
+    /// request inherits this full list.
+    #[serde(default)]
+    pub allowed_hosts: Vec<String>,
+}
+
+fn default_shell_command_timeout_secs() -> u64 {
+    300
+}
+
+/// Settings for `/mnt/data` artifact capture from the shell tool.
+///
+/// When the configured shell runtime supports `file_io`, Hadrian
+/// snapshots the container's `/mnt/data` directory before and after
+/// every shell command. New or changed files are surfaced as
+/// `container_file_citation` annotations on the assistant's reply, with
+/// a stable `cfile_<uuid>` identifier that the container files API
+/// resolves to downloadable bytes.
+///
+/// Setting `enabled = false` reverts to the legacy "tear down VM after
+/// every command" behaviour with no artifact capture.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ContainersConfig {
+    /// Master switch. When false, the shell tool boots and tears down a
+    /// fresh microVM for every command and never captures artifacts.
+    #[serde(default = "default_containers_enabled")]
+    pub enabled: bool,
+
+    /// Idle time after which an in-memory container session is torn
+    /// down. Sessions are response-scoped, so this only kicks in if a
+    /// response stalls without terminating. Default 1200 (20m,
+    /// matching OpenAI's hosted-container idle TTL).
+    #[serde(default = "default_containers_idle_ttl_secs")]
+    pub default_idle_ttl_secs: u64,
+
+    /// Hard cap on `expires_after.minutes` per request and on
+    /// `POST /v1/containers` creation. Requests above this cap reject
+    /// with 400. Default 86_400 (60 days), matching OpenAI's
+    /// hosted-container maximum.
+    #[serde(default = "default_containers_max_idle_ttl_secs")]
+    pub max_idle_ttl_secs: u64,
+
+    /// Hard cap on the number of new/changed files captured per shell
+    /// exec. Excess files are dropped with a warning. Default 64.
+    #[serde(default = "default_containers_max_files_per_exec")]
+    pub max_files_per_exec: usize,
+
+    /// Hard cap on the size of any single captured file. Files larger
+    /// than this are recorded as metadata only (bytes + filename) with
+    /// no content stored. Default 25 MiB.
+    #[serde(default = "default_containers_max_bytes_per_file")]
+    pub max_bytes_per_file: u64,
+
+    /// Hard cap on the total bytes captured across all files in one
+    /// container session. Default 250 MiB.
+    #[serde(default = "default_containers_max_bytes_per_session")]
+    pub max_bytes_per_session: u64,
+
+    /// Hard cap on the number of `input_file` parts Hadrian will
+    /// materialize into `/mnt/data` for one request. Excess parts
+    /// cause the request to fail with a 400. Default 32.
+    #[serde(default = "default_containers_max_input_files_per_request")]
+    pub max_input_files_per_request: usize,
+
+    /// Hard cap on the total bytes across all staged input files in
+    /// one request. Default 100 MiB.
+    #[serde(default = "default_containers_max_input_bytes_per_request")]
+    pub max_input_bytes_per_request: u64,
+}
+
+impl Default for ContainersConfig {
+    fn default() -> Self {
+        Self {
+            enabled: default_containers_enabled(),
+            default_idle_ttl_secs: default_containers_idle_ttl_secs(),
+            max_idle_ttl_secs: default_containers_max_idle_ttl_secs(),
+            max_files_per_exec: default_containers_max_files_per_exec(),
+            max_bytes_per_file: default_containers_max_bytes_per_file(),
+            max_bytes_per_session: default_containers_max_bytes_per_session(),
+            max_input_files_per_request: default_containers_max_input_files_per_request(),
+            max_input_bytes_per_request: default_containers_max_input_bytes_per_request(),
+        }
+    }
+}
+
+impl ContainersConfig {
+    pub fn validate(&self) -> Result<(), String> {
+        // The reaper derives its poll interval from `default_idle_ttl_secs`,
+        // and both TTLs gate session/expiry math — a zero would expire
+        // sessions instantly and make the caps meaningless.
+        if self.default_idle_ttl_secs == 0 {
+            return Err("[features.containers] default_idle_ttl_secs must be > 0".into());
+        }
+        if self.max_idle_ttl_secs == 0 {
+            return Err("[features.containers] max_idle_ttl_secs must be > 0".into());
+        }
+        if self.default_idle_ttl_secs > self.max_idle_ttl_secs {
+            return Err(
+                "[features.containers] default_idle_ttl_secs must not exceed max_idle_ttl_secs"
+                    .into(),
+            );
+        }
         Ok(())
     }
 }
 
+fn default_containers_enabled() -> bool {
+    true
+}
+
+fn default_containers_idle_ttl_secs() -> u64 {
+    1200
+}
+
+fn default_containers_max_idle_ttl_secs() -> u64 {
+    // 60 days, matching OpenAI's published hosted-container cap.
+    60 * 24 * 60 * 60
+}
+
+fn default_containers_max_files_per_exec() -> usize {
+    64
+}
+
+fn default_containers_max_bytes_per_file() -> u64 {
+    25 * 1024 * 1024
+}
+
+fn default_containers_max_bytes_per_session() -> u64 {
+    250 * 1024 * 1024
+}
+
+fn default_containers_max_input_files_per_request() -> usize {
+    32
+}
+
+fn default_containers_max_input_bytes_per_request() -> u64 {
+    100 * 1024 * 1024
+}
+
+/// Cost rates for billable server-tool runtimes.
+///
+/// Rates are in **microcents per second** (1/1,000,000 of a dollar per
+/// second, matching the precision used elsewhere in `pricing::PricingConfig`).
+/// Total cost per shell call is `runtime_seconds * rate`.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ServerToolsPricingConfig {
+    /// Microcents per second of microsandbox VM wall-clock time.
+    /// Default 0 (no charge until operator sets a rate).
+    #[serde(default)]
+    pub microsandbox_microcents_per_second: u64,
+}
+
 /// Embedding configuration.
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
@@ -2541,6 +3444,114 @@ fn default_cleanup_max_duration_secs() -> u64 {
     60
 }
 
+/// Configuration for the container cleanup job.
+///
+/// Containers move `active` → `expired` (idle reaper) → `deleted` (explicit
+/// `DELETE /v1/containers/{id}`). Both terminal states stamp `expires_at` with
+/// the transition time but never remove the row, so without this job `expired`
+/// / `deleted` rows (and their `container_files`) accumulate forever. This
+/// worker hard-deletes terminal rows whose `expires_at` is older than
+/// `cleanup_delay_secs`, cascading their files.
+///
+/// # Example Configuration
+///
+/// ```toml
+/// [features.containers_cleanup]
+/// enabled = true
+/// interval_secs = 300
+/// cleanup_delay_secs = 3600
+/// batch_size = 100
+/// max_duration_secs = 60
+/// ```
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct ContainersCleanupConfig {
+    /// Enable the cleanup job.
+    /// When disabled, terminal containers remain in the database indefinitely.
+    #[serde(default)]
+    pub enabled: bool,
+
+    /// How often to run the cleanup job (in seconds).
+    /// Default: 300 (5 minutes)
+    #[serde(default = "default_cleanup_interval_secs")]
+    pub interval_secs: u64,
+
+    /// Time to wait after a container becomes terminal (`expired` /
+    /// `deleted`) before hard deleting it (in seconds). Measured from
+    /// `expires_at`. Gives clients time to download captured files.
+    /// Default: 3600 (1 hour)
+    #[serde(default = "default_cleanup_delay_secs")]
+    pub cleanup_delay_secs: u64,
+
+    /// Maximum number of containers to hard-delete per run.
+    /// Prevents long-running cleanup operations.
+    /// Default: 100
+    #[serde(default = "default_cleanup_batch_size")]
+    pub batch_size: u32,
+
+    /// Maximum duration for a single cleanup run (in seconds).
+    /// If exceeded, cleanup stops gracefully and continues next run.
+    /// Set to 0 for unlimited.
+    /// Default: 60
+    #[serde(default = "default_cleanup_max_duration_secs")]
+    pub max_duration_secs: u64,
+
+    /// Dry run mode - log what would be deleted without actually deleting.
+    /// Useful for testing cleanup configuration.
+    /// Default: false
+    #[serde(default)]
+    pub dry_run: bool,
+}
+
+impl Default for ContainersCleanupConfig {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            interval_secs: default_cleanup_interval_secs(),
+            cleanup_delay_secs: default_cleanup_delay_secs(),
+            batch_size: default_cleanup_batch_size(),
+            max_duration_secs: default_cleanup_max_duration_secs(),
+            dry_run: false,
+        }
+    }
+}
+
+impl ContainersCleanupConfig {
+    /// Get the interval as a Duration.
+    pub fn interval(&self) -> std::time::Duration {
+        std::time::Duration::from_secs(self.interval_secs)
+    }
+
+    /// Get the cleanup delay as a Duration.
+    pub fn cleanup_delay(&self) -> std::time::Duration {
+        std::time::Duration::from_secs(self.cleanup_delay_secs)
+    }
+
+    /// Get the max duration as a Duration, or None if unlimited.
+    pub fn max_duration(&self) -> Option<std::time::Duration> {
+        if self.max_duration_secs == 0 {
+            None
+        } else {
+            Some(std::time::Duration::from_secs(self.max_duration_secs))
+        }
+    }
+
+    pub fn validate(&self) -> Result<(), String> {
+        // Only meaningful when enabled, but validate unconditionally so a
+        // misconfigured-but-disabled job surfaces the error if it's later
+        // turned on. A zero interval is a tight DB-hammering loop; a zero
+        // batch makes no progress.
+        if self.interval_secs == 0 {
+            return Err("[features.containers_cleanup] interval_secs must be > 0".into());
+        }
+        if self.batch_size == 0 {
+            return Err("[features.containers_cleanup] batch_size must be > 0".into());
+        }
+        Ok(())
+    }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Model Catalog
 // ─────────────────────────────────────────────────────────────────────────────
@@ -2655,6 +3666,35 @@ mod tests {
         assert_eq!(metric, DistanceMetric::Cosine);
     }
 
+    #[test]
+    fn mcp_config_default_includes_hybrid_tool_search() {
+        let cfg = McpConfig::default();
+        assert_eq!(cfg.tool_search.ranker, ToolSearchRankerKind::Hybrid);
+        assert_eq!(cfg.tool_search.max_results, 20);
+        assert_eq!(cfg.tool_search.rrf_k, 60);
+        assert!(cfg.tool_search.embedding.is_none());
+    }
+
+    #[test]
+    fn tool_search_config_parses_overrides() {
+        let cfg: McpConfig = toml::from_str(
+            r#"
+            enabled = true
+            mode = "hadrian_hosted"
+            [tool_search]
+            ranker = "lexical"
+            max_results = 5
+            score_threshold = 0.4
+            rrf_k = 30
+            "#,
+        )
+        .expect("parses");
+        assert_eq!(cfg.tool_search.ranker, ToolSearchRankerKind::Lexical);
+        assert_eq!(cfg.tool_search.max_results, 5);
+        assert_eq!(cfg.tool_search.score_threshold, 0.4);
+        assert_eq!(cfg.tool_search.rrf_k, 30);
+    }
+
     #[test]
     fn test_distance_metric_pgvector_ops_class() {
         assert_eq!(
@@ -3851,6 +4891,139 @@ mod tests {
         assert_eq!(config.vector_store_cleanup.max_duration_secs, 60);
     }
 
+    // ───────────────────────────────────────────────────────────────────────────
+    // Containers Cleanup Config Tests
+    // ───────────────────────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_containers_cleanup_config_defaults() {
+        let config: ContainersCleanupConfig = toml::from_str("").unwrap();
+
+        assert!(!config.enabled);
+        assert_eq!(config.interval_secs, 300);
+        assert_eq!(config.cleanup_delay_secs, 3600);
+        assert_eq!(config.batch_size, 100);
+        assert_eq!(config.max_duration_secs, 60);
+        assert!(!config.dry_run);
+    }
+
+    #[test]
+    fn test_zero_interval_configs_rejected() {
+        // Defaults validate.
+        assert!(ContainersCleanupConfig::default().validate().is_ok());
+        assert!(ContainersConfig::default().validate().is_ok());
+        assert!(McpConfig::default().validate().is_ok());
+
+        // A zero cleanup interval (tight DB-hammering loop) is rejected.
+        assert!(
+            ContainersCleanupConfig {
+                interval_secs: 0,
+                ..Default::default()
+            }
+            .validate()
+            .is_err()
+        );
+        // Zero container TTLs are rejected.
+        assert!(
+            ContainersConfig {
+                default_idle_ttl_secs: 0,
+                ..Default::default()
+            }
+            .validate()
+            .is_err()
+        );
+        // Zero MCP call timeout / tool-search cap are rejected.
+        assert!(
+            McpConfig {
+                call_timeout_secs: 0,
+                ..Default::default()
+            }
+            .validate()
+            .is_err()
+        );
+        assert!(
+            McpConfig {
+                tool_search: ToolSearchConfig {
+                    max_results: 0,
+                    ..Default::default()
+                },
+                ..Default::default()
+            }
+            .validate()
+            .is_err()
+        );
+    }
+
+    #[test]
+    fn test_containers_cleanup_config_custom_values() {
+        let config: ContainersCleanupConfig = toml::from_str(
+            r#"
+            enabled = true
+            interval_secs = 600
+            cleanup_delay_secs = 7200
+            batch_size = 50
+            max_duration_secs = 120
+            dry_run = true
+            "#,
+        )
+        .unwrap();
+
+        assert!(config.enabled);
+        assert_eq!(config.interval_secs, 600);
+        assert_eq!(config.cleanup_delay_secs, 7200);
+        assert_eq!(config.batch_size, 50);
+        assert_eq!(config.max_duration_secs, 120);
+        assert!(config.dry_run);
+    }
+
+    #[test]
+    fn test_containers_cleanup_config_durations() {
+        let config = ContainersCleanupConfig {
+            enabled: true,
+            interval_secs: 300,
+            cleanup_delay_secs: 3600,
+            batch_size: 100,
+            max_duration_secs: 60,
+            dry_run: false,
+        };
+
+        assert_eq!(config.interval(), std::time::Duration::from_secs(300));
+        assert_eq!(config.cleanup_delay(), std::time::Duration::from_secs(3600));
+        assert_eq!(
+            config.max_duration(),
+            Some(std::time::Duration::from_secs(60))
+        );
+    }
+
+    #[test]
+    fn test_containers_cleanup_config_unlimited_duration() {
+        let config = ContainersCleanupConfig {
+            max_duration_secs: 0,
+            ..Default::default()
+        };
+
+        assert!(config.max_duration().is_none());
+    }
+
+    #[test]
+    fn test_features_config_with_containers_cleanup() {
+        let config: FeaturesConfig = toml::from_str(
+            r#"
+            [containers_cleanup]
+            enabled = true
+            interval_secs = 180
+            cleanup_delay_secs = 1800
+            "#,
+        )
+        .unwrap();
+
+        assert!(config.containers_cleanup.enabled);
+        assert_eq!(config.containers_cleanup.interval_secs, 180);
+        assert_eq!(config.containers_cleanup.cleanup_delay_secs, 1800);
+        assert_eq!(config.containers_cleanup.batch_size, 100);
+        assert_eq!(config.containers_cleanup.max_duration_secs, 60);
+    }
+
     // ───────────────────────────────────────────────────────────────────────────
     // File Processing Config Tests
     // ───────────────────────────────────────────────────────────────────────────
diff --git a/src/config/mod.rs b/src/config/mod.rs
index d1bbb53..45b1dff 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -24,6 +24,7 @@ mod limits;
 mod observability;
 mod providers;
 mod retention;
+mod runtimes;
 mod secrets;
 mod server;
 pub mod sovereignty;
@@ -42,6 +43,7 @@ pub use limits::*;
 pub use observability::*;
 pub use providers::*;
 pub use retention::*;
+pub use runtimes::*;
 pub use secrets::*;
 use serde::{Deserialize, Serialize};
 pub use server::*;
@@ -190,12 +192,18 @@ impl GatewayConfig {
         self.cache.validate()?;
         self.auth.validate()?;
         self.providers.validate()?;
-        self.storage
-            .files
-            .validate()
-            .map_err(ConfigError::Validation)?;
+        self.storage.validate().map_err(ConfigError::Validation)?;
         self.features.validate().map_err(ConfigError::Validation)?;
 
+        // SSRF-validate the responses webhook URL with the server's
+        // loopback policy. Done here (not in features.validate) so the
+        // webhook config doesn't need to know about server.allow_*.
+        if let Some(ref webhook) = self.features.responses.webhook {
+            webhook
+                .validate(self.server.allow_loopback_urls)
+                .map_err(ConfigError::Validation)?;
+        }
+
         Ok(())
     }
 
@@ -275,6 +283,16 @@ fn check_disabled_features(raw: &toml::Value) -> Result<(), ConfigError> {
         check_secrets_feature(type_val, &mut issues);
     }
 
+    // Check shell runtime type
+    if let Some(type_val) = raw
+        .get("features")
+        .and_then(|v| v.get("shell"))
+        .and_then(|v| v.get("type"))
+        .and_then(|v| v.as_str())
+    {
+        check_shell_runtime_feature(type_val, &mut issues);
+    }
+
     // Check cache type
     if let Some(type_val) = raw
         .get("cache")
@@ -415,6 +433,24 @@ fn check_secrets_feature(type_val: &str, _issues: &mut Vec<(String, &str)>) {
     }
 }
 
+#[cfg(feature = "server")]
+fn check_shell_runtime_feature(type_val: &str, _issues: &mut Vec<(String, &str)>) {
+    match type_val {
+        #[cfg(not(feature = "runtime-microsandbox"))]
+        "microsandbox" => _issues.push((
+            "[features.shell] type 'microsandbox' requires the 'runtime-microsandbox' feature"
+                .into(),
+            "runtime-microsandbox",
+        )),
+        #[cfg(not(feature = "runtime-opensandbox"))]
+        "opensandbox" => _issues.push((
+            "[features.shell] type 'opensandbox' requires the 'runtime-opensandbox' feature".into(),
+            "runtime-opensandbox",
+        )),
+        _ => {}
+    }
+}
+
 #[cfg(feature = "server")]
 fn check_cache_feature(type_val: &str, _issues: &mut Vec<(String, &str)>) {
     match type_val {
diff --git a/src/config/runtimes.rs b/src/config/runtimes.rs
new file mode 100644
index 0000000..2dfc567
--- /dev/null
+++ b/src/config/runtimes.rs
@@ -0,0 +1,198 @@
+//! Shell tool runtime configuration.
+//!
+//! Mirrors the `SecretsConfig` pattern: an enum tagged by `type` selects
+//! which backend runs the model's `shell` tool calls. Backends behind
+//! cargo features are conditionally compiled in.
+
+use serde::{Deserialize, Serialize};
+
+/// Top-level configuration for the `shell` tool runtime.
+///
+/// Defaults to `None`, which disables the shell tool entirely (any
+/// shell tool definition in a request is ignored, same as if the
+/// feature were not configured).
+///
+/// # Examples
+///
+/// Pass-through to OpenAI (works with GPT-5.2+ that has built-in shell):
+///
+/// ```toml
+/// [features.shell]
+/// type = "passthrough_openai"
+/// ```
+///
+/// Client fulfills shell calls itself (provider-agnostic equivalent of
+/// OpenAI's "local shell" mode — works behind Anthropic, Bedrock,
+/// Vertex, etc. as well as OpenAI):
+///
+/// ```toml
+/// [features.shell]
+/// type = "client_passthrough"
+/// ```
+///
+/// Local microVM via microsandbox:
+///
+/// ```toml
+/// [features.shell]
+/// type = "microsandbox"
+/// endpoint = "http://localhost:5555"
+/// ```
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ShellRuntimeConfig {
+    /// Shell tool is not configured. Requests with shell tools fail
+    /// with a clear error so it's obvious the gateway isn't set up.
+    #[default]
+    None,
+
+    /// Forward `shell` tool specs to the upstream provider unchanged.
+    /// Only meaningful when the upstream is OpenAI (the model itself
+    /// runs the shell call in OpenAI's hosted container).
+    PassthroughOpenAI,
+
+    /// The API client fulfills shell calls itself — Hadrian validates
+    /// the request, keeps OpenAI's native `shell` spec intact, rewrites
+    /// it to a function tool for non-OpenAI providers, and skips
+    /// server-side execution. Wire format the client sees:
+    ///
+    /// - OpenAI: `shell_call` / `shell_call_output` (native).
+    /// - Anthropic / Bedrock / Vertex: `function_call` with
+    ///   `name="shell"` / `function_call_output` (because those
+    ///   providers have no native shell tool type).
+    ///
+    /// Equivalent to OpenAI's "local shell" mode but works behind any
+    /// supported provider.
+    ClientPassthrough,
+
+    /// Local microVMs via microsandbox
+    /// (<https://github.com/superradcompany/microsandbox>).
+    #[cfg(feature = "runtime-microsandbox")]
+    Microsandbox(MicrosandboxConfig),
+
+    /// Alibaba OpenSandbox Protocol over HTTP.
+    /// (<https://github.com/alibaba/OpenSandbox>)
+    #[cfg(feature = "runtime-opensandbox")]
+    OpenSandbox(OpenSandboxConfig),
+}
+
+impl ShellRuntimeConfig {
+    /// Whether any shell runtime is configured. When false the shell
+    /// tool is effectively disabled and the orchestrator skips
+    /// registering it.
+    pub fn is_enabled(&self) -> bool {
+        !matches!(self, Self::None)
+    }
+
+    /// Whether this mode keeps OpenAI's native `shell` tool spec intact
+    /// rather than rewriting it to a function tool. True for both
+    /// passthrough modes (the OpenAI hosted container and the API
+    /// client both want native `shell_call` items); false for the
+    /// Hadrian-hosted sandbox modes (those run the call themselves and
+    /// need the function-mode rewrite so the executor can intercept).
+    pub fn keeps_openai_native_shell(&self) -> bool {
+        matches!(self, Self::PassthroughOpenAI | Self::ClientPassthrough)
+    }
+
+    /// Human-readable name of the configured runtime, for logging.
+    pub fn name(&self) -> &'static str {
+        match self {
+            Self::None => "none",
+            Self::PassthroughOpenAI => "passthrough_openai",
+            Self::ClientPassthrough => "client_passthrough",
+            #[cfg(feature = "runtime-microsandbox")]
+            Self::Microsandbox(_) => "microsandbox",
+            #[cfg(feature = "runtime-opensandbox")]
+            Self::OpenSandbox(_) => "opensandbox",
+        }
+    }
+}
+
+/// Configuration for the microsandbox runtime.
+///
+/// Microsandbox is an in-process Rust SDK (no daemon, no endpoint) — Hadrian
+/// links it directly and constructs `Sandbox` instances per session.
+#[cfg(feature = "runtime-microsandbox")]
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct MicrosandboxConfig {
+    /// Container image to boot for each session. Default `alpine` — small and
+    /// fast to pull/boot as a microVM. The base image is minimal; agents are
+    /// told how to `apk add` toolchains via
+    /// `[features.server_tools.shell_limits].environment_description`. Use a
+    /// fatter image (e.g. `ghcr.io/openai/codex-universal`) if you'd rather
+    /// trade boot time for pre-installed toolchains — and update the
+    /// `environment_description` to match.
+    #[serde(default = "default_microsandbox_image")]
+    pub image: String,
+
+    /// vCPUs per session. Default 1. Range 1..=255; values above 255
+    /// are clamped at the SDK boundary.
+    #[serde(default = "default_microsandbox_cpus")]
+    pub cpus: u32,
+
+    /// Memory per session in MB. Default 512.
+    #[serde(default = "default_microsandbox_memory_mb")]
+    pub memory_mb: u32,
+}
+
+#[cfg(feature = "runtime-microsandbox")]
+fn default_microsandbox_image() -> String {
+    "alpine".to_string()
+}
+
+#[cfg(feature = "runtime-microsandbox")]
+fn default_microsandbox_cpus() -> u32 {
+    1
+}
+
+#[cfg(feature = "runtime-microsandbox")]
+fn default_microsandbox_memory_mb() -> u32 {
+    512
+}
+
+/// Configuration for the OpenSandbox runtime.
+#[cfg(feature = "runtime-opensandbox")]
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct OpenSandboxConfig {
+    /// HTTP endpoint of the OpenSandbox Lifecycle API (e.g.
+    /// `http://localhost:8080/v1`).
+    pub endpoint: String,
+
+    /// Optional API key sent in the `OPEN-SANDBOX-API-KEY` header.
+    #[serde(default)]
+    pub auth_token: Option<String>,
+
+    /// Container image used when starting a sandbox. Default
+    /// `python:3.11-slim`.
+    #[serde(default)]
+    pub default_image: Option<String>,
+
+    /// Maximum seconds to wait for a newly created sandbox to reach
+    /// `Running` state. Default 60.
+    #[serde(default = "default_opensandbox_start_timeout")]
+    pub start_timeout_secs: u64,
+
+    /// Wall-clock cap, in seconds, the OpenSandbox control plane is
+    /// asked to enforce on the sandbox lifecycle (`timeout` field on
+    /// `POST /sandboxes`). Independent of `idle_ttl_secs` (which is
+    /// Hadrian-side) and `command_timeout_secs` (per-exec). Default
+    /// 3600 (1h); set lower for cost containment, higher for long
+    /// agent sessions. Always at least `start_timeout_secs + 60` to
+    /// keep startup polling under the lifecycle deadline.
+    #[serde(default = "default_opensandbox_sandbox_timeout")]
+    pub sandbox_timeout_secs: u64,
+}
+
+#[cfg(feature = "runtime-opensandbox")]
+fn default_opensandbox_start_timeout() -> u64 {
+    60
+}
+
+#[cfg(feature = "runtime-opensandbox")]
+fn default_opensandbox_sandbox_timeout() -> u64 {
+    3_600
+}
diff --git a/src/config/storage.rs b/src/config/storage.rs
index c4e533b..d945ea2 100644
--- a/src/config/storage.rs
+++ b/src/config/storage.rs
@@ -28,9 +28,36 @@ use serde::{Deserialize, Serialize};
 #[cfg_attr(feature = "json-schema", derive(schemars::JsonSchema))]
 #[serde(deny_unknown_fields)]
 pub struct StorageConfig {
-    /// File storage configuration.
+    /// Storage for the Files API (`/v1/files`) — the same resource that
+    /// backs Knowledge Bases and Responses-API `input_file` references.
     #[serde(default)]
     pub files: FileStorageConfig,
+
+    /// Storage for container output files — artifacts the agentic shell
+    /// tool captures under `/mnt/data` and serves from
+    /// `/v1/containers/{id}/files/{id}/content`.
+    ///
+    /// Defaults to the `database` backend (bytes inline in
+    /// `container_files.file_data`), which is simple but scales poorly for
+    /// large or numerous artifacts. Point it at `filesystem` or `s3` to
+    /// offload the bytes. Independent from `[storage.files]` so operators
+    /// can keep small uploaded files in the DB while routing bulky
+    /// agent-generated artifacts to object storage.
+    #[serde(default)]
+    pub container_files: FileStorageConfig,
+}
+
+impl StorageConfig {
+    /// Validate every configured storage target.
+    pub fn validate(&self) -> Result<(), String> {
+        self.files
+            .validate()
+            .map_err(|e| format!("[storage.files]: {e}"))?;
+        self.container_files
+            .validate()
+            .map_err(|e| format!("[storage.container_files]: {e}"))?;
+        Ok(())
+    }
 }
 
 /// File storage backend configuration for the Files API.
@@ -302,6 +329,83 @@ mod tests {
         assert!(matches!(config.files.backend, FileStorageBackend::Database));
         assert!(config.files.s3.is_none());
         assert!(config.files.filesystem.is_none());
+        // container_files defaults to the database backend too, preserving
+        // the historical "bytes inline in container_files.file_data" behavior.
+        assert!(matches!(
+            config.container_files.backend,
+            FileStorageBackend::Database
+        ));
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn test_container_files_independent_of_files() {
+        // Files API in the DB, container artifacts offloaded to S3.
+        let config: StorageConfig = toml::from_str(
+            r#"
+            [files]
+            backend = "database"
+
+            [container_files]
+            backend = "s3"
+
+            [container_files.s3]
+            bucket = "hadrian-container-artifacts"
+            region = "us-east-1"
+            key_prefix = "containers/"
+            "#,
+        )
+        .unwrap();
+
+        assert!(matches!(config.files.backend, FileStorageBackend::Database));
+        assert!(matches!(
+            config.container_files.backend,
+            FileStorageBackend::S3
+        ));
+        assert_eq!(
+            config.container_files.s3.as_ref().unwrap().bucket,
+            "hadrian-container-artifacts"
+        );
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn test_container_files_filesystem_backend() {
+        let config: StorageConfig = toml::from_str(
+            r#"
+            [container_files]
+            backend = "filesystem"
+
+            [container_files.filesystem]
+            path = "/var/hadrian/container-files"
+            "#,
+        )
+        .unwrap();
+
+        assert!(matches!(
+            config.container_files.backend,
+            FileStorageBackend::Filesystem
+        ));
+        assert_eq!(
+            config.container_files.filesystem.as_ref().unwrap().path,
+            "/var/hadrian/container-files"
+        );
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn test_storage_validate_surfaces_section() {
+        // A misconfigured container_files section must name itself in the error.
+        let config: StorageConfig = toml::from_str(
+            r#"
+            [container_files]
+            backend = "filesystem"
+            "#,
+        )
+        .unwrap();
+
+        let err = config.validate().unwrap_err();
+        assert!(err.contains("[storage.container_files]"), "got: {err}");
     }
 
     #[test]
diff --git a/src/config/ui.rs b/src/config/ui.rs
index 45cf8a5..af42372 100644
--- a/src/config/ui.rs
+++ b/src/config/ui.rs
@@ -523,6 +523,8 @@ pub struct PagesConfig {
     #[serde(default)]
     pub knowledge_bases: PageConfig,
     #[serde(default)]
+    pub containers: PageConfig,
+    #[serde(default)]
     pub api_keys: PageConfig,
     #[serde(default)]
     pub providers: PageConfig,
diff --git a/src/db/mod.rs b/src/db/mod.rs
index b13bb01..f7aa55a 100644
--- a/src/db/mod.rs
+++ b/src/db/mod.rs
@@ -74,6 +74,16 @@ struct CachedRepos {
     service_accounts: Arc<dyn ServiceAccountRepo>,
     // OAuth PKCE authorization codes
     oauth_authorization_codes: Arc<dyn OAuthAuthorizationCodeRepo>,
+    // Persisted Responses API records
+    responses: Arc<dyn ResponsesRepo>,
+    // Per-response event log
+    response_events: Arc<dyn ResponseEventsRepo>,
+    // Containers + container_files (shell-tool /mnt/data artifacts)
+    containers: Arc<dyn ContainersRepo>,
+    // Parked MCP tool calls waiting on `mcp_approval_response`. Only
+    // present when the `mcp` cargo feature is enabled.
+    #[cfg(feature = "mcp")]
+    mcp_pending_approvals: Arc<dyn McpPendingApprovalsRepo>,
 }
 
 enum PoolStorage {
@@ -153,6 +163,13 @@ impl DbPool {
             oauth_authorization_codes: Arc::new(sqlite::SqliteOAuthAuthorizationCodeRepo::new(
                 pool.clone(),
             )),
+            responses: Arc::new(sqlite::SqliteResponsesRepo::new(pool.clone())),
+            response_events: Arc::new(sqlite::SqliteResponseEventsRepo::new(pool.clone())),
+            containers: Arc::new(sqlite::SqliteContainersRepo::new(pool.clone())),
+            #[cfg(feature = "mcp")]
+            mcp_pending_approvals: Arc::new(sqlite::SqliteMcpPendingApprovalsRepo::new(
+                pool.clone(),
+            )),
         };
         DbPool {
             inner: PoolStorage::Sqlite(pool),
@@ -195,6 +212,13 @@ impl DbPool {
             oauth_authorization_codes: Arc::new(sqlite::SqliteOAuthAuthorizationCodeRepo::new(
                 pool.clone(),
             )),
+            responses: Arc::new(sqlite::SqliteResponsesRepo::new(pool.clone())),
+            response_events: Arc::new(sqlite::SqliteResponseEventsRepo::new(pool.clone())),
+            containers: Arc::new(sqlite::SqliteContainersRepo::new(pool.clone())),
+            #[cfg(feature = "mcp")]
+            mcp_pending_approvals: Arc::new(sqlite::SqliteMcpPendingApprovalsRepo::new(
+                pool.clone(),
+            )),
         };
         DbPool {
             inner: PoolStorage::WasmSqlite(pool),
@@ -305,6 +329,22 @@ impl DbPool {
                 write_pool.clone(),
                 read_pool.clone(),
             )),
+            responses: Arc::new(postgres::PostgresResponsesRepo::new(
+                write_pool.clone(),
+                read_pool.clone(),
+            )),
+            response_events: Arc::new(postgres::PostgresResponseEventsRepo::new(
+                write_pool.clone(),
+                read_pool.clone(),
+            )),
+            containers: Arc::new(postgres::PostgresContainersRepo::new(
+                write_pool.clone(),
+                read_pool.clone(),
+            )),
+            #[cfg(feature = "mcp")]
+            mcp_pending_approvals: Arc::new(postgres::PostgresMcpPendingApprovalsRepo::new(
+                write_pool.clone(),
+            )),
         };
         DbPool {
             inner: PoolStorage::Postgres(PgPoolPair {
@@ -384,6 +424,13 @@ impl DbPool {
                     oauth_authorization_codes: Arc::new(
                         sqlite::SqliteOAuthAuthorizationCodeRepo::new(pool.clone()),
                     ),
+                    responses: Arc::new(sqlite::SqliteResponsesRepo::new(pool.clone())),
+                    response_events: Arc::new(sqlite::SqliteResponseEventsRepo::new(pool.clone())),
+                    containers: Arc::new(sqlite::SqliteContainersRepo::new(pool.clone())),
+                    #[cfg(feature = "mcp")]
+                    mcp_pending_approvals: Arc::new(sqlite::SqliteMcpPendingApprovalsRepo::new(
+                        pool.clone(),
+                    )),
                 };
 
                 Ok(DbPool {
@@ -526,6 +573,22 @@ impl DbPool {
                             read_pool.clone(),
                         ),
                     ),
+                    responses: Arc::new(postgres::PostgresResponsesRepo::new(
+                        write_pool.clone(),
+                        read_pool.clone(),
+                    )),
+                    response_events: Arc::new(postgres::PostgresResponseEventsRepo::new(
+                        write_pool.clone(),
+                        read_pool.clone(),
+                    )),
+                    containers: Arc::new(postgres::PostgresContainersRepo::new(
+                        write_pool.clone(),
+                        read_pool.clone(),
+                    )),
+                    #[cfg(feature = "mcp")]
+                    mcp_pending_approvals: Arc::new(
+                        postgres::PostgresMcpPendingApprovalsRepo::new(write_pool.clone()),
+                    ),
                 };
 
                 Ok(DbPool {
@@ -696,6 +759,29 @@ impl DbPool {
         Arc::clone(&self.repos.oauth_authorization_codes)
     }
 
+    /// Get persisted Responses API record repository.
+    pub fn responses(&self) -> Arc<dyn ResponsesRepo> {
+        Arc::clone(&self.repos.responses)
+    }
+
+    /// Get the response event log repository.
+    pub fn response_events(&self) -> Arc<dyn ResponseEventsRepo> {
+        Arc::clone(&self.repos.response_events)
+    }
+
+    /// Get the containers + container_files repository.
+    pub fn containers(&self) -> Arc<dyn ContainersRepo> {
+        Arc::clone(&self.repos.containers)
+    }
+
+    /// Get the MCP pending-approvals repository. Used by the
+    /// `McpExecutor` to park gated calls and by the routes layer to
+    /// resume them.
+    #[cfg(feature = "mcp")]
+    pub fn mcp_pending_approvals(&self) -> Arc<dyn McpPendingApprovalsRepo> {
+        Arc::clone(&self.repos.mcp_pending_approvals)
+    }
+
     /// Get a reference to the underlying database pool.
     /// Useful for database-specific operations that need direct pool access.
     pub fn pool(&self) -> DbPoolRef<'_> {
diff --git a/src/db/postgres/containers.rs b/src/db/postgres/containers.rs
new file mode 100644
index 0000000..59c2337
--- /dev/null
+++ b/src/db/postgres/containers.rs
@@ -0,0 +1,477 @@
+//! Postgres implementation of [`ContainersRepo`].
+
+use async_trait::async_trait;
+use sqlx::{PgPool, Row};
+use uuid::Uuid;
+
+use crate::db::{
+    error::{DbError, DbResult},
+    repos::{
+        ContainerFileRecord, ContainerFileSourceKind, ContainerPatch, ContainerRecord,
+        ContainerStatus, ContainersRepo, DeletedFileObject, HardDeleteExpiredOutcome, NewContainer,
+        NewContainerFile, ResponseOwnerType,
+    },
+};
+
+const CONTAINER_COLUMNS: &str = "id, org_id, owner_type::TEXT, owner_id, status, runtime_label, \
+    source_response_id, idle_ttl_secs, last_active_at, created_at, expires_at, \
+    name, memory_limit_mb, network_policy_json, skill_ids_json";
+
+const CONTAINER_FILE_COLUMNS: &str = "id, container_id, org_id, path, filename, size_bytes, \
+    content_type, content_hash, source, storage_backend::TEXT, storage_path, \
+    source_response_id, source_call_id, created_at";
+
+pub struct PostgresContainersRepo {
+    write_pool: PgPool,
+    read_pool: PgPool,
+}
+
+impl PostgresContainersRepo {
+    pub fn new(write_pool: PgPool, read_pool: Option<PgPool>) -> Self {
+        let read_pool = read_pool.unwrap_or_else(|| write_pool.clone());
+        Self {
+            write_pool,
+            read_pool,
+        }
+    }
+}
+
+fn parse_status(s: &str) -> DbResult<ContainerStatus> {
+    ContainerStatus::parse(s)
+        .ok_or_else(|| DbError::Internal(format!("unknown container status: {s}")))
+}
+
+fn parse_owner_type(s: &str) -> DbResult<ResponseOwnerType> {
+    ResponseOwnerType::parse(s)
+        .ok_or_else(|| DbError::Internal(format!("unknown container owner_type: {s}")))
+}
+
+fn parse_source(s: &str) -> DbResult<ContainerFileSourceKind> {
+    ContainerFileSourceKind::parse(s)
+        .ok_or_else(|| DbError::Internal(format!("unknown container_file source: {s}")))
+}
+
+fn parse_storage_backend(s: &str) -> DbResult<crate::models::StorageBackend> {
+    s.parse::<crate::models::StorageBackend>()
+        .map_err(DbError::Internal)
+}
+
+fn row_to_container(row: &sqlx::postgres::PgRow) -> DbResult<ContainerRecord> {
+    Ok(ContainerRecord {
+        id: row.get("id"),
+        org_id: row.get("org_id"),
+        owner_type: parse_owner_type(&row.get::<String, _>("owner_type"))?,
+        owner_id: row.get("owner_id"),
+        status: parse_status(&row.get::<String, _>("status"))?,
+        runtime_label: row.get("runtime_label"),
+        source_response_id: row.get("source_response_id"),
+        idle_ttl_secs: row.get("idle_ttl_secs"),
+        last_active_at: row.get("last_active_at"),
+        created_at: row.get("created_at"),
+        expires_at: row.get("expires_at"),
+        name: row.get("name"),
+        memory_limit_mb: row.get::<Option<i32>, _>("memory_limit_mb").map(i64::from),
+        network_policy_json: row.get("network_policy_json"),
+        skill_ids_json: row.get("skill_ids_json"),
+    })
+}
+
+fn row_to_file(row: &sqlx::postgres::PgRow) -> DbResult<ContainerFileRecord> {
+    Ok(ContainerFileRecord {
+        id: row.get("id"),
+        container_id: row.get("container_id"),
+        org_id: row.get("org_id"),
+        path: row.get("path"),
+        filename: row.get("filename"),
+        size_bytes: row.get("size_bytes"),
+        content_type: row.get("content_type"),
+        content_hash: row.get("content_hash"),
+        source: parse_source(&row.get::<String, _>("source"))?,
+        storage_backend: parse_storage_backend(&row.get::<String, _>("storage_backend"))?,
+        storage_path: row.get("storage_path"),
+        source_response_id: row.get("source_response_id"),
+        source_call_id: row.get("source_call_id"),
+        created_at: row.get("created_at"),
+    })
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+impl ContainersRepo for PostgresContainersRepo {
+    async fn insert(&self, input: NewContainer) -> DbResult<ContainerRecord> {
+        // Both timestamps land at insert time. last_active_at == created_at.
+        let sql = format!(
+            r#"
+            INSERT INTO containers (
+                id, org_id, owner_type, owner_id, status, runtime_label,
+                source_response_id, idle_ttl_secs, last_active_at, created_at,
+                name, memory_limit_mb, network_policy_json, skill_ids_json
+            )
+            VALUES ($1, $2, $3::response_owner_type, $4, $5, $6, $7, $8, $9, $9, $10, $11, $12, $13)
+            RETURNING {CONTAINER_COLUMNS}
+            "#
+        );
+        let row = sqlx::query(&sql)
+            .bind(&input.id)
+            .bind(input.org_id)
+            .bind(input.owner_type.as_str())
+            .bind(input.owner_id)
+            .bind(input.status.as_str())
+            .bind(&input.runtime_label)
+            .bind(&input.source_response_id)
+            .bind(input.idle_ttl_secs)
+            .bind(input.created_at)
+            .bind(&input.name)
+            .bind(input.memory_limit_mb.map(|m| m as i32))
+            .bind(&input.network_policy_json)
+            .bind(&input.skill_ids_json)
+            .fetch_one(&self.write_pool)
+            .await?;
+        row_to_container(&row)
+    }
+
+    async fn get_by_id_and_org(&self, id: &str, org_id: Uuid) -> DbResult<Option<ContainerRecord>> {
+        let sql =
+            format!("SELECT {CONTAINER_COLUMNS} FROM containers WHERE id = $1 AND org_id = $2");
+        let row = sqlx::query(&sql)
+            .bind(id)
+            .bind(org_id)
+            .fetch_optional(&self.read_pool)
+            .await?;
+        row.map(|r| row_to_container(&r)).transpose()
+    }
+
+    async fn list_by_org(
+        &self,
+        org_id: Uuid,
+        limit: i64,
+        after: Option<&str>,
+    ) -> DbResult<Vec<ContainerRecord>> {
+        // Keyset cursor: resolve `after` (an opaque cntr_… id) into a
+        // `(created_at, id)` pair via a correlated subquery scoped to
+        // the same org. Cross-org ids fall through to `NULL` rows from
+        // the subquery and the comparison shorts to NULL (no match), so
+        // the caller can't enumerate other orgs by guessing ids.
+        let sql = format!(
+            r#"
+            SELECT {CONTAINER_COLUMNS} FROM containers
+            WHERE org_id = $1
+              AND (
+                $2::TEXT IS NULL
+                OR (created_at, id) < (
+                  SELECT created_at, id FROM containers
+                  WHERE id = $2 AND org_id = $1
+                )
+              )
+            ORDER BY created_at DESC, id DESC
+            LIMIT $3
+            "#
+        );
+        let rows = sqlx::query(&sql)
+            .bind(org_id)
+            .bind(after)
+            .bind(limit)
+            .fetch_all(&self.read_pool)
+            .await?;
+        rows.iter().map(row_to_container).collect()
+    }
+
+    async fn upsert_file(&self, input: NewContainerFile) -> DbResult<ContainerFileRecord> {
+        // ON CONFLICT keeps the original row's id stable so any
+        // annotation that already cited the prior version still
+        // resolves to the latest bytes.
+        let sql = format!(
+            r#"
+            INSERT INTO container_files (
+                id, container_id, org_id, path, filename, size_bytes,
+                content_type, content_hash, source, storage_backend,
+                file_data, storage_path, source_response_id, source_call_id, created_at
+            )
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10::file_storage_backend, $11, $12, $13, $14, $15)
+            ON CONFLICT (container_id, path) DO UPDATE SET
+                filename = EXCLUDED.filename,
+                size_bytes = EXCLUDED.size_bytes,
+                content_type = EXCLUDED.content_type,
+                content_hash = EXCLUDED.content_hash,
+                source = EXCLUDED.source,
+                storage_backend = EXCLUDED.storage_backend,
+                file_data = EXCLUDED.file_data,
+                storage_path = EXCLUDED.storage_path,
+                source_response_id = EXCLUDED.source_response_id,
+                source_call_id = EXCLUDED.source_call_id,
+                created_at = EXCLUDED.created_at
+            RETURNING {CONTAINER_FILE_COLUMNS}
+            "#
+        );
+        let row = sqlx::query(&sql)
+            .bind(&input.id)
+            .bind(&input.container_id)
+            .bind(input.org_id)
+            .bind(&input.path)
+            .bind(&input.filename)
+            .bind(input.size_bytes)
+            .bind(&input.content_type)
+            .bind(&input.content_hash)
+            .bind(input.source.as_str())
+            .bind(input.storage_backend.as_str())
+            .bind(&input.file_data)
+            .bind(&input.storage_path)
+            .bind(&input.source_response_id)
+            .bind(&input.source_call_id)
+            .bind(input.created_at)
+            .fetch_one(&self.write_pool)
+            .await?;
+        row_to_file(&row)
+    }
+
+    async fn get_file_by_id_and_org(
+        &self,
+        file_id: &str,
+        org_id: Uuid,
+    ) -> DbResult<Option<ContainerFileRecord>> {
+        let sql = format!(
+            "SELECT {CONTAINER_FILE_COLUMNS} FROM container_files \
+             WHERE id = $1 AND org_id = $2"
+        );
+        let row = sqlx::query(&sql)
+            .bind(file_id)
+            .bind(org_id)
+            .fetch_optional(&self.read_pool)
+            .await?;
+        row.map(|r| row_to_file(&r)).transpose()
+    }
+
+    async fn read_file_data(&self, file_id: &str, org_id: Uuid) -> DbResult<Option<Vec<u8>>> {
+        let row = sqlx::query(
+            r#"
+            SELECT file_data FROM container_files
+            WHERE id = $1 AND org_id = $2
+            "#,
+        )
+        .bind(file_id)
+        .bind(org_id)
+        .fetch_optional(&self.read_pool)
+        .await?;
+        Ok(row.and_then(|r| r.get::<Option<Vec<u8>>, _>("file_data")))
+    }
+
+    async fn list_files_by_container(
+        &self,
+        container_id: &str,
+        org_id: Uuid,
+        limit: i64,
+    ) -> DbResult<Vec<ContainerFileRecord>> {
+        let clamped = limit.clamp(1, 1000);
+        let sql = format!(
+            "SELECT {CONTAINER_FILE_COLUMNS} FROM container_files \
+             WHERE container_id = $1 AND org_id = $2 \
+             ORDER BY created_at DESC, id DESC \
+             LIMIT $3"
+        );
+        let rows = sqlx::query(&sql)
+            .bind(container_id)
+            .bind(org_id)
+            .bind(clamped)
+            .fetch_all(&self.read_pool)
+            .await?;
+        rows.iter().map(row_to_file).collect()
+    }
+
+    async fn list_files_for_replay(
+        &self,
+        container_id: &str,
+    ) -> DbResult<Vec<ContainerFileRecord>> {
+        let sql = format!(
+            "SELECT {CONTAINER_FILE_COLUMNS} FROM container_files \
+             WHERE container_id = $1 \
+             ORDER BY created_at DESC, id DESC"
+        );
+        let rows = sqlx::query(&sql)
+            .bind(container_id)
+            .fetch_all(&self.read_pool)
+            .await?;
+        rows.iter().map(row_to_file).collect()
+    }
+
+    async fn read_file_data_for_replay(
+        &self,
+        container_id: &str,
+        file_id: &str,
+    ) -> DbResult<Option<Vec<u8>>> {
+        let row = sqlx::query(
+            r#"
+            SELECT file_data FROM container_files
+            WHERE container_id = $1 AND id = $2
+            "#,
+        )
+        .bind(container_id)
+        .bind(file_id)
+        .fetch_optional(&self.read_pool)
+        .await?;
+        Ok(row.and_then(|r| r.get::<Option<Vec<u8>>, _>("file_data")))
+    }
+
+    async fn update_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ContainerPatch,
+    ) -> DbResult<Option<ContainerRecord>> {
+        let mut setters: Vec<String> = Vec::new();
+        let mut idx = 3usize; // $1 = id, $2 = org_id
+        if patch.status.is_some() {
+            setters.push(format!("status = ${idx}"));
+            idx += 1;
+        }
+        if patch.last_active_at.is_some() {
+            setters.push(format!("last_active_at = ${idx}"));
+            idx += 1;
+        }
+        if patch.expires_at.is_some() {
+            setters.push(format!("expires_at = ${idx}"));
+        }
+        if setters.is_empty() {
+            return self.get_by_id_and_org(id, org_id).await;
+        }
+        let sql = format!(
+            "UPDATE containers SET {set} WHERE id = $1 AND org_id = $2 \
+             RETURNING {CONTAINER_COLUMNS}",
+            set = setters.join(", "),
+        );
+        let mut q = sqlx::query(&sql).bind(id).bind(org_id);
+        if let Some(s) = patch.status {
+            q = q.bind(s.as_str());
+        }
+        if let Some(ts) = patch.last_active_at {
+            q = q.bind(ts);
+        }
+        if let Some(ts) = patch.expires_at {
+            q = q.bind(ts);
+        }
+        let row = q.fetch_optional(&self.write_pool).await?;
+        row.as_ref().map(row_to_container).transpose()
+    }
+
+    async fn delete_file_by_id_and_org(
+        &self,
+        file_id: &str,
+        container_id: &str,
+        org_id: Uuid,
+    ) -> DbResult<bool> {
+        let res = sqlx::query(
+            r#"
+            DELETE FROM container_files
+            WHERE id = $1 AND container_id = $2 AND org_id = $3
+            "#,
+        )
+        .bind(file_id)
+        .bind(container_id)
+        .bind(org_id)
+        .execute(&self.write_pool)
+        .await?;
+        Ok(res.rows_affected() > 0)
+    }
+
+    async fn mark_expired_idle(&self, now: chrono::DateTime<chrono::Utc>) -> DbResult<Vec<String>> {
+        let rows = sqlx::query(
+            r#"
+            UPDATE containers
+            SET status = 'expired', expires_at = $1
+            WHERE status = 'active'
+              AND last_active_at + (idle_ttl_secs || ' seconds')::interval < $1
+            RETURNING id
+            "#,
+        )
+        .bind(now)
+        .fetch_all(&self.write_pool)
+        .await?;
+        Ok(rows.iter().map(|r| r.get::<String, _>("id")).collect())
+    }
+
+    async fn expired_among(&self, ids: &[String]) -> DbResult<Vec<String>> {
+        if ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        let rows = sqlx::query(
+            r#"
+            SELECT id FROM containers
+            WHERE status IN ('expired', 'deleted')
+              AND id = ANY($1)
+            "#,
+        )
+        .bind(ids)
+        .fetch_all(&self.read_pool)
+        .await?;
+        Ok(rows.iter().map(|r| r.get::<String, _>("id")).collect())
+    }
+
+    async fn hard_delete_expired(
+        &self,
+        cutoff: chrono::DateTime<chrono::Utc>,
+        limit: i64,
+    ) -> DbResult<HardDeleteExpiredOutcome> {
+        // `expires_at` is the transition timestamp (stamped when the row left
+        // `active`), so the retention delay is measured from when it became
+        // terminal. The `LIMIT` caps how many rows one pass removes. We do
+        // the whole thing in a transaction so the captured file-storage refs
+        // and the row deletions are atomic: select victims, capture their
+        // files' external-storage refs, then delete the containers (the
+        // `ON DELETE CASCADE` drops `container_files` with them).
+        let mut tx = self.write_pool.begin().await?;
+        let victim_rows = sqlx::query(
+            r#"
+            SELECT id FROM containers
+            WHERE status IN ('expired', 'deleted')
+              AND expires_at IS NOT NULL
+              AND expires_at <= $1
+            -- Oldest-expired first: a full backlog must not starve the
+            -- earliest terminal rows by repeatedly deleting the newest.
+            ORDER BY expires_at ASC
+            LIMIT $2
+            FOR UPDATE SKIP LOCKED
+            "#,
+        )
+        .bind(cutoff)
+        .bind(limit)
+        .fetch_all(&mut *tx)
+        .await?;
+        let ids: Vec<String> = victim_rows
+            .iter()
+            .map(|r| r.get::<String, _>("id"))
+            .collect();
+        if ids.is_empty() {
+            tx.commit().await?;
+            return Ok(HardDeleteExpiredOutcome::default());
+        }
+
+        let file_rows = sqlx::query(
+            r#"
+            SELECT id, storage_backend::TEXT AS storage_backend, storage_path
+            FROM container_files
+            WHERE container_id = ANY($1)
+            "#,
+        )
+        .bind(&ids)
+        .fetch_all(&mut *tx)
+        .await?;
+        let mut file_objects = Vec::with_capacity(file_rows.len());
+        for r in &file_rows {
+            file_objects.push(DeletedFileObject {
+                file_id: r.get::<String, _>("id"),
+                storage_backend: parse_storage_backend(&r.get::<String, _>("storage_backend"))?,
+                storage_path: r.get::<Option<String>, _>("storage_path"),
+            });
+        }
+
+        sqlx::query("DELETE FROM containers WHERE id = ANY($1)")
+            .bind(&ids)
+            .execute(&mut *tx)
+            .await?;
+        tx.commit().await?;
+
+        Ok(HardDeleteExpiredOutcome {
+            container_ids: ids,
+            file_objects,
+        })
+    }
+}
diff --git a/src/db/postgres/mcp_pending_approvals.rs b/src/db/postgres/mcp_pending_approvals.rs
new file mode 100644
index 0000000..45a9797
--- /dev/null
+++ b/src/db/postgres/mcp_pending_approvals.rs
@@ -0,0 +1,107 @@
+//! Postgres implementation of [`McpPendingApprovalsRepo`].
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use sqlx::{PgPool, Row};
+use uuid::Uuid;
+
+use crate::db::{
+    error::DbResult,
+    repos::{McpPendingApproval, McpPendingApprovalsRepo, NewMcpPendingApproval},
+};
+
+pub struct PostgresMcpPendingApprovalsRepo {
+    write_pool: PgPool,
+}
+
+impl PostgresMcpPendingApprovalsRepo {
+    /// This repo has no read-only queries (the lookup is a
+    /// `DELETE … RETURNING` claim that must hit the primary), so it only
+    /// needs the write pool — unlike sibling repos that take a replica
+    /// read pool.
+    pub fn new(write_pool: PgPool) -> Self {
+        Self { write_pool }
+    }
+}
+
+#[async_trait]
+impl McpPendingApprovalsRepo for PostgresMcpPendingApprovalsRepo {
+    async fn insert(&self, row: NewMcpPendingApproval) -> DbResult<()> {
+        sqlx::query(
+            r#"
+            INSERT INTO mcp_pending_approvals (
+                id, response_id, org_id, call_id,
+                server_label, server_url, tool_name,
+                arguments_json, created_at, expires_at
+            )
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+            "#,
+        )
+        .bind(&row.id)
+        .bind(&row.response_id)
+        .bind(row.org_id)
+        .bind(&row.call_id)
+        .bind(&row.server_label)
+        .bind(&row.server_url)
+        .bind(&row.tool_name)
+        .bind(&row.arguments_json)
+        .bind(row.created_at)
+        .bind(row.expires_at)
+        .execute(&self.write_pool)
+        .await?;
+        Ok(())
+    }
+
+    async fn take_by_id_and_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        now: DateTime<Utc>,
+    ) -> DbResult<Option<McpPendingApproval>> {
+        // DELETE … RETURNING claims the row atomically: a concurrent
+        // resume of the same id deletes nothing and gets `None`, so only
+        // one caller executes the gated tool. Runs on the write pool. The
+        // `expires_at > $3` guard makes an expired approval unclaimable
+        // even before the retention worker sweeps it.
+        let row = sqlx::query(
+            r#"
+            DELETE FROM mcp_pending_approvals
+            WHERE id = $1 AND org_id = $2 AND expires_at > $3
+            RETURNING id, response_id, org_id, call_id,
+                      server_label, server_url, tool_name,
+                      arguments_json, created_at, expires_at
+            "#,
+        )
+        .bind(id)
+        .bind(org_id)
+        .bind(now)
+        .fetch_optional(&self.write_pool)
+        .await?;
+
+        Ok(row.map(|r| McpPendingApproval {
+            id: r.get("id"),
+            response_id: r.get("response_id"),
+            org_id: r.get("org_id"),
+            call_id: r.get("call_id"),
+            server_label: r.get("server_label"),
+            server_url: r.get("server_url"),
+            tool_name: r.get("tool_name"),
+            arguments_json: r.get("arguments_json"),
+            created_at: r.get("created_at"),
+            expires_at: r.get("expires_at"),
+        }))
+    }
+
+    async fn delete_expired(&self, cutoff: DateTime<Utc>) -> DbResult<u64> {
+        let result = sqlx::query(
+            r#"
+            DELETE FROM mcp_pending_approvals
+            WHERE expires_at < $1
+            "#,
+        )
+        .bind(cutoff)
+        .execute(&self.write_pool)
+        .await?;
+        Ok(result.rows_affected())
+    }
+}
diff --git a/src/db/postgres/mod.rs b/src/db/postgres/mod.rs
index 79136a9..e2c9187 100644
--- a/src/db/postgres/mod.rs
+++ b/src/db/postgres/mod.rs
@@ -1,9 +1,12 @@
 mod api_keys;
 mod audit_logs;
+mod containers;
 mod conversations;
 #[cfg(feature = "sso")]
 mod domain_verifications;
 mod files;
+#[cfg(feature = "mcp")]
+mod mcp_pending_approvals;
 mod model_pricing;
 mod oauth_authorization_codes;
 mod org_rbac_policies;
@@ -12,6 +15,8 @@ mod org_sso_configs;
 mod organizations;
 mod projects;
 mod providers;
+mod response_events;
+mod responses;
 #[cfg(feature = "sso")]
 mod scim_configs;
 #[cfg(feature = "sso")]
@@ -30,10 +35,13 @@ mod vector_stores;
 
 pub use api_keys::PostgresApiKeyRepo;
 pub use audit_logs::PostgresAuditLogRepo;
+pub use containers::PostgresContainersRepo;
 pub use conversations::PostgresConversationRepo;
 #[cfg(feature = "sso")]
 pub use domain_verifications::PostgresDomainVerificationRepo;
 pub use files::PostgresFilesRepo;
+#[cfg(feature = "mcp")]
+pub use mcp_pending_approvals::PostgresMcpPendingApprovalsRepo;
 pub use model_pricing::PostgresModelPricingRepo;
 pub use oauth_authorization_codes::PostgresOAuthAuthorizationCodeRepo;
 pub use org_rbac_policies::PostgresOrgRbacPolicyRepo;
@@ -42,6 +50,8 @@ pub use org_sso_configs::PostgresOrgSsoConfigRepo;
 pub use organizations::PostgresOrganizationRepo;
 pub use projects::PostgresProjectRepo;
 pub use providers::PostgresDynamicProviderRepo;
+pub use response_events::PostgresResponseEventsRepo;
+pub use responses::PostgresResponsesRepo;
 #[cfg(feature = "sso")]
 pub use scim_configs::PostgresOrgScimConfigRepo;
 #[cfg(feature = "sso")]
diff --git a/src/db/postgres/response_events.rs b/src/db/postgres/response_events.rs
new file mode 100644
index 0000000..56bbe0b
--- /dev/null
+++ b/src/db/postgres/response_events.rs
@@ -0,0 +1,123 @@
+//! Postgres implementation of [`ResponseEventsRepo`].
+
+use async_trait::async_trait;
+use sqlx::{PgPool, Row};
+
+use crate::db::{
+    error::DbResult,
+    repos::{NewResponseEvent, ResponseEvent, ResponseEventsRepo},
+};
+
+pub struct PostgresResponseEventsRepo {
+    write_pool: PgPool,
+    read_pool: PgPool,
+}
+
+impl PostgresResponseEventsRepo {
+    pub fn new(write_pool: PgPool, read_pool: Option<PgPool>) -> Self {
+        let read_pool = read_pool.unwrap_or_else(|| write_pool.clone());
+        Self {
+            write_pool,
+            read_pool,
+        }
+    }
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+impl ResponseEventsRepo for PostgresResponseEventsRepo {
+    async fn insert_batch(&self, events: Vec<NewResponseEvent>) -> DbResult<u64> {
+        if events.is_empty() {
+            return Ok(0);
+        }
+        // Postgres allows up to 65535 bind params; 5 per row → 13000+ rows
+        // per batch. Cap at 1000 for query-time and memory reasons.
+        const CHUNK: usize = 1000;
+        let mut total = 0u64;
+        for chunk in events.chunks(CHUNK) {
+            let placeholders: Vec<String> = chunk
+                .iter()
+                .enumerate()
+                .map(|(i, _)| {
+                    let o = i * 5;
+                    format!(
+                        "(${}, ${}, ${}, ${}, ${})",
+                        o + 1,
+                        o + 2,
+                        o + 3,
+                        o + 4,
+                        o + 5
+                    )
+                })
+                .collect();
+            let sql = format!(
+                "INSERT INTO response_events \
+                 (response_id, sequence_number, event_type, payload, created_at) \
+                 VALUES {} \
+                 ON CONFLICT (response_id, sequence_number) DO NOTHING",
+                placeholders.join(", ")
+            );
+            let mut q = sqlx::query(&sql);
+            for ev in chunk {
+                q = q
+                    .bind(&ev.response_id)
+                    .bind(ev.sequence_number)
+                    .bind(&ev.event_type)
+                    .bind(&ev.payload)
+                    .bind(ev.created_at);
+            }
+            let result = q.execute(&self.write_pool).await?;
+            total += result.rows_affected();
+        }
+        Ok(total)
+    }
+
+    async fn list_after(
+        &self,
+        response_id: &str,
+        after: i64,
+        limit: i64,
+    ) -> DbResult<Vec<ResponseEvent>> {
+        let rows = sqlx::query(
+            r#"
+            SELECT response_id, sequence_number, event_type, payload, created_at
+            FROM response_events
+            WHERE response_id = $1 AND sequence_number > $2
+            ORDER BY sequence_number ASC
+            LIMIT $3
+            "#,
+        )
+        .bind(response_id)
+        .bind(after)
+        .bind(limit)
+        .fetch_all(&self.read_pool)
+        .await?;
+
+        let mut out = Vec::with_capacity(rows.len());
+        for row in rows {
+            out.push(ResponseEvent {
+                response_id: row.get("response_id"),
+                sequence_number: row.get("sequence_number"),
+                event_type: row.get("event_type"),
+                payload: row.get("payload"),
+                created_at: row.get("created_at"),
+            });
+        }
+        Ok(out)
+    }
+
+    async fn set_last_sequence(&self, response_id: &str, seq: i64) -> DbResult<()> {
+        sqlx::query(
+            r#"
+            UPDATE responses
+            SET last_sequence_number = $1
+            WHERE id = $2 AND last_sequence_number < $1
+            "#,
+        )
+        .bind(seq)
+        .bind(response_id)
+        .execute(&self.write_pool)
+        .await?;
+        Ok(())
+    }
+}
diff --git a/src/db/postgres/responses.rs b/src/db/postgres/responses.rs
new file mode 100644
index 0000000..fac8db1
--- /dev/null
+++ b/src/db/postgres/responses.rs
@@ -0,0 +1,411 @@
+//! Postgres implementation of [`ResponsesRepo`].
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use sqlx::{PgPool, Row};
+use uuid::Uuid;
+
+use crate::db::{
+    error::{DbError, DbResult},
+    repos::{
+        NewResponse, ResponseCompletion, ResponseOwnerType, ResponseRecord, ResponseStatus,
+        ResponsesRepo,
+    },
+};
+
+/// Org-scope filter for reads/updates/deletes against `responses` —
+/// mirrors `skills::ORG_SCOPE_FILTER`. Org id is `$1` (referenced
+/// five times — once per owner type). The clause is prefixed with
+/// `AND` so it can be appended to a `WHERE` predicate that already
+/// matches by `id`.
+const ORG_SCOPE_FILTER: &str = r#"
+    AND (
+        (responses.owner_type = 'organization' AND responses.owner_id = $1)
+        OR (responses.owner_type = 'team' AND EXISTS (
+            SELECT 1 FROM teams t WHERE t.id = responses.owner_id AND t.org_id = $1
+        ))
+        OR (responses.owner_type = 'project' AND EXISTS (
+            SELECT 1 FROM projects pr WHERE pr.id = responses.owner_id AND pr.org_id = $1
+        ))
+        OR (responses.owner_type = 'user' AND EXISTS (
+            SELECT 1 FROM org_memberships om WHERE om.user_id = responses.owner_id AND om.org_id = $1
+        ))
+        OR (responses.owner_type = 'service_account' AND EXISTS (
+            SELECT 1 FROM service_accounts sa WHERE sa.id = responses.owner_id AND sa.org_id = $1
+        ))
+    )
+"#;
+
+/// All columns of `responses` in canonical SELECT order, with
+/// `owner_type` cast to TEXT for direct string parsing. Used by every
+/// SELECT / RETURNING in this repo so the column list stays in sync.
+const RESPONSE_COLUMNS: &str = "id, org_id, owner_type::TEXT, owner_id, \
+    project_id, user_id, api_key_id, service_account_id, \
+    status, background, model, provider, \
+    created_at, started_at, completed_at, \
+    request_payload, output, usage, error, \
+    retention_expires_at, last_sequence_number, last_heartbeat_at, container_id";
+
+pub struct PostgresResponsesRepo {
+    write_pool: PgPool,
+    read_pool: PgPool,
+}
+
+impl PostgresResponsesRepo {
+    pub fn new(write_pool: PgPool, read_pool: Option<PgPool>) -> Self {
+        let read_pool = read_pool.unwrap_or_else(|| write_pool.clone());
+        Self {
+            write_pool,
+            read_pool,
+        }
+    }
+
+    /// Shared body for `update_within_org` / `complete_within_org`.
+    /// When `guard_non_terminal` is set, the UPDATE only matches rows
+    /// whose current status is non-terminal, so a `Some` result means
+    /// this call performed the transition.
+    async fn update_within_org_inner(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ResponseCompletion,
+        guard_non_terminal: bool,
+    ) -> DbResult<Option<ResponseRecord>> {
+        // Build the SET clause dynamically. Org id is $1 (referenced
+        // by the cascade scope filter), so dynamic columns start at
+        // $2 and the id placeholder slots in after them.
+        let mut setters: Vec<String> = Vec::new();
+        let mut idx = 2usize;
+
+        macro_rules! add {
+            ($cond:expr, $col:expr) => {
+                if $cond {
+                    setters.push(format!("{} = ${}", $col, idx));
+                    idx += 1;
+                }
+            };
+        }
+        add!(patch.status.is_some(), "status");
+        add!(patch.started_at.is_some(), "started_at");
+        add!(patch.completed_at.is_some(), "completed_at");
+        add!(patch.output.is_some(), "output");
+        add!(patch.usage.is_some(), "usage");
+        add!(patch.error.is_some(), "error");
+        add!(patch.retention_expires_at.is_some(), "retention_expires_at");
+        add!(patch.container_id.is_some(), "container_id");
+        if setters.is_empty() {
+            return self.get_by_id_and_org(id, org_id).await;
+        }
+
+        // Terminal guard is a static literal fragment with no extra
+        // binds — see `ResponseStatus::is_terminal`.
+        let guard = if guard_non_terminal {
+            " AND status NOT IN ('completed', 'failed', 'cancelled', 'incomplete')"
+        } else {
+            ""
+        };
+        let id_placeholder = idx;
+        let sql = format!(
+            "UPDATE responses SET {set} WHERE id = ${id}{scope}{guard} RETURNING {cols}",
+            set = setters.join(", "),
+            id = id_placeholder,
+            scope = ORG_SCOPE_FILTER,
+            guard = guard,
+            cols = RESPONSE_COLUMNS,
+        );
+        let mut q = sqlx::query(&sql);
+        q = q.bind(org_id);
+        if let Some(status) = patch.status {
+            q = q.bind(status.as_str().to_string());
+        }
+        if let Some(ts) = patch.started_at {
+            q = q.bind(ts);
+        }
+        if let Some(ts) = patch.completed_at {
+            q = q.bind(ts);
+        }
+        if let Some(output) = patch.output {
+            q = q.bind(output);
+        }
+        if let Some(usage) = patch.usage {
+            q = q.bind(usage);
+        }
+        if let Some(error) = patch.error {
+            q = q.bind(error);
+        }
+        if let Some(ts) = patch.retention_expires_at {
+            q = q.bind(ts);
+        }
+        if let Some(cid) = patch.container_id {
+            q = q.bind(cid);
+        }
+        q = q.bind(id);
+
+        let result = q.fetch_optional(&self.write_pool).await?;
+        match result {
+            Some(row) => Ok(Some(row_to_record(&row)?)),
+            None => Ok(None),
+        }
+    }
+}
+
+fn parse_status(s: &str) -> DbResult<ResponseStatus> {
+    ResponseStatus::parse(s)
+        .ok_or_else(|| DbError::Internal(format!("unknown response status: {s}")))
+}
+
+fn parse_owner_type(s: &str) -> DbResult<ResponseOwnerType> {
+    ResponseOwnerType::parse(s)
+        .ok_or_else(|| DbError::Internal(format!("unknown response owner_type: {s}")))
+}
+
+fn row_to_record(row: &sqlx::postgres::PgRow) -> DbResult<ResponseRecord> {
+    Ok(ResponseRecord {
+        id: row.get("id"),
+        org_id: row.get("org_id"),
+        owner_type: parse_owner_type(&row.get::<String, _>("owner_type"))?,
+        owner_id: row.get("owner_id"),
+        project_id: row.get("project_id"),
+        user_id: row.get("user_id"),
+        api_key_id: row.get("api_key_id"),
+        service_account_id: row.get("service_account_id"),
+        status: parse_status(&row.get::<String, _>("status"))?,
+        background: row.get("background"),
+        model: row.get("model"),
+        provider: row.get("provider"),
+        created_at: row.get("created_at"),
+        started_at: row.get("started_at"),
+        completed_at: row.get("completed_at"),
+        request_payload: row.get("request_payload"),
+        output: row.get("output"),
+        usage: row.get("usage"),
+        error: row.get("error"),
+        retention_expires_at: row.get("retention_expires_at"),
+        last_sequence_number: row.get("last_sequence_number"),
+        last_heartbeat_at: row.get("last_heartbeat_at"),
+        container_id: row.get("container_id"),
+    })
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+impl ResponsesRepo for PostgresResponsesRepo {
+    async fn insert(&self, input: NewResponse) -> DbResult<ResponseRecord> {
+        sqlx::query(
+            r#"
+            INSERT INTO responses (
+                id, org_id, owner_type, owner_id,
+                project_id, user_id, api_key_id, service_account_id,
+                status, background, model, provider,
+                created_at, request_payload, retention_expires_at
+            )
+            VALUES (
+                $1, $2, $3::response_owner_type, $4,
+                $5, $6, $7, $8,
+                $9, $10, $11, $12,
+                $13, $14, $15
+            )
+            "#,
+        )
+        .bind(&input.id)
+        .bind(input.org_id)
+        .bind(input.owner_type.as_str())
+        .bind(input.owner_id)
+        .bind(input.project_id)
+        .bind(input.user_id)
+        .bind(input.api_key_id)
+        .bind(input.service_account_id)
+        .bind(input.status.as_str())
+        .bind(input.background)
+        .bind(&input.model)
+        .bind(&input.provider)
+        .bind(input.created_at)
+        .bind(&input.request_payload)
+        .bind(input.retention_expires_at)
+        .execute(&self.write_pool)
+        .await?;
+
+        Ok(ResponseRecord {
+            id: input.id,
+            org_id: input.org_id,
+            owner_type: input.owner_type,
+            owner_id: input.owner_id,
+            project_id: input.project_id,
+            user_id: input.user_id,
+            api_key_id: input.api_key_id,
+            service_account_id: input.service_account_id,
+            status: input.status,
+            background: input.background,
+            model: input.model,
+            provider: input.provider,
+            created_at: input.created_at,
+            started_at: None,
+            completed_at: None,
+            request_payload: input.request_payload,
+            output: None,
+            usage: None,
+            error: None,
+            retention_expires_at: input.retention_expires_at,
+            last_sequence_number: 0,
+            last_heartbeat_at: None,
+            container_id: None,
+        })
+    }
+
+    async fn get_by_id_and_org(&self, id: &str, org_id: Uuid) -> DbResult<Option<ResponseRecord>> {
+        let sql = format!(
+            "SELECT {cols} FROM responses WHERE id = $2{scope}",
+            cols = RESPONSE_COLUMNS,
+            scope = ORG_SCOPE_FILTER,
+        );
+        let result = sqlx::query(&sql)
+            .bind(org_id)
+            .bind(id)
+            .fetch_optional(&self.read_pool)
+            .await?;
+        match result {
+            Some(row) => Ok(Some(row_to_record(&row)?)),
+            None => Ok(None),
+        }
+    }
+
+    async fn update_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ResponseCompletion,
+    ) -> DbResult<Option<ResponseRecord>> {
+        self.update_within_org_inner(id, org_id, patch, false).await
+    }
+
+    async fn complete_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ResponseCompletion,
+    ) -> DbResult<Option<ResponseRecord>> {
+        self.update_within_org_inner(id, org_id, patch, true).await
+    }
+
+    async fn delete_by_id_and_org(&self, id: &str, org_id: Uuid) -> DbResult<bool> {
+        let sql = format!(
+            "DELETE FROM responses WHERE id = $2{scope}",
+            scope = ORG_SCOPE_FILTER,
+        );
+        let result = sqlx::query(&sql)
+            .bind(org_id)
+            .bind(id)
+            .execute(&self.write_pool)
+            .await?;
+        Ok(result.rows_affected() > 0)
+    }
+
+    async fn claim_queued(&self, now: DateTime<Utc>) -> DbResult<Option<ResponseRecord>> {
+        // SELECT FOR UPDATE SKIP LOCKED + UPDATE in one CTE gives
+        // atomic, contention-free claim semantics across N workers.
+        // Worker runs gateway-wide (not per principal), so no scope
+        // filter — every queued row is claimable.
+        let sql = format!(
+            r#"
+            WITH claimed AS (
+                SELECT id FROM responses
+                WHERE status = 'queued'
+                ORDER BY created_at ASC
+                FOR UPDATE SKIP LOCKED
+                LIMIT 1
+            )
+            UPDATE responses
+            SET status = 'in_progress', started_at = $1
+            FROM claimed
+            WHERE responses.id = claimed.id
+            RETURNING {cols}
+            "#,
+            cols = RESPONSE_COLUMNS,
+        );
+        let result = sqlx::query(&sql)
+            .bind(now)
+            .fetch_optional(&self.write_pool)
+            .await?;
+        match result {
+            Some(row) => Ok(Some(row_to_record(&row)?)),
+            None => Ok(None),
+        }
+    }
+
+    async fn list_cancelled_among(&self, ids: &[String]) -> DbResult<Vec<String>> {
+        if ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        let rows = sqlx::query(
+            r#"
+            SELECT id FROM responses
+            WHERE status = 'cancelled' AND id = ANY($1)
+            "#,
+        )
+        .bind(ids)
+        .fetch_all(&self.read_pool)
+        .await?;
+        Ok(rows.iter().map(|r| r.get::<String, _>("id")).collect())
+    }
+
+    async fn delete_expired(&self, before: DateTime<Utc>) -> DbResult<u64> {
+        let result = sqlx::query(
+            r#"
+            DELETE FROM responses
+            WHERE retention_expires_at < $1
+              AND status IN ('completed', 'failed', 'cancelled', 'incomplete')
+            "#,
+        )
+        .bind(before)
+        .execute(&self.write_pool)
+        .await?;
+        Ok(result.rows_affected())
+    }
+
+    async fn reap_stuck_in_progress(
+        &self,
+        started_before: DateTime<Utc>,
+        completed_at: DateTime<Utc>,
+        retention_expires_at: DateTime<Utc>,
+    ) -> DbResult<u64> {
+        let error_payload = serde_json::json!({
+            "code": "worker_lost",
+            "message": "Worker died mid-execution; reaped by retention worker",
+        });
+        // Compare against the liveness heartbeat, falling back to
+        // `started_at` for rows whose worker never stamped one — only
+        // genuinely stalled workers are reaped, never a healthy
+        // long-running response.
+        let result = sqlx::query(
+            r#"
+            UPDATE responses
+            SET status = 'failed',
+                completed_at = $1,
+                error = $2,
+                retention_expires_at = $3
+            WHERE status = 'in_progress'
+              AND started_at IS NOT NULL
+              AND COALESCE(last_heartbeat_at, started_at) < $4
+            "#,
+        )
+        .bind(completed_at)
+        .bind(error_payload)
+        .bind(retention_expires_at)
+        .bind(started_before)
+        .execute(&self.write_pool)
+        .await?;
+        Ok(result.rows_affected())
+    }
+
+    async fn touch_heartbeat(&self, id: &str, now: DateTime<Utc>) -> DbResult<()> {
+        // Best-effort liveness ping; only meaningful while `in_progress`.
+        sqlx::query(
+            "UPDATE responses SET last_heartbeat_at = $1 WHERE id = $2 AND status = 'in_progress'",
+        )
+        .bind(now)
+        .bind(id)
+        .execute(&self.write_pool)
+        .await?;
+        Ok(())
+    }
+}
diff --git a/src/db/postgres/usage.rs b/src/db/postgres/usage.rs
index a4d6b9d..34852b6 100644
--- a/src/db/postgres/usage.rs
+++ b/src/db/postgres/usage.rs
@@ -66,9 +66,10 @@ impl UsageRepo for PostgresUsageRepo {
                 user_id, org_id, project_id, team_id, service_account_id, pricing_source,
                 image_count, audio_seconds, character_count, provider_source,
                 record_type, tool_name, tool_query, tool_url,
-                tool_bytes_fetched, tool_results_count
+                tool_bytes_fetched, tool_results_count, tool_runtime_seconds,
+                tool_exit_code
             )
-            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28, $29, $30, $31, $32, $33, $34)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28, $29, $30, $31, $32, $33, $34, $35, $36)
             ON CONFLICT (request_id) DO NOTHING
             "#,
         )
@@ -106,6 +107,8 @@ impl UsageRepo for PostgresUsageRepo {
         .bind(&entry.tool_url)
         .bind(entry.tool_bytes_fetched)
         .bind(entry.tool_results_count)
+        .bind(entry.tool_runtime_seconds)
+        .bind(entry.tool_exit_code)
         .execute(&self.write_pool)
         .await?;
 
@@ -118,7 +121,7 @@ impl UsageRepo for PostgresUsageRepo {
         }
 
         // PostgreSQL allows up to 65535 parameters per query
-        // Each entry uses 34 parameters, so we can insert ~1927 entries per batch
+        // Each entry uses 36 parameters, so we can insert ~1820 entries per batch
         // Use 1000 as a reasonable batch size for performance
         const MAX_ENTRIES_PER_BATCH: usize = 1000;
 
@@ -136,15 +139,15 @@ impl UsageRepo for PostgresUsageRepo {
                 .iter()
                 .enumerate()
                 .map(|(i, _)| {
-                    let o = i * 34;
+                    let o = i * 36;
                     format!(
-                        "(${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${})",
+                        "(${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${}, ${})",
                         o + 1, o + 2, o + 3, o + 4, o + 5, o + 6,
                         o + 7, o + 8, o + 9, o + 10, o + 11, o + 12,
                         o + 13, o + 14, o + 15, o + 16, o + 17, o + 18,
                         o + 19, o + 20, o + 21, o + 22, o + 23, o + 24,
                         o + 25, o + 26, o + 27, o + 28, o + 29, o + 30,
-                        o + 31, o + 32, o + 33, o + 34
+                        o + 31, o + 32, o + 33, o + 34, o + 35, o + 36
                     )
                 })
                 .collect();
@@ -159,7 +162,8 @@ impl UsageRepo for PostgresUsageRepo {
                     user_id, org_id, project_id, team_id, service_account_id, pricing_source,
                     image_count, audio_seconds, character_count, provider_source,
                     record_type, tool_name, tool_query, tool_url,
-                    tool_bytes_fetched, tool_results_count
+                    tool_bytes_fetched, tool_results_count, tool_runtime_seconds,
+                    tool_exit_code
                 )
                 VALUES {}
                 ON CONFLICT (request_id) DO NOTHING
@@ -207,7 +211,9 @@ impl UsageRepo for PostgresUsageRepo {
                     .bind(&entry.tool_query)
                     .bind(&entry.tool_url)
                     .bind(entry.tool_bytes_fetched)
-                    .bind(entry.tool_results_count);
+                    .bind(entry.tool_results_count)
+                    .bind(entry.tool_runtime_seconds)
+                    .bind(entry.tool_exit_code);
             }
 
             let result = query_builder.execute(&mut *tx).await?;
@@ -3877,7 +3883,8 @@ impl UsageRepo for PostgresUsageRepo {
                    latency_ms, cancelled, status_code, pricing_source,
                    image_count, audio_seconds, character_count, provider_source,
                    record_type, tool_name, tool_query, tool_url,
-                   tool_bytes_fetched, tool_results_count
+                   tool_bytes_fetched, tool_results_count, tool_runtime_seconds,
+                   tool_exit_code
             FROM usage_records
             {}
             ORDER BY recorded_at {}, id {}
@@ -3971,6 +3978,8 @@ impl UsageRepo for PostgresUsageRepo {
                 tool_url: row.get("tool_url"),
                 tool_bytes_fetched: row.get("tool_bytes_fetched"),
                 tool_results_count: row.get("tool_results_count"),
+                tool_runtime_seconds: row.get("tool_runtime_seconds"),
+                tool_exit_code: row.get("tool_exit_code"),
             })
             .collect();
 
diff --git a/src/db/repos/containers.rs b/src/db/repos/containers.rs
new file mode 100644
index 0000000..6016d70
--- /dev/null
+++ b/src/db/repos/containers.rs
@@ -0,0 +1,370 @@
+//! Repo for `containers` and `container_files` — the shell-tool
+//! `/mnt/data` artifact store.
+//!
+//! A *container* tracks one persistent shell-tool session. Today the
+//! session is response-scoped; `previous_response_id` chains let the
+//! same container be reused across responses.
+//! A *container_file* tracks one file under `/mnt/data` in that
+//! container, with content stored via the same `FileStorage` backend
+//! abstraction the OpenAI Files API uses.
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+
+use crate::{
+    db::{
+        error::DbResult,
+        repos::{ResponseOwner, ResponseOwnerType},
+    },
+    models::StorageBackend,
+};
+
+/// One external storage object whose `container_files` row was removed
+/// by [`ContainersRepo::hard_delete_expired`]. The DB cascade drops the
+/// row but not the backing bytes in filesystem/S3 storage, so the
+/// service deletes these explicitly.
+#[derive(Debug, Clone)]
+pub struct DeletedFileObject {
+    pub file_id: String,
+    pub storage_backend: StorageBackend,
+    pub storage_path: Option<String>,
+}
+
+/// Outcome of one `hard_delete_expired` pass: the container rows that
+/// were removed and the external storage objects their files
+/// referenced.
+#[derive(Debug, Default)]
+pub struct HardDeleteExpiredOutcome {
+    pub container_ids: Vec<String>,
+    pub file_objects: Vec<DeletedFileObject>,
+}
+
+/// Lifecycle states for a container row.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ContainerStatus {
+    /// Session is live, can still accept new files / commands.
+    Active,
+    /// Idle TTL elapsed; the VM has been torn down. Existing files
+    /// remain downloadable until the container is hard-deleted.
+    Expired,
+    /// Operator or owner deleted it. Files cascade-delete with the
+    /// row (CASCADE on `container_files.container_id`).
+    Deleted,
+}
+
+impl ContainerStatus {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Expired => "expired",
+            Self::Deleted => "deleted",
+        }
+    }
+
+    pub fn parse(s: &str) -> Option<Self> {
+        match s {
+            "active" => Some(Self::Active),
+            "expired" => Some(Self::Expired),
+            "deleted" => Some(Self::Deleted),
+            _ => None,
+        }
+    }
+}
+
+/// One persisted container row.
+#[derive(Debug, Clone)]
+pub struct ContainerRecord {
+    /// `cntr_<32hex>` — same string the API emits.
+    pub id: String,
+    pub org_id: Uuid,
+    pub owner_type: ResponseOwnerType,
+    pub owner_id: Uuid,
+    pub status: ContainerStatus,
+    /// `microsandbox`, `opensandbox`, etc. Free-form so adding a new
+    /// runtime doesn't require a migration.
+    pub runtime_label: String,
+    /// Response this container was originally provisioned for.
+    /// `None` for containers created via `POST /v1/containers`.
+    pub source_response_id: Option<String>,
+    pub idle_ttl_secs: i64,
+    pub last_active_at: DateTime<Utc>,
+    pub created_at: DateTime<Utc>,
+    /// Set when status transitions to `Expired` (so we know when the
+    /// VM stopped backing the row).
+    pub expires_at: Option<DateTime<Utc>>,
+    /// Optional display name supplied at creation time.
+    pub name: Option<String>,
+    /// Memory ceiling captured at creation. `None` ⇒ runtime default.
+    pub memory_limit_mb: Option<i64>,
+    /// JSON-encoded network policy applied to this container.
+    pub network_policy_json: Option<String>,
+    /// JSON array of skill UUIDs bound to this container.
+    pub skill_ids_json: Option<String>,
+}
+
+/// Fields needed to create a new container row.
+#[derive(Debug, Clone)]
+pub struct NewContainer {
+    pub id: String,
+    pub org_id: Uuid,
+    pub owner_type: ResponseOwnerType,
+    pub owner_id: Uuid,
+    pub status: ContainerStatus,
+    pub runtime_label: String,
+    pub source_response_id: Option<String>,
+    pub idle_ttl_secs: i64,
+    pub created_at: DateTime<Utc>,
+    pub name: Option<String>,
+    pub memory_limit_mb: Option<i64>,
+    pub network_policy_json: Option<String>,
+    pub skill_ids_json: Option<String>,
+}
+
+impl NewContainer {
+    /// Convenience for the foreground/background pipeline: bundle the
+    /// principal-derived owner together with the rest of the row.
+    pub fn from_owner(
+        id: String,
+        org_id: Uuid,
+        owner: ResponseOwner,
+        runtime_label: impl Into<String>,
+        source_response_id: Option<String>,
+        idle_ttl_secs: i64,
+        created_at: DateTime<Utc>,
+    ) -> Self {
+        Self {
+            id,
+            org_id,
+            owner_type: owner.owner_type(),
+            owner_id: owner.owner_id(),
+            status: ContainerStatus::Active,
+            runtime_label: runtime_label.into(),
+            source_response_id,
+            idle_ttl_secs,
+            created_at,
+            name: None,
+            memory_limit_mb: None,
+            network_policy_json: None,
+            skill_ids_json: None,
+        }
+    }
+}
+
+/// Origin of a captured container file. Mirrors
+/// [`crate::api_types::responses::ContainerFileSource`] but lives in
+/// the repo layer so persistence code doesn't depend on the API
+/// surface.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ContainerFileSourceKind {
+    User,
+    Assistant,
+}
+
+impl ContainerFileSourceKind {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::User => "user",
+            Self::Assistant => "assistant",
+        }
+    }
+
+    pub fn parse(s: &str) -> Option<Self> {
+        match s {
+            "user" => Some(Self::User),
+            "assistant" => Some(Self::Assistant),
+            _ => None,
+        }
+    }
+}
+
+/// One persisted container_file row.
+#[derive(Debug, Clone)]
+pub struct ContainerFileRecord {
+    /// `cfile_<32hex>` — same string the API emits.
+    pub id: String,
+    pub container_id: String,
+    pub org_id: Uuid,
+    /// Absolute path inside the container, always under `/mnt/data/`.
+    pub path: String,
+    pub filename: String,
+    pub size_bytes: i64,
+    pub content_type: Option<String>,
+    pub content_hash: String,
+    pub source: ContainerFileSourceKind,
+    pub storage_backend: crate::models::StorageBackend,
+    /// Path inside the external storage backend, when applicable.
+    pub storage_path: Option<String>,
+    pub source_response_id: Option<String>,
+    pub source_call_id: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
+
+/// Fields needed to insert or overwrite a container_file row.
+///
+/// Repos resolve same-`(container_id, path)` collisions by replacing
+/// the existing row in place (UPSERT). That keeps a re-run of the
+/// same shell command from creating new rows for an idempotent
+/// artifact — but also means the row's `id` may change between Phase
+/// 1's in-memory view and the persisted one. Callers that emitted a
+/// `cfile_…` id into an annotation should pass that same id here so
+/// downloads stay stable across overwrites.
+#[derive(Debug, Clone)]
+pub struct NewContainerFile {
+    pub id: String,
+    pub container_id: String,
+    pub org_id: Uuid,
+    pub path: String,
+    pub filename: String,
+    pub size_bytes: i64,
+    pub content_type: Option<String>,
+    pub content_hash: String,
+    pub source: ContainerFileSourceKind,
+    pub storage_backend: crate::models::StorageBackend,
+    /// Bytes when `storage_backend == Database`. Repos ignore when the
+    /// backend is filesystem/S3 (those write through a `FileStorage`
+    /// adapter before the row is inserted).
+    pub file_data: Option<Vec<u8>>,
+    pub storage_path: Option<String>,
+    pub source_response_id: Option<String>,
+    pub source_call_id: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
+
+/// Patch applied to a container row in [`ContainersRepo::update_within_org`].
+/// Only `Some` fields are written. `expires_at` is set when status
+/// transitions to `Expired`; clear it explicitly by passing `Some(None)`
+/// using the `Option<Option<…>>` shape would be redundant since
+/// expiry is monotonic.
+#[derive(Debug, Clone, Default)]
+pub struct ContainerPatch {
+    pub status: Option<ContainerStatus>,
+    pub last_active_at: Option<DateTime<Utc>>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+pub trait ContainersRepo: Send + Sync {
+    /// Insert a new container row. The caller picks the `cntr_…` id
+    /// up front so it can be emitted into SSE/annotations before
+    /// persistence completes.
+    async fn insert(&self, input: NewContainer) -> DbResult<ContainerRecord>;
+
+    /// Org-scoped fetch by ID. Same enumeration-resistance pattern as
+    /// `ResponsesRepo`: returns `None` for missing-or-wrong-org without
+    /// distinguishing the two cases.
+    async fn get_by_id_and_org(&self, id: &str, org_id: Uuid) -> DbResult<Option<ContainerRecord>>;
+
+    /// List containers in an org, newest-first.
+    ///
+    /// `after` is a literal `cntr_…` id (OpenAI's cursor shape). The
+    /// repo resolves it to a `(created_at, id)` keyset and returns the
+    /// next page strictly after that position. Fetches `limit + 1` rows
+    /// so the caller can determine `has_more`.
+    ///
+    /// Returns the rows in `created_at DESC, id DESC` order. Unknown or
+    /// cross-org `after` values resolve to an empty page (no leakage).
+    async fn list_by_org(
+        &self,
+        org_id: Uuid,
+        limit: i64,
+        after: Option<&str>,
+    ) -> DbResult<Vec<ContainerRecord>>;
+
+    /// Upsert a container_file row. If `(container_id, path)` is
+    /// already present, replaces the existing row (path-level
+    /// idempotency for overwrites) while keeping the row's `id`
+    /// stable so any annotation citing the prior version still
+    /// resolves to the latest bytes.
+    async fn upsert_file(&self, input: NewContainerFile) -> DbResult<ContainerFileRecord>;
+
+    /// Org-scoped fetch of one container_file by id. Joins through the
+    /// container to enforce the org boundary in a single query.
+    async fn get_file_by_id_and_org(
+        &self,
+        file_id: &str,
+        org_id: Uuid,
+    ) -> DbResult<Option<ContainerFileRecord>>;
+
+    /// Read the raw bytes for a container_file when its
+    /// `storage_backend == Database`. For external backends the
+    /// caller resolves through the `FileStorage` adapter using
+    /// `record.storage_path`.
+    async fn read_file_data(&self, file_id: &str, org_id: Uuid) -> DbResult<Option<Vec<u8>>>;
+
+    /// List files inside a container, newest first. The container's
+    /// org gate is applied so a cross-tenant `container_id` returns an
+    /// empty list. Returns a simple slice (caller-supplied `limit`,
+    /// default 100); cursor pagination is a future enhancement.
+    async fn list_files_by_container(
+        &self,
+        container_id: &str,
+        org_id: Uuid,
+        limit: i64,
+    ) -> DbResult<Vec<ContainerFileRecord>>;
+
+    /// All files for a container, regardless of `org_id`. Used by the
+    /// reattach path which has already validated org access via the
+    /// `containers` row lookup. Files come back newest-first.
+    async fn list_files_for_replay(&self, container_id: &str)
+    -> DbResult<Vec<ContainerFileRecord>>;
+
+    /// Read raw bytes by `(container_id, file_id)` without an org
+    /// check. Used by reattach to replay files into a fresh VM.
+    async fn read_file_data_for_replay(
+        &self,
+        container_id: &str,
+        file_id: &str,
+    ) -> DbResult<Option<Vec<u8>>>;
+
+    /// Patch lifecycle fields on a container row, org-scoped.
+    /// Returns the updated record, or `None` when nothing matched.
+    async fn update_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ContainerPatch,
+    ) -> DbResult<Option<ContainerRecord>>;
+
+    /// Atomically mark all `active` containers whose
+    /// `last_active_at + idle_ttl_secs` is older than `now` as
+    /// `expired`. Returns the list of ids that just transitioned so
+    /// the caller can evict matching entries from the in-memory
+    /// session registry.
+    async fn mark_expired_idle(&self, now: DateTime<Utc>) -> DbResult<Vec<String>>;
+
+    /// Return the subset of `ids` whose row is in a terminal state
+    /// (`expired` / `deleted`). Used by the reaper on *every* replica to
+    /// reconcile its process-local session registry against rows a
+    /// (possibly different) leader replica already flipped to `expired`.
+    async fn expired_among(&self, ids: &[String]) -> DbResult<Vec<String>>;
+
+    /// Hard-`DELETE` terminal (`expired` / `deleted`) container rows whose
+    /// transition timestamp (`expires_at`) is at or before `cutoff`,
+    /// cascading their `container_files` rows. `expires_at` is stamped
+    /// when a row transitions out of `active`, so the caller measures the
+    /// retention delay from when the container became terminal.
+    ///
+    /// At most `limit` rows are removed per call so a backlog can't turn
+    /// into one long-running statement. Returns the deleted container
+    /// ids plus the external storage objects their files referenced, so
+    /// the caller can delete the backing bytes the cascade can't reach.
+    /// Atomic: rows and the returned object list are captured in a
+    /// single transaction.
+    async fn hard_delete_expired(
+        &self,
+        cutoff: DateTime<Utc>,
+        limit: i64,
+    ) -> DbResult<HardDeleteExpiredOutcome>;
+
+    /// Org-scoped delete of one `container_files` row. Returns true
+    /// when a row was removed. Bytes inside the row are dropped along
+    /// with the metadata.
+    async fn delete_file_by_id_and_org(
+        &self,
+        file_id: &str,
+        container_id: &str,
+        org_id: Uuid,
+    ) -> DbResult<bool>;
+}
diff --git a/src/db/repos/cursor.rs b/src/db/repos/cursor.rs
index e53f71d..211e6b1 100644
--- a/src/db/repos/cursor.rs
+++ b/src/db/repos/cursor.rs
@@ -227,11 +227,6 @@ pub fn cursor_from_row(created_at: DateTime<Utc>, id: Uuid) -> Cursor {
 /// // When creating entities that will use cursor pagination:
 /// let created_at = truncate_to_millis(Utc::now());
 /// ```
-#[cfg(any(
-    feature = "database-sqlite",
-    feature = "database-postgres",
-    feature = "database-wasm-sqlite"
-))]
 pub fn truncate_to_millis(dt: DateTime<Utc>) -> DateTime<Utc> {
     DateTime::from_timestamp_millis(dt.timestamp_millis()).unwrap_or(dt)
 }
diff --git a/src/db/repos/mcp_pending_approvals.rs b/src/db/repos/mcp_pending_approvals.rs
new file mode 100644
index 0000000..339e903
--- /dev/null
+++ b/src/db/repos/mcp_pending_approvals.rs
@@ -0,0 +1,87 @@
+//! Parked MCP tool calls waiting on a `mcp_approval_response`.
+//!
+//! Written by the `McpExecutor` when a model-initiated tool call is
+//! gated by `require_approval`; read by the preprocess in
+//! `routes/execution.rs` when a follow-up request includes a
+//! matching `mcp_approval_response` input item. See
+//! `docs/content/docs/features/mcp-tool.mdx` for the protocol.
+//!
+//! The table is intentionally simple — one row per parked call, keyed
+//! by the `approval_request_id` the gateway emitted on the
+//! `mcp_approval_request` SSE item. Cleanup is best-effort via
+//! `expires_at`: the responses retention worker
+//! (`jobs::responses_retention`) calls [`McpPendingApprovalsRepo::delete_expired`]
+//! each pass to sweep rows past their TTL.
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+
+use crate::db::error::DbResult;
+
+/// Persisted shape of one parked approval.
+#[derive(Debug, Clone)]
+pub struct McpPendingApproval {
+    /// `approval_request_id` echoed back on `mcp_approval_response`.
+    pub id: String,
+    pub response_id: String,
+    pub org_id: Uuid,
+    /// `call_id` from the original `function_call`.
+    pub call_id: String,
+    pub server_label: String,
+    pub server_url: String,
+    pub tool_name: String,
+    /// Arguments as a JSON string (matches `function_call.arguments`).
+    pub arguments_json: String,
+    pub created_at: DateTime<Utc>,
+    pub expires_at: DateTime<Utc>,
+}
+
+/// Fields supplied by the executor at park time.
+#[derive(Debug, Clone)]
+pub struct NewMcpPendingApproval {
+    pub id: String,
+    pub response_id: String,
+    pub org_id: Uuid,
+    pub call_id: String,
+    pub server_label: String,
+    pub server_url: String,
+    pub tool_name: String,
+    pub arguments_json: String,
+    pub created_at: DateTime<Utc>,
+    pub expires_at: DateTime<Utc>,
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+pub trait McpPendingApprovalsRepo: Send + Sync {
+    /// Park one approval. Conflicts on `id` are rejected — the gateway
+    /// generates UUID-based ids so a collision means a programming
+    /// error, not retry idempotency.
+    async fn insert(&self, row: NewMcpPendingApproval) -> DbResult<()>;
+
+    /// Atomically claim a parked approval by `approval_request_id`,
+    /// scoped to `org_id` so cross-tenant lookup is impossible. Deletes
+    /// the row and returns it in a single statement (`DELETE … RETURNING`)
+    /// so exactly one resume of a given `approval_request_id` can win the
+    /// claim — concurrent resumes of the same id see `None` and cannot
+    /// double-execute a side-effecting tool. Returns `None` when no row
+    /// matches (already consumed, wrong org, or expired).
+    ///
+    /// `now` gates the claim on `expires_at > now`: the retention worker
+    /// only sweeps periodically, so without this gate an expired (but
+    /// not-yet-swept) approval would still be claimable and executable.
+    /// An expired row is left in place for the sweeper rather than
+    /// claimed.
+    async fn take_by_id_and_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        now: DateTime<Utc>,
+    ) -> DbResult<Option<McpPendingApproval>>;
+
+    /// Delete every row whose `expires_at` is past `cutoff`. Returns
+    /// the number of rows reaped so retention metrics can log it.
+    /// Called by the retention worker; safe to invoke ad-hoc.
+    async fn delete_expired(&self, cutoff: DateTime<Utc>) -> DbResult<u64>;
+}
diff --git a/src/db/repos/mod.rs b/src/db/repos/mod.rs
index 2412f5a..55b6fab 100644
--- a/src/db/repos/mod.rs
+++ b/src/db/repos/mod.rs
@@ -1,10 +1,13 @@
 mod api_keys;
 mod audit_logs;
+mod containers;
 mod conversations;
 pub mod cursor;
 #[cfg(feature = "sso")]
 mod domain_verifications;
 mod files;
+#[cfg(feature = "mcp")]
+mod mcp_pending_approvals;
 mod model_pricing;
 mod oauth_authorization_codes;
 mod org_rbac_policies;
@@ -13,6 +16,8 @@ mod org_sso_configs;
 mod organizations;
 mod projects;
 mod providers;
+mod response_events;
+mod responses;
 #[cfg(feature = "sso")]
 mod scim_configs;
 #[cfg(feature = "sso")]
@@ -32,11 +37,14 @@ mod vector_stores;
 pub use api_keys::*;
 pub use audit_logs::*;
 use chrono::NaiveDate;
+pub use containers::*;
 pub use conversations::*;
 pub use cursor::*;
 #[cfg(feature = "sso")]
 pub use domain_verifications::*;
 pub use files::*;
+#[cfg(feature = "mcp")]
+pub use mcp_pending_approvals::*;
 pub use model_pricing::*;
 pub use oauth_authorization_codes::*;
 pub use org_rbac_policies::*;
@@ -45,6 +53,8 @@ pub use org_sso_configs::*;
 pub use organizations::*;
 pub use projects::*;
 pub use providers::*;
+pub use response_events::*;
+pub use responses::*;
 #[cfg(feature = "sso")]
 pub use scim_configs::*;
 #[cfg(feature = "sso")]
diff --git a/src/db/repos/response_events.rs b/src/db/repos/response_events.rs
new file mode 100644
index 0000000..14d798d
--- /dev/null
+++ b/src/db/repos/response_events.rs
@@ -0,0 +1,53 @@
+//! Append-only event log for in-flight Responses API streams.
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use serde_json::Value;
+
+use crate::db::error::DbResult;
+
+/// One row in `response_events`. Owned representation; the wire
+/// format emitted by the replay endpoint is the same JSON as the
+/// live SSE stream, so callers serialize `payload` directly.
+#[derive(Debug, Clone)]
+pub struct ResponseEvent {
+    pub response_id: String,
+    pub sequence_number: i64,
+    pub event_type: String,
+    pub payload: Value,
+    pub created_at: DateTime<Utc>,
+}
+
+/// Fields supplied by the streaming pipeline when persisting one
+/// event. `sequence_number` is gateway-authoritative — assigned in
+/// order as events flow to the client, so retries don't create gaps.
+#[derive(Debug, Clone)]
+pub struct NewResponseEvent {
+    pub response_id: String,
+    pub sequence_number: i64,
+    pub event_type: String,
+    pub payload: Value,
+    pub created_at: DateTime<Utc>,
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+pub trait ResponseEventsRepo: Send + Sync {
+    /// Batch-insert events. Conflicts on the (response_id,
+    /// sequence_number) PK are ignored — the buffer may double-flush
+    /// on retry and the DB enforces idempotency.
+    async fn insert_batch(&self, events: Vec<NewResponseEvent>) -> DbResult<u64>;
+
+    /// Return events for a response with sequence_number > `after`,
+    /// in ascending order, up to `limit`.
+    async fn list_after(
+        &self,
+        response_id: &str,
+        after: i64,
+        limit: i64,
+    ) -> DbResult<Vec<ResponseEvent>>;
+
+    /// Update the parent `responses.last_sequence_number` so the
+    /// replay endpoint knows when there's nothing more coming.
+    async fn set_last_sequence(&self, response_id: &str, seq: i64) -> DbResult<()>;
+}
diff --git a/src/db/repos/responses.rs b/src/db/repos/responses.rs
new file mode 100644
index 0000000..20aac79
--- /dev/null
+++ b/src/db/repos/responses.rs
@@ -0,0 +1,377 @@
+//! Persistence repo for the Responses API.
+//!
+//! Stores rows the gateway emits per request when `store=true` (the
+//! default per OpenAI's spec). Powers `GET /v1/responses/{id}`,
+//! `POST /v1/responses/{id}/cancel`, `DELETE /v1/responses/{id}`, and
+//! the background-mode poll/replay flows.
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use serde_json::Value;
+use uuid::Uuid;
+
+use crate::db::error::DbResult;
+
+/// Ownership scope for a stored response. Mirrors the pattern used
+/// by `skills`, `templates`, `conversations` etc.: every row is owned
+/// by one of organization/team/project/user/service-account, and
+/// reads cascade through the org-scope filter so any caller in the
+/// same org with the right RBAC can retrieve it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResponseOwnerType {
+    Organization,
+    Team,
+    Project,
+    User,
+    ServiceAccount,
+}
+
+impl ResponseOwnerType {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Organization => "organization",
+            Self::Team => "team",
+            Self::Project => "project",
+            Self::User => "user",
+            Self::ServiceAccount => "service_account",
+        }
+    }
+
+    pub fn parse(s: &str) -> Option<Self> {
+        match s {
+            "organization" => Some(Self::Organization),
+            "team" => Some(Self::Team),
+            "project" => Some(Self::Project),
+            "user" => Some(Self::User),
+            "service_account" => Some(Self::ServiceAccount),
+            _ => None,
+        }
+    }
+}
+
+/// Tagged owner specification — the canonical way to express
+/// "<scope, id>" in code. Repos consume the flat
+/// (`owner_type`, `owner_id`) pair; this enum is what handlers build
+/// when deriving an owner from the calling principal.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResponseOwner {
+    Organization(Uuid),
+    Team(Uuid),
+    Project(Uuid),
+    User(Uuid),
+    ServiceAccount(Uuid),
+}
+
+impl ResponseOwner {
+    pub fn owner_type(&self) -> ResponseOwnerType {
+        match self {
+            Self::Organization(_) => ResponseOwnerType::Organization,
+            Self::Team(_) => ResponseOwnerType::Team,
+            Self::Project(_) => ResponseOwnerType::Project,
+            Self::User(_) => ResponseOwnerType::User,
+            Self::ServiceAccount(_) => ResponseOwnerType::ServiceAccount,
+        }
+    }
+
+    pub fn owner_id(&self) -> Uuid {
+        match self {
+            Self::Organization(id)
+            | Self::Team(id)
+            | Self::Project(id)
+            | Self::User(id)
+            | Self::ServiceAccount(id) => *id,
+        }
+    }
+
+    /// Rebuild an owner from the flat (`owner_type`, `owner_id`) pair a
+    /// repo row stores.
+    pub fn from_parts(owner_type: ResponseOwnerType, owner_id: Uuid) -> Self {
+        match owner_type {
+            ResponseOwnerType::Organization => Self::Organization(owner_id),
+            ResponseOwnerType::Team => Self::Team(owner_id),
+            ResponseOwnerType::Project => Self::Project(owner_id),
+            ResponseOwnerType::User => Self::User(owner_id),
+            ResponseOwnerType::ServiceAccount => Self::ServiceAccount(owner_id),
+        }
+    }
+
+    /// Map to the Files / Vector-Store owner pair used for tenant
+    /// scoping. Returns `None` for `ServiceAccount`, which has no
+    /// file-owner equivalent (files are owned by org/team/project/user) —
+    /// callers treat `None` as "no file is in this scope" and fail
+    /// closed, so a service-account-owned request can't reference
+    /// Files-API uploads by id.
+    pub fn as_file_owner(&self) -> Option<(crate::models::VectorStoreOwnerType, Uuid)> {
+        use crate::models::VectorStoreOwnerType as V;
+        match self {
+            Self::Organization(id) => Some((V::Organization, *id)),
+            Self::Team(id) => Some((V::Team, *id)),
+            Self::Project(id) => Some((V::Project, *id)),
+            Self::User(id) => Some((V::User, *id)),
+            Self::ServiceAccount(_) => None,
+        }
+    }
+}
+
+/// Lifecycle states for a stored response, mirroring OpenAI's
+/// `ResponsesResponseStatus`. The wire-format strings match exactly so
+/// the column can be deserialized directly into the API type.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResponseStatus {
+    Queued,
+    InProgress,
+    Completed,
+    Failed,
+    Cancelled,
+    Incomplete,
+}
+
+impl ResponseStatus {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Queued => "queued",
+            Self::InProgress => "in_progress",
+            Self::Completed => "completed",
+            Self::Failed => "failed",
+            Self::Cancelled => "cancelled",
+            Self::Incomplete => "incomplete",
+        }
+    }
+
+    pub fn parse(s: &str) -> Option<Self> {
+        match s {
+            "queued" => Some(Self::Queued),
+            "in_progress" => Some(Self::InProgress),
+            "completed" => Some(Self::Completed),
+            "failed" => Some(Self::Failed),
+            "cancelled" => Some(Self::Cancelled),
+            "incomplete" => Some(Self::Incomplete),
+            _ => None,
+        }
+    }
+
+    /// Terminal states no longer accept status transitions and are
+    /// eligible for retention-based cleanup.
+    pub fn is_terminal(&self) -> bool {
+        matches!(
+            self,
+            Self::Completed | Self::Failed | Self::Cancelled | Self::Incomplete
+        )
+    }
+}
+
+/// A persisted Responses API record.
+///
+/// `request_payload`, `output`, `usage`, and `error` are kept as
+/// opaque JSON values so the API surface can evolve without further
+/// migrations. The route handler is responsible for stitching these
+/// back into a `CreateResponsesResponse` for the wire.
+#[derive(Debug, Clone)]
+pub struct ResponseRecord {
+    pub id: String,
+    pub org_id: Uuid,
+    /// Ownership scope. Determines which scope's listing the row
+    /// shows up in; reads / writes / deletes cascade through the org
+    /// the owner belongs to.
+    pub owner_type: ResponseOwnerType,
+    pub owner_id: Uuid,
+    /// Audit field: which project's API key (if any) made the call.
+    /// Distinct from ownership — an API key bound to a project can
+    /// submit a response owned by the user, for instance.
+    pub project_id: Option<Uuid>,
+    pub user_id: Option<Uuid>,
+    pub api_key_id: Option<Uuid>,
+    pub service_account_id: Option<Uuid>,
+    pub status: ResponseStatus,
+    pub background: bool,
+    pub model: String,
+    pub provider: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub completed_at: Option<DateTime<Utc>>,
+    pub request_payload: Value,
+    pub output: Option<Value>,
+    pub usage: Option<Value>,
+    pub error: Option<Value>,
+    pub retention_expires_at: DateTime<Utc>,
+    /// Highest event sequence_number persisted. Set by the event
+    /// buffer drainer on each batch flush.
+    pub last_sequence_number: i64,
+    /// Liveness heartbeat for `in_progress` rows, stamped periodically
+    /// by the executing worker. `None` until the first heartbeat (the
+    /// reaper falls back to `started_at`).
+    pub last_heartbeat_at: Option<DateTime<Utc>>,
+    /// Container the shell-tool session for this response was attached
+    /// to. `None` when the request had no shell tool, when containers
+    /// persistence is disabled, or before the shell tool first runs.
+    /// Drives `previous_response_id`-based reuse: a chained response
+    /// looks here to find which container to reattach to.
+    pub container_id: Option<String>,
+}
+
+/// Fields needed to create a new response row at request-start time.
+#[derive(Debug, Clone)]
+pub struct NewResponse {
+    pub id: String,
+    pub org_id: Uuid,
+    pub owner_type: ResponseOwnerType,
+    pub owner_id: Uuid,
+    pub project_id: Option<Uuid>,
+    pub user_id: Option<Uuid>,
+    pub api_key_id: Option<Uuid>,
+    pub service_account_id: Option<Uuid>,
+    pub status: ResponseStatus,
+    pub background: bool,
+    pub model: String,
+    pub provider: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub request_payload: Value,
+    pub retention_expires_at: DateTime<Utc>,
+}
+
+/// Fields to patch into an existing row when the response reaches a
+/// terminal state.
+#[derive(Debug, Clone, Default)]
+pub struct ResponseCompletion {
+    pub status: Option<ResponseStatus>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub completed_at: Option<DateTime<Utc>>,
+    pub output: Option<Value>,
+    pub usage: Option<Value>,
+    pub error: Option<Value>,
+    pub retention_expires_at: Option<DateTime<Utc>>,
+    /// Container attached to this response. Patched in by the
+    /// streaming pipeline once a shell-tool session has been
+    /// provisioned (or reattached), so a follow-up request that
+    /// chains via `previous_response_id` can resolve the right
+    /// container.
+    pub container_id: Option<String>,
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+pub trait ResponsesRepo: Send + Sync {
+    /// Insert a new response row at request-start. Status is typically
+    /// `Queued` (for background) or `InProgress` (synchronous).
+    async fn insert(&self, input: NewResponse) -> DbResult<ResponseRecord>;
+
+    /// Org-scoped fetch by ID. Returns `None` when the row is missing
+    /// **or** belongs to a different org — the caller can't distinguish
+    /// the two cases, which prevents enumeration attacks. The `org_id`
+    /// is required: anonymous-mode deployments populate a synthetic
+    /// default via the auth middleware, so all reachable rows have a
+    /// non-NULL org.
+    async fn get_by_id_and_org(&self, id: &str, org_id: Uuid) -> DbResult<Option<ResponseRecord>>;
+
+    /// Patch lifecycle fields, scoped to a tenant. The repo applies
+    /// only the `Some` fields in `patch`, so callers can advance status
+    /// and set completed_at/output/usage in one call. Returns `None` if
+    /// no row matches `id` AND `org_id` — protects against cross-tenant
+    /// writes even when a caller has the ID.
+    async fn update_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ResponseCompletion,
+    ) -> DbResult<Option<ResponseRecord>>;
+
+    /// Like [`update_within_org`](Self::update_within_org) but the
+    /// UPDATE additionally requires the row's *current* status to be
+    /// non-terminal. Returns `Some(record)` only when this call actually
+    /// performed the transition; `None` when the row was already
+    /// terminal (a lost race) or doesn't match `org_id`.
+    ///
+    /// This makes terminal lifecycle transitions atomic at the DB layer:
+    /// a late `completed` write from the persister cannot clobber an
+    /// earlier `cancelled`, and the affected-row outcome is what drives
+    /// exactly-once webhook firing — never a read-then-write.
+    async fn complete_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ResponseCompletion,
+    ) -> DbResult<Option<ResponseRecord>>;
+
+    /// Stamp the liveness heartbeat for an `in_progress` row. No-op for
+    /// rows in any other status (so a late ping can't resurrect a
+    /// terminal row's heartbeat). Best-effort: drives the in-progress
+    /// reaper's dead-worker detection.
+    async fn touch_heartbeat(&self, id: &str, now: DateTime<Utc>) -> DbResult<()>;
+
+    /// Org-scoped delete. Returns true if a row was removed.
+    async fn delete_by_id_and_org(&self, id: &str, org_id: Uuid) -> DbResult<bool>;
+
+    /// Delete all rows past `before` whose status is terminal. Run by
+    /// the retention worker.
+    async fn delete_expired(&self, before: DateTime<Utc>) -> DbResult<u64>;
+
+    /// Atomically claim the next `queued` row, transitioning it to
+    /// `in_progress` and stamping `started_at`. Returns `None` when
+    /// nothing is queued. Multi-worker-safe: SQLite uses
+    /// `UPDATE … RETURNING` against the rowid SELECT; Postgres uses
+    /// `SELECT … FOR UPDATE SKIP LOCKED` so concurrent workers never
+    /// claim the same row.
+    async fn claim_queued(&self, now: DateTime<Utc>) -> DbResult<Option<ResponseRecord>>;
+
+    /// Given a set of in-flight response IDs, return the subset whose
+    /// `status='cancelled'`. Used by the cross-replica cancel poller
+    /// to detect cancels issued on a *different* replica than the one
+    /// executing the response. One batched query per poll cycle
+    /// regardless of in-flight count.
+    async fn list_cancelled_among(&self, ids: &[String]) -> DbResult<Vec<String>>;
+
+    /// Mark rows in `in_progress` whose `started_at` is older than
+    /// `started_before` as `failed`, stamping a `worker_lost` error
+    /// payload. Returns the number of rows updated. Called by the
+    /// reaper to recover from worker crashes — without this, a row
+    /// claimed by a worker that died mid-execution would stay in
+    /// `in_progress` forever (`claim_queued` only picks `queued`).
+    async fn reap_stuck_in_progress(
+        &self,
+        started_before: DateTime<Utc>,
+        completed_at: DateTime<Utc>,
+        retention_expires_at: DateTime<Utc>,
+    ) -> DbResult<u64>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::VectorStoreOwnerType as V;
+
+    #[test]
+    fn response_owner_maps_to_file_owner_for_tenant_scoping() {
+        let id = Uuid::new_v4();
+        // Org/team/project/user map straight across.
+        assert_eq!(
+            ResponseOwner::Organization(id).as_file_owner(),
+            Some((V::Organization, id))
+        );
+        assert_eq!(ResponseOwner::Team(id).as_file_owner(), Some((V::Team, id)));
+        assert_eq!(
+            ResponseOwner::Project(id).as_file_owner(),
+            Some((V::Project, id))
+        );
+        assert_eq!(ResponseOwner::User(id).as_file_owner(), Some((V::User, id)));
+        // Service accounts have no file-owner equivalent → fail closed:
+        // an SA-owned request can't reference Files-API uploads by id.
+        assert_eq!(ResponseOwner::ServiceAccount(id).as_file_owner(), None);
+    }
+
+    #[test]
+    fn response_owner_from_parts_roundtrips() {
+        let id = Uuid::new_v4();
+        for owner in [
+            ResponseOwner::Organization(id),
+            ResponseOwner::Team(id),
+            ResponseOwner::Project(id),
+            ResponseOwner::User(id),
+            ResponseOwner::ServiceAccount(id),
+        ] {
+            assert_eq!(
+                ResponseOwner::from_parts(owner.owner_type(), owner.owner_id()),
+                owner
+            );
+        }
+    }
+}
diff --git a/src/db/sqlite/containers.rs b/src/db/sqlite/containers.rs
new file mode 100644
index 0000000..46a74f5
--- /dev/null
+++ b/src/db/sqlite/containers.rs
@@ -0,0 +1,522 @@
+//! SQLite implementation of [`ContainersRepo`].
+
+use async_trait::async_trait;
+
+use super::{
+    backend::{Pool, RowExt, begin, query},
+    common::parse_uuid,
+};
+use crate::db::{
+    error::{DbError, DbResult},
+    repos::{
+        ContainerFileRecord, ContainerFileSourceKind, ContainerPatch, ContainerRecord,
+        ContainerStatus, ContainersRepo, DeletedFileObject, HardDeleteExpiredOutcome, NewContainer,
+        NewContainerFile, ResponseOwnerType, truncate_to_millis,
+    },
+};
+
+const CONTAINER_COLUMNS: &str = "id, org_id, owner_type, owner_id, status, runtime_label, \
+    source_response_id, idle_ttl_secs, last_active_at, created_at, expires_at, \
+    name, memory_limit_mb, network_policy_json, skill_ids_json";
+
+const CONTAINER_FILE_COLUMNS: &str = "id, container_id, org_id, path, filename, size_bytes, \
+    content_type, content_hash, source, storage_backend, storage_path, \
+    source_response_id, source_call_id, created_at";
+
+pub struct SqliteContainersRepo {
+    pool: Pool,
+}
+
+impl SqliteContainersRepo {
+    pub fn new(pool: Pool) -> Self {
+        Self { pool }
+    }
+}
+
+fn parse_status(s: &str) -> DbResult<ContainerStatus> {
+    ContainerStatus::parse(s)
+        .ok_or_else(|| DbError::Internal(format!("unknown container status: {s}")))
+}
+
+fn parse_owner_type(s: &str) -> DbResult<ResponseOwnerType> {
+    ResponseOwnerType::parse(s)
+        .ok_or_else(|| DbError::Internal(format!("unknown container owner_type: {s}")))
+}
+
+fn parse_source(s: &str) -> DbResult<ContainerFileSourceKind> {
+    ContainerFileSourceKind::parse(s)
+        .ok_or_else(|| DbError::Internal(format!("unknown container_file source: {s}")))
+}
+
+fn parse_storage_backend(s: &str) -> DbResult<crate::models::StorageBackend> {
+    s.parse::<crate::models::StorageBackend>()
+        .map_err(DbError::Internal)
+}
+
+fn row_to_container(row: &super::backend::Row) -> DbResult<ContainerRecord> {
+    Ok(ContainerRecord {
+        id: row.col("id"),
+        org_id: parse_uuid(&row.col::<String>("org_id"))?,
+        owner_type: parse_owner_type(&row.col::<String>("owner_type"))?,
+        owner_id: parse_uuid(&row.col::<String>("owner_id"))?,
+        status: parse_status(&row.col::<String>("status"))?,
+        runtime_label: row.col("runtime_label"),
+        source_response_id: row.col("source_response_id"),
+        idle_ttl_secs: row.col("idle_ttl_secs"),
+        last_active_at: row.col("last_active_at"),
+        created_at: row.col("created_at"),
+        expires_at: row.col("expires_at"),
+        name: row.col("name"),
+        memory_limit_mb: row.col("memory_limit_mb"),
+        network_policy_json: row.col("network_policy_json"),
+        skill_ids_json: row.col("skill_ids_json"),
+    })
+}
+
+fn row_to_file(row: &super::backend::Row) -> DbResult<ContainerFileRecord> {
+    Ok(ContainerFileRecord {
+        id: row.col("id"),
+        container_id: row.col("container_id"),
+        org_id: parse_uuid(&row.col::<String>("org_id"))?,
+        path: row.col("path"),
+        filename: row.col("filename"),
+        size_bytes: row.col("size_bytes"),
+        content_type: row.col("content_type"),
+        content_hash: row.col("content_hash"),
+        source: parse_source(&row.col::<String>("source"))?,
+        storage_backend: parse_storage_backend(&row.col::<String>("storage_backend"))?,
+        storage_path: row.col("storage_path"),
+        source_response_id: row.col("source_response_id"),
+        source_call_id: row.col("source_call_id"),
+        created_at: row.col("created_at"),
+    })
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+impl ContainersRepo for SqliteContainersRepo {
+    async fn insert(&self, input: NewContainer) -> DbResult<ContainerRecord> {
+        let created_at = truncate_to_millis(input.created_at);
+        let last_active_at = created_at;
+
+        query(
+            r#"
+            INSERT INTO containers (
+                id, org_id, owner_type, owner_id, status, runtime_label,
+                source_response_id, idle_ttl_secs, last_active_at, created_at,
+                name, memory_limit_mb, network_policy_json, skill_ids_json
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            "#,
+        )
+        .bind(&input.id)
+        .bind(input.org_id.to_string())
+        .bind(input.owner_type.as_str())
+        .bind(input.owner_id.to_string())
+        .bind(input.status.as_str())
+        .bind(&input.runtime_label)
+        .bind(&input.source_response_id)
+        .bind(input.idle_ttl_secs)
+        .bind(last_active_at)
+        .bind(created_at)
+        .bind(&input.name)
+        .bind(input.memory_limit_mb)
+        .bind(&input.network_policy_json)
+        .bind(&input.skill_ids_json)
+        .execute(&self.pool)
+        .await?;
+
+        Ok(ContainerRecord {
+            id: input.id,
+            org_id: input.org_id,
+            owner_type: input.owner_type,
+            owner_id: input.owner_id,
+            status: input.status,
+            runtime_label: input.runtime_label,
+            source_response_id: input.source_response_id,
+            idle_ttl_secs: input.idle_ttl_secs,
+            last_active_at,
+            created_at,
+            expires_at: None,
+            name: input.name,
+            memory_limit_mb: input.memory_limit_mb,
+            network_policy_json: input.network_policy_json,
+            skill_ids_json: input.skill_ids_json,
+        })
+    }
+
+    async fn get_by_id_and_org(
+        &self,
+        id: &str,
+        org_id: uuid::Uuid,
+    ) -> DbResult<Option<ContainerRecord>> {
+        let sql = format!("SELECT {CONTAINER_COLUMNS} FROM containers WHERE id = ? AND org_id = ?");
+        let row = query(&sql)
+            .bind(id)
+            .bind(org_id.to_string())
+            .fetch_optional(&self.pool)
+            .await?;
+        row.map(|r| row_to_container(&r)).transpose()
+    }
+
+    async fn list_by_org(
+        &self,
+        org_id: uuid::Uuid,
+        limit: i64,
+        after: Option<&str>,
+    ) -> DbResult<Vec<ContainerRecord>> {
+        // SQLite stores TEXT timestamps; the `truncate_to_millis` call
+        // on `insert` makes the lexical `<` comparison match the
+        // chronological one. Correlated subquery resolves `after` to a
+        // `(created_at, id)` keyset; cross-org / unknown ids yield NULL
+        // and the comparison shorts to no match.
+        let sql = format!(
+            r#"
+            SELECT {CONTAINER_COLUMNS} FROM containers
+            WHERE org_id = ?
+              AND (
+                ?2 IS NULL
+                OR (created_at, id) < (
+                  SELECT created_at, id FROM containers
+                  WHERE id = ?2 AND org_id = ?1
+                )
+              )
+            ORDER BY created_at DESC, id DESC
+            LIMIT ?3
+            "#
+        );
+        let rows = query(&sql)
+            .bind(org_id.to_string())
+            .bind(after)
+            .bind(limit)
+            .fetch_all(&self.pool)
+            .await?;
+        rows.iter().map(row_to_container).collect()
+    }
+
+    async fn upsert_file(&self, input: NewContainerFile) -> DbResult<ContainerFileRecord> {
+        let created_at = truncate_to_millis(input.created_at);
+
+        // ON CONFLICT (container_id, path) DO UPDATE — keeps the
+        // existing row's id so any `container_file_citation` annotation
+        // emitted before the overwrite still resolves to the latest
+        // bytes. The replacement row uses the OLD id even if the
+        // caller passed a new one.
+        query(
+            r#"
+            INSERT INTO container_files (
+                id, container_id, org_id, path, filename, size_bytes,
+                content_type, content_hash, source, storage_backend,
+                file_data, storage_path, source_response_id, source_call_id, created_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(container_id, path) DO UPDATE SET
+                filename = excluded.filename,
+                size_bytes = excluded.size_bytes,
+                content_type = excluded.content_type,
+                content_hash = excluded.content_hash,
+                source = excluded.source,
+                storage_backend = excluded.storage_backend,
+                file_data = excluded.file_data,
+                storage_path = excluded.storage_path,
+                source_response_id = excluded.source_response_id,
+                source_call_id = excluded.source_call_id,
+                created_at = excluded.created_at
+            "#,
+        )
+        .bind(&input.id)
+        .bind(&input.container_id)
+        .bind(input.org_id.to_string())
+        .bind(&input.path)
+        .bind(&input.filename)
+        .bind(input.size_bytes)
+        .bind(&input.content_type)
+        .bind(&input.content_hash)
+        .bind(input.source.as_str())
+        .bind(input.storage_backend.as_str())
+        .bind(&input.file_data)
+        .bind(&input.storage_path)
+        .bind(&input.source_response_id)
+        .bind(&input.source_call_id)
+        .bind(created_at)
+        .execute(&self.pool)
+        .await?;
+
+        // Re-read so we return the canonical row (in particular the
+        // pre-existing `id` when an upsert hit a conflict).
+        let sql = format!(
+            "SELECT {CONTAINER_FILE_COLUMNS} FROM container_files \
+             WHERE container_id = ? AND path = ?"
+        );
+        let row = query(&sql)
+            .bind(&input.container_id)
+            .bind(&input.path)
+            .fetch_one(&self.pool)
+            .await?;
+        row_to_file(&row)
+    }
+
+    async fn get_file_by_id_and_org(
+        &self,
+        file_id: &str,
+        org_id: uuid::Uuid,
+    ) -> DbResult<Option<ContainerFileRecord>> {
+        let sql = format!(
+            "SELECT {CONTAINER_FILE_COLUMNS} FROM container_files \
+             WHERE id = ? AND org_id = ?"
+        );
+        let row = query(&sql)
+            .bind(file_id)
+            .bind(org_id.to_string())
+            .fetch_optional(&self.pool)
+            .await?;
+        row.map(|r| row_to_file(&r)).transpose()
+    }
+
+    async fn read_file_data(&self, file_id: &str, org_id: uuid::Uuid) -> DbResult<Option<Vec<u8>>> {
+        let row = query(
+            r#"
+            SELECT file_data
+            FROM container_files
+            WHERE id = ? AND org_id = ?
+            "#,
+        )
+        .bind(file_id)
+        .bind(org_id.to_string())
+        .fetch_optional(&self.pool)
+        .await?;
+        Ok(row.and_then(|r| r.col::<Option<Vec<u8>>>("file_data")))
+    }
+
+    async fn list_files_by_container(
+        &self,
+        container_id: &str,
+        org_id: uuid::Uuid,
+        limit: i64,
+    ) -> DbResult<Vec<ContainerFileRecord>> {
+        let clamped = limit.clamp(1, 1000);
+        let sql = format!(
+            "SELECT {CONTAINER_FILE_COLUMNS} FROM container_files \
+             WHERE container_id = ? AND org_id = ? \
+             ORDER BY created_at DESC, id DESC \
+             LIMIT ?"
+        );
+        let rows = query(&sql)
+            .bind(container_id)
+            .bind(org_id.to_string())
+            .bind(clamped)
+            .fetch_all(&self.pool)
+            .await?;
+        rows.iter().map(row_to_file).collect()
+    }
+
+    async fn list_files_for_replay(
+        &self,
+        container_id: &str,
+    ) -> DbResult<Vec<ContainerFileRecord>> {
+        let sql = format!(
+            "SELECT {CONTAINER_FILE_COLUMNS} FROM container_files \
+             WHERE container_id = ? \
+             ORDER BY created_at DESC, id DESC"
+        );
+        let rows = query(&sql).bind(container_id).fetch_all(&self.pool).await?;
+        rows.iter().map(row_to_file).collect()
+    }
+
+    async fn read_file_data_for_replay(
+        &self,
+        container_id: &str,
+        file_id: &str,
+    ) -> DbResult<Option<Vec<u8>>> {
+        let row = query(
+            r#"
+            SELECT file_data
+            FROM container_files
+            WHERE container_id = ? AND id = ?
+            "#,
+        )
+        .bind(container_id)
+        .bind(file_id)
+        .fetch_optional(&self.pool)
+        .await?;
+        Ok(row.and_then(|r| r.col::<Option<Vec<u8>>>("file_data")))
+    }
+
+    async fn update_within_org(
+        &self,
+        id: &str,
+        org_id: uuid::Uuid,
+        patch: ContainerPatch,
+    ) -> DbResult<Option<ContainerRecord>> {
+        let mut setters: Vec<&str> = Vec::new();
+        if patch.status.is_some() {
+            setters.push("status = ?");
+        }
+        if patch.last_active_at.is_some() {
+            setters.push("last_active_at = ?");
+        }
+        if patch.expires_at.is_some() {
+            setters.push("expires_at = ?");
+        }
+        if setters.is_empty() {
+            return self.get_by_id_and_org(id, org_id).await;
+        }
+        let sql = format!(
+            "UPDATE containers SET {set} WHERE id = ? AND org_id = ? \
+             RETURNING {CONTAINER_COLUMNS}",
+            set = setters.join(", "),
+        );
+        let mut q = query(&sql);
+        if let Some(s) = patch.status {
+            q = q.bind(s.as_str().to_string());
+        }
+        if let Some(ts) = patch.last_active_at {
+            q = q.bind(truncate_to_millis(ts));
+        }
+        if let Some(ts) = patch.expires_at {
+            q = q.bind(truncate_to_millis(ts));
+        }
+        q = q.bind(id).bind(org_id.to_string());
+        let row = q.fetch_optional(&self.pool).await?;
+        row.as_ref().map(row_to_container).transpose()
+    }
+
+    async fn delete_file_by_id_and_org(
+        &self,
+        file_id: &str,
+        container_id: &str,
+        org_id: uuid::Uuid,
+    ) -> DbResult<bool> {
+        let res = query(
+            r#"
+            DELETE FROM container_files
+            WHERE id = ? AND container_id = ? AND org_id = ?
+            "#,
+        )
+        .bind(file_id)
+        .bind(container_id)
+        .bind(org_id.to_string())
+        .execute(&self.pool)
+        .await?;
+        Ok(res.rows_affected() > 0)
+    }
+
+    async fn mark_expired_idle(&self, now: chrono::DateTime<chrono::Utc>) -> DbResult<Vec<String>> {
+        let now_ts = truncate_to_millis(now);
+        // SQLite's `datetime(x, '+N seconds')` strips fractional
+        // seconds and the timezone suffix, returning `YYYY-MM-DD HH:MM:SS`.
+        // sqlx-sqlite encodes a bound `DateTime<Utc>` as `YYYY-MM-DD
+        // HH:MM:SS.fff+00:00`. The two strings share the same date+time
+        // prefix but differ in suffix length, so a raw lex-comparison
+        // can trip ~1 ms early at the boundary. Wrap the bound value
+        // in `datetime()` too so both sides go through the same
+        // normalization and the comparison is apples-to-apples.
+        let rows = query(
+            r#"
+            UPDATE containers
+            SET status = 'expired', expires_at = ?
+            WHERE status = 'active'
+              AND datetime(last_active_at, '+' || idle_ttl_secs || ' seconds')
+                  < datetime(?)
+            RETURNING id
+            "#,
+        )
+        .bind(now_ts)
+        .bind(now_ts)
+        .fetch_all(&self.pool)
+        .await?;
+        Ok(rows.iter().map(|r| r.col("id")).collect())
+    }
+
+    async fn expired_among(&self, ids: &[String]) -> DbResult<Vec<String>> {
+        if ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        // SQLite has no ANY(array) operator, so build a placeholder
+        // list. Bounded by the caller (the local registry size).
+        let placeholders = vec!["?"; ids.len()].join(",");
+        let sql = format!(
+            "SELECT id FROM containers \
+             WHERE status IN ('expired', 'deleted') AND id IN ({placeholders})"
+        );
+        let mut q = query(&sql);
+        for id in ids {
+            q = q.bind(id);
+        }
+        let rows = q.fetch_all(&self.pool).await?;
+        Ok(rows.iter().map(|r| r.col::<String>("id")).collect())
+    }
+
+    async fn hard_delete_expired(
+        &self,
+        cutoff: chrono::DateTime<chrono::Utc>,
+        limit: i64,
+    ) -> DbResult<HardDeleteExpiredOutcome> {
+        // `expires_at` is a TEXT timestamp; `truncate_to_millis` keeps the
+        // bound value in the same `YYYY-MM-DD HH:MM:SS.fff+00:00` shape the
+        // column was written with, and wrapping both sides in `datetime()`
+        // normalizes the suffix the same way `mark_expired_idle` does so the
+        // boundary comparison is apples-to-apples.
+        let cutoff_ts = truncate_to_millis(cutoff);
+        // Wrap the select-then-delete in a transaction so a mid-loop failure
+        // can't leave a partially-deleted batch, and so the captured
+        // external-storage refs are consistent with the rows we remove. We
+        // delete `container_files` explicitly because the test harness pool
+        // doesn't enable `PRAGMA foreign_keys`, so the `ON DELETE CASCADE`
+        // can't be relied on.
+        let mut tx = begin(&self.pool).await?;
+        let rows = query(
+            r#"
+            SELECT id FROM containers
+            WHERE status IN ('expired', 'deleted')
+              AND expires_at IS NOT NULL
+              AND datetime(expires_at) <= datetime(?)
+            -- Oldest-expired first: a full backlog must not starve the
+            -- earliest terminal rows by repeatedly deleting the newest.
+            ORDER BY expires_at ASC
+            LIMIT ?
+            "#,
+        )
+        .bind(cutoff_ts)
+        .bind(limit)
+        .fetch_all(&mut *tx)
+        .await?;
+        let ids: Vec<String> = rows.iter().map(|r| r.col("id")).collect();
+        if ids.is_empty() {
+            tx.commit().await?;
+            return Ok(HardDeleteExpiredOutcome::default());
+        }
+
+        let mut file_objects = Vec::new();
+        for id in &ids {
+            let file_rows = query(
+                "SELECT id, storage_backend, storage_path \
+                 FROM container_files WHERE container_id = ?",
+            )
+            .bind(id)
+            .fetch_all(&mut *tx)
+            .await?;
+            for r in &file_rows {
+                file_objects.push(DeletedFileObject {
+                    file_id: r.col("id"),
+                    storage_backend: parse_storage_backend(&r.col::<String>("storage_backend"))?,
+                    storage_path: r.col::<Option<String>>("storage_path"),
+                });
+            }
+            query("DELETE FROM container_files WHERE container_id = ?")
+                .bind(id)
+                .execute(&mut *tx)
+                .await?;
+            query("DELETE FROM containers WHERE id = ?")
+                .bind(id)
+                .execute(&mut *tx)
+                .await?;
+        }
+        tx.commit().await?;
+
+        Ok(HardDeleteExpiredOutcome {
+            container_ids: ids,
+            file_objects,
+        })
+    }
+}
diff --git a/src/db/sqlite/mcp_pending_approvals.rs b/src/db/sqlite/mcp_pending_approvals.rs
new file mode 100644
index 0000000..b1964c4
--- /dev/null
+++ b/src/db/sqlite/mcp_pending_approvals.rs
@@ -0,0 +1,111 @@
+//! SQLite implementation of [`McpPendingApprovalsRepo`].
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+
+use super::{
+    backend::{Pool, RowExt, query},
+    common::parse_uuid,
+};
+use crate::db::{
+    error::DbResult,
+    repos::{
+        McpPendingApproval, McpPendingApprovalsRepo, NewMcpPendingApproval, truncate_to_millis,
+    },
+};
+
+pub struct SqliteMcpPendingApprovalsRepo {
+    pool: Pool,
+}
+
+impl SqliteMcpPendingApprovalsRepo {
+    pub fn new(pool: Pool) -> Self {
+        Self { pool }
+    }
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+impl McpPendingApprovalsRepo for SqliteMcpPendingApprovalsRepo {
+    async fn insert(&self, row: NewMcpPendingApproval) -> DbResult<()> {
+        query(
+            r#"
+            INSERT INTO mcp_pending_approvals (
+                id, response_id, org_id, call_id,
+                server_label, server_url, tool_name,
+                arguments_json, created_at, expires_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            "#,
+        )
+        .bind(&row.id)
+        .bind(&row.response_id)
+        .bind(row.org_id.to_string())
+        .bind(&row.call_id)
+        .bind(&row.server_label)
+        .bind(&row.server_url)
+        .bind(&row.tool_name)
+        .bind(&row.arguments_json)
+        .bind(truncate_to_millis(row.created_at))
+        .bind(truncate_to_millis(row.expires_at))
+        .execute(&self.pool)
+        .await?;
+        Ok(())
+    }
+
+    async fn take_by_id_and_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        now: DateTime<Utc>,
+    ) -> DbResult<Option<McpPendingApproval>> {
+        // DELETE … RETURNING claims the row atomically: a concurrent
+        // resume of the same id deletes nothing and gets `None`, so only
+        // one caller executes the gated tool. The `expires_at > ?` guard
+        // makes an expired approval unclaimable even before the retention
+        // worker sweeps it.
+        let row = query(
+            r#"
+            DELETE FROM mcp_pending_approvals
+            WHERE id = ? AND org_id = ? AND expires_at > ?
+            RETURNING id, response_id, org_id, call_id,
+                      server_label, server_url, tool_name,
+                      arguments_json, created_at, expires_at
+            "#,
+        )
+        .bind(id)
+        .bind(org_id.to_string())
+        .bind(truncate_to_millis(now))
+        .fetch_optional(&self.pool)
+        .await?;
+
+        let Some(r) = row else { return Ok(None) };
+        let org_id_str: String = r.col("org_id");
+        Ok(Some(McpPendingApproval {
+            id: r.col("id"),
+            response_id: r.col("response_id"),
+            org_id: parse_uuid(&org_id_str)?,
+            call_id: r.col("call_id"),
+            server_label: r.col("server_label"),
+            server_url: r.col("server_url"),
+            tool_name: r.col("tool_name"),
+            arguments_json: r.col("arguments_json"),
+            created_at: r.col::<DateTime<Utc>>("created_at"),
+            expires_at: r.col::<DateTime<Utc>>("expires_at"),
+        }))
+    }
+
+    async fn delete_expired(&self, cutoff: DateTime<Utc>) -> DbResult<u64> {
+        let result = query(
+            r#"
+            DELETE FROM mcp_pending_approvals
+            WHERE expires_at < ?
+            "#,
+        )
+        .bind(truncate_to_millis(cutoff))
+        .execute(&self.pool)
+        .await?;
+        Ok(result.rows_affected())
+    }
+}
diff --git a/src/db/sqlite/mod.rs b/src/db/sqlite/mod.rs
index 3e59ab1..5ec1386 100644
--- a/src/db/sqlite/mod.rs
+++ b/src/db/sqlite/mod.rs
@@ -2,10 +2,13 @@ mod api_keys;
 mod audit_logs;
 pub(crate) mod backend;
 mod common;
+mod containers;
 mod conversations;
 #[cfg(feature = "sso")]
 mod domain_verifications;
 mod files;
+#[cfg(feature = "mcp")]
+mod mcp_pending_approvals;
 mod model_pricing;
 mod oauth_authorization_codes;
 mod org_rbac_policies;
@@ -14,6 +17,8 @@ mod org_sso_configs;
 mod organizations;
 mod projects;
 mod providers;
+mod response_events;
+mod responses;
 #[cfg(feature = "sso")]
 mod scim_configs;
 #[cfg(feature = "sso")]
@@ -32,10 +37,13 @@ mod vector_stores;
 
 pub use api_keys::SqliteApiKeyRepo;
 pub use audit_logs::SqliteAuditLogRepo;
+pub use containers::SqliteContainersRepo;
 pub use conversations::SqliteConversationRepo;
 #[cfg(feature = "sso")]
 pub use domain_verifications::SqliteDomainVerificationRepo;
 pub use files::SqliteFilesRepo;
+#[cfg(feature = "mcp")]
+pub use mcp_pending_approvals::SqliteMcpPendingApprovalsRepo;
 pub use model_pricing::SqliteModelPricingRepo;
 pub use oauth_authorization_codes::SqliteOAuthAuthorizationCodeRepo;
 pub use org_rbac_policies::SqliteOrgRbacPolicyRepo;
@@ -44,6 +52,8 @@ pub use org_sso_configs::SqliteOrgSsoConfigRepo;
 pub use organizations::SqliteOrganizationRepo;
 pub use projects::SqliteProjectRepo;
 pub use providers::SqliteDynamicProviderRepo;
+pub use response_events::SqliteResponseEventsRepo;
+pub use responses::SqliteResponsesRepo;
 #[cfg(feature = "sso")]
 pub use scim_configs::SqliteOrgScimConfigRepo;
 #[cfg(feature = "sso")]
diff --git a/src/db/sqlite/response_events.rs b/src/db/sqlite/response_events.rs
new file mode 100644
index 0000000..f226bc5
--- /dev/null
+++ b/src/db/sqlite/response_events.rs
@@ -0,0 +1,108 @@
+//! SQLite implementation of [`ResponseEventsRepo`].
+
+use async_trait::async_trait;
+use chrono::DateTime;
+
+use super::backend::{Pool, RowExt, query};
+use crate::db::{
+    error::DbResult,
+    repos::{NewResponseEvent, ResponseEvent, ResponseEventsRepo, truncate_to_millis},
+};
+
+pub struct SqliteResponseEventsRepo {
+    pool: Pool,
+}
+
+impl SqliteResponseEventsRepo {
+    pub fn new(pool: Pool) -> Self {
+        Self { pool }
+    }
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+impl ResponseEventsRepo for SqliteResponseEventsRepo {
+    async fn insert_batch(&self, events: Vec<NewResponseEvent>) -> DbResult<u64> {
+        if events.is_empty() {
+            return Ok(0);
+        }
+        // Each row uses 5 params. SQLite caps at 999 — stay under
+        // with a chunk of 100 (500 params).
+        const CHUNK: usize = 100;
+        let mut total = 0u64;
+        for chunk in events.chunks(CHUNK) {
+            let placeholders: Vec<&str> = chunk.iter().map(|_| "(?, ?, ?, ?, ?)").collect();
+            let sql = format!(
+                "INSERT OR IGNORE INTO response_events \
+                 (response_id, sequence_number, event_type, payload, created_at) \
+                 VALUES {}",
+                placeholders.join(", ")
+            );
+            let mut q = query(&sql);
+            for ev in chunk {
+                q = q
+                    .bind(&ev.response_id)
+                    .bind(ev.sequence_number)
+                    .bind(&ev.event_type)
+                    .bind(serde_json::to_string(&ev.payload)?)
+                    .bind(truncate_to_millis(ev.created_at));
+            }
+            let result = q.execute(&self.pool).await?;
+            total += result.rows_affected();
+        }
+        Ok(total)
+    }
+
+    async fn list_after(
+        &self,
+        response_id: &str,
+        after: i64,
+        limit: i64,
+    ) -> DbResult<Vec<ResponseEvent>> {
+        let rows = query(
+            r#"
+            SELECT response_id, sequence_number, event_type, payload, created_at
+            FROM response_events
+            WHERE response_id = ? AND sequence_number > ?
+            ORDER BY sequence_number ASC
+            LIMIT ?
+            "#,
+        )
+        .bind(response_id)
+        .bind(after)
+        .bind(limit)
+        .fetch_all(&self.pool)
+        .await?;
+
+        let mut out = Vec::with_capacity(rows.len());
+        for row in rows {
+            let payload_str: String = row.col("payload");
+            out.push(ResponseEvent {
+                response_id: row.col("response_id"),
+                sequence_number: row.col("sequence_number"),
+                event_type: row.col("event_type"),
+                payload: serde_json::from_str(&payload_str)?,
+                created_at: row.col::<DateTime<chrono::Utc>>("created_at"),
+            });
+        }
+        Ok(out)
+    }
+
+    async fn set_last_sequence(&self, response_id: &str, seq: i64) -> DbResult<()> {
+        // Only ratchet upward — concurrent batches may complete out of
+        // order; we never want a smaller sequence to overwrite a larger.
+        query(
+            r#"
+            UPDATE responses
+            SET last_sequence_number = ?
+            WHERE id = ? AND last_sequence_number < ?
+            "#,
+        )
+        .bind(seq)
+        .bind(response_id)
+        .bind(seq)
+        .execute(&self.pool)
+        .await?;
+        Ok(())
+    }
+}
diff --git a/src/db/sqlite/responses.rs b/src/db/sqlite/responses.rs
new file mode 100644
index 0000000..2f533d2
--- /dev/null
+++ b/src/db/sqlite/responses.rs
@@ -0,0 +1,435 @@
+//! SQLite implementation of [`ResponsesRepo`].
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use serde_json::Value;
+use uuid::Uuid;
+
+use super::{
+    backend::{Pool, RowExt, query},
+    common::parse_uuid,
+};
+use crate::db::{
+    error::DbResult,
+    repos::{
+        NewResponse, ResponseCompletion, ResponseOwnerType, ResponseRecord, ResponseStatus,
+        ResponsesRepo, truncate_to_millis,
+    },
+};
+
+/// Org-scope filter for reads/updates/deletes against `responses`.
+/// Mirrors `skills::ORG_SCOPE_FILTER` and the postgres counterpart.
+/// Each `?` is bound to the caller's org id — five times, once per
+/// owner type. Prefixed with `AND` so it appends to an existing
+/// `WHERE id = ?` predicate.
+const ORG_SCOPE_FILTER: &str = r#"
+    AND (
+        (responses.owner_type = 'organization' AND responses.owner_id = ?)
+        OR (responses.owner_type = 'team' AND EXISTS (
+            SELECT 1 FROM teams t WHERE t.id = responses.owner_id AND t.org_id = ?
+        ))
+        OR (responses.owner_type = 'project' AND EXISTS (
+            SELECT 1 FROM projects pr WHERE pr.id = responses.owner_id AND pr.org_id = ?
+        ))
+        OR (responses.owner_type = 'user' AND EXISTS (
+            SELECT 1 FROM org_memberships om WHERE om.user_id = responses.owner_id AND om.org_id = ?
+        ))
+        OR (responses.owner_type = 'service_account' AND EXISTS (
+            SELECT 1 FROM service_accounts sa WHERE sa.id = responses.owner_id AND sa.org_id = ?
+        ))
+    )
+"#;
+
+/// Number of `?` placeholders in [`ORG_SCOPE_FILTER`] that resolve
+/// to the caller's org id. Used by callers when chaining binds.
+const ORG_SCOPE_BINDS: usize = 5;
+
+/// Canonical column list for SELECT / RETURNING.
+const RESPONSE_COLUMNS: &str = "id, org_id, owner_type, owner_id, \
+    project_id, user_id, api_key_id, service_account_id, \
+    status, background, model, provider, \
+    created_at, started_at, completed_at, \
+    request_payload, output, usage, error, \
+    retention_expires_at, last_sequence_number, last_heartbeat_at, container_id";
+
+pub struct SqliteResponsesRepo {
+    pool: Pool,
+}
+
+impl SqliteResponsesRepo {
+    pub fn new(pool: Pool) -> Self {
+        Self { pool }
+    }
+
+    /// Shared body for `update_within_org` / `complete_within_org`.
+    /// When `guard_non_terminal` is set, the UPDATE only matches rows
+    /// whose current status is non-terminal, so a `Some` result means
+    /// this call performed the transition.
+    async fn update_within_org_inner(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ResponseCompletion,
+        guard_non_terminal: bool,
+    ) -> DbResult<Option<ResponseRecord>> {
+        // Build the SET clause dynamically. SQLite handles this fine
+        // with one bind per Some field.
+        let mut setters: Vec<&str> = Vec::new();
+        if patch.status.is_some() {
+            setters.push("status = ?");
+        }
+        if patch.started_at.is_some() {
+            setters.push("started_at = ?");
+        }
+        if patch.completed_at.is_some() {
+            setters.push("completed_at = ?");
+        }
+        if patch.output.is_some() {
+            setters.push("output = ?");
+        }
+        if patch.usage.is_some() {
+            setters.push("usage = ?");
+        }
+        if patch.error.is_some() {
+            setters.push("error = ?");
+        }
+        if patch.retention_expires_at.is_some() {
+            setters.push("retention_expires_at = ?");
+        }
+        if patch.container_id.is_some() {
+            setters.push("container_id = ?");
+        }
+        if setters.is_empty() {
+            return self.get_by_id_and_org(id, org_id).await;
+        }
+
+        // Terminal guard is a static literal fragment with no extra
+        // binds — see `ResponseStatus::is_terminal`.
+        let guard = if guard_non_terminal {
+            " AND status NOT IN ('completed', 'failed', 'cancelled', 'incomplete')"
+        } else {
+            ""
+        };
+        let sql = format!(
+            "UPDATE responses SET {set} WHERE id = ?{scope}{guard} RETURNING {cols}",
+            set = setters.join(", "),
+            scope = ORG_SCOPE_FILTER,
+            guard = guard,
+            cols = RESPONSE_COLUMNS,
+        );
+        let mut q = query(&sql);
+        if let Some(status) = patch.status {
+            q = q.bind(status.as_str().to_string());
+        }
+        if let Some(ts) = patch.started_at {
+            q = q.bind(truncate_to_millis(ts));
+        }
+        if let Some(ts) = patch.completed_at {
+            q = q.bind(truncate_to_millis(ts));
+        }
+        if let Some(output) = patch.output {
+            q = q.bind(serde_json::to_string(&output)?);
+        }
+        if let Some(usage) = patch.usage {
+            q = q.bind(serde_json::to_string(&usage)?);
+        }
+        if let Some(error) = patch.error {
+            q = q.bind(serde_json::to_string(&error)?);
+        }
+        if let Some(ts) = patch.retention_expires_at {
+            q = q.bind(truncate_to_millis(ts));
+        }
+        if let Some(cid) = patch.container_id {
+            q = q.bind(cid);
+        }
+        q = q.bind(id);
+        let org_str = org_id.to_string();
+        for _ in 0..ORG_SCOPE_BINDS {
+            q = q.bind(org_str.clone());
+        }
+
+        let result = q.fetch_optional(&self.pool).await?;
+        match result {
+            Some(row) => Ok(Some(row_to_record(&row)?)),
+            None => Ok(None),
+        }
+    }
+}
+
+fn parse_status(s: &str) -> DbResult<ResponseStatus> {
+    ResponseStatus::parse(s)
+        .ok_or_else(|| crate::db::error::DbError::Internal(format!("unknown response status: {s}")))
+}
+
+fn parse_owner_type(s: &str) -> DbResult<ResponseOwnerType> {
+    ResponseOwnerType::parse(s).ok_or_else(|| {
+        crate::db::error::DbError::Internal(format!("unknown response owner_type: {s}"))
+    })
+}
+
+fn parse_json(s: Option<String>) -> DbResult<Option<Value>> {
+    match s {
+        Some(s) => Ok(Some(serde_json::from_str(&s)?)),
+        None => Ok(None),
+    }
+}
+
+fn parse_optional_uuid(s: Option<String>) -> DbResult<Option<Uuid>> {
+    s.map(|s| parse_uuid(&s)).transpose()
+}
+
+fn row_to_record(row: &super::backend::Row) -> DbResult<ResponseRecord> {
+    let request_payload: String = row.col("request_payload");
+    Ok(ResponseRecord {
+        id: row.col("id"),
+        org_id: parse_uuid(&row.col::<String>("org_id"))?,
+        owner_type: parse_owner_type(&row.col::<String>("owner_type"))?,
+        owner_id: parse_uuid(&row.col::<String>("owner_id"))?,
+        project_id: parse_optional_uuid(row.col("project_id"))?,
+        user_id: parse_optional_uuid(row.col("user_id"))?,
+        api_key_id: parse_optional_uuid(row.col("api_key_id"))?,
+        service_account_id: parse_optional_uuid(row.col("service_account_id"))?,
+        status: parse_status(&row.col::<String>("status"))?,
+        background: row.col::<i64>("background") != 0,
+        model: row.col("model"),
+        provider: row.col("provider"),
+        created_at: row.col("created_at"),
+        started_at: row.col("started_at"),
+        completed_at: row.col("completed_at"),
+        request_payload: serde_json::from_str(&request_payload)?,
+        output: parse_json(row.col("output"))?,
+        usage: parse_json(row.col("usage"))?,
+        error: parse_json(row.col("error"))?,
+        retention_expires_at: row.col("retention_expires_at"),
+        last_sequence_number: row.col("last_sequence_number"),
+        last_heartbeat_at: row.col("last_heartbeat_at"),
+        container_id: row.col("container_id"),
+    })
+}
+
+#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
+#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
+impl ResponsesRepo for SqliteResponsesRepo {
+    async fn insert(&self, input: NewResponse) -> DbResult<ResponseRecord> {
+        let created_at = truncate_to_millis(input.created_at);
+        let retention_expires_at = truncate_to_millis(input.retention_expires_at);
+        let request_payload_json = serde_json::to_string(&input.request_payload)?;
+
+        query(
+            r#"
+            INSERT INTO responses (
+                id, org_id, owner_type, owner_id,
+                project_id, user_id, api_key_id, service_account_id,
+                status, background, model, provider,
+                created_at, request_payload, retention_expires_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            "#,
+        )
+        .bind(&input.id)
+        .bind(input.org_id.to_string())
+        .bind(input.owner_type.as_str())
+        .bind(input.owner_id.to_string())
+        .bind(input.project_id.map(|id| id.to_string()))
+        .bind(input.user_id.map(|id| id.to_string()))
+        .bind(input.api_key_id.map(|id| id.to_string()))
+        .bind(input.service_account_id.map(|id| id.to_string()))
+        .bind(input.status.as_str())
+        .bind(input.background as i64)
+        .bind(&input.model)
+        .bind(&input.provider)
+        .bind(created_at)
+        .bind(&request_payload_json)
+        .bind(retention_expires_at)
+        .execute(&self.pool)
+        .await?;
+
+        Ok(ResponseRecord {
+            id: input.id,
+            org_id: input.org_id,
+            owner_type: input.owner_type,
+            owner_id: input.owner_id,
+            project_id: input.project_id,
+            user_id: input.user_id,
+            api_key_id: input.api_key_id,
+            service_account_id: input.service_account_id,
+            status: input.status,
+            background: input.background,
+            model: input.model,
+            provider: input.provider,
+            created_at,
+            started_at: None,
+            completed_at: None,
+            request_payload: input.request_payload,
+            output: None,
+            usage: None,
+            error: None,
+            retention_expires_at,
+            last_sequence_number: 0,
+            last_heartbeat_at: None,
+            container_id: None,
+        })
+    }
+
+    async fn get_by_id_and_org(&self, id: &str, org_id: Uuid) -> DbResult<Option<ResponseRecord>> {
+        let sql = format!(
+            "SELECT {cols} FROM responses WHERE id = ?{scope}",
+            cols = RESPONSE_COLUMNS,
+            scope = ORG_SCOPE_FILTER,
+        );
+        let mut q = query(&sql).bind(id);
+        let org_str = org_id.to_string();
+        for _ in 0..ORG_SCOPE_BINDS {
+            q = q.bind(org_str.clone());
+        }
+        let result = q.fetch_optional(&self.pool).await?;
+        match result {
+            Some(row) => Ok(Some(row_to_record(&row)?)),
+            None => Ok(None),
+        }
+    }
+
+    async fn update_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ResponseCompletion,
+    ) -> DbResult<Option<ResponseRecord>> {
+        self.update_within_org_inner(id, org_id, patch, false).await
+    }
+
+    async fn complete_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: ResponseCompletion,
+    ) -> DbResult<Option<ResponseRecord>> {
+        self.update_within_org_inner(id, org_id, patch, true).await
+    }
+
+    async fn delete_by_id_and_org(&self, id: &str, org_id: Uuid) -> DbResult<bool> {
+        let sql = format!(
+            "DELETE FROM responses WHERE id = ?{scope}",
+            scope = ORG_SCOPE_FILTER,
+        );
+        let mut q = query(&sql).bind(id);
+        let org_str = org_id.to_string();
+        for _ in 0..ORG_SCOPE_BINDS {
+            q = q.bind(org_str.clone());
+        }
+        let result = q.execute(&self.pool).await?;
+        Ok(result.rows_affected() > 0)
+    }
+
+    async fn claim_queued(&self, now: DateTime<Utc>) -> DbResult<Option<ResponseRecord>> {
+        let now = truncate_to_millis(now);
+        // SQLite serialises writes, so a plain UPDATE...RETURNING with
+        // a subselect of one row gives atomic claim semantics: the
+        // first transaction wins, the rest see status != 'queued' and
+        // get no rows back. Worker runs gateway-wide, so no scope
+        // filter — every queued row is claimable.
+        let sql = format!(
+            r#"
+            UPDATE responses
+            SET status = 'in_progress', started_at = ?
+            WHERE id = (
+                SELECT id FROM responses
+                WHERE status = 'queued'
+                ORDER BY created_at ASC
+                LIMIT 1
+            )
+            RETURNING {cols}
+            "#,
+            cols = RESPONSE_COLUMNS,
+        );
+        let result = query(&sql).bind(now).fetch_optional(&self.pool).await?;
+        match result {
+            Some(row) => Ok(Some(row_to_record(&row)?)),
+            None => Ok(None),
+        }
+    }
+
+    async fn list_cancelled_among(&self, ids: &[String]) -> DbResult<Vec<String>> {
+        if ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        // SQLite doesn't have an ANY(array) operator, so we build a
+        // placeholder list. Capped indirectly by the caller (the
+        // in-flight set has a worker_concurrency bound).
+        let placeholders = vec!["?"; ids.len()].join(",");
+        let sql = format!(
+            "SELECT id FROM responses WHERE status = 'cancelled' AND id IN ({placeholders})"
+        );
+        let mut q = query(&sql);
+        for id in ids {
+            q = q.bind(id);
+        }
+        let rows = q.fetch_all(&self.pool).await?;
+        Ok(rows.iter().map(|r| r.col::<String>("id")).collect())
+    }
+
+    async fn delete_expired(&self, before: DateTime<Utc>) -> DbResult<u64> {
+        let before = truncate_to_millis(before);
+        let result = query(
+            r#"
+            DELETE FROM responses
+            WHERE retention_expires_at < ?
+              AND status IN ('completed', 'failed', 'cancelled', 'incomplete')
+            "#,
+        )
+        .bind(before)
+        .execute(&self.pool)
+        .await?;
+        Ok(result.rows_affected())
+    }
+
+    async fn reap_stuck_in_progress(
+        &self,
+        started_before: DateTime<Utc>,
+        completed_at: DateTime<Utc>,
+        retention_expires_at: DateTime<Utc>,
+    ) -> DbResult<u64> {
+        let started_before = truncate_to_millis(started_before);
+        let completed_at = truncate_to_millis(completed_at);
+        let retention_expires_at = truncate_to_millis(retention_expires_at);
+        let error_json = serde_json::to_string(&serde_json::json!({
+            "code": "worker_lost",
+            "message": "Worker died mid-execution; reaped by retention worker",
+        }))?;
+        // Compare against the liveness heartbeat, falling back to
+        // `started_at` for rows whose worker never stamped one. This stops
+        // the reaper from force-failing a healthy long-running response —
+        // only rows whose worker has genuinely gone quiet past the cutoff
+        // are reaped. Wrap both sides in `datetime()` so the suffix
+        // normalization matches (see `mark_expired_idle`).
+        let result = query(
+            r#"
+            UPDATE responses
+            SET status = 'failed',
+                completed_at = ?,
+                error = ?,
+                retention_expires_at = ?
+            WHERE status = 'in_progress'
+              AND started_at IS NOT NULL
+              AND datetime(COALESCE(last_heartbeat_at, started_at)) < datetime(?)
+            "#,
+        )
+        .bind(completed_at)
+        .bind(error_json)
+        .bind(retention_expires_at)
+        .bind(started_before)
+        .execute(&self.pool)
+        .await?;
+        Ok(result.rows_affected())
+    }
+
+    async fn touch_heartbeat(&self, id: &str, now: DateTime<Utc>) -> DbResult<()> {
+        // Best-effort liveness ping; only meaningful while `in_progress`.
+        query("UPDATE responses SET last_heartbeat_at = ? WHERE id = ? AND status = 'in_progress'")
+            .bind(truncate_to_millis(now))
+            .bind(id)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+}
diff --git a/src/db/sqlite/usage.rs b/src/db/sqlite/usage.rs
index 7d19c89..42a610b 100644
--- a/src/db/sqlite/usage.rs
+++ b/src/db/sqlite/usage.rs
@@ -64,9 +64,10 @@ impl UsageRepo for SqliteUsageRepo {
                 latency_ms, cancelled, status_code, pricing_source,
                 image_count, audio_seconds, character_count, provider_source,
                 record_type, tool_name, tool_query, tool_url,
-                tool_bytes_fetched, tool_results_count
+                tool_bytes_fetched, tool_results_count, tool_runtime_seconds,
+                tool_exit_code
             )
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             "#,
         )
         .bind(id.to_string())
@@ -103,6 +104,8 @@ impl UsageRepo for SqliteUsageRepo {
         .bind(&entry.tool_url)
         .bind(entry.tool_bytes_fetched)
         .bind(entry.tool_results_count)
+        .bind(entry.tool_runtime_seconds)
+        .bind(entry.tool_exit_code)
         .execute(&self.pool)
         .await?;
 
@@ -115,8 +118,8 @@ impl UsageRepo for SqliteUsageRepo {
         }
 
         // SQLite has a limit of 999 parameters per query (SQLITE_LIMIT_VARIABLE_NUMBER)
-        // Each entry uses 34 parameters. Use 29 entries (34*29=986) to stay under limit.
-        const MAX_ENTRIES_PER_BATCH: usize = 29;
+        // Each entry uses 36 parameters. Use 27 entries (36*27=972) to stay under limit.
+        const MAX_ENTRIES_PER_BATCH: usize = 27;
 
         let mut total_inserted = 0;
 
@@ -125,7 +128,7 @@ impl UsageRepo for SqliteUsageRepo {
         for chunk in entries.chunks(MAX_ENTRIES_PER_BATCH) {
             let placeholders: Vec<&str> = chunk
                 .iter()
-                .map(|_| "(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+                .map(|_| "(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
                 .collect();
 
             let sql = format!(
@@ -138,7 +141,8 @@ impl UsageRepo for SqliteUsageRepo {
                     latency_ms, cancelled, status_code, pricing_source,
                     image_count, audio_seconds, character_count, provider_source,
                     record_type, tool_name, tool_query, tool_url,
-                    tool_bytes_fetched, tool_results_count
+                    tool_bytes_fetched, tool_results_count, tool_runtime_seconds,
+                    tool_exit_code
                 )
                 VALUES {}
                 "#,
@@ -185,7 +189,9 @@ impl UsageRepo for SqliteUsageRepo {
                     .bind(&entry.tool_query)
                     .bind(&entry.tool_url)
                     .bind(entry.tool_bytes_fetched)
-                    .bind(entry.tool_results_count);
+                    .bind(entry.tool_results_count)
+                    .bind(entry.tool_runtime_seconds)
+                    .bind(entry.tool_exit_code);
             }
 
             let result = query_builder.execute(&mut *tx).await?;
@@ -3992,7 +3998,8 @@ impl UsageRepo for SqliteUsageRepo {
                    latency_ms, cancelled, status_code, pricing_source,
                    image_count, audio_seconds, character_count, provider_source,
                    record_type, tool_name, tool_query, tool_url,
-                   tool_bytes_fetched, tool_results_count
+                   tool_bytes_fetched, tool_results_count, tool_runtime_seconds,
+                   tool_exit_code
             FROM usage_records
             {}
             ORDER BY recorded_at {}, id {}
@@ -4061,6 +4068,8 @@ impl UsageRepo for SqliteUsageRepo {
                     tool_url: row.col("tool_url"),
                     tool_bytes_fetched: row.col("tool_bytes_fetched"),
                     tool_results_count: row.col("tool_results_count"),
+                    tool_runtime_seconds: row.col("tool_runtime_seconds"),
+                    tool_exit_code: row.col("tool_exit_code"),
                 })
             })
             .collect::<DbResult<Vec<_>>>()?;
diff --git a/src/db/tests/containers.rs b/src/db/tests/containers.rs
new file mode 100644
index 0000000..1ab5190
--- /dev/null
+++ b/src/db/tests/containers.rs
@@ -0,0 +1,297 @@
+//! Shared repository tests for [`ContainersRepo`], focused on the
+//! `hard_delete_expired` cleanup path. Run against both SQLite (fast,
+//! in-memory) and PostgreSQL (testcontainers, `--ignored`).
+
+use chrono::{Duration, Utc};
+use uuid::Uuid;
+
+use crate::{
+    db::repos::{
+        ContainerFileSourceKind, ContainerPatch, ContainerStatus, ContainersRepo, NewContainer,
+        NewContainerFile, ResponseOwner, truncate_to_millis,
+    },
+    models::StorageBackend,
+};
+
+/// Insert a fresh `active` container for `org_id` and return its id.
+async fn seed_org(repo: &dyn ContainersRepo, org_id: Uuid) -> String {
+    let container_id = format!("cntr_{}", Uuid::new_v4().simple());
+    repo.insert(NewContainer::from_owner(
+        container_id.clone(),
+        org_id,
+        ResponseOwner::Organization(org_id),
+        "test",
+        None,
+        1200,
+        truncate_to_millis(Utc::now()),
+    ))
+    .await
+    .expect("insert container");
+    container_id
+}
+
+/// Flip a container into a terminal state with an explicit `expires_at`.
+async fn make_terminal(
+    repo: &dyn ContainersRepo,
+    id: &str,
+    org_id: Uuid,
+    status: ContainerStatus,
+    expires_at: chrono::DateTime<Utc>,
+) {
+    repo.update_within_org(
+        id,
+        org_id,
+        ContainerPatch {
+            status: Some(status),
+            last_active_at: None,
+            expires_at: Some(expires_at),
+        },
+    )
+    .await
+    .expect("transition container")
+    .expect("container exists");
+}
+
+/// Old `expired` and `deleted` containers past the cutoff are hard-deleted,
+/// and their `container_files` cascade.
+pub async fn hard_delete_removes_old_terminal_containers(repo: &dyn ContainersRepo, org_id: Uuid) {
+    let now = truncate_to_millis(Utc::now());
+    let old = now - Duration::hours(2);
+
+    let expired_id = seed_org(repo, org_id).await;
+    make_terminal(repo, &expired_id, org_id, ContainerStatus::Expired, old).await;
+
+    let deleted_id = seed_org(repo, org_id).await;
+    make_terminal(repo, &deleted_id, org_id, ContainerStatus::Deleted, old).await;
+
+    // Attach a file to the expired container so we can assert the cascade.
+    let file_id = format!("cfile_{}", Uuid::new_v4().simple());
+    repo.upsert_file(NewContainerFile {
+        id: file_id.clone(),
+        container_id: expired_id.clone(),
+        org_id,
+        path: "/mnt/data/out.bin".to_string(),
+        filename: "out.bin".to_string(),
+        size_bytes: 4,
+        content_type: Some("application/octet-stream".to_string()),
+        content_hash: "deadbeef".to_string(),
+        source: ContainerFileSourceKind::Assistant,
+        storage_backend: StorageBackend::Database,
+        file_data: Some(b"data".to_vec()),
+        storage_path: None,
+        source_response_id: None,
+        source_call_id: None,
+        created_at: now,
+    })
+    .await
+    .expect("upsert file");
+
+    // Cutoff: anything terminal more than 1h ago.
+    let cutoff = now - Duration::hours(1);
+    let outcome = repo.hard_delete_expired(cutoff, 100).await.expect("delete");
+    let mut deleted = outcome.container_ids.clone();
+    deleted.sort();
+    let mut want = vec![expired_id.clone(), deleted_id.clone()];
+    want.sort();
+    assert_eq!(deleted, want, "both old terminal containers deleted");
+    // The file under `expired_id` must be reported so the service layer can
+    // delete its backing object (the DB cascade only drops the row).
+    assert!(
+        outcome.file_objects.iter().any(|f| f.file_id == file_id),
+        "deleted file reported in outcome for external-storage cleanup"
+    );
+
+    assert!(
+        repo.get_by_id_and_org(&expired_id, org_id)
+            .await
+            .expect("get")
+            .is_none(),
+        "expired container row gone"
+    );
+    assert!(
+        repo.get_by_id_and_org(&deleted_id, org_id)
+            .await
+            .expect("get")
+            .is_none(),
+        "deleted container row gone"
+    );
+    // Files cascade with the container row.
+    let files = repo
+        .list_files_for_replay(&expired_id)
+        .await
+        .expect("list files");
+    assert!(files.is_empty(), "container_files cascaded on hard delete");
+}
+
+/// Active containers and terminal containers newer than the cutoff are NOT
+/// hard-deleted.
+pub async fn hard_delete_spares_active_and_recent(repo: &dyn ContainersRepo, org_id: Uuid) {
+    let now = truncate_to_millis(Utc::now());
+
+    // Active container — never a candidate, even with no expires_at.
+    let active_id = seed_org(repo, org_id).await;
+
+    // Terminal but transitioned only a moment ago (after the cutoff).
+    let recent_id = seed_org(repo, org_id).await;
+    make_terminal(repo, &recent_id, org_id, ContainerStatus::Expired, now).await;
+
+    // Terminal and old enough to be a candidate.
+    let old_id = seed_org(repo, org_id).await;
+    make_terminal(
+        repo,
+        &old_id,
+        org_id,
+        ContainerStatus::Deleted,
+        now - Duration::hours(2),
+    )
+    .await;
+
+    let cutoff = now - Duration::hours(1);
+    let deleted = repo.hard_delete_expired(cutoff, 100).await.expect("delete");
+    assert_eq!(
+        deleted.container_ids,
+        vec![old_id.clone()],
+        "only the old row is deleted"
+    );
+
+    assert!(
+        repo.get_by_id_and_org(&active_id, org_id)
+            .await
+            .expect("get")
+            .is_some(),
+        "active container preserved"
+    );
+    assert!(
+        repo.get_by_id_and_org(&recent_id, org_id)
+            .await
+            .expect("get")
+            .is_some(),
+        "recently-terminal container preserved"
+    );
+    assert!(
+        repo.get_by_id_and_org(&old_id, org_id)
+            .await
+            .expect("get")
+            .is_none(),
+        "old terminal container deleted"
+    );
+}
+
+/// `limit` caps how many rows a single pass removes.
+pub async fn hard_delete_respects_limit(repo: &dyn ContainersRepo, org_id: Uuid) {
+    let now = truncate_to_millis(Utc::now());
+    let old = now - Duration::hours(2);
+    for _ in 0..3 {
+        let id = seed_org(repo, org_id).await;
+        make_terminal(repo, &id, org_id, ContainerStatus::Expired, old).await;
+    }
+
+    let cutoff = now - Duration::hours(1);
+    let first = repo.hard_delete_expired(cutoff, 2).await.expect("delete");
+    assert_eq!(first.container_ids.len(), 2, "first pass capped at limit");
+    let second = repo.hard_delete_expired(cutoff, 2).await.expect("delete");
+    assert_eq!(
+        second.container_ids.len(),
+        1,
+        "second pass drains remainder"
+    );
+    let third = repo.hard_delete_expired(cutoff, 2).await.expect("delete");
+    assert!(third.container_ids.is_empty(), "nothing left to delete");
+}
+
+// ============================================================================
+// SQLite Tests - Fast, in-memory
+// ============================================================================
+
+#[cfg(all(test, feature = "database-sqlite"))]
+mod sqlite_tests {
+    use uuid::Uuid;
+
+    use crate::{
+        db::{
+            repos::OrganizationRepo,
+            sqlite::{SqliteContainersRepo, SqliteOrganizationRepo},
+            tests::harness::{create_sqlite_pool, run_sqlite_migrations},
+        },
+        models::CreateOrganization,
+    };
+
+    async fn create_repo() -> (SqliteContainersRepo, Uuid) {
+        let pool = create_sqlite_pool().await;
+        run_sqlite_migrations(&pool).await;
+        // Enable cascades so `hard_delete_expired` exercises the FK path the
+        // production pool relies on (the harness pool doesn't set it).
+        sqlx::query("PRAGMA foreign_keys = ON")
+            .execute(&pool)
+            .await
+            .expect("enable foreign keys");
+        let org = SqliteOrganizationRepo::new(pool.clone())
+            .create(CreateOrganization {
+                slug: "acme".to_string(),
+                name: "Acme".to_string(),
+            })
+            .await
+            .expect("create org");
+        (SqliteContainersRepo::new(pool), org.id)
+    }
+
+    macro_rules! sqlite_test {
+        ($name:ident) => {
+            #[tokio::test]
+            async fn $name() {
+                let (repo, org_id) = create_repo().await;
+                super::$name(&repo, org_id).await;
+            }
+        };
+    }
+
+    sqlite_test!(hard_delete_removes_old_terminal_containers);
+    sqlite_test!(hard_delete_spares_active_and_recent);
+    sqlite_test!(hard_delete_respects_limit);
+}
+
+// ============================================================================
+// PostgreSQL Tests - Require Docker, run with `cargo test -- --ignored`
+// ============================================================================
+
+#[cfg(all(test, feature = "database-postgres"))]
+mod postgres_tests {
+    use uuid::Uuid;
+
+    use crate::{
+        db::{
+            postgres::{PostgresContainersRepo, PostgresOrganizationRepo},
+            repos::OrganizationRepo,
+            tests::harness::postgres::{create_isolated_postgres_pool, run_postgres_migrations},
+        },
+        models::CreateOrganization,
+    };
+
+    async fn create_repo() -> (PostgresContainersRepo, Uuid) {
+        let pool = create_isolated_postgres_pool().await;
+        run_postgres_migrations(&pool).await;
+        let org = PostgresOrganizationRepo::new(pool.clone(), None)
+            .create(CreateOrganization {
+                slug: "acme".to_string(),
+                name: "Acme".to_string(),
+            })
+            .await
+            .expect("create org");
+        (PostgresContainersRepo::new(pool, None), org.id)
+    }
+
+    macro_rules! postgres_test {
+        ($name:ident) => {
+            #[tokio::test]
+            #[ignore = "Requires Docker - run with `cargo test -- --ignored`"]
+            async fn $name() {
+                let (repo, org_id) = create_repo().await;
+                super::$name(&repo, org_id).await;
+            }
+        };
+    }
+
+    postgres_test!(hard_delete_removes_old_terminal_containers);
+    postgres_test!(hard_delete_spares_active_and_recent);
+    postgres_test!(hard_delete_respects_limit);
+}
diff --git a/src/db/tests/mod.rs b/src/db/tests/mod.rs
index 5e2dc0c..770d44b 100644
--- a/src/db/tests/mod.rs
+++ b/src/db/tests/mod.rs
@@ -23,6 +23,7 @@
 
 mod api_keys;
 mod audit_logs;
+mod containers;
 mod conversations;
 pub mod harness;
 mod model_pricing;
diff --git a/src/db/tests/usage.rs b/src/db/tests/usage.rs
index e893d8a..082dd30 100644
--- a/src/db/tests/usage.rs
+++ b/src/db/tests/usage.rs
@@ -106,6 +106,8 @@ fn create_usage_entry(
         tool_url: None,
         tool_bytes_fetched: None,
         tool_results_count: None,
+        tool_runtime_seconds: None,
+        tool_exit_code: None,
     }
 }
 
@@ -148,6 +150,8 @@ fn create_usage_entry_with_referer(
         tool_url: None,
         tool_bytes_fetched: None,
         tool_results_count: None,
+        tool_runtime_seconds: None,
+        tool_exit_code: None,
     }
 }
 
@@ -190,6 +194,8 @@ fn create_usage_entry_at_time(
         tool_url: None,
         tool_bytes_fetched: None,
         tool_results_count: None,
+        tool_runtime_seconds: None,
+        tool_exit_code: None,
     }
 }
 
@@ -242,6 +248,8 @@ fn create_attributed_usage_entry(
         tool_url: None,
         tool_bytes_fetched: None,
         tool_results_count: None,
+        tool_runtime_seconds: None,
+        tool_exit_code: None,
     }
 }
 
@@ -368,6 +376,48 @@ pub async fn test_log_multiple_entries(ctx: &UsageTestContext<'_>) {
 // Log Batch Tests
 // ============================================================================
 
+/// Round-trip the new `tool_runtime_seconds` field through both the
+/// single-insert `log` path and `list_logs`, so a positional bug in
+/// the 35-parameter INSERT (or a missing column in the row reader)
+/// can't silently null the field.
+pub async fn test_log_tool_runtime_seconds_round_trip(ctx: &UsageTestContext<'_>) {
+    use crate::db::repos::UsageLogQuery;
+    let org_id = ctx.create_test_org("test-org-toolrt").await;
+    let api_key_id = ctx.create_test_api_key(org_id, "test-key-toolrt").await;
+
+    let mut entry = create_usage_entry(api_key_id, "gpt-4", "openai", 0, 0, Some(0));
+    entry.record_type = "tool".to_string();
+    entry.tool_name = Some("shell".to_string());
+    entry.tool_runtime_seconds = Some(12.5);
+
+    ctx.usage_repo
+        .log(entry)
+        .await
+        .expect("Failed to log tool usage entry");
+
+    let listed = ctx
+        .usage_repo
+        .list_logs(UsageLogQuery {
+            api_key_id: Some(api_key_id),
+            record_type: Some("tool".to_string()),
+            limit: Some(10),
+            ..Default::default()
+        })
+        .await
+        .expect("Failed to list logs");
+
+    assert_eq!(listed.items.len(), 1, "expected one tool record");
+    let record = &listed.items[0];
+    assert_eq!(record.tool_name.as_deref(), Some("shell"));
+    let runtime = record
+        .tool_runtime_seconds
+        .expect("tool_runtime_seconds should round-trip as Some(_)");
+    assert!(
+        (runtime - 12.5).abs() < 1e-9,
+        "tool_runtime_seconds {runtime} did not match 12.5"
+    );
+}
+
 pub async fn test_log_batch_empty(ctx: &UsageTestContext<'_>) {
     // Empty batch should return 0 without error
     let result = ctx
@@ -1884,6 +1934,7 @@ mod sqlite_tests {
     sqlite_test!(test_log_with_no_cost);
     sqlite_test!(test_log_with_referer);
     sqlite_test!(test_log_multiple_entries);
+    sqlite_test!(test_log_tool_runtime_seconds_round_trip);
 
     // Log batch tests
     sqlite_test!(test_log_batch_empty);
@@ -1988,6 +2039,7 @@ mod postgres_tests {
     postgres_test!(test_log_with_no_cost);
     postgres_test!(test_log_with_referer);
     postgres_test!(test_log_multiple_entries);
+    postgres_test!(test_log_tool_runtime_seconds_round_trip);
 
     // Log batch tests
     postgres_test!(test_log_batch_empty);
diff --git a/src/db/wasm_sqlite/types.rs b/src/db/wasm_sqlite/types.rs
index 21e580a..0b700fc 100644
--- a/src/db/wasm_sqlite/types.rs
+++ b/src/db/wasm_sqlite/types.rs
@@ -567,6 +567,17 @@ impl WasmDecode for f64 {
     }
 }
 
+impl WasmDecode for Option<f64> {
+    fn decode(value: &WasmValue, _col: &str) -> Result<Self, WasmDbError> {
+        match value {
+            WasmValue::Real(f) => Ok(Some(*f)),
+            WasmValue::Integer(i) => Ok(Some(*i as f64)),
+            WasmValue::Null => Ok(None),
+            _ => Ok(None),
+        }
+    }
+}
+
 impl WasmDecode for NaiveDate {
     fn decode(value: &WasmValue, col: &str) -> Result<Self, WasmDbError> {
         match value {
diff --git a/src/guardrails/evaluator.rs b/src/guardrails/evaluator.rs
index ee80a98..ce10f3d 100644
--- a/src/guardrails/evaluator.rs
+++ b/src/guardrails/evaluator.rs
@@ -1592,6 +1592,15 @@ fn extract_text_from_input_item(item: &ResponsesInputItem) -> Option<String> {
         // Tool calls don't have meaningful text content for guardrails
         ResponsesInputItem::WebSearchCall(_)
         | ResponsesInputItem::FileSearchCall(_)
+        | ResponsesInputItem::ShellCall(_)
+        | ResponsesInputItem::ShellCallOutput(_)
+        | ResponsesInputItem::McpListTools(_)
+        | ResponsesInputItem::McpCall(_)
+        | ResponsesInputItem::McpApprovalRequest(_)
+        | ResponsesInputItem::McpApprovalResponse(_)
+        | ResponsesInputItem::ToolSearchCall(_)
+        | ResponsesInputItem::ToolSearchOutput(_)
+        | ResponsesInputItem::Compaction(_)
         | ResponsesInputItem::ImageGeneration(_) => None,
     }
 }
diff --git a/src/jobs/background_responses.rs b/src/jobs/background_responses.rs
new file mode 100644
index 0000000..1596f4c
--- /dev/null
+++ b/src/jobs/background_responses.rs
@@ -0,0 +1,208 @@
+//! Background worker that runs `status=queued` responses.
+//!
+//! When a request arrives with `background=true`, the handler inserts
+//! a row with status `queued` and returns immediately. This worker
+//! polls for those rows and runs them through the LLM pipeline,
+//! letting the persister capture events along the way.
+//!
+//! Multi-worker safety: `ResponsesRepo::claim_queued` uses
+//! `SELECT FOR UPDATE SKIP LOCKED` on Postgres so multiple workers
+//! across replicas never claim the same row. SQLite's writer
+//! serialization gives equivalent semantics for single-node use.
+
+use std::{sync::Arc, time::Duration as StdDuration};
+
+use chrono::Utc;
+use tokio::{sync::Semaphore, time::sleep};
+use tokio_util::sync::CancellationToken;
+use tracing::{debug, error, info, warn};
+
+use crate::{
+    AppState,
+    db::repos::{ResponseCompletion, ResponseStatus},
+    services::background_executor::{
+        BackgroundExecuteError, execute_persisted_response, mark_background_failure,
+    },
+};
+
+/// How often to check for queued work when the previous tick found
+/// no rows. We back off slightly so an idle gateway isn't constantly
+/// hitting the DB; with work queued, the loop runs in a tight cycle
+/// after each row completes.
+const IDLE_INTERVAL: StdDuration = StdDuration::from_secs(1);
+
+/// Spawnable entry point. Runs forever under `tokio::spawn` until the
+/// `shutdown_token` is cancelled. Bounded concurrency via a semaphore
+/// sized at `[features.responses] worker_concurrency` — without a cap,
+/// a flood of `background=true` requests would `tokio::spawn` one task
+/// per claim and saturate the replica.
+pub async fn start_background_response_worker(state: AppState, shutdown: CancellationToken) {
+    let concurrency = state.config.features.responses.worker_concurrency.max(1);
+    let semaphore = Arc::new(Semaphore::new(concurrency));
+    info!(
+        worker_concurrency = concurrency,
+        "Starting background response worker"
+    );
+    loop {
+        if shutdown.is_cancelled() {
+            info!("Background response worker received shutdown signal");
+            return;
+        }
+        let Some(ref store) = state.responses_store else {
+            tokio::select! {
+                _ = shutdown.cancelled() => return,
+                _ = sleep(IDLE_INTERVAL) => continue,
+            }
+        };
+        let Some(ref db) = state.db else {
+            tokio::select! {
+                _ = shutdown.cancelled() => return,
+                _ = sleep(IDLE_INTERVAL) => continue,
+            }
+        };
+
+        // Wait for a slot before claiming, so we don't pop a row off
+        // the queue we have no capacity to execute.
+        let permit = tokio::select! {
+            _ = shutdown.cancelled() => return,
+            permit = Arc::clone(&semaphore).acquire_owned() => permit,
+        };
+        let permit = match permit {
+            Ok(p) => p,
+            Err(_) => return, // semaphore closed
+        };
+
+        let claim = db.responses().claim_queued(Utc::now()).await;
+        match claim {
+            Ok(Some(record)) => {
+                debug!(
+                    response_id = %record.id,
+                    model = %record.model,
+                    "Claimed queued response"
+                );
+                let response_id = record.id.clone();
+                let response_org = record.org_id;
+                let exec_state = state.clone();
+                let store = store.clone();
+                let retry_config = state.config.features.responses.retry.clone();
+                // Track the execution on the shared task tracker so a
+                // SIGTERM drains an in-flight background response instead
+                // of abandoning it mid-stream (later force-reaped as
+                // `worker_lost`). The claim loop above stops on the
+                // shutdown token; this keeps the work it already claimed.
+                let tracker = exec_state.task_tracker.clone();
+                tracker.spawn(async move {
+                    let result =
+                        run_with_retry(&exec_state, store.clone(), record, retry_config).await;
+                    if let Err(e) = result {
+                        warn!(
+                            response_id = %response_id,
+                            error = %e,
+                            "Background response execution failed after retries"
+                        );
+                        mark_background_failure(&store, &response_id, response_org, &e).await;
+                    }
+                    drop(permit);
+                });
+            }
+            Ok(None) => {
+                drop(permit);
+                tokio::select! {
+                    _ = shutdown.cancelled() => return,
+                    _ = sleep(IDLE_INTERVAL) => {}
+                }
+            }
+            Err(e) => {
+                drop(permit);
+                error!(error = %e, "claim_queued failed");
+                tokio::select! {
+                    _ = shutdown.cancelled() => return,
+                    _ = sleep(IDLE_INTERVAL) => {}
+                }
+            }
+        }
+    }
+}
+
+/// Execute a claimed response with retry on transient failures.
+///
+/// Permanent failures (BadPayload/Routing/Resolution/NoStore) return
+/// immediately. Between attempts we re-load the row so the persister
+/// resumes from the updated `last_sequence_number` and bump
+/// `started_at` so the in-progress reaper doesn't kill an active
+/// retry.
+async fn run_with_retry(
+    state: &AppState,
+    store: Arc<crate::services::ResponsesStore>,
+    initial_record: crate::db::repos::ResponseRecord,
+    retry: crate::config::ResponsesRetryConfig,
+) -> Result<(), BackgroundExecuteError> {
+    let max_attempts = if retry.enabled { retry.max_attempts } else { 1 };
+    let response_id = initial_record.id.clone();
+    let org_id = initial_record.org_id;
+    let mut record = initial_record;
+
+    for attempt in 1..=max_attempts {
+        let result = execute_persisted_response(state.clone(), record.clone()).await;
+        match result {
+            Ok(()) => return Ok(()),
+            Err(e) if !e.is_transient() => return Err(e),
+            Err(e) if attempt == max_attempts => return Err(e),
+            Err(e) => {
+                let backoff = retry.backoff_for_attempt(attempt);
+                warn!(
+                    response_id = %response_id,
+                    attempt,
+                    max_attempts,
+                    backoff_ms = backoff.as_millis() as u64,
+                    error = %e,
+                    "Background response attempt failed; retrying"
+                );
+                sleep(backoff).await;
+
+                // Re-fetch the row so the next attempt picks up the
+                // up-to-date `last_sequence_number` (the previous
+                // attempt's persister wrote partial events). Refresh
+                // `started_at` while we're at it so the reaper sees
+                // this as fresh work, and reset `status` to
+                // `in_progress` in case the previous attempt's persister
+                // marked the row `incomplete` (a terminal state) — that
+                // would otherwise stop clients polling before this
+                // retry completes.
+                if let Err(update_err) = store
+                    .update_within_org(
+                        &response_id,
+                        org_id,
+                        ResponseCompletion {
+                            status: Some(ResponseStatus::InProgress),
+                            started_at: Some(Utc::now()),
+                            ..Default::default()
+                        },
+                    )
+                    .await
+                {
+                    warn!(
+                        response_id = %response_id,
+                        error = %update_err,
+                        "Failed to bump started_at before retry; will retry anyway"
+                    );
+                }
+                match store.get(&response_id, org_id).await {
+                    Ok(r) => record = r,
+                    Err(get_err) => {
+                        warn!(
+                            response_id = %response_id,
+                            error = %get_err,
+                            "Failed to reload record between retries"
+                        );
+                        return Err(BackgroundExecuteError::Execution(get_err.to_string()));
+                    }
+                }
+            }
+        }
+    }
+    // Unreachable: the loop always returns or hits `attempt ==
+    // max_attempts`. The conditional construction keeps the compiler
+    // happy without an explicit unreachable!().
+    Ok(())
+}
diff --git a/src/jobs/containers_cleanup.rs b/src/jobs/containers_cleanup.rs
new file mode 100644
index 0000000..9d9d7bd
--- /dev/null
+++ b/src/jobs/containers_cleanup.rs
@@ -0,0 +1,215 @@
+//! Container cleanup worker for hard-deleting terminal container rows.
+//!
+//! Containers move `active` → `expired` (the idle reaper) → `deleted`
+//! (explicit `DELETE /v1/containers/{id}`). Both terminal transitions stamp
+//! `expires_at` but never remove the row, so without this worker `expired` /
+//! `deleted` containers (and their `container_files`) accumulate forever.
+//!
+//! This module provides a background worker that periodically:
+//! 1. Finds terminal containers whose `expires_at` has passed the cleanup delay
+//! 2. Hard deletes the container rows, cascading their `container_files`
+//!
+//! The cleanup process is designed to be safe and incremental:
+//! - Cleanup is batched to avoid long-running operations
+//! - A configurable delay between the terminal transition and hard delete
+//!   gives clients time to download captured files
+//! - Dry run mode allows testing the cleanup configuration
+
+use std::{sync::Arc, time::Instant};
+
+use chrono::{Duration, Utc};
+use tokio_util::sync::CancellationToken;
+
+use crate::{
+    config::ContainersCleanupConfig,
+    db::DbPool,
+    jobs::leader_lock::{self, LeadershipOutcome, keys},
+    observability::metrics,
+    services::containers::ContainersService,
+};
+
+/// Results from a single cleanup run.
+#[derive(Debug, Default)]
+pub struct CleanupRunResult {
+    /// Number of containers hard-deleted.
+    pub containers_deleted: u64,
+    /// Duration of the cleanup run in milliseconds.
+    pub duration_ms: u64,
+}
+
+impl CleanupRunResult {
+    /// Check if any records were deleted.
+    pub fn has_deletions(&self) -> bool {
+        self.containers_deleted > 0
+    }
+}
+
+/// Starts the container cleanup worker as a background task.
+///
+/// The worker runs in a loop, hard-deleting terminal containers at the
+/// configured interval. It runs until `shutdown` fires, so a SIGTERM
+/// stops it promptly instead of letting it keep hitting the DB while the
+/// rest of the process drains.
+pub async fn start_containers_cleanup_worker(
+    containers: Arc<ContainersService>,
+    db: Arc<DbPool>,
+    config: ContainersCleanupConfig,
+    shutdown: CancellationToken,
+) {
+    if !config.enabled {
+        tracing::info!("Container cleanup worker disabled by configuration");
+        return;
+    }
+
+    let dry_run_msg = if config.dry_run { " (DRY RUN)" } else { "" };
+
+    tracing::info!(
+        interval_secs = config.interval_secs,
+        cleanup_delay_secs = config.cleanup_delay_secs,
+        batch_size = config.batch_size,
+        max_duration_secs = config.max_duration_secs,
+        dry_run = config.dry_run,
+        "Starting container cleanup worker{}",
+        dry_run_msg
+    );
+
+    let interval = config.interval();
+
+    loop {
+        if shutdown.is_cancelled() {
+            tracing::info!("Container cleanup worker received shutdown signal");
+            return;
+        }
+        // Skip ticks where another replica already holds the cleanup lock —
+        // running deletes from two replicas would race on the same rows.
+        let _guard = match leader_lock::try_acquire(&db, keys::CONTAINERS_CLEANUP).await {
+            LeadershipOutcome::Leader(g) => Some(g),
+            LeadershipOutcome::NotLeader => {
+                tracing::trace!("containers_cleanup: not leader this tick, skipping");
+                tokio::select! {
+                    _ = shutdown.cancelled() => return,
+                    _ = tokio::time::sleep(interval) => {}
+                }
+                continue;
+            }
+            LeadershipOutcome::NoCoordination => None,
+        };
+
+        match run_cleanup(&containers, &config).await {
+            Ok(result) => {
+                if result.has_deletions() {
+                    tracing::info!(
+                        stage = "complete",
+                        containers = result.containers_deleted,
+                        duration_ms = result.duration_ms,
+                        dry_run = config.dry_run,
+                        "Container cleanup run complete{}",
+                        dry_run_msg
+                    );
+                } else {
+                    tracing::debug!(
+                        stage = "complete",
+                        "Container cleanup run complete, nothing to clean up"
+                    );
+                }
+            }
+            Err(e) => {
+                tracing::error!(stage = "error", error = %e, "Error running container cleanup");
+                metrics::record_cleanup_error("containers");
+            }
+        }
+
+        tokio::select! {
+            _ = shutdown.cancelled() => return,
+            _ = tokio::time::sleep(interval) => {}
+        }
+    }
+}
+
+/// Run a single cleanup pass, hard-deleting terminal containers and their
+/// captured files.
+async fn run_cleanup(
+    containers: &Arc<ContainersService>,
+    config: &ContainersCleanupConfig,
+) -> Result<CleanupRunResult, Box<dyn std::error::Error + Send + Sync>> {
+    let start = Instant::now();
+    let mut result = CleanupRunResult::default();
+
+    // Calculate cutoff time: containers that became terminal before this time
+    // should be cleaned up.
+    let cutoff = Utc::now() - Duration::seconds(config.cleanup_delay_secs as i64);
+    let max_duration = config.max_duration();
+
+    let mut remaining = config.batch_size as i64;
+    loop {
+        if remaining <= 0 {
+            break;
+        }
+        // Check if we've exceeded max duration.
+        if let Some(max_dur) = max_duration
+            && start.elapsed() > max_dur
+        {
+            tracing::info!(
+                stage = "max_duration",
+                containers_processed = result.containers_deleted,
+                "Max cleanup duration exceeded, stopping early"
+            );
+            break;
+        }
+
+        if config.dry_run {
+            // Dry run can't delete, so there's nothing to iterate on without
+            // racing the same rows forever. Report the candidate count once.
+            let cutoff_ts = cutoff;
+            tracing::info!(
+                stage = "dry_run",
+                cutoff = %cutoff_ts,
+                "DRY RUN: would hard-delete terminal containers older than cutoff"
+            );
+            break;
+        }
+
+        let deleted = containers.hard_delete_expired(cutoff, remaining).await?;
+        if deleted.is_empty() {
+            break;
+        }
+        result.containers_deleted += deleted.len() as u64;
+        remaining -= deleted.len() as i64;
+        for id in &deleted {
+            tracing::debug!(stage = "delete", container_id = %id, "Hard deleted terminal container");
+        }
+    }
+
+    result.duration_ms = start.elapsed().as_millis() as u64;
+
+    if result.containers_deleted > 0 {
+        metrics::record_cleanup_deletion("containers", result.containers_deleted);
+    }
+
+    Ok(result)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_cleanup_run_result_default() {
+        let result = CleanupRunResult::default();
+        assert_eq!(result.containers_deleted, 0);
+        assert_eq!(result.duration_ms, 0);
+        assert!(!result.has_deletions());
+    }
+
+    #[test]
+    fn test_cleanup_run_result_has_deletions() {
+        let empty = CleanupRunResult::default();
+        assert!(!empty.has_deletions());
+
+        let with_containers = CleanupRunResult {
+            containers_deleted: 1,
+            ..Default::default()
+        };
+        assert!(with_containers.has_deletions());
+    }
+}
diff --git a/src/jobs/containers_reaper.rs b/src/jobs/containers_reaper.rs
new file mode 100644
index 0000000..9e3e9d0
--- /dev/null
+++ b/src/jobs/containers_reaper.rs
@@ -0,0 +1,106 @@
+//! Idle-container reaper for the shell-tool `/mnt/data` workspace.
+//!
+//! Every pass does two things with different scopes:
+//! 1. **Leader only** — under the cluster-wide leader lock, mark
+//!    `containers` rows whose `last_active_at + idle_ttl_secs` has
+//!    elapsed as `expired`. Exactly one replica flips the rows.
+//! 2. **Every replica** — reconcile this process's in-memory
+//!    [`ContainerSessionRegistry`] against the DB: any locally-held
+//!    session whose row is now terminal (`expired`/`deleted`) is
+//!    removed so `ContainerSession::drop` detaches a terminate task and
+//!    the underlying VM is torn down.
+//!
+//! The registry is process-local, so the reconcile step must NOT be
+//! gated on leadership — only the replica hosting a VM can free it, and
+//! that is usually not the replica that won the lock and flipped the
+//! row.
+
+use std::{sync::Arc, time::Duration as StdDuration};
+
+use chrono::Utc;
+use tokio::time::sleep;
+use tokio_util::sync::CancellationToken;
+
+use crate::{
+    jobs::leader_lock::{self, LeadershipOutcome, keys},
+    services::{container_session::ContainerSessionRegistry, containers::ContainersService},
+};
+
+/// Run the reaper loop until `shutdown` fires.
+pub async fn start_containers_reaper_worker(
+    containers: Arc<ContainersService>,
+    registry: Arc<ContainerSessionRegistry>,
+    db: Arc<crate::db::DbPool>,
+    interval: StdDuration,
+    shutdown: CancellationToken,
+) {
+    tracing::info!(
+        interval_secs = interval.as_secs(),
+        "Starting containers reaper worker"
+    );
+
+    loop {
+        tokio::select! {
+            _ = shutdown.cancelled() => {
+                tracing::info!("Containers reaper worker received shutdown signal");
+                return;
+            }
+            _ = sleep(interval) => {}
+        }
+
+        // Only the leader flips DB rows; other replicas still need to
+        // sweep their local registry of in-memory sessions for any
+        // containers a previous leader pass already expired.
+        let leader_guard = match leader_lock::try_acquire(&db, keys::CONTAINERS_REAPER).await {
+            LeadershipOutcome::Leader(g) => Some(Some(g)),
+            LeadershipOutcome::NotLeader => Some(None),
+            LeadershipOutcome::NoCoordination => None,
+        };
+        let is_leader = !matches!(leader_guard, Some(None));
+
+        // Step 1 (leader only): flip expired rows in the DB.
+        if is_leader {
+            match containers.mark_expired_idle(Utc::now()).await {
+                Ok(expired_ids) if !expired_ids.is_empty() => {
+                    tracing::info!(count = expired_ids.len(), "Marked idle containers expired");
+                }
+                Ok(_) => {}
+                Err(e) => {
+                    tracing::warn!(error = %e, "Containers reaper DB pass failed");
+                }
+            }
+        }
+
+        // Step 2 (every replica): reconcile the process-local session
+        // registry against terminal rows. This is what actually frees
+        // VMs, and it must run regardless of leadership because only the
+        // replica holding a session can drop it.
+        let local_ids = registry.ids();
+        if !local_ids.is_empty() {
+            match containers.expired_among(&local_ids).await {
+                Ok(expired) => {
+                    let mut evicted = 0usize;
+                    for id in &expired {
+                        if registry.remove(id).is_some() {
+                            evicted += 1;
+                            tracing::debug!(
+                                container_id = %id,
+                                "Evicted expired container session from registry"
+                            );
+                        }
+                    }
+                    if evicted > 0 {
+                        tracing::info!(count = evicted, "Evicted expired container sessions");
+                    }
+                }
+                Err(e) => {
+                    tracing::warn!(error = %e, "Containers reaper registry reconcile failed");
+                }
+            }
+        }
+
+        // `leader_guard` is held across the leader work above and
+        // released here as it drops at end of scope, relinquishing
+        // leadership before the next interval.
+    }
+}
diff --git a/src/jobs/leader_lock.rs b/src/jobs/leader_lock.rs
index a31a0db..9d5b7a9 100644
--- a/src/jobs/leader_lock.rs
+++ b/src/jobs/leader_lock.rs
@@ -28,6 +28,9 @@ use crate::db::DbPool;
 pub mod keys {
     pub const VECTOR_STORE_CLEANUP: i64 = 0x6861_6472_5f76_7363_u64 as i64;
     pub const OAUTH_CODE_CLEANUP: i64 = 0x6861_6472_5f6f_6163_u64 as i64;
+    pub const RESPONSES_RETENTION: i64 = 0x6861_6472_5f72_6573_u64 as i64;
+    pub const CONTAINERS_REAPER: i64 = 0x6861_6472_5f63_7472_u64 as i64;
+    pub const CONTAINERS_CLEANUP: i64 = 0x6861_6472_5f63_636c_u64 as i64;
 }
 
 /// Outcome of a leader-election attempt.
diff --git a/src/jobs/mod.rs b/src/jobs/mod.rs
index 9df5a76..8389a69 100644
--- a/src/jobs/mod.rs
+++ b/src/jobs/mod.rs
@@ -4,6 +4,8 @@
 //!
 //! - **Vector Store Cleanup**: Removes soft-deleted vector stores, their chunks,
 //!   and orphaned files after a configurable delay.
+//! - **Container Cleanup**: Hard-deletes `expired` / `deleted` containers (and
+//!   their captured `container_files`) after a configurable delay.
 //! - **Provider Health Checks**: Periodically checks provider availability and
 //!   publishes health status changes to the EventBus.
 //!
@@ -28,15 +30,35 @@
 //! interval_secs = 60
 //! ```
 
+#[cfg(feature = "server")]
+mod background_responses;
+#[cfg(feature = "server")]
+mod containers_cleanup;
+#[cfg(feature = "server")]
+mod containers_reaper;
 mod leader_lock;
 mod model_catalog_sync;
 mod oauth_code_cleanup;
 mod provider_health_check;
+#[cfg(feature = "server")]
+mod responses_cancel_poller;
+#[cfg(feature = "server")]
+mod responses_retention;
 mod vector_store_cleanup;
 
+#[cfg(feature = "server")]
+pub use background_responses::start_background_response_worker;
+#[cfg(feature = "server")]
+pub use containers_cleanup::start_containers_cleanup_worker;
+#[cfg(feature = "server")]
+pub use containers_reaper::start_containers_reaper_worker;
 pub use model_catalog_sync::start_model_catalog_sync_worker;
 pub use oauth_code_cleanup::start_oauth_code_cleanup_worker;
 pub use provider_health_check::{
     ProviderHealthChecker, ProviderHealthState, ProviderHealthStateRegistry,
 };
+#[cfg(feature = "server")]
+pub use responses_cancel_poller::start_responses_cancel_poller;
+#[cfg(feature = "server")]
+pub use responses_retention::start_responses_retention_worker;
 pub use vector_store_cleanup::start_vector_store_cleanup_worker;
diff --git a/src/jobs/responses_cancel_poller.rs b/src/jobs/responses_cancel_poller.rs
new file mode 100644
index 0000000..c1c2d29
--- /dev/null
+++ b/src/jobs/responses_cancel_poller.rs
@@ -0,0 +1,48 @@
+//! Single replica-wide poller for cross-replica response cancels.
+//!
+//! When `POST /v1/responses/{id}/cancel` runs on replica A but the
+//! row is executing on replica B, the in-process watch channel on
+//! B doesn't see the flip. This worker polls every N seconds: one
+//! batched query `WHERE status='cancelled' AND id IN (active set)`
+//! that trips the matching watch sender on B. The previous
+//! per-execution poller cost one task + one DB round-trip per
+//! in-flight response; this is one task + one query for the whole
+//! replica.
+
+use std::{sync::Arc, time::Duration as StdDuration};
+
+use tokio::time::sleep;
+use tokio_util::sync::CancellationToken;
+
+use crate::services::ResponsesStore;
+
+/// Default poll cadence. Matches the previous per-execution
+/// polling interval so cancel latency doesn't regress.
+const POLL_INTERVAL: StdDuration = StdDuration::from_secs(5);
+
+/// Spawnable entry point. Exits when `shutdown` is cancelled.
+pub async fn start_responses_cancel_poller(
+    store: Arc<ResponsesStore>,
+    shutdown: CancellationToken,
+) {
+    tracing::info!("Starting responses cancel poller");
+    loop {
+        tokio::select! {
+            _ = shutdown.cancelled() => {
+                tracing::info!("Responses cancel poller received shutdown signal");
+                return;
+            }
+            _ = sleep(POLL_INTERVAL) => {}
+        }
+
+        match store.poll_external_cancels().await {
+            Ok(0) => {}
+            Ok(n) => {
+                tracing::debug!(tripped = n, "Cross-replica cancels delivered");
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "Cancel poll failed");
+            }
+        }
+    }
+}
diff --git a/src/jobs/responses_retention.rs b/src/jobs/responses_retention.rs
new file mode 100644
index 0000000..457e28d
--- /dev/null
+++ b/src/jobs/responses_retention.rs
@@ -0,0 +1,86 @@
+//! Retention + reaper worker for the `responses` table.
+//!
+//! Each pass under the cluster-wide leader lock:
+//! 1. **Reap**: mark `status='in_progress'` rows older than
+//!    `max_in_progress_secs` as Failed with `code='worker_lost'`. A
+//!    worker that died mid-execution would otherwise leave the row
+//!    stuck forever (`claim_queued` only picks `queued`).
+//! 2. **Prune**: delete rows whose `retention_expires_at` is past.
+//! 3. **MCP approvals sweep** (when the `mcp` feature is enabled):
+//!    delete `mcp_pending_approvals` rows past their `expires_at`. The
+//!    claim path already gates on `expires_at > now`, so stale rows are
+//!    never executable — this sweep just stops them accumulating
+//!    forever when a gated call is never resumed.
+//!
+//! The reap stamps a fresh `retention_expires_at` so the prune
+//! picks reaped rows up on a future cycle, not the current one
+//! (gives external observers time to see the terminal state).
+
+use std::{sync::Arc, time::Duration as StdDuration};
+
+use chrono::Utc;
+use tokio::time::sleep;
+use tokio_util::sync::CancellationToken;
+
+use crate::{
+    jobs::leader_lock::{self, LeadershipOutcome, keys},
+    services::ResponsesStore,
+};
+
+/// Loop until `shutdown` is cancelled. Runs under `tokio::spawn`. Each
+/// pass tries to acquire the cluster-wide leader lock first; non-leader
+/// replicas skip the prune so only one replica writes per interval.
+pub async fn start_responses_retention_worker(
+    store: Arc<ResponsesStore>,
+    db: Arc<crate::db::DbPool>,
+    cleanup_interval: StdDuration,
+    max_in_progress: StdDuration,
+    shutdown: CancellationToken,
+) {
+    tracing::info!(
+        interval_secs = cleanup_interval.as_secs(),
+        max_in_progress_secs = max_in_progress.as_secs(),
+        "Starting responses retention worker"
+    );
+
+    loop {
+        tokio::select! {
+            _ = shutdown.cancelled() => {
+                tracing::info!("Responses retention worker received shutdown signal");
+                return;
+            }
+            _ = sleep(cleanup_interval) => {}
+        }
+
+        let _guard = match leader_lock::try_acquire(&db, keys::RESPONSES_RETENTION).await {
+            LeadershipOutcome::Leader(g) => Some(g),
+            LeadershipOutcome::NotLeader => {
+                tracing::trace!("responses_retention: not leader, skipping");
+                continue;
+            }
+            LeadershipOutcome::NoCoordination => None,
+        };
+
+        match store.reap_stuck(max_in_progress).await {
+            Ok(0) => {}
+            Ok(n) => tracing::info!(reaped = n, "Reaped stuck in_progress response rows"),
+            Err(e) => tracing::warn!(error = %e, "Responses reaper pass failed"),
+        }
+
+        match store.prune_expired(Utc::now()).await {
+            Ok(0) => {}
+            Ok(n) => tracing::debug!(deleted = n, "Pruned expired response rows"),
+            Err(e) => tracing::warn!(error = %e, "Responses retention pass failed"),
+        }
+
+        // Sweep parked MCP approvals past their TTL. Runs under the same
+        // leader lock so only one replica writes; the claim path already
+        // refuses expired rows, so this only bounds storage growth.
+        #[cfg(feature = "mcp")]
+        match db.mcp_pending_approvals().delete_expired(Utc::now()).await {
+            Ok(0) => {}
+            Ok(n) => tracing::debug!(deleted = n, "Swept expired MCP pending-approval rows"),
+            Err(e) => tracing::warn!(error = %e, "MCP pending-approvals sweep failed"),
+        }
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
index 1162691..7b9317c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -24,6 +24,8 @@ pub mod providers;
 pub mod retention;
 pub mod routes;
 pub mod routing;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod runtimes;
 #[cfg(feature = "sso")]
 pub mod scim;
 pub mod secrets;
diff --git a/src/middleware/layers/admin.rs b/src/middleware/layers/admin.rs
index 16893e4..2822d27 100644
--- a/src/middleware/layers/admin.rs
+++ b/src/middleware/layers/admin.rs
@@ -2474,6 +2474,17 @@ mod tests {
             output_guardrails: None,
             event_bus: Arc::new(crate::events::EventBus::new()),
             file_search_service: None,
+            shell_runtime: None,
+            #[cfg(feature = "mcp")]
+            mcp_service: None,
+            #[cfg(feature = "mcp")]
+            tool_search_embeddings: None,
+            responses_store: None,
+            containers_service: None,
+            container_session_registry: std::sync::Arc::new(
+                crate::services::container_session::ContainerSessionRegistry::new(),
+            ),
+            response_event_buffer: None,
             #[cfg(any(
                 feature = "document-extraction-basic",
                 feature = "document-extraction-full"
@@ -2783,6 +2794,17 @@ mod tests {
             output_guardrails: None,
             event_bus: Arc::new(crate::events::EventBus::new()),
             file_search_service: None,
+            shell_runtime: None,
+            #[cfg(feature = "mcp")]
+            mcp_service: None,
+            #[cfg(feature = "mcp")]
+            tool_search_embeddings: None,
+            responses_store: None,
+            containers_service: None,
+            container_session_registry: std::sync::Arc::new(
+                crate::services::container_session::ContainerSessionRegistry::new(),
+            ),
+            response_event_buffer: None,
             #[cfg(any(
                 feature = "document-extraction-basic",
                 feature = "document-extraction-full"
diff --git a/src/middleware/layers/api.rs b/src/middleware/layers/api.rs
index 41730ce..a1c2f8b 100644
--- a/src/middleware/layers/api.rs
+++ b/src/middleware/layers/api.rs
@@ -977,6 +977,8 @@ pub async fn api_middleware(
                     tool_url: None,
                     tool_bytes_fetched: None,
                     tool_results_count: None,
+                    tool_runtime_seconds: None,
+                    tool_exit_code: None,
                 });
             }
         }
@@ -1138,6 +1140,8 @@ fn track_usage_async(ctx: UsageTrackingContext<'_>) {
         tool_url: None,
         tool_bytes_fetched: None,
         tool_results_count: None,
+        tool_runtime_seconds: None,
+        tool_exit_code: None,
     };
 
     let is_success = response.status().is_success();
@@ -2289,6 +2293,17 @@ mod tests {
             output_guardrails: None,
             event_bus: Arc::new(crate::events::EventBus::new()),
             file_search_service: None,
+            shell_runtime: None,
+            #[cfg(feature = "mcp")]
+            mcp_service: None,
+            #[cfg(feature = "mcp")]
+            tool_search_embeddings: None,
+            responses_store: None,
+            containers_service: None,
+            container_session_registry: std::sync::Arc::new(
+                crate::services::container_session::ContainerSessionRegistry::new(),
+            ),
+            response_event_buffer: None,
             #[cfg(any(
                 feature = "document-extraction-basic",
                 feature = "document-extraction-full"
@@ -2347,6 +2362,17 @@ mod tests {
             output_guardrails: None,
             event_bus: Arc::new(crate::events::EventBus::new()),
             file_search_service: None,
+            shell_runtime: None,
+            #[cfg(feature = "mcp")]
+            mcp_service: None,
+            #[cfg(feature = "mcp")]
+            tool_search_embeddings: None,
+            responses_store: None,
+            containers_service: None,
+            container_session_registry: std::sync::Arc::new(
+                crate::services::container_session::ContainerSessionRegistry::new(),
+            ),
+            response_event_buffer: None,
             #[cfg(any(
                 feature = "document-extraction-basic",
                 feature = "document-extraction-full"
diff --git a/src/models/usage.rs b/src/models/usage.rs
index 7d9970a..7f8fc59 100644
--- a/src/models/usage.rs
+++ b/src/models/usage.rs
@@ -50,6 +50,13 @@ pub struct UsageLogRecord {
     pub tool_bytes_fetched: Option<i64>,
     /// Number of search results returned — only for web_search records
     pub tool_results_count: Option<i32>,
+    /// Wall-clock runtime in seconds — only for shell tool records.
+    pub tool_runtime_seconds: Option<f64>,
+    /// Process exit code — only for shell tool records. Distinct from
+    /// `status_code` (which is the HTTP status of the API request that
+    /// drove the tool); a shell can exit `0` while the wrapping request
+    /// returns 200, or exit `7` while the request still returns 200.
+    pub tool_exit_code: Option<i32>,
 }
 
 /// Usage log entry for a single API request.
@@ -130,6 +137,19 @@ pub struct UsageLogEntry {
     /// Number of search results returned — only for web_search records
     #[serde(default)]
     pub tool_results_count: Option<i32>,
+    /// Wall-clock runtime in seconds — only for shell tool records.
+    /// Multiplied by the rate from `[features.server_tools.pricing]`
+    /// to populate `cost_microcents` for billing.
+    #[serde(default)]
+    pub tool_runtime_seconds: Option<f64>,
+    /// Process exit code for shell tool records. `None` when the
+    /// command never reached an `Exit` event (e.g. client disconnect
+    /// before the runtime signaled completion); clients see this
+    /// surfaced as `status: "incomplete"` with a `timeout` outcome on
+    /// the `shell_call_output` item, but the usage record preserves
+    /// the "never reported" vs "exited 0" distinction.
+    #[serde(default)]
+    pub tool_exit_code: Option<i32>,
 }
 
 fn default_record_type() -> String {
diff --git a/src/observability/metrics.rs b/src/observability/metrics.rs
index 2736bc6..163f6ba 100644
--- a/src/observability/metrics.rs
+++ b/src/observability/metrics.rs
@@ -647,84 +647,115 @@ pub fn record_file_search(
     }
 }
 
-/// Record file search tool iteration in the middleware loop.
-///
-/// Tracks iteration behavior for the file_search middleware, enabling:
-/// - Iteration count distribution analysis
-/// - Detection of potential infinite loops
-/// - Optimization of max_iterations setting
-/// - Understanding of multi-turn search patterns
-///
-/// # Arguments
-/// * `iteration` - Current iteration number (1-indexed)
-/// * `is_final` - Whether this is the final iteration (hit limit or completed)
-/// * `reason` - Why the iteration ended ("completed", "limit_reached", "no_tool_call", "error")
-pub fn record_file_search_iteration(iteration: u32, is_final: bool, reason: &str) {
+/// Record a web search tool execution.
+pub fn record_web_search(status: &str, duration_secs: f64, results_count: u32) {
     #[cfg(feature = "prometheus")]
     {
-        counter!("rag_file_search_iterations_total").increment(1);
+        counter!(
+            "web_search_total",
+            "status" => status.to_string(),
+        )
+        .increment(1);
 
-        if is_final {
-            histogram!("rag_file_search_iteration_count", "reason" => reason.to_string())
-                .record(iteration as f64);
+        histogram!(
+            "web_search_duration_seconds",
+            "status" => status.to_string(),
+        )
+        .record(duration_secs);
 
-            counter!(
-                "rag_file_search_completions_total",
-                "reason" => reason.to_string()
-            )
-            .increment(1);
-        }
+        histogram!("web_search_results_count").record(results_count as f64);
     }
     #[cfg(not(feature = "prometheus"))]
     {
-        let _ = (iteration, is_final, reason);
+        let _ = (status, duration_secs, results_count);
     }
 }
 
-/// Record a web search tool execution.
-pub fn record_web_search(status: &str, duration_secs: f64, results_count: u32) {
+/// Record a shell tool execution.
+///
+/// Emitted once per shell call at the end of the spawned task. The
+/// `shell_tool_runtime_seconds` histogram is the primary signal for
+/// cost attribution; `shell_tool_cost_microcents` is the precomputed
+/// (`runtime_seconds * rate`) value for ops teams that aggregate
+/// directly off the gateway metrics. The `status` label distinguishes
+/// natural completion from client-disconnect aborts. The `runtime`
+/// label names which runtime executed (e.g. `microsandbox`).
+pub fn record_shell_execution(
+    duration_secs: f64,
+    exit_code: i32,
+    status: &str,
+    runtime: &str,
+    cost_microcents: i64,
+) {
     #[cfg(feature = "prometheus")]
     {
         counter!(
-            "web_search_total",
+            "shell_tool_executions_total",
             "status" => status.to_string(),
+            "runtime" => runtime.to_string(),
         )
         .increment(1);
-
         histogram!(
-            "web_search_duration_seconds",
+            "shell_tool_runtime_seconds",
             "status" => status.to_string(),
+            "runtime" => runtime.to_string(),
         )
         .record(duration_secs);
-
-        histogram!("web_search_results_count").record(results_count as f64);
+        histogram!(
+            "shell_tool_exit_code",
+            "status" => status.to_string(),
+            "runtime" => runtime.to_string(),
+        )
+        .record(exit_code as f64);
+        counter!(
+            "shell_tool_cost_microcents_total",
+            "status" => status.to_string(),
+            "runtime" => runtime.to_string(),
+        )
+        .increment(cost_microcents.max(0) as u64);
     }
     #[cfg(not(feature = "prometheus"))]
     {
-        let _ = (status, duration_secs, results_count);
+        let _ = (duration_secs, exit_code, status, runtime, cost_microcents);
     }
 }
 
-/// Record web search tool iteration in the middleware loop.
-pub fn record_web_search_iteration(iteration: u32, is_final: bool, reason: &str) {
+/// Record one iteration of the server-tool orchestrator loop.
+///
+/// Emitted by `ToolLoopRunner` once per iteration regardless of which
+/// tool fired. `tools` lists the names of all enabled server tools for
+/// the request (e.g. `"file_search"`, `"web_search"`). On the final
+/// iteration, `reason` describes why the loop exited
+/// (`"completed"`, `"limit_reached"`, `"error"`, `"no_callback"`).
+pub fn record_server_tool_iteration(iteration: u32, is_final: bool, reason: &str, tools: &[&str]) {
     #[cfg(feature = "prometheus")]
     {
-        counter!("web_search_iterations_total").increment(1);
+        let tools_label = tools.join(",");
+        counter!(
+            "server_tool_iterations_total",
+            "tools" => tools_label.clone(),
+        )
+        .increment(1);
 
         if is_final {
-            histogram!("web_search_iteration_count", "reason" => reason.to_string())
-                .record(iteration as f64);
+            histogram!(
+                "server_tool_iteration_count",
+                "reason" => reason.to_string(),
+                "tools" => tools_label.clone(),
+            )
+            .record(iteration as f64);
 
             counter!(
-                "web_search_completions_total",
-                "reason" => reason.to_string()
+                "server_tool_completions_total",
+                "reason" => reason.to_string(),
+                "tools" => tools_label,
             )
             .increment(1);
         }
     }
     #[cfg(not(feature = "prometheus"))]
     {
-        let _ = (iteration, is_final, reason);
+        let _ = (iteration, is_final, reason, tools);
     }
 }
 
diff --git a/src/openapi.rs b/src/openapi.rs
index c5b3572..55f1ea3 100644
--- a/src/openapi.rs
+++ b/src/openapi.rs
@@ -387,6 +387,19 @@ requests_per_minute = 120
         // Public API routes
         api::api_v1_chat_completions,
         api::api_v1_responses,
+        api::api_v1_responses_compact,
+        api::responses_lookup::api_v1_responses_get,
+        api::responses_lookup::api_v1_responses_cancel,
+        api::responses_lookup::api_v1_responses_delete,
+        api::containers::api_v1_containers_create,
+        api::containers::api_v1_containers_list,
+        api::containers::api_v1_containers_get,
+        api::containers::api_v1_containers_delete,
+        api::containers::api_v1_containers_list_files,
+        api::containers::api_v1_containers_file_upload,
+        api::containers::api_v1_containers_file_get,
+        api::containers::api_v1_containers_file_delete,
+        api::containers::api_v1_containers_file_content,
         api::api_v1_completions,
         api::api_v1_embeddings,
         api::api_v1_models,
@@ -802,6 +815,42 @@ requests_per_minute = 120
         api_types::audio::TranslationVerboseResponse,
         // API types - Responses
         api_types::CreateResponsesPayload,
+        api_types::CompactRequest,
+        // API types - Containers
+        api::containers::CreateContainerRequest,
+        api_types::responses::ContainerExpiresAfter,
+        api_types::responses::ContainerExpiresAfterAnchor,
+        api_types::responses::ShellNetworkPolicy,
+        // API types - Responses tool definitions (`tools[]` variants).
+        // Registered so the OpenAPI spec emits a `oneOf` of named tool
+        // schemas under the `Tool` slot; the conformance script matches
+        // variants against OpenAI's `Tool` union by literal `type` value.
+        api_types::responses::ResponsesToolDefinition,
+        api_types::responses::FunctionTool,
+        api_types::responses::FunctionToolType,
+        api_types::responses::McpTool,
+        api_types::responses::McpToolType,
+        api_types::responses::McpRequireApproval,
+        api_types::responses::McpApprovalMode,
+        api_types::responses::McpApprovalFilter,
+        api_types::responses::McpAllowedTools,
+        api_types::responses::McpToolFilter,
+        api_types::responses::ToolSearchTool,
+        api_types::responses::ToolSearchToolType,
+        api_types::responses::ToolSearchExecution,
+        api_types::responses::ToolSearchRankerKind,
+        api_types::responses::ShellTool,
+        api_types::responses::ShellToolType,
+        api_types::responses::FileSearchTool,
+        api_types::responses::FileSearchToolType,
+        api_types::responses::WebSearchPreviewTool,
+        api_types::responses::WebSearchPreviewToolType,
+        api_types::responses::WebSearchPreview20250311Tool,
+        api_types::responses::WebSearchPreview20250311ToolType,
+        api_types::responses::WebSearchTool,
+        api_types::responses::WebSearchToolType,
+        api_types::responses::WebSearch20250826Tool,
+        api_types::responses::WebSearch20250826ToolType,
         // Models response
         api::CombinedModelsResponse,
         // Admin models - Organization
diff --git a/src/providers/anthropic/convert.rs b/src/providers/anthropic/convert.rs
index 0766b2f..5a2952e 100644
--- a/src/providers/anthropic/convert.rs
+++ b/src/providers/anthropic/convert.rs
@@ -593,6 +593,15 @@ pub fn convert_responses_input_to_messages(
                     }
                     ResponsesInputItem::WebSearchCall(_)
                     | ResponsesInputItem::FileSearchCall(_)
+                    | ResponsesInputItem::ShellCall(_)
+                    | ResponsesInputItem::ShellCallOutput(_)
+                    | ResponsesInputItem::McpListTools(_)
+                    | ResponsesInputItem::McpCall(_)
+                    | ResponsesInputItem::McpApprovalRequest(_)
+                    | ResponsesInputItem::McpApprovalResponse(_)
+                    | ResponsesInputItem::ToolSearchCall(_)
+                    | ResponsesInputItem::ToolSearchOutput(_)
+                    | ResponsesInputItem::Compaction(_)
                     | ResponsesInputItem::ImageGeneration(_) => {
                         // These are server-side tool calls that don't need translation
                         // to Anthropic format - they're OpenAI-specific features
@@ -699,33 +708,26 @@ pub fn convert_responses_tools(
 
     for tool in tools {
         match tool {
-            ResponsesToolDefinition::Function(value) => {
-                // Extract function tool definition from generic JSON
-                // Expected format: { "type": "function", "name": "...", "description": "...", "parameters": {...}, "cache_control": {...} }
-                if let Some(name) = value.get("name").and_then(|v| v.as_str()) {
-                    let description = value
-                        .get("description")
-                        .and_then(|v| v.as_str())
-                        .map(|s| s.to_string());
-                    let parameters = value
-                        .get("parameters")
-                        .cloned()
-                        .unwrap_or(serde_json::json!({"type": "object", "properties": {}}));
-
-                    // Extract cache_control from JSON if present
-                    let cache_control = value
-                        .get("cache_control")
-                        .and_then(|v| serde_json::from_value::<CacheControl>(v.clone()).ok())
-                        .as_ref()
-                        .and_then(|cc| convert_cache_control(Some(cc)));
-
-                    anthropic_tools.push(AnthropicTool {
-                        name: name.to_string(),
-                        description,
-                        input_schema: parameters,
-                        cache_control,
-                    });
-                }
+            ResponsesToolDefinition::Function(func) => {
+                // Expected shape mirrors OpenAI's FunctionTool. `extras`
+                // carries pipeline-specific extras like `cache_control`
+                // (Hadrian extension) and the MCP rewrite's `annotations`.
+                let parameters = func
+                    .parameters
+                    .unwrap_or_else(|| serde_json::json!({"type": "object", "properties": {}}));
+                let cache_control = func
+                    .extras
+                    .get("cache_control")
+                    .and_then(|v| serde_json::from_value::<CacheControl>(v.clone()).ok())
+                    .as_ref()
+                    .and_then(|cc| convert_cache_control(Some(cc)));
+
+                anthropic_tools.push(AnthropicTool {
+                    name: func.name,
+                    description: func.description,
+                    input_schema: parameters,
+                    cache_control,
+                });
             }
             ResponsesToolDefinition::WebSearchPreview(_)
             | ResponsesToolDefinition::WebSearchPreview20250311(_)
@@ -735,6 +737,35 @@ pub fn convert_responses_tools(
                 // before reaching provider-specific conversion. This branch is a safety net.
                 tracing::warn!("Unexpected web_search tool variant reached Anthropic conversion");
             }
+            ResponsesToolDefinition::Shell(_) => {
+                // Shell tool is OpenAI-specific (only the passthrough runtime forwards
+                // it). When the upstream is Anthropic, the request shouldn't include a
+                // shell tool — drop it with a warning rather than crashing.
+                tracing::warn!(
+                    "Shell tool reached Anthropic conversion — only OpenAI passthrough is \
+                     supported for shell in the current build; dropping the tool definition"
+                );
+            }
+            ResponsesToolDefinition::Mcp(_) => {
+                // Under `passthrough_openai` mode this branch is unreachable
+                // (preprocess rejects non-OpenAI providers). Under `hadrian_hosted`
+                // the rewrite replaces every MCP entry with function tools before
+                // we reach here. Anything slipping through is a defensive drop.
+                tracing::warn!(
+                    "MCP tool reached Anthropic conversion — should have been rewritten \
+                     under hadrian_hosted or rejected under passthrough_openai; dropping"
+                );
+            }
+            ResponsesToolDefinition::ToolSearch(_) => {
+                // Hadrian-internal: under `hadrian_hosted` the MCP rewrite consumes
+                // any caller-supplied `tool_search` entry (reading its `ranker`
+                // override) and synthesizes its own function tool. Anything reaching
+                // here is a defensive drop.
+                tracing::warn!(
+                    "tool_search tool reached Anthropic conversion — should have been \
+                     consumed by the MCP rewrite; dropping"
+                );
+            }
             ResponsesToolDefinition::FileSearch(file_search) => {
                 // File search is handled by the gateway middleware, but the model needs to know
                 // how to call it. Convert to a function tool so the model can generate proper
@@ -773,6 +804,15 @@ pub fn convert_responses_tool_choice(
             tracing::warn!("Web search tool choice not supported by Anthropic");
             None
         }
+        ResponsesToolChoice::Shell(_) => Some(AnthropicToolChoice::Tool {
+            name: "shell".to_string(),
+        }),
+        ResponsesToolChoice::Mcp(_) => {
+            // Reaches Anthropic only when the hadrian_hosted rewrite was
+            // skipped. Fall back to forcing any tool.
+            tracing::warn!("MCP tool choice without a hosted rewrite; falling back to `any`");
+            Some(AnthropicToolChoice::Any)
+        }
     })
 }
 
@@ -1087,7 +1127,7 @@ mod tests {
         },
         responses::{
             EasyInputMessage, EasyInputMessageContent, EasyInputMessageRole, FunctionCallOutput,
-            FunctionCallOutputType, FunctionToolCall, FunctionToolCallType,
+            FunctionCallOutputType, FunctionTool, FunctionToolCall, FunctionToolCallType,
             ResponseInputImageDetail, ResponsesNamedToolChoice, ResponsesNamedToolChoiceType,
         },
     };
@@ -1895,17 +1935,20 @@ mod tests {
 
     #[test]
     fn test_convert_responses_tools() {
-        let tools = Some(vec![ResponsesToolDefinition::Function(serde_json::json!({
-            "type": "function",
-            "name": "get_weather",
-            "description": "Get weather for a city",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "city": {"type": "string"}
+        let tools = Some(vec![ResponsesToolDefinition::Function(
+            FunctionTool::from_json(serde_json::json!({
+                "type": "function",
+                "name": "get_weather",
+                "description": "Get weather for a city",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "city": {"type": "string"}
+                    }
                 }
-            }
-        }))]);
+            }))
+            .unwrap(),
+        )]);
 
         let result = convert_responses_tools(tools);
 
@@ -2235,12 +2278,15 @@ mod tests {
         use crate::api_types::responses::{FileSearchTool, FileSearchToolType};
 
         let tools = Some(vec![
-            ResponsesToolDefinition::Function(serde_json::json!({
-                "type": "function",
-                "name": "get_weather",
-                "description": "Get weather",
-                "parameters": {"type": "object", "properties": {}}
-            })),
+            ResponsesToolDefinition::Function(
+                FunctionTool::from_json(serde_json::json!({
+                    "type": "function",
+                    "name": "get_weather",
+                    "description": "Get weather",
+                    "parameters": {"type": "object", "properties": {}}
+                }))
+                .unwrap(),
+            ),
             ResponsesToolDefinition::FileSearch(FileSearchTool {
                 type_: FileSearchToolType::FileSearch,
                 vector_store_ids: vec!["vs_456".to_string()],
diff --git a/src/providers/azure_openai/mod.rs b/src/providers/azure_openai/mod.rs
index aa1f223..1365fbd 100644
--- a/src/providers/azure_openai/mod.rs
+++ b/src/providers/azure_openai/mod.rs
@@ -261,6 +261,50 @@ impl Provider for AzureOpenAIProvider {
         providers::build_response(response, stream).await
     }
 
+    #[tracing::instrument(
+        skip(self, client, payload),
+        fields(
+            provider = "azure_openai",
+            operation = "responses_compact",
+            model = %payload.model,
+        )
+    )]
+    async fn create_responses_compact(
+        &self,
+        client: &reqwest::Client,
+        payload: crate::api_types::CompactRequest,
+    ) -> Result<Response, ProviderError> {
+        let (header_name, header_value) = self.get_auth_header().await?;
+        let timeout = self.timeout;
+        let stream = payload.stream;
+        let body = serde_json::to_vec(&payload).unwrap_or_default();
+        let url = format!("{}/v1/responses/compact", self.base_url);
+
+        let response = with_circuit_breaker_and_retry(
+            self.circuit_breaker.as_deref(),
+            &self.circuit_breaker_config,
+            &self.retry,
+            "azure_openai",
+            "responses_compact",
+            || async {
+                client
+                    .post(&url)
+                    .header(header_name, &*header_value)
+                    .header("content-type", "application/json")
+                    .timeout(timeout)
+                    .body(body.clone())
+                    .send()
+                    .await
+            },
+        )
+        .await?;
+
+        if !response.status().is_success() {
+            return error_response::<AzureOpenAiErrorParser>(response).await;
+        }
+        providers::build_response(response, stream).await
+    }
+
     #[tracing::instrument(
         skip(self, client, payload),
         fields(
diff --git a/src/providers/bedrock/convert.rs b/src/providers/bedrock/convert.rs
index 40fae96..a14ddef 100644
--- a/src/providers/bedrock/convert.rs
+++ b/src/providers/bedrock/convert.rs
@@ -605,6 +605,15 @@ pub(super) fn convert_responses_input_to_bedrock_messages(
                     }
                     ResponsesInputItem::WebSearchCall(_)
                     | ResponsesInputItem::FileSearchCall(_)
+                    | ResponsesInputItem::ShellCall(_)
+                    | ResponsesInputItem::ShellCallOutput(_)
+                    | ResponsesInputItem::McpListTools(_)
+                    | ResponsesInputItem::McpCall(_)
+                    | ResponsesInputItem::McpApprovalRequest(_)
+                    | ResponsesInputItem::McpApprovalResponse(_)
+                    | ResponsesInputItem::ToolSearchCall(_)
+                    | ResponsesInputItem::ToolSearchOutput(_)
+                    | ResponsesInputItem::Compaction(_)
                     | ResponsesInputItem::ImageGeneration(_) => {
                         // These are server-side tool calls that don't need translation
                     }
@@ -712,28 +721,21 @@ pub(super) fn convert_responses_tools_to_bedrock(
 
     for tool in tools {
         match tool {
-            ResponsesToolDefinition::Function(value) => {
-                // Extract function tool definition from generic JSON
-                if let Some(name) = value.get("name").and_then(|v| v.as_str()) {
-                    let description = value
-                        .get("description")
-                        .and_then(|v| v.as_str())
-                        .map(|s| s.to_string());
-                    let parameters = value
-                        .get("parameters")
-                        .cloned()
-                        .unwrap_or(serde_json::json!({"type": "object", "properties": {}}));
-
-                    bedrock_tools.push(BedrockTool::with_spec(BedrockToolSpec {
-                        name: name.to_string(),
-                        description,
-                        input_schema: BedrockInputSchema { json: parameters },
-                    }));
+            ResponsesToolDefinition::Function(func) => {
+                let parameters = func
+                    .parameters
+                    .unwrap_or_else(|| serde_json::json!({"type": "object", "properties": {}}));
+                let has_cache_control = func.extras.contains_key("cache_control");
 
-                    // Insert cache point after tool if cache_control is set
-                    if value.get("cache_control").is_some() {
-                        bedrock_tools.push(BedrockTool::cache_point());
-                    }
+                bedrock_tools.push(BedrockTool::with_spec(BedrockToolSpec {
+                    name: func.name,
+                    description: func.description,
+                    input_schema: BedrockInputSchema { json: parameters },
+                }));
+
+                // Insert cache point after tool if cache_control is set
+                if has_cache_control {
+                    bedrock_tools.push(BedrockTool::cache_point());
                 }
             }
             ResponsesToolDefinition::WebSearchPreview(_)
@@ -743,6 +745,24 @@ pub(super) fn convert_responses_tools_to_bedrock(
                 // Dead code: preprocessed to function tools in execution.rs
                 tracing::warn!("Unexpected web_search tool variant reached Bedrock conversion");
             }
+            ResponsesToolDefinition::Shell(_) => {
+                tracing::warn!(
+                    "Shell tool reached Bedrock conversion — only OpenAI passthrough is \
+                     supported for shell in the current build; dropping the tool definition"
+                );
+            }
+            ResponsesToolDefinition::Mcp(_) => {
+                tracing::warn!(
+                    "MCP tool reached Bedrock conversion — `mcp` requires `mode = \
+                     passthrough_openai` and an OpenAI/Azure upstream; dropping the tool definition"
+                );
+            }
+            ResponsesToolDefinition::ToolSearch(_) => {
+                tracing::warn!(
+                    "tool_search tool reached Bedrock conversion — should have been consumed \
+                     by the MCP rewrite under hadrian_hosted; dropping the tool definition"
+                );
+            }
             ResponsesToolDefinition::FileSearch(file_search) => {
                 // File search is handled by the gateway middleware
                 bedrock_tools.push(BedrockTool::with_spec(BedrockToolSpec {
@@ -785,6 +805,16 @@ pub(super) fn convert_responses_tool_choice_to_bedrock(
             tracing::warn!("Web search tool choice not supported by Bedrock");
             None
         }
+        ResponsesToolChoice::Shell(_) => Some(BedrockToolChoice::Tool {
+            name: "shell".to_string(),
+        }),
+        ResponsesToolChoice::Mcp(_) => {
+            // Reaches Bedrock only when the hadrian_hosted rewrite was
+            // skipped (mcp feature off or no matching `mcp` tool entry).
+            // No equivalent on Bedrock — fall back to forcing any tool.
+            tracing::warn!("MCP tool choice without a hosted rewrite; falling back to `any`");
+            Some(BedrockToolChoice::Any {})
+        }
     })
 }
 
@@ -1710,8 +1740,8 @@ mod cache_control_tests {
             ToolDefinitionFunction, ToolType,
         },
         responses::{
-            FileSearchTool, FileSearchToolType, ResponseInputContentItem, ResponseInputImageDetail,
-            ResponsesToolDefinition,
+            FileSearchTool, FileSearchToolType, FunctionTool, ResponseInputContentItem,
+            ResponseInputImageDetail, ResponsesToolDefinition,
         },
     };
 
@@ -2079,13 +2109,16 @@ mod cache_control_tests {
 
     #[test]
     fn test_convert_responses_tools_function_with_cache_control() {
-        let tools = Some(vec![ResponsesToolDefinition::Function(serde_json::json!({
-            "type": "function",
-            "name": "get_weather",
-            "description": "Get weather",
-            "parameters": {"type": "object", "properties": {}},
-            "cache_control": {"type": "ephemeral"}
-        }))]);
+        let tools = Some(vec![ResponsesToolDefinition::Function(
+            FunctionTool::from_json(serde_json::json!({
+                "type": "function",
+                "name": "get_weather",
+                "description": "Get weather",
+                "parameters": {"type": "object", "properties": {}},
+                "cache_control": {"type": "ephemeral"}
+            }))
+            .unwrap(),
+        )]);
 
         let result = convert_responses_tools_to_bedrock(tools);
         assert!(result.is_some());
@@ -2133,12 +2166,15 @@ mod cache_control_tests {
 
     #[test]
     fn test_convert_responses_tools_function_without_cache_control() {
-        let tools = Some(vec![ResponsesToolDefinition::Function(serde_json::json!({
-            "type": "function",
-            "name": "get_weather",
-            "description": "Get weather",
-            "parameters": {"type": "object", "properties": {}}
-        }))]);
+        let tools = Some(vec![ResponsesToolDefinition::Function(
+            FunctionTool::from_json(serde_json::json!({
+                "type": "function",
+                "name": "get_weather",
+                "description": "Get weather",
+                "parameters": {"type": "object", "properties": {}}
+            }))
+            .unwrap(),
+        )]);
 
         let result = convert_responses_tools_to_bedrock(tools);
         assert!(result.is_some());
diff --git a/src/providers/fallback.rs b/src/providers/fallback.rs
index 1091c6c..9aa0bac 100644
--- a/src/providers/fallback.rs
+++ b/src/providers/fallback.rs
@@ -60,6 +60,22 @@ pub fn classify_provider_error(error: &ProviderError) -> FallbackDecision {
 
         // Internal errors are typically programming errors - don't retry
         ProviderError::Internal(_) => FallbackDecision::NoRetry,
+
+        // Unsupported operations won't succeed on another provider of
+        // the same type — bail out instead of cycling fallbacks.
+        ProviderError::Unsupported(_) => FallbackDecision::NoRetry,
+
+        // BadGateway covers gateway-side dependency failures (e.g. an
+        // MCP server returning 503 during tools/list rewrite). Treat
+        // like a transient upstream error and let the fallback chain
+        // try the next provider — the next attempt re-runs the rewrite,
+        // and if the dependency comes back the request can succeed.
+        ProviderError::BadGateway(_, _) => FallbackDecision::Retry,
+
+        // BadRequest is a caller-side problem detected in a pipeline
+        // step (e.g. ambiguous MCP `tool_choice`). Retrying a different
+        // provider won't help — the request itself is malformed.
+        ProviderError::BadRequest(_, _) => FallbackDecision::NoRetry,
     }
 }
 
diff --git a/src/providers/mod.rs b/src/providers/mod.rs
index 935ad6e..e46ef74 100644
--- a/src/providers/mod.rs
+++ b/src/providers/mod.rs
@@ -150,6 +150,30 @@ pub enum ProviderError {
     #[error("Internal provider error: {0}")]
     Internal(String),
 
+    /// The provider does not implement the requested operation. Maps to
+    /// HTTP 501 with `error_code = "not_supported"` so clients can
+    /// distinguish from generic provider errors.
+    #[error("{0}")]
+    Unsupported(String),
+
+    /// An upstream the gateway depends on (e.g. a remote MCP server
+    /// during the `tools/list` rewrite, or a downstream sandbox API)
+    /// failed in a caller-visible way. Maps to HTTP 502 with the
+    /// supplied `(error_code, message)` so clients can distinguish
+    /// "the gateway tried but the dependency was unreachable" from
+    /// generic 500s. Use only for errors where exposing the message
+    /// won't leak internal infrastructure detail.
+    #[error("{1}")]
+    BadGateway(&'static str, String),
+
+    /// The caller's request is malformed in a way that pipeline steps
+    /// only detect once they have context the route layer doesn't
+    /// (e.g. which MCP tools survive the `allowed_tools` filter at
+    /// rewrite time). Maps to HTTP 400 with the supplied
+    /// `(error_code, message)`.
+    #[error("{1}")]
+    BadRequest(&'static str, String),
+
     #[error("{0}")]
     CircuitBreakerOpen(#[from] circuit_breaker::CircuitBreakerError),
 }
@@ -157,10 +181,12 @@ pub enum ProviderError {
 impl From<ProviderError> for StatusCode {
     fn from(err: ProviderError) -> Self {
         match err {
-            ProviderError::Request(_) => StatusCode::BAD_GATEWAY,
+            ProviderError::Request(_) | ProviderError::BadGateway(_, _) => StatusCode::BAD_GATEWAY,
             ProviderError::ResponseBuilder(_) | ProviderError::Internal(_) => {
                 StatusCode::INTERNAL_SERVER_ERROR
             }
+            ProviderError::Unsupported(_) => StatusCode::NOT_IMPLEMENTED,
+            ProviderError::BadRequest(_, _) => StatusCode::BAD_REQUEST,
             ProviderError::CircuitBreakerOpen(_) => StatusCode::SERVICE_UNAVAILABLE,
         }
     }
@@ -188,6 +214,11 @@ impl IntoResponse for ProviderError {
                 "internal",
                 "Internal provider error".to_string(),
             ),
+            ProviderError::Unsupported(msg) => {
+                (StatusCode::NOT_IMPLEMENTED, "not_supported", msg.clone())
+            }
+            ProviderError::BadGateway(code, msg) => (StatusCode::BAD_GATEWAY, *code, msg.clone()),
+            ProviderError::BadRequest(code, msg) => (StatusCode::BAD_REQUEST, *code, msg.clone()),
             ProviderError::CircuitBreakerOpen(e) => (
                 StatusCode::SERVICE_UNAVAILABLE,
                 "circuit_breaker_open",
@@ -242,6 +273,20 @@ pub trait Provider: Send + Sync {
         payload: CreateResponsesPayload,
     ) -> Result<Response, ProviderError>;
 
+    /// Compact a context window via the provider's standalone compact
+    /// endpoint. Only OpenAI-compatible providers implement this; the
+    /// default returns `Unsupported` so non-OpenAI providers surface a
+    /// clean 501 to the caller.
+    async fn create_responses_compact(
+        &self,
+        _client: &reqwest::Client,
+        _payload: crate::api_types::CompactRequest,
+    ) -> Result<Response, ProviderError> {
+        Err(ProviderError::Unsupported(
+            "compaction is not supported by this provider".to_string(),
+        ))
+    }
+
     async fn create_completion(
         &self,
         client: &reqwest::Client,
@@ -1006,6 +1051,8 @@ pub async fn log_media_usage(params: MediaUsageParams<'_>) -> (Option<i64>, bool
             tool_url: None,
             tool_bytes_fetched: None,
             tool_results_count: None,
+            tool_runtime_seconds: None,
+            tool_exit_code: None,
         };
 
         let db = db_pool.clone();
diff --git a/src/providers/open_ai/mod.rs b/src/providers/open_ai/mod.rs
index 85e5701..5c97d8d 100644
--- a/src/providers/open_ai/mod.rs
+++ b/src/providers/open_ai/mod.rs
@@ -278,6 +278,42 @@ impl Provider for OpenAICompatibleProvider {
         providers::build_response(response, stream).await
     }
 
+    #[tracing::instrument(
+        skip(self, client, payload),
+        fields(
+            provider = "openai",
+            operation = "responses_compact",
+            model = %payload.model,
+        )
+    )]
+    async fn create_responses_compact(
+        &self,
+        client: &reqwest::Client,
+        payload: crate::api_types::CompactRequest,
+    ) -> Result<Response, ProviderError> {
+        let url = format!("{}/responses/compact", self.base_url);
+        let stream = payload.stream;
+        let body = serde_json::to_vec(&payload).unwrap_or_default();
+
+        let response = with_circuit_breaker_and_retry(
+            self.circuit_breaker.as_deref(),
+            &self.circuit_breaker_config,
+            &self.retry,
+            "openai",
+            "responses_compact",
+            || async {
+                self.build_request(client.post(&url))
+                    .header(CONTENT_TYPE, "application/json")
+                    .body(body.clone())
+                    .send()
+                    .await
+            },
+        )
+        .await?;
+
+        providers::build_response(response, stream).await
+    }
+
     #[tracing::instrument(
         skip(self, client, payload),
         fields(
diff --git a/src/providers/test/mod.rs b/src/providers/test/mod.rs
index be253fc..89efc83 100644
--- a/src/providers/test/mod.rs
+++ b/src/providers/test/mod.rs
@@ -653,26 +653,35 @@ impl Provider for TestProvider {
         // Use requested dimensions or default to 1536 (OpenAI's ada-002 default)
         let dims = payload.dimensions.unwrap_or(1536) as usize;
 
-        // Extract text from input
-        let text = match &payload.input {
-            crate::api_types::embeddings::EmbeddingInput::Text(t) => t.clone(),
-            crate::api_types::embeddings::EmbeddingInput::TextArray(arr) => arr.join(" "),
-            crate::api_types::embeddings::EmbeddingInput::Tokens(_) => String::new(),
-            crate::api_types::embeddings::EmbeddingInput::TokenArrays(_) => String::new(),
-            crate::api_types::embeddings::EmbeddingInput::Multimodal(_) => String::new(),
+        // Collect input texts. Batch (`TextArray`) inputs produce one
+        // embedding per element — mirroring real embedding APIs — so
+        // callers like Hadrian-side tool search can embed a catalog in
+        // one request.
+        let texts: Vec<String> = match &payload.input {
+            crate::api_types::embeddings::EmbeddingInput::Text(t) => vec![t.clone()],
+            crate::api_types::embeddings::EmbeddingInput::TextArray(arr) => arr.clone(),
+            crate::api_types::embeddings::EmbeddingInput::Tokens(_) => vec![String::new()],
+            crate::api_types::embeddings::EmbeddingInput::TokenArrays(_) => vec![String::new()],
+            crate::api_types::embeddings::EmbeddingInput::Multimodal(_) => vec![String::new()],
         };
 
         // Generate word-based embeddings so texts sharing words have positive cosine similarity.
         // This enables semantic search testing without a real embedding provider.
-        let embedding = generate_word_based_embedding(&text, dims);
+        let data: Vec<_> = texts
+            .iter()
+            .enumerate()
+            .map(|(i, text)| {
+                json!({
+                    "object": "embedding",
+                    "embedding": generate_word_based_embedding(text, dims),
+                    "index": i
+                })
+            })
+            .collect();
 
         build_json_response(json!({
             "object": "list",
-            "data": [{
-                "object": "embedding",
-                "embedding": embedding,
-                "index": 0
-            }],
+            "data": data,
             "model": payload.model,
             "usage": {
                 "prompt_tokens": 8,
diff --git a/src/providers/vertex/convert.rs b/src/providers/vertex/convert.rs
index 2de6a0c..dcf45ac 100644
--- a/src/providers/vertex/convert.rs
+++ b/src/providers/vertex/convert.rs
@@ -681,6 +681,15 @@ pub(super) fn convert_responses_input_to_vertex(
                     }
                     ResponsesInputItem::WebSearchCall(_)
                     | ResponsesInputItem::FileSearchCall(_)
+                    | ResponsesInputItem::ShellCall(_)
+                    | ResponsesInputItem::ShellCallOutput(_)
+                    | ResponsesInputItem::McpListTools(_)
+                    | ResponsesInputItem::McpCall(_)
+                    | ResponsesInputItem::McpApprovalRequest(_)
+                    | ResponsesInputItem::McpApprovalResponse(_)
+                    | ResponsesInputItem::ToolSearchCall(_)
+                    | ResponsesInputItem::ToolSearchOutput(_)
+                    | ResponsesInputItem::Compaction(_)
                     | ResponsesInputItem::ImageGeneration(_) => {
                         // Server-side tool calls not supported by Vertex
                     }
@@ -753,22 +762,12 @@ pub(super) fn convert_responses_tools_to_vertex(
 
     for tool in tools {
         match tool {
-            ResponsesToolDefinition::Function(value) => {
-                // Extract function tool definition from generic JSON
-                // Expected: { "type": "function", "name": "...", "description": "...", "parameters": {...} }
-                if let Some(name) = value.get("name").and_then(|v| v.as_str()) {
-                    let description = value
-                        .get("description")
-                        .and_then(|v| v.as_str())
-                        .map(|s| s.to_string());
-                    let parameters = value.get("parameters").cloned();
-
-                    function_declarations.push(VertexFunctionDeclaration {
-                        name: name.to_string(),
-                        description,
-                        parameters,
-                    });
-                }
+            ResponsesToolDefinition::Function(func) => {
+                function_declarations.push(VertexFunctionDeclaration {
+                    name: func.name,
+                    description: func.description,
+                    parameters: func.parameters,
+                });
             }
             ResponsesToolDefinition::WebSearchPreview(_)
             | ResponsesToolDefinition::WebSearchPreview20250311(_)
@@ -777,6 +776,24 @@ pub(super) fn convert_responses_tools_to_vertex(
                 // Dead code: preprocessed to function tools in execution.rs
                 tracing::warn!("Unexpected web_search tool variant reached Vertex conversion");
             }
+            ResponsesToolDefinition::Shell(_) => {
+                tracing::warn!(
+                    "Shell tool reached Vertex conversion — only OpenAI passthrough is \
+                     supported for shell in the current build; dropping the tool definition"
+                );
+            }
+            ResponsesToolDefinition::Mcp(_) => {
+                tracing::warn!(
+                    "MCP tool reached Vertex conversion — `mcp` requires `mode = \
+                     passthrough_openai` and an OpenAI/Azure upstream; dropping the tool definition"
+                );
+            }
+            ResponsesToolDefinition::ToolSearch(_) => {
+                tracing::warn!(
+                    "tool_search tool reached Vertex conversion — should have been consumed \
+                     by the MCP rewrite under hadrian_hosted; dropping the tool definition"
+                );
+            }
             ResponsesToolDefinition::FileSearch(_) => {
                 // File search is handled by the gateway middleware, but the model needs to know
                 // how to call it. Convert to a function declaration so the model can generate proper
@@ -818,6 +835,16 @@ pub(super) fn convert_responses_tool_choice_to_vertex(
                 tracing::warn!("Web search tool choice not supported by Vertex AI");
                 (VertexFunctionCallingMode::Auto, None)
             }
+            ResponsesToolChoice::Shell(_) => (
+                VertexFunctionCallingMode::Any,
+                Some(vec!["shell".to_string()]),
+            ),
+            ResponsesToolChoice::Mcp(_) => {
+                // Reaches Vertex only when the hadrian_hosted rewrite
+                // was skipped. Fall back to forcing any tool.
+                tracing::warn!("MCP tool choice without a hosted rewrite; falling back to `any`");
+                (VertexFunctionCallingMode::Any, None)
+            }
         };
         VertexToolConfig {
             function_calling_config: VertexFunctionCallingConfig {
@@ -1143,7 +1170,7 @@ mod responses_api_tests {
     };
     use crate::api_types::responses::{
         EasyInputMessage, EasyInputMessageContent, FunctionCallOutput, FunctionCallOutputType,
-        FunctionToolCall, FunctionToolCallType, OutputItemFunctionCallStatus,
+        FunctionTool, FunctionToolCall, FunctionToolCallType, OutputItemFunctionCallStatus,
         OutputItemFunctionCallType, OutputMessage, OutputMessageContentItem, OutputMessageStatus,
         ResponseInputImageDetail, ResponsesNamedToolChoice, ResponsesNamedToolChoiceType,
     };
@@ -1321,18 +1348,21 @@ mod responses_api_tests {
 
     #[test]
     fn test_convert_responses_tools_function() {
-        let tools = Some(vec![ResponsesToolDefinition::Function(serde_json::json!({
-            "type": "function",
-            "name": "get_weather",
-            "description": "Get weather for a location",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "location": {"type": "string"}
-                },
-                "required": ["location"]
-            }
-        }))]);
+        let tools = Some(vec![ResponsesToolDefinition::Function(
+            FunctionTool::from_json(serde_json::json!({
+                "type": "function",
+                "name": "get_weather",
+                "description": "Get weather for a location",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string"}
+                    },
+                    "required": ["location"]
+                }
+            }))
+            .unwrap(),
+        )]);
 
         let vertex_tools = convert_responses_tools_to_vertex(tools).unwrap();
 
@@ -1350,14 +1380,20 @@ mod responses_api_tests {
     #[test]
     fn test_convert_responses_tools_multiple() {
         let tools = Some(vec![
-            ResponsesToolDefinition::Function(serde_json::json!({
-                "name": "tool1",
-                "description": "First tool"
-            })),
-            ResponsesToolDefinition::Function(serde_json::json!({
-                "name": "tool2",
-                "description": "Second tool"
-            })),
+            ResponsesToolDefinition::Function(
+                FunctionTool::from_json(serde_json::json!({
+                    "name": "tool1",
+                    "description": "First tool"
+                }))
+                .unwrap(),
+            ),
+            ResponsesToolDefinition::Function(
+                FunctionTool::from_json(serde_json::json!({
+                    "name": "tool2",
+                    "description": "Second tool"
+                }))
+                .unwrap(),
+            ),
         ]);
 
         let vertex_tools = convert_responses_tools_to_vertex(tools).unwrap();
@@ -1672,11 +1708,14 @@ mod responses_api_tests {
         use crate::api_types::responses::{FileSearchTool, FileSearchToolType};
 
         let tools = Some(vec![
-            ResponsesToolDefinition::Function(serde_json::json!({
-                "name": "get_weather",
-                "description": "Get weather",
-                "parameters": {"type": "object", "properties": {}}
-            })),
+            ResponsesToolDefinition::Function(
+                FunctionTool::from_json(serde_json::json!({
+                    "name": "get_weather",
+                    "description": "Get weather",
+                    "parameters": {"type": "object", "properties": {}}
+                }))
+                .unwrap(),
+            ),
             ResponsesToolDefinition::FileSearch(FileSearchTool {
                 type_: FileSearchToolType::FileSearch,
                 vector_store_ids: vec!["vs_456".to_string()],
diff --git a/src/routes/api/chat.rs b/src/routes/api/chat.rs
index 20a8c48..8516aa0 100644
--- a/src/routes/api/chat.rs
+++ b/src/routes/api/chat.rs
@@ -10,6 +10,8 @@ use super::{
     messages_contain_images, reasoning_effort_to_string, response_format_to_string,
     responses_reasoning_effort_to_string, should_bypass_cache,
 };
+#[cfg(feature = "server")]
+use crate::services::response_persister::persist_non_streaming;
 use crate::{
     AppState, api_types,
     auth::AuthenticatedRequest,
@@ -18,14 +20,10 @@ use crate::{
     middleware::{AuthzContext, ClientInfo, RequestId},
     models::UsageLogEntry,
     routes::execution::{
-        ChatCompletionExecutor, CompletionExecutor, ExecutionResult, ProviderExecutor,
-        ResponsesExecutor, execute_with_fallback,
+        ChatCompletionExecutor, CompactExecutor, CompletionExecutor, ExecutionResult,
+        ProviderExecutor, ResponsesExecutor, execute_with_fallback,
     },
     routing::{resolver, route_model_extended, route_models_extended},
-    services::{
-        FileSearchAuthContext, FileSearchContext, ProviderCallback, WebSearchContext,
-        wrap_streaming_with_file_search, wrap_streaming_with_web_search,
-    },
 };
 
 /// Cache status for tracking cache hits/misses in response headers.
@@ -167,6 +165,260 @@ pub(super) async fn apply_output_guardrails(
     }
 }
 
+/// Two skill entries refer to the same logical skill iff their type and
+/// identity match. Used by the container-bound merge to avoid mounting
+/// the same skill twice when a request both names it explicitly and
+/// inherits it from a `container_reference`.
+fn skills_have_same_identity(
+    a: &crate::api_types::RequestSkill,
+    b: &crate::api_types::RequestSkill,
+) -> bool {
+    use crate::api_types::RequestSkill;
+    match (a, b) {
+        (RequestSkill::SkillReference(x), RequestSkill::SkillReference(y)) => {
+            x.skill_id == y.skill_id
+        }
+        (RequestSkill::Inline(x), RequestSkill::Inline(y)) => x.name == y.name,
+        _ => false,
+    }
+}
+
+/// Whether a non-streaming `/v1/responses` request needs the
+/// forced-streaming bridge on account of a `hadrian_hosted` MCP tool.
+///
+/// The server-tool loop that intercepts and runs MCP `tools/call`s only
+/// operates on SSE bodies, so a non-streaming caller must have
+/// `payload.stream` flipped on internally (the result is folded back to
+/// JSON before responding). `passthrough_openai` is deliberately
+/// excluded: there OpenAI/Azure run the MCP loop upstream and already
+/// return a complete non-streaming response.
+#[cfg(feature = "mcp")]
+fn request_needs_mcp_loop(
+    payload: &api_types::CreateResponsesPayload,
+    mcp_cfg: Option<&crate::config::McpConfig>,
+    mcp_service_present: bool,
+) -> bool {
+    payload
+        .tools
+        .as_ref()
+        .is_some_and(|t| t.iter().any(|tt| tt.is_mcp()))
+        && mcp_service_present
+        && mcp_cfg.is_some_and(crate::config::McpConfig::is_hadrian_hosted)
+}
+
+/// True iff the request carries a `tool_search` tool entry whose
+/// Hadrian-extension `ranker` is explicitly `semantic`.
+#[cfg(feature = "mcp")]
+fn payload_requests_semantic_tool_search(payload: &api_types::CreateResponsesPayload) -> bool {
+    use crate::api_types::responses::ToolSearchRankerKind;
+    payload.tools.as_ref().is_some_and(|tools| {
+        tools.iter().any(|t| {
+            t.as_tool_search()
+                .and_then(|ts| ts.ranker)
+                .is_some_and(|r| r == ToolSearchRankerKind::Semantic)
+        })
+    })
+}
+
+/// True iff the request has an `mcp` tool that would be deferred via
+/// Hadrian-side tool search (`defer_loading` without native passthrough).
+#[cfg(feature = "mcp")]
+fn payload_has_deferred_mcp_tool(payload: &api_types::CreateResponsesPayload) -> bool {
+    payload.tools.as_ref().is_some_and(|tools| {
+        tools
+            .iter()
+            .filter_map(|t| t.as_mcp())
+            .any(|m| m.defer_loading == Some(true) && m.defer_loading_passthrough != Some(true))
+    })
+}
+
+fn provider_supports_passthrough_shell(provider: &crate::config::ProviderConfig) -> bool {
+    use crate::config::ProviderConfig;
+    matches!(provider, ProviderConfig::OpenAi(_)) || {
+        #[cfg(feature = "provider-azure")]
+        {
+            matches!(provider, ProviderConfig::AzureOpenAi(_))
+        }
+        #[cfg(not(feature = "provider-azure"))]
+        {
+            false
+        }
+    }
+}
+
+/// Resolve `input_file` parts into byte blobs for `/mnt/data` staging.
+///
+/// Returns an empty `Vec` (without doing any I/O) when the request
+/// doesn't declare a shell tool — staging is only useful when the
+/// model can actually reach the files via shell. Errors from the
+/// resolver map onto 400 / 502-eligible API errors with stable codes.
+#[cfg(feature = "server")]
+async fn stage_input_files_if_shell(
+    state: &crate::AppState,
+    payload: &crate::api_types::CreateResponsesPayload,
+    owner: Option<crate::db::repos::ResponseOwner>,
+) -> Result<Vec<crate::services::input_file_staging::StagedFile>, ApiError> {
+    let shell_requested = payload
+        .tools
+        .as_ref()
+        .map(|tools| {
+            tools.iter().any(|t| {
+                t.is_shell()
+                    || matches!(
+                        t,
+                        crate::api_types::responses::ResponsesToolDefinition::Function(f)
+                            if f.name == "shell"
+                    )
+            })
+        })
+        .unwrap_or(false);
+    if !shell_requested {
+        return Ok(Vec::new());
+    }
+    crate::services::input_file_staging::stage_input_files(
+        state,
+        payload,
+        &state.config.features.containers,
+        owner,
+    )
+    .await
+    .map_err(|e| {
+        use crate::services::input_file_staging::StageError;
+        let status = match e {
+            StageError::Storage(_) => StatusCode::INTERNAL_SERVER_ERROR,
+            StageError::FetchFailed(_) | StageError::HttpStatus(_) => StatusCode::BAD_GATEWAY,
+            _ => StatusCode::BAD_REQUEST,
+        };
+        let code = e.error_code();
+        ApiError::new(status, code, e.to_string())
+    })
+}
+
+/// Serialize a Responses-API payload for storage in `responses.request_payload`,
+/// stripping inline base64 blobs that are already resolved into separate
+/// container files / staged buffers.
+///
+/// Concretely: `input_file.file_data` carries the raw bytes the model
+/// uploaded (often megabytes of base64 in a single string). The file
+/// has already been resolved into `StagedFile` (for /mnt/data) and, when
+/// persistence is on, into a `container_files` row. Storing the blob a
+/// second time in JSONB doubles the row size and slows every later
+/// `GET /v1/responses/{id}`. We replace the blob with a placeholder
+/// note so the persisted payload still records that an inline file
+/// was present, just not its contents.
+fn serialize_payload_for_storage(
+    payload: &crate::api_types::CreateResponsesPayload,
+) -> serde_json::Value {
+    let mut value = serde_json::to_value(payload).unwrap_or(serde_json::Value::Null);
+    strip_input_file_data(&mut value);
+    strip_mcp_credentials(&mut value);
+    value
+}
+
+/// Walk a serialized payload, replacing every `input_file.file_data`
+/// (a base64 data URL) with a small `{ "_omitted": "..."}` marker.
+fn strip_input_file_data(value: &mut serde_json::Value) {
+    use serde_json::Value;
+    match value {
+        Value::Object(map) => {
+            // An `input_file` part: redact `file_data` if present.
+            if map.get("type").and_then(|v| v.as_str()) == Some("input_file")
+                && let Some(file_data) = map.get_mut("file_data")
+                && let Value::String(s) = file_data
+            {
+                let len = s.len();
+                *file_data = Value::String(format!("_omitted_{len}_bytes"));
+            }
+            // Recurse — `input` items, nested message parts, etc.
+            for (_, v) in map.iter_mut() {
+                strip_input_file_data(v);
+            }
+        }
+        Value::Array(items) => {
+            for v in items.iter_mut() {
+                strip_input_file_data(v);
+            }
+        }
+        _ => {}
+    }
+}
+
+/// Walk a serialized payload, scrubbing caller-supplied credentials on
+/// every `mcp` tool entry before persistence. Matches OpenAI's
+/// documented behaviour: `authorization` and `headers` are discarded
+/// after each request, and `server_url` is trimmed to scheme + host so
+/// no path / query info is retained.
+fn strip_mcp_credentials(value: &mut serde_json::Value) {
+    use serde_json::Value;
+    match value {
+        Value::Object(map) => {
+            if map.get("type").and_then(|v| v.as_str()) == Some("mcp") {
+                map.remove("authorization");
+                map.remove("headers");
+                if let Some(Value::String(url)) = map.get("server_url") {
+                    let trimmed = trim_url_to_origin(url);
+                    map.insert("server_url".into(), Value::String(trimmed));
+                }
+            }
+            for (_, v) in map.iter_mut() {
+                strip_mcp_credentials(v);
+            }
+        }
+        Value::Array(items) => {
+            for v in items.iter_mut() {
+                strip_mcp_credentials(v);
+            }
+        }
+        _ => {}
+    }
+}
+
+/// Return `url` reduced to `scheme://host[:port]` — drops path, query,
+/// and fragment. Falls back to the original string when parsing fails
+/// so we never silently lose the value.
+pub(crate) fn trim_url_to_origin(url: &str) -> String {
+    let Ok(parsed) = url::Url::parse(url) else {
+        return url.to_string();
+    };
+    let host = match parsed.host_str() {
+        Some(h) => h,
+        None => return url.to_string(),
+    };
+    let scheme = parsed.scheme();
+    match parsed.port() {
+        Some(p) => format!("{scheme}://{host}:{p}"),
+        None => format!("{scheme}://{host}"),
+    }
+}
+
+/// Resolve a chain reuse opportunity: if `prev_id` is a response in
+/// this org and its row carries a still-active `container_id`, return
+/// it so the new request reattaches to the same VM. Returns `None`
+/// (causing the executor to fall back to a fresh container) on any
+/// not-found / expired / cross-org situation — chain reuse is implicit
+/// from the user's perspective so we silently start fresh rather than
+/// erroring.
+#[cfg(feature = "server")]
+async fn resolve_chained_container_id(
+    store: &crate::services::ResponsesStore,
+    containers: &crate::services::containers::ContainersService,
+    prev_id: &str,
+    org_id: uuid::Uuid,
+) -> Option<String> {
+    let prev = match store.get(prev_id, org_id).await {
+        Ok(rec) => rec,
+        Err(_) => return None,
+    };
+    let candidate = prev.container_id?;
+    let container = containers.get_container(&candidate, org_id).await.ok()?;
+    match container.status {
+        crate::db::repos::ContainerStatus::Active => Some(candidate),
+        crate::db::repos::ContainerStatus::Expired | crate::db::repos::ContainerStatus::Deleted => {
+            None
+        }
+    }
+}
+
 /// Modifies the assistant content in a chat completion response JSON.
 ///
 /// Returns the modified response body, or None if modification failed.
@@ -234,6 +486,8 @@ pub(super) fn build_streaming_usage_entry(
             tool_url: None,
             tool_bytes_fetched: None,
             tool_results_count: None,
+            tool_runtime_seconds: None,
+            tool_exit_code: None,
         })
     } else if state.default_user_id.is_some() || state.default_org_id.is_some() {
         // Anonymous mode: attribute to the default user/org so streaming usage
@@ -271,6 +525,8 @@ pub(super) fn build_streaming_usage_entry(
             tool_url: None,
             tool_bytes_fetched: None,
             tool_results_count: None,
+            tool_runtime_seconds: None,
+            tool_exit_code: None,
         })
     } else {
         None
@@ -284,7 +540,7 @@ pub(super) fn build_streaming_usage_entry(
 /// - FinalOnly: Pass chunks through, evaluate complete response at end
 /// - Buffered: Evaluate periodically during streaming
 /// - PerChunk: Evaluate each chunk individually
-pub(super) fn wrap_streaming_with_guardrails(
+pub fn wrap_streaming_with_guardrails(
     response: Response,
     output_guardrails: &crate::guardrails::OutputGuardrails,
     user_id: Option<String>,
@@ -1115,7 +1371,6 @@ pub async fn api_v1_responses(
     // Route the model to a provider with dynamic support
     let model_clone = payload.model.clone();
     let models_clone = payload.models.clone();
-    let is_streaming = payload.stream;
     let routed = route_models_extended(
         model_clone.as_deref(),
         models_clone.as_deref(),
@@ -1159,6 +1414,216 @@ pub async fn api_v1_responses(
         })?;
     }
 
+    // Shell-tool passthrough requires an OpenAI-compatible upstream
+    // (OpenAI's hosted runtime or Azure OpenAI). Reject early instead
+    // of dropping the tool silently in a downstream provider's
+    // convert.rs.
+    let payload_has_shell = payload
+        .tools
+        .as_ref()
+        .map(|t| t.iter().any(|tt| tt.is_shell()))
+        .unwrap_or(false);
+    if payload_has_shell
+        && matches!(
+            state.config.features.shell,
+            crate::config::ShellRuntimeConfig::PassthroughOpenAI
+        )
+        && !provider_supports_passthrough_shell(&provider_config)
+    {
+        return Err(ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "passthrough_requires_openai_upstream",
+            "shell-tool passthrough is configured but the resolved provider is not OpenAI-compatible",
+        ));
+    }
+
+    // MCP-tool admission. Validates every `{"type": "mcp", ...}` entry
+    // against operator config + the resolved provider. Failure here is
+    // a clean 400 with the variant's stable error code — for background
+    // requests this is the only chance to reject; for foreground it
+    // spares us the upstream round-trip on doomed calls.
+    #[cfg(feature = "server")]
+    {
+        let mcp_provider =
+            crate::services::mcp_tool::McpProviderKind::from_provider(&provider_config);
+        if let Err(e) = crate::services::mcp_tool::preprocess_mcp_tools(
+            &payload,
+            state.config.features.mcp.as_ref(),
+            mcp_provider,
+        ) {
+            return Err(ApiError::new(
+                StatusCode::BAD_REQUEST,
+                e.code(),
+                e.to_string(),
+            ));
+        }
+    }
+
+    // Tool-search ranker admission. A request that explicitly asks for
+    // `semantic` ranking on a deployment with no embedding provider can't
+    // be honored — fail loud with a 400 rather than silently downgrading.
+    // (A `hybrid`/config default degrades to lexical instead; only an
+    // explicit per-request `semantic` is a hard error.)
+    #[cfg(feature = "mcp")]
+    if let Some(mcp_cfg) = state.config.features.mcp.as_ref()
+        && mcp_cfg.is_hadrian_hosted()
+        && state.tool_search_embeddings.is_none()
+        && payload_requests_semantic_tool_search(&payload)
+        && payload_has_deferred_mcp_tool(&payload)
+    {
+        return Err(ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "tool_search_ranker_unavailable",
+            "tool_search requested `semantic` ranking but this deployment has no embedding \
+             provider configured for MCP tool search",
+        ));
+    }
+
+    // MCP approval resumption. Convert any `mcp_approval_response`
+    // input items into `function_call_output` items by looking up the
+    // parked call, running it (on approve) or refusing it (on deny),
+    // and folding the result back. Only runs under `hadrian_hosted`
+    // mode with a resolved org scope.
+    #[cfg(feature = "mcp")]
+    if let (Some(mcp_cfg), Some(mcp_service), Some(org_id)) = (
+        state.config.features.mcp.as_ref(),
+        state.mcp_service.as_ref(),
+        auth.as_ref().and_then(|a| a.0.principal().org_id()),
+    ) && mcp_cfg.is_hadrian_hosted()
+        && let Err(e) = crate::services::mcp::resume_mcp_approvals(
+            &mut payload,
+            mcp_service,
+            org_id,
+            mcp_cfg.call_timeout_secs,
+        )
+        .await
+    {
+        let status = if e.is_client_error() {
+            StatusCode::BAD_REQUEST
+        } else {
+            StatusCode::BAD_GATEWAY
+        };
+        return Err(ApiError::new(status, e.code(), e.to_string()));
+    }
+
+    // Non-streaming callers that include a server-executed tool need
+    // the runner's loop to mediate the conversation server-side, the
+    // same way OpenAI's hosted Responses API does: the server runs the
+    // tool, threads paired function_call/function_call_output items
+    // into the next provider request, and returns one JSON with the
+    // full transcript. The runner only operates on SSE bodies, so we
+    // flip `payload.stream` on for the upstream call and collect the
+    // resulting stream back into a non-streaming JSON before
+    // responding. `caller_wants_streaming` preserves the caller's
+    // original intent for cache/persist branching below.
+    let caller_wants_streaming = payload.stream;
+    #[cfg(feature = "server")]
+    let payload_has_web_search = payload
+        .tools
+        .as_ref()
+        .map(|t| t.iter().any(|tt| tt.is_web_search()))
+        .unwrap_or(false);
+    #[cfg(feature = "server")]
+    let payload_has_file_search = payload
+        .tools
+        .as_ref()
+        .map(|t| t.iter().any(|tt| tt.is_file_search()))
+        .unwrap_or(false);
+    // When the request explicitly asks for the `local` environment
+    // (spec name `LocalEnvironmentParam`), the API client — not the
+    // gateway — runs the shell. Skip executor registration regardless
+    // of the operator-configured runtime so the shell_call / shell_call_output
+    // round-trip flows through to the client.
+    #[cfg(feature = "server")]
+    let request_env_is_local = payload
+        .tools
+        .as_ref()
+        .and_then(|tools| tools.iter().find_map(|t| t.as_shell()))
+        .and_then(|s| s.environment.as_ref())
+        .is_some_and(|e| e.is_local());
+    #[cfg(feature = "server")]
+    let shell_loops = payload_has_shell
+        && !request_env_is_local
+        && state
+            .shell_runtime
+            .as_ref()
+            .is_some_and(|r| !r.capabilities().passthrough_only);
+    #[cfg(feature = "server")]
+    let web_search_loops = payload_has_web_search
+        && state
+            .config
+            .features
+            .web_search
+            .as_ref()
+            .is_some_and(|_| true);
+    #[cfg(feature = "server")]
+    let file_search_loops = payload_has_file_search
+        && state.file_search_service.is_some()
+        && state
+            .config
+            .features
+            .file_search
+            .as_ref()
+            .is_some_and(|c| c.enabled);
+    // `hadrian_hosted` MCP tools run the same server-side loop as the
+    // shell/web/file_search tools, so a non-streaming caller needs the
+    // same forced-streaming bridge — otherwise the rewritten
+    // `mcp_<label>__<tool>` function call leaks back to the client
+    // unexecuted instead of being run and folded into an `mcp_call`.
+    // `passthrough_openai` is excluded: OpenAI/Azure run the loop
+    // upstream and return a complete non-streaming response themselves.
+    #[cfg(all(feature = "server", feature = "mcp"))]
+    let mcp_loops = request_needs_mcp_loop(
+        &payload,
+        state.config.features.mcp.as_ref(),
+        state.mcp_service.is_some(),
+    );
+    #[cfg(all(feature = "server", not(feature = "mcp")))]
+    let mcp_loops = false;
+    #[cfg(feature = "server")]
+    let needs_non_streaming_bridge = !caller_wants_streaming
+        && (shell_loops || web_search_loops || file_search_loops || mcp_loops);
+    // WASM has no server-executed tool loop, so there is never a
+    // forced-streaming bridge — requests forward to the provider as-is.
+    #[cfg(not(feature = "server"))]
+    let needs_non_streaming_bridge = false;
+    if needs_non_streaming_bridge {
+        payload.stream = true;
+    }
+    // Re-bind so downstream branches that operate on the actual
+    // upstream behavior (guardrails wrap, pipeline wrap) see the
+    // forced-true state. Branches that key off the caller's original
+    // intent (cache, persistence) use `caller_wants_streaming` below.
+    let is_streaming = payload.stream;
+
+    // Intersect any per-request shell `environment` overrides with the
+    // operator's `[features.server_tools.shell_limits]` envelope before
+    // we admit the request. A failure here returns 400 to the caller
+    // immediately — for background requests this is the only chance to
+    // reject; for foreground it spares us the VM-boot cost on doomed
+    // calls. Background re-validates at execution time against the
+    // current config.
+    #[cfg(feature = "server")]
+    let resolved_shell_env = {
+        let request_env = payload
+            .tools
+            .as_ref()
+            .and_then(|tools| tools.iter().find_map(|t| t.as_shell()))
+            .and_then(|s| s.environment.as_ref());
+        crate::services::shell_tool::resolve_shell_environment(
+            request_env,
+            &state.config.features.server_tools.shell_limits,
+            &state.config.features.containers,
+        )
+        .map_err(|e| {
+            ApiError::new(
+                StatusCode::BAD_REQUEST,
+                "shell_environment_rejected",
+                e.to_string(),
+            )
+        })?
+    };
+
     // Check authorization if authz context is available and API RBAC is enabled
     if let Some(Extension(ref authz)) = authz {
         // Check if file_search tool is present
@@ -1230,6 +1695,252 @@ pub async fn api_v1_responses(
     // Check if cache should be bypassed based on request headers
     let force_refresh = should_bypass_cache(&headers);
 
+    // Background mode: insert the row now and return queued JSON
+    // immediately. The background worker (jobs/background_responses.rs)
+    // claims the row asynchronously and runs the LLM in its own task,
+    // recording events via the persister. Clients tail the live event
+    // log via GET /v1/responses/{id}?stream=true&starting_after=N (the
+    // OpenAI Responses-API spec for resuming a stream) or fetch the
+    // terminal-state JSON via GET /v1/responses/{id}.
+    #[cfg(feature = "server")]
+    if payload.background == Some(true) {
+        if let Some(ref store) = state.responses_store {
+            let principal_org = auth
+                .as_ref()
+                .and_then(|a| a.api_key().and_then(|k| k.org_id))
+                .or_else(|| auth.as_ref().and_then(|a| a.principal().org_id()))
+                .or(state.default_org_id)
+                .ok_or_else(|| {
+                    ApiError::new(
+                        StatusCode::UNAUTHORIZED,
+                        "org_required",
+                        "Background responses require an authenticated org",
+                    )
+                })?;
+            let owner = crate::services::responses_pipeline::derive_response_owner(
+                &state,
+                auth.as_ref().map(|e| &e.0),
+            )
+            .ok_or_else(|| {
+                ApiError::new(
+                    StatusCode::UNAUTHORIZED,
+                    "org_required",
+                    "Background responses require an authenticated principal",
+                )
+            })?;
+            let principal_user = auth
+                .as_ref()
+                .and_then(|a| a.user_id())
+                .or(state.default_user_id);
+            let principal_api_key = auth.as_ref().and_then(|a| a.api_key().map(|k| k.key.id));
+            let principal_project = auth
+                .as_ref()
+                .and_then(|a| a.api_key().and_then(|k| k.project_id));
+            let principal_service_account = auth
+                .as_ref()
+                .and_then(|a| a.api_key().and_then(|k| k.service_account_id));
+
+            let resp_id = crate::services::ResponsesStore::new_response_id();
+            let now = chrono::Utc::now();
+            let new_row = crate::db::repos::NewResponse {
+                id: resp_id.clone(),
+                org_id: principal_org,
+                owner_type: owner.owner_type(),
+                owner_id: owner.owner_id(),
+                project_id: principal_project,
+                user_id: principal_user,
+                api_key_id: principal_api_key,
+                service_account_id: principal_service_account,
+                status: crate::db::repos::ResponseStatus::Queued,
+                background: true,
+                model: model_name.clone(),
+                provider: Some(provider_name.clone()),
+                created_at: now,
+                // Background mode persists the user's original payload
+                // verbatim — `resolve_and_inject_skills` hasn't run on
+                // this code path (it short-circuits earlier than the
+                // skill-resolution block below), so `instructions`
+                // does not contain inlined SKILL.md content. The
+                // background worker resolves skills locally at
+                // execute time so the row stays free of operator-
+                // private skill content.
+                request_payload: serialize_payload_for_storage(&payload),
+                retention_expires_at: store.retention_expires_at(now),
+            };
+            store.create(new_row).await.map_err(|e| {
+                tracing::error!(error = %e, "background dispatch failed");
+                ApiError::new(
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "background_dispatch_failed",
+                    "Failed to enqueue background response",
+                )
+            })?;
+
+            // Return the queued response envelope. The client uses
+            // resp_id to poll for status / events.
+            let queued = serde_json::json!({
+                "id": resp_id,
+                "object": "response",
+                "status": "queued",
+                "background": true,
+                "model": model_name,
+                "provider": provider_name,
+                "created_at": now.timestamp(),
+            });
+            return Ok(Response::builder()
+                .status(StatusCode::ACCEPTED)
+                .header("Content-Type", "application/json")
+                .body(Body::from(queued.to_string()))
+                .unwrap());
+        }
+        return Err(ApiError::new(
+            StatusCode::NOT_IMPLEMENTED,
+            "background_mode_requires_persistence",
+            "background=true requires a configured database".to_string(),
+        ));
+    }
+
+    // Resolve skills (Hadrian extension): fetch the bundles, mount
+    // them in the sandbox via `mounted_skills`, and prepend each
+    // SKILL.md to `payload.instructions` so the model knows the skill
+    // is available. Background-mode requests skip this — they short
+    // -circuit above and the worker resolves skills when it runs, so
+    // the persisted `request_payload` keeps the user's original input
+    // (not the rewritten instructions).
+    #[cfg(feature = "server")]
+    let principal = crate::services::responses_pipeline::PipelinePrincipal::from_auth(
+        &state,
+        auth.as_ref().map(|e| &e.0),
+    );
+
+    // Merge `shell.environment.container_auto.skills` (spec:
+    // ContainerAutoParam.skills) into `payload.skills` so the existing
+    // resolver picks them up. Spec treats per-environment skills as
+    // additive to top-level ones; we drop duplicates on identity.
+    {
+        let inline_skills: Option<Vec<crate::api_types::RequestSkill>> =
+            payload.tools.as_ref().and_then(|tools| {
+                tools.iter().find_map(|t| {
+                    t.as_shell()
+                        .and_then(|s| s.environment.as_ref())
+                        .and_then(|env| match env {
+                            crate::api_types::responses::ShellEnvironment::ContainerAuto(auto) => {
+                                auto.skills.clone()
+                            }
+                            _ => None,
+                        })
+                })
+            });
+        if let Some(extra) = inline_skills
+            && !extra.is_empty()
+        {
+            let mut merged = payload.skills.clone().unwrap_or_default();
+            for incoming in extra {
+                let dup = merged
+                    .iter()
+                    .any(|existing| skills_have_same_identity(existing, &incoming));
+                if !dup {
+                    merged.push(incoming);
+                }
+            }
+            payload.skills = Some(merged);
+        }
+    }
+
+    // If the request targets a specific container (via
+    // `environment.type = "container_reference"` or implicitly via
+    // `previous_response_id`), union that container's stored skill
+    // ids into `payload.skills` so `resolve_and_inject_skills` mounts
+    // them. Matches OpenAI's spec where skills are bound to the
+    // container, not to the response.
+    #[cfg(feature = "server")]
+    if let (Some(svc), Some(org_id)) = (state.containers_service.as_ref(), principal.org_id) {
+        let candidate_container_id: Option<String> = match (
+            resolved_shell_env.referenced_container_id.as_deref(),
+            payload.previous_response_id.as_deref(),
+            state.responses_store.as_ref(),
+        ) {
+            (Some(referenced), _, _) => Some(referenced.to_string()),
+            (None, Some(prev), Some(store)) => store
+                .get(prev, org_id)
+                .await
+                .ok()
+                .and_then(|r| r.container_id),
+            _ => None,
+        };
+        if let Some(cid) = candidate_container_id
+            && let Ok(record) = svc.get_container(&cid, org_id).await
+            && matches!(record.status, crate::db::repos::ContainerStatus::Active)
+            && let Some(json) = record.skill_ids_json.as_deref()
+            && let Ok(bound) = serde_json::from_str::<Vec<crate::api_types::RequestSkill>>(json)
+            && !bound.is_empty()
+        {
+            // Merge container-bound skills into the request, dropping
+            // duplicates by identity: same skill_id for references,
+            // same name for inline bundles. The OpenAI spec treats
+            // container-bound skills as additive to per-request ones.
+            let mut merged = payload.skills.clone().unwrap_or_default();
+            for incoming in bound {
+                let dup = merged
+                    .iter()
+                    .any(|existing| skills_have_same_identity(existing, &incoming));
+                if !dup {
+                    merged.push(incoming);
+                }
+            }
+            payload.skills = Some(merged);
+        }
+    }
+    // Snapshot the caller's original `instructions` before skill
+    // resolution rewrites them with inlined SKILL.md content. The
+    // foreground persistence block below restores this snapshot when
+    // building `request_payload`, so retrieve echoes the user's
+    // original input rather than leaking operator-private skill
+    // content to anyone with GET access in the same org.
+    #[cfg(feature = "server")]
+    let original_instructions = payload.instructions.clone();
+    #[cfg(feature = "server")]
+    let mounted_skills = crate::services::responses_pipeline::resolve_and_inject_skills(
+        &state,
+        &mut payload,
+        principal.org_id,
+    )
+    .await
+    .map_err(|e| {
+        use crate::services::responses_pipeline::SkillResolutionError as SRE;
+        let code = match &e {
+            SRE::InvalidId(_) | SRE::NotFound(_) | SRE::MissingOrg => "invalid_skill_reference",
+            SRE::UnsupportedVersion(_) => "unsupported_skill_version",
+            SRE::InvalidBase64 { .. } | SRE::InvalidUtf8 { .. } | SRE::EmptyInlineName => {
+                "invalid_inline_skill"
+            }
+            SRE::UnsupportedMediaType { .. } => "unsupported_inline_skill_media_type",
+            SRE::NoService => "skills_not_configured",
+            SRE::Db(_) => "skill_lookup_failed",
+        };
+        let status = if matches!(e, SRE::Db(_)) {
+            StatusCode::INTERNAL_SERVER_ERROR
+        } else {
+            StatusCode::BAD_REQUEST
+        };
+        ApiError::new(status, code, e.to_string())
+    })?;
+
+    // Resolve any `input_file` parts on the request into in-memory
+    // bytes that `ShellExecutor` will write to `/mnt/data` before the
+    // model's first shell command. Skipped (resolved to an empty Vec)
+    // when the request doesn't carry a shell tool or `[features.
+    // containers]` is disabled.
+    // Scope file_id references to the caller's owner so a request can't
+    // stage another tenant's Files-API uploads into its container.
+    #[cfg(feature = "server")]
+    let staging_owner = crate::services::responses_pipeline::derive_response_owner(
+        &state,
+        auth.as_ref().map(|e| &e.0),
+    );
+    #[cfg(feature = "server")]
+    let staged_input_files = stage_input_files_if_shell(&state, &payload, staging_owner).await?;
+
     // Track cache status for response headers
     let mut cache_status = CacheStatus::None;
 
@@ -1343,6 +2054,22 @@ pub async fn api_v1_responses(
     // In concurrent mode, we race guardrails with the LLM call
     // Clone provider_config early - we need it later for file_search callback
     let saved_provider_config = provider_config.clone();
+
+    // Gateway-side compaction (non-OpenAI providers only). Runs after
+    // skills resolution so the rolling token estimate includes the
+    // injected SKILL.md content but before the provider call. We
+    // log + continue on any compactor error: an oversize-but-uncompacted
+    // payload still has a fair chance of working at the provider.
+    #[cfg(feature = "server")]
+    if let Err(e) = crate::services::compactor::apply_gateway_compaction(
+        &state,
+        &saved_provider_config,
+        &mut payload,
+    )
+    .await
+    {
+        tracing::warn!(error = %e, "Gateway compaction failed; continuing with original payload");
+    }
     let (response, provider_name, model_name, provider_config) = if use_concurrent_guardrails {
         let input_guardrails = state.input_guardrails.as_ref().unwrap();
         let user_id = auth
@@ -1448,7 +2175,7 @@ pub async fn api_v1_responses(
     };
 
     // Apply output guardrails if configured
-    let (final_response, output_guardrails_headers) = if let Some(ref output_guardrails) =
+    let (final_response, output_guardrails_headers) = if let Some(ref _output_guardrails) =
         state.output_guardrails
         && response.status().is_success()
     {
@@ -1458,12 +2185,15 @@ pub async fn api_v1_responses(
         let req_id = request_id.as_ref().map(|r| r.0.0.clone());
 
         if is_streaming {
-            // Wrap streaming response with guardrails filter
-            let wrapped =
-                wrap_streaming_with_guardrails(response, output_guardrails, user_id, req_id);
-            (wrapped, Vec::new())
+            // Streaming guardrails are applied inside the shared
+            // pipeline below alongside the tool runner + persister.
+            // Suppress unused-var warnings by binding explicitly.
+            let _ = (user_id, req_id);
+            (response, Vec::new())
         } else {
-            // Apply guardrails to non-streaming response
+            // Apply guardrails to non-streaming response. Non-streaming
+            // needs ci_ip/ci_ua for audit logging, so it stays out of
+            // the shared pipeline.
             apply_output_guardrails_responses(
                 &state,
                 response,
@@ -1478,124 +2208,192 @@ pub async fn api_v1_responses(
         (response, Vec::new())
     };
 
-    // Apply file_search tool interception for streaming responses
-    // This wraps the stream to detect and execute file_search tool calls
-    let final_response = if is_streaming
-        && final_response.status().is_success()
-        && let Some(ref file_search_service) = state.file_search_service
-        && let Some(ref file_search_config) = state.config.features.file_search
-        && file_search_config.enabled
-    {
-        // Extract file_search tool definitions from the request
-        let file_search_tools: Vec<_> = payload
-            .tools
-            .as_ref()
-            .map(|tools| {
-                tools
-                    .iter()
-                    .filter_map(|t| t.as_file_search().cloned())
-                    .collect()
-            })
-            .unwrap_or_default();
-
-        if !file_search_tools.is_empty() {
-            // Extract full auth context for access control
-            let file_search_auth =
-                FileSearchAuthContext::from_auth_optional(auth.as_ref().map(|e| &e.0));
-
-            // Create the provider callback for continuation requests
-            let callback_state = state.clone();
-            let callback_provider_name = provider_name.clone();
-            let callback_provider_config = provider_config.clone();
-            let callback_model_name = model_name.clone();
-
-            let provider_callback: ProviderCallback = std::sync::Arc::new(move |payload| {
-                let state = callback_state.clone();
-                let provider_name = callback_provider_name.clone();
-                let provider_config = callback_provider_config.clone();
-                let model_name = callback_model_name.clone();
-
-                Box::pin(async move {
-                    // Set the model on the payload
-                    let mut payload = payload;
-                    payload.model = Some(model_name);
-
-                    // Execute using the same provider
-                    ResponsesExecutor::execute(&state, &provider_name, &provider_config, payload)
-                        .await
-                })
-            });
-
-            let context = FileSearchContext::new(
-                file_search_service.clone(),
-                file_search_config.clone(),
-                file_search_auth,
-                file_search_tools,
-                payload.clone(),
-            )
-            .with_provider_callback(provider_callback);
-
-            tracing::debug!(
-                vector_store_ids = ?context.get_vector_store_ids(),
-                "File search middleware enabled for request with multi-turn support"
-            );
-
-            wrap_streaming_with_file_search(final_response, context)
+    // Insert the persisted-response row up front (when store=true)
+    // so the shared pipeline can attach the persister wrap. Principal
+    // was already built up top for skill resolution.
+    #[cfg(feature = "server")]
+    let persistence_handle: Option<crate::services::responses_pipeline::PersistenceHandle> = {
+        let want_persist = state.responses_store.is_some()
+            && payload.store != Some(false)
+            && final_response.status().is_success();
+        if !want_persist {
+            None
+        } else if let (Some(store), Some(row_org), Some(owner)) = (
+            state.responses_store.as_ref(),
+            principal.org_id,
+            crate::services::responses_pipeline::derive_response_owner(
+                &state,
+                auth.as_ref().map(|e| &e.0),
+            ),
+        ) {
+            let resp_id = crate::services::ResponsesStore::new_response_id();
+            let now = chrono::Utc::now();
+            let new_row = crate::db::repos::NewResponse {
+                id: resp_id.clone(),
+                org_id: row_org,
+                owner_type: owner.owner_type(),
+                owner_id: owner.owner_id(),
+                project_id: principal.project_id,
+                user_id: principal.user_id,
+                api_key_id: principal.api_key_id,
+                service_account_id: principal.service_account_id,
+                status: crate::db::repos::ResponseStatus::InProgress,
+                background: payload.background.unwrap_or(false),
+                model: model_name.clone(),
+                provider: Some(provider_name.clone()),
+                created_at: now,
+                // Persist the caller's original instructions, not the
+                // skill-rewritten ones, so retrieve doesn't leak
+                // operator-private SKILL.md content. The execution
+                // pipeline keeps using `payload` with the rewritten
+                // instructions — only the persisted snapshot is
+                // restored.
+                request_payload: {
+                    let mut snapshot = payload.clone();
+                    snapshot.instructions = original_instructions.clone();
+                    serialize_payload_for_storage(&snapshot)
+                },
+                retention_expires_at: store.retention_expires_at(now),
+            };
+            match store.create(new_row).await {
+                Ok((record, cancel_rx)) => {
+                    Some(crate::services::responses_pipeline::PersistenceHandle {
+                        response_id: resp_id,
+                        org_id: row_org,
+                        initial_sequence_number: record.last_sequence_number,
+                        cancel_rx,
+                    })
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        error = %e,
+                        "Failed to insert response row; persistence skipped"
+                    );
+                    None
+                }
+            }
         } else {
-            final_response
+            // Persistence requires an authenticated tenant. Without
+            // an org we can't scope subsequent retrieve/cancel/delete
+            // calls safely, so persistence is silently skipped — the
+            // request still serves a response.
+            if state.responses_store.is_some() {
+                tracing::warn!(
+                    "Response persistence skipped: no org on principal (anonymous/disabled auth)"
+                );
+            }
+            None
         }
-    } else {
-        final_response
     };
-
-    // Apply web_search tool interception for streaming responses
-    let mut final_response = if is_streaming
-        && final_response.status().is_success()
-        && let Some(ref web_search_config) = state.config.features.web_search
-    {
-        let has_web_search = payload
-            .tools
-            .as_ref()
-            .map(|tools| tools.iter().any(|t| t.is_web_search()))
-            .unwrap_or(false);
-
-        if has_web_search {
-            let callback_state = state.clone();
-            let callback_provider_name = provider_name.clone();
-            let callback_provider_config = provider_config.clone();
-            let callback_model_name = model_name.clone();
-
-            let provider_callback: ProviderCallback = std::sync::Arc::new(move |payload| {
-                let state = callback_state.clone();
-                let provider_name = callback_provider_name.clone();
-                let provider_config = callback_provider_config.clone();
-                let model_name = callback_model_name.clone();
-
-                Box::pin(async move {
-                    let mut payload = payload;
-                    payload.model = Some(model_name);
-                    ResponsesExecutor::execute(&state, &provider_name, &provider_config, payload)
-                        .await
-                })
-            });
-
-            let context = WebSearchContext::new(
-                state.http_client.clone(),
-                web_search_config.clone(),
-                web_search_config.max_iterations,
-                payload.clone(),
-            )
-            .with_provider_callback(provider_callback);
-
-            tracing::debug!("Web search middleware enabled for request with multi-turn support");
-
-            wrap_streaming_with_web_search(final_response, context)
+    #[cfg(feature = "server")]
+    let persistence_id_and_org = persistence_handle
+        .as_ref()
+        .map(|h| (h.response_id.clone(), h.org_id));
+    // WASM never persists responses (no DB-backed store), so there is
+    // no response row to cache-store or persist into below.
+    #[cfg(not(feature = "server"))]
+    let persistence_id_and_org: Option<(String, uuid::Uuid)> = None;
+
+    // Apply the shared pipeline: output guardrails + server-executed
+    // tool loop + persister.
+    #[cfg(feature = "server")]
+    let mut final_response = if is_streaming {
+        let req_id_str = request_id.as_ref().map(|r| r.0.0.clone());
+        // Derive the response owner for container-persistence wiring
+        // even if `store=false` (the pipeline routes container files
+        // through the owner regardless of whether the response itself
+        // is persisted). Returns None when no auth + no default_org —
+        // in which case containers persistence is silently disabled.
+        let containers_owner = crate::services::responses_pipeline::derive_response_owner(
+            &state,
+            auth.as_ref().map(|e| &e.0),
+        );
+        // Explicit `environment.type = "container_reference"` wins
+        // over implicit `previous_response_id` chaining: when the
+        // caller named a container we attach to that exact one, and
+        // return a 400 here if it isn't usable. Implicit chaining
+        // silently falls through to a fresh container on miss because
+        // the caller didn't promise anything.
+        let container_id_hint = if let Some(ref referenced) =
+            resolved_shell_env.referenced_container_id
+        {
+            match (principal.org_id, state.containers_service.as_ref()) {
+                (Some(org_id), Some(containers_svc)) => {
+                    match containers_svc.get_container(referenced, org_id).await {
+                        Ok(c) if matches!(c.status, crate::db::repos::ContainerStatus::Active) => {
+                            Some(referenced.clone())
+                        }
+                        Ok(c) => {
+                            return Err(ApiError::new(
+                                StatusCode::BAD_REQUEST,
+                                "container_not_reusable",
+                                format!(
+                                    "Container '{}' is in status '{}' and cannot be referenced",
+                                    referenced,
+                                    c.status.as_str()
+                                ),
+                            ));
+                        }
+                        Err(_) => {
+                            return Err(ApiError::new(
+                                StatusCode::NOT_FOUND,
+                                "container_not_found",
+                                format!(
+                                    "Container '{}' was not found in this organization",
+                                    referenced
+                                ),
+                            ));
+                        }
+                    }
+                }
+                _ => {
+                    return Err(ApiError::new(
+                        StatusCode::SERVICE_UNAVAILABLE,
+                        "containers_persistence_disabled",
+                        "Container references require persistence to be enabled".to_string(),
+                    ));
+                }
+            }
         } else {
-            final_response
-        }
+            // Implicit container reuse via `previous_response_id`
+            // chaining. Walking the prior response's row gives us a
+            // clean fall-through path when the container has expired
+            // or been deleted — we silently start fresh.
+            match (
+                payload.previous_response_id.as_deref(),
+                principal.org_id,
+                state.responses_store.as_ref(),
+                state.containers_service.as_ref(),
+            ) {
+                (Some(prev_id), Some(org_id), Some(store), Some(containers_svc)) => {
+                    resolve_chained_container_id(store, containers_svc, prev_id, org_id).await
+                }
+                _ => None,
+            }
+        };
+        crate::services::responses_pipeline::apply_streaming_pipeline(
+            &state,
+            &payload,
+            provider_name.clone(),
+            provider_config.clone(),
+            model_name.clone(),
+            principal,
+            mounted_skills,
+            staged_input_files,
+            containers_owner,
+            container_id_hint,
+            resolved_shell_env.clone(),
+            req_id_str,
+            final_response,
+            persistence_handle,
+        )
     } else {
         final_response
     };
+    // WASM has no server-executed tool loop / persister pipeline; the
+    // upstream response (streaming or not) is returned unchanged.
+    #[cfg(not(feature = "server"))]
+    let mut final_response = final_response;
 
     // Add input guardrails headers
     for (key, value) in guardrails_headers {
@@ -1611,27 +2409,51 @@ pub async fn api_v1_responses(
         }
     }
 
-    // Cache successful responses (non-streaming only)
-    let final_response = if cache_status == CacheStatus::Miss
+    // If we forced streaming upstream for a non-streaming caller, fold
+    // the SSE transcript back into a single JSON response now — before
+    // cache/persist, so they see the same shape as a native
+    // non-streaming response.
+    #[cfg(feature = "server")]
+    let final_response = if needs_non_streaming_bridge {
+        crate::services::responses_pipeline::collect_streaming_response_to_json(final_response)
+            .await
+    } else {
+        final_response
+    };
+    #[cfg(not(feature = "server"))]
+    let final_response = final_response;
+
+    // Cache and/or persist the response (non-streaming only). The two
+    // operations share a materialized body: read it once, hand the
+    // bytes to whichever side wants them. Persistence is needed
+    // regardless of cache outcome — without this branch a cache hit
+    // or a cache-disabled deployment would leave the response row
+    // stuck `in_progress` until retention pruned it.
+    let needs_cache_store = cache_status == CacheStatus::Miss
         && final_response.status().is_success()
-        && !is_streaming
-    {
-        // Extract content-type and body for caching
+        && !caller_wants_streaming
+        && state.response_cache.is_some();
+    #[cfg(feature = "server")]
+    let needs_persist = !caller_wants_streaming
+        && persistence_id_and_org.is_some()
+        && state.responses_store.is_some();
+    #[cfg(not(feature = "server"))]
+    let needs_persist = false;
+    let final_response = if needs_cache_store || needs_persist {
+        // Extract content-type and body once.
         let content_type = final_response
             .headers()
             .get("Content-Type")
             .and_then(|v| v.to_str().ok())
             .unwrap_or("application/json")
             .to_string();
-
-        // Read the body bytes for caching
         let (parts, body) = final_response.into_parts();
         match axum::body::to_bytes(body, state.config.server.max_response_body_bytes).await {
             Ok(bytes) => {
                 let body_vec = bytes.to_vec();
 
                 // Store in response cache (semantic cache not yet supported for responses API)
-                if let Some(ref response_cache) = state.response_cache {
+                if needs_cache_store && let Some(ref response_cache) = state.response_cache {
                     let cache = response_cache.clone();
                     let payload_clone = payload.clone();
                     let model_clone = model_name.clone();
@@ -1654,11 +2476,30 @@ pub async fn api_v1_responses(
                     });
                 }
 
+                // Persist the non-streaming response now that the body
+                // is materialized. Streaming responses are persisted by
+                // `wrap_streaming_with_persistence` from inside its
+                // spawned task as the final event arrives.
+                #[cfg(feature = "server")]
+                if let (Some((resp_id, org_id)), Some(store)) = (
+                    persistence_id_and_org.as_ref(),
+                    state.responses_store.as_ref(),
+                ) {
+                    persist_non_streaming(
+                        store,
+                        resp_id,
+                        *org_id,
+                        &body_vec,
+                        parts.status.as_u16(),
+                    )
+                    .await;
+                }
+
                 // Rebuild response
                 Response::from_parts(parts, Body::from(body_vec))
             }
             Err(e) => {
-                tracing::warn!(error = %e, "Failed to read response body for caching");
+                tracing::warn!(error = %e, "Failed to read response body for caching/persistence");
                 // Return error - we've consumed the body
                 return Ok(Response::builder()
                     .status(StatusCode::INTERNAL_SERVER_ERROR)
@@ -1670,8 +2511,11 @@ pub async fn api_v1_responses(
         final_response
     };
 
-    // Create usage entry for streaming cost tracking
-    let usage_entry = if is_streaming {
+    // Create usage entry for streaming cost tracking. Keys off the
+    // caller's original intent: when the non-streaming bridge has
+    // folded the SSE transcript back to JSON, cost injection runs in
+    // its blocking, body-parsing mode.
+    let usage_entry = if caller_wants_streaming {
         build_streaming_usage_entry(&auth, &state, &model_name, &provider_name, {
             headers
                 .get("X-Hadrian-Project")
@@ -1698,7 +2542,7 @@ pub async fn api_v1_responses(
             max_response_body_bytes: state.config.server.max_response_body_bytes,
             streaming_idle_timeout_secs: state.config.server.streaming_idle_timeout_secs,
             validation_config: &state.config.observability.response_validation,
-            response_type: if is_streaming {
+            response_type: if caller_wants_streaming {
                 crate::validation::ResponseType::ResponseStream
             } else {
                 crate::validation::ResponseType::Response
@@ -1838,6 +2682,131 @@ async fn apply_output_guardrails_responses(
     }
 }
 
+/// Compact a context window via the provider's standalone compact
+/// endpoint.
+///
+/// Stateless passthrough: forwards `model` + `input` (and any other
+/// fields the provider accepts) to the upstream `/responses/compact`
+/// endpoint and streams the compacted window back. Only OpenAI and
+/// Azure OpenAI implement this; routing to any other provider returns
+/// 501 with `error_code = "not_supported"`.
+#[cfg(feature = "server")]
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    post,
+    path = "/api/v1/responses/compact",
+    tag = "responses",
+    request_body = api_types::CompactRequest,
+    responses(
+        (status = 200, description = "Compacted context window"),
+        (status = 400, description = "Bad request", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Provider does not support compaction", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+#[tracing::instrument(
+    name = "api.responses.compact",
+    skip(state, auth, authz, payload),
+    fields(model = %payload.model)
+)]
+pub async fn api_v1_responses_compact(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Valid(Json(mut payload)): Valid<Json<api_types::CompactRequest>>,
+) -> Result<Response, ApiError> {
+    // Route + resolve the model the same way the main responses
+    // handler does so per-org overrides and model-aliasing apply.
+    let model_clone = payload.model.clone();
+    let models_clone = payload.models.clone();
+    let routed = route_models_extended(
+        Some(model_clone.as_str()),
+        models_clone.as_deref(),
+        &state.config.providers,
+    )?;
+
+    let resolved = resolver::resolve_to_provider(
+        routed,
+        state.db.as_ref(),
+        state.cache.as_ref(),
+        state.secrets.as_ref(),
+        auth.as_ref().map(|e| &e.0),
+    )
+    .await
+    .map_err(|e| {
+        ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "provider_resolution_error",
+            format!("Failed to resolve provider: {e}"),
+        )
+    })?;
+    let (provider_name, provider_config, model_name) = (
+        resolved.provider_name,
+        resolved.provider_config,
+        resolved.model,
+    );
+    payload.model = model_name.clone();
+
+    // Per-API-key model restrictions (mirrors api_v1_responses).
+    if let Some(Extension(ref auth)) = auth
+        && let Some(api_key) = auth.api_key()
+    {
+        api_key.check_model_allowed(&model_clone).map_err(|e| {
+            ApiError::new(StatusCode::FORBIDDEN, "model_not_allowed", e.to_string())
+        })?;
+    }
+
+    // RBAC: same `model:use` policy as the main responses endpoint —
+    // compaction is a strict subset of `/responses` access.
+    if let Some(Extension(ref authz)) = authz {
+        let org_id = auth.as_ref().and_then(|a| {
+            a.api_key()
+                .and_then(|k| k.org_id.map(|id| id.to_string()))
+                .or_else(|| a.identity().and_then(|i| i.org_ids.first().cloned()))
+        });
+        let project_id = auth.as_ref().and_then(|a| {
+            a.api_key()
+                .and_then(|k| k.project_id.map(|id| id.to_string()))
+                .or_else(|| a.identity().and_then(|i| i.project_ids.first().cloned()))
+        });
+        authz
+            .require_api(
+                "model",
+                "use",
+                Some(model_clone.as_str()),
+                Some(RequestContext::new().with_stream(payload.stream)),
+                org_id.as_deref(),
+                project_id.as_deref(),
+            )
+            .await
+            .map_err(|e| {
+                ApiError::new(StatusCode::FORBIDDEN, "authorization_denied", e.to_string())
+            })?;
+    }
+
+    // Compaction sends context through the model, so it has the same
+    // data-sovereignty surface as the main responses endpoint. Apply
+    // the same per-API-key + per-request residency check.
+    let _ = check_sovereignty(
+        auth.as_ref(),
+        payload.sovereignty_requirements.as_ref(),
+        &provider_config,
+        &model_name,
+        &state.model_catalog,
+    )?;
+
+    CompactExecutor::execute(&state, &provider_name, &provider_config, payload)
+        .await
+        .map_err(|e| {
+            let (status, code) = match &e {
+                crate::providers::ProviderError::Unsupported(_) => {
+                    (StatusCode::NOT_IMPLEMENTED, "not_supported")
+                }
+                _ => (StatusCode::BAD_GATEWAY, "provider_error"),
+            };
+            ApiError::new(status, code, e.to_string())
+        })
+}
+
 /// Modifies the output_text in a responses API response JSON.
 ///
 /// Returns the modified response body, or None if modification failed.
@@ -2459,3 +3428,94 @@ fn modify_completion_content(body: &[u8], new_content: &str) -> Option<Vec<u8>>
 
     serde_json::to_vec(&json).ok()
 }
+
+#[cfg(all(test, feature = "mcp"))]
+mod mcp_loop_tests {
+    use super::request_needs_mcp_loop;
+    use crate::{
+        api_types::CreateResponsesPayload,
+        config::{McpConfig, McpMode},
+    };
+
+    fn payload_with_mcp_tool() -> CreateResponsesPayload {
+        serde_json::from_value(serde_json::json!({
+            "tools": [{
+                "type": "mcp",
+                "server_label": "platter",
+                "server_url": "http://127.0.0.1:3100/mcp"
+            }]
+        }))
+        .expect("payload parses")
+    }
+
+    fn payload_without_mcp_tool() -> CreateResponsesPayload {
+        serde_json::from_value(serde_json::json!({
+            "tools": [{ "type": "web_search" }]
+        }))
+        .expect("payload parses")
+    }
+
+    fn cfg(mode: McpMode, enabled: bool) -> McpConfig {
+        McpConfig {
+            enabled,
+            mode,
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn hadrian_hosted_mcp_tool_needs_bridge() {
+        assert!(request_needs_mcp_loop(
+            &payload_with_mcp_tool(),
+            Some(&cfg(McpMode::HadrianHosted, true)),
+            true,
+        ));
+    }
+
+    #[test]
+    fn passthrough_openai_does_not_need_bridge() {
+        // OpenAI/Azure run the loop upstream and return a complete
+        // non-streaming response, so no forced-streaming bridge.
+        assert!(!request_needs_mcp_loop(
+            &payload_with_mcp_tool(),
+            Some(&cfg(McpMode::PassthroughOpenai, true)),
+            true,
+        ));
+    }
+
+    #[test]
+    fn no_mcp_tool_does_not_need_bridge() {
+        assert!(!request_needs_mcp_loop(
+            &payload_without_mcp_tool(),
+            Some(&cfg(McpMode::HadrianHosted, true)),
+            true,
+        ));
+    }
+
+    #[test]
+    fn disabled_config_does_not_need_bridge() {
+        assert!(!request_needs_mcp_loop(
+            &payload_with_mcp_tool(),
+            Some(&cfg(McpMode::HadrianHosted, false)),
+            true,
+        ));
+    }
+
+    #[test]
+    fn missing_service_does_not_need_bridge() {
+        assert!(!request_needs_mcp_loop(
+            &payload_with_mcp_tool(),
+            Some(&cfg(McpMode::HadrianHosted, true)),
+            false,
+        ));
+    }
+
+    #[test]
+    fn missing_config_does_not_need_bridge() {
+        assert!(!request_needs_mcp_loop(
+            &payload_with_mcp_tool(),
+            None,
+            true
+        ));
+    }
+}
diff --git a/src/routes/api/containers.rs b/src/routes/api/containers.rs
new file mode 100644
index 0000000..94e106e
--- /dev/null
+++ b/src/routes/api/containers.rs
@@ -0,0 +1,1564 @@
+//! `/v1/containers/*` endpoints for the shell-tool `/mnt/data`
+//! artifact store. Spec-parity surface for OpenAI's Container resource:
+//!
+//! - `POST   /v1/containers`                         — create a container
+//! - `GET    /v1/containers/{container_id}`          — retrieve metadata
+//! - `DELETE /v1/containers/{container_id}`          — soft-delete
+//! - `POST   /v1/containers/{container_id}/files`    — upload a file
+//! - `GET    /v1/containers/{container_id}/files`    — list files
+//! - `GET    /v1/containers/{container_id}/files/{file_id}` — file metadata
+//! - `GET    /v1/containers/{container_id}/files/{file_id}/content` — raw bytes
+//! - `DELETE /v1/containers/{container_id}/files/{file_id}` — remove a file
+//!
+//! `POST /v1/containers` creates an *empty* container row (no live VM
+//! yet) so subsequent responses can attach to it via
+//! `environment.type = "container_reference"`. The VM boots on first
+//! shell call against the row.
+
+#![cfg(feature = "server")]
+
+use axum::{
+    Extension, Json,
+    body::Body,
+    extract::{FromRequest, Path, Query, State},
+    http::{HeaderMap, StatusCode, header},
+    response::Response,
+};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use super::ApiError;
+use crate::{
+    AppState,
+    auth::AuthenticatedRequest,
+    db::repos::{ContainerFileRecord, ContainerRecord},
+    middleware::AuthzContext,
+    services::containers::{ContainersService, ContainersServiceError},
+};
+
+const OBJECT_CONTAINER: &str = "container";
+const OBJECT_CONTAINER_FILE: &str = "container.file";
+const OBJECT_LIST: &str = "list";
+
+/// Wire shape for a container resource. Matches OpenAI's
+/// `Container` object so generic clients work without modification.
+#[derive(Serialize)]
+pub struct WireContainer {
+    id: String,
+    object: &'static str,
+    /// `active` | `expired` | `deleted`.
+    status: String,
+    /// Unix timestamp (seconds).
+    created_at: i64,
+    /// Unix timestamp of the last successful activity.
+    last_active_at: i64,
+    /// Unix timestamp when this container will expire (or did expire,
+    /// for terminal statuses). For `active` containers this is a
+    /// forward-looking estimate computed as
+    /// `last_active_at + idle_ttl_secs`; every shell call rolls
+    /// `last_active_at` forward, so the field moves with activity. For
+    /// `expired` / `deleted` containers it's the exact moment the row
+    /// transitioned. Always present.
+    ///
+    /// **Hadrian Extension:** OpenAI's `Container` object surfaces only
+    /// `created_at`; the proactive expiry estimate is a Hadrian addition
+    /// so clients can plan reuse without polling. The field name and
+    /// type match OpenAI's other expiring resources (e.g. Files API).
+    expires_at: i64,
+    /// **Hadrian Extension:** idle TTL applied to this container, in
+    /// seconds. Stable for the row's lifetime; clients can recompute
+    /// `expires_at` themselves from `last_active_at + idle_ttl_secs`.
+    idle_ttl_secs: i64,
+    /// **Hadrian Extension:** runtime that backed the session.
+    runtime: String,
+    /// Optional display name set at creation.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    name: Option<String>,
+    /// Memory ceiling captured at creation, formatted as the
+    /// OpenAI-spec string (e.g. `"512m"`, `"1g"`). Picks the largest
+    /// power-of-two unit that yields a clean integer. `None` when no
+    /// limit was set at creation. Matches OpenAI's `Container.memory_limit`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    memory_limit: Option<String>,
+    /// **Hadrian Extension:** memory ceiling in MiB. Stable integer
+    /// form for clients that prefer parsing it directly. Kept alongside
+    /// `memory_limit` so existing Hadrian-aware clients don't break.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    memory_limit_mb: Option<i64>,
+    /// `expires_after` block echoed back per OpenAI's spec.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expires_after: Option<WireExpiresAfter>,
+    /// **Hadrian Extension:** network policy bound to this container
+    /// at creation time (or `null` when none was set). Returned as the
+    /// same JSON shape that goes into the request body.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    network_policy: Option<serde_json::Value>,
+    /// **Hadrian Extension:** skill UUIDs bound to this container.
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    skill_ids: Vec<String>,
+    /// **Hadrian Extension:** response this container was originally
+    /// provisioned for, when implicit-created from a response. `null`
+    /// when the container was created via `POST /v1/containers`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    source_response_id: Option<String>,
+}
+
+#[derive(Serialize)]
+pub struct WireExpiresAfter {
+    anchor: &'static str,
+    minutes: i64,
+}
+
+/// Wire shape for one `container.file` row. Matches OpenAI's response
+/// to `POST /v1/containers/{id}/files` and `GET .../{file_id}`.
+#[derive(Serialize)]
+pub struct WireContainerFile {
+    id: String,
+    object: &'static str,
+    container_id: String,
+    /// Absolute path inside the container, always under `/mnt/data/`.
+    path: String,
+    /// **Hadrian Extension:** the display name (basename of `path`).
+    filename: String,
+    /// Size of the file in bytes.
+    bytes: i64,
+    /// `user` (staged from an `input_file` part) or `assistant` (written
+    /// by the model during a shell command).
+    source: String,
+    /// Best-effort MIME type.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    content_type: Option<String>,
+    /// Unix timestamp (seconds).
+    created_at: i64,
+}
+
+/// Wrapper for list endpoints. Matches OpenAI's `list` object shape
+/// (with `data`, `has_more`, plus optional `first_id` / `last_id` for
+/// cursor pagination on endpoints that need it).
+#[derive(Serialize)]
+pub struct WireList<T: Serialize> {
+    object: &'static str,
+    data: Vec<T>,
+    has_more: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    first_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    last_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ListFilesQuery {
+    /// Maximum number of files to return. Server clamps to `[1, 1000]`.
+    /// Cursor pagination (`after`) is a future enhancement.
+    #[serde(default)]
+    limit: Option<i64>,
+}
+
+/// Query params for `GET /v1/containers`. Matches OpenAI's cursor
+/// shape — `after` is an opaque `cntr_<hex>` id and pagination flows
+/// newest-first.
+#[derive(Debug, Deserialize)]
+pub struct ListContainersQuery {
+    /// Page size. Clamped to `[1, 100]` (default 20).
+    #[serde(default)]
+    limit: Option<i64>,
+    /// Cursor: the `cntr_<hex>` id of the last item from a prior page.
+    /// Unknown ids return an empty page rather than 404.
+    #[serde(default)]
+    after: Option<String>,
+}
+
+fn container_to_wire(record: ContainerRecord) -> WireContainer {
+    // For active containers compute a forward-looking expiry from the
+    // last_active_at + idle_ttl. The reaper job uses the same formula
+    // to decide when to flip the row to `expired`; surfacing it lets
+    // clients reuse a container right before it would have lapsed
+    // without having to poll. Terminal statuses use the persisted
+    // moment of transition.
+    let expires_at = record
+        .expires_at
+        .map(|t| t.timestamp())
+        .unwrap_or_else(|| record.last_active_at.timestamp() + record.idle_ttl_secs);
+    let expires_after = if record.idle_ttl_secs > 0 {
+        Some(WireExpiresAfter {
+            anchor: "last_active_at",
+            minutes: record.idle_ttl_secs / 60,
+        })
+    } else {
+        None
+    };
+    let network_policy = record
+        .network_policy_json
+        .as_deref()
+        .and_then(|s| serde_json::from_str::<serde_json::Value>(s).ok());
+    let skill_ids = record
+        .skill_ids_json
+        .as_deref()
+        .and_then(|s| serde_json::from_str::<Vec<String>>(s).ok())
+        .unwrap_or_default();
+    let memory_limit = record.memory_limit_mb.map(format_memory_limit_mb);
+    WireContainer {
+        id: record.id,
+        object: OBJECT_CONTAINER,
+        status: record.status.as_str().to_string(),
+        created_at: record.created_at.timestamp(),
+        last_active_at: record.last_active_at.timestamp(),
+        expires_at,
+        idle_ttl_secs: record.idle_ttl_secs,
+        runtime: record.runtime_label,
+        name: record.name,
+        memory_limit,
+        memory_limit_mb: record.memory_limit_mb,
+        expires_after,
+        network_policy,
+        skill_ids,
+        source_response_id: record.source_response_id,
+    }
+}
+
+/// Render a MiB-denominated memory limit as the spec string form
+/// (`"512m"`, `"1g"`, etc.). Picks `g` when the value is a whole number
+/// of GiB, otherwise `m`. Zero or negative values produce `None`-equivalent
+/// behaviour at the caller (we never pass them in).
+fn format_memory_limit_mb(mb: i64) -> String {
+    if mb > 0 && mb % 1024 == 0 {
+        format!("{}g", mb / 1024)
+    } else {
+        format!("{mb}m")
+    }
+}
+
+fn file_to_wire(record: ContainerFileRecord) -> WireContainerFile {
+    WireContainerFile {
+        id: record.id,
+        object: OBJECT_CONTAINER_FILE,
+        container_id: record.container_id,
+        path: record.path,
+        filename: record.filename,
+        bytes: record.size_bytes,
+        source: record.source.as_str().to_string(),
+        content_type: record.content_type,
+        created_at: record.created_at.timestamp(),
+    }
+}
+
+fn resolve_service(state: &AppState) -> Result<&ContainersService, ApiError> {
+    state.containers_service.as_deref().ok_or_else(|| {
+        ApiError::new(
+            StatusCode::NOT_IMPLEMENTED,
+            "containers_persistence_disabled",
+            "Container persistence requires a configured database".to_string(),
+        )
+    })
+}
+
+/// Resolve the org the request operates in. Falls back to the deployment's
+/// `default_org_id` (set in no-auth / anonymous dev mode) so the same
+/// endpoints work locally without credentials — mirroring how the responses
+/// pipeline attributes anonymous usage to the default org.
+fn require_caller_org(
+    auth: Option<&Extension<AuthenticatedRequest>>,
+    default_org: Option<Uuid>,
+) -> Result<Uuid, ApiError> {
+    auth.and_then(|Extension(a)| {
+        a.api_key()
+            .and_then(|k| k.org_id)
+            .or_else(|| a.principal().org_id())
+    })
+    .or(default_org)
+    .ok_or_else(|| {
+        ApiError::new(
+            StatusCode::UNAUTHORIZED,
+            "authentication_required",
+            "An authenticated org is required",
+        )
+    })
+}
+
+async fn enforce_authz(
+    authz: Option<&Extension<AuthzContext>>,
+    auth: Option<&Extension<AuthenticatedRequest>>,
+    action: &str,
+) -> Result<(), ApiError> {
+    let Some(Extension(authz)) = authz else {
+        return Ok(());
+    };
+    let org_id = auth.and_then(|a| {
+        a.api_key()
+            .and_then(|k| k.org_id.map(|id| id.to_string()))
+            .or_else(|| a.identity().and_then(|i| i.org_ids.first().cloned()))
+    });
+    let project_id = auth.and_then(|a| {
+        a.api_key()
+            .and_then(|k| k.project_id.map(|id| id.to_string()))
+            .or_else(|| a.identity().and_then(|i| i.project_ids.first().cloned()))
+    });
+    authz
+        .require_api(
+            "container",
+            action,
+            None,
+            None,
+            org_id.as_deref(),
+            project_id.as_deref(),
+        )
+        .await
+        .map_err(|e| ApiError::new(StatusCode::FORBIDDEN, "authorization_denied", e.to_string()))
+}
+
+/// Surface-level validation for skill entries before they're persisted
+/// onto a container row. Mirrors what `resolve_and_inject_skills` will
+/// later enforce on request — we run it eagerly here so a misshaped
+/// `inline` skill never makes it onto a stored row.
+fn validate_skill_entry(entry: &crate::api_types::RequestSkill) -> Result<(), ApiError> {
+    match entry {
+        crate::api_types::RequestSkill::SkillReference(reference) => {
+            Uuid::parse_str(&reference.skill_id).map_err(|_| {
+                ApiError::new(
+                    StatusCode::BAD_REQUEST,
+                    "invalid_skill_id",
+                    format!("skill id '{}' is not a valid UUID", reference.skill_id),
+                )
+            })?;
+            if let Some(v) = reference.version.as_deref()
+                && v != "latest"
+            {
+                return Err(ApiError::new(
+                    StatusCode::BAD_REQUEST,
+                    "unsupported_skill_version",
+                    format!("only `version = \"latest\"` is supported (got `{v}`)"),
+                ));
+            }
+            Ok(())
+        }
+        crate::api_types::RequestSkill::Inline(inline) => {
+            if inline.name.trim().is_empty() {
+                return Err(ApiError::new(
+                    StatusCode::BAD_REQUEST,
+                    "invalid_inline_skill",
+                    "inline skill `name` must be non-empty",
+                ));
+            }
+            let crate::api_types::InlineSkillSource::Base64 { media_type, data } = &inline.source;
+            if media_type != "text/markdown" {
+                return Err(ApiError::new(
+                    StatusCode::BAD_REQUEST,
+                    "unsupported_inline_skill_media_type",
+                    format!(
+                        "inline skill `{}` uses media_type `{media_type}` — only `text/markdown` is supported today",
+                        inline.name
+                    ),
+                ));
+            }
+            use base64::Engine as _;
+            base64::engine::general_purpose::STANDARD
+                .decode(data.as_bytes())
+                .map_err(|e| {
+                    ApiError::new(
+                        StatusCode::BAD_REQUEST,
+                        "invalid_inline_skill",
+                        format!("inline skill `{}` base64: {e}", inline.name),
+                    )
+                })?;
+            Ok(())
+        }
+    }
+}
+
+fn map_service_err(e: ContainersServiceError) -> ApiError {
+    match e {
+        ContainersServiceError::NotFound => ApiError::new(
+            StatusCode::NOT_FOUND,
+            "container_not_found",
+            "No such container or container file",
+        ),
+        ContainersServiceError::Expired(_) => ApiError::new(
+            StatusCode::GONE,
+            "container_expired",
+            "Container has expired and cannot be reused",
+        ),
+        ContainersServiceError::ContentUnavailable(msg) => ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "file_content_unavailable",
+            msg,
+        ),
+        ContainersServiceError::Db(msg) => {
+            tracing::error!(error = %msg, "Containers service DB error");
+            ApiError::new(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "internal_error",
+                "An internal error occurred",
+            )
+        }
+    }
+}
+
+/// Request body for `POST /v1/containers`.
+#[derive(Debug, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(deny_unknown_fields)]
+pub struct CreateContainerRequest {
+    /// Optional display name (max 255 chars).
+    #[serde(default)]
+    pub name: Option<String>,
+    /// Optional memory ceiling. Accepts OpenAI's `"1g"` / `"512m"`
+    /// strings; parsed case-insensitively. Capped by the operator's
+    /// `[features.server_tools.shell_limits].max_mem_limit_mb`.
+    #[serde(default)]
+    pub memory_limit: Option<String>,
+    /// Optional idle-TTL hint. Per OpenAI's spec: `{anchor:
+    /// "last_active_at", minutes: N}`. Capped by
+    /// `[features.containers].max_idle_ttl_secs / 60`.
+    #[serde(default)]
+    pub expires_after: Option<crate::api_types::responses::ContainerExpiresAfter>,
+    /// Optional network policy (same shape as
+    /// `tools.shell.environment.network_policy`). OpenAI types this as
+    /// a `oneOf { Disabled, Allowlist }` discriminated by `type`;
+    /// Hadrian represents it as a single flat object that validates
+    /// the same constraints at request resolution, so the schema is
+    /// rendered as an opaque `object` to avoid spurious diffs.
+    #[serde(default)]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Object))]
+    pub network_policy: Option<crate::api_types::responses::ShellNetworkPolicy>,
+    /// Skills to mount whenever a session is booted against this
+    /// container. Matches OpenAI's typed shape — see
+    /// [`crate::api_types::RequestSkill`].
+    #[serde(default)]
+    #[cfg_attr(feature = "utoipa", schema(value_type = Vec<Object>))]
+    pub skills: Vec<crate::api_types::RequestSkill>,
+    /// Files-API ids to copy into `/mnt/data` at container creation.
+    /// Spec: `CreateContainerBody.file_ids`. Each id is resolved via
+    /// the Files API (same path as `input_file` parts on a response
+    /// request) and the bytes are persisted into `container_files`
+    /// so the model can read them on first attach.
+    #[serde(default)]
+    pub file_ids: Vec<String>,
+}
+
+/// `POST /v1/containers` — create an unattached container.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    post,
+    path = "/api/v1/containers",
+    tag = "containers",
+    request_body = CreateContainerRequest,
+    responses(
+        (status = 200, description = "The created container metadata"),
+        (status = 400, description = "Request rejected", body = crate::openapi::ErrorResponse),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_create(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Json(body): Json<CreateContainerRequest>,
+) -> Result<Json<WireContainer>, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "write").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+
+    let owner = crate::services::responses_pipeline::derive_response_owner(
+        &state,
+        auth.as_ref().map(|e| &e.0),
+    )
+    .ok_or_else(|| {
+        ApiError::new(
+            StatusCode::UNAUTHORIZED,
+            "authentication_required",
+            "Container creation requires an authenticated owner",
+        )
+    })?;
+
+    let containers_cfg = &state.config.features.containers;
+    let shell_limits = &state.config.features.server_tools.shell_limits;
+
+    // ── Memory limit (request → bytes → MiB column) ──
+    let memory_limit_mb: Option<i64> = match body.memory_limit.as_deref() {
+        Some(raw) => {
+            let bytes =
+                crate::services::shell_tool::parse_memory_limit_pub(raw).ok_or_else(|| {
+                    ApiError::new(
+                        StatusCode::BAD_REQUEST,
+                        "invalid_memory_limit",
+                        format!("invalid memory_limit '{raw}'"),
+                    )
+                })?;
+            if let Some(cap_mb) = shell_limits.max_mem_limit_mb {
+                let cap_bytes = u64::from(cap_mb) * 1024 * 1024;
+                if bytes > cap_bytes {
+                    return Err(ApiError::new(
+                        StatusCode::BAD_REQUEST,
+                        "memory_limit_exceeds_cap",
+                        format!(
+                            "memory_limit {} MB exceeds operator cap {} MB",
+                            bytes / (1024 * 1024),
+                            cap_mb
+                        ),
+                    ));
+                }
+            }
+            Some(i64::try_from(bytes / (1024 * 1024)).unwrap_or(i64::MAX))
+        }
+        None => None,
+    };
+
+    // ── expires_after ──
+    let idle_ttl_secs = match body.expires_after.as_ref() {
+        Some(exp) => {
+            let max_minutes = (containers_cfg.max_idle_ttl_secs / 60) as u32;
+            if exp.minutes > max_minutes {
+                return Err(ApiError::new(
+                    StatusCode::BAD_REQUEST,
+                    "expires_after_exceeds_cap",
+                    format!(
+                        "expires_after.minutes {} exceeds operator cap of {} minutes",
+                        exp.minutes, max_minutes
+                    ),
+                ));
+            }
+            i64::from(exp.minutes) * 60
+        }
+        None => containers_cfg.default_idle_ttl_secs as i64,
+    };
+
+    // ── network_policy: validate against operator caps (resolver
+    //    accepts both inline + reference forms) and persist verbatim.
+    if let Some(ref np) = body.network_policy {
+        // Wrap in a minimal `ShellEnvironment::ContainerAuto` so the
+        // existing resolver does the validation work.
+        let env = crate::api_types::responses::ShellEnvironment::ContainerAuto(
+            crate::api_types::responses::ShellContainerAuto {
+                memory_limit: None,
+                network_policy: Some(np.clone()),
+                file_ids: None,
+                skills: None,
+                expires_after: None,
+            },
+        );
+        crate::services::shell_tool::resolve_shell_environment(
+            Some(&env),
+            shell_limits,
+            containers_cfg,
+        )
+        .map_err(|e| {
+            ApiError::new(
+                StatusCode::BAD_REQUEST,
+                "network_policy_rejected",
+                e.to_string(),
+            )
+        })?;
+    }
+    let network_policy_json = body
+        .network_policy
+        .as_ref()
+        .map(|np| serde_json::to_string(np).unwrap_or_default());
+
+    // ── skills: validate references + inline payloads up front so an
+    //    invalid skill never makes it onto the container row. We don't
+    //    actually mount them here — that happens on the first response
+    //    the container backs. Validation: shape, base64 decode, and
+    //    media_type. Stored verbatim so per-response resolve picks up
+    //    the same payload.
+    if !body.skills.is_empty() {
+        for entry in &body.skills {
+            validate_skill_entry(entry)?;
+        }
+    }
+    let skill_ids_json = if body.skills.is_empty() {
+        None
+    } else {
+        Some(serde_json::to_string(&body.skills).unwrap_or_default())
+    };
+
+    // Choose the runtime label so future requests reusing this
+    // container know which runtime backend is expected. When no shell
+    // runtime is configured we still let the row exist so that an
+    // operator switching from `passthrough_openai` to e.g.
+    // `microsandbox` later doesn't have to recreate containers.
+    let runtime_label = match &state.config.features.shell {
+        crate::config::ShellRuntimeConfig::None => "none",
+        crate::config::ShellRuntimeConfig::PassthroughOpenAI => "passthrough_openai",
+        crate::config::ShellRuntimeConfig::ClientPassthrough => "client_passthrough",
+        #[cfg(feature = "runtime-microsandbox")]
+        crate::config::ShellRuntimeConfig::Microsandbox(_) => "microsandbox",
+        #[cfg(feature = "runtime-opensandbox")]
+        crate::config::ShellRuntimeConfig::OpenSandbox(_) => "opensandbox",
+    };
+
+    let container_id = format!("cntr_{}", Uuid::new_v4().simple());
+    let name = body.name.clone();
+    if let Some(ref n) = name
+        && n.len() > 255
+    {
+        return Err(ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "name_too_long",
+            "name must be 255 chars or fewer",
+        ));
+    }
+
+    let record = svc
+        .create_explicit(
+            container_id.clone(),
+            org_id,
+            owner,
+            runtime_label,
+            idle_ttl_secs,
+            name,
+            memory_limit_mb,
+            network_policy_json,
+            skill_ids_json,
+        )
+        .await
+        .map_err(map_service_err)?;
+
+    // Spec: `CreateContainerBody.file_ids` — copy the named Files-API
+    // uploads into `/mnt/data` immediately so they're present the first
+    // time the container is attached. Fetch via the same Files service
+    // as `input_file` parts, then persist into `container_files`.
+    if !body.file_ids.is_empty() {
+        use std::str::FromStr;
+
+        use sha2::{Digest, Sha256};
+        let services = state.services.as_ref().ok_or_else(|| {
+            ApiError::new(
+                StatusCode::NOT_IMPLEMENTED,
+                "files_unavailable",
+                "Files service is unavailable; cannot resolve file_ids",
+            )
+        })?;
+        // Scope file_id lookups to the container owner so a caller can't
+        // stage another tenant's Files-API uploads. A missing owner
+        // scope (service-account owner) fails closed as not-found.
+        let (file_owner_type, file_owner_id) = owner.as_file_owner().ok_or_else(|| {
+            ApiError::new(
+                StatusCode::BAD_REQUEST,
+                "file_not_found",
+                "file_ids are not available for this owner",
+            )
+        })?;
+        let max_bytes = state.config.features.containers.max_bytes_per_file as usize;
+        let mut to_persist: Vec<crate::services::containers::PersistFileInput> =
+            Vec::with_capacity(body.file_ids.len());
+        for raw in &body.file_ids {
+            let file_id = crate::models::FileId::from_str(raw).map_err(|_| {
+                ApiError::new(
+                    StatusCode::BAD_REQUEST,
+                    "invalid_file_id",
+                    format!("file_id '{raw}' is not a valid identifier"),
+                )
+            })?;
+            let uuid = file_id.into_inner();
+            let metadata = services
+                .files
+                .get_for_owner(uuid, file_owner_type, file_owner_id)
+                .await
+                .map_err(|e| {
+                    ApiError::new(
+                        StatusCode::INTERNAL_SERVER_ERROR,
+                        "file_lookup_failed",
+                        e.to_string(),
+                    )
+                })?
+                .ok_or_else(|| {
+                    ApiError::new(
+                        StatusCode::BAD_REQUEST,
+                        "file_not_found",
+                        format!("file_id '{raw}' not found"),
+                    )
+                })?;
+            let content = services.files.get_content(uuid).await.map_err(|e| {
+                ApiError::new(
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "file_lookup_failed",
+                    e.to_string(),
+                )
+            })?;
+            if content.len() > max_bytes {
+                return Err(ApiError::new(
+                    StatusCode::PAYLOAD_TOO_LARGE,
+                    "file_too_large",
+                    format!(
+                        "file_id '{}' size {} exceeds operator cap of {} bytes",
+                        raw,
+                        content.len(),
+                        max_bytes
+                    ),
+                ));
+            }
+            let bytes = bytes::Bytes::from(content);
+            let hash = Sha256::digest(&bytes);
+            let content_hash_hex = hex::encode(hash);
+            to_persist.push(crate::services::containers::PersistFileInput {
+                file_id: format!("cfile_{}", uuid::Uuid::new_v4().simple()),
+                path: format!("/mnt/data/{}", metadata.filename),
+                filename: metadata.filename.clone(),
+                content_type: metadata.content_type.clone(),
+                source: crate::api_types::responses::ContainerFileSource::User,
+                content: bytes,
+                content_hash_hex,
+                source_response_id: None,
+                source_call_id: None,
+            });
+        }
+        let svc_for_files = svc.clone();
+        svc_for_files
+            .persist_files(&container_id, org_id, to_persist)
+            .await
+            .map_err(map_service_err)?;
+    }
+
+    Ok(Json(container_to_wire(record)))
+}
+
+/// `GET /v1/containers` — list containers in the caller's org,
+/// newest-first. Matches OpenAI's cursor pagination shape.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    get,
+    path = "/api/v1/containers",
+    tag = "containers",
+    params(
+        ("limit" = Option<i64>, Query, description = "Page size, clamped to 1..=100 (default 20)"),
+        ("after" = Option<String>, Query, description = "Cursor: cntr_<hex> id of the last item from a prior page"),
+    ),
+    responses(
+        (status = 200, description = "Containers in the org"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_list(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Query(params): Query<ListContainersQuery>,
+) -> Result<Json<WireList<WireContainer>>, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "read").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+
+    let limit = params.limit.unwrap_or(20).clamp(1, 100);
+    let mut rows = svc
+        .list_containers(org_id, limit + 1, params.after.as_deref())
+        .await
+        .map_err(map_service_err)?;
+    let has_more = rows.len() as i64 > limit;
+    rows.truncate(limit as usize);
+    let first_id = rows.first().map(|r| r.id.clone());
+    let last_id = rows.last().map(|r| r.id.clone());
+    let data = rows.into_iter().map(container_to_wire).collect();
+    Ok(Json(WireList {
+        object: OBJECT_LIST,
+        data,
+        has_more,
+        first_id,
+        last_id,
+    }))
+}
+
+/// `GET /v1/containers/{container_id}` — retrieve a container.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    get,
+    path = "/api/v1/containers/{container_id}",
+    tag = "containers",
+    params(("container_id" = String, Path, description = "Container ID (`cntr_<hex>`)")),
+    responses(
+        (status = 200, description = "The container metadata"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "Container not found", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_get(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path(container_id): Path<String>,
+) -> Result<Json<WireContainer>, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "read").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+    let record = svc
+        .get_container(&container_id, org_id)
+        .await
+        .map_err(map_service_err)?;
+    Ok(Json(container_to_wire(record)))
+}
+
+/// `GET /v1/containers/{container_id}/files` — list files.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    get,
+    path = "/api/v1/containers/{container_id}/files",
+    tag = "containers",
+    params(
+        ("container_id" = String, Path, description = "Container ID"),
+        ("limit" = Option<i64>, Query, description = "Page size, clamped to 1..=1000"),
+    ),
+    responses(
+        (status = 200, description = "Files in the container"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "Container not found", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_list_files(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path(container_id): Path<String>,
+    Query(params): Query<ListFilesQuery>,
+) -> Result<Json<WireList<WireContainerFile>>, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "read").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+
+    // 404 the listing when the container itself isn't reachable from
+    // this org. Without this an enumerator could distinguish "no
+    // container" from "container exists but is empty".
+    svc.get_container(&container_id, org_id)
+        .await
+        .map_err(map_service_err)?;
+
+    let limit = params.limit.unwrap_or(100).clamp(1, 1000);
+    // Fetch limit+1 to compute has_more, then truncate.
+    let mut rows = svc
+        .list_files(&container_id, org_id, limit + 1)
+        .await
+        .map_err(map_service_err)?;
+    let has_more = rows.len() as i64 > limit;
+    rows.truncate(limit as usize);
+    let data = rows.into_iter().map(file_to_wire).collect();
+    Ok(Json(WireList {
+        object: OBJECT_LIST,
+        data,
+        has_more,
+        first_id: None,
+        last_id: None,
+    }))
+}
+
+/// `GET /v1/containers/{container_id}/files/{file_id}` — file metadata.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    get,
+    path = "/api/v1/containers/{container_id}/files/{file_id}",
+    tag = "containers",
+    params(
+        ("container_id" = String, Path),
+        ("file_id" = String, Path),
+    ),
+    responses(
+        (status = 200, description = "The container file metadata"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "File not found", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_file_get(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path((container_id, file_id)): Path<(String, String)>,
+) -> Result<Json<WireContainerFile>, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "read").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+    let record = svc
+        .get_file(&file_id, org_id)
+        .await
+        .map_err(map_service_err)?;
+    if record.container_id != container_id {
+        // Don't leak the existence of a file in a different container —
+        // return the same 404 as a non-existent id.
+        return Err(ApiError::new(
+            StatusCode::NOT_FOUND,
+            "container_not_found",
+            "No such container or container file",
+        ));
+    }
+    Ok(Json(file_to_wire(record)))
+}
+
+/// `DELETE /v1/containers/{container_id}` — soft-delete a container.
+///
+/// Sets `status='deleted'` and evicts the matching in-memory session
+/// from the registry so the VM is torn down on the next Arc drop.
+/// The underlying `container_files` rows cascade-delete with the
+/// container row.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    delete,
+    path = "/api/v1/containers/{container_id}",
+    tag = "containers",
+    params(("container_id" = String, Path)),
+    responses(
+        (status = 204, description = "Container deleted"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "Container not found", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_delete(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path(container_id): Path<String>,
+) -> Result<StatusCode, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "delete").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+
+    // Mark the row deleted first so a concurrent reuse attempt fails
+    // the active-status check before we evict the session. The
+    // service returns 404 when the row isn't there or belongs to a
+    // different org.
+    let patch = crate::db::repos::ContainerPatch {
+        status: Some(crate::db::repos::ContainerStatus::Deleted),
+        expires_at: Some(chrono::Utc::now()),
+        ..Default::default()
+    };
+    let updated = svc
+        .update_within_org(&container_id, org_id, patch)
+        .await
+        .map_err(map_service_err)?;
+    if updated.is_none() {
+        return Err(ApiError::new(
+            StatusCode::NOT_FOUND,
+            "container_not_found",
+            "No such container",
+        ));
+    }
+
+    // Evict from the in-memory registry. Dropping the Arc lets
+    // ContainerSession::drop run, which detaches a terminate task.
+    state.container_session_registry.remove(&container_id);
+
+    Ok(StatusCode::NO_CONTENT)
+}
+
+/// `GET /v1/containers/{container_id}/files/{file_id}/content` — raw bytes.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    get,
+    path = "/api/v1/containers/{container_id}/files/{file_id}/content",
+    tag = "containers",
+    params(
+        ("container_id" = String, Path),
+        ("file_id" = String, Path),
+    ),
+    responses(
+        (status = 200, description = "Raw file bytes; Content-Type comes from the row"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "File not found", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_file_content(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path((container_id, file_id)): Path<(String, String)>,
+) -> Result<Response<Body>, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "read").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+
+    // Two-step fetch so we get the content-type + container check from
+    // the row before reading bytes — keeps the 404 path cheap.
+    let record = svc
+        .get_file(&file_id, org_id)
+        .await
+        .map_err(map_service_err)?;
+    if record.container_id != container_id {
+        return Err(ApiError::new(
+            StatusCode::NOT_FOUND,
+            "container_not_found",
+            "No such container or container file",
+        ));
+    }
+
+    let bytes = svc
+        .read_content(&file_id, org_id)
+        .await
+        .map_err(map_service_err)?;
+
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        header::CONTENT_TYPE,
+        record
+            .content_type
+            .as_deref()
+            .unwrap_or("application/octet-stream")
+            .parse()
+            .unwrap_or_else(|_| "application/octet-stream".parse().unwrap()),
+    );
+    if let Ok(disp) = content_disposition_attachment(&record.filename).parse() {
+        headers.insert(header::CONTENT_DISPOSITION, disp);
+    }
+    headers.insert(header::CONTENT_LENGTH, bytes.len().into());
+
+    let mut response = Response::new(Body::from(bytes));
+    *response.headers_mut() = headers;
+    Ok(response)
+}
+
+/// JSON body for `POST /v1/containers/{container_id}/files` when
+/// copying an existing Files-API upload into the container instead of
+/// streaming bytes via multipart. Spec shape: `{file_id: "file_..."}`.
+#[derive(Debug, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+pub struct CreateContainerFileRequest {
+    /// Files-API id of an already-uploaded file to copy into the
+    /// container's `/mnt/data`. Must belong to the caller's org.
+    pub file_id: String,
+    /// Optional override for the destination path. Same rules as the
+    /// multipart variant: rebased under `/mnt/data` and rejects `..`.
+    #[serde(default)]
+    pub path: Option<String>,
+}
+
+/// `POST /v1/containers/{container_id}/files` — upload a file into a
+/// container's `/mnt/data`. Accepts either:
+///
+/// - `multipart/form-data` with a `file` part (required) and optional
+///   `path` / `content_type` parts — streams bytes directly.
+/// - `application/json` with `{file_id: "file_..."}` — copies an
+///   existing Files-API upload into the container (same resolver as
+///   the `file_ids` array on `POST /v1/containers`).
+///
+/// Matches OpenAI's upload contract.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    post,
+    path = "/api/v1/containers/{container_id}/files",
+    tag = "containers",
+    params(("container_id" = String, Path)),
+    responses(
+        (status = 200, description = "Uploaded file metadata"),
+        (status = 400, description = "Request rejected", body = crate::openapi::ErrorResponse),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "Container not found", body = crate::openapi::ErrorResponse),
+        (status = 413, description = "Payload too large", body = crate::openapi::ErrorResponse),
+        (status = 415, description = "Unsupported Content-Type", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_file_upload(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path(container_id): Path<String>,
+    request: axum::http::Request<Body>,
+) -> Result<Json<WireContainerFile>, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "write").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+
+    // 404 the upload up front when the container isn't reachable.
+    let container = svc
+        .get_container(&container_id, org_id)
+        .await
+        .map_err(map_service_err)?;
+    if !matches!(container.status, crate::db::repos::ContainerStatus::Active) {
+        return Err(ApiError::new(
+            StatusCode::GONE,
+            "container_not_reusable",
+            format!(
+                "container is in status '{}' and cannot accept uploads",
+                container.status.as_str()
+            ),
+        ));
+    }
+
+    let content_type = request
+        .headers()
+        .get(header::CONTENT_TYPE)
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("")
+        .to_ascii_lowercase();
+
+    if content_type.starts_with("application/json") {
+        let bytes = axum::body::to_bytes(request.into_body(), usize::MAX)
+            .await
+            .map_err(|e| {
+                ApiError::new(
+                    StatusCode::BAD_REQUEST,
+                    "invalid_body",
+                    format!("failed to read request body: {e}"),
+                )
+            })?;
+        let body: CreateContainerFileRequest = serde_json::from_slice(&bytes).map_err(|e| {
+            ApiError::new(
+                StatusCode::BAD_REQUEST,
+                "invalid_body",
+                format!("invalid JSON body: {e}"),
+            )
+        })?;
+        let owner = crate::services::responses_pipeline::derive_response_owner(
+            &state,
+            auth.as_ref().map(|e| &e.0),
+        )
+        .ok_or_else(|| {
+            ApiError::new(
+                StatusCode::UNAUTHORIZED,
+                "owner_unresolved",
+                "could not resolve an owner for this request",
+            )
+        })?;
+        let record = upload_from_file_id(
+            &state,
+            svc,
+            &container_id,
+            org_id,
+            owner,
+            &body.file_id,
+            body.path,
+        )
+        .await?;
+        return Ok(Json(file_to_wire(record)));
+    }
+    if !content_type.starts_with("multipart/") {
+        return Err(ApiError::new(
+            StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            "unsupported_content_type",
+            "Content-Type must be 'multipart/form-data' or 'application/json'",
+        ));
+    }
+
+    let mut multipart = axum::extract::Multipart::from_request(request, &state)
+        .await
+        .map_err(|e| {
+            ApiError::new(
+                StatusCode::BAD_REQUEST,
+                "invalid_multipart",
+                format!("malformed multipart request: {e}"),
+            )
+        })?;
+
+    let max_bytes = state.config.features.containers.max_bytes_per_file as usize;
+    let mut filename: Option<String> = None;
+    let mut content_bytes: Option<Vec<u8>> = None;
+    let mut content_type_field: Option<String> = None;
+    let mut path_field: Option<String> = None;
+
+    while let Some(mut field) = multipart.next_field().await.map_err(|e| {
+        ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "invalid_multipart",
+            format!("malformed multipart request: {e}"),
+        )
+    })? {
+        match field.name().unwrap_or("") {
+            "file" => {
+                filename = field.file_name().map(str::to_string);
+                content_type_field = field.content_type().map(str::to_string);
+                let mut data: Vec<u8> = Vec::new();
+                while let Some(chunk) = field.chunk().await.map_err(|e| {
+                    ApiError::new(
+                        StatusCode::BAD_REQUEST,
+                        "invalid_multipart",
+                        format!("failed to read file part: {e}"),
+                    )
+                })? {
+                    if data.len() + chunk.len() > max_bytes {
+                        return Err(ApiError::new(
+                            StatusCode::PAYLOAD_TOO_LARGE,
+                            "file_too_large",
+                            format!("file size exceeds operator cap of {max_bytes} bytes"),
+                        ));
+                    }
+                    data.extend_from_slice(&chunk);
+                }
+                content_bytes = Some(data);
+            }
+            "path" => {
+                path_field = Some(field.text().await.unwrap_or_default());
+            }
+            "content_type" => {
+                content_type_field = Some(field.text().await.unwrap_or_default());
+            }
+            _ => {
+                // Skip unknown parts silently — OpenAI clients
+                // sometimes attach `purpose` or similar markers.
+                let _ = field.bytes().await;
+            }
+        }
+    }
+
+    let content = content_bytes.ok_or_else(|| {
+        ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "missing_file_part",
+            "multipart upload must include a 'file' part",
+        )
+    })?;
+    let filename = filename.unwrap_or_else(|| "upload".to_string());
+    let path = normalize_mnt_path(path_field.as_deref(), &filename)?;
+
+    let record = svc
+        .upload_file(
+            &container_id,
+            org_id,
+            path,
+            filename,
+            content_type_field,
+            content,
+            crate::api_types::responses::ContainerFileSource::User,
+            None,
+            None,
+        )
+        .await
+        .map_err(map_service_err)?;
+    Ok(Json(file_to_wire(record)))
+}
+
+/// Resolve the requested destination path under `/mnt/data`. Rebases
+/// anything else and rejects `..` traversal.
+fn normalize_mnt_path(path_field: Option<&str>, filename: &str) -> Result<String, ApiError> {
+    const MNT: &str = crate::services::container_session::MNT_DATA;
+    // The relative target comes from the explicit `path` field when
+    // present, otherwise from the (user-controlled) upload filename.
+    // Both are untrusted, so the traversal guard applies uniformly.
+    let normalised = match path_field {
+        Some(p) if !p.is_empty() => p.trim_start_matches('/').to_string(),
+        _ => filename.trim_start_matches('/').to_string(),
+    };
+    if normalised.contains("..") {
+        return Err(ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "invalid_path",
+            "path may not contain '..'",
+        ));
+    }
+    if normalised.starts_with("mnt/data/") {
+        Ok(format!("/{normalised}"))
+    } else {
+        Ok(format!("{MNT}/{normalised}"))
+    }
+}
+
+/// Copy bytes from a Files-API upload into the container. Mirrors the
+/// `file_ids` resolution path on `POST /v1/containers` so behaviour is
+/// identical between creation-time staging and post-creation copies.
+async fn upload_from_file_id(
+    state: &AppState,
+    svc: &ContainersService,
+    container_id: &str,
+    org_id: Uuid,
+    owner: crate::db::repos::ResponseOwner,
+    raw_file_id: &str,
+    path_override: Option<String>,
+) -> Result<crate::db::repos::ContainerFileRecord, ApiError> {
+    use std::str::FromStr;
+
+    let services = state.services.as_ref().ok_or_else(|| {
+        ApiError::new(
+            StatusCode::NOT_IMPLEMENTED,
+            "files_unavailable",
+            "Files service is unavailable; cannot resolve file_id",
+        )
+    })?;
+    let file_id = crate::models::FileId::from_str(raw_file_id).map_err(|_| {
+        ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "invalid_file_id",
+            format!("file_id '{raw_file_id}' is not a valid identifier"),
+        )
+    })?;
+    let uuid = file_id.into_inner();
+    // Scope to the caller's owner so a file_id belonging to another
+    // tenant resolves as not-found (no info leak).
+    let (file_owner_type, file_owner_id) = owner.as_file_owner().ok_or_else(|| {
+        ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "file_not_found",
+            format!("file_id '{raw_file_id}' not found"),
+        )
+    })?;
+    let metadata = services
+        .files
+        .get_for_owner(uuid, file_owner_type, file_owner_id)
+        .await
+        .map_err(|e| {
+            ApiError::new(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "file_lookup_failed",
+                e.to_string(),
+            )
+        })?
+        .ok_or_else(|| {
+            ApiError::new(
+                StatusCode::BAD_REQUEST,
+                "file_not_found",
+                format!("file_id '{raw_file_id}' not found"),
+            )
+        })?;
+    let content = services.files.get_content(uuid).await.map_err(|e| {
+        ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "file_lookup_failed",
+            e.to_string(),
+        )
+    })?;
+    let max_bytes = state.config.features.containers.max_bytes_per_file as usize;
+    if content.len() > max_bytes {
+        return Err(ApiError::new(
+            StatusCode::PAYLOAD_TOO_LARGE,
+            "file_too_large",
+            format!(
+                "file size {} exceeds operator cap of {} bytes",
+                content.len(),
+                max_bytes
+            ),
+        ));
+    }
+    let path = normalize_mnt_path(path_override.as_deref(), &metadata.filename)?;
+    svc.upload_file(
+        container_id,
+        org_id,
+        path,
+        metadata.filename.clone(),
+        metadata.content_type.clone(),
+        content,
+        crate::api_types::responses::ContainerFileSource::User,
+        None,
+        None,
+    )
+    .await
+    .map_err(map_service_err)
+}
+
+/// `DELETE /v1/containers/{container_id}/files/{file_id}` — remove
+/// a file from a container.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    delete,
+    path = "/api/v1/containers/{container_id}/files/{file_id}",
+    tag = "containers",
+    params(("container_id" = String, Path), ("file_id" = String, Path)),
+    responses(
+        (status = 204, description = "File deleted"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "File not found", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_containers_file_delete(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path((container_id, file_id)): Path<(String, String)>,
+) -> Result<StatusCode, ApiError> {
+    let svc = resolve_service(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "delete").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+    svc.delete_file(&container_id, &file_id, org_id)
+        .await
+        .map_err(map_service_err)?;
+    Ok(StatusCode::NO_CONTENT)
+}
+
+/// Build an RFC 6266 `Content-Disposition: attachment` header value
+/// that survives any byte sequence in `filename`.
+///
+/// Emits both an ASCII-safe quoted form (with `"` / `\` / controls /
+/// non-ASCII swapped for `_`) and an RFC 5987 `filename*=UTF-8''…`
+/// percent-encoded form. Modern clients prefer the latter and round-
+/// trip Unicode losslessly; legacy clients fall back to the quoted
+/// form. Either way the header parses — no silent drop when the model
+/// produces a filename with `"` or control chars.
+fn content_disposition_attachment(filename: &str) -> String {
+    let fallback: String = filename
+        .chars()
+        .map(|c| {
+            if matches!(c, ' '..='~') && c != '"' && c != '\\' {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect();
+    let encoded = percent_encode_rfc5987(filename);
+    format!("attachment; filename=\"{fallback}\"; filename*=UTF-8''{encoded}")
+}
+
+/// RFC 5987 `value-chars` percent-encoder. Encodes everything that
+/// isn't in the `attr-char` set so the result can land in an
+/// `ext-value` like `filename*=UTF-8''…`.
+fn percent_encode_rfc5987(s: &str) -> String {
+    // attr-char = ALPHA / DIGIT / one of "!#$&+-.^_`|~"
+    fn is_attr_char(b: u8) -> bool {
+        b.is_ascii_alphanumeric()
+            || matches!(
+                b,
+                b'!' | b'#' | b'$' | b'&' | b'+' | b'-' | b'.' | b'^' | b'_' | b'`' | b'|' | b'~'
+            )
+    }
+    let mut out = String::with_capacity(s.len());
+    for byte in s.as_bytes() {
+        if is_attr_char(*byte) {
+            out.push(*byte as char);
+        } else {
+            out.push_str(&format!("%{:02X}", byte));
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use chrono::TimeZone;
+
+    use super::*;
+    use crate::db::repos::ResponseOwnerType;
+
+    fn record(status: crate::db::repos::ContainerStatus) -> ContainerRecord {
+        ContainerRecord {
+            id: "cntr_test".into(),
+            org_id: Uuid::nil(),
+            owner_type: ResponseOwnerType::User,
+            owner_id: Uuid::nil(),
+            status,
+            runtime_label: "microsandbox".into(),
+            source_response_id: None,
+            idle_ttl_secs: 1200,
+            last_active_at: chrono::Utc.timestamp_opt(1_000_000, 0).unwrap(),
+            created_at: chrono::Utc.timestamp_opt(999_000, 0).unwrap(),
+            expires_at: None,
+            name: None,
+            memory_limit_mb: None,
+            network_policy_json: None,
+            skill_ids_json: None,
+        }
+    }
+
+    #[test]
+    fn active_container_projects_expiry_from_last_active() {
+        let wire = container_to_wire(record(crate::db::repos::ContainerStatus::Active));
+        assert_eq!(wire.last_active_at, 1_000_000);
+        assert_eq!(wire.idle_ttl_secs, 1200);
+        assert_eq!(wire.expires_at, 1_001_200);
+    }
+
+    #[test]
+    fn terminal_container_uses_persisted_expiry() {
+        let mut r = record(crate::db::repos::ContainerStatus::Expired);
+        r.expires_at = Some(chrono::Utc.timestamp_opt(1_000_500, 0).unwrap());
+        let wire = container_to_wire(r);
+        assert_eq!(wire.expires_at, 1_000_500);
+    }
+
+    #[test]
+    fn memory_limit_string_renders_clean_units() {
+        assert_eq!(format_memory_limit_mb(1024), "1g");
+        assert_eq!(format_memory_limit_mb(4096), "4g");
+        assert_eq!(format_memory_limit_mb(512), "512m");
+        assert_eq!(format_memory_limit_mb(1500), "1500m");
+    }
+
+    #[test]
+    fn wire_container_surfaces_memory_limit_string() {
+        let mut r = record(crate::db::repos::ContainerStatus::Active);
+        r.memory_limit_mb = Some(1024);
+        let wire = container_to_wire(r);
+        assert_eq!(wire.memory_limit.as_deref(), Some("1g"));
+        assert_eq!(wire.memory_limit_mb, Some(1024));
+    }
+
+    #[test]
+    fn normalize_mnt_path_rebases_relative_paths() {
+        assert_eq!(
+            normalize_mnt_path(Some("out.csv"), "fallback.txt").unwrap(),
+            "/mnt/data/out.csv"
+        );
+        assert_eq!(
+            normalize_mnt_path(Some("/mnt/data/sub/out.csv"), "fallback.txt").unwrap(),
+            "/mnt/data/sub/out.csv"
+        );
+        assert_eq!(
+            normalize_mnt_path(None, "fallback.txt").unwrap(),
+            "/mnt/data/fallback.txt"
+        );
+    }
+
+    #[test]
+    fn normalize_mnt_path_rejects_traversal() {
+        let err = normalize_mnt_path(Some("../escape.txt"), "x").unwrap_err();
+        assert!(err.to_string().starts_with("invalid_path:"), "{err}");
+    }
+
+    #[test]
+    fn normalize_mnt_path_rejects_traversal_in_filename_fallback() {
+        // No `path` field: the untrusted upload filename must still be
+        // guarded against `..` traversal.
+        let err = normalize_mnt_path(None, "../../etc/passwd").unwrap_err();
+        assert!(err.to_string().starts_with("invalid_path:"), "{err}");
+    }
+
+    #[test]
+    fn create_container_file_request_parses_file_id_json() {
+        let body: CreateContainerFileRequest =
+            serde_json::from_str(r#"{"file_id":"file_abc"}"#).unwrap();
+        assert_eq!(body.file_id, "file_abc");
+        assert!(body.path.is_none());
+    }
+
+    #[test]
+    fn create_container_file_request_parses_file_id_with_path() {
+        let body: CreateContainerFileRequest =
+            serde_json::from_str(r#"{"file_id":"file_abc","path":"sub/out.csv"}"#).unwrap();
+        assert_eq!(body.file_id, "file_abc");
+        assert_eq!(body.path.as_deref(), Some("sub/out.csv"));
+    }
+
+    #[test]
+    fn content_disposition_escapes_quotes_and_backslashes() {
+        let h = content_disposition_attachment("evil\"name.txt");
+        // ASCII fallback strips the offending quote.
+        assert!(h.contains("filename=\"evil_name.txt\""));
+        // Ext form percent-encodes it.
+        assert!(h.contains("filename*=UTF-8''evil%22name.txt"));
+    }
+
+    #[test]
+    fn content_disposition_handles_crlf_and_controls() {
+        let h = content_disposition_attachment("a\r\nInjected: yes\nb");
+        // No bare CR/LF survives in the header value — header parsers
+        // reject those, which was the bug we're fixing.
+        assert!(!h.contains('\r'));
+        assert!(!h.contains('\n'));
+        // And the encoded form preserves the original bytes for clients
+        // that decode it.
+        assert!(h.contains("%0D%0A"));
+    }
+
+    #[test]
+    fn content_disposition_preserves_unicode_in_ext_form() {
+        let h = content_disposition_attachment("café.csv");
+        // ASCII fallback degrades one underscore per non-ASCII char;
+        // ext form percent-encodes the UTF-8 bytes losslessly.
+        assert!(h.contains("filename=\"caf_.csv\""), "got: {h}");
+        assert!(h.contains("filename*=UTF-8''caf%C3%A9.csv"), "got: {h}");
+    }
+
+    #[test]
+    fn content_disposition_passes_through_plain_ascii() {
+        let h = content_disposition_attachment("report.csv");
+        assert!(h.contains("filename=\"report.csv\""));
+        assert!(h.contains("filename*=UTF-8''report.csv"));
+    }
+}
diff --git a/src/routes/api/mod.rs b/src/routes/api/mod.rs
index 2abbd0f..d221c4f 100644
--- a/src/routes/api/mod.rs
+++ b/src/routes/api/mod.rs
@@ -28,11 +28,15 @@ use crate::{
 };
 
 mod audio;
-mod chat;
+pub(crate) mod chat;
+#[cfg(feature = "server")]
+pub mod containers;
 mod embeddings;
 mod files;
 mod images;
 mod models;
+#[cfg(feature = "server")]
+pub mod responses_lookup;
 pub(crate) mod tools;
 mod vector_stores;
 
@@ -851,8 +855,42 @@ pub(crate) fn api_v1_routes(limits: ApiBodyLimits) -> Router<AppState> {
         // Tools API (Hadrian extension)
         .route("/v1/tools/web-search", post(web_search))
         .route("/v1/tools/web-fetch", post(web_fetch));
+    // Responses persistence + containers endpoints depend on the DB-backed
+    // ResponsesStore / ContainersService, which are server-only (no WASM).
     #[cfg(feature = "server")]
     let router = router
+        .route("/v1/responses/compact", post(api_v1_responses_compact))
+        .route(
+            "/v1/responses/{response_id}",
+            get(responses_lookup::api_v1_responses_get)
+                .delete(responses_lookup::api_v1_responses_delete),
+        )
+        .route(
+            "/v1/responses/{response_id}/cancel",
+            post(responses_lookup::api_v1_responses_cancel),
+        )
+        .route(
+            "/v1/containers",
+            post(containers::api_v1_containers_create).get(containers::api_v1_containers_list),
+        )
+        .route(
+            "/v1/containers/{container_id}",
+            get(containers::api_v1_containers_get).delete(containers::api_v1_containers_delete),
+        )
+        .route(
+            "/v1/containers/{container_id}/files",
+            get(containers::api_v1_containers_list_files)
+                .post(containers::api_v1_containers_file_upload),
+        )
+        .route(
+            "/v1/containers/{container_id}/files/{file_id}",
+            get(containers::api_v1_containers_file_get)
+                .delete(containers::api_v1_containers_file_delete),
+        )
+        .route(
+            "/v1/containers/{container_id}/files/{file_id}/content",
+            get(containers::api_v1_containers_file_content),
+        )
         .route("/v1/images/edits", post(api_v1_images_edits))
         .route("/v1/images/variations", post(api_v1_images_variations));
     let router = router
diff --git a/src/routes/api/responses_lookup.rs b/src/routes/api/responses_lookup.rs
new file mode 100644
index 0000000..a394c9a
--- /dev/null
+++ b/src/routes/api/responses_lookup.rs
@@ -0,0 +1,609 @@
+//! `GET`/`POST cancel`/`DELETE` handlers for stored Responses API
+//! records, matching OpenAI's Responses API spec.
+//!
+//! Persistence happens during `POST /v1/responses` (see chat.rs); these
+//! endpoints surface the resulting rows.
+
+#![cfg(feature = "server")]
+
+use axum::{
+    Extension, Json,
+    body::Body,
+    extract::{Path, Query, State},
+    http::{StatusCode, header},
+    response::IntoResponse,
+};
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+use uuid::Uuid;
+
+use super::ApiError;
+use crate::{
+    AppState,
+    auth::AuthenticatedRequest,
+    db::repos::ResponseRecord,
+    middleware::AuthzContext,
+    services::{ResponsesStore, ResponsesStoreError},
+};
+
+/// Wire-format response shape. Wraps the stored JSON output and stamps
+/// gateway-controlled fields (id, status, created_at). All other
+/// fields come from the persisted request_payload / output / usage so
+/// the surface matches OpenAI's spec.
+#[derive(Serialize)]
+pub struct WireResponse {
+    id: String,
+    object: &'static str,
+    status: &'static str,
+    background: bool,
+    model: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    provider: Option<String>,
+    /// **Hadrian Extension:** ownership scope of the response —
+    /// `organization`, `team`, `project`, `user`, or `service_account`.
+    /// Mirrors the pattern used by skills, templates, and conversations.
+    owner: WireOwner,
+    /// Unix timestamp in seconds, matching OpenAI's integer encoding.
+    created_at: i64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    completed_at: Option<i64>,
+    #[serde(skip_serializing_if = "Value::is_null")]
+    output: Value,
+    #[serde(skip_serializing_if = "Value::is_null")]
+    usage: Value,
+    #[serde(skip_serializing_if = "Value::is_null")]
+    error: Value,
+    /// Container the shell-tool session for this response was attached
+    /// to. Surfaced so callers can chain via
+    /// `environment.type = "container_reference"` without scraping
+    /// output items. `null` when the request had no shell tool, when
+    /// container persistence is disabled, or before the shell tool
+    /// first runs.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    container_id: Option<String>,
+    /// Echo selected request-payload fields so the response carries the
+    /// instructions, tools, etc. that originally drove it — same as
+    /// OpenAI's Retrieve endpoint.
+    #[serde(flatten)]
+    echoed: Map<String, Value>,
+}
+
+#[derive(Serialize)]
+pub struct WireOwner {
+    #[serde(rename = "type")]
+    type_: &'static str,
+    id: String,
+}
+
+fn record_to_wire(record: &ResponseRecord) -> WireResponse {
+    // Pull selected request fields back into the top-level shape so
+    // clients can introspect what they sent. Sensitive values are kept
+    // out of the echo: MCP credentials are scrubbed before storage, and
+    // inline shell `domain_secrets[].value` (which background rows must
+    // retain to execute) is redacted here on the way out.
+    const ECHO_FIELDS: &[&str] = &[
+        "input",
+        "instructions",
+        "metadata",
+        "tools",
+        "tool_choice",
+        "parallel_tool_calls",
+        "temperature",
+        "top_p",
+        "max_output_tokens",
+        "reasoning",
+        "text",
+        "include",
+        "store",
+        "previous_response_id",
+    ];
+    let mut echoed = Map::new();
+    if let Value::Object(obj) = &record.request_payload {
+        for k in ECHO_FIELDS {
+            if let Some(v) = obj.get(*k) {
+                let mut cloned = v.clone();
+                // Background rows keep the raw inline domain-secret value
+                // in `request_payload` so the worker can execute the
+                // shell tool, but the value must never be echoed back to
+                // a client — mirroring how MCP `authorization` is
+                // scrubbed before storage.
+                if *k == "tools" {
+                    redact_inline_domain_secrets(&mut cloned);
+                }
+                echoed.insert((*k).to_string(), cloned);
+            }
+        }
+    }
+    WireResponse {
+        id: record.id.clone(),
+        object: "response",
+        status: record.status.as_str(),
+        background: record.background,
+        model: record.model.clone(),
+        provider: record.provider.clone(),
+        owner: WireOwner {
+            type_: record.owner_type.as_str(),
+            id: record.owner_id.to_string(),
+        },
+        created_at: record.created_at.timestamp(),
+        completed_at: record.completed_at.map(|t| t.timestamp()),
+        output: record.output.clone().unwrap_or(Value::Null),
+        usage: record.usage.clone().unwrap_or(Value::Null),
+        error: record.error.clone().unwrap_or(Value::Null),
+        container_id: record.container_id.clone(),
+        echoed,
+    }
+}
+
+/// Walk a serialized `tools` array, redacting every inline
+/// `domain_secrets[].value` (the OpenAI `{domain, name, value}` form
+/// that carries a raw secret on the wire). The reference form
+/// (`{placeholder, allowed_domains}`) holds no secret and is left
+/// intact.
+fn redact_inline_domain_secrets(value: &mut Value) {
+    match value {
+        Value::Object(map) => {
+            if let Some(Value::Array(secrets)) = map.get_mut("domain_secrets") {
+                for secret in secrets.iter_mut() {
+                    if let Value::Object(entry) = secret
+                        && let Some(Value::String(s)) = entry.get_mut("value")
+                    {
+                        *s = format!("_omitted_{}_bytes", s.len());
+                    }
+                }
+            }
+            for (_, v) in map.iter_mut() {
+                redact_inline_domain_secrets(v);
+            }
+        }
+        Value::Array(items) => {
+            for v in items.iter_mut() {
+                redact_inline_domain_secrets(v);
+            }
+        }
+        _ => {}
+    }
+}
+
+fn resolve_store(state: &AppState) -> Result<&ResponsesStore, ApiError> {
+    state.responses_store.as_deref().ok_or_else(|| {
+        ApiError::new(
+            StatusCode::NOT_IMPLEMENTED,
+            "responses_persistence_disabled",
+            "Response persistence requires a configured database".to_string(),
+        )
+    })
+}
+
+/// Resolve the caller's org, falling back to the deployment `default_org_id`
+/// (no-auth / anonymous dev mode) so response lookups work locally without
+/// credentials — same fallback the responses pipeline uses for usage.
+fn require_caller_org(
+    auth: Option<&Extension<AuthenticatedRequest>>,
+    default_org: Option<Uuid>,
+) -> Result<Uuid, ApiError> {
+    auth.and_then(|Extension(a)| {
+        a.api_key()
+            .and_then(|k| k.org_id)
+            .or_else(|| a.principal().org_id())
+    })
+    .or(default_org)
+    .ok_or_else(|| {
+        ApiError::new(
+            StatusCode::UNAUTHORIZED,
+            "authentication_required",
+            "An authenticated org is required",
+        )
+    })
+}
+
+/// Run `authz.require_api("response", action, ...)` when authz is
+/// configured. Mirrors the gate `api_v1_responses` applies for
+/// `("model", "use")`, so RBAC policies that allow create-but-deny-
+/// retrieve (or vice versa) can express that.
+async fn enforce_authz(
+    authz: Option<&Extension<AuthzContext>>,
+    auth: Option<&Extension<AuthenticatedRequest>>,
+    action: &str,
+) -> Result<(), ApiError> {
+    let Some(Extension(authz)) = authz else {
+        return Ok(());
+    };
+    let org_id = auth.and_then(|a| {
+        a.api_key()
+            .and_then(|k| k.org_id.map(|id| id.to_string()))
+            .or_else(|| a.identity().and_then(|i| i.org_ids.first().cloned()))
+    });
+    let project_id = auth.and_then(|a| {
+        a.api_key()
+            .and_then(|k| k.project_id.map(|id| id.to_string()))
+            .or_else(|| a.identity().and_then(|i| i.project_ids.first().cloned()))
+    });
+    authz
+        .require_api(
+            "response",
+            action,
+            None,
+            None,
+            org_id.as_deref(),
+            project_id.as_deref(),
+        )
+        .await
+        .map_err(|e| ApiError::new(StatusCode::FORBIDDEN, "authorization_denied", e.to_string()))
+}
+
+/// Convert a [`ResponsesStoreError`] into an `ApiError`, logging
+/// internal details server-side and returning a safe shape to the
+/// caller. Mirrors the canonical `impl From<DbError> for ApiError` in
+/// `src/routes/api/mod.rs` — internal-only errors get a generic
+/// message; expected-shape errors get specific codes.
+fn map_store_err(e: ResponsesStoreError) -> ApiError {
+    match e {
+        ResponsesStoreError::NotFound => ApiError::new(
+            StatusCode::NOT_FOUND,
+            "response_not_found",
+            "No such response",
+        ),
+        ResponsesStoreError::NotBackground => ApiError::new(
+            StatusCode::BAD_REQUEST,
+            "response_not_background",
+            "Only responses created with background=true can be cancelled",
+        ),
+        ResponsesStoreError::Database(db_err) => {
+            // Delegate to the canonical From<DbError> impl so known
+            // variants (NotFound / Conflict / Validation) map to the
+            // same codes everywhere, and unknown ones get logged but
+            // surface a generic message.
+            ApiError::from(db_err)
+        }
+        ResponsesStoreError::Internal(msg) => {
+            tracing::error!(error = %msg, "Responses store internal error");
+            ApiError::new(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "internal_error",
+                "An internal error occurred",
+            )
+        }
+    }
+}
+
+/// Query parameters for `GET /v1/responses/{id}`. Mirrors OpenAI's
+/// retrieve-response spec: `stream` flips to SSE mode, `starting_after`
+/// resumes replay from a sequence number, and `include` widens the
+/// response shape.
+#[derive(Debug, Default, Deserialize)]
+pub struct RetrieveQuery {
+    /// When `true`, the response is streamed as Server-Sent Events
+    /// replaying the persisted event log instead of returning a static
+    /// JSON object. Matches OpenAI's `stream` field on the retrieve
+    /// endpoint so SDK clients can resume a dropped subscription.
+    #[serde(default)]
+    pub stream: Option<bool>,
+    /// Return events with `sequence_number > starting_after`. Clients
+    /// pass the highest sequence number they've already seen so a
+    /// reconnect resumes without duplicates. Only meaningful with
+    /// `stream=true`.
+    #[serde(default)]
+    pub starting_after: Option<i64>,
+    /// Pass-through of OpenAI's `include` widening field. Currently
+    /// ignored — the persisted shape already returns echoed fields.
+    /// Accepted so SDK calls don't 400 on the extra param.
+    #[serde(default)]
+    pub include: Option<Vec<String>>,
+    /// Pass-through of OpenAI's `include_obfuscation` field. Accepted
+    /// for parity but Hadrian doesn't add padding bytes today.
+    #[serde(default)]
+    pub include_obfuscation: Option<bool>,
+}
+
+/// `GET /v1/responses/{response_id}` — retrieve a stored response.
+///
+/// When `?stream=true` is set, returns the persisted event log as an
+/// SSE stream (matching OpenAI's retrieve-with-stream behavior). The
+/// `starting_after` query parameter resumes replay from a specific
+/// sequence number so a client reconnecting after a disconnect picks
+/// up exactly where it stopped.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    get,
+    path = "/api/v1/responses/{response_id}",
+    tag = "responses",
+    params(
+        ("response_id" = String, Path, description = "ID returned by POST /v1/responses"),
+        ("stream" = Option<bool>, Query, description = "Stream the event log as SSE"),
+        ("starting_after" = Option<i64>, Query, description = "Resume cursor (stream mode)"),
+    ),
+    responses(
+        (status = 200, description = "Stored response (JSON) or SSE replay when stream=true"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "Response not found", body = crate::openapi::ErrorResponse),
+        (status = 501, description = "Persistence disabled", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_responses_get(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path(response_id): Path<String>,
+    Query(query): Query<RetrieveQuery>,
+) -> Result<axum::response::Response, ApiError> {
+    let store = resolve_store(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "read").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+
+    if query.stream.unwrap_or(false) {
+        return stream_response_events(state.clone(), response_id, org_id, query.starting_after)
+            .await;
+    }
+
+    let record = store
+        .get(&response_id, org_id)
+        .await
+        .map_err(map_store_err)?;
+    Ok(Json(record_to_wire(&record)).into_response())
+}
+
+/// `POST /v1/responses/{response_id}/cancel` — cancel an in-progress
+/// background response. Per OpenAI's spec, returns 400 if the response
+/// is not in background mode. Idempotent for already-terminal rows.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    post,
+    path = "/api/v1/responses/{response_id}/cancel",
+    tag = "responses",
+    params(("response_id" = String, Path, description = "ID of the response to cancel")),
+    responses(
+        (status = 200, description = "The cancelled response object"),
+        (status = 400, description = "Response is not in background mode", body = crate::openapi::ErrorResponse),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+        (status = 404, description = "Response not found", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_responses_cancel(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path(response_id): Path<String>,
+) -> Result<Json<WireResponse>, ApiError> {
+    let store = resolve_store(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "cancel").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+    let record = store
+        .cancel(&response_id, org_id)
+        .await
+        .map_err(map_store_err)?;
+    Ok(Json(record_to_wire(&record)))
+}
+
+#[derive(Serialize)]
+pub struct DeleteResponse {
+    pub id: String,
+    pub object: &'static str,
+    pub deleted: bool,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Event log replay
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Stream the persisted event log as Server-Sent Events. While the
+/// response is still in-progress the handler polls the DB every
+/// 250ms for new rows; once the row reaches a terminal status and the
+/// caller has caught up to `last_sequence_number`, the stream
+/// terminates with a `data: [DONE]` sentinel.
+///
+/// Each event is emitted with the OpenAI-style named SSE form
+/// (`event: <type>\ndata: <payload>\n\n`) so JS SDK callers see the
+/// typed events they expect.
+///
+/// Used by both `GET /v1/responses/{id}?stream=true` (the
+/// spec-conformant entry point) and any clients that supply the cursor
+/// query parameter.
+/// Fixed page size for SSE replay batches. Kept internal so the
+/// wire protocol doesn't expose a knob clients would need to tune.
+const REPLAY_PAGE_SIZE: i64 = 200;
+
+async fn stream_response_events(
+    state: AppState,
+    response_id: String,
+    org_id: Uuid,
+    starting_after: Option<i64>,
+) -> Result<axum::response::Response, ApiError> {
+    use bytes::Bytes;
+    use http::Response as HttpResponse;
+
+    let store = resolve_store(&state)?;
+    let Some(db) = state.db.as_ref().cloned() else {
+        return Err(ApiError::new(
+            StatusCode::NOT_IMPLEMENTED,
+            "responses_persistence_disabled",
+            "Response persistence requires a configured database".to_string(),
+        ));
+    };
+
+    // Verify the response exists and belongs to the caller's org.
+    let _record = store
+        .get(&response_id, org_id)
+        .await
+        .map_err(map_store_err)?;
+
+    let starting_after = starting_after.unwrap_or(0).max(0);
+    let limit = REPLAY_PAGE_SIZE;
+    let store_clone = state.responses_store.as_ref().cloned();
+    let events_repo = db.response_events();
+    let response_id_clone = response_id.clone();
+    let org_id_for_task = org_id;
+
+    let (tx, rx) = tokio::sync::mpsc::channel::<Result<Bytes, std::io::Error>>(8);
+
+    crate::compat::spawn_detached(async move {
+        const TERMINAL_EVENT_TYPES: &[&str] = &[
+            "response.completed",
+            "response.failed",
+            "response.cancelled",
+            "response.incomplete",
+        ];
+        let mut cursor = starting_after;
+        loop {
+            // Drain everything past the cursor.
+            let events = match events_repo
+                .list_after(&response_id_clone, cursor, limit)
+                .await
+            {
+                Ok(e) => e,
+                Err(e) => {
+                    tracing::error!(
+                        response_id = %response_id_clone,
+                        error = %e,
+                        "Failed to list response events for SSE replay"
+                    );
+                    // Don't leak DB internals to the caller — terminate
+                    // the stream cleanly. They can reconnect and we'll
+                    // retry.
+                    let _ = tx
+                        .send(Err(std::io::Error::other("event log read failed")))
+                        .await;
+                    return;
+                }
+            };
+
+            let batch_max = events.last().map(|e| e.sequence_number);
+            // Event log is the truth source: if any event in this
+            // batch is a terminal type, we know nothing else is coming
+            // and we can [DONE] right after emitting. This sidesteps
+            // the race where row.status updates before
+            // last_sequence_number does (the persister commits
+            // terminal events via `insert_sync` to make this happen).
+            let mut saw_terminal_event = false;
+            for ev in events {
+                let payload_str = match serde_json::to_string(&ev.payload) {
+                    Ok(s) => s,
+                    Err(e) => {
+                        tracing::warn!(
+                            response_id = %response_id_clone,
+                            seq = ev.sequence_number,
+                            error = %e,
+                            "Skipping unserialisable response event"
+                        );
+                        continue;
+                    }
+                };
+                if TERMINAL_EVENT_TYPES.contains(&ev.event_type.as_str()) {
+                    saw_terminal_event = true;
+                }
+                // Named-SSE-event form matches OpenAI's Responses API
+                // wire format: `event: <type>\ndata: <payload>\n\n`.
+                let sse = format!("event: {}\ndata: {}\n\n", ev.event_type, payload_str);
+                if tx.send(Ok(Bytes::from(sse))).await.is_err() {
+                    return; // client disconnected
+                }
+            }
+
+            if let Some(seq) = batch_max {
+                cursor = seq;
+            }
+
+            if saw_terminal_event {
+                let _ = tx.send(Ok(Bytes::from_static(b"data: [DONE]\n\n"))).await;
+                return;
+            }
+
+            // No terminal event yet. Fall back to the row's status for
+            // responses that never generated any events (non-streaming
+            // requests persisted via `persist_non_streaming`): those
+            // reach terminal status without writing to the event log,
+            // so without this we'd loop forever.
+            let Some(ref store) = store_clone else { return };
+            let record = match store.get(&response_id_clone, org_id_for_task).await {
+                Ok(r) => r,
+                Err(_) => return,
+            };
+            if record.status.is_terminal() && record.last_sequence_number == 0 {
+                let _ = tx.send(Ok(Bytes::from_static(b"data: [DONE]\n\n"))).await;
+                return;
+            }
+
+            // In-progress — poll again shortly.
+            tokio::time::sleep(std::time::Duration::from_millis(250)).await;
+        }
+    });
+
+    let stream = futures_util::stream::unfold(rx, |mut rx| async move {
+        rx.recv().await.map(|item| (item, rx))
+    });
+    Ok(HttpResponse::builder()
+        .status(StatusCode::OK)
+        .header(header::CONTENT_TYPE, "text/event-stream")
+        .header(header::CACHE_CONTROL, "no-cache")
+        .body(Body::from_stream(stream))
+        .unwrap())
+}
+
+/// `DELETE /v1/responses/{response_id}` — remove a stored response.
+/// Returns the OpenAI-spec deletion confirmation shape.
+#[cfg_attr(feature = "utoipa", utoipa::path(
+    delete,
+    path = "/api/v1/responses/{response_id}",
+    tag = "responses",
+    params(("response_id" = String, Path, description = "ID of the response to delete")),
+    responses(
+        (status = 200, description = "Deletion confirmation"),
+        (status = 401, description = "Authentication required", body = crate::openapi::ErrorResponse),
+        (status = 403, description = "Authorization denied", body = crate::openapi::ErrorResponse),
+    ),
+    security(("api_key" = []))
+))]
+pub async fn api_v1_responses_delete(
+    State(state): State<AppState>,
+    auth: Option<Extension<AuthenticatedRequest>>,
+    authz: Option<Extension<AuthzContext>>,
+    Path(response_id): Path<String>,
+) -> Result<Json<DeleteResponse>, ApiError> {
+    let store = resolve_store(&state)?;
+    enforce_authz(authz.as_ref(), auth.as_ref(), "delete").await?;
+    let org_id = require_caller_org(auth.as_ref(), state.default_org_id)?;
+    let deleted = store
+        .delete(&response_id, org_id)
+        .await
+        .map_err(map_store_err)?;
+    Ok(Json(DeleteResponse {
+        id: response_id,
+        object: "response.deleted",
+        deleted,
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn redacts_inline_domain_secret_values_but_keeps_references() {
+        let mut tools = json!([
+            {
+                "type": "shell",
+                "network_policy": {
+                    "type": "allowlist",
+                    "allowed_domains": ["api.example.com"],
+                    "domain_secrets": [
+                        {"domain": "api.example.com", "name": "API_KEY", "value": "sk-supersecret"},
+                        {"placeholder": "shared_token", "allowed_domains": ["api.example.com"]}
+                    ]
+                }
+            }
+        ]);
+        redact_inline_domain_secrets(&mut tools);
+
+        let secrets = &tools[0]["network_policy"]["domain_secrets"];
+        // Inline value is redacted to a length marker, never the raw value.
+        assert_eq!(secrets[0]["value"], json!("_omitted_14_bytes"));
+        // Non-secret fields and the reference form are untouched.
+        assert_eq!(secrets[0]["name"], json!("API_KEY"));
+        assert_eq!(secrets[1]["placeholder"], json!("shared_token"));
+        assert!(secrets[1].get("value").is_none());
+    }
+}
diff --git a/src/routes/api/tools.rs b/src/routes/api/tools.rs
index 063d299..b883513 100644
--- a/src/routes/api/tools.rs
+++ b/src/routes/api/tools.rs
@@ -347,6 +347,8 @@ pub async fn web_search(
             tool_url: None,
             tool_bytes_fetched: None,
             tool_results_count: Some(results_count),
+            tool_runtime_seconds: None,
+            tool_exit_code: None,
         });
     }
 
@@ -638,6 +640,8 @@ pub async fn web_fetch(
             tool_url: Some(payload.url.clone()),
             tool_bytes_fetched: Some(bytes_fetched),
             tool_results_count: None,
+            tool_runtime_seconds: None,
+            tool_exit_code: None,
         });
     }
 
diff --git a/src/routes/execution.rs b/src/routes/execution.rs
index 95b2626..e32b0ba 100644
--- a/src/routes/execution.rs
+++ b/src/routes/execution.rs
@@ -13,6 +13,14 @@ use crate::providers::azure_openai;
 use crate::providers::bedrock;
 #[cfg(feature = "provider-vertex")]
 use crate::providers::vertex;
+#[cfg(feature = "server")]
+use crate::services::{
+    container_session::MNT_DATA,
+    shell_tool::{
+        ShellExecutionLocation, ShellNetworkSummary, ShellToolHint, preprocess_shell_tools,
+        resolve_shell_environment,
+    },
+};
 use crate::{
     AppState, api_types,
     config::{ProviderConfig, SovereigntyMetadata, SovereigntyRequirements},
@@ -24,6 +32,74 @@ use crate::{
     services::{preprocess_file_search_tools, preprocess_web_search_tools},
 };
 
+/// Whether OpenAI's native `shell` tool spec should be left intact
+/// (vs rewritten to a function tool). True in both passthrough modes —
+/// `passthrough_openai` (OpenAI's hosted container executes) and
+/// `client_passthrough` (the API client executes). In both cases the
+/// model should emit native `shell_call` items the OpenAI SDK can
+/// recognize; Hadrian-hosted runtimes always rewrite so the executor
+/// can intercept function-call output.
+fn keep_openai_native_shell(state: &AppState) -> bool {
+    state.config.features.shell.keeps_openai_native_shell()
+}
+
+/// Build the description hint the model sees on the function-mode shell
+/// tool. Drawn from the runtime mode, per-request shell environment
+/// overrides intersected with operator caps, and the containers config.
+///
+/// Re-resolves the per-request env even though `chat.rs` already did so
+/// at admission time — preprocessing happens deep in the per-provider
+/// dispatch and re-derivation is cheap. Errors fall back to defaults
+/// silently because the request would have been rejected with a 400 at
+/// admission if the env was actually invalid.
+#[cfg(feature = "server")]
+fn build_shell_tool_hint(
+    state: &AppState,
+    payload: &api_types::CreateResponsesPayload,
+) -> ShellToolHint {
+    let location = match state.config.features.shell {
+        crate::config::ShellRuntimeConfig::ClientPassthrough => ShellExecutionLocation::ApiClient,
+        _ => ShellExecutionLocation::HadrianSandbox,
+    };
+
+    let containers = &state.config.features.containers;
+    let shell_limits = &state.config.features.server_tools.shell_limits;
+
+    let request_env = payload
+        .tools
+        .as_ref()
+        .and_then(|tools| tools.iter().find_map(|t| t.as_shell()))
+        .and_then(|s| s.environment.as_ref());
+    let resolved =
+        resolve_shell_environment(request_env, shell_limits, &state.config.features.containers)
+            .ok();
+
+    let mem_limit_mb = resolved
+        .as_ref()
+        .and_then(|r| r.mem_limit_bytes)
+        .map(|b| b / (1024 * 1024))
+        .or_else(|| shell_limits.default_mem_limit_mb.map(u64::from));
+
+    let network_summary = match resolved.as_ref() {
+        Some(r) if !r.egress_policy.allow_hosts.is_empty() => {
+            ShellNetworkSummary::Allowlist(r.egress_policy.allow_hosts.clone())
+        }
+        _ => ShellNetworkSummary::Unknown,
+    };
+
+    ShellToolHint {
+        location,
+        workdir: MNT_DATA,
+        container_persistence: containers.enabled
+            && matches!(location, ShellExecutionLocation::HadrianSandbox),
+        network_summary,
+        mem_limit_mb,
+        command_timeout_secs: shell_limits.command_timeout_secs,
+        environment_description: shell_limits.environment_description.clone(),
+        ..ShellToolHint::default()
+    }
+}
+
 // ============================================================================
 // Unified Execution Result
 // ============================================================================
@@ -122,6 +198,20 @@ impl ApiPayload for api_types::CreateEmbeddingPayload {
     // Embeddings don't support streaming, so we use the default (false)
 }
 
+impl ApiPayload for api_types::CompactRequest {
+    fn model(&self) -> Option<&str> {
+        Some(&self.model)
+    }
+
+    fn set_model(&mut self, model: String) {
+        self.model = model;
+    }
+
+    fn is_streaming(&self) -> bool {
+        self.stream
+    }
+}
+
 // ============================================================================
 // Provider Executor Trait
 // ============================================================================
@@ -256,14 +346,70 @@ impl ProviderExecutor for ResponsesExecutor {
         state: &AppState,
         provider_name: &str,
         provider_config: &ProviderConfig,
-        payload: Self::Payload,
+        #[cfg_attr(not(feature = "mcp"), allow(unused_mut))] mut payload: Self::Payload,
     ) -> Result<Response, ProviderError> {
+        // Shell tool preprocessing rules:
+        // - OpenAI / Azure OpenAI: leave native `shell` tool intact when
+        //   either passthrough mode is configured (so the model emits
+        //   native `shell_call` items the OpenAI SDK / hosted container
+        //   can consume); otherwise rewrite to function tool so the
+        //   Hadrian-hosted executor can intercept.
+        // - Anthropic / Bedrock / Vertex: always rewrite, since these
+        //   providers have no native shell tool. Under `client_passthrough`
+        //   the rewrite still happens; the model emits `function_call`
+        //   items with `name="shell"` that pass through to the client.
+        let openai_keep_native_shell = keep_openai_native_shell(state);
+        // Build the hint once per provider attempt; rewrites are idempotent
+        // and the hint depends only on request payload + operator config.
+        #[cfg(feature = "server")]
+        let shell_hint = build_shell_tool_hint(state, &payload);
+
+        // MCP `hadrian_hosted` rewrite — uniformly across providers. The
+        // executor in `services::mcp` will intercept the resulting
+        // function calls; under `passthrough_openai` this is a no-op
+        // and we forward `mcp` verbatim to OpenAI/Azure. Approval
+        // resumption (turning `mcp_approval_response` items into
+        // `function_call_output`s) runs in `routes/api/chat.rs`
+        // BEFORE this point, since that's where the resolved
+        // principal (and thus `org_id`) is in scope.
+        #[cfg(feature = "mcp")]
+        {
+            use crate::config::McpMode;
+            if let (Some(mcp_cfg), Some(mcp_service)) = (
+                state.config.features.mcp.as_ref(),
+                state.mcp_service.as_ref(),
+            ) && mcp_cfg.enabled
+                && mcp_cfg.mode == McpMode::HadrianHosted
+            {
+                let mcp_provider_kind =
+                    crate::services::mcp_tool::McpProviderKind::from_provider(provider_config);
+                crate::services::mcp::rewrite_mcp_tools(
+                    &mut payload,
+                    mcp_service,
+                    mcp_provider_kind,
+                )
+                .await
+                .map_err(|e| {
+                    let code = e.code();
+                    let msg = e.to_string();
+                    if e.is_client_error() {
+                        ProviderError::BadRequest(code, msg)
+                    } else {
+                        ProviderError::BadGateway(code, msg)
+                    }
+                })?;
+            }
+        }
+
         match provider_config {
             ProviderConfig::OpenAi(config) => {
-                // Preprocess built-in tools to function tools for OpenAI-compatible providers
                 let mut payload = payload;
                 preprocess_file_search_tools(&mut payload);
                 preprocess_web_search_tools(&mut payload);
+                #[cfg(feature = "server")]
+                if !openai_keep_native_shell {
+                    preprocess_shell_tools(&mut payload, &shell_hint);
+                }
 
                 open_ai::OpenAICompatibleProvider::from_config_with_registry(
                     config,
@@ -274,9 +420,10 @@ impl ProviderExecutor for ResponsesExecutor {
                 .await
             }
             ProviderConfig::Anthropic(config) => {
-                // Preprocess web_search tools (Anthropic handles file_search in its own convert)
                 let mut payload = payload;
                 preprocess_web_search_tools(&mut payload);
+                #[cfg(feature = "server")]
+                preprocess_shell_tools(&mut payload, &shell_hint);
                 anthropic::AnthropicProvider::from_config_with_registry(
                     config,
                     provider_name,
@@ -287,10 +434,13 @@ impl ProviderExecutor for ResponsesExecutor {
             }
             #[cfg(feature = "provider-azure")]
             ProviderConfig::AzureOpenAi(config) => {
-                // Preprocess built-in tools to function tools for Azure OpenAI
                 let mut payload = payload;
                 preprocess_file_search_tools(&mut payload);
                 preprocess_web_search_tools(&mut payload);
+                #[cfg(feature = "server")]
+                if !openai_keep_native_shell {
+                    preprocess_shell_tools(&mut payload, &shell_hint);
+                }
 
                 azure_openai::AzureOpenAIProvider::from_config_with_registry(
                     config,
@@ -302,10 +452,11 @@ impl ProviderExecutor for ResponsesExecutor {
             }
             #[cfg(feature = "provider-bedrock")]
             ProviderConfig::Bedrock(config) => {
-                // Preprocess built-in tools to function tools for Bedrock
                 let mut payload = payload;
                 preprocess_file_search_tools(&mut payload);
                 preprocess_web_search_tools(&mut payload);
+                #[cfg(feature = "server")]
+                preprocess_shell_tools(&mut payload, &shell_hint);
 
                 bedrock::BedrockProvider::from_config_with_registry(
                     config,
@@ -317,9 +468,10 @@ impl ProviderExecutor for ResponsesExecutor {
             }
             #[cfg(feature = "provider-vertex")]
             ProviderConfig::Vertex(config) => {
-                // Preprocess web_search tools (Vertex handles file_search in its own convert)
                 let mut payload = payload;
                 preprocess_web_search_tools(&mut payload);
+                #[cfg(feature = "server")]
+                preprocess_shell_tools(&mut payload, &shell_hint);
                 vertex::VertexProvider::from_config_with_registry(
                     config,
                     provider_name,
@@ -329,10 +481,11 @@ impl ProviderExecutor for ResponsesExecutor {
                 .await
             }
             ProviderConfig::Test(config) => {
-                // Preprocess built-in tools for test provider
                 let mut payload = payload;
                 preprocess_file_search_tools(&mut payload);
                 preprocess_web_search_tools(&mut payload);
+                #[cfg(feature = "server")]
+                preprocess_shell_tools(&mut payload, &shell_hint);
 
                 test::TestProvider::from_config(config)
                     .create_responses(&state.http_client, payload)
@@ -346,6 +499,69 @@ impl ProviderExecutor for ResponsesExecutor {
     }
 }
 
+/// Marker type for the standalone `/v1/responses/compact` endpoint.
+///
+/// Forwards to providers that implement
+/// [`Provider::create_responses_compact`]. Non-OpenAI providers return
+/// `Unsupported` from the trait default, which surfaces as HTTP 501
+/// to the caller with `error_code = "not_supported"`.
+pub struct CompactExecutor;
+
+impl ProviderExecutor for CompactExecutor {
+    type Payload = api_types::CompactRequest;
+
+    async fn execute(
+        state: &AppState,
+        provider_name: &str,
+        provider_config: &ProviderConfig,
+        payload: Self::Payload,
+    ) -> Result<Response, ProviderError> {
+        match provider_config {
+            ProviderConfig::OpenAi(config) => {
+                open_ai::OpenAICompatibleProvider::from_config_with_registry(
+                    config,
+                    provider_name,
+                    &state.circuit_breakers,
+                )
+                .create_responses_compact(&state.http_client, payload)
+                .await
+            }
+            #[cfg(feature = "provider-azure")]
+            ProviderConfig::AzureOpenAi(config) => {
+                azure_openai::AzureOpenAIProvider::from_config_with_registry(
+                    config,
+                    provider_name,
+                    &state.circuit_breakers,
+                )
+                .create_responses_compact(&state.http_client, payload)
+                .await
+            }
+            // Every other provider falls through to the trait default
+            // (Unsupported → 501). Listing them explicitly keeps the
+            // match exhaustive so adding a future provider forces a
+            // conscious choice here.
+            ProviderConfig::Anthropic(_) => Err(ProviderError::Unsupported(
+                "compaction is only supported by OpenAI-compatible providers".to_string(),
+            )),
+            #[cfg(feature = "provider-bedrock")]
+            ProviderConfig::Bedrock(_) => Err(ProviderError::Unsupported(
+                "compaction is only supported by OpenAI-compatible providers".to_string(),
+            )),
+            #[cfg(feature = "provider-vertex")]
+            ProviderConfig::Vertex(_) => Err(ProviderError::Unsupported(
+                "compaction is only supported by OpenAI-compatible providers".to_string(),
+            )),
+            ProviderConfig::Test(_) => Err(ProviderError::Unsupported(
+                "compaction is only supported by OpenAI-compatible providers".to_string(),
+            )),
+        }
+    }
+
+    fn operation_name() -> &'static str {
+        "responses_compact"
+    }
+}
+
 /// Marker type for completion (legacy) operations.
 pub struct CompletionExecutor;
 
@@ -852,6 +1068,15 @@ pub fn provider_error_to_api_error(e: ProviderError) -> ApiError {
             "internal_error",
             "Internal provider error".to_string(),
         ),
+        ProviderError::Unsupported(msg) => {
+            (StatusCode::NOT_IMPLEMENTED, "not_supported", msg.clone())
+        }
+        ProviderError::BadGateway(error_code, msg) => {
+            (StatusCode::BAD_GATEWAY, *error_code, msg.clone())
+        }
+        ProviderError::BadRequest(error_code, msg) => {
+            (StatusCode::BAD_REQUEST, *error_code, msg.clone())
+        }
         ProviderError::CircuitBreakerOpen(cb) => (
             StatusCode::SERVICE_UNAVAILABLE,
             "circuit_breaker_open",
@@ -913,6 +1138,17 @@ mod tests {
             output_guardrails: None,
             event_bus: Arc::new(EventBus::new()),
             file_search_service: None,
+            shell_runtime: None,
+            #[cfg(feature = "mcp")]
+            mcp_service: None,
+            #[cfg(feature = "mcp")]
+            tool_search_embeddings: None,
+            responses_store: None,
+            containers_service: None,
+            container_session_registry: std::sync::Arc::new(
+                crate::services::container_session::ContainerSessionRegistry::new(),
+            ),
+            response_event_buffer: None,
             #[cfg(any(
                 feature = "document-extraction-basic",
                 feature = "document-extraction-full"
diff --git a/src/runtimes/microsandbox.rs b/src/runtimes/microsandbox.rs
new file mode 100644
index 0000000..ef7fac8
--- /dev/null
+++ b/src/runtimes/microsandbox.rs
@@ -0,0 +1,601 @@
+//! Microsandbox runtime adapter.
+//!
+//! Wraps the [`microsandbox`] SDK so each Hadrian session corresponds to
+//! one local microVM. Microsandbox runs in-process (no daemon, no
+//! endpoint) — booting a VM, streaming command I/O, and tearing it down
+//! all happen via direct Rust calls.
+
+#![cfg(feature = "runtime-microsandbox")]
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use bytes::Bytes;
+use futures_util::stream::Stream;
+use microsandbox::{ExecEvent as MsExecEvent, NetworkPolicy, Sandbox};
+use tokio::sync::{Mutex, mpsc};
+use tracing::{debug, error, info, warn};
+use uuid::Uuid;
+
+use crate::{
+    config::MicrosandboxConfig,
+    runtimes::{
+        ExecEvent, ExecHandle, ExecRequest, NetworkMode, RuntimeCapabilities, RuntimeError,
+        RuntimeResult, SessionHandle, SessionSpec, ShellRuntime, ShellSession,
+    },
+};
+
+/// `ShellRuntime` implementation backed by microsandbox microVMs.
+///
+/// Each `start_session` boots a fresh VM — the previous pre-warm pool
+/// was removed because pooled VMs were reused across tenants without a
+/// filesystem reset, opening a cross-tenant data leak window for any
+/// session whose `SessionSpec` didn't force a fresh VM. Cold-start
+/// cost is paid per request; revisit pooling later only if we add
+/// per-tenant keying or snapshot-restore.
+pub struct MicrosandboxRuntime {
+    config: MicrosandboxConfig,
+}
+
+impl MicrosandboxRuntime {
+    pub fn new(config: MicrosandboxConfig) -> Self {
+        Self { config }
+    }
+}
+
+fn cpus_for_sdk(cpus: u32) -> u8 {
+    // SDK takes u8 (0..=255). Anything beyond 255 vCPUs is operator
+    // error; clamp rather than silently wrapping.
+    cpus.min(u8::MAX as u32) as u8
+}
+
+#[async_trait]
+impl ShellRuntime for MicrosandboxRuntime {
+    fn capabilities(&self) -> RuntimeCapabilities {
+        RuntimeCapabilities {
+            passthrough_only: false,
+            client_executes: false,
+            // Microsandbox supports placeholder substitution at the TLS
+            // proxy via SecretBuilder so the model never sees the raw
+            // secret value.
+            secret_injection: true,
+            // Hostname-based egress allowlists are first-class in the
+            // microsandbox 0.4 NetworkPolicy builder (`allow_domains` /
+            // `allow_domain_suffixes`). With those rules wired up, this
+            // runtime matches opensandbox's deny-by-default + explicit
+            // allowlist semantics.
+            egress_allowlist: true,
+            skill_mount: true,
+            file_io: true,
+            network_isolation_modes: vec![
+                NetworkMode::None,
+                NetworkMode::AllowList,
+                NetworkMode::Full,
+            ],
+            max_session_duration: None,
+        }
+    }
+
+    async fn start_session(&self, spec: SessionSpec) -> RuntimeResult<SessionHandle> {
+        let session_id = spec
+            .session_id_hint
+            .unwrap_or_else(|| format!("hadrian-{}", Uuid::new_v4()));
+
+        let cpus: u8 = spec
+            .cpu_limit
+            .map(|c| c.ceil().clamp(1.0, u8::MAX as f64) as u8)
+            .unwrap_or_else(|| cpus_for_sdk(self.config.cpus));
+        let memory_mb: u32 = spec
+            .mem_limit_bytes
+            .map(|b| (b / (1024 * 1024)) as u32)
+            .unwrap_or(self.config.memory_mb);
+
+        // Translate Hadrian's `allow_hosts` patterns into a concrete
+        // `NetworkPolicy`. The shapes we accept (from the OpenAI shell
+        // tool spec via `resolve_shell_environment`):
+        //   - `[]`        → no egress (deny-all). Matches opensandbox.
+        //   - `["*"]`     → public internet + DNS to the gateway resolver.
+        //                   Other private egress and the IMDS endpoint at
+        //                   169.254.169.254 stay blocked. See
+        //                   `build_network_policy`.
+        //   - exact name  → `allow_domains([name])`.
+        //   - `*.suffix`  → `allow_domain_suffixes([suffix])`.
+        // Per-secret allow-host rules still apply on top via
+        // `secret().allow_host()` below.
+        let policy = build_network_policy(&spec.egress_policy.allow_hosts);
+
+        info!(
+            stage = "microsandbox_starting",
+            session_id = %session_id,
+            image = %self.config.image,
+            cpus,
+            memory_mb,
+            egress_hosts = ?spec.egress_policy.allow_hosts,
+            "Creating microsandbox VM"
+        );
+
+        let mut builder = Sandbox::builder(session_id.clone())
+            .image(self.config.image.clone())
+            .cpus(cpus)
+            .memory(memory_mb)
+            .replace()
+            .network(|n| n.policy(policy));
+
+        // Wire each requested SecretMount into microsandbox's
+        // SecretBuilder. Each mount gives the guest a placeholder env
+        // var (e.g. `$MSB_GITHUB_TOKEN`); the TLS-intercepting proxy
+        // substitutes the real value when outbound requests are
+        // destined for one of the allowed hosts. The model never sees
+        // the raw secret value.
+        for mount in &spec.egress_policy.secrets {
+            if mount.allowed_hosts.is_empty() {
+                return Err(RuntimeError::Backend(format!(
+                    "secret mount {:?} has no allowed_hosts",
+                    mount.placeholder
+                )));
+            }
+            let placeholder = mount.placeholder.clone();
+            let value = mount.value.clone();
+            let hosts = mount.allowed_hosts.clone();
+            builder = builder.secret(move |s| {
+                let mut sb = s.env(&placeholder).value(&value);
+                for h in &hosts {
+                    sb = if h.contains('*') {
+                        sb.allow_host_pattern(h)
+                    } else {
+                        sb.allow_host(h)
+                    };
+                }
+                sb
+            });
+        }
+
+        let sandbox = builder
+            .create()
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("microsandbox create: {e}")))?;
+
+        // Mount any requested skill bundles via the VM's filesystem
+        // API. Each skill's files are written under its `mount_path`;
+        // intermediate directories are created on demand.
+        for skill in &spec.mounted_skills {
+            mount_skill_into_sandbox(&sandbox, skill).await?;
+            debug!(
+                stage = "microsandbox_skill_mounted",
+                skill_id = %skill.skill_id,
+                mount_path = %skill.mount_path,
+                file_count = skill.files.len(),
+                "Mounted skill bundle"
+            );
+        }
+
+        Ok(SessionHandle::new(
+            session_id,
+            Box::new(MicrosandboxSession {
+                sandbox: Arc::new(Mutex::new(Some(sandbox))),
+            }),
+        ))
+    }
+}
+
+/// Build a [`NetworkPolicy`] from a Hadrian `allow_hosts` list (already
+/// intersected with the operator allowlist by `resolve_shell_environment`).
+///
+/// Rules:
+/// - Empty list → deny-all in both directions. The runtime defers to
+///   `NetworkPolicy::none()`; matches opensandbox's default semantics
+///   so the model can't quietly assume the public internet is reachable
+///   when no per-request `network_policy` was supplied.
+/// - `"*"` anywhere in the list → public internet on any port plus DNS to
+///   the per-sandbox gateway resolver (a private/CGN address `public_only()`
+///   would otherwise refuse). All other private/loopback/link-local/metadata
+///   egress stays denied, so SSRF surface is limited to name resolution.
+/// - Otherwise → deny by default, allow only the supplied hostnames /
+///   `*.suffix` patterns. Patterns are normalized: a leading `*.` is
+///   recognised as a `Destination::DomainSuffix`; everything else is
+///   treated as an exact `Destination::Domain`.
+fn build_network_policy(allow_hosts: &[String]) -> NetworkPolicy {
+    if allow_hosts.is_empty() {
+        return NetworkPolicy::none();
+    }
+    if allow_hosts.iter().any(|h| h == "*") {
+        // Public internet on any port, plus DNS to the per-sandbox gateway
+        // resolver. `public_only()` alone denies the gateway (a private/CGN
+        // address in the 100.96.0.0/11 pool), so name resolution is refused;
+        // the explicit `Host` rule on :53 reaches the resolver without
+        // opening any other private/LAN egress. IMDS (169.254.169.254) and
+        // loopback stay blocked.
+        return NetworkPolicy::builder()
+            .default_deny()
+            .egress(|e| e.allow_public())
+            .egress(|e| e.allow_host().udp().tcp().port(53))
+            .build()
+            .unwrap_or_else(|err| {
+                warn!(
+                    stage = "microsandbox_public_policy_build_failed",
+                    error = %err,
+                    "public egress policy build failed; falling back to public_only"
+                );
+                NetworkPolicy::public_only()
+            });
+    }
+
+    let mut domains: Vec<String> = Vec::new();
+    let mut suffixes: Vec<String> = Vec::new();
+    for h in allow_hosts {
+        let h = h.trim().trim_end_matches('.');
+        if let Some(rest) = h.strip_prefix("*.") {
+            // Strip a redundant trailing dot the operator might have
+            // typed (`*.example.com.`).
+            suffixes.push(rest.trim_end_matches('.').to_string());
+        } else {
+            domains.push(h.to_string());
+        }
+    }
+
+    // Egress is the only thing this allowlist gates. We don't publish
+    // inbound ports for shell-tool VMs, so denying ingress is benign
+    // (avoids the extra `Action` import path).
+    //
+    // The `Host` rule on :53 is required for the SAME reason as the `*`
+    // branch above: the guest resolves these domains through the per-sandbox
+    // gateway resolver, which `default_deny` (and `public_only`) classify as
+    // `Host` and refuse — so without it DNS for `allowed_domains` fails and
+    // the domains are unreachable even though the policy "allows" them. The
+    // SDK's own `public_only_preset_denies_host_gateway` test confirms the
+    // gateway is denied by default. This opens DNS to the gateway only, not
+    // any other private/LAN egress.
+    let policy = NetworkPolicy::builder()
+        .default_deny()
+        .egress(|e| e.allow_host().udp().tcp().port(53))
+        .egress(|e| {
+            if !suffixes.is_empty() {
+                e.allow_domain_suffixes(suffixes.iter().cloned());
+            }
+            if !domains.is_empty() {
+                e.allow_domains(domains.iter().cloned());
+            }
+            e
+        });
+    match policy.build() {
+        Ok(p) => p,
+        Err(err) => {
+            // Builder errors only happen on invalid patterns (e.g. an
+            // empty domain string). Fall back to deny-all rather than
+            // silently allowing more than the operator asked for.
+            warn!(
+                stage = "microsandbox_policy_build_failed",
+                error = %err,
+                hosts = ?allow_hosts,
+                "NetworkPolicy build failed; falling back to deny-all"
+            );
+            NetworkPolicy::none()
+        }
+    }
+}
+
+/// Write a skill's files into a freshly-booted sandbox. Creates the
+/// mount directory and any subdirectories implied by file paths.
+async fn mount_skill_into_sandbox(
+    sandbox: &Sandbox,
+    skill: &crate::runtimes::SkillMount,
+) -> RuntimeResult<()> {
+    let fs = sandbox.fs();
+    // Root directory first.
+    fs.mkdir(&skill.mount_path)
+        .await
+        .map_err(|e| RuntimeError::Backend(format!("mkdir {}: {e}", skill.mount_path)))?;
+    for file in &skill.files {
+        // Reject path traversal: treat the SkillService output as
+        // untrusted on this code path. `..` or absolute prefixes
+        // would let one skill clobber arbitrary paths inside the VM.
+        let safe_rel = sanitize_skill_relative_path(&file.relative_path)?;
+        let full_path = join_paths(&skill.mount_path, &safe_rel);
+        // Ensure parent directory exists.
+        if let Some(parent) = parent_of(&full_path)
+            && parent != skill.mount_path
+        {
+            // microsandbox returns an AlreadyExists-style error if
+            // the directory is already there; log other failures so
+            // we don't silently swallow real problems on `write`
+            // later. Per CLAUDE.md memory: prefer correctness + debug
+            // logs over silent error swallowing.
+            if let Err(e) = fs.mkdir(&parent).await {
+                let msg = e.to_string();
+                let already_exists = msg.contains("AlreadyExists")
+                    || msg.contains("already exists")
+                    || msg.contains("EEXIST");
+                if !already_exists {
+                    debug!(
+                        path = %parent,
+                        error = %msg,
+                        "Non-AlreadyExists mkdir error inside sandbox (continuing)"
+                    );
+                }
+            }
+        }
+        fs.write(&full_path, file.content.as_ref())
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("write {full_path}: {e}")))?;
+    }
+    Ok(())
+}
+
+/// Reject path traversal in skill-file relative paths. Returns the
+/// cleaned path (leading slashes stripped) or a `RuntimeError::Backend`
+/// on any `..` segment, absolute prefix, or non-normal component.
+fn sanitize_skill_relative_path(rel: &str) -> RuntimeResult<String> {
+    use std::path::{Component, Path};
+    let path = Path::new(rel);
+    if path.is_absolute() {
+        return Err(RuntimeError::Backend(format!(
+            "skill relative_path must not be absolute: {rel}"
+        )));
+    }
+    let mut cleaned = std::path::PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::Normal(part) => cleaned.push(part),
+            Component::CurDir => {}
+            Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
+                return Err(RuntimeError::Backend(format!(
+                    "skill relative_path must not contain traversal: {rel}"
+                )));
+            }
+        }
+    }
+    cleaned.to_str().map(str::to_string).ok_or_else(|| {
+        RuntimeError::Backend(format!("skill relative_path is not valid UTF-8: {rel}"))
+    })
+}
+
+fn join_paths(base: &str, rel: &str) -> String {
+    let base = base.trim_end_matches('/');
+    let rel = rel.trim_start_matches('/');
+    format!("{base}/{rel}")
+}
+
+fn parent_of(path: &str) -> Option<String> {
+    let trimmed = path.trim_end_matches('/');
+    let idx = trimmed.rfind('/')?;
+    if idx == 0 {
+        return Some("/".to_string());
+    }
+    Some(trimmed[..idx].to_string())
+}
+
+/// Internal sentinel returned by the per-iteration `select!` inside
+/// the exec drain task: a delivered SDK event, the upstream channel
+/// closing cleanly, or the per-command deadline elapsing.
+enum DrainOutcome {
+    Event(MsExecEvent),
+    Eof,
+    Timeout,
+}
+
+/// One live microsandbox session.
+///
+/// The inner `Option<Sandbox>` lets `terminate()` consume the Sandbox
+/// without requiring `&mut self` (which the trait doesn't provide).
+struct MicrosandboxSession {
+    sandbox: Arc<Mutex<Option<Sandbox>>>,
+}
+
+#[async_trait]
+impl ShellSession for MicrosandboxSession {
+    async fn exec(&self, cmd: ExecRequest) -> RuntimeResult<ExecHandle> {
+        let guard = self.sandbox.lock().await;
+        let sandbox = guard
+            .as_ref()
+            .ok_or_else(|| RuntimeError::Backend("session already terminated".into()))?;
+
+        // stdin: SDK supports a Pipe mode for streaming; for a one-shot
+        // bytes payload from the model we'd ideally use `stdin_bytes`
+        // before exec, but `shell_stream` is the simplest path and
+        // doesn't accept stdin. Fall back to redirecting via heredoc in
+        // the command when stdin is provided.
+        //
+        // Per-call random terminator: a fixed marker is forge-able
+        // (an adversarial model could embed the literal string in
+        // stdin to escape into shell). The UUID makes collision
+        // probability ~2^-122. Single-quoting prevents variable
+        // expansion inside the body.
+        let script = match cmd.stdin {
+            Some(bytes) => {
+                let stdin_text = String::from_utf8_lossy(&bytes);
+                let terminator = format!("__HADRIAN_STDIN_{}__", uuid::Uuid::new_v4().simple());
+                format!(
+                    "{} <<'{terminator}'\n{stdin_text}\n{terminator}",
+                    cmd.command
+                )
+            }
+            None => cmd.command.clone(),
+        };
+
+        let mut handle = sandbox
+            .shell_stream(script)
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("microsandbox shell_stream: {e}")))?;
+
+        // Honor the per-command timeout in `ExecRequest`. The SDK's
+        // `shell_stream` doesn't apply the `ExecOptionsBuilder.timeout`
+        // value to the streaming path (`exec_stream_inner` discards it
+        // — only `exec_with_opts` enforces it after collecting), so we
+        // wrap the drain loop with `tokio::time::timeout` ourselves and
+        // call the SDK's `handle.kill()` on elapse. Exit code 124 is
+        // the coreutils convention for "command timed out."
+        //
+        // Stash a clone of the underlying `ExecHandle` first so the kill
+        // path doesn't fight the drain task for ownership.
+        let kill_after = cmd.timeout;
+        let exec_id = handle.id();
+        // Bridge the SDK's UnboundedReceiver<MsExecEvent> into our
+        // Stream<ExecEvent>. We can't move `handle` directly across a
+        // .await in a stream::unfold without owning it, so we drain it
+        // into our own channel via a detached task.
+        let (tx, rx) = mpsc::channel::<ExecEvent>(32);
+        crate::compat::spawn_detached(async move {
+            let deadline = kill_after.map(|d| tokio::time::Instant::now() + d);
+            let mut exit_seen = false;
+            loop {
+                let next = if let Some(dl) = deadline {
+                    tokio::select! {
+                        ev = handle.recv() => ev.map(DrainOutcome::Event)
+                            .unwrap_or(DrainOutcome::Eof),
+                        _ = tokio::time::sleep_until(dl) => DrainOutcome::Timeout,
+                    }
+                } else {
+                    match handle.recv().await {
+                        Some(ev) => DrainOutcome::Event(ev),
+                        None => DrainOutcome::Eof,
+                    }
+                };
+
+                match next {
+                    DrainOutcome::Event(ev) => {
+                        let mapped = match ev {
+                            MsExecEvent::Started { .. } => continue, // skip
+                            MsExecEvent::Stdout(b) => ExecEvent::Stdout(b),
+                            MsExecEvent::Stderr(b) => ExecEvent::Stderr(b),
+                            MsExecEvent::Exited { code } => {
+                                exit_seen = true;
+                                ExecEvent::Exit { code, signal: None }
+                            }
+                            MsExecEvent::Failed(f) => {
+                                warn!(
+                                    stage = "exec_failed",
+                                    error = ?f,
+                                    exec_id = %exec_id,
+                                    "microsandbox exec failed to start"
+                                );
+                                exit_seen = true;
+                                ExecEvent::Exit {
+                                    code: -1,
+                                    signal: None,
+                                }
+                            }
+                        };
+                        if tx.send(mapped).await.is_err() {
+                            return;
+                        }
+                    }
+                    DrainOutcome::Eof => return,
+                    DrainOutcome::Timeout => {
+                        warn!(
+                            stage = "exec_timeout",
+                            exec_id = %exec_id,
+                            timeout_ms = kill_after.map(|d| d.as_millis() as u64),
+                            "microsandbox shell command exceeded timeout; killing"
+                        );
+                        // Best-effort kill of the underlying process.
+                        if let Err(e) = handle.kill().await {
+                            warn!(
+                                stage = "exec_kill_failed",
+                                exec_id = %exec_id,
+                                error = ?e,
+                                "Failed to kill timed-out microsandbox exec"
+                            );
+                        }
+                        // Brief grace period to collect anything the
+                        // process emitted between the timeout firing
+                        // and the kill landing. After that, emit our
+                        // own `Exit { code: 124 }` so the caller's
+                        // stream terminates promptly.
+                        let grace =
+                            tokio::time::Instant::now() + std::time::Duration::from_millis(500);
+                        loop {
+                            let res = tokio::select! {
+                                ev = handle.recv() => Some(ev),
+                                _ = tokio::time::sleep_until(grace) => None,
+                            };
+                            match res {
+                                Some(Some(MsExecEvent::Stdout(b))) => {
+                                    let _ = tx.send(ExecEvent::Stdout(b)).await;
+                                }
+                                Some(Some(MsExecEvent::Stderr(b))) => {
+                                    let _ = tx.send(ExecEvent::Stderr(b)).await;
+                                }
+                                Some(Some(MsExecEvent::Exited { code })) => {
+                                    let _ = tx.send(ExecEvent::Exit { code, signal: None }).await;
+                                    return;
+                                }
+                                Some(Some(_)) => continue,
+                                // Stream closed or grace elapsed.
+                                Some(None) | None => break,
+                            }
+                        }
+                        if !exit_seen {
+                            let _ = tx
+                                .send(ExecEvent::Exit {
+                                    code: 124,
+                                    signal: None,
+                                })
+                                .await;
+                        }
+                        return;
+                    }
+                }
+            }
+        });
+
+        Ok(ExecHandle {
+            output: Box::pin(receiver_stream(rx)),
+        })
+    }
+
+    async fn write_file(&self, path: &str, bytes: Bytes) -> RuntimeResult<()> {
+        let guard = self.sandbox.lock().await;
+        let sandbox = guard
+            .as_ref()
+            .ok_or_else(|| RuntimeError::Backend("session already terminated".into()))?;
+        sandbox
+            .fs()
+            .write(path, bytes.as_ref())
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("write_file {path}: {e}")))
+    }
+
+    async fn read_file(&self, path: &str) -> RuntimeResult<Bytes> {
+        let guard = self.sandbox.lock().await;
+        let sandbox = guard
+            .as_ref()
+            .ok_or_else(|| RuntimeError::Backend("session already terminated".into()))?;
+        sandbox
+            .fs()
+            .read(path)
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("read_file {path}: {e}")))
+    }
+
+    async fn terminate(&self) -> RuntimeResult<()> {
+        let mut guard = self.sandbox.lock().await;
+        let Some(sandbox) = guard.take() else {
+            return Ok(());
+        };
+        match sandbox.stop_and_wait().await {
+            Ok(status) => {
+                info!(
+                    stage = "microsandbox_stopped",
+                    exit_code = status.code().unwrap_or(-1),
+                    "microsandbox VM stopped cleanly"
+                );
+                Ok(())
+            }
+            Err(e) => {
+                error!(
+                    stage = "microsandbox_stop_failed",
+                    error = %e,
+                    "Failed to stop microsandbox VM"
+                );
+                Err(RuntimeError::Backend(format!("stop_and_wait: {e}")))
+            }
+        }
+    }
+}
+
+fn receiver_stream<T>(mut rx: mpsc::Receiver<T>) -> impl Stream<Item = T> + Send
+where
+    T: Send + 'static,
+{
+    futures_util::stream::poll_fn(move |cx| rx.poll_recv(cx))
+}
diff --git a/src/runtimes/mod.rs b/src/runtimes/mod.rs
new file mode 100644
index 0000000..9d7bea6
--- /dev/null
+++ b/src/runtimes/mod.rs
@@ -0,0 +1,325 @@
+//! Pluggable shell-tool runtimes for the Responses API.
+//!
+//! A "runtime" is the backend that executes the model's `shell` tool
+//! calls — anything from forwarding the request verbatim to OpenAI's
+//! hosted container, to spawning a local microVM via microsandbox, to
+//! delegating to a managed sandbox service like E2B.
+//!
+//! Each runtime implements the [`ShellRuntime`] trait. The orchestrator
+//! in `services::server_tools` picks one based on admin config + the
+//! request's upstream provider, then drives sessions through the
+//! [`ShellSession`] interface.
+//!
+//! # Backends
+//!
+//! - **`passthrough_openai`** — forward the shell tool spec to OpenAI
+//!   unchanged so OpenAI's hosted container executes the call.
+//! - **`client_passthrough`** — the API client fulfills shell calls
+//!   itself (OpenAI's "local shell" mode, generalized to all providers).
+//!   Hadrian validates the request, keeps OpenAI's native `shell` spec
+//!   intact, rewrites it to a function tool for non-OpenAI providers,
+//!   and does not register a server-side executor.
+//! - **`microsandbox`** — local microVMs via
+//!   <https://github.com/superradcompany/microsandbox>. Behind the
+//!   `runtime-microsandbox` feature flag.
+//! - **`opensandbox`** — Alibaba's [Sandbox
+//!   Protocol](https://github.com/alibaba/OpenSandbox) over HTTP. Behind
+//!   the `runtime-opensandbox` feature flag.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::{pin::Pin, time::Duration};
+
+use async_trait::async_trait;
+use bytes::Bytes;
+use futures_util::stream::Stream;
+use thiserror::Error;
+
+#[cfg(feature = "runtime-microsandbox")]
+pub mod microsandbox;
+#[cfg(feature = "runtime-opensandbox")]
+pub mod opensandbox;
+pub mod passthrough;
+
+#[cfg(feature = "runtime-microsandbox")]
+pub use microsandbox::MicrosandboxRuntime;
+#[cfg(feature = "runtime-opensandbox")]
+pub use opensandbox::OpenSandboxRuntime;
+pub use passthrough::PassthroughRuntime;
+
+/// Errors returned by runtime adapters.
+#[derive(Debug, Error)]
+pub enum RuntimeError {
+    /// The requested capability is not supported by this backend
+    /// (e.g. per-domain secret injection on a backend that only does
+    /// allow-all/deny-all egress).
+    #[error("runtime does not support: {0}")]
+    Unsupported(&'static str),
+
+    /// The backend was reachable but returned an error.
+    #[error("runtime error: {0}")]
+    Backend(String),
+
+    /// Could not reach the backend (network, auth, etc.).
+    #[error("runtime unreachable: {0}")]
+    Unreachable(String),
+
+    /// Session timed out (max_session_duration exceeded).
+    #[error("session exceeded max duration")]
+    SessionTimeout,
+
+    /// The orchestrator should not invoke local execution — the request
+    /// is being forwarded to the upstream provider. Returned by the
+    /// passthrough adapter from `start_session`.
+    #[error("runtime is in passthrough mode; defer to upstream provider")]
+    Passthrough,
+}
+
+pub type RuntimeResult<T> = Result<T, RuntimeError>;
+
+/// Network isolation policy advertised by a runtime.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum NetworkMode {
+    /// Container has no outbound network access.
+    None,
+    /// Container can reach hosts on the allowlist only.
+    AllowList,
+    /// Container has unrestricted outbound network access.
+    Full,
+}
+
+/// What a runtime can and cannot do.
+///
+/// Inspected before starting a session; if the request demands a
+/// capability the runtime can't deliver (e.g. per-domain secret
+/// injection on a backend that doesn't support it), the orchestrator
+/// fails the request with a clear capability-mismatch error rather than
+/// silently degrading.
+#[derive(Debug, Clone)]
+pub struct RuntimeCapabilities {
+    /// True if the runtime defers shell execution rather than running it
+    /// in a Hadrian-hosted environment. When set, the orchestrator does
+    /// not register a [`ShellExecutor`](crate::services::shell_tool::ShellExecutor)
+    /// for the request. Combine with [`client_executes`] to distinguish
+    /// where execution actually happens (`false` = upstream provider's
+    /// hosted container; `true` = the API client).
+    pub passthrough_only: bool,
+    /// True iff the shell call is fulfilled by the API client itself
+    /// (rather than the upstream provider). Drives the preprocessing
+    /// decision in `routes/execution.rs`: when this is set, the OpenAI
+    /// native `shell` tool spec is left intact so the model emits
+    /// `shell_call` items the OpenAI SDK's local-shell loop can
+    /// recognize, while non-OpenAI providers still receive the
+    /// function-mode rewrite so they emit `function_call` items the
+    /// client can interpret. Meaningless without `passthrough_only`.
+    pub client_executes: bool,
+    /// Can the runtime substitute placeholder strings with secret
+    /// values at egress (so the model never sees raw secret values)?
+    pub secret_injection: bool,
+    /// Can the runtime enforce a per-domain egress allowlist?
+    pub egress_allowlist: bool,
+    /// Can the runtime mount skill bundles into the session?
+    pub skill_mount: bool,
+    /// Can the runtime stage files in/out of the session?
+    pub file_io: bool,
+    /// Network isolation modes the runtime supports.
+    pub network_isolation_modes: Vec<NetworkMode>,
+    /// Hard limit on session duration, if any.
+    pub max_session_duration: Option<Duration>,
+}
+
+impl RuntimeCapabilities {
+    /// Capabilities of a passthrough runtime where the upstream provider's
+    /// hosted environment executes the call (e.g. OpenAI's Responses API
+    /// container).
+    pub fn passthrough_upstream() -> Self {
+        Self {
+            passthrough_only: true,
+            client_executes: false,
+            secret_injection: false,
+            egress_allowlist: false,
+            skill_mount: false,
+            file_io: false,
+            network_isolation_modes: Vec::new(),
+            max_session_duration: None,
+        }
+    }
+
+    /// Capabilities of a passthrough runtime where the API client fulfills
+    /// shell calls itself (OpenAI's local-shell mode, generalized to all
+    /// providers). The orchestrator still skips registering an executor;
+    /// the difference from [`passthrough_upstream`](Self::passthrough_upstream)
+    /// is purely in the preprocessing decision documented on
+    /// [`client_executes`](RuntimeCapabilities::client_executes).
+    pub fn passthrough_client() -> Self {
+        Self {
+            passthrough_only: true,
+            client_executes: true,
+            ..Self::passthrough_upstream()
+        }
+    }
+}
+
+/// Egress policy applied to a session.
+#[derive(Debug, Clone, Default)]
+pub struct EgressPolicy {
+    /// Allowed hostnames (or hostname patterns). Empty = deny-all.
+    pub allow_hosts: Vec<String>,
+    /// Map of placeholder name → secret value. The runtime substitutes
+    /// `${PLACEHOLDER}` in outbound request headers/bodies with the
+    /// real value when the destination matches `allow_hosts`. The model
+    /// only ever sees the placeholders.
+    pub secrets: Vec<SecretMount>,
+}
+
+#[derive(Debug, Clone)]
+pub struct SecretMount {
+    /// The placeholder the model will see, e.g. `GITHUB_TOKEN`.
+    pub placeholder: String,
+    /// The actual secret value. Never logged. Cleared on session
+    /// termination.
+    pub value: String,
+    /// Hostnames this secret may be sent to (if empty, applies
+    /// everywhere in `allow_hosts`).
+    pub allowed_hosts: Vec<String>,
+}
+
+/// Skill bundle to mount into a session.
+///
+/// The gateway resolves `skill_id` to file contents from `SkillService`
+/// and passes the materialized files in `files`. Adapters write them
+/// to `mount_path` inside the sandbox via whatever native filesystem
+/// API the runtime exposes (microsandbox: `sandbox.fs().write()`;
+/// OpenSandbox: execd `/files/upload`).
+#[derive(Debug, Clone)]
+pub struct SkillMount {
+    pub skill_id: String,
+    /// Mount path inside the container (e.g. `/skills/<skill_id>`).
+    pub mount_path: String,
+    /// Files to write under `mount_path`. Paths are relative to the
+    /// mount point; the adapter is responsible for creating
+    /// intermediate directories.
+    pub files: Vec<MountedFile>,
+}
+
+/// One file to write into a sandbox during skill mount.
+#[derive(Debug, Clone)]
+pub struct MountedFile {
+    /// Path relative to `SkillMount::mount_path`.
+    pub relative_path: String,
+    /// File contents.
+    pub content: bytes::Bytes,
+}
+
+/// Parameters for starting a new session.
+#[derive(Debug, Clone, Default)]
+pub struct SessionSpec {
+    pub network_mode: Option<NetworkMode>,
+    pub egress_policy: EgressPolicy,
+    pub mounted_skills: Vec<SkillMount>,
+    pub cpu_limit: Option<f64>,
+    pub mem_limit_bytes: Option<u64>,
+    pub session_id_hint: Option<String>,
+}
+
+/// A request to execute one shell command in an existing session.
+#[derive(Debug, Clone)]
+pub struct ExecRequest {
+    pub command: String,
+    /// Optional stdin to pipe to the command.
+    pub stdin: Option<Bytes>,
+    /// Wall-clock timeout for this command.
+    pub timeout: Option<Duration>,
+}
+
+/// One event from a running command.
+#[derive(Debug, Clone)]
+pub enum ExecEvent {
+    /// Stdout chunk.
+    Stdout(Bytes),
+    /// Stderr chunk.
+    Stderr(Bytes),
+    /// Final exit signal. Always the last event emitted for a command.
+    Exit { code: i32, signal: Option<i32> },
+}
+
+/// Handle to a running command — streams output until exit.
+pub struct ExecHandle {
+    pub output: Pin<Box<dyn Stream<Item = ExecEvent> + Send>>,
+}
+
+/// Top-level trait every runtime adapter implements.
+///
+/// Mirrors the `SecretManager` trait shape (`async_trait` + per-backend
+/// implementors gated behind feature flags).
+#[async_trait]
+pub trait ShellRuntime: Send + Sync {
+    /// What this runtime can do. Inspected once at startup and per
+    /// session-start to fail fast on capability mismatches.
+    fn capabilities(&self) -> RuntimeCapabilities;
+
+    /// Start a new session.
+    ///
+    /// Passthrough adapters return `Err(RuntimeError::Passthrough)` so
+    /// the orchestrator knows to defer to the upstream provider.
+    async fn start_session(&self, spec: SessionSpec) -> RuntimeResult<SessionHandle>;
+
+    /// Cheap readiness check (e.g. ping the backend, verify auth).
+    async fn health_check(&self) -> RuntimeResult<()> {
+        Ok(())
+    }
+}
+
+/// Owned handle to a live session.
+///
+/// Owns the underlying `ShellSession` implementation and tears it down
+/// in `Drop` (best-effort; explicit `terminate()` is preferred).
+pub struct SessionHandle {
+    pub session_id: String,
+    inner: Box<dyn ShellSession>,
+}
+
+impl SessionHandle {
+    pub fn new(session_id: String, inner: Box<dyn ShellSession>) -> Self {
+        Self { session_id, inner }
+    }
+
+    pub async fn exec(&self, cmd: ExecRequest) -> RuntimeResult<ExecHandle> {
+        self.inner.exec(cmd).await
+    }
+
+    pub async fn write_file(&self, path: &str, bytes: Bytes) -> RuntimeResult<()> {
+        self.inner.write_file(path, bytes).await
+    }
+
+    pub async fn read_file(&self, path: &str) -> RuntimeResult<Bytes> {
+        self.inner.read_file(path).await
+    }
+
+    /// Tear down the session. Always prefer calling this explicitly so
+    /// errors are surfaced; `Drop` is best-effort.
+    pub async fn terminate(self) -> RuntimeResult<()> {
+        self.inner.terminate().await
+    }
+}
+
+/// Per-session API exposed by the runtime adapter.
+#[async_trait]
+pub trait ShellSession: Send + Sync {
+    /// Run one command. Returns a handle that streams output until
+    /// exit.
+    async fn exec(&self, cmd: ExecRequest) -> RuntimeResult<ExecHandle>;
+
+    /// Stage a file into the session's filesystem.
+    async fn write_file(&self, _path: &str, _bytes: Bytes) -> RuntimeResult<()> {
+        Err(RuntimeError::Unsupported("file_io"))
+    }
+
+    /// Read a file out of the session's filesystem.
+    async fn read_file(&self, _path: &str) -> RuntimeResult<Bytes> {
+        Err(RuntimeError::Unsupported("file_io"))
+    }
+
+    /// Tear down the session. Called exactly once.
+    async fn terminate(&self) -> RuntimeResult<()>;
+}
diff --git a/src/runtimes/opensandbox.rs b/src/runtimes/opensandbox.rs
new file mode 100644
index 0000000..f4ee4f0
--- /dev/null
+++ b/src/runtimes/opensandbox.rs
@@ -0,0 +1,718 @@
+//! OpenSandbox runtime adapter.
+//!
+//! Speaks the Alibaba OpenSandbox Lifecycle API (`POST /v1/sandboxes`,
+//! `DELETE /v1/sandboxes/{id}`) to provision/tear down sandboxes, then
+//! the execd API (`POST /command`) inside each sandbox to run shell
+//! commands. Hadrian sees only the Lifecycle endpoint; the OpenSandbox
+//! control plane (Docker or Kubernetes) handles the actual container
+//! orchestration.
+//!
+//! Spec: <https://github.com/alibaba/OpenSandbox/blob/main/specs/sandbox-lifecycle.yml>
+//! Execd spec: <https://github.com/alibaba/OpenSandbox/blob/main/specs/execd-api.yaml>
+
+#![cfg(feature = "runtime-opensandbox")]
+
+use std::{sync::Arc, time::Duration};
+
+use async_trait::async_trait;
+use bytes::Bytes;
+use futures_util::stream::{Stream, StreamExt};
+use reqwest::{Client, header};
+use serde::{Deserialize, Serialize};
+use tokio::sync::{Mutex, mpsc};
+use tracing::{debug, error, info, warn};
+use uuid::Uuid;
+
+use crate::{
+    config::OpenSandboxConfig,
+    runtimes::{
+        ExecEvent, ExecHandle, ExecRequest, NetworkMode, RuntimeCapabilities, RuntimeError,
+        RuntimeResult, SessionHandle, SessionSpec, ShellRuntime, ShellSession,
+    },
+    streaming::SseBuffer,
+};
+
+/// Default container image when the request doesn't specify one.
+const DEFAULT_IMAGE: &str = "python:3.11-slim";
+
+/// Port that OpenSandbox's execd listens on inside every sandbox.
+const EXECD_PORT: u16 = 44772;
+
+/// Status states from the Lifecycle API.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+enum SandboxState {
+    Pending,
+    Running,
+    Pausing,
+    Paused,
+    Resuming,
+    Stopping,
+    Terminated,
+    Failed,
+}
+
+#[derive(Debug, Deserialize)]
+struct SandboxStatusObj {
+    state: SandboxState,
+}
+
+#[derive(Debug, Deserialize)]
+struct SandboxResponse {
+    id: String,
+    status: SandboxStatusObj,
+}
+
+#[derive(Debug, Serialize)]
+struct CreateSandboxRequest<'a> {
+    image: ImageSpec<'a>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    timeout: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none", rename = "resourceLimits")]
+    resource_limits: Option<ResourceLimits<'a>>,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    entrypoint: Vec<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none", rename = "networkPolicy")]
+    network_policy: Option<NetworkPolicySpec<'a>>,
+}
+
+#[derive(Debug, Serialize)]
+struct ImageSpec<'a> {
+    uri: &'a str,
+}
+
+#[derive(Debug, Serialize)]
+struct ResourceLimits<'a> {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    cpu: Option<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    memory: Option<&'a str>,
+}
+
+#[derive(Debug, Serialize)]
+struct NetworkPolicySpec<'a> {
+    #[serde(rename = "defaultAction")]
+    default_action: &'a str,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    egress: Vec<EgressRule<'a>>,
+}
+
+#[derive(Debug, Serialize)]
+struct EgressRule<'a> {
+    action: &'a str,
+    target: &'a str,
+}
+
+#[derive(Debug, Serialize)]
+struct RunCommandRequest<'a> {
+    command: &'a str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    timeout: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    cwd: Option<&'a str>,
+    #[serde(default)]
+    background: bool,
+}
+
+#[derive(Debug, Deserialize)]
+struct EndpointResponse {
+    url: String,
+}
+
+/// `ShellRuntime` implementation that delegates to an OpenSandbox
+/// control plane.
+pub struct OpenSandboxRuntime {
+    config: OpenSandboxConfig,
+    http: Client,
+}
+
+impl OpenSandboxRuntime {
+    pub fn new(config: OpenSandboxConfig, http: Client) -> Self {
+        Self { config, http }
+    }
+
+    fn base_url(&self) -> &str {
+        self.config.endpoint.trim_end_matches('/')
+    }
+
+    fn apply_auth(&self, req: reqwest::RequestBuilder) -> reqwest::RequestBuilder {
+        if let Some(ref key) = self.config.auth_token {
+            req.header("OPEN-SANDBOX-API-KEY", key)
+        } else {
+            req
+        }
+    }
+
+    async fn create_sandbox(&self, body: CreateSandboxRequest<'_>) -> RuntimeResult<String> {
+        let url = format!("{}/sandboxes", self.base_url());
+        let resp = self
+            .apply_auth(self.http.post(&url).json(&body))
+            .send()
+            .await
+            .map_err(|e| RuntimeError::Unreachable(format!("create sandbox: {e}")))?;
+        if !resp.status().is_success() {
+            return Err(RuntimeError::Backend(format!(
+                "create sandbox failed: {} {}",
+                resp.status(),
+                resp.text().await.unwrap_or_default()
+            )));
+        }
+        let sandbox: SandboxResponse = resp
+            .json()
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("decode create response: {e}")))?;
+        Ok(sandbox.id)
+    }
+
+    /// Poll the sandbox until it reaches Running (or terminal failure)
+    /// within the configured timeout. Uses exponential backoff so a
+    /// slow control plane gets fewer polls per second over time.
+    async fn wait_for_running(&self, id: &str) -> RuntimeResult<()> {
+        let deadline =
+            tokio::time::Instant::now() + Duration::from_secs(self.config.start_timeout_secs);
+        let mut backoff = Duration::from_millis(100);
+        let max_backoff = Duration::from_secs(2);
+        loop {
+            if tokio::time::Instant::now() > deadline {
+                return Err(RuntimeError::SessionTimeout);
+            }
+            let url = format!("{}/sandboxes/{}", self.base_url(), id);
+            let resp = self
+                .apply_auth(self.http.get(&url))
+                .send()
+                .await
+                .map_err(|e| RuntimeError::Unreachable(format!("get sandbox: {e}")))?;
+            if !resp.status().is_success() {
+                return Err(RuntimeError::Backend(format!(
+                    "get sandbox failed: {}",
+                    resp.status()
+                )));
+            }
+            let sandbox: SandboxResponse = resp
+                .json()
+                .await
+                .map_err(|e| RuntimeError::Backend(format!("decode get response: {e}")))?;
+            match sandbox.status.state {
+                SandboxState::Running => return Ok(()),
+                SandboxState::Failed | SandboxState::Terminated => {
+                    return Err(RuntimeError::Backend(format!(
+                        "sandbox entered terminal state {:?} before running",
+                        sandbox.status.state
+                    )));
+                }
+                _ => {
+                    tokio::time::sleep(backoff).await;
+                    backoff = (backoff * 2).min(max_backoff);
+                }
+            }
+        }
+    }
+
+    async fn fetch_execd_url(&self, id: &str) -> RuntimeResult<String> {
+        let url = format!(
+            "{}/sandboxes/{}/endpoints/{}",
+            self.base_url(),
+            id,
+            EXECD_PORT
+        );
+        let resp = self
+            .apply_auth(self.http.get(&url))
+            .send()
+            .await
+            .map_err(|e| RuntimeError::Unreachable(format!("get endpoint: {e}")))?;
+        if !resp.status().is_success() {
+            return Err(RuntimeError::Backend(format!(
+                "get endpoint failed: {}",
+                resp.status()
+            )));
+        }
+        let ep: EndpointResponse = resp
+            .json()
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("decode endpoint response: {e}")))?;
+        Ok(ep.url)
+    }
+
+    async fn delete_sandbox(&self, id: &str) -> RuntimeResult<()> {
+        let url = format!("{}/sandboxes/{}", self.base_url(), id);
+        let resp = self
+            .apply_auth(self.http.delete(&url))
+            .send()
+            .await
+            .map_err(|e| RuntimeError::Unreachable(format!("delete sandbox: {e}")))?;
+        if !resp.status().is_success() && resp.status() != reqwest::StatusCode::NOT_FOUND {
+            return Err(RuntimeError::Backend(format!(
+                "delete sandbox failed: {}",
+                resp.status()
+            )));
+        }
+        Ok(())
+    }
+
+    /// Best-effort cleanup of a sandbox we created but couldn't fully
+    /// hand off to a session. Logs the failure (with the rollback
+    /// stage) instead of silently swallowing it — orphaned sandboxes
+    /// burn operator budget and are easy to lose visibility on.
+    async fn cleanup_orphan(&self, id: &str, stage: &'static str) {
+        if let Err(e) = self.delete_sandbox(id).await {
+            warn!(
+                sandbox_id = %id,
+                stage,
+                error = %e,
+                "Failed to delete orphaned opensandbox during rollback"
+            );
+        }
+    }
+}
+
+#[async_trait]
+impl ShellRuntime for OpenSandboxRuntime {
+    fn capabilities(&self) -> RuntimeCapabilities {
+        RuntimeCapabilities {
+            passthrough_only: false,
+            client_executes: false,
+            // Per-domain secret injection isn't natively supported by
+            // execd; secrets get injected via `envs` which makes them
+            // visible in the env block but not destination-scoped.
+            // Mark unsupported so the orchestrator fails fast.
+            secret_injection: false,
+            // OpenSandbox supports network policies natively
+            // (default_action + egress allowlist / denylist).
+            egress_allowlist: true,
+            skill_mount: true,
+            // Backed by execd's `GET /files/download?path=` and
+            // `POST /files/upload` (the same upload endpoint used by
+            // `mount_skill_via_execd`).
+            file_io: true,
+            network_isolation_modes: vec![NetworkMode::Full, NetworkMode::AllowList],
+            max_session_duration: None,
+        }
+    }
+
+    async fn start_session(&self, spec: SessionSpec) -> RuntimeResult<SessionHandle> {
+        if !spec.egress_policy.secrets.is_empty() {
+            return Err(RuntimeError::Unsupported("secret_injection"));
+        }
+
+        let session_id = spec
+            .session_id_hint
+            .unwrap_or_else(|| format!("hadrian-{}", Uuid::new_v4()));
+
+        // Build network policy from egress allowlist if present.
+        let allow_hosts = spec.egress_policy.allow_hosts.clone();
+        let network_policy = if allow_hosts.is_empty() {
+            None
+        } else {
+            Some(NetworkPolicySpec {
+                default_action: "deny",
+                egress: allow_hosts
+                    .iter()
+                    .map(|h| EgressRule {
+                        action: "allow",
+                        target: h.as_str(),
+                    })
+                    .collect(),
+            })
+        };
+
+        let cpu_str = spec.cpu_limit.map(|c| format!("{}m", (c * 1000.0) as u64));
+        let mem_str = spec
+            .mem_limit_bytes
+            .map(|b| format!("{}Mi", b / (1024 * 1024)));
+        let resource_limits = match (&cpu_str, &mem_str) {
+            (None, None) => None,
+            (cpu, mem) => Some(ResourceLimits {
+                cpu: cpu.as_deref(),
+                memory: mem.as_deref(),
+            }),
+        };
+
+        let image = self
+            .config
+            .default_image
+            .as_deref()
+            .unwrap_or(DEFAULT_IMAGE);
+
+        info!(
+            stage = "opensandbox_create",
+            session_id = %session_id,
+            image,
+            "Creating OpenSandbox sandbox"
+        );
+
+        let body = CreateSandboxRequest {
+            image: ImageSpec { uri: image },
+            // Sandbox lifecycle cap — configurable so operators can
+            // bound cost (or extend for long agent sessions) without
+            // touching the source. See
+            // `OpenSandboxConfig::sandbox_timeout_secs`.
+            timeout: Some(self.config.sandbox_timeout_secs.max(
+                // Keep startup polling under the lifecycle deadline.
+                self.config.start_timeout_secs.saturating_add(60),
+            )),
+            resource_limits,
+            entrypoint: vec!["tail", "-f", "/dev/null"],
+            network_policy,
+        };
+
+        let id = self.create_sandbox(body).await?;
+        if let Err(e) = self.wait_for_running(&id).await {
+            self.cleanup_orphan(&id, "wait_for_running").await;
+            return Err(e);
+        }
+        let execd_url = match self.fetch_execd_url(&id).await {
+            Ok(u) => u,
+            Err(e) => {
+                self.cleanup_orphan(&id, "fetch_execd_url").await;
+                return Err(e);
+            }
+        };
+
+        // Mount requested skills via execd /files/upload. Each file is
+        // a separate multipart POST; small bundles fit comfortably,
+        // larger ones get serialized writes.
+        for skill in &spec.mounted_skills {
+            if let Err(e) = mount_skill_via_execd(
+                &self.http,
+                &execd_url,
+                self.config.auth_token.as_deref(),
+                skill,
+            )
+            .await
+            {
+                self.cleanup_orphan(&id, "mount_skill_via_execd").await;
+                return Err(e);
+            }
+            debug!(
+                stage = "opensandbox_skill_mounted",
+                skill_id = %skill.skill_id,
+                mount_path = %skill.mount_path,
+                file_count = skill.files.len(),
+                "Mounted skill bundle"
+            );
+        }
+
+        let session = OpenSandboxSession {
+            http: self.http.clone(),
+            execd_url,
+            sandbox_id: id.clone(),
+            base_url: self.base_url().to_string(),
+            api_key: self.config.auth_token.clone(),
+            terminated: Arc::new(Mutex::new(false)),
+        };
+
+        Ok(SessionHandle::new(session_id, Box::new(session)))
+    }
+}
+
+/// Upload a skill bundle to OpenSandbox via execd `/files/upload`.
+/// Each file is one multipart POST; the `metadata` part is a JSON
+/// `FileMetadata` followed by the binary `file` part.
+async fn mount_skill_via_execd(
+    http: &Client,
+    execd_url: &str,
+    api_key: Option<&str>,
+    skill: &crate::runtimes::SkillMount,
+) -> RuntimeResult<()> {
+    let upload_url = format!("{}/files/upload", execd_url.trim_end_matches('/'));
+    for file in &skill.files {
+        // Reject path traversal and absolute paths. Skills come from
+        // Hadrian's own SkillService, but treat their `relative_path`
+        // as untrusted — a single malicious entry of `../etc/passwd`
+        // would otherwise let one skill clobber arbitrary files inside
+        // the sandbox (and across tenants if a skill is shared).
+        let safe_rel = sanitize_skill_relative_path(&file.relative_path)?;
+        let full_path = format!("{}/{}", skill.mount_path.trim_end_matches('/'), safe_rel);
+        let metadata = serde_json::json!({
+            "path": full_path,
+            "mode": 0o644,
+        });
+        let form = reqwest::multipart::Form::new()
+            .text("metadata", metadata.to_string())
+            .part(
+                "file",
+                reqwest::multipart::Part::bytes(file.content.to_vec())
+                    .mime_str("application/octet-stream")
+                    .unwrap_or_else(|_| reqwest::multipart::Part::bytes(file.content.to_vec())),
+            );
+        let mut req = http.post(&upload_url).multipart(form);
+        if let Some(key) = api_key {
+            req = req.header("OPEN-SANDBOX-API-KEY", key);
+        }
+        let resp = req
+            .send()
+            .await
+            .map_err(|e| RuntimeError::Unreachable(format!("skill upload: {e}")))?;
+        if !resp.status().is_success() {
+            return Err(RuntimeError::Backend(format!(
+                "skill upload {} failed: {}",
+                full_path,
+                resp.status()
+            )));
+        }
+    }
+    Ok(())
+}
+
+/// Reject path traversal in skill-file relative paths. Returns the
+/// cleaned path on success (leading slashes stripped) or a
+/// `RuntimeError::Backend` on any `..` segment, absolute prefix, or
+/// non-normal path component (e.g. `.`, prefix verbatim on Windows).
+fn sanitize_skill_relative_path(rel: &str) -> RuntimeResult<String> {
+    use std::path::{Component, Path};
+
+    let path = Path::new(rel);
+    if path.is_absolute() {
+        return Err(RuntimeError::Backend(format!(
+            "skill relative_path must not be absolute: {rel}"
+        )));
+    }
+    let mut cleaned = std::path::PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::Normal(part) => cleaned.push(part),
+            Component::CurDir => {
+                // `./foo` is harmless; just skip the component.
+            }
+            Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
+                return Err(RuntimeError::Backend(format!(
+                    "skill relative_path must not contain traversal: {rel}"
+                )));
+            }
+        }
+    }
+    cleaned.to_str().map(str::to_string).ok_or_else(|| {
+        RuntimeError::Backend(format!("skill relative_path is not valid UTF-8: {rel}"))
+    })
+}
+
+struct OpenSandboxSession {
+    http: Client,
+    execd_url: String,
+    sandbox_id: String,
+    base_url: String,
+    api_key: Option<String>,
+    terminated: Arc<Mutex<bool>>,
+}
+
+impl OpenSandboxSession {
+    fn auth(&self, req: reqwest::RequestBuilder) -> reqwest::RequestBuilder {
+        if let Some(ref key) = self.api_key {
+            req.header("OPEN-SANDBOX-API-KEY", key)
+        } else {
+            req
+        }
+    }
+}
+
+#[async_trait]
+impl ShellSession for OpenSandboxSession {
+    async fn exec(&self, cmd: ExecRequest) -> RuntimeResult<ExecHandle> {
+        let url = format!("{}/command", self.execd_url.trim_end_matches('/'));
+        let timeout_ms = cmd.timeout.map(|d| d.as_millis() as u64);
+        let body = RunCommandRequest {
+            command: &cmd.command,
+            timeout: timeout_ms,
+            cwd: None,
+            background: false,
+        };
+        let resp = self
+            .auth(
+                self.http
+                    .post(&url)
+                    .header(header::ACCEPT, "text/event-stream")
+                    .json(&body),
+            )
+            .send()
+            .await
+            .map_err(|e| RuntimeError::Unreachable(format!("exec: {e}")))?;
+        if !resp.status().is_success() {
+            return Err(RuntimeError::Backend(format!(
+                "exec failed: {} {}",
+                resp.status(),
+                resp.text().await.unwrap_or_default()
+            )));
+        }
+
+        // Bridge the byte stream into an ExecEvent stream by parsing SSE.
+        let byte_stream = resp.bytes_stream();
+        let output = bridge_sse_to_exec_events(byte_stream);
+        Ok(ExecHandle { output })
+    }
+
+    async fn write_file(&self, path: &str, bytes: Bytes) -> RuntimeResult<()> {
+        let upload_url = format!("{}/files/upload", self.execd_url.trim_end_matches('/'));
+        let metadata = serde_json::json!({
+            "path": path,
+            "mode": 0o644,
+        });
+        let form = reqwest::multipart::Form::new()
+            .text("metadata", metadata.to_string())
+            .part(
+                "file",
+                reqwest::multipart::Part::bytes(bytes.to_vec())
+                    .mime_str("application/octet-stream")
+                    .unwrap_or_else(|_| reqwest::multipart::Part::bytes(bytes.to_vec())),
+            );
+        let resp = self
+            .auth(self.http.post(&upload_url).multipart(form))
+            .send()
+            .await
+            .map_err(|e| RuntimeError::Unreachable(format!("write_file {path}: {e}")))?;
+        if !resp.status().is_success() {
+            return Err(RuntimeError::Backend(format!(
+                "write_file {path} failed: {} {}",
+                resp.status(),
+                resp.text().await.unwrap_or_default()
+            )));
+        }
+        Ok(())
+    }
+
+    async fn read_file(&self, path: &str) -> RuntimeResult<Bytes> {
+        let download_url = format!("{}/files/download", self.execd_url.trim_end_matches('/'));
+        let resp = self
+            .auth(self.http.get(&download_url).query(&[("path", path)]))
+            .send()
+            .await
+            .map_err(|e| RuntimeError::Unreachable(format!("read_file {path}: {e}")))?;
+        if !resp.status().is_success() {
+            return Err(RuntimeError::Backend(format!(
+                "read_file {path} failed: {}",
+                resp.status()
+            )));
+        }
+        resp.bytes()
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("read_file {path} body: {e}")))
+    }
+
+    async fn terminate(&self) -> RuntimeResult<()> {
+        let mut t = self.terminated.lock().await;
+        if *t {
+            return Ok(());
+        }
+        let url = format!("{}/sandboxes/{}", self.base_url, self.sandbox_id);
+        let req = self.http.delete(&url);
+        let req = match &self.api_key {
+            Some(k) => req.header("OPEN-SANDBOX-API-KEY", k),
+            None => req,
+        };
+        match req.send().await {
+            Ok(resp)
+                if resp.status().is_success()
+                    || resp.status() == reqwest::StatusCode::NOT_FOUND =>
+            {
+                *t = true;
+                debug!(
+                    stage = "opensandbox_terminated",
+                    sandbox_id = %self.sandbox_id,
+                    "OpenSandbox sandbox terminated"
+                );
+                Ok(())
+            }
+            Ok(resp) => Err(RuntimeError::Backend(format!(
+                "delete sandbox failed: {}",
+                resp.status()
+            ))),
+            Err(e) => Err(RuntimeError::Unreachable(format!("delete sandbox: {e}"))),
+        }
+    }
+}
+
+/// Parse the execd `/command` SSE stream into [`ExecEvent`]s.
+///
+/// Recognised event types per the execd spec: `stdout`, `stderr`,
+/// `execution_complete`, `error`. Others are ignored. The stream
+/// always ends with an `Exit` event so the caller's loop terminates;
+/// if the upstream stream closes without one, we synthesize `Exit
+/// { code: -1 }`.
+fn bridge_sse_to_exec_events(
+    mut byte_stream: impl Stream<Item = reqwest::Result<Bytes>> + Send + Unpin + 'static,
+) -> std::pin::Pin<Box<dyn Stream<Item = ExecEvent> + Send>> {
+    let (tx, rx) = mpsc::channel::<ExecEvent>(32);
+    crate::compat::spawn_detached(async move {
+        let mut sse = SseBuffer::new();
+        let mut exit_emitted = false;
+        while let Some(chunk_result) = byte_stream.next().await {
+            let chunk = match chunk_result {
+                Ok(c) => c,
+                Err(e) => {
+                    warn!(error = %e, "OpenSandbox SSE stream error");
+                    break;
+                }
+            };
+            sse.extend(&chunk);
+            for event in sse.extract_complete_events() {
+                let Some((event_type, text, exit_code)) = parse_execd_event(&event) else {
+                    continue;
+                };
+                let mapped = match event_type.as_str() {
+                    "stdout" => ExecEvent::Stdout(Bytes::from(text.unwrap_or_default())),
+                    "stderr" => ExecEvent::Stderr(Bytes::from(text.unwrap_or_default())),
+                    "execution_complete" => {
+                        exit_emitted = true;
+                        ExecEvent::Exit {
+                            code: exit_code.unwrap_or(0),
+                            signal: None,
+                        }
+                    }
+                    "error" => {
+                        exit_emitted = true;
+                        error!(
+                            stage = "opensandbox_exec_error",
+                            text = ?text,
+                            "Execd reported error"
+                        );
+                        ExecEvent::Exit {
+                            code: -1,
+                            signal: None,
+                        }
+                    }
+                    _ => continue,
+                };
+                if tx.send(mapped).await.is_err() {
+                    return;
+                }
+            }
+        }
+        if !exit_emitted {
+            let _ = tx
+                .send(ExecEvent::Exit {
+                    code: -1,
+                    signal: None,
+                })
+                .await;
+        }
+    });
+    let mut rx = rx;
+    Box::pin(futures_util::stream::poll_fn(move |cx| rx.poll_recv(cx)))
+}
+
+/// Best-effort parser for one SSE event payload. Returns
+/// (event_type, optional text, optional exit_code) when the payload
+/// is a JSON object with a `type` field.
+fn parse_execd_event(event: &[u8]) -> Option<(String, Option<String>, Option<i32>)> {
+    let s = std::str::from_utf8(event).ok()?;
+    for line in s.lines() {
+        let Some(data) = line.strip_prefix("data:") else {
+            continue;
+        };
+        let data = data.trim();
+        if data.is_empty() {
+            continue;
+        }
+        let json: serde_json::Value = serde_json::from_str(data).ok()?;
+        let event_type = json.get("type")?.as_str()?.to_string();
+        let text = json.get("text").and_then(|v| v.as_str()).map(String::from);
+        // execd doesn't always carry exit code; check `data.code` or
+        // `exitCode` if present.
+        let exit_code = json
+            .get("data")
+            .and_then(|d| d.get("code"))
+            .and_then(|v| v.as_i64())
+            .or_else(|| json.get("exitCode").and_then(|v| v.as_i64()))
+            .map(|v| v as i32);
+        return Some((event_type, text, exit_code));
+    }
+    None
+}
diff --git a/src/runtimes/passthrough.rs b/src/runtimes/passthrough.rs
new file mode 100644
index 0000000..c2c1412
--- /dev/null
+++ b/src/runtimes/passthrough.rs
@@ -0,0 +1,107 @@
+//! Passthrough runtime: defer shell execution off the Hadrian process.
+//!
+//! Two modes share this adapter because both skip server-side execution
+//! and differ only in which party fulfills the shell call:
+//!
+//! - [`PassthroughMode::OpenAiContainer`] (config `passthrough_openai`) —
+//!   forward the native `shell` tool spec to OpenAI; the model runs the
+//!   call in OpenAI's hosted container. Only meaningful when the
+//!   upstream provider is OpenAI (GPT-5.2+ with the built-in `shell`
+//!   tool type).
+//! - [`PassthroughMode::ApiClient`] (config `client_passthrough`) — the
+//!   API client fulfills shell calls itself. Models with native shell
+//!   support (OpenAI) emit `shell_call` items; non-OpenAI providers get
+//!   the function-mode rewrite and emit `function_call` items with
+//!   `name="shell"`. Either way the orchestrator skips server-side
+//!   execution and the call passes through.
+//!
+//! In both modes `start_session` returns [`RuntimeError::Passthrough`]
+//! so the orchestrator knows not to invoke local execution. The mode
+//! choice is exposed via [`RuntimeCapabilities::client_executes`] so
+//! the preprocessing layer (`routes/execution.rs`) can keep OpenAI's
+//! native `shell` spec intact for `ApiClient` mode the same way it does
+//! for `OpenAiContainer` mode.
+
+use async_trait::async_trait;
+
+use super::{
+    RuntimeCapabilities, RuntimeError, RuntimeResult, SessionHandle, SessionSpec, ShellRuntime,
+};
+
+/// Which party fulfills shell calls when execution is deferred off
+/// Hadrian. See the module docs for the rationale behind each variant.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub enum PassthroughMode {
+    /// OpenAI's Responses-API hosted container runs the call.
+    #[default]
+    OpenAiContainer,
+    /// The API client fulfills the call locally (OpenAI's "local shell"
+    /// mode, generalized to all providers).
+    ApiClient,
+}
+
+/// Pass-through runtime for both `passthrough_openai` and
+/// `client_passthrough` config modes. The mode it was constructed with
+/// only affects [`capabilities()`](ShellRuntime::capabilities); the
+/// execution surface is identical (start_session is a no-op that asks
+/// the orchestrator to skip local execution).
+#[derive(Debug, Default, Clone, Copy)]
+pub struct PassthroughRuntime {
+    mode: PassthroughMode,
+}
+
+impl PassthroughRuntime {
+    /// Construct a passthrough runtime for OpenAI's hosted container.
+    pub const fn for_openai_container() -> Self {
+        Self {
+            mode: PassthroughMode::OpenAiContainer,
+        }
+    }
+
+    /// Construct a passthrough runtime where the API client fulfills
+    /// shell calls itself.
+    pub const fn for_api_client() -> Self {
+        Self {
+            mode: PassthroughMode::ApiClient,
+        }
+    }
+
+    pub fn mode(&self) -> PassthroughMode {
+        self.mode
+    }
+}
+
+#[async_trait]
+impl ShellRuntime for PassthroughRuntime {
+    fn capabilities(&self) -> RuntimeCapabilities {
+        match self.mode {
+            PassthroughMode::OpenAiContainer => RuntimeCapabilities::passthrough_upstream(),
+            PassthroughMode::ApiClient => RuntimeCapabilities::passthrough_client(),
+        }
+    }
+
+    async fn start_session(&self, _spec: SessionSpec) -> RuntimeResult<SessionHandle> {
+        Err(RuntimeError::Passthrough)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn openai_mode_advertises_upstream_execution() {
+        let rt = PassthroughRuntime::for_openai_container();
+        let caps = rt.capabilities();
+        assert!(caps.passthrough_only);
+        assert!(!caps.client_executes);
+    }
+
+    #[test]
+    fn client_mode_advertises_client_execution() {
+        let rt = PassthroughRuntime::for_api_client();
+        let caps = rt.capabilities();
+        assert!(caps.passthrough_only);
+        assert!(caps.client_executes);
+    }
+}
diff --git a/src/services/background_executor.rs b/src/services/background_executor.rs
new file mode 100644
index 0000000..65bd1cf
--- /dev/null
+++ b/src/services/background_executor.rs
@@ -0,0 +1,560 @@
+//! Executor for background responses claimed by the worker.
+//!
+//! The worker (`jobs::background_responses`) calls
+//! [`execute_persisted_response`] once it claims a queued row. The
+//! function reconstructs the request, routes it through the same
+//! provider plumbing the synchronous handler uses, then wraps the
+//! streaming response with the shared `apply_streaming_pipeline`
+//! (output guardrails + server-executed tool loop + persister) and
+//! drains the body. Skills referenced on the request are resolved at
+//! claim time from the persisted `org_id` so each shell session boots
+//! with the same mounts the foreground caller asked for.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use chrono::Utc;
+use futures_util::StreamExt;
+use thiserror::Error;
+use tracing::{error, info, warn};
+
+use crate::{
+    AppState,
+    api_types::CreateResponsesPayload,
+    db::repos::{ResponseCompletion, ResponseRecord, ResponseStatus},
+    routes::execution::{ExecutionResult, ResponsesExecutor, execute_with_fallback},
+    routing::{resolver, route_models_extended},
+    services::{
+        ResponsesStore,
+        responses_pipeline::{
+            PipelinePrincipal, apply_streaming_pipeline, resolve_and_inject_skills,
+        },
+    },
+};
+
+#[derive(Debug, Error)]
+pub enum BackgroundExecuteError {
+    #[error("payload deserialization failed: {0}")]
+    BadPayload(String),
+    #[error("model routing failed: {0}")]
+    Routing(String),
+    #[error("provider resolution failed: {0}")]
+    Resolution(String),
+    #[error("provider execution failed: {0}")]
+    Execution(String),
+    #[error("response store missing — background mode requires persistence")]
+    NoStore,
+}
+
+impl BackgroundExecuteError {
+    /// Classify whether this failure could plausibly succeed on a
+    /// retry. Configuration-shaped failures (bad payload, missing
+    /// provider config) won't get better; transport / provider /
+    /// network problems often will.
+    pub fn is_transient(&self) -> bool {
+        match self {
+            // Provider / network / streaming — the same row may
+            // succeed if we wait and try again.
+            Self::Execution(_) => true,
+            // Everything else is a config / structural issue: the
+            // payload won't deserialise differently, the routing
+            // won't resolve a missing provider, etc.
+            Self::BadPayload(_) | Self::Routing(_) | Self::Resolution(_) | Self::NoStore => false,
+        }
+    }
+}
+
+/// True when the request carries a `shell` tool (either as the native
+/// `{"type": "shell"}` form or the post-`preprocess_shell_tools`
+/// function-mode rewrite). Used to gate `input_file` staging — staging
+/// files into `/mnt/data` for a request that can't run shell commands
+/// is just wasted I/O.
+/// Locate the first `ShellTool` in the request payload and return its
+/// (optional) `environment` block. Returns `None` when the payload
+/// doesn't carry a typed `shell` tool — `Function`-rewritten tools
+/// have no `environment` field by construction.
+fn first_shell_environment(
+    payload: &crate::api_types::CreateResponsesPayload,
+) -> Option<&crate::api_types::responses::ShellEnvironment> {
+    payload
+        .tools
+        .as_ref()?
+        .iter()
+        .find_map(|t| t.as_shell())
+        .and_then(|s| s.environment.as_ref())
+}
+
+/// Local copy of the foreground helper. Avoids leaking a chat.rs
+/// helper through `pub`. See `routes/api/chat.rs::skills_have_same_identity`.
+fn skills_have_same_identity_bg(
+    a: &crate::api_types::RequestSkill,
+    b: &crate::api_types::RequestSkill,
+) -> bool {
+    use crate::api_types::RequestSkill;
+    match (a, b) {
+        (RequestSkill::SkillReference(x), RequestSkill::SkillReference(y)) => {
+            x.skill_id == y.skill_id
+        }
+        (RequestSkill::Inline(x), RequestSkill::Inline(y)) => x.name == y.name,
+        _ => false,
+    }
+}
+
+fn shell_tool_requested(payload: &crate::api_types::CreateResponsesPayload) -> bool {
+    let Some(tools) = payload.tools.as_ref() else {
+        return false;
+    };
+    tools.iter().any(|t| {
+        t.is_shell()
+            || matches!(
+                t,
+                crate::api_types::responses::ResponsesToolDefinition::Function(f)
+                    if f.name == "shell"
+            )
+    })
+}
+
+/// Run a claimed response to completion.
+///
+/// `record` must already be in `in_progress` status (claimed via
+/// `ResponsesRepo::claim_queued`). The function returns once the
+/// streaming response has been fully consumed; the persister updates
+/// the row to its terminal status in its own spawned task before this
+/// function exits.
+pub async fn execute_persisted_response(
+    state: AppState,
+    record: ResponseRecord,
+) -> Result<(), BackgroundExecuteError> {
+    let store = state
+        .responses_store
+        .clone()
+        .ok_or(BackgroundExecuteError::NoStore)?;
+
+    info!(
+        response_id = %record.id,
+        model = %record.model,
+        "Background worker executing claimed response"
+    );
+
+    // Reconstruct the payload. We force `stream = true` so the
+    // persister captures events; the client tails them via
+    // GET /v1/responses/{id}?stream=true (matching OpenAI's spec for
+    // resuming a Responses-API stream).
+    let mut payload: CreateResponsesPayload =
+        serde_json::from_value(record.request_payload.clone()).map_err(|e| {
+            BackgroundExecuteError::BadPayload(format!("invalid request_payload: {e}"))
+        })?;
+    payload.stream = true;
+    // `background` flag stays — the executor inspects it nowhere in
+    // the inner pipeline, but downstream tooling can read it.
+
+    // Route the model.
+    let routed = route_models_extended(
+        payload.model.as_deref(),
+        payload.models.as_deref(),
+        &state.config.providers,
+    )
+    .map_err(|e| BackgroundExecuteError::Routing(e.to_string()))?;
+
+    let resolved = resolver::resolve_to_provider(
+        routed,
+        state.db.as_ref(),
+        state.cache.as_ref(),
+        state.secrets.as_ref(),
+        None, // background runs without an auth extension; principal already on the row
+    )
+    .await
+    .map_err(|e| BackgroundExecuteError::Resolution(e.to_string()))?;
+
+    let provider_name = resolved.provider_name;
+    let provider_config = resolved.provider_config;
+    let model_name = resolved.model;
+    payload.model = Some(model_name.clone());
+
+    // Re-validate the request's shell `environment` overrides against
+    // the current operator limits. Foreground already checked at
+    // admission time, but the operator config may have tightened
+    // between admission and execution — re-checking ensures we never
+    // launch a session that exceeds the current envelope. Misconfig
+    // is permanent for this row (`BadPayload`), not retried.
+    //
+    // We resolve this before skills so container-bound skills can be
+    // merged into `payload.skills` ahead of skill resolution.
+    let resolved_shell_env_pre = {
+        let request_env = first_shell_environment(&payload);
+        crate::services::shell_tool::resolve_shell_environment(
+            request_env,
+            &state.config.features.server_tools.shell_limits,
+            &state.config.features.containers,
+        )
+        .map_err(|e| {
+            BackgroundExecuteError::BadPayload(format!("shell environment rejected: {e}"))
+        })?
+    };
+
+    // Union container-bound skills into `payload.skills` (matches
+    // OpenAI's spec where skills bind to the container). We consider
+    // both explicit `container_reference` and implicit
+    // `previous_response_id` chaining.
+    if let Some(svc) = state.containers_service.as_ref() {
+        let candidate_container_id: Option<String> = match (
+            resolved_shell_env_pre.referenced_container_id.as_deref(),
+            payload.previous_response_id.as_deref(),
+        ) {
+            (Some(referenced), _) => Some(referenced.to_string()),
+            (None, Some(prev)) => store
+                .get(prev, record.org_id)
+                .await
+                .ok()
+                .and_then(|r| r.container_id),
+            _ => None,
+        };
+        if let Some(cid) = candidate_container_id
+            && let Ok(c) = svc.get_container(&cid, record.org_id).await
+            && matches!(c.status, crate::db::repos::ContainerStatus::Active)
+            && let Some(json) = c.skill_ids_json.as_deref()
+            && let Ok(bound) = serde_json::from_str::<Vec<crate::api_types::RequestSkill>>(json)
+            && !bound.is_empty()
+        {
+            let mut merged = payload.skills.clone().unwrap_or_default();
+            for incoming in bound {
+                let dup = merged
+                    .iter()
+                    .any(|existing| skills_have_same_identity_bg(existing, &incoming));
+                if !dup {
+                    merged.push(incoming);
+                }
+            }
+            payload.skills = Some(merged);
+        }
+    }
+
+    // Resolve skills using the org from the persisted row. Mirrors the
+    // foreground path: SKILL.md is prepended to instructions and the
+    // returned mounts are threaded into apply_streaming_pipeline so
+    // the shell runtime materializes the files when a shell call boots
+    // a session.
+    let mounted_skills = resolve_and_inject_skills(&state, &mut payload, Some(record.org_id))
+        .await
+        .map_err(|e| BackgroundExecuteError::BadPayload(format!("skill resolution failed: {e}")))?;
+
+    // Final resolved env (re-do after potential payload changes).
+    let resolved_shell_env = {
+        let request_env = first_shell_environment(&payload);
+        crate::services::shell_tool::resolve_shell_environment(
+            request_env,
+            &state.config.features.server_tools.shell_limits,
+            &state.config.features.containers,
+        )
+        .map_err(|e| {
+            BackgroundExecuteError::BadPayload(format!("shell environment rejected: {e}"))
+        })?
+    };
+
+    // Resolve input_file parts the request asked us to stage into
+    // /mnt/data. We only do the work if the request actually carries
+    // a shell tool — files for non-shell requests would just sit in
+    // memory unused. Errors bubble up as `BadPayload` so the row
+    // ends in `failed` with the resolver's diagnostic preserved.
+    let staged_input_files = if shell_tool_requested(&payload) {
+        // Scope file_id references to the row's owner so a background
+        // response can't stage another tenant's Files-API uploads.
+        let staging_owner =
+            crate::db::repos::ResponseOwner::from_parts(record.owner_type, record.owner_id);
+        crate::services::input_file_staging::stage_input_files(
+            &state,
+            &payload,
+            &state.config.features.containers,
+            Some(staging_owner),
+        )
+        .await
+        .map_err(|e| {
+            BackgroundExecuteError::BadPayload(format!("input_file staging failed: {e}"))
+        })?
+    } else {
+        Vec::new()
+    };
+
+    // Gateway-side compaction for non-OpenAI providers. Best-effort:
+    // an error here means the original payload still flows through.
+    if let Err(e) =
+        crate::services::compactor::apply_gateway_compaction(&state, &provider_config, &mut payload)
+            .await
+    {
+        tracing::warn!(error = %e, "Background gateway compaction failed; continuing with original payload");
+    }
+
+    // Sovereignty requirements are checked at request-creation time
+    // for the foreground path; in the background we trust the row.
+    let exec_result = execute_with_fallback::<ResponsesExecutor>(
+        &state,
+        provider_name.clone(),
+        provider_config.clone(),
+        model_name.clone(),
+        payload.clone(),
+        None,
+    )
+    .await
+    .map_err(|e| BackgroundExecuteError::Execution(format!("{e:?}")))?;
+
+    let ExecutionResult { response, .. } = exec_result;
+
+    // Cancellation: use the row's in-process watch channel directly.
+    // The cross-replica case is handled by a single replica-wide
+    // poller (`jobs::responses_cancel_poller`) that periodically
+    // queries `WHERE status='cancelled' AND id IN (active set)` and
+    // trips the matching sender — one DB round-trip per poll cycle
+    // no matter how many backgrounds are in-flight. We use
+    // `register_external_execution` so the row's id appears in the
+    // active set even when the row was created on a different
+    // replica (before a restart, for instance) and there's no local
+    // `create()` sender to inherit.
+    let cancel_rx = store.register_external_execution(&record.id).await;
+
+    // Reconstruct principal from the persisted row so the shared
+    // pipeline applies guardrails / file_search ACLs / shell usage
+    // attribution using the same identity that submitted the request.
+    let principal = PipelinePrincipal {
+        api_key_id: record.api_key_id,
+        user_id: record.user_id,
+        org_id: Some(record.org_id),
+        project_id: record.project_id,
+        team_id: None, // teams aren't currently stored on the row
+        service_account_id: record.service_account_id,
+    };
+
+    // Reconstruct the response owner from the persisted row so the
+    // container-persistence layer attributes files to the same scope
+    // the foreground caller used.
+    let containers_owner = match record.owner_type {
+        crate::db::repos::ResponseOwnerType::Organization => {
+            crate::db::repos::ResponseOwner::Organization(record.owner_id)
+        }
+        crate::db::repos::ResponseOwnerType::Team => {
+            crate::db::repos::ResponseOwner::Team(record.owner_id)
+        }
+        crate::db::repos::ResponseOwnerType::Project => {
+            crate::db::repos::ResponseOwner::Project(record.owner_id)
+        }
+        crate::db::repos::ResponseOwnerType::User => {
+            crate::db::repos::ResponseOwner::User(record.owner_id)
+        }
+        crate::db::repos::ResponseOwnerType::ServiceAccount => {
+            crate::db::repos::ResponseOwner::ServiceAccount(record.owner_id)
+        }
+    };
+
+    // Explicit `container_reference` wins over implicit chaining.
+    // Foreground validates at admission and returns 400; the row that
+    // reached here has already been admitted, so an explicit reference
+    // failing now is fatal for this run (`BadPayload`, not retried).
+    let container_id_hint = if let Some(ref referenced) = resolved_shell_env.referenced_container_id
+    {
+        let svc = state.containers_service.as_ref().ok_or_else(|| {
+            BackgroundExecuteError::BadPayload(
+                "container_reference requires persistence to be enabled".into(),
+            )
+        })?;
+        match svc.get_container(referenced, record.org_id).await {
+            Ok(c) if matches!(c.status, crate::db::repos::ContainerStatus::Active) => {
+                Some(referenced.clone())
+            }
+            Ok(c) => {
+                return Err(BackgroundExecuteError::BadPayload(format!(
+                    "container '{}' is in status '{}' and cannot be referenced",
+                    referenced,
+                    c.status.as_str()
+                )));
+            }
+            Err(_) => {
+                return Err(BackgroundExecuteError::BadPayload(format!(
+                    "container '{}' was not found in this organization",
+                    referenced
+                )));
+            }
+        }
+    } else {
+        // Implicit chaining via `previous_response_id`. Any
+        // non-active prior container silently falls back to a fresh
+        // one rather than erroring.
+        match (
+            payload.previous_response_id.as_deref(),
+            state.containers_service.as_ref(),
+        ) {
+            (Some(prev_id), Some(containers_svc)) => {
+                let prev = store
+                    .get(prev_id, record.org_id)
+                    .await
+                    .ok()
+                    .and_then(|r| r.container_id);
+                match prev {
+                    Some(cid) => match containers_svc.get_container(&cid, record.org_id).await {
+                        Ok(c) if matches!(c.status, crate::db::repos::ContainerStatus::Active) => {
+                            Some(cid)
+                        }
+                        _ => None,
+                    },
+                    None => None,
+                }
+            }
+            _ => None,
+        }
+    };
+
+    // Build a `UsageLogEntry` so model-token usage from this
+    // background run lands in the per-principal usage ledger. Without
+    // this the row's `usage` field gets persisted but no
+    // `usage_records` row is written — which means cost reports and
+    // budget enforcement diverge from reality for background-mode
+    // workloads. Mirrors what `build_streaming_usage_entry` does for
+    // the foreground path, but sources principal fields from the
+    // persisted row instead of the live auth extension.
+    let usage_entry = crate::models::UsageLogEntry {
+        request_id: uuid::Uuid::new_v4().to_string(),
+        api_key_id: record.api_key_id,
+        user_id: record.user_id,
+        org_id: Some(record.org_id),
+        project_id: record.project_id,
+        team_id: None,
+        service_account_id: record.service_account_id,
+        model: model_name.clone(),
+        provider: provider_name.clone(),
+        input_tokens: 0,
+        output_tokens: 0,
+        cost_microcents: None,
+        http_referer: None,
+        request_at: chrono::Utc::now(),
+        streamed: true,
+        cached_tokens: 0,
+        reasoning_tokens: 0,
+        finish_reason: None,
+        latency_ms: None,
+        cancelled: false,
+        status_code: None,
+        pricing_source: crate::pricing::CostPricingSource::None,
+        image_count: None,
+        audio_seconds: None,
+        character_count: None,
+        provider_source: None,
+        record_type: "model".to_string(),
+        tool_name: None,
+        tool_query: None,
+        tool_url: None,
+        tool_bytes_fetched: None,
+        tool_results_count: None,
+        tool_runtime_seconds: None,
+        tool_exit_code: None,
+    };
+
+    let provider_name_clone = provider_name.clone();
+    let model_name_clone = model_name.clone();
+    let wrapped = apply_streaming_pipeline(
+        &state,
+        &payload,
+        provider_name,
+        provider_config,
+        model_name,
+        principal,
+        mounted_skills,
+        staged_input_files,
+        Some(containers_owner),
+        container_id_hint,
+        resolved_shell_env,
+        // Background has no HTTP request_id; use the response_id for
+        // audit-log correlation so events tied to this run can be
+        // grouped consistently.
+        Some(record.id.clone()),
+        response,
+        Some(crate::services::responses_pipeline::PersistenceHandle {
+            response_id: record.id.clone(),
+            org_id: record.org_id,
+            initial_sequence_number: record.last_sequence_number,
+            cancel_rx,
+        }),
+    );
+
+    // Wrap the response with the usage-tracking stream so token deltas
+    // flow into `state.usage_buffer` exactly the way they do for
+    // foreground streaming. The wrap also injects calculated cost into
+    // the SSE chunks, but in background mode no client is reading them
+    // — the persister is the only downstream consumer, and it already
+    // captures the upstream's verbatim `usage` payload.
+    let wrapped =
+        crate::providers::inject_cost_into_response(crate::providers::CostInjectionParams {
+            response: wrapped,
+            provider: &provider_name_clone,
+            model: &model_name_clone,
+            pricing: &state.pricing,
+            db: state.db.as_ref(),
+            usage_entry: Some(usage_entry),
+            #[cfg(feature = "server")]
+            task_tracker: Some(&state.task_tracker),
+            #[cfg(feature = "server")]
+            usage_drain: Some(&state.usage_drain),
+            max_response_body_bytes: state.config.server.max_response_body_bytes,
+            streaming_idle_timeout_secs: state.config.server.streaming_idle_timeout_secs,
+            validation_config: &state.config.observability.response_validation,
+            response_type: crate::validation::ResponseType::ResponseStream,
+        })
+        .await;
+
+    // Drain the body silently. The persister's internal spawned task
+    // handles event log writes + the terminal row update.
+    let (_parts, body) = wrapped.into_parts();
+    let mut stream = body.into_data_stream();
+    while let Some(chunk) = stream.next().await {
+        if let Err(e) = chunk {
+            warn!(
+                response_id = %record.id,
+                error = %e,
+                "Stream error during background drain"
+            );
+            // Do NOT write a terminal state here. A stream error is a
+            // transient `Execution` failure that `run_with_retry` will
+            // re-attempt; writing `failed` + `completed_at` now would
+            // flip the row to a terminal state mid-retry, so a polling
+            // client would see `failed` and stop watching before the
+            // retry has a chance to succeed. The terminal write is
+            // owned by `mark_background_failure`, which runs only after
+            // retries are exhausted.
+            return Err(BackgroundExecuteError::Execution(e.to_string()));
+        }
+    }
+
+    info!(response_id = %record.id, "Background response drain complete");
+    Ok(())
+}
+
+/// Mark a claimed row as `failed` with a structured error payload.
+/// Called by the worker when execute_persisted_response returns Err.
+pub async fn mark_background_failure(
+    store: &ResponsesStore,
+    response_id: &str,
+    org_id: uuid::Uuid,
+    err: &BackgroundExecuteError,
+) {
+    let error_payload = serde_json::json!({
+        "code": match err {
+            BackgroundExecuteError::BadPayload(_) => "bad_payload",
+            BackgroundExecuteError::Routing(_) => "routing_failed",
+            BackgroundExecuteError::Resolution(_) => "provider_resolution_failed",
+            BackgroundExecuteError::Execution(_) => "execution_failed",
+            BackgroundExecuteError::NoStore => "internal_error",
+        },
+        "message": err.to_string(),
+    });
+    if let Err(e) = store
+        .update_within_org(
+            response_id,
+            org_id,
+            ResponseCompletion {
+                status: Some(ResponseStatus::Failed),
+                completed_at: Some(Utc::now()),
+                error: Some(error_payload),
+                ..Default::default()
+            },
+        )
+        .await
+    {
+        error!(error = %e, response_id, "Failed to mark background row as failed");
+    }
+}
diff --git a/src/services/compactor.rs b/src/services/compactor.rs
new file mode 100644
index 0000000..b161584
--- /dev/null
+++ b/src/services/compactor.rs
@@ -0,0 +1,531 @@
+//! Gateway-side context compactor for non-OpenAI providers.
+//!
+//! OpenAI's `context_management = [{type: "compaction", …}]` directive
+//! is forwarded verbatim when the upstream is OpenAI or Azure OpenAI
+//! (those providers run server-side compaction natively). For every
+//! other provider — Anthropic, Bedrock, Vertex, Test — Hadrian runs a
+//! compactor here, before the request reaches the upstream call.
+//!
+//! Two strategies:
+//!
+//! - **`truncate`** (free, deterministic): drop the oldest non-system
+//!   items until the rolling token estimate falls under
+//!   `compact_threshold`. Reasoning items are folded in with messages
+//!   (they aren't system context). Always keeps the most recent
+//!   `keep_recent_items` items intact.
+//! - **`llm`** (extra inference call): summarise the items that would
+//!   otherwise be dropped via a single call to the same provider/model,
+//!   then replace them with one `system`-role message carrying the
+//!   summary. Higher signal preservation; costs one extra round trip.
+//!
+//! The caller picks the strategy via the Hadrian-extension `strategy`
+//! field on the compaction directive (falling back to
+//! `[features.responses.compaction].default_strategy`).
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use thiserror::Error;
+use tracing::{debug, info, warn};
+
+use crate::{
+    AppState,
+    api_types::{
+        self,
+        responses::{
+            CompactionStrategy, ContextManagementItem, CreateResponsesPayload, EasyInputMessage,
+            EasyInputMessageContent, EasyInputMessageRole, ResponsesInput, ResponsesInputItem,
+        },
+    },
+    config::{ProviderConfig, ResponsesCompactionStrategy},
+    routes::execution::ProviderExecutor,
+};
+
+/// Errors raised by the compactor. Most are non-fatal — the caller
+/// should log + skip compaction and let the original payload through
+/// rather than failing the request, because an oversize-but-uncompacted
+/// payload is still likely to work (the provider may itself truncate
+/// or surface a clear context-window error).
+#[derive(Debug, Error)]
+pub enum CompactionError {
+    #[error("summarisation provider call failed: {0}")]
+    SummariseCall(String),
+    #[error("summarisation response was empty or unparseable")]
+    EmptySummary,
+}
+
+/// Public entry point. Mutates `payload.input` in place when
+/// compaction runs; returns `Ok(false)` otherwise. Always returns
+/// `Ok(_)` for foreground use even when compaction misfires — the
+/// caller logs and continues. Errors are reserved for cases where the
+/// caller asked explicitly for compaction and the operator has it
+/// disabled.
+pub async fn apply_gateway_compaction(
+    state: &AppState,
+    provider_config: &ProviderConfig,
+    payload: &mut CreateResponsesPayload,
+) -> Result<bool, CompactionError> {
+    let compaction_cfg = &state.config.features.responses.compaction;
+    if !compaction_cfg.enabled {
+        return Ok(false);
+    }
+    if provider_has_native_compaction(provider_config) {
+        debug!(
+            stage = "compaction_skipped_native",
+            "Provider supports native compaction; forwarding directive verbatim"
+        );
+        return Ok(false);
+    }
+
+    // Pull the directive (and its Hadrian-extension fields) off the
+    // payload. We leave `context_management` in place so the caller
+    // sees the same shape they sent — providers without native support
+    // ignore it.
+    let Some(directive) = payload.context_management.as_ref().and_then(|items| {
+        items.iter().find_map(|item| match item {
+            ContextManagementItem::Compaction {
+                compact_threshold,
+                strategy,
+                prompt,
+            } => Some((
+                compact_threshold.map(|f| f as u32),
+                *strategy,
+                prompt.clone(),
+            )),
+            ContextManagementItem::Other => None,
+        })
+    }) else {
+        return Ok(false);
+    };
+
+    let threshold = directive
+        .0
+        .unwrap_or(compaction_cfg.default_threshold_tokens);
+    let strategy = match directive.1 {
+        Some(CompactionStrategy::Llm) => ResponsesCompactionStrategy::Llm,
+        Some(CompactionStrategy::Truncate) => ResponsesCompactionStrategy::Truncate,
+        None => compaction_cfg.default_strategy,
+    };
+    let prompt_override = directive.2;
+
+    // Cheap pre-check: only act if the rolling estimate exceeds the
+    // threshold. Avoids paying the LLM round-trip on short
+    // conversations that happened to advertise compaction.
+    let items = match payload.input.as_mut() {
+        Some(ResponsesInput::Items(items)) => items,
+        // Plain-text input fits in one message and never needs compaction.
+        Some(ResponsesInput::Text(_)) | None => return Ok(false),
+    };
+    let estimated = estimate_tokens(items);
+    if estimated <= threshold {
+        debug!(
+            stage = "compaction_skipped_under_threshold",
+            estimated_tokens = estimated,
+            threshold,
+            "Estimated token count is under threshold; no compaction needed"
+        );
+        return Ok(false);
+    }
+
+    let keep = compaction_cfg.keep_recent_items;
+    let split_at = items.len().saturating_sub(keep);
+    if split_at == 0 {
+        // Recent-window already covers the whole conversation; nothing
+        // can be dropped while preserving the user's most recent intent.
+        return Ok(false);
+    }
+
+    let dropped: Vec<ResponsesInputItem> = items.drain(..split_at).collect();
+    let surviving = std::mem::take(items);
+
+    let replacement = match strategy {
+        ResponsesCompactionStrategy::Truncate => truncate_replacement(&dropped),
+        ResponsesCompactionStrategy::Llm => {
+            let prompt = prompt_override
+                .filter(|p| !p.trim().is_empty())
+                .unwrap_or_else(|| compaction_cfg.default_prompt.clone());
+            match llm_replacement(state, provider_config, payload, &dropped, &prompt).await {
+                Ok(text) => Some(make_summary_item(&text)),
+                Err(e) => {
+                    warn!(
+                        stage = "compaction_llm_failed",
+                        error = %e,
+                        "LLM compaction failed; falling back to truncate"
+                    );
+                    truncate_replacement(&dropped)
+                }
+            }
+        }
+    };
+
+    let mut next = Vec::with_capacity(surviving.len() + 1);
+    if let Some(item) = replacement {
+        next.push(item);
+    }
+    next.extend(surviving);
+    payload.input = Some(ResponsesInput::Items(next));
+
+    info!(
+        stage = "compaction_applied",
+        strategy = ?strategy,
+        dropped = dropped.len(),
+        kept = keep,
+        estimated_tokens_before = estimated,
+        threshold,
+        "Applied gateway-side compaction"
+    );
+    Ok(true)
+}
+
+fn provider_has_native_compaction(cfg: &ProviderConfig) -> bool {
+    match cfg {
+        ProviderConfig::OpenAi(_) => true,
+        #[cfg(feature = "provider-azure")]
+        ProviderConfig::AzureOpenAi(_) => true,
+        ProviderConfig::Anthropic(_) => false,
+        #[cfg(feature = "provider-bedrock")]
+        ProviderConfig::Bedrock(_) => false,
+        #[cfg(feature = "provider-vertex")]
+        ProviderConfig::Vertex(_) => false,
+        ProviderConfig::Test(_) => false,
+    }
+}
+
+/// Rough token estimate over a slice of input items. Mirrors the
+/// guardrails streaming heuristic (1 token ≈ 4 chars).
+pub(crate) fn estimate_tokens(items: &[ResponsesInputItem]) -> u32 {
+    let chars: usize = items.iter().map(item_chars).sum();
+    chars.div_ceil(4) as u32
+}
+
+fn item_chars(item: &ResponsesInputItem) -> usize {
+    match item {
+        ResponsesInputItem::EasyMessage(m) => message_chars(&m.content),
+        ResponsesInputItem::MessageItem(m) => {
+            m.content.iter().map(content_item_chars).sum::<usize>()
+        }
+        ResponsesInputItem::FunctionCall(f) => f.name.len() + f.arguments.len(),
+        ResponsesInputItem::FunctionCallOutput(f) => f.output.len(),
+        ResponsesInputItem::Reasoning(r) => {
+            let summary_chars: usize = r.summary.iter().map(|s| s.text.len()).sum();
+            let content_chars: usize = r
+                .content
+                .as_ref()
+                .map(|v| v.iter().map(|t| t.text.len()).sum())
+                .unwrap_or(0);
+            summary_chars + content_chars
+        }
+        ResponsesInputItem::OutputMessage(_)
+        | ResponsesInputItem::OutputFunctionCall(_)
+        | ResponsesInputItem::WebSearchCall(_)
+        | ResponsesInputItem::FileSearchCall(_)
+        | ResponsesInputItem::ShellCall(_)
+        | ResponsesInputItem::ShellCallOutput(_)
+        | ResponsesInputItem::McpListTools(_)
+        | ResponsesInputItem::McpCall(_)
+        | ResponsesInputItem::McpApprovalRequest(_)
+        | ResponsesInputItem::McpApprovalResponse(_)
+        | ResponsesInputItem::ToolSearchCall(_)
+        | ResponsesInputItem::ToolSearchOutput(_)
+        | ResponsesInputItem::Compaction(_)
+        | ResponsesInputItem::ImageGeneration(_) => 64, // structural marker
+    }
+}
+
+fn message_chars(c: &EasyInputMessageContent) -> usize {
+    match c {
+        EasyInputMessageContent::Text(t) => t.len(),
+        EasyInputMessageContent::Parts(parts) => {
+            parts.iter().map(content_item_chars).sum::<usize>()
+        }
+    }
+}
+
+fn content_item_chars(item: &api_types::responses::ResponseInputContentItem) -> usize {
+    use api_types::responses::ResponseInputContentItem;
+    match item {
+        ResponseInputContentItem::InputText { text, .. } => text.len(),
+        // Image / file / audio bytes don't add to the rolling text
+        // estimate. The provider charges for them via vision tokens
+        // we can't see here, but compaction is text-only.
+        ResponseInputContentItem::InputImage { .. } => 0,
+        ResponseInputContentItem::InputFile { .. } => 0,
+        ResponseInputContentItem::InputAudio { .. } => 0,
+    }
+}
+
+/// Build the placeholder item that replaces dropped messages when no
+/// LLM call is involved. Emits a spec-shaped `compaction` item
+/// (`CompactionBody`) so SDK consumers can recognise it the same as
+/// they would the upstream-emitted version. Hadrian uses plain-text
+/// English in `encrypted_content` since we can't mint encrypted
+/// tokens the model would natively decode — the field is opaque to
+/// SDK consumers regardless.
+fn truncate_replacement(dropped: &[ResponsesInputItem]) -> Option<ResponsesInputItem> {
+    if dropped.is_empty() {
+        return None;
+    }
+    let summary = format!(
+        "[Hadrian compaction] {} earlier conversation item(s) dropped to fit context.",
+        dropped.len()
+    );
+    Some(make_summary_item(&summary))
+}
+
+fn make_summary_item(text: &str) -> ResponsesInputItem {
+    use crate::api_types::responses::{CompactionItem, CompactionItemType};
+    ResponsesInputItem::Compaction(CompactionItem {
+        type_: CompactionItemType::Compaction,
+        id: format!("cmp_{}", uuid::Uuid::new_v4().simple()),
+        encrypted_content: text.to_string(),
+        created_by: Some("gateway".to_string()),
+    })
+}
+
+/// Run a one-shot non-streaming summarisation call against the same
+/// provider as the parent request. Returns the raw assistant text.
+async fn llm_replacement(
+    state: &AppState,
+    provider_config: &ProviderConfig,
+    parent: &CreateResponsesPayload,
+    dropped: &[ResponsesInputItem],
+    prompt: &str,
+) -> Result<String, CompactionError> {
+    // Render a concise transcript out of the dropped items so the
+    // summariser has plain text to chew on (instead of forcing the
+    // model to parse function_call internals it didn't produce itself).
+    let transcript = render_items_for_summary(dropped);
+    let model = parent
+        .model
+        .clone()
+        .unwrap_or_else(|| "gpt-4o-mini".to_string());
+
+    // Reuse the parent's field layout (most importantly auth-related
+    // fields, sovereignty, etc.) but reset everything that would
+    // recurse or pollute the summarisation call.
+    let mut summary_payload = parent.clone();
+    summary_payload.model = Some(model.clone());
+    summary_payload.stream = false;
+    summary_payload.background = None;
+    summary_payload.tools = None;
+    summary_payload.tool_choice = None;
+    summary_payload.skills = None;
+    summary_payload.context_management = None;
+    summary_payload.previous_response_id = None;
+    summary_payload.store = Some(false);
+    summary_payload.instructions = Some(prompt.to_string());
+    summary_payload.input = Some(ResponsesInput::Items(vec![
+        ResponsesInputItem::EasyMessage(EasyInputMessage {
+            type_: None,
+            role: EasyInputMessageRole::User,
+            content: EasyInputMessageContent::Text(transcript),
+        }),
+    ]));
+
+    let response = crate::routes::execution::ResponsesExecutor::execute(
+        state,
+        provider_config_name(provider_config),
+        provider_config,
+        summary_payload,
+    )
+    .await
+    .map_err(|e| CompactionError::SummariseCall(format!("{e:?}")))?;
+
+    // Drain the body and extract the assistant text. We accept either
+    // a Responses-API JSON payload (when the provider returned one) or
+    // a chat-style fallback shape.
+    let body = response.into_body();
+    let bytes = axum::body::to_bytes(body, 8 * 1024 * 1024)
+        .await
+        .map_err(|e| CompactionError::SummariseCall(format!("failed to read body: {e}")))?;
+    extract_summary_text(&bytes)
+}
+
+/// Render a chronological transcript so the summariser sees plain
+/// text instead of typed-union JSON.
+fn render_items_for_summary(items: &[ResponsesInputItem]) -> String {
+    let mut buf = String::with_capacity(items.len() * 128);
+    for item in items {
+        match item {
+            ResponsesInputItem::EasyMessage(m) => {
+                buf.push_str(role_label(m.role));
+                buf.push_str(": ");
+                buf.push_str(&match &m.content {
+                    EasyInputMessageContent::Text(t) => t.clone(),
+                    EasyInputMessageContent::Parts(parts) => parts
+                        .iter()
+                        .filter_map(|p| match p {
+                            api_types::responses::ResponseInputContentItem::InputText {
+                                text,
+                                ..
+                            } => Some(text.clone()),
+                            _ => None,
+                        })
+                        .collect::<Vec<_>>()
+                        .join(" "),
+                });
+                buf.push('\n');
+            }
+            ResponsesInputItem::FunctionCallOutput(f) => {
+                buf.push_str("tool_output: ");
+                buf.push_str(&f.output);
+                buf.push('\n');
+            }
+            ResponsesInputItem::FunctionCall(f) => {
+                buf.push_str(&format!("tool_call: {} {}\n", f.name, f.arguments));
+            }
+            _ => {}
+        }
+    }
+    buf
+}
+
+fn role_label(role: EasyInputMessageRole) -> &'static str {
+    match role {
+        EasyInputMessageRole::User => "user",
+        EasyInputMessageRole::Assistant => "assistant",
+        EasyInputMessageRole::System => "system",
+        EasyInputMessageRole::Developer => "developer",
+    }
+}
+
+fn extract_summary_text(bytes: &[u8]) -> Result<String, CompactionError> {
+    let json: serde_json::Value =
+        serde_json::from_slice(bytes).map_err(|_| CompactionError::EmptySummary)?;
+    // Try Responses-API shape: output[].content[].text where type =
+    // "message"/"output_text".
+    if let Some(output) = json.get("output").and_then(|v| v.as_array()) {
+        let mut acc = String::new();
+        for item in output {
+            if item.get("type").and_then(|t| t.as_str()) != Some("message") {
+                continue;
+            }
+            if let Some(parts) = item.get("content").and_then(|v| v.as_array()) {
+                for part in parts {
+                    if let Some(text) = part.get("text").and_then(|v| v.as_str()) {
+                        if !acc.is_empty() {
+                            acc.push('\n');
+                        }
+                        acc.push_str(text);
+                    }
+                }
+            }
+        }
+        if !acc.is_empty() {
+            return Ok(acc);
+        }
+    }
+    // Fall back to choices[].message.content (chat-completion shape
+    // emitted by some adapters).
+    if let Some(choices) = json.get("choices").and_then(|v| v.as_array())
+        && let Some(first) = choices.first()
+        && let Some(text) = first
+            .get("message")
+            .and_then(|m| m.get("content"))
+            .and_then(|c| c.as_str())
+    {
+        return Ok(text.to_string());
+    }
+    Err(CompactionError::EmptySummary)
+}
+
+fn provider_config_name(cfg: &ProviderConfig) -> &str {
+    match cfg {
+        ProviderConfig::OpenAi(_) => "openai",
+        #[cfg(feature = "provider-azure")]
+        ProviderConfig::AzureOpenAi(_) => "azure_openai",
+        ProviderConfig::Anthropic(_) => "anthropic",
+        #[cfg(feature = "provider-bedrock")]
+        ProviderConfig::Bedrock(_) => "bedrock",
+        #[cfg(feature = "provider-vertex")]
+        ProviderConfig::Vertex(_) => "vertex",
+        ProviderConfig::Test(_) => "test",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api_types::responses::{
+        CompactionStrategy, ContextManagementItem, EasyInputMessage, EasyInputMessageContent,
+        EasyInputMessageRole, ResponsesInputItem,
+    };
+
+    fn text_item(role: EasyInputMessageRole, text: &str) -> ResponsesInputItem {
+        ResponsesInputItem::EasyMessage(EasyInputMessage {
+            type_: None,
+            role,
+            content: EasyInputMessageContent::Text(text.to_string()),
+        })
+    }
+
+    #[test]
+    fn estimate_tokens_counts_text_chars() {
+        let items = vec![text_item(EasyInputMessageRole::User, "abcdefgh")]; // 8 chars
+        assert_eq!(estimate_tokens(&items), 2);
+    }
+
+    #[test]
+    fn truncate_replacement_emits_compaction_item() {
+        let dropped = vec![
+            text_item(EasyInputMessageRole::User, "x"),
+            text_item(EasyInputMessageRole::Assistant, "y"),
+        ];
+        let r = truncate_replacement(&dropped).unwrap();
+        match r {
+            ResponsesInputItem::Compaction(item) => {
+                assert!(
+                    item.encrypted_content
+                        .contains("2 earlier conversation item(s)")
+                );
+                assert!(item.id.starts_with("cmp_"));
+                assert_eq!(item.created_by.as_deref(), Some("gateway"));
+            }
+            _ => panic!("expected compaction item"),
+        }
+    }
+
+    #[test]
+    fn extract_summary_handles_responses_shape() {
+        let body = serde_json::json!({
+            "output": [
+                {
+                    "type": "message",
+                    "content": [
+                        {"type": "output_text", "text": "Hello world"}
+                    ]
+                }
+            ]
+        });
+        let text = extract_summary_text(body.to_string().as_bytes()).unwrap();
+        assert_eq!(text, "Hello world");
+    }
+
+    #[test]
+    fn extract_summary_handles_chat_shape() {
+        let body = serde_json::json!({
+            "choices": [{"message": {"content": "Concise summary"}}]
+        });
+        let text = extract_summary_text(body.to_string().as_bytes()).unwrap();
+        assert_eq!(text, "Concise summary");
+    }
+
+    #[test]
+    fn render_items_emits_role_labels() {
+        let items = vec![
+            text_item(EasyInputMessageRole::User, "Hi"),
+            text_item(EasyInputMessageRole::Assistant, "Hello!"),
+        ];
+        let rendered = render_items_for_summary(&items);
+        assert!(rendered.contains("user: Hi"));
+        assert!(rendered.contains("assistant: Hello!"));
+    }
+
+    #[test]
+    fn compaction_strategy_enum_round_trips() {
+        // Sanity: the request-level strategy enum maps onto the
+        // operator config enum we expose internally.
+        let _llm = CompactionStrategy::Llm;
+        let _trunc = CompactionStrategy::Truncate;
+        let _other = ContextManagementItem::Other;
+    }
+}
diff --git a/src/services/container_session.rs b/src/services/container_session.rs
new file mode 100644
index 0000000..4f3945e
--- /dev/null
+++ b/src/services/container_session.rs
@@ -0,0 +1,1174 @@
+//! Container session: a wrapper around `SessionHandle` that snapshots
+//! `/mnt/data` between shell commands and captures any
+//! new/changed files as `ContainerFileRef`s.
+//!
+//! One session per `ShellExecutor` (i.e. per response). File content
+//! is committed to the `container_files` table for durability and
+//! shadowed in process memory for fast access during the active
+//! response.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::{
+    collections::HashMap,
+    sync::Arc,
+    time::{Duration, Instant},
+};
+
+use bytes::Bytes;
+use sha2::{Digest, Sha256};
+use tokio::sync::Mutex;
+use tracing::{debug, error, warn};
+use uuid::Uuid;
+
+use crate::{
+    api_types::responses::{ContainerFileRef, ContainerFileSource},
+    config::ContainersConfig,
+    db::repos::ResponseOwner,
+    runtimes::{
+        ExecRequest, RuntimeError, RuntimeResult, SessionHandle, SessionSpec, ShellRuntime,
+    },
+    services::{
+        containers::{ContainersService, PersistFileInput},
+        input_file_staging::StagedFile,
+    },
+};
+
+/// Root of the writable workspace inside the container.
+pub const MNT_DATA: &str = "/mnt/data";
+
+/// Generate a `cntr_<simple-uuid>` identifier.
+pub fn new_container_id() -> String {
+    format!("cntr_{}", Uuid::new_v4().simple())
+}
+
+/// Generate a `cfile_<simple-uuid>` identifier.
+pub fn new_file_id() -> String {
+    format!("cfile_{}", Uuid::new_v4().simple())
+}
+
+/// One file currently being tracked by the session.
+///
+/// `content` is the in-memory copy used to build the persist payload
+/// for `container_files`; `hash` mirrors the snapshot entry so the
+/// persist payload can carry the canonical content-hash without
+/// re-digesting the bytes.
+#[derive(Debug, Clone)]
+struct TrackedFile {
+    file_id: String,
+    path: String,
+    filename: String,
+    bytes: u64,
+    content_type: Option<String>,
+    source: ContainerFileSource,
+    content: Bytes,
+    hash: [u8; 32],
+}
+
+impl TrackedFile {
+    fn to_ref(&self, container_id: &str) -> ContainerFileRef {
+        ContainerFileRef {
+            container_id: container_id.to_string(),
+            file_id: self.file_id.clone(),
+            filename: self.filename.clone(),
+            path: self.path.clone(),
+            bytes: self.bytes,
+            content_type: self.content_type.clone(),
+            source: self.source,
+        }
+    }
+}
+
+/// Mutable state inside a `ContainerSession`.
+///
+/// Held behind a `Mutex` because parallel shell tool calls dispatched
+/// by the runner share one session and must serialize access to the
+/// snapshot map and byte counters.
+#[derive(Default)]
+struct SessionState {
+    /// path -> sha256 of every file under `/mnt/data` as of the last
+    /// snapshot. Drives the new/changed diff after each exec.
+    snapshot: HashMap<String, [u8; 32]>,
+    /// Files captured during this session, indexed by path. Latest
+    /// version per path wins (overwrites replace the prior entry).
+    captured: HashMap<String, TrackedFile>,
+    /// Sum of `bytes` across all current `captured` entries, used to
+    /// enforce `max_bytes_per_session`.
+    bytes_total: u64,
+    /// Wall-clock of the last successful `exec()`. Drives idle TTL.
+    last_active: Option<Instant>,
+}
+
+/// Process-wide cache of live [`ContainerSession`]s keyed by their
+/// container id. Lets multiple `/v1/responses` requests share one
+/// VM across the lifetime of a container.
+///
+/// Each entry holds an `Arc<Mutex<ContainerSession>>`. Shell commands
+/// from concurrent requests serialize through the mutex; the registry
+/// itself is lock-free for lookups. When the reaper or
+/// `DELETE /v1/containers/{id}` evicts a row, dropping the registry's
+/// Arc lets `ContainerSession::drop` tear the VM down once the last
+/// outstanding request finishes with it.
+#[derive(Default)]
+pub struct ContainerSessionRegistry {
+    sessions: dashmap::DashMap<String, Arc<Mutex<ContainerSession>>>,
+}
+
+impl ContainerSessionRegistry {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Look up a live session by id. Cheap; lock-free.
+    pub fn get(&self, container_id: &str) -> Option<Arc<Mutex<ContainerSession>>> {
+        self.sessions.get(container_id).map(|e| e.clone())
+    }
+
+    /// Insert a freshly-started session. If an entry already exists
+    /// for this id (e.g. two requests for the same `previous_response_id`
+    /// raced to create), the new entry wins and the previous one is
+    /// returned so the caller can terminate it explicitly.
+    pub fn insert(
+        &self,
+        container_id: String,
+        session: ContainerSession,
+    ) -> (
+        Arc<Mutex<ContainerSession>>,
+        Option<Arc<Mutex<ContainerSession>>>,
+    ) {
+        let arc = Arc::new(Mutex::new(session));
+        let prior = self.sessions.insert(container_id, arc.clone());
+        (arc, prior)
+    }
+
+    /// Atomic get-or-insert: returns the existing session if one is
+    /// already registered for `container_id`, otherwise inserts the
+    /// session produced by `build()` and returns it. The booted
+    /// session — including the underlying VM — is only constructed
+    /// when no prior entry exists, so a race between two requests for
+    /// the same `previous_response_id` boots exactly one VM instead
+    /// of two (with the loser then being torn down).
+    ///
+    /// Returns `(arc, inserted)` where `inserted` is `false` when the
+    /// existing entry won the race. On `build` failure the slot is
+    /// left empty and the error bubbles up.
+    pub async fn get_or_try_insert_with<F, Fut, E>(
+        &self,
+        container_id: String,
+        build: F,
+    ) -> Result<(Arc<Mutex<ContainerSession>>, bool), E>
+    where
+        F: FnOnce() -> Fut,
+        Fut: std::future::Future<Output = Result<ContainerSession, E>>,
+    {
+        // `DashMap::entry` blocks any other writer on the same shard
+        // for the duration the `Entry` is held. We do NOT hold it
+        // across the `build().await` (it's a sync mutex internally —
+        // holding across await would block all other shard writers
+        // including unrelated containers). Instead, fast-path a
+        // get(), boot, then re-check under entry().
+        if let Some(existing) = self.sessions.get(&container_id) {
+            return Ok((existing.clone(), false));
+        }
+        let session = build().await?;
+        let arc_new = Arc::new(Mutex::new(session));
+        // CAS: only insert if still vacant. If a parallel request
+        // raced us and registered first, drop our freshly-booted VM
+        // (its `Drop` impl detaches a terminate task).
+        let entry = self.sessions.entry(container_id);
+        match entry {
+            dashmap::Entry::Occupied(o) => Ok((o.get().clone(), false)),
+            dashmap::Entry::Vacant(v) => {
+                v.insert(arc_new.clone());
+                Ok((arc_new, true))
+            }
+        }
+    }
+
+    /// Drop the registry's reference to this session. Returns the
+    /// removed entry so callers can terminate it explicitly when
+    /// they need ordered cleanup; ignoring the return value relies on
+    /// `ContainerSession::drop` to detach the terminate task.
+    pub fn remove(&self, container_id: &str) -> Option<Arc<Mutex<ContainerSession>>> {
+        self.sessions.remove(container_id).map(|(_, v)| v)
+    }
+
+    /// Snapshot of the ids of all live sessions. Used by the reaper to
+    /// reconcile this replica's local registry against expired DB rows
+    /// (the registry is process-local, so every replica must evict its
+    /// own sessions even when a different replica flipped the row).
+    pub fn ids(&self) -> Vec<String> {
+        self.sessions.iter().map(|e| e.key().clone()).collect()
+    }
+
+    /// Number of live sessions. Used by tests and the
+    /// `hadrian_container_session_count` gauge.
+    pub fn len(&self) -> usize {
+        self.sessions.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.sessions.is_empty()
+    }
+}
+
+/// Persistence wiring for a session. Optional — when `None`, files
+/// captured under `/mnt/data` live only in memory and never make it
+/// to the database (no `GET /v1/containers/{id}/files/...` route
+/// resolves). Populated whenever a database is configured and the
+/// pipeline can derive a [`ResponseOwner`] for the request.
+#[derive(Clone)]
+pub struct ContainerPersistence {
+    pub service: Arc<ContainersService>,
+    pub org_id: uuid::Uuid,
+    pub owner: ResponseOwner,
+    pub source_response_id: Option<String>,
+}
+
+/// A persistent shell-tool session backed by a `SessionHandle`.
+///
+/// Owns the underlying VM for the lifetime of one response. Future
+/// work may extend ownership to a `Container` resource that spans
+/// multiple responses. Implements `Drop` to detach a terminate task
+/// so the VM is cleaned up even on client disconnect.
+pub struct ContainerSession {
+    pub container_id: String,
+    pub runtime_label: &'static str,
+    pub created_at: Instant,
+    pub idle_ttl: Duration,
+    file_io: bool,
+    session: Option<SessionHandle>,
+    config: ContainersConfig,
+    state: Mutex<SessionState>,
+    persistence: Option<ContainerPersistence>,
+}
+
+impl ContainerSession {
+    /// Boot a fresh VM and provision a new `containers` row. The
+    /// caller is responsible for inserting the returned session into
+    /// a `ContainerSessionRegistry` (the registry doesn't try to
+    /// auto-register so the caller controls the keying and can react
+    /// to insert races).
+    pub async fn start_new(
+        runtime: Arc<dyn ShellRuntime>,
+        runtime_label: &'static str,
+        spec: SessionSpec,
+        config: ContainersConfig,
+        persistence: Option<ContainerPersistence>,
+        idle_ttl_secs_override: Option<i64>,
+    ) -> RuntimeResult<Self> {
+        let container_id = new_container_id();
+        Self::boot_inner(
+            container_id,
+            runtime,
+            runtime_label,
+            spec,
+            config,
+            persistence,
+            None,
+            idle_ttl_secs_override,
+        )
+        .await
+    }
+
+    /// Boot a VM bound to a specific container id. If the
+    /// `containers` row for `container_id` exists and is active, its
+    /// persisted files are replayed into `/mnt/data` so the model
+    /// picks up where it left off. If the row is missing, this method
+    /// also inserts it.
+    ///
+    /// Returns [`RuntimeError::Backend`] when the row exists but is
+    /// no longer reusable (`expired` / `deleted`). Callers translate
+    /// to a 410-style error for explicit reuse or silently fall back
+    /// to `start_new` for implicit chaining.
+    pub async fn start_attached(
+        container_id: String,
+        runtime: Arc<dyn ShellRuntime>,
+        runtime_label: &'static str,
+        spec: SessionSpec,
+        config: ContainersConfig,
+        persistence: ContainerPersistence,
+        idle_ttl_secs_override: Option<i64>,
+    ) -> RuntimeResult<Self> {
+        // Materialise the row before booting the VM so a failure
+        // (expired container, DB outage) costs us nothing. Reattach
+        // does *not* extend the TTL — the container row's
+        // `idle_ttl_secs` is whatever was set at creation time and
+        // stays put across reuse.
+        let initial_ttl = idle_ttl_secs_override.unwrap_or(config.default_idle_ttl_secs as i64);
+        persistence
+            .service
+            .ensure_container(
+                container_id.clone(),
+                persistence.org_id,
+                persistence.owner,
+                runtime_label,
+                persistence.source_response_id.clone(),
+                initial_ttl,
+            )
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("ensure_container: {e}")))?;
+
+        Self::boot_inner(
+            container_id,
+            runtime,
+            runtime_label,
+            spec,
+            config,
+            Some(persistence.clone()),
+            Some(persistence),
+            idle_ttl_secs_override,
+        )
+        .await
+    }
+
+    /// Shared boot path. When `replay` is `Some`, skips provisioning
+    /// (the row already exists) and replays persisted files into
+    /// `/mnt/data` after the baseline `mkdir`.
+    #[allow(clippy::too_many_arguments)] // each arg is load-bearing; bundling doesn't help
+    async fn boot_inner(
+        container_id: String,
+        runtime: Arc<dyn ShellRuntime>,
+        runtime_label: &'static str,
+        spec: SessionSpec,
+        config: ContainersConfig,
+        persistence: Option<ContainerPersistence>,
+        replay: Option<ContainerPersistence>,
+        idle_ttl_secs_override: Option<i64>,
+    ) -> RuntimeResult<Self> {
+        let file_io = runtime.capabilities().file_io;
+        let session = runtime.start_session(spec).await?;
+
+        let initial_ttl = idle_ttl_secs_override.unwrap_or(config.default_idle_ttl_secs as i64);
+
+        // For fresh containers, insert the row up front so a
+        // simultaneous chain-reuse request can find it. For reattach,
+        // skip — the row was created in a previous response.
+        let persistence = if replay.is_some() {
+            persistence
+        } else {
+            match persistence {
+                Some(p) => match p
+                    .service
+                    .provision(
+                        container_id.clone(),
+                        p.org_id,
+                        p.owner,
+                        runtime_label,
+                        p.source_response_id.clone(),
+                        initial_ttl,
+                    )
+                    .await
+                {
+                    Ok(_) => Some(p),
+                    Err(e) => {
+                        warn!(
+                            stage = "container_provision_failed",
+                            container_id = %container_id,
+                            error = %e,
+                            "Failed to insert containers row; continuing in-memory only"
+                        );
+                        None
+                    }
+                },
+                None => None,
+            }
+        };
+
+        // Once the container row exists (whether freshly provisioned
+        // or reattached), stamp the current response's
+        // `container_id` column. Lets the next chained request find
+        // this container via `previous_response_id`.
+        if let Some(ref p) = persistence
+            && let Some(ref resp_id) = p.source_response_id
+            && let Err(e) = p
+                .service
+                .link_response_to_container(resp_id, &container_id, p.org_id)
+                .await
+        {
+            warn!(
+                stage = "container_link_response_failed",
+                container_id = %container_id,
+                response_id = %resp_id,
+                error = %e,
+                "Failed to stamp responses.container_id; chain reuse from this response won't work"
+            );
+        }
+
+        let effective_ttl_secs = if initial_ttl > 0 {
+            initial_ttl as u64
+        } else {
+            config.default_idle_ttl_secs
+        };
+        let session_obj = Self {
+            container_id,
+            runtime_label,
+            created_at: Instant::now(),
+            idle_ttl: Duration::from_secs(effective_ttl_secs.max(1)),
+            file_io,
+            session: Some(session),
+            config,
+            state: Mutex::new(SessionState::default()),
+            persistence,
+        };
+
+        if file_io && session_obj.config.enabled {
+            // Ensure /mnt/data exists. `mkdir -p` is a no-op if it
+            // already does; either way it's cheap.
+            if let Err(e) = session_obj
+                .exec_blocking("mkdir -p /mnt/data".to_string(), Duration::from_secs(5))
+                .await
+            {
+                warn!(
+                    stage = "container_mkdir_failed",
+                    container_id = %session_obj.container_id,
+                    error = %e,
+                    "Failed to create /mnt/data — artifact capture disabled for this session"
+                );
+            } else {
+                if let Some(replay_ctx) = replay {
+                    // Replay persisted files into the fresh VM so the
+                    // model sees the same `/mnt/data` it left in the
+                    // prior response. Files are restored as
+                    // `source: assistant|user` from the DB rows; the
+                    // snapshot map is seeded so capture_changes only
+                    // reports genuinely new edits.
+                    if let Err(e) = session_obj.replay_from_db(&replay_ctx).await {
+                        warn!(
+                            stage = "container_replay_failed",
+                            container_id = %session_obj.container_id,
+                            error = %e,
+                            "Failed to replay persisted files into /mnt/data — \
+                             continuing with empty workspace"
+                        );
+                    }
+                }
+
+                // Baseline snapshot. Errors here are logged but not
+                // fatal — the model can still run commands; we just
+                // won't know about pre-existing files.
+                if let Err(e) = session_obj.refresh_snapshot().await {
+                    warn!(
+                        stage = "container_baseline_snapshot_failed",
+                        container_id = %session_obj.container_id,
+                        error = %e,
+                        "Failed to seed /mnt/data baseline snapshot"
+                    );
+                }
+            }
+        }
+
+        Ok(session_obj)
+    }
+
+    /// Restore persisted `container_files` rows into the live VM's
+    /// `/mnt/data`. Called by [`Self::start_attached`].
+    async fn replay_from_db(&self, persistence: &ContainerPersistence) -> RuntimeResult<()> {
+        let svc = &persistence.service;
+        let records = svc
+            .list_files_for_replay(&self.container_id)
+            .await
+            .map_err(|e| RuntimeError::Backend(format!("replay list: {e}")))?;
+        if records.is_empty() {
+            return Ok(());
+        }
+
+        let session = self.session()?;
+        let mut state = self.state.lock().await;
+        let mut replayed = 0usize;
+        let mut bytes_total: u64 = 0;
+        for rec in records.into_iter().rev() {
+            // Reverse so an overwrite history applies in time order.
+            let bytes = match svc.read_content_for_replay(&rec).await {
+                Ok(Some(b)) => Bytes::from(b),
+                Ok(None) => {
+                    // Metadata-only row (oversized; content was
+                    // dropped). Restore the snapshot entry without
+                    // bytes; the model sees the file is "gone" until
+                    // it writes again.
+                    let hash = sha256_bytes(&[]);
+                    state.snapshot.insert(rec.path.clone(), hash);
+                    continue;
+                }
+                Err(e) => {
+                    warn!(
+                        stage = "container_replay_read_failed",
+                        container_id = %self.container_id,
+                        path = %rec.path,
+                        error = %e,
+                        "Failed to read persisted bytes during replay; skipping"
+                    );
+                    continue;
+                }
+            };
+
+            if let Err(e) = session.write_file(&rec.path, bytes.clone()).await {
+                warn!(
+                    stage = "container_replay_write_failed",
+                    container_id = %self.container_id,
+                    path = %rec.path,
+                    error = %e,
+                    "Failed to write file into /mnt/data during replay; skipping"
+                );
+                continue;
+            }
+
+            let hash = sha256_bytes(&bytes);
+            let source = match rec.source {
+                crate::db::repos::ContainerFileSourceKind::User => ContainerFileSource::User,
+                crate::db::repos::ContainerFileSourceKind::Assistant => {
+                    ContainerFileSource::Assistant
+                }
+            };
+            let tracked = TrackedFile {
+                file_id: rec.id.clone(),
+                path: rec.path.clone(),
+                filename: rec.filename.clone(),
+                bytes: bytes.len() as u64,
+                content_type: rec.content_type.clone(),
+                source,
+                content: bytes,
+                hash,
+            };
+            bytes_total = bytes_total.saturating_add(tracked.bytes);
+            state.snapshot.insert(rec.path.clone(), hash);
+            state.captured.insert(rec.path.clone(), tracked);
+            replayed += 1;
+        }
+        state.bytes_total = bytes_total;
+        debug!(
+            stage = "container_replay",
+            container_id = %self.container_id,
+            files = replayed,
+            bytes_total,
+            "Replayed persisted files into /mnt/data"
+        );
+        Ok(())
+    }
+
+    pub fn file_io_enabled(&self) -> bool {
+        self.file_io && self.config.enabled
+    }
+
+    fn session(&self) -> RuntimeResult<&SessionHandle> {
+        self.session
+            .as_ref()
+            .ok_or_else(|| RuntimeError::Backend("container session already terminated".into()))
+    }
+
+    /// Run one command. On success and when artifact capture is
+    /// enabled, snapshot `/mnt/data` afterwards and return the diff
+    /// (new/changed files) so the caller can fold them into the
+    /// terminal `shell_call_output` item's `output_files` array.
+    pub async fn exec(&self, req: ExecRequest) -> RuntimeResult<ExecOutcome> {
+        let exec = self.session()?.exec(req).await?;
+        {
+            let mut state = self.state.lock().await;
+            state.last_active = Some(Instant::now());
+        }
+        // Persist the activity ping so the idle reaper doesn't expire a busy
+        // container and the containers API shows a moving last_active_at /
+        // expires_at. The in-memory `last_active` above only guards the
+        // process-local registry. Best-effort: a failed write must not fail
+        // the command.
+        if let Some(persistence) = &self.persistence
+            && let Err(e) = persistence
+                .service
+                .touch_last_active(&self.container_id, persistence.org_id)
+                .await
+        {
+            debug!(
+                stage = "container_touch_last_active_failed",
+                container_id = %self.container_id,
+                error = %e,
+                "Failed to persist container last_active_at"
+            );
+        }
+        Ok(ExecOutcome { handle: exec })
+    }
+
+    /// Helper for one-shot internal commands (mkdir, sha256sum) where
+    /// we don't care about streaming output. Captures stdout+stderr
+    /// into a single `String` and returns the exit code alongside.
+    async fn exec_blocking(&self, command: String, timeout: Duration) -> RuntimeResult<String> {
+        use futures_util::StreamExt;
+
+        use crate::runtimes::ExecEvent;
+
+        let exec = self
+            .session()?
+            .exec(ExecRequest {
+                command,
+                stdin: None,
+                timeout: Some(timeout),
+            })
+            .await?;
+        let mut stdout = Vec::new();
+        let mut stream = exec.output;
+        while let Some(ev) = stream.next().await {
+            match ev {
+                ExecEvent::Stdout(b) => stdout.extend_from_slice(&b),
+                ExecEvent::Stderr(_) => {}
+                ExecEvent::Exit { .. } => break,
+            }
+        }
+        Ok(String::from_utf8_lossy(&stdout).into_owned())
+    }
+
+    /// Diff `/mnt/data` after a shell command. Returns one entry per
+    /// new or changed file (caller decides what to do with them —
+    /// typically attach to the shell_call_output and emit
+    /// `file_created` SSE events).
+    ///
+    /// No-op when `file_io` is unavailable or `[features.containers]
+    /// enabled = false`.
+    pub async fn capture_changes(&self) -> RuntimeResult<Vec<ContainerFileRef>> {
+        if !self.file_io_enabled() {
+            return Ok(Vec::new());
+        }
+
+        let listing = self.list_mnt_data().await?;
+
+        let mut state = self.state.lock().await;
+        let mut new_refs = Vec::new();
+        let mut files_this_exec: usize = 0;
+
+        for (path, hash) in &listing {
+            let prior = state.snapshot.get(path);
+            let changed = match prior {
+                None => true,
+                Some(prev) => prev != hash,
+            };
+            if !changed {
+                continue;
+            }
+
+            if files_this_exec >= self.config.max_files_per_exec {
+                warn!(
+                    stage = "container_capture_truncated",
+                    container_id = %self.container_id,
+                    limit = self.config.max_files_per_exec,
+                    "Hit max_files_per_exec; remaining changes for this command dropped"
+                );
+                break;
+            }
+            files_this_exec += 1;
+
+            // Pull the bytes out of the VM. Errors are logged and the
+            // file is skipped rather than aborting the whole capture.
+            let bytes = match self.session()?.read_file(path).await {
+                Ok(b) => b,
+                Err(e) => {
+                    warn!(
+                        stage = "container_read_failed",
+                        container_id = %self.container_id,
+                        path = %path,
+                        error = %e,
+                        "Failed to read captured file"
+                    );
+                    continue;
+                }
+            };
+
+            // Preserve the existing TrackedFile.file_id when
+            // overwriting a known path. The repo's UPSERT keeps the
+            // row's PK stable across overwrites, so any annotation
+            // already cited for this path keeps resolving — the
+            // in-memory id must match.
+            let stable_id = state
+                .captured
+                .get(path)
+                .map(|f| f.file_id.clone())
+                .unwrap_or_else(new_file_id);
+
+            if bytes.len() as u64 > self.config.max_bytes_per_file {
+                warn!(
+                    stage = "container_file_too_large",
+                    container_id = %self.container_id,
+                    path = %path,
+                    bytes = bytes.len(),
+                    limit = self.config.max_bytes_per_file,
+                    "Captured file exceeds max_bytes_per_file; recording metadata only"
+                );
+                // Insert a metadata-only entry: no content, but the
+                // model and client still see that the file exists.
+                let prior_bytes = state.captured.get(path).map(|f| f.bytes).unwrap_or(0);
+                state.bytes_total = state.bytes_total.saturating_sub(prior_bytes);
+                let filename = filename_from_path(path);
+                let entry = TrackedFile {
+                    file_id: stable_id,
+                    path: path.clone(),
+                    filename: filename.clone(),
+                    bytes: bytes.len() as u64,
+                    content_type: guess_content_type(&filename),
+                    source: ContainerFileSource::Assistant,
+                    content: Bytes::new(),
+                    hash: *hash,
+                };
+                let r = entry.to_ref(&self.container_id);
+                state.captured.insert(path.clone(), entry);
+                state.snapshot.insert(path.clone(), *hash);
+                new_refs.push(r);
+                continue;
+            }
+
+            // Enforce the cumulative session cap. If adding this file
+            // would put us over, skip with a warning.
+            let prior_bytes = state.captured.get(path).map(|f| f.bytes).unwrap_or(0);
+            let projected = state.bytes_total.saturating_sub(prior_bytes) + bytes.len() as u64;
+            if projected > self.config.max_bytes_per_session {
+                warn!(
+                    stage = "container_session_bytes_limit",
+                    container_id = %self.container_id,
+                    path = %path,
+                    projected,
+                    limit = self.config.max_bytes_per_session,
+                    "Captured file would exceed max_bytes_per_session; skipping"
+                );
+                continue;
+            }
+
+            let filename = filename_from_path(path);
+            let content_type = guess_content_type(&filename);
+            let entry = TrackedFile {
+                file_id: stable_id,
+                path: path.clone(),
+                filename: filename.clone(),
+                bytes: bytes.len() as u64,
+                content_type,
+                source: ContainerFileSource::Assistant,
+                content: bytes,
+                hash: *hash,
+            };
+            let r = entry.to_ref(&self.container_id);
+            state.bytes_total = projected;
+            state.captured.insert(path.clone(), entry);
+            state.snapshot.insert(path.clone(), *hash);
+            new_refs.push(r);
+        }
+
+        // Files that disappeared from /mnt/data: drop their tracking
+        // info. We don't emit deletion events — only creations and
+        // modifications surface as annotations.
+        let removed_paths: Vec<String> = state
+            .snapshot
+            .keys()
+            .filter(|p| !listing.contains_key(p.as_str()))
+            .cloned()
+            .collect();
+        for p in removed_paths {
+            if let Some(entry) = state.captured.remove(&p) {
+                state.bytes_total = state.bytes_total.saturating_sub(entry.bytes);
+            }
+            state.snapshot.remove(&p);
+        }
+
+        debug!(
+            stage = "container_capture",
+            container_id = %self.container_id,
+            new_or_changed = new_refs.len(),
+            total_tracked = state.captured.len(),
+            bytes_total = state.bytes_total,
+            "Captured /mnt/data changes"
+        );
+
+        // Snapshot the newly captured entries while we still hold the
+        // state lock so the persist payload sees the same bytes as
+        // the in-memory view. Then drop the lock before doing async DB
+        // I/O so concurrent capture_changes / read_file calls don't
+        // queue behind the persister.
+        let persist_payload: Vec<PersistFileInput> = if self.persistence.is_some() {
+            new_refs
+                .iter()
+                .filter_map(|r| state.captured.get(&r.path).map(|t| (r, t)))
+                .map(|(_r, t)| PersistFileInput {
+                    file_id: t.file_id.clone(),
+                    path: t.path.clone(),
+                    filename: t.filename.clone(),
+                    content_type: t.content_type.clone(),
+                    source: t.source,
+                    content: t.content.clone(),
+                    content_hash_hex: hex::encode(t.hash),
+                    source_response_id: self
+                        .persistence
+                        .as_ref()
+                        .and_then(|p| p.source_response_id.clone()),
+                    source_call_id: None,
+                })
+                .collect()
+        } else {
+            Vec::new()
+        };
+        drop(state);
+
+        if !persist_payload.is_empty()
+            && let Some(p) = self.persistence.as_ref()
+            && let Err(e) = p
+                .service
+                .persist_files(&self.container_id, p.org_id, persist_payload)
+                .await
+        {
+            warn!(
+                stage = "container_persist_failed",
+                container_id = %self.container_id,
+                error = %e,
+                "Failed to persist captured files; in-memory annotations remain valid for this response"
+            );
+        }
+
+        Ok(new_refs)
+    }
+
+    /// Write a batch of user-supplied files into `/mnt/data` and
+    /// register them as captured artifacts with `source = User`.
+    ///
+    /// The responses pipeline resolves `input_file` parts into
+    /// `StagedFile`s and feeds them in before the first shell command
+    /// runs. The snapshot is updated as we go so the next
+    /// `capture_changes()` call doesn't re-report these as new/changed.
+    ///
+    /// No-ops with `Ok(vec![])` when artifact capture is disabled or
+    /// the runtime doesn't expose `file_io`. Returns the per-file
+    /// references in input order so the caller can fold them into the
+    /// terminal `shell_call_output` item's `output_files` array or
+    /// surface them as `container_file_citation` annotations.
+    pub async fn ingest_user_files(
+        &self,
+        files: Vec<StagedFile>,
+    ) -> RuntimeResult<Vec<ContainerFileRef>> {
+        if !self.file_io_enabled() || files.is_empty() {
+            return Ok(Vec::new());
+        }
+
+        let session = self.session()?;
+        let mut out = Vec::with_capacity(files.len());
+        let mut state = self.state.lock().await;
+
+        for file in files {
+            let path = format!("{MNT_DATA}/{}", file.filename);
+            let len = file.bytes.len() as u64;
+
+            // Enforce the session-wide byte budget. We treat user
+            // files the same way as assistant-produced ones — they
+            // share `bytes_total`. Hitting the cap is logged and the
+            // remaining files are skipped, but the staged file is
+            // still written so the model can see it; the only thing
+            // we drop is the in-memory cached copy used for download.
+            let over_budget =
+                state.bytes_total.saturating_add(len) > self.config.max_bytes_per_session;
+            if over_budget {
+                warn!(
+                    stage = "ingest_user_file_over_budget",
+                    container_id = %self.container_id,
+                    filename = %file.filename,
+                    bytes = len,
+                    bytes_total = state.bytes_total,
+                    limit = self.config.max_bytes_per_session,
+                    "Staging file would exceed max_bytes_per_session; recording metadata only"
+                );
+            }
+
+            if let Err(e) = session.write_file(&path, file.bytes.clone()).await {
+                error!(
+                    stage = "ingest_user_file_write_failed",
+                    container_id = %self.container_id,
+                    filename = %file.filename,
+                    error = %e,
+                    "Failed to stage user input file into /mnt/data"
+                );
+                return Err(e);
+            }
+
+            let hash = sha256_bytes(&file.bytes);
+            let stored_content = if over_budget {
+                Bytes::new()
+            } else {
+                file.bytes
+            };
+            let tracked = TrackedFile {
+                file_id: new_file_id(),
+                path: path.clone(),
+                filename: file.filename.clone(),
+                bytes: len,
+                content_type: file.content_type,
+                source: ContainerFileSource::User,
+                content: stored_content,
+                hash,
+            };
+            let r = tracked.to_ref(&self.container_id);
+            if !over_budget {
+                state.bytes_total = state.bytes_total.saturating_add(len);
+            }
+            state.captured.insert(path.clone(), tracked);
+            state.snapshot.insert(path, hash);
+            out.push(r);
+        }
+
+        state.last_active = Some(Instant::now());
+
+        debug!(
+            stage = "ingest_user_files",
+            container_id = %self.container_id,
+            count = out.len(),
+            bytes_total = state.bytes_total,
+            "Staged user input files into /mnt/data"
+        );
+
+        // Build the persist payload from the freshly-inserted tracked
+        // files (still inside the lock so bytes match). Drop the lock
+        // before the async DB call.
+        let persist_payload: Vec<PersistFileInput> = if self.persistence.is_some() {
+            out.iter()
+                .filter_map(|r| state.captured.get(&r.path).map(|t| (r, t)))
+                .map(|(_, t)| PersistFileInput {
+                    file_id: t.file_id.clone(),
+                    path: t.path.clone(),
+                    filename: t.filename.clone(),
+                    content_type: t.content_type.clone(),
+                    source: t.source,
+                    content: t.content.clone(),
+                    content_hash_hex: hex::encode(t.hash),
+                    source_response_id: self
+                        .persistence
+                        .as_ref()
+                        .and_then(|p| p.source_response_id.clone()),
+                    source_call_id: None,
+                })
+                .collect()
+        } else {
+            Vec::new()
+        };
+        drop(state);
+
+        if !persist_payload.is_empty()
+            && let Some(p) = self.persistence.as_ref()
+            && let Err(e) = p
+                .service
+                .persist_files(&self.container_id, p.org_id, persist_payload)
+                .await
+        {
+            warn!(
+                stage = "container_persist_failed",
+                container_id = %self.container_id,
+                error = %e,
+                "Failed to persist staged input files"
+            );
+        }
+
+        Ok(out)
+    }
+
+    /// All container files currently tracked, regardless of when they
+    /// were first captured. Callers attach an annotation per file to
+    /// the assistant's final `output_text`.
+    pub async fn list_captured(&self) -> Vec<ContainerFileRef> {
+        let state = self.state.lock().await;
+        state
+            .captured
+            .values()
+            .map(|f| f.to_ref(&self.container_id))
+            .collect()
+    }
+
+    /// Re-seed `snapshot` from the current `/mnt/data` state without
+    /// emitting any change events. Used at session-start.
+    async fn refresh_snapshot(&self) -> RuntimeResult<()> {
+        let listing = self.list_mnt_data().await?;
+        let mut state = self.state.lock().await;
+        state.snapshot = listing;
+        Ok(())
+    }
+
+    /// List every regular file under `/mnt/data` with its sha256.
+    ///
+    /// Uses `sha256sum` which is present on the alpine base image
+    /// (busybox) and on every glibc Linux distro we ship images for.
+    /// The trailing `|| true` keeps the command's exit code at 0 even
+    /// when `/mnt/data` is empty (so we don't surface a confusing
+    /// `exit_code=1` to callers via the orchestrator's plumbing — this
+    /// is an internal command).
+    async fn list_mnt_data(&self) -> RuntimeResult<HashMap<String, [u8; 32]>> {
+        let command = format!(
+            "find {MNT_DATA} -type f -print0 2>/dev/null | xargs -0 -r sha256sum 2>/dev/null || true"
+        );
+        let output = self.exec_blocking(command, Duration::from_secs(30)).await?;
+        Ok(parse_sha256sum_output(&output))
+    }
+
+    /// Tear down the underlying VM. Idempotent; safe to call from
+    /// `Drop` via a detached task.
+    pub async fn terminate(mut self) -> RuntimeResult<()> {
+        if let Some(session) = self.session.take() {
+            session.terminate().await
+        } else {
+            Ok(())
+        }
+    }
+}
+
+impl Drop for ContainerSession {
+    fn drop(&mut self) {
+        if let Some(session) = self.session.take() {
+            let cid = self.container_id.clone();
+            crate::compat::spawn_detached(async move {
+                if let Err(e) = session.terminate().await {
+                    warn!(
+                        stage = "container_drop_terminate_failed",
+                        container_id = %cid,
+                        error = %e,
+                        "Detached terminate after Drop failed"
+                    );
+                }
+            });
+        }
+    }
+}
+
+/// Outcome of a single `exec()` call. Mirrors the runtime's
+/// `ExecHandle` for now; future revisions may add per-exec annotation
+/// hints or a captured-files preview here.
+pub struct ExecOutcome {
+    pub handle: crate::runtimes::ExecHandle,
+}
+
+fn filename_from_path(path: &str) -> String {
+    std::path::Path::new(path)
+        .file_name()
+        .and_then(|s| s.to_str())
+        .unwrap_or(path)
+        .to_string()
+}
+
+/// Map a small set of common extensions to MIME types. Returns
+/// `None` for unknowns rather than guessing — clients are free to
+/// sniff if they need finer detail.
+fn guess_content_type(filename: &str) -> Option<String> {
+    let ext = std::path::Path::new(filename)
+        .extension()
+        .and_then(|e| e.to_str())
+        .map(str::to_ascii_lowercase)?;
+    let mime = match ext.as_str() {
+        "txt" | "log" | "md" => "text/plain",
+        "csv" => "text/csv",
+        "tsv" => "text/tab-separated-values",
+        "json" => "application/json",
+        "jsonl" | "ndjson" => "application/x-ndjson",
+        "html" | "htm" => "text/html",
+        "xml" => "application/xml",
+        "yaml" | "yml" => "application/yaml",
+        "toml" => "application/toml",
+        "pdf" => "application/pdf",
+        "png" => "image/png",
+        "jpg" | "jpeg" => "image/jpeg",
+        "gif" => "image/gif",
+        "webp" => "image/webp",
+        "svg" => "image/svg+xml",
+        "zip" => "application/zip",
+        "gz" | "tgz" => "application/gzip",
+        "tar" => "application/x-tar",
+        "wav" => "audio/wav",
+        "mp3" => "audio/mpeg",
+        "mp4" => "video/mp4",
+        "py" => "text/x-python",
+        "js" => "text/javascript",
+        "ts" => "text/typescript",
+        "css" => "text/css",
+        _ => return None,
+    };
+    Some(mime.to_string())
+}
+
+/// Parse `sha256sum`'s output format: `<64-hex>  <path>` per line.
+/// Tolerates the busybox/coreutils binary-flag variants (`*` prefix).
+fn parse_sha256sum_output(output: &str) -> HashMap<String, [u8; 32]> {
+    let mut map = HashMap::new();
+    for line in output.lines() {
+        let line = line.trim_end();
+        if line.is_empty() {
+            continue;
+        }
+        // Hash, two spaces (or space + `*` for binary), then path.
+        let Some((hash_str, rest)) = line.split_once(' ') else {
+            continue;
+        };
+        if hash_str.len() != 64 {
+            continue;
+        }
+        let path = rest.trim_start_matches([' ', '*']);
+        let mut bytes = [0u8; 32];
+        let Ok(()) = hex::decode_to_slice(hash_str, &mut bytes) else {
+            continue;
+        };
+        map.insert(path.to_string(), bytes);
+    }
+    map
+}
+
+/// Convenience: compute sha256 of a byte slice. Used by
+/// `ingest_user_files` to seed the snapshot map for staged inputs.
+pub fn sha256_bytes(data: &[u8]) -> [u8; 32] {
+    let mut h = Sha256::new();
+    h.update(data);
+    let out = h.finalize();
+    let mut arr = [0u8; 32];
+    arr.copy_from_slice(&out);
+    arr
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_coreutils_sha256sum_lines() {
+        let raw = "\
+e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  /mnt/data/empty.txt\n\
+abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd  /mnt/data/sub/foo.bin\n";
+        let map = parse_sha256sum_output(raw);
+        assert_eq!(map.len(), 2);
+        assert!(map.contains_key("/mnt/data/empty.txt"));
+        assert!(map.contains_key("/mnt/data/sub/foo.bin"));
+    }
+
+    #[test]
+    fn parses_busybox_binary_flag_lines() {
+        // busybox sha256sum emits a `*` before the path for binary mode.
+        let raw =
+            "1111111111111111111111111111111111111111111111111111111111111111 */mnt/data/a.bin\n";
+        let map = parse_sha256sum_output(raw);
+        assert_eq!(map.len(), 1);
+        assert!(map.contains_key("/mnt/data/a.bin"));
+    }
+
+    #[test]
+    fn skips_malformed_lines() {
+        let raw = "garbage\n\nshorthash  /mnt/data/x\nffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff  /mnt/data/ok\n";
+        let map = parse_sha256sum_output(raw);
+        assert_eq!(map.len(), 1);
+        assert!(map.contains_key("/mnt/data/ok"));
+    }
+
+    #[test]
+    fn guesses_common_content_types() {
+        assert_eq!(guess_content_type("foo.csv"), Some("text/csv".to_string()));
+        assert_eq!(guess_content_type("a.PNG"), Some("image/png".to_string()));
+        assert_eq!(guess_content_type("README"), None);
+        assert_eq!(guess_content_type("a.unknown"), None);
+    }
+
+    #[test]
+    fn filename_extraction_handles_trailing_slash() {
+        assert_eq!(filename_from_path("/mnt/data/sub/foo.txt"), "foo.txt");
+        assert_eq!(filename_from_path("/mnt/data/foo.txt"), "foo.txt");
+    }
+
+    #[test]
+    fn ids_have_expected_prefixes() {
+        let c = new_container_id();
+        let f = new_file_id();
+        assert!(c.starts_with("cntr_"));
+        assert!(f.starts_with("cfile_"));
+        assert_eq!(c.len(), 5 + 32);
+        assert_eq!(f.len(), 6 + 32);
+    }
+}
diff --git a/src/services/containers.rs b/src/services/containers.rs
new file mode 100644
index 0000000..c2bab42
--- /dev/null
+++ b/src/services/containers.rs
@@ -0,0 +1,854 @@
+//! Service layer for the container + container_files persistence
+//! layer. Sits between the in-memory `ContainerSession` and the
+//! database repos.
+//!
+//! Write-through every captured file and expose read paths for the
+//! `/v1/containers/*` GET endpoints. Where the bytes physically live is
+//! governed by `[storage.container_files]`: the `database` backend keeps
+//! them inline in `container_files.file_data` (simple, scales poorly),
+//! while `filesystem` / `s3` offload the bytes to a [`FileStorage`]
+//! backend and persist only a `storage_path` reference on the row. The
+//! row's `storage_backend` column records which path produced it so reads
+//! route correctly even if the operator later switches backends.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::sync::Arc;
+
+use bytes::Bytes;
+use chrono::Utc;
+use sha2::{Digest, Sha256};
+use thiserror::Error;
+use tracing::{debug, error};
+use uuid::Uuid;
+
+fn sha256_hex(bytes: &[u8]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(bytes);
+    format!("{:x}", hasher.finalize())
+}
+
+use crate::{
+    api_types::responses::{ContainerFileRef, ContainerFileSource},
+    db::{
+        DbError, DbPool,
+        repos::{
+            ContainerFileRecord, ContainerFileSourceKind, ContainerRecord, ContainersRepo,
+            NewContainer, NewContainerFile, ResponseOwner, truncate_to_millis,
+        },
+    },
+    models::StorageBackend,
+    services::{FileStorage, FileStorageError},
+};
+
+/// Errors emitted by `ContainersService`. Distinct from `DbError` so
+/// route handlers can map cleanly to HTTP status codes.
+#[derive(Debug, Error)]
+pub enum ContainersServiceError {
+    #[error("container not found")]
+    NotFound,
+    /// Container row exists but is no longer reusable. The caller
+    /// should surface this as `410 Gone` (matching OpenAI's
+    /// "expired containers cannot be reactivated" semantics) or
+    /// silently fall back to a fresh container, depending on whether
+    /// the reuse was implicit or explicit.
+    #[error("container '{0}' has expired")]
+    Expired(String),
+    #[error("database error: {0}")]
+    Db(String),
+    #[error("file content unavailable: {0}")]
+    ContentUnavailable(String),
+}
+
+impl ContainersServiceError {
+    pub fn error_code(&self) -> &'static str {
+        match self {
+            Self::NotFound => "not_found",
+            Self::Expired(_) => "container_expired",
+            Self::Db(_) => "internal_error",
+            Self::ContentUnavailable(_) => "file_content_unavailable",
+        }
+    }
+}
+
+impl From<DbError> for ContainersServiceError {
+    fn from(e: DbError) -> Self {
+        match e {
+            DbError::NotFound => Self::NotFound,
+            other => Self::Db(other.to_string()),
+        }
+    }
+}
+
+pub type ContainersServiceResult<T> = Result<T, ContainersServiceError>;
+
+/// One file ready to be persisted into the `container_files` table.
+/// Mirrors `ContainerFileRef` plus the raw content + provenance.
+#[derive(Debug, Clone)]
+pub struct PersistFileInput {
+    /// Stable id the in-memory session already published in
+    /// annotations + SSE events. Service uses it as the new row's
+    /// PK on first insert; on overwrite the repo's UPSERT keeps the
+    /// existing row's id so the published id stays valid.
+    pub file_id: String,
+    pub path: String,
+    pub filename: String,
+    pub content_type: Option<String>,
+    pub source: ContainerFileSource,
+    /// File bytes. Routed through the configured `[storage.container_files]`
+    /// [`FileStorage`] backend: stored inline in the row for the `database`
+    /// backend, or offloaded to `filesystem` / `s3` with only a
+    /// `storage_path` kept on the row.
+    pub content: Bytes,
+    pub content_hash_hex: String,
+    pub source_response_id: Option<String>,
+    pub source_call_id: Option<String>,
+}
+
+#[derive(Clone)]
+pub struct ContainersService {
+    db: Arc<DbPool>,
+    /// Where container-file bytes live, from `[storage.container_files]`.
+    /// The `database` backend is a thin shim that stores nothing here and
+    /// signals the row to keep bytes inline; `filesystem` / `s3` persist the
+    /// bytes and return a `storage_path`.
+    file_storage: Arc<dyn FileStorage>,
+    /// The configured backend, recorded on every row this service writes so
+    /// reads can route without re-deriving it. Derived from
+    /// `file_storage.backend_name()` at construction.
+    storage_backend: StorageBackend,
+}
+
+impl ContainersService {
+    pub fn new(db: Arc<DbPool>, file_storage: Arc<dyn FileStorage>) -> Self {
+        let storage_backend = file_storage
+            .backend_name()
+            .parse()
+            .unwrap_or(StorageBackend::Database);
+        Self {
+            db,
+            file_storage,
+            storage_backend,
+        }
+    }
+
+    fn repo(&self) -> Arc<dyn ContainersRepo> {
+        self.db.containers()
+    }
+
+    /// Persist `content` to the configured backend and return the column
+    /// values for the new row: the recorded `storage_backend`, the inline
+    /// `file_data` (only for the `database` backend), and the external
+    /// `storage_path` (only for `filesystem` / `s3`).
+    ///
+    /// The two are mutually exclusive — the `database` shim returns `None`
+    /// from `store()`, every external backend returns `Some(path)`.
+    async fn stage_content(
+        &self,
+        file_id: &str,
+        content: &[u8],
+    ) -> ContainersServiceResult<(StorageBackend, Option<Vec<u8>>, Option<String>)> {
+        let storage_path = self
+            .file_storage
+            .store(file_id, content)
+            .await
+            .map_err(|e| {
+                ContainersServiceError::ContentUnavailable(format!(
+                    "failed to store container file via {} backend: {e}",
+                    self.storage_backend.as_str()
+                ))
+            })?;
+        match storage_path {
+            Some(path) => Ok((self.storage_backend, None, Some(path))),
+            None => Ok((StorageBackend::Database, Some(content.to_vec()), None)),
+        }
+    }
+
+    /// Fetch the bytes for an external-backend (`filesystem` / `s3`) record.
+    /// Returns `Ok(None)` when the underlying object is gone so callers can
+    /// mirror the "metadata-only row" handling used for dropped DB content.
+    async fn read_external(
+        &self,
+        record: &ContainerFileRecord,
+    ) -> ContainersServiceResult<Option<Vec<u8>>> {
+        // Prefer the stored path; fall back to the file id so a backend that
+        // derives keys from ids (S3 without an explicit path) still resolves.
+        let key = record.storage_path.as_deref().unwrap_or(&record.id);
+        match self.file_storage.retrieve(key).await {
+            Ok(bytes) => Ok(Some(bytes)),
+            Err(FileStorageError::NotFound(_)) => Ok(None),
+            Err(e) => Err(ContainersServiceError::ContentUnavailable(e.to_string())),
+        }
+    }
+
+    /// Insert a container row for a freshly-started session. Caller
+    /// supplies the `cntr_…` id (already emitted in `output_files`
+    /// references / `container_file_citation` annotations) and the
+    /// owner derived from the request principal.
+    pub async fn provision(
+        &self,
+        container_id: String,
+        org_id: Uuid,
+        owner: ResponseOwner,
+        runtime_label: impl Into<String>,
+        source_response_id: Option<String>,
+        idle_ttl_secs: i64,
+    ) -> ContainersServiceResult<ContainerRecord> {
+        let created_at = truncate_to_millis(Utc::now());
+        let new = NewContainer::from_owner(
+            container_id,
+            org_id,
+            owner,
+            runtime_label,
+            source_response_id,
+            idle_ttl_secs,
+            created_at,
+        );
+        let record = self.repo().insert(new).await?;
+        debug!(
+            stage = "container_provisioned",
+            container_id = %record.id,
+            org_id = %record.org_id,
+            "Inserted containers row"
+        );
+        Ok(record)
+    }
+
+    /// `POST /v1/containers` — create an unattached container row.
+    /// The VM is not booted yet; the row's `network_policy_json` /
+    /// `memory_limit_mb` / `skill_ids_json` are picked up when the
+    /// first response references this container.
+    #[allow(clippy::too_many_arguments)]
+    pub async fn create_explicit(
+        &self,
+        container_id: String,
+        org_id: Uuid,
+        owner: ResponseOwner,
+        runtime_label: impl Into<String>,
+        idle_ttl_secs: i64,
+        name: Option<String>,
+        memory_limit_mb: Option<i64>,
+        network_policy_json: Option<String>,
+        skill_ids_json: Option<String>,
+    ) -> ContainersServiceResult<ContainerRecord> {
+        let created_at = truncate_to_millis(Utc::now());
+        let mut new = NewContainer::from_owner(
+            container_id,
+            org_id,
+            owner,
+            runtime_label,
+            None,
+            idle_ttl_secs,
+            created_at,
+        );
+        new.name = name;
+        new.memory_limit_mb = memory_limit_mb;
+        new.network_policy_json = network_policy_json;
+        new.skill_ids_json = skill_ids_json;
+        let record = self.repo().insert(new).await?;
+        debug!(
+            stage = "container_created",
+            container_id = %record.id,
+            org_id = %record.org_id,
+            "Created container via POST /v1/containers"
+        );
+        Ok(record)
+    }
+
+    /// Persist a batch of captured files. Errors on individual rows
+    /// are logged + skipped so a single bad row doesn't lose the
+    /// rest. Returns the canonical records (with the repo's view of
+    /// the id, after any UPSERT collision).
+    pub async fn persist_files(
+        &self,
+        container_id: &str,
+        org_id: Uuid,
+        files: Vec<PersistFileInput>,
+    ) -> ContainersServiceResult<Vec<ContainerFileRecord>> {
+        let repo = self.repo();
+        let mut out = Vec::with_capacity(files.len());
+        for input in files {
+            let (storage_backend, file_data, storage_path) =
+                match self.stage_content(&input.file_id, &input.content).await {
+                    Ok(staged) => staged,
+                    Err(e) => {
+                        error!(
+                            stage = "container_file_store_failed",
+                            container_id,
+                            path = %input.path,
+                            file_id = %input.file_id,
+                            error = %e,
+                            "Failed to store container file bytes; skipping"
+                        );
+                        continue;
+                    }
+                };
+            let new = NewContainerFile {
+                id: input.file_id.clone(),
+                container_id: container_id.to_string(),
+                org_id,
+                path: input.path.clone(),
+                filename: input.filename,
+                size_bytes: input.content.len() as i64,
+                content_type: input.content_type,
+                content_hash: input.content_hash_hex,
+                source: match input.source {
+                    ContainerFileSource::User => ContainerFileSourceKind::User,
+                    ContainerFileSource::Assistant => ContainerFileSourceKind::Assistant,
+                },
+                storage_backend,
+                file_data,
+                storage_path,
+                source_response_id: input.source_response_id,
+                source_call_id: input.source_call_id,
+                created_at: truncate_to_millis(Utc::now()),
+            };
+            match repo.upsert_file(new).await {
+                Ok(rec) => out.push(rec),
+                Err(e) => {
+                    error!(
+                        stage = "container_file_upsert_failed",
+                        container_id,
+                        path = %input.path,
+                        file_id = %input.file_id,
+                        error = %e,
+                        "Failed to persist container file; skipping"
+                    );
+                }
+            }
+        }
+        Ok(out)
+    }
+
+    /// Org-scoped container lookup.
+    pub async fn get_container(
+        &self,
+        id: &str,
+        org_id: Uuid,
+    ) -> ContainersServiceResult<ContainerRecord> {
+        self.repo()
+            .get_by_id_and_org(id, org_id)
+            .await?
+            .ok_or(ContainersServiceError::NotFound)
+    }
+
+    /// List containers in an org, newest first. Fetches `limit + 1`
+    /// rows so the handler can derive `has_more` without a second
+    /// query.
+    pub async fn list_containers(
+        &self,
+        org_id: Uuid,
+        limit: i64,
+        after: Option<&str>,
+    ) -> ContainersServiceResult<Vec<ContainerRecord>> {
+        Ok(self.repo().list_by_org(org_id, limit, after).await?)
+    }
+
+    /// Get-or-create a container row by id. Used at attach time: the
+    /// pipeline pre-picks a `cntr_…` (either from the
+    /// `previous_response_id` chain or freshly generated) and asks
+    /// the service to materialise the row.
+    ///
+    /// Returns `Err(Expired)` when the row exists but isn't reusable
+    /// (`expired` or `deleted`). Returns the resolved record
+    /// otherwise.
+    pub async fn ensure_container(
+        &self,
+        container_id: String,
+        org_id: Uuid,
+        owner: ResponseOwner,
+        runtime_label: impl Into<String>,
+        source_response_id: Option<String>,
+        idle_ttl_secs: i64,
+    ) -> ContainersServiceResult<ContainerRecord> {
+        if let Some(existing) = self.repo().get_by_id_and_org(&container_id, org_id).await? {
+            return match existing.status {
+                crate::db::repos::ContainerStatus::Active => Ok(existing),
+                crate::db::repos::ContainerStatus::Expired => {
+                    Err(ContainersServiceError::Expired(container_id))
+                }
+                crate::db::repos::ContainerStatus::Deleted => Err(ContainersServiceError::NotFound),
+            };
+        }
+        self.provision(
+            container_id,
+            org_id,
+            owner,
+            runtime_label,
+            source_response_id,
+            idle_ttl_secs,
+        )
+        .await
+    }
+
+    /// Org-scoped file metadata lookup.
+    pub async fn get_file(
+        &self,
+        file_id: &str,
+        org_id: Uuid,
+    ) -> ContainersServiceResult<ContainerFileRecord> {
+        self.repo()
+            .get_file_by_id_and_org(file_id, org_id)
+            .await?
+            .ok_or(ContainersServiceError::NotFound)
+    }
+
+    /// Org-scoped file content read. Routes by the row's recorded
+    /// `storage_backend`: `database` reads the inline `file_data` column,
+    /// `filesystem` / `s3` fetch the bytes from the configured
+    /// [`FileStorage`] backend by `storage_path`.
+    pub async fn read_content(
+        &self,
+        file_id: &str,
+        org_id: Uuid,
+    ) -> ContainersServiceResult<Vec<u8>> {
+        let record = self.get_file(file_id, org_id).await?;
+        match record.storage_backend {
+            StorageBackend::Database => self
+                .repo()
+                .read_file_data(file_id, org_id)
+                .await?
+                .ok_or_else(|| {
+                    ContainersServiceError::ContentUnavailable(
+                        "row exists but file_data is NULL".into(),
+                    )
+                }),
+            StorageBackend::Filesystem | StorageBackend::S3 => {
+                self.read_external(&record).await?.ok_or_else(|| {
+                    ContainersServiceError::ContentUnavailable(format!(
+                        "{} object for container file is missing",
+                        record.storage_backend.as_str()
+                    ))
+                })
+            }
+        }
+    }
+
+    /// Org-scoped listing inside one container.
+    pub async fn list_files(
+        &self,
+        container_id: &str,
+        org_id: Uuid,
+        limit: i64,
+    ) -> ContainersServiceResult<Vec<ContainerFileRecord>> {
+        Ok(self
+            .repo()
+            .list_files_by_container(container_id, org_id, limit)
+            .await?)
+    }
+
+    /// Used by `ContainerSession::replay_from_db` to enumerate every
+    /// file under a container at reattach time. Skips the org gate
+    /// because the caller already validated org access through the
+    /// `containers` row.
+    pub async fn list_files_for_replay(
+        &self,
+        container_id: &str,
+    ) -> ContainersServiceResult<Vec<ContainerFileRecord>> {
+        Ok(self.repo().list_files_for_replay(container_id).await?)
+    }
+
+    /// Used by `ContainerSession::replay_from_db` to fetch raw bytes
+    /// at reattach time. Same rationale as `list_files_for_replay` —
+    /// skips the org gate because the caller has already authorized
+    /// via the parent container row. Takes the already-fetched record so
+    /// it can route by `storage_backend` without a second metadata query.
+    pub async fn read_content_for_replay(
+        &self,
+        record: &ContainerFileRecord,
+    ) -> ContainersServiceResult<Option<Vec<u8>>> {
+        match record.storage_backend {
+            StorageBackend::Database => Ok(self
+                .repo()
+                .read_file_data_for_replay(&record.container_id, &record.id)
+                .await?),
+            StorageBackend::Filesystem | StorageBackend::S3 => self.read_external(record).await,
+        }
+    }
+
+    /// Patch lifecycle fields on a container row, org-scoped.
+    pub async fn update_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        patch: crate::db::repos::ContainerPatch,
+    ) -> ContainersServiceResult<Option<ContainerRecord>> {
+        Ok(self.repo().update_within_org(id, org_id, patch).await?)
+    }
+
+    /// Touch `last_active_at` so the reaper doesn't expire a busy
+    /// container and the containers API surfaces a moving `expires_at`.
+    /// Called by `ContainerSession::exec` after every successful shell
+    /// command. Truncates to millis to match every other container
+    /// timestamp write (cursor-comparison safety).
+    pub async fn touch_last_active(&self, id: &str, org_id: Uuid) -> ContainersServiceResult<()> {
+        let patch = crate::db::repos::ContainerPatch {
+            last_active_at: Some(truncate_to_millis(Utc::now())),
+            ..Default::default()
+        };
+        self.update_within_org(id, org_id, patch).await?;
+        Ok(())
+    }
+
+    /// Atomically mark idle containers as `expired`. Called by the
+    /// reaper job. Returns the ids that just transitioned so the
+    /// caller can drop their entries from the in-memory registry.
+    pub async fn mark_expired_idle(
+        &self,
+        now: chrono::DateTime<chrono::Utc>,
+    ) -> ContainersServiceResult<Vec<String>> {
+        Ok(self.repo().mark_expired_idle(now).await?)
+    }
+
+    /// Return the subset of `ids` whose container row is terminal
+    /// (`expired` / `deleted`). The reaper calls this on every replica
+    /// to evict process-local sessions whose rows another replica
+    /// already expired.
+    pub async fn expired_among(&self, ids: &[String]) -> ContainersServiceResult<Vec<String>> {
+        Ok(self.repo().expired_among(ids).await?)
+    }
+
+    /// Hard-delete terminal (`expired` / `deleted`) containers whose
+    /// `expires_at` is at or before `cutoff`, cascading their
+    /// `container_files`. Called by the cleanup job. Returns the ids that
+    /// were removed so the caller can log/meter them. At most `limit`
+    /// rows are deleted per call.
+    pub async fn hard_delete_expired(
+        &self,
+        cutoff: chrono::DateTime<chrono::Utc>,
+        limit: i64,
+    ) -> ContainersServiceResult<Vec<String>> {
+        let outcome = self.repo().hard_delete_expired(cutoff, limit).await?;
+        // Best-effort external cleanup, mirroring `delete_file`: the rows are
+        // already gone (atomically, in the repo), so a storage hiccup orphans
+        // bytes rather than failing the GC pass. Without this the bulk path
+        // leaks every filesystem/S3 object forever (the cascade only drops
+        // the DB rows).
+        for file in &outcome.file_objects {
+            if !matches!(
+                file.storage_backend,
+                StorageBackend::Filesystem | StorageBackend::S3
+            ) {
+                continue;
+            }
+            let key = file.storage_path.as_deref().unwrap_or(&file.file_id);
+            if let Err(e) = self.file_storage.delete(key).await {
+                error!(
+                    stage = "container_file_storage_delete_failed",
+                    file_id = %file.file_id,
+                    backend = file.storage_backend.as_str(),
+                    error = %e,
+                    "Hard-deleted container_files row but failed to remove backing object"
+                );
+            }
+        }
+        Ok(outcome.container_ids)
+    }
+
+    /// Org-scoped delete of one container_file row. Returns
+    /// `NotFound` when the row doesn't exist (or belongs to a
+    /// different container / org).
+    pub async fn delete_file(
+        &self,
+        container_id: &str,
+        file_id: &str,
+        org_id: Uuid,
+    ) -> ContainersServiceResult<()> {
+        // Capture the storage location before dropping the row so we can
+        // clean up an external object. Tolerate a missing record here — the
+        // delete below is the authoritative not-found check.
+        let record = self.get_file(file_id, org_id).await.ok();
+        let removed = self
+            .repo()
+            .delete_file_by_id_and_org(file_id, container_id, org_id)
+            .await?;
+        if !removed {
+            return Err(ContainersServiceError::NotFound);
+        }
+        // Best-effort external cleanup. The row is already gone, so a storage
+        // hiccup orphans bytes rather than failing the API call — log and move
+        // on instead of resurrecting a deleted file.
+        if let Some(record) = record
+            && matches!(
+                record.storage_backend,
+                StorageBackend::Filesystem | StorageBackend::S3
+            )
+        {
+            let key = record.storage_path.as_deref().unwrap_or(&record.id);
+            if let Err(e) = self.file_storage.delete(key).await {
+                error!(
+                    stage = "container_file_storage_delete_failed",
+                    container_id,
+                    file_id,
+                    backend = record.storage_backend.as_str(),
+                    error = %e,
+                    "Deleted container_files row but failed to remove backing object"
+                );
+            }
+        }
+        Ok(())
+    }
+
+    /// Upsert one file under an existing container. Used by
+    /// `POST /v1/containers/{id}/files`. Returns the canonical record
+    /// (the repo's view of the row, post-conflict resolution).
+    #[allow(clippy::too_many_arguments)] // each arg is load-bearing for the persisted row
+    pub async fn upload_file(
+        &self,
+        container_id: &str,
+        org_id: Uuid,
+        path: String,
+        filename: String,
+        content_type: Option<String>,
+        content: Vec<u8>,
+        source: ContainerFileSource,
+        source_response_id: Option<String>,
+        source_call_id: Option<String>,
+    ) -> ContainersServiceResult<ContainerFileRecord> {
+        // Compute a sha256 of the bytes; this is what the
+        // capture/exec paths persist so an uploaded file behaves the
+        // same as a captured one downstream.
+        let content_hash_hex = sha256_hex(&content);
+        let file_id = format!("cfile_{}", uuid::Uuid::new_v4().simple());
+        let now = truncate_to_millis(Utc::now());
+        let (storage_backend, file_data, storage_path) =
+            self.stage_content(&file_id, &content).await?;
+        let new = NewContainerFile {
+            id: file_id,
+            container_id: container_id.to_string(),
+            org_id,
+            path,
+            filename,
+            size_bytes: content.len() as i64,
+            content_type,
+            content_hash: content_hash_hex,
+            source: match source {
+                ContainerFileSource::User => ContainerFileSourceKind::User,
+                ContainerFileSource::Assistant => ContainerFileSourceKind::Assistant,
+            },
+            storage_backend,
+            file_data,
+            storage_path,
+            source_response_id,
+            source_call_id,
+            created_at: now,
+        };
+        Ok(self.repo().upsert_file(new).await?)
+    }
+
+    /// Stamp the `container_id` column on a `responses` row so the
+    /// next request that chains via `previous_response_id` can find
+    /// the container to reattach to. No-ops for `response_id == None`
+    /// (in-memory / no-persistence runs) — the row doesn't exist.
+    pub async fn link_response_to_container(
+        &self,
+        response_id: &str,
+        container_id: &str,
+        org_id: Uuid,
+    ) -> ContainersServiceResult<()> {
+        let patch = crate::db::repos::ResponseCompletion {
+            container_id: Some(container_id.to_string()),
+            ..Default::default()
+        };
+        self.db
+            .responses()
+            .update_within_org(response_id, org_id, patch)
+            .await
+            .map_err(|e| ContainersServiceError::Db(e.to_string()))?;
+        Ok(())
+    }
+}
+
+/// Render a `ContainerFileRecord` into the API-facing
+/// `ContainerFileRef` shape so handlers can return one type from both
+/// in-memory + persisted code paths.
+pub fn record_to_api_ref(record: &ContainerFileRecord) -> ContainerFileRef {
+    let source = match record.source {
+        ContainerFileSourceKind::User => ContainerFileSource::User,
+        ContainerFileSourceKind::Assistant => ContainerFileSource::Assistant,
+    };
+    ContainerFileRef {
+        container_id: record.container_id.clone(),
+        file_id: record.id.clone(),
+        filename: record.filename.clone(),
+        path: record.path.clone(),
+        bytes: record.size_bytes.max(0) as u64,
+        content_type: record.content_type.clone(),
+        source,
+    }
+}
+
+#[cfg(all(test, feature = "database-sqlite", feature = "server"))]
+mod tests {
+    use tempfile::TempDir;
+    use uuid::Uuid;
+
+    use super::*;
+    use crate::{
+        config::FilesystemStorageConfig,
+        db::{DbPool, repos::ResponseOwner, tests::harness},
+        models::CreateOrganization,
+        services::{DatabaseFileStorage, FilesystemFileStorage},
+    };
+
+    /// Stand up an in-memory SQLite DbPool with a seeded org + an active
+    /// container, ready for file persistence assertions.
+    async fn seed() -> (Arc<DbPool>, Uuid, String) {
+        let pool = harness::create_sqlite_pool().await;
+        harness::run_sqlite_migrations(&pool).await;
+        let db = Arc::new(DbPool::from_sqlite(pool));
+
+        let org = db
+            .organizations()
+            .create(CreateOrganization {
+                slug: "acme".to_string(),
+                name: "Acme".to_string(),
+            })
+            .await
+            .expect("create org");
+
+        let container_id = format!("cntr_{}", Uuid::new_v4().simple());
+        db.containers()
+            .insert(NewContainer::from_owner(
+                container_id.clone(),
+                org.id,
+                ResponseOwner::Organization(org.id),
+                "test",
+                None,
+                1200,
+                truncate_to_millis(Utc::now()),
+            ))
+            .await
+            .expect("insert container");
+
+        (db, org.id, container_id)
+    }
+
+    async fn upload(
+        svc: &ContainersService,
+        container_id: &str,
+        org_id: Uuid,
+        content: &[u8],
+    ) -> ContainerFileRecord {
+        svc.upload_file(
+            container_id,
+            org_id,
+            "/mnt/data/out.bin".to_string(),
+            "out.bin".to_string(),
+            Some("application/octet-stream".to_string()),
+            content.to_vec(),
+            ContainerFileSource::Assistant,
+            None,
+            None,
+        )
+        .await
+        .expect("upload_file")
+    }
+
+    #[tokio::test]
+    async fn database_backend_stores_inline() {
+        let (db, org_id, container_id) = seed().await;
+        let svc =
+            ContainersService::new(db.clone(), Arc::new(DatabaseFileStorage::new(db.clone())));
+
+        let rec = upload(&svc, &container_id, org_id, b"hello db").await;
+        assert_eq!(rec.storage_backend, StorageBackend::Database);
+        assert!(
+            rec.storage_path.is_none(),
+            "DB backend keeps no storage_path"
+        );
+
+        // Bytes live inline in the row and read back through the service.
+        let inline = db
+            .containers()
+            .read_file_data(&rec.id, org_id)
+            .await
+            .unwrap();
+        assert_eq!(inline.as_deref(), Some(b"hello db".as_ref()));
+        assert_eq!(
+            svc.read_content(&rec.id, org_id).await.unwrap(),
+            b"hello db"
+        );
+    }
+
+    #[tokio::test]
+    async fn filesystem_backend_offloads_bytes() {
+        let (db, org_id, container_id) = seed().await;
+        let dir = TempDir::new().unwrap();
+        let storage = FilesystemFileStorage::new(FilesystemStorageConfig {
+            path: dir.path().to_string_lossy().to_string(),
+            create_dir: true,
+            file_mode: 0o600,
+            dir_mode: 0o700,
+        })
+        .unwrap();
+        let svc = ContainersService::new(db.clone(), Arc::new(storage));
+
+        let rec = upload(&svc, &container_id, org_id, b"hello fs").await;
+
+        // Bytes are offloaded: backend recorded, path set, nothing inline.
+        assert_eq!(rec.storage_backend, StorageBackend::Filesystem);
+        let path = rec
+            .storage_path
+            .as_deref()
+            .expect("filesystem storage_path");
+        assert!(
+            std::path::Path::new(path).exists(),
+            "object written to disk"
+        );
+        let inline = db
+            .containers()
+            .read_file_data(&rec.id, org_id)
+            .await
+            .unwrap();
+        assert!(inline.is_none(), "filesystem backend leaves file_data NULL");
+
+        // Round-trips through the read path.
+        assert_eq!(
+            svc.read_content(&rec.id, org_id).await.unwrap(),
+            b"hello fs"
+        );
+
+        // Replay path resolves the same bytes from the record.
+        let replayed = svc.read_content_for_replay(&rec).await.unwrap();
+        assert_eq!(replayed.as_deref(), Some(b"hello fs".as_ref()));
+
+        // Delete removes both the row and the backing object.
+        svc.delete_file(&container_id, &rec.id, org_id)
+            .await
+            .unwrap();
+        assert!(
+            !std::path::Path::new(path).exists(),
+            "object removed on delete"
+        );
+        assert!(matches!(
+            svc.read_content(&rec.id, org_id).await,
+            Err(ContainersServiceError::NotFound)
+        ));
+    }
+
+    #[tokio::test]
+    async fn missing_filesystem_object_surfaces_unavailable() {
+        let (db, org_id, container_id) = seed().await;
+        let dir = TempDir::new().unwrap();
+        let storage = FilesystemFileStorage::new(FilesystemStorageConfig {
+            path: dir.path().to_string_lossy().to_string(),
+            create_dir: true,
+            file_mode: 0o600,
+            dir_mode: 0o700,
+        })
+        .unwrap();
+        let svc = ContainersService::new(db.clone(), Arc::new(storage));
+
+        let rec = upload(&svc, &container_id, org_id, b"transient").await;
+        // Remove the backing object out from under the row.
+        std::fs::remove_file(rec.storage_path.as_deref().unwrap()).unwrap();
+
+        assert!(matches!(
+            svc.read_content(&rec.id, org_id).await,
+            Err(ContainersServiceError::ContentUnavailable(_))
+        ));
+        // Replay tolerates the gap (metadata-only) rather than erroring.
+        assert!(svc.read_content_for_replay(&rec).await.unwrap().is_none());
+    }
+}
diff --git a/src/services/file_search_tool.rs b/src/services/file_search_tool.rs
index dc36d6d..23fba51 100644
--- a/src/services/file_search_tool.rs
+++ b/src/services/file_search_tool.rs
@@ -31,17 +31,14 @@
 //! 4. Continues the conversation with the provider
 //! 5. Streams the final response to the client
 
-use std::{collections::HashMap, future::Future, pin::Pin, sync::Arc, time::Instant};
+use std::{collections::HashMap, sync::Arc, time::Instant};
 
-use axum::body::Body;
-use bytes::{Bytes, BytesMut};
-use futures_util::StreamExt;
-use http::Response;
+use bytes::Bytes;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use thiserror::Error;
 use tokio::sync::mpsc;
-use tracing::{Instrument, debug, error, info, info_span, instrument, warn};
+use tracing::{debug, error, info, instrument, warn};
 use uuid::Uuid;
 
 use crate::{
@@ -50,7 +47,7 @@ use crate::{
         FileSearchComparisonFilter, FileSearchCompoundFilter, FileSearchFilter,
         FileSearchFilterComparison, FileSearchFilterLogicalType, FileSearchResultContent,
         FileSearchResultItem, FileSearchTool, FunctionCallOutput, FunctionCallOutputType,
-        ResponsesAnnotation, ResponsesIncludable, ResponsesInput, ResponsesInputItem,
+        FunctionTool, ResponsesAnnotation, ResponsesIncludable, ResponsesInput, ResponsesInputItem,
         ResponsesToolDefinition, WebSearchStatus,
     },
     auth::AuthenticatedRequest,
@@ -59,11 +56,7 @@ use crate::{
         AttributeFilter, ComparisonFilter, ComparisonOperator, CompoundFilter, FilterValue,
         LogicalOperator,
     },
-    observability::{
-        metrics::{record_file_search, record_file_search_iteration},
-        otel_span_error, otel_span_ok,
-    },
-    providers::ProviderError,
+    observability::{metrics::record_file_search, otel_span_error, otel_span_ok},
     services::{FileSearchRequest, FileSearchResponse, FileSearchService},
 };
 
@@ -251,7 +244,10 @@ pub fn preprocess_file_search_tools(payload: &mut CreateResponsesPayload) {
         if matches!(tool, ResponsesToolDefinition::FileSearch(_)) {
             // Convert file_search to a function tool
             let function_def = FileSearchToolArguments::function_tool_definition();
-            *tool = ResponsesToolDefinition::Function(function_def);
+            *tool = ResponsesToolDefinition::Function(
+                FunctionTool::from_json(function_def)
+                    .expect("file_search function-tool definition is well-formed"),
+            );
             debug!(
                 stage = "tool_preprocessed",
                 "Preprocessed file_search tool to function definition for OpenAI-compatible provider"
@@ -427,26 +423,6 @@ impl FileSearchAuthContext {
     }
 }
 
-/// Type alias for the provider callback function.
-///
-/// This callback is used to send continuation requests to the provider
-/// after executing file_search tool calls.
-#[cfg(not(target_arch = "wasm32"))]
-pub type ProviderCallback = Arc<
-    dyn Fn(
-            CreateResponsesPayload,
-        ) -> Pin<Box<dyn Future<Output = Result<Response<Body>, ProviderError>> + Send>>
-        + Send
-        + Sync,
->;
-
-#[cfg(target_arch = "wasm32")]
-pub type ProviderCallback = Arc<
-    dyn Fn(
-        CreateResponsesPayload,
-    ) -> Pin<Box<dyn Future<Output = Result<Response<Body>, ProviderError>>>>,
->;
-
 /// Errors that can occur during file search middleware processing.
 #[derive(Debug, Error)]
 #[allow(dead_code)] // Variants will be used as implementation grows
@@ -637,6 +613,7 @@ impl CitationTracker {
             ResponsesAnnotation::FileCitation { index, .. } => *index,
             ResponsesAnnotation::UrlCitation { start_index, .. } => *start_index,
             ResponsesAnnotation::FilePath { index, .. } => *index,
+            ResponsesAnnotation::ContainerFileCitation { start_index, .. } => *start_index,
         });
 
         annotations
@@ -647,102 +624,6 @@ impl CitationTracker {
 // SSE Frame Buffer
 // ─────────────────────────────────────────────────────────────────────────────
 
-/// Buffer for accumulating SSE (Server-Sent Events) data and extracting complete events.
-///
-/// SSE events are delimited by double newlines (`\n\n` or `\r\n\r\n`). TCP chunks may
-/// arrive with events split across boundaries, so this buffer accumulates data until
-/// complete events can be extracted.
-///
-/// # Example
-///
-/// ```ignore
-/// let mut buffer = SseBuffer::new();
-///
-/// // First chunk arrives with partial event
-/// buffer.extend(b"data: {\"type\":");
-/// assert!(buffer.extract_complete_events().is_empty());
-///
-/// // Second chunk completes the event
-/// buffer.extend(b" \"test\"}\n\n");
-/// let events = buffer.extract_complete_events();
-/// assert_eq!(events.len(), 1);
-/// ```
-#[derive(Debug, Default)]
-pub(crate) struct SseBuffer {
-    buffer: BytesMut,
-}
-
-impl SseBuffer {
-    /// Create a new empty SSE buffer.
-    pub(crate) fn new() -> Self {
-        Self {
-            buffer: BytesMut::new(),
-        }
-    }
-
-    /// Append data to the buffer.
-    pub(crate) fn extend(&mut self, data: &[u8]) {
-        self.buffer.extend_from_slice(data);
-    }
-
-    /// Extract all complete SSE events from the buffer.
-    ///
-    /// Returns a vector of complete events (each ending with `\n\n` or `\r\n\r\n`)
-    /// and retains any incomplete data for the next call.
-    pub(crate) fn extract_complete_events(&mut self) -> Vec<Bytes> {
-        let mut events = Vec::new();
-
-        while let Some(end_pos) = self.find_event_boundary() {
-            // Extract the complete event including the delimiter
-            let event = self.buffer.split_to(end_pos);
-            events.push(event.freeze());
-        }
-
-        events
-    }
-
-    /// Find the position of the next event boundary (end of `\n\n` or `\r\n\r\n`).
-    ///
-    /// Returns the position immediately after the delimiter, or None if no
-    /// complete event boundary is found.
-    fn find_event_boundary(&self) -> Option<usize> {
-        let bytes = &self.buffer[..];
-
-        // Look for \n\n (most common)
-        for i in 0..bytes.len().saturating_sub(1) {
-            if bytes[i] == b'\n' && bytes[i + 1] == b'\n' {
-                return Some(i + 2);
-            }
-        }
-
-        // Also check for \r\n\r\n (Windows-style)
-        for i in 0..bytes.len().saturating_sub(3) {
-            if bytes[i] == b'\r'
-                && bytes[i + 1] == b'\n'
-                && bytes[i + 2] == b'\r'
-                && bytes[i + 3] == b'\n'
-            {
-                return Some(i + 4);
-            }
-        }
-
-        None
-    }
-
-    /// Get any remaining incomplete data in the buffer.
-    ///
-    /// This is useful for forwarding partial data when the stream ends
-    /// or when we need to pass through data that couldn't be parsed.
-    pub(crate) fn take_remaining(&mut self) -> Bytes {
-        self.buffer.split().freeze()
-    }
-
-    /// Check if the buffer is empty.
-    pub(crate) fn is_empty(&self) -> bool {
-        self.buffer.is_empty()
-    }
-}
-
 /// Context for file search middleware operations.
 #[derive(Clone)]
 pub struct FileSearchContext {
@@ -757,8 +638,6 @@ pub struct FileSearchContext {
     pub tool_definitions: Vec<FileSearchTool>,
     /// The original request payload (used to build continuation requests).
     pub original_payload: CreateResponsesPayload,
-    /// Callback to send continuation requests to the provider.
-    pub provider_callback: Option<ProviderCallback>,
 }
 
 impl FileSearchContext {
@@ -776,16 +655,9 @@ impl FileSearchContext {
             auth,
             tool_definitions,
             original_payload,
-            provider_callback: None,
         }
     }
 
-    /// Set the provider callback for multi-turn execution.
-    pub fn with_provider_callback(mut self, callback: ProviderCallback) -> Self {
-        self.provider_callback = Some(callback);
-        self
-    }
-
     /// Check if file search is enabled.
     pub fn is_enabled(&self) -> bool {
         self.config.enabled && !self.tool_definitions.is_empty()
@@ -1425,516 +1297,6 @@ pub fn detect_file_search_in_chunk(
     found_calls
 }
 
-/// Build a continuation payload with the original input plus tool call outputs.
-///
-/// Handles multiple file_search tool calls from a single LLM response by adding
-/// all function call outputs to the payload.
-///
-/// # Arguments
-/// * `original` - The original request payload to clone and modify
-/// * `tool_results` - The tool calls and their results to add to the input
-/// * `is_final_iteration` - If true, removes file_search tools from the payload to force
-///   the model to generate a final text response instead of requesting more tool calls
-#[instrument(skip(original, tool_results), fields(
-    tool_result_count = tool_results.len(),
-    is_final_iteration = is_final_iteration,
-))]
-fn build_continuation_payload(
-    original: &CreateResponsesPayload,
-    tool_results: &[(&FileSearchToolCall, FileSearchToolResult)],
-    is_final_iteration: bool,
-) -> CreateResponsesPayload {
-    let mut payload = original.clone();
-
-    // Build function call output items for all tool calls
-    let function_outputs: Vec<ResponsesInputItem> = tool_results
-        .iter()
-        .map(|(tool_call, tool_result)| {
-            ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
-                type_: FunctionCallOutputType::FunctionCallOutput,
-                id: Some(tool_call.id.clone()),
-                call_id: tool_call.id.clone(),
-                output: tool_result.content.clone(),
-                status: None,
-            })
-        })
-        .collect();
-
-    // Add all function call outputs to the input
-    match payload.input {
-        Some(ResponsesInput::Items(ref mut items)) => {
-            items.extend(function_outputs);
-        }
-        Some(ResponsesInput::Text(text)) => {
-            // Convert text input to items and add all function call outputs
-            let mut items = vec![ResponsesInputItem::EasyMessage(
-                crate::api_types::responses::EasyInputMessage {
-                    type_: None,
-                    role: crate::api_types::responses::EasyInputMessageRole::User,
-                    content: crate::api_types::responses::EasyInputMessageContent::Text(text),
-                },
-            )];
-            items.extend(function_outputs);
-            payload.input = Some(ResponsesInput::Items(items));
-        }
-        None => {
-            payload.input = Some(ResponsesInput::Items(function_outputs));
-        }
-    }
-
-    // On the final iteration, remove file_search tools to force the model to
-    // generate a final text response instead of requesting more tool calls.
-    // This prevents hitting the iteration limit with an unexecuted tool call.
-    if is_final_iteration && let Some(ref mut tools) = payload.tools {
-        let original_count = tools.len();
-        tools.retain(|t| !t.is_file_search());
-        let removed_count = original_count - tools.len();
-        if removed_count > 0 {
-            info!(
-                stage = "tools_removed",
-                removed_count = removed_count,
-                "Removed file_search tools on final iteration to force completion"
-            );
-        }
-        // If no tools remain, set to None to avoid sending empty array
-        if tools.is_empty() {
-            payload.tools = None;
-        }
-    }
-
-    // Ensure streaming is enabled for the continuation
-    payload.stream = true;
-
-    payload
-}
-
-/// Wrap a streaming response with file_search tool interception and multi-turn execution.
-///
-/// This function monitors the stream for file_search tool calls. When detected:
-/// 1. Executes the search against configured vector stores
-/// 2. Builds a continuation payload with the tool result
-/// 3. Sends the continuation request to the provider via the callback
-/// 4. Streams the continuation response to the client
-///
-/// If no provider callback is configured, it falls back to detection-only mode
-/// (logs tool calls but doesn't execute multi-turn).
-pub fn wrap_streaming_with_file_search(
-    response: Response<Body>,
-    context: FileSearchContext,
-) -> Response<Body> {
-    if !context.is_enabled() {
-        return response;
-    }
-
-    let (parts, body) = response.into_parts();
-    let vector_store_ids = context.get_vector_store_ids();
-    let max_iterations = context.config.max_iterations;
-    let has_callback = context.provider_callback.is_some();
-    let include_results = should_include_results(&context.original_payload);
-
-    // Create parent span for the entire file search flow
-    let file_search_span = info_span!(
-        "file_search_stream",
-        vector_store_ids = ?vector_store_ids,
-        max_iterations = max_iterations,
-        has_callback = has_callback,
-    );
-
-    // Create a channel for forwarding chunks
-    let (tx, rx) = mpsc::channel::<Result<Bytes, std::io::Error>>(32);
-
-    // Spawn a task to process the stream, propagating the span context
-    crate::compat::spawn_detached(
-        async move {
-            let mut iteration = 0;
-            let mut current_body = body;
-            // Track citations across all search results for annotation injection
-            let mut citation_tracker = CitationTracker::new();
-            // Cache for query deduplication within this request
-            // Maps cache_key -> FileSearchToolResult to avoid redundant searches
-            let mut query_cache: HashMap<String, FileSearchToolResult> = HashMap::new();
-
-            loop {
-                iteration += 1;
-                let at_iteration_limit = iteration > max_iterations;
-
-                // Create child span for this iteration
-                let iteration_span = info_span!(
-                    "file_search_iteration",
-                    iteration = iteration,
-                    at_limit = at_iteration_limit,
-                );
-                let _iteration_guard = iteration_span.enter();
-
-                let mut body_stream = current_body.into_data_stream();
-                let mut accumulated = BytesMut::new();
-                // Collect all file_search tool calls from this response
-                let mut detected_tool_calls: Vec<FileSearchToolCall> = Vec::new();
-                // SSE buffer to handle events split across TCP chunks
-                let mut sse_buffer = SseBuffer::new();
-
-                // Process the current response stream
-                while let Some(chunk_result) = body_stream.next().await {
-                    match chunk_result {
-                        Ok(chunk) => {
-                            accumulated.extend_from_slice(&chunk);
-                            sse_buffer.extend(&chunk);
-
-                            // Extract complete SSE events from the buffer
-                            let complete_events = sse_buffer.extract_complete_events();
-
-                            for event in complete_events {
-                                // Check for file_search tool calls in this event
-                                // (skip detection if we've hit the iteration limit - we'll forward everything)
-                                if !at_iteration_limit {
-                                    let tool_calls =
-                                        detect_file_search_in_chunk(&event, &vector_store_ids);
-                                    for tool_call in tool_calls {
-                                        info!(
-                                            stage = "tool_call_detected",
-                                            tool_call_id = %tool_call.id,
-                                            query = %tool_call.query,
-                                            vector_store_ids = ?tool_call.vector_store_ids,
-                                            iteration = iteration,
-                                            "Detected file_search tool call in stream"
-                                        );
-                                        detected_tool_calls.push(tool_call);
-                                    }
-
-                                    // If we found tool calls and have a callback,
-                                    // we're accumulating the response, don't forward yet
-                                    if !detected_tool_calls.is_empty() && has_callback {
-                                        continue;
-                                    }
-                                }
-
-                                // Forward the complete event to the client, injecting citations if we have tracked sources
-                                let event_to_send = if !citation_tracker.is_empty() {
-                                    inject_citation_annotations(&event, &citation_tracker)
-                                } else {
-                                    event
-                                };
-                                if tx.send(Ok(event_to_send)).await.is_err() {
-                                    return; // Client disconnected
-                                }
-                            }
-                        }
-                        Err(e) => {
-                            warn!(
-                                stage = "stream_error",
-                                error = %e,
-                                iteration = iteration,
-                                "Error reading stream chunk"
-                            );
-                            let _ = tx.send(Err(std::io::Error::other(e))).await;
-                            return;
-                        }
-                    }
-                }
-
-                // Forward any remaining incomplete data in the SSE buffer
-                // (provider may have sent data without final \n\n)
-                if !sse_buffer.is_empty() {
-                    let remaining = sse_buffer.take_remaining();
-                    if !remaining.is_empty() {
-                        // Only forward if we're not accumulating for tool calls
-                        if detected_tool_calls.is_empty() || !has_callback {
-                            let data_to_send = if !citation_tracker.is_empty() {
-                                inject_citation_annotations(&remaining, &citation_tracker)
-                            } else {
-                                remaining
-                            };
-                            if tx.send(Ok(data_to_send)).await.is_err() {
-                                return; // Client disconnected
-                            }
-                        }
-                    }
-                }
-
-                // If we've hit the iteration limit, we've forwarded the final response above
-                // (tool call detection was skipped, so all chunks were forwarded)
-                if at_iteration_limit {
-                    warn!(
-                        stage = "iteration_limit_reached",
-                        iteration = iteration,
-                        max_iterations = max_iterations,
-                        "Maximum file_search iterations exceeded, forwarding final response"
-                    );
-                    record_file_search_iteration(iteration as u32, true, "limit_reached");
-                    break;
-                }
-
-                // If we detected tool calls, execute them all in parallel and continue
-                if !detected_tool_calls.is_empty() {
-                    let tool_call_count = detected_tool_calls.len();
-
-                    // Emit in_progress events for each tool call to notify the client
-                    for (idx, tool_call) in detected_tool_calls.iter().enumerate() {
-                        let event = format_file_search_in_progress_event(&tool_call.id, idx);
-                        if tx.send(Ok(event)).await.is_err() {
-                            return; // Client disconnected
-                        }
-                    }
-
-                    // Create span for the batch search execution
-                    let batch_search_span = info_span!(
-                        "execute_batch_searches",
-                        tool_call_count = tool_call_count,
-                        iteration = iteration,
-                    );
-                    let _batch_guard = batch_search_span.enter();
-
-                    info!(
-                        stage = "batch_search_starting",
-                        tool_call_count = tool_call_count,
-                        iteration = iteration,
-                        "Executing {} file_search tool calls in parallel",
-                        tool_call_count
-                    );
-
-                    // Emit searching events as we start the actual search
-                    for (idx, tool_call) in detected_tool_calls.iter().enumerate() {
-                        let event = format_file_search_searching_event(&tool_call.id, idx);
-                        if tx.send(Ok(event)).await.is_err() {
-                            return; // Client disconnected
-                        }
-                    }
-
-                    // Execute all searches in parallel
-                    // First, separate cached vs uncached to minimize redundant work
-                    let search_futures: Vec<_> = detected_tool_calls
-                        .iter()
-                        .enumerate()
-                        .map(|(idx, tool_call)| {
-                            let cache_key = tool_call.cache_key();
-                            let cached = query_cache.get(&cache_key).cloned();
-                            let ctx = context.clone();
-                            let tc = tool_call.clone();
-
-                            // Create child span for each individual search
-                            let search_span = info_span!(
-                                "execute_single_search",
-                                search_index = idx,
-                                tool_call_id = %tc.id,
-                                query = %tc.query,
-                                cache_hit = cached.is_some(),
-                            );
-
-                            async move {
-                                if let Some(cached_result) = cached {
-                                    info!(
-                                        stage = "search_completed",
-                                        tool_call_id = %tc.id,
-                                        query = %tc.query,
-                                        result_count = cached_result.result_count,
-                                        vector_stores_searched = cached_result.vector_stores_searched,
-                                        cache_hit = true,
-                                        duration_ms = 0_u64,
-                                        "Returning cached file search result (duplicate query)"
-                                    );
-                                    // Record cache hit metric (duration ~0 for cached result)
-                                    record_file_search(
-                                        "success",
-                                        0.0,
-                                        cached_result.result_count as u32,
-                                        cached_result.vector_stores_searched as u32,
-                                        true, // cache_hit = true
-                                    );
-                                    let tool_call_id = tc.id.clone();
-                                    Ok((
-                                        tc,
-                                        FileSearchToolResult {
-                                            tool_call_id,
-                                            ..cached_result
-                                        },
-                                        None, // No cache key to update
-                                    ))
-                                } else {
-                                    match ctx.execute_search(&tc).await {
-                                        Ok(result) => {
-                                            // execute_search already logs search_completed
-                                            Ok((tc, result, Some(cache_key)))
-                                        }
-                                        Err(e) => {
-                                            // execute_search already logs the error
-                                            Err(e)
-                                        }
-                                    }
-                                }
-                            }
-                            .instrument(search_span)
-                        })
-                        .collect();
-
-                    let search_results = futures_util::future::join_all(search_futures).await;
-
-                    // Process results: check for failures, update cache, emit to client
-                    let mut successful_results: Vec<(&FileSearchToolCall, FileSearchToolResult)> =
-                        Vec::new();
-                    let mut had_failure = false;
-
-                    for result in search_results {
-                        match result {
-                            Ok((tool_call, search_result, cache_key_opt)) => {
-                                // Update cache for newly executed searches
-                                if let Some(cache_key) = cache_key_opt {
-                                    query_cache.insert(cache_key, search_result.clone());
-                                }
-
-                                // Track sources for citation annotation
-                                if let Some(ref raw_response) = search_result.raw_response {
-                                    citation_tracker.add_from_response(raw_response);
-                                    debug!(
-                                        stage = "citations_tracked",
-                                        tool_call_id = %tool_call.id,
-                                        source_count = raw_response.results.len(),
-                                        "Added search results to citation tracker"
-                                    );
-
-                                    // Emit file_search_call output item to the client
-                                    let file_search_call_output = build_file_search_call_output(
-                                        &tool_call.id,
-                                        &tool_call.query,
-                                        raw_response,
-                                        include_results,
-                                    );
-
-                                    if let Some(sse_event) =
-                                        format_file_search_call_sse_event(&file_search_call_output)
-                                    {
-                                        debug!(
-                                            stage = "result_emitted",
-                                            tool_call_id = %tool_call.id,
-                                            include_results = include_results,
-                                            "Sending file_search_call output to client"
-                                        );
-                                        if tx.send(Ok(sse_event)).await.is_err() {
-                                            return; // Client disconnected
-                                        }
-                                    }
-
-                                    // Emit completed event for this tool call
-                                    // Find the index of this tool call in the detected list
-                                    let output_index = detected_tool_calls
-                                        .iter()
-                                        .position(|tc| tc.id == tool_call.id)
-                                        .unwrap_or(0);
-                                    let completed_event = format_file_search_completed_event(
-                                        &tool_call.id,
-                                        output_index,
-                                    );
-                                    if tx.send(Ok(completed_event)).await.is_err() {
-                                        return; // Client disconnected
-                                    }
-                                }
-
-                                // Find the original tool call reference for the continuation payload
-                                if let Some(orig_tc) =
-                                    detected_tool_calls.iter().find(|tc| tc.id == tool_call.id)
-                                {
-                                    successful_results.push((orig_tc, search_result));
-                                }
-                            }
-                            Err(_) => {
-                                had_failure = true;
-                            }
-                        }
-                    }
-
-                    // If any search failed, forward accumulated response and stop
-                    if had_failure {
-                        if tx.send(Ok(accumulated.freeze())).await.is_err() {
-                            return;
-                        }
-                        record_file_search_iteration(iteration as u32, true, "error");
-                        break;
-                    }
-
-                    // If we have a callback, make the continuation request with all results
-                    if let Some(ref callback) = context.provider_callback {
-                        // On the final iteration (iteration == max_iterations), remove file_search
-                        // tools from the continuation request to force the model to generate a
-                        // final text response instead of requesting another tool call.
-                        let is_final_iteration = iteration == max_iterations;
-                        let continuation_payload = build_continuation_payload(
-                            &context.original_payload,
-                            &successful_results,
-                            is_final_iteration,
-                        );
-
-                        info!(
-                            stage = "continuation_sent",
-                            tool_call_count = successful_results.len(),
-                            iteration = iteration,
-                            is_final_iteration = is_final_iteration,
-                            "Sending continuation request to provider with {} tool results",
-                            successful_results.len()
-                        );
-
-                        match callback(continuation_payload).await {
-                            Ok(continuation_response) => {
-                                // Continue processing the new response stream
-                                let (_, new_body) = continuation_response.into_parts();
-                                current_body = new_body;
-                                continue; // Go to next iteration of the loop
-                            }
-                            Err(e) => {
-                                error!(
-                                    stage = "continuation_failed",
-                                    iteration = iteration,
-                                    error = %e,
-                                    "Provider continuation request failed"
-                                );
-                                // On provider error, forward accumulated response and stop
-                                if tx.send(Ok(accumulated.freeze())).await.is_err() {
-                                    return;
-                                }
-                                record_file_search_iteration(iteration as u32, true, "error");
-                                break;
-                            }
-                        }
-                    } else {
-                        // No callback - forward accumulated response
-                        debug!(
-                            stage = "no_callback",
-                            iteration = iteration,
-                            "No provider callback configured, forwarding original response"
-                        );
-                        if tx.send(Ok(accumulated.freeze())).await.is_err() {
-                            return;
-                        }
-                        record_file_search_iteration(iteration as u32, true, "no_callback");
-                        break;
-                    }
-                } else {
-                    // No tool calls detected, we're done
-                    debug!(
-                        stage = "stream_completed",
-                        iteration = iteration,
-                        "No tool calls detected, stream complete"
-                    );
-                    record_file_search_iteration(iteration as u32, true, "completed");
-                    break;
-                }
-            }
-
-            debug!(
-                stage = "processing_completed",
-                "File search stream processing completed"
-            );
-        }
-        .instrument(file_search_span),
-    );
-
-    // Create a stream from the receiver using futures_util::stream::unfold
-    let stream = futures_util::stream::unfold(rx, |mut rx| async move {
-        rx.recv().await.map(|item| (item, rx))
-    });
-    let body = Body::from_stream(stream);
-
-    Response::from_parts(parts, body)
-}
-
 /// Check a non-streaming response for file_search tool calls.
 ///
 /// Returns the detected tool calls and whether the response requires
@@ -1987,9 +1349,322 @@ pub fn format_tool_result_json(result: &FileSearchToolResult) -> Value {
     })
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// ServerExecutedTool implementation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// `ServerExecutedTool` implementation for `file_search`.
+///
+/// Wraps a `FileSearchContext` plus per-request shared state (query cache and
+/// citation tracker) so the runner can dispatch concurrent calls against a
+/// single instance while preserving the original wrapper's behaviour.
+#[cfg(not(target_arch = "wasm32"))]
+pub struct FileSearchExecutor {
+    context: FileSearchContext,
+    /// Citation tracker shared across all calls for this request, used by
+    /// `transform_event` to inject `FileCitation` annotations into events
+    /// the model emits after a search has completed.
+    citation_tracker: std::sync::Mutex<CitationTracker>,
+    /// Query cache deduplicates identical searches within one request.
+    query_cache: tokio::sync::Mutex<HashMap<String, FileSearchToolResult>>,
+    /// Hides the rewritten `file_search` function-call plumbing from the
+    /// client stream; the executor emits the spec-shaped
+    /// `file_search_call` items itself.
+    suppressor: crate::services::server_tools::FunctionCallSuppressor,
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+impl FileSearchExecutor {
+    pub fn new(context: FileSearchContext) -> Self {
+        Self {
+            context,
+            citation_tracker: std::sync::Mutex::new(CitationTracker::new()),
+            query_cache: tokio::sync::Mutex::new(HashMap::new()),
+            suppressor: crate::services::server_tools::FunctionCallSuppressor::new(),
+        }
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[async_trait::async_trait]
+impl crate::services::server_tools::ServerExecutedTool for FileSearchExecutor {
+    fn name(&self) -> &'static str {
+        "file_search"
+    }
+
+    fn is_enabled_for(&self, _payload: &CreateResponsesPayload) -> bool {
+        self.context.is_enabled()
+    }
+
+    fn detect(
+        &self,
+        event: &[u8],
+        _ctx: &crate::services::server_tools::ToolContext,
+    ) -> Vec<crate::services::server_tools::DetectedToolCall> {
+        let vector_store_ids = self.context.get_vector_store_ids();
+        detect_file_search_in_chunk(event, &vector_store_ids)
+            .into_iter()
+            .map(|tc| crate::services::server_tools::DetectedToolCall {
+                tool_name: "file_search",
+                call_id: tc.id.clone(),
+                arguments: serde_json::to_value(&tc).unwrap_or(Value::Null),
+            })
+            .collect()
+    }
+
+    async fn execute(
+        &self,
+        call: crate::services::server_tools::DetectedToolCall,
+        ctx: &crate::services::server_tools::ToolContext,
+    ) -> Result<
+        crate::services::server_tools::ToolExecutionHandle,
+        crate::services::server_tools::ToolError,
+    > {
+        let tool_call: FileSearchToolCall =
+            serde_json::from_value(call.arguments).map_err(|e| {
+                crate::services::server_tools::ToolError::InvalidCall(format!(
+                    "could not deserialize FileSearchToolCall: {e}"
+                ))
+            })?;
+        let include_results = should_include_results(&ctx.original_payload);
+        let cache_key = tool_call.cache_key();
+        let context = self.context.clone();
+        let call_id = call.call_id.clone();
+
+        // Channel carries the progress/output events to the runner.
+        let (event_tx, event_rx) = mpsc::channel::<Bytes>(8);
+
+        // Future producing the final ToolCallResult.
+        let cache_handle = &self.query_cache;
+        let tracker_handle = &self.citation_tracker;
+        let (result_tx, result_rx) = tokio::sync::oneshot::channel::<
+            Result<
+                crate::services::server_tools::ToolCallResult,
+                crate::services::server_tools::ToolError,
+            >,
+        >();
+
+        // Clone the mutex references into the spawned task.
+        // SAFETY: Mutex<T> is Send+Sync when T is — but we need owned handles.
+        // Move via Arcs is the standard pattern; since the executor owns the
+        // mutexes, callers must keep the executor alive while execute() is
+        // running. The runner holds `Arc<dyn ServerExecutedTool>`, so this
+        // is naturally upheld.
+        // We work around by accessing the mutex via the spawned closure
+        // borrowing the executor — but that needs lifetime tricks. Instead
+        // we'll just clone what we need synchronously before spawning.
+        let cached_result = {
+            let cache = cache_handle.lock().await;
+            cache.get(&cache_key).cloned()
+        };
+
+        // Shared citation tracker: capture by Arc<Mutex<...>> for the result
+        // task. We need an Arc not a borrow.
+        // Since CitationTracker is per-instance, we'll do the update
+        // synchronously after the result is ready, before completing.
+
+        // To avoid lifetime complications, we collect the work synchronously
+        // here and only stream the events through a small async task.
+        let (in_progress_evt, searching_evt) = (
+            format_file_search_in_progress_event(&tool_call.id, 0),
+            format_file_search_searching_event(&tool_call.id, 0),
+        );
+
+        // Send in_progress + searching synchronously into the channel.
+        let _ = event_tx.send(in_progress_evt).await;
+        let _ = event_tx.send(searching_evt).await;
+
+        // Perform the search (or use cache).
+        let search_result = if let Some(cached) = cached_result {
+            info!(
+                stage = "search_completed",
+                tool_call_id = %tool_call.id,
+                query = %tool_call.query,
+                cache_hit = true,
+                "Returning cached file_search result"
+            );
+            FileSearchToolResult {
+                tool_call_id: tool_call.id.clone(),
+                ..cached
+            }
+        } else {
+            match context.execute_search(&tool_call).await {
+                Ok(r) => {
+                    let mut cache = cache_handle.lock().await;
+                    cache.insert(cache_key, r.clone());
+                    r
+                }
+                Err(e) => {
+                    let _ = result_tx.send(Err(
+                        crate::services::server_tools::ToolError::ExecutionFailed(e.to_string()),
+                    ));
+                    // Drop event_tx so the events stream completes.
+                    drop(event_tx);
+                    return Ok(crate::services::server_tools::ToolExecutionHandle {
+                        events: Box::pin(futures_util::stream::unfold(
+                            event_rx,
+                            |mut rx| async move { rx.recv().await.map(|item| (item, rx)) },
+                        )),
+                        result: Box::pin(async move {
+                            result_rx.await.map_err(|_| {
+                                crate::services::server_tools::ToolError::ExecutionFailed(
+                                    "result channel closed".into(),
+                                )
+                            })?
+                        }),
+                    });
+                }
+            }
+        };
+
+        // Update citation tracker.
+        if let Some(ref raw) = search_result.raw_response {
+            if let Ok(mut tracker) = tracker_handle.lock() {
+                tracker.add_from_response(raw);
+                debug!(
+                    stage = "citations_tracked",
+                    tool_call_id = %tool_call.id,
+                    source_count = raw.results.len(),
+                    "Added search results to citation tracker"
+                );
+            }
+
+            // Emit the file_search_call output_item.done event.
+            let call_output = build_file_search_call_output(
+                &tool_call.id,
+                &tool_call.query,
+                raw,
+                include_results,
+            );
+            if let Some(evt) = format_file_search_call_sse_event(&call_output) {
+                let _ = event_tx.send(evt).await;
+            }
+        }
+
+        // Emit the completed event.
+        let completed_evt = format_file_search_completed_event(&tool_call.id, 0);
+        let _ = event_tx.send(completed_evt).await;
+
+        // Build the continuation item (FunctionCallOutput) for the next turn.
+        let cont_item = ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+            type_: FunctionCallOutputType::FunctionCallOutput,
+            id: Some(tool_call.id.clone()),
+            call_id: tool_call.id.clone(),
+            output: search_result.content.clone(),
+            status: None,
+        });
+
+        let _ = result_tx.send(Ok(crate::services::server_tools::ToolCallResult {
+            call_id,
+            continuation_items: vec![cont_item],
+        }));
+
+        drop(event_tx);
+
+        Ok(crate::services::server_tools::ToolExecutionHandle {
+            events: Box::pin(futures_util::stream::unfold(
+                event_rx,
+                |mut rx| async move { rx.recv().await.map(|item| (item, rx)) },
+            )),
+            result: Box::pin(async move {
+                result_rx.await.map_err(|_| {
+                    crate::services::server_tools::ToolError::ExecutionFailed(
+                        "result channel closed".into(),
+                    )
+                })?
+            }),
+        })
+    }
+
+    fn apply_to_continuation(
+        &self,
+        payload: &mut CreateResponsesPayload,
+        results: &[crate::services::server_tools::ToolCallResult],
+        is_final_iteration: bool,
+    ) {
+        // Append all function-call outputs to the input.
+        let function_outputs: Vec<ResponsesInputItem> = results
+            .iter()
+            .flat_map(|r| r.continuation_items.clone())
+            .collect();
+
+        if function_outputs.is_empty() {
+            return;
+        }
+
+        match payload.input {
+            Some(ResponsesInput::Items(ref mut items)) => {
+                items.extend(function_outputs);
+            }
+            Some(ResponsesInput::Text(ref text)) => {
+                let text = text.clone();
+                let mut items = vec![ResponsesInputItem::EasyMessage(
+                    crate::api_types::responses::EasyInputMessage {
+                        type_: None,
+                        role: crate::api_types::responses::EasyInputMessageRole::User,
+                        content: crate::api_types::responses::EasyInputMessageContent::Text(text),
+                    },
+                )];
+                items.extend(function_outputs);
+                payload.input = Some(ResponsesInput::Items(items));
+            }
+            None => {
+                payload.input = Some(ResponsesInput::Items(function_outputs));
+            }
+        }
+
+        // On the final iteration, strip file_search tool definitions so the
+        // model is forced to produce a text response instead of looping.
+        if is_final_iteration && let Some(ref mut tools) = payload.tools {
+            let before = tools.len();
+            tools.retain(|t| !t.is_file_search());
+            // Preprocessing rewrites the spec `file_search` tool into a
+            // `Function{name:"file_search"}` form, which `is_file_search()`
+            // does not match — strip that form too, otherwise the model can
+            // keep calling file_search past `max_iterations`.
+            tools.retain(|t| {
+                if let ResponsesToolDefinition::Function(f) = t {
+                    f.name != FileSearchToolArguments::FUNCTION_NAME
+                } else {
+                    true
+                }
+            });
+            if tools.len() < before {
+                info!(
+                    stage = "tools_removed",
+                    removed = before - tools.len(),
+                    "Removed file_search tools on final iteration to force completion"
+                );
+            }
+            if tools.is_empty() {
+                payload.tools = None;
+            }
+        }
+    }
+
+    fn transform_event(&self, event: Bytes) -> Bytes {
+        // Hide the rewritten `file_search` function-call plumbing first;
+        // the executor emits the spec-shaped `file_search_call` items.
+        let event = self
+            .suppressor
+            .suppress(event, |name| name == "file_search");
+        if event.is_empty() {
+            return event;
+        }
+        let Ok(tracker) = self.citation_tracker.lock() else {
+            return event;
+        };
+        if tracker.is_empty() {
+            return event;
+        }
+        inject_citation_annotations(&event, &tracker)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::streaming::SseBuffer;
 
     #[test]
     fn test_parse_file_search_tool_call() {
@@ -2288,379 +1963,6 @@ mod tests {
         assert_eq!(results[1].query, "climate report");
     }
 
-    #[test]
-    fn test_build_continuation_payload_multiple_results() {
-        use crate::api_types::responses::{CreateResponsesPayload, ResponsesInput};
-
-        let original = CreateResponsesPayload {
-            input: Some(ResponsesInput::Text(
-                "What are Q1 and Q2 metrics?".to_string(),
-            )),
-            instructions: None,
-            metadata: None,
-            tools: None,
-            tool_choice: None,
-            parallel_tool_calls: None,
-            model: Some("gpt-4".to_string()),
-            models: None,
-            text: None,
-            reasoning: None,
-            max_output_tokens: None,
-            temperature: None,
-            top_p: None,
-            top_k: None,
-            prompt_cache_key: None,
-            previous_response_id: None,
-            prompt: None,
-            include: None,
-            background: None,
-            safety_identifier: None,
-            store: None,
-            service_tier: None,
-            truncation: None,
-            presence_penalty: None,
-            frequency_penalty: None,
-            stream: false,
-            provider: None,
-            plugins: None,
-            user: None,
-            sovereignty_requirements: None,
-        };
-
-        let tool_call_1 = FileSearchToolCall {
-            id: "call_1".to_string(),
-            query: "Q1 metrics".to_string(),
-            vector_store_ids: vec!["vs_1".to_string()],
-            max_num_results: None,
-            score_threshold: None,
-            filters: None,
-            ranking_options: None,
-        };
-
-        let tool_call_2 = FileSearchToolCall {
-            id: "call_2".to_string(),
-            query: "Q2 metrics".to_string(),
-            vector_store_ids: vec!["vs_1".to_string()],
-            max_num_results: None,
-            score_threshold: None,
-            filters: None,
-            ranking_options: None,
-        };
-
-        let result_1 = FileSearchToolResult {
-            tool_call_id: "call_1".to_string(),
-            content: "Q1 revenue: $1M".to_string(),
-            result_count: 1,
-            vector_stores_searched: 1,
-            raw_response: None,
-        };
-
-        let result_2 = FileSearchToolResult {
-            tool_call_id: "call_2".to_string(),
-            content: "Q2 revenue: $1.5M".to_string(),
-            result_count: 1,
-            vector_stores_searched: 1,
-            raw_response: None,
-        };
-
-        let tool_results = vec![(&tool_call_1, result_1), (&tool_call_2, result_2)];
-
-        let payload = build_continuation_payload(&original, &tool_results, false);
-
-        // Check that streaming is enabled
-        assert!(payload.stream);
-
-        // Check that the payload has items input (converted from text)
-        match payload.input {
-            Some(ResponsesInput::Items(items)) => {
-                // Should have: original text message + 2 function outputs
-                assert_eq!(items.len(), 3);
-
-                // First item should be the original text as an EasyMessage
-                match &items[0] {
-                    ResponsesInputItem::EasyMessage(msg) => {
-                        assert_eq!(
-                            msg.role,
-                            crate::api_types::responses::EasyInputMessageRole::User
-                        );
-                    }
-                    _ => panic!("Expected EasyMessage as first item"),
-                }
-
-                // Second and third items should be FunctionCallOutput
-                match &items[1] {
-                    ResponsesInputItem::FunctionCallOutput(output) => {
-                        assert_eq!(output.call_id, "call_1");
-                        assert_eq!(output.output, "Q1 revenue: $1M");
-                    }
-                    _ => panic!("Expected FunctionCallOutput as second item"),
-                }
-
-                match &items[2] {
-                    ResponsesInputItem::FunctionCallOutput(output) => {
-                        assert_eq!(output.call_id, "call_2");
-                        assert_eq!(output.output, "Q2 revenue: $1.5M");
-                    }
-                    _ => panic!("Expected FunctionCallOutput as third item"),
-                }
-            }
-            _ => panic!("Expected Items input"),
-        }
-    }
-
-    #[test]
-    fn test_build_continuation_payload_final_iteration_removes_file_search() {
-        use crate::api_types::responses::{
-            CreateResponsesPayload, FileSearchTool, FileSearchToolType, ResponsesInput,
-            ResponsesToolDefinition,
-        };
-
-        // Create a payload with file_search and function tools
-        let function_tool = serde_json::json!({
-            "type": "function",
-            "name": "get_weather",
-            "description": "Get current weather",
-            "parameters": {"type": "object", "properties": {}}
-        });
-
-        let original = CreateResponsesPayload {
-            input: Some(ResponsesInput::Text("Find Q1 results".to_string())),
-            instructions: None,
-            metadata: None,
-            tools: Some(vec![
-                ResponsesToolDefinition::FileSearch(FileSearchTool {
-                    type_: FileSearchToolType::FileSearch,
-                    vector_store_ids: vec!["vs_1".to_string()],
-                    max_num_results: None,
-                    ranking_options: None,
-                    filters: None,
-                    cache_control: None,
-                }),
-                ResponsesToolDefinition::Function(function_tool.clone()),
-            ]),
-            tool_choice: None,
-            parallel_tool_calls: None,
-            model: Some("gpt-4".to_string()),
-            models: None,
-            text: None,
-            reasoning: None,
-            max_output_tokens: None,
-            temperature: None,
-            top_p: None,
-            top_k: None,
-            prompt_cache_key: None,
-            previous_response_id: None,
-            prompt: None,
-            include: None,
-            background: None,
-            safety_identifier: None,
-            store: None,
-            service_tier: None,
-            truncation: None,
-            presence_penalty: None,
-            frequency_penalty: None,
-            stream: false,
-            provider: None,
-            plugins: None,
-            user: None,
-            sovereignty_requirements: None,
-        };
-
-        let tool_call = FileSearchToolCall {
-            id: "call_1".to_string(),
-            query: "Q1 metrics".to_string(),
-            vector_store_ids: vec!["vs_1".to_string()],
-            max_num_results: None,
-            score_threshold: None,
-            filters: None,
-            ranking_options: None,
-        };
-
-        let result = FileSearchToolResult {
-            tool_call_id: "call_1".to_string(),
-            content: "Q1 revenue: $1M".to_string(),
-            result_count: 1,
-            vector_stores_searched: 1,
-            raw_response: None,
-        };
-
-        let tool_results = vec![(&tool_call, result)];
-
-        // Test with is_final_iteration = true
-        let payload = build_continuation_payload(&original, &tool_results, true);
-
-        // file_search tool should be removed
-        let tools = payload.tools.expect("tools should exist");
-        assert_eq!(tools.len(), 1, "Should have 1 tool (function only)");
-        assert!(
-            !tools[0].is_file_search(),
-            "Remaining tool should not be file_search"
-        );
-
-        // Function tool should be preserved
-        match &tools[0] {
-            ResponsesToolDefinition::Function(v) => {
-                assert_eq!(v["name"], "get_weather");
-            }
-            _ => panic!("Expected Function tool"),
-        }
-    }
-
-    #[test]
-    fn test_build_continuation_payload_final_iteration_removes_all_tools_if_only_file_search() {
-        use crate::api_types::responses::{
-            CreateResponsesPayload, FileSearchTool, FileSearchToolType, ResponsesInput,
-            ResponsesToolDefinition,
-        };
-
-        // Create a payload with only file_search tool
-        let original = CreateResponsesPayload {
-            input: Some(ResponsesInput::Text("Find Q1 results".to_string())),
-            instructions: None,
-            metadata: None,
-            tools: Some(vec![ResponsesToolDefinition::FileSearch(FileSearchTool {
-                type_: FileSearchToolType::FileSearch,
-                vector_store_ids: vec!["vs_1".to_string()],
-                max_num_results: None,
-                ranking_options: None,
-                filters: None,
-                cache_control: None,
-            })]),
-            tool_choice: None,
-            parallel_tool_calls: None,
-            model: Some("gpt-4".to_string()),
-            models: None,
-            text: None,
-            reasoning: None,
-            max_output_tokens: None,
-            temperature: None,
-            top_p: None,
-            top_k: None,
-            prompt_cache_key: None,
-            previous_response_id: None,
-            prompt: None,
-            include: None,
-            background: None,
-            safety_identifier: None,
-            store: None,
-            service_tier: None,
-            truncation: None,
-            presence_penalty: None,
-            frequency_penalty: None,
-            stream: false,
-            provider: None,
-            plugins: None,
-            user: None,
-            sovereignty_requirements: None,
-        };
-
-        let tool_call = FileSearchToolCall {
-            id: "call_1".to_string(),
-            query: "Q1 metrics".to_string(),
-            vector_store_ids: vec!["vs_1".to_string()],
-            max_num_results: None,
-            score_threshold: None,
-            filters: None,
-            ranking_options: None,
-        };
-
-        let result = FileSearchToolResult {
-            tool_call_id: "call_1".to_string(),
-            content: "Q1 revenue: $1M".to_string(),
-            result_count: 1,
-            vector_stores_searched: 1,
-            raw_response: None,
-        };
-
-        let tool_results = vec![(&tool_call, result)];
-
-        // Test with is_final_iteration = true
-        let payload = build_continuation_payload(&original, &tool_results, true);
-
-        // tools should be None (not empty array) since only file_search was present
-        assert!(
-            payload.tools.is_none(),
-            "tools should be None when only file_search was present"
-        );
-    }
-
-    #[test]
-    fn test_build_continuation_payload_not_final_iteration_preserves_tools() {
-        use crate::api_types::responses::{
-            CreateResponsesPayload, FileSearchTool, FileSearchToolType, ResponsesInput,
-            ResponsesToolDefinition,
-        };
-
-        // Create a payload with file_search tool
-        let original = CreateResponsesPayload {
-            input: Some(ResponsesInput::Text("Find Q1 results".to_string())),
-            instructions: None,
-            metadata: None,
-            tools: Some(vec![ResponsesToolDefinition::FileSearch(FileSearchTool {
-                type_: FileSearchToolType::FileSearch,
-                vector_store_ids: vec!["vs_1".to_string()],
-                max_num_results: None,
-                ranking_options: None,
-                filters: None,
-                cache_control: None,
-            })]),
-            tool_choice: None,
-            parallel_tool_calls: None,
-            model: Some("gpt-4".to_string()),
-            models: None,
-            text: None,
-            reasoning: None,
-            max_output_tokens: None,
-            temperature: None,
-            top_p: None,
-            top_k: None,
-            prompt_cache_key: None,
-            previous_response_id: None,
-            prompt: None,
-            include: None,
-            background: None,
-            safety_identifier: None,
-            store: None,
-            service_tier: None,
-            truncation: None,
-            presence_penalty: None,
-            frequency_penalty: None,
-            stream: false,
-            provider: None,
-            plugins: None,
-            user: None,
-            sovereignty_requirements: None,
-        };
-
-        let tool_call = FileSearchToolCall {
-            id: "call_1".to_string(),
-            query: "Q1 metrics".to_string(),
-            vector_store_ids: vec!["vs_1".to_string()],
-            max_num_results: None,
-            score_threshold: None,
-            filters: None,
-            ranking_options: None,
-        };
-
-        let result = FileSearchToolResult {
-            tool_call_id: "call_1".to_string(),
-            content: "Q1 revenue: $1M".to_string(),
-            result_count: 1,
-            vector_stores_searched: 1,
-            raw_response: None,
-        };
-
-        let tool_results = vec![(&tool_call, result)];
-
-        // Test with is_final_iteration = false
-        let payload = build_continuation_payload(&original, &tool_results, false);
-
-        // file_search tool should be preserved
-        let tools = payload.tools.expect("tools should exist");
-        assert_eq!(tools.len(), 1, "Should have 1 tool");
-        assert!(tools[0].is_file_search(), "Tool should be file_search");
-    }
-
     #[test]
     fn test_check_response_for_file_search() {
         let body = serde_json::json!({
@@ -3365,6 +2667,8 @@ mod tests {
             plugins: None,
             user: None,
             sovereignty_requirements: None,
+            skills: None,
+            context_management: None,
         };
 
         // Should not panic with no tools
@@ -3416,6 +2720,8 @@ mod tests {
             plugins: None,
             user: None,
             sovereignty_requirements: None,
+            skills: None,
+            context_management: None,
         };
 
         preprocess_file_search_tools(&mut payload);
@@ -3425,10 +2731,9 @@ mod tests {
         assert_eq!(tools.len(), 1);
 
         match &tools[0] {
-            ResponsesToolDefinition::Function(json) => {
-                assert_eq!(json["type"], "function");
-                assert_eq!(json["name"], "file_search");
-                assert!(json.get("parameters").is_some());
+            ResponsesToolDefinition::Function(f) => {
+                assert_eq!(f.name, "file_search");
+                assert!(f.parameters.is_some());
             }
             _ => panic!("Expected Function tool, got {:?}", tools[0]),
         }
@@ -3437,10 +2742,11 @@ mod tests {
     #[test]
     fn test_preprocess_file_search_tools_preserves_other_tools() {
         use crate::api_types::responses::{
-            CreateResponsesPayload, FileSearchTool, FileSearchToolType, ResponsesToolDefinition,
+            CreateResponsesPayload, FileSearchTool, FileSearchToolType, FunctionTool,
+            ResponsesToolDefinition,
         };
 
-        let function_tool = serde_json::json!({
+        let function_tool = FunctionTool::from_json(serde_json::json!({
             "type": "function",
             "name": "get_weather",
             "description": "Get weather for a location",
@@ -3450,7 +2756,8 @@ mod tests {
                     "location": {"type": "string"}
                 }
             }
-        });
+        }))
+        .unwrap();
 
         let mut payload = CreateResponsesPayload {
             input: None,
@@ -3493,6 +2800,8 @@ mod tests {
             plugins: None,
             user: None,
             sovereignty_requirements: None,
+            skills: None,
+            context_management: None,
         };
 
         preprocess_file_search_tools(&mut payload);
@@ -3502,16 +2811,16 @@ mod tests {
 
         // First tool should be unchanged
         match &tools[0] {
-            ResponsesToolDefinition::Function(json) => {
-                assert_eq!(json["name"], "get_weather");
+            ResponsesToolDefinition::Function(f) => {
+                assert_eq!(f.name, "get_weather");
             }
             _ => panic!("Expected Function tool"),
         }
 
         // Second tool should be converted from file_search
         match &tools[1] {
-            ResponsesToolDefinition::Function(json) => {
-                assert_eq!(json["name"], "file_search");
+            ResponsesToolDefinition::Function(f) => {
+                assert_eq!(f.name, "file_search");
             }
             _ => panic!("Expected converted file_search tool"),
         }
diff --git a/src/services/files.rs b/src/services/files.rs
index bca83af..9cdc083 100644
--- a/src/services/files.rs
+++ b/src/services/files.rs
@@ -123,6 +123,25 @@ impl FilesService {
         self.db.files().get_file(id).await
     }
 
+    /// Get a file by ID, scoped to an owner. Returns `None` (the same as
+    /// a missing file — no info leak) when the file exists but belongs to
+    /// a different `(owner_type, owner_id)`. Used by the container
+    /// staging paths so a caller can only reference files in its own
+    /// tenant scope, mirroring how `list_files` is scoped.
+    pub async fn get_for_owner(
+        &self,
+        id: Uuid,
+        owner_type: crate::models::VectorStoreOwnerType,
+        owner_id: Uuid,
+    ) -> DbResult<Option<File>> {
+        Ok(self
+            .db
+            .files()
+            .get_file(id)
+            .await?
+            .filter(|f| f.owner_type == owner_type && f.owner_id == owner_id))
+    }
+
     /// Get the content of a file.
     ///
     /// Retrieves the file content from the appropriate storage backend:
diff --git a/src/services/input_file_staging.rs b/src/services/input_file_staging.rs
new file mode 100644
index 0000000..f5c2fd7
--- /dev/null
+++ b/src/services/input_file_staging.rs
@@ -0,0 +1,804 @@
+//! Resolve `input_file` content parts on a Responses-API request into
+//! ready-to-mount byte blobs.
+//!
+//! Walks `payload.input` for [`ResponseInputContentItem::InputFile`]
+//! parts, resolves each through one of three sources (Files API
+//! lookup, base64 data URL, or HTTP URL with SSRF protection), and
+//! returns the bytes alongside a sanitized filename. The caller
+//! (`apply_streaming_pipeline`) feeds the result into
+//! [`ContainerSession::ingest_user_files`] so the shell tool sees the
+//! files at `/mnt/data/<filename>` on its first command.
+//!
+//! Errors are surfaced as 400-eligible so callers can turn them into
+//! a clear client response.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::collections::HashSet;
+
+use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};
+use sha2::{Digest, Sha256};
+use thiserror::Error;
+
+use crate::{
+    AppState,
+    api_types::responses::{
+        CreateResponsesPayload, EasyInputMessageContent, ResponseInputContentItem, ResponsesInput,
+        ResponsesInputItem,
+    },
+    config::ContainersConfig,
+    db::repos::ResponseOwner,
+};
+
+/// One resolved input file, ready to write into `/mnt/data`.
+#[derive(Debug, Clone)]
+pub struct StagedFile {
+    /// Sanitized basename. Empty path components, traversal segments,
+    /// and absolute prefixes are stripped before this struct is built.
+    /// On filename collision a `<sha8>-` prefix is added to keep the
+    /// originals distinguishable, matching OpenAI's behavior.
+    pub filename: String,
+    /// File bytes.
+    pub bytes: bytes::Bytes,
+    /// MIME type when known. Comes from the Files API metadata for
+    /// `file_id`, the data URL prefix for `file_data`, or the HTTP
+    /// `Content-Type` header for `file_url`.
+    pub content_type: Option<String>,
+    /// Original Files-API id when the source was `file_id`. Used to
+    /// cross-link the container file row back to the source upload
+    /// and recorded for traceability.
+    pub source_file_id: Option<String>,
+}
+
+/// Errors emitted by [`stage_input_files`].
+///
+/// All variants are 400-eligible from the client's perspective — the
+/// caller is expected to translate to a `bad_request` API error with
+/// a code drawn from `error_code()`.
+#[derive(Debug, Error)]
+pub enum StageError {
+    #[error("input_file is missing any of file_id / file_data / file_url")]
+    NoSource,
+    #[error("input_file specifies multiple sources; pick one of file_id / file_data / file_url")]
+    AmbiguousSource,
+    #[error("input_file file_id '{0}' is not a valid file identifier")]
+    InvalidFileId(String),
+    #[error("input_file file_id '{0}' was not found")]
+    FileNotFound(String),
+    #[error("input_file file_data is not a valid data URL: {0}")]
+    BadDataUrl(String),
+    #[error("input_file file_data base64 decode failed: {0}")]
+    BadBase64(String),
+    #[error("input_file file_url is blocked or invalid: {0}")]
+    BlockedUrl(String),
+    #[error("input_file file_url fetch failed: {0}")]
+    FetchFailed(String),
+    #[error("input_file file_url HTTP {0}")]
+    HttpStatus(u16),
+    #[error(
+        "input_file '{filename}' exceeds the {limit}-byte per-request input budget at {bytes} bytes"
+    )]
+    FileTooLarge {
+        filename: String,
+        bytes: u64,
+        limit: u64,
+    },
+    #[error("request stages {count} input_file parts, exceeding the configured maximum of {limit}")]
+    TooManyFiles { count: usize, limit: usize },
+    #[error("input_file storage backend error: {0}")]
+    Storage(String),
+}
+
+impl StageError {
+    /// Stable machine code for the API error envelope.
+    pub fn error_code(&self) -> &'static str {
+        match self {
+            Self::NoSource | Self::AmbiguousSource => "invalid_input_file",
+            Self::InvalidFileId(_) | Self::FileNotFound(_) => "invalid_input_file_id",
+            Self::BadDataUrl(_) | Self::BadBase64(_) => "invalid_input_file_data",
+            Self::BlockedUrl(_) | Self::FetchFailed(_) | Self::HttpStatus(_) => {
+                "invalid_input_file_url"
+            }
+            Self::FileTooLarge { .. } => "input_file_too_large",
+            Self::TooManyFiles { .. } => "too_many_input_files",
+            Self::Storage(_) => "input_file_storage_error",
+        }
+    }
+}
+
+/// Walk `payload.input`, resolve every `input_file` part, and return
+/// the staged files in encounter order.
+///
+/// Skips staging entirely when `config.enabled = false`. Skips
+/// resolution when no `input_file` parts are present (returns `Ok([])`
+/// without touching the network or DB).
+///
+/// `owner` is the request's response owner; `file_id` references are
+/// resolved only when the referenced file belongs to that same owner
+/// (cross-tenant access prevention). `None` (no resolvable owner, or a
+/// service-account owner that has no file scope) fails closed for
+/// `file_id` parts.
+pub async fn stage_input_files(
+    state: &AppState,
+    payload: &CreateResponsesPayload,
+    config: &ContainersConfig,
+    owner: Option<ResponseOwner>,
+) -> Result<Vec<StagedFile>, StageError> {
+    if !config.enabled {
+        return Ok(Vec::new());
+    }
+
+    let parts = collect_input_file_parts(payload);
+    if parts.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    if parts.len() > config.max_input_files_per_request {
+        return Err(StageError::TooManyFiles {
+            count: parts.len(),
+            limit: config.max_input_files_per_request,
+        });
+    }
+
+    let mut total_bytes: u64 = 0;
+    let mut seen: HashSet<String> = HashSet::new();
+    let mut out: Vec<StagedFile> = Vec::with_capacity(parts.len());
+
+    for part in parts {
+        let resolved = resolve_one(state, &part, owner, config.max_input_bytes_per_request).await?;
+        let bytes_len = resolved.bytes.len() as u64;
+        if total_bytes.saturating_add(bytes_len) > config.max_input_bytes_per_request {
+            return Err(StageError::FileTooLarge {
+                filename: resolved.filename,
+                bytes: total_bytes + bytes_len,
+                limit: config.max_input_bytes_per_request,
+            });
+        }
+        total_bytes += bytes_len;
+
+        let filename = dedupe_filename(resolved.filename, &resolved.bytes, &mut seen);
+
+        out.push(StagedFile {
+            filename,
+            bytes: resolved.bytes,
+            content_type: resolved.content_type,
+            source_file_id: resolved.source_file_id,
+        });
+    }
+
+    Ok(out)
+}
+
+/// Internal shape returned by `resolve_one` — same as `StagedFile`
+/// except the filename hasn't been deduped yet.
+struct ResolvedFile {
+    filename: String,
+    bytes: bytes::Bytes,
+    content_type: Option<String>,
+    source_file_id: Option<String>,
+}
+
+/// Snapshot of one `input_file` part, broken out of the AST so the
+/// resolution code doesn't need to know about [`ResponseInputContentItem`]
+/// internals.
+#[derive(Debug, Clone)]
+struct InputFilePart {
+    file_id: Option<String>,
+    file_data: Option<String>,
+    file_url: Option<String>,
+    filename: Option<String>,
+}
+
+fn collect_input_file_parts(payload: &CreateResponsesPayload) -> Vec<InputFilePart> {
+    let mut out = Vec::new();
+    // Files pre-uploaded via `shell.environment.container_auto.file_ids`
+    // (spec: ContainerAutoParam.file_ids) are staged the same way as
+    // `input_file` parts — they end up in /mnt/data before the model's
+    // first shell command. Treated as `file_id`-only parts with no
+    // inline data or remote URL.
+    if let Some(tools) = payload.tools.as_ref() {
+        for tool in tools {
+            if let Some(shell) = tool.as_shell()
+                && let Some(env) = shell.environment.as_ref()
+                && let crate::api_types::responses::ShellEnvironment::ContainerAuto(auto) = env
+                && let Some(ids) = auto.file_ids.as_ref()
+            {
+                for id in ids {
+                    out.push(InputFilePart {
+                        file_id: Some(id.clone()),
+                        file_data: None,
+                        file_url: None,
+                        filename: None,
+                    });
+                }
+            }
+        }
+    }
+    let Some(input) = payload.input.as_ref() else {
+        return out;
+    };
+    match input {
+        ResponsesInput::Text(_) => {}
+        ResponsesInput::Items(items) => {
+            for item in items {
+                collect_from_item(item, &mut out);
+            }
+        }
+    }
+    out
+}
+
+fn collect_from_item(item: &ResponsesInputItem, out: &mut Vec<InputFilePart>) {
+    match item {
+        ResponsesInputItem::EasyMessage(msg) => match &msg.content {
+            EasyInputMessageContent::Text(_) => {}
+            EasyInputMessageContent::Parts(parts) => {
+                for part in parts {
+                    push_if_input_file(part, out);
+                }
+            }
+        },
+        ResponsesInputItem::MessageItem(msg) => {
+            for part in &msg.content {
+                push_if_input_file(part, out);
+            }
+        }
+        // Other variants (FunctionCall, FunctionCallOutput, OutputMessage,
+        // tool-specific outputs, Reasoning, ImageGeneration) carry no
+        // user-supplied file parts.
+        _ => {}
+    }
+}
+
+fn push_if_input_file(part: &ResponseInputContentItem, out: &mut Vec<InputFilePart>) {
+    if let ResponseInputContentItem::InputFile {
+        file_id,
+        file_data,
+        filename,
+        file_url,
+        ..
+    } = part
+    {
+        out.push(InputFilePart {
+            file_id: file_id.clone(),
+            file_data: file_data.clone(),
+            file_url: file_url.clone(),
+            filename: filename.clone(),
+        });
+    }
+}
+
+async fn resolve_one(
+    state: &AppState,
+    part: &InputFilePart,
+    owner: Option<ResponseOwner>,
+    max_bytes: u64,
+) -> Result<ResolvedFile, StageError> {
+    validate_source_count(part)?;
+
+    if let Some(ref id) = part.file_id {
+        return resolve_file_id(state, id, part.filename.as_deref(), owner).await;
+    }
+    if let Some(ref data) = part.file_data {
+        return resolve_file_data(data, part.filename.as_deref());
+    }
+    if let Some(ref url) = part.file_url {
+        return resolve_file_url(state, url, part.filename.as_deref(), max_bytes).await;
+    }
+    unreachable!("validate_source_count guarantees exactly one source is set")
+}
+
+/// Ensure exactly one of `file_id` / `file_data` / `file_url` is set.
+fn validate_source_count(part: &InputFilePart) -> Result<(), StageError> {
+    let count = [
+        part.file_id.is_some(),
+        part.file_data.is_some(),
+        part.file_url.is_some(),
+    ]
+    .into_iter()
+    .filter(|b| *b)
+    .count();
+    match count {
+        0 => Err(StageError::NoSource),
+        1 => Ok(()),
+        _ => Err(StageError::AmbiguousSource),
+    }
+}
+
+/// Apply collision dedupe: if `filename` is already in `seen`, prefix
+/// it with the short content hash so the staged set keeps both files.
+/// If that prefixed form is also taken (e.g. three uploads with the
+/// same content + filename), append an incrementing `-N-` counter
+/// until a free name is found.
+///
+/// Mutates `seen` to remember the returned name.
+fn dedupe_filename(filename: String, bytes: &[u8], seen: &mut HashSet<String>) -> String {
+    if seen.insert(filename.clone()) {
+        return filename;
+    }
+    let prefix = short_content_hash(bytes);
+    let prefixed = format!("{prefix}-{filename}");
+    if seen.insert(prefixed.clone()) {
+        return prefixed;
+    }
+    // Same content + same filename arriving a third time. Walk a
+    // counter to keep collisions unique — bounded by attempt count
+    // so we never spin forever on a pathologically full `seen`.
+    for n in 2u32..u32::MAX {
+        let candidate = format!("{prefix}-{n}-{filename}");
+        if seen.insert(candidate.clone()) {
+            return candidate;
+        }
+    }
+    // Fall-through is unreachable in practice (we'd need to have
+    // ingested ~4 billion files with identical content in one
+    // request, which `max_input_files_per_request` rules out). Emit
+    // a UUID-suffixed fallback rather than risk a duplicate-path
+    // overwrite at /mnt/data write time.
+    let fallback = format!("{prefix}-{}-{filename}", uuid::Uuid::new_v4().simple());
+    seen.insert(fallback.clone());
+    fallback
+}
+
+async fn resolve_file_id(
+    state: &AppState,
+    raw_id: &str,
+    override_filename: Option<&str>,
+    owner: Option<ResponseOwner>,
+) -> Result<ResolvedFile, StageError> {
+    use std::str::FromStr;
+
+    let file_id = crate::models::FileId::from_str(raw_id)
+        .map_err(|_| StageError::InvalidFileId(raw_id.to_string()))?;
+    let uuid = file_id.into_inner();
+
+    let services = state
+        .services
+        .as_ref()
+        .ok_or_else(|| StageError::Storage("files service unavailable".into()))?;
+
+    // Tenant scope: the referenced file must belong to the request's
+    // owner. A missing owner scope (no resolvable owner, or a
+    // service-account owner) fails closed — `FileNotFound`, the same
+    // shape as a genuinely absent file, so we never leak whether a file
+    // exists in another tenant.
+    let (owner_type, owner_id) = owner
+        .and_then(|o| o.as_file_owner())
+        .ok_or_else(|| StageError::FileNotFound(raw_id.to_string()))?;
+    let metadata = services
+        .files
+        .get_for_owner(uuid, owner_type, owner_id)
+        .await
+        .map_err(|e| StageError::Storage(e.to_string()))?
+        .ok_or_else(|| StageError::FileNotFound(raw_id.to_string()))?;
+
+    let content = services
+        .files
+        .get_content(uuid)
+        .await
+        .map_err(|e| StageError::Storage(e.to_string()))?;
+
+    let filename = sanitize_filename(
+        override_filename.unwrap_or(&metadata.filename),
+        Some(&metadata.filename),
+    );
+
+    Ok(ResolvedFile {
+        filename,
+        bytes: bytes::Bytes::from(content),
+        content_type: metadata.content_type,
+        source_file_id: Some(raw_id.to_string()),
+    })
+}
+
+fn resolve_file_data(
+    raw: &str,
+    override_filename: Option<&str>,
+) -> Result<ResolvedFile, StageError> {
+    let parsed = crate::providers::image::parse_data_url(raw)
+        .map_err(|e| StageError::BadDataUrl(e.to_string()))?;
+    let bytes = BASE64
+        .decode(parsed.data.as_bytes())
+        .map_err(|e| StageError::BadBase64(e.to_string()))?;
+
+    // Best-effort filename: caller may have supplied one, else
+    // synthesize from the media type so the model sees something
+    // sensible at `/mnt/data/<name>`.
+    let synthesized = format!("upload{}", media_type_to_ext(&parsed.media_type));
+    let filename = sanitize_filename(
+        override_filename.unwrap_or(&synthesized),
+        Some(&synthesized),
+    );
+
+    Ok(ResolvedFile {
+        filename,
+        bytes: bytes::Bytes::from(bytes),
+        content_type: Some(parsed.media_type),
+        source_file_id: None,
+    })
+}
+
+async fn resolve_file_url(
+    state: &AppState,
+    url: &str,
+    override_filename: Option<&str>,
+    max_bytes: u64,
+) -> Result<ResolvedFile, StageError> {
+    // SSRF guard — same options the image fetcher uses. Loopback is
+    // forbidden because content URLs in user requests are untrusted.
+    let validated = crate::validation::validate_base_url_opts(
+        url,
+        crate::validation::UrlValidationOptions::default(),
+    )
+    .map_err(|e| StageError::BlockedUrl(e.to_string()))?;
+    let pinned = crate::validation::pinned_reqwest_client(&validated)
+        .map_err(|e| StageError::FetchFailed(format!("pin dns: {e}")))?;
+    let _ = &state.http_client; // pool unused — pin is per-host
+    let resp = pinned
+        .get(url)
+        .timeout(std::time::Duration::from_secs(30))
+        .send()
+        .await
+        .map_err(|e| StageError::FetchFailed(e.to_string()))?;
+    let status = resp.status();
+    if !status.is_success() {
+        return Err(StageError::HttpStatus(status.as_u16()));
+    }
+    let content_type = resp
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|v| v.to_str().ok())
+        .map(|s| s.split(';').next().unwrap_or(s).trim().to_string());
+
+    let url_filename = url_basename(url);
+    let filename = sanitize_filename(
+        override_filename.unwrap_or(&url_filename),
+        Some(&url_filename),
+    );
+
+    // Reject up front if the advertised size already blows the budget,
+    // then stream and abort the moment we cross it — a malicious upstream
+    // must not be able to burn server memory proportional to whatever the
+    // 30s timeout allows. Mirrors `providers::image::fetch_image_from_url`.
+    if let Some(content_length) = resp.content_length()
+        && content_length > max_bytes
+    {
+        return Err(StageError::FileTooLarge {
+            filename,
+            bytes: content_length,
+            limit: max_bytes,
+        });
+    }
+
+    use futures::StreamExt;
+    let mut buf = bytes::BytesMut::new();
+    let mut stream = resp.bytes_stream();
+    while let Some(chunk) = stream.next().await {
+        let chunk = chunk.map_err(|e| StageError::FetchFailed(e.to_string()))?;
+        if buf.len() as u64 + chunk.len() as u64 > max_bytes {
+            return Err(StageError::FileTooLarge {
+                filename,
+                bytes: buf.len() as u64 + chunk.len() as u64,
+                limit: max_bytes,
+            });
+        }
+        buf.extend_from_slice(&chunk);
+    }
+
+    Ok(ResolvedFile {
+        filename,
+        bytes: buf.freeze(),
+        content_type,
+        source_file_id: None,
+    })
+}
+
+/// First 8 hex chars of sha256(content) — used as the dedupe prefix.
+fn short_content_hash(bytes: &[u8]) -> String {
+    let mut h = Sha256::new();
+    h.update(bytes);
+    let out = h.finalize();
+    hex::encode(&out[..4])
+}
+
+fn url_basename(url: &str) -> String {
+    let path_only = url.split(['?', '#']).next().unwrap_or(url);
+    // Strip the scheme so we don't mistake the host for a filename
+    // when the path is empty (e.g. `https://example.com/`).
+    let after_scheme = match path_only.find("://") {
+        Some(idx) => &path_only[idx + 3..],
+        None => path_only,
+    };
+    // Drop the host: everything up to and including the first '/'.
+    let path = match after_scheme.find('/') {
+        Some(idx) => &after_scheme[idx + 1..],
+        None => "",
+    };
+    let last = path.rsplit('/').find(|s| !s.is_empty()).unwrap_or("");
+    if last.is_empty() {
+        "upload".to_string()
+    } else {
+        last.to_string()
+    }
+}
+
+/// Strip path components, traversal segments, leading dots, and any
+/// characters that would let one file clobber another. Always returns
+/// a non-empty string — falls back to `fallback` (or "upload") if the
+/// primary input sanitizes to nothing.
+fn sanitize_filename(raw: &str, fallback: Option<&str>) -> String {
+    let candidate = clean_filename(raw);
+    if !candidate.is_empty() {
+        return truncate(candidate);
+    }
+    if let Some(fb) = fallback {
+        let cleaned = clean_filename(fb);
+        if !cleaned.is_empty() {
+            return truncate(cleaned);
+        }
+    }
+    "upload".to_string()
+}
+
+fn clean_filename(raw: &str) -> String {
+    let base = std::path::Path::new(raw)
+        .file_name()
+        .and_then(|s| s.to_str())
+        .unwrap_or("");
+    // Drop any leading dots so we don't accidentally create dotfiles
+    // (which could shadow real config in the image like `.bashrc`).
+    let trimmed = base.trim_start_matches('.');
+    // Replace any character that isn't a safe filename char with `_`.
+    trimmed
+        .chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() || matches!(c, '.' | '-' | '_' | ' ' | '+' | '(' | ')') {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect()
+}
+
+fn truncate(s: String) -> String {
+    const MAX: usize = 200;
+    if s.len() <= MAX {
+        return s;
+    }
+    // Preserve the extension if possible.
+    let path = std::path::Path::new(&s);
+    let ext = path
+        .extension()
+        .and_then(|e| e.to_str())
+        .map(|e| format!(".{e}"))
+        .unwrap_or_default();
+    let stem = path.file_stem().and_then(|e| e.to_str()).unwrap_or(&s);
+    let stem_keep = MAX.saturating_sub(ext.len());
+    let mut out: String = stem.chars().take(stem_keep).collect();
+    out.push_str(&ext);
+    out
+}
+
+/// Pick a sensible extension for a media type when the caller didn't
+/// supply a filename. Keeps the synthesized name small and grep-able.
+fn media_type_to_ext(media_type: &str) -> &'static str {
+    match media_type.to_ascii_lowercase().as_str() {
+        "text/plain" => ".txt",
+        "text/csv" => ".csv",
+        "text/tab-separated-values" => ".tsv",
+        "application/json" => ".json",
+        "application/x-ndjson" => ".jsonl",
+        "text/html" => ".html",
+        "application/xml" | "text/xml" => ".xml",
+        "application/yaml" | "text/yaml" => ".yaml",
+        "application/pdf" => ".pdf",
+        "image/png" => ".png",
+        "image/jpeg" => ".jpg",
+        "image/gif" => ".gif",
+        "image/webp" => ".webp",
+        "image/svg+xml" => ".svg",
+        "application/zip" => ".zip",
+        "application/gzip" => ".gz",
+        _ => "",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sanitize_filename_strips_path_components() {
+        assert_eq!(sanitize_filename("../../etc/passwd", None), "passwd");
+        assert_eq!(sanitize_filename("/abs/path/foo.csv", None), "foo.csv");
+        assert_eq!(sanitize_filename("foo.csv", None), "foo.csv");
+        assert_eq!(
+            sanitize_filename("..", Some("fallback.txt")),
+            "fallback.txt"
+        );
+        assert_eq!(sanitize_filename("", None), "upload");
+        assert_eq!(sanitize_filename(".bashrc", None), "bashrc");
+    }
+
+    #[test]
+    fn sanitize_filename_neutralizes_dangerous_chars() {
+        assert_eq!(sanitize_filename("foo bar.csv", None), "foo bar.csv");
+        // Path-style traversal collapses to the OS-level basename
+        // ".csv", which our leading-dot strip turns into "csv".
+        assert_eq!(sanitize_filename("foo;rm -rf /.csv", None), "csv");
+        // No path separators here, so the dangerous chars get mapped
+        // to '_' by the char filter.
+        assert_eq!(sanitize_filename("foo;rm.csv", None), "foo_rm.csv");
+        // The `ï` is one codepoint, so it gets replaced with one `_`.
+        assert_eq!(sanitize_filename("naïve.txt", None), "na_ve.txt");
+    }
+
+    #[test]
+    fn sanitize_filename_truncates_long_names_preserving_extension() {
+        let long = format!("{}.csv", "a".repeat(300));
+        let result = sanitize_filename(&long, None);
+        assert!(result.len() <= 200);
+        assert!(result.ends_with(".csv"));
+    }
+
+    #[test]
+    fn url_basename_strips_query_and_fragment() {
+        assert_eq!(url_basename("https://example.com/foo/bar.csv"), "bar.csv");
+        assert_eq!(
+            url_basename("https://example.com/foo/bar.csv?x=1"),
+            "bar.csv"
+        );
+        assert_eq!(
+            url_basename("https://example.com/foo/bar.csv#sec"),
+            "bar.csv"
+        );
+        assert_eq!(url_basename("https://example.com/"), "upload");
+    }
+
+    #[test]
+    fn media_type_to_ext_covers_common_types() {
+        assert_eq!(media_type_to_ext("text/csv"), ".csv");
+        assert_eq!(media_type_to_ext("Application/JSON"), ".json");
+        assert_eq!(media_type_to_ext("image/png"), ".png");
+        assert_eq!(media_type_to_ext("application/x-unknown"), "");
+    }
+
+    #[test]
+    fn resolve_file_data_handles_inline_base64() {
+        // "hello" = aGVsbG8=
+        let raw = "data:text/plain;base64,aGVsbG8=";
+        let r = resolve_file_data(raw, Some("greeting.txt")).unwrap();
+        assert_eq!(r.filename, "greeting.txt");
+        assert_eq!(r.content_type.as_deref(), Some("text/plain"));
+        assert_eq!(r.bytes.as_ref(), b"hello");
+    }
+
+    #[test]
+    fn resolve_file_data_rejects_malformed_data_url() {
+        assert!(resolve_file_data("not-a-data-url", None).is_err());
+        assert!(resolve_file_data("data:text/plain;base64,!!!", None).is_err());
+    }
+
+    #[test]
+    fn collect_input_file_parts_walks_message_items() {
+        let payload_json = serde_json::json!({
+            "input": [
+                {
+                    "type": "message",
+                    "role": "user",
+                    "content": [
+                        {"type": "input_text", "text": "see attached"},
+                        {"type": "input_file", "file_id": "file-1111111111111111", "filename": "a.csv"}
+                    ]
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "input_file", "file_data": "data:text/plain;base64,aGk="}
+                    ]
+                }
+            ]
+        });
+        let payload: CreateResponsesPayload = serde_json::from_value(payload_json).unwrap();
+        let parts = collect_input_file_parts(&payload);
+        assert_eq!(parts.len(), 2);
+        assert!(parts[0].file_id.as_deref() == Some("file-1111111111111111"));
+        assert!(parts[1].file_data.is_some());
+    }
+
+    #[test]
+    fn collect_input_file_parts_returns_empty_for_text_input() {
+        let payload: CreateResponsesPayload = serde_json::from_value(serde_json::json!({
+            "input": "hello"
+        }))
+        .unwrap();
+        assert!(collect_input_file_parts(&payload).is_empty());
+    }
+
+    #[test]
+    fn short_content_hash_is_stable_and_8_chars() {
+        let h = short_content_hash(b"hello");
+        assert_eq!(h.len(), 8);
+        // sha256("hello") = 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
+        assert_eq!(h, "2cf24dba");
+    }
+
+    #[test]
+    fn validate_source_count_rejects_zero_and_multiple() {
+        let none = InputFilePart {
+            file_id: None,
+            file_data: None,
+            file_url: None,
+            filename: None,
+        };
+        assert!(matches!(
+            validate_source_count(&none),
+            Err(StageError::NoSource)
+        ));
+
+        let ambiguous = InputFilePart {
+            file_id: Some("file-x".into()),
+            file_data: Some("data:text/plain;base64,Zm9v".into()),
+            file_url: None,
+            filename: None,
+        };
+        assert!(matches!(
+            validate_source_count(&ambiguous),
+            Err(StageError::AmbiguousSource)
+        ));
+
+        let single = InputFilePart {
+            file_id: None,
+            file_data: Some("data:text/plain;base64,Zm9v".into()),
+            file_url: None,
+            filename: None,
+        };
+        assert!(validate_source_count(&single).is_ok());
+    }
+
+    #[test]
+    fn dedupe_filename_prefixes_collisions_with_hash() {
+        let mut seen = HashSet::new();
+        let first = dedupe_filename("data.csv".into(), b"first", &mut seen);
+        assert_eq!(first, "data.csv");
+        let second = dedupe_filename("data.csv".into(), b"second", &mut seen);
+        assert_ne!(second, "data.csv");
+        assert!(second.ends_with("-data.csv"));
+        // The prefix is the short hash of the *second* file's content.
+        assert!(second.starts_with(&short_content_hash(b"second")));
+        // And both names are tracked so a third collision picks up the
+        // already-prefixed name in the set rather than re-colliding.
+        assert!(seen.contains(&first));
+        assert!(seen.contains(&second));
+    }
+
+    #[test]
+    fn dedupe_filename_no_op_when_unique() {
+        let mut seen = HashSet::new();
+        let r = dedupe_filename("a.txt".into(), b"x", &mut seen);
+        assert_eq!(r, "a.txt");
+        let r2 = dedupe_filename("b.txt".into(), b"y", &mut seen);
+        assert_eq!(r2, "b.txt");
+    }
+
+    #[test]
+    fn dedupe_filename_handles_repeat_same_content_collisions() {
+        // Three uploads with identical content + filename: the first
+        // gets the bare name, the second a content-hash-prefixed name,
+        // the third a counter-suffixed prefix so all three stage
+        // distinct paths under `/mnt/data`.
+        let mut seen = HashSet::new();
+        let bytes = b"identical";
+        let a = dedupe_filename("doc.csv".into(), bytes, &mut seen);
+        let b = dedupe_filename("doc.csv".into(), bytes, &mut seen);
+        let c = dedupe_filename("doc.csv".into(), bytes, &mut seen);
+        assert_eq!(a, "doc.csv");
+        assert_ne!(b, a);
+        assert_ne!(c, a);
+        assert_ne!(c, b, "third occurrence must not collide with the second");
+        // Counter variant is recognizable.
+        let prefix = short_content_hash(bytes);
+        assert!(c.starts_with(&format!("{prefix}-2-")), "got: {c}");
+    }
+}
diff --git a/src/services/mcp/client.rs b/src/services/mcp/client.rs
new file mode 100644
index 0000000..067232e
--- /dev/null
+++ b/src/services/mcp/client.rs
@@ -0,0 +1,337 @@
+//! Thin Hadrian-friendly wrapper around [`rmcp`]'s Streamable-HTTP
+//! client. We hide rmcp's `Cow<'static, str>` / `JsonObject` /
+//! `Annotated<RawContent>` types behind plain serde JSON so the rest
+//! of Hadrian doesn't need to know about the MCP SDK's internals.
+
+use std::sync::Arc;
+
+use rmcp::{
+    RoleClient, ServiceExt,
+    model::{CallToolRequestParams, Content, RawContent},
+    service::RunningService,
+    transport::{
+        StreamableHttpClientTransport, streamable_http_client::StreamableHttpClientTransportConfig,
+    },
+};
+use thiserror::Error;
+
+/// One tool advertised by a remote MCP server. The shape mirrors
+/// [`api_types::responses::McpListedTool`](crate::api_types::responses::McpListedTool)
+/// so the executor can re-emit the catalog as an `mcp_list_tools`
+/// item without re-deriving fields.
+#[derive(Debug, Clone)]
+pub struct McpToolMeta {
+    pub name: String,
+    pub description: Option<String>,
+    pub input_schema: serde_json::Value,
+    /// Raw annotations forwarded from the server (read-only hint,
+    /// idempotency, etc.). `None` if the server didn't supply any.
+    pub annotations: Option<serde_json::Value>,
+}
+
+impl McpToolMeta {
+    fn from_rmcp(tool: rmcp::model::Tool) -> Self {
+        let input_schema =
+            serde_json::to_value(tool.input_schema.as_ref()).unwrap_or(serde_json::json!({}));
+        let annotations = tool
+            .annotations
+            .as_ref()
+            .and_then(|a| serde_json::to_value(a).ok());
+        Self {
+            name: tool.name.into_owned(),
+            description: tool.description.map(|d| d.into_owned()),
+            input_schema,
+            annotations,
+        }
+    }
+}
+
+/// Hadrian-side projection of `rmcp::model::CallToolResult`. We flatten
+/// the content array down to a single text payload (the model only
+/// consumes text), preserve a structured-content fallback, and surface
+/// `is_error` so the executor can populate `mcp_call.error`.
+#[derive(Debug, Clone)]
+pub struct McpCallResult {
+    /// True iff the server returned `isError = true`.
+    pub is_error: bool,
+    /// Text content concatenated in order. Empty when the server
+    /// returned only non-text content (images, etc.).
+    pub text: String,
+    /// Optional `structuredContent` from the result (JSON object the
+    /// server attached for richer consumers).
+    pub structured_content: Option<serde_json::Value>,
+    /// Non-text content blocks the server returned, kept verbatim so
+    /// callers can render images / resources if they choose to.
+    pub extra_content: Vec<McpCallContent>,
+}
+
+/// Non-text content block from a tool result, captured verbatim so
+/// future consumers (e.g. image rendering in the chat UI) can use it
+/// without going through rmcp.
+#[derive(Debug, Clone)]
+pub struct McpCallContent {
+    /// Content kind: `"image"`, `"audio"`, `"resource"`, `"resource_link"`.
+    pub kind: String,
+    /// Raw JSON of the content block.
+    pub value: serde_json::Value,
+}
+
+#[derive(Debug, Error)]
+pub enum McpClientError {
+    #[error("MCP transport setup failed: {0}")]
+    Transport(String),
+    #[error("MCP handshake (initialize) failed: {0}")]
+    Initialize(String),
+    #[error("MCP `tools/list` failed: {0}")]
+    ListTools(String),
+    #[error("MCP `tools/call` ({tool}) failed: {message}")]
+    CallTool { tool: String, message: String },
+    #[error("MCP arguments must serialize to a JSON object, got: {0}")]
+    NonObjectArguments(String),
+}
+
+/// A live MCP client session. Wraps `rmcp`'s `RunningService` so the
+/// connection stays open across multiple `call_tool` invocations
+/// during a single response.
+///
+/// One `McpClient` represents one `(server_url, authorization)` pair.
+/// [`McpService`](super::service::McpService) keys a `DashMap` of these
+/// (behind `Arc`) for cross-request reuse; `list_tools` / `call_tool`
+/// take `&self`, so the pooled handle is shared without a mutex.
+pub struct McpClient {
+    service: Option<RunningService<RoleClient, ()>>,
+    server_url: Arc<str>,
+}
+
+impl McpClient {
+    /// Open a Streamable HTTP connection to `server_url`, send
+    /// `initialize`, and return a ready-to-use client.
+    ///
+    /// `authorization` is sent verbatim in the `Authorization` HTTP
+    /// header on every request — caller is responsible for the
+    /// `Bearer ` prefix (or whatever the upstream expects).
+    /// `headers` are merged into every request.
+    ///
+    /// `host` / `addrs` are the hostname and the IP addresses it was
+    /// validated to resolve to. The underlying reqwest client is pinned
+    /// to those addresses so it cannot independently re-resolve the host
+    /// (closing the DNS-rebinding TOCTOU between SSRF validation and the
+    /// connection). When `addrs` is empty the default resolver is used.
+    pub async fn connect(
+        server_url: impl Into<Arc<str>>,
+        host: &str,
+        addrs: &[std::net::SocketAddr],
+        authorization: Option<String>,
+        headers: std::collections::HashMap<String, String>,
+    ) -> Result<Self, McpClientError> {
+        let server_url: Arc<str> = server_url.into();
+
+        let mut custom_headers = std::collections::HashMap::new();
+        for (k, v) in headers {
+            let name = http::HeaderName::try_from(k.as_str()).map_err(|e| {
+                McpClientError::Transport(format!("invalid header name '{k}': {e}"))
+            })?;
+            let value = http::HeaderValue::try_from(v.as_str()).map_err(|e| {
+                McpClientError::Transport(format!("invalid header value for '{k}': {e}"))
+            })?;
+            custom_headers.insert(name, value);
+        }
+
+        let mut cfg = StreamableHttpClientTransportConfig::with_uri(server_url.clone());
+        if let Some(auth) = authorization {
+            cfg = cfg.auth_header(strip_bearer_prefix(&auth));
+        }
+        cfg = cfg.custom_headers(custom_headers);
+
+        // Mirror rmcp's default client (`pool_max_idle_per_host(0)`) but
+        // pin DNS for the validated host to the validated IPs. reqwest
+        // ignores the port in these socket addrs (it uses the URL's), so
+        // we override resolution to exactly the addresses the SSRF guard
+        // approved. Built with `reqwest_mcp` (reqwest 0.12) — the version
+        // rmcp's `StreamableHttpClient` is implemented for.
+        let mut builder = reqwest_mcp::Client::builder().pool_max_idle_per_host(0);
+        if !addrs.is_empty() {
+            builder = builder.resolve_to_addrs(host, addrs);
+        }
+        let http_client = builder
+            .build()
+            .map_err(|e| McpClientError::Transport(format!("failed to build HTTP client: {e}")))?;
+
+        let transport = StreamableHttpClientTransport::with_client(http_client, cfg);
+        let service =
+            ().serve(transport)
+                .await
+                .map_err(|e| McpClientError::Initialize(e.to_string()))?;
+
+        Ok(Self {
+            service: Some(service),
+            server_url,
+        })
+    }
+
+    /// URL of the connected MCP server.
+    pub fn server_url(&self) -> &str {
+        &self.server_url
+    }
+
+    /// Fetch the full tool catalog (auto-paginated via
+    /// `list_all_tools`).
+    pub async fn list_tools(&self) -> Result<Vec<McpToolMeta>, McpClientError> {
+        let svc = self
+            .service
+            .as_ref()
+            .ok_or_else(|| McpClientError::ListTools("client already closed".to_string()))?;
+        let tools = svc
+            .peer()
+            .list_all_tools()
+            .await
+            .map_err(|e| McpClientError::ListTools(e.to_string()))?;
+        Ok(tools.into_iter().map(McpToolMeta::from_rmcp).collect())
+    }
+
+    /// Invoke a tool by name. `arguments` must serialize to a JSON
+    /// object — MCP doesn't accept arrays or scalars at the top level.
+    pub async fn call_tool(
+        &self,
+        name: &str,
+        arguments: serde_json::Value,
+    ) -> Result<McpCallResult, McpClientError> {
+        let svc = self
+            .service
+            .as_ref()
+            .ok_or_else(|| McpClientError::CallTool {
+                tool: name.to_string(),
+                message: "client already closed".to_string(),
+            })?;
+
+        let args_obj = match arguments {
+            serde_json::Value::Null => None,
+            serde_json::Value::Object(map) => Some(map),
+            other => {
+                return Err(McpClientError::NonObjectArguments(other.to_string()));
+            }
+        };
+
+        let mut params = CallToolRequestParams::new(name.to_string());
+        params.arguments = args_obj;
+
+        let result = svc
+            .peer()
+            .call_tool(params)
+            .await
+            .map_err(|e| McpClientError::CallTool {
+                tool: name.to_string(),
+                message: e.to_string(),
+            })?;
+
+        Ok(flatten_call_result(result))
+    }
+
+    /// Gracefully close the connection. Idempotent — safe to call
+    /// once after pool eviction or once before drop.
+    pub async fn close(mut self) -> Result<(), McpClientError> {
+        if let Some(svc) = self.service.take() {
+            svc.cancel()
+                .await
+                .map_err(|e| McpClientError::Transport(e.to_string()))?;
+        }
+        Ok(())
+    }
+}
+
+impl Drop for McpClient {
+    fn drop(&mut self) {
+        if let Some(svc) = self.service.take() {
+            // RunningService logs a warning if dropped without explicit
+            // close — avoid the noise for the common case (pool TTL
+            // eviction can't await). Spawn a detached cancel.
+            tokio::spawn(async move {
+                let _ = svc.cancel().await;
+            });
+        }
+    }
+}
+
+/// If `value` starts with `Bearer ` (case-insensitive), drop the
+/// prefix. rmcp prepends `Bearer ` itself; double-prefixing would
+/// produce `Authorization: Bearer Bearer …` which servers reject.
+fn strip_bearer_prefix(value: &str) -> String {
+    let trimmed = value.trim_start();
+    if let Some(prefix) = trimmed.get(..7)
+        && prefix.eq_ignore_ascii_case("bearer ")
+    {
+        return trimmed.get(7..).unwrap_or("").trim_start().to_string();
+    }
+    trimmed.to_string()
+}
+
+fn flatten_call_result(result: rmcp::model::CallToolResult) -> McpCallResult {
+    let mut text_parts = Vec::new();
+    let mut extra = Vec::new();
+
+    for content in result.content {
+        match flatten_content(content) {
+            FlattenedContent::Text(t) => text_parts.push(t),
+            FlattenedContent::Other(kind, value) => extra.push(McpCallContent { kind, value }),
+        }
+    }
+
+    McpCallResult {
+        is_error: result.is_error.unwrap_or(false),
+        text: text_parts.join("\n"),
+        structured_content: result.structured_content,
+        extra_content: extra,
+    }
+}
+
+enum FlattenedContent {
+    Text(String),
+    Other(String, serde_json::Value),
+}
+
+fn flatten_content(content: Content) -> FlattenedContent {
+    match content.raw {
+        RawContent::Text(t) => FlattenedContent::Text(t.text),
+        RawContent::Image(img) => {
+            FlattenedContent::Other("image".to_string(), to_value_or_null("image", &img))
+        }
+        RawContent::Audio(a) => {
+            FlattenedContent::Other("audio".to_string(), to_value_or_null("audio", &a))
+        }
+        RawContent::Resource(r) => {
+            FlattenedContent::Other("resource".to_string(), to_value_or_null("resource", &r))
+        }
+        RawContent::ResourceLink(r) => FlattenedContent::Other(
+            "resource_link".to_string(),
+            to_value_or_null("resource_link", &r),
+        ),
+    }
+}
+
+/// Serialize an MCP content block to JSON, logging (rather than silently
+/// swallowing) a failure and falling back to `null` so one bad block
+/// doesn't drop the whole result.
+fn to_value_or_null<T: serde::Serialize>(kind: &str, value: &T) -> serde_json::Value {
+    serde_json::to_value(value).unwrap_or_else(|e| {
+        tracing::warn!(
+            content_kind = kind,
+            error = %e,
+            "Failed to serialize MCP {kind} content block; dropping it (null)"
+        );
+        serde_json::Value::Null
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn strip_bearer_handles_case_insensitive() {
+        assert_eq!(strip_bearer_prefix("Bearer xyz"), "xyz");
+        assert_eq!(strip_bearer_prefix("BEARER xyz"), "xyz");
+        assert_eq!(strip_bearer_prefix("bearer xyz"), "xyz");
+        assert_eq!(strip_bearer_prefix("xyz"), "xyz");
+        assert_eq!(strip_bearer_prefix("  Bearer  xyz"), "xyz");
+    }
+}
diff --git a/src/services/mcp/executor.rs b/src/services/mcp/executor.rs
new file mode 100644
index 0000000..591bbe4
--- /dev/null
+++ b/src/services/mcp/executor.rs
@@ -0,0 +1,1989 @@
+//! `McpExecutor` — the [`ServerExecutedTool`] that intercepts the
+//! function calls produced by [`super::preprocess::rewrite_mcp_tools`]
+//! and dispatches them to the right pooled MCP client.
+//!
+//! Lifecycle per call:
+//! 1. The upstream provider emits `response.output_item.done` with a
+//!    `function_call` item whose `name` matches `mcp_<label>__<tool>`.
+//! 2. `detect()` parses the function name and arguments, returns one
+//!    `DetectedToolCall` per match.
+//! 3. `execute()` resolves `<label>` back to the requesting `McpTool`
+//!    (server_url + auth + headers), emits the `mcp_call` lifecycle
+//!    events (`output_item.added`, `mcp_call_arguments.delta/done`,
+//!    `mcp_call.in_progress`, then `mcp_call.completed`/`.failed` plus
+//!    a terminal `output_item.done` with `output` / `error` inlined on
+//!    the same `mcp_call` item), and folds a `function_call_output`
+//!    continuation item for the next provider request.
+//! 4. The runner re-invokes `ResponsesExecutor::execute` with the
+//!    continuation payload, which triggers another tools/list-cached
+//!    rewrite (idempotent — same catalog → same function tools).
+//!
+//! Calls gated by `require_approval` are parked instead of executed.
+//! [`McpExecutor::park_for_approval`] writes a row to
+//! `mcp_pending_approvals` and emits the canonical `mcp_approval_request`
+//! item; [`super::resume::resume_mcp_approvals`] picks the parked call
+//! back up when a follow-up request carries a matching
+//! `mcp_approval_response` input item.
+
+use async_trait::async_trait;
+use bytes::Bytes;
+use serde_json::Value;
+use tokio::sync::mpsc;
+use tracing::warn;
+
+use super::{McpCallResult, McpService, preprocess::parse_function_name};
+use crate::{
+    api_types::responses::{
+        CreateResponsesPayload, FunctionCallOutput, McpTool, ResponsesInput, ResponsesInputItem,
+        ResponsesToolDefinition,
+    },
+    services::server_tools::{
+        DetectedToolCall, ServerExecutedTool, ToolCallResult, ToolContext, ToolError,
+        ToolExecutionHandle,
+    },
+};
+
+/// One MCP server's connection details, captured from a `McpTool` entry
+/// on the request. Used by [`McpExecutor::resolve_binding`] to map a
+/// detected function call back to the server it belongs to.
+#[derive(Clone)]
+struct ServerBinding {
+    server_label: String,
+    server_url: String,
+    authorization: Option<String>,
+    headers: std::collections::HashMap<String, String>,
+    /// Sanitized form of `server_label` — what appears in the function
+    /// name the model invokes. Computed once at executor construction
+    /// to match the rewrite output.
+    sanitized_label: String,
+    /// Per-server approval policy, captured at request time. The
+    /// executor consults this before every call to decide whether to
+    /// park or run.
+    require_approval: Option<crate::api_types::responses::McpRequireApproval>,
+    /// Upper bound on a single `tools/call` round-trip. Resolved at
+    /// construction from the tool's `call_timeout_secs` Hadrian extension,
+    /// falling back to `[features.mcp].call_timeout_secs`.
+    call_timeout: std::time::Duration,
+}
+
+impl ServerBinding {
+    fn from_mcp(tool: &McpTool, default_call_timeout_secs: u64) -> Option<Self> {
+        let server_url = tool.server_url.clone()?;
+        // Synthesize a known function name with a sentinel tool to
+        // extract just the sanitized label. Keeps the two sides aligned
+        // even if `sanitize_label`'s rules evolve.
+        let synthesized = super::synthesize_function_name(&tool.server_label, "x");
+        let (sanitized_label, _) = parse_function_name(&synthesized)?;
+        let timeout_secs = tool.call_timeout_secs.unwrap_or(default_call_timeout_secs);
+        Some(Self {
+            server_label: tool.server_label.clone(),
+            server_url,
+            authorization: tool.authorization.clone(),
+            headers: tool.headers.clone().unwrap_or_default(),
+            sanitized_label: sanitized_label.to_string(),
+            require_approval: tool.require_approval.clone(),
+            call_timeout: std::time::Duration::from_secs(timeout_secs),
+        })
+    }
+
+    /// Decide whether a call to `tool_name` on this server should be
+    /// gated by approval. Honors the spec's three shapes:
+    ///
+    /// - `None` → spec default is `"always"`
+    ///   (`openapi/openai.openapi.json::MCPTool.require_approval`); gate.
+    /// - `Mode(Never)` → never gate.
+    /// - `Mode(Always)` → always gate.
+    /// - `Filter { always, never }` → if `never` matches, skip; else
+    ///   if `always` matches, gate; else gate by default (matches the
+    ///   `Always` default OpenAI documents for the filter object form).
+    ///
+    /// `read_only` predicate on a filter matches only when the tool
+    /// carries an explicit MCP `readOnlyHint` annotation equal to the
+    /// filter value (passed in via `read_only_hint`); `None` (no
+    /// annotation) matches neither `read_only: true` nor `false`.
+    fn requires_approval(&self, tool_name: &str, read_only_hint: Option<bool>) -> bool {
+        use crate::api_types::responses::{McpApprovalMode, McpRequireApproval};
+        match &self.require_approval {
+            None => true,
+            Some(McpRequireApproval::Mode(McpApprovalMode::Never)) => false,
+            Some(McpRequireApproval::Mode(McpApprovalMode::Always)) => true,
+            Some(McpRequireApproval::Filter(f)) => {
+                if let Some(never) = f.never.as_ref()
+                    && filter_matches(never, tool_name, read_only_hint)
+                {
+                    return false;
+                }
+                if let Some(always) = f.always.as_ref()
+                    && filter_matches(always, tool_name, read_only_hint)
+                {
+                    return true;
+                }
+                // Default for the object form: gate. OpenAI documents
+                // the filter object as a way to *exempt* specific tools;
+                // anything not explicitly listed keeps the default.
+                true
+            }
+        }
+    }
+}
+
+/// True iff `tool_name` (and its read-only hint) match every constraint
+/// declared on the filter. Empty constraints (both fields `None`) match
+/// every tool.
+fn filter_matches(
+    filter: &crate::api_types::responses::McpToolFilter,
+    tool_name: &str,
+    read_only_hint: Option<bool>,
+) -> bool {
+    if let Some(names) = filter.tool_names.as_ref()
+        && !names.iter().any(|n| n == tool_name)
+    {
+        return false;
+    }
+    if let Some(required) = filter.read_only
+        && read_only_hint != Some(required)
+    {
+        // Per the MCP tool filter spec, a `read_only` predicate matches
+        // only tools annotated with `readOnlyHint`; an absent annotation
+        // matches neither `true` nor `false`.
+        return false;
+    }
+    true
+}
+
+/// Server-executed-tool implementation for MCP.
+///
+/// One executor instance per `/v1/responses` request — built in
+/// `apply_streaming_pipeline` after the request payload is admitted.
+pub struct McpExecutor {
+    /// Pooled MCP clients + tools/list cache.
+    service: McpService,
+    /// All MCP tool entries originally on the request, captured before
+    /// the rewrite stripped them. Each is a server we may need to call
+    /// during this response.
+    bindings: Vec<ServerBinding>,
+    /// Server labels whose `mcp_list_tools` snapshot is already in the
+    /// caller's context (via a prior `previous_response_id`). For these
+    /// we skip emitting a fresh catalog so SDKs see the snapshot exactly
+    /// once per conversation, matching OpenAI's behavior.
+    suppress_list_tools: std::collections::HashSet<String>,
+    /// Identifier of the response this executor is serving. Used to
+    /// scope `mcp_pending_approvals` rows. `None` when the request
+    /// isn't persisted (e.g. `store=false` with no DB), in which case a
+    /// gated call fails closed — it cannot be parked for resume, so
+    /// [`Self::park_for_approval`] synthesizes a failed `mcp_call`
+    /// rather than executing the tool.
+    response_id: Option<String>,
+    /// Org scope for parked approvals.
+    org_id: Option<uuid::Uuid>,
+    /// TTL for parked approvals. Rows past this are reaped by the
+    /// existing retention worker. Default 24h to give users plenty of
+    /// time to decide; configurable per-deployment is a future tweak.
+    approval_ttl_secs: u64,
+    /// Approvals resolved by the resume path on this request, drained
+    /// out of [`McpService::take_resolved_approval`] at construction.
+    /// Emitted as synthesized `mcp_call` output items by
+    /// [`Self::prefix_events`] so the resumed response stream carries
+    /// the spec-mandated item lifecycle (`output_item.added`,
+    /// `response.mcp_call.in_progress`, `response.mcp_call.completed`
+    /// or `.failed`, `output_item.done`).
+    resumed_approvals: Vec<super::ResolvedMcpApproval>,
+    /// Hides the rewritten `mcp_<label>__<tool>` function-call plumbing
+    /// from the client stream — we synthesize the spec-shaped `mcp_call`
+    /// items ourselves (see [`Self::transform_event`]). Shared with the
+    /// other server tools.
+    suppressor: crate::services::server_tools::FunctionCallSuppressor,
+}
+
+/// Fallback per-call timeout used by [`McpExecutor::new`] and tests.
+/// Mirrors `[features.mcp].call_timeout_secs`'s default; the real
+/// pipeline path always passes the configured value to
+/// [`McpExecutor::with_persistence`].
+const DEFAULT_CALL_TIMEOUT_SECS: u64 = 300;
+
+impl McpExecutor {
+    pub fn new(service: McpService, original_payload: &CreateResponsesPayload) -> Self {
+        Self::with_persistence(
+            service,
+            original_payload,
+            None,
+            None,
+            DEFAULT_CALL_TIMEOUT_SECS,
+        )
+    }
+
+    /// Construct an executor that can persist parked approvals. Pass
+    /// `response_id` / `org_id` when both are known (DB-backed
+    /// responses); otherwise use [`McpExecutor::new`] and a gated call
+    /// fails closed (a parked-for-approval tool cannot be resumed
+    /// without persistence, so it synthesizes a failed `mcp_call`).
+    /// `default_call_timeout_secs` is the deployment default applied to
+    /// any `mcp` tool that doesn't set its own `call_timeout_secs`.
+    pub fn with_persistence(
+        service: McpService,
+        original_payload: &CreateResponsesPayload,
+        response_id: Option<String>,
+        org_id: Option<uuid::Uuid>,
+        default_call_timeout_secs: u64,
+    ) -> Self {
+        let bindings: Vec<ServerBinding> = original_payload
+            .tools
+            .as_ref()
+            .map(|tools| {
+                tools
+                    .iter()
+                    .filter_map(|t| t.as_mcp())
+                    .filter_map(|m| ServerBinding::from_mcp(m, default_call_timeout_secs))
+                    .collect()
+            })
+            .unwrap_or_default();
+        let suppress_list_tools = collect_inlined_list_tools_labels(original_payload);
+        // Drain any approvals the resume path just resolved on this
+        // request. Match by `call_id` of `function_call_output` items
+        // the resume wrote into `payload.input` — that's our stable
+        // join key.
+        let resumed_approvals = drain_resumed_approvals(&service, org_id, original_payload);
+        Self {
+            service,
+            bindings,
+            suppress_list_tools,
+            response_id,
+            org_id,
+            approval_ttl_secs: 86_400,
+            resumed_approvals,
+            suppressor: crate::services::server_tools::FunctionCallSuppressor::new(),
+        }
+    }
+
+    /// `true` iff the tool's `readOnlyHint` annotation is set to true.
+    /// `false` when unknown / missing — matches OpenAI's documented
+    /// behavior for the `read_only` filter (matches only when the
+    /// server explicitly annotated the tool as read-only). Reads the
+    /// service-level `tools/list` cache, which the rewrite primed for
+    /// this endpoint moments earlier.
+    /// The tool's MCP `readOnlyHint` annotation, or `None` when the tool
+    /// has no such annotation (or the catalog isn't cached). `None` is
+    /// distinct from `Some(false)`: a `read_only` filter only matches an
+    /// explicit annotation, so the absence must not be coerced to false.
+    fn read_only_hint_for(&self, binding: &ServerBinding, tool_name: &str) -> Option<bool> {
+        let catalog = self.service.cached_tools(
+            &binding.server_url,
+            binding.authorization.as_deref(),
+            &binding.headers,
+        )?;
+        catalog
+            .iter()
+            .find(|t| t.name == tool_name)
+            .and_then(|t| t.annotations.as_ref())
+            .and_then(|a| a.get("readOnlyHint"))
+            .and_then(|v| v.as_bool())
+    }
+
+    /// True when this request had at least one `mcp` tool entry the
+    /// executor can serve, or at least one resumed approval to surface
+    /// as an `mcp_call` item.
+    pub fn has_bindings(&self) -> bool {
+        !self.bindings.is_empty() || !self.resumed_approvals.is_empty()
+    }
+
+    fn resolve_binding(&self, sanitized_label: &str) -> Option<&ServerBinding> {
+        self.bindings
+            .iter()
+            .find(|b| b.sanitized_label == sanitized_label)
+    }
+
+    /// Park a model-initiated call for human approval.
+    ///
+    /// Emits the canonical `mcp_approval_request` SSE item, persists
+    /// the call to `mcp_pending_approvals` so a follow-up
+    /// `mcp_approval_response` can find it, and synthesizes a
+    /// `function_call_output` telling the model to stop and wait.
+    ///
+    /// **Fail-closed**: when persistence is unavailable (no DB, the
+    /// request is `store=false`, or the principal has no org), the
+    /// call is *not* run. Instead a synthesized `mcp_call` item with
+    /// `status="failed"` and an explanatory `error` is emitted, and
+    /// the continuation `function_call_output` carries the same error.
+    /// Letting the call through silently would defeat the purpose of
+    /// `require_approval`.
+    async fn park_for_approval(
+        &self,
+        binding: &ServerBinding,
+        call_id: &str,
+        tool_name: &str,
+        arguments: &Value,
+    ) -> Result<ToolExecutionHandle, ToolError> {
+        let (Some(repo), Some(response_id), Some(org_id)) = (
+            self.service.approvals_repo().cloned(),
+            self.response_id.clone(),
+            self.org_id,
+        ) else {
+            // Diagnose which precondition is missing so the operator/
+            // caller can fix it. The order mirrors the destructuring:
+            // no repo → no DB; no response_id → store=false (or no DB);
+            // no org_id → anonymous request.
+            let missing = if self.service.approvals_repo().is_none() {
+                "no database is configured (server-side)"
+            } else if self.response_id.is_none() {
+                "the request was sent with `store=false` (or persistence is not \
+                 wired for this response); approvals require a persisted response \
+                 so the parked call can be resumed"
+            } else {
+                "the request has no authenticated organization scope"
+            };
+            let err = format!(
+                "MCP `require_approval` gates this tool but the gateway cannot park \
+                 the call: {missing}. Set `[features.mcp]` with a database, send \
+                 `store=true`, and authenticate the request — or set \
+                 `require_approval=\"never\"` if gating isn't desired."
+            );
+            tracing::error!(
+                server_label = %binding.server_label,
+                tool = %tool_name,
+                error = %err,
+                "MCP approval gate failing closed"
+            );
+            return self.synthesize_failed_call(binding, call_id, tool_name, arguments, err);
+        };
+
+        let approval_id = format!("mcpr_{}", uuid::Uuid::new_v4().simple());
+        let now = crate::db::repos::truncate_to_millis(chrono::Utc::now());
+        let expires_at = now + chrono::Duration::seconds(self.approval_ttl_secs as i64);
+
+        // `arguments` was parsed from the model's JSON, so serializing it
+        // back can't realistically fail; if it ever does, persisting `{}`
+        // would silently drop the model's intent on resume — log loudly.
+        let arguments_json = serde_json::to_string(arguments).unwrap_or_else(|e| {
+            tracing::error!(
+                server_label = %binding.server_label,
+                tool = %tool_name,
+                error = %e,
+                "Failed to serialize MCP call arguments while parking for approval; storing empty"
+            );
+            "{}".to_string()
+        });
+
+        // Strip path / query from `server_url` before persistence —
+        // matches OpenAI's "discard everything but scheme+host" rule.
+        // The resume path pulls the live URL from `payload.tools` so
+        // the trimmed copy is only ever used for audit / lookup keys.
+        let stored_server_url = crate::routes::api::chat::trim_url_to_origin(&binding.server_url);
+
+        repo.insert(crate::db::repos::NewMcpPendingApproval {
+            id: approval_id.clone(),
+            response_id,
+            org_id,
+            call_id: call_id.to_string(),
+            server_label: binding.server_label.clone(),
+            server_url: stored_server_url,
+            tool_name: tool_name.to_string(),
+            arguments_json: arguments_json.clone(),
+            created_at: now,
+            expires_at,
+        })
+        .await
+        .map_err(|e| ToolError::ExecutionFailed(format!("MCP approval persist failed: {e}")))?;
+
+        let (event_tx, event_rx) = mpsc::channel::<Bytes>(8);
+        let (result_tx, result_rx) =
+            tokio::sync::oneshot::channel::<Result<ToolCallResult, ToolError>>();
+
+        // Emit `mcp_approval_request` as a paired added/done item.
+        // Every other Responses-API output item emits `.added` before
+        // `.done`; SDKs that key off the open→close transition need
+        // both edges, so match that here even though we have nothing
+        // incremental to stream between them.
+        let request_item = mcp_approval_request_item(
+            &approval_id,
+            &binding.server_label,
+            tool_name,
+            &arguments_json,
+        );
+        let _ = event_tx
+            .send(sse_output_item(
+                "response.output_item.added",
+                request_item.clone(),
+            ))
+            .await;
+        let _ = event_tx
+            .send(sse_output_item("response.output_item.done", request_item))
+            .await;
+
+        let call_id_owned = call_id.to_string();
+        let server_label_owned = binding.server_label.clone();
+        let tool_name_owned = tool_name.to_string();
+        // Spawn so the channel survives until the runner pulls the
+        // event; the actual continuation is synthesized immediately.
+        tokio::spawn(async move {
+            // Tell the model to stop and wait. Without an output the
+            // function_call has no result; with one, the model sees a
+            // clear "do not continue" signal and the response ends in
+            // an assistant turn rather than burning the iteration
+            // budget on retries.
+            let waiting_msg = serde_json::json!({
+                "status": "pending_approval",
+                "approval_request_id": approval_id,
+                "server_label": server_label_owned,
+                "tool": tool_name_owned,
+                "message": "Call gated by `require_approval`. Stop here — the caller \
+                            must submit an `mcp_approval_response` on a follow-up \
+                            request to resume."
+            })
+            .to_string();
+            let continuation = ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+                type_: crate::api_types::responses::FunctionCallOutputType::FunctionCallOutput,
+                id: None,
+                call_id: call_id_owned.clone(),
+                output: waiting_msg,
+                status: None,
+            });
+            let _ = result_tx.send(Ok(ToolCallResult {
+                call_id: call_id_owned,
+                continuation_items: vec![continuation],
+            }));
+            drop(event_tx);
+        });
+
+        Ok(ToolExecutionHandle {
+            events: Box::pin(futures_util::stream::unfold(
+                event_rx,
+                |mut rx| async move { rx.recv().await.map(|item| (item, rx)) },
+            )),
+            result: Box::pin(async move {
+                result_rx.await.map_err(|_| {
+                    ToolError::ExecutionFailed(
+                        "MCP approval task dropped before sending result".to_string(),
+                    )
+                })?
+            }),
+        })
+    }
+
+    /// Synthesize a failed `mcp_call` item without touching the
+    /// upstream — used when the approval gate fails closed because
+    /// persistence isn't available. Emits the same item lifecycle as
+    /// `dispatch_call` (`output_item.added` → `output_item.done` →
+    /// `response.mcp_call.failed`) but skips the HTTP round-trip and
+    /// fills in `error` directly. The continuation carries the same
+    /// error JSON so the model sees a clean refusal.
+    fn synthesize_failed_call(
+        &self,
+        binding: &ServerBinding,
+        call_id: &str,
+        tool_name: &str,
+        raw_args: &Value,
+        error_msg: String,
+    ) -> Result<ToolExecutionHandle, ToolError> {
+        let item_id = next_item_id("mcp");
+
+        let (event_tx, event_rx) = mpsc::channel::<Bytes>(4);
+        let (result_tx, result_rx) =
+            tokio::sync::oneshot::channel::<Result<ToolCallResult, ToolError>>();
+
+        let failed_item = mcp_call_item(
+            &item_id,
+            &binding.server_label,
+            tool_name,
+            raw_args,
+            "failed",
+            None,
+            Some(error_msg.as_str()),
+            None,
+        );
+        let added = sse_output_item("response.output_item.added", failed_item.clone());
+        let done = sse_output_item("response.output_item.done", failed_item);
+        let lifecycle = sse_mcp_lifecycle_event("response.mcp_call.failed", &item_id);
+
+        let call_id_owned = call_id.to_string();
+        let error_for_task = error_msg.clone();
+        tokio::spawn(async move {
+            // Spec order: lifecycle `failed` precedes terminal `done`.
+            for ev in [added, lifecycle, done] {
+                if event_tx.send(ev).await.is_err() {
+                    return;
+                }
+            }
+            let continuation = ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+                type_: crate::api_types::responses::FunctionCallOutputType::FunctionCallOutput,
+                id: None,
+                call_id: call_id_owned.clone(),
+                output: serde_json::json!({ "error": error_for_task }).to_string(),
+                status: None,
+            });
+            let _ = result_tx.send(Ok(ToolCallResult {
+                call_id: call_id_owned,
+                continuation_items: vec![continuation],
+            }));
+            drop(event_tx);
+        });
+
+        Ok(ToolExecutionHandle {
+            events: Box::pin(futures_util::stream::unfold(
+                event_rx,
+                |mut rx| async move { rx.recv().await.map(|item| (item, rx)) },
+            )),
+            result: Box::pin(async move {
+                result_rx.await.map_err(|_| {
+                    ToolError::ExecutionFailed(
+                        "MCP fail-closed task dropped before sending result".to_string(),
+                    )
+                })?
+            }),
+        })
+    }
+
+    /// Run an MCP `tools/call` and stream the canonical `mcp_call`
+    /// lifecycle events. The result is inlined onto the terminal
+    /// `mcp_call` item — there is no separate `mcp_call_output` per
+    /// OpenAI's spec. Used by the normal `execute()` path after the
+    /// approval gate either passes or has already been resolved on a
+    /// follow-up request.
+    async fn dispatch_call(
+        &self,
+        binding: ServerBinding,
+        call_id: String,
+        tool_name: String,
+        raw_args: Value,
+        approval_request_id: Option<String>,
+    ) -> Result<ToolExecutionHandle, ToolError> {
+        let service = self.service.clone();
+
+        let (event_tx, event_rx) = mpsc::channel::<Bytes>(16);
+        let (result_tx, result_rx) =
+            tokio::sync::oneshot::channel::<Result<ToolCallResult, ToolError>>();
+
+        // Emit the full MCP lifecycle ahead of the actual call:
+        //   response.output_item.added         (mcp_call status=in_progress)
+        //   response.mcp_call_arguments.delta  (single chunk of full args)
+        //   response.mcp_call_arguments.done
+        //   response.mcp_call.in_progress
+        // We have no incremental source for the arguments under
+        // hadrian_hosted (the upstream emits the function_call
+        // atomically via `output_item.done`), so the delta carries
+        // the full argument JSON in one chunk.
+        let call_item_id = next_item_id("mcp");
+        let arguments_str = serde_json::to_string(&raw_args).unwrap_or_else(|_| "{}".to_string());
+        let approval_req = approval_request_id.clone();
+
+        // Initial item status is `calling` rather than `in_progress`:
+        // under hadrian_hosted the model's function_call arrived
+        // atomically from the upstream, so by the time we emit the
+        // `output_item.added` we are already invoking the MCP server.
+        // `MCPToolCallStatus` defines `calling` for exactly this state
+        // (`openapi/openai.openapi.json::MCPToolCallStatus`); using it
+        // here lets SDKs and persistence reflect that the args phase
+        // is done and the network round-trip is in flight.
+        let _ = event_tx
+            .send(sse_output_item(
+                "response.output_item.added",
+                mcp_call_item(
+                    &call_item_id,
+                    &binding.server_label,
+                    &tool_name,
+                    &raw_args,
+                    "calling",
+                    None,
+                    None,
+                    approval_req.as_deref(),
+                ),
+            ))
+            .await;
+        let _ = event_tx
+            .send(sse_mcp_arguments_event(
+                "response.mcp_call_arguments.delta",
+                &call_item_id,
+                Some(&arguments_str),
+            ))
+            .await;
+        let _ = event_tx
+            .send(sse_mcp_arguments_event(
+                "response.mcp_call_arguments.done",
+                &call_item_id,
+                Some(&arguments_str),
+            ))
+            .await;
+        let _ = event_tx
+            .send(sse_mcp_lifecycle_event(
+                "response.mcp_call.in_progress",
+                &call_item_id,
+            ))
+            .await;
+
+        // Spawn the actual call so the executor returns its handle
+        // immediately and the runner can stream the `added` events
+        // while we work.
+        let binding_for_task = binding.clone();
+        let approval_req_for_task = approval_request_id;
+        tokio::spawn(async move {
+            // Bound the call: `rmcp` applies no request timeout and the
+            // reqwest client it builds sets none either, so a server that
+            // accepts the connection and then stalls would hang the whole
+            // response. On expiry we cancel the in-flight future and
+            // surface an `incomplete` call.
+            let call_timeout = binding_for_task.call_timeout;
+            let outcome = tokio::time::timeout(
+                call_timeout,
+                run_call(&service, &binding_for_task, &tool_name, raw_args.clone()),
+            )
+            .await;
+
+            // OpenAI's `mcp_call.output` is a plain string. MCP servers
+            // may return `text` content, `structuredContent` (a JSON
+            // object), or non-text blocks (image/audio/resource). We
+            // collapse to one string in priority order so the model
+            // always gets _something_ readable: text first, then a
+            // JSON-encoded `structuredContent`, then `{}` as a last
+            // resort. Mirrors the same fallback in `resume.rs`.
+            // `output` is populated only for a successful call. On any
+            // failure (isError, transport/protocol error, timeout) the
+            // message lives in `error` and `output` is `null` — matching
+            // OpenAI's `MCPToolCall` schema (output/error are mutually
+            // exclusive) and the resume path in `resume.rs`.
+            let (status, output, error_text): (&str, Option<String>, Option<String>) =
+                match &outcome {
+                    Ok(Ok(result)) if !result.is_error => {
+                        let text = collapse_result_text(result);
+                        ("completed", Some(text), None)
+                    }
+                    Ok(Ok(result)) => {
+                        let text = collapse_result_text(result);
+                        let err = format!("MCP tool returned isError=true: {text}");
+                        ("failed", None, Some(err))
+                    }
+                    Ok(Err(e)) => ("failed", None, Some(e.to_string())),
+                    Err(_elapsed) => {
+                        let err =
+                            format!("MCP tool call timed out after {}s", call_timeout.as_secs());
+                        tracing::warn!(
+                            server_label = %binding_for_task.server_label,
+                            tool = %tool_name,
+                            timeout_secs = call_timeout.as_secs(),
+                            "MCP tools/call timed out; surfacing incomplete call"
+                        );
+                        // The timed-out request was abandoned mid-flight
+                        // without a protocol-level cancel, so the pooled
+                        // session is now suspect. Evict it: the next call
+                        // reconnects, and dropping the connection issues a
+                        // clean rmcp cancel. See `McpService::evict_endpoint`.
+                        service.evict_endpoint(
+                            &binding_for_task.server_url,
+                            binding_for_task.authorization.as_deref(),
+                            &binding_for_task.headers,
+                        );
+                        // `incomplete` is the `MCPToolCallStatus` for a call
+                        // that neither succeeded nor hard-failed but was cut
+                        // short — exactly a timeout.
+                        ("incomplete", None, Some(err))
+                    }
+                };
+
+            // MCP-specific terminal lifecycle event SDKs key on. Spec
+            // order: the lifecycle `completed`/`failed` precedes the
+            // terminal `output_item.done`. There is no `.incomplete`
+            // stream event in the spec, so a timeout rides the `.failed`
+            // lifecycle event while the item itself carries the precise
+            // `incomplete` status.
+            let lifecycle_event = if error_text.is_some() {
+                "response.mcp_call.failed"
+            } else {
+                "response.mcp_call.completed"
+            };
+            let _ = event_tx
+                .send(sse_mcp_lifecycle_event(lifecycle_event, &call_item_id))
+                .await;
+
+            // Terminal `output_item.done` with `output` / `error`
+            // inlined on the same `mcp_call` item — the spec has no
+            // separate `mcp_call_output` type.
+            if event_tx
+                .send(sse_output_item(
+                    "response.output_item.done",
+                    mcp_call_item(
+                        &call_item_id,
+                        &binding_for_task.server_label,
+                        &tool_name,
+                        &raw_args,
+                        status,
+                        output.as_deref(),
+                        error_text.as_deref(),
+                        approval_req_for_task.as_deref(),
+                    ),
+                ))
+                .await
+                .is_err()
+            {
+                tracing::debug!(
+                    server_label = %binding_for_task.server_label,
+                    tool = %tool_name,
+                    "MCP event consumer dropped before the terminal mcp_call item; \
+                     the call result is still recorded for the continuation"
+                );
+            }
+
+            let function_output_text = if let Some(err) = &error_text {
+                serde_json::json!({"error": err}).to_string()
+            } else {
+                output.unwrap_or_default()
+            };
+
+            let continuation = ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+                type_: crate::api_types::responses::FunctionCallOutputType::FunctionCallOutput,
+                id: None,
+                call_id: call_id.clone(),
+                output: function_output_text,
+                status: None,
+            });
+
+            let _ = result_tx.send(Ok(ToolCallResult {
+                call_id,
+                continuation_items: vec![continuation],
+            }));
+        });
+
+        Ok(ToolExecutionHandle {
+            events: Box::pin(futures_util::stream::unfold(
+                event_rx,
+                |mut rx| async move { rx.recv().await.map(|item| (item, rx)) },
+            )),
+            result: Box::pin(async move {
+                result_rx.await.map_err(|_| {
+                    ToolError::ExecutionFailed(
+                        "MCP executor task dropped before sending result".to_string(),
+                    )
+                })?
+            }),
+        })
+    }
+}
+
+#[async_trait]
+impl ServerExecutedTool for McpExecutor {
+    fn name(&self) -> &'static str {
+        "mcp"
+    }
+
+    fn is_enabled_for(&self, payload: &CreateResponsesPayload) -> bool {
+        // Enabled when the original payload has `mcp` tool entries.
+        // Once the rewrite has run, those entries become function tools
+        // — we still want to be enabled because the model will be
+        // calling the rewritten names. So we engage iff the constructor
+        // captured any bindings; the trait method's `payload` argument
+        // is the original, and the rewrite happens *after* registration.
+        let _ = payload;
+        self.has_bindings()
+    }
+
+    fn detect(&self, event: &[u8], _ctx: &ToolContext) -> Vec<DetectedToolCall> {
+        detect_in_chunk(event, &self.bindings)
+    }
+
+    /// Suppress the rewritten `function_call` plumbing from the
+    /// client-facing stream. Under `hadrian_hosted` the model drives
+    /// MCP via `mcp_<label>__<tool>` function tools, but the spec's
+    /// output only contains `mcp_call` / `mcp_list_tools` /
+    /// `mcp_approval_request` items — never the function calls. We emit
+    /// the `mcp_call` items ourselves (see [`Self::execute`] /
+    /// [`Self::prefix_events`]), so the underlying `function_call`
+    /// `output_item.added` / `.done` and `function_call_arguments.*`
+    /// events are dropped here (returned as empty bytes; the runner
+    /// skips empty events). Detection and the continuation payload run
+    /// off the *raw* upstream event, so suppressing the client copy
+    /// doesn't break the server-tool loop.
+    fn transform_event(&self, event: Bytes) -> Bytes {
+        // Only the MCP-rewritten function tools (`mcp_<label>__<tool>`)
+        // are ours to hide.
+        self.suppressor
+            .suppress(event, |name| parse_function_name(name).is_some())
+    }
+
+    fn prefix_events(&self) -> Vec<Bytes> {
+        // One `mcp_list_tools` item per requesting server, populated
+        // from the cache the preprocess rewrite just warmed up. Servers
+        // whose catalog already appears in the caller's input (via
+        // `previous_response_id`) are skipped — matches OpenAI's
+        // "don't re-emit when the item is in context" behavior.
+        let mut out = Vec::with_capacity(self.bindings.len() * 5);
+        for binding in &self.bindings {
+            if self.suppress_list_tools.contains(&binding.server_label) {
+                continue;
+            }
+            let item_id = next_item_id("mcpl");
+
+            // `output_item.added` placeholder — required by the spec
+            // before the body and `output_item.done` events.
+            let placeholder = serde_json::json!({
+                "type": "mcp_list_tools",
+                "id": item_id,
+                "server_label": binding.server_label,
+                "tools": [],
+                "error": null,
+            });
+            out.push(sse_output_item("response.output_item.added", placeholder));
+            out.push(sse_mcp_lifecycle_event(
+                "response.mcp_list_tools.in_progress",
+                &item_id,
+            ));
+
+            let catalog = self.service.cached_tools(
+                &binding.server_url,
+                binding.authorization.as_deref(),
+                &binding.headers,
+            );
+
+            match catalog {
+                Some(catalog) => {
+                    let tools_json: Vec<Value> = catalog
+                        .iter()
+                        .map(|t| {
+                            let mut obj = serde_json::json!({
+                                "name": t.name,
+                                "input_schema": t.input_schema,
+                            });
+                            if let Some(desc) = t.description.as_ref() {
+                                obj["description"] = Value::from(desc.as_str());
+                            }
+                            if let Some(ann) = t.annotations.as_ref() {
+                                obj["annotations"] = ann.clone();
+                            }
+                            obj
+                        })
+                        .collect();
+                    let item = serde_json::json!({
+                        "type": "mcp_list_tools",
+                        "id": item_id,
+                        "server_label": binding.server_label,
+                        "tools": tools_json,
+                        "error": null,
+                    });
+                    // Spec order: the lifecycle `completed` precedes the
+                    // terminal `output_item.done`.
+                    out.push(sse_mcp_lifecycle_event(
+                        "response.mcp_list_tools.completed",
+                        &item_id,
+                    ));
+                    out.push(sse_output_item("response.output_item.done", item));
+                }
+                None => {
+                    // Cache miss — surface as the spec-shaped failed
+                    // path with `error` inlined on the item. Prefer the
+                    // verbatim upstream `tools/list` error when one was
+                    // recorded; fall back to a generic message only when
+                    // the catalog merely aged out of cache between the
+                    // rewrite and stream start.
+                    let error_message = self
+                        .service
+                        .cached_tools_error(
+                            &binding.server_url,
+                            binding.authorization.as_deref(),
+                            &binding.headers,
+                        )
+                        .unwrap_or_else(|| "tools/list catalog unavailable".to_string());
+                    let item = serde_json::json!({
+                        "type": "mcp_list_tools",
+                        "id": item_id,
+                        "server_label": binding.server_label,
+                        "tools": [],
+                        "error": error_message,
+                    });
+                    out.push(sse_mcp_lifecycle_event(
+                        "response.mcp_list_tools.failed",
+                        &item_id,
+                    ));
+                    out.push(sse_output_item("response.output_item.done", item));
+                }
+            }
+        }
+
+        // Synthesize `mcp_call` items for any approvals the resume
+        // path resolved on this request. The spec requires the
+        // resumed response to carry an `mcp_call` linked to the
+        // original `mcp_approval_request` via `approval_request_id`,
+        // with `output` / `error` inlined. The model also gets the
+        // same payload as a `function_call_output` in its input (so
+        // it continues), but the `mcp_call` output item is what SDKs
+        // and the persisted response history key off.
+        for approval in &self.resumed_approvals {
+            let item_id = next_item_id("mcp");
+            // Args were serialized from a `Value` when the call was parked;
+            // a parse failure means the stashed/stored row is corrupt.
+            // Surface `null` args rather than fabricating, but log it.
+            let raw_args: Value = serde_json::from_str(&approval.arguments_json)
+                .unwrap_or_else(|e| {
+                    tracing::error!(
+                        approval_request_id = %approval.approval_request_id,
+                        server_label = %approval.server_label,
+                        tool = %approval.tool_name,
+                        error = %e,
+                        "Resumed MCP approval has unparseable arguments_json; emitting null arguments"
+                    );
+                    Value::Null
+                });
+            let status = if approval.error.is_some() {
+                "failed"
+            } else {
+                "completed"
+            };
+
+            out.push(sse_output_item(
+                "response.output_item.added",
+                mcp_call_item(
+                    &item_id,
+                    &approval.server_label,
+                    &approval.tool_name,
+                    &raw_args,
+                    // Match the live dispatch path: the args phase is done
+                    // and (here) the call already executed during resume,
+                    // so the initial item status is `calling`, not
+                    // `in_progress`.
+                    "calling",
+                    None,
+                    None,
+                    Some(&approval.approval_request_id),
+                ),
+            ));
+            out.push(sse_mcp_lifecycle_event(
+                "response.mcp_call.in_progress",
+                &item_id,
+            ));
+            // Spec order: lifecycle `completed`/`failed` precedes the
+            // terminal `output_item.done`.
+            let lifecycle = if approval.error.is_some() {
+                "response.mcp_call.failed"
+            } else {
+                "response.mcp_call.completed"
+            };
+            out.push(sse_mcp_lifecycle_event(lifecycle, &item_id));
+            out.push(sse_output_item(
+                "response.output_item.done",
+                mcp_call_item(
+                    &item_id,
+                    &approval.server_label,
+                    &approval.tool_name,
+                    &raw_args,
+                    status,
+                    approval.output.as_deref(),
+                    approval.error.as_deref(),
+                    Some(&approval.approval_request_id),
+                ),
+            ));
+        }
+
+        out
+    }
+
+    async fn execute(
+        &self,
+        call: DetectedToolCall,
+        _ctx: &ToolContext,
+    ) -> Result<ToolExecutionHandle, ToolError> {
+        let sanitized_label = call
+            .arguments
+            .get("__mcp_label")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string();
+        let tool_name = call
+            .arguments
+            .get("__mcp_tool")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string();
+        let raw_args = call
+            .arguments
+            .get("__mcp_args")
+            .cloned()
+            .unwrap_or(Value::Null);
+
+        let binding = self
+            .resolve_binding(&sanitized_label)
+            .cloned()
+            .ok_or_else(|| {
+                ToolError::InvalidCall(format!(
+                    "no MCP server binding for sanitized label '{sanitized_label}' \
+                     (function_call was probably stale across a config change)"
+                ))
+            })?;
+
+        // Approval gate. When the binding requires approval for this
+        // tool, park the call instead of running it. The caller must
+        // submit a matching `mcp_approval_response` on a follow-up
+        // request to resume.
+        let read_only_hint = self.read_only_hint_for(&binding, &tool_name);
+        if binding.requires_approval(&tool_name, read_only_hint) {
+            return self
+                .park_for_approval(&binding, &call.call_id, &tool_name, &raw_args)
+                .await;
+        }
+
+        self.dispatch_call(binding, call.call_id, tool_name, raw_args, None)
+            .await
+    }
+
+    fn apply_to_continuation(
+        &self,
+        payload: &mut CreateResponsesPayload,
+        results: &[ToolCallResult],
+        is_final_iteration: bool,
+    ) {
+        let outputs: Vec<ResponsesInputItem> = results
+            .iter()
+            .flat_map(|r| r.continuation_items.clone())
+            .collect();
+        if outputs.is_empty() && !is_final_iteration {
+            return;
+        }
+
+        if !outputs.is_empty() {
+            match payload.input {
+                Some(ResponsesInput::Items(ref mut items)) => items.extend(outputs),
+                Some(ResponsesInput::Text(ref text)) => {
+                    let text = text.clone();
+                    let mut items = vec![ResponsesInputItem::EasyMessage(
+                        crate::api_types::responses::EasyInputMessage {
+                            type_: None,
+                            role: crate::api_types::responses::EasyInputMessageRole::User,
+                            content: crate::api_types::responses::EasyInputMessageContent::Text(
+                                text,
+                            ),
+                        },
+                    )];
+                    items.extend(outputs);
+                    payload.input = Some(ResponsesInput::Items(items));
+                }
+                None => {
+                    payload.input = Some(ResponsesInput::Items(outputs));
+                }
+            }
+        }
+
+        // On the final iteration, strip every function tool that came
+        // from the MCP rewrite so the model has to produce a text
+        // response. Detected by the `mcp_` prefix on the function name.
+        if is_final_iteration && let Some(ref mut tools) = payload.tools {
+            tools.retain(|t| match t {
+                ResponsesToolDefinition::Function(f) => parse_function_name(&f.name).is_none(),
+                _ => true,
+            });
+            if tools.is_empty() {
+                payload.tools = None;
+            }
+        }
+    }
+}
+
+/// Collapse `McpCallResult` to the single string `mcp_call.output`
+/// requires. OpenAI's spec types `output` as a plain string and gives
+/// no guidance on non-text MCP content; we fall through in priority
+/// order so the model always sees *something* instead of an empty
+/// payload that would make it look like the call returned nothing:
+///
+/// 1. Concatenated text blocks (the common case).
+/// 2. JSON-encoded `structuredContent` (richer return shape).
+/// 3. JSON-encoded non-text blocks (image / audio / resource) — kept
+///    verbatim from the MCP server so the model at least sees the
+///    shape and can react ("the tool returned an image with this
+///    mime type and base64 data"). Better than silently dropping.
+/// 4. `"{}"` as a last resort.
+pub(super) fn collapse_result_text(result: &McpCallResult) -> String {
+    if !result.text.is_empty() {
+        return result.text.clone();
+    }
+    if let Some(structured) = result.structured_content.as_ref() {
+        return structured.to_string();
+    }
+    if !result.extra_content.is_empty() {
+        let blocks: Vec<Value> = result
+            .extra_content
+            .iter()
+            .map(|c| {
+                serde_json::json!({
+                    "type": c.kind,
+                    "data": c.value,
+                })
+            })
+            .collect();
+        return Value::Array(blocks).to_string();
+    }
+    "{}".to_string()
+}
+
+/// Run one tool call against the remote server. Wraps service errors
+/// in a friendly string for SSE surfacing.
+async fn run_call(
+    service: &McpService,
+    binding: &ServerBinding,
+    tool_name: &str,
+    arguments: Value,
+) -> Result<McpCallResult, super::McpClientError> {
+    service
+        .call_tool(
+            &binding.server_url,
+            binding.authorization.as_deref(),
+            &binding.headers,
+            tool_name,
+            arguments,
+        )
+        .await
+}
+
+/// Scan one SSE event for `response.output_item.done` carrying a
+/// `function_call` whose name matches the MCP rewrite. Returns a
+/// `DetectedToolCall` per match. The runner hands us one complete SSE
+/// event (terminated by a blank line) at a time via
+/// [`crate::streaming::sse_buffer::SseBuffer`].
+fn detect_in_chunk(chunk: &[u8], bindings: &[ServerBinding]) -> Vec<DetectedToolCall> {
+    let Some(data) = extract_sse_data(chunk) else {
+        return Vec::new();
+    };
+    let trimmed = data.trim();
+    if trimmed == "[DONE]" {
+        return Vec::new();
+    }
+    let Ok(json) = serde_json::from_str::<Value>(trimmed) else {
+        return Vec::new();
+    };
+    if json.get("type").and_then(|t| t.as_str()) != Some("response.output_item.done") {
+        return Vec::new();
+    }
+    let Some(item) = json.get("item") else {
+        return Vec::new();
+    };
+    if item.get("type").and_then(|t| t.as_str()) != Some("function_call") {
+        return Vec::new();
+    }
+    let Some(name) = item.get("name").and_then(|v| v.as_str()) else {
+        return Vec::new();
+    };
+    let Some((sanitized_label, tool_name)) = parse_function_name(name) else {
+        return Vec::new();
+    };
+    if !bindings
+        .iter()
+        .any(|b| b.sanitized_label == sanitized_label)
+    {
+        // Function name matches the prefix but no binding — could
+        // be a stale call from a prior turn after config changed.
+        // Don't emit; let the runner pass it through unchanged.
+        warn!(
+            tool = %name,
+            "MCP-shaped function call has no matching binding; ignoring"
+        );
+        return Vec::new();
+    }
+    let Some(call_id) = item
+        .get("call_id")
+        .or_else(|| item.get("id"))
+        .and_then(|v| v.as_str())
+    else {
+        // No `call_id`/`id` means we can't pair the continuation
+        // `function_call_output` back to this call. Fabricating a
+        // placeholder would let two malformed calls collide on the join
+        // key; skip instead and let the runner pass the event through.
+        warn!(
+            tool = %name,
+            "MCP-shaped function call missing both `call_id` and `id`; ignoring (cannot pair continuation)"
+        );
+        return Vec::new();
+    };
+    let call_id = call_id.to_string();
+    // Model emits `arguments` as a JSON-encoded string. Parse it
+    // so the executor can serve structured args to the MCP server.
+    let raw_args_str = item
+        .get("arguments")
+        .and_then(|v| v.as_str())
+        .unwrap_or("{}");
+    let parsed_args: Value = serde_json::from_str(raw_args_str).unwrap_or(Value::Null);
+
+    vec![DetectedToolCall {
+        tool_name: "mcp",
+        call_id,
+        arguments: serde_json::json!({
+            "__mcp_label": sanitized_label,
+            "__mcp_tool": tool_name,
+            "__mcp_args": parsed_args,
+        }),
+    }]
+}
+
+/// Concatenate every `data:` field on an SSE event into a single
+/// string, joined with `\n`. Per the [HTML SSE spec][1], one event can
+/// carry multiple `data:` lines and the dispatched payload is their
+/// `\n`-joined concatenation — line-by-line JSON parsing (which the
+/// previous implementation did) drops valid events where a provider
+/// chose to wrap a long JSON across multiple `data:` lines.
+///
+/// Returns `None` if the event has no `data:` fields, or if the bytes
+/// aren't UTF-8.
+///
+/// [1]: https://html.spec.whatwg.org/multipage/server-sent-events.html#dispatchMessage
+fn extract_sse_data(event: &[u8]) -> Option<String> {
+    let text = std::str::from_utf8(event).ok()?;
+    let mut parts: Vec<&str> = Vec::new();
+    for line in text.split('\n') {
+        // CRLF framing: strip the trailing '\r' from the line. Bare LF
+        // framing leaves the line untouched.
+        let line = line.strip_suffix('\r').unwrap_or(line);
+        // Empty line is the event terminator (the SseBuffer already
+        // delimited on this, but a final blank line can still appear
+        // inside the slice). Comments start with `:`. Skip both.
+        if line.is_empty() || line.starts_with(':') {
+            continue;
+        }
+        // Other field types (`event:`, `id:`, `retry:`) are ignored —
+        // we only consume `data:` payloads.
+        let Some(rest) = line.strip_prefix("data:") else {
+            continue;
+        };
+        // Per spec, a single leading space after the colon is stripped.
+        // Any subsequent leading whitespace is preserved.
+        let value = rest.strip_prefix(' ').unwrap_or(rest);
+        parts.push(value);
+    }
+    if parts.is_empty() {
+        return None;
+    }
+    Some(parts.join("\n"))
+}
+
+/// `output_index` / `sequence_number` are emitted as `0` placeholders:
+/// the pipeline always runs the `StreamRewriter`, which stamps one
+/// monotonic `sequence_number` across the whole stream and remaps
+/// `output_index` to a stable per-item value (see
+/// `server_tools::runner::StreamRewriter::rewrite`). Computing them here
+/// would be dead work — the rewriter overwrites both. The `output_index`
+/// key must still be present, since the rewriter only remaps events that
+/// already carry it.
+fn sse_output_item(event_type: &str, item: Value) -> Bytes {
+    let payload = serde_json::json!({
+        "type": event_type,
+        "output_index": 0,
+        "sequence_number": 0,
+        "item": item,
+    });
+    let s = serde_json::to_string(&payload).unwrap_or_default();
+    Bytes::from(format!("data: {}\n\n", s))
+}
+
+/// `response.mcp_call.in_progress` / `.completed` / `.failed`. No
+/// payload other than the locators — SDKs use this to fire MCP-specific
+/// state transitions; the item content lives on the matching
+/// `output_item.added` / `.done`.
+fn sse_mcp_lifecycle_event(event_type: &str, item_id: &str) -> Bytes {
+    // `output_index` / `sequence_number` are `0` placeholders the
+    // `StreamRewriter` overwrites — see `sse_output_item`.
+    let payload = serde_json::json!({
+        "type": event_type,
+        "output_index": 0,
+        "sequence_number": 0,
+        "item_id": item_id,
+    });
+    let s = serde_json::to_string(&payload).unwrap_or_default();
+    Bytes::from(format!("data: {}\n\n", s))
+}
+
+/// `response.mcp_call_arguments.delta` / `.done`. Carries the
+/// model-supplied arguments JSON. Under hadrian_hosted there's no
+/// incremental source, so the `.delta` is a single chunk holding the
+/// full string and `.done` echoes it.
+fn sse_mcp_arguments_event(event_type: &str, item_id: &str, arguments: Option<&str>) -> Bytes {
+    let key = if event_type.ends_with(".delta") {
+        "delta"
+    } else {
+        "arguments"
+    };
+    // `output_index` / `sequence_number` are `0` placeholders the
+    // `StreamRewriter` overwrites — see `sse_output_item`.
+    let payload = serde_json::json!({
+        "type": event_type,
+        "output_index": 0,
+        "sequence_number": 0,
+        "item_id": item_id,
+        key: arguments.unwrap_or(""),
+    });
+    let s = serde_json::to_string(&payload).unwrap_or_default();
+    Bytes::from(format!("data: {}\n\n", s))
+}
+
+/// Build a fully-shaped `mcp_call` item. `output` / `error` live on the
+/// item itself per OpenAI's `MCPToolCall` schema — there is no separate
+/// `mcp_call_output` type. `approval_request_id`, when set, links back
+/// to the `mcp_approval_request` that gated this call.
+#[allow(clippy::too_many_arguments)]
+fn mcp_call_item(
+    item_id: &str,
+    server_label: &str,
+    tool_name: &str,
+    arguments: &Value,
+    status: &str,
+    output: Option<&str>,
+    error: Option<&str>,
+    approval_request_id: Option<&str>,
+) -> Value {
+    // OpenAI's `MCPToolCall` always carries `output`, `error`, and
+    // `approval_request_id` keys — `null` when unset, not omitted — so
+    // SDKs can read them unconditionally. Mirror that exactly.
+    serde_json::json!({
+        "type": "mcp_call",
+        "id": item_id,
+        "server_label": server_label,
+        "name": tool_name,
+        "arguments": serde_json::to_string(arguments).unwrap_or_else(|_| "{}".to_string()),
+        "status": status,
+        "output": output.map(Value::from).unwrap_or(Value::Null),
+        "error": error.map(Value::from).unwrap_or(Value::Null),
+        "approval_request_id": approval_request_id.map(Value::from).unwrap_or(Value::Null),
+    })
+}
+
+/// Drain any approvals the resume path stashed for this org on this
+/// request. The join key is the `call_id` of every `function_call_output`
+/// in `payload.input` — those are the items the resume just wrote, and
+/// each has a matching stashed `ResolvedMcpApproval`.
+///
+/// Returns an empty Vec when `org_id` is unknown (no auth scope) or
+/// when the resume path didn't stash anything (the common case — most
+/// requests aren't resumes).
+fn drain_resumed_approvals(
+    service: &McpService,
+    org_id: Option<uuid::Uuid>,
+    payload: &CreateResponsesPayload,
+) -> Vec<super::ResolvedMcpApproval> {
+    let Some(org_id) = org_id else {
+        return Vec::new();
+    };
+    let Some(ResponsesInput::Items(items)) = payload.input.as_ref() else {
+        return Vec::new();
+    };
+    let mut out = Vec::new();
+    for item in items {
+        if let ResponsesInputItem::FunctionCallOutput(fco) = item
+            && let Some(approval) = service.take_resolved_approval(org_id, &fco.call_id)
+        {
+            out.push(approval);
+        }
+    }
+    out
+}
+
+/// Walk `payload.input` for `mcp_list_tools` items, returning the set
+/// of `server_label`s already present in the caller's context. Used
+/// to suppress re-emission of the catalog on follow-up turns — matches
+/// OpenAI's "don't refetch when the item is already in context" rule.
+fn collect_inlined_list_tools_labels(
+    payload: &CreateResponsesPayload,
+) -> std::collections::HashSet<String> {
+    let mut out = std::collections::HashSet::new();
+    let Some(input) = payload.input.as_ref() else {
+        return out;
+    };
+    let ResponsesInput::Items(items) = input else {
+        return out;
+    };
+    for item in items {
+        if let ResponsesInputItem::McpListTools(it) = item {
+            out.insert(it.server_label.clone());
+        }
+    }
+    out
+}
+
+/// Synthesize a globally-unique output-item id (`mcp_`, `mcpl_`, …),
+/// matching OpenAI's `<prefix>_<random hex>` scheme. A UUID rather than
+/// a per-response counter so ids don't collide across responses when
+/// `store=true` — and so we stay consistent with the rest of the
+/// pipeline, which also uses `Uuid::new_v4().simple()` for synthesized
+/// ids.
+fn next_item_id(prefix: &str) -> String {
+    format!("{prefix}_{}", uuid::Uuid::new_v4().simple())
+}
+
+/// Build the spec-shaped `mcp_approval_request` item. The
+/// `approval_request_id` (item `id`) is what the caller echoes back
+/// on the matching `mcp_approval_response` to resume.
+fn mcp_approval_request_item(
+    approval_id: &str,
+    server_label: &str,
+    tool_name: &str,
+    arguments_json: &str,
+) -> Value {
+    serde_json::json!({
+        "type": "mcp_approval_request",
+        "id": approval_id,
+        "server_label": server_label,
+        "name": tool_name,
+        "arguments": arguments_json,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api_types::responses::McpToolType;
+
+    fn mcp_with(label: &str, url: &str) -> McpTool {
+        McpTool {
+            type_: McpToolType::Mcp,
+            server_label: label.to_string(),
+            server_url: Some(url.to_string()),
+            connector_id: None,
+            server_description: None,
+            authorization: None,
+            headers: None,
+            require_approval: None,
+            allowed_tools: None,
+            defer_loading: None,
+            defer_loading_passthrough: None,
+            call_timeout_secs: None,
+        }
+    }
+
+    #[test]
+    fn server_binding_captures_sanitized_label() {
+        let b = ServerBinding::from_mcp(
+            &mcp_with("My Co/Linear", "https://x"),
+            DEFAULT_CALL_TIMEOUT_SECS,
+        )
+        .unwrap();
+        assert_eq!(b.server_label, "My Co/Linear");
+        assert_eq!(b.sanitized_label, "My_Co_Linear");
+    }
+
+    #[test]
+    fn server_binding_resolves_call_timeout() {
+        // No per-tool override → deployment default applies.
+        let b = ServerBinding::from_mcp(&mcp_with("atlassian", "https://x"), 42).unwrap();
+        assert_eq!(b.call_timeout, std::time::Duration::from_secs(42));
+
+        // Per-tool `call_timeout_secs` extension wins over the default.
+        let mut tool = mcp_with("atlassian", "https://x");
+        tool.call_timeout_secs = Some(7);
+        let b = ServerBinding::from_mcp(&tool, 42).unwrap();
+        assert_eq!(b.call_timeout, std::time::Duration::from_secs(7));
+    }
+
+    #[test]
+    fn detect_skips_non_mcp_function_calls() {
+        let bindings = vec![
+            ServerBinding::from_mcp(
+                &mcp_with("atlassian", "https://x"),
+                DEFAULT_CALL_TIMEOUT_SECS,
+            )
+            .unwrap(),
+        ];
+        let chunk = br#"data: {"type":"response.output_item.done","item":{"type":"function_call","name":"shell","arguments":"{}","call_id":"c1"}}"#;
+        let calls = detect_in_chunk(chunk, &bindings);
+        assert!(calls.is_empty());
+    }
+
+    #[test]
+    fn detect_picks_up_mcp_function_calls() {
+        let bindings = vec![
+            ServerBinding::from_mcp(
+                &mcp_with("atlassian", "https://x"),
+                DEFAULT_CALL_TIMEOUT_SECS,
+            )
+            .unwrap(),
+        ];
+        let chunk = br#"data: {"type":"response.output_item.done","item":{"type":"function_call","name":"mcp_atlassian__jira_search","arguments":"{\"query\":\"bugs\"}","call_id":"c1"}}"#;
+        let calls = detect_in_chunk(chunk, &bindings);
+        assert_eq!(calls.len(), 1);
+        let c = &calls[0];
+        assert_eq!(c.tool_name, "mcp");
+        assert_eq!(c.call_id, "c1");
+        assert_eq!(c.arguments.get("__mcp_label").unwrap(), "atlassian");
+        assert_eq!(c.arguments.get("__mcp_tool").unwrap(), "jira_search");
+        assert_eq!(
+            c.arguments.get("__mcp_args").unwrap().get("query").unwrap(),
+            "bugs"
+        );
+    }
+
+    #[test]
+    fn detect_ignores_unknown_label() {
+        let bindings = vec![
+            ServerBinding::from_mcp(
+                &mcp_with("atlassian", "https://x"),
+                DEFAULT_CALL_TIMEOUT_SECS,
+            )
+            .unwrap(),
+        ];
+        let chunk = br#"data: {"type":"response.output_item.done","item":{"type":"function_call","name":"mcp_notion__something","arguments":"{}","call_id":"c1"}}"#;
+        let calls = detect_in_chunk(chunk, &bindings);
+        assert!(calls.is_empty());
+    }
+
+    #[test]
+    fn detect_handles_multiline_data_fields() {
+        // Per the SSE spec, a single event can carry the JSON payload
+        // across multiple `data:` lines; the actual data is the
+        // `\n`-joined concatenation. The previous line-by-line parser
+        // would have dropped this event.
+        let bindings = vec![
+            ServerBinding::from_mcp(
+                &mcp_with("atlassian", "https://x"),
+                DEFAULT_CALL_TIMEOUT_SECS,
+            )
+            .unwrap(),
+        ];
+        let chunk = b"data: {\"type\":\"response.output_item.done\",\"item\":{\n\
+                      data: \"type\":\"function_call\",\n\
+                      data: \"name\":\"mcp_atlassian__jira_search\",\n\
+                      data: \"arguments\":\"{\\\"q\\\":\\\"bugs\\\"}\",\n\
+                      data: \"call_id\":\"c1\"}}\n\n";
+        let calls = detect_in_chunk(chunk, &bindings);
+        assert_eq!(calls.len(), 1, "multi-line data: should reconstruct");
+        assert_eq!(calls[0].call_id, "c1");
+        assert_eq!(calls[0].arguments.get("__mcp_tool").unwrap(), "jira_search");
+    }
+
+    #[test]
+    fn detect_handles_crlf_framing() {
+        // Some upstream HTTP stacks emit `\r\n` line terminators. The
+        // parser must strip the trailing `\r` before matching `data:`.
+        let bindings = vec![
+            ServerBinding::from_mcp(
+                &mcp_with("atlassian", "https://x"),
+                DEFAULT_CALL_TIMEOUT_SECS,
+            )
+            .unwrap(),
+        ];
+        let chunk = b"data: {\"type\":\"response.output_item.done\",\"item\":{\"type\":\"function_call\",\"name\":\"mcp_atlassian__jira_search\",\"arguments\":\"{}\",\"call_id\":\"c1\"}}\r\n\r\n";
+        let calls = detect_in_chunk(chunk, &bindings);
+        assert_eq!(calls.len(), 1);
+        assert_eq!(calls[0].call_id, "c1");
+    }
+
+    #[test]
+    fn detect_skips_comment_and_other_fields() {
+        // `:` comments and non-`data:` fields (`event:`, `id:`) must
+        // be ignored — only `data:` contributes to the payload.
+        let bindings = vec![
+            ServerBinding::from_mcp(
+                &mcp_with("atlassian", "https://x"),
+                DEFAULT_CALL_TIMEOUT_SECS,
+            )
+            .unwrap(),
+        ];
+        let chunk = b": keepalive\n\
+                      event: response.output_item.done\n\
+                      id: 42\n\
+                      data: {\"type\":\"response.output_item.done\",\"item\":{\"type\":\"function_call\",\"name\":\"mcp_atlassian__jira_search\",\"arguments\":\"{}\",\"call_id\":\"c1\"}}\n\n";
+        let calls = detect_in_chunk(chunk, &bindings);
+        assert_eq!(calls.len(), 1);
+    }
+
+    #[test]
+    fn detect_returns_empty_on_done_sentinel() {
+        let bindings = vec![
+            ServerBinding::from_mcp(
+                &mcp_with("atlassian", "https://x"),
+                DEFAULT_CALL_TIMEOUT_SECS,
+            )
+            .unwrap(),
+        ];
+        let chunk = b"data: [DONE]\n\n";
+        let calls = detect_in_chunk(chunk, &bindings);
+        assert!(calls.is_empty());
+    }
+
+    #[test]
+    fn extract_sse_data_joins_with_newline() {
+        // Verify the join character matches the SSE spec — concatenated
+        // with `\n`, not `\r\n` and not empty string.
+        let chunk = b"data: line1\ndata: line2\ndata: line3\n\n";
+        let joined = extract_sse_data(chunk).unwrap();
+        assert_eq!(joined, "line1\nline2\nline3");
+    }
+
+    #[test]
+    fn extract_sse_data_preserves_subsequent_spaces() {
+        // Per spec, only the *first* leading space after `data:` is
+        // stripped — additional whitespace is part of the payload.
+        let chunk = b"data:  with-two-leading-spaces\n\n";
+        let joined = extract_sse_data(chunk).unwrap();
+        assert_eq!(joined, " with-two-leading-spaces");
+    }
+
+    #[test]
+    fn mcp_call_item_inlines_output_and_error() {
+        let v = mcp_call_item(
+            "mcp_1",
+            "atlassian",
+            "jira_search",
+            &serde_json::json!({"q": "bugs"}),
+            "completed",
+            Some("{\"hits\":2}"),
+            None,
+            Some("mcpr_x"),
+        );
+        assert_eq!(v["type"], "mcp_call");
+        assert_eq!(v["server_label"], "atlassian");
+        let args = v["arguments"].as_str().unwrap();
+        let parsed: serde_json::Value = serde_json::from_str(args).unwrap();
+        assert_eq!(parsed["q"], "bugs");
+        assert_eq!(v["output"], "{\"hits\":2}");
+        assert_eq!(v["approval_request_id"], "mcpr_x");
+        // `error` is always present per OpenAI's schema — `null`, not omitted.
+        assert_eq!(v["error"], Value::Null);
+    }
+
+    #[test]
+    fn binding_requires_approval_handles_every_shape() {
+        use crate::api_types::responses::{
+            McpApprovalFilter, McpApprovalMode, McpRequireApproval, McpToolFilter,
+        };
+
+        let mut tool = mcp_with("atlassian", "https://x");
+
+        // No policy → spec default is `"always"`, so gate.
+        tool.require_approval = None;
+        let b = ServerBinding::from_mcp(&tool, DEFAULT_CALL_TIMEOUT_SECS).unwrap();
+        assert!(b.requires_approval("jira_create", None));
+
+        // Mode::Never → never.
+        tool.require_approval = Some(McpRequireApproval::Mode(McpApprovalMode::Never));
+        let b = ServerBinding::from_mcp(&tool, DEFAULT_CALL_TIMEOUT_SECS).unwrap();
+        assert!(!b.requires_approval("jira_create", None));
+
+        // Mode::Always → every tool.
+        tool.require_approval = Some(McpRequireApproval::Mode(McpApprovalMode::Always));
+        let b = ServerBinding::from_mcp(&tool, DEFAULT_CALL_TIMEOUT_SECS).unwrap();
+        assert!(b.requires_approval("jira_search", None));
+        assert!(b.requires_approval("jira_create", None));
+
+        // Filter with `never` exempts a subset; everything else stays gated.
+        tool.require_approval = Some(McpRequireApproval::Filter(McpApprovalFilter {
+            always: None,
+            never: Some(McpToolFilter {
+                tool_names: Some(vec!["jira_search".into()]),
+                read_only: None,
+            }),
+        }));
+        let b = ServerBinding::from_mcp(&tool, DEFAULT_CALL_TIMEOUT_SECS).unwrap();
+        assert!(!b.requires_approval("jira_search", None));
+        assert!(b.requires_approval("jira_create", None));
+
+        // `never` with `read_only: true` exempts tools whose readOnlyHint
+        // is explicitly true; mutating tools still gate.
+        tool.require_approval = Some(McpRequireApproval::Filter(McpApprovalFilter {
+            always: None,
+            never: Some(McpToolFilter {
+                tool_names: None,
+                read_only: Some(true),
+            }),
+        }));
+        let b = ServerBinding::from_mcp(&tool, DEFAULT_CALL_TIMEOUT_SECS).unwrap();
+        assert!(!b.requires_approval("jira_search", Some(true)));
+        assert!(b.requires_approval("jira_create", Some(false)));
+        // A tool with NO readOnlyHint annotation must not match a
+        // `read_only: true` filter — absence is not `false`, so it gates.
+        assert!(b.requires_approval("jira_unknown", None));
+
+        // `always` explicitly gates a subset and exempts the rest via
+        // implicit default — actually the spec default for the filter
+        // object is "gate", so non-listed tools still gate.
+        tool.require_approval = Some(McpRequireApproval::Filter(McpApprovalFilter {
+            always: Some(McpToolFilter {
+                tool_names: Some(vec!["jira_create".into()]),
+                read_only: None,
+            }),
+            never: None,
+        }));
+        let b = ServerBinding::from_mcp(&tool, DEFAULT_CALL_TIMEOUT_SECS).unwrap();
+        assert!(b.requires_approval("jira_create", None));
+        // Non-listed tools fall through to the default — gate.
+        assert!(b.requires_approval("jira_search", None));
+    }
+
+    #[test]
+    fn collapse_result_text_prefers_text_then_structured_then_extras() {
+        use super::super::McpCallContent;
+
+        // Text wins.
+        let r = McpCallResult {
+            is_error: false,
+            text: "hello".into(),
+            structured_content: Some(serde_json::json!({"k": "v"})),
+            extra_content: vec![],
+        };
+        assert_eq!(collapse_result_text(&r), "hello");
+
+        // No text → structured.
+        let r = McpCallResult {
+            is_error: false,
+            text: String::new(),
+            structured_content: Some(serde_json::json!({"k": "v"})),
+            extra_content: vec![],
+        };
+        assert_eq!(collapse_result_text(&r), r#"{"k":"v"}"#);
+
+        // No text + no structured → JSON-encode extras (image/audio/resource)
+        // so the model sees *something* rather than an empty payload.
+        let r = McpCallResult {
+            is_error: false,
+            text: String::new(),
+            structured_content: None,
+            extra_content: vec![McpCallContent {
+                kind: "image".into(),
+                value: serde_json::json!({"mimeType": "image/png", "data": "..."}),
+            }],
+        };
+        let s = collapse_result_text(&r);
+        assert!(s.contains("\"image\""), "got: {s}");
+        assert!(s.contains("image/png"), "got: {s}");
+
+        // Nothing at all → "{}" placeholder.
+        let r = McpCallResult {
+            is_error: false,
+            text: String::new(),
+            structured_content: None,
+            extra_content: vec![],
+        };
+        assert_eq!(collapse_result_text(&r), "{}");
+    }
+
+    #[test]
+    fn drain_resumed_approvals_matches_function_call_outputs_in_input() {
+        use crate::api_types::responses::{
+            FunctionCallOutput, FunctionCallOutputType, ResponsesInput, ResponsesInputItem,
+        };
+
+        let svc = McpService::new();
+        let org_id = uuid::Uuid::new_v4();
+        let other_org = uuid::Uuid::new_v4();
+
+        // Stash two approvals: one matching, one for a call_id not in payload.
+        svc.stash_resolved_approval(
+            org_id,
+            super::super::ResolvedMcpApproval {
+                call_id: "call_match".into(),
+                approval_request_id: "mcpr_1".into(),
+                server_label: "atlassian".into(),
+                tool_name: "jira_search".into(),
+                arguments_json: r#"{"q":"x"}"#.into(),
+                output: Some("ok".into()),
+                error: None,
+            },
+        );
+        svc.stash_resolved_approval(
+            org_id,
+            super::super::ResolvedMcpApproval {
+                call_id: "call_stale".into(),
+                approval_request_id: "mcpr_2".into(),
+                server_label: "atlassian".into(),
+                tool_name: "jira_search".into(),
+                arguments_json: "{}".into(),
+                output: None,
+                error: Some("err".into()),
+            },
+        );
+        // Different org — must not leak across tenants.
+        svc.stash_resolved_approval(
+            other_org,
+            super::super::ResolvedMcpApproval {
+                call_id: "call_match".into(),
+                approval_request_id: "mcpr_3".into(),
+                server_label: "atlassian".into(),
+                tool_name: "jira_search".into(),
+                arguments_json: "{}".into(),
+                output: Some("other-org".into()),
+                error: None,
+            },
+        );
+
+        let payload: CreateResponsesPayload =
+            serde_json::from_value(serde_json::json!({})).unwrap();
+        let mut payload = payload;
+        payload.input = Some(ResponsesInput::Items(vec![
+            ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+                type_: FunctionCallOutputType::FunctionCallOutput,
+                id: None,
+                call_id: "call_match".into(),
+                output: "ok".into(),
+                status: None,
+            }),
+            ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+                type_: FunctionCallOutputType::FunctionCallOutput,
+                id: None,
+                call_id: "call_no_match".into(),
+                output: "nope".into(),
+                status: None,
+            }),
+        ]));
+
+        let drained = super::drain_resumed_approvals(&svc, Some(org_id), &payload);
+        assert_eq!(drained.len(), 1);
+        assert_eq!(drained[0].call_id, "call_match");
+        assert_eq!(drained[0].approval_request_id, "mcpr_1");
+
+        // Stash for `call_match` was consumed (one-shot) and other_org's
+        // entry is untouched.
+        assert!(svc.take_resolved_approval(org_id, "call_match").is_none());
+        assert!(svc.take_resolved_approval(org_id, "call_stale").is_some());
+        assert!(
+            svc.take_resolved_approval(other_org, "call_match")
+                .is_some()
+        );
+    }
+
+    #[test]
+    fn approval_request_item_has_expected_shape() {
+        let item = mcp_approval_request_item(
+            "mcpr_abc",
+            "atlassian",
+            "jira_create",
+            r#"{"summary":"bug"}"#,
+        );
+        assert_eq!(item["type"], "mcp_approval_request");
+        assert_eq!(item["id"], "mcpr_abc");
+        assert_eq!(item["server_label"], "atlassian");
+        assert_eq!(item["name"], "jira_create");
+        assert_eq!(item["arguments"], r#"{"summary":"bug"}"#);
+    }
+
+    #[tokio::test]
+    async fn park_for_approval_fails_closed_without_persistence() {
+        use futures_util::StreamExt;
+
+        use crate::api_types::responses::{McpApprovalMode, McpRequireApproval};
+
+        // Build an executor with no persistence: no DB on the service,
+        // no response_id, no org_id. require_approval = "always" forces
+        // the gate to engage. The fail-closed path should produce a
+        // synthesized failed mcp_call rather than running the call.
+        let mut tool = mcp_with("atlassian", "https://x");
+        tool.require_approval = Some(McpRequireApproval::Mode(McpApprovalMode::Always));
+        let payload: CreateResponsesPayload = serde_json::from_value(serde_json::json!({
+            "tools": [serde_json::to_value(tool).unwrap()],
+        }))
+        .unwrap();
+
+        let service = McpService::new();
+        let executor =
+            McpExecutor::with_persistence(service, &payload, None, None, DEFAULT_CALL_TIMEOUT_SECS);
+
+        let call = DetectedToolCall {
+            tool_name: "mcp",
+            call_id: "c1".into(),
+            arguments: serde_json::json!({
+                "__mcp_label": "atlassian",
+                "__mcp_tool": "jira_create",
+                "__mcp_args": {"summary": "bug"},
+            }),
+        };
+        let ctx = ToolContext {
+            original_payload: payload,
+        };
+        let handle = executor.execute(call, &ctx).await.expect("handle returned");
+
+        // Drain events; expect a failed mcp_call lifecycle.
+        let mut events = handle.events;
+        let mut payloads: Vec<serde_json::Value> = Vec::new();
+        let mut lifecycle_types: Vec<String> = Vec::new();
+        while let Some(bytes) = events.next().await {
+            let text = std::str::from_utf8(&bytes).unwrap();
+            for line in text.lines() {
+                if let Some(rest) = line.strip_prefix("data:") {
+                    let v: serde_json::Value = serde_json::from_str(rest.trim()).unwrap();
+                    if let Some(t) = v.get("type").and_then(|t| t.as_str()) {
+                        if t.starts_with("response.mcp_call.") {
+                            lifecycle_types.push(t.to_string());
+                        }
+                        if t == "response.output_item.done" {
+                            payloads.push(v["item"].clone());
+                        }
+                    }
+                }
+            }
+        }
+
+        // The lifecycle ends in `failed`, not `completed`.
+        assert!(
+            lifecycle_types
+                .iter()
+                .any(|t| t == "response.mcp_call.failed"),
+            "expected response.mcp_call.failed lifecycle, got {:?}",
+            lifecycle_types
+        );
+        // The terminal item has status=failed and a non-empty error
+        // mentioning the gate.
+        let terminal = payloads.last().expect("a terminal item was emitted");
+        assert_eq!(terminal["status"], "failed");
+        let err = terminal["error"].as_str().expect("error field set");
+        assert!(
+            err.contains("require_approval"),
+            "expected the error to mention the gate, got: {err}"
+        );
+
+        // The continuation function_call_output also surfaces the error
+        // so the model sees it on its next turn.
+        let result = handle.result.await.expect("result resolves");
+        assert_eq!(result.call_id, "c1");
+        assert_eq!(result.continuation_items.len(), 1);
+        let cont = &result.continuation_items[0];
+        if let ResponsesInputItem::FunctionCallOutput(fco) = cont {
+            assert_eq!(fco.call_id, "c1");
+            let parsed: serde_json::Value = serde_json::from_str(&fco.output).unwrap();
+            assert!(
+                parsed.get("error").is_some(),
+                "continuation should carry an error field"
+            );
+        } else {
+            panic!("expected FunctionCallOutput continuation");
+        }
+    }
+
+    fn executor() -> McpExecutor {
+        let payload: CreateResponsesPayload = serde_json::from_value(serde_json::json!({
+            "tools": [{"type":"mcp","server_label":"atlassian","server_url":"https://x"}]
+        }))
+        .unwrap();
+        McpExecutor::new(McpService::new(), &payload)
+    }
+
+    #[test]
+    fn transform_suppresses_mcp_function_call_items() {
+        use crate::services::server_tools::ServerExecutedTool;
+        let exec = executor();
+        // The rewritten function_call must not leak to the client — the
+        // executor emits the spec-shaped `mcp_call` itself.
+        let added = Bytes::from(
+            r#"data: {"type":"response.output_item.added","item":{"type":"function_call","id":"fc_1","name":"mcp_atlassian__jira_search","arguments":""}}"#.to_string() + "\n\n",
+        );
+        assert!(exec.transform_event(added).is_empty());
+
+        // Argument-streaming events for that item id are suppressed too.
+        let delta = Bytes::from(
+            r#"data: {"type":"response.function_call_arguments.delta","item_id":"fc_1","delta":"{"}"#.to_string() + "\n\n",
+        );
+        assert!(exec.transform_event(delta).is_empty());
+
+        let done = Bytes::from(
+            r#"data: {"type":"response.output_item.done","item":{"type":"function_call","id":"fc_1","name":"mcp_atlassian__jira_search","arguments":"{}"}}"#.to_string() + "\n\n",
+        );
+        assert!(exec.transform_event(done).is_empty());
+    }
+
+    #[test]
+    fn transform_passes_through_non_mcp_and_synthesized_items() {
+        use crate::services::server_tools::ServerExecutedTool;
+        let exec = executor();
+        // A regular (non-MCP) function call is left alone.
+        let other = Bytes::from(
+            r#"data: {"type":"response.output_item.added","item":{"type":"function_call","id":"fc_2","name":"get_weather","arguments":""}}"#.to_string() + "\n\n",
+        );
+        assert_eq!(exec.transform_event(other.clone()), other);
+
+        // The executor's own mcp_call item must pass through untouched.
+        let mcp_call = Bytes::from(
+            r#"data: {"type":"response.output_item.done","item":{"type":"mcp_call","id":"mcp_1","name":"t","arguments":"{}","status":"completed"}}"#.to_string() + "\n\n",
+        );
+        assert_eq!(exec.transform_event(mcp_call.clone()), mcp_call);
+
+        // Arg events for an untracked item id pass through.
+        let delta = Bytes::from(
+            r#"data: {"type":"response.function_call_arguments.delta","item_id":"fc_2","delta":"{"}"#.to_string() + "\n\n",
+        );
+        assert_eq!(exec.transform_event(delta.clone()), delta);
+    }
+}
diff --git a/src/services/mcp/mod.rs b/src/services/mcp/mod.rs
new file mode 100644
index 0000000..a5f2223
--- /dev/null
+++ b/src/services/mcp/mod.rs
@@ -0,0 +1,39 @@
+//! Hadrian's hosted MCP (Model Context Protocol) integration.
+//!
+//! The `mcp` tool on a `/v1/responses` request can run in two modes:
+//!
+//! - `passthrough_openai` — the tool entry is forwarded verbatim to
+//!   OpenAI/Azure, which runs the MCP client loop. Hadrian does no
+//!   MCP-protocol work; see
+//!   [`services::mcp_tool`](crate::services::mcp_tool).
+//! - `hadrian_hosted` — this module. Hadrian opens a Streamable HTTP
+//!   connection to the remote MCP server, lists the advertised tools,
+//!   and rewrites the `mcp` tool into N per-tool function tools so any
+//!   provider can drive the loop.
+//!
+//! Implementation is layered on top of the official [`rmcp`] crate —
+//! it owns the transport, JSON-RPC envelope, and `Mcp-Session-Id`
+//! propagation. This module owns only the Hadrian-specific glue: the
+//! client pool, the function-tool rewrite, the `ServerExecutedTool`
+//! executor, and the approval gate.
+//!
+//! Wired in when the `mcp` cargo feature is enabled.
+
+#![cfg(feature = "mcp")]
+#![cfg(not(target_arch = "wasm32"))]
+
+pub mod client;
+pub mod executor;
+pub mod preprocess;
+pub mod resume;
+pub mod service;
+pub mod tool_search;
+
+pub use client::{McpCallContent, McpCallResult, McpClient, McpClientError, McpToolMeta};
+pub use executor::McpExecutor;
+pub use preprocess::{
+    McpRewriteError, parse_function_name, rewrite_mcp_tools, synthesize_function_name,
+};
+pub use resume::{McpResumeError, resume_mcp_approvals};
+pub use service::{McpEndpointKey, McpService, ResolvedMcpApproval};
+pub use tool_search::{TOOL_SEARCH_FUNCTION_NAME, ToolSearchExecutor};
diff --git a/src/services/mcp/preprocess.rs b/src/services/mcp/preprocess.rs
new file mode 100644
index 0000000..6d3b0f5
--- /dev/null
+++ b/src/services/mcp/preprocess.rs
@@ -0,0 +1,1480 @@
+//! Function-tool rewrite for `hadrian_hosted` mode.
+//!
+//! When the operator picks `[features.mcp].mode = "hadrian_hosted"`,
+//! Hadrian runs the MCP client loop itself. For *every* provider —
+//! OpenAI, Azure, Anthropic, Bedrock, Vertex, Test — we rewrite the
+//! request's `mcp` tool entries into N function tools, one per tool
+//! the remote MCP server advertises via `tools/list`. The model sees
+//! a flat list of function tools named
+//! `mcp_<server_label>__<tool_name>`; the
+//! [`McpExecutor`](super::executor) intercepts those calls, looks up
+//! the right pooled client, and runs the actual `tools/call`.
+//!
+//! Uniform rewriting (even for OpenAI) is intentional: it keeps the
+//! interception logic single-path and gives Hadrian-side policy
+//! enforcement / audit on every call, regardless of upstream. The
+//! tradeoff is OpenAI's first-party MCP optimizations aren't used in
+//! `hadrian_hosted` — operators wanting those should pick
+//! `passthrough_openai` instead.
+//!
+//! Failures here surface as HTTP 502 (bad gateway) when the upstream
+//! MCP server is unreachable, or HTTP 400 (bad request) for caller-
+//! side mistakes — duplicate `server_label`, ambiguous `tool_choice`,
+//! `connector_id` under `hadrian_hosted`, etc. See
+//! [`McpRewriteError::is_client_error`].
+
+use std::sync::Arc;
+
+use super::{McpService, McpToolMeta};
+use crate::{
+    api_types::responses::{
+        CreateResponsesPayload, FunctionCallOutput, FunctionCallOutputType, FunctionToolCall,
+        FunctionToolCallType, McpAllowedTools, McpCallItem, McpTool, McpToolFilter, ResponsesInput,
+        ResponsesInputItem, ResponsesMcpToolChoice, ResponsesNamedToolChoice,
+        ResponsesNamedToolChoiceType, ResponsesToolChoice, ResponsesToolDefinition,
+    },
+    services::{mcp::tool_search::TOOL_SEARCH_FUNCTION_NAME, mcp_tool::McpProviderKind},
+};
+
+/// Failures surfaced by [`rewrite_mcp_tools`]. `ListToolsFailed` maps
+/// to HTTP 502 (the upstream MCP server is unreachable). The other
+/// variants are caller errors and map to HTTP 400.
+#[derive(Debug, thiserror::Error)]
+pub enum McpRewriteError {
+    #[error("MCP tools/list failed for server '{server_label}' ({server_url}): {message}")]
+    ListToolsFailed {
+        server_label: String,
+        server_url: String,
+        message: String,
+    },
+    #[error(
+        "MCP request has conflicting server_label '{0}': it duplicates, or normalizes to the \
+         same function-name prefix as, another `mcp` tool entry. server_labels must be unique \
+         once reduced to `[A-Za-z0-9_]` (e.g. 'My-Co' and 'My_Co' collide); use distinct labels"
+    )]
+    DuplicateServerLabel(String),
+    #[error(
+        "MCP tool with server_label '{0}' has no server_url (connector_id requires passthrough mode)"
+    )]
+    MissingServerUrl(String),
+    #[error(
+        "MCP `tool_choice` for server_label '{server_label}' is ambiguous: \
+         no `name` was supplied and {match_count} matching tool(s) survived the rewrite. \
+         Under `hadrian_hosted` the upstream function tool_choice grammar has no \
+         per-server constraint, so the `name` field is required when more than one tool \
+         from the server is exposed (and at least one must be exposed). \
+         Specify `tool_choice.name` or narrow `allowed_tools` until exactly one tool remains."
+    )]
+    AmbiguousToolChoice {
+        server_label: String,
+        match_count: usize,
+    },
+    #[error(
+        "MCP tool with server_label '{0}' set `defer_loading_passthrough` but the resolved \
+         provider does not support native tool search; only OpenAI / Azure OpenAI do. Drop \
+         the flag to use Hadrian-side tool search, which works behind any provider"
+    )]
+    DeferLoadingPassthroughUnsupported(String),
+    #[error(
+        "MCP server '{server_label}' advertised tool '{tool}' with a definition Hadrian \
+         cannot turn into a function tool: {message}"
+    )]
+    InvalidToolDefinition {
+        server_label: String,
+        tool: String,
+        message: String,
+    },
+}
+
+impl McpRewriteError {
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::ListToolsFailed { .. } => "mcp_list_tools_failed",
+            Self::DuplicateServerLabel(_) => "mcp_duplicate_server_label",
+            Self::MissingServerUrl(_) => "mcp_missing_server_url",
+            Self::AmbiguousToolChoice { .. } => "mcp_ambiguous_tool_choice",
+            Self::DeferLoadingPassthroughUnsupported(_) => {
+                "mcp_defer_loading_passthrough_unsupported"
+            }
+            Self::InvalidToolDefinition { .. } => "mcp_invalid_tool_definition",
+        }
+    }
+
+    /// True when this error is a caller-side problem (HTTP 400) rather
+    /// than an upstream / gateway failure (HTTP 502). Used by the route
+    /// handler to pick the right status code.
+    pub fn is_client_error(&self) -> bool {
+        !matches!(
+            self,
+            Self::ListToolsFailed { .. } | Self::InvalidToolDefinition { .. }
+        )
+    }
+}
+
+/// Replace every `mcp` tool entry in `payload.tools` with function
+/// tools the model can call. Mutates in place.
+///
+/// Each MCP server is handled one of three ways:
+///
+/// - **eager** (no `defer_loading`): one function tool per allowed tool,
+///   exposed up front — the original behaviour.
+/// - **deferred, Hadrian-side** (`defer_loading: true`, the default):
+///   the server's per-tool functions are *not* exposed; instead a single
+///   `tool_search` function tool is injected. [`ToolSearchExecutor`] runs
+///   the search locally and injects matched tools on demand. Works behind
+///   any provider.
+/// - **deferred, native passthrough** (`defer_loading: true` +
+///   `defer_loading_passthrough: true`, OpenAI/Azure only): per-tool
+///   functions are exposed with `defer_loading` set, leaving the upstream
+///   to run its own tool search.
+///
+/// A server pinned by `tool_choice` is always treated as eager (forcing a
+/// tool implies it must be callable now, so deferral is moot).
+///
+/// No-op when the payload has no `mcp` tool entries.
+pub async fn rewrite_mcp_tools(
+    payload: &mut CreateResponsesPayload,
+    mcp_service: &McpService,
+    provider: McpProviderKind,
+) -> Result<(), McpRewriteError> {
+    // Spec: "as long as the `mcp_list_tools` item is present in the
+    // context of an API request, the API will not fetch a list of
+    // tools from the MCP server again." Build an index of any
+    // caller-provided catalogs BEFORE acquiring the mutable borrow on
+    // `payload.tools` below, so we can skip the upstream `tools/list`
+    // round-trip for matching server_labels.
+    let inlined_catalogs = collect_inlined_catalogs(payload);
+    // Which server (if any) `tool_choice` pins — read before the mutable
+    // borrow below. A pinned server is forced eager.
+    let forced_label = mcp_choice_label(payload);
+
+    // Translate any prior-turn `mcp_call` items the caller echoed back
+    // into the `function_call` + `function_call_output` shape every
+    // provider understands. Must run after `collect_inlined_catalogs`
+    // (which reads `mcp_list_tools` items from the same input) and
+    // before the tool-presence early-returns below, so multi-turn MCP
+    // history survives even on a turn that carries no `mcp` tool entry.
+    rewrite_mcp_history(payload);
+
+    let Some(tools) = payload.tools.as_mut() else {
+        return Ok(());
+    };
+    if !tools.iter().any(|t| t.is_mcp()) {
+        return Ok(());
+    }
+
+    // First pass: duplicate detection on the *sanitized* label. Two
+    // distinct raw labels that reduce to the same function-name prefix
+    // (e.g. `"My-Co"` and `"My_Co"` → `"My_Co"`) would otherwise route
+    // calls to whichever binding `resolve_binding` found first. Keying on
+    // the sanitized form rejects both exact duplicates and collisions.
+    {
+        let mut seen = std::collections::HashSet::new();
+        for t in tools.iter() {
+            if let Some(mcp) = t.as_mcp()
+                && !seen.insert(sanitize_label(&mcp.server_label, MAX_LABEL_LEN))
+            {
+                return Err(McpRewriteError::DuplicateServerLabel(
+                    mcp.server_label.clone(),
+                ));
+            }
+        }
+    }
+
+    // Second pass: rewrite. Walk + build a fresh Vec rather than
+    // splice-in-place to keep ordering deterministic.
+    let mut rewritten: Vec<ResponsesToolDefinition> = Vec::with_capacity(tools.len());
+    // Servers exposed via Hadrian-side tool search (one shared
+    // `tool_search` tool is injected for all of them at the end). Each
+    // entry keeps the optional `server_description` so the model can use
+    // it to decide when to search a given server.
+    let mut deferred_servers: Vec<(String, Option<String>)> = Vec::new();
+    for tool in tools.drain(..) {
+        match tool {
+            ResponsesToolDefinition::Mcp(mcp) => {
+                let server_url = mcp
+                    .server_url
+                    .as_deref()
+                    .ok_or_else(|| McpRewriteError::MissingServerUrl(mcp.server_label.clone()))?;
+
+                let wants_defer = mcp.defer_loading == Some(true);
+                let wants_passthrough = mcp.defer_loading_passthrough == Some(true);
+                // The native-passthrough opt-in only works on an upstream
+                // that actually implements tool search. Fail loud rather
+                // than silently ignoring the caller's request.
+                if wants_defer && wants_passthrough && !provider.supports_passthrough_mcp() {
+                    return Err(McpRewriteError::DeferLoadingPassthroughUnsupported(
+                        mcp.server_label.clone(),
+                    ));
+                }
+                let forced = forced_label.as_deref() == Some(mcp.server_label.as_str());
+                // Hadrian-side deferral: wants deferral, isn't opting into
+                // native passthrough, and isn't pinned by tool_choice.
+                let hadrian_deferred = wants_defer && !wants_passthrough && !forced;
+
+                let headers = mcp.headers.clone().unwrap_or_default();
+                // Always fetch + prime the catalog: the executor's
+                // `tool_search` and `mcp_list_tools` reads rely on the
+                // primed cache, and eager rewriting needs it directly.
+                let catalog = match inlined_catalogs.get(&mcp.server_label) {
+                    Some(inlined) => {
+                        // Caller already has the catalog in context —
+                        // skip the network round-trip. Prime the service
+                        // cache so downstream reads (`cached_tools`,
+                        // `read_only_hint_for`) see the same catalog.
+                        let metas: Vec<McpToolMeta> =
+                            inlined.iter().map(meta_from_listed_tool).collect();
+                        mcp_service.prime_tools_cache(
+                            server_url,
+                            mcp.authorization.as_deref(),
+                            &headers,
+                            metas.clone(),
+                        );
+                        Arc::new(metas)
+                    }
+                    None => mcp_service
+                        .list_tools(server_url, mcp.authorization.as_deref(), &headers)
+                        .await
+                        .map_err(|e| McpRewriteError::ListToolsFailed {
+                            server_label: mcp.server_label.clone(),
+                            server_url: server_url.to_string(),
+                            message: e.to_string(),
+                        })?,
+                };
+
+                if hadrian_deferred {
+                    // Keep the catalog out of the prompt; expose it via
+                    // the shared `tool_search` tool injected below.
+                    tracing::debug!(
+                        server_label = %mcp.server_label,
+                        "MCP `defer_loading`: deferring catalog via Hadrian-side tool search"
+                    );
+                    deferred_servers
+                        .push((mcp.server_label.clone(), mcp.server_description.clone()));
+                    continue;
+                }
+
+                // Eager or native-passthrough: expose per-tool functions.
+                // `defer_loading` is set on them only for the passthrough
+                // path, where the upstream runs its own tool search.
+                let defer_flag = wants_defer && wants_passthrough;
+                for meta in catalog.iter() {
+                    if !is_allowed(meta, mcp.allowed_tools.as_ref()) {
+                        continue;
+                    }
+                    if !is_valid_tool_name(&meta.name) {
+                        tracing::warn!(
+                            tool = %meta.name,
+                            server_label = %mcp.server_label,
+                            "Skipping MCP tool with non-ASCII or invalid name (must match \
+                             [A-Za-z0-9_-]{{1,48}})"
+                        );
+                        continue;
+                    }
+                    rewritten.push(build_function_tool(&mcp, meta, defer_flag)?);
+                }
+            }
+            other => rewritten.push(other),
+        }
+    }
+
+    // One shared `tool_search` tool covers every Hadrian-deferred server.
+    if !deferred_servers.is_empty() {
+        rewritten.push(build_tool_search_function(&deferred_servers));
+    }
+
+    *tools = rewritten;
+
+    rewrite_tool_choice(payload)?;
+
+    Ok(())
+}
+
+/// The `server_label` an `mcp` `tool_choice` pins, if any. Read before
+/// the rewrite so a forced server can be exposed eagerly.
+fn mcp_choice_label(payload: &CreateResponsesPayload) -> Option<String> {
+    match payload.tool_choice.as_ref()? {
+        ResponsesToolChoice::Mcp(c) => Some(c.server_label.clone()),
+        _ => None,
+    }
+}
+
+/// Build the single `tool_search` function tool the model uses to
+/// discover deferred tools. Lists the searchable servers — with their
+/// `server_description` when supplied — in the description so the model
+/// can decide which server to search and when.
+fn build_tool_search_function(
+    deferred_servers: &[(String, Option<String>)],
+) -> ResponsesToolDefinition {
+    // `label` or `label (description)` per server, comma-joined.
+    let servers = deferred_servers
+        .iter()
+        .map(
+            |(label, desc)| match desc.as_deref().filter(|s| !s.is_empty()) {
+                Some(d) => format!("{label} ({d})"),
+                None => label.clone(),
+            },
+        )
+        .collect::<Vec<_>>()
+        .join(", ");
+    let labels: Vec<&str> = deferred_servers.iter().map(|(l, _)| l.as_str()).collect();
+    let description = format!(
+        "Search for tools to call. Tools from these MCP servers are available but not loaded \
+         up front: {servers}. Call this with a natural-language `query` describing the task to \
+         discover matching tools; the matching tool definitions are then loaded and become \
+         callable. Optionally pass `server_label` to restrict the search to one server."
+    );
+    let def = serde_json::json!({
+        "type": "function",
+        "name": TOOL_SEARCH_FUNCTION_NAME,
+        "description": description,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Natural-language description of the tool(s) you need."
+                },
+                "server_label": {
+                    "type": "string",
+                    "description": "Optional: restrict the search to this MCP server.",
+                    "enum": labels,
+                }
+            },
+            "required": ["query"],
+            "additionalProperties": false
+        },
+        "strict": false
+    });
+    ResponsesToolDefinition::Function(
+        crate::api_types::responses::FunctionTool::from_json(def)
+            .expect("tool_search function-tool definition is well-formed"),
+    )
+}
+
+/// Walk `payload.input` for `mcp_list_tools` items and return a map of
+/// `server_label → Vec<McpListedTool>`. When the caller chains a prior
+/// response via `previous_response_id` (or hand-rolls input items),
+/// these catalogs are already in context and the API spec says we
+/// shouldn't refetch.
+fn collect_inlined_catalogs(
+    payload: &CreateResponsesPayload,
+) -> std::collections::HashMap<String, Vec<crate::api_types::responses::McpListedTool>> {
+    let mut out = std::collections::HashMap::new();
+    let Some(ResponsesInput::Items(items)) = payload.input.as_ref() else {
+        return out;
+    };
+    for item in items {
+        if let ResponsesInputItem::McpListTools(it) = item {
+            // Skip catalogs flagged as errors — they have no usable
+            // tools and we still need a fresh fetch.
+            if it.error.is_some() {
+                continue;
+            }
+            out.insert(it.server_label.clone(), it.tools.clone());
+        }
+    }
+    out
+}
+
+/// Rewrite prior-turn `mcp_call` items echoed back in `payload.input`
+/// into the `function_call` + `function_call_output` pair every provider
+/// understands. Mutates in place; a no-op when no `mcp_call` items are
+/// present.
+///
+/// Under `hadrian_hosted` the model only ever sees `mcp_<label>__<tool>`
+/// *function* tools — the `function_call` it actually emits is suppressed
+/// from the client and replaced by a synthesized `mcp_call` output item.
+/// On a follow-up turn, a client that resends prior output items (the
+/// standard Responses multi-turn pattern, and the *only* option for
+/// providers without server-side `previous_response_id` state, i.e.
+/// everything except OpenAI/Azure) sends those `mcp_call` items back as
+/// input. Left untranslated they hit the per-provider conversion's
+/// catch-all and are dropped — erasing the assistant's tool call and its
+/// result from context. Rewriting them back into the function pair keeps
+/// multi-turn MCP coherent behind any provider, mirroring exactly what
+/// [`super::executor`] folds into the continuation during a live loop.
+///
+/// `mcp_list_tools` items are intentionally left for the provider
+/// conversion to drop: they're output-only catalog snapshots the model
+/// doesn't reason over, and dropping them loses no conversational
+/// content. `mcp_approval_request` / `mcp_approval_response` items are
+/// also left alone — pending approvals are resolved by [`super::resume`].
+fn rewrite_mcp_history(payload: &mut CreateResponsesPayload) {
+    let Some(ResponsesInput::Items(items)) = payload.input.as_mut() else {
+        return;
+    };
+    if !items
+        .iter()
+        .any(|i| matches!(i, ResponsesInputItem::McpCall(_)))
+    {
+        return;
+    }
+    let mut rewritten = Vec::with_capacity(items.len() + 1);
+    for item in std::mem::take(items) {
+        match item {
+            ResponsesInputItem::McpCall(call) => {
+                let (function_call, output) = mcp_call_to_function_pair(call);
+                rewritten.push(ResponsesInputItem::FunctionCall(function_call));
+                rewritten.push(ResponsesInputItem::FunctionCallOutput(output));
+            }
+            other => rewritten.push(other),
+        }
+    }
+    *items = rewritten;
+}
+
+/// Reconstruct the `(function_call, function_call_output)` pair for one
+/// echoed `mcp_call` item. The two share a `call_id` derived from the
+/// item id so the provider conversion pairs them (Anthropic `tool_use` /
+/// `tool_result`, etc.). The result-string encoding matches the
+/// executor's live-loop continuation: `output` verbatim on success,
+/// `{"error": …}` on failure (the executor stores at most one of
+/// `output` / `error`).
+fn mcp_call_to_function_pair(call: McpCallItem) -> (FunctionToolCall, FunctionCallOutput) {
+    let function_name = synthesize_function_name(&call.server_label, &call.name);
+    // Reuse the item id as the pairing token — it's already unique per
+    // response and never collides with a live `function_call.call_id`
+    // (those are suppressed before the client ever sees them).
+    let call_id = call.id.clone();
+    let output_text = match (&call.output, &call.error) {
+        (_, Some(err)) => serde_json::json!({ "error": err }).to_string(),
+        (Some(out), None) => out.clone(),
+        (None, None) => String::new(),
+    };
+    let function_call = FunctionToolCall {
+        type_: FunctionToolCallType::FunctionCall,
+        id: call.id,
+        call_id: call_id.clone(),
+        name: function_name,
+        arguments: call.arguments,
+        status: None,
+    };
+    let output = FunctionCallOutput {
+        type_: FunctionCallOutputType::FunctionCallOutput,
+        id: None,
+        call_id,
+        output: output_text,
+        status: None,
+    };
+    (function_call, output)
+}
+
+fn meta_from_listed_tool(t: &crate::api_types::responses::McpListedTool) -> McpToolMeta {
+    McpToolMeta {
+        name: t.name.clone(),
+        description: t.description.clone(),
+        input_schema: t.input_schema.clone(),
+        annotations: t.annotations.clone(),
+    }
+}
+
+/// Translate `tool_choice = {"type": "mcp", server_label, name?}` into
+/// the function-tool form the rewritten payload exposes.
+///
+/// OpenAI's `ToolChoiceMCP` schema accepts `name: null`, but the
+/// schema description is "force the model to call a specific tool on a
+/// remote MCP server" — i.e. `name` is the load-bearing field. Under
+/// `passthrough_openai` the entry is forwarded verbatim and OpenAI's
+/// hosted MCP runtime gets to apply its own semantics for the no-name
+/// case. Under `hadrian_hosted` we rewrite to flat function tools, and
+/// the upstream function `tool_choice` grammar has no "any function
+/// from server L" predicate — so we can only honor the unambiguous
+/// shapes:
+///
+/// - `{"type":"mcp","server_label":"L","name":"T"}` → named function
+///   `mcp_<sanitized(L)>__T`.
+/// - `{"type":"mcp","server_label":"L"}` with exactly one rewritten
+///   function from `L` → pin to that single function.
+/// - `{"type":"mcp","server_label":"L"}` with zero or ≥2 matches →
+///   reject as `AmbiguousToolChoice`. The previous behaviour was to
+///   fall back to `"required"`, which let the model pick from any
+///   tool in the request (potentially a different server). Failing
+///   fast is more honest than silently weakening the constraint.
+fn rewrite_tool_choice(payload: &mut CreateResponsesPayload) -> Result<(), McpRewriteError> {
+    let Some(choice) = payload.tool_choice.as_mut() else {
+        return Ok(());
+    };
+    let ResponsesToolChoice::Mcp(ResponsesMcpToolChoice {
+        server_label, name, ..
+    }) = choice
+    else {
+        return Ok(());
+    };
+    let new_choice = match name {
+        Some(tool_name) => ResponsesToolChoice::Named(ResponsesNamedToolChoice {
+            type_: ResponsesNamedToolChoiceType::Function,
+            name: synthesize_function_name(server_label, tool_name),
+        }),
+        None => {
+            // Find every rewritten function whose synthesized prefix
+            // matches this server label. The prefix is stable because
+            // `sanitize_label` is deterministic.
+            let sanitized = sanitize_label(server_label, MAX_LABEL_LEN);
+            let prefix = format!("{FUNCTION_NAME_PREFIX}{sanitized}{SEPARATOR}");
+            let mut matching: Vec<&str> = Vec::new();
+            if let Some(tools) = payload.tools.as_ref() {
+                for t in tools {
+                    if let ResponsesToolDefinition::Function(f) = t
+                        && f.name.starts_with(&prefix)
+                    {
+                        matching.push(f.name.as_str());
+                    }
+                }
+            }
+            match matching.as_slice() {
+                [only] => ResponsesToolChoice::Named(ResponsesNamedToolChoice {
+                    type_: ResponsesNamedToolChoiceType::Function,
+                    name: (*only).to_string(),
+                }),
+                _ => {
+                    return Err(McpRewriteError::AmbiguousToolChoice {
+                        server_label: server_label.clone(),
+                        match_count: matching.len(),
+                    });
+                }
+            }
+        }
+    };
+    *choice = new_choice;
+    Ok(())
+}
+
+pub(crate) fn is_allowed(meta: &McpToolMeta, allowed: Option<&McpAllowedTools>) -> bool {
+    match allowed {
+        None => true,
+        Some(McpAllowedTools::List(names)) => names.iter().any(|n| n == &meta.name),
+        Some(McpAllowedTools::Filter(filter)) => filter_matches(filter, meta),
+    }
+}
+
+/// True iff `meta` (name + `readOnlyHint` annotation) satisfies every
+/// constraint declared on `filter`. Empty constraints (both fields
+/// `None`) match every tool.
+fn filter_matches(filter: &McpToolFilter, meta: &McpToolMeta) -> bool {
+    if let Some(names) = filter.tool_names.as_ref()
+        && !names.iter().any(|n| n == &meta.name)
+    {
+        return false;
+    }
+    if let Some(required) = filter.read_only {
+        // Per the MCP tool filter spec, a `read_only` predicate matches
+        // only tools carrying an explicit `readOnlyHint` annotation equal
+        // to `required`. An absent annotation (`None`) matches neither
+        // `true` nor `false` — don't coerce it to `false`.
+        let hint = meta
+            .annotations
+            .as_ref()
+            .and_then(|a| a.get("readOnlyHint"))
+            .and_then(|v| v.as_bool());
+        if hint != Some(required) {
+            return false;
+        }
+    }
+    true
+}
+
+/// Build the JSON function-tool definition the model will see for
+/// one MCP-advertised tool. `defer_loading` is set on the function only
+/// on the native-passthrough path (an OpenAI/Azure upstream running its
+/// own tool search); the default Hadrian-side path defers via the
+/// `tool_search` tool instead and passes `false`.
+pub(crate) fn build_function_tool(
+    mcp: &McpTool,
+    meta: &McpToolMeta,
+    defer_loading: bool,
+) -> Result<ResponsesToolDefinition, McpRewriteError> {
+    let function_name = synthesize_function_name(&mcp.server_label, &meta.name);
+    let description = compose_description(mcp, meta);
+    let parameters = if meta.input_schema.is_object() {
+        meta.input_schema.clone()
+    } else {
+        serde_json::json!({"type": "object", "properties": {}})
+    };
+
+    let mut def = serde_json::json!({
+        "type": "function",
+        "name": function_name,
+        "description": description,
+        "parameters": parameters,
+        "strict": false,
+    });
+    // `def` is a freshly constructed object literal, so `as_object_mut`
+    // can't be `None` here.
+    let obj = def
+        .as_object_mut()
+        .expect("function tool literal is an object");
+    // Forward MCP tool annotations (read-only hint, idempotency,
+    // destructive hint, title) verbatim so downstream consumers and
+    // any provider that surfaces these to the model can use them.
+    if let Some(ann) = meta.annotations.as_ref() {
+        obj.insert("annotations".into(), ann.clone());
+    }
+    // Only the native-passthrough path forwards `defer_loading` onto the
+    // function tool, leaving the OpenAI/Azure upstream to run its own
+    // tool search. `defer_loading` is a valid field on `function` tools
+    // per OpenAI's spec (`openapi/openai.openapi.json::FunctionToolParam`).
+    if defer_loading {
+        obj.insert("defer_loading".into(), serde_json::Value::Bool(true));
+    }
+
+    // `parameters` and `description` come from the remote MCP server
+    // (untrusted). A pathological `input_schema` that fails to
+    // deserialize into `FunctionTool` must surface as a 502, not panic
+    // the request task.
+    let function = crate::api_types::responses::FunctionTool::from_json(def).map_err(|e| {
+        McpRewriteError::InvalidToolDefinition {
+            server_label: mcp.server_label.clone(),
+            tool: meta.name.clone(),
+            message: e.to_string(),
+        }
+    })?;
+    Ok(ResponsesToolDefinition::Function(function))
+}
+
+/// Stable function-name derivation. The **server label** is sanitized
+/// and truncated to [`MAX_LABEL_LEN`]; the **tool name** is taken
+/// verbatim because we need to round-trip it back to the MCP server
+/// unchanged. The two budgets are sized so the combined
+/// `mcp_<label>__<tool>` always fits the providers' 64-char function-name
+/// regex (`[A-Za-z0-9_-]{1,64}`). Tool names that wouldn't pass
+/// validation are rejected at rewrite time (see [`is_valid_tool_name`]).
+pub fn synthesize_function_name(server_label: &str, tool_name: &str) -> String {
+    let label = sanitize_label(server_label, MAX_LABEL_LEN);
+    format!("{FUNCTION_NAME_PREFIX}{label}{SEPARATOR}{tool_name}")
+}
+
+/// Split a function name back into `(sanitized_label, tool_name)`.
+/// The tool name is the original (un-sanitized) name the MCP server
+/// exposed and is safe to pass to `tools/call`.
+///
+/// Returns `None` if `name` doesn't match the rewrite shape.
+pub fn parse_function_name(name: &str) -> Option<(&str, &str)> {
+    let stripped = name.strip_prefix(FUNCTION_NAME_PREFIX)?;
+    let (label, tool) = stripped.split_once(SEPARATOR)?;
+    if label.is_empty() || tool.is_empty() {
+        return None;
+    }
+    Some((label, tool))
+}
+
+/// True iff `name` is a legal OpenAI function-tool name. Used to
+/// filter MCP tools the model can't address — exotic names ("my.tool"
+/// or non-ASCII) are skipped at rewrite time with a warning rather
+/// than mangled (which would break the round-trip to `tools/call`).
+pub fn is_valid_tool_name(name: &str) -> bool {
+    !name.is_empty()
+        && name.len() <= MAX_TOOL_LEN
+        && name
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
+}
+
+const FUNCTION_NAME_PREFIX: &str = "mcp_";
+const SEPARATOR: &str = "__";
+/// Every provider we target caps function/tool names at 64 chars
+/// (`^[A-Za-z0-9_-]{1,64}$`). The synthesized name is
+/// `mcp_<label>__<tool>`, so the label and tool budgets together must
+/// leave room for the 6 fixed chars (`mcp_` + `__`). The static
+/// assertion below enforces `prefix + label + sep + tool <= 64` so a
+/// long label *and* a long tool name can never combine into a name the
+/// upstream rejects (which would 400 the whole request). The tool name
+/// is preserved verbatim — never truncated — so the round-trip back to
+/// `tools/call` is exact; tools whose name alone exceeds `MAX_TOOL_LEN`
+/// are skipped at rewrite time (see [`is_valid_tool_name`]).
+const MAX_FUNCTION_NAME_LEN: usize = 64;
+const MAX_LABEL_LEN: usize = 18;
+const MAX_TOOL_LEN: usize = 40;
+const _: () = assert!(
+    FUNCTION_NAME_PREFIX.len() + MAX_LABEL_LEN + SEPARATOR.len() + MAX_TOOL_LEN
+        <= MAX_FUNCTION_NAME_LEN,
+    "synthesized MCP function name `mcp_<label>__<tool>` must fit the 64-char provider limit"
+);
+
+/// Replace anything outside `[A-Za-z0-9]` with `_`, collapse runs of
+/// `_`, and truncate to `max_len`. Match-on-prefix detection means the
+/// output must be ASCII-only.
+///
+/// Collapsing underscore runs is load-bearing: the synthesized function
+/// name is `mcp_<label>__<tool>` and [`parse_function_name`] splits on
+/// the first `__`. If a sanitized label could itself contain `__` (e.g.
+/// raw `"a  b"` → `"a__b"`), the split would land mid-label and route a
+/// call to the wrong tool. Collapsing guarantees the label has no `__`.
+fn sanitize_label(s: &str, max_len: usize) -> String {
+    let mut out = String::with_capacity(s.len().min(max_len));
+    let mut prev_underscore = false;
+    for ch in s.chars() {
+        let mapped = if ch.is_ascii_alphanumeric() { ch } else { '_' };
+        if mapped == '_' {
+            if prev_underscore {
+                continue;
+            }
+            prev_underscore = true;
+        } else {
+            prev_underscore = false;
+        }
+        out.push(mapped);
+        if out.len() >= max_len {
+            break;
+        }
+    }
+    if out.is_empty() {
+        out.push('x');
+    }
+    out
+}
+
+fn compose_description(mcp: &McpTool, meta: &McpToolMeta) -> String {
+    // Fold in the operator-supplied `server_description` — OpenAI's spec
+    // says it's "used to provide more context" and the model uses it to
+    // decide when a server's tools are relevant.
+    let mut prefix = format!("MCP tool from server `{}`.", mcp.server_label);
+    if let Some(sd) = mcp.server_description.as_deref().filter(|s| !s.is_empty()) {
+        prefix = format!("{prefix} {sd}");
+    }
+    match meta.description.as_deref() {
+        Some(d) if !d.is_empty() => format!("{prefix} {d}"),
+        _ => prefix,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api_types::responses::McpToolType;
+
+    fn meta(name: &str, description: Option<&str>) -> McpToolMeta {
+        McpToolMeta {
+            name: name.to_string(),
+            description: description.map(str::to_string),
+            input_schema: serde_json::json!({"type": "object"}),
+            annotations: None,
+        }
+    }
+
+    fn mcp_with(label: &str, allowed: Option<McpAllowedTools>) -> McpTool {
+        McpTool {
+            type_: McpToolType::Mcp,
+            server_label: label.to_string(),
+            server_url: Some("https://x".to_string()),
+            connector_id: None,
+            server_description: None,
+            authorization: None,
+            headers: None,
+            require_approval: None,
+            allowed_tools: allowed,
+            defer_loading: None,
+            defer_loading_passthrough: None,
+            call_timeout_secs: None,
+        }
+    }
+
+    #[test]
+    fn synthesized_name_round_trips() {
+        let n = synthesize_function_name("atlassian", "jira_search");
+        assert_eq!(n, "mcp_atlassian__jira_search");
+        let (l, t) = parse_function_name(&n).unwrap();
+        assert_eq!(l, "atlassian");
+        assert_eq!(t, "jira_search");
+    }
+
+    #[test]
+    fn synthesized_name_sanitizes_label_only() {
+        // Label gets sanitized; tool name is preserved verbatim so the
+        // call round-trips to the MCP server.
+        let n = synthesize_function_name("My Co/Linear", "issue_list");
+        assert!(n.starts_with("mcp_My_Co_Linear__"));
+        let (l, t) = parse_function_name(&n).unwrap();
+        assert_eq!(l, "My_Co_Linear");
+        assert_eq!(t, "issue_list");
+    }
+
+    #[test]
+    fn synthesized_name_truncates_long_labels() {
+        let long_label = "a".repeat(100);
+        let n = synthesize_function_name(&long_label, "tool");
+        let (l, _) = parse_function_name(&n).unwrap();
+        assert_eq!(l.len(), MAX_LABEL_LEN);
+    }
+
+    #[test]
+    fn synthesized_name_fits_provider_limit_at_max_budgets() {
+        // Worst case: a label that truncates to MAX_LABEL_LEN plus a tool
+        // name at exactly MAX_TOOL_LEN must still fit the 64-char limit.
+        let label = "a".repeat(100);
+        let tool = "b".repeat(MAX_TOOL_LEN);
+        assert!(is_valid_tool_name(&tool));
+        let n = synthesize_function_name(&label, &tool);
+        assert!(
+            n.len() <= MAX_FUNCTION_NAME_LEN,
+            "synthesized name {} chars exceeds {MAX_FUNCTION_NAME_LEN}",
+            n.len()
+        );
+    }
+
+    #[test]
+    fn parse_rejects_non_prefix() {
+        assert!(parse_function_name("foo_bar__baz").is_none());
+        assert!(parse_function_name("mcp_only").is_none());
+        assert!(parse_function_name("mcp___missing_label").is_none());
+    }
+
+    #[test]
+    fn sanitize_label_collapses_underscore_runs_so_name_round_trips() {
+        // A label with consecutive non-alnum chars must NOT yield `__`
+        // inside the label, or `parse_function_name` (which splits on the
+        // first `__`) would land mid-label and route to the wrong tool.
+        let n = synthesize_function_name("a  b", "do__thing");
+        assert_eq!(n, "mcp_a_b__do__thing");
+        let (l, t) = parse_function_name(&n).unwrap();
+        assert_eq!(l, "a_b");
+        // Tool name (which legitimately contains `__`) round-trips intact.
+        assert_eq!(t, "do__thing");
+    }
+
+    #[test]
+    fn distinct_labels_collide_after_sanitization() {
+        // `-` and `_` both sanitize to `_`, so these two raw labels map to
+        // the same function-name prefix — duplicate detection keys on the
+        // sanitized form to reject the collision.
+        assert_eq!(
+            sanitize_label("My-Co", MAX_LABEL_LEN),
+            sanitize_label("My_Co", MAX_LABEL_LEN)
+        );
+    }
+
+    #[test]
+    fn is_valid_tool_name_accepts_typical_names() {
+        assert!(is_valid_tool_name("jira_search"));
+        assert!(is_valid_tool_name("get-user"));
+        assert!(is_valid_tool_name("a"));
+    }
+
+    #[test]
+    fn is_valid_tool_name_rejects_problematic_names() {
+        assert!(!is_valid_tool_name(""));
+        assert!(!is_valid_tool_name("issue.list")); // contains dot
+        assert!(!is_valid_tool_name("my tool")); // contains space
+        assert!(!is_valid_tool_name("héllo")); // non-ASCII
+        assert!(!is_valid_tool_name(&"x".repeat(50))); // too long
+    }
+
+    #[test]
+    fn is_allowed_none_means_all() {
+        let m = meta("jira_search", None);
+        assert!(is_allowed(&m, None));
+    }
+
+    #[test]
+    fn is_allowed_list_form() {
+        let m = meta("jira_search", None);
+        assert!(is_allowed(
+            &m,
+            Some(&McpAllowedTools::List(vec!["jira_search".into()]))
+        ));
+        assert!(!is_allowed(
+            &m,
+            Some(&McpAllowedTools::List(vec!["other".into()]))
+        ));
+    }
+
+    #[test]
+    fn is_allowed_filter_form() {
+        let m = meta("jira_search", None);
+        assert!(is_allowed(
+            &m,
+            Some(&McpAllowedTools::Filter(McpToolFilter {
+                tool_names: Some(vec!["jira_search".into()]),
+                read_only: None,
+            }))
+        ));
+    }
+
+    #[test]
+    fn is_allowed_filter_read_only_matches_annotation() {
+        let mut m = meta("jira_search", None);
+        m.annotations = Some(serde_json::json!({"readOnlyHint": true}));
+        assert!(is_allowed(
+            &m,
+            Some(&McpAllowedTools::Filter(McpToolFilter {
+                tool_names: None,
+                read_only: Some(true),
+            }))
+        ));
+        // read_only: true demands the hint to be true; a tool without
+        // the annotation is excluded.
+        let m2 = meta("jira_create", None);
+        assert!(!is_allowed(
+            &m2,
+            Some(&McpAllowedTools::Filter(McpToolFilter {
+                tool_names: None,
+                read_only: Some(true),
+            }))
+        ));
+    }
+
+    #[test]
+    fn description_falls_back_when_server_omits_one() {
+        let m = mcp_with("atlassian", None);
+        let t = meta("jira_search", None);
+        let desc = compose_description(&m, &t);
+        assert_eq!(desc, "MCP tool from server `atlassian`.");
+    }
+
+    #[test]
+    fn description_includes_server_description() {
+        let m = mcp_with("atlassian", None);
+        let t = meta("jira_search", Some("Search Jira issues"));
+        let desc = compose_description(&m, &t);
+        assert!(desc.starts_with("MCP tool from server `atlassian`."));
+        assert!(desc.contains("Search Jira issues"));
+    }
+
+    #[test]
+    fn build_function_tool_produces_function_variant() {
+        let m = mcp_with("atlassian", None);
+        let t = meta("jira_search", Some("Search Jira"));
+        let def = build_function_tool(&m, &t, false).expect("valid tool def");
+        assert!(matches!(def, ResponsesToolDefinition::Function(_)));
+        if let ResponsesToolDefinition::Function(func) = def {
+            assert_eq!(func.name, "mcp_atlassian__jira_search");
+            assert!(func.description.as_deref().unwrap().contains("Search Jira"));
+            assert_eq!(
+                func.parameters.as_ref().unwrap()["type"],
+                serde_json::Value::String("object".into())
+            );
+            assert!(!func.extras.contains_key("annotations"));
+        }
+    }
+
+    #[test]
+    fn build_function_tool_sets_defer_loading_on_passthrough_path() {
+        // `defer_loading` is set on the function only when the caller asks
+        // for native passthrough (an OpenAI/Azure upstream runs its own
+        // tool search). The flag is a valid field on FunctionToolParam.
+        let m = mcp_with("atlassian", None);
+        let t = meta("jira_search", None);
+        let def = build_function_tool(&m, &t, true).expect("valid tool def");
+        if let ResponsesToolDefinition::Function(func) = def {
+            assert_eq!(func.defer_loading, Some(true));
+        } else {
+            panic!("expected function tool");
+        }
+    }
+
+    #[test]
+    fn build_function_tool_omits_defer_loading_on_default_path() {
+        let m = mcp_with("atlassian", None);
+        let t = meta("jira_search", None);
+        let def = build_function_tool(&m, &t, false).expect("valid tool def");
+        if let ResponsesToolDefinition::Function(func) = def {
+            assert_eq!(func.defer_loading, None);
+        } else {
+            panic!("expected function tool");
+        }
+    }
+
+    #[test]
+    fn build_function_tool_forwards_annotations() {
+        let m = mcp_with("atlassian", None);
+        let mut t = meta("jira_search", None);
+        t.annotations = Some(serde_json::json!({
+            "readOnlyHint": true,
+            "title": "Search Jira",
+        }));
+        let def = build_function_tool(&m, &t, false).expect("valid tool def");
+        if let ResponsesToolDefinition::Function(func) = def {
+            let ann = func.extras.get("annotations").expect("annotations present");
+            assert_eq!(ann["readOnlyHint"], true);
+            assert_eq!(ann["title"], "Search Jira");
+        } else {
+            panic!("expected function tool");
+        }
+    }
+
+    #[tokio::test]
+    async fn rewrite_uses_inlined_catalog_and_skips_upstream_fetch() {
+        // When the caller's input already includes an `mcp_list_tools`
+        // item for the same server_label, the rewrite uses that catalog
+        // directly. We confirm the upstream wasn't contacted by pointing
+        // server_url at a non-existent host — if the rewrite tried to
+        // fetch, the test would fail with a network error.
+        use crate::api_types::responses::{
+            McpListToolsItem, McpListToolsItemType, McpListedTool, ResponsesInput,
+            ResponsesInputItem,
+        };
+
+        let service = McpService::new();
+        let payload_json = serde_json::json!({
+            "tools": [{
+                "type": "mcp",
+                "server_label": "atlassian",
+                "server_url": "http://127.0.0.1:1/never-reachable",
+            }],
+        });
+        let mut payload: CreateResponsesPayload = serde_json::from_value(payload_json).unwrap();
+        payload.input = Some(ResponsesInput::Items(vec![
+            ResponsesInputItem::McpListTools(McpListToolsItem {
+                type_: McpListToolsItemType::McpListTools,
+                id: "mcpl_abc".into(),
+                server_label: "atlassian".into(),
+                tools: vec![McpListedTool {
+                    name: "jira_search".into(),
+                    description: Some("Search Jira".into()),
+                    input_schema: serde_json::json!({"type":"object"}),
+                    annotations: None,
+                }],
+                error: None,
+            }),
+        ]));
+
+        rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Test)
+            .await
+            .expect("rewrite uses inlined catalog without contacting upstream");
+
+        let tools = payload.tools.unwrap();
+        assert_eq!(tools.len(), 1);
+        if let ResponsesToolDefinition::Function(f) = &tools[0] {
+            assert_eq!(f.name, "mcp_atlassian__jira_search");
+        } else {
+            panic!("expected one rewritten function tool");
+        }
+
+        // The cache was primed; the executor's cached_tools read path
+        // sees the same catalog.
+        let cached = service.cached_tools(
+            "http://127.0.0.1:1/never-reachable",
+            None,
+            &std::collections::HashMap::new(),
+        );
+        assert!(cached.is_some());
+        assert_eq!(cached.unwrap().len(), 1);
+    }
+
+    /// Build a payload with one `mcp` tool entry whose catalog is inlined
+    /// (so the rewrite never hits the network), plus optional `extra`
+    /// fields merged onto the tool entry (e.g. `defer_loading`).
+    fn payload_with_inlined_catalog(
+        tool_names: &[&str],
+        extra: serde_json::Value,
+    ) -> CreateResponsesPayload {
+        use crate::api_types::responses::{
+            McpListToolsItem, McpListToolsItemType, McpListedTool, ResponsesInput,
+            ResponsesInputItem,
+        };
+        let mut tool = serde_json::json!({
+            "type": "mcp",
+            "server_label": "atlassian",
+            "server_url": "http://127.0.0.1:1/never-reachable",
+        });
+        if let (Some(obj), Some(extra)) = (tool.as_object_mut(), extra.as_object()) {
+            for (k, v) in extra {
+                obj.insert(k.clone(), v.clone());
+            }
+        }
+        let mut payload: CreateResponsesPayload =
+            serde_json::from_value(serde_json::json!({ "tools": [tool] })).unwrap();
+        payload.input = Some(ResponsesInput::Items(vec![
+            ResponsesInputItem::McpListTools(McpListToolsItem {
+                type_: McpListToolsItemType::McpListTools,
+                id: "mcpl_abc".into(),
+                server_label: "atlassian".into(),
+                tools: tool_names
+                    .iter()
+                    .map(|n| McpListedTool {
+                        name: (*n).into(),
+                        description: Some(format!("desc for {n}")),
+                        input_schema: serde_json::json!({"type":"object"}),
+                        annotations: None,
+                    })
+                    .collect(),
+                error: None,
+            }),
+        ]));
+        payload
+    }
+
+    fn tool_names(payload: &CreateResponsesPayload) -> Vec<String> {
+        payload
+            .tools
+            .as_ref()
+            .unwrap()
+            .iter()
+            .filter_map(|t| match t {
+                ResponsesToolDefinition::Function(f) => Some(f.name.clone()),
+                _ => None,
+            })
+            .collect()
+    }
+
+    #[tokio::test]
+    async fn rewrite_deferred_server_injects_tool_search_not_per_tool_functions() {
+        let service = McpService::new();
+        let mut payload = payload_with_inlined_catalog(
+            &["jira_search", "jira_create"],
+            serde_json::json!({ "defer_loading": true }),
+        );
+        rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Anthropic)
+            .await
+            .unwrap();
+
+        let names = tool_names(&payload);
+        // Exactly the search tool — no per-tool mcp_* functions.
+        assert_eq!(names, vec![TOOL_SEARCH_FUNCTION_NAME.to_string()]);
+        assert!(!names.iter().any(|n| n.starts_with("mcp_atlassian__")));
+
+        // Catalog is still primed for the executor to search.
+        let cached = service.cached_tools(
+            "http://127.0.0.1:1/never-reachable",
+            None,
+            &std::collections::HashMap::new(),
+        );
+        assert_eq!(cached.unwrap().len(), 2);
+    }
+
+    #[tokio::test]
+    async fn rewrite_eager_server_exposes_per_tool_functions() {
+        let service = McpService::new();
+        let mut payload =
+            payload_with_inlined_catalog(&["jira_search", "jira_create"], serde_json::json!({}));
+        rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Anthropic)
+            .await
+            .unwrap();
+
+        let mut names = tool_names(&payload);
+        names.sort();
+        assert_eq!(
+            names,
+            vec![
+                "mcp_atlassian__jira_create".to_string(),
+                "mcp_atlassian__jira_search".to_string(),
+            ]
+        );
+        // No search tool when nothing is deferred.
+        assert!(!names.iter().any(|n| n == TOOL_SEARCH_FUNCTION_NAME));
+    }
+
+    #[tokio::test]
+    async fn rewrite_passthrough_keeps_functions_with_defer_loading_on_openai() {
+        let service = McpService::new();
+        let mut payload = payload_with_inlined_catalog(
+            &["jira_search"],
+            serde_json::json!({ "defer_loading": true, "defer_loading_passthrough": true }),
+        );
+        rewrite_mcp_tools(&mut payload, &service, McpProviderKind::OpenAi)
+            .await
+            .unwrap();
+
+        let tools = payload.tools.unwrap();
+        assert_eq!(tools.len(), 1);
+        // Native passthrough: per-tool function exposed with defer_loading set,
+        // and NO Hadrian-side tool_search tool.
+        match &tools[0] {
+            ResponsesToolDefinition::Function(f) => {
+                assert_eq!(f.name, "mcp_atlassian__jira_search");
+                assert_eq!(f.defer_loading, Some(true));
+            }
+            other => panic!("expected function tool, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn rewrite_passthrough_rejected_on_non_openai_provider() {
+        let service = McpService::new();
+        let mut payload = payload_with_inlined_catalog(
+            &["jira_search"],
+            serde_json::json!({ "defer_loading": true, "defer_loading_passthrough": true }),
+        );
+        let err = rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Anthropic)
+            .await
+            .expect_err("passthrough on non-OpenAI must be rejected");
+        assert_eq!(err.code(), "mcp_defer_loading_passthrough_unsupported");
+        assert!(err.is_client_error());
+    }
+
+    #[tokio::test]
+    async fn rewrite_tool_choice_forces_deferred_server_eager() {
+        // A deferred server pinned by tool_choice is exposed eagerly so
+        // the forced call can resolve — no tool_search for it.
+        let service = McpService::new();
+        let mut payload = payload_with_inlined_catalog(
+            &["jira_search", "jira_create"],
+            serde_json::json!({ "defer_loading": true }),
+        );
+        payload.tool_choice = Some(
+            serde_json::from_value(serde_json::json!({
+                "type": "mcp",
+                "server_label": "atlassian",
+                "name": "jira_search"
+            }))
+            .unwrap(),
+        );
+        rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Anthropic)
+            .await
+            .unwrap();
+
+        let names = tool_names(&payload);
+        // Forced eager → per-tool functions present, no tool_search.
+        assert!(names.iter().any(|n| n == "mcp_atlassian__jira_search"));
+        assert!(!names.iter().any(|n| n == TOOL_SEARCH_FUNCTION_NAME));
+    }
+
+    #[tokio::test]
+    async fn rewrite_rejects_ambiguous_tool_choice_without_name() {
+        // tool_choice = {type:"mcp", server_label:"L"} with no name
+        // and >1 tools surviving the rewrite is ambiguous under
+        // hadrian_hosted — fail with mcp_ambiguous_tool_choice rather
+        // than silently weakening to "required".
+        use crate::api_types::responses::{
+            McpListToolsItem, McpListToolsItemType, McpListedTool, ResponsesInput,
+            ResponsesInputItem,
+        };
+
+        let service = McpService::new();
+        let payload_json = serde_json::json!({
+            "tools": [{
+                "type": "mcp",
+                "server_label": "atlassian",
+                "server_url": "http://127.0.0.1:1/never-reachable",
+            }],
+            "tool_choice": {
+                "type": "mcp",
+                "server_label": "atlassian",
+            },
+        });
+        let mut payload: CreateResponsesPayload = serde_json::from_value(payload_json).unwrap();
+        payload.input = Some(ResponsesInput::Items(vec![
+            ResponsesInputItem::McpListTools(McpListToolsItem {
+                type_: McpListToolsItemType::McpListTools,
+                id: "mcpl_abc".into(),
+                server_label: "atlassian".into(),
+                tools: vec![
+                    McpListedTool {
+                        name: "jira_search".into(),
+                        description: None,
+                        input_schema: serde_json::json!({"type":"object"}),
+                        annotations: None,
+                    },
+                    McpListedTool {
+                        name: "jira_create".into(),
+                        description: None,
+                        input_schema: serde_json::json!({"type":"object"}),
+                        annotations: None,
+                    },
+                ],
+                error: None,
+            }),
+        ]));
+
+        let err = rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Test)
+            .await
+            .expect_err("expected ambiguous tool_choice rejection");
+        match err {
+            McpRewriteError::AmbiguousToolChoice {
+                server_label,
+                match_count,
+            } => {
+                assert_eq!(server_label, "atlassian");
+                assert_eq!(match_count, 2);
+            }
+            other => panic!("expected AmbiguousToolChoice, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn rewrite_pins_to_single_match_when_name_omitted() {
+        // The degenerate single-match case still works: tool_choice
+        // without `name` resolves to the only tool surviving the rewrite.
+        use crate::api_types::responses::{
+            McpListToolsItem, McpListToolsItemType, McpListedTool, ResponsesInput,
+            ResponsesInputItem,
+        };
+
+        let service = McpService::new();
+        let payload_json = serde_json::json!({
+            "tools": [{
+                "type": "mcp",
+                "server_label": "atlassian",
+                "server_url": "http://127.0.0.1:1/never-reachable",
+            }],
+            "tool_choice": {
+                "type": "mcp",
+                "server_label": "atlassian",
+            },
+        });
+        let mut payload: CreateResponsesPayload = serde_json::from_value(payload_json).unwrap();
+        payload.input = Some(ResponsesInput::Items(vec![
+            ResponsesInputItem::McpListTools(McpListToolsItem {
+                type_: McpListToolsItemType::McpListTools,
+                id: "mcpl_abc".into(),
+                server_label: "atlassian".into(),
+                tools: vec![McpListedTool {
+                    name: "jira_search".into(),
+                    description: None,
+                    input_schema: serde_json::json!({"type":"object"}),
+                    annotations: None,
+                }],
+                error: None,
+            }),
+        ]));
+
+        rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Test)
+            .await
+            .unwrap();
+        match payload.tool_choice.as_ref().unwrap() {
+            ResponsesToolChoice::Named(n) => {
+                assert_eq!(n.name, "mcp_atlassian__jira_search");
+            }
+            other => panic!("expected Named function tool_choice, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn ambiguous_tool_choice_is_client_error() {
+        let e = McpRewriteError::AmbiguousToolChoice {
+            server_label: "atlassian".into(),
+            match_count: 2,
+        };
+        assert!(e.is_client_error());
+        assert_eq!(e.code(), "mcp_ambiguous_tool_choice");
+    }
+
+    #[test]
+    fn list_tools_failed_is_not_client_error() {
+        let e = McpRewriteError::ListToolsFailed {
+            server_label: "atlassian".into(),
+            server_url: "https://x".into(),
+            message: "boom".into(),
+        };
+        assert!(!e.is_client_error());
+    }
+
+    #[tokio::test]
+    async fn rewrite_translates_prior_mcp_call_to_function_pair() {
+        // A follow-up turn echoes a completed `mcp_call`; the rewrite must
+        // turn it into a `function_call` + `function_call_output` pair so
+        // non-OpenAI providers (which drop raw `mcp_call` input items)
+        // still see the assistant's call and its result.
+        use crate::api_types::responses::{
+            McpCallItem, McpCallItemType, McpItemStatus, ResponsesInput, ResponsesInputItem,
+        };
+
+        let service = McpService::new();
+        // No `mcp` tool entry on this turn — history rewrite must still run.
+        let mut payload: CreateResponsesPayload =
+            serde_json::from_value(serde_json::json!({})).unwrap();
+        payload.input = Some(ResponsesInput::Items(vec![ResponsesInputItem::McpCall(
+            McpCallItem {
+                type_: McpCallItemType::McpCall,
+                id: "mcp_abc".into(),
+                server_label: "atlassian".into(),
+                name: "jira_search".into(),
+                arguments: r#"{"q":"bug"}"#.into(),
+                status: McpItemStatus::Completed,
+                output: Some("found 3 issues".into()),
+                error: None,
+                approval_request_id: None,
+            },
+        )]));
+
+        rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Anthropic)
+            .await
+            .unwrap();
+
+        let Some(ResponsesInput::Items(items)) = payload.input.as_ref() else {
+            panic!("expected items input");
+        };
+        assert_eq!(items.len(), 2, "one mcp_call → call + output pair");
+        match &items[0] {
+            ResponsesInputItem::FunctionCall(fc) => {
+                assert_eq!(fc.name, "mcp_atlassian__jira_search");
+                assert_eq!(fc.arguments, r#"{"q":"bug"}"#);
+                assert_eq!(fc.call_id, "mcp_abc");
+            }
+            other => panic!("expected function_call, got {other:?}"),
+        }
+        match &items[1] {
+            ResponsesInputItem::FunctionCallOutput(out) => {
+                assert_eq!(out.call_id, "mcp_abc");
+                assert_eq!(out.output, "found 3 issues");
+            }
+            other => panic!("expected function_call_output, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn rewrite_translates_failed_mcp_call_with_error_envelope() {
+        // A failed `mcp_call` (output null, error set) folds into the same
+        // `{"error": …}` envelope the executor uses in the live loop.
+        use crate::api_types::responses::{
+            McpCallItem, McpCallItemType, McpItemStatus, ResponsesInput, ResponsesInputItem,
+        };
+
+        let service = McpService::new();
+        let mut payload: CreateResponsesPayload =
+            serde_json::from_value(serde_json::json!({})).unwrap();
+        payload.input = Some(ResponsesInput::Items(vec![ResponsesInputItem::McpCall(
+            McpCallItem {
+                type_: McpCallItemType::McpCall,
+                id: "mcp_err".into(),
+                server_label: "atlassian".into(),
+                name: "jira_search".into(),
+                arguments: "{}".into(),
+                status: McpItemStatus::Failed,
+                output: None,
+                error: Some("upstream 500".into()),
+                approval_request_id: None,
+            },
+        )]));
+
+        rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Anthropic)
+            .await
+            .unwrap();
+
+        let Some(ResponsesInput::Items(items)) = payload.input.as_ref() else {
+            panic!("expected items input");
+        };
+        match &items[1] {
+            ResponsesInputItem::FunctionCallOutput(out) => {
+                assert_eq!(out.output, r#"{"error":"upstream 500"}"#);
+            }
+            other => panic!("expected function_call_output, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn rewrite_ignores_inlined_catalog_when_errored() {
+        // An `mcp_list_tools` item carrying `error` is not a usable
+        // catalog; the rewrite must fall through to a fresh fetch.
+        // Since we point at an unreachable host, that fetch fails — we
+        // verify the rewrite *attempted* the fetch by checking for the
+        // ListToolsFailed error rather than success.
+        use crate::api_types::responses::{
+            McpListToolsItem, McpListToolsItemType, ResponsesInput, ResponsesInputItem,
+        };
+
+        let service = McpService::new();
+        let payload_json = serde_json::json!({
+            "tools": [{
+                "type": "mcp",
+                "server_label": "atlassian",
+                "server_url": "http://127.0.0.1:1/never-reachable",
+            }],
+        });
+        let mut payload: CreateResponsesPayload = serde_json::from_value(payload_json).unwrap();
+        payload.input = Some(ResponsesInput::Items(vec![
+            ResponsesInputItem::McpListTools(McpListToolsItem {
+                type_: McpListToolsItemType::McpListTools,
+                id: "mcpl_abc".into(),
+                server_label: "atlassian".into(),
+                tools: vec![],
+                error: Some("upstream down".into()),
+            }),
+        ]));
+
+        let err = rewrite_mcp_tools(&mut payload, &service, McpProviderKind::Test)
+            .await
+            .expect_err("errored catalog should not be used; upstream fetch must run");
+        assert!(matches!(err, McpRewriteError::ListToolsFailed { .. }));
+    }
+}
diff --git a/src/services/mcp/resume.rs b/src/services/mcp/resume.rs
new file mode 100644
index 0000000..156e37c
--- /dev/null
+++ b/src/services/mcp/resume.rs
@@ -0,0 +1,662 @@
+//! Resume parked MCP tool calls.
+//!
+//! When a caller sends a follow-up `/v1/responses` request containing
+//! `mcp_approval_response` input items, this module:
+//!
+//! 1. Atomically *claims* each parked approval by `approval_request_id`
+//!    (scoped to the caller's org) with a `DELETE … RETURNING`. Doing
+//!    the delete up front, before the upstream call, makes resume
+//!    exactly-once: of two concurrent resumes of the same id only the
+//!    one that wins the delete gets the row and proceeds.
+//! 2. On `approve: true` — pulls the caller's bearer / headers off the
+//!    matching `mcp` tool entry on the current request, invokes the
+//!    original `tools/call` via [`McpService`], and folds the result
+//!    back as a reconstructed `function_call` + `function_call_output`
+//!    pair sharing the parked `call_id`. The original `function_call`
+//!    was suppressed from the client when the gate parked it, so
+//!    emitting both keeps the call/result coherent on providers that
+//!    translate to native pairwise formats. The model on its next turn
+//!    sees the result and continues.
+//! 3. On `approve: false` — synthesizes the same pair with a
+//!    `{ "error": "<reason>" }` JSON output. The model sees the refusal
+//!    and can replan. **Does not require the `mcp` tool block** —
+//!    refusals don't need to call the upstream.
+//!
+//! Approvals that can't be claimed (already consumed, expired, wrong
+//! org, never parked) are dropped from `input` with a warning so the
+//! request can proceed — the alternative (rejecting the whole request)
+//! would leave the caller unable to recover from stale UI state. The
+//! tradeoff of claiming before calling is that a transient upstream
+//! failure consumes the approval; that is preferable to risking a
+//! double-executed side-effecting tool.
+//!
+//! ### Why the bearer comes from `payload.tools`, not the parked row
+//!
+//! The parked row deliberately stores `server_label` / `server_url` /
+//! tool name / arguments — but **not** the caller's `authorization`
+//! header. That keeps OAuth tokens out of the database. Resumption
+//! pulls the bearer back off the live request's `tools[]` entry that
+//! matches the parked `server_label`, so the caller continues to
+//! "own" the credential exactly as they do on every other request.
+
+use std::collections::HashMap;
+
+use uuid::Uuid;
+
+use super::{McpService, preprocess::synthesize_function_name};
+use crate::{
+    api_types::responses::{
+        CreateResponsesPayload, FunctionCallOutput, FunctionCallOutputType, FunctionToolCall,
+        FunctionToolCallType, McpApprovalResponseItem, ResponsesInput, ResponsesInputItem,
+        ResponsesToolDefinition,
+    },
+    db::repos::McpPendingApprovalsRepo,
+};
+
+/// Failures surfaced by [`resume_mcp_approvals`].
+///
+/// `CallFailed` / `Repo` map to HTTP 502 (the upstream MCP server or
+/// the approvals table failed). `MissingToolBinding` maps to HTTP 400
+/// — the caller asked us to approve a call but didn't include the
+/// matching `mcp` tool entry on the request, so we have no bearer to
+/// forward. Lookup misses on the approvals table itself are NOT
+/// errors (warn + drop, so stale UI state doesn't brick the request).
+#[derive(Debug, thiserror::Error)]
+pub enum McpResumeError {
+    #[error("MCP resume failed for tool '{tool}' on '{server_label}': {message}")]
+    CallFailed {
+        server_label: String,
+        tool: String,
+        message: String,
+    },
+    #[error("MCP approvals repo error: {0}")]
+    Repo(String),
+    #[error(
+        "MCP approval response approves a call to server '{server_label}' but the request \
+         does not include a matching `mcp` tool entry. Re-send the original `tools` block on \
+         the resume request so the gateway has credentials for the upstream call. \
+         (approval_request_id: {approval_request_id})"
+    )]
+    MissingToolBinding {
+        server_label: String,
+        approval_request_id: String,
+    },
+    #[error(
+        "MCP approval response for server '{server_label}' targets a different server origin \
+         than the call that was approved. The approval was issued for '{approved_origin}' but \
+         the resume request's `mcp` tool entry points at '{request_origin}'. Re-send the \
+         original `server_url` so the approved call runs against the host it was approved for. \
+         (approval_request_id: {approval_request_id})"
+    )]
+    ServerOriginMismatch {
+        server_label: String,
+        approved_origin: String,
+        request_origin: String,
+        approval_request_id: String,
+    },
+}
+
+impl McpResumeError {
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::CallFailed { .. } => "mcp_resume_call_failed",
+            Self::Repo(_) => "mcp_resume_repo_error",
+            Self::MissingToolBinding { .. } => "mcp_resume_missing_tool_binding",
+            Self::ServerOriginMismatch { .. } => "mcp_resume_server_origin_mismatch",
+        }
+    }
+
+    /// True when this error reflects a malformed caller request (HTTP
+    /// 400) rather than an upstream / gateway failure (HTTP 502). The
+    /// route handler uses this to pick the right status.
+    pub fn is_client_error(&self) -> bool {
+        matches!(
+            self,
+            Self::MissingToolBinding { .. } | Self::ServerOriginMismatch { .. }
+        )
+    }
+}
+
+/// Authorization, headers, and the full `server_url` extracted from
+/// one `mcp` tool entry on the live request. Owned (not borrowed)
+/// because we need to release the immutable borrow on `payload.tools`
+/// before re-acquiring a mutable borrow on `payload.input` to rewrite
+/// it. The extra clone of the bearer / URL happens once per request —
+/// negligible.
+///
+/// `server_url` is sourced from the live request rather than the
+/// parked row because we deliberately trim the stored URL to
+/// scheme+host (matches OpenAI's discard-after-request behaviour).
+#[derive(Debug, Clone)]
+struct ToolBinding {
+    authorization: Option<String>,
+    headers: HashMap<String, String>,
+    server_url: Option<String>,
+    /// Upper bound on the resumed `tools/call`, resolved from the tool's
+    /// `call_timeout_secs` extension or the deployment default. Same
+    /// rationale as the streaming dispatch path: rmcp/reqwest apply no
+    /// timeout, so an unresponsive server would otherwise hang the
+    /// resume request indefinitely.
+    call_timeout: std::time::Duration,
+}
+
+/// Process every `mcp_approval_response` item in `payload.input`.
+///
+/// Mutates `payload.input` in place: each `McpApprovalResponse` is
+/// replaced by a `FunctionCallOutput` carrying the call's result (on
+/// approve) or refusal (on deny). Caller is the `org_id` whose
+/// approvals table we look in.
+pub async fn resume_mcp_approvals(
+    payload: &mut CreateResponsesPayload,
+    mcp_service: &McpService,
+    org_id: Uuid,
+    default_call_timeout_secs: u64,
+) -> Result<(), McpResumeError> {
+    // Quick exit: no approvals → no work, no allocation.
+    let needs_resume = payload
+        .input
+        .as_ref()
+        .map(|i| match i {
+            ResponsesInput::Items(items) => items
+                .iter()
+                .any(|x| matches!(x, ResponsesInputItem::McpApprovalResponse(_))),
+            ResponsesInput::Text(_) => false,
+        })
+        .unwrap_or(false);
+    if !needs_resume {
+        return Ok(());
+    }
+
+    let Some(repo) = mcp_service.approvals_repo().cloned() else {
+        tracing::warn!(
+            "MCP approval response items present but approvals repo is unavailable; \
+             dropping the items so the request can proceed"
+        );
+        if let Some(ResponsesInput::Items(items)) = payload.input.as_mut() {
+            items.retain(|i| !matches!(i, ResponsesInputItem::McpApprovalResponse(_)));
+        }
+        return Ok(());
+    };
+
+    // Build the server_label → ToolBinding lookup from payload.tools
+    // BEFORE mutating input. This is the credential the caller sent
+    // on THIS request — same lifecycle as any other authenticated
+    // call, never persisted by the gateway.
+    let bindings = collect_tool_bindings(payload, default_call_timeout_secs);
+
+    let Some(ResponsesInput::Items(items)) = payload.input.as_mut() else {
+        return Ok(());
+    };
+
+    let mut rewritten: Vec<ResponsesInputItem> = Vec::with_capacity(items.len());
+    for item in std::mem::take(items) {
+        match item {
+            ResponsesInputItem::McpApprovalResponse(resp) => {
+                if let Some((call, output)) =
+                    resolve_approval(&resp, mcp_service, repo.as_ref(), org_id, &bindings).await?
+                {
+                    // Emit the call and its output as a self-contained pair.
+                    // The model's original `function_call` was suppressed from
+                    // the client when the gate parked it, so the resumed
+                    // request carries no matching call for this output —
+                    // providers that translate to native pairwise formats
+                    // (Anthropic/Bedrock/Vertex) would drop an orphan
+                    // `function_call_output`. Reconstructing the pair keeps the
+                    // approved call and its result coherent behind any provider.
+                    rewritten.push(ResponsesInputItem::FunctionCall(call));
+                    rewritten.push(ResponsesInputItem::FunctionCallOutput(output));
+                }
+                // None means the approval wasn't found / already
+                // consumed — drop silently after the warn so the model
+                // doesn't see a dangling response.
+            }
+            other => rewritten.push(other),
+        }
+    }
+    *items = rewritten;
+    Ok(())
+}
+
+/// Walk `payload.tools` once and index every `mcp` entry by its
+/// `server_label`. Returns owned data so the caller can drop the
+/// borrow on `payload` before rewriting `payload.input`.
+fn collect_tool_bindings(
+    payload: &CreateResponsesPayload,
+    default_call_timeout_secs: u64,
+) -> HashMap<String, ToolBinding> {
+    let Some(tools) = payload.tools.as_ref() else {
+        return HashMap::new();
+    };
+    let mut out = HashMap::with_capacity(tools.len());
+    for tool in tools {
+        if let ResponsesToolDefinition::Mcp(mcp) = tool {
+            let timeout_secs = mcp.call_timeout_secs.unwrap_or(default_call_timeout_secs);
+            out.insert(
+                mcp.server_label.clone(),
+                ToolBinding {
+                    authorization: mcp.authorization.clone(),
+                    headers: mcp.headers.clone().unwrap_or_default(),
+                    server_url: mcp.server_url.clone(),
+                    call_timeout: std::time::Duration::from_secs(timeout_secs),
+                },
+            );
+        }
+    }
+    out
+}
+
+/// Look up + resolve one approval. Returns the reconstructed
+/// `(function_call, function_call_output)` pair to fold back into input,
+/// or `None` when the approval doesn't match any parked row.
+async fn resolve_approval(
+    resp: &McpApprovalResponseItem,
+    mcp_service: &McpService,
+    repo: &dyn McpPendingApprovalsRepo,
+    org_id: Uuid,
+    bindings: &HashMap<String, ToolBinding>,
+) -> Result<Option<(FunctionToolCall, FunctionCallOutput)>, McpResumeError> {
+    // Claim the row atomically (DELETE … RETURNING). Doing the delete up
+    // front — before the upstream call — is what makes resume exactly-once:
+    // two concurrent resumes of the same `approval_request_id` race on the
+    // delete, and only the winner gets `Some(row)` and proceeds to execute.
+    // The loser (and any replay of an already-consumed/expired id) sees
+    // `None` and is dropped. The tradeoff is that a transient upstream
+    // failure after the claim consumes the approval; we prefer that over
+    // risking a double-executed side-effecting tool.
+    let parked = repo
+        .take_by_id_and_org(&resp.approval_request_id, org_id, chrono::Utc::now())
+        .await
+        .map_err(|e| McpResumeError::Repo(e.to_string()))?;
+
+    let Some(row) = parked else {
+        tracing::warn!(
+            approval_request_id = %resp.approval_request_id,
+            "MCP approval response references an unknown (or already-consumed) parked call; ignoring"
+        );
+        return Ok(None);
+    };
+
+    // Resolve to (function_call_output text, mcp_call output, mcp_call error).
+    // `mcp_call.output` and `.error` are mutually exclusive on the
+    // synthesized output item the executor will emit; the
+    // `function_call_output` text is what the model actually consumes
+    // on its next turn.
+    let (output_text, mcp_output, mcp_error) = if resp.approve {
+        // Resume requires a live tool binding to recover the caller's
+        // bearer AND the full `server_url` — we deliberately don't
+        // persist auth tokens or the URL path/query in the approvals
+        // table. A missing binding is a malformed request (caller
+        // forgot to re-send `tools[]`); refuse with 400.
+        let binding =
+            bindings
+                .get(&row.server_label)
+                .ok_or_else(|| McpResumeError::MissingToolBinding {
+                    server_label: row.server_label.clone(),
+                    approval_request_id: resp.approval_request_id.clone(),
+                })?;
+        let server_url =
+            binding
+                .server_url
+                .as_deref()
+                .ok_or_else(|| McpResumeError::MissingToolBinding {
+                    server_label: row.server_label.clone(),
+                    approval_request_id: resp.approval_request_id.clone(),
+                })?;
+
+        // Bind the approval to the server it was approved against.
+        // The parked row stores the origin (scheme://host[:port]) the
+        // gate emitted the `mcp_approval_request` for; we recompute the
+        // origin of the live request's `server_url` and reject a
+        // mismatch. Without this, a caller holding a valid
+        // `approval_request_id` could resume the approved (tool, args)
+        // against a *different* host (same `server_label`), redirecting
+        // a human-approved side-effecting call — and forwarding that
+        // entry's bearer — to an attacker-chosen origin.
+        let request_origin = crate::routes::api::chat::trim_url_to_origin(server_url);
+        if request_origin != row.server_url {
+            tracing::warn!(
+                approval_request_id = %resp.approval_request_id,
+                server_label = %row.server_label,
+                approved_origin = %row.server_url,
+                request_origin = %request_origin,
+                "MCP approval response targets a different server origin than the approved call; refusing"
+            );
+            return Err(McpResumeError::ServerOriginMismatch {
+                server_label: row.server_label.clone(),
+                approved_origin: row.server_url.clone(),
+                request_origin,
+                approval_request_id: resp.approval_request_id.clone(),
+            });
+        }
+
+        // The arguments were serialized from a `Value` at park time, so
+        // a parse failure here means the stored row is corrupt. Don't
+        // silently call the tool with `null` args — fail loud.
+        let arguments: serde_json::Value =
+            serde_json::from_str(&row.arguments_json).map_err(|e| {
+                tracing::error!(
+                    approval_request_id = %resp.approval_request_id,
+                    server_label = %row.server_label,
+                    tool = %row.tool_name,
+                    error = %e,
+                    "Parked MCP approval has corrupt arguments_json; refusing to resume"
+                );
+                McpResumeError::CallFailed {
+                    server_label: row.server_label.clone(),
+                    tool: row.tool_name.clone(),
+                    message: format!("corrupt stored arguments: {e}"),
+                }
+            })?;
+        // Bound the call the same way the streaming dispatch path
+        // does: rmcp/reqwest apply no timeout, so an unresponsive
+        // server would hang the resume request. On expiry, surface a
+        // timeout failure to the model.
+        let call = mcp_service.call_tool(
+            server_url,
+            binding.authorization.as_deref(),
+            &binding.headers,
+            &row.tool_name,
+            arguments,
+        );
+        let result = match tokio::time::timeout(binding.call_timeout, call).await {
+            Ok(inner) => inner.map_err(|e| McpResumeError::CallFailed {
+                server_label: row.server_label.clone(),
+                tool: row.tool_name.clone(),
+                message: e.to_string(),
+            })?,
+            Err(_elapsed) => {
+                tracing::warn!(
+                    approval_request_id = %resp.approval_request_id,
+                    server_label = %row.server_label,
+                    tool = %row.tool_name,
+                    timeout_secs = binding.call_timeout.as_secs(),
+                    "Resumed MCP tools/call timed out"
+                );
+                // Evict the pooled connection: the timed-out request was
+                // abandoned mid-flight without a protocol-level cancel,
+                // so the rmcp session is suspect and must not be reused.
+                mcp_service.evict_endpoint(
+                    server_url,
+                    binding.authorization.as_deref(),
+                    &binding.headers,
+                );
+                return Err(McpResumeError::CallFailed {
+                    server_label: row.server_label.clone(),
+                    tool: row.tool_name.clone(),
+                    message: format!(
+                        "MCP tool call timed out after {}s",
+                        binding.call_timeout.as_secs()
+                    ),
+                });
+            }
+        };
+
+        let result_text = super::executor::collapse_result_text(&result);
+        if result.is_error {
+            let err = format!("MCP tool returned isError=true: {result_text}");
+            (
+                serde_json::json!({"error": result_text}).to_string(),
+                None,
+                Some(err),
+            )
+        } else {
+            (result_text.clone(), Some(result_text), None)
+        }
+    } else {
+        // Refusals don't hit the upstream — no binding needed. Lets
+        // callers cleanly deny without re-sending the tools block.
+        let detail = resp
+            .reason
+            .as_deref()
+            .filter(|s| !s.is_empty())
+            .unwrap_or("User refused the call.");
+        let refusal = format!("refused: {detail}");
+        (
+            serde_json::json!({ "error": refusal.clone() }).to_string(),
+            None,
+            Some(refusal),
+        )
+    };
+
+    // No delete here: the row was already claimed (and removed) by the
+    // `take_by_id_and_org` above.
+
+    // Hand the resolved approval to the executor so it can synthesize
+    // an `mcp_call` output item on the resumed response stream — the
+    // spec-mandated item carrying `output` / `error` and the link back
+    // to the original `approval_request_id`.
+    mcp_service.stash_resolved_approval(
+        org_id,
+        super::ResolvedMcpApproval {
+            call_id: row.call_id.clone(),
+            approval_request_id: resp.approval_request_id.clone(),
+            server_label: row.server_label.clone(),
+            tool_name: row.tool_name.clone(),
+            arguments_json: row.arguments_json.clone(),
+            output: mcp_output,
+            error: mcp_error,
+        },
+    );
+
+    // Reconstruct the assistant's `function_call` so the output below has a
+    // matching call to anchor to (`synthesize_function_name` yields the same
+    // `mcp_<label>__<tool>` name the rewrite exposed). The original was
+    // suppressed from the client at park time, so it isn't in the resumed
+    // input. `id` and `call_id` share the parked `call_id` — unique per
+    // response and never colliding with a live function-call id.
+    let function_call = FunctionToolCall {
+        type_: FunctionToolCallType::FunctionCall,
+        id: row.call_id.clone(),
+        call_id: row.call_id.clone(),
+        name: synthesize_function_name(&row.server_label, &row.tool_name),
+        arguments: row.arguments_json.clone(),
+        status: None,
+    };
+    let output = FunctionCallOutput {
+        type_: FunctionCallOutputType::FunctionCallOutput,
+        id: None,
+        call_id: row.call_id,
+        output: output_text,
+        status: None,
+    };
+    Ok(Some((function_call, output)))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api_types::responses::{McpTool, McpToolType};
+
+    fn mcp_tool_def(label: &str, auth: Option<&str>) -> ResponsesToolDefinition {
+        ResponsesToolDefinition::Mcp(McpTool {
+            type_: McpToolType::Mcp,
+            server_label: label.to_string(),
+            server_url: Some("https://x".to_string()),
+            connector_id: None,
+            server_description: None,
+            authorization: auth.map(str::to_string),
+            headers: None,
+            require_approval: None,
+            allowed_tools: None,
+            defer_loading: None,
+            defer_loading_passthrough: None,
+            call_timeout_secs: None,
+        })
+    }
+
+    fn payload_with_tools(tools: Vec<ResponsesToolDefinition>) -> CreateResponsesPayload {
+        let mut p: CreateResponsesPayload =
+            serde_json::from_value(serde_json::json!({})).expect("minimal payload");
+        p.tools = Some(tools);
+        p
+    }
+
+    #[test]
+    fn collect_tool_bindings_indexes_by_server_label() {
+        let payload = payload_with_tools(vec![
+            mcp_tool_def("atlassian", Some("Bearer X")),
+            mcp_tool_def("notion", Some("Bearer Y")),
+            // Non-mcp tools (here represented as a function tool)
+            // should be ignored by the indexer.
+            ResponsesToolDefinition::Function(
+                crate::api_types::responses::FunctionTool::from_json(
+                    serde_json::json!({"type":"function","name":"foo"}),
+                )
+                .unwrap(),
+            ),
+        ]);
+        let map = collect_tool_bindings(&payload, 300);
+        assert_eq!(map.len(), 2);
+        assert_eq!(
+            map.get("atlassian").unwrap().authorization.as_deref(),
+            Some("Bearer X")
+        );
+        assert_eq!(
+            map.get("notion").unwrap().authorization.as_deref(),
+            Some("Bearer Y")
+        );
+        assert!(!map.contains_key("github"));
+    }
+
+    #[test]
+    fn collect_tool_bindings_handles_no_tools() {
+        let payload: CreateResponsesPayload =
+            serde_json::from_value(serde_json::json!({})).unwrap();
+        let map = collect_tool_bindings(&payload, 300);
+        assert!(map.is_empty());
+    }
+
+    #[test]
+    fn collect_tool_bindings_captures_missing_authorization() {
+        // Callers without a bearer (e.g. anonymous MCP servers) still
+        // get a binding, just with `authorization: None`.
+        let payload = payload_with_tools(vec![mcp_tool_def("anon", None)]);
+        let map = collect_tool_bindings(&payload, 300);
+        assert!(map.get("anon").unwrap().authorization.is_none());
+    }
+
+    #[test]
+    fn missing_tool_binding_is_client_error() {
+        let e = McpResumeError::MissingToolBinding {
+            server_label: "atlassian".into(),
+            approval_request_id: "mcpr_x".into(),
+        };
+        assert!(e.is_client_error());
+        assert_eq!(e.code(), "mcp_resume_missing_tool_binding");
+    }
+
+    #[test]
+    fn call_failed_is_not_client_error() {
+        let e = McpResumeError::CallFailed {
+            server_label: "atlassian".into(),
+            tool: "jira_search".into(),
+            message: "503".into(),
+        };
+        assert!(!e.is_client_error());
+        assert_eq!(e.code(), "mcp_resume_call_failed");
+    }
+
+    /// Repo holding a single parked approval; `take_by_id_and_org`
+    /// returns it once (and `None` thereafter, mirroring the real
+    /// claim-and-delete semantics).
+    struct OneShotRepo {
+        row: std::sync::Mutex<Option<crate::db::repos::McpPendingApproval>>,
+    }
+
+    #[async_trait::async_trait]
+    impl McpPendingApprovalsRepo for OneShotRepo {
+        async fn insert(
+            &self,
+            _row: crate::db::repos::NewMcpPendingApproval,
+        ) -> crate::db::DbResult<()> {
+            Ok(())
+        }
+
+        async fn take_by_id_and_org(
+            &self,
+            id: &str,
+            org_id: Uuid,
+            _now: chrono::DateTime<chrono::Utc>,
+        ) -> crate::db::DbResult<Option<crate::db::repos::McpPendingApproval>> {
+            let mut guard = self.row.lock().unwrap();
+            match guard.as_ref() {
+                Some(r) if r.id == id && r.org_id == org_id => Ok(guard.take()),
+                _ => Ok(None),
+            }
+        }
+
+        async fn delete_expired(
+            &self,
+            _cutoff: chrono::DateTime<chrono::Utc>,
+        ) -> crate::db::DbResult<u64> {
+            Ok(0)
+        }
+    }
+
+    #[tokio::test]
+    async fn refusal_reconstructs_self_contained_function_pair() {
+        // A `mcp_approval_response` with `approve: false` is rewritten into
+        // a paired `function_call` + `function_call_output` so non-OpenAI
+        // providers (which drop an orphan `function_call_output`) still see
+        // the call and its refusal. Refusals don't hit the upstream, so no
+        // tool binding / network is needed.
+        use crate::api_types::responses::{McpApprovalResponseItem, McpApprovalResponseItemType};
+
+        let org_id = Uuid::new_v4();
+        let now = chrono::Utc::now();
+        let repo = std::sync::Arc::new(OneShotRepo {
+            row: std::sync::Mutex::new(Some(crate::db::repos::McpPendingApproval {
+                id: "mcpr_x".into(),
+                response_id: "resp_1".into(),
+                org_id,
+                call_id: "fc_1".into(),
+                server_label: "atlassian".into(),
+                server_url: "https://mcp.atlassian.com".into(),
+                tool_name: "jira_search".into(),
+                arguments_json: r#"{"q":"bug"}"#.into(),
+                created_at: now,
+                expires_at: now + chrono::Duration::seconds(600),
+            })),
+        });
+        let service = McpService::with_approvals_repo(
+            Some(repo as std::sync::Arc<dyn McpPendingApprovalsRepo>),
+            Default::default(),
+        );
+
+        let mut payload: CreateResponsesPayload =
+            serde_json::from_value(serde_json::json!({})).unwrap();
+        payload.input = Some(ResponsesInput::Items(vec![
+            ResponsesInputItem::McpApprovalResponse(McpApprovalResponseItem {
+                type_: McpApprovalResponseItemType::McpApprovalResponse,
+                approval_request_id: "mcpr_x".into(),
+                approve: false,
+                reason: Some("not now".into()),
+            }),
+        ]));
+
+        resume_mcp_approvals(&mut payload, &service, org_id, 300)
+            .await
+            .unwrap();
+
+        let Some(ResponsesInput::Items(items)) = payload.input.as_ref() else {
+            panic!("expected items input");
+        };
+        assert_eq!(items.len(), 2, "approval response → call + output pair");
+        match &items[0] {
+            ResponsesInputItem::FunctionCall(fc) => {
+                assert_eq!(fc.name, "mcp_atlassian__jira_search");
+                assert_eq!(fc.call_id, "fc_1");
+                assert_eq!(fc.arguments, r#"{"q":"bug"}"#);
+            }
+            other => panic!("expected function_call, got {other:?}"),
+        }
+        match &items[1] {
+            ResponsesInputItem::FunctionCallOutput(out) => {
+                assert_eq!(out.call_id, "fc_1");
+                assert!(out.output.contains("refused"));
+                assert!(out.output.contains("not now"));
+            }
+            other => panic!("expected function_call_output, got {other:?}"),
+        }
+    }
+}
diff --git a/src/services/mcp/service.rs b/src/services/mcp/service.rs
new file mode 100644
index 0000000..75443cb
--- /dev/null
+++ b/src/services/mcp/service.rs
@@ -0,0 +1,615 @@
+//! `McpService` — the long-lived `AppState` field that brokers
+//! Hadrian-hosted MCP calls. Holds:
+//!
+//! - a pool of warm [`McpClient`](super::McpClient) handles keyed by
+//!   `(server_url, auth_hash)` so chained calls inside one response
+//!   don't pay the `initialize` round-trip,
+//! - a tools-list cache keyed the same way so the preprocess rewrite
+//!   and the executor see the same catalog (and so the cold-start
+//!   `tools/list` only fires once per request),
+//! - a pending-approvals registry so `mcp_approval_response` items can
+//!   resume parked calls.
+//!
+//! The pool's eviction policy is intentionally simple in this
+//! iteration: TTL-based eviction on every cache access. Sophisticated
+//! LRU + max-entries can land later if pool growth becomes an issue.
+
+use std::{
+    collections::HashMap,
+    sync::Arc,
+    time::{Duration, Instant},
+};
+
+use dashmap::DashMap;
+use sha2::{Digest, Sha256};
+use tokio::sync::Mutex;
+
+use super::{McpClient, McpClientError, McpToolMeta};
+use crate::validation::{UrlValidationOptions, validate_base_url_opts};
+
+/// Cache TTL for warm clients. Reaped on next access; we intentionally
+/// don't run a background sweeper to keep the service free of timer
+/// state. Matches the `default_idle_ttl_secs` rationale for containers.
+const CLIENT_IDLE_TTL: Duration = Duration::from_secs(300);
+
+/// Cache TTL for `tools/list` responses, refreshed on miss. Short
+/// enough that a server adding a new tool gets picked up within ~1m;
+/// long enough that chained calls in one response amortize the cost.
+const TOOLS_CACHE_TTL: Duration = Duration::from_secs(60);
+
+/// Cache TTL for tool-description embeddings used by Hadrian-side tool
+/// search. The cache is content-addressed (keyed by the hash of the
+/// embedded text), so a stale entry can never be *wrong* — only
+/// occasionally re-embedded. A generous hour keeps a deferred catalog
+/// warm across the many requests an agent loop makes against it.
+const TOOL_EMBEDDING_TTL: Duration = Duration::from_secs(3600);
+
+/// Connection key. Including the auth-hash means two callers using
+/// different bearer tokens for the same `server_url` get separate
+/// pooled clients — no leak between credentials.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct McpEndpointKey {
+    pub server_url: String,
+    /// Hex-encoded SHA-256 of `(authorization || headers_sorted_json)`.
+    /// `None` is folded into a stable sentinel hash so anonymous
+    /// callers share a pool entry.
+    pub auth_hash: String,
+}
+
+impl McpEndpointKey {
+    pub fn new(
+        server_url: &str,
+        authorization: Option<&str>,
+        headers: &HashMap<String, String>,
+    ) -> Self {
+        let mut hasher = Sha256::new();
+        hasher.update(authorization.unwrap_or("").as_bytes());
+        hasher.update(b"\0");
+        let mut header_pairs: Vec<(&String, &String)> = headers.iter().collect();
+        header_pairs.sort_by(|a, b| a.0.cmp(b.0));
+        for (k, v) in header_pairs {
+            hasher.update(k.as_bytes());
+            hasher.update(b":");
+            hasher.update(v.as_bytes());
+            hasher.update(b"\n");
+        }
+        let auth_hash = hex::encode(hasher.finalize());
+        Self {
+            server_url: server_url.to_string(),
+            auth_hash,
+        }
+    }
+}
+
+struct PooledClient {
+    /// Shared, lock-free handle. `McpClient`'s `list_tools` / `call_tool`
+    /// take `&self` and rmcp's peer multiplexes concurrent JSON-RPC
+    /// requests over one session, so several in-flight `tools/call`s to
+    /// the same endpoint run concurrently rather than serializing behind
+    /// a mutex. Dropping the last `Arc` runs `McpClient::Drop`, which
+    /// issues a clean `RunningService::cancel`.
+    client: Arc<McpClient>,
+    last_used: Instant,
+}
+
+struct CachedTools {
+    tools: Arc<Vec<McpToolMeta>>,
+    refreshed_at: Instant,
+}
+
+/// Last `tools/list` failure for an endpoint, kept so the executor can
+/// surface the verbatim upstream error on the `mcp_list_tools` item
+/// rather than a generic placeholder. Cleared on the next success.
+struct CachedToolsError {
+    message: String,
+    at: Instant,
+}
+
+/// Approval that has just been resolved by [`super::resume`] and is
+/// waiting for the executor to surface as an `mcp_call` output item on
+/// the resumed response stream.
+///
+/// Keyed in [`McpServiceInner::resolved_approvals`] by
+/// `(org_id, call_id)`. The call_id matches the original
+/// `function_call`'s `call_id` that the model emitted before the gate
+/// parked it; the executor scans the resumed request's input for
+/// matching `function_call_output` items and consumes the entry.
+#[derive(Debug, Clone)]
+pub struct ResolvedMcpApproval {
+    /// Echoes the original `function_call.call_id` so the executor can
+    /// pair this entry with the `function_call_output` resume produced.
+    pub call_id: String,
+    /// Id of the `mcp_approval_request` item that gated this call;
+    /// surfaced on the synthesized `mcp_call.approval_request_id`.
+    pub approval_request_id: String,
+    /// Origin server label — must match an `mcp` tool entry on the
+    /// resumed request (resume already validated this).
+    pub server_label: String,
+    /// Tool name as advertised by the MCP server.
+    pub tool_name: String,
+    /// Arguments the model proposed for the parked call (JSON string).
+    pub arguments_json: String,
+    /// Successful tool result (text or stringified non-text content).
+    /// `None` when the call failed or was refused.
+    pub output: Option<String>,
+    /// Failure / refusal message. `None` on success.
+    pub error: Option<String>,
+}
+
+/// Window during which a stashed [`ResolvedMcpApproval`] is consumed
+/// by the executor. The executor reads at request-start, immediately
+/// after `resume_mcp_approvals` writes — sub-second under normal
+/// operation. The TTL is just defense against an executor that never
+/// runs (e.g. a request that errors out before reaching the pipeline).
+const RESOLVED_APPROVAL_TTL: Duration = Duration::from_secs(60);
+
+/// The long-lived MCP service held on [`AppState`](crate::AppState).
+/// Cheap to clone (everything is behind `Arc` / `DashMap`).
+#[derive(Clone)]
+pub struct McpService {
+    inner: Arc<McpServiceInner>,
+}
+
+/// Cache key for a tool-description embedding: `(embedding_model,
+/// sha256(text))`. The model is part of the key because vectors from
+/// different embedding models are not comparable.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+struct EmbeddingCacheKey {
+    model: String,
+    text_hash: String,
+}
+
+impl EmbeddingCacheKey {
+    fn new(model: &str, text: &str) -> Self {
+        let mut hasher = Sha256::new();
+        hasher.update(text.as_bytes());
+        Self {
+            model: model.to_string(),
+            text_hash: hex::encode(hasher.finalize()),
+        }
+    }
+}
+
+struct McpServiceInner {
+    pool: DashMap<McpEndpointKey, PooledClient>,
+    tools_cache: DashMap<McpEndpointKey, CachedTools>,
+    /// Last `tools/list` error per endpoint (see [`CachedToolsError`]).
+    tools_errors: DashMap<McpEndpointKey, CachedToolsError>,
+    /// Per-endpoint single-flight guards for `tools/list`. Without this,
+    /// concurrent first requests for the same endpoint all miss the
+    /// cache and stampede the upstream `tools/list` (common on agent
+    /// fan-out / cold start). The winner fetches and primes the cache;
+    /// the others await the lock and then hit the warm cache. Keyed the
+    /// same way as the pool so the map is bounded by distinct endpoints.
+    tools_fetch_locks: DashMap<McpEndpointKey, Arc<Mutex<()>>>,
+    /// Content-addressed cache of tool-description embeddings for
+    /// Hadrian-side tool search, keyed by `(model, sha256(text))`.
+    tool_embeddings: DashMap<EmbeddingCacheKey, (Arc<Vec<f64>>, Instant)>,
+    /// Persistence backend for parked approvals. `None` when the
+    /// gateway runs without a database — in that case the approval gate
+    /// **fails closed**: a call that `require_approval` would gate is
+    /// not run, and the executor surfaces a failed `mcp_call` explaining
+    /// that persistence is required (see
+    /// [`McpExecutor::park_for_approval`](super::executor::McpExecutor)).
+    /// Cross-replica / cross-request resume needs persistence.
+    approvals_repo: Option<Arc<dyn crate::db::repos::McpPendingApprovalsRepo>>,
+    /// Hand-off between `resume_mcp_approvals` (route layer) and
+    /// `McpExecutor::prefix_events` (pipeline layer). Resume writes one
+    /// entry per resolved approval; the executor drains entries whose
+    /// `call_id` matches a `function_call_output` on the resumed
+    /// request and emits a synthesized `mcp_call` output item so the
+    /// resumed response carries the spec-mandated item lifecycle.
+    resolved_approvals: DashMap<(uuid::Uuid, String), (ResolvedMcpApproval, Instant)>,
+    /// SSRF guard config, applied to every `server_url` before opening
+    /// a transport. Blocks loopback/private/cloud-metadata addresses
+    /// unless the operator explicitly opted in via `server.allow_*_urls`.
+    url_validation_opts: UrlValidationOptions,
+}
+
+impl McpService {
+    /// Construct a service without persistence. With no approvals repo
+    /// the approval gate fails closed (a gated call is refused, not run)
+    /// — use [`McpService::with_approvals_repo`] when a DB is available.
+    pub fn new() -> Self {
+        Self::with_approvals_repo(None, UrlValidationOptions::default())
+    }
+
+    /// Construct a service with the given approvals repo and SSRF
+    /// guard policy. Pass `None` for `approvals_repo` when the
+    /// deployment has no database.
+    pub fn with_approvals_repo(
+        approvals_repo: Option<Arc<dyn crate::db::repos::McpPendingApprovalsRepo>>,
+        url_validation_opts: UrlValidationOptions,
+    ) -> Self {
+        Self {
+            inner: Arc::new(McpServiceInner {
+                pool: DashMap::new(),
+                tools_cache: DashMap::new(),
+                tools_errors: DashMap::new(),
+                tools_fetch_locks: DashMap::new(),
+                tool_embeddings: DashMap::new(),
+                approvals_repo,
+                resolved_approvals: DashMap::new(),
+                url_validation_opts,
+            }),
+        }
+    }
+
+    /// Access the approvals repo, if persistence is wired up.
+    pub fn approvals_repo(&self) -> Option<&Arc<dyn crate::db::repos::McpPendingApprovalsRepo>> {
+        self.inner.approvals_repo.as_ref()
+    }
+
+    /// Record an approval that the resume path just resolved. The
+    /// matching executor will pick it up by `(org_id, call_id)` when
+    /// the pipeline runs moments later. Stale entries past
+    /// [`RESOLVED_APPROVAL_TTL`] are reaped on every write.
+    pub fn stash_resolved_approval(&self, org_id: uuid::Uuid, approval: ResolvedMcpApproval) {
+        let now = Instant::now();
+        self.inner
+            .resolved_approvals
+            .retain(|_, (_, ts)| now.duration_since(*ts) < RESOLVED_APPROVAL_TTL);
+        let key = (org_id, approval.call_id.clone());
+        self.inner.resolved_approvals.insert(key, (approval, now));
+    }
+
+    /// Remove and return the approval previously stashed for this
+    /// `(org_id, call_id)`. One-shot consumption — the executor calls
+    /// this exactly once per resumed call.
+    pub fn take_resolved_approval(
+        &self,
+        org_id: uuid::Uuid,
+        call_id: &str,
+    ) -> Option<ResolvedMcpApproval> {
+        self.inner
+            .resolved_approvals
+            .remove(&(org_id, call_id.to_string()))
+            .map(|(_, (a, _))| a)
+    }
+
+    /// Synchronous fast-path peek into the `tools/list` cache. Returns
+    /// the previously fetched catalog if and only if it is still fresh
+    /// (within [`TOOLS_CACHE_TTL`]). Used by the executor to surface
+    /// `mcp_list_tools` items at stream start without re-fetching —
+    /// the rewrite already populated the cache moments earlier.
+    pub fn cached_tools(
+        &self,
+        server_url: &str,
+        authorization: Option<&str>,
+        headers: &HashMap<String, String>,
+    ) -> Option<Arc<Vec<McpToolMeta>>> {
+        let key = McpEndpointKey::new(server_url, authorization, headers);
+        let entry = self.inner.tools_cache.get(&key)?;
+        if entry.refreshed_at.elapsed() < TOOLS_CACHE_TTL {
+            Some(entry.tools.clone())
+        } else {
+            None
+        }
+    }
+
+    /// Look up a cached tool-description embedding for `(model, text)`.
+    /// Returns `None` on miss or when the entry has aged past
+    /// [`TOOL_EMBEDDING_TTL`]. Used by Hadrian-side tool search to avoid
+    /// re-embedding a static deferred catalog on every request.
+    pub fn cached_embedding(&self, model: &str, text: &str) -> Option<Arc<Vec<f64>>> {
+        let key = EmbeddingCacheKey::new(model, text);
+        let entry = self.inner.tool_embeddings.get(&key)?;
+        if entry.1.elapsed() < TOOL_EMBEDDING_TTL {
+            Some(entry.0.clone())
+        } else {
+            None
+        }
+    }
+
+    /// Store a tool-description embedding for `(model, text)`. Reaps
+    /// entries past [`TOOL_EMBEDDING_TTL`] on write to bound growth.
+    pub fn cache_embedding(&self, model: &str, text: &str, embedding: Arc<Vec<f64>>) {
+        let now = Instant::now();
+        self.inner
+            .tool_embeddings
+            .retain(|_, (_, ts)| now.duration_since(*ts) < TOOL_EMBEDDING_TTL);
+        self.inner
+            .tool_embeddings
+            .insert(EmbeddingCacheKey::new(model, text), (embedding, now));
+    }
+
+    /// Seed the `tools/list` cache for an endpoint without hitting the
+    /// network. Used by [`super::preprocess::rewrite_mcp_tools`] when a
+    /// caller's request already carries an `mcp_list_tools` item for
+    /// the same `server_label` — the spec says the API doesn't refetch
+    /// while the catalog is in context, and priming the cache lets the
+    /// executor's downstream reads (`cached_tools`, `read_only_hint_for`)
+    /// see the same catalog the rewrite is using.
+    ///
+    /// The cache key folds the caller-supplied auth and headers in, so
+    /// a primed entry can only be observed by requests with matching
+    /// credentials — no cross-tenant poisoning.
+    pub fn prime_tools_cache(
+        &self,
+        server_url: &str,
+        authorization: Option<&str>,
+        headers: &HashMap<String, String>,
+        tools: Vec<McpToolMeta>,
+    ) {
+        let key = McpEndpointKey::new(server_url, authorization, headers);
+        self.inner.tools_cache.insert(
+            key,
+            CachedTools {
+                tools: Arc::new(tools),
+                refreshed_at: Instant::now(),
+            },
+        );
+    }
+
+    /// Get the cached tool catalog for an endpoint, calling
+    /// `tools/list` if the cache is empty or stale.
+    ///
+    /// Single-flighted per endpoint: concurrent first callers serialize
+    /// on a per-key lock so only one `tools/list` round-trip fires; the
+    /// others await the lock and then read the freshly primed cache.
+    pub async fn list_tools(
+        &self,
+        server_url: &str,
+        authorization: Option<&str>,
+        headers: &HashMap<String, String>,
+    ) -> Result<Arc<Vec<McpToolMeta>>, McpClientError> {
+        let key = McpEndpointKey::new(server_url, authorization, headers);
+
+        // Fast path: fresh cache entry.
+        if let Some(cached) = self.cached_fresh(&key) {
+            return Ok(cached);
+        }
+
+        // Single-flight: hold the per-endpoint fetch lock across the slow
+        // path so concurrent cold callers don't stampede the upstream.
+        let fetch_lock = self
+            .inner
+            .tools_fetch_locks
+            .entry(key.clone())
+            .or_insert_with(|| Arc::new(Mutex::new(())))
+            .clone();
+        let _guard = fetch_lock.lock().await;
+
+        // Re-check: another caller may have primed the cache while we
+        // waited for the lock.
+        if let Some(cached) = self.cached_fresh(&key) {
+            return Ok(cached);
+        }
+
+        // Slow path: fetch and cache. No mutex on the client — rmcp
+        // multiplexes concurrent requests over the session. On failure
+        // we stash the verbatim error so the executor can surface it on
+        // the `mcp_list_tools` item; on success we clear any stale error.
+        let tools = match self
+            .acquire_client(&key, server_url, authorization, headers)
+            .await
+        {
+            Ok(client) => client.list_tools().await,
+            Err(e) => Err(e),
+        };
+        let tools = match tools {
+            Ok(t) => t,
+            Err(e) => {
+                self.inner.tools_errors.insert(
+                    key,
+                    CachedToolsError {
+                        message: e.to_string(),
+                        at: Instant::now(),
+                    },
+                );
+                return Err(e);
+            }
+        };
+        self.inner.tools_errors.remove(&key);
+        let tools_arc = Arc::new(tools);
+        self.inner.tools_cache.insert(
+            key,
+            CachedTools {
+                tools: tools_arc.clone(),
+                refreshed_at: Instant::now(),
+            },
+        );
+        Ok(tools_arc)
+    }
+
+    /// The verbatim error from the most recent failed `tools/list` for an
+    /// endpoint, if one is still fresh (within [`TOOLS_CACHE_TTL`]). Used
+    /// by the executor to populate `mcp_list_tools.error` with the real
+    /// upstream message instead of a generic placeholder.
+    pub fn cached_tools_error(
+        &self,
+        server_url: &str,
+        authorization: Option<&str>,
+        headers: &HashMap<String, String>,
+    ) -> Option<String> {
+        let key = McpEndpointKey::new(server_url, authorization, headers);
+        let entry = self.inner.tools_errors.get(&key)?;
+        (entry.at.elapsed() < TOOLS_CACHE_TTL).then(|| entry.message.clone())
+    }
+
+    /// Fresh cache read shared by the fast path and the post-lock
+    /// re-check in [`Self::list_tools`].
+    fn cached_fresh(&self, key: &McpEndpointKey) -> Option<Arc<Vec<McpToolMeta>>> {
+        let entry = self.inner.tools_cache.get(key)?;
+        (entry.refreshed_at.elapsed() < TOOLS_CACHE_TTL).then(|| entry.tools.clone())
+    }
+
+    /// Invoke a tool. Uses a pooled client when available; otherwise
+    /// opens a fresh connection. Updates `last_used` on success.
+    pub async fn call_tool(
+        &self,
+        server_url: &str,
+        authorization: Option<&str>,
+        headers: &HashMap<String, String>,
+        tool_name: &str,
+        arguments: serde_json::Value,
+    ) -> Result<super::McpCallResult, McpClientError> {
+        let key = McpEndpointKey::new(server_url, authorization, headers);
+        let client = self
+            .acquire_client(&key, server_url, authorization, headers)
+            .await?;
+        // No lock held across the round-trip: concurrent calls to the
+        // same endpoint run in parallel over the shared rmcp session.
+        let result = client.call_tool(tool_name, arguments).await?;
+        // Touch the entry so eviction doesn't reap a busy connection.
+        if let Some(mut entry) = self.inner.pool.get_mut(&key) {
+            entry.last_used = Instant::now();
+        }
+        Ok(result)
+    }
+
+    /// Drop the pooled client for an endpoint, forcing the next call to
+    /// reconnect. Called after a `tools/call` times out: a timed-out
+    /// request is abandoned mid-flight without a protocol-level cancel,
+    /// leaving the rmcp session's JSON-RPC stream in an indeterminate
+    /// state. Reusing it risks hangs or mismatched responses, so the
+    /// safe move is to evict. Dropping the last `Arc<McpClient>` runs its
+    /// `Drop`, which issues `RunningService::cancel` — a clean session
+    /// shutdown. The tools cache is left intact (the catalog is still
+    /// valid; only the live connection is suspect).
+    pub fn evict_endpoint(
+        &self,
+        server_url: &str,
+        authorization: Option<&str>,
+        headers: &HashMap<String, String>,
+    ) {
+        let key = McpEndpointKey::new(server_url, authorization, headers);
+        self.inner.pool.remove(&key);
+    }
+
+    /// Drop entries idle past their TTL across every per-endpoint map.
+    /// Called opportunistically on every `acquire_client`; no background
+    /// task. The endpoint key folds in `server_url + sha256(auth||headers)`,
+    /// so without this a caller rotating a token/header/path would mint
+    /// unbounded permanent entries (each holding a full tool catalog).
+    fn reap_expired(&self) {
+        let now = Instant::now();
+        self.inner
+            .pool
+            .retain(|_, v| now.duration_since(v.last_used) < CLIENT_IDLE_TTL);
+        self.inner
+            .tools_cache
+            .retain(|_, v| now.duration_since(v.refreshed_at) < TOOLS_CACHE_TTL);
+        self.inner
+            .tools_errors
+            .retain(|_, v| now.duration_since(v.at) < TOOLS_CACHE_TTL);
+        // Single-flight guards have no TTL; drop those nobody is holding
+        // (strong_count == 1 means only the map references it, so no fetch
+        // is in flight). A later fetch re-creates the lock atomically via
+        // get-or-insert, so dropping an idle guard is safe.
+        self.inner
+            .tools_fetch_locks
+            .retain(|_, v| Arc::strong_count(v) > 1);
+    }
+
+    /// Get or open a client for the given endpoint key.
+    async fn acquire_client(
+        &self,
+        key: &McpEndpointKey,
+        server_url: &str,
+        authorization: Option<&str>,
+        headers: &HashMap<String, String>,
+    ) -> Result<Arc<McpClient>, McpClientError> {
+        self.reap_expired();
+
+        // SSRF guard FIRST, before the pool lookup. A warm pool entry must
+        // not let a caller-supplied URL skip validation, and re-validating
+        // is cheap relative to the call it precedes (it also re-resolves
+        // DNS, catching rebinding to a private IP after warm-up). The
+        // cache key isn't poisoned because we only stash on success.
+        let validated = validate_base_url_opts(server_url, self.inner.url_validation_opts)
+            .map_err(|e| McpClientError::Transport(format!("blocked server_url: {e}")))?;
+
+        // Try the pool. We can't return early from inside the closure, so
+        // clone the Arc after the lookup.
+        if let Some(mut entry) = self.inner.pool.get_mut(key) {
+            entry.last_used = Instant::now();
+            return Ok(entry.client.clone());
+        }
+
+        // Cold path: open a fresh connection and stash it. Pin the HTTP
+        // client to the IPs we just validated so reqwest can't re-resolve
+        // the host to a private/loopback/metadata address between the
+        // SSRF check and the actual connection (DNS-rebinding TOCTOU).
+        let client = McpClient::connect(
+            server_url,
+            &validated.host,
+            &validated.addrs,
+            authorization.map(str::to_string),
+            headers.clone(),
+        )
+        .await?;
+        let arc = Arc::new(client);
+        self.inner.pool.insert(
+            key.clone(),
+            PooledClient {
+                client: arc.clone(),
+                last_used: Instant::now(),
+            },
+        );
+        Ok(arc)
+    }
+}
+
+impl Default for McpService {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn endpoint_key_differs_on_auth() {
+        let h = HashMap::new();
+        let a = McpEndpointKey::new("https://x", Some("token-a"), &h);
+        let b = McpEndpointKey::new("https://x", Some("token-b"), &h);
+        assert_ne!(a, b);
+        assert_eq!(a.server_url, b.server_url);
+    }
+
+    #[test]
+    fn embedding_cache_round_trips_and_keys_on_content() {
+        let svc = McpService::new();
+        assert!(svc.cached_embedding("m1", "search jira").is_none());
+
+        let v = Arc::new(vec![0.1, 0.2, 0.3]);
+        svc.cache_embedding("m1", "search jira", v.clone());
+        assert_eq!(
+            svc.cached_embedding("m1", "search jira").as_deref(),
+            Some(&*v)
+        );
+
+        // Different text → miss (content-addressed).
+        assert!(svc.cached_embedding("m1", "create page").is_none());
+        // Different model → miss (vectors aren't comparable across models).
+        assert!(svc.cached_embedding("m2", "search jira").is_none());
+    }
+
+    #[test]
+    fn endpoint_key_stable_across_header_order() {
+        let mut h1 = HashMap::new();
+        h1.insert("X-Region".to_string(), "us".to_string());
+        h1.insert("X-Workspace".to_string(), "team".to_string());
+
+        let mut h2 = HashMap::new();
+        h2.insert("X-Workspace".to_string(), "team".to_string());
+        h2.insert("X-Region".to_string(), "us".to_string());
+
+        let a = McpEndpointKey::new("https://x", Some("t"), &h1);
+        let b = McpEndpointKey::new("https://x", Some("t"), &h2);
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn endpoint_key_distinguishes_no_auth_from_empty_auth() {
+        let h = HashMap::new();
+        let none = McpEndpointKey::new("https://x", None, &h);
+        let empty = McpEndpointKey::new("https://x", Some(""), &h);
+        // Both have empty bearer hash inputs; treat as equivalent —
+        // the pool dedupes correctly either way.
+        assert_eq!(none, empty);
+    }
+}
diff --git a/src/services/mcp/tool_search/mod.rs b/src/services/mcp/tool_search/mod.rs
new file mode 100644
index 0000000..0563231
--- /dev/null
+++ b/src/services/mcp/tool_search/mod.rs
@@ -0,0 +1,743 @@
+//! Hadrian-side tool search for deferred MCP tools (`defer_loading`).
+//!
+//! Under `hadrian_hosted`, when a request marks an `mcp` tool entry with
+//! `defer_loading: true` (and does not opt into native passthrough), the
+//! rewrite keeps that server's catalog out of the prompt and exposes a
+//! single `tool_search` function tool instead. The model calls it with a
+//! query; [`ToolSearchExecutor`] ranks the retained catalog locally
+//! ([`ranker`]), emits spec-shaped `tool_search_call` / `tool_search_output`
+//! items, and injects the matched per-tool function definitions into the
+//! continuation so the model can actually call them next turn.
+//!
+//! This makes `defer_loading` work behind every provider — not just the
+//! ones with native tool search — mirroring OpenAI's wire contract.
+
+pub mod ranker;
+
+use std::sync::{
+    Arc, Mutex,
+    atomic::{AtomicU64, Ordering},
+};
+
+use async_trait::async_trait;
+use bytes::Bytes;
+pub use ranker::{
+    HybridRanker, LexicalRanker, RankError, RankedTool, SemanticRanker, ToolSearchRanker,
+};
+use serde_json::Value;
+
+use super::{McpService, McpToolMeta, preprocess};
+use crate::{
+    api_types::responses::{
+        CreateResponsesPayload, FunctionCallOutput, FunctionCallOutputType, McpTool,
+        ResponsesInputItem, ResponsesToolChoice, ResponsesToolDefinition, ToolSearchRankerKind,
+    },
+    cache::EmbeddingService,
+    config::ToolSearchConfig,
+    services::server_tools::{
+        DetectedToolCall, ServerExecutedTool, ToolCallResult, ToolContext, ToolError,
+        ToolExecutionHandle,
+    },
+};
+
+/// Name of the synthetic function tool the rewrite injects for deferred
+/// MCP servers. The model calls it to discover tools; [`ToolSearchExecutor`]
+/// intercepts the call. Distinct from the `mcp_<label>__<tool>` shape so
+/// detection is unambiguous.
+pub const TOOL_SEARCH_FUNCTION_NAME: &str = "tool_search";
+
+/// The [`ServerExecutedTool`] that answers `tool_search` calls locally:
+/// ranks the deferred MCP catalog, emits `tool_search_call` /
+/// `tool_search_output` items, and injects the matched per-tool function
+/// definitions into the continuation so the model can call them.
+///
+/// Constructed once per request from the *original* payload (before the
+/// rewrite strips `mcp` entries), alongside [`super::McpExecutor`].
+pub struct ToolSearchExecutor {
+    service: McpService,
+    /// The deferred-default MCP servers, captured before rewrite.
+    deferred: Vec<McpTool>,
+    /// Ranking strategy resolved at construction from config + per-request
+    /// override + embedding availability.
+    ranker: Arc<dyn ToolSearchRanker>,
+    max_results: usize,
+    score_threshold: f64,
+    output_index: AtomicU64,
+    sequence_number: AtomicU64,
+    /// Function tools discovered by `execute`, awaiting injection into the
+    /// continuation payload by `apply_to_continuation`.
+    pending_tools: Mutex<Vec<ResponsesToolDefinition>>,
+    suppressor: crate::services::server_tools::FunctionCallSuppressor,
+}
+
+impl ToolSearchExecutor {
+    /// Build the executor. Returns one even when no server is deferred;
+    /// [`Self::is_enabled_for`] gates registration.
+    pub fn new(
+        service: McpService,
+        original_payload: &CreateResponsesPayload,
+        cfg: &ToolSearchConfig,
+        embeddings: Option<Arc<EmbeddingService>>,
+    ) -> Self {
+        let forced = mcp_choice_label(original_payload);
+        let deferred: Vec<McpTool> = original_payload
+            .tools
+            .as_ref()
+            .map(|tools| {
+                tools
+                    .iter()
+                    .filter_map(|t| t.as_mcp())
+                    .filter(|m| {
+                        m.defer_loading == Some(true)
+                            && m.defer_loading_passthrough != Some(true)
+                            && forced.as_deref() != Some(m.server_label.as_str())
+                    })
+                    .cloned()
+                    .collect()
+            })
+            .unwrap_or_default();
+
+        // Per-request ranker override (a caller-supplied `tool_search`
+        // tool entry) wins over the deployment default.
+        let request_override = original_payload
+            .tools
+            .as_ref()
+            .and_then(|tools| tools.iter().find_map(|t| t.as_tool_search()))
+            .and_then(|ts| ts.ranker);
+        let effective = request_override.unwrap_or(cfg.ranker);
+        let ranker = build_ranker(effective, embeddings, &service, cfg.rrf_k);
+
+        Self {
+            service,
+            deferred,
+            ranker,
+            max_results: cfg.max_results,
+            score_threshold: cfg.score_threshold,
+            output_index: AtomicU64::new(0),
+            sequence_number: AtomicU64::new(0),
+            pending_tools: Mutex::new(Vec::new()),
+            suppressor: crate::services::server_tools::FunctionCallSuppressor::new(),
+        }
+    }
+
+    /// True iff at least one server is deferred via Hadrian-side search.
+    pub fn has_deferred(&self) -> bool {
+        !self.deferred.is_empty()
+    }
+
+    fn next_seq(&self) -> u64 {
+        self.sequence_number.fetch_add(1, Ordering::Relaxed)
+    }
+
+    /// Collect the searchable catalog: every allowed, valid tool from the
+    /// deferred servers, optionally narrowed to `server_label`. Returns
+    /// parallel vectors of metadata (for the ranker) and the owning
+    /// `McpTool` index (for rendering the function definition).
+    fn candidates(&self, server_label: Option<&str>) -> (Vec<McpToolMeta>, Vec<usize>) {
+        let mut metas = Vec::new();
+        let mut owners = Vec::new();
+        for (idx, mcp) in self.deferred.iter().enumerate() {
+            if let Some(want) = server_label
+                && want != mcp.server_label
+            {
+                continue;
+            }
+            let Some(server_url) = mcp.server_url.as_deref() else {
+                continue;
+            };
+            let headers = mcp.headers.clone().unwrap_or_default();
+            let Some(catalog) =
+                self.service
+                    .cached_tools(server_url, mcp.authorization.as_deref(), &headers)
+            else {
+                continue;
+            };
+            for meta in catalog.iter() {
+                if preprocess::is_allowed(meta, mcp.allowed_tools.as_ref())
+                    && preprocess::is_valid_tool_name(&meta.name)
+                {
+                    metas.push(meta.clone());
+                    owners.push(idx);
+                }
+            }
+        }
+        (metas, owners)
+    }
+}
+
+/// The `server_label` an `mcp` `tool_choice` pins, if any.
+fn mcp_choice_label(payload: &CreateResponsesPayload) -> Option<String> {
+    match payload.tool_choice.as_ref()? {
+        ResponsesToolChoice::Mcp(c) => Some(c.server_label.clone()),
+        _ => None,
+    }
+}
+
+/// Select a ranker from the effective strategy and embedding
+/// availability. `hybrid`/`semantic` fall back to lexical (with a warning)
+/// when no embedding provider resolved — the request still succeeds.
+fn build_ranker(
+    kind: ToolSearchRankerKind,
+    embeddings: Option<Arc<EmbeddingService>>,
+    service: &McpService,
+    rrf_k: u32,
+) -> Arc<dyn ToolSearchRanker> {
+    match (kind, embeddings) {
+        (ToolSearchRankerKind::Lexical, _) => Arc::new(LexicalRanker),
+        (ToolSearchRankerKind::Semantic, Some(e)) => {
+            Arc::new(SemanticRanker::new(e, service.clone()))
+        }
+        (ToolSearchRankerKind::Hybrid, Some(e)) => Arc::new(HybridRanker::new(
+            SemanticRanker::new(e, service.clone()),
+            rrf_k,
+        )),
+        (kind, None) => {
+            tracing::warn!(
+                ?kind,
+                "tool search requested {kind:?} ranking but no embedding provider is \
+                 configured; falling back to lexical ranking"
+            );
+            Arc::new(LexicalRanker)
+        }
+    }
+}
+
+#[async_trait]
+impl ServerExecutedTool for ToolSearchExecutor {
+    fn name(&self) -> &'static str {
+        TOOL_SEARCH_FUNCTION_NAME
+    }
+
+    fn is_enabled_for(&self, _payload: &CreateResponsesPayload) -> bool {
+        self.has_deferred()
+    }
+
+    fn detect(&self, event: &[u8], _ctx: &ToolContext) -> Vec<DetectedToolCall> {
+        let Some(data) = sse_data(event) else {
+            return Vec::new();
+        };
+        let trimmed = data.trim();
+        if trimmed == "[DONE]" {
+            return Vec::new();
+        }
+        let Ok(json) = serde_json::from_str::<Value>(trimmed) else {
+            return Vec::new();
+        };
+        if json.get("type").and_then(|t| t.as_str()) != Some("response.output_item.done") {
+            return Vec::new();
+        }
+        let Some(item) = json.get("item") else {
+            return Vec::new();
+        };
+        if item.get("type").and_then(|t| t.as_str()) != Some("function_call") {
+            return Vec::new();
+        }
+        if item.get("name").and_then(|v| v.as_str()) != Some(TOOL_SEARCH_FUNCTION_NAME) {
+            return Vec::new();
+        }
+        let call_id = match item
+            .get("call_id")
+            .or_else(|| item.get("id"))
+            .and_then(|v| v.as_str())
+        {
+            Some(id) => id.to_string(),
+            None => {
+                // A `tool_search` function-call event with neither
+                // `call_id` nor `id` can't be paired to a continuation;
+                // fabricating a placeholder would let two such calls
+                // collide on the join key. Skip it.
+                tracing::warn!(
+                    "tool_search function-call event missing both `call_id` and `id`; \
+                     ignoring (continuation cannot be paired)"
+                );
+                return Vec::new();
+            }
+        };
+        let args_str = item
+            .get("arguments")
+            .and_then(|v| v.as_str())
+            .unwrap_or("{}");
+        let arguments: Value = serde_json::from_str(args_str).unwrap_or_else(|e| {
+            tracing::warn!(
+                error = %e,
+                arguments = %args_str,
+                "tool_search call arguments are not valid JSON; treating as empty"
+            );
+            Value::Null
+        });
+        vec![DetectedToolCall {
+            tool_name: TOOL_SEARCH_FUNCTION_NAME,
+            call_id,
+            arguments,
+        }]
+    }
+
+    async fn execute(
+        &self,
+        call: DetectedToolCall,
+        _ctx: &ToolContext,
+    ) -> Result<ToolExecutionHandle, ToolError> {
+        let query = call
+            .arguments
+            .get("query")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string();
+        let server_label = call
+            .arguments
+            .get("server_label")
+            .and_then(|v| v.as_str())
+            .map(str::to_string);
+
+        let (metas, owners) = self.candidates(server_label.as_deref());
+
+        // Rank, then apply the score floor and result cap. The floor only
+        // applies to rankers whose scores are normalized to `0.0..=1.0`
+        // (lexical/semantic); hybrid RRF scores are ranking-only, so
+        // applying a `0..1` threshold to them would drop every result.
+        let mut ranked = self
+            .ranker
+            .rank(&query, &metas)
+            .await
+            .map_err(|e| ToolError::ExecutionFailed(e.to_string()))?;
+        if self.ranker.scores_are_normalized() {
+            ranked.retain(|r| r.score >= self.score_threshold);
+        }
+        ranked.truncate(self.max_results);
+
+        // Render the matched tools as their `mcp_<label>__<tool>` function
+        // definitions: one copy for the `tool_search_output` item, one for
+        // injection into the continuation payload.
+        let mut tool_defs_json: Vec<Value> = Vec::with_capacity(ranked.len());
+        let mut summary: Vec<Value> = Vec::with_capacity(ranked.len());
+        let mut injected: Vec<ResponsesToolDefinition> = Vec::with_capacity(ranked.len());
+        for r in &ranked {
+            let meta = &metas[r.index];
+            let mcp = &self.deferred[owners[r.index]];
+            // A discovered tool we can't render (server-controlled schema
+            // that won't build, or won't serialize) would land as a null
+            // hole in `tool_search_output.tools`; skip it entirely (call +
+            // injection) and log rather than emit a malformed item.
+            let def = match preprocess::build_function_tool(mcp, meta, false) {
+                Ok(d) => d,
+                Err(e) => {
+                    tracing::error!(
+                        tool = %meta.name,
+                        server_label = %mcp.server_label,
+                        error = %e,
+                        "Failed to build discovered MCP tool definition; omitting from tool_search_output"
+                    );
+                    continue;
+                }
+            };
+            let def_json = match serde_json::to_value(&def) {
+                Ok(v) => v,
+                Err(e) => {
+                    tracing::error!(
+                        tool = %meta.name,
+                        server_label = %mcp.server_label,
+                        error = %e,
+                        "Failed to serialize discovered MCP tool definition; omitting from tool_search_output"
+                    );
+                    continue;
+                }
+            };
+            tool_defs_json.push(def_json);
+            summary.push(serde_json::json!({
+                "name": preprocess::synthesize_function_name(&mcp.server_label, &meta.name),
+                "description": meta.description.clone().unwrap_or_default(),
+            }));
+            injected.push(def);
+        }
+
+        if let Ok(mut pending) = self.pending_tools.lock() {
+            pending.extend(injected);
+        }
+
+        // Emit the spec-shaped lifecycle: a `tool_search_call` then a
+        // `tool_search_output` carrying the loaded definitions.
+        let call_index = self.output_index.fetch_add(1, Ordering::Relaxed);
+        let out_index = self.output_index.fetch_add(1, Ordering::Relaxed);
+        let call_item_id = next_item_id("ts");
+        let out_item_id = next_item_id("tso");
+        // Per the tool-search spec, server-executed search reports
+        // `call_id: null` (a client-executed search would echo the id the
+        // caller assigned). The model's underlying `tool_search`
+        // function-call id is still used for the provider continuation
+        // below — it's just not surfaced on these spec items.
+        let call_item = |status: &str| {
+            serde_json::json!({
+                "type": "tool_search_call",
+                "id": call_item_id,
+                "call_id": Value::Null,
+                "execution": "server",
+                "arguments": call.arguments,
+                "status": status,
+            })
+        };
+        let output_item = |status: &str| {
+            serde_json::json!({
+                "type": "tool_search_output",
+                "id": out_item_id,
+                "call_id": Value::Null,
+                "execution": "server",
+                "tools": tool_defs_json,
+                "status": status,
+            })
+        };
+        let events = vec![
+            sse_output_item(
+                "response.output_item.added",
+                call_index,
+                self.next_seq(),
+                call_item("in_progress"),
+            ),
+            sse_output_item(
+                "response.output_item.done",
+                call_index,
+                self.next_seq(),
+                call_item("completed"),
+            ),
+            sse_output_item(
+                "response.output_item.added",
+                out_index,
+                self.next_seq(),
+                output_item("in_progress"),
+            ),
+            sse_output_item(
+                "response.output_item.done",
+                out_index,
+                self.next_seq(),
+                output_item("completed"),
+            ),
+        ];
+
+        // The function-call output the model reads next turn: the list of
+        // tools the search surfaced (now also callable via injection).
+        let output_text = serde_json::json!({ "tools": summary }).to_string();
+        let continuation = ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+            type_: FunctionCallOutputType::FunctionCallOutput,
+            id: None,
+            call_id: call.call_id.clone(),
+            output: output_text,
+            status: None,
+        });
+        let result = ToolCallResult {
+            call_id: call.call_id,
+            continuation_items: vec![continuation],
+        };
+
+        Ok(ToolExecutionHandle {
+            events: Box::pin(futures_util::stream::iter(events)),
+            result: Box::pin(async move { Ok(result) }),
+        })
+    }
+
+    fn apply_to_continuation(
+        &self,
+        payload: &mut CreateResponsesPayload,
+        results: &[ToolCallResult],
+        is_final_iteration: bool,
+    ) {
+        // Append the tool_search function-call outputs.
+        let outputs: Vec<ResponsesInputItem> = results
+            .iter()
+            .flat_map(|r| r.continuation_items.clone())
+            .collect();
+        if !outputs.is_empty() {
+            use crate::api_types::responses::ResponsesInput;
+            match payload.input {
+                Some(ResponsesInput::Items(ref mut items)) => items.extend(outputs),
+                Some(ResponsesInput::Text(ref text)) => {
+                    let text = text.clone();
+                    let mut items = vec![ResponsesInputItem::EasyMessage(
+                        crate::api_types::responses::EasyInputMessage {
+                            type_: None,
+                            role: crate::api_types::responses::EasyInputMessageRole::User,
+                            content: crate::api_types::responses::EasyInputMessageContent::Text(
+                                text,
+                            ),
+                        },
+                    )];
+                    items.extend(outputs);
+                    payload.input = Some(ResponsesInput::Items(items));
+                }
+                None => payload.input = Some(ResponsesInput::Items(outputs)),
+            }
+        }
+
+        // Inject the discovered function definitions so the model can call
+        // them on its next turn. They persist on the continuation payload;
+        // the per-iteration rewrite leaves Function tools untouched. Dedup
+        // against names already present (a tool found by an earlier search).
+        let discovered = self
+            .pending_tools
+            .lock()
+            .map(|mut p| std::mem::take(&mut *p))
+            .unwrap_or_default();
+        if !discovered.is_empty() {
+            let tools = payload.tools.get_or_insert_with(Vec::new);
+            let existing: std::collections::HashSet<String> = tools
+                .iter()
+                .filter_map(|t| match t {
+                    ResponsesToolDefinition::Function(f) => Some(f.name.clone()),
+                    _ => None,
+                })
+                .collect();
+            for def in discovered {
+                if let ResponsesToolDefinition::Function(f) = &def
+                    && existing.contains(&f.name)
+                {
+                    continue;
+                }
+                tools.push(def);
+            }
+        }
+
+        // On the final iteration, drop the `tool_search` tool so the model
+        // must produce a text answer. (The MCP executor strips the
+        // discovered `mcp_<label>__<tool>` functions in its own pass.)
+        if is_final_iteration && let Some(ref mut tools) = payload.tools {
+            tools.retain(|t| !t.is_tool_search());
+            tools.retain(|t| match t {
+                ResponsesToolDefinition::Function(f) => f.name != TOOL_SEARCH_FUNCTION_NAME,
+                _ => true,
+            });
+            if tools.is_empty() {
+                payload.tools = None;
+            }
+        }
+    }
+
+    fn transform_event(&self, event: Bytes) -> Bytes {
+        // Hide the raw `tool_search` function-call plumbing; the
+        // spec-shaped `tool_search_call` / `_output` items we emit replace it.
+        self.suppressor
+            .suppress(event, |name| name == TOOL_SEARCH_FUNCTION_NAME)
+    }
+}
+
+/// Concatenate the `data:` fields of one SSE event. Mirrors the helper in
+/// [`super::executor`] (kept local to avoid widening its visibility).
+fn sse_data(event: &[u8]) -> Option<String> {
+    let text = std::str::from_utf8(event).ok()?;
+    let mut parts: Vec<&str> = Vec::new();
+    for line in text.split('\n') {
+        let line = line.strip_suffix('\r').unwrap_or(line);
+        if line.is_empty() || line.starts_with(':') {
+            continue;
+        }
+        if let Some(rest) = line.strip_prefix("data:") {
+            parts.push(rest.strip_prefix(' ').unwrap_or(rest));
+        }
+    }
+    (!parts.is_empty()).then(|| parts.join("\n"))
+}
+
+fn sse_output_item(
+    event_type: &str,
+    output_index: u64,
+    sequence_number: u64,
+    item: Value,
+) -> Bytes {
+    let payload = serde_json::json!({
+        "type": event_type,
+        "output_index": output_index,
+        "sequence_number": sequence_number,
+        "item": item,
+    });
+    let body = serde_json::to_string(&payload).unwrap_or_else(|e| {
+        tracing::error!(
+            event_type,
+            error = %e,
+            "Failed to serialize tool_search SSE event; emitting empty frame"
+        );
+        String::new()
+    });
+    Bytes::from(format!("data: {body}\n\n"))
+}
+
+fn next_item_id(prefix: &str) -> String {
+    format!("{prefix}_{}", uuid::Uuid::new_v4().simple())
+}
+
+#[cfg(test)]
+mod tests {
+    use futures_util::StreamExt;
+
+    use super::*;
+    use crate::api_types::responses::ResponsesInput;
+
+    const URL: &str = "http://127.0.0.1:1/mcp";
+
+    fn meta(name: &str, desc: &str) -> McpToolMeta {
+        McpToolMeta {
+            name: name.to_string(),
+            description: Some(desc.to_string()),
+            input_schema: serde_json::json!({"type": "object"}),
+            annotations: None,
+        }
+    }
+
+    /// Service with a primed deferred catalog, plus an executor over a
+    /// single deferred server. Lexical ranking (no embeddings).
+    fn executor_with_catalog() -> ToolSearchExecutor {
+        let service = McpService::new();
+        service.prime_tools_cache(
+            URL,
+            None,
+            &std::collections::HashMap::new(),
+            vec![
+                meta("jira_search", "Search Jira issues by query"),
+                meta("confluence_create_page", "Create a Confluence page"),
+            ],
+        );
+        let payload: CreateResponsesPayload = serde_json::from_value(serde_json::json!({
+            "tools": [{
+                "type": "mcp",
+                "server_label": "atlassian",
+                "server_url": URL,
+                "defer_loading": true,
+            }]
+        }))
+        .unwrap();
+        ToolSearchExecutor::new(service, &payload, &ToolSearchConfig::default(), None)
+    }
+
+    fn tool_search_call_event(call_id: &str, args: serde_json::Value) -> Vec<u8> {
+        let ev = serde_json::json!({
+            "type": "response.output_item.done",
+            "item": {
+                "type": "function_call",
+                "id": "fc_1",
+                "call_id": call_id,
+                "name": TOOL_SEARCH_FUNCTION_NAME,
+                "arguments": args.to_string(),
+            }
+        });
+        format!("data: {}\n\n", ev).into_bytes()
+    }
+
+    fn ctx() -> ToolContext {
+        ToolContext {
+            original_payload: serde_json::from_value(serde_json::json!({})).unwrap(),
+        }
+    }
+
+    #[test]
+    fn enabled_only_with_deferred_server() {
+        let exec = executor_with_catalog();
+        assert!(exec.has_deferred());
+        assert!(exec.is_enabled_for(&serde_json::from_value(serde_json::json!({})).unwrap()));
+    }
+
+    #[test]
+    fn detect_matches_tool_search_function_call() {
+        let exec = executor_with_catalog();
+        let ev = tool_search_call_event("call_1", serde_json::json!({"query": "jira"}));
+        let calls = exec.detect(&ev, &ctx());
+        assert_eq!(calls.len(), 1);
+        assert_eq!(calls[0].tool_name, TOOL_SEARCH_FUNCTION_NAME);
+        assert_eq!(calls[0].call_id, "call_1");
+        assert_eq!(calls[0].arguments["query"], "jira");
+    }
+
+    #[test]
+    fn detect_ignores_other_function_calls() {
+        let exec = executor_with_catalog();
+        let ev = serde_json::json!({
+            "type": "response.output_item.done",
+            "item": {"type": "function_call", "id": "x", "call_id": "c", "name": "mcp_atlassian__jira_search", "arguments": "{}"}
+        });
+        let calls = exec.detect(format!("data: {ev}\n\n").as_bytes(), &ctx());
+        assert!(calls.is_empty());
+    }
+
+    #[tokio::test]
+    async fn execute_emits_call_and_output_items_and_stashes_defs() {
+        let exec = executor_with_catalog();
+        let call = DetectedToolCall {
+            tool_name: TOOL_SEARCH_FUNCTION_NAME,
+            call_id: "call_1".to_string(),
+            arguments: serde_json::json!({"query": "search jira issues"}),
+        };
+        let handle = exec.execute(call, &ctx()).await.expect("execute");
+        let events: Vec<Bytes> = handle.events.collect().await;
+        let joined: String = events
+            .iter()
+            .map(|b| String::from_utf8_lossy(b).into_owned())
+            .collect();
+        assert!(joined.contains("\"type\":\"tool_search_call\""));
+        assert!(joined.contains("\"type\":\"tool_search_output\""));
+        // The jira tool should have matched and been rendered.
+        assert!(joined.contains("mcp_atlassian__jira_search"));
+
+        // Result carries a function_call_output for the call.
+        let result = handle.result.await.expect("result");
+        assert_eq!(result.call_id, "call_1");
+        assert_eq!(result.continuation_items.len(), 1);
+
+        // The discovered function def is stashed for injection.
+        assert!(!exec.pending_tools.lock().unwrap().is_empty());
+    }
+
+    #[tokio::test]
+    async fn apply_to_continuation_injects_discovered_tools_and_output() {
+        let exec = executor_with_catalog();
+        let call = DetectedToolCall {
+            tool_name: TOOL_SEARCH_FUNCTION_NAME,
+            call_id: "call_1".to_string(),
+            arguments: serde_json::json!({"query": "search jira"}),
+        };
+        let handle = exec.execute(call, &ctx()).await.unwrap();
+        let _ = handle.events.collect::<Vec<_>>().await;
+        let result = handle.result.await.unwrap();
+
+        let mut payload: CreateResponsesPayload = serde_json::from_value(serde_json::json!({
+            "input": [],
+            "tools": [{"type": "mcp", "server_label": "atlassian", "server_url": URL, "defer_loading": true}]
+        }))
+        .unwrap();
+        exec.apply_to_continuation(&mut payload, std::slice::from_ref(&result), false);
+
+        let tools = payload.tools.as_ref().unwrap();
+        // Discovered function tool injected.
+        assert!(tools.iter().any(|t| matches!(t, ResponsesToolDefinition::Function(f) if f.name == "mcp_atlassian__jira_search")));
+        // function_call_output appended to input.
+        if let Some(ResponsesInput::Items(items)) = &payload.input {
+            assert!(items.iter().any(
+                |i| matches!(i, ResponsesInputItem::FunctionCallOutput(o) if o.call_id == "call_1")
+            ));
+        } else {
+            panic!("expected items input");
+        }
+    }
+
+    #[tokio::test]
+    async fn final_iteration_strips_tool_search_tool() {
+        let exec = executor_with_catalog();
+        let mut payload: CreateResponsesPayload = serde_json::from_value(serde_json::json!({
+            "input": [],
+            "tools": [
+                {"type": "tool_search"},
+                {"type": "function", "name": "mcp_atlassian__jira_search", "parameters": {"type": "object"}}
+            ]
+        }))
+        .unwrap();
+        exec.apply_to_continuation(&mut payload, &[], true);
+        // tool_search tool removed; the mcp_ function remains (the MCP
+        // executor strips those in its own pass).
+        let tools = payload.tools.unwrap();
+        assert!(!tools.iter().any(|t| t.is_tool_search()));
+        assert!(tools.iter().any(|t| matches!(t, ResponsesToolDefinition::Function(f) if f.name == "mcp_atlassian__jira_search")));
+    }
+
+    #[test]
+    fn build_ranker_falls_back_to_lexical_without_embeddings() {
+        // hybrid default + no embeddings → lexical (no panic, returns a ranker).
+        let service = McpService::new();
+        let r = build_ranker(ToolSearchRankerKind::Hybrid, None, &service, 60);
+        // Smoke: it ranks without embeddings.
+        let _ = r;
+    }
+}
diff --git a/src/services/mcp/tool_search/ranker.rs b/src/services/mcp/tool_search/ranker.rs
new file mode 100644
index 0000000..9ca3199
--- /dev/null
+++ b/src/services/mcp/tool_search/ranker.rs
@@ -0,0 +1,481 @@
+//! Ranking strategies for Hadrian-side tool search.
+//!
+//! A [`ToolSearchRanker`] scores a deferred MCP catalog against the
+//! model's search query and returns the tools in descending relevance
+//! order. The executor then applies the configured score threshold and
+//! result cap. Three strategies ship:
+//!
+//! - [`LexicalRanker`] — token overlap with substring matching over the
+//!   tool name, description, annotation title, and schema parameter
+//!   names/descriptions. No dependency; always available. Returns only
+//!   tools with non-zero overlap.
+//! - [`SemanticRanker`] — embedding cosine similarity, reusing Hadrian's
+//!   [`EmbeddingService`] and the [`McpService`] embedding cache. Returns
+//!   every tool scored.
+//! - [`HybridRanker`] — fuses the two with Reciprocal Rank Fusion (RRF),
+//!   the default when an embedding provider is available.
+//!
+//! OpenAI's hosted tool search is semantic; mirroring that, `hybrid` /
+//! `semantic` are preferred and `lexical` is the dependency-free
+//! fallback when no embedding provider resolves.
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use super::super::{McpService, McpToolMeta};
+use crate::cache::EmbeddingService;
+
+/// A scored tool: the `index` into the catalog slice passed to
+/// [`ToolSearchRanker::rank`], plus a relevance `score`. Lexical and
+/// semantic scores are in `0.0..=1.0`; hybrid RRF scores are a smaller
+/// ranking-only range (see [`HybridRanker`]).
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct RankedTool {
+    pub index: usize,
+    pub score: f64,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum RankError {
+    #[error("embedding failed: {0}")]
+    Embedding(String),
+}
+
+/// Ranks a deferred MCP catalog against a search query, best first.
+#[async_trait]
+pub trait ToolSearchRanker: Send + Sync {
+    async fn rank(&self, query: &str, tools: &[McpToolMeta]) -> Result<Vec<RankedTool>, RankError>;
+
+    /// Whether [`Self::rank`] returns scores normalized to `0.0..=1.0`,
+    /// so the configured `score_threshold` is meaningful against them.
+    /// Lexical and semantic scores are normalized; hybrid RRF scores are
+    /// a ranking-only quantity (a tiny range like `0.0..≈0.033`) and
+    /// return `false` so the executor skips the threshold rather than
+    /// dropping every result. Defaults to `true`.
+    fn scores_are_normalized(&self) -> bool {
+        true
+    }
+}
+
+/// Text representation of a tool used for both lexical and semantic
+/// scoring: name, description, the annotation `title` if present, and
+/// the input-schema parameter names + their descriptions. Indexing the
+/// schema matters for tools whose discriminating keywords live in their
+/// parameters (e.g. a generic `search` tool with a `repository` param)
+/// rather than the name/description.
+fn tool_text(meta: &McpToolMeta) -> String {
+    let mut s = meta.name.clone();
+    if let Some(d) = meta.description.as_deref().filter(|d| !d.is_empty()) {
+        s.push('\n');
+        s.push_str(d);
+    }
+    if let Some(title) = meta
+        .annotations
+        .as_ref()
+        .and_then(|a| a.get("title"))
+        .and_then(|v| v.as_str())
+    {
+        s.push('\n');
+        s.push_str(title);
+    }
+    if let Some(props) = meta
+        .input_schema
+        .get("properties")
+        .and_then(|p| p.as_object())
+    {
+        for (name, schema) in props {
+            s.push('\n');
+            s.push_str(name);
+            if let Some(d) = schema.get("description").and_then(|v| v.as_str()) {
+                s.push(' ');
+                s.push_str(d);
+            }
+        }
+    }
+    s
+}
+
+/// Lowercase alphanumeric tokens.
+fn tokenize(s: &str) -> Vec<String> {
+    s.to_lowercase()
+        .split(|c: char| !c.is_alphanumeric())
+        .filter(|t| !t.is_empty())
+        .map(str::to_string)
+        .collect()
+}
+
+/// Cosine similarity of two equal-length vectors. Returns 0 for a
+/// zero-magnitude vector. Mirrors the RAG path's similarity measure.
+fn cosine_similarity(a: &[f64], b: &[f64]) -> f64 {
+    let dot: f64 = a.iter().zip(b.iter()).map(|(x, y)| x * y).sum();
+    let mag_a = a.iter().map(|x| x * x).sum::<f64>().sqrt();
+    let mag_b = b.iter().map(|x| x * x).sum::<f64>().sqrt();
+    if mag_a == 0.0 || mag_b == 0.0 {
+        0.0
+    } else {
+        dot / (mag_a * mag_b)
+    }
+}
+
+/// Sort scored tools by descending score, breaking ties by original
+/// index for deterministic output.
+fn sort_ranked(mut ranked: Vec<RankedTool>) -> Vec<RankedTool> {
+    ranked.sort_by(|a, b| {
+        b.score
+            .partial_cmp(&a.score)
+            .unwrap_or(std::cmp::Ordering::Equal)
+            .then(a.index.cmp(&b.index))
+    });
+    ranked
+}
+
+/// True when query token `q` matches any token in `tokens` — exact, or
+/// substring in either direction for tokens of length ≥ 3 (so "jira"
+/// matches "jiras" and "searching" matches "search", without short
+/// tokens like "id" matching everything).
+fn token_matches(q: &str, tokens: &[String]) -> bool {
+    tokens.iter().any(|t| {
+        t.as_str() == q
+            || (q.len() >= 3 && t.contains(q))
+            || (t.len() >= 3 && q.contains(t.as_str()))
+    })
+}
+
+/// Token-overlap ranking with substring matching. No embedding
+/// dependency.
+#[derive(Default)]
+pub struct LexicalRanker;
+
+impl LexicalRanker {
+    fn score(query_tokens: &[String], meta: &McpToolMeta) -> f64 {
+        if query_tokens.is_empty() {
+            return 0.0;
+        }
+        let text = tool_text(meta);
+        let tool_tokens = tokenize(&text);
+        let matched = query_tokens
+            .iter()
+            .filter(|q| token_matches(q, &tool_tokens))
+            .count();
+        let overlap = matched as f64 / query_tokens.len() as f64;
+        // Boost matches that land in the tool name — those are the
+        // strongest signal that the model wants this exact tool. Blend
+        // (rather than add-then-clamp) so the boost is never erased on a
+        // high-overlap match and the result stays in `0.0..=1.0`: a
+        // name-token hit always outranks a description-only match of
+        // equal overlap.
+        let name_tokens = tokenize(&meta.name);
+        let name_hit = query_tokens.iter().any(|q| token_matches(q, &name_tokens));
+        overlap * 0.75 + if name_hit { 0.25 } else { 0.0 }
+    }
+}
+
+#[async_trait]
+impl ToolSearchRanker for LexicalRanker {
+    async fn rank(&self, query: &str, tools: &[McpToolMeta]) -> Result<Vec<RankedTool>, RankError> {
+        let query_tokens = tokenize(query);
+        let ranked: Vec<RankedTool> = tools
+            .iter()
+            .enumerate()
+            .filter_map(|(index, meta)| {
+                let score = Self::score(&query_tokens, meta);
+                // Drop zero-overlap tools — they're noise, and keeping
+                // them would let a default threshold of 0.0 surface the
+                // whole catalog.
+                (score > 0.0).then_some(RankedTool { index, score })
+            })
+            .collect();
+        Ok(sort_ranked(ranked))
+    }
+}
+
+/// Embedding cosine-similarity ranking. Reuses [`EmbeddingService`] and
+/// caches tool-description embeddings on [`McpService`] so a static
+/// catalog is embedded once, not per request.
+pub struct SemanticRanker {
+    embeddings: Arc<EmbeddingService>,
+    service: McpService,
+}
+
+impl SemanticRanker {
+    pub fn new(embeddings: Arc<EmbeddingService>, service: McpService) -> Self {
+        Self {
+            embeddings,
+            service,
+        }
+    }
+
+    /// Resolve an embedding per tool, hitting the cache first and
+    /// embedding the misses in a single batch call.
+    async fn tool_embeddings(&self, texts: &[String]) -> Result<Vec<Arc<Vec<f64>>>, RankError> {
+        let model = self.embeddings.model();
+        let mut resolved: Vec<Option<Arc<Vec<f64>>>> = texts
+            .iter()
+            .map(|t| self.service.cached_embedding(model, t))
+            .collect();
+
+        let miss_idx: Vec<usize> = resolved
+            .iter()
+            .enumerate()
+            .filter_map(|(i, e)| e.is_none().then_some(i))
+            .collect();
+
+        if !miss_idx.is_empty() {
+            let miss_texts: Vec<String> = miss_idx.iter().map(|&i| texts[i].clone()).collect();
+            let embedded = self
+                .embeddings
+                .embed_batch(&miss_texts)
+                .await
+                .map_err(|e| RankError::Embedding(e.to_string()))?;
+            // Don't index blindly: a provider that drops/dedups inputs
+            // (e.g. empty strings) could return fewer vectors than we
+            // asked for. Indexing `embedded[j]` would then panic.
+            if embedded.len() != miss_texts.len() {
+                return Err(RankError::Embedding(format!(
+                    "embedding provider returned {} vectors for {} inputs",
+                    embedded.len(),
+                    miss_texts.len()
+                )));
+            }
+            for (j, &i) in miss_idx.iter().enumerate() {
+                let arc = Arc::new(embedded[j].clone());
+                self.service.cache_embedding(model, &texts[i], arc.clone());
+                resolved[i] = Some(arc);
+            }
+        }
+
+        // Every slot is Some now (cache hit or freshly embedded).
+        Ok(resolved.into_iter().map(|e| e.expect("filled")).collect())
+    }
+}
+
+#[async_trait]
+impl ToolSearchRanker for SemanticRanker {
+    async fn rank(&self, query: &str, tools: &[McpToolMeta]) -> Result<Vec<RankedTool>, RankError> {
+        if tools.is_empty() {
+            return Ok(Vec::new());
+        }
+        let texts: Vec<String> = tools.iter().map(tool_text).collect();
+        let tool_embeddings = self.tool_embeddings(&texts).await?;
+        let query_embedding = self
+            .embeddings
+            .embed_text(query)
+            .await
+            .map_err(|e| RankError::Embedding(e.to_string()))?;
+
+        let ranked: Vec<RankedTool> = tool_embeddings
+            .iter()
+            .enumerate()
+            .map(|(index, emb)| RankedTool {
+                index,
+                score: cosine_similarity(&query_embedding, emb).max(0.0),
+            })
+            .collect();
+        Ok(sort_ranked(ranked))
+    }
+}
+
+/// Reciprocal Rank Fusion of [`SemanticRanker`] and [`LexicalRanker`].
+///
+/// Each ranker produces an ordered list; a tool's fused score is
+/// `Σ 1 / (k + rank)` over the lists it appears in (1-indexed rank).
+/// Robust to embedding noise and to tools with sparse descriptions. The
+/// fused score is a ranking-only quantity (typically `0.0..≈0.033` at
+/// `k = 60`), not a similarity — keep `score_threshold` at 0 for hybrid.
+pub struct HybridRanker {
+    semantic: SemanticRanker,
+    lexical: LexicalRanker,
+    rrf_k: u32,
+}
+
+impl HybridRanker {
+    pub fn new(semantic: SemanticRanker, rrf_k: u32) -> Self {
+        Self {
+            semantic,
+            lexical: LexicalRanker,
+            rrf_k,
+        }
+    }
+}
+
+#[async_trait]
+impl ToolSearchRanker for HybridRanker {
+    async fn rank(&self, query: &str, tools: &[McpToolMeta]) -> Result<Vec<RankedTool>, RankError> {
+        let semantic = self.semantic.rank(query, tools).await?;
+        let lexical = self.lexical.rank(query, tools).await?;
+
+        let k = self.rrf_k as f64;
+        let mut scores = vec![0.0f64; tools.len()];
+        let mut seen = vec![false; tools.len()];
+        for list in [&semantic, &lexical] {
+            for (rank0, rt) in list.iter().enumerate() {
+                scores[rt.index] += 1.0 / (k + (rank0 + 1) as f64);
+                seen[rt.index] = true;
+            }
+        }
+
+        let ranked: Vec<RankedTool> = scores
+            .into_iter()
+            .enumerate()
+            .filter_map(|(index, score)| seen[index].then_some(RankedTool { index, score }))
+            .collect();
+        Ok(sort_ranked(ranked))
+    }
+
+    /// RRF fuses *ranks*, not similarities; the fused score is a small
+    /// ranking-only quantity, not a `0..=1` relevance. The executor must
+    /// not apply `score_threshold` to it.
+    fn scores_are_normalized(&self) -> bool {
+        false
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn meta(name: &str, desc: &str) -> McpToolMeta {
+        McpToolMeta {
+            name: name.to_string(),
+            description: (!desc.is_empty()).then(|| desc.to_string()),
+            input_schema: serde_json::json!({"type": "object"}),
+            annotations: None,
+        }
+    }
+
+    fn test_embedding_service() -> Arc<EmbeddingService> {
+        let cfg = crate::config::EmbeddingConfig {
+            provider: "test".to_string(),
+            model: "test-embed".to_string(),
+            dimensions: 64,
+        };
+        let test_cfg: crate::config::TestProviderConfig =
+            toml::from_str("").expect("default test provider config");
+        let provider_cfg = crate::config::ProviderConfig::Test(test_cfg);
+        Arc::new(
+            EmbeddingService::new(
+                &cfg,
+                &provider_cfg,
+                &crate::providers::CircuitBreakerRegistry::new(),
+                reqwest::Client::new(),
+            )
+            .expect("embedding service"),
+        )
+    }
+
+    fn catalog() -> Vec<McpToolMeta> {
+        vec![
+            meta("jira_search", "Search Jira issues by query"),
+            meta(
+                "confluence_create_page",
+                "Create a new Confluence wiki page",
+            ),
+            meta("github_list_pull_requests", "List GitHub pull requests"),
+        ]
+    }
+
+    #[tokio::test]
+    async fn lexical_ranks_query_relevant_tool_first() {
+        let tools = catalog();
+        let ranked = LexicalRanker
+            .rank("search jira issues", &tools)
+            .await
+            .unwrap();
+        assert!(!ranked.is_empty());
+        assert_eq!(tools[ranked[0].index].name, "jira_search");
+    }
+
+    #[tokio::test]
+    async fn lexical_drops_zero_overlap_tools() {
+        let tools = catalog();
+        // No token overlaps any tool text.
+        let ranked = LexicalRanker.rank("xyzzy", &tools).await.unwrap();
+        assert!(ranked.is_empty());
+    }
+
+    #[tokio::test]
+    async fn lexical_respects_top_ordering_by_score() {
+        let tools = catalog();
+        let ranked = LexicalRanker
+            .rank("github pull requests", &tools)
+            .await
+            .unwrap();
+        assert_eq!(tools[ranked[0].index].name, "github_list_pull_requests");
+        // Scores are sorted descending.
+        for w in ranked.windows(2) {
+            assert!(w[0].score >= w[1].score);
+        }
+    }
+
+    #[tokio::test]
+    async fn semantic_ranks_query_relevant_tool_first() {
+        // The Test provider's word-based embeddings give shared words
+        // positive cosine similarity, so the Jira tool should win for a
+        // Jira query.
+        let svc = McpService::new();
+        let ranker = SemanticRanker::new(test_embedding_service(), svc);
+        let tools = catalog();
+        let ranked = ranker.rank("search jira issues", &tools).await.unwrap();
+        assert_eq!(ranked.len(), 3);
+        assert_eq!(tools[ranked[0].index].name, "jira_search");
+    }
+
+    #[tokio::test]
+    async fn semantic_uses_embedding_cache_on_second_call() {
+        let svc = McpService::new();
+        let ranker = SemanticRanker::new(test_embedding_service(), svc.clone());
+        let tools = catalog();
+        let _ = ranker.rank("search jira", &tools).await.unwrap();
+        // Tool descriptions should now be cached (one entry per tool).
+        for t in &tools {
+            assert!(svc.cached_embedding("test-embed", &tool_text(t)).is_some());
+        }
+    }
+
+    #[test]
+    fn normalized_score_flag_matches_ranker_kind() {
+        // Lexical/semantic scores are 0..=1 (threshold applies); hybrid
+        // RRF scores are ranking-only (threshold must be skipped).
+        assert!(LexicalRanker.scores_are_normalized());
+        let svc = McpService::new();
+        let semantic = SemanticRanker::new(test_embedding_service(), svc.clone());
+        assert!(semantic.scores_are_normalized());
+        let hybrid = HybridRanker::new(SemanticRanker::new(test_embedding_service(), svc), 60);
+        assert!(!hybrid.scores_are_normalized());
+    }
+
+    #[tokio::test]
+    async fn lexical_matches_query_against_schema_parameters() {
+        // A tool whose discriminating keyword lives only in a parameter
+        // name/description is still findable after indexing the schema.
+        let tool = McpToolMeta {
+            name: "search".to_string(),
+            description: Some("Run a search".to_string()),
+            input_schema: serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "repository": { "type": "string", "description": "GitHub repo slug" }
+                }
+            }),
+            annotations: None,
+        };
+        let ranked = LexicalRanker.rank("repository", &[tool]).await.unwrap();
+        assert_eq!(ranked.len(), 1);
+    }
+
+    #[tokio::test]
+    async fn hybrid_fuses_both_rankers_and_covers_union() {
+        let svc = McpService::new();
+        let semantic = SemanticRanker::new(test_embedding_service(), svc);
+        let ranker = HybridRanker::new(semantic, 60);
+        let tools = catalog();
+        let ranked = ranker.rank("search jira issues", &tools).await.unwrap();
+        // Semantic scores all three, so the fused list covers the union.
+        assert_eq!(ranked.len(), 3);
+        assert_eq!(tools[ranked[0].index].name, "jira_search");
+        for w in ranked.windows(2) {
+            assert!(w[0].score >= w[1].score);
+        }
+    }
+}
diff --git a/src/services/mcp_tool.rs b/src/services/mcp_tool.rs
new file mode 100644
index 0000000..3407ba7
--- /dev/null
+++ b/src/services/mcp_tool.rs
@@ -0,0 +1,431 @@
+//! MCP (Model Context Protocol) tool preprocessing.
+//!
+//! Validate `{"type": "mcp", ...}` tool entries on a `/v1/responses`
+//! payload against the operator config and the resolved provider.
+//! Under `mode = passthrough_openai` the entries are forwarded
+//! verbatim to OpenAI / Azure OpenAI; under `mode = hadrian_hosted`
+//! the rewrite in [`super::mcp::preprocess`] turns them into per-tool
+//! function tools so any provider can drive the loop. Either way,
+//! invalid shapes are rejected with a clear 400.
+//!
+//! Caller-supplied credentials only — the `authorization` field on
+//! `McpTool` is treated as opaque and never persisted by the gateway.
+//! See `docs/content/docs/features/mcp.mdx`.
+//!
+//! Pre-admission lives in `routes/api/chat.rs::api_v1_responses`, next
+//! to the existing `resolve_shell_environment` block. Failures map to
+//! HTTP 400 via `ApiError`.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use crate::{
+    api_types::responses::{
+        CreateResponsesPayload, McpTool, ResponsesToolDefinition, is_known_mcp_connector_id,
+    },
+    config::{McpConfig, McpMode, ProviderConfig},
+};
+
+/// Errors raised by `preprocess_mcp_tools`. All map to HTTP 400 with
+/// the variant's `error_code` and the `Display` form as message.
+#[derive(Debug, thiserror::Error, PartialEq, Eq)]
+pub enum McpToolError {
+    #[error("MCP tool requires exactly one of `server_url` or `connector_id` (server_label: {0})")]
+    InvalidTarget(String),
+
+    #[error(
+        "MCP tool uses `connector_id` but `[features.mcp].allow_connector_ids` is false \
+         (server_label: {0})"
+    )]
+    ConnectorIdNotAllowed(String),
+
+    #[error(
+        "MCP `connector_id` '{connector_id}' is not a known OpenAI connector \
+         (server_label: {server_label})"
+    )]
+    InvalidConnectorId {
+        server_label: String,
+        connector_id: String,
+    },
+
+    #[error(
+        "MCP tool `server_url` '{server_url}' is not in `[features.mcp].allowed_server_urls` \
+         (server_label: {server_label})"
+    )]
+    ServerUrlNotAllowed {
+        server_label: String,
+        server_url: String,
+    },
+
+    #[error(
+        "MCP `mode = passthrough_openai` requires an OpenAI or Azure OpenAI upstream; \
+         resolved provider is {0} (server_label: {1})"
+    )]
+    PassthroughRequiresOpenAi(&'static str, String),
+
+    #[error(
+        "MCP `mode = hadrian_hosted` requires the gateway to be built with the `mcp` \
+         cargo feature (server_label: {0})"
+    )]
+    HadrianHostedNotImplemented(String),
+
+    #[error("MCP tool is present but `[features.mcp]` is not enabled (server_label: {0})")]
+    Disabled(String),
+}
+
+impl McpToolError {
+    /// Stable error code string surfaced to clients.
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::InvalidTarget(_) => "mcp_invalid_target",
+            Self::ConnectorIdNotAllowed(_) => "mcp_connector_id_not_allowed",
+            Self::InvalidConnectorId { .. } => "mcp_invalid_connector_id",
+            Self::ServerUrlNotAllowed { .. } => "mcp_server_url_not_allowed",
+            Self::PassthroughRequiresOpenAi(_, _) => "mcp_passthrough_unsupported_provider",
+            Self::HadrianHostedNotImplemented(_) => "mcp_hadrian_hosted_not_implemented",
+            Self::Disabled(_) => "mcp_disabled",
+        }
+    }
+}
+
+/// Coarse provider classification used by the MCP preprocess. We only
+/// need to know whether the upstream speaks OpenAI's `mcp` tool
+/// natively; the concrete provider config is captured for error
+/// messages.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum McpProviderKind {
+    OpenAi,
+    AzureOpenAi,
+    Anthropic,
+    Bedrock,
+    Vertex,
+    Test,
+}
+
+impl McpProviderKind {
+    pub fn name(self) -> &'static str {
+        match self {
+            Self::OpenAi => "openai",
+            Self::AzureOpenAi => "azure_openai",
+            Self::Anthropic => "anthropic",
+            Self::Bedrock => "bedrock",
+            Self::Vertex => "vertex",
+            Self::Test => "test",
+        }
+    }
+
+    /// True for the upstreams that run OpenAI's MCP loop natively.
+    pub fn supports_passthrough_mcp(self) -> bool {
+        matches!(self, Self::OpenAi | Self::AzureOpenAi)
+    }
+
+    /// Derive the kind from a resolved `ProviderConfig`. Stays in sync
+    /// with the arms in `routes/execution.rs::ResponsesExecutor::execute`.
+    pub fn from_provider(provider: &ProviderConfig) -> Self {
+        match provider {
+            ProviderConfig::OpenAi(_) => Self::OpenAi,
+            ProviderConfig::Anthropic(_) => Self::Anthropic,
+            #[cfg(feature = "provider-azure")]
+            ProviderConfig::AzureOpenAi(_) => Self::AzureOpenAi,
+            #[cfg(feature = "provider-bedrock")]
+            ProviderConfig::Bedrock(_) => Self::Bedrock,
+            #[cfg(feature = "provider-vertex")]
+            ProviderConfig::Vertex(_) => Self::Vertex,
+            ProviderConfig::Test(_) => Self::Test,
+        }
+    }
+}
+
+/// Validate every `mcp` tool entry on the payload against the operator
+/// configuration and the resolved provider.
+///
+/// Returns the first failure encountered (bail-on-first; collecting
+/// every failure into a `Vec` is a future enhancement). On success the
+/// payload is untouched; the downstream rewrite in
+/// [`super::mcp::preprocess`] runs only under `hadrian_hosted`.
+pub fn preprocess_mcp_tools(
+    payload: &CreateResponsesPayload,
+    cfg: Option<&McpConfig>,
+    provider: McpProviderKind,
+) -> Result<(), McpToolError> {
+    let Some(tools) = payload.tools.as_ref() else {
+        return Ok(());
+    };
+
+    for tool in tools {
+        let ResponsesToolDefinition::Mcp(mcp) = tool else {
+            continue;
+        };
+        validate_one(mcp, cfg, provider)?;
+    }
+
+    Ok(())
+}
+
+fn validate_one(
+    mcp: &McpTool,
+    cfg: Option<&McpConfig>,
+    provider: McpProviderKind,
+) -> Result<(), McpToolError> {
+    let label = mcp.server_label.clone();
+
+    // 1. Feature gate.
+    let cfg = match cfg {
+        Some(c) if c.enabled => c,
+        _ => return Err(McpToolError::Disabled(label)),
+    };
+
+    // 2. Target shape — exactly one of `server_url`, `connector_id`.
+    if !mcp.has_exactly_one_target() {
+        return Err(McpToolError::InvalidTarget(label));
+    }
+
+    // 3. Connector flag + closed-enum check.
+    if let Some(ref cid) = mcp.connector_id {
+        if !cfg.allow_connector_ids {
+            return Err(McpToolError::ConnectorIdNotAllowed(label));
+        }
+        if !is_known_mcp_connector_id(cid) {
+            return Err(McpToolError::InvalidConnectorId {
+                server_label: label,
+                connector_id: cid.clone(),
+            });
+        }
+    }
+
+    // 4. Server URL allowlist (only when configured).
+    if let (Some(url), Some(allowed)) = (mcp.server_url.as_ref(), cfg.allowed_server_urls.as_ref())
+        && !allowed.iter().any(|a| a == url)
+    {
+        return Err(McpToolError::ServerUrlNotAllowed {
+            server_label: label,
+            server_url: url.clone(),
+        });
+    }
+
+    // 5. Mode → provider check.
+    match cfg.mode {
+        McpMode::PassthroughOpenai => {
+            if !provider.supports_passthrough_mcp() {
+                return Err(McpToolError::PassthroughRequiresOpenAi(
+                    provider.name(),
+                    label,
+                ));
+            }
+        }
+        McpMode::HadrianHosted => {
+            // The hosted implementation lives in `services::mcp` and is
+            // gated on the `mcp` cargo feature. When the feature is off
+            // (e.g. `tiny`/`minimal` builds) the mode is still rejected.
+            #[cfg(not(feature = "mcp"))]
+            {
+                return Err(McpToolError::HadrianHostedNotImplemented(label));
+            }
+            #[cfg(feature = "mcp")]
+            {
+                // The actual tools/list + rewrite happens in
+                // `routes/execution.rs` (async), so pre-admission only
+                // gates structural validity. `connector_id` is
+                // unreachable under hadrian_hosted — reject early.
+                if mcp.connector_id.is_some() {
+                    return Err(McpToolError::ConnectorIdNotAllowed(label));
+                }
+                // server_url is mandatory under hadrian_hosted, and
+                // `has_exactly_one_target` already guarantees one of
+                // server_url/connector_id is set, so this is implicit.
+                let _ = label;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api_types::responses::{McpToolType, ResponsesToolDefinition};
+
+    fn cfg_passthrough() -> McpConfig {
+        McpConfig {
+            enabled: true,
+            mode: McpMode::PassthroughOpenai,
+            allowed_server_urls: None,
+            allow_connector_ids: false,
+            ..McpConfig::default()
+        }
+    }
+
+    fn cfg_hosted() -> McpConfig {
+        McpConfig {
+            enabled: true,
+            mode: McpMode::HadrianHosted,
+            allowed_server_urls: None,
+            allow_connector_ids: false,
+            ..McpConfig::default()
+        }
+    }
+
+    fn mcp_tool(server_url: Option<&str>, connector_id: Option<&str>) -> ResponsesToolDefinition {
+        ResponsesToolDefinition::Mcp(McpTool {
+            type_: McpToolType::Mcp,
+            server_label: "test".into(),
+            server_url: server_url.map(str::to_string),
+            connector_id: connector_id.map(str::to_string),
+            server_description: None,
+            authorization: None,
+            headers: None,
+            require_approval: None,
+            allowed_tools: None,
+            defer_loading: None,
+            defer_loading_passthrough: None,
+            call_timeout_secs: None,
+        })
+    }
+
+    fn empty_payload() -> CreateResponsesPayload {
+        serde_json::from_value(serde_json::json!({})).expect("minimal payload parses")
+    }
+
+    fn payload_with(tool: ResponsesToolDefinition) -> CreateResponsesPayload {
+        let mut p = empty_payload();
+        p.tools = Some(vec![tool]);
+        p
+    }
+
+    #[test]
+    fn no_mcp_tools_is_noop() {
+        let payload = empty_payload();
+        assert!(preprocess_mcp_tools(&payload, None, McpProviderKind::Anthropic).is_ok());
+    }
+
+    #[test]
+    fn disabled_when_config_missing() {
+        let payload = payload_with(mcp_tool(Some("https://x"), None));
+        let err = preprocess_mcp_tools(&payload, None, McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_disabled");
+    }
+
+    #[test]
+    fn disabled_when_config_disabled() {
+        let cfg = McpConfig {
+            enabled: false,
+            ..cfg_passthrough()
+        };
+        let payload = payload_with(mcp_tool(Some("https://x"), None));
+        let err = preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_disabled");
+    }
+
+    #[test]
+    fn rejects_no_target() {
+        let cfg = cfg_passthrough();
+        let payload = payload_with(mcp_tool(None, None));
+        let err = preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_invalid_target");
+    }
+
+    #[test]
+    fn rejects_both_targets() {
+        let cfg = cfg_passthrough();
+        let payload = payload_with(mcp_tool(
+            Some("https://x"),
+            Some("connector_googlecalendar"),
+        ));
+        let err = preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_invalid_target");
+    }
+
+    #[test]
+    fn rejects_connector_id_when_disallowed() {
+        let cfg = cfg_passthrough();
+        let payload = payload_with(mcp_tool(None, Some("connector_googlecalendar")));
+        let err = preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_connector_id_not_allowed");
+    }
+
+    #[test]
+    fn accepts_connector_id_when_allowed() {
+        let cfg = McpConfig {
+            allow_connector_ids: true,
+            ..cfg_passthrough()
+        };
+        let payload = payload_with(mcp_tool(None, Some("connector_googlecalendar")));
+        assert!(preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).is_ok());
+    }
+
+    #[test]
+    fn rejects_unknown_connector_id() {
+        let cfg = McpConfig {
+            allow_connector_ids: true,
+            ..cfg_passthrough()
+        };
+        let payload = payload_with(mcp_tool(None, Some("connector_made_up")));
+        let err = preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_invalid_connector_id");
+    }
+
+    #[test]
+    fn enforces_server_url_allowlist() {
+        let cfg = McpConfig {
+            allowed_server_urls: Some(vec!["https://allowed.example/mcp".into()]),
+            ..cfg_passthrough()
+        };
+        let payload = payload_with(mcp_tool(Some("https://evil.example/mcp"), None));
+        let err = preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_server_url_not_allowed");
+
+        let ok_payload = payload_with(mcp_tool(Some("https://allowed.example/mcp"), None));
+        assert!(preprocess_mcp_tools(&ok_payload, Some(&cfg), McpProviderKind::OpenAi).is_ok());
+    }
+
+    #[test]
+    fn passthrough_rejects_anthropic() {
+        let cfg = cfg_passthrough();
+        let payload = payload_with(mcp_tool(Some("https://x"), None));
+        let err =
+            preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::Anthropic).unwrap_err();
+        assert_eq!(err.code(), "mcp_passthrough_unsupported_provider");
+    }
+
+    #[test]
+    fn passthrough_accepts_azure() {
+        let cfg = cfg_passthrough();
+        let payload = payload_with(mcp_tool(Some("https://x"), None));
+        assert!(preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::AzureOpenAi).is_ok());
+    }
+
+    #[cfg(not(feature = "mcp"))]
+    #[test]
+    fn hadrian_hosted_rejects_without_feature() {
+        let cfg = cfg_hosted();
+        let payload = payload_with(mcp_tool(Some("https://x"), None));
+        let err = preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_hadrian_hosted_not_implemented");
+    }
+
+    #[cfg(feature = "mcp")]
+    #[test]
+    fn hadrian_hosted_admits_with_feature() {
+        // The actual tools/list + rewrite happens later in
+        // routes/execution.rs; pre-admission just validates structural
+        // shape, so a valid `mcp` tool under hadrian_hosted passes here.
+        let cfg = cfg_hosted();
+        let payload = payload_with(mcp_tool(Some("https://x"), None));
+        assert!(preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).is_ok());
+    }
+
+    #[cfg(feature = "mcp")]
+    #[test]
+    fn hadrian_hosted_rejects_connector_id() {
+        // connector_id needs OpenAI's connector registry, unreachable
+        // from a self-hosted gateway. Reject at pre-admission even
+        // though allow_connector_ids=true would let passthrough through.
+        let cfg = McpConfig {
+            allow_connector_ids: true,
+            ..cfg_hosted()
+        };
+        let payload = payload_with(mcp_tool(None, Some("connector_googlecalendar")));
+        let err = preprocess_mcp_tools(&payload, Some(&cfg), McpProviderKind::OpenAi).unwrap_err();
+        assert_eq!(err.code(), "mcp_connector_id_not_allowed");
+    }
+}
diff --git a/src/services/mod.rs b/src/services/mod.rs
index e2d1d9e..3ca7269 100644
--- a/src/services/mod.rs
+++ b/src/services/mod.rs
@@ -1,6 +1,14 @@
 mod access_reviews;
 mod api_keys;
 pub mod audit_logs;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod background_executor;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod compactor;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod container_session;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod containers;
 mod conversations;
 #[cfg(any(
     feature = "document-extraction-basic",
@@ -15,6 +23,12 @@ mod file_storage;
 mod files;
 #[cfg(feature = "forecasting")]
 pub mod forecasting;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod input_file_staging;
+#[cfg(all(feature = "mcp", not(target_arch = "wasm32")))]
+pub mod mcp;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod mcp_tool;
 mod model_pricing;
 pub mod oauth_pkce;
 mod org_rbac_policies;
@@ -29,11 +43,25 @@ pub mod prometheus_parser;
 pub mod provider_metrics;
 mod providers;
 mod reranker;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod response_event_buffer;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod response_persister;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod responses_pipeline;
+#[cfg(not(target_arch = "wasm32"))]
+mod responses_store;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod responses_webhook;
 #[cfg(feature = "sso")]
 mod scim_configs;
 #[cfg(feature = "sso")]
 mod scim_provisioning;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod server_tools;
 mod service_accounts;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod shell_tool;
 mod skills;
 #[cfg(feature = "sso")]
 mod sso_group_mappings;
@@ -67,8 +95,7 @@ pub use file_search::{
     FileSearchServiceConfig,
 };
 pub use file_search_tool::{
-    FileSearchAuthContext, FileSearchContext, FileSearchToolArguments, ProviderCallback,
-    preprocess_file_search_tools, wrap_streaming_with_file_search,
+    FileSearchAuthContext, FileSearchContext, FileSearchToolArguments, preprocess_file_search_tools,
 };
 #[cfg(feature = "server")]
 pub use file_storage::FilesystemFileStorage;
@@ -97,6 +124,14 @@ pub use reranker::{
     LlmReranker, NoOpReranker, RankedResult, RerankError, RerankRequest, RerankResponse,
     RerankUsage, Reranker,
 };
+#[cfg(not(target_arch = "wasm32"))]
+pub use response_event_buffer::ResponseEventBuffer;
+#[cfg(not(target_arch = "wasm32"))]
+pub use responses_store::{
+    CancelSignal, ResponsesStore, ResponsesStoreError, ResponsesStoreResult,
+};
+#[cfg(not(target_arch = "wasm32"))]
+pub use responses_webhook::{ResponsesWebhookDispatcher, WebhookEvent, WebhookEventData};
 #[cfg(feature = "sso")]
 pub use scim_configs::{OrgScimConfigError, OrgScimConfigService};
 #[cfg(feature = "sso")]
@@ -114,9 +149,7 @@ pub use vector_stores::VectorStoresService;
 pub use virus_scan::{
     ClamAvScanner, NoOpScanner, ScanResult, VirusScanError, VirusScanResult, VirusScanner,
 };
-pub use web_search_tool::{
-    WebSearchContext, preprocess_web_search_tools, wrap_streaming_with_web_search,
-};
+pub use web_search_tool::{WebSearchContext, preprocess_web_search_tools};
 
 use crate::{db::DbPool, events::EventBus};
 
diff --git a/src/services/response_event_buffer.rs b/src/services/response_event_buffer.rs
new file mode 100644
index 0000000..b092eff
--- /dev/null
+++ b/src/services/response_event_buffer.rs
@@ -0,0 +1,269 @@
+//! Bounded-channel writer for `response_events`.
+//!
+//! Each call to `push` enqueues one event onto a bounded channel; a
+//! single drainer task collects events and flushes them in batches
+//! either when `max_batch` accumulates or after `flush_interval`,
+//! whichever comes first. Buffering trades 100ms of tail latency for
+//! ~10–100x fewer DB round-trips during high-throughput streaming.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::{collections::HashMap, sync::Arc, time::Duration};
+
+use tokio::{
+    sync::{Mutex, mpsc, oneshot, watch},
+    time::Instant,
+};
+use tracing::{debug, warn};
+
+use crate::db::repos::{NewResponseEvent, ResponseEventsRepo};
+
+/// Handle to enqueue events. Cheap to clone; backed by a single
+/// underlying channel + drainer.
+#[derive(Clone)]
+pub struct ResponseEventBuffer {
+    tx: mpsc::Sender<NewResponseEvent>,
+    /// A direct repo handle for synchronous insertion. The persister
+    /// uses this for the terminal event so the row's status update
+    /// can't observe a state where status=Completed but the terminal
+    /// event hasn't yet been committed to the log.
+    repo: Arc<dyn ResponseEventsRepo>,
+    /// Watch channel for shutdown coordination. The drainer awaits
+    /// `changed()`; `shutdown()` flips `true` and then awaits the
+    /// `drainer_done` watch.
+    shutdown_tx: watch::Sender<bool>,
+    drainer_done_rx: Arc<Mutex<watch::Receiver<bool>>>,
+    /// Flush-barrier channel. `flush()` sends a oneshot ack sender; the
+    /// drainer drains everything currently queued, commits it, then
+    /// acks. Used by the persister to ensure all buffered events are
+    /// durably committed *before* the synchronous terminal-event insert.
+    flush_tx: mpsc::Sender<oneshot::Sender<()>>,
+}
+
+impl ResponseEventBuffer {
+    /// Spawn the drainer task and return a handle for `push`. The task
+    /// runs until `shutdown()` is called or all senders are dropped,
+    /// flushes pending events, and signals completion.
+    pub fn spawn(
+        repo: Arc<dyn ResponseEventsRepo>,
+        max_batch: usize,
+        flush_interval: Duration,
+        channel_capacity: usize,
+    ) -> Self {
+        let (tx, rx) = mpsc::channel(channel_capacity);
+        let (shutdown_tx, shutdown_rx) = watch::channel(false);
+        let (done_tx, done_rx) = watch::channel(false);
+        let (flush_tx, flush_rx) = mpsc::channel(8);
+        let drainer_repo = repo.clone();
+        crate::compat::spawn_detached(async move {
+            drain_events(
+                rx,
+                flush_rx,
+                drainer_repo,
+                max_batch,
+                flush_interval,
+                shutdown_rx,
+            )
+            .await;
+            let _ = done_tx.send(true);
+        });
+        Self {
+            tx,
+            repo,
+            shutdown_tx,
+            drainer_done_rx: Arc::new(Mutex::new(done_rx)),
+            flush_tx,
+        }
+    }
+
+    /// Synchronously drain and commit every event the drainer currently
+    /// holds — both its in-memory batch and anything queued on the
+    /// channel at the time of the call. Returns once those events are
+    /// durably committed (and `last_sequence_number` ratcheted).
+    ///
+    /// The persister calls this before `insert_sync` for a terminal
+    /// event: every prior non-terminal event was already `push`ed
+    /// (synchronous `try_send`), so they are guaranteed to land in the
+    /// log before the terminal event. Without it, a reconnecting
+    /// `?stream=true` reader could see the terminal event (and emit
+    /// `[DONE]`) while earlier events are still buffered, dropping the
+    /// tail of the stream.
+    pub async fn flush(&self) {
+        let (ack_tx, ack_rx) = oneshot::channel();
+        if self.flush_tx.send(ack_tx).await.is_err() {
+            // Drainer has exited (shutting down); nothing to flush.
+            return;
+        }
+        let _ = ack_rx.await;
+    }
+
+    /// Trigger an orderly shutdown of the drainer. Waits until the
+    /// drainer has flushed in-flight events and exited. Called by
+    /// `cli::server` during graceful shutdown so buffered events
+    /// aren't lost when the process is killed.
+    pub async fn shutdown(&self) {
+        let _ = self.shutdown_tx.send(true);
+        let mut done = self.drainer_done_rx.lock().await;
+        // wait_for returns immediately if the value is already true.
+        let _ = done.wait_for(|v| *v).await;
+    }
+
+    /// Enqueue one event. On overflow we never silently drop: a dropped
+    /// event leaves a permanent hole in the replay log while the terminal
+    /// event still commits, so a reconnecting `?stream=true` reader
+    /// replays a complete-looking response that is missing content.
+    /// Instead we `flush()` the drainer (which commits everything
+    /// currently queued, in order) and retry once; if the channel is
+    /// still full (drainer contended), we commit the event synchronously.
+    pub async fn push(&self, event: NewResponseEvent) {
+        let event = match self.tx.try_send(event) {
+            Ok(()) => return,
+            Err(mpsc::error::TrySendError::Full(event)) => event,
+            // Drainer has exited; system is shutting down.
+            Err(mpsc::error::TrySendError::Closed(_)) => return,
+        };
+        // Channel full — drain everything queued (preserving order) and
+        // retry the fast path once.
+        warn!("response_event_buffer: channel full; flushing and retrying");
+        self.flush().await;
+        let event = match self.tx.try_send(event) {
+            Ok(()) => return,
+            Err(mpsc::error::TrySendError::Full(event)) => event,
+            Err(mpsc::error::TrySendError::Closed(_)) => return,
+        };
+        // Still full after a flush: commit synchronously rather than drop.
+        if let Err(e) = self.insert_sync(event).await {
+            warn!(error = %e, "response_event_buffer: synchronous fallback insert failed");
+        }
+    }
+
+    /// Synchronously insert a single event, bypassing the buffer.
+    /// Returns once the row is committed and `last_sequence_number`
+    /// is ratcheted.
+    ///
+    /// The persister uses this for the terminal event so the row's
+    /// status update happens-after the terminal event commit. Without
+    /// this, `GET /v1/responses/{id}?stream=true` readers can observe
+    /// `status=Completed` before the terminal event reaches the log.
+    pub async fn insert_sync(&self, event: NewResponseEvent) -> Result<(), crate::db::DbError> {
+        let response_id = event.response_id.clone();
+        let seq = event.sequence_number;
+        self.repo.insert_batch(vec![event]).await?;
+        self.repo.set_last_sequence(&response_id, seq).await?;
+        Ok(())
+    }
+}
+
+async fn drain_events(
+    mut rx: mpsc::Receiver<NewResponseEvent>,
+    mut flush_rx: mpsc::Receiver<oneshot::Sender<()>>,
+    repo: Arc<dyn ResponseEventsRepo>,
+    max_batch: usize,
+    flush_interval: Duration,
+    mut shutdown: watch::Receiver<bool>,
+) {
+    let mut buffer: Vec<NewResponseEvent> = Vec::with_capacity(max_batch);
+    let mut next_flush = Instant::now() + flush_interval;
+
+    loop {
+        if *shutdown.borrow() {
+            break;
+        }
+        let now = Instant::now();
+        let timeout = if next_flush > now {
+            next_flush - now
+        } else {
+            Duration::ZERO
+        };
+        let result = tokio::select! {
+            biased;
+            _ = shutdown.changed() => {
+                break;
+            }
+            req = flush_rx.recv() => {
+                match req {
+                    Some(ack) => {
+                        // Pull everything currently queued so all events
+                        // sent before this flush request land before we
+                        // ack — the caller `push`ed them synchronously,
+                        // so they are already in the channel buffer.
+                        while let Ok(ev) = rx.try_recv() {
+                            buffer.push(ev);
+                        }
+                        flush(&repo, &mut buffer).await;
+                        next_flush = Instant::now() + flush_interval;
+                        let _ = ack.send(());
+                        continue;
+                    }
+                    // All flush handles dropped (shutting down). The
+                    // data channel lives in the same struct and closes
+                    // with it, so exit to the final drain rather than
+                    // busy-looping on the closed flush channel.
+                    None => break,
+                }
+            }
+            r = tokio::time::timeout(timeout, rx.recv()) => r,
+        };
+        match result {
+            Ok(Some(ev)) => {
+                buffer.push(ev);
+                if buffer.len() >= max_batch {
+                    flush(&repo, &mut buffer).await;
+                    next_flush = Instant::now() + flush_interval;
+                }
+            }
+            Ok(None) => {
+                // Channel closed — flush remainder and exit.
+                break;
+            }
+            Err(_) => {
+                // Timeout — flush whatever we have.
+                if !buffer.is_empty() {
+                    flush(&repo, &mut buffer).await;
+                }
+                next_flush = Instant::now() + flush_interval;
+            }
+        }
+    }
+
+    // Final flush: drain anything still in the channel + buffer so
+    // shutdown doesn't lose events.
+    while let Ok(ev) = rx.try_recv() {
+        buffer.push(ev);
+    }
+    if !buffer.is_empty() {
+        flush(&repo, &mut buffer).await;
+    }
+    debug!("response_event_buffer drainer exiting");
+}
+
+async fn flush(repo: &Arc<dyn ResponseEventsRepo>, buffer: &mut Vec<NewResponseEvent>) {
+    if buffer.is_empty() {
+        return;
+    }
+    // Compute max sequence per response in this batch so we can
+    // ratchet `responses.last_sequence_number` after the insert.
+    let mut max_seq: HashMap<String, i64> = HashMap::new();
+    for ev in buffer.iter() {
+        let entry = max_seq.entry(ev.response_id.clone()).or_insert(0);
+        if ev.sequence_number > *entry {
+            *entry = ev.sequence_number;
+        }
+    }
+    let drained: Vec<NewResponseEvent> = std::mem::take(buffer);
+    let count = drained.len();
+    match repo.insert_batch(drained).await {
+        Ok(n) => {
+            debug!(inserted = n, batch = count, "response_events batch flushed");
+        }
+        Err(e) => {
+            warn!(error = %e, "response_events batch insert failed");
+            return;
+        }
+    }
+    for (response_id, seq) in max_seq {
+        if let Err(e) = repo.set_last_sequence(&response_id, seq).await {
+            warn!(error = %e, %response_id, "set_last_sequence failed");
+        }
+    }
+}
diff --git a/src/services/response_persister.rs b/src/services/response_persister.rs
new file mode 100644
index 0000000..6ee53e9
--- /dev/null
+++ b/src/services/response_persister.rs
@@ -0,0 +1,543 @@
+//! Persistence wrapper for `/v1/responses` streams.
+//!
+//! Sits at the very end of the streaming pipeline (after the tool
+//! loop runner). Reads the SSE events flowing to the client, looks
+//! for the terminal `response.completed` / `response.failed` /
+//! `response.incomplete` event, captures the full `response` object,
+//! and persists it via [`ResponsesStore::update`]. The body is
+//! forwarded byte-for-byte — the persister is non-destructive.
+//!
+//! Cancellation: a watch receiver tied to the response row is polled
+//! in parallel with the body stream. When it flips, the wrapper
+//! terminates forwarding immediately and marks the row Cancelled.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::sync::Arc;
+
+use axum::body::Body;
+use bytes::Bytes;
+use chrono::Utc;
+use futures_util::StreamExt;
+use http::Response;
+use serde_json::Value;
+use tokio::sync::mpsc;
+use tracing::{debug, error, info, warn};
+use uuid::Uuid;
+
+use crate::{
+    db::repos::{NewResponseEvent, ResponseCompletion, ResponseStatus},
+    services::{CancelSignal, ResponseEventBuffer, ResponsesStore},
+    streaming::SseBuffer,
+};
+
+/// Wrap a streaming Responses-API HTTP response so the final state
+/// gets persisted to the `responses` table when the stream terminates.
+///
+/// Returns the same response shape, with body replaced by a stream
+/// that mirrors the original.
+///
+/// `initial_sequence_number` is the row's `last_sequence_number` at
+/// attach time. The persister increments from there so re-attaches
+/// (background retries, hypothetical resume) continue the sequence
+/// instead of restarting at 0 and colliding on the (response_id,
+/// sequence_number) primary key.
+pub fn wrap_streaming_with_persistence(
+    response: Response<Body>,
+    store: Arc<ResponsesStore>,
+    response_id: String,
+    org_id: Uuid,
+    initial_sequence_number: i64,
+    mut cancel_rx: CancelSignal,
+    event_buffer: Option<Arc<ResponseEventBuffer>>,
+) -> Response<Body> {
+    let (parts, body) = response.into_parts();
+    let (tx, rx) = mpsc::channel::<Result<Bytes, std::io::Error>>(32);
+
+    crate::compat::spawn_detached(async move {
+        let mut body_stream = body.into_data_stream();
+        let mut sse_buffer = SseBuffer::new();
+        let mut final_response_object: Option<Value> = None;
+        let mut terminal_status: Option<ResponseStatus> = None;
+        let mut terminal_event_persisted = false;
+        let mut sequence_number: i64 = initial_sequence_number;
+        let mut cancelled = false;
+        // Liveness heartbeat: stamp `last_heartbeat_at` at most once per
+        // interval while the stream is live so the in-progress reaper can
+        // tell a healthy long-running response from a dead worker.
+        const HEARTBEAT_INTERVAL: std::time::Duration = std::time::Duration::from_secs(15);
+        let mut last_heartbeat = std::time::Instant::now();
+        // Lazily filled when the first terminal event is detected so
+        // we can inject `container_id` into the response payload (the
+        // upstream provider doesn't know about Hadrian containers).
+        // Fetched once per response; `None` after the lookup means no
+        // shell-tool session was attached.
+        let mut container_id_for_event: Option<Option<String>> = None;
+
+        loop {
+            tokio::select! {
+                _ = cancel_rx.changed() => {
+                    if *cancel_rx.borrow() {
+                        cancelled = true;
+                        warn!(
+                            stage = "persist_cancelled",
+                            response_id = %response_id,
+                            "Cancel signal tripped; finalising stream"
+                        );
+                        break;
+                    }
+                }
+                chunk = body_stream.next() => {
+                    let Some(chunk_result) = chunk else { break };
+                    let chunk = match chunk_result {
+                        Ok(c) => c,
+                        Err(e) => {
+                            let _ = tx.send(Err(std::io::Error::other(e))).await;
+                            return;
+                        }
+                    };
+                    sse_buffer.extend(&chunk);
+                    if last_heartbeat.elapsed() >= HEARTBEAT_INTERVAL {
+                        store.touch_heartbeat(&response_id).await;
+                        last_heartbeat = std::time::Instant::now();
+                    }
+                    for event in sse_buffer.extract_complete_events() {
+                        let is_terminal = inspect_terminal_event(&event);
+
+                        // On the first terminal event, look up the
+                        // response record once and cache its
+                        // container_id so we can stamp it into both the
+                        // forwarded SSE event and the persisted event
+                        // payload. Upstream providers don't know about
+                        // Hadrian-hosted containers, so without this
+                        // injection clients only see container_id on
+                        // the GET retrieve path.
+                        if is_terminal.is_some() && container_id_for_event.is_none() {
+                            let lookup = store
+                                .get(&response_id, org_id)
+                                .await
+                                .ok()
+                                .and_then(|r| r.container_id);
+                            container_id_for_event = Some(lookup);
+                        }
+                        let event = if is_terminal.is_some()
+                            && let Some(Some(ref cid)) = container_id_for_event
+                        {
+                            inject_container_id_into_event(&event, cid).unwrap_or(event)
+                        } else {
+                            event
+                        };
+                        if final_response_object.is_none()
+                            && let Some((resp_obj, status)) = inspect_terminal_event(&event)
+                        {
+                            final_response_object = Some(resp_obj);
+                            terminal_status = Some(status);
+                        }
+
+                        // Append to the event log if a buffer is wired
+                        // up. Terminal events go through `insert_sync`
+                        // so the row's status update later in this
+                        // function happens-after the event commit —
+                        // closes the race where ?stream=true readers
+                        // see `status=Completed` before the terminal
+                        // event reaches the log. Non-terminal events
+                        // ride the buffered fast path.
+                        if let Some(ref buf) = event_buffer {
+                            sequence_number += 1;
+                            let (event_type, payload) = parse_event_for_log(&event);
+                            let new_event = NewResponseEvent {
+                                response_id: response_id.clone(),
+                                sequence_number,
+                                event_type,
+                                payload,
+                                created_at: Utc::now(),
+                            };
+                            if is_terminal.is_some() {
+                                // Flush all buffered non-terminal events
+                                // first so the terminal event (and its
+                                // `last_sequence_number` ratchet) can't
+                                // commit ahead of earlier events still in
+                                // the drainer — otherwise a reconnecting
+                                // ?stream=true reader emits [DONE] and
+                                // drops the un-flushed tail.
+                                buf.flush().await;
+                                if let Err(e) = buf.insert_sync(new_event).await {
+                                    warn!(
+                                        error = %e,
+                                        response_id = %response_id,
+                                        "Failed to commit terminal response event; \
+                                         readers may see status=terminal without the event"
+                                    );
+                                } else {
+                                    terminal_event_persisted = true;
+                                }
+                            } else {
+                                buf.push(new_event).await;
+                            }
+                        }
+
+                        if tx.send(Ok(event)).await.is_err() {
+                            // Client gone; we still want to record state
+                            // for the GET endpoint, so finish the persist
+                            // step below.
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+
+        // Flush any trailing partial bytes. On cancel, append a
+        // synthetic `response.cancelled` event so polling clients
+        // observe the terminal status in the event log too.
+        if !sse_buffer.is_empty() {
+            let _ = tx.send(Ok(sse_buffer.take_remaining())).await;
+        }
+
+        // Persist the captured state. If we never saw a terminal
+        // event, mark as incomplete — the stream ended without a
+        // `response.completed`. Cancel takes precedence regardless of
+        // what events we saw.
+        let (output, usage, error_field, status) = if cancelled {
+            (None, None, None, ResponseStatus::Cancelled)
+        } else {
+            match final_response_object {
+                Some(resp) => {
+                    let status = terminal_status.unwrap_or(ResponseStatus::Completed);
+                    (
+                        resp.get("output").cloned(),
+                        resp.get("usage").cloned(),
+                        resp.get("error").cloned().filter(|v| !v.is_null()),
+                        status,
+                    )
+                }
+                None => {
+                    debug!(
+                        stage = "persist_no_terminal_event",
+                        response_id = %response_id,
+                        "Stream ended without a terminal response event; marking incomplete"
+                    );
+                    (None, None, None, ResponseStatus::Incomplete)
+                }
+            }
+        };
+
+        // If the row is closing out terminally but no terminal event
+        // landed in the log yet (cancelled mid-stream, or the upstream
+        // closed without one), synthesise one and commit it
+        // synchronously. ?stream=true readers can then detect the
+        // terminal event from the log alone, matching the
+        // "event-log-as-truth" contract.
+        if let Some(ref buf) = event_buffer
+            && status.is_terminal()
+            && !terminal_event_persisted
+        {
+            sequence_number += 1;
+            let synth_type = match status {
+                ResponseStatus::Completed => "response.completed",
+                ResponseStatus::Failed => "response.failed",
+                ResponseStatus::Cancelled => "response.cancelled",
+                ResponseStatus::Incomplete => "response.incomplete",
+                _ => "response.completed",
+            };
+            // Resolve container_id once for the synthetic event too.
+            // Re-read if we never hit a terminal event during the
+            // stream (so `container_id_for_event` is still `None`).
+            let container_id_synth: Option<String> = match container_id_for_event.take() {
+                Some(cid) => cid,
+                None => store
+                    .get(&response_id, org_id)
+                    .await
+                    .ok()
+                    .and_then(|r| r.container_id),
+            };
+            let mut response_obj = serde_json::json!({
+                "id": response_id.clone(),
+                "status": status.as_str(),
+            });
+            if let Some(ref cid) = container_id_synth {
+                response_obj["container_id"] = Value::String(cid.clone());
+            }
+            let payload = serde_json::json!({
+                "type": synth_type,
+                "response": response_obj,
+            });
+            let synth_event = NewResponseEvent {
+                response_id: response_id.clone(),
+                sequence_number,
+                event_type: synth_type.to_string(),
+                payload,
+                created_at: Utc::now(),
+            };
+            if let Err(e) = buf.insert_sync(synth_event).await {
+                warn!(
+                    error = %e,
+                    response_id = %response_id,
+                    "Failed to commit synthetic terminal event"
+                );
+            }
+        }
+
+        if let Err(e) = store
+            .update_within_org(
+                &response_id,
+                org_id,
+                ResponseCompletion {
+                    status: Some(status),
+                    completed_at: Some(Utc::now()),
+                    output,
+                    usage,
+                    error: error_field,
+                    ..Default::default()
+                },
+            )
+            .await
+        {
+            error!(
+                error = %e,
+                response_id = %response_id,
+                "Failed to persist final response state"
+            );
+        } else {
+            info!(
+                stage = "persist_complete",
+                response_id = %response_id,
+                status = ?status,
+                "Persisted final response state"
+            );
+        }
+    });
+
+    let stream = futures_util::stream::unfold(rx, |mut rx| async move {
+        rx.recv().await.map(|item| (item, rx))
+    });
+    Response::from_parts(parts, Body::from_stream(stream))
+}
+
+/// Rewrite a terminal SSE event's `data:` payload to stamp
+/// `response.container_id`. Upstream providers don't emit this for
+/// Hadrian-hosted containers, so we inject it on the way out so the
+/// streaming surface matches what `GET /v1/responses/{id}` returns.
+///
+/// Returns `None` when the event has no parseable `data:` JSON line,
+/// or when the payload already carries a matching container_id (so
+/// passthrough_openai responses round-trip unchanged).
+fn inject_container_id_into_event(event: &[u8], container_id: &str) -> Option<Bytes> {
+    let s = std::str::from_utf8(event).ok()?;
+    let mut out = String::with_capacity(event.len() + container_id.len() + 24);
+    let mut mutated = false;
+    for line in s.split_inclusive('\n') {
+        let trimmed = line.trim_end_matches(['\r', '\n']);
+        if let Some(data) = trimmed.strip_prefix("data:") {
+            let data = data.trim_start();
+            if !data.is_empty()
+                && data != "[DONE]"
+                && let Ok(mut json) = serde_json::from_str::<Value>(data)
+                && let Some(resp) = json.get_mut("response").and_then(|r| r.as_object_mut())
+            {
+                let existing = resp
+                    .get("container_id")
+                    .and_then(|v| v.as_str())
+                    .map(str::to_string);
+                if existing.as_deref() != Some(container_id) {
+                    resp.insert(
+                        "container_id".to_string(),
+                        Value::String(container_id.to_string()),
+                    );
+                    out.push_str("data: ");
+                    out.push_str(&serde_json::to_string(&json).ok()?);
+                    // Preserve the original frame's line terminator.
+                    if line.ends_with("\r\n") {
+                        out.push_str("\r\n");
+                    } else if line.ends_with('\n') {
+                        out.push('\n');
+                    }
+                    mutated = true;
+                    continue;
+                }
+            }
+        }
+        out.push_str(line);
+    }
+    if mutated {
+        Some(Bytes::from(out))
+    } else {
+        None
+    }
+}
+
+/// Recognise an SSE event that terminates the response and carries the
+/// full final object. The Responses API emits one of:
+///   data: {"type":"response.completed","response":{...}}
+///   data: {"type":"response.failed","response":{...}}
+///   data: {"type":"response.incomplete","response":{...}}
+fn inspect_terminal_event(event: &[u8]) -> Option<(Value, ResponseStatus)> {
+    let s = std::str::from_utf8(event).ok()?;
+    // Named SSE events arrive as `event: <type>\ndata: <json>\n\n` —
+    // we must skip the `event:` (and any future header) lines instead
+    // of short-circuiting on the first non-`data:` line. A `?` on
+    // `strip_prefix` here would mean a single `event:` header in a
+    // multi-line frame silently drops the trailing terminal payload.
+    for line in s.lines() {
+        let Some(data) = line.strip_prefix("data:") else {
+            continue;
+        };
+        let data = data.trim();
+        if data.is_empty() || data == "[DONE]" {
+            continue;
+        }
+        let Ok(json) = serde_json::from_str::<Value>(data) else {
+            continue;
+        };
+        let Some(event_type) = json.get("type").and_then(|t| t.as_str()) else {
+            continue;
+        };
+        let status = match event_type {
+            "response.completed" => ResponseStatus::Completed,
+            "response.failed" => ResponseStatus::Failed,
+            "response.incomplete" => ResponseStatus::Incomplete,
+            _ => continue,
+        };
+        let response = json.get("response").cloned().unwrap_or(Value::Null);
+        return Some((response, status));
+    }
+    None
+}
+
+/// Parse one SSE event into (`event_type`, `payload`) for the event
+/// log. Best-effort: malformed events get `event_type = "unknown"`
+/// and the raw bytes as a JSON string so replay never loses data.
+fn parse_event_for_log(event: &[u8]) -> (String, Value) {
+    let Ok(s) = std::str::from_utf8(event) else {
+        // Non-UTF-8 bytes get base64-encoded so the audit log is
+        // human-pasteable (Debug-format of `bytes::Bytes` is a hex
+        // array that's hard to recover from).
+        use base64::Engine;
+        let encoded = base64::engine::general_purpose::STANDARD.encode(event);
+        return (
+            "unknown_binary".to_string(),
+            serde_json::json!({ "base64": encoded }),
+        );
+    };
+    for line in s.lines() {
+        let Some(data) = line.strip_prefix("data:") else {
+            continue;
+        };
+        let data = data.trim();
+        if data == "[DONE]" {
+            return ("done".to_string(), Value::Null);
+        }
+        let Ok(json) = serde_json::from_str::<Value>(data) else {
+            continue;
+        };
+        let event_type = json
+            .get("type")
+            .and_then(|t| t.as_str())
+            .unwrap_or("unknown")
+            .to_string();
+        return (event_type, json);
+    }
+    ("unknown".to_string(), Value::String(s.to_string()))
+}
+
+/// Persist a non-streaming final response by reading and reparsing the
+/// JSON body. Returns the bytes so the caller can also send them to
+/// the client / cache. On parse failure the response is recorded as
+/// `Failed` and the bytes are still forwarded.
+pub async fn persist_non_streaming(
+    store: &ResponsesStore,
+    response_id: &str,
+    org_id: Uuid,
+    body_bytes: &[u8],
+    http_status: u16,
+) {
+    let status = if (200..300).contains(&http_status) {
+        ResponseStatus::Completed
+    } else {
+        ResponseStatus::Failed
+    };
+    let parsed: Result<Value, _> = serde_json::from_slice(body_bytes);
+    let (output, usage, error_field) = match parsed {
+        Ok(v) => (
+            v.get("output").cloned(),
+            v.get("usage").cloned(),
+            v.get("error").cloned().filter(|v| !v.is_null()),
+        ),
+        Err(_) => (None, None, None),
+    };
+    if let Err(e) = store
+        .update_within_org(
+            response_id,
+            org_id,
+            ResponseCompletion {
+                status: Some(status),
+                completed_at: Some(Utc::now()),
+                output,
+                usage,
+                error: error_field,
+                ..Default::default()
+            },
+        )
+        .await
+    {
+        error!(error = %e, response_id, "Failed to persist non-streaming response");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn detects_terminal_event_with_event_header_prefix() {
+        // Named-SSE form: `event: response.completed\ndata: {...}\n\n`.
+        // A previous bug short-circuited on the first non-`data:` line
+        // (the `event:` header) and missed the terminal data entirely.
+        let raw = b"event: response.completed\ndata: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp_abc\",\"status\":\"completed\"}}\n\n";
+        let result = inspect_terminal_event(raw);
+        assert!(
+            result.is_some(),
+            "should detect terminal event past header line"
+        );
+        let (resp, status) = result.unwrap();
+        assert_eq!(status, ResponseStatus::Completed);
+        assert_eq!(resp.get("id").and_then(|v| v.as_str()), Some("resp_abc"));
+    }
+
+    #[test]
+    fn detects_terminal_event_data_only_form() {
+        // Plain Responses-API form without an `event:` line.
+        let raw = b"data: {\"type\":\"response.failed\",\"response\":{\"error\":\"boom\"}}\n\n";
+        let result = inspect_terminal_event(raw);
+        assert!(result.is_some());
+        assert_eq!(result.unwrap().1, ResponseStatus::Failed);
+    }
+
+    #[test]
+    fn ignores_non_terminal_events() {
+        let raw = b"data: {\"type\":\"response.output_text.delta\",\"delta\":\"hi\"}\n\n";
+        assert!(inspect_terminal_event(raw).is_none());
+    }
+
+    #[test]
+    fn ignores_done_sentinel() {
+        let raw = b"data: [DONE]\n\n";
+        assert!(inspect_terminal_event(raw).is_none());
+    }
+
+    #[test]
+    fn injects_container_id_into_terminal_event() {
+        let raw = b"event: response.completed\ndata: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp_abc\",\"status\":\"completed\"}}\n\n";
+        let out = inject_container_id_into_event(raw, "cntr_xyz").expect("should mutate");
+        let s = std::str::from_utf8(&out).unwrap();
+        assert!(s.contains("\"container_id\":\"cntr_xyz\""), "got: {s}");
+        // Header line preserved verbatim.
+        assert!(s.starts_with("event: response.completed\n"));
+    }
+
+    #[test]
+    fn injection_skipped_when_already_present() {
+        let raw = b"data: {\"type\":\"response.completed\",\"response\":{\"container_id\":\"cntr_xyz\"}}\n\n";
+        assert!(inject_container_id_into_event(raw, "cntr_xyz").is_none());
+    }
+}
diff --git a/src/services/responses_pipeline.rs b/src/services/responses_pipeline.rs
new file mode 100644
index 0000000..9b4744a
--- /dev/null
+++ b/src/services/responses_pipeline.rs
@@ -0,0 +1,908 @@
+//! Shared streaming pipeline for `/v1/responses`.
+//!
+//! Both the foreground handler (`api_v1_responses`) and the background
+//! worker need to apply the same wraps around the upstream LLM stream:
+//! output guardrails, the server-executed-tool loop runner
+//! (`file_search`, `web_search`, `shell`), and the persister. This
+//! module factors that pipeline out so both call sites stay in sync.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::sync::Arc;
+
+use axum::body::Body;
+use bytes::Bytes;
+use http::Response;
+use thiserror::Error;
+use uuid::Uuid;
+
+use crate::{
+    AppState,
+    api_types::CreateResponsesPayload,
+    auth::AuthenticatedRequest,
+    config::ProviderConfig,
+    db::repos::ResponseOwner,
+    models::{ApiKeyOwner, SKILL_MAIN_FILE},
+    routes::{
+        api::wrap_streaming_with_guardrails,
+        execution::{ProviderExecutor, ResponsesExecutor},
+    },
+    runtimes::{MountedFile, SkillMount},
+    services::{
+        FileSearchAuthContext, FileSearchContext, WebSearchContext,
+        container_session::ContainerPersistence,
+        file_search_tool::FileSearchExecutor,
+        input_file_staging::StagedFile,
+        server_tools::{ProviderCallback, ServerExecutedTool, ToolLoopRunner},
+        shell_tool::ShellExecutor,
+        web_search_tool::WebSearchExecutor,
+    },
+};
+
+/// Identity fields used by the shell tool's usage attribution.
+///
+/// Foreground builds this from the `AuthenticatedRequest`; background
+/// builds it from the persisted `ResponseRecord`. Either way the
+/// downstream wrap code looks the same.
+#[derive(Debug, Clone, Default)]
+pub struct PipelinePrincipal {
+    pub api_key_id: Option<Uuid>,
+    pub user_id: Option<Uuid>,
+    pub org_id: Option<Uuid>,
+    pub project_id: Option<Uuid>,
+    pub team_id: Option<Uuid>,
+    pub service_account_id: Option<Uuid>,
+}
+
+impl PipelinePrincipal {
+    /// Build from an HTTP auth context with sensible fallbacks to the
+    /// gateway's default user/org for unauthenticated requests.
+    pub fn from_auth(state: &AppState, auth: Option<&AuthenticatedRequest>) -> Self {
+        let api_key = auth.and_then(|a| a.api_key());
+        Self {
+            api_key_id: api_key.map(|k| k.key.id),
+            user_id: auth.and_then(|a| a.user_id()).or(state.default_user_id),
+            org_id: api_key
+                .and_then(|k| k.org_id)
+                .or_else(|| auth.and_then(|a| a.principal().org_id()))
+                .or(state.default_org_id),
+            project_id: api_key.and_then(|k| k.project_id),
+            team_id: api_key.and_then(|k| k.team_id),
+            service_account_id: api_key.and_then(|k| k.service_account_id),
+        }
+    }
+}
+
+/// Derive the canonical owner for a persisted response from the
+/// calling principal. Mirrors the ownership semantics used by other
+/// Hadrian resources (skills, templates, conversations): the response
+/// is owned by whatever scope its API key is bound to, falling back
+/// to the user for identity-based auth or the organization for
+/// anonymous / default-principal deployments.
+///
+/// Returns `None` only when no auth context is available and no
+/// `default_org_id` is configured — i.e., the gateway can't safely
+/// place the row anywhere. Callers turn that into a 401 or skip
+/// persistence, depending on the surface.
+pub fn derive_response_owner(
+    state: &AppState,
+    auth: Option<&AuthenticatedRequest>,
+) -> Option<ResponseOwner> {
+    if let Some(auth) = auth {
+        if let Some(api_key) = auth.api_key() {
+            return Some(match &api_key.key.owner {
+                ApiKeyOwner::Organization { org_id } => ResponseOwner::Organization(*org_id),
+                ApiKeyOwner::Team { team_id } => ResponseOwner::Team(*team_id),
+                ApiKeyOwner::Project { project_id } => ResponseOwner::Project(*project_id),
+                ApiKeyOwner::User { user_id } => ResponseOwner::User(*user_id),
+                ApiKeyOwner::ServiceAccount { service_account_id } => {
+                    ResponseOwner::ServiceAccount(*service_account_id)
+                }
+            });
+        }
+        if let Some(user_id) = auth.user_id() {
+            return Some(ResponseOwner::User(user_id));
+        }
+    }
+    state.default_org_id.map(ResponseOwner::Organization)
+}
+
+impl From<PipelinePrincipal> for crate::services::shell_tool::ShellPrincipal {
+    fn from(p: PipelinePrincipal) -> Self {
+        Self {
+            api_key_id: p.api_key_id,
+            user_id: p.user_id,
+            org_id: p.org_id,
+            project_id: p.project_id,
+            team_id: p.team_id,
+            service_account_id: p.service_account_id,
+        }
+    }
+}
+
+/// Errors from resolving the `skills` field on a Responses-API request.
+#[derive(Debug, Error)]
+pub enum SkillResolutionError {
+    #[error("skill id '{0}' is not a valid UUID")]
+    InvalidId(String),
+    #[error("skill '{0}' not found")]
+    NotFound(String),
+    #[error("skills require an org context; the request has no resolvable organization")]
+    MissingOrg,
+    #[error("skill service is not configured on this gateway")]
+    NoService,
+    #[error("skill lookup failed: {0}")]
+    Db(String),
+    #[error("only `version = \"latest\"` is supported (got `{0}`)")]
+    UnsupportedVersion(String),
+    #[error("inline skill `{name}` has invalid base64 data: {detail}")]
+    InvalidBase64 { name: String, detail: String },
+    #[error(
+        "inline skill `{name}` uses media_type `{media_type}` — only `text/markdown` is supported today"
+    )]
+    UnsupportedMediaType { name: String, media_type: String },
+    #[error("inline skill `{name}` payload is not valid UTF-8")]
+    InvalidUtf8 { name: String },
+    #[error("inline skill name must be non-empty")]
+    EmptyInlineName,
+}
+
+/// Resolve `payload.skills` to mountable bundles and prepend each
+/// skill's `SKILL.md` to `payload.instructions` so the model knows the
+/// skill is available.
+///
+/// Mutates `payload.instructions` in place when skills are present.
+/// Returns an empty `Vec` if `payload.skills` is `None` or empty.
+///
+/// Called from both the foreground handler and the background executor
+/// before the upstream LLM call; the returned mounts are threaded into
+/// `apply_streaming_pipeline` so the shell runtime materializes them
+/// when a shell-tool call boots a session.
+pub async fn resolve_and_inject_skills(
+    state: &AppState,
+    payload: &mut CreateResponsesPayload,
+    org_id: Option<Uuid>,
+) -> Result<Vec<SkillMount>, SkillResolutionError> {
+    let Some(ref skills) = payload.skills else {
+        return Ok(Vec::new());
+    };
+    if skills.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let mut mounts = Vec::with_capacity(skills.len());
+    let mut preamble_sections = Vec::with_capacity(skills.len());
+
+    for entry in skills {
+        let mount = resolve_one_skill(state, org_id, entry).await?;
+        let preamble = mount.build_preamble();
+        preamble_sections.push(preamble);
+        mounts.push(mount.into_skill_mount());
+    }
+
+    if !preamble_sections.is_empty() {
+        let preamble = format!(
+            "The following skills are mounted in the sandbox. Use the files at the indicated paths when relevant.\n\n{}",
+            preamble_sections.join("\n\n---\n\n")
+        );
+        payload.instructions = Some(match payload.instructions.take() {
+            Some(existing) if !existing.trim().is_empty() => format!("{preamble}\n\n{existing}"),
+            _ => preamble,
+        });
+    }
+
+    Ok(mounts)
+}
+
+/// Intermediate form between a parsed `RequestSkill` and a runtime
+/// `SkillMount`. Carries the display-name + description so we can
+/// build a consistent preamble section regardless of whether the
+/// skill came from the database or an inline bundle.
+#[derive(Debug)]
+struct ResolvedSkill {
+    skill_id: String,
+    name: String,
+    description: String,
+    mount_path: String,
+    files: Vec<MountedFile>,
+    /// `SKILL.md` content when present — used to embed in the preamble.
+    main_content: Option<String>,
+}
+
+impl ResolvedSkill {
+    fn build_preamble(&self) -> String {
+        match &self.main_content {
+            Some(content) => format!(
+                "## Skill: {name}\n{description}\n\nFiles available under: {mount_path}/\n\n{content}",
+                name = self.name,
+                description = self.description,
+                mount_path = self.mount_path,
+                content = content,
+            ),
+            None => format!(
+                "## Skill: {name}\n{description}\n\nFiles available under: {mount_path}/",
+                name = self.name,
+                description = self.description,
+                mount_path = self.mount_path,
+            ),
+        }
+    }
+
+    fn into_skill_mount(self) -> SkillMount {
+        SkillMount {
+            skill_id: self.skill_id,
+            mount_path: self.mount_path,
+            files: self.files,
+        }
+    }
+}
+
+async fn resolve_one_skill(
+    state: &AppState,
+    org_id: Option<Uuid>,
+    entry: &crate::api_types::RequestSkill,
+) -> Result<ResolvedSkill, SkillResolutionError> {
+    match entry {
+        crate::api_types::RequestSkill::SkillReference(reference) => {
+            // Version pin: only `latest` (and the absence of a value)
+            // are honored today. Reject anything else loudly so callers
+            // discover the gap instead of silently getting `latest`.
+            if let Some(v) = reference.version.as_deref()
+                && v != "latest"
+            {
+                return Err(SkillResolutionError::UnsupportedVersion(v.to_string()));
+            }
+            let services = state
+                .services
+                .as_ref()
+                .ok_or(SkillResolutionError::NoService)?;
+            let org = org_id.ok_or(SkillResolutionError::MissingOrg)?;
+            let id = Uuid::parse_str(&reference.skill_id)
+                .map_err(|_| SkillResolutionError::InvalidId(reference.skill_id.clone()))?;
+            let skill = services
+                .skills
+                .get_by_id_and_org(id, org)
+                .await
+                .map_err(|e| SkillResolutionError::Db(e.to_string()))?
+                .ok_or_else(|| SkillResolutionError::NotFound(reference.skill_id.clone()))?;
+
+            let mount_path = format!("/skills/{}", skill.id);
+            let main_content = skill
+                .files
+                .iter()
+                .find(|f| f.path == SKILL_MAIN_FILE)
+                .map(|f| f.content.clone());
+            let files = skill
+                .files
+                .iter()
+                .map(|f| MountedFile {
+                    relative_path: f.path.clone(),
+                    content: Bytes::from(f.content.clone().into_bytes()),
+                })
+                .collect();
+            Ok(ResolvedSkill {
+                skill_id: skill.id.to_string(),
+                name: skill.name,
+                description: skill.description,
+                mount_path,
+                files,
+                main_content,
+            })
+        }
+        crate::api_types::RequestSkill::Inline(inline) => resolve_inline_skill(inline),
+    }
+}
+
+fn resolve_inline_skill(
+    inline: &crate::api_types::InlineSkill,
+) -> Result<ResolvedSkill, SkillResolutionError> {
+    if inline.name.trim().is_empty() {
+        return Err(SkillResolutionError::EmptyInlineName);
+    }
+    let crate::api_types::InlineSkillSource::Base64 { media_type, data } = &inline.source;
+    if media_type != "text/markdown" {
+        return Err(SkillResolutionError::UnsupportedMediaType {
+            name: inline.name.clone(),
+            media_type: media_type.clone(),
+        });
+    }
+    use base64::Engine as _;
+    let bytes = base64::engine::general_purpose::STANDARD
+        .decode(data.as_bytes())
+        .map_err(|e| SkillResolutionError::InvalidBase64 {
+            name: inline.name.clone(),
+            detail: e.to_string(),
+        })?;
+    let content = String::from_utf8(bytes).map_err(|_| SkillResolutionError::InvalidUtf8 {
+        name: inline.name.clone(),
+    })?;
+    // Synthetic per-request id derived from the payload hash so the
+    // mount path is stable across foreground/background dispatch but
+    // doesn't collide with stored skill UUIDs.
+    let synthetic_id = inline_skill_synthetic_id(&inline.name, &content);
+    let mount_path = format!("/skills/{synthetic_id}");
+    let files = vec![MountedFile {
+        relative_path: SKILL_MAIN_FILE.to_string(),
+        content: Bytes::from(content.clone().into_bytes()),
+    }];
+    Ok(ResolvedSkill {
+        skill_id: synthetic_id,
+        name: inline.name.clone(),
+        description: inline.description.clone(),
+        mount_path,
+        files,
+        main_content: Some(content),
+    })
+}
+
+/// Synthetic id used as the mount-path segment for inline skills.
+/// Hash-based so the same payload reuses the same path across the
+/// foreground / background lanes (otherwise the response that resumes
+/// from a background tick would mount the skill at a different path).
+fn inline_skill_synthetic_id(name: &str, content: &str) -> String {
+    use std::hash::{DefaultHasher, Hash, Hasher};
+    let mut hasher = DefaultHasher::new();
+    name.hash(&mut hasher);
+    content.hash(&mut hasher);
+    format!("skill_inline_{:016x}", hasher.finish())
+}
+
+/// Wrap a streaming Responses-API response with the full server-side
+/// pipeline: output guardrails, the server-executed tool loop
+/// (`file_search` / `web_search` / `shell`), and the persister.
+///
+/// Wrap order matches the foreground handler: guardrails first so the
+/// tool loop and persister only ever see content that has passed the
+/// filter.
+///
+/// `request_id` is forwarded to guardrails for audit-log correlation.
+/// Background callers pass the response_id; foreground passes the
+/// HTTP request_id. Either way it's only used as a tracing tag.
+///
+/// `persistence`: when `Some`, the response is also wrapped with
+/// `wrap_streaming_with_persistence`. Background callers always supply
+/// this (they pre-created the row); foreground also supplies it when
+/// `store=true`. Carries the row's `org_id` so persistence writes are
+/// tenant-scoped — a stale or wrong id can't punch into another org.
+#[allow(clippy::too_many_arguments)] // each arg is load-bearing; bundling adds no clarity
+pub fn apply_streaming_pipeline(
+    state: &AppState,
+    payload: &CreateResponsesPayload,
+    provider_name: String,
+    provider_config: ProviderConfig,
+    model_name: String,
+    principal: PipelinePrincipal,
+    mounted_skills: Vec<SkillMount>,
+    staged_input_files: Vec<StagedFile>,
+    response_owner: Option<ResponseOwner>,
+    // `container_id_hint`: pre-resolved container id this response
+    // should attach to (or create under). Derived from
+    // `previous_response_id` chaining upstream; `None` falls back to
+    // the executor allocating a fresh id on first use.
+    container_id_hint: Option<String>,
+    // `resolved_shell_env`: per-request shell `environment` block
+    // already intersected with `[features.server_tools.shell_limits]`
+    // upstream. Foreground and background callers both validate at
+    // request-acceptance time so an out-of-bounds request can't even
+    // be queued — by the time we get here it's known-safe.
+    resolved_shell_env: crate::services::shell_tool::ResolvedShellEnvironment,
+    request_id: Option<String>,
+    response: Response<Body>,
+    persistence: Option<PersistenceHandle>,
+) -> Response<Body> {
+    if !response.status().is_success() {
+        return response;
+    }
+
+    // ── Output guardrails ───────────────────────────────────────
+    // Wrap first so the tool loop and persister only see content
+    // that's already passed the filter. `wrap_streaming_with_guardrails`
+    // is a no-op when the response isn't actually a streaming SSE
+    // body, so it's safe to call unconditionally.
+    let response = if let Some(ref output_guardrails) = state.output_guardrails {
+        let user_id_str = principal.user_id.map(|id| id.to_string());
+        wrap_streaming_with_guardrails(response, output_guardrails, user_id_str, request_id)
+    } else {
+        response
+    };
+
+    // ── Tool runner ─────────────────────────────────────────────
+    let mut tools: Vec<Arc<dyn ServerExecutedTool>> = Vec::new();
+
+    if let Some(ref file_search_service) = state.file_search_service
+        && let Some(ref file_search_config) = state.config.features.file_search
+        && file_search_config.enabled
+    {
+        let file_search_tools: Vec<_> = payload
+            .tools
+            .as_ref()
+            .map(|t| {
+                t.iter()
+                    .filter_map(|tt| tt.as_file_search().cloned())
+                    .collect()
+            })
+            .unwrap_or_default();
+        if !file_search_tools.is_empty() {
+            // Build a synthetic FileSearchAuthContext from the
+            // principal so the same ACL scoping works for foreground
+            // and background calls.
+            let file_search_auth = FileSearchAuthContext {
+                user_id: principal.user_id,
+                org_id: principal.org_id,
+                project_id: principal.project_id,
+                identity_org_ids: Vec::new(),
+                identity_project_ids: Vec::new(),
+            };
+            let context = FileSearchContext::new(
+                file_search_service.clone(),
+                file_search_config.clone(),
+                Some(file_search_auth),
+                file_search_tools,
+                payload.clone(),
+            );
+            tools.push(Arc::new(FileSearchExecutor::new(context)));
+        }
+    }
+
+    if let Some(ref web_search_config) = state.config.features.web_search {
+        let has_web_search = payload
+            .tools
+            .as_ref()
+            .map(|t| t.iter().any(|tt| tt.is_web_search()))
+            .unwrap_or(false);
+        if has_web_search {
+            let context = WebSearchContext::new(
+                state.http_client.clone(),
+                web_search_config.clone(),
+                state.config.features.server_tools.max_iterations,
+            );
+            tools.push(Arc::new(WebSearchExecutor::new(context)));
+        }
+    }
+
+    if let Some(ref shell_runtime) = state.shell_runtime {
+        let has_shell = payload
+            .tools
+            .as_ref()
+            .map(|t| t.iter().any(|tt| tt.is_shell()))
+            .unwrap_or(false);
+        if has_shell && !shell_runtime.capabilities().passthrough_only {
+            // The two passthrough variants are filtered out by the
+            // `passthrough_only` guard above; the `None` arm is unreachable
+            // because `shell_runtime` would have been `None` too. They're
+            // listed for match exhaustiveness only.
+            let (rate, label) = match &state.config.features.shell {
+                crate::config::ShellRuntimeConfig::None
+                | crate::config::ShellRuntimeConfig::PassthroughOpenAI
+                | crate::config::ShellRuntimeConfig::ClientPassthrough => (0, "unknown"),
+                #[cfg(feature = "runtime-microsandbox")]
+                crate::config::ShellRuntimeConfig::Microsandbox(_) => (
+                    state
+                        .config
+                        .features
+                        .server_tools
+                        .pricing
+                        .microsandbox_microcents_per_second,
+                    "microsandbox",
+                ),
+                #[cfg(feature = "runtime-opensandbox")]
+                crate::config::ShellRuntimeConfig::OpenSandbox(_) => (0, "opensandbox"),
+            };
+            // Build the optional ContainerPersistence handle. All three
+            // ingredients must be present: the gateway has a DB (so a
+            // ContainersService was constructed), the caller derived a
+            // ResponseOwner from auth, and the principal carries an
+            // org id. When any is missing we run in-memory only — the
+            // live response still works, but `/v1/containers/*`
+            // returns 404 for files captured under this session.
+            let persistence = match (
+                state.containers_service.as_ref(),
+                response_owner,
+                principal.org_id,
+            ) {
+                (Some(svc), Some(owner), Some(org_id)) => Some(ContainerPersistence {
+                    service: svc.clone(),
+                    org_id,
+                    owner,
+                    source_response_id: persistence.as_ref().map(|h| h.response_id.clone()),
+                }),
+                _ => None,
+            };
+            tools.push(Arc::new(ShellExecutor::new(
+                shell_runtime.clone(),
+                rate,
+                label,
+                principal.clone().into(),
+                mounted_skills,
+                state.config.features.server_tools.shell_limits.clone(),
+                resolved_shell_env.clone(),
+                state.config.features.containers.clone(),
+                staged_input_files,
+                persistence,
+                state.container_session_registry.clone(),
+                container_id_hint,
+                #[cfg(feature = "concurrency")]
+                state.usage_buffer.clone(),
+            )));
+        }
+    }
+
+    // MCP tool executor — engages when `[features.mcp].mode =
+    // hadrian_hosted` is configured and the request carries any
+    // `mcp` tool entries. Under `passthrough_openai` the upstream
+    // (OpenAI/Azure) runs the MCP loop and we don't register here.
+    #[cfg(feature = "mcp")]
+    {
+        if let (Some(mcp_cfg), Some(mcp_service)) = (
+            state.config.features.mcp.as_ref(),
+            state.mcp_service.as_ref(),
+        ) && mcp_cfg.is_hadrian_hosted()
+        {
+            // Thread persistence context through so the approval gate
+            // can park calls. Both response_id and org_id must be
+            // present for parking to work; the executor degrades to
+            // warn-and-run otherwise.
+            let response_id = persistence.as_ref().map(|h| h.response_id.clone());
+            let org_id = principal.org_id;
+            let executor = crate::services::mcp::McpExecutor::with_persistence(
+                mcp_service.clone(),
+                payload,
+                response_id,
+                org_id,
+                mcp_cfg.call_timeout_secs,
+            );
+            if executor.has_bindings() {
+                tools.push(Arc::new(executor));
+            }
+
+            // Hadrian-side tool search for any `defer_loading` servers.
+            // Registered after the MCP executor so its continuation pass
+            // (which appends function-call outputs) runs first.
+            let tool_search = crate::services::mcp::ToolSearchExecutor::new(
+                mcp_service.clone(),
+                payload,
+                &mcp_cfg.tool_search,
+                state.tool_search_embeddings.clone(),
+            );
+            if tool_search.has_deferred() {
+                tools.push(Arc::new(tool_search));
+            }
+        }
+    }
+
+    let after_tools = if tools.is_empty() {
+        response
+    } else {
+        let callback_state = state.clone();
+        let callback_provider_name = provider_name.clone();
+        let callback_provider_config = provider_config.clone();
+        let callback_model_name = model_name.clone();
+        let provider_callback: ProviderCallback = Arc::new(move |payload| {
+            let state = callback_state.clone();
+            let provider_name = callback_provider_name.clone();
+            let provider_config = callback_provider_config.clone();
+            let model_name = callback_model_name.clone();
+            Box::pin(async move {
+                let mut payload = payload;
+                payload.model = Some(model_name);
+                ResponsesExecutor::execute(&state, &provider_name, &provider_config, payload).await
+            })
+        });
+        let max_iterations = state.config.features.server_tools.max_iterations;
+        // Every server tool synthesizes its own spec-shaped output items
+        // (web_search_call / file_search_call / shell_call / mcp_call …)
+        // and suppresses the rewritten function-call plumbing via
+        // `transform_event`. Turning on the stream rewriter makes the
+        // runner own a single monotonic sequence_number / output_index
+        // space and reconstruct the terminal `response.output` from the
+        // items it actually forwards — so the persisted/retrieved
+        // response carries the hosted-tool items the client saw, not the
+        // provider's last-turn view or the internal function calls.
+        let mut runner = ToolLoopRunner::new(payload.clone(), max_iterations)
+            .with_provider_callback(provider_callback)
+            .rewrite_output(true);
+        // Restore the caller's original `mcp` tool entries on the echoed
+        // `response.tools`. The `hadrian_hosted` rewrite expanded each `mcp`
+        // entry into N `mcp_<label>__<tool>` function tools before the
+        // provider call; without this the provider echoes those internal
+        // functions instead of the `mcp` tool the caller sent.
+        #[cfg(feature = "mcp")]
+        {
+            let echo = build_mcp_tool_echo(payload);
+            if !echo.is_empty() {
+                runner = runner.with_mcp_tool_echo(echo);
+            }
+        }
+        // Stamp the persisted response id onto lifecycle events so the
+        // streamed id is stable across turns and matches what's
+        // retrievable via GET /v1/responses/{id}.
+        if let Some(handle) = persistence.as_ref() {
+            runner = runner.with_response_id(handle.response_id.clone());
+        }
+        for tool in tools {
+            runner = runner.register(tool);
+        }
+        runner.wrap_streaming(response)
+    };
+
+    // ── Persistence wrap ───────────────────────────────────────
+    if let (Some(handle), Some(store)) = (persistence, state.responses_store.as_ref()) {
+        crate::services::response_persister::wrap_streaming_with_persistence(
+            after_tools,
+            store.clone(),
+            handle.response_id,
+            handle.org_id,
+            handle.initial_sequence_number,
+            handle.cancel_rx,
+            state.response_event_buffer.clone(),
+        )
+    } else {
+        after_tools
+    }
+}
+
+/// Build the `(function-name prefix, original tool JSON)` pairs the runner
+/// uses to collapse rewritten MCP function tools back into the caller's
+/// original `mcp` entry on the echoed `response.tools`. The `authorization`
+/// bearer is stripped — it must never be echoed back (and thereby persisted)
+/// on the stored response. Returns empty when the payload carries no `mcp`
+/// tools.
+#[cfg(feature = "mcp")]
+fn build_mcp_tool_echo(payload: &CreateResponsesPayload) -> Vec<(String, serde_json::Value)> {
+    use crate::services::mcp::synthesize_function_name;
+    let Some(tools) = payload.tools.as_ref() else {
+        return Vec::new();
+    };
+    let mut out = Vec::new();
+    for tool in tools {
+        let Some(mcp) = tool.as_mcp() else {
+            continue;
+        };
+        let Ok(mut value) = serde_json::to_value(mcp) else {
+            continue;
+        };
+        if let Some(obj) = value.as_object_mut() {
+            obj.remove("authorization");
+        }
+        out.push((synthesize_function_name(&mcp.server_label, ""), value));
+    }
+    out
+}
+
+/// Plumbing handle for the persister wrap. Bundles the row's id and
+/// `org_id` together so the persister can issue tenant-scoped writes
+/// without re-loading the row.
+pub struct PersistenceHandle {
+    pub response_id: String,
+    pub org_id: Uuid,
+    /// Last sequence number already in the event log for this
+    /// response. The persister starts incrementing from this so a
+    /// re-attach can't collide on the `(response_id, sequence_number)`
+    /// primary key.
+    pub initial_sequence_number: i64,
+    pub cancel_rx: crate::services::CancelSignal,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Non-streaming bridge
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Collect a streaming Responses-API SSE body into a single JSON object
+/// matching the OpenAI non-streaming response shape.
+///
+/// Walks each `data:` event and:
+///   - pushes every `response.output_item.done` `item` onto `output[]`,
+///     so the caller sees the full transcript across all server-tool
+///     iterations (function_call + shell_call_output + final message);
+///   - takes the terminal `response.completed` / `response.failed` /
+///     `response.incomplete` event's `response` object as the metadata
+///     envelope (id, model, status, error, etc.);
+///   - sums `usage` across every terminal event observed so the
+///     reported tokens and cost reflect the entire agent loop, not the
+///     final turn alone.
+///
+/// Non-success or non-SSE responses pass through unchanged.
+pub async fn collect_streaming_response_to_json(response: Response<Body>) -> Response<Body> {
+    if !response.status().is_success() {
+        return response;
+    }
+    let is_sse = response
+        .headers()
+        .get(http::header::CONTENT_TYPE)
+        .and_then(|v| v.to_str().ok())
+        .is_some_and(|ct| ct.starts_with("text/event-stream"));
+    if !is_sse {
+        return response;
+    }
+
+    let (mut parts, body) = response.into_parts();
+    // The pipeline produces bounded SSE bodies (the runner terminates
+    // when the model stops calling tools or the iteration budget is
+    // hit), so `usize::MAX` is fine here — we already trust the
+    // upstream's per-call output size limits.
+    let bytes = match axum::body::to_bytes(body, usize::MAX).await {
+        Ok(b) => b,
+        Err(e) => {
+            tracing::error!(
+                stage = "collect_buffered_failed",
+                error = %e,
+                "Failed to read streaming body for non-streaming bridge"
+            );
+            return Response::builder()
+                .status(http::StatusCode::BAD_GATEWAY)
+                .body(Body::empty())
+                .unwrap_or_else(|_| Response::new(Body::empty()));
+        }
+    };
+
+    let mut output_items: Vec<serde_json::Value> = Vec::new();
+    let mut terminal_response: Option<serde_json::Value> = None;
+    let mut usage_sum: Option<crate::api_types::responses::ResponsesUsage> = None;
+
+    for line in bytes.split(|b| *b == b'\n') {
+        let Ok(line_str) = std::str::from_utf8(line) else {
+            continue;
+        };
+        let Some(data) = line_str.strip_prefix("data:").map(str::trim) else {
+            continue;
+        };
+        if data.is_empty() || data == "[DONE]" {
+            continue;
+        }
+        let Ok(value) = serde_json::from_str::<serde_json::Value>(data) else {
+            continue;
+        };
+        let event_type = value.get("type").and_then(|t| t.as_str());
+        match event_type {
+            Some("response.output_item.done") => {
+                if let Some(item) = value.get("item").cloned() {
+                    output_items.push(item);
+                }
+            }
+            Some("response.completed" | "response.failed" | "response.incomplete") => {
+                if let Some(resp) = value.get("response").cloned() {
+                    if let Some(usage_val) = resp.get("usage")
+                        && let Ok(usage) = serde_json::from_value::<
+                            crate::api_types::responses::ResponsesUsage,
+                        >(usage_val.clone())
+                    {
+                        match usage_sum.as_mut() {
+                            None => usage_sum = Some(usage),
+                            Some(acc) => add_usage(acc, &usage),
+                        }
+                    }
+                    terminal_response = Some(resp);
+                }
+            }
+            _ => {}
+        }
+    }
+
+    let mut response_obj = match terminal_response {
+        Some(r) => r,
+        None => {
+            tracing::warn!(
+                stage = "collect_buffered_no_terminal",
+                "No response.completed event in stream; falling back to passthrough"
+            );
+            return Response::from_parts(parts, Body::from(bytes));
+        }
+    };
+    response_obj["output"] = serde_json::Value::Array(output_items);
+    if let Some(usage) = usage_sum
+        && let Ok(usage_val) = serde_json::to_value(&usage)
+    {
+        response_obj["usage"] = usage_val;
+    }
+    let body_bytes = match serde_json::to_vec(&response_obj) {
+        Ok(b) => b,
+        Err(e) => {
+            tracing::error!(
+                stage = "collect_buffered_serialize_failed",
+                error = %e,
+                "Failed to serialize collected response JSON"
+            );
+            return Response::builder()
+                .status(http::StatusCode::INTERNAL_SERVER_ERROR)
+                .body(Body::empty())
+                .unwrap_or_else(|_| Response::new(Body::empty()));
+        }
+    };
+
+    parts.headers.insert(
+        http::header::CONTENT_TYPE,
+        http::HeaderValue::from_static("application/json"),
+    );
+    // Strip every header that says "this body is being streamed" — once
+    // we've buffered the SSE stream into a fixed JSON blob, hyper will
+    // emit the correct Content-Length itself, and leaving any of these
+    // in place produces a malformed HTTP frame that hyper closes the
+    // connection on (manifests as "Empty reply from server" on the
+    // client).
+    parts.headers.remove(http::header::CONTENT_LENGTH);
+    parts.headers.remove(http::header::TRANSFER_ENCODING);
+    parts.headers.remove(http::header::CACHE_CONTROL);
+    parts.headers.remove("x-accel-buffering");
+    Response::from_parts(parts, Body::from(body_bytes))
+}
+
+fn add_usage(
+    acc: &mut crate::api_types::responses::ResponsesUsage,
+    add: &crate::api_types::responses::ResponsesUsage,
+) {
+    acc.accumulate(add);
+}
+
+#[cfg(test)]
+mod skill_tests {
+    use base64::Engine as _;
+
+    use super::*;
+    use crate::api_types::{InlineSkill, InlineSkillSource};
+
+    #[test]
+    fn inline_markdown_skill_resolves_to_skill_md() {
+        let payload = "# Useful skill\n\nDo a thing.";
+        let encoded = base64::engine::general_purpose::STANDARD.encode(payload.as_bytes());
+        let inline = InlineSkill {
+            name: "useful".into(),
+            description: "Does a thing".into(),
+            source: InlineSkillSource::Base64 {
+                media_type: "text/markdown".into(),
+                data: encoded,
+            },
+        };
+        let mount = resolve_inline_skill(&inline).expect("should resolve");
+        assert!(mount.skill_id.starts_with("skill_inline_"));
+        assert_eq!(mount.mount_path, format!("/skills/{}", mount.skill_id));
+        assert_eq!(mount.files.len(), 1);
+        assert_eq!(mount.files[0].relative_path, SKILL_MAIN_FILE);
+        assert_eq!(
+            std::str::from_utf8(&mount.files[0].content).unwrap(),
+            payload
+        );
+        let preamble = mount.build_preamble();
+        assert!(preamble.contains("## Skill: useful"));
+        assert!(preamble.contains(payload));
+    }
+
+    #[test]
+    fn inline_rejects_unsupported_media_type() {
+        let inline = InlineSkill {
+            name: "useful".into(),
+            description: "x".into(),
+            source: InlineSkillSource::Base64 {
+                media_type: "application/zip".into(),
+                data: "AAAA".into(),
+            },
+        };
+        let err = resolve_inline_skill(&inline).expect_err("should fail");
+        assert!(
+            matches!(err, SkillResolutionError::UnsupportedMediaType { .. }),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn inline_rejects_invalid_base64() {
+        let inline = InlineSkill {
+            name: "x".into(),
+            description: "x".into(),
+            source: InlineSkillSource::Base64 {
+                media_type: "text/markdown".into(),
+                data: "not valid base64 !!!".into(),
+            },
+        };
+        let err = resolve_inline_skill(&inline).expect_err("should fail");
+        assert!(matches!(err, SkillResolutionError::InvalidBase64 { .. }));
+    }
+
+    #[test]
+    fn inline_synthetic_id_stable_for_same_payload() {
+        let a = inline_skill_synthetic_id("foo", "bar");
+        let b = inline_skill_synthetic_id("foo", "bar");
+        assert_eq!(a, b);
+        let c = inline_skill_synthetic_id("foo", "different");
+        assert_ne!(a, c);
+    }
+}
diff --git a/src/services/responses_store.rs b/src/services/responses_store.rs
new file mode 100644
index 0000000..18d0f88
--- /dev/null
+++ b/src/services/responses_store.rs
@@ -0,0 +1,362 @@
+//! Service layer for persisted Responses API records.
+//!
+//! Wraps `ResponsesRepo` with:
+//! - Response ID generation (`resp_<base32>` to match OpenAI's pattern)
+//! - Retention-window computation from config
+//! - In-process cancellation signaling — each persisted response maps
+//!   to a `tokio::sync::watch` channel that the streaming pipeline can
+//!   listen to so `POST /v1/responses/{id}/cancel` can abort in-flight
+//!   execution as well as updating the DB row.
+//!
+//! Naming this module `responses_store` (not just `responses`) avoids a
+//! collision with the existing `api_types::responses` import surface.
+
+use std::{collections::HashMap, sync::Arc, time::Duration as StdDuration};
+
+use chrono::{DateTime, Duration, Utc};
+use thiserror::Error;
+use tokio::sync::{Mutex, watch};
+use uuid::Uuid;
+
+use crate::{
+    db::{
+        DbError, DbPool,
+        repos::{NewResponse, ResponseCompletion, ResponseRecord, ResponseStatus, ResponsesRepo},
+    },
+    services::responses_webhook::ResponsesWebhookDispatcher,
+};
+
+#[derive(Debug, Error)]
+pub enum ResponsesStoreError {
+    #[error("response not found")]
+    NotFound,
+    #[error("response is not background and cannot be cancelled")]
+    NotBackground,
+    #[error("database error: {0}")]
+    Database(#[from] DbError),
+    #[error("internal error: {0}")]
+    Internal(String),
+}
+
+pub type ResponsesStoreResult<T> = Result<T, ResponsesStoreError>;
+
+/// Cancellation signal for a single in-flight response. The streaming
+/// pipeline holds a `watch::Receiver<bool>` and polls it; the cancel
+/// route handler flips it via the matching `Sender`.
+///
+/// # Cross-replica cancel protocol
+///
+/// A single response can be created on replica A, executed on replica
+/// B (by the background worker after `claim_queued`), and cancelled
+/// on replica C (because the user retried the cancel POST against a
+/// different load-balancer target). The in-process `cancel_senders`
+/// map only knows about its local replica's executions, so the cancel
+/// has to flow through the database. The protocol is:
+///
+/// 1. Replica C's `cancel()` handler flips the in-process flag (no-op
+///    on C if the row isn't executing there) AND writes
+///    `status='cancelled'` to the DB.
+/// 2. On every replica, [`jobs::responses_cancel_poller`] periodically
+///    queries `WHERE status='cancelled' AND id IN (active set)` against
+///    the `responses` table and trips the matching local cancel sender.
+/// 3. On replica B (the executor), the cancel sender fires, the
+///    persister's `tokio::select!` on `cancel_rx.changed()` wins, the
+///    stream terminates, and a synthetic `response.cancelled` event is
+///    appended to the log so polling clients converge to the same view.
+///
+/// **Why a poller and not a notify/listen channel?** Hadrian deploys
+/// equally on SQLite (no LISTEN/NOTIFY) and Postgres; one batched
+/// query per cycle is one DB round-trip regardless of in-flight count
+/// and avoids per-execution polling tasks. The cancel latency floor is
+/// `[features.responses]` cleanup_interval bounded by `POLL_INTERVAL`
+/// in the poller job (currently 5s).
+///
+/// **What happens between the cancel and the poller tick?** The DB
+/// row already says `cancelled`; new `GET /v1/responses/{id}` calls
+/// see the terminal state immediately. The executor on replica B keeps
+/// streaming until the poller fires, at which point the persister
+/// truncates the stream and writes the synthetic terminal event. The
+/// row's `status` doesn't flip back to in_progress in the interim.
+pub type CancelSignal = watch::Receiver<bool>;
+
+/// Service for persisted Responses API records.
+#[derive(Clone)]
+pub struct ResponsesStore {
+    repo: Arc<dyn ResponsesRepo>,
+    retention: StdDuration,
+    /// Per-response cancellation senders. Removed when the response
+    /// reaches a terminal state.
+    cancel_senders: Arc<Mutex<HashMap<String, watch::Sender<bool>>>>,
+    /// Optional webhook fired on terminal-state transitions.
+    webhook: Option<ResponsesWebhookDispatcher>,
+}
+
+impl ResponsesStore {
+    pub fn new(db: Arc<DbPool>, retention: StdDuration) -> Self {
+        Self {
+            repo: db.responses(),
+            retention,
+            cancel_senders: Arc::new(Mutex::new(HashMap::new())),
+            webhook: None,
+        }
+    }
+
+    /// Attach a webhook dispatcher. Fired once per response when the
+    /// row first transitions into a terminal state.
+    pub fn with_webhook(mut self, webhook: ResponsesWebhookDispatcher) -> Self {
+        self.webhook = Some(webhook);
+        self
+    }
+
+    /// Look up an active cancel signal for a given response. Returns
+    /// `None` when the row has already reached a terminal state, was
+    /// never created in this process (e.g. claimed across a restart),
+    /// or doesn't exist. Background workers should fall back to
+    /// status-polling in those cases.
+    pub async fn subscribe_cancel(&self, response_id: &str) -> Option<CancelSignal> {
+        self.cancel_senders
+            .lock()
+            .await
+            .get(response_id)
+            .map(|sender| sender.subscribe())
+    }
+
+    /// Register an in-flight execution that didn't go through
+    /// `create()` on this replica — e.g., a background worker that
+    /// just claimed a row created on another replica or before a
+    /// restart. Returns a receiver that the local replica-wide cancel
+    /// poller can trip via `trip_cancel_in_process`. Idempotent:
+    /// returns a subscriber on the existing sender if the id is
+    /// already registered.
+    pub async fn register_external_execution(&self, response_id: &str) -> CancelSignal {
+        let mut senders = self.cancel_senders.lock().await;
+        if let Some(existing) = senders.get(response_id) {
+            return existing.subscribe();
+        }
+        let (tx, rx) = watch::channel(false);
+        senders.insert(response_id.to_string(), tx);
+        rx
+    }
+
+    /// Generate a new response ID matching OpenAI's `resp_<random>`
+    /// pattern. The random suffix is a base32-encoded UUID (no padding,
+    /// lowercase) to be URL-safe.
+    pub fn new_response_id() -> String {
+        let bytes = Uuid::new_v4().into_bytes();
+        let mut suffix = String::with_capacity(26);
+        const ALPHABET: &[u8] = b"abcdefghijklmnopqrstuvwxyz234567";
+        let mut buffer = 0u64;
+        let mut bits = 0u8;
+        for byte in &bytes {
+            buffer = (buffer << 8) | (*byte as u64);
+            bits += 8;
+            while bits >= 5 {
+                bits -= 5;
+                let idx = ((buffer >> bits) & 0x1f) as usize;
+                suffix.push(ALPHABET[idx] as char);
+            }
+        }
+        if bits > 0 {
+            let idx = ((buffer << (5 - bits)) & 0x1f) as usize;
+            suffix.push(ALPHABET[idx] as char);
+        }
+        format!("resp_{suffix}")
+    }
+
+    /// Compute the retention timestamp from `now()` plus the configured
+    /// retention window. Terminal records are eligible for deletion
+    /// past this time.
+    pub fn retention_expires_at(&self, from: DateTime<Utc>) -> DateTime<Utc> {
+        from + Duration::from_std(self.retention).unwrap_or_else(|_| Duration::seconds(86_400))
+    }
+
+    /// Insert a fresh response row. Returns the record and a
+    /// cancellation receiver the caller should pass into the streaming
+    /// pipeline so `cancel()` can interrupt mid-flight execution.
+    pub async fn create(
+        &self,
+        input: NewResponse,
+    ) -> ResponsesStoreResult<(ResponseRecord, CancelSignal)> {
+        let record = self.repo.insert(input.clone()).await?;
+        let (tx, rx) = watch::channel(false);
+        self.cancel_senders
+            .lock()
+            .await
+            .insert(record.id.clone(), tx);
+        Ok((record, rx))
+    }
+
+    /// Patch a response's lifecycle fields. Tenant-scoped: a wrong
+    /// `org_id` returns `NotFound` rather than writing into someone
+    /// else's row.
+    ///
+    /// Terminal transitions go through the DB-guarded
+    /// [`ResponsesRepo::complete_within_org`], which only matches a
+    /// non-terminal row. This makes the transition atomic: a late
+    /// `completed` write from the persister can't clobber an earlier
+    /// `cancelled` (lost-cancel), and exactly-once webhook firing is
+    /// driven off whether *this* call actually flipped the row — never
+    /// a read-then-write that two racing writers could both pass.
+    pub async fn update_within_org(
+        &self,
+        id: &str,
+        org_id: Uuid,
+        mut patch: ResponseCompletion,
+    ) -> ResponsesStoreResult<ResponseRecord> {
+        let to_terminal = patch.status.is_some_and(|s| s.is_terminal());
+        if !to_terminal {
+            // Non-terminal patch (started_at, container_id, …): plain update.
+            return self
+                .repo
+                .update_within_org(id, org_id, patch)
+                .await?
+                .ok_or(ResponsesStoreError::NotFound);
+        }
+
+        // When transitioning to a terminal state we also stamp the
+        // retention expiry so the cleanup worker has a deadline.
+        if patch.retention_expires_at.is_none() {
+            patch.retention_expires_at = Some(self.retention_expires_at(Utc::now()));
+        }
+        match self.repo.complete_within_org(id, org_id, patch).await? {
+            // We won the race to flip the row terminal: drop the cancel
+            // sender and fire the webhook exactly once.
+            Some(record) => {
+                self.cancel_senders.lock().await.remove(id);
+                if let Some(ref webhook) = self.webhook {
+                    webhook.enqueue(record.id.clone(), record.status, record.background);
+                }
+                Ok(record)
+            }
+            // Row was already terminal (lost race) or wrong org. Don't
+            // overwrite, don't fire the webhook — return the current
+            // record (NotFound if it doesn't exist in this org).
+            None => self
+                .repo
+                .get_by_id_and_org(id, org_id)
+                .await?
+                .ok_or(ResponsesStoreError::NotFound),
+        }
+    }
+
+    /// Org-scoped fetch.
+    pub async fn get(&self, id: &str, org_id: Uuid) -> ResponsesStoreResult<ResponseRecord> {
+        self.repo
+            .get_by_id_and_org(id, org_id)
+            .await?
+            .ok_or(ResponsesStoreError::NotFound)
+    }
+
+    /// Org-scoped delete. Idempotent — succeeds even when the row is
+    /// already gone (we still return Ok so `DELETE` is idempotent per
+    /// REST convention).
+    pub async fn delete(&self, id: &str, org_id: Uuid) -> ResponsesStoreResult<bool> {
+        let removed = self.repo.delete_by_id_and_org(id, org_id).await?;
+        if removed {
+            self.cancel_senders.lock().await.remove(id);
+        }
+        Ok(removed)
+    }
+
+    /// Trip the cancel signal AND mark the row cancelled.
+    ///
+    /// Per OpenAI's spec, cancel only succeeds when `background=true`.
+    /// Idempotent for already-terminal rows: returns the existing
+    /// record without re-patching (which would otherwise churn
+    /// completed_at and risk a stray webhook fire).
+    pub async fn cancel(&self, id: &str, org_id: Uuid) -> ResponsesStoreResult<ResponseRecord> {
+        let record = self.get(id, org_id).await?;
+        if !record.background {
+            return Err(ResponsesStoreError::NotBackground);
+        }
+        if record.status.is_terminal() {
+            return Ok(record);
+        }
+        // Trip the in-process flag first so any in-flight stream sees
+        // it before we update the DB.
+        if let Some(tx) = self.cancel_senders.lock().await.get(id) {
+            let _ = tx.send(true);
+        }
+        self.update_within_org(
+            id,
+            org_id,
+            ResponseCompletion {
+                status: Some(ResponseStatus::Cancelled),
+                completed_at: Some(Utc::now()),
+                ..Default::default()
+            },
+        )
+        .await
+    }
+
+    /// Stamp the liveness heartbeat for an in-progress response. Called
+    /// periodically by the persister while a response streams so the
+    /// in-progress reaper can tell a healthy long-running response from a
+    /// dead worker. Best-effort: a failure is logged, not propagated.
+    pub async fn touch_heartbeat(&self, id: &str) {
+        if let Err(e) = self.repo.touch_heartbeat(id, Utc::now()).await {
+            tracing::debug!(response_id = %id, error = %e, "heartbeat stamp failed");
+        }
+    }
+
+    /// Run by the retention worker — delete records past their
+    /// expiry. Returns the number of rows removed.
+    pub async fn prune_expired(&self, before: DateTime<Utc>) -> ResponsesStoreResult<u64> {
+        Ok(self.repo.delete_expired(before).await?)
+    }
+
+    /// Reap rows stuck in `in_progress`. Used by the retention
+    /// worker when a worker that claimed a row died mid-execution
+    /// (claim_queued only picks rows in `queued`, so without this
+    /// they'd linger forever). Marks them `failed` with a
+    /// `worker_lost` error payload and stamps a fresh
+    /// retention_expires_at so they're pruned on the normal cycle.
+    pub async fn reap_stuck(&self, max_age: StdDuration) -> ResponsesStoreResult<u64> {
+        let now = Utc::now();
+        let cutoff = match Duration::from_std(max_age) {
+            Ok(d) => now - d,
+            Err(_) => now - Duration::hours(1),
+        };
+        let retention = self.retention_expires_at(now);
+        Ok(self
+            .repo
+            .reap_stuck_in_progress(cutoff, now, retention)
+            .await?)
+    }
+
+    /// Snapshot of response IDs currently registered with an in-flight
+    /// persister. Used by the cross-replica cancel poller to build the
+    /// "active set" it polls each cycle.
+    pub async fn active_response_ids(&self) -> Vec<String> {
+        self.cancel_senders.lock().await.keys().cloned().collect()
+    }
+
+    /// Trip the in-process cancel signal for a response without
+    /// touching the DB. Called by the cross-replica cancel poller
+    /// when another replica has flipped `status='cancelled'`; the
+    /// row update already happened on the originating replica.
+    pub async fn trip_cancel_in_process(&self, id: &str) {
+        if let Some(tx) = self.cancel_senders.lock().await.get(id) {
+            let _ = tx.send(true);
+        }
+    }
+
+    /// Poll the DB once for any `status='cancelled'` rows in the
+    /// in-flight set and trip their watch signals. Designed to be
+    /// driven by a single replica-wide task (see
+    /// `jobs::responses_cancel_poller`), replacing per-execution
+    /// pollers.
+    pub async fn poll_external_cancels(&self) -> ResponsesStoreResult<usize> {
+        let active = self.active_response_ids().await;
+        if active.is_empty() {
+            return Ok(0);
+        }
+        let cancelled = self.repo.list_cancelled_among(&active).await?;
+        let mut tripped = 0;
+        for id in &cancelled {
+            self.trip_cancel_in_process(id).await;
+            tripped += 1;
+        }
+        Ok(tripped)
+    }
+}
diff --git a/src/services/responses_webhook.rs b/src/services/responses_webhook.rs
new file mode 100644
index 0000000..4632525
--- /dev/null
+++ b/src/services/responses_webhook.rs
@@ -0,0 +1,405 @@
+//! Webhook delivery for Responses API terminal-state transitions.
+//!
+//! When `[features.responses.webhook]` is configured, a `POST` is
+//! fired at the URL each time a stored response transitions to a
+//! terminal status (`completed`, `failed`, `cancelled`, `incomplete`).
+//! The body is a small JSON envelope; the receiver fetches the full
+//! object via `GET /v1/responses/{id}` for any further detail.
+//!
+//! Flow control:
+//! - `enqueue` pushes to a bounded mpsc; full → drop with a
+//!   `webhook_dropped_total` counter increment.
+//! - A single drainer task pulls events and acquires a slot from a
+//!   `Semaphore` (capacity `max_concurrent_deliveries`) before
+//!   spawning the actual HTTP call. Slow targets back-pressure the
+//!   drainer instead of unboundedly spawning tasks.
+//! - Each delivery retries 3× with exponential backoff. Permanent
+//!   failure pushes a `DlqEntry` (when a DLQ is configured) so
+//!   operators can replay later instead of losing the event.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::{sync::Arc, time::Duration};
+
+use chrono::{DateTime, Utc};
+use hmac::{Hmac, Mac};
+use reqwest::Client;
+use serde::Serialize;
+use sha2::Sha256;
+use tokio::sync::{Semaphore, mpsc};
+use tracing::{debug, error, info, warn};
+
+use crate::{
+    config::ResponsesWebhookConfig,
+    db::repos::ResponseStatus,
+    dlq::{DeadLetterQueue, DlqEntry},
+};
+
+type HmacSha256 = Hmac<Sha256>;
+
+/// Header carrying the HMAC signature when `signing_secret` is set.
+/// Format: `t=<unix-seconds>,v1=<hex-sha256>`. The signed payload is
+/// `"<unix>.<body>"` so a captured request can't be replayed against a
+/// receiver that enforces timestamp freshness.
+const SIGNATURE_HEADER: &str = "X-Hadrian-Signature";
+
+/// Entry-type marker used when pushing failed webhook deliveries to
+/// the DLQ. Surfaced in `/admin/v1/dlq` filters.
+const DLQ_ENTRY_TYPE: &str = "responses_webhook";
+
+/// Payload sent to the configured webhook endpoint.
+///
+/// Mirrors OpenAI's webhook event shape so existing handlers work
+/// with minimal porting: `type` distinguishes which terminal state
+/// fired, `data.id` carries the response id for follow-up fetches.
+#[derive(Debug, Serialize, Clone)]
+pub struct WebhookEvent {
+    /// e.g. `"response.completed"`, `"response.failed"`,
+    /// `"response.cancelled"`, `"response.incomplete"`.
+    #[serde(rename = "type")]
+    pub event_type: String,
+    /// ISO-8601 timestamp.
+    pub created_at: DateTime<Utc>,
+    pub data: WebhookEventData,
+}
+
+#[derive(Debug, Serialize, Clone)]
+pub struct WebhookEventData {
+    pub id: String,
+    pub status: &'static str,
+    pub background: bool,
+}
+
+/// Dispatcher held in AppState. Cheap to clone (everything inside is
+/// already `Arc`-friendly).
+#[derive(Clone)]
+pub struct ResponsesWebhookDispatcher {
+    tx: mpsc::Sender<WebhookEvent>,
+    /// Held on the dispatcher (not just the drainer) so `enqueue` can
+    /// divert events to the DLQ when the bounded channel is full,
+    /// instead of silently dropping them.
+    dlq: Option<Arc<dyn DeadLetterQueue>>,
+    /// Webhook target URL — copied here so the overflow path can
+    /// label DLQ entries without reading the full config.
+    target_url: String,
+}
+
+impl ResponsesWebhookDispatcher {
+    /// Construct a dispatcher and spawn its drainer. `dlq` is
+    /// optional; when present, permanently-failed deliveries land
+    /// there for operator replay.
+    pub fn spawn(
+        config: ResponsesWebhookConfig,
+        http: Client,
+        dlq: Option<Arc<dyn DeadLetterQueue>>,
+    ) -> Self {
+        let (tx, rx) = mpsc::channel(config.retry_queue_capacity.max(1));
+        let semaphore = Arc::new(Semaphore::new(config.max_concurrent_deliveries.max(1)));
+        let target_url = config.url.clone();
+        let shared = Arc::new(DispatcherInner {
+            config,
+            http,
+            dlq: dlq.clone(),
+        });
+        crate::compat::spawn_detached(drain_events(rx, semaphore, shared));
+        Self {
+            tx,
+            dlq,
+            target_url,
+        }
+    }
+
+    /// Non-blocking enqueue. When the retry queue is full, the event
+    /// is diverted to the DLQ (if configured) so a wedged target
+    /// can't cause terminal-state notifications to vanish silently.
+    /// Without a DLQ, an overflow logs and drops as a last resort.
+    pub fn enqueue(&self, response_id: String, status: ResponseStatus, background: bool) {
+        let Some(event_type) = terminal_event_name(status) else {
+            // Non-terminal status — nothing to deliver.
+            return;
+        };
+        let event = WebhookEvent {
+            event_type: event_type.to_string(),
+            created_at: Utc::now(),
+            data: WebhookEventData {
+                id: response_id,
+                status: status.as_str(),
+                background,
+            },
+        };
+        match self.tx.try_send(event) {
+            Ok(()) => {}
+            Err(mpsc::error::TrySendError::Full(ev)) => {
+                self.route_overflow_to_dlq(ev);
+            }
+            Err(mpsc::error::TrySendError::Closed(_)) => {
+                // Drainer exited; we're shutting down.
+            }
+        }
+    }
+
+    /// Divert an overflow event to the DLQ off the hot path. Uses a
+    /// detached task because `enqueue` is sync; the caller (the
+    /// `responses_store` update path) doesn't pay for DLQ writes.
+    fn route_overflow_to_dlq(&self, ev: WebhookEvent) {
+        let Some(ref dlq) = self.dlq else {
+            warn!(
+                response_id = %ev.data.id,
+                event_type = %ev.event_type,
+                "Webhook retry queue full and no DLQ configured; dropping event"
+            );
+            return;
+        };
+        let dlq = dlq.clone();
+        let target_url = self.target_url.clone();
+        crate::compat::spawn_detached(async move {
+            let payload = match serde_json::to_string(&ev) {
+                Ok(s) => s,
+                Err(e) => {
+                    warn!(
+                        error = %e,
+                        response_id = %ev.data.id,
+                        event_type = %ev.event_type,
+                        "Failed to serialise overflow webhook event for DLQ; event lost"
+                    );
+                    return;
+                }
+            };
+            let entry = DlqEntry::new(
+                DLQ_ENTRY_TYPE,
+                payload,
+                format!("webhook retry queue full; deferred to DLQ ({target_url})"),
+            )
+            .with_metadata("response_id", ev.data.id.clone())
+            .with_metadata("event_type", ev.event_type.clone())
+            .with_metadata("reason", "queue_full".to_string());
+            match dlq.push(entry).await {
+                Ok(_) => info!(
+                    response_id = %ev.data.id,
+                    event_type = %ev.event_type,
+                    "Webhook retry queue full; overflow event routed to DLQ"
+                ),
+                Err(e) => error!(
+                    response_id = %ev.data.id,
+                    event_type = %ev.event_type,
+                    error = %e,
+                    "Failed to push overflow webhook event to DLQ; event lost"
+                ),
+            }
+        });
+    }
+}
+
+struct DispatcherInner {
+    config: ResponsesWebhookConfig,
+    http: Client,
+    dlq: Option<Arc<dyn DeadLetterQueue>>,
+}
+
+async fn drain_events(
+    mut rx: mpsc::Receiver<WebhookEvent>,
+    semaphore: Arc<Semaphore>,
+    shared: Arc<DispatcherInner>,
+) {
+    while let Some(event) = rx.recv().await {
+        // Block here until a slot is free. Back-pressures the channel
+        // so a slow target can't fan out unbounded in-flight requests.
+        let Ok(permit) = Arc::clone(&semaphore).acquire_owned().await else {
+            return; // semaphore closed
+        };
+        let shared = shared.clone();
+        crate::compat::spawn_detached(async move {
+            let _permit = permit; // released when this task ends
+            deliver_or_dlq(&shared, event).await;
+        });
+    }
+}
+
+async fn deliver_or_dlq(shared: &DispatcherInner, event: WebhookEvent) {
+    if deliver_with_retry(shared, &event).await {
+        return;
+    }
+    // Permanent failure: route to DLQ if available so the event can
+    // be replayed later. Without a DLQ we log and drop — the
+    // persisted `responses` row still carries the same data.
+    let Some(ref dlq) = shared.dlq else {
+        info!(
+            response_id = %event.data.id,
+            event_type = %event.event_type,
+            "Webhook delivery permanently failed; no DLQ configured, dropping"
+        );
+        return;
+    };
+    let payload = match serde_json::to_string(&event) {
+        Ok(s) => s,
+        Err(e) => {
+            warn!(error = %e, "Failed to serialise webhook event for DLQ");
+            return;
+        }
+    };
+    let entry = DlqEntry::new(
+        DLQ_ENTRY_TYPE,
+        payload,
+        format!(
+            "permanent delivery failure to {} after retries",
+            shared.config.url
+        ),
+    )
+    .with_metadata("response_id", event.data.id.clone())
+    .with_metadata("event_type", event.event_type.clone());
+    if let Err(e) = dlq.push(entry).await {
+        warn!(
+            response_id = %event.data.id,
+            event_type = %event.event_type,
+            error = %e,
+            "Failed to push webhook delivery to DLQ"
+        );
+    } else {
+        info!(
+            response_id = %event.data.id,
+            event_type = %event.event_type,
+            "Webhook delivery permanently failed; routed to DLQ"
+        );
+    }
+}
+
+fn terminal_event_name(status: ResponseStatus) -> Option<&'static str> {
+    match status {
+        ResponseStatus::Completed => Some("response.completed"),
+        ResponseStatus::Failed => Some("response.failed"),
+        ResponseStatus::Cancelled => Some("response.cancelled"),
+        ResponseStatus::Incomplete => Some("response.incomplete"),
+        ResponseStatus::Queued | ResponseStatus::InProgress => None,
+    }
+}
+
+/// Returns true on success, false after exhausting retries.
+async fn deliver_with_retry(shared: &DispatcherInner, event: &WebhookEvent) -> bool {
+    let body = match serde_json::to_vec(event) {
+        Ok(b) => b,
+        Err(e) => {
+            warn!(error = %e, "Webhook serialization failed; dropping");
+            return false;
+        }
+    };
+
+    const BACKOFFS_MS: [u64; 3] = [250, 1_000, 4_000];
+    for (attempt, backoff) in BACKOFFS_MS.iter().enumerate() {
+        // Recompute the signature per attempt so the `t=` timestamp
+        // stays fresh — a retry an hour later shouldn't fail receiver
+        // freshness checks for a stale stamp from the first try.
+        let signature = shared
+            .config
+            .signing_secret
+            .as_deref()
+            .map(|secret| sign_payload(secret, &body, Utc::now()));
+        let mut req = shared
+            .http
+            .post(&shared.config.url)
+            .header("Content-Type", "application/json")
+            .header("User-Agent", "hadrian-responses-webhook/1")
+            .timeout(Duration::from_secs(shared.config.timeout_secs))
+            .body(body.clone());
+        if let Some(ref token) = shared.config.bearer_token {
+            req = req.bearer_auth(token);
+        }
+        if let Some(ref sig) = signature {
+            req = req.header(SIGNATURE_HEADER, sig);
+        }
+        match req.send().await {
+            Ok(resp) if resp.status().is_success() => {
+                debug!(
+                    response_id = %event.data.id,
+                    event_type = %event.event_type,
+                    attempt = attempt + 1,
+                    status = resp.status().as_u16(),
+                    "Webhook delivered"
+                );
+                return true;
+            }
+            Ok(resp) => {
+                warn!(
+                    response_id = %event.data.id,
+                    event_type = %event.event_type,
+                    attempt = attempt + 1,
+                    status = resp.status().as_u16(),
+                    "Webhook responded non-2xx; retrying"
+                );
+            }
+            Err(e) => {
+                warn!(
+                    response_id = %event.data.id,
+                    event_type = %event.event_type,
+                    attempt = attempt + 1,
+                    error = %e,
+                    "Webhook delivery failed; retrying"
+                );
+            }
+        }
+        if attempt + 1 < BACKOFFS_MS.len() {
+            tokio::time::sleep(Duration::from_millis(*backoff)).await;
+        }
+    }
+    false
+}
+
+/// Compute the `X-Hadrian-Signature` header value for a body.
+///
+/// Signs the payload `"<unix>.<body>"` with HMAC-SHA256 keyed by the
+/// configured secret. The leading timestamp prevents a captured
+/// request from being replayed against a receiver that enforces a
+/// freshness window (the receiver re-signs with its own copy of
+/// `body` and the timestamp from the header, then compares).
+fn sign_payload(secret: &str, body: &[u8], now: DateTime<Utc>) -> String {
+    let ts = now.timestamp();
+    let mut mac =
+        HmacSha256::new_from_slice(secret.as_bytes()).expect("HMAC-SHA256 accepts any key length");
+    mac.update(ts.to_string().as_bytes());
+    mac.update(b".");
+    mac.update(body);
+    let digest = mac.finalize().into_bytes();
+    format!("t={ts},v1={}", hex::encode(digest))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn signature_format_and_verifiability() {
+        let secret = "shh";
+        let body = br#"{"type":"response.completed","data":{"id":"resp_abc"}}"#;
+        let now = DateTime::<Utc>::from_timestamp(1_700_000_000, 0).unwrap();
+        let header = sign_payload(secret, body, now);
+
+        // Format: t=<unix>,v1=<64-hex>
+        let (t_part, v_part) = header.split_once(',').expect("comma-separated header");
+        assert_eq!(t_part, "t=1700000000");
+        let hex_sig = v_part.strip_prefix("v1=").expect("v1= prefix");
+        assert_eq!(hex_sig.len(), 64);
+
+        // Verifiable: recomputing with the same secret + body + ts
+        // reproduces the digest byte-for-byte.
+        let mut mac = HmacSha256::new_from_slice(secret.as_bytes()).unwrap();
+        mac.update(b"1700000000");
+        mac.update(b".");
+        mac.update(body);
+        assert_eq!(hex::encode(mac.finalize().into_bytes()), hex_sig);
+    }
+
+    #[test]
+    fn signature_changes_when_body_changes() {
+        let now = DateTime::<Utc>::from_timestamp(1_700_000_000, 0).unwrap();
+        let a = sign_payload("shh", b"a", now);
+        let b = sign_payload("shh", b"b", now);
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn signature_changes_when_timestamp_changes() {
+        let body = b"payload";
+        let t1 = DateTime::<Utc>::from_timestamp(1_700_000_000, 0).unwrap();
+        let t2 = DateTime::<Utc>::from_timestamp(1_700_000_001, 0).unwrap();
+        assert_ne!(sign_payload("shh", body, t1), sign_payload("shh", body, t2));
+    }
+}
diff --git a/src/services/server_tools/mod.rs b/src/services/server_tools/mod.rs
new file mode 100644
index 0000000..055216d
--- /dev/null
+++ b/src/services/server_tools/mod.rs
@@ -0,0 +1,362 @@
+//! Server-executed tool framework for the Responses API.
+//!
+//! Tools like `file_search`, `web_search`, and (in later phases) `shell` are
+//! intercepted by the gateway: when the upstream provider emits a function
+//! call, the gateway pauses, executes the work locally, then continues the
+//! conversation with the result folded back in. This module provides the
+//! shared trait + orchestrator that all such tools build on.
+//!
+//! # Architecture
+//!
+//! ```text
+//!   provider stream  ─►  ToolLoopRunner  ─►  client
+//!                            │
+//!                            ├─ for each event: dispatch to ServerExecutedTool::detect()
+//!                            ├─ on detection: ServerExecutedTool::execute()
+//!                            │   ├─ stream tool progress events to client
+//!                            │   └─ produce continuation items
+//!                            ├─ ServerExecutedTool::apply_to_continuation()
+//!                            └─ provider_callback() → new stream → loop
+//! ```
+//!
+//! The runner enforces a global iteration limit across all registered tools.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::{future::Future, pin::Pin, sync::Arc};
+
+use axum::body::Body;
+use bytes::Bytes;
+use futures_util::stream::Stream;
+use http::Response;
+use serde_json::Value;
+use thiserror::Error;
+
+use crate::{
+    api_types::responses::{CreateResponsesPayload, ResponsesInputItem},
+    providers::ProviderError,
+};
+
+mod runner;
+
+pub use runner::ToolLoopRunner;
+
+/// Suppresses the rewritten `function_call` plumbing for a server tool
+/// that synthesizes its own spec-shaped output items.
+///
+/// Every server-executed tool is driven by function-tool rewriting: the
+/// model emits a `function_call` (`web_search` / `file_search` / `shell`
+/// / `mcp_<label>__<tool>`), which the runner intercepts and replaces
+/// with the hosted-tool item (`web_search_call`, `mcp_call`, …). OpenAI's
+/// Responses output only ever carries those hosted-tool items, never the
+/// `function_call` that drove them — so the underlying
+/// `output_item.added` / `.done` and `function_call_arguments.delta` /
+/// `.done` events must not reach the client. A tool calls
+/// [`Self::suppress`] from its `transform_event`; suppressed events come
+/// back as empty `Bytes`, which the runner drops.
+#[derive(Default)]
+pub struct FunctionCallSuppressor {
+    /// Item ids of the function calls we've decided to hide. The
+    /// argument-streaming events carry only `item_id` (no name), so we
+    /// remember the id from the `output_item.added` / `.done` (which do
+    /// carry the name) to suppress them as well.
+    tracked: std::sync::Mutex<std::collections::HashSet<String>>,
+}
+
+impl FunctionCallSuppressor {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Return empty `Bytes` when `event` is the rewritten function-call
+    /// plumbing for a call whose name satisfies `is_match`; otherwise
+    /// return `event` untouched. Non-`function_call` events (including
+    /// the tool's own synthesized items) always pass through.
+    pub fn suppress(&self, event: Bytes, is_match: impl Fn(&str) -> bool) -> Bytes {
+        let Some(data) = sse_event_data(&event) else {
+            return event;
+        };
+        let trimmed = data.trim();
+        if trimmed == "[DONE]" {
+            return event;
+        }
+        let Ok(json) = serde_json::from_str::<Value>(trimmed) else {
+            return event;
+        };
+        match json.get("type").and_then(|t| t.as_str()) {
+            Some("response.output_item.added" | "response.output_item.done") => {
+                let Some(item) = json.get("item") else {
+                    return event;
+                };
+                if item.get("type").and_then(|t| t.as_str()) != Some("function_call") {
+                    return event;
+                }
+                let name = item.get("name").and_then(|v| v.as_str()).unwrap_or("");
+                if !is_match(name) {
+                    return event;
+                }
+                if let Some(id) = item.get("id").and_then(|v| v.as_str())
+                    && let Ok(mut set) = self.tracked.lock()
+                {
+                    set.insert(id.to_string());
+                }
+                Bytes::new()
+            }
+            Some(
+                "response.function_call_arguments.delta" | "response.function_call_arguments.done",
+            ) => {
+                // Real OpenAI arg events carry only `item_id`; some
+                // providers (and our own fixtures) also include `name`.
+                // Match on either so the plumbing is hidden regardless.
+                let by_name = json
+                    .get("name")
+                    .and_then(|v| v.as_str())
+                    .is_some_and(&is_match);
+                let item_id = json.get("item_id").and_then(|v| v.as_str()).unwrap_or("");
+                let by_id = self
+                    .tracked
+                    .lock()
+                    .map(|s| s.contains(item_id))
+                    .unwrap_or(false);
+                if by_name || by_id {
+                    Bytes::new()
+                } else {
+                    event
+                }
+            }
+            _ => event,
+        }
+    }
+}
+
+/// Join the `data:` field(s) of a single SSE event into one string,
+/// honoring CRLF framing and the spec's single-leading-space rule.
+/// Returns `None` when the event carries no `data:` payload.
+fn sse_event_data(event: &[u8]) -> Option<String> {
+    let text = std::str::from_utf8(event).ok()?;
+    let mut parts: Vec<&str> = Vec::new();
+    for line in text.split('\n') {
+        let line = line.strip_suffix('\r').unwrap_or(line);
+        if line.is_empty() || line.starts_with(':') {
+            continue;
+        }
+        if let Some(rest) = line.strip_prefix("data:") {
+            parts.push(rest.strip_prefix(' ').unwrap_or(rest));
+        }
+    }
+    (!parts.is_empty()).then(|| parts.join("\n"))
+}
+
+/// Callback that re-invokes the upstream provider with a new payload.
+///
+/// Used to continue the conversation after a server-executed tool produces
+/// results: the orchestrator builds a continuation payload with the tool
+/// outputs folded in, then calls this to start the next response stream.
+pub type ProviderCallback = Arc<
+    dyn Fn(
+            CreateResponsesPayload,
+        ) -> Pin<Box<dyn Future<Output = Result<Response<Body>, ProviderError>> + Send>>
+        + Send
+        + Sync,
+>;
+
+/// Stream of bytes that gets forwarded to the client.
+pub type EventStream = Pin<Box<dyn Stream<Item = Bytes> + Send>>;
+
+/// Future that resolves to a tool call's final result.
+pub type ResultFuture =
+    Pin<Box<dyn Future<Output = Result<ToolCallResult, ToolError>> + Send + 'static>>;
+
+/// Errors emitted by server-executed tools.
+#[derive(Debug, Error)]
+pub enum ToolError {
+    /// Tool execution failed for an internal reason.
+    #[error("tool execution failed: {0}")]
+    ExecutionFailed(String),
+    /// Tool received a malformed call from the model.
+    #[error("malformed tool call: {0}")]
+    InvalidCall(String),
+    /// Upstream provider returned an error during continuation.
+    #[error("provider error: {0}")]
+    Provider(String),
+}
+
+/// A tool call detected in an SSE event from the upstream provider.
+///
+/// Carries enough information for the orchestrator to route the call to
+/// the right tool implementation; the tool itself parses `arguments` into
+/// its concrete arguments type.
+#[derive(Debug, Clone)]
+pub struct DetectedToolCall {
+    /// Name of the tool, matching `ServerExecutedTool::name()`.
+    pub tool_name: &'static str,
+    /// Stable identifier the model assigned to this call.
+    pub call_id: String,
+    /// Tool-specific arguments payload — JSON value or any other structure
+    /// the tool needs to execute. Each tool's `execute()` interprets this.
+    pub arguments: Value,
+}
+
+/// Result of executing one tool call.
+#[derive(Clone)]
+pub struct ToolCallResult {
+    /// The call this result corresponds to.
+    pub call_id: String,
+    /// Items to fold into the next provider request's `input`.
+    ///
+    /// Typically one `FunctionCallOutput` containing the tool result text
+    /// the model can read on its next turn.
+    pub continuation_items: Vec<ResponsesInputItem>,
+}
+
+/// Handle returned by `ServerExecutedTool::execute()`.
+///
+/// The orchestrator interleaves `events` into the client stream while
+/// awaiting `result` for the continuation payload.
+pub struct ToolExecutionHandle {
+    /// Progress/output events the orchestrator forwards to the client.
+    ///
+    /// For file_search this is `in_progress`, `searching`, the
+    /// `file_search_call` output item, then `completed`. For a future
+    /// `shell` tool this carries `output_chunk` events from the container.
+    pub events: EventStream,
+    /// Final result of the call.
+    pub result: ResultFuture,
+}
+
+/// Context passed to detection and execution.
+///
+/// Currently minimal; will grow as tools need things like the principal
+/// or per-request budget state.
+#[derive(Clone)]
+pub struct ToolContext {
+    /// The original request payload, used to inspect things like the
+    /// `include` field for `file_search` annotations.
+    pub original_payload: CreateResponsesPayload,
+}
+
+/// A tool the gateway executes on behalf of the model.
+///
+/// Implementors define detection (what an SSE event for *their* tool looks
+/// like), execution (the actual work), and continuation (how their results
+/// shape the next provider request).
+#[async_trait::async_trait]
+pub trait ServerExecutedTool: Send + Sync {
+    /// Stable identifier for routing detected calls. Must match
+    /// `DetectedToolCall::tool_name`.
+    fn name(&self) -> &'static str;
+
+    /// Whether this tool should engage for the given request.
+    ///
+    /// Examined once per request before the loop starts. If false, the
+    /// tool is skipped entirely (no detection overhead).
+    fn is_enabled_for(&self, payload: &CreateResponsesPayload) -> bool;
+
+    /// Inspect one complete SSE event and emit any tool calls of this
+    /// tool's type that it contains.
+    ///
+    /// Called for every event of every iteration. Must be cheap.
+    fn detect(&self, event: &[u8], ctx: &ToolContext) -> Vec<DetectedToolCall>;
+
+    /// Execute one detected tool call.
+    ///
+    /// Returns a handle exposing progress events plus the final result.
+    /// The orchestrator forwards the events to the client and awaits the
+    /// result to build the continuation payload.
+    async fn execute(
+        &self,
+        call: DetectedToolCall,
+        ctx: &ToolContext,
+    ) -> Result<ToolExecutionHandle, ToolError>;
+
+    /// Fold this tool's results into a continuation payload.
+    ///
+    /// Called once per iteration with all results for this tool. Typically
+    /// appends function-call outputs to `payload.input`. On the final
+    /// iteration (when the runner has exhausted its iteration budget for
+    /// the next round) the tool should strip its own definitions from
+    /// `payload.tools` so the model is forced to produce a text response.
+    fn apply_to_continuation(
+        &self,
+        payload: &mut CreateResponsesPayload,
+        results: &[ToolCallResult],
+        is_final_iteration: bool,
+    );
+
+    /// Transform an outgoing SSE event before it is forwarded to the
+    /// client. Default: pass-through. `file_search` overrides this to
+    /// inject citation annotations into message-content events after
+    /// search results are known.
+    ///
+    /// Implementations needing stateful transformation (where the result
+    /// depends on prior `execute()` calls) should use interior mutability.
+    fn transform_event(&self, event: Bytes) -> Bytes {
+        event
+    }
+
+    /// Events to emit once, before the upstream stream starts.
+    ///
+    /// Used by `mcp` to surface the `mcp_list_tools` catalog snapshot
+    /// at the start of the response, mirroring OpenAI's hosted MCP
+    /// behavior so the persisted output records what tool surface the
+    /// model saw. Default: empty.
+    fn prefix_events(&self) -> Vec<Bytes> {
+        Vec::new()
+    }
+}
+
+#[cfg(test)]
+mod suppressor_tests {
+    use super::*;
+
+    fn ev(s: &str) -> Bytes {
+        Bytes::from(format!("data: {s}\n\n"))
+    }
+
+    #[test]
+    fn suppresses_matching_function_call_lifecycle() {
+        let s = FunctionCallSuppressor::new();
+        let is_ws = |n: &str| n == "web_search";
+
+        // output_item.added for the matching function call → dropped,
+        // and its item id is remembered.
+        let added = ev(
+            r#"{"type":"response.output_item.added","item":{"type":"function_call","id":"fc_1","name":"web_search","arguments":""}}"#,
+        );
+        assert!(s.suppress(added, is_ws).is_empty());
+
+        // The arg-streaming events carry only item_id → dropped via the
+        // remembered id.
+        let delta =
+            ev(r#"{"type":"response.function_call_arguments.delta","item_id":"fc_1","delta":"{"}"#);
+        assert!(s.suppress(delta, is_ws).is_empty());
+        let done = ev(
+            r#"{"type":"response.output_item.done","item":{"type":"function_call","id":"fc_1","name":"web_search","arguments":"{}"}}"#,
+        );
+        assert!(s.suppress(done, is_ws).is_empty());
+    }
+
+    #[test]
+    fn passes_through_other_calls_and_synthesized_items() {
+        let s = FunctionCallSuppressor::new();
+        let is_ws = |n: &str| n == "web_search";
+
+        // A different function call is untouched.
+        let other = ev(
+            r#"{"type":"response.output_item.added","item":{"type":"function_call","id":"fc_2","name":"get_weather","arguments":""}}"#,
+        );
+        assert_eq!(s.suppress(other.clone(), is_ws), other);
+        // Arg events for an untracked id pass through.
+        let delta =
+            ev(r#"{"type":"response.function_call_arguments.delta","item_id":"fc_2","delta":"{"}"#);
+        assert_eq!(s.suppress(delta.clone(), is_ws), delta);
+        // The tool's own synthesized item passes through.
+        let synth = ev(
+            r#"{"type":"response.output_item.done","item":{"type":"web_search_call","id":"ws_1","status":"completed"}}"#,
+        );
+        assert_eq!(s.suppress(synth.clone(), is_ws), synth);
+        // [DONE] and non-JSON pass through.
+        let done = Bytes::from("data: [DONE]\n\n");
+        assert_eq!(s.suppress(done.clone(), is_ws), done);
+    }
+}
diff --git a/src/services/server_tools/runner.rs b/src/services/server_tools/runner.rs
new file mode 100644
index 0000000..dd17045
--- /dev/null
+++ b/src/services/server_tools/runner.rs
@@ -0,0 +1,1581 @@
+//! Streaming orchestrator that runs registered `ServerExecutedTool`s in a
+//! shared multi-turn loop.
+
+use std::{collections::HashMap, sync::Arc};
+
+use axum::body::Body;
+use bytes::{Bytes, BytesMut};
+use futures_util::{StreamExt, stream::FuturesUnordered};
+use http::Response;
+use tokio::sync::mpsc;
+use tracing::{Instrument, debug, error, info, info_span, warn};
+
+use super::{DetectedToolCall, ProviderCallback, ServerExecutedTool, ToolCallResult, ToolContext};
+use crate::{
+    api_types::responses::{
+        CreateResponsesPayload, EasyInputMessage, EasyInputMessageContent, EasyInputMessageRole,
+        OutputItemFunctionCall, OutputMessage, ResponsesInput, ResponsesInputItem,
+        ResponsesReasoning, ResponsesUsage,
+    },
+    observability::metrics::record_server_tool_iteration,
+    streaming::SseBuffer,
+};
+
+/// Multi-tool orchestrator for streaming Responses API output.
+///
+/// Wraps the upstream response body, reads SSE events, dispatches detection
+/// across all registered tools, executes detected calls, and continues the
+/// conversation with the provider until either the model stops calling
+/// tools or the global iteration budget is exhausted.
+pub struct ToolLoopRunner {
+    tools: Vec<Arc<dyn ServerExecutedTool>>,
+    provider_callback: Option<ProviderCallback>,
+    original_payload: CreateResponsesPayload,
+    max_iterations: usize,
+    rewrite_output: bool,
+    response_id: Option<String>,
+    /// `(function-name prefix, original tool JSON)` pairs used to collapse
+    /// rewritten MCP function tools back into the caller's original `mcp`
+    /// entry on the echoed `response.tools`. Empty when no MCP rewrite ran.
+    /// See [`ToolLoopRunner::with_mcp_tool_echo`].
+    mcp_tool_echo: Vec<(String, serde_json::Value)>,
+}
+
+impl ToolLoopRunner {
+    /// Create a new runner.
+    ///
+    /// `max_iterations` is the maximum number of provider continuation
+    /// requests the runner will dispatch — i.e., the total number of
+    /// times the loop body executes. Counted globally across all tools.
+    pub fn new(original_payload: CreateResponsesPayload, max_iterations: usize) -> Self {
+        Self {
+            tools: Vec::new(),
+            provider_callback: None,
+            original_payload,
+            max_iterations,
+            rewrite_output: false,
+            response_id: None,
+            mcp_tool_echo: Vec::new(),
+        }
+    }
+
+    /// Restore the caller's original `mcp` tool entries on the echoed
+    /// `response.tools`. Under `hadrian_hosted` the request's `mcp` tool is
+    /// rewritten into N `mcp_<label>__<tool>` function tools before it hits
+    /// the provider, so the provider echoes those internal function tools
+    /// instead of the `mcp` entry the caller sent. Each pair is
+    /// `(function-name prefix, original tool JSON)`: on every lifecycle
+    /// event the rewriter collapses a run of function tools whose `name`
+    /// starts with the prefix back into the single original `mcp` entry.
+    /// Only takes effect when [`Self::rewrite_output`] is enabled.
+    pub fn with_mcp_tool_echo(mut self, echo: Vec<(String, serde_json::Value)>) -> Self {
+        self.mcp_tool_echo = echo;
+        self
+    }
+
+    /// Set the stable Hadrian `resp_…` id to stamp onto lifecycle events,
+    /// replacing the provider's per-turn id. Only takes effect when
+    /// [`Self::rewrite_output`] is enabled. Pass the persisted response id
+    /// so the streamed id matches what's retrievable / chainable.
+    pub fn with_response_id(mut self, response_id: String) -> Self {
+        self.response_id = Some(response_id);
+        self
+    }
+
+    /// Enable single-stream normalization of the forwarded events.
+    ///
+    /// When on, the runner owns one monotonic `sequence_number` /
+    /// `output_index` space across the prefix events, every provider
+    /// turn, and the tool-synthesized events, and reconstructs the
+    /// terminal `response.output` from the `output_item.done` items it
+    /// actually forwards. This is what lets a tool that synthesizes its
+    /// own output items (the MCP executor: `mcp_list_tools` / `mcp_call`
+    /// / `mcp_approval_request`) and suppresses the underlying
+    /// function-call plumbing produce a spec-shaped, collision-free
+    /// stream *and* a persisted output that matches it. Off by default
+    /// so tools that don't synthesize items keep the provider's stream
+    /// verbatim.
+    pub fn rewrite_output(mut self, on: bool) -> Self {
+        self.rewrite_output = on;
+        self
+    }
+
+    /// Register a tool. Tools are dispatched in registration order; first
+    /// `detect()` match wins for a given event.
+    pub fn register(mut self, tool: Arc<dyn ServerExecutedTool>) -> Self {
+        self.tools.push(tool);
+        self
+    }
+
+    /// Set the provider callback used for continuation requests.
+    ///
+    /// Without a callback the runner only detects + emits in-progress
+    /// events; it doesn't actually execute multi-turn. Most callers should
+    /// always set this.
+    pub fn with_provider_callback(mut self, callback: ProviderCallback) -> Self {
+        self.provider_callback = Some(callback);
+        self
+    }
+
+    /// Are any registered tools enabled for the original payload?
+    pub fn has_enabled_tools(&self) -> bool {
+        self.tools
+            .iter()
+            .any(|t| t.is_enabled_for(&self.original_payload))
+    }
+
+    /// Wrap a streaming HTTP response, intercepting and executing tool
+    /// calls along the way.
+    ///
+    /// If no registered tool is enabled for the request, returns the
+    /// response unchanged.
+    pub fn wrap_streaming(self, response: Response<Body>) -> Response<Body> {
+        // Filter to enabled tools up-front so detection loops are tight.
+        let enabled_tools: Vec<Arc<dyn ServerExecutedTool>> = self
+            .tools
+            .into_iter()
+            .filter(|t| t.is_enabled_for(&self.original_payload))
+            .collect();
+
+        if enabled_tools.is_empty() {
+            return response;
+        }
+
+        let (parts, body) = response.into_parts();
+        let max_iterations = self.max_iterations;
+        let has_callback = self.provider_callback.is_some();
+        let provider_callback = self.provider_callback;
+        let original_payload = self.original_payload;
+        let rewrite_output = self.rewrite_output;
+        let response_id = self.response_id;
+        let mcp_tool_echo = self.mcp_tool_echo;
+
+        let span = info_span!(
+            "tool_loop_runner",
+            tool_count = enabled_tools.len(),
+            max_iterations = max_iterations,
+            has_callback = has_callback,
+        );
+
+        let (tx, rx) = mpsc::channel::<Result<Bytes, std::io::Error>>(32);
+
+        crate::compat::spawn_detached(
+            async move {
+                let ctx = ToolContext {
+                    original_payload: original_payload.clone(),
+                };
+                let tool_by_name: HashMap<&'static str, Arc<dyn ServerExecutedTool>> =
+                    enabled_tools
+                        .iter()
+                        .map(|t| (t.name(), t.clone()))
+                        .collect();
+                let tool_names: Vec<&'static str> =
+                    enabled_tools.iter().map(|t| t.name()).collect();
+
+                // Single-stream normalizer (sequence_number / output_index /
+                // terminal-output reconstruction). `None` keeps the provider
+                // stream verbatim — see `ToolLoopRunner::rewrite_output`.
+                let mut rewriter = rewrite_output
+                    .then(|| StreamRewriter::new(response_id.clone(), mcp_tool_echo.clone()));
+
+                // Collect any one-shot prefix events the tools want to
+                // surface (the `mcp` `mcp_list_tools` catalog snapshot).
+                // With the rewriter on, they're deferred until after the
+                // lifecycle start events so `response.created` leads the
+                // stream; without it, they're forwarded verbatim up front.
+                for tool in &enabled_tools {
+                    for event in tool.prefix_events() {
+                        match rewriter.as_mut() {
+                            Some(r) => r.defer_prefix(event),
+                            None => {
+                                if tx.send(Ok(event)).await.is_err() {
+                                    return;
+                                }
+                            }
+                        }
+                    }
+                }
+
+                let mut iteration: usize = 0;
+                let mut current_body = body;
+                // Set when an error/fallback path forwards a turn's raw
+                // accumulated bytes (which still carry that turn's `[DONE]`
+                // sentinel). The normal path swallows every per-turn `[DONE]`
+                // and emits a single terminal one after the loop; this flag
+                // keeps the fallback paths from producing a second `[DONE]`.
+                let mut raw_tail_forwarded = false;
+                // Continuation payload carried across iterations. Each
+                // turn appends the assistant items the upstream emitted
+                // plus the tool function-call outputs, so the model
+                // sees its own prior tool_use/tool_result pairs on
+                // subsequent turns. Without this, providers that
+                // translate Responses items into native pairwise
+                // formats (e.g. Anthropic via OpenRouter) drop the
+                // orphan tool outputs on the floor and the model loops
+                // forever as if it had never run anything.
+                let mut continuation_payload = original_payload.clone();
+
+                loop {
+                    iteration += 1;
+                    let at_iteration_limit = iteration > max_iterations;
+
+                    let iter_span = info_span!(
+                        "tool_loop_iteration",
+                        iteration = iteration,
+                        at_limit = at_iteration_limit,
+                    );
+                    let _iter_guard = iter_span.enter();
+
+                    let mut body_stream = current_body.into_data_stream();
+                    let mut accumulated = BytesMut::new();
+                    let mut detected: Vec<DetectedToolCall> = Vec::new();
+                    let mut sse_buffer = SseBuffer::new();
+                    // The turn's suppressed *final* terminal event
+                    // (`response.completed` / `failed` / `incomplete`), kept so
+                    // a failure/abort path can re-emit it through the rewriter
+                    // instead of dumping the provider's raw last-turn bytes.
+                    let mut suppressed_terminal: Option<Bytes> = None;
+                    // Assistant items the upstream emitted this turn.
+                    // Threaded into the continuation payload below so
+                    // the function-call outputs from this iteration
+                    // have matching function_call items to anchor to.
+                    let mut captured_assistant_items: Vec<ResponsesInputItem> = Vec::new();
+
+                    // Read the current response stream, forwarding events
+                    // until we've finished consuming or detected calls.
+                    while let Some(chunk_result) = body_stream.next().await {
+                        match chunk_result {
+                            Ok(chunk) => {
+                                accumulated.extend_from_slice(&chunk);
+                                sse_buffer.extend(&chunk);
+
+                                for event in sse_buffer.extract_complete_events() {
+                                    // Each provider turn ends with its own
+                                    // `[DONE]` sentinel. Swallow them all here
+                                    // and emit exactly one terminal `[DONE]`
+                                    // after the loop — otherwise a spec-
+                                    // compliant SSE client treats the first
+                                    // mid-loop `[DONE]` as end-of-stream and
+                                    // never sees the remaining turns.
+                                    if is_done_sentinel(&event) {
+                                        continue;
+                                    }
+                                    if !at_iteration_limit {
+                                        for tool in &enabled_tools {
+                                            let calls = tool.detect(&event, &ctx);
+                                            for call in calls {
+                                                info!(
+                                                    stage = "tool_call_detected",
+                                                    tool = call.tool_name,
+                                                    call_id = %call.call_id,
+                                                    iteration = iteration,
+                                                    "Detected tool call"
+                                                );
+                                                detected.push(call);
+                                            }
+                                        }
+
+                                        if let Some(item) = parse_assistant_item(&event) {
+                                            captured_assistant_items.push(item);
+                                        }
+
+                                        // Once a tool call has been detected for
+                                        // this iteration, hold back only the
+                                        // iteration-terminator events
+                                        // (`response.created`,
+                                        // `response.in_progress`,
+                                        // `response.completed`, ...) — they would
+                                        // confuse a client into thinking the
+                                        // upstream is finished when in fact we're
+                                        // about to continue the loop. Item-level
+                                        // events (`output_item.done`,
+                                        // `content_part.done`, etc.) are
+                                        // informational and must be forwarded so
+                                        // both streaming clients and the
+                                        // non-streaming bridge can reconstruct
+                                        // the full transcript.
+                                        if !detected.is_empty()
+                                            && has_callback
+                                            && is_iteration_terminator(&event)
+                                        {
+                                            // Capture this suppressed turn's
+                                            // usage before dropping it, so the
+                                            // final terminal can report the
+                                            // whole loop's tokens/cost.
+                                            if let Some(r) = rewriter.as_mut() {
+                                                r.accumulate_suppressed_usage(&event);
+                                            }
+                                            // Keep the final terminal so an
+                                            // error/abort path below can re-emit
+                                            // it through the rewriter rather than
+                                            // forwarding raw provider bytes.
+                                            if is_terminal_lifecycle(&event) {
+                                                suppressed_terminal = Some(event.clone());
+                                            }
+                                            continue;
+                                        }
+                                    }
+
+                                    let to_send = apply_transforms(&enabled_tools, event);
+                                    if let Some(out) = finalize_event(&mut rewriter, to_send)
+                                        && tx.send(Ok(out)).await.is_err()
+                                    {
+                                        return; // client disconnected
+                                    }
+                                }
+                            }
+                            Err(e) => {
+                                warn!(
+                                    stage = "stream_error",
+                                    error = %e,
+                                    iteration = iteration,
+                                    "Error reading stream chunk"
+                                );
+                                let _ = tx.send(Err(std::io::Error::other(e))).await;
+                                return;
+                            }
+                        }
+                    }
+
+                    // Flush any trailing partial event.
+                    if !sse_buffer.is_empty() {
+                        let remaining = sse_buffer.take_remaining();
+                        if !remaining.is_empty()
+                            && !is_done_sentinel(&remaining)
+                            && (detected.is_empty() || !has_callback)
+                        {
+                            let to_send = apply_transforms(&enabled_tools, remaining);
+                            if let Some(out) = finalize_event(&mut rewriter, to_send)
+                                && tx.send(Ok(out)).await.is_err()
+                            {
+                                return;
+                            }
+                        }
+                    }
+
+                    if at_iteration_limit {
+                        warn!(
+                            stage = "iteration_limit_reached",
+                            iteration = iteration,
+                            max_iterations = max_iterations,
+                            "Maximum server-tool iterations exceeded; forwarding final response"
+                        );
+                        record_server_tool_iteration(
+                            iteration as u32,
+                            true,
+                            "limit_reached",
+                            &tool_names,
+                        );
+                        break;
+                    }
+
+                    if detected.is_empty() {
+                        debug!(
+                            stage = "stream_completed",
+                            iteration = iteration,
+                            "No tool calls detected; stream complete"
+                        );
+                        record_server_tool_iteration(
+                            iteration as u32,
+                            true,
+                            "completed",
+                            &tool_names,
+                        );
+                        break;
+                    }
+
+                    // Execute all detected calls in parallel, interleaving
+                    // their progress events into the client stream.
+                    let mut exec_handles = FuturesUnordered::new();
+                    for call in detected.drain(..) {
+                        let Some(tool) = tool_by_name.get(call.tool_name).cloned() else {
+                            error!(
+                                stage = "unknown_tool",
+                                tool = call.tool_name,
+                                "Detected call references unregistered tool; skipping"
+                            );
+                            continue;
+                        };
+                        let ctx = ctx.clone();
+                        let call_id = call.call_id.clone();
+                        let tool_name = call.tool_name;
+                        exec_handles.push(async move {
+                            let handle = tool.execute(call, &ctx).await;
+                            (tool_name, call_id, handle)
+                        });
+                    }
+
+                    // results_by_tool[tool_name] = Vec<ToolCallResult>
+                    let mut results_by_tool: HashMap<&'static str, Vec<ToolCallResult>> =
+                        HashMap::new();
+                    let mut had_failure = false;
+
+                    while let Some((tool_name, call_id, handle)) = exec_handles.next().await {
+                        let handle = match handle {
+                            Ok(h) => h,
+                            Err(e) => {
+                                error!(
+                                    stage = "execute_failed",
+                                    tool = tool_name,
+                                    call_id = %call_id,
+                                    error = %e,
+                                    "Tool execute() returned error"
+                                );
+                                had_failure = true;
+                                continue;
+                            }
+                        };
+
+                        let mut events = handle.events;
+                        while let Some(event) = events.next().await {
+                            let to_send = apply_transforms(&enabled_tools, event);
+                            if let Some(out) = finalize_event(&mut rewriter, to_send)
+                                && tx.send(Ok(out)).await.is_err()
+                            {
+                                return;
+                            }
+                        }
+
+                        match handle.result.await {
+                            Ok(result) => {
+                                results_by_tool.entry(tool_name).or_default().push(result);
+                            }
+                            Err(e) => {
+                                error!(
+                                    stage = "result_failed",
+                                    tool = tool_name,
+                                    call_id = %call_id,
+                                    error = %e,
+                                    "Tool result returned error"
+                                );
+                                had_failure = true;
+                            }
+                        }
+                    }
+
+                    if had_failure {
+                        // A tool call failed; stop the loop and emit a final
+                        // terminal. With the rewriter on we re-emit the turn's
+                        // suppressed terminal through it — so the client gets a
+                        // normalized terminal with the reconstructed
+                        // `response.output` (synthesized `mcp_*` items included),
+                        // stable id, collapsed `tools`, and folded usage —
+                        // instead of the provider's raw, un-normalized bytes.
+                        // With the rewriter off (file_search/web_search/shell)
+                        // we forward the raw accumulated tail as before.
+                        match emit_failure_terminal(
+                            &mut rewriter,
+                            &tx,
+                            suppressed_terminal.take(),
+                            accumulated,
+                        )
+                        .await
+                        {
+                            Ok(forwarded) => raw_tail_forwarded = forwarded,
+                            Err(()) => return,
+                        }
+                        record_server_tool_iteration(iteration as u32, true, "error", &tool_names);
+                        break;
+                    }
+
+                    // Build the continuation payload by letting each tool
+                    // fold its results in.
+                    let Some(ref callback) = provider_callback else {
+                        // No callback: forward what we have and stop. The raw
+                        // tail still carries this turn's `[DONE]`.
+                        if tx.send(Ok(accumulated.freeze())).await.is_err() {
+                            return;
+                        }
+                        raw_tail_forwarded = true;
+                        record_server_tool_iteration(
+                            iteration as u32,
+                            true,
+                            "no_callback",
+                            &tool_names,
+                        );
+                        break;
+                    };
+
+                    let is_final_iteration = iteration == max_iterations;
+                    // The continuation payload accumulates across
+                    // iterations: each turn it grows by the assistant
+                    // items the upstream emitted plus the function-call
+                    // outputs this turn's tools produced. Pairing the
+                    // assistant's function_call items with their
+                    // corresponding function_call_output items is what
+                    // lets non-OpenAI providers (e.g. Anthropic via
+                    // OpenRouter) reconstruct valid tool_use/tool_result
+                    // pairs on the wire.
+                    normalize_input_to_items(&mut continuation_payload);
+                    if let Some(ResponsesInput::Items(ref mut items)) = continuation_payload.input {
+                        items.append(&mut captured_assistant_items);
+                    }
+                    for tool in &enabled_tools {
+                        if let Some(results) = results_by_tool.get(tool.name()) {
+                            tool.apply_to_continuation(
+                                &mut continuation_payload,
+                                results,
+                                is_final_iteration,
+                            );
+                        }
+                    }
+                    let mut continuation_payload_for_call = continuation_payload.clone();
+                    continuation_payload_for_call.stream = true;
+
+                    info!(
+                        stage = "continuation_sent",
+                        iteration = iteration,
+                        is_final_iteration = is_final_iteration,
+                        tools_with_results = results_by_tool.len(),
+                        "Sending continuation request to provider"
+                    );
+
+                    record_server_tool_iteration(
+                        iteration as u32,
+                        false,
+                        "continuation",
+                        &tool_names,
+                    );
+
+                    match callback(continuation_payload_for_call).await {
+                        Ok(continuation_response) => {
+                            let (_, new_body) = continuation_response.into_parts();
+                            current_body = new_body;
+                            continue;
+                        }
+                        Err(e) => {
+                            error!(
+                                stage = "continuation_failed",
+                                iteration = iteration,
+                                error = %e,
+                                "Provider continuation request failed"
+                            );
+                            // Same as the `had_failure` path: re-emit the prior
+                            // turn's terminal through the rewriter (so the
+                            // already-streamed synthesized items survive in the
+                            // reconstructed output) rather than dumping raw bytes.
+                            match emit_failure_terminal(
+                                &mut rewriter,
+                                &tx,
+                                suppressed_terminal.take(),
+                                accumulated,
+                            )
+                            .await
+                            {
+                                Ok(forwarded) => raw_tail_forwarded = forwarded,
+                                Err(()) => return,
+                            }
+                            record_server_tool_iteration(
+                                iteration as u32,
+                                true,
+                                "continuation_error",
+                                &tool_names,
+                            );
+                            break;
+                        }
+                    }
+                }
+
+                // Emit exactly one terminal `[DONE]` for the merged stream.
+                // Per-turn sentinels were swallowed above; the fallback paths
+                // that dumped raw bytes set `raw_tail_forwarded` since their
+                // tail already carries a `[DONE]`.
+                if !raw_tail_forwarded {
+                    let _ = tx.send(Ok(Bytes::from_static(b"data: [DONE]\n\n"))).await;
+                }
+
+                debug!(
+                    stage = "processing_completed",
+                    "Tool loop processing complete"
+                );
+            }
+            .instrument(span),
+        );
+
+        let stream = futures_util::stream::unfold(rx, |mut rx| async move {
+            rx.recv().await.map(|item| (item, rx))
+        });
+        let body = Body::from_stream(stream);
+        Response::from_parts(parts, body)
+    }
+}
+
+fn apply_transforms(tools: &[Arc<dyn ServerExecutedTool>], event: Bytes) -> Bytes {
+    let mut out = event;
+    for t in tools {
+        out = t.transform_event(out);
+    }
+    out
+}
+
+/// Drop suppressed (empty) events and run the optional [`StreamRewriter`].
+/// A tool's `transform_event` returns empty bytes to suppress an event
+/// (the MCP executor hides the rewritten function-call plumbing this
+/// way); those are skipped here. Returns `None` when nothing should be
+/// forwarded.
+fn finalize_event(rewriter: &mut Option<StreamRewriter>, event: Bytes) -> Option<Bytes> {
+    if event.is_empty() {
+        return None;
+    }
+    match rewriter {
+        // The rewriter returns empty bytes for a suppressed event (a
+        // duplicate lifecycle start); drop those rather than forwarding a
+        // blank chunk.
+        Some(r) => {
+            let out = r.rewrite(event);
+            (!out.is_empty()).then_some(out)
+        }
+        None => Some(event),
+    }
+}
+
+/// Extract the payload `type` of a single SSE event, if it carries a
+/// JSON `data:` line with a string `type` field.
+fn event_type_of(event: &[u8]) -> Option<String> {
+    let text = std::str::from_utf8(event).ok()?;
+    let data = text
+        .lines()
+        .find_map(|line| line.strip_prefix("data:").map(str::trim))?;
+    if data == "[DONE]" {
+        return None;
+    }
+    let value: serde_json::Value = serde_json::from_str(data).ok()?;
+    value
+        .get("type")
+        .and_then(|t| t.as_str())
+        .map(str::to_string)
+}
+
+/// Single-stream normalizer for the runner's forwarded SSE events.
+///
+/// The runner multiplexes three event sources into one client stream:
+/// tool prefix events, the provider's per-turn streams, and the
+/// tool-synthesized execution events. Each source numbers its own
+/// `sequence_number` / `output_index` from zero, so without
+/// normalization they collide. This rewriter assigns a single monotonic
+/// `sequence_number` to every event and a stable `output_index` per
+/// item id, then reconstructs the terminal `response.output` from the
+/// `output_item.done` items it actually forwarded — so the persisted /
+/// retrieved response carries exactly the items the client saw streamed
+/// (e.g. `mcp_list_tools` / `mcp_call`), not the provider's last-turn
+/// view.
+struct StreamRewriter {
+    seq: u64,
+    next_output_index: u64,
+    /// item id → assigned `output_index`, so added/done/delta events for
+    /// one item share a slot.
+    item_index: HashMap<String, u64>,
+    /// Output items captured in forward order, for terminal-output
+    /// reconstruction.
+    output_items: Vec<serde_json::Value>,
+    /// item id → position in `output_items`, to dedupe a re-emitted item.
+    output_pos: HashMap<String, usize>,
+    /// Stable Hadrian `resp_…` id stamped onto every lifecycle event's
+    /// `response.id`, replacing the provider's per-turn id (e.g.
+    /// OpenRouter's `gen-…`). Matches the persisted/retrievable id so a
+    /// streaming client sees one stable id across the whole tool loop.
+    /// `None` when the response isn't persisted — the provider id passes
+    /// through unchanged.
+    response_id: Option<String>,
+    /// Whether a `response.created` / `response.in_progress` has already
+    /// been forwarded. The server-tool loop concatenates one provider
+    /// stream per turn, each opening with its own start events; only the
+    /// first of each may reach the client so the loop reads as a single
+    /// response.
+    seen_created: bool,
+    seen_in_progress: bool,
+    /// Upstream item id → normalized stable id. Providers may hand back
+    /// placeholder ids (e.g. OpenRouter's `rs_tmp_…` / `msg_tmp_…`); these
+    /// are rewritten to clean, stable ids consistently across every event
+    /// that references the item.
+    id_map: HashMap<String, String>,
+    /// One-shot tool prefix events (the MCP `mcp_list_tools` snapshot)
+    /// held back until after `response.created` / `response.in_progress`
+    /// so the stream opens with the lifecycle events the spec requires
+    /// first, not the catalog.
+    deferred_prefix: Vec<Bytes>,
+    prefix_flushed: bool,
+    /// `(function-name prefix, original tool JSON)` pairs for collapsing
+    /// rewritten MCP function tools back into the caller's original `mcp`
+    /// entry on the echoed `response.tools`. Empty when no MCP rewrite ran.
+    mcp_tool_echo: Vec<(String, serde_json::Value)>,
+    /// Running sum of the `usage` carried on each *suppressed* intermediate
+    /// turn's terminal event. The runner drops those events from the client
+    /// stream, so without this their tokens/cost would be lost; the total is
+    /// folded into the final terminal event's own usage by [`Self::rewrite_one`]
+    /// so the streamed/persisted/billed usage reflects the whole loop.
+    carried_usage: Option<ResponsesUsage>,
+}
+
+impl StreamRewriter {
+    fn new(response_id: Option<String>, mcp_tool_echo: Vec<(String, serde_json::Value)>) -> Self {
+        Self {
+            seq: 0,
+            next_output_index: 0,
+            item_index: HashMap::new(),
+            output_items: Vec::new(),
+            output_pos: HashMap::new(),
+            response_id,
+            seen_created: false,
+            seen_in_progress: false,
+            id_map: HashMap::new(),
+            deferred_prefix: Vec::new(),
+            prefix_flushed: false,
+            mcp_tool_echo,
+            carried_usage: None,
+        }
+    }
+
+    /// Fold a *suppressed* intermediate turn's `response.usage` into the
+    /// carried total. The runner calls this for terminal events it drops from
+    /// the client stream (so their usage isn't lost); events without a
+    /// `response.usage` (e.g. `response.created` / `response.in_progress`)
+    /// no-op. Only effective with [`ToolLoopRunner::rewrite_output`], which the
+    /// `/v1/responses` pipeline always enables for multi-turn loops.
+    fn accumulate_suppressed_usage(&mut self, event: &[u8]) {
+        let Ok(text) = std::str::from_utf8(event) else {
+            return;
+        };
+        let Some(data) = text
+            .lines()
+            .find_map(|line| line.strip_prefix("data:").map(str::trim))
+        else {
+            return;
+        };
+        let Ok(value) = serde_json::from_str::<serde_json::Value>(data) else {
+            return;
+        };
+        let Some(usage_val) = value.get("response").and_then(|r| r.get("usage")) else {
+            return;
+        };
+        let Ok(usage) = serde_json::from_value::<ResponsesUsage>(usage_val.clone()) else {
+            return;
+        };
+        match self.carried_usage.as_mut() {
+            Some(acc) => acc.accumulate(&usage),
+            None => self.carried_usage = Some(usage),
+        }
+    }
+
+    /// Collapse rewritten MCP function tools on a lifecycle event's
+    /// `response.tools` array back into the caller's original `mcp` entry.
+    /// Under `hadrian_hosted` the request's `mcp` tool is expanded into N
+    /// `mcp_<label>__<tool>` function tools before reaching the provider, so
+    /// the provider echoes those internal functions. This replaces the first
+    /// function tool of each label's run with the original `mcp` entry and
+    /// drops the rest, leaving every non-MCP tool untouched — so the echoed
+    /// `tools` match what the caller sent, per the OpenAI spec.
+    fn restore_mcp_tools(&self, tools: &mut serde_json::Value) {
+        if self.mcp_tool_echo.is_empty() {
+            return;
+        }
+        let Some(arr) = tools.as_array() else {
+            return;
+        };
+        let mut out: Vec<serde_json::Value> = Vec::with_capacity(arr.len());
+        let mut emitted: Vec<&str> = Vec::new();
+        for tool in arr {
+            let fn_name = (tool.get("type").and_then(|t| t.as_str()) == Some("function"))
+                .then(|| tool.get("name").and_then(|n| n.as_str()))
+                .flatten();
+            let matched = fn_name.and_then(|name| {
+                self.mcp_tool_echo
+                    .iter()
+                    .find(|(prefix, _)| name.starts_with(prefix.as_str()))
+            });
+            match matched {
+                Some((prefix, original)) => {
+                    // Emit the original `mcp` entry once per label, at the
+                    // position of its first function tool; skip the rest.
+                    if !emitted.contains(&prefix.as_str()) {
+                        emitted.push(prefix.as_str());
+                        out.push(original.clone());
+                    }
+                }
+                None => out.push(tool.clone()),
+            }
+        }
+        *tools = serde_json::Value::Array(out);
+    }
+
+    /// Hold a one-shot prefix event back until the lifecycle start events
+    /// have been forwarded. Flushed by [`Self::flush_prefix`].
+    fn defer_prefix(&mut self, event: Bytes) {
+        self.deferred_prefix.push(event);
+    }
+
+    /// Normalize an upstream item id to a stable id. Placeholder ids
+    /// carrying a `_tmp_` marker are rewritten to `<prefix>_<token>`
+    /// (preserving the `rs`/`msg`/… type prefix); already-clean ids pass
+    /// through. Mapping is memoized so every event referencing the item
+    /// (added / delta / done / content_part) shares one id.
+    fn normalize_id(&mut self, raw: &str) -> String {
+        if let Some(existing) = self.id_map.get(raw) {
+            return existing.clone();
+        }
+        let normalized = match raw.find("_tmp_") {
+            Some(idx) => format!("{}_{}", &raw[..idx], uuid::Uuid::new_v4().simple()),
+            None => raw.to_string(),
+        };
+        self.id_map.insert(raw.to_string(), normalized.clone());
+        normalized
+    }
+
+    /// Append every deferred prefix event (rewritten through the normal
+    /// path) into `buf`, marking the prefix flushed.
+    fn flush_prefix(&mut self, buf: &mut Vec<u8>) {
+        if self.prefix_flushed {
+            return;
+        }
+        self.prefix_flushed = true;
+        for event in std::mem::take(&mut self.deferred_prefix) {
+            buf.extend_from_slice(&self.rewrite_one(event));
+        }
+    }
+
+    /// Rewrite one SSE event, applying lifecycle de-duplication and
+    /// prefix ordering on top of the core [`Self::rewrite_one`] transform.
+    /// Returns empty bytes for a suppressed event (a duplicate lifecycle
+    /// start), or one-or-more concatenated SSE events when deferred prefix
+    /// events are flushed alongside this one.
+    fn rewrite(&mut self, event: Bytes) -> Bytes {
+        let etype = event_type_of(&event);
+        // De-dupe the per-turn lifecycle start events: forward only the
+        // first `response.created` / `response.in_progress`.
+        match etype.as_deref() {
+            Some("response.created") => {
+                if self.seen_created {
+                    return Bytes::new();
+                }
+                self.seen_created = true;
+            }
+            Some("response.in_progress") => {
+                if self.seen_in_progress {
+                    return Bytes::new();
+                }
+                self.seen_in_progress = true;
+            }
+            _ => {}
+        }
+
+        let is_start = matches!(
+            etype.as_deref(),
+            Some("response.created" | "response.in_progress")
+        );
+        // Keep-alive heartbeats can arrive before `response.created` (the
+        // pipeline emits them while waiting on the upstream's first byte);
+        // they must not trigger the prefix flush, or the catalog would
+        // precede `response.created`.
+        let is_keep_alive = matches!(etype.as_deref(), Some("response.keep_alive"));
+        let mut buf = Vec::new();
+        // Fallback flush before the first real (non-start, non-heartbeat)
+        // event, but only once `response.created` has been forwarded — so
+        // the catalog can never lead the stream even if `in_progress` is
+        // absent.
+        if !is_start && !is_keep_alive && self.seen_created {
+            self.flush_prefix(&mut buf);
+        }
+        buf.extend_from_slice(&self.rewrite_one(event));
+        // Primary: emit the prefix right after `response.in_progress` (the
+        // spec's first post-lifecycle slot).
+        if matches!(etype.as_deref(), Some("response.in_progress")) {
+            self.flush_prefix(&mut buf);
+        }
+        Bytes::from(buf)
+    }
+
+    /// Core transform for one complete SSE event: normalize sequence
+    /// number, output index, item ids and `response.id`, accumulate the
+    /// terminal output, and re-frame with an `event:` line. Non-JSON
+    /// events (`[DONE]`, comments) and unparseable payloads pass through
+    /// untouched. Preserves any non-`data:` framing lines already present.
+    fn rewrite_one(&mut self, event: Bytes) -> Bytes {
+        let Ok(text) = std::str::from_utf8(&event) else {
+            return event;
+        };
+        // Split SSE framing: keep non-`data:` field lines verbatim, join
+        // the `data:` payloads (one event may carry several).
+        let mut prefix_lines: Vec<&str> = Vec::new();
+        let mut data_parts: Vec<&str> = Vec::new();
+        for line in text.split('\n') {
+            let line = line.strip_suffix('\r').unwrap_or(line);
+            if line.is_empty() || line.starts_with(':') {
+                continue;
+            }
+            if let Some(rest) = line.strip_prefix("data:") {
+                data_parts.push(rest.strip_prefix(' ').unwrap_or(rest));
+            } else {
+                prefix_lines.push(line);
+            }
+        }
+        if data_parts.is_empty() {
+            return event;
+        }
+        let data = data_parts.join("\n");
+        if data.trim() == "[DONE]" {
+            return event;
+        }
+        let Ok(mut json) = serde_json::from_str::<serde_json::Value>(&data) else {
+            return event;
+        };
+        let Some(obj) = json.as_object_mut() else {
+            return event;
+        };
+        let Some(event_type) = obj.get("type").and_then(|t| t.as_str()).map(str::to_string) else {
+            return event;
+        };
+
+        // (1) One monotonic sequence_number across the whole stream.
+        obj.insert(
+            "sequence_number".into(),
+            serde_json::Value::from(self.next_seq()),
+        );
+
+        // (1a) Stamp the stable response id onto lifecycle events,
+        // replacing the provider's per-turn id so the client sees one id.
+        if let Some(ref rid) = self.response_id
+            && let Some(resp) = obj.get_mut("response").and_then(|r| r.as_object_mut())
+            && resp.contains_key("id")
+        {
+            resp.insert("id".into(), serde_json::Value::from(rid.clone()));
+        }
+
+        // (1c) Collapse rewritten MCP function tools on the echoed
+        // `response.tools` back into the caller's original `mcp` entry so the
+        // client never sees the internal `mcp_<label>__<tool>` expansion.
+        if let Some(tools) = obj
+            .get_mut("response")
+            .and_then(|r| r.as_object_mut())
+            .and_then(|r| r.get_mut("tools"))
+        {
+            self.restore_mcp_tools(tools);
+        }
+
+        // (1b) Normalize placeholder item ids (`rs_tmp_…`, `msg_tmp_…`)
+        // to stable ids, consistently across `item.id` and `item_id`.
+        if let Some(raw) = obj
+            .get("item")
+            .and_then(|i| i.get("id"))
+            .and_then(|v| v.as_str())
+            .map(str::to_string)
+        {
+            let norm = self.normalize_id(&raw);
+            if let Some(item) = obj.get_mut("item").and_then(|i| i.as_object_mut()) {
+                item.insert("id".into(), serde_json::Value::from(norm));
+            }
+        }
+        if let Some(raw) = obj
+            .get("item_id")
+            .and_then(|v| v.as_str())
+            .map(str::to_string)
+        {
+            let norm = self.normalize_id(&raw);
+            obj.insert("item_id".into(), serde_json::Value::from(norm));
+        }
+
+        // (2) Stable output_index per item id. Only events that already
+        // carry an output_index are remapped.
+        if obj.contains_key("output_index") {
+            let id = obj
+                .get("item")
+                .and_then(|i| i.get("id"))
+                .and_then(|v| v.as_str())
+                .or_else(|| obj.get("item_id").and_then(|v| v.as_str()))
+                .map(str::to_string);
+            if let Some(id) = id {
+                let idx = self.index_for(&id);
+                obj.insert("output_index".into(), serde_json::Value::from(idx));
+            }
+        }
+
+        // (3) Accumulate output items, and on the terminal event splice
+        // the reconstructed array into `response.output`.
+        if event_type == "response.output_item.done" {
+            if let Some(item) = obj.get("item").cloned() {
+                self.record_output_item(item);
+            }
+        } else if matches!(
+            event_type.as_str(),
+            "response.completed" | "response.failed" | "response.incomplete"
+        ) && !self.output_items.is_empty()
+            && let Some(resp) = obj.get_mut("response").and_then(|r| r.as_object_mut())
+        {
+            resp.insert(
+                "output".into(),
+                serde_json::Value::Array(self.output_items.clone()),
+            );
+        }
+
+        // (4) Fold the usage carried from suppressed intermediate turns into
+        // the final terminal event's own usage, so the streamed/persisted/
+        // billed usage reflects the whole loop, not just the last turn. Only
+        // the final terminal reaches the rewriter (intermediates are
+        // suppressed), so this fires at most once.
+        if matches!(
+            event_type.as_str(),
+            "response.completed" | "response.failed" | "response.incomplete"
+        ) && let Some(carried) = self.carried_usage.as_ref()
+            && let Some(resp) = obj.get_mut("response").and_then(|r| r.as_object_mut())
+        {
+            let mut total = carried.clone();
+            // The final turn's own usage is the larger base; fold it in (or
+            // emit the carried total alone when the final event omits usage).
+            if let Some(own) = resp
+                .get("usage")
+                .and_then(|u| serde_json::from_value::<ResponsesUsage>(u.clone()).ok())
+            {
+                total.accumulate(&own);
+            }
+            if let Ok(value) = serde_json::to_value(&total) {
+                resp.insert("usage".into(), value);
+            }
+        }
+
+        let body = serde_json::to_string(&json).unwrap_or_default();
+        let mut out = String::with_capacity(body.len() + prefix_lines.len() * 8 + 32);
+        // Re-frame with an `event:` line matching the payload `type` (the
+        // spec emits both `event:` and `data:`). Skip if the upstream
+        // already supplied one in the preserved framing lines.
+        let has_event_line = prefix_lines.iter().any(|l| l.starts_with("event:"));
+        if !has_event_line {
+            out.push_str("event: ");
+            out.push_str(&event_type);
+            out.push('\n');
+        }
+        for line in prefix_lines {
+            out.push_str(line);
+            out.push('\n');
+        }
+        out.push_str("data: ");
+        out.push_str(&body);
+        out.push_str("\n\n");
+        Bytes::from(out)
+    }
+
+    fn next_seq(&mut self) -> u64 {
+        let s = self.seq;
+        self.seq += 1;
+        s
+    }
+
+    fn index_for(&mut self, id: &str) -> u64 {
+        if let Some(i) = self.item_index.get(id) {
+            return *i;
+        }
+        let i = self.next_output_index;
+        self.next_output_index += 1;
+        self.item_index.insert(id.to_string(), i);
+        i
+    }
+
+    fn record_output_item(&mut self, item: serde_json::Value) {
+        if let Some(id) = item.get("id").and_then(|v| v.as_str()).map(str::to_string) {
+            if let Some(&pos) = self.output_pos.get(&id) {
+                self.output_items[pos] = item;
+                return;
+            }
+            self.output_pos.insert(id, self.output_items.len());
+        }
+        self.output_items.push(item);
+    }
+}
+
+/// True iff `event` is the SSE `[DONE]` end-of-stream sentinel
+/// (`data: [DONE]`), ignoring framing whitespace.
+fn is_done_sentinel(event: &[u8]) -> bool {
+    let Ok(text) = std::str::from_utf8(event) else {
+        return false;
+    };
+    text.lines()
+        .filter_map(|line| line.strip_prefix("data:").map(str::trim))
+        .any(|data| data == "[DONE]")
+}
+
+/// True for SSE events that mark a turn boundary: the start
+/// (`response.created` / `response.in_progress`) or end
+/// (`response.completed` / `response.failed` / `response.incomplete`)
+/// of one upstream stream. The runner holds these back across
+/// intermediate iterations so the client sees one coherent timeline,
+/// not N concatenated mini-streams.
+/// True for a *final* response lifecycle event (`response.completed` /
+/// `response.failed` / `response.incomplete`) — the subset of
+/// [`is_iteration_terminator`] events that close out a turn. Used to
+/// stash the suppressed terminal of a tool-calling turn so a later
+/// failure/abort path can re-emit it through the [`StreamRewriter`].
+fn is_terminal_lifecycle(event: &[u8]) -> bool {
+    matches!(
+        event_type_of(event).as_deref(),
+        Some("response.completed" | "response.failed" | "response.incomplete")
+    )
+}
+
+/// Emit the final terminal on a failure/abort path.
+///
+/// With the rewriter on we re-emit the turn's suppressed terminal
+/// through it: this normalizes ids/sequence numbers, reconstructs
+/// `response.output` from the items actually forwarded (so the
+/// already-streamed synthesized `mcp_*` items survive), collapses the
+/// rewritten MCP function tools back to the original `mcp` entry, and
+/// folds in the carried usage. Falls back to forwarding the raw
+/// `accumulated` tail when the rewriter is off (file_search /
+/// web_search / shell keep the provider stream verbatim) or when no
+/// terminal was captured (the upstream sent none).
+///
+/// Returns `Ok(raw_tail_forwarded)` — `true` only on the raw fallback,
+/// whose tail already carries a `[DONE]` so the epilogue must not emit a
+/// second one — or `Err(())` if the client disconnected.
+async fn emit_failure_terminal(
+    rewriter: &mut Option<StreamRewriter>,
+    tx: &mpsc::Sender<Result<Bytes, std::io::Error>>,
+    suppressed_terminal: Option<Bytes>,
+    accumulated: BytesMut,
+) -> Result<bool, ()> {
+    if rewriter.is_some()
+        && let Some(terminal) = suppressed_terminal
+    {
+        if let Some(out) = finalize_event(rewriter, terminal)
+            && tx.send(Ok(out)).await.is_err()
+        {
+            return Err(());
+        }
+        // The terminal went through the rewriter; the single terminal
+        // `[DONE]` is emitted by the post-loop epilogue.
+        return Ok(false);
+    }
+    // Fallback: forward the raw accumulated tail (carries its own `[DONE]`).
+    if tx.send(Ok(accumulated.freeze())).await.is_err() {
+        return Err(());
+    }
+    Ok(true)
+}
+
+fn is_iteration_terminator(event: &[u8]) -> bool {
+    let Ok(text) = std::str::from_utf8(event) else {
+        return false;
+    };
+    let Some(data) = text
+        .lines()
+        .find_map(|line| line.strip_prefix("data:").map(str::trim))
+    else {
+        return false;
+    };
+    if data == "[DONE]" {
+        return false;
+    }
+    let Ok(value): Result<serde_json::Value, _> = serde_json::from_str(data) else {
+        return false;
+    };
+    matches!(
+        value.get("type").and_then(|t| t.as_str()),
+        Some(
+            "response.created"
+                | "response.in_progress"
+                | "response.completed"
+                | "response.failed"
+                | "response.incomplete"
+        )
+    )
+}
+
+/// Inspect one SSE event and extract the assistant item it carries,
+/// if any. Returns `Some(item)` for `response.output_item.done` events
+/// whose `item` is a model-emitted `message`, `function_call`, or
+/// `reasoning`. Gateway-synthesized items (`shell_call_output`,
+/// `web_search_call`, `file_search_call`) are skipped — tools fold
+/// their own continuation items in via `apply_to_continuation`.
+fn parse_assistant_item(event: &[u8]) -> Option<ResponsesInputItem> {
+    let text = std::str::from_utf8(event).ok()?;
+    let data = text
+        .lines()
+        .find_map(|line| line.strip_prefix("data:").map(str::trim))?;
+    if data == "[DONE]" {
+        return None;
+    }
+    let value: serde_json::Value = serde_json::from_str(data).ok()?;
+    if value.get("type").and_then(|t| t.as_str()) != Some("response.output_item.done") {
+        return None;
+    }
+    let item = value.get("item")?;
+    match item.get("type").and_then(|t| t.as_str())? {
+        "message" => serde_json::from_value::<OutputMessage>(item.clone())
+            .ok()
+            .map(ResponsesInputItem::OutputMessage),
+        "function_call" => serde_json::from_value::<OutputItemFunctionCall>(item.clone())
+            .ok()
+            .map(ResponsesInputItem::OutputFunctionCall),
+        "reasoning" => serde_json::from_value::<ResponsesReasoning>(item.clone())
+            .ok()
+            .map(ResponsesInputItem::Reasoning),
+        _ => None,
+    }
+}
+
+/// Ensure `payload.input` is `Items` so callers can append to it.
+/// A `Text` input is rewrapped as a single user `EasyMessage`; `None`
+/// becomes an empty `Items` vec.
+fn normalize_input_to_items(payload: &mut CreateResponsesPayload) {
+    match payload.input.take() {
+        Some(ResponsesInput::Items(items)) => {
+            payload.input = Some(ResponsesInput::Items(items));
+        }
+        Some(ResponsesInput::Text(text)) => {
+            payload.input = Some(ResponsesInput::Items(vec![
+                ResponsesInputItem::EasyMessage(EasyInputMessage {
+                    type_: None,
+                    role: EasyInputMessageRole::User,
+                    content: EasyInputMessageContent::Text(text),
+                }),
+            ]));
+        }
+        None => {
+            payload.input = Some(ResponsesInput::Items(Vec::new()));
+        }
+    }
+}
+
+#[cfg(test)]
+mod rewriter_tests {
+    use super::*;
+
+    fn data(event: &Bytes) -> serde_json::Value {
+        let text = std::str::from_utf8(event).unwrap();
+        let line = text
+            .lines()
+            .find_map(|l| l.strip_prefix("data:").map(str::trim))
+            .unwrap();
+        serde_json::from_str(line).unwrap()
+    }
+
+    fn ev(json: serde_json::Value) -> Bytes {
+        Bytes::from(format!("data: {}\n\n", json))
+    }
+
+    #[test]
+    fn rewrites_monotonic_sequence_numbers() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        // Three events that each carried their own (colliding) seq 0.
+        let a = r.rewrite(ev(
+            serde_json::json!({"type":"response.created","sequence_number":0}),
+        ));
+        let b = r.rewrite(ev(
+            serde_json::json!({"type":"response.in_progress","sequence_number":0}),
+        ));
+        let c = r.rewrite(ev(
+            serde_json::json!({"type":"response.output_text.delta","sequence_number":0,"delta":"hi"}),
+        ));
+        assert_eq!(data(&a)["sequence_number"], 0);
+        assert_eq!(data(&b)["sequence_number"], 1);
+        assert_eq!(data(&c)["sequence_number"], 2);
+    }
+
+    #[test]
+    fn assigns_stable_output_index_per_item() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        // Two items each claiming output_index 0; the second must get 1,
+        // and the matching done/delta events for one item share its slot.
+        let added0 = r.rewrite(ev(serde_json::json!({
+            "type":"response.output_item.added","output_index":0,
+            "item":{"type":"mcp_list_tools","id":"mcpl_1"}
+        })));
+        let added1 = r.rewrite(ev(serde_json::json!({
+            "type":"response.output_item.added","output_index":0,
+            "item":{"type":"message","id":"msg_1"}
+        })));
+        let delta = r.rewrite(ev(serde_json::json!({
+            "type":"response.output_text.delta","output_index":0,"item_id":"msg_1","delta":"x"
+        })));
+        assert_eq!(data(&added0)["output_index"], 0);
+        assert_eq!(data(&added1)["output_index"], 1);
+        // The delta references msg_1 by item_id → same slot as added1.
+        assert_eq!(data(&delta)["output_index"], 1);
+    }
+
+    #[test]
+    fn reconstructs_terminal_output_from_done_items() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        // A synthesized mcp_list_tools, an mcp_call, and a final message
+        // all arrive as output_item.done across the (multi-turn) stream.
+        r.rewrite(ev(serde_json::json!({
+            "type":"response.output_item.done","output_index":0,
+            "item":{"type":"mcp_list_tools","id":"mcpl_1","server_label":"x","tools":[]}
+        })));
+        r.rewrite(ev(serde_json::json!({
+            "type":"response.output_item.done","output_index":1,
+            "item":{"type":"mcp_call","id":"mcp_1","name":"t","arguments":"{}","status":"completed"}
+        })));
+        r.rewrite(ev(serde_json::json!({
+            "type":"response.output_item.done","output_index":2,
+            "item":{"type":"message","id":"msg_1","role":"assistant"}
+        })));
+        // The provider's terminal event only knows about the last turn's
+        // message; the rewriter splices in the full forwarded history.
+        let terminal = r.rewrite(ev(serde_json::json!({
+            "type":"response.completed",
+            "response":{"id":"resp_1","output":[{"type":"message","id":"msg_1"}]}
+        })));
+        let out = data(&terminal);
+        let items = out["response"]["output"].as_array().unwrap();
+        assert_eq!(items.len(), 3);
+        assert_eq!(items[0]["type"], "mcp_list_tools");
+        assert_eq!(items[1]["type"], "mcp_call");
+        assert_eq!(items[2]["type"], "message");
+    }
+
+    #[test]
+    fn accumulates_usage_across_suppressed_turns() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        // Intermediate turn (suppressed by the runner): its usage must be
+        // captured even though the event never reaches the client stream.
+        let intermediate = ev(serde_json::json!({
+            "type": "response.completed",
+            "response": {"usage": {
+                "input_tokens": 100, "output_tokens": 50, "total_tokens": 150,
+                "input_tokens_details": {"cached_tokens": 0},
+                "output_tokens_details": {"reasoning_tokens": 10},
+                "cost": 0.001
+            }}
+        }));
+        r.accumulate_suppressed_usage(&intermediate);
+        // Final turn's terminal event reaches the rewriter normally.
+        let final_ev = r.rewrite(ev(serde_json::json!({
+            "type": "response.completed",
+            "response": {"id": "resp_1", "usage": {
+                "input_tokens": 200, "output_tokens": 30, "total_tokens": 230,
+                "input_tokens_details": {"cached_tokens": 0},
+                "output_tokens_details": {"reasoning_tokens": 5},
+                "cost": 0.002
+            }}
+        })));
+        let usage = &data(&final_ev)["response"]["usage"];
+        assert_eq!(usage["input_tokens"], 300);
+        assert_eq!(usage["output_tokens"], 80);
+        assert_eq!(usage["total_tokens"], 380);
+        assert_eq!(usage["output_tokens_details"]["reasoning_tokens"], 15);
+        assert!((usage["cost"].as_f64().unwrap() - 0.003).abs() < 1e-9);
+    }
+
+    #[test]
+    fn usage_fold_emits_carried_total_when_final_omits_usage() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        r.accumulate_suppressed_usage(&ev(serde_json::json!({
+            "type": "response.completed",
+            "response": {"usage": {
+                "input_tokens": 7, "output_tokens": 3, "total_tokens": 10,
+                "input_tokens_details": {"cached_tokens": 0},
+                "output_tokens_details": {"reasoning_tokens": 0}
+            }}
+        })));
+        // Final terminal with no usage field still surfaces the carried total.
+        let final_ev = r.rewrite(ev(serde_json::json!({
+            "type": "response.completed",
+            "response": {"id": "resp_1"}
+        })));
+        let usage = &data(&final_ev)["response"]["usage"];
+        assert_eq!(usage["input_tokens"], 7);
+        assert_eq!(usage["total_tokens"], 10);
+    }
+
+    #[test]
+    fn detects_done_sentinel() {
+        assert!(super::is_done_sentinel(b"data: [DONE]\n\n"));
+        assert!(super::is_done_sentinel(b"event: done\ndata: [DONE]\n\n"));
+        assert!(!super::is_done_sentinel(
+            b"data: {\"type\":\"response.completed\"}\n\n"
+        ));
+        assert!(!super::is_done_sentinel(b": keep-alive\n\n"));
+    }
+
+    #[test]
+    fn passes_through_done_sentinel_and_non_json() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        let done = r.rewrite(Bytes::from("data: [DONE]\n\n"));
+        assert_eq!(&done[..], b"data: [DONE]\n\n");
+    }
+
+    #[test]
+    fn collapses_rewritten_mcp_function_tools_on_echo() {
+        // The provider echoes the internal `mcp_<label>__<tool>` function
+        // tools; the rewriter must collapse each label's run back into the
+        // single original `mcp` entry, leaving non-MCP tools untouched.
+        let original = serde_json::json!({
+            "type": "mcp",
+            "server_label": "platter",
+            "server_url": "http://127.0.0.1:3100/mcp",
+            "require_approval": "never"
+        });
+        let echo = vec![("mcp_platter__".to_string(), original.clone())];
+        let mut r = StreamRewriter::new(None, echo);
+        let out = r.rewrite(ev(serde_json::json!({
+            "type": "response.created",
+            "response": {
+                "id": "resp_1",
+                "tools": [
+                    {"type": "function", "name": "mcp_platter__read"},
+                    {"type": "function", "name": "mcp_platter__bash"},
+                    {"type": "function", "name": "get_weather"}
+                ]
+            }
+        })));
+        let tools = data(&out)["response"]["tools"].as_array().unwrap().clone();
+        assert_eq!(tools.len(), 2, "two mcp functions collapse to one entry");
+        assert_eq!(tools[0]["type"], "mcp");
+        assert_eq!(tools[0]["server_label"], "platter");
+        assert!(tools[0].get("authorization").is_none());
+        // The caller's own function tool passes through unchanged.
+        assert_eq!(tools[1]["type"], "function");
+        assert_eq!(tools[1]["name"], "get_weather");
+    }
+
+    #[test]
+    fn preserves_event_field_line() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        let out = r.rewrite(Bytes::from(
+            "event: response.created\ndata: {\"type\":\"response.created\"}\n\n",
+        ));
+        let text = std::str::from_utf8(&out).unwrap();
+        assert!(text.contains("event: response.created"));
+        assert_eq!(data(&out)["sequence_number"], 0);
+    }
+
+    #[test]
+    fn does_not_overwrite_output_when_no_items_captured() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        // No output_item.done seen → leave the provider's output intact.
+        let terminal = r.rewrite(ev(serde_json::json!({
+            "type":"response.completed",
+            "response":{"id":"r","output":[{"type":"message","id":"m"}]}
+        })));
+        let items = data(&terminal)["response"]["output"]
+            .as_array()
+            .unwrap()
+            .len();
+        assert_eq!(items, 1);
+    }
+
+    #[test]
+    fn dedupes_lifecycle_start_events_across_turns() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        // Turn 1 opens the stream.
+        assert!(
+            !r.rewrite(ev(serde_json::json!({"type":"response.created"})))
+                .is_empty()
+        );
+        assert!(
+            !r.rewrite(ev(serde_json::json!({"type":"response.in_progress"})))
+                .is_empty()
+        );
+        // Turn 2 (a server-tool continuation) reopens with its own start
+        // events — those must be suppressed so the loop reads as one
+        // response.
+        assert!(
+            r.rewrite(ev(serde_json::json!({"type":"response.created"})))
+                .is_empty()
+        );
+        assert!(
+            r.rewrite(ev(serde_json::json!({"type":"response.in_progress"})))
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn defers_prefix_until_after_in_progress() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        r.defer_prefix(ev(serde_json::json!({
+            "type":"response.output_item.added","output_index":0,
+            "item":{"type":"mcp_list_tools","id":"mcpl_1"}
+        })));
+        // created leads, no prefix yet.
+        let created = r.rewrite(ev(serde_json::json!({"type":"response.created"})));
+        assert!(
+            !std::str::from_utf8(&created)
+                .unwrap()
+                .contains("mcp_list_tools")
+        );
+        // in_progress flushes the prefix immediately after it.
+        let in_progress = r.rewrite(ev(serde_json::json!({"type":"response.in_progress"})));
+        let text = std::str::from_utf8(&in_progress).unwrap();
+        let ip = text.find("response.in_progress").unwrap();
+        let cat = text.find("mcp_list_tools").unwrap();
+        assert!(ip < cat, "in_progress must precede the deferred catalog");
+    }
+
+    #[test]
+    fn flushes_prefix_before_first_real_event_when_no_in_progress() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        r.defer_prefix(ev(serde_json::json!({
+            "type":"response.output_item.added","output_index":0,
+            "item":{"type":"mcp_list_tools","id":"mcpl_1"}
+        })));
+        // created leads; in_progress never arrives, so the first real
+        // event flushes the held-back catalog.
+        r.rewrite(ev(serde_json::json!({"type":"response.created"})));
+        let out = r.rewrite(ev(serde_json::json!({
+            "type":"response.output_item.added","output_index":0,
+            "item":{"type":"message","id":"msg_1"}
+        })));
+        let text = std::str::from_utf8(&out).unwrap();
+        assert!(text.find("mcp_list_tools").unwrap() < text.find("\"message\"").unwrap());
+    }
+
+    #[test]
+    fn keep_alive_before_created_does_not_leak_prefix() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        r.defer_prefix(ev(serde_json::json!({
+            "type":"response.output_item.added","output_index":0,
+            "item":{"type":"mcp_list_tools","id":"mcpl_1"}
+        })));
+        // A heartbeat ahead of `response.created` must not flush the
+        // catalog — `response.created` has to stay ahead of it.
+        let ka = r.rewrite(ev(serde_json::json!({"type":"response.keep_alive"})));
+        assert!(!std::str::from_utf8(&ka).unwrap().contains("mcp_list_tools"));
+        let created = r.rewrite(ev(serde_json::json!({"type":"response.created"})));
+        assert!(
+            !std::str::from_utf8(&created)
+                .unwrap()
+                .contains("mcp_list_tools")
+        );
+        // in_progress finally releases it.
+        let ip = r.rewrite(ev(serde_json::json!({"type":"response.in_progress"})));
+        assert!(std::str::from_utf8(&ip).unwrap().contains("mcp_list_tools"));
+    }
+
+    #[test]
+    fn stamps_stable_response_id_onto_lifecycle_events() {
+        let mut r = StreamRewriter::new(Some("resp_stable".to_string()), Vec::new());
+        let created = r.rewrite(ev(serde_json::json!({
+            "type":"response.created","response":{"id":"gen-123","status":"in_progress"}
+        })));
+        assert_eq!(data(&created)["response"]["id"], "resp_stable");
+        let completed = r.rewrite(ev(serde_json::json!({
+            "type":"response.completed","response":{"id":"gen-456","status":"completed"}
+        })));
+        assert_eq!(data(&completed)["response"]["id"], "resp_stable");
+    }
+
+    #[test]
+    fn normalizes_tmp_item_ids_consistently() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        let added = r.rewrite(ev(serde_json::json!({
+            "type":"response.output_item.added","output_index":0,
+            "item":{"type":"message","id":"msg_tmp_abc"}
+        })));
+        let new_id = data(&added)["item"]["id"].as_str().unwrap().to_string();
+        assert!(new_id.starts_with("msg_"), "preserves the type prefix");
+        assert!(!new_id.contains("_tmp_"), "drops the placeholder marker");
+        // A later event referencing the same upstream id via item_id must
+        // map to the same normalized id.
+        let delta = r.rewrite(ev(serde_json::json!({
+            "type":"response.output_text.delta","output_index":0,"item_id":"msg_tmp_abc","delta":"x"
+        })));
+        assert_eq!(data(&delta)["item_id"], new_id);
+    }
+
+    #[test]
+    fn synthesizes_event_field_line_when_absent() {
+        let mut r = StreamRewriter::new(None, Vec::new());
+        let out = r.rewrite(ev(serde_json::json!({"type":"response.created"})));
+        let text = std::str::from_utf8(&out).unwrap();
+        assert!(text.starts_with("event: response.created\n"));
+        assert!(text.contains("data: "));
+    }
+}
diff --git a/src/services/shell_tool.rs b/src/services/shell_tool.rs
new file mode 100644
index 0000000..0fd5acb
--- /dev/null
+++ b/src/services/shell_tool.rs
@@ -0,0 +1,3156 @@
+//! Shell tool interception service for the Responses API.
+//!
+//! Detects `shell` tool calls in upstream responses, dispatches them to
+//! the configured `ShellRuntime`, emits the spec-canonical
+//! `response.output_item.added` / `.done` events carrying `shell_call`
+//! and `shell_call_output` items, and folds the final result into the
+//! next provider continuation request.
+//!
+//! Passthrough mode is handled at registration time: the orchestrator
+//! simply doesn't register a `ShellExecutor` when the configured
+//! runtime advertises `passthrough_only`. In that case the upstream
+//! provider's shell tool spec flows through unchanged.
+
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::{
+    collections::HashMap,
+    sync::Arc,
+    time::{Duration, Instant},
+};
+
+use bytes::Bytes;
+use chrono::Utc;
+use futures_util::StreamExt;
+use serde::Deserialize;
+use serde_json::Value;
+use tokio::sync::{Mutex, mpsc};
+use tracing::{debug, error, info, warn};
+use uuid::Uuid;
+
+use crate::{
+    api_types::responses::{
+        ContainerFileRef, CreateResponsesPayload, FunctionCallOutput, FunctionCallOutputType,
+        FunctionTool, KnownShellNetworkPolicyType, ResponsesAnnotation, ResponsesInput,
+        ResponsesInputItem, ResponsesToolDefinition, ShellDomainSecret, ShellEnvironment,
+        ShellNetworkPolicyType,
+    },
+    config::{ContainersConfig, ShellLimitsConfig},
+    models::UsageLogEntry,
+    pricing::CostPricingSource,
+    runtimes::{
+        EgressPolicy, ExecEvent, ExecRequest, RuntimeError, SecretMount, SessionSpec, ShellRuntime,
+        SkillMount,
+    },
+    services::{
+        container_session::{ContainerPersistence, ContainerSession, ContainerSessionRegistry},
+        input_file_staging::StagedFile,
+        server_tools::{
+            DetectedToolCall, ServerExecutedTool, ToolCallResult, ToolContext, ToolError,
+            ToolExecutionHandle,
+        },
+    },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-request environment resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Result of intersecting a per-request `ShellEnvironment` with the
+/// operator's `[features.server_tools.shell_limits]`. Drives the
+/// `SessionSpec` the executor hands to the runtime on first call.
+#[derive(Debug, Clone, Default)]
+pub struct ResolvedShellEnvironment {
+    /// Memory limit to apply to this session, in bytes. `None` means
+    /// "use the runtime backend's default".
+    pub mem_limit_bytes: Option<u64>,
+    /// Egress allowlist + secrets to mount. An empty `allow_hosts`
+    /// list means the runtime applies its built-in default.
+    pub egress_policy: EgressPolicy,
+    /// Per-request idle TTL override (in seconds). `None` falls back to
+    /// `[features.containers].default_idle_ttl_secs` at attach time.
+    pub idle_ttl_secs: Option<i64>,
+    /// `container_id` the caller explicitly referenced via
+    /// `environment.type = "container_reference"`. The executor must
+    /// attach to this exact id; mismatches between this and any
+    /// pipeline-derived hint surface as 400.
+    pub referenced_container_id: Option<String>,
+}
+
+/// Rejection reasons surfaced as `400 Bad Request` at the route layer.
+#[derive(Debug, thiserror::Error, PartialEq, Eq)]
+pub enum ShellEnvironmentError {
+    #[error("invalid memory_limit '{0}': expected '<n>[k|m|g][b]' (e.g. '512m', '1g')")]
+    BadMemoryLimit(String),
+    #[error("requested memory_limit {requested_mb} MB exceeds operator cap of {max_mb} MB")]
+    MemoryExceedsCap { requested_mb: u64, max_mb: u32 },
+    #[error("egress host '{0}' is not in the operator's allowed_egress_hosts")]
+    HostNotAllowed(String),
+    #[error("unknown domain secret placeholder '{0}' (not in allowed_domain_secrets)")]
+    UnknownSecret(String),
+    #[error("secret '{placeholder}' may not flow to host '{host}' under operator's allowed_hosts")]
+    SecretHostNotAllowed { placeholder: String, host: String },
+    #[error(
+        "inline domain secret '{name}': host '{host}' is not in operator's allowed_egress_hosts"
+    )]
+    InlineSecretHostNotAllowed { name: String, host: String },
+    #[error("container_reference.container_id is empty")]
+    EmptyContainerReferenceId,
+    #[error(
+        "network_policy.type = 'disabled' does not allow allowed_domains \
+         or domain_secrets to be set"
+    )]
+    DisabledPolicyWithFields,
+    #[error(
+        "expires_after.minutes {requested} exceeds operator cap of {max} minutes \
+         ([features.containers].max_idle_ttl_secs)"
+    )]
+    ExpiresAfterExceedsCap { requested: u32, max: u32 },
+}
+
+/// Intersect the per-request environment with the operator-pinned
+/// limits. The request can ask for a **narrower** subset of what the
+/// operator permits; anything outside that envelope is rejected.
+///
+/// Always succeeds for `request_env = None` (the caller didn't ask for
+/// anything beyond defaults). Returns an empty `EgressPolicy` when no
+/// egress was requested.
+pub fn resolve_shell_environment(
+    request_env: Option<&ShellEnvironment>,
+    operator: &ShellLimitsConfig,
+    containers: &ContainersConfig,
+) -> Result<ResolvedShellEnvironment, ShellEnvironmentError> {
+    let default_mem_bytes = operator
+        .default_mem_limit_mb
+        .map(|mb| u64::from(mb) * 1024 * 1024);
+
+    let Some(env) = request_env else {
+        return Ok(ResolvedShellEnvironment {
+            mem_limit_bytes: default_mem_bytes,
+            egress_policy: EgressPolicy::default(),
+            idle_ttl_secs: None,
+            referenced_container_id: None,
+        });
+    };
+
+    // ── memory + expires_after (auto-only) ──
+    // OpenAI's `ContainerAutoParam` includes `expires_after`; the
+    // resolver honors it here so a per-request idle TTL flows into the
+    // container row at provision time. Inline requests with no
+    // `expires_after` fall back to the container's persisted TTL (when
+    // chained) or `[features.containers].default_idle_ttl_secs` (for a
+    // fresh auto-provisioned session).
+    let max_idle_minutes = (containers.max_idle_ttl_secs / 60) as u32;
+    let (mem_limit_bytes, idle_ttl_secs) = match env {
+        ShellEnvironment::ContainerAuto(auto) => {
+            let mem = match auto.memory_limit.as_deref() {
+                Some(raw) => {
+                    let requested_bytes = parse_memory_limit(raw)
+                        .ok_or_else(|| ShellEnvironmentError::BadMemoryLimit(raw.to_string()))?;
+                    if let Some(cap_mb) = operator.max_mem_limit_mb {
+                        let cap_bytes = u64::from(cap_mb) * 1024 * 1024;
+                        if requested_bytes > cap_bytes {
+                            return Err(ShellEnvironmentError::MemoryExceedsCap {
+                                requested_mb: requested_bytes / (1024 * 1024),
+                                max_mb: cap_mb,
+                            });
+                        }
+                    }
+                    Some(requested_bytes)
+                }
+                None => default_mem_bytes,
+            };
+            let ttl = match auto.expires_after.as_ref() {
+                Some(exp) => {
+                    if exp.minutes > max_idle_minutes {
+                        return Err(ShellEnvironmentError::ExpiresAfterExceedsCap {
+                            requested: exp.minutes,
+                            max: max_idle_minutes,
+                        });
+                    }
+                    Some(i64::from(exp.minutes) * 60)
+                }
+                None => None,
+            };
+            (mem, ttl)
+        }
+        ShellEnvironment::ContainerReference(_) | ShellEnvironment::Local(_) => {
+            (default_mem_bytes, None)
+        }
+    };
+
+    let referenced_container_id = match env {
+        ShellEnvironment::ContainerReference(r) => {
+            let trimmed = r.container_id.trim();
+            if trimmed.is_empty() {
+                return Err(ShellEnvironmentError::EmptyContainerReferenceId);
+            }
+            Some(trimmed.to_string())
+        }
+        ShellEnvironment::ContainerAuto(_) | ShellEnvironment::Local(_) => None,
+    };
+
+    // ── egress hosts + domain secrets ──
+    let mut allow_hosts: Vec<String> = Vec::new();
+    let mut secrets: Vec<SecretMount> = Vec::new();
+    if let Some(policy) = env.network_policy() {
+        // `disabled` ⇒ deny-all egress: no allowed_domains, no
+        // domain_secrets. We treat the disabled policy as authoritative
+        // and refuse to silently ignore allowlist entries the caller
+        // also sent.
+        if matches!(
+            policy.type_,
+            ShellNetworkPolicyType::Known(KnownShellNetworkPolicyType::Disabled)
+        ) {
+            if !policy.allowed_domains.is_empty() || !policy.domain_secrets.is_empty() {
+                return Err(ShellEnvironmentError::DisabledPolicyWithFields);
+            }
+            // allow_hosts stays empty → runtime applies deny-all.
+            return Ok(ResolvedShellEnvironment {
+                mem_limit_bytes,
+                egress_policy: EgressPolicy {
+                    allow_hosts: Vec::new(),
+                    secrets: Vec::new(),
+                },
+                idle_ttl_secs,
+                referenced_container_id,
+            });
+        }
+        for host in &policy.allowed_domains {
+            if !host_matches_any(host, &operator.allowed_egress_hosts) {
+                return Err(ShellEnvironmentError::HostNotAllowed(host.clone()));
+            }
+        }
+        allow_hosts = policy.allowed_domains.clone();
+
+        for entry in &policy.domain_secrets {
+            match entry {
+                ShellDomainSecret::Reference(r) => {
+                    let allowed = operator
+                        .allowed_domain_secrets
+                        .get(&r.placeholder)
+                        .ok_or_else(|| {
+                            ShellEnvironmentError::UnknownSecret(r.placeholder.clone())
+                        })?;
+                    for host in &r.allowed_domains {
+                        if !host_matches_any(host, &allowed.allowed_hosts) {
+                            return Err(ShellEnvironmentError::SecretHostNotAllowed {
+                                placeholder: r.placeholder.clone(),
+                                host: host.clone(),
+                            });
+                        }
+                    }
+                    // Empty `allowed_domains` in the request inherits the
+                    // operator's full list — same convention as omitting the
+                    // field in OpenAI's spec.
+                    let allowed_hosts = if r.allowed_domains.is_empty() {
+                        allowed.allowed_hosts.clone()
+                    } else {
+                        r.allowed_domains.clone()
+                    };
+                    secrets.push(SecretMount {
+                        placeholder: r.placeholder.clone(),
+                        value: allowed.value.clone(),
+                        allowed_hosts,
+                    });
+                }
+                ShellDomainSecret::Inline(inline) => {
+                    // Inline form puts the raw value on the wire (OpenAI
+                    // shape). Hadrian still enforces the operator's host
+                    // allowlist: the secret may only flow to a host the
+                    // operator permits, not anywhere the caller wants.
+                    if !host_matches_any(&inline.domain, &operator.allowed_egress_hosts) {
+                        return Err(ShellEnvironmentError::InlineSecretHostNotAllowed {
+                            name: inline.name.clone(),
+                            host: inline.domain.clone(),
+                        });
+                    }
+                    secrets.push(SecretMount {
+                        placeholder: inline.name.clone(),
+                        value: inline.value.clone(),
+                        allowed_hosts: vec![inline.domain.clone()],
+                    });
+                }
+            }
+        }
+    }
+
+    Ok(ResolvedShellEnvironment {
+        mem_limit_bytes,
+        egress_policy: EgressPolicy {
+            allow_hosts,
+            secrets,
+        },
+        idle_ttl_secs,
+        referenced_container_id,
+    })
+}
+
+/// Public façade for [`parse_memory_limit`] used by
+/// `POST /v1/containers` to pre-validate the request body before
+/// persisting it.
+pub fn parse_memory_limit_pub(raw: &str) -> Option<u64> {
+    parse_memory_limit(raw)
+}
+
+/// Parse OpenAI-style `memory_limit` strings: `"512m"`, `"1g"`,
+/// `"1024MB"`, case-insensitive. Returns the value in bytes, or
+/// `None` on any parse failure. A bare integer is treated as bytes.
+fn parse_memory_limit(raw: &str) -> Option<u64> {
+    let s = raw.trim().to_ascii_lowercase();
+    let (digits, suffix) = s
+        .find(|c: char| !c.is_ascii_digit())
+        .map(|i| (&s[..i], s[i..].trim()))
+        .unwrap_or((s.as_str(), ""));
+    if digits.is_empty() {
+        return None;
+    }
+    let n: u64 = digits.parse().ok()?;
+    let mult: u64 = match suffix {
+        "" | "b" => 1,
+        "k" | "kb" => 1024,
+        "m" | "mb" => 1024 * 1024,
+        "g" | "gb" => 1024 * 1024 * 1024,
+        _ => return None,
+    };
+    n.checked_mul(mult)
+}
+
+/// `host` is allowed iff it matches any entry in `patterns`. Entries
+/// may be exact hostnames or `*.suffix.example` glob patterns;
+/// a single `"*"` matches anything.
+fn host_matches_any(host: &str, patterns: &[String]) -> bool {
+    patterns.iter().any(|p| host_matches(host, p))
+}
+
+fn host_matches(host: &str, pattern: &str) -> bool {
+    if pattern == "*" {
+        return true;
+    }
+    // Normalize a trailing dot on the host — `example.com.` and
+    // `example.com` are the same FQDN and operators don't write the
+    // trailing form into allowlists. Cheap to strip; avoids a surprise
+    // miss when the model echoes a fully-qualified name back through
+    // curl or DNS tooling.
+    let host = host.trim_end_matches('.');
+    if let Some(suffix) = pattern.strip_prefix("*.") {
+        // `*.example.com` matches any subdomain (`a.example.com`,
+        // `a.b.example.com`) but not the bare apex.
+        let suffix = suffix.trim_end_matches('.');
+        return host.len() > suffix.len() + 1
+            && host.ends_with(suffix)
+            && host.as_bytes()[host.len() - suffix.len() - 1] == b'.';
+    }
+    host.eq_ignore_ascii_case(pattern.trim_end_matches('.'))
+}
+
+/// Identity fields captured at request time for shell-tool usage
+/// attribution. Mirrors the tuple `extract_identity` returns elsewhere.
+#[derive(Debug, Clone, Default)]
+pub struct ShellPrincipal {
+    pub api_key_id: Option<Uuid>,
+    pub user_id: Option<Uuid>,
+    pub org_id: Option<Uuid>,
+    pub project_id: Option<Uuid>,
+    pub team_id: Option<Uuid>,
+    pub service_account_id: Option<Uuid>,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool arguments (function schema the model sees)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Where shell execution actually happens. Drives the tone of the
+/// dynamic tool description emitted to non-OpenAI providers.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ShellExecutionLocation {
+    /// Hadrian-hosted sandbox VM (microsandbox / opensandbox).
+    HadrianSandbox,
+    /// The API client fulfills the call itself (`client_passthrough`).
+    /// Hadrian can't promise anything about the environment.
+    ApiClient,
+}
+
+/// Everything the model should be told about its shell tool for a given
+/// request. Built once per request from the resolved runtime, container
+/// config, and effective shell environment, then folded into the
+/// function-mode description rewritten in [`preprocess_shell_tools`].
+///
+/// The default value produces a minimal, conservative description
+/// suitable when no concrete sandbox is wired up.
+#[derive(Debug, Clone)]
+pub struct ShellToolHint {
+    pub location: ShellExecutionLocation,
+    /// Workdir inside the sandbox where input files are staged and
+    /// captured output files are read from. Always `/mnt/data` today.
+    pub workdir: &'static str,
+    /// Idle / capture behavior is enabled (containers feature on).
+    pub container_persistence: bool,
+    /// Network access from inside the sandbox.
+    pub network_summary: ShellNetworkSummary,
+    /// Memory limit applied to the sandbox, in MiB.
+    pub mem_limit_mb: Option<u64>,
+    /// Per-command wall-clock cap, in seconds.
+    pub command_timeout_secs: u64,
+    /// stdout/stderr fed back to the model are truncated past this many
+    /// characters with a head+tail keep.
+    pub max_output_chars: usize,
+    /// Names of skill bundles mounted under `/skills/<id>` for this
+    /// request.
+    pub mounted_skill_ids: Vec<String>,
+    /// Operator-supplied description of the container environment
+    /// (`[features.server_tools.shell_limits].environment_description`):
+    /// pre-installed toolchains, how to install packages, etc. Appended
+    /// verbatim to the tool description. `None` appends nothing.
+    pub environment_description: Option<String>,
+}
+
+/// Network access summary for the model. Tone matches OpenAI's
+/// `network_policy` field.
+#[derive(Debug, Clone)]
+pub enum ShellNetworkSummary {
+    /// No outbound network from the sandbox.
+    NoNetwork,
+    /// Egress restricted to specific hosts.
+    Allowlist(Vec<String>),
+    /// Unrestricted outbound network.
+    Unrestricted,
+    /// Hadrian can't tell (e.g. client-fulfilled mode).
+    Unknown,
+}
+
+impl Default for ShellToolHint {
+    fn default() -> Self {
+        Self {
+            location: ShellExecutionLocation::HadrianSandbox,
+            workdir: crate::services::container_session::MNT_DATA,
+            container_persistence: false,
+            network_summary: ShellNetworkSummary::Unknown,
+            mem_limit_mb: None,
+            command_timeout_secs: 300,
+            max_output_chars: DEFAULT_MAX_OUTPUT_CHARS,
+            mounted_skill_ids: Vec::new(),
+            environment_description: None,
+        }
+    }
+}
+
+impl ShellToolHint {
+    /// Render the hint into the `description` string the model sees on
+    /// the function-mode shell tool. The wording is deliberately
+    /// prescriptive about workdir, file capture, persistence, network,
+    /// and truncation — model providers' built-in shell tools embed
+    /// similar guidance (Anthropic's `bash_20250124` adds ~245 tokens
+    /// of it) and without it models guess at paths and lose output.
+    pub fn render_description(&self) -> String {
+        let mut s = String::with_capacity(512);
+        s.push_str(
+            "Execute a shell command and return its stdout, stderr, and exit code. \
+             Use this for running scripts, processing data, or any task that benefits \
+             from a shell.\n\n",
+        );
+
+        match self.location {
+            ShellExecutionLocation::HadrianSandbox => {
+                s.push_str(&format!(
+                    "Runs in a sandboxed Linux environment hosted by the gateway. \
+                     Working directory is `{}`.\n",
+                    self.workdir
+                ));
+                if self.container_persistence {
+                    s.push_str(&format!(
+                        "- Files you write under `{}` are captured and returned to the \
+                         caller as `container_file_citation` annotations. The caller can \
+                         download them via the containers API.\n",
+                        self.workdir
+                    ));
+                    s.push_str(
+                        "- State under that directory **persists across turns** in the \
+                         same response and across responses that chain via \
+                         `previous_response_id`. Files you wrote earlier are still there.\n",
+                    );
+                } else {
+                    s.push_str(
+                        "- Files written during this call are not persisted between \
+                         turns; recreate any intermediate state you need.\n",
+                    );
+                }
+                if !self.mounted_skill_ids.is_empty() {
+                    s.push_str("- Skill bundles mounted for this request: ");
+                    for (i, id) in self.mounted_skill_ids.iter().enumerate() {
+                        if i > 0 {
+                            s.push_str(", ");
+                        }
+                        s.push_str(&format!("`/skills/{id}`"));
+                    }
+                    s.push_str(
+                        ". Inspect those directories for tools or data the \
+                                caller wants you to use.\n",
+                    );
+                }
+                match &self.network_summary {
+                    ShellNetworkSummary::NoNetwork => {
+                        s.push_str(
+                            "- **No outbound network.** Do not attempt to fetch \
+                                    packages, call APIs, or resolve hostnames.\n",
+                        );
+                    }
+                    ShellNetworkSummary::Allowlist(hosts) if !hosts.is_empty() => {
+                        s.push_str("- Outbound network is restricted to these hosts only: ");
+                        for (i, h) in hosts.iter().enumerate() {
+                            if i > 0 {
+                                s.push_str(", ");
+                            }
+                            s.push_str(&format!("`{h}`"));
+                        }
+                        s.push_str(". Reaching anything else will fail.\n");
+                    }
+                    ShellNetworkSummary::Allowlist(_) => {
+                        s.push_str("- Outbound network uses an operator-defined allowlist.\n");
+                    }
+                    ShellNetworkSummary::Unrestricted => {
+                        s.push_str(
+                            "- Outbound network is unrestricted, but prefer minimal \
+                             egress and never exfiltrate secrets the caller didn't share.\n",
+                        );
+                    }
+                    ShellNetworkSummary::Unknown => {}
+                }
+                if let Some(mb) = self.mem_limit_mb {
+                    s.push_str(&format!(
+                        "- Memory limit: {mb} MiB. Stream large datasets through pipes \
+                         rather than loading them all in memory.\n"
+                    ));
+                }
+                s.push_str(&format!(
+                    "- Per-command wall-clock limit: {}s. Long-running jobs must be \
+                     broken into steps.\n",
+                    self.command_timeout_secs
+                ));
+            }
+            ShellExecutionLocation::ApiClient => {
+                s.push_str(
+                    "Runs on the **API client**, not the gateway. The client decides \
+                     the working directory, available tools, and network policy — assume \
+                     a generic POSIX shell with whatever the caller's environment \
+                     provides. Do not assume packages, files, or services are present \
+                     unless the caller said so.\n",
+                );
+            }
+        }
+
+        s.push_str(&format!(
+            "\nstdout and stderr fed back to you are truncated past {} characters \
+             (head + tail kept). For long output, redirect to a file (e.g. \
+             `cmd > /mnt/data/log.txt`) and grep / tail it on a follow-up call.",
+            self.max_output_chars
+        ));
+
+        // Operator-supplied environment notes (pre-installed toolchains, how to
+        // install packages, etc.) so the model doesn't waste turns probing.
+        if let Some(desc) = self.environment_description.as_deref() {
+            let desc = desc.trim();
+            if !desc.is_empty() {
+                s.push_str("\n\nEnvironment:\n");
+                s.push_str(desc);
+            }
+        }
+
+        s
+    }
+}
+
+/// Arguments the model emits when invoking the function-mode shell
+/// tool. Mirrors OpenAI's `shell_call.action` object: `commands` is a
+/// sequence of shell strings executed in order in the same session,
+/// with optional `working_directory`, `env`, `timeout_ms`, and
+/// `max_output_length` overrides.
+///
+/// ```json
+/// {"action": {"commands": ["cd src", "ls -la"], "timeout_ms": 5000}}
+/// ```
+#[derive(Debug, Clone, Default, Deserialize)]
+pub struct ShellToolArguments {
+    /// Nested OpenAI `action` object carrying the commands and
+    /// per-call overrides.
+    #[serde(default)]
+    pub action: Option<ShellToolAction>,
+    /// Optional stdin piped to the joined command script. Hadrian
+    /// extension — kept because the spec doesn't carry stdin and some
+    /// useful flows (`base64 -d > out`) need it.
+    #[serde(default)]
+    pub stdin: Option<String>,
+}
+
+/// Per-call action object (OpenAI's `shell_call.action` shape).
+#[derive(Debug, Clone, Default, Deserialize)]
+pub struct ShellToolAction {
+    /// Shell command lines to execute, in order, in the same session.
+    /// Joined with newlines and run as a single script — exit_code is
+    /// the script's final exit status. Use explicit `&&` chains inside
+    /// one entry when the model wants short-circuit semantics.
+    #[serde(default)]
+    pub commands: Vec<String>,
+    /// Per-call timeout in milliseconds. Clamped to the operator's
+    /// `command_timeout_secs * 1000` cap; values larger than the cap
+    /// are silently shortened rather than rejected, mirroring
+    /// OpenAI's behaviour.
+    #[serde(default)]
+    pub timeout_ms: Option<u64>,
+    /// Per-call cap on stdout+stderr characters fed back to the
+    /// model. Clamped to the operator's `max_output_chars` cap.
+    #[serde(default)]
+    pub max_output_length: Option<usize>,
+    /// Optional environment variables for this call. Names must match
+    /// `[A-Za-z_][A-Za-z0-9_]*`; values are passed through to the
+    /// shell verbatim.
+    #[serde(default)]
+    pub env: Option<HashMap<String, String>>,
+    /// Optional working directory for this call. When unset, the
+    /// runtime's default (`/mnt/data`) is used.
+    #[serde(default)]
+    pub working_directory: Option<String>,
+}
+
+/// One concrete shell call after parsing the `action` shape.
+#[derive(Debug, Clone)]
+pub struct ResolvedShellArgs {
+    /// Spec-shaped command list — joined into a script for execution.
+    pub commands: Vec<String>,
+    pub stdin: Option<String>,
+    pub timeout_ms: Option<u64>,
+    pub max_output_length: Option<usize>,
+    pub env: Option<HashMap<String, String>>,
+    pub working_directory: Option<String>,
+}
+
+impl ResolvedShellArgs {
+    /// Join `commands` into a single shell script. Empty / whitespace
+    /// entries are dropped — they'd otherwise produce confusing
+    /// "command not found" lines.
+    pub fn joined_script(&self) -> String {
+        self.commands
+            .iter()
+            .map(|s| s.trim())
+            .filter(|s| !s.is_empty())
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+}
+
+impl ShellToolArguments {
+    pub const FUNCTION_NAME: &'static str = "shell";
+
+    pub fn parse(arguments_json: &str) -> Option<Self> {
+        serde_json::from_str(arguments_json).ok()
+    }
+
+    /// Resolve the parsed arguments into a flat call shape. Returns
+    /// `None` when no non-empty command line was supplied.
+    pub fn resolve(self) -> Option<ResolvedShellArgs> {
+        let action = self.action?;
+        let commands: Vec<String> = action
+            .commands
+            .into_iter()
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty())
+            .collect();
+        if commands.is_empty() {
+            return None;
+        }
+        Some(ResolvedShellArgs {
+            commands,
+            stdin: self.stdin,
+            timeout_ms: action.timeout_ms,
+            max_output_length: action.max_output_length,
+            env: action.env,
+            working_directory: action.working_directory,
+        })
+    }
+
+    pub fn function_parameters_schema() -> Value {
+        serde_json::json!({
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "object",
+                    "description": "Spec-compliant action object (matches OpenAI's shell_call.action shape).",
+                    "properties": {
+                        "commands": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "minItems": 1,
+                            "description": "Shell command lines, executed in order in the same session. Joined into a script — use explicit `&&` for short-circuit semantics."
+                        },
+                        "timeout_ms": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "Per-call timeout in milliseconds. Clamped to the operator's cap."
+                        },
+                        "max_output_length": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "Per-call cap on stdout+stderr characters fed back to the model. Clamped to the operator's cap."
+                        },
+                        "env": {
+                            "type": "object",
+                            "additionalProperties": {"type": "string"},
+                            "description": "Extra environment variables exported for this call only."
+                        },
+                        "working_directory": {
+                            "type": "string",
+                            "description": "Override working directory for this call (defaults to /mnt/data)."
+                        }
+                    },
+                    "required": ["commands"],
+                    "additionalProperties": false
+                },
+                "stdin": {
+                    "type": "string",
+                    "description": "Optional stdin piped to the joined command script."
+                }
+            },
+            "required": ["action"],
+            "additionalProperties": false
+        })
+    }
+
+    /// Build the function-tool JSON the model sees, embedding the
+    /// rendered hint as the description.
+    pub fn function_tool_definition(hint: &ShellToolHint) -> Value {
+        serde_json::json!({
+            "type": "function",
+            "name": Self::FUNCTION_NAME,
+            "description": hint.render_description(),
+            "parameters": Self::function_parameters_schema(),
+            "strict": false,
+        })
+    }
+}
+
+/// Rewrite `shell` tool definitions in the payload to function tools so
+/// non-OpenAI models can invoke them. The hint describes the effective
+/// sandbox so the model sees workdir, persistence, network, and
+/// truncation rules accurate for *this* request.
+///
+/// Called by `routes/execution.rs` for every non-passthrough provider
+/// path. In OpenAI passthrough modes the native spec is left intact and
+/// this is skipped.
+pub fn preprocess_shell_tools(payload: &mut CreateResponsesPayload, hint: &ShellToolHint) {
+    let Some(tools) = payload.tools.as_mut() else {
+        return;
+    };
+    let rewrite = ResponsesToolDefinition::Function(
+        FunctionTool::from_json(ShellToolArguments::function_tool_definition(hint))
+            .expect("shell function-tool definition is well-formed"),
+    );
+    for tool in tools.iter_mut() {
+        if tool.is_shell() {
+            *tool = rewrite.clone();
+            debug!(
+                stage = "tool_preprocessed",
+                location = ?hint.location,
+                "Preprocessed shell tool to function definition"
+            );
+        }
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[derive(Debug, Clone)]
+struct ShellToolCall {
+    id: String,
+    args: ResolvedShellArgs,
+}
+
+fn parse_shell_tool_call(value: &Value) -> Option<ShellToolCall> {
+    let obj = value.as_object()?;
+    if obj.get("type").and_then(|t| t.as_str())? != "function_call" {
+        return None;
+    }
+    if obj.get("name").and_then(|n| n.as_str())? != ShellToolArguments::FUNCTION_NAME {
+        return None;
+    }
+    let id = obj
+        .get("call_id")
+        .or_else(|| obj.get("id"))
+        .and_then(|v| v.as_str())
+        .unwrap_or("unknown")
+        .to_string();
+    let arguments_str = obj.get("arguments")?.as_str()?;
+    let args = ShellToolArguments::parse(arguments_str)?.resolve()?;
+    Some(ShellToolCall { id, args })
+}
+
+fn detect_shell_in_chunk(chunk: &[u8]) -> Vec<ShellToolCall> {
+    let Ok(chunk_str) = std::str::from_utf8(chunk) else {
+        return Vec::new();
+    };
+    let mut found = Vec::new();
+    for line in chunk_str.lines() {
+        let Some(data) = line.strip_prefix("data:") else {
+            continue;
+        };
+        let data = data.trim();
+        if data == "[DONE]" {
+            continue;
+        }
+        let Ok(json) = serde_json::from_str::<Value>(data) else {
+            continue;
+        };
+        // Same canonical detection as web_search: only emit on
+        // response.output_item.done to avoid duplicates.
+        if json.get("type").and_then(|t| t.as_str()) == Some("response.output_item.done")
+            && let Some(item) = json.get("item")
+            && let Some(tc) = parse_shell_tool_call(item)
+        {
+            found.push(tc);
+        }
+    }
+    found
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SSE event formatters
+// ─────────────────────────────────────────────────────────────────────────────
+
+fn sse_event(payload: Value) -> Bytes {
+    let s = serde_json::to_string(&payload).unwrap_or_default();
+    Bytes::from(format!("data: {}\n\n", s))
+}
+
+/// Item lifecycle stage. Drives the `response.output_item.<verb>` event
+/// type Hadrian emits and the corresponding `status` on the carried item.
+/// Spec lifecycle is `added → done`; SDK consumers hook the typed event
+/// stream off these names.
+#[derive(Debug, Clone, Copy)]
+enum ItemLifecycle {
+    Added,
+    Done,
+}
+
+impl ItemLifecycle {
+    fn event_type(self) -> &'static str {
+        match self {
+            ItemLifecycle::Added => "response.output_item.added",
+            ItemLifecycle::Done => "response.output_item.done",
+        }
+    }
+}
+
+/// Build the `shell_call` item JSON, shared between `output_item.added`
+/// (status `in_progress`) and `output_item.done` (status
+/// `completed` / `incomplete`). Per OpenAI's `FunctionShellCall` shape:
+/// `{id, call_id, action: {commands, timeout_ms?, max_output_length?},
+/// status, environment}`.
+#[allow(clippy::too_many_arguments)]
+fn build_shell_call_item(
+    item_id: &str,
+    call_id: &str,
+    commands: &[String],
+    timeout_ms: Option<u64>,
+    max_output_length: Option<usize>,
+    env: Option<&HashMap<String, String>>,
+    working_directory: Option<&str>,
+    status: &str,
+    environment: Option<&serde_json::Value>,
+    created_by: Option<&str>,
+) -> serde_json::Value {
+    let mut action = serde_json::json!({
+        "commands": commands,
+    });
+    if let Some(ms) = timeout_ms {
+        action["timeout_ms"] = serde_json::Value::from(ms);
+    }
+    if let Some(n) = max_output_length {
+        action["max_output_length"] = serde_json::Value::from(n);
+    }
+    if let Some(env) = env
+        && !env.is_empty()
+    {
+        action["env"] = serde_json::to_value(env).unwrap_or(serde_json::Value::Null);
+    }
+    if let Some(wd) = working_directory {
+        action["working_directory"] = serde_json::Value::from(wd);
+    }
+    let mut item = serde_json::json!({
+        "type": "shell_call",
+        "id": item_id,
+        "call_id": call_id,
+        "action": action,
+        "status": status,
+    });
+    if let Some(env_val) = environment {
+        item["environment"] = env_val.clone();
+    }
+    if let Some(c) = created_by {
+        item["created_by"] = serde_json::Value::from(c);
+    }
+    item
+}
+
+/// Emit a structured `response.output_item.<lifecycle>` event carrying
+/// a spec-compliant `shell_call` item.
+///
+/// Hadrian synthesizes both `added` (status `in_progress`) and `done`
+/// (terminal status) events so non-passthrough runtimes (`microsandbox`
+/// / `opensandbox`) match the wire contract OpenAI's hosted shell emits
+/// natively. For `passthrough_openai` the upstream already emits these
+/// items and we don't double-emit.
+#[allow(clippy::too_many_arguments)]
+fn format_shell_call_item(
+    lifecycle: ItemLifecycle,
+    item_id: &str,
+    call_id: &str,
+    output_index: usize,
+    commands: &[String],
+    timeout_ms: Option<u64>,
+    max_output_length: Option<usize>,
+    env: Option<&HashMap<String, String>>,
+    working_directory: Option<&str>,
+    status: &str,
+    environment: Option<&serde_json::Value>,
+    created_by: Option<&str>,
+) -> Bytes {
+    let item = build_shell_call_item(
+        item_id,
+        call_id,
+        commands,
+        timeout_ms,
+        max_output_length,
+        env,
+        working_directory,
+        status,
+        environment,
+        created_by,
+    );
+    sse_event(serde_json::json!({
+        "type": lifecycle.event_type(),
+        "output_index": output_index,
+        "item": item,
+    }))
+}
+
+/// Emit a structured `response.output_item.done` event carrying a
+/// spec-compliant `shell_call_output` item. Per OpenAI's
+/// `FunctionShellCallOutput` shape: `{id, call_id, status,
+/// output: [{stdout, stderr, outcome: {type: "exit"|"timeout", exit_code?}}],
+/// max_output_length?}`. The Hadrian-extension `output_files` array
+/// rides alongside.
+///
+/// The standard `function_call_output` continuation item still flows
+/// through `apply_to_continuation` for the model's next-turn input —
+/// this event is purely additive on the client-facing SSE stream.
+#[allow(clippy::too_many_arguments)]
+fn format_shell_call_output_item(
+    lifecycle: ItemLifecycle,
+    item_id: &str,
+    call_id: &str,
+    output_index: usize,
+    exit_code: i32,
+    stdout: &str,
+    stderr: &str,
+    files: &[ContainerFileRef],
+    killed: bool,
+    max_output_length: Option<usize>,
+    created_by: Option<&str>,
+) -> Bytes {
+    // `incomplete` whenever we never observed a normal exit — i.e. the
+    // call was killed by timeout or the runtime didn't report. Spec
+    // uses `incomplete` for "abandoned mid-flight" outcomes. The added
+    // lifecycle always carries `in_progress` per the spec.
+    let status_str = match lifecycle {
+        ItemLifecycle::Added => "in_progress",
+        ItemLifecycle::Done if killed => "incomplete",
+        ItemLifecycle::Done => "completed",
+    };
+    // Outcome discriminator: `timeout` for killed calls (we don't get
+    // a real exit code from the runtime), `exit` otherwise.
+    let outcome = if killed {
+        serde_json::json!({ "type": "timeout" })
+    } else {
+        serde_json::json!({ "type": "exit", "exit_code": exit_code })
+    };
+    let mut content = serde_json::json!({
+        "stdout": stdout,
+        "stderr": stderr,
+        "outcome": outcome,
+    });
+    if let Some(c) = created_by {
+        content["created_by"] = serde_json::Value::from(c);
+    }
+    let mut item = serde_json::json!({
+        "type": "shell_call_output",
+        "id": item_id,
+        "call_id": call_id,
+        "status": status_str,
+        "output": [content],
+        // Hadrian Extension: captured file manifest. Spec leaves the
+        // shell_call_output content array open for additive properties.
+        "output_files": files,
+    });
+    if let Some(n) = max_output_length {
+        item["max_output_length"] = serde_json::Value::from(n);
+    }
+    if let Some(c) = created_by {
+        item["created_by"] = serde_json::Value::from(c);
+    }
+    sse_event(serde_json::json!({
+        "type": lifecycle.event_type(),
+        "output_index": output_index,
+        "item": item,
+    }))
+}
+
+/// Emit the spec-canonical `output_item.done` events for both the
+/// `shell_call` and `shell_call_output` items when a shell call fails
+/// before producing real output (boot failure, passthrough misconfig,
+/// exec error). Both items carry `status: "incomplete"`; the output
+/// item's stderr surfaces the error message so the model can react.
+#[allow(clippy::too_many_arguments)]
+async fn emit_failure_done(
+    event_tx: &mpsc::Sender<Bytes>,
+    id: &str,
+    commands: &[String],
+    timeout_ms: Option<u64>,
+    max_output_length: Option<usize>,
+    env: Option<&HashMap<String, String>>,
+    working_directory: Option<&str>,
+    stderr: &str,
+) {
+    let _ = event_tx
+        .send(format_shell_call_item(
+            ItemLifecycle::Done,
+            id,
+            id,
+            0,
+            commands,
+            timeout_ms,
+            max_output_length,
+            env,
+            working_directory,
+            "incomplete",
+            None,
+            Some("model"),
+        ))
+        .await;
+    let _ = event_tx
+        .send(format_shell_call_output_item(
+            ItemLifecycle::Done,
+            id,
+            id,
+            0,
+            -1,
+            "",
+            stderr,
+            &[],
+            true,
+            max_output_length,
+            Some("gateway"),
+        ))
+        .await;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-call env / working_directory threading
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// POSIX-ish environment variable name check: starts with a letter or
+/// underscore, followed by letters, digits, or underscores. Rejects names
+/// that could break out of the synthesized `export` statement.
+fn is_valid_env_name(name: &str) -> bool {
+    let mut chars = name.chars();
+    match chars.next() {
+        Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
+        _ => return false,
+    }
+    chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
+}
+
+/// Single-quotes a string for safe inclusion in a POSIX shell command,
+/// escaping embedded single quotes (`'` → `'\''`).
+fn shell_single_quote(s: &str) -> String {
+    let mut out = String::with_capacity(s.len() + 2);
+    out.push('\'');
+    for c in s.chars() {
+        if c == '\'' {
+            out.push_str("'\\''");
+        } else {
+            out.push(c);
+        }
+    }
+    out.push('\'');
+    out
+}
+
+/// Builds the effective shell script honoring the model's per-call
+/// `working_directory` and `env`. Runtimes accept only a single command
+/// string and expose no separate cwd/env channel, so we prepend a
+/// validated, shell-escaped `cd`/`export` preamble to `command`. A
+/// missing working directory fails the call loudly (`|| exit 1`) rather
+/// than silently running in the default cwd. Returns `InvalidCall` for a
+/// malformed env name.
+fn build_effective_command(
+    command: &str,
+    env: Option<&HashMap<String, String>>,
+    working_directory: Option<&str>,
+) -> Result<String, ToolError> {
+    let mut preamble = String::new();
+    if let Some(wd) = working_directory.map(str::trim).filter(|s| !s.is_empty()) {
+        preamble.push_str(&format!("cd {} || exit 1\n", shell_single_quote(wd)));
+    }
+    if let Some(env) = env {
+        // Deterministic order so the synthesized script is stable.
+        let mut names: Vec<&String> = env.keys().collect();
+        names.sort();
+        for name in names {
+            if !is_valid_env_name(name) {
+                return Err(ToolError::InvalidCall(format!(
+                    "invalid environment variable name: {name}"
+                )));
+            }
+            preamble.push_str(&format!(
+                "export {}={}\n",
+                name,
+                shell_single_quote(&env[name])
+            ));
+        }
+    }
+    if preamble.is_empty() {
+        Ok(command.to_string())
+    } else {
+        Ok(format!("{preamble}{command}"))
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Output trimming for continuation payload
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Default operator cap for `[features.server_tools.shell_limits].max_output_chars`.
+/// Used as the fallback the `ShellToolHint::default()` description embeds; the
+/// configured value flows in via [`ShellExecutor`] at execute time.
+pub const DEFAULT_MAX_OUTPUT_CHARS: usize = 8_000;
+
+/// Streaming UTF-8 decoder that buffers bytes split across chunk
+/// boundaries instead of emitting a `U+FFFD` per partial sequence.
+/// Callers feed in raw stdout/stderr bytes via [`Self::push`] and read
+/// out fully-decoded strings; whatever's left over (≤ 3 trailing bytes
+/// of an incomplete code point) is carried into the next call.
+struct Utf8ChunkDecoder {
+    /// Bytes that belong to an in-progress UTF-8 sequence at the tail
+    /// of the previous push. Always < 4 bytes.
+    leftover: Vec<u8>,
+}
+
+impl Utf8ChunkDecoder {
+    fn new() -> Self {
+        Self {
+            leftover: Vec::with_capacity(4),
+        }
+    }
+
+    /// Append `bytes` to the pending buffer and return everything we
+    /// can prove is a complete UTF-8 sequence. Invalid sequences are
+    /// turned into replacement chars (consistent with
+    /// `String::from_utf8_lossy`); the very last possibly-partial
+    /// sequence is held back for the next call.
+    fn push(&mut self, bytes: &[u8]) -> String {
+        if bytes.is_empty() && self.leftover.is_empty() {
+            return String::new();
+        }
+        let combined: Vec<u8> = if self.leftover.is_empty() {
+            bytes.to_vec()
+        } else {
+            let mut v = std::mem::take(&mut self.leftover);
+            v.extend_from_slice(bytes);
+            v
+        };
+
+        // Find the largest prefix of `combined` that's complete. A
+        // trailing UTF-8 sequence is incomplete if its leading byte
+        // promises more continuation bytes than we've seen.
+        let mut boundary = combined.len();
+        let max_lookback = boundary.min(3);
+        for back in 1..=max_lookback {
+            let i = boundary - back;
+            let b = combined[i];
+            if b < 0x80 {
+                break; // ASCII — nothing partial above this
+            }
+            // Continuation byte (10xxxxxx): keep scanning back.
+            if b & 0b1100_0000 == 0b1000_0000 {
+                continue;
+            }
+            // Leading byte: figure out how many bytes the sequence
+            // should occupy and see whether we have them all.
+            let needed = if b & 0b1110_0000 == 0b1100_0000 {
+                2
+            } else if b & 0b1111_0000 == 0b1110_0000 {
+                3
+            } else if b & 0b1111_1000 == 0b1111_0000 {
+                4
+            } else {
+                // Invalid leading byte — let the lossy decoder mark
+                // it `U+FFFD` rather than holding back forever.
+                break;
+            };
+            if combined.len() - i < needed {
+                boundary = i;
+            }
+            break;
+        }
+
+        self.leftover.clear();
+        if boundary < combined.len() {
+            self.leftover.extend_from_slice(&combined[boundary..]);
+        }
+        String::from_utf8_lossy(&combined[..boundary]).into_owned()
+    }
+
+    /// Flush whatever's left, treating any straggling partial sequence
+    /// as malformed (renders as `U+FFFD`).
+    fn flush(&mut self) -> String {
+        if self.leftover.is_empty() {
+            return String::new();
+        }
+        let s = String::from_utf8_lossy(&self.leftover).into_owned();
+        self.leftover.clear();
+        s
+    }
+}
+
+/// Bounded buffer that head + tail trims as bytes arrive so a runaway
+/// stdout doesn't pin gigabytes of memory before the post-exec trim
+/// runs. Total visible characters are capped at `max_chars`: the first
+/// `max_chars / 2` chars land in `head`, the last `max_chars / 2` chars
+/// in a rotating `tail` ring, and everything in between is counted but
+/// discarded.
+///
+/// Final rendering via [`Self::into_trimmed`] emits `head` + a
+/// `... N chars truncated ...` marker + `tail` when the stream
+/// overflowed `max_chars`; otherwise the captured prefix is returned
+/// verbatim. Matches the contract the function-mode shell tool
+/// description embeds ("truncated past {N} chars").
+struct BoundedHeadTail {
+    head: String,
+    head_chars: usize,
+    /// Ring of the most recent tail chars sized at `half`. Below the
+    /// head fill we accumulate into `head` only.
+    tail: std::collections::VecDeque<char>,
+    /// Total chars seen (used to compute the truncation count and
+    /// avoid mixing bytes and chars).
+    total_chars: usize,
+    /// Per-side cap. Head takes the first `half` chars, tail rotates
+    /// the most recent `half` chars after that.
+    half: usize,
+    max_chars: usize,
+}
+
+impl BoundedHeadTail {
+    fn new(max_chars: usize) -> Self {
+        let half = max_chars / 2;
+        Self {
+            head: String::with_capacity(half.min(8 * 1024)),
+            head_chars: 0,
+            tail: std::collections::VecDeque::new(),
+            total_chars: 0,
+            half,
+            max_chars,
+        }
+    }
+
+    fn push_str(&mut self, s: &str) {
+        for c in s.chars() {
+            self.total_chars += 1;
+            if self.head_chars < self.half {
+                self.head.push(c);
+                self.head_chars += 1;
+                continue;
+            }
+            // Past the head fill: rotate into a `half`-sized ring.
+            if self.tail.len() == self.half {
+                self.tail.pop_front();
+            }
+            self.tail.push_back(c);
+        }
+    }
+
+    fn into_trimmed(self) -> String {
+        if self.total_chars <= self.max_chars {
+            // Head + tail combined still fit under the cap; just glue
+            // them (no truncation marker).
+            let head = self.head;
+            let tail: String = self.tail.into_iter().collect();
+            return format!("{head}{tail}");
+        }
+        let head = self.head;
+        let tail: String = self.tail.into_iter().collect();
+        let dropped = self.total_chars - self.max_chars;
+        format!("{head}\n... [{dropped} chars truncated] ...\n{tail}")
+    }
+
+    /// True when the stream exceeded `max_chars` and the rendered
+    /// output had to insert a truncation marker.
+    fn was_truncated(&self) -> bool {
+        self.total_chars > self.max_chars
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ShellExecutor
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// `ServerExecutedTool` implementation that runs shell commands against
+/// any [`ShellRuntime`] whose `capabilities().passthrough_only` is
+/// false.
+///
+/// **Not registered for passthrough runtimes** — the orchestrator
+/// inspects the runtime's capabilities and skips registration entirely
+/// when passthrough is in effect.
+///
+/// Each `ShellExecutor` is request-scoped (created by
+/// `apply_streaming_pipeline` per Responses-API request) and owns one
+/// lazily-started [`ContainerSession`] that all shell tool calls
+/// within that request share. The session — and its underlying
+/// sandbox VM — lives until the `ShellExecutor` is dropped at
+/// stream-end, at which point [`ContainerSession::drop`] detaches a
+/// terminate task. Files written to `/mnt/data` along the way are
+/// captured into `captured_files` and replayed as
+/// `container_file_citation` annotations on the assistant's reply.
+pub struct ShellExecutor {
+    runtime: Arc<dyn ShellRuntime>,
+    /// Cost per second of runtime time, in microcents. Multiplied by
+    /// the wall-clock duration of each shell call to compute the
+    /// chargeable cost emitted to metrics and the usage record.
+    cost_microcents_per_second: u64,
+    /// Label used for the runtime axis of cost metrics
+    /// (e.g. `"microsandbox"`, `"passthrough_openai"`).
+    runtime_label: &'static str,
+    /// Identity context attached to the per-shell-call usage record so
+    /// runtime time is attributed to the right principal.
+    principal: ShellPrincipal,
+    /// Skill bundles to mount into the session started by this
+    /// executor. Resolved upstream from the request's `skills` field;
+    /// empty when the request didn't ask for any. Cloned into the
+    /// `SessionSpec` on first `execute()` call.
+    mounted_skills: Vec<SkillMount>,
+    /// Per-execution limits (timeouts, default CPU/mem). Loaded from
+    /// `[features.server_tools].shell_limits`.
+    limits: crate::config::ShellLimitsConfig,
+    /// Per-request `environment` overrides, already intersected with
+    /// `limits` at request-acceptance time. Drives memory and egress
+    /// on the `SessionSpec` we hand the runtime.
+    resolved_env: ResolvedShellEnvironment,
+    /// Container / artifact-capture settings.
+    containers_config: ContainersConfig,
+    /// Per-executor cache of the resolved registry entry. `None`
+    /// until the first `execute()` call. Once populated, every
+    /// subsequent call in this response goes straight to the cached
+    /// `Arc<Mutex<ContainerSession>>` without touching the registry.
+    session_handle: Arc<Mutex<Option<Arc<Mutex<ContainerSession>>>>>,
+    /// Process-wide registry of live container sessions. Used to
+    /// share one VM across responses that target the same
+    /// `container_id` (e.g. chained via `previous_response_id`).
+    registry: Arc<ContainerSessionRegistry>,
+    /// Pre-allocated container id from the pipeline. When `Some`, the
+    /// executor checks the registry for an existing session and
+    /// reattaches (or creates) under this id; when `None`, it
+    /// generates a fresh id on first use (in-memory-only deployments).
+    container_id_hint: Option<String>,
+    /// Files captured across every shell call in this response,
+    /// keyed by path so an overwrite replaces the prior entry. Read
+    /// synchronously by `transform_event` to populate
+    /// `container_file_citation` annotations on output_text events.
+    captured_files: Arc<std::sync::Mutex<HashMap<String, ContainerFileRef>>>,
+    /// Hides the rewritten `shell` function-call plumbing from the
+    /// client stream; the executor emits the spec-shaped `shell_call` /
+    /// `shell_call_output` items itself.
+    suppressor: crate::services::server_tools::FunctionCallSuppressor,
+    /// `input_file` parts the request asked us to stage into
+    /// `/mnt/data` before the first shell command. Drained on the
+    /// first `execute()` call; subsequent calls see `None`.
+    pending_input_files: Arc<Mutex<Option<Vec<StagedFile>>>>,
+    /// Optional database write-through. When `Some`, a `containers`
+    /// row is inserted on session start and every captured file is
+    /// upserted into `container_files`; when `None`, the session
+    /// runs entirely in-memory.
+    persistence: Option<ContainerPersistence>,
+    /// Usage log buffer. When set, the executor pushes a `record_type:
+    /// "tool"` entry per completed call with `tool_runtime_seconds` set.
+    #[cfg(feature = "concurrency")]
+    usage_buffer: Option<Arc<crate::usage_buffer::UsageLogBuffer>>,
+}
+
+impl ShellExecutor {
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        runtime: Arc<dyn ShellRuntime>,
+        cost_microcents_per_second: u64,
+        runtime_label: &'static str,
+        principal: ShellPrincipal,
+        mounted_skills: Vec<SkillMount>,
+        limits: crate::config::ShellLimitsConfig,
+        resolved_env: ResolvedShellEnvironment,
+        containers_config: ContainersConfig,
+        staged_input_files: Vec<StagedFile>,
+        persistence: Option<ContainerPersistence>,
+        registry: Arc<ContainerSessionRegistry>,
+        container_id_hint: Option<String>,
+        #[cfg(feature = "concurrency")] usage_buffer: Option<
+            Arc<crate::usage_buffer::UsageLogBuffer>,
+        >,
+    ) -> Self {
+        let pending = if staged_input_files.is_empty() {
+            None
+        } else {
+            Some(staged_input_files)
+        };
+        Self {
+            runtime,
+            cost_microcents_per_second,
+            runtime_label,
+            principal,
+            mounted_skills,
+            limits,
+            resolved_env,
+            containers_config,
+            session_handle: Arc::new(Mutex::new(None)),
+            registry,
+            container_id_hint,
+            captured_files: Arc::new(std::sync::Mutex::new(HashMap::new())),
+            suppressor: crate::services::server_tools::FunctionCallSuppressor::new(),
+            pending_input_files: Arc::new(Mutex::new(pending)),
+            persistence,
+            #[cfg(feature = "concurrency")]
+            usage_buffer,
+        }
+    }
+}
+
+#[async_trait::async_trait]
+impl ServerExecutedTool for ShellExecutor {
+    fn name(&self) -> &'static str {
+        ShellToolArguments::FUNCTION_NAME
+    }
+
+    fn is_enabled_for(&self, payload: &CreateResponsesPayload) -> bool {
+        // We only engage if there's a shell tool — or a function tool
+        // already preprocessed from a shell tool — in the request.
+        payload
+            .tools
+            .as_ref()
+            .map(|tools| {
+                tools.iter().any(|t| {
+                    t.is_shell()
+                        || matches!(
+                            t,
+                            ResponsesToolDefinition::Function(f)
+                                if f.name == ShellToolArguments::FUNCTION_NAME
+                        )
+                })
+            })
+            .unwrap_or(false)
+    }
+
+    fn detect(&self, event: &[u8], _ctx: &ToolContext) -> Vec<DetectedToolCall> {
+        detect_shell_in_chunk(event)
+            .into_iter()
+            .map(|tc| DetectedToolCall {
+                tool_name: ShellToolArguments::FUNCTION_NAME,
+                call_id: tc.id.clone(),
+                arguments: serde_json::json!({
+                    "id": tc.id,
+                    "commands": tc.args.commands,
+                    "stdin": tc.args.stdin,
+                    "timeout_ms": tc.args.timeout_ms,
+                    "max_output_length": tc.args.max_output_length,
+                    "env": tc.args.env,
+                    "working_directory": tc.args.working_directory,
+                }),
+            })
+            .collect()
+    }
+
+    async fn execute(
+        &self,
+        call: DetectedToolCall,
+        _ctx: &ToolContext,
+    ) -> Result<ToolExecutionHandle, ToolError> {
+        let commands: Vec<String> = call
+            .arguments
+            .get("commands")
+            .and_then(|v| v.as_array())
+            .map(|a| {
+                a.iter()
+                    .filter_map(|v| v.as_str())
+                    .map(|s| s.trim().to_string())
+                    .filter(|s| !s.is_empty())
+                    .collect()
+            })
+            .unwrap_or_default();
+        // Joined script — runtimes only accept a single string today,
+        // so multi-command actions are concatenated and run as a shell
+        // script. Final exit code is the script's.
+        let command = commands.join("\n");
+        let stdin = call
+            .arguments
+            .get("stdin")
+            .and_then(|v| v.as_str())
+            .map(|s| Bytes::from(s.to_string()));
+        let model_timeout_ms = call.arguments.get("timeout_ms").and_then(|v| v.as_u64());
+        let model_max_output_length = call
+            .arguments
+            .get("max_output_length")
+            .and_then(|v| v.as_u64())
+            .and_then(|n| usize::try_from(n).ok());
+        let model_env: Option<HashMap<String, String>> = call
+            .arguments
+            .get("env")
+            .and_then(|v| serde_json::from_value(v.clone()).ok());
+        let model_workdir = call
+            .arguments
+            .get("working_directory")
+            .and_then(|v| v.as_str())
+            .map(str::to_string);
+        // Honor the model's per-call working_directory/env by synthesizing a
+        // validated `cd`/`export` preamble — runtimes accept only a single
+        // command string with no separate cwd/env channel. The echoed
+        // shell_call item still reports the raw `model_env`/`model_workdir`.
+        let command =
+            build_effective_command(&command, model_env.as_ref(), model_workdir.as_deref())?;
+        let id = call.call_id.clone();
+        let runtime = self.runtime.clone();
+        let cost_per_sec = self.cost_microcents_per_second;
+        let runtime_label = self.runtime_label;
+        let principal = self.principal.clone();
+        let mounted_skills = self.mounted_skills.clone();
+        let containers_config = self.containers_config.clone();
+        let session_handle_slot = self.session_handle.clone();
+        let registry = self.registry.clone();
+        let container_id_hint = self.container_id_hint.clone();
+        let captured_files = self.captured_files.clone();
+        let pending_input_files = self.pending_input_files.clone();
+        let persistence = self.persistence.clone();
+        #[cfg(feature = "concurrency")]
+        let usage_buffer = self.usage_buffer.clone();
+
+        let (event_tx, event_rx) = mpsc::channel::<Bytes>(32);
+        let (result_tx, result_rx) =
+            tokio::sync::oneshot::channel::<Result<ToolCallResult, ToolError>>();
+
+        // Emit the spec-canonical `output_item.added` lifecycle events
+        // for the `shell_call` and (placeholder) `shell_call_output`
+        // items before any I/O. SDKs typed against the Responses API
+        // stream pick the items up here; the matching `output_item.done`
+        // events fire from the exec-complete branch below with the
+        // final status and content.
+        //
+        // `environment` is omitted on the `added` event because the
+        // resolved container_id isn't known until boot completes; the
+        // `done` event carries it.
+        let added_shell_call = format_shell_call_item(
+            ItemLifecycle::Added,
+            &id,
+            &id,
+            0,
+            &commands,
+            model_timeout_ms,
+            model_max_output_length,
+            model_env.as_ref(),
+            model_workdir.as_deref(),
+            "in_progress",
+            None,
+            Some("model"),
+        );
+        let _ = event_tx.send(added_shell_call).await;
+        let added_shell_output = format_shell_call_output_item(
+            ItemLifecycle::Added,
+            &id,
+            &id,
+            0,
+            0,
+            "",
+            "",
+            &[],
+            false,
+            model_max_output_length,
+            Some("gateway"),
+        );
+        let _ = event_tx.send(added_shell_output).await;
+
+        // Spawn the actual session work so the orchestrator can start
+        // consuming events while we boot the container.
+        let id_for_task = id.clone();
+        let command_for_task = command.clone();
+        let commands_for_task = commands.clone();
+        let working_directory_for_task = model_workdir.clone();
+        // Capture model-side action fields so we can emit a spec-shaped
+        // `shell_call` item after exec completes (`action.timeout_ms`,
+        // `action.env`, `action.max_output_length`).
+        let action_timeout_ms_for_task = model_timeout_ms;
+        let action_env_for_task = model_env.clone();
+        // Apply the model's per-call timeout when given; clamp to the
+        // operator cap. `timeout_ms < 1000` rounds up to one second.
+        let op_timeout_ms = self
+            .limits
+            .command_timeout_secs
+            .saturating_mul(1000)
+            .max(1000);
+        let effective_timeout_ms = match model_timeout_ms {
+            Some(ms) if ms > 0 => ms.min(op_timeout_ms),
+            _ => op_timeout_ms,
+        };
+        let exec_timeout = Duration::from_millis(effective_timeout_ms.max(1));
+        let default_cpu = self.limits.default_cpu_limit;
+        // Per-call cap on stdout+stderr fed back to the model. Clamped
+        // to the operator's `max_output_chars` cap.
+        let op_max_chars = self.limits.max_output_chars.max(64);
+        let max_output_chars = match model_max_output_length {
+            Some(n) if n > 0 => n.min(op_max_chars).max(64),
+            _ => op_max_chars,
+        };
+        // Per-request override (already intersected with operator's
+        // limits at request-acceptance time) wins; fall back to the
+        // operator default. `egress_policy` is taken from the resolved
+        // env verbatim — an empty `allow_hosts` means inherit runtime
+        // default, which `SessionSpec`'s default already encodes.
+        let resolved_env = self.resolved_env.clone();
+        crate::compat::spawn_detached(async move {
+            let start = Instant::now();
+
+            // Resolve the registry entry. On the first execute() call
+            // for this executor we either grab an existing shared
+            // session (chained `previous_response_id`) or boot a new
+            // VM and register it. Subsequent calls within this
+            // response read the cached `Arc<Mutex<ContainerSession>>`
+            // without touching the registry.
+            //
+            // When `container_id_hint` is set, the get-or-insert path
+            // is atomic via `ContainerSessionRegistry::get_or_try_insert_with`
+            // so two concurrent requests racing on the same hint boot
+            // exactly one VM rather than booting two and terminating
+            // the loser mid-exec.
+            let session_arc: Arc<Mutex<ContainerSession>> = {
+                let mut handle_slot = session_handle_slot.lock().await;
+                if let Some(existing) = handle_slot.as_ref() {
+                    existing.clone()
+                } else {
+                    let spec_template = || SessionSpec {
+                        mounted_skills: mounted_skills.clone(),
+                        cpu_limit: default_cpu,
+                        mem_limit_bytes: resolved_env.mem_limit_bytes,
+                        egress_policy: resolved_env.egress_policy.clone(),
+                        ..SessionSpec::default()
+                    };
+
+                    // Async boot helper kept inline so it can close
+                    // over `runtime`, `containers_config`, etc.
+                    let runtime_for_boot = runtime.clone();
+                    let runtime_label_for_boot = runtime_label;
+                    let containers_config_for_boot = containers_config.clone();
+                    let persistence_for_boot = persistence.clone();
+                    let hint_for_boot = container_id_hint.clone();
+
+                    let idle_ttl_override = resolved_env.idle_ttl_secs;
+                    let boot_session = move || async move {
+                        let spec = spec_template();
+                        match (hint_for_boot, persistence_for_boot.clone()) {
+                            (Some(cid), Some(p)) => {
+                                ContainerSession::start_attached(
+                                    cid,
+                                    runtime_for_boot,
+                                    runtime_label_for_boot,
+                                    spec,
+                                    containers_config_for_boot,
+                                    p,
+                                    idle_ttl_override,
+                                )
+                                .await
+                            }
+                            _ => {
+                                ContainerSession::start_new(
+                                    runtime_for_boot,
+                                    runtime_label_for_boot,
+                                    spec,
+                                    containers_config_for_boot,
+                                    persistence_for_boot,
+                                    idle_ttl_override,
+                                )
+                                .await
+                            }
+                        }
+                    };
+
+                    let resolved: Arc<Mutex<ContainerSession>> = match container_id_hint.as_deref()
+                    {
+                        Some(hint) => {
+                            // Atomic get-or-create under the hint id.
+                            // The registry's CAS guarantees at most one
+                            // VM gets booted across racing requests.
+                            match registry
+                                .get_or_try_insert_with(hint.to_string(), boot_session)
+                                .await
+                            {
+                                Ok((arc, inserted)) => {
+                                    debug!(
+                                        stage = "container_session_resolved",
+                                        call_id = %id_for_task,
+                                        container_id = %hint,
+                                        booted = inserted,
+                                        "Resolved container session via registry CAS"
+                                    );
+                                    arc
+                                }
+                                Err(RuntimeError::Passthrough) => {
+                                    warn!(
+                                        stage = "passthrough_invoked",
+                                        call_id = %id_for_task,
+                                        "Passthrough runtime received an execute() call; \
+                                         this indicates a misconfiguration in chat.rs registration"
+                                    );
+                                    emit_failure_done(
+                                        &event_tx,
+                                        &id_for_task,
+                                        &commands_for_task,
+                                        action_timeout_ms_for_task,
+                                        model_max_output_length,
+                                        action_env_for_task.as_ref(),
+                                        working_directory_for_task.as_deref(),
+                                        "shell runtime is configured for passthrough but \
+                                         executor was invoked",
+                                    )
+                                    .await;
+                                    let _ = result_tx.send(Err(ToolError::ExecutionFailed(
+                                        "shell runtime is configured for passthrough but \
+                                         executor was invoked"
+                                            .into(),
+                                    )));
+                                    return;
+                                }
+                                Err(e) => {
+                                    error!(
+                                        stage = "session_start_failed",
+                                        call_id = %id_for_task,
+                                        error = %e,
+                                        "Failed to start shell session"
+                                    );
+                                    let err_text = e.to_string();
+                                    emit_failure_done(
+                                        &event_tx,
+                                        &id_for_task,
+                                        &commands_for_task,
+                                        action_timeout_ms_for_task,
+                                        model_max_output_length,
+                                        action_env_for_task.as_ref(),
+                                        working_directory_for_task.as_deref(),
+                                        &err_text,
+                                    )
+                                    .await;
+                                    let _ =
+                                        result_tx.send(Err(ToolError::ExecutionFailed(err_text)));
+                                    return;
+                                }
+                            }
+                        }
+                        None => {
+                            // No hint: each request boots its own
+                            // fresh container. We still register so
+                            // subsequent chains can reattach.
+                            let session = match boot_session().await {
+                                Ok(s) => {
+                                    debug!(
+                                        stage = "container_session_started",
+                                        call_id = %id_for_task,
+                                        container_id = %s.container_id,
+                                        file_io = s.file_io_enabled(),
+                                        "Started persistent container session"
+                                    );
+                                    s
+                                }
+                                Err(RuntimeError::Passthrough) => {
+                                    warn!(
+                                        stage = "passthrough_invoked",
+                                        call_id = %id_for_task,
+                                        "Passthrough runtime received an execute() call; \
+                                         this indicates a misconfiguration in chat.rs registration"
+                                    );
+                                    emit_failure_done(
+                                        &event_tx,
+                                        &id_for_task,
+                                        &commands_for_task,
+                                        action_timeout_ms_for_task,
+                                        model_max_output_length,
+                                        action_env_for_task.as_ref(),
+                                        working_directory_for_task.as_deref(),
+                                        "shell runtime is configured for passthrough but \
+                                         executor was invoked",
+                                    )
+                                    .await;
+                                    let _ = result_tx.send(Err(ToolError::ExecutionFailed(
+                                        "shell runtime is configured for passthrough but \
+                                         executor was invoked"
+                                            .into(),
+                                    )));
+                                    return;
+                                }
+                                Err(e) => {
+                                    error!(
+                                        stage = "session_start_failed",
+                                        call_id = %id_for_task,
+                                        error = %e,
+                                        "Failed to start shell session"
+                                    );
+                                    let err_text = e.to_string();
+                                    emit_failure_done(
+                                        &event_tx,
+                                        &id_for_task,
+                                        &commands_for_task,
+                                        action_timeout_ms_for_task,
+                                        model_max_output_length,
+                                        action_env_for_task.as_ref(),
+                                        working_directory_for_task.as_deref(),
+                                        &err_text,
+                                    )
+                                    .await;
+                                    let _ =
+                                        result_tx.send(Err(ToolError::ExecutionFailed(err_text)));
+                                    return;
+                                }
+                            };
+                            let cid = session.container_id.clone();
+                            let (arc, _displaced) = registry.insert(cid, session);
+                            // No `container_id_hint` ⇒ the id we just
+                            // picked is fresh, so a `displaced` here
+                            // would only happen against an unrelated
+                            // session under the same brand-new UUID —
+                            // statistically impossible (32 hex chars).
+                            arc
+                        }
+                    };
+                    *handle_slot = Some(resolved.clone());
+                    resolved
+                }
+            };
+
+            // Hold the per-session lock for the duration of:
+            // input-file staging → exec → capture. Concurrent shell
+            // calls (within this response OR across responses sharing
+            // the container) queue behind this; one VM, one in-flight
+            // command.
+            let session_guard = session_arc.lock().await;
+            let session: &ContainerSession = &session_guard;
+            // Snapshot the container_id now so we can build the
+            // `shell_call.environment.container_reference` after exec
+            // completes — by then `session_guard` has been dropped.
+            let container_id_for_items = session.container_id.clone();
+
+            // Drain any `input_file` parts the pipeline staged for us
+            // and write them into /mnt/data before the model's command
+            // runs. Only fires on the first execute() call per
+            // executor; subsequent calls see `None`.
+            let pending = {
+                let mut p = pending_input_files.lock().await;
+                p.take()
+            };
+            if let Some(files) = pending {
+                let file_count = files.len();
+                match session.ingest_user_files(files).await {
+                    Ok(refs) => {
+                        if !refs.is_empty() {
+                            debug!(
+                                stage = "input_files_staged",
+                                call_id = %id_for_task,
+                                count = refs.len(),
+                                "Staged input_file parts into /mnt/data"
+                            );
+                        }
+                        // Mirror into captured_files so the very first
+                        // assistant message picks them up in
+                        // annotations, even if the shell command
+                        // itself produces no further output.
+                        // Poison recovery: see `transform_event`; the
+                        // map contents are still consistent after a
+                        // panic in another holder.
+                        let mut guard = match captured_files.lock() {
+                            Ok(g) => g,
+                            Err(poisoned) => poisoned.into_inner(),
+                        };
+                        for r in refs {
+                            guard.insert(r.path.clone(), r);
+                        }
+                    }
+                    Err(e) => {
+                        warn!(
+                            stage = "input_files_staging_failed",
+                            call_id = %id_for_task,
+                            count = file_count,
+                            error = %e,
+                            "Failed to stage one or more input_file parts; \
+                             continuing with the shell command anyway"
+                        );
+                    }
+                }
+            }
+
+            let exec = match session
+                .exec(ExecRequest {
+                    command: command_for_task.clone(),
+                    stdin,
+                    timeout: Some(exec_timeout),
+                })
+                .await
+            {
+                Ok(e) => e,
+                Err(e) => {
+                    error!(
+                        stage = "exec_failed",
+                        call_id = %id_for_task,
+                        error = %e,
+                        "Failed to exec shell command"
+                    );
+                    let _ = start.elapsed();
+                    let err_text = e.to_string();
+                    emit_failure_done(
+                        &event_tx,
+                        &id_for_task,
+                        &commands_for_task,
+                        action_timeout_ms_for_task,
+                        model_max_output_length,
+                        action_env_for_task.as_ref(),
+                        working_directory_for_task.as_deref(),
+                        &err_text,
+                    )
+                    .await;
+                    let _ = result_tx.send(Err(ToolError::ExecutionFailed(err_text)));
+                    return;
+                }
+            };
+
+            // Stream output, accumulating for the continuation payload.
+            // We race two futures:
+            //   - `output.next()`: the next ExecEvent from the runtime.
+            //   - `event_tx.closed()`: resolves when the orchestrator has
+            //     dropped its receiver, which happens when the HTTP
+            //     client disconnects upstream.
+            //
+            // This catches disconnect even for commands that produce no
+            // output, which the previous send-error-only check missed.
+            //
+            // Output handling: we feed bytes through a `Utf8ChunkDecoder`
+            // so multi-byte sequences split across stdout chunks don't
+            // emit a `U+FFFD` per chunk boundary, and into a
+            // `BoundedHeadTail` so an `echo "$(head -c 1G /dev/urandom)"`
+            // can't pin gigabytes of memory before the post-exec trim
+            // runs. The SSE chunk is still emitted from the original
+            // bytes so observers downstream see the raw stream.
+            let max_chars = max_output_chars;
+            let mut stdout_decoder = Utf8ChunkDecoder::new();
+            let mut stderr_decoder = Utf8ChunkDecoder::new();
+            let mut stdout_buf = BoundedHeadTail::new(max_chars);
+            let mut stderr_buf = BoundedHeadTail::new(max_chars);
+            let mut final_exit: Option<i32> = None;
+            let mut output = exec.handle.output;
+            let mut client_disconnected = false;
+            loop {
+                tokio::select! {
+                    _ = event_tx.closed() => {
+                        warn!(
+                            stage = "client_disconnected",
+                            call_id = %id_for_task,
+                            "Client disconnected (channel closed); terminating session"
+                        );
+                        client_disconnected = true;
+                        break;
+                    }
+                    maybe_ev = output.next() => {
+                        let Some(ev) = maybe_ev else { break };
+                        // OpenAI's Responses API spec has no per-delta
+                        // streaming event for `shell_call`; stdout/stderr
+                        // surface in a single `shell_call_output` item via
+                        // `response.output_item.done` after exec. We
+                        // accumulate into bounded head/tail buffers here
+                        // and rely on the `event_tx.closed()` arm above
+                        // for client-disconnect detection.
+                        match ev {
+                            ExecEvent::Stdout(bytes) => {
+                                let decoded = stdout_decoder.push(&bytes);
+                                if !decoded.is_empty() {
+                                    stdout_buf.push_str(&decoded);
+                                }
+                            }
+                            ExecEvent::Stderr(bytes) => {
+                                let decoded = stderr_decoder.push(&bytes);
+                                if !decoded.is_empty() {
+                                    stderr_buf.push_str(&decoded);
+                                }
+                            }
+                            ExecEvent::Exit { code, .. } => {
+                                final_exit = Some(code);
+                            }
+                        }
+                    }
+                }
+            }
+            // Flush any straggling bytes from a multi-byte sequence
+            // that wasn't completed before the runtime closed the stream.
+            let stdout_tail = stdout_decoder.flush();
+            if !stdout_tail.is_empty() {
+                stdout_buf.push_str(&stdout_tail);
+            }
+            let stderr_tail = stderr_decoder.flush();
+            if !stderr_tail.is_empty() {
+                stderr_buf.push_str(&stderr_tail);
+            }
+
+            // Snapshot /mnt/data to detect any files the command
+            // produced. Only runs when the runtime supports file_io
+            // and the operator hasn't disabled the feature. Errors
+            // are surfaced as warnings — they don't fail the shell
+            // call, since the command itself already ran.
+            let mut new_files: Vec<ContainerFileRef> = Vec::new();
+            if !client_disconnected {
+                match session.capture_changes().await {
+                    Ok(refs) => new_files = refs,
+                    Err(e) => warn!(
+                        stage = "capture_failed",
+                        call_id = %id_for_task,
+                        error = %e,
+                        "Failed to snapshot /mnt/data after exec"
+                    ),
+                }
+                let _ = &new_files;
+            }
+
+            // Replace the global captured_files map for this response
+            // with the session's full tracked set (handles overwrites
+            // and deletions consistently with what the model sees).
+            let all_tracked = session.list_captured().await;
+            {
+                let mut guard = match captured_files.lock() {
+                    Ok(g) => g,
+                    Err(poisoned) => poisoned.into_inner(),
+                };
+                guard.clear();
+                for r in all_tracked {
+                    guard.insert(r.path.clone(), r);
+                }
+            }
+
+            // Release the session lock before the cost-accounting and
+            // continuation-build work — those don't need the VM.
+            drop(session_guard);
+
+            let duration_secs = start.elapsed().as_secs_f64();
+
+            // Cost is billable regardless of how the session ended — we
+            // ran the VM, the operator pays for the time.
+            let cost_microcents = (duration_secs * cost_per_sec as f64).round() as i64;
+
+            // Push the per-principal usage record. We do this on every
+            // exit path (completion + disconnect) so the principal is
+            // billed for what they consumed.
+            // Resolve the exit code for downstream reporting. `final_exit
+            // == None` means the runtime stream closed without an `Exit`
+            // event — surface that as `-1` to metrics (the sentinel
+            // `record_shell_execution` uses for error exits) but preserve
+            // `None` on the usage row so a later audit can tell "process
+            // exited 0" from "process never reported an exit." Clients
+            // see this case as `status: "incomplete"` with a `timeout`
+            // outcome on the `shell_call_output` item.
+            let exit_for_report = final_exit.unwrap_or(-1);
+
+            #[cfg(feature = "concurrency")]
+            if let Some(ref buf) = usage_buffer {
+                buf.push(UsageLogEntry {
+                    request_id: Uuid::new_v4().to_string(),
+                    api_key_id: principal.api_key_id,
+                    user_id: principal.user_id,
+                    org_id: principal.org_id,
+                    project_id: principal.project_id,
+                    team_id: principal.team_id,
+                    service_account_id: principal.service_account_id,
+                    model: "shell".to_string(),
+                    provider: runtime_label.to_string(),
+                    http_referer: None,
+                    input_tokens: 0,
+                    output_tokens: 0,
+                    cost_microcents: Some(cost_microcents),
+                    request_at: Utc::now(),
+                    streamed: true,
+                    cached_tokens: 0,
+                    reasoning_tokens: 0,
+                    finish_reason: Some(
+                        match (client_disconnected, final_exit) {
+                            (true, _) => "client_disconnected",
+                            (false, None) => "no_exit_event",
+                            (false, Some(_)) => "completed",
+                        }
+                        .to_string(),
+                    ),
+                    latency_ms: Some((duration_secs * 1000.0) as i32),
+                    cancelled: client_disconnected,
+                    status_code: Some(200),
+                    pricing_source: CostPricingSource::PricingConfig,
+                    image_count: None,
+                    audio_seconds: None,
+                    character_count: None,
+                    provider_source: None,
+                    record_type: "tool".to_string(),
+                    tool_name: Some("shell".to_string()),
+                    tool_query: Some(command_for_task.clone()),
+                    tool_url: None,
+                    tool_bytes_fetched: None,
+                    tool_results_count: None,
+                    tool_runtime_seconds: Some(duration_secs),
+                    tool_exit_code: final_exit,
+                });
+            }
+            #[cfg(not(feature = "concurrency"))]
+            let _ = (&principal, command_for_task.clone());
+
+            if client_disconnected {
+                crate::observability::metrics::record_shell_execution(
+                    duration_secs,
+                    exit_for_report,
+                    "client_disconnected",
+                    runtime_label,
+                    cost_microcents,
+                );
+                // Drop both channels without sending — the orchestrator
+                // is gone, no one is listening.
+                return;
+            }
+
+            // `killed` ≈ runtime returned the timeout sentinel (124 is
+            // the canonical `timeout(1)` exit code; we also surface
+            // `None` exits — the process didn't report — as killed.
+            let killed = final_exit == Some(124) || final_exit.is_none();
+            let _ = stdout_buf.was_truncated() || stderr_buf.was_truncated();
+
+            // Emit the spec-shaped `shell_call` and `shell_call_output`
+            // items so clients built against the OpenAI Responses-API
+            // spec see the same wire contract regardless of which
+            // runtime executed the call. Hadrian's additive bits
+            // (`output_files` etc.) ride alongside as extra properties.
+            //
+            // Snapshot the trimmed stdout/stderr for this event before
+            // building anything — `into_trimmed` consumes the buffers
+            // and we want them both for the SSE event and the
+            // continuation text.
+            let stdout_render =
+                std::mem::replace(&mut stdout_buf, BoundedHeadTail::new(max_chars)).into_trimmed();
+            let stderr_render =
+                std::mem::replace(&mut stderr_buf, BoundedHeadTail::new(max_chars)).into_trimmed();
+            // Spec status: `incomplete` when we killed/timed out,
+            // `completed` otherwise (a non-zero exit code still counts
+            // as `completed` per spec).
+            let shell_call_status = if killed { "incomplete" } else { "completed" };
+            let environment_val = serde_json::json!({
+                "type": "container_reference",
+                "container_id": container_id_for_items,
+            });
+            let _ = event_tx
+                .send(format_shell_call_item(
+                    ItemLifecycle::Done,
+                    &id_for_task,
+                    &id_for_task,
+                    0,
+                    &commands_for_task,
+                    action_timeout_ms_for_task,
+                    model_max_output_length,
+                    action_env_for_task.as_ref(),
+                    working_directory_for_task.as_deref(),
+                    shell_call_status,
+                    Some(&environment_val),
+                    Some("model"),
+                ))
+                .await;
+            let _ = event_tx
+                .send(format_shell_call_output_item(
+                    ItemLifecycle::Done,
+                    &id_for_task,
+                    &id_for_task,
+                    0,
+                    exit_for_report,
+                    &stdout_render,
+                    &stderr_render,
+                    &new_files,
+                    killed,
+                    model_max_output_length,
+                    Some("gateway"),
+                ))
+                .await;
+            info!(
+                stage = "shell_completed",
+                call_id = %id_for_task,
+                exit_code = exit_for_report,
+                exit_observed = final_exit.is_some(),
+                duration_ms = (duration_secs * 1000.0) as u64,
+                cost_microcents,
+                runtime = runtime_label,
+                "Shell command completed"
+            );
+            crate::observability::metrics::record_shell_execution(
+                duration_secs,
+                exit_for_report,
+                if final_exit.is_some() {
+                    "completed"
+                } else {
+                    "no_exit_event"
+                },
+                runtime_label,
+                cost_microcents,
+            );
+
+            // Build the continuation item — the model sees a single
+            // text blob with combined stdout/stderr summary, head+tail
+            // truncated. When this command produced files, append a
+            // short manifest so the model can refer to them on its
+            // next turn (e.g. "I wrote /mnt/data/foo.csv").
+            let files_section = if new_files.is_empty() {
+                String::new()
+            } else {
+                let mut s = String::from("\noutput_files:\n");
+                for f in &new_files {
+                    s.push_str(&format!("- {} ({} bytes)\n", f.path, f.bytes));
+                }
+                s
+            };
+            let combined = format!(
+                "exit_code: {}\nstdout:\n{}\nstderr:\n{}{}",
+                exit_for_report, stdout_render, stderr_render, files_section,
+            );
+
+            let cont_item = ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+                type_: FunctionCallOutputType::FunctionCallOutput,
+                id: Some(id_for_task.clone()),
+                call_id: id_for_task.clone(),
+                output: combined,
+                status: None,
+            });
+
+            let _ = result_tx.send(Ok(ToolCallResult {
+                call_id: id_for_task,
+                continuation_items: vec![cont_item],
+            }));
+            drop(event_tx);
+        });
+
+        Ok(ToolExecutionHandle {
+            events: Box::pin(futures_util::stream::unfold(
+                event_rx,
+                |mut rx| async move { rx.recv().await.map(|item| (item, rx)) },
+            )),
+            result: Box::pin(async move {
+                result_rx
+                    .await
+                    .map_err(|_| ToolError::ExecutionFailed("shell result channel closed".into()))?
+            }),
+        })
+    }
+
+    fn apply_to_continuation(
+        &self,
+        payload: &mut CreateResponsesPayload,
+        results: &[ToolCallResult],
+        is_final_iteration: bool,
+    ) {
+        let function_outputs: Vec<ResponsesInputItem> = results
+            .iter()
+            .flat_map(|r| r.continuation_items.clone())
+            .collect();
+        if function_outputs.is_empty() {
+            return;
+        }
+
+        match payload.input {
+            Some(ResponsesInput::Items(ref mut items)) => {
+                items.extend(function_outputs);
+            }
+            Some(ResponsesInput::Text(ref text)) => {
+                let text = text.clone();
+                let mut items = vec![ResponsesInputItem::EasyMessage(
+                    crate::api_types::responses::EasyInputMessage {
+                        type_: None,
+                        role: crate::api_types::responses::EasyInputMessageRole::User,
+                        content: crate::api_types::responses::EasyInputMessageContent::Text(text),
+                    },
+                )];
+                items.extend(function_outputs);
+                payload.input = Some(ResponsesInput::Items(items));
+            }
+            None => {
+                payload.input = Some(ResponsesInput::Items(function_outputs));
+            }
+        }
+
+        if is_final_iteration && let Some(ref mut tools) = payload.tools {
+            let before = tools.len();
+            tools.retain(|t| !t.is_shell());
+            tools.retain(|t| {
+                if let ResponsesToolDefinition::Function(f) = t {
+                    f.name != ShellToolArguments::FUNCTION_NAME
+                } else {
+                    true
+                }
+            });
+            if tools.len() < before {
+                info!(
+                    stage = "tools_removed",
+                    removed = before - tools.len(),
+                    "Removed shell tools on final iteration to force completion"
+                );
+            }
+            if tools.is_empty() {
+                payload.tools = None;
+            }
+        }
+    }
+
+    /// Inject `container_file_citation` annotations into output_text
+    /// `response.content_part.done` events using the captured-files
+    /// map populated by each `execute()` call.
+    fn transform_event(&self, event: Bytes) -> Bytes {
+        // Hide the rewritten `shell` function-call plumbing first; the
+        // executor emits the spec-shaped `shell_call` / `shell_call_output`
+        // items itself.
+        let event = self
+            .suppressor
+            .suppress(event, |name| name == ShellToolArguments::FUNCTION_NAME);
+        if event.is_empty() {
+            return event;
+        }
+        let captured: Vec<ContainerFileRef> = {
+            let guard = match self.captured_files.lock() {
+                Ok(g) => g,
+                Err(poisoned) => poisoned.into_inner(),
+            };
+            if guard.is_empty() {
+                return event;
+            }
+            guard.values().cloned().collect()
+        };
+        inject_container_file_citations(&event, &captured)
+    }
+}
+
+/// Append `container_file_citation` annotations to any
+/// `response.content_part.done` event whose part is an `output_text`.
+/// Existing annotations on the part are preserved; we extend the
+/// `annotations` array rather than overwriting it.
+///
+/// Mirrors the file_search citation injector but uses a fixed file
+/// list rather than parsing markers out of the text.
+fn inject_container_file_citations(chunk: &[u8], files: &[ContainerFileRef]) -> Bytes {
+    if files.is_empty() {
+        return Bytes::copy_from_slice(chunk);
+    }
+    let Ok(chunk_str) = std::str::from_utf8(chunk) else {
+        return Bytes::copy_from_slice(chunk);
+    };
+
+    let mut output = String::new();
+    for line in chunk_str.split_inclusive('\n') {
+        if let Some(data) = line.strip_prefix("data:") {
+            let data_trimmed = data.trim();
+            if data_trimmed.is_empty() || data_trimmed == "[DONE]" {
+                output.push_str(line);
+                continue;
+            }
+            if let Ok(mut json) = serde_json::from_str::<Value>(data_trimmed) {
+                let event_type = json.get("type").and_then(|t| t.as_str()).unwrap_or("");
+                if event_type == "response.content_part.done"
+                    && let Some(part) = json.get_mut("part")
+                    && let Some(part_obj) = part.as_object_mut()
+                    && part_obj.get("type").and_then(|t| t.as_str()) == Some("output_text")
+                {
+                    let mut existing: Vec<Value> = part_obj
+                        .get("annotations")
+                        .and_then(|v| v.as_array())
+                        .cloned()
+                        .unwrap_or_default();
+                    for f in files {
+                        let ann = ResponsesAnnotation::ContainerFileCitation {
+                            container_id: f.container_id.clone(),
+                            file_id: f.file_id.clone(),
+                            filename: f.filename.clone(),
+                            start_index: 0,
+                            end_index: 0,
+                            index: None,
+                        };
+                        if let Ok(v) = serde_json::to_value(&ann) {
+                            existing.push(v);
+                        }
+                    }
+                    part_obj.insert("annotations".to_string(), Value::Array(existing));
+                    debug!(
+                        stage = "container_annotations_injected",
+                        count = files.len(),
+                        "Injected container_file_citation annotations"
+                    );
+                }
+                if let Ok(json_str) = serde_json::to_string(&json) {
+                    output.push_str("data: ");
+                    output.push_str(&json_str);
+                    output.push_str("\n\n");
+                    continue;
+                }
+            }
+        }
+        output.push_str(line);
+    }
+    Bytes::from(output)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{
+        api_types::responses::{
+            ContainerExpiresAfter, ContainerExpiresAfterAnchor, ShellContainerAuto,
+            ShellContainerReference, ShellDomainSecret, ShellDomainSecretInline,
+            ShellDomainSecretRef, ShellEnvironment, ShellNetworkPolicy, ShellNetworkPolicyType,
+        },
+        config::AllowedDomainSecret,
+    };
+
+    fn op_limits_with(
+        max_mb: Option<u32>,
+        hosts: &[&str],
+        secrets: &[(&str, &str, &[&str])],
+    ) -> ShellLimitsConfig {
+        let mut limits = ShellLimitsConfig {
+            max_mem_limit_mb: max_mb,
+            allowed_egress_hosts: hosts.iter().map(|s| (*s).to_string()).collect(),
+            ..Default::default()
+        };
+        for (name, value, hs) in secrets {
+            limits.allowed_domain_secrets.insert(
+                (*name).to_string(),
+                AllowedDomainSecret {
+                    value: (*value).to_string(),
+                    allowed_hosts: hs.iter().map(|s| (*s).to_string()).collect(),
+                },
+            );
+        }
+        limits
+    }
+
+    fn default_containers() -> ContainersConfig {
+        ContainersConfig::default()
+    }
+
+    fn auto_env(memory_limit: Option<&str>, net: Option<ShellNetworkPolicy>) -> ShellEnvironment {
+        ShellEnvironment::ContainerAuto(ShellContainerAuto {
+            memory_limit: memory_limit.map(str::to_string),
+            network_policy: net,
+            file_ids: None,
+            skills: None,
+            expires_after: None,
+        })
+    }
+
+    fn net_policy(domains: &[&str], secrets: Vec<ShellDomainSecret>) -> ShellNetworkPolicy {
+        ShellNetworkPolicy {
+            type_: ShellNetworkPolicyType::Known(
+                crate::api_types::responses::KnownShellNetworkPolicyType::Allowlist,
+            ),
+            allowed_domains: domains.iter().map(|s| (*s).to_string()).collect(),
+            domain_secrets: secrets,
+        }
+    }
+
+    #[test]
+    fn resolver_none_inherits_operator_default_memory() {
+        let limits = ShellLimitsConfig {
+            default_mem_limit_mb: Some(512),
+            ..Default::default()
+        };
+        let r = resolve_shell_environment(None, &limits, &default_containers()).unwrap();
+        assert_eq!(r.mem_limit_bytes, Some(512 * 1024 * 1024));
+        assert!(r.egress_policy.allow_hosts.is_empty());
+        assert!(r.egress_policy.secrets.is_empty());
+        assert!(r.referenced_container_id.is_none());
+        assert!(r.idle_ttl_secs.is_none());
+    }
+
+    #[test]
+    fn resolver_memory_request_within_cap() {
+        let limits = op_limits_with(Some(2048), &[], &[]);
+        let env = auto_env(Some("1g"), None);
+        let r = resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap();
+        assert_eq!(r.mem_limit_bytes, Some(1024 * 1024 * 1024));
+    }
+
+    #[test]
+    fn resolver_memory_request_exceeds_cap_rejected() {
+        let limits = op_limits_with(Some(512), &[], &[]);
+        let env = auto_env(Some("1g"), None);
+        let err =
+            resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap_err();
+        assert!(
+            matches!(
+                err,
+                ShellEnvironmentError::MemoryExceedsCap {
+                    requested_mb: 1024,
+                    max_mb: 512
+                }
+            ),
+            "unexpected error: {err:?}"
+        );
+    }
+
+    #[test]
+    fn resolver_memory_no_cap_accepts_anything() {
+        let limits = op_limits_with(None, &[], &[]);
+        let env = auto_env(Some("64g"), None);
+        let r = resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap();
+        assert_eq!(r.mem_limit_bytes, Some(64 * 1024 * 1024 * 1024));
+    }
+
+    #[test]
+    fn resolver_expires_after_within_cap_flows_through() {
+        let limits = op_limits_with(None, &[], &[]);
+        let containers = default_containers();
+        let env = ShellEnvironment::ContainerAuto(ShellContainerAuto {
+            expires_after: Some(ContainerExpiresAfter {
+                anchor: ContainerExpiresAfterAnchor::LastActiveAt,
+                minutes: 30,
+            }),
+            ..Default::default()
+        });
+        let r = resolve_shell_environment(Some(&env), &limits, &containers).unwrap();
+        assert_eq!(r.idle_ttl_secs, Some(30 * 60));
+    }
+
+    #[test]
+    fn resolver_expires_after_exceeds_cap_rejected() {
+        let limits = op_limits_with(None, &[], &[]);
+        let mut containers = default_containers();
+        containers.max_idle_ttl_secs = 600; // 10 min cap
+        let env = ShellEnvironment::ContainerAuto(ShellContainerAuto {
+            expires_after: Some(ContainerExpiresAfter {
+                anchor: ContainerExpiresAfterAnchor::LastActiveAt,
+                minutes: 30,
+            }),
+            ..Default::default()
+        });
+        let err = resolve_shell_environment(Some(&env), &limits, &containers).unwrap_err();
+        assert!(
+            matches!(
+                err,
+                ShellEnvironmentError::ExpiresAfterExceedsCap {
+                    requested: 30,
+                    max: 10,
+                }
+            ),
+            "unexpected error: {err:?}"
+        );
+    }
+
+    #[test]
+    fn resolver_memory_unparseable_rejected() {
+        let limits = ShellLimitsConfig::default();
+        let env = auto_env(Some("huge"), None);
+        let err =
+            resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap_err();
+        assert!(matches!(err, ShellEnvironmentError::BadMemoryLimit(_)));
+    }
+
+    #[test]
+    fn resolver_egress_subset_accepted() {
+        let limits = op_limits_with(None, &["api.openai.com", "*.example.com"], &[]);
+        let env = auto_env(
+            None,
+            Some(net_policy(
+                &["api.openai.com", "foo.example.com"],
+                Vec::new(),
+            )),
+        );
+        let r = resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap();
+        assert_eq!(r.egress_policy.allow_hosts.len(), 2);
+    }
+
+    #[test]
+    fn resolver_egress_apex_does_not_match_wildcard() {
+        let limits = op_limits_with(None, &["*.example.com"], &[]);
+        let env = auto_env(None, Some(net_policy(&["example.com"], Vec::new())));
+        let err =
+            resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap_err();
+        assert!(matches!(err, ShellEnvironmentError::HostNotAllowed(h) if h == "example.com"));
+    }
+
+    #[test]
+    fn resolver_egress_host_outside_allowlist_rejected() {
+        let limits = op_limits_with(None, &["api.openai.com"], &[]);
+        let env = auto_env(None, Some(net_policy(&["evil.example.com"], Vec::new())));
+        let err =
+            resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap_err();
+        assert!(matches!(err, ShellEnvironmentError::HostNotAllowed(h) if h == "evil.example.com"));
+    }
+
+    #[test]
+    fn resolver_wildcard_star_allows_everything() {
+        let limits = op_limits_with(None, &["*"], &[]);
+        let env = auto_env(None, Some(net_policy(&["anything.example"], Vec::new())));
+        assert!(resolve_shell_environment(Some(&env), &limits, &default_containers()).is_ok());
+    }
+
+    #[test]
+    fn resolver_unknown_secret_rejected() {
+        let limits = op_limits_with(None, &[], &[]);
+        let env = auto_env(
+            None,
+            Some(net_policy(
+                &[],
+                vec![ShellDomainSecret::Reference(ShellDomainSecretRef {
+                    placeholder: "GITHUB_TOKEN".into(),
+                    allowed_domains: vec![],
+                })],
+            )),
+        );
+        let err =
+            resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap_err();
+        assert!(matches!(err, ShellEnvironmentError::UnknownSecret(p) if p == "GITHUB_TOKEN"));
+    }
+
+    #[test]
+    fn resolver_secret_subset_accepted_inherits_full_allowlist_when_empty() {
+        let limits = op_limits_with(
+            None,
+            &[],
+            &[("GH", "ghp_xxx", &["api.github.com", "uploads.github.com"])],
+        );
+        let env = auto_env(
+            None,
+            Some(net_policy(
+                &[],
+                vec![ShellDomainSecret::Reference(ShellDomainSecretRef {
+                    placeholder: "GH".into(),
+                    allowed_domains: vec![],
+                })],
+            )),
+        );
+        let r = resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap();
+        assert_eq!(r.egress_policy.secrets.len(), 1);
+        assert_eq!(r.egress_policy.secrets[0].value, "ghp_xxx");
+        assert_eq!(r.egress_policy.secrets[0].allowed_hosts.len(), 2);
+    }
+
+    #[test]
+    fn resolver_secret_host_outside_allowed_rejected() {
+        let limits = op_limits_with(None, &[], &[("GH", "v", &["api.github.com"])]);
+        let env = auto_env(
+            None,
+            Some(net_policy(
+                &[],
+                vec![ShellDomainSecret::Reference(ShellDomainSecretRef {
+                    placeholder: "GH".into(),
+                    allowed_domains: vec!["evil.example.com".into()],
+                })],
+            )),
+        );
+        let err =
+            resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap_err();
+        assert!(matches!(
+            err,
+            ShellEnvironmentError::SecretHostNotAllowed { placeholder, host }
+                if placeholder == "GH" && host == "evil.example.com"
+        ));
+    }
+
+    #[test]
+    fn resolver_inline_secret_uses_host_envelope_and_propagates_value() {
+        let limits = op_limits_with(None, &["api.github.com"], &[]);
+        let env = auto_env(
+            None,
+            Some(net_policy(
+                &["api.github.com"],
+                vec![ShellDomainSecret::Inline(ShellDomainSecretInline {
+                    domain: "api.github.com".into(),
+                    name: "GH_TOKEN".into(),
+                    value: "ghp_inline".into(),
+                })],
+            )),
+        );
+        let r = resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap();
+        assert_eq!(r.egress_policy.secrets.len(), 1);
+        assert_eq!(r.egress_policy.secrets[0].placeholder, "GH_TOKEN");
+        assert_eq!(r.egress_policy.secrets[0].value, "ghp_inline");
+        assert_eq!(
+            r.egress_policy.secrets[0].allowed_hosts,
+            vec!["api.github.com".to_string()]
+        );
+    }
+
+    #[test]
+    fn resolver_inline_secret_host_outside_operator_envelope_rejected() {
+        let limits = op_limits_with(None, &["api.github.com"], &[]);
+        let env = auto_env(
+            None,
+            Some(ShellNetworkPolicy {
+                type_: ShellNetworkPolicyType::Known(
+                    crate::api_types::responses::KnownShellNetworkPolicyType::Allowlist,
+                ),
+                allowed_domains: vec![],
+                domain_secrets: vec![ShellDomainSecret::Inline(ShellDomainSecretInline {
+                    domain: "evil.example.com".into(),
+                    name: "X".into(),
+                    value: "y".into(),
+                })],
+            }),
+        );
+        let err =
+            resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap_err();
+        assert!(matches!(
+            err,
+            ShellEnvironmentError::InlineSecretHostNotAllowed { name, host }
+                if name == "X" && host == "evil.example.com"
+        ));
+    }
+
+    #[test]
+    fn resolver_container_reference_returns_id() {
+        let limits = op_limits_with(None, &[], &[]);
+        let env = ShellEnvironment::ContainerReference(ShellContainerReference {
+            container_id: "cntr_abc".into(),
+            network_policy: None,
+        });
+        let r = resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap();
+        assert_eq!(r.referenced_container_id.as_deref(), Some("cntr_abc"));
+    }
+
+    #[test]
+    fn resolver_container_reference_rejects_empty_id() {
+        let limits = op_limits_with(None, &[], &[]);
+        let env = ShellEnvironment::ContainerReference(ShellContainerReference {
+            container_id: "   ".into(),
+            network_policy: None,
+        });
+        let err =
+            resolve_shell_environment(Some(&env), &limits, &default_containers()).unwrap_err();
+        assert!(matches!(
+            err,
+            ShellEnvironmentError::EmptyContainerReferenceId
+        ));
+    }
+
+    #[test]
+    fn parses_memory_limits() {
+        assert_eq!(parse_memory_limit("1g"), Some(1024 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("512m"), Some(512 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("1024MB"), Some(1024 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("2 GB"), Some(2 * 1024 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("4096"), Some(4096));
+        assert_eq!(parse_memory_limit("4096b"), Some(4096));
+        assert_eq!(parse_memory_limit(""), None);
+        assert_eq!(parse_memory_limit("nope"), None);
+        assert_eq!(parse_memory_limit("1tb"), None);
+    }
+
+    #[test]
+    fn host_match_handles_wildcards() {
+        assert!(host_matches("a.example.com", "*.example.com"));
+        assert!(host_matches("a.b.example.com", "*.example.com"));
+        assert!(!host_matches("example.com", "*.example.com"));
+        assert!(!host_matches("notexample.com", "*.example.com"));
+        assert!(host_matches("Anything.tld", "*"));
+        assert!(host_matches("API.OpenAI.com", "api.openai.com"));
+    }
+
+    #[test]
+    fn host_match_normalizes_trailing_dot() {
+        // FQDN form (RFC 1035) with explicit root-domain dot.
+        assert!(host_matches("api.openai.com.", "api.openai.com"));
+        assert!(host_matches("api.openai.com", "api.openai.com."));
+        assert!(host_matches("a.example.com.", "*.example.com"));
+        assert!(host_matches("a.example.com", "*.example.com."));
+    }
+
+    #[test]
+    fn parses_single_command_action() {
+        let v = serde_json::json!({
+            "type": "function_call",
+            "name": "shell",
+            "call_id": "call_abc",
+            "arguments": "{\"action\": {\"commands\": [\"echo hi\"]}}"
+        });
+        let tc = parse_shell_tool_call(&v).unwrap();
+        assert_eq!(tc.id, "call_abc");
+        assert_eq!(tc.args.commands, vec!["echo hi".to_string()]);
+        assert!(tc.args.stdin.is_none());
+        assert!(tc.args.timeout_ms.is_none());
+    }
+
+    #[test]
+    fn parses_multi_command_action() {
+        let v = serde_json::json!({
+            "type": "function_call",
+            "name": "shell",
+            "call_id": "call_xyz",
+            "arguments": "{\"action\": {\"commands\": [\"cd /tmp\", \"ls /\"], \"timeout_ms\": 1500, \"max_output_length\": 2000, \"env\": {\"FOO\": \"bar\"}, \"working_directory\": \"/tmp\"}}"
+        });
+        let tc = parse_shell_tool_call(&v).unwrap();
+        assert_eq!(
+            tc.args.commands,
+            vec!["cd /tmp".to_string(), "ls /".to_string()]
+        );
+        assert_eq!(tc.args.timeout_ms, Some(1500));
+        assert_eq!(tc.args.max_output_length, Some(2000));
+        assert_eq!(
+            tc.args.env.as_ref().unwrap().get("FOO").map(|s| s.as_str()),
+            Some("bar")
+        );
+        assert_eq!(tc.args.working_directory.as_deref(), Some("/tmp"));
+        // Script form joins with newlines.
+        assert_eq!(tc.args.joined_script(), "cd /tmp\nls /");
+    }
+
+    #[test]
+    fn empty_commands_resolves_none() {
+        let args =
+            ShellToolArguments::parse("{\"action\": {\"commands\": [\"   \", \"\"]}}").unwrap();
+        assert!(args.resolve().is_none());
+    }
+
+    #[test]
+    fn build_effective_command_prepends_cd_and_exports() {
+        let mut env = HashMap::new();
+        env.insert("FOO".to_string(), "bar".to_string());
+        env.insert("BAZ".to_string(), "with 'quote'".to_string());
+        let out = build_effective_command("ls /", Some(&env), Some("/tmp")).unwrap();
+        // cd preamble first, then exports in sorted order, then command.
+        assert_eq!(
+            out,
+            "cd '/tmp' || exit 1\nexport BAZ='with '\\''quote'\\'''\nexport FOO='bar'\nls /"
+        );
+    }
+
+    #[test]
+    fn build_effective_command_noop_without_env_or_cwd() {
+        assert_eq!(build_effective_command("ls /", None, None).unwrap(), "ls /");
+        // Blank working_directory is ignored.
+        assert_eq!(
+            build_effective_command("ls /", None, Some("   ")).unwrap(),
+            "ls /"
+        );
+    }
+
+    #[test]
+    fn build_effective_command_rejects_bad_env_name() {
+        let mut env = HashMap::new();
+        env.insert("BAD NAME".to_string(), "x".to_string());
+        assert!(matches!(
+            build_effective_command("ls", Some(&env), None),
+            Err(ToolError::InvalidCall(_))
+        ));
+        let mut env2 = HashMap::new();
+        env2.insert("1FOO".to_string(), "x".to_string());
+        assert!(build_effective_command("ls", Some(&env2), None).is_err());
+    }
+
+    #[test]
+    fn env_name_validation() {
+        assert!(is_valid_env_name("FOO"));
+        assert!(is_valid_env_name("_foo_BAR9"));
+        assert!(!is_valid_env_name(""));
+        assert!(!is_valid_env_name("9foo"));
+        assert!(!is_valid_env_name("FO O"));
+        assert!(!is_valid_env_name("FOO=BAR"));
+    }
+
+    #[test]
+    fn ignores_non_shell_function_calls() {
+        let v = serde_json::json!({
+            "type": "function_call",
+            "name": "web_search",
+            "call_id": "call_xyz",
+            "arguments": "{\"query\": \"hi\"}"
+        });
+        assert!(parse_shell_tool_call(&v).is_none());
+    }
+
+    #[test]
+    fn preprocess_rewrites_shell_tool_to_function() {
+        let payload_json = serde_json::json!({
+            "tools": [{"type": "shell"}],
+            "stream": false,
+        });
+        let mut payload: CreateResponsesPayload = serde_json::from_value(payload_json).unwrap();
+        preprocess_shell_tools(&mut payload, &ShellToolHint::default());
+        let tools = payload.tools.unwrap();
+        assert_eq!(tools.len(), 1);
+        let ResponsesToolDefinition::Function(func) = &tools[0] else {
+            panic!("expected function tool");
+        };
+        // Default hint advertises Hadrian-hosted sandbox and the workdir.
+        let desc = func.description.as_deref().unwrap();
+        assert!(
+            desc.contains("/mnt/data"),
+            "description should mention workdir: {desc}"
+        );
+        assert!(
+            desc.contains("truncated"),
+            "description should warn about truncation: {desc}"
+        );
+    }
+
+    #[test]
+    fn shell_hint_describes_client_passthrough() {
+        let hint = ShellToolHint {
+            location: ShellExecutionLocation::ApiClient,
+            ..ShellToolHint::default()
+        };
+        let desc = hint.render_description();
+        assert!(
+            desc.contains("API client"),
+            "should call out client execution: {desc}"
+        );
+        // Workdir guidance is for Hadrian-hosted sandboxes; client-mode
+        // models shouldn't be told to write to /mnt/data.
+        assert!(
+            !desc.contains("written under `/mnt/data`"),
+            "client mode should not promise /mnt/data: {desc}"
+        );
+    }
+
+    #[test]
+    fn shell_hint_describes_allowlist() {
+        let hint = ShellToolHint {
+            network_summary: ShellNetworkSummary::Allowlist(vec![
+                "api.example.com".into(),
+                "cdn.example.org".into(),
+            ]),
+            ..ShellToolHint::default()
+        };
+        let desc = hint.render_description();
+        assert!(
+            desc.contains("api.example.com"),
+            "should list allowed host: {desc}"
+        );
+        assert!(desc.contains("cdn.example.org"));
+    }
+
+    #[test]
+    fn utf8_chunk_decoder_buffers_partial_sequences() {
+        let mut dec = Utf8ChunkDecoder::new();
+        // "é" is 0xC3 0xA9 in UTF-8. Feed the lead byte alone — should
+        // emit nothing yet and hold the byte for the next push.
+        assert_eq!(dec.push(&[0xC3]), "");
+        // Now feed the continuation byte — should emit the full char.
+        assert_eq!(dec.push(&[0xA9]), "é");
+        // Mixed: ASCII then a partial sequence at the tail.
+        assert_eq!(dec.push(b"abc\xC3"), "abc");
+        assert_eq!(dec.push(&[0xA9]), "é");
+    }
+
+    #[test]
+    fn utf8_chunk_decoder_handles_three_and_four_byte_sequences() {
+        let mut dec = Utf8ChunkDecoder::new();
+        // Snowman: 0xE2 0x98 0x83 (3 bytes).
+        assert_eq!(dec.push(&[0xE2, 0x98]), "");
+        assert_eq!(dec.push(&[0x83]), "☃");
+        // 4-byte: 𝄞 = 0xF0 0x9D 0x84 0x9E.
+        assert_eq!(dec.push(&[0xF0, 0x9D, 0x84]), "");
+        assert_eq!(dec.push(&[0x9E]), "𝄞");
+    }
+
+    #[test]
+    fn bounded_head_tail_under_cap_passes_through() {
+        let mut b = BoundedHeadTail::new(20);
+        b.push_str("hello world");
+        assert_eq!(b.into_trimmed(), "hello world");
+    }
+
+    #[test]
+    fn bounded_head_tail_emits_truncation_marker() {
+        let mut b = BoundedHeadTail::new(10);
+        // 5 head + 5 tail = 10 kept; the rest is the truncated middle.
+        b.push_str("AAAAA");
+        b.push_str("BBBBBBBBBB");
+        b.push_str("CCCCC");
+        let out = b.into_trimmed();
+        assert!(out.contains("chars truncated"), "got: {out}");
+        assert!(out.starts_with("AAAAA"));
+        assert!(out.ends_with("CCCCC"));
+    }
+
+    fn sample_file(file_id: &str, filename: &str, path: &str) -> ContainerFileRef {
+        ContainerFileRef {
+            container_id: "cntr_test".to_string(),
+            file_id: file_id.to_string(),
+            filename: filename.to_string(),
+            path: path.to_string(),
+            bytes: 42,
+            content_type: Some("text/csv".to_string()),
+            source: crate::api_types::responses::ContainerFileSource::Assistant,
+        }
+    }
+
+    #[test]
+    fn injects_container_file_citation_on_content_part_done() {
+        let files = vec![sample_file("cfile_abc", "out.csv", "/mnt/data/out.csv")];
+        let event = b"data: {\"type\":\"response.content_part.done\",\"part\":{\"type\":\"output_text\",\"text\":\"Done\"}}\n\n";
+        let out = inject_container_file_citations(event, &files);
+        let s = std::str::from_utf8(&out).unwrap();
+        // Pull the JSON payload back out and re-parse.
+        let json_str = s.trim().strip_prefix("data: ").unwrap();
+        let v: Value = serde_json::from_str(json_str).unwrap();
+        let anns = v
+            .get("part")
+            .and_then(|p| p.get("annotations"))
+            .and_then(|a| a.as_array())
+            .expect("annotations array");
+        assert_eq!(anns.len(), 1);
+        let ann = &anns[0];
+        assert_eq!(
+            ann.get("type").and_then(|t| t.as_str()),
+            Some("container_file_citation")
+        );
+        assert_eq!(
+            ann.get("file_id").and_then(|f| f.as_str()),
+            Some("cfile_abc")
+        );
+        assert_eq!(
+            ann.get("filename").and_then(|f| f.as_str()),
+            Some("out.csv")
+        );
+        assert_eq!(
+            ann.get("container_id").and_then(|c| c.as_str()),
+            Some("cntr_test")
+        );
+    }
+
+    #[test]
+    fn preserves_existing_annotations_on_content_part_done() {
+        let files = vec![sample_file("cfile_a", "a.csv", "/mnt/data/a.csv")];
+        let event = b"data: {\"type\":\"response.content_part.done\",\"part\":{\"type\":\"output_text\",\"text\":\"hi\",\"annotations\":[{\"type\":\"file_citation\",\"file_id\":\"file_existing\",\"filename\":\"prior.txt\",\"index\":0}]}}\n\n";
+        let out = inject_container_file_citations(event, &files);
+        let s = std::str::from_utf8(&out).unwrap();
+        let json_str = s.trim().strip_prefix("data: ").unwrap();
+        let v: Value = serde_json::from_str(json_str).unwrap();
+        let anns = v["part"]["annotations"].as_array().unwrap();
+        assert_eq!(anns.len(), 2, "existing annotation should be preserved");
+        assert!(
+            anns.iter()
+                .any(|a| a["type"] == "file_citation" && a["file_id"] == "file_existing")
+        );
+        assert!(
+            anns.iter()
+                .any(|a| a["type"] == "container_file_citation" && a["file_id"] == "cfile_a")
+        );
+    }
+
+    #[test]
+    fn leaves_unrelated_events_untouched() {
+        let files = vec![sample_file("cfile_x", "x", "/mnt/data/x")];
+        let event = b"data: {\"type\":\"response.output_text.delta\",\"delta\":\"hello\"}\n\n";
+        let out = inject_container_file_citations(event, &files);
+        // No content_part.done → no annotations injected; passes through
+        // semantically. We deserialize + reserialize so byte-equality
+        // isn't guaranteed, but the parsed shape must match.
+        let s = std::str::from_utf8(&out).unwrap();
+        let json_str = s.trim().strip_prefix("data: ").unwrap();
+        let v: Value = serde_json::from_str(json_str).unwrap();
+        assert_eq!(v["type"], "response.output_text.delta");
+        assert_eq!(v["delta"], "hello");
+        assert!(v.get("annotations").is_none());
+    }
+
+    #[test]
+    fn no_op_when_no_captured_files() {
+        let event = b"data: {\"type\":\"response.content_part.done\",\"part\":{\"type\":\"output_text\",\"text\":\"hi\"}}\n\n";
+        let out = inject_container_file_citations(event, &[]);
+        // Pass-through: returned bytes equal the input bytes verbatim.
+        assert_eq!(&out[..], &event[..]);
+    }
+
+    #[test]
+    fn shell_call_done_carries_container_reference_environment() {
+        let env = serde_json::json!({
+            "type": "container_reference",
+            "container_id": "cntr_abc123",
+        });
+        let bytes = format_shell_call_item(
+            ItemLifecycle::Done,
+            "call_1",
+            "call_1",
+            0,
+            &["echo hi".to_string()],
+            None,
+            None,
+            None,
+            None,
+            "completed",
+            Some(&env),
+            Some("model"),
+        );
+        let s = std::str::from_utf8(&bytes).unwrap();
+        let json_str = s.trim().strip_prefix("data: ").unwrap();
+        let v: Value = serde_json::from_str(json_str).unwrap();
+        assert_eq!(v["type"], "response.output_item.done");
+        let item = &v["item"];
+        assert_eq!(item["type"], "shell_call");
+        assert_eq!(item["status"], "completed");
+        assert_eq!(item["environment"]["type"], "container_reference");
+        assert_eq!(item["environment"]["container_id"], "cntr_abc123");
+    }
+
+    #[test]
+    fn shell_call_added_omits_environment_when_unknown() {
+        let bytes = format_shell_call_item(
+            ItemLifecycle::Added,
+            "call_1",
+            "call_1",
+            0,
+            &["echo hi".to_string()],
+            None,
+            None,
+            None,
+            None,
+            "in_progress",
+            None,
+            Some("model"),
+        );
+        let s = std::str::from_utf8(&bytes).unwrap();
+        let json_str = s.trim().strip_prefix("data: ").unwrap();
+        let v: Value = serde_json::from_str(json_str).unwrap();
+        assert_eq!(v["type"], "response.output_item.added");
+        let item = &v["item"];
+        assert_eq!(item["status"], "in_progress");
+        assert!(item.get("environment").is_none());
+    }
+
+    #[test]
+    fn shell_call_output_done_includes_captured_files() {
+        let f = sample_file("cfile_abc", "out.csv", "/mnt/data/out.csv");
+        let bytes = format_shell_call_output_item(
+            ItemLifecycle::Done,
+            "call_1",
+            "call_1",
+            0,
+            0,
+            "",
+            "",
+            std::slice::from_ref(&f),
+            false,
+            None,
+            Some("gateway"),
+        );
+        let s = std::str::from_utf8(&bytes).unwrap();
+        let json_str = s.trim().strip_prefix("data: ").unwrap();
+        let v: Value = serde_json::from_str(json_str).unwrap();
+        assert_eq!(v["type"], "response.output_item.done");
+        let item = &v["item"];
+        assert_eq!(item["type"], "shell_call_output");
+        assert_eq!(item["status"], "completed");
+        let files = item["output_files"].as_array().unwrap();
+        assert_eq!(files.len(), 1);
+        assert_eq!(files[0]["file_id"], "cfile_abc");
+        assert_eq!(files[0]["container_id"], "cntr_test");
+    }
+}
diff --git a/src/services/usage.rs b/src/services/usage.rs
index 994063a..0a77857 100644
--- a/src/services/usage.rs
+++ b/src/services/usage.rs
@@ -1458,6 +1458,8 @@ mod tests {
             tool_url: None,
             tool_bytes_fetched: None,
             tool_results_count: None,
+            tool_runtime_seconds: None,
+            tool_exit_code: None,
         }
     }
 
@@ -1502,6 +1504,8 @@ mod tests {
             tool_url: None,
             tool_bytes_fetched: None,
             tool_results_count: None,
+            tool_runtime_seconds: None,
+            tool_exit_code: None,
         }
     }
 
diff --git a/src/services/web_search_tool.rs b/src/services/web_search_tool.rs
index 0bc4113..c664fc3 100644
--- a/src/services/web_search_tool.rs
+++ b/src/services/web_search_tool.rs
@@ -4,28 +4,22 @@
 //! the configured search provider (Tavily/Exa), feeding results back into the
 //! conversation transparently — following the same pattern as `file_search_tool`.
 
-use std::{future::Future, pin::Pin, sync::Arc, time::Instant};
+use std::time::Instant;
 
-use axum::body::Body;
-use bytes::{Bytes, BytesMut};
-use futures_util::StreamExt;
-use http::Response;
+use bytes::Bytes;
 use serde::Deserialize;
 use serde_json::Value;
-use tokio::sync::mpsc;
-use tracing::{Instrument, debug, error, info, info_span, warn};
+use tracing::{debug, error, info};
 
 use crate::{
     api_types::responses::{
-        CreateResponsesPayload, FunctionCallOutput, FunctionCallOutputType, ResponsesInput,
-        ResponsesInputItem, ResponsesToolDefinition, WebSearchCallOutput, WebSearchCallOutputType,
-        WebSearchStatus,
+        CreateResponsesPayload, FunctionCallOutput, FunctionCallOutputType, FunctionTool,
+        ResponsesInput, ResponsesInputItem, ResponsesToolDefinition, WebSearchCallOutput,
+        WebSearchCallOutputType, WebSearchStatus,
     },
     config::WebSearchConfig,
-    observability::metrics::{record_web_search, record_web_search_iteration},
-    providers::ProviderError,
+    observability::metrics::record_web_search,
     routes::api::tools::{WebSearchResult, execute_web_search},
-    services::file_search_tool::SseBuffer,
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -90,7 +84,10 @@ pub fn preprocess_web_search_tools(payload: &mut CreateResponsesPayload) {
     for tool in tools.iter_mut() {
         if tool.is_web_search() {
             let function_def = WebSearchToolArguments::function_tool_definition();
-            *tool = ResponsesToolDefinition::Function(function_def);
+            *tool = ResponsesToolDefinition::Function(
+                FunctionTool::from_json(function_def)
+                    .expect("web_search function-tool definition is well-formed"),
+            );
             debug!(
                 stage = "tool_preprocessed",
                 "Preprocessed web_search tool to function definition"
@@ -103,31 +100,12 @@ pub fn preprocess_web_search_tools(payload: &mut CreateResponsesPayload) {
 // Context
 // ─────────────────────────────────────────────────────────────────────────────
 
-/// Type alias for the provider callback (reuses the same signature as file_search).
-#[cfg(not(target_arch = "wasm32"))]
-type ProviderCallback = Arc<
-    dyn Fn(
-            CreateResponsesPayload,
-        ) -> Pin<Box<dyn Future<Output = Result<Response<Body>, ProviderError>> + Send>>
-        + Send
-        + Sync,
->;
-
-#[cfg(target_arch = "wasm32")]
-type ProviderCallback = Arc<
-    dyn Fn(
-        CreateResponsesPayload,
-    ) -> Pin<Box<dyn Future<Output = Result<Response<Body>, ProviderError>>>>,
->;
-
 /// Context for web search middleware operations.
 #[derive(Clone)]
 pub struct WebSearchContext {
     pub http_client: reqwest::Client,
     pub config: WebSearchConfig,
     pub max_iterations: usize,
-    original_payload: CreateResponsesPayload,
-    provider_callback: Option<ProviderCallback>,
 }
 
 impl WebSearchContext {
@@ -135,22 +113,14 @@ impl WebSearchContext {
         http_client: reqwest::Client,
         config: WebSearchConfig,
         max_iterations: usize,
-        original_payload: CreateResponsesPayload,
     ) -> Self {
         Self {
             http_client,
             config,
             max_iterations,
-            original_payload,
-            provider_callback: None,
         }
     }
 
-    pub fn with_provider_callback(mut self, callback: crate::services::ProviderCallback) -> Self {
-        self.provider_callback = Some(callback);
-        self
-    }
-
     pub fn is_enabled(&self) -> bool {
         true // If we have a context, we're enabled
     }
@@ -346,382 +316,221 @@ fn format_web_search_call_output_event(item_id: &str) -> Option<Bytes> {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Continuation payload
+// Streaming wrapper
 // ─────────────────────────────────────────────────────────────────────────────
 
-fn build_web_search_continuation_payload(
-    original: &CreateResponsesPayload,
-    tool_results: &[(&WebSearchToolCall, String)],
-    is_final_iteration: bool,
-) -> CreateResponsesPayload {
-    let mut payload = original.clone();
-
-    let function_outputs: Vec<ResponsesInputItem> = tool_results
-        .iter()
-        .map(|(tool_call, content)| {
-            ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
-                type_: FunctionCallOutputType::FunctionCallOutput,
-                id: Some(tool_call.id.clone()),
-                call_id: tool_call.id.clone(),
-                output: content.clone(),
-                status: None,
-            })
-        })
-        .collect();
+// ─────────────────────────────────────────────────────────────────────────────
+// ServerExecutedTool implementation
+// ─────────────────────────────────────────────────────────────────────────────
 
-    match payload.input {
-        Some(ResponsesInput::Items(ref mut items)) => {
-            items.extend(function_outputs);
-        }
-        Some(ResponsesInput::Text(text)) => {
-            let mut items = vec![ResponsesInputItem::EasyMessage(
-                crate::api_types::responses::EasyInputMessage {
-                    type_: None,
-                    role: crate::api_types::responses::EasyInputMessageRole::User,
-                    content: crate::api_types::responses::EasyInputMessageContent::Text(text),
-                },
-            )];
-            items.extend(function_outputs);
-            payload.input = Some(ResponsesInput::Items(items));
-        }
-        None => {
-            payload.input = Some(ResponsesInput::Items(function_outputs));
-        }
-    }
+/// `ServerExecutedTool` implementation for `web_search`.
+#[cfg(feature = "server")]
+pub struct WebSearchExecutor {
+    context: WebSearchContext,
+    /// Hides the rewritten `web_search` function-call plumbing from the
+    /// client stream; the executor emits the spec-shaped
+    /// `web_search_call` items itself.
+    suppressor: crate::services::server_tools::FunctionCallSuppressor,
+}
 
-    // On final iteration, remove web_search tools to force text completion
-    if is_final_iteration && let Some(ref mut tools) = payload.tools {
-        let original_count = tools.len();
-        tools.retain(|t| !t.is_web_search());
-        // Also remove function tools named "web_search" (from preprocessing)
-        tools.retain(|t| {
-            if let ResponsesToolDefinition::Function(v) = t {
-                v.get("name").and_then(|n| n.as_str())
-                    != Some(WebSearchToolArguments::FUNCTION_NAME)
-            } else {
-                true
-            }
-        });
-        let removed_count = original_count - tools.len();
-        if removed_count > 0 {
-            info!(
-                stage = "tools_removed",
-                removed_count = removed_count,
-                "Removed web_search tools on final iteration to force completion"
-            );
-        }
-        if tools.is_empty() {
-            payload.tools = None;
+#[cfg(feature = "server")]
+impl WebSearchExecutor {
+    pub fn new(context: WebSearchContext) -> Self {
+        Self {
+            context,
+            suppressor: crate::services::server_tools::FunctionCallSuppressor::new(),
         }
     }
-
-    payload.stream = true;
-    payload
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Streaming wrapper
-// ─────────────────────────────────────────────────────────────────────────────
-
-/// Wrap a streaming response with web_search tool interception and multi-turn execution.
-///
-/// Monitors the stream for web_search function calls. When detected:
-/// 1. Executes the search against the configured provider (Tavily/Exa)
-/// 2. Builds a continuation payload with the search results
-/// 3. Sends the continuation to the provider via the callback
-/// 4. Streams the continuation response to the client
-pub fn wrap_streaming_with_web_search(
-    response: Response<Body>,
-    context: WebSearchContext,
-) -> Response<Body> {
-    if !context.is_enabled() {
-        return response;
+#[cfg(feature = "server")]
+#[async_trait::async_trait]
+impl crate::services::server_tools::ServerExecutedTool for WebSearchExecutor {
+    fn name(&self) -> &'static str {
+        WebSearchToolArguments::FUNCTION_NAME
     }
 
-    let (parts, body) = response.into_parts();
-    let max_iterations = context.max_iterations;
-    let has_callback = context.provider_callback.is_some();
-
-    let web_search_span = info_span!(
-        "web_search_stream",
-        max_iterations = max_iterations,
-        has_callback = has_callback,
-    );
-
-    let (tx, rx) = mpsc::channel::<Result<Bytes, std::io::Error>>(32);
-
-    crate::compat::spawn_detached(
-        async move {
-            let mut iteration = 0;
-            let mut current_body = body;
-
-            loop {
-                iteration += 1;
-                let at_iteration_limit = iteration > max_iterations;
-
-                debug!(
-                    iteration = iteration,
-                    at_limit = at_iteration_limit,
-                    "Starting web_search iteration"
-                );
-
-                let mut body_stream = current_body.into_data_stream();
-                let mut accumulated = BytesMut::new();
-                let mut detected_tool_calls: Vec<WebSearchToolCall> = Vec::new();
-                let mut sse_buffer = SseBuffer::new();
-
-                while let Some(chunk_result) = body_stream.next().await {
-                    match chunk_result {
-                        Ok(chunk) => {
-                            accumulated.extend_from_slice(&chunk);
-                            sse_buffer.extend(&chunk);
-
-                            let complete_events = sse_buffer.extract_complete_events();
-
-                            for event in complete_events {
-                                if !at_iteration_limit {
-                                    let tool_calls = detect_web_search_in_chunk(&event);
-                                    for tool_call in tool_calls {
-                                        info!(
-                                            stage = "tool_call_detected",
-                                            tool_call_id = %tool_call.id,
-                                            query = %tool_call.query,
-                                            iteration = iteration,
-                                            "Detected web_search tool call in stream"
-                                        );
-                                        detected_tool_calls.push(tool_call);
-                                    }
-
-                                    if !detected_tool_calls.is_empty() && has_callback {
-                                        continue;
-                                    }
-                                }
+    /// Hide the rewritten `web_search` function-call plumbing; the
+    /// executor emits the spec-shaped `web_search_call` items itself.
+    fn transform_event(&self, event: Bytes) -> Bytes {
+        self.suppressor
+            .suppress(event, |name| name == WebSearchToolArguments::FUNCTION_NAME)
+    }
 
-                                if tx.send(Ok(event)).await.is_err() {
-                                    return;
-                                }
-                            }
-                        }
-                        Err(e) => {
-                            warn!(
-                                stage = "stream_error",
-                                error = %e,
-                                iteration = iteration,
-                                "Error reading stream chunk"
-                            );
-                            let _ = tx.send(Err(std::io::Error::other(e))).await;
-                            return;
-                        }
-                    }
-                }
+    fn is_enabled_for(&self, payload: &CreateResponsesPayload) -> bool {
+        self.context.is_enabled()
+            && payload
+                .tools
+                .as_ref()
+                .map(|tools| {
+                    tools.iter().any(|t| {
+                        t.is_web_search()
+                            || matches!(
+                                t,
+                                ResponsesToolDefinition::Function(f)
+                                    if f.name == WebSearchToolArguments::FUNCTION_NAME
+                            )
+                    })
+                })
+                .unwrap_or(false)
+    }
 
-                // Forward remaining incomplete data
-                if !sse_buffer.is_empty() {
-                    let remaining = sse_buffer.take_remaining();
-                    if !remaining.is_empty()
-                        && (detected_tool_calls.is_empty() || !has_callback)
-                        && tx.send(Ok(remaining)).await.is_err()
-                    {
-                        return;
-                    }
-                }
+    fn detect(
+        &self,
+        event: &[u8],
+        _ctx: &crate::services::server_tools::ToolContext,
+    ) -> Vec<crate::services::server_tools::DetectedToolCall> {
+        detect_web_search_in_chunk(event)
+            .into_iter()
+            .map(|tc| crate::services::server_tools::DetectedToolCall {
+                tool_name: WebSearchToolArguments::FUNCTION_NAME,
+                call_id: tc.id.clone(),
+                arguments: serde_json::json!({
+                    "id": tc.id,
+                    "query": tc.query,
+                }),
+            })
+            .collect()
+    }
 
-                if at_iteration_limit {
-                    warn!(
-                        stage = "iteration_limit_reached",
-                        iteration = iteration,
-                        max_iterations = max_iterations,
-                        "Maximum web_search iterations exceeded, forwarding final response"
-                    );
-                    record_web_search_iteration(iteration as u32, true, "limit_reached");
-                    break;
+    async fn execute(
+        &self,
+        call: crate::services::server_tools::DetectedToolCall,
+        _ctx: &crate::services::server_tools::ToolContext,
+    ) -> Result<
+        crate::services::server_tools::ToolExecutionHandle,
+        crate::services::server_tools::ToolError,
+    > {
+        let query = call
+            .arguments
+            .get("query")
+            .and_then(|v| v.as_str())
+            .unwrap_or_default()
+            .to_string();
+        let id = call.call_id.clone();
+
+        let (event_tx, event_rx) = tokio::sync::mpsc::channel::<Bytes>(8);
+
+        // in_progress + searching events
+        let _ = event_tx
+            .send(format_web_search_in_progress_event(&id, 0))
+            .await;
+        let _ = event_tx
+            .send(format_web_search_searching_event(&id, 0))
+            .await;
+
+        let context = self.context.clone();
+        let start = Instant::now();
+        let search_outcome = context.execute_search(&query).await;
+        let duration = start.elapsed().as_secs_f64();
+
+        let content = match search_outcome {
+            Ok(results) => {
+                record_web_search("success", duration, results.len() as u32);
+                if let Some(out_event) = format_web_search_call_output_event(&id) {
+                    let _ = event_tx.send(out_event).await;
                 }
+                let _ = event_tx
+                    .send(format_web_search_completed_event(&id, 0))
+                    .await;
+                format_web_search_results(&query, &results)
+            }
+            Err(e) => {
+                record_web_search("error", duration, 0);
+                error!(
+                    stage = "search_failed",
+                    call_id = %id,
+                    error = %e,
+                    "Web search execution failed"
+                );
+                // Surface error text back to the model rather than dropping it.
+                format!("Web search failed for query \"{}\": {}", query, e)
+            }
+        };
+
+        let continuation_item = ResponsesInputItem::FunctionCallOutput(FunctionCallOutput {
+            type_: FunctionCallOutputType::FunctionCallOutput,
+            id: Some(id.clone()),
+            call_id: id.clone(),
+            output: content,
+            status: None,
+        });
 
-                if !detected_tool_calls.is_empty() {
-                    let tool_call_count = detected_tool_calls.len();
-
-                    // Emit in_progress events
-                    for (idx, tool_call) in detected_tool_calls.iter().enumerate() {
-                        let event = format_web_search_in_progress_event(&tool_call.id, idx);
-                        if tx.send(Ok(event)).await.is_err() {
-                            return;
-                        }
-                    }
+        drop(event_tx);
 
-                    info!(
-                        stage = "batch_search_starting",
-                        tool_call_count = tool_call_count,
-                        iteration = iteration,
-                        "Executing {} web_search tool calls in parallel",
-                        tool_call_count
-                    );
-
-                    // Emit searching events
-                    for (idx, tool_call) in detected_tool_calls.iter().enumerate() {
-                        let event = format_web_search_searching_event(&tool_call.id, idx);
-                        if tx.send(Ok(event)).await.is_err() {
-                            return;
-                        }
-                    }
+        let result = crate::services::server_tools::ToolCallResult {
+            call_id: id,
+            continuation_items: vec![continuation_item],
+        };
 
-                    // Execute all searches in parallel
-                    let search_futures: Vec<_> = detected_tool_calls
-                        .iter()
-                        .map(|tool_call| {
-                            let ctx = context.clone();
-                            let query = tool_call.query.clone();
-                            async move {
-                                let start = Instant::now();
-                                match ctx.execute_search(&query).await {
-                                    Ok(results) => {
-                                        let count = results.len() as u32;
-                                        record_web_search(
-                                            "success",
-                                            start.elapsed().as_secs_f64(),
-                                            count,
-                                        );
-                                        Ok(results)
-                                    }
-                                    Err(e) => {
-                                        record_web_search(
-                                            "error",
-                                            start.elapsed().as_secs_f64(),
-                                            0,
-                                        );
-                                        Err(e)
-                                    }
-                                }
-                            }
-                        })
-                        .collect();
-
-                    let search_results = futures_util::future::join_all(search_futures).await;
-
-                    // Process results — on failure, synthesize an error message
-                    // for the model instead of forwarding raw internal SSE.
-                    let mut tool_results: Vec<(&WebSearchToolCall, String)> = Vec::new();
-
-                    for (tool_call, result) in detected_tool_calls.iter().zip(search_results) {
-                        match result {
-                            Ok(results) => {
-                                let content = format_web_search_results(&tool_call.query, &results);
-
-                                // Emit output_item.done with WebSearchCallOutput
-                                if let Some(sse_event) =
-                                    format_web_search_call_output_event(&tool_call.id)
-                                    && tx.send(Ok(sse_event)).await.is_err()
-                                {
-                                    return;
-                                }
+        Ok(crate::services::server_tools::ToolExecutionHandle {
+            events: Box::pin(futures_util::stream::unfold(
+                event_rx,
+                |mut rx| async move { rx.recv().await.map(|item| (item, rx)) },
+            )),
+            result: Box::pin(async move { Ok(result) }),
+        })
+    }
 
-                                // Emit completed event
-                                let output_index = detected_tool_calls
-                                    .iter()
-                                    .position(|tc| tc.id == tool_call.id)
-                                    .unwrap_or(0);
-                                let completed =
-                                    format_web_search_completed_event(&tool_call.id, output_index);
-                                if tx.send(Ok(completed)).await.is_err() {
-                                    return;
-                                }
+    fn apply_to_continuation(
+        &self,
+        payload: &mut CreateResponsesPayload,
+        results: &[crate::services::server_tools::ToolCallResult],
+        is_final_iteration: bool,
+    ) {
+        let function_outputs: Vec<ResponsesInputItem> = results
+            .iter()
+            .flat_map(|r| r.continuation_items.clone())
+            .collect();
+
+        if function_outputs.is_empty() {
+            return;
+        }
 
-                                tool_results.push((tool_call, content));
-                            }
-                            Err(e) => {
-                                error!(
-                                    stage = "search_failed",
-                                    tool_call_id = %tool_call.id,
-                                    error = %e,
-                                    "Web search execution failed"
-                                );
-                                // Provide the model with an error message instead of
-                                // dropping the result or leaking raw SSE.
-                                tool_results.push((
-                                    tool_call,
-                                    format!(
-                                        "Web search failed for query \"{}\": {}",
-                                        tool_call.query, e
-                                    ),
-                                ));
-                            }
-                        }
-                    }
+        match payload.input {
+            Some(ResponsesInput::Items(ref mut items)) => {
+                items.extend(function_outputs);
+            }
+            Some(ResponsesInput::Text(ref text)) => {
+                let text = text.clone();
+                let mut items = vec![ResponsesInputItem::EasyMessage(
+                    crate::api_types::responses::EasyInputMessage {
+                        type_: None,
+                        role: crate::api_types::responses::EasyInputMessageRole::User,
+                        content: crate::api_types::responses::EasyInputMessageContent::Text(text),
+                    },
+                )];
+                items.extend(function_outputs);
+                payload.input = Some(ResponsesInput::Items(items));
+            }
+            None => {
+                payload.input = Some(ResponsesInput::Items(function_outputs));
+            }
+        }
 
-                    // Continue with provider callback
-                    if let Some(ref callback) = context.provider_callback {
-                        let is_final_iteration = iteration == max_iterations;
-                        let continuation_payload = build_web_search_continuation_payload(
-                            &context.original_payload,
-                            &tool_results,
-                            is_final_iteration,
-                        );
-
-                        info!(
-                            stage = "continuation_sent",
-                            tool_call_count = tool_results.len(),
-                            iteration = iteration,
-                            is_final_iteration = is_final_iteration,
-                            "Sending continuation request to provider with {} web search results",
-                            tool_results.len()
-                        );
-
-                        match callback(continuation_payload).await {
-                            Ok(continuation_response) => {
-                                let (_, new_body) = continuation_response.into_parts();
-                                current_body = new_body;
-                                continue;
-                            }
-                            Err(e) => {
-                                error!(
-                                    stage = "continuation_failed",
-                                    iteration = iteration,
-                                    error = %e,
-                                    "Provider continuation request failed"
-                                );
-                                if tx.send(Ok(accumulated.freeze())).await.is_err() {
-                                    return;
-                                }
-                                record_web_search_iteration(iteration as u32, true, "error");
-                                break;
-                            }
-                        }
-                    } else {
-                        debug!(
-                            stage = "no_callback",
-                            iteration = iteration,
-                            "No provider callback configured, forwarding original response"
-                        );
-                        if tx.send(Ok(accumulated.freeze())).await.is_err() {
-                            return;
-                        }
-                        record_web_search_iteration(iteration as u32, true, "no_callback");
-                        break;
-                    }
+        // Strip web_search tool definitions on the final iteration.
+        if is_final_iteration && let Some(ref mut tools) = payload.tools {
+            let before = tools.len();
+            tools.retain(|t| !t.is_web_search());
+            tools.retain(|t| {
+                if let ResponsesToolDefinition::Function(f) = t {
+                    f.name != WebSearchToolArguments::FUNCTION_NAME
                 } else {
-                    debug!(
-                        stage = "stream_completed",
-                        iteration = iteration,
-                        "No web_search tool calls detected, stream complete"
-                    );
-                    record_web_search_iteration(iteration as u32, true, "completed");
-                    break;
+                    true
                 }
+            });
+            if tools.len() < before {
+                info!(
+                    stage = "tools_removed",
+                    removed = before - tools.len(),
+                    "Removed web_search tools on final iteration to force completion"
+                );
+            }
+            if tools.is_empty() {
+                payload.tools = None;
             }
-
-            debug!(
-                stage = "processing_completed",
-                "Web search stream processing completed"
-            );
         }
-        .instrument(web_search_span),
-    );
-
-    let stream = futures_util::stream::unfold(rx, |mut rx| async move {
-        rx.recv().await.map(|item| (item, rx))
-    });
-    let body = Body::from_stream(stream);
-
-    Response::from_parts(parts, body)
+    }
 }
 
 #[cfg(test)]
@@ -836,8 +645,8 @@ mod tests {
         let tools = payload.tools.unwrap();
         assert_eq!(tools.len(), 1);
         assert!(matches!(tools[0], ResponsesToolDefinition::Function(_)));
-        if let ResponsesToolDefinition::Function(ref v) = tools[0] {
-            assert_eq!(v.get("name").unwrap().as_str().unwrap(), "web_search");
+        if let ResponsesToolDefinition::Function(ref f) = tools[0] {
+            assert_eq!(f.name, "web_search");
         }
     }
 }
diff --git a/src/streaming/mod.rs b/src/streaming/mod.rs
index e7faf86..c539eaa 100644
--- a/src/streaming/mod.rs
+++ b/src/streaming/mod.rs
@@ -1,3 +1,5 @@
+pub mod sse_buffer;
+
 use std::{
     io,
     pin::Pin,
@@ -12,6 +14,7 @@ use std::{
 use bytes::Bytes;
 use futures_util::stream::Stream;
 use serde_json::Value;
+pub use sse_buffer::SseBuffer;
 #[cfg(feature = "server")]
 use tokio::sync::mpsc;
 use tokio::time::Sleep;
diff --git a/src/streaming/sse_buffer.rs b/src/streaming/sse_buffer.rs
new file mode 100644
index 0000000..107e0b9
--- /dev/null
+++ b/src/streaming/sse_buffer.rs
@@ -0,0 +1,163 @@
+//! Buffer for accumulating SSE (Server-Sent Events) data and extracting complete events.
+//!
+//! SSE events are delimited by double newlines (`\n\n` or `\r\n\r\n`). TCP chunks may
+//! arrive with events split across boundaries, so this buffer accumulates data until
+//! complete events can be extracted. Used by every server-executed tool that
+//! intercepts streaming Responses API output.
+
+use bytes::{Bytes, BytesMut};
+
+/// Buffer for accumulating SSE data and extracting complete events.
+///
+/// # Example
+///
+/// ```ignore
+/// let mut buffer = SseBuffer::new();
+///
+/// // First chunk arrives with partial event
+/// buffer.extend(b"data: {\"type\":");
+/// assert!(buffer.extract_complete_events().is_empty());
+///
+/// // Second chunk completes the event
+/// buffer.extend(b" \"test\"}\n\n");
+/// let events = buffer.extract_complete_events();
+/// assert_eq!(events.len(), 1);
+/// ```
+#[derive(Debug, Default)]
+pub struct SseBuffer {
+    buffer: BytesMut,
+    /// Offset within `buffer` we've already searched up to. Each
+    /// `extend` only needs to scan from here forward (minus a small
+    /// overlap for the four-byte `\r\n\r\n` delimiter). Reset to 0
+    /// after every `split_to`. Without this, an N-byte buffer with M
+    /// extracted events does M full linear scans — O(N·M).
+    scan_offset: usize,
+}
+
+impl SseBuffer {
+    /// Create a new empty SSE buffer.
+    pub fn new() -> Self {
+        Self {
+            buffer: BytesMut::new(),
+            scan_offset: 0,
+        }
+    }
+
+    /// Append data to the buffer.
+    pub fn extend(&mut self, data: &[u8]) {
+        self.buffer.extend_from_slice(data);
+    }
+
+    /// Extract all complete SSE events from the buffer.
+    ///
+    /// Returns a vector of complete events (each ending with `\n\n` or `\r\n\r\n`)
+    /// and retains any incomplete data for the next call.
+    pub fn extract_complete_events(&mut self) -> Vec<Bytes> {
+        let mut events = Vec::new();
+        while let Some(end_pos) = self.find_event_boundary() {
+            let event = self.buffer.split_to(end_pos);
+            // split_to invalidated absolute offsets; the next search
+            // starts at the front of what remains.
+            self.scan_offset = 0;
+            events.push(event.freeze());
+        }
+        events
+    }
+
+    /// Find the position of the next event boundary (end of `\n\n` or `\r\n\r\n`).
+    ///
+    /// Walks the buffer once per appended chunk by tracking
+    /// `scan_offset` — we never re-examine bytes that were already
+    /// proved not to be a boundary on a previous call.
+    fn find_event_boundary(&mut self) -> Option<usize> {
+        let bytes = &self.buffer[..];
+        // The boundary check looks at up to 4 bytes (`\r\n\r\n`), so
+        // back off the saved offset enough to cover a delimiter that
+        // straddles the previous extend boundary.
+        let start = self.scan_offset.saturating_sub(3);
+        let mut i = start;
+        while i + 1 < bytes.len() {
+            if bytes[i] == b'\n' && bytes[i + 1] == b'\n' {
+                return Some(i + 2);
+            }
+            if i + 3 < bytes.len()
+                && bytes[i] == b'\r'
+                && bytes[i + 1] == b'\n'
+                && bytes[i + 2] == b'\r'
+                && bytes[i + 3] == b'\n'
+            {
+                return Some(i + 4);
+            }
+            i += 1;
+        }
+        // Everything scanned without a hit. Remember how far we got
+        // so the next extend() only walks the new bytes.
+        self.scan_offset = bytes.len();
+        None
+    }
+
+    /// Get any remaining incomplete data in the buffer.
+    pub fn take_remaining(&mut self) -> Bytes {
+        self.scan_offset = 0;
+        self.buffer.split().freeze()
+    }
+
+    /// Check if the buffer is empty.
+    pub fn is_empty(&self) -> bool {
+        self.buffer.is_empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn extracts_single_event() {
+        let mut buf = SseBuffer::new();
+        buf.extend(b"data: hello\n\n");
+        let events = buf.extract_complete_events();
+        assert_eq!(events.len(), 1);
+        assert_eq!(&events[0][..], b"data: hello\n\n");
+        assert!(buf.is_empty());
+    }
+
+    #[test]
+    fn extracts_event_split_across_chunks() {
+        let mut buf = SseBuffer::new();
+        buf.extend(b"data: hel");
+        assert!(buf.extract_complete_events().is_empty());
+        buf.extend(b"lo\n\n");
+        let events = buf.extract_complete_events();
+        assert_eq!(events.len(), 1);
+        assert_eq!(&events[0][..], b"data: hello\n\n");
+    }
+
+    #[test]
+    fn extracts_multiple_events_in_one_call() {
+        let mut buf = SseBuffer::new();
+        buf.extend(b"data: one\n\ndata: two\n\n");
+        let events = buf.extract_complete_events();
+        assert_eq!(events.len(), 2);
+        assert_eq!(&events[0][..], b"data: one\n\n");
+        assert_eq!(&events[1][..], b"data: two\n\n");
+    }
+
+    #[test]
+    fn handles_crlf_delimiters() {
+        let mut buf = SseBuffer::new();
+        buf.extend(b"data: win\r\n\r\n");
+        let events = buf.extract_complete_events();
+        assert_eq!(events.len(), 1);
+        assert_eq!(&events[0][..], b"data: win\r\n\r\n");
+    }
+
+    #[test]
+    fn take_remaining_returns_incomplete_data() {
+        let mut buf = SseBuffer::new();
+        buf.extend(b"partial");
+        let remaining = buf.take_remaining();
+        assert_eq!(&remaining[..], b"partial");
+        assert!(buf.is_empty());
+    }
+}
diff --git a/src/usage_buffer.rs b/src/usage_buffer.rs
index 9178844..315f381 100644
--- a/src/usage_buffer.rs
+++ b/src/usage_buffer.rs
@@ -355,6 +355,8 @@ mod buffer {
                 tool_url: None,
                 tool_bytes_fetched: None,
                 tool_results_count: None,
+                tool_runtime_seconds: None,
+                tool_exit_code: None,
             }
         }
 
diff --git a/ui/package.json b/ui/package.json
index afcaa8c..e81790a 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -131,7 +131,9 @@
       "lodash": ">=4.18.1",
       "lodash-es": ">=4.18.1",
       "defu": ">=6.1.7",
-      "vite": ">=7.3.2 <8"
+      "vite": ">=7.3.2 <8",
+      "fast-uri": ">=3.1.2",
+      "@babel/plugin-transform-modules-systemjs": ">=7.29.4"
     }
   }
 }
\ No newline at end of file
diff --git a/ui/pnpm-lock.yaml b/ui/pnpm-lock.yaml
index 767ac9f..16072c2 100644
--- a/ui/pnpm-lock.yaml
+++ b/ui/pnpm-lock.yaml
@@ -26,6 +26,8 @@ overrides:
   lodash-es: '>=4.18.1'
   defu: '>=6.1.7'
   vite: '>=7.3.2 <8'
+  fast-uri: '>=3.1.2'
+  '@babel/plugin-transform-modules-systemjs': '>=7.29.4'
 
 importers:
 
@@ -581,8 +583,8 @@ packages:
     peerDependencies:
       '@babel/core': ^7.0.0-0
 
-  '@babel/plugin-transform-modules-systemjs@7.29.0':
-    resolution: {integrity: sha512-PrujnVFbOdUpw4UHiVwKvKRLMMic8+eC0CuNlxjsyZUiBjhFdPsewdXCkveh2KqBA9/waD0W1b4hXSOBQJezpQ==}
+  '@babel/plugin-transform-modules-systemjs@7.29.4':
+    resolution: {integrity: sha512-N7QmZ0xRZfjHOfZeQLJjwgX2zS9pdGHSVl/cjSGlo4dXMqvurfxXDMKY4RqEKzPozV78VMcd0lxyG13mlbKc4w==}
     engines: {node: '>=6.9.0'}
     peerDependencies:
       '@babel/core': ^7.0.0-0
@@ -3265,8 +3267,8 @@ packages:
   fast-levenshtein@2.0.6:
     resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
 
-  fast-uri@3.1.0:
-    resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==}
+  fast-uri@3.1.2:
+    resolution: {integrity: sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==}
 
   fdir@6.5.0:
     resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
@@ -6087,7 +6089,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@babel/plugin-transform-modules-systemjs@7.29.0(@babel/core@7.29.0)':
+  '@babel/plugin-transform-modules-systemjs@7.29.4(@babel/core@7.29.0)':
     dependencies:
       '@babel/core': 7.29.0
       '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
@@ -6303,7 +6305,7 @@ snapshots:
       '@babel/plugin-transform-member-expression-literals': 7.27.1(@babel/core@7.29.0)
       '@babel/plugin-transform-modules-amd': 7.27.1(@babel/core@7.29.0)
       '@babel/plugin-transform-modules-commonjs': 7.28.6(@babel/core@7.29.0)
-      '@babel/plugin-transform-modules-systemjs': 7.29.0(@babel/core@7.29.0)
+      '@babel/plugin-transform-modules-systemjs': 7.29.4(@babel/core@7.29.0)
       '@babel/plugin-transform-modules-umd': 7.27.1(@babel/core@7.29.0)
       '@babel/plugin-transform-named-capturing-groups-regex': 7.29.0(@babel/core@7.29.0)
       '@babel/plugin-transform-new-target': 7.27.1(@babel/core@7.29.0)
@@ -7935,7 +7937,7 @@ snapshots:
   ajv@8.18.0:
     dependencies:
       fast-deep-equal: 3.1.3
-      fast-uri: 3.1.0
+      fast-uri: 3.1.2
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
@@ -8953,7 +8955,7 @@ snapshots:
 
   fast-levenshtein@2.0.6: {}
 
-  fast-uri@3.1.0: {}
+  fast-uri@3.1.2: {}
 
   fdir@6.5.0(picomatch@4.0.4):
     optionalDependencies:
diff --git a/ui/src/api/openapi.json b/ui/src/api/openapi.json
index d22897a..455d950 100644
--- a/ui/src/api/openapi.json
+++ b/ui/src/api/openapi.json
@@ -17555,6 +17555,688 @@
         ]
       }
     },
+    "/api/v1/containers": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers` — list containers in the caller's org,\nnewest-first. Matches OpenAI's cursor pagination shape.",
+        "operationId": "api_v1_containers_list",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Page size, clamped to 1..=100 (default 20)",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          },
+          {
+            "name": "after",
+            "in": "query",
+            "description": "Cursor: cntr_<hex> id of the last item from a prior page",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Containers in the org"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "post": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`POST /v1/containers` — create an unattached container.",
+        "operationId": "api_v1_containers_create",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateContainerRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "The created container metadata"
+          },
+          "400": {
+            "description": "Request rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/containers/{container_id}": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers/{container_id}` — retrieve a container.",
+        "operationId": "api_v1_containers_get",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "description": "Container ID (`cntr_<hex>`)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The container metadata"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Container not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "delete": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`DELETE /v1/containers/{container_id}` — soft-delete a container.",
+        "description": "Sets `status='deleted'` and evicts the matching in-memory session\nfrom the registry so the VM is torn down on the next Arc drop.\nThe underlying `container_files` rows cascade-delete with the\ncontainer row.",
+        "operationId": "api_v1_containers_delete",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Container deleted"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Container not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/containers/{container_id}/files": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers/{container_id}/files` — list files.",
+        "operationId": "api_v1_containers_list_files",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "description": "Container ID",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Page size, clamped to 1..=1000",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Files in the container"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Container not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "post": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`POST /v1/containers/{container_id}/files` — upload a file into a\ncontainer's `/mnt/data`. Accepts either:",
+        "description": "- `multipart/form-data` with a `file` part (required) and optional\n  `path` / `content_type` parts — streams bytes directly.\n- `application/json` with `{file_id: \"file_...\"}` — copies an\n  existing Files-API upload into the container (same resolver as\n  the `file_ids` array on `POST /v1/containers`).\n\nMatches OpenAI's upload contract.",
+        "operationId": "api_v1_containers_file_upload",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Uploaded file metadata"
+          },
+          "400": {
+            "description": "Request rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Container not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "413": {
+            "description": "Payload too large",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "415": {
+            "description": "Unsupported Content-Type",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/containers/{container_id}/files/{file_id}": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers/{container_id}/files/{file_id}` — file metadata.",
+        "operationId": "api_v1_containers_file_get",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "file_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The container file metadata"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "File not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "delete": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`DELETE /v1/containers/{container_id}/files/{file_id}` — remove\na file from a container.",
+        "operationId": "api_v1_containers_file_delete",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "file_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "File deleted"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "File not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/containers/{container_id}/files/{file_id}/content": {
+      "get": {
+        "tags": [
+          "containers"
+        ],
+        "summary": "`GET /v1/containers/{container_id}/files/{file_id}/content` — raw bytes.",
+        "operationId": "api_v1_containers_file_content",
+        "parameters": [
+          {
+            "name": "container_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "file_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Raw file bytes; Content-Type comes from the row"
+          },
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "File not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
     "/api/v1/embeddings": {
       "post": {
         "tags": [
@@ -18064,40 +18746,267 @@
         ]
       }
     },
-    "/api/v1/images/variations": {
-      "post": {
+    "/api/v1/images/variations": {
+      "post": {
+        "tags": [
+          "Images"
+        ],
+        "summary": "Create image variations",
+        "description": "POST /v1/images/variations",
+        "operationId": "api_v1_images_variations",
+        "requestBody": {
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateImageVariationRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Image variations created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ImagesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/models": {
+      "get": {
+        "tags": [
+          "models"
+        ],
+        "summary": "List available models",
+        "description": "Lists all models available from all configured providers.",
+        "operationId": "api_v1_models",
+        "responses": {
+          "200": {
+            "description": "List of available models",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CombinedModelsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/responses": {
+      "post": {
+        "tags": [
+          "chat"
+        ],
+        "summary": "Create a response",
+        "description": "Creates a model response using the Responses API format.",
+        "operationId": "api_v1_responses",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateResponsesPayload"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Response object (streaming or non-streaming)"
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "502": {
+            "description": "Provider error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/responses/compact": {
+      "post": {
+        "tags": [
+          "responses"
+        ],
+        "summary": "Compact a context window via the provider's standalone compact\nendpoint.",
+        "description": "Stateless passthrough: forwards `model` + `input` (and any other\nfields the provider accepts) to the upstream `/responses/compact`\nendpoint and streams the compacted window back. Only OpenAI and\nAzure OpenAI implement this; routing to any other provider returns\n501 with `error_code = \"not_supported\"`.",
+        "operationId": "api_v1_responses_compact",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CompactRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Compacted context window"
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Provider does not support compaction",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/api/v1/responses/{response_id}": {
+      "get": {
         "tags": [
-          "Images"
+          "responses"
         ],
-        "summary": "Create image variations",
-        "description": "POST /v1/images/variations",
-        "operationId": "api_v1_images_variations",
-        "requestBody": {
-          "content": {
-            "multipart/form-data": {
-              "schema": {
-                "$ref": "#/components/schemas/CreateImageVariationRequest"
-              }
+        "summary": "`GET /v1/responses/{response_id}` — retrieve a stored response.",
+        "description": "When `?stream=true` is set, returns the persisted event log as an\nSSE stream (matching OpenAI's retrieve-with-stream behavior). The\n`starting_after` query parameter resumes replay from a specific\nsequence number so a client reconnecting after a disconnect picks\nup exactly where it stopped.",
+        "operationId": "api_v1_responses_get",
+        "parameters": [
+          {
+            "name": "response_id",
+            "in": "path",
+            "description": "ID returned by POST /v1/responses",
+            "required": true,
+            "schema": {
+              "type": "string"
             }
           },
-          "required": true
-        },
+          {
+            "name": "stream",
+            "in": "query",
+            "description": "Stream the event log as SSE",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "starting_after",
+            "in": "query",
+            "description": "Resume cursor (stream mode)",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          }
+        ],
         "responses": {
           "200": {
-            "description": "Image variations created successfully",
+            "description": "Stored response (JSON) or SSE replay when stream=true"
+          },
+          "401": {
+            "description": "Authentication required",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ImagesResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           },
-          "400": {
-            "description": "Bad request"
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           },
-          "500": {
-            "description": "Internal server error"
+          "404": {
+            "description": "Response not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "Persistence disabled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         },
         "security": [
@@ -18105,29 +19014,40 @@
             "api_key": []
           }
         ]
-      }
-    },
-    "/api/v1/models": {
-      "get": {
+      },
+      "delete": {
         "tags": [
-          "models"
+          "responses"
+        ],
+        "summary": "`DELETE /v1/responses/{response_id}` — remove a stored response.\nReturns the OpenAI-spec deletion confirmation shape.",
+        "operationId": "api_v1_responses_delete",
+        "parameters": [
+          {
+            "name": "response_id",
+            "in": "path",
+            "description": "ID of the response to delete",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
         ],
-        "summary": "List available models",
-        "description": "Lists all models available from all configured providers.",
-        "operationId": "api_v1_models",
         "responses": {
           "200": {
-            "description": "List of available models",
+            "description": "Deletion confirmation"
+          },
+          "401": {
+            "description": "Authentication required",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/CombinedModelsResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           },
-          "400": {
-            "description": "Bad request",
+          "403": {
+            "description": "Authorization denied",
             "content": {
               "application/json": {
                 "schema": {
@@ -18144,30 +19064,30 @@
         ]
       }
     },
-    "/api/v1/responses": {
+    "/api/v1/responses/{response_id}/cancel": {
       "post": {
         "tags": [
-          "chat"
+          "responses"
         ],
-        "summary": "Create a response",
-        "description": "Creates a model response using the Responses API format.",
-        "operationId": "api_v1_responses",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/CreateResponsesPayload"
-              }
+        "summary": "`POST /v1/responses/{response_id}/cancel` — cancel an in-progress\nbackground response. Per OpenAI's spec, returns 400 if the response\nis not in background mode. Idempotent for already-terminal rows.",
+        "operationId": "api_v1_responses_cancel",
+        "parameters": [
+          {
+            "name": "response_id",
+            "in": "path",
+            "description": "ID of the response to cancel",
+            "required": true,
+            "schema": {
+              "type": "string"
             }
-          },
-          "required": true
-        },
+          }
+        ],
         "responses": {
           "200": {
-            "description": "Response object (streaming or non-streaming)"
+            "description": "The cancelled response object"
           },
           "400": {
-            "description": "Bad request",
+            "description": "Response is not in background mode",
             "content": {
               "application/json": {
                 "schema": {
@@ -18176,8 +19096,28 @@
               }
             }
           },
-          "502": {
-            "description": "Provider error",
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorization denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Response not found",
             "content": {
               "application/json": {
                 "schema": {
@@ -20660,6 +21600,69 @@
           }
         }
       },
+      "CompactRequest": {
+        "type": "object",
+        "description": "Request body for `POST /v1/responses/compact`.\n\nMirrors OpenAI's `CompactResponseMethodPublicBody`: `model` is\nrequired; everything else is optional. Hadrian-specific extensions\n(`models`, `stream`, `sovereignty_requirements`) ride alongside\nbecause the gateway still routes, streams, and enforces sovereignty\nfor compaction requests just like the main `/responses` handler.",
+        "required": [
+          "model"
+        ],
+        "properties": {
+          "input": {
+            "type": "object",
+            "description": "Conversation history to compact. Accepts a plain string or the\ntyped item array used by `POST /responses`."
+          },
+          "instructions": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "System instructions threaded into the compaction prompt."
+          },
+          "model": {
+            "type": "string",
+            "description": "Model to compact with. Required by OpenAI; Hadrian also accepts\nit as the routing key when the gateway picks an upstream\nprovider."
+          },
+          "models": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "**Hadrian Extension:** alternate model list for multi-model\nrouting. The first entry the gateway resolves successfully wins."
+          },
+          "previous_response_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Continue compacting from a previously persisted response. Spec:\n`CompactResponseMethodPublicBody.previous_response_id`."
+          },
+          "prompt_cache_key": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "OpenAI prompt-cache key passthrough."
+          },
+          "sovereignty_requirements": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/SovereigntyRequirements",
+                "description": "**Hadrian Extension:** per-request data-sovereignty requirements.\nMerged with API-key-level requirements; the most restrictive\nwins."
+              }
+            ]
+          },
+          "stream": {
+            "type": "boolean",
+            "description": "**Hadrian Extension:** stream the compacted response as SSE.\nForwarded verbatim to the upstream provider when supported."
+          }
+        }
+      },
       "ComparisonFilter": {
         "type": "object",
         "description": "A comparison filter for attribute-based filtering.\n\nCompares a specific attribute key to a given value using a comparison operator.\n\n# Example\n\n```json\n{\n  \"type\": \"eq\",\n  \"key\": \"author\",\n  \"value\": \"John Doe\"\n}\n```\n\n# Supported Comparisons\n\n| Operator | Description |\n|----------|-------------|\n| `eq` | Equal to |\n| `ne` | Not equal to |\n| `gt` | Greater than |\n| `gte` | Greater than or equal to |\n| `lt` | Less than |\n| `lte` | Less than or equal to |",
@@ -20775,6 +21778,32 @@
           }
         }
       },
+      "ContainerExpiresAfter": {
+        "type": "object",
+        "description": "Container TTL hint. Mirrors OpenAI's `expires_after` shape — only\n`last_active_at` is honored today (the same anchor the operator's\nidle reaper uses), with `minutes` setting the per-container idle\nTTL.",
+        "required": [
+          "minutes"
+        ],
+        "properties": {
+          "anchor": {
+            "$ref": "#/components/schemas/ContainerExpiresAfterAnchor",
+            "description": "Anchor for the TTL countdown. Today only `\"last_active_at\"` is\nsupported; unknown anchors reject with 400."
+          },
+          "minutes": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Minutes after `anchor` when the container expires. Validated\nagainst `[features.containers].max_idle_ttl_secs / 60`.",
+            "minimum": 0
+          }
+        },
+        "additionalProperties": false
+      },
+      "ContainerExpiresAfterAnchor": {
+        "type": "string",
+        "enum": [
+          "last_active_at"
+        ]
+      },
       "ContentPart": {
         "oneOf": [
           {
@@ -21701,37 +22730,87 @@
             "type": "object",
             "description": "Stream options"
           },
-          "suffix": {
+          "suffix": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Text to append after completion"
+          },
+          "temperature": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "format": "double",
+            "description": "Sampling temperature (0.0 to 2.0)"
+          },
+          "top_p": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "format": "double",
+            "description": "Nucleus sampling probability (0.0 to 1.0)"
+          },
+          "user": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "User identifier for abuse detection"
+          }
+        }
+      },
+      "CreateContainerRequest": {
+        "type": "object",
+        "description": "Request body for `POST /v1/containers`.",
+        "properties": {
+          "expires_after": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/ContainerExpiresAfter",
+                "description": "Optional idle-TTL hint. Per OpenAI's spec: `{anchor:\n\"last_active_at\", minutes: N}`. Capped by\n`[features.containers].max_idle_ttl_secs / 60`."
+              }
+            ]
+          },
+          "file_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Files-API ids to copy into `/mnt/data` at container creation.\nSpec: `CreateContainerBody.file_ids`. Each id is resolved via\nthe Files API (same path as `input_file` parts on a response\nrequest) and the bytes are persisted into `container_files`\nso the model can read them on first attach."
+          },
+          "memory_limit": {
             "type": [
               "string",
               "null"
             ],
-            "description": "Text to append after completion"
+            "description": "Optional memory ceiling. Accepts OpenAI's `\"1g\"` / `\"512m\"`\nstrings; parsed case-insensitively. Capped by the operator's\n`[features.server_tools.shell_limits].max_mem_limit_mb`."
           },
-          "temperature": {
+          "name": {
             "type": [
-              "number",
+              "string",
               "null"
             ],
-            "format": "double",
-            "description": "Sampling temperature (0.0 to 2.0)"
+            "description": "Optional display name (max 255 chars)."
           },
-          "top_p": {
-            "type": [
-              "number",
-              "null"
-            ],
-            "format": "double",
-            "description": "Nucleus sampling probability (0.0 to 1.0)"
+          "network_policy": {
+            "type": "object",
+            "description": "Optional network policy (same shape as\n`tools.shell.environment.network_policy`). OpenAI types this as\na `oneOf { Disabled, Allowlist }` discriminated by `type`;\nHadrian represents it as a single flat object that validates\nthe same constraints at request resolution, so the schema is\nrendered as an opaque `object` to avoid spurious diffs."
           },
-          "user": {
-            "type": [
-              "string",
-              "null"
-            ],
-            "description": "User identifier for abuse detection"
+          "skills": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Skills to mount whenever a session is booted against this\ncontainer. Matches OpenAI's typed shape — see\n[`crate::api_types::RequestSkill`]."
           }
-        }
+        },
+        "additionalProperties": false
       },
       "CreateConversation": {
         "type": "object",
@@ -22702,6 +23781,13 @@
             ],
             "description": "Run in background"
           },
+          "context_management": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Context management directives. Forwarded verbatim to providers\nthat support server-side compaction (OpenAI, Azure OpenAI); for\nothers the field is ignored at the adapter layer. See OpenAI's\ncompaction guide for the schema; the canonical entry is\n`{\"type\": \"compaction\", \"compact_threshold\": <tokens>}`."
+          },
           "frequency_penalty": {
             "type": [
               "number",
@@ -22816,6 +23902,13 @@
             "type": "object",
             "description": "Service tier"
           },
+          "skills": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "**Hadrian Extension:** Skills to mount into the shell-tool\nsession. Hadrian treats skills as a top-level request field\nrather than threading them through the OpenAI shell-tool\n`environment` block, so they're accepted on every responses\nrequest regardless of whether the upstream provider has its own\nskills surface.\n\nMirrors OpenAI's typed shape — each entry is either a reference\nto a stored skill or an inline bundle:\n\n```json\n[\n  {\"type\": \"skill_reference\", \"skill_id\": \"<uuid>\", \"version\": \"latest\"},\n  {\"type\": \"inline\", \"name\": \"extract-csv\", \"description\": \"...\",\n   \"source\": {\"type\": \"base64\", \"media_type\": \"text/markdown\", \"data\": \"...\"}}\n]\n```\n\nFor `skill_reference`, `skill_id` is a Hadrian skill UUID\nowned by the caller's org. `version` is optional; only\n`\"latest\"` (the default) is supported today — pinned versions\nreject with 400 until version-pinning lands.\n\nFor `inline`, the decoded `source.data` is mounted as an\nephemeral skill bundle: `text/markdown` is treated as the\n`SKILL.md` content; other media types are rejected today.\n\nEach resolved skill's `SKILL.md` is prepended to `instructions`\nso the model knows the skill is available; all skill files are\nmaterialized under `/skills/<skill_id>/` inside the sandbox."
+          },
           "sovereignty_requirements": {
             "oneOf": [
               {
@@ -22855,9 +23948,12 @@
             "description": "Tool choice configuration"
           },
           "tools": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
-              "type": "object"
+              "$ref": "#/components/schemas/ResponsesToolDefinition"
             },
             "description": "Available tools"
           },
@@ -25677,6 +26773,61 @@
           }
         }
       },
+      "FileSearchTool": {
+        "type": "object",
+        "description": "File search tool for RAG in the Responses API.\nEnables semantic search across vector stores.",
+        "required": [
+          "type",
+          "vector_store_ids"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "filters": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Metadata filters to apply to the search."
+          },
+          "max_num_results": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Maximum number of results to return.",
+            "minimum": 0
+          },
+          "ranking_options": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Ranking options for controlling result relevance."
+          },
+          "type": {
+            "$ref": "#/components/schemas/FileSearchToolType"
+          },
+          "vector_store_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Vector store IDs to search across."
+          }
+        }
+      },
+      "FileSearchToolType": {
+        "type": "string",
+        "enum": [
+          "file_search"
+        ]
+      },
       "FileStatus": {
         "type": "string",
         "description": "File upload status (OpenAI Files API compatible)\n\nTracks the state of a file uploaded via the Files API.\nNote: This status is **deprecated** in OpenAI's API but still returned for compatibility.\n\n## State Transitions\n\n```text\n┌──────────┐     validation      ┌───────────┐\n│ uploaded │ ──────────────────▶ │ processed │\n└──────────┘     success         └───────────┘\n      │\n      │ validation failed\n      ▼\n┌──────────┐\n│  error   │\n└──────────┘\n```\n\n- `uploaded`: File received and stored, initial validation pending\n- `processed`: File validated and ready for use (e.g., adding to vector stores)\n- `error`: File validation failed (see `status_details` for reason)\n\n## Important\n\nThis is the **file upload** status, not the vector store processing status.\nWhen a file is added to a vector store, its processing status is tracked\nseparately via `VectorStoreFileStatus`.",
@@ -25747,6 +26898,64 @@
           }
         }
       },
+      "FunctionTool": {
+        "allOf": [
+          {
+            "type": "object",
+            "description": "Extra fields the gateway forwards verbatim (e.g. MCP `annotations`\non rewritten function tools). Not part of OpenAI's documented\nshape; preserved here so internal rewrite pipelines can attach\nprovider-specific metadata without losing it through round-trips."
+          },
+          {
+            "type": "object",
+            "required": [
+              "name"
+            ],
+            "properties": {
+              "defer_loading": {
+                "type": [
+                  "boolean",
+                  "null"
+                ],
+                "description": "Delay loading the function definition until the model discovers it\nvia tool search. On a caller-supplied function tool this is\nforwarded to the provider and treated as opaque. On the per-tool\nfunction tools the MCP rewrite synthesizes it is only set on the\nnative-passthrough path (`McpTool::defer_loading_passthrough` on an\nOpenAI/Azure upstream); the default `hadrian_hosted` path defers via\nHadrian-side tool search instead and does not set this flag."
+              },
+              "description": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Human-readable description surfaced to the model."
+              },
+              "name": {
+                "type": "string",
+                "description": "Function name. Must be `[A-Za-z0-9_-]{1,64}`."
+              },
+              "parameters": {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "description": "JSON Schema describing the function's parameters. Forwarded\nverbatim to the provider; the gateway treats it as opaque."
+              },
+              "strict": {
+                "type": [
+                  "boolean",
+                  "null"
+                ],
+                "description": "When true, the model is constrained to emit arguments that\nstrictly conform to `parameters`."
+              },
+              "type": {
+                "$ref": "#/components/schemas/FunctionToolType"
+              }
+            }
+          }
+        ],
+        "description": "Custom function tool. **Schema-only**: at the wire level the gateway\nkeeps `Function` as an opaque `serde_json::Value` so existing\nrewrite pipelines (web_search → function, shell → function, MCP →\nper-tool function) can construct/inspect it via JSON without\ntouching a typed struct. This struct exists purely to give the\nOpenAPI spec a typed shape for the function-tool variant."
+      },
+      "FunctionToolType": {
+        "type": "string",
+        "enum": [
+          "function"
+        ]
+      },
       "HealthStatus": {
         "type": "string",
         "description": "Status of a provider's health.",
@@ -26470,29 +27679,214 @@
               }
             ]
           },
-          "owner_id": {
+          "owner_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "uuid",
+            "description": "**Hadrian Extension:** Owner ID for multi-tenancy.\nWhen omitted along with `owner_type`, returns all accessible vector stores."
+          },
+          "owner_type": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Owner type for multi-tenancy (organization, team, project, or user).\nWhen omitted along with `owner_id`, returns all accessible vector stores."
+          }
+        }
+      },
+      "LogicalOperator": {
+        "type": "string",
+        "description": "Logical operators for compound filters.",
+        "enum": [
+          "and",
+          "or"
+        ]
+      },
+      "McpAllowedTools": {
+        "oneOf": [
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          {
+            "$ref": "#/components/schemas/McpToolFilter"
+          }
+        ],
+        "description": "Tool whitelist for an `McpTool`. Untagged so OpenAI's accepted\nshorthand `[\"tool_a\", \"tool_b\"]` round-trips as the `List` variant\nand the `{tool_names: [...], read_only?: bool}` object form picks\nup extra knobs."
+      },
+      "McpApprovalFilter": {
+        "type": "object",
+        "description": "Object form of `require_approval`. `always` lists tools that must\nbe gated; `never` lists tools that bypass the gate. Tools not named\nin either fall back to the default (gate). Mirrors OpenAI's\n`MCPToolApprovalFilter`.",
+        "properties": {
+          "always": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/McpToolFilter",
+                "description": "Tools that require approval."
+              }
+            ]
+          },
+          "never": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/McpToolFilter",
+                "description": "Tools exempt from approval."
+              }
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
+      "McpApprovalMode": {
+        "type": "string",
+        "enum": [
+          "always",
+          "never"
+        ]
+      },
+      "McpRequireApproval": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/McpApprovalMode"
+          },
+          {
+            "$ref": "#/components/schemas/McpApprovalFilter"
+          }
+        ],
+        "description": "Approval gating shape for the MCP tool. Accepts the spec's string\nshorthand (`\"always\"` / `\"never\"`) or an object with `always` / `never`\nfilters that opt subsets in or out of the approval gate."
+      },
+      "McpTool": {
+        "type": "object",
+        "description": "MCP tool — lets the model invoke tools exposed by a remote Model\nContext Protocol server (Atlassian, Notion, GitHub, HuggingFace, …).\n\nMirrors OpenAI's `mcp` tool. Two mutually-exclusive shapes: pointing\nat a remote server via `server_url`, or pointing at an OpenAI\nfirst-party connector via `connector_id`. The caller supplies any\n`authorization` bearer token directly on the tool entry; Hadrian\ndoes not persist or rewrite it.\n\nUnder `mode = passthrough_openai` the tool entry is forwarded\nverbatim to OpenAI / Azure OpenAI, and non-OpenAI providers reject\nwith `mcp_passthrough_unsupported_provider`. Under\n`mode = hadrian_hosted` the gateway runs the MCP client loop itself\nvia `rmcp` and rewrites the tool into per-tool function tools, so\nany provider can drive it.",
+        "required": [
+          "type",
+          "server_label"
+        ],
+        "properties": {
+          "allowed_tools": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/McpAllowedTools",
+                "description": "Restrict which tools from the server are exposed to the model.\nAccepts either a flat list of tool names or an object form for\nforward-compat with extra knobs."
+              }
+            ]
+          },
+          "authorization": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Bearer / OAuth access token. The caller obtains this\nout-of-band (OpenAI's API does not run the OAuth dance for the\nremote server, and neither does Hadrian). Sent verbatim to the\nMCP server's `Authorization` header. Hadrian does not persist\nthe value — clients must include it on every request."
+          },
+          "connector_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Identifier for an OpenAI-maintained connector\n(e.g. `connector_googlecalendar`). Mutually exclusive with\n`server_url`. Only usable under `mode = passthrough_openai`;\n`hadrian_hosted` cannot reach OpenAI's connector registry."
+          },
+          "defer_loading": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Delay loading the tool definitions until the model discovers them\nvia tool search, rather than dumping the whole catalog into the\nprompt. Forwarded verbatim under `passthrough_openai` (OpenAI runs\nits native tool search). Under `hadrian_hosted` deferral is\nrealized by **Hadrian-side tool search**: the gateway exposes a\nsingle `tool_search` function tool, keeps the catalog server-side,\nand lazily injects matched per-tool function definitions as the\nmodel discovers them — so deferral works behind every provider,\nnot just OpenAI. The upstream `tools/list` catalog fetch always\nruns eagerly at rewrite time (it's needed to know what's\nsearchable); only the per-tool definitions are deferred."
+          },
+          "defer_loading_passthrough": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** opt out of Hadrian-side tool search and let\nthe upstream handle `defer_loading` natively. Only honored when\n`defer_loading` is set, the gateway is in `hadrian_hosted` mode,\nand the resolved provider is OpenAI / Azure OpenAI (which\nimplement native tool search); rejected with HTTP 400 otherwise.\nDefault/`None` keeps the provider-agnostic Hadrian-side path."
+          },
+          "headers": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Additional HTTP headers sent with every JSON-RPC call to the\nMCP server. Useful for region or workspace selectors.",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "propertyNames": {
+              "type": "string"
+            }
+          },
+          "require_approval": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/McpRequireApproval",
+                "description": "Approval gate. Spec default is `\"always\"` when omitted — under\n`hadrian_hosted` the executor enforces that default; under\n`passthrough_openai` the field is forwarded verbatim and OpenAI\napplies its own default."
+              }
+            ]
+          },
+          "server_description": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Human-readable description surfaced to the model."
+          },
+          "server_label": {
+            "type": "string",
+            "description": "Stable identifier surfaced in `mcp_list_tools` and `mcp_call`\nitems. Required even when using `connector_id` so output items\nhave a consistent label."
+          },
+          "server_url": {
             "type": [
               "string",
               "null"
             ],
-            "format": "uuid",
-            "description": "**Hadrian Extension:** Owner ID for multi-tenancy.\nWhen omitted along with `owner_type`, returns all accessible vector stores."
+            "description": "URL of the remote MCP server (Streamable HTTP). Mutually\nexclusive with `connector_id`."
           },
-          "owner_type": {
+          "type": {
+            "$ref": "#/components/schemas/McpToolType"
+          }
+        }
+      },
+      "McpToolFilter": {
+        "type": "object",
+        "description": "Spec `MCPToolFilter`: a set of tool names plus an optional\n`read_only` predicate that matches tools whose MCP `readOnlyHint`\nannotation is true. Either field is optional; both are AND-combined\n(tool name must be in `tool_names` *and* `read_only` must match if set).",
+        "properties": {
+          "read_only": {
             "type": [
-              "string",
+              "boolean",
               "null"
             ],
-            "description": "**Hadrian Extension:** Owner type for multi-tenancy (organization, team, project, or user).\nWhen omitted along with `owner_id`, returns all accessible vector stores."
+            "description": "Restrict to tools whose annotation `readOnlyHint == true`.\n`None` means don't filter on this property."
+          },
+          "tool_names": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "Tool names to include. Omit to match any name."
           }
-        }
+        },
+        "additionalProperties": false
       },
-      "LogicalOperator": {
+      "McpToolType": {
         "type": "string",
-        "description": "Logical operators for compound filters.",
         "enum": [
-          "and",
-          "or"
+          "mcp"
         ]
       },
       "MeResponse": {
@@ -29111,6 +30505,38 @@
         ],
         "description": "Response format for chat completion"
       },
+      "ResponsesToolDefinition": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/FileSearchTool"
+          },
+          {
+            "$ref": "#/components/schemas/WebSearchPreviewTool"
+          },
+          {
+            "$ref": "#/components/schemas/WebSearchPreview20250311Tool"
+          },
+          {
+            "$ref": "#/components/schemas/WebSearchTool"
+          },
+          {
+            "$ref": "#/components/schemas/WebSearch20250826Tool"
+          },
+          {
+            "$ref": "#/components/schemas/ShellTool"
+          },
+          {
+            "$ref": "#/components/schemas/McpTool"
+          },
+          {
+            "$ref": "#/components/schemas/ToolSearchTool"
+          },
+          {
+            "$ref": "#/components/schemas/FunctionTool"
+          }
+        ],
+        "description": "Tool definition - one of the supported tool variants. The schema\nemits a `oneOf` over the variants; each variant constrains its\n`type` field to a single literal, so consumers (and the OpenAPI\nconformance script) can match variants by `type`. The `Function`\nvariant stays as an opaque `serde_json::Value` at the data level\nso existing rewrite pipelines (web_search → function, shell →\nfunction, MCP → per-tool function) keep constructing it via JSON;\nthe schema reports it as a [`FunctionTool`] for documentation."
+      },
       "RollbackOrgRbacPolicy": {
         "type": "object",
         "description": "Request to rollback an RBAC policy to a previous version.",
@@ -29479,6 +30905,56 @@
           }
         }
       },
+      "ShellNetworkPolicy": {
+        "type": "object",
+        "description": "Per-domain egress policy. Matches OpenAI's `network_policy` shape:\n`{ \"type\": \"allowlist\", \"allowed_domains\": [...], \"domain_secrets\": [...] }`.",
+        "properties": {
+          "allowed_domains": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Hostnames or hostname patterns (`*.example.com`) the container\nmay make outbound requests to. Must be a subset of the\noperator's `allowed_egress_hosts`."
+          },
+          "domain_secrets": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Secrets injected for outbound traffic. Accepts either OpenAI's\ninline `{domain, name, value}` form or Hadrian's safer\n`{placeholder, allowed_domains}` reference form — see\n[`ShellDomainSecret`]."
+          },
+          "type": {
+            "type": "string",
+            "description": "Policy kind. Only `allowlist` is supported today; the field is\nhere for forward compatibility with future OpenAI additions."
+          }
+        },
+        "additionalProperties": false
+      },
+      "ShellTool": {
+        "type": "object",
+        "description": "Shell tool — instructs the model that it may call `shell` and the\ngateway will execute the resulting commands in a sandboxed runtime\n(or forward them to the upstream provider's hosted runtime if\nconfigured for passthrough).\n\nMirrors OpenAI's `shell` tool definition for GPT-5.2+. The\n`environment` block lets a caller request narrower constraints than\nthe operator's defaults — anything outside those defaults is\nrejected with `400` at request validation.",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "environment": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Runtime environment overrides. Every field is a **subset** of\nwhat `[features.server_tools.shell_limits]` permits; requests\nasking for more than the operator allows are rejected."
+          },
+          "type": {
+            "$ref": "#/components/schemas/ShellToolType"
+          }
+        }
+      },
+      "ShellToolType": {
+        "type": "string",
+        "enum": [
+          "shell"
+        ]
+      },
       "SimulateContext": {
         "type": "object",
         "description": "Context information for policy simulation",
@@ -31648,6 +33124,69 @@
           }
         }
       },
+      "ToolSearchExecution": {
+        "type": "string",
+        "description": "Whether a tool search ran on the server (Hadrian / OpenAI) or was\ndelegated to the client (BYOT). Hadrian only emits `Server`. Mirrors\nOpenAI's `ToolSearchExecutionType`.",
+        "enum": [
+          "server",
+          "client"
+        ]
+      },
+      "ToolSearchRankerKind": {
+        "type": "string",
+        "description": "Ranking strategy for Hadrian-side tool search over a deferred MCP\ncatalog. `Hybrid` fuses semantic + lexical relevance (RRF); `Semantic`\nis embedding cosine only; `Lexical` is token/substring scoring with no\nembedding dependency.",
+        "enum": [
+          "hybrid",
+          "semantic",
+          "lexical"
+        ]
+      },
+      "ToolSearchTool": {
+        "type": "object",
+        "description": "`tool_search` tool — OpenAI's `ToolSearchToolParam`. Configures\ndiscovery of deferred tools (`defer_loading: true`). Under\n`hadrian_hosted` a caller need not supply this: Hadrian synthesizes\nits own search tool whenever a deferred MCP server is present. A\ncaller may still include the entry to set the Hadrian-extension\n`ranker`; Hadrian reads that override and does not forward the entry\nto the model.",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "description": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Description shown to the model for a client-executed search tool."
+          },
+          "execution": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Whether the search executes server-side (hosted) or client-side\n(BYOT). Hadrian only supports server-side execution."
+          },
+          "parameters": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Parameter schema for a client-executed search tool. Opaque."
+          },
+          "ranker": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** per-request override of the ranking\nstrategy for Hadrian-side tool search. Takes precedence over the\n`[features.mcp.tool_search].ranker` deployment default. Requesting\n`semantic` on a deployment without an embedding provider returns\nHTTP 400 (`tool_search_ranker_unavailable`)."
+          },
+          "type": {
+            "$ref": "#/components/schemas/ToolSearchToolType"
+          }
+        }
+      },
+      "ToolSearchToolType": {
+        "type": "string",
+        "enum": [
+          "tool_search"
+        ]
+      },
       "ToolType": {
         "type": "string",
         "description": "Tool type",
@@ -34648,6 +36187,120 @@
           }
         }
       },
+      "WebSearch20250826Tool": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "filters": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "search_context_size": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/WebSearch20250826ToolType"
+          },
+          "user_location": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "WebSearch20250826ToolType": {
+        "type": "string",
+        "enum": [
+          "web_search_2025_08_26"
+        ]
+      },
+      "WebSearchPreview20250311Tool": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "search_context_size": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/WebSearchPreview20250311ToolType"
+          },
+          "user_location": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "WebSearchPreview20250311ToolType": {
+        "type": "string",
+        "enum": [
+          "web_search_preview_2025_03_11"
+        ]
+      },
+      "WebSearchPreviewTool": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "search_context_size": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/WebSearchPreviewToolType"
+          },
+          "user_location": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "WebSearchPreviewToolType": {
+        "type": "string",
+        "enum": [
+          "web_search_preview"
+        ]
+      },
       "WebSearchRequest": {
         "type": "object",
         "required": [
@@ -34705,6 +36358,48 @@
             "type": "string"
           }
         }
+      },
+      "WebSearchTool": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "cache_control": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "**Hadrian Extension:** Cache control for prompt caching (Anthropic/Bedrock)"
+          },
+          "filters": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "search_context_size": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/WebSearchToolType"
+          },
+          "user_location": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "WebSearchToolType": {
+        "type": "string",
+        "enum": [
+          "web_search"
+        ]
       }
     },
     "securitySchemes": {
diff --git a/ui/src/components/AgentToolSettings/AgentToolSettings.stories.tsx b/ui/src/components/AgentToolSettings/AgentToolSettings.stories.tsx
new file mode 100644
index 0000000..01f4470
--- /dev/null
+++ b/ui/src/components/AgentToolSettings/AgentToolSettings.stories.tsx
@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { AgentToolSettings } from "./AgentToolSettings";
+
+const meta: Meta<typeof AgentToolSettings> = {
+  title: "Chat/AgentToolSettings",
+  component: AgentToolSettings,
+  decorators: [
+    (Story) => (
+      <div className="p-4 w-72">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof AgentToolSettings>;
+
+export const Default: Story = {};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
diff --git a/ui/src/components/AgentToolSettings/AgentToolSettings.tsx b/ui/src/components/AgentToolSettings/AgentToolSettings.tsx
new file mode 100644
index 0000000..cf3cce7
--- /dev/null
+++ b/ui/src/components/AgentToolSettings/AgentToolSettings.tsx
@@ -0,0 +1,103 @@
+/**
+ * AgentToolSettings — container configuration for the "Agent (Shell)" tool.
+ *
+ * Rendered as the tool's settings flyout in the ToolsBar. Enabling/disabling
+ * the tool is handled by the ToolsBar toggle (the `agent` tool id); this panel
+ * configures the container a *new* conversation provisions. The conversation
+ * then reuses that container until it expires (handled in useChat), so there's
+ * no manual container picker. Changing a setting auto-enables the tool via
+ * `onConfigured`, mirroring how picking a sub-agent model enables `sub_agent`.
+ */
+
+import { Input } from "@/components/Input/Input";
+import { Textarea } from "@/components/Textarea/Textarea";
+import { NumberInput } from "@/components/NumberInput/NumberInput";
+import { FormField } from "@/components/FormField/FormField";
+import {
+  useChatUIStore,
+  useAgentMemoryLimit,
+  useAgentExpiresAfterMinutes,
+  useAgentAllowedDomains,
+} from "@/stores/chatUIStore";
+
+export interface AgentToolSettingsProps {
+  disabled?: boolean;
+  /** Called when the user configures the agent, so the tool is enabled. */
+  onConfigured?: () => void;
+}
+
+export function AgentToolSettings({ disabled = false, onConfigured }: AgentToolSettingsProps) {
+  const memoryLimit = useAgentMemoryLimit();
+  const expiresAfterMinutes = useAgentExpiresAfterMinutes();
+  const allowedDomains = useAgentAllowedDomains();
+
+  const setMemoryLimit = useChatUIStore((s) => s.setAgentMemoryLimit);
+  const setExpiresAfterMinutes = useChatUIStore((s) => s.setAgentExpiresAfterMinutes);
+  const setAllowedDomains = useChatUIStore((s) => s.setAgentAllowedDomains);
+
+  const touch = () => onConfigured?.();
+
+  return (
+    <div className="w-full space-y-3">
+      <p className="text-xs text-muted-foreground">
+        Runs shell commands in a container that persists for the whole conversation, until it
+        expires.
+      </p>
+
+      <FormField
+        label="Memory limit"
+        htmlFor="agent-memory-limit"
+        helpText="Optional, e.g. 512m or 1g. Blank uses the default."
+      >
+        <Input
+          id="agent-memory-limit"
+          className="w-full"
+          value={memoryLimit}
+          disabled={disabled}
+          onChange={(e) => {
+            setMemoryLimit(e.target.value);
+            touch();
+          }}
+          placeholder="default"
+        />
+      </FormField>
+
+      <FormField
+        label="Idle timeout (minutes)"
+        htmlFor="agent-idle-ttl"
+        helpText="Optional. Container is reaped after this long without activity."
+      >
+        <NumberInput
+          id="agent-idle-ttl"
+          className="w-full"
+          value={expiresAfterMinutes ?? 0}
+          onChange={(v) => {
+            setExpiresAfterMinutes(v > 0 ? v : null);
+            touch();
+          }}
+          min={0}
+          max={1440}
+        />
+      </FormField>
+
+      <FormField
+        label="Allowed egress domains"
+        htmlFor="agent-allowed-domains"
+        helpText="Comma-separated. `*` allows any host (capped by the operator); blank means deny-all."
+      >
+        <Textarea
+          id="agent-allowed-domains"
+          className="w-full"
+          value={allowedDomains}
+          disabled={disabled}
+          onChange={(e) => {
+            setAllowedDomains(e.target.value);
+            touch();
+          }}
+          placeholder="*"
+          rows={2}
+        />
+      </FormField>
+    </div>
+  );
+}
diff --git a/ui/src/components/Artifact/Artifact.tsx b/ui/src/components/Artifact/Artifact.tsx
index 0f291c7..783a6f0 100644
--- a/ui/src/components/Artifact/Artifact.tsx
+++ b/ui/src/components/Artifact/Artifact.tsx
@@ -16,7 +16,17 @@
  */
 
 import { memo } from "react";
-import { Code2, Table2, Image, BarChart3, Globe, Bot, Search, AlertCircle } from "lucide-react";
+import {
+  Code2,
+  Table2,
+  Image,
+  BarChart3,
+  Globe,
+  Bot,
+  Search,
+  FileText,
+  AlertCircle,
+} from "lucide-react";
 
 import type {
   Artifact as ArtifactType,
@@ -31,6 +41,7 @@ import { ChartArtifact } from "./ChartArtifact";
 import { HtmlArtifact } from "./HtmlArtifact";
 import { AgentArtifact } from "./AgentArtifact";
 import { FileSearchArtifact } from "./FileSearchArtifact";
+import { ContainerFileArtifact } from "./ContainerFileArtifact";
 
 export interface ArtifactProps {
   artifact: ArtifactType;
@@ -54,6 +65,8 @@ function ArtifactIcon({ type, className }: { type: ArtifactKind; className?: str
       return <Bot className={className} />;
     case "file_search":
       return <Search className={className} />;
+    case "container_file":
+      return <FileText className={className} />;
     default:
       return <Code2 className={className} />;
   }
@@ -76,6 +89,8 @@ function getArtifactLabel(type: ArtifactKind): string {
       return "Sub-Agent";
     case "file_search":
       return "Knowledge Base Search";
+    case "container_file":
+      return "Container File";
     default:
       return "Output";
   }
@@ -100,6 +115,8 @@ function ArtifactComponent({ artifact, className }: ArtifactProps) {
         return <AgentArtifact artifact={artifact} />;
       case "file_search":
         return <FileSearchArtifact artifact={artifact} />;
+      case "container_file":
+        return <ContainerFileArtifact artifact={artifact} />;
       default:
         return (
           <div className="flex items-center gap-2 text-sm text-muted-foreground p-4">
diff --git a/ui/src/components/Artifact/ContainerFileArtifact.stories.tsx b/ui/src/components/Artifact/ContainerFileArtifact.stories.tsx
new file mode 100644
index 0000000..0bf0f65
--- /dev/null
+++ b/ui/src/components/Artifact/ContainerFileArtifact.stories.tsx
@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { http, HttpResponse } from "msw";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ContainerFileArtifact } from "./ContainerFileArtifact";
+import { AuthProvider } from "@/auth";
+import type { Artifact } from "@/components/chat-types";
+
+const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+
+// 1x1 transparent PNG.
+const PNG_BYTES = Uint8Array.from(
+  atob(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
+  ),
+  (c) => c.charCodeAt(0)
+);
+
+const imageArtifact: Artifact = {
+  id: "cfile-1",
+  type: "container_file",
+  role: "output",
+  title: "chart.png",
+  data: {
+    containerId: "cntr_abc",
+    fileId: "cfile_1",
+    filename: "chart.png",
+    contentType: "image/png",
+    bytes: 1024,
+  },
+};
+
+const fileArtifact: Artifact = {
+  id: "cfile-2",
+  type: "container_file",
+  role: "output",
+  title: "results.csv",
+  data: {
+    containerId: "cntr_abc",
+    fileId: "cfile_2",
+    filename: "results.csv",
+    contentType: "text/csv",
+    bytes: 20480,
+  },
+};
+
+const meta: Meta<typeof ContainerFileArtifact> = {
+  title: "Artifact/ContainerFileArtifact",
+  component: ContainerFileArtifact,
+  decorators: [
+    (Story) => (
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider>
+          <div className="max-w-md rounded-lg border">
+            <Story />
+          </div>
+        </AuthProvider>
+      </QueryClientProvider>
+    ),
+  ],
+  parameters: {
+    msw: {
+      handlers: [
+        http.get("*/files/cfile_1/content", () =>
+          HttpResponse.arrayBuffer(PNG_BYTES.buffer, {
+            headers: { "Content-Type": "image/png" },
+          })
+        ),
+        http.get("*/files/cfile_2/content", () => HttpResponse.text("a,b\n1,2\n")),
+      ],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ContainerFileArtifact>;
+
+export const ImageInline: Story = { args: { artifact: imageArtifact } };
+export const FileDownload: Story = { args: { artifact: fileArtifact } };
diff --git a/ui/src/components/Artifact/ContainerFileArtifact.tsx b/ui/src/components/Artifact/ContainerFileArtifact.tsx
new file mode 100644
index 0000000..dd93409
--- /dev/null
+++ b/ui/src/components/Artifact/ContainerFileArtifact.tsx
@@ -0,0 +1,164 @@
+/**
+ * ContainerFileArtifact - Renders a file the shell tool wrote to /mnt/data.
+ *
+ * The bytes aren't inlined in the artifact; we lazily fetch them from the
+ * authed container content endpoint. Images render inline (with download);
+ * everything else renders as a download chip. The `<img>` element can't send
+ * the bearer token, so images go through an authed fetch → object URL.
+ */
+
+import { memo, useState, useEffect, useCallback } from "react";
+import { Download, FileText, Loader2 } from "lucide-react";
+
+import type { Artifact, ContainerFileArtifactData } from "@/components/chat-types";
+import { Button } from "@/components/Button/Button";
+import { useAuth } from "@/auth";
+import { formatBytes } from "@/utils/formatters";
+import { formatApiError } from "@/utils/formatApiError";
+
+export interface ContainerFileArtifactProps {
+  artifact: Artifact;
+  className?: string;
+}
+
+function isContainerFileData(data: unknown): data is ContainerFileArtifactData {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    typeof (data as ContainerFileArtifactData).containerId === "string" &&
+    typeof (data as ContainerFileArtifactData).fileId === "string"
+  );
+}
+
+function ContainerFileArtifactComponent({ artifact }: ContainerFileArtifactProps) {
+  const { token } = useAuth();
+  const data = isContainerFileData(artifact.data) ? artifact.data : null;
+  const isImage = !!data?.contentType?.startsWith("image/");
+
+  const [objectUrl, setObjectUrl] = useState<string | null>(null);
+  const [downloading, setDownloading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const contentUrl = data
+    ? `/api/v1/containers/${data.containerId}/files/${data.fileId}/content`
+    : "";
+
+  const fetchBlob = useCallback(async (): Promise<Blob> => {
+    const res = await fetch(contentUrl, {
+      headers: token ? { Authorization: `Bearer ${token}` } : {},
+    });
+    if (!res.ok) throw new Error(`Failed to load file (${res.status})`);
+    return res.blob();
+  }, [contentUrl, token]);
+
+  // Eagerly load images so they render inline; other files load on download.
+  useEffect(() => {
+    if (!data || !isImage) return;
+    let url: string | null = null;
+    let cancelled = false;
+    (async () => {
+      try {
+        const blob = await fetchBlob();
+        if (cancelled) return;
+        url = URL.createObjectURL(blob);
+        setObjectUrl(url);
+      } catch (err) {
+        if (!cancelled) setError(formatApiError(err));
+      }
+    })();
+    return () => {
+      cancelled = true;
+      if (url) URL.revokeObjectURL(url);
+    };
+  }, [data, isImage, fetchBlob]);
+
+  const handleDownload = useCallback(async () => {
+    if (!data) return;
+    setDownloading(true);
+    try {
+      const blob = await fetchBlob();
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = data.filename;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+    } catch (err) {
+      setError(formatApiError(err));
+    } finally {
+      setDownloading(false);
+    }
+  }, [data, fetchBlob]);
+
+  if (!data) {
+    return <div className="p-4 text-sm text-muted-foreground">Invalid container file artifact</div>;
+  }
+
+  if (isImage) {
+    return (
+      <div className="relative group p-2">
+        {error ? (
+          <div className="p-4 text-sm text-muted-foreground">{error}</div>
+        ) : objectUrl ? (
+          <>
+            <Button
+              variant="secondary"
+              size="sm"
+              className="absolute right-3 top-3 h-7 w-7 p-0 opacity-0 group-hover:opacity-100 transition-opacity"
+              onClick={handleDownload}
+              aria-label={`Download ${data.filename}`}
+            >
+              <Download className="h-3.5 w-3.5" />
+            </Button>
+            <img
+              src={objectUrl}
+              alt={data.filename}
+              className="rounded max-w-full max-h-[400px] mx-auto"
+            />
+            <p className="mt-1 text-center text-xs text-muted-foreground font-mono">
+              {data.filename}
+            </p>
+          </>
+        ) : (
+          <div className="flex items-center justify-center gap-2 p-6 text-sm text-muted-foreground">
+            <Loader2 className="h-4 w-4 animate-spin" />
+            Loading {data.filename}…
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  // Non-image: download chip.
+  return (
+    <div className="flex items-center gap-3 p-3">
+      <FileText className="h-5 w-5 text-muted-foreground shrink-0" />
+      <div className="min-w-0 flex-1">
+        <p className="text-sm font-medium truncate font-mono">{data.filename}</p>
+        <p className="text-xs text-muted-foreground">
+          {data.contentType ?? "file"}
+          {typeof data.bytes === "number" ? ` · ${formatBytes(data.bytes)}` : ""}
+        </p>
+        {error && <p className="text-xs text-destructive mt-0.5">{error}</p>}
+      </div>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={handleDownload}
+        disabled={downloading}
+        aria-label={`Download ${data.filename}`}
+      >
+        {downloading ? (
+          <Loader2 className="h-4 w-4 animate-spin" />
+        ) : (
+          <Download className="h-4 w-4" />
+        )}
+        <span className="ml-1.5">Download</span>
+      </Button>
+    </div>
+  );
+}
+
+export const ContainerFileArtifact = memo(ContainerFileArtifactComponent);
diff --git a/ui/src/components/Artifact/index.ts b/ui/src/components/Artifact/index.ts
index 29b45bb..c9d7316 100644
--- a/ui/src/components/Artifact/index.ts
+++ b/ui/src/components/Artifact/index.ts
@@ -5,3 +5,4 @@ export { TableArtifact, type TableArtifactProps } from "./TableArtifact";
 export { ImageArtifact, type ImageArtifactProps } from "./ImageArtifact";
 export { ChartArtifact, type ChartArtifactProps } from "./ChartArtifact";
 export { HtmlArtifact, type HtmlArtifactProps } from "./HtmlArtifact";
+export { ContainerFileArtifact, type ContainerFileArtifactProps } from "./ContainerFileArtifact";
diff --git a/ui/src/components/ChatMessageList/ChatMessageList.tsx b/ui/src/components/ChatMessageList/ChatMessageList.tsx
index 176e761..9b752d0 100644
--- a/ui/src/components/ChatMessageList/ChatMessageList.tsx
+++ b/ui/src/components/ChatMessageList/ChatMessageList.tsx
@@ -22,6 +22,7 @@ import { useAutoScroll } from "@/hooks/useAutoScroll";
 import type { ChatMessage as ChatMessageType } from "@/components/chat-types";
 import { EmptyChat } from "@/components/EmptyChat/EmptyChat";
 import { MultiModelResponse } from "@/components/MultiModelResponse/MultiModelResponse";
+import { MCPApprovalRequest } from "@/components/MCPApprovalRequest/MCPApprovalRequest";
 import {
   useMessages,
   useConversationStore,
@@ -113,6 +114,8 @@ interface ChatMessageListProps {
   onEditAndRerun?: (messageId: string, newContent: string) => void;
   /** Callback to regenerate all responses for a user message (same as edit & resend with unchanged content) */
   onRegenerateAll?: (messageId: string) => void;
+  /** Callback to respond to a gateway MCP approval request */
+  onRespondMcpApproval?: (messageId: string, approvalRequestId: string, approve: boolean) => void;
 }
 
 export function ChatMessageList({
@@ -122,6 +125,7 @@ export function ChatMessageList({
   onForkFromMessage,
   onEditAndRerun,
   onRegenerateAll,
+  onRespondMcpApproval,
 }: ChatMessageListProps) {
   // ============================================================================
   // STORE SUBSCRIPTIONS (Surgical Selectors)
@@ -659,6 +663,23 @@ export function ChatMessageList({
                           actionConfig={actionConfig}
                           historyMode={group.userMessage.historyMode}
                         />
+                        {/* Gateway MCP approval prompts for this group's responses */}
+                        {committedResponses.flatMap((m) =>
+                          (m.pendingMcpApprovals ?? []).map((approval) => (
+                            <MCPApprovalRequest
+                              key={`${m.id}:${approval.approvalRequestId}`}
+                              approval={approval}
+                              // Disable while a turn is streaming: resolving
+                              // an approval starts a new turn, which would
+                              // race the in-flight stream (the handler also
+                              // guards, but this stops the click entirely).
+                              disabled={!onRespondMcpApproval || isStreaming}
+                              onRespond={(approve) =>
+                                onRespondMcpApproval?.(m.id, approval.approvalRequestId, approve)
+                              }
+                            />
+                          ))
+                        )}
                       </>
                     )}
                   </div>
diff --git a/ui/src/components/ChatView/ChatView.tsx b/ui/src/components/ChatView/ChatView.tsx
index 65c9c4a..035cd1c 100644
--- a/ui/src/components/ChatView/ChatView.tsx
+++ b/ui/src/components/ChatView/ChatView.tsx
@@ -21,6 +21,8 @@ import {
   useTTSSpeed,
   useWidescreenMode,
   useSubAgentModel,
+  useToolSearchEnabled,
+  useToolSearchRanker,
   useMCPConfigModalOpen,
 } from "@/stores/chatUIStore";
 import {
@@ -75,6 +77,8 @@ export interface ChatViewProps {
   pendingProjectId?: string | null;
   /** Callback to edit a message and re-run from that point */
   onEditAndRerun?: (messageId: string, newContent: string) => void;
+  /** Callback to respond to a gateway MCP approval request */
+  onRespondMcpApproval?: (messageId: string, approvalRequestId: string, approve: boolean) => void;
   /** Owner type for vector store filtering (e.g., "user", "organization") */
   vectorStoreOwnerType?: VectorStoreOwnerType;
   /** Owner ID for vector store filtering (e.g., user id, org id) */
@@ -98,6 +102,7 @@ export function ChatView({
   pendingProjectName,
   pendingProjectId,
   onEditAndRerun,
+  onRespondMcpApproval,
   vectorStoreOwnerType,
   vectorStoreOwnerId,
 }: ChatViewProps) {
@@ -118,6 +123,8 @@ export function ChatView({
   const ttsSpeed = useTTSSpeed();
   const widescreenMode = useWidescreenMode();
   const subAgentModel = useSubAgentModel();
+  const toolSearchEnabled = useToolSearchEnabled();
+  const toolSearchRanker = useToolSearchRanker();
   const mcpConfigModalOpen = useMCPConfigModalOpen();
   const [mcpPrefill, setMcpPrefill] = useState<MCPServerPrefill | null>(null);
 
@@ -173,6 +180,8 @@ export function ChatView({
     setTTSSpeed,
     setSubAgentModel,
     setPendingPrompt,
+    setToolSearchEnabled,
+    setToolSearchRanker,
   } = useChatUIStore();
 
   // Stable callback for instance parameter changes
@@ -250,6 +259,7 @@ export function ChatView({
           onRegenerateAll={onRegenerateAll}
           onForkFromMessage={onForkFromMessage}
           onEditAndRerun={onEditAndRerun}
+          onRespondMcpApproval={onRespondMcpApproval}
         />
       </main>
 
@@ -298,8 +308,13 @@ export function ChatView({
         vectorStoreOwnerId={vectorStoreOwnerId}
         clientSideRAG={clientSideRAG}
         onClientSideRAGChange={setClientSideRAG}
+        enabledTools={enabledTools}
         maxToolIterations={maxToolIterations}
         onMaxToolIterationsChange={setMaxToolIterations}
+        toolSearchEnabled={toolSearchEnabled}
+        onToolSearchEnabledChange={setToolSearchEnabled}
+        toolSearchRanker={toolSearchRanker}
+        onToolSearchRankerChange={setToolSearchRanker}
         captureRawSSEEvents={captureRawSSEEvents}
         onCaptureRawSSEEventsChange={setCaptureRawSSEEvents}
         ttsVoice={ttsVoice}
diff --git a/ui/src/components/ConversationSettingsModal/ConversationSettingsModal.tsx b/ui/src/components/ConversationSettingsModal/ConversationSettingsModal.tsx
index 356f411..d891116 100644
--- a/ui/src/components/ConversationSettingsModal/ConversationSettingsModal.tsx
+++ b/ui/src/components/ConversationSettingsModal/ConversationSettingsModal.tsx
@@ -4,6 +4,7 @@ import { Settings2, RotateCcw, Database, Save, Volume2 } from "lucide-react";
 import type { VectorStoreOwnerType, Voice } from "@/api/generated/types.gen";
 import { TTS_VOICES, DEFAULT_TTS_VOICE, DEFAULT_TTS_SPEED } from "@/hooks/useAudioPlayback";
 import { getDefaultSystemPrompt } from "@/utils/defaultSystemPrompt";
+import { getEnabledToolsSystemGuidance } from "@/pages/chat/utils/toolExecutors";
 import { Button } from "@/components/Button/Button";
 import type { ResponseActionConfig } from "@/components/chat-types";
 import { DEFAULT_ACTION_CONFIG } from "@/components/chat-types";
@@ -41,10 +42,20 @@ interface ConversationSettingsModalProps {
   clientSideRAG?: boolean;
   /** Callback when client-side RAG setting changes */
   onClientSideRAGChange?: (enabled: boolean) => void;
+  /** Enabled tool IDs, used to show any per-tool system-prompt guidance. */
+  enabledTools?: string[];
   /** Maximum tool execution iterations */
   maxToolIterations?: number;
   /** Callback when max tool iterations changes */
   onMaxToolIterationsChange?: (iterations: number) => void;
+  /** Whether tool search / deferred tool loading is enabled */
+  toolSearchEnabled?: boolean;
+  /** Callback when tool search setting changes */
+  onToolSearchEnabledChange?: (enabled: boolean) => void;
+  /** Tool search ranker override */
+  toolSearchRanker?: "default" | "hybrid" | "semantic" | "lexical";
+  /** Callback when tool search ranker changes */
+  onToolSearchRankerChange?: (ranker: "default" | "hybrid" | "semantic" | "lexical") => void;
   /** Whether to capture raw SSE events for debugging */
   captureRawSSEEvents?: boolean;
   /** Callback when SSE capture setting changes */
@@ -78,8 +89,13 @@ export function ConversationSettingsModal({
   vectorStoreOwnerId,
   clientSideRAG,
   onClientSideRAGChange,
+  enabledTools = [],
   maxToolIterations = 25,
   onMaxToolIterationsChange,
+  toolSearchEnabled = false,
+  onToolSearchEnabledChange,
+  toolSearchRanker = "default",
+  onToolSearchRankerChange,
   captureRawSSEEvents,
   onCaptureRawSSEEventsChange,
   ttsVoice = DEFAULT_TTS_VOICE,
@@ -91,6 +107,11 @@ export function ConversationSettingsModal({
 
   const displayedPrompt = systemPrompt || getDefaultSystemPrompt();
   const isDefault = !systemPrompt;
+  // Guidance auto-appended to the system prompt at request time for the
+  // enabled tools (e.g. the shell tool's file-output note). Shown read-only so
+  // the user sees the full effective prompt without it polluting their editable
+  // text.
+  const toolGuidance = getEnabledToolsSystemGuidance(enabledTools);
 
   const autoResize = useCallback((el: HTMLTextAreaElement) => {
     el.style.height = "auto";
@@ -192,6 +213,20 @@ export function ConversationSettingsModal({
             aria-label="System prompt"
             className={`w-full min-h-[120px] rounded-md border bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 resize-none ${isDefault ? "text-muted-foreground" : ""}`}
           />
+          {toolGuidance && (
+            <div className="rounded-md border border-dashed bg-muted/30 px-3 py-2">
+              <p className="text-xs font-medium text-muted-foreground mb-1">
+                Auto-added for enabled tools
+              </p>
+              <p className="text-xs text-muted-foreground mb-2">
+                Appended to the system prompt while the relevant tools are on. Not editable here —
+                it updates as you toggle tools.
+              </p>
+              <pre className="max-h-40 overflow-auto whitespace-pre-wrap break-words text-xs text-muted-foreground">
+                {toolGuidance}
+              </pre>
+            </div>
+          )}
         </div>
 
         {/* Knowledge Base Section */}
@@ -347,7 +382,9 @@ export function ConversationSettingsModal({
         )}
 
         {/* Advanced Section */}
-        {(onMaxToolIterationsChange || onCaptureRawSSEEventsChange) && (
+        {(onMaxToolIterationsChange ||
+          onCaptureRawSSEEventsChange ||
+          onToolSearchEnabledChange) && (
           <div className="space-y-3 mb-6">
             <div>
               <h3 className="text-sm font-medium mb-1">Advanced</h3>
@@ -356,6 +393,36 @@ export function ConversationSettingsModal({
               </p>
             </div>
             <div className="rounded-lg border p-4 space-y-4">
+              {onToolSearchEnabledChange && (
+                <div className="space-y-3">
+                  <div className="flex items-center justify-between">
+                    <div>
+                      <span className="text-sm">Tool search</span>
+                      <p className="text-xs text-muted-foreground mt-0.5">
+                        Let the model search for tools and load them on demand. Keeps context small
+                        when many MCP tools are attached.
+                      </p>
+                    </div>
+                    <Switch
+                      checked={toolSearchEnabled}
+                      onChange={(e) => onToolSearchEnabledChange(e.target.checked)}
+                      aria-label="Enable tool search"
+                    />
+                  </div>
+                  {toolSearchEnabled && onToolSearchRankerChange && (
+                    <Select<"default" | "hybrid" | "semantic" | "lexical">
+                      value={toolSearchRanker}
+                      onChange={(v) => onToolSearchRankerChange(v ?? "default")}
+                      options={[
+                        { value: "default", label: "Ranker: Default" },
+                        { value: "hybrid", label: "Ranker: Hybrid" },
+                        { value: "semantic", label: "Ranker: Semantic" },
+                        { value: "lexical", label: "Ranker: Lexical" },
+                      ]}
+                    />
+                  )}
+                </div>
+              )}
               {onMaxToolIterationsChange && (
                 <Slider
                   label="Max tool iterations"
diff --git a/ui/src/components/Header/Header.tsx b/ui/src/components/Header/Header.tsx
index b88298e..e7b4f0a 100644
--- a/ui/src/components/Header/Header.tsx
+++ b/ui/src/components/Header/Header.tsx
@@ -2,6 +2,7 @@ import { Link, NavLink, useLocation } from "react-router-dom";
 import {
   BarChart3,
   BookOpen,
+  Box,
   FolderOpen,
   Key,
   Menu,
@@ -37,6 +38,7 @@ export const navItems: NavItem[] = [
   { to: "/projects", icon: FolderOpen, label: "Projects", pageKey: "projects" },
   { to: "/teams", icon: UsersRound, label: "Teams", pageKey: "teams" },
   { to: "/knowledge-bases", icon: BookOpen, label: "Knowledge", pageKey: "knowledge_bases" },
+  { to: "/containers", icon: Box, label: "Containers", pageKey: "containers" },
   { to: "/api-keys", icon: Key, label: "API Keys", pageKey: "api_keys" },
   { to: "/providers", icon: Server, label: "Providers", pageKey: "providers" },
   { to: "/usage", icon: BarChart3, label: "Usage", pageKey: "usage" },
diff --git a/ui/src/components/MCPApprovalRequest/MCPApprovalRequest.stories.tsx b/ui/src/components/MCPApprovalRequest/MCPApprovalRequest.stories.tsx
new file mode 100644
index 0000000..c001d9b
--- /dev/null
+++ b/ui/src/components/MCPApprovalRequest/MCPApprovalRequest.stories.tsx
@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MCPApprovalRequest } from "./MCPApprovalRequest";
+
+const meta: Meta<typeof MCPApprovalRequest> = {
+  title: "Chat/MCPApprovalRequest",
+  component: MCPApprovalRequest,
+  args: {
+    onRespond: (approve: boolean) => console.log("respond", approve),
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof MCPApprovalRequest>;
+
+export const Pending: Story = {
+  args: {
+    approval: {
+      id: "mcpr_1",
+      approvalRequestId: "mcpr_1",
+      serverLabel: "github",
+      toolName: "create_issue",
+      argumentsJson: '{"repo":"acme/app","title":"Bug: crash on load"}',
+      parsedArguments: { repo: "acme/app", title: "Bug: crash on load" },
+    },
+  },
+};
+
+export const Approved: Story = {
+  args: {
+    approval: {
+      ...Pending.args!.approval!,
+      resolved: "approved",
+    },
+  },
+};
+
+export const Denied: Story = {
+  args: {
+    approval: {
+      ...Pending.args!.approval!,
+      resolved: "denied",
+    },
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    ...Pending.args,
+    disabled: true,
+  },
+};
diff --git a/ui/src/components/MCPApprovalRequest/MCPApprovalRequest.tsx b/ui/src/components/MCPApprovalRequest/MCPApprovalRequest.tsx
new file mode 100644
index 0000000..4ec939a
--- /dev/null
+++ b/ui/src/components/MCPApprovalRequest/MCPApprovalRequest.tsx
@@ -0,0 +1,101 @@
+/**
+ * MCPApprovalRequest — approve/deny prompt for a gateway MCP tool call that
+ * paused on `require_approval`. Approving resumes the response server-side via
+ * an `mcp_approval_response`; denying refuses the call.
+ */
+
+import { useState } from "react";
+import { Check, ChevronDown, ChevronRight, ShieldAlert, X } from "lucide-react";
+
+import { Button } from "@/components/Button/Button";
+import { Badge } from "@/components/Badge/Badge";
+import { cn } from "@/utils/cn";
+import type { McpApprovalRequest } from "@/components/chat-types";
+
+export interface MCPApprovalRequestProps {
+  approval: McpApprovalRequest;
+  /** Called with the user's decision. */
+  onRespond: (approve: boolean) => void;
+  /** Disable the buttons (e.g. while a resume is streaming). */
+  disabled?: boolean;
+}
+
+function prettyArgs(approval: McpApprovalRequest): string {
+  if (approval.parsedArguments) {
+    try {
+      return JSON.stringify(approval.parsedArguments, null, 2);
+    } catch {
+      // fall through to the raw string
+    }
+  }
+  return approval.argumentsJson || "{}";
+}
+
+export function MCPApprovalRequest({
+  approval,
+  onRespond,
+  disabled = false,
+}: MCPApprovalRequestProps) {
+  const [expanded, setExpanded] = useState(false);
+  const resolved = approval.resolved;
+
+  return (
+    <div
+      className={cn(
+        "my-2 rounded-lg border px-3 py-2 text-sm",
+        resolved ? "border-border bg-muted/40" : "border-amber-500/40 bg-amber-500/5"
+      )}
+    >
+      <div className="flex items-start justify-between gap-2">
+        <div className="flex items-center gap-2 min-w-0">
+          <ShieldAlert
+            className={cn(
+              "h-4 w-4 shrink-0",
+              resolved ? "text-muted-foreground" : "text-amber-600 dark:text-amber-500"
+            )}
+          />
+          <div className="min-w-0">
+            <p className="font-medium">{resolved ? "Tool call reviewed" : "Approval required"}</p>
+            <p className="text-xs text-muted-foreground truncate">
+              <span className="font-mono">{approval.serverLabel}</span>
+              {" · "}
+              <span className="font-mono">{approval.toolName}</span>
+            </p>
+          </div>
+        </div>
+
+        {resolved ? (
+          <Badge variant={resolved === "approved" ? "default" : "destructive"}>
+            {resolved === "approved" ? "Approved" : "Denied"}
+          </Badge>
+        ) : (
+          <div className="flex items-center gap-1 shrink-0">
+            <Button size="sm" variant="ghost" onClick={() => onRespond(false)} disabled={disabled}>
+              <X className="h-4 w-4 mr-1" />
+              Deny
+            </Button>
+            <Button size="sm" variant="primary" onClick={() => onRespond(true)} disabled={disabled}>
+              <Check className="h-4 w-4 mr-1" />
+              Approve
+            </Button>
+          </div>
+        )}
+      </div>
+
+      <button
+        type="button"
+        className="mt-2 flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground"
+        onClick={() => setExpanded((v) => !v)}
+        aria-expanded={expanded}
+      >
+        {expanded ? <ChevronDown className="h-3 w-3" /> : <ChevronRight className="h-3 w-3" />}
+        {expanded ? "Hide arguments" : "Show arguments"}
+      </button>
+      {expanded && (
+        <pre className="mt-1 max-h-48 overflow-auto rounded bg-muted p-2 text-xs">
+          <code>{prettyArgs(approval)}</code>
+        </pre>
+      )}
+    </div>
+  );
+}
diff --git a/ui/src/components/MCPConfigModal/MCPConfigModal.tsx b/ui/src/components/MCPConfigModal/MCPConfigModal.tsx
index 45329a2..f9cb029 100644
--- a/ui/src/components/MCPConfigModal/MCPConfigModal.tsx
+++ b/ui/src/components/MCPConfigModal/MCPConfigModal.tsx
@@ -111,6 +111,10 @@ const serverFormSchema = z.object({
   oauthScopes: z.string(),
   headers: z.string(),
   timeout: z.number().int().min(1, "Must be at least 1 second"),
+  runsOn: z.enum(["browser", "gateway"]),
+  requireApproval: z.enum(["always", "never"]),
+  /** Comma/newline separated tool names; empty = all tools allowed. */
+  allowedTools: z.string(),
 });
 
 type ServerFormValues = z.infer<typeof serverFormSchema>;
@@ -527,6 +531,9 @@ function ServerForm({ editingServer, onSubmit, onCancel, prefill }: ServerFormPr
           ? JSON.stringify(mergedExtraHeaders, null, 2)
           : "",
       timeout: Math.round((editingServer?.timeout ?? 300000) / 1000),
+      runsOn: editingServer?.runsOn ?? "browser",
+      requireApproval: editingServer?.requireApproval ?? "never",
+      allowedTools: (editingServer?.allowedTools ?? []).join(", "),
     },
   });
 
@@ -553,6 +560,8 @@ function ServerForm({ editingServer, onSubmit, onCancel, prefill }: ServerFormPr
   const watchedUrl = form.watch("url");
   const watchedHeaders = form.watch("headers");
   const watchedAuthType = form.watch("authType") as MCPAuthType;
+  const watchedRunsOn = form.watch("runsOn");
+  const watchedRequireApproval = form.watch("requireApproval");
   // Debounce URL so network-touching effects (auth probe, template checks) run
   // only after the user stops typing.
   const debouncedUrl = useDebouncedValue(watchedUrl, 500);
@@ -813,6 +822,86 @@ function ServerForm({ editingServer, onSubmit, onCancel, prefill }: ServerFormPr
         <Input id="server-name" {...form.register("name")} placeholder="My MCP Server" />
       </FormField>
 
+      {/* Where the server runs: browser (client-side) vs gateway (server-side) */}
+      <FormField
+        label="Runs on"
+        htmlFor="server-runs-on"
+        helpText={
+          watchedRunsOn === "gateway"
+            ? "Hadrian connects and runs tool calls server-side. Works for API clients and background/agent runs; credentials are sent with the request."
+            : "Your browser connects and runs tool calls. Only works inside this chat UI."
+        }
+      >
+        <div className="flex gap-1.5" role="radiogroup" aria-label="Where the server runs">
+          {[
+            { value: "browser" as const, label: "Browser" },
+            { value: "gateway" as const, label: "Gateway" },
+          ].map((opt) => (
+            <button
+              key={opt.value}
+              type="button"
+              role="radio"
+              aria-checked={watchedRunsOn === opt.value}
+              onClick={() => form.setValue("runsOn", opt.value)}
+              className={cn(
+                "px-3 py-1.5 rounded-md text-sm border transition-colors",
+                watchedRunsOn === opt.value
+                  ? "border-primary bg-primary/10 text-primary font-medium"
+                  : "border-input text-muted-foreground hover:bg-muted"
+              )}
+            >
+              {opt.label}
+            </button>
+          ))}
+        </div>
+      </FormField>
+
+      {/* Gateway-only: approval gating + allowed tools */}
+      {watchedRunsOn === "gateway" && (
+        <>
+          <FormField
+            label="Tool approval"
+            htmlFor="server-require-approval"
+            helpText="Pause for your approval before each tool call, or run them automatically."
+          >
+            <div className="flex gap-1.5" role="radiogroup" aria-label="Tool approval">
+              {[
+                { value: "never" as const, label: "Run automatically" },
+                { value: "always" as const, label: "Require approval" },
+              ].map((opt) => (
+                <button
+                  key={opt.value}
+                  type="button"
+                  role="radio"
+                  aria-checked={watchedRequireApproval === opt.value}
+                  onClick={() => form.setValue("requireApproval", opt.value)}
+                  className={cn(
+                    "px-3 py-1.5 rounded-md text-sm border transition-colors",
+                    watchedRequireApproval === opt.value
+                      ? "border-primary bg-primary/10 text-primary font-medium"
+                      : "border-input text-muted-foreground hover:bg-muted"
+                  )}
+                >
+                  {opt.label}
+                </button>
+              ))}
+            </div>
+          </FormField>
+
+          <FormField
+            label="Allowed tools"
+            htmlFor="server-allowed-tools"
+            helpText="Optional. Comma-separated tool names to allow; leave blank for all."
+          >
+            <Input
+              id="server-allowed-tools"
+              {...form.register("allowedTools")}
+              placeholder="create_issue, list_repos"
+            />
+          </FormField>
+        </>
+      )}
+
       {/* Auth detection indicator */}
       {detectionStatus === "detecting" && (
         <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
@@ -1191,6 +1280,18 @@ export function MCPConfigModal({ open, onClose, prefill }: MCPConfigModalProps)
 
       const timeout = values.timeout * 1000;
 
+      // Gateway-only fields. `allowedTools` is a comma/newline list; empty = all.
+      const allowedTools = values.allowedTools
+        .split(/[\n,]/)
+        .map((t) => t.trim())
+        .filter(Boolean);
+      const gatewayFields = {
+        runsOn: values.runsOn,
+        requireApproval: values.runsOn === "gateway" ? values.requireApproval : undefined,
+        allowedTools:
+          values.runsOn === "gateway" && allowedTools.length > 0 ? allowedTools : undefined,
+      };
+
       if (editingServer) {
         updateServer(editingServer.id, {
           name: values.name,
@@ -1199,6 +1300,7 @@ export function MCPConfigModal({ open, onClose, prefill }: MCPConfigModalProps)
           headers,
           timeout,
           oauth,
+          ...gatewayFields,
         });
       } else {
         addServer({
@@ -1209,6 +1311,7 @@ export function MCPConfigModal({ open, onClose, prefill }: MCPConfigModalProps)
           headers,
           timeout,
           oauth,
+          ...gatewayFields,
         });
       }
 
diff --git a/ui/src/components/PageGuard/PageGuard.tsx b/ui/src/components/PageGuard/PageGuard.tsx
index d175e9a..1922c37 100644
--- a/ui/src/components/PageGuard/PageGuard.tsx
+++ b/ui/src/components/PageGuard/PageGuard.tsx
@@ -11,6 +11,7 @@ const mainPageOrder: MainPageKey[] = [
   "projects",
   "teams",
   "knowledge_bases",
+  "containers",
   "api_keys",
   "providers",
   "usage",
@@ -22,6 +23,7 @@ const mainPageRoutes: Record<MainPageKey, string> = {
   projects: "/projects",
   teams: "/teams",
   knowledge_bases: "/knowledge-bases",
+  containers: "/containers",
   api_keys: "/api-keys",
   providers: "/providers",
   usage: "/usage",
diff --git a/ui/src/components/ToolExecution/ArtifactThumbnail.tsx b/ui/src/components/ToolExecution/ArtifactThumbnail.tsx
index efd35e1..60cecb4 100644
--- a/ui/src/components/ToolExecution/ArtifactThumbnail.tsx
+++ b/ui/src/components/ToolExecution/ArtifactThumbnail.tsx
@@ -1,5 +1,15 @@
 import { memo } from "react";
-import { Code, Table, BarChart3, Image, FileCode, Bot, ExternalLink, Search } from "lucide-react";
+import {
+  Code,
+  Table,
+  BarChart3,
+  Image,
+  FileCode,
+  Bot,
+  ExternalLink,
+  Search,
+  FileText,
+} from "lucide-react";
 import type { Artifact, ArtifactType } from "@/components/chat-types";
 
 interface ArtifactThumbnailProps {
@@ -19,6 +29,7 @@ const ARTIFACT_ICONS: Record<ArtifactType, typeof Code> = {
   html: FileCode,
   agent: Bot,
   file_search: Search,
+  container_file: FileText,
   // display_selection is internal and shouldn't be rendered as a thumbnail
   display_selection: Code,
 };
@@ -32,6 +43,7 @@ const ARTIFACT_LABELS: Record<ArtifactType, string> = {
   html: "HTML",
   agent: "Sub-Agent",
   file_search: "Search Results",
+  container_file: "File",
   display_selection: "Selection",
 };
 
@@ -44,6 +56,7 @@ const ARTIFACT_COLORS: Record<ArtifactType, string> = {
   html: "bg-pink-500/10 text-pink-700 dark:text-pink-400",
   agent: "bg-cyan-500/10 text-cyan-800 dark:text-cyan-400",
   file_search: "bg-indigo-500/10 text-indigo-700 dark:text-indigo-400",
+  container_file: "bg-teal-500/10 text-teal-700 dark:text-teal-400",
   display_selection: "bg-zinc-500/10 text-zinc-700 dark:text-zinc-400",
 };
 
diff --git a/ui/src/components/ToolIcons/ToolIcons.tsx b/ui/src/components/ToolIcons/ToolIcons.tsx
index ac2c5e2..13e3304 100644
--- a/ui/src/components/ToolIcons/ToolIcons.tsx
+++ b/ui/src/components/ToolIcons/ToolIcons.tsx
@@ -5,7 +5,16 @@
  * and ArtifactThumbnail for consistent tool identification.
  */
 
-import { FileSearch, Globe, BarChart3, Wrench, Bot, Plug, Download } from "lucide-react";
+import {
+  FileSearch,
+  Globe,
+  BarChart3,
+  Wrench,
+  Users,
+  Plug,
+  Download,
+  SquareTerminal,
+} from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 
 /** Python icon - "Py" text in a rounded box */
@@ -197,7 +206,9 @@ export const TOOL_ICON_MAP: Record<string, ToolIconComponent> = {
   web_fetch: Download,
   wikipedia: WikipediaIcon,
   wikidata: WikidataIcon,
-  sub_agent: Bot,
+  agent: SquareTerminal,
+  shell: SquareTerminal,
+  sub_agent: Users,
   mcp: Plug,
   display_artifacts: Wrench,
 };
@@ -220,7 +231,9 @@ export const TOOL_SHORT_NAMES: Record<string, string> = {
   web_fetch: "Fetch",
   wikipedia: "Wikipedia",
   wikidata: "Wikidata",
-  sub_agent: "Agent",
+  agent: "Agent",
+  shell: "Shell",
+  sub_agent: "Sub-agent",
   mcp: "MCP",
   display_artifacts: "Display",
 };
@@ -247,7 +260,9 @@ const TOOL_STATUS_LABELS: Record<string, string> = {
   web_fetch: "Fetching URL",
   wikipedia: "Searching Wikipedia",
   wikidata: "Querying Wikidata",
-  sub_agent: "Running agent",
+  agent: "Running command",
+  shell: "Running command",
+  sub_agent: "Running sub-agent",
   mcp: "Calling tool",
 };
 
diff --git a/ui/src/components/ToolsBar/ToolsBar.tsx b/ui/src/components/ToolsBar/ToolsBar.tsx
index 201cdee..926e45c 100644
--- a/ui/src/components/ToolsBar/ToolsBar.tsx
+++ b/ui/src/components/ToolsBar/ToolsBar.tsx
@@ -14,6 +14,7 @@ import type { VectorStoreOwnerType } from "@/api/generated/types.gen";
 import { Button } from "@/components/Button/Button";
 import { DataFileUpload } from "@/components/DataFileUpload";
 import { ModelPicker, type ModelInfo } from "@/components/ModelPicker/ModelPicker";
+import { AgentToolSettings } from "@/components/AgentToolSettings/AgentToolSettings";
 import { Popover, PopoverAnchor, PopoverContent } from "@/components/Popover/Popover";
 import { getToolIcon } from "@/components/ToolIcons";
 import { TOOL_METADATA, type ToolMetadata } from "@/pages/chat/utils/toolExecutors";
@@ -534,6 +535,11 @@ export function ToolsBar({
           />
         );
       }
+      if (toolId === "agent") {
+        return (
+          <AgentToolSettings disabled={disabled} onConfigured={() => ensureEnabled("agent")} />
+        );
+      }
       if (toolId === "mcp") {
         return (
           <MCPServerStatus
diff --git a/ui/src/components/chat-types.ts b/ui/src/components/chat-types.ts
index 33bcf03..b98ad21 100644
--- a/ui/src/components/chat-types.ts
+++ b/ui/src/components/chat-types.ts
@@ -8,6 +8,7 @@ import type {
   ChartArtifactData as ChartArtifactDataImport,
   DisplaySelectionData as DisplaySelectionDataImport,
   AgentArtifactData as AgentArtifactDataImport,
+  ContainerFileArtifactData as ContainerFileArtifactDataImport,
   FileSearchArtifactData as FileSearchArtifactDataImport,
   FileSearchResultItem as FileSearchResultItemImport,
   ToolExecutionStatus as ToolExecutionStatusImport,
@@ -23,6 +24,7 @@ export type TableArtifactData = TableArtifactDataImport;
 export type ChartArtifactData = ChartArtifactDataImport;
 export type DisplaySelectionData = DisplaySelectionDataImport;
 export type AgentArtifactData = AgentArtifactDataImport;
+export type ContainerFileArtifactData = ContainerFileArtifactDataImport;
 export type FileSearchArtifactData = FileSearchArtifactDataImport;
 export type FileSearchResultItem = FileSearchResultItemImport;
 export type ToolExecutionStatus = ToolExecutionStatusImport;
@@ -798,6 +800,29 @@ export interface ChunkCitation extends BaseCitation {
 /** Union type for all citation types */
 export type Citation = FileCitation | UrlCitation | ChunkCitation;
 
+/**
+ * A gateway MCP tool call that paused for human approval
+ * (`require_approval`). The user approves/denies it and the chat resumes the
+ * response by echoing back an `mcp_approval_response` keyed by
+ * `approvalRequestId`.
+ */
+export interface McpApprovalRequest {
+  /** Output item id of the approval request. */
+  id: string;
+  /** Id echoed back in the `mcp_approval_response` to resume. */
+  approvalRequestId: string;
+  /** MCP server label that requested the call. */
+  serverLabel: string;
+  /** Tool the model wants to call. */
+  toolName: string;
+  /** Raw JSON arguments string (for display when not parseable). */
+  argumentsJson: string;
+  /** Parsed arguments, when the JSON was valid. */
+  parsedArguments?: Record<string, unknown>;
+  /** Set once the user responds; absent while still pending. */
+  resolved?: "approved" | "denied";
+}
+
 export interface ChatMessage {
   id: string;
   role: "user" | "assistant" | "system";
@@ -834,6 +859,8 @@ export interface ChatMessage {
   completedRounds?: CompletedRound[];
   /** Debug message ID for looking up debug info in debugStore (assistant messages only) */
   debugMessageId?: string;
+  /** Gateway MCP approval requests this response paused on (assistant messages only) */
+  pendingMcpApprovals?: McpApprovalRequest[];
 }
 
 export interface ChatFile {
diff --git a/ui/src/config/defaults.ts b/ui/src/config/defaults.ts
index 4ab70c2..e4bc2c3 100644
--- a/ui/src/config/defaults.ts
+++ b/ui/src/config/defaults.ts
@@ -8,6 +8,7 @@ export const defaultPagesConfig: PagesConfig = {
   projects: enabledPage,
   teams: enabledPage,
   knowledge_bases: enabledPage,
+  containers: enabledPage,
   api_keys: enabledPage,
   providers: enabledPage,
   usage: enabledPage,
diff --git a/ui/src/config/types.ts b/ui/src/config/types.ts
index 0ccf8fd..12795b7 100644
--- a/ui/src/config/types.ts
+++ b/ui/src/config/types.ts
@@ -11,6 +11,7 @@ export interface PagesConfig {
   projects: PageConfig;
   teams: PageConfig;
   knowledge_bases: PageConfig;
+  containers: PageConfig;
   api_keys: PageConfig;
   providers: PageConfig;
   usage: PageConfig;
diff --git a/ui/src/pages/ContainerDetailPage.stories.tsx b/ui/src/pages/ContainerDetailPage.stories.tsx
new file mode 100644
index 0000000..4af64b0
--- /dev/null
+++ b/ui/src/pages/ContainerDetailPage.stories.tsx
@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { http, HttpResponse } from "msw";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter, Routes, Route } from "react-router-dom";
+import ContainerDetailPage from "./ContainerDetailPage";
+import { AuthProvider } from "@/auth";
+import { ToastProvider } from "@/components/Toast/Toast";
+import { ConfirmDialogProvider } from "@/components/ConfirmDialog/ConfirmDialog";
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: false } },
+});
+
+const now = Math.floor(Date.now() / 1000);
+const CONTAINER_ID = "cntr_a1b2c3d4e5f6";
+
+const mockContainer = {
+  id: CONTAINER_ID,
+  object: "container",
+  status: "active",
+  created_at: now - 3600,
+  last_active_at: now - 120,
+  expires_at: now + 1080,
+  idle_ttl_secs: 1200,
+  runtime: "microsandbox",
+  name: "data-analysis",
+  memory_limit: "512m",
+  memory_limit_mb: 512,
+};
+
+const mockFiles = {
+  object: "list",
+  data: [
+    {
+      id: "cfile_111",
+      object: "container.file",
+      container_id: CONTAINER_ID,
+      path: "/mnt/data/residuals.csv",
+      filename: "residuals.csv",
+      bytes: 20480,
+      source: "user",
+      content_type: "text/csv",
+      created_at: now - 3000,
+    },
+    {
+      id: "cfile_222",
+      object: "container.file",
+      container_id: CONTAINER_ID,
+      path: "/mnt/data/chart.png",
+      filename: "chart.png",
+      bytes: 153600,
+      source: "assistant",
+      content_type: "image/png",
+      created_at: now - 600,
+    },
+  ],
+  has_more: false,
+};
+
+const meta: Meta<typeof ContainerDetailPage> = {
+  title: "Pages/ContainerDetailPage",
+  component: ContainerDetailPage,
+  decorators: [
+    (Story) => (
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider>
+          <MemoryRouter initialEntries={[`/containers/${CONTAINER_ID}`]}>
+            <ToastProvider>
+              <ConfirmDialogProvider>
+                <Routes>
+                  <Route path="/containers/:containerId" element={<Story />} />
+                </Routes>
+              </ConfirmDialogProvider>
+            </ToastProvider>
+          </MemoryRouter>
+        </AuthProvider>
+      </QueryClientProvider>
+    ),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    msw: {
+      handlers: [
+        http.get(`*/v1/containers/${CONTAINER_ID}/files`, () => HttpResponse.json(mockFiles)),
+        http.get(`*/v1/containers/${CONTAINER_ID}`, () => HttpResponse.json(mockContainer)),
+      ],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ContainerDetailPage>;
+
+export const Default: Story = {};
+
+export const NoFiles: Story = {
+  parameters: {
+    msw: {
+      handlers: [
+        http.get(`*/v1/containers/${CONTAINER_ID}/files`, () =>
+          HttpResponse.json({ object: "list", data: [], has_more: false })
+        ),
+        http.get(`*/v1/containers/${CONTAINER_ID}`, () => HttpResponse.json(mockContainer)),
+      ],
+    },
+  },
+};
+
+export const NotFound: Story = {
+  parameters: {
+    msw: {
+      handlers: [
+        http.get(`*/v1/containers/${CONTAINER_ID}/files`, () =>
+          HttpResponse.json({ object: "list", data: [], has_more: false })
+        ),
+        http.get(`*/v1/containers/${CONTAINER_ID}`, () => HttpResponse.error()),
+      ],
+    },
+  },
+};
diff --git a/ui/src/pages/ContainerDetailPage.tsx b/ui/src/pages/ContainerDetailPage.tsx
new file mode 100644
index 0000000..68e32f8
--- /dev/null
+++ b/ui/src/pages/ContainerDetailPage.tsx
@@ -0,0 +1,259 @@
+import { useCallback, useMemo, useState } from "react";
+import { useParams, useNavigate } from "react-router-dom";
+import { createColumnHelper, type ColumnDef } from "@tanstack/react-table";
+import { ArrowLeft, Box, Download, FileText, Trash2 } from "lucide-react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+import {
+  apiV1ContainersGetOptions,
+  apiV1ContainersListFilesOptions,
+  apiV1ContainersFileDeleteMutation,
+} from "@/api/generated/@tanstack/react-query.gen";
+import { Badge } from "@/components/Badge/Badge";
+import { Button } from "@/components/Button/Button";
+import { Card, CardContent } from "@/components/Card/Card";
+import { DataTable } from "@/components/DataTable/DataTable";
+import { Skeleton } from "@/components/Skeleton/Skeleton";
+import { useToast } from "@/components/Toast/Toast";
+import { useConfirm } from "@/components/ConfirmDialog/ConfirmDialog";
+import { useAuth } from "@/auth";
+import { formatDateTime, formatBytes } from "@/utils/formatters";
+import { formatApiError } from "@/utils/formatApiError";
+import type {
+  Container,
+  ContainerFile,
+  ContainerFileList,
+  ContainerStatus,
+} from "@/pages/containers/types";
+
+const STATUS_VARIANT: Record<ContainerStatus, "default" | "outline" | "destructive"> = {
+  active: "default",
+  expired: "outline",
+  deleted: "destructive",
+};
+
+function Stat({ label, value }: { label: string; value: React.ReactNode }) {
+  return (
+    <div>
+      <p className="text-xs text-muted-foreground">{label}</p>
+      <p className="text-sm font-medium mt-0.5">{value}</p>
+    </div>
+  );
+}
+
+const columnHelper = createColumnHelper<ContainerFile>();
+
+export default function ContainerDetailPage() {
+  const { containerId = "" } = useParams();
+  const navigate = useNavigate();
+  const { token } = useAuth();
+  const { toast } = useToast();
+  const confirm = useConfirm();
+  const queryClient = useQueryClient();
+  const [downloadingId, setDownloadingId] = useState<string | null>(null);
+
+  const {
+    data: containerData,
+    isLoading: containerLoading,
+    error: containerError,
+  } = useQuery({
+    ...apiV1ContainersGetOptions({ path: { container_id: containerId } }),
+    enabled: !!containerId,
+  });
+  const container = containerData as Container | undefined;
+
+  const { data: filesData, isLoading: filesLoading } = useQuery({
+    ...apiV1ContainersListFilesOptions({
+      path: { container_id: containerId },
+      query: { limit: 1000 },
+    }),
+    enabled: !!containerId,
+  });
+  const files = useMemo(
+    () => (filesData as ContainerFileList | undefined)?.data ?? [],
+    [filesData]
+  );
+
+  const deleteFileMutation = useMutation({
+    ...apiV1ContainersFileDeleteMutation(),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [{ _id: "apiV1ContainersListFiles" }] });
+      toast({ title: "File deleted", type: "success" });
+    },
+    onError: (err) => {
+      toast({ title: "Failed to delete file", description: formatApiError(err), type: "error" });
+    },
+  });
+
+  const downloadFile = useCallback(
+    async (file: ContainerFile) => {
+      setDownloadingId(file.id);
+      try {
+        const res = await fetch(`/api/v1/containers/${containerId}/files/${file.id}/content`, {
+          headers: token ? { Authorization: `Bearer ${token}` } : {},
+        });
+        if (!res.ok) throw new Error(`Download failed (${res.status})`);
+        const blob = await res.blob();
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = file.filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+      } catch (err) {
+        toast({
+          title: "Failed to download file",
+          description: formatApiError(err),
+          type: "error",
+        });
+      } finally {
+        setDownloadingId(null);
+      }
+    },
+    [containerId, token, toast]
+  );
+
+  const handleDeleteFile = async (file: ContainerFile) => {
+    const ok = await confirm({
+      title: "Delete file?",
+      message: `Delete ${file.filename} from this container? This cannot be undone.`,
+      confirmLabel: "Delete",
+      variant: "destructive",
+    });
+    if (ok) {
+      deleteFileMutation.mutate({ path: { container_id: containerId, file_id: file.id } });
+    }
+  };
+
+  const columns = useMemo(
+    () => [
+      columnHelper.accessor("filename", {
+        header: "File",
+        cell: (ctx) => (
+          <div className="flex items-center gap-2 min-w-0">
+            <FileText className="h-4 w-4 text-muted-foreground shrink-0" />
+            <span className="truncate font-mono text-xs" title={ctx.row.original.path}>
+              {ctx.getValue()}
+            </span>
+          </div>
+        ),
+      }),
+      columnHelper.accessor("source", {
+        header: "Source",
+        cell: (ctx) => (
+          <Badge variant={ctx.getValue() === "assistant" ? "default" : "secondary"}>
+            {ctx.getValue()}
+          </Badge>
+        ),
+      }),
+      columnHelper.accessor("bytes", {
+        header: "Size",
+        cell: (ctx) => <span className="text-sm">{formatBytes(ctx.getValue())}</span>,
+      }),
+      columnHelper.accessor("created_at", {
+        header: "Created",
+        cell: (ctx) => (
+          <span className="text-sm text-muted-foreground">
+            {formatDateTime(new Date(ctx.getValue() * 1000))}
+          </span>
+        ),
+      }),
+      columnHelper.display({
+        id: "actions",
+        header: "",
+        cell: (ctx) => {
+          const file = ctx.row.original;
+          return (
+            <div className="flex items-center justify-end gap-1">
+              <Button
+                size="icon"
+                variant="ghost"
+                className="h-7 w-7"
+                onClick={() => downloadFile(file)}
+                disabled={downloadingId === file.id}
+                aria-label={`Download ${file.filename}`}
+              >
+                <Download className="h-4 w-4" />
+              </Button>
+              <Button
+                size="icon"
+                variant="ghost"
+                className="h-7 w-7 text-muted-foreground hover:text-destructive"
+                onClick={() => handleDeleteFile(file)}
+                disabled={deleteFileMutation.isPending}
+                aria-label={`Delete ${file.filename}`}
+              >
+                <Trash2 className="h-4 w-4" />
+              </Button>
+            </div>
+          );
+        },
+      }),
+    ],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [downloadingId, deleteFileMutation.isPending]
+  );
+
+  return (
+    <div className="p-6 max-w-5xl mx-auto">
+      <Button variant="ghost" className="mb-4 -ml-2" onClick={() => navigate("/containers")}>
+        <ArrowLeft className="h-4 w-4 mr-2" />
+        Containers
+      </Button>
+
+      {containerError && (
+        <div className="rounded-md bg-destructive/10 px-4 py-3 text-sm text-destructive">
+          Failed to load container. It may have been deleted.
+        </div>
+      )}
+
+      {containerLoading && <Skeleton className="h-32 w-full" />}
+
+      {container && (
+        <>
+          <div className="flex items-start justify-between gap-3 mb-4">
+            <div className="flex items-center gap-2 min-w-0">
+              <Box className="h-6 w-6 text-muted-foreground shrink-0" />
+              <div className="min-w-0">
+                <h1 className="text-xl font-semibold truncate">
+                  {container.name?.trim() || container.id}
+                </h1>
+                <p className="text-xs text-muted-foreground font-mono truncate">{container.id}</p>
+              </div>
+            </div>
+            <Badge variant={STATUS_VARIANT[container.status] ?? "outline"}>
+              {container.status}
+            </Badge>
+          </div>
+
+          <Card className="mb-6">
+            <CardContent className="p-4 grid grid-cols-2 gap-4 sm:grid-cols-3">
+              <Stat label="Runtime" value={container.runtime} />
+              <Stat label="Memory" value={container.memory_limit ?? "default"} />
+              <Stat label="Idle TTL" value={`${Math.round(container.idle_ttl_secs / 60)} min`} />
+              <Stat label="Created" value={formatDateTime(new Date(container.created_at * 1000))} />
+              <Stat
+                label="Last active"
+                value={formatDateTime(new Date(container.last_active_at * 1000))}
+              />
+              <Stat
+                label={container.status === "active" ? "Expires" : "Expired"}
+                value={formatDateTime(new Date(container.expires_at * 1000))}
+              />
+            </CardContent>
+          </Card>
+
+          <h2 className="text-lg font-medium mb-3">Files</h2>
+          <DataTable
+            columns={columns as ColumnDef<ContainerFile>[]}
+            data={files}
+            isLoading={filesLoading}
+            emptyMessage="No files in this container."
+          />
+        </>
+      )}
+    </div>
+  );
+}
diff --git a/ui/src/pages/ContainersPage.stories.tsx b/ui/src/pages/ContainersPage.stories.tsx
new file mode 100644
index 0000000..c1b8425
--- /dev/null
+++ b/ui/src/pages/ContainersPage.stories.tsx
@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { http, HttpResponse } from "msw";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "react-router-dom";
+import ContainersPage from "./ContainersPage";
+import { ToastProvider } from "@/components/Toast/Toast";
+import { ConfirmDialogProvider } from "@/components/ConfirmDialog/ConfirmDialog";
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: false } },
+});
+
+const now = Math.floor(Date.now() / 1000);
+
+const mockContainers = {
+  object: "list",
+  data: [
+    {
+      id: "cntr_a1b2c3d4e5f6",
+      object: "container",
+      status: "active",
+      created_at: now - 3600,
+      last_active_at: now - 120,
+      expires_at: now + 1080,
+      idle_ttl_secs: 1200,
+      runtime: "microsandbox",
+      name: "data-analysis",
+      memory_limit: "512m",
+      memory_limit_mb: 512,
+    },
+    {
+      id: "cntr_f6e5d4c3b2a1",
+      object: "container",
+      status: "expired",
+      created_at: now - 86400,
+      last_active_at: now - 84000,
+      expires_at: now - 82800,
+      idle_ttl_secs: 1200,
+      runtime: "opensandbox",
+    },
+  ],
+  has_more: false,
+};
+
+const meta: Meta<typeof ContainersPage> = {
+  title: "Pages/ContainersPage",
+  component: ContainersPage,
+  decorators: [
+    (Story) => (
+      <QueryClientProvider client={queryClient}>
+        <MemoryRouter>
+          <ToastProvider>
+            <ConfirmDialogProvider>
+              <Story />
+            </ConfirmDialogProvider>
+          </ToastProvider>
+        </MemoryRouter>
+      </QueryClientProvider>
+    ),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    msw: {
+      handlers: [http.get("*/v1/containers", () => HttpResponse.json(mockContainers))],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ContainersPage>;
+
+export const Default: Story = {};
+
+export const Loading: Story = {
+  parameters: {
+    msw: {
+      handlers: [
+        http.get("*/v1/containers", async () => {
+          await new Promise((resolve) => setTimeout(resolve, 999999));
+          return HttpResponse.json(mockContainers);
+        }),
+      ],
+    },
+  },
+};
+
+export const Empty: Story = {
+  parameters: {
+    msw: {
+      handlers: [
+        http.get("*/v1/containers", () =>
+          HttpResponse.json({ object: "list", data: [], has_more: false })
+        ),
+      ],
+    },
+  },
+};
+
+export const Error: Story = {
+  parameters: {
+    msw: {
+      handlers: [http.get("*/v1/containers", () => HttpResponse.error())],
+    },
+  },
+};
diff --git a/ui/src/pages/ContainersPage.tsx b/ui/src/pages/ContainersPage.tsx
new file mode 100644
index 0000000..8200ab4
--- /dev/null
+++ b/ui/src/pages/ContainersPage.tsx
@@ -0,0 +1,253 @@
+import { useMemo, useState } from "react";
+import { Link } from "react-router-dom";
+import { Box, Calendar, Clock, Cpu, Trash2 } from "lucide-react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+import {
+  apiV1ContainersListOptions,
+  apiV1ContainersDeleteMutation,
+} from "@/api/generated/@tanstack/react-query.gen";
+import { Button } from "@/components/Button/Button";
+import { Badge } from "@/components/Badge/Badge";
+import { Card, CardContent } from "@/components/Card/Card";
+import { Input } from "@/components/Input/Input";
+import { Skeleton } from "@/components/Skeleton/Skeleton";
+import { useConfirm } from "@/components/ConfirmDialog/ConfirmDialog";
+import { useToast } from "@/components/Toast/Toast";
+import { formatDateTime, formatRelativeTime } from "@/utils/formatters";
+import { formatApiError } from "@/utils/formatApiError";
+import type { Container, ContainerList, ContainerStatus } from "@/pages/containers/types";
+
+function StatusBadge({ status }: { status: ContainerStatus }) {
+  const variants: Record<ContainerStatus, "default" | "secondary" | "destructive" | "outline"> = {
+    active: "default",
+    expired: "outline",
+    deleted: "destructive",
+  };
+  const labels: Record<ContainerStatus, string> = {
+    active: "Active",
+    expired: "Expired",
+    deleted: "Deleted",
+  };
+  return <Badge variant={variants[status] ?? "outline"}>{labels[status] ?? status}</Badge>;
+}
+
+function ContainerCard({
+  container,
+  onDelete,
+  deleting,
+}: {
+  container: Container;
+  onDelete: (c: Container) => void;
+  deleting: boolean;
+}) {
+  const title = container.name?.trim() || container.id;
+  const isDeleted = container.status === "deleted";
+  return (
+    <Card className="h-full">
+      <CardContent className="p-4">
+        <div className="flex items-start justify-between gap-2">
+          <Link
+            to={`/containers/${container.id}`}
+            className="flex items-center gap-2 min-w-0 hover:underline"
+          >
+            <Box className="h-5 w-5 text-muted-foreground shrink-0" />
+            <span className="font-medium truncate" title={title}>
+              {title}
+            </span>
+          </Link>
+          <div className="flex items-center gap-1 shrink-0">
+            <StatusBadge status={container.status} />
+            {!isDeleted && (
+              <Button
+                size="icon"
+                variant="ghost"
+                className="h-7 w-7 text-muted-foreground hover:text-destructive"
+                onClick={() => onDelete(container)}
+                disabled={deleting}
+                aria-label={`Delete container ${title}`}
+              >
+                <Trash2 className="h-4 w-4" />
+              </Button>
+            )}
+          </div>
+        </div>
+
+        {container.name && (
+          <p className="mt-1 text-xs text-muted-foreground font-mono truncate">{container.id}</p>
+        )}
+
+        <div className="mt-3 flex flex-wrap items-center gap-3 text-xs text-muted-foreground">
+          <span className="flex items-center gap-1">
+            <Cpu className="h-3 w-3" />
+            {container.runtime}
+            {container.memory_limit && ` · ${container.memory_limit}`}
+          </span>
+          <span className="flex items-center gap-1">
+            <Calendar className="h-3 w-3" />
+            {formatDateTime(new Date(container.created_at * 1000))}
+          </span>
+          {container.status === "active" && (
+            <span
+              className="flex items-center gap-1"
+              title={formatDateTime(new Date(container.expires_at * 1000))}
+            >
+              <Clock className="h-3 w-3" />
+              Expires {formatRelativeTime(new Date(container.expires_at * 1000))}
+            </span>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function ContainerCardSkeleton() {
+  return (
+    <Card>
+      <CardContent className="p-4">
+        <div className="flex items-start justify-between gap-2">
+          <div className="flex items-center gap-2">
+            <Skeleton className="h-5 w-5 rounded" />
+            <Skeleton className="h-5 w-40" />
+          </div>
+          <Skeleton className="h-5 w-16" />
+        </div>
+        <div className="mt-3 flex gap-3">
+          <Skeleton className="h-3 w-20" />
+          <Skeleton className="h-3 w-24" />
+          <Skeleton className="h-3 w-20" />
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default function ContainersPage() {
+  const [search, setSearch] = useState("");
+  const { toast } = useToast();
+  const confirm = useConfirm();
+  const queryClient = useQueryClient();
+
+  const { data, isLoading, error } = useQuery({
+    ...apiV1ContainersListOptions({ query: { limit: 100 } }),
+    staleTime: 30 * 1000,
+  });
+
+  const containers = useMemo(() => {
+    const list = (data as ContainerList | undefined)?.data ?? [];
+    // Newest-first from the API; keep that order.
+    return list;
+  }, [data]);
+
+  const deleteMutation = useMutation({
+    ...apiV1ContainersDeleteMutation(),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [{ _id: "apiV1ContainersList" }] });
+      toast({ title: "Container deleted", type: "success" });
+    },
+    onError: (err) => {
+      toast({
+        title: "Failed to delete container",
+        description: formatApiError(err),
+        type: "error",
+      });
+    },
+  });
+
+  const handleDelete = async (container: Container) => {
+    const ok = await confirm({
+      title: "Delete container?",
+      message: `This permanently deletes ${
+        container.name?.trim() || container.id
+      } and all of its files. This cannot be undone.`,
+      confirmLabel: "Delete",
+      variant: "destructive",
+    });
+    if (ok) {
+      deleteMutation.mutate({ path: { container_id: container.id } });
+    }
+  };
+
+  const filtered = containers.filter((c) => {
+    const q = search.trim().toLowerCase();
+    if (!q) return true;
+    return (
+      c.id.toLowerCase().includes(q) ||
+      (c.name?.toLowerCase().includes(q) ?? false) ||
+      c.runtime.toLowerCase().includes(q)
+    );
+  });
+
+  return (
+    <div className="p-6 max-w-6xl mx-auto">
+      <div className="mb-6">
+        <h1 className="text-2xl font-semibold">Containers</h1>
+        <p className="text-sm text-muted-foreground mt-1">
+          Persistent sandboxes that back the shell tool in agent runs. Containers are created
+          automatically when a response uses the shell tool, and reaped on their idle TTL.
+        </p>
+      </div>
+
+      <div className="mb-6">
+        <Input
+          placeholder="Search containers..."
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+          className="max-w-sm"
+        />
+      </div>
+
+      {error && (
+        <div className="rounded-md bg-destructive/10 px-4 py-3 text-sm text-destructive mb-6">
+          Failed to load containers. Please try again.
+        </div>
+      )}
+
+      {isLoading && (
+        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {Array.from({ length: 6 }).map((_, i) => (
+            <ContainerCardSkeleton key={i} />
+          ))}
+        </div>
+      )}
+
+      {!isLoading && containers.length === 0 && (
+        <div className="text-center py-12">
+          <Box className="h-12 w-12 text-muted-foreground mx-auto mb-4" />
+          <h2 className="text-lg font-medium mb-2">No containers yet</h2>
+          <p className="text-sm text-muted-foreground max-w-md mx-auto">
+            Containers appear here once an agent run uses the shell tool. Enable the agent tools in
+            chat to create one.
+          </p>
+        </div>
+      )}
+
+      {!isLoading && containers.length > 0 && filtered.length === 0 && (
+        <div className="text-center py-12">
+          <Box className="h-12 w-12 text-muted-foreground mx-auto mb-4" />
+          <h2 className="text-lg font-medium mb-2">No matching containers</h2>
+          <p className="text-sm text-muted-foreground">
+            Try adjusting your search terms or{" "}
+            <button onClick={() => setSearch("")} className="text-primary hover:underline">
+              clear the search
+            </button>
+          </p>
+        </div>
+      )}
+
+      {!isLoading && filtered.length > 0 && (
+        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {filtered.map((c) => (
+            <ContainerCard
+              key={c.id}
+              container={c}
+              onDelete={handleDelete}
+              deleting={deleteMutation.isPending}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/ui/src/pages/chat/ChatPage.tsx b/ui/src/pages/chat/ChatPage.tsx
index fe7c9ef..eb9bef1 100644
--- a/ui/src/pages/chat/ChatPage.tsx
+++ b/ui/src/pages/chat/ChatPage.tsx
@@ -29,6 +29,11 @@ import {
   useMaxToolIterations,
   useCaptureRawSSEEvents,
   useSubAgentModel,
+  useAgentMemoryLimit,
+  useAgentExpiresAfterMinutes,
+  useAgentAllowedDomains,
+  useToolSearchEnabled,
+  useToolSearchRanker,
 } from "@/stores/chatUIStore";
 import { useUserSkills } from "@/hooks/useUserSkills";
 import { setSkillCatalog } from "./utils/skillCache";
@@ -66,6 +71,31 @@ export default function ChatPage() {
   const maxToolIterations = useMaxToolIterations();
   const captureRawSSEEvents = useCaptureRawSSEEvents();
   const subAgentModel = useSubAgentModel();
+  const agentMemoryLimit = useAgentMemoryLimit();
+  const agentExpiresAfterMinutes = useAgentExpiresAfterMinutes();
+  const agentAllowedDomains = useAgentAllowedDomains();
+  const toolSearchEnabled = useToolSearchEnabled();
+  const toolSearchRanker = useToolSearchRanker();
+
+  const agentConfig = useMemo(
+    () => ({
+      // The shell tool is enabled via the `agent` entry in the tools bar.
+      enabled: enabledTools.includes("agent"),
+      memoryLimit: agentMemoryLimit,
+      expiresAfterMinutes: agentExpiresAfterMinutes,
+      allowedDomains: agentAllowedDomains,
+      toolSearch: toolSearchEnabled,
+      toolSearchRanker,
+    }),
+    [
+      enabledTools,
+      agentMemoryLimit,
+      agentExpiresAfterMinutes,
+      agentAllowedDomains,
+      toolSearchEnabled,
+      toolSearchRanker,
+    ]
+  );
 
   const { setSelectedModels } = useConversationStore();
 
@@ -175,6 +205,7 @@ export default function ChatPage() {
     clearMessages,
     regenerateResponse,
     editAndRerun,
+    respondToMcpApproval,
   } = useChat({
     models: activeModels,
     settings: modelSettings,
@@ -185,6 +216,7 @@ export default function ChatPage() {
     vectorStoreIds: vectorStoreIds.length > 0 ? vectorStoreIds : undefined,
     clientSideToolExecution,
     enabledTools,
+    agentConfig,
     enabledSkills,
     dataFiles: registeredDataFiles.length > 0 ? registeredDataFiles : undefined,
     maxToolIterations,
@@ -315,6 +347,7 @@ export default function ChatPage() {
           pendingProjectName={pendingProject.name}
           pendingProjectId={pendingProject.id}
           onEditAndRerun={editAndRerun}
+          onRespondMcpApproval={respondToMcpApproval}
         />
       </ErrorBoundary>
       {currentConversation && (
diff --git a/ui/src/pages/chat/modes/types.ts b/ui/src/pages/chat/modes/types.ts
index 5d3dbd4..72b5841 100644
--- a/ui/src/pages/chat/modes/types.ts
+++ b/ui/src/pages/chat/modes/types.ts
@@ -149,11 +149,31 @@ export interface ResponsesStreamEvent {
       score: number;
       content?: Array<{ type: string; text: string }>;
     }>;
+    /** Server label for gateway MCP items (mcp_call, mcp_list_tools, mcp_approval_request) */
+    server_label?: string;
+    /** Tool name for mcp_call / mcp_approval_request items */
+    name?: string;
+    /** JSON-encoded arguments for mcp_call / mcp_approval_request items */
+    arguments?: string;
+    /** Tool output for completed mcp_call items */
+    output?: string;
+    /** Error message for failed mcp_call items */
+    error?: string | null;
+    /** Approval request id to echo back in an mcp_approval_response */
+    approval_request_id?: string;
+    /** Tools discovered by an mcp_list_tools item */
+    tools?: Array<{ name: string }>;
+    /** Shell-call action object (`shell_call` items): the commands to run. */
+    action?: { commands?: string[] };
+    /** Call id that pairs a shell_call with its shell_call_output. */
+    call_id?: string;
   };
   response?: {
     id: string;
     model: string;
     status: string;
+    /** Container the shell tool used, injected on terminal events. */
+    container_id?: string;
     output_text?: string;
     output?: Array<{
       type: string;
diff --git a/ui/src/pages/chat/useChat.ts b/ui/src/pages/chat/useChat.ts
index fc05d98..26a9e37 100644
--- a/ui/src/pages/chat/useChat.ts
+++ b/ui/src/pages/chat/useChat.ts
@@ -44,6 +44,7 @@ import {
   executeToolCalls,
   buildToolResultInputItems,
   createMCPToolName,
+  getEnabledToolsSystemGuidance,
   DISPLAY_PARAMETER_SCHEMA,
   type ToolExecutorContext,
 } from "./utils/toolExecutors";
@@ -112,6 +113,23 @@ interface UseChatOptions {
    * Each tool may have additional requirements (e.g., file_search needs vectorStoreIds).
    */
   enabledTools?: string[];
+  /**
+   * Agent mode: attaches the shell tool (+ container) and optional tool
+   * search to the request. Built from `chatUIStore` agent state in ChatPage.
+   */
+  agentConfig?: {
+    enabled: boolean;
+    /** OpenAI memory string (e.g. "512m"); empty = operator default. */
+    memoryLimit: string;
+    /** Idle TTL in minutes; null = operator default. */
+    expiresAfterMinutes: number | null;
+    /** Egress allowlist (comma/newline separated); empty = inherit. */
+    allowedDomains: string;
+    /** Attach a `tool_search` tool + defer-load gateway MCP tools. */
+    toolSearch: boolean;
+    /** Tool-search ranker override; "default" omits it (deployment default). */
+    toolSearchRanker: "default" | "hybrid" | "semantic" | "lexical";
+  };
   /**
    * Skills enabled for this session. Each skill's name + description is
    * listed in the `Skill` tool's description so the model can match user
@@ -219,6 +237,15 @@ interface UseChatReturn {
    * For assistant messages: updates content only (preserves sibling model responses).
    */
   editAndRerun: (messageId: string, newContent: string) => void;
+  /**
+   * Resume a gateway MCP tool call that paused for human approval by echoing
+   * back an `mcp_approval_response`. Single-model turns only.
+   */
+  respondToMcpApproval: (
+    assistantMessageId: string,
+    approvalRequestId: string,
+    approve: boolean
+  ) => void;
 }
 
 /** Default maximum number of tool execution iterations to prevent infinite loops */
@@ -243,6 +270,42 @@ interface StreamResponseResult {
   responseOutput?: unknown[];
 }
 
+/** One entry in a `shell_call_output` item's Hadrian `output_files` manifest. */
+interface ShellOutputFile {
+  container_id?: string;
+  file_id?: string;
+  filename?: string;
+  content_type?: string;
+  bytes?: number;
+  source?: string;
+}
+
+/**
+ * Build `container_file` artifacts from a shell `output_files` manifest. These
+ * render as message-level artifacts (images inline, other files as download
+ * chips) by lazily fetching the container content endpoint. Staged inputs
+ * (`source === "user"`) are skipped. Ids are stable (`cfile-<file_id>`) so the
+ * streamed and `response.completed` paths dedupe against each other.
+ */
+function containerFilesToArtifacts(outputFiles: ShellOutputFile[] | undefined): Artifact[] {
+  if (!outputFiles?.length) return [];
+  return outputFiles
+    .filter((f) => f.container_id && f.file_id && f.source !== "user")
+    .map((f) => ({
+      id: `cfile-${f.file_id}`,
+      type: "container_file" as const,
+      role: "output" as const,
+      title: f.filename,
+      data: {
+        containerId: f.container_id!,
+        fileId: f.file_id!,
+        filename: f.filename ?? f.file_id!,
+        contentType: f.content_type,
+        bytes: f.bytes,
+      },
+    }));
+}
+
 /** Extract the metadata fields from a streaming response for committing to the conversation store. */
 function commitFieldsFromStream(stream: StreamingResponse | undefined) {
   return {
@@ -250,6 +313,7 @@ function commitFieldsFromStream(stream: StreamingResponse | undefined) {
     artifacts: stream?.artifacts,
     toolExecutionRounds: stream?.toolExecutionRounds,
     completedRounds: stream?.completedRounds.length ? stream.completedRounds : undefined,
+    pendingMcpApprovals: stream?.mcpApprovals?.length ? stream.mcpApprovals : undefined,
   };
 }
 
@@ -263,6 +327,7 @@ export function useChat({
   vectorStoreIds,
   clientSideToolExecution = false,
   enabledTools = [],
+  agentConfig,
   enabledSkills = [],
   dataFiles = [],
   maxToolIterations = DEFAULT_maxToolIterations,
@@ -273,6 +338,10 @@ export function useChat({
 }: UseChatOptions): UseChatReturn {
   const { token } = useAuth();
   const abortControllersRef = useRef<AbortController[]>([]);
+  // Active shell container per conversation, so the whole conversation reuses
+  // one container (via `container_reference`) until it expires — then the next
+  // turn provisions a fresh one. Keyed by conversation id.
+  const activeContainerRef = useRef<Map<string, string>>(new Map());
 
   // Use zustand stores instead of local state
   const messages = useMessages();
@@ -378,10 +447,15 @@ export function useChat({
         // Priority: existing in input > instanceParams > perModelSettings > global modelSettings > default
         const hasSystemMessage = input.some((item) => item.role === "system");
         if (!hasSystemMessage) {
-          const systemPrompt =
+          const basePrompt =
             perModel?.systemPrompt ??
             modelSettings?.systemPrompt ??
             getDefaultSystemPrompt(model, instanceLabel);
+          // Append any per-tool system guidance for the enabled tools (e.g. the
+          // shell tool explaining that files written to /mnt/data are shown in
+          // the chat). Tools opt in via `systemGuidance` on their metadata.
+          const toolGuidance = getEnabledToolsSystemGuidance(enabledTools);
+          const systemPrompt = toolGuidance ? `${basePrompt}\n\n${toolGuidance}` : basePrompt;
           input.unshift({
             role: "system",
             content: systemPrompt,
@@ -848,14 +922,48 @@ export function useChat({
           });
         }
 
-        // Add MCP tools from connected servers
+        // Add MCP tools from configured servers.
         if (enabledTools.includes("mcp")) {
-          // Ensure enabled servers are connected before building tools list
-          await useMCPStore.getState().ensureConnected();
+          const allServers = useMCPStore.getState().servers;
+
+          // Gateway servers run server-side: emit a single `mcp` tool object
+          // per server and let Hadrian connect + execute. No browser
+          // connection is required, so these work for background/agent runs.
+          for (const server of allServers) {
+            if (!server.enabled || (server.runsOn ?? "browser") !== "gateway") continue;
+            const mcpTool: { type: string; [key: string]: unknown } = {
+              type: "mcp",
+              server_label: server.name || server.id,
+              server_url: server.url,
+              require_approval: server.requireApproval ?? "never",
+            };
+            if (server.headers && Object.keys(server.headers).length > 0) {
+              mcpTool.headers = server.headers;
+            }
+            if (server.allowedTools && server.allowedTools.length > 0) {
+              mcpTool.allowed_tools = server.allowedTools;
+            }
+            // With tool search on, defer-load this server's catalog so the
+            // model discovers tools lazily instead of loading every definition.
+            if (agentConfig?.toolSearch) {
+              mcpTool.defer_loading = true;
+            }
+            tools.push(mcpTool);
+          }
+
+          // Browser servers execute client-side: connect, discover, and expose
+          // each discovered tool as a `function` tool the client fulfils.
+          const hasBrowserServer = allServers.some(
+            (s) => s.enabled && (s.runsOn ?? "browser") === "browser"
+          );
+          if (hasBrowserServer) {
+            await useMCPStore.getState().ensureConnected();
+          }
           const mcpState = useMCPStore.getState();
           for (const server of mcpState.servers) {
-            // Skip disabled or disconnected servers
-            if (!server.enabled || server.status !== "connected") continue;
+            // Skip disabled, gateway, or disconnected servers
+            if (!server.enabled || (server.runsOn ?? "browser") !== "browser") continue;
+            if (server.status !== "connected") continue;
 
             for (const tool of server.tools) {
               // Check if this specific tool is enabled (default to enabled)
@@ -892,6 +1000,50 @@ export function useChat({
           }
         }
 
+        // Agent mode: attach the shell tool. Reuse the conversation's existing
+        // container if one is live; otherwise provision a fresh one with the
+        // configured limits. The captured id is refreshed from each response's
+        // terminal event (and cleared on error) below.
+        if (agentConfig?.enabled) {
+          const conv = conversationIdRef.current;
+          const reuseId = conv ? activeContainerRef.current.get(conv) : undefined;
+          let environment: Record<string, unknown>;
+          if (reuseId) {
+            environment = { type: "container_reference", container_id: reuseId };
+          } else {
+            environment = { type: "container_auto" };
+            if (agentConfig.memoryLimit.trim()) {
+              environment.memory_limit = agentConfig.memoryLimit.trim();
+            }
+            if (agentConfig.expiresAfterMinutes && agentConfig.expiresAfterMinutes > 0) {
+              environment.expires_after = {
+                anchor: "last_active_at",
+                minutes: agentConfig.expiresAfterMinutes,
+              };
+            }
+            const allowedDomains = agentConfig.allowedDomains
+              .split(/[\n,]/)
+              .map((d) => d.trim())
+              .filter(Boolean);
+            if (allowedDomains.length > 0) {
+              environment.network_policy = {
+                type: "allowlist",
+                allowed_domains: allowedDomains,
+              };
+            }
+          }
+          tools.push({ type: "shell", environment });
+        }
+
+        // Tool search: let the model search for / lazily load tools.
+        if (agentConfig?.toolSearch) {
+          const toolSearchTool: { type: string; [key: string]: unknown } = { type: "tool_search" };
+          if (agentConfig.toolSearchRanker && agentConfig.toolSearchRanker !== "default") {
+            toolSearchTool.ranker = agentConfig.toolSearchRanker;
+          }
+          tools.push(toolSearchTool);
+        }
+
         // Add tools to request if any are configured
         if (tools.length > 0) {
           requestBody.tools = tools;
@@ -919,6 +1071,65 @@ export function useChat({
         const decoder = new TextDecoder();
         let content = "";
         let reasoningContent = "";
+        // Server-side multi-turn tracking. A single `/v1/responses` can carry
+        // several model turns (the gateway runs its own tool loop for shell /
+        // MCP). Each turn is a distinct reasoning item; when a new reasoning
+        // item id appears we flush the prior turn's reasoning+content as a
+        // completed round instead of overwriting it. `null` until the first
+        // reasoning item is seen.
+        let currentReasoningItemId: string | null = null;
+        // Server-side tool executions for the current turn, surfaced in the
+        // "reasoning & tools" disclosure. Built from the spec items the gateway
+        // streams (shell_call/shell_call_output, mcp_call, tool_search) and
+        // attached to each completed round so they persist on the message.
+        let serverRound = 0;
+        let roundExecutions: ToolExecution[] = [];
+        const pendingShell = new Map<string, { command: string; startTime: number }>();
+        let lastToolSearchQuery = "";
+        const codeArtifact = (
+          id: string,
+          role: "input" | "output",
+          language: string,
+          code: string,
+          title?: string
+        ): Artifact => ({ id, type: "code", role, title, data: { language, code } });
+        const recordServerExecution = (exec: ToolExecution) => {
+          roundExecutions.push(exec);
+        };
+        const takeRoundExecution = (): ToolExecutionRound | undefined => {
+          if (roundExecutions.length === 0) return undefined;
+          const round: ToolExecutionRound = {
+            round: serverRound,
+            executions: roundExecutions,
+            hasError: roundExecutions.some((e) => e.status === "error"),
+          };
+          roundExecutions = [];
+          return round;
+        };
+
+        const flushServerTurn = (nextItemId?: string) => {
+          if (!nextItemId) return;
+          if (currentReasoningItemId === null) {
+            currentReasoningItemId = nextItemId;
+            return;
+          }
+          if (nextItemId === currentReasoningItemId) return;
+          // New reasoning item → previous server turn finished. Commit it as a
+          // round so its reasoning isn't overwritten by the next turn.
+          const round: CompletedRound = {};
+          if (reasoningContent.trim()) round.reasoning = reasoningContent;
+          if (content.trim()) round.content = content;
+          const toolExecution = takeRoundExecution();
+          if (toolExecution) round.toolExecution = toolExecution;
+          if (round.reasoning || round.content || round.toolExecution) {
+            streamingStore.pushCompletedRound(storeKey, round);
+            reasoningContent = "";
+            content = "";
+            hasOutputText = false;
+          }
+          serverRound += 1;
+          currentReasoningItemId = nextItemId;
+        };
         // Spec-compliant SSE parser — handles `\r\n`/`\r`/`\n`, multi-line
         // `data:` fields joined with `\n`, and dispatches events on blank
         // lines instead of every `data:` line.
@@ -1003,6 +1214,9 @@ export function useChat({
                 event.type === "response.reasoning_summary_text.delta") &&
               event.delta
             ) {
+              // A new reasoning item id means a new server-side turn — commit
+              // the prior turn before accumulating this one.
+              flushServerTurn(event.item_id);
               // Stream reasoning content (extended thinking)
               reasoningContent += event.delta;
               streamingStore.appendReasoningContent(storeKey, event.delta);
@@ -1011,6 +1225,7 @@ export function useChat({
                 event.type === "response.reasoning_summary_text.done") &&
               event.text
             ) {
+              flushServerTurn(event.item_id);
               // Final reasoning text
               reasoningContent = event.text;
               streamingStore.setReasoningContent(storeKey, reasoningContent);
@@ -1053,6 +1268,232 @@ export function useChat({
                   role: "output",
                 };
                 streamingStore.addArtifacts(storeKey, [artifact]);
+              } else if (event.item.type === "mcp_list_tools") {
+                // Gateway MCP discovered a server's tools.
+                const itemId = event.item.id ?? `mcp_list_${Date.now()}`;
+                const label = event.item.server_label ?? "mcp";
+                const count = event.item.tools?.length ?? 0;
+                const ts = Date.now();
+                streamingStore.addToolCall(storeKey, {
+                  id: itemId,
+                  callId: itemId,
+                  name: `${label}: list tools`,
+                  outputIndex: event.output_index ?? 0,
+                  argumentsBuffer: "",
+                  status: "pending",
+                });
+                streamingStore.completeToolCall(storeKey, itemId, { count });
+                recordServerExecution({
+                  id: itemId,
+                  toolName: `${label}: list tools`,
+                  status: "success",
+                  startTime: ts,
+                  endTime: ts,
+                  input: { server_label: label },
+                  inputArtifacts: [],
+                  outputArtifacts: [
+                    codeArtifact(
+                      `${itemId}-out`,
+                      "output",
+                      "text",
+                      `Loaded ${count} tool${count === 1 ? "" : "s"} from ${label}`
+                    ),
+                  ],
+                  round: serverRound,
+                });
+              } else if (event.item.type === "mcp_call") {
+                // Gateway-executed MCP tool call.
+                const itemId = event.item.id ?? `mcp_call_${Date.now()}`;
+                const label = event.item.server_label ?? "mcp";
+                const name = event.item.name ?? "tool";
+                const ts = Date.now();
+                streamingStore.addToolCall(storeKey, {
+                  id: itemId,
+                  callId: itemId,
+                  name: `${label}.${name}`,
+                  outputIndex: event.output_index ?? 0,
+                  argumentsBuffer: event.item.arguments ?? "",
+                  status: "pending",
+                });
+                let parsedArgs: Record<string, unknown> = {};
+                try {
+                  parsedArgs = event.item.arguments ? JSON.parse(event.item.arguments) : {};
+                } catch {
+                  // Leave args unparsed; the buffer still renders.
+                }
+                const errored = !!event.item.error;
+                if (errored) {
+                  streamingStore.setToolCallError(storeKey, itemId, event.item.error!);
+                } else {
+                  streamingStore.completeToolCall(storeKey, itemId, parsedArgs);
+                }
+                recordServerExecution({
+                  id: itemId,
+                  toolName: `${label}.${name}`,
+                  status: errored ? "error" : "success",
+                  startTime: ts,
+                  endTime: ts,
+                  input: parsedArgs,
+                  error: event.item.error ?? undefined,
+                  inputArtifacts: event.item.arguments?.trim()
+                    ? [
+                        codeArtifact(
+                          `${itemId}-in`,
+                          "input",
+                          "json",
+                          JSON.stringify(parsedArgs, null, 2)
+                        ),
+                      ]
+                    : [],
+                  outputArtifacts: event.item.output
+                    ? [codeArtifact(`${itemId}-out`, "output", "text", event.item.output)]
+                    : [],
+                  round: serverRound,
+                });
+              } else if (
+                event.item.type === "mcp_approval_request" &&
+                event.item.approval_request_id
+              ) {
+                // Gateway MCP paused for human approval. Record it on the
+                // stream so it commits to the message and renders an
+                // approve/deny prompt the user can resume from.
+                let parsedArgs: Record<string, unknown> = {};
+                try {
+                  parsedArgs = event.item.arguments ? JSON.parse(event.item.arguments) : {};
+                } catch {
+                  // Non-JSON args — render the raw string instead.
+                }
+                streamingStore.addMcpApproval(storeKey, {
+                  id: event.item.id ?? event.item.approval_request_id,
+                  approvalRequestId: event.item.approval_request_id,
+                  serverLabel: event.item.server_label ?? "mcp",
+                  toolName: event.item.name ?? "tool",
+                  argumentsJson: event.item.arguments ?? "",
+                  parsedArguments: parsedArgs,
+                });
+              } else if (event.item.type === "shell_call") {
+                // Hadrian-hosted shell tool ran a command. Show the command as a
+                // live indicator; the paired shell_call_output carries the result.
+                const itemId = event.item.id ?? `shell_${Date.now()}`;
+                const commands = event.item.action?.commands ?? [];
+                streamingStore.addToolCall(storeKey, {
+                  id: itemId,
+                  callId: itemId,
+                  name: "shell",
+                  outputIndex: event.output_index ?? 0,
+                  argumentsBuffer: commands.join("\n"),
+                  status: "pending",
+                });
+                streamingStore.completeToolCall(storeKey, itemId, { commands });
+                const callId = event.item.call_id ?? itemId;
+                pendingShell.set(callId, {
+                  command: commands.join("\n"),
+                  startTime: Date.now(),
+                });
+              } else if (event.item.type === "shell_call_output") {
+                // Result of a shell_call. Pair with the command and record a
+                // completed execution carrying the command + stdout/stderr/exit.
+                const callId = event.item.call_id ?? event.item.id ?? `shell_${Date.now()}`;
+                const pending = pendingShell.get(callId);
+                pendingShell.delete(callId);
+                const blocks =
+                  (
+                    event.item as {
+                      output?: Array<{
+                        stdout?: string;
+                        stderr?: string;
+                        outcome?: { type?: string; exit_code?: number };
+                      }>;
+                    }
+                  ).output ?? [];
+                const stdout = blocks.map((b) => b.stdout ?? "").join("");
+                const stderr = blocks.map((b) => b.stderr ?? "").join("");
+                const outcome = blocks[0]?.outcome;
+                const exitCode = outcome?.exit_code ?? 0;
+                const errored = (!!outcome?.type && outcome.type !== "exit") || exitCode !== 0;
+                const outText =
+                  [stdout, stderr.trim() ? `[stderr]\n${stderr}` : "", `[exit ${exitCode}]`]
+                    .filter(Boolean)
+                    .join("\n") || "(no output)";
+                const now = Date.now();
+                // Files the command wrote to /mnt/data surface as prominent
+                // message-level artifacts (images inline, others as download
+                // chips). Dedup-by-id means the response.completed sweep below
+                // is harmless if these also arrive only in the final output.
+                const fileArtifacts = containerFilesToArtifacts(
+                  (event.item as { output_files?: ShellOutputFile[] }).output_files
+                );
+                if (fileArtifacts.length > 0) {
+                  streamingStore.addArtifacts(storeKey, fileArtifacts);
+                }
+                recordServerExecution({
+                  id: event.item.id ?? `shellout_${now}`,
+                  toolName: "shell",
+                  status: errored ? "error" : "success",
+                  startTime: pending?.startTime ?? now,
+                  endTime: now,
+                  input: { command: pending?.command ?? "" },
+                  inputArtifacts: pending?.command
+                    ? [codeArtifact(`${callId}-in`, "input", "bash", pending.command)]
+                    : [],
+                  outputArtifacts: [codeArtifact(`${callId}-out`, "output", "text", outText)],
+                  error: errored ? `exit ${exitCode}` : undefined,
+                  round: serverRound,
+                });
+              } else if (event.item.type === "tool_search_call") {
+                // Model searched the deferred tool catalog. Show the query.
+                const itemId = event.item.id ?? `ts_${Date.now()}`;
+                streamingStore.addToolCall(storeKey, {
+                  id: itemId,
+                  callId: itemId,
+                  name: "tool_search",
+                  outputIndex: event.output_index ?? 0,
+                  argumentsBuffer: event.item.arguments ?? "",
+                  status: "pending",
+                });
+                let parsedArgs: Record<string, unknown> = {};
+                try {
+                  parsedArgs = event.item.arguments ? JSON.parse(event.item.arguments) : {};
+                } catch {
+                  // Leave unparsed; the buffer still renders.
+                }
+                streamingStore.completeToolCall(storeKey, itemId, parsedArgs);
+                lastToolSearchQuery = typeof parsedArgs.query === "string" ? parsedArgs.query : "";
+              } else if (event.item.type === "tool_search_output") {
+                // Tools were loaded from the search — show the query + how many.
+                const itemId = event.item.id ?? `tso_${Date.now()}`;
+                const count = event.item.tools?.length ?? 0;
+                const now = Date.now();
+                streamingStore.addToolCall(storeKey, {
+                  id: itemId,
+                  callId: itemId,
+                  name: "tool_search: loaded tools",
+                  outputIndex: event.output_index ?? 0,
+                  argumentsBuffer: "",
+                  status: "pending",
+                });
+                streamingStore.completeToolCall(storeKey, itemId, { count });
+                recordServerExecution({
+                  id: itemId,
+                  toolName: "tool_search",
+                  status: "success",
+                  startTime: now,
+                  endTime: now,
+                  input: { query: lastToolSearchQuery },
+                  inputArtifacts: lastToolSearchQuery
+                    ? [codeArtifact(`${itemId}-in`, "input", "text", lastToolSearchQuery)]
+                    : [],
+                  outputArtifacts: [
+                    codeArtifact(
+                      `${itemId}-out`,
+                      "output",
+                      "text",
+                      `Loaded ${count} tool${count === 1 ? "" : "s"}`
+                    ),
+                  ],
+                  round: serverRound,
+                });
+                lastToolSearchQuery = "";
               }
             } else if (event.type === "response.file_search_call.in_progress") {
               // Server-side file search starting - add tool call to streaming store
@@ -1111,6 +1552,29 @@ export function useChat({
                 streamingStore.completeToolCall(storeKey, event.item_id, {});
               }
             } else if (event.type === "response.completed" && event.response) {
+              // Remember the container this response used so the rest of the
+              // conversation reuses it (until it expires and a turn fails — see
+              // the catch below, which clears it so the next turn starts fresh).
+              const convId = conversationIdRef.current;
+              if (event.response.container_id && convId) {
+                activeContainerRef.current.set(convId, event.response.container_id);
+              }
+              // Harvest container files from the final output. Some providers
+              // (e.g. OpenRouter-routed models) deliver shell_call_output items
+              // only in `response.output` rather than as streamed
+              // `output_item.done` events, so the streamed handler above never
+              // sees them. Sweeping here makes generated files show regardless;
+              // addArtifacts dedupes by id against the streamed path.
+              const finalFileArtifacts = (event.response.output ?? [])
+                .filter((item) => item.type === "shell_call_output")
+                .flatMap((item) =>
+                  containerFilesToArtifacts(
+                    (item as { output_files?: ShellOutputFile[] }).output_files
+                  )
+                );
+              if (finalFileArtifacts.length > 0) {
+                streamingStore.addArtifacts(storeKey, finalFileArtifacts);
+              }
               // Extract final text from completed response
               // First try output_text, then message content, then reasoning content as fallback
               const outputText =
@@ -1267,12 +1731,17 @@ export function useChat({
         const trackerToolCalls = toolTracker ? toolTracker.getCompletedToolCalls() : [];
         const toolCalls = trackerToolCalls.length > 0 ? trackerToolCalls : completedToolCalls;
 
+        // The final server turn's tool executions never hit a turn boundary,
+        // so hand them to the caller to attach to the last completed round.
+        const finalServerRound = takeRoundExecution();
+
         return {
           content,
           hasOutputText,
           usage,
           reasoningContent: reasoningContent || undefined,
           toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+          toolExecutionRounds: finalServerRound ? [finalServerRound] : undefined,
           requestBody,
           responseOutput,
         };
@@ -1282,6 +1751,11 @@ export function useChat({
         }
 
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        // Drop the reused container so the next turn provisions a fresh one —
+        // an expired/deleted container is the most likely cause of a failure
+        // mid-conversation once agent mode is on.
+        const convId = conversationIdRef.current;
+        if (convId) activeContainerRef.current.delete(convId);
         streamingStore.setError(storeKey, errorMessage);
         return null;
       }
@@ -1292,6 +1766,7 @@ export function useChat({
       perModelSettings,
       vectorStoreIds,
       enabledTools,
+      agentConfig,
       enabledSkills,
       dataFiles,
     ]
@@ -1422,6 +1897,12 @@ export function useChat({
           const roundData: CompletedRound = {};
           if (result.reasoningContent) roundData.reasoning = result.reasoningContent;
           if (result.hasOutputText && result.content?.trim()) roundData.content = result.content;
+          // Attach the final server turn's tool executions (shell/MCP/tool_search)
+          // so they render in the "reasoning & tools" disclosure and persist.
+          if (result.toolExecutionRounds?.length) {
+            roundData.toolExecution =
+              result.toolExecutionRounds[result.toolExecutionRounds.length - 1];
+          }
           streamingStore.pushCompletedRound(storeKey, roundData);
           result.completedRounds = [roundData];
         }
@@ -2082,6 +2563,94 @@ export function useChat({
     ]
   );
 
+  /**
+   * Resume a gateway MCP tool call that paused for human approval.
+   *
+   * Re-streams the assistant turn with an `mcp_approval_response` input item
+   * appended; Hadrian claims the parked approval by `approvalRequestId`,
+   * runs (or refuses) the call, and continues the model loop. The continued
+   * output is appended to the same assistant message. Single-model turns only
+   * — gateway MCP approvals aren't surfaced in multi-model modes.
+   */
+  const respondToMcpApproval = useCallback(
+    async (assistantMessageId: string, approvalRequestId: string, approve: boolean) => {
+      // Don't start an approval-resume turn while another turn is
+      // streaming — it would clobber the active AbortController and race
+      // the in-flight stream. The button is also disabled in this state
+      // (see ChatMessageList), this is the belt-and-suspenders guard.
+      if (useStreamingStore.getState().isStreaming) return;
+      // Read messages live from the store rather than the closed-over
+      // snapshot so the resumed request is built from current state, not
+      // whatever was rendered when the handler was created.
+      const liveMessages = useConversationStore.getState().messages;
+      const idx = liveMessages.findIndex((m) => m.id === assistantMessageId);
+      if (idx === -1) return;
+      const assistantMessage = liveMessages[idx];
+      if (assistantMessage.role !== "assistant") return;
+
+      const model = assistantMessage.model ?? models[0];
+      if (!model) return;
+      const sendEpoch = conversationIdRef.current;
+
+      // Optimistically record the decision so the prompt flips to resolved.
+      const resolvedApprovals = (assistantMessage.pendingMcpApprovals ?? []).map((a) =>
+        a.approvalRequestId === approvalRequestId
+          ? { ...a, resolved: approve ? ("approved" as const) : ("denied" as const) }
+          : a
+      );
+      updateMessage(assistantMessageId, { pendingMcpApprovals: resolvedApprovals });
+
+      // Build history through this assistant turn, then echo the approval back.
+      const messagesThroughAssistant = liveMessages.slice(0, idx + 1);
+      const filtered = filterMessagesForModel(messagesThroughAssistant, model, historyMode);
+      const inputItems = [
+        ...filtered.map(messageToApiInput),
+        {
+          type: "mcp_approval_response",
+          approval_request_id: approvalRequestId,
+          approve,
+        },
+      ];
+
+      streamingStore.initStreaming([model]);
+      const controller = new AbortController();
+      abortControllersRef.current = [controller];
+      const debugMessageId = `msg_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+      const result = await streamWithToolExecution(
+        model,
+        inputItems,
+        controller,
+        settings,
+        model,
+        debugMessageId
+      );
+
+      if (result !== null && sendEpoch === conversationIdRef.current) {
+        const stream = useStreamingStore.getState().streams.get(model);
+        const committed = commitFieldsFromStream(stream);
+        const continued = result.content
+          ? `${assistantMessage.content ? `${assistantMessage.content}\n\n` : ""}${result.content}`
+          : assistantMessage.content;
+        updateMessage(assistantMessageId, {
+          content: continued,
+          usage: result.usage ?? assistantMessage.usage,
+          ...committed,
+          // Preserve the resolved decision unless the continuation parked a new one.
+          pendingMcpApprovals: committed.pendingMcpApprovals ?? resolvedApprovals,
+        });
+      }
+
+      streamingStore.clearStreams();
+      abortControllersRef.current = [];
+    },
+    // `messages` is intentionally not a dep: the handler reads live store
+    // state (useConversationStore.getState()) so it can't act on a stale
+    // snapshot, and keeping the callback identity stable lets the
+    // disabled-while-streaming guard in ChatMessageList stay reliable.
+    [models, settings, historyMode, streamWithToolExecution, streamingStore, updateMessage]
+  );
+
   /**
    * Edit a message and re-run the conversation from that point.
    * For user messages: updates content, deletes all subsequent messages, and streams new responses.
@@ -2227,5 +2796,6 @@ export function useChat({
     setMessages,
     regenerateResponse,
     editAndRerun,
+    respondToMcpApproval,
   };
 }
diff --git a/ui/src/pages/chat/utils/toolExecutors.ts b/ui/src/pages/chat/utils/toolExecutors.ts
index db7127f..19943af 100644
--- a/ui/src/pages/chat/utils/toolExecutors.ts
+++ b/ui/src/pages/chat/utils/toolExecutors.ts
@@ -80,8 +80,25 @@ export type ArtifactType =
   | "html"
   | "agent"
   | "file_search"
+  | "container_file"
   | "display_selection";
 
+/**
+ * Container file artifact data — a file written to `/mnt/data` by the shell
+ * tool. The bytes aren't inlined; the renderer lazily fetches them from
+ * `GET /v1/containers/{containerId}/files/{fileId}/content` (authed), showing
+ * images inline and other files as a download chip.
+ */
+export interface ContainerFileArtifactData {
+  containerId: string;
+  fileId: string;
+  filename: string;
+  /** Best-effort MIME type (e.g. "image/png"). */
+  contentType?: string;
+  /** Size in bytes, for the download chip. */
+  bytes?: number;
+}
+
 /**
  * Role of an artifact in the execution timeline
  * - 'input': Code, queries, or other inputs shown to the tool (collapsed by default)
@@ -2703,12 +2720,46 @@ export interface ToolMetadata {
   requiresConfig?: boolean;
   /** Config requirement description */
   configDescription?: string;
+  /**
+   * Extra guidance appended to the system prompt when this tool is enabled.
+   * Use it for UI-specific behavior the tool's own API description can't carry
+   * (e.g. "files you write are shown in this chat"). Optional — most tools
+   * rely solely on their API-level description.
+   */
+  systemGuidance?: string;
+}
+
+/**
+ * Concatenated system-prompt guidance for the enabled tools that define it.
+ * Appended after the base system prompt in `useChat`. Empty when no enabled
+ * tool contributes guidance.
+ */
+export function getEnabledToolsSystemGuidance(enabledToolIds: string[]): string {
+  const enabled = new Set(enabledToolIds);
+  return TOOL_METADATA.filter((t) => enabled.has(t.id) && t.systemGuidance)
+    .map((t) => t.systemGuidance!)
+    .join("\n\n");
 }
 
 /**
  * Available tools with metadata for UI display
  */
 export const TOOL_METADATA: ToolMetadata[] = [
+  {
+    id: "agent",
+    name: "Agent (Shell)",
+    description:
+      "Run shell commands in a persistent server-side container. Files persist across turns in /mnt/data, and the whole conversation reuses one container until it expires. Configure the container in this tool's settings.",
+    icon: "SquareTerminal",
+    implemented: true,
+    systemGuidance: `## Shell tool & file output
+
+You have a shell tool that runs commands in a persistent Linux container; \`/mnt/data\` is the working directory and persists for the whole conversation.
+
+Files you save to \`/mnt/data\` are shown to the user directly in this chat — images render inline and other files appear as downloads. So when you produce a visual or downloadable result (a plot, generated image, rendered document, data export, etc.), **save it to \`/mnt/data\`** rather than only printing it or describing it.
+
+The gateway attaches and displays saved files automatically — you do not link to them. Do NOT reference container paths with Markdown image or link syntax: \`![red_square.png](/mnt/data/red_square.png)\` (or a plain link to \`/mnt/data/...\`) will **not** render, because \`/mnt/data\` is a path inside the container, not a URL the chat can load. Likewise, never paste base64-encoded image or file data into your reply. Just write the file and mention its name in prose (e.g. "I saved the chart as \`red_square.png\`"); it will appear on its own.`,
+  },
   {
     id: "file_search",
     name: "File Search",
@@ -2787,10 +2838,10 @@ export const TOOL_METADATA: ToolMetadata[] = [
   },
   {
     id: "sub_agent",
-    name: "Sub-Agent",
+    name: "Sub-agent",
     description:
-      "Delegate investigative tasks to a separate AI agent. Best for research, analysis, or focused subtasks that benefit from isolated context.",
-    icon: "Bot",
+      "Delegate a focused subtask to a separate model that runs its own tool loop and reports back. Unlike the Agent (Shell) tool, this spawns a nested LLM with isolated context — it does not run shell commands itself. Best for research and analysis.",
+    icon: "Users",
     implemented: true,
   },
   {
diff --git a/ui/src/pages/containers/types.ts b/ui/src/pages/containers/types.ts
new file mode 100644
index 0000000..2824cd6
--- /dev/null
+++ b/ui/src/pages/containers/types.ts
@@ -0,0 +1,68 @@
+/**
+ * Local types for the Containers API.
+ *
+ * The generated client (`ui/src/api/generated`) types the list/get/file
+ * response bodies as `unknown` (the backend `#[utoipa::path]` annotations
+ * don't carry a body schema for these endpoints yet). These mirror the
+ * wire shapes serialized by `src/routes/api/containers.rs` — `WireContainer`,
+ * `WireContainerFile`, and `WireList<T>` — so the page code is typed.
+ *
+ * All timestamps are Unix **seconds** (multiply by 1000 for `Date`).
+ */
+
+export type ContainerStatus = "active" | "expired" | "deleted";
+
+export interface ContainerExpiresAfter {
+  anchor: string;
+  minutes: number;
+}
+
+export interface Container {
+  id: string;
+  object: "container";
+  status: ContainerStatus;
+  created_at: number;
+  last_active_at: number;
+  /** Forward-looking expiry estimate for active rows; transition time otherwise. */
+  expires_at: number;
+  idle_ttl_secs: number;
+  runtime: string;
+  name?: string;
+  memory_limit?: string;
+  memory_limit_mb?: number;
+  expires_after?: ContainerExpiresAfter;
+  network_policy?: unknown;
+  skill_ids?: string[];
+  source_response_id?: string;
+}
+
+export type ContainerFileSource = "user" | "assistant";
+
+export interface ContainerFile {
+  id: string;
+  object: "container.file";
+  container_id: string;
+  /** Absolute path inside the container, always under `/mnt/data/`. */
+  path: string;
+  filename: string;
+  bytes: number;
+  source: ContainerFileSource;
+  content_type?: string;
+  created_at: number;
+}
+
+export interface ContainerList {
+  object: "list";
+  data: Container[];
+  has_more: boolean;
+  first_id?: string;
+  last_id?: string;
+}
+
+export interface ContainerFileList {
+  object: "list";
+  data: ContainerFile[];
+  has_more: boolean;
+  first_id?: string;
+  last_id?: string;
+}
diff --git a/ui/src/routes/AppRoutes.tsx b/ui/src/routes/AppRoutes.tsx
index f38dbd4..ad62f2c 100644
--- a/ui/src/routes/AppRoutes.tsx
+++ b/ui/src/routes/AppRoutes.tsx
@@ -13,6 +13,8 @@ const AccountPage = lazy(() => import("@/pages/AccountPage"));
 const ProjectsPage = lazy(() => import("@/pages/ProjectsPage"));
 const TeamsPage = lazy(() => import("@/pages/TeamsPage"));
 const KnowledgeBasesPage = lazy(() => import("@/pages/KnowledgeBasesPage"));
+const ContainersPage = lazy(() => import("@/pages/ContainersPage"));
+const ContainerDetailPage = lazy(() => import("@/pages/ContainerDetailPage"));
 const ApiKeysPage = lazy(() => import("@/pages/ApiKeysPage"));
 const ApiKeyDetailPage = lazy(() => import("@/pages/ApiKeyDetailPage"));
 const MyUsagePage = lazy(() => import("@/pages/MyUsagePage"));
@@ -175,6 +177,28 @@ export function AppRoutes() {
           }
         />
 
+        {/* Containers routes */}
+        <Route
+          path="/containers"
+          element={
+            <Suspense fallback={<PageLoader />}>
+              <PageGuard pageKey="containers" pageTitle="Containers">
+                <ContainersPage />
+              </PageGuard>
+            </Suspense>
+          }
+        />
+        <Route
+          path="/containers/:containerId"
+          element={
+            <Suspense fallback={<PageLoader />}>
+              <PageGuard pageKey="containers" pageTitle="Containers">
+                <ContainerDetailPage />
+              </PageGuard>
+            </Suspense>
+          }
+        />
+
         {/* API Keys routes */}
         <Route
           path="/api-keys"
diff --git a/ui/src/services/mcp/types.ts b/ui/src/services/mcp/types.ts
index bfd34f2..1a0023d 100644
--- a/ui/src/services/mcp/types.ts
+++ b/ui/src/services/mcp/types.ts
@@ -328,6 +328,22 @@ export interface MCPOAuthConfig {
 /** MCP Server connection status */
 export type MCPConnectionStatus = "disconnected" | "connecting" | "connected" | "error";
 
+/**
+ * Where an MCP server's tool calls execute.
+ *
+ * - `browser` (default): the browser connects to the server, discovers tools,
+ *   and executes calls client-side (the existing behavior). Only works inside
+ *   the chat UI.
+ * - `gateway`: Hadrian connects to the server and runs the calls server-side.
+ *   The server config is sent as an `mcp` tool in the `/v1/responses` request,
+ *   so it works for background/agent runs and for API clients — but credentials
+ *   (`headers`/`authorization`) leave the browser with the request.
+ */
+export type MCPRunsOn = "browser" | "gateway";
+
+/** Approval gating for gateway-executed MCP tools. */
+export type MCPRequireApproval = "always" | "never";
+
 /** MCP Server configuration */
 export interface MCPServerConfig {
   /** Unique identifier */
@@ -346,6 +362,18 @@ export interface MCPServerConfig {
   authType?: MCPAuthType;
   /** OAuth configuration (when authType is "oauth") */
   oauth?: MCPOAuthConfig;
+  /** Where tool calls execute (default: "browser"). */
+  runsOn?: MCPRunsOn;
+  /**
+   * Approval gating for gateway-executed tools (default: "never").
+   * Only meaningful when `runsOn === "gateway"`.
+   */
+  requireApproval?: MCPRequireApproval;
+  /**
+   * Restrict the gateway to this subset of tool names (empty/undefined = all).
+   * Only meaningful when `runsOn === "gateway"`.
+   */
+  allowedTools?: string[];
 }
 
 /** MCP Server state (config + runtime state) */
diff --git a/ui/src/stores/chatUIStore.ts b/ui/src/stores/chatUIStore.ts
index 5bca1f2..569bb43 100644
--- a/ui/src/stores/chatUIStore.ts
+++ b/ui/src/stores/chatUIStore.ts
@@ -223,6 +223,32 @@ interface ChatUIState {
    * rounds without content to minimal "Thinking" / "Processing" indicators.
    */
   compactMode: boolean;
+
+  // --- Agent mode (shell tool + container) ---
+  // The shell tool is enabled via the `agent` entry in `enabledTools`
+  // (ToolsBar); these fields configure the container a new conversation
+  // provisions. The conversation then reuses that container until it expires
+  // (handled in useChat), so there's no manual container picker.
+  /** Memory ceiling (OpenAI string, e.g. "512m"/"1g"). Empty = operator default. */
+  agentMemoryLimit: string;
+  /** Idle TTL in minutes for a new container. Null = operator default. */
+  agentExpiresAfterMinutes: number | null;
+  /**
+   * Egress allowlist (comma/newline separated). Defaults to `*` (any host,
+   * subject to the operator's `allowed_egress_hosts` ceiling). Empty = deny-all.
+   */
+  agentAllowedDomains: string;
+  /**
+   * Let the model search for tools / defer-load them (`tool_search`).
+   * Keeps context small when many MCP tools are attached.
+   */
+  toolSearchEnabled: boolean;
+  /**
+   * Ranking strategy override for tool search. `"default"` omits the field
+   * (deployment default applies). `"semantic"`/`"hybrid"` need an embedding
+   * provider — the gateway rejects them with 400 otherwise.
+   */
+  toolSearchRanker: "default" | "hybrid" | "semantic" | "lexical";
 }
 
 interface ChatUIActions {
@@ -347,6 +373,13 @@ interface ChatUIActions {
   setCompactMode: (enabled: boolean) => void;
   /** Toggle compact mode */
   toggleCompactMode: () => void;
+
+  // --- Agent mode setters ---
+  setAgentMemoryLimit: (value: string) => void;
+  setAgentExpiresAfterMinutes: (minutes: number | null) => void;
+  setAgentAllowedDomains: (value: string) => void;
+  setToolSearchEnabled: (enabled: boolean) => void;
+  setToolSearchRanker: (ranker: "default" | "hybrid" | "semantic" | "lexical") => void;
 }
 
 export type ChatUIStore = ChatUIState & ChatUIActions;
@@ -410,6 +443,11 @@ const initialState: ChatUIState = {
   pendingPrompt: null,
   subAgentModel: null,
   compactMode: loadCompactMode(),
+  agentMemoryLimit: "",
+  agentExpiresAfterMinutes: null,
+  agentAllowedDomains: "*",
+  toolSearchEnabled: false,
+  toolSearchRanker: "default",
 };
 
 export const useChatUIStore = create<ChatUIStore>((set) => ({
@@ -702,6 +740,12 @@ export const useChatUIStore = create<ChatUIStore>((set) => ({
       }
       return { compactMode: next };
     }),
+
+  setAgentMemoryLimit: (value) => set({ agentMemoryLimit: value }),
+  setAgentExpiresAfterMinutes: (minutes) => set({ agentExpiresAfterMinutes: minutes }),
+  setAgentAllowedDomains: (value) => set({ agentAllowedDomains: value }),
+  setToolSearchEnabled: (enabled) => set({ toolSearchEnabled: enabled }),
+  setToolSearchRanker: (ranker) => set({ toolSearchRanker: ranker }),
 }));
 
 /**
@@ -846,3 +890,15 @@ export const useCompactMode = () => useChatUIStore((state: ChatUIState) => state
 /** Get MCP config modal open state */
 export const useMCPConfigModalOpen = () =>
   useChatUIStore((state: ChatUIState) => state.mcpConfigModalOpen);
+
+// --- Agent mode selectors ---
+export const useAgentMemoryLimit = () =>
+  useChatUIStore((state: ChatUIState) => state.agentMemoryLimit);
+export const useAgentExpiresAfterMinutes = () =>
+  useChatUIStore((state: ChatUIState) => state.agentExpiresAfterMinutes);
+export const useAgentAllowedDomains = () =>
+  useChatUIStore((state: ChatUIState) => state.agentAllowedDomains);
+export const useToolSearchEnabled = () =>
+  useChatUIStore((state: ChatUIState) => state.toolSearchEnabled);
+export const useToolSearchRanker = () =>
+  useChatUIStore((state: ChatUIState) => state.toolSearchRanker);
diff --git a/ui/src/stores/mcpStore.ts b/ui/src/stores/mcpStore.ts
index abf5ebe..73ceb04 100644
--- a/ui/src/stores/mcpStore.ts
+++ b/ui/src/stores/mcpStore.ts
@@ -492,7 +492,12 @@ export const useMCPStore = create<MCPStore>()(
       ensureConnected: async () => {
         const { servers } = get();
         const needsConnect = servers.filter(
-          (s) => s.enabled && s.status !== "connected" && s.status !== "connecting"
+          (s) =>
+            s.enabled &&
+            // Gateway servers run server-side — never connect them in the browser.
+            (s.runsOn ?? "browser") === "browser" &&
+            s.status !== "connected" &&
+            s.status !== "connecting"
         );
         await Promise.all(
           needsConnect.map((s) =>
@@ -549,6 +554,9 @@ export const useMCPStore = create<MCPStore>()(
           timeout: s.timeout,
           authType: s.authType,
           oauth: s.oauth,
+          runsOn: s.runsOn,
+          requireApproval: s.requireApproval,
+          allowedTools: s.allowedTools,
           // Persist tool enable/disable preferences
           toolsEnabled: s.toolsEnabled,
         })),
diff --git a/ui/src/stores/streamingStore.ts b/ui/src/stores/streamingStore.ts
index 3f02e88..62f0008 100644
--- a/ui/src/stores/streamingStore.ts
+++ b/ui/src/stores/streamingStore.ts
@@ -9,6 +9,7 @@ import type {
   CompletedRound,
   ToolExecution,
   ToolExecutionRound,
+  McpApprovalRequest,
 } from "@/components/chat-types";
 import type { ToolCallState } from "@/pages/chat/utils/toolCallParser";
 
@@ -101,6 +102,12 @@ export interface StreamingResponse {
    * These are rich output objects displayed in the UI but not sent to the model.
    */
   artifacts?: Artifact[];
+  /**
+   * Gateway MCP tool calls that paused for human approval during this
+   * response. Rendered as approve/deny prompts; resolved entries stay so the
+   * transcript records the decision.
+   */
+  mcpApprovals?: McpApprovalRequest[];
   /**
    * Tool execution timeline tracking rounds of tool calls.
    * Each round contains one or more tool executions and optional model reasoning.
@@ -767,6 +774,10 @@ interface StreamingActions {
   /** Clear citations for a model */
   clearCitations: (model: string) => void;
 
+  // Gateway MCP approval actions
+  /** Append a pending gateway MCP approval request to a model's stream */
+  addMcpApproval: (model: string, approval: McpApprovalRequest) => void;
+
   // Artifact management actions
   /** Add artifacts to a model's stream (appends to existing) */
   addArtifacts: (model: string, artifacts: Artifact[]) => void;
@@ -1230,6 +1241,23 @@ export const useStreamingStore = create<StreamingStore>((set) => ({
       return { streams: newStreams };
     }),
 
+  // Gateway MCP approval implementations
+  addMcpApproval: (model, approval) =>
+    set((state) => {
+      const existing = state.streams.get(model);
+      if (!existing) return state;
+
+      const current = existing.mcpApprovals ?? [];
+      // Dedupe by approvalRequestId so replays don't double-add.
+      if (current.some((a) => a.approvalRequestId === approval.approvalRequestId)) {
+        return state;
+      }
+
+      const newStreams = new Map(state.streams);
+      newStreams.set(model, { ...existing, mcpApprovals: [...current, approval] });
+      return { streams: newStreams };
+    }),
+
   // Artifact management implementations
   addArtifacts: (model, artifacts) =>
     set((state) => {