@resolveworks/fork 0.1.1 → 0.2.0

package/README.md

@@ -33,11 +33,13 @@ Then restart pi, or `/reload`.
 
 The parent session gains three tools:
 
-- `spawn_agent({ task, branch? })` — writes the task to a file and opens a new tmux window running `pi @<taskfile>`. Returns immediately. The child sees the task plus normal project context, not the parent's conversation, so the task must be self-contained.
+- `spawn_agent({ task, branch?, model? })` — writes the task to a file and opens a new tmux window running `pi @<taskfile>`. Returns immediately. The child sees the task plus normal project context, not the parent's conversation, so the task must be self-contained.
 - `message_agent({ id, text })` — steers a revision request into the child's current run, or starts a new turn when the child is idle.
 - `close_agent({ id })` — mechanical shutdown; no model turn spent.
 
-The child gains `report_result({ result })`. The report travels over a Unix socket and arrives in the parent as a steering notification: immediately if the parent is idle, or injected into the parent's current run after its pending tool calls. The child stays alive after reporting, awaiting the verdict: revisions via `message_agent`, or closure. Reports are outcomes, not progress updates. If delivery fails, the child is told unambiguously and retries with the same payload — a retry cannot double-deliver. Interrupting the parent would drop its queued notifications, so fork re-delivers them once the interrupted run settles — an escape can no longer lose a report.
+The child gains `message_parent({ message })`. The message travels over a Unix socket and arrives in the parent as a steering notification: immediately if the parent is idle, or injected into the parent's current run after its pending tool calls. The child stays alive after replying, awaiting the verdict: revisions via `message_agent`, or closure. Messages are outcomes, not progress updates. If delivery fails, the child is told unambiguously and retries with the same payload — a retry cannot double-deliver. Interrupting the parent would drop its queued notifications, so fork re-delivers them once the interrupted run settles — an escape can no longer lose a message.
+
+Input is tagged by sender: the task and every `message_agent` message reach the child wrapped in `<message-from-parent>`, while anything typed into the child's tmux window arrives unwrapped. The child's prompt uses that distinction to know who it is answering.
 
 Don't poll. Navigate windows with your usual tmux keys.
 
@@ -51,12 +53,29 @@ Fork deliberately does no environment setup and runs no checks. `git worktree ad
 
 ## Config
 
-`~/.pi/agent/fork.json`, overridden per-project by `.pi/fork.json` (read only in trusted projects). All fields optional; passed through to the child as CLI flags:
+`~/.pi/agent/fork.json`, overridden per-project by `.pi/fork.json` (read only in trusted projects). A `default` profile plus named `options`, passed through to the child as CLI flags:
 
 ```json
