@tyvm/knowhow 0.0.137 → 0.0.140

package/src/agents/tools/replyToParent.ts

@@ -0,0 +1,122 @@
+import * as fs from "fs";
+import * as path from "path";
+import { Tool } from "../../clients/types";
+import { ToolCallContext } from "../../services/Tools";
+
+/** Resolve the agents dir lazily so tests (and cwd changes) are respected. */
+function agentsDir(): string {
+  return path.join(process.cwd(), ".knowhow", "processes", "agents");
+}
+
+/**
+ * Resolve the parent taskId for the calling agent.
+ *
+ * Order of resolution:
+ *  1. `_ctx.parentTaskId` if the caller carries it directly
+ *  2. `_ctx.caller.parentTaskId` if the agent instance exposes it
+ *  3. The `parentTaskId` field of the caller's own metadata.json (looked up by
+ *     `_ctx.taskId`)
+ */
+function resolveParentTaskId(ctx?: ToolCallContext): string | undefined {
+  if (!ctx) return undefined;
+
+  if (ctx.parentTaskId) return ctx.parentTaskId as string;
+  const callerParent = (ctx.caller as any)?.parentTaskId;
+  if (callerParent) return callerParent as string;
+
+  // Fall back to reading our own metadata.json for the parentTaskId field.
+  const ownTaskId = ctx.taskId ?? (ctx.caller as any)?.currentTaskId;
+  if (!ownTaskId) return undefined;
+
+  try {
+    const metaPath = path.join(agentsDir(), ownTaskId, "metadata.json");
+    if (fs.existsSync(metaPath)) {
+      const meta = JSON.parse(fs.readFileSync(metaPath, "utf8"));
+      return meta.parentTaskId;
+    }
+  } catch {
+    // ignore — no parent metadata available
+  }
+  return undefined;
+}
+
+/**
+ * Send a message back to the parent agent that spawned this task.
+ *
+ * This is a self-referential tool: it uses the per-call context (`_ctx`) to
+ * discover which agent is calling it and which parent task spawned it, then
+ * appends the message to the parent's `input.txt` so the parent picks it up on
+ * its next sync cycle.
+ *
+ * `_ctx` is threaded in by ToolsService.callTool as the LAST positional
+ * argument. The agent effectively passes *itself* in via `_ctx.caller`.
+ */
+export async function replyToParent(
+  message: string,
+  _ctx?: ToolCallContext
+): Promise<string> {
+  if (!message || !message.trim()) {
+    return "No message provided to replyToParent.";
+  }
+
+  const parentTaskId = resolveParentTaskId(_ctx);
+  if (!parentTaskId) {
+    return (
+      "No parent task found — this agent was not spawned with a parent taskId, " +
+      "so there is no one to reply to."
+    );
+  }
+
+  const parentDir = path.join(agentsDir(), parentTaskId);
+  const parentInputPath = path.join(parentDir, "input.txt");
+
+  if (!fs.existsSync(parentDir)) {
+    return `Parent task directory not found: ${parentDir}`;
+  }
+
+  const fromTaskId =
+    _ctx?.taskId ?? (_ctx?.caller as any)?.currentTaskId ?? "unknown";
+  const fromAgent = (_ctx?.caller as any)?.name ?? "child";
+
+  // Envelope with sender identity so the parent knows who is replying.
+  const envelope = `[from:${fromTaskId}] [agent:${fromAgent}] ${message}`;
+
+  try {
+    // Append rather than overwrite so we don't clobber other pending messages.
+    const existing = fs.existsSync(parentInputPath)
+      ? fs.readFileSync(parentInputPath, "utf8")
+      : "";
+    const next = existing && !existing.endsWith("\n")
+      ? `${existing}\n${envelope}\n`
+      : `${existing}${envelope}\n`;
+    fs.writeFileSync(parentInputPath, next, "utf8");
+  } catch (e: any) {
+    return `Failed to write to parent input.txt: ${e?.message ?? String(e)}`;
+  }
+
+  return `Sent message to parent task ${parentTaskId}.`;
+}
+
+export const replyToParentDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "replyToParent",
+    description:
+      "Send a message back to the parent agent that spawned this task. Use this " +
+      "to report progress, ask a question, or alert the parent to something. The " +
+      "message is delivered to the parent's input queue and picked up on its next " +
+      "sync cycle. Only works when this agent was spawned by another agent (i.e. " +
+      "it has a parent taskId).",
+    parameters: {
+      type: "object",
+      positional: true,
+      properties: {
+        message: {
+          type: "string",
+          description: "The message to send back to the parent agent",
+        },
+      },
+      required: ["message"],
+    },
+  },
+};

