@bridge_gpt/mcp-server 0.2.18 → 0.2.20

package/build/sfcc/writes-system-object.js

@@ -0,0 +1,348 @@
+/**
+ * SFCC system-object metadata write tools (BAPI-583).
+ *
+ * Live OCAPI write surface mirroring `reads-system-object.ts`. Implements six
+ * sandbox-only write operations:
+ *   system_object_attribute_definition_create — PUT   /system_object_definitions/{type}/attribute_definitions/{id}
+ *   system_object_attribute_definition_update — PATCH /system_object_definitions/{type}/attribute_definitions/{id}
+ *   system_object_attribute_group_create      — PUT   /system_object_definitions/{type}/attribute_groups/{id}
+ *   system_object_attribute_group_update      — PATCH /system_object_definitions/{type}/attribute_groups/{id}
+ *   system_object_attribute_assign_to_group   — PUT   /system_object_definitions/{type}/attribute_groups/{group}/attribute_definitions/{def}
+ *   custom_preference_definition_create        — PUT   /system_object_definitions/{SitePreferences|OrganizationPreferences}/attribute_definitions/{id}
+ *
+ * Every handler follows the BAPI-582 foundation write recipe: parse inputs →
+ * `rejectIfNotSandboxForWrite` → build a decoupled payload → `ocapiPut`/`ocapiPatch`
+ * → `formatOcapiWriteToolResult` (which echoes the OCAPI write-grant JSON on 403).
+ */
+import { z } from "zod";
+import { ocapiPut, ocapiPatch } from "./client.js";
+import { withSfccGate } from "./tool-wrapper.js";
+import { rejectIfNotSandboxForWrite } from "./write-guard.js";
+import { formatOcapiWriteToolResult } from "./write-result.js";
+import { objectAttributeDefinitionCreateBodySchema, objectAttributeDefinitionPatchBodySchema, attributeGroupPatchBodySchema, localizedStringSchema, SfccWritePayloadFault, buildObjectAttributeDefinitionCreatePayload, buildObjectAttributeDefinitionPatchPayload, buildAttributeGroupPutPayload, buildAttributeGroupPatchPayload, buildEmptyRelationPayload, } from "./writes-system-object-payloads.js";
+// ---------------------------------------------------------------------------
+// Annotations (destructive OCAPI writes against a developer sandbox)
+// ---------------------------------------------------------------------------
+const WRITE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+/** Safe 400 envelope for a Zod validation failure — no stacks, no raw thrown strings. */
+function zodValidationEnvelope(err) {
+    return textResult(JSON.stringify({
+        error: "VALIDATION_ERROR",
+        status: 400,
+        message: "Invalid SFCC write tool input.",
+        issues: err.issues,
+    }));
+}
+/** Safe 400 envelope for a local payload-shape fault, in OCAPI-fault vocabulary. */
+function payloadFaultEnvelope(fault) {
+    return textResult(JSON.stringify({
+        error: "OCAPI_WRITE_ERROR",
+        status: fault.status,
+        fault: { type: fault.faultType, message: fault.message },
+    }));
+}
+/** Safe 500 envelope — never includes stacks, secrets, headers, or raw error text. */
+function unexpectedEnvelope() {
+    return textResult(JSON.stringify({
+        error: "INTERNAL_ERROR",
+        status: 500,
+        message: "Unexpected SFCC write tool failure",
+    }));
+}
+/** Map a pre-transport error (parse or payload-build) to its safe envelope. */
+function preTransportErrorEnvelope(err) {
+    if (err instanceof z.ZodError)
+        return zodValidationEnvelope(err);
+    if (err instanceof SfccWritePayloadFault)
+        return payloadFaultEnvelope(err);
+    return unexpectedEnvelope();
+}
+// ---------------------------------------------------------------------------
+// OCAPI path builders (every dynamic segment URL-encoded)
+// ---------------------------------------------------------------------------
+function encodedSegment(segment) {
+    return encodeURIComponent(segment);
+}
+function attributeDefinitionPath(objectType, attributeId) {
+    return `/system_object_definitions/${encodedSegment(objectType)}/attribute_definitions/${encodedSegment(attributeId)}`;
+}
+function attributeGroupPath(objectType, groupId) {
+    return `/system_object_definitions/${encodedSegment(objectType)}/attribute_groups/${encodedSegment(groupId)}`;
+}
+function attributeGroupAssignmentPath(objectType, groupId, attributeId) {
+    return (`/system_object_definitions/${encodedSegment(objectType)}` +
+        `/attribute_groups/${encodedSegment(groupId)}` +
+        `/attribute_definitions/${encodedSegment(attributeId)}`);
+}
+/** Map a preference scope to the OCAPI system object that backs preference attributes. */
+function preferenceObjectTypeForScope(scope) {
+    return scope === "site" ? "SitePreferences" : "OrganizationPreferences";
+}
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+/** Optional sandbox instance context. Writes are sandbox-only (see write-guard). */
+const instanceSchema = z
+    .string()
+    .optional()
+    .describe("Sandbox-only: omit (defaults to sandbox) or pass \"sandbox\".");
+const createAttributeDefinitionInput = z.object({
+    object_type: z.string().describe("System object type, e.g. \"Product\"."),
+    attribute_id: z.string().describe("Attribute id (URL id); the body id must match it."),
+    definition: objectAttributeDefinitionCreateBodySchema.describe("OCAPI ObjectAttributeDefinition create body (requires value_type)."),
+    instance: instanceSchema,
+});
+const updateAttributeDefinitionInput = z.object({
+    object_type: z.string().describe("System object type."),
+    attribute_id: z.string().describe("Attribute id (URL id)."),
+    patch: objectAttributeDefinitionPatchBodySchema.describe("Partial ObjectAttributeDefinition body (>=1 field)."),
+    instance: instanceSchema,
+});
+const createAttributeGroupInput = z.object({
+    object_type: z.string().describe("System object type."),
+    group_id: z.string().describe("Attribute group id (URL id)."),
+    display_name: localizedStringSchema.describe("Localized group display name."),
+    internal: z.boolean().describe("Whether the group is internal (BM-only)."),
+    instance: instanceSchema,
+});
+const updateAttributeGroupInput = z.object({
+    object_type: z.string().describe("System object type."),
+    group_id: z.string().describe("Attribute group id (URL id)."),
+    patch: attributeGroupPatchBodySchema.describe("Partial group body (display_name and/or internal; >=1 field)."),
+    instance: instanceSchema,
+});
+const assignAttributeToGroupInput = z.object({
+    object_type: z.string().describe("System object type."),
+    group_id: z.string().describe("Attribute group id."),
+    attribute_id: z.string().describe("Attribute definition id to assign."),
+    instance: instanceSchema,
+});
+const createCustomPreferenceDefinitionInput = z.object({
+    preference_scope: z
+        .enum(["site", "organization"])
+        .describe("site → SitePreferences; organization → OrganizationPreferences."),
+    preference_id: z.string().describe("Preference (attribute) id."),
+    definition: objectAttributeDefinitionCreateBodySchema.describe("OCAPI ObjectAttributeDefinition create body (requires value_type). " +
+        "Set default_value for booleans (else they resolve to null)."),
+    instance: instanceSchema,
+});
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+function buildCreateAttributeDefinitionHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let path;
+        let body;
+        try {
+            const parsed = createAttributeDefinitionInput.parse(args);
+            const guard = rejectIfNotSandboxForWrite(parsed.instance);
+            if (guard)
+                return guard;
+            path = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+            body = buildObjectAttributeDefinitionCreatePayload(parsed.attribute_id, parsed.definition);
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        try {
+            const result = await ocapiPut(path, body, credentials);
+            return formatOcapiWriteToolResult(result, "PUT", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+function buildUpdateAttributeDefinitionHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let path;
+        let body;
+        try {
+            const parsed = updateAttributeDefinitionInput.parse(args);
+            const guard = rejectIfNotSandboxForWrite(parsed.instance);
+            if (guard)
+                return guard;
+            path = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+            body = buildObjectAttributeDefinitionPatchPayload(parsed.attribute_id, parsed.patch);
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        try {
+            // ocapiPatch performs the GET-then-If-Match round trip; 409/412 flow
+            // back through formatOcapiWriteToolResult rather than becoming generic errors.
+            const result = await ocapiPatch(path, body, credentials);
+            return formatOcapiWriteToolResult(result, "PATCH", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+function buildCreateAttributeGroupHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let path;
+        let body;
+        try {
+            const parsed = createAttributeGroupInput.parse(args);
+            const guard = rejectIfNotSandboxForWrite(parsed.instance);
+            if (guard)
+                return guard;
+            path = attributeGroupPath(parsed.object_type, parsed.group_id);
+            body = buildAttributeGroupPutPayload({
+                display_name: parsed.display_name,
+                internal: parsed.internal,
+            });
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        try {
+            const result = await ocapiPut(path, body, credentials);
+            return formatOcapiWriteToolResult(result, "PUT", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+function buildUpdateAttributeGroupHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let path;
+        let body;
+        try {
+            const parsed = updateAttributeGroupInput.parse(args);
+            const guard = rejectIfNotSandboxForWrite(parsed.instance);
+            if (guard)
+                return guard;
+            path = attributeGroupPath(parsed.object_type, parsed.group_id);
+            body = buildAttributeGroupPatchPayload(parsed.patch);
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        try {
+            const result = await ocapiPatch(path, body, credentials);
+            return formatOcapiWriteToolResult(result, "PATCH", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+function buildAssignAttributeToGroupHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let path;
+        try {
+            const parsed = assignAttributeToGroupInput.parse(args);
+            const guard = rejectIfNotSandboxForWrite(parsed.instance);
+            if (guard)
+                return guard;
+            path = attributeGroupAssignmentPath(parsed.object_type, parsed.group_id, parsed.attribute_id);
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        try {
+            const result = await ocapiPut(path, buildEmptyRelationPayload(), credentials);
+            return formatOcapiWriteToolResult(result, "PUT", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+function buildCreateCustomPreferenceDefinitionHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let path;
+        let body;
+        try {
+            const parsed = createCustomPreferenceDefinitionInput.parse(args);
+            const guard = rejectIfNotSandboxForWrite(parsed.instance);
+            if (guard)
+                return guard;
+            const objectType = preferenceObjectTypeForScope(parsed.preference_scope);
+            path = attributeDefinitionPath(objectType, parsed.preference_id);
+            body = buildObjectAttributeDefinitionCreatePayload(parsed.preference_id, parsed.definition);
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        try {
+            const result = await ocapiPut(path, body, credentials);
+            return formatOcapiWriteToolResult(result, "PUT", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+/** Concrete write tool names registered by this module. */
+export const SYSTEM_OBJECT_WRITE_TOOL_NAMES = [
+    "system_object_attribute_definition_create",
+    "system_object_attribute_definition_update",
+    "system_object_attribute_group_create",
+    "system_object_attribute_group_update",
+    "system_object_attribute_assign_to_group",
+    "custom_preference_definition_create",
+];
+/**
+ * Register the six SFCC system-object write tools. Called from the write seam
+ * (`registerSfccWriteTools` in writes.ts) — no direct `register.ts`/`index.ts` edits.
+ */
+export function registerSystemObjectWriteTools(registerTool, deps) {
+    const { gateDeps } = deps;
+    registerTool("system_object_attribute_definition_create", {
+        description: "Create a system-object attribute definition (sandbox-only, destructive). " +
+            "PUT .../attribute_definitions/{id}; body id must equal URL id and system must be false. " +
+            "Returns 201. HTTP 403 echoes the OCAPI write-grant JSON.",
+        inputSchema: createAttributeDefinitionInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildCreateAttributeDefinitionHandler(gateDeps));
+    registerTool("system_object_attribute_definition_update", {
+        description: "Update a system-object attribute definition (sandbox-only, destructive). " +
+            "PATCH .../attribute_definitions/{id} via the ETag GET-then-If-Match round trip. " +
+            "Returns 200; surfaces 409/412 on ETag conflicts. HTTP 403 echoes the write-grant JSON.",
+        inputSchema: updateAttributeDefinitionInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildUpdateAttributeDefinitionHandler(gateDeps));
+    registerTool("system_object_attribute_group_create", {
+        description: "Create a system-object attribute group (sandbox-only, destructive). " +
+            "PUT .../attribute_groups/{id} with a minimal body (display_name + internal). " +
+            "HTTP 403 echoes the OCAPI write-grant JSON.",
+        inputSchema: createAttributeGroupInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildCreateAttributeGroupHandler(gateDeps));
+    registerTool("system_object_attribute_group_update", {
+        description: "Update a system-object attribute group (sandbox-only, destructive). " +
+            "PATCH .../attribute_groups/{id} via the ETag round trip (display_name and/or internal). " +
+            "HTTP 403 echoes the OCAPI write-grant JSON.",
+        inputSchema: updateAttributeGroupInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildUpdateAttributeGroupHandler(gateDeps));
+    registerTool("system_object_attribute_assign_to_group", {
+        description: "Assign an attribute definition to an attribute group (sandbox-only, destructive). " +
+            "PUT .../attribute_groups/{group}/attribute_definitions/{def} with an empty body. " +
+            "HTTP 403 echoes the OCAPI write-grant JSON.",
+        inputSchema: assignAttributeToGroupInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildAssignAttributeToGroupHandler(gateDeps));
+    registerTool("custom_preference_definition_create", {
+        description: "Create a custom preference definition (sandbox-only, destructive). " +
+            "PUT .../{SitePreferences|OrganizationPreferences}/attribute_definitions/{id}. " +
+            "Booleans resolve to null unless default_value is set. HTTP 403 echoes the write-grant JSON.",
+        inputSchema: createCustomPreferenceDefinitionInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildCreateCustomPreferenceDefinitionHandler(gateDeps));
+}

package/build/sfcc/writes.js

@@ -0,0 +1,66 @@
+/**
+ * SFCC write-tool registration aggregator (BAPI-581 / BAPI-582 foundation,
+ * populated by BAPI-584).
+ *
+ * This is the registration seam that write-surface tickets register through.
+ * `register.ts` wires this behind the existing `includeReadTools` SFCC gate, so
+ * the write tools become default-on with the reads without touching
+ * `register.ts` or `index.ts`.
+ *
+ * Each write handler follows the foundation recipe:
+ *   1. Parse inputs.
+ *   2. Call `rejectIfNotSandboxForWrite` (write-guard.ts) BEFORE payload
+ *      construction or any OCAPI mutation.
+ *   3. Build the SFCC payload in a tool-specific payload helper.
+ *   4. Call `ocapiPut` / `ocapiPatch` / `ocapiPatchDirect` (client.ts).
+ *   5. Route the result through `formatOcapiWriteToolResult` (write-result.ts).
+ */
+import { registerSystemObjectWriteTools, SYSTEM_OBJECT_WRITE_TOOL_NAMES, } from "./writes-system-object.js";
+import { registerSfccCustomObjectDefWriteTools, CUSTOM_OBJECT_DEF_WRITE_TOOL_NAMES, } from "./writes-custom-object-def.js";
+import { registerSitePreferenceWriteTools, SITE_PREFERENCE_WRITE_TOOL_NAMES, } from "./writes-site-preference.js";
+// ---------------------------------------------------------------------------
+// Tool name registry
+// ---------------------------------------------------------------------------
+/**
+ * Write tool names registered by this seam (centralized inventory). Extended by
+ * each write-surface ticket — BAPI-583 adds the six system-object write tools,
+ * BAPI-584 adds the custom-object attribute-definition and site-preference value
+ * write tools.
+ */
+export const SFCC_WRITE_TOOL_NAMES = [
+    ...SYSTEM_OBJECT_WRITE_TOOL_NAMES,
+    ...CUSTOM_OBJECT_DEF_WRITE_TOOL_NAMES,
+    ...SITE_PREFERENCE_WRITE_TOOL_NAMES,
+];
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+/**
+ * Register all SFCC write tools through the host's registerTool wrapper.
+ *
+ * Registration is delegated to per-surface write modules. Each write handler
+ * MUST:
+ *   1. Parse inputs.
+ *   2. Call `rejectIfNotSandboxForWrite` (write-guard.ts) BEFORE payload
+ *      construction or any OCAPI mutation.
+ *   3. Build the SFCC payload in a tool-specific payload helper.
+ *   4. Call `ocapiPut` or `ocapiPatch` (client.ts) for transport.
+ *   5. Route the result through `formatOcapiWriteToolResult` (write-result.ts).
+ *
+ * Each handler is additionally call-time gated by `withSfccGate` and
+ * sandbox-guarded, so registering them here (default-on with the reads) does
+ * not weaken the per-call safety model.
+ *
+ * BAPI-583 registers the system-object write surface here; BAPI-584 adds the
+ * custom-object attribute-definition and site-preference value write surfaces
+ * alongside it. Later write-surface tickets add their modules the same way,
+ * without touching `register.ts`/`index.ts`.
+ */
+export function registerSfccWriteTools(registerTool, deps) {
+    // System-object attribute/group definition writes (BAPI-583).
+    registerSystemObjectWriteTools(registerTool, { gateDeps: deps.gateDeps });
+    // Custom-object attribute-definition create/update (PUT / ETag-PATCH).
+    registerSfccCustomObjectDefWriteTools(registerTool, { gateDeps: deps.gateDeps });
+    // Site-preference value set (direct PATCH of a flat c_ map).
+    registerSitePreferenceWriteTools(registerTool, { gateDeps: deps.gateDeps });
+}

package/build/start-tickets-conductor.js

@@ -20,8 +20,8 @@
  * metadata, or the shell command string.
  */
 import { randomBytes } from "node:crypto";
-import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { mergeClaudeSettingsWithCommandHook, detectExistingPreToolUseMatcher, provisionClaudeSettingsForWorktree, DEFAULT_PRE_TOOL_USE_MATCHER, } from "./claude-settings.js";
 import { normalizeDeclaredTouchedFiles } from "./conductor/file-scope-guard.js";
 import { resolveProfiles } from "./mcp-profile.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
@@ -116,6 +116,10 @@ export async function createStartTicketsConductorContext(options, agent, deps) {
         supervisorMode,
         agentName: agent.name,
         cliFile: resolveBinPath("conductor-bin.js"),
+        // Capture the conductor process's Node executable so dispatched workers run
+        // conductor-bin.js under THIS runtime (which owns the ledger), never the
+        // worker's own Node (BAPI-527).
+        conductorNodePath: deps.execPath ?? process.execPath,
         hookBinPath: resolveBinPath("conductor-claude-hook-bin.js"),
     };
     if (options.epic) {
@@ -167,6 +171,10 @@ export function buildConductorWorkerEnv(context, worker, parentEnv) {
         BAPI_CONDUCTOR_GATE_NAME: context.gateName,
         BAPI_CONDUCTOR_SUPERVISOR_MODE: context.supervisorMode,
         BAPI_CONDUCTOR_CLI_FILE: context.cliFile,
+        // BAPI-527: the CLI file + Node runtime are a PAIR. The worker runs
+        // conductor-bin.js under this captured conductor Node for every worker-side
+        // ledger op, so the worker Node never loads better-sqlite3. Non-secret.
+        CONDUCTOR_NODE_PATH: context.conductorNodePath,
     };
     if (context.repoName) {
         env.BAPI_CONDUCTOR_REPO_NAME = context.repoName;
@@ -205,8 +213,10 @@ export const CONDUCTOR_HOOK_LIFECYCLE_EVENTS = [
     "SessionEnd",
     "Notification",
 ];
-/** Broad matcher used for `PreToolUse` when no existing matcher is present. */
-export const DEFAULT_PRE_TOOL_USE_MATCHER = "*";
+// BAPI-534: the broad PreToolUse matcher and generic hook-merge machinery now
+// live in `claude-settings.ts` (shared with the executor deny-layer path).
+// Re-exported so existing importers of this name keep resolving.
+export { DEFAULT_PRE_TOOL_USE_MATCHER };
 /** Shell-quote a path for embedding in a hook command string. */
 function shellQuotePath(value) {
     // Single-quote for POSIX safety; embedded single quotes are escaped. Hook
@@ -224,55 +234,15 @@ export function resolveConductorHookCommand(env, hookBinPath, execPath = process
     }
     return `${shellQuotePath(execPath)} ${shellQuotePath(hookBinPath)}`;
 }
-function asHookEntries(value) {
-    return Array.isArray(value) ? value : [];
-}
-/** Does this event already register `command` as a command hook? */
-function entriesContainCommand(entries, command) {
-    return entries.some((entry) => Array.isArray(entry?.hooks) &&
-        entry.hooks.some((h) => h && h.type === "command" && h.command === command));
-}
 /**
- * Merge conductor lifecycle hooks into an existing Claude settings object
- * WITHOUT removing any existing settings or hooks. Idempotent: re-applying the
- * same command never duplicates an entry. `PreToolUse` is registered only when
- * `enablePreToolUse` is true, mirroring any existing matcher style.
+ * Merge conductor lifecycle hooks into an existing Claude settings object.
+ * BAPI-534: a thin wrapper over the generic {@link mergeClaudeSettingsWithCommandHook}
+ * bound to the conductor lifecycle events — preserving the exported signature and
+ * behavior (idempotent; `PreToolUse` only when `enablePreToolUse`; mirrors any
+ * existing matcher style; never removes existing settings/hooks).
  */
 export function mergeClaudeSettingsWithConductorHook(settings, command, options = {}) {
-    const existingHooks = settings.hooks !== null && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
-        ? settings.hooks
-        : {};
-    const hooks = { ...existingHooks };
-    const events = [...CONDUCTOR_HOOK_LIFECYCLE_EVENTS];
-    if (options.enablePreToolUse) {
-        events.push("PreToolUse");
-    }
-    for (const event of events) {
-        const entries = asHookEntries(hooks[event]);
-        if (entriesContainCommand(entries, command)) {
-            // Idempotent: already registered for this event.
-            hooks[event] = entries;
-            continue;
-        }
-        const newEntry = { hooks: [{ type: "command", command }] };
-        if (event === "PreToolUse") {
-            newEntry.matcher = options.preToolUseMatcher ?? DEFAULT_PRE_TOOL_USE_MATCHER;
-        }
-        hooks[event] = [...entries, newEntry];
-    }
-    return { ...settings, hooks };
-}
-/** Detect an existing PreToolUse matcher to mirror, if any. */
-function detectExistingPreToolUseMatcher(settings) {
-    const hooks = settings.hooks;
-    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks))
-        return undefined;
-    const entries = asHookEntries(hooks.PreToolUse);
-    for (const entry of entries) {
-        if (typeof entry?.matcher === "string")
-            return entry.matcher;
-    }
-    return undefined;
+    return mergeClaudeSettingsWithCommandHook(settings, command, CONDUCTOR_HOOK_LIFECYCLE_EVENTS, options);
 }
 /**
  * Provision the conductor Claude hook into ONE worktree's
@@ -281,52 +251,14 @@ function detectExistingPreToolUseMatcher(settings) {
  * pretty-printed JSON, mirroring any existing PreToolUse matcher.
  */
 export async function provisionConductorHookForWorktree(worktreePath, command, options, deps) {
-    const claudeDir = path.join(worktreePath, ".claude");
-    const settingsPath = path.join(claudeDir, "settings.local.json");
-    let existing = {};
-    let raw = null;
-    try {
-        raw = await deps.readFile(settingsPath);
-    }
-    catch {
-        // Missing file -> treat as empty settings.
-        raw = null;
-    }
-    if (raw !== null) {
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                return {
-                    ok: false,
-                    reason: "malformed",
-                    error: "existing .claude/settings.local.json is not a JSON object",
-                };
-            }
-            existing = parsed;
-        }
-        catch {
-            // Malformed JSON: fail the row rather than clobber the user's file. The
-            // error is generic — it never echoes the file contents.
-            return {
-                ok: false,
-                reason: "malformed",
-                error: "existing .claude/settings.local.json contains invalid JSON",
-            };
-        }
-    }
-    const merged = mergeClaudeSettingsWithConductorHook(existing, command, {
+    // BAPI-534: delegate the malformed-safe read/merge/write to the shared
+    // `provisionClaudeSettingsForWorktree`, supplying a conductor-hook merge
+    // closure. The returned `{ ok, reason, error }` shape is identical to
+    // ConductorHookProvisionResult, so the mapping is a pass-through.
+    return provisionClaudeSettingsForWorktree(worktreePath, (existing) => mergeClaudeSettingsWithConductorHook(existing, command, {
         enablePreToolUse: options.enablePreToolUse,
         preToolUseMatcher: options.preToolUseMatcher ?? detectExistingPreToolUseMatcher(existing),
-    });
-    try {
-        await deps.mkdir(claudeDir, { recursive: true });
-        await deps.writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
-    }
-    catch {
-        // Best-effort: a write/mkdir failure must not block the actual work.
-        return { ok: false, reason: "io", error: "failed to write .claude/settings.local.json" };
-    }
-    return { ok: true };
+    }), deps);
 }
 /**
  * Provision conductor identity across rows. Attaches `runId` to EVERY row (so