@cspeach/cli 1.1.19 → 1.1.21

package/dist/tools/subagent/read_agent.js

@@ -0,0 +1,178 @@
+/**
+ * read_agent — Task 18 (model control, 2026-09-27, spec D18).
+ *
+ * Heavy reading (many sources, a where-used walk, ATC-finding triage, a
+ * package inventory) runs in a lean child conversation and only a short
+ * report returns to the parent's history. Unlike agent_run (flag-gated, a
+ * full skill prefix per child), a reader carries:
+ *   - a ~300-token system prompt owned by the proxy (skill header `_reader`,
+ *     ruling F8; BYOK / AI-hub use the pinned copy in reader-prompt.ts),
+ *   - a fixed small tool list (READER_TOOLS: read-only, no tool search),
+ *   - the session model at effort `low`, role `reader` (never enforced, F7),
+ *   - a capped report: overflow is saved to a file and the tail is cut.
+ *
+ * Read-only and depth 1 are enforced by `ctx.readerMode` at dispatch (F22).
+ * The loop runs consecutive read_agent calls concurrently, each with its own
+ * ctx clone whose `adt` is serialized through one lock (F21). The child's
+ * spend is added to the parent's per-turn `readerSpend` (F24); the child also
+ * writes its own reader-*-cost.jsonl.
+ */
+import { EventEmitter } from 'node:events';
+import { listTools, registerTool, toolsForContext } from '../index.js';
+import { runTurn } from '../../agent/loop.js';
+import { collectTurnAssistantText } from '../../agent/turn-assistant-text.js';
+import { newSession } from '../../session/schema.js';
+import { computeSessionCost } from '../../cost/session-cost.js';
+import { sessionIdOf, spillIfLarge } from '../result-spill.js';
+import { INTERRUPTED_LINE, READER_SKILL, READER_SYSTEM_PROMPT, READER_TOOLS, hasReaderReadTools } from './reader-prompt.js';
+export { INTERRUPTED_LINE, READER_SKILL, READER_SYSTEM_PROMPT, READER_TOOLS, hasReaderReadTools };
+export const BRIEF_MAX_CHARS = 4_000;
+export const DEFAULT_REPORT_MAX_CHARS = 3_000;
+export const HARD_REPORT_MAX_CHARS = 6_000;
+/**
+ * Final review tools-I4 — told to every reader. The proxy owns the reader's
+ * system prompt (pinned byte-equal), so the CLI says this in the child's
+ * user message.
+ */
+export const PARENT_OUTPUT_LINE = 'A saved-output path in this brief (a scan or ATC result the main session already ran) can be read with ' +
+    'tool_output_read. Read it instead of repeating the scan: never re-run ATC or a scan whose output you were given.';
+/** The result when the account's proxy refuses the `_reader` skill. */
+export const NOT_ENABLED_LINE = 'readers are not enabled for this account — read the sources directly';
+function reportCap(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 1)
+        return DEFAULT_REPORT_MAX_CHARS;
+    return Math.min(Math.floor(raw), HARD_REPORT_MAX_CHARS);
+}
+function isNotEntitled(err) {
+    const e = err;
+    if (e?.error?.error === 'skill_not_in_entitlements')
+        return true;
+    return typeof e?.message === 'string' && e.message.includes('skill_not_in_entitlements');
+}
+export async function readAgentHandler(args, ctx) {
+    const brief = args?.brief;
+    if (typeof brief !== 'string' || brief.trim().length === 0) {
+        return { content: "error: 'brief' is required: say what to read and what to report.", is_error: true };
+    }
+    if (brief.length > BRIEF_MAX_CHARS) {
+        return { content: `error: 'brief' is ${brief.length} chars; keep it under ${BRIEF_MAX_CHARS}.`, is_error: true };
+    }
+    // Depth 1 (dispatch refuses this too; belt and braces for direct calls).
+    if (ctx.readerMode) {
+        return { content: 'error: a reader cannot start another reader.', is_error: true };
+    }
+    // Fix M4 — an agent_run child does its own reading.
+    if (ctx.subagent) {
+        return { content: 'error: a subagent cannot start a reader — read the sources directly.', is_error: true };
+    }
+    // Fix M5 — nothing a reader could read here (standalone, file tools off).
+    if (!hasReaderReadTools(new Set(toolsForContext(listTools(), ctx).map((t) => t.name)))) {
+        return { content: 'error: no read tools are available to a reader here — read the sources directly.', is_error: true };
+    }
+    if (ctx.signal?.aborted)
+        return { content: INTERRUPTED_LINE, is_error: true };
+    if (!ctx.provider) {
+        return { content: 'error: read_agent requires ctx.provider — not wired into this ToolContext.', is_error: true };
+    }
+    const cap = reportCap(args.report_max_chars);
+    // The session model, never a cheaper one (owner decision 11); effort low.
+    const model = ctx.session.model;
+    const childSession = newSession(`reader-${Date.now()}-${Math.floor(Math.random() * 1e9).toString(16)}`, ctx.session.sap_system ?? null, READER_SKILL, model);
+    // Only what a read needs. No previewHook (no writes), no chunkEmitter /
+    // todoEmitter (the child never paints the parent UI), no pendingDispatch /
+    // currentTransport (the child never changes parent REPL state).
+    const parentSessionId = sessionIdOf(ctx);
+    const childCtx = {
+        adt: ctx.adt,
+        sapAlias: ctx.sapAlias,
+        session: childSession,
+        cwd: ctx.cwd,
+        provider: ctx.provider,
+        skillSource: ctx.skillSource,
+        readerMode: true,
+        // Final review tools-I4 — the reader may open the parent's saved outputs.
+        ...(parentSessionId !== undefined ? { spillParentSessionId: parentSessionId } : {}),
+    };
+    const userMessage = `${brief}\n\n${PARENT_OUTPUT_LINE}\n\nReport limit: ${cap} characters.`;
+    let failure = null;
+    try {
+        await runTurn({
+            provider: ctx.provider,
+            userMessage,
+            skill: READER_SKILL,
+            ctx: childCtx,
+            // Null sink: the child's text lands in childSession.messages only.
+            chunkEmitter: new EventEmitter(),
+            modelRole: 'reader',
+            toolsOverride: READER_TOOLS,
+            effortOverride: 'low',
+            modelOverride: model,
+            suppressSaveHook: true,
+            // Fix I1 — Esc / Ctrl+C on the parent turn stops the reader's stream.
+            signal: ctx.signal,
+        });
+    }
+    catch (err) {
+        failure = err;
+    }
+    finally {
+        // Spend counts whether or not the reader finished.
+        if (ctx.readerSpend) {
+            ctx.readerSpend.cost += computeSessionCost(childSession);
+            ctx.readerSpend.calls += 1;
+        }
+    }
+    if (failure !== null) {
+        if (ctx.signal?.aborted)
+            return { content: INTERRUPTED_LINE, is_error: true };
+        if (isNotEntitled(failure))
+            return { content: NOT_ENABLED_LINE, is_error: true };
+        const msg = failure instanceof Error ? failure.message : String(failure);
+        return { content: `error: the reader failed — ${msg.slice(0, 300)}`, is_error: true };
+    }
+    const text = collectTurnAssistantText(childSession.messages, 0).trim();
+    if (text.length === 0) {
+        return {
+            content: 'error: the reader returned no report — read the sources directly.',
+            is_error: true,
+        };
+    }
+    if (text.length <= cap)
+        return { content: text };
+    // Over the cap: the full report goes to the PARENT's spill area under the
+    // parent's tool_use id, where tool_output_read can open it.
+    const head = text.slice(0, cap);
+    const sessionId = sessionIdOf(ctx);
+    const spilled = sessionId !== undefined
+        ? spillIfLarge({ text, sessionId, toolUseId: ctx.toolUseId, kind: 'report', threshold: cap })
+        : null;
+    const where = spilled?.spilled ? ` — full report saved to ${spilled.path}` : '';
+    return { content: `${head}\n[report cut at ${cap} chars${where}]` };
+}
+registerTool({
+    name: 'read_agent',
+    description: 'Hand heavy reading to a lean read-only reader; only its short report comes back. Use it for more ' +
+        'than two source reads, a where-used scan, ATC-finding triage or a package inventory when the turn ' +
+        'will keep working afterwards. The reader has read-only SAP and file tools; it cannot write, ask the ' +
+        'user or start another reader. Give a precise brief: what to read and what to report. To hand over ' +
+        'a result you already have (ATC findings), put its saved-output path in the brief: the reader reads it ' +
+        'and never re-runs the scan. Send ' +
+        'independent readers in one response; they run at the same time.',
+    isMutating: false,
+    category: 'subagent',
+    input_schema: {
+        type: 'object',
+        properties: {
+            brief: {
+                type: 'string',
+                description: 'What to read (objects, includes, packages) and what to report. Max 4000 characters.',
+            },
+            report_max_chars: {
+                type: 'number',
+                description: 'Report length limit. Default 3000, max 6000. Longer reports are cut and saved to a file.',
+            },
+        },
+        required: ['brief'],
+    },
+    handler: (args, ctx) => readAgentHandler(args, ctx),
+});

