@dench.com/cli 0.3.7 → 0.3.8

package/README.md

@@ -195,11 +195,14 @@ dench crm entries list people
 
 Auth precedence:
 
-1. `--dev` flag → use the dev workspace env (`NEXT_PUBLIC_CONVEX_URL`,
+1. Explicit `--dev` flag → use the dev workspace env (`NEXT_PUBLIC_CONVEX_URL`,
    `DENCH_WORKSPACE`, `DENCH_DEV_AGENT_KEY`).
 2. A locally-stored `dench login` session for the current host.
 3. `DENCH_API_KEY` + `CONVEX_URL` (sandbox / automation path).
-4. `--dev`-style env vars (without the flag).
+
+Plain terminal usage does not silently fall back to dev env vars. Without
+`--dev`, a saved session, or `DENCH_API_KEY` + `CONVEX_URL`, live commands
+return `login_required`.
 
 Commands that need to impersonate a specific agent (`dench memory`,
 `dench task`, `dench claim`, `dench log`, `dench approval request`,

package/agent.ts

@@ -34,6 +34,20 @@ type CliCtx = {
   convex: ConvexHttpClient;
   args: string[];
   jsonOutput: boolean;
+  /**
+   * Bearer token forwarded by the dispatcher in `cli/dench.ts`. Either a
+   * `dch_agent_*` agent session minted by `dench login` or a unified
+   * Dench API key (`DENCH_API_KEY`) when the CLI is running inside a
+   * sandbox. Used by `runAwait` to authenticate against
+   * `runs:getChildRunStatusForCli`.
+   */
+  sessionToken?: string;
+  /**
+   * Convex `runs._id` of the caller's own run, when authenticated via
+   * an API key (sandbox path). Required by `getChildRunStatusForCli`
+   * to scope the API key's reach to a specific organization.
+   */
+  callerRunId?: string;
 };
 
 // Args helpers moved to cli/lib/cli-args.ts; we adapt shift to throw
@@ -137,10 +151,18 @@ async function postJson(
 export async function runAgentCommand(opts: {
   convex: ConvexHttpClient;
   args: string[];
+  sessionToken?: string;
+  callerRunId?: string;
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
-  const ctx: CliCtx = { convex: opts.convex, args, jsonOutput };
+  const ctx: CliCtx = {
+    convex: opts.convex,
+    args,
+    jsonOutput,
+    sessionToken: opts.sessionToken,
+    callerRunId: opts.callerRunId,
+  };
   const subcommand = args.shift();
   if (!subcommand || subcommand === "help" || subcommand === "--help") {
     agentHelp();
@@ -243,27 +265,81 @@ async function runAwait(ctx: CliCtx): Promise<void> {
       "dench agent await requires --hook <token> or --children <csv>",
     );
   }
-  // Polling fallback: subscribe to runs via Convex realtime would be the
-  // proper implementation; for v1 we poll status fields every 2s.
-  const childIds = childIdsCsv.split(",").map((id) => id.trim()).filter(Boolean);
-  const completed: Record<string, string> = {};
+  if (!ctx.sessionToken) {
+    throw new AgentCliError(
+      "dench agent await --children needs an authenticated session " +
+        "(run `dench login`, or set DENCH_API_KEY in a sandbox)",
+    );
+  }
+
+  const childIds = childIdsCsv
+    .split(",")
+    .map((id) => id.trim())
+    .filter(Boolean);
+  if (childIds.length === 0) {
+    throw new AgentCliError("--children requires at least one run id");
+  }
   const start = Date.now();
   const timeoutMs = parseInt(
     getFlag(ctx.args, "--timeout-ms") ?? "3600000",
     10,
   );
+  const intervalMs = parseInt(
+    getFlag(ctx.args, "--interval-ms") ?? "2000",
+    10,
+  );
+
+  type ChildSnapshot = {
+    runId: string;
+    status: string;
+    summary: string | null;
+    threadId: string | null;
+    terminal: boolean;
+  };
+  const getStatus = makeFunctionReference<"query">(
+    "functions/runs:getChildRunStatusForCli",
+  );
+
+  // Poll each child's status until it reaches a terminal state. The
+  // server uses sessionToken auth (mirrors `dench chat list`) so this
+  // works both for `dch_agent_*` sessions (local dev) and for unified
+  // `DENCH_API_KEY`s (sandbox, must include `--caller-run-id`).
+  const completed: Record<string, ChildSnapshot> = {};
   while (Object.keys(completed).length < childIds.length) {
     if (Date.now() - start > timeoutMs) {
-      throw new AgentCliError("dench agent await timed out");
+      throw new AgentCliError(
+        `dench agent await timed out after ${timeoutMs}ms with ${
+          Object.keys(completed).length
+        }/${childIds.length} children completed`,
+      );
     }
     for (const childId of childIds) {
       if (completed[childId]) continue;
-      // Reading status requires a query; for v1 use a tight loop on the
-      // public runs.getRun. (Wired in P5 once DenchClient lands.)
-      completed[childId] = "pending";
+      try {
+        const snap = (await ctx.convex.query(getStatus, {
+          sessionToken: ctx.sessionToken,
+          runId: ctx.callerRunId ?? undefined,
+          childRunId: childId as never,
+        })) as ChildSnapshot | null;
+        if (snap?.terminal) {
+          completed[childId] = snap;
+        }
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        // Treat "not found" / access errors as terminal-with-error so
+        // we don't poll forever on a typo'd id.
+        completed[childId] = {
+          runId: childId,
+          status: "error",
+          summary: msg,
+          threadId: null,
+          terminal: true,
+        };
+      }
+    }
+    if (Object.keys(completed).length < childIds.length) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
-    await new Promise((resolve) => setTimeout(resolve, 2000));
-    break; // v1 polling stub — placeholder
   }
   out(ctx, { children: completed });
 }
@@ -367,12 +443,18 @@ function agentHelp(): void {
 Spawn a chat-turn workflow (same as the web UI's chat panel):
   dench agent new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
   dench agent send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
-  These are aliases for \`dench chat new\` / \`dench chat send\`.
+  dench agent follow <thread-id> [--json]
+  These are aliases for \`dench chat new\` / \`dench chat send\` / \`dench chat follow\`.
+  Use \`follow\` to tail the live stream of an existing thread (e.g.
+  a subagent spawned by \`spawn_agent\`) without sending a new message.
 
 Subagents (autonomous Long Sessions, NOT chat threads):
   dench agent spawn '<goal>' [--parent-run-id <id>] [--sandbox own|share_parent] [--time-budget-ms N]
   dench agent await --hook <token>
-  dench agent await --children id1,id2,id3 [--timeout-ms N]
+  dench agent await --children id1,id2,id3 [--timeout-ms N] [--interval-ms N]
+                                            (polls runs:getChildRunStatusForCli
+                                             with the active session token until
+                                             every child is terminal)
 
 Peer messaging:
   dench agent message <toRunId> '<text...>' [--from-run-id <id>]

package/chat-spawn.ts

@@ -87,21 +87,47 @@ function buildSpawnUrl(host: string): string {
   return `${host.replace(/\/+$/, "")}/api/chat/cli`;
 }
 
-function buildStreamUrl(host: string, runId: string): string {
+function buildStreamUrlByRunId(host: string, runId: string): string {
   return `${host.replace(/\/+$/, "")}/api/chat/${encodeURIComponent(runId)}/stream`;
 }
 
+function buildStreamUrlByThreadId(host: string, threadId: string): string {
+  return `${host.replace(/\/+$/, "")}/api/chat/stream?sessionId=${encodeURIComponent(threadId)}`;
+}
+
 /**
  * Subscribe to the durable chat stream and pretty-print useful chunks
  * until the stream closes. Mirrors the chunk types the chat panel
  * cares about (text deltas, reasoning, tool input/output, finish).
+ *
+ * Resolves the stream URL from EITHER:
+ *   - `runId` (Workflow SDK run id, returned in `x-workflow-run-id`
+ *     by `POST /api/chat/cli`), via `/api/chat/[runId]/stream`, OR
+ *   - `threadId` (Convex `chatThreads._id`), via
+ *     `/api/chat/stream?sessionId=...` which resolves the active run
+ *     by following `chatThreads.activeRunId → runs.workflowRunId`.
+ *
+ * The thread-id path is what `dench chat follow <threadId>` uses, so
+ * we can tail any live thread (including a subagent created by
+ * `spawn_agent`) without needing to know its workflow run id ahead of
+ * time.
  */
 async function followStream(args: {
   host: string;
   bearerToken: string;
-  runId: string;
+  runId?: string;
+  threadId?: string;
 }): Promise<void> {
-  const url = buildStreamUrl(args.host, args.runId);
+  const url = args.runId
+    ? buildStreamUrlByRunId(args.host, args.runId)
+    : args.threadId
+      ? buildStreamUrlByThreadId(args.host, args.threadId)
+      : null;
+  if (!url) {
+    throw new ChatSpawnError(
+      "followStream requires either { runId } or { threadId }",
+    );
+  }
   const response = await fetch(url, {
     method: "GET",
     headers: {
@@ -342,6 +368,37 @@ async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
   }
 }
 
+/**
+ * `dench chat follow <threadId>` — tail the live stream of an
+ * existing chat thread by Convex thread id.
+ *
+ * Useful for watching a subagent (a child thread spawned by a parent
+ * via `spawn_agent`) live, or for resuming the stream of any chat
+ * thread that's currently in flight. Resolves the active workflow run
+ * server-side via `chatThreads.activeRunId → runs.workflowRunId`, so
+ * the caller doesn't need to know any workflow ids.
+ *
+ * Exits when the stream closes (workflow finishes) or when the user
+ * hits Ctrl-C.
+ */
+async function runChatFollow(ctx: ChatSpawnContext): Promise<void> {
+  const positionals = ctx.args.filter((arg) => !arg.startsWith("--"));
+  const threadId = positionals.shift();
+  if (!threadId) {
+    throw new ChatSpawnError(
+      "Usage: dench chat follow <threadId> [--json]",
+    );
+  }
+  if (!ctx.jsonOutput) {
+    console.error(`--- following stream for thread ${threadId} ---`);
+  }
+  await followStream({
+    host: ctx.runtime.host,
+    bearerToken: ctx.runtime.bearerToken,
+    threadId,
+  });
+}
+
 /**
  * Public entry point invoked by the chat dispatcher in cli/dench.ts
  * (and the agent dispatcher when the user runs `dench agent new` /
@@ -351,7 +408,7 @@ async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
 export async function runChatSpawnCommand(opts: {
   runtime: RuntimeBundle;
   args: string[];
-  subcommand: "new" | "send";
+  subcommand: "new" | "send" | "follow";
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
@@ -364,6 +421,10 @@ export async function runChatSpawnCommand(opts: {
     await runChatNew(ctx);
     return;
   }
+  if (opts.subcommand === "follow") {
+    await runChatFollow(ctx);
+    return;
+  }
   await runChatSend(ctx);
 }
 

package/chat.ts

@@ -111,7 +111,12 @@ Read messages from a specific past chat thread:
 Spawn a new chat-turn workflow (same agent loop as the web UI):
   dench chat new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
   dench chat send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
-  Aliased as: dench agent new / dench agent send.
+  dench chat follow <thread-id> [--json]
+  dench chat tree [<root-thread-id>] [--limit N] [--json]
+  Aliased as: dench agent new / dench agent send / dench agent follow.
+  Use \`follow\` to tail any live thread by id (e.g. a subagent
+  spawned by another chat). Use \`tree\` to print the parent-child
+  thread hierarchy from a root thread.
 
 Approval policy:
   Without --yolo the workflow uses the workspace policy from
@@ -156,6 +161,8 @@ export async function runChatCommand(opts: {
       return await runChatSearchCommand(ctx);
     case "read":
       return await runChatReadCommand(ctx);
+    case "tree":
+      return await runChatTreeCommand(ctx);
     default:
       throw new ChatCliError(`Unknown chat subcommand: ${subcommand}`);
   }
@@ -214,3 +221,129 @@ async function runChatReadCommand(ctx: ChatCliContext): Promise<void> {
     }),
   );
 }
+
+/**
+ * `dench chat tree [<root-thread-id>] [--limit N] [--json]` — print the
+ * parent-child chat thread hierarchy rooted at the given thread (or
+ * roots = top-level chats if no id is passed).
+ *
+ * Uses `listPastChats` (which already includes nested threads in its
+ * results — `topLevelOnly` is a `listThreads`-only knob) and groups
+ * client-side by `parentThreadId`. With `--json`, prints the raw flat
+ * array; otherwise prints an indented tree with status + a short
+ * summary excerpt for each row.
+ */
+async function runChatTreeCommand(ctx: ChatCliContext): Promise<void> {
+  // Strip flag values from positionals so e.g. `tree --limit 30` doesn't
+  // misinterpret "30" as the rootThreadId. We treat "--key value" as a
+  // pair iff value doesn't itself start with "--".
+  const positionals: string[] = [];
+  for (let i = 0; i < ctx.args.length; i++) {
+    const arg = ctx.args[i];
+    if (arg.startsWith("--")) {
+      const next = ctx.args[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        i += 1; // skip the flag value
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+  const rootThreadId = positionals[0]?.trim() || undefined;
+  const limit = parseLimit(getFlag(ctx.args, "--limit")) ?? 200;
+
+  const flat = (await callQuery(ctx, api.listPastChats, {
+    limit,
+    includeArchived: false,
+  })) as Array<{
+    threadId: string;
+    title: string;
+    status: string;
+    parentThreadId: string | null;
+    nestingDepth: number | null;
+    summary: string | null;
+    lastMessageAt: number;
+    createdAt: number;
+    activeRunId: string | null;
+  }>;
+
+  if (ctx.jsonOutput) {
+    out(ctx, flat);
+    return;
+  }
+
+  // Group by parent. Top-level rows = either no parent, or parent
+  // outside the loaded set (so we don't silently swallow children
+  // whose parent fell off the limit window).
+  const ids = new Set(flat.map((t) => t.threadId));
+  const childrenByParent = new Map<string, typeof flat>();
+  const roots: typeof flat = [];
+  for (const thread of flat) {
+    if (thread.parentThreadId && ids.has(thread.parentThreadId)) {
+      let list = childrenByParent.get(thread.parentThreadId);
+      if (!list) {
+        list = [];
+        childrenByParent.set(thread.parentThreadId, list);
+      }
+      list.push(thread);
+      continue;
+    }
+    if (rootThreadId) {
+      if (thread.threadId === rootThreadId) roots.push(thread);
+    } else {
+      roots.push(thread);
+    }
+  }
+  // When the user passed an explicit `rootThreadId` but it didn't
+  // appear in the loaded set (e.g. it sits beyond `--limit`), pull
+  // it on its own so we still surface it as the single root.
+  if (rootThreadId && roots.length === 0) {
+    const explicit = flat.find((t) => t.threadId === rootThreadId);
+    if (explicit) roots.push(explicit);
+  }
+  // Sort children oldest-first within each parent (spawn order),
+  // roots newest-first (most recent root at the top).
+  for (const list of childrenByParent.values()) {
+    list.sort((a, b) => (a.createdAt || a.lastMessageAt) - (b.createdAt || b.lastMessageAt));
+  }
+  roots.sort((a, b) => b.lastMessageAt - a.lastMessageAt);
+
+  if (roots.length === 0) {
+    if (rootThreadId) {
+      console.error(
+        `No thread found with id ${rootThreadId} (or it's outside the limit ` +
+          `${limit} window — increase --limit).`,
+      );
+    } else {
+      console.error("No chat threads in this workspace yet.");
+    }
+    return;
+  }
+
+  const stripe = (s: string, n: number) =>
+    s.length > n ? `${s.slice(0, n - 1)}…` : s;
+  const print = (thread: (typeof flat)[number], depth: number): void => {
+    const indent = "  ".repeat(depth);
+    const branch = depth > 0 ? "└─ " : "";
+    const status =
+      thread.status === "streaming"
+        ? "▸ running"
+        : thread.status === "error"
+          ? "✗ error"
+          : thread.summary
+            ? "✓ done"
+            : "·";
+    process.stdout.write(
+      `${indent}${branch}[${status}] ${stripe(thread.title || "Untitled", 60)}  ` +
+        `(${thread.threadId})\n`,
+    );
+    if (thread.summary) {
+      process.stdout.write(
+        `${indent}${depth > 0 ? "   " : ""}${stripe(thread.summary.replace(/\s+/g, " "), 80)}\n`,
+      );
+    }
+    const direct = childrenByParent.get(thread.threadId) ?? [];
+    for (const child of direct) print(child, depth + 1);
+  };
+  for (const root of roots) print(root, 0);
+}

package/dench.ts

@@ -327,6 +327,41 @@ function throwIfCliError(value: unknown) {
   }
 }
 
+function normalizeCliError(error: unknown): CliError {
+  if (error instanceof CliError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("Invalid dev agent key")) {
+    return new CliError("Invalid dev agent key", {
+      code: "invalid_dev_agent_key",
+      nextActions: [
+        "Check that DENCH_DEV_AGENT_KEY in your shell matches the Convex deployment env.",
+        "Use --dev only for a local/dev Convex deployment configured with that key.",
+        "For normal terminal usage, run dench login or set DENCH_API_KEY + CONVEX_URL.",
+      ],
+    });
+  }
+  if (message.includes("Dev CRM access is disabled in production")) {
+    return new CliError("Dev CRM access is disabled in production", {
+      code: "dev_access_disabled",
+      nextActions: [
+        "Remove --dev and run dench login for terminal access.",
+        "Or use DENCH_API_KEY + CONVEX_URL for sandbox/automation access.",
+      ],
+    });
+  }
+  if (message.includes("Invalid Dench API key")) {
+    return new CliError("Invalid Dench API key", {
+      code: "invalid_api_key",
+      nextActions: [
+        "Check DENCH_API_KEY and CONVEX_URL point to the same organization/deployment.",
+        "Unset DENCH_API_KEY to use a saved dench login session instead.",
+        "Or run dench login to create a new terminal session.",
+      ],
+    });
+  }
+  return new CliError(message);
+}
+
 function parseJsonObjectOption(name: string) {
   const raw = option(name);
   if (!raw) return {};
@@ -461,8 +496,12 @@ Past chat threads (own + shared in this workspace):
 Spawn a new chat-turn workflow (same as the web UI):
   dench chat new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
   dench chat send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
-  dench agent new ...    (alias for dench chat new)
-  dench agent send ...   (alias for dench chat send)
+  dench chat follow <thread-id> [--json]            (tail a live thread by id)
+  dench chat tree [<root-thread-id>] [--limit N] [--json]
+                                                    (parent-child thread tree)
+  dench agent new ...     (alias for dench chat new)
+  dench agent send ...    (alias for dench chat send)
+  dench agent follow ...  (alias for dench chat follow)
 
   Help: dench chat help
 
@@ -1755,6 +1794,30 @@ async function getRuntime() {
       });
     }
 
+    // Sandbox session-mode path: workflow minting provisions a real
+    // dch_agent_* token at sandbox-create time. Prefer it over apiKey so
+    // agentWorkspace.* commands (Composio tools) work inside sandboxes.
+    const sandboxAgentToken = process.env.DENCH_AGENT_SESSION_TOKEN?.trim();
+    const sandboxConvexUrl = resolveApiKeyConvexUrl();
+    if (sandboxAgentToken && sandboxConvexUrl) {
+      const orgId = process.env.DENCH_ORG_ID?.trim();
+      const orgSlug = process.env.DENCH_ORG_SLUG?.trim();
+      const apiHost =
+        process.env.DENCH_API_URL?.trim() ||
+        process.env.DENCH_INTERNAL_BASE?.trim() ||
+        host;
+      return {
+        mode: "session" as const,
+        host: apiHost,
+        client: new ConvexHttpClient(sandboxConvexUrl),
+        sessionToken: sandboxAgentToken,
+        organization:
+          orgId && orgSlug
+            ? { id: orgId, name: orgSlug, slug: orgSlug }
+            : undefined,
+      };
+    }
+
     // Sandbox / automation path: the unified Dench API key + Convex URL
     // baked into sandbox envVars (see
     // src/lib/secrets/sandbox-tokens.ts) is enough to drive every
@@ -1781,10 +1844,12 @@ async function getRuntime() {
             : undefined,
       };
     }
