gemcatch 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-04
+
+### Added
+
+- **Collaborative planning.** Until now the only agent flow was a blind one-shot
+  bet: gemcatch showed a cost band, asked y/N, and fired. The cost band was
+  everything you knew before spending, and there was no way to check the agent
+  had read the prompt the way you meant it. A 20-line `batch` against
+  `deep-research-max` is a $60–$140 command placed sight unseen. The Deep
+  Research docs have always documented a second mode for exactly this, and
+  gemcatch could not reach it. Now it can:
+
+  - `--plan` on `research` and `batch` submits with
+    `agent_config.collaborative_planning: true`, so **the agent returns a
+    research plan instead of a report**. Still `background: true`, still stored,
+    still collected by the daemon. The row is stored with `kind='plan'`.
+  - `gemcatch get <id>` on a plan prints the plan and then the literal next
+    command, `Approve with: gemcatch approve 8f3a1c04 · Refine with: gemcatch
+    refine 8f3a1c04 "..."`, on stderr, so `get <plan> > plan.md` still captures
+    just the plan.
+  - `gemcatch refine <id> "<instruction>"` sends the instruction back with
+    `previous_interaction_id` and planning still on, and stores the revised plan
+    linked to the one it came from, inheriting its agent and tag.
+  - `gemcatch approve <id>` is the turn that commits: `previous_interaction_id`
+    with `collaborative_planning: false`, stored as `kind='report'` linked to the
+    plan. It shows the cost band and asks, honours `--yes` when stdin is not a
+    TTY, and honours `--dry-run`.
+
+  **Planning is not cheaper.** The docs give one band per task and do not price a
+  planning turn separately, so a planning turn is quoted at the same band and the
+  line says so: *"the docs price per task and do not price a planning turn
+  separately"*. What you get for it is a look at the plan before you commit to
+  the research run, not a discount.
+- `gemcatch list` renders a chain indented under its root, in submission order,
+  and grows a `KIND` column when a listing contains plans or reports (a store
+  with neither keeps the layout it had). `gemcatch export` follows a chain to its
+  report and leaves the intermediate plans out unless `--include-plans` is
+  passed; the Markdown sections and the JSON rows now name the turn.
+- `gemcatch stats` now tallies plan and report turns, and totals the estimated
+  spend across the agent turns that were actually billed, from the same
+  published bands the guard quotes before each one. A chain bills per turn, so a
+  release that turns one submission into three owes the user a running total. It
+  is the documented bands applied to what was submitted, not a reading of your
+  bill, and it errs toward telling you rather than flattering you: only runs
+  that reached the server are priced (a submit that failed before it left the
+  machine is counted as an attempt but costs nothing), and an agent with no
+  published band totals to `unknown`, never to `$0.00`. A store with no agent
+  runs prints neither line.
+- Additive schema migration: `collaborative_planning`, `previous_interaction_id`,
+  `kind` (defaulting to `'task'`) and `parent_id`. A 0.4.0 `tasks.db` upgrades in
+  place, keeps every row, and behaves exactly as it did.
+
+### Fixed
+
+- `approve` and `refine` fail before sending anything when the target is not a
+  plan, or is a plan that has not completed. A plan whose interaction the free
+  tier has already dropped names the retention window (1 day free, 55 days paid)
+  instead of sending a `previous_interaction_id` the server would reject. A plan
+  that expires *after* it completed locally gets the same explanation rather
+  than a bare 404 for an id the user never typed.
+- `--plan` without `--agent` (or with `--model`) is a clean error rather than a
+  flag that quietly does nothing: collaborative planning is an agent feature.
+- Approving the same plan twice submits a second run rather than silently
+  reusing the first, and `list` shows both under their plan.
+
 ## [0.4.0] - 2026-08-08
 
 ### Added
@@ -204,7 +269,8 @@ seen a task complete, the text is cached locally and survives that expiry — bu
 something has to poll inside that window for it to be seen at all, which is what
 `gemcatch daemon` exists to do.
 
-[Unreleased]: https://github.com/Booyaka101/gemcatch/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/Booyaka101/gemcatch/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/Booyaka101/gemcatch/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/Booyaka101/gemcatch/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Booyaka101/gemcatch/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Booyaka101/gemcatch/compare/v0.1.1...v0.2.0

package/README.md

@@ -81,8 +81,10 @@ This week in AI: ...
 | `gemcatch research "<prompt>"` | Submits with `background: true`, stores the interaction ID, exits immediately. |
 | `gemcatch batch <file>` | Submits many prompts from a file at once, tagged as one collectable batch. |
 | `gemcatch status <id>` | Polls the API and prints the current state. |