package/src/agents/tools/runGenerate.ts

@@ -0,0 +1,209 @@
+import { Tool } from "../../clients/types";
+import { GenerationSource } from "../../types";
+import { generate, GenerateOptions, buildWaves } from "../../generate";
+
+export interface RunGenerateParams {
+  /**
+   * In-memory generation sources defining the pipeline. When provided, these
+   * are used INSTEAD of the sources in .knowhow/knowhow.json. Each source can
+   * declare `dependsOn` for explicit ordering, an `agent` for agent-driven
+   * generation, and input/output/prompt for the work itself.
+   */
+  sources?: GenerationSource[];
+  /** Only run sources whose `name` matches exactly this value (config mode). */
+  name?: string;
+  /** Only run sources whose name/input/output contains this substring. */
+  filter?: string;
+  /** Skip hash checks and regenerate all matching sources regardless of changes. */
+  force?: boolean;
+  /** Max sources to run in parallel within a dependency wave. Default: 3. */
+  concurrency?: number;
+  /**
+   * When true, agent-driven sources create .knowhow/processes/agents/<taskId>/
+   * so they appear in `knowhow agents list`.
+   */
+  syncFs?: boolean;
+  /**
+   * When true, agent-driven sources push their work to a remote Knowhow task
+   * (identified by the source's taskId).
+   */
+  syncRemote?: boolean;
+  /** When true, only compute and return the execution plan (waves) without running. */
+  planOnly?: boolean;
+  /** Per-call context injected by ToolsService.callTool. */
+  _ctx?: { caller?: any; taskId?: string; [key: string]: any };
+}
+
+/**
+ * runGenerate — expose `knowhow generate` as an agent tool.
+ *
+ * This lets an agent orchestrate complex, multi-step pipelines at runtime
+ * without needing them defined in the config. It supports:
+ *   - `dependsOn` for explicit ordering (topological waves)
+ *   - automatic I/O overlap detection (source B reading source A's output runs after A)
+ *   - per-source `agent` for agent-driven generation (map/reduce fan-out)
+ *   - concurrency control within each dependency wave
+ *   - plain summarization/analysis sources (no agent)
+ *
+ * With `planOnly: true`, it returns the computed wave plan so the agent can
+ * inspect ordering/parallelism before committing to a run.
+ */
+export async function runGenerate(params: RunGenerateParams): Promise<string> {
+  const {
+    sources,
+    name,
+    filter,
+    force,
+    concurrency,
+    syncFs,
+    syncRemote,
+    planOnly,
+  } = params ?? {};
+
+  // Default filesystem sync ON for agent-driven sources so they show up in
+  // `knowhow agents list` and can be attached/tailed. Pass syncFs: false to opt out.
+  const effectiveSyncFs = syncFs !== false;
+
+  const options: GenerateOptions = {
+    sources,
+    name,
+    filter,
+    force,
+    concurrency,
+    syncFs: effectiveSyncFs,
+    syncRemote,
+  };
+
+  // Resolve the source set for planning output.
+  const effectiveSources = sources ?? [];
+
+  if (planOnly) {
+    if (effectiveSources.length === 0) {
+      return (
+        "planOnly requires in-memory `sources` to build a plan. " +
+        "Provide sources to see how they'd be grouped into dependency waves."
+      );
+    }
+    const filtered = effectiveSources.filter((s) => {
+      if (name) return s.name === name;
+      if (filter) {
+        const needle = filter.toLowerCase();
+        return [s.name, s.input, s.output]
+          .filter(Boolean)
+          .some((v) => v!.toLowerCase().includes(needle));
+      }
+      return true;
+    });
+    const waves = buildWaves(filtered);
+    const lines: string[] = [];
+    lines.push(
+      `📋 Generation Plan (concurrency: ${concurrency ?? 3}, ${filtered.length} sources, ${waves.length} wave${waves.length !== 1 ? "s" : ""})`
+    );
+    waves.forEach((wave, i) => {
+      lines.push(`\n┌─ Wave ${i + 1}/${waves.length} (${wave.length} in parallel)`);
+      for (const s of wave) {
+        const label = s.name || "(unnamed)";
+        const io = `${s.input || "-"} → ${s.output || "-"}`;
+        const agentPart = s.agent ? `  [agent: ${s.agent}]` : "";
+        lines.push(`│  • ${label}  ${io}${agentPart}`);
+      }
+      lines.push("└────────────────────────────────────────────────");
+    });
+    return lines.join("\n");
+  }
+
+  try {
+    await generate(options);
+  } catch (e: any) {
+    return `Generation failed: ${e?.message ?? String(e)}`;
+  }
+
+  const count = effectiveSources.length;
+  const mode = count > 0 ? `${count} in-memory source(s)` : "config sources";
+  return (
+    `Generation complete for ${mode}` +
+    (name ? ` (name="${name}")` : filter ? ` (filter="${filter}")` : "") +
+    `. Outputs written to their configured paths. ` +
+    `If agent-driven sources used syncFs, inspect them with \`knowhow agents list\`.`
+  );
+}
+
+export const runGenerateDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "runGenerate",
+    description:
+      "Run the `knowhow generate` pipeline. Accepts in-memory `sources` so you can define arbitrary " +
+      "task orchestration at runtime WITHOUT editing the config file. Supports dependency ordering via " +
+      "`dependsOn`, automatic I/O overlap detection (a source reading another's output runs after it), " +
+      "per-source `agent` for agent-driven generation (map/reduce fan-out — one agent per input), " +
+      "concurrency control within each dependency wave, and plain summarization/analysis sources. " +
+      "Use `planOnly: true` to preview how sources group into concurrent dependency waves before running. " +
+      "When `sources` is omitted, it runs the sources defined in .knowhow/knowhow.json (optionally scoped by name/filter).",
+    parameters: {
+      type: "object",
+      properties: {
+        sources: {
+          type: "array",
+          description:
+            "In-memory generation sources. Each item: { name?, input, output, prompt, agent?, model?, " +
+            "kind?, outputExt?, outputName?, dependsOn?: string[], syncFs?, maxTimeLimit?, maxSpendLimit? }. " +
+            "`input` is a glob or comma-separated file list; `output` is the target file/dir; `prompt` is the " +
+            "generation instruction; `agent` (optional) runs an agent per input instead of a summarization call; " +
+            "`dependsOn` lists names of sources that must finish first.",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              input: { type: "string" },
+              output: { type: "string" },
+              prompt: { type: "string" },
+              agent: { type: "string" },
+              model: { type: "string" },
+              kind: { type: "string" },
+              outputExt: { type: "string" },
+              outputName: { type: "string" },
+              dependsOn: { type: "array", items: { type: "string" } },
+              syncFs: { type: "boolean" },
+              maxTimeLimit: { type: "number" },
+              maxSpendLimit: { type: "number" },
+            },
+          },
+        },
+        name: {
+          type: "string",
+          description: "Only run sources whose `name` matches exactly (config mode).",
+        },
+        filter: {
+          type: "string",
+          description: "Only run sources whose name/input/output contains this substring.",
+        },
+        force: {
+          type: "boolean",
+          description: "Skip hash checks and regenerate all matching sources.",
+        },
+        concurrency: {
+          type: "number",
+          description: "Max sources to run in parallel within a dependency wave. Default: 3.",
+        },
+        syncFs: {
+          type: "boolean",
+          description:
+            "For agent-driven sources, create .knowhow/processes/agents/<taskId>/ so they appear in `knowhow agents list`. " +
+            "Defaults to true (enabled). Pass false to opt out.",
+        },
+        syncRemote: {
+          type: "boolean",
+          description:
+            "For agent-driven sources, push their work to a remote Knowhow task (identified by the source's taskId), " +
+            "in addition to fs sync.",
+        },
+        planOnly: {
+          type: "boolean",
+          description: "Return the wave execution plan without running anything (requires `sources`).",
+        },
+      },
+      required: [],
+    },
+  },
+};

