@ken-jo/agent-connector 0.4.6 → 0.4.8

package/dist/chunk-H53QZQJI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/claude-code/wire.ts"],"sourcesContent":["/**\n * adapters/claude-code/wire — Claude Code hook wire protocol.\n *\n * Claude Code pipes a JSON object to a hook command on stdin and reads a JSON\n * object (or empty) from stdout, interpreting the exit code as well. This module\n * captures the exact stdin shape and the canonical reply shape so the adapter's\n * parse/format methods are a single source of truth.\n *\n * Stdin (documented Claude Code hook input):\n *   {\n *     session_id, transcript_path, cwd, hook_event_name,\n *     tool_name, tool_input, tool_response,            // tool events\n *     permission_suggestions,                          // PermissionRequest\n *     tool_use_id, error, is_interrupt, duration_ms,   // PostToolUseFailure\n *     agent_id, agent_type,                            // SubagentStart/Stop\n *     agent_transcript_path, last_assistant_message,   // SubagentStop\n *     source,                                          // SessionStart\n *     reason,                                          // SessionEnd\n *     prompt,                                          // UserPromptSubmit\n *     trigger,                                         // PreCompact\n *     stop_hook_active,                                // Stop / SubagentStop\n *     message                                          // Notification\n *   }\n *\n * Stdout (canonical reply): a `hookSpecificOutput` object keyed by\n * `hookEventName`, carrying `permissionDecision` (allow|deny|ask) +\n * `permissionDecisionReason`, `additionalContext`, and (PreToolUse)\n * `updatedInput`; PermissionRequest instead takes a nested\n * `decision: { behavior: \"allow\"|\"deny\", ... }`; Stop-class blocks\n * (Stop / SubagentStop / UserPromptSubmit / PostToolUse) take the TOP-LEVEL\n * `{\"decision\":\"block\",\"reason\"}`. Exit 0 = proceed; the JSON refines the\n * decision.\n */\n\nimport type { SessionStartEvent } from \"../../core/types.js\";\n\n/** Canonical Claude Code hook event names (the values of `hook_event_name`). */\nexport const CLAUDE_HOOK_EVENTS = [\n  \"PreToolUse\",\n  \"PostToolUse\",\n  \"PreCompact\",\n  \"SessionStart\",\n  \"SessionEnd\",\n  \"UserPromptSubmit\",\n  \"Stop\",\n  \"Notification\",\n  \"PermissionRequest\",\n  \"PostToolUseFailure\",\n  \"SubagentStart\",\n  \"SubagentStop\",\n] as const;\n\nexport type ClaudeHookEvent = (typeof CLAUDE_HOOK_EVENTS)[number];\n\n/**\n * Raw Claude Code hook stdin payload. Every field is optional — a given event\n * only populates the subset relevant to it. `connector` is NOT a Claude field;\n * it is threaded in by the universal entrypoint so parseEvent can recover the\n * connector id (the home binary passes `--connector <id>` and may inject it).\n */\nexport interface ClaudeWireInput {\n  session_id?: string;\n  transcript_path?: string;\n  cwd?: string;\n  hook_event_name?: string;\n\n  // tool events\n  tool_name?: string;\n  tool_input?: Record<string, unknown>;\n  /** PostToolUse result payload (string or structured). */\n  tool_response?: unknown;\n\n  // PermissionRequest — permission-update entries the dialog would offer.\n  // NOTE: the docs explicitly state PermissionRequest has NO tool_use_id.\n  permission_suggestions?: unknown[];\n\n  // PostToolUseFailure\n  tool_use_id?: string;\n  error?: string;\n  is_interrupt?: boolean;\n  duration_ms?: number;\n\n  // SubagentStart / SubagentStop — agent_type is unreliable on SubagentStop\n  // (the SDK may not populate it); treat both as optional everywhere.\n  agent_id?: string;\n  agent_type?: string;\n  // SubagentStop — the subagent's OWN transcript (transcript_path stays the\n  // parent session's) + the text of its final response.\n  agent_transcript_path?: string;\n  last_assistant_message?: string;\n\n  // SessionStart\n  source?: string;\n  // SessionEnd\n  reason?: string;\n  // UserPromptSubmit\n  prompt?: string;\n  // PreCompact\n  trigger?: string;\n  // Stop / SubagentStop\n  stop_hook_active?: boolean;\n  // Notification\n  message?: string;\n\n  /** Injected by the entrypoint so the runtime knows which connector to dispatch. */\n  connector?: string;\n}\n\n/**\n * Extract a stable session id from a Claude wire payload.\n * Priority mirrors the proven adapter: transcript UUID > session_id > \"\".\n * (The framework's normalized event uses \"\" when no id is available, per\n * core/types BaseEvent.sessionId docstring — no ppid fabrication here.)\n */\nexport function extractSessionId(input: ClaudeWireInput): string {\n  if (typeof input.transcript_path === \"string\") {\n    const m = input.transcript_path.match(/([a-f0-9-]{36})\\.jsonl$/);\n    if (m && m[1]) return m[1];\n  }\n  if (typeof input.session_id === \"string\" && input.session_id !== \"\") {\n    return input.session_id;\n  }\n  return \"\";\n}\n\n/** Coerce a Claude PostToolUse `tool_response` into a string for the normalized event. */\nexport function toolResponseToString(value: unknown): string | undefined {\n  if (value == null) return undefined;\n  if (typeof value === \"string\") return value;\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/** Map a host's raw session-start \"source\" to the canonical SessionStart source. */\nexport function normalizeSessionSource(source: string | undefined): SessionStartEvent[\"source\"] {\n  switch (source) {\n    case \"compact\":\n      return \"compact\";\n    case \"resume\":\n      return \"resume\";\n    case \"clear\":\n      return \"clear\";\n    default:\n      return \"startup\";\n  }\n}\n"],"mappings":";;;AAkHO,SAAS,iBAAiB,OAAgC;AAC/D,MAAI,OAAO,MAAM,oBAAoB,UAAU;AAC7C,UAAM,IAAI,MAAM,gBAAgB,MAAM,yBAAyB;AAC/D,QAAI,KAAK,EAAE,CAAC,EAAG,QAAO,EAAE,CAAC;AAAA,EAC3B;AACA,MAAI,OAAO,MAAM,eAAe,YAAY,MAAM,eAAe,IAAI;AACnE,WAAO,MAAM;AAAA,EACf;AACA,SAAO;AACT;AAGO,SAAS,qBAAqB,OAAoC;AACvE,MAAI,SAAS,KAAM,QAAO;AAC1B,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI;AACF,WAAO,KAAK,UAAU,KAAK;AAAA,EAC7B,QAAQ;AACN,WAAO,OAAO,KAAK;AAAA,EACrB;AACF;AAGO,SAAS,uBAAuB,QAAyD;AAC9F,UAAQ,QAAQ;AAAA,IACd,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;","names":[]}

