@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

package/src/kiro-cli-agent.mjs

@@ -0,0 +1,270 @@
+// kiro-cli-agent.mjs — the Kiro CLI agent-config + default-agent registration (Task 50.L / D-198).
+//
+// kiro-cli (= Amazon Q Developer CLI) hooks live in an agent-config JSON. Its
+// hooks auto-fire ONLY for the resolved-ACTIVE agent, so for automatic memory
+// with no `--agent` flag, cmk must be the DEFAULT agent. TWO files, verified
+// against a real kiro-cli 2.8.1 (`kiro-cli agent list` + `agent validate`):
+//
+//   1. ~/.kiro/agents/cmk.json        — the agent config (hooks/mcp/prompt/…)
+//   2. ~/.kiro/settings/cli.json      — {"chat.defaultAgent":"cmk"} (the
+//                                        LOAD-BEARING registration; without it
+//                                        the built-in `kiro_default` runs and
+//                                        NO kit hooks fire)
+//
+// ── D-198 (the cut-gate-kiro root cause) ──────────────────────────────────────
+// The original impl wrote `~/.aws/amazonq/cli-agents/q_cli_default.json`. That is
+// the WRONG location for kiro-cli 2.8.1: `kiro-cli agent list` resolves agents
+// from `~/.kiro/agents/` (global) + `<project>/.kiro/agents/` (workspace), and
+// the default is the built-in `kiro_default`. Our `~/.aws/...` file was NEVER
+// loaded — so the instrumented cut-gate probe showed NEITHER agentSpawn NOR
+// preToolUse firing, and KG-guard let a memory delete through every time. Our own
+// research (2026-06-20-kiro-automatic-memory-deep-research §3, "the load-bearing
+// step the kit is missing") had `~/.kiro/agents/cmk.json` + `~/.kiro/settings/
+// cli.json` correct; the impl dropped it. This module follows the research +
+// the live-verified contract. The matcher fix (D-197, `'*'`) was correct but
+// secondary — a right fix to a file kiro-cli never read.
+//
+// Also: kiro-cli's `agent validate` is STRICT — it rejects unknown top-level
+// fields. The old `managedBy` marker FAILS validation (`unknown field
+// managedBy`). Ownership is now tracked structurally WITHOUT an invalid field:
+// the agent file lives at our well-known path (`agents/cmk.json`) and the
+// settings pointer names `cmk`; uninstall keys on that, plus a marker carried in
+// a VALID field (the `description`, which validate accepts) as a belt.
+//
+// Public surface:
+//   installKiroCliAgent({ kiroDir? }) → { action, defaultAgent, changed, path }
+//   uninstallKiroCliAgent({ kiroDir? }) → { action, changed }
+//   hasOurCliAgent({ kiroDir? }) → boolean
+//   (kiroDir overrides the ~/.kiro base; defaults to $MEMORY_KIT_KIRO_DIR or ~/.kiro.
+//    $MEMORY_KIT_AWS_DIR is still honored as a back-compat alias for the base.)
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { kiroHookCommand, kiroGuardCommand, kiroCliAllowedCommands } from './kiro-hook-command.mjs';
+import { parseJsonFile } from './read-json.mjs';
+
+// The kit's agent name. NOT `q_cli_default` — that name doesn't exist in kiro-cli
+// (the built-in default is `kiro_default`). We register `cmk` and point
+// chat.defaultAgent at it.
+const AGENT_NAME = 'cmk';
+
+// A marker carried in the `description` (a VALID schema field — unlike the old
+// top-level `managedBy`, which kiro-cli's strict `agent validate` rejects). Used
+// as a belt on top of the well-known path for ownership detection on uninstall.
+const MANAGED_MARKER = '[claude-memory-kit]';
+
+// The kiro config root is `~/.kiro/`. $MEMORY_KIT_KIRO_DIR (or the back-compat
+// $MEMORY_KIT_AWS_DIR) overrides the BASE — REQUIRED in tests so the user-tier
+// write lands in a sandbox, never the real ~/.kiro. Production passes nothing.
+function kiroRoot(kiroDir) {
+  const base = kiroDir || process.env.MEMORY_KIT_KIRO_DIR || process.env.MEMORY_KIT_AWS_DIR;
+  return base ? base : join(homedir(), '.kiro');
+}
+
+function agentsDirOf(kiroDir) {
+  return join(kiroRoot(kiroDir), 'agents');
+}
+function agentPathOf(kiroDir) {
+  return join(agentsDirOf(kiroDir), `${AGENT_NAME}.json`);
+}
+function cliSettingsPathOf(kiroDir) {
+  return join(kiroRoot(kiroDir), 'settings', 'cli.json');
+}
+
+// Build the agent-config in the live-verified kiro-cli schema. ONLY valid
+// top-level fields (kiro-cli `agent validate` is strict): name, description,
+// prompt, mcpServers, tools, allowedTools, resources, hooks, toolsSettings,
+// includeMcpJson, useLegacyMcpJson, model. NO `managedBy` (rejected).
+function buildAgentConfig() {
+  const cfg = {
+    name: AGENT_NAME,
+    description: `claude-memory-kit — automatic per-session memory (inject + capture). ${MANAGED_MARKER}`,
+    // ★ `tools` is the agent's CAPABILITY SET — what it CAN use. WITHOUT it, a
+    // custom agent has NO tools: it cannot run shell commands at all, so the model
+    // "calls" cmk remember but nothing executes (the cut-gate-kiro-cli silent
+    // failure — kiro.dev/docs/cli/custom-agents/configuration-reference: "the
+    // tools field lists all tools the agent can potentially use"). `'*'` = all
+    // built-in tools (incl. shell, so `cmk remember`/`cmk search` actually run) +
+    // any MCP tools. This was THE missing piece behind the explicit-memory failure.
+    //
+    // ★ Do NOT "tighten" this to a scoped list. `tools` is the CAPABILITY set, NOT
+    // the security boundary — auto-execution is gated separately by `allowedTools`
+    // (absent) + `toolsSettings.shell.allowedCommands` (scoped to `^cmk …`) + the
+    // `preToolUse` delete-guardrail. With `'*'` but no `allowedTools`, every tool
+    // call EXCEPT the pre-trusted `^cmk` shell commands still hits kiro-cli's native
+    // Run/Reject/Trust prompt — so `'*'` widens capability, not silent execution.
+    // A hardcoded scoped list (e.g. `execute_bash`) would also silently drop the
+    // shell tool across the V2→V3 rename (`execute_bash`→`execute_command`),
+    // re-breaking this version-dependently. The approval gate is the boundary.
+    tools: ['*'],
+    // INLINE prompt — NOT `file://AGENTS.md`. kiro-cli resolves a config's
+    // `prompt`/`resources` file:// paths RELATIVE TO THE AGENT FILE'S DIR
+    // (~/.kiro/agents/), per kiro.dev/docs/cli/custom-agents/configuration-
+    // reference — so `file://AGENTS.md` would point at ~/.kiro/agents/AGENTS.md,
+    // NOT the project root (D-198). AGENTS.md is AUTO-INCLUDED by kiro-cli from
+    // the workspace root with no ref needed (it's "always included"), so the
+    // project instruction loads regardless; this inline prompt is the
+    // belt-and-suspenders recall/persist directive that travels WITH the agent.
+    // ★ kiro-cli memory = HOOKS (automatic) + CLI commands (explicit), NOT MCP.
+    // WHY no MCP here (the cut-gate-kiro-cli findings + Kiro issues #5873/#5662):
+    // kiro-cli does NOT wire MCP tools to a CUSTOM agent's LLM (only the built-in
+    // kiro_default gets them), so the MCP memory tools silently no-op. Loading the
+    // MCP server in the kiro-cli agent gains NOTHING (dead tools) and COSTS a
+    // visible `cmd.exe /C cmk mcp serve` console window every session on Windows
+    // (kiro's MCP launcher — not suppressible from the kit). So `includeMcpJson:
+    // false` keeps the kiro-cli agent OFF MCP entirely → no dead tools, no popup.
+    // (The Kiro IDE keeps its OWN MCP via `.kiro/settings/mcp.json`, where MCP
+    // WORKS — the IDE does not read this agent config, so it's unaffected.)
+    //
+    // The working memory paths in kiro-cli:
+    //   • AUTOMATIC — the agentSpawn (inject) + stop (capture) hooks below run
+    //     `cmk hook`, which kiro feeds the project cwd via the hook stdin payload,
+    //     so they capture/recall correctly with no model action.
+    //   • EXPLICIT recall — `cmk search` (a pre-trusted shell command).
+    prompt:
+      'You have claude-memory-kit memory for this project, captured automatically ' +
+      'each turn by the kit\'s hooks. Use the kit\'s SHELL COMMANDS for explicit ' +
+      'recall/save. ### CRITICAL command form — do NOT prefix a kit command with ' +
+      '`cd`. A `cd … && cmk …` prefix breaks kiro-cli\'s command allowlist (the ' +
+      'command then needs manual approval and may be skipped). Instead pass the ' +
+      'project root with `--project` and run the bare command. To RECALL: `cmk ' +
+      'search "<topic>" --project "<absolute project path>"` before answering (do ' +
+      'not re-derive what memory records). To SAVE: `cmk remember "<the fact>" ' +
+      '--project "<absolute project path>"` (add `--why "..." --how "..." --type ' +
+      'user|feedback|project` for a rich preference). The absolute project path is ' +
+      'this workspace\'s root. Treat AGENTS.md as authoritative project instruction.',
+    // includeMcpJson:false — the kiro-cli agent does NOT load any MCP server (see
+    // the rationale above: dead tools + a popup, no benefit). The IDE's MCP is
+    // wired separately in `.kiro/settings/mcp.json` and is untouched by this.
+    includeMcpJson: false,
+    // NO `allowedTools` — there are no MCP tools to pre-approve (includeMcpJson is
+    // false). The kit's shell commands are trusted via toolsSettings below.
+    // NO `resources` file:// refs: a project-relative path can't resolve from the
+    // GLOBAL agent dir (~/.kiro/agents/) — D-198. AGENTS.md auto-loads anyway.
+    // Pre-trust the kit's OWN hook + CLI commands (no per-command approval) — D-194.
+    toolsSettings: { shell: { allowedCommands: kiroCliAllowedCommands() } },
+  };
+  // hooks: object keyed by trigger → array of {command, timeout_ms}. agentSpawn
+  // (inject) + userPromptSubmit (inject + prompt-capture) + stop (capture) +
+  // preToolUse (the delete-guardrail). timeout_ms (NOT `timeout`). preToolUse
+  // `matcher: '*'` (all tools) — kiro-cli matchers are literal strings, not regex
+  // (D-197); the bin exits 2 to BLOCK. userPromptSubmit (50.N.1) routes to BOTH
+  // inject AND capturePrompt (the <private>-strip + transcript-append half of
+  // Claude Code's UserPromptSubmit); kiro-cli's userPromptSubmit stdin carries
+  // `prompt`, which capturePrompt reads.
+  // postToolUse (50.N.2) → observe-edit, scoped to the file-write tool with
+  // `matcher: 'fs_write'` (kiro-cli matchers are literal tool names — the runHook
+  // adapter maps fs_write → Write for the shared observeEdit core). Only fires on
+  // a file write, so it's cheap.
+  cfg.hooks = {
+    agentSpawn: [{ command: kiroHookCommand('agentSpawn'), timeout_ms: 10000 }],
+    userPromptSubmit: [{ command: kiroHookCommand('userPromptSubmit'), timeout_ms: 10000 }],
+    postToolUse: [{ command: kiroHookCommand('postToolUse'), timeout_ms: 10000, matcher: 'fs_write' }],
+    stop: [{ command: kiroHookCommand('stop'), timeout_ms: 30000 }],
+    preToolUse: [{ command: kiroGuardCommand(), timeout_ms: 5000, matcher: '*' }],
+  };
+  return cfg;
+}
+
+export function installKiroCliAgent({ kiroDir, awsDir } = {}) {
+  kiroDir = kiroDir ?? awsDir; // `awsDir` accepted as a back-compat alias for the sandbox base
+  const agentsDir = agentsDirOf(kiroDir);
+  const agentPath = agentPathOf(kiroDir);
+  const settingsPath = cliSettingsPathOf(kiroDir);
+
+  mkdirSync(agentsDir, { recursive: true });
+
+  // 1. write the agent config
+  const changedAgent = writeIfChanged(agentPath, `${JSON.stringify(buildAgentConfig(), null, 2)}\n`);
+
+  // 2. register chat.defaultAgent — the LOAD-BEARING step. GUARDED: never clobber
+  //    a user's existing default that ISN'T ours. If they already point at a
+  //    different agent, we install `cmk` but leave their default alone (they run
+  //    `kiro-cli --agent cmk` or set it themselves) and report skipped-existing.
+  const existingDefault = readDefaultAgentSetting(settingsPath);
+  const userHasForeignDefault = existingDefault != null && existingDefault !== AGENT_NAME;
+
+  let defaultAgent;
+  let changedSettings = false;
+  if (userHasForeignDefault) {
+    defaultAgent = 'skipped-existing';
+  } else {
+    changedSettings = mergeDefaultAgentSetting(settingsPath, AGENT_NAME);
+    defaultAgent = 'set';
+  }
+
+  return {
+    action: 'installed',
+    defaultAgent,
+    changed: changedAgent || changedSettings,
+    path: agentPath,
+  };
+}
+
+// Write only if the serialized content differs (idempotent re-install).
+function writeIfChanged(path, serialized) {
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  if (existing === serialized) return false;
+  writeFileSync(path, serialized, 'utf8');
+  return true;
+}
+
+// Merge {"chat.defaultAgent": name} into ~/.kiro/settings/cli.json, BYTE-
+// PRESERVING every other key (managed-merge discipline — same as the Claude
+// settings path). Returns true if the file changed.
+function mergeDefaultAgentSetting(settingsPath, name) {
+  mkdirSync(join(settingsPath, '..'), { recursive: true });
+  const current = parseJsonFile(settingsPath, { fallback: null }) ?? {};
+  if (current['chat.defaultAgent'] === name) return false;
+  current['chat.defaultAgent'] = name;
+  writeFileSync(settingsPath, `${JSON.stringify(current, null, 2)}\n`, 'utf8');
+  return true;
+}
+
+export function uninstallKiroCliAgent({ kiroDir, awsDir } = {}) {
+  kiroDir = kiroDir ?? awsDir;
+  const agentPath = agentPathOf(kiroDir);
+  const settingsPath = cliSettingsPathOf(kiroDir);
+  let changed = false;
+
+  // remove OUR agent file only (well-known path + our marker)
+  if (existsSync(agentPath) && isOurAgent(agentPath)) {
+    rmSync(agentPath, { force: true });
+    changed = true;
+  }
+
+  // un-register the default ONLY if it points at us (byte-preserve other keys)
+  const current = parseJsonFile(settingsPath, { fallback: null });
+  if (current != null && current['chat.defaultAgent'] === AGENT_NAME) {
+    delete current['chat.defaultAgent'];
+    writeFileSync(settingsPath, `${JSON.stringify(current, null, 2)}\n`, 'utf8');
+    changed = true;
+  }
+
+  return { action: 'uninstalled', changed };
+}
+
+// Does a cmk-owned kiro-cli agent exist? (the well-known ~/.kiro/agents/cmk.json
+// with our marker). Used by `cmk doctor` HC-1 — a kiro-cli user's capture/inject
+// fires via THIS surface (D-186).
+export function hasOurCliAgent({ kiroDir, awsDir } = {}) {
+  kiroDir = kiroDir ?? awsDir;
+  const agentPath = agentPathOf(kiroDir);
+  return existsSync(agentPath) && isOurAgent(agentPath);
+}
+
+// ── internal ─────────────────────────────────────────────────────────────────
+
+// Is the agent at `path` ours? Keyed on our marker in the (valid) `description`
+// field — NOT a rejected top-level field. BOM-tolerant.
+function isOurAgent(path) {
+  const j = parseJsonFile(path, { fallback: null });
+  return j != null && typeof j.description === 'string' && j.description.includes(MANAGED_MARKER);
+}
+
+// Read the user's chat.defaultAgent from ~/.kiro/settings/cli.json. BOM-tolerant.
+function readDefaultAgentSetting(settingsPath) {
+  const j = parseJsonFile(settingsPath, { fallback: null });
+  return j != null ? (j['chat.defaultAgent'] ?? null) : null;
+}

