fix(agent): address PR #1092 review findings from Bugbot and CodeRabbit

- `sql_explain` analyze-safety guard hardened: string literals are masked
  BEFORE comments (comments-first was bypassable via quoted `/*`..`*/` markers
  smuggling DML), multi-statement payloads rejected (non-trailing `;`), and
  dollar-quoted strings fail closed; adversarial tests added
- rewrite verify gate tightened from `decidable !== false` to
  `decidable === true` — the field is required since altimate-core@0.5.1, so a
  missing value is a malformed response and fails closed
- `sql_diff` now forwards `schema_context`/`dialect` to the native handler
  (equivalence never ran before — no schema ever reached it) and reports
  "not assessed" instead of "not proven" when no schema is supplied
- warehouse-write boundary wording aligned: the agent description and prompt
  now state that the direct SQL write tool is denied non-overridably while dbt
  builds run only as user-approved shell commands against a dev target; a new
  test documents the boundary under permissive global + per-agent bash
  overrides (builds allowed, DDL and sql_execute_write still denied)
- live eval: tmpdir cleanup via `await using tmpdir()` on all exit paths;
  nonzero CLI exit now fails the eval
- docs: https links, one-line reference labels (MD039), Databricks
  liquid-clustering citations [14]->[21], and a status note on the catalog
  research doc recording the security review's four design requirements for
  the future SaaS distribution (not built in this PR)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: anandgupta42

docs/internal/2026-08-12-agent-catalog-scaling-research.md

@@ -1,5 +1,22 @@
 # Scaling Agent Catalogs Without Losing TUI Speed
 
+> **Status: research record, not an implementation spec.** The SaaS distribution
+> design sketched below (control plane, signed bundles, capability tiers) is NOT
+> built; nothing in this document changes runtime behavior. Security review
+> flagged four design requirements that any implementation must resolve before
+> shipping, tracked here as design inputs:
+> 1. cache entries partitioned by full authorization scope + policy version, with
+>    defined offline/revocation behavior including active sessions;
+> 2. warehouse-write denial for optimizer-class agents expressed as a
+>    non-overridable deny state, not an approval tier (the shipped `dbt-optimizer`
+>    already enforces this in `agent.ts` — `sql_execute_write` deny is re-applied
+>    after all config merges);
+> 3. promotion to primary restricted to `mode: both` definitions with
+>    immutable-manifest + session-policy validation, never a safety label alone;
+> 4. a non-self-referential signature envelope (canonical serialization, signature
+>    excluded from signed bytes, algorithm + key ID) and redacted, allowlisted
+>    audit payloads.
+
 ## Executive Summary
 
 - **Hybrid Selection**: Claude Code, OpenCode, Cursor, Codex, and Cline all expose a user-facing agent that can delegate bounded work to specialists, while also offering explicit ways to invoke or configure specialists. Claude Code uses description-based routing plus explicit `@` selection, and OpenCode uses automatic invocation plus `@` mentions. [16] [16] [5] [5] -> Keep automatic delegation, but always provide an explicit picker and mention syntax.
@@ -192,24 +209,20 @@ On distribution, use the same boundary that the strongest platforms expose: huma
 12. *Configure the sandboxed Bash tool*. https://code.claude.com/docs/en/sandboxing
 13. *Application card: GitHub Copilot Agents*. https://docs.github.com/en/copilot/responsible-use/agents
 14. *Agent Server*. https://docs.langchain.com/langsmith/agent-server
-15. *Create and distribute a plugin marketplace*. http://code.claude.com/docs/en/plugin-marketplaces
+15. *Create and distribute a plugin marketplace*. https://code.claude.com/docs/en/plugin-marketplaces
 16. *Create custom subagents*. https://code.claude.com/docs/en/sub-agents
-17. *Discover and install prebuilt plugins through marketplaces*. http://code.claude.com/docs/en/discover-plugins
+17. *Discover and install prebuilt plugins through marketplaces*. https://code.claude.com/docs/en/discover-plugins
 18. *Preparing to use custom agents in your organization*. https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents
 19. *Creating and using custom agents for GitHub Copilot CLI*. https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
