@korso/shepherd 0.4.1 → 0.4.2

package/README.md

@@ -59,6 +59,111 @@ override only to replace what's detected:
 | `PROGRAM` | defaults to `claude-code` | `codex` |
 | `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` |
+
+---
+
+## Announcement push (on by default)
+
+Announcements reach an agent **without it having to ask**. The background
+heartbeat pulls any pending announcements from the hub every beat and stages them
+in a local **inbox file** (per working directory, under `SHEPHERD_INBOX_DIR`,
+default `~/.shepherd/inbox`). That file is then drained by two paths:
+
+1. **Universal drainer (always on, every client).** Whenever the agent calls any
+   Shepherd tool (`work`/`sync`/`done`/`announce`), the result also includes
+   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.
+
+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
+merge is just defensive). It's cheap: a **local file read — no network** (the
+heartbeat already did the fetch), and it only adds to the model's context when
+something is actually waiting.
+
+It delivers to an agent **while it's active**; an idle agent picks messages up the
+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 needs no arguments — it resolves the same default inbox dir the server
+uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123"
+      }
+    }
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "npx -y -p @korso/shepherd shepherd-inbox-hook" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Codex — `UserPromptSubmit` hook
+
+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`
+or MCP calls. Hooks must be enabled with `features.hooks = true`. In
+`~/.codex/config.toml`:
+
+```toml
+[features]
+hooks = true
+
+[[hooks.UserPromptSubmit]]
+command = ["npx", "-y", "-p", "@korso/shepherd", "shepherd-inbox-hook"]
+# On Windows use command_windows instead:
+# command_windows = ["cmd", "/c", "npx -y -p @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:
+
+```sh
+# global, applies everywhere:
+mkdir -p ~/.pi/agent/extensions
+cp "$(npm root -g)/@korso/shepherd/dist/inboxExtension.js" ~/.pi/agent/extensions/shepherd-inbox.js
+# …or per-project: copy into .pi/extensions/ in the repo root.
+```
+
+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`.)
+
+### Notes
+
+Every path is **fail-open**: a missing dir, unreachable hub, or any error means
+nothing is surfaced and the tool call / turn proceeds normally — coordination
+never blocks the agent. The inbox is keyed per working directory; two sessions in
+the exact same directory share it (a benign edge — they're the same repo). If you
+override `SHEPHERD_INBOX_DIR` on the server, set it on the hook/extension to the
+same value (the Claude/Codex bin and the Pi extension both read
+`SHEPHERD_INBOX_DIR`, or you can pass the dir as the first CLI arg to the bin).
 
 ---
 

package/dist/inboxExtension.js

@@ -0,0 +1,93 @@
+// src/inbox.ts
+import { createHash } from "crypto";
+import {
+  appendFileSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  existsSync
+} from "fs";
+import { homedir, tmpdir } from "os";
+import { dirname, join, resolve } from "path";
+function defaultInboxDir() {
+  let base = "";
+  try {
+    base = homedir();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir();
+  return join(base, ".shepherd", "inbox");
+}
+function inboxFilePath(dir, cwd) {
+  let normalized = resolve(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join(dir, `${hash}.jsonl`);
+}
+function drainInbox(filePath) {
+  const tmp = `${filePath}.draining`;
+  let raw = "";
+  try {
+    if (existsSync(tmp)) {
+      raw += readFileSync(tmp, "utf8");
+      rmSync(tmp, { force: true });
+    }
+  } catch {
+  }
+  try {
+    if (existsSync(filePath)) {
+      renameSync(filePath, tmp);
+      raw += readFileSync(tmp, "utf8");
+      rmSync(tmp, { force: true });
+    }
+  } catch {
+  }
+  if (!raw.trim()) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed?.id !== "number" || seen.has(parsed.id)) continue;
+      seen.add(parsed.id);
+      out.push(parsed);
+    } catch {
+    }
+  }
+  return out;
+}
+function formatInboxAnnouncements(announcements) {
+  if (!announcements || announcements.length === 0) return "";
+  const count = announcements.length;
+  const lines = [
+    `[Shepherd] ${count} new announcement${count === 1 ? "" : "s"} from your teammates:`
+  ];
+  for (const a of announcements) {
+    const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
+    lines.push(`  [${a.fromAgentName}${target}] ${a.body}`);
+  }
+  return lines.join("\n");
+}
+
+// src/inboxExtension.ts
+function shepherdInbox(pi) {
+  pi.on("before_agent_start", (_event, ctx) => {
+    try {
+      const dir = process.env["SHEPHERD_INBOX_DIR"] || defaultInboxDir();
+      const cwd = ctx?.cwd ?? process.cwd();
+      const announcements = drainInbox(inboxFilePath(dir, cwd));
+      const content = formatInboxAnnouncements(announcements);
+      if (!content) return void 0;
+      return { message: { customType: "shepherd-inbox", content, display: true } };
+    } catch {
+      return void 0;
+    }
+  });
+}
+export {
+  shepherdInbox as default
+};

package/dist/inboxHook.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+// src/inbox.ts
+import { createHash } from "crypto";
+import {
+  appendFileSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  existsSync
+} from "fs";
+import { homedir, tmpdir } from "os";
+import { dirname, join, resolve } from "path";
+function defaultInboxDir() {
+  let base = "";
+  try {
+    base = homedir();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir();
+  return join(base, ".shepherd", "inbox");
+}
+function inboxFilePath(dir, cwd) {
+  let normalized = resolve(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join(dir, `${hash}.jsonl`);
+}
+function drainInbox(filePath) {
+  const tmp = `${filePath}.draining`;
+  let raw = "";
+  try {
+    if (existsSync(tmp)) {
+      raw += readFileSync(tmp, "utf8");
+      rmSync(tmp, { force: true });
+    }
+  } catch {
+  }
+  try {
+    if (existsSync(filePath)) {
+      renameSync(filePath, tmp);
+      raw += readFileSync(tmp, "utf8");
+      rmSync(tmp, { force: true });
+    }
+  } catch {
+  }
+  if (!raw.trim()) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed?.id !== "number" || seen.has(parsed.id)) continue;
+      seen.add(parsed.id);
+      out.push(parsed);
+    } catch {
+    }
+  }
+  return out;
+}
+function formatInboxAnnouncements(announcements) {
+  if (!announcements || announcements.length === 0) return "";
+  const count = announcements.length;
+  const lines = [
+    `[Shepherd] ${count} new announcement${count === 1 ? "" : "s"} from your teammates:`
+  ];
+  for (const a of announcements) {
+    const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
+    lines.push(`  [${a.fromAgentName}${target}] ${a.body}`);
+  }
+  return lines.join("\n");
+}
+function buildHookOutput(rawStdin, inboxDir, drain = drainInbox) {
+  if (!inboxDir) return "";
+  let input;
+  try {
+    input = JSON.parse(rawStdin);
+  } catch {
+    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 "";
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: input.hook_event_name || "PreToolUse",
+      additionalContext: text
+    }
+  });
+}
+
+// src/inboxHook.ts
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function main() {
+  try {
+    const raw = await readStdin();
+    const inboxDir = process.argv[2] || process.env["SHEPHERD_INBOX_DIR"] || defaultInboxDir();
+    const out = buildHookOutput(raw, inboxDir);
+    if (out) process.stdout.write(out);
+  } catch {
+  }
+  process.exit(0);
+}
+void main();

package/dist/index.js

@@ -20,7 +20,14 @@ var ConfigSchema = z.object({
   PROGRAM: z.string().min(1).optional(),
   MODEL: z.string().min(1).optional(),
   // Heartbeat cadence in seconds; coerced from string env var.
-  HEARTBEAT_INTERVAL_SECONDS: z.coerce.number().int().positive().default(60)
+  HEARTBEAT_INTERVAL_SECONDS: z.coerce.number().int().positive().default(60),
+  // Opt-in: directory for the local announcement inbox. When set, the background
+  // heartbeat delivers pending announcements into a per-cwd file here, which the
+  // `shepherd-inbox-hook` (configured with the SAME dir) drains into the agent's
+  // 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()
 });
 function parseConfig(env) {
   return ConfigSchema.parse({
@@ -33,7 +40,8 @@ function parseConfig(env) {
     HUMAN: env["HUMAN"],
     PROGRAM: env["PROGRAM"],
     MODEL: env["MODEL"],
-    HEARTBEAT_INTERVAL_SECONDS: env["HEARTBEAT_INTERVAL_SECONDS"]
+    HEARTBEAT_INTERVAL_SECONDS: env["HEARTBEAT_INTERVAL_SECONDS"],
+    SHEPHERD_INBOX_DIR: env["SHEPHERD_INBOX_DIR"]
   });
 }
 function loadConfig(env = process.env) {
@@ -210,6 +218,39 @@ function generateName() {
   return randomAdj + randomNoun;
 }
 
+// ../shared/dist/repo.js
+function normalizeRemoteUrl(url) {
+  let s = url.trim();
+  if (!s)
+    return null;
+  s = s.replace(/\.git$/, "");
+  const scp = s.match(/^[^/@]+@[^:]+:(.+)$/);
+  if (scp) {
+    s = scp[1];
+  } else {
+    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
+    const slash = s.indexOf("/");
+    if (slash !== -1) {
+      s = s.slice(slash + 1);
+    }
+  }
+  s = s.replace(/^\/+|\/+$/g, "");
+  const segments = s.split("/").filter(Boolean);
+  if (segments.length < 2)
+    return null;
+  const owner = segments[segments.length - 2];
+  const repo = segments[segments.length - 1];
+  return `${owner}/${repo}`;
+}
+function canonicalizeRepo(input) {
+  const s = input.trim();
+  const looksLikeUrl = /:\/\//.test(s) || /^[^/@]+@[^:]+:/.test(s);
+  const base = looksLikeUrl ? normalizeRemoteUrl(s) ?? s : s.replace(/\.git$/, "").replace(/^\/+|\/+$/g, "");
+  const segments = base.split("/").filter(Boolean);
+  const name = segments.length > 0 ? segments[segments.length - 1] : base;
+  return name.toLowerCase();
+}
+
 // ../shared/dist/contract.js
 import { z as z2 } from "zod";
 var IsoTimestamp = z2.string();
@@ -312,6 +353,10 @@ var WorkspaceAnnouncement = z2.object({
   body: z2.string(),
   targetAgentName: z2.string().nullable(),
   repo: z2.string(),
+  // True when the message was sent by the human operator from the dashboard
+  // (no agent session). The dashboard renders these as "me" (right-aligned).
+  // Defaulted for version-skew safety with older hubs.
+  fromAdmin: z2.boolean().default(false),
   createdAt: IsoTimestamp
 });
 var WorkspaceLandscapeResponse = z2.object({
@@ -322,6 +367,22 @@ var WorkspaceLandscapeResponse = z2.object({
   // the hub rather than the (possibly skewed) browser clock.
   serverTime: IsoTimestamp
 });
+var WorkspaceAnnounceRequest = z2.object({
+  body: z2.string().min(1).max(8192),
+  // Direct-message a single agent (by the exact name shown in the landscape).
+  // Absent/null => broadcast. The hub resolves the target's repo server-side.
+  targetAgentName: z2.string().min(1).nullable().optional(),
+  // For a broadcast, the repo to scope the message to (matches the dashboard's
+  // selected repo). Absent/null => fan out to every repo in the workspace.
+  // Ignored for a DM (the target's own repo is used).
+  repo: z2.string().min(1).nullable().optional()
+});
+var WorkspaceAnnounceResponse = z2.object({
+  ok: z2.literal(true),
+  // One id per inserted row: a single id for a DM or repo-scoped broadcast, or
+  // several when an all-repos broadcast fans out across repos.
+  announcementIds: z2.array(DbId)
+});
 var JoinRequest = z2.object({
   workspace: z2.string().min(1),
   repo: z2.string().min(1),
@@ -389,10 +450,21 @@ var HeartbeatRequest = z2.object({
   // change records fresh (commits surface within ~one heartbeat interval, not
   // only when it next calls work/sync). Processed presence-style: it refreshes
   // change records but, like the rest of heartbeat, does NOT renew claim TTLs.
-  changeReport: ChangeReport.optional()
+  changeReport: ChangeReport.optional(),
+  // Opt-in: when set, the heartbeat ALSO delivers (and marks delivered) any
+  // pending announcements for the caller, returned in the response. The MCP
+  // client only sets this when it has somewhere model-visible to surface them
+  // (a local inbox file drained by a hook) — otherwise the long-standing
+  // invariant holds: heartbeat must NOT consume announcements the model can't
+  // see. Absent for older clients, so default delivery is unchanged.
+  deliverAnnouncements: z2.boolean().optional()
 });
 var HeartbeatResponse = z2.object({
-  ok: z2.literal(true)
+  ok: z2.literal(true),
+  // Pending announcements for the caller, delivered only when the request set
+  // `deliverAnnouncements`. Defaulted to [] for version-skew safety with older
+  // hubs (which return just { ok: true }).
+  announcements: z2.array(Announcement).default([])
 });
 var LeaveRequest = z2.object({
   sessionId: z2.string().uuid()
@@ -443,35 +515,6 @@ function runGitExitOk(cwd, args) {
 function isValidSha(sha) {
   return /^[0-9a-f]{4,64}$/.test(sha);
 }
-function normalizeRemoteUrl(url) {
-  let s = url.trim();
-  if (!s) return null;
-  s = s.replace(/\.git$/, "");
-  const scp = s.match(/^[^/@]+@[^:]+:(.+)$/);
-  if (scp) {
-    s = scp[1];
-  } else {
-    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
-    const slash = s.indexOf("/");
-    if (slash !== -1) {
-      s = s.slice(slash + 1);
-    }
-  }
-  s = s.replace(/^\/+|\/+$/g, "");
-  const segments = s.split("/").filter(Boolean);
-  if (segments.length < 2) return null;
-  const owner = segments[segments.length - 2];
-  const repo = segments[segments.length - 1];
-  return `${owner}/${repo}`;
-}
-function canonicalizeRepo(input) {
-  const s = input.trim();
-  const looksLikeUrl = /:\/\//.test(s) || /^[^/@]+@[^:]+:/.test(s);
-  const base = looksLikeUrl ? normalizeRemoteUrl(s) ?? s : s.replace(/\.git$/, "").replace(/^\/+|\/+$/g, "");
-  const segments = base.split("/").filter(Boolean);
-  const name = segments.length > 0 ? segments[segments.length - 1] : base;
-  return name.toLowerCase();
-}
 function detectRepo(cwd = process.cwd()) {
   const origin = runGit(cwd, ["config", "--get", "remote.origin.url"]);
   if (origin) {
@@ -674,6 +717,88 @@ async function buildChangeReport(cwd, config) {
   };
 }
 
+// src/inbox.ts
+import { createHash } from "crypto";
+import {
+  appendFileSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  existsSync
+} from "fs";
+import { homedir, tmpdir } from "os";
+import { dirname, join, resolve } from "path";
+function defaultInboxDir() {
+  let base = "";
+  try {
+    base = homedir();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir();
+  return join(base, ".shepherd", "inbox");
+}
+function inboxFilePath(dir, cwd) {
+  let normalized = resolve(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join(dir, `${hash}.jsonl`);
+}
+function appendAnnouncements(filePath, announcements) {
+  if (!announcements || announcements.length === 0) return;
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const payload = announcements.map((a) => JSON.stringify(a)).join("\n") + "\n";
+    appendFileSync(filePath, payload, "utf8");
+  } catch {
+  }
+}
+function drainInbox(filePath) {
+  const tmp = `${filePath}.draining`;
+  let raw = "";
+  try {
+    if (existsSync(tmp)) {
+      raw += readFileSync(tmp, "utf8");
+      rmSync(tmp, { force: true });
+    }
+  } catch {
+  }
+  try {
+    if (existsSync(filePath)) {
+      renameSync(filePath, tmp);
+      raw += readFileSync(tmp, "utf8");
+      rmSync(tmp, { force: true });
+    }
+  } catch {
+  }
+  if (!raw.trim()) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed?.id !== "number" || seen.has(parsed.id)) continue;
+      seen.add(parsed.id);
+      out.push(parsed);
+    } catch {
+    }
+  }
+  return out;
+}
+function mergeAnnouncements(...lists) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    if (!list) continue;
+    for (const a of list) {
+      if (!byId.has(a.id)) byId.set(a.id, a);
+    }
+  }
+  return [...byId.values()].sort((x, y) => x.id - y.id);
+}
+
 // src/tools.ts
 function formatLandscape(landscape) {
   const lines = [];
@@ -793,7 +918,7 @@ function degradedResult(err) {
   };
 }
 function registerTools(server, deps) {
-  const { hubClient, config, context, heartbeat } = deps;
+  const { hubClient, config, context, heartbeat, inboxFile } = deps;
   let sessionId = null;
   let agentName = null;
   const joinBody = {
@@ -837,6 +962,14 @@ ${body}` : body;
       return void 0;
     }
   }
