heyspex 0.1.0 → 0.2.1

package/plugins/heyspex/README.md

@@ -0,0 +1,309 @@
+# SpexCode plugin (for Claude Code and GitHub Copilot CLI) — Claude Code + Copilot CLI + Cursor (prototype)
+
+Prototype packaging of HeySpex's agent integration as a self-hosted plugin for **both** hosts,
+implementing migration-path steps 1–2 of [[HS-QTBK-5EK5-RES-claude-code-plugin-packaging-for]].
+**Additive:** the project-level wiring stays live and remains the source of truth
+(`.mcp.json` + `.claude/settings.json` for Claude Code; `.cursor/mcp.json` +
+`.cursor/hooks.json` for Cursor). Nothing here activates until the plugin is explicitly installed.
+
+One plugin directory, two manifests — the hosts read different files and never see each other's.
+
+## Layout
+
+| Path | Host | What it is |
+| --- | --- | --- |
+| `.claude-plugin/plugin.json` | Claude Code | Plugin manifest (`name: heyspex`). |
+| `.cursor-plugin/plugin.json` | Cursor | Plugin manifest. Names `mcp.json` and `hooks/cursor-hooks.json` EXPLICITLY, because a Cursor manifest path replaces auto-discovery — without it Cursor would find `hooks/hooks.json` and try to read Claude-shaped config. |
+| `.mcp.json` | Claude Code | MCP server declaration — launches `bin/launch-mcp.mjs` via `${CLAUDE_PLUGIN_ROOT}`. |
+| `mcp.json` | Cursor | MCP server declaration. Runs `${CURSOR_PLUGIN_ROOT}/bin/launch-mcp.mjs` (Cursor expands that variable to the plugin install path), the same launcher `.mcp.json` uses, so it boots from a plain `npm install heyspex`; `HEYSPEX_VAULT_ROOT` is `${workspaceFolder}`. |
+| `bin/launch-mcp.mjs` | Claude Code | Resolver shim: locates `vendor/heyspex-mcp/cli.mjs` in the host vault repo (`HEYSPEX_MCP_ENTRY` override → `$CLAUDE_PROJECT_DIR` → `$CURSOR_PROJECT_DIR` → `$HEYSPEX_VAULT_ROOT` → cwd) and hands off in-process. Needed because the server's deps come from the repo's `node_modules`, so it can't yet run from the plugin's versioned cache copy. |
+| `hooks/hooks.json` | Claude Code, Copilot CLI | **Generated** from the customer-scoped rows of `scripts/lib/customer-kit.mjs` (`node scripts/lib/customer-kit.mjs --write-plugin-hooks`; a test fails on drift). Every command is a self-locating inline bootstrap (plugin-root env `CLAUDE_PLUGIN_ROOT`/`COPILOT_PLUGIN_ROOT`/`PLUGIN_ROOT` → `bin/run-hook.mjs`, else a walk up from the cwd to `scripts/claude-hooks/_run.mjs`, else exit 0) that reaches `bin/run-hook.mjs`, which finds the platform checkout (`HEYSPEX_PLATFORM_ROOT` → `HEYSPEX_MCP_ENTRY` → its own checkout → `node_modules/heyspex` → `$CLAUDE_PROJECT_DIR`) — never `$CLAUDE_PROJECT_DIR/scripts`, which only exists in heyspex-app. MCP-tool matchers carry both `mcp__heyspex__*` and `mcp__plugin_heyspex_heyspex__*` names. |
+| `.github/hooks/heyspex.json` (repo root) | Copilot cloud agent | **Generated** by `npm run hooks:write-github`; bash-only, default branch only. See "Copilot cloud agent" below. |
+| `bin/run-hook.mjs` | Claude Code | Hook launcher: resolves the platform shim `scripts/claude-hooks/_run.mjs` and hands off in-process (fail-open, like the shim). |
+| `hooks/cursor-hooks.json` | Cursor | **Generated** from `scripts/cursor-hooks/manifest.mjs` by `npm run hooks:install-cursor`; drift is a `hs doctor` failure. Commands resolve through `$CURSOR_PROJECT_DIR`. |
+
+Each host has its own marketplace catalog at the repo root, both pointing at this directory:
+`.claude-plugin/marketplace.json` and `.cursor-plugin/marketplace.json` — the documented
+self-hosted single-repo pattern; no hosted registry involved.
+
+## Installing
+
+### From the npm package (customers; no heyspex-app checkout)
+
+A team that only installs the published `heyspex` package does not have, and does not need, the
+heyspex-app repository. The package carries the marketplace (`node_modules/heyspex/.claude-plugin/marketplace.json`,
+plugin source `./plugins/heyspex`), the hooks and the MCP server. From the root of your own repo:
+
+```bash
+npm install heyspex                      # or: npm install ./heyspex-<version>.tgz
+npx hs login
+npx hs install --target . --plugin-apply            # Claude Code
+npx hs install --target . --copilot-plugin-apply    # GitHub Copilot CLI (plugin) ...
+npx hs install --target . --copilot-hooks           # ... OR repo hooks in .github/hooks, never both
+```
+
+By hand: `claude plugin marketplace add ./node_modules/heyspex` /
+`copilot plugin marketplace add ./node_modules/heyspex`, then `... plugin install heyspex@heyspex-marketplace`.
+Restart the session (`/restart` in Copilot), then check `copilot plugin list` and `npx hs doctor`.
+Full walkthrough: `node_modules/heyspex/docs/copilot-plugin-install.md`. The sections below describe the same plugin from the
+platform checkout and are for HeySpex developers.
+
+### Claude Code
+
+One command, from the platform checkout (wraps the manual flow below):
+
+```bash
+node bin/hs.mjs install --target <consumer-repo> --plugin-apply
+```
+
+`--plugin` prints the commands instead of running them. The equivalent manual flow, inside a
+Claude Code session in the consumer repo — or via the `claude plugin` CLI:
+
+```
+/plugin marketplace add <path-or-git-url-of-this-repo>
+/plugin install heyspex@heyspex-marketplace
+```
+
+### GitHub Copilot CLI
+
+Copilot CLI installs Claude-format plugins (`.claude-plugin/plugin.json`) from a marketplace
+(`.claude-plugin/marketplace.json` is on its search path). Source of truth for the commands and the
+file layout: <https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference>
+(fetched 2026-10-16). Hook behaviour: <https://docs.github.com/en/copilot/reference/hooks-configuration>.
+
+```bash
+copilot plugin marketplace add <owner>/<repo>          # or a git URL or a local path to this repo
+copilot plugin install heyspex@heyspex-marketplace      # SPECIFICATION is plugin@marketplace
+copilot plugin list                                    # confirm it is enabled
+```
+
+For local development: `copilot plugin marketplace add /path/to/heyspex-app`; a path-sourced plugin in a local
+marketplace loads live (`/restart` picks up edits).
+
+What gets loaded:
+
+| Component | Loaded from | Notes |
+| --- | --- | --- |
+| Hooks | `hooks/hooks.json` | Same file Claude Code reads. PascalCase events (`PreToolUse`, `PostToolUse`, `Stop`...) use Claude matcher semantics and snake_case payloads. Every command is a self-locating inline bootstrap: it needs no `$CLAUDE_PROJECT_DIR` and exits 0 when it cannot find the runtime (Copilot turns any non-zero exit into a deny). |
+| MCP | `.mcp.json` | Legacy-plugin MCP file. Its `${CLAUDE_PLUGIN_ROOT}` expansion under Copilot is **not documented** (Copilot documents `${PLUGIN_ROOT}` for Agent Plugins `mcp.json` only) and could not be verified without a Copilot CLI on the build machine. If the server does not start, add it explicitly: `copilot mcp add heyspex -- node <install-path>/plugins/heyspex/bin/launch-mcp.mjs`. |
+| Skills / prompts | MCP prompts (`hs-*`) | Delivered by the MCP server. **The Copilot cloud coding agent has no prompts**; there use the `hs` CLI loop in `docs/driving-heyspex-from-copilot.md`. |
+| Commands | not loaded | Claude Code slash commands are not a Copilot component. |
+
+### One source of hooks: plugin OR repo hooks, never both
+
+Copilot CLI (and Claude Code) load hooks from the plugin AND from the repository's own registrations
+(`.claude/settings.json`, `.claude/settings.local.json`, `.github/hooks/*.json`). A repo that has both runs every HeySpex
+hook twice. Pick one per repo:
+
+- **Plugin** (this directory): `copilot plugin install heyspex@heyspex-marketplace` / `/plugin install ...`. Do not run
+  `hs install` hook registration in the same repo, or strip it afterwards.
+- **Repo hooks** (`hs install`, which writes `.claude/settings.json` + the committed launcher): do not also install the plugin.
+
+`npm run doctor` has a `hook-double-fire` check: it warns when HeySpex rows in the repo's `.claude/settings*.json` or
+`.github/hooks/*.json` coexist with an installed heyspex plugin, and reports `unknown` (never a failure) when no plugin
+registry can be read. What it looks at: `~/.claude/plugins/installed_plugins.json` (a `heyspex@...` key),
+`enabledPlugins` in `~/.claude/settings.json` and the project's Claude settings, and, best effort, a heyspex directory
+under `~/.copilot/installed-plugins` or `~/.copilot/plugins` (the Copilot plugin list file is not documented; `copilot
+plugin list` is the authority). As a runtime backstop, `_run.mjs` also de-duplicates a repeated Copilot invocation
+(`HEYSPEX_COPILOT_DEDUPE_OFF=1` disables that).
+
+### Copilot cloud agent: `.github/hooks/heyspex.json`
+
+The Copilot **cloud agent** loads no plugins and no user-level hook files; its only hook source is `.github/hooks/*.json`
+**on the default branch**. `.github/hooks/heyspex.json` is therefore generated from the same customer rows as
+`hooks/hooks.json`, restricted to the hooks whose Copilot disposition is `mapped` (plus `intent-classifier-trigger`, which
+only arms the capture obligation state and whose dropped output does not matter):
+
+```bash
+npm run hooks:write-github     # node scripts/lib/customer-kit.mjs --write-github-hooks  (a test fails on drift)
+npm run hooks:check-github     # exit 1 when stale
+```
+
+- Linux bash only: every entry is `type: "command"` with a `bash` command that resolves
+  `node_modules/heyspex/scripts/claude-hooks/_run.mjs`, then `./scripts/claude-hooks/_run.mjs`, else `exit 0` (fail open).
+  Events are the camelCase names (`sessionStart`, `preToolUse`, `postToolUse`, `userPromptSubmitted`, `agentStop`,
+  `sessionEnd`, `preCompact`); matchers use Copilot tool names (`create|edit|bash|powershell|task`, MCP tools as a
+  `.*<tool>` suffix).
+- The cloud sandbox must contain `node_modules/heyspex` (run `npm install` in the `copilot-setup-steps` workflow), or the
+  hooks silently no-op.
+- The firewall must allow the console URL (`emit-claim-status` and claim heartbeats call it), or those hooks time out (timeouts fail open).
+- The file only takes effect once it is on the repository's **default branch**.
+- If the repo also carries `.claude/settings.json` HeySpex rows, Copilot CLI reads both files: that is the double-fire case
+  above. Use the manifest for the cloud agent only, or rely on the shim de-duplication.
+- MCP is configured in the repository's Copilot settings (tools only, no OAuth), not by a committed file.
+
+### Gates that are weaker or absent on Copilot (published list)
+
+Parity is not identity. Where Copilot has a trigger the gate is a hard deny or re-drive; the rows below are the exceptions.
+The list is generated from `scripts/lib/hook-dispositions.mjs` (the single three-host table, which also covers Claude Code
+and Cursor) and a test fails when this block is stale. The hard floor under all of it is the MCP server itself:
+`heyspex_claim_spec`, `heyspex_submit_for_review` and `heyspex_save_research` refuse without a preflight marker on every
+surface that connects the MCP server, with no hook involved.
+
+<!-- hook-dispositions:copilot:begin (generated by scripts/lib/hook-dispositions.test.mjs; UPDATE_HOOK_DOCS=1 refreshes) -->
+| Gate | Disposition | Compensating control / what is lost |
+| --- | --- | --- |
+| `research-method-guard` | unportable | MCP preflight refusal on heyspex_save_research (hard floor, hook-independent) + .github/copilot-instructions.md research rule; Copilot has no Skill or Workflow tool to hook. |
+| `deep-research-cost-gate` | unportable | MCP preflight refusal on heyspex_save_research + .github/copilot-instructions.md cost-confirmation rule; Copilot has no Skill or Workflow tool to hook. |
+| `plan-review-gate` | unportable | MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny |
+| `plan-exit-ingest-gate` | unportable | MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny |
+| `preflight-reminder` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. Real enforcement is the MCP preflight refusal. |
+| `intent-classifier-trigger` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. The hook still runs and arms obligation state; the HS-20SW directive-obligation-gate turns that state into a hard deny. |
+| `inject-communication-style` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. |
+| `inject-vault-context` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. Per-prompt vault retrieval has no Copilot channel at all. |
+| `claim-before-code-gate` | advisory-degraded | Armed only by plan-exit-ingest-gate, which has no Copilot trigger (no ExitPlanMode tool), so it stays dormant; covered by the HS-20SW claim-before-build rule. |
+| `diagnose-capture-reminder` | advisory-degraded | Copilot preToolUse has no context channel for an inject, so this advisory is silent (lost). |
+<!-- hook-dispositions:copilot:end -->
+
+Unverified on Copilot (no official page read, or not run live): the VS Code 128-tool-per-request cap; the spelling of MCP
+tool names inside hook payloads (matched by suffix); `${CLAUDE_PLUGIN_ROOT}` expansion for the plugin `.mcp.json` under
+the Copilot CLI (documented for VS Code only); and how the MCP server learns the Copilot session id (its preflight marker
+falls back to a 4 hour TTL when the runtime exposes none). Also unverified: that a Claude-format `hookSpecificOutput` deny is
+read by the CLI (only the top-level `permissionDecision` form and exit 2 are documented), and where a `matcher` is read
+in the camelCase `.github/hooks` entry shape.
+
+### Turning HeySpex on and off (any harness)
+
+One switch, `hs mode` (alias `heyspex mode`; from a checkout without `hs` on PATH: `node bin/hs.mjs mode ...`):
+
+```bash
+hs mode status      # on | off, and why
+hs mode off         # writes <project>/.heyspex/mode.json; every hook exits 0 at once (no restart)
+hs mode on
+hs mode toggle
+```
+
+- `HEYSPEX_MODE=off` silences hooks for one shell/session without touching a file (wins over the file).
+- `HEYSPEX_COPILOT_HOOKS_OFF=1` (or `agent_behaviors.harness_hooks.copilot.enabled: false` in the vault `.heyspex/config.yaml`)
+  silences every hook **only when the caller is GitHub Copilot**; Claude Code and Cursor keep theirs.
+- The switch is read from the PROJECT being worked on (`CLAUDE_PROJECT_DIR`, then the hook payload `cwd`, then upward
+  from the working directory), so `hs mode off` in a customer repo works even though the hooks run from `node_modules/heyspex`.
+- Four security gates ignore the switch by design (`env-vault-guard`, `research-method-guard`, `research-protocol-gate`,
+  `git-identity-guard`): an agent must not be able to disarm them by writing one JSON file. Their own env-var
+  break-glass (set by a human) still applies. The Copilot opt-out does not cover them either unless the owner extends it.
+
+### Cursor
+
+For local development, symlink or copy this directory into Cursor's local plugin root and
+reload the window (**Developer: Reload Window**):
+
+```
+~/.cursor/plugins/local/heyspex
+```
+
+Otherwise add the repo as a marketplace source from Cursor's plugin surface; the root
+`.cursor-plugin/marketplace.json` catalogs it.
+
+**In the platform repo itself you do not need the plugin at all** — `.cursor/hooks.json`,
+`.cursor/mcp.json`, `.cursor/rules/`, `.cursor/skills/` and `.cursor/commands/` are already
+installed and are the live path. The plugin exists for CONSUMER repos.
+
+## Running Claude Code against Ollama or DeepSeek
+
+Claude Code can be pointed at a local Ollama instance or DeepSeek's cloud API through
+`ANTHROPIC_BASE_URL`: both expose an Anthropic Messages API-compatible endpoint, so Claude
+Code talks to them directly with no proxy. The recipes below are verified against each
+vendor's own docs ([[HS-REF-pointing-claude-code-at-non-anthropic]]).
+
+### Ollama (local)
+
+Requires Ollama 0.14+, which added a native Anthropic-compatible endpoint. The auth token is
+required but ignored.
+
+```bash
+# one-shot
+ollama launch claude --model qwen3-coder
+
+# manual
+export ANTHROPIC_AUTH_TOKEN=ollama
+export ANTHROPIC_API_KEY=""
+export ANTHROPIC_BASE_URL=http://localhost:11434
+claude --model qwen3-coder
+```
+
+### DeepSeek (cloud)
+
+```bash
+export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
+export ANTHROPIC_API_KEY=your-deepseek-api-key
+claude
+```
+
+The `/anthropic` path is required — the bare host `https://api.deepseek.com` (without
+`/anthropic`) is not the Anthropic-compatible endpoint. DeepSeek's own docs specify
+`ANTHROPIC_API_KEY`, not `ANTHROPIC_AUTH_TOKEN`.
+
+### Model name mapping (DeepSeek)
+
+There is no `ANTHROPIC_MODEL` var to set manually — model choice is automatic name-mapping:
+Claude Opus names map to `deepseek-v4-pro` (billed at V4 Pro price), while every other Claude
+name (Haiku/Sonnet) and any unmapped name maps to `deepseek-flash`.
+
+### Known DeepSeek limitations
+
+- `top_p` fixed at 1.0 outside thinking mode (min 0.95 inside it).
+- Unsupported Anthropic content types: documents, search results, redacted thinking, code
+  execution results, MCP tool integrations, container uploads.
+- `budget_tokens` in thinking-mode config is ignored.
+
+### Enforcement is independent of the backend
+
+HeySpex hooks fire regardless of backend: Claude Code hooks fire at session, turn, and
+tool-call points of Claude Code's own loop, so every HeySpex hook in `.claude/settings.json`
+and `plugins/heyspex/hooks/` runs unchanged regardless of backend — see the
+[Claude Code hooks reference](https://code.claude.com/docs/en/hooks).
+
+### Launcher
+
+`hs next <id> --launch --backend ollama|deepseek` sets the right env vars and execs `claude`.
+This is the supported path, shipping with epic
+[[HS-30JD-94Q5-EPIC-claude-code-launches-against-ollama-or]]; until then, use the manual
+recipe above.
+
+## Validating (migration-path step 3)
+
+Run the install above in a **fresh clone / separate consumer repo** (avoids the double-hook
+caveat below), after `npm install` in the platform checkout.
+
+Then restart the session and confirm:
+
+1. The MCP server connects and tools appear as `mcp__plugin_heyspex_heyspex__heyspex_*`.
+2. Hooks fire (SessionStart seat injection, PreToolUse gates) — and only once.
+3. The re-prefix blast radius: anything load-bearing that hardcodes `mcp__heyspex__*`
+   (CLAUDE.md, `.claude/settings.json` permission allow/deny lists, procedures, hook scripts)
+   still behaves. This is the migration cost the research flags as largest.
+
+## Known caveats (by design, this stage)
+
+- **Double-fire:** enabling this plugin in a repo that still registers the same hooks project-level
+  runs every hook twice. Single-source rule: plugin OR repo hooks, never both (see above; `npm run doctor` warns).
+  Validate in a fresh clone, or strip the project hooks first (`node scripts/install-cursor-hooks.mjs --uninstall` for Cursor).
+- **Not standalone:** the plugin requires a HeySpex vault checkout with `npm install` run —
+  the MCP server and hook scripts resolve from the host project, not the plugin cache.
+  Bundling the server into the plugin is a full-cutover-stage task.
+- **`hs-*` skills stay MCP prompts** (research step 4, unresolved): they travel with the MCP
+  server, not as plugin `SKILL.md` files. Commands, rules and agents are deliberately not
+  duplicated here to avoid drift and double registration — which matters more for Cursor, whose
+  plugin format CAN carry `rules/`, `commands/` and `skills/`. Bundling them is a cutover decision,
+  not a packaging one.
+- **Permissions/statusLine are not mirrored** — those remain project-level concerns.
+- **Manual updates are two steps and scope-sensitive:** `claude plugin marketplace update
+  heyspex-marketplace` refreshes the catalog only; the installed copy moves on
+  `claude plugin update heyspex@heyspex-marketplace --scope project` (the CLI defaults to
+  `--scope user` and errors "not installed at scope user" on a project-scoped install).
+  Background auto-update does both, and the new version applies at restart or `/reload-plugins`.
+  Version/auto-update findings: `specs/memory/decisions/claude-code-plugin-auto-update-third.md`.
+- **Two hooks have no Cursor trigger** (`plan-review-gate`, `plan-exit-ingest-gate`): Cursor
+  exposes no `ExitPlanMode` tool call to hooks, so the plan-review gate is enforced by
+  `.cursor/rules/plan-review-required.mdc` instead. Tracked in
+  `scripts/cursor-hooks/manifest.mjs` → `UNPORTABLE`; hooks that run weaker are in `DEGRADED` there.
+  Four hooks have no Copilot trigger (see the published list above).
+- **Backend choice is separate from enforcement:** running the Claude Code host against a local
+  or cloud non-Anthropic model disables no hook — see
+  [Running Claude Code against Ollama or DeepSeek](#running-claude-code-against-ollama-or-deepseek)
+  for the recipes.
+
+## Cutover criteria (research steps 4–5)
+
+Only after the validation above passes end-to-end and the skills-vs-prompts question is settled
+does removing the project-level wiring (or extending this to customer vaults) become a decision.

package/plugins/heyspex/bin/launch-mcp.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// HeySpex plugin MCP launcher (post-repo-split — HS-S1BX; prototype stage: HS-QTBK).
+//
+// The heyspex MCP server (vendor/heyspex-mcp/cli.mjs) reaches a customer machine
+// two ways: bundled inside the `heyspex` npm package (node_modules/heyspex/
+// vendor/heyspex-mcp/cli.mjs, once `npm install heyspex` has run), or via a
+// source checkout of the heyspex-app repo. This shim locates whichever is
+// reachable and hands off in-process, failing with an actionable message
+// instead of a silent MCP connection error.
+//
+// Resolution order:
+//   1. HEYSPEX_MCP_ENTRY — explicit override (absolute path to cli.mjs)
+//   2. node_modules/heyspex/vendor/heyspex-mcp/cli.mjs — found by walking up
+//      from THIS launcher's own location for the containing node_modules/heyspex
+//      install. Package-first is correct for the plugin use case: plugins run
+//      on customer machines, where a plain `npm install heyspex` is the one
+//      artifact that's always there — a source checkout of heyspex-app is not a
+//      safe assumption. When this launcher itself ships inside that install
+//      (node_modules/heyspex/plugins/heyspex/bin/launch-mcp.mjs), the walk finds
+//      the package root in a single hop; if the launcher is running from
+//      somewhere else (a source checkout, a plugin cache outside node_modules),
+//      the walk finds nothing and this candidate is skipped.
+//   3. $CLAUDE_PROJECT_DIR/vendor/heyspex-mcp/cli.mjs           (source checkout)
+//   4. $CURSOR_PROJECT_DIR/vendor/heyspex-mcp/cli.mjs   (Cursor sets both, but
+//      only CLAUDE_PROJECT_DIR as a compatibility alias — do not rely on it)
+//   5. $HEYSPEX_VAULT_ROOT/vendor/heyspex-mcp/cli.mjs           (source checkout)
+//   6. <cwd>/vendor/heyspex-mcp/cli.mjs                         (source checkout)
+
+import { existsSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * Walk up from `fromFile` looking for the `node_modules/heyspex` directory that
+ * contains it, and return the vendor/heyspex-mcp/cli.mjs path under that package
+ * root — or null if this file isn't nested inside such an install.
+ */
+function findPackagedEntry(fromFile) {
+  let dir = dirname(fromFile);
+  for (;;) {
+    const parent = dirname(dir);
+    if (parent === dir) return null; // reached the filesystem root
+    const base = dir.split(sep).pop();
+    const parentBase = parent.split(sep).pop();
+    if (base === "heyspex" && parentBase === "node_modules") {
+      return resolve(dir, "vendor/heyspex-mcp/cli.mjs");
+    }
+    dir = parent;
+  }
+}
+
+const packagedEntry = findPackagedEntry(fileURLToPath(import.meta.url));
+
+const candidates = [
+  process.env.HEYSPEX_MCP_ENTRY,
+  packagedEntry,
+  process.env.CLAUDE_PROJECT_DIR &&
+    resolve(process.env.CLAUDE_PROJECT_DIR, "vendor/heyspex-mcp/cli.mjs"),
+  process.env.CURSOR_PROJECT_DIR &&
+    resolve(process.env.CURSOR_PROJECT_DIR, "vendor/heyspex-mcp/cli.mjs"),
+  process.env.HEYSPEX_VAULT_ROOT &&
+    resolve(process.env.HEYSPEX_VAULT_ROOT, "vendor/heyspex-mcp/cli.mjs"),
+  resolve(process.cwd(), "vendor/heyspex-mcp/cli.mjs"),
+].filter(Boolean);
+
+const entry = candidates.find((p) => existsSync(p));
+
+if (!entry) {
+  console.error(
+    [
+      "[heyspex plugin] Could not locate the HeySpex MCP server (vendor/heyspex-mcp/cli.mjs).",
+      "Searched:",
+      ...candidates.map((p) => `  - ${p}`),
+      "",
+      "Fixes:",
+      "  - Run `npm install heyspex` in this project, then restart — the plugin",
+      "    boots the server from node_modules/heyspex.",
+      "  - Or point this at a source checkout of the heyspex-app repo, e.g. by",
+      "    setting CLAUDE_PROJECT_DIR or HEYSPEX_VAULT_ROOT to its path.",
+      "  - Or set HEYSPEX_MCP_ENTRY to the absolute path of cli.mjs directly.",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
+// The guessed "grandparent of vendor/heyspex-mcp" vault root only makes sense
+// for a source checkout, where that directory IS the vault. For the packaged
+// entry it resolves to node_modules/heyspex, which is never the customer's
+// vault — leave HEYSPEX_VAULT_ROOT alone in that case and let the server's own
+// multi-tier vault resolver (vault-resolve.mjs) find the real one.
+if (!process.env.HEYSPEX_VAULT_ROOT && entry !== packagedEntry) {
+  process.env.HEYSPEX_VAULT_ROOT = resolve(entry, "../../..");
+}
+
+await import(pathToFileURL(entry).href);

package/plugins/heyspex/bin/run-hook.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// HeySpex plugin hook launcher — the hooks.json counterpart of launch-mcp.mjs.
+//
+// Every command in ../hooks/hooks.json is
+//   node "${CLAUDE_PLUGIN_ROOT}/bin/run-hook.mjs" <hook> [args]
+// The hook bodies and their shim (scripts/claude-hooks/_run.mjs) live in the
+// HeySpex PLATFORM checkout, not in the plugin cache and not in the customer
+// repo — so `$CLAUDE_PROJECT_DIR/scripts/...` (the old form) only ever
+// resolved inside heyspex-app and failed with MODULE_NOT_FOUND everywhere else
+// (non-blocking, so every gate was silently off). This launcher finds the
+// platform and hands off in-process, so the shim still owns stdin and the exit
+// code, exactly as if Claude Code had invoked it directly.
+//
+// Resolution order (first that has scripts/claude-hooks/_run.mjs):
+//   1. HEYSPEX_PLATFORM_ROOT                         (explicit override)
+//   2. HEYSPEX_MCP_ENTRY → <root>/vendor/heyspex-mcp/cli.mjs — `hs install`
+//      writes this into the customer repo's .claude/settings.json env
+//   3. this launcher's own checkout (<root>/plugins/heyspex/bin/)
+//   4. node_modules/heyspex containing this launcher (published package)
+//   5. $CLAUDE_PROJECT_DIR, $CURSOR_PROJECT_DIR      (the platform repo itself)
+//
+// Fail-open like the shim: nothing found → one stderr line, exit 0. This matters most on GitHub Copilot, which
+// turns ANY non-zero hook exit into a deny: a failed shim import, a throw while the shim loads, an unhandled
+// rejection or an uncaught exception all log to stderr and exit 0 here. (The launcher cannot know the harness
+// before the shim reads stdin; for Claude Code a crash exit was already non-blocking, so exiting 0 only changes
+// the exit status, never a decision. Deliberate exit codes - the shim's legacy `exit 2` deny - pass through.)
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function failOpen(what) {
+  return (err) => {
+    try { process.stderr.write(`[heyspex plugin] hook ${process.argv[2] ?? '?'} ${what} (failing open): ${err?.message ?? err}
+`); } catch { /* ignore */ }
+    process.exit(0);
+  };
+}
+process.on('uncaughtException', failOpen('crashed'));
+process.on('unhandledRejection', failOpen('rejected'));
+
+const SHIM_REL = ['scripts', 'claude-hooks', '_run.mjs'];
+const here = dirname(fileURLToPath(import.meta.url));
+
+function packagedRoot(fromDir) {
+  let dir = fromDir;
+  for (;;) {
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    if (dir.split(sep).pop() === 'heyspex' && parent.split(sep).pop() === 'node_modules') return dir;
+    dir = parent;
+  }
+}
+
+const env = process.env;
+const candidates = [
+  env.HEYSPEX_PLATFORM_ROOT?.trim(),
+  env.HEYSPEX_MCP_ENTRY?.trim() && resolve(env.HEYSPEX_MCP_ENTRY.trim(), '..', '..', '..'),
+  resolve(here, '..', '..', '..'),
+  packagedRoot(here),
+  env.CLAUDE_PROJECT_DIR?.trim(),
+  env.CURSOR_PROJECT_DIR?.trim(),
+].filter(Boolean);
+
+const shim = candidates.map((root) => resolve(root, ...SHIM_REL)).find((p) => existsSync(p));
+
+if (!shim) {
+  process.stderr.write(
+    `[heyspex plugin] hook ${process.argv[2] ?? '?'} skipped: no HeySpex platform checkout found ` +
+      `(set HEYSPEX_MCP_ENTRY via \`hs install\`, or HEYSPEX_PLATFORM_ROOT). Searched: ${candidates.join(', ')}\n`,
+  );
+  process.exit(0);
+}
+
+// argv is already [node, <this>, <hook>, ...args] — the shape _run.mjs reads.
+try {
+  await import(pathToFileURL(shim).href);
+} catch (err) {
+  failOpen('failed to load the shim')(err);
+}