package/dist/{chunk-DCK5FADX.js → chunk-HOE2MN36.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   REGISTERED_PLATFORM_IDS
-} from "./chunk-BMD7ANKF.js";
+} from "./chunk-XQUUNAGC.js";
 import {
   CONFIG_PATCH_SEGMENT_RE,
   configPatchNamespaceViolation,
@@ -495,4 +495,4 @@ export {
   defineConfigPatch,
   defineNativeHook
 };
-//# sourceMappingURL=chunk-DCK5FADX.js.map
+//# sourceMappingURL=chunk-HOE2MN36.js.map

package/dist/{chunk-7L6ITC4T.js → chunk-IEGR4TP3.js}

@@ -9,13 +9,16 @@ ${stringifyYaml(frontmatter)}---
 ${body}
 `;
 }
-function renderCommandMd(cmd) {
+function renderCommandMd(cmd, opts = {}) {
+  const { includeToolsAndModel = true } = opts;
   const frontmatter = {};
   if (cmd.description !== void 0) frontmatter.description = cmd.description;
   if (cmd.argumentHint !== void 0) frontmatter["argument-hint"] = cmd.argumentHint;
-  const allow = cmd.tools?.allow;
-  if (allow && allow.length > 0) frontmatter["allowed-tools"] = allow.join(", ");
-  if (cmd.model !== void 0) frontmatter.model = cmd.model;
+  if (includeToolsAndModel) {
+    const allow = cmd.tools?.allow;
+    if (allow && allow.length > 0) frontmatter["allowed-tools"] = allow.join(", ");
+    if (cmd.model !== void 0) frontmatter.model = cmd.model;
+  }
   if (cmd.extra) Object.assign(frontmatter, cmd.extra);
   return renderFrontmatterMd(frontmatter, cmd.prompt);
 }
@@ -44,11 +47,24 @@ function renderSubagentMd(agent) {
   if (agent.extra) Object.assign(frontmatter, agent.extra);
   return renderFrontmatterMd(frontmatter, agent.prompt);
 }
+function renderOpenCodeSubagentMd(agent) {
+  const frontmatter = {
+    description: agent.description,
+    mode: "subagent"
+  };
+  if (agent.model !== void 0) frontmatter.model = agent.model;
+  if (agent.readonly === true) {
+    frontmatter.permission = { edit: "deny", bash: "deny" };
+  }
+  if (agent.extra) Object.assign(frontmatter, agent.extra);
+  return renderFrontmatterMd(frontmatter, agent.prompt);
+}
 
 export {
   renderFrontmatterMd,
   renderCommandMd,
   renderSkillMd,
-  renderSubagentMd
+  renderSubagentMd,
+  renderOpenCodeSubagentMd
 };
-//# sourceMappingURL=chunk-7L6ITC4T.js.map
+//# sourceMappingURL=chunk-IEGR4TP3.js.map

package/dist/chunk-IEGR4TP3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/claude-code/render.ts"],"sourcesContent":["/**\n * adapters/claude-code/render — shared content-surface renderers.\n *\n * The single source of truth for how a connector's commands / skills / subagents\n * are serialized into Claude Code's native `md + YAML-frontmatter` documents.\n * BOTH the live claude-code adapter (which writes into ~/.claude or .claude when\n * installing) AND `core/package` (which emits a marketplace-installable plugin\n * bundle) import these so the two paths produce BYTE-IDENTICAL output — there is\n * no second, subtly-different copy to drift.\n *\n * The frontmatter serializer reuses the `yaml` package (the same serializer\n * core/yaml and BaseAdapter.renderFrontmatterMd use): a `---` fence, the YAML\n * block, a closing `---`, a blank line, then the markdown body and a trailing\n * newline.\n */\n\nimport { stringify as stringifyYaml } from \"yaml\";\n\nimport type { CommandDef, SkillDef, SubagentDef } from \"../../core/types.js\";\n\n/**\n * Render a YAML-frontmatter + markdown body document:\n *   \"---\\n\" + <yaml> + \"---\\n\\n\" + <body> + \"\\n\".\n * Identical to BaseAdapter.renderFrontmatterMd (which now delegates here).\n */\nexport function renderFrontmatterMd(\n  frontmatter: Record<string, unknown>,\n  body: string,\n): string {\n  return `---\\n${stringifyYaml(frontmatter)}---\\n\\n${body}\\n`;\n}\n\n/**\n * Render a command to md+frontmatter\n * (description, argument-hint, allowed-tools, model + verbatim extra).\n *\n * `opts.includeToolsAndModel` (default `true`) controls the allowed-tools and\n * model insertions. Hosts whose command frontmatter is only\n * (description, argument-hint + verbatim extra) — i.e. they have no native\n * allowed-tools/model keys — pass `{ includeToolsAndModel: false }` to suppress\n * both; the default reproduces the full shape byte-for-byte.\n */\nexport function renderCommandMd(\n  cmd: CommandDef,\n  opts: { includeToolsAndModel?: boolean } = {},\n): string {\n  const { includeToolsAndModel = true } = opts;\n  const frontmatter: Record<string, unknown> = {};\n  if (cmd.description !== undefined) frontmatter.description = cmd.description;\n  if (cmd.argumentHint !== undefined) frontmatter[\"argument-hint\"] = cmd.argumentHint;\n  if (includeToolsAndModel) {\n    const allow = cmd.tools?.allow;\n    if (allow && allow.length > 0) frontmatter[\"allowed-tools\"] = allow.join(\", \");\n    if (cmd.model !== undefined) frontmatter.model = cmd.model;\n  }\n  if (cmd.extra) Object.assign(frontmatter, cmd.extra);\n  return renderFrontmatterMd(frontmatter, cmd.prompt);\n}\n\n/**\n * Render a skill's SKILL.md: frontmatter (name, description + optional model,\n * allowed-tools, disable-model-invocation, verbatim extra) + body.\n */\nexport function renderSkillMd(skill: SkillDef): string {\n  const frontmatter: Record<string, unknown> = {\n    name: skill.name,\n    description: skill.description,\n  };\n  if (skill.model !== undefined) frontmatter.model = skill.model;\n  const allow = skill.tools?.allow;\n  if (allow && allow.length > 0) frontmatter[\"allowed-tools\"] = allow.join(\", \");\n  if (skill.disableModelInvocation !== undefined) {\n    frontmatter[\"disable-model-invocation\"] = skill.disableModelInvocation;\n  }\n  if (skill.extra) Object.assign(frontmatter, skill.extra);\n  return renderFrontmatterMd(frontmatter, skill.body);\n}\n\n/** Render a subagent to md+frontmatter (name, description, tools, model) + prompt body. */\nexport function renderSubagentMd(agent: SubagentDef): string {\n  const frontmatter: Record<string, unknown> = {\n    name: agent.name,\n    description: agent.description,\n  };\n  const allow = agent.tools?.allow;\n  if (allow && allow.length > 0) frontmatter.tools = allow.join(\", \");\n  if (agent.model !== undefined) frontmatter.model = agent.model;\n  if (agent.extra) Object.assign(frontmatter, agent.extra);\n  return renderFrontmatterMd(frontmatter, agent.prompt);\n}\n\n/**\n * Render a subagent in OpenCode's shape (shared by opencode/kilo/mimo-code):\n * frontmatter (description, mode:\"subagent\", model?, permission? + verbatim\n * extra) with the system prompt as the body. `name` is NOT a frontmatter\n * field — it comes from the filename. `permission` is derived from the coarse\n * `readonly` knob: a readonly agent gets a per-tool deny map (edit/bash) so it\n * cannot mutate the workspace.\n */\nexport function renderOpenCodeSubagentMd(agent: SubagentDef): string {\n  const frontmatter: Record<string, unknown> = {\n    description: agent.description,\n    mode: \"subagent\",\n  };\n  if (agent.model !== undefined) frontmatter.model = agent.model;\n  if (agent.readonly === true) {\n    // Per-tool permission map: deny mutating tools for a readonly subagent.\n    frontmatter.permission = { edit: \"deny\", bash: \"deny\" };\n  }\n  if (agent.extra) Object.assign(frontmatter, agent.extra);\n  return renderFrontmatterMd(frontmatter, agent.prompt);\n}\n"],"mappings":";;;AAgBA,SAAS,aAAa,qBAAqB;AASpC,SAAS,oBACd,aACA,MACQ;AACR,SAAO;AAAA,EAAQ,cAAc,WAAW,CAAC;AAAA;AAAA,EAAU,IAAI;AAAA;AACzD;AAYO,SAAS,gBACd,KACA,OAA2C,CAAC,GACpC;AACR,QAAM,EAAE,uBAAuB,KAAK,IAAI;AACxC,QAAM,cAAuC,CAAC;AAC9C,MAAI,IAAI,gBAAgB,OAAW,aAAY,cAAc,IAAI;AACjE,MAAI,IAAI,iBAAiB,OAAW,aAAY,eAAe,IAAI,IAAI;AACvE,MAAI,sBAAsB;AACxB,UAAM,QAAQ,IAAI,OAAO;AACzB,QAAI,SAAS,MAAM,SAAS,EAAG,aAAY,eAAe,IAAI,MAAM,KAAK,IAAI;AAC7E,QAAI,IAAI,UAAU,OAAW,aAAY,QAAQ,IAAI;AAAA,EACvD;AACA,MAAI,IAAI,MAAO,QAAO,OAAO,aAAa,IAAI,KAAK;AACnD,SAAO,oBAAoB,aAAa,IAAI,MAAM;AACpD;AAMO,SAAS,cAAc,OAAyB;AACrD,QAAM,cAAuC;AAAA,IAC3C,MAAM,MAAM;AAAA,IACZ,aAAa,MAAM;AAAA,EACrB;AACA,MAAI,MAAM,UAAU,OAAW,aAAY,QAAQ,MAAM;AACzD,QAAM,QAAQ,MAAM,OAAO;AAC3B,MAAI,SAAS,MAAM,SAAS,EAAG,aAAY,eAAe,IAAI,MAAM,KAAK,IAAI;AAC7E,MAAI,MAAM,2BAA2B,QAAW;AAC9C,gBAAY,0BAA0B,IAAI,MAAM;AAAA,EAClD;AACA,MAAI,MAAM,MAAO,QAAO,OAAO,aAAa,MAAM,KAAK;AACvD,SAAO,oBAAoB,aAAa,MAAM,IAAI;AACpD;AAGO,SAAS,iBAAiB,OAA4B;AAC3D,QAAM,cAAuC;AAAA,IAC3C,MAAM,MAAM;AAAA,IACZ,aAAa,MAAM;AAAA,EACrB;AACA,QAAM,QAAQ,MAAM,OAAO;AAC3B,MAAI,SAAS,MAAM,SAAS,EAAG,aAAY,QAAQ,MAAM,KAAK,IAAI;AAClE,MAAI,MAAM,UAAU,OAAW,aAAY,QAAQ,MAAM;AACzD,MAAI,MAAM,MAAO,QAAO,OAAO,aAAa,MAAM,KAAK;AACvD,SAAO,oBAAoB,aAAa,MAAM,MAAM;AACtD;AAUO,SAAS,yBAAyB,OAA4B;AACnE,QAAM,cAAuC;AAAA,IAC3C,aAAa,MAAM;AAAA,IACnB,MAAM;AAAA,EACR;AACA,MAAI,MAAM,UAAU,OAAW,aAAY,QAAQ,MAAM;AACzD,MAAI,MAAM,aAAa,MAAM;AAE3B,gBAAY,aAAa,EAAE,MAAM,QAAQ,MAAM,OAAO;AAAA,EACxD;AACA,MAAI,MAAM,MAAO,QAAO,OAAO,aAAa,MAAM,KAAK;AACvD,SAAO,oBAAoB,aAAa,MAAM,MAAM;AACtD;","names":[]}

package/dist/{chunk-CPLK7GTE.js → chunk-KG6T3YNJ.js}

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import {
   renderFrontmatterMd
-} from "./chunk-7L6ITC4T.js";
+} from "./chunk-IEGR4TP3.js";
 import {
-  buildHomeBinActionCommand
-} from "./chunk-I5MLE6S7.js";
+  buildHomeBinActionCommand,
+  buildHomeBinHookCommand
+} from "./chunk-TO57WYBB.js";
 import {
   MEMORY_CONTENT_SOFT_BUDGET_BYTES,
   listManagedBlocks,
@@ -102,6 +103,88 @@ function parseJsonc(text) {
   return JSON.parse(stripJsonc(text));
 }
 
+// src/core/object-map.ts
+function isMalformedRootValue(value) {
+  return value != null && (typeof value !== "object" || Array.isArray(value));
+}
+function unparseableWarn(platform, configPath) {
+  return {
+    platform,
+    action: "warn",
+    path: configPath,
+    detail: `existing ${configPath} is not parseable; left untouched (back it up / fix it, then re-run)`
+  };
+}
+function malformedWarn(platform, rootKey, configPath) {
+  return {
+    platform,
+    action: "warn",
+    path: configPath,
+    detail: `existing "${rootKey}" in ${configPath} is not an object map; left untouched (fix it, then re-run)`
+  };
+}
+function upsertInObjectMap(o) {
+  const policy = o.policy ?? "warn-skip";
+  if (o.codec.isPresentButUnparseable(o.configPath)) {
+    return unparseableWarn(o.platform, o.configPath);
+  }
+  const cfg = o.codec.parse(o.configPath) ?? {};
+  if (isMalformedRootValue(cfg[o.rootKey])) {
+    if (policy === "warn-skip") return malformedWarn(o.platform, o.rootKey, o.configPath);
+    cfg[o.rootKey] = {};
+  }
+  const bucket = cfg[o.rootKey] ?? (cfg[o.rootKey] = {});
+  const before = JSON.stringify(bucket[o.entryId]);
+  const after = JSON.stringify(o.entry);
+  let action;
+  if (before === void 0) action = "create";
+  else if (before === after) action = "skip";
+  else action = "update";
+  if (action !== "skip") {
+    bucket[o.entryId] = o.entry;
+    o.codec.serialize(o.configPath, cfg, o.dryRun ?? false);
+  }
+  return {
+    platform: o.platform,
+    action,
+    path: o.configPath,
+    detail: `${o.rootKey}.${o.entryId}`
+  };
+}
+function removeFromObjectMap(o) {
+  const policy = o.policy ?? "warn-skip";
+  if (o.codec.isPresentButUnparseable(o.configPath)) {
+    return unparseableWarn(o.platform, o.configPath);
+  }
+  const cfg = o.codec.parse(o.configPath);
+  if (cfg && isMalformedRootValue(cfg[o.rootKey])) {
+    if (policy === "warn-skip") return malformedWarn(o.platform, o.rootKey, o.configPath);
+    return {
+      platform: o.platform,
+      action: "skip",
+      path: o.configPath,
+      detail: `${o.rootKey}.${o.entryId} absent`
+    };
+  }
+  const bucket = cfg?.[o.rootKey];
+  if (!cfg || !bucket || !(o.entryId in bucket)) {
+    return {
+      platform: o.platform,
+      action: "skip",
+      path: o.configPath,
+      detail: `${o.rootKey}.${o.entryId} absent`
+    };
+  }
+  delete bucket[o.entryId];
+  o.codec.serialize(o.configPath, cfg, o.dryRun ?? false);
+  return {
+    platform: o.platform,
+    action: "remove",
+    path: o.configPath,
+    detail: `${o.rootKey}.${o.entryId}`
+  };
+}
+
 // src/adapters/base.ts
 import {
   copyFileSync,
@@ -114,6 +197,36 @@ import {
 } from "fs";
 import { homedir } from "os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "path";
+
+// src/core/hook-array.ts
+function upsertInArray(array, candidate, ownsEntry) {
+  const idx = array.findIndex(ownsEntry);
+  if (idx >= 0) {
+    if (JSON.stringify(array[idx]) === JSON.stringify(candidate)) {
+      return { array, action: "skip" };
+    }
+    const next = array.slice();
+    next[idx] = candidate;
+    return { array: next, action: "update" };
+  }
+  return { array: [...array, candidate], action: "create" };
+}
+function removeFromArray(array, ownsEntry, stripInner) {
+  if (!stripInner) {
+    const kept2 = array.filter((e) => !ownsEntry(e));
+    return { array: kept2, removed: array.length - kept2.length };
+  }
+  const kept = [];
+  let removed = 0;
+  for (const e of array) {
+    const r = stripInner(e);
+    removed += r.removed;
+    if (r.next !== null) kept.push(r.next);
+  }
+  return { array: kept, removed };
+}
+
+// src/adapters/base.ts
 var AGENTS_MD_USER_PATHS = {
   // codex resolves its own user path in-adapter ($CODEX_HOME with ~ expansion
   // + the AGENTS.override.md shadow probe) — deliberately no row here.
@@ -735,51 +848,253 @@ var BaseAdapter = class {
 `, "utf8");
   }
   /**
-   * Upsert `entry` at `config[rootKey][serverId]` in a JSON file, creating the
-   * file/object as needed. Returns a ChangeRecord describing create/update/skip.
-   * Idempotent: an identical entry yields "skip".
+   * True when a PRESENT rootKey value is not a plain object map (the user
+   * hand-edited it to an array / string / number / boolean). Assigning a server
+   * entry into such a value would corrupt the file silently (a named property on
+   * an Array is dropped by JSON.stringify) or throw under strict mode (a property
+   * write / `in` operator against a primitive), so callers warn-and-skip. A
+   * `null`/`undefined` value is NOT malformed — it is the well-formed "absent"
+   * case the helpers create fresh.
    */
