@lh8ppl/claude-memory-kit 0.3.5 → 0.4.0

package/src/install-kiro.mjs

@@ -0,0 +1,287 @@
+// install-kiro.mjs — the Kiro orchestrator, all surfaces (Task 50, D-182).
+//
+// Kiro needs its OWN installer branch (D-182): the generic installAgent assumed
+// a Claude-Code-shaped model (one settings file + one instruction file) that
+// doesn't fit Kiro's distinct surfaces. This composes the verified surface
+// modules:
+//   MCP       → .kiro/settings/mcp.json (mcpServers.cmk) via mutateAgentConfig
+//   steering  → .kiro/steering/cmk.md (inclusion: always), managed marker block
+//   skills    → .kiro/skills/{memory-search,memory-write}/ via installKiroSkills
+//   IDE hooks → .kiro/hooks/cmk-{capture,inject}.kiro.hook via installKiroIdeHooks
+//   CLI agent → ~/.kiro/agents/cmk.json + ~/.kiro/settings/cli.json (agentSpawn/stop hooks + default-agent
+//               default-agent) via installKiroCliAgent — for kiro-cli users
+//
+// IDE hooks auto-fire with no agent selection; the CLI agent needs cmk to be the
+// default agent (guarded — never clobbers a user's existing default). Both hook
+// surfaces reuse the SAME `cmk hook <event>` dispatcher (the shared core).
+//
+// Each leg reuses the kit's safe primitives: mutateAgentConfig (touch-only-our-
+// keys, refuse-to-clobber-on-parse-error), managed marker blocks (byte-preserve),
+// and the skills/hooks copiers (idempotent, remove-only-ours on uninstall).
+//
+// Public surface:
+//   installKiro({ projectRoot, awsDir? }) → { action, changed, surfaces, cliDefaultAgent, errors? }
+//   uninstallKiro({ projectRoot, awsDir? }) → { action, changed }
+//   (awsDir is the kept-for-back-compat alias for the CLI-agent sandbox base —
+//    it sandboxes the CLI-agent leg in tests; production writes the real ~/.kiro
+//    [agents/cmk.json + settings/cli.json], NOT ~/.aws. The name predates the
+//    D-198 ~/.aws→~/.kiro relocation; MEMORY_KIT_KIRO_DIR is the current env var.)
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { mutateAgentConfig } from './mutate-agent-config.mjs';
+import { installKiroSkills, uninstallKiroSkills } from './kiro-skills.mjs';
+import { installKiroIdeHooks, uninstallKiroIdeHooks } from './kiro-ide-hooks.mjs';
+import { installKiroCliAgent, uninstallKiroCliAgent } from './kiro-cli-agent.mjs';
+import { installKiroTrustedCommands, uninstallKiroTrustedCommands } from './kiro-trusted-commands.mjs';
+import { installKiroPermissions, uninstallKiroPermissions } from './kiro-permissions.mjs';
+import {
+  writeManagedBlock,
+  removeManagedBlock,
+  removeJsonKey,
+  pruneEmptyParent,
+} from './managed-block.mjs';
+
+const MCP_PATH = ['settings', 'mcp.json'];
+const MCP_SERVERS_KEY = 'mcpServers';
+const MCP_SERVER_NAME = 'claude-memory-kit';
+// autoApprove pre-approves the kit's MCP tools so Kiro runs them WITHOUT a
+// per-call "Reject / Trust / Run" prompt (found live in cut-gate-kiro Session 1:
+// Kiro gates MCP TOOL calls separately from the shell-command hooks D-194 wired,
+// so mk_remember etc. prompted every time). Verified shape from kiro.dev/docs/mcp:
+// an `autoApprove` array of bare tool names INSIDE the server entry. Explicit
+// list of the 11 kit tools — scoped to OUR tools, never a `"*"` wildcard (which
+// would auto-approve any tool the server ever adds). mk_forget is safe to
+// auto-approve the CALL: it has its own two-step confirm-token before deleting.
+// MCP_AUTO_APPROVE now lives in the leaf kiro-constants.mjs (shared with
+// kiro-permissions, no import cycle); imported for local use + re-exported for
+// back-compat (existing importers of install-kiro.MCP_AUTO_APPROVE keep working).
+import { MCP_AUTO_APPROVE } from './kiro-constants.mjs';
+export { MCP_AUTO_APPROVE };
+// The MCP entry for `.kiro/settings/mcp.json` — the KIRO IDE's MCP surface (the
+// IDE wires MCP tools to the chat; the kiro-cli agent sets includeMcpJson:false
+// and does NOT use MCP — it uses the `cmk remember`/`cmk search` shell commands).
+// `cmk mcp serve` resolves its project from CLAUDE_PROJECT_DIR (Claude Code) or
+// the launch cwd; the IDE launches from the workspace, so no per-project arg is
+// needed here (the IDE worked without one).
+const MCP_ENTRY = Object.freeze({
+  type: 'stdio',
+  command: 'cmk',
+  args: ['mcp', 'serve'],
+  autoApprove: MCP_AUTO_APPROVE,
+});
+
+const STEERING_PATH = ['steering', 'cmk.md'];
+const STEERING_FRONTMATTER = '---\ninclusion: always\n---\n\n';
+const MEMORY_BODY = [
+  '# claude-memory-kit',
+  '',
+  'This project uses claude-memory-kit for durable, in-repo memory across sessions.',
+  'Recall before re-deriving: run `cmk search "<topic>"` for prior decisions,',
+  'preferences, and project facts; the curated tiers live under `context/`.',
+  'Capture durable facts with `cmk remember` — never hand-edit the memory files.',
+].join('\n');
+const STEERING_BODY = MEMORY_BODY;
+
+// AGENTS.md — Kiro's real, always-loaded instruction file (kiro.dev/docs/steering:
+// auto-included from the project root, no inclusion modes). The CLI agent-config's
+// `prompt: file://AGENTS.md` resolves to THIS (D-188). A managed block so it
+// coexists with any user AGENTS.md content; no frontmatter (AGENTS.md is the
+// cross-tool standard — inclusion modes are a Kiro-steering-only feature).
+const AGENTS_MD_PATH = 'AGENTS.md';
+const AGENTS_MD_BODY = MEMORY_BODY;
+
+export function installKiro({ projectRoot, awsDir } = {}) {
+  if (!projectRoot) throw new Error('installKiro: projectRoot is required');
+  const kiro = (parts) => join(projectRoot, '.kiro', ...parts);
+
+  const surfaces = [];
+  const errors = [];
+  const warnings = []; // non-fatal surface failures (e.g. a corrupt user .vscode/settings.json)
+  let changed = false;
+  let cliDefaultAgent = null;
+
+  // ── MCP ──────────────────────────────────────────────────────────────────
+  const mcp = mutateAgentConfig({
+    path: kiro(MCP_PATH),
+    format: 'json',
+    keyPath: [MCP_SERVERS_KEY, MCP_SERVER_NAME],
+    entry: MCP_ENTRY,
+  });
+  if (mcp.action === 'error') {
+    errors.push({ surface: 'mcp', ...mcp });
+  } else {
+    surfaces.push('mcp');
+    if (mcp.changed) changed = true;
+  }
+
+  // If MCP refused (corrupt config), halt — report, don't push past it.
+  if (errors.length > 0) {
+    return { action: 'error', changed, surfaces, errors };
+  }
+
+  // ── steering ───────────────────────────────────────────────────────────────
+  if (writeManagedBlock(kiro(STEERING_PATH), { body: STEERING_BODY, frontmatter: STEERING_FRONTMATTER })) changed = true;
+  surfaces.push('steering');
+
+  // ── AGENTS.md (project root) — Kiro's always-loaded instruction file; the CLI
+  //    agent-config's prompt:file://AGENTS.md points here (D-188). Managed block,
+  //    no frontmatter. Coexists with a Claude-Code CLAUDE.md (each agent reads
+  //    its own) and with any user-authored AGENTS.md content.
+  if (writeManagedBlock(join(projectRoot, AGENTS_MD_PATH), { body: AGENTS_MD_BODY })) changed = true;
+  surfaces.push('agents-md');
+
+  // ── skills ───────────────────────────────────────────────────────────────
+  const skills = installKiroSkills({ projectRoot });
+  if (skills.changed) changed = true;
+  surfaces.push('skills');
+
+  // ── IDE hooks ──────────────────────────────────────────────────────────────
+  const hooks = installKiroIdeHooks({ projectRoot });
+  if (hooks.changed) changed = true;
+  surfaces.push('ide-hooks');
+
+  // ── trusted commands (D-194) — pre-trust the kit's hook commands in the
+  //    workspace .vscode/settings.json so Kiro auto-runs them instead of
+  //    prompting "Run / Reject" on every hook fire. Without this the IDE hooks
+  //    above are wired but not silent. Array-union (preserves a user's existing
+  //    trustedCommands); refuse-to-clobber a corrupt settings.json.
+  //
+  //    NON-FATAL on error, UNLIKE the MCP leg above (skill-review I1): MCP is the
+  //    FIRST surface (a corrupt MCP config → clean abort, nothing written yet).
+  //    Trust runs LAST-but-one, after MCP/steering/AGENTS.md/skills/ide-hooks all
+  //    succeeded — and it's the LEAST critical surface (if it can't write, the
+  //    hooks still fire, they just prompt). So a user's pre-existing malformed
+  //    .vscode/settings.json must NOT abort an otherwise-good install: record the
+  //    warning, skip the surface, and continue to the CLI agent.
+  const trust = installKiroTrustedCommands({ projectRoot });
+  if (trust.action === 'error') {
+    warnings.push({ surface: 'trusted-commands', ...trust });
+  } else {
+    if (trust.changed) changed = true;
+    surfaces.push('trusted-commands');
+  }
+
+  // ── IDE-1.0 permissions (50.N.5 / D-203h/i) — Kiro IDE 1.0's AUTHORITATIVE trust
+  //    is ~/.kiro/workspace-roots/<hash>/permissions.yaml (NOT .vscode; Kiro
+  //    migrates .vscode into it). The `.vscode` trustedCommands above keep 0.x +
+  //    pre-migration working; this pre-trusts the kit's shell + mcp + SKILL on 1.0
+  //    so even the first memory-write skill-load runs prompt-free (the one thing
+  //    `.vscode` has NO setting for). Best-effort like trusted-commands — a write
+  //    failure never aborts the install.
+  let permissions;
+  try {
+    permissions = installKiroPermissions({ projectRoot });
+    if (permissions.changed) changed = true;
+    surfaces.push('permissions');
+  } catch (err) {
+    warnings.push({ surface: 'permissions', action: 'error', error: err?.message ?? String(err) });
+  }
+
+  // ── CLI agent-config (kiro-cli, user-tier) — agentSpawn/stop hooks + the
+  //    guarded default-agent. Covers terminal `kiro-cli` users; the IDE hooks
+  //    above cover the GUI. Both reuse the same `cmk hook` dispatcher.
+  const cli = installKiroCliAgent({ awsDir });
+  cliDefaultAgent = cli.defaultAgent; // 'set' | 'skipped-existing'
+  if (cli.changed) changed = true;
+  surfaces.push('cli-agent');
+
+  const result = { action: 'installed', changed, surfaces, cliDefaultAgent };
+  if (warnings.length > 0) result.warnings = warnings;
+  return result;
+}
+
+export function uninstallKiro({ projectRoot, awsDir } = {}) {
+  if (!projectRoot) throw new Error('uninstallKiro: projectRoot is required');
+  const kiro = (parts) => join(projectRoot, '.kiro', ...parts);
+  let changed = false;
+
+  // MCP: remove only our server key, prune an emptied servers object.
+  const mcpPath = kiro(MCP_PATH);
+  const mcpTouched = removeJsonKey(mcpPath, [MCP_SERVERS_KEY, MCP_SERVER_NAME]);
+  if (mcpTouched) changed = true;
+  pruneEmptyParent(mcpPath, [MCP_SERVERS_KEY]);
+
+  // steering: strip our marker block (byte-preserve the rest).
+  const steeringPath = kiro(STEERING_PATH);
+  const steeringTouched = removeManagedBlock(steeringPath);
+  if (steeringTouched) changed = true;
+
+  // AGENTS.md: strip our marker block only (a user's own AGENTS.md content,
+  // outside our markers, is byte-preserved).
+  const agentsMdPath = join(projectRoot, AGENTS_MD_PATH);
+  const agentsMdTouched = removeManagedBlock(agentsMdPath);
+  if (agentsMdTouched) changed = true;
+
+  // No husks (D-191): a file the kit created that uninstall just emptied —
+  // an empty AGENTS.md, a `{}` mcp.json, a frontmatter-only steering file —
+  // should be removed, not left as a confusing shell. removeIfHusk deletes
+  // ONLY when no user content remains. GATED on "the kit's removal step actually
+  // changed THIS file" (B2 defense-in-depth) — so a pristine, never-kit-managed
+  // file is never even a deletion candidate, narrowing the blast radius.
+  if (agentsMdTouched && removeIfHusk(agentsMdPath)) changed = true;
+  if (steeringTouched && removeIfHusk(steeringPath)) changed = true;
+  if (mcpTouched && removeIfHusk(mcpPath)) changed = true;
+
+  // skills + IDE hooks + CLI agent-config: remove our files only.
+  if (uninstallKiroSkills({ projectRoot }).changed) changed = true;
+  if (uninstallKiroIdeHooks({ projectRoot }).changed) changed = true;
+  if (uninstallKiroCliAgent({ awsDir }).changed) changed = true;
+
+  // trusted commands (D-194): remove ONLY our patterns from
+  // .vscode/settings.json, preserving the user's; prune an emptied key.
+  if (uninstallKiroTrustedCommands({ projectRoot }).changed) changed = true;
+
+  // IDE-1.0 permissions (50.N.5): remove ONLY our rules from
+  // ~/.kiro/workspace-roots/<hash>/permissions.yaml, preserving the user's.
+  // Best-effort (the file is per-user, may be absent); never abort uninstall.
+  try {
+    if (uninstallKiroPermissions({ projectRoot }).changed) changed = true;
+  } catch {
+    /* best-effort — a missing/locked permissions.yaml never blocks uninstall */
+  }
+
+  return { action: 'uninstalled', changed };
+}
+
+// Is `trimmed` ONLY a YAML frontmatter block (opener `---`, a closing `---`,
+// and nothing but blank lines after the FIRST closing fence)? Line-scan, not a
+// backtracking regex (the managed-block.mjs ReDoS-safe-string-utils discipline)
+// — AND, critically, the closing fence must be the FIRST `---` after the opener
+// with nothing meaningful after it. A naive `---[\s\S]*?---$` regex backtracks
+// to a LATER `---` (a user's horizontal rule) and would match — then DELETE — a
+// file full of user prose bordered by `---` (the skill-review B1 data-loss bug).
+function isOnlyFrontmatter(trimmed) {
+  const lines = trimmed.split(/\r?\n/);
+  if (lines[0] !== '---') return false;
+  const close = lines.indexOf('---', 1);
+  if (close === -1) return false;
+  // nothing but blank lines may follow the first closing fence
+  return lines.slice(close + 1).every((l) => l.trim() === '');
+}
+
+// Delete a file the kit created IFF uninstall left it with no real content —
+// i.e. it's now empty, an empty JSON object (`{}`), or only YAML frontmatter.
+// Anything else (user prose, a sibling MCP server, user frontmatter+body) means
+// real content remains → keep the file. Conservative by construction: a
+// non-husk is never touched. Returns true if a file was removed.
+// (D-191 — no empty husks after a Kiro uninstall; B1-fixed predicate.)
+function removeIfHusk(path) {
+  if (!existsSync(path)) return false;
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    return false;
+  }
+  const trimmed = raw.trim();
+  if (trimmed === '' || trimmed === '{}' || isOnlyFrontmatter(trimmed)) {
+    try {
+      rmSync(path, { force: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}

package/src/install.mjs

@@ -371,8 +371,13 @@ export async function install(options = {}) {
   // design §1.3. Same boundary as the tiers: idempotent skip-existing +
   // over-mutation-safe (a hand-edited skill survives a re-install). The skill
   // files carry no {{placeholders}}, so renderTemplate is a byte-passthrough.
+  //
+  // `.claude/skills/` is CLAUDE-CODE-SPECIFIC. A `--ide kiro` install gets its
+  // skills at `.kiro/skills/` (written by the Kiro orchestrator), so it passes
+  // skipClaudeFiles to avoid leaving a dead Claude skills dir on a Kiro project
+  // (the cut-gate find: a Kiro user shouldn't carry Claude Code's skill files).
   const skillsSrc = join(templateDir, '.claude', 'skills');
-  if (existsSync(skillsSrc)) {
+  if (!options.skipClaudeFiles && existsSync(skillsSrc)) {
     installTier(skillsSrc, join(projectRoot, '.claude', 'skills'), {
       created,
       skipped,
@@ -389,10 +394,18 @@ export async function install(options = {}) {
 
   // CLAUDE.md loader block — Task 4. Read the block content from the kit's
   // template/ and inject (or refresh) it inside marker delimiters. Never
-  // touches content outside the markers.
+  // touches content outside the markers. CLAUDE.md is CLAUDE-CODE-SPECIFIC
+  // (Kiro reads AGENTS.md + steering, not CLAUDE.md) — a --ide kiro install
+  // passes skipClaudeFiles so it doesn't drop a CLAUDE.md the Kiro user can't
+  // use (D-188). An EXISTING CLAUDE.md from a prior Claude-Code install is left
+  // untouched regardless (we simply don't write a fresh one).
   const claudeMdTemplatePath = join(templateDir, 'CLAUDE.md.template');
   let claudeMd = { action: 'skipped', path: join(projectRoot, 'CLAUDE.md') };
-  if (existsSync(claudeMdTemplatePath)) {
+  if (options.skipClaudeFiles) {
+    // a non-Claude-Code (--ide kiro) install: CLAUDE.md is intentionally not
+    // written; an existing one is left untouched. NOT an error.
+    claudeMd = { action: 'skipped', reason: 'non-claude-code-agent', path: join(projectRoot, 'CLAUDE.md') };
+  } else if (existsSync(claudeMdTemplatePath)) {
     const content = readFileSync(claudeMdTemplatePath, 'utf8');
     try {
       claudeMd = injectClaudeMdBlock({ projectRoot, content, version, force });

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',
+]);