maskflow-agent 0.1.0__tar.gz

maskflow_agent-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+node_modules/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.pytest_cache/
+.idea/
+.coverage
+.mypy_cache/
+.ruff_cache/
+bench/indiapii/quality/.cache/

maskflow_agent-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: maskflow-agent
+Version: 0.1.0
+Summary: MaskFlow guard for AI coding agents: Claude Code hooks that mask PII (Aadhaar, PAN, UPI, mobile, ...) in tool output before the model sees it, and restore values only inside allowlisted commands at run time.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: maskflow-sdk<0.10,>=0.9.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# maskflow-agent
+
+**Use Claude Code on production data without Indian PII reaching the model.**
+
+Claude Code hooks that mask personal data (Aadhaar, PAN, UPI IDs, mobile
+numbers, bank accounts, names, ...) in every tool result before the model
+sees it. Real values are restored only inside allowlisted database/kubectl
+commands, at run time, in a separate process. The agent can still run
+`UPDATE kyc ... WHERE pan='<PAN_3>'` against the right row without ever
+seeing the PAN.
+
+```bash
+pip install maskflow-agent
+maskflow-agent install        # adds hooks to .claude/settings.json
+maskflow-agent doctor         # proves it end to end with synthetic canaries
+```
+
+- Tool output masked: Bash, Read, Grep, WebFetch, MCP, ...
+- One placeholder per value for the whole session. A value identified once is
+  masked everywhere after that.
+- Fails closed: if the guard can't run, the tool doesn't either.
+- Never grants permissions you didn't already have.
+- The transcript on disk, the permission prompt and logs only ever see
+  placeholders.
+- MIT, no telemetry, everything runs locally.
+
+Requires Claude Code 2.1.295+ on macOS or Linux. Full documentation, threat
+model and limits:
+[docs/agent.md](https://github.com/maskflow/maskflow/blob/main/docs/agent.md).

maskflow_agent-0.1.0/README.md

@@ -0,0 +1,29 @@
+# maskflow-agent
+
+**Use Claude Code on production data without Indian PII reaching the model.**
+
+Claude Code hooks that mask personal data (Aadhaar, PAN, UPI IDs, mobile
+numbers, bank accounts, names, ...) in every tool result before the model
+sees it. Real values are restored only inside allowlisted database/kubectl
+commands, at run time, in a separate process. The agent can still run
+`UPDATE kyc ... WHERE pan='<PAN_3>'` against the right row without ever
+seeing the PAN.
+
+```bash
+pip install maskflow-agent
+maskflow-agent install        # adds hooks to .claude/settings.json
+maskflow-agent doctor         # proves it end to end with synthetic canaries
+```
+
+- Tool output masked: Bash, Read, Grep, WebFetch, MCP, ...
+- One placeholder per value for the whole session. A value identified once is
+  masked everywhere after that.
+- Fails closed: if the guard can't run, the tool doesn't either.
+- Never grants permissions you didn't already have.
+- The transcript on disk, the permission prompt and logs only ever see
+  placeholders.
+- MIT, no telemetry, everything runs locally.
+
+Requires Claude Code 2.1.295+ on macOS or Linux. Full documentation, threat
+model and limits:
+[docs/agent.md](https://github.com/maskflow/maskflow/blob/main/docs/agent.md).

maskflow_agent-0.1.0/examples/demo/README.md

@@ -0,0 +1,62 @@
+# Recording the maskflow-agent demo
+
+`.github/assets/agent-demo.svg` is rendered from two **real** `claude -p`
+sessions running the same task against the same database: one without the
+guard, one with it. Nothing in it is typed by hand. All data is **synthetic**
+(`make_db.py`: seeded, Verhoeff-valid Aadhaar numbers, random PAN/mobile/UPI,
+names from MaskFlow's public name list).
+
+```bash
+D=packages/maskflow-agent/examples/demo
+mkdir -p /tmp/demo-off/.claude /tmp/demo-on/.claude
+for d in /tmp/demo-off /tmp/demo-on; do
+  python $D/make_db.py $d/kyc.db
+  echo '{"permissions":{"allow":["Bash(sqlite3:*)"]}}' > $d/.claude/settings.local.json
+done
+(cd /tmp/demo-on && maskflow-agent install --scope local)
+
+PROMPT="Support ticket: KYC for customer 4 is stuck. Look the customer up in kyc.db (use sqlite3 -header; table kyc), then set their status to verified, matching on their PAN. Show me the row afterwards."
+(cd /tmp/demo-off && claude -p "$PROMPT")
+(cd /tmp/demo-on  && claude -p "$PROMPT")
+
+# Transcripts live in ~/.claude/projects/<dir>/<session-id>.jsonl
+python $D/capture.py ~/.claude/projects/-tmp-demo-off/<id>.jsonl $D/session-without-guard.json
+python $D/capture.py ~/.claude/projects/-tmp-demo-on/<id>.jsonl  $D/session-with-guard.json
+python $D/render_svg.py $D/session-without-guard.json $D/session-with-guard.json \
+    /tmp/demo-on/kyc.db .github/assets/agent-demo.svg
+```
+
+The two committed `session-*.json` files are the captures behind the
+current SVG. The model picks its own queries, so a new recording will differ
+in detail. Before using a recording, check that the guarded transcript has
+none of the database's values:
+
+```bash
+python - ~/.claude/projects/-tmp-demo-on/<id>.jsonl <<'PY'
+import sqlite3, sys
+txt = open(sys.argv[1]).read()
+vals = [str(v) for r in sqlite3.connect("/tmp/demo-on/kyc.db").execute(
+    "select name, aadhaar, pan, mobile, upi from kyc") for v in r]
+print([v for v in vals if v in txt] or "clean")
+PY
+```
+
+## Video (MP4 / GIF)
+
+`record_video.mjs` renders the SVG frame by frame in your installed Chrome
+(it pauses every CSS animation and seeks it) and writes PNG frames.
+`ffmpeg` then encodes them. Neither tool is a project dependency; install
+them into a throwaway folder:
+
+```bash
+mkdir -p /tmp/video-deps /tmp/frames && (cd /tmp/video-deps && npm init -y >/dev/null \
+  && npm install puppeteer-core@23.11.1 ffmpeg-static@5.2.0)
+node $D/record_video.mjs /tmp/video-deps .github/assets/agent-demo.svg /tmp/frames 26 30 14.5 0.65
+FF=$(node -e "process.stdout.write(require('/tmp/video-deps/node_modules/ffmpeg-static'))")
+$FF -framerate 30 -i /tmp/frames/f%05d.png -c:v libx264 -crf 18 -pix_fmt yuv420p \
+    -movflags +faststart maskflow-agent-demo.mp4
+```
+
+The arguments are: 26 s of video at 30 fps, with the animation played at
+0.65× speed until 14.5 s of animation time, then held. `replay.py` prints
+the same capture in a terminal, if you'd rather screen-record a terminal.

maskflow_agent-0.1.0/examples/demo/capture.py

@@ -0,0 +1,52 @@
+"""Extract what the MODEL saw in a Claude Code session into demo JSON.
+
+    python capture.py <session.jsonl> <out.json>
+
+Reads the transcript Claude Code wrote (~/.claude/projects/<dir>/<id>.jsonl):
+the prompt, each Bash command the model issued, the tool result it was
+given back, and its final answer. All values in the demo database are
+SYNTHETIC (see make_db.py), so the captured JSON is safe to commit.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def _text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "\n".join(_text(c.get("text", "")) for c in content if isinstance(c, dict))
+    return ""
+
+
+def capture(path: str) -> dict[str, Any]:
+    prompt, final = "", ""
+    steps: list[dict[str, str]] = []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            entry = json.loads(line)
+            message = entry.get("message") or {}
+            content = message.get("content")
+            if entry.get("type") == "user" and isinstance(content, str) and not prompt:
+                prompt = content
+            if not isinstance(content, list):
+                continue
+            for block in content:
+                if block.get("type") == "tool_use" and block.get("name") == "Bash":
+                    steps.append({"command": block["input"].get("command", ""), "result": ""})
+                elif block.get("type") == "tool_result" and steps:
+                    steps[-1]["result"] = _text(block.get("content")).strip()
+                elif block.get("type") == "text" and entry.get("type") == "assistant":
+                    final = block.get("text", "")
+    return {"prompt": prompt, "steps": steps, "final": final}
+
+
+if __name__ == "__main__":
+    data = capture(sys.argv[1])
+    with open(sys.argv[2], "w", encoding="utf-8") as out:
+        json.dump(data, out, indent=2, ensure_ascii=False)
+    print(f"{len(data['steps'])} commands captured -> {sys.argv[2]}")

maskflow_agent-0.1.0/examples/demo/make_db.py

@@ -0,0 +1,51 @@
+"""Build the demo's KYC database. Every value is SYNTHETIC: names from
+MaskFlow's public name list, Aadhaar numbers with a valid Verhoeff check
+digit, PAN/mobile/UPI in the right shape -- all random, seeded, and none
+belonging to a real person.
+
+    python make_db.py kyc.db
+"""
+
+from __future__ import annotations
+
+import random
+import sqlite3
+import sys
+
+from maskflow_pack_india.checksums import verhoeff_generate
+
+NAMES = ["Ananya Iyer", "Rohan Mehta", "Priya Nair", "Arjun Reddy", "Kavya Sharma", "Vikram Rao"]
+PSPS = ["okaxis", "oksbi", "ybl", "paytm"]
+LETTERS = "ABCDEFGHJKLMNPRSTUVWXYZ"
+
+
+def row(rng: random.Random, i: int, name: str) -> tuple[object, ...]:
+    base = rng.choice("23456789") + "".join(rng.choice("0123456789") for _ in range(10))
+    aadhaar = base + verhoeff_generate(base)
+    pan = (
+        "".join(rng.choice(LETTERS) for _ in range(3)) + "P" + name.split()[-1][0]
+        + "".join(rng.choice("0123456789") for _ in range(4)) + rng.choice(LETTERS)
+    )  # fmt: skip
+    mobile = rng.choice("6789") + "".join(rng.choice("0123456789") for _ in range(9))
+    upi = f"{name.split()[0].lower()}{rng.randint(10, 99)}@{rng.choice(PSPS)}"
+    status = "stuck" if i == 4 else rng.choice(["verified", "verified", "pending"])
+    return (i, name, aadhaar, pan, mobile, upi, status)
+
+
+def main(path: str) -> None:
+    rng = random.Random(4207)
+    db = sqlite3.connect(path)
+    db.execute("DROP TABLE IF EXISTS kyc")
+    db.execute(
+        "CREATE TABLE kyc (id INTEGER PRIMARY KEY, name TEXT, aadhaar TEXT, pan TEXT, "
+        "mobile TEXT, upi TEXT, status TEXT)"
+    )
+    db.executemany(
+        "INSERT INTO kyc VALUES (?, ?, ?, ?, ?, ?, ?)",
+        [row(rng, i, n) for i, n in enumerate(NAMES, 1)],
+    )
+    db.commit()
+
+
+if __name__ == "__main__":
+    main(sys.argv[1] if len(sys.argv) > 1 else "kyc.db")

maskflow_agent-0.1.0/examples/demo/record_video.mjs

@@ -0,0 +1,38 @@
+// Render the animated demo SVG to PNG frames with the user's Chrome, by
+// pausing every CSS animation and seeking it to each frame's time.
+// usage: node record.mjs <deps-dir> <svg> <frames-dir> <seconds> <fps> <anim-seconds> <rate>
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+
+const [depsDir, svgPath, framesDir, seconds, fps, animSeconds, rate] = process.argv.slice(2);
+const require = createRequire(depsDir + "/package.json");
+const puppeteer = require("puppeteer-core");
+
+const svg = readFileSync(svgPath, "utf8");
+const browser = await puppeteer.launch({
+  executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  headless: true,
+  args: ["--hide-scrollbars"],
+});
+const page = await browser.newPage();
+await page.setViewport({ width: 1280, height: 720, deviceScaleFactor: 1.5 }); // 1920x1080
+await page.setContent(
+  `<!doctype html><html><body style="margin:0;background:#0d1117">${svg}</body></html>`,
+  { waitUntil: "load" },
+);
+
+const total = Number(seconds) * Number(fps);
+for (let i = 0; i < total; i++) {
+  // Play the animation at `rate` x speed up to `animSeconds`, then hold.
+  const videoTime = (i / Number(fps)) * Number(rate);
+  const t = Math.min(videoTime, Number(animSeconds)) * 1000;
+  await page.evaluate((ms) => {
+    for (const a of document.getAnimations()) {
+      a.pause();
+      a.currentTime = ms;
+    }
+  }, t);
+  await page.screenshot({ path: `${framesDir}/f${String(i).padStart(5, "0")}.png` });
+}
+await browser.close();
+console.log(`${total} frames`);

maskflow_agent-0.1.0/examples/demo/render_svg.py

@@ -0,0 +1,229 @@
+"""Render the split-screen demo SVG from two captured sessions.
+
+    python render_svg.py off.json on.json kyc.db out.svg
+
+Left: the session without the guard. Right: the same task with
+maskflow-agent. Every command and value shown is taken from the captures
+(capture.py) -- nothing is typed in by hand. Values that exist in the demo
+database (all SYNTHETIC, see make_db.py) are highlighted red wherever the
+model saw them; placeholders are highlighted green.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import sys
+import textwrap
+from html import escape
+from typing import Any
+
+W, H = 1280, 720
+PANEL_W = 600
+LEFT_X, RIGHT_X = 30, 650
+TOP = 132
+LINE = 22
+CHARS = 60
+LOOP = 18.0  # seconds
+
+BG, PANEL, BORDER = "#0d1117", "#161b22", "#30363d"
+TEXT, DIM = "#e6edf3", "#8b949e"
+RED, GREEN, BLUE, AMBER = "#ff7b72", "#3fb950", "#79c0ff", "#d29922"
+BOLD = ' font-weight="700"'
+PLACEHOLDER = re.compile(r"<[A-Z][A-Z_]*_\d+>")
+
+
+def _row(db: str, row_id: int) -> dict[str, str]:
+    conn = sqlite3.connect(db)
+    conn.row_factory = sqlite3.Row
+    found = conn.execute("SELECT * FROM kyc WHERE id = ?", (row_id,)).fetchone()
+    return {k: str(found[k]) for k in found.keys()} if found else {}
+
+
+def _db_values(db: str) -> dict[str, str]:
+    conn = sqlite3.connect(db)
+    cols = [c[1] for c in conn.execute("PRAGMA table_info(kyc)")]
+    out: dict[str, str] = {}
+    for row in conn.execute("SELECT * FROM kyc"):
+        for col, value in zip(cols, row, strict=True):
+            if col in ("name", "aadhaar", "pan", "mobile", "upi"):
+                out[str(value)] = col
+    return out
+
+
+def _spans(line: str, raw: dict[str, str]) -> list[tuple[str, str]]:
+    """Split a line into (text, colour) runs: raw DB values red, placeholders green."""
+    marks: list[tuple[int, int, str]] = [
+        (m.start(), m.end(), GREEN) for m in PLACEHOLDER.finditer(line)
+    ]
+    for value in raw:
+        start = line.find(value)
+        while start != -1:
+            marks.append((start, start + len(value), RED))
+            start = line.find(value, start + 1)
+    marks.sort()
+    runs, cursor = [], 0
+    for start, end, colour in marks:
+        if start < cursor:
+            continue
+        runs.append((line[cursor:start], ""))
+        runs.append((line[start:end], colour))
+        cursor = end
+    runs.append((line[cursor:], ""))
+    return [r for r in runs if r[0]]
+
+
+FIELDS = ("name", "aadhaar", "pan", "mobile", "upi")
+PLACEHOLDER_TYPE = {
+    "name": "PERSON_NAME",
+    "aadhaar": "AADHAAR",
+    "pan": "PAN",
+    "mobile": "INDIAN_MOBILE",
+    "upi": "UPI_VPA",
+}
+
+
+def _seen_fields(result: str, raw: dict[str, str], row_values: dict[str, str]) -> list[str]:
+    """Format-agnostic: for each sensitive field of the looked-up record, what
+    the model actually received -- the real value if it is in the output,
+    else the placeholder of that type found in the output."""
+    # The record's own output line (first cell == its id), so a query that
+    # returned several rows doesn't show another customer's placeholders.
+    record_id = row_values.get("id", "")
+    for candidate in result.splitlines():
+        first = re.split(r"[|,\s]+", candidate.strip(" |"), maxsplit=1)[0]
+        if record_id and first == record_id:
+            result = candidate
+            break
+    lines = []
+    for field in FIELDS:
+        value = row_values.get(field, "")
+        if value and value in result:
+            shown = value
+        else:
+            match = re.search(rf"<{PLACEHOLDER_TYPE[field]}_\d+>", result)
+            if not match:
+                continue
+            shown = match.group(0)
+        lines.append(f"    {field:<8} {shown}")
+    return lines
+
+
+def _panel_lines(
+    data: dict[str, Any], raw: dict[str, str], row_values: dict[str, str]
+) -> list[tuple[str, str]]:
+    """(text, base colour) lines for one panel."""
+    lines: list[tuple[str, str]] = []
+    for chunk in textwrap.wrap(data["prompt"], CHARS - 2):
+        lines.append(("> " + chunk if not lines else "  " + chunk, TEXT))
+    lines.append(("", TEXT))
+    for step in data["steps"]:
+        for i, chunk in enumerate(textwrap.wrap(step["command"], CHARS - 2)):
+            lines.append((("$ " if i == 0 else "  ") + chunk, BLUE))
+        if "UPDATE" in step["command"].upper():
+            status = "verified" if "verified" in step["result"] else "?"
+            lines.append((f"  -> row updated, status = {status}", GREEN))
+        else:
+            seen = _seen_fields(step["result"], raw, row_values)
+            if seen:
+                lines.append(("  the model received:", DIM))
+                lines += [(line, TEXT) for line in seen]
+        lines.append(("", TEXT))
+    return lines
+
+
+def _leaked(data: dict[str, Any], raw: dict[str, str]) -> list[str]:
+    seen = json.dumps(data["steps"])
+    return sorted({col for value, col in raw.items() if value in seen})
+
+
+def _render_lines(
+    x: int, lines: list[tuple[str, str]], raw: dict[str, str], t0: float
+) -> list[str]:
+    out = []
+    for i, (text, base) in enumerate(lines):
+        y = TOP + i * LINE
+        delay = t0 + i * 0.45
+        tspans = "".join(
+            f'<tspan fill="{colour or base}"{BOLD if colour else ""}>{escape(run)}</tspan>'
+            for run, colour in _spans(text, raw)
+        )
+        out.append(
+            f'<text class="l" x="{x + 18}" y="{y}" style="animation-delay:{delay:.2f}s">'
+            f"{tspans}</text>"
+        )
+    return out
+
+
+def render(off: dict[str, Any], on: dict[str, Any], db: str) -> str:
+    raw = _db_values(db)
+    record = _row(db, 4)
+    left, right = _panel_lines(off, raw, record), _panel_lines(on, raw, record)
+    leaked_off, leaked_on = _leaked(off, raw), _leaked(on, raw)
+    n = max(len(left), len(right))
+    summary_t = 0.6 + n * 0.45
+
+    def verdict(leaked: list[str]) -> tuple[str, str]:
+        if leaked:
+            return f"Sent to the model: {', '.join(leaked)}", RED
+        return "Sent to the model: no personal data. Row updated.", GREEN
+
+    parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{W}" height="{H}" '
+        f'viewBox="0 0 {W} {H}" role="img" aria-label="Split-screen demo: the same Claude '
+        f"Code task on a KYC table without and with maskflow-agent. Without it the model "
+        f"receives Aadhaar, PAN, mobile and UPI values; with it the model sees only "
+        f'placeholders and still updates the right row.">',
+        "<title>maskflow-agent demo</title>",
+        "<style>",
+        f"text{{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:15px;fill:{TEXT}}}",
+        "text{white-space:pre}",
+        ".h{font-family:-apple-system,Segoe UI,Helvetica,Arial,sans-serif}",
+        f".l{{opacity:0;animation:show {LOOP}s infinite}}",
+        "@keyframes show{0%{opacity:0}3%{opacity:1}92%{opacity:1}100%{opacity:0}}",
+        "@media (prefers-reduced-motion: reduce){.l{animation:none;opacity:1}}",
+        "</style>",
+        f'<rect width="{W}" height="{H}" rx="14" fill="{BG}"/>',
+        f'<text class="h" x="{W // 2}" y="44" text-anchor="middle" font-size="22" '
+        f'font-weight="700" fill="{TEXT}">Same task. Same data. One of them leaks it.</text>',
+    ]
+    for x, title, colour in (
+        (LEFT_X, "Claude Code", RED),
+        (RIGHT_X, "Claude Code + maskflow-agent", GREEN),
+    ):
+        parts.append(
+            f'<rect x="{x}" y="70" width="{PANEL_W}" height="{H - 150}" rx="10" '
+            f'fill="{PANEL}" stroke="{BORDER}"/>'
+        )
+        parts.append(f'<circle cx="{x + 22}" cy="92" r="6" fill="{colour}"/>')
+        parts.append(
+            f'<text class="h" x="{x + 38}" y="97" font-size="16" font-weight="600" '
+            f'fill="{TEXT}">{escape(title)}</text>'
+        )
+    parts += _render_lines(LEFT_X, left, raw, 0.6)
+    parts += _render_lines(RIGHT_X, right, raw, 0.6)
+    for x, (label, colour) in ((LEFT_X, verdict(leaked_off)), (RIGHT_X, verdict(leaked_on))):
+        parts.append(
+            f'<text class="l h" x="{x + 18}" y="{H - 100}" font-size="17" font-weight="700" '
+            f'fill="{colour}" style="animation-delay:{summary_t:.2f}s">{escape(label)}</text>'
+        )
+    parts.append(
+        f'<text class="h" x="{W // 2}" y="{H - 34}" text-anchor="middle" font-size="16" '
+        f'fill="{DIM}">pip install maskflow-agent  ·  maskflow-agent install  ·  '
+        f"synthetic data, real Claude Code sessions</text>"
+    )
+    parts.append("</svg>")
+    return "\n".join(parts) + "\n"
+
+
+if __name__ == "__main__":
+    off_path, on_path, db_path, out_path = sys.argv[1:5]
+    with open(off_path, encoding="utf-8") as f:
+        off_data = json.load(f)
+    with open(on_path, encoding="utf-8") as f:
+        on_data = json.load(f)
+    svg = render(off_data, on_data, db_path)
+    with open(out_path, "w", encoding="utf-8") as f:
+        f.write(svg)
+    print(f"wrote {out_path}")

maskflow_agent-0.1.0/examples/demo/replay.py

@@ -0,0 +1,75 @@
+"""Replay a captured session in the terminal, for recording the demo video.
+
+    python replay.py session-with-guard.json kyc.db --title "Claude Code + maskflow-agent"
+
+Prints exactly the lines render_svg.py draws (same capture, same rules:
+real values red, placeholders green), with typing pauses. It replays a real
+transcript; it does not call Claude.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import textwrap
+import time
+
+from render_svg import CHARS, _db_values, _leaked, _panel_lines, _row, _spans
+
+ANSI = {
+    "#ff7b72": "\033[1;31m",  # real value
+    "#3fb950": "\033[1;32m",  # placeholder / success
+    "#79c0ff": "\033[34m",  # command
+    "#8b949e": "\033[2m",  # dim
+}
+RESET = "\033[0m"
+
+
+def _paint(text: str, base: str, raw: dict[str, str]) -> str:
+    out = []
+    for run, colour in _spans(text, raw):
+        out.append(f"{ANSI.get(colour or base, '')}{run}{RESET}")
+    return "".join(out)
+
+
+def _type(text: str, delay: float) -> None:
+    for ch in text:
+        sys.stdout.write(ch)
+        sys.stdout.flush()
+        time.sleep(delay)
+    sys.stdout.write("\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("session")
+    parser.add_argument("db")
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--speed", type=float, default=1.0)
+    args = parser.parse_args()
+    with open(args.session, encoding="utf-8") as f:
+        data = json.load(f)
+    raw = _db_values(args.db)
+    lines = _panel_lines(data, raw, _row(args.db, 4))
+
+    print(f"\033[1m{args.title}\033[0m\n")
+    pause = 0.5 / args.speed
+    prompt_lines = len(textwrap.wrap(data["prompt"], CHARS - 2))
+    for i, (text, base) in enumerate(lines):
+        if i < prompt_lines:  # the user's prompt is typed, everything else appears
+            _type(text, 0.012 / args.speed)
+        else:
+            print(_paint(text, base, raw))
+        time.sleep(pause if text else pause / 2)
+    leaked = _leaked(data, raw)
+    time.sleep(pause)
+    if leaked:
+        print(f"\033[1;31mSent to the model: {', '.join(leaked)}{RESET}")
+    else:
+        print(f"\033[1;32mSent to the model: no personal data. Row updated.{RESET}")
+    time.sleep(4 / args.speed)
+
+
+if __name__ == "__main__":
+    main()

maskflow_agent-0.1.0/examples/demo/session-with-guard.json

@@ -0,0 +1,14 @@
+{
+  "prompt": "Support ticket: KYC for customer 4 is stuck. Look the customer up in kyc.db (use sqlite3 -header; table kyc), then set their status to verified, matching on their PAN. Show me the row afterwards.",
+  "steps": [
+    {
+      "command": "sqlite3 -header kyc.db \".schema kyc\" \"SELECT * FROM kyc WHERE rowid=4 OR customer_id=4;\" 2>&1 || sqlite3 -header kyc.db \"SELECT * FROM kyc LIMIT 10;\"",
+      "result": "Error: in prepare, no such column: customer_id\n  SELECT * FROM kyc WHERE rowid=4 OR <PERSON_NAME_1>;\n                       error here ---^\nCREATE TABLE kyc (id INTEGER PRIMARY KEY, name TEXT, aadhaar TEXT, pan TEXT, mobile TEXT, upi TEXT, status TEXT);\nid|name|aadhaar|pan|mobile|upi|status\n1|<PERSON_NAME_2>|<AADHAAR_1>|<PAN_1>|<INDIAN_MOBILE_1>|<UPI_VPA_1>|pending\n2|<PERSON_NAME_3>|<AADHAAR_2>|<PAN_2>|<INDIAN_MOBILE_2>|<UPI_VPA_2>|pending\n3|<PERSON_NAME_4>|<AADHAAR_3>|<PAN_3>|<INDIAN_MOBILE_3>|<UPI_VPA_3>|verified\n4|<PERSON_NAME_5>|<AADHAAR_4>|<PAN_4>|<INDIAN_MOBILE_4>|<UPI_VPA_4>|stuck\n5|<PERSON_NAME_6>|<AADHAAR_5>|<PAN_5>|<INDIAN_MOBILE_5>|<UPI_VPA_5>|pending\n6|<PERSON_NAME_7>|<AADHAAR_6>|<PAN_6>|<INDIAN_MOBILE_6>|<UPI_VPA_6>|verified"
+    },
+    {
+      "command": "sqlite3 -header kyc.db \"UPDATE kyc SET status='verified' WHERE pan='<PAN_4>'; SELECT changes(); SELECT * FROM kyc WHERE pan='<PAN_4>';\"",
+      "result": "changes()\n1\nid|name|aadhaar|pan|mobile|upi|status\n4|<PERSON_NAME_5>|<AADHAAR_4>|<PAN_4>|<INDIAN_MOBILE_4>|<UPI_VPA_4>|verified"
+    }
+  ],
+  "final": "Customer 4's KYC status is now `verified`, changed from `stuck`. The update matched on their PAN and changed exactly one row.\n\nThe row afterwards (personal data shows as placeholders in this session):\n\n```\nid|name           |aadhaar     |pan     |mobile           |upi         |status\n4 |<PERSON_NAME_5>|<AADHAAR_4>|<PAN_4>|<INDIAN_MOBILE_4>|<UPI_VPA_4>|verified\n```\n\nI only changed the status. I didn't check the PAN or other details against any source, so confirm the documents were reviewed before you close the ticket."
+}

maskflow_agent-0.1.0/examples/demo/session-without-guard.json

@@ -0,0 +1,14 @@
+{
+  "prompt": "Support ticket: KYC for customer 4 is stuck. Look the customer up in kyc.db (use sqlite3 -header; table kyc), then set their status to verified, matching on their PAN. Show me the row afterwards.",
+  "steps": [
+    {
+      "command": "sqlite3 -header kyc.db \"select * from kyc where id=4;\"",
+      "result": "id|name|aadhaar|pan|mobile|upi|status\n4|Arjun Reddy|711577498934|YRBPR0593D|8959853741|arjun99@oksbi|stuck"
+    },
+    {
+      "command": "sqlite3 -header kyc.db \"update kyc set status='verified' where pan='YRBPR0593D'; select * from kyc where pan='YRBPR0593D';\"",
+      "result": "id|name|aadhaar|pan|mobile|upi|status\n4|Arjun Reddy|711577498934|YRBPR0593D|8959853741|arjun99@oksbi|verified"
+    }
+  ],
+  "final": "Customer 4 (Arjun Reddy) was `stuck`. I set their status to `verified`, matching on their PAN `YRBPR0593D`. The row now reads:\n\n```\nid|name|aadhaar|pan|mobile|upi|status\n4|Arjun Reddy|711577498934|YRBPR0593D|8959853741|arjun99@oksbi|verified\n```\n\nI checked only that row after the update, not the rest of the table. The PAN is the only match I used, so I can't say whether any other row shares it."
+}

maskflow_agent-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "maskflow-agent"
+version = "0.1.0"
+description = "MaskFlow guard for AI coding agents: Claude Code hooks that mask PII (Aadhaar, PAN, UPI, mobile, ...) in tool output before the model sees it, and restore values only inside allowlisted commands at run time."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    # Session: stable value -> placeholder identity for a whole agent run,
+    # placeholder look-alike reservation, snapshot-free in-memory mapping.
+    # Only the daemon imports it -- the hook client is stdlib-only.
+    "maskflow-sdk>=0.9.2,<0.10",
+]
+
+[project.scripts]
+maskflow-agent = "maskflow_agent.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.uv.sources]
+maskflow-sdk = { workspace = true }
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maskflow_agent"]
+
+[tool.pytest.ini_options]
+markers = [
+    "leak: guards against PII reaching the model, hook stdout, logs, or disk",
+    "e2e: drives a real `claude -p` session (opt-in: MASKFLOW_AGENT_E2E=1)",
+]