feat(agent): let plan mode read the database it plans against, and draft the SQL

[cevheri]

Plan mode was built to be the safe mode: it reaches nothing, executes nothing, and hands you a
statement you run yourself. What it did instead was lecture.

Asked "What are the popular films and actors?" against a PostgreSQL connection holding the dvdrental
sample database, it answered with a four-step generic investigation plan that would have read
identically against any database in the world, opening with "I have no schema inventory available to
this run and have not seen this database at all."

That is not a model failure. It is what the code asked for, and there were two independent causes.

Cause 1 — plan mode never read a schema, it scavenged one

investigation.ts skipped the whole context-establishing path for a planning run and consulted one
in-process map instead:

const inventory = heldSnapshotForConnection(record.connectionId);
if (inventory === null) return;   // schemaKnown stays false

heldSnapshotForConnection is an LRU held in the serving process, and the only thing that fills it is
a prior agent-mode run on the same connection in the same process. So plan mode was blind whenever
the user had not run agent mode first, whenever the server had restarted, and whenever a second replica
served the request. The safe mode's usefulness was conditional on having already used the unsafe
one.

#384 added PLANNING_SCHEMA_RULES for the grounded case. It fixed the wording of a path that is
rarely taken; it did not make the path reachable.

Cause 2 — even when grounded, the contract asked for a lecture

The mode's governing rule was:

"Answer with a plan in prose: what you would inspect, in what order, and what each step would
establish."

Nothing in either the grounded or the ungrounded half ever asked for a statement. Fixing cause 1 alone
would have produced the same numbered inspection plan with real table names in it.

Why it stayed broken

verifyPlanningGoal passed a planning run that left any non-empty prose. The lecture above scored
as a success. Nothing in the repository could tell the two apart.

---

What this changes

Plan mode grounds itself. A planning run now establishes context the way an agent run does —
server-side, before the first turn — and then takes its turns with no tools, exactly as before. The
model stays toolless; grounding is the server's work, so the capability gate, the probe and the
toolless-set assertions are untouched.

The contract that changes, and the one that does not. "A plan run reaches no database" is now
false and is rewritten wherever it was asserted. That sentence was never the safety property; it was a
proxy for it. What replaces it is the property the product actually sells: plan mode runs no
statement of the user's, writes nothing, and hands every statement it drafts to the user to run
themselves. Reading a catalog is what the sidebar already does on every connect.

The profile is read from engine statistics, not from scans. Row counts, null fractions and
distinct counts come from pg_class.reltuples / pg_stats and sqlite_stat1 — catalog reads, zero
table scans. A COUNT(DISTINCT col) per column would have been a full scan, which is unacceptable in a
mode whose selling point is "open it against production without worrying".

Three honesty requirements follow, because these numbers are estimates:

• everything derived from them is labelled an estimate in the text the model sees;
• pg_stats.n_distinct is negative when it expresses a ratio, converted only against a row estimate
  and marked derived;
• absence is not zero. A table never ANALYZEd has no statistics, and is listed as having none:
  "a table listed below as having no statistics is a table whose size is UNKNOWN to you — it is not an
  empty table, and nothing here entitles you to call it small." Silence read as zero would make the
  model refuse to join a real table.

No column values are read at any point. pg_stats carries sample values in most_common_vals; they
are not selected.

The deliverable is a statement. One runnable statement in a fence tagged with the connection's
canonical type-id (the tag rich-text.tsx already reads, so the editor hand-off is never lost to a
tag it does not know), rationale after it, no identifier absent from the inventory. Plan deliverables
are a total record over AgentRunWorkflowType, so a new workflow stops the file compiling until
someone decides what a plan of it hands back. operations is the exception by decision: it reads no
schema and composes no SQL.

The refusal is a first-class ending. When the inventory does not support the question the run
writes no statement and begins a line with NO STATEMENT:, naming what is missing and asking the one
question that would unblock it. A convention in the output rather than a tool, which is what lets a
toolless mode make its two outcomes mechanically distinguishable.

The statement is a ledger fact, not a parse. A new plan-statement-drafted event carries the SQL,
the dialect, the guard's classification and what validation found. This closes B44 — the browser no
longer depends on the model having fenced its SQL for the editor hand-off to exist.

The verdict stops accepting a lecture. A new no-statement shortfall: a planning run passes when
it produced either a drafted statement or an explicit refusal. Prose with neither is a shortfall,
however long. Without this the fix would regress silently the first time a prompt was reworded.

What review caught that the build did not

Two adversarial reviewers read the whole diff. All seven findings were verified against the code and
all seven were real.