package/src/kiro-constants.mjs

@@ -0,0 +1,19 @@
+// kiro-constants.mjs — leaf module of shared Kiro constants, so multiple Kiro
+// modules can import them without an import cycle (install-kiro ↔ kiro-permissions).
+
+// The kit's 11 MCP tool names (bare). Used for BOTH the IDE mcp.json `autoApprove`
+// (install-kiro) AND the IDE-1.0 permissions.yaml `capability: mcp` match list
+// (kiro-permissions) — one source so the two never drift.
+export const MCP_AUTO_APPROVE = Object.freeze([
+  'mk_remember',
+  'mk_search',
+  'mk_get',
+  'mk_timeline',
+  'mk_cite',
+  'mk_recent_activity',
+  'mk_trust',
+  'mk_lessons_promote',
+  'mk_forget',
+  'mk_queue_list',
+  'mk_queue_resolve',
+]);

package/src/kiro-hook-bin.mjs

@@ -0,0 +1,105 @@
+// kiro-hook-bin.mjs — the Kiro hook ADAPTER (Task 50.J/50.L).
+//
+// Bridges Kiro's runCommand hook input model to the kit's inject/capture cores.
+// Kiro's model (LIVE-VERIFIED via probe, P-CJYGTQYR — and there is NO published
+// runCommand prior art; every real Kiro hook is askAgent, so the probe is ground
+// truth):
+//   - EVENT  → argv          (`cmk hook stop` → argv[0] = 'stop')
+//   - PROJECT→ process.cwd()  (Kiro runs the hook in the project root)
+//   - PROMPT → process.env.USER_PROMPT  (set on promptSubmit; empty on stop)
+//   - TURN   → Kiro's transcript file (.history), NOT a stdin payload
+//   - TOOL   → (preToolUse) the about-to-run tool command; passed via env/argv
+//             (exact field flagged for the cut-gate-kiro live test, D-192)
+//
+// This is the per-agent adapter the cross-agent seam needs: Claude Code reads a
+// stdin JSON payload; Kiro reads argv+env+cwd+transcript. The dispatcher (50.J)
+// owns the routing + the always-exit-0 invariant; this adapter owns the
+// input translation. `deps` is the injection seam (tests pass fakes; the bin
+// wires the real readKiroTurn / injectContext / captureTurn).
+//
+// Public surface:
+//   runKiroHook({ argv, cwd, env, deps }) → { action, exitCode: 0, stdout?, stderr? }
+
+import { dispatchKiroHook } from './kiro-hook-dispatch.mjs';
+
+// 50.N.2 — Kiro's file-write tool names → Claude's PostToolUse-eligible names, so
+// the shared observeEdit core (keyed on Write/Edit/MultiEdit) recognizes a Kiro
+// file edit. `fs_write` is Kiro's create-or-edit-a-file tool (kiro.dev tool list);
+// it covers both the create + edit cases, mapping to Claude's Write/Edit class
+// (observeEdit treats Write/Edit/MultiEdit identically — the target name only
+// appears in the summary line, so the map is behavior-neutral).
+// NOTE: if a real kiro-cli turns out to have a SEPARATE append/patch tool (e.g.
+// `fs_append`), add it here AND to the agent-config `matcher` (today scoped to the
+// literal `fs_write`). Flagged for the cut-gate to confirm `fs_write` is the only
+// file-mutation tool — no Kiro tool enumeration is captured in the research yet.
+const KIRO_EDIT_TOOL_MAP = Object.freeze({
+  fs_write: 'Write',
+  fsWrite: 'Write', // camelCase spelling tolerance
+});
+
+export function runKiroHook({ argv = [], cwd = process.cwd(), env = process.env, payload = {}, deps = {} } = {}) {
+  const event = argv[0];
+  const { readKiroTurn, inject, capture, capturePrompt, observe, guard } = deps;
+
+  // Wrap the kit cores so the dispatcher's generic inject/capture contract is fed
+  // Kiro's actual inputs.
+  const wrappedInject = (args) => inject({ ...args, userPrompt: env.USER_PROMPT || '' });
+
+  const wrappedCapture = (args) => {
+    // Kiro has no stdin payload — read the turn from Kiro's transcript instead,
+    // then build the {assistant_message} payload captureTurn's extractTurnText
+    // understands. A failed read must NOT crash (dispatcher catches + exits 0).
+    const turn = readKiroTurn({ projectRoot: args.projectRoot, env }) || {};
+    const payload = {
+      assistant_message: turn.assistantText || '',
+      // carry the user prompt too (capture-prompt pairing analog)
+      ...(turn.userText ? { user_message: turn.userText } : {}),
+    };
+    return capture({ ...args, payload });
+  };
+
+  // 50.N.1 — prompt-capture on the prompt-submit events. The prompt text comes
+  // from the stdin payload (kiro-cli `userPromptSubmit` carries `prompt`) OR env
+  // USER_PROMPT (the IDE legacy surface). capturePrompt reads `payload.prompt`,
+  // so build a payload that carries whichever is present.
+  const wrappedCapturePrompt = capturePrompt
+    ? (args) => {
+        const prompt =
+          (payload && typeof payload.prompt === 'string' && payload.prompt) ||
+          env.USER_PROMPT ||
+          '';
+        return capturePrompt({ ...args, payload: { ...payload, prompt } });
+      }
+    : undefined;
+
+  // 50.N.2 — observe-edit on postToolUse. Kiro's file-write tool is `fs_write`
+  // (not Claude's Write/Edit/MultiEdit), so map the Kiro tool name to an eligible
+  // one before observeEdit's eligibility check. observeEdit's path-extractor
+  // already probes `path` (which Kiro's fs_write tool_input uses) alongside
+  // file_path/filePath. The stdin payload (postToolUse → {tool_name, tool_input,
+  // tool_response}) carries everything observeEdit needs.
+  const wrappedObserve = observe
+    ? (args) => {
+        const mapped = KIRO_EDIT_TOOL_MAP[payload?.tool_name] ?? payload?.tool_name;
+        return observe({ ...args, payload: { ...payload, tool_name: mapped } });
+      }
+    : undefined;
+
+  // preToolUse guard (forward-compat path — the production Kiro install calls the
+  // cmk-guard-memory bin directly, which reads the stdin payload). If a guard dep
+  // is wired, pass the stdin payload through so it can read tool_input.command.
+  const wrappedGuard = guard ? (args) => guard({ ...args, payload }) : undefined;
+
+  return dispatchKiroHook({
+    event,
+    payload,
+    cwd,
+    deps: {
+      inject: wrappedInject,
+      capture: wrappedCapture,
+      ...(wrappedCapturePrompt ? { capturePrompt: wrappedCapturePrompt } : {}),
+      ...(wrappedObserve ? { observe: wrappedObserve } : {}),
+      ...(wrappedGuard ? { guard: wrappedGuard } : {}),
+    },
+  });
+}

