grounder 0.1.0 → 0.3.0

package/README.md

@@ -3,16 +3,17 @@
 [![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.
+AI coding agents forget everything between sessions. Grounder gives them persistent memory in a personal Obsidian vault — notes, handoffs, and plans 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
+- **Built for agents** — installs `/grounder-note`, `/grounder-task`, `/grounder-task-handoff`, `/grounder-plan` 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
+- **Named plans** — living docs under `plans/` you update in place (`--force` to overwrite; unlike dated notes/handoffs)
+- **Zero per-project install** — slash commands run through a small per-machine runtime that `vault init` keeps current; 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) · [Troubleshooting](#troubleshooting)
+**Contents:** [Install](#install) · [Upgrading](#upgrading) · [Quickstart](#quickstart) · [Setup overview](#setup-overview) · [Commands](#commands) · [Configuration](#configuration) · [Agents](#agents) · [Session-start hooks](#session-start-hooks) · [Troubleshooting](#troubleshooting)
 
 ## Install
 
@@ -26,7 +27,17 @@ Or run without installing:
 npx grounder --help
 ```
 
-`grounder -h` prints the full reference; `grounder -v` prints the installed version.
+`grounder -h` prints a short synopsis; `grounder --help` (or `grounder help`) prints the full reference; `grounder -v` prints the installed version.
+
+## Upgrading
+
+After upgrading the package, refresh agent installs:
+
+```bash
+grounder migrate
+```
+
+Run `grounder doctor` if you’re unsure — it hints when plain `migrate` is enough vs `migrate --force` (needed **once** when upgrading from Grounder before 0.3, or when command files were edited locally). Most grounder commands and session-start teasers will also tell you when a migrate is due. Flag details: [Migrate flags](#migrate-flags).
 
 ## Quickstart
 
@@ -34,9 +45,10 @@ npx grounder --help
 
 ```bash
 # Once per machine — set vault location + install agent slash commands
-grounder vault init <path-to-your-vault>
+# --hooks adds an optional one-line session-start reminder (see Session-start hooks)
+grounder vault init <path-to-your-vault> --hooks
 
-# Once per project folder — link project id to vault notes/ + logs/
+# Once per project folder — link project id to vault notes/ + logs/ + plans/
 cd your-project
 grounder init
 ```
@@ -60,38 +72,47 @@ Both commands preview what they'll write and ask to confirm; add `--yes` to skip
   Wrote handoff → <vault>/10-Projects/your-project/logs/2026-07-28-143200-auth-middleware.md
 ```
 
-`/grounder-task` hydrates the agent from the newest handoff plus `AGENTS.md`; `/grounder-task-handoff` writes the next checkpoint when you close the session. Behind the scenes these run `grounder handoff list` and `grounder handoff <text>` for you — see [Session loop](#session-loop).
+`/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).
 
 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
+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
+grounder plan $'# Goal\n\nShip it' --title phase-1    # named living plan
 ```
 
 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).  
+Plans land in `<vault>/10-Projects/{projectId}/plans/` (one file per `--title`; overwrite only with `--force`).
+
+Unlike `note` (one-off) and `handoff` (per-session checkpoint), `plan` is for anything spanning multiple sessions — write it once with the goal + steps, then re-run with `--force` as the work progresses to keep one file current instead of scattering updates across handoffs.
 
 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 |
+| Slash command | Equivalent 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` |
+| `/grounder-task` | `grounder handoff list --head` + read it | Read-only hydrate from newest usable handoff + `AGENTS.md` |
+| `/grounder-plan` | `grounder plan` | Named living plan under `plans/` |
+
+The "Equivalent CLI" column is what you'd type by hand — under the hood, slash commands invoke a small runtime `vault init` maintains at `~/.grounder/runtime` (see [Agents](#agents)), not whatever `grounder` binary happens to be on your `PATH`.
+
+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).
 
 ## Setup overview
 
 - **`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.
+- **`grounder init`** (once per project folder) writes `.grounder.json` (`projectId` — safe to commit) and creates `<vault>/10-Projects/{projectId}/notes/`, `logs/`, and `plans/`.
+- **Daily use** — notes, handoffs, plans, 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.
 
@@ -103,10 +124,16 @@ 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 plan <text>         Write/update a named plan under vault plans/
+grounder plan list           Print recent plan paths (newest first)
 grounder path notes          Print resolved notes directory
 grounder path logs           Print resolved logs directory
+grounder path plans          Print resolved plans directory
 grounder status              Snapshot of machine + project link + resolved paths
 grounder doctor              Health checks with fix hints
+grounder migrate             Refresh agent install after upgrading grounder
 ```
 
 ### Init flags
@@ -114,17 +141,40 @@ grounder doctor              Health checks with fix hints
 | Flag | Commands | Description |
 | --- | --- | --- |
 | `--yes` | `vault init`, `init` | Skip confirmation prompts |
-| `--force` | `vault init`, `init` | Overwrite existing generated files |
+| `--force` | `vault init`, `init`, `migrate` | Overwrite existing generated / locally-modified files |
 | `--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` |
+| `--agent <id>` | `vault init`, `migrate` | Install for a specific agent (repeatable; default: auto-detect). Supported: `cursor`, `claude` |
+| `--hooks` | `vault init`, `migrate` | Also install session-start teaser hooks (opt-in; see [Session-start hooks](#session-start-hooks)) |
+
+### Migrate flags
+
+| Flag | Description |
+| --- | --- |
+| `--force` | Overwrite slash command files you edited locally; also needed **once** when upgrading from Grounder before 0.3 |
+| `--dry-run` | Preview without writing |
+| `--agent <id>` | Limit to a specific agent (repeatable) |
+| `--hooks` | Install hooks even if they were never installed before |
+
+See [Upgrading](#upgrading) for the usual post-package-upgrade flow. Untouched command files update automatically; locally edited ones (and pre-0.3 installs with no ledger) are skipped unless you pass `--force`.
 
 ### Note / handoff flags
 
 | Flag | Commands | Description |
 | --- | --- | --- |
 | `--title <slug>` | `note`, `handoff` | Filename slug (default: slugified text / first line) |
-| `--limit <n>` | `handoff list` | Max paths to print (default: 5) |
+| `--limit <n>` | `handoff list`, `plan 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` |
+
+### Plan flags
+
+| Flag | Commands | Description |
+| --- | --- | --- |
+| `--title <name>` | `plan` | Filename stem when creating/updating by name (trailing `.md` ok; sanitized, max 80 chars; no auto-slug). Mutually exclusive with `--path`. |
+| `--path <file>` | `plan` | Update an existing plan by path (must resolve under this project's `plans/`; no title sanitization; always overwrites). Mutually exclusive with `--title`. |
+| `--force` | `plan` | With `--title`: overwrite an existing plan (preserves original `created`, sets `updated`). Not used with `--path`. |
+
+Unlike `note` / `handoff` (always a new dated file), `plan` is living: create or collide by `--title` (use `--force` to overwrite), or update an existing file in place with `--path`.
 
 ### Doctor flags
 
@@ -138,7 +188,7 @@ Run `grounder --help` for the full reference.
 
 | 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 status` | Snapshot of Machine (home config + vault path) and Project (link, id, notes/logs/plans, 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.
@@ -161,7 +211,7 @@ Written by `grounder vault init`. Holds the vault path for this machine only.
 
 Written by `grounder init` in the **current working directory**. Project id detection (when `--id` is omitted): `package.json` name in that folder → git `origin` remote (if inside a git repo) → folder basename.
 
-`grounder note`, `grounder handoff`, and `grounder path *` walk up from the current directory to find the nearest `.grounder.json`, stopping at the git root when one exists (or at the filesystem root otherwise).
+`grounder note`, `grounder handoff`, `grounder plan`, and `grounder path *` walk up from the current directory to find the nearest `.grounder.json`, stopping at the git root when one exists (or at the filesystem root otherwise).
 
 **Environment variables**
 
@@ -176,8 +226,8 @@ The vault layout is agent-agnostic. `grounder vault init` installs thin glue art
 
 | Agent | Detection | Artifacts |
 | --- | --- | --- |
-| Cursor | `~/.cursor` exists | `~/.cursor/commands/grounder-{note,task,task-handoff}.md` |
-| Claude Code | `~/.claude` exists | `~/.claude/commands/grounder-{note,task,task-handoff}.md` |
+| Cursor | `~/.cursor` exists | `~/.cursor/commands/grounder-{note,task,task-handoff,plan}.md` |
+| Claude Code | `~/.claude` exists | `~/.claude/commands/grounder-{note,task,task-handoff,plan}.md` |
 
 No `--agent` flag: auto-detect installed agents. Explicit install:
 
@@ -185,20 +235,57 @@ No `--agent` flag: auto-detect installed agents. Explicit install:
 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.
+Slash commands invoke `~/.grounder/runtime/dist/cli.js` directly (not `npx`) — see [Session-start hooks](#session-start-hooks) for how that runtime stays current. Command files that still match what Grounder last wrote are refreshed by `grounder migrate` without `--force`. Locally edited files are left alone unless you pass `--force`.
+
+After upgrading the package, see [Upgrading](#upgrading). `vault init --force` still works for scripts that already use it; it shares the same install path as `migrate`.
 
 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 `~/.grounder/runtime` is stale or missing.
+
+Hooks *and* slash commands both run `~/.grounder/runtime/dist/cli.js` directly (never `npx`) — `vault init` materializes it, regardless of whether `--hooks` is passed:
+
+- **Real install** (`npm i -g grounder`, `pnpm add -g grounder`, or a monorepo checkout) → symlinked. Upgrading overwrites the same path in place, so both stay current with **no re-run needed**.
+- **Bare `npx grounder vault init …`** (nothing installed) → copied, since each `npx` invocation resolves to a disposable, version-pinned cache dir that can't be symlinked durably. Re-run `grounder migrate` (or `vault init`) after upgrading grounder to refresh (no `--force` needed).
+
+If you want the runtime to stay current with zero maintenance, install grounder rather than using bare `npx` for this step.
+
+That refresh only touches the shared runtime, not installed command files — see [Upgrading](#upgrading) if `doctor` flags stale command schemas.
+
 ## 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 |
+| Notes / handoffs / plans 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>`) |
+| No `.grounder.json` / notes / logs / plans dirs | `grounder init` |
+| Agent slash commands stale (`doctor` warns) | `grounder migrate` — if migrate skips everything as “locally modified”, use `grounder migrate --force` once (typical when upgrading from before 0.3) |
+| Session-start teaser missing (optional) | `grounder migrate --hooks` — `doctor` warns when absent |
+| Shared runtime stale after upgrade (bare npx install) | `grounder migrate` — `doctor` warns when `hook-runtime` is stale |
+| Migrate skips all commands as locally modified (first run after upgrade) | `grounder migrate --force` once, then plain `migrate` on later upgrades |
+| Node binary gone / not executable (`doctor` fails on hook or command interpreter path) | `grounder migrate` (add `--force` if command files were edited or you’re still on a pre-0.3 install) |
 
 ## Development
 

package/dist/agents/claude.d.ts

@@ -1,8 +1,23 @@
 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 grounderPlanCommandPath(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;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAkBD,eAAO,MAAM,MAAM,EAAE,YAkBpB,CAAC"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,YAAY,CAAC;AAYpB;;;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,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;AA+ND,eAAO,MAAM,MAAM,EAAE,YAyCpB,CAAC"}

package/dist/agents/claude.js

@@ -1,17 +1,44 @@
-import { copyFile, mkdir } from "node:fs/promises";
+import { 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";
+import { installCommandFile, recordCommandFileHashes } from "./install-command.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"];
+const COMMANDS = [
+    "grounder-note.md",
+    "grounder-plan.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");
 }
+export function grounderPlanCommandPath(homeDir) {
+    return path.join(claudeCommandsDir(homeDir), "grounder-plan.md");
+}
 export function grounderTaskHandoffCommandPath(homeDir) {
     return path.join(claudeCommandsDir(homeDir), "grounder-task-handoff.md");
 }
@@ -21,30 +48,248 @@ export function grounderTaskCommandPath(homeDir) {
 export function expectedArtifacts(homeDir) {
     return COMMANDS.map((filename) => path.join(claudeCommandsDir(homeDir), filename));
 }
-async function installCommand(filename, opts) {
-    const dest = path.join(claudeCommandsDir(opts.homeDir), filename);
-    const existed = await fileExists(dest);
-    if (existed && !opts.force) {
-        return { dest, status: "skipped" };
+/** Paths of hook config this adapter touches — currently just `settings.json`. */
+export function expectedHookArtifacts(homeDir) {
+    return [claudeSettingsJsonPath(homeDir)];
+}
+// ---------------------------------------------------------------------------
+// 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" } };
+    }
+    if (opts.dryRun) {
+        const fileExisted = await fileExists(dest);
+        const hadGrounderEntry = fileExisted && (await peekHookHadGrounderEntry(dest));
+        const status = hadGrounderEntry ? "overwritten" : "created";
+        return { artifacts: { [dest]: status } };
+    }
+    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);
     }
-    await mkdir(path.dirname(dest), { recursive: true });
-    await copyFile(path.join(templateDir, filename), dest);
-    return { dest, status: existed ? "overwritten" : "created" };
+    const status = hadGrounderEntry ? "overwritten" : "created";
+    return { artifacts: { [dest]: status } };
 }
 export const claude = {
     id: "claude",
     name: "Claude Code",
+    commandsSchema: 1,
+    hooksSchema: 1,
     async isInstalled() {
         return fileExists(path.join(resolveHomeDir(), ".claude"));
     },
     expectedArtifacts,
+    expectedHookArtifacts,
     async install(opts) {
         const artifacts = {};
+        const files = {};
         for (const filename of COMMANDS) {
-            const { dest, status } = await installCommand(filename, opts);
+            const { dest, status, hash } = await installCommandFile({
+                ...opts,
+                agentId: claude.id,
+                commandsSchema: claude.commandsSchema,
+                templateDir,
+                commandsDir: claudeCommandsDir(opts.homeDir),
+                filename,
+            });
             artifacts[dest] = status;
+            if (hash) {
+                files[dest] = { schema: claude.commandsSchema, hash };
+            }
         }
+        await recordCommandFileHashes({
+            agentId: claude.id,
+            commandsSchema: claude.commandsSchema,
+            files,
+            homeDir: opts.homeDir,
+            dryRun: opts.dryRun,
+        });
         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"}