gitnexushub 0.6.0 → 0.7.1

package/dist/cli-helpers.js

@@ -12,11 +12,13 @@ import { claudeCodeEditor } from './editors/claude-code.js';
 import { cursorEditor } from './editors/cursor.js';
 import { windsurfEditor } from './editors/windsurf.js';
 import { opencodeEditor } from './editors/opencode.js';
+import { kiroEditor } from './editors/kiro.js';
 export const EDITORS = {
     'claude-code': claudeCodeEditor,
     cursor: cursorEditor,
     windsurf: windsurfEditor,
     opencode: opencodeEditor,
+    kiro: kiroEditor,
 };
 export const ok = (msg) => console.log(`  ${pc.green('✔')} ${msg}`);
 export const info = (msg) => console.log(`  ${pc.cyan('ℹ')} ${msg}`);

package/dist/connect-command.js

@@ -13,7 +13,7 @@ import { generateConnectContext } from './content.js';
 import { isGitRepo, getGitRemoteUrl, parseGitRemote, matchRepo } from './project.js';
 import { writeProjectContext } from './context.js';
 import { detectInstalledEditors } from './editors/detect.js';
-import { installClaudeCodeHook, installCursorHook, installOpenCodeHook, } from './hooks-installer.js';
+import { installClaudeCodeHook, installCursorHook, installKiroHook, installOpenCodeHook, } from './hooks-installer.js';
 import { ok, info, warn, fail, resolveAuth, EDITORS } from './cli-helpers.js';
 /**
  * Resolve the path to the shipped hook script (`gitnexus-enterprise-hook.cjs`).
@@ -65,7 +65,7 @@ export async function runConnect(tokenArg, opts) {
         }
         else {
             fail('No editor detected. Please specify one:');
-            console.error(`      ${pc.cyan('--editor claude-code | cursor | windsurf | opencode')}`);
+            console.error(`      ${pc.cyan('--editor claude-code | cursor | windsurf | opencode | kiro')}`);
             console.error('');
             return process.exit(1);
         }
@@ -116,6 +116,10 @@ export async function runConnect(tokenArg, opts) {
                 await installOpenCodeHook({ hookScriptPath });
                 ok('Hooks installed');
             }
+            else if (editorId === 'kiro') {
+                await installKiroHook({ hookScriptPath });
+                ok('Hooks installed');
+            }
             // windsurf: no hook system, skip silently
         }
         catch (err) {

package/dist/context.js

@@ -5,7 +5,7 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
-import { upsertMarkedSection, removeMarkedSection } from './utils.js';
+import { upsertMarkedSection, removeMarkedSection, fileExists } from './utils.js';
 export async function writeProjectContext(projectDir, ctx) {
     const files = [];
     // Write CLAUDE.md
@@ -16,6 +16,31 @@ export async function writeProjectContext(projectDir, ctx) {
     const agentsPath = path.join(projectDir, 'AGENTS.md');
     const agentsResult = await upsertMarkedSection(agentsPath, ctx.agentsMd);
     files.push(`AGENTS.md (${agentsResult})`);
+    // Write Kiro steering doc — Kiro doesn't read AGENTS.md / CLAUDE.md,
+    // so we mirror the same content into .kiro/steering/gitnexus.md with
+    // `inclusion: always` frontmatter so it's loaded into every Kiro
+    // chat in this workspace.
+    //
+    // Unlike CLAUDE.md / AGENTS.md (which may carry hand-written user
+    // content alongside the gitnexus block), this file is dedicated to
+    // gitnexus — it's named gitnexus.md, lives in a gitnexus-managed
+    // path, and isn't expected to host anything else. So we rewrite the
+    // whole file every run instead of using upsertMarkedSection. The
+    // previous marker-based approach broke because the YAML frontmatter
+    // sat *outside* the gitnexus markers (Kiro requires frontmatter on
+    // line 1), so each re-run's "before" prefix re-included the existing
+    // frontmatter and stacked another copy on top — Bugbot caught the
+    // accumulation on commit de24e98c.
+    const kiroSteeringPath = path.join(projectDir, '.kiro', 'steering', 'gitnexus.md');
+    const kiroBody = `---\n` +
+        `inclusion: always\n` +
+        `description: GitNexus code intelligence — graph-backed query, context, and impact tools\n` +
+        `---\n\n` +
+        `${ctx.agentsMd}\n`;
+    const kiroExisted = await fileExists(kiroSteeringPath);
+    await fs.mkdir(path.dirname(kiroSteeringPath), { recursive: true });
+    await fs.writeFile(kiroSteeringPath, kiroBody, 'utf-8');
+    files.push(`.kiro/steering/gitnexus.md (${kiroExisted ? 'updated' : 'created'})`);
     // Write skills to .claude/skills/gitnexus/
     if (ctx.skills.length > 0) {
         const skillsDir = path.join(projectDir, '.claude', 'skills', 'gitnexus');
@@ -30,13 +55,27 @@ export async function writeProjectContext(projectDir, ctx) {
 }
 export async function removeProjectContext(projectDir) {
     const removed = [];
-    // Remove marked sections from CLAUDE.md and AGENTS.md
+    // CLAUDE.md / AGENTS.md may carry user content; only strip the
+    // gitnexus-marked block.
     for (const name of ['CLAUDE.md', 'AGENTS.md']) {
         const filePath = path.join(projectDir, name);
         if (await removeMarkedSection(filePath)) {
             removed.push(name);
         }
     }
+    // The Kiro steering doc is dedicated to gitnexus (no user content
+    // ever lives here, no markers are written), so delete the file
+    // outright when it exists.
+    const kiroSteeringPath = path.join(projectDir, '.kiro', 'steering', 'gitnexus.md');
+    if (await fileExists(kiroSteeringPath)) {
+        try {
+            await fs.unlink(kiroSteeringPath);
+            removed.push('.kiro/steering/gitnexus.md');
+        }
+        catch {
+            // Already gone
+        }
+    }
     // Remove .claude/skills/gitnexus/ directory
     const skillsDir = path.join(projectDir, '.claude', 'skills', 'gitnexus');
     try {

package/dist/editors/detect.js

@@ -27,6 +27,11 @@ const PROBES = [
         name: 'OpenCode',
         dirs: [path.join(os.homedir(), '.config', 'opencode')],
     },
+    {
+        id: 'kiro',
+        name: 'Kiro',
+        dirs: [path.join(os.homedir(), '.kiro')],
+    },
 ];
 export async function detectInstalledEditors() {
     const found = [];

package/dist/editors/kiro.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Kiro Editor Setup
+ *
+ * Writes MCP config to ~/.kiro/settings/mcp.json
+ * Installs skill content as steering files in ~/.kiro/steering/
+ *
+ * Kiro (kiro.dev) doesn't have a SKILL.md system like Claude Code or
+ * Cursor — its closest concept is "steering" (always-on guidance docs
+ * with optional frontmatter for fileMatch / manual inclusion modes).
+ * We emit each Hub skill as `~/.kiro/steering/gitnexus-<name>.md` with
+ * `inclusion: manual` so the user pulls them in via `#gitnexus-<name>`
+ * in chat — same mental model as `/gitnexus-<name>` in Claude Code.
+ */
+import type { EditorConfig } from './types.js';
+export declare const kiroEditor: EditorConfig;