package/src/kiro-hook-command.mjs

@@ -0,0 +1,67 @@
+// kiro-hook-command.mjs — the platform-correct `cmk hook <event>` command string.
+//
+// Shared by BOTH Kiro hook surfaces (the IDE .kiro.hook writer + the CLI
+// agent-config writer) so the platform logic lives in ONE place (the
+// shared-module discipline).
+//
+// LIVE-VERIFIED 2026-06-21 (P-PM2CD6CB): Kiro runs a hook command through WSL on
+// Windows, and WSL has no node, so a bare `cmk hook stop` fails ("node: not
+// found"). Forcing the Windows-native shell with `cmd.exe /c` reaches the real
+// node+cmk (proven: `cmd.exe /c cmk --version` → 0.3.5 in the Kiro chat). On
+// macOS/Linux there's no WSL hop, so the native `cmk` runs directly.
+//   Windows → `cmd.exe /c cmk hook <event>`
+//   macOS/Linux → `cmk hook <event>`
+//
+// platform-commands: ignore (the Kiro-hook command runs in KIRO's shell, not the
+//   kit's — this is the deliberate cmd.exe form; it keys on the INSTALL host's
+//   process.platform, the right signal for "which OS will run these hooks").
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/** Build the `cmk hook <event>` command, platform-wrapped. */
+export function kiroHookCommand(event, cmkCmd = 'cmk') {
+  const inner = `${cmkCmd} hook ${event}`;
+  return IS_WINDOWS ? `cmd.exe /c ${inner}` : inner;
+}
+
+/**
+ * Build the memory delete-guardrail command (D-192), platform-wrapped. Kiro's
+ * `preToolUse` delivers `{ tool_name, tool_input: { command } }` on STDIN — the
+ * SAME shape as Claude Code (verified from the real oh-my-kiro + vibekit
+ * preToolUse hooks). So the `cmk-guard-memory` bin (which reads that stdin and
+ * exits 2 to BLOCK) guards BOTH agents — no Kiro-specific adapter needed.
+ */
+export function kiroGuardCommand(binCmd = 'cmk-guard-memory') {
+  return IS_WINDOWS ? `cmd.exe /c ${binCmd}` : binCmd;
+}
+
+/**
+ * The kit's hook commands as CLI agent-config `toolsSettings.shell.allowedCommands`
+ * REGEX patterns (D-194). Distinct from the IDE `kiroAgent.trustedCommands` shape:
+ * the CLI agent-config uses REGEX (per the Kiro agent config reference —
+ * `deniedCommands: ["git commit .*"]`), the IDE uses wildcard PREFIX. Without these,
+ * the kiro-cli default agent prompts to approve its OWN inject/capture/guard hooks.
+ * We escape the `cmd.exe` dot and anchor each to the kit's own commands only —
+ * never a blanket `.*`.
+ */
+export function kiroCliAllowedCommands() {
+  // Regex, START-ANCHORED (`^`) to mirror the IDE side's prefix-from-start
+  // semantics (skill-review M2 — an unanchored `cmk hook .*` could match a
+  // command that merely CONTAINS the phrase mid-string). `.` in cmd.exe is
+  // escaped; `.*` matches the hook event / guard tail / command args.
+  //
+  // `cmk remember` + `cmk search` are pre-trusted because kiro-cli uses the CLI
+  // commands (not the MCP tools) for explicit capture/recall — kiro-cli does not
+  // wire MCP tools to a custom agent's LLM (Kiro #5873), so the shell commands are
+  // the working path. Pre-trusting them means they run WITHOUT a Run/Reject prompt
+  // (the same posture as the hook commands). Scoped to the kit's own verbs only.
+  const base = IS_WINDOWS
+    ? [
+        '^cmd\\.exe /c cmk hook .*',
+        '^cmd\\.exe /c cmk-guard-memory',
+        '^cmk remember .*',
+        '^cmk search .*',
+      ]
+    : ['^cmk hook .*', '^cmk-guard-memory', '^cmk remember .*', '^cmk search .*'];
+  return base;
+}