-| `gemcatch get <id>` | Prints the full response if complete, otherwise the current status. |
-| `gemcatch list` | All tasks, newest first: id, age, status, prompt. |
+| `gemcatch get <id>` | Prints the full response if complete, otherwise the current status. On a [plan](#see-the-plan-before-you-pay-for-the-run), the plan plus the approve/refine commands. |
+| `gemcatch refine <id> "<instruction>"` | Sends an instruction back to a plan and returns a revised plan. |
+| `gemcatch approve <id>` | Approves a plan and submits the research run it describes. |
+| `gemcatch list` | All tasks, newest first: id, age, status, prompt. Plan chains are indented under their root. |
 | `gemcatch export` | Concatenates finished results, each under its prompt, to stdout or a file (Markdown or JSON). |
 | `gemcatch digest` | Feeds a tag's completed results through one Gemini call into a single summary. |
 | `gemcatch watch <id>` | Polls until the task finishes, then prints the result. |
@@ -91,7 +93,7 @@ This week in AI: ...
 | `gemcatch cancel <id>` | Asks the API to stop an in-flight task. |
 | `gemcatch rm <ids...>` | Forgets tasks locally. `--remote` deletes them server-side too. |
 | `gemcatch prune` | Drops finished tasks older than `--days` (default 30). |
-| `gemcatch stats` | Where the store lives and what's in it. |
+| `gemcatch stats` | Where the store lives, what's in it, and what the agent runs have plausibly cost. |
 
 Useful flags:
 
@@ -100,7 +102,8 @@ Useful flags:
 | `--json` | most commands | Machine-readable output. |
 | `-m, --model <id>` | `research`, `batch` | Override the model. |
 | `-a, --agent <id>` | `research`, `batch` | Submit to a [research agent](#research-agents) instead of a model. Mutually exclusive with `--model`. |
-| `--yes` | `research`, `batch` | Confirm the agent cost without asking. Required for `--agent` when stdin is not a TTY. |
+| `--plan` | `research`, `batch` | Ask the agent for a [research plan](#see-the-plan-before-you-pay-for-the-run) first, to refine and approve. Needs `--agent`. |
+| `--yes` | `research`, `batch`, `refine`, `approve` | Confirm the agent cost without asking. Required for `--agent` when stdin is not a TTY. |
 | `-s, --system <text>` | `research`, `batch` | Set a system instruction. |
 | `-f, --file <path>` | `research` | Read the prompt from a file. |
 | `-t, --tag <tag>` | `research`, `batch`, `list` | Label tasks and filter them. |
@@ -112,7 +115,8 @@ Useful flags:
 | `-n, --limit <n>` | `list` | Cap the rows (non-negative; `0` shows none). |
 | `--format <md\|json>` | `export` | Output format. Default `md`. |
 | `-o, --out <file>` | `export` | Write to a file instead of stdout. |
-| `--dry-run` | `research`, `batch`, `prune` | Show what would go — including the projected agent spend; submit/delete nothing. |
+| `--include-plans` | `export` | Also emit a chain's plan turns, not just its report. |
+| `--dry-run` | `research`, `batch`, `refine`, `approve`, `prune` | Show what would go — including the projected agent spend; submit/delete nothing. |
 | `--raw` | `get` | Dump the raw interaction JSON. |
 
 IDs are the first 8 characters of a UUID. Any unique prefix works, so `gemcatch get 8f3a` is fine.
@@ -187,14 +191,97 @@ The report lands like any other result — final answer only, none of the agent'
 
 An agent run can also come back `incomplete` — that is what a `max_total_tokens` budget cap produces when the run "safely pauses" — which `gemcatch` treats as terminal, exactly like the API does: the daemon retires it and moves on.
 
+### See the plan before you pay for the run
+
+A cost band tells you what a run will cost. It tells you nothing about whether the agent understood the question. Add `--plan` and it doesn't start researching: with `agent_config.collaborative_planning: true`, *"the agent returns a research plan instead of a full report"*. You read it, push back on it, and approve it when it's right.
+
+```console
+$ gemcatch research "map the EU AI Act high-risk obligations against the UK approach" --agent deep-research --plan -t euuk
+Agent deep-research-preview-04-2026 (planning turn) — estimated $1.00–$3.00 for this task (preview rates, subject to change; the docs price per task and do not price a planning turn separately).
+Submit? [y/N] y
+Plan task d014e21b submitted. Run: gemcatch get d014e21b when ready.
+
+$ gemcatch get d014e21b
+Research plan
+
+1. Scope the EU AI Act high-risk regime: Annex III use cases, Article 6 classification,
+   and the Chapter III obligations (risk management, data governance, logging, human
+   oversight, conformity assessment) with their August 2026 / August 2027 dates.
+2. Scope the UK approach: the five cross-sector principles, the regulator-led model
+   (ICO, FCA, MHRA, Ofcom), and what is guidance rather than statute.
+3. Build an obligation-by-obligation comparison table: EU requirement, nearest UK
+   equivalent, whether it is binding, and who enforces it.
+4. Flag the gaps in both directions and the compliance implications for a firm
+   operating in both.
+Approve with: gemcatch approve d014e21b   ·   Refine with: gemcatch refine d014e21b "..."
+
+$ gemcatch refine d014e21b "cut the history, and add enforcement penalties on both sides"
+Plan task 2140e699 submitted (refines d014e21b). Run: gemcatch get 2140e699 when ready.
+
+$ gemcatch approve 2140e699
+Agent deep-research-preview-04-2026 — estimated $1.00–$3.00 for this task (preview rates, subject to change).
+Submit? [y/N] y
+Task 96e8209b submitted (approves plan 2140e699).
+```
+
+Every turn is an ordinary background task: stored, polled, and collected by the daemon before the 1-day expiry, same as everything else. `refine` chains as many times as you like; each revision inherits the agent and tag of the plan it came from.
+
+**A planning turn is a task, and it is billed as one.** The docs publish one band per task and price no planning turn separately, so `gemcatch` quotes the same band for it and says exactly that on the line. What `--plan` buys you is a look at the plan before you commit to the research run, not a discount. Budget for the plan, each refinement, and the run.
+
+Since a chain bills per turn, `gemcatch stats` keeps a running total across all of them:
+
+```console
+$ gemcatch stats
+Store: ~/.gemcatch/tasks.db
+Tasks: 3
+  completed         3
+Agent runs:
+  deep-research-preview-04-2026      3
+Plan chains: 2 plan, 1 report
+Estimated spend: $3.00–$9.00 across 3 billed task(s) (preview rates, subject to change).
+```
+
+That's the chain above: one plan, one refinement, one run, three tasks at the same band. It's the published bands applied to what you actually submitted, not a reading of your bill, and it errs toward telling you rather than flattering you:
+
+- Only runs that **reached the server** are priced. A submit that failed before it left the machine (bad key, rejected agent id) is still counted under "Agent runs" as an attempt, but it costs nothing and isn't billed.
+- An agent with **no published band** totals to `unknown`, never to `$0.00`. Quoting zero for a run that costs real money is the one thing a spend guard must not do.
+
+`list` shows the chain as one thing, and `export` follows it to the report:
+
+```console
+$ gemcatch list
+ID        AGE   STATUS           KIND    AGENT              PROMPT
+d014e21b  22s   completed        plan    deep-research      map the EU AI Act high-risk obligations against the UK ap...
+2140e699  12s   completed        plan    deep-research      └─ cut the history, and add enforcement penalties on both sides
+96e8209b  7s    completed        report  deep-research        └─ map the EU AI Act high-risk obligations against the UK ap...
+
+$ gemcatch export --tag euuk -o report.md
+Wrote 1 result(s) to report.md.
+```
+
+The plans are working notes on the way to the report, so `export` leaves them out; pass `--include-plans` if you want the whole chain in the document. The report is filed under the question that started the chain rather than the one-line approval actually sent to the API, so an exported document reads as research.
+
+A few things that will bite otherwise:
+
+- `--plan` needs `--agent`. Collaborative planning is an agent feature, so `--plan --model ...` (or `--plan` on its own) is an error, not a no-op.
+- `approve` only works on a plan that has completed. Anything else fails before a request goes out.
+- On the free tier the plan's interaction is dropped after a day. Once that happens the chain cannot be continued. `approve` says so and names the window instead of sending a `previous_interaction_id` the server will reject. Run the daemon, or approve the same day.
+- Approving twice submits twice. There is no dedupe, and both runs show up under the plan in `list`.
+- `--plan` and `--watch` work together: `gemcatch research "..." --agent deep-research --plan -w` waits for the plan and then prints it.
+
 The agent recipe, end to end:
 
 ```bash
-$ gemcatch batch questions.txt --agent deep-research --yes   # bands shown, N × total quoted
-$ gemcatch daemon --exit-when-idle                           # catch reports before the 1-day expiry
-$ gemcatch export --tag batch-1a2b3c -o reports.md           # every report, with its sources
+$ gemcatch batch questions.txt --agent deep-research --plan --yes   # a plan per prompt, N × band quoted
+$ gemcatch daemon --exit-when-idle                                  # catch the plans
+$ gemcatch list --tag batch-1a2b3c                                  # read them, approve the good ones
+$ gemcatch approve 8f3a1c04 --yes
+$ gemcatch daemon --exit-when-idle                                  # catch the reports before the 1-day expiry
+$ gemcatch export --tag batch-1a2b3c -o reports.md                  # every report, with its sources
 ```
 
+Drop `--plan` and the first two lines become the 0.4.0 one-shot flow, which still works exactly as it did.
+
 ## How it works
 
 Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
@@ -202,7 +289,8 @@ Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
 ```sql
 CREATE TABLE tasks (id TEXT PRIMARY KEY, prompt TEXT, interaction_id TEXT,
                     status TEXT DEFAULT 'pending', result TEXT, created_at INTEGER);
--- plus model, system_instruction, tag, error, usage, updated_at, agent, citations
+-- plus model, system_instruction, tag, error, usage, updated_at, agent, citations,
+--      collaborative_planning, previous_interaction_id, kind, parent_id
 ```
 
 `research` calls `interactions.create({model, input, background: true})` via [`@google/genai`](https://www.npmjs.com/package/@google/genai) and keeps the returned `id`. The polling commands call `interactions.get(id)` and write the status back. Once a task completes, the text is cached in the `result` column — `gemcatch get` then answers from disk without touching the network.

package/db.js

@@ -31,6 +31,17 @@ const MIGRATIONS = [
   // the JSON array of sources an agent run returned alongside its report.
   ['agent', 'TEXT'],
   ['citations', 'TEXT'],
+  // 0.5.0: collaborative planning. `collaborative_planning` is the agent_config
+  // flag the row was submitted with (1 plan turn, 0 report turn, NULL for every
+  // run that sent no agent_config at all, including every pre-0.5.0 row);
+  // `previous_interaction_id` is the interaction this turn continues;
+  // `kind` is 'task' | 'plan' | 'report'; `parent_id` is the local task this
+  // turn continues. The DEFAULT backfills 'task' for older rows, so a 0.4.0
+  // store keeps behaving exactly as it did.
+  ['collaborative_planning', 'INTEGER'],
+  ['previous_interaction_id', 'TEXT'],
+  ['kind', "TEXT DEFAULT 'task'"],
+  ['parent_id', 'TEXT'],
 ];
 
 let _db = null;
@@ -64,8 +75,10 @@ function createTask(fields) {
   const now = Date.now();
   db()
     .prepare(
-      'INSERT INTO tasks (id, prompt, status, created_at, updated_at, model, system_instruction, tag, agent) ' +
-        'VALUES (@id, @prompt, @status, @now, @now, @model, @system_instruction, @tag, @agent)'
+      'INSERT INTO tasks (id, prompt, status, created_at, updated_at, model, system_instruction, tag, agent, ' +
+        'kind, parent_id, collaborative_planning, previous_interaction_id) ' +
+        'VALUES (@id, @prompt, @status, @now, @now, @model, @system_instruction, @tag, @agent, ' +
+        '@kind, @parent_id, @collaborative_planning, @previous_interaction_id)'
     )
     .run({
       id,
@@ -76,6 +89,12 @@ function createTask(fields) {
       system_instruction: t.systemInstruction || null,
       tag: t.tag || null,
       agent: t.agent || null,
+      kind: t.kind || 'task',
+      parent_id: t.parentId || null,
+      // Presence, not truthiness: `false` is the report turn's real flag and
+      // must be stored as 0, while a run that sends no agent_config stores NULL.
+      collaborative_planning: t.collaborativePlanning === undefined ? null : Number(!!t.collaborativePlanning),
+      previous_interaction_id: t.previousInteractionId || null,
     });
   return id;
 }
@@ -181,6 +200,27 @@ function agentCounts() {
     .all();
 }
 
+// Agent runs that actually reached the server, keyed by agent. A submit that
+// never got an interaction_id (a bad key, a rejected agent id, a network
+// failure) was never billed, so it must not appear in a spend total -- unlike
+// agentCounts(), which tallies every attempt.
+function billedAgentCounts() {
+  return db()
+    .prepare(
+      'SELECT agent, COUNT(*) AS n FROM tasks WHERE agent IS NOT NULL AND interaction_id IS NOT NULL GROUP BY agent'
+    )
+    .all();
+}
+
+// Plan/report totals for `stats`. Ordinary tasks are not a row here; they are
+// already accounted for in counts(), and a store that has never planned reports
+// nothing at all.
+function kindCounts() {
+  return db()
+    .prepare("SELECT kind, COUNT(*) AS n FROM tasks WHERE kind IS NOT NULL AND kind != 'task' GROUP BY kind")
+    .all();
+}
+
 function close() {
   if (_db) _db.close();
   _db = null;
@@ -200,5 +240,7 @@ module.exports = {
   prunableTasks,
   counts,
   agentCounts,
+  billedAgentCounts,
+  kindCounts,
   close,
 };

package/gemini.js

@@ -23,6 +23,12 @@ const AGENT_ALIASES = Object.freeze({
   'deep-research-max': 'deep-research-max-preview-04-2026',
 });
 
+// `agent_config.type` for the config block a collaborative-planning turn sends.
+// Both documented Deep Research agents use the same value, and an unknown
+// pass-through id is assumed to be one too -- collaborative planning is a Deep
+// Research feature, so there is nothing else it could be.
+const AGENT_CONFIG_TYPE = 'deep-research';
+
 // Documented per-task price bands, in dollars, keyed by the RESOLVED id.
 // The docs' own hedge applies -- "These figures are estimates based on
 // preview rates and are subject to change" -- so the spend guard quotes
@@ -360,6 +366,21 @@ async function submit(prompt, opts) {
     ? { agent: o.agent, input: prompt, background: true }
     : { model: o.model || DEFAULT_MODEL, input: prompt, background: true };
   if (o.systemInstruction) body.system_instruction = o.systemInstruction;
+  // collaborative_planning is an `agent_config` field, NOT a top-level one, and
+  // the docs send the whole block (type + thinking_summaries) with it. Sent only
+  // when a plan turn is involved -- agent_config is optional otherwise, so an
+  // ordinary run keeps making exactly the request it always made. Presence, not
+  // truthiness: `false` is the approval turn's real value and must reach the API.
+  if (o.collaborativePlanning !== undefined) {
+    body.agent_config = {
+      type: AGENT_CONFIG_TYPE,
+      thinking_summaries: 'auto',
+      collaborative_planning: !!o.collaborativePlanning,
+    };
+  }
+  // Continues an earlier interaction server-side: the plan is already in that
+  // conversation, so this turn sends only what changed.
+  if (o.previousInteractionId) body.previous_interaction_id = o.previousInteractionId;
   const r = await call(() => {
     const api = sdkInteractions();
     return api
@@ -414,6 +435,7 @@ module.exports = {
   MAX_RETRIES,
   AGENT_ALIASES,
   AGENT_PRICE_BANDS,
+  AGENT_CONFIG_TYPE,
   resolveAgent,
   submit,
   poll,

package/index.js

@@ -126,6 +126,12 @@ function parseCitations(raw) {
 // The bands are quoted with the docs' own hedge ("estimates based on preview
 // rates and subject to change"), never as authoritative.
 
+// A planning turn is a task and is billed as one. The docs publish ONE band per
+// task and price no planning turn separately, so it is quoted at the same band
+// and the line says so outright. Planning buys you a look at the plan before you
+// commit to the research run; it does not buy you a discount.
+const PLAN_NOTE = 'the docs price per task and do not price a planning turn separately';
+
 function bandText(agentId, count) {
   const band = gemini.AGENT_PRICE_BANDS[agentId];
   if (!band) return 'no published price band for this agent';
@@ -135,9 +141,51 @@ function bandText(agentId, count) {
     : `estimated ${money(band[0])}–${money(band[1])} for this task`;
 }
 
-function spendLine(agentId, count) {
+function spendLine(agentId, count, planning) {
   const head = count > 1 ? `${count} prompts × ${agentId}` : `Agent ${agentId}`;
-  return `${head} — ${bandText(agentId, count)}`;
+  return `${head}${planning ? ' (planning turn)' : ''} — ${bandText(agentId, count)}`;
+}
+
+// The parenthetical after the band. `hedge` is the docs' "preview rates" caveat,
+// which the confirmation carries; --dry-run already reads as a projection.
+function spendNote(planning, hedge) {
+  const parts = [];
+  if (hedge) parts.push('preview rates, subject to change');
+  if (planning) parts.push(PLAN_NOTE);
+  return parts.length ? ` (${parts.join('; ')})` : '';
+}
+
+// What the agent runs in the store have plausibly cost, from the same per-task
+// bands the guard quotes before each one. A plan chain bills per turn, so this
+// counts plans and refinements alongside reports -- that is the number worth
+// knowing. Agents with no published band are counted separately rather than
+// silently priced at zero. Null when nothing has been billed at all.
+function estimatedSpend(agentRows) {
+  let low = 0;
+  let high = 0;
+  let tasks = 0;
+  let unpriced = 0;
+  for (const a of agentRows) {
+    const band = gemini.AGENT_PRICE_BANDS[a.agent];
+    if (!band) {
+      unpriced += a.n;
+      continue;
+    }
+    low += band[0] * a.n;
+    high += band[1] * a.n;
+    tasks += a.n;
+  }
+  if (!tasks && !unpriced) return null;
+  // Nothing priced means the total is unknown, NOT zero. Reporting $0.00 for
+  // runs that cost real money is the exact dishonesty this guard exists to
+  // avoid, so low/high are null and the caller says "unknown" instead.
+  if (!tasks) return { low: null, high: null, tasks: 0, unpriced };
+  return { low, high, tasks, unpriced };
+}
+
+// One sentence for a --dry-run: the band, the honesty note, and that nothing went.
+function dryRunSpend(agentId, count, planning) {
+  return `${spendLine(agentId, count, planning)}${spendNote(planning, false)}. Nothing submitted (--dry-run).`;
 }
 
 function askYesNo(question) {
@@ -154,8 +202,8 @@ function askYesNo(question) {
 // Returns only when the submission is confirmed; otherwise it exits (declined)
 // or throws (no way to ask). Runs BEFORE any row is written, so a declined or
 // refused submission leaves the tasks table untouched.
-async function confirmSpend(agentId, count, opts) {
-  console.error(`${spendLine(agentId, count)} (preview rates, subject to change).`);
+async function confirmSpend(agentId, count, opts, planning) {
+  console.error(`${spendLine(agentId, count, planning)}${spendNote(planning, true)}.`);
   if (opts.yes) return;
   // GEMCATCH_ASSUME_TTY lets the offline suite drive the interactive branch
   // through a pipe; real non-TTY callers (cron, CI, scripts) must say --yes.
@@ -177,7 +225,18 @@ async function confirmSpend(agentId, count, opts) {
 // only when the user actually typed it -- commander fills in the default
 // otherwise, and the default must not poison every agent run.
 function resolveAgentOpts(opts, cmd) {
-  if (!opts.agent) return null;
+  if (!opts.agent) {
+    // Collaborative planning is an agent_config field on an agent run. A model
+    // run has no plan turn at all, so --plan without --agent is a mistake worth
+    // naming rather than a flag that quietly does nothing.
+    if (opts.plan) {
+      throw new Error(
+        '--plan is a research-agent feature: collaborative planning applies to an agent, not a model, ' +
+          'and a model run has no plan turn.\n  Try: --agent deep-research --plan'
+      );
+    }
+    return null;
+  }
   if (cmd.getOptionValueSource('model') === 'cli') {
     throw new Error(
       '--model and --agent are mutually exclusive: an agent run is submitted with `agent` ' +
@@ -187,6 +246,170 @@ function resolveAgentOpts(opts, cmd) {
   return gemini.resolveAgent(opts.agent);
 }
 
+// --- plan chains ----------------------------------------------------------
+
+// `collaborative_planning: true` makes the agent return a research plan instead
+// of a report. That plan is a decision point, not a deliverable: you read it,
+// optionally `refine` it, and `approve` it to spend on the research run itself.
+// Each turn is its own task row, linked to the one it continues by parent_id
+// locally and by previous_interaction_id on the wire.
+
+// What the approval turn sends as `input`. The plan is already in the
+// conversation via previous_interaction_id, so this turn only has to say yes --
+// the docs' own example sends a one-line confirmation, not the question again.
+const APPROVE_INPUT = 'Plan looks good, proceed with the research.';
+
+// The reason refresh() records when a poll 404s. Named because `approve` reads
+// it back to tell an expired plan apart from any other terminal one.
+const EXPIRED_ERROR = 'interaction not found (expired or deleted)';
+
+const RETENTION_NOTE =
+  'The Interactions API retains interactions for 1 day on the free tier (55 days on paid).';
+
+// A finished plan is a decision point, so the next command is spelled out under
+// it. Guidance, so it goes to stderr like the rest -- `gemcatch get <plan> >
+// plan.md` still captures only the plan.
+function planFooter(task) {
+  return `Approve with: gemcatch approve ${task.id}   ·   Refine with: gemcatch refine ${task.id} "..."`;
+}
+
+// The result payload for `get`/`watch`. The plan-chain fields ride along only on
+// a plan row, so a model run's --json shape is exactly what it always was.
+function resultPayload(task, status, result, citations) {
+  const p = { id: task.id, status, result, citations: citations || null };
+  if (task.kind === 'plan') {
+    p.kind = 'plan';
+    p.approve = `gemcatch approve ${task.id}`;
+    p.refine = `gemcatch refine ${task.id} "<instruction>"`;
+  }
+  return p;
+}
+
+// Both continuation commands need the same thing: a plan row that completed and
+// whose interaction the server can still resolve. Anything else exits here,
+// before a row is written or a request is sent.
+function needPlan(id, verb) {
+  const task = needTask(id);
+  if (task.kind !== 'plan') {
+    die(
+      new Error(
+        `Task ${task.id} is not a plan (kind: ${task.kind || 'task'}), so there is nothing to ${verb}.\n` +
+          '  Plans come from: gemcatch research "<prompt>" --agent deep-research --plan'
+      )
+    );
+  }
+  if (task.status === 'incomplete' && task.error === EXPIRED_ERROR) {
+    die(
+      new Error(
+        `Plan ${task.id}'s interaction was dropped server-side, so it can no longer be continued.\n` +
+          `  ${RETENTION_NOTE}\n` +
+          `  Submit a fresh plan: gemcatch research "<prompt>" --agent ${task.agent || '<agent>'} --plan`
+      )
+    );
+  }
+  // A plan that finished any way other than `completed` is never coming back, so
+  // "wait for it" would be wrong advice. Only a plan still in flight gets
+  // pointed at `watch`.
+  if (isDone(task.status) && !isSuccess(task.status)) {
+    die(
+      new Error(
+        `Plan ${task.id} ended ${task.status}, so there is nothing to ${verb}.\n` +
+          `  Submit a fresh plan: gemcatch research "<prompt>" --agent ${task.agent || '<agent>'} --plan`
+      )
+    );
+  }
+  if (!isSuccess(task.status)) {
+    die(
+      new Error(
+        `Plan ${task.id} has not completed yet (status: ${task.status}), so there is nothing to ${verb}.\n` +
+          `  Wait for it: gemcatch watch ${task.id}`
+      )
+    );
+  }
+  if (!task.interaction_id) die(new Error(`Plan ${task.id} was never submitted.`));
+  return task;
+}
+
+// A plan can complete locally and still expire server-side before you approve
+// it, in which case the continuation 404s on an id the user never typed. Name
+// the retention window instead of passing that through raw.
+function expiredHint(err, plan) {
+  if (!err || err.httpStatus !== 404) return err;
+  const e = new Error(
+    `the plan's interaction (${plan.interaction_id}) is gone server-side, so it cannot be continued.\n` +
+      `  ${RETENTION_NOTE}\n` +
+      `  Submit a fresh plan: gemcatch research "<prompt>" --agent ${plan.agent || '<agent>'} --plan`
+  );
+  e.code = 'API_ERROR';
+  e.httpStatus = 404;
+  return e;
+}
+
+// A report row is displayed under the question that started the chain rather
+// than the "plan looks good" line actually sent -- that is what keeps `list` and
+// `export` reading as research instead of as protocol chatter.
+function rootPrompt(task) {
+  let cur = task;
+  const seen = new Set([task.id]);
+  while (cur.parent_id && !seen.has(cur.parent_id)) {
+    seen.add(cur.parent_id);
+    const parent = store.getTask(cur.parent_id);
+    if (!parent) break;
+    cur = parent;
+  }
+  return cur.prompt;
+}
+
+// `refine` (another plan) and `approve` (the report) are the same submission --
+// same agent, same tag, linked to the plan by previous_interaction_id --
+// differing only in the collaborative_planning flag they send, the kind they
+// store and the line they print. So they share one path, and the spend guard is
+// on it exactly once.
+async function continuePlan(plan, opts, turn) {
+  let id;
+  try {
+    if (opts.dryRun) {
+      emit(
+        opts.json,
+        {
+          dry_run: true,
+          agent: plan.agent,
+          kind: turn.kind,
+          parent_id: plan.id,
+          previous_interaction_id: plan.interaction_id,
+          input: turn.input,
+        },
+        () => console.log(dryRunSpend(plan.agent, 1, turn.planning))
+      );
+      return;
+    }
+    await confirmSpend(plan.agent, 1, opts, turn.planning);
+    id = store.createTask({
+      prompt: turn.prompt,
+      agent: plan.agent,
+      tag: plan.tag,
+      kind: turn.kind,
+      parentId: plan.id,
+      collaborativePlanning: turn.planning,
+      previousInteractionId: plan.interaction_id,
+    });
+    const r = await gemini.submit(turn.input, {
+      agent: plan.agent,
+      collaborativePlanning: turn.planning,
+      previousInteractionId: plan.interaction_id,
+    });
+    store.setInteraction(id, r.interactionId, r.status);
+    emit(
+      opts.json,
+      { id, interaction_id: r.interactionId, status: r.status, kind: turn.kind, parent_id: plan.id },
+      () => console.log(turn.line(id))
+    );
+  } catch (err) {
+    markSubmitFailure(id, err);
+    die(expiredHint(err, plan));
+  }
+}
+
 // --- input ----------------------------------------------------------------
 
 function readStdin() {
@@ -230,7 +453,7 @@ async function refresh(task) {
     // the end of time. Any other error (5xx, network) is transient and is
     // re-thrown for the caller to retry on its next pass.
     if (err && err.httpStatus === 404) {
-      store.setStatus(task.id, 'incomplete', { error: 'interaction not found (expired or deleted)' });
+      store.setStatus(task.id, 'incomplete', { error: EXPIRED_ERROR });
       return { status: 'incomplete', text: null, usage: null, raw: null };
     }
     throw err;
@@ -249,6 +472,18 @@ async function refresh(task) {
   return r;
 }
 
+// Only a failed *submit* should mark a task failed. Once it has an
+// interaction_id it is live on the server, and a later watch/poll error must
+// never overwrite it to failed -- that would drop it from the active set and the
+// daemon would abandon a task whose result is still coming. Leave it active; the
+// daemon (or a later `get`) collects it. Every command that submits calls this
+// on its way out, so the rule cannot drift between them.
+function markSubmitFailure(id, err) {
+  if (!id) return;
+  const t = store.getTask(id);
+  if (!t || !t.interaction_id) store.setStatus(id, 'failed', { error: err.message });
+}
+
 // Bounds how many polls are open at once. The *rate* limit is enforced in
 // gemini.js (GEMCATCH_RPM), which is the part that keeps a wide fan-out inside the
 // free tier's requests-per-minute allowance.
@@ -280,6 +515,7 @@ program
   .option('-f, --file <path>', 'read the prompt from a file')
   .option('-m, --model <id>', 'model to use', gemini.DEFAULT_MODEL)
   .option('-a, --agent <id>', 'submit to a research agent instead of a model (e.g. deep-research)')
+  .option('--plan', 'ask the agent for a research plan first, to refine and approve (needs --agent)')
   .option('-s, --system <text>', 'system instruction')
   .option('-t, --tag <tag>', 'label for filtering with `gemcatch list --tag`')
   .option('-w, --watch', 'wait for the result instead of exiting')
@@ -292,44 +528,50 @@ program
     try {
       const agent = resolveAgentOpts(opts, cmd);
       const prompt = await resolvePrompt(promptArg, opts);
+      // undefined, not false: an ordinary run must keep sending no agent_config
+      // at all, exactly as it did before collaborative planning existed.
+      const planning = opts.plan ? true : undefined;
       if (opts.dryRun) {
-        emit(opts.json, { dry_run: true, agent: agent || null, model: agent ? null : opts.model, prompt }, () => {
-          if (agent) console.log(`${spendLine(agent, 1)}. Nothing submitted (--dry-run).`);
-          else console.log(`Would submit to ${opts.model}: ${snippet(prompt)}. Nothing submitted (--dry-run).`);
-        });
+        emit(
+          opts.json,
+          { dry_run: true, agent: agent || null, model: agent ? null : opts.model, plan: !!opts.plan, prompt },
+          () => {
+            if (agent) console.log(dryRunSpend(agent, 1, opts.plan));
+            else console.log(`Would submit to ${opts.model}: ${snippet(prompt)}. Nothing submitted (--dry-run).`);
+          }
+        );
         return;
       }
-      if (agent) await confirmSpend(agent, 1, opts);
+      if (agent) await confirmSpend(agent, 1, opts, opts.plan);
       id = store.createTask({
         prompt,
         model: agent ? null : opts.model,
         agent,
         systemInstruction: opts.system,
         tag: opts.tag,
+        kind: opts.plan ? 'plan' : 'task',
+        collaborativePlanning: planning,
+      });
+      const r = await gemini.submit(prompt, {
+        model: opts.model,
+        agent,
+        systemInstruction: opts.system,
+        collaborativePlanning: planning,
       });
-      const r = await gemini.submit(prompt, { model: opts.model, agent, systemInstruction: opts.system });
       store.setInteraction(id, r.interactionId, r.status);
       if (opts.watch) {
         // Under --watch the submit line is progress, not the answer, so it
         // goes to stderr -- `gemcatch research -w "..." > out.txt` then captures
         // only the result.
-        if (!opts.json) console.error(edim(`Task ${id} submitted.`));
+        if (!opts.json) console.error(edim(`${opts.plan ? 'Plan task' : 'Task'} ${id} submitted.`));
         await watchTask(store.getTask(id), DEFAULT_POLL_MS, opts.json);
         return;
       }
-      emit(opts.json, { id, interaction_id: r.interactionId, status: r.status }, () =>
-        console.log(`Task ${id} submitted. Run: gemcatch get ${id} when ready.`)
+      emit(opts.json, { id, interaction_id: r.interactionId, status: r.status, kind: opts.plan ? 'plan' : 'task' }, () =>
+        console.log(`${opts.plan ? 'Plan task' : 'Task'} ${id} submitted. Run: gemcatch get ${id} when ready.`)
       );
     } catch (err) {
-      // Only a failed *submit* should mark the task failed. Once it has an
-      // interaction_id it is live on the server, and a later watch/poll error
-      // must never overwrite it to failed -- that would drop it from the active
-      // set and the daemon would abandon a task whose result is still coming.
-      // Leave it active; the daemon (or a later `get`) collects it.
-      if (id) {
-        const t = store.getTask(id);
-        if (!t || !t.interaction_id) store.setStatus(id, 'failed', { error: err.message });
-      }
+      markSubmitFailure(id, err);
       die(err);
     }
   });
@@ -412,6 +654,7 @@ program
   .argument('<file>', 'prompts file — one per line, or "-" to read stdin')
   .option('-m, --model <id>', 'model to use', gemini.DEFAULT_MODEL)
   .option('-a, --agent <id>', 'submit every prompt to a research agent instead of a model')
+  .option('--plan', 'ask the agent for a research plan per prompt, to refine and approve (needs --agent)')
   .option('-s, --system <text>', 'system instruction')
   .option('-t, --tag <tag>', 'tag the whole batch (default: batch-<hex>)')
   .option('--separator <str>', 'split the file on this delimiter line for multi-line prompts')
@@ -434,11 +677,14 @@ program
       // Auto-tag so the batch is collectable as a unit; a user tag wins.
       const tag = opts.tag || `batch-${crypto.randomUUID().slice(0, 6)}`;
 
+      // undefined, not false: an ordinary run must keep sending no agent_config.
+      const planning = opts.plan ? true : undefined;
+
       if (opts.dryRun) {
-        emit(opts.json, { tag, dry_run: true, agent: agent || null, prompts }, () => {
+        emit(opts.json, { tag, dry_run: true, agent: agent || null, plan: !!opts.plan, prompts }, () => {
           if (agent) {
             // The whole point of the guard: N × the per-task band, up front.
-            console.log(`${spendLine(agent, prompts.length)}. Nothing submitted (--dry-run).`);
+            console.log(dryRunSpend(agent, prompts.length, opts.plan));
           } else {
             console.log(`Batch ${tag}: ${prompts.length} prompt(s) would be submitted:`);
             for (const p of prompts) console.log(`  ${snippet(p)}`);
@@ -449,14 +695,27 @@ program
 
       // An agent batch multiplies a per-task dollar band by the whole file, so
       // it is confirmed as one total before a single row is written.
-      if (agent) await confirmSpend(agent, prompts.length, opts);
+      if (agent) await confirmSpend(agent, prompts.length, opts, opts.plan);
 
       // One failed submit must not sink the batch: mark that task failed and
       // keep going. mapLimit preserves input order, so the report is stable.
       const results = await mapLimit(prompts, 4, async (prompt) => {
-        const id = store.createTask({ prompt, model: agent ? null : opts.model, agent, systemInstruction: opts.system, tag });
+        const id = store.createTask({
+          prompt,
+          model: agent ? null : opts.model,
+          agent,
+          systemInstruction: opts.system,
+          tag,
+          kind: opts.plan ? 'plan' : 'task',
+          collaborativePlanning: planning,
+        });
         try {
-          const r = await gemini.submit(prompt, { model: opts.model, agent, systemInstruction: opts.system });
+          const r = await gemini.submit(prompt, {
+            model: opts.model,
+            agent,
+            systemInstruction: opts.system,
+            collaborativePlanning: planning,
+          });
           store.setInteraction(id, r.interactionId, r.status);
           return { id, interaction_id: r.interactionId, status: r.status, prompt };
         } catch (err) {
@@ -484,9 +743,16 @@ program
           const pad = ' '.repeat(Math.max(0, 16 - status.length));
           console.log(`${r.id}  ${colorStatus(status)}${pad} ${snippet(r.prompt)}`);
         }
-        console.log(dim('\nCollect them:'));
-        console.log(dim('  gemcatch daemon --exit-when-idle'));
-        console.log(dim(`  gemcatch list --tag ${tag} --status completed`));
+        if (opts.plan) {
+          console.log(dim('\nCollect the plans, then approve the ones worth running:'));
+          console.log(dim('  gemcatch daemon --exit-when-idle'));
+          console.log(dim(`  gemcatch list --tag ${tag}`));
+          console.log(dim('  gemcatch get <id>   # prints the plan and the approve command'));
+        } else {
+          console.log(dim('\nCollect them:'));
+          console.log(dim('  gemcatch daemon --exit-when-idle'));
+          console.log(dim(`  gemcatch list --tag ${tag} --status completed`));
+        }
       });
     } catch (err) {
       die(err);
@@ -530,17 +796,19 @@ program
       // -- re-polling it would 404 after 24h, the very thing we cache to avoid.
       if (isSuccess(task.status) && task.result != null && !opts.raw) {
         const cits = parseCitations(task.citations);
-        emit(opts.json, { id: task.id, status: task.status, result: task.result, citations: cits }, () =>
-          console.log(withSources(task.result, cits))
-        );
+        emit(opts.json, resultPayload(task, task.status, task.result, cits), () => {
+          console.log(withSources(task.result, cits));
+          if (task.kind === 'plan') console.error(planFooter(task));
+        });
         return;
       }
       const r = await refresh(task);
       if (opts.raw) return console.log(JSON.stringify(r.raw, null, 2));
       if (isSuccess(r.status)) {
-        emit(opts.json, { id: task.id, status: r.status, result: r.text, citations: r.citations || null }, () =>
-          console.log(withSources(r.text, r.citations))
-        );
+        emit(opts.json, resultPayload(task, r.status, r.text, r.citations), () => {
+          console.log(withSources(r.text, r.citations));
+          if (task.kind === 'plan') console.error(planFooter(task));
+        });
       } else if (isDone(r.status)) {
         emit(opts.json, { id: task.id, status: r.status, error: r.text || null }, () =>
           console.log(`Task ${task.id}: ${colorStatus(r.status)}${r.text ? `\n${r.text}` : ''}`)
@@ -556,8 +824,80 @@ program
     }
   });
 
+// --- refine / approve -----------------------------------------------------
+
+program
+  .command('refine')
+  .argument('<id>', 'plan task id')
+  .argument('<instruction>', 'what the plan should do differently')
+  .option('--yes', 'confirm the agent cost without asking (required when stdin is not a TTY)')
+  .option('--dry-run', 'show what it would cost; submit nothing')
+  .option('--json', 'machine-readable output')
+  .description('send an instruction back to a plan and get a revised plan')
+  .action(async (id, instruction, opts) => {
+    const text = (instruction || '').trim();
+    if (!text) {
+      return die(new Error('provide an instruction, e.g. gemcatch refine 8f3a1c04 "focus on enforcement dates"'));
+    }
+    const plan = needPlan(id, 'refine');
+    await continuePlan(plan, opts, {
+      planning: true,
+      kind: 'plan',
+      input: text,
+      prompt: text,
+      line: (newId) => `Plan task ${newId} submitted (refines ${plan.id}). Run: gemcatch get ${newId} when ready.`,
+    });
+  });
+
+program
+  .command('approve')
+  .argument('<id>', 'plan task id')
+  .option('--yes', 'confirm the agent cost without asking (required when stdin is not a TTY)')
+  .option('--dry-run', 'show what it would cost; submit nothing')
+  .option('--json', 'machine-readable output')
+  .description('approve a plan and submit the research run it describes')
+  .action(async (id, opts) => {
+    const plan = needPlan(id, 'approve');
+    await continuePlan(plan, opts, {
+      planning: false,
+      kind: 'report',
+      input: APPROVE_INPUT,
+      prompt: rootPrompt(plan),
+      line: (newId) => `Task ${newId} submitted (approves plan ${plan.id}).`,
+    });
+  });
+
 // --- list -----------------------------------------------------------------
 
+// A plan chain is one piece of work, so it is listed as one: the root in its
+// normal newest-first position, its continuations indented under it in the order
+// they were submitted. A row whose parent is filtered out of this listing (by
+// --status, --tag or -n) is rendered as its own root rather than dropped.
+function chainOrder(tasks) {
+  const present = new Set(tasks.map((t) => t.id));
+  const kids = new Map();
+  for (const t of tasks) {
+    if (!t.parent_id || !present.has(t.parent_id)) continue;
+    if (!kids.has(t.parent_id)) kids.set(t.parent_id, []);
+    kids.get(t.parent_id).push(t);
+  }
+  for (const list of kids.values()) list.sort((a, b) => a.created_at - b.created_at);
+  const out = [];
+  const seen = new Set();
+  const walk = (t, depth) => {
+    if (seen.has(t.id)) return;
+    seen.add(t.id);
+    out.push({ task: t, depth });
+    for (const c of kids.get(t.id) || []) walk(c, depth + 1);
+  };
+  for (const t of tasks) if (!t.parent_id || !present.has(t.parent_id)) walk(t, 0);
+  // A listing must never lose a row. Nothing the CLI writes can put a cycle in
+  // parent_id, but a row that is unreachable from any root would otherwise
+  // vanish silently, so anything left over is rendered flat.
+  for (const t of tasks) walk(t, 0);
+  return out;
+}
+
 program
   .command('list')
   .alias('ls')
@@ -578,21 +918,27 @@ program
       console.log('No tasks yet. Submit one:  gemcatch research "your question"');
       return;
     }
-    // The AGENT column only appears when something in the listing used one, so
-    // a pure-model store keeps the compact four-column layout it always had.
-    // Agent ids are shown compact -- the "-preview-MM-YYYY" suffix is version
-    // noise in a table (the full id is in --json and in stats).
+    // The AGENT and KIND columns only appear when something in the listing uses
+    // them, so a pure-model store keeps the compact four-column layout it always
+    // had. Agent ids are shown compact -- the "-preview-MM-YYYY" suffix is
+    // version noise in a table (the full id is in --json and in stats).
     const showAgent = tasks.some((t) => t.agent);
+    const showKind = tasks.some((t) => t.kind && t.kind !== 'task');
     const shortAgent = (a) => (a ? a.replace(/-preview-\d{2}-\d{4}$/, '') : '-');
-    console.log(dim(`ID        AGE   STATUS           ${showAgent ? 'AGENT              ' : ''}PROMPT`));
-    for (const t of tasks) {
-      const snip = snippet(t.prompt);
+    console.log(
+      dim(`ID        AGE   STATUS           ${showKind ? 'KIND    ' : ''}${showAgent ? 'AGENT              ' : ''}PROMPT`)
+    );
+    for (const { task: t, depth } of chainOrder(tasks)) {
       const status = t.status || PENDING;
       // Pad before colouring: ANSI codes would break the column width.
       const pad = ' '.repeat(Math.max(0, 16 - status.length));
+      const kindCol = showKind ? `${(t.kind || 'task').padEnd(7)} ` : '';
       const agentCol = showAgent ? `${shortAgent(t.agent).padEnd(18)} ` : '';
+      // Indent the prompt, not the id: the fixed-width columns stay aligned and
+      // the chain still reads as one thing.
+      const branch = depth ? `${'  '.repeat(depth - 1)}└─ ` : '';
       console.log(
-        `${t.id}  ${age(t.created_at).padEnd(4)}  ${colorStatus(status)}${pad} ${agentCol}${snip}`
+        `${t.id}  ${age(t.created_at).padEnd(4)}  ${colorStatus(status)}${pad} ${kindCol}${agentCol}${branch}${snippet(t.prompt)}`
       );
     }
   });
@@ -609,6 +955,7 @@ program
   .addOption(new Option('--status <status>', 'only this status').choices(ALL_STATUSES).default('completed'))
   .addOption(new Option('--format <fmt>', 'output format').choices(['md', 'json']).default('md'))
   .option('-o, --out <file>', 'write to a file instead of stdout')
+  .option('--include-plans', 'also export the plan turns of a chain, not just its report')
   .description('concatenate finished results, each under its prompt, to stdout or a file')
   .action((opts) => {
     const tasks = store.listTasks({ tag: opts.tag, status: opts.status });
@@ -617,11 +964,19 @@ program
     tasks.reverse();
     // Only rows that actually carry a result are worth exporting: a status
     // filter other than `completed` can match tasks that never stored text.
-    const rows = tasks.filter((t) => t.result != null);
+    // A chain's plan turns are working notes on the way to its report, so an
+    // export of a tag follows the chain to the report and leaves them out
+    // unless they were asked for.
+    const rows = tasks.filter((t) => t.result != null && (opts.includePlans || t.kind !== 'plan'));
     if (!rows.length) {
       // Nothing to write isn't an error, but say why so an empty -o file (or an
       // empty pipe) isn't a mystery. The note goes to stderr, never the output.
       console.error(`No ${opts.status} results to export${opts.tag ? ` for tag '${opts.tag}'` : ''}.`);
+      // A chain with no approved run yet has plans and nothing else, which would
+      // otherwise read as "there is nothing here".
+      if (!opts.includePlans && tasks.some((t) => t.result != null && t.kind === 'plan')) {
+        console.error('  Only plan turns matched. Approve one (gemcatch approve <id>), or pass --include-plans.');
+      }
       return;
     }
 
@@ -632,6 +987,7 @@ program
           id: t.id,
           tag: t.tag,
           status: t.status,
+          kind: t.kind || 'task',
           prompt: t.prompt,
           result: t.result,
           created_at: t.created_at,
@@ -645,7 +1001,8 @@ program
           const when = new Date(t.created_at).toISOString().replace('T', ' ').slice(0, 16);
           const head = (t.prompt || '(no prompt)').replace(/\s+/g, ' ').trim();
           const body = t.result && t.result.trim() ? t.result : '_(empty result)_';
-          return `## ${head}\n\n\`${t.id}\` · ${t.status} · ${when} UTC\n\n${body}`;
+          const kind = t.kind && t.kind !== 'task' ? ` · ${t.kind}` : '';
+          return `## ${head}\n\n\`${t.id}\` · ${t.status}${kind} · ${when} UTC\n\n${body}`;
         })
         .join('\n\n---\n\n');
     }
@@ -699,11 +1056,7 @@ program
       if (!opts.json) console.error(edim(`Digesting ${done.length} result(s) tagged ${opts.tag} -> task ${id}.`));
       await watchTask(store.getTask(id), DEFAULT_POLL_MS, opts.json);
     } catch (err) {
-      // Same rule as `research`: only a failed *submit* marks the task failed.
-      if (id) {
-        const t = store.getTask(id);
-        if (!t || !t.interaction_id) store.setStatus(id, 'failed', { error: err.message });
-      }
+      markSubmitFailure(id, err);
       die(err);
     }
   });
@@ -861,9 +1214,10 @@ async function watchTask(task, intervalMs, json) {
       last = r.status;
     }
     if (isSuccess(r.status)) {
-      emit(json, { id: task.id, status: r.status, result: r.text, citations: r.citations || null }, () =>
-        console.log(withSources(r.text, r.citations))
-      );
+      emit(json, resultPayload(task, r.status, r.text, r.citations), () => {
+        console.log(withSources(r.text, r.citations));
+        if (task.kind === 'plan') console.error(planFooter(task));
+      });
       return;
     }
     if (isDone(r.status)) {
@@ -891,9 +1245,10 @@ program
       // empty-text completion is served instead of re-polled (and lost at 24h).
       if (isSuccess(task.status) && task.result != null) {
         const cits = parseCitations(task.citations);
-        emit(opts.json, { id: task.id, status: task.status, result: task.result, citations: cits }, () =>
-          console.log(withSources(task.result, cits))
-        );
+        emit(opts.json, resultPayload(task, task.status, task.result, cits), () => {
+          console.log(withSources(task.result, cits));
+          if (task.kind === 'plan') console.error(planFooter(task));
+        });
         return;
       }
       if (opts.interval != null && (!Number.isFinite(opts.interval) || opts.interval <= 0)) {
@@ -983,20 +1338,44 @@ program
 program
   .command('stats')
   .option('--json', 'machine-readable output')
-  .description('where the store lives and what is in it')
+  .description('where the store lives, what is in it, and what the agent runs have plausibly cost')
   .action((opts) => {
     const rows = store.counts();
     const agents = store.agentCounts();
+    const kinds = store.kindCounts();
     const total = rows.reduce((n, r) => n + r.n, 0);
-    emit(opts.json, { db: store.DB_PATH, total, by_status: rows, by_agent: agents }, () => {
-      console.log(`Store: ${store.DB_PATH}`);
-      console.log(`Tasks: ${total}`);
-      for (const r of rows) console.log(`  ${colorStatus(r.status).padEnd(useColor ? 26 : 17)} ${r.n}`);
-      if (agents.length) {
-        console.log('Agent runs:');
-        for (const a of agents) console.log(`  ${a.agent.padEnd(34)} ${a.n}`);
+    // Priced from the runs that actually reached the server, not from every
+    // attempt: a submit that failed before it left the machine cost nothing.
+    const spend = estimatedSpend(store.billedAgentCounts());
+    emit(
+      opts.json,
+      { db: store.DB_PATH, total, by_status: rows, by_agent: agents, by_kind: kinds, estimated_spend: spend },
+      () => {
+        console.log(`Store: ${store.DB_PATH}`);
+        console.log(`Tasks: ${total}`);
+        for (const r of rows) console.log(`  ${colorStatus(r.status).padEnd(useColor ? 26 : 17)} ${r.n}`);
+        if (agents.length) {
+          console.log('Agent runs:');
+          for (const a of agents) console.log(`  ${a.agent.padEnd(34)} ${a.n}`);
+        }
+        if (kinds.length) {
+          console.log(`Plan chains: ${kinds.map((k) => `${k.n} ${k.kind}`).join(', ')}`);
+        }
+        if (spend && !spend.tasks) {
+          console.log(
+            `Estimated spend: unknown for ${spend.unpriced} agent task(s) on an agent with no published price band.`
+          );
+        } else if (spend) {
+          const rest = spend.unpriced
+            ? `, plus ${spend.unpriced} on an agent with no published band`
+            : '';
+          console.log(
+            `Estimated spend: $${spend.low.toFixed(2)}–$${spend.high.toFixed(2)} across ${spend.tasks} billed task(s)` +
+              ` (preview rates, subject to change)${rest}.`
+          );
+        }
       }
-    });
+    );
   });
 
 // Close the store on the way out so a one-shot command doesn't leave the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemcatch",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Fire-and-forget CLI for Gemini's Interactions API background execution. Submit long-running research prompts, close your laptop, collect results later.",
   "main": "index.js",
   "bin": {
@@ -51,7 +51,7 @@
     "commander": "^15.0.0"
   },
   "allowScripts": {
-    "@google/genai@2.15.0": true,
+    "@google/genai@2.16.0": true,
     "protobufjs@7.6.5": true
   }
 }