From 2620cc0f5d3a2f3c6960fb98258f73105407d74a Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 07:50:29 -0800 Subject: [PATCH 01/58] fix: explain why `sql_execute` refuses a query as a write; stop misreading two reads - A denied write now names the parser error and position, shell syntax to remove, or the writing statement, and what to do next. `sql_check`, `sql_materialize` and MCP refusals carry it too. - Qualified `t.update`-style columns are reads; `scratch.` targets are scratch writes. Closes #1810 Co-Authored-By: Claude Opus 5.5 --- docs/docs/configure/permissions.md | 6 + .../src/altimate/mcp-server/workspace.ts | 3 +- .../src/altimate/tools/read-only-sql.ts | 11 +- .../src/altimate/tools/sql-classify.ts | 102 ++++++++++- .../src/altimate/tools/sql-execute.ts | 60 ++++-- .../src/altimate/tools/sql-materialize.ts | 4 +- .../tools/sql-readonly-guard-explain.test.ts | 83 +++++++++ .../altimate/tools/sql-readonly-guard.test.ts | 171 ++++++++++++++++++ 8 files changed, 422 insertions(+), 18 deletions(-) create mode 100644 packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts create mode 100644 packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index 65bbc9393e..954651c086 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -251,6 +251,12 @@ When prompted, you have three choices: "Allow always" approvals persist for your current session only. They reset when you restart Altimate Code. +### How SQL is classified for `sql_execute_write` + +`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals and column names that contain words like `update` or `delete` do not count. SQL the parser cannot read is treated as a write, so it is never run without write permission. + +When an agent's `sql_execute_write` is `"deny"`, the tool error tells the agent why the query counted as a write and what to change: the statement that writes, the parser error and its position, or trailing shell syntax such as `2>/dev/null` to remove. + ## Tips - **Start with `"ask"` and relax as you build confidence.** You can always approve patterns with "Allow always" during a session. diff --git a/packages/opencode/src/altimate/mcp-server/workspace.ts b/packages/opencode/src/altimate/mcp-server/workspace.ts index fdd6bcf65b..8ad9111e3e 100644 --- a/packages/opencode/src/altimate/mcp-server/workspace.ts +++ b/packages/opencode/src/altimate/mcp-server/workspace.ts @@ -7,6 +7,7 @@ import * as WorkspaceClient from "../workspace/client" import { which, versionOf } from "../workspace/engine-probes" import { clearsFloor, engineEntry, ENGINE_BINARY } from "../workspace/engine-types" import { classifyAndCheck } from "../tools/sql-classify" +import { writeReason } from "../tools/read-only-sql" // Deliberately closed: adding a new engine capability requires classifying it. const METADATA_READS = new Set([ @@ -38,7 +39,7 @@ export function checkEngineRead(name: string, args: Record) { for (const query of queries) { const result = classifyAndCheck(query, dialect) if (result.parseError || result.blocked || result.queryType !== "read") { - throw new Error("Workspace SQL must be read-only. Use Altimate Code directly for writes.") + throw new Error("Workspace SQL must be read-only. Use Altimate Code directly for writes." + writeReason(query, dialect)) } } } diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 7ce5fa345b..de4ff627cc 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -1,4 +1,4 @@ -import { classifyAndCheck, isSingleQuery } from "./sql-classify" +import { classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" import { maskSql, tokenizeSql } from "./sql-tokenize" import { sqlFunctionCalls } from "./sql-functions" import { hasSideEffectFunction } from "./sql-function-policy" @@ -57,9 +57,16 @@ export function readSql(sql: string, dialect?: string): string { /\bREPLACE\b(?!\s*\()/i.test(body) ) { throw new Error( - "This operation only accepts a single read-only SELECT (or WITH ... SELECT); it never writes or fixes data.", + "This operation only accepts a single read-only SELECT (or WITH ... SELECT); it never writes or fixes data." + + writeReason(sql, dialect), ) } const semicolon = checked.masked.indexOf(";") return semicolon < 0 ? sql : sql.slice(0, semicolon) + sql.slice(semicolon + 1) } + +/** Why the classifier reads sql as a write, as a sentence to append to a refusal; empty for a read. */ +export function writeReason(sql: string, dialect?: string): string { + const { queryType, blocked } = classifyAndCheck(sql, dialect) + return queryType === "write" && !blocked ? ` It counts as a write because ${explainWrite(sql, dialect).reason}.` : "" +} diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index a79357eb34..c52e608d96 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -88,7 +88,9 @@ function hasQueryWriteClause(sql: string, dialect?: string): boolean { let masked = maskSql(tokenizeSql(sql, dialect).tokens) // UNPIVOT's INTO NAME labels output columns; it does not create a table. if (dialect?.toLowerCase() === "duckdb") masked = maskUnpivotLabels(masked) - return /\b(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i.test(masked) + // A name qualified by a table or alias (t.update, s.delete) is a column, not a clause. The lookbehind + // runs only where a keyword matched, so long masked literals are not rescanned at every position. + return /\b(INTO|INSERT|UPDATE|DELETE|MERGE)\b(?/dev/null`, `2>&1`) can sit anywhere, even before LIMIT; a pipe into a shell command (`| head -20`) +// or a redirect into a file (`> out.csv`) only ends the text. A file target needs a / or an extension, +// so a comparison such as `x > 2` never matches. +const SHELL_REDIRECT = /\s(?:[12]|&)?>>?\s*(?:&[12]|\/dev\/null)(?![\w/])/g +const SHELL_TAIL = + /(?:\s*\|\s*(?:head|tail|grep|egrep|less|more|cat|wc|sort|uniq|cut|column|jq|tee|awk|sed)\b[^|\n]*|\s*(?:[12]|&)?>>?\s*[\w~.-]*[/.][\w./~-]+)+\s*;?\s*$/i + +/** The shell syntax in a query that is a read without it, or undefined. Only code counts (literals and + * comments are masked). The query is never rewritten: the caller names the residue so the sender removes + * it, since running the query without it would run SQL other than what was sent. */ +export function shellResidue(sql: string, dialect?: string): string | undefined { + const lexical = tokenizeSql(sql, dialect) + if (!lexical.complete) return undefined + // Masking keeps every offset, so a match in the masked text cuts the same span of the original. + const masked = maskSql(lexical.tokens) + const cuts = [...masked.matchAll(SHELL_REDIRECT)].map((match) => [match.index!, match.index! + match[0].length]) + // Only the tail can hold a pipe or file redirect; bounding it keeps the scan cheap on large queries. + const offset = Math.max(0, masked.length - 400) + const tail = SHELL_TAIL.exec(masked.slice(offset)) + if (tail) cuts.push([offset + tail.index, masked.length]) + if (!cuts.length) return undefined + cuts.sort((a, b) => a[0] - b[0]) + const fragments: string[] = [] + let query = "" + let position = 0 + for (const [start, end] of cuts) { + if (end <= position) continue + const from = Math.max(start, position) + query += sql.slice(position, from) + " " + fragments.push(sql.slice(from, end).trim()) + position = end + } + query += sql.slice(position) + if (!query.trim()) return undefined + const result = classifyAndCheck(query, dialect) + return result.queryType === "read" && !result.blocked ? fragments.filter(Boolean).join("`, `") : undefined +} + +function snippet(statement: string): string { + const flat = statement.replace(/\s+/g, " ").trim() + return flat.length > 80 ? `${flat.slice(0, 77)}...` : flat +} + +/** + * Why classifyAndCheck treats this SQL as a write, in words an agent can act on: shell residue to + * remove, the parser error and its position, or the first statement that is not a read. `unreadable` + * is true when the SQL could not be read at all (fix the text), false when a statement writes. + */ +export function explainWrite(sql: string, dialect?: string): { reason: string; unreadable: boolean } { + const unreadable = (reason: string) => ({ reason, unreadable: true }) + const writes = (reason: string) => ({ reason, unreadable: false }) + const residue = shellResidue(sql, dialect) + if (residue) return unreadable(`it contains shell syntax (\`${residue}\`), which is not SQL. Remove it and send only the SQL`) + const lexical = tokenizeSql(sql, dialect) + if (!lexical.complete) { + return unreadable( + "it has unterminated quoted text or comments, so it cannot be proven read-only. Check that every quote and comment " + + "is closed; inside a string literal, write a single quote as ''" + ) + } + const statements = statementsOf(sql, dialect) + for (const [index, statement] of statements.entries()) { + const result = classifySql(statement, dialect, 0) + if (result.queryType === "read" && !result.blocked) continue + const where = statements.length > 1 ? `statement ${index + 1} of ${statements.length} (${snippet(statement)})` : "it" + if (result.parseError) { + return unreadable( + `the SQL parser could not read ${where} (${result.parseError}), so it cannot be proven read-only. ` + + 'Fix the syntax at that position: quote identifiers that contain spaces or are keywords ("order date"), ' + + "check the clause order, and replace any placeholder text such as ..." + ) + } + let type: string | undefined + try { + type = getStatementTypes?.(parserSql(statement, dialect), dialect)?.statements?.[0]?.statement_type + } catch { + type = undefined + } + if (type && !/^(SELECT|QUERY)$/i.test(type)) return writes(`${where} is not a read (${type.toUpperCase()})`) + if (hasQueryWriteClause(statement, dialect)) { + return writes(`${where} contains a write clause (SELECT ... INTO, or INSERT/UPDATE/DELETE/MERGE inside a CTE)`) + } + if (functionSafety(statement, dialect, 0).write) return writes(`${where} calls a function that can modify data or run other SQL`) + return writes(`${where} could not be proven read-only`) + } + return writes("the statements together could not be proven read-only") +} + // MongoDB commands are JSON, not SQL: the SQL classifier reads every one as a write, which denied // 52 of 52 Mongo reads for a read-only agent in one evaluation run. Classify them by command. const MONGO_READ_COMMANDS = new Set([ @@ -593,8 +684,13 @@ function hasLocalScratchTarget(statement: string): boolean { "i", ).exec(statement) if (!target) return false - const names = target[1].match(new RegExp(identifier, "g"))! - if (names.length > 2 || (names.length === 2 && names[0].replace(/^"|"$/g, "").toLowerCase() !== "main")) return false + const names = target[1].match(new RegExp(identifier, "g"))!.map((name) => name.replace(/^"|"$/g, "").toLowerCase()) + // The scratch database's own catalog is named scratch: scratch.t and scratch.main.t are local too. + const local = + names.length === 1 || + (names.length === 2 && (names[0] === "main" || names[0] === "scratch")) || + (names.length === 3 && names[0] === "scratch" && names[1] === "main") + if (!local) return false // A DROP statement can name more than one table, unlike the other forms. return !/^\s*DROP\b/i.test(statement) || !statement.slice(target[0].length).includes(",") } diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 78a5a11d41..7fe3723863 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -13,6 +13,7 @@ import { classifyAndCheck, classifyMongoCommand, computeSqlFingerprint, + explainWrite, isScratchSafeWrite, mentionsHardDenyAnywhere, } from "./sql-classify" @@ -25,6 +26,8 @@ function isMongoWarehouse(name: string | undefined): boolean { return MONGO_WAREHOUSE_TYPES.has(type) } import { Telemetry } from "../telemetry" +import { PermissionV1 } from "@opencode-ai/core/v1/permission" +import { PermissionNext } from "../../permission/next" // altimate_change end // altimate_change start — progressive disclosure suggestions import { PostConnectSuggestions } from "./post-connect-suggestions" @@ -274,17 +277,24 @@ export const SqlExecuteTool = Tool.define( // the hard-deny list above still applies. if (queryType === "write" && !(isScratch(args.warehouse) && isScratchSafeWrite(sql))) { // Unprovable SQL still goes through write approval; the prompt carries the parse error. - await ctx.ask({ - permission: "sql_execute_write", - patterns: [sql.slice(0, 200)], - always: ["*"], - metadata: { - queryType, - warehouse: args.warehouse || target?.warehouse, - hardDenyChecked: true, - ...(parseError && { parseError }), - }, - }) + // altimate_change start — a denied write says why and how to proceed, instead of a rule dump + try { + await ctx.ask({ + permission: "sql_execute_write", + patterns: [sql.slice(0, 200)], + always: ["*"], + metadata: { + queryType, + warehouse: args.warehouse || target?.warehouse, + hardDenyChecked: true, + ...(parseError && { parseError }), + }, + }) + } catch (error) { + if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error + throw new Error(deniedWriteMessage({ sql, dialects, jinja, mongo: mongo !== null, scratch: isScratch(args.warehouse) })) + } + // altimate_change end } // altimate_change end @@ -721,6 +731,34 @@ function classifyEvery(sql: string, dialects: (string | undefined)[]) { } } +// altimate_change start — a denied write says why and how to proceed +/** The error a read-only agent gets when its query counts as a write: the reason, then what to do next, + * so the agent fixes the query instead of resending it. */ +function deniedWriteMessage(input: { + sql: string + dialects: (string | undefined)[] + jinja: boolean + mongo: boolean + scratch: boolean +}): string { + const head = "sql_execute did not run this query. This agent may only read (write permission is denied), and the query counts as a write because" + if (input.jinja) { + return `${head} it contains Jinja ({{ }}, {% %} or {# #}), which dbt renders and runs before the SQL. Send plain SQL without Jinja.` + } + if (input.mongo) { + return `${head} it is a MongoDB write (a write command, or an aggregate with a $out or $merge stage). Use a read command (find, aggregate, countDocuments, distinct) instead.` + } + const dialect = input.dialects.find((d) => classifyAndCheck(input.sql, d).queryType === "write") + const { reason, unreadable } = explainWrite(input.sql, dialect) + const next = unreadable + ? "Fix the query and call sql_execute again; the same text will be refused again." + : input.scratch + ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission; send reads in their own call." + : "Rewrite it as a single read (SELECT, or WITH ... SELECT). To keep an intermediate result, store it in scratch with sql_materialize if that tool is available." + return `${head} ${reason}. ${next}` +} +// altimate_change end + /** Dialects whose string literals treat a backslash as an escape character. */ const BACKSLASH_ESCAPE_TYPES = new Set(["mysql", "bigquery", "snowflake", "databricks", "clickhouse", "redshift"]) /** Dialects with no `''` escape inside a string literal; a quote is escaped with a backslash. */ diff --git a/packages/opencode/src/altimate/tools/sql-materialize.ts b/packages/opencode/src/altimate/tools/sql-materialize.ts index 9a5c79b01a..c59158aeaf 100644 --- a/packages/opencode/src/altimate/tools/sql-materialize.ts +++ b/packages/opencode/src/altimate/tools/sql-materialize.ts @@ -8,6 +8,7 @@ import * as Registry from "../native/connections/registry" import { SCRATCH_NAME, withScratchConnection, isScratch } from "../native/connections/scratch" import { classifyAndCheck, classifyMongoCommand } from "./sql-classify" import { readSql } from "./sql-check" +import { writeReason } from "./read-only-sql" import { lintSqlResult } from "./sql-result-lint" import * as Precedence from "../workspace/precedence" import { executeQuery, type QueryContext } from "../native/query-execution" @@ -218,7 +219,8 @@ function assertReadOnlySource(warehouse: string, sql: string): { mongo: boolean; } catch { throw new MaterializeError( "sql_materialize only reads from the source warehouse: use a single read-only SELECT (or WITH ... SELECT), " + - "without modifying CTEs, SELECT INTO or side-effect functions. Its only write target is the scratch database.", + "without modifying CTEs, SELECT INTO or side-effect functions. Its only write target is the scratch database." + + writeReason(sql, Registry.canonicalType(type) ?? undefined), ) } } diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts new file mode 100644 index 0000000000..f2b2db5b69 --- /dev/null +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -0,0 +1,83 @@ +import { describe, expect, test } from "bun:test" +import { classifyAndCheck, explainWrite, shellResidue } from "../../../src/altimate/tools/sql-classify" +import { readSql, writeReason } from "../../../src/altimate/tools/read-only-sql" + +describe("shellResidue", () => { + const cases: Record = { + "SELECT 1 2>/dev/null": "2>/dev/null", + "SELECT * FROM t LIMIT 5 2>&1": "2>&1", + "SELECT * FROM t >/dev/null": ">/dev/null", + "SELECT * FROM t > out.csv": "> out.csv", + "SELECT * FROM t | head -20": "| head -20", + "SELECT * FROM t LIMIT 5 2>&1 | head -n 20": "2>&1`, `| head -n 20", + "SELECT * FROM t; 2>/dev/null": "2>/dev/null", + "SELECT a FROM t ORDER BY a 2>/dev/null LIMIT 5": "2>/dev/null", + "SELECT a FROM t 2>/dev/null | head -5": "2>/dev/null`, `| head -5", + } + for (const [sql, residue] of Object.entries(cases)) { + test(`finds ${residue}`, () => { + expect(shellResidue(sql, "postgres")).toBe(residue) + // The residue makes the text unreadable, so it is never classified as a read. + expect(classifyAndCheck(sql, "postgres").queryType).toBe("write") + }) + } + + test("a comparison is not a redirect", () => { + expect(shellResidue("SELECT a FROM t WHERE x > 2", "postgres")).toBeUndefined() + expect(shellResidue("SELECT a FROM t WHERE x >= 2.5", "postgres")).toBeUndefined() + }) + + test("text inside a comment or literal is not residue", () => { + expect(shellResidue("SELECT 1 -- 2>/dev/null", "postgres")).toBeUndefined() + expect(shellResidue("SELECT '2>/dev/null'", "postgres")).toBeUndefined() + }) + + test("a write followed by residue is not offered as a read", () => { + expect(shellResidue("DELETE FROM t 2>/dev/null", "postgres")).toBeUndefined() + expect(explainWrite("DELETE FROM t 2>/dev/null", "postgres").reason).not.toContain("shell syntax") + }) +}) + +describe("other read-only refusals carry the reason", () => { + test("sql_check and query_from (readSql)", () => { + expect(() => readSql("SELECT 1 2>/dev/null", "postgres")).toThrow("`2>/dev/null`") + expect(() => readSql("SELECT 1; DELETE FROM t", "postgres")).toThrow("statement 2 of 2") + }) + + test("a refusal that is not about writing stays as it was", () => { + expect(writeReason("SELECT 1", "postgres")).toBe("") + }) +}) + +describe("explainWrite", () => { + test("names shell residue", () => { + const result = explainWrite("SELECT 1 2>/dev/null", "postgres") + expect(result).toEqual({ unreadable: true, reason: expect.stringContaining("`2>/dev/null`") }) + }) + + test("carries the parser's position", () => { + const result = explainWrite("SELECT Order Date FROM orders", "postgres") + expect(result.unreadable).toBe(true) + expect(result.reason).toMatch(/line 1, column \d+/) + }) + + test("explains an unterminated quote", () => { + const result = explainWrite("SELECT 'it\\'s' FROM t", "postgres") + expect(result.unreadable).toBe(true) + expect(result.reason).toContain("unterminated") + }) + + test("names the first write statement", () => { + expect(explainWrite("SELECT 1; SELECT 2; DROP TABLE t", "postgres")).toEqual({ + unreadable: false, + reason: "statement 3 of 3 (DROP TABLE t) is not a read (DROP TABLE)", + }) + expect(explainWrite("COPY INTO orders FROM @stage", "snowflake").reason).toBe("it is not a read (COPY)") + }) + + test("names a write clause inside a query", () => { + for (const sql of ["WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x", "SELECT * INTO c FROM t"]) { + expect(explainWrite(sql, "postgres")).toEqual({ unreadable: false, reason: expect.stringContaining("write clause") }) + } + }) +}) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts new file mode 100644 index 0000000000..4478fba760 --- /dev/null +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -0,0 +1,171 @@ +import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test" +import { PermissionV1 } from "@opencode-ai/core/v1/permission" +import { SessionID, MessageID } from "../../../src/session/schema" +import { SqlExecuteTool } from "../../../src/altimate/tools/sql-execute" +import { classifyAndCheck, isScratchSafeWrite } from "../../../src/altimate/tools/sql-classify" +import * as Registry from "../../../src/altimate/native/connections/registry" +import { closeScratch } from "../../../src/altimate/native/connections/scratch" +import { initTool } from "../tool-fixture" + +// A read-only agent denies `sql_execute_write`. Reads must never reach that rule, and when a query does, +// the agent must learn why and what to change instead of a raw permission-rule dump it tends to retry. + +const DIALECTS = ["postgres", "snowflake", "bigquery", "duckdb", "sqlite", "mysql", "databricks", "redshift"] + +const isRead = (sql: string, dialect: string) => { + const result = classifyAndCheck(sql, dialect) + return result.queryType === "read" && !result.blocked +} + +const deniedCtx = (asked: unknown[]) => ({ + sessionID: SessionID.make("ses_readonly_guard"), + messageID: MessageID.make("msg_readonly_guard"), + callID: "", + agent: "analyst", + abort: AbortSignal.any([]), + messages: [] as any[], + metadata: () => {}, + ask: async (request: any) => { + asked.push(request) + if (request.permission === "sql_execute_write") throw new PermissionV1.DeniedError({ ruleset: [] }) + }, +}) + +let previousTelemetry: string | undefined + +beforeAll(() => { + previousTelemetry = process.env.ALTIMATE_TELEMETRY_DISABLED + process.env.ALTIMATE_TELEMETRY_DISABLED = "true" + Registry.setConfigs({ guard_db: { type: "sqlite", path: ":memory:" } as never }) +}) + +afterEach(async () => { + await closeScratch() +}) + +afterAll(() => { + Registry.reset() + if (previousTelemetry === undefined) delete process.env.ALTIMATE_TELEMETRY_DISABLED + else process.env.ALTIMATE_TELEMETRY_DISABLED = previousTelemetry +}) + +describe("reads are classified as reads in every dialect", () => { + const reads: Record = { + "comment with write words": "SELECT id FROM orders -- update later\n/* delete stale rows */", + "leading comment with write words": "-- insert into notes later\nSELECT 1", + "string literal with write words": "SELECT * FROM orders WHERE status = 'DELETED' OR note = 'insert into x'", + "identifiers containing write words": "SELECT update_ts, created_by, deleted_at FROM orders", + "qualified columns named like write keywords": "SELECT o.update, o.delete, o.insert, o.merge FROM orders o", + "CTE": "WITH a AS (SELECT 1 AS x), b AS (SELECT x FROM a) SELECT * FROM b", + "EXPLAIN of a read": "EXPLAIN SELECT * FROM orders", + "leading whitespace": "\n\n SELECT 1", + "parenthesized query": "(SELECT 1) UNION ALL (SELECT 2)", + "two reads": "SELECT 1; SELECT 2", + } + for (const [name, sql] of Object.entries(reads)) { + test(name, () => { + expect(DIALECTS.filter((dialect) => !isRead(sql, dialect))).toEqual([]) + }) + } + + test("DESCRIBE, SHOW and PRAGMA metadata reads", () => { + for (const sql of ["DESCRIBE orders", "SHOW TABLES", "SHOW COLUMNS FROM orders"]) expect(isRead(sql, "duckdb")).toBe(true) + expect(isRead("PRAGMA table_info('orders')", "sqlite")).toBe(true) + }) +}) + +describe("writes stay writes", () => { + const writes: Record = { + INSERT: "INSERT INTO orders VALUES (1)", + UPDATE: "UPDATE orders SET status = 'x'", + DELETE: "DELETE FROM orders", + MERGE: "MERGE INTO t USING s ON t.id = s.id WHEN MATCHED THEN UPDATE SET v = s.v", + "CREATE TABLE": "CREATE TABLE t (a INT)", + "DROP TABLE": "DROP TABLE orders", + "ALTER TABLE": "ALTER TABLE orders ADD COLUMN c INT", + "COPY INTO": "COPY INTO orders FROM @stage", + "write after a read": "SELECT 1; DELETE FROM orders", + "write hidden after a semicolon on one line": "SELECT * FROM orders;DELETE FROM orders", + "write CTE": "WITH x AS (DELETE FROM orders RETURNING *) SELECT * FROM x", + "SELECT INTO": "SELECT * INTO copy_of_orders FROM orders", + "qualified column beside a real write": "SELECT o.update FROM orders o; UPDATE orders SET a = 1", + "write followed by shell residue": "DELETE FROM orders 2>/dev/null", + "unparseable text": "SELECT a b c FROM WHERE", + } + for (const [name, sql] of Object.entries(writes)) { + test(name, () => { + expect(DIALECTS.filter((dialect) => isRead(sql, dialect))).toEqual([]) + }) + } +}) + +describe("scratch writes", () => { + test("the scratch catalog prefix is local", () => { + expect(isScratchSafeWrite("CREATE OR REPLACE TABLE scratch.pubs AS SELECT 1 AS x")).toBe(true) + expect(isScratchSafeWrite("CREATE TABLE scratch.main.pubs AS SELECT 1 AS x")).toBe(true) + }) + + test("other catalogs and schemas are not", () => { + expect(isScratchSafeWrite("CREATE TABLE other.pubs AS SELECT 1 AS x")).toBe(false) + expect(isScratchSafeWrite("CREATE TABLE other.main.pubs AS SELECT 1 AS x")).toBe(false) + expect(isScratchSafeWrite("CREATE TABLE scratch.other.pubs AS SELECT 1 AS x")).toBe(false) + }) +}) + +describe("sql_execute on a read-only agent", () => { + const run = async (query: string, warehouse = "guard_db") => { + const tool = await initTool(SqlExecuteTool) + const asked: any[] = [] + const outcome = await tool.execute({ query, warehouse, limit: 10 }, deniedCtx(asked) as any).then( + (result: any) => ({ result, error: undefined as string | undefined }), + (error: Error) => ({ result: undefined, error: error.message }), + ) + return { ...outcome, asked: asked.filter((request) => request.permission === "sql_execute_write") } + } + + test("a qualified column named like a keyword runs without asking", async () => { + const { result, error, asked } = await run("SELECT t.update FROM (SELECT 1 AS \"update\") t", "scratch") + expect(error).toBeUndefined() + expect(asked).toHaveLength(0) + expect(result.output).toMatch(/\b1\b/) + }) + + test("shell residue is named and must be removed; nothing runs", async () => { + const { error } = await run("SELECT 1 AS x 2>/dev/null") + expect(error).toContain("`2>/dev/null`") + expect(error).toContain("Remove it") + expect(error).not.toContain("relevant rules") + }) + + test("unparseable SQL reports the parser's position", async () => { + const { error } = await run("SELECT Order Date FROM orders WHERE Order Date > '2020-01-01'") + expect(error).toMatch(/could not read it \(.*line 1, column \d+/) + expect(error).toContain("Fix the query") + }) + + test("a write names the statement and suggests a read", async () => { + const { error } = await run("SELECT 1; DELETE FROM orders") + expect(error).toContain("statement 2 of 2 (DELETE FROM orders) is not a read (DELETE)") + expect(error).toContain("single read") + }) + + test("a scratch batch mixing a write and a read says to split it", async () => { + const { error } = await run("CREATE TABLE items AS SELECT 1 AS v; SELECT * FROM items", "scratch") + expect(error).toContain("statement 1 of 2") + expect(error).toContain("send reads in their own call") + }) + + test("a scratch write through the scratch catalog runs without asking", async () => { + const { error, asked } = await run("CREATE OR REPLACE TABLE scratch.pubs AS SELECT 1 AS x", "scratch") + expect(error).toBeUndefined() + expect(asked).toHaveLength(0) + }) + + test("errors other than a rule denial pass through unchanged", async () => { + const tool = await initTool(SqlExecuteTool) + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new Error("rejected by test")) } + await expect(tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any)).rejects.toThrow( + "rejected by test", + ) + }) +}) From 7f0ed7f4d25d9c503262a9d2aaa81b58a432068b Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 07:55:19 -0800 Subject: [PATCH 02/58] fix: keep `SELECT 1. INTO t` a write when exempting qualified columns The qualifier must be a whole unquoted identifier directly before the dot; a number ending in a dot followed by INTO stays a SELECT INTO. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/sql-classify.ts | 8 +++++--- .../test/altimate/tools/sql-readonly-guard.test.ts | 4 ++++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index c52e608d96..e1d83929d6 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -88,9 +88,11 @@ function hasQueryWriteClause(sql: string, dialect?: string): boolean { let masked = maskSql(tokenizeSql(sql, dialect).tokens) // UNPIVOT's INTO NAME labels output columns; it does not create a table. if (dialect?.toLowerCase() === "duckdb") masked = maskUnpivotLabels(masked) - // A name qualified by a table or alias (t.update, s.delete) is a column, not a clause. The lookbehind - // runs only where a keyword matched, so long masked literals are not rescanned at every position. - return /\b(INTO|INSERT|UPDATE|DELETE|MERGE)\b(? { "write CTE": "WITH x AS (DELETE FROM orders RETURNING *) SELECT * FROM x", "SELECT INTO": "SELECT * INTO copy_of_orders FROM orders", "qualified column beside a real write": "SELECT o.update FROM orders o; UPDATE orders SET a = 1", + "SELECT INTO after a number ending in a dot": "SELECT 1. INTO copy_of_orders FROM orders", + "SELECT INTO after a column and a number ending in a dot": "SELECT o.a, 2. INTO copy_of_orders FROM orders o", + "SELECT INTO after a hex number ending in a dot": "SELECT 0x1.INTO copy_of_orders FROM orders", + "SELECT INTO after a spaced qualifier": "SELECT o. INTO copy_of_orders FROM orders o", "write followed by shell residue": "DELETE FROM orders 2>/dev/null", "unparseable text": "SELECT a b c FROM WHERE", } From b97438cb7e294ab80ef84a22a19b27b02ff5d194 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 08:01:07 -0800 Subject: [PATCH 03/58] fix: tighten shell-residue detection, align `readSql`, keep SQL out of refusal text - File redirects must look like paths or output files, and residue is offered only for text that does not parse. - `readSql` exempts qualified keyword-named columns like the classifier. - Refusals name the dialect and no longer quote statements. - Tests for the MCP, materialize and subagent denial paths. Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/read-only-sql.ts | 3 ++- .../src/altimate/tools/sql-classify.ts | 20 ++++++++--------- .../src/altimate/tools/sql-execute.ts | 22 ++++++++++++++----- .../altimate/mcp-server/workspace.test.ts | 3 +++ .../test/altimate/sql-materialize.test.ts | 4 ++++ .../tools/sql-readonly-guard-explain.test.ts | 17 +++++++++++++- .../altimate/tools/sql-readonly-guard.test.ts | 16 +++++++++++--- 7 files changed, 64 insertions(+), 21 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index de4ff627cc..9096611aad 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -51,7 +51,8 @@ export function readSql(sql: string, dialect?: string): string { if ( checked === undefined || !/^(SELECT|WITH)\b/i.test(body) || - /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|COPY|ATTACH|DETACH|PRAGMA|VACUUM|CALL|DO|INTO|INSTALL|LOAD|EXPORT|IMPORT|GRANT|REVOKE)\b/i.test( + // A column qualified by a whole identifier (t.update) is not a statement word, as in the classifier. + /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|COPY|ATTACH|DETACH|PRAGMA|VACUUM|CALL|DO|INTO|INSTALL|LOAD|EXPORT|IMPORT|GRANT|REVOKE)\b(?/dev/null`, `2>&1`) can sit anywhere, even before LIMIT; a pipe into a shell command (`| head -20`) -// or a redirect into a file (`> out.csv`) only ends the text. A file target needs a / or an extension, -// so a comparison such as `x > 2` never matches. +// or a redirect into a file (`> out.csv`) only ends the text. A file target must start like a path +// (/, ./, ../, ~/) or end in a known output extension, so comparisons such as `x > 2`, `x > 1.5` and +// `x > t.total` never match. const SHELL_REDIRECT = /\s(?:[12]|&)?>>?\s*(?:&[12]|\/dev\/null)(?![\w/])/g const SHELL_TAIL = - /(?:\s*\|\s*(?:head|tail|grep|egrep|less|more|cat|wc|sort|uniq|cut|column|jq|tee|awk|sed)\b[^|\n]*|\s*(?:[12]|&)?>>?\s*[\w~.-]*[/.][\w./~-]+)+\s*;?\s*$/i + /(?:\s*\|\s*(?:head|tail|grep|egrep|less|more|cat|wc|sort|uniq|cut|column|jq|tee|awk|sed)\b[^|\n]*|\s*(?:[12]|&)?>>?\s*(?:(?:\/|\.\.?\/|~\/)[\w./~-]*|[\w~-][\w~.-]*\.(?:csv|tsv|txt|json|jsonl|log|out|err|sql|parquet|tmp)\b))+\s*;?\s*$/i /** The shell syntax in a query that is a read without it, or undefined. Only code counts (literals and * comments are masked). The query is never rewritten: the caller names the residue so the sender removes * it, since running the query without it would run SQL other than what was sent. */ export function shellResidue(sql: string, dialect?: string): string | undefined { const lexical = tokenizeSql(sql, dialect) - if (!lexical.complete) return undefined + // Residue is only an explanation for text that does not parse; valid SQL is never offered for removal. + if (!lexical.complete || !classifyAndCheck(sql, dialect).parseError) return undefined // Masking keeps every offset, so a match in the masked text cuts the same span of the original. const masked = maskSql(lexical.tokens) const cuts = [...masked.matchAll(SHELL_REDIRECT)].map((match) => [match.index!, match.index! + match[0].length]) @@ -564,11 +566,6 @@ export function shellResidue(sql: string, dialect?: string): string | undefined return result.queryType === "read" && !result.blocked ? fragments.filter(Boolean).join("`, `") : undefined } -function snippet(statement: string): string { - const flat = statement.replace(/\s+/g, " ").trim() - return flat.length > 80 ? `${flat.slice(0, 77)}...` : flat -} - /** * Why classifyAndCheck treats this SQL as a write, in words an agent can act on: shell residue to * remove, the parser error and its position, or the first statement that is not a read. `unreadable` @@ -590,10 +587,11 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u for (const [index, statement] of statements.entries()) { const result = classifySql(statement, dialect, 0) if (result.queryType === "read" && !result.blocked) continue - const where = statements.length > 1 ? `statement ${index + 1} of ${statements.length} (${snippet(statement)})` : "it" + // No SQL text is quoted back: the error is also recorded by telemetry. + const where = statements.length > 1 ? `statement ${index + 1} of ${statements.length}` : "it" if (result.parseError) { return unreadable( - `the SQL parser could not read ${where} (${result.parseError}), so it cannot be proven read-only. ` + + `the ${dialect ?? "generic"} SQL parser could not read ${where} (${result.parseError}), so it cannot be proven read-only. ` + 'Fix the syntax at that position: quote identifiers that contain spaces or are keywords ("order date"), ' + "check the clause order, and replace any placeholder text such as ..." ) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 7fe3723863..faf472ddee 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -277,7 +277,7 @@ export const SqlExecuteTool = Tool.define( // the hard-deny list above still applies. if (queryType === "write" && !(isScratch(args.warehouse) && isScratchSafeWrite(sql))) { // Unprovable SQL still goes through write approval; the prompt carries the parse error. - // altimate_change start — a denied write says why and how to proceed, instead of a rule dump + // A denied write says why and how to proceed, instead of a rule dump. try { await ctx.ask({ permission: "sql_execute_write", @@ -292,9 +292,17 @@ export const SqlExecuteTool = Tool.define( }) } catch (error) { if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error - throw new Error(deniedWriteMessage({ sql, dialects, jinja, mongo: mongo !== null, scratch: isScratch(args.warehouse) })) + throw new Error( + deniedWriteMessage({ + sql, + dialects, + jinja, + mongo: mongo !== null, + scratch: isScratch(args.warehouse), + warehouseGiven: !!args.warehouse, + }), + ) } - // altimate_change end } // altimate_change end @@ -740,6 +748,7 @@ function deniedWriteMessage(input: { jinja: boolean mongo: boolean scratch: boolean + warehouseGiven: boolean }): string { const head = "sql_execute did not run this query. This agent may only read (write permission is denied), and the query counts as a write because" if (input.jinja) { @@ -751,9 +760,12 @@ function deniedWriteMessage(input: { const dialect = input.dialects.find((d) => classifyAndCheck(input.sql, d).queryType === "write") const { reason, unreadable } = explainWrite(input.sql, dialect) const next = unreadable - ? "Fix the query and call sql_execute again; the same text will be refused again." + ? "Fix the query and call sql_execute again; the same text will be refused again." + + (input.warehouseGiven || input.dialects.length < 2 + ? "" + : " No warehouse was given, so the query was read in every dialect it could reach; pass warehouse to read it in that warehouse's dialect only.") : input.scratch - ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission; send reads in their own call." + ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission, each call without reads; other statements (ATTACH, COPY, INSTALL, SET, ...) need write permission." : "Rewrite it as a single read (SELECT, or WITH ... SELECT). To keep an intermediate result, store it in scratch with sql_materialize if that tool is available." return `${head} ${reason}. ${next}` } diff --git a/packages/opencode/test/altimate/mcp-server/workspace.test.ts b/packages/opencode/test/altimate/mcp-server/workspace.test.ts index 2162004abc..623d645969 100644 --- a/packages/opencode/test/altimate/mcp-server/workspace.test.ts +++ b/packages/opencode/test/altimate/mcp-server/workspace.test.ts @@ -33,6 +33,9 @@ test("only the supported workspace read capabilities cross the facade", () => { test("workspace SQL reuses the native classifier and refuses mutation, hidden side effects and absent SQL", () => { expect(() => checkEngineRead("snowflake_execute_database_query", { query: "SELECT 1" })).not.toThrow() + expect(() => checkEngineRead("postgresql_execute_database_query", { query: "SELECT 1; DELETE FROM t" })).toThrow( + "statement 2 of 2 is not a read (DELETE)", + ) expect(() => checkEngineRead("postgresql_execute_database_query", { sql: "SELECT count(*) FROM orders" }), ).not.toThrow() diff --git a/packages/opencode/test/altimate/sql-materialize.test.ts b/packages/opencode/test/altimate/sql-materialize.test.ts index 05b9e0a5eb..6de6c541ba 100644 --- a/packages/opencode/test/altimate/sql-materialize.test.ts +++ b/packages/opencode/test/altimate/sql-materialize.test.ts @@ -347,6 +347,10 @@ describe("sql_materialize", () => { /only reads/, ) } + // The refusal names the statement that writes. + await expect( + materialize({ source_warehouse: "ordersdb", sql: "SELECT 1; DELETE FROM orders", target_table: "nope" }), + ).rejects.toThrow("statement 2 of 2 is not a read (DELETE)") const db = new Database(ordersDb, { readonly: true }) expect((db.query("SELECT count(*) AS n FROM orders").get() as any).n).toBe(4) db.close() diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index f2b2db5b69..f230db69ec 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -27,6 +27,16 @@ describe("shellResidue", () => { expect(shellResidue("SELECT a FROM t WHERE x >= 2.5", "postgres")).toBeUndefined() }) + test("a comparison before the residue is kept", () => { + expect(shellResidue("SELECT a FROM t WHERE flag OR x > 1.5 2>/dev/null", "postgres")).toBe("2>/dev/null") + expect(shellResidue("SELECT a FROM t WHERE x > t.total 2>/dev/null", "postgres")).toBe("2>/dev/null") + }) + + test("SQL that parses is never offered for removal", () => { + expect(shellResidue("SELECT a FROM t WHERE a > out.csv", "postgres")).toBeUndefined() + expect(shellResidue("SELECT a FROM t WHERE a > b / 2", "postgres")).toBeUndefined() + }) + test("text inside a comment or literal is not residue", () => { expect(shellResidue("SELECT 1 -- 2>/dev/null", "postgres")).toBeUndefined() expect(shellResidue("SELECT '2>/dev/null'", "postgres")).toBeUndefined() @@ -44,6 +54,11 @@ describe("other read-only refusals carry the reason", () => { expect(() => readSql("SELECT 1; DELETE FROM t", "postgres")).toThrow("statement 2 of 2") }) + test("qualified columns named like keywords are reads here too", () => { + expect(readSql("SELECT o.update, o.delete FROM orders o", "postgres")).toBe("SELECT o.update, o.delete FROM orders o") + expect(() => readSql("SELECT 1. INTO c FROM orders", "postgres")).toThrow() + }) + test("a refusal that is not about writing stays as it was", () => { expect(writeReason("SELECT 1", "postgres")).toBe("") }) @@ -70,7 +85,7 @@ describe("explainWrite", () => { test("names the first write statement", () => { expect(explainWrite("SELECT 1; SELECT 2; DROP TABLE t", "postgres")).toEqual({ unreadable: false, - reason: "statement 3 of 3 (DROP TABLE t) is not a read (DROP TABLE)", + reason: "statement 3 of 3 is not a read (DROP TABLE)", }) expect(explainWrite("COPY INTO orders FROM @stage", "snowflake").reason).toBe("it is not a read (COPY)") }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 7d2ce9df05..5e6c01a60d 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -1,5 +1,6 @@ import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test" import { PermissionV1 } from "@opencode-ai/core/v1/permission" +import { PermissionNext } from "../../../src/permission/next" import { SessionID, MessageID } from "../../../src/session/schema" import { SqlExecuteTool } from "../../../src/altimate/tools/sql-execute" import { classifyAndCheck, isScratchSafeWrite } from "../../../src/altimate/tools/sql-classify" @@ -143,20 +144,21 @@ describe("sql_execute on a read-only agent", () => { test("unparseable SQL reports the parser's position", async () => { const { error } = await run("SELECT Order Date FROM orders WHERE Order Date > '2020-01-01'") - expect(error).toMatch(/could not read it \(.*line 1, column \d+/) + expect(error).toMatch(/sqlite SQL parser could not read it \(.*line 1, column \d+/) expect(error).toContain("Fix the query") }) test("a write names the statement and suggests a read", async () => { const { error } = await run("SELECT 1; DELETE FROM orders") - expect(error).toContain("statement 2 of 2 (DELETE FROM orders) is not a read (DELETE)") + expect(error).toContain("statement 2 of 2 is not a read (DELETE)") + expect(error).not.toContain("FROM orders") expect(error).toContain("single read") }) test("a scratch batch mixing a write and a read says to split it", async () => { const { error } = await run("CREATE TABLE items AS SELECT 1 AS v; SELECT * FROM items", "scratch") expect(error).toContain("statement 1 of 2") - expect(error).toContain("send reads in their own call") + expect(error).toContain("each call without reads") }) test("a scratch write through the scratch catalog runs without asking", async () => { @@ -165,6 +167,14 @@ describe("sql_execute on a read-only agent", () => { expect(asked).toHaveLength(0) }) + test("a denial from the subagent permission path is explained too", async () => { + const tool = await initTool(SqlExecuteTool) + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionNext.DeniedError([])) } + await expect( + tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("it is not a read (DELETE)") + }) + test("errors other than a rule denial pass through unchanged", async () => { const tool = await initTool(SqlExecuteTool) const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new Error("rejected by test")) } From 4c2d954000a4853eb3b83161b49d211c1451fa5f Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 08:10:58 -0800 Subject: [PATCH 04/58] fix: qualified columns are reads on SQL Server too; refusal reasons follow every classifier check - The T-SQL batch keyword scan skips names qualified by a whole identifier and reports the keyword. - A pipe residue stops at `;`, so a following statement is never hidden as shell syntax. Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/sql-classify.ts | 41 ++++++++++++++----- .../tools/sql-readonly-guard-explain.test.ts | 10 +++++ .../altimate/tools/sql-readonly-guard.test.ts | 4 +- 3 files changed, 42 insertions(+), 13 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index f8fab6040d..7692e46744 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -221,11 +221,13 @@ function classifyFallback(sql: string, dialect?: string, write = true): { queryT return { queryType: "write", blocked } } -/** Where statements need no separator (T-SQL) or the dialect is not one the lexer models, a read +/** The statement keyword, if any. Where statements need no separator (T-SQL) or the dialect is not one the lexer models, a read * must hold no statement keyword in its code (literals, identifiers and comments masked): the * engine would run `SELECT ... DELETE FROM t` as two statements however a parser reads it. */ -function batchedStatement(masked: string, dialect?: string): boolean { - return (/^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") || !isModeledDialect(dialect)) && BATCH_STATEMENT.test(masked) +function batchedStatement(masked: string, dialect?: string): string | undefined { + if (!/^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") && isModeledDialect(dialect)) return undefined + // A name qualified by a whole unquoted identifier (t.update, t.into) cannot start a statement. + return BATCH_STATEMENT.exec(masked.replace(/((?:^|[^\w$])[A-Za-z_][\w$]*\.)[A-Za-z_][\w$]*/g, "$1_"))?.[0] } // T-SQL statements that can follow a read in the same batch. Words that are also common column names @@ -532,7 +534,7 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // `x > t.total` never match. const SHELL_REDIRECT = /\s(?:[12]|&)?>>?\s*(?:&[12]|\/dev\/null)(?![\w/])/g const SHELL_TAIL = - /(?:\s*\|\s*(?:head|tail|grep|egrep|less|more|cat|wc|sort|uniq|cut|column|jq|tee|awk|sed)\b[^|\n]*|\s*(?:[12]|&)?>>?\s*(?:(?:\/|\.\.?\/|~\/)[\w./~-]*|[\w~-][\w~.-]*\.(?:csv|tsv|txt|json|jsonl|log|out|err|sql|parquet|tmp)\b))+\s*;?\s*$/i + /(?:\s*\|\s*(?:head|tail|grep|egrep|less|more|cat|wc|sort|uniq|cut|column|jq|tee|awk|sed)\b[^|;\n]*|\s*(?:[12]|&)?>>?\s*(?:(?:\/|\.\.?\/|~\/)[\w./~-]*|[\w~-][\w~.-]*\.(?:csv|tsv|txt|json|jsonl|log|out|err|sql|parquet|tmp)\b))+\s*;?\s*$/i /** The shell syntax in a query that is a read without it, or undefined. Only code counts (literals and * comments are masked). The query is never rewritten: the caller names the residue so the sender removes @@ -587,7 +589,8 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u for (const [index, statement] of statements.entries()) { const result = classifySql(statement, dialect, 0) if (result.queryType === "read" && !result.blocked) continue - // No SQL text is quoted back: the error is also recorded by telemetry. + // Statements are not quoted back, since telemetry records this error; the parser's own message + // quotes at most a token, which telemetry masks as a literal. const where = statements.length > 1 ? `statement ${index + 1} of ${statements.length}` : "it" if (result.parseError) { return unreadable( @@ -596,17 +599,33 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u "check the clause order, and replace any placeholder text such as ..." ) } - let type: string | undefined + // The checks below follow classifySql's conditions. + let parsed: { category?: string; statement_type?: string } | undefined try { - type = getStatementTypes?.(parserSql(statement, dialect), dialect)?.statements?.[0]?.statement_type + parsed = getStatementTypes?.(parserSql(statement, dialect), dialect)?.statements?.[0] } catch { - type = undefined + parsed = undefined } - if (type && !/^(SELECT|QUERY)$/i.test(type)) return writes(`${where} is not a read (${type.toUpperCase()})`) - if (hasQueryWriteClause(statement, dialect)) { + const type = String(parsed?.statement_type ?? "statement").toUpperCase() + const tokens = tokenizeSql(statement, dialect).tokens + const masked = maskSql(tokens) + if (functionSafety(statement, dialect, 0).write) return writes(`${where} calls a function that can modify data or run other SQL`) + const keyword = batchedStatement(masked, dialect) + if (keyword) { + return writes( + `${where} holds the statement keyword ${keyword.trim().split(/\s+/)[0].toUpperCase()} outside a literal or comment; ` + + "SQL Server runs a statement there even without a separator, so quote it if it is a column name", + ) + } + if (/^snowflake$/i.test(dialect ?? "") && masked.includes("->>")) return writes(`${where} chains statements with ->>`) + if (/\bTRANSFORM\s*\(/i.test(masked) && /\bUSING\b(?!\s*\()/i.test(masked)) { + return writes(`${where} runs a command through TRANSFORM ... USING`) + } + if (advancesSequence(tokens, masked, dialect)) return writes(`${where} advances a sequence`) + if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { return writes(`${where} contains a write clause (SELECT ... INTO, or INSERT/UPDATE/DELETE/MERGE inside a CTE)`) } - if (functionSafety(statement, dialect, 0).write) return writes(`${where} calls a function that can modify data or run other SQL`) + if (parsed?.category !== "query") return writes(`${where} is not a read (${type})`) return writes(`${where} could not be proven read-only`) } return writes("the statements together could not be proven read-only") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index f230db69ec..d4111bfd53 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -42,6 +42,12 @@ describe("shellResidue", () => { expect(shellResidue("SELECT '2>/dev/null'", "postgres")).toBeUndefined() }) + test("a write after residue is named, not hidden in the residue", () => { + const sql = "SELECT 1 FROM t | head -5; DROP TABLE t" + expect(shellResidue(sql, "postgres")).toBeUndefined() + expect(explainWrite(sql, "postgres").reason).not.toContain("shell syntax") + }) + test("a write followed by residue is not offered as a read", () => { expect(shellResidue("DELETE FROM t 2>/dev/null", "postgres")).toBeUndefined() expect(explainWrite("DELETE FROM t 2>/dev/null", "postgres").reason).not.toContain("shell syntax") @@ -90,6 +96,10 @@ describe("explainWrite", () => { expect(explainWrite("COPY INTO orders FROM @stage", "snowflake").reason).toBe("it is not a read (COPY)") }) + test("names a SQL Server batch keyword", () => { + expect(explainWrite("SELECT exec FROM t", "sqlserver").reason).toContain("statement keyword EXEC") + }) + test("names a write clause inside a query", () => { for (const sql of ["WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x", "SELECT * INTO c FROM t"]) { expect(explainWrite(sql, "postgres")).toEqual({ unreadable: false, reason: expect.stringContaining("write clause") }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 5e6c01a60d..a2e1ed7015 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -11,7 +11,7 @@ import { initTool } from "../tool-fixture" // A read-only agent denies `sql_execute_write`. Reads must never reach that rule, and when a query does, // the agent must learn why and what to change instead of a raw permission-rule dump it tends to retry. -const DIALECTS = ["postgres", "snowflake", "bigquery", "duckdb", "sqlite", "mysql", "databricks", "redshift"] +const DIALECTS = ["postgres", "snowflake", "bigquery", "duckdb", "sqlite", "mysql", "databricks", "redshift", "sqlserver", "oracle", "clickhouse"] const isRead = (sql: string, dialect: string) => { const result = classifyAndCheck(sql, dialect) @@ -95,7 +95,7 @@ describe("writes stay writes", () => { "SELECT INTO after a hex number ending in a dot": "SELECT 0x1.INTO copy_of_orders FROM orders", "SELECT INTO after a spaced qualifier": "SELECT o. INTO copy_of_orders FROM orders o", "write followed by shell residue": "DELETE FROM orders 2>/dev/null", - "unparseable text": "SELECT a b c FROM WHERE", + "unparseable text": "SELECT FROM WHERE (((", } for (const [name, sql] of Object.entries(writes)) { test(name, () => { From 6a9d1c64a3cb59cb6c146640948d55fc1718ae8a Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 08:18:21 -0800 Subject: [PATCH 05/58] fix: refusal reasons keep file paths and pipe arguments out; a qualified `replace` column is a read - Shell residue is named by its form (`> `, `| head ...`), since the error is also recorded by telemetry. - The TRANSFORM reason applies only where the classifier checks it. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/read-only-sql.ts | 2 +- .../opencode/src/altimate/tools/sql-classify.ts | 16 ++++++++++++++-- .../tools/sql-readonly-guard-explain.test.ts | 16 ++++++++++++---- 3 files changed, 27 insertions(+), 7 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 9096611aad..422b2b1a46 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -55,7 +55,7 @@ export function readSql(sql: string, dialect?: string): string { /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|COPY|ATTACH|DETACH|PRAGMA|VACUUM|CALL|DO|INTO|INSTALL|LOAD|EXPORT|IMPORT|GRANT|REVOKE)\b(?>?\s*)(?!&[12]|\/dev\/null)\S+/g, "$1") + .replace(/(\|\s*[A-Za-z]+)[^|]*/g, "$1 ..."), + ) position = end } query += sql.slice(position) @@ -618,7 +626,11 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u ) } if (/^snowflake$/i.test(dialect ?? "") && masked.includes("->>")) return writes(`${where} chains statements with ->>`) - if (/\bTRANSFORM\s*\(/i.test(masked) && /\bUSING\b(?!\s*\()/i.test(masked)) { + if ( + (/^(spark|databricks|hive)$/i.test(dialect ?? "") || !isModeledDialect(dialect)) && + /\bTRANSFORM\s*\(/i.test(masked) && + /\bUSING\b(?!\s*\()/i.test(masked) + ) { return writes(`${where} runs a command through TRANSFORM ... USING`) } if (advancesSequence(tokens, masked, dialect)) return writes(`${where} advances a sequence`) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index d4111bfd53..97b8e7a3c7 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -7,12 +7,14 @@ describe("shellResidue", () => { "SELECT 1 2>/dev/null": "2>/dev/null", "SELECT * FROM t LIMIT 5 2>&1": "2>&1", "SELECT * FROM t >/dev/null": ">/dev/null", - "SELECT * FROM t > out.csv": "> out.csv", - "SELECT * FROM t | head -20": "| head -20", - "SELECT * FROM t LIMIT 5 2>&1 | head -n 20": "2>&1`, `| head -n 20", + "SELECT * FROM t > /home/someone/private/out.csv": "> ", + "SELECT * FROM t | grep private-name": "| grep ...", + "SELECT * FROM t > out.csv": "> ", + "SELECT * FROM t | head -20": "| head ...", + "SELECT * FROM t LIMIT 5 2>&1 | head -n 20": "2>&1`, `| head ...", "SELECT * FROM t; 2>/dev/null": "2>/dev/null", "SELECT a FROM t ORDER BY a 2>/dev/null LIMIT 5": "2>/dev/null", - "SELECT a FROM t 2>/dev/null | head -5": "2>/dev/null`, `| head -5", + "SELECT a FROM t 2>/dev/null | head -5": "2>/dev/null`, `| head ...", } for (const [sql, residue] of Object.entries(cases)) { test(`finds ${residue}`, () => { @@ -62,6 +64,8 @@ describe("other read-only refusals carry the reason", () => { test("qualified columns named like keywords are reads here too", () => { expect(readSql("SELECT o.update, o.delete FROM orders o", "postgres")).toBe("SELECT o.update, o.delete FROM orders o") + expect(readSql("SELECT o.replace FROM orders o", "postgres")).toBe("SELECT o.replace FROM orders o") + expect(() => readSql("REPLACE INTO orders VALUES (1)", "mysql")).toThrow() expect(() => readSql("SELECT 1. INTO c FROM orders", "postgres")).toThrow() }) @@ -96,6 +100,10 @@ describe("explainWrite", () => { expect(explainWrite("COPY INTO orders FROM @stage", "snowflake").reason).toBe("it is not a read (COPY)") }) + test("a TRANSFORM call outside Spark and Hive does not hide the statement type", () => { + expect(explainWrite("DELETE FROM t USING u WHERE transform(t.x) = 1", "postgres").reason).toBe("it is not a read (DELETE)") + }) + test("names a SQL Server batch keyword", () => { expect(explainWrite("SELECT exec FROM t", "sqlserver").reason).toContain("statement keyword EXEC") }) From 2101006d86da8f7a4f13a581795d9547d52dbac1 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 08:26:36 -0800 Subject: [PATCH 06/58] fix: shell-residue detection uses anchored patterns only; docs match the qualified-column rule - Redirects to a descriptor or /dev/null anywhere, plus one trailing pipe or file redirect, matched without nested repetition (no backtracking on a crafted tail). Fragments are named by form. Co-Authored-By: Claude Opus 5.5 --- docs/docs/configure/permissions.md | 2 +- .../src/altimate/tools/sql-classify.ts | 69 ++++++++++--------- .../tools/sql-readonly-guard-explain.test.ts | 15 +++- 3 files changed, 50 insertions(+), 36 deletions(-) diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index 954651c086..8fad4560eb 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -253,7 +253,7 @@ When prompted, you have three choices: ### How SQL is classified for `sql_execute_write` -`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals and column names that contain words like `update` or `delete` do not count. SQL the parser cannot read is treated as a write, so it is never run without write permission. +`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts` or `t.update` do not count; a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. When an agent's `sql_execute_write` is `"deny"`, the tool error tells the agent why the query counted as a write and what to change: the statement that writes, the parser error and its position, or trailing shell syntax such as `2>/dev/null` to remove. diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 1edbf48c71..831be8d8e8 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -528,52 +528,53 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { } // Shell syntax pasted into a query out of terminal habit. A redirect to a descriptor or /dev/null -// (`2>/dev/null`, `2>&1`) can sit anywhere, even before LIMIT; a pipe into a shell command (`| head -20`) -// or a redirect into a file (`> out.csv`) only ends the text. A file target must start like a path -// (/, ./, ../, ~/) or end in a known output extension, so comparisons such as `x > 2`, `x > 1.5` and -// `x > t.total` never match. -const SHELL_REDIRECT = /\s(?:[12]|&)?>>?\s*(?:&[12]|\/dev\/null)(?![\w/])/g -const SHELL_TAIL = - /(?:\s*\|\s*(?:head|tail|grep|egrep|less|more|cat|wc|sort|uniq|cut|column|jq|tee|awk|sed)\b[^|;\n]*|\s*(?:[12]|&)?>>?\s*(?:(?:\/|\.\.?\/|~\/)[\w./~-]*|[\w~-][\w~.-]*\.(?:csv|tsv|txt|json|jsonl|log|out|err|sql|parquet|tmp)\b))+\s*;?\s*$/i +// (`2>/dev/null`, `2>&1`) can sit anywhere, even before LIMIT. At the very end there may also be one pipe +// into a shell command (`| head -20`) or one redirect into a file (`> out.csv`). A file target must start +// like a path (/, ./, ../, ~/) or end in a known output extension, so comparisons such as `x > 2`, +// `x > 1.5` and `x > t.total` never match. Every pattern is anchored with no nested repetition, so a +// crafted tail cannot make the scan backtrack. +const SHELL_REDIRECT = /\s(?:[12]|&)?>>?[ \t]*(?:&[12]|\/dev\/null)(?![\w/])/g +const SHELL_PIPE_TAIL = /\|[ \t]*(head|tail|grep|egrep|less|more|cat|wc|sort|uniq|cut|column|jq|tee|awk|sed)\b[^|;\n]*$/i +const SHELL_FILE_TAIL = + /\s(?:[12]|&)?>>?[ \t]*(?:(?:\/|\.\.?\/|~\/)[\w./~-]*|[\w~-][\w~.-]*\.(?:csv|tsv|txt|json|jsonl|log|out|err|sql|parquet|tmp))[ \t]*$/i /** The shell syntax in a query that is a read without it, or undefined. Only code counts (literals and - * comments are masked). The query is never rewritten: the caller names the residue so the sender removes - * it, since running the query without it would run SQL other than what was sent. */ + * comments are masked), and only text that does not parse as sent. The query is never rewritten: the + * caller names the residue so the sender removes it, since running the query without it would run SQL + * other than what was sent. Fragments are named by their form (`2>/dev/null`, `> `, `| head ...`), + * since a path or a pipe's arguments may hold private text and telemetry records the error. */ export function shellResidue(sql: string, dialect?: string): string | undefined { const lexical = tokenizeSql(sql, dialect) - // Residue is only an explanation for text that does not parse; valid SQL is never offered for removal. if (!lexical.complete || !classifyAndCheck(sql, dialect).parseError) return undefined - // Masking keeps every offset, so a match in the masked text cuts the same span of the original. - const masked = maskSql(lexical.tokens) - const cuts = [...masked.matchAll(SHELL_REDIRECT)].map((match) => [match.index!, match.index! + match[0].length]) - // Only the tail can hold a pipe or file redirect; bounding it keeps the scan cheap on large queries. - const offset = Math.max(0, masked.length - 400) - const tail = SHELL_TAIL.exec(masked.slice(offset)) - if (tail) cuts.push([offset + tail.index, masked.length]) + // Masking keeps every offset, so a span of the masked text cuts the same span of the original. + let masked = maskSql(lexical.tokens) + const cuts: Array<{ start: number; end: number; label: string }> = [] + for (const match of masked.matchAll(SHELL_REDIRECT)) { + cuts.push({ start: match.index!, end: match.index! + match[0].length, label: match[0].replace(/\s+/g, "") }) + } + // Only the last 400 characters can hold a tail; strip trailing ; and whitespace first. + const end = masked.replace(/[\s;]+$/, "").length + const offset = Math.max(0, end - 400) + const window = masked.slice(offset, end) + const pipe = SHELL_PIPE_TAIL.exec(window) + const file = pipe ? undefined : SHELL_FILE_TAIL.exec(window) + if (pipe) cuts.push({ start: offset + pipe.index, end: masked.length, label: `| ${pipe[1].toLowerCase()} ...` }) + if (file) cuts.push({ start: offset + file.index, end: masked.length, label: `${file[0].trim().match(/^[12&]?>>?/)![0]} ` }) if (!cuts.length) return undefined - cuts.sort((a, b) => a[0] - b[0]) - const fragments: string[] = [] + cuts.sort((a, b) => a.start - b.start) + const labels: string[] = [] let query = "" let position = 0 - for (const [start, end] of cuts) { - if (end <= position) continue - const from = Math.max(start, position) - query += sql.slice(position, from) + " " - // Name only the shell form: a file path or a pipe's arguments may hold private text, and telemetry - // records this error. - fragments.push( - sql - .slice(from, end) - .trim() - .replace(/(>>?\s*)(?!&[12]|\/dev\/null)\S+/g, "$1") - .replace(/(\|\s*[A-Za-z]+)[^|]*/g, "$1 ..."), - ) - position = end + for (const cut of cuts) { + if (cut.end <= position) continue + query += sql.slice(position, Math.max(cut.start, position)) + " " + labels.push(cut.label) + position = cut.end } query += sql.slice(position) if (!query.trim()) return undefined const result = classifyAndCheck(query, dialect) - return result.queryType === "read" && !result.blocked ? fragments.filter(Boolean).join("`, `") : undefined + return result.queryType === "read" && !result.blocked ? labels.join("`, `") : undefined } /** diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 97b8e7a3c7..b7e0c32723 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -29,6 +29,19 @@ describe("shellResidue", () => { expect(shellResidue("SELECT a FROM t WHERE x >= 2.5", "postgres")).toBeUndefined() }) + test("an appended redirect is named as written, and several pipes by their last command", () => { + expect(shellResidue("SELECT * FROM t 2>> /dev/null", "postgres")).toBe("2>>/dev/null") + expect(shellResidue("SELECT * FROM t | grep -i private | head", "postgres")).toBeUndefined() + }) + + test("a crafted tail is scanned in linear time", () => { + const start = performance.now() + shellResidue(`SELECT * FROM t ${"| head ".repeat(60)}x;y`, "postgres") + shellResidue(`SELECT * FROM t ${"| head ".repeat(44)};y`, "postgres") + explainWrite(`SELECT * FROM t ${"| head ".repeat(60)}x;y`, "postgres") + expect(performance.now() - start).toBeLessThan(1000) + }) + test("a comparison before the residue is kept", () => { expect(shellResidue("SELECT a FROM t WHERE flag OR x > 1.5 2>/dev/null", "postgres")).toBe("2>/dev/null") expect(shellResidue("SELECT a FROM t WHERE x > t.total 2>/dev/null", "postgres")).toBe("2>/dev/null") @@ -57,7 +70,7 @@ describe("shellResidue", () => { }) describe("other read-only refusals carry the reason", () => { - test("sql_check and query_from (readSql)", () => { + test("sql_check (readSql)", () => { expect(() => readSql("SELECT 1 2>/dev/null", "postgres")).toThrow("`2>/dev/null`") expect(() => readSql("SELECT 1; DELETE FROM t", "postgres")).toThrow("statement 2 of 2") }) From effb526081b8009c3afda686d77ae15a1e07d38e Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 08:35:32 -0800 Subject: [PATCH 07/58] fix: dotted names of any length are columns, never after a number; test every refusal branch - Qualifier chains (s.t.update) are exempt in the classifier, readSql and the SQL Server batch scan; a qualifier never follows a dot or digit (1.e.INTO stays a write). - Tests for the Jinja, MongoDB and no-warehouse refusal messages. Co-Authored-By: Claude Opus 5.5 --- docs/docs/configure/permissions.md | 2 +- .../src/altimate/tools/read-only-sql.ts | 4 ++-- .../src/altimate/tools/sql-classify.ts | 10 ++++++--- .../src/altimate/tools/sql-execute.ts | 5 +++-- .../altimate/tools/sql-readonly-guard.test.ts | 22 ++++++++++++++++++- 5 files changed, 34 insertions(+), 9 deletions(-) diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index 8fad4560eb..63284fa424 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -253,7 +253,7 @@ When prompted, you have three choices: ### How SQL is classified for `sql_execute_write` -`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts` or `t.update` do not count; a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. +`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count; a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. When an agent's `sql_execute_write` is `"deny"`, the tool error tells the agent why the query counted as a write and what to change: the statement that writes, the parser error and its position, or trailing shell syntax such as `2>/dev/null` to remove. diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 422b2b1a46..8d4643efcd 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -52,10 +52,10 @@ export function readSql(sql: string, dialect?: string): string { checked === undefined || !/^(SELECT|WITH)\b/i.test(body) || // A column qualified by a whole identifier (t.update) is not a statement word, as in the classifier. - /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|COPY|ATTACH|DETACH|PRAGMA|VACUUM|CALL|DO|INTO|INSTALL|LOAD|EXPORT|IMPORT|GRANT|REVOKE)\b(? + head + rest.replace(/[A-Za-z_][\w$]*/g, "_"), + ) + return BATCH_STATEMENT.exec(names)?.[0] } // T-SQL statements that can follow a read in the same batch. Words that are also common column names diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index faf472ddee..1052d04d68 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -221,7 +221,8 @@ export const SqlExecuteTool = Tool.define( }) } // altimate_change start - SQL write access control - // Permission checks OUTSIDE try/catch so denial errors propagate to the framework + // Permission checks OUTSIDE the execution try/catch: a rule denial of sql_execute_write is rethrown + // with its reason below, and every other permission error propagates unchanged // MongoDB warehouses take JSON command documents; the SQL classifier would read // every one as a write. Dispatch the normalized `{command, collection}` form. const warehouse = args.warehouse || Registry.list().warehouses[0]?.name @@ -742,7 +743,7 @@ function classifyEvery(sql: string, dialects: (string | undefined)[]) { // altimate_change start — a denied write says why and how to proceed /** The error a read-only agent gets when its query counts as a write: the reason, then what to do next, * so the agent fixes the query instead of resending it. */ -function deniedWriteMessage(input: { +export function deniedWriteMessage(input: { sql: string dialects: (string | undefined)[] jinja: boolean diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index a2e1ed7015..156616dbab 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -2,7 +2,7 @@ import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test import { PermissionV1 } from "@opencode-ai/core/v1/permission" import { PermissionNext } from "../../../src/permission/next" import { SessionID, MessageID } from "../../../src/session/schema" -import { SqlExecuteTool } from "../../../src/altimate/tools/sql-execute" +import { SqlExecuteTool, deniedWriteMessage } from "../../../src/altimate/tools/sql-execute" import { classifyAndCheck, isScratchSafeWrite } from "../../../src/altimate/tools/sql-classify" import * as Registry from "../../../src/altimate/native/connections/registry" import { closeScratch } from "../../../src/altimate/native/connections/scratch" @@ -57,6 +57,7 @@ describe("reads are classified as reads in every dialect", () => { "string literal with write words": "SELECT * FROM orders WHERE status = 'DELETED' OR note = 'insert into x'", "identifiers containing write words": "SELECT update_ts, created_by, deleted_at FROM orders", "qualified columns named like write keywords": "SELECT o.update, o.delete, o.insert, o.merge FROM orders o", + "three-part names ending in a write keyword": "SELECT s.o.update FROM s.o", "CTE": "WITH a AS (SELECT 1 AS x), b AS (SELECT x FROM a) SELECT * FROM b", "EXPLAIN of a read": "EXPLAIN SELECT * FROM orders", "leading whitespace": "\n\n SELECT 1", @@ -94,6 +95,7 @@ describe("writes stay writes", () => { "SELECT INTO after a column and a number ending in a dot": "SELECT o.a, 2. INTO copy_of_orders FROM orders o", "SELECT INTO after a hex number ending in a dot": "SELECT 0x1.INTO copy_of_orders FROM orders", "SELECT INTO after a spaced qualifier": "SELECT o. INTO copy_of_orders FROM orders o", + "SELECT INTO after a float with an exponent letter": "SELECT 1.e.INTO copy_of_orders FROM orders", "write followed by shell residue": "DELETE FROM orders 2>/dev/null", "unparseable text": "SELECT FROM WHERE (((", } @@ -183,3 +185,21 @@ describe("sql_execute on a read-only agent", () => { ) }) }) + +describe("denied write message branches", () => { + const base = { sql: "SELECT 1", dialects: ["postgres"], jinja: false, mongo: false, scratch: false, warehouseGiven: true } + + test("Jinja asks for plain SQL", () => { + expect(deniedWriteMessage({ ...base, sql: "SELECT * FROM {{ ref('x') }}", jinja: true })).toContain("Send plain SQL without Jinja") + }) + + test("a MongoDB write asks for a read command", () => { + expect(deniedWriteMessage({ ...base, sql: '{"command":"insertOne"}', mongo: true })).toContain("Use a read command") + }) + + test("an unreadable query without a warehouse suggests passing one", () => { + const message = deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((", dialects: ["postgres", "snowflake"], warehouseGiven: false }) + expect(message).toContain("pass warehouse") + expect(deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((" })).not.toContain("pass warehouse") + }) +}) From b4e4dafe230a97ce1f4e38f21a41a4f6d3a94cc5 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 08:42:36 -0800 Subject: [PATCH 08/58] test: send a rule denial through `Effect.runPromise`, as the tool bridge does Co-Authored-By: Claude Opus 5.5 --- .../test/altimate/tools/sql-readonly-guard.test.ts | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 156616dbab..dbd256ac51 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -1,4 +1,5 @@ import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test" +import { Effect } from "effect" import { PermissionV1 } from "@opencode-ai/core/v1/permission" import { PermissionNext } from "../../../src/permission/next" import { SessionID, MessageID } from "../../../src/session/schema" @@ -169,6 +170,18 @@ describe("sql_execute on a read-only agent", () => { expect(asked).toHaveLength(0) }) + test("a denial that fails an Effect, as the tool bridge runs it, is explained", async () => { + const tool = await initTool(SqlExecuteTool) + // The production context runs ctx.ask through Effect.runPromise (EffectBridge.promise). + const ctx = { + ...deniedCtx([]), + ask: () => Effect.runPromise(Effect.fail(new PermissionV1.DeniedError({ ruleset: [] }))), + } + await expect( + tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("it is not a read (DELETE)") + }) + test("a denial from the subagent permission path is explained too", async () => { const tool = await initTool(SqlExecuteTool) const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionNext.DeniedError([])) } From de0937fd456edc3546c87bbf38620e4654ca465e Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 08:50:42 -0800 Subject: [PATCH 09/58] fix: name a plain write by its type on SQL Server; keep SQL text out of parser messages - The statement type is reported before any T-SQL batch keyword, and SQL Server is named only for its dialects. - Parser messages drop quoted tokens and `near [...]` snippets before reaching the refusal. Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/sql-classify.ts | 18 +++++++++++++-- .../tools/sql-readonly-guard-explain.test.ts | 22 +++++++++++++++++++ 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index e64ec05cb7..2ddb768c42 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -581,6 +581,15 @@ export function shellResidue(sql: string, dialect?: string): string | undefined return result.queryType === "read" && !result.blocked ? labels.join("`, `") : undefined } +/** The parser's message with any quoted or named token removed: only the position and the kind of error + * remain, since telemetry records this error and does not mask a bare word. */ +function parserMessage(message: string): string { + return message + .replace(/\s*near \[[^\]]*\]?/gi, "") + .replace(/\s*\('[^']*'\)/g, "") + .replace(/(Unexpected token|found|got):\s*[^\s,)]+/gi, "$1 a token") +} + /** * Why classifyAndCheck treats this SQL as a write, in words an agent can act on: shell residue to * remove, the parser error and its position, or the first statement that is not a read. `unreadable` @@ -607,7 +616,7 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u const where = statements.length > 1 ? `statement ${index + 1} of ${statements.length}` : "it" if (result.parseError) { return unreadable( - `the ${dialect ?? "generic"} SQL parser could not read ${where} (${result.parseError}), so it cannot be proven read-only. ` + + `the ${dialect ?? "generic"} SQL parser could not read ${where} (${parserMessage(result.parseError)}), so it cannot be proven read-only. ` + 'Fix the syntax at that position: quote identifiers that contain spaces or are keywords ("order date"), ' + "check the clause order, and replace any placeholder text such as ..." ) @@ -623,11 +632,16 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u const tokens = tokenizeSql(statement, dialect).tokens const masked = maskSql(tokens) if (functionSafety(statement, dialect, 0).write) return writes(`${where} calls a function that can modify data or run other SQL`) + // A statement that is itself a write is named by its type, before any batch keyword inside it. + if (parsed && parsed.category !== "query") return writes(`${where} is not a read (${type})`) const keyword = batchedStatement(masked, dialect) if (keyword) { + const engine = /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") + ? "SQL Server runs a statement there even without a separator" + : "this dialect is not modeled, so it may run as a statement" return writes( `${where} holds the statement keyword ${keyword.trim().split(/\s+/)[0].toUpperCase()} outside a literal or comment; ` + - "SQL Server runs a statement there even without a separator, so quote it if it is a column name", + `${engine}; quote it if it is a column name`, ) } if (/^snowflake$/i.test(dialect ?? "") && masked.includes("->>")) return writes(`${where} chains statements with ->>`) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index b7e0c32723..8b7e7a1b0e 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -117,6 +117,28 @@ describe("explainWrite", () => { expect(explainWrite("DELETE FROM t USING u WHERE transform(t.x) = 1", "postgres").reason).toBe("it is not a read (DELETE)") }) + test("a plain write on SQL Server or an unmodeled dialect is named by its type", () => { + for (const dialect of ["sqlserver", undefined]) { + expect(explainWrite("DELETE FROM orders", dialect).reason).toBe("it is not a read (DELETE)") + expect(explainWrite("INSERT INTO t VALUES (1)", dialect).reason).toBe("it is not a read (INSERT)") + } + }) + + test("parser messages keep no token text", () => { + const reason = explainWrite("SELECT set FROM t", "sqlserver").reason + expect(reason).toContain("line 1, column") + expect(reason).not.toContain("Set") + for (const sql of [ + "SELECT len(DISTINCT customer_secret_name(a)) FROM t", + "SELECT customer_secret_name customer_x customer_y FROM t", + "SELECT a FROM customer_secret_table WHERE (((", + ]) { + const message = explainWrite(sql, "sqlite").reason + expect(message).toContain("could not read") + expect(message).not.toMatch(/customer_/) + } + }) + test("names a SQL Server batch keyword", () => { expect(explainWrite("SELECT exec FROM t", "sqlserver").reason).toContain("statement keyword EXEC") }) From 57c9b35bcac6a9ada6643a0522cb4c208823a5b9 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 08:59:37 -0800 Subject: [PATCH 10/58] fix: word a pattern-scoped write denial as a rule, not read-only; skip the reason on the result-lint path Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/read-only-sql.ts | 4 ++-- .../src/altimate/tools/sql-classify.ts | 2 +- .../src/altimate/tools/sql-execute.ts | 13 +++++++++++-- .../src/altimate/tools/sql-result-lint.ts | 3 ++- .../tools/sql-readonly-guard-explain.test.ts | 7 +++++++ .../altimate/tools/sql-readonly-guard.test.ts | 19 +++++++++++++++++++ 6 files changed, 42 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 8d4643efcd..572ed19020 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -45,7 +45,7 @@ export function requireReadOnlyQuery(sql: string, dialect?: string): void { /** Ignore quoted content while checking structure; preserve the original SELECT and its LIMIT. * Stricter than requireReadOnlyQuery: sql_check also requires SELECT or WITH and refuses * write keywords anywhere, even where the parser reports a query. */ -export function readSql(sql: string, dialect?: string): string { +export function readSql(sql: string, dialect?: string, options: { explain?: boolean } = {}): string { const checked = readOnlyBody(sql, dialect) const body = checked?.body ?? "" if ( @@ -59,7 +59,7 @@ export function readSql(sql: string, dialect?: string): string { ) { throw new Error( "This operation only accepts a single read-only SELECT (or WITH ... SELECT); it never writes or fixes data." + - writeReason(sql, dialect), + (options.explain === false ? "" : writeReason(sql, dialect)), ) } const semicolon = checked.masked.indexOf(";") diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 2ddb768c42..7c8c264219 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -587,7 +587,7 @@ function parserMessage(message: string): string { return message .replace(/\s*near \[[^\]]*\]?/gi, "") .replace(/\s*\('[^']*'\)/g, "") - .replace(/(Unexpected token|found|got):\s*[^\s,)]+/gi, "$1 a token") + .replace(/(Unexpected token|found|got):\s*[^\s,)]+/gi, "$1") } /** diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 1052d04d68..49b8b7f4d1 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -293,6 +293,7 @@ export const SqlExecuteTool = Tool.define( }) } catch (error) { if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error + const rules: Array<{ permission?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] throw new Error( deniedWriteMessage({ sql, @@ -301,6 +302,8 @@ export const SqlExecuteTool = Tool.define( mongo: mongo !== null, scratch: isScratch(args.warehouse), warehouseGiven: !!args.warehouse, + // Read-only unless a rule of its own allows or asks for some writes (a pattern deny). + readOnly: !rules.some((rule) => rule.permission !== "*" && rule.action !== "deny"), }), ) } @@ -750,8 +753,12 @@ export function deniedWriteMessage(input: { mongo: boolean scratch: boolean warehouseGiven: boolean + readOnly?: boolean }): string { - const head = "sql_execute did not run this query. This agent may only read (write permission is denied), and the query counts as a write because" + const readOnly = input.readOnly !== false + const head = readOnly + ? "sql_execute did not run this query. This agent may only read (write permission is denied), and the query counts as a write because" + : "sql_execute did not run this query. A sql_execute_write rule denies it, and the query counts as a write because" if (input.jinja) { return `${head} it contains Jinja ({{ }}, {% %} or {# #}), which dbt renders and runs before the SQL. Send plain SQL without Jinja.` } @@ -765,7 +772,9 @@ export function deniedWriteMessage(input: { (input.warehouseGiven || input.dialects.length < 2 ? "" : " No warehouse was given, so the query was read in every dialect it could reach; pass warehouse to read it in that warehouse's dialect only.") - : input.scratch + : !readOnly + ? "Change it to a statement the configured sql_execute_write rules allow, or ask the user to change the rules." + : input.scratch ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission, each call without reads; other statements (ATTACH, COPY, INSTALL, SET, ...) need write permission." : "Rewrite it as a single read (SELECT, or WITH ... SELECT). To keep an intermediate result, store it in scratch with sql_materialize if that tool is available." return `${head} ${reason}. ${next}` diff --git a/packages/opencode/src/altimate/tools/sql-result-lint.ts b/packages/opencode/src/altimate/tools/sql-result-lint.ts index 82aa47caf5..5716d395ff 100644 --- a/packages/opencode/src/altimate/tools/sql-result-lint.ts +++ b/packages/opencode/src/altimate/tools/sql-result-lint.ts @@ -56,7 +56,8 @@ export async function lintSqlResult(sql: string, warehouse: string | undefined, const name = warehouse ?? Registry.list().warehouses[0]?.name const type = Registry.canonicalType(name ? Registry.getConfig(name)?.type : undefined) // The general classifier also labels modifying CTEs and SELECT INTO as queries. - readSql(sql, type ?? undefined) + // Only the yes/no matters here: skip the refusal's explanation on this per-result path. + readSql(sql, type ?? undefined, { explain: false }) const timeout = new Promise((resolve) => { timer = setTimeout(() => { slowSessions.add(sessionID) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 8b7e7a1b0e..c53ec6cf0e 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -82,6 +82,12 @@ describe("other read-only refusals carry the reason", () => { expect(() => readSql("SELECT 1. INTO c FROM orders", "postgres")).toThrow() }) + test("the result lint path can skip the explanation", () => { + expect(() => readSql("SELECT 1; DELETE FROM t", "postgres", { explain: false })).toThrow( + /^This operation only accepts a single read-only SELECT \(or WITH \.\.\. SELECT\); it never writes or fixes data\.$/, + ) + }) + test("a refusal that is not about writing stays as it was", () => { expect(writeReason("SELECT 1", "postgres")).toBe("") }) @@ -128,6 +134,7 @@ describe("explainWrite", () => { const reason = explainWrite("SELECT set FROM t", "sqlserver").reason expect(reason).toContain("line 1, column") expect(reason).not.toContain("Set") + expect(reason).not.toContain("a token") for (const sql of [ "SELECT len(DISTINCT customer_secret_name(a)) FROM t", "SELECT customer_secret_name customer_x customer_y FROM t", diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index dbd256ac51..237c1d16ea 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -210,6 +210,25 @@ describe("denied write message branches", () => { expect(deniedWriteMessage({ ...base, sql: '{"command":"insertOne"}', mongo: true })).toContain("Use a read command") }) + test("a pattern-scoped deny does not claim the agent may only read", () => { + const message = deniedWriteMessage({ ...base, sql: "DROP TABLE stg_tmp", readOnly: false }) + expect(message).toContain("A sql_execute_write rule denies it") + expect(message).not.toContain("may only read") + expect(message).toContain("rules allow") + }) + + test("sql_execute reads the denial's rules to choose the wording", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [ + { permission: "sql_execute_write", pattern: "*", action: "allow" }, + { permission: "sql_execute_write", pattern: "DROP*", action: "deny" }, + ] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + await expect( + tool.execute({ query: "DROP TABLE stg_tmp", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("A sql_execute_write rule denies it") + }) + test("an unreadable query without a warehouse suggests passing one", () => { const message = deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((", dialects: ["postgres", "snowflake"], warehouseGiven: false }) expect(message).toContain("pass warehouse") From 270bf826b0dadf85dad56ef8f2f76c8235e1cc45 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 09:15:40 -0800 Subject: [PATCH 11/58] fix: judge read-only from the rule in effect; cut parser messages to position and kind - An agent deny after a user ask is read-only; a pattern deny after an allow is not. - Parser details are cut at the first token, quote or paren, so no literal text reaches the error. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/sql-classify.ts | 13 +++++++------ .../opencode/src/altimate/tools/sql-execute.ts | 11 ++++++++--- .../opencode/src/altimate/tools/sql-materialize.ts | 2 +- .../tools/sql-readonly-guard-explain.test.ts | 1 + .../test/altimate/tools/sql-readonly-guard.test.ts | 14 ++++++++++++++ 5 files changed, 31 insertions(+), 10 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 7c8c264219..bb99d8fd0f 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -581,13 +581,14 @@ export function shellResidue(sql: string, dialect?: string): string | undefined return result.queryType === "read" && !result.blocked ? labels.join("`, `") : undefined } -/** The parser's message with any quoted or named token removed: only the position and the kind of error - * remain, since telemetry records this error and does not mask a bare word. */ +/** The parser's position and the kind of error only: everything from the first quoted or named token + * (`got`, `found`, `near`, a parenthesis, a quote, a colon after the kind) is cut, since telemetry records + * this error and its masking does not cover every token the parser prints. */ function parserMessage(message: string): string { - return message - .replace(/\s*near \[[^\]]*\]?/gi, "") - .replace(/\s*\('[^']*'\)/g, "") - .replace(/(Unexpected token|found|got):\s*[^\s,)]+/gi, "$1") + const located = /^(.*?line \d+, column \d+:\s*)([\s\S]*)$/.exec(message) + const prefix = located ? located[1] : "" + const detail = (located ? located[2] : message).split(/\s+(?:got|found|near)\b|\s*[('"`[:]/i)[0].trim() + return `${prefix}${detail}`.trim() || "parse error" } /** diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 49b8b7f4d1..cc99d0cbbe 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -293,7 +293,13 @@ export const SqlExecuteTool = Tool.define( }) } catch (error) { if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error - const rules: Array<{ permission?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] + const rules: Array<{ pattern?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] + // Rules apply last-match-wins: the agent is read-only when the last catch-all rule denies and + // nothing after it allows or asks (an agent's own deny can override a user's earlier "ask"). + let lastCatchAllDeny = -1 + rules.forEach((rule, index) => { + if (rule.pattern === "*" && rule.action === "deny") lastCatchAllDeny = index + }) throw new Error( deniedWriteMessage({ sql, @@ -302,8 +308,7 @@ export const SqlExecuteTool = Tool.define( mongo: mongo !== null, scratch: isScratch(args.warehouse), warehouseGiven: !!args.warehouse, - // Read-only unless a rule of its own allows or asks for some writes (a pattern deny). - readOnly: !rules.some((rule) => rule.permission !== "*" && rule.action !== "deny"), + readOnly: !rules.slice(lastCatchAllDeny + 1).some((rule) => rule.action !== "deny"), }), ) } diff --git a/packages/opencode/src/altimate/tools/sql-materialize.ts b/packages/opencode/src/altimate/tools/sql-materialize.ts index c59158aeaf..d405e11abb 100644 --- a/packages/opencode/src/altimate/tools/sql-materialize.ts +++ b/packages/opencode/src/altimate/tools/sql-materialize.ts @@ -215,7 +215,7 @@ function assertReadOnlySource(warehouse: string, sql: string): { mongo: boolean; const { queryType, blocked } = classifyAndCheck(sql, Registry.canonicalType(type) ?? undefined) try { if (blocked || queryType !== "read") throw new Error("Not a read") - return { mongo: false, sql: readSql(sql, Registry.canonicalType(type) ?? undefined) } + return { mongo: false, sql: readSql(sql, Registry.canonicalType(type) ?? undefined, { explain: false }) } } catch { throw new MaterializeError( "sql_materialize only reads from the source warehouse: use a single read-only SELECT (or WITH ... SELECT), " + diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index c53ec6cf0e..b55fb710a0 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -139,6 +139,7 @@ describe("explainWrite", () => { "SELECT len(DISTINCT customer_secret_name(a)) FROM t", "SELECT customer_secret_name customer_x customer_y FROM t", "SELECT a FROM customer_secret_table WHERE (((", + "SELECT CAST(a AS int 'customer_it''s secret') FROM t", ]) { const message = explainWrite(sql, "sqlite").reason expect(message).toContain("could not read") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 237c1d16ea..80442d0102 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -217,6 +217,20 @@ describe("denied write message branches", () => { expect(message).toContain("rules allow") }) + test("an agent deny after a user's ask is still read-only", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [ + { permission: "*", pattern: "*", action: "allow" }, + { permission: "sql_execute_write", pattern: "*", action: "deny" }, + { permission: "sql_execute_write", pattern: "*", action: "ask" }, + { permission: "sql_execute_write", pattern: "*", action: "deny" }, + ] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + await expect( + tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("may only read") + }) + test("sql_execute reads the denial's rules to choose the wording", async () => { const tool = await initTool(SqlExecuteTool) const ruleset = [ From 9e8b968a649ce0ecd18a4496c2ffa1aa006ea9b7 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 09:27:58 -0800 Subject: [PATCH 12/58] fix: name SELECT INTO before batch keywords, hint quoted qualifiers, keep rule advice for unreadable SQL Co-Authored-By: Claude Opus 5.5 --- docs/docs/configure/permissions.md | 2 +- .../src/altimate/tools/sql-classify.ts | 9 ++++-- .../src/altimate/tools/sql-execute.ts | 1 + .../tools/sql-readonly-guard-explain.test.ts | 28 ++++++++++++++++++- .../altimate/tools/sql-readonly-guard.test.ts | 1 + 5 files changed, 36 insertions(+), 5 deletions(-) diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index 63284fa424..87a66dacc4 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -255,7 +255,7 @@ When prompted, you have three choices: `sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count; a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. -When an agent's `sql_execute_write` is `"deny"`, the tool error tells the agent why the query counted as a write and what to change: the statement that writes, the parser error and its position, or trailing shell syntax such as `2>/dev/null` to remove. +When an agent's `sql_execute_write` is `"deny"`, the tool error tells the agent why the query counted as a write and what to change: the statement that writes, the parser error and its position, or shell syntax such as `2>/dev/null` to remove. ## Tips diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index bb99d8fd0f..0f788f9522 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -635,6 +635,12 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u if (functionSafety(statement, dialect, 0).write) return writes(`${where} calls a function that can modify data or run other SQL`) // A statement that is itself a write is named by its type, before any batch keyword inside it. if (parsed && parsed.category !== "query") return writes(`${where} is not a read (${type})`) + if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { + return writes( + `${where} contains a write clause (SELECT ... INTO, INSERT/UPDATE/DELETE/MERGE inside a CTE, ` + + 'or a write keyword after a quoted name such as "t".update: quote the column too, "t"."update")', + ) + } const keyword = batchedStatement(masked, dialect) if (keyword) { const engine = /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") @@ -654,9 +660,6 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u return writes(`${where} runs a command through TRANSFORM ... USING`) } if (advancesSequence(tokens, masked, dialect)) return writes(`${where} advances a sequence`) - if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { - return writes(`${where} contains a write clause (SELECT ... INTO, or INSERT/UPDATE/DELETE/MERGE inside a CTE)`) - } if (parsed?.category !== "query") return writes(`${where} is not a read (${type})`) return writes(`${where} could not be proven read-only`) } diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index cc99d0cbbe..798d803d31 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -774,6 +774,7 @@ export function deniedWriteMessage(input: { const { reason, unreadable } = explainWrite(input.sql, dialect) const next = unreadable ? "Fix the query and call sql_execute again; the same text will be refused again." + + (readOnly ? "" : " The configured sql_execute_write rules may still deny it once it parses.") + (input.warehouseGiven || input.dialects.length < 2 ? "" : " No warehouse was given, so the query was read in every dialect it could reach; pass warehouse to read it in that warehouse's dialect only.") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index b55fb710a0..c654cb1339 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -39,7 +39,8 @@ describe("shellResidue", () => { shellResidue(`SELECT * FROM t ${"| head ".repeat(60)}x;y`, "postgres") shellResidue(`SELECT * FROM t ${"| head ".repeat(44)};y`, "postgres") explainWrite(`SELECT * FROM t ${"| head ".repeat(60)}x;y`, "postgres") - expect(performance.now() - start).toBeLessThan(1000) + // A backtracking blowup takes many seconds; parser calls alone stay far below this on a busy runner. + expect(performance.now() - start).toBeLessThan(5000) }) test("a comparison before the residue is kept", () => { @@ -147,6 +148,31 @@ describe("explainWrite", () => { } }) + test("a SELECT INTO on SQL Server is named as a write clause, not a keyword to quote", () => { + for (const dialect of ["sqlserver", undefined]) { + expect(explainWrite("SELECT * INTO c FROM t", dialect).reason).toContain("write clause") + } + }) + + test("a quoted qualifier gets a specific hint", () => { + expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).toContain('"t"."update"') + }) + + test("every write in the guard corpus gets a specific reason", () => { + const writes = [ + "INSERT INTO t VALUES (1)", "UPDATE t SET a = 1", "DELETE FROM t", "MERGE INTO t USING s ON t.id = s.id WHEN MATCHED THEN DELETE", + "CREATE TABLE t (a INT)", "DROP TABLE t", "ALTER TABLE t ADD COLUMN c INT", "COPY INTO t FROM @s", "SELECT 1; DELETE FROM t", + "WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x", "SELECT * INTO c FROM t", "SELECT 1. INTO c FROM t", + "SELECT nextval('s')", "SELECT exec FROM t", + ] + for (const dialect of ["postgres", "snowflake", "duckdb", "sqlserver", "bigquery", undefined]) { + for (const sql of writes) { + if (classifyAndCheck(sql, dialect).queryType !== "write") continue + expect({ dialect, sql, reason: explainWrite(sql, dialect).reason }).not.toMatchObject({ reason: expect.stringContaining("could not be proven") }) + } + } + }) + test("names a SQL Server batch keyword", () => { expect(explainWrite("SELECT exec FROM t", "sqlserver").reason).toContain("statement keyword EXEC") }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 80442d0102..b90b2c4c10 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -247,5 +247,6 @@ describe("denied write message branches", () => { const message = deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((", dialects: ["postgres", "snowflake"], warehouseGiven: false }) expect(message).toContain("pass warehouse") expect(deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((" })).not.toContain("pass warehouse") + expect(deniedWriteMessage({ ...base, sql: "DELETE FROM t WHERE ((", readOnly: false })).toContain("may still deny it") }) }) From 01e219c9ec1e3cc372a4384fa18603e6b7a8732a Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 09:46:12 -0800 Subject: [PATCH 13/58] fix: query_from refusals carry the reason once; parser positions are stated relative to the statement Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/sql-classify.ts | 3 ++- packages/opencode/src/altimate/tools/sql-execute.ts | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 0f788f9522..1c3908b7ae 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -618,7 +618,8 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u if (result.parseError) { return unreadable( `the ${dialect ?? "generic"} SQL parser could not read ${where} (${parserMessage(result.parseError)}), so it cannot be proven read-only. ` + - 'Fix the syntax at that position: quote identifiers that contain spaces or are keywords ("order date"), ' + + "The position counts from the start of that statement with comments removed. " + + 'Fix the syntax there: quote identifiers that contain spaces or are keywords ("order date"), ' + "check the clause order, and replace any placeholder text such as ..." ) } diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 798d803d31..8ec9f5eb52 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -44,6 +44,7 @@ import * as Precedence from "../workspace/precedence" import { normalizeError } from "./response-normalization" // altimate_change end import { readSql } from "./sql-check" +import { writeReason } from "./read-only-sql" import { MaterializeError, storeRows } from "./sql-materialize" import { firstTime } from "./session-hints" @@ -70,10 +71,11 @@ const STEP_REF = /\{\{([A-Za-z_]\w*)(?:\.([A-Za-z_]\w*))?\}\}/g const MAX_BOUND_ROWS = 1000 function generatedRead(sql: string, warehouse: string, stage: "source" | "result"): string { + const dialect = Registry.canonicalType(Registry.getConfig(warehouse)?.type) ?? undefined try { - return readSql(sql, Registry.canonicalType(Registry.getConfig(warehouse)?.type) ?? undefined) + return readSql(sql, dialect, { explain: false }) } catch { - throw new Error(`query_from ${stage} must be a single read-only SELECT (or WITH ... SELECT).`) + throw new Error(`query_from ${stage} must be a single read-only SELECT (or WITH ... SELECT).${writeReason(sql, dialect)}`) } } From 548ab8012c02eddd0736079e96a72a07de542b6a Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 09:59:51 -0800 Subject: [PATCH 14/58] fix: name the word a stricter sql_check list refuses; tidy parser details and position wording Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/read-only-sql.ts | 24 ++++++++++++++----- .../src/altimate/tools/sql-classify.ts | 6 +++-- .../tools/sql-readonly-guard-explain.test.ts | 8 +++++++ .../altimate/tools/sql-readonly-guard.test.ts | 4 ++-- 4 files changed, 32 insertions(+), 10 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 572ed19020..d40ee0b085 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -42,6 +42,12 @@ export function requireReadOnlyQuery(sql: string, dialect?: string): void { throw new Error("Only a single read-only query is accepted here; it never writes data.") } +// Statement words refused anywhere in a read handed to sql_check; a column qualified by a whole +// identifier (t.update) is not one, as in the classifier. +const STATEMENT_WORD = + /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|COPY|ATTACH|DETACH|PRAGMA|VACUUM|CALL|DO|INTO|INSTALL|LOAD|EXPORT|IMPORT|GRANT|REVOKE)\b(? { expect(() => readSql("SELECT 1. INTO c FROM orders", "postgres")).toThrow() }) + test("a word only the stricter sql_check list refuses is named", () => { + expect(() => readSql("SELECT x AS load FROM t", "postgres")).toThrow("statement word LOAD") + }) + + test("parser details end without stray punctuation", () => { + expect(explainWrite("SELECT a FROM WHERE (((", "postgres").reason).not.toMatch(/,\)/) + }) + test("the result lint path can skip the explanation", () => { expect(() => readSql("SELECT 1; DELETE FROM t", "postgres", { explain: false })).toThrow( /^This operation only accepts a single read-only SELECT \(or WITH \.\.\. SELECT\); it never writes or fixes data\.$/, diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index b90b2c4c10..5d43c39596 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -172,10 +172,10 @@ describe("sql_execute on a read-only agent", () => { test("a denial that fails an Effect, as the tool bridge runs it, is explained", async () => { const tool = await initTool(SqlExecuteTool) - // The production context runs ctx.ask through Effect.runPromise (EffectBridge.promise). + // Production runs permission.ask(...).pipe(Effect.orDie) through Effect.runPromise (EffectBridge.promise). const ctx = { ...deniedCtx([]), - ask: () => Effect.runPromise(Effect.fail(new PermissionV1.DeniedError({ ruleset: [] }))), + ask: () => Effect.runPromise(Effect.fail(new PermissionV1.DeniedError({ ruleset: [] })).pipe(Effect.orDie)), } await expect( tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), From e1af0c992bf64894ab4b419951fd9dc430b3a02a Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 10:07:16 -0800 Subject: [PATCH 15/58] fix: pattern-only denies are not read-only; name SQL Server batches and UNKNOWN statements; test query_from reasons Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/sql-classify.ts | 16 +++++++++++++++- .../opencode/src/altimate/tools/sql-execute.ts | 3 ++- .../tools/sql-execute-query-from.test.ts | 10 ++++++++++ .../tools/sql-readonly-guard-explain.test.ts | 12 +++++++++++- .../altimate/tools/sql-readonly-guard.test.ts | 18 +++++++++++++++--- 5 files changed, 53 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 5206bf573d..ee6abd75dc 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -617,6 +617,15 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u // Statements are not quoted back, since telemetry records this error; the parser's own message // quotes at most a token, which telemetry masks as a literal. const where = statements.length > 1 ? `statement ${index + 1} of ${statements.length}` : "it" + // Where statements need no separator, a statement keyword is the real reason, even if it breaks the parse. + const batchKeyword = batchedStatement(maskSql(tokenizeSql(statement, dialect).tokens), dialect) + if (result.parseError && batchKeyword) { + return writes( + `${where} holds the statement keyword ${batchKeyword.trim().split(/\s+/)[0].toUpperCase()} outside a literal or comment; ` + + `${/^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") ? "SQL Server runs a statement there even without a separator" : "this dialect is not modeled, so it may run as a statement"}` + + "; run each statement in its own call, or quote it if it is a column name", + ) + } if (result.parseError) { return unreadable( `the ${dialect ?? "generic"} SQL parser could not read ${where} (${parserMessage(result.parseError)}), so it cannot be proven read-only. ` + @@ -632,7 +641,12 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u } catch { parsed = undefined } - const type = String(parsed?.statement_type ?? "statement").toUpperCase() + const reported = String(parsed?.statement_type ?? "").toUpperCase() + // An UNKNOWN type is named by the statement's first keyword instead. + const type = + reported && reported !== "UNKNOWN" + ? reported + : (/^\s*([A-Za-z_]+)/.exec(maskSql(tokenizeSql(statement, dialect).tokens))?.[1] ?? "statement").toUpperCase() const tokens = tokenizeSql(statement, dialect).tokens const masked = maskSql(tokens) if (functionSafety(statement, dialect, 0).write) return writes(`${where} calls a function that can modify data or run other SQL`) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 8ec9f5eb52..4380a23fd0 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -310,7 +310,8 @@ export const SqlExecuteTool = Tool.define( mongo: mongo !== null, scratch: isScratch(args.warehouse), warehouseGiven: !!args.warehouse, - readOnly: !rules.slice(lastCatchAllDeny + 1).some((rule) => rule.action !== "deny"), + // With no catch-all deny, writes the rules do not name fall to the default ("ask"). + readOnly: lastCatchAllDeny >= 0 && !rules.slice(lastCatchAllDeny + 1).some((rule) => rule.action !== "deny"), }), ) } diff --git a/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts b/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts index 3adc47d5c8..71173ada88 100644 --- a/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts +++ b/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts @@ -205,6 +205,16 @@ describe("sql_execute generated reads", () => { }) } + test("a refused source says once which statement writes", async () => { + const tool = await initTool(SqlExecuteTool) + const error = await tool + .execute({ query_from: { ...source, sql: "SELECT 1; DELETE FROM orders" }, warehouse: "analytics" }, ctx) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("query_from source must be a single read-only SELECT") + expect(error.split("statement 2 of 2 is not a read (DELETE)").length).toBe(2) + expect(dispatch).not.toHaveBeenCalled() + }) + for (const sql of [ "DELETE FROM orders", "CREATE TEMP TABLE generated AS SELECT 1", diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index eeb45f85c1..5825e1d152 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -140,7 +140,7 @@ describe("explainWrite", () => { }) test("parser messages keep no token text", () => { - const reason = explainWrite("SELECT set FROM t", "sqlserver").reason + const reason = explainWrite("SELECT set FROM t", "postgres").reason expect(reason).toContain("line 1, column") expect(reason).not.toContain("Set") expect(reason).not.toContain("a token") @@ -181,6 +181,16 @@ describe("explainWrite", () => { } }) + test("a SQL Server batch without a separator is named as such, not as a syntax error", () => { + const reason = explainWrite("SELECT a FROM t\nUPDATE t SET a = 1", "sqlserver").reason + expect(reason).toContain("statement keyword UPDATE") + expect(reason).not.toContain("could not read") + }) + + test("an UNKNOWN statement type is named by its first keyword", () => { + expect(explainWrite("ATTACH 'x.db' AS other", "duckdb").reason).not.toContain("UNKNOWN") + }) + test("names a SQL Server batch keyword", () => { expect(explainWrite("SELECT exec FROM t", "sqlserver").reason).toContain("statement keyword EXEC") }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 5d43c39596..79bd6c4897 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -14,6 +14,9 @@ import { initTool } from "../tool-fixture" const DIALECTS = ["postgres", "snowflake", "bigquery", "duckdb", "sqlite", "mysql", "databricks", "redshift", "sqlserver", "oracle", "clickhouse"] +// What a read-only agent's denial carries: its catch-all write deny. +const READ_ONLY_RULES = [{ permission: "sql_execute_write", pattern: "*", action: "deny" }] + const isRead = (sql: string, dialect: string) => { const result = classifyAndCheck(sql, dialect) return result.queryType === "read" && !result.blocked @@ -29,7 +32,7 @@ const deniedCtx = (asked: unknown[]) => ({ metadata: () => {}, ask: async (request: any) => { asked.push(request) - if (request.permission === "sql_execute_write") throw new PermissionV1.DeniedError({ ruleset: [] }) + if (request.permission === "sql_execute_write") throw new PermissionV1.DeniedError({ ruleset: READ_ONLY_RULES }) }, }) @@ -175,7 +178,7 @@ describe("sql_execute on a read-only agent", () => { // Production runs permission.ask(...).pipe(Effect.orDie) through Effect.runPromise (EffectBridge.promise). const ctx = { ...deniedCtx([]), - ask: () => Effect.runPromise(Effect.fail(new PermissionV1.DeniedError({ ruleset: [] })).pipe(Effect.orDie)), + ask: () => Effect.runPromise(Effect.fail(new PermissionV1.DeniedError({ ruleset: READ_ONLY_RULES })).pipe(Effect.orDie)), } await expect( tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), @@ -184,7 +187,7 @@ describe("sql_execute on a read-only agent", () => { test("a denial from the subagent permission path is explained too", async () => { const tool = await initTool(SqlExecuteTool) - const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionNext.DeniedError([])) } + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionNext.DeniedError(READ_ONLY_RULES as any)) } await expect( tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), ).rejects.toThrow("it is not a read (DELETE)") @@ -231,6 +234,15 @@ describe("denied write message branches", () => { ).rejects.toThrow("may only read") }) + test("a pattern-only deny leaves other writes to the default ask, so it is not read-only", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [{ permission: "sql_execute_write", pattern: "DROP*", action: "deny" }] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + await expect( + tool.execute({ query: "DROP TABLE stg_tmp", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("A sql_execute_write rule denies it") + }) + test("sql_execute reads the denial's rules to choose the wording", async () => { const tool = await initTool(SqlExecuteTool) const ruleset = [ From 28e880b0224ebb79a7e1c12028cfd7c0a69aee5e Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 10:15:45 -0800 Subject: [PATCH 16/58] fix: one reason helper names a stricter-list word only when it is the sole reason, for every caller Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/read-only-sql.ts | 23 +++++++++---------- .../tools/sql-readonly-guard-explain.test.ts | 3 +++ .../altimate/tools/sql-readonly-guard.test.ts | 12 ++++++++++ 3 files changed, 26 insertions(+), 12 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index d40ee0b085..f41f17b151 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -61,25 +61,24 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool STATEMENT_WORD.test(body) || REPLACE_WORD.test(body) ) { - let reason = "" - if (options.explain !== false) { - reason = writeReason(sql, dialect) - // The classifier reads it as a read; only this stricter word list refused it. Name the word only. - const word = checked === undefined ? undefined : (STATEMENT_WORD.exec(body) ?? REPLACE_WORD.exec(body))?.[0] - if (!reason && word) { - reason = ` It contains the statement word ${word.toUpperCase()} outside a literal or comment; quote it if it is a column name.` - } - } throw new Error( - "This operation only accepts a single read-only SELECT (or WITH ... SELECT); it never writes or fixes data." + reason, + "This operation only accepts a single read-only SELECT (or WITH ... SELECT); it never writes or fixes data." + + (options.explain === false ? "" : writeReason(sql, dialect)), ) } const semicolon = checked.masked.indexOf(";") return semicolon < 0 ? sql : sql.slice(0, semicolon) + sql.slice(semicolon + 1) } -/** Why the classifier reads sql as a write, as a sentence to append to a refusal; empty for a read. */ +/** Why sql is refused as a read, as a sentence to append to a refusal: the classifier's reason for a write, + * or, for a read that only the stricter statement-word list refuses, that word (no SQL text). Empty otherwise. */ export function writeReason(sql: string, dialect?: string): string { const { queryType, blocked } = classifyAndCheck(sql, dialect) - return queryType === "write" && !blocked ? ` It counts as a write because ${explainWrite(sql, dialect).reason}.` : "" + if (blocked) return "" + if (queryType === "write") return ` It counts as a write because ${explainWrite(sql, dialect).reason}.` + // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. + const body = readOnlyBody(sql, dialect)?.body + if (!body || !/^(SELECT|WITH)\b/i.test(body)) return "" + const word = (STATEMENT_WORD.exec(body) ?? REPLACE_WORD.exec(body))?.[0] + return word ? ` It contains the statement word ${word.toUpperCase()} outside a literal or comment; quote it if it is a column name.` : "" } diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 5825e1d152..cb5b4c8994 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -85,6 +85,9 @@ describe("other read-only refusals carry the reason", () => { test("a word only the stricter sql_check list refuses is named", () => { expect(() => readSql("SELECT x AS load FROM t", "postgres")).toThrow("statement word LOAD") + // Not named when something else also refuses it (the leading parenthesis). + expect(() => readSql("(SELECT x AS load FROM t)", "postgres")).not.toThrow("statement word") + expect(writeReason("SELECT x AS load FROM t", "postgres")).toContain("statement word LOAD") }) test("parser details end without stray punctuation", () => { diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 79bd6c4897..e7161872da 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -234,6 +234,18 @@ describe("denied write message branches", () => { ).rejects.toThrow("may only read") }) + test("a catch-all deny followed by an allow is a rule, not read-only", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [ + { permission: "sql_execute_write", pattern: "*", action: "deny" }, + { permission: "sql_execute_write", pattern: "INSERT INTO audit*", action: "allow" }, + ] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + await expect( + tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("A sql_execute_write rule denies it") + }) + test("a pattern-only deny leaves other writes to the default ask, so it is not read-only", async () => { const tool = await initTool(SqlExecuteTool) const ruleset = [{ permission: "sql_execute_write", pattern: "DROP*", action: "deny" }] From 65f502c664343fc92c37908d077e0dfb81046386 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 10:24:00 -0800 Subject: [PATCH 17/58] fix: keep ClickHouse dotted keywords strict; name only known keywords for unknown statements Co-Authored-By: Claude Opus 5.5 --- docs/docs/configure/permissions.md | 2 +- .../opencode/src/altimate/tools/sql-classify.ts | 17 +++++++++++++++-- .../tools/sql-readonly-guard-explain.test.ts | 2 ++ .../altimate/tools/sql-readonly-guard.test.ts | 11 ++++++++++- 4 files changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index 87a66dacc4..aa5fe6b9d9 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -253,7 +253,7 @@ When prompted, you have three choices: ### How SQL is classified for `sql_execute_write` -`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count; a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. +`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count (dotted names still count on ClickHouse); a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. When an agent's `sql_execute_write` is `"deny"`, the tool error tells the agent why the query counted as a write and what to change: the statement that writes, the parser error and its position, or shell syntax such as `2>/dev/null` to remove. diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index ee6abd75dc..fe248b07b5 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -92,6 +92,8 @@ function hasQueryWriteClause(sql: string, dialect?: string): boolean { // must be a whole unquoted identifier directly before the dot: `1. INTO t` and `0x1.INTO t` are a // number followed by SELECT INTO, and anything else stays a write. The lookbehind runs only where a // keyword matched, so long masked literals are not rescanned at every position. + // The bundled ClickHouse parser accepts trailing text it cannot read, so there every keyword counts. + if (dialect?.toLowerCase() === "clickhouse") return /\b(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i.test(masked) return /\b(INTO|INSERT|UPDATE|DELETE|MERGE)\b(? { test("an UNKNOWN statement type is named by its first keyword", () => { expect(explainWrite("ATTACH 'x.db' AS other", "duckdb").reason).not.toContain("UNKNOWN") + // Only known keywords are named; any other first word is the user's text. + expect(explainWrite("acme_secret SELECT 1", "clickhouse").reason).not.toMatch(/ACME_SECRET/i) }) test("names a SQL Server batch keyword", () => { diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index e7161872da..48bbf49452 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -68,12 +68,21 @@ describe("reads are classified as reads in every dialect", () => { "parenthesized query": "(SELECT 1) UNION ALL (SELECT 2)", "two reads": "SELECT 1; SELECT 2", } + // The bundled ClickHouse parser accepts trailing text, so its keyword scan stays strict for dotted names. + const STRICT_DOTTED = new Set(["qualified columns named like write keywords", "three-part names ending in a write keyword"]) for (const [name, sql] of Object.entries(reads)) { test(name, () => { - expect(DIALECTS.filter((dialect) => !isRead(sql, dialect))).toEqual([]) + const dialects = STRICT_DOTTED.has(name) ? DIALECTS.filter((d) => d !== "clickhouse") : DIALECTS + expect(dialects.filter((dialect) => !isRead(sql, dialect))).toEqual([]) }) } + test("ClickHouse keeps dotted write keywords as writes, since its parser accepts trailing text", () => { + for (const sql of ["SELECT * FROM a.INTO OUTFILE '/tmp/x'", "SELECT a FROM t x.UPDATE t SET a = 1"]) { + expect(isRead(sql, "clickhouse")).toBe(false) + } + }) + test("DESCRIBE, SHOW and PRAGMA metadata reads", () => { for (const sql of ["DESCRIBE orders", "SHOW TABLES", "SHOW COLUMNS FROM orders"]) expect(isRead(sql, "duckdb")).toBe(true) expect(isRead("PRAGMA table_info('orders')", "sqlite")).toBe(true) From bf8dc496159593efef464908db83dd32bec241f9 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 10:32:10 -0800 Subject: [PATCH 18/58] fix: trim the residue tail in linear time; report a missing SQL classifier as such A `$`-anchored trim regex was quadratic on long masked literals (80k chars took about 4 s on the refusal path). Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/sql-classify.ts | 15 ++++++++++++--- .../tools/sql-readonly-guard-explain.test.ts | 9 +++++++++ 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index fe248b07b5..ee67f8aa5b 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -537,8 +537,8 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // (`2>/dev/null`, `2>&1`) can sit anywhere, even before LIMIT. At the very end there may also be one pipe // into a shell command (`| head -20`) or one redirect into a file (`> out.csv`). A file target must start // like a path (/, ./, ../, ~/) or end in a known output extension, so comparisons such as `x > 2`, -// `x > 1.5` and `x > t.total` never match. Every pattern is anchored with no nested repetition, so a -// crafted tail cannot make the scan backtrack. +// `x > 1.5` and `x > t.total` never match. The tail patterns run on at most 400 characters and have no +// nested repetition. const SHELL_REDIRECT = /\s(?:[12]|&)?>>?[ \t]*(?:&[12]|\/dev\/null)(?![\w/])/g const SHELL_PIPE_TAIL = /\|[ \t]*(head|tail|grep|egrep|less|more|cat|wc|sort|uniq|cut|column|jq|tee|awk|sed)\b[^|;\n]*$/i const SHELL_FILE_TAIL = @@ -559,7 +559,10 @@ export function shellResidue(sql: string, dialect?: string): string | undefined cuts.push({ start: match.index!, end: match.index! + match[0].length, label: match[0].replace(/\s+/g, "") }) } // Only the last 400 characters can hold a tail; strip trailing ; and whitespace first. - const end = masked.replace(/[\s;]+$/, "").length + // A backward loop, not a `$`-anchored regex: masked literals can be long runs of spaces, and a regex + // would retry the end-of-text match from every position in them. + let end = masked.length + while (end > 0 && /[\s;]/.test(masked[end - 1])) end-- const offset = Math.max(0, end - 400) const window = masked.slice(offset, end) const pipe = SHELL_PIPE_TAIL.exec(window) @@ -628,6 +631,12 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u const where = statements.length > 1 ? `statement ${index + 1} of ${statements.length}` : "it" // Where statements need no separator, a statement keyword is the real reason, even if it breaks the parse. const batchKeyword = batchedStatement(maskSql(tokenizeSql(statement, dialect).tokens), dialect) + // The classifier itself could not run: no rewrite of the SQL can help. + if (result.parseError === "SQL parser is unavailable" || result.parseError === "SQL parser returned an invalid statement list") { + return writes( + "the SQL classifier is unavailable in this installation, so no query can be proven read-only; changing the SQL will not help", + ) + } if (result.parseError && batchKeyword) { return writes( `${where} holds the statement keyword ${batchKeyword.trim().split(/\s+/)[0].toUpperCase()} outside a literal or comment; ` + diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 3653994630..4ebaaba5c0 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -34,6 +34,15 @@ describe("shellResidue", () => { expect(shellResidue("SELECT * FROM t | grep -i private | head", "postgres")).toBeUndefined() }) + test("a long literal before a syntax error is explained in linear time", () => { + const sql = `SELECT '${"x".repeat(200_000)}' FROM WHERE` + const start = performance.now() + explainWrite(sql, "postgres") + shellResidue(sql, "postgres") + // Quadratic trimming took about 4 s at 80k characters; linear work stays far below this. + expect(performance.now() - start).toBeLessThan(3000) + }) + test("a crafted tail is scanned in linear time", () => { const start = performance.now() shellResidue(`SELECT * FROM t ${"| head ".repeat(60)}x;y`, "postgres") From 67f519e10031ae4001a636e743e65ed42179249b Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 10:39:36 -0800 Subject: [PATCH 19/58] fix: keep readSql strict for dotted statement words on ClickHouse, matching the classifier Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/read-only-sql.ts | 14 +++++++++++--- .../opencode/src/altimate/tools/sql-classify.ts | 7 +++++-- .../test/altimate/tools/sql-readonly-guard.test.ts | 7 +++++++ 3 files changed, 23 insertions(+), 5 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index f41f17b151..96085b31e8 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -47,6 +47,14 @@ export function requireReadOnlyQuery(sql: string, dialect?: string): void { const STATEMENT_WORD = /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|COPY|ATTACH|DETACH|PRAGMA|VACUUM|CALL|DO|INTO|INSTALL|LOAD|EXPORT|IMPORT|GRANT|REVOKE)\b(? pattern.test(body)) ) { throw new Error( "This operation only accepts a single read-only SELECT (or WITH ... SELECT); it never writes or fixes data." + @@ -79,6 +86,7 @@ export function writeReason(sql: string, dialect?: string): string { // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. const body = readOnlyBody(sql, dialect)?.body if (!body || !/^(SELECT|WITH)\b/i.test(body)) return "" - const word = (STATEMENT_WORD.exec(body) ?? REPLACE_WORD.exec(body))?.[0] + const [statement, replace] = wordPatterns(dialect) + const word = (statement.exec(body) ?? replace.exec(body))?.[0] return word ? ` It contains the statement word ${word.toUpperCase()} outside a literal or comment; quote it if it is a column name.` : "" } diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index ee67f8aa5b..18ed47fce5 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -676,8 +676,11 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u if (parsed && parsed.category !== "query") return writes(`${where} is not a read (${type})`) if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { return writes( - `${where} contains a write clause (SELECT ... INTO, INSERT/UPDATE/DELETE/MERGE inside a CTE, ` + - 'or a write keyword after a quoted name such as "t".update: quote the column too, "t"."update")', + dialect?.toLowerCase() === "clickhouse" + ? `${where} contains a write clause (SELECT ... INTO or a modifying CTE), or a write keyword that on ClickHouse ` + + 'counts even after a dot: quote the column, t."update"' + : `${where} contains a write clause (SELECT ... INTO, INSERT/UPDATE/DELETE/MERGE inside a CTE, ` + + 'or a write keyword after a quoted name such as "t".update: quote the column too, "t"."update")', ) } const keyword = batchedStatement(masked, dialect) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 48bbf49452..050e3f6895 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -5,6 +5,7 @@ import { PermissionNext } from "../../../src/permission/next" import { SessionID, MessageID } from "../../../src/session/schema" import { SqlExecuteTool, deniedWriteMessage } from "../../../src/altimate/tools/sql-execute" import { classifyAndCheck, isScratchSafeWrite } from "../../../src/altimate/tools/sql-classify" +import { readSql } from "../../../src/altimate/tools/read-only-sql" import * as Registry from "../../../src/altimate/native/connections/registry" import { closeScratch } from "../../../src/altimate/native/connections/scratch" import { initTool } from "../tool-fixture" @@ -77,6 +78,12 @@ describe("reads are classified as reads in every dialect", () => { }) } + test("readSql on ClickHouse refuses dotted statement words too", () => { + expect(() => readSql("SELECT * FROM t AS x.DROP TABLE y", "clickhouse")).toThrow() + expect(() => readSql("SELECT t.alter FROM t", "clickhouse")).toThrow() + expect(readSql("SELECT t.alter FROM t", "postgres")).toBe("SELECT t.alter FROM t") + }) + test("ClickHouse keeps dotted write keywords as writes, since its parser accepts trailing text", () => { for (const sql of ["SELECT * FROM a.INTO OUTFILE '/tmp/x'", "SELECT a FROM t x.UPDATE t SET a = 1"]) { expect(isRead(sql, "clickhouse")).toBe(false) From d1b725a6c358c24019ab4849948f4813dbc9ae34 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 10:57:45 -0800 Subject: [PATCH 20/58] test: the write corpus asserts write classification and a specific reason; docs scope the denial message Co-Authored-By: Claude Opus 5.5 --- docs/docs/configure/permissions.md | 4 ++-- .../tools/sql-readonly-guard-explain.test.ts | 22 ++++++++++++------- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index aa5fe6b9d9..3a6b281262 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -253,9 +253,9 @@ When prompted, you have three choices: ### How SQL is classified for `sql_execute_write` -`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count (dotted names still count on ClickHouse); a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. +`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count (dotted names still count on ClickHouse); a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. On a dbt target, any Jinja (`{{ }}`, `{% %}`, `{# #}`) counts as a write too, even inside a comment or literal, because dbt renders and runs it first. -When an agent's `sql_execute_write` is `"deny"`, the tool error tells the agent why the query counted as a write and what to change: the statement that writes, the parser error and its position, or shell syntax such as `2>/dev/null` to remove. +When a query reaches the `sql_execute_write` check and a `"deny"` rule refuses it, the tool error tells the agent why the query counted as a write and what to change (hard-blocked statements such as `DROP DATABASE`, and writes inside a batch, fail earlier with their own messages): the statement that writes, the parser error and its position, or shell syntax such as `2>/dev/null` to remove. ## Tips diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 4ebaaba5c0..056b7a221d 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -178,18 +178,24 @@ describe("explainWrite", () => { expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).toContain('"t"."update"') }) - test("every write in the guard corpus gets a specific reason", () => { - const writes = [ + test("every write in the guard corpus is a write with a specific reason", () => { + const everywhere = [ "INSERT INTO t VALUES (1)", "UPDATE t SET a = 1", "DELETE FROM t", "MERGE INTO t USING s ON t.id = s.id WHEN MATCHED THEN DELETE", "CREATE TABLE t (a INT)", "DROP TABLE t", "ALTER TABLE t ADD COLUMN c INT", "COPY INTO t FROM @s", "SELECT 1; DELETE FROM t", "WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x", "SELECT * INTO c FROM t", "SELECT 1. INTO c FROM t", - "SELECT nextval('s')", "SELECT exec FROM t", ] - for (const dialect of ["postgres", "snowflake", "duckdb", "sqlserver", "bigquery", undefined]) { - for (const sql of writes) { - if (classifyAndCheck(sql, dialect).queryType !== "write") continue - expect({ dialect, sql, reason: explainWrite(sql, dialect).reason }).not.toMatchObject({ reason: expect.stringContaining("could not be proven") }) - } + const cases: Array<[string, string | undefined]> = [ + ...["postgres", "snowflake", "duckdb", "sqlserver", "bigquery", undefined].flatMap((d) => everywhere.map((sql) => [sql, d] as [string, string | undefined])), + ["SELECT exec FROM t", "sqlserver"], + ["SELECT nextval('s')", "postgres"], + ["SELECT NEXT VALUE FOR s", "sqlserver"], + ] + for (const [sql, dialect] of cases) { + expect({ dialect, sql, type: classifyAndCheck(sql, dialect).queryType }).toEqual({ dialect, sql, type: "write" }) + const reason = explainWrite(sql, dialect).reason + // Every corpus write parses, so a parser-failure reason would be generic too. + const specific = reason.length > 10 && !reason.includes("could not be proven") && !reason.includes("could not read") + expect({ dialect, sql, specific }).toEqual({ dialect, sql, specific: true }) } }) From ef53fc98985f2bef1aa4e585ecf27df82041c59c Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 11:13:29 -0800 Subject: [PATCH 21/58] fix: own next step for an unavailable classifier; one keyword source; timing tests compare growth Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/read-only-sql.ts | 16 +++++----- .../src/altimate/tools/sql-classify.ts | 13 ++++++--- .../src/altimate/tools/sql-execute.ts | 6 ++-- .../tools/sql-readonly-guard-explain.test.ts | 29 +++++++++++-------- 4 files changed, 38 insertions(+), 26 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 96085b31e8..1d9eb9d0a8 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -42,14 +42,14 @@ export function requireReadOnlyQuery(sql: string, dialect?: string): void { throw new Error("Only a single read-only query is accepted here; it never writes data.") } -// Statement words refused anywhere in a read handed to sql_check; a column qualified by a whole -// identifier (t.update) is not one, as in the classifier. -const STATEMENT_WORD = - /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|COPY|ATTACH|DETACH|PRAGMA|VACUUM|CALL|DO|INTO|INSTALL|LOAD|EXPORT|IMPORT|GRANT|REVOKE)\b(? ({ reason, unreadable: true }) const writes = (reason: string) => ({ reason, unreadable: false }) const residue = shellResidue(sql, dialect) @@ -633,9 +636,11 @@ export function explainWrite(sql: string, dialect?: string): { reason: string; u const batchKeyword = batchedStatement(maskSql(tokenizeSql(statement, dialect).tokens), dialect) // The classifier itself could not run: no rewrite of the SQL can help. if (result.parseError === "SQL parser is unavailable" || result.parseError === "SQL parser returned an invalid statement list") { - return writes( - "the SQL classifier is unavailable in this installation, so no query can be proven read-only; changing the SQL will not help", - ) + return { + reason: "the SQL classifier is unavailable in this installation, so no query can be proven read-only", + unreadable: false, + unavailable: true, + } } if (result.parseError && batchKeyword) { return writes( diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 4380a23fd0..6eeedb57fa 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -774,8 +774,10 @@ export function deniedWriteMessage(input: { return `${head} it is a MongoDB write (a write command, or an aggregate with a $out or $merge stage). Use a read command (find, aggregate, countDocuments, distinct) instead.` } const dialect = input.dialects.find((d) => classifyAndCheck(input.sql, d).queryType === "write") - const { reason, unreadable } = explainWrite(input.sql, dialect) - const next = unreadable + const { reason, unreadable, unavailable } = explainWrite(input.sql, dialect) + const next = unavailable + ? "Changing the SQL will not help; ask the user to check the installation." + : unreadable ? "Fix the query and call sql_execute again; the same text will be refused again." + (readOnly ? "" : " The configured sql_execute_write rules may still deny it once it parses.") + (input.warehouseGiven || input.dialects.length < 2 diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 056b7a221d..43927f6a8b 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -34,22 +34,27 @@ describe("shellResidue", () => { expect(shellResidue("SELECT * FROM t | grep -i private | head", "postgres")).toBeUndefined() }) + // Timing compares two sizes on the same host instead of a wall-clock bound: linear work grows about 8x + // from 1x to 8x input, quadratic about 64x. + const growth = (build: (n: number) => string, n: number) => { + const time = (sql: string) => { + const start = performance.now() + explainWrite(sql, "postgres") + shellResidue(sql, "postgres") + return performance.now() - start + } + time(build(n)) // warm up + return time(build(n * 8)) / Math.max(time(build(n)), 1) + } + test("a long literal before a syntax error is explained in linear time", () => { - const sql = `SELECT '${"x".repeat(200_000)}' FROM WHERE` - const start = performance.now() - explainWrite(sql, "postgres") - shellResidue(sql, "postgres") - // Quadratic trimming took about 4 s at 80k characters; linear work stays far below this. - expect(performance.now() - start).toBeLessThan(3000) + expect(growth((n) => `SELECT '${"x".repeat(n)}' FROM WHERE`, 25_000)).toBeLessThan(30) }) test("a crafted tail is scanned in linear time", () => { - const start = performance.now() - shellResidue(`SELECT * FROM t ${"| head ".repeat(60)}x;y`, "postgres") - shellResidue(`SELECT * FROM t ${"| head ".repeat(44)};y`, "postgres") - explainWrite(`SELECT * FROM t ${"| head ".repeat(60)}x;y`, "postgres") - // A backtracking blowup takes many seconds; parser calls alone stay far below this on a busy runner. - expect(performance.now() - start).toBeLessThan(5000) + // The tail patterns see at most 400 characters, so a longer crafted tail costs no more. + expect(growth((n) => `SELECT * FROM t ${"| head ".repeat(n)}x;y`, 8)).toBeLessThan(30) + expect(growth((n) => `SELECT * FROM t ${"| head ".repeat(n)};y`, 6)).toBeLessThan(30) }) test("a comparison before the residue is kept", () => { From 151e4094e82d3b78b896b818f5ba2dd7b375b7ac Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 11:24:31 -0800 Subject: [PATCH 22/58] fix: refusals from sql_check, query_from and sql_materialize carry the unavailable-classifier next step Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 1d9eb9d0a8..4e4b1587f2 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -82,7 +82,10 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool export function writeReason(sql: string, dialect?: string): string { const { queryType, blocked } = classifyAndCheck(sql, dialect) if (blocked) return "" - if (queryType === "write") return ` It counts as a write because ${explainWrite(sql, dialect).reason}.` + if (queryType === "write") { + const { reason, unavailable } = explainWrite(sql, dialect) + return ` It counts as a write because ${reason}.${unavailable ? " Changing the SQL will not help; ask the user to check the installation." : ""}` + } // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. const body = readOnlyBody(sql, dialect)?.body if (!body || !/^(SELECT|WITH)\b/i.test(body)) return "" From fa40acdbd2216be952bdd35e877dcaca5789b294 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 11:31:34 -0800 Subject: [PATCH 23/58] refactor: one constant for the unavailable-classifier next step Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 4 ++-- packages/opencode/src/altimate/tools/sql-classify.ts | 3 +++ packages/opencode/src/altimate/tools/sql-execute.ts | 3 ++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 4e4b1587f2..67f2eeb740 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -1,4 +1,4 @@ -import { classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" +import { UNAVAILABLE_NEXT_STEP, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" import { maskSql, tokenizeSql } from "./sql-tokenize" import { sqlFunctionCalls } from "./sql-functions" import { hasSideEffectFunction } from "./sql-function-policy" @@ -84,7 +84,7 @@ export function writeReason(sql: string, dialect?: string): string { if (blocked) return "" if (queryType === "write") { const { reason, unavailable } = explainWrite(sql, dialect) - return ` It counts as a write because ${reason}.${unavailable ? " Changing the SQL will not help; ask the user to check the installation." : ""}` + return ` It counts as a write because ${reason}.${unavailable ? ` ${UNAVAILABLE_NEXT_STEP}` : ""}` } // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. const body = readOnlyBody(sql, dialect)?.body diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 3e1cf6b407..ca6ae879d5 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -586,6 +586,9 @@ export function shellResidue(sql: string, dialect?: string): string | undefined return result.queryType === "read" && !result.blocked ? labels.join("`, `") : undefined } +/** What to do when the SQL classifier itself is unavailable: no rewrite of the SQL can help. */ +export const UNAVAILABLE_NEXT_STEP = "Changing the SQL will not help; ask the user to check the installation." + // Statement keywords that may name an UNKNOWN statement in a refusal. const STATEMENT_KEYWORDS = new Set([ "ATTACH", "DETACH", "INSTALL", "LOAD", "SET", "RESET", "PRAGMA", "COPY", "CALL", "EXEC", "EXECUTE", "GRANT", "REVOKE", diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 6eeedb57fa..80181a2dd8 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -15,6 +15,7 @@ import { computeSqlFingerprint, explainWrite, isScratchSafeWrite, + UNAVAILABLE_NEXT_STEP, mentionsHardDenyAnywhere, } from "./sql-classify" import { statementsOf } from "./sql-tokenize" @@ -776,7 +777,7 @@ export function deniedWriteMessage(input: { const dialect = input.dialects.find((d) => classifyAndCheck(input.sql, d).queryType === "write") const { reason, unreadable, unavailable } = explainWrite(input.sql, dialect) const next = unavailable - ? "Changing the SQL will not help; ask the user to check the installation." + ? UNAVAILABLE_NEXT_STEP : unreadable ? "Fix the query and call sql_execute again; the same text will be refused again." + (readOnly ? "" : " The configured sql_execute_write rules may still deny it once it parses.") + From b2466f9e343cfbcc876211f81413d710381772c2 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 11:42:34 -0800 Subject: [PATCH 24/58] fix: name hard-blocked statements in read-only refusals Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/read-only-sql.ts | 16 ++++++++++++++-- .../tools/sql-readonly-guard-explain.test.ts | 9 +++++++++ 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 67f2eeb740..18dc99d9b0 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -77,11 +77,23 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool return semicolon < 0 ? sql : sql.slice(0, semicolon) + sql.slice(semicolon + 1) } -/** Why sql is refused as a read, as a sentence to append to a refusal: the classifier's reason for a write, +/** Why sql is refused as a read, as a sentence to append to a refusal: a hard block, the classifier's reason for a write, * or, for a read that only the stricter statement-word list refuses, that word (no SQL text). Empty otherwise. */ export function writeReason(sql: string, dialect?: string): string { const { queryType, blocked } = classifyAndCheck(sql, dialect) - if (blocked) return "" + if (blocked) { + // Text that cannot be read is blocked on its words alone, even inside an unclosed literal: name the + // unreadable text first, since closing the quote may be the whole fix. + const hard = + " It holds a hard-blocked statement, such as DROP DATABASE, DROP SCHEMA, TRUNCATE, SQL run from a string" + + " literal or an executable comment; those never run and cannot be allowed." + const untilClosed = + " Until it is closed, words inside the open quote or comment such as DROP DATABASE or TRUNCATE count as a" + + " hard-blocked statement, which never runs." + return tokenizeSql(sql, dialect).complete + ? hard + : ` It counts as a write because ${explainWrite(sql, dialect).reason}.${untilClosed}` + } if (queryType === "write") { const { reason, unavailable } = explainWrite(sql, dialect) return ` It counts as a write because ${reason}.${unavailable ? ` ${UNAVAILABLE_NEXT_STEP}` : ""}` diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 43927f6a8b..17838a3443 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -114,6 +114,15 @@ describe("other read-only refusals carry the reason", () => { ) }) + test("a hard-blocked statement is named as such", () => { + expect(writeReason("SELECT 1; DROP DATABASE prod", "postgres")).toContain("hard-blocked statement") + // An unclosed quote holding a blocked word names the quote first. + const reason = writeReason("SELECT a FROM t WHERE n = 'do not truncate", "postgres") + expect(reason.indexOf("unterminated")).toBeGreaterThan(-1) + expect(reason.indexOf("unterminated")).toBeLessThan(reason.indexOf("Until it is closed")) + expect(reason).not.toContain("cannot be allowed") + }) + test("a refusal that is not about writing stays as it was", () => { expect(writeReason("SELECT 1", "postgres")).toBe("") }) From 9aae937eb451d1fe3b6a49f8cbe8e7ae34ad94b6 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 11:50:16 -0800 Subject: [PATCH 25/58] docs: spaced qualifiers still ask, like quoted ones Co-Authored-By: Claude Opus 5.5 --- docs/docs/configure/permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index 3a6b281262..f1332a2cb7 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -253,7 +253,7 @@ When prompted, you have three choices: ### How SQL is classified for `sql_execute_write` -`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count (dotted names still count on ClickHouse); a quoted or bracketed qualifier (`"t".update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. On a dbt target, any Jinja (`{{ }}`, `{% %}`, `{# #}`) counts as a write too, even inside a comment or literal, because dbt renders and runs it first. +`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count (dotted names still count on ClickHouse); a quoted, bracketed or spaced qualifier (`"t".update`, `t . update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. On a dbt target, any Jinja (`{{ }}`, `{% %}`, `{# #}`) counts as a write too, even inside a comment or literal, because dbt renders and runs it first. When a query reaches the `sql_execute_write` check and a `"deny"` rule refuses it, the tool error tells the agent why the query counted as a write and what to change (hard-blocked statements such as `DROP DATABASE`, and writes inside a batch, fail earlier with their own messages): the statement that writes, the parser error and its position, or shell syntax such as `2>/dev/null` to remove. From 16c2cc28d80b43883cbd64bd64c36b1a4df79c49 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 11:52:47 -0800 Subject: [PATCH 26/58] fix: word unreadable quoted text neutrally (open or unsupported) Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 6 +++--- packages/opencode/src/altimate/tools/sql-classify.ts | 4 ++-- .../test/altimate/tools/sql-readonly-guard-explain.test.ts | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 18dc99d9b0..6071a6b904 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -82,13 +82,13 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool export function writeReason(sql: string, dialect?: string): string { const { queryType, blocked } = classifyAndCheck(sql, dialect) if (blocked) { - // Text that cannot be read is blocked on its words alone, even inside an unclosed literal: name the - // unreadable text first, since closing the quote may be the whole fix. + // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone: name + // the unreadable text first, since fixing it may be the whole fix. const hard = " It holds a hard-blocked statement, such as DROP DATABASE, DROP SCHEMA, TRUNCATE, SQL run from a string" + " literal or an executable comment; those never run and cannot be allowed." const untilClosed = - " Until it is closed, words inside the open quote or comment such as DROP DATABASE or TRUNCATE count as a" + + " Until that quoted text or comment can be read, words inside it such as DROP DATABASE or TRUNCATE count as a" + " hard-blocked statement, which never runs." return tokenizeSql(sql, dialect).complete ? hard diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index ca6ae879d5..d76b266ba2 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -624,8 +624,8 @@ export function explainWrite( const lexical = tokenizeSql(sql, dialect) if (!lexical.complete) { return unreadable( - "it has unterminated quoted text or comments, so it cannot be proven read-only. Check that every quote and comment " + - "is closed; inside a string literal, write a single quote as ''" + "it has unterminated or unsupported quoted text or comments, so it cannot be proven read-only. Check that every " + + "quote and comment is closed; inside a string literal, write a single quote as ''" ) } const statements = statementsOf(sql, dialect) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 17838a3443..3c39634d91 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -119,7 +119,7 @@ describe("other read-only refusals carry the reason", () => { // An unclosed quote holding a blocked word names the quote first. const reason = writeReason("SELECT a FROM t WHERE n = 'do not truncate", "postgres") expect(reason.indexOf("unterminated")).toBeGreaterThan(-1) - expect(reason.indexOf("unterminated")).toBeLessThan(reason.indexOf("Until it is closed")) + expect(reason.indexOf("unterminated")).toBeLessThan(reason.indexOf("Until that quoted text")) expect(reason).not.toContain("cannot be allowed") }) From ade0b0042840278c2324f2ea13a6fbb71ba8a64f Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 11:55:10 -0800 Subject: [PATCH 27/58] fix: name a closed executable comment instead of asking to close a quote Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 4 ++-- packages/opencode/src/altimate/tools/sql-classify.ts | 6 ++++++ .../test/altimate/tools/sql-readonly-guard-explain.test.ts | 7 +++++++ 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 6071a6b904..c39c712781 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -1,4 +1,4 @@ -import { UNAVAILABLE_NEXT_STEP, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" +import { EXECUTABLE_COMMENT, UNAVAILABLE_NEXT_STEP, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" import { maskSql, tokenizeSql } from "./sql-tokenize" import { sqlFunctionCalls } from "./sql-functions" import { hasSideEffectFunction } from "./sql-function-policy" @@ -90,7 +90,7 @@ export function writeReason(sql: string, dialect?: string): string { const untilClosed = " Until that quoted text or comment can be read, words inside it such as DROP DATABASE or TRUNCATE count as a" + " hard-blocked statement, which never runs." - return tokenizeSql(sql, dialect).complete + return tokenizeSql(sql, dialect).complete || EXECUTABLE_COMMENT.test(sql) ? hard : ` It counts as a write because ${explainWrite(sql, dialect).reason}.${untilClosed}` } diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index d76b266ba2..db35953757 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -589,6 +589,8 @@ export function shellResidue(sql: string, dialect?: string): string | undefined /** What to do when the SQL classifier itself is unavailable: no rewrite of the SQL can help. */ export const UNAVAILABLE_NEXT_STEP = "Changing the SQL will not help; ask the user to check the installation." +export const EXECUTABLE_COMMENT = /\/\*(?:!|[mM]!)/ + // Statement keywords that may name an UNKNOWN statement in a refusal. const STATEMENT_KEYWORDS = new Set([ "ATTACH", "DETACH", "INSTALL", "LOAD", "SET", "RESET", "PRAGMA", "COPY", "CALL", "EXEC", "EXECUTE", "GRANT", "REVOKE", @@ -623,6 +625,10 @@ export function explainWrite( if (residue) return unreadable(`it contains shell syntax (\`${residue}\`), which is not SQL. Remove it and send only the SQL`) const lexical = tokenizeSql(sql, dialect) if (!lexical.complete) { + // An executable comment (/*! ... */) is closed but runs as SQL on some engines, so it is never read as one. + if (EXECUTABLE_COMMENT.test(sql)) { + return unreadable("it contains an executable comment (/*! ... */), which some engines run as SQL; remove it or use a plain comment") + } return unreadable( "it has unterminated or unsupported quoted text or comments, so it cannot be proven read-only. Check that every " + "quote and comment is closed; inside a string literal, write a single quote as ''" diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 3c39634d91..61c8a408b4 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -114,6 +114,13 @@ describe("other read-only refusals carry the reason", () => { ) }) + test("a closed executable comment is named, not treated as an open quote", () => { + const reason = explainWrite("SELECT 1 /*! + 1 */", "mysql").reason + expect(reason).toContain("executable comment") + expect(reason).not.toContain("unterminated") + expect(writeReason("SELECT 1 /*! + 1 */", "mysql")).not.toContain("Until that quoted text") + }) + test("a hard-blocked statement is named as such", () => { expect(writeReason("SELECT 1; DROP DATABASE prod", "postgres")).toContain("hard-blocked statement") // An unclosed quote holding a blocked word names the quote first. From 742003c25ed3c9805a4d4e2254196e66eff28ca7 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 12:00:52 -0800 Subject: [PATCH 28/58] fix: name which statement is hard-blocked in read-only refusals Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 10 +++++++--- .../altimate/tools/sql-readonly-guard-explain.test.ts | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index c39c712781..b1e5d7254c 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -1,5 +1,5 @@ import { EXECUTABLE_COMMENT, UNAVAILABLE_NEXT_STEP, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" -import { maskSql, tokenizeSql } from "./sql-tokenize" +import { maskSql, statementsOf, tokenizeSql } from "./sql-tokenize" import { sqlFunctionCalls } from "./sql-functions" import { hasSideEffectFunction } from "./sql-function-policy" @@ -84,9 +84,13 @@ export function writeReason(sql: string, dialect?: string): string { if (blocked) { // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone: name // the unreadable text first, since fixing it may be the whole fix. + // Name the first statement that is blocked on its own, by position only (no SQL text is quoted back). + const statements = tokenizeSql(sql, dialect).complete ? statementsOf(sql, dialect) : [] + const index = statements.length > 1 ? statements.findIndex((statement) => classifyAndCheck(statement, dialect).blocked) : -1 + const where = index >= 0 ? `statement ${index + 1} of ${statements.length} is` : "it holds" const hard = - " It holds a hard-blocked statement, such as DROP DATABASE, DROP SCHEMA, TRUNCATE, SQL run from a string" + - " literal or an executable comment; those never run and cannot be allowed." + ` It is refused because ${where} a hard-blocked statement, such as DROP DATABASE, DROP SCHEMA, TRUNCATE, SQL run` + + " from a string literal or an executable comment; those never run and cannot be allowed." const untilClosed = " Until that quoted text or comment can be read, words inside it such as DROP DATABASE or TRUNCATE count as a" + " hard-blocked statement, which never runs." diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 61c8a408b4..bda8894f1f 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -122,7 +122,7 @@ describe("other read-only refusals carry the reason", () => { }) test("a hard-blocked statement is named as such", () => { - expect(writeReason("SELECT 1; DROP DATABASE prod", "postgres")).toContain("hard-blocked statement") + expect(writeReason("SELECT 1; DROP DATABASE prod", "postgres")).toContain("statement 2 of 2 is a hard-blocked statement") // An unclosed quote holding a blocked word names the quote first. const reason = writeReason("SELECT a FROM t WHERE n = 'do not truncate", "postgres") expect(reason.indexOf("unterminated")).toBeGreaterThan(-1) From f48e3d5fe38d804bafa631a0d979751bd99feae8 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 12:03:24 -0800 Subject: [PATCH 29/58] fix: detect executable comments from comment tokens, not raw text Co-Authored-By: Claude Opus 5.5 --- docs/docs/configure/permissions.md | 2 +- packages/opencode/src/altimate/tools/read-only-sql.ts | 4 ++-- packages/opencode/src/altimate/tools/sql-classify.ts | 7 +++++-- .../test/altimate/tools/sql-readonly-guard-explain.test.ts | 7 ++++++- 4 files changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index f1332a2cb7..7263e8fb74 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -253,7 +253,7 @@ When prompted, you have three choices: ### How SQL is classified for `sql_execute_write` -`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments, string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count (dotted names still count on ClickHouse); a quoted, bracketed or spaced qualifier (`"t".update`, `t . update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. On a dbt target, any Jinja (`{{ }}`, `{% %}`, `{# #}`) counts as a write too, even inside a comment or literal, because dbt renders and runs it first. +`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments (except MySQL executable comments such as `/*! ... */`, which are refused), string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count (dotted names still count on ClickHouse); a quoted, bracketed or spaced qualifier (`"t".update`, `t . update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. On a dbt target, any Jinja (`{{ }}`, `{% %}`, `{# #}`) counts as a write too, even inside a comment or literal, because dbt renders and runs it first. When a query reaches the `sql_execute_write` check and a `"deny"` rule refuses it, the tool error tells the agent why the query counted as a write and what to change (hard-blocked statements such as `DROP DATABASE`, and writes inside a batch, fail earlier with their own messages): the statement that writes, the parser error and its position, or shell syntax such as `2>/dev/null` to remove. diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index b1e5d7254c..16731d4430 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -1,4 +1,4 @@ -import { EXECUTABLE_COMMENT, UNAVAILABLE_NEXT_STEP, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" +import { UNAVAILABLE_NEXT_STEP, hasExecutableComment, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" import { maskSql, statementsOf, tokenizeSql } from "./sql-tokenize" import { sqlFunctionCalls } from "./sql-functions" import { hasSideEffectFunction } from "./sql-function-policy" @@ -94,7 +94,7 @@ export function writeReason(sql: string, dialect?: string): string { const untilClosed = " Until that quoted text or comment can be read, words inside it such as DROP DATABASE or TRUNCATE count as a" + " hard-blocked statement, which never runs." - return tokenizeSql(sql, dialect).complete || EXECUTABLE_COMMENT.test(sql) + return tokenizeSql(sql, dialect).complete || hasExecutableComment(sql, dialect) ? hard : ` It counts as a write because ${explainWrite(sql, dialect).reason}.${untilClosed}` } diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index db35953757..4d90585044 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -589,7 +589,10 @@ export function shellResidue(sql: string, dialect?: string): string | undefined /** What to do when the SQL classifier itself is unavailable: no rewrite of the SQL can help. */ export const UNAVAILABLE_NEXT_STEP = "Changing the SQL will not help; ask the user to check the installation." -export const EXECUTABLE_COMMENT = /\/\*(?:!|[mM]!)/ +// Whether the SQL holds an executable comment (a /*! comment) as a comment token, not inside a literal. +export function hasExecutableComment(sql: string, dialect?: string): boolean { + return tokenizeSql(sql, dialect).tokens.some(({ kind, text }) => kind === "comment" && /^\/\*(?:!|[mM]!)/.test(text)) +} // Statement keywords that may name an UNKNOWN statement in a refusal. const STATEMENT_KEYWORDS = new Set([ @@ -626,7 +629,7 @@ export function explainWrite( const lexical = tokenizeSql(sql, dialect) if (!lexical.complete) { // An executable comment (/*! ... */) is closed but runs as SQL on some engines, so it is never read as one. - if (EXECUTABLE_COMMENT.test(sql)) { + if (hasExecutableComment(sql, dialect)) { return unreadable("it contains an executable comment (/*! ... */), which some engines run as SQL; remove it or use a plain comment") } return unreadable( diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index bda8894f1f..9c9724d9a7 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -118,7 +118,12 @@ describe("other read-only refusals carry the reason", () => { const reason = explainWrite("SELECT 1 /*! + 1 */", "mysql").reason expect(reason).toContain("executable comment") expect(reason).not.toContain("unterminated") - expect(writeReason("SELECT 1 /*! + 1 */", "mysql")).not.toContain("Until that quoted text") + const refusal = writeReason("SELECT 1 /*! + 1 */", "mysql") + expect(refusal).toContain("hard-blocked statement") + expect(refusal).toContain("executable comment") + expect(refusal).not.toContain("Until that quoted text") + // The marker inside a literal is not a comment. + expect(explainWrite("SELECT '/*! x' AS a, 'unclosed", "mysql").reason).not.toContain("executable comment") }) test("a hard-blocked statement is named as such", () => { From 993e19efe08620790af068d58eba089ff740cbb2 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 12:13:12 -0800 Subject: [PATCH 30/58] fix: do not place a real hard block inside an unclosed quote When SQL cannot be fully read, the refusal now says blocked words count anywhere, inside the open quote or outside it, and that a real one outside it stays refused once the text is fixed. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 8 ++++---- .../altimate/tools/sql-readonly-guard-explain.test.ts | 6 ++++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 16731d4430..83a0e5217b 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -82,8 +82,6 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool export function writeReason(sql: string, dialect?: string): string { const { queryType, blocked } = classifyAndCheck(sql, dialect) if (blocked) { - // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone: name - // the unreadable text first, since fixing it may be the whole fix. // Name the first statement that is blocked on its own, by position only (no SQL text is quoted back). const statements = tokenizeSql(sql, dialect).complete ? statementsOf(sql, dialect) : [] const index = statements.length > 1 ? statements.findIndex((statement) => classifyAndCheck(statement, dialect).blocked) : -1 @@ -91,9 +89,11 @@ export function writeReason(sql: string, dialect?: string): string { const hard = ` It is refused because ${where} a hard-blocked statement, such as DROP DATABASE, DROP SCHEMA, TRUNCATE, SQL run` + " from a string literal or an executable comment; those never run and cannot be allowed." + // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone, inside the + // unreadable text or outside it: name the unreadable text first, since fixing it may be the whole fix. const untilClosed = - " Until that quoted text or comment can be read, words inside it such as DROP DATABASE or TRUNCATE count as a" + - " hard-blocked statement, which never runs." + " Until it can be read, words such as DROP DATABASE or TRUNCATE anywhere in the SQL, inside that quoted text or" + + " outside it, count as a hard-blocked statement; a real one outside it stays refused once the text is fixed." return tokenizeSql(sql, dialect).complete || hasExecutableComment(sql, dialect) ? hard : ` It counts as a write because ${explainWrite(sql, dialect).reason}.${untilClosed}` diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 9c9724d9a7..2194240c81 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -121,7 +121,7 @@ describe("other read-only refusals carry the reason", () => { const refusal = writeReason("SELECT 1 /*! + 1 */", "mysql") expect(refusal).toContain("hard-blocked statement") expect(refusal).toContain("executable comment") - expect(refusal).not.toContain("Until that quoted text") + expect(refusal).not.toContain("Until it can be read") // The marker inside a literal is not a comment. expect(explainWrite("SELECT '/*! x' AS a, 'unclosed", "mysql").reason).not.toContain("executable comment") }) @@ -131,8 +131,10 @@ describe("other read-only refusals carry the reason", () => { // An unclosed quote holding a blocked word names the quote first. const reason = writeReason("SELECT a FROM t WHERE n = 'do not truncate", "postgres") expect(reason.indexOf("unterminated")).toBeGreaterThan(-1) - expect(reason.indexOf("unterminated")).toBeLessThan(reason.indexOf("Until that quoted text")) + expect(reason.indexOf("unterminated")).toBeLessThan(reason.indexOf("Until it can be read")) expect(reason).not.toContain("cannot be allowed") + // A real hard block outside the open quote is not described as sitting inside it. + expect(writeReason("DROP DATABASE x; SELECT 'abc", "postgres")).toContain("inside that quoted text or outside it") }) test("a refusal that is not about writing stays as it was", () => { From 162d1d90fa4480ccfbe76176ec7aa8996dd23d3b Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 12:30:13 -0800 Subject: [PATCH 31/58] fix: name the hard-block rule and explain hard blocks in every tool - Refusals name the matched rule (DROP DATABASE, TRUNCATE, an executable comment, SQL run from a string literal) by fixed label, no SQL text. - `sql_execute`, `data_diff` and `sql_explain` hard-block errors append the reason, so an open quote that made a word count says to close it. - An unparseable SELECT ... INTO is reported as a write, not a syntax error. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/data-diff.ts | 5 ++++- .../src/altimate/tools/read-only-sql.ts | 7 +++--- .../src/altimate/tools/sql-classify.ts | 17 ++++++++++++++ .../src/altimate/tools/sql-execute.ts | 5 ++++- .../src/altimate/tools/sql-explain.ts | 3 ++- .../tools/sql-readonly-guard-explain.test.ts | 22 ++++++++++++++++++- .../altimate/tools/sql-readonly-guard.test.ts | 11 ++++++++++ 7 files changed, 62 insertions(+), 8 deletions(-) diff --git a/packages/opencode/src/altimate/tools/data-diff.ts b/packages/opencode/src/altimate/tools/data-diff.ts index 2a883ff4ad..ce604a87cf 100644 --- a/packages/opencode/src/altimate/tools/data-diff.ts +++ b/packages/opencode/src/altimate/tools/data-diff.ts @@ -3,6 +3,7 @@ import { Tool } from "../../tool/tool" import { Dispatcher } from "../native" import * as Registry from "../native/connections/registry" import { classifyAndCheck } from "./sql-classify" +import { writeReason } from "./read-only-sql" export const DataDiffTool = Tool.define("data_diff", { description: [ @@ -104,7 +105,9 @@ export const DataDiffTool = Tool.define("data_diff", { const dialectOf = (warehouse?: string) => Registry.canonicalType(warehouse ? Registry.getConfig(warehouse)?.type : undefined) ?? undefined for (const [sql, warehouse] of [[args.source, sourceWarehouse], [args.target, targetWarehouse]] as const) if (classifyAndCheck(sql, dialectOf(warehouse)).blocked) - throw new Error("DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety. This cannot be overridden.") + throw new Error( + `DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety. This cannot be overridden.${writeReason(sql, dialectOf(warehouse))}`, + ) for (const side of sides) await ctx.ask({ permission: "sql_execute_read", diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 83a0e5217b..20af539f29 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -1,4 +1,4 @@ -import { UNAVAILABLE_NEXT_STEP, hasExecutableComment, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" +import { UNAVAILABLE_NEXT_STEP, hardBlockCause, hasExecutableComment, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" import { maskSql, statementsOf, tokenizeSql } from "./sql-tokenize" import { sqlFunctionCalls } from "./sql-functions" import { hasSideEffectFunction } from "./sql-function-policy" @@ -86,9 +86,8 @@ export function writeReason(sql: string, dialect?: string): string { const statements = tokenizeSql(sql, dialect).complete ? statementsOf(sql, dialect) : [] const index = statements.length > 1 ? statements.findIndex((statement) => classifyAndCheck(statement, dialect).blocked) : -1 const where = index >= 0 ? `statement ${index + 1} of ${statements.length} is` : "it holds" - const hard = - ` It is refused because ${where} a hard-blocked statement, such as DROP DATABASE, DROP SCHEMA, TRUNCATE, SQL run` + - " from a string literal or an executable comment; those never run and cannot be allowed." + const cause = hardBlockCause(index >= 0 ? statements[index] : sql, dialect) + const hard = ` It is refused because ${where} a hard-blocked statement (${cause}); hard-blocked statements never run and cannot be allowed.` // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone, inside the // unreadable text or outside it: name the unreadable text first, since fixing it may be the whole fix. const untilClosed = diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 4d90585044..1c794c1f98 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -594,6 +594,18 @@ export function hasExecutableComment(sql: string, dialect?: string): boolean { return tokenizeSql(sql, dialect).tokens.some(({ kind, text }) => kind === "comment" && /^\/\*(?:!|[mM]!)/.test(text)) } +// Which hard-block rule a blocked statement matched, as a fixed label (no SQL text): DROP DATABASE, SCHEMA, +// CATALOG or NAMESPACE, TRUNCATE, an executable comment, or else SQL run from a string literal. +export function hardBlockCause(sql: string, dialect?: string): string { + const lexical = tokenizeSql(sql, dialect) + const code = lexical.complete ? namesKept(lexical.tokens) : "" + const drop = /\bDROP\s+(?:(?:EXTERNAL|PLUGGABLE)\s+)?(DATABASE|SCHEMA|CATALOG|NAMESPACE)\b/i.exec(code) + if (drop) return `DROP ${drop[1].toUpperCase()}` + if (/\bTRUNCATE\b(?!\s*\()/i.test(code)) return "TRUNCATE" + if (hasExecutableComment(sql, dialect)) return "an executable comment" + return "SQL run from a string literal" +} + // Statement keywords that may name an UNKNOWN statement in a refusal. const STATEMENT_KEYWORDS = new Set([ "ATTACH", "DETACH", "INSTALL", "LOAD", "SET", "RESET", "PRAGMA", "COPY", "CALL", "EXEC", "EXECUTE", "GRANT", "REVOKE", @@ -661,6 +673,11 @@ export function explainWrite( "; run each statement in its own call, or quote it if it is a column name", ) } + // A SELECT ... INTO the parser cannot read (MySQL INTO OUTFILE or @var) is still a write: say so, not "fix the syntax". + const code = maskSql(tokenizeSql(statement, dialect).tokens) + if (result.parseError && /^\s*(SELECT|WITH)\b/i.test(code) && /(? classifyAndCheck(sql, d).blocked) + const why = blockedIn >= 0 ? writeReason(sql, dialects[blockedIn]) : "" throw new Error( - "DROP DATABASE, DROP SCHEMA, TRUNCATE, and executable SQL comments are blocked for safety. This cannot be overridden.", + `DROP DATABASE, DROP SCHEMA, TRUNCATE, and executable SQL comments are blocked for safety. This cannot be overridden.${why}`, ) } if (budget && queryType !== "read") { diff --git a/packages/opencode/src/altimate/tools/sql-explain.ts b/packages/opencode/src/altimate/tools/sql-explain.ts index 699e884fa7..eb0f8946c0 100644 --- a/packages/opencode/src/altimate/tools/sql-explain.ts +++ b/packages/opencode/src/altimate/tools/sql-explain.ts @@ -8,6 +8,7 @@ import * as Precedence from "../workspace/precedence" import { validateWarehouseName } from "./input-validation" import * as Registry from "../native/connections/registry" import { classifyAndCheck, isSingleQuery } from "./sql-classify" +import { writeReason } from "./read-only-sql" import { maskSql, statementsOf, tokenizeSql } from "./sql-tokenize" /** @@ -108,7 +109,7 @@ export const SqlExplainTool = Tool.define("sql_explain", { /^(EXPLAIN|ANALY[SZ]E|VERBOSE)\b|^\((?![(\s]*(SELECT|WITH|VALUES|TABLE|FROM)\b)/i.test(statements[0] ?? "") || (lexical.complete && /^\s*;/.test(maskSql(lexical.tokens))) let error: string | undefined - if (blocked) error = "DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety." + if (blocked) error = `DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety.${writeReason(args.sql, dialect)}` else if (!lexical.complete) error = lexical.backslash ? "The SQL has a backslash in a quoted string, which this dialect can read as an escape, so it is not explained. Build that character with the dialect's character function instead (CHR(92) or CHAR(92), depending on the dialect) to get a plan." diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 2194240c81..ba67994723 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -127,7 +127,16 @@ describe("other read-only refusals carry the reason", () => { }) test("a hard-blocked statement is named as such", () => { - expect(writeReason("SELECT 1; DROP DATABASE prod", "postgres")).toContain("statement 2 of 2 is a hard-blocked statement") + expect(writeReason("SELECT 1; DROP DATABASE prod", "postgres")).toContain( + "statement 2 of 2 is a hard-blocked statement (DROP DATABASE)", + ) + // The matched rule is named by a fixed label, never with SQL text. + expect(writeReason("SELECT 1; TRUNCATE TABLE secret_t", "postgres")).toContain("(TRUNCATE)") + expect(writeReason("DROP SCHEMA s", "postgres")).toContain("it holds a hard-blocked statement (DROP SCHEMA)") + expect(writeReason("SELECT 1 /*! + 1 */", "mysql")).toContain("(an executable comment)") + const nested = writeReason("SELECT * FROM query('DROP SCHEMA secret_s')", "duckdb") + expect(nested).toContain("(SQL run from a string literal)") + expect(nested).not.toContain("secret_s") // An unclosed quote holding a blocked word names the quote first. const reason = writeReason("SELECT a FROM t WHERE n = 'do not truncate", "postgres") expect(reason.indexOf("unterminated")).toBeGreaterThan(-1) @@ -137,6 +146,17 @@ describe("other read-only refusals carry the reason", () => { expect(writeReason("DROP DATABASE x; SELECT 'abc", "postgres")).toContain("inside that quoted text or outside it") }) + test("a SELECT ... INTO the parser cannot read is a write, not a syntax error", () => { + for (const sql of ["SELECT a FROM t INTO OUTFILE '/tmp/x'", "SELECT a FROM t LIMIT 1 INTO @v"]) { + const reason = explainWrite(sql, "mysql").reason + expect(reason).toContain("INTO clause") + expect(reason).not.toContain("could not read") + } + // INTO inside a literal or after a dot is not an INTO clause. + expect(explainWrite("SELECT 'into' FROM WHERE", "postgres").reason).toContain("could not read") + expect(explainWrite("SELECT t.into FROM WHERE", "postgres").reason).toContain("could not read") + }) + test("a refusal that is not about writing stays as it was", () => { expect(writeReason("SELECT 1", "postgres")).toBe("") }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 050e3f6895..d4102f0471 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -170,6 +170,17 @@ describe("sql_execute on a read-only agent", () => { expect(error).toContain("Fix the query") }) + test("a hard block names its rule, or the open quote that made a word count", async () => { + const quote = await run("SELECT * FROM t WHERE note = 'don't truncate'") + expect(quote.error).toContain("blocked for safety") + expect(quote.error).toContain("unterminated") + expect(quote.error).toContain("write a single quote as ''") + expect(quote.asked).toHaveLength(0) + const real = await run("SELECT 1; DROP DATABASE secret_db") + expect(real.error).toContain("statement 2 of 2 is a hard-blocked statement (DROP DATABASE)") + expect(real.error).not.toContain("secret_db") + }) + test("a write names the statement and suggests a read", async () => { const { error } = await run("SELECT 1; DELETE FROM orders") expect(error).toContain("statement 2 of 2 is not a read (DELETE)") From 83b753f92b43218ae48431c1c7f4aa1eb0994662 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 12:52:28 -0800 Subject: [PATCH 32/58] fix: record the hard-block cause in the classifier itself - The classifier sets a fixed cause label where it blocks; refusals show it. - Unreadable-text blocks no longer claim "cannot be overridden". - Jinja-only blocks say why; the blocking dialect is reused. - MCP/tool CLI write denials get the reason plus the --allow-write hint. - Any parse-failed SELECT with a write clause is named a write. Co-Authored-By: Claude Opus 5.5 --- docs/docs/usage/tool.md | 2 +- .../src/altimate/tool-cli/permissions.ts | 6 +- .../opencode/src/altimate/tools/data-diff.ts | 6 +- .../src/altimate/tools/read-only-sql.ts | 7 ++ .../src/altimate/tools/sql-classify.ts | 72 +++++++++++-------- .../src/altimate/tools/sql-execute.ts | 42 ++++++----- .../src/altimate/tools/sql-explain.ts | 4 +- .../test/altimate/sql-read-syntax.test.ts | 2 +- .../test/altimate/tool-cli/runner.test.ts | 4 +- .../altimate/tools/sql-comment-safety.test.ts | 2 + .../tools/sql-readonly-guard-explain.test.ts | 19 ++++- .../altimate/tools/sql-readonly-guard.test.ts | 12 ++++ .../skill/release-v0.12.9-adversarial.test.ts | 4 +- 13 files changed, 123 insertions(+), 59 deletions(-) diff --git a/docs/docs/usage/tool.md b/docs/docs/usage/tool.md index 7a1caea180..c61fddf72f 100644 --- a/docs/docs/usage/tool.md +++ b/docs/docs/usage/tool.md @@ -51,7 +51,7 @@ Only the data tools are exposed. Coding tools (`bash`, `read`, `edit`, ...), `db ## Permissions -Runs are read-only by default. Reads such as `sql_execute` on a SELECT and `schema_inspect` are allowed; anything else is refused with `Permission denied: . Re-run with --allow-write to enable writes.` Tools that change local configuration (`warehouse_add`, `warehouse_remove`, `warehouse_install_driver`) also need `--allow-write`. +Runs are read-only by default. Reads such as `sql_execute` on a SELECT and `schema_inspect` are allowed; anything else is refused with `Permission denied: . Re-run with --allow-write to enable writes.` For `sql_execute`, the refusal first says why the query counts as a write, so a malformed read can be fixed instead. Tools that change local configuration (`warehouse_add`, `warehouse_remove`, `warehouse_install_driver`) also need `--allow-write`. `DROP` of a database, schema, catalog or namespace (including `DROP EXTERNAL SCHEMA` and `DROP PLUGGABLE DATABASE`), `TRUNCATE`, and MySQL/MariaDB executable comments (`/*! ... */`, `/*M! ... */`) are refused even with `--allow-write` when the SQL check recognises them. The check reads the SQL text, so it is best effort: a statement the warehouse builds or decodes at run time (dynamic SQL assembled by concatenation, a stored routine, an unusual literal encoding) can get past it. For a hard guarantee, connect with a database user that has no `DROP` or `TRUNCATE` privilege. diff --git a/packages/opencode/src/altimate/tool-cli/permissions.ts b/packages/opencode/src/altimate/tool-cli/permissions.ts index 24e04ed2e4..62335aebaa 100644 --- a/packages/opencode/src/altimate/tool-cli/permissions.ts +++ b/packages/opencode/src/altimate/tool-cli/permissions.ts @@ -25,8 +25,12 @@ function dialectOf(metadata: unknown): string | undefined { : undefined } +/** A write refused because writes were not enabled; sql_execute adds why the query counts as a write. */ +export class WriteDeniedError extends Error {} + export function denied(permission: string, retry = "Re-run"): Error { - return new Error(`Permission denied: ${permission}. ${retry} with --allow-write to enable writes.`) + const message = `Permission denied: ${permission}. ${retry} with --allow-write to enable writes.` + return permission === "sql_execute_write" ? new WriteDeniedError(message) : new Error(message) } /** diff --git a/packages/opencode/src/altimate/tools/data-diff.ts b/packages/opencode/src/altimate/tools/data-diff.ts index ce604a87cf..32216da14c 100644 --- a/packages/opencode/src/altimate/tools/data-diff.ts +++ b/packages/opencode/src/altimate/tools/data-diff.ts @@ -3,7 +3,7 @@ import { Tool } from "../../tool/tool" import { Dispatcher } from "../native" import * as Registry from "../native/connections/registry" import { classifyAndCheck } from "./sql-classify" -import { writeReason } from "./read-only-sql" +import { hardBlockRefusal } from "./read-only-sql" export const DataDiffTool = Tool.define("data_diff", { description: [ @@ -105,9 +105,7 @@ export const DataDiffTool = Tool.define("data_diff", { const dialectOf = (warehouse?: string) => Registry.canonicalType(warehouse ? Registry.getConfig(warehouse)?.type : undefined) ?? undefined for (const [sql, warehouse] of [[args.source, sourceWarehouse], [args.target, targetWarehouse]] as const) if (classifyAndCheck(sql, dialectOf(warehouse)).blocked) - throw new Error( - `DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety. This cannot be overridden.${writeReason(sql, dialectOf(warehouse))}`, - ) + throw new Error(hardBlockRefusal("DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety.", sql, dialectOf(warehouse))) for (const side of sides) await ctx.ask({ permission: "sql_execute_read", diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 20af539f29..616816cde5 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -77,6 +77,13 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool return semicolon < 0 ? sql : sql.slice(0, semicolon) + sql.slice(semicolon + 1) } +/** A hard-block refusal: head, then "cannot be overridden" unless only unreadable text (an open quote or comment) + * made a word count, then the reason. */ +export function hardBlockRefusal(head: string, sql: string, dialect?: string): string { + const unreadable = !tokenizeSql(sql, dialect).complete && !hasExecutableComment(sql, dialect) + return `${head}${unreadable ? "" : " This cannot be overridden."}${writeReason(sql, dialect)}` +} + /** Why sql is refused as a read, as a sentence to append to a refusal: a hard block, the classifier's reason for a write, * or, for a read that only the stricter statement-word list refuses, that word (no SQL text). Empty otherwise. */ export function writeReason(sql: string, dialect?: string): string { diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 1c794c1f98..17730f19df 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -183,15 +183,26 @@ const HARD_DENY_PATTERN = /^\s*(DROP\s+((EXTERNAL|PLUGGABLE)\s+)?(DATABASE|SCHEM * Fail closed when the parser is unavailable or rejects the input. Lexical * statement boundaries still enforce hard denies without reading quoted text. */ -function classifyFallback(sql: string, dialect?: string, write = true): { queryType: "read" | "write"; blocked: boolean } { +// The label of a hard-deny match (DROP DATABASE, DROP SCHEMA, ..., TRUNCATE), from the matched text only. +function hardDenyLabel(match: string): string { + const drop = /\bDROP\s+(?:(?:EXTERNAL|PLUGGABLE)\s+)?(\w+)/i.exec(match) + return drop ? `DROP ${drop[1].toUpperCase()}` : "TRUNCATE" +} + +function classifyFallback( + sql: string, + dialect?: string, + write = true, +): { queryType: "read" | "write"; blocked: boolean; cause?: string } { const statements = statementsOf(sql, dialect) + // The first rule that blocks names the cause (a fixed label, no SQL text). + let cause: string | undefined // Executable comments can contain entire statements or fragments of a hard // deny. Reject them outright because generic parsers discard their bodies. - let blocked = tokenizeSql(sql, dialect).tokens.some( - ({ kind, text }) => kind === "comment" && /^\/\*(?:!|[mM]!)/.test(text), - ) + if (hasExecutableComment(sql, dialect)) cause = "an executable comment" for (const stmt of statements) { - if (HARD_DENY_PATTERN.test(stmt)) blocked = true + const match = HARD_DENY_PATTERN.exec(stmt) + if (match) cause ??= hardDenyLabel(match[0]) } // When quoting or comments cannot be read with certainty, no reading of the literals or comments // can be trusted to hide a hard deny (a misread literal can make a real statement look like a @@ -199,7 +210,7 @@ function classifyFallback(sql: string, dialect?: string, write = true): { queryT const lexical = tokenizeSql(sql, dialect) if (!lexical.complete) { // Escapes decoded too: dynamic SQL may run a literal such as '\x44ROP SCHEMA s'. - if (mentionsHardDenyAnywhere(sql)) blocked = true + if (mentionsHardDenyAnywhere(sql)) cause ??= "DROP DATABASE, DROP SCHEMA or TRUNCATE words in text that cannot be fully read" } else { // Read with certainty: the statement words in code (literals and comments masked, each quoted // identifier a placeholder name, so DROP/**/SCHEMA reads as DROP SCHEMA) decide too, since T-SQL runs `SELECT 1 DROP DATABASE x` @@ -210,17 +221,19 @@ function classifyFallback(sql: string, dialect?: string, write = true): { queryT const chained = (/^snowflake$/i.test(dialect ?? "") || !isModeledDialect(dialect)) && /(->>|\bASYNC\s*\(|:=\s*\(|\bDEFAULT\s*\()\s*TRUNCATE\b(?!\s*\()/i.test(names) - if (CODE_HARD_DENY.test(names) || handlerTruncate(names) || chained || (write && WRITE_TRUNCATE.test(names))) - blocked = true + const code = CODE_HARD_DENY.exec(names) + if (code) cause ??= hardDenyLabel(code[0]) + else if (handlerTruncate(names) || chained || (write && WRITE_TRUNCATE.test(names))) cause ??= "TRUNCATE" // Dynamic SQL runs its literals, joined into one statement ('DROP ' + 'DATABASE x', or PostgreSQL's // adjacent constants), whether the call reads as a read (SELECT exec('...')) or a write. This runs at // every nesting depth, as on main. Both readings count: quoted names masked to spaces, as on main, so // EXEC[sp_executesql] and PREPARE`p`FROM keep their word boundaries, and quoted names unwrapped, so // "exec"('...') and [exec]('...') count as calls. const dynamic = DYNAMIC_SQL.test(maskSql(lexical.tokens)) || DYNAMIC_SQL.test(maskSql(lexical.tokens, true)) - if (dynamic && mentionsHardDenyAnywhere(sql)) blocked = true + if (dynamic && mentionsHardDenyAnywhere(sql)) + cause ??= "dynamic SQL (EXEC, PREPARE or DO) with DROP DATABASE, DROP SCHEMA or TRUNCATE in its text" } - return { queryType: "write", blocked } + return { queryType: "write", blocked: cause !== undefined, ...(cause && { cause }) } } /** The statement keyword, if any. Where statements need no separator (T-SQL) or the dialect is not one the lexer models, a read @@ -467,13 +480,16 @@ export function classifyAndCheck(sql: string, dialect?: string): { queryType: "read" | "write" blocked: boolean parseError?: string + /** Which hard-block rule matched, as a fixed label with no SQL text; set when blocked. */ + cause?: string } { const result = classifySql(sql, dialect, 0) if (result.queryType !== "write" || result.blocked) return result // A write may also run the SQL in its literals: a routine body created and called in the same call. Only // SQL read with certainty; otherwise the word scan of the whole text already covered its literals. const lexical = tokenizeSql(sql, dialect) - if (lexical.complete && quotedHardDeny(lexical.tokens, dialect)) return { ...result, blocked: true } + if (lexical.complete && quotedHardDeny(lexical.tokens, dialect)) + return { ...result, blocked: true, cause: "a string literal this write may run, holding a hard-blocked statement or a Unicode escape" } return result } @@ -488,6 +504,7 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { queryType: "read" | "write" blocked: boolean parseError?: string + cause?: string } { if (!sql || typeof sql !== "string") return { queryType: "read", blocked: false } const lexical = tokenizeSql(sql, dialect) @@ -505,12 +522,14 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // trailing statements. Keep dialect-aware lexical hard denies authoritative. const functions = functionSafety(sql, dialect, depth) const masked = maskSql(lexical.tokens) - const blocked = - functions.blocked || - classifyFallback(sql, dialect, false).blocked || - result.statements.some( - (s: { statement_type: string }) => s.statement_type && HARD_DENY_TYPES.has(s.statement_type.toUpperCase()), - ) + const hardType = result.statements.find( + (s: { statement_type: string }) => s.statement_type && HARD_DENY_TYPES.has(s.statement_type.toUpperCase()), + )?.statement_type + const cause = + (functions.blocked ? "SQL run from a string literal" : undefined) ?? + classifyFallback(sql, dialect, false).cause ?? + (hardType ? hardDenyLabel(hardType) : undefined) + const blocked = cause !== undefined const queryType = !functions.write && @@ -527,7 +546,9 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { otherIsReadOnly(sql, result.statements, dialect) ? "read" : "write" - return { queryType, blocked: blocked || (queryType === "write" && WRITE_TRUNCATE.test(namesKept(lexical.tokens))) } + const writeTruncate = queryType === "write" && WRITE_TRUNCATE.test(namesKept(lexical.tokens)) + const finalCause = cause ?? (writeTruncate ? "TRUNCATE" : undefined) + return { queryType, blocked: finalCause !== undefined, ...(finalCause && { cause: finalCause }) } } catch (error) { return { ...classifyFallback(sql, dialect), parseError: error instanceof Error ? error.message : String(error) } } @@ -594,16 +615,9 @@ export function hasExecutableComment(sql: string, dialect?: string): boolean { return tokenizeSql(sql, dialect).tokens.some(({ kind, text }) => kind === "comment" && /^\/\*(?:!|[mM]!)/.test(text)) } -// Which hard-block rule a blocked statement matched, as a fixed label (no SQL text): DROP DATABASE, SCHEMA, -// CATALOG or NAMESPACE, TRUNCATE, an executable comment, or else SQL run from a string literal. +// Which hard-block rule a blocked statement matched, as the classifier recorded it (no SQL text). export function hardBlockCause(sql: string, dialect?: string): string { - const lexical = tokenizeSql(sql, dialect) - const code = lexical.complete ? namesKept(lexical.tokens) : "" - const drop = /\bDROP\s+(?:(?:EXTERNAL|PLUGGABLE)\s+)?(DATABASE|SCHEMA|CATALOG|NAMESPACE)\b/i.exec(code) - if (drop) return `DROP ${drop[1].toUpperCase()}` - if (/\bTRUNCATE\b(?!\s*\()/i.test(code)) return "TRUNCATE" - if (hasExecutableComment(sql, dialect)) return "an executable comment" - return "SQL run from a string literal" + return classifyAndCheck(sql, dialect).cause ?? "a hard-blocked statement" } // Statement keywords that may name an UNKNOWN statement in a refusal. @@ -675,8 +689,8 @@ export function explainWrite( } // A SELECT ... INTO the parser cannot read (MySQL INTO OUTFILE or @var) is still a write: say so, not "fix the syntax". const code = maskSql(tokenizeSql(statement, dialect).tokens) - if (result.parseError && /^\s*(SELECT|WITH)\b/i.test(code) && /(? classifyAndCheck(sql, d).blocked) - const why = blockedIn >= 0 ? writeReason(sql, dialects[blockedIn]) : "" - throw new Error( - `DROP DATABASE, DROP SCHEMA, TRUNCATE, and executable SQL comments are blocked for safety. This cannot be overridden.${why}`, - ) + const blockedIn = "blockedIndex" in classification ? classification.blockedIndex : -1 + if (blockedIn >= 0) throw new Error(hardBlockRefusal(head, sql, dialects[blockedIn])) + if (jinja) + throw new Error( + `${head} It contains Jinja, which dbt renders before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + + "TRUNCATE words count wherever they sit, even in a literal or comment. Remove those words, or send plain SQL without Jinja.", + ) + throw new Error(`${head} This cannot be overridden.`) } if (budget && queryType !== "read") { throw new Error("Batched queries must be read-only; run a write as its own sql_execute call.") @@ -298,6 +303,18 @@ export const SqlExecuteTool = Tool.define( }, }) } catch (error) { + const explain = (readOnly: boolean) => + deniedWriteMessage({ + sql, + dialects, + jinja, + mongo: mongo !== null, + scratch: isScratch(args.warehouse), + warehouseGiven: !!args.warehouse, + readOnly, + }) + // The MCP server and `altimate tool` refuse writes unless --allow-write was given. + if (error instanceof WriteDeniedError) throw new Error(`${explain(true)} ${error.message}`) if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error const rules: Array<{ pattern?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] // Rules apply last-match-wins: the agent is read-only when the last catch-all rule denies and @@ -306,17 +323,9 @@ export const SqlExecuteTool = Tool.define( rules.forEach((rule, index) => { if (rule.pattern === "*" && rule.action === "deny") lastCatchAllDeny = index }) + // With no catch-all deny, writes the rules do not name fall to the default ("ask"). throw new Error( - deniedWriteMessage({ - sql, - dialects, - jinja, - mongo: mongo !== null, - scratch: isScratch(args.warehouse), - warehouseGiven: !!args.warehouse, - // With no catch-all deny, writes the rules do not name fall to the default ("ask"). - readOnly: lastCatchAllDeny >= 0 && !rules.slice(lastCatchAllDeny + 1).some((rule) => rule.action !== "deny"), - }), + explain(lastCatchAllDeny >= 0 && !rules.slice(lastCatchAllDeny + 1).some((rule) => rule.action !== "deny")), ) } } @@ -751,6 +760,7 @@ function classifyEvery(sql: string, dialects: (string | undefined)[]) { return { queryType: results.some((result) => result.queryType === "write") ? ("write" as const) : ("read" as const), blocked: results.some((result) => result.blocked), + blockedIndex: results.findIndex((result) => result.blocked), ...(parseError && { parseError }), } } diff --git a/packages/opencode/src/altimate/tools/sql-explain.ts b/packages/opencode/src/altimate/tools/sql-explain.ts index eb0f8946c0..d9b5635262 100644 --- a/packages/opencode/src/altimate/tools/sql-explain.ts +++ b/packages/opencode/src/altimate/tools/sql-explain.ts @@ -8,7 +8,7 @@ import * as Precedence from "../workspace/precedence" import { validateWarehouseName } from "./input-validation" import * as Registry from "../native/connections/registry" import { classifyAndCheck, isSingleQuery } from "./sql-classify" -import { writeReason } from "./read-only-sql" +import { hardBlockRefusal } from "./read-only-sql" import { maskSql, statementsOf, tokenizeSql } from "./sql-tokenize" /** @@ -109,7 +109,7 @@ export const SqlExplainTool = Tool.define("sql_explain", { /^(EXPLAIN|ANALY[SZ]E|VERBOSE)\b|^\((?![(\s]*(SELECT|WITH|VALUES|TABLE|FROM)\b)/i.test(statements[0] ?? "") || (lexical.complete && /^\s*;/.test(maskSql(lexical.tokens))) let error: string | undefined - if (blocked) error = `DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety.${writeReason(args.sql, dialect)}` + if (blocked) error = hardBlockRefusal("DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety.", args.sql, dialect) else if (!lexical.complete) error = lexical.backslash ? "The SQL has a backslash in a quoted string, which this dialect can read as an escape, so it is not explained. Build that character with the dialect's character function instead (CHR(92) or CHAR(92), depending on the dialect) to get a plan." diff --git a/packages/opencode/test/altimate/sql-read-syntax.test.ts b/packages/opencode/test/altimate/sql-read-syntax.test.ts index c8b2a149c5..7500a77692 100644 --- a/packages/opencode/test/altimate/sql-read-syntax.test.ts +++ b/packages/opencode/test/altimate/sql-read-syntax.test.ts @@ -60,7 +60,7 @@ describe("read-only dialect syntax", () => { ]) { expect(classifyAndCheck(sql, "duckdb").queryType).toBe("write") } - expect(classifyAndCheck("SELECT 10//3; TRUNCATE users", "duckdb")).toEqual({ queryType: "write", blocked: true }) + expect(classifyAndCheck("SELECT 10//3; TRUNCATE users", "duckdb")).toEqual({ queryType: "write", blocked: true, cause: "TRUNCATE" }) }) test("unsupported dialects do not inherit DuckDB-only syntax", () => { diff --git a/packages/opencode/test/altimate/tool-cli/runner.test.ts b/packages/opencode/test/altimate/tool-cli/runner.test.ts index 67cbae0f0e..a7f0739f98 100644 --- a/packages/opencode/test/altimate/tool-cli/runner.test.ts +++ b/packages/opencode/test/altimate/tool-cli/runner.test.ts @@ -136,7 +136,9 @@ describe("tool run", () => { test("a write is denied without --allow-write", async () => { const result = await runner.run("sql_execute", { query: "CREATE TABLE t (a int)" }) expect(result.status).toBe("error") - expect(result.output).toBe("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.") + // The refusal says why the query counts as a write, then how to enable writes. + expect(result.output).toContain("counts as a write because") + expect(result.output.endsWith("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.")).toBe(true) }) test("config-changing tools need --allow-write", async () => { diff --git a/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts b/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts index 96eca55685..06657ae143 100644 --- a/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts +++ b/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts @@ -265,6 +265,8 @@ test("on the dbt route, Jinja in a comment or literal is a write, and a hard-den expect(write.asked).toEqual(["sql_execute_write"]) const drop = await run("SELECT 1 AS x -- {% do run_query('DROP SCHEMA prod CASCADE') %}") await expect(drop.result).rejects.toThrow("blocked for safety") + // Blocked by the Jinja word scan alone (the SQL reads the words as a comment): the error says why. + await expect((await run("SELECT 1 AS x -- {% do run_query('DROP SCHEMA prod CASCADE') %}")).result).rejects.toThrow("dbt renders") // A Jinja comment removes text, which can expose a statement the SQL lexing reads as a literal. const hidden = await run("SELECT 'x' /* {# */ || ' #} */) AS q ; DROP SCHEMA s CASCADE ; SELECT 1 -- '") await expect(hidden.result).rejects.toThrow("blocked for safety") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index ba67994723..c80bb28c8c 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -1,6 +1,6 @@ import { describe, expect, test } from "bun:test" import { classifyAndCheck, explainWrite, shellResidue } from "../../../src/altimate/tools/sql-classify" -import { readSql, writeReason } from "../../../src/altimate/tools/read-only-sql" +import { hardBlockRefusal, readSql, writeReason } from "../../../src/altimate/tools/read-only-sql" describe("shellResidue", () => { const cases: Record = { @@ -137,6 +137,11 @@ describe("other read-only refusals carry the reason", () => { const nested = writeReason("SELECT * FROM query('DROP SCHEMA secret_s')", "duckdb") expect(nested).toContain("(SQL run from a string literal)") expect(nested).not.toContain("secret_s") + // The label is the rule the classifier blocked on: a qualified column named truncate is not TRUNCATE, + // a Unicode-escaped literal holds no hard-deny word, and dynamic SQL is named as such. + expect(writeReason("SELECT q.truncate FROM query('DROP SCHEMA s') q", "duckdb")).toContain("(SQL run from a string literal)") + expect(writeReason("INSERT INTO t VALUES (U&'d!0061t' UESCAPE '!')", "postgres")).toContain("Unicode escape") + expect(writeReason("EXEC sp_x /* drop schema s */", "sqlserver")).toContain("(dynamic SQL") // An unclosed quote holding a blocked word names the quote first. const reason = writeReason("SELECT a FROM t WHERE n = 'do not truncate", "postgres") expect(reason.indexOf("unterminated")).toBeGreaterThan(-1) @@ -147,9 +152,9 @@ describe("other read-only refusals carry the reason", () => { }) test("a SELECT ... INTO the parser cannot read is a write, not a syntax error", () => { - for (const sql of ["SELECT a FROM t INTO OUTFILE '/tmp/x'", "SELECT a FROM t LIMIT 1 INTO @v"]) { + for (const sql of ["SELECT a FROM t INTO OUTFILE '/tmp/x'", "SELECT a FROM t LIMIT 1 INTO @v", "SELECT 0x1.INTO t FROM"]) { const reason = explainWrite(sql, "mysql").reason - expect(reason).toContain("INTO clause") + expect(reason).toContain("write clause") expect(reason).not.toContain("could not read") } // INTO inside a literal or after a dot is not an INTO clause. @@ -157,6 +162,14 @@ describe("other read-only refusals carry the reason", () => { expect(explainWrite("SELECT t.into FROM WHERE", "postgres").reason).toContain("could not read") }) + test("a hard-block refusal claims it cannot be overridden only for a real hard block", () => { + const head = "DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety." + expect(hardBlockRefusal(head, "SELECT 1; DROP DATABASE p", "postgres")).toContain("cannot be overridden") + const open = hardBlockRefusal(head, "SELECT * FROM t WHERE note = 'don't truncate'", "postgres") + expect(open).not.toContain("cannot be overridden") + expect(open).toContain("write a single quote as ''") + }) + test("a refusal that is not about writing stays as it was", () => { expect(writeReason("SELECT 1", "postgres")).toBe("") }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index d4102f0471..9f967a24bb 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -9,6 +9,7 @@ import { readSql } from "../../../src/altimate/tools/read-only-sql" import * as Registry from "../../../src/altimate/native/connections/registry" import { closeScratch } from "../../../src/altimate/native/connections/scratch" import { initTool } from "../tool-fixture" +import { askFor } from "../../../src/altimate/tool-cli/permissions" // A read-only agent denies `sql_execute_write`. Reads must never reach that rule, and when a query does, // the agent must learn why and what to change instead of a raw permission-rule dump it tends to retry. @@ -220,6 +221,17 @@ describe("sql_execute on a read-only agent", () => { ).rejects.toThrow("it is not a read (DELETE)") }) + test("the MCP server and tool CLI write denial is explained, with the --allow-write hint", async () => { + const tool = await initTool(SqlExecuteTool) + const cli = askFor(false) + const ctx = { ...deniedCtx([]), ask: (request: any) => Effect.runPromise(cli(request)) } + const error = await tool + .execute({ query: "SELECT a FROM t 2>/dev/null", warehouse: "guard_db", limit: 10 }, ctx as any) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("`2>/dev/null`") + expect(error).toContain("--allow-write") + }) + test("errors other than a rule denial pass through unchanged", async () => { const tool = await initTool(SqlExecuteTool) const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new Error("rejected by test")) } diff --git a/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts b/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts index 9c8d529ed7..b8e73392e9 100644 --- a/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts +++ b/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts @@ -424,7 +424,9 @@ describe("v0.12.9 adversarial: runner argument validation and the hard deny end test("a write without allowWrite is refused with the retry hint", async () => { const result = await runner.run("sql_execute", { query: "INSERT INTO t VALUES (1)" }) expect(result.status).toBe("error") - expect(result.output).toBe("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.") + // The refusal says why the query counts as a write, then how to enable writes. + expect(result.output).toContain("counts as a write because") + expect(result.output.endsWith("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.")).toBe(true) }) test("a read that quotes 'drop database' is not refused by the permission gate", async () => { From 6fb1ee4fc4dac98a49ae39515228d78be352cf11 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 13:01:19 -0800 Subject: [PATCH 33/58] fix: CLI denial wording, fixed-word hard-block labels - `altimate tool`/MCP write denials open with "Writes are not enabled for this run" instead of claiming the agent may only read. - Hard-block labels take only fixed object kinds, never a name after DROP. - Tests assert the specific reason; JSDoc back on `classifyFallback`. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/sql-classify.ts | 13 +++++++------ packages/opencode/src/altimate/tools/sql-execute.ts | 11 ++++++++--- .../opencode/test/altimate/tool-cli/runner.test.ts | 2 +- .../tools/sql-readonly-guard-explain.test.ts | 6 ++++++ .../test/skill/release-v0.12.9-adversarial.test.ts | 2 +- 5 files changed, 23 insertions(+), 11 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 17730f19df..eb08465da0 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -179,16 +179,17 @@ const HARD_DENY_TYPES = new Set(["DROP DATABASE", "DROP SCHEMA", "TRUNCATE", "TR const HARD_DENY_PATTERN = /^\s*(DROP\s+((EXTERNAL|PLUGGABLE)\s+)?(DATABASE|SCHEMA|CATALOG|NAMESPACE)\b|TRUNCATE(\s+TABLE)?\b)/i -/** - * Fail closed when the parser is unavailable or rejects the input. Lexical - * statement boundaries still enforce hard denies without reading quoted text. - */ -// The label of a hard-deny match (DROP DATABASE, DROP SCHEMA, ..., TRUNCATE), from the matched text only. +// The label of a hard-deny match (DROP DATABASE, DROP SCHEMA, ..., TRUNCATE): a match that starts with +// DROP and a fixed object kind is that DROP; any other is TRUNCATE. Only fixed words reach the label. function hardDenyLabel(match: string): string { - const drop = /\bDROP\s+(?:(?:EXTERNAL|PLUGGABLE)\s+)?(\w+)/i.exec(match) + const drop = /^\W*DROP\s+(?:(?:EXTERNAL|PLUGGABLE)\s+)?(DATABASE|SCHEMA|CATALOG|NAMESPACE)\b/i.exec(match) return drop ? `DROP ${drop[1].toUpperCase()}` : "TRUNCATE" } +/** + * Fail closed when the parser is unavailable or rejects the input. Lexical + * statement boundaries still enforce hard denies without reading quoted text. + */ function classifyFallback( sql: string, dialect?: string, diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 46d4ea1e94..71e41ba17d 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -303,7 +303,7 @@ export const SqlExecuteTool = Tool.define( }, }) } catch (error) { - const explain = (readOnly: boolean) => + const explain = (readOnly: boolean, cli = false) => deniedWriteMessage({ sql, dialects, @@ -312,9 +312,10 @@ export const SqlExecuteTool = Tool.define( scratch: isScratch(args.warehouse), warehouseGiven: !!args.warehouse, readOnly, + cli, }) // The MCP server and `altimate tool` refuse writes unless --allow-write was given. - if (error instanceof WriteDeniedError) throw new Error(`${explain(true)} ${error.message}`) + if (error instanceof WriteDeniedError) throw new Error(`${explain(true, true)} ${error.message}`) if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error const rules: Array<{ pattern?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] // Rules apply last-match-wins: the agent is read-only when the last catch-all rule denies and @@ -776,9 +777,13 @@ export function deniedWriteMessage(input: { scratch: boolean warehouseGiven: boolean readOnly?: boolean + /** Refused because this MCP server or tool CLI run was started without --allow-write. */ + cli?: boolean }): string { const readOnly = input.readOnly !== false - const head = readOnly + const head = input.cli + ? "sql_execute did not run this query. Writes are not enabled for this run, and the query counts as a write because" + : readOnly ? "sql_execute did not run this query. This agent may only read (write permission is denied), and the query counts as a write because" : "sql_execute did not run this query. A sql_execute_write rule denies it, and the query counts as a write because" if (input.jinja) { diff --git a/packages/opencode/test/altimate/tool-cli/runner.test.ts b/packages/opencode/test/altimate/tool-cli/runner.test.ts index a7f0739f98..4e06203882 100644 --- a/packages/opencode/test/altimate/tool-cli/runner.test.ts +++ b/packages/opencode/test/altimate/tool-cli/runner.test.ts @@ -137,7 +137,7 @@ describe("tool run", () => { const result = await runner.run("sql_execute", { query: "CREATE TABLE t (a int)" }) expect(result.status).toBe("error") // The refusal says why the query counts as a write, then how to enable writes. - expect(result.output).toContain("counts as a write because") + expect(result.output).toContain("Writes are not enabled for this run, and the query counts as a write because it is not a read (CREATE TABLE)") expect(result.output.endsWith("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.")).toBe(true) }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index c80bb28c8c..b8076519e5 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -142,6 +142,12 @@ describe("other read-only refusals carry the reason", () => { expect(writeReason("SELECT q.truncate FROM query('DROP SCHEMA s') q", "duckdb")).toContain("(SQL run from a string literal)") expect(writeReason("INSERT INTO t VALUES (U&'d!0061t' UESCAPE '!')", "postgres")).toContain("Unicode escape") expect(writeReason("EXEC sp_x /* drop schema s */", "sqlserver")).toContain("(dynamic SQL") + // Only fixed words reach the label: a name after DROP inside a TRUNCATE target is not echoed. + const target = writeReason("SELECT 1 THEN TRUNCATE IDENTIFIER(drop secret_tbl);", "postgres") + expect(target).toContain("(TRUNCATE)") + expect(target).not.toMatch(/secret_tbl/i) + // SQL Server's query() is XQuery, so a qualified column named truncate beside it is a read. + expect(classifyAndCheck("SELECT q.truncate FROM query('DROP SCHEMA s') q", "sqlserver")).toMatchObject({ queryType: "read", blocked: false }) // An unclosed quote holding a blocked word names the quote first. const reason = writeReason("SELECT a FROM t WHERE n = 'do not truncate", "postgres") expect(reason.indexOf("unterminated")).toBeGreaterThan(-1) diff --git a/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts b/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts index b8e73392e9..060fe6ce8f 100644 --- a/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts +++ b/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts @@ -425,7 +425,7 @@ describe("v0.12.9 adversarial: runner argument validation and the hard deny end const result = await runner.run("sql_execute", { query: "INSERT INTO t VALUES (1)" }) expect(result.status).toBe("error") // The refusal says why the query counts as a write, then how to enable writes. - expect(result.output).toContain("counts as a write because") + expect(result.output).toContain("Writes are not enabled for this run, and the query counts as a write because it is not a read (INSERT)") expect(result.output.endsWith("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.")).toBe(true) }) From b77eeec9b92030927eaa5da47b20b374f51e635d Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 13:18:53 -0800 Subject: [PATCH 34/58] fix: name the clearest write and the warehouse hint only where it helps - With no warehouse, the "pass warehouse" hint covers the write branch too, except on the dbt route, where it would move the query off dbt. - The reason prefers a dialect that reads the text over a parse error. - The parse-error reason no longer ends in four dots (tested). Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/sql-classify.ts | 2 +- .../src/altimate/tools/sql-execute.ts | 22 ++++++++++++++----- .../altimate/tools/sql-readonly-guard.test.ts | 16 ++++++++++++++ 3 files changed, 34 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index eb08465da0..5aa38bbc08 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -698,7 +698,7 @@ export function explainWrite( `the ${dialect ?? "generic"} SQL parser could not read ${where} (${parserMessage(result.parseError)}), so it cannot be proven read-only. ` + "The position is approximate: it counts within that statement, with each comment read as one space. " + 'Fix the syntax there: quote identifiers that contain spaces or are keywords ("order date"), ' + - "check the clause order, and replace any placeholder text such as ..." + "check the clause order, and replace any placeholder text (...)" ) } // The checks below follow classifySql's conditions. diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 71e41ba17d..4f5be01e06 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -313,6 +313,7 @@ export const SqlExecuteTool = Tool.define( warehouseGiven: !!args.warehouse, readOnly, cli, + dbt: target?.dbt === true, }) // The MCP server and `altimate tool` refuse writes unless --allow-write was given. if (error instanceof WriteDeniedError) throw new Error(`${explain(true, true)} ${error.message}`) @@ -779,6 +780,8 @@ export function deniedWriteMessage(input: { readOnly?: boolean /** Refused because this MCP server or tool CLI run was started without --allow-write. */ cli?: boolean + /** The default route is dbt: passing a warehouse would also move the query off dbt, so no hint names it. */ + dbt?: boolean }): string { const readOnly = input.readOnly !== false const head = input.cli @@ -792,22 +795,31 @@ export function deniedWriteMessage(input: { if (input.mongo) { return `${head} it is a MongoDB write (a write command, or an aggregate with a $out or $merge stage). Use a read command (find, aggregate, countDocuments, distinct) instead.` } - const dialect = input.dialects.find((d) => classifyAndCheck(input.sql, d).queryType === "write") + // Prefer a dialect that reads the text and names a concrete write over one that cannot parse it. + const writing = input.dialects.filter((d) => classifyAndCheck(input.sql, d).queryType === "write") + const dialect = writing.find((d) => !explainWrite(input.sql, d).unreadable) ?? writing[0] const { reason, unreadable, unavailable } = explainWrite(input.sql, dialect) + // Without a warehouse, a query that only some reachable dialects call a write may be a read in the real one. + const someRead = input.dialects.some((d) => { + const result = classifyAndCheck(input.sql, d) + return result.queryType === "read" && !result.blocked + }) + const dialectHint = + !input.warehouseGiven && !input.dbt && input.dialects.length > 1 && (unreadable || someRead) + ? " No warehouse was given, so the query was read in every dialect it could reach; pass warehouse to read it in that warehouse's dialect only." + : "" const next = unavailable ? UNAVAILABLE_NEXT_STEP : unreadable ? "Fix the query and call sql_execute again; the same text will be refused again." + (readOnly ? "" : " The configured sql_execute_write rules may still deny it once it parses.") + - (input.warehouseGiven || input.dialects.length < 2 - ? "" - : " No warehouse was given, so the query was read in every dialect it could reach; pass warehouse to read it in that warehouse's dialect only.") + dialectHint : !readOnly ? "Change it to a statement the configured sql_execute_write rules allow, or ask the user to change the rules." : input.scratch ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission, each call without reads; other statements (ATTACH, COPY, INSTALL, SET, ...) need write permission." : "Rewrite it as a single read (SELECT, or WITH ... SELECT). To keep an intermediate result, store it in scratch with sql_materialize if that tool is available." - return `${head} ${reason}. ${next}` + return `${head} ${reason}. ${next}${unreadable ? "" : dialectHint}` } // altimate_change end diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 9f967a24bb..86a8f01f4a 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -169,6 +169,7 @@ describe("sql_execute on a read-only agent", () => { const { error } = await run("SELECT Order Date FROM orders WHERE Order Date > '2020-01-01'") expect(error).toMatch(/sqlite SQL parser could not read it \(.*line 1, column \d+/) expect(error).toContain("Fix the query") + expect(error).not.toContain("....") }) test("a hard block names its rule, or the open quote that made a word count", async () => { @@ -312,4 +313,19 @@ describe("denied write message branches", () => { expect(deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((" })).not.toContain("pass warehouse") expect(deniedWriteMessage({ ...base, sql: "DELETE FROM t WHERE ((", readOnly: false })).toContain("may still deny it") }) + + test("a write in only one reachable dialect suggests passing a warehouse", () => { + const split = { ...base, sql: "SELECT t.update FROM t", dialects: ["postgres", "clickhouse"], warehouseGiven: false } + expect(deniedWriteMessage(split)).toContain("pass warehouse") + expect(deniedWriteMessage({ ...split, warehouseGiven: true })).not.toContain("pass warehouse") + // A write in every dialect gets no hint, and on the dbt route a warehouse would also move the query off dbt. + expect(deniedWriteMessage({ ...split, sql: "DELETE FROM t" })).not.toContain("pass warehouse") + expect(deniedWriteMessage({ ...split, dbt: true })).not.toContain("pass warehouse") + }) + + test("the reason comes from a dialect that reads the text when one does", () => { + const message = deniedWriteMessage({ ...base, sql: "SELECT 1 DELETE FROM t", dialects: ["postgres", "sqlserver"], warehouseGiven: false }) + expect(message).toContain("DELETE") + expect(message).not.toContain("could not read") + }) }) From da71cbaf6405d13e7239732bbe235cfd98d02656 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 13:22:58 -0800 Subject: [PATCH 35/58] fix: one parse per dialect on denial; test the missing-parser path - Word-scan and dynamic-SQL labels give examples ("such as ..."). - The no-warehouse hint says the reachable dialects disagree; each dialect is classified and explained once. - A subprocess test stubs a missing parser and checks the reason. - The Jinja test reuses its first run. Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/sql-classify.ts | 4 +-- .../src/altimate/tools/sql-execute.ts | 30 +++++++++------- .../altimate/tools/sql-comment-safety.test.ts | 2 +- .../tools/sql-readonly-guard-explain.test.ts | 36 +++++++++++++++++++ .../altimate/tools/sql-readonly-guard.test.ts | 2 +- 5 files changed, 58 insertions(+), 16 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 5aa38bbc08..50ac4fb154 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -211,7 +211,7 @@ function classifyFallback( const lexical = tokenizeSql(sql, dialect) if (!lexical.complete) { // Escapes decoded too: dynamic SQL may run a literal such as '\x44ROP SCHEMA s'. - if (mentionsHardDenyAnywhere(sql)) cause ??= "DROP DATABASE, DROP SCHEMA or TRUNCATE words in text that cannot be fully read" + if (mentionsHardDenyAnywhere(sql)) cause ??= "hard-blocked words (such as DROP DATABASE or TRUNCATE) in text that cannot be fully read" } else { // Read with certainty: the statement words in code (literals and comments masked, each quoted // identifier a placeholder name, so DROP/**/SCHEMA reads as DROP SCHEMA) decide too, since T-SQL runs `SELECT 1 DROP DATABASE x` @@ -232,7 +232,7 @@ function classifyFallback( // "exec"('...') and [exec]('...') count as calls. const dynamic = DYNAMIC_SQL.test(maskSql(lexical.tokens)) || DYNAMIC_SQL.test(maskSql(lexical.tokens, true)) if (dynamic && mentionsHardDenyAnywhere(sql)) - cause ??= "dynamic SQL (EXEC, PREPARE or DO) with DROP DATABASE, DROP SCHEMA or TRUNCATE in its text" + cause ??= "dynamic SQL (EXEC, PREPARE or DO) with hard-blocked words (such as DROP DATABASE or TRUNCATE) in its text" } return { queryType: "write", blocked: cause !== undefined, ...(cause && { cause }) } } diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 4f5be01e06..13e97245b2 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -795,19 +795,25 @@ export function deniedWriteMessage(input: { if (input.mongo) { return `${head} it is a MongoDB write (a write command, or an aggregate with a $out or $merge stage). Use a read command (find, aggregate, countDocuments, distinct) instead.` } - // Prefer a dialect that reads the text and names a concrete write over one that cannot parse it. - const writing = input.dialects.filter((d) => classifyAndCheck(input.sql, d).queryType === "write") - const dialect = writing.find((d) => !explainWrite(input.sql, d).unreadable) ?? writing[0] - const { reason, unreadable, unavailable } = explainWrite(input.sql, dialect) - // Without a warehouse, a query that only some reachable dialects call a write may be a read in the real one. - const someRead = input.dialects.some((d) => { - const result = classifyAndCheck(input.sql, d) - return result.queryType === "read" && !result.blocked - }) + // Classify once per dialect. Prefer a dialect that reads the text and names a concrete write over one that + // cannot parse it. + const results = input.dialects.map((d) => ({ dialect: d, ...classifyAndCheck(input.sql, d) })) + const writing = results + .filter((result) => result.queryType === "write") + .map((result) => ({ dialect: result.dialect, explained: explainWrite(input.sql, result.dialect) })) + const chosen = writing.find((entry) => !entry.explained.unreadable) ?? writing[0] + const { reason, unreadable, unavailable } = chosen?.explained ?? explainWrite(input.sql, undefined) + // Without a warehouse (and off the dbt route, where a warehouse also moves the query off dbt), a query the + // reachable dialects disagree on, or cannot read, may be fine in the real warehouse's dialect. + const disagree = results.some((result) => result.queryType === "read" && !result.blocked) const dialectHint = - !input.warehouseGiven && !input.dbt && input.dialects.length > 1 && (unreadable || someRead) - ? " No warehouse was given, so the query was read in every dialect it could reach; pass warehouse to read it in that warehouse's dialect only." - : "" + input.warehouseGiven || input.dbt || input.dialects.length < 2 + ? "" + : disagree + ? " No warehouse was given and the reachable dialects disagree on whether this is a write; pass warehouse to check it in that warehouse's dialect only." + : unreadable + ? " No warehouse was given, so the query was checked in every dialect it could reach; pass warehouse to check it in that warehouse's dialect only." + : "" const next = unavailable ? UNAVAILABLE_NEXT_STEP : unreadable diff --git a/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts b/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts index 06657ae143..c3752dd339 100644 --- a/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts +++ b/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts @@ -266,7 +266,7 @@ test("on the dbt route, Jinja in a comment or literal is a write, and a hard-den const drop = await run("SELECT 1 AS x -- {% do run_query('DROP SCHEMA prod CASCADE') %}") await expect(drop.result).rejects.toThrow("blocked for safety") // Blocked by the Jinja word scan alone (the SQL reads the words as a comment): the error says why. - await expect((await run("SELECT 1 AS x -- {% do run_query('DROP SCHEMA prod CASCADE') %}")).result).rejects.toThrow("dbt renders") + await expect(drop.result).rejects.toThrow("dbt renders") // A Jinja comment removes text, which can expose a statement the SQL lexing reads as a literal. const hidden = await run("SELECT 'x' /* {# */ || ' #} */) AS q ; DROP SCHEMA s CASCADE ; SELECT 1 -- '") await expect(hidden.result).rejects.toThrow("blocked for safety") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index b8076519e5..1b044f2b36 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -1,4 +1,7 @@ import { describe, expect, test } from "bun:test" +import { mkdtempSync, rmSync, writeFileSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" import { classifyAndCheck, explainWrite, shellResidue } from "../../../src/altimate/tools/sql-classify" import { hardBlockRefusal, readSql, writeReason } from "../../../src/altimate/tools/read-only-sql" @@ -176,6 +179,39 @@ describe("other read-only refusals carry the reason", () => { expect(open).toContain("write a single quote as ''") }) + test("a missing parser is reported as unavailable, not as a syntax error", async () => { + // The parser binding is read once at import, so stub it in a fresh process run outside the package + // (its test preload loads the classifier first; mock.module also leaks across files in one process). + const dir = mkdtempSync(join(tmpdir(), "guard-unavailable-")) + const src = join(import.meta.dir, "../../../src/altimate/tools") + writeFileSync( + join(dir, "unavailable.test.ts"), + `import { expect, mock, test } from "bun:test" +mock.module("@altimateai/altimate-core", () => ({})) +test("unavailable", async () => { + const { explainWrite, UNAVAILABLE_NEXT_STEP } = await import(${JSON.stringify(join(src, "sql-classify"))}) + const { writeReason } = await import(${JSON.stringify(join(src, "read-only-sql"))}) + const explained = explainWrite("SELECT 1", "postgres") + expect(explained.unavailable).toBe(true) + expect(explained.reason).not.toContain("could not read") + expect(writeReason("SELECT 1", "postgres")).toContain(UNAVAILABLE_NEXT_STEP) +}) +`, + ) + try { + const run = Bun.spawnSync(["bun", "test", "./unavailable.test.ts"], { + cwd: dir, + stdout: "pipe", + stderr: "pipe", + }) + const output = run.stdout.toString() + run.stderr.toString() + expect(output).toContain("1 pass") + expect(run.exitCode).toBe(0) + } finally { + rmSync(dir, { recursive: true, force: true }) + } + }, 60_000) + test("a refusal that is not about writing stays as it was", () => { expect(writeReason("SELECT 1", "postgres")).toBe("") }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 86a8f01f4a..31b5b0bf96 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -316,7 +316,7 @@ describe("denied write message branches", () => { test("a write in only one reachable dialect suggests passing a warehouse", () => { const split = { ...base, sql: "SELECT t.update FROM t", dialects: ["postgres", "clickhouse"], warehouseGiven: false } - expect(deniedWriteMessage(split)).toContain("pass warehouse") + expect(deniedWriteMessage(split)).toContain("reachable dialects disagree on whether this is a write; pass warehouse") expect(deniedWriteMessage({ ...split, warehouseGiven: true })).not.toContain("pass warehouse") // A write in every dialect gets no hint, and on the dbt route a warehouse would also move the query off dbt. expect(deniedWriteMessage({ ...split, sql: "DELETE FROM t" })).not.toContain("pass warehouse") From c52a33c8ab959cef18ef259e4ae7708e4763f3b8 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 13:47:37 -0800 Subject: [PATCH 36/58] fix: streamline SQL refusal explanations and stabilize parser test --- .../opencode/src/altimate/tools/sql-execute.ts | 16 +++++++++++----- .../tools/sql-readonly-guard-explain.test.ts | 7 ++++--- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 13e97245b2..2421a3e228 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -798,11 +798,17 @@ export function deniedWriteMessage(input: { // Classify once per dialect. Prefer a dialect that reads the text and names a concrete write over one that // cannot parse it. const results = input.dialects.map((d) => ({ dialect: d, ...classifyAndCheck(input.sql, d) })) - const writing = results - .filter((result) => result.queryType === "write") - .map((result) => ({ dialect: result.dialect, explained: explainWrite(input.sql, result.dialect) })) - const chosen = writing.find((entry) => !entry.explained.unreadable) ?? writing[0] - const { reason, unreadable, unavailable } = chosen?.explained ?? explainWrite(input.sql, undefined) + let chosen: ReturnType | undefined + for (const result of results) { + if (result.queryType !== "write") continue + const explanation = explainWrite(input.sql, result.dialect) + if (!explanation.unreadable) { + chosen = explanation + break + } + chosen ??= explanation + } + const { reason, unreadable, unavailable } = chosen ?? explainWrite(input.sql, undefined) // Without a warehouse (and off the dbt route, where a warehouse also moves the query off dbt), a query the // reachable dialects disagree on, or cannot read, may be fine in the real warehouse's dialect. const disagree = results.some((result) => result.queryType === "read" && !result.blocked) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 1b044f2b36..6f8e9995d6 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -199,14 +199,15 @@ test("unavailable", async () => { `, ) try { - const run = Bun.spawnSync(["bun", "test", "./unavailable.test.ts"], { + const run = Bun.spawnSync([process.execPath, "test", "./unavailable.test.ts"], { cwd: dir, stdout: "pipe", stderr: "pipe", }) const output = run.stdout.toString() + run.stderr.toString() - expect(output).toContain("1 pass") - expect(run.exitCode).toBe(0) + // Bun can crash during cleanup after printing a complete test summary. + expect(output).toMatch(/^\s*[1-9]\d* pass\s*$/m) + expect(output).toMatch(/^\s*0 fail\s*$/m) } finally { rmSync(dir, { recursive: true, force: true }) } From 6caa2a44c13f22c2407ee1ec8902b0abff546d0f Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 14:13:45 -0800 Subject: [PATCH 37/58] test: pin qualified keyword-named functions as calls; keep tests valid after the parser fix - `t.EXEC(...)`, `t.DELETE(...)` are user function calls, reads like any other. - The token-text parser test drops `len(DISTINCT f(...))`, which the engine fix makes parse. - Linear-time checks take each size's fastest of three runs, so one stall is not growth. Co-Authored-By: Claude Opus 5.5 --- .../tools/sql-readonly-guard-explain.test.ts | 17 +++++++++++------ .../altimate/tools/sql-readonly-guard.test.ts | 10 ++++++++++ 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 6f8e9995d6..5ac63f0ae9 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -38,13 +38,18 @@ describe("shellResidue", () => { }) // Timing compares two sizes on the same host instead of a wall-clock bound: linear work grows about 8x - // from 1x to 8x input, quadratic about 64x. + // from 1x to 8x input, quadratic about 64x. Each size takes its fastest of three runs, so one scheduler + // stall on a loaded host does not read as growth. const growth = (build: (n: number) => string, n: number) => { const time = (sql: string) => { - const start = performance.now() - explainWrite(sql, "postgres") - shellResidue(sql, "postgres") - return performance.now() - start + let best = Infinity + for (let run = 0; run < 3; run++) { + const start = performance.now() + explainWrite(sql, "postgres") + shellResidue(sql, "postgres") + best = Math.min(best, performance.now() - start) + } + return best } time(build(n)) // warm up return time(build(n * 8)) / Math.max(time(build(n)), 1) @@ -261,7 +266,7 @@ describe("explainWrite", () => { expect(reason).not.toContain("Set") expect(reason).not.toContain("a token") for (const sql of [ - "SELECT len(DISTINCT customer_secret_name(a)) FROM t", + "SELECT customer_secret_name(a FROM t", "SELECT customer_secret_name customer_x customer_y FROM t", "SELECT a FROM customer_secret_table WHERE (((", "SELECT CAST(a AS int 'customer_it''s secret') FROM t", diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 31b5b0bf96..80b166c8fe 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -91,6 +91,16 @@ describe("reads are classified as reads in every dialect", () => { } }) + test("a schema-qualified function named like a statement word is a function call, like any user function", () => { + // Engines read a keyword after a dot as a name. User function calls are reads with or without a qualifier. + for (const dialect of ["sqlserver", "postgres"]) { + for (const sql of ["SELECT run_sql('DELETE FROM t')", "SELECT dbo.run_sql('DELETE FROM t')", "SELECT t.DELETE('x')"]) { + expect(isRead(sql, dialect)).toBe(true) + } + } + expect(isRead("SELECT t.EXEC('DROP TABLE z')", "sqlserver")).toBe(true) + }) + test("DESCRIBE, SHOW and PRAGMA metadata reads", () => { for (const sql of ["DESCRIBE orders", "SHOW TABLES", "SHOW COLUMNS FROM orders"]) expect(isRead(sql, "duckdb")).toBe(true) expect(isRead("PRAGMA table_info('orders')", "sqlite")).toBe(true) From bd397d8a9a5b88a4a47b39b33fed510832f79e4d Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 14:35:35 -0800 Subject: [PATCH 38/58] fix: preserve SQL refusal telemetry classes and explain unsupported read shapes --- .../src/altimate/tools/read-only-sql.ts | 15 ++-- .../src/altimate/tools/sql-classify.ts | 15 ++-- .../src/altimate/tools/sql-execute.ts | 10 +-- .../test/altimate/tool-cli/runner.test.ts | 2 +- .../tools/sql-execute-query-from.test.ts | 8 ++ .../tools/sql-readonly-guard-explain.test.ts | 4 + .../altimate/tools/sql-readonly-guard.test.ts | 74 +++++++++++++++++-- .../skill/release-v0.12.9-adversarial.test.ts | 2 +- 8 files changed, 105 insertions(+), 25 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 616816cde5..b66f29d257 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -85,7 +85,7 @@ export function hardBlockRefusal(head: string, sql: string, dialect?: string): s } /** Why sql is refused as a read, as a sentence to append to a refusal: a hard block, the classifier's reason for a write, - * or, for a read that only the stricter statement-word list refuses, that word (no SQL text). Empty otherwise. */ + * a read shape that cannot be embedded, or a statement word refused by the stricter list. Empty for accepted reads. */ export function writeReason(sql: string, dialect?: string): string { const { queryType, blocked } = classifyAndCheck(sql, dialect) if (blocked) { @@ -94,7 +94,7 @@ export function writeReason(sql: string, dialect?: string): string { const index = statements.length > 1 ? statements.findIndex((statement) => classifyAndCheck(statement, dialect).blocked) : -1 const where = index >= 0 ? `statement ${index + 1} of ${statements.length} is` : "it holds" const cause = hardBlockCause(index >= 0 ? statements[index] : sql, dialect) - const hard = ` It is refused because ${where} a hard-blocked statement (${cause}); hard-blocked statements never run and cannot be allowed.` + const hard = ` It is refused because ${where} a hard-blocked statement (${cause}); hard-blocked statements never run, regardless of permission.` // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone, inside the // unreadable text or outside it: name the unreadable text first, since fixing it may be the whole fix. const untilClosed = @@ -105,13 +105,16 @@ export function writeReason(sql: string, dialect?: string): string { : ` It counts as a write because ${explainWrite(sql, dialect).reason}.${untilClosed}` } if (queryType === "write") { - const { reason, unavailable } = explainWrite(sql, dialect) - return ` It counts as a write because ${reason}.${unavailable ? ` ${UNAVAILABLE_NEXT_STEP}` : ""}` + const { reason, unreadable, unavailable } = explainWrite(sql, dialect) + const head = unreadable ? "It counts as a write because" : "It falls outside the read-only permission because" + return ` ${head} ${reason}.${unavailable ? ` ${UNAVAILABLE_NEXT_STEP}` : ""}` } // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. const body = readOnlyBody(sql, dialect)?.body - if (!body || !/^(SELECT|WITH)\b/i.test(body)) return "" + if (!body || !/^(SELECT|WITH)\b/i.test(body)) { + return " Invalid query shape here: send a single SELECT or WITH query that can be embedded." + } const [statement, replace] = wordPatterns(dialect) const word = (statement.exec(body) ?? replace.exec(body))?.[0] - return word ? ` It contains the statement word ${word.toUpperCase()} outside a literal or comment; quote it if it is a column name.` : "" + return word ? ` It contains the statement word ${word.toUpperCase()} outside a literal or comment, so the read-only permission does not cover it; quote it if it is a column name.` : "" } diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 50ac4fb154..98f0484a38 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -640,6 +640,12 @@ function parserMessage(message: string): string { return `${prefix}${detail}`.trim() || "parse error" } +function batchKeywordExplanation(dialect?: string): string { + return /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") + ? "SQL Server runs a statement there even without a separator" + : "this dialect is not modeled, so it may run as a statement" +} + /** * Why classifyAndCheck treats this SQL as a write, in words an agent can act on: shell residue to * remove, the parser error and its position, or the first statement that is not a read. `unreadable` @@ -660,7 +666,7 @@ export function explainWrite( return unreadable("it contains an executable comment (/*! ... */), which some engines run as SQL; remove it or use a plain comment") } return unreadable( - "it has unterminated or unsupported quoted text or comments, so it cannot be proven read-only. Check that every " + + "it has unterminated or unsupported quoted text or comments, so it cannot be proven read-only. To fix the syntax, check that every " + "quote and comment is closed; inside a string literal, write a single quote as ''" ) } @@ -684,7 +690,7 @@ export function explainWrite( if (result.parseError && batchKeyword) { return writes( `${where} holds the statement keyword ${batchKeyword.trim().split(/\s+/)[0].toUpperCase()} outside a literal or comment; ` + - `${/^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") ? "SQL Server runs a statement there even without a separator" : "this dialect is not modeled, so it may run as a statement"}` + + `${batchKeywordExplanation(dialect)}` + "; run each statement in its own call, or quote it if it is a column name", ) } @@ -734,12 +740,9 @@ export function explainWrite( } const keyword = batchedStatement(masked, dialect) if (keyword) { - const engine = /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") - ? "SQL Server runs a statement there even without a separator" - : "this dialect is not modeled, so it may run as a statement" return writes( `${where} holds the statement keyword ${keyword.trim().split(/\s+/)[0].toUpperCase()} outside a literal or comment; ` + - `${engine}; quote it if it is a column name`, + `${batchKeywordExplanation(dialect)}; quote it if it is a column name`, ) } if (/^snowflake$/i.test(dialect ?? "") && masked.includes("->>")) return writes(`${where} chains statements with ->>`) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 2421a3e228..8cdb85049c 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -259,13 +259,13 @@ export const SqlExecuteTool = Tool.define( if (blockedIn >= 0) throw new Error(hardBlockRefusal(head, sql, dialects[blockedIn])) if (jinja) throw new Error( - `${head} It contains Jinja, which dbt renders before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + + `${head} This cannot be overridden by a permission rule. dbt renders Jinja before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + "TRUNCATE words count wherever they sit, even in a literal or comment. Remove those words, or send plain SQL without Jinja.", ) - throw new Error(`${head} This cannot be overridden.`) + throw new Error(`${head} This cannot be overridden by a permission rule.`) } if (budget && queryType !== "read") { - throw new Error("Batched queries must be read-only; run a write as its own sql_execute call.") + throw new Error("Batched queries must be read-only. To use write permission, run a write as its own sql_execute call.") } const parseError = "parseError" in classification ? classification.parseError : undefined if (!mongo && queryType === "read") { @@ -785,10 +785,10 @@ export function deniedWriteMessage(input: { }): string { const readOnly = input.readOnly !== false const head = input.cli - ? "sql_execute did not run this query. Writes are not enabled for this run, and the query counts as a write because" + ? "sql_execute did not run this query. Write permission is disabled for this run, and the query counts as a write because" : readOnly ? "sql_execute did not run this query. This agent may only read (write permission is denied), and the query counts as a write because" - : "sql_execute did not run this query. A sql_execute_write rule denies it, and the query counts as a write because" + : "sql_execute did not run this query. A sql_execute_write permission rule denies it, and the query counts as a write because" if (input.jinja) { return `${head} it contains Jinja ({{ }}, {% %} or {# #}), which dbt renders and runs before the SQL. Send plain SQL without Jinja.` } diff --git a/packages/opencode/test/altimate/tool-cli/runner.test.ts b/packages/opencode/test/altimate/tool-cli/runner.test.ts index 4e06203882..5fd13bcd34 100644 --- a/packages/opencode/test/altimate/tool-cli/runner.test.ts +++ b/packages/opencode/test/altimate/tool-cli/runner.test.ts @@ -137,7 +137,7 @@ describe("tool run", () => { const result = await runner.run("sql_execute", { query: "CREATE TABLE t (a int)" }) expect(result.status).toBe("error") // The refusal says why the query counts as a write, then how to enable writes. - expect(result.output).toContain("Writes are not enabled for this run, and the query counts as a write because it is not a read (CREATE TABLE)") + expect(result.output).toContain("Write permission is disabled for this run, and the query counts as a write because it is not a read (CREATE TABLE)") expect(result.output.endsWith("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.")).toBe(true) }) diff --git a/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts b/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts index 71173ada88..d1aa221be7 100644 --- a/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts +++ b/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts @@ -215,6 +215,14 @@ describe("sql_execute generated reads", () => { expect(dispatch).not.toHaveBeenCalled() }) + test.each(["SELECT 1; SELECT 2", "SHOW TABLES"])("explains the refused source shape %s", async (sql) => { + const tool = await initTool(SqlExecuteTool) + await expect(tool.execute({ query_from: { ...source, sql }, warehouse: "analytics" }, ctx)).rejects.toThrow( + "send a single SELECT or WITH query", + ) + expect(dispatch).not.toHaveBeenCalled() + }) + for (const sql of [ "DELETE FROM orders", "CREATE TEMP TABLE generated AS SELECT 1", diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 5ac63f0ae9..c7db6179fd 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -218,6 +218,10 @@ test("unavailable", async () => { } }, 60_000) + test.each(["SELECT 1; SELECT 2", "SHOW TABLES"])("explains the unsupported read shape %s", (sql) => { + expect(writeReason(sql, "postgres")).toContain("send a single SELECT or WITH query") + }) + test("a refusal that is not about writing stays as it was", () => { expect(writeReason("SELECT 1", "postgres")).toBe("") }) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 80b166c8fe..89dbd75bdf 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -5,11 +5,15 @@ import { PermissionNext } from "../../../src/permission/next" import { SessionID, MessageID } from "../../../src/session/schema" import { SqlExecuteTool, deniedWriteMessage } from "../../../src/altimate/tools/sql-execute" import { classifyAndCheck, isScratchSafeWrite } from "../../../src/altimate/tools/sql-classify" -import { readSql } from "../../../src/altimate/tools/read-only-sql" +import { hardBlockRefusal, readSql } from "../../../src/altimate/tools/read-only-sql" import * as Registry from "../../../src/altimate/native/connections/registry" import { closeScratch } from "../../../src/altimate/native/connections/scratch" import { initTool } from "../tool-fixture" -import { askFor } from "../../../src/altimate/tool-cli/permissions" +import { askFor, denied } from "../../../src/altimate/tool-cli/permissions" + +import { Telemetry } from "../../../src/altimate/telemetry" +import { materialize } from "../../../src/altimate/tools/sql-materialize" +import { checkEngineRead } from "../../../src/altimate/mcp-server/workspace" // A read-only agent denies `sql_execute_write`. Reads must never reach that rule, and when a query does, // the agent must learn why and what to change instead of a raw permission-rule dump it tends to retry. @@ -255,6 +259,64 @@ describe("sql_execute on a read-only agent", () => { describe("denied write message branches", () => { const base = { sql: "SELECT 1", dialects: ["postgres"], jinja: false, mongo: false, scratch: false, warehouseGiven: true } + test("refusal messages keep their telemetry error class", async () => { + const write = { ...base, sql: "DELETE FROM orders" } + const hard = "DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety." + const scoped = { ...write, readOnly: false } + const hint = denied("sql_execute_write").message + const refusal = async (fn: () => unknown) => { + try { + await fn() + } catch (error) { + if (error instanceof Error) return error.message + throw error + } + throw new Error("Expected a SQL refusal") + } + const tool = await initTool(SqlExecuteTool) + const cases = [ + ["agent", deniedWriteMessage(write), "permission"], + ["pattern rule", deniedWriteMessage(scoped), "permission"], + ["scratch", deniedWriteMessage({ ...write, scratch: true }), "permission"], + ["CLI opening", deniedWriteMessage({ ...write, cli: true }), "permission"], + ["CLI hint", hint, "permission"], + ["CLI refusal with hint", deniedWriteMessage({ ...write, cli: true }) + " " + hint, "permission"], + ["Jinja", deniedWriteMessage({ ...scoped, jinja: true }), "permission"], + ["MongoDB", deniedWriteMessage({ ...scoped, mongo: true }), "permission"], + ["SQL parser error", deniedWriteMessage({ ...scoped, sql: "SELECT Order Date FROM orders" }), "parse_error"], + ["shell residue", deniedWriteMessage({ ...scoped, sql: "SELECT 1 2>/dev/null" }), "parse_error"], + ["open quote", deniedWriteMessage({ ...scoped, sql: "SELECT 'abc" }), "parse_error"], + ["hard block", hardBlockRefusal(hard, "TRUNCATE TABLE orders", "postgres"), "permission"], + ["hard-blocked open quote", hardBlockRefusal(hard, "SELECT 'truncate", "postgres"), "parse_error"], + ["hard-blocked comment", hardBlockRefusal(hard, "SELECT 1 /*! + 1 */", "mysql"), "permission"], + ["sql_check", await refusal(() => readSql(write.sql, "postgres")), "permission"], + ["sql_check statement word", await refusal(() => readSql("SELECT x AS load FROM t", "postgres")), "permission"], + ["sql_check query shape", await refusal(() => readSql("SHOW TABLES", "postgres")), "validation"], + [ + "query_from source", + await refusal(() => tool.execute({ + query_from: { warehouse: "guard_db", sql: write.sql }, + warehouse: "guard_db", + limit: 10, + }, deniedCtx([]) as any)), + "permission", + ], + [ + "sql_materialize", + await refusal(() => materialize({ source_warehouse: "guard_db", sql: write.sql, target_table: "guard_test" })), + "permission", + ], + [ + "MCP workspace", + await refusal(() => checkEngineRead("postgresql_execute_database_query", { query: write.sql })), + "permission", + ], + ] + expect(cases.map(([label, message]) => [label, Telemetry.classifyError(message)])).toEqual( + cases.map(([label, , expected]) => [label, expected]), + ) + }) + test("Jinja asks for plain SQL", () => { expect(deniedWriteMessage({ ...base, sql: "SELECT * FROM {{ ref('x') }}", jinja: true })).toContain("Send plain SQL without Jinja") }) @@ -265,7 +327,7 @@ describe("denied write message branches", () => { test("a pattern-scoped deny does not claim the agent may only read", () => { const message = deniedWriteMessage({ ...base, sql: "DROP TABLE stg_tmp", readOnly: false }) - expect(message).toContain("A sql_execute_write rule denies it") + expect(message).toContain("A sql_execute_write permission rule denies it") expect(message).not.toContain("may only read") expect(message).toContain("rules allow") }) @@ -293,7 +355,7 @@ describe("denied write message branches", () => { const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } await expect( tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), - ).rejects.toThrow("A sql_execute_write rule denies it") + ).rejects.toThrow("A sql_execute_write permission rule denies it") }) test("a pattern-only deny leaves other writes to the default ask, so it is not read-only", async () => { @@ -302,7 +364,7 @@ describe("denied write message branches", () => { const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } await expect( tool.execute({ query: "DROP TABLE stg_tmp", warehouse: "guard_db", limit: 10 }, ctx as any), - ).rejects.toThrow("A sql_execute_write rule denies it") + ).rejects.toThrow("A sql_execute_write permission rule denies it") }) test("sql_execute reads the denial's rules to choose the wording", async () => { @@ -314,7 +376,7 @@ describe("denied write message branches", () => { const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } await expect( tool.execute({ query: "DROP TABLE stg_tmp", warehouse: "guard_db", limit: 10 }, ctx as any), - ).rejects.toThrow("A sql_execute_write rule denies it") + ).rejects.toThrow("A sql_execute_write permission rule denies it") }) test("an unreadable query without a warehouse suggests passing one", () => { diff --git a/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts b/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts index 060fe6ce8f..befd20fcfd 100644 --- a/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts +++ b/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts @@ -425,7 +425,7 @@ describe("v0.12.9 adversarial: runner argument validation and the hard deny end const result = await runner.run("sql_execute", { query: "INSERT INTO t VALUES (1)" }) expect(result.status).toBe("error") // The refusal says why the query counts as a write, then how to enable writes. - expect(result.output).toContain("Writes are not enabled for this run, and the query counts as a write because it is not a read (INSERT)") + expect(result.output).toContain("Write permission is disabled for this run, and the query counts as a write because it is not a read (INSERT)") expect(result.output.endsWith("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.")).toBe(true) }) From 5cd4407809c2c6a965ac2ff004cfa4561dbe062e Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 14:49:23 -0800 Subject: [PATCH 39/58] fix: name why a read cannot be embedded; a missing classifier is not a permission denial - `query()`, an unknown or side-effect function, several statements or a non-SELECT command each get their own reason instead of a generic shape message. - An unavailable classifier keeps the "counts as a write" wording, so telemetry does not record it as `permission`. Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/read-only-sql.ts | 16 ++++++++++++-- .../tools/sql-readonly-guard-explain.test.ts | 21 +++++++++++++++++-- 2 files changed, 33 insertions(+), 4 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index b66f29d257..6cda536134 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -36,6 +36,17 @@ function readOnlyBody(sql: string, dialect?: string): { masked: string; body: st return safe ? { masked, body } : undefined } +/** Why readOnlyBody refused a classifier read, in fixed words (function names only from fixed lists). */ +function unembeddableReason(sql: string, dialect?: string): string { + const calls = sqlFunctionCalls(sql, dialect) + if (calls.some((call) => call.name === "query")) return "it calls query(), which runs SQL text that cannot be checked; query the tables directly" + if (calls.some((call) => call.escaped)) return "it has an escaped function call, which cannot be checked" + if (calls.some((call) => hasSideEffectFunction(call.name))) return "it calls a function that is not known to be read-only" + if (statementsOf(sql, dialect).length > 1) return "it holds more than one statement" + if (!isSingleQuery(sql, dialect)) return "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" + return "its parentheses, quotes or comments do not balance" +} + /** Throws unless sql is one read-only query that is safe to embed in a larger query. */ export function requireReadOnlyQuery(sql: string, dialect?: string): void { if (readOnlyBody(sql, dialect) === undefined) @@ -106,13 +117,14 @@ export function writeReason(sql: string, dialect?: string): string { } if (queryType === "write") { const { reason, unreadable, unavailable } = explainWrite(sql, dialect) - const head = unreadable ? "It counts as a write because" : "It falls outside the read-only permission because" + // A missing classifier is an installation failure, not a permission decision. + const head = unreadable || unavailable ? "It counts as a write because" : "It falls outside the read-only permission because" return ` ${head} ${reason}.${unavailable ? ` ${UNAVAILABLE_NEXT_STEP}` : ""}` } // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. const body = readOnlyBody(sql, dialect)?.body if (!body || !/^(SELECT|WITH)\b/i.test(body)) { - return " Invalid query shape here: send a single SELECT or WITH query that can be embedded." + return ` This read is invalid here because ${body ? "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" : unembeddableReason(sql, dialect)}; send a single SELECT or WITH query that can be embedded.` } const [statement, replace] = wordPatterns(dialect) const word = (statement.exec(body) ?? replace.exec(body))?.[0] diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index c7db6179fd..22d7711d03 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -200,6 +200,8 @@ test("unavailable", async () => { expect(explained.unavailable).toBe(true) expect(explained.reason).not.toContain("could not read") expect(writeReason("SELECT 1", "postgres")).toContain(UNAVAILABLE_NEXT_STEP) + // An installation failure is not a permission decision, in words or in its telemetry class. + expect(writeReason("SELECT 1", "postgres")).not.toContain("permission") }) `, ) @@ -218,8 +220,23 @@ test("unavailable", async () => { } }, 60_000) - test.each(["SELECT 1; SELECT 2", "SHOW TABLES"])("explains the unsupported read shape %s", (sql) => { - expect(writeReason(sql, "postgres")).toContain("send a single SELECT or WITH query") + test.each([ + ["SELECT 1; SELECT 2", "more than one statement"], + ["SHOW TABLES", "not a SELECT or WITH query"], + ["SELECT pg_sleep(1)", "not known to be read-only"], + ])("explains the unsupported read shape %s", (sql, cause) => { + const reason = writeReason(sql, "postgres") + expect(reason).toContain(cause) + expect(reason).toContain("send a single SELECT or WITH query") + }) + + test("a single read calling query() is refused for the function", () => { + const sql = "SELECT * FROM query('SELECT 1 AS private_alias')" + const reason = writeReason(sql, "duckdb") + expect(reason).toContain("calls query()") + expect(reason).not.toContain("Invalid query shape") + expect(reason).not.toContain("private_alias") + expect(() => readSql(sql, "duckdb")).toThrow("calls query()") }) test("a refusal that is not about writing stays as it was", () => { From 0b34a0b699fed5ea8b1ea5a0047b20e3fedf30d9 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 14:57:18 -0800 Subject: [PATCH 40/58] refactor: one ordered check names why a read cannot be embedded `readOnlyBody` and the refusal reason now share one ordered list of checks, so the named cause cannot drift from the decision. `query()` is described without assuming its argument is SQL (it takes XQuery on SQL Server). Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/read-only-sql.ts | 53 +++++++++---------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 6cda536134..d5cda1e99f 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -8,43 +8,40 @@ import { hasSideEffectFunction } from "./sql-function-policy" * CTE or subquery it is placed in), it has no statement separator, and it calls no function * that writes or runs SQL (dynamic query() included). Undefined otherwise. */ function readOnlyBody(sql: string, dialect?: string): { masked: string; body: string } | undefined { + const checked = embeddable(sql, dialect) + return "refused" in checked ? undefined : checked +} + +/** readOnlyBody's checks, in order, with the first failed one named in fixed words (no SQL text). A write or + * hard block is refused without a reason: the classifier explains those. */ +function embeddable(sql: string, dialect?: string): { masked: string; body: string } | { refused: string } { const { queryType, blocked } = classifyAndCheck(sql, dialect) // Settled already; the function scan below is costly on deeply nested input. - if (blocked || queryType !== "read") return undefined + if (blocked || queryType !== "read") return { refused: "" } const { tokens, complete } = tokenizeSql(sql, dialect) const masked = maskSql(tokens) // All calls use real code '(' tokens. - const unsafeFunction = sqlFunctionCalls(sql, dialect).some( - (call) => call.escaped || call.name === "query" || hasSideEffectFunction(call.name), - ) + const calls = sqlFunctionCalls(sql, dialect) + if (calls.some((call) => call.name === "query")) { + return { refused: "it calls query(), whose argument this check cannot verify; query the tables directly" } + } + if (calls.some((call) => call.escaped)) return { refused: "it has an escaped function call, which cannot be checked" } + if (calls.some((call) => hasSideEffectFunction(call.name))) { + return { refused: "it calls a function that is not known to be read-only" } + } const body = masked.trim().replace(/;$/, "").trim() + if (body.includes(";")) return { refused: "it holds more than one statement" } + if (!isSingleQuery(sql, dialect)) { + return { refused: "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" } + } let depth = 0 let balanced = true for (const char of body) { if (char === "(") depth++ if (char === ")" && --depth < 0) balanced = false } - const safe = - !blocked && - queryType === "read" && - isSingleQuery(sql, dialect) && - complete && - !unsafeFunction && - balanced && - depth === 0 && - !body.includes(";") - return safe ? { masked, body } : undefined -} - -/** Why readOnlyBody refused a classifier read, in fixed words (function names only from fixed lists). */ -function unembeddableReason(sql: string, dialect?: string): string { - const calls = sqlFunctionCalls(sql, dialect) - if (calls.some((call) => call.name === "query")) return "it calls query(), which runs SQL text that cannot be checked; query the tables directly" - if (calls.some((call) => call.escaped)) return "it has an escaped function call, which cannot be checked" - if (calls.some((call) => hasSideEffectFunction(call.name))) return "it calls a function that is not known to be read-only" - if (statementsOf(sql, dialect).length > 1) return "it holds more than one statement" - if (!isSingleQuery(sql, dialect)) return "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" - return "its parentheses, quotes or comments do not balance" + if (!complete || !balanced || depth !== 0) return { refused: "its parentheses, quotes or comments do not balance" } + return { masked, body } } /** Throws unless sql is one read-only query that is safe to embed in a larger query. */ @@ -122,9 +119,11 @@ export function writeReason(sql: string, dialect?: string): string { return ` ${head} ${reason}.${unavailable ? ` ${UNAVAILABLE_NEXT_STEP}` : ""}` } // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. - const body = readOnlyBody(sql, dialect)?.body + const checked = embeddable(sql, dialect) + const body = "refused" in checked ? undefined : checked.body if (!body || !/^(SELECT|WITH)\b/i.test(body)) { - return ` This read is invalid here because ${body ? "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" : unembeddableReason(sql, dialect)}; send a single SELECT or WITH query that can be embedded.` + const cause = "refused" in checked ? checked.refused : "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" + return ` This read is invalid here because ${cause}; send a single SELECT or WITH query that can be embedded.` } const [statement, replace] = wordPatterns(dialect) const word = (statement.exec(body) ?? replace.exec(body))?.[0] From cb887bf0ab8dfbafddb2ca02d6e819c6320e58ce Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 15:16:40 -0800 Subject: [PATCH 41/58] fix: keep SQL Server XML .query() a read; hard blocks keep their own wording and class - `readOnlyBody` skips `query()` on SQL Server, where it takes XQuery, as the classifier does. - Hard blocks say "cannot be overridden by any rule" on every path; telemetry keeps them apart from permission denials. - `data_diff` refusals and `requireReadOnlyQuery` name their reason. - One constant pair marks a missing classifier. Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/native/connections/data-diff.ts | 4 ++-- .../opencode/src/altimate/tools/read-only-sql.ts | 12 +++++++----- .../opencode/src/altimate/tools/sql-classify.ts | 10 +++++++--- packages/opencode/src/altimate/tools/sql-execute.ts | 4 ++-- .../tools/sql-readonly-guard-explain.test.ts | 13 ++++++++++++- .../test/altimate/tools/sql-readonly-guard.test.ts | 7 ++++--- 6 files changed, 34 insertions(+), 16 deletions(-) diff --git a/packages/opencode/src/altimate/native/connections/data-diff.ts b/packages/opencode/src/altimate/native/connections/data-diff.ts index 22c8905141..063b550003 100644 --- a/packages/opencode/src/altimate/native/connections/data-diff.ts +++ b/packages/opencode/src/altimate/native/connections/data-diff.ts @@ -9,7 +9,7 @@ import type { DataDiffParams, DataDiffResult, PartitionDiffResult } from "../types" import * as Registry from "./registry" -import { requireReadOnlyQuery } from "../../tools/read-only-sql" +import { requireReadOnlyQuery, writeReason } from "../../tools/read-only-sql" import { classifyAndCheck } from "../../tools/sql-classify" // --------------------------------------------------------------------------- @@ -196,7 +196,7 @@ async function executeQuery(sql: string, warehouseName: string | undefined, meta const dialect = warehouseTypeToDialect(Registry.getConfig(warehouseName)?.type ?? "generic") if (metadata) { const check = classifyAndCheck(sql, dialect) - if (check.blocked || check.queryType !== "read") throw new Error("Data diff metadata must be read-only") + if (check.blocked || check.queryType !== "read") throw new Error(`Data diff metadata must be read-only.${writeReason(sql, dialect)}`) } else { requireReadOnlyQuery(sql, dialect) } diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index d5cda1e99f..0abd6ffa6c 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -22,8 +22,10 @@ function embeddable(sql: string, dialect?: string): { masked: string; body: stri const masked = maskSql(tokens) // All calls use real code '(' tokens. const calls = sqlFunctionCalls(sql, dialect) - if (calls.some((call) => call.name === "query")) { - return { refused: "it calls query(), whose argument this check cannot verify; query the tables directly" } + // SQL Server's XML .query() takes XQuery, not SQL, as in the classifier; elsewhere query() runs SQL text. + const sqlServer = /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") + if (!sqlServer && calls.some((call) => call.name === "query")) { + return { refused: "it calls query(), which runs SQL text that cannot be checked; query the tables directly" } } if (calls.some((call) => call.escaped)) return { refused: "it has an escaped function call, which cannot be checked" } if (calls.some((call) => hasSideEffectFunction(call.name))) { @@ -47,7 +49,7 @@ function embeddable(sql: string, dialect?: string): { masked: string; body: stri /** Throws unless sql is one read-only query that is safe to embed in a larger query. */ export function requireReadOnlyQuery(sql: string, dialect?: string): void { if (readOnlyBody(sql, dialect) === undefined) - throw new Error("Only a single read-only query is accepted here; it never writes data.") + throw new Error(`Only a single read-only query is accepted here; it never writes data.${writeReason(sql, dialect)}`) } // Statement words refused anywhere in a read handed to sql_check. A column qualified by a whole @@ -89,7 +91,7 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool * made a word count, then the reason. */ export function hardBlockRefusal(head: string, sql: string, dialect?: string): string { const unreadable = !tokenizeSql(sql, dialect).complete && !hasExecutableComment(sql, dialect) - return `${head}${unreadable ? "" : " This cannot be overridden."}${writeReason(sql, dialect)}` + return `${head}${unreadable ? "" : " This cannot be overridden by any rule."}${writeReason(sql, dialect)}` } /** Why sql is refused as a read, as a sentence to append to a refusal: a hard block, the classifier's reason for a write, @@ -102,7 +104,7 @@ export function writeReason(sql: string, dialect?: string): string { const index = statements.length > 1 ? statements.findIndex((statement) => classifyAndCheck(statement, dialect).blocked) : -1 const where = index >= 0 ? `statement ${index + 1} of ${statements.length} is` : "it holds" const cause = hardBlockCause(index >= 0 ? statements[index] : sql, dialect) - const hard = ` It is refused because ${where} a hard-blocked statement (${cause}); hard-blocked statements never run, regardless of permission.` + const hard = ` It is refused because ${where} a hard-blocked statement (${cause}); hard-blocked statements never run, whatever the rules allow.` // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone, inside the // unreadable text or outside it: name the unreadable text first, since fixing it may be the whole fix. const untilClosed = diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 98f0484a38..d3cbe4a955 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -186,6 +186,10 @@ function hardDenyLabel(match: string): string { return drop ? `DROP ${drop[1].toUpperCase()}` : "TRUNCATE" } +// Parse errors that mean the installation, not the SQL, is at fault; explainWrite reports them as such. +const PARSER_UNAVAILABLE = "SQL parser is unavailable" +const PARSER_INVALID_RESULT = "SQL parser returned an invalid statement list" + /** * Fail closed when the parser is unavailable or rejects the input. Lexical * statement boundaries still enforce hard denies without reading quoted text. @@ -512,11 +516,11 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { if (!lexical.complete) { return { ...classifyFallback(sql, dialect), parseError: "SQL contains unterminated or unsupported quoted text or comments" } } - if (!getStatementTypes) return { ...classifyFallback(sql, dialect), parseError: "SQL parser is unavailable" } + if (!getStatementTypes) return { ...classifyFallback(sql, dialect), parseError: PARSER_UNAVAILABLE } try { const result = getStatementTypes(parserSql(sql, dialect), dialect) if (!Array.isArray(result?.statements) || result.statement_count !== result.statements.length) { - return { ...classifyFallback(sql, dialect), parseError: "SQL parser returned an invalid statement list" } + return { ...classifyFallback(sql, dialect), parseError: PARSER_INVALID_RESULT } } // A generic parser can treat MySQL arithmetic (--2) as a comment and omit @@ -680,7 +684,7 @@ export function explainWrite( // Where statements need no separator, a statement keyword is the real reason, even if it breaks the parse. const batchKeyword = batchedStatement(maskSql(tokenizeSql(statement, dialect).tokens), dialect) // The classifier itself could not run: no rewrite of the SQL can help. - if (result.parseError === "SQL parser is unavailable" || result.parseError === "SQL parser returned an invalid statement list") { + if (result.parseError === PARSER_UNAVAILABLE || result.parseError === PARSER_INVALID_RESULT) { return { reason: "the SQL classifier is unavailable in this installation, so no query can be proven read-only", unreadable: false, diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 8cdb85049c..01b1dcbe32 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -259,10 +259,10 @@ export const SqlExecuteTool = Tool.define( if (blockedIn >= 0) throw new Error(hardBlockRefusal(head, sql, dialects[blockedIn])) if (jinja) throw new Error( - `${head} This cannot be overridden by a permission rule. dbt renders Jinja before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + + `${head} This cannot be overridden by any rule. dbt renders Jinja before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + "TRUNCATE words count wherever they sit, even in a literal or comment. Remove those words, or send plain SQL without Jinja.", ) - throw new Error(`${head} This cannot be overridden by a permission rule.`) + throw new Error(`${head} This cannot be overridden by any rule.`) } if (budget && queryType !== "read") { throw new Error("Batched queries must be read-only. To use write permission, run a write as its own sql_execute call.") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 22d7711d03..177679f7c8 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -3,7 +3,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs" import { tmpdir } from "node:os" import { join } from "node:path" import { classifyAndCheck, explainWrite, shellResidue } from "../../../src/altimate/tools/sql-classify" -import { hardBlockRefusal, readSql, writeReason } from "../../../src/altimate/tools/read-only-sql" +import { hardBlockRefusal, readSql, requireReadOnlyQuery, writeReason } from "../../../src/altimate/tools/read-only-sql" describe("shellResidue", () => { const cases: Record = { @@ -230,6 +230,17 @@ test("unavailable", async () => { expect(reason).toContain("send a single SELECT or WITH query") }) + test("data_diff's embedded-query check names its reason too", () => { + expect(() => requireReadOnlyQuery("SELECT 1; DELETE FROM t", "postgres")).toThrow("statement 2 of 2 is not a read (DELETE)") + expect(() => requireReadOnlyQuery("SELECT 1; SELECT 2", "postgres")).toThrow("more than one statement") + }) + + test("SQL Server's XML .query() takes XQuery, so the read is accepted, as in the classifier", () => { + const sql = "SELECT x.query('/a/b') AS v FROM t" + expect(readSql(sql, "sqlserver")).toBe(sql) + expect(writeReason(sql, "sqlserver")).toBe("") + }) + test("a single read calling query() is refused for the function", () => { const sql = "SELECT * FROM query('SELECT 1 AS private_alias')" const reason = writeReason(sql, "duckdb") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 89dbd75bdf..2081de02fc 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -259,7 +259,8 @@ describe("sql_execute on a read-only agent", () => { describe("denied write message branches", () => { const base = { sql: "SELECT 1", dialects: ["postgres"], jinja: false, mongo: false, scratch: false, warehouseGiven: true } - test("refusal messages keep their telemetry error class", async () => { + // Hard blocks keep the class they had on main, apart from permission denials, so safety blocks stay countable. + test("refusal messages carry their telemetry error class", async () => { const write = { ...base, sql: "DELETE FROM orders" } const hard = "DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety." const scoped = { ...write, readOnly: false } @@ -286,9 +287,9 @@ describe("denied write message branches", () => { ["SQL parser error", deniedWriteMessage({ ...scoped, sql: "SELECT Order Date FROM orders" }), "parse_error"], ["shell residue", deniedWriteMessage({ ...scoped, sql: "SELECT 1 2>/dev/null" }), "parse_error"], ["open quote", deniedWriteMessage({ ...scoped, sql: "SELECT 'abc" }), "parse_error"], - ["hard block", hardBlockRefusal(hard, "TRUNCATE TABLE orders", "postgres"), "permission"], + ["hard block", hardBlockRefusal(hard, "TRUNCATE TABLE orders", "postgres"), "unknown"], ["hard-blocked open quote", hardBlockRefusal(hard, "SELECT 'truncate", "postgres"), "parse_error"], - ["hard-blocked comment", hardBlockRefusal(hard, "SELECT 1 /*! + 1 */", "mysql"), "permission"], + ["hard-blocked comment", hardBlockRefusal(hard, "SELECT 1 /*! + 1 */", "mysql"), "unknown"], ["sql_check", await refusal(() => readSql(write.sql, "postgres")), "permission"], ["sql_check statement word", await refusal(() => readSql("SELECT x AS load FROM t", "postgres")), "permission"], ["sql_check query shape", await refusal(() => readSql("SHOW TABLES", "postgres")), "validation"], From aa3d5cedfec241539990a1938e4a3941b95d7689 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 15:29:52 -0800 Subject: [PATCH 42/58] fix: hard blocks keep the permission class; one SQL Server dialect check; case-aware quoting hint - Hard blocks say "cannot be overridden by any permission rule" on every path. - `isSqlServerDialect` replaces four copies of the dialect list. - The quoted-qualifier hint names the stored case on Snowflake and Oracle. - `writeReason` says a write needs a permission the path lacks. - Tail timing checks use larger inputs. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/read-only-sql.ts | 11 +++++------ .../opencode/src/altimate/tools/sql-classify.ts | 15 +++++++++++---- .../opencode/src/altimate/tools/sql-execute.ts | 4 ++-- .../tools/sql-readonly-guard-explain.test.ts | 6 ++++-- .../altimate/tools/sql-readonly-guard.test.ts | 5 ++--- 5 files changed, 24 insertions(+), 17 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 0abd6ffa6c..1970ae78dc 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -1,4 +1,4 @@ -import { UNAVAILABLE_NEXT_STEP, hardBlockCause, hasExecutableComment, classifyAndCheck, explainWrite, isSingleQuery } from "./sql-classify" +import { UNAVAILABLE_NEXT_STEP, hardBlockCause, hasExecutableComment, classifyAndCheck, explainWrite, isSingleQuery, isSqlServerDialect } from "./sql-classify" import { maskSql, statementsOf, tokenizeSql } from "./sql-tokenize" import { sqlFunctionCalls } from "./sql-functions" import { hasSideEffectFunction } from "./sql-function-policy" @@ -23,8 +23,7 @@ function embeddable(sql: string, dialect?: string): { masked: string; body: stri // All calls use real code '(' tokens. const calls = sqlFunctionCalls(sql, dialect) // SQL Server's XML .query() takes XQuery, not SQL, as in the classifier; elsewhere query() runs SQL text. - const sqlServer = /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") - if (!sqlServer && calls.some((call) => call.name === "query")) { + if (!isSqlServerDialect(dialect) && calls.some((call) => call.name === "query")) { return { refused: "it calls query(), which runs SQL text that cannot be checked; query the tables directly" } } if (calls.some((call) => call.escaped)) return { refused: "it has an escaped function call, which cannot be checked" } @@ -91,7 +90,7 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool * made a word count, then the reason. */ export function hardBlockRefusal(head: string, sql: string, dialect?: string): string { const unreadable = !tokenizeSql(sql, dialect).complete && !hasExecutableComment(sql, dialect) - return `${head}${unreadable ? "" : " This cannot be overridden by any rule."}${writeReason(sql, dialect)}` + return `${head}${unreadable ? "" : " This cannot be overridden by any permission rule."}${writeReason(sql, dialect)}` } /** Why sql is refused as a read, as a sentence to append to a refusal: a hard block, the classifier's reason for a write, @@ -104,7 +103,7 @@ export function writeReason(sql: string, dialect?: string): string { const index = statements.length > 1 ? statements.findIndex((statement) => classifyAndCheck(statement, dialect).blocked) : -1 const where = index >= 0 ? `statement ${index + 1} of ${statements.length} is` : "it holds" const cause = hardBlockCause(index >= 0 ? statements[index] : sql, dialect) - const hard = ` It is refused because ${where} a hard-blocked statement (${cause}); hard-blocked statements never run, whatever the rules allow.` + const hard = ` It is refused because ${where} a hard-blocked statement (${cause}); hard-blocked statements never run, whatever the permission rules allow.` // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone, inside the // unreadable text or outside it: name the unreadable text first, since fixing it may be the whole fix. const untilClosed = @@ -117,7 +116,7 @@ export function writeReason(sql: string, dialect?: string): string { if (queryType === "write") { const { reason, unreadable, unavailable } = explainWrite(sql, dialect) // A missing classifier is an installation failure, not a permission decision. - const head = unreadable || unavailable ? "It counts as a write because" : "It falls outside the read-only permission because" + const head = unreadable || unavailable ? "It counts as a write because" : "It counts as a write, which needs a write permission this path does not have, because" return ` ${head} ${reason}.${unavailable ? ` ${UNAVAILABLE_NEXT_STEP}` : ""}` } // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index d3cbe4a955..6e52c93cb2 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -186,6 +186,11 @@ function hardDenyLabel(match: string): string { return drop ? `DROP ${drop[1].toUpperCase()}` : "TRUNCATE" } +/** SQL Server and its aliases, whose batches run statements without separators and whose XML .query() takes XQuery. */ +export function isSqlServerDialect(dialect?: string): boolean { + return /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") +} + // Parse errors that mean the installation, not the SQL, is at fault; explainWrite reports them as such. const PARSER_UNAVAILABLE = "SQL parser is unavailable" const PARSER_INVALID_RESULT = "SQL parser returned an invalid statement list" @@ -245,7 +250,7 @@ function classifyFallback( * must hold no statement keyword in its code (literals, identifiers and comments masked): the * engine would run `SELECT ... DELETE FROM t` as two statements however a parser reads it. */ function batchedStatement(masked: string, dialect?: string): string | undefined { - if (!/^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") && isModeledDialect(dialect)) return undefined + if (!isSqlServerDialect(dialect) && isModeledDialect(dialect)) return undefined // A name qualified by a whole unquoted identifier (t.update, s.t.into) cannot start a statement: // every part after the first of a dotted name (s.t.update) is a name. const names = masked.replace(/((?:^|[^\w$.])[A-Za-z_][\w$]*)((?:\.[A-Za-z_][\w$]*)+)/g, (_, head: string, rest: string) => @@ -462,7 +467,7 @@ function functionSafety(sql: string, dialect: string | undefined, depth: number, Object.hasOwn(SQL_ARGUMENTS, call.name) && call.qualifier === undefined && !hasSideEffectFunction(call.name) if (depth > 0 && !nestedExecutor && !isReadOnlyNestedFunction(call.name, call.qualifier)) write = true // SQL Server's XML .query() takes XQuery, not executable SQL. - if (call.name === "query" && /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "")) continue + if (call.name === "query" && isSqlServerDialect(dialect)) continue const argument = Object.hasOwn(SQL_ARGUMENTS, call.name) ? SQL_ARGUMENTS[call.name] : undefined if (!argument) continue const inner = sqlLiteral(call.args[argument.index], dialect) @@ -645,7 +650,7 @@ function parserMessage(message: string): string { } function batchKeywordExplanation(dialect?: string): string { - return /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") + return isSqlServerDialect(dialect) ? "SQL Server runs a statement there even without a separator" : "this dialect is not modeled, so it may run as a statement" } @@ -734,12 +739,14 @@ export function explainWrite( // A statement that is itself a write is named by its type, before any batch keyword inside it. if (parsed && parsed.category !== "query") return writes(`${where} is not a read (${type})`) if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { + // Quoted names keep their case; engines that store unquoted names in uppercase need it written so. + const stored = /^(snowflake|oracle)$/i.test(dialect ?? "") ? ', in the case the engine stores, such as "UPDATE"' : "" return writes( dialect?.toLowerCase() === "clickhouse" ? `${where} contains a write clause (SELECT ... INTO or a modifying CTE), or a write keyword that on ClickHouse ` + 'counts even after a dot: quote the column, t."update"' : `${where} contains a write clause (SELECT ... INTO, INSERT/UPDATE/DELETE/MERGE inside a CTE, ` + - 'or a write keyword after a quoted name such as "t".update: quote the column too, "t"."update")', + `or a write keyword after a quoted name such as "t".update: quote the column too, "t"."update"${stored})`, ) } const keyword = batchedStatement(masked, dialect) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 01b1dcbe32..073e566ee2 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -259,10 +259,10 @@ export const SqlExecuteTool = Tool.define( if (blockedIn >= 0) throw new Error(hardBlockRefusal(head, sql, dialects[blockedIn])) if (jinja) throw new Error( - `${head} This cannot be overridden by any rule. dbt renders Jinja before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + + `${head} This cannot be overridden by any permission rule. dbt renders Jinja before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + "TRUNCATE words count wherever they sit, even in a literal or comment. Remove those words, or send plain SQL without Jinja.", ) - throw new Error(`${head} This cannot be overridden by any rule.`) + throw new Error(`${head} This cannot be overridden by any permission rule.`) } if (budget && queryType !== "read") { throw new Error("Batched queries must be read-only. To use write permission, run a write as its own sql_execute call.") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 177679f7c8..ab9abeec08 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -61,8 +61,8 @@ describe("shellResidue", () => { test("a crafted tail is scanned in linear time", () => { // The tail patterns see at most 400 characters, so a longer crafted tail costs no more. - expect(growth((n) => `SELECT * FROM t ${"| head ".repeat(n)}x;y`, 8)).toBeLessThan(30) - expect(growth((n) => `SELECT * FROM t ${"| head ".repeat(n)};y`, 6)).toBeLessThan(30) + expect(growth((n) => `SELECT * FROM t ${"| head ".repeat(n)}x;y`, 2_000)).toBeLessThan(30) + expect(growth((n) => `SELECT * FROM t ${"| head ".repeat(n)};y`, 1_500)).toBeLessThan(30) }) test("a comparison before the residue is kept", () => { @@ -317,6 +317,8 @@ describe("explainWrite", () => { test("a quoted qualifier gets a specific hint", () => { expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).toContain('"t"."update"') + expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).not.toContain("stores") + expect(explainWrite('SELECT "T".update FROM t', "snowflake").reason).toContain('the case the engine stores, such as "UPDATE"') }) test("every write in the guard corpus is a write with a specific reason", () => { diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 2081de02fc..235bc97ceb 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -259,7 +259,6 @@ describe("sql_execute on a read-only agent", () => { describe("denied write message branches", () => { const base = { sql: "SELECT 1", dialects: ["postgres"], jinja: false, mongo: false, scratch: false, warehouseGiven: true } - // Hard blocks keep the class they had on main, apart from permission denials, so safety blocks stay countable. test("refusal messages carry their telemetry error class", async () => { const write = { ...base, sql: "DELETE FROM orders" } const hard = "DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety." @@ -287,9 +286,9 @@ describe("denied write message branches", () => { ["SQL parser error", deniedWriteMessage({ ...scoped, sql: "SELECT Order Date FROM orders" }), "parse_error"], ["shell residue", deniedWriteMessage({ ...scoped, sql: "SELECT 1 2>/dev/null" }), "parse_error"], ["open quote", deniedWriteMessage({ ...scoped, sql: "SELECT 'abc" }), "parse_error"], - ["hard block", hardBlockRefusal(hard, "TRUNCATE TABLE orders", "postgres"), "unknown"], + ["hard block", hardBlockRefusal(hard, "TRUNCATE TABLE orders", "postgres"), "permission"], ["hard-blocked open quote", hardBlockRefusal(hard, "SELECT 'truncate", "postgres"), "parse_error"], - ["hard-blocked comment", hardBlockRefusal(hard, "SELECT 1 /*! + 1 */", "mysql"), "unknown"], + ["hard-blocked comment", hardBlockRefusal(hard, "SELECT 1 /*! + 1 */", "mysql"), "permission"], ["sql_check", await refusal(() => readSql(write.sql, "postgres")), "permission"], ["sql_check statement word", await refusal(() => readSql("SELECT x AS load FROM t", "postgres")), "permission"], ["sql_check query shape", await refusal(() => readSql("SHOW TABLES", "postgres")), "validation"], From c8a3d4733a346f9267cdd9caa78bdbee6ca7e9ca Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 15:44:31 -0800 Subject: [PATCH 43/58] fix: SQLite returns rows for comment-led reads; ClickHouse names shell redirects - The SQLite driver skips leading comments before choosing rows or a change count. - On ClickHouse a descriptor or /dev/null redirect makes the text unreadable, so it is named, not run. - Hard-block wording is one shared constant; the Snowflake/Oracle hint shows "T"."UPDATE". Co-Authored-By: Claude Opus 5.5 --- packages/drivers/src/sqlite.ts | 15 +++++++++++++-- .../opencode/src/altimate/tools/read-only-sql.ts | 5 ++++- .../opencode/src/altimate/tools/sql-classify.ts | 11 +++++++++-- .../opencode/src/altimate/tools/sql-execute.ts | 6 +++--- .../opencode/test/altimate/drivers-e2e.test.ts | 8 ++++++++ .../tools/sql-readonly-guard-explain.test.ts | 16 ++++++++++++++-- 6 files changed, 51 insertions(+), 10 deletions(-) diff --git a/packages/drivers/src/sqlite.ts b/packages/drivers/src/sqlite.ts index c950faa084..871f733d02 100644 --- a/packages/drivers/src/sqlite.ts +++ b/packages/drivers/src/sqlite.ts @@ -12,6 +12,16 @@ import { resolveQueryTimeout } from "./query-timeout" import { allowsCreate, assertStoreExists, isLocalFilePath, requireStorePath } from "./file-store" import type { ConnectionConfig, Connector, ConnectorResult, ExecuteOptions, SchemaColumn } from "./types" +/** The statement after any leading whitespace, `--` line comments and block comments. */ +function withoutLeadingComments(sql: string): string { + let s = sql + for (;;) { + const next = s.replace(/^\s+/, "").replace(/^--[^\n]*(\n|$)/, "").replace(/^\/\*[\s\S]*?\*\//, "") + if (next === s) return s + s = next + } +} + export async function connect(config: ConnectionConfig): Promise { // altimate_change start — a missing path must fail loudly, not become :memory: const cwd = process.cwd() @@ -52,8 +62,9 @@ export async function connect(config: ConnectionConfig): Promise { const timeoutMs = resolveQueryTimeout(config, options).ms const effectiveLimit = options?.noLimit ? 0 : (limit ?? 1000) - // Determine if this is a SELECT-like statement - const trimmed = sql.trim().toLowerCase() + // Determine if this is a SELECT-like statement. Leading comments are skipped, so a commented read + // still returns rows instead of a change count. + const trimmed = withoutLeadingComments(sql).toLowerCase() const isPragma = trimmed.startsWith("pragma") const isSelect = trimmed.startsWith("select") || diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 1970ae78dc..5328b2b797 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -86,11 +86,14 @@ export function readSql(sql: string, dialect?: string, options: { explain?: bool return semicolon < 0 ? sql : sql.slice(0, semicolon) + sql.slice(semicolon + 1) } +/** Every hard-block refusal says this; its "permission" keyword sets the telemetry error class. */ +export const NOT_OVERRIDABLE = "This cannot be overridden by any permission rule." + /** A hard-block refusal: head, then "cannot be overridden" unless only unreadable text (an open quote or comment) * made a word count, then the reason. */ export function hardBlockRefusal(head: string, sql: string, dialect?: string): string { const unreadable = !tokenizeSql(sql, dialect).complete && !hasExecutableComment(sql, dialect) - return `${head}${unreadable ? "" : " This cannot be overridden by any permission rule."}${writeReason(sql, dialect)}` + return `${head}${unreadable ? "" : ` ${NOT_OVERRIDABLE}`}${writeReason(sql, dialect)}` } /** Why sql is refused as a read, as a sentence to append to a refusal: a hard block, the classifier's reason for a write, diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 6e52c93cb2..d0c5090909 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -532,6 +532,11 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // trailing statements. Keep dialect-aware lexical hard denies authoritative. const functions = functionSafety(sql, dialect, depth) const masked = maskSql(lexical.tokens) + // ClickHouse's bundled parser accepts trailing text, so a shell redirect to a descriptor or /dev/null + // (never SQL) would pass as a read. Treat it as unreadable so the residue is named, as on other dialects. + if (dialect?.toLowerCase() === "clickhouse" && masked.search(SHELL_REDIRECT) >= 0) { + return { ...classifyFallback(sql, dialect), parseError: "shell redirect after the SQL" } + } const hardType = result.statements.find( (s: { statement_type: string }) => s.statement_type && HARD_DENY_TYPES.has(s.statement_type.toUpperCase()), )?.statement_type @@ -740,13 +745,15 @@ export function explainWrite( if (parsed && parsed.category !== "query") return writes(`${where} is not a read (${type})`) if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { // Quoted names keep their case; engines that store unquoted names in uppercase need it written so. - const stored = /^(snowflake|oracle)$/i.test(dialect ?? "") ? ', in the case the engine stores, such as "UPDATE"' : "" + const quoted = /^(snowflake|oracle)$/i.test(dialect ?? "") + ? '"T"."UPDATE" (this engine stores unquoted names in uppercase)' + : '"t"."update"' return writes( dialect?.toLowerCase() === "clickhouse" ? `${where} contains a write clause (SELECT ... INTO or a modifying CTE), or a write keyword that on ClickHouse ` + 'counts even after a dot: quote the column, t."update"' : `${where} contains a write clause (SELECT ... INTO, INSERT/UPDATE/DELETE/MERGE inside a CTE, ` + - `or a write keyword after a quoted name such as "t".update: quote the column too, "t"."update"${stored})`, + `or a write keyword after a quoted name such as "t".update: quote the column too, ${quoted})`, ) } const keyword = batchedStatement(masked, dialect) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 073e566ee2..c2d7002f6b 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -45,7 +45,7 @@ import * as Precedence from "../workspace/precedence" import { normalizeError } from "./response-normalization" // altimate_change end import { readSql } from "./sql-check" -import { hardBlockRefusal, writeReason } from "./read-only-sql" +import { NOT_OVERRIDABLE, hardBlockRefusal, writeReason } from "./read-only-sql" import { WriteDeniedError } from "../tool-cli/permissions" import { MaterializeError, storeRows } from "./sql-materialize" import { firstTime } from "./session-hints" @@ -259,10 +259,10 @@ export const SqlExecuteTool = Tool.define( if (blockedIn >= 0) throw new Error(hardBlockRefusal(head, sql, dialects[blockedIn])) if (jinja) throw new Error( - `${head} This cannot be overridden by any permission rule. dbt renders Jinja before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + + `${head} ${NOT_OVERRIDABLE} dbt renders Jinja before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + "TRUNCATE words count wherever they sit, even in a literal or comment. Remove those words, or send plain SQL without Jinja.", ) - throw new Error(`${head} This cannot be overridden by any permission rule.`) + throw new Error(`${head} ${NOT_OVERRIDABLE}`) } if (budget && queryType !== "read") { throw new Error("Batched queries must be read-only. To use write permission, run a write as its own sql_execute call.") diff --git a/packages/opencode/test/altimate/drivers-e2e.test.ts b/packages/opencode/test/altimate/drivers-e2e.test.ts index b4f6a131a3..9d5bc37574 100644 --- a/packages/opencode/test/altimate/drivers-e2e.test.ts +++ b/packages/opencode/test/altimate/drivers-e2e.test.ts @@ -682,6 +682,14 @@ describe("SQLite Driver E2E", () => { expect(result.truncated).toBe(false) }) + test("a read after leading comments returns rows, not a change count", async () => { + for (const sql of ["-- note: update later\nSELECT 1 AS x", "/* delete */ SELECT 1 AS x", " -- a\n/* b */\n WITH t AS (SELECT 1 AS x) SELECT x FROM t"]) { + const result = await connector.execute(sql) + expect(result.columns).toEqual(["x"]) + expect(result.rows).toEqual([[1]]) + } + }) + test( "execute DDL + DML queries", async () => { diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index ab9abeec08..15779cc813 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -27,6 +27,16 @@ describe("shellResidue", () => { }) } + test("on ClickHouse, whose parser accepts trailing text, a redirect is still named and not run", () => { + for (const [sql, residue] of [["SELECT 1 2>/dev/null", "2>/dev/null"], ["SELECT * FROM t LIMIT 5 2>&1", "2>&1"]]) { + expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("write") + expect(shellResidue(sql, "clickhouse")).toBe(residue) + } + for (const sql of ["SELECT a > 2 FROM t", "SELECT '2>/dev/null'", "SELECT 1 -- 2>/dev/null", "SELECT a || tail FROM t"]) { + expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("read") + } + }) + test("a comparison is not a redirect", () => { expect(shellResidue("SELECT a FROM t WHERE x > 2", "postgres")).toBeUndefined() expect(shellResidue("SELECT a FROM t WHERE x >= 2.5", "postgres")).toBeUndefined() @@ -317,8 +327,10 @@ describe("explainWrite", () => { test("a quoted qualifier gets a specific hint", () => { expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).toContain('"t"."update"') - expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).not.toContain("stores") - expect(explainWrite('SELECT "T".update FROM t', "snowflake").reason).toContain('the case the engine stores, such as "UPDATE"') + expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).not.toContain("uppercase") + const upper = explainWrite('SELECT "T".update FROM t', "snowflake").reason + expect(upper).toContain('"T"."UPDATE"') + expect(upper).not.toContain('"t"."update"') }) test("every write in the guard corpus is a write with a specific reason", () => { From 4feaf2868bea14f0f45a640cb980c36b7dbdc49f Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 15:52:50 -0800 Subject: [PATCH 44/58] fix: keep the SQLite driver unchanged; name ClickHouse redirects only on reads - Revert the SQLite prefix change: routing by text drew new misroutes (`WITH ... DML`, LIMIT in comments). #1819 tracks routing by the prepared statement instead. - The ClickHouse redirect rule applies only when every statement is a query, so a write keeps "not a read (DELETE)". Co-Authored-By: Claude Opus 5.5 --- packages/drivers/src/sqlite.ts | 15 ++------------- .../opencode/src/altimate/tools/sql-classify.ts | 7 ++++++- .../opencode/test/altimate/drivers-e2e.test.ts | 8 -------- .../tools/sql-readonly-guard-explain.test.ts | 2 ++ 4 files changed, 10 insertions(+), 22 deletions(-) diff --git a/packages/drivers/src/sqlite.ts b/packages/drivers/src/sqlite.ts index 871f733d02..c950faa084 100644 --- a/packages/drivers/src/sqlite.ts +++ b/packages/drivers/src/sqlite.ts @@ -12,16 +12,6 @@ import { resolveQueryTimeout } from "./query-timeout" import { allowsCreate, assertStoreExists, isLocalFilePath, requireStorePath } from "./file-store" import type { ConnectionConfig, Connector, ConnectorResult, ExecuteOptions, SchemaColumn } from "./types" -/** The statement after any leading whitespace, `--` line comments and block comments. */ -function withoutLeadingComments(sql: string): string { - let s = sql - for (;;) { - const next = s.replace(/^\s+/, "").replace(/^--[^\n]*(\n|$)/, "").replace(/^\/\*[\s\S]*?\*\//, "") - if (next === s) return s - s = next - } -} - export async function connect(config: ConnectionConfig): Promise { // altimate_change start — a missing path must fail loudly, not become :memory: const cwd = process.cwd() @@ -62,9 +52,8 @@ export async function connect(config: ConnectionConfig): Promise { const timeoutMs = resolveQueryTimeout(config, options).ms const effectiveLimit = options?.noLimit ? 0 : (limit ?? 1000) - // Determine if this is a SELECT-like statement. Leading comments are skipped, so a commented read - // still returns rows instead of a change count. - const trimmed = withoutLeadingComments(sql).toLowerCase() + // Determine if this is a SELECT-like statement + const trimmed = sql.trim().toLowerCase() const isPragma = trimmed.startsWith("pragma") const isSelect = trimmed.startsWith("select") || diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index d0c5090909..0bf5318065 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -534,7 +534,12 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { const masked = maskSql(lexical.tokens) // ClickHouse's bundled parser accepts trailing text, so a shell redirect to a descriptor or /dev/null // (never SQL) would pass as a read. Treat it as unreadable so the residue is named, as on other dialects. - if (dialect?.toLowerCase() === "clickhouse" && masked.search(SHELL_REDIRECT) >= 0) { + // Only for queries: a write is already refused and named by its type. + if ( + dialect?.toLowerCase() === "clickhouse" && + result.statements.every((s: { category?: string }) => s.category === "query") && + masked.search(SHELL_REDIRECT) >= 0 + ) { return { ...classifyFallback(sql, dialect), parseError: "shell redirect after the SQL" } } const hardType = result.statements.find( diff --git a/packages/opencode/test/altimate/drivers-e2e.test.ts b/packages/opencode/test/altimate/drivers-e2e.test.ts index 9d5bc37574..b4f6a131a3 100644 --- a/packages/opencode/test/altimate/drivers-e2e.test.ts +++ b/packages/opencode/test/altimate/drivers-e2e.test.ts @@ -682,14 +682,6 @@ describe("SQLite Driver E2E", () => { expect(result.truncated).toBe(false) }) - test("a read after leading comments returns rows, not a change count", async () => { - for (const sql of ["-- note: update later\nSELECT 1 AS x", "/* delete */ SELECT 1 AS x", " -- a\n/* b */\n WITH t AS (SELECT 1 AS x) SELECT x FROM t"]) { - const result = await connector.execute(sql) - expect(result.columns).toEqual(["x"]) - expect(result.rows).toEqual([[1]]) - } - }) - test( "execute DDL + DML queries", async () => { diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 15779cc813..c52c5071d1 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -35,6 +35,8 @@ describe("shellResidue", () => { for (const sql of ["SELECT a > 2 FROM t", "SELECT '2>/dev/null'", "SELECT 1 -- 2>/dev/null", "SELECT a || tail FROM t"]) { expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("read") } + // A write keeps its own reason rather than a parser failure. + expect(explainWrite("DELETE FROM t 2>/dev/null", "clickhouse").reason).toBe("it is not a read (DELETE)") }) test("a comparison is not a redirect", () => { From d06aa2b63541a1c373befb92a5d6fe7e75b22d1c Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 15:59:39 -0800 Subject: [PATCH 45/58] fix: name ClickHouse redirects on any read, including SHOW and DESCRIBE The redirect rule now runs after the read/write decision, so every read (queries and read-only commands) gets the shell-syntax reason, and a write keeps its own. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/sql-classify.ts | 16 ++++++---------- .../tools/sql-readonly-guard-explain.test.ts | 7 ++++++- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 0bf5318065..eef0f42cf7 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -532,16 +532,6 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // trailing statements. Keep dialect-aware lexical hard denies authoritative. const functions = functionSafety(sql, dialect, depth) const masked = maskSql(lexical.tokens) - // ClickHouse's bundled parser accepts trailing text, so a shell redirect to a descriptor or /dev/null - // (never SQL) would pass as a read. Treat it as unreadable so the residue is named, as on other dialects. - // Only for queries: a write is already refused and named by its type. - if ( - dialect?.toLowerCase() === "clickhouse" && - result.statements.every((s: { category?: string }) => s.category === "query") && - masked.search(SHELL_REDIRECT) >= 0 - ) { - return { ...classifyFallback(sql, dialect), parseError: "shell redirect after the SQL" } - } const hardType = result.statements.find( (s: { statement_type: string }) => s.statement_type && HARD_DENY_TYPES.has(s.statement_type.toUpperCase()), )?.statement_type @@ -566,6 +556,12 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { otherIsReadOnly(sql, result.statements, dialect) ? "read" : "write" + // ClickHouse's bundled parser accepts trailing text, so a shell redirect to a descriptor or /dev/null + // (never SQL) would pass as a read. Treat such a read as unreadable so the residue is named, as on other + // dialects; a write is already refused and named by its type. + if (queryType === "read" && dialect?.toLowerCase() === "clickhouse" && masked.search(SHELL_REDIRECT) >= 0) { + return { ...classifyFallback(sql, dialect), parseError: "shell redirect after the SQL" } + } const writeTruncate = queryType === "write" && WRITE_TRUNCATE.test(namesKept(lexical.tokens)) const finalCause = cause ?? (writeTruncate ? "TRUNCATE" : undefined) return { queryType, blocked: finalCause !== undefined, ...(finalCause && { cause: finalCause }) } diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index c52c5071d1..0cc0c78ac5 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -28,7 +28,12 @@ describe("shellResidue", () => { } test("on ClickHouse, whose parser accepts trailing text, a redirect is still named and not run", () => { - for (const [sql, residue] of [["SELECT 1 2>/dev/null", "2>/dev/null"], ["SELECT * FROM t LIMIT 5 2>&1", "2>&1"]]) { + for (const [sql, residue] of [ + ["SELECT 1 2>/dev/null", "2>/dev/null"], + ["SELECT * FROM t LIMIT 5 2>&1", "2>&1"], + ["SHOW TABLES 2>/dev/null", "2>/dev/null"], + ["DESCRIBE TABLE t 2>&1", "2>&1"], + ]) { expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("write") expect(shellResidue(sql, "clickhouse")).toBe(residue) } From 29fe53f167cc1e849d70ae9067da1423278682d2 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 16:10:45 -0800 Subject: [PATCH 46/58] fix: quote names in refusal hints the way the dialect does MySQL, BigQuery and Spark-family hints use backticks, since double quotes make a string there. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/sql-classify.ts | 13 +++++++++---- .../tools/sql-readonly-guard-explain.test.ts | 4 ++++ 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index eef0f42cf7..473177314e 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -186,6 +186,11 @@ function hardDenyLabel(match: string): string { return drop ? `DROP ${drop[1].toUpperCase()}` : "TRUNCATE" } +/** A name quoted the way the dialect quotes identifiers: backticks where double quotes make a string. */ +function quoteName(name: string, dialect?: string): string { + return /^(mysql|mariadb|bigquery|spark|databricks|hive)$/i.test(dialect ?? "") ? `\`${name}\`` : `"${name}"` +} + /** SQL Server and its aliases, whose batches run statements without separators and whose XML .query() takes XQuery. */ export function isSqlServerDialect(dialect?: string): boolean { return /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") @@ -718,7 +723,7 @@ export function explainWrite( return unreadable( `the ${dialect ?? "generic"} SQL parser could not read ${where} (${parserMessage(result.parseError)}), so it cannot be proven read-only. ` + "The position is approximate: it counts within that statement, with each comment read as one space. " + - 'Fix the syntax there: quote identifiers that contain spaces or are keywords ("order date"), ' + + `Fix the syntax there: quote identifiers that contain spaces or are keywords (${quoteName("order date", dialect)}), ` + "check the clause order, and replace any placeholder text (...)" ) } @@ -747,14 +752,14 @@ export function explainWrite( if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { // Quoted names keep their case; engines that store unquoted names in uppercase need it written so. const quoted = /^(snowflake|oracle)$/i.test(dialect ?? "") - ? '"T"."UPDATE" (this engine stores unquoted names in uppercase)' - : '"t"."update"' + ? `${quoteName("T", dialect)}.${quoteName("UPDATE", dialect)} (this engine stores unquoted names in uppercase)` + : `${quoteName("t", dialect)}.${quoteName("update", dialect)}` return writes( dialect?.toLowerCase() === "clickhouse" ? `${where} contains a write clause (SELECT ... INTO or a modifying CTE), or a write keyword that on ClickHouse ` + 'counts even after a dot: quote the column, t."update"' : `${where} contains a write clause (SELECT ... INTO, INSERT/UPDATE/DELETE/MERGE inside a CTE, ` + - `or a write keyword after a quoted name such as "t".update: quote the column too, ${quoted})`, + `or a write keyword after a quoted name such as ${quoteName("t", dialect)}.update: quote the column too, ${quoted})`, ) } const keyword = batchedStatement(masked, dialect) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 0cc0c78ac5..b810507850 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -338,6 +338,10 @@ describe("explainWrite", () => { const upper = explainWrite('SELECT "T".update FROM t', "snowflake").reason expect(upper).toContain('"T"."UPDATE"') expect(upper).not.toContain('"t"."update"') + // Where double quotes make a string, the hints use backticks. + expect(explainWrite("SELECT `t`.update FROM t", "mysql").reason).toContain("`t`.`update`") + expect(explainWrite("SELECT Order Date FROM orders", "mysql").reason).toContain("(`order date`)") + expect(explainWrite("SELECT Order Date FROM orders", "postgres").reason).toContain('("order date")') }) test("every write in the guard corpus is a write with a specific reason", () => { From 94a878d8a56de87ecf75cc5833d38b7d8e3e5ee2 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 16:16:48 -0800 Subject: [PATCH 47/58] fix: refusal hints quote names with brackets on SQL Server and backticks on ClickHouse Matches how data_diff quotes those dialects; SQL Server double quotes can be strings when QUOTED_IDENTIFIER is off. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/sql-classify.ts | 6 ++++-- .../test/altimate/tools/sql-readonly-guard-explain.test.ts | 1 + 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index 473177314e..dd879cd715 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -186,9 +186,11 @@ function hardDenyLabel(match: string): string { return drop ? `DROP ${drop[1].toUpperCase()}` : "TRUNCATE" } -/** A name quoted the way the dialect quotes identifiers: backticks where double quotes make a string. */ +/** A name quoted the way the dialect always reads as an identifier: backticks where double quotes can make a + * string (or, on ClickHouse, as data_diff quotes), brackets on SQL Server, where QUOTED_IDENTIFIER may be off. */ function quoteName(name: string, dialect?: string): string { - return /^(mysql|mariadb|bigquery|spark|databricks|hive)$/i.test(dialect ?? "") ? `\`${name}\`` : `"${name}"` + if (isSqlServerDialect(dialect)) return `[${name}]` + return /^(mysql|mariadb|clickhouse|bigquery|spark|databricks|hive)$/i.test(dialect ?? "") ? `\`${name}\`` : `"${name}"` } /** SQL Server and its aliases, whose batches run statements without separators and whose XML .query() takes XQuery. */ diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index b810507850..ca6215c429 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -342,6 +342,7 @@ describe("explainWrite", () => { expect(explainWrite("SELECT `t`.update FROM t", "mysql").reason).toContain("`t`.`update`") expect(explainWrite("SELECT Order Date FROM orders", "mysql").reason).toContain("(`order date`)") expect(explainWrite("SELECT Order Date FROM orders", "postgres").reason).toContain('("order date")') + expect(explainWrite("SELECT Order Date FROM orders", "sqlserver").reason).toContain("([order date])") }) test("every write in the guard corpus is a write with a specific reason", () => { From 050301b9902a24586156d4a2912778f416e0ece1 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 16:25:53 -0800 Subject: [PATCH 48/58] fix: case-correct quoting hints on ClickHouse, Snowflake and Oracle - ClickHouse's dotted-keyword hint quotes with backticks like the rest. - Snowflake/Oracle hints keep the qualifier as written and ask for the column in uppercase. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 2 +- packages/opencode/src/altimate/tools/sql-classify.ts | 4 ++-- .../test/altimate/tools/sql-readonly-guard-explain.test.ts | 5 ++++- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 5328b2b797..2e9a6e3f9b 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -131,5 +131,5 @@ export function writeReason(sql: string, dialect?: string): string { } const [statement, replace] = wordPatterns(dialect) const word = (statement.exec(body) ?? replace.exec(body))?.[0] - return word ? ` It contains the statement word ${word.toUpperCase()} outside a literal or comment, so the read-only permission does not cover it; quote it if it is a column name.` : "" + return word ? ` It contains the statement word ${word.toUpperCase()} outside a literal or comment, so the read-only permission does not cover it; quote it if it is a column name${/^(snowflake|oracle)$/i.test(dialect ?? "") ? ", in uppercase as this engine stores unquoted names" : ""}.` : "" } diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index dd879cd715..f6eec05c1a 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -754,12 +754,12 @@ export function explainWrite( if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { // Quoted names keep their case; engines that store unquoted names in uppercase need it written so. const quoted = /^(snowflake|oracle)$/i.test(dialect ?? "") - ? `${quoteName("T", dialect)}.${quoteName("UPDATE", dialect)} (this engine stores unquoted names in uppercase)` + ? `${quoteName("t", dialect)}.${quoteName("UPDATE", dialect)}, keeping the qualifier as written and the column in uppercase, as this engine stores unquoted names` : `${quoteName("t", dialect)}.${quoteName("update", dialect)}` return writes( dialect?.toLowerCase() === "clickhouse" ? `${where} contains a write clause (SELECT ... INTO or a modifying CTE), or a write keyword that on ClickHouse ` + - 'counts even after a dot: quote the column, t."update"' + `counts even after a dot: quote the column, t.${quoteName("update", dialect)}` : `${where} contains a write clause (SELECT ... INTO, INSERT/UPDATE/DELETE/MERGE inside a CTE, ` + `or a write keyword after a quoted name such as ${quoteName("t", dialect)}.update: quote the column too, ${quoted})`, ) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index ca6215c429..7d363176f6 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -336,13 +336,16 @@ describe("explainWrite", () => { expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).toContain('"t"."update"') expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).not.toContain("uppercase") const upper = explainWrite('SELECT "T".update FROM t', "snowflake").reason - expect(upper).toContain('"T"."UPDATE"') + expect(upper).toContain('"t"."UPDATE", keeping the qualifier as written') expect(upper).not.toContain('"t"."update"') + expect(writeReason("SELECT x AS load FROM t", "snowflake")).toContain("in uppercase") + expect(writeReason("SELECT x AS load FROM t", "postgres")).not.toContain("uppercase") // Where double quotes make a string, the hints use backticks. expect(explainWrite("SELECT `t`.update FROM t", "mysql").reason).toContain("`t`.`update`") expect(explainWrite("SELECT Order Date FROM orders", "mysql").reason).toContain("(`order date`)") expect(explainWrite("SELECT Order Date FROM orders", "postgres").reason).toContain('("order date")') expect(explainWrite("SELECT Order Date FROM orders", "sqlserver").reason).toContain("([order date])") + expect(explainWrite("SELECT t.update FROM t", "clickhouse").reason).toContain("t.`update`") }) test("every write in the guard corpus is a write with a specific reason", () => { From c7301174be9f8acb894c54176289700dcf5a2cb4 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 16:35:06 -0800 Subject: [PATCH 49/58] fix: pattern-rule refusals name the allowed patterns; hints fit the actual write - A pattern-rule denial lists the configured allow/ask patterns, as the rule dump did. - A plain SELECT INTO gets no quoted-name hint; that hint shows only after a quoted name. - CLI refusals lead with --allow-write. Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/sql-classify.ts | 17 +++++++++----- .../src/altimate/tools/sql-execute.ts | 11 +++++++++- .../tools/sql-readonly-guard-explain.test.ts | 6 +++++ .../altimate/tools/sql-readonly-guard.test.ts | 22 ++++++++++++++++--- 4 files changed, 47 insertions(+), 9 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index f6eec05c1a..f4c34cd823 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -756,12 +756,19 @@ export function explainWrite( const quoted = /^(snowflake|oracle)$/i.test(dialect ?? "") ? `${quoteName("t", dialect)}.${quoteName("UPDATE", dialect)}, keeping the qualifier as written and the column in uppercase, as this engine stores unquoted names` : `${quoteName("t", dialect)}.${quoteName("update", dialect)}` + // Name the dotted-keyword case only when the statement has a keyword right after a dot (after a quoted + // name, or any name on ClickHouse); otherwise the hint would point away from the real write clause. + const clickhouse = dialect?.toLowerCase() === "clickhouse" + const dotted = (clickhouse ? /\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i : /["`\]]\s*\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i).test(statement) + const clause = clickhouse + ? "a write clause (SELECT ... INTO or a modifying CTE)" + : "a write clause (SELECT ... INTO, or INSERT/UPDATE/DELETE/MERGE inside a CTE)" return writes( - dialect?.toLowerCase() === "clickhouse" - ? `${where} contains a write clause (SELECT ... INTO or a modifying CTE), or a write keyword that on ClickHouse ` + - `counts even after a dot: quote the column, t.${quoteName("update", dialect)}` - : `${where} contains a write clause (SELECT ... INTO, INSERT/UPDATE/DELETE/MERGE inside a CTE, ` + - `or a write keyword after a quoted name such as ${quoteName("t", dialect)}.update: quote the column too, ${quoted})`, + !dotted + ? `${where} contains ${clause}` + : clickhouse + ? `${where} contains a write keyword that on ClickHouse counts even after a dot: quote the column, t.${quoteName("update", dialect)}` + : `${where} contains a write keyword after a quoted name such as ${quoteName("t", dialect)}.update: quote the column too, ${quoted}`, ) } const keyword = batchedStatement(masked, dialect) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index c2d7002f6b..ab285a746a 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -303,6 +303,7 @@ export const SqlExecuteTool = Tool.define( }, }) } catch (error) { + let permitted: string[] = [] const explain = (readOnly: boolean, cli = false) => deniedWriteMessage({ sql, @@ -314,11 +315,13 @@ export const SqlExecuteTool = Tool.define( readOnly, cli, dbt: target?.dbt === true, + permitted, }) // The MCP server and `altimate tool` refuse writes unless --allow-write was given. if (error instanceof WriteDeniedError) throw new Error(`${explain(true, true)} ${error.message}`) if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error const rules: Array<{ pattern?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] + permitted = rules.filter((rule) => rule.action !== "deny" && rule.pattern).map((rule) => rule.pattern!) // Rules apply last-match-wins: the agent is read-only when the last catch-all rule denies and // nothing after it allows or asks (an agent's own deny can override a user's earlier "ask"). let lastCatchAllDeny = -1 @@ -782,6 +785,8 @@ export function deniedWriteMessage(input: { cli?: boolean /** The default route is dbt: passing a warehouse would also move the query off dbt, so no hint names it. */ dbt?: boolean + /** Configured sql_execute_write patterns that allow or ask (not user SQL), named so the agent can comply. */ + permitted?: string[] }): string { const readOnly = input.readOnly !== false const head = input.cli @@ -826,8 +831,12 @@ export function deniedWriteMessage(input: { ? "Fix the query and call sql_execute again; the same text will be refused again." + (readOnly ? "" : " The configured sql_execute_write rules may still deny it once it parses.") + dialectHint + : input.cli + ? "To write, re-run with --allow-write; otherwise rewrite it as a single read (SELECT, or WITH ... SELECT)." : !readOnly - ? "Change it to a statement the configured sql_execute_write rules allow, or ask the user to change the rules." + ? "Change it to a statement the configured sql_execute_write rules allow" + + (input.permitted?.length ? ` (they allow or ask for: ${input.permitted.slice(0, 10).map((p) => `\`${p}\``).join(", ")})` : "") + + ", or ask the user to change the rules." : input.scratch ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission, each call without reads; other statements (ATTACH, COPY, INSTALL, SET, ...) need write permission." : "Rewrite it as a single read (SELECT, or WITH ... SELECT). To keep an intermediate result, store it in scratch with sql_materialize if that tool is available." diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 7d363176f6..477688ad60 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -332,6 +332,12 @@ describe("explainWrite", () => { } }) + test("a plain SELECT INTO is named as a write clause without the quoted-name hint", () => { + const reason = explainWrite("SELECT a INTO newt FROM t", "postgres").reason + expect(reason).toContain("write clause") + expect(reason).not.toContain("quoted name") + }) + test("a quoted qualifier gets a specific hint", () => { expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).toContain('"t"."update"') expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).not.toContain("uppercase") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 235bc97ceb..5519b92125 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -332,6 +332,18 @@ describe("denied write message branches", () => { expect(message).toContain("rules allow") }) + test("a pattern-rule denial names the patterns the rules allow or ask for", () => { + const message = deniedWriteMessage({ ...base, sql: "DELETE FROM orders", readOnly: false, permitted: ["INSERT INTO audit*"] }) + expect(message).toContain("they allow or ask for: `INSERT INTO audit*`") + expect(deniedWriteMessage({ ...base, sql: "DELETE FROM orders", readOnly: false })).not.toContain("allow or ask for") + }) + + test("a CLI write refusal leads with --allow-write", () => { + const message = deniedWriteMessage({ ...base, sql: "CREATE TABLE t (a int)", cli: true }) + expect(message.indexOf("--allow-write")).toBeGreaterThan(-1) + expect(message.indexOf("--allow-write")).toBeLessThan(message.indexOf("single read")) + }) + test("an agent deny after a user's ask is still read-only", async () => { const tool = await initTool(SqlExecuteTool) const ruleset = [ @@ -353,9 +365,13 @@ describe("denied write message branches", () => { { permission: "sql_execute_write", pattern: "INSERT INTO audit*", action: "allow" }, ] const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } - await expect( - tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), - ).rejects.toThrow("A sql_execute_write permission rule denies it") + const error = await tool + .execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("A sql_execute_write permission rule denies it") + // The allowed pattern comes from the denial's own rules. + expect(error).toContain("`INSERT INTO audit*`") + expect(error).not.toContain("`*`") }) test("a pattern-only deny leaves other writes to the default ask, so it is not read-only", async () => { From 67ceaaa920d763ec5b09d1f19a1b5e28dc693df4 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:10:56 -0800 Subject: [PATCH 50/58] fix: honest write-clause hints; pattern names stay out of telemetry; ClickHouse pipes named - The dotted-keyword hint is chosen from masked code and covers spaced dots. - Named allow/ask patterns skip catch-alls and are single-quoted, so telemetry masks them. - The CLI states --allow-write once. - On ClickHouse a trailing `| head`-style pipe on a read is named (never `||`). Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/tools/sql-classify.ts | 18 ++++++++++++++--- .../src/altimate/tools/sql-execute.ts | 13 ++++++++---- .../tools/sql-readonly-guard-explain.test.ts | 10 ++++++++++ .../altimate/tools/sql-readonly-guard.test.ts | 20 +++++++++++++------ 4 files changed, 48 insertions(+), 13 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index f4c34cd823..f45dba4f4b 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -566,7 +566,13 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // ClickHouse's bundled parser accepts trailing text, so a shell redirect to a descriptor or /dev/null // (never SQL) would pass as a read. Treat such a read as unreadable so the residue is named, as on other // dialects; a write is already refused and named by its type. - if (queryType === "read" && dialect?.toLowerCase() === "clickhouse" && masked.search(SHELL_REDIRECT) >= 0) { + // A single trailing pipe into a shell command counts too (never `||`, ClickHouse's concatenation). A file tail + // does not: `a > b.csv` compares a column there. + if ( + queryType === "read" && + dialect?.toLowerCase() === "clickhouse" && + (masked.search(SHELL_REDIRECT) >= 0 || CLICKHOUSE_PIPE_TAIL.test(masked.slice(-400))) + ) { return { ...classifyFallback(sql, dialect), parseError: "shell redirect after the SQL" } } const writeTruncate = queryType === "write" && WRITE_TRUNCATE.test(namesKept(lexical.tokens)) @@ -584,6 +590,7 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // `x > 1.5` and `x > t.total` never match. The tail patterns run on at most 400 characters and have no // nested repetition. const SHELL_REDIRECT = /\s(?:[12]|&)?>>?[ \t]*(?:&[12]|\/dev\/null)(?![\w/])/g +const CLICKHOUSE_PIPE_TAIL = /(?>?[ \t]*(?:(?:\/|\.\.?\/|~\/)[\w./~-]*|[\w~-][\w~.-]*\.(?:csv|tsv|txt|json|jsonl|log|out|err|sql|parquet|tmp))[ \t]*$/i @@ -759,7 +766,12 @@ export function explainWrite( // Name the dotted-keyword case only when the statement has a keyword right after a dot (after a quoted // name, or any name on ClickHouse); otherwise the hint would point away from the real write clause. const clickhouse = dialect?.toLowerCase() === "clickhouse" - const dotted = (clickhouse ? /\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i : /["`\]]\s*\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i).test(statement) + // Read on masked code (quoted names blanked, literals and comments ignored): a keyword after a quoted + // name or a spaced dot counts; an unquoted t.update is a column and never reaches here. + const statementMasked = maskSql(tokenizeSql(statement, dialect).tokens) + const dotted = ( + clickhouse ? /\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i : /(?:(?:^|[^\w$])\s*|\s)\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b|\.\s+(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i + ).test(statementMasked) const clause = clickhouse ? "a write clause (SELECT ... INTO or a modifying CTE)" : "a write clause (SELECT ... INTO, or INSERT/UPDATE/DELETE/MERGE inside a CTE)" @@ -768,7 +780,7 @@ export function explainWrite( ? `${where} contains ${clause}` : clickhouse ? `${where} contains a write keyword that on ClickHouse counts even after a dot: quote the column, t.${quoteName("update", dialect)}` - : `${where} contains a write keyword after a quoted name such as ${quoteName("t", dialect)}.update: quote the column too, ${quoted}`, + : `${where} contains a write keyword after a quoted name or a spaced dot, such as ${quoteName("t", dialect)}.update: quote the column too, ${quoted}`, ) } const keyword = batchedStatement(masked, dialect) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index ab285a746a..03f1f22432 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -321,7 +321,11 @@ export const SqlExecuteTool = Tool.define( if (error instanceof WriteDeniedError) throw new Error(`${explain(true, true)} ${error.message}`) if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error const rules: Array<{ pattern?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] - permitted = rules.filter((rule) => rule.action !== "deny" && rule.pattern).map((rule) => rule.pattern!) + // Name specific patterns only: a catch-all "*" would read as "everything is allowed". Allow before ask. + permitted = [ + ...rules.filter((rule) => rule.action === "allow" && rule.pattern && rule.pattern !== "*"), + ...rules.filter((rule) => rule.action === "ask" && rule.pattern && rule.pattern !== "*"), + ].map((rule) => rule.pattern!) // Rules apply last-match-wins: the agent is read-only when the last catch-all rule denies and // nothing after it allows or asks (an agent's own deny can override a user's earlier "ask"). let lastCatchAllDeny = -1 @@ -785,7 +789,8 @@ export function deniedWriteMessage(input: { cli?: boolean /** The default route is dbt: passing a warehouse would also move the query off dbt, so no hint names it. */ dbt?: boolean - /** Configured sql_execute_write patterns that allow or ask (not user SQL), named so the agent can comply. */ + /** Configured sql_execute_write patterns that allow or ask, named so the agent can comply. Single-quoted, so + * telemetry's literal masking keeps config text out of recorded errors. */ permitted?: string[] }): string { const readOnly = input.readOnly !== false @@ -832,10 +837,10 @@ export function deniedWriteMessage(input: { (readOnly ? "" : " The configured sql_execute_write rules may still deny it once it parses.") + dialectHint : input.cli - ? "To write, re-run with --allow-write; otherwise rewrite it as a single read (SELECT, or WITH ... SELECT)." + ? "If a write is intended, see the --allow-write note below; otherwise rewrite it as a single read (SELECT, or WITH ... SELECT)." : !readOnly ? "Change it to a statement the configured sql_execute_write rules allow" + - (input.permitted?.length ? ` (they allow or ask for: ${input.permitted.slice(0, 10).map((p) => `\`${p}\``).join(", ")})` : "") + + (input.permitted?.length ? ` (they allow or ask for: ${input.permitted.slice(0, 10).map((p) => `'${p.replaceAll("'", "''")}'`).join(", ")})` : "") + ", or ask the user to change the rules." : input.scratch ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission, each call without reads; other statements (ATTACH, COPY, INSTALL, SET, ...) need write permission." diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 477688ad60..840f855802 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -40,6 +40,11 @@ describe("shellResidue", () => { for (const sql of ["SELECT a > 2 FROM t", "SELECT '2>/dev/null'", "SELECT 1 -- 2>/dev/null", "SELECT a || tail FROM t"]) { expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("read") } + expect(classifyAndCheck("SELECT * FROM t | head -5", "clickhouse").queryType).toBe("write") + expect(shellResidue("SELECT * FROM t | head -5", "clickhouse")).toBe("| head ...") + for (const sql of ["SELECT a || tail FROM t", "SELECT * FROM t WHERE a > b.csv"]) { + expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("read") + } // A write keeps its own reason rather than a parser failure. expect(explainWrite("DELETE FROM t 2>/dev/null", "clickhouse").reason).toBe("it is not a read (DELETE)") }) @@ -338,6 +343,11 @@ describe("explainWrite", () => { expect(reason).not.toContain("quoted name") }) + test("a spaced dot gets the quoting hint; a quoted name inside a comment does not", () => { + expect(explainWrite("SELECT t . update FROM t", "sqlserver").reason).toContain("spaced dot") + expect(explainWrite('SELECT a INTO newt FROM t -- "t".update', "postgres").reason).not.toContain("spaced dot") + }) + test("a quoted qualifier gets a specific hint", () => { expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).toContain('"t"."update"') expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).not.toContain("uppercase") diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 5519b92125..99b43babbb 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -89,6 +89,11 @@ describe("reads are classified as reads in every dialect", () => { expect(readSql("SELECT t.alter FROM t", "postgres")).toBe("SELECT t.alter FROM t") }) + test("a dotted word right before a real write clause stays a write", () => { + for (const dialect of ["postgres", "mysql"]) expect(isRead("SELECT a FROM t x.INTO t3", dialect)).toBe(false) + expect(isRead("SELECT a FROM t.into OUTFILE '/tmp/x'", "mysql")).toBe(false) + }) + test("ClickHouse keeps dotted write keywords as writes, since its parser accepts trailing text", () => { for (const sql of ["SELECT * FROM a.INTO OUTFILE '/tmp/x'", "SELECT a FROM t x.UPDATE t SET a = 1"]) { expect(isRead(sql, "clickhouse")).toBe(false) @@ -334,7 +339,7 @@ describe("denied write message branches", () => { test("a pattern-rule denial names the patterns the rules allow or ask for", () => { const message = deniedWriteMessage({ ...base, sql: "DELETE FROM orders", readOnly: false, permitted: ["INSERT INTO audit*"] }) - expect(message).toContain("they allow or ask for: `INSERT INTO audit*`") + expect(message).toContain("they allow or ask for: 'INSERT INTO audit*'") expect(deniedWriteMessage({ ...base, sql: "DELETE FROM orders", readOnly: false })).not.toContain("allow or ask for") }) @@ -370,8 +375,8 @@ describe("denied write message branches", () => { .then(() => "", (e: Error) => e.message) expect(error).toContain("A sql_execute_write permission rule denies it") // The allowed pattern comes from the denial's own rules. - expect(error).toContain("`INSERT INTO audit*`") - expect(error).not.toContain("`*`") + expect(error).toContain("'INSERT INTO audit*'") + expect(error).not.toContain("'*'") }) test("a pattern-only deny leaves other writes to the default ask, so it is not read-only", async () => { @@ -390,9 +395,12 @@ describe("denied write message branches", () => { { permission: "sql_execute_write", pattern: "DROP*", action: "deny" }, ] const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } - await expect( - tool.execute({ query: "DROP TABLE stg_tmp", warehouse: "guard_db", limit: 10 }, ctx as any), - ).rejects.toThrow("A sql_execute_write permission rule denies it") + const error = await tool + .execute({ query: "DROP TABLE stg_tmp", warehouse: "guard_db", limit: 10 }, ctx as any) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("A sql_execute_write permission rule denies it") + // A catch-all allow is not named as a pattern to comply with. + expect(error).not.toContain("allow or ask for") }) test("an unreadable query without a warehouse suggests passing one", () => { From d0585f01a9584f634a4ce43be46c82e04a9ed235 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:13:02 -0800 Subject: [PATCH 51/58] fix: name only sql_execute_write's own allow/ask patterns Wildcard-permission rules (the builder's "*": "allow" family) are about every tool, so they are not listed as statements the agent may run. A test pins that a quoted dotted keyword inside a string literal does not change the write-clause hint. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/sql-execute.ts | 14 +++++++++----- .../tools/sql-readonly-guard-explain.test.ts | 1 + .../test/altimate/tools/sql-readonly-guard.test.ts | 3 +++ 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 03f1f22432..099b5dc963 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -320,12 +320,16 @@ export const SqlExecuteTool = Tool.define( // The MCP server and `altimate tool` refuse writes unless --allow-write was given. if (error instanceof WriteDeniedError) throw new Error(`${explain(true, true)} ${error.message}`) if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error - const rules: Array<{ pattern?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] + const rules: Array<{ permission?: string; pattern?: string; action?: string }> = Array.isArray(error.ruleset) + ? error.ruleset + : [] + // Only this permission's own rules name statements; wildcard-permission rules (the builder's + // "*": "allow") are about every tool. // Name specific patterns only: a catch-all "*" would read as "everything is allowed". Allow before ask. - permitted = [ - ...rules.filter((rule) => rule.action === "allow" && rule.pattern && rule.pattern !== "*"), - ...rules.filter((rule) => rule.action === "ask" && rule.pattern && rule.pattern !== "*"), - ].map((rule) => rule.pattern!) + const own = rules.filter((rule) => rule.permission === "sql_execute_write" && rule.pattern && rule.pattern !== "*") + permitted = [...own.filter((rule) => rule.action === "allow"), ...own.filter((rule) => rule.action === "ask")].map( + (rule) => rule.pattern!, + ) // Rules apply last-match-wins: the agent is read-only when the last catch-all rule denies and // nothing after it allows or asks (an agent's own deny can override a user's earlier "ask"). let lastCatchAllDeny = -1 diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 840f855802..bd59c395c9 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -346,6 +346,7 @@ describe("explainWrite", () => { test("a spaced dot gets the quoting hint; a quoted name inside a comment does not", () => { expect(explainWrite("SELECT t . update FROM t", "sqlserver").reason).toContain("spaced dot") expect(explainWrite('SELECT a INTO newt FROM t -- "t".update', "postgres").reason).not.toContain("spaced dot") + expect(explainWrite(`SELECT '"t".update' INTO c FROM t`, "postgres").reason).not.toContain("spaced dot") }) test("a quoted qualifier gets a specific hint", () => { diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 99b43babbb..fb196fe981 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -366,6 +366,7 @@ describe("denied write message branches", () => { test("a catch-all deny followed by an allow is a rule, not read-only", async () => { const tool = await initTool(SqlExecuteTool) const ruleset = [ + { permission: "*", pattern: "prod_*", action: "allow" }, { permission: "sql_execute_write", pattern: "*", action: "deny" }, { permission: "sql_execute_write", pattern: "INSERT INTO audit*", action: "allow" }, ] @@ -377,6 +378,8 @@ describe("denied write message branches", () => { // The allowed pattern comes from the denial's own rules. expect(error).toContain("'INSERT INTO audit*'") expect(error).not.toContain("'*'") + // Rules for other permissions are not named. + expect(error).not.toContain("prod_") }) test("a pattern-only deny leaves other writes to the default ask, so it is not read-only", async () => { From 2645542e433a03edfd1ede6fd4160cf18b8924a9 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:15:44 -0800 Subject: [PATCH 52/58] fix: name only rule patterns still in effect after the last catch-all deny Rules apply last-match-wins, so an allow before a later `"*": "deny"` no longer applies and is not offered to the agent. Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/sql-execute.ts | 16 +++++++++------- .../altimate/tools/sql-readonly-guard.test.ts | 15 +++++++++++++++ 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 099b5dc963..08e3d720b6 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -323,19 +323,21 @@ export const SqlExecuteTool = Tool.define( const rules: Array<{ permission?: string; pattern?: string; action?: string }> = Array.isArray(error.ruleset) ? error.ruleset : [] - // Only this permission's own rules name statements; wildcard-permission rules (the builder's - // "*": "allow") are about every tool. - // Name specific patterns only: a catch-all "*" would read as "everything is allowed". Allow before ask. - const own = rules.filter((rule) => rule.permission === "sql_execute_write" && rule.pattern && rule.pattern !== "*") - permitted = [...own.filter((rule) => rule.action === "allow"), ...own.filter((rule) => rule.action === "ask")].map( - (rule) => rule.pattern!, - ) // Rules apply last-match-wins: the agent is read-only when the last catch-all rule denies and // nothing after it allows or asks (an agent's own deny can override a user's earlier "ask"). let lastCatchAllDeny = -1 rules.forEach((rule, index) => { if (rule.pattern === "*" && rule.action === "deny") lastCatchAllDeny = index }) + // Name only patterns still in effect (after that deny), from this permission's own rules (wildcard- + // permission rules such as the builder's "*": "allow" are about every tool), and never a catch-all, + // which would read as "everything is allowed". Allow before ask. + const own = rules + .slice(lastCatchAllDeny + 1) + .filter((rule) => rule.permission === "sql_execute_write" && rule.pattern && rule.pattern !== "*") + permitted = [...own.filter((rule) => rule.action === "allow"), ...own.filter((rule) => rule.action === "ask")].map( + (rule) => rule.pattern!, + ) // With no catch-all deny, writes the rules do not name fall to the default ("ask"). throw new Error( explain(lastCatchAllDeny >= 0 && !rules.slice(lastCatchAllDeny + 1).some((rule) => rule.action !== "deny")), diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index fb196fe981..ca565a2e2f 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -343,6 +343,21 @@ describe("denied write message branches", () => { expect(deniedWriteMessage({ ...base, sql: "DELETE FROM orders", readOnly: false })).not.toContain("allow or ask for") }) + test("a pattern overridden by a later catch-all deny is not named", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [ + { permission: "sql_execute_write", pattern: "INSERT INTO audit*", action: "allow" }, + { permission: "sql_execute_write", pattern: "*", action: "deny" }, + { permission: "sql_execute_write", pattern: "CREATE TEMP*", action: "allow" }, + ] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + const error = await tool + .execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("'CREATE TEMP*'") + expect(error).not.toContain("INSERT INTO audit") + }) + test("a CLI write refusal leads with --allow-write", () => { const message = deniedWriteMessage({ ...base, sql: "CREATE TABLE t (a int)", cli: true }) expect(message.indexOf("--allow-write")).toBeGreaterThan(-1) From b1a702f5af29728a620dafce3ac7ef82bce8df20 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:23:29 -0800 Subject: [PATCH 53/58] fix: ClickHouse pipe rule needs a flagged command; escape backslashes in named patterns - ClickHouse parses `|` as an operator, so only `| head -5`-style tails count; `a = b | head` stays a read. - Named rule patterns escape backslashes, so telemetry masks them even when one ends in `\`. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/sql-classify.ts | 8 +++++--- packages/opencode/src/altimate/tools/sql-execute.ts | 2 +- .../altimate/tools/sql-readonly-guard-explain.test.ts | 2 +- .../test/altimate/tools/sql-readonly-guard.test.ts | 11 +++++++++++ 4 files changed, 18 insertions(+), 5 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index f45dba4f4b..fb16ee40be 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -566,8 +566,8 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // ClickHouse's bundled parser accepts trailing text, so a shell redirect to a descriptor or /dev/null // (never SQL) would pass as a read. Treat such a read as unreadable so the residue is named, as on other // dialects; a write is already refused and named by its type. - // A single trailing pipe into a shell command counts too (never `||`, ClickHouse's concatenation). A file tail - // does not: `a > b.csv` compares a column there. + // A trailing pipe into a shell command with a flag counts too (never `||`, ClickHouse's concatenation). A file + // tail does not: `a > b.csv` compares a column there. if ( queryType === "read" && dialect?.toLowerCase() === "clickhouse" && @@ -590,7 +590,9 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { // `x > 1.5` and `x > t.total` never match. The tail patterns run on at most 400 characters and have no // nested repetition. const SHELL_REDIRECT = /\s(?:[12]|&)?>>?[ \t]*(?:&[12]|\/dev\/null)(?![\w/])/g -const CLICKHOUSE_PIPE_TAIL = /(?>?[ \t]*(?:(?:\/|\.\.?\/|~\/)[\w./~-]*|[\w~-][\w~.-]*\.(?:csv|tsv|txt|json|jsonl|log|out|err|sql|parquet|tmp))[ \t]*$/i diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 08e3d720b6..17d7cd5ede 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -846,7 +846,7 @@ export function deniedWriteMessage(input: { ? "If a write is intended, see the --allow-write note below; otherwise rewrite it as a single read (SELECT, or WITH ... SELECT)." : !readOnly ? "Change it to a statement the configured sql_execute_write rules allow" + - (input.permitted?.length ? ` (they allow or ask for: ${input.permitted.slice(0, 10).map((p) => `'${p.replaceAll("'", "''")}'`).join(", ")})` : "") + + (input.permitted?.length ? ` (they allow or ask for: ${input.permitted.slice(0, 10).map((p) => `'${p.replaceAll("\\", "\\\\").replaceAll("'", "''")}'`).join(", ")})` : "") + ", or ask the user to change the rules." : input.scratch ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission, each call without reads; other statements (ATTACH, COPY, INSTALL, SET, ...) need write permission." diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index bd59c395c9..1bb421d36c 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -42,7 +42,7 @@ describe("shellResidue", () => { } expect(classifyAndCheck("SELECT * FROM t | head -5", "clickhouse").queryType).toBe("write") expect(shellResidue("SELECT * FROM t | head -5", "clickhouse")).toBe("| head ...") - for (const sql of ["SELECT a || tail FROM t", "SELECT * FROM t WHERE a > b.csv"]) { + for (const sql of ["SELECT a || tail FROM t", "SELECT * FROM t WHERE a > b.csv", "SELECT x FROM t WHERE a = b | head"]) { expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("read") } // A write keeps its own reason rather than a parser failure. diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index ca565a2e2f..3cfb381511 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -343,6 +343,17 @@ describe("denied write message branches", () => { expect(deniedWriteMessage({ ...base, sql: "DELETE FROM orders", readOnly: false })).not.toContain("allow or ask for") }) + test("named rule patterns stay masked in telemetry, even with a trailing backslash or a quote", () => { + const message = deniedWriteMessage({ + ...base, + sql: "DELETE FROM orders", + readOnly: false, + permitted: ["INSERT INTO secret_tbl\\", "UPDATE it's_secret*"], + }) + expect(message).toContain("'INSERT INTO secret_tbl\\\\'") + expect(Telemetry.maskString(message)).not.toMatch(/secret/) + }) + test("a pattern overridden by a later catch-all deny is not named", async () => { const tool = await initTool(SqlExecuteTool) const ruleset = [ From 01d0a8c827210b06977a7720515c5ee94ca30994 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:30:46 -0800 Subject: [PATCH 54/58] fix: numbers never read as dotted names in hints; residue refusals skip the warehouse hint - The dotted-keyword hint reuses the masked statement and ignores numbers, so `1. INTO` is named as SELECT INTO. - Shell-residue refusals no longer suggest passing a warehouse. - The CLI note points to the --allow-write text at the end. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/sql-classify.ts | 7 ++++--- packages/opencode/src/altimate/tools/sql-execute.ts | 6 ++++-- .../test/altimate/tools/sql-readonly-guard-explain.test.ts | 3 +++ .../test/altimate/tools/sql-readonly-guard.test.ts | 6 ++++++ 4 files changed, 17 insertions(+), 5 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index fb16ee40be..a8de554301 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -768,9 +768,10 @@ export function explainWrite( // Name the dotted-keyword case only when the statement has a keyword right after a dot (after a quoted // name, or any name on ClickHouse); otherwise the hint would point away from the real write clause. const clickhouse = dialect?.toLowerCase() === "clickhouse" - // Read on masked code (quoted names blanked, literals and comments ignored): a keyword after a quoted - // name or a spaced dot counts; an unquoted t.update is a column and never reaches here. - const statementMasked = maskSql(tokenizeSql(statement, dialect).tokens) + // Read on masked code (quoted names blanked, literals and comments ignored) with numbers blanked too, so + // `1. INTO` stays a SELECT INTO: a keyword after a quoted name or a spaced dot counts; an unquoted t.update + // is a column and never reaches here. + const statementMasked = masked.replace(/\b\d+(?:\.\d*|\s*\.)?/g, (number) => " ".repeat(number.length)) const dotted = ( clickhouse ? /\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i : /(?:(?:^|[^\w$])\s*|\s)\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b|\.\s+(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i ).test(statementMasked) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 17d7cd5ede..7bad1d3a85 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -828,8 +828,10 @@ export function deniedWriteMessage(input: { // Without a warehouse (and off the dbt route, where a warehouse also moves the query off dbt), a query the // reachable dialects disagree on, or cannot read, may be fine in the real warehouse's dialect. const disagree = results.some((result) => result.queryType === "read" && !result.blocked) + // Shell syntax is not SQL in any dialect, so checking another dialect cannot help. + const residue = reason.startsWith("it contains shell syntax") const dialectHint = - input.warehouseGiven || input.dbt || input.dialects.length < 2 + residue || input.warehouseGiven || input.dbt || input.dialects.length < 2 ? "" : disagree ? " No warehouse was given and the reachable dialects disagree on whether this is a write; pass warehouse to check it in that warehouse's dialect only." @@ -843,7 +845,7 @@ export function deniedWriteMessage(input: { (readOnly ? "" : " The configured sql_execute_write rules may still deny it once it parses.") + dialectHint : input.cli - ? "If a write is intended, see the --allow-write note below; otherwise rewrite it as a single read (SELECT, or WITH ... SELECT)." + ? "If a write is intended, see the --allow-write note at the end; otherwise rewrite it as a single read (SELECT, or WITH ... SELECT)." : !readOnly ? "Change it to a statement the configured sql_execute_write rules allow" + (input.permitted?.length ? ` (they allow or ask for: ${input.permitted.slice(0, 10).map((p) => `'${p.replaceAll("\\", "\\\\").replaceAll("'", "''")}'`).join(", ")})` : "") + diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 1bb421d36c..3786e520a9 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -347,6 +347,9 @@ describe("explainWrite", () => { expect(explainWrite("SELECT t . update FROM t", "sqlserver").reason).toContain("spaced dot") expect(explainWrite('SELECT a INTO newt FROM t -- "t".update', "postgres").reason).not.toContain("spaced dot") expect(explainWrite(`SELECT '"t".update' INTO c FROM t`, "postgres").reason).not.toContain("spaced dot") + for (const sql of ["SELECT 1. INTO c FROM t", "SELECT 1 . INTO c FROM t"]) { + expect(explainWrite(sql, "postgres").reason).not.toContain("spaced dot") + } }) test("a quoted qualifier gets a specific hint", () => { diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts index 3cfb381511..ece856a7a0 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -432,6 +432,12 @@ describe("denied write message branches", () => { expect(error).not.toContain("allow or ask for") }) + test("shell residue without a warehouse does not suggest passing one", () => { + const message = deniedWriteMessage({ ...base, sql: "SELECT a FROM t 2>/dev/null", dialects: ["postgres", "snowflake"], warehouseGiven: false }) + expect(message).toContain("shell syntax") + expect(message).not.toContain("pass warehouse") + }) + test("an unreadable query without a warehouse suggests passing one", () => { const message = deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((", dialects: ["postgres", "snowflake"], warehouseGiven: false }) expect(message).toContain("pass warehouse") From 81d9e4e83a55f9a1da364ad98abca56783a81567 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:36:53 -0800 Subject: [PATCH 55/58] fix: residue is a flag from explainWrite; leading-dot decimals are numbers in hints - `explainWrite` returns `residue: true`, so the warehouse hint no longer depends on message wording. - `.5` and `-.5` are blanked with other numbers, so `SELECT .5 INTO` is named as SELECT INTO. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/sql-classify.ts | 10 ++++++---- packages/opencode/src/altimate/tools/sql-execute.ts | 3 +-- .../altimate/tools/sql-readonly-guard-explain.test.ts | 4 ++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index a8de554301..2df3ed78c3 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -685,11 +685,13 @@ function batchKeywordExplanation(dialect?: string): string { export function explainWrite( sql: string, dialect?: string, -): { reason: string; unreadable: boolean; unavailable?: boolean } { +): { reason: string; unreadable: boolean; unavailable?: boolean; residue?: boolean } { const unreadable = (reason: string) => ({ reason, unreadable: true }) const writes = (reason: string) => ({ reason, unreadable: false }) const residue = shellResidue(sql, dialect) - if (residue) return unreadable(`it contains shell syntax (\`${residue}\`), which is not SQL. Remove it and send only the SQL`) + if (residue) { + return { ...unreadable(`it contains shell syntax (\`${residue}\`), which is not SQL. Remove it and send only the SQL`), residue: true } + } const lexical = tokenizeSql(sql, dialect) if (!lexical.complete) { // An executable comment (/*! ... */) is closed but runs as SQL on some engines, so it is never read as one. @@ -769,9 +771,9 @@ export function explainWrite( // name, or any name on ClickHouse); otherwise the hint would point away from the real write clause. const clickhouse = dialect?.toLowerCase() === "clickhouse" // Read on masked code (quoted names blanked, literals and comments ignored) with numbers blanked too, so - // `1. INTO` stays a SELECT INTO: a keyword after a quoted name or a spaced dot counts; an unquoted t.update + // `1. INTO` and `.5 INTO` stay a SELECT INTO: a keyword after a quoted name or a spaced dot counts; an unquoted t.update // is a column and never reaches here. - const statementMasked = masked.replace(/\b\d+(?:\.\d*|\s*\.)?/g, (number) => " ".repeat(number.length)) + const statementMasked = masked.replace(/(? " ".repeat(number.length)) const dotted = ( clickhouse ? /\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i : /(?:(?:^|[^\w$])\s*|\s)\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b|\.\s+(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i ).test(statementMasked) diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 7bad1d3a85..bcef06a84c 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -824,12 +824,11 @@ export function deniedWriteMessage(input: { } chosen ??= explanation } - const { reason, unreadable, unavailable } = chosen ?? explainWrite(input.sql, undefined) + const { reason, unreadable, unavailable, residue } = chosen ?? explainWrite(input.sql, undefined) // Without a warehouse (and off the dbt route, where a warehouse also moves the query off dbt), a query the // reachable dialects disagree on, or cannot read, may be fine in the real warehouse's dialect. const disagree = results.some((result) => result.queryType === "read" && !result.blocked) // Shell syntax is not SQL in any dialect, so checking another dialect cannot help. - const residue = reason.startsWith("it contains shell syntax") const dialectHint = residue || input.warehouseGiven || input.dbt || input.dialects.length < 2 ? "" diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 3786e520a9..613e3a001c 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -280,7 +280,7 @@ test("unavailable", async () => { describe("explainWrite", () => { test("names shell residue", () => { const result = explainWrite("SELECT 1 2>/dev/null", "postgres") - expect(result).toEqual({ unreadable: true, reason: expect.stringContaining("`2>/dev/null`") }) + expect(result).toEqual({ unreadable: true, residue: true, reason: expect.stringContaining("`2>/dev/null`") }) }) test("carries the parser's position", () => { @@ -347,7 +347,7 @@ describe("explainWrite", () => { expect(explainWrite("SELECT t . update FROM t", "sqlserver").reason).toContain("spaced dot") expect(explainWrite('SELECT a INTO newt FROM t -- "t".update', "postgres").reason).not.toContain("spaced dot") expect(explainWrite(`SELECT '"t".update' INTO c FROM t`, "postgres").reason).not.toContain("spaced dot") - for (const sql of ["SELECT 1. INTO c FROM t", "SELECT 1 . INTO c FROM t"]) { + for (const sql of ["SELECT 1. INTO c FROM t", "SELECT 1 . INTO c FROM t", "SELECT .5 INTO c FROM t", "SELECT -.5 INTO c FROM t"]) { expect(explainWrite(sql, "postgres").reason).not.toContain("spaced dot") } }) From 54ad4d6c39f73c12cfa542484004eb208e438d20 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:45:59 -0800 Subject: [PATCH 56/58] fix: data_diff names the refused input; a parenthesized SELECT is told to drop the parentheses - Checks on SQL built around a table name or where_clause name that input instead of positions in the built text. - A read wrapped in parentheses gets its own reason. Co-Authored-By: Claude Opus 5.5 --- .../src/altimate/native/connections/data-diff.ts | 7 +++++-- .../opencode/src/altimate/tools/read-only-sql.ts | 16 ++++++++++++---- .../tools/sql-readonly-guard-explain.test.ts | 15 +++++++++++++++ 3 files changed, 32 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/altimate/native/connections/data-diff.ts b/packages/opencode/src/altimate/native/connections/data-diff.ts index 063b550003..df17f2725b 100644 --- a/packages/opencode/src/altimate/native/connections/data-diff.ts +++ b/packages/opencode/src/altimate/native/connections/data-diff.ts @@ -900,8 +900,11 @@ export async function runDataDiff(params: DataDiffParams): Promise { expect(reason).toContain("send a single SELECT or WITH query") }) + test("a parenthesized SELECT is told to drop the parentheses", () => { + expect(() => readSql("(SELECT 1)", "postgres")).toThrow("remove the outer parentheses") + }) + + test("a check on SQL built around user input names the input, not positions in the built text", () => { + let message = "" + try { + requireReadOnlyQuery("SELECT 1 WHERE (a = 1; DELETE FROM t)", "postgres", "where_clause") + } catch (error) { + message = (error as Error).message + } + expect(message).toContain("The where_clause must be part of a single read-only query") + expect(message).not.toContain("column") + }) + test("data_diff's embedded-query check names its reason too", () => { expect(() => requireReadOnlyQuery("SELECT 1; DELETE FROM t", "postgres")).toThrow("statement 2 of 2 is not a read (DELETE)") expect(() => requireReadOnlyQuery("SELECT 1; SELECT 2", "postgres")).toThrow("more than one statement") From 14e92f7e67f852ca6c3f88588e10d06cccf217e3 Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:52:54 -0800 Subject: [PATCH 57/58] fix: a read starting with a parenthesis gets advice that holds for set operations too The hint no longer claims the whole query is wrapped: it asks for a SELECT or WITH start, and for UNION-style branches to move into WITH or lose their parentheses. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 2 +- .../test/altimate/tools/sql-readonly-guard-explain.test.ts | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 7862c4c0f1..2865bfae7f 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -133,7 +133,7 @@ export function writeReason(sql: string, dialect?: string): string { "refused" in checked ? checked.refused : body!.startsWith("(") - ? "it is wrapped in parentheses; remove the outer parentheses" + ? "it starts with a parenthesis; start it with SELECT or WITH (for UNION or a similar set operation, put the parenthesized branches in a WITH query or drop their parentheses)" : "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" return ` This read is invalid here because ${cause}; send a single SELECT or WITH query that can be embedded.` } diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 504e9b0eb6..2b29559959 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -252,8 +252,10 @@ test("unavailable", async () => { expect(reason).toContain("send a single SELECT or WITH query") }) - test("a parenthesized SELECT is told to drop the parentheses", () => { - expect(() => readSql("(SELECT 1)", "postgres")).toThrow("remove the outer parentheses") + test("a read starting with a parenthesis is told to start with SELECT or WITH", () => { + for (const sql of ["(SELECT 1)", "(SELECT 1) UNION ALL (SELECT 2)"]) { + expect(() => readSql(sql, "postgres")).toThrow("start it with SELECT or WITH") + } }) test("a check on SQL built around user input names the input, not positions in the built text", () => { From 77469155ab6b880ee21306ec0b04da139096114c Mon Sep 17 00:00:00 2001 From: anandgupta42 Date: Sat, 21 Nov 2026 18:56:24 -0800 Subject: [PATCH 58/58] fix: the parenthesis reason no longer repeats the closing advice Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/read-only-sql.ts | 2 +- .../test/altimate/tools/sql-readonly-guard-explain.test.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 2865bfae7f..54ee0b148a 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -133,7 +133,7 @@ export function writeReason(sql: string, dialect?: string): string { "refused" in checked ? checked.refused : body!.startsWith("(") - ? "it starts with a parenthesis; start it with SELECT or WITH (for UNION or a similar set operation, put the parenthesized branches in a WITH query or drop their parentheses)" + ? "it starts with a parenthesis (for UNION or a similar set operation, move the parenthesized branches into a WITH query or drop their parentheses)" : "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" return ` This read is invalid here because ${cause}; send a single SELECT or WITH query that can be embedded.` } diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts index 2b29559959..18c476fd57 100644 --- a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -254,7 +254,7 @@ test("unavailable", async () => { test("a read starting with a parenthesis is told to start with SELECT or WITH", () => { for (const sql of ["(SELECT 1)", "(SELECT 1) UNION ALL (SELECT 2)"]) { - expect(() => readSql(sql, "postgres")).toThrow("start it with SELECT or WITH") + expect(() => readSql(sql, "postgres")).toThrow("it starts with a parenthesis") } })