• The write marking was defeated in practice. The closing prose is still rendered through
  renderProse with onApplySql, so the same DELETE also got an unmarked "Apply to editor" button
  from rich-text.tsx directly above the marked card. The rail now withholds the prose hand-off for a
  closing entry whose statement the ledger already recorded; feat(agent): let a plan's SQL be copied, and reach the editor #389's fallback is untouched everywhere
  else.
• A classification was stated as stronger than it is. readOnly === false is the statement guard's
  objection, which includes "two statements", "no statement" and text no single dialect reading
  settles — and the guard deliberately over-refuses some legitimate reads. The card said "This is not a
  read … can change or delete data". A pure SELECT ... #>> ... would have been shown to the user, and
  to a screen reader, as SQL that can delete their data. It now reports what the guard actually said,
  and shows the reason.
• Three documents still published the retired contract after every other doc was rewritten, and one
  design record asserted the opposite decision as settled.
• plan-statement.ts claimed an agreement with rich-text.tsx that did not hold on the fence info
  string. Fixed by extracting the shared predicate to src/lib/sql/fence-tags.ts rather than by
  editing the docblock, so the two readers cannot drift again.

Honest limits, stated in the docs

• Grounding works on PostgreSQL and SQLite only — the dialects the catalog composers serve. On any
  other engine a plan run is ungrounded, knows it, and is steered to the refusal path rather than left
  to produce generic advice as though it were an answer.
• A statement validated against the inventory is not a statement that will run. The inventory
  records what exists, not what the user's role may select from.

Not in this change

Exact COUNT(DISTINCT) scanning, sample rows and distinct-value listing (the depth decision was counts
only); a persisted connection-level data dictionary; and renaming the mode, which now under-describes
itself but touches storage, the rail, the docs and the API surface.

Verification

All six local gates green: format, lint, typecheck, knip, test, build.

[Copilot]

Pull request overview

Grounds Plan mode with audited schema/statistics reads and records its SQL deliverable for validation and editor handoff.

Changes:

• Adds PostgreSQL/SQLite catalog-statistics grounding.
• Records and validates drafted statements or explicit refusals.
• Updates the rail, verifier, tests, and documentation for the new contract.

Reviewed changes

Copilot reviewed 38 out of 38 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/lib/agent/investigation.ts	Grounds planning runs and records drafts.
src/lib/agent/composed-sql.ts	Composes statistics catalog reads.
src/lib/agent/context-snapshot.ts	Enables server-side planning capture.
src/lib/agent/schema-stats.ts	Reads and packs estimated statistics.
src/lib/agent/plan-statement.ts	Extracts and validates plan SQL.
src/lib/agent/goal-verifier.ts	Requires a statement or refusal.
src/lib/agent/tools.ts	Adds audited grounding operations.
src/lib/agent/types.ts	Defines the drafted-statement event.
src/lib/agent/run-store.ts	Recognizes the new event.
src/lib/agent/run-service.ts	Classifies drafts as narrative events.
src/lib/sql/fence-tags.ts	Shares query-fence recognition.
src/components/rich-text.tsx	Uses shared fence-tag logic.
src/components/agent/timeline.ts	Folds drafts and refusals for display.
src/components/agent/AgentRail.tsx	Adds marked statement/refusal cards.
tests/unit/lib/agent/types.test.ts	Covers event serialization shape.
tests/unit/lib/agent/tools.test.ts	Covers the grounding execution seam.
tests/unit/lib/agent/schema-stats.test.ts	Covers statistics reading and packing.
tests/unit/lib/agent/plan-statement.test.ts	Covers extraction and validation.
tests/unit/lib/agent/goal-verifier.test.ts	Covers planning verdicts.
tests/unit/lib/agent/context-snapshot.test.ts	Covers planning snapshot capture.
tests/unit/lib/agent/composed-sql.test.ts	Covers statistics SQL composition.
tests/unit/components/agent-timeline.test.ts	Covers timeline presentation.
tests/unit/agent-policy-gates.test.ts	Preserves the toolless-model gate.
tests/isolated/agent-investigation.test.ts	Exercises planning grounding end to end.
tests/isolated/fixtures/agent-eval-harness.ts	Adds grounding/statistics fixtures.
tests/evals/real-model.ts	Updates live-model expectations.
tests/evals/plan-grounding.test.ts	Evaluates cold-process grounding.
tests/evals/investigation-arc.test.ts	Evaluates statement/refusal outcomes.
tests/components/agent/AgentRail.test.tsx	Covers cards and accessible warnings.
README.md	Updates Plan-mode behavior.
docs/FEATURES.md	Documents grounding limits.
docs/BACKLOG.md	Retires completed gaps and adds B45.
docs/API_DOCS.md	Updates the API mode contract.
docs/AGENT.md	Documents runtime grounding behavior.
docs/AGENT_GUIDE.md	Explains statements and refusals.
docs/AGENT_DEMO.md	Revises the demo narrative.
docs/AGENT_DATA_FLOW.md	Documents server grounding reads.
docs/AGENT_ANALYST_DESIGN.md	Records the superseded decision.

