grounder 0.0.2 → 0.2.0

package/README.md

@@ -1,9 +1,19 @@
 # Grounder
 
-Connect project folders to a personal Obsidian vault so AI agents (Cursor, Claude Code, etc.) get persistent memory without committing personal docs to the repo.
+[![npm version](https://img.shields.io/npm/v/grounder.svg)](https://www.npmjs.com/package/grounder)
+[![license](https://img.shields.io/npm/l/grounder.svg)](../../LICENSE)
+
+AI coding agents forget everything between sessions. Grounder gives them persistent memory in a personal Obsidian vault — notes and handoffs live outside the repo, under your control, and never get committed.
+
+- **Private by default** — vault notes live outside the project tree; only a small `projectId` marker is safe to commit
+- **Built for agents** — installs `/grounder-note`, `/grounder-task`, `/grounder-task-handoff` slash commands in Cursor and Claude Code
+- **Structured handoffs** — end a session with a Done/Next/Blockers/Decisions checkpoint; resume next time by hydrating from it
+- **Zero per-project install** — slash commands shell out via `npx`; nothing to add to the repo besides the marker file
 
 **Requirements:** Node.js 18+ and an Obsidian vault on disk. Git is optional but used when present (project id detection and link lookup bounds).
 
+**Contents:** [Install](#install) · [Quickstart](#quickstart) · [Setup overview](#setup-overview) · [Commands](#commands) · [Configuration](#configuration) · [Agents](#agents) · [Session-start hooks](#session-start-hooks) · [Troubleshooting](#troubleshooting)
+
 ## Install
 
 ```bash
@@ -16,75 +26,75 @@ Or run without installing:
 npx grounder --help
 ```
 
+`grounder -h` prints the full reference; `grounder -v` prints the installed version.
+
 ## Quickstart
 
+**1. One-time setup:**
+
 ```bash
 # Once per machine — set vault location + install agent slash commands
-grounder vault init ~/Documents/obsidian/dev
+# --hooks adds an optional one-line session-start reminder (see Session-start hooks)
+grounder vault init <path-to-your-vault> --hooks
 
-# Once per folder — link project id to vault notes/ + logs/
+# Once per project folder — link project id to vault notes/ + logs/
 cd your-project
 grounder init
+```
 
-# Write a note (or use /grounder-note in Cursor / Claude Code)
-grounder note "Investigate auth middleware"
+Both commands preview what they'll write and ask to confirm; add `--yes` to skip the prompt (e.g. in scripts).
 
-# End a session with a structured handoff (or use /grounder-task-handoff)
-grounder handoff "$(cat <<'EOF'
-# Handoff: auth middleware
+**2. Daily use — from your agent's chat:**
 
-## Done
-- Mapped middleware order
+```text
+> /grounder-task
+
+  Reading latest handoff… (logs/2026-07-21-091500-auth-middleware.md)
+  Done: mapped middleware order.
+  Next: 1. Add tests for 401 path
+  Starting on tests for the 401 path now.
 
-## Next
-1. Add tests for 401 path
+> ...you work with the agent...
 
-## Blockers
-- None
+> /grounder-task-handoff
 
-## Decisions
-- Keep cookie session for now
+  Wrote handoff → <vault>/10-Projects/your-project/logs/2026-07-28-143200-auth-middleware.md
+```
 
-## Files
-- src/middleware/auth.ts
-EOF
-)"
+`/grounder-task` hydrates the agent from the newest *usable* handoff plus `AGENTS.md`; `/grounder-task-handoff` writes the next checkpoint when you close the session. Behind the scenes these run `grounder handoff list --head` and `grounder handoff <text>` for you — see [Session loop](#session-loop).
 
-# Next session — hydrate from newest handoff (or use /grounder-task)
-grounder handoff list
+No agent, or want to write by hand? The same actions are plain CLI commands:
+
+```bash
+grounder note "Investigate auth middleware"      # ad-hoc note
+grounder handoff "# Handoff: ...\n\n## Next\n1. ..."  # session checkpoint
+grounder handoff list                            # newest handoffs, for manual hydrate
 ```
 
 Notes land in `<vault>/10-Projects/{projectId}/notes/`.  
-Handoffs land in `<vault>/10-Projects/{projectId}/logs/` (one file per close; newest wins).
+Handoffs land in `<vault>/10-Projects/{projectId}/logs/` (one file per close; newest *usable* file wins — an empty or unreadable newest file falls back to the next one).
+
+Inspect or debug setup any time with `grounder status` / `grounder doctor` — see [Troubleshooting](#troubleshooting).
 
 ### Session loop
 
 ```text
-/grounder-task → work → /grounder-task-handoff → next /grounder-task
+(optional teaser) → /grounder-task → work → /grounder-task-handoff → next session
 ```
 
 | Slash command | CLI | Role |
 | --- | --- | --- |
 | `/grounder-note` | `grounder note` | Ad-hoc vault note |
 | `/grounder-task-handoff` | `grounder handoff` | Write session checkpoint to `logs/` |
-| `/grounder-task` | `grounder handoff list` + read newest | Read-only hydrate from newest handoff + `AGENTS.md` |
-
-## Setup overview
+| `/grounder-task` | `grounder handoff list --head` + read it | Read-only hydrate from newest usable handoff + `AGENTS.md` |
 
-Three steps — vault once per machine, then link each project folder:
+With `--hooks` on `vault init`, a new Cursor/Claude session may also print a one-line teaser when a handoff exists — never the full body. See [Session-start hooks](#session-start-hooks).
 
-1. **`grounder vault init <path>`** (once per machine)
-   - Writes `~/.grounder/config.json` with the vault root
-   - Creates `<vault>/10-Projects/` if missing
-   - Installs agent slash commands for detected agents (or `--agent=<id>`):
-     - Cursor → `~/.cursor/commands/grounder-{note,task,task-handoff}.md`
-     - Claude Code → `~/.claude/commands/grounder-{note,task,task-handoff}.md`
-
-2. **`grounder init`** (once per project folder)
-   - Writes `.grounder.json` in the current directory (`projectId` — safe to commit)
-   - Creates `<vault>/10-Projects/{projectId}/notes/` and `logs/`
+## Setup overview
 
-3. **Daily use** — notes, handoffs, and recall via CLI or slash commands; no further install.
+- **`grounder vault init <path>`** (once per machine) writes `~/.grounder/config.json`, creates `<vault>/10-Projects/`, and installs slash commands for detected agents (Cursor → `~/.cursor/commands/`, Claude Code → `~/.claude/commands/`; override with `--agent=<id>`).
+- **`grounder init`** (once per project folder) writes `.grounder.json` (`projectId` — safe to commit) and creates `<vault>/10-Projects/{projectId}/notes/` and `logs/`.
+- **Daily use** — notes, handoffs, and recall via CLI or slash commands; no further install.
 
 Nothing is written into the repo except the small `.grounder.json` marker. Agent artifacts stay under the user’s home directory; vault notes stay outside the project tree.
 
@@ -96,8 +106,12 @@ grounder init                Connect the current folder to your vault
 grounder note <text>         Write a note to the vault
 grounder handoff <text>      Write a session handoff to vault logs/
 grounder handoff list        Print recent handoff paths (newest first)
+grounder handoff list --head Print only the newest usable handoff path
+grounder handoff peek        One-line latest-handoff teaser (used by session hooks)
 grounder path notes          Print resolved notes directory
 grounder path logs           Print resolved logs directory
+grounder status              Snapshot of machine + project link + resolved paths
+grounder doctor              Health checks with fix hints
 ```
 
 ### Init flags
@@ -109,6 +123,7 @@ grounder path logs           Print resolved logs directory
 | `--id <id>` | `init` | Override detected project id |
 | `--vault <path>` | `init` | Override home vault root for this run |
 | `--agent <id>` | `vault init` | Install for a specific agent (repeatable; default: auto-detect). Supported: `cursor`, `claude` |
+| `--hooks` | `vault init` | Also install session-start teaser hooks (opt-in; see [Session-start hooks](#session-start-hooks)) |
 
 ### Note / handoff flags
 
@@ -116,9 +131,25 @@ grounder path logs           Print resolved logs directory
 | --- | --- | --- |
 | `--title <slug>` | `note`, `handoff` | Filename slug (default: slugified text / first line) |
 | `--limit <n>` | `handoff list` | Max paths to print (default: 5) |
+| `--head` | `handoff list` | Print only the newest *usable* handoff path — skips empty/unreadable files, same pick as `handoff peek` |
+
+### Doctor flags
+
+| Flag | Description |
+| --- | --- |
+| `--global` | Machine-only checks (skip project/link checks) |
 
 Run `grounder --help` for the full reference.
 
+### Status vs doctor
+
+| Command | Job | When to use |
+| --- | --- | --- |
+| `grounder status` | Snapshot of Machine (home config + vault path) and Project (link, id, notes/logs, git) | “Am I wired?” — see paths and link state |
+| `grounder doctor` | Health checklist (`ok` / `fail` / `warn`) with fix hints; exit `1` on any fail | “Why isn’t memory working?” — verify setup |
+
+Both are read-only. `status` exits `0` even when unlinked; `doctor` fails when checks fail. Use `doctor --global` to check the machine without a project link.
+
 ## Configuration
 
 **Machine config** — `~/.grounder/config.json`:
@@ -158,13 +189,55 @@ The vault layout is agent-agnostic. `grounder vault init` installs thin glue art
 No `--agent` flag: auto-detect installed agents. Explicit install:
 
 ```bash
-grounder vault init ~/Documents/obsidian/dev --agent=cursor --agent=claude
+grounder vault init <path-to-your-vault> --agent=cursor --agent=claude
 ```
 
 Slash commands tell the agent to run `npx grounder …` from the linked project folder (no global install required). Re-run with `--force` to refresh existing installs.
 
 Templates live under `templates/agents/{id}/`. Adding another agent means one adapter file + one template directory — `vault init` stays agent-blind.
 
+## Session-start hooks
+
+Opt-in safety net for the session loop: when a Cursor or Claude Code session starts in a linked project that already has a handoff, Grounder prints **one line** reminding you it exists. You (or the agent) still decide whether to run `/grounder-task`.
+
+```bash
+grounder vault init <path-to-your-vault> --hooks
+```
+
+Example teaser:
+
+```text
+[grounder] Latest handoff: "auth middleware" (2026-07-28). Run /grounder-task to load it, or ignore if unrelated.
+```
+
+What hooks do **not** do:
+
+- They never auto-load the full handoff body into context
+- They never block or delay a session from starting
+- Unlinked folders and projects with no handoffs print nothing (exit 0, silent)
+
+`doctor` reports a `warn` (never a `fail`) when a detected agent has no Grounder hook installed, and when hooks are installed but `~/.grounder/runtime` is stale or missing.
+
+Hooks run `~/.grounder/runtime/dist/cli.js` directly (not `npx`), materialized on install:
+
+- **Real install** (`npm i -g grounder`, `pnpm add -g grounder`, or a monorepo checkout) → symlinked. Upgrading overwrites the same path in place, so hooks stay current with **no re-run needed**.
+- **Bare `npx grounder vault init --hooks`** (nothing installed) → copied, since each `npx` invocation resolves to a disposable, version-pinned cache dir that can't be symlinked durably. Re-run the same command after upgrading grounder to refresh (no `--force` needed).
+
+If you want hooks that stay current with zero maintenance, install grounder rather than using bare `npx` for this step.
+
+## Troubleshooting
+
+| Symptom | Try |
+| --- | --- |
+| Not sure if this folder is linked | `grounder status` — check Project `Linked:` and paths |
+| Notes / handoffs fail or slash commands missing | `grounder doctor` — follow fix hints |
+| Machine setup only (no project yet) | `grounder doctor --global` |
+| Home config / vault missing | `grounder vault init <path>` |
+| No `.grounder.json` / notes dirs | `grounder init` |
+| Agent slash commands stale or partial | `grounder vault init <path> --force` (or `--agent=<id>`) |
+| Session-start teaser missing (optional) | `grounder vault init <path> --hooks` — `doctor` warns when absent |
+| Session-start teaser stale after upgrade (bare npx) | `grounder vault init <path> --hooks` — `doctor` warns when `hook-runtime` is stale |
+
 ## Development
 
 Source, tests, and contribution workflow live in the [Grounder monorepo](https://github.com/andrej-kolic/grounder).

package/dist/agents/claude.d.ts

@@ -1,7 +1,22 @@
 import type { AgentAdapter } from "./types.js";
+/**
+ * Canonical SessionStart command for Claude Code (home-local runtime, not `npx`).
+ * @see {@link peekHookCommand} — REVERT: restore `"npx grounder handoff peek"` and drop runtime.
+ */
+export declare function claudePeekHookCommand(homeDir?: string): string;
+/**
+ * SessionStart matcher Grounder owns.
+ * Excludes `resume` and `fork` — those sessions already carry prior context.
+ */
+export declare const CLAUDE_SESSION_START_MATCHER = "startup|clear|compact";
 export declare function claudeCommandsDir(homeDir?: string): string;
+/** Absolute path to Claude Code's shared settings file (`~/.claude/settings.json`). */
+export declare function claudeSettingsJsonPath(homeDir?: string): string;
 export declare function grounderNoteCommandPath(homeDir?: string): string;
 export declare function grounderTaskHandoffCommandPath(homeDir?: string): string;
 export declare function grounderTaskCommandPath(homeDir?: string): string;
+export declare function expectedArtifacts(homeDir?: string): string[];
+/** Paths of hook config this adapter touches — currently just `settings.json`. */
+export declare function expectedHookArtifacts(homeDir?: string): string[];
 export declare const claude: AgentAdapter;
 //# sourceMappingURL=claude.d.ts.map

package/dist/agents/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,YAAY,CAAC;AAOpB,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAkBD,eAAO,MAAM,MAAM,EAAE,YAgBpB,CAAC"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,YAAY,CAAC;AAOpB;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAEpE,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhE;AAwOD,eAAO,MAAM,MAAM,EAAE,YAqBpB,CAAC"}

package/dist/agents/claude.js

@@ -1,14 +1,32 @@
-import { copyFile, mkdir } from "node:fs/promises";
+import { copyFile, mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveHomeDir } from "../connector/home.js";
 import { fileExists } from "../util/fs.js";
+import { mergeJsonFile } from "../util/merge-json.js";
+import { installHookRuntime, isGrounderPeekHookCommand, isHookRuntimeStale, peekHookCommand, } from "./hook-runtime.js";
 const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const templateDir = path.join(pkgRoot, "templates", "agents", "claude", "commands");
 const COMMANDS = ["grounder-note.md", "grounder-task-handoff.md", "grounder-task.md"];
+/**
+ * Canonical SessionStart command for Claude Code (home-local runtime, not `npx`).
+ * @see {@link peekHookCommand} — REVERT: restore `"npx grounder handoff peek"` and drop runtime.
+ */
+export function claudePeekHookCommand(homeDir) {
+    return peekHookCommand(homeDir);
+}
+/**
+ * SessionStart matcher Grounder owns.
+ * Excludes `resume` and `fork` — those sessions already carry prior context.
+ */
+export const CLAUDE_SESSION_START_MATCHER = "startup|clear|compact";
 export function claudeCommandsDir(homeDir) {
     return path.join(resolveHomeDir(homeDir), ".claude", "commands");
 }
+/** Absolute path to Claude Code's shared settings file (`~/.claude/settings.json`). */
+export function claudeSettingsJsonPath(homeDir) {
+    return path.join(resolveHomeDir(homeDir), ".claude", "settings.json");
+}
 export function grounderNoteCommandPath(homeDir) {
     return path.join(claudeCommandsDir(homeDir), "grounder-note.md");
 }
@@ -18,6 +36,13 @@ export function grounderTaskHandoffCommandPath(homeDir) {
 export function grounderTaskCommandPath(homeDir) {
     return path.join(claudeCommandsDir(homeDir), "grounder-task.md");
 }
+export function expectedArtifacts(homeDir) {
+    return COMMANDS.map((filename) => path.join(claudeCommandsDir(homeDir), filename));
+}
+/** Paths of hook config this adapter touches — currently just `settings.json`. */
+export function expectedHookArtifacts(homeDir) {
+    return [claudeSettingsJsonPath(homeDir)];
+}
 async function installCommand(filename, opts) {
     const dest = path.join(claudeCommandsDir(opts.homeDir), filename);
     const existed = await fileExists(dest);
@@ -28,12 +53,210 @@ async function installCommand(filename, opts) {
     await copyFile(path.join(templateDir, filename), dest);
     return { dest, status: existed ? "overwritten" : "created" };
 }
+// ---------------------------------------------------------------------------
+// Session-start hook install (~/.claude/settings.json)
+//
+// Claude Code settings are a shared JSON object. Grounder only owns one nested
+// command entry; unrelated keys (permissions, other hook events, etc.) must
+// survive merge. Relevant shape after install (path varies by home / Node):
+//
+//   {
+//     "hooks": {
+//       "SessionStart": [
+//         {
+//           "matcher": "startup|clear|compact",
+//           "hooks": [
+//             {
+//               "type": "command",
+//               "command": "'/path/to/node' '/path/to/.grounder/runtime/dist/cli.js' handoff peek"
+//             }
+//           ]
+//         }
+//       ]
+//     }
+//   }
+//
+// Terminology used below:
+//   - settings root      → the whole settings.json object
+//   - hooks              → settings.hooks (map of event name → matcher groups)
+//   - SessionStart       → hooks.SessionStart (array of matcher groups)
+//   - matcher group      → { matcher, hooks: Hook[] }
+//   - hook entry         → { type: "command", command: string }
+//
+// Idempotency: {@link isGrounderPeekHookCommand} (runtime path or legacy npx).
+// ---------------------------------------------------------------------------
+function peekHookEntry(homeDir) {
+    return { type: "command", command: claudePeekHookCommand(homeDir) };
+}
+/**
+ * Locate Grounder's peek command inside a `hooks.SessionStart` array.
+ *
+ * @param sessionStart - `settings.hooks.SessionStart` — array of matcher groups
+ * @returns Indices into that array / the group's `hooks` array, or `null` if absent
+ */
+function findPeekHook(sessionStart) {
+    for (let groupIdx = 0; groupIdx < sessionStart.length; groupIdx++) {
+        const group = sessionStart[groupIdx];
+        if (!group || typeof group !== "object" || Array.isArray(group)) {
+            continue;
+        }
+        const hooks = group.hooks;
+        if (!Array.isArray(hooks)) {
+            continue;
+        }
+        for (let hookIdx = 0; hookIdx < hooks.length; hookIdx++) {
+            const hook = hooks[hookIdx];
+            if (hook &&
+                typeof hook === "object" &&
+                !Array.isArray(hook) &&
+                isGrounderPeekHookCommand(hook.command)) {
+                return { groupIdx, hookIdx };
+            }
+        }
+    }
+    return null;
+}
+/** Whether `settings.json` already lists any Grounder peek command (for status labeling). */
+async function peekHookHadGrounderEntry(filePath) {
+    try {
+        const parsed = JSON.parse(await readFile(filePath, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return false;
+        }
+        const hooks = parsed.hooks;
+        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
+            return false;
+        }
+        const sessionStart = hooks.SessionStart;
+        return Array.isArray(sessionStart) && findPeekHook(sessionStart) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Skip only when the canonical command is already present *and* the runtime is
+ * current for the running grounder version/source. Legacy `npx` entries or a
+ * stale runtime (missing, or symlinked/copied from a different source) always
+ * refresh — no `--force` required to migrate or to pick up an upgrade.
+ */
+async function peekHookUpToDate(filePath, homeDir) {
+    if (!(await fileExists(filePath))) {
+        return false;
+    }
+    if (await isHookRuntimeStale(homeDir)) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(filePath, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return false;
+        }
+        const hooks = parsed.hooks;
+        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
+            return false;
+        }
+        const sessionStart = hooks.SessionStart;
+        if (!Array.isArray(sessionStart)) {
+            return false;
+        }
+        const found = findPeekHook(sessionStart);
+        if (!found) {
+            return false;
+        }
+        const group = sessionStart[found.groupIdx];
+        return group.hooks[found.hookIdx]?.command === claudePeekHookCommand(homeDir);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Deep-merge Grounder's SessionStart hook into an existing settings object.
+ *
+ * Preserves every key except the nested path it owns. Strategy:
+ * 1. If a Grounder peek hook already exists (runtime or legacy npx) → replace in place.
+ * 2. Else if a matcher group with `matcher === CLAUDE_SESSION_START_MATCHER` exists →
+ *    append Grounder's hook to that group's `hooks` array.
+ * 3. Else → push a new matcher group with Grounder's hook.
+ *
+ * @param current - Parsed settings.json root (object). Other top-level keys untouched.
+ * @param homeDir - Home override for the canonical command path
+ * @returns New settings object with `hooks.SessionStart` updated
+ */
+function mergeClaudeHooks(current, homeDir) {
+    const hooks = current.hooks && typeof current.hooks === "object" && !Array.isArray(current.hooks)
+        ? { ...current.hooks }
+        : {};
+    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
+    const found = findPeekHook(sessionStart);
+    const entry = peekHookEntry(homeDir);
+    if (found) {
+        // Path 1: refresh existing Grounder hook entry in place
+        const group = { ...sessionStart[found.groupIdx] };
+        const groupHooks = Array.isArray(group.hooks) ? [...group.hooks] : [];
+        groupHooks[found.hookIdx] = entry;
+        group.hooks = groupHooks;
+        sessionStart[found.groupIdx] = group;
+    }
+    else {
+        const matcherIdx = sessionStart.findIndex((group) => group &&
+            typeof group === "object" &&
+            !Array.isArray(group) &&
+            group.matcher === CLAUDE_SESSION_START_MATCHER);
+        if (matcherIdx >= 0) {
+            // Path 2: same matcher group already exists (e.g. user hooks) — append ours
+            const group = { ...sessionStart[matcherIdx] };
+            const groupHooks = Array.isArray(group.hooks) ? [...group.hooks] : [];
+            groupHooks.push(entry);
+            group.hooks = groupHooks;
+            sessionStart[matcherIdx] = group;
+        }
+        else {
+            // Path 3: no matching group — create the canonical SessionStart entry
+            sessionStart.push({
+                matcher: CLAUDE_SESSION_START_MATCHER,
+                hooks: [entry],
+            });
+        }
+    }
+    return { ...current, hooks: { ...hooks, SessionStart: sessionStart } };
+}
+/**
+ * Install (or refresh) Grounder's SessionStart teaser hook into `~/.claude/settings.json`.
+ *
+ * Also materializes `~/.grounder/runtime` (see {@link installHookRuntime}).
+ *
+ * Force semantics:
+ * - Up-to-date canonical entry + fresh runtime and `force` false → skip
+ * - Otherwise → refresh runtime + merge host config
+ *
+ * Unparseable settings.json: {@link mergeJsonFile} backs off and this throws (never clobbers).
+ */
+async function installHooks(opts) {
+    const dest = claudeSettingsJsonPath(opts.homeDir);
+    const upToDate = await peekHookUpToDate(dest, opts.homeDir);
+    if (upToDate && !opts.force) {
+        return { artifacts: { [dest]: "skipped" } };
+    }
+    await installHookRuntime({ homeDir: opts.homeDir });
+    const fileExisted = await fileExists(dest);
+    const hadGrounderEntry = fileExisted && (await peekHookHadGrounderEntry(dest));
+    const result = await mergeJsonFile(dest, (current) => mergeClaudeHooks(current, opts.homeDir));
+    if (!result.ok) {
+        throw new Error(result.message);
+    }
+    const status = hadGrounderEntry ? "overwritten" : "created";
+    return { artifacts: { [dest]: status } };
+}
 export const claude = {
     id: "claude",
     name: "Claude Code",
     async isInstalled() {
         return fileExists(path.join(resolveHomeDir(), ".claude"));
     },
+    expectedArtifacts,
+    expectedHookArtifacts,
     async install(opts) {
         const artifacts = {};
         for (const filename of COMMANDS) {
@@ -42,5 +265,6 @@ export const claude = {
         }
         return { artifacts };
     },
+    installHooks,
 };
 //# sourceMappingURL=claude.js.map

package/dist/agents/claude.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"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"}

package/dist/agents/cursor-hook-input.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read Cursor's sessionStart hook payload from stdin and return the first
+ * workspace root when present.
+ *
+ * Cursor pipes JSON like `{ "workspace_roots": ["/path/to/repo"] }` into
+ * user-level hooks, whose `cwd` is `~/.cursor` — not the open project.
+ *
+ * Never throws. Returns `undefined` for TTY stdin, empty/malformed input,
+ * missing `workspace_roots`, or when no data arrives within the timeout
+ * (so interactive/`grounder handoff peek` runs never hang). If data arrived
+ * but stdin has not ended yet, the buffered payload is still parsed.
+ */
+export declare function readCursorHookWorkspaceRoot(stdin?: NodeJS.ReadableStream): Promise<string | undefined>;
+//# sourceMappingURL=cursor-hook-input.d.ts.map

package/dist/agents/cursor-hook-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-hook-input.d.ts","sourceRoot":"","sources":["../../src/agents/cursor-hook-input.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,GAAE,MAAM,CAAC,cAA8B,GAC3C,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA2B7B"}

package/dist/agents/cursor-hook-input.js

@@ -0,0 +1,80 @@
+/** Max wait for piped Cursor hook JSON on stdin before giving up. */
+const STDIN_TIMEOUT_MS = 200;
+/**
+ * Read Cursor's sessionStart hook payload from stdin and return the first
+ * workspace root when present.
+ *
+ * Cursor pipes JSON like `{ "workspace_roots": ["/path/to/repo"] }` into
+ * user-level hooks, whose `cwd` is `~/.cursor` — not the open project.
+ *
+ * Never throws. Returns `undefined` for TTY stdin, empty/malformed input,
+ * missing `workspace_roots`, or when no data arrives within the timeout
+ * (so interactive/`grounder handoff peek` runs never hang). If data arrived
+ * but stdin has not ended yet, the buffered payload is still parsed.
+ */
+export async function readCursorHookWorkspaceRoot(stdin = process.stdin) {
+    if ("isTTY" in stdin && stdin.isTTY) {
+        return undefined;
+    }
+    const raw = await readStdinWithTimeout(stdin, STDIN_TIMEOUT_MS);
+    if (raw === undefined || raw.trim() === "") {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return undefined;
+        }
+        const roots = parsed.workspace_roots;
+        if (!Array.isArray(roots) || roots.length === 0) {
+            return undefined;
+        }
+        const first = roots[0];
+        if (typeof first !== "string" || first.trim() === "") {
+            return undefined;
+        }
+        return first;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readStdinWithTimeout(stdin, timeoutMs) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let settled = false;
+        const settle = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            stdin.off("data", onData);
+            stdin.off("end", onEnd);
+            stdin.off("error", onError);
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        };
+        const buffered = () => {
+            if (chunks.length === 0) {
+                return undefined;
+            }
+            return Buffer.concat(chunks).toString("utf8");
+        };
+        const onEnd = () => settle(buffered());
+        const onError = () => settle(undefined);
+        // On timeout, still use whatever arrived — Cursor may flush the JSON
+        // payload before closing stdin; discarding it would lose workspace_roots.
+        const timer = setTimeout(() => settle(buffered()), timeoutMs);
+        timer.unref?.();
+        stdin.on("data", onData);
+        stdin.on("end", onEnd);
+        stdin.on("error", onError);
+        if ("readableEnded" in stdin && stdin.readableEnded) {
+            onEnd();
+        }
+    });
+}
+//# sourceMappingURL=cursor-hook-input.js.map