refactor(cli): deduplicate command options between top-level and agent subcommands

Extract addXxxOptions() builder functions for all 9 shared commands
(ls, run, attach, logs, stop, delete, send, inspect, wait) so both
paseo <cmd> and paseo agent <cmd> use a single source of truth.

Fixes drift where agent subcommands were missing --wait-timeout (run),
--worktree/--base/--image (run), --since (logs), and --image (send).

packages/cli/src/cli.ts

@@ -9,22 +9,21 @@ import { createWorktreeCommand } from "./commands/worktree/index.js";
 import { startCommand as daemonStartCommand } from "./commands/daemon/start.js";
 import { runStatusCommand as runDaemonStatusCommand } from "./commands/daemon/status.js";
 import { runRestartCommand as runDaemonRestartCommand } from "./commands/daemon/restart.js";
-import { runLsCommand } from "./commands/agent/ls.js";
+import { addLsOptions, runLsCommand } from "./commands/agent/ls.js";
-import { runRunCommand } from "./commands/agent/run.js";
+import { addRunOptions, runRunCommand } from "./commands/agent/run.js";
-import { runLogsCommand } from "./commands/agent/logs.js";
+import { addLogsOptions, runLogsCommand } from "./commands/agent/logs.js";
-import { runDeleteCommand } from "./commands/agent/delete.js";
+import { addDeleteOptions, runDeleteCommand } from "./commands/agent/delete.js";
-import { runStopCommand } from "./commands/agent/stop.js";
+import { addStopOptions, runStopCommand } from "./commands/agent/stop.js";
-import { runSendCommand } from "./commands/agent/send.js";
+import { addSendOptions, runSendCommand } from "./commands/agent/send.js";
-import { runInspectCommand } from "./commands/agent/inspect.js";
+import { addInspectOptions, runInspectCommand } from "./commands/agent/inspect.js";
-import { runWaitCommand } from "./commands/agent/wait.js";
+import { addWaitOptions, runWaitCommand } from "./commands/agent/wait.js";
-import { runAttachCommand } from "./commands/agent/attach.js";
+import { addAttachOptions, runAttachCommand } from "./commands/agent/attach.js";
 import { withOutput } from "./output/index.js";
 import { onboardCommand } from "./commands/onboard.js";
 import {
   addDaemonHostOption,
   addJsonAndDaemonHostOptions,
   addJsonOption,
-  collectMultiple,
 } from "./utils/command-options.js";
 
 const require = createRequire(import.meta.url);
