@korso/shepherd 0.7.0 → 0.8.1

package/README.md

@@ -60,6 +60,7 @@ override only to replace what's detected:
 | `MODEL` | omitted — **never auto-detected**, so set it if you want it shown | `claude-sonnet-4-6` |
 | `HEARTBEAT_INTERVAL_SECONDS` | defaults to `60` | `30` |
 | `SHEPHERD_INBOX_DIR` | defaults to `~/.shepherd/inbox`. Override only to relocate the **announcement-push** inbox (see below); the background heartbeat writes incoming announcements here. If you set it, point your client hook/extension at the **same** dir | `~/.shepherd/inbox` |
+| `SHEPHERD_NO_AUTO_HOOKS` | unset — set to `1`/`true` to stop the server from auto-installing the client delivery hook on first run (see below) | `1` |
 
 **Device-identity cache.** Whenever `HUMAN` is unset and git **does** detect a
 name, that name is cached for your OS user at `~/.shepherd/identity.json`. A
@@ -84,10 +85,37 @@ default `~/.shepherd/inbox`). That file is then drained by two paths:
    anything sitting in the inbox. So even with no hook configured, no announcement
    is ever lost — the worst case is the old behaviour (delivered on the next
    Shepherd tool call), never silent drops.
-2. **Passive client hook/extension (optional, per client).** To get announcements
-   **without** waiting for a Shepherd tool call — surfaced on the agent's next
-   action of any kind — wire up your client's hook below. This is the
-   "a subagent finished" style of notification.
+2. **Passive client hook/extension (installed automatically, per client).** To
+   get announcements **without** waiting for a Shepherd tool call — surfaced on
+   the agent's next action of any kind — the client needs its hook wired up.
+   **You normally don't do this by hand**: the first time the server runs under
+   Claude Code, Codex, or Pi, it installs the hook itself (see *Automatic hook
+   install* below). The per-client sections that follow document exactly what
+   gets installed, for auditing or manual setup.
+
+### Automatic hook install
+
+On its first `initialize` handshake the server detects the connecting client
+and, for Claude Code / Codex / Pi, installs the delivery hook **once per
+machine**:
+
+- **Claude Code** — merges the `SessionStart` + `PreToolUse` hook entries into
+  `~/.claude/settings.json` (additive JSON merge; an unparseable file is left
+  untouched).
+- **Codex** — appends the `[[hooks.UserPromptSubmit]]` block (and
+  `features.hooks = true`) to `~/.codex/config.toml` (text-level append; it
+  respects an explicit `hooks = false` and never rewrites existing content).
+- **Pi** — copies the bundled extension to
+  `~/.pi/agent/extensions/shepherd-inbox.js`.
+- **Cursor** — merges a `beforeSubmitPrompt` entry into `~/.cursor/hooks.json`
+  (additive JSON merge). Only that event is wired: it is the one Cursor event
+  verified to inject hook output into the agent's context, and wiring an
+  unverified event would consume announcements without delivering them.
+
+A record under `~/.shepherd/hooks/` guarantees at-most-once: if you remove the
+hook, Shepherd won't re-add it. Everything is fail-open (an error just means no
+hook, never a broken session), and `SHEPHERD_NO_AUTO_HOOKS=1` disables the whole
+mechanism.
 
 Both paths read the **same** inbox file and de-duplicate by announcement id, so
 running both is safe (the hub hands each announcement to exactly one drain; the
@@ -111,8 +139,21 @@ tool-less events like Codex's `UserPromptSubmit` or a Pi turn. The
 nudge is advisory and self-extinguishing: the moment the repo is linked or
 declined it goes quiet, and like everything else here it fails open.
 
+**First-run ask (zero-setup).** Independently of the hook, the server watches an
+unlinked, undeclined repo for its first file edit (a lightweight `git status`
+poll) and — on clients that support MCP elicitation — asks the user directly via
+a popup: *"Coordinate this repo with Shepherd?"* with the workspace choices and
+a "No — don't ask again" option. Only an explicitly **submitted** answer is
+recorded (a dismissed or auto-declined popup means "ask again next session"), so
+the question is answered at most once and never by accident. Linking activates
+coordination live, mid-session; "don't ask again" hides the coordination tools
+for that repo entirely. Clients without elicitation fall back to the
+instructions + hook nudge above.
+
 ### Claude Code — `PreToolUse` + `SessionStart` hooks
 
+*(Installed automatically on first run — shown for reference/manual setup.)*
+
 `PreToolUse` fires before every tool, giving the most frequent passive delivery;
 `SessionStart` surfaces the link ask at the top of a session in an unlinked repo.
 The hook needs no arguments — it resolves the same default inbox dir the server
@@ -152,6 +193,8 @@ uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
 
 ### Codex — `UserPromptSubmit` hook
 
+*(Installed automatically on first run — shown for reference/manual setup.)*
+
 Codex uses the **same** hook contract as Claude Code (JSON on stdin, a
 `hookSpecificOutput.additionalContext` reply), so the **same bin** serves it. Use
 `UserPromptSubmit` — Codex's `PreToolUse` only fires for Bash, not `apply_patch`
@@ -170,8 +213,10 @@ command = ["npx", "-y", "--package=@korso/shepherd", "shepherd-inbox-hook"]
 
 ### Pi — extension
 
-Pi has no stdin/stdout hook; it loads in-process extensions. Ship the bundled
-extension into Pi's extensions dir:
+*(Installed automatically on first run — shown for reference/manual setup.)*
+
+Pi has no stdin/stdout hook; it loads in-process extensions. The auto-install
+copies the bundled extension into Pi's extensions dir; by hand:
 
 ```sh
 # global, applies everywhere:
@@ -184,6 +229,27 @@ It runs on every user turn (`before_agent_start`), drains the same inbox, and
 injects pending announcements plus the unlinked-repo nudge. (Or load it ad hoc
 with `pi -e /abs/path/to/dist/inboxExtension.js`.)
 
+### Cursor — `beforeSubmitPrompt` hook
+
+*(Installed automatically on first run — shown for reference/manual setup.)*
+
+Cursor runs hooks from `~/.cursor/hooks.json` with JSON on stdin and a JSON
+reply on stdout; the same bin detects Cursor's dialect (BOM-prefixed payload,
+`workspace_roots` instead of `cwd`) and answers with the top-level
+`additionalContext` form Cursor injects into the agent's context. Only
+`beforeSubmitPrompt` is used — verified (Cursor 3.9.16) to reach the model:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "beforeSubmitPrompt": [
+      { "command": "npx -y --package=@korso/shepherd shepherd-inbox-hook" }
+    ]
+  }
+}
+```
+
 ### Notes
 
 Every path is **fail-open**: a missing dir, unreachable hub, or any error means
@@ -302,9 +368,10 @@ or per-project at `.cursor/mcp.json`:
 ```
 
 Confirm under **Settings → MCP** that `shepherd` is listed with its tools.
-Announcement push: Cursor has no hook equivalent (see the hooks above for
-Claude Code/Codex/Pi), so announcements arrive via the universal drainer — on
-the agent's next Shepherd tool call — rather than pushed between calls.
+Announcement push: handled by the auto-installed `beforeSubmitPrompt` hook in
+`~/.cursor/hooks.json` (see the Cursor hook section above) — announcements and
+the link nudge land on each user turn, plus the universal drainer on every
+Shepherd tool call.
 
 ---
 

package/dist/inboxExtension.js

@@ -152,6 +152,7 @@ function drainInbox(filePath) {
   }
   return out;
 }
+var REPLY_ROUTING_HINT = "(The senders can't see this chat. If a message needs a reply, send it with the `announce` tool \u2014 directed to the sender by name \u2014 not here.)";
 function formatInboxAnnouncements(announcements) {
   if (!announcements || announcements.length === 0) return "";
   const count = announcements.length;
@@ -162,6 +163,7 @@ function formatInboxAnnouncements(announcements) {
     const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
     lines.push(`  [${a.fromAgentName}${target}] ${a.body}`);
   }
+  lines.push(REPLY_ROUTING_HINT);
   return lines.join("\n");
 }
 

package/dist/inboxHook.js

@@ -154,6 +154,7 @@ function drainInbox(filePath) {
   }
   return out;
 }
+var REPLY_ROUTING_HINT = "(The senders can't see this chat. If a message needs a reply, send it with the `announce` tool \u2014 directed to the sender by name \u2014 not here.)";
 function formatInboxAnnouncements(announcements) {
   if (!announcements || announcements.length === 0) return "";
   const count = announcements.length;
@@ -164,27 +165,42 @@ function formatInboxAnnouncements(announcements) {
     const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
     lines.push(`  [${a.fromAgentName}${target}] ${a.body}`);
   }
+  lines.push(REPLY_ROUTING_HINT);
   return lines.join("\n");
 }
+function nativeWorkspacePath(root) {
+  const win = /^\/([A-Za-z]:[/\\].*)$/.exec(root);
+  return win ? win[1] : root;
+}
 function buildHookOutput(rawStdin, inboxDir, drain = drainInbox, nudge = buildLinkNudge) {
   let input;
   try {
-    input = JSON.parse(rawStdin);
+    input = JSON.parse(rawStdin.replace(/^\uFEFF/, ""));
   } catch {
     return "";
   }
-  if (!input || typeof input.cwd !== "string" || input.cwd.length === 0) return "";
+  if (!input || typeof input !== "object") return "";
+  const isCursor = typeof input.cursor_version === "string" || Array.isArray(input.workspace_roots);
+  const firstRoot = Array.isArray(input.workspace_roots) ? input.workspace_roots[0] : void 0;
+  const cwd = typeof input.cwd === "string" && input.cwd.length > 0 ? input.cwd : isCursor && typeof firstRoot === "string" && firstRoot.length > 0 ? nativeWorkspacePath(firstRoot) : null;
+  if (cwd === null) return "";
   const parts = [];
   const nudgeText = nudge(
-    input.cwd,
+    cwd,
     typeof input.tool_name === "string" ? input.tool_name : void 0
   );
   if (nudgeText) parts.push(nudgeText);
   if (inboxDir) {
-    const text = formatInboxAnnouncements(drain(inboxFilePath(inboxDir, input.cwd)));
+    const text = formatInboxAnnouncements(drain(inboxFilePath(inboxDir, cwd)));
     if (text) parts.push(text);
   }
   if (parts.length === 0) return "";
+  if (isCursor) {
+    return JSON.stringify({
+      continue: true,
+      additionalContext: parts.join("\n\n")
+    });
+  }
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: input.hook_event_name || "PreToolUse",

package/dist/index.js

@@ -34,7 +34,11 @@ var ConfigSchema = z.object({
   // context on its next action. Unset → no inbox, announcements flow only via
   // work/sync/done/announce tool results as before. Both the MCP server and the
   // hook must agree on this path.
-  SHEPHERD_INBOX_DIR: z.string().min(1).optional()
+  SHEPHERD_INBOX_DIR: z.string().min(1).optional(),
+  // Opt-out for the zero-setup hook auto-install (Layer 4). Any of "1", "true",
+  // "yes" (case-insensitive) disables it; everything else (including unset)
+  // leaves the default-on behavior. See hookInstall.ts and the README.
+  SHEPHERD_NO_AUTO_HOOKS: z.string().optional().transform((v) => ["1", "true", "yes"].includes((v ?? "").toLowerCase()))
 }).refine((c) => Boolean(c.SHEPHERD_TOKEN || c.TEAM_TOKEN), {
   message: "Either SHEPHERD_TOKEN or TEAM_TOKEN is required",
   path: ["SHEPHERD_TOKEN"]
@@ -52,7 +56,8 @@ function parseConfig(env) {
     PROGRAM: env["PROGRAM"],
     MODEL: env["MODEL"],
     HEARTBEAT_INTERVAL_SECONDS: env["HEARTBEAT_INTERVAL_SECONDS"],
-    SHEPHERD_INBOX_DIR: env["SHEPHERD_INBOX_DIR"]
+    SHEPHERD_INBOX_DIR: env["SHEPHERD_INBOX_DIR"],
+    SHEPHERD_NO_AUTO_HOOKS: env["SHEPHERD_NO_AUTO_HOOKS"]
   });
   const authToken = parsed.SHEPHERD_TOKEN ?? parsed.TEAM_TOKEN;
   return { ...parsed, authToken };
@@ -390,10 +395,16 @@ var WorkspaceAnnouncement = z2.object({
   // (no agent session). The dashboard renders these as "me" (right-aligned).
   // Defaulted for version-skew safety with older hubs.
   fromAdmin: z2.boolean().default(false),
-  // True when an agent addressed the message TO the operator (the mirror of
-  // fromAdmin). The dashboard renders these as "<agent> → admin". Not delivered
-  // to other agents. Defaulted for version-skew safety with older hubs.
+  // True when an agent addressed the message TO the operator side (the
+  // dashboard) — collectively (legacy) or a specific member (see
+  // targetMemberName). Not delivered to other agents. Defaulted for
+  // version-skew safety with older hubs.
   toAdmin: z2.boolean().default(false),
+  // When an agent addressed a SPECIFIC workspace member, the member's display
+  // name snapshotted at send time — the dashboard renders "→ <name>" instead of
+  // the collective "→ admin". Null for legacy/collective operator messages and
+  // everything else. Defaulted for version-skew safety with older hubs.
+  targetMemberName: z2.string().nullable().default(null),
   createdAt: IsoTimestamp
 });
 var WorkspaceLandscapeResponse = z2.object({
@@ -457,13 +468,20 @@ var DoneResponse = z2.object({
 var AnnounceRequest = z2.object({
   sessionId: z2.string().uuid(),
   body: z2.string().min(1).max(8192),
-  // absent or null => broadcast to all agents in the workspace
+  // THE preferred addressing field: one name that reaches either kind of
+  // teammate. The hub resolves it in order — a LIVE AGENT in the sender's repo
+  // (exact landscape name, e.g. "alex-rivera-2"), else the operator label
+  // ("admin" by default => the dashboard collectively), else a WORKSPACE MEMBER
+  // (a dashboard user, matched case-insensitively on display name, GitHub
+  // login, or email). No match => 400 listing both sets. Absent/null =>
+  // broadcast to all agents. Mutually exclusive with the legacy fields below.
+  target: z2.string().min(1).nullable().optional(),
+  // LEGACY (kept for older clients; prefer `target`): the exact live-agent name.
   targetAgentName: z2.string().nullable().optional(),
-  // true => address the human operator (the dashboard) instead of agents. The
-  // mirror of the operator's admin → agent DM: it shows in the workspace feed as
-  // "<agent> → admin" and is NOT delivered to other agents. Mutually exclusive
-  // with targetAgentName (the hub rejects setting both). Defaulted/optional for
-  // version skew with older clients.
+  // LEGACY (kept for older clients; prefer `target` with a member's name):
+  // true => address the human operators (the dashboard) collectively. Shows in
+  // the workspace feed as "<agent> → admin" and is NOT delivered to other
+  // agents. Mutually exclusive with targetAgentName and target.
   toAdmin: z2.boolean().optional()
 });
 var AnnounceResponse = z2.object({
@@ -1036,6 +1054,7 @@ function drainInbox(filePath) {
   }
   return out;
 }
+var REPLY_ROUTING_HINT = "(The senders can't see this chat. If a message needs a reply, send it with the `announce` tool \u2014 directed to the sender by name \u2014 not here.)";
 function mergeAnnouncements(...lists) {
   const byId = /* @__PURE__ */ new Map();
   for (const list of lists) {
@@ -1047,6 +1066,125 @@ function mergeAnnouncements(...lists) {
   return [...byId.values()].sort((x, y) => x.id - y.id);
 }
 
+// src/editTripwire.ts
+import { execFile } from "child_process";
+function createEditTripwire({
+  cwd,
+  intervalMs = 3e4,
+  onEdits,
+  runGitStatus = defaultRunGitStatus
+}) {
+  let timer = null;
+  let baseline = null;
+  let disarmed = false;
+  function stop() {
+    disarmed = true;
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+  async function check() {
+    const out = await runGitStatus(cwd);
+    if (out === null || baseline === null || disarmed) return;
+    for (const path3 of parsePorcelainPaths(out)) {
+      if (!baseline.has(path3)) {
+        stop();
+        try {
+          onEdits();
+        } catch (err) {
+          console.error(
+            `[shepherd] edit-tripwire handler failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        return;
+      }
+    }
+  }
+  function start() {
+    stop();
+    disarmed = false;
+    void (async () => {
+      const out = await runGitStatus(cwd);
+      if (out === null || disarmed) return;
+      baseline = new Set(parsePorcelainPaths(out));
+      timer = setInterval(() => {
+        void check().catch(() => {
+        });
+      }, intervalMs);
+      timer.unref();
+    })();
+  }
+  return { start, stop };
+}
+function parsePorcelainPaths(out) {
+  return out.split("\n").filter((line) => line.length > 3).map((line) => line.slice(3));
+}
+function defaultRunGitStatus(cwd) {
+  return new Promise((resolve4) => {
+    execFile(
+      "git",
+      ["status", "--porcelain"],
+      { cwd, timeout: 5e3, windowsHide: true },
+      (err, stdout) => {
+        resolve4(err ? null : stdout);
+      }
+    );
+  });
+}
+
+// src/linkPopup.ts
+var NEVER_ASK_CHOICE = "No \u2014 don't ask again";
+async function offerLinkPopup({
+  repoName,
+  elicit,
+  listWorkspaces,
+  linkWorkspace,
+  neverAskAgain
+}) {
+  let slugs;
+  try {
+    slugs = await listWorkspaces();
+  } catch {
+    return { outcome: "unanswered" };
+  }
+  if (slugs.length === 0) return { outcome: "unanswered" };
+  let response;
+  try {
+    response = await elicit({
+      message: `Shepherd: "${repoName}" isn't linked to a team workspace, so teammates can't see the work happening here. Link it to start coordinating? This writes a small .shepherd file naming the workspace (commit it so teammates inherit the link). Dismiss to decide later \u2014 you'll be asked again next session.`,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          decision: {
+            type: "string",
+            title: "Workspace",
+            description: `Use the arrow keys (\u2192) to view your workspaces. Pick one to link this repo, or "${NEVER_ASK_CHOICE}".`,
+            enum: [...slugs, NEVER_ASK_CHOICE]
+          }
+        },
+        required: ["decision"]
+      }
+    });
+  } catch {
+    return { outcome: "unanswered" };
+  }
+  if (response?.action !== "accept") return { outcome: "unanswered" };
+  const decision = response.content?.decision;
+  if (typeof decision !== "string") return { outcome: "unanswered" };
+  if (decision === NEVER_ASK_CHOICE) {
+    neverAskAgain();
+    return { outcome: "declined" };
+  }
+  if (!slugs.includes(decision)) return { outcome: "unanswered" };
+  try {
+    await linkWorkspace(decision);
+  } catch {
+    return { outcome: "unanswered" };
+  }
+  return { outcome: "linked", workspace: decision };
+}
+
 // src/tools.ts
 function classifyJoinFailure(err) {
   if (err instanceof HubUnreachable) return "unreachable";
@@ -1116,6 +1254,7 @@ function formatLandscape(landscape) {
       const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
       lines.push(`  [${a.fromAgentName}${target}] ${a.body}`);
     }
+    lines.push(REPLY_ROUTING_HINT);
   } else {
     lines.push("ANNOUNCEMENTS: none");
   }
