@zlnap/astrolabe 0.17.0 → 0.17.2

package/README.md

@@ -12,7 +12,7 @@ MCP 客户端（推荐一键配置）：
 npx -y @zlnap/astrolabe setup
 ```
 
-Detects Claude Code, Cursor, Codex, Windsurf, Cline, Roo, Continue, OpenCode, DeepSeek Harness, Codebuddy, Grok Build, Kimi Code, and ZCode. Merges MCP config (OpenCode V1/V2/jsonc; Grok `[mcp_servers.*]` TOML; ZCode `mcp.servers`; DSH installs the native guard plugin + `cordis.patch.yml` merge). Optional `--with-hooks` installs OpenCode's guard plugin and hook recipes for Codebuddy / Grok / Kimi / ZCode (ZCode: no `SessionEnd`, do not hang cleanup on `Stop`). Flags: `--yes`, `--clients=…`, `--dry-run`, `--with-hooks`, `--list`.
+Detects Claude Code, Cursor, Codex, Windsurf, Cline, Roo, Continue, OpenCode, DeepSeek Harness, Codebuddy, Grok Build, Kimi Code, and ZCode. Merges MCP config (OpenCode V1/V2/jsonc; Grok `[mcp_servers.*]` TOML; ZCode `mcp.servers`; DSH installs the native guard plugin + `cordis.patch.yml` merge). Optional `--with-hooks` installs OpenCode's guard plugin and hook recipes for Cursor / Codebuddy / Grok / Kimi / ZCode (Cursor: `~/.cursor/hooks.json` with `--client=cursor`; ZCode: no `SessionEnd`, scrub cleanup off `Stop`). Flags: `--yes`, `--clients=…`, `--dry-run`, `--with-hooks`, `--list`.
 
 探测本机 Claude Code / Cursor / Codex 等，交互勾选后合并写入 MCP 配置（`--yes`、`--dry-run`、`--list` 可用）。手动配置示例：
 

package/lib/setup/args.js

@@ -13,8 +13,10 @@ Options:
   --native               Use command "astrolabe" on PATH instead of npx
   --command=<bin>        Override MCP command (default: npx, or astrolabe with --native)
   --with-hooks           Also install drift-guard hooks/plugins where supported
-                         (OpenCode guard plugin; Codebuddy/Grok/Kimi/ZCode hook recipes;
-                          DSH always installs its native guard)
+                         (OpenCode guard plugin; Cursor/Codebuddy/Grok/Kimi/ZCode hook
+                          recipes; DSH always installs its native guard).
+                         Cursor writes ~/.cursor/hooks.json (--client=cursor).
+                         ZCode: PreToolUse only — never SessionEnd, never Stop cleanup
   --no-cursor-permissions
                          Skip merging Cursor mcpAllowlist
   --cursor-permissions   Force Cursor allowlist merge when Cursor is selected (default on)

package/lib/setup/clients.js

@@ -9,6 +9,7 @@ const codebuddyMod = require('./codebuddy');
 const grokMod = require('./grok');
 const kimicodeMod = require('./kimicode');
 const zcodeMod = require('./zcode');
+const cursorMod = require('./cursor');
 const PACKAGE_NAME = '@zlnap/astrolabe';
 const SERVER_NAME = 'astrolabe';
 
@@ -360,17 +361,60 @@ const CLIENTS = [
       }
       return { detected: evidence.length > 0, evidence };
     },
-    plan({ home, launch }) {
+    plan({ home, launch, withHooks = false }) {
       const filePath = path.join(home, '.cursor', 'mcp.json');
+      const hooksPath = cursorMod.resolveCursorHooksPath(home);
       const entry = jsonServerEntry(launch);
-      return {
+      const steps = [];
+      steps.push({
         kind: 'json-mcp',
         filePath,
-        entry,
         summary: `merge mcpServers.astrolabe into ${filePath}`,
         apply() {
           const result = mergeJsonMcpFile(filePath, entry, { create: true });
-          return { ...result, write: () => writeJsonAtomic(filePath, result.doc) };
+          return { ...result, entry, write: () => writeJsonAtomic(filePath, result.doc) };
+        },
+      });
+      if (withHooks) {
+        steps.push({
+          kind: 'cursor-hooks',
+          filePath: hooksPath,
+          summary: `merge preToolUse/sessionEnd into ${hooksPath} (--client=cursor)`,
+          apply() {
+            const create = exists(path.join(home, '.cursor')) || exists(hooksPath);
+            const result = cursorMod.mergeCursorHooksFile(hooksPath, {
+              create,
+              existsFn: exists,
+            });
+            if (result.skipped) return result;
+            return { ...result, write: () => writeJsonAtomic(hooksPath, result.doc) };
+          },
+        });
+      }
+      return {
+        kind: 'cursor',
+        filePath,
+        entry,
+        summary:
+          steps[0].summary +
+          (withHooks ? `; hooks → ${hooksPath} (--client=cursor, matcher incl. mcp__astrolabe__.*)` : ''),
+        steps,
+        apply() {
+          const results = [];
+          for (const step of steps) {
+            results.push(step.apply());
+          }
+          const primary = results.find((r) => !r.skipped) || results[0];
+          return {
+            ...primary,
+            entry,
+            results,
+            write: () => {
+              for (const r of results) {
+                if (!r.skipped && r.write) r.write();
+              }
+            },
+          };
         },
       };
     },
@@ -839,7 +883,7 @@ const CLIENTS = [
         filePath,
         summary:
           `merge mcp.servers.astrolabe into ${filePath}` +
-          (withHooks ? ' (+ hooks.events.PreToolUse, no SessionEnd)' : ''),
+          (withHooks ? ' (+ hooks.events.PreToolUse; no SessionEnd; scrub Stop cleanup)' : ''),
         apply() {
           const create =
             exists(path.join(home, '.zcode')) ||
@@ -898,7 +942,7 @@ module.exports = {
   resolveDshPluginInstallDirs: dshMod.resolveDshPluginInstallDirs,
   OPENCODE_GUARD_TS: opencodeMod.OPENCODE_GUARD_TS,
   parseJsonc: require('./jsonc').parseJsonc,
-  // Codebuddy / Grok / Kimi / ZCode helpers (tests)
+  // Codebuddy / Grok / Kimi / ZCode / Cursor helpers (tests)
   resolveCodebuddyMcpPath: codebuddyMod.resolveCodebuddyMcpPath,
   mergeCodebuddyHooksSettings: codebuddyMod.mergeCodebuddyHooksSettings,
   resolveGrokConfigToml: grokMod.resolveGrokConfigToml,
@@ -909,4 +953,7 @@ module.exports = {
   mergeKimiHooksToml: kimicodeMod.mergeKimiHooksToml,
   resolveZcodeConfigPath: zcodeMod.resolveZcodeConfigPath,
   mergeZcodeConfigFile: zcodeMod.mergeZcodeConfigFile,
+  resolveCursorHooksPath: cursorMod.resolveCursorHooksPath,
+  mergeCursorHooksFile: cursorMod.mergeCursorHooksFile,
+  CURSOR_REMIND_MATCHER: cursorMod.REMIND_MATCHER,
 };

package/lib/setup/cursor.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const REMIND_CMD = 'astrolabe hooks remind --client=cursor';
+const CLEANUP_CMD = 'astrolabe hooks cleanup';
+/** Matcher must include mcp__astrolabe__.* so successful Astrolabe calls reset counters. */
+const REMIND_MATCHER = 'Shell|Read|Grep|mcp__astrolabe__.*';
+
+function resolveCursorHooksPath(home) {
+  return path.join(home, '.cursor', 'hooks.json');
+}
+
+function remindEntry() {
+  return {
+    command: REMIND_CMD,
+    matcher: REMIND_MATCHER,
+  };
+}
+
+function cleanupEntry() {
+  return {
+    command: CLEANUP_CMD,
+  };
+}
+
+function entryCommand(entry) {
+  if (!entry || typeof entry !== 'object') return '';
+  if (typeof entry.command === 'string') return entry.command;
+  const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+  for (const h of hooks) {
+    if (h && typeof h.command === 'string') return h.command;
+  }
+  return '';
+}
+
+function isAstrolabeRemind(entry) {
+  return entryCommand(entry).includes('astrolabe hooks remind');
+}
+
+function isAstrolabeCleanup(entry) {
+  return entryCommand(entry).includes('astrolabe hooks cleanup');
+}
+
+/**
+ * Merge ~/.cursor/hooks.json (Cursor CLI native format: camelCase events,
+ * flat command entries). Enforces --client=cursor and the documented matcher
+ * that includes mcp__astrolabe__.* so counter resets work.
+ */
+function mergeCursorHooksFile(filePath, { create = true, existsFn = fs.existsSync } = {}) {
+  let created = false;
+  let doc = {};
+  if (existsFn(filePath)) {
+    const raw = fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '');
+    doc = JSON.parse(raw);
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+      throw new Error(`${filePath} root must be a JSON object`);
+    }
+  } else if (!create) {
+    return { skipped: true, reason: `missing ${filePath} (will not create)` };
+  } else {
+    created = true;
+  }
+
+  if (doc.version == null) doc.version = 1;
+  if (!doc.hooks || typeof doc.hooks !== 'object' || Array.isArray(doc.hooks)) {
+    doc.hooks = {};
+  }
+  const hooks = doc.hooks;
+  let replaced = false;
+
+  if (!Array.isArray(hooks.preToolUse)) hooks.preToolUse = [];
+  const remindIdx = hooks.preToolUse.findIndex(isAstrolabeRemind);
+  const nextRemind = remindEntry();
+  if (remindIdx >= 0) {
+    hooks.preToolUse[remindIdx] = nextRemind;
+    replaced = true;
+  } else {
+    hooks.preToolUse.push(nextRemind);
+  }
+
+  if (!Array.isArray(hooks.sessionEnd)) hooks.sessionEnd = [];
+  const cleanupIdx = hooks.sessionEnd.findIndex(isAstrolabeCleanup);
+  const nextCleanup = cleanupEntry();
+  if (cleanupIdx >= 0) {
+    hooks.sessionEnd[cleanupIdx] = nextCleanup;
+    replaced = true;
+  } else {
+    hooks.sessionEnd.push(nextCleanup);
+  }
+
+  return {
+    filePath,
+    doc,
+    created,
+    replaced,
+    entryPreview: JSON.stringify(
+      { version: doc.version, hooks: { preToolUse: [nextRemind], sessionEnd: [nextCleanup] } },
+      null,
+      2,
+    ),
+  };
+}
+
+module.exports = {
+  REMIND_CMD,
+  CLEANUP_CMD,
+  REMIND_MATCHER,
+  resolveCursorHooksPath,
+  mergeCursorHooksFile,
+};

package/lib/setup/run.js

@@ -261,6 +261,15 @@ function run(argv = process.argv.slice(2)) {
     process.stdout.write(
       '  3. Cursor: open Settings → MCP and confirm astrolabe is listed; enable Run Mode for allowlist.\n',
     );
+    if (opts.withHooks) {
+      process.stdout.write(
+        '     Hooks: ~/.cursor/hooks.json uses --client=cursor (matcher includes mcp__astrolabe__.*).\n',
+      );
+    } else {
+      process.stdout.write(
+        '     Tip: re-run with --with-hooks to write ~/.cursor/hooks.json (--client=cursor).\n',
+      );
+    }
   }
   if (selectedIds.includes('opencode')) {
     process.stdout.write(
@@ -294,7 +303,7 @@ function run(argv = process.argv.slice(2)) {
   }
   if (selectedIds.includes('zcode')) {
     process.stdout.write(
-      '  3. ZCode: MCP under mcp.servers in ~/.zcode/cli/config.json; tip: --with-hooks adds hooks.events.PreToolUse (no SessionEnd).\n',
+      '  3. ZCode: MCP under mcp.servers in ~/.zcode/cli/config.json; tip: --with-hooks adds hooks.events.PreToolUse (--client=zcode; no SessionEnd; scrub Stop cleanup).\n',
     );
   }
   return summary.some((row) => row.status === 'written') || summary.every((row) => row.status === 'skipped')

package/lib/setup/vendor/astrolabe-dsh-guard/README.md

@@ -84,9 +84,11 @@ and reset when the OS clears the temp directory.
 
 - Astrolabe identifies its own tools by substring, so DSH's per-repository server
   names (`mcp__astrolabe-<repo>__find_symbol`) need no rewriting.
-- `search_code` is a *non-symbolic* Astrolabe tool: it does not reset the
-  grep/read counter (by Astrolabe's own design). Use `find_symbol` /
-  `resolve_context` / `find_references` / `goto_definition` to reset it.
+- Any Astrolabe catalog tool (including `search_code`) resets the
+  grep/read/non_symbolic/slice counters on PreToolUse and clears the
+  post-deny silence window. Prefer `find_symbol` /
+  `resolve_context` / `find_references` / `goto_definition` for navigation;
+  `search_code` is fine for recovery after a deny.
 
 ## Licence
 

package/lib/setup/vendor/astrolabe-dsh-guard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrolabe-dsh-guard",
-  "version": "0.1.0",
+  "version": "0.17.2",
   "private": true,
   "description": "Astrolabe drift guard for DeepSeek Harness: deny repeated grep/read calls and steer the model to Astrolabe's MCP code-navigation tools.",
   "type": "module",

package/lib/setup/zcode.js

@@ -47,20 +47,54 @@ function preToolUseEntry() {
   };
 }
 
-function entryHasRemind(entry) {
+function hookCommands(entry) {
+  if (!entry || typeof entry !== 'object') return [];
+  const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+  return hooks
+    .filter((h) => h && typeof h.command === 'string')
+    .map((h) => h.command);
+}
+
+function entryHasAstrolabeRemind(entry) {
+  return hookCommands(entry).some((cmd) => cmd.includes('astrolabe hooks remind'));
+}
+
+/**
+ * Strip cleanup hooks from a Stop entry; drop the entry if nothing remains.
+ * Returns { entry | null, stripped }.
+ */
+function scrubStopEntry(entry) {
+  if (!entry || typeof entry !== 'object') return { entry: null, stripped: false };
+  if (!entryHasCleanup(entry)) return { entry, stripped: false };
+  const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+  const kept = hooks.filter(
+    (h) => !(h && typeof h.command === 'string' && h.command.includes('astrolabe hooks cleanup')),
+  );
+  if (!kept.length) return { entry: null, stripped: true };
+  return { entry: { ...entry, hooks: kept }, stripped: true };
+}
+
+/**
+ * True when a Stop (or similar) event entry hangs `astrolabe hooks cleanup`.
+ * ZCode fires Stop at every turn end — cleanup there would wipe counters each turn.
+ */
+function entryHasCleanup(entry) {
   if (!entry || typeof entry !== 'object') return false;
   const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
   return hooks.some(
     (h) =>
       h &&
       typeof h.command === 'string' &&
-      h.command.includes('astrolabe hooks remind --client=zcode'),
+      h.command.includes('astrolabe hooks cleanup'),
   );
 }
 
+
 /**
  * Merge mcp.servers.astrolabe and (optional) hooks.events.PreToolUse into
- * ~/.zcode/cli/config.json. Never writes SessionEnd; never hangs cleanup on Stop.
+ * ~/.zcode/cli/config.json. Never writes SessionEnd; never hangs cleanup on Stop
+ * (Stop is turn-end — use `astrolabe hooks gc`). Replaces any prior Astrolabe
+ * remind (including wrong --client=claude-code).
  */
 function mergeZcodeConfigFile(
   filePath,
@@ -102,11 +136,27 @@ function mergeZcodeConfigFile(
     // Hard rule: never SessionEnd (ZCode rejects unknown events).
     if (Object.prototype.hasOwnProperty.call(doc.hooks.events, 'SessionEnd')) {
       delete doc.hooks.events.SessionEnd;
+      hooksReplaced = true;
+    }
+    // Hard rule: never hang cleanup on Stop (fires every turn; would zero counters).
+    if (Array.isArray(doc.hooks.events.Stop)) {
+      const scrubbed = [];
+      for (const entry of doc.hooks.events.Stop) {
+        const { entry: next, stripped } = scrubStopEntry(entry);
+        if (stripped) hooksReplaced = true;
+        if (next) scrubbed.push(next);
+      }
+      if (scrubbed.length) {
+        doc.hooks.events.Stop = scrubbed;
+      } else {
+        delete doc.hooks.events.Stop;
+      }
     }
     if (!Array.isArray(doc.hooks.events.PreToolUse)) {
       doc.hooks.events.PreToolUse = [];
     }
-    const idx = doc.hooks.events.PreToolUse.findIndex(entryHasRemind);
+    // Match any prior remind (wrong --client=claude-code included) and replace.
+    const idx = doc.hooks.events.PreToolUse.findIndex(entryHasAstrolabeRemind);
     const next = preToolUseEntry();
     if (idx >= 0) {
       doc.hooks.events.PreToolUse[idx] = next;

package/lib/setup.test.js

@@ -453,6 +453,15 @@ test('ZCode mcp.servers + hooks.events without SessionEnd', () => {
             enabled: false,
             events: {
               SessionEnd: [{ hooks: [{ type: 'command', command: 'bad' }] }],
+              // Misconfigured: cleanup on Stop would wipe counters every turn
+              Stop: [
+                {
+                  hooks: [
+                    { type: 'command', command: 'astrolabe hooks cleanup' },
+                    { type: 'command', command: 'echo keep-stop' },
+                  ],
+                },
+              ],
               PreToolUse: [{ hooks: [{ type: 'command', command: 'echo keep' }] }],
             },
           },
@@ -476,6 +485,15 @@ test('ZCode mcp.servers + hooks.events without SessionEnd', () => {
       !JSON.stringify(doc.hooks).includes('SessionEnd'),
       'SessionEnd must not appear in ZCode hooks',
     );
+    // Stop keeps non-cleanup hooks; cleanup command is stripped
+    assert.ok(Array.isArray(doc.hooks.events.Stop));
+    assert.equal(doc.hooks.events.Stop.length, 1);
+    assert.equal(doc.hooks.events.Stop[0].hooks.length, 1);
+    assert.equal(doc.hooks.events.Stop[0].hooks[0].command, 'echo keep-stop');
+    assert.ok(
+      !JSON.stringify(doc.hooks).includes('hooks cleanup'),
+      'Stop must not hang astrolabe hooks cleanup',
+    );
     assert.ok(
       doc.hooks.events.PreToolUse.some((e) =>
         (e.hooks || []).some((h) => String(h.command).includes('--client=zcode')),
@@ -509,6 +527,53 @@ test('ZCode mcp.servers + hooks.events without SessionEnd', () => {
   }
 });
 
+test('ZCode withHooks strips Stop cleanup but keeps non-cleanup Stop', () => {
+  const home = tmpHome();
+  try {
+    const cli = path.join(home, '.zcode', 'cli');
+    fs.mkdirSync(cli, { recursive: true });
+    fs.writeFileSync(
+      path.join(cli, 'config.json'),
+      JSON.stringify(
+        {
+          hooks: {
+            enabled: true,
+            events: {
+              Stop: [
+                {
+                  matcher: 'cleanup-only',
+                  hooks: [{ type: 'command', command: 'astrolabe hooks cleanup' }],
+                },
+                {
+                  matcher: 'other',
+                  hooks: [{ type: 'command', command: 'echo turn-end' }],
+                },
+              ],
+            },
+          },
+        },
+        null,
+        2,
+      ),
+    );
+    const launch = { command: 'npx', args: ['-y', '@zlnap/astrolabe', '.'] };
+    clientsMod
+      .getClient('zcode')
+      .plan({ home, launch, withHooks: true })
+      .apply()
+      .write();
+    const doc = JSON.parse(fs.readFileSync(path.join(cli, 'config.json'), 'utf8'));
+    assert.equal(doc.hooks.events.SessionEnd, undefined);
+    assert.ok(Array.isArray(doc.hooks.events.Stop));
+    assert.equal(doc.hooks.events.Stop.length, 1);
+    assert.equal(doc.hooks.events.Stop[0].matcher, 'other');
+    assert.equal(doc.hooks.events.Stop[0].hooks[0].command, 'echo turn-end');
+    assert.ok(!JSON.stringify(doc.hooks).includes('hooks cleanup'));
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('setup --clients aliases resolve for new clients', () => {
   const home = tmpHome();
   try {
@@ -537,3 +602,216 @@ test('setup --clients aliases resolve for new clients', () => {
     fs.rmSync(home, { recursive: true, force: true });
   }
 });
+
+test('Cursor client context is always cursor (never claude-code)', () => {
+  const client = clientsMod.getClient('cursor');
+  assert.equal(client.context, 'cursor');
+  const launch = clientsMod.resolveLaunch({ context: client.context });
+  assert.ok(launch.args.includes('--context=cursor'));
+  assert.ok(!launch.args.some((a) => String(a).includes('claude-code')));
+});
+
+test('Cursor --with-hooks writes hooks.json with --client=cursor and mcp matcher', () => {
+  const home = tmpHome();
+  try {
+    fs.mkdirSync(path.join(home, '.cursor'), { recursive: true });
+    // Bad prior config: wrong client + matcher missing mcp__astrolabe__.*
+    fs.writeFileSync(
+      path.join(home, '.cursor', 'hooks.json'),
+      JSON.stringify(
+        {
+          version: 1,
+          hooks: {
+            preToolUse: [
+              {
+                command: 'astrolabe hooks remind --client=claude-code',
+                matcher: 'Shell|Read|Grep',
+              },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+    );
+    fs.writeFileSync(
+      path.join(home, '.cursor', 'mcp.json'),
+      JSON.stringify(
+        {
+          mcpServers: {
+            astrolabe: {
+              command: 'npx',
+              args: ['-y', '@zlnap/astrolabe', '.', '--context=claude-code'],
+            },
+          },
+        },
+        null,
+        2,
+      ),
+    );
+    const result = spawnSync(
+      process.execPath,
+      [
+        BIN,
+        'setup',
+        '--yes',
+        '--clients=cursor',
+        '--with-hooks',
+        '--home',
+        home,
+        '--no-cursor-permissions',
+      ],
+      { encoding: 'utf8' },
+    );
+    assert.equal(result.status, 0, result.stderr + result.stdout);
+
+    const mcp = JSON.parse(fs.readFileSync(path.join(home, '.cursor', 'mcp.json'), 'utf8'));
+    assert.deepEqual(mcp.mcpServers.astrolabe.args, [
+      '-y',
+      '@zlnap/astrolabe',
+      '.',
+      '--context=cursor',
+    ]);
+    assert.ok(!JSON.stringify(mcp).includes('claude-code'));
+
+    const hooks = JSON.parse(fs.readFileSync(path.join(home, '.cursor', 'hooks.json'), 'utf8'));
+    assert.equal(hooks.version, 1);
+    const remind = hooks.hooks.preToolUse.find((e) =>
+      String(e.command || '').includes('astrolabe hooks remind'),
+    );
+    assert.ok(remind, 'preToolUse remind missing');
+    assert.equal(remind.command, 'astrolabe hooks remind --client=cursor');
+    assert.equal(remind.matcher, clientsMod.CURSOR_REMIND_MATCHER);
+    assert.match(remind.matcher, /mcp__astrolabe__\.\*/);
+    assert.ok(!remind.command.includes('claude-code'));
+    const cleanup = hooks.hooks.sessionEnd.find((e) =>
+      String(e.command || '').includes('hooks cleanup'),
+    );
+    assert.ok(cleanup, 'sessionEnd cleanup missing');
+    // Idempotent: no duplicate reminds
+    const remindCount = hooks.hooks.preToolUse.filter((e) =>
+      String(e.command || '').includes('astrolabe hooks remind'),
+    ).length;
+    assert.equal(remindCount, 1);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('ZCode --with-hooks replaces wrong remind client and scrubs Stop cleanup', () => {
+  const home = tmpHome();
+  try {
+    const cli = path.join(home, '.zcode', 'cli');
+    fs.mkdirSync(cli, { recursive: true });
+    fs.writeFileSync(
+      path.join(cli, 'config.json'),
+      JSON.stringify(
+        {
+          mcp: { servers: {} },
+          hooks: {
+            enabled: true,
+            events: {
+              PreToolUse: [
+                {
+                  matcher: '*',
+                  hooks: [
+                    {
+                      type: 'command',
+                      command: 'astrolabe hooks remind --client=claude-code',
+                      timeout: 10,
+                    },
+                  ],
+                },
+              ],
+              Stop: [
+                {
+                  matcher: '*',
+                  hooks: [
+                    {
+                      type: 'command',
+                      command: 'astrolabe hooks cleanup',
+                      timeout: 10,
+                    },
+                    {
+                      type: 'command',
+                      command: 'echo keep-stop',
+                    },
+                  ],
+                },
+              ],
+              SessionEnd: [
+                {
+                  hooks: [{ type: 'command', command: 'astrolabe hooks cleanup' }],
+                },
+              ],
+            },
+          },
+        },
+        null,
+        2,
+      ),
+    );
+    const client = clientsMod.getClient('zcode');
+    assert.equal(client.context, null);
+    const launch = clientsMod.resolveLaunch({ context: client.context });
+    assert.ok(!launch.args.some((a) => String(a).includes('--context=')));
+    const plan = client.plan({ home, launch, withHooks: true });
+    plan.apply().write();
+    const doc = JSON.parse(fs.readFileSync(path.join(cli, 'config.json'), 'utf8'));
+    assert.equal(doc.hooks.events.SessionEnd, undefined);
+    assert.ok(!JSON.stringify(doc.hooks).includes('SessionEnd'));
+    // Stop cleanup removed; non-cleanup Stop hook preserved
+    assert.ok(doc.hooks.events.Stop, 'Stop should remain when non-cleanup hooks survive');
+    const stopCmds = (doc.hooks.events.Stop || []).flatMap((e) =>
+      (e.hooks || []).map((h) => h.command),
+    );
+    assert.ok(stopCmds.includes('echo keep-stop'));
+    assert.ok(!stopCmds.some((c) => String(c).includes('hooks cleanup')));
+    // Wrong client replaced
+    const remindCmds = (doc.hooks.events.PreToolUse || []).flatMap((e) =>
+      (e.hooks || []).map((h) => h.command),
+    );
+    assert.ok(remindCmds.includes('astrolabe hooks remind --client=zcode'));
+    assert.ok(!remindCmds.some((c) => String(c).includes('--client=claude-code')));
+    // Pure Stop-cleanup-only configs drop Stop entirely
+    const home2 = tmpHome();
+    try {
+      const cli2 = path.join(home2, '.zcode', 'cli');
+      fs.mkdirSync(cli2, { recursive: true });
+      fs.writeFileSync(
+        path.join(cli2, 'config.json'),
+        JSON.stringify(
+          {
+            hooks: {
+              events: {
+                Stop: [
+                  {
+                    hooks: [{ type: 'command', command: 'astrolabe hooks cleanup' }],
+                  },
+                ],
+              },
+            },
+          },
+          null,
+          2,
+        ),
+      );
+      clientsMod
+        .getClient('zcode')
+        .plan({ home: home2, launch, withHooks: true })
+        .apply()
+        .write();
+      const d2 = JSON.parse(fs.readFileSync(path.join(cli2, 'config.json'), 'utf8'));
+      assert.equal(d2.hooks.events.Stop, undefined);
+      assert.ok(
+        d2.hooks.events.PreToolUse.some((e) =>
+          (e.hooks || []).some((h) => h.command === 'astrolabe hooks remind --client=zcode'),
+        ),
+      );
+    } finally {
+      fs.rmSync(home2, { recursive: true, force: true });
+    }
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlnap/astrolabe",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "mcpName": "io.github.wojiushirencai/astrolabe",
   "description": "Local MCP server for code search and navigation (search_code, find_symbol, find_references, goto_definition) for AI coding agents. Node shim for the native Astrolabe AI binary.",
   "keywords": [
@@ -40,12 +40,12 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@zlnap/darwin-arm64": "0.17.0",
-    "@zlnap/darwin-x64": "0.17.0",
-    "@zlnap/linux-x64-gnu": "0.17.0",
-    "@zlnap/linux-x64-musl": "0.17.0",
-    "@zlnap/linux-arm64-gnu": "0.17.0",
-    "@zlnap/win32-x64-msvc": "0.17.0"
+    "@zlnap/darwin-arm64": "0.17.2",
+    "@zlnap/darwin-x64": "0.17.2",
+    "@zlnap/linux-x64-gnu": "0.17.2",
+    "@zlnap/linux-x64-musl": "0.17.2",
+    "@zlnap/linux-arm64-gnu": "0.17.2",
+    "@zlnap/win32-x64-msvc": "0.17.2"
   },
   "publishConfig": {
     "access": "public"