package/dist/tools/subagent/reader-prompt.js

@@ -0,0 +1,48 @@
+/**
+ * Task 18 (model control, 2026-09-27, spec D18, ruling F8) — the reader
+ * subagent's system prompt and tool list.
+ *
+ * The PROXY owns READER_SYSTEM_PROMPT (cspeach-proxy/src/skills/
+ * reader-prompt.ts): for the skill header `_reader` it sends that constant
+ * and ignores the client's `system`. This is the CLI's pinned copy, used only
+ * where the CLI talks to a model directly (BYOK, AI-hub, local).
+ * src/tools/__tests__/reader-prompt-pin.test.ts asserts the two template
+ * literals stay byte-equal — edit both files together.
+ *
+ * No imports on purpose: tool-dispatch.ts reads READER_TOOLS, and importing
+ * read_agent.ts there would close a cycle through agent/loop.ts.
+ */
+/** The skill header a reader's model calls carry. */
+export const READER_SKILL = '_reader';
+export const READER_SYSTEM_PROMPT = `You are a read-only investigator inside CSPeach. Read exactly what the brief asks for with the tools you have, then answer the brief. Report facts with object names, includes and line numbers. Say what you could not find. No recommendations unless the brief asks. Stay under the report limit.`;
+/**
+ * The reader's fixed, small, static tool list (no deferred entries, no tool
+ * search): the ten read-only tools of spec D18 plus tool_output_read (Task
+ * 17), so a reader can open a result that was saved to a file. Every entry is
+ * `isMutating: false`. Flag-gated entries (file_read, grep, glob) reach the
+ * reader only when the session has them on, and standalone hides the SAP ones.
+ * tool-dispatch.ts refuses every other tool while `ctx.readerMode` is set.
+ */
+export const READER_TOOLS = Object.freeze([
+    'sap_get_source',
+    'sap_object_structure',
+    'sap_search_object',
+    'sap_sql_query',
+    'sap_usage_references',
+    'sap_class_includes',
+    'sap_atc_run',
+    'file_read',
+    'grep',
+    'glob',
+    'tool_output_read',
+]);
+/** Task 18 fix I1 — the result of a reader stopped by Esc / Ctrl+C (or never started). */
+export const INTERRUPTED_LINE = 'interrupted: the reader was stopped before it finished';
+/**
+ * Task 18 fix M5 — true when a reader would have at least one real read tool
+ * among `visibleNames` (tool_output_read alone reads nothing new: standalone
+ * with the file tools off). The loop hides read_agent otherwise.
+ */
+export function hasReaderReadTools(visibleNames) {
+    return READER_TOOLS.some((n) => n !== 'tool_output_read' && visibleNames.has(n));
+}

