From 89743839670cee85b2c73452b8d83808b52f38fb Mon Sep 17 00:00:00 2001
From: Elias Bachaalany <elias.bachaalany@gmail.com>
Date: Tue, 23 Jun 2026 10:25:03 -0700
Subject: [PATCH] feat: ?format= output option + intent-driven output guidance

- Bump libxsql pin v1.0.5 -> v1.0.7 (brings ?format=text|csv|tsv on /query,
  handled in the shared thinclient; JSON stays the default).
- Document format= in the HTTP /help text and README.
- Rewrite agent guide 'ALWAYS Show Actual Data' into Selection/Fidelity/
  Mechanics: decide display by intent, show real artifacts, consume the JSON
  envelope rather than piping through a reformatter.
---
 CMakeLists.txt             |  2 +-
 README.md                  |  4 ++++
 prompts/ghidrasql_agent.md | 22 ++++++++++++++++++++--
 src/lib/src/http.cpp       |  3 +++
 4 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 7e9bc07..0909200 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -65,7 +65,7 @@ else()
     message(STATUS "ghidrasql: Fetching libxsql from GitHub (shallow clone)...")
     FetchContent_Declare(libxsql
         GIT_REPOSITORY https://github.com/0xeb/libxsql.git
-        GIT_TAG        v1.0.5
+        GIT_TAG        v1.0.7
         GIT_SHALLOW    TRUE
     )
     FetchContent_MakeAvailable(libxsql)
diff --git a/README.md b/README.md
index 75c9f8f..ccea57a 100644
--- a/README.md
+++ b/README.md
@@ -129,6 +129,10 @@ ghidrasql --ghidra /path/to/ghidra_dist \
   --serve --port 8081
 
 # Then query it: curl -X POST http://localhost:8081/query -d "SELECT * FROM funcs LIMIT 5"
+
+# Output format for terminals/pipes (default is JSON; agents should consume JSON):
+#   curl -X POST "http://localhost:8081/query?format=text" -d "SELECT name,size FROM funcs LIMIT 5"
+#   format=json (default) | text (ASCII table) | csv | tsv
 ```
 
 ## Example Queries
diff --git a/prompts/ghidrasql_agent.md b/prompts/ghidrasql_agent.md
index e2790f8..d961e37 100644
--- a/prompts/ghidrasql_agent.md
+++ b/prompts/ghidrasql_agent.md
@@ -1528,9 +1528,19 @@ curl -X POST http://localhost:8081/query -H "Authorization: Bearer mysecret" \
 
 ## Output Guidelines
 
-### ALWAYS Show Actual Data
+### Deciding what to show
 
-When the user asks to see something (decompilation, code, data), **ALWAYS include the actual output** in your response — don't just describe it.
+Showing data serves the user's intent — it is not automatic. Keep three concerns separate:
+
+**Selection — *whether* and *how much* to show.** A judgment driven by what was asked:
+- They asked to *see* something (decompile, list the strings) → show it.
+- They asked a *question* the data answers (biggest function? does it call malloc?) →
+  answer directly ("biggest is `main`, 135 bytes"), surfacing supporting rows only when they
+  help the user verify. Don't dump full tables unprompted.
+- You queried only to decide your next step → don't show it; it's internal.
+
+**Fidelity — when you *do* present code or data, show the real artifact, not a paraphrase.**
+Never describe what code does in place of showing it:
 
 **BAD:**
 > "The function appears to call malloc and contains a loop..."
@@ -1549,6 +1559,14 @@ int parseConfig(const char *path) {
 }
 ```
 
+**Mechanics — consume the JSON; don't reformat it for display.** Over HTTP, `/query` returns a
+JSON envelope (`{success, results:[{columns,rows,…}]}`). Parse it yourself and render in your
+reply. Do **not** pipe responses through `python`/`jq`/`awk` to pre-render a table — that
+discards `success`/`elapsed_ms`/`error` and makes you reason over a lossy view. Reserve
+`jq`/`python` for extracting a value to feed a later query. The CLI (`-q`) already prints a
+table. (For direct terminal/pipe use, the server can emit `?format=text|csv|tsv` — but as an
+agent, consume `json`.)
+
 ### Addresses in Hex
 Always display addresses in hex format using `printf('0x%X', address)`.
 
diff --git a/src/lib/src/http.cpp b/src/lib/src/http.cpp
index f018e83..37eab3f 100644
--- a/src/lib/src/http.cpp
+++ b/src/lib/src/http.cpp
@@ -92,6 +92,9 @@ static std::string build_http_help_text() {
         "  }\n"
         "  Failure: {\"success\": false, \"error\": \"message\", \"statement_count\": N, \"results\": [...]}\n"
         "  Single-statement bodies use the same shape with statement_count == 1.\n\n"
+        "Query Options (query string):\n"
+        "  format=json|text|csv|tsv  (default json; text/csv/tsv are for terminal/\n"
+        "                             pipe use \xE2\x80\x94 agents should consume json)\n\n"
         "Example (single statement):\n"
         "  curl -X POST http://localhost:<port>/query -d \"SELECT name FROM funcs LIMIT 10\"\n"
         "Example (multi-statement):\n"