@@ -1128,6 +1267,7 @@ function formatAnnouncements(announcements) {
     const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
     lines.push(`  [${a.fromAgentName}${target}] ${a.body}`);
   }
+  lines.push(REPLY_ROUTING_HINT);
   return lines.join("\n");
 }
 function relativeAge(iso) {
@@ -1210,13 +1350,28 @@ function registerTools(server, deps) {
   const dormant = !context.linked || selfHostMismatch;
   let linked = context.linked;
   let declined = context.declined;
+  const gatedTools = [];
+  let surfaceVisible = true;
+  function syncToolSurface() {
+    const visible = linked || !declined;
+    if (visible === surfaceVisible) return;
+    surfaceVisible = visible;
+    for (const tool of gatedTools) {
+      if (visible) tool?.enable();
+      else tool?.disable();
+    }
+  }
+  let tripwire = null;
   function rememberDecline() {
     if (repoRoot !== null) setDeclined(repoRoot, declinedDir);
     declined = true;
+    tripwire?.stop();
+    syncToolSurface();
   }
   function forgetDecline() {
     if (repoRoot !== null) clearDeclined(repoRoot, declinedDir);
     declined = false;
+    syncToolSurface();
   }
   let joinFailure = null;
   let joinInFlight = Promise.resolve();
@@ -1347,7 +1502,7 @@ ${body}` : body;
 
 ${section}` : body;
   }
-  server.registerTool(
+  const workTool = server.registerTool(
     "work",
     {
       title: "Claim a unit of work",
@@ -1384,7 +1539,7 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
       }
     }
   );
-  server.registerTool(
+  const doneTool = server.registerTool(
     "done",
     {
       title: "Release a work claim",
@@ -1416,11 +1571,11 @@ ${msgs}` : base }
       }
     }
   );
-  server.registerTool(
+  const announceTool = server.registerTool(
     "announce",
     {
-      title: "Broadcast a message to teammates",
-      description: "Broadcast a heads-up to the other agents, direct a finding to a specific agent, or reply to the human operator. This is awareness only \u2014 not a task assignment. To direct it to an agent, pass that agent's EXACT name as shown in the landscape \u2014 including its numeric suffix (e.g. 'alex-rivera-2', NOT the bare handle 'alex-rivera') \u2014 as targetAgentName. Several agents can share one handle (alex-rivera-1, alex-rivera-2, \u2026); the suffix is what picks one, so the bare handle is rejected. The hub rejects any targetAgentName that doesn't match a live agent in your repo \u2014 if you mean the whole team, omit it to broadcast. To reply to the operator (the dashboard), pass toAdmin: true. targetAgentName and toAdmin are mutually exclusive. Delivery is best-effort: the recipient sees it on their next work/sync, once.",
+      title: "Message teammates (agents or humans)",
+      description: "Broadcast a heads-up to the other agents, direct a finding to a specific teammate, or reply to a human on the dashboard. This is awareness only \u2014 not a task assignment. To direct it, pass ONE name as `target`: an agent's EXACT name as shown in the landscape \u2014 including its numeric suffix (e.g. 'alex-rivera-2', NOT the bare handle 'alex-rivera'; several agents can share one handle, the suffix picks one) \u2014 OR a human's name to reach that workspace member on the dashboard (reply to the person a message came from by using their sender name as target), OR 'admin' to reach the dashboard collectively. The hub rejects a target that matches no live agent and no member \u2014 if you mean the whole team, omit target to broadcast. (targetAgentName and toAdmin are deprecated aliases; don't combine them with target.) Delivery is best-effort: agents see it on their next work/sync, once; humans see the feed.",
       inputSchema: AnnounceAgentInput.shape
     },
     async (args) => {
@@ -1448,7 +1603,7 @@ ${msgs}` : base }
       }
     }
   );