package/dist/editors/kiro.js

@@ -0,0 +1,118 @@
+/**
+ * Kiro Editor Setup
+ *
+ * Writes MCP config to ~/.kiro/settings/mcp.json
+ * Installs skill content as steering files in ~/.kiro/steering/
+ *
+ * Kiro (kiro.dev) doesn't have a SKILL.md system like Claude Code or
+ * Cursor — its closest concept is "steering" (always-on guidance docs
+ * with optional frontmatter for fileMatch / manual inclusion modes).
+ * We emit each Hub skill as `~/.kiro/steering/gitnexus-<name>.md` with
+ * `inclusion: manual` so the user pulls them in via `#gitnexus-<name>`
+ * in chat — same mental model as `/gitnexus-<name>` in Claude Code.
+ */
+import os from 'os';
+import path from 'path';
+import fs from 'fs/promises';
+import { readJsonFile, writeJsonFile } from '../utils.js';
+import { HUB_SKILLS } from '../content.js';
+import { computeFingerprint, getDeviceName } from '../fingerprint.js';
+function getMcpConfig(hubUrl, token) {
+    // Kiro's `~/.kiro/settings/mcp.json` is documented at
+    // kiro.dev/docs/mcp/configuration. Remote HTTP MCP servers are
+    // identified by the presence of `url`. `disabled: false` and the
+    // `autoApprove` array are optional — we leave them off so Kiro
+    // falls back to its sensible defaults (auto-approval prompts on
+    // first call).
+    return {
+        url: `${hubUrl}/mcp`,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'X-Device-Fingerprint': computeFingerprint(),
+            'X-Device-Name': getDeviceName(),
+        },
+    };
+}
+async function configure(hubUrl, token) {
+    const mcpPath = path.join(os.homedir(), '.kiro', 'settings', 'mcp.json');
+    try {
+        const existing = (await readJsonFile(mcpPath)) || {};
+        if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
+            existing.mcpServers = {};
+        }
+        const overrodeCli = !!(existing.mcpServers.gitnexus && 'command' in existing.mcpServers.gitnexus);
+        existing.mcpServers.gitnexus = getMcpConfig(hubUrl, token);
+        await writeJsonFile(mcpPath, existing);
+        return { success: true, message: 'MCP configured in ~/.kiro/settings/mcp.json', overrodeCli };
+    }
+    catch (err) {
+        return { success: false, message: `Failed: ${err.message}` };
+    }
+}
+/**
+ * Wrap raw skill content in a steering frontmatter block so Kiro
+ * treats it as a manually-included guidance doc. Without the
+ * `inclusion: manual` line Kiro defaults to `always`, which would
+ * shove every GitNexus skill into every chat turn — far too noisy.
+ */
+function toSteeringDoc(name, body) {
+    return `---
+inclusion: manual
+description: ${name} (GitNexus skill — invoke via #${name})
+---
+
+${body.trim()}
+`;
+}
+async function installSkills(skills) {
+    const steeringDir = path.join(os.homedir(), '.kiro', 'steering');
+    let installed = 0;
+    await fs.mkdir(steeringDir, { recursive: true });
+    for (const skill of skills) {
+        try {
+            const filePath = path.join(steeringDir, `${skill.name}.md`);
+            await fs.writeFile(filePath, toSteeringDoc(skill.name, skill.content), 'utf-8');
+            installed++;
+        }
+        catch {
+            // Skip on error
+        }
+    }
+    return installed;
+}
+async function unconfigure() {
+    const mcpPath = path.join(os.homedir(), '.kiro', 'settings', 'mcp.json');
+    try {
+        const existing = await readJsonFile(mcpPath);
+        if (existing?.mcpServers?.gitnexus) {
+            delete existing.mcpServers.gitnexus;
+            await writeJsonFile(mcpPath, existing);
+        }
+        return { success: true, message: 'MCP removed from ~/.kiro/settings/mcp.json' };
+    }
+    catch (err) {
+        return { success: false, message: `Failed: ${err.message}` };
+    }
+}
+async function removeSkills() {
+    const steeringDir = path.join(os.homedir(), '.kiro', 'steering');
+    let removed = 0;
+    for (const name of HUB_SKILLS) {
+        try {
+            await fs.rm(path.join(steeringDir, `${name}.md`), { force: true });
+            removed++;
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    return removed;
+}
+export const kiroEditor = {
+    id: 'kiro',
+    name: 'Kiro',
+    configure,
+    unconfigure,
+    installSkills,
+    removeSkills,
+};

package/dist/editors/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Editor Types
  */
-export type EditorId = 'claude-code' | 'cursor' | 'windsurf' | 'opencode';
+export type EditorId = 'claude-code' | 'cursor' | 'windsurf' | 'opencode' | 'kiro';
 export interface EditorConfig {
     id: EditorId;
     name: string;

package/dist/hooks-installer.d.ts

@@ -10,6 +10,22 @@ export interface InstallOptions {
     homeDir?: string;
     /** Absolute path to the shipped hook script. */
     hookScriptPath: string;
+    /**
+     * Absolute path to the `node` binary that should run the hook
+     * script. Defaults to `process.execPath` — the node binary
+     * currently running the installer, which is the safest cross-
+     * platform guarantee that the hook spawn will find an interpreter.
+     *
+     * Why this matters: GUI editor processes (Cursor.app on macOS, Kiro
+     * launched from Dock) inherit a minimal `PATH` that often excludes
+     * `~/.local/node/bin`, `/opt/homebrew/bin`, etc. — wherever the
+     * user installed node. A hook command of `node "..."` then fails
+     * to spawn (`/bin/sh: node: command not found`) and the editor
+     * silently marks the hook as failed (Cursor renders this as a
+     * cosmetic red X in the Hooks tab; the hook never runs). Embedding
+     * the absolute path sidesteps PATH entirely. Tests can override.
+     */
+    nodePath?: string;
 }
 /**
  * Install the Claude Code PreToolUse + PostToolUse hooks.
@@ -17,10 +33,57 @@ export interface InstallOptions {
  */
 export declare function installClaudeCodeHook(opts: InstallOptions): Promise<string>;
 /**
- * Install the Cursor beforeShellExecution hook.
+ * Install the Cursor preToolUse + postToolUse hooks.
  * Returns the absolute path to the written hooks.json.
+ *
+ * Cursor 2.4+ hooks live at ~/.cursor/hooks.json with a
+ *   { version: 1, hooks: { <eventName>: [{ command, ... }] } }
+ * shape (cursor.com/docs/hooks). We register `preToolUse` for
+ * graph-context augmentation on Shell/Read/Write, and `postToolUse`
+ * for staleness detection after `git commit/merge/...` and for
+ * edit-closure capture on Edit/Write/MultiEdit.
+ *
+ * The earlier 0.6.0 implementation used `beforeShellExecution`,
+ * which:
+ *   1. fires *before* shell execution — wrong direction for the
+ *      git-staleness post-commit nudge,
+ *   2. sends a different stdin shape (no `tool_name`/`tool_input`),
+ *      so the hook script silently bails on the event check,
+ *   3. has no documented context-injection envelope.
+ * Switching to pre/postToolUse fixes all three.
  */
 export declare function installCursorHook(opts: InstallOptions): Promise<string>;
+/**
+ * Install Kiro hooks — graph-tools nudge (askAgent) + edit-closure
+ * capture (runCommand). Returns the absolute paths to both files.
+ *
+ * Kiro's actual hook schema (verified against a Kiro-UI-generated
+ * file, kiro.dev/docs/hooks notwithstanding) differs in three places
+ * from what 0.7.0 shipped:
+ *
+ *   1. Top-level shape is `{when, then, version, name, enabled}` —
+ *      not the `{trigger, actions[]}` shape we were writing.
+ *   2. Trigger type values are camelCase (`postToolUse`) — not the
+ *      kebab-case (`post-tool-use`) we emitted.
+ *   3. Action type for shell commands is `runCommand` — not `shell`.
+ *
+ * Plus three runtime constraints Kiro disclosed when asked directly:
+ *
+ *   - `runCommand` actions get NO stdin payload, NO env vars for
+ *     tool metadata, and NO `${variable}` substitution. So unlike
+ *     Claude Code / Cursor, the script can't read the just-edited
+ *     file path off stdin — we have to scan the working tree
+ *     ourselves (see runKiroEditCapture in the hook script).
+ *   - `runCommand` stdout is NOT fed back to the agent. Staleness
+ *     nudges and graph-context augmentation are invisible via this
+ *     channel — only `askAgent` actions can inject prompt text.
+ *   - The graph-tools nudge therefore uses `askAgent`; capture uses
+ *     `runCommand` plus the `--kiro-edit-capture` flag.
+ *
+ * `~/.kiro/hooks/` (user-level) IS loaded by Kiro despite some docs
+ * suggesting workspace-only — verified empirically in this session.
+ */
+export declare function installKiroHook(opts: InstallOptions): Promise<string[]>;
 /**
  * Install the OpenCode plugin stub.
  * Returns the absolute path to the written TypeScript file.

package/dist/hooks-installer.js

@@ -11,11 +11,43 @@ import os from 'os';
 function getHome(opts) {
     return opts.homeDir ?? os.homedir();
 }
+function getNode(opts) {
+    return opts.nodePath ?? process.execPath;
+}
 async function writeJsonIdempotent(filePath, obj) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     const body = JSON.stringify(obj, null, 2) + '\n';
     await fs.writeFile(filePath, body);
 }
+/**
+ * Quote a path for embedding in a shell-style command string. The
+ * hook spec across Claude Code / Cursor / Kiro is a literal shell
+ * command, not an argv array — so spaces (`John Doe`) and stray
+ * quotes both have to survive shell parsing. Wraps in `"..."` and
+ * escapes any `"` already inside the path so the shell sees a single
+ * argument.
+ *
+ * Realistic risk of `"` inside the path is near-zero (npm install
+ * dirs, Windows profile dirs), but matching the same defensive quoting
+ * the OSS gitnexus/src/cli/setup.ts uses keeps the two installers
+ * symmetrical.
+ */
+function shellQuote(p) {
+    return `"${p.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Read an existing JSON file, returning null if the file is absent
+ * or unparseable. Used by installers that need to merge into a
+ * shared config rather than clobber it.
+ */
+async function readJsonOrNull(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Install the Claude Code PreToolUse + PostToolUse hooks.
  * Returns the absolute path to the written hooks.json.
@@ -24,11 +56,15 @@ export async function installClaudeCodeHook(opts) {
     const home = getHome(opts);
     const hooksDir = path.join(home, '.claude', 'plugins', 'gitnexus-enterprise', 'hooks');
     const hooksJsonPath = path.join(hooksDir, 'hooks.json');
-    // Double-quote the absolute path so shell splitting doesn't break
-    // when the install dir contains a space (e.g. Windows profiles at
-    // `C:\Users\John Doe\...`). The hook spec is a shell-style command
-    // string, not an argv array, so quoting is the only knob available.
-    const quotedScriptPath = `"${opts.hookScriptPath}"`;
+    // Double-quote (and escape any embedded quotes) so shell splitting
+    // doesn't break when the install dir contains a space (e.g. Windows
+    // profiles at `C:\Users\John Doe\...`). The hook spec is a shell-
+    // style command string, not an argv array, so quoting is the only
+    // knob available. The `--agent=claude-code` flag tells the hook
+    // script which editor it's running under so /api/activity captures
+    // get the right agentName (the stdin payload alone can't
+    // distinguish editors that share the PascalCase MCP event names).
+    const command = `${shellQuote(getNode(opts))} ${shellQuote(opts.hookScriptPath)} --agent=claude-code`;
     const config = {
         hooks: {
             PreToolUse: [
@@ -37,7 +73,7 @@ export async function installClaudeCodeHook(opts) {
                     hooks: [
                         {
                             type: 'command',
-                            command: `node ${quotedScriptPath}`,
+                            command,
                             timeout: 5,
                         },
                     ],
@@ -49,7 +85,7 @@ export async function installClaudeCodeHook(opts) {
                     hooks: [
                         {
                             type: 'command',
-                            command: `node ${quotedScriptPath}`,
+                            command,
                             timeout: 5,
                         },
                     ],
@@ -61,24 +97,120 @@ export async function installClaudeCodeHook(opts) {
     return hooksJsonPath;
 }
 /**
- * Install the Cursor beforeShellExecution hook.
+ * Install the Cursor preToolUse + postToolUse hooks.
  * Returns the absolute path to the written hooks.json.
+ *
+ * Cursor 2.4+ hooks live at ~/.cursor/hooks.json with a
+ *   { version: 1, hooks: { <eventName>: [{ command, ... }] } }
+ * shape (cursor.com/docs/hooks). We register `preToolUse` for
+ * graph-context augmentation on Shell/Read/Write, and `postToolUse`
+ * for staleness detection after `git commit/merge/...` and for
+ * edit-closure capture on Edit/Write/MultiEdit.
+ *
+ * The earlier 0.6.0 implementation used `beforeShellExecution`,
+ * which:
+ *   1. fires *before* shell execution — wrong direction for the
+ *      git-staleness post-commit nudge,
+ *   2. sends a different stdin shape (no `tool_name`/`tool_input`),
+ *      so the hook script silently bails on the event check,
+ *   3. has no documented context-injection envelope.
+ * Switching to pre/postToolUse fixes all three.
  */
 export async function installCursorHook(opts) {
     const home = getHome(opts);
     const hooksJsonPath = path.join(home, '.cursor', 'hooks.json');
-    // Same shell-quoting rationale as installClaudeCodeHook — the
-    // command is a shell string, not argv, so the absolute path must
-    // be quoted to survive spaces.
-    const config = {
-        beforeShellExecution: {
-            command: `node "${opts.hookScriptPath}"`,
-            timeout: 5000,
-        },
-    };
-    await writeJsonIdempotent(hooksJsonPath, config);
+    const command = `${shellQuote(getNode(opts))} ${shellQuote(opts.hookScriptPath)} --agent=cursor`;
+    // Merge into the user's existing ~/.cursor/hooks.json instead of
+    // clobbering it — that file is the GLOBAL Cursor hooks config and
+    // may already carry the user's own audit / lint hooks. Idempotent:
+    // re-running replaces only the gitnexus entries (matched by their
+    // command containing "gitnexus-enterprise-hook") and leaves
+    // unrelated event arrays + entries intact.
+    const existing = (await readJsonOrNull(hooksJsonPath)) || {};
+    if (typeof existing.version !== 'number')
+        existing.version = 1;
+    if (!existing.hooks || typeof existing.hooks !== 'object')
+        existing.hooks = {};
+    function upsertGitNexus(eventName, matcher, timeout) {
+        const arr = Array.isArray(existing.hooks[eventName])
+            ? existing.hooks[eventName]
+            : [];
+        const filtered = arr.filter((e) => !e.command?.includes('--agent=cursor'));
+        filtered.push({ matcher, command, timeout });
+        existing.hooks[eventName] = filtered;
+    }
+    upsertGitNexus('preToolUse', 'Shell|Read|Write', 5);
+    upsertGitNexus('postToolUse', 'Shell|Edit|Write|MultiEdit', 5);
+    await fs.mkdir(path.dirname(hooksJsonPath), { recursive: true });
+    await fs.writeFile(hooksJsonPath, JSON.stringify(existing, null, 2) + '\n');
     return hooksJsonPath;
 }
+/**
+ * Install Kiro hooks — graph-tools nudge (askAgent) + edit-closure
+ * capture (runCommand). Returns the absolute paths to both files.
+ *
+ * Kiro's actual hook schema (verified against a Kiro-UI-generated
+ * file, kiro.dev/docs/hooks notwithstanding) differs in three places
+ * from what 0.7.0 shipped:
+ *
+ *   1. Top-level shape is `{when, then, version, name, enabled}` —
+ *      not the `{trigger, actions[]}` shape we were writing.
+ *   2. Trigger type values are camelCase (`postToolUse`) — not the
+ *      kebab-case (`post-tool-use`) we emitted.
+ *   3. Action type for shell commands is `runCommand` — not `shell`.
+ *
+ * Plus three runtime constraints Kiro disclosed when asked directly:
+ *
+ *   - `runCommand` actions get NO stdin payload, NO env vars for
+ *     tool metadata, and NO `${variable}` substitution. So unlike
+ *     Claude Code / Cursor, the script can't read the just-edited
+ *     file path off stdin — we have to scan the working tree
+ *     ourselves (see runKiroEditCapture in the hook script).
+ *   - `runCommand` stdout is NOT fed back to the agent. Staleness
+ *     nudges and graph-context augmentation are invisible via this
+ *     channel — only `askAgent` actions can inject prompt text.
+ *   - The graph-tools nudge therefore uses `askAgent`; capture uses
+ *     `runCommand` plus the `--kiro-edit-capture` flag.
+ *
+ * `~/.kiro/hooks/` (user-level) IS loaded by Kiro despite some docs
+ * suggesting workspace-only — verified empirically in this session.
+ */
+export async function installKiroHook(opts) {
+    const home = getHome(opts);
+    const hooksDir = path.join(home, '.kiro', 'hooks');
+    const editCaptureCmd = `${shellQuote(getNode(opts))} ${shellQuote(opts.hookScriptPath)} --agent=kiro --kiro-edit-capture`;
+    const preferGraphHookPath = path.join(hooksDir, 'gitnexus-prefer-graph-tools.kiro.hook');
+    const editCaptureHookPath = path.join(hooksDir, 'gitnexus-edit-capture.kiro.hook');
+    // 1. Steer the agent toward graph tools before shell searches.
+    // askAgent is the only Kiro action whose prompt actually reaches
+    // the agent context; runCommand stdout is discarded.
+    await writeJsonIdempotent(preferGraphHookPath, {
+        name: 'gitnexus-prefer-graph-tools',
+        version: '1',
+        enabled: true,
+        description: 'Before running shell searches (grep/find/rg), prefer GitNexus graph tools for richer code context',
+        when: { type: 'preToolUse', toolTypes: ['shell'] },
+        then: {
+            type: 'askAgent',
+            prompt: "Before running this shell command: if it's a search (grep, find, glob, rg), prefer the GitNexus MCP tools instead — `gitnexus_query` for concept search, `gitnexus_context` for symbol lookup, `gitnexus_cypher` for structural queries. Only fall back to shell search if GitNexus can't answer it.",
+        },
+    });
+    // 2. Edit-closure capture. Fires after every write tool. Hook
+    // script runs `git status --porcelain` in the workspace root,
+    // posts each dirty file to /api/activity/edit-observed. Coarser
+    // than Claude Code / Cursor (catches all dirty files, not just
+    // the one the agent just touched) — but it's the only signal
+    // Kiro's hook plumbing exposes.
+    await writeJsonIdempotent(editCaptureHookPath, {
+        name: 'gitnexus-edit-capture',
+        version: '1',
+        enabled: true,
+        description: 'Capture file edits for distillation by scanning the working tree after write tool calls',
+        when: { type: 'postToolUse', toolTypes: ['write'] },
+        then: { type: 'runCommand', command: editCaptureCmd, timeout: 5 },
+    });
+    return [preferGraphHookPath, editCaptureHookPath];
+}
 /**
  * Install the OpenCode plugin stub.
  * Returns the absolute path to the written TypeScript file.
@@ -95,6 +227,12 @@ export async function installOpenCodeHook(opts) {
     const content = `// GitNexus Enterprise OpenCode plugin
 // Stub — delegates to gitnexus-enterprise-hook.cjs via child process.
 // Hook script: ${opts.hookScriptPath}
+//
+// When wiring up the real spawn() call, pass --agent=opencode so
+// /api/activity captures land with agentName='opencode' (otherwise
+// the script defaults to 'claude-code', which corrupts distillation).
+// Example:
+//   spawn('node', [HOOK_PATH, '--agent=opencode'], { stdio: ... })
 
 export default {
   async toolBefore(ctx: { tool: string }) {

package/dist/index.js

@@ -57,7 +57,7 @@ program
     .command('connect', { isDefault: true })
     .description('Register Hub MCP, install skills, and write project files')
     .argument('[token]', 'gnx_ API token (optional if already saved)')
-    .option('--editor <name>', 'Editor to configure: claude-code | cursor | windsurf | opencode')
+    .option('--editor <name>', 'Editor to configure: claude-code | cursor | windsurf | opencode | kiro')
     .option('--hub <url>', `Hub URL (default: saved config or ${DEFAULT_HUB_URL})`)
     .option('--skip-project', 'Only configure MCP, skip project files')
     .action(connectAction);
@@ -65,7 +65,7 @@ program
 program
     .command('disconnect')
     .description('Remove GitNexus MCP config, skills, and project files')
-    .option('--editor <name>', 'Editor to unconfigure: claude-code | cursor | windsurf | opencode')
+    .option('--editor <name>', 'Editor to unconfigure: claude-code | cursor | windsurf | opencode | kiro')
     .action(async (opts) => {
     try {
         printBanner();

package/hooks/gitnexus-enterprise-hook.cjs

@@ -311,11 +311,147 @@ function httpGetJson(urlStr, headers) {
 }
 
 /**
- * Emit the Claude Code / Cursor / OpenCode hookSpecificOutput envelope.
- * The editor will prepend `message` to the tool's output before handing
- * control back to the model.
+ * Map raw `hook_event_name` strings (as written by each editor) onto
+ * the Claude Code-canonical PascalCase form the rest of this script
+ * uses. Returns null if the event isn't one we handle.
+ *
+ *   Claude Code / OpenCode → "PreToolUse"   / "PostToolUse"   (PascalCase)
+ *   Cursor 2.4+            → "preToolUse"   / "postToolUse"   (camelCase, see cursor.com/docs/hooks)
+ *   Kiro IDE               → "pre-tool-use" / "post-tool-use" (kebab-case, see kiro.dev/docs/hooks/types)
+ *
+ * Three different conventions; one script. Without this normalisation
+ * Cursor and Kiro hooks fire but the script bails on the event check
+ * and emits nothing — which is exactly the bug v0.6.0 shipped with.
  */
-function sendResponse(event, message) {
+function normaliseEvent(rawEvent) {
+  if (rawEvent === 'PreToolUse' || rawEvent === 'pre-tool-use' || rawEvent === 'preToolUse') {
+    return 'PreToolUse';
+  }
+  if (
+    rawEvent === 'PostToolUse' ||
+    rawEvent === 'post-tool-use' ||
+    rawEvent === 'postToolUse'
+  ) {
+    return 'PostToolUse';
+  }
+  return null;
+}
+
+/**
+ * Read an explicit agent override from argv. Each hook installer
+ * appends `--agent=<id>` to the spawn command so `/api/activity/*`
+ * captures can split rows by editor (claude-code vs cursor vs
+ * opencode vs kiro). The stdin payload alone can't distinguish
+ * Cursor from Claude Code from OpenCode — they all emit
+ * `hook_event_name: PreToolUse` — so the agent identity has to be
+ * baked in at install time.
+ *
+ * Returns null when the flag isn't present; callers fall back to
+ * stdin-based detection.
+ */
+function parseAgentArg() {
+  for (const arg of process.argv.slice(2)) {
+    const m = arg.match(/^--agent=(.+)$/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/**
+ * Detect which editor invoked us, used to tag /api/activity captures
+ * with the right `agentName`. Priority:
+ *   1. `--agent=<id>` argv flag (set by the hook installer at
+ *      install time — the only reliable way to distinguish editors
+ *      that share the PascalCase MCP convention)
+ *   2. kebab-case `pre-tool-use` / `post-tool-use` event → `kiro`
+ *      (Kiro is the only editor emitting kebab-case)
+ *   3. fallback → `claude-code` (matches the historical hardcoded
+ *      value, so older installs without the argv flag keep working)
+ */
+function detectAgent(rawEvent) {
+  const explicit = parseAgentArg();
+  if (explicit) return explicit;
+  if (rawEvent === 'pre-tool-use' || rawEvent === 'post-tool-use') return 'kiro';
+  if (rawEvent === 'preToolUse' || rawEvent === 'postToolUse') return 'cursor';
+  return 'claude-code';
+}
+
+/**
+ * Normalise the editor-specific tool name onto the Claude Code-
+ * canonical PascalCase shape the rest of this script uses. Cursor
+ * calls the shell tool `Shell` (cursor.com/docs/hooks postToolUse
+ * example), Claude Code / Kiro / OpenCode call it `Bash`. Other
+ * tool names match across editors so far.
+ */
+function normaliseToolName(raw) {
+  if (raw === 'Shell') return 'Bash';
+  return raw || '';
+}
+
+/**
+ * Parse a `tool_output` field that may be either an object (Claude
+ * Code / Kiro / OpenCode native shape) or a JSON-stringified blob
+ * (Cursor wraps the result as a string per cursor.com/docs/hooks).
+ * Returns the parsed object, or the original value if it isn't a
+ * string we can decode. Caller still has to check for null.
+ */
+function parseToolOutput(out) {
+  if (typeof out === 'string') {
+    try {
+      return JSON.parse(out);
+    } catch {
+      return null;
+    }
+  }
+  return out;
+}
+
+/**
+ * Get the exit code from a normalised tool_output, accepting either
+ * `exit_code` (Claude Code / snake_case) or `exitCode` (Cursor /
+ * camelCase). Returns null when neither is present so callers can
+ * treat that as "succeeded" (some editors omit exit info entirely).
+ */
+function readExitCode(out) {
+  if (!out || typeof out !== 'object') return null;
+  if (typeof out.exit_code === 'number') return out.exit_code;
+  if (typeof out.exitCode === 'number') return out.exitCode;
+  return null;
+}
+
+/**
+ * Emit the response in the format the source editor expects. Four
+ * envelopes today, one script:
+ *
+ *   Claude Code / OpenCode → `hookSpecificOutput` envelope
+ *     ({ hookSpecificOutput: { hookEventName, additionalContext } })
+ *   Cursor 2.4+ preToolUse → `permission` field is REQUIRED (cursor.com/docs/hooks)
+ *     plus optional `additional_context` for prompt injection
+ *   Cursor 2.4+ postToolUse → `additional_context` only
+ *   Kiro IDE               → plain stdout (kiro.dev/docs/hooks/actions —
+ *     except `runCommand` actions are fire-and-forget; stdout is NOT
+ *     fed back into agent context per Kiro's own clarification)
+ */
+function sendResponse(event, agentName, message) {
+  if (agentName === 'kiro') {
+    // Kiro `runCommand` action discards stdout. Writing it is harmless
+    // — it just doesn't reach the agent. We still emit so manual
+    // testing / log inspection has something to read.
+    process.stdout.write(message + '\n');
+    return;
+  }
+  if (agentName === 'cursor') {
+    // Cursor preToolUse rejects entries that don't include `permission`
+    // — without it the Hooks tab logs the call as failed (cosmetic red
+    // X) even when our capture POST succeeded behind the scenes. We
+    // always allow; gating tool calls isn't gitnexus's job.
+    const envelope =
+      event === 'PreToolUse'
+        ? { permission: 'allow', additional_context: message }
+        : { additional_context: message };
+    process.stdout.write(JSON.stringify(envelope) + '\n');
+    return;
+  }
   process.stdout.write(
     JSON.stringify({
       hookSpecificOutput: { hookEventName: event, additionalContext: message },
@@ -323,23 +459,48 @@ function sendResponse(event, message) {
   );
 }
 
-async function handlePreToolUse(input, config, entry) {
-  const toolName = input.tool_name || '';
-  if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return;
-
-  const pattern = extractPattern(toolName, input.tool_input || {});
-  if (!pattern || pattern.length < 3) return;
+/**
+ * Cursor preToolUse with no augmentation message still has to return
+ * `permission: "allow"` or the IDE logs the call as failed. Use this
+ * when the script's other handlers decide not to inject context but
+ * we still need to clear the permission gate.
+ */
+function sendCursorAllow() {
+  process.stdout.write(JSON.stringify({ permission: 'allow' }) + '\n');
+}
 
-  const res = await httpPostJson(
-    `${config.hubUrl}/api/repos/${entry.hubRepoId}/augment`,
-    authHeaders(config),
-    { pattern },
-  );
-  if (!res || res.status !== 200 || !res.body || !res.body.text) return;
+async function handlePreToolUse(input, config, entry, agentName) {
+  const toolName = normaliseToolName(input.tool_name);
+
+  // Cursor's preToolUse matcher includes Read + Write so the hook
+  // also fires for those, but our augment flow only handles search
+  // tools. Track whether we actually injected context so we can
+  // satisfy Cursor's permission contract on the no-augment path.
+  let injected = false;
+
+  if (toolName === 'Grep' || toolName === 'Glob' || toolName === 'Bash') {
+    const pattern = extractPattern(toolName, input.tool_input || {});
+    if (pattern && pattern.length >= 3) {
+      const res = await httpPostJson(
+        `${config.hubUrl}/api/repos/${entry.hubRepoId}/augment`,
+        authHeaders(config),
+        { pattern },
+      );
+      if (res && res.status === 200 && res.body && res.body.text) {
+        const text = String(res.body.text).trim();
+        if (text) {
+          sendResponse('PreToolUse', agentName, text);
+          injected = true;
+        }
+      }
+    }
+  }
 
-  const text = String(res.body.text).trim();
-  if (!text) return;
-  sendResponse('PreToolUse', text);
+  // Cursor preToolUse REQUIRES `permission` in the response; without
+  // it the Hooks tab marks every fire as failed (red X). Allow the
+  // tool unconditionally when we have nothing else to say — gating
+  // tool execution isn't gitnexus's responsibility.
+  if (!injected && agentName === 'cursor') sendCursorAllow();
 }
 
 /**
@@ -376,15 +537,20 @@ function writeMetaCache(repoId, meta) {
  *
  * Best-effort: never blocks the editor, never re-tries, swallows errors.
  */
-async function handleEditObservation(input, config, entry) {
-  const tool = input.tool_name;
+async function handleEditObservation(input, config, entry, agentName) {
+  const tool = normaliseToolName(input.tool_name);
   if (tool !== 'Edit' && tool !== 'Write' && tool !== 'MultiEdit') return;
 
   // Only fire when the edit succeeded. Some editors omit exit info; treat
-  // missing as success so we don't drop legitimate edits.
-  const out = input.tool_output;
-  if (out && out.exit_code !== undefined && out.exit_code !== 0) return;
-  if (out && out.error) return;
+  // missing as success so we don't drop legitimate edits. Cursor wraps
+  // tool_output as a JSON-stringified blob; everyone else passes an
+  // object — parseToolOutput normalises both. Cursor uses `exitCode`
+  // (camel) while Claude Code uses `exit_code` (snake) — readExitCode
+  // accepts either.
+  const out = parseToolOutput(input.tool_output);
+  const exitCode = readExitCode(out);
+  if (exitCode !== null && exitCode !== 0) return;
+  if (out && typeof out === 'object' && out.error) return;
 
   const filePath = (input.tool_input && input.tool_input.file_path) || '';
   if (!filePath || typeof filePath !== 'string') return;
@@ -401,27 +567,30 @@ async function handleEditObservation(input, config, entry) {
     filePath,
     line,
     tool,
-    agentName: 'claude-code',
+    agentName,
   });
 }
 
-async function handlePostToolUse(input, config, entry) {
+async function handlePostToolUse(input, config, entry, agentName) {
+  const toolName = normaliseToolName(input.tool_name);
+
   // Fan out: edit observations are independent of the git-staleness check.
   // Both run on PostToolUse; we don't want one to block the other.
-  if (input.tool_name === 'Edit' || input.tool_name === 'Write' || input.tool_name === 'MultiEdit') {
-    await handleEditObservation(input, config, entry);
+  if (toolName === 'Edit' || toolName === 'Write' || toolName === 'MultiEdit') {
+    await handleEditObservation(input, config, entry, agentName);
     return;
   }
 
-  if (input.tool_name !== 'Bash') return;
+  if (toolName !== 'Bash') return;
   const cmd = (input.tool_input && input.tool_input.command) || '';
   if (!/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(cmd)) return;
 
-  // Only nudge when the git command actually succeeded. Some editors
-  // omit exit_code; treat missing as success so we don't silently
-  // skip legitimate mutations.
-  const exitCode = input.tool_output && input.tool_output.exit_code;
-  if (exitCode !== undefined && exitCode !== 0) return;
+  // Only nudge when the git command actually succeeded. Same parse
+  // shenanigans as handleEditObservation — Cursor stringifies and uses
+  // camelCase. Treat missing exit info as success.
+  const out = parseToolOutput(input.tool_output);
+  const exitCode = readExitCode(out);
+  if (exitCode !== null && exitCode !== 0) return;
 
   let localHead = '';
   try {
@@ -451,6 +620,7 @@ async function handlePostToolUse(input, config, entry) {
   const shortOld = meta.last_commit ? String(meta.last_commit).slice(0, 7) : 'none';
   sendResponse(
     'PostToolUse',
+    agentName,
     `GitNexus index is stale (last indexed: ${shortOld}). Run \`gnx sync\` to update.`,
   );
 }
@@ -538,12 +708,101 @@ async function maybeNudgeUpgrade(config) {
   }
 }
 
+/**
+ * Kiro edit-capture mode. Kiro's `runCommand` action provides no stdin
+ * payload, no env vars for tool metadata, and no argument substitution
+ * — so we can't know which file the agent just edited. Instead, fire
+ * this on Kiro's `postToolUse` toolTypes:["write"] hook and scan the
+ * git working tree for changed files via `git status --porcelain`.
+ * Each dirty path POSTs to /api/activity/edit-observed so distillation
+ * gets per-file edit-closure data, even though the precision is
+ * coarser than Claude Code / Cursor (catches all dirty files in the
+ * tree, not just the one the agent just touched).
+ *
+ * cwd defaults to process.cwd() which Kiro sets to the workspace root.
+ * Resolving to a registry repo + reading the auth token mirrors the
+ * standard PostToolUse path.
+ */
+async function runKiroEditCapture(agentName) {
+  const config = readConfig();
+  if (!config || !config.hubToken || !config.hubUrl) return;
+
+  const entries = readRegistry();
+  const cwd = process.cwd();
+  const entry = resolveCwdToRepo(cwd, entries);
+  if (!entry) return;
+
+  // Two parallel git invocations: tracked-file modifications via
+  // `git diff --name-only HEAD` (catches modified + staged + deleted-
+  // tracked), and untracked files via `git ls-files --others
+  // --exclude-standard`. Both produce one absolute-relative path per
+  // line, no status-code prefix — far more robust than parsing
+  // `git status --porcelain` (whose XY field varies across git
+  // versions and edge cases).
+  const collected = new Set();
+  for (const args of [
+    ['diff', '--name-only', 'HEAD'],
+    ['ls-files', '--others', '--exclude-standard'],
+  ]) {
+    try {
+      const r = spawnSync('git', args, { cwd, encoding: 'utf-8', timeout: 2000 });
+      const out = (r.stdout || '').trim();
+      if (!out) continue;
+      for (const line of out.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed) collected.add(trimmed);
+      }
+    } catch {
+      // Best effort — proceed with whatever we got from prior args.
+    }
+  }
+  if (collected.size === 0) return;
+
+  // Cap at 20 files per fire so a big rewrite or a fresh branch
+  // pull doesn't hammer the hub with hundreds of edit-observed
+  // posts. The 20 cap is arbitrary but matches the per-call
+  // ladybugdb worker pool's typical session length.
+  let posted = 0;
+  for (const filePath of collected) {
+    if (posted >= 20) break;
+    const absPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+    await httpPostJson(`${config.hubUrl}/api/activity/edit-observed`, authHeaders(config), {
+      sessionId: null,
+      repoId: entry.hubRepoId,
+      filePath: absPath,
+      line: null,
+      tool: 'Write',
+      agentName,
+    });
+    posted++;
+  }
+}
+
 async function main() {
   if (process.env.GITNEXUS_NO_AUGMENT === '1') return;
 
+  // Kiro short-circuit: when invoked with --kiro-edit-capture, skip
+  // the standard stdin-driven flow entirely (Kiro's runCommand
+  // doesn't pipe stdin) and run the porcelain scan instead. The
+  // installer wires this flag onto Kiro's postToolUse:write hook.
+  if (process.argv.slice(2).includes('--kiro-edit-capture')) {
+    const agentName = parseAgentArg() || 'kiro';
+    try {
+      await runKiroEditCapture(agentName);
+    } catch (err) {
+      if (process.env.GITNEXUS_DEBUG) {
+        process.stderr.write(`kiro edit-capture: ${(err && err.message) || String(err)}\n`);
+      }
+    }
+    return;
+  }
+
   const input = readInput();
-  const event = input.hook_event_name;
-  if (event !== 'PreToolUse' && event !== 'PostToolUse') return;
+  const rawEvent = input.hook_event_name;
+  const event = normaliseEvent(rawEvent);
+  if (!event) return;
+
+  const agentName = detectAgent(rawEvent);
 
   const config = readConfig();
   if (!config || !config.hubToken || !config.hubUrl) return;
@@ -556,15 +815,32 @@ async function main() {
   }
 
   const entries = readRegistry();
-  const cwd = input.cwd || process.cwd();
+  // Cursor 3.x spawns hooks from ~/.cursor (NOT the workspace) and
+  // sets `cwd: ""` in the stdin payload. The actual project root is
+  // in `workspace_roots[0]`. Without this fallback, resolveCwdToRepo
+  // looks for a registry entry at ~/.cursor → no match → script
+  // bails before posting /api/activity/edit-observed. Other editors
+  // (Claude Code, Kiro) set `cwd` themselves, so the fallback chain
+  // hits their value first.
+  const cwd =
+    (Array.isArray(input.workspace_roots) && input.workspace_roots[0]) ||
+    input.cwd ||
+    process.cwd();
   const entry = resolveCwdToRepo(cwd, entries);
-  if (!entry) return;
+  if (!entry) {
+    // Cursor preToolUse must still emit `permission: "allow"` even
+    // when we have nothing else to say — without it the IDE flags the
+    // hook entry as failed (cosmetic red X). All other paths exit
+    // silently as before.
+    if (event === 'PreToolUse' && agentName === 'cursor') sendCursorAllow();
+    return;
+  }
 
   try {
     if (event === 'PreToolUse') {
-      await handlePreToolUse(input, config, entry);
+      await handlePreToolUse(input, config, entry, agentName);
     } else {
-      await handlePostToolUse(input, config, entry);
+      await handlePostToolUse(input, config, entry, agentName);
     }
   } catch (err) {
     if (process.env.GITNEXUS_DEBUG) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexushub",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Connect your editor to GitNexus Hub — one command MCP setup + project context",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",