ghostmode 0.1.0__py3-none-any.whl

ghostmode/__init__.py

@@ -0,0 +1,6 @@
+"""Ghost Mode — dry-run proxy for AI agents.
+
+See what your agent would do, before it does anything.
+"""
+
+__version__ = "0.1.0"

ghostmode/cli.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+"""Ghost Mode CLI — one command, zero config.
+
+Usage:
+    ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents
+    ghostmode -v -- python my_mcp_server.py
+    ghostmode --export session.json -- node my_tools.js
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="ghostmode",
+        description=(
+            "\U0001f47b Ghost Mode — see what your AI agent would do, "
+            "without letting it do anything."
+        ),
+        epilog=(
+            "Example:\n"
+            "  ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents\n"
+            "\n"
+            "Point your agent at ghostmode instead of the MCP server.\n"
+            "Reads pass through. Writes get intercepted. Nothing changes.\n"
+            "\n"
+            "For full security (rollback, enforcement, audit chain), upgrade to UNWIND:\n"
+            "  pip install unwind-mcp\n"
+            "  https://github.com/unwind-mcp/unwind"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "upstream_command",
+        nargs=argparse.REMAINDER,
+        help="The MCP server command (after --)",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Log every intercepted and passed action to stderr",
+    )
+    parser.add_argument(
+        "--export",
+        metavar="FILE",
+        help="Export the session log to a JSON file on exit",
+    )
+    parser.add_argument(
+        "--also-block",
+        metavar="TOOL",
+        action="append",
+        default=[],
+        help="Additional tool names to treat as writes (can be repeated)",
+    )
+
+    args = parser.parse_args()
+
+    # Parse upstream command
+    upstream_cmd = args.upstream_command
+    if upstream_cmd and upstream_cmd[0] == "--":
+        upstream_cmd = upstream_cmd[1:]
+
+    if not upstream_cmd:
+        print(
+            "\n  \U0001f47b Ghost Mode — dry-run proxy for AI agents\n"
+            "\n"
+            "  Usage:\n"
+            "    ghostmode -- <upstream MCP server command>\n"
+            "\n"
+            "  Examples:\n"
+            "    ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents\n"
+            "    ghostmode -- python my_mcp_server.py\n"
+            "    ghostmode -v -- node tools_server.js\n"
+            "\n"
+            "  The agent talks to ghostmode. Reads pass through to your\n"
+            "  real MCP server. Writes get intercepted. Nothing changes.\n"
+            "\n"
+            "  When the session ends, you see everything the agent tried to do.\n",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Custom write tools
+    custom_writes = frozenset(args.also_block) if args.also_block else None
+
+    # Logging
+    level = logging.DEBUG if args.verbose else logging.WARNING
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter(
+        "%(asctime)s [ghostmode] %(message)s", datefmt="%H:%M:%S",
+    ))
+    logging.root.addHandler(handler)
+    logging.root.setLevel(level)
+
+    # Banner
+    print(
+        "\n  \U0001f47b Ghost Mode active\n"
+        f"  Upstream: {' '.join(upstream_cmd)}\n"
+        f"  Writes will be intercepted. Reads pass through.\n",
+        file=sys.stderr,
+    )
+
+    from .proxy import run_ghost_proxy
+
+    # Run with export on exit
+    async def _run():
+        from .proxy import GhostProxy
+        proxy = GhostProxy(upstream_cmd, custom_writes, args.verbose)
+        try:
+            await proxy.run()
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            pass
+        finally:
+            await proxy.shutdown()
+
+            # Export if requested
+            if args.export:
+                from pathlib import Path
+                count = proxy.log.export_json(Path(args.export))
+                print(f"\n  Exported {count} events to {args.export}", file=sys.stderr)
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

ghostmode/event_log.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+"""Ghost Mode event log — lightweight action recorder.
+
+A minimal event log that records what the agent tried to do.
+No SQLite, no hash chains — just an in-memory list with optional
+file export. This is the "See Everything" without the security
+infrastructure.
+
+For the full flight recorder with CR-AFT hash chains, tamper
+detection, and rollback, upgrade to UNWIND.
+"""
+
+import json
+import time
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class GhostEvent:
+    """A single intercepted action."""
+    timestamp: float
+    tool: str
+    action: str          # "intercepted", "passed_through", "shadow_read"
+    target: Optional[str] = None
+    parameters_summary: Optional[str] = None  # Brief summary, not full params
+    detail: Optional[str] = None
+
+
+class GhostEventLog:
+    """In-memory event log for Ghost Mode sessions."""
+
+    def __init__(self):
+        self.events: list[GhostEvent] = []
+        self._start_time: float = time.time()
+
+    def log_intercept(self, tool: str, target: Optional[str] = None,
+                      detail: Optional[str] = None) -> GhostEvent:
+        """Log an intercepted (blocked) write action."""
+        event = GhostEvent(
+            timestamp=time.time(),
+            tool=tool,
+            action="intercepted",
+            target=target,
+            detail=detail,
+        )
+        self.events.append(event)
+        return event
+
+    def log_passthrough(self, tool: str, target: Optional[str] = None) -> GhostEvent:
+        """Log a read-only action that was passed through."""
+        event = GhostEvent(
+            timestamp=time.time(),
+            tool=tool,
+            action="passed_through",
+            target=target,
+        )
+        self.events.append(event)
+        return event
+
+    def log_shadow_read(self, tool: str, target: str) -> GhostEvent:
+        """Log a read served from the shadow VFS."""
+        event = GhostEvent(
+            timestamp=time.time(),
+            tool=tool,
+            action="shadow_read",
+            target=target,
+            detail="Content served from shadow VFS (ghost-written earlier)",
+        )
+        self.events.append(event)
+        return event
+
+    @property
+    def intercepted_count(self) -> int:
+        return sum(1 for e in self.events if e.action == "intercepted")
+
+    @property
+    def passthrough_count(self) -> int:
+        return sum(1 for e in self.events if e.action == "passed_through")
+
+    @property
+    def shadow_read_count(self) -> int:
+        return sum(1 for e in self.events if e.action == "shadow_read")
+
+    @property
+    def duration_seconds(self) -> float:
+        return time.time() - self._start_time
+
+    def summary(self) -> dict:
+        """Return a session summary."""
+        return {
+            "duration_seconds": round(self.duration_seconds, 1),
+            "total_events": len(self.events),
+            "intercepted": self.intercepted_count,
+            "passed_through": self.passthrough_count,
+            "shadow_reads": self.shadow_read_count,
+        }
+
+    def format_timeline(self) -> str:
+        """Format events as a human-readable timeline."""
+        if not self.events:
+            return "  No events recorded."
+
+        lines = []
+        for event in self.events:
+            ts = time.strftime("%H:%M:%S", time.localtime(event.timestamp))
+            target_str = f" → {event.target}" if event.target else ""
+
+            if event.action == "intercepted":
+                icon = "\U0001f6ab"  # no entry
+                label = "BLOCKED"
+            elif event.action == "shadow_read":
+                icon = "\U0001f47b"  # ghost
+                label = "SHADOW"
+            else:
+                icon = "\u2705"  # check
+                label = "PASSED"
+
+            lines.append(f"  {icon} {ts}  [{label}]  {event.tool}{target_str}")
+
+            if event.detail:
+                lines.append(f"{'':>14}\u2514\u2500 {event.detail}")
+
+        return "\n".join(lines)
+
+    def export_json(self, path: Path) -> int:
+        """Export the event log to a JSON file."""
+        data = {
+            "ghostmode_version": "0.1.0",
+            "session_summary": self.summary(),
+            "events": [asdict(e) for e in self.events],
+        }
+        path.write_text(json.dumps(data, indent=2))
+        return len(self.events)
+
+    def export_jsonl(self, path: Path) -> int:
+        """Export events as newline-delimited JSON."""
+        with open(path, "w") as f:
+            for event in self.events:
+                f.write(json.dumps(asdict(event)) + "\n")
+        return len(self.events)

ghostmode/proxy.py

@@ -0,0 +1,482 @@
+from __future__ import annotations
+
+"""Ghost Mode proxy — the write-blocking MCP middleware.
+
+This is the entire Ghost Mode product in one class. It:
+1. Intercepts all tool calls from the agent
+2. Lets read-only calls through to upstream unchanged
+3. Blocks state-modifying calls and returns fake success
+4. Maintains a shadow VFS so reads after ghost-writes stay consistent
+5. Logs everything the agent tried to do
+
+No enforcement pipeline, no rollback engine, no hash chains.
+Just: "see what it would do, without letting it do anything."
+
+For the full security suite, upgrade to UNWIND.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import time
+from typing import Any, Optional
+
+from .shadow_vfs import ShadowVFS
+from .event_log import GhostEventLog
+
+logger = logging.getLogger("ghostmode")
+
+
+# ── Tool Classification ──────────────────────────────────────────
+
+# These tools modify state and will be intercepted
+DEFAULT_WRITE_TOOLS = frozenset({
+    # Filesystem
+    "fs_write", "fs_delete", "fs_rename", "fs_mkdir", "fs_move", "fs_copy",
+    "write_file", "delete_file", "rename_file", "move_file", "create_directory",
+    # Communication
+    "send_email", "post_message", "send_message", "reply_email",
+    # Network writes
+    "http_post", "http_put", "http_delete", "http_patch",
+    "upload_file", "api_call", "webhook",
+    # System
+    "bash_exec", "shell_exec", "run_command", "execute_command",
+    "install_package", "pip_install", "npm_install",
+    # Calendar / Scheduling
+    "create_calendar_event", "modify_calendar_event", "delete_calendar_event",
+    "create_event", "update_event", "delete_event",
+    # Database
+    "db_insert", "db_update", "db_delete", "db_execute",
+    "sql_execute", "query_execute",
+    # Git
+    "git_commit", "git_push", "git_checkout", "git_merge",
+    # Edit operations
+    "edit_file", "patch_file", "replace_in_file",
+})
+
+# Tools that look like writes based on naming patterns
+WRITE_PREFIXES = ("create_", "delete_", "remove_", "update_", "modify_",
+                  "send_", "post_", "put_", "write_", "set_", "insert_",
+                  "drop_", "execute_", "run_", "install_", "push_", "edit_",
+                  "patch_", "replace_", "rename_", "move_", "copy_")
+
+
+def is_write_tool(tool_name: str, custom_writes: Optional[frozenset] = None) -> bool:
+    """Determine if a tool modifies state.
+
+    Uses explicit list + prefix heuristic. Errs on the side of blocking:
+    if a tool looks like it might write, it gets intercepted.
+    """
+    if custom_writes and tool_name in custom_writes:
+        return True
+    if tool_name in DEFAULT_WRITE_TOOLS:
+        return True
+    # Prefix heuristic — catches tools we haven't explicitly listed
+    return any(tool_name.startswith(prefix) for prefix in WRITE_PREFIXES)
+
+
+# ── JSON-RPC Helpers ──────────────────────────────────────────────
+
+def _make_response(id: Any, result: Any) -> dict:
+    return {"jsonrpc": "2.0", "id": id, "result": result}
+
+
+def _make_error(id: Any, code: int, message: str) -> dict:
+    return {"jsonrpc": "2.0", "id": id, "error": {"code": code, "message": message}}
+
+
+# ── Transport ─────────────────────────────────────────────────────
+
+class StdioReader:
+    """Read newline-delimited JSON from an asyncio StreamReader."""
+
+    def __init__(self, reader: asyncio.StreamReader):
+        self.reader = reader
+
+    async def read(self) -> Optional[dict]:
+        while True:
+            try:
+                line = await self.reader.readline()
+            except (asyncio.CancelledError, ConnectionError):
+                return None
+            if not line:
+                return None
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                return json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+
+class StdioWriter:
+    """Write newline-delimited JSON to an asyncio StreamWriter."""
+
+    def __init__(self, writer: asyncio.StreamWriter):
+        self.writer = writer
+        self._closed = False
+
+    async def write(self, msg: dict) -> None:
+        if self._closed:
+            return
+        try:
+            self.writer.write((json.dumps(msg, separators=(",", ":")) + "\n").encode())
+            await self.writer.drain()
+        except (ConnectionError, BrokenPipeError, asyncio.CancelledError):
+            self._closed = True
+
+    async def close(self) -> None:
+        self._closed = True
+        try:
+            self.writer.close()
+            await self.writer.wait_closed()
+        except Exception:
+            pass
+
+
+# ── Ghost Mode Proxy ──────────────────────────────────────────────
+
+class GhostProxy:
+    """The Ghost Mode MCP proxy.
+
+    Sits between agent (stdin/stdout) and upstream (subprocess).
+    Reads pass through. Writes get intercepted. Shadow VFS keeps
+    the agent consistent.
+    """
+
+    def __init__(
+        self,
+        upstream_command: list[str],
+        custom_write_tools: Optional[frozenset] = None,
+        verbose: bool = False,
+    ):
+        self.upstream_command = upstream_command
+        self.custom_write_tools = custom_write_tools
+        self.verbose = verbose
+
+        self.shadow = ShadowVFS()
+        self.log = GhostEventLog()
+
+        self._process: Optional[asyncio.subprocess.Process] = None
+        self._agent_reader: Optional[StdioReader] = None
+        self._agent_writer: Optional[StdioWriter] = None
+        self._upstream_reader: Optional[StdioReader] = None
+        self._upstream_writer: Optional[StdioWriter] = None
+
+        self._pending: dict[int, Any] = {}
+        self._upstream_id: int = 0
+        self._shutdown = False
+        self._summary_printed = False
+
+    def _next_id(self) -> int:
+        self._upstream_id += 1
+        return self._upstream_id
+
+    def _is_write(self, tool_name: str) -> bool:
+        return is_write_tool(tool_name, self.custom_write_tools)
+
+    # ── Lifecycle ──
+
+    async def start(self) -> None:
+        """Start upstream and set up agent transport."""
+        # Agent stdio
+        loop = asyncio.get_event_loop()
+        reader = asyncio.StreamReader()
+        protocol = asyncio.StreamReaderProtocol(reader)
+        await loop.connect_read_pipe(lambda: protocol, sys.stdin)
+        w_transport, w_protocol = await loop.connect_write_pipe(
+            asyncio.streams.FlowControlMixin, sys.stdout
+        )
+        writer = asyncio.StreamWriter(w_transport, w_protocol, reader, loop)
+        self._agent_reader = StdioReader(reader)
+        self._agent_writer = StdioWriter(writer)
+
+        # Upstream subprocess
+        self._process = await asyncio.create_subprocess_exec(
+            *self.upstream_command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        self._upstream_reader = StdioReader(self._process.stdout)
+        self._upstream_writer = StdioWriter(self._process.stdin)
+
+        logger.info("Ghost Mode proxy started (upstream PID %d)", self._process.pid)
+
+    async def run(self) -> None:
+        """Main loop — run until agent disconnects."""
+        await self.start()
+        try:
+            await asyncio.gather(
+                self._agent_loop(),
+                self._upstream_loop(),
+            )
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await self.shutdown()
+
+    async def shutdown(self) -> None:
+        if self._shutdown:
+            # Already shutting down, but still print summary if not yet printed
+            if not self._summary_printed:
+                self._print_summary()
+            return
+        self._shutdown = True
+
+        # Print session summary to stderr
+        self._print_summary()
+
+        if self._process and self._process.returncode is None:
+            self._process.terminate()
+            try:
+                await asyncio.wait_for(self._process.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                self._process.kill()
+
+        if self._agent_writer:
+            await self._agent_writer.close()
+
+        logger.info("Ghost Mode proxy shut down")
+
+    def _print_summary(self) -> None:
+        """Print session summary to stderr on shutdown."""
+        self._summary_printed = True
+        summary = self.log.summary()
+        shadow = self.shadow.summary()
+
+        print("\n" + "=" * 55, file=sys.stderr)
+        print("  \U0001f47b GHOST MODE SESSION SUMMARY", file=sys.stderr)
+        print("=" * 55, file=sys.stderr)
+        print(f"  Duration:     {summary['duration_seconds']}s", file=sys.stderr)
+        print(f"  Total events: {summary['total_events']}", file=sys.stderr)
+        print(f"  Intercepted:  {summary['intercepted']} writes blocked", file=sys.stderr)
+        print(f"  Passed:       {summary['passed_through']} reads forwarded", file=sys.stderr)
+        print(f"  Shadow reads: {summary['shadow_reads']} served from VFS", file=sys.stderr)
+
+        if shadow["write_count"] > 0:
+            print(f"\n  Files the agent tried to write:", file=sys.stderr)
+            for f in shadow["files_written"]:
+                print(f"    \U0001f4dd {f}", file=sys.stderr)
+
+        if shadow["delete_count"] > 0:
+            print(f"\n  Files the agent tried to delete:", file=sys.stderr)
+            for f in shadow["files_deleted"]:
+                print(f"    \U0001f5d1\ufe0f  {f}", file=sys.stderr)
+
+        if summary["intercepted"] == 0:
+            print("\n  \u2705 Agent performed no write operations.", file=sys.stderr)
+        else:
+            print(
+                f"\n  \U0001f6ab {summary['intercepted']} write(s) were blocked. "
+                f"Nothing was modified.",
+                file=sys.stderr,
+            )
+
+        print("\n  Full timeline:", file=sys.stderr)
+        print(self.log.format_timeline(), file=sys.stderr)
+        print("\n  Full security suite: https://github.com/unwind-mcp/unwind", file=sys.stderr)
+        print("=" * 55 + "\n", file=sys.stderr)
+
+        # Auto-write summary to file for clients that hide stderr
+        try:
+            from pathlib import Path
+            summary_path = Path("ghostmode-summary.txt")
+            lines = []
+            lines.append("GHOST MODE SESSION SUMMARY")
+            lines.append(f"Duration:     {summary['duration_seconds']}s")
+            lines.append(f"Total events: {summary['total_events']}")
+            lines.append(f"Intercepted:  {summary['intercepted']} writes blocked")
+            lines.append(f"Passed:       {summary['passed_through']} reads forwarded")
+            lines.append(f"Shadow reads: {summary['shadow_reads']} served from VFS")
+            if shadow["write_count"] > 0:
+                lines.append(f"\nFiles the agent tried to write:")
+                for f in shadow["files_written"]:
+                    lines.append(f"  {f}")
+            if shadow["delete_count"] > 0:
+                lines.append(f"\nFiles the agent tried to delete:")
+                for f in shadow["files_deleted"]:
+                    lines.append(f"  {f}")
+            if summary["intercepted"] == 0:
+                lines.append("\nAgent performed no write operations.")
+            else:
+                lines.append(f"\n{summary['intercepted']} write(s) were blocked. Nothing was modified.")
+            lines.append("\nFull timeline:")
+            lines.append(self.log.format_timeline())
+            summary_path.write_text("\n".join(lines) + "\n")
+            print(f"  Summary written to {summary_path.resolve()}", file=sys.stderr)
+        except Exception:
+            pass  # Best-effort — don't fail shutdown over summary file
+
+    # ── Agent → Proxy ──
+
+    async def _agent_loop(self) -> None:
+        while not self._shutdown:
+            msg = await self._agent_reader.read()
+            if msg is None:
+                self._shutdown = True
+                return
+
+            method = msg.get("method")
+            msg_id = msg.get("id")
+
+            try:
+                if method == "tools/call":
+                    await self._handle_tool_call(msg)
+                else:
+                    await self._forward_to_upstream(msg)
+            except Exception as e:
+                logger.error("Error handling agent message: %s", e, exc_info=True)
+                if msg_id is not None:
+                    await self._agent_writer.write(
+                        _make_error(msg_id, -32603, f"Ghost proxy error: {e}")
+                    )
+
+    async def _handle_tool_call(self, msg: dict) -> None:
+        """The ghost gate — intercept writes, pass reads."""
+        params = msg.get("params", {})
+        tool_name = params.get("name", "")
+        arguments = params.get("arguments", {})
+        msg_id = msg.get("id")
+
+        # Extract target path/URL for logging
+        target = None
+        for key in ("path", "file", "target", "filename", "url", "uri",
+                     "source", "old_path"):
+            if key in arguments:
+                target = str(arguments[key])
+                break
+
+        # Extract content for shadow VFS
+        content = None
+        for key in ("content", "body", "text", "data"):
+            if key in arguments:
+                content = arguments[key]
+                break
+
+        # ── Is this a write? ──
+        if self._is_write(tool_name):
+            # Intercept it
+            self.log.log_intercept(
+                tool=tool_name,
+                target=target,
+                detail=f"Would have executed {tool_name}" + (f" on {target}" if target else ""),
+            )
+
+            # Shadow VFS: record the write for read consistency
+            if target and content is not None:
+                self.shadow.write(target, content if isinstance(content, str) else str(content))
+            elif tool_name in ("fs_delete", "delete_file", "remove_file") and target:
+                self.shadow.delete(target)
+            elif tool_name in ("fs_rename", "rename_file", "move_file", "fs_move"):
+                old = arguments.get("path", arguments.get("source", arguments.get("old_path", "")))
+                new = arguments.get("new_path", arguments.get("destination", arguments.get("target", "")))
+                if old and new:
+                    self.shadow.rename(str(old), str(new))
+
+            if self.verbose:
+                logger.info("\U0001f6ab INTERCEPTED: %s%s", tool_name,
+                           f" → {target}" if target else "")
+
+            # Return fake success to the agent
+            await self._agent_writer.write(_make_response(msg_id, {
+                "content": [{
+                    "type": "text",
+                    "text": f"[Ghost Mode] {tool_name} completed successfully."
+                }],
+            }))
+            return
+
+        # ── Is this a read of something we ghost-wrote? ──
+        if target and self.shadow.has(target):
+            shadow_content = self.shadow.read(target)
+            self.log.log_shadow_read(tool=tool_name, target=target)
+
+            if self.verbose:
+                logger.info("\U0001f47b SHADOW READ: %s → %s", tool_name, target)
+
+            await self._agent_writer.write(_make_response(msg_id, {
+                "content": [{
+                    "type": "text",
+                    "text": str(shadow_content) if shadow_content else "",
+                }],
+            }))
+            return
+
+        # ── Read-only — pass through to upstream ──
+        self.log.log_passthrough(tool=tool_name, target=target)
+
+        if self.verbose:
+            logger.info("\u2705 PASSTHROUGH: %s%s", tool_name,
+                       f" → {target}" if target else "")
+
+        uid = self._next_id()
+        self._pending[uid] = msg_id
+        await self._upstream_writer.write({
+            "jsonrpc": "2.0",
+            "id": uid,
+            "method": "tools/call",
+            "params": params,
+        })
+
+    async def _forward_to_upstream(self, msg: dict) -> None:
+        """Forward non-tool-call messages transparently."""
+        msg_id = msg.get("id")
+        method = msg.get("method")
+
+        if msg_id is not None:  # Request
+            uid = self._next_id()
+            self._pending[uid] = msg_id
+            await self._upstream_writer.write({
+                "jsonrpc": "2.0",
+                "id": uid,
+                "method": method,
+                "params": msg.get("params", {}),
+            })
+        else:  # Notification
+            await self._upstream_writer.write(msg)
+
+    # ── Upstream → Proxy ──
+
+    async def _upstream_loop(self) -> None:
+        while not self._shutdown:
+            msg = await self._upstream_reader.read()
+            if msg is None:
+                self._shutdown = True
+                return
+
+            try:
+                await self._handle_upstream_message(msg)
+            except Exception as e:
+                logger.error("Error handling upstream message: %s", e, exc_info=True)
+
+    async def _handle_upstream_message(self, msg: dict) -> None:
+        msg_id = msg.get("id")
+        method = msg.get("method")
+
+        # Notification — pass through
+        if method is not None and msg_id is None:
+            await self._agent_writer.write(msg)
+            return
+
+        # Response — remap ID and forward
+        if msg_id is not None and msg_id in self._pending:
+            agent_id = self._pending.pop(msg_id)
+            response = {"jsonrpc": "2.0", "id": agent_id}
+            if "result" in msg:
+                response["result"] = msg["result"]
+            if "error" in msg:
+                response["error"] = msg["error"]
+            await self._agent_writer.write(response)
+
+
+async def run_ghost_proxy(
+    upstream_command: list[str],
+    custom_write_tools: Optional[frozenset] = None,
+    verbose: bool = False,
+) -> None:
+    """Entry point — run Ghost Mode proxy."""
+    proxy = GhostProxy(upstream_command, custom_write_tools, verbose)
+    await proxy.run()

ghostmode/shadow_vfs.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+"""Shadow VFS — in-memory filesystem overlay for Ghost Mode.
+
+When Ghost Mode intercepts a write, the content goes here.
+When a subsequent read targets the same path, the shadow returns
+the "written" content so the agent stays consistent.
+
+The agent thinks it wrote a file and can read it back.
+In reality, nothing touched disk.
+"""
+
+from typing import Optional
+
+
+class ShadowVFS:
+    """In-memory virtual filesystem overlay.
+
+    Tracks writes that were intercepted and serves them back on reads,
+    maintaining agent consistency without touching the real filesystem.
+    """
+
+    def __init__(self):
+        self._store: dict[str, str | bytes] = {}
+        self._deleted: set[str] = set()
+
+    def write(self, path: str, content: str | bytes) -> None:
+        """Record a ghost write."""
+        self._store[path] = content
+        self._deleted.discard(path)
+
+    def read(self, path: str) -> Optional[str | bytes]:
+        """Read from shadow. Returns None if path not in shadow."""
+        if path in self._deleted:
+            return ""  # File was "deleted" in ghost mode
+        return self._store.get(path)
+
+    def delete(self, path: str) -> None:
+        """Record a ghost delete."""
+        self._store.pop(path, None)
+        self._deleted.add(path)
+
+    def rename(self, old_path: str, new_path: str) -> None:
+        """Record a ghost rename."""
+        content = self._store.pop(old_path, None)
+        if content is not None:
+            self._store[new_path] = content
+        self._deleted.add(old_path)
+        self._deleted.discard(new_path)
+
+    def has(self, path: str) -> bool:
+        """Check if a path has been touched in ghost mode."""
+        return path in self._store or path in self._deleted
+
+    @property
+    def write_count(self) -> int:
+        return len(self._store)
+
+    @property
+    def delete_count(self) -> int:
+        return len(self._deleted)
+
+    def clear(self) -> None:
+        """Reset the shadow filesystem."""
+        self._store.clear()
+        self._deleted.clear()
+
+    def summary(self) -> dict:
+        """Return a summary of ghost activity."""
+        return {
+            "files_written": list(self._store.keys()),
+            "files_deleted": list(self._deleted),
+            "write_count": self.write_count,
+            "delete_count": self.delete_count,
+        }

ghostmode-0.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: ghostmode
+Version: 0.1.0
+Summary: See what your AI agent would do, without letting it do anything. Zero-config dry-run proxy for MCP servers.
+Author: David Russell
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/unwind-mcp/ghostmode
+Project-URL: Repository, https://github.com/unwind-mcp/ghostmode
+Project-URL: Full Security Suite, https://github.com/unwind-mcp/unwind
+Keywords: mcp,ai-agents,ghost-mode,dry-run,proxy,safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# Ghost Mode
+
+**See what your AI agent would do, without letting it do anything.**
+
+Ghost Mode is a safe first step before giving an AI agent real authority.
+
+It's a zero-config dry-run layer for AI agents. It intercepts every write and lets reads through. Think of it as a flight simulator for AI agents — nothing gets modified, but you see everything the agent tried to do.
+
+Requires Python 3.9+.
+
+## Quick Start
+
+### MCP Client Users (Claude Desktop, Cursor, etc.)
+
+```bash
+pip install ghostmode
+ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents
+```
+
+Point your agent at Ghost Mode instead of the real server. When the session ends, a summary is written to `ghostmode-summary.txt` in your working directory and printed to stderr.
+
+### OpenClaw Users
+
+```bash
+# 1. Install Ghost Mode
+pip install ghostmode
+
+# 2. Install the OpenClaw plugin
+openclaw plugins install @unwind/ghostmode-openclaw
+
+# 3. Restart the gateway
+```
+
+Ghost Mode hooks into OpenClaw's tool-call system. Every write is intercepted. Every read passes through.
+
+## What it does
+
+Ghost Mode intercepts state-modifying tool calls — file writes, deletions, emails, API posts, shell commands — and returns fake success responses. The agent thinks it completed the action. Your filesystem, email, and APIs are untouched.
+
+A shadow virtual filesystem keeps the agent consistent: if it "writes" a file and then reads it back, Ghost Mode serves the written content from memory. The agent doesn't know it's in a sandbox.
+
+## Example output
+
+```
+=======================================================
+  GHOST MODE SESSION SUMMARY
+=======================================================
+  Duration:     47.3s
+  Total events: 12
+  Intercepted:  4 writes blocked
+  Passed:       7 reads forwarded
+  Shadow reads: 1 served from VFS
+
+  Files the agent tried to write:
+    /home/user/Documents/report.md
+    /home/user/Documents/summary.txt
+
+  Files the agent tried to delete:
+    /home/user/Documents/old_draft.md
+
+  4 write(s) were blocked. Nothing was modified.
+
+  Full timeline:
+  14:23:01  [PASSED]  fs_read  /home/user/Documents/notes.txt
+  14:23:02  [PASSED]  fs_list  /home/user/Documents
+  14:23:03  [BLOCKED] fs_write /home/user/Documents/report.md
+  14:23:04  [SHADOW]  fs_read  /home/user/Documents/report.md
+  14:23:05  [BLOCKED] fs_delete /home/user/Documents/old_draft.md
+  14:23:06  [BLOCKED] send_email
+  14:23:07  [PASSED]  fs_read  /home/user/Documents/config.json
+=======================================================
+```
+
+## Use cases
+
+**Testing untrusted tools.** Install a new MCP server and see what it actually does before giving it real access.
+
+**Reviewing agent behaviour.** Let your agent plan and "execute" a complex task, then review the timeline before running it for real.
+
+**Demos and training.** Show stakeholders what an AI agent workflow looks like without risking real data.
+
+**Compliance dry runs.** Verify that an agent workflow stays within policy boundaries before going live.
+
+## What Ghost Mode is not
+
+Ghost Mode does not enforce policy or provide rollback. It is a visibility tool, not a security system. If you need enforcement, audit trails, or recovery, that's what [UNWIND](https://github.com/unwind-mcp/unwind) is for.
+
+## CLI options (MCP proxy mode)
+
+```
+ghostmode -- <upstream command>        Basic usage
+ghostmode -v -- <command>              Verbose: log every action to stderr
+ghostmode --export log.json -- <cmd>   Export session log on exit
+ghostmode --also-block my_tool -- ...  Add custom tool names to intercept
+```
+
+## How it knows what to block
+
+Ghost Mode recognises 50+ common MCP tool names as state-modifying (filesystem writes, email sends, API posts, shell commands, database mutations, git operations). It also uses prefix heuristics: any tool starting with `create_`, `delete_`, `send_`, `write_`, `execute_`, etc. gets intercepted. The block list is heuristic-based and configurable.
+
+If a tool slips through, use `--also-block tool_name` to add it.
+
+## Zero dependencies
+
+Ghost Mode has no external dependencies. It uses only Python 3.9+ stdlib (asyncio, json, pathlib). It installs in under a second.
+
+## Known limitations
+
+**Shell commands can't see ghost-written files.** If the agent writes a file through Ghost Mode and then tries to run it via `bash_exec` or `shell_exec`, the shell will fail because the file only exists in the in-memory shadow VFS, not on disk. Ghost Mode works best for tool-call-level dry runs, not multi-step build/execute workflows.
+
+**Session summary in background clients.** Claude Desktop and Cursor run MCP servers in the background and may not surface stderr output. Ghost Mode automatically writes a `ghostmode-summary.txt` file to your working directory on exit. You can also use `--export log.json` for a machine-readable session log.
+
+## Want more?
+
+Ghost Mode shows you what happened. **UNWIND** lets you control it:
+
+- 15-stage enforcement pipeline (path jail, SSRF shield, DLP, canary honeypots)
+- Smart snapshots with one-command rollback
+- CRAFT tamper-evident audit chain
+- Real-time trust light dashboard
+- Detects encoded/obfuscated data exfiltration attempts
+
+```bash
+pip install unwind-mcp
+```
+
+[github.com/unwind-mcp/unwind](https://github.com/unwind-mcp/unwind)
+
+## License
+
+MIT

ghostmode-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ghostmode/__init__.py,sha256=L71HGgMslnfm4huuQiKOqUWmyCTT6Z_FedXEKm7J3NA,130
+ghostmode/cli.py,sha256=A-bXFoCTMsDz0cCZXbHjNny8y34enE6RCK0khlJviC0,4145
+ghostmode/event_log.py,sha256=Gh3L5VVWVTYC8l1R1ZfwCMFK1jBeTRmnvtwMOAgAMS0,4666
+ghostmode/proxy.py,sha256=FKBFMcAz7hi5eVKJ9pWpr0B811A62w2uEIriRGUKmso,18345
+ghostmode/shadow_vfs.py,sha256=6-weNiFhx_sFMjftDwfZi4S5JuMRKnEE7cpCAGZBIIU,2365
+ghostmode-0.1.0.dist-info/licenses/LICENSE,sha256=rE3GEttfJ0MbIEdKqlkUO1U21Dos0_UQR0I9Wn5dD8w,1070
+ghostmode-0.1.0.dist-info/METADATA,sha256=btlVZpPRx4PAJuV35nDSKxau5dQjW09h5h6gTanNFKg,6346
+ghostmode-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ghostmode-0.1.0.dist-info/entry_points.txt,sha256=u39fQDBfWMRW4N0p9adNcnG_P7XAJHyDQpW8wzXVmiM,49
+ghostmode-0.1.0.dist-info/top_level.txt,sha256=z7A_ZKsvnr3fqPVvHg2r1MCHvkmoo2kQ-D4ZtZYuIhM,10
+ghostmode-0.1.0.dist-info/RECORD,,

ghostmode-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ghostmode-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ghostmode = ghostmode.cli:main

ghostmode-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghostmode-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ghostmode