package/dist/tools/todo.js

@@ -124,7 +124,9 @@ registerTool({
         'in_progress at a time. The user sees this list — keep items short and outcome-shaped. ' +
         'Update at EVERY step transition: when you finish a step, immediately call todo_set ' +
         'marking it completed and the next step in_progress. Never batch several finished steps ' +
-        'into one later call — the user watches the ▶ indicator live.',
+        'into one later call — the user watches the ▶ indicator live. ' +
+        // Task 16 (cost profile lever 7): a lone todo_set round re-reads the whole context.
+        'Call todo_set in the same response as your next action, never as the only tool call in a response.',
     isMutating: false,
     category: 'session',
     input_schema: {

package/dist/tools/tool-loading.js

@@ -0,0 +1,255 @@
+import { toAnthropicTools } from './index.js';
+/** The server-side tool search tool (probe P6: this exact name). */
+export const TOOL_SEARCH_TOOL = Object.freeze({
+    type: 'tool_search_tool_regex_20251119',
+    name: 'tool_search_tool_regex',
+});
+/** Beta that allows `role: 'system'` tool_addition messages (and rides with deferred tools). */
+export const TOOL_CHANGES_BETA = 'mid-conversation-tool-changes-2026-07-01';
+/**
+ * Spec D11 — always loaded. Names missing from the list a build is given
+ * (flag-gated `agent_run` / file tools when their flag is off; every SAP tool
+ * in standalone) are skipped, never an error (ruling F25). `read_agent`
+ * (Task 18) is core because the preamble's heavy-reading rule names it.
+ */
+export const CORE_TOOLS = Object.freeze([
+    'ask_question',
+    'todo_set',
+    'request_approval',
+    'dispatch_skill',
+    'agent_run',
+    'read_agent',
+    'file_read',
+    'tool_output_read',
+    'file_write',
+    'shell_exec',
+    'sap_get_source',
+    'sap_search_object',
+    'sap_object_structure',
+    'sap_sql_query',
+    'sap_syntax_check',
+    'sap_set_source',
+    'sap_update_method',
+    'sap_activate',
+    'sap_inactive_objects',
+    'sap_create_object',
+]);
+const FIORI_FAMILY = [
+    'fiori_apply', 'fiori_deploy_config', 'fiori_draft_smoke', 'fiori_fe_extend',
+    'fiori_list', 'fiori_metadata_audit', 'fiori_preview', 'fiori_render_smoke',
+    'fiori_sample_get', 'fiori_sample_search', 'fiori_scaffold', 'fiori_scaffold_fe',
+];
+const TRANSPORT_FAMILY = [
+    'sap_transport_create', 'sap_transport_for_object', 'sap_transport_list', 'sap_transport_release',
+];
+/**
+ * Per-skill starter tools: the non-core tools a skill's body names as its
+ * working set (counted from `.claude/skills/<skill>/SKILL.md`). A tool left
+ * out is still reachable through tool search — a starter only saves the
+ * search round. Skills not listed start with the core set alone.
+ */
+export const SKILL_STARTERS = Object.freeze({
+    'abap-fiori-build': FIORI_FAMILY,
+    'abap-transport': TRANSPORT_FAMILY,
+    'abap-transport-analysis': [...TRANSPORT_FAMILY, 'sap_atc_run', 'sap_usage_references'],
+    'abap-cap': ['fiori_scaffold_fe', 'fiori_render_smoke', 'fiori_draft_smoke'],
+    'abap-atc-fix': ['sap_atc_run'],
+    'abap-cca': ['sap_atc_run', 'sap_usage_references', 'sap_api_state'],
+    'abap-clean-core': ['sap_api_state', 'sap_atc_run', 'sap_usage_references'],
+    'abap-data-model': ['sap_create_domain', 'sap_create_data_element'],
+    'abap-document': ['sap_usage_references'],
+    'abap-handover': ['sap_usage_references'],
+    'abap-impact': ['sap_usage_references', 'sap_atc_run'],
+    'abap-performance': ['sap_usage_references', 'sap_atc_run'],
+    'abap-migrate': ['sap_usage_references'],
+    'abap-dump': ['sap_short_dump', 'sap_snapshot_take'],
+    'abap-incident': ['sap_short_dump', 'sap_snapshot_take', 'sap_atc_run', 'sap_run_unit_test', 'sap_api_state', 'sap_diff'],
+    'abap-eml': ['sap_run_unit_test'],
+    'abap-test': ['sap_run_unit_test', 'sap_set_class_include'],
+    'abap-extend-model': ['extend_model_insert', 'sap_snapshot_take', 'sap_service_binding_publish', 'sap_set_class_include'],
+    'abap-rap': ['sap_set_class_include', 'sap_service_binding_publish', 'sap_class_includes'],
+    'abap-modernize': ['sap_api_state', 'sap_snapshot_take', 'sap_service_binding_publish', 'sap_atc_run', 'sap_transport_create'],
+    'abap-segw': ['sap_snapshot_take', 'sap_odata_test'],
+    'abap-upgrade-fix': ['sap_snapshot_take', 'glob'],
+    'abap-upgrade-scan': ['sap_atc_run'],
+    'abap-upgrade-verify': ['sap_atc_run'],
+});
+/** The starter tools for a skill; unknown skill (or none) ⇒ []. */
+export function startersForSkill(skill) {
+    if (!skill)
+        return [];
+    const s = SKILL_STARTERS[skill];
+    return s ? [...s] : [];
+}
+/**
+ * Final review C1 (controller ruling, 2026-09-28) — ALLOW-list of the model
+ * families the deferred shapes (defer_loading entries, the tool search tool,
+ * `role: 'system'` tool_addition messages) were probe-proven on (P6, D1, D3:
+ * claude-opus-5 and claude-opus-5-5). Same matching as the other allow-lists
+ * in agent/provider-shape.ts (lowercased, trailing -YYYYMMDD stripped). Every
+ * other model — claude-opus-4-8 (the session default until the global flip),
+ * the claude-sonnet-4-6 plan/audit tier, haiku — gets the static list. The
+ * loop decides by the model actually sent on each call.
+ */
+export const DEFERRED_TOOL_MODELS = new Set([
+    'claude-opus-5-5', 'claude-opus-5',
+]);
+export function modelAcceptsDeferredTools(model) {
+    if (typeof model !== 'string')
+        return false;
+    return DEFERRED_TOOL_MODELS.has(model.trim().toLowerCase().replace(/-\d{8}$/, ''));
+}
+/**
+ * Mode precedence (ruling F13): AI-hub and local are always 'static' (their
+ * wire has no deferred loading). Otherwise env `CSPEACH_TOOL_LOADING`
+ * (`deferred` | `static`) wins; then managed uses the served value (default
+ * 'static': only a proxy that serves tool_loading takes the new shapes);
+ * BYOK uses the served value when it fetched one, else 'static'.
+ */
+export function resolveToolLoading(i) {
+    if (i.providerMode === 'ai-hub' || i.providerMode === 'local')
+        return 'static';
+    const raw = i.env.CSPEACH_TOOL_LOADING?.trim().toLowerCase();
+    if (raw === 'deferred' || raw === 'static')
+        return raw;
+    // Task 21 fix round (controller ruling): an old proxy serves no tool_loading
+    // and adds none of the deferred-tool betas, so 'deferred' only when served.
+    if (i.providerMode === 'managed')
+        return i.served ?? 'static';
+    if (i.providerMode === 'byok')
+        return i.served ?? 'static';
+    // Unknown/fake provider modes keep today's full list.
+    return 'static';
+}
+/**
+ * Build the `tools[]` array. 'static' ⇒ exactly today's list
+ * (toAnthropicTools). 'deferred' ⇒ loaded entries (core ∪ starters, in
+ * registry order, byte-identical to today's entries), then every other tool
+ * with `defer_loading: true` (registry order), then the tool search tool —
+ * the search tool only when at least one entry is deferred.
+ */
+export function buildToolList(tools, opts) {
+    if (opts.mode === 'static')
+        return toAnthropicTools(tools);
+    const loadedNames = new Set([...CORE_TOOLS, ...startersForSkill(opts.skill)]);
+    const loaded = tools.filter((t) => loadedNames.has(t.name));
+    const deferred = tools.filter((t) => !loadedNames.has(t.name));
+    // Final review I1 — nothing deferred ⇒ nothing to search: no search tool
+    // (plan audit's `toolFilter: () => false` means "no tools at all" ⇒ []).
+    if (deferred.length === 0)
+        return toAnthropicTools(loaded);
+    return [
+        ...toAnthropicTools(loaded),
+        ...toAnthropicTools(deferred).map((t) => ({ ...t, defer_loading: true })),
+        { ...TOOL_SEARCH_TOOL },
+    ];
+}
+/** Names of the entries a built list declares with `defer_loading: true`. */
+export function deferredNames(toolList) {
+    const out = new Set();
+    for (const t of toolList) {
+        if (t && t.defer_loading === true && typeof t.name === 'string')
+            out.add(t.name);
+    }
+    return out;
+}
+/** True for the tool search entry of a built list (the one predicate; provider-shape re-exports it). */
+export function isToolSearchEntry(t) {
+    return !!t && typeof t === 'object' && t.type === TOOL_SEARCH_TOOL.type;
+}
+/**
+ * Probe D2 (2026-09-27): the API rejects a `role: 'system'` message followed
+ * by a user message — "role 'system' must precede an 'assistant' message or
+ * end the array" (400). A tool_addition pushed after a tool-result message
+ * can be followed by a user message when the next round adds one first (mid-
+ * turn steering, the watchdog nudge) or when the turn ended before the model
+ * answered (refusal, interruption) and the next turn's prompt is pushed, and
+ * a later skill switch can then append a second tool_addition.
+ *
+ * Only the TAIL after the last assistant message is ever touched (the whole
+ * array when there is none): it holds only user and system messages, none of
+ * which an assistant message has followed yet, so no thinking block's prefix
+ * changes (at most the uncached tail is re-written). The tail is stably
+ * partitioned: user messages first (in order), then the system messages'
+ * blocks (in order) merged into ONE system message that ends the array — the
+ * shape probe D3 proved, its next round included. Merging avoids a
+ * [system, system] run, whose acceptance was never probed; one system message
+ * with several tool_addition blocks is the shape the CLI already sends for a
+ * skill's starters. Anything before the last assistant message is left
+ * exactly as it is. Mutates `messages`; returns the number of system messages
+ * moved or merged. Idempotent: a second pass is a no-op.
+ */
+export function placeSystemMessagesInPlace(messages) {
+    if (!messages)
+        return 0;
+    let tailStart = messages.length;
+    while (tailStart > 0 && messages[tailStart - 1]?.role !== 'assistant')
+        tailStart--;
+    const tail = messages.slice(tailStart);
+    const users = tail.filter((m) => m?.role !== 'system');
+    const systems = tail.filter((m) => m?.role === 'system');
+    if (systems.length === 0)
+        return 0;
+    // Already in shape: users, then exactly one system message last.
+    if (systems.length === 1 && tail[tail.length - 1] === systems[0])
+        return 0;
+    const merged = {
+        role: 'system',
+        content: systems.flatMap((m) => (Array.isArray(m.content) ? m.content : [])),
+    };
+    messages.splice(tailStart, tail.length, ...users, merged);
+    return systems.length;
+}
+/**
+ * A `role: 'system'` message surfacing deferred tools by reference. Names not
+ * in `deferredSet` (loaded already, or unknown in this build) are dropped;
+ * nothing left ⇒ null.
+ */
+export function buildToolAdditionMessage(names, deferredSet) {
+    const keep = [...new Set(names)].filter((n) => deferredSet.has(n));
+    if (keep.length === 0)
+        return null;
+    return {
+        role: 'system',
+        content: keep.map((name) => ({ type: 'tool_addition', tool: { type: 'tool_reference', name } })),
+    };
+}
+/**
+ * Integration finding N1 (c) — the tool_addition for a skill switch: the
+ * skill's starters that the CURRENT mode's list (`toolList`, the list the
+ * next request carries) declares deferred, minus those the conversation has
+ * already surfaced. A session pinned 'static' never gets one, whatever list
+ * the caller holds (a static request cannot carry a `role: 'system'`
+ * tool_addition). Nothing to add ⇒ null.
+ */
+export function buildSkillToolAddition(i) {
+    if (i.toolLoading === 'static')
+        return null;
+    const surfaced = surfacedToolNames(i.messages);
+    return buildToolAdditionMessage(startersForSkill(i.skill).filter((n) => !surfaced.has(n)), deferredNames(i.toolList));
+}
+/**
+ * Tool names already surfaced in a conversation: every `tool_addition`
+ * reference (`tool.name`) and every search-result reference (`tool_name`).
+ * Used so a skill switch never re-adds a tool.
+ */
+export function surfacedToolNames(messages) {
+    const out = new Set();
+    for (const m of messages ?? []) {
+        if (!Array.isArray(m?.content))
+            continue;
+        for (const b of m.content) {
+            if (b?.type === 'tool_addition' && typeof b.tool?.name === 'string')
+                out.add(b.tool.name);
+            if (b?.type === 'tool_search_tool_result') {
+                const refs = b.content?.tool_references;
+                if (Array.isArray(refs)) {
+                    for (const r of refs)
+                        if (typeof r?.tool_name === 'string')
+                            out.add(r.tool_name);
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/tools/tool-output-read.js

@@ -0,0 +1,117 @@
+/**
+ * tool_output_read — Task 17 ruling (2026-09-27).
+ *
+ * Large tool results are saved to ~/.cspeach/streams/<sessionId>/tool-<id>.txt
+ * (result-spill.ts) and the history keeps a preview naming this tool. It is
+ * always registered (not flag-gated — file_read is off in a plain SAP session),
+ * read-only, in CORE_TOOLS, and reads ONLY the current session's spill files
+ * (a reader child: also its parent session's — final review tools-I4): the
+ * path must be a tool-*.txt directly inside one of those spill dirs, and
+ * it is re-checked after realpath (a symlink cannot point it elsewhere).
+ * Anything else — including a ctx with no session id — is an error result.
+ * Its own result is never spilled; instead it has a char budget.
+ */
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from './index.js';
+import { spillDirFor, sessionIdOf, SPILL_FILE_RE, NUMBERED_SPILL_RE, SPILL_MAX_AGE_DAYS, withRealpath, } from './result-spill.js';
+const MAX_LINES = 2000;
+/** Total characters one call returns (fix round 1, minor 2). */
+export const TOOL_OUTPUT_READ_MAX_CHARS = 40_000;
+/** One returned line never carries more than this. */
+export const TOOL_OUTPUT_READ_LINE_MAX_CHARS = 2_000;
+const REFUSED = 'not a saved tool output of this session';
+const err = (msg) => ({ content: `error: ${msg}`, is_error: true });
+/** Case-insensitive file systems (win32, darwin default) compare paths case-insensitively. */
+const norm = (p) => (process.platform === 'win32' || process.platform === 'darwin' ? p.toLowerCase() : p);
+/** The spill file itself must sit directly in one of the session-dir spellings. */
+function directlyIn(dirs, file) {
+    const parent = norm(path.dirname(file));
+    return dirs.some((d) => norm(d) === parent);
+}
+function clip(line) {
+    return line.length <= TOOL_OUTPUT_READ_LINE_MAX_CHARS
+        ? line
+        : `${line.slice(0, TOOL_OUTPUT_READ_LINE_MAX_CHARS)}… [+${line.length - TOOL_OUTPUT_READ_LINE_MAX_CHARS} chars]`;
+}
+export async function toolOutputReadHandler(args, ctx) {
+    const sessionId = sessionIdOf(ctx);
+    if (sessionId === undefined)
+        return err(REFUSED);
+    const p = typeof args.path === 'string' ? args.path : '';
+    if (p.length === 0 || p.includes('\0') || !path.isAbsolute(p)) {
+        return err('path must be the absolute spill-file path shown in the tool result');
+    }
+    const offset = args.offset === undefined ? 0 : Number(args.offset);
+    const limitArg = args.limit === undefined ? MAX_LINES : Number(args.limit);
+    if (!Number.isInteger(offset) || offset < 0)
+        return err(`offset must be a non-negative integer (got ${String(args.offset)})`);
+    if (!Number.isInteger(limitArg) || limitArg < 1)
+        return err(`limit must be a positive integer (got ${String(args.limit)})`);
+    const limit = Math.min(limitArg, MAX_LINES);
+    // Final review tools-I4 — a reader child may also read its parent's saved
+    // outputs: that one dir only, and only on a reader ctx.
+    const parentId = ctx.readerMode && typeof ctx.spillParentSessionId === 'string' && ctx.spillParentSessionId.length > 0
+        ? ctx.spillParentSessionId
+        : undefined;
+    const dirs = [
+        ...withRealpath(spillDirFor(sessionId)),
+        ...(parentId !== undefined ? withRealpath(spillDirFor(parentId)) : []),
+    ];
+    const abs = path.resolve(p);
+    if (!SPILL_FILE_RE.test(path.basename(abs)) || !directlyIn(dirs, abs))
+        return err(REFUSED);
+    let real;
+    try {
+        real = await fsp.realpath(abs);
+    }
+    catch (e) {
+        return err(e.code === 'ENOENT'
+            ? `saved output not found (saved outputs are kept ${SPILL_MAX_AGE_DAYS} days)`
+            : 'cannot read saved output');
+    }
+    if (!SPILL_FILE_RE.test(path.basename(real)) || !directlyIn(dirs, real))
+        return err(REFUSED);
+    let raw;
+    try {
+        raw = await fsp.readFile(real, 'utf-8');
+    }
+    catch {
+        return err('cannot read saved output');
+    }
+    // A `.n.txt` spill (file_read) already carries the file's line numbers.
+    const numberedAlready = NUMBERED_SPILL_RE.test(real);
+    const all = raw.replace(/\n$/, '').split('\n');
+    const end = Math.min(all.length, offset + limit);
+    const out = [];
+    let used = 0;
+    let next = offset;
+    for (let i = offset; i < end; i++) {
+        const line = clip(numberedAlready ? all[i] : `${i + 1}\t${all[i]}`);
+        if (out.length > 0 && used + line.length + 1 > TOOL_OUTPUT_READ_MAX_CHARS)
+            break;
+        out.push(line);
+        used += line.length + 1;
+        next = i + 1;
+    }
+    const rest = all.length - next;
+    return { content: out.join('\n') + (rest > 0 ? `\n... (${rest} more lines — next offset=${next})` : '') };
+}
+registerTool({
+    name: 'tool_output_read',
+    description: 'Read a slice of a large tool result that was saved to a file (the result names the path). '
+        + 'Returns numbered lines. offset is 0-based; limit defaults to and caps at 2000 lines (40 000 chars). '
+        + 'Only this session\'s saved outputs can be read.',
+    isMutating: false,
+    category: 'filesystem',
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'The saved-output path from the tool result.' },
+            offset: { type: 'number', description: 'Optional 0-based line offset.' },
+            limit: { type: 'number', description: 'Optional max lines (cap 2000).' },
+        },
+        required: ['path'],
+    },
+    handler: toolOutputReadHandler,
+});

package/dist/tools/transport.js

@@ -16,7 +16,7 @@ import { auditLog } from '@cspeach/sap-client';
 import { ERR } from '../errors/codes.js';
 import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
 import { isSafetyConfirmEnabled } from '../repl/safety-mode-state.js';
-import { setCurrentTransport } from '../repl/current-transport.js';
+import { setCurrentTransport, noteConfirmedTransport } from '../repl/current-transport.js';
 import { enrichTransportList } from './transport-fit.js';
 // ── Session ledger: transports CREATED by sap_transport_create this session ──
 //
@@ -286,6 +286,11 @@ registerTool({
                 // Ownership-aware guidance (I1) — mirrors the create guard wording.
                 const me = (ctx.adt.username ?? '').toUpperCase();
                 const foreignOwner = r.owner && r.owner.toUpperCase() !== me ? r.owner : undefined;
+                // UI fix round (1.1.20): a lock the connected user may write under is
+                // a CONFIRMED transport for this work — the footer shows it (display
+                // only; the write pointer is untouched). A foreign lock is not ours.
+                if (!foreignOwner)
+                    noteConfirmedTransport(r.transport);
                 note = foreignOwner
                     ? `${args.object_name} is locked in ${r.transport} (owned by ${foreignOwner}) — SAP `
                         + 'only accepts changes under that request; ask the owner to add you as a task '

package/dist/ui/footer.js

@@ -8,7 +8,7 @@ import { pasteClipboardImage } from './clipboard-image.js';
 import Fuse from 'fuse.js';
 // Task 8 (ux-wave1) — persistence lives in the shared writer.
 import { appendHistoryEntry, readHistoryEntries, flattenHistoryEntry } from '../repl/history.js';
-import { uiWidth, truncateToWidth } from '../renderer/ui-width.js';
+import { frameWidth, truncateToWidth } from '../renderer/ui-width.js';
 import { shouldUseUnicodeBoxChars } from '../renderer/tty.js';
 import { getGlyphs } from '../renderer/glyphs.js';
 import { roleProps, selectedProps } from './role-props.js';
@@ -31,12 +31,12 @@ const PROMPT = `${PROMPT_GLYPH} `;
 /** Rounded border (2) + paddingX 1 on each side (2). */
 const BOX_CHROME = 4;
 /**
- * Width of the input box (and of the footer line under it). uiWidth() caps it
- * at 100; the −1 keeps the box off the exact-terminal-width deferred-wrap edge
- * on Windows Terminal (the margin the old single-row budget kept, Bug 1).
+ * Width of the input box (and of the footer line under it) — the FRAME width
+ * (frameWidth(): full terminal less the 1-column deferred-wrap margin, Bug 1).
+ * No 100-col cap: the frame spans the terminal; text inside wraps on its own.
  */
 export function inputBoxWidth(columns) {
-    return Math.max(12, Math.min(uiWidth(columns), columns - 1));
+    return frameWidth(columns);
 }
 export function Footer({ onSubmit, onSlashTrigger, onHistoryTrigger, onValueChange, prefill, disabled, onNotice, onBufferChange, maxLines, onInputLinesChange, waitingForCard, }) {
     const [value, setValue] = useState('');