feat(server): OCP_LOCAL_TOOLS — positive local-tools system-prompt wrapper (single-user, default off) (#182)

Motivation (the OpenClaw case). OCP's `-p` path prepends OCP_SYSTEM_PROMPT_WRAPPER,
which tells the model it has NO local filesystem/shell/env access. Correct for a
shared/multi-tenant gateway. But an OpenClaw agent pointed at its own local OCP runs
the model SERVER-SIDE via `claude -p`, which already passes --allowedTools and has the
CLI's built-in tools — and on a loopback instance the OCP host IS the operator's
machine, so those are local tools. The wrapper gags them: the agent replies "I don't
have filesystem access" for tools it actually holds. OCP_LOCAL_TOOLS=1 swaps in a
positive wrapper for that case. (It does NOT enable client-side tool_calls for
OpenClaw/Cline — that remains unsupported by design; OCP is a text-prompt bridge.)

Safety: changes ONLY the system-prompt text, never the tool surface. Tools are governed
solely by --allowedTools/--disallowedTools; AUTH_MODE=multi still --disallowedTools the
whole FS/web/agent surface regardless of the wrapper. Fail-closed boot gate mirroring
OCP_TUI_FULL_TOOLS (ADR 0007): refuse to start when =1 is combined with
CLAUDE_AUTH_MODE=multi, a non-loopback bind, or PROXY_ANONYMOUS_KEY.

Scope/alignment: no new endpoint/header/field/wire operation. The wrapper text is
OCP-owned prompt composition (same class as OCP_SYSTEM_PROMPT_WRAPPER and
CLAUDE_SYSTEM_PROMPT), passed via the already-cited `claude --system-prompt` flag
(unchanged). ALIGNMENT.md Rule 2: nothing invented on the wire.

- lib/prompt.mjs: pure selectPromptWrapper() + localToolsSafetyError() (unit-tested).
- server.mjs: single hoisted flag LOCAL_TOOLS_ACTIVE = OCP_LOCAL_TOOLS && !TUI_MODE
  (the wrapper is only applied on the -p path; TUI composes its own prompt, so the flag
  is inert under TUI — announced with a warning rather than a misleading "ON"). Wrapper
  selection, boot gate, and the CONFIG_EPOCH fold all key off it, so toggling the flag +
  restarting invalidates the standard response cache (#177). Default path byte-for-byte
  unchanged.
- README env-var row + tool-model note; CHANGELOG Unreleased entry.

Tests (+14): unit-test both ternary branches and every gate condition; plus an
INTEGRATION harness that boots real server.mjs with a fake `claude` capturing the
--system-prompt — asserting the POSITIVE wrapper reaches a request under =1 and the
EXACT negative wrapper when unset, the boot gate refuses all three unsafe configs, the
safe config boots, TUI announces inert, and toggling the flag re-spawns (cache
invalidated). Mutation-verified: reverting the wiring / neutering the gate / reverting
the epoch fold each turns a test RED. 443 passed, 0 failed.

Noticed but scoped out (Iron Rule 11): the structured-output cache path
(handleChatCompletions, the response_format branch) does not fold CONFIG_EPOCH at all —
a pre-existing gap from #177/#153, independent of this flag. Happy to fix in a follow-up.

Co-authored-by: vvlasy-openclaw <vvlasy@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lib/prompt.mjs

@@ -52,3 +52,38 @@ export function derivePromptCharBudget(models, { charsPerToken = 3, floor = 1500
 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;
+}