-20. [
-  Subagents | ChatGPT Learn
-](https://learn.chatgpt.com/docs/agent-configuration/subagents)
+20. *Subagents | ChatGPT Learn*. https://learn.chatgpt.com/docs/agent-configuration/subagents
 21. *feat: subagents · Issue #431 · charmbracelet/crush · GitHub*. https://github.com/charmbracelet/crush/issues/431
 22. *Aider - AI Pair Programming in Your Terminal*. https://aider.chat/
 23. *Run agents in parallel*. https://code.claude.com/docs/en/agents
-24. [
-  Advanced Configuration | ChatGPT Learn
-](https://learn.chatgpt.com/docs/config-file/config-advanced)
+24. *Advanced Configuration | ChatGPT Learn*. https://learn.chatgpt.com/docs/config-file/config-advanced
 25. *Recipe Reference Guide | goose | Your open source AI agent*. https://goose-docs.ai/docs/guides/recipes/recipe-reference/
 26. *Manage multiple agents with agent view*. https://code.claude.com/docs/en/agent-view
 27. *Subagents*. https://docs.cline.bot/features/subagents
-28. *Using Agent in CLI | Cursor Docs*. http://cursor.com/docs/cli/using
+28. *Using Agent in CLI | Cursor Docs*. https://cursor.com/docs/cli/using
 29. *Subagents | Cursor Docs*. https://cursor.com/docs/subagents
 30. *Reusable Recipes | goose | Your open source AI agent*. https://goose-docs.ai/docs/guides/recipes/session-recipes
 31. *Using Commands*. https://docs.cline.bot/core-workflows/using-commands
@@ -225,17 +238,16 @@ On distribution, use the same boundary that the strongest platforms expose: huma
 41. *Tools*. https://opencode.ai/docs/tools/
 42. *Chat modes*. https://aider.chat/docs/usage/modes.html
 43. *Plugins*. https://opencode.ai/docs/plugins/
-44. [Chat Participant API | Visual Studio Code Extension
-API](https://code.visualstudio.com/api/extension-guides/ai/chat)
-45. *http://cursor.com/docs*. http://cursor.com/docs
+44. *Chat Participant API | Visual Studio Code Extension API*. https://code.visualstudio.com/api/extension-guides/ai/chat
+45. *https://cursor.com/docs*. https://cursor.com/docs
 46. *Agent Skills | Cursor Docs*. https://cursor.com/docs/skills
 47. *Agent Skills*. https://opencode.ai/docs/skills/
 48. *Aider Documentation*. https://aider.chat/docs/
 49. *Workspace agents | OpenAI*. https://openai.com/academy/workspace-agents/
 50. *Plugins | Cursor Docs*. https://cursor.com/docs/plugins
 51. *Separating code reasoning and editing*. https://aider.chat/2024/09/26/architect.html
 52. *Set up Claude Code for your organization*. https://code.claude.com/docs/en/admin-setup
-53. *Enterprise | Cursor Docs*. http://cursor.com/docs/enterprise
+53. *Enterprise | Cursor Docs*. https://cursor.com/docs/enterprise
 54. *Configure server-managed settings*. https://code.claude.com/docs/en/server-managed-settings
 55. *About GitHub Copilot cloud agent*. https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent
 56. *Managing GPT access in Enterprise and Edu workspaces | OpenAI Help Center*. https://help.openai.com/en/articles/8555535-managing-gpt-access-in-enterprise-and-edu-workspaces

docs/internal/2026-08-12-dbt-optimization-taxonomy-research.md

@@ -65,7 +65,7 @@ The key implementation rule is to recommend a strategy together with its failure
 
 ## 3 Warehouse Physical Design and Storage Taxonomy
 
-Physical design should be inferred from recurring filters, join keys, partition coverage, and query profiles. It should not be generated from column names alone. Snowflake's micro-partition metadata supports runtime pruning [33], while Databricks liquid clustering is documented as a data-layout technique that replaces traditional partitioning and ZORDER [14]. Those mechanisms are similar in purpose but not interchangeable.
+Physical design should be inferred from recurring filters, join keys, partition coverage, and query profiles. It should not be generated from column names alone. Snowflake's micro-partition metadata supports runtime pruning [33], while Databricks liquid clustering is documented as a data-layout technique that replaces traditional partitioning and ZORDER [21]. Those mechanisms are similar in purpose but not interchangeable.
 
 | Engine and use-case | Detection signal and evidence needed | Proposed fix | Impact | Risk and preconditions | Agent confidence |
 |---|---|---|---|---|---|
@@ -78,7 +78,7 @@ Physical design should be inferred from recurring filters, join keys, partition
 | BigQuery partition pruning defeated | Partition filter is wrapped in a function, uses a mismatched type, or is applied after a broad subquery | Use direct partition-column predicates and push them to the scan | C, R | Correctness depends on timezone and inclusive boundary rules | Medium |
 | BigQuery required partition filter missing | Large partitioned table is queried without a bounded partition predicate | Set `require_partition_filter`; add model/source conventions and tests | C, Q | It can break legitimate unbounded jobs and BI queries, so propose with affected-consumer list | Medium |
 | BigQuery clustering missing or wrong | Repeated filters after partition pruning still scan many blocks; common equality/range columns are visible in query history | Add up to the engine-supported clustering columns in predicate/join order; validate bytes and slot time | C, R | Clustering is not a substitute for partitioning; high-cardinality or unstable keys may not help | Medium |
-| Databricks liquid clustering candidate | Delta table has recurring filters on dimensions, poor data skipping, and frequent schema/query evolution | Use liquid clustering on observed keys; run/monitor `OPTIMIZE` according to platform policy | C, R | Liquid clustering replaces partitioning/ZORDER and is not a drop-in change for all runtimes [14]; maintenance consumes compute | Low to medium |
+| Databricks liquid clustering candidate | Delta table has recurring filters on dimensions, poor data skipping, and frequent schema/query evolution | Use liquid clustering on observed keys; run/monitor `OPTIMIZE` according to platform policy | C, R | Liquid clustering replaces partitioning/ZORDER and is not a drop-in change for all runtimes [21]; maintenance consumes compute | Low to medium |
 | Databricks ZORDER candidate on legacy layout | Legacy Delta table, repeated selective predicates, data-skipping stats show poor locality | ZORDER on a small set of high-value columns, or migrate to liquid clustering | C, R | ZORDER can be inferior to liquid clustering on supported runtimes; avoid piling both without evidence | Medium |
 | Databricks partition explosion | Too many tiny partitions, small files, high task overhead, low rows per file | Remove or coarsen partitions; use liquid clustering or compaction | C, R | File layout and streaming latency can change | Medium |
 | Redshift sort key missing or misordered | Poor sort order, high unsorted region, scans on a recurring time/join predicate, EXPLAIN shows broad scan | Add/reorder sort key; choose compound/interleaved/automatic design appropriate to workload | C, R | Sort maintenance, vacuum, load order, and workload mix matter; use EXPLAIN and history | Medium |

packages/opencode/src/agent/agent.ts

@@ -383,7 +383,7 @@ export const layer = Layer.effect(
           "dbt-optimizer": {
             name: "dbt-optimizer",
             description:
-              "Scan a dbt project for fixable issues — performance, materialization, repeated logic, missing tests/docs — and propose targeted fixes with cost and impact reporting. File edits and shell commands prompt for approval; warehouse writes are denied.",
+              "Scan a dbt project for fixable issues — performance, materialization, repeated logic, missing tests/docs — and propose targeted fixes with cost and impact reporting. File edits and shell commands prompt for approval; the direct SQL write tool is denied non-overridably, and dbt builds against a dev target run only as user-approved shell commands.",
             prompt: PROMPT_OPTIMIZER,
             options: {},
             permission: Permission.merge(

packages/opencode/src/altimate/native/types.ts

@@ -726,6 +726,8 @@ export interface SqlDiffParams {
   context_lines?: number
   /** Optional parsing-dialect hint forwarded to the equivalence engine. */
   dialect?: string
+  /** Inline schema for the equivalence check; without it the handler skips equivalence entirely. */
+  schema_context?: Record<string, unknown>
 }
 
 export interface SqlDiffResult {

packages/opencode/src/altimate/prompts/dbt-optimizer.txt

@@ -8,7 +8,9 @@ fixes with cost and impact reporting so the user can prioritize. Your outputs ar
 - **Pull requests** — for the fixes the user applies
 
 Your permissions enforce your phases: file edits and shell commands prompt the user
-for approval by default, and warehouse writes are denied outright.
+for approval by default, and the direct SQL write tool (`sql_execute_write`) is
+denied outright. dbt builds DO mutate the warehouse — that is why they run only as
+shell commands the user approves, against a dev target (see Build safety).
 
 ## Trust boundary
 

packages/opencode/src/altimate/tools/altimate-core-rewrite.ts

@@ -123,11 +123,13 @@ async function verifyRewrites(
         schema_context: args.schema_context,
       })) as { error?: string; data?: Record<string, any> } | null
       const ed = (eq?.data ?? {}) as Record<string, any>
-      // The gate requires BOTH `equivalent === true` AND a decidable result. The
-      // engine can return { equivalent: true, decidable: false } when its heuristic
-      // comparator could not actually decide — that is an unproven rewrite, and
-      // reporting it as verified would be a false safety claim.
-      if (ed.equivalent === true && ed.decidable !== false) {
+      // The gate requires BOTH `equivalent === true` AND `decidable === true`.
+      // The engine can return { equivalent: true, decidable: false } when its
+      // heuristic comparator could not actually decide — that is an unproven
+      // rewrite, and reporting it as verified would be a false safety claim.
+      // `decidable` is a required field since altimate-core@0.5.1, so a missing
+      // value means a malformed response and also fails closed.
+      if (ed.equivalent === true && ed.decidable === true) {
         verified.push({ sql: c.sql, rule: c.rule, confidence: ed.confidence })
       } else {
         // Derive a specific reason. The gate stays strict (only `=== true` verifies);
@@ -138,6 +140,8 @@ async function verifyRewrites(
           reason = String(eq?.error ?? ed.error)
         } else if (ed.equivalent === true && ed.decidable === false) {
           reason = "equivalence undecidable — the engine could not prove the rewrite; validate with a data-diff"
+        } else if (ed.equivalent === true && ed.decidable !== true) {
+          reason = "missing or invalid 'decidable' field in equivalence response"
         } else if (!("equivalent" in ed)) {
           reason = "missing 'equivalent' field in equivalence response"
         } else if (typeof ed.equivalent !== "boolean") {

packages/opencode/src/altimate/tools/sql-diff.ts

@@ -4,22 +4,31 @@ import { Dispatcher } from "../native"
 
 export const SqlDiffTool = Tool.define("sql_diff", {
   description:
-    "Compare two SQL queries and show the differences. Returns a line diff plus a semantic-equivalence assessment. Useful for reviewing suggested changes before applying them.",
+    "Compare two SQL queries and show the differences. Returns a line diff, plus a semantic-equivalence assessment when schema_context is provided (equivalence needs schema to resolve table/column references). Useful for reviewing suggested changes before applying them.",
   parameters: z.object({
     original: z.string().describe("The original SQL"),
     modified: z.string().describe("The modified SQL"),
     context_lines: z.number().optional().default(3).describe("Number of context lines around changes"),
+    schema_context: z
+      .record(z.string(), z.any())
+      .optional()
+      .describe("Inline schema definition — required for the semantic-equivalence assessment"),
+    dialect: z.string().optional().describe("SQL dialect hint for equivalence (e.g. snowflake, bigquery)"),
   }),
   async execute(args, ctx) {
     try {
       // Native handler contract (sql/register.ts): { success, diff, equivalent,
       // equivalence_confidence, differences, error? }. The previous wrapper read
       // fields the handler never returns (has_changes/unified_diff/similarity),
-      // so every comparison fell into the "no changes" branch.
+      // so every comparison fell into the "no changes" branch. The handler only
+      // runs the equivalence check when schema_context is present.
+      const hasSchema = !!(args.schema_context && Object.keys(args.schema_context).length > 0)
       const result = (await Dispatcher.call("sql.diff", {
         original: args.original,
         modified: args.modified,
         context_lines: args.context_lines,
+        schema_context: args.schema_context,
+        dialect: args.dialect,
       })) as Record<string, any>
 
       if (result.success === false) {
@@ -34,8 +43,11 @@ export const SqlDiffTool = Tool.define("sql_diff", {
       const diffText = typeof result.diff === "string" ? result.diff : ""
       const changeCount = diffText.length ? diffText.split("\n").filter((l) => /^[+-]/.test(l)).length : 0
       const differences: any[] = Array.isArray(result.differences) ? result.differences : []
-      const equivalenceLine =
-        result.equivalent === true
+      // Without a schema the handler never runs the equivalence check — saying
+      // "not proven" there would misrepresent an unassessed comparison.
+      const equivalenceLine = !hasSchema
+        ? "Semantic equivalence: not assessed (pass schema_context to enable)"
+        : result.equivalent === true
           ? `Semantic equivalence: equivalent (confidence ${result.equivalence_confidence ?? "unknown"})`
           : "Semantic equivalence: not proven"
 

packages/opencode/src/altimate/tools/sql-explain.ts

@@ -83,11 +83,26 @@ function validateWarehouseName(warehouse: string | undefined): string | null {
  */
 function validateAnalyzeSafety(sql: string, analyze: boolean | undefined): string | null {
   if (!analyze) return null
+  const blocked =
+    "analyze:true runs EXPLAIN ANALYZE, which actually executes the statement — it is only allowed for a single plain SELECT query. " +
+    "Re-run with analyze:false for an estimated plan."
+  // Dollar-quoted strings (PostgreSQL $tag$...$tag$) can hide arbitrary text from
+  // the masking below; fail closed rather than tokenize them.
+  if (/\$[a-zA-Z_]*\$/.test(sql)) return blocked
+  // Mask string literals BEFORE removing comments. Comments-first is bypassable:
+  // in `SELECT '/*'; DELETE FROM t; SELECT '*/'` the comment regex would swallow
+  // the DELETE because the `/*` and `*/` live inside string literals. Masking
+  // errs toward false positives (a mangled comment can only ADD leftover text),
+  // which fails closed — the caller just falls back to analyze:false.
   const stripped = sql
+    .replace(/'(?:[^']|'')*'/g, "''")
+    .replace(/"(?:[^"]|"")*"/g, '""')
     .replace(/--[^\n]*/g, " ")
     .replace(/\/\*[\s\S]*?\*\//g, " ")
-    .replace(/'(?:[^']|'')*'/g, "''")
     .trim()
+  // Exactly one executable statement: any semicolon other than a trailing one
+  // means a multi-statement payload.
+  if (stripped.replace(/;\s*$/, "").includes(";")) return blocked
   const readOnlyStart = /^(select|with|show|describe|desc|values|table)\b/i.test(stripped)
   // Data-modifying CTEs (`WITH x AS (...) INSERT INTO ...`) and similar mean a
   // read-only prefix is not enough — reject write keywords anywhere.
@@ -97,12 +112,7 @@ function validateAnalyzeSafety(sql: string, analyze: boolean | undefined): strin
     /\b(insert|update|delete|merge|truncate|drop|alter|create|replace|grant|revoke|copy|call|vacuum|set|into)\b/i.test(
       stripped,
     )
-  if (!readOnlyStart || hasWriteKeyword) {
-    return (
-      "analyze:true runs EXPLAIN ANALYZE, which actually executes the statement — it is only allowed for plain SELECT queries. " +
-      "Re-run with analyze:false for an estimated plan."
-    )
-  }
+  if (!readOnlyStart || hasWriteKeyword) return blocked
   return null
 }
 

packages/opencode/test/agent/agent.test.ts

@@ -172,6 +172,32 @@ it.instance(
   },
 )
 
+it.instance(
+  "dbt-optimizer bash boundary: user bash overrides relax builds, never DDL or SQL writes",
+  () =>
+    Effect.gen(function* () {
+      const optimizer = yield* load((svc) => svc.get("dbt-optimizer"))
+      // DOCUMENTED BOUNDARY: `bash` is "ask" by default; a user who explicitly
+      // sets bash overrides accepts that dbt builds (which mutate a dev target)
+      // run without a prompt. That is the user's choice — but the invariants
+      // hold regardless: destructive DDL through bash stays denied, and the
+      // direct SQL write tool stays denied.
+      expect(
+        Permission.evaluate("bash", "altimate-dbt build --model fct_orders", optimizer!.permission).action,
+      ).toBe("allow")
+      expect(Permission.evaluate("bash", "DROP DATABASE prod", optimizer!.permission).action).toBe("deny")
+      expect(evalPerm(optimizer, "sql_execute_write")).toBe("deny")
+    }),
+  {
+    config: {
+      permission: { bash: "allow" },
+      agent: {
+        "dbt-optimizer": { permission: { bash: "allow" } },
+      },
+    },
+  },
+)
+
 it.instance("sensitive_write guard actually fires (not neutralized by *: allow)", () =>
   Effect.gen(function* () {
     // The #209 sensitive-write guard asks for the "sensitive_write" permission. It must NOT