@cspeach/cli 0.6.0

package/dist/tools/sap-write.js

@@ -0,0 +1,746 @@
+/**
+ * Write tools with the complete gate pipeline:
+ *
+ *   approval_id verify → snapshot gate → WAL pending → adt.<method> →
+ *   audit log → verify gate (syntax check / activation check) → WAL finalize
+ *
+ * Confirmed AdtClient signatures (sap-client/src/adt-client.ts):
+ *   setSource(type, name, source, transport?)        → Promise<WriteResult>      line 1983
+ *   updateMethod(className, methodName, methodBody, transport?)
+ *                                                    → Promise<WriteResult>      line 2159
+ *   createObject(objtype, name, packageName, description, transport?, extras?)
+ *                                                    → Promise<CreateResult>     line 2245
+ *   deleteObject(type, name, transport?)             → Promise<{status,error?}>  line 2335
+ *   activate(type, name)                             → Promise<ActivationResult> line 2382
+ *   lock(type, name)                                 → Promise<LockResult>       line 1914
+ *   unlock(type, name, lockHandle)                   → Promise<void>             line 1949
+ *   serviceBindingPublish(name)                      → Promise<{status,error?}>  line 2658
+ *   messageMaintain (STUB — not yet in sap-client)
+ *   numberRangeIntervals (STUB — not yet in sap-client)
+ *
+ * auditLog aliased from safety/audit-log.ts#log via sap-client/src/index.ts.
+ */
+import crypto from 'node:crypto';
+import { registerTool } from './index.js';
+import { verifyAndSpendApprovalId } from '../approvals/jwt.js';
+import { autoSnapshot } from './snapshot.js';
+import { verifySyntax, verifyActive } from './verify.js';
+import { appendPending, finalizeToolCall } from '../session/pending.js';
+import { auditLog } from '@cspeach/sap-client';
+import { ERR } from '../errors/codes.js';
+import { interceptUpdateMethod, CancelledByUserError, } from './update-method-intercept.js';
+import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
+import { isSafetyConfirmEnabled } from '../repl/safety-mode-state.js';
+registerTool({
+    name: 'sap_set_source',
+    description: 'Overwrite the full source of an ABAP object. Requires approval_id. '
+        + 'Use for class-definition changes, new methods, or any change not confined to '
+        + 'a single method body. For method-body-only edits use sap_update_method (Rule 7a).',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'ABAP object name' },
+            type: { type: 'string', description: 'ABAP object type (PROG, CLAS, etc.)' },
+            source: { type: 'string', description: 'Full new source (replaces existing)' },
+            transport: { type: 'string', description: 'Transport request number (optional)' },
+            approval_id: { type: 'string', description: 'JWT from request_approval' },
+        },
+        required: ['name', 'type', 'source', 'approval_id'],
+    },
+    handler: async (args, ctx) => {
+        // ── Gate 1: Approval ────────────────────────────────────────────────────
+        const verify = await verifyAndSpendApprovalId(args.approval_id, args.name, 'modify');
+        if (!verify.ok) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
+                is_error: true,
+            };
+        }
+        const toolUseId = crypto.randomUUID();
+        const startedAt = Date.now();
+        // ── Rule 9 conflict warning ──────────────────────────────────────────────
+        // Emit a warning if the LLM passed an explicit transport that differs from
+        // the session current-transport. Prefer LLM intent (explicit caller); this
+        // is informational only and does NOT block the operation.
+        {
+            const sessionTransport = ctx.currentTransport?.get() ?? null;
+            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
+                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
+            }
+        }
+        // ── Gate 2: Snapshot (Rule 7) ────────────────────────────────────────────
+        try {
+            await autoSnapshot(args.name, args.type, ctx.adt);
+        }
+        catch (err) {
+            return {
+                content: JSON.stringify({ error: ERR.SNAPSHOT_FAILED, detail: String(err) }),
+                is_error: true,
+            };
+        }
+        // ── Gate 3: Safety confirmation (Rule 7) ─────────────────────────────────
+        if (isSafetyConfirmEnabled()) {
+            const r = await presentSafetyConfirmation({
+                rule: 'RULE_7_SNAPSHOT_BEFORE_WRITE',
+                op: 'set_source',
+                object: { type: args.type, name: args.name },
+                what_will_happen: 'Overwrites full object source; snapshot is taken first.',
+                rollback_available: true,
+                transport: args.transport ?? ctx.currentTransport?.get() ?? '',
+            });
+            if (!r.confirmed) {
+                return {
+                    content: JSON.stringify({ error: 'cancelled_by_user', reason: r.reason }),
+                    is_error: true,
+                };
+            }
+        }
+        // ── WAL: record pending entry ────────────────────────────────────────────
+        await appendPending(ctx.session, {
+            tool_use_id: toolUseId,
+            tool: 'sap_set_source',
+            args: { name: args.name, type: args.type },
+            started_at: new Date().toISOString(),
+        });
+        // ── Write ────────────────────────────────────────────────────────────────
+        // setSource(type, name, source, transport?) — transport is optional.
+        //
+        // CRITICAL: AdtClient.setSource only THROWS for catastrophic errors (network
+        // down, all retries exhausted). For HTTP 4xx responses (e.g., the second PUT
+        // after 423-recovery still failing) it RETURNS a WriteResult with
+        // writeStatus >= 400 and `error: '...'`. The handler MUST check the return
+        // value — without it, we silently report success on a failed write.
+        // Regression evidence + diagnosis: memory/project_phase3_lite_regression.md.
+        let writeResult;
+        try {
+            writeResult = await ctx.adt.setSource(args.type, args.name, args.source, args.transport);
+        }
+        catch (err) {
+            const errStr = String(err);
+            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({ error: 'write_failed', detail: errStr }),
+                is_error: true,
+            };
+        }
+        if (writeResult.error || (writeResult.writeStatus !== undefined && writeResult.writeStatus >= 400)) {
+            const detail = writeResult.error ?? `Write returned HTTP ${writeResult.writeStatus} but did not throw`;
+            await finalizeToolCall(ctx.session, toolUseId, detail, true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({
+                    error: 'write_failed',
+                    detail,
+                    write_status: writeResult.writeStatus,
+                }),
+                is_error: true,
+            };
+        }
+        await auditLog('setSource', args.type, args.name, 'success', Date.now() - startedAt);
+        // ── Gate 4: Verify — syntax check (Rule 10) ──────────────────────────────
+        const syntax = await verifySyntax(ctx.adt, args.name, args.type);
+        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ written: true, syntax }), false, Date.now() - startedAt);
+        return {
+            content: JSON.stringify({
+                written: true,
+                syntax_ok: syntax.ok,
+                errors: syntax.errors,
+                warnings: syntax.warnings,
+                next_step: syntax.ok
+                    ? 'activation_allowed'
+                    : 'activation_blocked_until_syntax_errors_fixed',
+            }),
+        };
+    },
+});
+// ── sap_update_method ────────────────────────────────────────────────────────
+//
+// Rule 7a: method-body-only edits. Reads current source, replaces the named
+// method block in-memory, then delegates to setSource internally via
+// AdtClient.updateMethod. Does NOT rewrite the class definition.
+//
+// Signature: updateMethod(className, methodName, methodBody, transport?)
+//   methodBody — the lines BETWEEN METHOD x. and ENDMETHOD. (no wrappers)
+registerTool({
+    name: 'sap_update_method',
+    description: 'Replace the body of a single method in an existing class. '
+        + 'Preferred over sap_set_source for method-body-only changes (Rule 7a) — '
+        + 'does NOT rewrite the class definition. '
+        + 'method_source must be the lines between METHOD x. and ENDMETHOD. (no wrappers).',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            class_name: { type: 'string', description: 'ABAP class name (e.g. ZCL_MY_CLASS)' },
+            method_name: { type: 'string', description: 'Method name (e.g. DO_WORK or IF_FOO~BAR)' },
+            method_source: { type: 'string', description: 'Lines between METHOD x. and ENDMETHOD. (no wrapper lines)' },
+            transport: { type: 'string', description: 'Transport request number (optional)' },
+            approval_id: { type: 'string', description: 'JWT from request_approval' },
+        },
+        required: ['class_name', 'method_name', 'method_source', 'approval_id'],
+    },
+    handler: async (args, ctx) => {
+        // ── Gate 1: Approval ────────────────────────────────────────────────────
+        const verify = await verifyAndSpendApprovalId(args.approval_id, args.class_name, 'modify');
+        if (!verify.ok) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
+                is_error: true,
+            };
+        }
+        const toolUseId = crypto.randomUUID();
+        const startedAt = Date.now();
+        // ── Rule 9 conflict warning ──────────────────────────────────────────────
+        // Emit a warning if the LLM passed an explicit transport that differs from
+        // the session current-transport. Prefer LLM intent (explicit caller); this
+        // is informational only and does NOT block the operation.
+        {
+            const sessionTransport = ctx.currentTransport?.get() ?? null;
+            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
+                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
+            }
+        }
+        // ── Gate 2: Snapshot (Rule 7) ────────────────────────────────────────────
+        try {
+            await autoSnapshot(args.class_name, 'CLAS', ctx.adt);
+        }
+        catch (err) {
+            return {
+                content: JSON.stringify({ error: ERR.SNAPSHOT_FAILED, detail: String(err) }),
+                is_error: true,
+            };
+        }
+        // ── Gate 3: Diff preview & confirmation (Rule 7a) ────────────────────────
+        if (!ctx.previewHook) {
+            return {
+                content: JSON.stringify({
+                    error: 'preview_hook_unavailable',
+                    detail: 'cannot confirm method body changes in this execution context',
+                }),
+                is_error: true,
+            };
+        }
+        const minimal = {
+            getSource: ({ type, name }) => ctx.adt.getSource(type, name),
+        };
+        const call = {
+            className: args.class_name,
+            methodName: args.method_name,
+            methodSource: args.method_source,
+            transport: args.transport ?? ctx.currentTransport?.get() ?? '',
+        };
+        try {
+            await interceptUpdateMethod(minimal, call, ctx.previewHook);
+        }
+        catch (err) {
+            if (err instanceof CancelledByUserError) {
+                return {
+                    content: JSON.stringify({ error: 'cancelled_by_user', detail: err.message }),
+                    is_error: true,
+                };
+            }
+            return {
+                content: JSON.stringify({ error: 'preview_failed', detail: String(err) }),
+                is_error: true,
+            };
+        }
+        // ── WAL: record pending entry ────────────────────────────────────────────
+        await appendPending(ctx.session, {
+            tool_use_id: toolUseId,
+            tool: 'sap_update_method',
+            args: { class_name: args.class_name, method_name: args.method_name },
+            started_at: new Date().toISOString(),
+        });
+        // ── Write ────────────────────────────────────────────────────────────────
+        // updateMethod(className, methodName, methodBody, transport?). Same return
+        // semantics as setSource — RETURNS a WriteResult on HTTP-level failure
+        // rather than throwing. Must check writeStatus / error on the return value.
+        let updateResult;
+        try {
+            updateResult = await ctx.adt.updateMethod(args.class_name, args.method_name, args.method_source, args.transport);
+        }
+        catch (err) {
+            const errStr = String(err);
+            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({ error: 'update_failed', detail: errStr }),
+                is_error: true,
+            };
+        }
+        if (updateResult.error || (updateResult.writeStatus !== undefined && updateResult.writeStatus >= 400)) {
+            const detail = updateResult.error ?? `Update returned HTTP ${updateResult.writeStatus} but did not throw`;
+            await finalizeToolCall(ctx.session, toolUseId, detail, true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({
+                    error: 'update_failed',
+                    detail,
+                    write_status: updateResult.writeStatus,
+                }),
+                is_error: true,
+            };
+        }
+        await auditLog('updateMethod', 'CLAS', args.class_name, 'success', Date.now() - startedAt, `method=${args.method_name}`);
+        // ── Gate 4: Verify — syntax check (Rule 10) ──────────────────────────────
+        const syntax = await verifySyntax(ctx.adt, args.class_name, 'CLAS');
+        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ updated: true, syntax }), false, Date.now() - startedAt);
+        return {
+            content: JSON.stringify({
+                updated: true,
+                syntax_ok: syntax.ok,
+                errors: syntax.errors,
+                warnings: syntax.warnings,
+                next_step: syntax.ok
+                    ? 'activation_allowed'
+                    : 'activation_blocked_until_syntax_errors_fixed',
+            }),
+        };
+    },
+});
+// ── sap_delete_object ────────────────────────────────────────────────────────
+//
+// Signature: deleteObject(type, name, transport?) → { status: number; error?: string }
+// AdtClient auto-snapshots before delete (Rule 7 built-in), but we also call
+// autoSnapshot here for belt-and-suspenders consistency with the CLI gate model.
+registerTool({
+    name: 'sap_delete_object',
+    description: 'Delete an ABAP object. Requires approval_id. '
+        + 'A snapshot is taken automatically before deletion. '
+        + 'Post-check: confirms the object no longer exists.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'ABAP object name' },
+            type: { type: 'string', description: 'ABAP object type (PROG, CLAS, etc.)' },
+            transport: { type: 'string', description: 'Transport request number (optional)' },
+            approval_id: { type: 'string', description: 'JWT from request_approval' },
+        },
+        required: ['name', 'type', 'approval_id'],
+    },
+    handler: async (args, ctx) => {
+        // ── Gate 1: Approval ────────────────────────────────────────────────────
+        const verify = await verifyAndSpendApprovalId(args.approval_id, args.name, 'delete');
+        if (!verify.ok) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
+                is_error: true,
+            };
+        }
+        const toolUseId = crypto.randomUUID();
+        const startedAt = Date.now();
+        // ── Rule 9 conflict warning ──────────────────────────────────────────────
+        // Emit a warning if the LLM passed an explicit transport that differs from
+        // the session current-transport. Prefer LLM intent (explicit caller); this
+        // is informational only and does NOT block the operation.
+        {
+            const sessionTransport = ctx.currentTransport?.get() ?? null;
+            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
+                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
+            }
+        }
+        // ── Gate 2: Snapshot (Rule 7) — best-effort, object may not have source ──
+        try {
+            await autoSnapshot(args.name, args.type, ctx.adt);
+        }
+        catch {
+            // Silently ignore — object may be a shell with no readable source.
+        }
+        // ── Gate 3: Safety confirmation (Rule 7 — delete is irreversible-ish) ────
+        if (isSafetyConfirmEnabled()) {
+            const r = await presentSafetyConfirmation({
+                rule: 'RULE_7_SNAPSHOT_BEFORE_WRITE',
+                op: 'delete_object',
+                object: { type: args.type, name: args.name },
+                what_will_happen: 'Deletes object from SAP; snapshot is taken first; recovery via sap_snapshot_read + sap_set_source (LLM composes the rollback).',
+                rollback_available: true,
+                transport: args.transport ?? ctx.currentTransport?.get() ?? '',
+            });
+            if (!r.confirmed) {
+                return {
+                    content: JSON.stringify({ error: 'cancelled_by_user', reason: r.reason }),
+                    is_error: true,
+                };
+            }
+        }
+        // ── WAL: record pending entry ────────────────────────────────────────────
+        await appendPending(ctx.session, {
+            tool_use_id: toolUseId,
+            tool: 'sap_delete_object',
+            args: { name: args.name, type: args.type },
+            started_at: new Date().toISOString(),
+        });
+        // ── Delete ───────────────────────────────────────────────────────────────
+        // deleteObject(type, name, transport?) → { status: number; error?: string }.
+        // Same return semantics as setSource — RETURNS rather than throws on HTTP
+        // 4xx. Must check status / error on the return value.
+        let deleteResult;
+        try {
+            deleteResult = await ctx.adt.deleteObject(args.type, args.name, args.transport);
+        }
+        catch (err) {
+            const errStr = String(err);
+            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({ error: 'delete_failed', detail: errStr }),
+                is_error: true,
+            };
+        }
+        if (deleteResult.error || (deleteResult.status !== undefined && deleteResult.status >= 400)) {
+            const detail = deleteResult.error ?? `Delete returned HTTP ${deleteResult.status} but did not throw`;
+            await finalizeToolCall(ctx.session, toolUseId, detail, true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({
+                    error: 'delete_failed',
+                    detail,
+                    status: deleteResult.status,
+                }),
+                is_error: true,
+            };
+        }
+        await auditLog('deleteObject', args.type, args.name, 'success', Date.now() - startedAt);
+        // ── Post-check: object should no longer exist ────────────────────────────
+        const stillExists = await ctx.adt.objectStructure(args.type, args.name)
+            .then(() => true)
+            .catch(() => false);
+        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ deleted: !stillExists }), false, Date.now() - startedAt);
+        return {
+            content: JSON.stringify({ deleted: !stillExists, still_exists: stillExists }),
+        };
+    },
+});
+// ── sap_create_object ────────────────────────────────────────────────────────
+//
+// Signature: createObject(objtype, name, packageName, description, transport?, extras?)
+//   → Promise<CreateResult>
+// NOTE: arg order differs from the plan snippet — packageName comes before description.
+// No snapshot needed: new object has no prior source.
+registerTool({
+    name: 'sap_create_object',
+    description: 'Create a new ABAP object shell. '
+        + 'Requires approval_id. No snapshot needed (new object). '
+        + 'Write source separately via sap_set_source, then call sap_activate.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'ABAP object name' },
+            type: { type: 'string', description: 'ABAP object type (PROG, CLAS, INTF, DDLS, etc.)' },
+            package: { type: 'string', description: 'Development package (Z*/Y*)' },
+            description: { type: 'string', description: 'Short description' },
+            transport: { type: 'string', description: 'Target transport (optional — required for workbench packages)' },
+            approval_id: { type: 'string', description: 'JWT from request_approval' },
+        },
+        required: ['name', 'type', 'package', 'description', 'approval_id'],
+    },
+    handler: async (args, ctx) => {
+        // ── Gate 1: Approval ────────────────────────────────────────────────────
+        const verify = await verifyAndSpendApprovalId(args.approval_id, args.name, 'create');
+        if (!verify.ok) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
+                is_error: true,
+            };
+        }
+        const toolUseId = crypto.randomUUID();
+        const startedAt = Date.now();
+        // No snapshot — new object has no prior source.
+        // ── Rule 9 conflict warning + 3-tier transport fallback ──────────────────
+        // Emit a warning if the LLM passed an explicit transport that differs from
+        // the session current-transport. Prefer LLM intent (explicit caller); this
+        // is informational only and does NOT block the operation.
+        {
+            const sessionTransport = ctx.currentTransport?.get() ?? null;
+            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
+                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
+            }
+        }
+        // 3-tier fallback: explicit arg → session current-transport → undefined
+        const effectiveTransport = args.transport ?? ctx.currentTransport?.get() ?? undefined;
+        // ── WAL: record pending entry ────────────────────────────────────────────
+        await appendPending(ctx.session, {
+            tool_use_id: toolUseId,
+            tool: 'sap_create_object',
+            args: { name: args.name, type: args.type, package: args.package },
+            started_at: new Date().toISOString(),
+        });
+        // ── Create ───────────────────────────────────────────────────────────────
+        // createObject(objtype, name, packageName, description, transport?, extras?)
+        let result;
+        try {
+            result = await ctx.adt.createObject(args.type, args.name, args.package, args.description, effectiveTransport);
+            await auditLog('createObject', args.type, args.name, 'success', Date.now() - startedAt);
+        }
+        catch (err) {
+            const errStr = String(err);
+            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({ error: 'create_failed', detail: errStr }),
+                is_error: true,
+            };
+        }
+        if (result.status !== 'created') {
+            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({ error: 'create_failed', detail: result.error }),
+                is_error: true,
+            };
+        }
+        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), false, Date.now() - startedAt);
+        return {
+            content: JSON.stringify({
+                created: true,
+                object: result.objectName,
+                type: result.objectType,
+                package: result.packageName,
+                next_step: 'write_source_via_sap_set_source_then_activate',
+            }),
+        };
+    },
+});
+// ── sap_activate ─────────────────────────────────────────────────────────────
+//
+// Signature: activate(type, name) → Promise<ActivationResult>
+//   ActivationResult { success, hasErrors, hasWarnings, messages[] }
+//
+// AdtClient activates one object per call. This tool accepts a batch (array)
+// and calls activate() per object, collecting results. Post-check via
+// verifyActive() inspects the inactive-objects list.
+registerTool({
+    name: 'sap_activate',
+    description: 'Activate one or more ABAP objects. Required after sap_set_source / '
+        + 'sap_update_method / sap_create_object (Rule 10). '
+        + 'Post-check: objects must no longer appear in the inactive-objects list.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            objects: {
+                type: 'array',
+                description: 'List of objects to activate',
+                items: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string' },
+                        type: { type: 'string' },
+                    },
+                    required: ['name', 'type'],
+                },
+            },
+            approval_id: {
+                type: 'string',
+                description: 'JWT from request_approval — one approval covers the whole batch',
+            },
+        },
+        required: ['objects', 'approval_id'],
+    },
+    handler: async (args, ctx) => {
+        if (!Array.isArray(args.objects) || args.objects.length === 0) {
+            return { content: JSON.stringify({ activated: [], note: 'empty_activation_batch' }) };
+        }
+        // ── Gate 1: Approval (verify against primary object) ────────────────────
+        const primary = args.objects[0];
+        const verify = await verifyAndSpendApprovalId(args.approval_id, primary.name, 'activate');
+        if (!verify.ok) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
+                is_error: true,
+            };
+        }
+        const toolUseId = crypto.randomUUID();
+        const startedAt = Date.now();
+        // ── WAL: record pending entry ────────────────────────────────────────────
+        await appendPending(ctx.session, {
+            tool_use_id: toolUseId,
+            tool: 'sap_activate',
+            args: { objects: args.objects },
+            started_at: new Date().toISOString(),
+        });
+        // ── Activate each object, collect per-object results ─────────────────────
+        // activate(type, name) — one call per object; no batch API in AdtClient.
+        const activationResults = [];
+        let anyError = false;
+        for (const obj of args.objects) {
+            try {
+                const res = await ctx.adt.activate(obj.type, obj.name);
+                await auditLog('activate', obj.type, obj.name, res.success ? 'success' : 'error', Date.now() - startedAt);
+                activationResults.push({ name: obj.name, type: obj.type, success: res.success, messages: res.messages });
+                if (!res.success)
+                    anyError = true;
+            }
+            catch (err) {
+                activationResults.push({ name: obj.name, type: obj.type, success: false, messages: [String(err)] });
+                anyError = true;
+            }
+        }
+        // ── Post-check: verify none of the objects remain inactive ───────────────
+        // 2026-05-01: verifyActive now returns { active, verifyError? }. If the
+        // inactive-objects probe itself failed, we MUST surface that as
+        // "unverified" — not silently treat it as "activated". This was the
+        // root cause of the "told user activate succeeded when program was
+        // still inactive with syntax errors" incident.
+        const stillInactive = [];
+        const unverifiable = [];
+        for (const obj of args.objects) {
+            const v = await verifyActive(ctx.adt, obj.name, obj.type);
+            if (v.verifyError) {
+                unverifiable.push({ object: `${obj.type}/${obj.name}`, reason: v.verifyError });
+            }
+            else if (!v.active) {
+                stillInactive.push(`${obj.type}/${obj.name}`);
+            }
+        }
+        const overallSuccess = !anyError && stillInactive.length === 0 && unverifiable.length === 0;
+        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ overallSuccess, activationResults, stillInactive, unverifiable }), anyError, Date.now() - startedAt);
+        let note;
+        if (stillInactive.length > 0) {
+            note = 'Some objects remain inactive — check activation_results for error messages';
+        }
+        else if (unverifiable.length > 0) {
+            note = 'Activation reported success but verification failed — DO NOT claim activation succeeded. ' +
+                'Re-run sap_inactive_objects manually to confirm state. See `unverifiable` for the underlying error.';
+        }
+        // 2026-05-01: when activation fails, return `is_error: true` so the
+        // dispatch layer (tool-dispatch.ts) does NOT credit this call as a
+        // successful write op. Without this, Rule 8 counts a failed activate
+        // as if it had run, inflating the "batch in progress" count and
+        // confusing the user about how many real writes have happened.
+        return {
+            content: JSON.stringify({
+                success: overallSuccess,
+                activation_results: activationResults,
+                still_inactive: stillInactive,
+                unverifiable,
+                note,
+            }),
+            is_error: !overallSuccess,
+        };
+    },
+});
+// ── sap_lock ──────────────────────────────────────────────────────────────────
+//
+// Lightweight lock primitive — does NOT go through the approval / WAL / verify
+// pipeline. Used to acquire an edit lock on an object before a manual PUT.
+// Signature: lock(type, name) → Promise<LockResult>
+//   LockResult { lockHandle: string; status: 'locked' | 'lock_failed' }
+registerTool({
+    name: 'sap_lock',
+    description: 'RARELY needed. Returns a lock handle but other write tools cannot consume it — sap_set_source / sap_update_method / sap_delete_object each acquire their OWN lock internally. Calling sap_lock as a recovery step after a write failure CREATES A STALE LOCK that blocks the next write attempt; do not do that. Only call this when you need to inspect lock state or hold a lock for a coordinated multi-step ABAP workbench operation outside of CSPeach.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            type: { type: 'string', description: 'ABAP object type (PROG, CLAS, etc.)' },
+            name: { type: 'string', description: 'ABAP object name' },
+        },
+        required: ['type', 'name'],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.lock(args.type, args.name);
+        return { content: JSON.stringify(result) };
+    },
+});
+// ── sap_unlock ────────────────────────────────────────────────────────────────
+//
+// Release an ADT edit lock previously acquired with sap_lock.
+// Signature: unlock(type, name, lockHandle) → Promise<void>
+registerTool({
+    name: 'sap_unlock',
+    description: 'Release an ADT edit lock on an ABAP object using the lockHandle from sap_lock.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            type: { type: 'string', description: 'ABAP object type (PROG, CLAS, etc.)' },
+            name: { type: 'string', description: 'ABAP object name' },
+            lockHandle: { type: 'string', description: 'Lock handle returned by sap_lock' },
+        },
+        required: ['type', 'name', 'lockHandle'],
+    },
+    handler: async (args, ctx) => {
+        await ctx.adt.unlock(args.type, args.name, args.lockHandle);
+        return { content: JSON.stringify({ status: 'ok' }) };
+    },
+});
+// ── sap_service_binding_publish ───────────────────────────────────────────────
+//
+// Publish a service binding so it is reachable via OData.
+// Signature: serviceBindingPublish(name) → Promise<{ status: number; error?: string }>
+registerTool({
+    name: 'sap_service_binding_publish',
+    description: 'Publish an ADT service binding so its OData endpoint becomes active and reachable.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Service binding name (e.g. ZSALES_UI_V4)' },
+        },
+        required: ['name'],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.serviceBindingPublish(args.name);
+        return { content: JSON.stringify(result) };
+    },
+});
+// ── sap_message_maintain (STUB) ───────────────────────────────────────────────
+//
+// STUB — MSAG message-class maintenance requires XML message-class-format
+// parsing not yet implemented in @cspeach/sap-client.
+registerTool({
+    name: 'sap_message_maintain',
+    description: 'STUB — not currently implemented; do not call. '
+        + 'Maintaining MSAG message-class entries via ADT requires XML message-class-format '
+        + 'parsing not yet implemented in @cspeach/sap-client.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            messageClass: { type: 'string', description: 'Message class name (e.g. ZMSAG_FOO)' },
+            messageNumber: { type: 'string', description: 'Three-digit message number (e.g. 001)' },
+            messageText: { type: 'string', description: 'Message text (up to 73 characters)' },
+            messageType: { type: 'string', description: 'Message type: I, W, E, A, X, S' },
+        },
+        required: ['messageClass', 'messageNumber', 'messageText'],
+    },
+    handler: async (_args, _ctx) => {
+        return {
+            content: JSON.stringify({
+                error: 'not_implemented',
+                detail: 'MSAG message maintenance via ADT requires XML message-class-format parsing not yet implemented in @cspeach/sap-client',
+            }),
+            is_error: true,
+        };
+    },
+});
+// ── sap_number_range_intervals (STUB) ─────────────────────────────────────────
+//
+// STUB — NROB interval write requires NR-object XML format not yet implemented
+// in @cspeach/sap-client.
+registerTool({
+    name: 'sap_number_range_intervals',
+    description: 'STUB — not currently implemented; do not call. '
+        + 'Writing NROB number-range intervals via ADT requires NR-object XML format '
+        + 'not yet implemented in @cspeach/sap-client.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            nrObject: { type: 'string', description: 'Number range object name' },
+            subobject: { type: 'string', description: 'Subobject (leave blank for main object)' },
+            intervals: {
+                type: 'array',
+                description: 'Array of interval definitions',
+                items: { type: 'object' },
+            },
+        },
+        required: ['nrObject'],
+    },
+    handler: async (_args, _ctx) => {
+        return {
+            content: JSON.stringify({
+                error: 'not_implemented',
+                detail: 'NROB interval write via ADT requires NR-object XML format not yet implemented in @cspeach/sap-client',
+            }),
+            is_error: true,
+        };
+    },
+});