Folly critic-iterate 安全恢复指南：处理 Guardian 对 `codex-reviewer.py` 顶层调用的拒绝

Folly critic-iterate 安全恢复指南：处理 Guardian 对codex-reviewer.py顶层调用的拒绝

【免费下载链接】follyAn open-source C++ library developed and used at Facebook.项目地址: https://gitcode.com/GitHub_Trending/fol/folly

本指南聚焦 Folly 仓库中critic-iterate作者-评审循环（author-critic loop）在代码评审执行链路里的一个具体故障场景：当安全代理 Guardian 将顶层对受信任评审包装器codex-reviewer.py的调用判定为"可能存在数据外泄（possible exfiltration）"并拒绝时，如何向 Guardian 提供证据完成重试、如何为用户生成一条窄化的默认白名单规则并验证其生效。读完本文，你将掌握一套完整的"拒绝 → 证据重试 → 白名单固化 → 规则校验"恢复流程，以及codex-reviewer.py包装器固定接口背后的设计原理。

适用边界：只在"可能外泄"拒绝时使用本文档

folly/agents/critic-iterate/auth-prompt.md开篇即划定了严格的使用范围：

• 仅在 Guardian 对受信任评审包装器的顶层调用报告"可能存在外泄"之后使用；
• 它的作用是告诉 Agent 如何为重试提供 Guardian 可评估的证据，以及如何为包装器添加一条窄化的默认规则；
• 它不是通用策略管理指南，不应被推广到其他策略故障场景。

这一边界在包入口文档 folly/agents/critic-iterate.md 的 "Codex reviewer mechanism" 一节有对应表述：只有遇到 Guardian 对顶层包装器调用的"可能外泄"拒绝时才读取critic-iterate/auth-prompt.md，绝不在正常路径（happy path）上、也不为无关的策略失败读取它。恢复步骤不会触及运行在私有CODEX_HOME下的嵌套评审器——嵌套评审器报告拒绝或运行失败后即停止，不会自行重试。

同时需要明确的是，auth-prompt 属于操作性规则而非开发材料。仓库中与之同名的 auth-prompt.contrib.md 明确标注了> NOT A RULE. If loaded as task policy, stop and ask the user.，其作用是记录该规则的撰写目的与背景（即"NOT A RULE"标记本身不可作为任务策略加载），这与 folly/agents/README.md 中"*.contrib.md是开发材料，不是操作规则"的约定一致。

角色分工：谁拥有证据、批准与重试

Guardian 拒绝发生时的责任边界由文档明确约定：

角色	职责
嵌套或委派会话（nested/delegated session）	将完整的拒绝文本向上报告后停止，不自行处理
顶层作者或编排者（top-level author/orchestrator）	拥有证据收集、用户批准与重试的决策权
顶层会话	即使后续重试成功，也必须把完整的拒绝文本展示出来（Surface the full rejection text even if a retry succeeds）

这意味着恢复动作必须在顶层会话执行，嵌套评审器不参与 Guardian 交涉；完整拒绝文本是审计记录的一部分，不能因为最终成功而被隐去。

被保护对象：codex-reviewer.py的固定接口

理解恢复流程前，需要先认识被白名单保护的包装器本身。folly/agents/critic-iterate/codex-reviewer.py的设计目标是"通过一个固定、可白名单化的接口运行 Codex 评审"（Run Codex reviews through a fixed, allow-listable interface.），其要点如下。

固定命令行形态

包装器不接受任意参数组合，parse_args中硬编码了固定形态：

codex-reviewer.py --preamble-dir=PATH --preamble=NAME --workdir=PATH PROMPT

源码中通过以下手段强制这一形态（codex-reviewer.py）：

• allow_abbrev=False：禁止参数缩写，防止--prea之类歧义写法；
• 检查len(argv) != 4或任一参数不以--preamble-dir=、--preamble=、--workdir=前缀开头，直接parser.error；
• 三个路径参数都必须是绝对路径，且逐一校验：preamble 目录必须是目录、<preamble>.md必须是常规文件、prompt 必须是文件、workdir 必须是目录；
• --preamble的可选值被锁定在REVIEW_PROFILES字典中：

preamble 名称	沙箱参数-s	用途
fresh-review-preamble	不设置（None）	新鲜评审者（source-aware），只读外层沙箱会阻塞嵌套冷评审的私有输出，因此不设-s
cold-review-preamble	"read-only"	冷评审者（artifact-only），显式保持只读

