@cspeach/cli 0.8.0 → 1.0.0

package/dist/tools/shell/shell_exec.js

@@ -8,11 +8,26 @@
  *   allow = ["docker", "make"]
  * block in ~/.cspeach/config.toml.
  *
- * Cross-platform: on Windows resolves the .cmd / .bat / .exe shim
- * via PATH walk before spawning (Node's spawn with shell:false can't
- * directly invoke .cmd files; using shell:true reopens shell-injection
- * + CVE-2024-27980). On Unix the bare name is passed straight through
- * — spawn finds it on PATH.
+ * Cross-platform spawn via cross-spawn (the library npm itself uses).
+ * The actual spawn is handed the ABSOLUTE PATH-resolved executable path
+ * (from resolveExecutable's PATH-only walk) + argv ARRAY. cross-spawn
+ * still inspects the file extension and, on Windows, invokes .cmd / .bat
+ * through cmd.exe with correct per-arg escaping. This satisfies Node's
+ * CVE-2024-27980 restriction (spawn with shell:false refuses to launch
+ * .cmd/.bat directly) WITHOUT ever setting shell:true — args stay an
+ * array, so shell metacharacters are inert and there is no injection
+ * surface. On Unix cross-spawn is a near-passthrough to
+ * child_process.spawn (unchanged behavior).
+ *
+ * SECURITY — why the absolute path, not the bare name: cross-spawn
+ * resolves a BARE command name cwd-FIRST on Windows (node_modules/which
+ * checks process.cwd() before PATH on win32). A model with an in-tree
+ * write primitive could plant `<safelisted>.cmd` in the project tree and
+ * have cross-spawn pick it up ahead of the real PATH binary → arbitrary
+ * code execution, safelist bypassed. Spawning the absolute PATH-resolved
+ * path (which never consults cwd/PATH for a path-bearing command) closes
+ * that vector. The pre-flight resolveExecutable() PATH walk and the spawn
+ * now use the SAME binary — no pre-flight/spawn divergence.
  *
  * Operational caps:
  *   - 30 s wall-clock timeout (overridable up to 300 s via timeout_ms arg)
@@ -24,7 +39,7 @@
  * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_SHELL_EXEC=on.
  * isMutating: true — hooks into the existing approval gate.
  */
-import { spawn } from 'node:child_process';
+import spawn from 'cross-spawn';
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
@@ -80,6 +95,9 @@ export async function shellExecHandler(args, ctx) {
     catch {
         return { content: `error: cwd "${args.cwd ?? '.'}" does not exist`, is_error: true };
     }
+    // Resolve the bare safelisted name to an absolute executable path via a
+    // PATH-only walk (no cwd-first). This is BOTH the friendly "not installed"
+    // pre-flight check AND the spawn target below — same binary, no divergence.
     const resolved = await resolveExecutable(args.command);
     if (resolved === null) {
         return {
@@ -101,6 +119,23 @@ export async function shellExecHandler(args, ctx) {
             settled = true;
             resolve(result);
         };
+        // Pass the already-validated absolute `resolved` path (from
+        // resolveExecutable's PATH-only walk) — NOT the bare command name.
+        //
+        // SECURITY: cross-spawn resolves a BARE name cwd-first on Windows
+        // (node_modules/which checks process.cwd() before PATH on win32, and
+        // it chdir's into options.cwd first). A model with a write primitive
+        // could plant `<safelisted>.cmd` (e.g. git.cmd) in the project tree and
+        // have cross-spawn pick it up cwd-first → arbitrary code execution,
+        // safelist bypassed. Handing cross-spawn the absolute PATH-resolved
+        // path closes that: `which` short-circuits to the literal file when the
+        // command contains a path separator (pathEnv=['']), so cwd/PATH are
+        // never consulted. cross-spawn STILL inspects the file extension and
+        // wraps an absolute `.cmd`/`.bat` through cmd.exe with proper per-arg
+        // escaping (parse.js isExecutableRegExp only matches .com/.exe), so the
+        // Windows shim handling + CVE-2024-27980 .cmd restriction handling are
+        // preserved. shell:false stays (argv-only; metacharacters inert). The
+        // existence check above and this spawn now target the SAME binary.
         const child = spawn(resolved, argv, {
             cwd,
             env: buildSafeEnv(),

package/dist/tools/snapshot.js

@@ -14,7 +14,18 @@
  *   cleanup(retentionHours?)          → Promise<number>
  */
 import { registerTool } from './index.js';
-import { snapshots } from '@cspeach/sap-client';
+import { snapshots, SapError } from '@cspeach/sap-client';
+/** True only for a genuine ADT 404 — the object does not exist. Any other
+ *  failure (network, auth, 5xx, timeout) is a READ failure, not proof of
+ *  absence, and must never be labelled "object not found". */
+function isNotFound(err) {
+    return err instanceof SapError && err.httpStatus === 404;
+}
+/** Short single-line failure message for transcripts / error envelopes. */
+function shortErrorMessage(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.replace(/\s+/g, ' ').trim();
+}
 registerTool({
     name: 'sap_snapshot_take',
     description: "Take a snapshot of an object's current source before modification. Usually invoked automatically by the CLI before any write — rarely called directly by the model.",
@@ -28,25 +39,37 @@ registerTool({
         required: ['name', 'type'],
     },
     handler: async (args, ctx) => {
-        const source = await ctx.adt.getSource(args.type, args.name).catch(() => null);
-        if (source === null) {
-            return { content: JSON.stringify({ skipped: true, reason: 'object_not_found' }) };
+        let source;
+        try {
+            source = await ctx.adt.getSource(args.type, args.name);
+        }
+        catch (err) {
+            if (isNotFound(err)) {
+                return { content: JSON.stringify({ skipped: true, reason: 'object_not_found' }) };
+            }
+            // Read failed for some OTHER reason — the object may well exist.
+            // Claiming "object_not_found" here would be a lie; surface the failure.
+            return {
+                content: JSON.stringify({ error: 'source_read_failed', detail: shortErrorMessage(err) }),
+                is_error: true,
+            };
         }
         const entry = await snapshots.take(args.type, args.name, source, 'manual');
         return { content: JSON.stringify({ snapshot: entry, size: source.length }) };
     },
 });
-/**
- * Auto-snapshot helper called by write tools before mutating an object.
- * Silently skips if the object does not exist yet (first write after create).
- *
- * snapshots.take expects (type, name, source, reason).
- */
 export async function autoSnapshot(objectName, objectType, adt) {
-    const src = await adt.getSource(objectType, objectName).catch(() => null);
-    if (src === null)
-        return; // new object — nothing to snapshot
-    await snapshots.take(objectType, objectName, src, 'before_write');
+    let src;
+    try {
+        src = await adt.getSource(objectType, objectName);
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return { taken: false, reason: 'object_not_found' }; // new object
+        return { taken: false, reason: 'source_read_failed', detail: shortErrorMessage(err) };
+    }
+    const entry = await snapshots.take(objectType, objectName, src, 'before_write');
+    return { taken: true, entry };
 }
 // ── sap_snapshot_list ─────────────────────────────────────────────────────────
 registerTool({

package/dist/tools/subagent/background_run.js

@@ -16,7 +16,7 @@
  * CSPEACH_TOOL_BACKGROUND_RUN=on. isMutating: true — hooks the existing
  * approval gate (same UX as shell_exec).
  */
-import { spawn } from 'node:child_process';
+import spawn from 'cross-spawn';
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -69,6 +69,9 @@ export async function backgroundRunHandler(args, ctx) {
     catch {
         return { content: `error: cwd "${args.cwd ?? '.'}" does not exist`, is_error: true };
     }
+    // Resolve the bare safelisted name to an absolute executable path via a
+    // PATH-only walk (no cwd-first). Both the friendly "not installed"
+    // pre-flight check AND the spawn target below — same binary, no divergence.
     const resolved = await resolveExecutable(args.command);
     if (resolved === null) {
         return {
@@ -78,6 +81,19 @@ export async function backgroundRunHandler(args, ctx) {
     }
     let child;
     try {
+        // Absolute PATH-resolved `resolved` (NOT the bare command name).
+        //
+        // SECURITY: cross-spawn resolves a BARE name cwd-first on Windows
+        // (node_modules/which checks process.cwd() before PATH and chdir's into
+        // options.cwd first). A model with a write primitive could plant
+        // `<safelisted>.cmd` in the project tree and have it picked up cwd-first
+        // → arbitrary code execution, safelist bypassed. Handing cross-spawn the
+        // absolute PATH-resolved path closes that (`which` short-circuits to the
+        // literal file for path-bearing commands, pathEnv=['']). cross-spawn
+        // still wraps an absolute `.cmd`/`.bat` through cmd.exe with per-arg
+        // escaping, so Windows shim + CVE-2024-27980 handling stay. shell:false
+        // → metacharacters inert. Existence check + spawn now target the SAME
+        // binary. See shell_exec.ts for the full rationale.
         child = spawn(resolved, argv, {
             cwd,
             env: buildSafeEnv(),

package/dist/tools/transport-resolution.js

@@ -0,0 +1,86 @@
+/**
+ * transport-resolution — owning-transport check before SAP writes (Rule 9,
+ * battery defects D15/D20).
+ *
+ * The trap this kills: an object (or one of its LIMU pieces) is already
+ * locked in an open transport request. Writing under ANY other transport is
+ * guaranteed to fail with a CTS lock conflict (CTS_WBO_API 020 — observed
+ * live: "Object LIMU CINC ZBP_I_DOWNTIMELOG…CCIMP is already locked in
+ * request S4HK903431"). Asking the human to pick from N open transports
+ * (D15: 89 of them) or creating a fresh junk transport (D20) cannot succeed.
+ *
+ * Correct flow, now structural instead of prose-only:
+ *   - object locked in exactly one open request → USE that transport
+ *     silently, overriding a conflicting supplied transport (with a notice);
+ *   - object locked in several open requests → ambiguous, never force —
+ *     keep the supplied transport and surface the candidates;
+ *   - object free / lookup failed → current behaviour (supplied transport).
+ *
+ * The lookup is one E071+E070 query pair (AdtClient.transportForObject) and
+ * is strictly best-effort: a failed lookup (VPN drop, data-preview auth,
+ * older mocks without the method) must NEVER block the write.
+ */
+import { wasTransportCreatedThisSession } from './transport.js';
+/**
+ * Resolve the transport for a write against the owning-transport ledger.
+ *
+ * @param ctx        tool context (uses ctx.adt + ctx.chunkEmitter)
+ * @param objectType ABAP object type of the write target (CLAS, PROG, …)
+ * @param objectName ABAP object name of the write target
+ * @param supplied   the transport the tool would use today (each tool keeps
+ *                   its own args/session fallback semantics and passes the
+ *                   outcome here)
+ */
+export async function resolveWriteTransport(ctx, objectType, objectName, supplied) {
+    // TODO(perf): per-turn memo. Every write funnels through this lookup
+    // (2 datapreview SQL queries inside transportForObject), so a multi-method
+    // turn — N sap_update_method calls against the same class — amplifies to
+    // N×2 queries for an answer that cannot change mid-turn. Memoise per turn,
+    // keyed `${objectType}:${objectName}`, before the battery grows
+    // write-heavy scenarios. No implementation yet.
+    let owning = null;
+    try {
+        owning = await ctx.adt.transportForObject(objectType, objectName);
+    }
+    catch (err) {
+        // Best-effort only — never block or delay the write on a failed lookup,
+        // but leave a dim trace so "why didn't it auto-resolve?" is diagnosable
+        // ('info' channel = non-fatal diagnostics; 'warn' is reserved for the
+        // conflicting-override case below).
+        ctx.chunkEmitter?.emit('info', `owning-transport lookup failed for ${objectType} ${objectName} — `
+            + `proceeding with ${supplied ?? 'no transport'} `
+            + `(${err instanceof Error ? err.message : String(err)})`);
+        return { transport: supplied };
+    }
+    if (owning?.transport) {
+        const conflicting = !!supplied && supplied !== owning.transport;
+        const note = conflicting
+            ? `${objectName} is already locked in ${owning.transport} — writing under the owning transport and ignoring transport=${supplied} (SAP would refuse with a CTS lock conflict)`
+            : `object locked in ${owning.transport} — writing under owning transport`;
+        // warn only when we OVERRIDE what the caller asked for; the happy match
+        // (supplied === owning, or nothing supplied) is informational.
+        ctx.chunkEmitter?.emit(conflicting ? 'warn' : 'info', note);
+        // Orphan hint (third junk TR this month, 2026-06-12): the session's
+        // current transport was created by sap_transport_create THIS session, yet
+        // this write was forced into a different (owning) request — the created
+        // TR is probably an empty orphan. Warn only; deleting a TR is destructive
+        // and stays with the human.
+        const sessionCurrent = ctx.currentTransport?.get() ?? null;
+        if (sessionCurrent
+            && sessionCurrent !== owning.transport
+            && wasTransportCreatedThisSession(sessionCurrent)) {
+            ctx.chunkEmitter?.emit('warn', `transport ${sessionCurrent} created this session was not used by this write — `
+                + 'it may be an empty orphan (delete via SE09 or ask me)');
+        }
+        return { transport: owning.transport, owning: owning.transport, note };
+    }
+    if (owning && owning.candidates.length > 1) {
+        const note = `${objectName} pieces are locked in ${owning.candidates.length} open transports `
+            + `(${owning.candidates.join(', ')}) — cannot auto-resolve the owning request; `
+            + `using ${supplied ?? 'no transport'}`;
+        ctx.chunkEmitter?.emit('warn', note);
+        return { transport: supplied, note };
+    }
+    // Object is free — current behaviour.
+    return { transport: supplied };
+}

package/dist/tools/transport.js

@@ -17,6 +17,28 @@ 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';
+// ── Session ledger: transports CREATED by sap_transport_create this session ──
+//
+// Orphan-hint support (third junk transport this month, 2026-06-12 — D15/D20
+// pattern: /abap-refactor created a fresh TR while ZTTT_GAME was already
+// locked in S4HK903328, leaving the new TR an empty orphan).
+// resolveWriteTransport (transport-resolution.ts) consults this set: when a
+// write is forced into the owning transport, the session current-transport
+// differs, AND the current one came from a create THIS session, it warns that
+// the created TR may be an empty orphan. Deliberately NOT persisted — a TR
+// created in an earlier session may have collected objects since.
+const createdThisSession = new Set();
+export function markTransportCreatedThisSession(trkorr) {
+    createdThisSession.add(trkorr);
+}
+export function wasTransportCreatedThisSession(trkorr) {
+    return createdThisSession.has(trkorr);
+}
+/** Test hook — the set is a module-scope singleton and would otherwise leak
+ *  across Vitest tests (same pattern as clearCurrentTransport). */
+export function clearTransportsCreatedThisSession() {
+    createdThisSession.clear();
+}
 // ── sap_transport_create ─────────────────────────────────────────────────────
 //
 // Creates a new CTS workbench transport request.
@@ -24,16 +46,43 @@ import { setCurrentTransport } from '../repl/current-transport.js';
 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. '
+        + 'RESOLVE FIRST: pass for_object_type/for_object_name ONLY for an EXISTING object you '
+        + 'are about to MODIFY/WRITE — the tool then reuses that object owning transport. Do NOT '
+        + 'pass an object you are only READING and not changing (e.g. the legacy source in a '
+        + 'modernization; the NEW objects go to a fresh transport and the read-only source lock '
+        + 'is irrelevant). Creating brand-new objects from scratch? OMIT for_object and a fresh '
+        + 'transport is created. '
+        + 'Flow: resolve → object locked in an open transport? this tool then does NOT '
+        + 'create anything and returns the owning transport — use it → only create when '
+        + 'the object is free. '
+        + 'Ask the user for the transport description using `ask_question` — DO NOT '
+        + 'generate a marketing-style description yourself. When asking, SUGGEST the '
+        + 'Rule 9 session format "ABAPForge <YYYY-MM-DD>: <work summary>" as the default; '
+        + 'the user may override. 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: {
+            for_object_type: {
+                type: 'string',
+                description: 'ABAP object type (PROG, CLAS, …) of the object motivating this transport. '
+                    + 'Pass it together with for_object_name whenever the transport is for work '
+                    + 'on a known existing object.',
+            },
+            for_object_name: {
+                type: 'string',
+                description: 'Name of the object you are about to WRITE/modify (NOT a read-only source object '
+                    + 'you only read — e.g. the legacy program in a modernization, whose new objects '
+                    + 'go to a fresh transport).',
+            },
+            force: {
+                type: 'boolean',
+                description: 'Set true to create a new transport even though for_object is already '
+                    + 'locked elsewhere (rare — deliberate parallel transport). Default false.',
+            },
             description: {
                 type: 'string',
                 description: 'Transport description AS PROVIDED BY THE USER (ask via ask_question first). '
@@ -60,6 +109,79 @@ registerTool({
         required: ['description', 'approval_id'],
     },
     handler: async (args, ctx) => {
+        // ── Gate 0: owning-transport guard (runs BEFORE the approval gate) ──────
+        //
+        // Ordering decision (2026-06-12, documented on purpose): the E071 lookup
+        // runs BEFORE verifyAndSpendApprovalId. When the motivating object is
+        // already locked, the early `already_locked` return performs NO mutation
+        // (read-only lookup + session current-transport pointer), so no
+        // authorization needs to be — or should be — consumed for it. Concretely:
+        // verifyAndSpendApprovalId only burns a nonce for one-shot ops
+        // (delete/release; 'create' approvals are reusable within TTL), so the
+        // user's approval JWT survives either ordering — but lookup-first means
+        // the model gets the useful answer ("use S4HK903328") even when the
+        // approval is stale/mismatched, instead of an APPROVAL_INVALID round-trip
+        // for a create that should never happen. The approval is verified only on
+        // the path that actually creates.
+        //
+        // Best-effort: a failed lookup must NEVER block the create (VPN flake is
+        // normal here) — same contract as resolveWriteTransport.
+        let guardNote;
+        if (args.for_object_name && !args.force) {
+            try {
+                const owning = await ctx.adt.transportForObject(args.for_object_type ?? '', args.for_object_name);
+                if (owning.transport) {
+                    // Mirror the create success path: the owning TR becomes the session
+                    // current-transport so subsequent writes pick it up via the 3-tier
+                    // fallback. It is NOT marked created-this-session — it wasn't.
+                    setCurrentTransport(owning.transport);
+                    // Ownership-aware guidance (I1): "use it" is only honest advice when
+                    // the connected user owns the lock — SAP rejects a foreign user's
+                    // writes under someone else's request unless the owner adds a task.
+                    const me = (ctx.adt.username ?? '').toUpperCase();
+                    const foreignOwner = owning.owner && owning.owner.toUpperCase() !== me ? owning.owner : undefined;
+                    const note = foreignOwner
+                        ? `${args.for_object_name} is locked in ${owning.transport} (owned by ${foreignOwner}) `
+                            + '— SAP only accepts changes under that request; ask the owner to add you as a '
+                            + 'task user. Do NOT create a new transport either way.'
+                        : `${args.for_object_name} is already locked in ${owning.transport} — use it; `
+                            + 'no new transport created. Set as session current transport for subsequent writes.';
+                    ctx.chunkEmitter?.emit('info', note);
+                    return {
+                        content: JSON.stringify({
+                            created: false,
+                            already_locked: true,
+                            transport: owning.transport,
+                            ...(owning.owner ? { owner: owning.owner } : {}),
+                            note,
+                        }),
+                    };
+                }
+                if (owning.candidates.length > 1) {
+                    // Ambiguous ownership — never pick silently (same stance as
+                    // resolveWriteTransport). The create proceeds, but the model is
+                    // told the candidates so it can surface them to the user.
+                    guardNote =
+                        `${args.for_object_name} pieces are locked in ${owning.candidates.length} open `
+                            + `transports (${owning.candidates.join(', ')}) — writes to those pieces will be `
+                            + 'forced into their owning requests; the new transport may stay empty.';
+                }
+                else if (owning.capped) {
+                    // M1: a capped lookup means the E071 row set was truncated — the
+                    // object COULD be locked in rows we never saw. The create proceeds
+                    // (best-effort contract), but never silently.
+                    guardNote =
+                        'owning-transport pre-check unreliable (row cap) — proceeding to create; '
+                            + 'verify in SE03 if unsure.';
+                }
+                // free → normal create flow.
+            }
+            catch (err) {
+                ctx.chunkEmitter?.emit('info', `owning-transport pre-check failed for ${args.for_object_type ?? ''} `
+                    + `${args.for_object_name} — proceeding with create `
+                    + `(${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
         // ── Gate 1: Approval ────────────────────────────────────────────────────
         const verify = await verifyAndSpendApprovalId(args.approval_id, args.description, 'create');
         if (!verify.ok) {
@@ -84,11 +206,34 @@ registerTool({
             // subsequent write calls pick it up via the 3-tier fallback without the LLM
             // needing to pass it explicitly every time.
             setCurrentTransport(result.transportNumber);
+            // Orphan-hint ledger: resolveWriteTransport warns later if this freshly
+            // created TR ends up bypassed by an owning-transport force.
+            markTransportCreatedThisSession(result.transportNumber);
+            // Legacy-caller nudge: the object-context args are how the create guard
+            // learns what the transport is FOR. Surfaced in the RESULT payload (not
+            // just the human stream) so the model learns the contract.
+            const forObjectHint = args.for_object_name
+                ? undefined
+                : 'Tip: pass for_object_type/for_object_name when the transport is for a known '
+                    + 'existing object — the tool then reuses the owning transport instead of '
+                    + 'creating an empty orphan (or check first via sap_transport_for_object).';
+            // Rule 9 description format (D20: "Magic fix" accepted verbatim) —
+            // non-blocking note when the description doesn't follow the session
+            // format. The transport IS created; the user's wording always wins.
+            const rule9Format = /^ABAPForge \d{4}-\d{2}-\d{2}: .+/;
+            const today = new Date().toISOString().slice(0, 10);
+            const rule9Suggestion = rule9Format.test(args.description)
+                ? undefined
+                : `Description does not follow the Rule 9 session format. Suggested: "ABAPForge ${today}: <work summary>". `
+                    + 'Non-blocking — keep the user\'s wording if they chose it deliberately.';
             return {
                 content: JSON.stringify({
                     created: true,
                     transport_number: result.transportNumber,
                     description: result.description,
+                    ...(rule9Suggestion ? { rule9_suggestion: rule9Suggestion } : {}),
+                    ...(guardNote ? { guard_note: guardNote } : {}),
+                    ...(forObjectHint ? { for_object_hint: forObjectHint } : {}),
                     note: 'Use this transport_number in all subsequent sap_set_source / sap_create_object calls this session.',
                 }),
             };
@@ -102,6 +247,80 @@ registerTool({
         }
     },
 });
+// ── sap_transport_for_object ─────────────────────────────────────────────────
+//
+// Read-only E071/E070 owning-transport lookup (AdtClient.transportForObject).
+// First-class way for skills/models to resolve the transport question BEFORE
+// asking the user anything or creating a request.
+registerTool({
+    name: 'sap_transport_for_object',
+    description: 'Check whether an ABAP object (or any of its LIMU pieces) is already locked '
+        + 'in an OPEN transport request (E071/E070 lookup). Read-only, no approval. '
+        + 'Call this BEFORE asking the user about transports or creating one: '
+        + 'locked → use the returned owning transport; not locked → a new or '
+        + 'existing transport may be used.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            object_type: {
+                type: 'string',
+                description: 'ABAP object type (PROG, CLAS, TABL, …)',
+            },
+            object_name: {
+                type: 'string',
+                description: 'ABAP object name (e.g. ZTTT_GAME)',
+            },
+        },
+        required: ['object_type', 'object_name'],
+    },
+    handler: async (args, ctx) => {
+        try {
+            const r = await ctx.adt.transportForObject(args.object_type, args.object_name);
+            let note;
+            if (r.transport) {
+                // 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;
+                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 '
+                        + 'user. Do NOT create a new transport either way.'
+                    : `${args.object_name} is already locked in ${r.transport} — use this `
+                        + 'transport for writes to it; do NOT create a new one.';
+            }
+            else if (r.capped) {
+                note = 'Lookup hit its row cap — the result is unreliable; ownership could not '
+                    + 'be determined. Treat as unknown (write tools will still auto-resolve).';
+            }
+            else if (r.candidates.length > 1) {
+                note = `${args.object_name} pieces are locked in ${r.candidates.length} open `
+                    + `transports (${r.candidates.join(', ')}) — ambiguous; ask the user which to use.`;
+            }
+            else {
+                note = `${args.object_name} is not locked in any open transport — a new or `
+                    + 'existing transport may be used.';
+            }
+            return {
+                content: JSON.stringify({
+                    object_type: args.object_type,
+                    object_name: args.object_name,
+                    transport: r.transport,
+                    owner: r.owner ?? null,
+                    candidates: r.candidates,
+                    capped: r.capped ?? false,
+                    note,
+                }),
+            };
+        }
+        catch (err) {
+            return {
+                content: JSON.stringify({ error: 'transport_for_object_failed', detail: String(err) }),
+                is_error: true,
+            };
+        }
+    },
+});
 // ── sap_transport_list ───────────────────────────────────────────────────────
 //
 // Lists transport requests, optionally filtered by owner and/or status.

package/dist/tools/write-mode.js

@@ -9,12 +9,16 @@
  */
 export const WRITE_TOOLS = new Set([
     'sap_create_object',
+    'sap_create_domain',
+    'sap_create_data_element',
     'sap_set_source',
+    'sap_set_class_include',
     'sap_update_method',
     'sap_delete_object',
     'sap_activate',
     'sap_message_maintain',
     'sap_service_binding_publish',
+    'sap_service_binding_unpublish',
     'sap_transport_release',
 ]);
 export function isWriteTool(name) {