跳转至

仓库门禁与任务产物目录

English: Task artifact directories

已启用项目门禁的 Codex Desktop 聊天可以在本任务已授权的仓库外目录写入评测样例、报告和其他产物。仓库内代码继续执行 Operation v2;仓库外输出需要登记精确目录。登记是流程范围元数据,execution_authorization=NONE,不替代 Desktop 沙箱、审批或用户授权,也不返回 permissionDecision: allow。

使用流程

  1. 按任务授权准备独立的产物工作目录,使用其绝对路径。目录必须存在;不要登记盘根、账户主目录、源码仓库或控制文件目录。
  2. 在当前 Desktop 聊天发起实际需要的原生 apply_patch。尚未登记时返回 ARTIFACT_SCOPE_UNREGISTERED,不执行文件写入。Hook 从全部目标冻结最窄的已存在公共父目录,并返回 AR1-... 请求引用和精确登记命令;范围不能由管理脚本改写。
  3. 使用当前安装版本的管理入口登记目录。以下源码入口只用于开发;已安装环境使用账户 tools/cp-runtime.py 的同名命令。
python scripts/cp-runtime.py capability-task-artifact-register --profile <project-profile.json> --repo-path <repo> --request-ref <AR1-native-request>

管理命令只消费原生请求记录,不接受会话号、任意产物目录或有效期参数,也不使用环境变量声明会话归属。请求冻结会话、项目、目录身份和期限;命令只能完成该范围的登记,不能扩大它。不要修改状态 JSON、提供提示词白名单,或把缺少登记当成更换写入工具的理由。

登记需要读取绑定仓库并写入账户门禁状态。普通沙箱被 Git 所有权保护拒绝时,返回 PROFILE_HOST_CONTEXT_REQUIRED,不把它当作已确认的 Profile 损坏。在已有任务授权内,通过宿主审批执行同一条精确登记命令,再读回登记结果;不要修改 Profile、关闭 Git 所有权保护或放宽文件系统沙箱。

子 Agent 的独立上下文可能无法提供主聊天中的真人授权。此时由主协调者核对原生父子关系、子回合、已批准工作、精确目录与固定期限,并在已有真人授权范围内执行原登记命令。子 Agent 保持当前轮次等待,只在实际读回 REGISTERED 后重试原补丁。自动审批拒绝后,必须先补充核验证明;真实越界不能通过更换执行者绕过,也不能改写请求或扩大目录范围。

登记恢复不撤销已经发生的模型调用。已结束的失败子调用保留原账本消耗;需要补跑时仍使用同一工作及有效额度,不通过新聊天、改名或重建任务清账。

  1. 重试原生补丁。全部目标必须属于同一个已登记目录;最终是否能写由宿主原有权限决定。中性 Hook 响应只表示不适用仓库复用流程,不表示产物正确或写入已经完成。
  2. 任务结束或范围变化时撤销对应目录,再读回命令结果。撤销不删除产物。
python scripts/cp-runtime.py capability-task-artifact-revoke --profile <project-profile.json> --repo-path <repo> --request-ref <AR1-native-request>

每个会话和项目最多登记 16 个互不重叠的目录。请求须在生成后 5 分钟内消费,产物范围在请求生成后 240 分钟到期;重复消费不续期,撤销后不能重放登记。过期或目录替换时,重新核对任务授权并通过新的原生补丁请求冻结范围。命令返回的 roots 是实际读回范围。登记写入中断时,尚未完成的请求不能使产物范围可用;撤销优先使范围失效,再幂等移除记录。

不可放宽的边界

  • 一个补丁中不能混合仓库代码和外部产物;Move 的源与目标分别检查。相对路径按原生 Hook 的真实工作目录解释,不能使用 ..。
  • 控制文件、门禁状态、Profile、索引、插件载荷、其他登记项目的控制目录及 Git 仓库均不能作为产物目录。账户工具目录受保护,账户 visualizations 下的具体任务产物目录仍可在通过其他检查后登记。
  • 拒绝符号链接、重解析点、现存多链接目标、UNC/设备路径、驱动器相对路径、ADS 以及有歧义的路径形式。目录、目标、祖先查询和处理时间均有上限;无法证明范围时拒绝对应写入。
  • 原生 PreToolUse 保存不含补丁正文的调用绑定。PostToolUse 先按会话、轮次与 tool_use_id 找原调用,再核对原工作目录和命令摘要;改成仓库外路径或其他 cwd 不能跳过已派发操作的收敛。
  • 升级前已派发且没有新调用绑定的操作保留旧兼容路径,不补造新证据。源文件修改、软件包安装和实际 Desktop 加载是不同状态。

验证与限制

历史项目登记中的本地目录别名只用于查找保护范围:同时保护登记路径和当前实际目标,限制链接层数、查找数量与时间,并拒绝网络别名及循环。一个无关历史 junction 不应把普通产物误判为链接写入。实际写入目标及其祖先仍须通过原来的无链接检查;登记别名的解析不会授予跟随链接写入的权限。

已登记的远端根仅保留其路径边界,本地写入检查不访问远端文件系统。实际 UNC 写入和本地控制别名转向网络路径仍拒绝;不据此宣称已核验远端文件系统或跨主机物理别名。

开发回归入口:runtime/tests/test_artifact_scope.py、test_patch_intent.py 和 test_capability_gate_hook.py。测试中的临时仓库、合成身份和 Hook 子进程不等于真实 Desktop 权限验收;运行结果应分别记录跳过项。

此 Hook 不是完整文件系统安全边界,也不保证原生写入与预检查之间的原子性。宿主沙箱继续控制实际写入;shell/MCP 等入口不能因此宣称受本门禁保护。协议依据见 官方 Hooks 文档。