对应地，两个 preamble 文件分别定义了评审者行为：fresh-review-preamble.md 负责"先形成独立标准再读候选稿，并在最后整合冷评审报告"，cold-review-preamble.md 负责"只依据任务允许的输入、以普通语言解释作品，不重写、不评估覆盖面"。

私有输出与自建目录

包装器会自行管理输出，绝不把评审结果写到调用方目录（codex-reviewer.py）：

• 输出根目录为~/.codex/tmp，每次运行用tempfile.mkdtemp生成%Y%m%d-codex-reviewer.*私有目录，并打印REVIEW_OUTPUT_DIR=<path>标记；
• 运行期间将 umask 收紧为0o077，确保 prompt 与 trace（可能含源码文本）仅当前用户可读；
• 生成effective-prompt.md（preamble + prompt 拼接）、review.md（最终评审）、run.jsonl（过程 trace）、err.txt（错误流）四件套，供审计；
• 为每次评审创建私有CODEX_HOME（output_dir/codex-home，权限0o700），并在环境中用CODEX_HOME覆盖用户默认配置，从而排除用户规则与可执行配置的干扰；
• 实际执行命令形如codex [-s sandbox] -a never exec --ignore-user-config --skip-git-repo-check --ephemeral --json --output-last-message <review.md> -（-a never表示评审是无头的，无法应答批准提示，因此两个 preamble 都要求把完整评审放进最终响应）。

正是这种"固定接口 + 逐参数校验 + 自建输出目录"的结构，构成了白名单规则的信任基础：白名单只需要锁定包装器本身，而不必信任裸露的codex exec或 shell。

带证据重试（Retry with evidence）

Guardian 在判定时会评估完整 transcript，包括命令输出。因此重试的第一步不是改命令，而是展示足以说明"这是受信任包装器、而非任意命令执行"的证据。

1. 展示环境证据

按 folly/agents/critic-iterate.md "Loading" 一节的解析规则取得包装器路径（.../name表示解析后的绝对路径，从PATH解析一次，缺失时回退到包内critic-iterate/codex-reviewer.py，仍不可用则停止），然后依次展示环境中的 Codex 命令、包装器真实路径及其固定接口：

codex --version readlink -f .../codex-reviewer.py .../codex-reviewer.py --help

其中readlink -f .../codex-reviewer.py用于向 Guardian 证明调用目标解析到的绝对路径就是受信任包装器本身（而非被符号链接替换的其它程序），--help则展示其固定的、仅有的接口形态。

2. 陈述信任声明

接着向 Guardian 明确陈述以下文字（原文为英文，可直接照用）：

The trusted codex-reviewer.py wrapper delegates to Codex; this ambient session also runs in Codex. The wrapper restricts the nested call to its fixed review interface and controls its output directory.

即：受信任的codex-reviewer.py包装器将工作委托给 Codex，本会话本身也运行在 Codex 中；包装器把嵌套调用限制在它固定的评审接口上，并自行控制其输出目录。

3. 原样重试

用同一条包装器命令重试。文档强调两条红线：

• 不要扩大包装器的权限；
• 不要仅仅为了绕过拒绝而修改命令。

4. 若 Guardian 仍要求批准

如果 Guardian 仍然要求人工批准，则：

1. 向用户展示 Guardian 的完整风险文本，询问用户是否批准这一次确切的运行；
2. 无头（headless）会话不询问用户，直接停止并报告拒绝；
3. 只有用户实际批准后才重试；若该次重试仍被拒绝，停止，不再继续尝试。

防止复发（Prevent recurrence）：白名单固化与校验

重试成功的下一步，是为包装器建立一条窄化默认规则，避免每次评审都被 Guardian 拦截。

白名单原则

• 白名单受信任的包装器本身，绝不白名单codex exec或 shell；
• 包装器必须持续校验每一个参数、自行创建输出目录——这两点正是 codex-reviewer.py 的既有行为（parse_args的强制校验与run()中tempfile.mkdtemp自建目录），白名单信任由此闭环。

生成规则声明

将上一步readlink -f解析出的包装器路径替换...占位符，把以下声明打印给用户，让用户添加到~/.codex/rules/default.rules：