@@ -59,120 +58,39 @@ export function createCli(): Command {
 
   // Primary agent commands (top-level)
   addJsonAndDaemonHostOptions(
-    program
+    addLsOptions(program.command("ls")),
-      .command("ls")
-      .description("List agents. By default excludes archived agents.")
-      .option("-a, --all", "Include archived agents")
-      .option("-g, --global", "Legacy no-op (kept for compatibility)")
-      .option(
-        "--label <key=value>",
-        "Filter by label (can be used multiple times)",
-        collectMultiple,
-        [],
-      )
-      .option("--thinking <id>", "Filter by thinking option ID"),
   ).action(withOutput(runLsCommand));
 
   addJsonAndDaemonHostOptions(
-    program
+    addRunOptions(program.command("run")),
-      .command("run")
-      .description("Create and start an agent with a task")
-      .argument("<prompt>", "The task/prompt for the agent")
-      .option("-d, --detach", "Run in background (detached)")
-      .option("--name <name>", "Assign a name/title to the agent")
-      .option(
-        "--provider <provider>",
-        "Agent provider, or provider/model (e.g. codex or codex/gpt-5.4)",
-        "claude",
-      )
-      .option(
-        "--model <model>",
-        "Model to use (e.g., claude-sonnet-4-20250514, claude-3-5-haiku-20241022)",
-      )
-      .option("--thinking <id>", "Thinking option ID to use for this run")
-      .option("--mode <mode>", "Provider-specific mode (e.g., plan, default, bypass)")
-      .option("--worktree <name>", "Create agent in a new git worktree")
-      .option("--base <branch>", "Base branch for worktree (default: current branch)")
-      .option(
-        "--image <path>",
-        "Attach image(s) to the initial prompt (can be used multiple times)",
-        collectMultiple,
-        [],
-      )
-      .option("--cwd <path>", "Working directory (default: current)")
-      .option(
-        "--label <key=value>",
-        "Add label(s) to the agent (can be used multiple times)",
-        collectMultiple,
-        [],
-      )
-      .option(
-        "--output-schema <schema>",
-        "Output JSON matching the provided schema file path or inline JSON schema",
-      ),
   ).action(withOutput(runRunCommand));
 
   addDaemonHostOption(
-    program
+    addAttachOptions(program.command("attach")),
-      .command("attach")
-      .description("Attach to a running agent's output stream")
-      .argument("<id>", "Agent ID (or prefix)"),
   ).action(runAttachCommand);
 
   addDaemonHostOption(
-    program
+    addLogsOptions(program.command("logs")),
-      .command("logs")
-      .description("View agent activity/timeline")
-      .argument("<id>", "Agent ID (or prefix)")
-      .option("-f, --follow", "Follow log output (streaming)")
-      .option("--tail <n>", "Show last n entries")
-      .option("--filter <type>", "Filter by event type (tools, text, errors, permissions)")
-      .option("--since <time>", "Show logs since timestamp"),
   ).action(runLogsCommand);
 
   addJsonAndDaemonHostOptions(
-    program
+    addStopOptions(program.command("stop")),
-      .command("stop")
-      .description("Interrupt an agent if it is running (no-op for idle agents)")
-      .argument("[id]", "Agent ID (or prefix) - optional if --all or --cwd specified")
-      .option("--all", "Stop all agents")
-      .option("--cwd <path>", "Stop all agents in directory"),
   ).action(withOutput(runStopCommand));
 
   addJsonAndDaemonHostOptions(
-    program
+    addDeleteOptions(program.command("delete")),
-      .command("delete")
-      .description("Delete an agent (interrupt if running, then hard-delete)")
-      .argument("[id]", "Agent ID (or prefix) - optional if --all or --cwd specified")
-      .option("--all", "Delete all agents")
-      .option("--cwd <path>", "Delete all agents in directory"),
   ).action(withOutput(runDeleteCommand));
 
   addJsonAndDaemonHostOptions(
-    program
+    addSendOptions(program.command("send")),
-      .command("send")
-      .description("Send a message/task to an existing agent")
-      .argument("<id>", "Agent ID (or prefix)")
-      .argument("[prompt]", "The message to send")
-      .option("--prompt <text>", "Provide the message inline as a flag")
-      .option("--prompt-file <path>", "Read the message from a UTF-8 text file")
-      .option("--no-wait", "Return immediately without waiting for completion")
-      .option("--image <path>", "Attach image(s) to the message", collectMultiple, []),
   ).action(withOutput(runSendCommand));
 
   addJsonAndDaemonHostOptions(
-    program
+    addInspectOptions(program.command("inspect")),
-      .command("inspect")
-      .description("Show detailed information about an agent")
-      .argument("<id>", "Agent ID (or prefix)"),
   ).action(withOutput(runInspectCommand));
 
   addJsonAndDaemonHostOptions(
-    program
+    addWaitOptions(program.command("wait")),
-      .command("wait")
-      .description("Wait for an agent to become idle")
-      .argument("<id>", "Agent ID (or prefix)")
-      .option("--timeout <seconds>", "Maximum wait time (default: no limit)"),
   ).action(withOutput(runWaitCommand));
 
   // Top-level local daemon shortcuts

packages/cli/src/commands/agent/attach.ts

@@ -1,4 +1,10 @@
 import type { Command } from "commander";
+
+export function addAttachOptions(cmd: Command): Command {
+  return cmd
+    .description("Attach to a running agent's output stream")
+    .argument("<id>", "Agent ID (or prefix)");
+}
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
 import { fetchProjectedTimelineItems } from "../../utils/timeline.js";
 import type {

packages/cli/src/commands/agent/delete.ts

@@ -1,5 +1,13 @@
 import type { Command } from "commander";
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
+
+export function addDeleteOptions(cmd: Command): Command {
+  return cmd
+    .description("Delete an agent (interrupt if running, then hard-delete)")
+    .argument("[id]", "Agent ID (or prefix) - optional if --all or --cwd specified")
+    .option("--all", "Delete all agents")
+    .option("--cwd <path>", "Delete all agents in directory");
+}
 import type {
   CommandOptions,
   SingleResult,

packages/cli/src/commands/agent/index.ts

@@ -1,15 +1,15 @@
 import { Command } from "commander";
 import { runModeCommand } from "./mode.js";
 import { runArchiveCommand } from "./archive.js";
-import { runDeleteCommand } from "./delete.js";
+import { addDeleteOptions, runDeleteCommand } from "./delete.js";
-import { runLsCommand } from "./ls.js";
+import { addLsOptions, runLsCommand } from "./ls.js";
-import { runRunCommand } from "./run.js";
+import { addRunOptions, runRunCommand } from "./run.js";
-import { runLogsCommand } from "./logs.js";
+import { addLogsOptions, runLogsCommand } from "./logs.js";
-import { runStopCommand } from "./stop.js";
+import { addStopOptions, runStopCommand } from "./stop.js";
-import { runSendCommand } from "./send.js";
+import { addSendOptions, runSendCommand } from "./send.js";
-import { runInspectCommand } from "./inspect.js";
+import { addInspectOptions, runInspectCommand } from "./inspect.js";
-import { runWaitCommand } from "./wait.js";
+import { addWaitOptions, runWaitCommand } from "./wait.js";
-import { runAttachCommand } from "./attach.js";
+import { addAttachOptions, runAttachCommand } from "./attach.js";
 import { runUpdateCommand } from "./update.js";
 import { withOutput } from "../../output/index.js";
 import {
@@ -23,114 +23,39 @@ export function createAgentCommand(): Command {
 
   // Primary agent commands (same as top-level)
   addJsonAndDaemonHostOptions(
-    agent
+    addLsOptions(agent.command("ls")),
-      .command("ls")
-      .description("List agents. By default excludes archived agents.")
-      .option("-a, --all", "Include archived agents")
-      .option("-g, --global", "Legacy no-op (kept for compatibility)")
-      .option(
-        "--label <key=value>",
-        "Filter by label (can be used multiple times)",
-        collectMultiple,
-        [],
-      )
-      .option("--thinking <id>", "Filter by thinking option ID"),
   ).action(withOutput(runLsCommand));
 
   addJsonAndDaemonHostOptions(
-    agent
+    addRunOptions(agent.command("run")),
-      .command("run")
-      .description("Create and start an agent with a task")
-      .argument("<prompt>", "The task/prompt for the agent")
-      .option("-d, --detach", "Run in background (detached)")
-      .option("--name <name>", "Assign a name/title to the agent")
-      .option(
-        "--provider <provider>",
-        "Agent provider, or provider/model (e.g. codex or codex/gpt-5.4)",
-        "claude",
-      )
-      .option(
-        "--model <model>",
-        "Model to use (e.g., claude-sonnet-4-20250514, claude-3-5-haiku-20241022)",
-      )
-      .option("--thinking <id>", "Thinking option ID to use for this run")
-      .option("--mode <mode>", "Provider-specific mode (e.g., plan, default, bypass)")
-      .option("--cwd <path>", "Working directory (default: current)")
-      .option(
-        "--label <key=value>",
-        "Add label(s) to the agent (can be used multiple times)",
-        collectMultiple,
-        [],
-      )
-      .option(
-        "--wait-timeout <duration>",
-        "Maximum time to wait for agent to finish (e.g., 30s, 5m, 1h). Default: no limit",
-      )
-      .option(
-        "--output-schema <schema>",
-        "Output JSON matching the provided schema file path or inline JSON schema",
-      ),
   ).action(withOutput(runRunCommand));
 
   addDaemonHostOption(
-    agent
+    addAttachOptions(agent.command("attach")),
-      .command("attach")
-      .description("Attach to a running agent's output stream")
-      .argument("<id>", "Agent ID (or prefix)"),
   ).action(runAttachCommand);
 
   addDaemonHostOption(
-    agent
+    addLogsOptions(agent.command("logs")),
-      .command("logs")
-      .description("View agent activity/timeline")
-      .argument("<id>", "Agent ID (or prefix)")
-      .option("-f, --follow", "Follow log output (streaming)")
-      .option("--tail <n>", "Show last n entries")
-      .option("--filter <type>", "Filter by event type (tools, text, errors, permissions)"),
   ).action(runLogsCommand);
 
   addJsonAndDaemonHostOptions(
-    agent
+    addStopOptions(agent.command("stop")),
-      .command("stop")
-      .description("Interrupt an agent if it is running (no-op for idle agents)")
-      .argument("[id]", "Agent ID (or prefix) - optional if --all or --cwd specified")
-      .option("--all", "Stop all agents")
-      .option("--cwd <path>", "Stop all agents in directory"),
   ).action(withOutput(runStopCommand));
 
   addJsonAndDaemonHostOptions(
-    agent
+    addDeleteOptions(agent.command("delete")),
-      .command("delete")
-      .description("Delete an agent (interrupt if running, then hard-delete)")
-      .argument("[id]", "Agent ID (or prefix) - optional if --all or --cwd specified")
-      .option("--all", "Delete all agents")
-      .option("--cwd <path>", "Delete all agents in directory"),
   ).action(withOutput(runDeleteCommand));
 
   addJsonAndDaemonHostOptions(
-    agent
+    addSendOptions(agent.command("send")),
-      .command("send")
-      .description("Send a message/task to an existing agent")
-      .argument("<id>", "Agent ID (or prefix)")
-      .argument("[prompt]", "The message to send")
-      .option("--prompt <text>", "Provide the message inline as a flag")
-      .option("--prompt-file <path>", "Read the message from a UTF-8 text file")
-      .option("--no-wait", "Return immediately without waiting for completion"),
   ).action(withOutput(runSendCommand));
 
   addJsonAndDaemonHostOptions(
-    agent
+    addInspectOptions(agent.command("inspect")),
-      .command("inspect")
-      .description("Show detailed information about an agent")
-      .argument("<id>", "Agent ID (or prefix)"),
   ).action(withOutput(runInspectCommand));
 
   addJsonAndDaemonHostOptions(
-    agent
+    addWaitOptions(agent.command("wait")),
-      .command("wait")
-      .description("Wait for an agent to become idle")
-      .argument("<id>", "Agent ID (or prefix)")
-      .option("--timeout <seconds>", "Maximum wait time (default: no limit)"),
   ).action(withOutput(runWaitCommand));
 
   // Advanced agent commands (less common operations)

packages/cli/src/commands/agent/inspect.ts

@@ -3,6 +3,12 @@ import type { AgentSnapshotPayload } from "@getpaseo/server";
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
 import type { CommandOptions, ListResult, OutputSchema, CommandError } from "../../output/index.js";
 
+export function addInspectOptions(cmd: Command): Command {
+  return cmd
+    .description("Show detailed information about an agent")
+    .argument("<id>", "Agent ID (or prefix)");
+}
+
 /** Agent inspect data for display (matches CLI spec format) */
 interface AgentInspect {
   Id: string;

packages/cli/src/commands/agent/logs.ts

@@ -1,10 +1,20 @@
-import type { Command } from "commander";
+import { Command } from "commander";
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
 import type { CommandOptions } from "../../output/index.js";
 import { fetchProjectedTimelineItems } from "../../utils/timeline.js";
 import type { DaemonClient, AgentStreamMessage, AgentTimelineItem } from "@getpaseo/server";
 import { curateAgentActivity } from "@getpaseo/server";
 
+export function addLogsOptions(cmd: Command): Command {
+  return cmd
+    .description("View agent activity/timeline")
+    .argument("<id>", "Agent ID (or prefix)")
+    .option("-f, --follow", "Follow log output (streaming)")
+    .option("--tail <n>", "Show last n entries")
+    .option("--filter <type>", "Filter by event type (tools, text, errors, permissions)")
+    .option("--since <time>", "Show logs since timestamp");
+}
+
 export interface AgentLogsOptions extends CommandOptions {
   follow?: boolean;
   tail?: string;

packages/cli/src/commands/agent/ls.ts

@@ -2,6 +2,21 @@ import type { Command } from "commander";
 import type { AgentSnapshotPayload } from "@getpaseo/server";
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
 import type { CommandOptions, ListResult, OutputSchema, CommandError } from "../../output/index.js";
+import { collectMultiple } from "../../utils/command-options.js";
+
+export function addLsOptions(cmd: Command): Command {
+  return cmd
+    .description("List agents. By default excludes archived agents.")
+    .option("-a, --all", "Include archived agents")
+    .option("-g, --global", "Legacy no-op (kept for compatibility)")
+    .option(
+      "--label <key=value>",
+      "Filter by label (can be used multiple times)",
+      collectMultiple,
+      [],
+    )
+    .option("--thinking <id>", "Filter by thinking option ID");
+}
 
 /** Agent list item for display */
 export interface AgentListItem {

packages/cli/src/commands/agent/run.ts

@@ -1,4 +1,4 @@
-import type { Command } from "commander";
+import { Command } from "commander";
 import {
   getStructuredAgentResponse,
   StructuredAgentResponseError,
@@ -15,6 +15,49 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { lookup } from "mime-types";
 import { parseDuration } from "../../utils/duration.js";
+import { collectMultiple } from "../../utils/command-options.js";
+
+export function addRunOptions(cmd: Command): Command {
+  return cmd
+    .description("Create and start an agent with a task")
+    .argument("<prompt>", "The task/prompt for the agent")
+    .option("-d, --detach", "Run in background (detached)")
+    .option("--name <name>", "Assign a name/title to the agent")
+    .option(
+      "--provider <provider>",
+      "Agent provider, or provider/model (e.g. codex or codex/gpt-5.4)",
+      "claude",
+    )
+    .option(
+      "--model <model>",
+      "Model to use (e.g., claude-sonnet-4-20250514, claude-3-5-haiku-20241022)",
+    )
+    .option("--thinking <id>", "Thinking option ID to use for this run")
+    .option("--mode <mode>", "Provider-specific mode (e.g., plan, default, bypass)")
+    .option("--worktree <name>", "Create agent in a new git worktree")
+    .option("--base <branch>", "Base branch for worktree (default: current branch)")
+    .option(
+      "--image <path>",
+      "Attach image(s) to the initial prompt (can be used multiple times)",
+      collectMultiple,
+      [],
+    )
+    .option("--cwd <path>", "Working directory (default: current)")
+    .option(
+      "--label <key=value>",
+      "Add label(s) to the agent (can be used multiple times)",
+      collectMultiple,
+      [],
+    )
+    .option(
+      "--wait-timeout <duration>",
+      "Maximum time to wait for agent to finish (e.g., 30s, 5m, 1h). Default: no limit",
+    )
+    .option(
+      "--output-schema <schema>",
+      "Output JSON matching the provided schema file path or inline JSON schema",
+    );
+}
 
 /** Result type for agent run command */
 export interface AgentRunResult {

packages/cli/src/commands/agent/send.ts

@@ -1,4 +1,5 @@
-import type { Command } from "commander";
+import { type Command } from "commander";
+import { collectMultiple } from "../../utils/command-options.js";
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
 import type {
   CommandOptions,
@@ -33,6 +34,17 @@ export interface AgentSendOptions extends CommandOptions {
   promptFile?: string;
 }
 
+export function addSendOptions(cmd: Command): Command {
+  return cmd
+    .description("Send a message/task to an existing agent")
+    .argument("<id>", "Agent ID (or prefix)")
+    .argument("[prompt]", "The message to send")
+    .option("--prompt <text>", "Provide the message inline as a flag")
+    .option("--prompt-file <path>", "Read the message from a UTF-8 text file")
+    .option("--image <path>", "Attach image(s) to the message", collectMultiple, [])
+    .option("--no-wait", "Return immediately without waiting for completion");
+}
+
 /**
  * Read image files and convert them to base64 data URIs
  */

packages/cli/src/commands/agent/stop.ts

@@ -1,4 +1,4 @@
-import type { Command } from "commander";
+import { Command } from "commander";
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
 import type {
   CommandOptions,
@@ -20,6 +20,14 @@ export const stopSchema: OutputSchema<StopResult> = {
   columns: [{ header: "INTERRUPTED", field: "stoppedCount" }],
 };
 
+export function addStopOptions(cmd: Command): Command {
+  return cmd
+    .description("Interrupt an agent if it is running (no-op for idle agents)")
+    .argument("[id]", "Agent ID (or prefix) - optional if --all or --cwd specified")
+    .option("--all", "Stop all agents")
+    .option("--cwd <path>", "Stop all agents in directory");
+}
+
 export interface AgentStopOptions extends CommandOptions {
   all?: boolean;
   cwd?: string;

packages/cli/src/commands/agent/wait.ts

@@ -1,4 +1,4 @@
-import type { Command } from "commander";
+import { Command } from "commander";
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
 import type {
   CommandOptions,
@@ -53,6 +53,13 @@ async function getRecentActivityTranscript(
   }
 }
 
+export function addWaitOptions(cmd: Command): Command {
+  return cmd
+    .description("Wait for an agent to become idle")
+    .argument("<id>", "Agent ID (or prefix)")
+    .option("--timeout <seconds>", "Maximum wait time (default: no limit)");
+}
+
 export async function runWaitCommand(
   agentIdArg: string,
   options: AgentWaitOptions,