pythia-plsql 0.9.0__tar.gz → 0.10.0__tar.gz

{pythia_plsql-0.9.0/scripts/pythia_plsql.egg-info → pythia_plsql-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.9.0
+Version: 0.10.0
 Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -101,11 +101,14 @@ through one door: **snapshot → impact → preview → token → approve → ap
 verify → report**. DDL self-commits in Oracle, so the snapshot is the only real
 undo — it runs first and no flag disables it. A content-bound token guarantees
 what lands is byte-for-byte what was previewed, and a **developer-minted grant**
-guarantees a person approved it at all: `pythia approve` runs only at a human's
-own console, and without its one-time grant `apply --confirm` refuses. The
-agent's command line is unchanged; what changed is that it now stops until
-someone acts. A headless agent cannot `--yes` its own writes, cannot approve
-them, and cannot loosen policy — each of those takes a human at a real terminal.
+guarantees a person approved it at all — through one of two doors, both the
+developer's. In chat: the agent asks with `AskUserQuestion`, the question text
+being pythia's own approval card (`pythia approve --card <token>`), and the
+answer **Approve** — written into the hook payload by Claude Code, never by
+the agent — mints the one-time grant. At a console: `pythia approve <token>`.
+Without that grant `apply --confirm` refuses. A headless agent cannot `--yes`
+its own writes, cannot mint approval, and cannot loosen policy — each of those
+takes a human, answering or typing.
 
 The same discipline holds when the *developer* does the work: `src` and
 `impact` silently snapshot what they read, so even a change made by hand in

{pythia_plsql-0.9.0 → pythia_plsql-0.10.0}/README.md

@@ -87,11 +87,14 @@ through one door: **snapshot → impact → preview → token → approve → ap
 verify → report**. DDL self-commits in Oracle, so the snapshot is the only real
 undo — it runs first and no flag disables it. A content-bound token guarantees
 what lands is byte-for-byte what was previewed, and a **developer-minted grant**
-guarantees a person approved it at all: `pythia approve` runs only at a human's
-own console, and without its one-time grant `apply --confirm` refuses. The
-agent's command line is unchanged; what changed is that it now stops until
-someone acts. A headless agent cannot `--yes` its own writes, cannot approve
-them, and cannot loosen policy — each of those takes a human at a real terminal.
+guarantees a person approved it at all — through one of two doors, both the
+developer's. In chat: the agent asks with `AskUserQuestion`, the question text
+being pythia's own approval card (`pythia approve --card <token>`), and the
+answer **Approve** — written into the hook payload by Claude Code, never by
+the agent — mints the one-time grant. At a console: `pythia approve <token>`.
+Without that grant `apply --confirm` refuses. A headless agent cannot `--yes`
+its own writes, cannot mint approval, and cannot loosen policy — each of those
+takes a human, answering or typing.
 
 The same discipline holds when the *developer* does the work: `src` and
 `impact` silently snapshot what they read, so even a change made by hand in

{pythia_plsql-0.9.0 → pythia_plsql-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.9.0"
+version = "0.10.0"
 description = "PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback."
 readme = "README.md"
 license = { text = "MIT" }

pythia_plsql-0.10.0/queries/current-schema.sql

@@ -0,0 +1,6 @@
+-- Purpose: the schema an unqualified CREATE lands in for this session. A proxy
+--          or a mis-set connections.json can put it somewhere other than the
+--          schema pythia snapshots and verifies; apply refuses that mismatch.
+-- Binds:   none
+-- Returns: CURRENT_SCHEMA
+select sys_context('userenv', 'current_schema') current_schema from dual

{pythia_plsql-0.9.0 → pythia_plsql-0.10.0}/scripts/pythia.py

@@ -84,6 +84,7 @@ QUERY_BINDS = {
     "source.sql": {"s", "n"},
     "object-source.sql": {"s", "n", "t"},
     "session-privileges.sql": set(),
+    "current-schema.sql": set(),
     "name-occupants.sql": {"s", "n"},
     "object-names.sql": {"s"},
 }
@@ -382,8 +383,11 @@ HEADLESS_YES_MSG = (
 
 APPROVE_HEADLESS_MSG = (
     "approve is the developer's command — it needs a real console.\n"
-    "Agents relay the preview and wait; a person runs approve in their own "
-    "terminal.\n(Real pipelines apply with --yes and PYTHIA_CI=1 instead.)")
+    "Agents ask instead: AskUserQuestion with the text of `approve --card "
+    "<token>` and the options Approve / Reject — the pythia hook mints the "
+    "grant when the developer answers Approve. Or a person runs approve in "
+    "their own terminal.\n(Real pipelines apply with --yes and PYTHIA_CI=1 "
+    "instead.)")
 
 
 def grant_refusal(status, token, grant, conn_name, file_hint):
@@ -393,7 +397,10 @@ def grant_refusal(status, token, grant, conn_name, file_hint):
     preview_line = f"  {invocation()} apply {file_hint}"
     if status == "missing":
         return ("The confirmation token matches, but no developer approval is "
-                "on file.\nAsk the developer to run, in their own terminal "
+                "on file.\nAsk in chat — AskUserQuestion carrying the text of\n"
+                f"  {invocation()} approve --card {token}\nwith the options "
+                "Approve / Reject (the pythia hook mints the grant on Approve) "
+                "— or ask the developer to run, in their own terminal "
                 f"(agents cannot run it):\n{approve_line}\n"
                 "Then re-run this command.")
     if status == "expired":
@@ -1129,11 +1136,14 @@ def grant_path(root, token):
     return grants_root(root) / f"{token}.json"
 
 
-def mint_grant(root, token, conn_name, now=None, revalidate=None):
+def mint_grant(root, token, conn_name, now=None, revalidate=None,
+               approver="console", session=None):
     """Record one developer approval. Single use, short-lived, bound to the
     connection the preview ran on. `revalidate` is the row-set fingerprint the
     human was shown — audit data, not a second gate: the enforcement is the
-    token, which already hashes that same fingerprint."""
+    token, which already hashes that same fingerprint. `approver` says which
+    door the human came through — console or chat — and `session` is the
+    chat session's id; both are audit data too."""
     import datetime
     now = now or datetime.datetime.now()
     rec = {"token": token,
@@ -1142,7 +1152,9 @@ def mint_grant(root, token, conn_name, now=None, revalidate=None):
            "expires_at": (now + datetime.timedelta(
                minutes=GRANT_TTL_MINUTES)).isoformat(timespec="seconds"),
            "used_at": None,
-           "revalidate": revalidate or None}
+           "revalidate": revalidate or None,
+           "approver": approver,
+           "session": session or None}
     d = grants_root(root)
     d.mkdir(parents=True, exist_ok=True)
     grant_path(root, token).write_text(json.dumps(rec, indent=2) + "\n",
@@ -1437,6 +1449,14 @@ def cmd_check(conn, schema, ns):
                (select count(*) from all_triggers  where owner = :s) triggers
         from dual""", {"s": schema})
     emit_table(ns, cols, rows, False)
+    current = session_schema(conn)
+    if current and current != str(schema).upper():
+        print("\n" + paint(
+            f"! Session schema is {current}, but this connection is configured "
+            f"for {schema}: unqualified writes would land in {current} while "
+            f"pythia reads {schema}. apply refuses until connections.json says "
+            f"\"schema\": \"{current}\".", "yellow", color_enabled(sys.stderr)),
+            file=sys.stderr)
     warn = privilege_warning(conn, schema, ns.conn_user)
     if warn:
         print("\n" + paint(warn, "yellow", color_enabled(sys.stderr)),
@@ -1942,6 +1962,31 @@ def privilege_warning(conn, schema, conn_user):
             "explains what is at stake.")
 
 
+def session_schema(conn):
+    """Where an unqualified name lands for this session, or None if the
+    database did not say (it always does on Oracle; test doubles may not)."""
+    _, rows = run_query(conn, load_query("current-schema.sql"), {})
+    return str(rows[0][0]).upper() if rows and rows[0] and rows[0][0] else None
+
+
+def refuse_schema_mismatch(conn, schema, ns):
+    """An unqualified CREATE lands in the session's current schema, while
+    every snapshot, impact and verify query here asks the configured one. If
+    those differ — a proxy into another user, a stale `schema` in
+    connections.json — the write would land in one place and be verified in
+    another, and "Applied, compiled clean" would be about the wrong object.
+    Found live: PYTHIA_AGENT[PYTHIA_DEV] with schema still set to PYTHIA."""
+    current = session_schema(conn)
+    if current and current != str(schema).upper():
+        sys.exit(f"Refused: this session's schema is {current!r}, but connection "
+                 f"{getattr(ns, 'conn_name', None) or '?'!r} is configured for "
+                 f"{schema!r}.\nAn unqualified statement would land in {current!r} "
+                 f"while pythia snapshots and verifies {schema!r}.\nSet "
+                 f"\"schema\": \"{current}\" for this connection in "
+                 f".pythia/connections.json (or connect as {schema!r}), then "
+                 "preview again.")
+
+
 def run_apply(conn, schema, ns, file_text, origin=None):
     """The six steps: SNAPSHOT, IMPACT, PREVIEW, APPLY, VERIFY, REPORT.
     Returns the exit code. Refusals raise SystemExit (exit 1)."""
@@ -2002,6 +2047,8 @@ def run_apply(conn, schema, ns, file_text, origin=None):
         # journal records the statement itself so at least *what ran* is kept.
         otype, name = group.upper(), "STATEMENT"
 
+    refuse_schema_mismatch(conn, schema, ns)   # the write must land where it is verified
+
     # 1. SNAPSHOT — before anything else, unconditionally.
     db_source = ""
     row_set = None
@@ -2111,10 +2158,12 @@ def run_apply(conn, schema, ns, file_text, origin=None):
                         f"{journal_root(ns.project_root) / entry / 'restore.sql'}",
                         "dim", en))
         if not confirmed:
-            print("\n  To apply — two steps, two people:")
-            print("    developer, in your own terminal:   "
+            print("\n  To apply — the developer approves, then the agent confirms:")
+            print("    in chat:            the agent asks (AskUserQuestion) with the text of "
+                  + paint(f"{invocation()} approve --card {token}", "cyan", en))
+            print("    or in a terminal:   "
                   + paint(f"{invocation()} approve {token}", "cyan", en))
-            print("    then the agent:                    "
+            print("    then the agent:     "
                   + paint(f"{invocation()} apply {ns.file} --confirm {token}",
                           "cyan", en))
     if not confirmed:
@@ -2229,7 +2278,10 @@ def cmd_apply(conn, schema, ns):
     path = pathlib.Path(ns.file)
     if not path.is_file():
         sys.exit(f"No such file: {path}")
-    code = run_apply(conn, schema, ns, path.read_text(encoding="utf-8"))
+    # utf-8-sig: Windows editors prepend a BOM, which read as a stray byte
+    # turned every such file into "cannot classify". A BOM-less file reads
+    # identically.
+    code = run_apply(conn, schema, ns, path.read_text(encoding="utf-8-sig"))
     if code:
         sys.exit(code)
 
@@ -2274,14 +2326,13 @@ def token_mismatch_message(ns, row_set):
             f"  {invocation()} apply {ns.file}")
 
 
-def cmd_approve(conn, schema, ns):
-    """The developer's half of the gate: one human act, at a real console,
-    that lets the agent's next `apply --confirm` through. Touches no
-    database — a terminal with no connection configured can still approve."""
-    token = str(ns.token).strip().lower()
-    if not console_session(ns):
-        sys.exit(APPROVE_HEADLESS_MSG)
-    entry, meta = find_preview_by_token(ns.project_root, token)
+def approval_card(root, token):
+    """What a human approves, in pythia's own words, read from the preview's
+    journal entry and never recomputed. Returns (entry, meta, lines). The same
+    text is printed at the console, asked with in chat, and checked by the
+    hook — so what is approved is what was shown, whichever door it came
+    through. Refuses a token no pending preview carries."""
+    entry, meta = find_preview_by_token(root, token)
     if not meta:
         sys.exit(f"No pending preview carries token {token!r}.\n"
                  "Approve what you have seen: run the preview first, then "
@@ -2291,49 +2342,154 @@ def cmd_approve(conn, schema, ns):
         sys.exit(f"Token {token!r} belongs to a preview that was already "
                  "applied.\nPreview again to get a fresh token:\n"
                  f"  {invocation()} apply <file>")
-    conn_name = meta.get("connection") or ""
-    prune_expired_grants(ns.project_root)
-    row_set = meta.get("row_set")
-    rec = mint_grant(ns.project_root, token, conn_name,
-                     revalidate=fingerprint_text(row_set))
-    obj, otype = meta.get("object", "?"), meta.get("type", "?")
     group = meta.get("group", "")
-    if ns.json:
-        print(json.dumps({"ok": True, "token": token, "conn": conn_name,
-                          "object": obj, "type": otype, "group": group,
-                          "rows": (row_set or {}).get("count"),
-                          "entry": entry, "minted_at": rec["minted_at"],
-                          "expires_at": rec["expires_at"],
-                          "ttl_minutes": GRANT_TTL_MINUTES}))
-        return
-    en = getattr(ns, "color", False)
-    print()
+    row_set = meta.get("row_set")
+    lines = []
     if group and group != "plsql_source":
         # no object identity, no snapshot: show the statement itself and say
         # plainly that there is no undo waiting behind it
-        stmt = read_journal_entry(ns.project_root, entry)["after"].strip()
-        print(f"  Approving a {group} statement on {meta.get('schema', '?')}:")
-        for ln in stmt.splitlines():
-            print(f"    {ln}")
+        stmt = read_journal_entry(root, entry)["after"].strip()
+        lines.append(f"Approving a {group} statement on {meta.get('schema', '?')}:")
+        lines += [f"  {ln}" for ln in stmt.splitlines()]
         if row_set:
             # the rows themselves, exactly as the preview showed them: what is
             # approved has to be what was seen
-            print()
-            for ln in render_row_set(row_set, en, indent="    "):
-                print(ln)
-        print(paint("\n  There is no snapshot for this group — after commit "
-                    "it cannot be undone from the journal.", "yellow", en))
+            lines.append("")
+            lines += render_row_set(row_set, False, indent="  ")
+        lines.append("There is no snapshot for this group — after commit it "
+                     "cannot be undone from the journal.")
     else:
-        print(f"  Approving: {paint(f'{obj} ({otype})', 'bold', en)} in "
-              f"{meta.get('schema', '?')}")
+        lines.append(f"Approving: {meta.get('object', '?')} "
+                     f"({meta.get('type', '?')}) in {meta.get('schema', '?')}")
         if meta.get("summary"):
-            print(f"  Impact: {meta['summary'].lstrip('- ')}")
-    print(f"  Previewed {entry[:19].replace('T', ' ')} on connection "
-          f"{conn_name or '?'}.")
-    print(paint(f"\n  Grant minted — single use, expires in "
-                f"{GRANT_TTL_MINUTES} minutes.", "green", en))
-    print("  The agent may now run:  "
-          + paint(f"{invocation()} apply <file> --confirm {token}", "cyan", en))
+            lines.append(f"Impact: {meta['summary'].lstrip('- ')}")
+    lines.append(f"Previewed {entry[:19].replace('T', ' ')} on connection "
+                 f"{meta.get('connection') or '?'}.")
+    return entry, meta, lines
+
+
+def squash(text):
+    """Whitespace-insensitive form, for 'did the question carry the card'."""
+    return " ".join(str(text).split()).lower()
+
+
+TOKEN_IN_QUESTION = re.compile(r"approve\s+(?:--card\s+)?([0-9a-f]{6,})\b", re.I)
+
+
+def hook_approve(ns):
+    """The chat door. Claude Code runs this as a PostToolUse hook on
+    AskUserQuestion, with the payload on stdin; the developer's answer in it
+    was filled in by the client, not the agent. A grant is minted only when
+    the answer is exactly Approve AND the question carried pythia's own card
+    for that token — otherwise the human approved the agent's words, not the
+    preview, and that is no approval. Everything else is silence: a hook that
+    talks on every question is noise."""
+    try:
+        payload = json.load(sys.stdin)
+    except ValueError:
+        return
+    if not isinstance(payload, dict) or payload.get("tool_name") != "AskUserQuestion":
+        return
+    resp = payload.get("tool_response")
+    answers = (resp.get("answers") if isinstance(resp, dict) else None) \
+        or (payload.get("tool_input") or {}).get("answers") or {}
+    notes = []
+    for question, answer in answers.items():
+        m = TOKEN_IN_QUESTION.search(str(question))
+        if not m:
+            continue
+        token = m.group(1).lower()
+        if squash(answer) != "approve":
+            notes.append(f"{token}: the developer did NOT approve (answered "
+                         f"{str(answer)!r}). No grant minted — do not apply; "
+                         "ask what should change.")
+            continue
+        try:
+            _, meta, body = approval_card(ns.project_root, token)
+        except SystemExit as e:
+            notes.append(f"{token}: {e}")
+            continue
+        if squash("\n".join(body)) not in squash(question):
+            notes.append(f"{token}: the question did not carry pythia's approval "
+                         "card verbatim, so the developer approved your words, "
+                         "not the preview. No grant minted. Run "
+                         f"`{invocation()} approve --card {token}` and ask "
+                         "again with exactly that text.")
+            continue
+        prune_expired_grants(ns.project_root)
+        mint_grant(ns.project_root, token, meta.get("connection") or "",
+                   revalidate=fingerprint_text(meta.get("row_set")),
+                   approver="chat", session=payload.get("session_id"))
+        notes.append(f"{token}: approved in chat — grant minted, single use, "
+                     f"expires in {GRANT_TTL_MINUTES} minutes. Run: "
+                     f"{invocation()} apply <file> --confirm {token}")
+    if notes:
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": "pythia: " + "\n".join(notes)}}))
+
+
+def cmd_approve(conn, schema, ns):
+    """The developer's half of the gate: one human act that lets the agent's
+    next `apply --confirm` through — at a real console, or in chat via the
+    hook (--hook). --card prints what the agent asks with and mints nothing.
+    Touches no database — a terminal with no connection configured can still
+    approve."""
+    if getattr(ns, "hook", False):
+        return hook_approve(ns)
+    tokens = [ns.token] if isinstance(ns.token, str) else list(ns.token or [])
+    tokens = [str(t).strip().lower() for t in tokens]
+    card_only = getattr(ns, "card", False)
+    if not tokens:
+        sys.exit(f"Usage: {invocation()} approve <token> [<token> ...]\n"
+                 f"       {invocation()} approve --card <token>")
+    if not card_only and not console_session(ns):
+        sys.exit(APPROVE_HEADLESS_MSG)
+    en = getattr(ns, "color", False)
+    out = []
+    for token in tokens:
+        entry, meta, body = approval_card(ns.project_root, token)
+        conn_name = meta.get("connection") or ""
+        row_set = meta.get("row_set")
+        rec = None
+        if not card_only:
+            prune_expired_grants(ns.project_root)
+            rec = mint_grant(ns.project_root, token, conn_name,
+                             revalidate=fingerprint_text(row_set))
+        if ns.json:
+            card = f"{invocation()} approve {token}\n" + "\n".join(body)
+            out.append({"ok": True, "token": token, "conn": conn_name,
+                        "object": meta.get("object", "?"),
+                        "type": meta.get("type", "?"),
+                        "group": meta.get("group", ""),
+                        "rows": (row_set or {}).get("count"),
+                        "entry": entry, "card": card,
+                        "question": {"question": card, "header": "pythia",
+                                     "multiSelect": False,
+                                     "options": [
+                                         {"label": "Approve",
+                                          "description": "mint the one-time grant; the agent then runs apply --confirm"},
+                                         {"label": "Reject",
+                                          "description": "nothing is written; say what should change"}]},
+                        "minted": rec is not None,
+                        "minted_at": (rec or {}).get("minted_at"),
+                        "expires_at": (rec or {}).get("expires_at"),
+                        "ttl_minutes": GRANT_TTL_MINUTES})
+            continue
+        print()
+        if card_only:
+            # plain text on purpose: this goes into a question, not a terminal
+            print(f"{invocation()} approve {token}")
+            print("\n".join(body))
+            continue
+        for ln in body:
+            print(f"  {paint(ln, 'yellow', en) if ln.startswith('There is no snapshot') else ln}")
+        print(paint(f"\n  Grant minted — single use, expires in "
+                    f"{GRANT_TTL_MINUTES} minutes.", "green", en))
+        print("  The agent may now run:  "
+              + paint(f"{invocation()} apply <file> --confirm {token}", "cyan", en))
+    if ns.json:
+        print(json.dumps(out[0] if len(out) == 1 else out))
 
 
 def run_restore(conn, schema, ns):
@@ -2513,7 +2669,9 @@ ASK    relay apply previews verbatim and wait for a real yes. >=10 dependents
        exit 3 (written-but-broken) are relayed, never routed around. Do not
        read exit codes through a pipe.
 DO     writes go through `pythia apply` only - snapshot, token, verify. The
-       developer runs `pythia approve <token>`; you never can. Full
+       developer approves: you ask in chat (AskUserQuestion, text from
+       `pythia approve --card <token>`, options Approve/Reject) or they run
+       `pythia approve <token>` themselves; you never mint it. Full
        contract: `pythia guide`.
 """
 
@@ -2565,10 +2723,13 @@ Stop at exactly these moments; a guess past any of them is a defect.
 One door for writes: snapshot -> impact -> preview -> token -> approve ->
 apply -> verify -> report.
 
-  approve                 THE DEVELOPER'S COMMAND, at their own terminal:
-                          mints the one-time grant that --confirm requires.
-                          An agent cannot run it - that is the point. Relay
-                          the line the preview printed and wait.
+  approve                 THE DEVELOPER'S ACT: mints the one-time grant that
+                          --confirm requires. Two doors, both theirs: answer
+                          Approve to your AskUserQuestion (question text =
+                          `approve --card <token>`, verbatim - the hook mints
+                          only then), or `approve <token>` at their own
+                          terminal. An agent never mints it - that is the
+                          point.
   apply                   the six-step write; --confirm binds to the preview
                           AND to the developer's approval
   journal restore         undo, through the same six steps and the same gate
@@ -3142,7 +3303,14 @@ def build_parser():
     s = sub.add_parser("approve", parents=[common()],
                        help="the developer approves a preview: mints the "
                             "one-time grant apply --confirm requires")
-    s.add_argument("token", help="the token printed by the preview")
+    s.add_argument("token", nargs="*", help="token(s) printed by the preview")
+    s.add_argument("--card", action="store_true",
+                   help="print the approval card the agent asks with in chat "
+                        "(AskUserQuestion); mints nothing, needs no console")
+    s.add_argument("--hook", action="store_true",
+                   help="Claude Code PostToolUse hook on AskUserQuestion: "
+                        "reads the payload on stdin and mints the grant the "
+                        "developer answered Approve to")
     sub.add_parser("connections", parents=[common()],
                    help="list configured connections — names, users, "
                         "targets; never passwords")

{pythia_plsql-0.9.0 → pythia_plsql-0.10.0/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.9.0
+Version: 0.10.0
 Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -101,11 +101,14 @@ through one door: **snapshot → impact → preview → token → approve → ap
 verify → report**. DDL self-commits in Oracle, so the snapshot is the only real
 undo — it runs first and no flag disables it. A content-bound token guarantees
 what lands is byte-for-byte what was previewed, and a **developer-minted grant**
-guarantees a person approved it at all: `pythia approve` runs only at a human's
-own console, and without its one-time grant `apply --confirm` refuses. The
-agent's command line is unchanged; what changed is that it now stops until
-someone acts. A headless agent cannot `--yes` its own writes, cannot approve
-them, and cannot loosen policy — each of those takes a human at a real terminal.
+guarantees a person approved it at all — through one of two doors, both the
+developer's. In chat: the agent asks with `AskUserQuestion`, the question text
+being pythia's own approval card (`pythia approve --card <token>`), and the
+answer **Approve** — written into the hook payload by Claude Code, never by
+the agent — mints the one-time grant. At a console: `pythia approve <token>`.
+Without that grant `apply --confirm` refuses. A headless agent cannot `--yes`
+its own writes, cannot mint approval, and cannot loosen policy — each of those
+takes a human, answering or typing.
 
 The same discipline holds when the *developer* does the work: `src` and
 `impact` silently snapshot what they read, so even a change made by hand in

{pythia_plsql-0.9.0 → pythia_plsql-0.10.0}/scripts/pythia_plsql.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 queries/compile-errors.sql
+queries/current-schema.sql
 queries/dependencies.sql
 queries/impact.sql
 queries/invalid-objects.sql

{pythia_plsql-0.9.0 → pythia_plsql-0.10.0}/skills/pythia-apply/SKILL.md

@@ -26,15 +26,13 @@ Three moves are FORBIDDEN for agents, and the CLI enforces all three (no
 terminal attached → refusal):
 
 - `--yes` — it is the developer's flag, never yours.
-- `pythia approve <token>` — the developer's command, run at their own
-  terminal. It mints the one-time grant `--confirm` requires, and an agent
-  cannot run it. Relay the line; never run it yourself.
+- Minting the approval. `pythia approve <token>` is the developer's console
+  command; an agent cannot run it. Your door is to ASK (step 3): the pythia
+  hook mints the grant only from the developer's own answer to your question.
 - `pythia policy set <group>` to anything LOOSER — loosening policy is the
   developer's decision; hand them the exact command to run themselves.
 
-One move is yours but never in the same turn as the preview: `--confirm`. The
-preview ends your turn; the token is used only after approval arrives as a NEW
-message.
+One move is yours: `--confirm` — only after `Approve`, or a console approve.
 
 ## When the change will NOT go through apply
 
@@ -55,16 +53,17 @@ confirms a number you already knew.
 2. **Relay the preview — verbatim.** The diff, the `impact:` line, every `!`
    warning, exactly as printed. The developer approves what they see, not
    your paraphrase.
-3. **Wait for an explicit yes, and for the approval to be minted.** The
-   preview prints two follow-up lines — `pythia approve <token>` for the
-   developer, `apply --confirm` for you. Relay both. A yes is an instruction
-   to proceed with THIS preview: "yes, apply it", "go ahead". Not a yes: a
-   compliment, a question, silence, or approval given for an earlier preview.
-   If the developer changes the file instead, start over at step 1.
+3. **Ask for approval — one question per token.** `pythia approve --card
+   <token>` prints the card; ask an `AskUserQuestion` whose text is that card
+   verbatim (header `pythia`; options exactly `Approve` / `Reject`, no
+   "(Recommended)"; up to four tokens per call). `Approve` mints the grant via
+   the hook. Anything else — `Reject`, free text, silence, an earlier preview's
+   yes — is not approval: stop and ask what should change. File changed → step 1.
+   No hook installed? Relay `pythia approve <token>` for their own terminal.
 4. **Apply** by running the exact `then the agent:` line pythia printed. Two
    refusals are normal here, and neither is a malfunction:
-   - *"no developer approval is on file"* — they have not run `approve` yet.
-     Say so and wait; retrying does not create approval.
+   - *"no developer approval is on file"* — the answer was not `Approve`, or
+     the hook is not installed. Say so and wait; retrying does not create it.
    - *"the confirmation token does not match"* — the file or the database
      changed since the preview. Go back to step 1, never "retry". If the fresh
      preview's before-side differs from what you last saw, say so: someone may
@@ -85,8 +84,8 @@ confirms a number you already knew.
 ## Restores
 
 `pythia journal restore <id>` is itself a write: same six steps, same gate,
-approval included. Preview the reverse diff, relay both follow-up lines, wait
-for their approve, then confirm. Restoring an object that did not exist before
+approval included. Preview the reverse diff, ask with the card the same way,
+then confirm. Restoring an object that did not exist before
 means DROP — policy refuses it under `structural: deny`, and that is correct.
 
 ## Batch mode
@@ -135,7 +134,8 @@ affected count and up to ten rows, and `--confirm` refuses if that set moved.
 | "apply refused it; run-sql will take it" | The refusal is the product working. Relay it. |
 | "I'll restore quietly to clean up my mistake" | Restores are writes. Same gate, same visibility. |
 | "`$?` said 0 after I piped to tail" | That was tail's 0. Read pythia's own words, or its unpiped code. |
-| "I'll run approve myself to unblock this" | The developer's console act. It refuses you, and routing around it is what this gate exists to stop. |
+| "I'll run approve myself to unblock this" | The developer's act. Console approve refuses you; the hook mints only from *their* answer. Routing around it is what this gate exists to stop. |
+| "I'll summarise the card so the question reads nicer" | The hook refuses a paraphrase — the developer must approve pythia's words, not yours. Paste the card verbatim. |
 
 ## When NOT to use this skill
 

{pythia_plsql-0.9.0 → pythia_plsql-0.10.0}/tests/test_phase3.py

@@ -240,6 +240,7 @@ def base_script(errors=(), invalid_after=None, db_source=OLD_SRC):
         "from all_errors": ([("NAME", "TYPE", "SEQUENCE", "LINE", "POSITION",
                               "ATTRIBUTE", "TEXT")], list(errors)),
         "from session_privs": ([("PRIVILEGE",)], []),
+        "current_schema": ([("CURRENT_SCHEMA",)], [("APP",)]),
         # main-namespace occupants of the target name (type-conflict check)
         "object_name = upper(:n)": ([("OBJECT_TYPE",)], [("PACKAGE BODY",)]),
     }
@@ -1128,9 +1129,10 @@ def test_preview_prints_both_follow_up_lines():
             pythia.run_apply(conn, "APP", apply_ns(td, file="f.sql"), NEW_FILE)
         out = buf.getvalue()
         tok = pythia.apply_token("PACKAGE BODY", "PKG_ORDER", NEW_FILE, OLD_SRC)
-        assert f"approve {tok}" in out
+        assert f"approve --card {tok}" in out      # the chat door
+        assert f"approve {tok}" in out             # the console door
         assert f"apply f.sql --confirm {tok}" in out
-        assert "your own terminal" in out
+        assert "in chat" in out and "terminal" in out
 
 
 def test_journal_restore_needs_a_grant_too():
@@ -1338,6 +1340,156 @@ def test_approve_needs_no_database():
     assert "approve" in pythia.COMMANDS
 
 
+# --- the chat door: approve --card / approve --hook ---------------------------
+
+def _hook_payload(question, answer, tool="AskUserQuestion", session="sess-1"):
+    q = {"question": question, "header": "pythia", "multiSelect": False,
+         "options": [{"label": "Approve", "description": "mint"},
+                     {"label": "Reject", "description": "stop"}]}
+    return {"hook_event_name": "PostToolUse", "session_id": session,
+            "tool_name": tool, "tool_input": {"questions": [q]},
+            "tool_response": {"questions": [q], "answers": {question: answer}}}
+
+
+def _run_hook(td, payload):
+    """A headless agent session with the hook payload on stdin — exactly how
+    Claude Code invokes it. Returns stdout."""
+    import contextlib
+    import io
+    buf = io.StringIO()
+    with _NoTTY():
+        sys.stdin = io.StringIO(json.dumps(payload) if not isinstance(payload, str)
+                                else payload)
+        with contextlib.redirect_stdout(buf):
+            pythia.cmd_approve(None, None, approve_ns(td, [], hook=True))
+    return buf.getvalue()
+
+
+def _pending_preview(td, token="7f3a91"):
+    pythia.write_journal_entry(
+        td, "PACKAGE BODY", "PKG_ORDER", OLD_SRC, NEW_FILE,
+        {"token": token, "connection": "DEV", "schema": "APP",
+         "group": "plsql_source", "applied": False,
+         "summary": "12 dependent objects, 11 currently VALID"})
+    _, _, body = pythia.approval_card(td, token)
+    return f"pythia approve {token}\n" + "\n".join(body)
+
+
+def test_hook_mints_the_grant_the_developer_approved_in_chat():
+    """The developer answered Approve to a question carrying pythia's own
+    card: that is the console act, through the other door. The grant says
+    which door, and which session."""
+    with tempfile.TemporaryDirectory() as td:
+        card = _pending_preview(td)
+        out = _run_hook(td, _hook_payload("  Please approve:\n" + card, "Approve"))
+        g = pythia.read_grant(td, "7f3a91")
+        assert g and g["approver"] == "chat" and g["session"] == "sess-1"
+        assert g["conn"] == "DEV" and g["used_at"] is None
+        ctx = json.loads(out)["hookSpecificOutput"]
+        assert ctx["hookEventName"] == "PostToolUse"
+        assert "--confirm 7f3a91" in ctx["additionalContext"]
+
+
+def test_hook_refuses_a_question_that_is_not_pythias_card():
+    """An agent's paraphrase is not a preview. If the question did not carry
+    the card verbatim, the human approved the agent's words — no grant, and
+    the agent is told to ask again with the card."""
+    with tempfile.TemporaryDirectory() as td:
+        _pending_preview(td)
+        out = _run_hook(td, _hook_payload(
+            "pythia approve 7f3a91\nJust a tiny, totally safe change.", "Approve"))
+        assert pythia.read_grant(td, "7f3a91") is None
+        assert "approve --card 7f3a91" in json.loads(out)["hookSpecificOutput"]["additionalContext"]
+
+
+def test_hook_mints_nothing_on_reject_other_tools_or_garbage():
+    with tempfile.TemporaryDirectory() as td:
+        card = _pending_preview(td)
+        out = _run_hook(td, _hook_payload(card, "Reject"))
+        assert pythia.read_grant(td, "7f3a91") is None
+        assert "did not approve" in out.lower()
+        assert _run_hook(td, _hook_payload(card, "Approve", tool="Bash")) == ""
+        assert _run_hook(td, "not json at all") == ""
+        assert _run_hook(td, _hook_payload("no token here", "Approve")) == ""
+        assert not pythia.grants_root(td).exists()
+        # a token no preview carries cannot be approved blind, in chat either
+        out = _run_hook(td, _hook_payload("pythia approve abc123", "Approve"))
+        assert "no pending preview" in out.lower()
+        assert pythia.read_grant(td, "abc123") is None
+
+
+def test_approve_card_needs_no_console_and_mints_nothing():
+    """--card is the agent's half: it prints what to ask with. Headless is
+    fine, and nothing is minted by printing."""
+    import contextlib
+    import io
+    with tempfile.TemporaryDirectory() as td, _NoTTY():
+        _pending_preview(td)
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            pythia.cmd_approve(None, None, approve_ns(td, ["7f3a91"], card=True))
+        out = buf.getvalue()
+        assert "approve 7f3a91" in out and "PKG_ORDER" in out
+        assert "12 dependent objects" in out and "DEV" in out
+        assert "\x1b[" not in out                       # plain text: it goes into a question
+        assert not pythia.grants_root(td).exists()
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            pythia.cmd_approve(None, None, approve_ns(td, ["7f3a91"], card=True,
+                                                      json=True))
+        d = json.loads(buf.getvalue())
+        assert d["minted"] is False and d["question"]["header"] == "pythia"
+        assert [o["label"] for o in d["question"]["options"]] == ["Approve", "Reject"]
+        assert d["card"] in d["question"]["question"]
+
+
+def test_approve_several_tokens_in_one_console_act():
+    """Four previews, one approve line — not four."""
+    import contextlib
+    import io
+    with tempfile.TemporaryDirectory() as td:
+        _pending_preview(td, "aa1111")
+        _pending_preview(td, "bb2222")
+        with contextlib.redirect_stdout(io.StringIO()):
+            pythia.cmd_approve(None, None,
+                               approve_ns(td, ["aa1111", "bb2222"], console=True))
+        assert pythia.read_grant(td, "aa1111")["approver"] == "console"
+        assert pythia.read_grant(td, "bb2222")["approver"] == "console"
+
+
+def test_apply_reads_a_bom_file_as_the_statement_it_is():
+    """Windows editors prepend a UTF-8 BOM. Read as a stray byte it turned a
+    plain CREATE OR REPLACE into 'cannot classify' — a refusal with the wrong
+    reason, found live in 0.10.0's dogfood run."""
+    import contextlib
+    import io
+    import pathlib
+    with tempfile.TemporaryDirectory() as td:
+        f = pathlib.Path(td) / "f.sql"
+        import codecs
+        f.write_bytes(codecs.BOM_UTF8 + NEW_FILE.encode("utf-8"))
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            pythia.cmd_apply(FakeConn(base_script()), "APP",
+                             apply_ns(td, file=str(f)))
+        assert "approve --card" in buf.getvalue()      # it previewed
+
+
+def test_apply_refuses_when_the_session_schema_is_not_the_configured_one():
+    """A proxy into another user, or a stale `schema` in connections.json:
+    an unqualified CREATE would land in one schema while pythia snapshots
+    and verifies another. Refuse before the snapshot, with the fix."""
+    with tempfile.TemporaryDirectory() as td:
+        script = base_script()
+        script["current_schema"] = ([("CURRENT_SCHEMA",)], [("PYTHIA_DEV",)])
+        conn = FakeConn(script)
+        expect_exit(lambda: pythia.run_apply(conn, "APP", apply_ns(td, file="f.sql"),
+                                             NEW_FILE),
+                    "PYTHIA_DEV", "configured for 'APP'", "connections.json")
+        assert wrote_ddl(conn) == []
+        assert not pythia.journal_root(td).exists()     # refused before step 1
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):