pythia-plsql 0.12.0__tar.gz → 0.14.0__tar.gz

{pythia_plsql-0.12.0/scripts/pythia_plsql.egg-info → pythia_plsql-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.12.0
+Version: 0.14.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
@@ -128,7 +128,7 @@ Or the same thing piecewise:
 
 ```bash
 pip install pythia-plsql   # the CLI (thin driver — no Oracle Instant Client needed)
-python -m pythia install   # skills into your agent + .pythia/ scaffold + Claude Code hooks
+python -m pythia install   # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md
 pythia check               # fill in connections.json first, then verify
 ```
 
@@ -212,6 +212,10 @@ stops it prompting for the read-only commands and asks it to pause on
 writes — optional, and yours to install
 ([why pythia does not](GUIDE.md#11-optional-claude-code-permission-settings)).
 
+On Codex, the same command writes the harness into `AGENTS.md` (loaded every
+session) and a session-start hook into `.codex/hooks.json`; approve previews in
+the terminal with `pythia approve <token>`, since Codex has no chat-mint.
+
 Per-group write policy, `.pythia/policy.json` (defaults shown):
 
 | Group | Default | Is rollback real? |

{pythia_plsql-0.12.0 → pythia_plsql-0.14.0}/README.md

@@ -114,7 +114,7 @@ Or the same thing piecewise:
 
 ```bash
 pip install pythia-plsql   # the CLI (thin driver — no Oracle Instant Client needed)
-python -m pythia install   # skills into your agent + .pythia/ scaffold + Claude Code hooks
+python -m pythia install   # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md
 pythia check               # fill in connections.json first, then verify
 ```
 
@@ -198,6 +198,10 @@ stops it prompting for the read-only commands and asks it to pause on
 writes — optional, and yours to install
 ([why pythia does not](GUIDE.md#11-optional-claude-code-permission-settings)).
 
+On Codex, the same command writes the harness into `AGENTS.md` (loaded every
+session) and a session-start hook into `.codex/hooks.json`; approve previews in
+the terminal with `pythia approve <token>`, since Codex has no chat-mint.
+
 Per-group write policy, `.pythia/policy.json` (defaults shown):
 
 | Group | Default | Is rollback real? |

{pythia_plsql-0.12.0 → pythia_plsql-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.12.0"
+version = "0.14.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.12.0 → pythia_plsql-0.14.0}/scripts/pythia.py

@@ -2818,6 +2818,51 @@ DO     writes go through `pythia apply` only - snapshot, token, verify. The
 """
 
 
+AGENTS_BEGIN = "<!-- pythia:begin (managed by `pythia install`; edit outside this block) -->"
+AGENTS_END = "<!-- pythia:end -->"
+
+
+def agents_md_block():
+    """The pythia section for AGENTS.md — Codex's always-loaded instruction
+    file. Body is BRIEF_GUIDE verbatim (the same constant `guide --brief`
+    prints and the Claude SessionStart hook runs, so the two cannot drift),
+    plus the one line Codex needs that Claude gets from its hook: where the
+    approval door is, since Codex has no chat-mint. Marker-wrapped so a re-run
+    replaces it in place and the developer's own text is untouched."""
+    return (f"{AGENTS_BEGIN}\n"
+            "## pythia — developing PL/SQL on Oracle\n\n"
+            f"{BRIEF_GUIDE.rstrip()}\n\n"
+            "On Codex there is no chat approval hook: the developer approves a "
+            "preview in this terminal with `pythia approve <token>`, then the "
+            "agent runs `pythia apply <file> --confirm <token>`.\n"
+            f"{AGENTS_END}")
+
+
+def merge_agents_md(path):
+    """Write the pythia block into an AGENTS.md. The file is the developer's,
+    shared with every AGENTS.md-reading agent, so only the delimited block is
+    ours: present -> replaced in place, absent -> appended below their text,
+    everything else byte-identical. Returns (path, action) where action is
+    'created' | 'updated' | 'unchanged'."""
+    path = pathlib.Path(path)
+    block = agents_md_block()
+    old = path.read_text(encoding="utf-8") if path.is_file() else None
+    if old is None:
+        new, action = block + "\n", "created"
+    elif AGENTS_BEGIN in old and AGENTS_END in old:
+        pre = old[:old.index(AGENTS_BEGIN)]
+        post = old[old.index(AGENTS_END) + len(AGENTS_END):]
+        new = pre + block + post
+        action = "unchanged" if new == old else "updated"
+    else:
+        tail = "" if old.endswith("\n\n") else "\n" if old.endswith("\n") else "\n\n"
+        new, action = old + tail + block + "\n", "updated"
+    if new != old:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(new, encoding="utf-8")
+    return path, action
+
+
 OPERATING_GUIDE = """\
 THE OPERATING MODEL — Learn, Ask, Do (Hoc - Hoi - Lam)
 
@@ -2876,6 +2921,10 @@ apply -> verify -> report.
                           AND to the developer's approval
   journal restore         undo, through the same six steps and the same gate
   unistr                  exact non-ASCII literals for what you are writing
+  mcp                     Codex only: a write-free MCP approver. The agent
+                          calls its pythia_approve tool, Codex shows the card
+                          as a select prompt, and the developer's Approve mints
+                          the grant. It never writes; apply still verifies it.
   install · agent-user · guide    setting the harness itself up
 
 The CLI enforces the gates: headless --yes is refused, policy cannot be
@@ -3236,29 +3285,36 @@ def global_pack_present(home=None):
 
 
 def copy_bundled_skills(base_dir):
-    """No-Node fallback: copy the wheel-bundled pack into
-    <base>/.claude/skills/ ONLY — the directory Claude Code reliably reads
-    in both scopes (field evidence: a project's .agents/skills is invisible
-    to some Claude Code versions, and a second copy doubles every menu
-    entry). base_dir is the project root, or the home directory for -g.
+    """No-Node fallback: copy the wheel-bundled pack into BOTH conventional
+    roots — <base>/.claude/skills/ (Claude Code) and <base>/.agents/skills/
+    (Codex, and ~/.agents/skills on -g). base_dir is the project root, or the
+    home directory for -g. Node users get the same reach from `npx skills
+    add`; this is the machine that has only Python.
+
+    Trade-off, stated plainly: this reverses an earlier one-root-only choice.
+    A Claude Code version that reads both roots may list a pack entry twice —
+    accepted, because a Codex user without Node otherwise gets no skills at
+    all, and Codex reads only .agents/skills.
 
     Both destinations are cleared link-first before the copy. An earlier
     `npx skills add` leaves .claude/skills/<name> as a symlink into
-    .agents/skills/<name>; copying into that symlink would write through to
-    its target, which the .agents cleanup then deletes — leaving a dangling
-    link and no pack at all. Only the pack's own names are touched; other
-    skills in those directories are left alone."""
+    .agents/skills/<name>; removing both links first means each copytree
+    writes a fresh real directory, never through a link into a target the
+    other copy would then overwrite. Only the pack's own names are touched;
+    other skills in those directories are left alone."""
     import shutil
     base = pathlib.Path(base_dir)
-    dest_root = base / ".claude" / "skills"
+    claude_root = base / ".claude" / "skills"      # Claude Code reads this
+    agents_root = base / ".agents" / "skills"      # Codex reads this
     for pack in sorted(SKILLS_DIR.iterdir()):
         if not (pack / "SKILL.md").is_file():
             continue
-        _remove_link_first(dest_root / pack.name)
-        _remove_link_first(base / ".agents" / "skills" / pack.name)
-        shutil.copytree(pack, dest_root / pack.name)
+        _remove_link_first(claude_root / pack.name)
+        _remove_link_first(agents_root / pack.name)
+        shutil.copytree(pack, claude_root / pack.name)
+        shutil.copytree(pack, agents_root / pack.name)
     clean_legacy_skills(base_dir)
-    return [dest_root]
+    return [claude_root, agents_root]
 
 
 def _remove_link_first(path):
@@ -3302,6 +3358,258 @@ CLAUDE_DENY = ["Bash(pythia approve --hook*)",
 # is recognised by what it runs, not by how it invokes it
 HOOK_MARKS = {"SessionStart": "guide --brief", "PostToolUse": "approve --hook"}
 
+# Codex loads hooks from <repo>/.codex/hooks.json once the layer is trusted
+# (/hooks). Only the session-start guide is wired — Codex has no answer-reading
+# PostToolUse and no question tool, so the chat approve-mint cannot port; the
+# developer approves in the terminal. Same shape and merge discipline as the
+# Claude hooks.
+CODEX_HOOKS = {
+    "SessionStart": [{"hooks": [
+        {"type": "command", "command": "python -m pythia guide --brief"}]}],
+}
+CODEX_HOOK_MARKS = {"SessionStart": "guide --brief"}
+
+
+def merge_codex_hooks(path, events=None):
+    """Merge pythia's Codex hooks into a hooks.json ({"hooks": {...}}). Every
+    other key survives, a hook already present in any spelling is recognised by
+    what it runs, and a file that will not parse is left byte-identical.
+    Returns (path, added|None)."""
+    path = pathlib.Path(path)
+    try:
+        s = json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
+        hooks = s.setdefault("hooks", {})
+        added = []
+        for event in events or CODEX_HOOKS:
+            present = hooks.setdefault(event, [])
+            cmds = " ".join(h.get("command", "")
+                            for e in present for h in e.get("hooks", []))
+            if CODEX_HOOK_MARKS[event] not in cmds:
+                present.extend(json.loads(json.dumps(CODEX_HOOKS[event])))
+                added.append(f"hooks.{event}")
+    except (ValueError, TypeError, AttributeError):
+        return path, None
+    if added:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(s, indent=2, ensure_ascii=False) + "\n",
+                        encoding="utf-8")
+    return path, added
+
+
+# The MCP approver: a write-free stdio server whose one tool, pythia_approve,
+# mints the same grant `approve` mints — gated by an MCP elicitation the
+# developer answers in Codex. Writes never go through here; apply still
+# verifies the grant. Hand-rolled JSON-RPC (stdlib only).
+MCP_TOOL = "pythia_approve"
+MCP_PROTOCOL = "2025-06-18"
+MCP_ELICIT_METHOD = "elicitation/create"   # the one spelling to adjust if a
+#                                            live Codex disagrees (isolated)
+_MCP_TOOL_DEF = {
+    "name": MCP_TOOL,
+    "description": ("Ask the developer to approve a pythia apply preview by its "
+                    "token. Shows pythia's approval card and mints the one-time "
+                    "grant only if the developer picks Approve. Call it after "
+                    "`pythia apply <file>` prints a token; then run "
+                    "`pythia apply <file> --confirm <token>`."),
+    "inputSchema": {"type": "object",
+                    "properties": {"token": {"type": "string"}},
+                    "required": ["token"]},
+}
+
+
+def _rpc_result(mid, result):
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def _rpc_error(mid, code, message):
+    return {"jsonrpc": "2.0", "id": mid, "error": {"code": code, "message": message}}
+
+
+def mcp_handle(msg, state):
+    """Dispatch one incoming JSON-RPC message that is NOT a tools/call (those
+    need the elicitation round-trip and are handled in the loop). Returns
+    (outgoing_messages, done). A notification (no id) is answered with []."""
+    method = msg.get("method")
+    mid = msg.get("id")
+    if method == "initialize":
+        proto = (msg.get("params") or {}).get("protocolVersion") or MCP_PROTOCOL
+        return [_rpc_result(mid, {
+            "protocolVersion": proto,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "pythia",
+                           "version": getattr(sys.modules[__name__],
+                                              "__version__", "0")}})], False
+    if method == "notifications/initialized":
+        return [], False
+    if method == "tools/list":
+        return [_rpc_result(mid, {"tools": [_MCP_TOOL_DEF]})], False
+    if mid is None:
+        return [], False                       # any other notification
+    return [_rpc_error(mid, -32601, f"method not found: {method}")], False
+
+
+def _mcp_text(text, is_error=False):
+    return {"content": [{"type": "text", "text": text}], "isError": is_error}
+
+
+def mcp_approve_decision(root, token, elicit):
+    """Mint on a developer's Approve, delivered through an MCP elicitation.
+
+    Transport-free: `elicit(message, schema) -> (action, content)` performs the
+    round-trip (a fake in tests). The card is pythia's own, built from the
+    journal — so there is nothing for the agent to paraphrase and no verbatim
+    check to run. Fail-closed everywhere: the only path that mints is an
+    explicit accept whose decision is exactly Approve."""
+    token = str(token or "").strip().lower()
+    try:
+        _, meta, body = approval_card(root, token)   # refuses unknown/applied
+    except SystemExit as e:
+        return _mcp_text(str(e), is_error=True)
+    message = f"{invocation()} approve {token}\n" + "\n".join(body)
+    schema = {"type": "object",
+              "properties": {"decision": {"type": "string",
+                                          "enum": ["Approve", "Reject"]}},
+              "required": ["decision"]}
+    try:
+        action, content = elicit(message, schema)
+    except Exception as e:                        # noqa: BLE001 — fail closed
+        return _mcp_text(f"No grant minted: the approval prompt could not be "
+                         f"completed ({e}). Approve in a terminal instead: "
+                         f"{invocation()} approve {token}", is_error=True)
+    if action != "accept" or (content or {}).get("decision") != "Approve":
+        return _mcp_text(f"No grant minted for {token}: the developer did not "
+                         "approve (answered "
+                         f"{(content or {}).get('decision') or action!r}). "
+                         "Do not apply; ask what should change.", is_error=True)
+    prune_expired_grants(root)
+    mint_grant(root, token, meta.get("connection") or "",
+               revalidate=fingerprint_text(meta.get("row_set")), approver="mcp")
+    return _mcp_text(f"Approved — grant minted for {token}, single use, expires "
+                     f"in {GRANT_TTL_MINUTES} minutes. Now run: "
+                     f"{invocation()} apply <file> --confirm {token}")
+
+
+def mcp_serve(reader, writer, root):
+    """The stdio loop. Newline-delimited JSON-RPC in and out. A tools/call for
+    pythia_approve runs the elicitation round-trip inline: send
+    elicitation/create, then read until the matching-id response. One call in
+    flight at a time (Codex calls tools serially in a turn)."""
+    counter = [1000]
+
+    def send(msg):
+        writer.write(json.dumps(msg) + "\n")
+        writer.flush()
+
+    def read_msg():
+        line = reader.readline()
+        if not line:
+            return None
+        try:
+            return json.loads(line)
+        except ValueError:
+            return {}                       # skip a malformed line
+
+    def elicit(message, schema):
+        counter[0] += 1
+        eid = counter[0]
+        send({"jsonrpc": "2.0", "id": eid, "method": MCP_ELICIT_METHOD,
+              "params": {"message": message, "requestedSchema": schema}})
+        while True:
+            m = read_msg()
+            if m is None:
+                raise RuntimeError("client closed before answering the elicitation")
+            if m.get("id") == eid and ("result" in m or "error" in m):
+                if "error" in m:
+                    raise RuntimeError(str(m["error"]))
+                r = m["result"] or {}
+                return r.get("action"), r.get("content") or {}
+            # ignore anything else that arrives mid-elicitation
+
+    while True:
+        msg = read_msg()
+        if msg is None:
+            return
+        if msg.get("method") == "tools/call":
+            mid = msg.get("id")
+            params = msg.get("params") or {}
+            if params.get("name") != MCP_TOOL:
+                send(_rpc_error(mid, -32601, f"no such tool: {params.get('name')}"))
+                continue
+            token = (params.get("arguments") or {}).get("token", "")
+            result = mcp_approve_decision(root, token, elicit)
+            send(_rpc_result(mid, result))
+            continue
+        out, _ = mcp_handle(msg, {})
+        for m in out:
+            send(m)
+
+
+def cmd_mcp(conn, schema, ns):
+    """Run the MCP approver on stdio. Launched by Codex per its
+    [mcp_servers.pythia] config; lives for the session. Touches no database."""
+    mcp_serve(sys.stdin, sys.stdout, ns.project_root)
+
+
+# Codex config is TOML, and the stdlib cannot parse or write it on 3.9
+# (tomllib is read-only, 3.11+). So these merges never parse TOML: they append
+# a marker-delimited block when the target tables are absent, and refuse
+# (writing nothing) when a table already exists — the installer then prints
+# what to add. ponytail: literal-text collision check, not a TOML engine; a
+# table header inside a string/comment is not worth a parser here.
+CODEX_MCP_BEGIN = "# pythia:begin (managed by `pythia install`)"
+CODEX_MCP_END = "# pythia:end"
+CODEX_MCP_BLOCK = (f"{CODEX_MCP_BEGIN}\n"
+                   "[mcp_servers.pythia]\n"
+                   'command = "python"\n'
+                   'args = ["-m", "pythia", "mcp"]\n\n'
+                   "[approval_policy.granular]\n"
+                   "mcp_elicitations = true\n"
+                   f"{CODEX_MCP_END}")
+# requirements.toml is a separate admin-enforced file; forbidding these two is
+# what closes the danger-full-access elicitation auto-approve hole.
+CODEX_REQUIREMENTS = (f"{CODEX_MCP_BEGIN}\n"
+                      "# pythia needs elicitations to reach a human, so the two\n"
+                      "# modes that would auto-answer or skip them are disallowed.\n"
+                      'allowed_approval_policies = ["untrusted", "on-request", "on-failure"]\n'
+                      'allowed_sandbox_modes = ["read-only", "workspace-write"]\n'
+                      f"{CODEX_MCP_END}")
+
+
+def merge_codex_mcp_config(path):
+    """Append the MCP block to <project>/.codex/config.toml. Returns
+    (path, action): 'created' | 'appended' | 'present' | 'conflict'. Refuses
+    (writes nothing) if either table already exists without our marker."""
+    path = pathlib.Path(path)
+    old = path.read_text(encoding="utf-8") if path.is_file() else None
+    if old is not None and CODEX_MCP_BEGIN in old:
+        return path, "present"
+    if old is not None and ("[mcp_servers.pythia]" in old
+                            or "[approval_policy.granular]" in old):
+        return path, "conflict"
+    if old is None:
+        new, action = CODEX_MCP_BLOCK + "\n", "created"
+    else:
+        tail = "" if old.endswith("\n\n") else "\n" if old.endswith("\n") else "\n\n"
+        new, action = old + tail + CODEX_MCP_BLOCK + "\n", "appended"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(new, encoding="utf-8")
+    return path, action
+
+
+def merge_codex_requirements(path):
+    """Write <project>/.codex/requirements.toml forbidding danger-full-access
+    and never-approval. Returns (path, action): 'created' | 'present' |
+    'conflict'. An existing file without our marker is left untouched."""
+    path = pathlib.Path(path)
+    old = path.read_text(encoding="utf-8") if path.is_file() else None
+    if old is not None and CODEX_MCP_BEGIN in old:
+        return path, "present"
+    if old is not None:
+        return path, "conflict"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(CODEX_REQUIREMENTS + "\n", encoding="utf-8")
+    return path, "created"
+
 
 def install_claude_hooks(base_dir, events=None):
     """Merge the two hooks and the deny rule into <base>/.claude/settings.json
@@ -3357,6 +3665,58 @@ def report_claude_hooks(base_dir, ns, events=None):
         print(f"\nClaude Code hooks already in {path}.")
 
 
+def report_codex_agents_md(project_root):
+    """Project scope: write the harness into <project>/AGENTS.md, the file
+    Codex loads every session. Not done on -g — a global AGENTS.md is noise in
+    every non-Oracle session, as the Claude guide is per-project."""
+    path, action = merge_agents_md(pathlib.Path(project_root) / "AGENTS.md")
+    verb = {"created": "Wrote the pythia harness into",
+            "updated": "Updated the pythia block in",
+            "unchanged": "pythia harness already current in"}[action]
+    print(f"\n{verb} {path} (Codex and other AGENTS.md agents load it each session).")
+
+
+def report_codex_hooks(project_root, ns):
+    """Project scope: the Codex session-start guide hook. --no-hooks skips it,
+    as with the Claude hooks. AGENTS.md already carries the guide, so this is
+    reinforcement for hook-driven Codex users."""
+    if getattr(ns, "no_hooks", False):
+        return
+    path, added = merge_codex_hooks(pathlib.Path(project_root) / ".codex" / "hooks.json")
+    if added is None:
+        print(f"\n! {path} is not valid JSON, so it was left untouched.")
+    elif added:
+        print(f"\nWired the Codex session-start hook into {path}.")
+        print("In Codex, run /hooks once to trust this project's .codex layer.")
+    else:
+        print(f"\nCodex session-start hook already in {path}.")
+
+
+def report_codex_mcp(project_root, ns):
+    """Project scope: register the write-free MCP approver in Codex's config and
+    pin the sandbox so elicitations always reach a human. --no-hooks skips it,
+    as with the other Codex wiring. Needs Codex >= v0.120; older Codex ignores
+    the server and the console approve path still works."""
+    if getattr(ns, "no_hooks", False):
+        return
+    base = pathlib.Path(project_root) / ".codex"
+    cfg_path, cfg = merge_codex_mcp_config(base / "config.toml")
+    req_path, req = merge_codex_requirements(base / "requirements.toml")
+    if cfg in ("created", "appended"):
+        print(f"\nRegistered the pythia MCP approver in {cfg_path} "
+              "(Codex >= v0.120; run /mcp to trust it).")
+    elif cfg == "conflict":
+        print(f"\n! {cfg_path} already defines [mcp_servers.pythia] or "
+              "[approval_policy.granular]; add this yourself:\n"
+              + CODEX_MCP_BLOCK)
+    if req == "created":
+        print(f"Pinned the sandbox in {req_path} (no danger-full-access, so "
+              "elicitations always ask a human).")
+    elif req == "conflict":
+        print(f"\n! {req_path} already exists; add these constraints to it:\n"
+              + CODEX_REQUIREMENTS)
+
+
 def cmd_install(conn, schema, ns):
     import shutil
     en = getattr(ns, "color", False)
@@ -3398,6 +3758,9 @@ def cmd_install(conn, schema, ns):
         else:
             clean_legacy_skills(ns.project_root)
     report_claude_hooks(ns.project_root, ns)
+    report_codex_agents_md(ns.project_root)
+    report_codex_hooks(ns.project_root, ns)
+    report_codex_mcp(ns.project_root, ns)
     print(f"\nNext: fill in {path}")
     print(f"Then: {invocation()} check")
     scripts_dir = installed_scripts_dir()
@@ -3418,10 +3781,10 @@ COMMANDS = {"check": cmd_check, "ls": cmd_ls, "src": cmd_src, "args": cmd_args,
             "approve": cmd_approve,
             "conventions": cmd_conventions, "guide": cmd_guide, "connections": cmd_connections, "install": cmd_install,
             "unistr": cmd_unistr, "agent-user": cmd_agent_user,
-            "history": cmd_history}
+            "history": cmd_history, "mcp": cmd_mcp}
 
 NO_DB_COMMANDS = {"policy", "journal", "install", "unistr", "guide", "connections",
-                  "history", "approve"}
+                  "history", "approve", "mcp"}
 
 
 # --- CLI ---------------------------------------------------------------------
@@ -3565,6 +3928,9 @@ def build_parser():
     s.add_argument("text", nargs="*", help="text; omit to read stdin")
     s.add_argument("--loi", action="store_true",
                    help="wrap as 'loi:'||unistr(...)||':loi'")
+    sub.add_parser("mcp", parents=[common()],
+                   help="run the MCP approver for Codex (stdio; Codex launches "
+                        "it — the developer approves via an elicitation)")
     s = sub.add_parser("install", parents=[common()],
                        help="install the skill pack, scaffold .pythia/ config, wire the Claude Code hooks")
     s.add_argument("-g", "--global", dest="glob", action="store_true",

{pythia_plsql-0.12.0 → pythia_plsql-0.14.0/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.12.0
+Version: 0.14.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
@@ -128,7 +128,7 @@ Or the same thing piecewise:
 
 ```bash
 pip install pythia-plsql   # the CLI (thin driver — no Oracle Instant Client needed)
-python -m pythia install   # skills into your agent + .pythia/ scaffold + Claude Code hooks
+python -m pythia install   # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md
 pythia check               # fill in connections.json first, then verify
 ```
 
@@ -212,6 +212,10 @@ stops it prompting for the read-only commands and asks it to pause on
 writes — optional, and yours to install
 ([why pythia does not](GUIDE.md#11-optional-claude-code-permission-settings)).
 
+On Codex, the same command writes the harness into `AGENTS.md` (loaded every
+session) and a session-start hook into `.codex/hooks.json`; approve previews in
+the terminal with `pythia approve <token>`, since Codex has no chat-mint.
+
 Per-group write policy, `.pythia/policy.json` (defaults shown):
 
 | Group | Default | Is rollback real? |

{pythia_plsql-0.12.0 → pythia_plsql-0.14.0}/scripts/pythia_plsql.egg-info/SOURCES.txt

@@ -37,6 +37,7 @@ skills/pythia-write/SKILL.md
 skills/pythia-write/reference/patterns.md
 skills/using-pythia/SKILL.md
 tests/test_install.py
+tests/test_mcp.py
 tests/test_phase1.py
 tests/test_phase2.py
 tests/test_phase3.py

{pythia_plsql-0.12.0 → pythia_plsql-0.14.0}/skills/pythia-apply/SKILL.md

@@ -60,7 +60,7 @@ confirms a number you already knew.
    in the option descriptions; the hook does not read those. Header `pythia`;
    options exactly `Approve` / `Reject`, no "(Recommended)"; up to four tokens
    per call. Anything but `Approve` is not approval: stop and ask what should
-   change. File changed → step 1. No hook? Relay `pythia approve <token>`.
+   change. File changed → step 1. No hook (Codex, or none)? Relay `pythia approve <token>` in the terminal — Codex has no chat-mint.
 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"* — the answer was not `Approve`, or

{pythia_plsql-0.12.0 → pythia_plsql-0.14.0}/tests/test_install.py

@@ -57,16 +57,27 @@ def test_missing_npx_falls_back_to_the_bundled_pack():
         (agents / "pythia-apply").mkdir()      # stale copy from 0.2.0-0.2.3
         (claude / "plsql-review").mkdir(parents=True)
         targets = pythia.copy_bundled_skills(td)
-        assert targets == [claude]
+        assert targets == [claude, agents]
         assert (claude / "pythia-apply" / "SKILL.md").is_file()
         assert (claude / "pythia-review" / "reference" / "antipatterns.md").is_file()
-        assert not (agents / "pythia-apply").exists()       # single copy
+        assert (agents / "pythia-apply" / "SKILL.md").is_file()   # Codex reads this
         assert (agents / "my-team-skill" / "SKILL.md").read_text(
             encoding="utf-8") == "x"                         # merge, not wipe
         assert not (claude / "plsql-review").exists()        # legacy cleaned
         pythia.copy_bundled_skills(td)                       # idempotent
 
 
+def test_fallback_serves_both_claude_and_codex():
+    """Claude reads .claude/skills; Codex reads .agents/skills. The no-Node
+    fallback must populate both, or a Codex user without Node gets nothing."""
+    with tempfile.TemporaryDirectory() as td:
+        base = pathlib.Path(td)
+        targets = pythia.copy_bundled_skills(td)
+        assert targets == [base / ".claude" / "skills", base / ".agents" / "skills"]
+        for root in targets:
+            assert (root / "pythia-apply" / "SKILL.md").is_file()
+
+
 def test_copy_survives_a_symlinked_destination():
     """`npx skills add` leaves .claude/skills/<name> as a symlink into
     .agents/skills/<name>. Copying through that link and then cleaning the
@@ -350,6 +361,97 @@ def test_global_install_wires_the_approve_hook_only():
         assert s["hooks"]["PostToolUse"] == pythia.CLAUDE_HOOKS["PostToolUse"]
 
 
+def test_cmd_install_serves_codex_in_the_project_scope():
+    """Project install writes the harness into AGENTS.md always, and the
+    session-start hook unless --no-hooks. (The .agents/skills copy is gated by
+    global_pack_present() — a machine with a global pack skips it — so that is
+    proven directly in test_fallback_serves_both_claude_and_codex, not here.)"""
+    import argparse
+    import contextlib
+    import io
+    old = os.environ.get("PATH")
+    os.environ["PATH"] = ""                     # no npx: bundled fallback
+    try:
+        for no_hooks in (False, True):
+            with tempfile.TemporaryDirectory() as td:
+                ns = argparse.Namespace(project_root=td, glob=False, source=None,
+                                        color=False, json=False, no_hooks=no_hooks)
+                with contextlib.redirect_stdout(io.StringIO()):
+                    pythia.cmd_install(None, None, ns)
+                base = pathlib.Path(td)
+                agents_md = base / "AGENTS.md"
+                assert agents_md.is_file()                        # always
+                assert pythia.BRIEF_GUIDE.rstrip() in agents_md.read_text(encoding="utf-8")
+                hooks = base / ".codex" / "hooks.json"
+                assert hooks.is_file() != no_hooks                # skipped iff --no-hooks
+    finally:
+        if old is not None:
+            os.environ["PATH"] = old
+
+
+# --- Codex: AGENTS.md harness (TP1) ------------------------------------------
+
+def test_agents_md_block_is_the_guide_verbatim():
+    block = pythia.agents_md_block()
+    assert block.startswith(pythia.AGENTS_BEGIN)
+    assert block.rstrip().endswith(pythia.AGENTS_END)
+    assert pythia.BRIEF_GUIDE.rstrip() in block          # one source, no drift
+    assert "pythia approve <token>" in block             # the Codex approval door
+
+
+def test_merge_agents_md_creates_updates_and_is_idempotent():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / "AGENTS.md"
+        p, action = pythia.merge_agents_md(path)
+        assert p == path and action == "created"
+        assert pythia.BRIEF_GUIDE.rstrip() in path.read_text(encoding="utf-8")
+        assert pythia.merge_agents_md(path)[1] == "unchanged"
+
+
+def test_merge_agents_md_preserves_the_developers_text():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / "AGENTS.md"
+        path.write_text("# House rules\n\nUse tabs.\n", encoding="utf-8")
+        pythia.merge_agents_md(path)
+        body = path.read_text(encoding="utf-8")
+        assert body.startswith("# House rules\n\nUse tabs.\n")   # kept, on top
+        assert pythia.AGENTS_BEGIN in body and pythia.BRIEF_GUIDE.rstrip() in body
+        pythia.merge_agents_md(path)                             # a stale block
+        assert path.read_text(encoding="utf-8").count(pythia.AGENTS_BEGIN) == 1
+
+
+# --- Codex: session-start hook (TP3) -----------------------------------------
+
+def test_merge_codex_hooks_creates_and_is_idempotent():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "hooks.json"
+        p, added = pythia.merge_codex_hooks(path)
+        assert p == path and added == ["hooks.SessionStart"]
+        s = json.loads(path.read_text(encoding="utf-8"))
+        assert s["hooks"]["SessionStart"] == pythia.CODEX_HOOKS["SessionStart"]
+        assert pythia.merge_codex_hooks(path) == (path, [])
+
+
+def test_merge_codex_hooks_recognises_an_existing_spelling():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "hooks.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({"hooks": {"SessionStart": [
+            {"hooks": [{"type": "command",
+                        "command": "python3 -m pythia guide --brief"}]}]}}),
+            encoding="utf-8")
+        assert pythia.merge_codex_hooks(path) == (path, [])   # not doubled
+
+
+def test_merge_codex_hooks_refuses_a_file_it_cannot_parse():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "hooks.json"
+        path.parent.mkdir(parents=True)
+        path.write_text("{not json", encoding="utf-8")
+        assert pythia.merge_codex_hooks(path) == (path, None)
+        assert path.read_text(encoding="utf-8") == "{not json"
+
+
 # Native paths: on POSIX ':' is the PATH separator and would cut a
 # Windows path in half, so these are built from os.sep.
 SCRIPTS = os.path.join(os.sep + 'opt', 'a', 'Scripts')

pythia_plsql-0.14.0/tests/test_mcp.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""MCP approver self-checks — no database, no network, no live Codex.
+
+Run: python tests/test_mcp.py
+"""
+import io
+import json
+import os
+import pathlib
+import sys
+import tempfile
+
+os.environ.setdefault("PYTHIA_CI", "1")
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "scripts"))
+import pythia  # noqa: E402
+
+
+# --- Task 1: transport handshake + tools/list -------------------------------
+
+def test_initialize_echoes_protocol_and_declares_tools():
+    out, done = pythia.mcp_handle(
+        {"jsonrpc": "2.0", "id": 1, "method": "initialize",
+         "params": {"protocolVersion": "2025-06-18", "capabilities": {},
+                    "clientInfo": {"name": "codex", "version": "0.120.0"}}},
+        {})
+    assert done is False
+    assert len(out) == 1
+    r = out[0]
+    assert r["id"] == 1 and r["jsonrpc"] == "2.0"
+    assert r["result"]["protocolVersion"] == "2025-06-18"     # echo client's
+    assert "tools" in r["result"]["capabilities"]
+    assert r["result"]["serverInfo"]["name"] == "pythia"
+
+
+def test_initialized_notification_is_silent():
+    out, done = pythia.mcp_handle(
+        {"jsonrpc": "2.0", "method": "notifications/initialized"}, {})
+    assert out == [] and done is False
+
+
+def test_tools_list_returns_only_pythia_approve():
+    out, _ = pythia.mcp_handle(
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, {})
+    tools = out[0]["result"]["tools"]
+    assert [t["name"] for t in tools] == ["pythia_approve"]
+    schema = tools[0]["inputSchema"]
+    assert schema["properties"]["token"]["type"] == "string"
+    assert schema["required"] == ["token"]
+
+
+def test_unknown_method_with_id_is_an_error_not_a_crash():
+    out, _ = pythia.mcp_handle(
+        {"jsonrpc": "2.0", "id": 3, "method": "resources/list"}, {})
+    assert out[0]["error"]["code"] == -32601        # method not found
+    assert out[0]["id"] == 3
+
+
+# --- Task 2: the elicitation round-trip and the mint (fail-closed) ----------
+
+def _preview(root, token="a1b2c3"):
+    """A pending plsql_source preview in the journal, the way apply writes one."""
+    pythia.write_journal_entry(
+        root, "PACKAGE BODY", "PKG_ORDER", "old\n",
+        "CREATE OR REPLACE PACKAGE BODY pkg_order AS\n new;\nEND;\n",
+        {"token": token, "connection": "DEV", "schema": "APP",
+         "group": "plsql_source", "applied": False})
+    return token
+
+
+def test_mint_only_on_accept_with_approve():
+    with tempfile.TemporaryDirectory() as td:
+        token = _preview(td)
+        seen = {}
+
+        def elicit(message, schema):
+            seen["message"] = message
+            seen["schema"] = schema
+            return "accept", {"decision": "Approve"}
+
+        res = pythia.mcp_approve_decision(td, token, elicit)
+        assert res["isError"] is False
+        assert token in res["content"][0]["text"]
+        assert "PKG_ORDER" in seen["message"]                 # the card was shown
+        assert seen["schema"]["properties"]["decision"]["enum"] == ["Approve", "Reject"]
+        g = pythia.read_grant(td, token)
+        assert g and g["approver"] == "mcp" and g["used_at"] is None
+
+
+def test_no_mint_on_reject_decline_or_cancel():
+    for action, content in (("accept", {"decision": "Reject"}),
+                            ("decline", {}), ("cancel", {})):
+        with tempfile.TemporaryDirectory() as td:
+            token = _preview(td)
+            res = pythia.mcp_approve_decision(td, token, lambda m, s: (action, content))
+            assert res["isError"] is True
+            assert pythia.read_grant(td, token) is None       # nothing minted
+
+
+def test_no_mint_for_unknown_token_and_elicit_is_not_even_called():
+    with tempfile.TemporaryDirectory() as td:
+        called = []
+        res = pythia.mcp_approve_decision(
+            td, "nope99",
+            lambda m, s: called.append(1) or ("accept", {"decision": "Approve"}))
+        assert res["isError"] is True
+        assert called == []                                   # refused before asking
+        assert pythia.read_grant(td, "nope99") is None
+
+
+def test_elicit_error_fails_closed():
+    with tempfile.TemporaryDirectory() as td:
+        token = _preview(td)
+
+        def boom(message, schema):
+            raise RuntimeError("transport died")
+
+        res = pythia.mcp_approve_decision(td, token, boom)
+        assert res["isError"] is True
+        assert pythia.read_grant(td, token) is None
+
+
+# --- Task 3: the server loop, the mcp subcommand, and the guide -------------
+
+class ScriptedClient:
+    """Feeds the server initialize -> tools/call, then answers the server's
+    elicitation/create with a fixed (action, decision). Acts as both reader
+    and writer for mcp_serve."""
+    def __init__(self, token, action="accept", decision="Approve"):
+        self.out = io.StringIO()
+        self.answered = False
+        self.action, self.decision = action, decision
+        self._pending = [
+            {"jsonrpc": "2.0", "id": 1, "method": "initialize",
+             "params": {"protocolVersion": "2025-06-18", "capabilities": {}}},
+            {"jsonrpc": "2.0", "id": 2, "method": "tools/call",
+             "params": {"name": "pythia_approve", "arguments": {"token": token}}},
+        ]
+
+    def readline(self):
+        if self._pending:
+            return json.dumps(self._pending.pop(0)) + "\n"
+        if not self.answered:
+            for line in reversed(self.out.getvalue().splitlines()):
+                m = json.loads(line)
+                if m.get("method") == pythia.MCP_ELICIT_METHOD:
+                    self.answered = True
+                    return json.dumps({"jsonrpc": "2.0", "id": m["id"],
+                                       "result": {"action": self.action,
+                                                  "content": {"decision": self.decision}}}) + "\n"
+        return ""     # EOF -> server loop ends
+
+    def write(self, s):
+        self.out.write(s)
+
+    def flush(self):
+        pass
+
+    def messages(self):
+        return [json.loads(l) for l in self.out.getvalue().splitlines() if l.strip()]
+
+
+def test_serve_end_to_end_mints_on_scripted_approve():
+    with tempfile.TemporaryDirectory() as td:
+        token = _preview(td)
+        client = ScriptedClient(token)
+        pythia.mcp_serve(client, client, td)
+        msgs = client.messages()
+        assert any(m.get("result", {}).get("serverInfo", {}).get("name") == "pythia"
+                   for m in msgs)
+        assert any(m.get("method") == pythia.MCP_ELICIT_METHOD for m in msgs)
+        call_result = [m for m in msgs if m.get("id") == 2 and "result" in m][-1]
+        assert call_result["result"]["isError"] is False
+        assert pythia.read_grant(td, token)["approver"] == "mcp"
+
+
+def test_serve_fails_closed_on_scripted_decline():
+    with tempfile.TemporaryDirectory() as td:
+        token = _preview(td)
+        client = ScriptedClient(token, action="decline", decision="")
+        pythia.mcp_serve(client, client, td)
+        call_result = [m for m in client.messages()
+                       if m.get("id") == 2 and "result" in m][-1]
+        assert call_result["result"]["isError"] is True
+        assert pythia.read_grant(td, token) is None
+
+
+def test_mcp_is_a_no_db_command_in_the_guide():
+    assert "mcp" in pythia.COMMANDS
+    assert "mcp" in pythia.NO_DB_COMMANDS
+    assert "mcp" in pythia.OPERATING_GUIDE
+
+
+# --- Task 4: config.toml and requirements.toml merges (TOML-safe) -----------
+
+def test_merge_codex_mcp_config_appends_once_when_clean():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "config.toml"
+        p, action = pythia.merge_codex_mcp_config(path)
+        assert p == path and action == "created"
+        body = path.read_text(encoding="utf-8")
+        assert "[mcp_servers.pythia]" in body
+        assert 'args = ["-m", "pythia", "mcp"]' in body
+        assert "mcp_elicitations = true" in body
+        assert pythia.merge_codex_mcp_config(path)[1] == "present"   # idempotent
+
+
+def test_merge_codex_mcp_config_preserves_other_content():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "config.toml"
+        path.parent.mkdir(parents=True)
+        path.write_text('model = "gpt-5"\n', encoding="utf-8")
+        _, action = pythia.merge_codex_mcp_config(path)
+        assert action == "appended"
+        body = path.read_text(encoding="utf-8")
+        assert body.startswith('model = "gpt-5"\n')                  # kept
+        assert "[mcp_servers.pythia]" in body
+
+
+def test_merge_codex_mcp_config_refuses_on_table_collision():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "config.toml"
+        path.parent.mkdir(parents=True)
+        original = "[approval_policy.granular]\nmcp_elicitations = false\n"
+        path.write_text(original, encoding="utf-8")
+        p, action = pythia.merge_codex_mcp_config(path)
+        assert action == "conflict"
+        assert path.read_text(encoding="utf-8") == original          # untouched
+
+
+def test_merge_codex_requirements_creates_and_is_idempotent():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "requirements.toml"
+        p, action = pythia.merge_codex_requirements(path)
+        assert action == "created"
+        body = path.read_text(encoding="utf-8")
+        assert "allowed_approval_policies" in body and "allowed_sandbox_modes" in body
+        assert "danger-full-access" not in body     # the forbidden mode is absent
+        assert '"never"' not in body                 # the forbidden policy is absent
+        assert pythia.merge_codex_requirements(path)[1] == "present"
+
+
+def test_merge_codex_requirements_refuses_an_existing_file():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "requirements.toml"
+        path.parent.mkdir(parents=True)
+        original = "# org policy\nallowed_sandbox_modes = []\n"
+        path.write_text(original, encoding="utf-8")
+        p, action = pythia.merge_codex_requirements(path)
+        assert action == "conflict"
+        assert path.read_text(encoding="utf-8") == original          # untouched
+
+
+# --- Task 5: wire the MCP install into cmd_install (project scope) ----------
+
+def test_cmd_install_registers_the_mcp_server_and_pins_the_sandbox():
+    import argparse
+    import contextlib
+    old = os.environ.get("PATH")
+    os.environ["PATH"] = ""
+    try:
+        with tempfile.TemporaryDirectory() as td:
+            ns = argparse.Namespace(project_root=td, glob=False, source=None,
+                                    color=False, json=False, no_hooks=False)
+            with contextlib.redirect_stdout(io.StringIO()):
+                pythia.cmd_install(None, None, ns)
+            cfg = pathlib.Path(td) / ".codex" / "config.toml"
+            req = pathlib.Path(td) / ".codex" / "requirements.toml"
+            assert "[mcp_servers.pythia]" in cfg.read_text(encoding="utf-8")
+            assert "mcp_elicitations = true" in cfg.read_text(encoding="utf-8")
+            assert "allowed_sandbox_modes" in req.read_text(encoding="utf-8")
+    finally:
+        if old is not None:
+            os.environ["PATH"] = old
+
+
+def test_cmd_install_no_hooks_skips_the_mcp_files():
+    import argparse
+    import contextlib
+    old = os.environ.get("PATH")
+    os.environ["PATH"] = ""
+    try:
+        with tempfile.TemporaryDirectory() as td:
+            ns = argparse.Namespace(project_root=td, glob=False, source=None,
+                                    color=False, json=False, no_hooks=True)
+            with contextlib.redirect_stdout(io.StringIO()):
+                pythia.cmd_install(None, None, ns)
+            assert not (pathlib.Path(td) / ".codex" / "config.toml").exists()
+    finally:
+        if old is not None:
+            os.environ["PATH"] = old
+
+
+def main():
+    failed = 0
+    for name, fn in sorted(globals().items()):
+        if name.startswith("test_") and callable(fn):
+            try:
+                fn()
+                print(f"PASS {name}")
+            except (Exception, SystemExit) as e:  # noqa: BLE001 — keep going
+                failed += 1
+                print(f"FAIL {name}: {e!r}")
+    if failed:
+        sys.exit(f"{failed} test(s) failed")
+    print("OK")
+
+
+if __name__ == "__main__":
+    main()