pi-famulus 0.1.3 → 0.1.6

package/README.md

@@ -1,6 +1,8 @@
 # pi-famulus
 
-Subagent orchestration, auto-backgrounding bash, monitoring, and agent-to-agent communication for pi.
+Subagent orchestration, auto-backgrounding bash, monitoring, and agent-to-agent communication for pi 1.0.0 or newer.
+
+Workers inherit user/global and trusted-project pi configuration and resources, including codemode and MCP, then receive famulus communication tools. An explicit agent `tools` list remains an allowlist; omitting it inherits the user’s default tools. Parent-only CLI resource overrides are not copied.
 
 After the first public release:
 
@@ -18,8 +20,9 @@ Supported native packages:
 | Linux | arm64 | `pi-famulus-linux-arm64` |
 | macOS | Intel x64 | `pi-famulus-darwin-x64` |
 | macOS | Apple Silicon arm64 | `pi-famulus-darwin-arm64` |
+| Windows | x64 | `pi-famulus-win-x64` |
 
-Linux binaries are statically linked with musl. macOS binaries target macOS 13 or newer; your Node/pi runtime's requirements also apply. Windows and other CPU architectures are not supported.
+Linux binaries are statically linked with musl. macOS binaries target macOS 13 or newer; Windows x64 binaries use MSVC with the CRT linked statically. Windows ARM64 is not published until CI produces that tarball. Your Node/pi runtime's requirements also apply. In-place manager upgrade remains Unix-only.
 
 The npm package also exposes the `pi-famulus` CLI (`npx pi-famulus --help`). The extension's binary search order is:
 
@@ -29,6 +32,8 @@ The npm package also exposes the `pi-famulus` CLI (`npx pi-famulus --help`). The
 4. Executable `~/.pi/agent/pi-famulus/bin/pi-famulus` (or the equivalent beneath `PI_FAMULUS_HOME`).
 5. Executable `pi-famulus` on `PATH`.
 
+On Windows the file name in steps 4 and 5 (and inside the native package) is `pi-famulus.exe`.
+
 Configuration and runtime state remain in `~/.pi/agent/pi-famulus`. Installing/updating the npm package does not move that state or copy a binary into the shared home. The npm CLI uses the package's native executable; use the extension configuration above when intentionally running a separately built manager.
 
 If optional dependencies were omitted, reinstall with them enabled. The CLI reports an actionable error; the extension can still discover an explicitly installed manager and otherwise enters degraded mode. An arbitrary different-version native npm package is never substituted.

package/bin/pi-famulus.js

@@ -7,7 +7,7 @@ if (!binary) {
   const name = nativePackageName(process.platform, process.arch);
   console.error(name
     ? `pi-famulus: missing usable ${name}. Reinstall pi-famulus with optional dependencies enabled (npm install --include=optional pi-famulus).`
-    : `pi-famulus: unsupported ${process.platform}/${process.arch}; only Linux/macOS x64/arm64 are supported.`);
+    : `pi-famulus: unsupported ${process.platform}/${process.arch}; only Linux/macOS/Windows x64/arm64 are supported.`);
   process.exit(1);
 }
 const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,8 @@
   },
   "os": [
     "linux",
-    "darwin"
+    "darwin",
+    "win32"
   ],
   "cpu": [
     "x64",
@@ -30,10 +31,11 @@
     "pi-famulus": "./bin/pi-famulus.js"
   },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.1.3",
-    "pi-famulus-linux-arm64": "0.1.3",
-    "pi-famulus-darwin-x64": "0.1.3",
-    "pi-famulus-darwin-arm64": "0.1.3"
+    "pi-famulus-linux-x64": "0.1.6",
+    "pi-famulus-linux-arm64": "0.1.6",
+    "pi-famulus-darwin-x64": "0.1.6",
+    "pi-famulus-darwin-arm64": "0.1.6",
+    "pi-famulus-win-x64": "0.1.6"
   },
   "pi": {
     "extensions": [
@@ -41,6 +43,8 @@
     ]
   },
   "scripts": {
+    "deps": "nub install --frozen-lockfile --node-linker hoisted",
+    "prompts": "node scripts/build-prompts.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
@@ -53,7 +57,7 @@
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
     "typebox": "*",
     "@earendil-works/pi-tui": "*"
   },