Suppressed comments (1)

src/components/agent/timeline.ts:1111

• drafted is global to the entire ledger, so one drafted event marks every planning closing as statement-backed. A supported resume can contain multiple closings (for example, a refusal appended before a crash, followed by a drafted statement after resume); the earlier refusal then skips refusal rendering and leaks the NO STATEMENT: protocol token. Pair each drafted event only with the immediately preceding closing entry.

    if (drafted) {
      // The prose the statement was read OUT of, so the deliverable is in this text
      // as well as on the card below it. The surface is told, because the per-block
      // control inside prose cannot say what it is applying.
      items[index] = { ...item, planStatementRecorded: true };

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cevheri]

All six verified against the code, all six real, all six fixed in f889000.

1. A bare NO STATEMENT: scored as a refusal — readPlanStatement now requires substantive text
after the marker; a bare token reads as absent and the verdict reports no-statement. The bar is
substance and deliberately not a question mark: "Tell me which column records the rental price." is
a proper request and carries none. A bare marker also no longer suppresses a real block written
beside it, since refusal-beats-block only applies to an actual refusal.

2. A conflicting engine tag was relabelled — the sharpest of the six. isQueryFenceTag answers
"is this a query", which is yes for mysql on a PostgreSQL run, and the recorder then stamps the
event with the connection's dialect. New fenceTagEngine in src/lib/sql/fence-tags.ts says which
engine a tag names, including through unambiguous aliases (pgsql → postgres, tsql → mssql).
sql and an untagged fence name none, so they contradict none; only an explicit engine can. A block
naming another engine is not a deliverable, and a conflicting block no longer hides the run's real
one.

3. Only the first doubled delimiter unescaped — replaceAll. Exactly as described: "a""b""c"
came back a"b""c and a real table was reported unknown.

4. Quoted aliases ended the comma list — the alias step now reads with readNamePart rather than
readSqlWord, and handles the bare quoted alias (t "x", u) as well as AS "x". Both forms of
FROM film AS "f", payments now name both tables.

Findings 3 and 4 belong together: each made the validation quietly weaker than the sentence
describing it, one by rejecting a real table and one by never looking at an invented one.

5. The marker inside a non-query fence — fixed by removing the second reader rather than by
teaching it about fences. src/lib/db/operations/statement-guard.ts imports only zod and the SQL
span/word helpers, so plan-statement.ts is client-safe, and timeline.ts now asks
readPlanStatement directly. There is no longer a pair that can disagree.

Worth recording why the old code's defence failed, because the reasoning was sound and the covered
set was not. Its docblock argued the two readers could not disagree since the regex is consulted only
when the ledger holds no statement — but a ```text block containing the marker records no
statement either, which is precisely your example. The regex survives for the display strip alone,
now downstream of the shared ruling.

6. Three surfaces still publishing the retired contract — .env.example:250 and
DOCKERHUB.md:107 fixed, and docs/AGENT_DEMO.md ("sends no statements at all") with them. You were
right that the PR body overclaimed: the sweep covered docs/ and the README and missed the env
sample and the Docker Hub page.

---

Two notes from fixing these, since both bear on how much the green checks were worth.

One of the tests I replaced asserted the bug: "a refusal marker with nothing after it is still a refusal". It passed, it was covered, and it pinned the wrong behaviour.

And one fixture was self-contradictory — a fenced() helper hardcoding a ```postgres tag, used by
a test running on a mongodb connection. Finding 2's fix broke it, which is to say the break was the
fix working. The tag is a parameter now, because it is a claim rather than syntax.

Gates green after the fixes: format, lint (0 errors), typecheck, knip, test (28/28 groups),
build, and coverage at 35799/35799 lines (100.00%).

[Copilot]

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated no new comments.

Suppressed comments (6)

src/components/agent/AgentRail.tsx:510