-{ "model": "glm-5.2", "provider": "zai", "thinking": "high" }
+{
+  "default": { "model": "glm-5.2", "thinking": "high" },
+  "options": [
+    {
+      "tag": "small",
+      "description": "Fast and inexpensive; use for routine tasks.",
+      "model": "glm-4.7-air"
+    },
+    {
+      "tag": "big",
+      "description": "Stronger reasoning; use for complex design and difficult debugging.",
+      "model": "claude-opus-4-5",
+      "provider": "anthropic"
+    }
+  ]
+}
 ```
 
+Each option requires a `description`, shown to the parent model alongside its tag so it can select an appropriate profile. `spawn_agent` takes an optional `model` argument naming an option's tag; without it, the `default` profile applies, or pi's normal startup rules if there is none. The project file replaces global fields wholesale.
+
 ## Runtime state
 
 Under `~/.pi/agent/extensions/fork/` (sockets and task files are mode `0o600`):

package/index.ts

@@ -3,22 +3,25 @@
  *
  * The parent registers `spawn_agent`, `message_agent`, and `close_agent`
  * tools. Calling spawn_agent opens a new tmux window running pi with the
- * given task and returns immediately. The child reports results through `report_result`;
- * each report is delivered over a Unix socket as a notification that reaches
- * the parent promptly: if the parent is idle the report starts a turn at
- * once; if it is mid-run the report is steered into that run — delivered
- * after its current tool calls, before the next LLM call. An interrupt
- * clears the steering queue without delivering queued custom messages, so
- * reports are tracked until delivery is confirmed and re-delivered when an
- * interrupted run settles. The child stays alive after
- * reporting: the parent reviews the report, sends revision requests with
+ * given task and returns immediately. The child replies to the parent through
+ * `message_parent`; each message is delivered over a Unix socket as a
+ * notification that reaches the parent promptly: if the parent is idle the
+ * message starts a turn at once; if it is mid-run the message is steered into
+ * that run — delivered after its current tool calls, before the next LLM call.
+ * An interrupt clears the steering queue without delivering queued custom
+ * messages, so messages are tracked until delivery is confirmed and
+ * re-delivered when an interrupted run settles. The child stays alive after
+ * replying: the parent reviews the message, sends revision requests with
  * message_agent, and closes the child with close_agent.
  *
- * Configure the subagent model via ~/.pi/agent/fork.json (global) or
- * .pi/fork.json (project, overrides global). Any field is optional:
- *   { "model": "glm-5.2", "provider": "zai", "thinking": "high" }
- * Fork passes these settings to the child pi process as CLI flags, so pi
- * resolves them using its normal startup rules.
+ * Configure subagent models via ~/.pi/agent/fork.json (global) or
+ * .pi/fork.json (project, overrides global): a default profile plus named
+ * options selected by tag:
+ *   { "default": { "model": "glm-5.2" },
+ *     "options": [{ "tag": "small", "description": "Fast routine tasks",
+ *       "model": "glm-4.7-air" }] }
+ * Fork passes the selected profile to the child pi process as CLI flags, so
+ * pi resolves them using its normal startup rules.
  *
  * Requires: run pi inside tmux.
  */
@@ -32,6 +35,7 @@ import * as path from "node:path";
 import {
   CONFIG_DIR_NAME,
   type ExtensionAPI,
+  type ExtensionContext,
   getAgentDir,
   getMarkdownTheme,
   keyHint,
@@ -155,7 +159,8 @@ type AgentMessage = { type: "message"; text: string };
 
 // ── config (~/.pi/agent/fork.json, .pi/fork.json) ───────────────────
 
-interface ForkConfig {
+/** Model settings passed to the child as CLI flags. */
+interface ModelProfile {
   /** Model id or pattern (supports `provider/id` and `:thinking`). */
   model?: string;
   provider?: string;
@@ -163,14 +168,22 @@ interface ForkConfig {
   thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 }
 
+/** A named profile, selectable via spawn_agent's model argument. */
+interface ModelOption extends ModelProfile {
+  tag: string;
+  /** Shown to the parent model to help it select a profile. */
+  description: string;
+}
+
+interface ForkConfig {
+  /** Profile for spawns without a model argument. */
+  default?: ModelProfile;
+  options?: ModelOption[];
+}
+
 function readConfig(file: string): ForkConfig {
-  try {
-    if (!fs.existsSync(file)) return {};
-    return JSON.parse(fs.readFileSync(file, "utf-8")) as ForkConfig;
-  } catch (err) {
-    console.error(`fork: failed to load ${file}: ${err}`);
-    return {};
-  }
+  if (!fs.existsSync(file)) return {};
+  return JSON.parse(fs.readFileSync(file, "utf-8")) as ForkConfig;
 }
 
 /** Merge global + project config. Project wins; only read if trusted. */
@@ -180,6 +193,14 @@ function loadConfig(cwd: string, projectTrusted: boolean): ForkConfig {
   return { ...globalCfg, ...projectCfg };
 }
 
+/** The profile for a named tag, or `default` when no tag is given. */
+function resolveProfile(config: ForkConfig, tag: string | undefined): ModelProfile {
+  if (tag === undefined) return config.default ?? {};
+  const option = config.options?.find((option) => option.tag === tag);
+  if (option === undefined) throw new Error(`fork: unknown model tag "${tag}"`);
+  return option;
+}
+
 // ── git worktrees ───────────────────────────────────────────────────
 
 interface WorktreeInfo {
@@ -266,15 +287,15 @@ function spawn(
   id: string,
   taskPath: string,
   cwd: string,
-  config: ForkConfig,
+  profile: ModelProfile,
   branch?: string,
 ): void {
   // argv passed directly; tmux runs a multi-arg command without `sh -c`, so
   // no shell quoting is needed. Let pi resolve model settings itself.
   const cmdArgs = ["pi", "--subagent-socket", socketPathFor(sessionId), "--subagent-id", id];
-  if (config.provider) cmdArgs.push("--provider", config.provider);
-  if (config.model) cmdArgs.push("--model", config.model);
-  if (config.thinking) cmdArgs.push("--thinking", config.thinking);
+  if (profile.provider) cmdArgs.push("--provider", profile.provider);
+  if (profile.model) cmdArgs.push("--model", profile.model);
+  if (profile.thinking) cmdArgs.push("--thinking", profile.thinking);
   if (branch) cmdArgs.push("--subagent-branch", branch);
   cmdArgs.push(`@${taskPath}`);
 
@@ -452,10 +473,10 @@ function assertOpenAgent(id: string): void {
   }
 }
 
-function setupParent(
-  pi: ExtensionAPI,
-  ctx: { sessionManager: { getSessionId: () => string } },
-): void {
+function setupParent(pi: ExtensionAPI, ctx: ExtensionContext): void {
+  const config = loadConfig(ctx.cwd, ctx.isProjectTrusted());
+  const modelOptions = config.options ?? [];
+
   fs.mkdirSync(SOCKETS_DIR, { recursive: true });
   fs.mkdirSync(TASKS_DIR, { recursive: true });
 
@@ -501,18 +522,17 @@ function setupParent(
     name: "spawn_agent",
     label: "Spawn Agent",
     description:
-      "Delegate a self-contained task to a subagent: a fresh pi session in a " +
-      "new tmux window. By default it shares your working tree; provide branch " +
-      "to create an isolated Git worktree on a new agent/<name> branch. Use " +
-      "for independent work that benefits from isolated context; do simple, " +
-      "sequential, or context-dependent work yourself. The subagent sees the " +
-      "task plus normal project context (AGENTS.md, files), but not this " +
-      "conversation, so include needed context in the task. Avoid concurrent " +
-      "editing agents in shared mode. Returns immediately with a spawn " +
-      "confirmation. The report arrives later as a message in this " +
-      "session — steered into current work or a new turn when idle; do not " +
-      "poll or sleep. Continue other work or end your turn. Then " +
-      "request revisions with message_agent or close it with close_agent.",
+      "Delegate a self-contained task to a subagent in a fresh pi session and " +
+      "tmux window. Use this for independent work that benefits from isolated " +
+      "context; handle simple, sequential, or context-dependent work yourself. " +
+      "By default, the subagent shares your working tree; do not run concurrent " +
+      "editing agents in shared mode. Set branch to use an isolated Git worktree. " +
+      "The subagent sees the task and normal project context, but not this " +
+      "conversation, so include all necessary context in the task. This tool " +
+      "returns immediately. The subagent's report steers your current run, or " +
+      "starts a new turn if you are idle. Do not poll or sleep; continue other " +
+      "work or end your turn. After the report arrives, review its work, then " +
+      "use message_agent for revisions or close_agent when finished.",
     parameters: Type.Object({
       task: Type.String({
         description:
@@ -532,16 +552,42 @@ function setupParent(
             "already exist. Omit to share the current working tree.",
         }),
       ),
+      ...(modelOptions.length > 0
+        ? {
+            model: Type.Optional(
+              Type.Enum(
+                modelOptions.map((option) => option.tag),
+                {
+                  description:
+                    "Model profile for the subagent:\n" +
+                    modelOptions
+                      .map((option) => `- ${option.tag}: ${option.description}`)
+                      .join("\n") +
+                    "\nOmit to use the default profile, or pi's normal startup rules " +
+                    "if no default is configured.",
+                },
+              ),
+            ),
+          }
+        : {}),
     }),
     execute: async (_id, params, signal, _onUpdate, toolCtx) => {
-      const { task, branch } = params as { task: string; branch?: string };
+      const { task, branch, model } = params as {
+        task: string;
+        branch?: string;
+        model?: string;
+      };
       const id = randomUUID();
       const taskPath = taskPathFor(id);
-      fs.writeFileSync(taskPath, task, { mode: 0o600 });
+      // Tag the task like every other parent message, so the child learns one
+      // rule: tagged input is the parent, untagged input is a human at its window.
+      fs.writeFileSync(taskPath, `<message-from-parent>\n${task}\n</message-from-parent>`, {
+        mode: 0o600,
+      });
 
       let worktree: WorktreeInfo | undefined;
       try {
-        const config = loadConfig(toolCtx.cwd, toolCtx.isProjectTrusted());
+        const profile = resolveProfile(config, model);
         if (branch !== undefined) {
           worktree = await createWorktree(pi, toolCtx.cwd, id, branch, signal);
         }
@@ -551,7 +597,7 @@ function setupParent(
           id,
           taskPath,
           worktree?.path ?? toolCtx.cwd,
-          config,
+          profile,
           worktree?.branch,
         );
       } catch (err) {
@@ -583,10 +629,10 @@ function setupParent(
     label: "Message Agent",
     description:
       "Send a revision request or follow-up instruction to a live subagent. " +
-      "It receives your text as a new turn, acts on it, and reports again. " +
-      "Use after reviewing its report when changes are needed; use " +
-      "close_agent when the work is accepted. The next report arrives as a " +
-      "message in this session; do not poll or sleep.",
+      "The message steers its current run, or starts a new turn if it is idle. " +
+      "Use after reviewing its report when changes are needed. Its next report " +
+      "steers your current run, or starts a new turn if you are idle. Do not poll " +
+      "or sleep; continue other work or end your turn.",
     parameters: Type.Object({
       id: Type.String({
         description: "The subagent's UUID, from its spawn result or report.",
@@ -628,11 +674,10 @@ function setupParent(
     name: "close_agent",
     label: "Close Agent",
     description:
-      "Shut down a live subagent's session without spending a model turn. " +
-      "Use to accept its report or to stop one you no longer need. For an " +
-      "isolated agent, this removes its worktree but retains its agent/<name> " +
-      "branch for normal review, merge, or deletion. Subagents stay alive " +
-      "until closed; close every subagent when you are done with it.",
+      "Shut down a live subagent without spending a model turn. Use after " +
+      "accepting its report or when the subagent is no longer needed. For an " +
+      "isolated subagent, this removes its worktree and discards uncommitted " +
+      "changes, but retains its agent/<name> branch. Close every subagent when finished.",
     parameters: Type.Object({
       id: Type.String({
         description: "The subagent's UUID, from its spawn result or report.",
@@ -697,19 +742,14 @@ function subagentSystemPrompt(branch?: string): string {
     "conversation. Focus only on the delegated task. " +
     workspace +
     "\n\n" +
-    "# Reporting to the parent\n\n" +
-    "report_result is the only channel that reaches the parent. It cannot " +
-    "see your text replies, your tool output, or anything else in this " +
-    "session — so a turn that ends in plain text leaves the parent waiting " +
-    "forever, with no way to know you responded.\n\n" +
-    "- Call report_result when the task is done, when you have acted on a " +
-    "revision request from the parent, and when you are blocked and need " +
-    "the parent's input.\n" +
-    "- Every message from the parent calls for a report_result response, " +
-    "even if the report is only a brief status update.\n" +
-    "- After reporting, end your turn and wait. The session stays alive: " +
-    "the parent reviews each report and either sends you a revision request " +
-    "as an ordinary message or closes the session."
+    "# Communication\n\n" +
+    "- Parent messages, including your task, arrive in <message-from-parent> " +
+    "tags. Send answers, outcomes, and blockers back with message_parent; " +
+    "the parent cannot see your text replies.\n" +
+    "- Unwrapped messages come from the human using this session. Reply in " +
+    "text unless they ask you to relay something to the parent.\n\n" +
+    "After calling message_parent, end your turn and wait. The session stays " +
+    "alive for the parent's reply."
   );
 }
 
@@ -737,17 +777,14 @@ function processAgentLine(pi: ExtensionAPI, line: string): void {
     // steer: a revision request is news the child can fold into its current
     // run; it is delivered after the child's pending tool calls, before its
     // next LLM call.
-    // The tags and the trailing instruction matter: without an explicit cue
-    // to report back, a child may answer in plain text and end its turn,
-    // which never reaches the parent.
+    // Match the spawn task's wrapper. The reminder makes the child reply over
+    // the socket rather than ending with a text reply the parent cannot see.
     pi.sendMessage(
       {
         customType: MESSAGE_TYPE,
         content:
           `<message-from-parent>\n${candidate.text}\n</message-from-parent>\n\n` +
-          "Act on this message, then report the outcome with report_result. " +
-          "The parent receives only report_result output — it cannot see " +
-          "your text replies.",
+          "Act on this message, then reply with message_parent.",
         display: true,
       },
       { triggerTurn: true, deliverAs: "steer" },
@@ -770,37 +807,35 @@ function setupChild(
     };
   });
 
-  // ── result reporting (child → parent) ──────────────────────────────
+  // ── message channel (child → parent) ───────────────────────────────
   //
   // Delivery failures are reported to the model, which retries with the same
-  // result. Failures are unambiguous in practice: they mean the parent is
-  // gone or the write failed, so a retry cannot deliver a report twice.
-  let reportState: "open" | "sending" = "open";
+  // message. Failures are unambiguous in practice: they mean the parent is
+  // gone or the write failed, so a retry cannot deliver a message twice.
+  let sendState: "open" | "sending" = "open";
 
   pi.registerTool({
-    name: "report_result",
-    label: "Report Result",
+    name: "message_parent",
+    label: "Message Parent",
     description:
-      "Send a result report to the parent — the only channel that reaches " +
-      "it. The parent cannot see your text replies. Use when the task is " +
-      "done, when reporting a requested revision, or when you are " +
-      "blocked and need the parent's input. Report outcomes, not " +
-      "progress updates.",
+      "Send a message to the parent session; it cannot see your text replies. " +
+      "Use it to answer the parent, report completed work, or ask for input " +
+      "when blocked. Send outcomes, not progress updates.",
     parameters: Type.Object({
-      result: Type.String({
+      message: Type.String({
         description:
-          "The complete result for the parent. Include the outcome and, when " +
-          "relevant, edits, verification, and blockers.",
+          "The answer, outcome, or blocker for the parent. Include edits and " +
+          "verification when relevant.",
       }),
     }),
     execute: async (_id, params, _signal, _onUpdate, toolCtx) => {
-      if (reportState !== "open") {
-        throw new Error("report_result is already delivering a report");
+      if (sendState !== "open") {
+        throw new Error("message_parent is already sending a message");
       }
-      reportState = "sending";
+      sendState = "sending";
 
-      const { result } = params as { result: string };
-      const payload = `${JSON.stringify({ id: subagentId, summary: result })}\n`;
+      const { message } = params as { message: string };
+      const payload = `${JSON.stringify({ id: subagentId, summary: message })}\n`;
 
       try {
         await new Promise<void>((resolve, reject) => {
@@ -823,25 +858,25 @@ function setupChild(
           socket.end(payload, () => finish());
         });
       } catch (err) {
-        reportState = "open";
-        const message = `fork: could not deliver result to parent: ${err}`;
-        console.error(message);
+        sendState = "open";
+        const failure = `fork: could not deliver message to parent: ${err}`;
+        console.error(failure);
         toolCtx.ui.notify(
-          `${message}. The report was not sent; retry report_result with the same result.`,
+          `${failure}. The message was not sent; retry message_parent with the same message.`,
           "error",
         );
         throw new Error(
-          "Result delivery failed; the report was not sent. Retry " +
-            "report_result with the same result.",
+          "Message delivery failed; the message was not sent. Retry " +
+            "message_parent with the same message.",
         );
       }
 
-      reportState = "open";
+      sendState = "open";
       return {
         content: [
           {
             type: "text" as const,
-            text: "Report delivered. End your turn and await the parent's verdict.",
+            text: "Delivered to the parent. End your turn and wait for its reply.",
           },
         ],
         details: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resolveworks/fork",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Subagents for Pi — spawn pi sessions in tmux windows with task delegation and revision loops",
   "type": "module",
   "engines": {