fix: pre-execution SQL validation, apply_patch retry, agent behavior rules, and error UX

- Wire datafusion validation into sql_execute — catches column/table errors
  locally before hitting the warehouse (uses schema cache with 24h TTL)
- Add sql_pre_validation telemetry event to measure catch rate and latency
- Add apply_patch retry-with-re-read on verification failure — re-reads
  the file and retries once before giving up, with actionable error messages
- Add file-not-found cache in read tool — prevents retry loops on missing
  paths (capped at 500 entries)
- Add agent behavior rules to system prompt: act first/ask later, enforce
  read-before-edit, limit retries to 2 per input
- Add actionable connection error guidance in warehouse_test — maps common
  auth failures (wrong password, missing key, SSO timeout) to fix instructions
- Auto-pull schema cache in altimate_core_validate when no schema provided

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anandgupta42

packages/opencode/src/altimate/telemetry/index.ts

@@ -446,6 +446,20 @@ export namespace Telemetry {
         duration_ms: number
       }
   // altimate_change end
+    // altimate_change start — pre-execution SQL validation telemetry
+    | {
+        type: "sql_pre_validation"
+        timestamp: number
+        session_id: string
+        /** skipped = no cache or stale, passed = valid SQL, blocked = invalid SQL caught, error = validation itself failed */
+        outcome: "skipped" | "passed" | "blocked" | "error"
+        /** why: no_cache, stale_cache, empty_cache, valid, non_structural, structural_error, validation_exception */
+        reason: string
+        schema_columns: number
+        duration_ms: number
+        error_message?: string
+      }
+    // altimate_change end
 
   // altimate_change start — expanded error classification patterns for better triage
   // Order matters: earlier patterns take priority. Use specific phrases, not

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

@@ -2,6 +2,9 @@ import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
 import type { Telemetry } from "../telemetry"