• This caveat now contradicts the mode’s implementation: a grounded Plan run executes several catalog/statistics statements before the model turn. Say that the drafted statement (or no statement of the user’s) was executed, rather than claiming the run executed nothing.

      <p data-testid="agent-plan-statement-caveat" className="mt-1 text-[0.625rem] text-zinc-600">
        The run executed nothing. What was checked is what this run read of the schema, which records what exists rather
        than what your role is permitted to read.

src/components/agent/AgentRail.tsx:1436

• This message is false for the documented ungrounded path (for example MySQL): no schema was read there, yet its required NO STATEMENT: response renders as though a read schema failed to answer. Use wording that covers both a missing inventory and an insufficient inventory.

                    <p className="text-[0.625rem] text-amber-300">
                      This run drafted no statement: it reports that the schema it read does not answer the question as
                      asked. What it says is missing, and what it needs from you, are in its own words below.
                    </p>

src/components/agent/timeline.ts:396

• The fence-aware reader may select a later refusal, but this fence-blind replace always removes the first marker. For prose containing a marker in a ```text block before the real refusal, it mutates the example and leaves the actual protocol marker visible/copyable, contradicting the refusal-card contract. Strip the exact refusal occurrence found outside fences.

function readPlanRefusal(prose: string | undefined): string | null {
  if (prose === undefined || readPlanStatement(prose).kind !== "refusal") return null;
  return prose.replace(PLAN_REFUSAL_MARKER, "");

src/components/agent/timeline.ts:1117

• drafted is run-global, so one plan-statement-drafted event marks every planning closing in the ledger as carded. A process can resume a running run after crashing between recording a closing and finishing it; if either attempt drafted SQL, unrelated closings/refusals are then misclassified and lose their prose editor affordance. Associate each draft only with the immediately preceding closing event.

    const item = items[index];
    if (drafted) {
      // The prose the statement was read OUT of, so the deliverable is in this text
      // as well as on the card below it. The surface is told, because the per-block
      // control inside prose cannot say what it is applying.
      items[index] = { ...item, planStatementRecorded: true };

src/lib/agent/plan-statement.ts:249

• ONLY is a PostgreSQL table modifier, not the end of the table position. With this rule, valid SQL such as SELECT * FROM ONLY payments reports no referenced tables, so a missing table escapes unknownTables and the UI presents the identifier check as clean. Skip the modifier and continue by reading the following relation name.

const NOT_A_TABLE_NAME: ReadonlySet<string> = new Set(["ONLY", "LATERAL", "UNNEST", "VALUES", "SELECT", "DUAL"]);

src/lib/agent/investigation.ts:1202

• This cache lookup verifies only the connection ID, even though an existing connection can be edited in place with the same ID and a different host/database. The Plan run can therefore receive and validate against the previous database’s inventory instead of taking the new grounding path. Key or validate held snapshots against immutable target identity before reusing them.

    const recorded = reusableSnapshot(record.events, record.connectionId);
    const held = recorded === null ? heldSnapshotForConnection(record.connectionId) : null;
    let snapshot = recorded ?? held;

[cevheri]

Correction to my reply above, on finding 5.

I wrote: "statement-guard.ts imports only zod and the SQL span/word helpers, so plan-statement.ts
is client-safe." That was wrong, and the E2E security-headers spec proved it in chromium and webkit:
script-src blocked eval.

zod v4 probes new Function("") at module load to decide whether it may compile validators. The
throw is caught, but a browser under a strict CSP fires securitypolicyviolation anyway — zod's own
source carries a comment about exactly this. So giving the rail the server's reader put an eval probe
on every page rendering an agent run.

The mistake is worth naming precisely, because it is the same class this PR was congratulating itself
for catching: I inspected the module's direct imports and concluded it was safe. The transitive
closure is what the policy measures.

Fixed in 5e07c27. The reading half moves to src/lib/agent/plan-draft.ts, which may import nothing
but types and the fence-tag predicate; plan-statement.ts keeps the validation half and the guard
with it. The one-reader property finding 5 asked for is unchanged — the rail, the verdict and the
recorder all go through plan-draft.

Measured rather than argued this time: built both ways and grepped the client chunks for zod's own
jitless marker — one chunk with the old import, zero with the new — and the failing
e2e/security-headers.spec.ts passes locally against this build.

tests/unit/lib/agent/plan-draft-boundary.test.ts pins the allowed imports as an exact set rather
than a prefix rule. "Anything under @/lib/sql" would admit the grammar and span readers, which are
pure today and one commit from not being — and admitting a module for where it sits is the reasoning
that admitted the guard in the first place.

[sonarqubecloud]

Quality Gate passed

Issues
11 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud