pi-approval-guardian

為 Pi 工具呼叫提供預設 fail-closed 的自動審核。

Agent 執行 shell、讀取私密資料，或修改專案外／敏感檔案前，會先交由隔離 reviewer model 評估。

English · 繁體中文 · 简体中文 · 日本語 · 한국어 · Español

[!IMPORTANT] Pi extension 會以目前使用者權限執行。安裝前請先檢查原始碼。本套件是 approval gate，不是作業系統 sandbox。

安裝

pi install npm:pi-approval-guardian

預設使用 openai-codex/codex-auto-review，共同 deadline 為 90 秒。尚未登入官方 Codex provider 時執行：

/login openai-codex
/reload
/approval-guardian

預設設定不需要建立設定檔。

預設保護範圍

| 工具／動作 | 預設審核範圍 | | --- | --- | | bash.command | 全部送審 | | grep.path | 專案外搜尋，或 path／pattern／glob／有效 scope 可能接觸私密資料時送審 | | read.path | 已知私密資料 | | find.path／ls.path | 已知私密路徑 | | write.path／edit.path | 專案外或私密／敏感路徑 | | 其他帶有字串 path 的工具 | 預設 private-only |

一般乾淨的專案內 source edit 與搜尋不增加 reviewer 延遲。使用者直接輸入的 !／!!、其他 terminal 或其他 process 不會被攔截。

運作方式

Pi agent tool call
        │
        ├─ 一般動作 ───────────────────────────────► 執行
        │
        └─ 受保護動作
               │
               ▼
        隔離 Guardian reviewer
        一般審核：read · grep · find · ls
        私密資料審核：不提供工具
               │
          ┌────┴────┐
          ▼         ▼
        allow     其他結果
        執行       阻擋

Guardian 啟用時，受保護動作只有在 reviewer 回傳有效的 outcome: "allow" 後才會執行。Deny、timeout、錯誤輸出、auth/model/provider failure、取消與 circuit open 都會 fail closed。

私密資料還必須在 user transcript 中已有明確授權，且 reviewer 回傳 user_authorization: "high"。

私密資料判定

常見保護項目包括：

• .env、.npmrc、.netrc、.pypirc、Git credential、service-account、credential／secret 目錄；
• SSH／GPG 金鑰、cloud CLI、Kubernetes、Docker 認證；
• Browser login store、password manager、keychain／keyring、VPN、私密憑證與 Terraform credential；
• Linux、macOS 與 Windows 的常見 credential 位置；
• Pi 的 auth、settings/model/Guardian/trust、API key、run/session/delegate history、memory、context/session database 與搜尋索引。

整個 .pi/ 不會被視為私密。.pi/agent/npm/node_modules/ 內的已安裝套件程式碼與 skill 文件，以及使用者的 skill／agent／extension 原始碼，不會只因位於 .pi/ 就要求私密讀取授權；個別檔名仍可能命中其他規則。

讀取與修改採不同分類：project .pi/skills、.pi/agents、.pi/extensions、prompts、themes、chains 與套件設定仍是敏感 mutation surface，因為修改後可能改變 Pi 行為。它們的讀取不會只因 .pi/ 位置被視為機密，但修改仍會送審。

分類會使用 canonical path，並解析 symlink target。

Reviewer 行為

• Reviewer 狀態使用獨立的 in-memory session；最後 fallback 可使用主 session 的 model identity，但不會重用主對話狀態。
• 一般審核只提供 read、grep、find、ls。
• 私密資料授權審核完全不提供工具。
• Reviewer 不會取得 bash、write、edit。
• Transcript、檔案、tool output 與 planned action 都視為不可信 evidence。
• 每個 reviewer channel 各自在共同 deadline 內，對錯誤 assessment 與部分暫時性 provider failure 最多嘗試 3 次。

連續 3 個 adverse batch，或最近 50 個 review batch 累積 10 個 adverse batch，會開啟 circuit。Deny、timeout 與 failure 屬於 adverse；allow 與取消不計。同一筆 assistant message 的 sibling tool calls 視為一個 batch。

選用設定

Global：

~/.pi/agent/approval-guardian.json

Trusted project：

<project>/.pi/approval-guardian.json

最小範例：

{
  "model": "openai-codex/codex-auto-review",
  "fallbackModel": "openai-codex/codex-auto-review",
  "timeoutMs": 90000,
  "policy": "未取得精確授權時不得修改 production。"
}

也可使用已在 Pi model registry 註冊並完成認證的自訂 reviewer channel。去除重複 model 後，Guardian 會依序嘗試 primary、設定的 fallbackModel，最後才使用目前 Pi session model。只有 model／認證不可用或明確 failure 才會進下一個 channel。Timeout 會直接讓該動作 fail closed，不再嘗試其他 channel；allow、明確 deny 與取消也會立即停止。每個 channel 都有各自獨立、可增量重用的 reviewer session，切換提示只顯示於 UI。

預設 review matrix：

{
  "review": {
    "bash.command": "always",
    "grep.path": "outside-or-private",
    "read.path": "private-only",
    "find.path": "private-only",
    "ls.path": "private-only",
    "write.path": "outside-or-private",
    "edit.path": "outside-or-private"
  }
}

可用層級：always、outside-or-private、private-only、off。

Trusted project 只能提高 global 保護，不能降低：

off < private-only < outside-or-private < always

預設會審查每個 agent bash；一般專案內 grep 若 path、selector 與有效 scope 都不涉及私密資料，則不增加 reviewer 延遲。需要更嚴格模式時可把 grep.path 設為 always。不建議直接關閉 bash.command，除非已有可信的 shell gate 或 sandbox 提供同等保護。

環境變數：

PI_APPROVAL_GUARDIAN_MODEL
PI_APPROVAL_GUARDIAN_FALLBACK_MODEL
PI_APPROVAL_GUARDIAN_TIMEOUT_MS
PI_APPROVAL_GUARDIAN_POLICY

Primary model、fallback model 與 timeout precedence：environment > trusted project > global > built-in default。Policy 會合併 global、trusted project 與 environment 設定。

格式錯誤或不支援的設定只會顯示 UI 警告並被忽略；其餘有效設定與內建預設仍會生效，因此設定 typo 不會全域阻擋工具。未啟用暫時 bypass 時，受保護動作若未取得 reviewer 的有效 allow，仍然會 fail closed。

執行 /approval-guardian 可查看 primary、設定 fallback、current-model fallback 的 readiness 與有效設定來源；/approval-guardian rules 可查看生效中的規則。

暫時 bypass

確定要在目前 Pi 執行階段短暫停用審核時，執行：

/approval-guardian bypass

bypass 期間，editor 下方會持續保留單行警告。停用期間，受保護的 agent tool call 會略過 Guardian 分類、reviewer 推論、核准 input 鎖定與 circuit enforcement；其他 extension 或 tool 內部檢查仍然有效。要恢復保護，執行：

/approval-guardian enable

指令會等待目前 agent run 完全結束後再切換狀態；不會放行或重試先前已阻擋的 call、不會自行觸發新的 agent turn，也不代表授予 agent 額外權限。bypass 只保存在記憶體中，遇到 /reload、/new、/resume、/fork 或 process 重啟就會自動清除。只有互動式 TUI mode 能啟用；RPC、JSON 與 print mode 因無法保證持續顯示警告而會拒絕。

bypass／enable 通知只顯示於 UI。Guardian 刻意不把這個控制狀態注入 agent context：持久的「已 bypass」訊息可能在重新啟用後變成過期資訊，也可能被誤解為工作授權。要 agent 執行什麼，仍應另外下達明確指令。

這會移除一層重要安全邊界，只應在明確且短暫的時間窗使用。

更新與移除

pi update npm:pi-approval-guardian

更新後執行 /reload。

pi remove npm:pi-approval-guardian

專案區域安裝與移除：

pi install -l npm:pi-approval-guardian
pi remove -l npm:pi-approval-guardian

移除後執行 /reload，即可從目前 session 卸載。

帶版本號的 npm spec 會固定版本；要更新 pin，請重新安裝新的明確版本。

安全限制

• 核准後的動作仍以 Pi 的一般使用者權限執行。
• Reviewer 判斷具有機率性，可能出錯。
• Reviewer provider 會收到 bounded transcript 與 planned-action metadata。
• 已授權的私密讀取不會在主對話中自動遮罩。
• 路徑分類先套用與 Pi 相同的 ~、@、file:// 與 Unicode 空白正規化，但規則仍是 heuristic，無法辨識所有重新命名或間接 secret。
• Shell 不會被完整解析成 AST；Guardian 只對常見私密目標做有界 glob 比對，複雜間接讀取仍可能漏判。
• allow 後 Guardian 會驗證並鎖定 JSON-like tool input，避免後續 tool_call handler 改寫；exotic runtime value 會 fail closed。它無法觀察 commandPrefix、spawnHook、custom tool 內部行為或 dispatch 後的 filesystem 變化。
• Pathless 或 nested-path custom tools、MCP、network、browser、email、deployment 與 subagent 動作不會自動全部受保護，必須有專屬 enforcement。
• Filesystem 狀態可能在審核與執行之間改變。
• Guardian 啟用時，Primary、設定 fallback 與不同的 current-model fallback 都不可用會讓受保護動作 fail closed。
• 使用者啟用暫時 bypass 後，Guardian review、input lock 與 circuit enforcement 會刻意停用，直到重新啟用或自動重設。
• Pi project trust、OS/container sandbox 與本套件解決的是不同安全層。

完整技術行為請參閱 docs/REFERENCE.md。

開發

需要 Node.js 22.19 以上。

npm install
npm run check
npm run package:check
pi -e .

維護者發布流程請參閱 docs/PUBLISHING.md。

授權與來源標示

原始專案程式碼採 MIT License。修改與改寫的 OpenAI Codex Guardian policy／prompt 材料仍適用 Apache License 2.0，詳見 NOTICE。

本專案受 Guardian 啟發，與 OpenAI 無隸屬或背書關係。