-  upsertServerInJson(configPath, rootKey, serverId, entry, dryRun = false) {
-    if (this.isPresentButUnparseable(configPath)) {
+  isMalformedRootValue(value) {
+    return isMalformedRootValue(value);
+  }
+  /**
+   * Warn-skip ChangeRecord when an existing JSON `hooks` config is present-but-
+   * malformed (root hand-edited to an array/primitive, or an existing event
+   * bucket is a non-array) — installing a hook into it would silently drop the
+   * entry (a named property on an Array is dropped by JSON.stringify) or throw
+   * under strict mode (a `.push`/property write against a primitive or non-array
+   * bucket). Returns null when the hooks config is well-formed, including the
+   * absent case the installers create fresh (proceed normally). Mirrors the
+   * server-root guard (isMalformedRootValue). All targeted hosts use the Claude-
+   * style `{ Event: Matcher[] }` shape, so every present event bucket must be an
+   * array; a non-array bucket is the same malformed class as a wrong-typed root.
+   */
+  malformedHookRootSkip(configPath, hooksRoot) {
+    if (hooksRoot == null) return null;
+    if (this.isMalformedRootValue(hooksRoot)) {
       return {
         platform: this.id,
         action: "warn",
         path: configPath,
-        detail: `existing ${configPath} is not parseable; left untouched (back it up / fix it, then re-run)`
+        detail: `existing "hooks" in ${configPath} is not an object map; left untouched (fix it, then re-run)`
       };
     }
-    const cfg = this.readJson(configPath) ?? {};
-    const bucket = cfg[rootKey] ??= {};
-    const before = JSON.stringify(bucket[serverId]);
-    const after = JSON.stringify(entry);
-    let action;
-    if (before === void 0) action = "create";
-    else if (before === after) action = "skip";
-    else action = "update";
-    if (action !== "skip") {
-      bucket[serverId] = entry;
-      this.writeJson(configPath, cfg, dryRun);
+    for (const v of Object.values(hooksRoot)) {
+      if (v !== void 0 && !Array.isArray(v)) {
+        return {
+          platform: this.id,
+          action: "warn",
+          path: configPath,
+          detail: `existing "hooks" in ${configPath} has a non-array event bucket; left untouched (fix it, then re-run)`
+        };
+      }
     }
-    return { platform: this.id, action, path: configPath, detail: `${rootKey}.${serverId}` };
+    return null;
   }
-  /** Remove `config[rootKey][serverId]` from a JSON file. */
-  removeServerFromJson(configPath, rootKey, serverId, dryRun = false) {
-    if (this.isPresentButUnparseable(configPath)) {
-      return {
+  // ── Shared object-map hook-array merge engine ────────────────────────────
+  // installHooks/uninstallHooks for every json-stdio host that stores hooks as
+  // `{ <event>: HookEntry[] }` share ONE create/update/skip + strip/remove
+  // orchestration. The host supplies a {@link HookMergeDescriptor} carrying
+  // EVERY observable string and ownership predicate — the engine body hardcodes
+  // none of them, so per-host wording (skip/remove/absent/no-match details) and
+  // FLAT-vs-NESTED removal stay host-controlled and never drift to a lowest-
+  // common-denominator phrasing the suites (which assert by action) would miss.
+  // The write-gate is the `mutated` bool, matching the migrated host exactly.
+  /**
+   * Install: upsert each `{ event, matcher }` in `pending` into the object-map
+   * `hooks` root at `configPath`. Reproduces the canonical host's loop: read
+   * `?? {}`, warn-skip on a malformed `hooks` root, then per pending item render
+   * the entry, find the owned slot, and create/update/skip. Writes once at the
+   * end iff anything mutated.
+   *
+   * Hosts that fold their `nativeHooks` surface into `pending` (claude-code) pass
+   * no `native` arg. Hosts that keep the native surface SEPARATE — verbatim
+   * event keys, EXACT-command ownership, a distinct `(native)` detail — pass it
+   * as the optional `native` list (cursor); that pass runs after the normalized
+   * loop and before the single write. Omitting it is byte-identical to before.
+   */
+  /**
+   * Resolve the per-event hook bucket. With "coerce" policy a present-but-non-
+   * array bucket (hand-edited) is replaced by a fresh array; otherwise `??=` is
+   * used (the warn-skip path already rejected any non-array bucket via
+   * malformedHookRootSkip, so `??=` only ever fills the absent case).
+   */
+  coerceHookBucket(hooks, event, coerce) {
+    if (coerce) {
+      return Array.isArray(hooks[event]) ? hooks[event] : hooks[event] = [];
+    }
+    return hooks[event] ??= [];
+  }
+  upsertHookEntries(ctx, configPath, pending, descriptor, native) {
+    const file = this.readJson(configPath) ?? {};
+    const coerce = descriptor.malformedPolicy === "coerce";
+    let hooks;
+    if (coerce) {
+      const existing = file.hooks;
+      hooks = existing && typeof existing === "object" && !Array.isArray(existing) ? existing : file.hooks = {};
+    } else {
+      const skip = this.malformedHookRootSkip(configPath, file.hooks);
+      if (skip) return [skip];
+      hooks = file.hooks ??= {};
+    }
+    const changes = [];
+    let mutated = false;
+    for (const { event, matcher } of pending) {
+      const hostEvent = descriptor.mapEvent ? descriptor.mapEvent(event) : event;
+      if (hostEvent === void 0) {
+        changes.push({
+          platform: this.id,
+          action: "warn",
+          path: configPath,
+          detail: descriptor.unmappedWarnDetail(event)
+        });
+        continue;
+      }
+      const command = buildHomeBinHookCommand(
+        ctx.homeBinPath,
+        this.id,
+        event,
+        ctx.connector.id
+      );
+      const entry = descriptor.renderEntry(hostEvent, matcher, command);
+      const bucket = this.coerceHookBucket(hooks, hostEvent, coerce);
+      const r = upsertInArray(
+        bucket,
+        entry,
+        (e) => descriptor.entryOwnsCommand(e, command)
+      );
+      if (r.action !== "skip") {
+        hooks[hostEvent] = r.array;
+        mutated = true;
+      }
+      changes.push({
         platform: this.id,
-        action: "warn",
+        action: r.action,
         path: configPath,
-        detail: `existing ${configPath} is not parseable; left untouched (back it up / fix it, then re-run)`
-      };
+        detail: r.action === "skip" ? descriptor.skipDetail(hostEvent) : `hooks.${hostEvent}`
+      });
     }
-    const cfg = this.readJson(configPath);
-    const bucket = cfg?.[rootKey];
-    if (!cfg || !bucket || !(serverId in bucket)) {
-      return { platform: this.id, action: "skip", path: configPath, detail: `${rootKey}.${serverId} absent` };
+    for (const { event, matcher } of native ?? []) {
+      const command = buildHomeBinHookCommand(
+        ctx.homeBinPath,
+        this.id,
+        event,
+        ctx.connector.id
+      );
+      const entry = descriptor.renderEntry(event, matcher, command);
+      const bucket = this.coerceHookBucket(hooks, event, coerce);
+      const r = upsertInArray(
+        bucket,
+        entry,
+        (e) => descriptor.nativeOwnsCommand(e, command)
+      );
+      if (r.action !== "skip") {
+        hooks[event] = r.array;
+        mutated = true;
+      }
+      changes.push({
+        platform: this.id,
+        action: r.action,
+        path: configPath,
+        detail: r.action === "skip" ? descriptor.nativeSkipDetail(event) : descriptor.nativeMutateDetail(event)
+      });
+    }
+    if (mutated) {
+      descriptor.onMutate?.(file);
+      this.writeJson(configPath, file, ctx.dryRun);
     }
-    delete bucket[serverId];
-    this.writeJson(configPath, cfg, dryRun);
-    return { platform: this.id, action: "remove", path: configPath, detail: `${rootKey}.${serverId}` };
+    return changes;
+  }
+  /**
+   * Uninstall: strip owned content from every event bucket in the object-map
+   * `hooks` root at `configPath`. NESTED hosts pass `descriptor.stripInner`
+   * (strip owned inner commands, drop emptied entries; `removed` = inner
+   * commands); FLAT hosts omit it (drop whole owned entries). Reproduces the
+   * canonical host: read (NO `?? {}`), `[skip]` (absentDetail) when no hooks
+   * section, per-event remove → delete-or-replace bucket, write once iff
+   * mutated, and a single `[skip]` (noMatchDetail) when nothing matched.
+   */
+  removeHookEntries(ctx, configPath, descriptor) {
+    const file = this.readJson(configPath);
+    const hooks = file?.hooks;
+    if (!file || !hooks) {
+      return [
+        {
+          platform: this.id,
+          action: "skip",
+          path: configPath,
+          detail: descriptor.absentDetail
+        }
+      ];
+    }
+    const changes = [];
+    let mutated = false;
+    const stripInner = descriptor.stripInner?.(ctx);
+    for (const event of descriptor.removeEventKeys ?? Object.keys(hooks)) {
+      const bucket = hooks[event];
+      if (!Array.isArray(bucket)) continue;
+      const ownsEntry = descriptor.ownsEntryForRemove(ctx, event);
+      const r = removeFromArray(bucket, ownsEntry, stripInner);
+      if (r.removed > 0) {
+        if (r.array.length > 0) hooks[event] = r.array;
+        else delete hooks[event];
+        changes.push({
+          platform: this.id,
+          action: "remove",
+          path: configPath,
+          detail: descriptor.removeDetail(event, r.removed)
+        });
+        mutated = true;
+      }
+    }
+    if (mutated) this.writeJson(configPath, file, ctx.dryRun);
+    if (changes.length === 0) {
+      changes.push({
+        platform: this.id,
+        action: "skip",
+        path: configPath,
+        detail: descriptor.noMatchDetail
+      });
+    }
+    return changes;
+  }
+  /** Bind BaseAdapter's JSON leaf IO (readJson/writeJson + the unparseable
+   * overwrite guard) as a Codec for the object-map engine. */
+  jsonObjectMapCodec() {
+    return {
+      parse: (path) => this.readJson(path),
+      serialize: (path, data, dryRun) => this.writeJson(path, data, dryRun),
+      isPresentButUnparseable: (path) => this.isPresentButUnparseable(path)
+    };
+  }
+  /**
+   * Upsert `entry` at `config[rootKey][serverId]` in a JSON file, creating the
+   * file/object as needed. Returns a ChangeRecord describing create/update/skip.
+   * Idempotent: an identical entry yields "skip".
+   */
+  upsertServerInJson(configPath, rootKey, serverId, entry, dryRun = false) {
+    return upsertInObjectMap({
+      codec: this.jsonObjectMapCodec(),
+      rootKey,
+      platform: this.id,
+      configPath,
+      entryId: serverId,
+      entry,
+      dryRun
+    });
+  }
+  /** Remove `config[rootKey][serverId]` from a JSON file. */
+  removeServerFromJson(configPath, rootKey, serverId, dryRun = false) {
+    return removeFromObjectMap({
+      codec: this.jsonObjectMapCodec(),
+      rootKey,
+      platform: this.id,
+      configPath,
+      entryId: serverId,
+      dryRun
+    });
   }
   // ── Backup ───────────────────────────────────────────────────────────────
   backupSettings(ctx) {
@@ -829,6 +1144,8 @@ var BaseAdapter = class {
 
 export {
   parseJsonc,
+  upsertInObjectMap,
+  removeFromObjectMap,
   BaseAdapter
 };
-//# sourceMappingURL=chunk-CPLK7GTE.js.map
+//# sourceMappingURL=chunk-KG6T3YNJ.js.map