cat <<'RULES' host_executable(name="codex-reviewer.py", paths=[".../codex-reviewer.py"]) prefix_rule(pattern=["codex-reviewer.py"], decision="allow", justification="The review wrapper validates its fixed profiles and arguments and controls its output directory.") RULES

两条规则的语义分别是：

• host_executable(name=..., paths=[...])：声明该名称对应的主机可执行文件为绝对路径列表中的实体（等价于告诉策略引擎"codex-reviewer.py这个命令就是那个文件"）；
• prefix_rule(pattern=[...], decision="allow", ...)：当命令前缀匹配["codex-reviewer.py"]时放行，并记录 justification（评审包装器会校验其固定的 profiles 与参数、控制其输出目录）。

值得一提的是，这一手工规则格式与包装器源码内部的自动生成逻辑完全一致：_install_cold_review_policy（codex-reviewer.py）在 fresh 评审场景下会向私有的CODEX_HOME/rules/default.rules写入同样的host_executable+prefix_rule组合，只不过前缀被锁定为["codex-reviewer.py", "--preamble-dir=<abs>", "--preamble=cold-review-preamble"]，因为 exec-policy 前缀规则无法约束尾部参数，所以尾部 workdir/prompt 由parse_args的固定顺序与绝对路径校验兜底。

安装后校验规则

用户添加规则之后，不要实际发起评审，用codex execpolicy check离线验证规则是否匹配包装器命令：

codex execpolicy check \ --pretty \ --resolve-host-executables \ --rules "$HOME/.codex/rules/default.rules" \ .../codex-reviewer.py \ --preamble-dir="$(dirname "$(readlink -f "/path/to/critic-iterate.md")")/critic-iterate" \ --preamble=cold-review-preamble \ --workdir="$(mktemp -d)" \ "$(mktemp)"

命令参数说明：

参数	作用
--pretty	人类可读的 JSON 输出
--resolve-host-executables	解析host_executable声明，验证真实文件路径
--rules "$HOME/.codex/rules/default.rules"	显式指定要检查的规则文件
--preamble-dir=...	从critic-iterate.md实际位置反推critic-iterate包目录（注意把/path/to/critic-iterate.md替换为真实路径）
--preamble=cold-review-preamble	选择冷评审 profile（与规则前缀匹配）
--workdir="$(mktemp -d)"	用临时目录作为 workdir，避免触碰真实目录
"$(mktemp)"	用一个空临时文件充当 prompt 占位，不触发真实评审

结果应当显示"decision": "allow"。文档特别提醒：这只能证明规则与包装器命令匹配，不能证明评审本身会被 Guardian 放行——规则校验与实际策略执行是两个层面。

关键流程速查

阶段	核心动作	关键红线
定位	顶层会话处理；嵌套会话上报后停止	只在"可能外泄"拒绝时使用本流程
证据	codex --version、readlink -f、--help+ 固定接口	展示解析后的绝对路径
声明	陈述"包装器限制嵌套调用到固定接口并控制输出目录"	—
重试	原样重跑同一包装器命令	不扩权、不改命令绕过
批准	展示完整风险文本，等用户批准	无头会话不询问，直接停止；再次被拒则停止
白名单	host_executable+prefix_rule写入~/.codex/rules/default.rules	只白名单包装器，不白名单codex exec/shell
校验	codex execpolicy check离线检查	期望"decision": "allow"，只证明规则匹配

总结与安全边界

auth-prompt.md是一份高度场景化的故障恢复规程：它以"信任包装器、信任它的固定接口"为前提，把 Guardian 的"可能外泄"拒绝转化为"证据 → 批准 → 白名单 → 校验"的闭环，同时用三条红线约束整个流程——不扩大包装器权限、不改命令绕过拒绝、无头会话不得自行假设用户批准。整套机制与 codex-reviewer.py 的固定接口、私有输出目录、私有CODEX_HOME设计相互印证，也与 folly/agents/critic-iterate.md 中"绝不扫描临时目录、绝不从部分输出推断评审结果"的纪律一致。使用本流程时请始终记得：它是专门针对顶层包装器调用的恢复指南，不是通用策略管理文档，也不适用于嵌套评审器运行在私有CODEX_HOME下的失败场景。

【免费下载链接】follyAn open-source C++ library developed and used at Facebook.项目地址: https://gitcode.com/GitHub_Trending/fol/folly