@korso/shepherd 0.6.3 → 0.7.0

package/README.md

@@ -99,9 +99,22 @@ It delivers to an agent **while it's active**; an idle agent picks messages up t
 moment it next does anything. (Waking a fully-idle agent is out of scope — for
 Claude Code that needs Channels; Codex/Pi have no equivalent.)
 
-### Claude Code — `PreToolUse` hook
-
-`PreToolUse` fires before every tool, giving the most frequent passive delivery.
+**The hook also carries the unlinked-repo nudge.** The server instructions tell
+the agent to ask about linking on its first write in a new repo, but instructions
+sitting passively in context don't trigger themselves — an agent focused on the
+task can skip straight to editing. So on every invocation the hook also checks
+this repo's link state and, when the repo is **neither linked (`.shepherd`
+marker) nor declined**, injects a reminder to run `link`/`decline` — on
+`SessionStart` (front-loads the ask), right before a file-writing tool
+(`Edit`/`Write`/`MultiEdit`/`NotebookEdit`; read-only tools never nudge), and on
+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.
+
+### Claude Code — `PreToolUse` + `SessionStart` hooks
+
+`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
 uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
 
@@ -118,6 +131,13 @@ uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
     }
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "npx -y --package=@korso/shepherd shepherd-inbox-hook" }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "*",
@@ -161,8 +181,8 @@ cp "$(npm root -g)/@korso/shepherd/dist/inboxExtension.js" ~/.pi/agent/extension
 ```
 
 It runs on every user turn (`before_agent_start`), drains the same inbox, and
-injects pending announcements. (Or load it ad hoc with
-`pi -e /abs/path/to/dist/inboxExtension.js`.)
+injects pending announcements plus the unlinked-repo nudge. (Or load it ad hoc
+with `pi -e /abs/path/to/dist/inboxExtension.js`.)
 
 ### Notes
 

package/dist/inboxExtension.js

@@ -1,16 +1,59 @@
 // src/inbox.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import {
   appendFileSync,
-  mkdirSync,
-  readFileSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
   renameSync,
-  rmSync,
-  existsSync
+  rmSync as rmSync3,
+  existsSync as existsSync3
 } from "fs";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
