feat(nl2sql): prompt-injection boundary defence + EXPLAIN dry-run pre-flight

[devopam]

Summary

Ships the two remaining security-hardening.md items — both scoped to translate_nl_to_sql, both now ✅.

1. Prompt-injection boundary defence. Defence-in-depth at the prompt layer (the AST allowlist stays the enforcement backstop):

• The user question is fenced in <user_request> … </user_request> delimiters.
• The system prompt instructs the model to treat that text as data, never instructions, and to refuse any out-of-scope request (write/DDL, secrets, "ignore previous instructions") by emitting the sentinel -- MCPG_REFUSED: <reason>.
• translate_nl_to_sql detects the sentinel (in the JSON sql field or a bare reply) and returns TranslationResult(refused=True, refusal_reason=…) with empty sql — never forwarding it to SafeSqlDriver / execution.

2. EXPLAIN dry-run pre-flight. Semantic validation before returning/executing:

• Runs a non-executing EXPLAIN (reusing mcpg.query.explain_query, so the SQL is SafeSqlDriver-validated first) to catch queries that pass the structural allowlist but reference a non-existent column/table or mistype something.
• Planner rejection → structured error="query invalid: <message>" (SQL returned for inspection, nothing executed). A pre-flight statement_timeout degrades to "proceed" rather than blocking a valid translation.
• New explain_preflight tool arg (default on), bypassable per call.

Surface/return-shape changes: TranslationResult gains refused / refusal_reason; the tool gains the explain_preflight input. Both contract snapshots regenerated (diffs scoped to exactly these). 5 new unit tests (delimiter wrap, JSON-field + bare-line refusal, invalid-query pre-flight, pre-flight bypass); 101 unit + contract tests green; ruff/mypy clean.

Roadmap linkage

Advances roadmap row: N/A — clears the two open items in docs/security-hardening.md (marked ✅ in this PR).

Checklist

• Tests added first; suite passes locally (101 relevant tests green)
• ruff, ruff format, and mypy src/mcpg pass
• CHANGELOG.md updated under [Unreleased]
• Both contract snapshots regenerated + committed
• No hand-edits to src/mcpg/_vendor/

🤖 Generated with Claude Code

---

Generated by Claude Code

Summary by Sourcery

Strengthen nl2sql security and robustness by adding prompt-injection refusal handling and an EXPLAIN-based semantic pre-flight check, and surface these via extended TranslationResult and tool parameters.

New Features:

• Add prompt-level refusal mechanism where the model can decline out-of-scope or injected requests using a refusal sentinel that is surfaced as a structured TranslationResult.
• Introduce an EXPLAIN-based dry-run pre-flight for nl2sql translations, controllable via a new explain_preflight argument and enabled by default.

Enhancements:

• Extend TranslationResult with refusal metadata to distinguish clean refusals from other error conditions.
• Update the nl2sql system prompt to wrap user questions in explicit delimiters and emphasize treating them as data, not instructions.

Documentation:

• Mark the nl2sql prompt-injection hardening and EXPLAIN pre-flight items as shipped in security-hardening documentation, describing the new behaviour and controls.

Tests:

• Add unit tests covering user question delimiter wrapping, refusal sentinel handling in both JSON and bare responses, EXPLAIN pre-flight invalid-query reporting, and the ability to disable pre-flight.

Chores:

• Regenerate contract snapshots and update the changelog to reflect the new nl2sql security and validation behaviours.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="src/mcpg/tools.py" line_range="3164" />
<code_context>
     question: str,
     schema: str,
     execute: bool = False,
+    explain_preflight: bool = True,
     table_filter: tuple[str, ...] | None = None,
     max_tokens: int = DEFAULT_MAX_TOKENS,
</code_context>
<issue_to_address>
**issue (bug_risk):** Adding `explain_preflight` before `table_filter` changes positional argument order and can break existing callers.

Because this is a public-facing function, inserting `explain_preflight` before `table_filter` changes the positional argument order and can silently misroute arguments for any existing positional callers. To avoid breaking those callers, consider adding `explain_preflight` at the end of the parameter list or making new parameters keyword-only.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist-2]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.