chore(release): v3.24.0 — OpenAI multimodal + structured outputs, SPOT prompt budget, agentic fix, OCP_LOCAL_TOOLS (#186 )

* chore(release): v3.24.0 — OpenAI multimodal vision + structured outputs, SPOT prompt budget, agentic-turn fix, OCP_LOCAL_TOOLS Consolidates #179/#153/#154/#183/#181/#182 (merged since the v3.23.0 tag). 3.23.0 → 3.24.0. Minor: four user-facing features (multimodal vision #154, structured outputs #153, SPOT-derived prompt budget #179, OCP_LOCAL_TOOLS #182) + two fixes (#183 agentic final-answer, #181 deep-reply-500). No breaking change; no new endpoint; no new cli.js wire behavior. Two features from @vvlasy-openclaw. Release-kit walk: new env vars all documented in-PR (CLAUDE_IMAGE_ALLOW_URL / CLAUDE_MAX_IMAGE_* #154, OCP_STRUCTURED_MAX_ATTEMPTS #153, OCP_LOCAL_TOOLS #182 — grepped present in README env table); ADR 0009 (#179) + ADR 0006 (B.1, #153/#154) indexed; version from package.json only (no stale refs); the CHANGELOG Unreleased section (which held #182) is retitled to v3.24.0 with the other five entries added. Tag push v3.24.0 at this squash commit triggers release.yml. Co-Authored-By: Claude <claude-opus-4-8> <noreply@anthropic.com> * docs(changelog): correct contributor count — four of six PRs are @vvlasy-openclaw's, not two (release reviewer) --------- Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude <claude-opus-4-8> <noreply@anthropic.com>
feat(server): OCP_LOCAL_TOOLS — positive local-tools system-prompt wrapper (single-user, default off) (#182 )
2026-07-21 21:15:09 +00:00 · 2026-07-21 21:19:13 +10:00 · 2026-07-21 21:05:38 +10:00 · 2026-07-21 20:05:50 +10:00 · 2026-07-21 19:58:09 +10:00 · 2026-07-20 07:55:40 +10:00
12 changed files with 2241 additions and 77 deletions
@@ -1,10 +1,41 @@
 # Changelog

-## Unreleased
+## v3.24.0 — 2026-07-21
+
+Minor release. Headline: two long-requested **OpenAI-compat features** land — **multimodal vision** (`image_url` parts) and **structured outputs** (`response_format` / JSON schema). Also: the prompt-char budget now derives from the model SPOT instead of a hand-set constant, an agentic-turn bug that dropped the model's final answer is fixed, and `OCP_LOCAL_TOOLS` supports the OpenClaw-backend use case. Four of the six landed from external contributors (@vvlasy-openclaw). Every code PR carried a fresh-context reviewer (Iron Rule 10); no new endpoint, no new `cli.js` wire behavior.
+
+### Added
+
+- **Multimodal vision — OpenAI `image_url` parts (#154, contributed by @vvlasy-openclaw).** `/v1/chat/completions` forwards OpenAI `image_url` content parts to `claude` as native Anthropic image blocks via `--input-format stream-json` (the CLI's own contract — no invented wire shape, verified live). Base64 `data:` URIs by default; remote `http(s)` URLs are off unless `CLAUDE_IMAGE_ALLOW_URL=1` (and even then OCP never fetches them — no SSRF surface). Byte/count caps (`CLAUDE_MAX_IMAGE_BYTES`, `CLAUDE_MAX_IMAGES`, `CLAUDE_MAX_IMAGE_TOTAL_BYTES`), all fail-closed on a misconfigured value. TUI mode returns `400 images_unsupported_in_tui_mode` (it can't carry image blocks) and an image present only in a `system` message returns `400` rather than being silently dropped. README § "Images / Multimodal".
+- **Structured outputs — OpenAI `response_format` (#153, contributed by @vvlasy-openclaw).** `/v1/chat/completions` honors `response_format: { type: "json_schema" | "json_object" }` so OpenAI-SDK clients (Home Assistant AI Tasks, Honcho, scripts) get machine-parseable JSON in `content`. Validates against the schema (incl. `$ref`/`$defs` + `allOf`/`anyOf`/`oneOf` — the shapes the OpenAI SDK emits), retries with a stronger instruction up to `OCP_STRUCTURED_MAX_ATTEMPTS` (default 3, fail-closed), and on exhaustion returns OpenAI's own `refusal` field (200/`content:null`) rather than an invented error. Cyclic-`$ref` schemas fail closed (no stack overflow); a pathologically deep model reply returns a refusal, not a 500 (#181). Single-flight dedup + structured-keyed cache bound the cost. Class B.1 (ADR 0006). README § "Structured Outputs".
+- **SPOT-derived prompt-char budget (#179, ADR 0009).** `MAX_PROMPT_CHARS` default now derives from `max(models.json contextWindow) × 3 chars/token` (600,000 today) instead of the hand-set 150,000 (~37.5k tokens) that silently under-delivered the advertised window ~5×. `CLAUDE_MAX_PROMPT_CHARS` and the settings API remain absolute overrides; a garbage value fails closed to the derived default.
+- **`OCP_LOCAL_TOOLS` — positive local-tools system-prompt wrapper (single-user, loopback only; default off) (#182, contributed by @vvlasy-openclaw).** The `-p` path prepends a wrapper telling the model it has no local filesystem/shell access — correct for a shared gateway, but it makes a personal instance's model (e.g. an OpenClaw agent on its own local OCP) refuse to use the server-side `claude` tools it legitimately has. `=1` swaps in a positive wrapper. Changes **only the prompt**, never the tool surface (`--allowedTools`/`--disallowedTools` untouched; multi-tenant still disallows the FS surface); it does **not** enable client-side `tool_calls` (still unsupported by design). Fail-closed boot gate mirroring `OCP_TUI_FULL_TOOLS` (ADR 0007): refuses to start under `CLAUDE_AUTH_MODE=multi`, a non-loopback bind, or `PROXY_ANONYMOUS_KEY`. Inert (and logged as such) in TUI mode. The active wrapper is folded into the config epoch so toggling it invalidates the standard response cache. No new `cli.js` wire behavior (reuses the already-cited `--system-prompt` flag).
+
+### Fixed
+
+- **Agentic turns dropped the model's final answer (#183, contributed by @vvlasy-openclaw).** On a tool-using turn, `/v1/chat/completions` returned only the opening preamble ("I'll find the repo…") and silently discarded the post-tool-use final answer: aggregate-`assistant` extraction was gated on `isFirstDelta` (which flips false after the first text), and OCP runs pure-aggregate mode (no `--include-partial-messages`), so each of an agentic turn's several assistant messages after the first was lost. Now guards on `sawTextDelta` and accumulates every assistant message (streaming and buffered paths assemble byte-identically).
+- **Deep structured reply returned a 500 instead of a refusal (#181 / #184).** `validateJsonSchema` recurses on the model reply's nesting depth; a ~2000-level-deep reply overflowed the stack → caught `RangeError` → generic 500. A crash-safe façade converts that (only) into a validation miss → refusal; any other throw still surfaces.
+
+## v3.23.0 — 2026-07-17
+
+Minor release. Headline: **the default `sonnet` alias now resolves to Claude Sonnet 5** — a behavior change for every request that omits `model` (pin `claude-sonnet-4-6` by full ID to keep the previous default). Also: Windows-safe upgrade snapshots, two upgrade-system reliability fixes from a live fleet update, the `CLAUDE_SYSTEM_PROMPT` env var made functional, cache-key honesty for config changes, a billing-policy status correction (the 2026-06-15 `-p` split is PAUSED by Anthropic), and a major README restructure. No new endpoint; no new `cli.js` wire behavior. Every code PR carried a fresh-context reviewer (Iron Rule 10).

 ### Changed

- **Default `sonnet` alias → `claude-sonnet-5`.** The `sonnet` alias (the model used for every `/v1/chat/completions` request that omits `model`, and OpenClaw's OCP primary via `ocp-connect`) now resolves to `claude-sonnet-5` instead of `claude-sonnet-4-6`. `claude-sonnet-4-6` remains available by full ID for pinning. This is a behavior change for clients relying on the default — pin `claude-sonnet-4-6` explicitly to retain the previous model. Split out from the additive `claude-sonnet-5` model entry (#152) per Iron Rule 11.
+- **Default `sonnet` alias → `claude-sonnet-5` (#168, contributed by @vvlasy-openclaw).** The `sonnet` alias (the model used for every `/v1/chat/completions` request that omits `model`, and OpenClaw's OCP primary via `ocp-connect`) now resolves to `claude-sonnet-5` instead of `claude-sonnet-4-6`. `claude-sonnet-4-6` remains available by full ID for pinning. Mirrors the shipped Claude CLI's own `latest_per_family` mapping (`sonnet → claude-sonnet-5`, verified from binary 2.1.211). Split out from the additive model entry (#152) per Iron Rule 11.
+- **`CLAUDE_SYSTEM_PROMPT` is now functional (#175).** The var was read, documented, and echoed on `/health.systemPrompt` but never reached a request (dead since the `APPEND_SYSTEM_PROMPT` retirement). It is now appended (last, trimmed) to the composed system prompt on the default `-p` path via the new pure `lib/prompt.mjs`; TUI-mode panes are unaffected. Unset ⇒ byte-identical composition to before. README § Environment Variables documents it, including the cache caveat below.
+
+### Fixed
+
+- **Windows-safe upgrade snapshot paths (#167, contributed by @nyxst4ck).** Snapshot directory timestamps now use `-` instead of `:` (Windows forbids `:` in names); legacy colon-named snapshots keep parsing, and `listSnapshots` now orders by **parsed timestamp** (with a deterministic name tie-breaker) so mixed legacy/new names sort chronologically — the initial revision's raw-string sort could delete the newest recovery snapshot at the format boundary and was caught in review; regression tests pin the same-hour mixed-format case.
+- **`ocp update` reliability — two live-incident fixes (#174, closes #173).** (1) The doctor now runs `git fetch --tags` (offline-tolerant) before computing `latest_version` — previously it compared against the locally cached `origin/main`, so machines that hadn't pulled since a release reported "Already at latest" forever. (2) Post-flight now asserts `/health.version` equals the upgrade target (new `postFlightOk` predicate) instead of accepting any `auth.ok` — a stale orphan process holding the port used to pass post-flight while still serving the old version; the failure message now reports the last-seen version and points at `ss -ltnp`/`lsof -i`.
+- **Response-cache key now carries a boot-config epoch (#177, closes #176).** The persistent cache keyed on model+key+params+messages but not on server config that shapes answers (`CLAUDE_SYSTEM_PROMPT`, wrapper text, `CLAUDE_ALLOWED_TOOLS`, `CLAUDE_NO_CONTEXT`) — changing any of these and restarting could serve stale-config answers until TTL expiry. A sha256 config-epoch is folded into every key; any config change is an instant whole-cache invalidation. One-time side effect: existing cache entries miss once after this upgrade.
+
+### Docs
+
+- **Billing-policy status corrected (#171).** Anthropic **paused** the announced 2026-06-15 `claude -p` billing split on its effective date (official help-article citation in README § How It Works): the default `-p` path currently bills the subscription, and TUI-mode is reframed as the ready-made **hedge** for if/when a reworked change lands. All in-force assertions of the split are now date-stamped and conditioned.
+- **LAN mode scoped to chat-class workloads (#171).** New "workload fit" paragraph: multi-device OCP is for text-in/text-out workloads; client-machine coding agents are architecturally out of scope (tools execute on the OCP host).
+- **README restructured, 1205 → ~500 lines (#172).** Operations-manual content moved to `docs/lan-mode.md`, `docs/tui-mode.md`, `docs/troubleshooting.md`, `docs/upgrading.md` (verbatim moves + two canonical dedups; zero content loss verified section-by-section). README keeps the quickstart, the release-kit-pinned reference tables, and summary stubs with links. Plus a staleness sweep (#170): 6-model examples, removal of the never-existed `ocp stop` command, `ocp-connect` claims corrected, current version examples.

 ## v3.22.1 — 2026-07-17

@@ -27,7 +27,7 @@ One proxy. Multiple IDEs. All models. **$0 API cost.**
 - [How It Works](#how-it-works)
 - Reference: [Available Models](#available-models) · [API Endpoints](#api-endpoints) · [Environment Variables](#environment-variables)
 - Modes & operations: [LAN & multi-user](#lan--multi-user) → [`docs/lan-mode.md`](docs/lan-mode.md) · [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) → [`docs/tui-mode.md`](docs/tui-mode.md) · [Upgrading](#upgrading) → [`docs/upgrading.md`](docs/upgrading.md)
- [Built-in Usage Monitoring](#built-in-usage-monitoring) · [Response Cache](#response-cache) · [OpenClaw Integration](#openclaw-integration)
+- [Built-in Usage Monitoring](#built-in-usage-monitoring) · [Response Cache](#response-cache) · [Structured Outputs](#structured-outputs-openai-response_format) · [Images / Multimodal](#images--multimodal-vision) · [OpenClaw Integration](#openclaw-integration)
 - [Troubleshooting](#troubleshooting) → [`docs/troubleshooting.md`](docs/troubleshooting.md)
 - [Repository Layout](#repository-layout) · [Security](#security) · [Governance](#governance) · [Support OCP](#support-ocp) · [License](#license)

@@ -159,7 +159,7 @@ OCP translates OpenAI-compatible `/v1/chat/completions` requests into `claude --

 OCP is a **text-prompt bridge** to the official `claude` CLI. It does **not** pass through OpenAI `tools`/`functions` payloads or Anthropic `tool_use` blocks to the client. Clients (Cline, Cursor, OpenClaw, etc.) pointed at OCP receive **assistant TEXT only** — they never get `tool_calls` to execute locally.

-Any tool use happens server-side, under the `--allowedTools` set configured on the OCP host. In default mode (no `CLAUDE_NO_CONTEXT`), the `claude` CLI's own built-in tools are available to the model; in TUI mode, the operator controls the tool surface via `OCP_TUI_FULL_TOOLS`. Either way, the tools run under the operator's credentials on the server, and the client sees only the final text output.
+Any tool use happens server-side, under the `--allowedTools` set configured on the OCP host. In default mode (no `CLAUDE_NO_CONTEXT`), the `claude` CLI's own built-in tools are available to the model; in TUI mode, the operator controls the tool surface via `OCP_TUI_FULL_TOOLS`. Either way, the tools run under the operator's credentials on the server, and the client sees only the final text output. Note that on the `-p` path OCP prepends a system-prompt wrapper telling the model it has **no** local access (right for a shared gateway) — a single-user loopback instance whose model *should* use its tools can flip this with `OCP_LOCAL_TOOLS=1` (see Environment Variables).

 **Client-local tool execution is not supported by design.** Supporting it would require bypassing the `claude` CLI to call the raw Anthropic API directly — that is a different product, and is out of scope per `ALIGNMENT.md` (every OCP endpoint must correspond to something `cli.js` actually does).

@@ -222,12 +222,20 @@ The canonical list lives in [`models.json`](./models.json) — the single source
 | `CLAUDE_MAX_CONCURRENT` | `8` | Max concurrent claude processes (`-p`/stream-json path) |
 | `CLAUDE_MAX_QUEUE` | `16` | Max requests **waiting** for a `-p` concurrency slot. Beyond `CLAUDE_MAX_CONCURRENT`, requests queue (up to this cap) instead of being rejected; when the queue is **also** full, the request gets `HTTP 429` + `Retry-After` (not an opaque 500). Surfaced on `/health.concurrency` + `/health.stats.queueRejections`. |
 | `CLAUDE_QUEUE_RETRY_AFTER` | `5` | Seconds advertised in the `Retry-After` header on a `-p` concurrency-overflow `429`. |
-| `CLAUDE_MAX_PROMPT_CHARS` | `150000` | Prompt truncation limit (chars) |
+| `CLAUDE_MAX_PROMPT_CHARS` | *(derived)* | Prompt truncation limit in chars. Default derives from the models.json SPOT: `max(contextWindow) × 3` — currently **600,000** (≈150–200k tokens). Setting this env var (or the runtime settings API) overrides the derivation absolutely. See [ADR 0009](docs/adr/0009-spot-derived-prompt-budget.md). Note: very large prompts burn subscription-window quota quickly and slow TTFT; the TUI-mode paste path is untested beyond ~hundreds of KB. Applies to **text only** — image bytes bypass this budget (see [Images / Multimodal](#images--multimodal-vision)). |
+| `OCP_STRUCTURED_MAX_ATTEMPTS` | `3` | Max attempts (initial + retries) to coerce a schema-valid JSON reply when a request uses OpenAI `response_format`. Fail-closed: a non-numeric value keeps the default. See [Structured Outputs](#structured-outputs-openai-response_format). |
 | `CLAUDE_SESSION_TTL` | `3600000` | Session expiry (ms, default: 1 hour) |
 | `CLAUDE_CACHE_TTL` | `0` | Response cache TTL (ms, 0 = disabled). Set to e.g. `300000` for 5-min cache. See [Response Cache](#response-cache). |
 | `CLAUDE_ALLOWED_TOOLS` | `Bash,Read,...,Agent` | Comma-separated tools to pre-approve |
 | `CLAUDE_SKIP_PERMISSIONS` | `false` | Bypass all permission checks |
 | `CLAUDE_MCP_CONFIG` | *(unset)* | Path to an MCP server config JSON, passed to the spawned `claude` as `--mcp-config` (both the `-p` path and TUI `OCP_TUI_FULL_TOOLS` panes) |
+| `CLAUDE_MAX_BODY_SIZE` | `5242880` | Max request body size (bytes, default 5 MB). Base64 image payloads inflate ~33%; raise this to admit larger multimodal requests. Fail-closed parsing: a garbage value keeps the default. |
+| `CLAUDE_IMAGE_ALLOW_URL` | `false` | Allow remote `http(s)` image URLs in `image_url` parts. **Off by default** (v1 supports base64 `data:` URIs only). When on, the URL is passed through to Anthropic as a `url` image source — **OCP does not fetch it** (no OCP-side SSRF surface); unreachable/blocked URLs surface as an API error. |
+| `CLAUDE_MAX_IMAGE_BYTES` | `5242880` | Per-image decoded-byte cap (default 5 MB). Over-cap images get `HTTP 413`. |
+| `CLAUDE_MAX_IMAGES` | `20` | Max image parts per request. Over-cap gets `HTTP 413`. |
+| `CLAUDE_MAX_IMAGE_TOTAL_BYTES` | `20971520` | Aggregate decoded-byte cap across all images in a request (default 20 MB). Over-cap gets `HTTP 413`. |
+| `CLAUDE_SYSTEM_PROMPT` | *(unset)* | Operator-wide system-prompt text appended (last) to every request's composed system prompt on the default `-p` path. TUI-mode panes are unaffected (they keep the interactive CLI's own system prompt). Echoed truncated on `/health.systemPrompt`. Note: changing this value and restarting auto-invalidates the response cache (the key carries a boot-config epoch, #177). |
+| `OCP_LOCAL_TOOLS` | *(unset)* | **Single-user, loopback only.** `=1` swaps the default *"you have no local filesystem/shell access"* system-prompt wrapper for a positive one telling the model it **may** use its tools. These are the **server-side `claude` tools** OCP spawns via `-p` (`--allowedTools`) — which, on a loopback instance, run on the operator's own machine, i.e. *local* tools. For a personal instance (e.g. an **OpenClaw** agent on its own local OCP) the default wrapper otherwise makes the model refuse to use tools it legitimately has. Changes **only the prompt**, never the tool surface (governed by `--allowedTools`/`--disallowedTools`; multi-tenant still `--disallowedTools` the whole FS surface). **Does not** enable client-side `tool_calls` for OpenClaw/Cline/etc. — that remains unsupported by design (see § How tools work). Fail-closed: OCP **refuses to boot** if `=1` is combined with `CLAUDE_AUTH_MODE=multi`, a non-loopback bind, or `PROXY_ANONYMOUS_KEY` (mirrors `OCP_TUI_FULL_TOOLS`, ADR 0007). **Inert in TUI mode** (the `-p` wrapper is unused there; the TUI tool surface is `OCP_TUI_FULL_TOOLS`) — a warning is logged. Off by default → the default path is byte-for-byte unchanged. Toggling it auto-invalidates the standard response cache (boot-config epoch, #177). |
 | `CLAUDE_NO_CONTEXT` | `false` | Suppress CLAUDE.md and auto-memory injection (pure API mode) |
 | `PROXY_API_KEY` | *(unset)* | Bearer token for shared-mode authentication |
 | `PROXY_ANONYMOUS_KEY` | *(unset)* | Well-known anonymous key (multi mode) — this exact string bypasses `validateKey()` and grants public access. Exposed via `/health.anonymousKey` only to localhost, or to all callers when `PROXY_ADVERTISE_ANON_KEY=1`. Full setup + security notes: [docs/lan-mode.md § Anonymous Access](docs/lan-mode.md#anonymous-access-optional). |
@@ -381,6 +389,114 @@ ocp settings cacheTTL 0                       # disable at runtime

 Cache is **disabled by default** (`CLAUDE_CACHE_TTL=0`). All data is stored locally in `~/.ocp/ocp.db`. **Hash format upgrade in v3.13.0:** legacy `v1` cache rows don't match new `v2`-format lookups; they orphan and are reaped by the TTL cleanup interval within one window — no migration script required.

+## Structured Outputs (OpenAI `response_format`)
+
+`/v1/chat/completions` honors OpenAI's [`response_format`](https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format) parameter so OpenAI-SDK clients that require machine-parseable JSON (Home Assistant AI Tasks, Honcho, BYO scripts) get JSON in `choices[].message.content` — not prose.
+
+Supported shapes:
+
+- `response_format: { "type": "json_schema", "json_schema": { "name", "strict", "schema" } }`
+- `response_format: { "type": "json_object" }`
+- `json_mode: true` — non-standard top-level alias honored by several OpenAI-compatible clients; treated as `json_object`.
+
+When a structured request is detected, OCP:
+
+1. Appends a strict JSON-only steering instruction to the request (no Markdown, no fences, no prose, must begin with `{` or `[`).
+2. Extracts the JSON from the model reply (unwraps a stray code fence / prose via a string-aware balanced slice).
+3. For `json_schema`, validates the result against the supplied schema (types, `required`, `enum`, `const`, `additionalProperties`, nullability, `items`, `min/maxItems`, and `$ref`/`$defs` + `allOf`/`anyOf`/`oneOf` composition — the shapes the official OpenAI SDK emits via `zodResponseFormat` / `client.beta.chat.completions.parse`). For `json_object`, the whole reply must parse as a single JSON value (a stray brace inside prose is not served as the answer).
+4. On a parse/validation miss, retries with a stronger instruction that names the failure, up to `OCP_STRUCTURED_MAX_ATTEMPTS` (default 3).
+5. If no valid JSON can be produced, returns OpenAI's assistant **`refusal`** field (`HTTP 200`, `message.content: null`, `message.refusal: "<reason>"`, `finish_reason: "stop"`) — the spec's own mechanism for "the model would not produce the required output" — rather than an invented error type or passing prose through. SDK clients take their written `refusal` branch.
+
+A reply that carries **more than one** top-level JSON value (e.g. `Schema: {…}` then `Answer: {…}`) is rejected as ambiguous rather than silently serving the first — OCP never serves an unvalidated or arbitrarily-chosen extraction.
+
+`message.content` for a structured request is the raw JSON string only — no fences, no reasoning, no wrapper. Non-structured requests are completely unaffected (normal conversational behaviour, streaming included). This is a Class B.1 endpoint extension authorized by ADR 0006; the pure logic lives in [`lib/structured-output.mjs`](./lib/structured-output.mjs) and is unit-tested in `test-features.mjs`.
+
+**Caching & cost.** A structured request can cost up to `OCP_STRUCTURED_MAX_ATTEMPTS` metered `claude` spawns — each retry is a fresh spawn, burning subscription-window quota today and metered credits if the (currently **paused**) 2026-06-15 billing split re-lands (see the billing-policy status note in [How It Works](#how-it-works)) — so this feature adds cost-attack surface. Two guards bound it: (a) identical **concurrent** structured requests share one flight (single-flight dedup, so N callers ≠ N× spawns), and (b) when `CLAUDE_CACHE_TTL > 0`, a **validated** result is cached on a **structured-keyed** hash (the `response_format`/schema is folded into the key, so a JSON reply never collides with the conversational answer and different schemas never share a slot). A refusal is never cached. Operators concerned about cost can lower `OCP_STRUCTURED_MAX_ATTEMPTS` to `1` (no retries) or gate the surface behind per-key quotas (`/api/keys/:id/quota`).
+## Images / Multimodal (Vision)
+
+`POST /v1/chat/completions` accepts OpenAI-style multimodal `content` parts, so a
+message can carry images alongside text and Claude will actually see them. This
+follows OpenAI's [vision](https://platform.openai.com/docs/guides/vision) /
+[chat-completions `image_url`](https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages)
+request shape — no OCP-invented fields. (Class B.1 endpoint; see ADR 0006.)
+
+Under the hood, when a request carries an image OCP feeds the conversation to the
+Claude CLI as Anthropic image blocks over `--input-format stream-json`. Text-only
+requests are completely unaffected (unchanged code path).
+
+### Supported input
+
+- **Base64 data URIs** (default, recommended):
+  `data:image/png;base64,<...>`. Media types: `image/jpeg`, `image/png`,
+  `image/gif`, `image/webp`.
+- **Remote `http(s)` URLs** — **off by default**. Set `CLAUDE_IMAGE_ALLOW_URL=1`
+  to enable; the URL is passed through to Anthropic (OCP never fetches it itself,
+  so there is no OCP-side SSRF surface).
+- Images may appear in **any** message in the history (multi-turn), not just the
+  last one.
+- Non-image, non-text parts (audio, files) are **not** yet supported and are
+  replaced with a `[non-text content omitted]` placeholder (deferred to a future
+  version).
+
+### Example (base64 data URI)
+
+```bash
+curl -X POST http://127.0.0.1:3456/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "claude-sonnet-4-6",
+    "messages": [{
+      "role": "user",
+      "content": [
+        { "type": "text", "text": "What is in this image?" },
+        { "type": "image_url",
+          "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAA..." } }
+      ]
+    }]
+  }'
+```
+
+### Not supported in TUI mode
+
+Multimodal images require the default `-p` spawn path. In **TUI / subscription-pool
+mode** (`CLAUDE_TUI_MODE=true`) the CLI is driven interactively and cannot carry
+image blocks, so a request with an `image_url` part returns **`400
+images_unsupported_in_tui_mode`** rather than silently dropping the image and
+answering about something the model never saw. Remove the images, or run OCP
+without TUI mode, to use vision.
+
+Images must also live in a **user or assistant** message, not a `system` message
+(system content is not forwarded to the CLI as image blocks). An `image_url` part
+present only in a system message returns **`400 images_unsupported_in_system_messages`**
+for the same reason — fail loudly rather than answer about an unseen image. This matches
+the OpenAI vision spec, which does not place images in the system role.
+
+### Limits
+
+Images bypass the text `CLAUDE_MAX_PROMPT_CHARS` budget and are instead bounded by
+their own byte/count caps. The **text** in a multimodal request is still subject to
+`CLAUDE_MAX_PROMPT_CHARS` (older text is truncated exactly as on the text-only
+path — only the image bytes are exempt). All numeric caps are parsed **fail-closed**:
+a malformed value (e.g. `CLAUDE_MAX_BODY_SIZE=unlimited` or `=5MB`) is rejected with
+a startup warning and the safe default is kept — a misconfigured cap can never
+silently disable the guard. Requests that violate a cap get a clear `4xx` (never a
+silent drop):
+
+| Cap | Env var | Default | Error |
+|-----|---------|---------|-------|
+| Request body | `CLAUDE_MAX_BODY_SIZE` | 5 MB | `413` request body too large |
+| Per-image bytes | `CLAUDE_MAX_IMAGE_BYTES` | 5 MB | `413` `image_too_large` |
+| Total image bytes | `CLAUDE_MAX_IMAGE_TOTAL_BYTES` | 20 MB | `413` `images_too_large` |
+| Image count | `CLAUDE_MAX_IMAGES` | 20 | `413` `too_many_images` |
+| Unsupported media type | — | — | `400` `unsupported_image_type` |
+| Malformed data URI | — | — | `400` `invalid_data_uri` |
+| Remote URL while disabled | `CLAUDE_IMAGE_ALLOW_URL` | off | `400` `remote_url_disabled` |
+
+Base64 payloads are large: a 5 MB image is ~6.7 MB as a data URI, so raise
+`CLAUDE_MAX_BODY_SIZE` (and, if needed, `CLAUDE_MAX_IMAGE_BYTES`) to admit big
+images. Vision support depends on the target model — request a current
+vision-capable Claude model.
+
 ## OpenClaw Integration

 OCP was originally built for [OpenClaw](https://github.com/openclaw/openclaw) and includes deep integration:
@@ -0,0 +1,54 @@
+# ADR 0009 — Prompt-char budget derives from the models.json SPOT
+
+Date: 2026-07-18
+Status: Accepted (maintainer directive, 2026-07-18: "37.5k 截断未免太短了吧 … 这个在现在还适用吗")
+
+## Context
+
+`MAX_PROMPT_CHARS` (the tail-first truncation guard in `messagesToPrompt`) defaulted to a
+hand-set constant of 150,000 chars ≈ 37.5k English tokens — set in the 200k-window era as a
+runaway-context guard. Meanwhile `models.json` advertises `contextWindow: 200000` for every
+model (and the underlying CLI registry carries 1M native windows for Opus 4.8 / Sonnet 5), and
+`scripts/sync-openclaw.mjs` feeds that 200k into OpenClaw's compaction budget. The result was
+a standing dishonesty identified in the PR #152 review: **no advertised contextWindow value was
+true**, because the proxy silently guillotined every request at ~37.5k tokens — roughly 5×
+below the advertised window — logging only a server-side warning the client never sees.
+
+Raising the constant to another hand-set number would rot the same way. Following the model's
+native 1M directly is also wrong: chars ≠ tokens (CJK runs ~1–1.5 chars/token vs ~4 for
+English, so a 1M-token char cap would let CJK text sail past the model's real window into an
+upstream rejection), single near-window requests can consume a large fraction of a 5-hour
+subscription quota window, and the TUI paste path is untested at megabyte scale.
+
+## Decision
+
+The default budget **derives from the SPOT** instead of being a constant:
+
+```
+MAX_PROMPT_CHARS (default) = max(models.json models[].contextWindow) × 3 chars/token
+                            = 200000 × 3 = 600,000 chars today
+```
+
+Implemented as the pure `derivePromptCharBudget(models, {charsPerToken = 3, floor = 150000})`
+in `lib/prompt.mjs` (unit-tested; floor guards degenerate SPOT states). The multiplier ×3 is
+deliberately conservative: full window for English, and CJK text reaches the model's real
+window at roughly the same point the cap fires — so OCP truncates gracefully (tail-first)
+instead of the upstream rejecting outright.
+
+`CLAUDE_MAX_PROMPT_CHARS` (env) and the runtime settings API remain **absolute overrides**;
+the derivation applies only when neither is set.
+
+## Consequences
+
+- The advertised `contextWindow: 200000` becomes honest: the proxy now actually accepts
+  prompts of that order (English ≈150–200k tokens) before truncating.
+- If `models.json` ever advertises a larger window (e.g. 1M for the 1M-native models), the
+  budget scales automatically — no code change. Whether to advertise 1M is a **separate,
+  deliberate decision** (quota burn per request, OpenClaw compaction memory, TUI paste
+  limits) and is explicitly NOT made by this ADR; the current recommendation is to keep
+  200000 advertised until a real >200k use case appears.
+- One-time behavior change: requests between 150k and 600k chars that were previously
+  truncated now pass through whole — longer TTFT and higher quota consumption for those
+  requests, by design.
+- The truncation mechanism, logging, and the multimodal-path budget threading (PR #154's F2,
+  pending) are unchanged — only the default value's provenance changed.
@@ -25,6 +25,7 @@ New ADRs increment from the highest existing number. Filenames are
 | [0006](0006-openai-shim-scope.md) | OpenAI Shim Scope | The Class A / Class B taxonomy. Class A endpoints (`cli.js`-mirror) keep Rules 1–5 verbatim; Class B endpoints (OCP-owned compatibility surface — `/v1/chat/completions`, `/v1/models`, admin endpoints) are anchored to OpenAI's spec (B.1) or to an authorizing ADR (B.2). Triggered by PR #99 (external `response_format` honoring). Grandfathers the existing B.2 inventory at v3.16.4. |
 | [0007](0007-tui-interactive-mode.md) | TUI Interactive Mode | Why TUI-mode spawns an interactive `claude` in a tmux pane (no `-p`) to reach the **subscription** billing pool (`cc_entrypoint=cli`) rather than the metered Agent SDK pool. Owns the TUI spawn machinery: entrypoint labeling, credential-isolated home, MCP hard-disable, session namespace + defunct-session reaping, the independent concurrency bound, and the `/health` `tui` block. **Single-user only** — hard FATAL on multi-user configs. |
 | [0008](0008-tui-warm-pane-pool.md) | TUI Warm Pane Pool | Why `OCP_TUI_POOL_SIZE` pre-boots **single-use** `claude` panes (one turn each, own `--session-id`) — and why reuse is forbidden (`transcript.mjs` returns the last assistant entry in the file, so a reused session leaks the earlier turn's text). Measured −41% end-to-end. Defines the pool↔reaper invariant (exemption by exact name from a live registry; drain before every sweep so `kill-server` zombie reaping survives) and the standing idle-process cost. Extends ADR 0007. |
+| [0009](0009-spot-derived-prompt-budget.md) | SPOT-Derived Prompt Budget | Why `MAX_PROMPT_CHARS`'s default is `max(models.json contextWindow) × 3 chars/token` (600k chars today) instead of a hand-set constant — the old 150k silently under-delivered the advertised window ~5×. ×3 is the CJK-safe multiplier; env/settings stay absolute overrides; whether to advertise 1M windows is explicitly a separate decision. |

 ## When to write a new ADR

@@ -355,6 +355,16 @@ export function cacheHash(model, messages, opts = {}) {
  if (opts.temperature != null) h.update(`t:${opts.temperature}`);
  if (opts.max_tokens != null) h.update(`mt:${opts.max_tokens}`);
  if (opts.top_p != null) h.update(`tp:${opts.top_p}`);
+  // #176: fold the server's boot-config epoch into the key, so a config change that shapes
+  // answers (operator system prompt, wrapper text, allowed tools, NO_CONTEXT) invalidates
+  // the persistent cache instead of serving answers composed under the old config. Callers
+  // that omit it (older paths, tests) hash byte-identically to before.
+  if (opts.configEpoch != null) h.update(`ce:${opts.configEpoch}|`);
+  // Structured-output (OpenAI response_format / json_mode) requests must never share a cache slot
+  // with the conversational answer to the same prompt, nor with a different schema — the steering
+  // instruction and validated JSON payload differ. Keying on the detected descriptor isolates them.
+  // Absent for normal requests → hashes are byte-identical to pre-change.
+  if (opts.structured != null) h.update(`s:${JSON.stringify(opts.structured)}`);
  for (const m of messages) {
    h.update(m.role || "");
    h.update(typeof m.content === "string" ? m.content : JSON.stringify(m.content));
@@ -0,0 +1,29 @@
+// OCP env-var parsing helpers.
+//
+// Fail-closed positive-integer parsing for numeric caps (body size, image
+// byte/count limits). A misconfigured cap must NEVER silently disable a guard:
+// `parseInt("unlimited", 10)` is NaN and `x > NaN` is always false, so a naive
+// parse of CLAUDE_MAX_BODY_SIZE=unlimited would remove the body-size limit
+// entirely (unbounded body → OOM). Likewise CLAUDE_MAX_BODY_SIZE=5MB naively
+// parses to 5 (bytes) and bricks the proxy. So a present-but-invalid value is
+// REJECTED (default kept, caller warns), not accepted. (PR #154 review F3.)
+//
+// Pure (no env access, no IO) so it is unit-testable without a live server.
+
+// Parse `raw` as a strictly-positive base-10 integer of bytes/count (no unit
+// suffix). Returns { value, ok, reason }:
+//   - missing/empty        → { value: def, ok: true }               (use default)
+//   - valid positive int   → { value: n,  ok: true }
+//   - anything else        → { value: def, ok: false, reason }      (fail closed)
+// Rejects: NaN ("unlimited"), non-positive ("0", "-1"), unit-suffixed ("5MB"),
+// and fractional/ambiguous ("20.5", "0x10") values — String(n) !== trimmed catches
+// any input parseInt only partially consumed.
+export function parsePositiveInt(raw, def) {
+  if (raw === undefined || raw === null || raw === "") return { value: def, ok: true };
+  const trimmed = String(raw).trim();
+  const n = parseInt(trimmed, 10);
+  if (!Number.isFinite(n) || n <= 0 || String(n) !== trimmed) {
+    return { value: def, ok: false, reason: "not a strictly-positive integer (bytes/count, no unit suffix)" };
+  }
+  return { value: n, ok: true };
+}
@@ -0,0 +1,278 @@
+// OCP multimodal helpers — OpenAI `image_url` content parts → Anthropic image
+// blocks fed to `claude -p --input-format stream-json`. (issue #110)
+//
+// Class B.1 (OpenAI-compatibility surface). Protocol authority is OpenAI's
+// chat/completions spec — the multimodal `content` parts shape
+// (https://platform.openai.com/docs/guides/vision and
+// https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages,
+// `image_url` part with `image_url.url` = data URI or http(s) URL). Authorized
+// by ADR 0006. This module introduces NO field beyond OpenAI's published shape:
+// the OpenAI-side vocabulary read here is `type:"image_url"` +
+// `image_url:{url, detail?}`; the Anthropic-side vocabulary written here
+// (`type:"image", source:{type:"base64"|"url", ...}`) is the CLI's native
+// stream-json input contract, not an OCP invention.
+//
+// Kept as a pure module (no I/O, no network, no process state) mirroring the
+// lib/*.mjs pattern so it is unit-testable without a live server. server.mjs is
+// the only consumer; it owns spawning, caps configuration, and HTTP status.
+
+// Anthropic vision-supported image media types. A data URI whose media type is
+// outside this set is rejected with a clear 4xx rather than forwarded (the API
+// would reject it anyway; failing early gives a better error).
+export const SUPPORTED_IMAGE_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+]);
+
+// Default caps. server.mjs overrides these from env; they live here so the
+// pure transform is self-contained and testable.
+export const DEFAULT_MULTIMODAL_OPTS = {
+  allowRemoteUrl: false,        // http(s) image URLs are OFF by default (v1: data URIs only)
+  maxImageBytes: 5 * 1024 * 1024,   // per-image decoded-byte cap
+  maxImages: 20,                // max image parts across the whole request
+  maxTotalImageBytes: 20 * 1024 * 1024, // aggregate decoded-byte cap
+  maxTextChars: Infinity,       // text-char budget (server passes MAX_PROMPT_CHARS); Infinity = no truncation
+};
+
+// Typed error so server.mjs can map to the right HTTP status + OpenAI-shaped
+// error body. `status` is the HTTP code; `type` is the OpenAI error `type`.
+export class MultimodalError extends Error {
+  constructor(code, status, message) {
+    super(message);
+    this.name = "MultimodalError";
+    this.code = code;
+    this.status = status;
+    this.type = "invalid_request_error"; // OpenAI error `type` for 4xx client errors
+  }
+}
+
+// True if any message carries an OpenAI `image_url` content part. Cheap guard so
+// the byte-for-byte text path is only left when an image is genuinely present.
+export function hasImageContent(messages) {
+  if (!Array.isArray(messages)) return false;
+  for (const m of messages) {
+    if (m && Array.isArray(m.content)) {
+      for (const part of m.content) {
+        if (part && part.type === "image_url") return true;
+      }
+    }
+  }
+  return false;
+}
+
+// Extract the URL string from an OpenAI image_url part. Spec form is
+// `{type:"image_url", image_url:{url, detail?}}`; many OpenAI-compatible clients
+// also send `image_url` as a bare string. Accept both (input leniency — no new
+// output field). `detail` (auto|low|high) is OpenAI-only and has no Anthropic
+// analogue, so it is read-and-ignored.
+function imageUrlOf(part) {
+  const iu = part.image_url;
+  if (typeof iu === "string") return iu;
+  if (iu && typeof iu.url === "string") return iu.url;
+  return null;
+}
+
+// Parse a base64 data URI: `data:[<media_type>][;base64],<data>`.
+// Returns { mediaType, data (base64), bytes (decoded size) } or throws MultimodalError.
+function parseDataUri(uri) {
+  const comma = uri.indexOf(",");
+  if (comma === -1) {
+    throw new MultimodalError("invalid_data_uri", 400, "Malformed image data URI (no comma).");
+  }
+  const meta = uri.slice(5, comma); // strip leading "data:"
+  const segs = meta.split(";");
+  const mediaType = (segs[0] || "").trim().toLowerCase();
+  const isBase64 = segs.slice(1).some((s) => s.trim().toLowerCase() === "base64");
+  if (!isBase64) {
+    throw new MultimodalError("invalid_data_uri", 400, "Only base64-encoded image data URIs are supported.");
+  }
+  if (!SUPPORTED_IMAGE_TYPES.has(mediaType)) {
+    throw new MultimodalError(
+      "unsupported_image_type",
+      400,
+      `Unsupported image media type '${mediaType || "(none)"}'. Supported: ${[...SUPPORTED_IMAGE_TYPES].join(", ")}.`
+    );
+  }
+  // Strip incidental whitespace/newlines some encoders insert into data URIs.
+  const data = uri.slice(comma + 1).replace(/\s/g, "");
+  if (data.length === 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(data)) {
+    throw new MultimodalError("invalid_data_uri", 400, "Image data URI payload is not valid base64.");
+  }
+  // Decoded size from base64 length (minus padding); avoids decoding the buffer
+  // just to measure it.
+  const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  const bytes = Math.floor((data.length * 3) / 4) - padding;
+  return { mediaType, data, bytes };
+}
+
+// Convert a single OpenAI image_url part to an Anthropic image block, enforcing
+// caps via the mutable `acc` accumulator ({ images, bytes }). Throws MultimodalError.
+function imagePartToBlock(part, opts, acc) {
+  const url = imageUrlOf(part);
+  if (!url) {
+    throw new MultimodalError("invalid_image_url", 400, "image_url part is missing a URL.");
+  }
+
+  acc.images += 1;
+  if (acc.images > opts.maxImages) {
+    throw new MultimodalError("too_many_images", 413, `Too many images in request (max ${opts.maxImages}).`);
+  }
+
+  if (url.startsWith("data:")) {
+    const { mediaType, data, bytes } = parseDataUri(url);
+    if (bytes > opts.maxImageBytes) {
+      throw new MultimodalError("image_too_large", 413, `Image exceeds per-image size limit (${opts.maxImageBytes} bytes).`);
+    }
+    acc.bytes += bytes;
+    if (acc.bytes > opts.maxTotalImageBytes) {
+      throw new MultimodalError("images_too_large", 413, `Total image payload exceeds limit (${opts.maxTotalImageBytes} bytes).`);
+    }
+    return { type: "image", source: { type: "base64", media_type: mediaType, data } };
+  }
+
+  if (/^https?:\/\//i.test(url)) {
+    if (!opts.allowRemoteUrl) {
+      throw new MultimodalError(
+        "remote_url_disabled",
+        400,
+        "Remote image URLs are disabled. Enable CLAUDE_IMAGE_ALLOW_URL=1 to allow http(s) image URLs, or pass the image as a base64 data URI."
+      );
+    }
+    // Passthrough as an Anthropic url-source block. OCP does NOT fetch the URL
+    // itself (no OCP-side SSRF surface); the fetch is performed upstream by the
+    // Anthropic API. Best-effort: unreachable/blocked URLs surface as an API error.
+    return { type: "image", source: { type: "url", url } };
+  }
+
+  throw new MultimodalError("unsupported_url_scheme", 400, "image_url must be a base64 data URI or an http(s) URL.");
+}
+
+// Role prefix mirrors messagesToPrompt()'s text-path labeling so a multi-turn
+// conversation reads the same whether or not it carries images. System messages
+// are handled by the caller via --system-prompt and never reach here.
+function rolePrefix(role) {
+  if (role === "assistant") return "[Assistant] ";
+  return ""; // user / tool / anything else: verbatim, as in the text path
+}
+
+// Build the Anthropic content-block array for a single stream-json user
+// envelope. Mirrors the text path's "collapse the whole conversation into one
+// turn passed via stdin" model (OCP runs stateless, full context per spawn), but
+// preserves image position relative to text and keeps images out of the text
+// char budget entirely. Returns { blocks, stats } or throws MultimodalError.
+export function buildImageBlocks(messages, opts = {}) {
+  const o = { ...DEFAULT_MULTIMODAL_OPTS, ...opts };
+  const blocks = [];
+  const acc = { images: 0, bytes: 0 };
+  let textChars = 0;
+  let firstMessage = true;
+
+  const pushText = (text) => {
+    if (!text) return;
+    blocks.push({ type: "text", text });
+    textChars += text.length;
+  };
+
+  for (const m of messages) {
+    const prefix = rolePrefix(m.role);
+    // Separate messages with a blank line, matching messagesToPrompt's "\n\n" join.
+    const sep = firstMessage ? "" : "\n\n";
+    firstMessage = false;
+    let prefixEmitted = false;
+    const emitPrefixWith = (t) => {
+      if (prefixEmitted) return t;
+      prefixEmitted = true;
+      return sep + prefix + t;
+    };
+
+    if (typeof m.content === "string") {
+      pushText(emitPrefixWith(m.content));
+      continue;
+    }
+    if (!Array.isArray(m.content)) {
+      // null / object content: mirror contentToText's fallback.
+      const t = m.content == null ? "" : JSON.stringify(m.content);
+      pushText(emitPrefixWith(t));
+      continue;
+    }
+
+    for (const part of m.content) {
+      if (part && part.type === "text" && typeof part.text === "string") {
+        pushText(emitPrefixWith(part.text));
+      } else if (part && part.type === "image_url") {
+        // Ensure the role prefix isn't lost when a message leads with an image.
+        if (!prefixEmitted && prefix) pushText(emitPrefixWith(""));
+        blocks.push(imagePartToBlock(part, o, acc));
+      } else {
+        // audio / file / unknown parts: preserve the existing placeholder
+        // behavior (issue #110) — deferred to a future version.
+        pushText(emitPrefixWith("[non-text content omitted]"));
+      }
+    }
+  }
+
+  // Defensive: a stream-json user turn must have at least one content block.
+  if (blocks.length === 0) blocks.push({ type: "text", text: "" });
+
+  // Enforce the text-char budget (PR #154 review F2). Without this, attaching a
+  // single tiny image would let unbounded text bypass the gateway's runaway-context
+  // guard entirely — messagesToPrompt truncates the text path, so the multimodal
+  // path must too. Image blocks are preserved and are NOT counted (they are bounded
+  // by the byte/count caps above).
+  const budgeted = enforceTextBudget(blocks, o.maxTextChars);
+
+  return {
+    blocks: budgeted.blocks,
+    stats: {
+      imageCount: acc.images,
+      totalImageBytes: acc.bytes,
+      textChars: budgeted.textChars,
+      originalTextChars: budgeted.originalTextChars,
+      truncated: budgeted.truncated,
+    },
+  };
+}
+
+// Enforce a text-char budget over already-built content blocks, mirroring
+// messagesToPrompt's "keep the tail, drop the oldest" truncation. Image blocks are
+// preserved in place; only text blocks count against the budget. A truncation note
+// is prepended when anything is dropped. Returns
+// { blocks, truncated, originalTextChars, textChars }.
+function enforceTextBudget(blocks, maxTextChars) {
+  let originalTextChars = 0;
+  for (const b of blocks) if (b.type === "text") originalTextChars += b.text.length;
+  if (!(maxTextChars > 0) || originalTextChars <= maxTextChars) {
+    return { blocks, truncated: false, originalTextChars, textChars: originalTextChars };
+  }
+  // Keep the most recent text up to the budget; trim within the boundary block and
+  // drop older text blocks. Non-text (image) blocks always survive, in order.
+  let budget = maxTextChars;
+  const out = [];
+  for (let i = blocks.length - 1; i >= 0; i--) {
+    const b = blocks[i];
+    if (b.type !== "text") { out.unshift(b); continue; }
+    if (budget <= 0) continue; // older text fully dropped
+    if (b.text.length <= budget) {
+      out.unshift(b);
+      budget -= b.text.length;
+    } else {
+      out.unshift({ type: "text", text: b.text.slice(b.text.length - budget) });
+      budget = 0;
+    }
+  }
+  out.unshift({ type: "text", text: "[System] Note: older text content was truncated to fit the context limit." });
+  let textChars = 0;
+  for (const b of out) if (b.type === "text") textChars += b.text.length;
+  return { blocks: out, truncated: true, originalTextChars, textChars };
+}
+
+// Serialize the non-system conversation to a single newline-terminated
+// stream-json user message for `claude -p --input-format stream-json` stdin.
+// Returns { payload, stats } or throws MultimodalError.
+export function buildStreamJsonInput(messages, opts = {}) {
+  const { blocks, stats } = buildImageBlocks(messages, opts);
+  const envelope = { type: "user", message: { role: "user", content: blocks } };
+  return { payload: JSON.stringify(envelope) + "\n", stats };
+}
@@ -0,0 +1,89 @@
+// lib/prompt.mjs — pure operator-append step for the system prompt.
+//
+// Extracted so the rule is unit-testable (the suite never imports server.mjs — it
+// boots a listener). server.mjs composes wrapper + client system messages exactly as
+// before, then passes the result through this. With CLAUDE_SYSTEM_PROMPT unset the
+// return is the INPUT STRING UNCHANGED — the default path stays byte-for-byte
+// identical, which is the repo's bar for touching a request-shaping function.
+//
+// The operator prompt goes LAST deliberately: a server-wide directive ("answer in
+// Chinese") should read as the final instruction, not something a client system
+// message overrides by coming later. Whitespace-only values are treated as unset —
+// a stray space in a service unit's Environment= line must not inject "\n\n " into
+// every request.
+export function appendOperatorPrompt(base, operatorAppend) {
+  const op = typeof operatorAppend === "string" ? operatorAppend.trim() : "";
+  return op ? `${base}\n\n${op}` : base;
+}
+
+// Derive the default prompt-char budget from the models.json SPOT (ADR 0009).
+//
+// The old default was a hand-set constant (150000 chars ≈ 37.5k English tokens) from the
+// 200k-window era — silently far below what the advertised contextWindow promises. Instead
+// of picking a new constant that will also rot, the default now FOLLOWS the SPOT:
+//
+//   budget = max(models[].contextWindow) × charsPerToken
+//
+// charsPerToken = 3 is deliberately conservative: English runs ~4 chars/token, CJK ~1–1.5.
+// At ×3, a 200k-token window yields 600,000 chars — full window for English, and CJK text
+// hits the model's real window at roughly the same point the cap fires, so we truncate
+// (graceful, tail-first) rather than let the upstream reject the request outright.
+//
+// The floor guards the degenerate cases (empty/missing models[], absent contextWindow):
+// fall back to the historical constant rather than 0 — a zero budget would truncate every
+// request to nothing, which is fail-OPEN in the "serve garbage" sense. CLAUDE_MAX_PROMPT_CHARS
+// remains an absolute operator override at the call site (server.mjs); this function is only
+// the unset-env default.
+export function derivePromptCharBudget(models, { charsPerToken = 3, floor = 150000 } = {}) {
+  const windows = (Array.isArray(models) ? models : [])
+    .map(m => m?.contextWindow)
+    .filter(w => Number.isFinite(w) && w > 0);
+  if (windows.length === 0) return floor;
+  return Math.max(floor, Math.max(...windows) * charsPerToken);
+}
+
+// Resolve the effective budget from the env var + SPOT. TRUTHINESS (not != null) on the env
+// value deliberately: an EMPTY value ("CLAUDE_MAX_PROMPT_CHARS=" in a systemd EnvironmentFile
+// or .env) must mean "use the default" — exactly the old `parseInt(env || "150000")` contract.
+// Treating "" as explicit gives parseInt("") = NaN, and a NaN cap silently DISABLES the
+// runaway-context guard while injecting a false "[System] Note: 0 older messages were
+// truncated" line into every prompt (caught in PR #179 review). Non-empty garbage still
+// parses to NaN — the pre-existing class, slated for parseIntEnv routing in PR #154.
+export function resolvePromptCharBudget(rawEnv, models, opts) {
+  return rawEnv ? parseInt(rawEnv, 10) : derivePromptCharBudget(models, opts);
+}
+
+// OCP_LOCAL_TOOLS system-prompt wrapper selection (pure).
+//
+// OCP's `-p` path prepends a fixed wrapper to every request's system prompt. The DEFAULT wrapper
+// tells the model it has NO local filesystem/shell/env access — the right posture for a shared or
+// multi-tenant gateway. But a single-user, loopback-bound instance (e.g. an OpenClaw agent talking
+// to its own local OCP) DOES legitimately have tools — the `-p` path already passes `--allowedTools`
+// and the CLI's built-in tools are available — so the default wrapper actively gaslights the model
+// into refusing to use tools it holds. `OCP_LOCAL_TOOLS=1` swaps in a positive wrapper for that case.
+//
+// This does NOT expand the tool surface: tools are governed solely by `--allowedTools` /
+// `--disallowedTools` (multi-tenant mode `--disallowedTools` the whole FS surface regardless of the
+// wrapper). It only changes the PROMPT the operator's own model reads. Pure so it is unit-testable.
+export function selectPromptWrapper(localToolsEnabled, negativeWrapper, positiveWrapper) {
+  return localToolsEnabled ? positiveWrapper : negativeWrapper;
+}
+
+// Boot-time safety gate for OCP_LOCAL_TOOLS, mirroring the OCP_TUI_FULL_TOOLS model (ADR 0007): a
+// positive "you may use local tools" wrapper must never reach an untrusted caller. Returns a fatal
+// message string when the flag is enabled in an unsafe deployment, or null when it is safe/disabled.
+// Fail-closed: any of multi-tenant auth, a non-loopback bind, or an anonymous key is refused. Pure —
+// the caller does the process.exit so this stays testable.
+export function localToolsSafetyError({ enabled, authMode, loopbackBind, anonymousKey }) {
+  if (!enabled) return null;
+  if (authMode === "multi") {
+    return "OCP_LOCAL_TOOLS=1 is incompatible with CLAUDE_AUTH_MODE=multi — a guest/anonymous prompt would be told it may drive the operator's filesystem/shell. Single-user only.";
+  }
+  if (!loopbackBind) {
+    return "OCP_LOCAL_TOOLS=1 requires a loopback bind (127.0.0.1/::1) — a network-exposed positive-tools wrapper could reach an untrusted peer. Bind to loopback, or leave OCP_LOCAL_TOOLS off.";
+  }
+  if (anonymousKey) {
+    return "OCP_LOCAL_TOOLS=1 is unsafe with PROXY_ANONYMOUS_KEY set — anonymous callers could reach the local-tools-enabled model without a named key. Remove PROXY_ANONYMOUS_KEY, or leave OCP_LOCAL_TOOLS off.";
+  }
+  return null;
+}
@@ -0,0 +1,318 @@
+// ── OpenAI Structured Outputs (response_format) — pure helpers ───────────────
+//
+// OCP's `/v1/chat/completions` (Class B.1, ADR 0006) advertises OpenAI compatibility but forwards
+// to `claude -p`, which has no native `response_format`. Asked for JSON, the coding-assistant CLI
+// typically replies with prose, a Markdown table, or a ```json fenced block — none of which is
+// `JSON.parse`-able. These helpers implement the OpenAI `response_format` contract on top of that:
+// detect the request, build a strict JSON-only steering instruction, then extract and validate the
+// JSON the model returns. All functions here are pure (no I/O) so they are unit-tested directly;
+// the retry loop that calls the model lives in server.mjs (runStructuredCompletion).
+//
+// Spec authority (B.1, ADR 0006): OpenAI chat/completions `response_format`
+//   https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format
+// No field or behaviour beyond that published shape is introduced.
+
+export class StructuredOutputError extends Error {
+  constructor(reason, raw) {
+    super(`structured output could not be produced: ${reason}`);
+    this.name = "StructuredOutputError";
+    this.reason = reason;
+    this.raw = raw;
+  }
+}
+
+// Fail-closed parse of the OCP_STRUCTURED_MAX_ATTEMPTS retry cap. `Math.max(1, parseInt("abc",10))`
+// === `Math.max(1, NaN)` === NaN, and a retry loop bounded by `attempt < NaN` never runs → 0 spawns,
+// every structured request silently refuses. So any non-integer / non-finite / <1 value keeps the
+// documented default instead (and warns), rather than bricking the feature. (PR #153 review round 2.)
+export function resolveMaxAttempts(raw, { fallback = 3, warn } = {}) {
+  if (raw === undefined || raw === null || raw === "") return fallback;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1) {
+    if (typeof warn === "function") {
+      warn(`Ignoring invalid OCP_STRUCTURED_MAX_ATTEMPTS="${raw}" (want integer >= 1); using default ${fallback}.`);
+    }
+    return fallback;
+  }
+  return n;
+}
+
+// Returns { mode: "schema", schema, name?, strict } | { mode: "json_object" } | null.
+// Supports the OpenAI shapes: response_format:{type:"json_schema",json_schema:{schema,strict,name}}
+// and response_format:{type:"json_object"}, a lenient response_format:{schema} fallback, and the
+// widely-used (non-standard) top-level `json_mode: true` flag as a json_object alias.
+export function detectStructuredOutput(parsed) {
+  const rf = parsed?.response_format;
+  if (rf && typeof rf === "object") {
+    if (rf.type === "json_schema") {
+      const js = (rf.json_schema && typeof rf.json_schema === "object") ? rf.json_schema : {};
+      const schema = js.schema || rf.schema || null;
+      return { mode: "schema", schema, name: js.name, strict: js.strict === true };
+    }
+    if (rf.type === "json_object") return { mode: "json_object" };
+    if (rf.schema && typeof rf.schema === "object") {
+      return { mode: "schema", schema: rf.schema, strict: rf.strict === true };
+    }
+  }
+  // Non-standard convenience alias honored by several OpenAI-compatible clients.
+  if (parsed?.json_mode === true) return { mode: "json_object" };
+  return null;
+}
+
+export function jsonTypeOf(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v; // object | string | number | boolean
+}
+
+export function jsonTypeMatches(t, value) {
+  switch (t) {
+    case "string": return typeof value === "string";
+    case "number": return typeof value === "number" && Number.isFinite(value);
+    case "integer": return typeof value === "number" && Number.isInteger(value);
+    case "boolean": return typeof value === "boolean";
+    case "object": return value !== null && typeof value === "object" && !Array.isArray(value);
+    case "array": return Array.isArray(value);
+    case "null": return value === null;
+    default: return true; // unknown type keyword → do not fail on it
+  }
+}
+
+const jsonDeepEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// Resolve a local JSON-Pointer `$ref` (e.g. "#/$defs/Step" or "#/definitions/Step") against the
+// document root. Only same-document refs are supported (that is all the OpenAI SDK emits); a remote
+// or unresolvable ref returns null and the caller skips validation for it rather than failing.
+function resolveRef(ref, root) {
+  if (typeof ref !== "string" || !ref.startsWith("#/") || !root) return null;
+  const parts = ref.slice(2).split("/").map(p => p.replace(/~1/g, "/").replace(/~0/g, "~"));
+  let cur = root;
+  for (const p of parts) {
+    if (cur && typeof cur === "object" && Object.prototype.hasOwnProperty.call(cur, p)) cur = cur[p];
+    else return null;
+  }
+  return (cur && typeof cur === "object") ? cur : null;
+}
+
+// Minimal JSON-Schema validator: covers the subset OpenAI structured outputs use — type (incl.
+// arrays of types / integer), required, properties, additionalProperties (no invented keys), items
+// (list + tuple), enum, const, nullability (type:["x","null"] or nullable:true), min/maxItems, and
+// $ref/$defs + allOf/anyOf/oneOf composition (which the official OpenAI SDK emits heavily via
+// zodResponseFormat / client.beta.chat.completions.parse). `root` carries the top-level schema so
+// same-document $refs resolve. Returns error strings ([] = valid).
+// `refChain` tracks the $ref pointers resolved on the CURRENT path WITHOUT consuming data (a $ref
+// hop, or an allOf/anyOf/oneOf branch, all re-validate the same value). A pointer reappearing on
+// that chain is a pure ref→ref (or ref→composition→ref) cycle that recurses forever independent of
+// the data — we fail closed on it. Data-consuming recursion (properties/items/additionalProperties)
+// deliberately resets the chain (default []): it always terminates because a JSON value is a finite
+// tree, so a legitimately recursive schema (Node→child:Node) must NOT be flagged as a cycle. A depth
+// cap backstops any threading mistake. (PR #153 review round 2, cyclic-$ref blocker.)
+const REF_DEPTH_CAP = 512;
+export function validateJsonSchema(value, schema, path = "$", strict = false, root = schema, refChain = []) {
+  const errors = [];
+  if (!schema || typeof schema !== "object") return errors;
+  if (refChain.length > REF_DEPTH_CAP) { // defensive backstop; refChain cycle-check below is primary
+    errors.push(`${path}: $ref resolution too deep (possible cycle)`);
+    return errors;
+  }
+
+  // $ref: resolve against the document root ($defs / definitions) and validate the target. Without
+  // this a nested {$ref:"#/$defs/Step"} presents as {no type, no properties} — and under strict that
+  // used to wrongly reject every real key as "additional property not allowed" (the flagship OpenAI
+  // SDK shape). Sibling keywords alongside $ref (rare) are merged over the resolved target.
+  if (typeof schema.$ref === "string") {
+    if (refChain.includes(schema.$ref)) { // cyclic $ref (a→b→a, or self a→a) — fail closed.
+      errors.push(`${path}: cyclic $ref detected (${schema.$ref})`);
+      return errors;
+    }
+    const resolved = resolveRef(schema.$ref, root);
+    if (!resolved) return errors; // unresolvable ref → cannot validate; do not fail
+    const { $ref, ...siblings } = schema;
+    return validateJsonSchema(value, { ...resolved, ...siblings }, path, strict, root, [...refChain, schema.$ref]);
+  }
+
+  // Composition. allOf: every branch must pass. anyOf: at least one. oneOf: exactly one.
+  // These re-validate the SAME value → thread refChain so a ref cycle routed through a branch is caught.
+  if (Array.isArray(schema.allOf)) {
+    for (const sub of schema.allOf) errors.push(...validateJsonSchema(value, sub, path, strict, root, refChain));
+  }
+  if (Array.isArray(schema.anyOf)) {
+    if (!schema.anyOf.some(sub => validateJsonSchema(value, sub, path, strict, root, refChain).length === 0)) {
+      errors.push(`${path}: does not match any of the allowed schemas (anyOf)`);
+    }
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const matches = schema.oneOf.filter(sub => validateJsonSchema(value, sub, path, strict, root, refChain).length === 0).length;
+    if (matches !== 1) errors.push(`${path}: must match exactly one allowed schema (oneOf), matched ${matches}`);
+  }
+
+  // Nullability takes precedence: a null value is valid whenever the schema permits null (its type
+  // union includes "null", or nullable:true), regardless of enum/const. This mirrors OpenAI
+  // structured-output behaviour — nullable fields accept null even when a bare enum (as generated by
+  // Home Assistant's extended_openai_conversation) omits null from its value list.
+  const allowsNull = schema.nullable === true
+    || (Array.isArray(schema.type) ? schema.type.includes("null") : schema.type === "null");
+  if (value === null && allowsNull) return errors;
+
+  if (Array.isArray(schema.enum) && !schema.enum.some(e => jsonDeepEqual(e, value))) {
+    errors.push(`${path}: not one of the allowed enum values`);
+  }
+  if ("const" in schema && !jsonDeepEqual(schema.const, value)) {
+    errors.push(`${path}: does not equal the required const value`);
+  }
+
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const nullable = schema.nullable === true || types.includes("null");
+    const ok = types.some(t => jsonTypeMatches(t, value)) || (value === null && nullable);
+    if (!ok) {
+      errors.push(`${path}: expected ${types.join("|")}${schema.nullable ? "|null" : ""}, got ${jsonTypeOf(value)}`);
+      return errors; // type mismatch — deeper checks are meaningless
+    }
+  }
+  if (value === null) return errors;
+
+  const vt = jsonTypeOf(value);
+  if (vt === "object") {
+    const props = schema.properties || {};
+    for (const r of (schema.required || [])) {
+      if (!Object.prototype.hasOwnProperty.call(value, r)) errors.push(`${path}.${r}: required property missing`);
+    }
+    const addl = schema.additionalProperties;
+    // Only treat strict as implying "no additional properties" when this object actually declares
+    // its own `properties` and is NOT a composite (allOf/anyOf/oneOf put the real keys in sub-schemas,
+    // which are validated separately above). Inferring closure from an EMPTY properties map — the
+    // shape an unresolved $ref or a pure-composition node presents — would reject every real key.
+    // An explicit additionalProperties:false is always honoured. (PR #153 review, finding 1.)
+    const isComposite = Array.isArray(schema.allOf) || Array.isArray(schema.anyOf) || Array.isArray(schema.oneOf);
+    const noExtra = addl === false || (strict && addl === undefined && Object.keys(props).length > 0 && !isComposite);
+    for (const k of Object.keys(value)) {
+      if (props[k]) {
+        errors.push(...validateJsonSchema(value[k], props[k], `${path}.${k}`, strict, root));
+      } else if (isComposite) {
+        // key may be defined in an allOf/anyOf/oneOf branch — already validated there; don't reject.
+      } else if (noExtra) {
+        errors.push(`${path}.${k}: additional property not allowed`);
+      } else if (addl && typeof addl === "object") {
+        errors.push(...validateJsonSchema(value[k], addl, `${path}.${k}`, strict, root));
+      }
+    }
+  } else if (vt === "array" && schema.items) {
+    if (Array.isArray(schema.items)) {
+      schema.items.forEach((s, i) => { if (i < value.length) errors.push(...validateJsonSchema(value[i], s, `${path}[${i}]`, strict, root)); });
+    } else {
+      value.forEach((item, i) => errors.push(...validateJsonSchema(item, schema.items, `${path}[${i}]`, strict, root)));
+    }
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) errors.push(`${path}: fewer items than minItems ${schema.minItems}`);
+    if (typeof schema.maxItems === "number" && value.length > schema.maxItems) errors.push(`${path}: more items than maxItems ${schema.maxItems}`);
+  }
+  return errors;
+}
+
+// Crash-safe façade over validateJsonSchema (issue #181). The validator recurses on the DATA's
+// nesting depth (properties/items/additionalProperties), which the REF_DEPTH_CAP does NOT bound —
+// only the ref-chain is. A model reply nested ~2000 levels deep therefore overflowed the stack with
+// a RangeError, which the request handler caught as a generic HTTP 500 instead of the spec-correct
+// `refusal`. This wrapper converts ANY throw (the deep-data RangeError, or any future recursion
+// hazard) into a single validation error, so the structured-output retry loop treats a pathological
+// reply as "did not validate" → refusal — never a 500, never a crash. A well-formed reply is
+// unaffected: the inner validator returns and this just passes its errors through.
+export function validateJsonSchemaSafe(value, schema, path = "$", strict = false, root = schema) {
+  try {
+    return validateJsonSchema(value, schema, path, strict, root);
+  } catch (e) {
+    // Catch ONLY the deep-nesting stack overflow (the #181 vector) and turn it into a validation
+    // miss → retry → refusal, never a 500. Any OTHER throw is a genuine bug: re-throw it so it
+    // surfaces at error level instead of being silently masked as "did not validate" (reviewer
+    // finding — a catch-all would hide a future TypeError behind a warn-level structured_retry).
+    if (e instanceof RangeError) return [`${path}: schema validation aborted (value nesting too deep)`];
+    throw e;
+  }
+}
+
+function tryJsonParse(s) {
+  try { return { ok: true, value: JSON.parse(s) }; } catch { return { ok: false }; }
+}
+
+// Find the next brace-balanced JSON span at or after `from`. String-aware: brackets inside quoted
+// strings are ignored. Returns { text, start, end } for the first complete top-level span, or null.
+function balancedSlice(s, from) {
+  let start = -1;
+  for (let i = from; i < s.length; i++) { if (s[i] === "{" || s[i] === "[") { start = i; break; } }
+  if (start === -1) return null;
+  let depth = 0, inStr = false, esc = false;
+  for (let i = start; i < s.length; i++) {
+    const c = s[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') { inStr = true; continue; }
+    if (c === "{" || c === "[") depth++;
+    else if (c === "}" || c === "]") { depth--; if (depth === 0) return { text: s.slice(start, i + 1), start, end: i }; }
+  }
+  return null;
+}
+
+// Extract a single JSON value from model text. Two modes (PR #153 review, finding 2):
+//
+//   opts.whole === true  (json_object mode): the ENTIRE reply, after trimming and stripping one code
+//     fence, must parse as a single JSON value. json_object has no schema to validate against, so
+//     this whole-reply parse is its ONLY guard — a reply like `I can't. The schema is {"type":"object"}`
+//     must NOT parse-and-serve the embedded object as if it were the answer.
+//
+//   default (schema mode): prose-wrapped JSON is tolerated (models often add a sentence), BUT a reply
+//     containing MORE THAN ONE top-level JSON value is rejected rather than silently serving the first
+//     — "Schema: {...}\n\nAnswer: {...}" or "Option A: {...} Option B: {...}" is ambiguous, not an
+//     answer. The extracted value is still schema-validated by the caller.
+//
+// Returns { ok:true, value } | { ok:false, reason? }.
+export function extractJsonPayload(text, opts = {}) {
+  if (typeof text !== "string") return { ok: false };
+  let s = text.trim();
+  const fence = s.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  if (fence) s = fence[1].trim();
+
+  if (opts.whole) {
+    const whole = tryJsonParse(s);
+    return whole.ok ? whole : { ok: false, reason: "reply was not a single JSON value" };
+  }
+
+  const direct = tryJsonParse(s);
+  if (direct.ok) return direct;
+
+  const first = balancedSlice(s, 0);
+  if (!first) return { ok: false };
+  const parsedFirst = tryJsonParse(first.text);
+  if (!parsedFirst.ok) return { ok: false };
+
+  // Reject ambiguity: a second parseable top-level JSON value means we cannot know which is the answer.
+  const second = balancedSlice(s, first.end + 1);
+  if (second && tryJsonParse(second.text).ok) {
+    return { ok: false, reason: "reply contained more than one JSON value" };
+  }
+  return parsedFirst;
+}
+
+// The strict JSON-only system instruction appended to the request (attempt 0), escalated with the
+// prior failure reason on retries.
+export function structuredSystemInstruction(structured, attempt, lastErr) {
+  const schemaBlock = (structured.mode === "schema" && structured.schema)
+    ? `Your JSON MUST validate EXACTLY against this JSON Schema:\n${JSON.stringify(structured.schema)}\n`
+      + `- Include every required property.\n`
+      + `- Do NOT add any property that is not defined in the schema.\n`
+      + `- Respect all declared types, enums, and nullability.`
+    : `Respond with a single valid JSON value.`;
+  let text =
+`You are a strict JSON generator. Output a SINGLE JSON value and NOTHING else.
+- The response MUST begin with { or [ and end with the matching } or ].
+- Do NOT wrap the JSON in Markdown or code fences (no \`\`\`).
+- Do NOT include any prose, explanation, heading, comment, reasoning, or XML — only the raw JSON.
+${schemaBlock}`;
+  if (attempt > 0) {
+    text = `YOUR PREVIOUS RESPONSE WAS REJECTED (${lastErr}). Output ONLY the corrected raw JSON now, with no other text.\n\n` + text;
+  }
+  return text;
+}
@@ -1,6 +1,6 @@
 {
  "name": "open-claude-proxy",
-  "version": "3.22.1",
+  "version": "3.24.0",
  "description": "OCP (Open Claude Proxy) — use your Claude Pro/Max subscription as an OpenAI-compatible API for any IDE. Works with Cline, OpenCode, Aider, Continue.dev, OpenClaw, and more.",
  "type": "module",
  "bin": {
@@ -35,13 +35,14 @@
 */
 import { createServer } from "node:http";
 import { spawn, execFileSync, spawnSync } from "node:child_process";
-import { randomUUID, timingSafeEqual } from "node:crypto";
+import { randomUUID, timingSafeEqual, createHash as cryptoCreateHash } from "node:crypto";
 import { readFileSync, readdirSync, accessSync, existsSync, constants, chmodSync, statSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { validateKey, recordUsage, getUsageByKey, getUsageTimeline, getRecentUsage, createKey, listKeys, revokeKey, closeDb, checkQuota, updateKeyQuota, getKeyQuota, findKey, cacheHash, getCachedResponse, setCachedResponse, clearCache, getCacheStats, hasCacheControl, singleflight, getInflightStats } from "./keys.mjs";
 import { DEFAULT_PORT } from "./lib/constants.mjs";
+import { StructuredOutputError, detectStructuredOutput, validateJsonSchemaSafe, extractJsonPayload, structuredSystemInstruction, resolveMaxAttempts } from "./lib/structured-output.mjs";
 import { isLoopbackBind } from "./lib/net.mjs";
 import { runTuiTurn, reapStaleTuiSessions, resolveTuiHome, bootTuiPane, tuiPaneHealthy, poolPaneName, POOL_BOOT_MS } from "./lib/tui/session.mjs";
 import { detectTuiUpstreamError } from "./lib/tui/transcript.mjs";
@@ -49,6 +50,9 @@ import { TuiSemaphore, SemaphoreAbortError, recordTuiEntrypoint, buildTuiHealthB
 import { TuiPanePool, resolvePoolSize, POOL_MAX_SIZE } from "./lib/tui/pool.mjs";
 import { TuiDeltaAssembler, DEFAULT_HOLDBACK_CHARS, resolveStreamHoldback } from "./lib/tui/stream.mjs";
 import { createSerialMutex, createTtlCache, isTokenExpiring, orderLabelsLastGoodFirst } from "./lib/spawn-auth.mjs";
+import { hasImageContent, buildImageBlocks, buildStreamJsonInput, MultimodalError } from "./lib/multimodal.mjs";
+import { parsePositiveInt } from "./lib/env.mjs";
+import { appendOperatorPrompt, derivePromptCharBudget, selectPromptWrapper, localToolsSafetyError } from "./lib/prompt.mjs";

 const __dirname = dirname(fileURLToPath(import.meta.url));
 const _pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
@@ -194,18 +198,40 @@ function resolveClaude() {
 // Reference: https://github.com/dtzp555-max/olp commit 97e7d16 (Phase 6c)
 const OCP_SYSTEM_PROMPT_WRAPPER = `You are accessed via the OCP HTTP proxy. You do NOT have access to any local filesystem, working directory, shell, git status, or machine environment. Do not infer or invent such information from any context you observe. Respond only based on the conversation provided.`;

-// Build the full system-prompt string: OCP_SYSTEM_PROMPT_WRAPPER prepended,
-// then any system-role messages from the request appended (separated by blank line).
-// ADR 0009 Amendment 1 analogue § "OLP system prompt wrapper".
+// Positive counterpart used only when OCP_LOCAL_TOOLS=1 — a single-user, loopback-bound instance
+// where the operator's own model legitimately has tools (the `-p` path passes --allowedTools). Tells
+// the model it MAY use them instead of disclaiming access it actually holds. Off by default; the
+// default wrapper above is byte-for-byte unchanged. Selecting the positive wrapper does NOT expand
+// the tool surface (governed independently by --allowedTools/--disallowedTools) — it only changes the
+// prompt — and is boot-gated below (multi/non-loopback/anon → refuse) mirroring OCP_TUI_FULL_TOOLS.
+const OCP_LOCAL_TOOLS_WRAPPER = `You are accessed via the OCP HTTP proxy running on the operator's own machine. You have full access to the local filesystem, working directory, and shell through your available tools (Bash, Read, Write, Edit, Glob, Grep, etc.). Use them as needed to complete the operator's requests.`;
+
+// OCP_LOCAL_TOOLS is inert in TUI mode: the interactive (non-`-p`) path composes its own prompt via
+// callClaudeTui/messagesToPrompt and never calls extractSystemPrompt, so the wrapper is only ever
+// applied on the `-p` path. LOCAL_TOOLS_ACTIVE is the single source of truth (hoisted once, house
+// style) used by the wrapper selection, the boot gate, and the startup notice — so the flag is
+// enabled/announced/gated in exactly the mode where it has an effect. (TUI tool surface is governed
+// by OCP_TUI_FULL_TOOLS instead.)
+const LOCAL_TOOLS = process.env.OCP_LOCAL_TOOLS === "1";
+const LOCAL_TOOLS_ACTIVE = LOCAL_TOOLS && process.env.CLAUDE_TUI_MODE !== "true";
+
+// The wrapper actually prepended to each request's system prompt, chosen once at startup.
+const SYSTEM_PROMPT_WRAPPER = selectPromptWrapper(LOCAL_TOOLS_ACTIVE, OCP_SYSTEM_PROMPT_WRAPPER, OCP_LOCAL_TOOLS_WRAPPER);
+
+// Build the full system-prompt string: SYSTEM_PROMPT_WRAPPER prepended,
+// then any system-role messages from the request appended (separated by blank line),
+// then the operator-wide CLAUDE_SYSTEM_PROMPT appended LAST (lib/prompt.mjs — a
+// no-op returning the same string when the var is unset, so the default path is
+// byte-for-byte unchanged). ADR 0009 Amendment 1 analogue § "OLP system prompt wrapper".
 function extractSystemPrompt(messages) {
  const systemMessages = (messages ?? []).filter(m => m.role === "system");
  if (systemMessages.length === 0) {
-    return OCP_SYSTEM_PROMPT_WRAPPER;
+    return appendOperatorPrompt(SYSTEM_PROMPT_WRAPPER, SYSTEM_PROMPT);
  }
  const clientContent = systemMessages.map(m =>
    contentToText(m.content)
  ).join("\n\n");
-  return `${OCP_SYSTEM_PROMPT_WRAPPER}\n\n${clientContent}`;
+  return appendOperatorPrompt(`${SYSTEM_PROMPT_WRAPPER}\n\n${clientContent}`, SYSTEM_PROMPT);
 }

 // ── NDJSON line buffer parser (Phase 6c port) ─────────────────────────────
@@ -245,8 +271,8 @@ function parseStreamJsonLines(buffered) {
 // Reference: OLP lib/providers/anthropic.mjs anthropicStreamJsonEventToIR (commit 97e7d16).
 //
 // @param {object} event — parsed NDJSON event
-// @param {boolean} isFirstDelta — true if no content has been yielded yet
-function parseStreamJsonEvent(event, isFirstDelta) {
+// @param {boolean} sawTextDelta — true if a streaming content_block_delta text was already seen
+function parseStreamJsonEvent(event, sawTextDelta) {
  const t = event?.type;

  // system/* — first-event init + other system meta (api_retry etc.)
@@ -258,19 +284,23 @@ function parseStreamJsonEvent(event, isFirstDelta) {
  if (t === "stream_event") {
    const inner = event.event ?? event;
    if (inner?.type === "content_block_delta" && inner.delta?.type === "text_delta") {
-      return { text: inner.delta.text ?? "" };
+      return { text: inner.delta.text ?? "", fromDelta: true };
    }
    // Other stream_event sub-types (content_block_start, message_delta, etc.) — consumed
    return null;
  }

-  // assistant — aggregate message (fallback when no prior content_block_delta seen)
-  // Empirically (claude CLI without --include-partial-messages, verified v2.1.104 through v2.1.158): fast/short
-  // responses may emit ONLY the aggregate assistant event, no content_block_delta events.
-  // If isFirstDelta is true, extract text here; otherwise it's a duplicate, ignore.
+  // assistant — aggregate message. claude CLI without --include-partial-messages emits NO
+  // content_block_delta events; each assistant message arrives as its own aggregate `assistant`
+  // event. An agentic/tool-using turn has SEVERAL (preamble + one per tool round + final answer),
+  // so we must accumulate the text of EVERY such event. The prior `isFirstDelta` guard kept only
+  // the FIRST message's text and dropped the rest — silently losing the post-tool-use final answer
+  // on every tool-using turn (verified v2.1.104 through v2.1.211; see PR body capture).
+  // The only real hazard is the delta+aggregate DOUBLE-COUNT: if streaming deltas were already
+  // seen (sawTextDelta), the aggregate duplicates them — ignore it.
  // Reference: OLP commit 65f945c (assistant-aggregate fallback, fold-in).
  if (t === "assistant") {
-    if (isFirstDelta) {
+    if (!sawTextDelta) {
      const blocks = event.message?.content;
      if (Array.isArray(blocks)) {
        const text = blocks
@@ -324,6 +354,16 @@ const ALLOWED_TOOLS = (process.env.CLAUDE_ALLOWED_TOOLS ||
  "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch,Agent"
 ).split(",").map(s => s.trim()).filter(Boolean);
 const SYSTEM_PROMPT = process.env.CLAUDE_SYSTEM_PROMPT || "";
+// Max attempts (initial + retries) to coerce a valid structured-output (OpenAI response_format)
+// JSON response out of the model before rejecting. See runStructuredCompletion.
+// Fail closed on a non-numeric value via resolveMaxAttempts(): the old `Math.max(1, parseInt("abc",10))`
+// === `Math.max(1, NaN)` === NaN, which made the retry loop `attempt < NaN` never execute → 0 spawns,
+// every structured request silently refused. The helper rejects NaN/non-finite/<1 and keeps the
+// documented default of 3. (PR #153 review round 2, NaN-guard must-fix.)
+const STRUCTURED_MAX_ATTEMPTS = resolveMaxAttempts(
+  process.env.OCP_STRUCTURED_MAX_ATTEMPTS,
+  { fallback: 3, warn: (m) => console.warn(`[init] ${m}`) },
+);
 const MCP_CONFIG = process.env.CLAUDE_MCP_CONFIG || "";
 let SESSION_TTL = parseInt(process.env.CLAUDE_SESSION_TTL || "3600000", 10);
 let MAX_CONCURRENT = parseInt(process.env.CLAUDE_MAX_CONCURRENT || "8", 10);
@@ -343,6 +383,19 @@ const BREAKER_HALF_OPEN_MAX = parseInt(process.env.CLAUDE_BREAKER_HALF_OPEN_MAX
 const HEARTBEAT_INTERVAL = parseInt(process.env.CLAUDE_HEARTBEAT_INTERVAL || "0", 10);
 const BIND_ADDRESS = process.env.CLAUDE_BIND || "127.0.0.1";
 const NO_CONTEXT = process.env.CLAUDE_NO_CONTEXT === "true";
+// Config epoch for the response cache (issue #176). The cache key hashes model + messages +
+// sampling params, but the ANSWER also depends on boot-time server config that shapes the
+// composed prompt / tool surface: the operator system prompt (#175), the OCP wrapper text,
+// the allowed-tools set, and NO_CONTEXT. The cache store is SQLite-backed and survives
+// restarts, so without this an operator who changes any of these and restarts keeps serving
+// answers composed under the OLD config until TTL expiry. Folding a digest of the four into
+// every cache key makes any change an instant, whole-cache invalidation — the honest behavior.
+// Deliberately boot-time-only: runtime-mutable settings (e.g. maxPromptChars via the settings
+// API) are excluded because a const epoch cannot track them; truncation also only drops
+// context rather than changing the instruction set.
+const CONFIG_EPOCH = cryptoCreateHash("sha256")
+  .update(JSON.stringify([SYSTEM_PROMPT, SYSTEM_PROMPT_WRAPPER, ALLOWED_TOOLS, NO_CONTEXT]))
+  .digest("hex").slice(0, 16);
 // Kill-switch for the FIX-③ default-path spawn-home isolation (see resolveSpawnHome /
 // spawnHomeMode below). When "1", the -p/stream-json spawn always runs in the operator's
 // real HOME with no cwd override — byte-for-byte the pre-isolation behaviour — even if an
@@ -779,6 +832,21 @@ if (TUI_MODE && PROXY_ANONYMOUS_KEY) {
  process.exit(1);
 }

+// OCP_LOCAL_TOOLS safety gate (mirrors the OCP_TUI_FULL_TOOLS model, ADR 0007): the positive
+// "you may use local tools" system-prompt wrapper is single-user only, so refuse to boot if it
+// could reach an untrusted caller. Fail-closed on multi-tenant auth, a non-loopback bind, or an
+// anonymous key. The pure predicate lives in lib/prompt.mjs (unit-tested); the exit stays here.
+const _localToolsBootError = localToolsSafetyError({
+  enabled: LOCAL_TOOLS_ACTIVE,
+  authMode: AUTH_MODE,
+  loopbackBind: isLoopbackBind(BIND_ADDRESS),
+  anonymousKey: !!PROXY_ANONYMOUS_KEY,
+});
+if (_localToolsBootError) {
+  console.error(`FATAL: ${_localToolsBootError}\n  See README § "Environment Variables" (OCP_LOCAL_TOOLS) and docs/adr/0007-tui-interactive-mode.md. Refusing to start.`);
+  process.exit(1);
+}
+
 if (PROXY_ANONYMOUS_KEY && AUTH_MODE !== "multi") {
  console.warn("WARNING: PROXY_ANONYMOUS_KEY is set but AUTH_MODE is not 'multi' — anonymous key will be ignored");
 }
@@ -1084,7 +1152,7 @@ const authCheckInterval = setInterval(checkAuth, 600000);
 // CLAUDE_SYSTEM_PROMPT env var is absorbed into the system prompt via
 // extractSystemPrompt() at the caller level; APPEND_SYSTEM_PROMPT no longer used.
 // Note: ALLOWED_TOOLS / SKIP_PERMISSIONS / MCP_CONFIG are preserved as before.
-function buildCliArgs(cliModel, systemPrompt) {
+function buildCliArgs(cliModel, systemPrompt, opts = {}) {
  const args = [
    "--model", cliModel,
    "--output-format", "stream-json",
@@ -1093,6 +1161,14 @@ function buildCliArgs(cliModel, systemPrompt) {
    "--system-prompt", systemPrompt,
  ];

+  // Multimodal path (issue #110): images are fed as Anthropic content blocks over
+  // a stream-json stdin stream. `--input-format stream-json` (§ --input-format,
+  // choices text|stream-json; realtime streaming input) is added ONLY when the
+  // request carries an image part; the default (text) input path is untouched.
+  if (opts.streamJsonInput) {
+    args.push("--input-format", "stream-json");
+  }
+
  // Permissions
  // ADR 0007 B-path: in multi-tenant mode, suppress operator-FS tools so a guest
  // prompt cannot drive Bash/Read/Write/Edit/etc. on the operator's filesystem.
@@ -1128,11 +1204,45 @@ function buildCliArgs(cliModel, systemPrompt) {
  return args;
 }

+// Thin env wrapper over parsePositiveInt (lib/env.mjs): resolve `name` from the
+// environment fail-closed, warning on a present-but-invalid value. Keeps the pure
+// parse in a unit-testable module. (PR #154 review F3)
+function parseIntEnv(name, def) {
+  const { value, ok } = parsePositiveInt(process.env[name], def);
+  if (!ok) console.warn(`⚠ ${name}="${process.env[name]}" is not a valid positive integer (bytes/count, no unit suffix); ignoring and using default ${def}.`);
+  return value;
+}
+
 // ── Format messages to prompt text ──────────────────────────────────────
 // Truncation guard: if total chars exceed MAX_PROMPT_CHARS, keep the system
 // message(s) + first user message + last N messages, dropping the middle.
 // This prevents runaway context from gateway-side conversation accumulation.
-let MAX_PROMPT_CHARS = parseInt(process.env.CLAUDE_MAX_PROMPT_CHARS || "150000", 10);
+// Routed through parseIntEnv so a misconfigured cap fails CLOSED to the default rather than
+// NaN — CLAUDE_MAX_PROMPT_CHARS=unlimited previously → NaN → enforceTextBudget's `!(NaN > 0)`
+// early-return → 500k chars passed unbounded, silently defeating F2's text-budget guarantee
+// (PR #154 round 2, gap (a)). The default itself is SPOT-DERIVED (ADR 0009, PR #179):
+// max(models.json contextWindow) × 3 chars/token — currently 600,000 — so the two fixes
+// compose: parseIntEnv guards a SET-but-garbage value, the derivation supplies the honest
+// default when unset/empty. `let` is kept for the settings API.
+let MAX_PROMPT_CHARS = parseIntEnv("CLAUDE_MAX_PROMPT_CHARS", derivePromptCharBudget(modelsConfig.models));
+
+// ── Multimodal image caps (issue #110) ──────────────────────────────────
+// OpenAI `image_url` parts are forwarded to claude as Anthropic image blocks via
+// `--input-format stream-json`. Images deliberately BYPASS the text char budget
+// (MAX_PROMPT_CHARS) — they are bounded by these byte/count caps instead, and by
+// MAX_BODY_SIZE at the HTTP layer. Data URIs are supported by default; remote
+// http(s) image URLs are OFF unless CLAUDE_IMAGE_ALLOW_URL is set (v1: data URIs
+// only). See docs/adr/0006-openai-shim-scope.md (Class B.1) and README § "Images".
+const IMAGE_ALLOW_URL = /^(1|true|yes|on)$/i.test(process.env.CLAUDE_IMAGE_ALLOW_URL || "");
+const MAX_IMAGE_BYTES = parseIntEnv("CLAUDE_MAX_IMAGE_BYTES", 5 * 1024 * 1024);
+const MAX_IMAGES = parseIntEnv("CLAUDE_MAX_IMAGES", 20);
+const MAX_IMAGE_TOTAL_BYTES = parseIntEnv("CLAUDE_MAX_IMAGE_TOTAL_BYTES", 20 * 1024 * 1024);
+const MULTIMODAL_OPTS = {
+  allowRemoteUrl: IMAGE_ALLOW_URL,
+  maxImageBytes: MAX_IMAGE_BYTES,
+  maxImages: MAX_IMAGES,
+  maxTotalImageBytes: MAX_IMAGE_TOTAL_BYTES,
+};

 // Flatten OpenAI content (string | array of parts) to plain text for the prompt.
 // Array content: concatenate text parts; replace non-text parts (e.g. image_url)
@@ -1224,25 +1334,51 @@ function spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlo

  // Circuit breaker: disabled (see comment at top of breaker section)

-  stats.activeRequests++;
-  stats.totalRequests++;
-
  // Phase 6c: always serialize full conversation via stdin (no session resume).
  // System messages are extracted and passed via --system-prompt; the remaining
-  // messages (user/assistant/tool) are serialized by messagesToPrompt.
+  // messages (user/assistant/tool) are serialized for stdin.
  const systemPrompt = extractSystemPrompt(messages);

-  // messagesToPrompt skips system messages now that they go via --system-prompt.
-  // Filter them out before calling to avoid double-injection.
+  // messagesToPrompt / buildStreamJsonInput skip system messages (they go via
+  // --system-prompt). Filter them out first to avoid double-injection.
  const nonSystemMessages = messages.filter(m => m.role !== "system");
-  const prompt = messagesToPrompt(nonSystemMessages);

-  stats.oneOffRequests++;
-  if (conversationId) {
-    console.log(`[session] stateless conv=${conversationId.slice(0, 12)}... key=${keyName || "anon"} msgs=${messages.length} prompt_chars=${prompt.length}`);
+  // Multimodal (issue #110): when any message carries an OpenAI image_url part,
+  // feed the conversation as Anthropic content blocks over --input-format
+  // stream-json (images preserved and kept OUT of the text char budget).
+  // Otherwise the text path is byte-for-byte unchanged. buildStreamJsonInput may
+  // throw MultimodalError on an invalid/oversized image; it runs BEFORE any stats
+  // mutation so a validation failure never leaks counters or the concurrency slot
+  // (handleChatCompletions validates first, so in practice it will not throw here).
+  const useStreamJson = hasImageContent(nonSystemMessages);
+  let stdinPayload, promptChars;
+  if (useStreamJson) {
+    // Pass MAX_PROMPT_CHARS so the multimodal text is bounded by the same
+    // runaway-context guard as the text path (PR #154 review F2). Images bypass it.
+    const built = buildStreamJsonInput(nonSystemMessages, { ...MULTIMODAL_OPTS, maxTextChars: MAX_PROMPT_CHARS });
+    stdinPayload = built.payload;
+    promptChars = built.stats.textChars;
+    if (built.stats.truncated) {
+      logEvent("warn", "prompt_truncated", {
+        originalChars: built.stats.originalTextChars,
+        maxChars: MAX_PROMPT_CHARS,
+        keptChars: built.stats.textChars,
+        path: "multimodal",
+      });
+    }
+  } else {
+    stdinPayload = messagesToPrompt(nonSystemMessages);
+    promptChars = stdinPayload.length;
  }

-  const cliArgs = buildCliArgs(cliModel, systemPrompt);
+  stats.activeRequests++;
+  stats.totalRequests++;
+  stats.oneOffRequests++;
+  if (conversationId) {
+    console.log(`[session] stateless conv=${conversationId.slice(0, 12)}... key=${keyName || "anon"} msgs=${messages.length} prompt_chars=${promptChars}`);
+  }
+
+  const cliArgs = buildCliArgs(cliModel, systemPrompt, { streamJsonInput: useStreamJson });

  const env = { ...process.env };
  delete env.CLAUDECODE;
@@ -1328,12 +1464,13 @@ function spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlo
  // the spawned process, NOT on the stdin Writable — it does not catch this.
  proc.stdin.on("error", (e) => logEvent("warn", "stdin_write_error", { error: e.message }));

-  // Write prompt to stdin immediately
-  proc.stdin.write(prompt);
+  // Write the serialized turn to stdin immediately. Text path: the flat prompt.
+  // Multimodal path: a single newline-terminated stream-json user envelope.
+  proc.stdin.write(stdinPayload);
  proc.stdin.end();

-  recordModelRequest(cliModel, prompt.length);
-  logEvent("info", "claude_spawned", { model: cliModel, promptChars: prompt.length, timeout: TIMEOUT, tier: getModelTier(cliModel), session: conversationId ? conversationId.slice(0, 12) + "..." : "none" });
+  recordModelRequest(cliModel, promptChars);
+  logEvent("info", "claude_spawned", { model: cliModel, promptChars, inputFormat: useStreamJson ? "stream-json" : "text", timeout: TIMEOUT, tier: getModelTier(cliModel), session: conversationId ? conversationId.slice(0, 12) + "..." : "none" });

  // Single request timeout — no separate first-byte timer.
  // Claude tool-use causes long pauses in the token stream (30s-5min),
@@ -1403,7 +1540,7 @@ async function callClaude(model, messages, conversationId, keyName, res) {
    const { proc, cliModel, conversationId: convId, t0, cleanup, handleSessionFailure, markFirstByte } = ctx;
    let lineBuffer = "";
    let assembledText = "";
-    let isFirstDelta = true;
+    let sawTextDelta = false;
    let resultEventSeen = false;
    let stderr = "";

@@ -1413,11 +1550,18 @@ async function callClaude(model, messages, conversationId, keyName, res) {
      const { events, remainder } = parseStreamJsonLines(lineBuffer);
      lineBuffer = remainder;
      for (const event of events) {
-        const parsed = parseStreamJsonEvent(event, isFirstDelta);
+        const parsed = parseStreamJsonEvent(event, sawTextDelta);
        if (!parsed) continue;
        if (parsed.text !== undefined) {
-          assembledText += parsed.text;
-          isFirstDelta = false;
+          if (parsed.fromDelta) {
+            assembledText += parsed.text;
+            sawTextDelta = true;
+          } else {
+            // aggregate assistant message — separate successive messages so the preamble and
+            // the post-tool-use final answer don't run together.
+            if (assembledText && !assembledText.endsWith("\n")) assembledText += "\n\n";
+            assembledText += parsed.text;
+          }
        } else if (parsed.stop) {
          resultEventSeen = true;
        } else if (parsed.error) {
@@ -1839,9 +1983,10 @@ async function callClaudeStreaming(model, messages, conversationId, res, authInf
  let stderr = "";
  let headersSent = false;
  let totalChars = 0;
+  let streamEndsWithNewline = false; // tracks whether emitted text ends in "\n" — see the separator guard below
  let cachedContent = ""; // accumulate for cache write-back
  let lineBuffer = "";
-  let isFirstDelta = true;
+  let sawTextDelta = false;
  let resultEventSeen = false;
  // Separate flag for is_error result — must NOT be conflated with resultEventSeen.
  // If errored===true the close handler must not cache the response or record success
@@ -1878,15 +2023,26 @@ async function callClaudeStreaming(model, messages, conversationId, res, authInf
    lineBuffer = remainder;

    for (const event of events) {
-      const parsed = parseStreamJsonEvent(event, isFirstDelta);
+      const parsed = parseStreamJsonEvent(event, sawTextDelta);
      if (!parsed) continue;

      if (parsed.text !== undefined) {
-        // content_block_delta text — forward as SSE delta
-        const text = parsed.text;
+        // Streamed delta, or an aggregate assistant-message text (agentic turns emit several).
+        // For an aggregate message after earlier text, prepend a separator so the preamble and
+        // the post-tool-use final answer don't run together in the forwarded stream.
+        let text = parsed.text;
+        if (parsed.fromDelta) {
+          sawTextDelta = true;
+        } else if (totalChars > 0 && !streamEndsWithNewline) {
+          // Mirror the buffered path's guard (assembledText.endsWith("\n")): only inject the
+          // blank-line separator when the already-emitted text doesn't already end in a newline,
+          // so a message ending in "\n" doesn't produce a triple newline here while the buffered
+          // path produces a single. Keeps the two assembly paths byte-identical. (PR #183 review.)
+          text = "\n\n" + text;
+        }
+        streamEndsWithNewline = text.endsWith("\n");
        totalChars += text.length;
        if (CACHE_TTL > 0) cachedContent += text;
-        isFirstDelta = false;

        if (!ensureHeaders()) continue;
        sendSSE(res, {
@@ -2056,6 +2212,31 @@ function completionResponse(res, id, model, content) {
  });
 }

+// OpenAI's designated mechanism for "the model would not produce the required output" is the
+// assistant `refusal` field (content:null, refusal:<text>, finish_reason:"stop") — NOT an invented
+// error type. Structured-output exhaustion emits this so SDK clients take their written `refusal`
+// branch instead of throwing an opaque UnprocessableEntityError. (PR #153 review, finding 3.)
+function refusalResponse(res, id, model, refusal) {
+  jsonResponse(res, 200, {
+    id, object: "chat.completion",
+    created: Math.floor(Date.now() / 1000),
+    model,
+    choices: [{ index: 0, message: { role: "assistant", content: null, refusal }, finish_reason: "stop" }],
+    usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+  });
+}
+
+// Streaming form of refusalResponse: a role chunk, a `refusal` delta, then the stop chunk.
+function streamRefusalAsSSE(res, id, model, refusal) {
+  const created = Math.floor(Date.now() / 1000);
+  res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no" });
+  sendSSE(res, { id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null }] });
+  sendSSE(res, { id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: { refusal }, finish_reason: null }] });
+  sendSSE(res, { id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: {}, finish_reason: "stop" }] });
+  res.write("data: [DONE]\n\n");
+  res.end();
+}
+
 // Replay a complete string as a chunked SSE stream (80 codepoints/chunk).
 // Used by: (a) cache-hit replay on the streaming path; (b) TUI-mode streaming
 // (buffered response replayed as SSE so clients get the same wire format).
@@ -2557,18 +2738,58 @@ async function handleSettings(req, res) {
 }

 // ── Handle chat completions ─────────────────────────────────────────────
-const MAX_BODY_SIZE = 5 * 1024 * 1024; // 5 MB
+// Default 5 MB, byte-for-byte unchanged unless CLAUDE_MAX_BODY_SIZE is set. Base64
+// image payloads inflate ~33%; operators enabling large images (issue #110) can
+// raise this to admit bigger requests. Parsed fail-closed (PR #154 review F3): a
+// bad value (`unlimited` → NaN, `5MB` → 5) must not disable the body cap or brick
+// the proxy — parseIntEnv keeps the 5 MB default and warns instead.
+const MAX_BODY_SIZE = parseIntEnv("CLAUDE_MAX_BODY_SIZE", 5 * 1024 * 1024);
+const MAX_BODY_SIZE_LABEL = `${Math.round(MAX_BODY_SIZE / (1024 * 1024))}MB`;

 // Set of all valid model identifiers (canonical IDs + aliases)
 const VALID_MODELS = new Set(Object.keys(MODEL_MAP));

+// Drive the model to a valid structured-output (OpenAI response_format) JSON string, retrying up to
+// STRUCTURED_MAX_ATTEMPTS. Appends a strict JSON-only steering instruction, extracts + validates the
+// reply (pure helpers in lib/structured-output.mjs), and escalates the instruction on failure.
+// Returns the canonical JSON string (message.content) or throws StructuredOutputError.
+async function runStructuredCompletion(upstreamCall, model, messages, conversationId, keyName, res, structured) {
+  let lastErr = "no valid JSON produced";
+  let lastRaw = "";
+  for (let attempt = 0; attempt < STRUCTURED_MAX_ATTEMPTS; attempt++) {
+    const augmented = [...messages, { role: "system", content: structuredSystemInstruction(structured, attempt, lastErr) }];
+    const raw = await upstreamCall(model, augmented, conversationId, keyName, res);
+    lastRaw = raw;
+    const extracted = extractJsonPayload(raw, { whole: structured.mode === "json_object" });
+    if (!extracted.ok) {
+      lastErr = extracted.reason || "response was not parseable as JSON";
+      logEvent("warn", "structured_retry", { attempt, reason: extracted.reason || "unparseable" });
+      continue;
+    }
+    if (structured.mode === "schema" && structured.schema) {
+      // validateJsonSchemaSafe (#181): a pathologically deep model reply overflows the value-depth
+      // recursion; the safe façade turns that into a validation miss (→ retry → refusal) instead of
+      // a caught RangeError surfacing as a generic 500.
+      const errs = validateJsonSchemaSafe(extracted.value, structured.schema, "$", structured.strict);
+      if (errs.length) {
+        lastErr = "schema validation failed: " + errs.slice(0, 5).join("; ");
+        logEvent("warn", "structured_retry", { attempt, reason: "schema", errors: errs.slice(0, 5) });
+        continue;
+      }
+    }
+    if (attempt > 0) logEvent("info", "structured_recovered", { attempt });
+    return JSON.stringify(extracted.value); // canonical, fence-free, prose-free
+  }
+  throw new StructuredOutputError(lastErr, lastRaw);
+}
+
 async function handleChatCompletions(req, res) {
  let body = "";
  try {
    for await (const chunk of req) {
      body += chunk;
      if (body.length > MAX_BODY_SIZE) {
-        return jsonResponse(res, 413, { error: { message: "Request body too large (max 5MB)", type: "invalid_request_error" } });
+        return jsonResponse(res, 413, { error: { message: `Request body too large (max ${MAX_BODY_SIZE_LABEL})`, type: "invalid_request_error" } });
      }
    }
  } catch (e) {
@@ -2597,6 +2818,57 @@ async function handleChatCompletions(req, res) {
    return jsonResponse(res, 400, { error: { message: "'messages' must be a non-empty array", type: "invalid_request_error" } });
  }

+  // Multimodal validation (issue #110): when a request carries OpenAI `image_url`
+  // content parts, validate/parse them now so an invalid, unsupported, or oversized
+  // image returns a clean 4xx BEFORE the cache/spawn path (rather than a silent drop
+  // or an opaque 500). The stream-json transform itself runs at spawn time
+  // (spawnClaudeProcess → buildStreamJsonInput). Class B.1: authorized by ADR 0006;
+  // request shape per OpenAI vision spec (image_url content parts). buildImageBlocks
+  // validates without stringifying, so this early pass is cheap.
+  if (hasImageContent(messages)) {
+    // F1 (PR #154 review): the TUI path (callClaudeTui → messagesToPrompt) cannot
+    // carry image blocks — it renders every non-text part as "[non-text content
+    // omitted]". Forwarding here would let the model answer about an image it never
+    // saw and return 200, which is strictly worse than an honest error (the one
+    // outcome ALIGNMENT.md forbids: silently serving text the model did not mean).
+    // Stream-json image input requires the `claude -p` path, so in TUI_MODE we fail
+    // loudly instead of dropping. Documented in README § "Images".
+    if (TUI_MODE) {
+      return jsonResponse(res, 400, {
+        error: {
+          message: "Image inputs are not supported in TUI mode (CLAUDE_TUI_MODE=true). Images require the default -p spawn path; remove images or run OCP without TUI mode.",
+          type: "invalid_request_error",
+          code: "images_unsupported_in_tui_mode",
+        },
+      });
+    }
+    // Detection runs on the FULL message list, but extraction/spawn drop system messages
+    // (system role carries no image blocks to the CLI). So an image present ONLY in a
+    // system message would be detected as multimodal, survive no filter, fall to the text
+    // path, and render as "[non-text content omitted]" → 200 with a hallucinated answer —
+    // the exact silent-drop this guard exists to forbid. Fail loudly instead. OpenAI
+    // disallows images in the system role anyway, so no legitimate request is rejected.
+    // (PR #154 review round 2, gap (b).)
+    const nonSystem = messages.filter(m => m.role !== "system");
+    if (!hasImageContent(nonSystem)) {
+      return jsonResponse(res, 400, {
+        error: {
+          message: "Image inputs are only supported in user/assistant messages, not in system messages. Move the image_url part to a user message.",
+          type: "invalid_request_error",
+          code: "images_unsupported_in_system_messages",
+        },
+      });
+    }
+    try {
+      buildImageBlocks(nonSystem, { ...MULTIMODAL_OPTS, maxTextChars: MAX_PROMPT_CHARS });
+    } catch (e) {
+      if (e instanceof MultimodalError) {
+        return jsonResponse(res, e.status, { error: { message: e.message, type: e.type, code: e.code } });
+      }
+      throw e;
+    }
+  }
+
  // NOTE: quota is best-effort / eventually-consistent. The gate reads the recorded count
  // at entry and records only after the upstream completes, so concurrent requests at the
  // boundary can overshoot the cap by up to MAX_CONCURRENT, and cache hits (served before
@@ -2618,6 +2890,74 @@ async function handleChatCompletions(req, res) {
    }
  }

+  // Structured output (OpenAI response_format / json_mode): its own path — the response must be
+  // schema-valid JSON, so it never shares the conversational cache slot. When caching is enabled it
+  // uses a structured-keyed hash (isolated via cacheHash's `structured` marker) and writes back ONLY
+  // a validated result (never a 422). Always validates on a miss.
+  const structured = detectStructuredOutput(parsed);
+  if (structured) {
+    const t0s = Date.now();
+    const promptCharsS = messages.reduce((a, m) => a + contentToText(m.content).length, 0);
+    let structuredHash = null;
+    if (CACHE_TTL > 0 && !conversationId && !hasCacheControl(messages)) {
+      structuredHash = cacheHash(model, messages, { keyId: req._authKeyId, temperature: parsed.temperature, max_tokens: parsed.max_tokens, top_p: parsed.top_p, structured });
+      try {
+        const cached = getCachedResponse(structuredHash, CACHE_TTL);
+        if (cached) {
+          logEvent("info", "cache_hit", { model, hash: structuredHash.slice(0, 12), hits: cached.hits, structured: true });
+          const id = `chatcmpl-${randomUUID()}`;
+          if (stream) streamStringAsSSE(res, id, model, cached.response);
+          else completionResponse(res, id, model, cached.response);
+          return;
+        }
+      } catch (e) { logEvent("error", "cache_check_failed", { error: e.message }); }
+    }
+    const upstreamCall = TUI_MODE ? callClaudeTui : callClaude;
+    // Stampede protection (PR #153 review, finding 5): a structured request can cost up to
+    // STRUCTURED_MAX_ATTEMPTS metered spawns, so N identical concurrent requests (Home Assistant
+    // firing several AI Tasks at once) must NOT each pay N× — they share one flight. We dedup every
+    // one-off structured request (not stateful sessions / client-side prompt caching), independent of
+    // whether OCP response caching is enabled; when caching IS on, the same key gates cache read/write.
+    const dedupKey = (!conversationId && !hasCacheControl(messages))
+      ? cacheHash(model, messages, { keyId: req._authKeyId, temperature: parsed.temperature, max_tokens: parsed.max_tokens, top_p: parsed.top_p, structured })
+      : null;
+    const runStructured = async () => {
+      const c = await runStructuredCompletion(upstreamCall, model, messages, conversationId, req._authKeyName, res, structured);
+      if (structuredHash) { try { setCachedResponse(structuredHash, model, c); } catch (e) { logEvent("error", "cache_write_failed", { error: e.message }); } }
+      return c;
+    };
+    try {
+      const content = dedupKey
+        ? await singleflight(dedupKey, async () => {
+            // A follower that raced in after the leader populated the cache re-reads it here.
+            if (structuredHash) { const rc = getCachedResponse(structuredHash, CACHE_TTL); if (rc) return rc.response; }
+            return runStructured();
+          }, (err) => err instanceof RequestDisconnectedError && !res.destroyed)
+        : await runStructured();
+      const id = `chatcmpl-${randomUUID()}`;
+      if (stream) streamStringAsSSE(res, id, model, content);
+      else completionResponse(res, id, model, content);
+      try { recordUsage({ keyId: req._authKeyId, keyName: req._authKeyName, model, promptChars: promptCharsS, responseChars: content.length, elapsedMs: Date.now() - t0s, success: true }); } catch (e) { logEvent("error", "usage_record_failed", { error: e.message }); }
+      return;
+    } catch (err) {
+      if (err instanceof RequestDisconnectedError) { try { res.end(); } catch {} return; }
+      try { recordUsage({ keyId: req._authKeyId, keyName: req._authKeyName, model, promptChars: promptCharsS, responseChars: 0, elapsedMs: Date.now() - t0s, success: false }); } catch {}
+      if (res.headersSent || res.writableEnded || res.destroyed) { try { res.end(); } catch {} return; }
+      if (err instanceof StructuredOutputError) {
+        // OpenAI's spec mechanism for "model would not produce the required output" is the assistant
+        // `refusal` field (200, content:null, finish_reason:"stop"), NOT an invented 422 error type —
+        // so SDK clients take their written refusal branch. (PR #153 review, finding 3.)
+        logEvent("warn", "structured_failed", { reason: err.reason });
+        const id = `chatcmpl-${randomUUID()}`;
+        const refusal = `Could not produce a response matching the requested response_format after ${STRUCTURED_MAX_ATTEMPTS} attempts (${sanitizeError(err.reason)}).`;
+        if (stream) streamRefusalAsSSE(res, id, model, refusal);
+        else refusalResponse(res, id, model, refusal);
+        return;
+      }
+      return respondUpstreamError(res, err);
+    }
+  }
+
  // Cache check (only when cache is enabled and no active conversation/session)
  if (CACHE_TTL > 0 && !conversationId) {
    // D2: skip OCP cache entirely when messages carry cache_control annotations;
@@ -2626,8 +2966,9 @@ async function handleChatCompletions(req, res) {
      req._cacheHash = null;
      logEvent("info", "cache_skipped", { reason: "cache_control_present" });
    } else {
-      // D1: include keyId in hash to isolate per-key cache pools (v2 format)
-      const hash = cacheHash(model, messages, { keyId: req._authKeyId, temperature: parsed.temperature, max_tokens: parsed.max_tokens, top_p: parsed.top_p });
+      // D1: include keyId in hash to isolate per-key cache pools (v2 format).
+      // configEpoch (#176): any boot-config change that shapes answers invalidates the cache.
+      const hash = cacheHash(model, messages, { keyId: req._authKeyId, temperature: parsed.temperature, max_tokens: parsed.max_tokens, top_p: parsed.top_p, configEpoch: CONFIG_EPOCH });
      req._cacheHash = hash; // store for later write-back
      try {
        const cached = getCachedResponse(hash, CACHE_TTL);
@@ -3272,6 +3613,8 @@ server.listen(PORT, BIND_ADDRESS, () => {
  console.log(`Auth: ${PROXY_API_KEY ? "enabled (PROXY_API_KEY set)" : "disabled (no PROXY_API_KEY)"}`);
  console.log(`Auth mode: ${AUTH_MODE}${AUTH_MODE === "shared" ? " (PROXY_API_KEY)" : AUTH_MODE === "multi" ? " (per-user keys)" : " (open)"}`);
  console.log(`Bind: ${BIND_ADDRESS}${BIND_ADDRESS === "0.0.0.0" ? " ⚠ LAN-accessible" : ""}`);
+  if (LOCAL_TOOLS_ACTIVE) console.log(`Local tools: ON (OCP_LOCAL_TOOLS=1) — model told it may use local tools; single-user/loopback only`);
+  else if (LOCAL_TOOLS) console.warn(`⚠ OCP_LOCAL_TOOLS=1 is ignored in TUI mode (the -p system-prompt wrapper is not used). The TUI tool surface is governed by OCP_TUI_FULL_TOOLS.`);
  if (NO_CONTEXT) console.log(`Context: suppressed (CLAUDE_NO_CONTEXT=true — no CLAUDE.md, no auto-memory)`);
  if (CACHE_TTL > 0) console.log(`Cache: enabled (TTL=${CACHE_TTL / 1000}s)`);
  else console.log(`Cache: disabled (set CLAUDE_CACHE_TTL to enable)`);