@hheei/pi-subagents 0.5.3 → 0.6.0

package/README.md

@@ -16,7 +16,7 @@ children and `/subagents stop [id]` to stop one without conflicting with other e
 | Tool | Purpose |
 | --- | --- |
 | `agent_spawn({ task, agent, cwd?, title? })` | Spawn an independent background subagent task. Runs in a new Herdr tab (or cmux surface) targeting the parent's workspace when a host is available, and headless in the background otherwise. **Prefer reusing existing subagents** via `agent_send` for related/follow-up work to maintain context and maximize prompt cache and memory efficiency. Tool description lists available agent names and roles, excluding disabled or hidden definitions. Deferred by default; discover via `tool_search({ query: "agent" })`. Do not poll for completion; results return automatically. |
-| `agent_send({ id, message, mode? })` | Send `steer`, `follow_up`, or `auto` input to a specific child. **Primary tool for assigning follow-up or functionally related tasks** to existing subagents: idle, blocked, done, or errored children resume their existing session automatically with historical context intact. A child whose runtime has ended is resumed the same way; spawn a new child only for new work. Stop first only when send says the previous process is still running. Deferred by default; discover via `tool_search({ query: "agent" })`. |
+| `agent_send({ id, message, mode? })` | Send input to a specific child. `mode: "steer"` (the default) enters the current turn once its tool calls are in, before the next model request; `mode: "follow_up"` waits until the child has no tool calls or steering left, then continues as a new turn. **Primary tool for assigning follow-up or functionally related tasks** to existing subagents: idle, blocked, done, or errored children resume their existing session automatically with historical context intact. A child whose runtime has ended is resumed the same way; spawn a new child only for new work. Stop first only when send says the previous process is still running. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 | `agent_get({ id, keys? })` | Inspect one subagent by id. `keys` is a comma-separated selection of `status` (default), `progress` (default), and `diagnostic`; unknown keys fail. The view never returns the child's task parameters or terminal result, which arrive automatically as reports. From the second successful inspection of the same child in this parent runtime, the result adds a short reminder that results return automatically and must not be polled. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 | `agent_stop({ id })` | Stop one subagent's runtime by id. The child keeps its session, so a later `agent_send` can resume it. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 

package/dist/domain.d.ts

@@ -8,7 +8,16 @@ export declare function normalizeSubagentState(value: unknown): SubagentState |
  * is created, because it decides who holds the process for the rest of the child's life.
  */
 export type Presentation = "panel" | "background";
-export type SendMode = "steer" | "follow_up" | "auto";
+/**
+ * How `agent_send` hands its message to a child.
+ *
+ * `steer` enters the current assistant turn once its tool calls are in, before the next model
+ * request, so it redirects work already in flight. `follow_up` waits until the child's run has no
+ * tool calls or steering left, then continues as a new turn in the same run. There is no "auto":
+ * the two queues already are the two situations, so the caller picks instead of guessing from the
+ * child's state.
+ */
+export type SendMode = "steer" | "follow_up";
 export type VisualSubagentState = SubagentState;
 export declare function toVisualSubagentState(state: SubagentState, interrupted?: string): VisualSubagentState;
 export declare const VISUAL_SUBAGENT_GLYPH: Record<VisualSubagentState, string>;

package/dist/manager.js

@@ -923,7 +923,7 @@ export class SubagentManager {
             return failed;
         }
     }
-    send(id, rawMessage, mode = "auto", signal) {
+    send(id, rawMessage, mode = "steer", signal) {
         const message = stripHindsightContent(rawMessage);
         this.#bumpActivity(id);
         this.#clearSettledPanelClose(id);
@@ -994,15 +994,10 @@ export class SubagentManager {
                 }
             }
             const state = isResumed ? "running" : record.state;
-            const operation = isResumed
-                ? "prompt"
-                : mode === "auto"
-                    ? state === "running"
-                        ? "steer"
-                        : "follow_up"
-                    : mode;
-            if (operation === undefined)
-                return failure("send", "Cannot infer send mode from unknown state", id, state);
+            // A resume already starts a fresh run, so the mode has nothing to decide: the message is
+            // that run's prompt. Otherwise the caller's mode is the request, with no state guessing:
+            // a running child steers at its next model step, an idle one simply starts a run.
+            const operation = isResumed ? "prompt" : mode;
             if (signal?.aborted)
                 return failure("send", "Send was cancelled", id, state);
             this.#clearSettledPanelClose(id);

package/dist/tool-presentation.js

@@ -55,7 +55,7 @@ function spawnPresentation(args, result) {
 function sendPresentation(args, result) {
     const record = isRecord(args) ? args : undefined;
     const id = stringField(record, "id") ?? "agent";
-    const mode = stringField(record, "mode") ?? "auto";
+    const mode = stringField(record, "mode") ?? "steer";
     const message = stringField(record, "message");
     const confirmation = result === undefined ? undefined : agentResultText(result);
     const copy = message === undefined

package/dist/tools.js

@@ -18,7 +18,9 @@ const spawnSchema = Type.Object({
 const sendSchema = Type.Object({
     id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
     message: Type.String({ minLength: 1 }),
-    mode: Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("follow_up"), Type.Literal("auto")])),
+    mode: Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("follow_up")], {
+        description: "steer (the default) enters the child's current turn once its tool calls are in, before the next model request, so it redirects work already in flight; an idle child just starts a run. follow_up waits until the child has no tool calls or steering left, then continues as a new turn. Use follow_up for work that must not interrupt what the child is doing now.",
+    })),
 });
 const idSchema = Type.Object({
     id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
@@ -66,7 +68,7 @@ function getSpawnDescription(agents) {
         formatAvailableAgents(agents),
     ].join("\n");
 }
-const SEND_DESCRIPTION = "Send input, steer, or follow-up instructions to an existing subagent (e.g. 'agent-1'), resuming its session when it is idle, blocked, done, or errored. A child whose runtime has ended is resumed the same way: send to that id, do not spawn a replacement. Stop it first only when send reports the previous process is still running. Results are returned automatically when the task finishes; do not poll agent_get. Related subagent tools: agent_spawn, agent_get, agent_stop.";
+const SEND_DESCRIPTION = "Send input to an existing subagent (e.g. 'agent-1'), resuming its session when it is idle, blocked, done, or errored. A child whose runtime has ended is resumed the same way: send to that id, do not spawn a replacement. Stop it first only when send reports the previous process is still running. Results are returned automatically when the task finishes; do not poll agent_get. Related subagent tools: agent_spawn, agent_get, agent_stop.";
 const GET_DESCRIPTION = "Inspect one subagent's status, progress, or diagnostic details by id (e.g. 'agent-1'). Use keys to choose fields; defaults to 'status,progress'. Results are returned automatically; use this for inspection, not completion polling. Related subagent tools: agent_spawn, agent_send, agent_stop.";
 const STOP_DESCRIPTION = "Stop a subagent's runtime by id (e.g. 'agent-1'). The child keeps its session, so a later agent_send can resume it. Related subagent tools: agent_spawn, agent_send, agent_get.";
 const CONTACT_DESCRIPTION = "Notify the parent session when you are BLOCKED and cannot continue without parent decision or intervention. Do NOT call this on success or task completion: simply output your final answer directly as normal text in your response, and the harness will automatically capture and report your result to the parent.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hheei/pi-subagents",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Independent background Pi subagent sessions with durable identity and RPC control.",
   "type": "module",
   "main": "dist/index.js",