package/src/agents/tools/sendAgentMessage.ts

@@ -0,0 +1,138 @@
+import * as fs from "fs";
+import * as path from "path";
+import { Tool } from "../../clients/types";
+import { ToolCallContext } from "../../services/Tools";
+
+/** Resolve the agents dir lazily so tests (and cwd changes) are respected. */
+function agentsDir(): string {
+  return path.join(process.cwd(), ".knowhow", "processes", "agents");
+}
+
+/**
+ * Append a line to a task's input.txt without clobbering other pending
+ * messages. AgentSyncFs.checkForChanges reads input.txt and turns non-slash
+ * content into a pending user message on the target agent (and honors /poke to
+ * interrupt).
+ */
+function appendToInput(inputPath: string, line: string): void {
+  const existing = fs.existsSync(inputPath)
+    ? fs.readFileSync(inputPath, "utf8")
+    : "";
+  const next =
+    existing && !existing.endsWith("\n")
+      ? `${existing}\n${line}\n`
+      : `${existing}${line}\n`;
+  fs.writeFileSync(inputPath, next, "utf8");
+}
+
+export interface SendAgentMessageParams {
+  /** The taskId of the agent to send a message to. */
+  taskId: string;
+  /** The message body to deliver. */
+  message: string;
+  /**
+   * Optional sender identifier. If omitted, resolved from the calling agent's
+   * own taskId via _ctx. Included as a `[from:...]` envelope so the recipient
+   * knows who to reply to.
+   */
+  from?: string;
+  /**
+   * When true, deliver as a `/poke` (interrupts the recipient's current step)
+   * rather than a queued user message. Default false.
+   */
+  poke?: boolean;
+  _ctx?: ToolCallContext;
+}
+
+/**
+ * Send a message to another running agent (a child, a peer, or the parent) by
+ * appending it to that agent's input.txt. This is the "down/lateral edge" of
+ * agent-to-agent communication — the complement to replyToParent (the up edge).
+ *
+ * The recipient's AgentSyncFs picks up the message on its next sync cycle and
+ * adds it as a pending user message. If `poke` is true, it is delivered as a
+ * `/poke` command which interrupts the recipient's current step.
+ *
+ * Self-referential: the sender identity is resolved from `_ctx` (the calling
+ * agent) when `from` isn't supplied.
+ */
+export async function sendAgentMessage(
+  params: SendAgentMessageParams
+): Promise<string> {
+  const { taskId, message, from, poke = false, _ctx } = params;
+
+  if (!taskId) {
+    return "sendAgentMessage: taskId is required.";
+  }
+  if (!message || !message.trim()) {
+    return "sendAgentMessage: message is required.";
+  }
+
+  const targetDir = path.join(agentsDir(), taskId);
+  const inputPath = path.join(targetDir, "input.txt");
+
+  if (!fs.existsSync(targetDir)) {
+    return `sendAgentMessage: target task directory not found: ${targetDir}`;
+  }
+
+  const fromId =
+    from ??
+    _ctx?.taskId ??
+    (_ctx?.caller as any)?.currentTaskId ??
+    "unknown";
+  const fromAgent = (_ctx?.caller as any)?.name;
+  const fromLabel = fromAgent ? `${fromId}/${fromAgent}` : fromId;
+
+  try {
+    if (poke) {
+      // /poke [message] — interrupts the recipient's current step.
+      appendToInput(inputPath, `/poke [from:${fromLabel}] ${message}`);
+    } else {
+      appendToInput(inputPath, `[from:${fromLabel}] ${message}`);
+    }
+  } catch (e: any) {
+    return `sendAgentMessage: failed to write to ${inputPath}: ${
+      e?.message ?? String(e)
+    }`;
+  }
+
+  return `Sent message to task ${taskId}${poke ? " (as /poke)" : ""}.`;
+}
+
+export const sendAgentMessageDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "sendAgentMessage",
+    description:
+      "Send a message to another running agent (a child you spawned, a peer, or your parent) by " +
+      "appending it to that agent's input queue. The recipient picks it up on its next sync cycle " +
+      "as a user message. This is the down/lateral communication edge (complement to replyToParent). " +
+      "Set poke:true to interrupt the recipient's current step (delivered as /poke). Your sender " +
+      "identity is attached automatically so the recipient can reply back to you.",
+    parameters: {
+      type: "object",
+      positional: false,
+      properties: {
+        taskId: {
+          type: "string",
+          description: "The taskId of the agent to send the message to.",
+        },
+        message: {
+          type: "string",
+          description: "The message to deliver to the recipient agent.",
+        },
+        from: {
+          type: "string",
+          description:
+            "Optional sender id. Defaults to the calling agent's own taskId.",
+        },
+        poke: {
+          type: "boolean",
+          description:
+            "When true, deliver as a /poke that interrupts the recipient's current step. Default false.",
+        },
+      },
+      required: ["taskId", "message"],
+    },
+  },
+};

