@tyvm/knowhow 0.0.137 → 0.0.140

package/src/agents/tools/waitForAgentCompleted.ts

@@ -0,0 +1,269 @@
+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");
+}
+
+const TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "killed",
+  "error",
+  "done",
+]);
+
+interface AgentTaskResult {
+  taskId: string;
+  status: string;
+  costUsd: number;
+  finalAnswer?: string;
+  artifacts?: string[];
+  elapsedMs?: number;
+  timedOut?: boolean;
+  error?: string;
+}
+
+function readMeta(taskId: string): any | null {
+  try {
+    const metaPath = path.join(agentsDir(), taskId, "metadata.json");
+    if (!fs.existsSync(metaPath)) return null;
+    return JSON.parse(fs.readFileSync(metaPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readStatusFile(taskId: string): string | null {
+  try {
+    const statusPath = path.join(agentsDir(), taskId, "status.txt");
+    if (!fs.existsSync(statusPath)) return null;
+    return fs.readFileSync(statusPath, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Consolidated status read. metadata.status is the live/canonical value; the
+ * status.txt file is a fallback signal. If metadata says the task is no longer
+ * inProgress but has no explicit terminal status, treat it as completed.
+ */
+function resolveStatus(meta: any | null, statusFile: string | null): string {
+  if (meta?.status) return meta.status;
+  if (statusFile) return statusFile;
+  if (meta && meta.inProgress === false) return "completed";
+  return "unknown";
+}
+
+/** Extract the last assistant message from a thread as a fallback finalAnswer. */
+function lastAssistantText(threads: any): string | undefined {
+  if (!threads) return undefined;
+  // threads may be an array of message arrays, or a flat message array.
+  let messages: any[] = [];
+  if (Array.isArray(threads)) {
+    if (threads.length && Array.isArray(threads[0])) {
+      // array of threads — flatten
+      messages = threads.flat();
+    } else {
+      messages = threads;
+    }
+  }
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg?.role === "assistant") {
+      if (typeof msg.content === "string" && msg.content.trim()) {
+        return msg.content.trim();
+      }
+      if (Array.isArray(msg.content)) {
+        const text = msg.content
+          .filter((c: any) => c?.type === "text")
+          .map((c: any) => c.text)
+          .join("\n")
+          .trim();
+        if (text) return text;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Check whether a process id is still alive. Used as a fallback liveness check
+ * so we don't wait forever on a task whose process crashed without writing a
+ * terminal status.
+ */
+function pidAlive(pid: number): boolean {
+  try {
+    // signal 0 doesn't kill — it only checks for existence/permission.
+    process.kill(pid, 0);
+    return true;
+  } catch (e: any) {
+    // ESRCH = no such process. EPERM = exists but not ours (still alive).
+    return e?.code === "EPERM";
+  }
+}
+
+/**
+ * Discover the pid of a spawned agent task. AgentSyncFs.createTask records the
+ * agent subprocess's own `process.pid` into metadata.json, so we read the
+ * `pid` (or legacy `processId`) field from there. If it's absent (e.g. an older
+ * task created before this was persisted), we skip the liveness check.
+ */
+function metaPid(meta: any | null): number | undefined {
+  const pid = meta?.pid ?? meta?.processId;
+  return typeof pid === "number" ? pid : undefined;
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export interface WaitForAgentCompletedParams {
+  /** The taskId of the agent to wait for. */
+  taskId: string;
+  /** Max time to wait in milliseconds before returning timedOut. Default 30 min. */
+  timeoutMs?: number;
+  /** How often to poll status in milliseconds. Default 2000ms. */
+  pollIntervalMs?: number;
+  _ctx?: ToolCallContext;
+}
+
+/**
+ * Block until a spawned agent task reaches a terminal status, then return a
+ * structured result: { status, costUsd, finalAnswer, artifacts }.
+ *
+ * This is the native "join" primitive for orchestration — it must be a real
+ * tool (not a script polling loop) because the script sandbox caps `sleep` and
+ * burns a tool call per poll. It reads the consolidated status from
+ * metadata.json / status.txt and falls back to a process-liveness check so a
+ * crashed child doesn't hang the parent forever.
+ */
+export async function waitForAgentCompleted(
+  params: WaitForAgentCompletedParams
+): Promise<string> {
+  const {
+    taskId,
+    timeoutMs = 30 * 60 * 1000,
+    pollIntervalMs = 2000,
+  } = params;
+
+  if (!taskId) {
+    return JSON.stringify({
+      taskId,
+      status: "error",
+      costUsd: 0,
+      error: "taskId is required for waitForAgentCompleted",
+    } as AgentTaskResult);
+  }
+
+  const taskDir = path.join(agentsDir(), taskId);
+  if (!fs.existsSync(taskDir)) {
+    return JSON.stringify({
+      taskId,
+      status: "error",
+      costUsd: 0,
+      error: `No agent task directory found for taskId: ${taskId}`,
+    } as AgentTaskResult);
+  }
+
+  const start = Date.now();
+  const interval = Math.max(250, pollIntervalMs);
+  let missingProcessPolls = 0;
+
+  while (true) {
+    const meta = readMeta(taskId);
+    const statusFile = readStatusFile(taskId);
+    const status = resolveStatus(meta, statusFile);
+
+    if (TERMINAL_STATUSES.has(status)) {
+      const finalAnswer =
+        meta?.result ?? lastAssistantText(meta?.threads);
+      const result: AgentTaskResult = {
+        taskId,
+        status,
+        costUsd: meta?.totalCostUsd ?? 0,
+        finalAnswer,
+        artifacts: meta?.artifacts,
+        elapsedMs: Date.now() - start,
+      };
+      return JSON.stringify(result);
+    }
+
+    // Liveness fallback: if metadata exposes a pid and it is no longer alive,
+    // but no terminal status was written, treat the task as failed after a
+    // couple of confirming polls (avoids a race where the process just exited
+    // but hasn't flushed its final status yet).
+    const pid = metaPid(meta);
+    if (pid !== undefined && !pidAlive(pid)) {
+      missingProcessPolls++;
+      if (missingProcessPolls >= 2) {
+        const finalAnswer =
+          meta?.result ?? lastAssistantText(meta?.threads);
+        return JSON.stringify({
+          taskId,
+          status: meta?.result ? "completed" : "failed",
+          costUsd: meta?.totalCostUsd ?? 0,
+          finalAnswer,
+          artifacts: meta?.artifacts,
+          elapsedMs: Date.now() - start,
+          error: meta?.result
+            ? undefined
+            : "Agent process exited without writing a terminal status",
+        } as AgentTaskResult);
+      }
+    } else {
+      missingProcessPolls = 0;
+    }
+
+    if (Date.now() - start >= timeoutMs) {
+      return JSON.stringify({
+        taskId,
+        status,
+        costUsd: meta?.totalCostUsd ?? 0,
+        finalAnswer: meta?.result ?? lastAssistantText(meta?.threads),
+        artifacts: meta?.artifacts,
+        elapsedMs: Date.now() - start,
+        timedOut: true,
+      } as AgentTaskResult);
+    }
+
+    await sleep(interval);
+  }
+}
+
+export const waitForAgentCompletedDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "waitForAgentCompleted",
+    description:
+      "Block until a spawned agent task (started via startAgentTask or runGenerate) reaches a " +
+      "terminal status (completed/failed/killed), then return a structured JSON result with " +
+      "{ status, costUsd, finalAnswer, artifacts, elapsedMs }. This is the native way to 'join' a " +
+      "subagent — prefer it over shell polling loops with sleep. Returns immediately if the task is " +
+      "already finished, and gives up with timedOut:true after timeoutMs.",
+    parameters: {
+      type: "object",
+      positional: false,
+      properties: {
+        taskId: {
+          type: "string",
+          description:
+            "The taskId of the agent task to wait for (as returned/used by startAgentTask).",
+        },
+        timeoutMs: {
+          type: "number",
+          description:
+            "Maximum time to wait in milliseconds before returning with timedOut:true. Default: 1800000 (30 min).",
+        },
+        pollIntervalMs: {
+          type: "number",
+          description:
+            "How often to poll the task status in milliseconds. Default: 2000.",
+        },
+      },
+      required: ["taskId"],
+    },
+  },
+};

package/src/ai.ts

@@ -4,6 +4,7 @@ import { readFile } from "./utils";
 /** Options forwarded to startAgentTask when a generation source has an `agent` field */
 export type AgentOptions = {
   syncFs?: boolean;
+  syncRemote?: boolean;
   taskId?: string;
   maxTimeLimit?: number;
   maxSpendLimit?: number;

package/src/chat/modules/AgentModule.ts

@@ -143,6 +143,32 @@ export class AgentModule extends BaseChatModule {
           }
         },
       },
+      {
+        name: "compact",
+        description:
+          "Force the attached agent to compact (summarize) its conversation now, dropping back to a much cheaper context size",
+        modes: ["agent:attached"],
+        handler: async (_args: string[]): Promise<void> => {
+          if (!this.attachedAgent) {
+            console.log("No attached agent to compact.");
+            return;
+          }
+          if (typeof this.attachedAgent.requestCompact !== "function") {
+            console.log(
+              "This agent does not support manual compaction (remote/watcher-backed agents compact automatically)."
+            );
+            return;
+          }
+          this.attachedAgent.requestCompact();
+          // Do NOT interrupt — compaction should not cancel the in-progress
+          // tool call / AI completion. The _forceCompact flag is picked up at
+          // the compression check on the next loop iteration, once the current
+          // step finishes naturally.
+          console.log(
+            "🗜  Compaction requested — the agent will summarize and shrink its context on the next step."
+          );
+        },
+      },
       {
         name: "reasoning_effort",
         description:
@@ -654,7 +680,6 @@ export class AgentModule extends BaseChatModule {
         agentName,
         input: resumePrompt,
         messageId: session.knowhowMessageId,
-        existingKnowhowTaskId: session.knowhowTaskId,
         chatHistory: [],
         run: false, // Don't run yet, we need to set up event listeners first
       });
@@ -724,7 +749,7 @@ export class AgentModule extends BaseChatModule {
     input: string;
     messageId?: string;
     syncFs?: boolean;
-    existingKnowhowTaskId?: string;
+    syncRemote?: boolean;
     provider?: string;
     model?: string;
     maxTimeLimit?: number; // in minutes
@@ -732,6 +757,7 @@ export class AgentModule extends BaseChatModule {
     chatHistory?: ChatInteraction[];
     run?: boolean; // whether to run immediately
     taskId?: string; // optional pre-generated taskId
+    parentTaskId?: string; // taskId of the parent agent that spawned this task
   }) {
     const { input, chatHistory = [], agentName } = options;
     const agentContext = services().Agents.getAgentContext();
@@ -773,7 +799,9 @@ export class AgentModule extends BaseChatModule {
       let taskInfo: TaskInfo = {
         taskId,
         knowhowMessageId: options.messageId,
-        knowhowTaskId: options.existingKnowhowTaskId, // Use existing or will be set after creating chat task
+        // When pushing to a remote task via --sync-remote, the taskId IS the
+        // remote task ID. Otherwise it will be set after creating a chat task.
+        knowhowTaskId: options.syncRemote ? taskId : undefined,
         agentName,
         agent,
         initialInput: input,
@@ -799,8 +827,9 @@ export class AgentModule extends BaseChatModule {
         prompt: input,
         messageId: options.messageId,
         syncFs: options.syncFs,
-        existingKnowhowTaskId: options.existingKnowhowTaskId,
+        syncRemote: options.syncRemote,
         agentName,
+        parentTaskId: options.parentTaskId,
       });
 
       const webTaskId = syncer.getCreatedWebTaskId();
@@ -947,33 +976,27 @@ export class AgentModule extends BaseChatModule {
           role: "assistant",
         });
       };
-      if (agent.eventTypes.toolCall) {
-        agent.agentEvents.on(agent.eventTypes.toolCall, toolCallHandler);
-      }
-      if (agent.eventTypes.toolUsed) {
-        agent.agentEvents.on(agent.eventTypes.toolUsed, toolResultHandler);
-      }
-      if (agent.eventTypes.agentSay) {
-        agent.agentEvents.on(agent.eventTypes.agentSay, agentSayHandler);
+      // Only register these inline render listeners for the direct CLI path
+      // (options.run === true). The interactive chat / resume / attach paths
+      // call attachedAgentChatLoop -> wireAgentRendering, which registers its
+      // own keyed render listeners. Registering both would render every
+      // toolCall / toolResult / agentMessage twice.
+      if (options.run) {
+        if (agent.eventTypes.toolCall) {
+          agent.agentEvents.on(agent.eventTypes.toolCall, toolCallHandler);
+        }
+        if (agent.eventTypes.toolUsed) {
+          agent.agentEvents.on(agent.eventTypes.toolUsed, toolResultHandler);
+        }
+        if (agent.eventTypes.agentSay) {
+          agent.agentEvents.on(agent.eventTypes.agentSay, agentSayHandler);
+        }
       }
       // Track the active task on the renderer so it doesn't filter out events
       this.renderer.setActiveTaskId(taskId);
       this.activeAgentTaskId = taskId;
 
       const taskCompleted = new Promise<string>((resolve) => {
-          // Remove tool rendering listeners
-          if (agent.eventTypes.toolCall) {
-            agent.agentEvents.removeListener(agent.eventTypes.toolCall, toolCallHandler);
-          }
-          if (agent.eventTypes.toolUsed) {
-            agent.agentEvents.removeListener(agent.eventTypes.toolUsed, toolResultHandler);
-          }
-          if (agent.eventTypes.agentSay) {
-            agent.agentEvents.removeListener(agent.eventTypes.agentSay, agentSayHandler);
-          }
-          // Clear active task on renderer
-          this.renderer.setActiveTaskId(undefined);
-          this.activeAgentTaskId = undefined;
         agent.agentEvents.once(agent.eventTypes.done, async (doneMsg) => {
           console.log("🎯 [AgentModule] Task Completed");
           done = true;
@@ -994,6 +1017,19 @@ export class AgentModule extends BaseChatModule {
           );
           // Update task info
           taskInfo = this.taskRegistry.get(taskId);
+          // Remove tool rendering listeners
+          if (agent.eventTypes.toolCall) {
+            agent.agentEvents.removeListener(agent.eventTypes.toolCall, toolCallHandler);
+          }
+          if (agent.eventTypes.toolUsed) {
+            agent.agentEvents.removeListener(agent.eventTypes.toolUsed, toolResultHandler);
+          }
+          if (agent.eventTypes.agentSay) {
+            agent.agentEvents.removeListener(agent.eventTypes.agentSay, agentSayHandler);
+          }
+          // Clear active task on renderer
+          this.renderer.setActiveTaskId(undefined);
+          this.activeAgentTaskId = undefined;
 
           // Wait for AgentSync to finish before resolving
           await syncer.waitForFinalization();
@@ -1092,6 +1128,7 @@ export class AgentModule extends BaseChatModule {
     threads: Message[][];
     messageId?: string;
     taskId?: string;
+    interactive?: boolean;
   }): Promise<{ taskCompleted: Promise<string> }> {
     const { agentName, input, threads, messageId, taskId } = options;
 
@@ -1147,11 +1184,36 @@ export class AgentModule extends BaseChatModule {
       agentName,
       input: resumePrompt,
       messageId,
-      existingKnowhowTaskId: taskId,
+      taskId,
+      // When resuming a remote task (no messageId), keep pushing work to the
+      // remote task identified by taskId.
+      syncRemote: !messageId && !!taskId,
       run: false,
     });
 
-    // Start agent with prior messages as context
+    // Interactive (chat REPL) resume: route through the attached chat loop so the
+    // renderer is wired the same way as a normal chat interaction / /attach, and
+    // the user gets agent:attached mode commands (/poke, /detach, /kill, /logs).
+    if (options.interactive) {
+      await this.attachedAgentChatLoop(
+        result.taskId,
+        result.agent,
+        resumePrompt,
+        resumeMessages
+      );
+      return { taskCompleted: result.taskCompleted };
+    }
+
+    // Non-interactive (headless CLI `knowhow agent --resume`) path: setupAgent was
+    // called with run:false, so no inline render listeners were registered. Wire
+    // rendering here (same keyed listeners as attachedAgentChatLoop) so the CLI
+    // still shows the agent's messages / tool calls, then start the agent.
+    this.wireAgentRendering(
+      result.taskId,
+      result.agent.agentEvents,
+      result.agent.eventTypes,
+      result.agent.name
+    );
     result.agent.call(resumePrompt, resumeMessages);
 
     return { taskCompleted: result.taskCompleted };

package/src/chat/modules/SessionsModule.ts

@@ -395,6 +395,7 @@ export class SessionsModule extends BaseChatModule {
             taskId: id,
             threads: normalizedThreads,
             input: additionalContext?.trim() || initialInput || "",
+            interactive: true,
           });
           return;
         } catch (e: any) {
@@ -770,18 +771,15 @@ export class SessionsModule extends BaseChatModule {
     await watcher.startWatching(taskId);
     this.agentModule.setActiveSyncedWatcher(watcher);
 
-    // Wire rendering via AgentModule utility (handles cleanup on detach)
-    this.agentModule.wireAgentRendering(taskId, watcher.agentEvents, watcher.eventTypes, watcher.agentName);
-    watcher.agentEvents.once(watcher.eventTypes.done, (output) => {
-      console.log(Marked.parse(output));
-    });
-
     const context = this.chatService?.getContext();
     if (context) context.activeAgentTaskId = taskId;
 
     console.log(`📁 Attached to filesystem agent: ${taskId}`);
 
     // Enter interactive loop — this sets mode to "agent:attached" and blocks until detach/done/kill
+    // attachedAgentChatLoop calls wireAgentRendering internally — do NOT call it here too,
+    // otherwise two sets of listeners are registered and output is doubled (or, after detach,
+    // the wrong agentEvents object holds the listeners).
     const fsWatcherAgent = new WatcherBackedAgent(watcher);
     await this.agentModule.attachedAgentChatLoop(taskId, fsWatcherAgent);
   }
@@ -811,15 +809,13 @@ export class SessionsModule extends BaseChatModule {
     await watcher.startWatching(taskId);
     this.agentModule.setActiveSyncedWatcher(watcher);
 
-    // Wire rendering via AgentModule utility (handles cleanup on detach)
-    this.agentModule.wireAgentRendering(taskId, watcher.agentEvents, watcher.eventTypes, watcher.agentName);
-
     const context = this.chatService?.getContext();
     if (context) context.activeAgentTaskId = taskId;
 
     console.log(`🌐 Attached to web agent: ${taskId}`);
 
-    // Enter interactive loop — this sets mode to "agent:attached" and blocks until detach/done/kill
+    // Enter interactive loop — wireAgentRendering is called inside attachedAgentChatLoop.
+    // Do NOT call it here too (would double-register listeners).
     const webWatcherAgent = new WatcherBackedAgent(watcher);
     await this.agentModule.attachedAgentChatLoop(taskId, webWatcherAgent);
   }

package/src/clients/contextLimits.ts

@@ -86,6 +86,9 @@ export const ContextLimits: Record<string, number> = {
   // ─── Anthropic ────────────────────────────────────────────────────────────
   [Models.anthropic.Opus4_8Fast]: 1_000_000,
   [Models.anthropic.Opus4_8]: 1_000_000,
+  // Claude Opus 5 (launched 2026-06-09, 1M context window)
+  [Models.anthropic.Opus5]: 1_000_000,
+  [Models.anthropic.Opus5Fast]: 1_000_000,
   // Claude 5 generation (launched 2026-06-09, 1M context window)
   [Models.anthropic.Fable5]: 1_000_000,
   [Models.anthropic.Sonnet5]: 1_000_000,
@@ -101,6 +104,10 @@ export const ContextLimits: Record<string, number> = {
   [Models.anthropic.Sonnet4]: 200_000,
   [Models.anthropic.Sonnet4_5]: 200_000,
   [Models.anthropic.Haiku4_5]: 200_000,
+  // Short aliases (resolve to their latest dated version)
+  [Models.anthropic.Sonnet4_5Short]: 200_000,
+  [Models.anthropic.Haiku4_5Short]: 200_000,
+  [Models.anthropic.Opus4_5Short]: 1_000_000,
   [Models.anthropic.Sonnet3_7]: 200_000,
   [Models.anthropic.Sonnet3_5]: 200_000,
   [Models.anthropic.Opus3]: 200_000,
@@ -115,6 +122,20 @@ export const ContextLimits: Record<string, number> = {
   [Models.anthropic.Sonnet4_0]: 200_000,
 
   // ─── Google ───────────────────────────────────────────────────────────────
+  // Gemini 3.6 / 3.5 (text)
+  [Models.google.Gemini_36_Flash]: 1_000_000,
+  [Models.google.Gemini_35_Flash]: 1_000_000,
+  [Models.google.Gemini_35_Flash_Lite]: 1_000_000,
+  [Models.google.Gemini_35_Live_Translate_Preview]: 1_000_000,
+  // Gemini 3.x (text / multimodal reasoning)
+  [Models.google.Gemini_31_Flash_Lite]: 1_000_000,
+  [Models.google.Gemini_31_Flash_TTS_Preview]: 1_000_000,
+  [Models.google.Gemini_3_Pro_Preview]: 1_000_000,
+  [Models.google.Gemini_Omni_Flash_Preview]: 1_000_000,
+  [Models.google.Gemini_25_Computer_Use_Preview]: 1_000_000,
+  [Models.google.Gemini_20_Flash_Lite]: 1_000_000,
+  [Models.google.Gemini_Robotics_ER_16_Preview]: 1_000_000,
+  [Models.google.Gemini_Robotics_ER_15_Preview]: 1_000_000,
   [Models.google.Gemini_31_Pro_Preview]: 1_000_000,
   [Models.google.Gemini_31_Flash_Image_Preview]: 1_000_000,
   [Models.google.Gemini_31_Flash_Lite_Preview]: 1_000_000,
@@ -142,6 +163,11 @@ export const ContextLimits: Record<string, number> = {
   [Models.google.Veo_3_Fast]: 0,
   [Models.google.Veo_3_1]: 0,
   [Models.google.Veo_3_1_Fast]: 0,
+  [Models.google.Veo_3_1_Lite]: 0,
+  // Google image generation models — no text context window; use 0
+  [Models.google.Gemini_31_Flash_Image]: 0,
+  [Models.google.Gemini_31_Flash_Lite_Image]: 0,
+  [Models.google.Gemini_3_Pro_Image]: 0,
   [Models.google.Gemini_20_Flash]: 1_000_000,
   [Models.google.Gemini_20_Flash_Preview_Image_Generation]: 1_000_000,
   [Models.google.Gemini_20_Flash_Live]: 1_000_000,

package/src/clients/pricing/anthropic.ts

@@ -20,6 +20,8 @@ export const AnthropicModels = {
   Sonnet5:   "claude-sonnet-5",
   Mythos5:   "claude-mythos-5",
   MythosPreview: "claude-mythos-preview",
+  Opus5:     "claude-opus-5",
+  Opus5Fast: "claude-opus-5-fast",
   Opus4_8:   "claude-opus-4-8",
   Opus4_8Fast: "claude-opus-4-8-fast",
   Opus4_7:   "claude-opus-4-7",
@@ -52,6 +54,7 @@ export const AnthropicTextModels: string[] = [
   AnthropicModels.Opus4_8,
   AnthropicModels.Fable5,
   AnthropicModels.Sonnet5,
+  AnthropicModels.Opus5,
   AnthropicModels.Opus4_7,
   AnthropicModels.Opus4_6,
   AnthropicModels.Sonnet4_6,
@@ -64,6 +67,7 @@ export const AnthropicTextModels: string[] = [
 // Models in our catalog but not yet publicly available
 export const AnthropicLimitedAvailabilityModels: string[] = [
   AnthropicModels.Opus4_8Fast, // fast mode pricing
+  AnthropicModels.Opus5Fast,   // fast mode pricing (research preview)
   AnthropicModels.Mythos5,     // invitation-only (Project Glasswing)
   AnthropicModels.MythosPreview, // invitation-only (defensive cybersecurity)
   AnthropicModels.Opus4_6Fast, // 404 – not publicly available yet
@@ -74,6 +78,11 @@ export const AnthropicLimitedAvailabilityModels: string[] = [
 const AnthropicAllModels: string[] = [
   ...AnthropicTextModels,
   ...AnthropicLimitedAvailabilityModels,
+  // Short aliases (resolve to their latest dated version) — kept in the catalog
+  // so cost tracking works whether the user passes the alias or the dated id.
+  AnthropicModels.Sonnet4_5Short,
+  AnthropicModels.Haiku4_5Short,
+  AnthropicModels.Opus4_5Short,
   // Deprecated (retirement 2026-06-15)
   AnthropicModels.Opus4,
   AnthropicModels.Sonnet4,
@@ -95,6 +104,9 @@ const AnthropicAllModels: string[] = [
 export const AnthropicTextPricing: Record<string, ModelPricing> = {
   [AnthropicModels.Opus4_8]:   { input: 5.0,  cache_write: 6.25,   cache_hit: 0.5,  output: 25.0 },
   [AnthropicModels.Opus4_8Fast]: { input: 10.0, cache_write: 12.5,  cache_hit: 1.0,  output: 50.0, limitedAvailability: true },
+  // Claude Opus 5 (launched 2026-06-09) — recommended for complex agentic coding
+  [AnthropicModels.Opus5]:     { input: 5.0,  cache_write: 6.25,   cache_hit: 0.5,  output: 25.0 },
+  [AnthropicModels.Opus5Fast]: { input: 10.0, cache_write: 12.5,   cache_hit: 1.0,  output: 50.0, limitedAvailability: true },
   // Claude 5 generation (launched 2026-06-09)
   [AnthropicModels.Fable5]:    { input: 10.0, cache_write: 12.5,   cache_hit: 1.0,  output: 50.0 },
   [AnthropicModels.Sonnet5]:   { input: 3.0,  cache_write: 3.75,   cache_hit: 0.3,  output: 15.0 },

package/src/commands/agent.ts

@@ -67,6 +67,10 @@ export function addAgentCommand(program: Command, getChatService: () => any): vo
     )
     .option("--message-id <messageId>", "Knowhow message ID for task tracking")
     .option("--sync-fs", "Enable filesystem-based synchronization")
+    .option(
+      "--sync-remote",
+      "Push this agent's work to a remote Knowhow task identified by --task-id (creates one if --message-id is given)"
+    )
     .option(
       "--behavior-id <id>",
       "Force a specific behavior by its ID (skips trigger matching)"
@@ -79,6 +83,10 @@ export function addAgentCommand(program: Command, getChatService: () => any): vo
       "--task-id <taskId>",
       "Pre-generated task ID (used with --sync-fs for predictable agent directory path)"
     )
+    .option(
+      "--parent-task-id <taskId>",
+      "The taskId of the parent agent that spawned this task (for reporting back)"
+    )
     .option("--prompt-file <path>", "Custom prompt template file with {text}")
     .option("--input <text>", "Task input (fallback to stdin if not provided)")
     .option(
@@ -139,6 +147,20 @@ export function addAgentCommand(program: Command, getChatService: () => any): vo
           process.exit(1);
         }
 
+        // If this agent was spawned by a parent agent, inject a note into its
+        // prompt so it knows it has a parent it can communicate with — regardless
+        // of how it was launched. This is idempotent: startAgentTask no longer
+        // adds the parent line itself, so this is the single source of truth.
+        if (options.parentTaskId) {
+          input =
+            input +
+            `\n\n---\n` +
+            `PARENT AGENT: You were spawned by a parent agent (task "${options.parentTaskId}"). ` +
+            `Use the \`replyToParent\` tool to report progress, ask questions, or send your final result back to it. ` +
+            `The parent may also send you follow-up messages via your input.txt.\n` +
+            `---\n`;
+        }
+
         await agentModule.initialize(chatService);
 
         // Match a behavior from local disk (.knowhow/behaviors/)