package/src/kiro-hook-dispatch.mjs

@@ -0,0 +1,115 @@
+// kiro-hook-dispatch.mjs — the `cmk hook <event>` Kiro dispatcher (Task 50.J).
+//
+// ONE entrypoint that both Kiro hook surfaces (IDE .kiro.hook + CLI agent-config)
+// call: `cmk hook <event>` with the Kiro hook payload on stdin. It fans out by
+// event to the kit's EXISTING inject/capture logic (injectContext / captureTurn —
+// the same cores the Claude-Code cmk-inject-context / cmk-capture-turn bins use),
+// so memory logic is shared cross-agent and only the per-agent payload adapter
+// differs.
+//
+// Kiro lifecycle events → kit operation:
+//   agentSpawn               → inject  (runs once, cached whole-conversation = SessionStart)
+//   promptSubmit /           → inject  (per-prompt recall). The IDE .kiro.hook surface
+//     userPromptSubmit                  emits `promptSubmit`; the Amazon-Q/CLI Rust contract
+//                                       names the same trigger `userPromptSubmit`. BOTH are
+//                                       recognized so the dispatcher is vocabulary-agnostic
+//                                       across the two hook surfaces (the I-1 composition fix:
+//                                       the CLI agent-config currently wires only
+//                                       agentSpawn+stop by design — inject-once is sufficient
+//                                       since agentSpawn caches the whole-conversation inject —
+//                                       but if a future CLI agent wires the contract's
+//                                       userPromptSubmit trigger, it routes to inject, not no-op).
+//   stop                     → capture (turn-end, the deterministic capture spine)
+//   <anything else>          → no-op   (forward-compatible: a new Kiro event never crashes)
+//
+// CRITICAL INVARIANT: always exit 0. A non-zero exit from a Kiro hook can break
+// the session (the PILOT caveat — aws-bash-hooks §6). Every error is caught,
+// reported on stderr, and the exit code stays 0. Memory capture is best-effort;
+// a failed capture must never take the user's Kiro session down with it.
+//
+// Public surface:
+//   dispatchKiroHook({ event, payload, cwd, userDir?, deps }) →
+//     { action: 'inject'|'capture'|'noop'|'error', exitCode: 0, stdout?, stderr? }
+//   `deps.inject` / `deps.capture` are REQUIRED — this is a pure router. The
+//   cmk-hook bin wires the real injectContext / captureTurn (top-level await
+//   import); tests pass fakes. Keeping the router dep-free makes it trivially
+//   testable and keeps the inject/capture cores out of the no-op event path.
+
+// `promptSubmit` (IDE .kiro.hook) and `userPromptSubmit` (Amazon-Q Rust contract)
+// are the SAME trigger under two surface vocabularies — both map to inject.
+const INJECT_EVENTS = new Set(['agentSpawn', 'promptSubmit', 'userPromptSubmit']);
+const CAPTURE_EVENTS = new Set(['stop']);
+// 50.N.1 — the prompt-submit events that ALSO capture the prompt (the <private>
+// -strip + transcript-append half of Claude Code's UserPromptSubmit). An explicit
+// ALLOW-set (not "INJECT minus agentSpawn") so a future inject-only event added to
+// INJECT_EVENTS never silently starts calling capturePrompt with no prompt.
+const PROMPT_CAPTURE_EVENTS = new Set(['promptSubmit', 'userPromptSubmit']);
+// preToolUse → the memory delete-guardrail (D-192). The ONE event that may exit
+// NON-zero: a non-zero preToolUse exit BLOCKS the Kiro tool (verified — the same
+// mechanism the always-exit-0 invariant exists for). The guard exits 2 ONLY on a
+// deliberate block; everything else (incl. a crashed guard via the catch) exits 0.
+const GUARD_EVENTS = new Set(['preToolUse']);
+// 50.N.2 — postToolUse → observe (the file-edit observation leg, matching Claude
+// Code's PostToolUse → cmk-observe-edit). Kiro's file-write tool is `fs_write`
+// (not Write/Edit); the runHook adapter maps the Kiro tool name + reads the path.
+const OBSERVE_EVENTS = new Set(['postToolUse']);
+
+export function dispatchKiroHook({ event, payload = {}, cwd, userDir, deps = {} } = {}) {
+  const { inject, capture, capturePrompt, observe, guard } = deps;
+
+  try {
+    if (INJECT_EVENTS.has(event)) {
+      // The prompt-submit events (promptSubmit / userPromptSubmit) do BOTH inject
+      // (recall) AND capturePrompt — the <private>-strip + transcript-append half,
+      // matching Claude Code's UserPromptSubmit (cmk-capture-prompt). agentSpawn is
+      // inject-only (no prompt to capture). capturePrompt is BEST-EFFORT: a throw
+      // must never break inject or the session (50.N.1). Older installs without
+      // the dep skip it cleanly.
+      if (PROMPT_CAPTURE_EVENTS.has(event) && typeof capturePrompt === 'function') {
+        try {
+          capturePrompt({ payload, projectRoot: cwd, ...(userDir ? { userDir } : {}) });
+        } catch (err) {
+          // swallow — capture is best-effort; inject below still runs.
+          process.stderr.write(`cmk hook ${event}: capturePrompt failed: ${err?.message ?? err}\n`);
+        }
+      }
+      const r = inject({ cwd, ...(userDir ? { userDir } : {}) });
+      // injectContext returns the text to surface as context; print on stdout so
+      // Kiro adds it to the agent's context (the runCommand→stdout→context path).
+      const stdout = r && typeof r.text === 'string' ? r.text : '';
+      return { action: 'inject', exitCode: 0, stdout };
+    }
+    if (OBSERVE_EVENTS.has(event)) {
+      // postToolUse → observe (the file-edit observation leg). Best-effort like
+      // capture; a throw must never wedge the tool/session. Older installs (no
+      // observe dep) skip cleanly → noop. The runHook adapter maps Kiro's tool
+      // name (fs_write → Write) before observeEdit's eligibility check.
+      if (typeof observe === 'function') {
+        observe({ payload, projectRoot: cwd, ...(userDir ? { userDir } : {}) });
+        return { action: 'observe', exitCode: 0 };
+      }
+      return { action: 'noop', exitCode: 0 };
+    }
+    if (CAPTURE_EVENTS.has(event)) {
+      capture({ payload, projectRoot: cwd, ...(userDir ? { userDir } : {}) });
+      return { action: 'capture', exitCode: 0 };
+    }
+    if (GUARD_EVENTS.has(event)) {
+      // guard() inspects the about-to-run tool command (from the Kiro payload)
+      // and returns { block, reason? }. A block → exit 2 (BLOCK the tool) with
+      // the reason on stderr; otherwise exit 0 (allow). If guard is not wired
+      // (older install), default to allow — fail-open, never block by accident.
+      const v = guard ? guard({ payload, cwd }) : { block: false };
+      if (v && v.block) {
+        return { action: 'blocked', exitCode: 2, stderr: v.reason ?? 'blocked by the memory delete-guardrail' };
+      }
+      return { action: 'allow', exitCode: 0 };
+    }
+    // unknown / not-yet-handled event — no-op, forward-compatible.
+    return { action: 'noop', exitCode: 0 };
+  } catch (err) {
+    // NEVER propagate — exit 0 with the error on stderr so the Kiro session lives.
+    // (A CRASHED guard fails OPEN here: a broken guardrail must not wedge the tool.)
+    return { action: 'error', exitCode: 0, stderr: `cmk hook ${event}: ${err?.message ?? err}` };
+  }
+}