package/src/agents/tools/startAgentTask.ts

@@ -9,6 +9,11 @@ export interface StartAgentTaskParams {
   taskId?: string;
   resume?: boolean;
   prompt: string;
+  /**
+   * Push this agent's work to a remote Knowhow task identified by taskId.
+   * When set (and no messageId), the spawned agent attaches to that remote task.
+   */
+  syncRemote?: boolean;
   provider?: string;
   model?: string;
   agentName?: string;
@@ -16,6 +21,15 @@ export interface StartAgentTaskParams {
   maxSpendLimit?: number;
   /** When true, wait for the agent subprocess to exit before resolving (for generate pipelines). */
   waitForCompletion?: boolean;
+  /**
+   * The taskId of the parent agent that is spawning this task. Passed to the
+   * child via --parent-task-id so the child knows who to report back to. When
+   * omitted, it is auto-populated from the per-call context (`_ctx.taskId`) of
+   * the spawning agent.
+   */
+  parentTaskId?: string;
+  /** Per-call context injected by ToolsService.callTool (contains caller + taskId). */
+  _ctx?: { caller?: any; taskId?: string; [key: string]: any };
 }
 
 const PROCESSES_DIR = path.join(process.cwd(), ".knowhow", "processes");
@@ -39,6 +53,37 @@ function generateTaskId(prompt: string): string {
   return fullId.slice(0, 80);
 }
 
+/**
+ * A short capabilities note appended to a spawned subagent's prompt so it knows
+ * it can use the `knowhow agents` and related CLI commands (via its execCommand
+ * tool) to coordinate, inspect, and orchestrate other agents — things it may
+ * not have dedicated tools for.
+ */
+function subagentCapabilitiesNote(): string {
+  const lines = [
+    "",
+    "---",
+    "SUBAGENT ORCHESTRATION CAPABILITIES:",
+    "You are running as a knowhow agent with a synchronized task directory. In addition to your tools,",
+    "you can shell out (via execCommand) to the `knowhow agents` CLI to coordinate and inspect other agents:",
+    "  • knowhow agents list                 — list running/recent agent tasks (with row indexes)",
+    "  • knowhow agents status <id|-i N>      — status, cost, last tool/message for a task",
+    "  • knowhow agents tail <id|-i N> [-f]   — read recent messages (read-only; -f to follow live)",
+    "  • knowhow agents answer <id|-i N>      — print the final answer of a COMPLETED task",
+    "  • knowhow agents attach <id|-i N>      — open the interactive chat attached to a running task",
+    "You can spawn more subagents with the startAgentTask tool, or run whole pipelines with the runGenerate tool",
+    "(supports dependsOn ordering, per-source agents, and concurrency for map/reduce fan-out).",
+    "To coordinate spawned subagents from your tools: use waitForAgentCompleted (join a subagent and",
+    "get a structured { status, costUsd, finalAnswer } result) and observe (stream a tool's results",
+    "back to yourself on an interval, e.g. observe waitForAgentCompleted or `agents status`).",
+    "To communicate with running agents: use sendAgentMessage (send a message or /poke to a child/peer/parent),",
+    "replyToParent (report back to whoever spawned you), and connectAgent (wire agents together with an ARRAY",
+    "of { listener, speaker } connections — enables bidirectional, pipeline, star, and mesh topologies in one call).",
+  ];
+  lines.push("---", "");
+  return lines.join("\n");
+}
+
 /**
  * Creates a chat task in Knowhow based on a message ID and prompt.
  * Spawns the knowhow CLI with the prompt piped via stdin to avoid
@@ -60,31 +105,50 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
     taskId: providedTaskId,
     resume,
     syncFs,
+    syncRemote,
     provider,
     model,
     agentName,
     maxTimeLimit,
     maxSpendLimit,
     waitForCompletion,
+    parentTaskId: explicitParentTaskId,
+    _ctx,
   } = params;
   if (!prompt) {
     throw new Error("prompt is required to create a chat task");
   }
 
+  // Default filesystem synchronization ON unless the caller explicitly opts out
+  // (syncFs: false) or is using a messageId-based web sync. This ensures spawned
+  // subagents always appear in `knowhow agents list` and can be attached/tailed.
+  const useSyncFs = syncFs !== false && !messageId;
+
   // Use provided taskId if given, otherwise generate one from the prompt
   const taskId = providedTaskId ?? generateTaskId(prompt);
   const agentTaskDir = path.join(AGENTS_DIR, taskId);
 
+  // Determine the parent taskId: explicit param wins, otherwise fall back to
+  // the spawning agent's taskId carried in the per-call context (`_ctx`).
+  const parentTaskId =
+    explicitParentTaskId ?? _ctx?.taskId ?? (_ctx?.caller as any)?.currentTaskId;
+
   // Build args array (no shell escaping needed - args are passed directly)
   const args: string[] = ["agent"];
 
   if (messageId) {
     args.push("--message-id", messageId);
-  } else if (syncFs) {
+  } else if (useSyncFs) {
     args.push("--sync-fs");
   }
+  // When syncRemote is requested, pass it through so the spawned agent pushes
+  // its work to the remote task identified by --task-id rather than staying
+  // local-only.
+  if (syncRemote) {
+    args.push("--sync-remote");
+  }
 
-  if (syncFs || providedTaskId) {
+  if (useSyncFs || providedTaskId) {
     // Pass --task-id whenever we have a known taskId (syncFs or explicit taskId)
     args.push("--task-id", taskId);
   }
@@ -108,6 +172,10 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
   if (maxSpendLimit !== undefined) {
     args.push("--max-spend-limit", String(maxSpendLimit));
   }
+  if (parentTaskId) {
+    // Tell the child who spawned it so it can report back to the parent.
+    args.push("--parent-task-id", parentTaskId);
+  }
   if (resume) {
     // --resume is a boolean flag; task ID is already passed via --task-id above
     args.push("--resume");
@@ -137,7 +205,12 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
   fs.writeSync(fd, `PID: ${pid}\n`);
 
   // Write prompt to stdin and close it so the process reads it
-  child.stdin!.write(prompt, "utf8");
+  // Append the subagent orchestration capabilities note (unless resuming — a
+  // resumed task already has its full context and we don't want to re-inject).
+  const promptWithCaps = resume
+    ? prompt
+    : prompt + subagentCapabilitiesNote();
+  child.stdin!.write(promptWithCaps, "utf8");
   child.stdin!.end();
 
   return new Promise<string>((resolve) => {
@@ -153,7 +226,7 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
       done(`Failed to start agent: ${String(e)}\nLogs: ${logPath}`);
     });
 
-    const syncFsNote = syncFs
+    const syncFsNote = useSyncFs
       ? `\nTask ID: ${taskId}\nAgent dir: ${agentTaskDir}\n` +
         `To send agent messages, write to: ${agentTaskDir}/input.txt\n` +
         `To check status, read: ${agentTaskDir}/status.txt\n`
@@ -201,7 +274,15 @@ export const startAgentTaskDefinition: Tool = {
         syncFs: {
           type: "boolean",
           description:
-            "Enable filesystem-based synchronization for the task. Use this when no messageId is available.",
+            "Filesystem-based synchronization for the task. Defaults to true (enabled) when no messageId is given, " +
+            "so the spawned agent always appears in `knowhow agents list` and can be attached/tailed. Pass false to opt out.",
+        },
+        syncRemote: {
+          type: "boolean",
+          description:
+            "Push this agent's work to a remote Knowhow task identified by taskId (in addition to fs sync). " +
+            "Use this to sync a spawned subagent's progress to an already-created remote task. " +
+            "If messageId is given instead, a fresh remote task is created from that message.",
         },
         prompt: {
           type: "string",
@@ -238,6 +319,12 @@ export const startAgentTaskDefinition: Tool = {
           description:
             "Resume a previously started task from where it left off. Must be used together with taskId which identifies the task to resume.",
         },
+        parentTaskId: {
+          type: "string",
+          description:
+            "The taskId of the parent that should be notified by this child (e.g. via replyToParent). " +
+            "If omitted, it is auto-populated from the spawning agent's own taskId.",
+        },
       },
       required: ["prompt"],
     },