-  server.registerTool(
+  const syncTool = server.registerTool(
     "sync",
     {
       title: "Sync team landscape",
@@ -1481,10 +1636,16 @@ ${msgs}` : base }
   function advisory(text) {
     return { content: [{ type: "text", text }] };
   }
+  async function linkableSlugs() {
+    if (!isHosted) return config.WORKSPACE ? [config.WORKSPACE] : [];
+    const res = await hubClient.get("/workspaces");
+    return (res.workspaces ?? []).map((w) => w.slug).filter((s) => typeof s === "string" && s.length > 0);
+  }
   async function linkAndActivate(slug) {
     writeMarker(markerCwd, slug);
     forgetDecline();
     linked = true;
+    tripwire?.stop();
     const result = await activate(slug);
     if (result.ok) {
       return advisory(`Linked this repo to \`${slug}\` \u2014 coordinating in \`${slug}\` now.`);
@@ -1520,8 +1681,7 @@ ${msgs}` : base }
       }
       let slugs;
       try {
-        const res = await hubClient.get("/workspaces");
-        slugs = (res.workspaces ?? []).map((w) => w.slug).filter((s) => typeof s === "string" && s.length > 0);
+        slugs = await linkableSlugs();
       } catch (err) {
         const detail = hubErrorDetail(err);
         return advisory(
@@ -1549,7 +1709,7 @@ ${msgs}` : base }
       return linkAndActivate(requested);
     }
   );