+// altimate_change start — auto-pull schema from cache when not provided
+import { getCache } from "../native/schema/cache"
+// altimate_change end
 
 export const AltimateCoreValidateTool = Tool.define("altimate_core_validate", {
   description:
@@ -12,11 +15,20 @@ export const AltimateCoreValidateTool = Tool.define("altimate_core_validate", {
     schema_context: z.record(z.string(), z.any()).optional().describe("Inline schema definition"),
   }),
   async execute(args, ctx) {
-    const hasSchema = !!(args.schema_path || (args.schema_context && Object.keys(args.schema_context).length > 0))
+    let hasSchema = !!(args.schema_path || (args.schema_context && Object.keys(args.schema_context).length > 0))
+    // altimate_change start — auto-pull schema from cache when not provided
+    if (!hasSchema) {
+      const cachedSchema = await tryGetSchemaFromCache()
+      if (cachedSchema) {
+        args = { ...args, schema_context: cachedSchema }
+        hasSchema = true
+      }
+    }
+    // altimate_change end
     const noSchema = !hasSchema
     if (noSchema) {
       const error =
-        "No schema provided. Provide schema_context or schema_path so table/column references can be resolved."
+        "No schema provided. Provide schema_context or schema_path so table/column references can be resolved. Tip: run schema_index first to cache your warehouse schema."
       return {
         title: "Validate: NO SCHEMA",
         metadata: { success: false, valid: false, has_schema: false, error },
@@ -77,6 +89,41 @@ function classifyValidationError(message: string): string {
   return "validation_error"
 }
 
+// altimate_change start — auto-pull schema from cache when not provided
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000
+
+async function tryGetSchemaFromCache(): Promise<Record<string, any> | null> {
+  try {
+    const cache = await getCache()
+    const status = cache.cacheStatus()
+    const warehouse = status.warehouses[0]
+    if (!warehouse?.last_indexed) return null
+
+    const cacheAge = Date.now() - new Date(warehouse.last_indexed).getTime()
+    if (cacheAge > CACHE_TTL_MS) return null
+
+    const columns = cache.listColumns(warehouse.name, 10_000)
+    if (columns.length === 0) return null
+
+    const schemaContext: Record<string, any> = {}
+    for (const col of columns) {
+      const tableName = col.schema_name ? `${col.schema_name}.${col.table}` : col.table
+      if (!schemaContext[tableName]) {
+        schemaContext[tableName] = []
+      }
+      schemaContext[tableName].push({
+        name: col.name,
+        type: col.data_type || "VARCHAR",
+        nullable: col.nullable,
+      })
+    }
+    return schemaContext
+  } catch {
+    return null
+  }
+}
+// altimate_change end
+
 function formatValidate(data: Record<string, any>): string {
   if (data.error) return `Error: ${data.error}`
   if (data.valid) return "SQL is valid."

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

@@ -8,6 +8,10 @@ import { classifyAndCheck } from "./sql-classify"
 // altimate_change start — progressive disclosure suggestions
 import { PostConnectSuggestions } from "./post-connect-suggestions"
 // altimate_change end
+// altimate_change start — pre-execution SQL validation via cached schema
+import { getCache } from "../native/schema/cache"
+import { Telemetry } from "../../telemetry"
+// altimate_change end
 
 export const SqlExecuteTool = Tool.define("sql_execute", {
   description: "Execute SQL against a connected data warehouse. Returns results as a formatted table.",
@@ -33,6 +37,17 @@ export const SqlExecuteTool = Tool.define("sql_execute", {
     }
     // altimate_change end
 
+    // altimate_change start — pre-execution SQL validation via cached schema
+    const preValidation = await preValidateSql(args.query, args.warehouse)
+    if (preValidation.blocked) {
+      return {
+        title: "SQL: VALIDATION ERROR",
+        metadata: { rowCount: 0, truncated: false, error: preValidation.error },
+        output: preValidation.error!,
+      }
+    }
+    // altimate_change end
+
     try {
       const result = await Dispatcher.call("sql.execute", {
         sql: args.query,
@@ -68,6 +83,135 @@ export const SqlExecuteTool = Tool.define("sql_execute", {
   },
 })
 
+// altimate_change start — pre-execution SQL validation via cached schema
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+interface PreValidationResult {
+  blocked: boolean
+  error?: string
+}
+
+async function preValidateSql(sql: string, warehouse?: string): Promise<PreValidationResult> {
+  const startTime = Date.now()
+  try {
+    const cache = await getCache()
+    const status = cache.cacheStatus()
+
+    // Find the target warehouse in cache
+    const warehouseName = warehouse || status.warehouses[0]?.name
+    if (!warehouseName) {
+      trackPreValidation("skipped", "no_cache", 0, Date.now() - startTime)
+      return { blocked: false }
+    }
+
+    const warehouseStatus = status.warehouses.find((w) => w.name === warehouseName)
+    if (!warehouseStatus?.last_indexed) {
+      trackPreValidation("skipped", "no_cache", 0, Date.now() - startTime)
+      return { blocked: false }
+    }
+
+    // Check cache freshness
+    const cacheAge = Date.now() - new Date(warehouseStatus.last_indexed).getTime()
+    if (cacheAge > CACHE_TTL_MS) {
+      trackPreValidation("skipped", "stale_cache", 0, Date.now() - startTime)
+      return { blocked: false }
+    }
+
+    // Build schema context from cached columns
+    const columns = cache.listColumns(warehouseName, 10_000)
+    if (columns.length === 0) {
+      trackPreValidation("skipped", "empty_cache", 0, Date.now() - startTime)
+      return { blocked: false }
+    }
+
+    const schemaContext: Record<string, any> = {}
+    for (const col of columns) {
+      const tableName = col.schema_name ? `${col.schema_name}.${col.table}` : col.table
+      if (!schemaContext[tableName]) {
+        schemaContext[tableName] = []
+      }
+      schemaContext[tableName].push({
+        name: col.name,
+        type: col.data_type || "VARCHAR",
+        nullable: col.nullable,
+      })
+    }
+
+    // Validate SQL against cached schema
+    const validationResult = await Dispatcher.call("altimate_core.validate", {
+      sql,
+      schema_path: "",
+      schema_context: schemaContext,
+    })
+
+    const data = (validationResult.data ?? {}) as Record<string, any>
+    const errors = Array.isArray(data.errors) ? data.errors : []
+    const isValid = data.valid !== false && errors.length === 0
+
+    if (isValid) {
+      trackPreValidation("passed", "valid", columns.length, Date.now() - startTime)
+      return { blocked: false }
+    }
+
+    // Only block on high-confidence structural errors
+    const structuralErrors = errors.filter((e: any) => {
+      const msg = (e.message ?? "").toLowerCase()
+      return msg.includes("column") || msg.includes("table") || msg.includes("not found") || msg.includes("does not exist")
+    })
+
+    if (structuralErrors.length === 0) {
+      // Non-structural errors (ambiguous cases) — let them through
+      trackPreValidation("passed", "non_structural", columns.length, Date.now() - startTime)
+      return { blocked: false }
+    }
+
+    // Build helpful error with available columns
+    const errorMsgs = structuralErrors.map((e: any) => e.message).join("\n")
+    const referencedTables = Object.keys(schemaContext).slice(0, 10)
+    const availableColumns = referencedTables
+      .map((t) => `${t}: ${schemaContext[t].map((c: any) => c.name).join(", ")}`)
+      .join("\n")
+
+    const errorOutput = [
+      `Pre-execution validation failed (validated against cached schema):`,
+      ``,
+      errorMsgs,
+      ``,
+      `Available tables and columns:`,
+      availableColumns,
+      ``,
+      `Fix the query and retry. If the schema cache is outdated, run schema_index to refresh it.`,
+    ].join("\n")
+
+    trackPreValidation("blocked", "structural_error", columns.length, Date.now() - startTime, errorMsgs)
+    return { blocked: true, error: errorOutput }
+  } catch {
+    // Validation failure should never block execution
+    trackPreValidation("error", "validation_exception", 0, Date.now() - startTime)
+    return { blocked: false }
+  }
+}
+
+function trackPreValidation(
+  outcome: "skipped" | "passed" | "blocked" | "error",
+  reason: string,
+  schema_columns: number,
+  duration_ms: number,
+  error_message?: string,
+) {
+  Telemetry.track({
+    type: "sql_pre_validation",
+    timestamp: Date.now(),
+    session_id: Telemetry.getContext().sessionId,
+    outcome,
+    reason,
+    schema_columns,
+    duration_ms,
+    ...(error_message && { error_message: error_message.slice(0, 500) }),
+  })
+}
+// altimate_change end
+
 function formatResult(result: SqlExecuteResult): string {
   if (result.row_count === 0) return "(0 rows)"
 

packages/opencode/src/altimate/tools/warehouse-test.ts

@@ -20,10 +20,14 @@ export const WarehouseTestTool = Tool.define("warehouse_test", {
         }
       }
 
+      // altimate_change start — actionable error guidance for common auth failures
+      const errorDetail = result.error ?? "Unknown error"
+      const guidance = getConnectionGuidance(errorDetail)
+      // altimate_change end
       return {
         title: `Connection '${args.name}': FAILED`,
         metadata: { connected: false },
-        output: `Failed to connect to warehouse '${args.name}'.\nError: ${result.error ?? "Unknown error"}`,
+        output: `Failed to connect to warehouse '${args.name}'.\nError: ${errorDetail}${guidance}`,
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)
@@ -35,3 +39,36 @@ export const WarehouseTestTool = Tool.define("warehouse_test", {
     }
   },
 })
+
+// altimate_change start — actionable error guidance for common auth failures
+function getConnectionGuidance(error: string): string {
+  const lower = error.toLowerCase()
+
+  if (lower.includes("password") && (lower.includes("incorrect") || lower.includes("authentication failed"))) {
+    return "\n\nHow to fix: Check the password in your connection config. Verify the username has access from your current IP address. Use `warehouse_remove` then `warehouse_add` to re-enter credentials."
+  }
+  if (lower.includes("password must be a string") || lower.includes("scram")) {
+    return "\n\nHow to fix: The password field is missing or not a string. Check your connection config — the password may be empty or set to a non-string value. Use `warehouse_remove` then `warehouse_add` to re-configure."
+  }
+  if (lower.includes("private key") || lower.includes("decrypt")) {
+    return "\n\nHow to fix: Key pair authentication failed. Verify: (1) the key file is PEM/PKCS#8 format, (2) the passphrase is correct, (3) the key has not expired, (4) the public key is registered in your warehouse."
+  }
+  if (lower.includes("missing") && lower.includes("password")) {
+    return "\n\nHow to fix: No password was provided. Use `warehouse_remove` then `warehouse_add` to configure credentials. For Snowflake, you can also use key pair or SSO authentication."
+  }
+  if (lower.includes("browser") && lower.includes("timed out")) {
+    return "\n\nHow to fix: SSO browser authentication timed out. Ensure your default browser opened the auth page. If running in a headless environment, switch to password or key pair authentication instead."
+  }
+  if (lower.includes("not installed") || lower.includes("cannot find module")) {
+    return "\n\nHow to fix: The database driver is not installed. Run `npm install` with the appropriate driver package for your database type."
+  }
+  if (lower.includes("econnrefused") || lower.includes("enotfound")) {
+    return "\n\nHow to fix: Cannot reach the database server. Check: (1) the hostname and port are correct, (2) the server is running, (3) any firewalls or VPNs are configured to allow the connection."
+  }
+  if (lower.includes("schema") && (lower.includes("does not exist") || lower.includes("not authorized"))) {
+    return "\n\nHow to fix: The specified schema does not exist or your user lacks access. Check: (1) the schema name is spelled correctly, (2) your user/role has USAGE privilege on the schema."
+  }
+
+  return ""
+}
+// altimate_change end

packages/opencode/src/session/prompt/anthropic.txt

@@ -69,9 +69,27 @@ I've found some existing telemetry code. Let me mark the first todo as in_progre
 
 # Doing tasks
 The user will primarily request you perform software engineering tasks. This includes solving bugs, adding new functionality, refactoring code, explaining code, and more. For these tasks the following steps are recommended:
-- 
+-
 - Use the TodoWrite tool to plan the task if required
 
+<!-- altimate_change start — bias toward action, reduce over-questioning, enforce read-before-edit -->
+# Agent behavior rules
+
+## Act first, ask later
+- Start working immediately. Do NOT ask clarifying questions unless the request is genuinely ambiguous with multiple incompatible interpretations.
+- If you can make a reasonable assumption, make it and state what you assumed. The user can correct you.
+- Prefer taking a small action (scan the project, read a file, check the schema) over asking the user what to do.
+
+## Always read before editing
+- NEVER call edit, write, or apply_patch on a file you have not read in the current session.
+- If apply_patch fails with "Failed to find expected lines", re-read the file immediately and generate a new patch from the fresh content. Do NOT retry the same patch.
+- After a file_not_found error on a specific path, do NOT attempt to read that same path again. Move on or ask the user.
+
+## Limit retries
+- If a tool call fails twice on the same input, do NOT retry a third time. Instead, explain what went wrong and try an alternative approach.
+- If apply_patch or edit fails on the same file twice, re-read the file, then try once more with fresh content. If that also fails, stop and report the issue.
+<!-- altimate_change end -->
+
 - Tool results and user messages may include <system-reminder> tags. <system-reminder> tags contain useful information and reminders. They are automatically added by the system, and bear no direct relation to the specific tool results or user messages in which they appear.
 
 

packages/opencode/src/tool/apply_patch.ts

@@ -100,13 +100,30 @@ export const ApplyPatchTool = Tool.define("apply_patch", {
           const oldContent = await fs.readFile(filePath, "utf-8")
           let newContent = oldContent
 
+          // altimate_change start — retry patch application with re-read on mismatch
           // Apply the update chunks to get new content
           try {
             const fileUpdate = Patch.deriveNewContentsFromChunks(filePath, hunk.chunks)
             newContent = fileUpdate.content
           } catch (error) {
-            throw new Error(`apply_patch verification failed: ${error}`)
+            // Re-read the file and retry once — the file may have changed since the LLM last saw it
+            const freshContent = await fs.readFile(filePath, "utf-8")
+            if (freshContent !== oldContent) {
+              try {
+                const retryUpdate = Patch.deriveNewContentsFromChunks(filePath, hunk.chunks)
+                newContent = retryUpdate.content
+              } catch (retryError) {
+                throw new Error(
+                  `apply_patch verification failed: ${retryError}\n\nThe file has been modified since you last read it. Please re-read the file and generate a new patch.`,
+                )
+              }
+            } else {
+              throw new Error(
+                `apply_patch verification failed: ${error}\n\nThe expected lines were not found in the file. Please re-read the file and generate a new patch based on its current contents.`,
+              )
+            }
           }
+          // altimate_change end
 
           const diff = trimDiff(createTwoFilesPatch(filePath, filePath, oldContent, newContent))