@cspeach/cli 0.9.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # CSPeach
 
-AI-assisted ABAP development CLI. 34 skills, direct SAP access, safety
+AI-assisted ABAP development CLI. 35 skills, direct SAP access, safety
 gates the model cannot bypass.
 
 ## Install

package/dist/agent/intent-system-prompt.js

@@ -19,7 +19,7 @@ You help senior SAP consultants and ABAP developers plan, build, modernize, migr
 - Live access to the user's SAP system via the sap_* tool family (~30 tools — get_source, set_source, atc_run, transport_create, sql_query, snapshot_take, etc.).
 - Filesystem + shell + web access to the project the user is working in (file_read, file_edit, file_write, glob, grep, shell_exec, web_fetch, web_search).
 - Subagent dispatch (agent_run) for focused sub-tasks; background_run + monitor_emit for non-blocking processes; schedule_draft_create for persisting schedule envelopes (no runner yet — see tool description).
-- A library of 34 SAP-development playbooks you can read on demand via playbook_get. These cover RAP scaffolding, S/4HANA upgrade remediation, CCA estate analysis, modernization, code review, performance triage, and more. When you need expertise on a specific workflow, fetch the relevant playbook BEFORE acting.
+- A library of 35 SAP-development playbooks you can read on demand via playbook_get. These cover RAP scaffolding, S/4HANA upgrade remediation, CCA estate analysis, modernization, code review, performance triage, and more. When you need expertise on a specific workflow, fetch the relevant playbook BEFORE acting.
 - The project context for this session (CDS views, tables, packages, conventions) — appended below if available.
 
 When the user states an intent, your job is:

package/dist/agent/loop.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
 import { basename } from 'node:path';
 import { dispatchTool } from './tool-dispatch.js';
-import { listTools, toAnthropicTools } from '../tools/index.js';
+import { listTools, getTool, toAnthropicTools } from '../tools/index.js';
 import { saveSession } from '../session/store.js';
+import { recordCompletedToolCall } from '../session/pending.js';
 import { loadConfig } from '../config/loader.js';
 import { retryWithBackoff } from './retry.js';
 import { renderChunk, initialBufferState, render } from '../renderer/pipeline.js';
@@ -19,9 +20,9 @@ import { buildRetryCapPausePayload, buildSkippedSiblingResults } from './retry-c
 import { appendCostLine, buildEntry as buildCostEntry } from '../cost/cost-log.js';
 import { lastAssistantIsAwaitingAnswer } from '../session/awaiting-answer.js';
 import { enrichUserMessage } from '../router/intent-extractor.js';
-import { resetRule8State } from '../repl/rule8-detector.js';
-import { runSaveCommand, runPromoteCommand } from '../projects/index.js';
-import { parseFromFlag } from '../skills/promotion-dispatch.js';
+import { resetRule8State, shouldGateRule8 } from '../repl/rule8-detector.js';
+import { runSaveCommand, runPromoteCommand, detectArtifactSkill, offerAnswerBlockers } from '../projects/index.js';
+import { parseFromFlag, coerceDocFromFlagToAttachment } from '../skills/promotion-dispatch.js';
 import { input } from '@inquirer/prompts';
 import { withInquirer } from '../repl/inquirer-guard.js';
 import { expandTextFileAttachments } from '../projects/workspace.js';