-  server.registerTool(
+  const unlinkTool = server.registerTool(
     "unlink",
     {
       title: "Unlink this repo from its Shepherd workspace",
@@ -1560,6 +1720,7 @@ ${msgs}` : base }
       removeMarker(markerCwd);
       rememberDecline();
       linked = false;
+      syncToolSurface();
       if (sessionId !== null) {
         heartbeat.stop();
         await leave();
@@ -1571,7 +1732,7 @@ ${msgs}` : base }
       );
     }
   );
-  server.registerTool(
+  const declineTool = server.registerTool(
     "decline",
     {
       title: "Decline Shepherd coordination for this repo",
@@ -1601,8 +1762,64 @@ ${msgs}` : base }
       );
     }
   }
+  gatedTools.push(workTool, doneTool, announceTool, syncTool, unlinkTool, declineTool);
+  surfaceVisible = true;
+  syncToolSurface();
+  async function runFirstRunAsk() {
+    try {
+      if (linked || declined) return;
+      const getCaps = deps.firstRunAsk?.getClientCapabilities ?? (() => server.server.getClientCapabilities());
+      if (!getCaps()?.elicitation) return;
+      const elicit = deps.firstRunAsk?.elicit ?? // Generous timeout: the user may leave the dialog open while they think.
+      // The param cast bridges our structural ElicitParams to the SDK's
+      // stricter schema type — the shapes agree (flat string enum).
+      ((params) => server.server.elicitInput(
+        params,
+        { timeout: 10 * 6e4 }
+      ));
+      const { outcome, workspace } = await offerLinkPopup({
+        repoName: context.repo,
+        elicit,
+        listWorkspaces: linkableSlugs,
+        linkWorkspace: async (slug) => {
+          await linkAndActivate(slug);
+        },
+        neverAskAgain: rememberDecline
+      });
+      if (outcome === "linked" && inboxFile) {
+        appendAnnouncements(inboxFile, [postLinkGuidance(workspace ?? "")]);
+      }
+      if (outcome !== "unanswered") {
+        console.error(`[shepherd] first-run ask answered by the user: ${outcome}`);
+      }
+    } catch (err) {
+      console.error(
+        `[shepherd] first-run ask failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  if (!context.linked && !context.declined) {
+    const createTripwire_ = deps.firstRunAsk?.createTripwire ?? createEditTripwire;
+    tripwire = createTripwire_({
+      cwd: markerCwd,
+      onEdits: () => {
+        void runFirstRunAsk();
+      }
+    });
+    tripwire.start();
+  }
   return { ready: joinInFlight, leave };
 }
+function postLinkGuidance(workspace) {
+  return {
+    id: -Date.now(),
+    fromAgentName: "shepherd",
+    fromHuman: "shepherd",
+    targetAgentName: null,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    body: `The user just linked this repository to the \`${workspace}\` workspace \u2014 coordination is NOW ACTIVE. Standing procedure from here on: call \`work\` (one-line intent + pathGlobs) BEFORE changing files in an area; \`done\` when that unit of work is complete; \`announce\` anything teammates need to know; \`sync\` when you resume or switch tasks. Start by calling \`work\` for the files you're editing right now.`
+  };
+}
 
 // src/identityCache.ts
 import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
@@ -1741,11 +1958,25 @@ function createHeartbeat({
 }
 
 // src/instructions.ts
-var SHEPHERD_INSTRUCTIONS = `You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories.
+function buildInstructions(state, workspace) {
+  switch (state) {
+    case "linked":
+      return `${INTRO} This repository is linked to the \`${workspace ?? "team"}\` workspace, so coordination is active.
+
+${PROCEDURE}`;
+    case "declined":
+      return "Shepherd (team coordination) is connected, but the user declined coordination for this repository. Do not call Shepherd tools or bring up coordination here. If the user asks to start coordinating this repo, call `link`.";
+    case "unanswered":
+      return `${INTRO}
 
-On your first coordination-relevant action in a repo, if it isn't linked and hasn't been declined, call \`link\` with no argument: it auto-starts coordination if you belong to exactly one workspace, or lists your workspaces \u2014 ask the user "Coordinate this repo with Shepherd? Which workspace?" then call \`link <workspace>\` with their answer, or \`decline\` if they say no. Ask at most once per repo: once linked or declined, do not ask again \u2014 the marker is committed and teammates inherit it, so coordination is automatic from then on.
+${FIRST_RUN_ASK}`;
+  }
+}
+var INTRO = "You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories.";
+var FIRST_RUN_ASK = `This repository isn't linked to a Shepherd workspace yet, so coordination is dormant. Shepherd normally asks the user directly (a popup) when file edits are detected \u2014 you don't need to raise it yourself.
 
-Once linked, follow this procedure on every session, proactively and without being asked:
+If the user asks you to set up coordination \u2014 or you're about to change files and no popup or Shepherd message has settled the question \u2014 ask at most once: call \`link\` with no argument. It auto-links when the user belongs to exactly one workspace, or lists the choices; ask the user which workspace, then call \`link\` again with their answer. If they say no, call \`decline\` so they're never asked again. Once linked, the tool results will guide the coordination procedure.`;
+var PROCEDURE = `Follow this procedure on every session, proactively and without being asked:
 
 1. Before you start producing or changing files in an AREA of the codebase, call \`work\` ONCE. This includes authoring a plan or design doc: claim the doc's path (e.g. ["docs/plans/auth.md"], or the directory you'll write into) BEFORE you write it \u2014 a plan you're about to author counts as a unit of work, not exploration. Pass a one-line \`intent\` and the \`pathGlobs\` covering the files you expect to touch. Scope the globs as specifically as you reasonably can \u2014 tight enough to avoid colliding with unrelated work, broad enough to cover the task (e.g. ["src/auth/**"], not ["src/**"] and not a single file). Hold that one claim across all your edits in that area; do NOT re-claim per file. If it reports a conflict, coordinate or pick different work \u2014 never silently collide.
 
@@ -1753,7 +1984,7 @@ Once linked, follow this procedure on every session, proactively and without bei
 
 3. Re-call \`work\` only when you move to a DIFFERENT area not covered by a live claim. (\`work\` and \`sync\` also renew your existing claims.)
 
-4. Call \`announce\` whenever you discover something another agent needs \u2014 a shared decision, a gotcha, an API change, a finding. If the landscape shows a specific agent working in the affected area, direct it to them by passing their name as \`targetAgentName\`; otherwise broadcast. Awareness only, not task assignment.
+4. Call \`announce\` whenever you discover something another agent needs \u2014 a shared decision, a gotcha, an API change, a finding. If the landscape shows a specific agent working in the affected area, direct it to them by passing their name as \`target\`; otherwise broadcast. A human teammate's name (or \`admin\`) as \`target\` reaches them on the dashboard \u2014 reply to a human's message that way, directed to its sender, never in your own chat. Awareness only, not task assignment.
 
 5. Call \`sync\` when you resume, start a new task, or before large changes, to refresh who is doing what.
 
@@ -1761,6 +1992,209 @@ Skip \`work\` entirely for read-only exploration \u2014 reading, searching, or t
 
 Commit work-in-progress as you go rather than sitting on a large dirty tree: committed work becomes a precise, presence-independent signal to teammates (with line-level detail and automatic resolution once it lands), whereas uncommitted edits are only a best-effort, decaying hint.`;
 
+// src/hookInstall.ts
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, mkdirSync as mkdirSync4, copyFileSync, existsSync as existsSync4 } from "fs";
+import { homedir as homedir4 } from "os";
+import { dirname as dirname5, join as join5 } from "path";
+import { fileURLToPath } from "url";
+function detectClient(clientName) {
+  const name = (clientName ?? "").toLowerCase();
+  if (!name) return "unknown";
+  if (name.includes("claude")) return "claude";
+  if (name.includes("codex")) return "codex";
+  if (name.includes("cursor")) return "cursor";
+  if (/(^|[^a-z0-9])pi([^a-z0-9]|$)/.test(name)) return "pi";
+  return "unknown";
+}
+var HOOK_COMMAND = "npx -y --package=@korso/shepherd shepherd-inbox-hook";
+var HOOK_MARKER = "shepherd-inbox-hook";
+var CODEX_HOOK_BLOCK = [
+  "",
+  "# Added by Shepherd: delivers teammate announcements to the agent. Remove to disable.",
+  "[[hooks.UserPromptSubmit]]",
+  'command = ["npx", "-y", "--package=@korso/shepherd", "shepherd-inbox-hook"]',
+  ""
+].join("\n");
+async function autoInstallHooks({
+  clientName,
+  homeDir = homedir4(),
+  disabled = false,
+  extensionSource,
+  log = (msg) => console.error(msg)
+}) {
+  const client = detectClient(clientName);
+  try {
+    if (disabled) return { client, status: "disabled" };
+    if (client === "unknown") {
+      return { client, status: "unsupported" };
+    }
+    const recordFile = join5(homeDir, ".shepherd", "hooks", `${client}.json`);
+    if (existsSync4(recordFile)) return { client, status: "already-attempted" };
+    let status;
+    if (client === "claude") {
+      status = installClaude(homeDir, log);
+    } else if (client === "codex") {
+      status = installCodex(homeDir, log);
+    } else if (client === "cursor") {
+      status = installCursor(homeDir, log);
+    } else {
+      status = installPi(homeDir, extensionSource, log);
+    }
+    mkdirSync4(dirname5(recordFile), { recursive: true });
+    writeFileSync4(
+      recordFile,
+      JSON.stringify({ status, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n",
+      "utf8"
+    );
+    if (status === "installed") {
+      log(
+        `[shepherd] Installed the announcement-delivery hook for ${client} (disable by removing it, or set SHEPHERD_NO_AUTO_HOOKS=1 to never auto-install).`
+      );
+    }
+    return { client, status };
+  } catch (err) {
+    log(
+      `[shepherd] hook auto-install skipped: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return { client, status: "skipped" };
+  }
+}
+function installClaude(homeDir, log) {
+  const settingsFile = join5(homeDir, ".claude", "settings.json");
+  let raw = "";
+  if (existsSync4(settingsFile)) {
+    raw = readFileSync5(settingsFile, "utf8");
+    if (raw.includes(HOOK_MARKER)) return "already-present";
+  }
+  let settings = {};
+  if (raw.trim()) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("settings.json is not a JSON object");
+      }
+      settings = parsed;
+    } catch {
+      log(
+        `[shepherd] ${settingsFile} could not be parsed \u2014 not touching it. Add the hook manually (see the dashboard's Connect screen).`
+      );
+      return "skipped";
+    }
+  }
+  const hooks = settings["hooks"] ??= {};
+  if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks)) {
+    log(`[shepherd] ${settingsFile} has an unexpected "hooks" shape \u2014 not touching it.`);
+    return "skipped";
+  }
+  const hooksObj = hooks;
+  for (const event of ["SessionStart", "PreToolUse"]) {
+    const existing = hooksObj[event] ??= [];
+    if (!Array.isArray(existing)) {
+      log(`[shepherd] ${settingsFile} has an unexpected hooks.${event} shape \u2014 not touching it.`);
+      return "skipped";
+    }
+  }
+  hooksObj["SessionStart"].push({
+    hooks: [{ type: "command", command: HOOK_COMMAND }]
+  });
+  hooksObj["PreToolUse"].push({
+    matcher: "*",
+    hooks: [{ type: "command", command: HOOK_COMMAND }]
+  });
+  mkdirSync4(dirname5(settingsFile), { recursive: true });
+  writeFileSync4(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  return "installed";
+}
+function installCodex(homeDir, log) {
+  const configFile = join5(homeDir, ".codex", "config.toml");
+  const manualHint = "Add the hook manually (see the dashboard's Connect screen).";
+  if (!existsSync4(configFile)) {
+    mkdirSync4(dirname5(configFile), { recursive: true });
+    writeFileSync4(configFile, `[features]
+hooks = true
+${CODEX_HOOK_BLOCK}`, "utf8");
+    return "installed";
+  }
+  const toml = readFileSync5(configFile, "utf8");
+  if (toml.includes(HOOK_MARKER)) return "already-present";
+  if (/^\s*\[hooks\.UserPromptSubmit\]\s*$/m.test(toml)) {
+    log(`[shepherd] ${configFile} defines [hooks.UserPromptSubmit] \u2014 not touching it. ${manualHint}`);
+    return "skipped";
+  }
+  if (/^\s*\[features\]/m.test(toml)) {
+    const hooksKey = /^\s*hooks\s*=\s*(.+)$/m.exec(toml);
+    if (hooksKey && hooksKey[1].trim() !== "true") {
+      log(`[shepherd] ${configFile} sets hooks = ${hooksKey[1].trim()} \u2014 respecting it. ${manualHint}`);
+      return "skipped";
+    }
+    let updated = toml;
+    if (!hooksKey) {
+      updated = toml.replace(/^(\s*\[features\]\s*)$/m, `$1
+hooks = true`);
+    }
+    writeFileSync4(configFile, updated + CODEX_HOOK_BLOCK, "utf8");
+    return "installed";
+  }
+  writeFileSync4(configFile, `${toml}
+[features]
+hooks = true
+${CODEX_HOOK_BLOCK}`, "utf8");
+  return "installed";
+}
+function installCursor(homeDir, log) {
+  const hooksFile = join5(homeDir, ".cursor", "hooks.json");
+  let raw = "";
+  if (existsSync4(hooksFile)) {
+    raw = readFileSync5(hooksFile, "utf8");
+    if (raw.includes(HOOK_MARKER)) return "already-present";
+  }
+  let config = {};
+  if (raw.trim()) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("hooks.json is not a JSON object");
+      }
+      config = parsed;
+    } catch {
+      log(
+        `[shepherd] ${hooksFile} could not be parsed \u2014 not touching it. Add the hook manually (see the dashboard's Connect screen).`
+      );
+      return "skipped";
+    }
+  }
+  config["version"] ??= 1;
+  const hooks = config["hooks"] ??= {};
+  if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks)) {
+    log(`[shepherd] ${hooksFile} has an unexpected "hooks" shape \u2014 not touching it.`);
+    return "skipped";
+  }
+  const hooksObj = hooks;
+  const entries = hooksObj["beforeSubmitPrompt"] ??= [];
+  if (!Array.isArray(entries)) {
+    log(
+      `[shepherd] ${hooksFile} has an unexpected hooks.beforeSubmitPrompt shape \u2014 not touching it.`
+    );
+    return "skipped";
+  }
+  entries.push({ command: HOOK_COMMAND });
+  mkdirSync4(dirname5(hooksFile), { recursive: true });
+  writeFileSync4(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
+  return "installed";
+}
+function installPi(homeDir, extensionSource, log) {
+  const source = extensionSource ?? join5(dirname5(fileURLToPath(import.meta.url)), "inboxExtension.js");
+  const dest = join5(homeDir, ".pi", "agent", "extensions", "shepherd-inbox.js");
+  if (existsSync4(dest)) return "already-present";
+  if (!existsSync4(source)) {
+    log(`[shepherd] bundled Pi extension not found at ${source} \u2014 skipping auto-install.`);
+    return "skipped";
+  }
+  mkdirSync4(dirname5(dest), { recursive: true });
+  copyFileSync(source, dest);
+  return "installed";
+}
+
 // src/index.ts
 async function main() {
   const config = loadConfig();
@@ -1787,10 +2221,16 @@ async function main() {
   });
   const server = new McpServer(
     { name: "shepherd", version: "0.1.0" },
-    { instructions: SHEPHERD_INSTRUCTIONS }
+    { instructions: buildInstructions(context.linkState, context.workspace) }
   );
   const tools = registerTools(server, { hubClient, config, context, heartbeat, inboxFile });
   const transport = new StdioServerTransport();
+  server.server.oninitialized = () => {
+    void autoInstallHooks({
+      clientName: server.server.getClientVersion()?.name,
+      disabled: config.SHEPHERD_NO_AUTO_HOOKS
+    });
+  };
   let shuttingDown = false;
   const shutdown = async () => {
     if (shuttingDown) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory cross-session coordination tools (work/done/announce/sync) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "type": "module",
   "main": "dist/index.js",