@cspeach/cli 0.6.0

package/dist/tools/subagent/background_run.js

@@ -0,0 +1,143 @@
+// cspeach-cli/src/tools/subagent/background_run.ts
+/**
+ * background_run — Phase 3 / Chunk 3E.
+ *
+ * Spawns a safelisted command via the Chunk 3B safelist (reused
+ * through _command-shared.ts), registers the child in the in-process
+ * _background-shared registry, and returns a bg_id immediately.
+ * Child stdout/stderr lines stream into the registry as BgEvents;
+ * monitor_emit drains them.
+ *
+ * Child does NOT outlive the CLI process — the registry's exit
+ * handler SIGTERMs every live child on Node exit and SIGKILLs after
+ * KILL_GRACE_MS.
+ *
+ * Flag-gated: invisible to listTools() unless
+ * CSPEACH_TOOL_BACKGROUND_RUN=on. isMutating: true — hooks the existing
+ * approval gate (same UX as shell_exec).
+ */
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { registerTool } from '../index.js';
+import { resolveSafePath, PathOutsideRootError } from '../_filesystem-shared.js';
+import { loadSafelist, buildSafeEnv, resolveExecutable, validateArgv, rejectPathSeparator, } from '../_command-shared.js';
+import { registerBackground, recordEvent, installExitHandler, } from './_background-shared.js';
+export async function backgroundRunHandler(args, ctx) {
+    // Install once-per-process exit handler before we register anything.
+    installExitHandler();
+    if (!args.command || typeof args.command !== 'string') {
+        return { content: 'error: command is required (non-empty string)', is_error: true };
+    }
+    if (args.cwd !== undefined && typeof args.cwd !== 'string') {
+        return { content: 'error: cwd must be a string when provided', is_error: true };
+    }
+    // Silently drop non-string argv elements. Schema validation upstream should
+    // already enforce strings; this is belt-and-braces. A model passing [1, 'x', 2]
+    // sees only 'x' reach the child — surprising from the model's perspective but
+    // safe (safelist is on `command`, not argv).
+    const argv = Array.isArray(args.args) ? args.args.filter((a) => typeof a === 'string') : [];
+    const argvErr = validateArgv(argv);
+    if (argvErr !== null)
+        return { content: `error: ${argvErr}`, is_error: true };
+    const sepErr = rejectPathSeparator(args.command);
+    if (sepErr !== null)
+        return { content: `error: ${sepErr}`, is_error: true };
+    const safelist = await loadSafelist();
+    if (!safelist.has(args.command)) {
+        return {
+            content: `error: command "${args.command}" is not in the safelist. allowed: ${[...safelist].sort().join(', ')}. ` +
+                'extend via [shell_exec] allow = [...] in ~/.cspeach/config.toml.',
+            is_error: true,
+        };
+    }
+    let cwd;
+    try {
+        cwd = args.cwd ? resolveSafePath(ctx.cwd, args.cwd) : path.resolve(ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError)
+            return { content: `error: ${err.message}`, is_error: true };
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    try {
+        const stat = await fs.stat(cwd);
+        if (!stat.isDirectory())
+            return { content: `error: cwd "${args.cwd ?? '.'}" is not a directory`, is_error: true };
+    }
+    catch {
+        return { content: `error: cwd "${args.cwd ?? '.'}" does not exist`, is_error: true };
+    }
+    const resolved = await resolveExecutable(args.command);
+    if (resolved === null) {
+        return {
+            content: `error: command "${args.command}" not installed on this system (not found on PATH).`,
+            is_error: true,
+        };
+    }
+    let child;
+    try {
+        child = spawn(resolved, argv, {
+            cwd,
+            env: buildSafeEnv(),
+            windowsHide: true,
+            shell: false,
+            detached: false, // explicit assertion — never daemonize
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        return { content: `error: spawn failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // bg-<uuid> prefix is load-bearing — Task 4's monitor_emit validates
+    // against BG_ID_PATTERN /^bg-[0-9a-f-]+$/ to refuse path-traversal-style
+    // registry-key injection. Do NOT drop the prefix. See commit 1bfd71d.
+    const bg_id = `bg-${randomUUID()}`;
+    registerBackground({ bg_id, command: args.command, argv, child });
+    child.stdout?.on('data', (chunk) => {
+        recordEvent(bg_id, { kind: 'stdout', text: chunk.toString('utf-8'), ts: Date.now() });
+    });
+    child.stderr?.on('data', (chunk) => {
+        recordEvent(bg_id, { kind: 'stderr', text: chunk.toString('utf-8'), ts: Date.now() });
+    });
+    child.on('error', (err) => {
+        recordEvent(bg_id, { kind: 'error', text: err.message, ts: Date.now() });
+    });
+    child.on('close', (code, signal) => {
+        recordEvent(bg_id, {
+            kind: 'exit',
+            text: `code=${code ?? 'null'}${signal ? ` signal=${signal}` : ''}`,
+            ts: Date.now(),
+            exitCode: code,
+            signal,
+        });
+    });
+    return {
+        content: `bg_id: ${bg_id}\n` +
+            `command: ${args.command} ${argv.join(' ')}\n` +
+            `pid: ${child.pid ?? 'unknown'}\n` +
+            `cwd: ${cwd}\n` +
+            `note: child is running — call monitor_emit with this bg_id to drain stdout/stderr/exit events. ` +
+            `child will be SIGTERMd on CLI exit (then SIGKILLd after grace).`,
+    };
+}
+registerTool({
+    name: 'background_run',
+    description: 'Spawn a safelisted command as a non-blocking background process. Returns a bg_id immediately; ' +
+        'caller polls events via monitor_emit. Same safelist + argv-only + env scrub as shell_exec. ' +
+        'Child does NOT outlive the CLI process — SIGTERM on exit, SIGKILL after grace.',
+    isMutating: true,
+    category: 'subagent',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            command: { type: 'string', description: 'Bare command name. Must be in the safelist. No paths.' },
+            args: { type: 'array', items: { type: 'string' }, description: 'argv array — no shell parsing.' },
+            cwd: { type: 'string', description: 'Optional working directory relative to project root.' },
+        },
+        required: ['command'],
+    },
+    handler: (args, ctx) => backgroundRunHandler(args, ctx),
+});

package/dist/tools/subagent/monitor_emit.js

@@ -0,0 +1,65 @@
+// cspeach-cli/src/tools/subagent/monitor_emit.ts
+/**
+ * monitor_emit — Phase 3 / Chunk 3E.
+ *
+ * Drains events from a bg_id's registry buffer. Per-call cursor advance:
+ * each call returns up to `max` events from the front of the FIFO and
+ * removes them. Subsequent calls return only NEW events.
+ *
+ * `dropped` is the count of events FIFO-evicted from the buffer since
+ * the previous consume call; counter resets on read.
+ *
+ * Read-only — does not spawn anything. Safe to call repeatedly.
+ *
+ * Flag-gated: invisible to listTools() unless
+ * CSPEACH_TOOL_MONITOR_EMIT=on. isMutating: false.
+ */
+import { registerTool } from '../index.js';
+import { consumeEvents } from './_background-shared.js';
+const DEFAULT_MAX = 100;
+const HARD_MAX = 1_000;
+// bg_id = `bg-<uuid>`, where uuid is the 36-char shape (8-4-4-4-12 hex)
+// from crypto.randomUUID. The pattern accepts any UUID-shaped hex (not
+// strictly v4) — that's intentional, since Node's randomUUID() always
+// emits v4 lowercase and the `/i` flag forgives a model fabricating
+// uppercase. Pattern shape is load-bearing — defends against registry-
+// key injection (e.g. '../../etc/passwd'-style strings) by rejecting
+// anything that doesn't match before the registry lookup runs.
+// MUST match background_run.ts's bg_id construction (Task 3, 1bfd71d).
+const BG_ID_PATTERN = /^bg-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export async function monitorEmitHandler(args, _ctx) {
+    if (!args.bg_id || typeof args.bg_id !== 'string') {
+        return { content: 'error: bg_id is required (non-empty string)', is_error: true };
+    }
+    if (!BG_ID_PATTERN.test(args.bg_id)) {
+        return { content: `error: invalid bg_id shape '${args.bg_id}' — must match bg-<uuid>`, is_error: true };
+    }
+    const maxArg = typeof args.max === 'number' && Number.isFinite(args.max) && args.max > 0
+        ? Math.floor(args.max)
+        : DEFAULT_MAX;
+    const max = Math.min(maxArg, HARD_MAX);
+    const result = consumeEvents(args.bg_id, max);
+    if (result === null) {
+        return { content: `error: bg_id '${args.bg_id}' not found in registry`, is_error: true };
+    }
+    return { content: JSON.stringify(result, null, 2) };
+}
+registerTool({
+    name: 'monitor_emit',
+    description: 'Drain buffered events (stdout/stderr/exit) from a background_run bg_id. Per-call cursor ' +
+        'advance: each call returns up to `max` events (default 100, hard cap 1000) and removes ' +
+        'them from the buffer. Subsequent calls return only NEW events. Surfaces `dropped` if ' +
+        'FIFO eviction occurred since the previous read.',
+    isMutating: false,
+    category: 'subagent',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            bg_id: { type: 'string', description: 'The bg_id returned by background_run.' },
+            max: { type: 'number', description: 'Max events to return this call. Default 100, hard cap 1000.' },
+        },
+        required: ['bg_id'],
+    },
+    handler: (args, ctx) => monitorEmitHandler(args, ctx),
+});

package/dist/tools/subagent/schedule_create.js

@@ -0,0 +1,131 @@
+// cspeach-cli/src/tools/subagent/schedule_create.ts
+/**
+ * schedule_create — Phase 3 / Chunk 3E.
+ *
+ * Persists a schedule envelope to ~/.cspeach/schedules/<uuid>.json.
+ * Filename is ALWAYS crypto.randomUUID — never derived from user
+ * input. Closes the path-injection class of attack on the schedules
+ * directory.
+ *
+ * IMPORTANT: this tool persists schedules. It does NOT execute them.
+ * A future chunk (Phase 4 or later) ships the actual runner. The
+ * tool description and the response body both surface this caveat
+ * so the agent doesn't assume the schedule will fire.
+ *
+ * Flag-gated: invisible to listTools() unless
+ * CSPEACH_TOOL_SCHEDULE_CREATE=on. isMutating: true (writes filesystem).
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { registerTool } from '../index.js';
+const NOT_EXECUTED_NOTE = 'Persisted only — the schedule runner has not shipped yet. ' +
+    'See Phase 4+ for execution.';
+// Test-overridable. Default to ~/.cspeach/schedules. Set null to reset.
+let schedulesDirOverride = null;
+/** Test-only: redirect the schedules dir so tests don't pollute the real home dir. */
+export function __setSchedulesDirForTests(dir) {
+    schedulesDirOverride = dir;
+}
+function getSchedulesDir() {
+    return schedulesDirOverride ?? path.join(os.homedir(), '.cspeach', 'schedules');
+}
+// Strict ISO-8601 UTC: YYYY-MM-DDTHH:MM:SS(.sss)?Z
+const ISO_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+export async function scheduleCreateHandler(args, _ctx) {
+    if (args.kind !== 'oneoff' && args.kind !== 'cron') {
+        return { content: `error: kind must be 'oneoff' or 'cron' — got '${args.kind}'`, is_error: true };
+    }
+    if (!args.when || typeof args.when !== 'string' || args.when.trim().length === 0) {
+        return { content: 'error: when is required (non-empty string)', is_error: true };
+    }
+    if (!args.command || typeof args.command !== 'string' || args.command.trim().length === 0) {
+        return { content: 'error: command is required (non-empty string)', is_error: true };
+    }
+    if (args.kind === 'oneoff') {
+        if (!ISO_PATTERN.test(args.when)) {
+            return { content: `error: when must be an ISO-8601 UTC timestamp (e.g. 2099-06-01T10:00:00Z) — got '${args.when}'`, is_error: true };
+        }
+        const t = Date.parse(args.when);
+        if (Number.isNaN(t)) {
+            return { content: `error: when is not a parseable ISO timestamp: '${args.when}'`, is_error: true };
+        }
+        // Belt-and-braces against silent month/day rollover. Date.parse('2099-02-30T00:00:00Z')
+        // returns a valid timestamp that round-trips to March 2 — without this check, the
+        // envelope persists '2099-02-30' but the runner fires on March 2 (phantom job).
+        const roundTrip = new Date(t).toISOString();
+        // Normalise both sides: lowercase 'z', strip optional fractional seconds, compare.
+        const norm = (s) => s.replace(/\.\d+Z$/, 'Z').toUpperCase();
+        if (norm(roundTrip) !== norm(args.when)) {
+            return { content: `error: when is not a valid calendar date: '${args.when}' (rolls to ${roundTrip})`, is_error: true };
+        }
+        if (t <= Date.now()) {
+            return { content: `error: when is in the past — schedule must be in the future`, is_error: true };
+        }
+    }
+    else {
+        // cron: just check it has 5 whitespace-separated fields.
+        const fields = args.when.trim().split(/\s+/);
+        if (fields.length !== 5) {
+            return { content: `error: cron expression must have 5 fields (min hour dom mon dow) — got ${fields.length}`, is_error: true };
+        }
+    }
+    const dir = getSchedulesDir();
+    await fs.mkdir(dir, { recursive: true });
+    // Defence-in-depth: resolve the directory and verify it sits inside
+    // the cspeach home (or the test override). Refuses if a symlink
+    // points the dir at /etc/, /tmp/host-controlled/, etc.
+    const realDir = await fs.realpath(dir);
+    // In test mode the override dir IS the root (self-containment is trivial —
+    // mkdtemp gives us a unique dir that acts as both schedules-dir and its own
+    // root). In prod the schedules dir must sit UNDER ~/.cspeach/, so the root
+    // is the parent. Asymmetric on purpose.
+    const expectedRoot = schedulesDirOverride !== null
+        ? path.resolve(schedulesDirOverride)
+        : path.join(os.homedir(), '.cspeach');
+    const rel = path.relative(expectedRoot, realDir);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        return { content: `error: schedules directory '${realDir}' resolves outside expected root`, is_error: true };
+    }
+    const id = randomUUID();
+    const envelope = {
+        id,
+        kind: args.kind,
+        when: args.when,
+        command: args.command,
+        createdAt: new Date().toISOString(),
+        note: NOT_EXECUTED_NOTE,
+    };
+    const target = path.join(realDir, `${id}.json`);
+    await fs.writeFile(target, JSON.stringify(envelope, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    return {
+        content: `schedule persisted (NOT YET EXECUTED — runner ships in a later chunk).\n` +
+            `path: ${target}\n` +
+            `id: ${id}\n` +
+            `kind: ${args.kind}\n` +
+            `when: ${args.when}\n` +
+            `command: ${args.command}\n` +
+            `note: ${NOT_EXECUTED_NOTE}`,
+    };
+}
+registerTool({
+    name: 'schedule_create',
+    description: 'Persist a oneoff or cron schedule envelope to ~/.cspeach/schedules/<uuid>.json. ' +
+        'Filename is a fresh UUID — never derived from input. NOTE: this tool only PERSISTS the ' +
+        'schedule. No runner is shipped yet — the agent should not assume the command will fire ' +
+        'automatically. A future chunk will ship the runner.',
+    isMutating: true,
+    category: 'subagent',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            kind: { type: 'string', enum: ['oneoff', 'cron'], description: 'oneoff = single ISO timestamp; cron = 5-field expression' },
+            when: { type: 'string', description: 'ISO-8601 UTC timestamp for oneoff, or 5-field cron expression' },
+            command: { type: 'string', description: 'The command the runner WOULD execute (free-form string for now)' },
+        },
+        required: ['kind', 'when', 'command'],
+    },
+    handler: (args, ctx) => scheduleCreateHandler(args, ctx),
+});

package/dist/tools/transport.js

@@ -0,0 +1,233 @@
+/**
+ * Transport tools — Rule 9 (transport isolation).
+ *
+ * Confirmed AdtClient signatures (sap-client/src/adt-client.ts):
+ *   transportCreate(description, targetPackage?)  → Promise<TransportResult>     line 2508
+ *     TransportResult { operation, transportNumber?, description?, status?, error? }
+ *   transportList(user?, status?)                 → Promise<TransportListResult>  line 1048
+ *     TransportListResult { filterUser, filterStatus, transports: TransportEntry[] }
+ *     TransportEntry { transportNumber, description?, owner?, status?, type?, target? }
+ *   transportRelease(transportNumber)             → Promise<TransportResult>      line 2546
+ *     Released status string from SAP is 'released' (not a raw 'R' code).
+ */
+import { registerTool } from './index.js';
+import { verifyAndSpendApprovalId } from '../approvals/jwt.js';
+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';
+// ── sap_transport_create ─────────────────────────────────────────────────────
+//
+// Creates a new CTS workbench transport request.
+// Used once per session (Rule 9 — dedicated transport per session).
+registerTool({
+    name: 'sap_transport_create',
+    description: 'Create a new CTS transport request (Rule 9 — one dedicated transport per session). '
+        + 'BEFORE calling this tool, you MUST ask the user for the transport description '
+        + 'using `ask_question` — DO NOT generate a marketing-style description yourself. '
+        + 'Use the user\'s exact answer as the `description` argument AND in your '
+        + '`request_approval` reason. Identical strings prevent the approval mismatch '
+        + 'failure mode observed live 2026-05-07. '
+        + 'Requires approval_id. Returns the transport number to use in subsequent writes.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            description: {
+                type: 'string',
+                description: 'Transport description AS PROVIDED BY THE USER (ask via ask_question first). '
+                    + 'Must be ≤60 characters, ASCII only — no em-dashes (—), em-spaces, smart quotes, '
+                    + 'or non-Latin characters. SAP\'s CTS description field is Latin-1 and rejects/'
+                    + 'garbles wider Unicode. Good examples: "Sales order overdue report", '
+                    + '"ZSD_OVERDUE: CDS + OData V4 stack". Bad examples: '
+                    + '"CSPeach: Overdue SO Monitoring — CDS + OData" (em-dash → HTTP 400), '
+                    + 'overly long marketing-style summaries.',
+            },
+            target_package: {
+                type: 'string',
+                description: 'Target package (DEVCLASS) for the transport — typically the same package the '
+                    + 'objects will live in. Required by SAP\'s CreateCorrectionRequest endpoint. '
+                    + 'Empty / missing target_package on this endpoint commonly causes HTTP 400.',
+            },
+            approval_id: {
+                type: 'string',
+                description: 'JWT from request_approval. Reason field on request_approval should be '
+                    + 'IDENTICAL to the description argument here — same exact string — or the '
+                    + 'approval will fail with object_mismatch.',
+            },
+        },
+        required: ['description', 'approval_id'],
+    },
+    handler: async (args, ctx) => {
+        // ── Gate 1: Approval ────────────────────────────────────────────────────
+        const verify = await verifyAndSpendApprovalId(args.approval_id, args.description, 'create');
+        if (!verify.ok) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
+                is_error: true,
+            };
+        }
+        const startedAt = Date.now();
+        // ── Create transport ─────────────────────────────────────────────────────
+        // transportCreate(description, targetPackage?)
+        try {
+            const result = await ctx.adt.transportCreate(args.description, args.target_package);
+            await auditLog('transportCreate', 'CTS', result.transportNumber ?? 'UNKNOWN', 'success', Date.now() - startedAt);
+            if (result.status !== 'created' || !result.transportNumber) {
+                return {
+                    content: JSON.stringify({ error: 'transport_create_failed', detail: result.error }),
+                    is_error: true,
+                };
+            }
+            // Rule 9 — auto-attach the new TR as the session current-transport so that
+            // subsequent write calls pick it up via the 3-tier fallback without the LLM
+            // needing to pass it explicitly every time.
+            setCurrentTransport(result.transportNumber);
+            return {
+                content: JSON.stringify({
+                    created: true,
+                    transport_number: result.transportNumber,
+                    description: result.description,
+                    note: 'Use this transport_number in all subsequent sap_set_source / sap_create_object calls this session.',
+                }),
+            };
+        }
+        catch (err) {
+            await auditLog('transportCreate', 'CTS', 'UNKNOWN', 'error', Date.now() - startedAt);
+            return {
+                content: JSON.stringify({ error: 'transport_create_failed', detail: String(err) }),
+                is_error: true,
+            };
+        }
+    },
+});
+// ── sap_transport_list ───────────────────────────────────────────────────────
+//
+// Lists transport requests, optionally filtered by owner and/or status.
+// Read-only — no approval needed.
+registerTool({
+    name: 'sap_transport_list',
+    description: 'List SAP CTS transport requests. '
+        + 'Optionally filter by owner (user) or status (modifiable | released).',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            owner: {
+                type: 'string',
+                description: 'Filter by transport owner (SAP user ID). Omit for all owners.',
+            },
+            status: {
+                type: 'string',
+                enum: ['modifiable', 'released'],
+                description: 'Filter by status. Defaults to "modifiable".',
+            },
+        },
+    },
+    handler: async (args, ctx) => {
+        // transportList(user?, status?)
+        try {
+            const result = await ctx.adt.transportList(args.owner, args.status);
+            return {
+                content: JSON.stringify({
+                    filter_user: result.filterUser || null,
+                    filter_status: result.filterStatus,
+                    count: result.transports.length,
+                    transports: result.transports,
+                }),
+            };
+        }
+        catch (err) {
+            return {
+                content: JSON.stringify({ error: 'transport_list_failed', detail: String(err) }),
+                is_error: true,
+            };
+        }
+    },
+});
+// ── sap_transport_release ────────────────────────────────────────────────────
+//
+// Releases a transport request.
+// Pre-conditions: all objects must be syntax-clean and ATC-clean (Rule 9).
+// Signature: transportRelease(transportNumber) → { operation, transportNumber, status }
+//   status is 'released' on success (not a raw SAP status code).
+registerTool({
+    name: 'sap_transport_release',
+    description: 'Release a CTS transport request. '
+        + 'All objects must be syntax-clean and ATC-clean before releasing (Rule 9). '
+        + 'Requires approval_id.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            transport: {
+                type: 'string',
+                description: 'Transport request number to release (e.g. DEVK900123)',
+            },
+            approval_id: {
+                type: 'string',
+                description: 'JWT from request_approval',
+            },
+        },
+        required: ['transport', 'approval_id'],
+    },
+    handler: async (args, ctx) => {
+        // ── Gate 1: Approval ────────────────────────────────────────────────────
+        const verify = await verifyAndSpendApprovalId(args.approval_id, args.transport, 'release');
+        if (!verify.ok) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
+                is_error: true,
+            };
+        }
+        const startedAt = Date.now();
+        // ── Gate 2: Safety confirmation (Rule 9 — transport release is irreversible) ──
+        if (isSafetyConfirmEnabled()) {
+            const r = await presentSafetyConfirmation({
+                rule: 'RULE_9_TRANSPORT_RELEASE',
+                op: 'transport_release',
+                object: { type: 'TRANSPORT', name: args.transport },
+                what_will_happen: `Releases ${args.transport}; objects move to QA queue, transport becomes immutable.`,
+                rollback_available: false,
+                transport: args.transport,
+            });
+            if (!r.confirmed) {
+                return {
+                    content: JSON.stringify({ error: 'cancelled_by_user', reason: r.reason }),
+                    is_error: true,
+                };
+            }
+        }
+        // ── Release transport ────────────────────────────────────────────────────
+        // transportRelease(transportNumber)
+        try {
+            const result = await ctx.adt.transportRelease(args.transport);
+            await auditLog('transportRelease', 'CTS', args.transport, result.status === 'released' ? 'success' : 'error', Date.now() - startedAt);
+            if (result.error) {
+                return {
+                    content: JSON.stringify({
+                        error: 'transport_release_failed',
+                        detail: result.error,
+                        status: result.status,
+                    }),
+                    is_error: true,
+                };
+            }
+            return {
+                content: JSON.stringify({
+                    released: result.status === 'released',
+                    transport_number: result.transportNumber,
+                    status: result.status,
+                }),
+            };
+        }
+        catch (err) {
+            await auditLog('transportRelease', 'CTS', args.transport, 'error', Date.now() - startedAt);
+            return {
+                content: JSON.stringify({ error: 'transport_release_failed', detail: String(err) }),
+                is_error: true,
+            };
+        }
+    },
+});