@@ -61,7 +62,7 @@ const SAVE_HOOK_SKILLS = new Set([
     // 2026-05-08: upgrade pipeline manifest envelopes. Each emits a
     // <!-- csforge:upgrade-manifest --> block that the matching
     // extract-upgrade.* parser turns into the manifest envelope. The
-    // heavy detail (per-finding data) stays in `.abapforge/upgrades/`,
+    // heavy detail (per-finding data) stays in `.cspeach/upgrades/`,
     // referenced by detail_path inside the envelope.
     'abap-upgrade-scan',
     'abap-upgrade-fix',
@@ -69,7 +70,7 @@ const SAVE_HOOK_SKILLS = new Set([
     'abap-upgrade-merge',
     // 2026-05-09: CCA pipeline manifest envelopes. /abap-cca emits a
     // <!-- csforge:cca-manifest --> block wrapping the heavy project.json
-    // detail at .abapforge/cca/projects/<slug>/. /abap-cca-merge produces
+    // detail at .cspeach/cca/projects/<slug>/. /abap-cca-merge produces
     // a consolidated cca-assessment from N parallel consultant slices.
     'abap-cca',
     'abap-cca-merge',
@@ -119,9 +120,21 @@ export function hasProjectContextBlock(messages) {
  *
  * Single shape `(q) => Promise<string>` so it slots straight into the
  * existing `prompt:` callback in runSaveCommand + runPromoteCommand.
+ * Exported for A1 (2026-06-10): repl.tsx reuses it as the consent prompt
+ * for harness-owned plan auto-run (offerNextPhaseAutoRun).
  */
-async function inkAwarePrompt(q) {
-    const { shouldUseInk } = await import('../renderer/tty.js');
+export async function inkAwarePrompt(q) {
+    const { shouldUseInk, isHeadless } = await import('../renderer/tty.js');
+    // B5 (2026-06-11) — headless runs must NEVER block on stdin (defect D1
+    // family). Any prompt that reaches the generic helper in headless mode
+    // takes the conservative default: empty answer (callers treat '' as
+    // decline / skip). Prompts that need a different headless default (e.g.
+    // the artifact-save hook, which defaults YES) install their own
+    // headless-aware prompt BEFORE reaching this helper — see maybeOfferSave.
+    if (isHeadless()) {
+        console.error(chalk.dim(`headless: skipped prompt '${q.trim()}' → '' (default)`));
+        return '';
+    }
     if (shouldUseInk()) {
         const { askQuestionEmitter } = await import('../ui/ask-question-emitter.js');
         const result = await askQuestionEmitter.request({
@@ -134,25 +147,117 @@ async function inkAwarePrompt(q) {
     }
     return withInquirer(() => input({ message: q }));
 }
+/**
+ * Choices picker for an answer-blocker that carries `options`. Renders the
+ * native Ink AskQuestionModal (the same CC-style picker the ask_question tool
+ * uses) with the candidate answers plus "Write my own" and "Skip" escapes.
+ *
+ * - headless  → skip (never blocks on stdin)
+ * - classic (non-Ink) → 'write' so the caller falls back to the free-text box
+ * - Ink → choice/multi modal; Esc or empty selection → skip
+ *
+ * The two sentinels are filtered out of any real picked answer; for multi-select
+ * the modal returns comma-joined values, so Write/Skip win over any co-selected
+ * options.
+ */
+const CHOOSE_WRITE = '__cspeach_write__';
+const CHOOSE_SKIP = '__cspeach_skip__';
+export async function inkAwareChoose(a) {
+    const { shouldUseInk, isHeadless } = await import('../renderer/tty.js');
+    if (isHeadless())
+        return { kind: 'skip' };
+    if (!shouldUseInk())
+        return { kind: 'write' }; // classic REPL → free-text fallback
+    const choices = [
+        ...a.options.map((o) => ({ value: o, label: o })),
+        { value: CHOOSE_WRITE, label: '✏️  Write my own…' },
+        { value: CHOOSE_SKIP, label: '↷  Skip (leave for the viewer)' },
+    ];
+    const { askQuestionEmitter } = await import('../ui/ask-question-emitter.js');
+    const res = await askQuestionEmitter.request({
+        id: 'answer-blocker',
+        question: `Blocker ${a.index + 1}/${a.total}: ${a.question}`,
+        context: a.multiSelect ? 'Space to toggle one or more · Enter to submit' : undefined,
+        kind: a.multiSelect ? 'multi' : 'choice',
+        choices,
+    });
+    if (res.cancelled || res.answer == null)
+        return { kind: 'skip' };
+    const values = res.answer.split(',');
+    if (values.includes(CHOOSE_WRITE))
+        return { kind: 'write' };
+    if (values.includes(CHOOSE_SKIP))
+        return { kind: 'skip' };
+    const real = values.filter((v) => v !== CHOOSE_WRITE && v !== CHOOSE_SKIP);
+    if (real.length === 0)
+        return { kind: 'skip' };
+    return { kind: 'picked', answer: real.join(', ') };
+}
 export async function maybeOfferSave(p) {
-    if (!SAVE_HOOK_SKILLS.has(p.skill))
-        return;
     if (p.assistantText.trim().length === 0)
         return;
+    // C1 (2026-06-11, defect D22) — the hook fires on artifact EVIDENCE, not
+    // only on the routed-skill label. The seed-session plan save was lost
+    // because the turn was misrouted (label 'abap-rap', not in the set) while
+    // the output carried a complete csforge:plan-manifest block. The label
+    // stays the primary trigger — it is authoritative for prose-extracted
+    // artefacts with no inline marker (spec-gap / design / estimate) and keeps
+    // merge-skill provenance exact (abap-cca-merge saves as abap-cca-merge).
+    // When the label would NOT fire, a recognizable manifest block in the
+    // output resolves the registry skill instead (detectArtifactSkill), so a
+    // misroute can no longer silently lose the artifact.
+    let saveSkill = p.skill;
+    if (!SAVE_HOOK_SKILLS.has(p.skill)) {
+        const detected = detectArtifactSkill(p.assistantText);
+        if (!detected)
+            return;
+        saveSkill = detected;
+        p.emit(chalk.dim(`[save] ${detected} artifact manifest detected in this turn's output (turn was labelled '${p.skill}') — offering save.`));
+    }
+    // B5 (2026-06-11) — defect D2: in headless runs the artifact IS the point
+    // of the run, so the "Save as project file? [y/N]" prompt defaults YES
+    // instead of blocking on stdin that will never answer. The auto-answer is
+    // logged so the transcript stays honest about who said yes.
+    //
+    // CONTRACT: this headless prompt blanket-answers 'y' to ANY question it
+    // is asked, so runSaveCommand must ask at most ONE question (the save
+    // confirm). See the matching note at the prompt site in
+    // src/projects/save-command.ts before adding further prompts there.
+    const { isHeadless } = await import('../renderer/tty.js');
+    const prompt = isHeadless()
+        ? async (q) => {
+            p.emit(chalk.dim(`headless: auto-answered '${q.trim()}' → 'y' (artifact save defaults YES)`));
+            return 'y';
+        }
+        : inkAwarePrompt;
     try {
-        await runSaveCommand({
+        const savedPath = await runSaveCommand({
             skillOutput: p.assistantText,
-            skillName: p.skill,
+            skillName: saveSkill,
             skillVersion: '1.0',
             skillInput: p.userMessage,
             tokensUsed: p.tokensUsed,
             model: p.model,
             author: getAuthorIdentity(),
             cwd: process.cwd(),
-            prompt: inkAwarePrompt,
+            prompt,
             log: (...lines) => lines.forEach((l) => p.emit(l)),
             promotedFrom: p.promotedFrom ?? null,
         });
+        // After a spec-gap file is saved, let a developer answer the open BLOCKER
+        // questions inline (recorded as `answered` items in the SAME file) — the
+        // business questions stay open for a consultant to answer in the viewer.
+        // Uses inkAwarePrompt directly (NOT the save hook's blanket-'y' headless
+        // prompt): in headless it returns '' → declined, so nothing is written.
+        if (savedPath && saveSkill === 'abap-spec-gap') {
+            await offerAnswerBlockers({
+                path: savedPath,
+                identity: getAuthorIdentity(),
+                prompt: inkAwarePrompt,
+                choose: inkAwareChoose,
+                log: (...lines) => lines.forEach((l) => p.emit(l)),
+            });
+        }
     }
     catch (err) {
         p.emit(chalk.yellow(`\n[save] skipped: ${err?.message ?? err}`));
@@ -182,7 +287,17 @@ export async function runTurn(params) {
     let userMessageForLLM = params.userMessage;
     let userMessageForSave = params.userMessage;
     {
-        const { fromPath, rest } = parseFromFlag(params.userMessage);
+        // Forgiveness: `--from @<document>` (a .docx/.pdf/.txt/.md, not a saved
+        // .cspeach.json) means "attach this file", not "chain a result". Rewrite it
+        // to a plain @<file> attachment and let Phase D ingest it — never error out
+        // and cancel the turn on this very natural slip.
+        const docAttach = coerceDocFromFlagToAttachment(params.userMessage);
+        if (docAttach) {
+            emit(chalk.dim(`[--from] ${docAttach.filename} is a document, not a saved result — attaching it as input instead.`));
+            userMessageForLLM = docAttach.rewritten;
+            userMessageForSave = docAttach.rewritten;
+        }
+        const { fromPath, rest } = parseFromFlag(docAttach ? '' : params.userMessage);
         if (fromPath) {
             const result = await runPromoteCommand({
                 sourcePath: fromPath,
@@ -331,6 +446,10 @@ export async function runTurn(params) {
     // already handed to onPlanManifest, so we fire once per DISTINCT manifest
     // (a continue-in-session run emits one per phase) and not once per round.
     let lastFiredManifest = null;
+    // Bounded auto-continue across max_tokens truncations within one turn, so a
+    // long phase (e.g. /abap-plan c2.behavior) that overruns the output cap
+    // mid-response finishes instead of dying with "unexpected stop reason".
+    let maxTokenContinuations = 0;
     // (emit was hoisted to the top of the function in v0.5 so the Phase J
     //  promote dispatch could share it. Original location was here.)
     while (true) {
@@ -400,7 +519,9 @@ export async function runTurn(params) {
                 // makes the 400 categorically impossible. Idempotent and O(messages).
                 healSessionMessagesInPlace(session.messages);
                 const streamParams = {
-                    model: cfg.default_model,
+                    // A4 — per-turn override (plan model tiering) wins over the
+                    // configured default; absent on every non-plan turn.
+                    model: params.modelOverride ?? cfg.default_model,
                     // v0.3.1 — was 8192. Bumped because code-gen skills (abap-generate
                     // etc.) kept running out of budget mid-turn: adaptive thinking +
                     // multiple tool-result prompts + TL;DR mandate + summary prose
@@ -460,6 +581,7 @@ export async function runTurn(params) {
         let currentAssistantContent = [];
         let sawEndTurn = false;
         let sawToolUse = false;
+        let sawMaxTokens = false;
         // M10 — ensure session.usage is present (shipped session schema may omit it
         // for older saved sessions; we default to zero on first turn).
         if (!session.usage) {
@@ -583,6 +705,8 @@ export async function runTurn(params) {
                         sawEndTurn = true;
                     if (stop_reason === 'tool_use')
                         sawToolUse = true;
+                    if (stop_reason === 'max_tokens' || stop_reason === 'length')
+                        sawMaxTokens = true;
                     // H2 — `deltaUsage.output_tokens` is the cumulative running total for
                     // THIS message, NOT a per-event delta. Compute the increment vs the
                     // last-seen cumulative and add only that. Guard against `null` /
@@ -675,7 +799,10 @@ export async function runTurn(params) {
             const turnDurationMs = Date.now() - turnStartedAt;
             const entry = buildCostEntry({
                 turn: turnNumber,
-                model: session.model,
+                // A4 — when a per-turn override ran the stream on a different model
+                // (plan model tiering), the cost line must record the ACTUAL model
+                // or the Sonnet-priced turn would be billed at session-model rates.
+                model: params.modelOverride ?? session.model,
                 tokens: turnTokens,
                 duration_ms: turnDurationMs,
             });
@@ -742,7 +869,10 @@ export async function runTurn(params) {
                     assistantText,
                     userMessage: userMessageForSave,
                     tokensUsed: Math.max(0, (session.usage?.output_tokens ?? 0) - turnStartOutputTokens),
-                    model: cfg.default_model ?? session.model ?? 'unknown',
+                    // A4 — record the actual turn model if an override ran the stream
+                    // (unreachable today: plan-resume turns suppress this hook, and
+                    // they are the only modelOverride caller — kept honest anyway).
+                    model: params.modelOverride ?? cfg.default_model ?? session.model ?? 'unknown',
                     emit,
                     promotedFrom: promotedFromForSave,
                 });
@@ -774,7 +904,29 @@ export async function runTurn(params) {
             return;
         }
         if (!sawToolUse) {
-            // Unexpected stop reason — bail to avoid infinite loop.
+            // The response was cut off at the output-token cap (stop_reason
+            // 'max_tokens'/'length') mid-generation — NOT a real end of turn. The
+            // truncated assistant message is already persisted (line ~733), so
+            // continue the turn and let the model finish (and, for /abap-plan, still
+            // emit its manifest). Bounded so a pathologically long response can't
+            // loop forever.
+            const MAX_TOKEN_CONTINUATIONS = 4;
+            if (sawMaxTokens && maxTokenContinuations < MAX_TOKEN_CONTINUATIONS) {
+                maxTokenContinuations += 1;
+                emit(chalk.yellow(`\n[output limit reached — auto-continuing (${maxTokenContinuations}/${MAX_TOKEN_CONTINUATIONS})]`));
+                session.messages.push({
+                    role: 'user',
+                    content: 'Your previous response was cut off at the output-token limit. Continue exactly where you left off — do NOT repeat what you already wrote. '
+                        + 'If you were mid-way through a tool call, or (for /abap-plan) had not yet emitted the closing csforge:plan-manifest block, complete it now. '
+                        + 'Keep narration brief to stay within the limit.',
+                });
+                continue;
+            }
+            if (sawMaxTokens) {
+                emit(chalk.yellow(`\n[output limit hit ${maxTokenContinuations}× this turn — stopping. Type "continue" to resume.]`));
+                return;
+            }
+            // Truly unexpected stop reason — bail to avoid an infinite loop.
             emit(chalk.yellow('\n[unexpected stop reason — ending turn]'));
             return;
         }
@@ -809,7 +961,27 @@ export async function runTurn(params) {
                 // every terminal, Ink included.
                 // Interactive tools wait on the USER, not the system — ticking
                 // "ask_question running… (30s)" while they think is noise.
-                const isInteractiveTool = block.name === 'ask_question' || block.name === 'request_approval';
+                // CRITICAL race fix (2026-06-13) — a mutating tool that will trip the
+                // Rule 8 batch gate (2nd+ write of the turn) ALSO blocks on the user:
+                // presentSafetyConfirmation opens an Ink modal from inside dispatchTool
+                // BEFORE the op runs. file_write / shell_exec are otherwise classified
+                // non-interactive, so without this the loop would start the per-second
+                // heartbeat + keep the turn-status row ticking UNDER the modal — the
+                // observed live bug (doubled card, lost Enter, history-replay leak,
+                // ~10-min wedge with the tool spinner ticking under the modal). Detect
+                // the gate the SAME way tool-dispatch does (tool.isMutating &&
+                // shouldGateRule8) and treat it as user-blocking: pause the status row,
+                // skip the heartbeat. The gate's own clearActiveSpinner +
+                // turnStatusEmitter.pause (safety-confirm.ts) is the inner belt; this
+                // is the outer one — together no live render source contends with the
+                // modal for the Ink frame or raw-mode stdin.
+                const willTripBatchGate = (() => {
+                    const t = getTool(block.name);
+                    return !!t?.isMutating && shouldGateRule8();
+                })();
+                const isInteractiveTool = block.name === 'ask_question' ||
+                    block.name === 'request_approval' ||
+                    willTripBatchGate;
                 // Interactive tools block on the USER. PAUSE the turn-status row (don't
                 // just relabel it): a live 250ms tick repaints the dynamic frame and
                 // overdraws the inquirer approval picker / churns the Ink ask_question
@@ -828,6 +1000,11 @@ export async function runTurn(params) {
                     });
                 // Phase 2b: dispatch (may take 100ms–several seconds for write tools).
                 const dispatchStart = Date.now();
+                // D19 (2026-06-11) — expose the LLM tool_use id to the handler so the
+                // write-tool WAL (appendPending/finalizeToolCall) is keyed by the SAME
+                // id the loop records below. Dispatch is sequential, so a single slot
+                // on the shared ctx is safe.
+                params.ctx.toolUseId = block.id;
                 // Bug 8 — short-circuit for 2nd+ write-class tool in the same round.
                 const guardDecision = checkAndMark(block.name, writeGuard);
                 let result;
@@ -837,6 +1014,9 @@ export async function runTurn(params) {
                         : { content: guardDecision.errorContent, is_error: true };
                 }
                 finally {
+                    // D19: clear the slot so a future non-loop invocation on this ctx
+                    // can't inherit a stale block id.
+                    params.ctx.toolUseId = undefined;
                     // Stop on the error path too — the interval is unref'd but would
                     // otherwise keep printing "<tool> running…" into the NEXT prompt
                     // after a dispatch throw.
@@ -864,16 +1044,25 @@ export async function runTurn(params) {
                     isError: result.is_error ?? false,
                     resultSummary,
                     chunkEmitter: params.chunkEmitter,
+                    // D29 (2026-06-12): self-identifying result row. Heartbeat lines,
+                    // sap-client warns, and notice lines legitimately print between
+                    // the ⏺ top line and this row — without the name here those rows
+                    // read as anonymous `⎿ ✓ 364ms` orphans in the transcript.
+                    name: block.name,
+                    args: (block.input ?? {}),
                 });
                 // v0.3 (Step 28.0): populate session.toolCalls so the SessionTimeline
                 // overlay can render per-write history. Cap per-entry payload size at
                 // 4kB to bound session.json growth.
+                // D19 (2026-06-11): upsert, not push — write handlers journal the same
+                // call through the WAL under this block.id; pushing unconditionally
+                // produced two ledger entries per approval-gated write.
                 const completedAt = new Date().toISOString();
                 {
                     const resultText = typeof result.content === 'string'
                         ? result.content
                         : JSON.stringify(result.content);
-                    session.toolCalls.push({
+                    recordCompletedToolCall(session, {
                         tool_use_id: block.id,
                         tool: block.name,
                         args: block.input ?? {},

package/dist/agent/providers/license-gate.js

@@ -0,0 +1,44 @@
+/**
+ * Thrown when a non-managed LLM mode is used without a valid CSPeach login.
+ * Carries a user-facing message; callers print it and exit rather than dumping
+ * a stack trace.
+ */
+export class CspeachLicenseError extends Error {
+    mode;
+    constructor(mode) {
+        super(`CSPeach requires a license to run in '${mode}' mode.\n` +
+            `In this mode your prompts go straight to your own LLM — but the CSPeach skills\n` +
+            `and CLI are licensed software. Run \`cspeach login\` to activate your license.\n` +
+            `Need an access key? Email laeeq.siddique@cremencing.com.`);
+        this.name = 'CspeachLicenseError';
+        this.mode = mode;
+    }
+}
+/**
+ * Gate every NON-managed mode (byok / local / ai-hub) on a valid CSPeach login.
+ *
+ * Why: managed mode authenticates against the proxy on every call, so it is
+ * already gated. The other modes bypass our proxy for inference — and the
+ * skills (our IP) are bundled into the package — so without this check a fresh
+ * `npm install` is fully usable by anyone who never logged in, untracked. A
+ * CSPeach key is admin-issued (no open self-signup), so requiring one means we
+ * know who is using the product and can revoke access.
+ *
+ * Scope (Part A): require a CSPeach key to be PRESENT. Server-side validation +
+ * revocation (so a forged key fails) is the Part-B follow-up — see
+ * docs/byok-portal-handover.md §0.
+ */
+export async function assertModeLicensed(mode, getBearer) {
+    if (mode === 'managed')
+        return;
+    let key = '';
+    try {
+        key = (await getBearer()) ?? '';
+    }
+    catch {
+        key = '';
+    }
+    if (key.trim().length === 0) {
+        throw new CspeachLicenseError(mode);
+    }
+}

package/dist/agent/skill-checkpoint.js

@@ -7,7 +7,7 @@
  * with full conversation context.
  *
  * What Layer 1 does NOT cover: skill-internal state files. /abap-cca, for
- * example, maintains `.abapforge/cca/projects/<id>/project.json` with an
+ * example, maintains `.cspeach/cca/projects/<id>/project.json` with an
  * inventory of objects, classifications, and per-package state. The skill
  * writes this file at PHASE BOUNDARIES (end of DISCOVER, end of INVENTORY,
  * etc.). A crash mid-DISCOVER means the partial inventory in project.json

package/dist/agent/tool-dispatch.js

@@ -23,6 +23,21 @@ export async function dispatchTool(name, args, ctx) {
             batch_count: getWriteOpsThisTurn().length + 1,
         });
         if (!r.confirmed) {
+            // B5 — discriminate WHO declined. A headless fail-fast (nobody ever
+            // saw the card) must not masquerade as a user decision: the model
+            // (and any transcript reader) reacts differently to "the user said
+            // no" vs "no user was available to say yes". Uniform `headless: true`
+            // marker matches the other headless result payloads.
+            if (r.headless) {
+                return {
+                    content: JSON.stringify({
+                        error: 'headless_safety_decline',
+                        headless: true,
+                        reason: r.reason,
+                    }),
+                    is_error: true,
+                };
+            }
             return {
                 content: JSON.stringify({ error: 'cancelled_by_user', reason: r.reason }),
                 is_error: true,

package/dist/approvals/canonical.js

@@ -0,0 +1,91 @@
+/**
+ * Canonical approval-object strings (Task A3 — defects D17/D21/D28).
+ *
+ * The battery exposed an APPROVAL_INVALID:object_mismatch epidemic (~8 wasted
+ * approval round-trips): request_approval minted whatever free-text object
+ * string the model wrote in the change row, while every write tool validated
+ * against a structured argument (args.name / args.className / args.description
+ * / objects[0].name). Any decoration the model added at mint time — and models
+ * reliably add decoration — broke the byte-equality check in
+ * verifyAndSpendApprovalId.
+ *
+ * Observed mismatch classes (exact strings from the battery sessions):
+ *   D17  "ZBP_I_DOWNTIMELOG (CCIMP / lhc_DowntimeLog.validateEndAfterStart)"
+ *        vs "ZBP_I_DOWNTIMELOG"               → trailing parenthetical
+ *   D21  "Transport: Magic fix" vs "Magic fix" → leading transport label
+ *   D28  "ZR_PM_MAINTREQ,ZBP_R_PM_MAINTREQ,…" vs "ZR_PM_MAINTREQ"
+ *        → one batch activate approval, per-object activate calls
+ *
+ * The fix is ONE code path for both sides:
+ *   - mint side (jwt.ts#mintChangeApproval, used by request_approval) stores
+ *     canonicalApprovalObject(change.object) in the JWT;
+ *   - spend side (jwt.ts#verifyAndSpendApprovalId) compares via
+ *     approvalObjectMatches, which canonicalizes BOTH the JWT payload object
+ *     and the tool's expected object before comparing.
+ * The spend side canonicalizes too because (a) the expected side is always the
+ * raw structured tool argument, never pre-canonicalized, and (b) it is
+ * defense-in-depth against any future mint site that bypasses
+ * mintChangeApproval and stores a raw string.
+ */
+/** Leading transport-request labels the model prepends to CTS descriptions. */
+const LEADING_LABEL = /^(?:transport(?:\s+request)?|tr|cts|request)\s*:\s*/i;
+/** A trailing parenthetical decoration, e.g. "(testclasses include)". */
+const TRAILING_PAREN = /\s*\([^()]*\)\s*$/;
+/** What an ABAP repository object name looks like once canonicalized. */
+const OBJECT_NAME = /^[A-Z0-9_/]+$/;
+/**
+ * Normalize an approval object string so mint and spend sides can never
+ * disagree on decoration, case, or whitespace:
+ *
+ *   1. trim
+ *   2. strip a leading "Transport:" / "TR:" / "Request:" label (D21)
+ *   3. strip trailing parenthetical decorations, stacked or single (D17)
+ *   4. collapse internal whitespace
+ *   5. uppercase
+ *
+ * All steps are applied symmetrically to both sides. Note that step 3 strips
+ * trailing parentheticals from free text too: transport descriptions
+ * "Fix dump (urgent)" and "Fix dump (rollback)" both canonicalize to
+ * "FIX DUMP" and therefore cross-match. This collision class is accepted
+ * because descriptions are display labels, not object identities, and every
+ * approval is session-scoped, TTL-bounded, and user-confirmed — the user saw
+ * the specific change row that minted the JWT.
+ */
+export function canonicalApprovalObject(raw) {
+    let s = String(raw ?? '').trim();
+    s = s.replace(LEADING_LABEL, '');
+    for (let prev = ''; prev !== s;) {
+        prev = s;
+        s = s.replace(TRAILING_PAREN, '');
+    }
+    return s.replace(/\s+/g, ' ').trim().toUpperCase();
+}
+/**
+ * Spend-side comparison: does the object string stored in the approval JWT
+ * authorize an operation on `expected` (the structured argument the write
+ * tool validates against)? Returns the match kind, or `false` for no match.
+ *
+ *   - byte equality ('exact'), OR
+ *   - canonical equality ('canonical'), OR
+ *   - the minted string is a comma-joined list of ABAP object names and
+ *     `expected` is one of them ('list_member', D28 — batch activate approval
+ *     spent by per-object sap_activate calls).
+ *
+ * The list rule only applies when EVERY part looks like an object name
+ * (no spaces / free text), so a transport description containing commas can
+ * never partially match.
+ */
+export function approvalObjectMatches(minted, expected) {
+    if (minted === expected)
+        return 'exact';
+    const m = canonicalApprovalObject(minted);
+    const e = canonicalApprovalObject(expected);
+    if (m === e)
+        return 'canonical';
+    const parts = m.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+    if (parts.length < 2)
+        return false;
+    if (!parts.every((p) => OBJECT_NAME.test(p)))
+        return false;
+    return parts.includes(e) ? 'list_member' : false;
+}

package/dist/approvals/jwt.js

@@ -1,5 +1,7 @@
 import { SignJWT, jwtVerify } from 'jose';
 import crypto from 'node:crypto';
+import { auditLog } from '@cspeach/sap-client';
+import { canonicalApprovalObject, approvalObjectMatches } from './canonical.js';
 // Session-scoped HMAC key — generated per CLI start, never persisted.
 const sessionKey = crypto.randomBytes(32);
 const usedNonces = new Set();
@@ -43,6 +45,24 @@ export async function mintApprovalId(payload) {
         .setExpirationTime('30m')
         .sign(sessionKey);
 }
+/**
+ * THE minting path for request_approval changes (Task A3 — D17/D21/D28).
+ *
+ * The object string stored in the JWT is canonicalized by the same helper the
+ * spend-side comparison in verifyAndSpendApprovalId uses, so mint and spend
+ * can never disagree on decoration ("Transport: …", "(testclasses include)"),
+ * case, or whitespace. request_approval and any future minting site MUST go
+ * through this function instead of calling mintApprovalId with a free-text
+ * object string.
+ */
+export async function mintChangeApproval(change, sessionId) {
+    return mintApprovalId({
+        object: canonicalApprovalObject(change.object),
+        type: change.type,
+        op: change.op,
+        session_id: sessionId,
+    });
+}
 export async function verifyAndSpendApprovalId(jwt, expectedObject, expectedOp) {
     // 2026-05-15 (bug 7): the previous catch lumped EVERY thrown failure
     // into `'invalid_signature'`, including expirations (which used to be
@@ -75,8 +95,19 @@ export async function verifyAndSpendApprovalId(jwt, expectedObject, expectedOp)
         // taxonomy short. Mismatch / spent-nonce paths NEVER reach this catch.
         return { ok: false, reason: 'invalid_signature' };
     }
-    if (payload.object !== expectedObject)
+    // Canonical comparison (Task A3 — D17/D21/D28): both sides are normalized
+    // by the same helper that mintChangeApproval used at mint time, and a
+    // comma-joined batch approval matches each of its member objects. The spend
+    // side canonicalizes as well because (a) `expectedObject` is always the raw
+    // structured tool argument, never pre-canonicalized, and (b) it is
+    // defense-in-depth against any future mint site that bypasses
+    // mintChangeApproval and stores a raw string. (It is NOT back-compat for
+    // old JWTs: the HMAC key is per-process and never persisted, so no
+    // pre-canonicalization token can ever reach this verifier.)
+    const matchKind = approvalObjectMatches(payload.object, expectedObject);
+    if (!matchKind) {
         return { ok: false, reason: 'object_mismatch' };
+    }
     // Op-group coverage: a create approval also authorizes the modify+activate
     // that complete the create; a modify approval authorizes its activate.
     const covered = OP_COVERAGE[payload.op];
@@ -90,5 +121,11 @@ export async function verifyAndSpendApprovalId(jwt, expectedObject, expectedOp)
             return { ok: false, reason: 'nonce_spent' };
         usedNonces.add(payload.nonce);
     }
-    return { ok: true, payload };
+    // Auditability: a lenient (non-byte-equal) match is an authorization
+    // decision worth a trace — record WHICH fold let the spend through, in the
+    // same audit log the write tools use.
+    if (matchKind !== 'exact') {
+        await auditLog('approvalSpend', payload.type, expectedObject, 'success', 0, `matchKind=${matchKind} minted="${payload.object}"`);
+    }
+    return { ok: true, payload, matchKind };
 }

package/dist/auth/org-anthropic-key.js

@@ -0,0 +1,25 @@
+/**
+ * Fetch the organisation's Anthropic API key from the CSPeach proxy.
+ *
+ * Returns the key string on success, or null on any failure.
+ * Non-fatal by design — callers must fall back to the manual prompt when null
+ * is returned. The key is NEVER logged.
+ */
+export async function fetchOrgAnthropicKey(proxyUrl, bearer, deps) {
+    const fetchFn = deps?.fetchImpl ?? fetch;
+    const url = `${proxyUrl.replace(/\/$/, '')}/v1/me/anthropic-key`;
+    try {
+        const r = await fetchFn(url, {
+            headers: { Authorization: `Bearer ${bearer}` },
+        });
+        if (!r.ok)
+            return null;
+        const body = await r.json();
+        if (typeof body.key === 'string' && body.key.length > 0)
+            return body.key;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}