+  function drainLocalInbox() {
+    if (!inboxFile) return [];
+    try {
+      return drainInbox(inboxFile);
+    } catch {
+      return [];
+    }
+  }
   function withChangeRecords(landscape, body) {
     let section = "";
     try {
@@ -864,6 +997,10 @@ ${section}` : body;
         const changeReport = await changeReportForBody();
         const body = { sessionId, ...args, ...changeReport ? { changeReport } : {} };
         const result = await hubClient.post("/work", body);
+        result.landscape.announcements = mergeAnnouncements(
+          result.landscape.announcements,
+          drainLocalInbox()
+        );
         const text = withIdentity(
           withChangeRecords(
             result.landscape,
@@ -871,7 +1008,7 @@ ${section}` : body;
 
 ` + formatLandscape(result.landscape) + `
 
-You hold this claim until you call done (workItemId: ${result.workItemId}) or it expires (~30 min). Calling work or sync renews it.`
+You hold this claim until you call done (workItemId: ${result.workItemId}) or it expires (~60 min). Calling work or sync renews it.`
           )
         );
         return { content: [{ type: "text", text }] };
@@ -899,7 +1036,9 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
         const body = { sessionId, ...args };
         const result = await hubClient.post("/done", body);
         const base = "Work item released. Call work again before your next edit in a new area.";