+
+// src/marker.ts
+import * as fs from "fs";
+import * as path from "path";
+var MARKER_FILENAME = ".shepherd";
+function findRepoRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (; ; ) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function markerPath(cwd) {
+  const root = findRepoRoot(cwd);
+  return root === null ? null : path.join(root, MARKER_FILENAME);
+}
+function readMarker(cwd = process.cwd()) {
+  const file = markerPath(cwd);
+  if (file === null) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && typeof parsed.workspace === "string" && parsed.workspace.length > 0) {
+      return { workspace: parsed.workspace };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/declined.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { homedir, tmpdir } from "os";
-import { dirname, join, resolve } from "path";
-function defaultInboxDir() {
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+function defaultDeclinedDir() {
   let base = "";
   try {
     base = homedir();
@@ -18,29 +61,78 @@ function defaultInboxDir() {
     base = "";
   }
   if (!base) base = tmpdir();
-  return join(base, ".shepherd", "inbox");
+  return join2(base, ".shepherd", "declined");
 }
-function inboxFilePath(dir, cwd) {
-  let normalized = resolve(cwd);
+function declinedFilePath(repoRoot, dir = defaultDeclinedDir()) {
+  let normalized = resolve2(repoRoot);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
   const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join(dir, `${hash}.jsonl`);
+  return join2(dir, hash);
+}
+function isDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  let raw;
+  try {
+    raw = readFileSync2(file, "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.declinedAt === "string";
+  } catch {
+    return false;
+  }
+}
+
+// src/linkNudge.ts
+var WRITE_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+var LINK_NUDGE_TEXT = '[Shepherd] This repo is not linked to a Shepherd workspace and has not been declined. Before writing files here, call the shepherd `link` tool with no argument: it auto-links if the user belongs to exactly one workspace, or lists workspaces \u2014 then ask the user "Coordinate this repo with Shepherd? Which workspace?" and call `link <workspace>` with their answer, or `decline` if they say no. Ask at most once per repo.';
+function buildLinkNudge(cwd, toolName, deps = {}) {
+  try {
+    if (toolName !== void 0 && !WRITE_TOOLS.has(toolName)) return "";
+    const repoRoot = findRepoRoot(cwd);
+    if (repoRoot === null) return "";
+    if (readMarker(cwd) !== null) return "";
+    if (isDeclined(repoRoot, deps.declinedDir)) return "";
+    return LINK_NUDGE_TEXT;
+  } catch {
+    return "";
+  }
+}
+
+// src/inbox.ts
+function defaultInboxDir() {
+  let base = "";
+  try {
+    base = homedir2();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir2();
+  return join3(base, ".shepherd", "inbox");
+}
+function inboxFilePath(dir, cwd) {
+  let normalized = resolve3(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join3(dir, `${hash}.jsonl`);
 }
 function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
   let raw = "";
   try {
-    if (existsSync(tmp)) {
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+    if (existsSync3(tmp)) {
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
   try {
-    if (existsSync(filePath)) {
+    if (existsSync3(filePath)) {
       renameSync(filePath, tmp);
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
@@ -80,7 +172,7 @@ function shepherdInbox(pi) {
       const dir = process.env["SHEPHERD_INBOX_DIR"] || defaultInboxDir();
       const cwd = ctx?.cwd ?? process.cwd();
       const announcements = drainInbox(inboxFilePath(dir, cwd));
-      const content = formatInboxAnnouncements(announcements);
+      const content = [buildLinkNudge(cwd), formatInboxAnnouncements(announcements)].filter(Boolean).join("\n\n");
       if (!content) return void 0;
       return { message: { customType: "shepherd-inbox", content, display: true } };
     } catch {

package/dist/inboxHook.js

@@ -1,18 +1,61 @@
 #!/usr/bin/env node
 
 // src/inbox.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import {
   appendFileSync,
-  mkdirSync,
-  readFileSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
   renameSync,
-  rmSync,
-  existsSync
+  rmSync as rmSync3,
+  existsSync as existsSync3
 } from "fs";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
+
+// src/marker.ts
+import * as fs from "fs";
+import * as path from "path";
+var MARKER_FILENAME = ".shepherd";
+function findRepoRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (; ; ) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function markerPath(cwd) {
+  const root = findRepoRoot(cwd);
+  return root === null ? null : path.join(root, MARKER_FILENAME);
+}
+function readMarker(cwd = process.cwd()) {
+  const file = markerPath(cwd);
+  if (file === null) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && typeof parsed.workspace === "string" && parsed.workspace.length > 0) {
+      return { workspace: parsed.workspace };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/declined.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { homedir, tmpdir } from "os";
-import { dirname, join, resolve } from "path";
-function defaultInboxDir() {
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+function defaultDeclinedDir() {
   let base = "";
   try {
     base = homedir();
@@ -20,29 +63,78 @@ function defaultInboxDir() {
     base = "";
   }
   if (!base) base = tmpdir();
-  return join(base, ".shepherd", "inbox");
+  return join2(base, ".shepherd", "declined");
 }
-function inboxFilePath(dir, cwd) {
-  let normalized = resolve(cwd);
+function declinedFilePath(repoRoot, dir = defaultDeclinedDir()) {
+  let normalized = resolve2(repoRoot);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
   const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join(dir, `${hash}.jsonl`);
+  return join2(dir, hash);
+}
+function isDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  let raw;
+  try {
+    raw = readFileSync2(file, "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.declinedAt === "string";
+  } catch {
+    return false;
+  }
+}
+
+// src/linkNudge.ts
+var WRITE_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+var LINK_NUDGE_TEXT = '[Shepherd] This repo is not linked to a Shepherd workspace and has not been declined. Before writing files here, call the shepherd `link` tool with no argument: it auto-links if the user belongs to exactly one workspace, or lists workspaces \u2014 then ask the user "Coordinate this repo with Shepherd? Which workspace?" and call `link <workspace>` with their answer, or `decline` if they say no. Ask at most once per repo.';
+function buildLinkNudge(cwd, toolName, deps = {}) {
+  try {
+    if (toolName !== void 0 && !WRITE_TOOLS.has(toolName)) return "";
+    const repoRoot = findRepoRoot(cwd);
+    if (repoRoot === null) return "";
+    if (readMarker(cwd) !== null) return "";
+    if (isDeclined(repoRoot, deps.declinedDir)) return "";
+    return LINK_NUDGE_TEXT;
+  } catch {
+    return "";
+  }
+}
+
+// src/inbox.ts
+function defaultInboxDir() {
+  let base = "";
+  try {
+    base = homedir2();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir2();
+  return join3(base, ".shepherd", "inbox");
+}
+function inboxFilePath(dir, cwd) {
+  let normalized = resolve3(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join3(dir, `${hash}.jsonl`);
 }
 function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
   let raw = "";
   try {
-    if (existsSync(tmp)) {
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+    if (existsSync3(tmp)) {
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
   try {
-    if (existsSync(filePath)) {
+    if (existsSync3(filePath)) {
       renameSync(filePath, tmp);
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
@@ -74,8 +166,7 @@ function formatInboxAnnouncements(announcements) {
   }
   return lines.join("\n");
 }
-function buildHookOutput(rawStdin, inboxDir, drain = drainInbox) {
-  if (!inboxDir) return "";
+function buildHookOutput(rawStdin, inboxDir, drain = drainInbox, nudge = buildLinkNudge) {
   let input;
   try {
     input = JSON.parse(rawStdin);
@@ -83,13 +174,21 @@ function buildHookOutput(rawStdin, inboxDir, drain = drainInbox) {
     return "";
   }
   if (!input || typeof input.cwd !== "string" || input.cwd.length === 0) return "";
-  const announcements = drain(inboxFilePath(inboxDir, input.cwd));
-  const text = formatInboxAnnouncements(announcements);
-  if (!text) return "";
+  const parts = [];
+  const nudgeText = nudge(
+    input.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)));
+    if (text) parts.push(text);
+  }
+  if (parts.length === 0) return "";
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: input.hook_event_name || "PreToolUse",
-      additionalContext: text
+      additionalContext: parts.join("\n\n")
     }
   });
 }

package/dist/index.js

@@ -783,7 +783,10 @@ function detectHuman(cwd = process.cwd()) {
     return null;
   }
   const name = runGit(cwd, ["config", "user.name"]);
-  if (name) return name;
+  if (name) {
+    const local = name.includes("@") ? name.split("@")[0] : name;
+    if (local) return local;
+  }
   const email = runGit(cwd, ["config", "user.email"]);
   if (email) {
     const local = email.split("@")[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "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",