package/src/agents/builtins.ts

@@ -4,38 +4,21 @@
  * These form the lowest precedence layer: user and project definitions with
  * the same name replace them wholesale.
  */
+import { PROMPTS } from "../prompts.generated";
 import type { AgentDefinition } from "./definition";
 
 export const BUILTIN_AGENTS: AgentDefinition[] = [
   {
     name: "explorer",
-    description:
-      "Fast read-only codebase exploration — finds files, symbols, and answers structure questions",
+    description: PROMPTS["agents.explorer.description"],
     tools: ["read", "grep", "find", "ls", "bash"],
-    systemPrompt: [
-      "You are an explorer agent. Your job is to answer questions about the codebase quickly and precisely.",
-      "",
-      "Rules:",
-      "- Return findings, never change code. You are strictly read-only: do not edit, write, or create files.",
-      "- Report concrete locations: cite specific file paths with line numbers (path:line) for every claim.",
-      "- Control your search scope: start narrow (targeted grep/find), widen only when needed, and stop once the question is answered.",
-      "- Prefer a short, factual summary over exhaustive dumps. List what you found and where.",
-    ].join("\n"),
+    systemPrompt: PROMPTS["agents.explorer.system-prompt"],
     source: "builtin",
   },
   {
     name: "worker",
-    description: "General-purpose executor — completes concrete coding tasks end to end",
-    tools: ["read", "bash", "edit", "write"],
-    systemPrompt: [
-      "You are a worker agent. Your job is to complete the concrete task you were given, end to end.",
-      "",
-      "Rules:",
-      "- Do the task, don't just describe it. Make the actual edits and run the actual commands.",
-      "- Self-verify before finishing: run the relevant tests, typecheck, or command that proves the task is done.",
-      "- Stay within the task's scope; do not refactor unrelated code.",
-      "- Report concisely: what you changed, how you verified it, and anything the supervisor should know.",
-    ].join("\n"),
+    description: PROMPTS["agents.worker.description"],
+    systemPrompt: PROMPTS["agents.worker.system-prompt"],
     source: "builtin",
   },
 ];

package/src/agents/definition.ts