-        const msgs = formatAnnouncements(result.announcements ?? []);
+        const msgs = formatAnnouncements(
+          mergeAnnouncements(result.announcements, drainLocalInbox())
+        );
         return {
           content: [
             { type: "text", text: msgs ? `${base}
@@ -931,7 +1070,9 @@ ${msgs}` : base }
         const body = { sessionId, ...args };
         const result = await hubClient.post("/announce", body);
         const base = `Announcement sent (id: ${result.announcementId}).`;
-        const msgs = formatAnnouncements(result.announcements ?? []);
+        const msgs = formatAnnouncements(
+          mergeAnnouncements(result.announcements, drainLocalInbox())
+        );
         return {
           content: [
             { type: "text", text: msgs ? `${base}
@@ -963,6 +1104,10 @@ ${msgs}` : base }
         const changeReport = await changeReportForBody();
         const body = { sessionId, ...changeReport ? { changeReport } : {} };
         const result = await hubClient.post("/sync", body);
+        result.landscape.announcements = mergeAnnouncements(
+          result.landscape.announcements,
+          drainLocalInbox()
+        );
         const text = withIdentity(
           withChangeRecords(result.landscape, formatLandscape(result.landscape))
         );
@@ -1012,7 +1157,9 @@ async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
 function createHeartbeat({
   hubClient,
   intervalSeconds,
-  buildReport
+  buildReport,
+  deliverAnnouncements = false,
+  onAnnouncements
 }) {
   let timer = null;
   function stop() {
@@ -1030,8 +1177,20 @@ function createHeartbeat({
         changeReport = void 0;
       }
     }
-    const body = changeReport ? { sessionId, changeReport } : { sessionId };
-    await hubClient.post("/heartbeat", body);
+    const body = { sessionId };
+    if (changeReport) body.changeReport = changeReport;
+    if (deliverAnnouncements) body.deliverAnnouncements = true;
+    const response = await hubClient.post("/heartbeat", body);
+    const delivered = response?.announcements;
+    if (onAnnouncements && Array.isArray(delivered) && delivered.length > 0) {
+      try {
+        onAnnouncements(delivered);
+      } catch (err) {
+        console.error(
+          `[shepherd] inbox delivery failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
   }
   function start(sessionId) {
     stop();
@@ -1071,6 +1230,8 @@ async function main() {
   const config = loadConfig();
   const hubClient = createHubClient({ hubUrl: config.HUB_URL, teamToken: config.TEAM_TOKEN });
   const context = await resolveContext(config);
+  const inboxDir = config.SHEPHERD_INBOX_DIR ?? defaultInboxDir();
+  const inboxFile = inboxFilePath(inboxDir, process.cwd());
   const heartbeat = createHeartbeat({
     hubClient,
     intervalSeconds: config.HEARTBEAT_INTERVAL_SECONDS,
@@ -1082,13 +1243,15 @@ async function main() {
       } catch {
         return void 0;
       }
-    }
+    },
+    deliverAnnouncements: true,
+    onAnnouncements: (announcements) => appendAnnouncements(inboxFile, announcements)
   });
   const server = new McpServer(
     { name: "shepherd", version: "0.1.0" },
     { instructions: SHEPHERD_INSTRUCTIONS }
   );
-  const tools = registerTools(server, { hubClient, config, context, heartbeat });
+  const tools = registerTools(server, { hubClient, config, context, heartbeat, inboxFile });
   const transport = new StdioServerTransport();
   let shuttingDown = false;
   const shutdown = async () => {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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",
   "bin": {
-    "shepherd-mcp": "dist/index.js"
+    "shepherd-mcp": "dist/index.js",
+    "shepherd-inbox-hook": "dist/inboxHook.js"
   },
   "files": [
     "dist",