Workspace grants now live in the current user's private store (~/.gemini/config/agent-blindfold-grants/) and use the canonical workspace path as identity. Issuing, renewing, or revoking a grant never modifies project files or Git metadata—cleanly supporting regular repositories, linked worktrees, and submodules without dirtying git status.
The Unix/Bash hooks require Python 3.9 or newer. They probe the active virtual environment, working executables on PATH (skipping empty WindowsApps alias stubs under Git Bash), and the Windows py launcher where available; a missing interpreter or malformed hook payload fails closed with a host-compatible blocking response.
Upgrading existing workspaces from v1.1.x: Legacy in-project .allow_media files are now ignored and left intact so untrusted repositories cannot ship pre-unlocked passes. Review each workspace path and use the local controller (unlock.ps1 / unlock.sh / blindfold-control.cmd) to reissue any manual timed or permanent grants you want to keep. Default timed policy still renews at each eligible session start; set off to require manual approval for each new grant. Existing local grants can be revoked individually, and an invalid policy file pauses new automatic issuance rather than falling back to auto-grant. Status output displays the effective settings for the current process along with their sources.
Modern AI Coding Agents (Google Antigravity, Claude Code, etc.) are natively multimodal—whenever an agent invokes read_file, Read, or an MCP inspection tool on a local image, video, or audio file, the raw binary bytes are immediately uploaded to cloud multimodal endpoints.
Relying solely on system prompts (GEMINI.md / CLAUDE.md) is a gentleman's agreement, not a security boundary:
- Irreversible Privacy Leakage: During broad directory scans, parallel subagent exploration, or long-context attention decay, an agent can accidentally read personal photos, screen recordings, or cached chat media in
Pictures,Downloads,Desktop, orAppData. Once transmitted to the cloud, it cannot be undone. - False-Positive Account Bans (Anti-Ban Shield): Cloud safety classifiers automatically audit uploaded visual media. If an agent accidentally reads local anime illustrations (e.g., Monogatari / Oshino Shinobu artwork), game CGs, or private artwork on your disk, automated cloud moderation can flag your account and trigger an immediate, irreversible account suspension.
agent-blindfold (Heart-Under-Blade / 刃下心) enforces Dual-Layer Zero-Trust Protection without blinding frontend/UI engineering:
- Layer 1 — Soft Prompt Discipline (
rules/AGENTS.md): Instructs the agent upfront to skip personal/external binary media while permitting legitimate UI/frontend verification assets. - Layer 2 — Host Tool-Call Guard (
SessionStart+PreToolUseHooks): Automatically grants Timed (TTL) or Permanent workspace passes at the start of engineering sessions, exempts UI sandboxes (scratch,brain,.playwright-mcp,.svg), and checks protected media paths and attempted policy changes before covered host tool calls.
flowchart TD
S["SessionStart Hook<br/>(session_start.ps1 / session_start.sh)"] --> S1{"Engineering Workspace?<br/>(Skips Vaults & Read-Only Chat)"}
S1 -- "Yes" --> S2["Issues user-owned workspace grant<br/>(Timed Default 2h OR Permanent)<br/>in private user state"]
A["Agent invokes Tool<br/>(read_file / Read / Write / MCP / run_command / Bash)"] --> T{"Anti-Tamper Guard:<br/>Touches .allow_media / policy / unlock.*?"}
T -- "Yes (Mutation / Exec)" --> DENYT["🚫 HARD DENY<br/>(Blocks Agent Self-Unlock)"]
T -- "No" --> C{"Touches Monitored Media?<br/>(.jpg/.png/.webp/.heic/.mp4/.mp3...)"}
C -- "No (Code / Web https:// / Workspace .svg)" --> ALLOW["✅ ALLOW / Neutral Pass-Through"]
C -- "Yes" --> D{"Tier 1: In Hard Personal Vault?<br/>(Pictures / Videos / Music / AppData<br/>or Root Desktop / Downloads / Documents)"}
D -- "Yes" --> DENY1["🚫 HARD DENY<br/>(Permanently Locked)"]
D -- "No" --> E0{"Tier 0: Engineering Sandbox?<br/>(scratch/<app> / active brain/<id> / .playwright-mcp)"}
E0 -- "Yes (Symlink-Verified)" --> ALLOW
E0 -- "No" --> E{"Tier 2: Inside a Dedicated<br/>Active Project Workspace?"}
E -- "No (External Path / Sibling Leak)" --> DENY2["🚫 HARD DENY<br/>(External Directory Isolation)"]
E -- "Yes" --> F{"Tier 3: Valid local workspace grant?<br/>(Permanent or Unexpired Timed TTL)"}
F -- "No / Expired (Auto-Cleaned)" --> DENY3["🔒 DEFAULT DENY<br/>(Blocks Read & Shell Byte-Dump;<br/>Allows Safe Git Ops)"]
F -- "Yes" --> ALLOW
- Images:
.jpg,.jpeg,.png,.gif,.webp,.bmp,.ico,.heic,.heif,.avif(Note: plain-text.svgvector icons inside project workspaces and engineering sandboxes are exempted so frontend UI development is never disrupted;.svginside personal vaults remains blocked). - Video:
.mp4,.mkv,.avi,.mov,.webm,.flv,.wmv - Audio:
.mp3,.wav,.flac,.m4a,.ogg,.aac
| Tier | Scope | Policy | Real-World Behavior |
|---|---|---|---|
| Tier 1: Hard Personal Vaults | Pictures, Videos, Music, AppData, plus root Desktop, Downloads, Documents |
Unconditional deny |
Permanently locked—even if ~/Downloads itself is opened as a workspace or contains .allow_media. Evaluated after symlink/junction resolution. |
| Tier 0: Engineering Sandboxes | ~/.gemini/antigravity/scratch/<subproject>, active artifactDirectoryPath (brain/<current-id>), <workspace>/.playwright-mcp/ |
Auto-Exempt (allow) |
Keeps frontend/SVG/Playwright UI visual checks working seamlessly even when no Active Workspace is mounted, while blocking cross-session .user_uploaded/ leaks. |
| Tier 2: External Directories | Any path outside your active dedicated project workspace (workspacePaths / cwd) |
Unconditional deny |
Blocks cross-drive snooping, ../ traversals, symlinks, and sibling files in parent folders. |
| Tier 3: Dedicated Project Workspace | Project assets inside a specific repo (including repos cloned under ~/Downloads/my-app or ~/Desktop/my-app) |
SessionStart Auto-Pass (timed / permanent) or Manual Pass |
Automatically receives a timed (2h default) or permanent local grant at session start (configurable to off for strict manual mode); expired passes auto-clean themselves. |
- Anti-Tamper Guard (Zero Self-Unlock): Intercepts
write_file,edit_file,Write,Edit,MultiEdit, MCP write tools, and terminal commands (run_command/Bash) so AI Agents can never create, edit, forge, or delete local grants (agent-blindfold-grants/), legacy.allow_mediamarkers,agent-blindfold.json, or rununlock.ps1/unlock.sh. - Shell / Terminal Guard (
run_command&Bash): Blocks directory scans onPictures/Videos/Music, blocks shell commands touching personal/external media, blocks command-chainedgitspoofing (git status && base64 a.png), and blocks content-encoding bypasses (base64,certutil,xxd,PIL,cv2,ffmpeg,magick,tesseract) on locked workspace media—without breakinggit status,git add, orgit commit. - MCP & URI Normalization: Inspects nested
call_mcp_toolarguments (markitdown,filesystem,playwright), decodes percent-encodedfile://URIs (%20), strips NTFS::$DATAstreams, resolves symlinks, and ignores publichttps://web URLs. - Zero Permission Hijacking on Claude Code: Exits
0with emptystdoutwhen allowing a tool call orSessionStartevent on Claude Code, deferring cleanly to Claude Code's native permission prompts. - Windows
cmd /cClean Stream: Writes raw UTF-8 (no BOM) bytes directly tostdoutand uses quote-free invocation so WindowsCreateProcessnever corruptsprotojsonwith\"escaping.
git clone https://github.com/zanex-dev/agent-blindfold.git
cd agent-blindfoldBy default, the installer enables Timed (2h) automatic exemption at SessionStart (~/.gemini/config/agent-blindfold.json), installs the Google Antigravity native plugin (~/.gemini/config/plugins/agent-blindfold), and losslessly merges SessionStart + PreToolUse hooks into Claude Code (~/.claude/settings.json with .bak backup):
# Default: Timed 2h auto-exemption at session start
powershell -ExecutionPolicy Bypass -File .\install.ps1
# Optional: Permanent auto-exemption for engineering workspaces, or 'off' for manual-only
powershell -ExecutionPolicy Bypass -File .\install.ps1 -AutoGrant permanent
powershell -ExecutionPolicy Bypass -File .\install.ps1 -AutoGrant timed -DefaultTTL 4hchmod +x ./install.sh ./scripts/*.sh
./install.sh
# Optional: Permanent auto-exemption or custom TTL
./install.sh --auto-grant permanent
./install.sh --auto-grant timed --ttl 4h# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall# macOS / Linux
./install.sh --uninstallBecause agent-blindfold ships as a native Antigravity plugin bundle, you can temporarily pause or resume all hooks & rules live—without uninstalling or restarting the app—via Customizations → Plugins → Agent Blindfold (or via chat link customization://agent-blindfold) whenever debugging or updating the firewall itself.
You can switch global SessionStart policy or issue/revoke per-workspace passes at any time from your own terminal (or by double-clicking blindfold-control.cmd on Windows):
# Grant a 2-hour timed pass (expires automatically; stored in the user profile)
powershell -ExecutionPolicy Bypass -File .\scripts\unlock.ps1 -Mode timed -TTL 2h -Workspace C:\path\to\my-app
# Grant a permanent pass to a trusted frontend project
powershell -ExecutionPolicy Bypass -File .\scripts\unlock.ps1 -Mode permanent -Workspace C:\path\to\my-app
# Check current workspace pass & global SessionStart policy
powershell -ExecutionPolicy Bypass -File .\scripts\unlock.ps1 -Status -Workspace C:\path\to\my-app
# Revoke pass immediately (re-lock workspace)
powershell -ExecutionPolicy Bypass -File .\scripts\unlock.ps1 -Lock -Workspace C:\path\to\my-app
# Switch global SessionStart auto-grant policy (timed | permanent | off)
powershell -ExecutionPolicy Bypass -File .\scripts\unlock.ps1 -GlobalAutoGrant permanent./scripts/unlock.sh --timed 2h --workspace /path/to/my-app
./scripts/unlock.sh --permanent --workspace /path/to/my-app
./scripts/unlock.sh --status --workspace /path/to/my-app
./scripts/unlock.sh --lock --workspace /path/to/my-app
./scripts/unlock.sh --global-auto-grant permanentBy default, block reasons are emitted in concise English + Chinese (bilingual). Customize via environment variable:
AGENT_BLINDFOLD_LANG=en— English onlyAGENT_BLINDFOLD_LANG=zh— Simplified Chinese onlyAGENT_BLINDFOLD_LANG=bilingual— Default (English | 中文)
agent-blindfold ships with zero-dependency cross-platform end-to-end security, local grant store, and sandboxed installer test suites (tests/run_tests.py and tests/test_local_grants.py):
python tests/run_tests.py
python -m unittest discover -s tests -p test_local_grants.py -vagent-blindfold/
├── .github/workflows/
│ └── ci.yml # Multi-OS GitHub Actions CI (Windows, Ubuntu, macOS)
├── assets/
│ └── shinobu-banner.svg # Project vector banner (Heart-Under-Blade)
├── docs/
│ └── v1.1-exemption-design.md # Historical v1.1 architecture & security specification
├── rules/
│ └── AGENTS.md # Layer 1 soft prompt media-isolation rule (Antigravity Plugin)
├── scripts/
│ ├── grant_store.ps1 # Windows user-scoped grant store, canonical path & locking helpers
│ ├── grant_store.py # Cross-platform Python user-scoped grant store & policy helpers
│ ├── guard.ps1 # Windows PowerShell PreToolUse firewall + Anti-Tamper Guard
│ ├── guard.py # Cross-platform Python PreToolUse firewall + Anti-Tamper Guard
│ ├── guard.sh # Unix Bash wrapper for guard.py with fail-closed fallback
│ ├── session_start.ps1 # Windows SessionStart auto-exemption hook (timed / permanent)
│ ├── session_start.py # Cross-platform Python SessionStart auto-exemption hook
│ ├── session_start.sh # Unix Bash wrapper for session_start.py
│ ├── unlock.ps1 # Windows pass issuer & global policy CLI / interactive wizard
│ ├── unlock.py # Cross-platform Python pass issuer & global policy CLI
│ ├── unlock.sh # Unix Bash wrapper for unlock.py
│ ├── claude_settings.py # Surgical non-destructive Claude Code settings.json hook merger
│ └── python_runtime.sh # Verified Python 3.9+ discovery helper (skips WindowsApps stubs)
├── tests/
│ ├── run_tests.py # Cross-platform E2E security, SessionStart & installer test suite
│ └── test_local_grants.py # User-scoped grant store, fail-closed & host integration tests
├── blindfold-control.cmd # Windows one-click interactive exemption control launcher
├── .gitattributes # Enforces LF on .sh/.py and CRLF on .ps1/.cmd across checkouts
├── hooks.json # Native Antigravity SessionStart + PreToolUse hook manifest
├── plugin.json # Native Antigravity plugin manifest
├── install.ps1 # Windows idempotent installer & uninstaller
├── install.sh # macOS / Linux idempotent installer & uninstaller
├── SECURITY.md # Threat model & vulnerability reporting policy
├── CHANGELOG.md # Release history
├── CHANGELOG_zh.md # Simplified Chinese release history
├── README.md # English documentation
├── README_zh.md # Simplified Chinese documentation
└── LICENSE # MIT License
Released under the MIT License.
Copyright (c) 2026 琢玹 (zanex)