@@ -26,8 +26,8 @@ export interface AgentDefinition {
   name: string;
   /** Required, non-empty. */
   description: string;
-  /** Tool allowlist. Defaults to ["read","bash","edit","write"]. */
-  tools: string[];
+  /** Omitted: inherit user-configured tools. Explicit list: allowlist; []: disables user-configured tools, but injected Famulus tools remain. */
+  tools?: string[];
   /** "provider:id" or bare id. */
   model?: string;
   /** Thinking level (pi core parity; src/thinking-levels.ts). */
@@ -39,8 +39,6 @@ export interface AgentDefinition {
   path?: string;
 }
 
-export const DEFAULT_AGENT_TOOLS: readonly string[] = ["read", "bash", "edit", "write"];
-
 const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
 
 type Fail = (reason: string) => never;
@@ -168,7 +166,7 @@ export function parseAgentMarkdown(
   const description = parseScalar(fields.description, "description", fail);
   if (description === "") fail("field 'description' must be non-empty");
 
-  let tools = [...DEFAULT_AGENT_TOOLS];
+  let tools: string[] | undefined;
   if (fields.tools !== undefined) {
     tools = parseStringArray(fields.tools, "tools", fail);
   }
@@ -195,7 +193,7 @@ export function parseAgentMarkdown(
   return {
     name,
     description,
-    tools,
+    ...(tools !== undefined ? { tools } : {}),
     ...(model !== undefined ? { model } : {}),
     ...(thinking !== undefined ? { thinking } : {}),
     systemPrompt: body.trim(),

package/src/bash-override.ts

@@ -18,11 +18,12 @@ import { writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Type, type Static } from "typebox";
-import type {
-  AgentToolResult,
-  BashToolDetails,
-  ExtensionContext,
-  ToolDefinition,
+import {
+  getShellConfig,
+  type AgentToolResult,
+  type BashToolDetails,
+  type ExtensionContext,
+  type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { taskOutputPath, type FamulusConfig } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
@@ -30,6 +31,7 @@ import { backgroundRowText, formatBackgroundNotice, truncateTail } from "./forma
 import { toolComponent } from "./tui/tool-component";
 import type { WorkIndex } from "./work-index";
 import type { ManagerClient } from "./manager-client";
+import { fill, PROMPTS } from "./prompts.generated";
 import {
   appendStatus,
   bareSleepError,
@@ -48,15 +50,12 @@ const MAX_LINES = SHELL_MAX_LINES;
 const MAX_BYTES = SHELL_MAX_BYTES;
 
 const bashParameters = Type.Object({
-  command: Type.String({ description: "The bash command to execute" }),
+  command: Type.String({ description: PROMPTS["tools.bash.param.command"] }),
   timeout: Type.Optional(
-    Type.Number({ description: "Hard kill timeout in seconds (optional, no default timeout)" }),
+    Type.Number({ description: PROMPTS["tools.bash.param.timeout"] }),
   ),
   run_in_background: Type.Optional(
-    Type.Boolean({
-      description:
-        "Start the command in the background and return immediately. You will be notified when it completes.",
-    }),
+    Type.Boolean({ description: PROMPTS["tools.bash.param.run_in_background"] }),
   ),
 });
 
@@ -135,11 +134,8 @@ function isActiveStatus(status: string | undefined): boolean {
   return status === undefined || status === "running" || status === "pending";
 }
 
-const BARE_SLEEP_GUIDANCE =
-  "Do not sleep to wait for background work; completion is delivered via notification. Use the monitor tool to watch for a condition, or run_in_background for long commands.";
-
 function rejectBareSleep(command: string): string | null {
-  return bareSleepError(command, BARE_SLEEP_GUIDANCE);
+  return bareSleepError(command, "tools.bash.error.bare-sleep");
 }
 
 function resolveTimeoutMs(timeoutSeconds: number | undefined): number | null {
@@ -171,15 +167,29 @@ async function executeLocal(
 ): Promise<AgentToolResult<FamulusBashDetails | undefined>> {
   const timeoutMs = resolveTimeoutMs(params.timeout);
   const startedAtMs = clock.now();
-  const shell = process.env.SHELL && process.env.SHELL.length > 0 ? process.env.SHELL : "/bin/bash";
+  // pi's own choice (Git Bash on Windows, /bin/bash on Unix): commands are
+  // written for pi's bash tool, not for whatever $SHELL is.
+  let shell: ReturnType<typeof getShellConfig>;
+  try {
+    shell = getShellConfig();
+  } catch (err) {
+    throw new Error(`Failed to start shell: ${(err as Error).message}`);
+  }
+  const viaStdin = shell.commandTransport === "stdin";
 
   const output = await new Promise<{ text: string; exitCode: number | null; signal: string | null; timedOut: boolean; aborted: boolean }>(
     (resolve, reject) => {
-      const child = spawn(shell, ["-c", params.command], {
+      const child = spawn(shell.shell, viaStdin ? shell.args : [...shell.args, params.command], {
         cwd: ctx.cwd,
         env: process.env,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: [viaStdin ? "pipe" : "ignore", "pipe", "pipe"],
+        windowsHide: true,
       });
+      if (viaStdin) {
+        // Swallow EPIPE if the shell exits before consuming stdin (pi's runner does the same).
+        child.stdin?.on("error", () => {});
+        child.stdin?.end(params.command);
+      }
       const chunks: Buffer[] = [];
       let settled = false;
       let timedOut = false;
@@ -289,17 +299,9 @@ export function createBashOverride(
   return {
     name: "bash",
     label: "Bash",
-    description:
-      "Execute a bash command in the current working directory. Returns stdout and stderr. " +
-      `Output is truncated to last ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB (whichever is hit first). ` +
-      "Foreground commands that exceed the foreground budget are automatically moved to the background; " +
-      "you will be notified when they complete. Optionally provide a timeout in seconds (hard kill limit), " +
-      "or run_in_background to background immediately.",
-    promptSnippet: "Execute bash commands (ls, grep, find, etc.)",
-    promptGuidelines: [
-      "You can inspect PI_* environment variables for current model and session details.",
-      "Long-running bash commands are moved to the background automatically; do not poll or sleep to wait for them. End your turn (a reply with no tool call) and resume from the task wake when it arrives.",
-    ],
+    description: fill("tools.bash.description", { maxLines: MAX_LINES, maxKb: MAX_BYTES / 1024 }),
+    promptSnippet: PROMPTS["tools.bash.snippet"],
+    promptGuidelines: [...PROMPTS["tools.bash.rules"]],
     parameters: bashParameters,
     outputSchema: bashOutputSchema,
     renderResult(result, { expanded }, theme, context) {

package/src/behavior-guidelines.ts

@@ -4,26 +4,22 @@
  * Returning `systemPrompt` from before_agent_start forces the whole prompt for
  * that user-prompt run only (and clobbers other extensions). Wake turns started
  * by sendMessage({ triggerTurn: true }) do not call before_agent_start again.
- * A named section is diffed into the transcript and stays visible on those turns.
+ * A named section is recorded on user turns. Pi can rebuild the base prompt
+ * after a wake's tool result and remove that run-local section, so the request
+ * projection restores only our section whenever it is missing or stale.
  */
-export const BEHAVIOR_GUIDELINES_SECTION = "pi-famulus";
+import type { ContextWithSystemEvent, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+// .ts suffix: eval/ loads this module with Node's own TypeScript support.
+import { fill, PROMPTS } from "./prompts.generated.ts";
 
-/** Child-only instructions injected through the contact_supervisor tool guideline. */
-export const CHILD_BEHAVIOR_GUIDELINES = `## Child agent behavior (pi-famulus)
+export const BEHAVIOR_GUIDELINES_SECTION = "pi-famulus";
 
-- Do not background work; bash runs to completion.
-- When blocked, use contact_supervisor with need_decision; use progress_update for status.
-- Use agent_message only to communicate with siblings in this same run.
-- Your final message is your result.`;
+export const MONITOR_IDLE_INSTRUCTION = PROMPTS["guidelines.monitor-idle"];
 
-export const BEHAVIOR_GUIDELINES = `## Background tasks and notifications (pi-famulus)
+/** Child-only instructions injected through the contact_supervisor tool guideline. */
+export const CHILD_BEHAVIOR_GUIDELINES = PROMPTS["guidelines.child"];
 
-- Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind="task"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands.
-- When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. Do not wait for further user input when the next step is clear; do not merely acknowledge and stop.
-- Never fabricate or assume a background task's result before its notification arrives.
-- Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind="subagent-handover"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:"resume", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind="subagent-done"> arrives — read each <child>, synthesize, and continue.
-- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind="subagent-overrun"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. Pick one: subagent({action:"extend", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:"interrupt", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.
-- Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind="supervisor-request"> (action:"reply"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:"resume"}). Supervisor wakes are not user messages — still act on them.`;
+export const BEHAVIOR_GUIDELINES = fill("guidelines.parent", { monitorIdle: MONITOR_IDLE_INSTRUCTION });
 
 export interface GuidelinePromptOptions {
   sections?: Record<string, string>;
@@ -35,7 +31,35 @@ export function applyBehaviorGuidelines(options: GuidelinePromptOptions): void {
   options.sections[BEHAVIOR_GUIDELINES_SECTION] = BEHAVIOR_GUIDELINES;
 }
 
-/** What a later wake turn sees: persisted sections, no before_agent_start. */
+/** Register parent behavior without relying on command-only context methods. */
+export function registerBehaviorGuidelines(pi: Pick<ExtensionAPI, "on">): void {
+  pi.on("before_agent_start", (event) => {
+    applyBehaviorGuidelines(event.systemPromptOptions);
+  });
+  pi.on("context_with_system", (event) => restoreBehaviorGuidelines(event.messages));
+}
+
+/** Repair the model request, not the persisted transcript or other sections. */
+export function restoreBehaviorGuidelines(messages: ContextWithSystemEvent["messages"]) {
+  const expected = `<${BEHAVIOR_GUIDELINES_SECTION}>\n${BEHAVIOR_GUIDELINES}\n</${BEHAVIOR_GUIDELINES_SECTION}>`;
+  let current: string | null | undefined;
+  for (const message of messages) {
+    if (message.role === "system" && message.sections && BEHAVIOR_GUIDELINES_SECTION in message.sections) {
+      current = message.sections[BEHAVIOR_GUIDELINES_SECTION];
+    }
+  }
+  if (current === expected) return undefined;
+  return {
+    messages: [...messages, {
+      role: "system" as const,
+      content: "",
+      sections: { [BEHAVIOR_GUIDELINES_SECTION]: expected },
+      timestamp: Date.now(),
+    }],
+  };
+}
+
+/** Render named sections without replacing unrelated instructions. */
 export function wakePromptFromSections(sections: Record<string, string>): string {
   return Object.entries(sections)
     .map(([name, content]) => `<${name}>\n${content}\n</${name}>`)

package/src/comms/comms.ts

@@ -10,6 +10,7 @@ import {
   type MailboxOptions,
 } from "./mailbox";
 import type { Comms, CommsHost } from "./types";
+import { fill } from "../prompts.generated";
 import { formatFamulusWake, type FormattedWake } from "../wake";
 import type { Clock } from "../clock";
 
@@ -149,9 +150,12 @@ export function createComms(host: CommsHost, options: CommsOptions = {}): CommsW
         // Lifecycle (resume) belongs to the subagent tool. Resuming here never
         // wired a completion wake, so the parent hung.
         throw new Error(
-          `Child ${toChildId} (${child.name}) has finished (${child.status}). ` +
-            `agent_message does not resume children. ` +
-            `Use subagent({ action: "resume", run_id: "${child.runId}", child_id: "${toChildId}", message: "..." }).`,
+          fill("tools.agent_message.error.finished-child", {
+            childId: toChildId,
+            name: child.name,
+            status: child.status,
+            runId: child.runId,
+          }),
         );
       } else {
         throw new Error(

package/src/comms/tools.ts

@@ -13,6 +13,7 @@ import { realClock, type Clock } from "../clock";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { CommsWithOrigin } from "./comms";
 import { assertSiblingAllowed } from "./routing";
+import { PROMPTS } from "../prompts.generated";
 import type { ChildStatus, Comms, CommsHost, MailboxEntry } from "./types";
 
 export type AgentMessageSender =
@@ -25,11 +26,9 @@ export type AgentMessageSender =
 
 const contactSupervisorParameters = Type.Object({
   reason: Type.Union([Type.Literal("need_decision"), Type.Literal("progress_update")], {
-    description:
-      '"need_decision" blocks until the supervisor (parent agent) replies; ' +
-      '"progress_update" is fire-and-forget.',
+    description: PROMPTS["tools.child.contact_supervisor.param.reason"],
   }),
-  message: Type.String({ description: "Message for the supervisor." }),
+  message: Type.String({ description: PROMPTS["tools.child.contact_supervisor.param.message"] }),
 });
 
 export interface ContactSupervisorDetails {
@@ -45,13 +44,8 @@ export function createContactSupervisorTool(
   return {
     name: "contact_supervisor",
     label: "Contact Supervisor",
-    description:
-      "Contact the supervisor (parent agent). " +
-      'Use reason "need_decision" when you are blocked and need the parent to decide — ' +
-      "the call blocks until the parent replies (10 minute timeout, after which you must " +
-      "decide yourself). " +
-      'Use reason "progress_update" for a fire-and-forget status note.',
-    promptSnippet: "Ask the parent agent for a decision or report progress",
+    description: PROMPTS["tools.child.contact_supervisor.description"],
+    promptSnippet: PROMPTS["tools.child.contact_supervisor.snippet"],
     parameters: contactSupervisorParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       try {
@@ -79,24 +73,18 @@ const agentMessageParameters = Type.Object({
   action: Type.Union(
     [Type.Literal("send"), Type.Literal("reply"), Type.Literal("broadcast"), Type.Literal("list")],
     {
-      description:
-        '"send" a message to a child, "reply" to a pending decision request, ' +
-        '"broadcast" to all running children of a run, "list" pending requests and recent traffic.',
+      description: PROMPTS["tools.agent_message.param.action"],
     },
   ),
   to: Type.Optional(
     Type.String({
-      description:
-        'Target child_id or name ("send"/"reply"). For "broadcast" from the parent session: run_id. ' +
-        "Child sessions broadcast to their own run and must omit this.",
+      description: PROMPTS["tools.agent_message.param.to"],
     }),
   ),
-  message: Type.Optional(Type.String({ description: "Message text." })),
+  message: Type.Optional(Type.String({ description: PROMPTS["tools.agent_message.param.message"] })),
   delivery: Type.Optional(
     Type.Union([Type.Literal("steer"), Type.Literal("queue")], {
-      description:
-        '"steer" (default) injects into a running child immediately; "queue" delivers after ' +
-        'its current turn. Sending to a finished child is an error — resume with subagent({action:"resume"}).',
+      description: PROMPTS["tools.agent_message.param.delivery"],
     }),
   ),
 });
@@ -209,21 +197,8 @@ export function createAgentMessageTool(
   return {
     name: "agent_message",
     label: "Agent Message",
-    description: isChild
-      ? "Message sibling subagents in your run, or list pending requests. " +
-        '"send" delivers to a running sibling. Sending to a finished sibling errors and does not resume it; ' +
-        'resume with subagent({ action: "resume", run_id, child_id, message }). ' +
-        '"broadcast" steers every running sibling in your run; "list" shows pending ' +
-        "decision requests and recent traffic. Cross-run messaging is rejected."
-      : "Message your subagents. " +
-        '"send" steers or queues a running child. Sending to a finished child errors ' +
-        '(it does not resume) and points at subagent({ action: "resume", run_id, child_id, message }). ' +
-        '"reply" answers a child\'s pending decision request; "broadcast" steers every ' +
-        'running child of a run (to = run_id); "list" shows children, pending decision ' +
-        "requests, and recent traffic.",
-    promptSnippet: isChild
-      ? "Message sibling subagents in your run"
-      : "Send/reply/broadcast messages to subagents",
+    description: isChild ? PROMPTS["tools.child.agent_message.description"] : PROMPTS["tools.agent_message.description"],
+    promptSnippet: isChild ? PROMPTS["tools.child.agent_message.snippet"] : PROMPTS["tools.agent_message.snippet"],
     parameters: agentMessageParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const action = params.action;

package/src/config.ts

@@ -6,7 +6,7 @@
  */
 import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { delimiter, join } from "node:path";
+import { delimiter, join, win32 } from "node:path";
 import { nativePackageName, resolveNativeManagerPath } from "./native-manager.js";
 
 export interface FamulusConfig {
@@ -141,11 +141,43 @@ export function getFamulusHome(env: NodeJS.ProcessEnv = process.env): string {
   return join(homedir(), ".pi", "agent", "pi-famulus");
 }
 
+/** FNV-1a 64-bit over UTF-8 bytes — must match manager `sys::fnv1a64`. */
+export function fnv1a64(input: string): string {
+  let h = 0xcbf29ce484222325n;
+  for (const byte of Buffer.from(input, "utf8")) {
+    h ^= BigInt(byte);
+    h = (h * 0x0100000001b3n) & 0xffffffffffffffffn;
+  }
+  return h.toString(16);
+}
+
+/**
+ * Named-pipe identity of a home — must match manager `lifecycle::windows_pipe_ident`.
+ * The home is made absolute lexically (`path.win32.resolve` against `cwd`):
+ * `.` / `..` and repeated separators collapse, symlinks and junctions are
+ * not expanded. One spelling per directory (backslashes, no trailing
+ * separator except a drive root, lower case). The same relative home from
+ * two working directories must not share a pipe.
+ */
+export function windowsHomeKey(home: string, cwd: string = process.cwd()): string {
+  let s = win32.resolve(cwd, home);
+  while (s.length > 3 && s.endsWith("\\")) s = s.slice(0, -1);
+  return s.toLowerCase();
+}
+
+export function windowsPipeName(home: string, cwd: string = process.cwd()): string {
+  return `\\\\.\\pipe\\pi-famulus-${fnv1a64(windowsHomeKey(home, cwd))}`;
+}
+
 /** Well-known paths inside the pi-famulus home directory (design doc §3.1). */
-export function famulusPaths(home: string) {
+export function famulusPaths(home: string, platform: NodeJS.Platform = process.platform) {
+  const socket =
+    platform === "win32"
+      ? windowsPipeName(home)
+      : join(home, "manager.sock");
   return {
     home,
-    socket: join(home, "manager.sock"),
+    socket,
     pidFile: join(home, "manager.pid"),
     spawnLock: join(home, "manager.spawn.lock"),
     log: join(home, "manager.log"),
@@ -225,6 +257,9 @@ export function loadConfig(home: string = getFamulusHome()): FamulusConfig {
   return config;
 }
 
+/** File name of the manager in <home>/bin and on PATH: Windows only starts `.exe` images. */
+export const MANAGER_FILE_NAME = process.platform === "win32" ? "pi-famulus.exe" : "pi-famulus";
+
 /** Return why a candidate is unusable, or null for an executable regular file. */
 function managerCandidateProblem(path: string): string | null {
   try {
@@ -260,14 +295,15 @@ export function describeManagerSearch(
   tried.push(nativeName
     ? `npm ${nativeName}${native ? ` ${native}` : " (missing or unusable, ignored)"}`
     : `npm native manager (unsupported ${process.platform}/${process.arch})`);
-  tried.push(describeCandidate(join(home, "bin", "pi-famulus")));
+  tried.push(describeCandidate(join(home, "bin", MANAGER_FILE_NAME)));
   tried.push("pi-famulus on PATH");
   return tried.join("; ");
 }
 
 /**
  * Resolve an executable regular pi-famulus binary, or null if none is usable.
- * Priority: config.managerPath > PI_FAMULUS_MANAGER_PATH env > npm native package > <home>/bin/pi-famulus > PATH.
+ * Priority: config.managerPath > PI_FAMULUS_MANAGER_PATH env > npm native package > <home>/bin/pi-famulus > PATH
+ * (`pi-famulus.exe` on Windows).
  */
 export function resolveManagerPath(
   config: FamulusConfig,
@@ -279,11 +315,11 @@ export function resolveManagerPath(
   if (envPath && managerCandidateProblem(envPath) === null) return envPath;
   const native = resolveNativeManagerPath();
   if (native) return native;
-  const bundled = join(home, "bin", "pi-famulus");
+  const bundled = join(home, "bin", MANAGER_FILE_NAME);
   if (managerCandidateProblem(bundled) === null) return bundled;
   for (const dir of (env.PATH ?? "").split(delimiter)) {
     if (!dir) continue;
-    const candidate = join(dir, "pi-famulus");
+    const candidate = join(dir, MANAGER_FILE_NAME);
     if (managerCandidateProblem(candidate) === null) return candidate;
   }
   return null;