+
+    throw loginRequiredError();
   }
 
   if (!hasDevEnv()) {
-    throw hasFlag("--dev") ? missingDevEnvError() : loginRequiredError();
+    throw missingDevEnvError();
   }
 
   return {
@@ -1799,6 +1864,22 @@ async function getRuntime() {
 
 type Runtime = Awaited<ReturnType<typeof getRuntime>>;
 
+function stripRuntimeFlags(args: string[]) {
+  const booleanFlags = new Set(["--dev", "--prod", "--staging"]);
+  const valueFlags = new Set(["--convex-url", "--host"]);
+  const stripped: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (booleanFlags.has(arg)) continue;
+    if (valueFlags.has(arg)) {
+      i++;
+      continue;
+    }
+    stripped.push(arg);
+  }
+  return stripped;
+}
+
 /**
  * `session` mode is required for `agentWorkspace.*` calls because they
  * gate on `validateAgentSession` server-side, which only accepts the
@@ -1837,6 +1918,13 @@ function requireAuthenticatedRuntime(
   throw loginRequiredError(command);
 }
 
+function encodeDevCrmSessionToken(args: {
+  workspaceSlug: string;
+  devKey: string;
+}) {
+  return `dch_dev_${encodeURIComponent(args.workspaceSlug)}:${encodeURIComponent(args.devKey)}`;
+}
+
 function agentSessionRequiredError(command: string) {
   return new CliError(
     `${command} requires an agent session — DENCH_API_KEY is org-scoped and cannot impersonate a specific agent`,
@@ -3458,7 +3546,7 @@ async function main() {
   }
 
   if (command === "crm") {
-    const subArgs = args.slice(args.indexOf("crm") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("crm") + 1));
     const sub = subArgs[0];
     // Short-circuit help so users don't need a session to read the
     // surface. The crm dispatcher's own help resolves --json + the
@@ -3478,6 +3566,14 @@ async function main() {
     // (`DENCH_API_KEY` baked into sandbox envVars). Server-side
     // `requireCrmAccess` (convex/lib/crm/access.ts) dispatches on the
     // bearer prefix and resolves the org for both.
+    if (runtime.mode === "dev") {
+      await runCrmCommand({
+        convex: runtime.client,
+        args: subArgs,
+        sessionToken: encodeDevCrmSessionToken(runtime.workspaceArgs),
+      });
+      return;
+    }
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench crm");
     await runCrmCommand({
       convex: authedRuntime.client,
@@ -3534,12 +3630,13 @@ async function main() {
       await runChatCommand({ convex: {} as any, args: subArgs });
       return;
     }
-    // `chat new` / `chat send` spawn a chat-turn workflow via
-    // /api/chat/cli (the same workflow the web UI uses). They need
-    // an HTTP host + bearer token, not a Convex client. The
-    // remaining subcommands (list / search / read) are Convex
-    // queries and keep going through `runChatCommand`.
-    if (sub === "new" || sub === "send") {
+    // `chat new` / `chat send` / `chat follow` use HTTP routes
+    // (/api/chat/cli for spawn, /api/chat/[runId]/stream and
+    // /api/chat/stream for follow) so they need an authenticated host
+    // + bearer token, not a Convex client. The remaining subcommands
+    // (list / search / read / tree) are Convex queries and keep going
+    // through `runChatCommand`.
+    if (sub === "new" || sub === "send" || sub === "follow") {
       const { runChatSpawnCommand } = await import("./chat-spawn");
       const runtime = await getRuntime();
       const authedRuntime = requireAuthenticatedRuntime(
@@ -3583,11 +3680,12 @@ async function main() {
       await runAgentCommand({ convex: {} as any, args: subArgs });
       return;
     }
-    // Aliases: `dench agent new` / `dench agent send` -> the chat-spawn
-    // implementation. Surfaced under `agent` so users who associate
-    // chat threads with the agent surface still find them; the actual
-    // workflow is identical to `dench chat new` / `dench chat send`.
-    if (sub === "new" || sub === "send") {
+    // Aliases: `dench agent new` / `dench agent send` / `dench agent
+    // follow` -> the chat-spawn implementation. Surfaced under
+    // `agent` so users who associate chat threads with the agent
+    // surface still find them; the actual workflow is identical to
+    // `dench chat new` / `dench chat send` / `dench chat follow`.
+    if (sub === "new" || sub === "send" || sub === "follow") {
       const { runChatSpawnCommand } = await import("./chat-spawn");
       const runtime = await getRuntime();
       const authedRuntime = requireAuthenticatedRuntime(
@@ -3609,6 +3707,8 @@ async function main() {
     await runAgentCommand({
       convex: runtime.client,
       args: subArgs,
+      sessionToken: runtime.sessionToken,
+      callerRunId: process.env.DENCH_RUN_ID?.trim() || undefined,
     });
     return;
   }
@@ -4237,11 +4337,12 @@ async function main() {
 }
 
 main().catch((error) => {
-  const extra = error instanceof CliError ? error.payload : {};
+  const normalized = normalizeCliError(error);
+  const extra = normalized.payload;
   const payload: JsonRecord = {
     ok: false,
     ...extra,
-    error: error instanceof Error ? error.message : String(error),
+    error: normalized.message,
   };
   if (json) {
     console.error(JSON.stringify(payload, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {