@cspeach/cli 1.1.19 → 1.1.20

package/dist/agent/provider-shape.js

@@ -0,0 +1,263 @@
+import { TOOL_CHANGES_BETA, isToolSearchEntry } from '../tools/tool-loading.js';
+/** Betas the proxy sends on every managed turn (messages.ts `betas: [...]`). */
+export const BASE_BETAS = ['compact-2026-01-12'];
+/** Task 6 — beta that enables `fallbacks: 'default'` (server-side fallback). */
+export const FALLBACK_BETA = 'server-side-fallback-2026-07-01';
+/**
+ * Controller ruling (Task 6): an ALLOW-list of the families probe P3 proved
+ * accept `fallbacks: 'default'`. Exact match after lowercasing and stripping a
+ * trailing -YYYYMMDD — so claude-opus-4-8, a future claude-opus-5-9, or a local
+ * alias get no fallbacks and no fallback beta. Mirrors the proxy's
+ * models/config.ts modelAcceptsFallbacks.
+ */
+export const FALLBACK_MODELS = new Set([
+    'claude-opus-5-5', 'claude-opus-5', 'claude-sonnet-4-6', 'claude-haiku-4-5',
+]);
+export function modelAcceptsFallbacks(model) {
+    return FALLBACK_MODELS.has(model.trim().toLowerCase().replace(/-\d{8}$/, ''));
+}
+/**
+ * Task 7 — beta that enables `thinking.block_binding` (preserved thinking:
+ * `prefix_mismatch_behavior: 'drop_block'` drops a thinking block whose prefix
+ * changed instead of rejecting the request).
+ */
+export const BINDING_BETA = 'thinking-binding-controls-2026-08-01';
+/**
+ * Task 7 — ALLOW-list of the families probe P4 proved accept
+ * `thinking.block_binding` with BINDING_BETA. Same matching as
+ * FALLBACK_MODELS (lowercased, trailing -YYYYMMDD stripped): claude-haiku-4-5*
+ * and claude-opus-4-8 were not probed for it, so they get neither the field
+ * nor the beta. Mirrors the proxy's models/config.ts modelAcceptsBinding.
+ */
+export const BINDING_MODELS = new Set([
+    'claude-opus-5-5', 'claude-opus-5', 'claude-sonnet-4-6',
+]);
+export function modelAcceptsBinding(model) {
+    return BINDING_MODELS.has(model.trim().toLowerCase().replace(/-\d{8}$/, ''));
+}
+/**
+ * Task 8 (ruling F5, spec D9) — ALLOW-list of the families probe P2 proved
+ * accept `max_tokens: 65536` (claude-opus-5, claude-opus-5-5). Same matching
+ * as FALLBACK_MODELS (lowercased, trailing -YYYYMMDD stripped), so a future
+ * claude-opus-5-9 keeps the 32768 default until it is probed.
+ */
+export const MAX_TOKENS_65K_MODELS = new Set([
+    'claude-opus-5-5', 'claude-opus-5',
+]);
+export const SESSION_MAX_TOKENS_DEFAULT = 32768;
+export const SESSION_MAX_TOKENS_OPUS5 = 65536;
+export function sessionMaxTokens(model) {
+    return MAX_TOKENS_65K_MODELS.has(model.trim().toLowerCase().replace(/-\d{8}$/, ''))
+        ? SESSION_MAX_TOKENS_OPUS5
+        : SESSION_MAX_TOKENS_DEFAULT;
+}
+/**
+ * Integration finding I1 (2026-09-28) — the per-model OUTPUT CEILING every
+ * request's max_tokens is clamped to, maxTokensOverride included (agent_run
+ * children default to 100000). Only the 65k allow-list above is proven;
+ * every other model (claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5,
+ * unknown ids) is capped at 32768. Dated ids are stripped. Without this an
+ * enforced sonnet/haiku child sent 100000 and the API answered 400.
+ */
+export function modelOutputCeiling(model) {
+    return sessionMaxTokens(model);
+}
+export function clampMaxTokens(model, requested) {
+    return Math.min(requested, modelOutputCeiling(model));
+}
+/**
+ * Task 16 — the beta for `role: 'system'` `tool_addition` messages (sent
+ * whenever a request declares a deferred tool or carries a system message)
+ * and the tool search predicate: one definition each, in tools/tool-loading.
+ */
+export { TOOL_CHANGES_BETA, isToolSearchEntry };
+function isDeferredEntry(t) {
+    return !!t && typeof t === 'object' && t.defer_loading === true;
+}
+/** Task 16 — a tool the request loads in full (neither deferred nor the search tool). */
+export function isLoadedToolEntry(t) {
+    return !isDeferredEntry(t) && !isToolSearchEntry(t);
+}
+function hasSystemMessage(messages) {
+    return (messages ?? []).some((m) => m?.role === 'system');
+}
+/**
+ * Betas matching the fields present in a shaped request. The beta follows the
+ * field: the model is gated where the field is set (`fallbacks` in BYOK
+ * shaping, `thinking.block_binding` in the loop), not here.
+ */
+export function requiredBetas(params) {
+    const betas = [...BASE_BETAS];
+    if (params.fallbacks)
+        betas.push(FALLBACK_BETA);
+    if (params.thinking?.block_binding)
+        betas.push(BINDING_BETA);
+    if ((params.tools ?? []).some(isDeferredEntry) || hasSystemMessage(params.messages))
+        betas.push(TOOL_CHANGES_BETA);
+    return betas;
+}
+const EPHEMERAL = { type: 'ephemeral' };
+/**
+ * Add the system prompt and (optionally) the proxy's two remaining cache
+ * breakpoints: the last tool and the last block of the last message. Never
+ * mutates the input — the loop's session messages are reused next turn.
+ * A caller-supplied `system` is replaced, as the proxy ignores body.system.
+ */
+export function withSkillPrompt(params, system, opts) {
+    const out = { ...params, system };
+    if (!opts.cacheMarkers)
+        return out;
+    // Task 16 — the marker goes on the last LOADED tool (loaded entries come
+    // first, deferred ones and the search tool after); with no deferred entries
+    // that is the last tool, as before.
+    if (Array.isArray(params.tools) && params.tools.length > 0) {
+        const tools = [...params.tools];
+        const markIdx = lastIndexWhere(tools, isLoadedToolEntry);
+        if (markIdx >= 0) {
+            tools[markIdx] = { ...tools[markIdx], cache_control: EPHEMERAL };
+            out.tools = tools;
+        }
+    }
+    // Task 16 — the marker goes on the last NON-system message: a trailing
+    // `role: 'system'` tool_addition is never marked (probe P7 proved this
+    // shape; a marker on a tool_addition block is unproven).
+    const lastIdx = lastIndexWhere(params.messages, (m) => m?.role !== 'system');
+    if (lastIdx >= 0) {
+        const messages = [...params.messages];
+        const last = { ...messages[lastIdx] };
+        if (typeof last.content === 'string') {
+            last.content = [{ type: 'text', text: last.content, cache_control: EPHEMERAL }];
+        }
+        else if (Array.isArray(last.content) && last.content.length > 0) {
+            const blocks = [...last.content];
+            blocks[blocks.length - 1] = { ...blocks[blocks.length - 1], cache_control: EPHEMERAL };
+            last.content = blocks;
+        }
+        messages[lastIdx] = last;
+        out.messages = messages;
+    }
+    return out;
+}
+function lastIndexWhere(arr, pred) {
+    for (let i = arr.length - 1; i >= 0; i--)
+        if (pred(arr[i]))
+            return i;
+    return -1;
+}
+const LEGACY_TOP_LEVEL = ['model', 'max_tokens', 'messages', 'system', 'tools', 'tool_choice', 'metadata'];
+const LEGACY_THINKING = ['type', 'display'];
+/** Task 16 — server tool blocks (tool search) the legacy wires never saw. */
+const SERVER_TOOL_BLOCKS = new Set(['server_tool_use', 'tool_search_tool_result']);
+/** A shallow copy of an object block without `cache_control`. */
+function withoutCacheControl(b) {
+    if (!b || typeof b !== 'object' || !('cache_control' in b))
+        return b;
+    const { cache_control: _drop, ...rest } = b;
+    return rest;
+}
+/** Task 16 — legacy tools: every tool loads (no defer_loading), no search entry, no markers. */
+function legacyTools(tools) {
+    return tools
+        .filter((t) => !isToolSearchEntry(t))
+        .map((t) => {
+        const copy = withoutCacheControl(t);
+        if (!isDeferredEntry(copy))
+            return copy;
+        const { defer_loading: _drop, ...rest } = copy;
+        return rest;
+    });
+}
+/**
+ * Task 16 — legacy messages: no `role: 'system'` messages, no server tool
+ * blocks (an assistant message left empty by that is dropped), no nested
+ * `cache_control` (Task 5 carry).
+ */
+function legacyMessages(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (m.role === 'system')
+            continue;
+        if (!Array.isArray(m.content)) {
+            out.push(m);
+            continue;
+        }
+        const content = m.content
+            .filter((b) => !SERVER_TOOL_BLOCKS.has(b?.type ?? ''))
+            .map(withoutCacheControl);
+        if (content.length === 0)
+            continue;
+        out.push({ ...m, content });
+    }
+    return out;
+}
+/**
+ * Whitelist copy of the fields AI-hub and local accepted before this plan.
+ * Every newer field (output_config, fallbacks, betas, thinking.block_binding,
+ * …) is dropped, and so are the Task 16 shapes (deferred tools load in full,
+ * the search tool, system messages, server tool blocks) and any nested
+ * cache_control. Never deletes from the input.
+ */
+export function toLegacyShape(params) {
+    const src = params;
+    const out = {};
+    for (const k of LEGACY_TOP_LEVEL) {
+        if (src[k] !== undefined)
+            out[k] = src[k];
+    }
+    if (Array.isArray(params.tools))
+        out.tools = legacyTools(params.tools);
+    if (Array.isArray(params.messages))
+        out.messages = legacyMessages(params.messages);
+    if (Array.isArray(params.system))
+        out.system = params.system.map(withoutCacheControl);
+    if (params.thinking !== undefined) {
+        const t = params.thinking;
+        const thinking = {};
+        for (const k of LEGACY_THINKING) {
+            if (t[k] !== undefined)
+                thinking[k] = t[k];
+        }
+        out.thinking = thinking;
+    }
+    return out;
+}
+/**
+ * Task 9 (Task 5 carry) — headers only our proxy understands. On a direct
+ * path (BYOK talks to the public API) they would leak CSPeach plumbing to a
+ * third party, so they are removed before the SDK sees them. Matching is
+ * case-insensitive: X-CSForge-* and X-CSPeach-*.
+ */
+export function withoutInternalHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers ?? {})) {
+        if (/^x-cs(forge|peach)-/i.test(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * Task 9 — the role header is new proxy plumbing; AI-hub keeps today's header
+ * set, so only X-CSPeach-Model-Role is removed there.
+ */
+export function withoutRoleHeader(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers ?? {})) {
+        if (k.toLowerCase() === 'x-cspeach-model-role')
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * The active skill travels as the X-CSForge-Skill header (coordination §1).
+ * Direct providers need it to fetch the skill body; without it the model
+ * would run with no skill prompt, so fail loudly instead.
+ */
+export function requireSkillName(options, mode) {
+    const name = options.headers?.['X-CSForge-Skill'];
+    if (!name) {
+        throw new Error(`${mode} request is missing the X-CSForge-Skill header — cannot load the skill prompt for this turn.`);
+    }
+    return name;
+}

package/dist/agent/providers/ai-hub-provider.js

@@ -2,6 +2,8 @@ import Anthropic from '@anthropic-ai/sdk';
 import keychain from '../../auth/keychain.js';
 import { createManifestSkillSource } from '../../skills/source-manifest.js';
 import { DEFAULT_MANIFEST_URL } from '../../skills/manifest-client.js';
+import { requireSkillName, toLegacyShape, withoutRoleHeader } from '../provider-shape.js';
+import { systemPromptForSkill } from '../system-prompt.js';
 const KEYCHAIN_SERVICE = 'cspeach.ai-hub';
 const KEYCHAIN_ACCOUNT = 'token';
 export function createAiHubProvider(cfg) {
@@ -16,14 +18,27 @@ export function createAiHubProvider(cfg) {
         mode: 'ai-hub',
         skillSource,
         async createStream(params, options = {}) {
+            // Task 5 (ruling F3) — AI-hub keeps today's field set only (newer
+            // fields such as output_config are stripped) and gains the preamble +
+            // skill body as `system`. No cache markers: the hub has no flag saying
+            // it accepts cache_control, so none is sent.
+            const skillName = requireSkillName(options, 'AI Hub');
             const token = await getToken();
+            // Task 18 — the `_reader` header uses the pinned reader prompt, no lookup.
+            const system = await systemPromptForSkill(skillName, skillSource, { cacheMarkers: false });
+            const request = {
+                ...toLegacyShape(params),
+                system,
+                model: modelAlias,
+            };
             const sdk = new Anthropic({
                 apiKey: token,
                 baseURL,
-                defaultHeaders: { ...options.headers },
+                // Task 9 — the proxy-only role header is not forwarded to the hub.
+                defaultHeaders: withoutRoleHeader(options.headers),
             });
             // v0.6 — pass AbortSignal so hard-interrupt tears down the stream.
-            return sdk.messages.stream({ ...params, model: modelAlias }, options.signal ? { signal: options.signal } : undefined);
+            return sdk.messages.stream(request, options.signal ? { signal: options.signal } : undefined);
         },
         async healthCheck() {
             const token = await keychain.getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);

package/dist/agent/providers/byok-provider.js

@@ -2,23 +2,53 @@ import Anthropic from '@anthropic-ai/sdk';
 import keychain from '../../auth/keychain.js';
 import { createManifestSkillSource } from '../../skills/source-manifest.js';
 import { DEFAULT_MANIFEST_URL } from '../../skills/manifest-client.js';
+import { modelAcceptsFallbacks, requiredBetas, requireSkillName, withoutInternalHeaders, withSkillPrompt } from '../provider-shape.js';
+import { systemPromptForSkill } from '../system-prompt.js';
 const KEYCHAIN_SERVICE = 'cspeach.anthropic';
 const KEYCHAIN_ACCOUNT = 'api-key';
 // Cheapest Anthropic model available at doctor-probe time.
 const HEALTH_PROBE_MODEL = 'claude-haiku-4-6-latest';
 export function createByokProvider(_cfg) {
     const skillSource = createManifestSkillSource(DEFAULT_MANIFEST_URL);
+    // Task 5 (ruling F3) — the loop's request is provider-neutral; BYOK talks to
+    // the model directly, so it adds what the proxy adds for managed: preamble +
+    // skill body as `system`, cache markers, and the betas matching the fields
+    // present. Shared by createStream and keepalive (Task 15) so a ping warms
+    // exactly the prefix the real call wrote.
+    async function shapeRequest(params, options) {
+        const skillName = requireSkillName(options, 'BYOK');
+        const key = await getKey();
+        // Task 18 — the `_reader` header uses the pinned reader prompt, no lookup.
+        const system = await systemPromptForSkill(skillName, skillSource, { cacheMarkers: true });
+        // Task 6 — opt into server-side fallback, only for the families probe
+        // P3 proved (allow-list); requiredBetas adds its beta.
+        const prompted = withSkillPrompt(params, system, { cacheMarkers: true });
+        const shaped = modelAcceptsFallbacks(params.model)
+            ? { ...prompted, fallbacks: 'default' }
+            : prompted;
+        const betas = requiredBetas(shaped);
+        // Task 9 — CSPeach-internal headers never reach the public API.
+        const sdk = new Anthropic({ apiKey: key, defaultHeaders: withoutInternalHeaders(options.headers) });
+        return { sdk, body: { ...shaped, betas } };
+    }
     return {
         name: 'anthropic-byok',
         mode: 'byok',
         skillSource,
         async createStream(params, options = {}) {
-            const key = await getKey();
-            const sdk = new Anthropic({ apiKey: key, defaultHeaders: { ...options.headers } });
+            const { sdk, body } = await shapeRequest(params, options);
             // v0.6 — pass AbortSignal so the agent loop's per-turn AbortController
             // can tear down the stream on Esc / SIGINT-during-turn. The Anthropic
             // SDK's `signal` option propagates to the underlying fetch.
-            return sdk.messages.stream(params, options.signal ? { signal: options.signal } : undefined);
+            return sdk.beta.messages.stream(body, options.signal ? { signal: options.signal } : undefined);
+        },
+        // Task 15 — keepalive ping, direct to the API: the SAME shaped body as
+        // createStream (system, cache markers, betas, fallbacks) with
+        // max_tokens 0 and no stream (probe P5: accepted, reads the cache). No
+        // SDK retries — a failed ping stops that wait, it must never storm.
+        async keepalive(params, options = {}) {
+            const { sdk, body } = await shapeRequest(params, options);
+            await sdk.beta.messages.create({ ...body, max_tokens: 0 }, { maxRetries: 0, timeout: 20_000 });
         },
         async healthCheck() {
             const key = await keychain.getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);

package/dist/agent/providers/local-provider.js

@@ -5,6 +5,8 @@ import { sha256 } from '@noble/hashes/sha256';
 import { bytesToHex } from '@noble/hashes/utils';
 import { createBundledSkillSource } from '../../skills/source-bundled.js';
 import { BUNDLED_SKILLS } from '../../skills/bundled-skills.js';
+import { requireSkillName } from '../provider-shape.js';
+import { buildSystemPrompt } from '../system-prompt.js';
 export function createLocalProvider(cfg) {
     if (!cfg.llm.local_base_url) {
         throw new Error('local mode requires llm.local_base_url — run: cspeach config set llm.local_base_url http://localhost:11434/v1');
@@ -20,9 +22,14 @@ export function createLocalProvider(cfg) {
             if (params.tools && params.tools.length > 0) {
                 throw new Error('Tool calling not supported in local mode (Plan A). Switch to managed/byok/ai-hub, or wait for the local-mode tool-calling follow-up PR.');
             }
+            // Task 5 (ruling F3) — preamble + bundled skill body as the system
+            // message (no cache markers). anthropicParamsToOpenAI copies only
+            // max_tokens / messages / system, so newer fields never reach the endpoint.
+            const skillName = requireSkillName(options, 'Local');
+            const skill = await skillSource.getSkillBody(skillName);
             const OpenAI = await loadOpenAI();
             const sdk = new OpenAI({ apiKey: 'local-ignored', baseURL });
-            const openAiParams = anthropicParamsToOpenAI(params, model);
+            const openAiParams = anthropicParamsToOpenAI({ ...params, system: buildSystemPrompt(skill.body, { cacheMarkers: false }) }, model);
             // stream: true widens via object spread; the literal-true overload cannot be
             // selected by structural inference, so cast to the streaming return shape.
             // v0.6 — pass AbortSignal through OpenAI SDK request options.

package/dist/agent/repair-partial.js

@@ -1,3 +1,30 @@
+/**
+ * Repair partial assistant content blocks before persisting them to a session.
+ *
+ * When a provider stream is interrupted mid-flight (HTTP socket dropped,
+ * AbortController fired, network blip), the agent loop's accumulated
+ * `currentAssistantContent` may include `tool_use` blocks whose `input` JSON
+ * never finished streaming — typically the SDK has buffered the bytes into
+ * `partial_json` but `JSON.parse` was never called, so `input` is undefined.
+ *
+ * Persisting an assistant message that contains an incomplete tool_use block
+ * causes the next API call to reject the message with:
+ *   400 each `tool_use` block must contain `input` (or similar)
+ *
+ * Drop incomplete tool_use blocks. The model will re-emit them on the next
+ * round (the prior tool round's results are already on session.messages,
+ * giving the model the same context). Text blocks are kept even if
+ * truncated — partial prose is still useful for the user to read, and a
+ * short paragraph fragment is a valid assistant message. Thinking blocks are
+ * kept only when complete and signed (see isUnsignedThinking).
+ */
+/**
+ * Block types whose input streams as `input_json_delta` (and so may carry a
+ * residual `partial_json`). Task 16 (F6): the tool search tool's
+ * `server_tool_use` streams its input the same way as a client `tool_use`
+ * (probe P6: 5 and 8 input_json_delta events).
+ */
+export const STREAMED_INPUT_BLOCKS = new Set(['tool_use', 'server_tool_use']);
 /**
  * 2026-09-27 — a thinking block is only valid to send back to the API with its
  * complete signature. The signature arrives last (`signature_delta`, right
@@ -17,7 +44,7 @@ export function repairPartialBlocks(blocks, opts = {}) {
     return blocks.filter((b) => {
         if (b == null || typeof b !== 'object')
             return false;
-        if (b.type === 'tool_use') {
+        if (STREAMED_INPUT_BLOCKS.has(b.type)) {
             // Complete only when input was successfully parsed (object, not undefined).
             if (b.input === undefined)
                 return false;
@@ -44,6 +71,32 @@ export function repairPartialBlocks(blocks, opts = {}) {
         return true;
     });
 }
+/**
+ * Task 6 (2026-09-27) — server-side fallback. When the first model hands off
+ * to a fallback model mid-output, the message carries a `fallback` block. The
+ * API rule for echoing it back: omit the `thinking`, `redacted_thinking` and
+ * `tool_use` blocks that precede the LAST `fallback` block (they belong to
+ * the model that did not finish). Everything else is kept in order.
+ *
+ * No `fallback` block ⇒ the same array reference is returned (no copy).
+ */
+// Task 16 review — also the tool search tool's server blocks (conservative,
+// same rule as tool_use: a server tool call of the model that did not finish).
+const PRE_FALLBACK_DROP = new Set([
+    'thinking', 'redacted_thinking', 'tool_use', 'server_tool_use', 'tool_search_tool_result',
+]);
+export function stripPreFallbackBlocks(blocks) {
+    let last = -1;
+    for (let i = blocks.length - 1; i >= 0; i--) {
+        if (blocks[i]?.type === 'fallback') {
+            last = i;
+            break;
+        }
+    }
+    if (last < 0)
+        return blocks;
+    return blocks.filter((b, i) => i >= last || !PRE_FALLBACK_DROP.has(b?.type));
+}
 /**
  * Heal a session already poisoned by an unsigned thinking block (saved by a
  * CLI before 2026-09-27): drop every thinking / redacted_thinking block that
@@ -96,7 +149,7 @@ export function healSessionMessagesInPlace(messages) {
         if (!Array.isArray(msg.content))
             continue;
         for (const block of msg.content) {
-            if (block?.type === 'tool_use' && typeof block.partial_json === 'string') {
+            if (STREAMED_INPUT_BLOCKS.has(block?.type) && typeof block.partial_json === 'string') {
                 if (block.input === undefined) {
                     try {
                         block.input = JSON.parse(block.partial_json);
@@ -199,10 +252,18 @@ export function healOrphanToolUses(messages) {
     }
     return added;
 }
-/** Review M2 — true when every block is thinking / redacted_thinking (and there is one). */
+/**
+ * Review M2 — true when the message holds at least one thinking /
+ * redacted_thinking block and nothing else readable. Integration M1 — a
+ * `fallback` block (Task 6) is neutral: [fallback, thinking] is still
+ * thinking-only; [fallback] alone is not.
+ */
 export function isThinkingOnly(blocks) {
-    return Array.isArray(blocks) && blocks.length > 0
-        && blocks.every((b) => b?.type === 'thinking' || b?.type === 'redacted_thinking');
+    if (!Array.isArray(blocks))
+        return false;
+    const rest = blocks.filter((b) => b?.type !== 'fallback');
+    return rest.length > 0
+        && rest.every((b) => b?.type === 'thinking' || b?.type === 'redacted_thinking');
 }
 /**
  * Review M2 — a turn cut right after a signed thinking block (before any

package/dist/agent/summarise-via-provider.js

@@ -29,7 +29,12 @@ export async function summariseViaProvider(provider, system, user, opts) {
         system,
         messages: [{ role: 'user', content: user }],
     }, {
-        headers: opts.headers,
+        // Task 9 — every caller is /compact, so the role defaults to 'compact'
+        // (the proxy never enforces the session model on it). A caller-set
+        // X-CSPeach-Model-Role wins. No headers ⇒ unchanged (undefined).
+        headers: opts.headers
+            ? { 'X-CSPeach-Model-Role': 'compact', ...opts.headers }
+            : opts.headers,
         signal: opts.signal,
     });
     let accumulated = '';

package/dist/agent/system-prompt.js

@@ -0,0 +1,38 @@
+/**
+ * Client-side system prompt for providers that talk to a model directly
+ * (BYOK, AI-hub, local). Task 5 (2026-09-27, ruling F3).
+ *
+ * Mirrors the proxy's managed system prompt (cspeach-proxy/src/routes/
+ * messages.ts): two text blocks — the CSPeach principles preamble, then the
+ * active skill's SKILL.md body — each carrying an ephemeral cache marker when
+ * the provider supports them.
+ */
+import { FORGE_PRINCIPLES_PREAMBLE } from '../skills/preamble.js';
+import { READER_SKILL, READER_SYSTEM_PROMPT } from '../tools/subagent/reader-prompt.js';
+export function buildSystemPrompt(skillBody, opts) {
+    const marker = opts.cacheMarkers ? { cache_control: { type: 'ephemeral' } } : {};
+    return [
+        { type: 'text', text: FORGE_PRINCIPLES_PREAMBLE, ...marker },
+        { type: 'text', text: skillBody, ...marker },
+    ];
+}
+/**
+ * Task 18 (ruling F8) — a reader subagent's system prompt: the pinned
+ * READER_SYSTEM_PROMPT alone (no preamble, no skill body), as the proxy sends
+ * it for the `_reader` skill header.
+ */
+export function buildReaderSystemPrompt(opts) {
+    const marker = opts.cacheMarkers ? { cache_control: { type: 'ephemeral' } } : {};
+    return [{ type: 'text', text: READER_SYSTEM_PROMPT, ...marker }];
+}
+/**
+ * The system prompt for the skill named in the X-CSForge-Skill header. The
+ * internal `_reader` skill has no SKILL.md, so it never reaches the skill
+ * source (a lookup would fail).
+ */
+export async function systemPromptForSkill(skillName, skillSource, opts) {
+    if (skillName === READER_SKILL)
+        return buildReaderSystemPrompt(opts);
+    const skill = await skillSource.getSkillBody(skillName);
+    return buildSystemPrompt(skill.body, opts);
+}

package/dist/agent/tool-dispatch.js

@@ -4,11 +4,19 @@ import { NOT_CONNECTED_MESSAGE } from '../sap/offline-adt-client.js';
 import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
 import { shouldGateRule8, recordWriteOp, renderPlanSummary, getWriteOpsThisTurn, } from '../repl/rule8-detector.js';
 import { isCredentialHandoverApproved, markCredentialHandoverApproved, } from '../repl/credential-handover-gate.js';
+import { READER_TOOLS } from '../tools/subagent/reader-prompt.js';
+const READER_TOOL_SET = new Set(READER_TOOLS);
 export async function dispatchTool(name, args, ctx) {
     const tool = getTool(name);
     if (!tool) {
         return { content: JSON.stringify({ error: `unknown_tool: ${name}` }), is_error: true };
     }
+    // Task 18 (ruling F22) — a reader subagent is read-only and depth 1: only
+    // its fixed tool list runs, whatever the model calls (no writes, no
+    // questions or approvals, no nested read_agent / agent_run, no shell).
+    if (ctx.readerMode && !READER_TOOL_SET.has(name)) {
+        return { content: `error: read-only reader — ${name} is not allowed here`, is_error: true };
+    }
     // Standalone safety net (2026-09-16). SAP-dependent tools are already
     // filtered out of the list the model sees (agent/loop.ts), but a model can
     // still call a tool it remembers from an earlier turn or from training. Fail

package/dist/agent/tool-loading-pin.js

@@ -0,0 +1,100 @@
+/**
+ * Final review I2 (controller ruling, 2026-09-28) — the tool-loading mode is
+ * pinned on the SESSION, not resolved per process.
+ *
+ * The first request pins `session.tool_loading` to the mode that request
+ * uses (the process-resolved mode, gated by the model allow-list). A resumed
+ * session keeps its pinned mode: a 'static' session never turns deferred
+ * (its `tools[]` stays byte-stable), and a 'deferred' session stays deferred
+ * while the call allows it.
+ *
+ * A 'deferred' session must become 'static' when a call cannot take the
+ * deferred shapes: the admin kill switch, a failed startup config fetch
+ * (static until restart), `CSPEACH_TOOL_LOADING=static`, or a call on a model
+ * outside the allow-list (a plan-tier sonnet turn, an adopted opus-4-8). Its
+ * history then still holds deferred artefacts — `server_tool_use` /
+ * `tool_search_tool_result` blocks and `role: 'system'` tool_addition
+ * messages — which a request with no search tool and no deferred entries
+ * cannot carry. They are stripped ONCE, before that request, and the session
+ * is re-pinned 'static' so the strip never repeats. This is a deliberate
+ * one-time prefix rewrite, like /compact: every assistant message from the
+ * first edit on loses its thinking blocks (the API binds thinking to the exact
+ * prefix that produced it), the same stripThinking /compact and the cold
+ * prune apply.
+ */
+import { stripThinking } from '../commands/compact.js';
+import { modelAcceptsDeferredTools } from '../tools/tool-loading.js';
+const SERVER_TOOL_BLOCK_TYPES = new Set(['server_tool_use', 'tool_search_tool_result']);
+/** True when the history holds a shape only a deferred-mode request may carry. */
+export function hasDeferredArtefacts(messages) {
+    for (const m of messages ?? []) {
+        if (m?.role === 'system')
+            return true;
+        if (Array.isArray(m?.content) && m.content.some((b) => SERVER_TOOL_BLOCK_TYPES.has(b?.type)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Remove every deferred artefact from `messages` in place: `role: 'system'`
+ * messages, and `server_tool_use` / `tool_search_tool_result` blocks (a
+ * message left with no content is dropped). Every assistant message from the
+ * first edit on loses its thinking blocks (a thinking-only message keeps a
+ * placeholder text). Returns the number of messages and blocks removed; 0 ⇒
+ * untouched. Idempotent.
+ */
+export function stripDeferredArtefacts(messages) {
+    let removed = 0;
+    let firstEdit = -1;
+    const out = [];
+    for (const m of messages) {
+        if (m?.role === 'system') {
+            removed++;
+            if (firstEdit < 0)
+                firstEdit = out.length;
+            continue;
+        }
+        if (Array.isArray(m?.content)) {
+            const kept = m.content.filter((b) => !SERVER_TOOL_BLOCK_TYPES.has(b?.type));
+            if (kept.length !== m.content.length) {
+                removed += m.content.length - kept.length;
+                if (firstEdit < 0)
+                    firstEdit = out.length;
+                if (kept.length > 0)
+                    out.push({ ...m, content: kept });
+                continue;
+            }
+        }
+        out.push(m);
+    }
+    if (removed === 0)
+        return 0;
+    for (let i = firstEdit; i < out.length; i++)
+        out[i] = stripThinking(out[i]);
+    messages.splice(0, messages.length, ...out);
+    return removed;
+}
+/**
+ * Decide the tool-loading mode for one call and keep the session consistent
+ * with it. `resolved` is the process-resolved mode (resolveToolLoading);
+ * `model` is the model this call sends. Mutates `session.tool_loading` and,
+ * on a deferred → static change, `session.messages` (see the file comment).
+ */
+export function settleSessionToolLoading(session, i) {
+    const allowed = i.resolved === 'deferred' && modelAcceptsDeferredTools(i.model) ? 'deferred' : 'static';
+    // A session saved before the pin existed: its history tells how it ran.
+    const pinned = session.tool_loading
+        ?? (hasDeferredArtefacts(session.messages) ? 'deferred' : undefined);
+    if (pinned === undefined) {
+        session.tool_loading = allowed;
+        return { mode: allowed, stripped: 0 };
+    }
+    if (pinned === 'deferred' && allowed === 'deferred') {
+        session.tool_loading = 'deferred';
+        return { mode: 'deferred', stripped: 0 };
+    }
+    // Static for this call (and from now on): strip once, pin 'static'.
+    session.tool_loading = 'static';
+    const stripped = pinned === 'deferred' ? stripDeferredArtefacts(session.messages) : 0;
+    return { mode: 'static', stripped };
+}