let resolution = match run_permission_request_hooks( // 第一问永远是 Hooks——配置层可以无条件放行/拒绝，零交互成本    self, // 会话实例：hooks 需要它读取当前 turn 的策略配置    ctx.review_context.turn(), // 传入当前 turn 上下文，hook 据此判断策略是否允许该动作    &permission_request_run_id, // 用 call_id 当 hook 运行 id：重试时加 :retry 后缀避免撞车    action.permission_request_payload(), // 把审批动作序列化成 hook 能理解的 payload（工具名+入参）).await // 异步跑完所有 permission_request hooks，拿到配置层裁决（或弃权）{    Some(PermissionRequestDecision::Allow) => ApprovalResolution { // hook 放行 → 直接 Approved，后面两级根本不用跑        decision: ReviewDecision::Approved, // hook 放行 → 最终裁决=批准        source: ApprovalResolutionSource::Hook, // 记录来源=Hook（遥测里映射成 Config）    },    Some(PermissionRequestDecision::Deny { message }) => ApprovalResolution { // hook 拒绝 → 带理由直接拒，同样跳过后面两级        decision: ReviewDecision::denied(message), // hook 拒绝 → 带上它给的拒绝理由        source: ApprovalResolutionSource::Hook, // 来源标记为 Hook（遥测里映射成 Config）    },    None => self.request_reviewer_approval(action, &ctx).await, // hook 弃权（None）→ 进入第二级裁决链};// …（中间省略：网络审批的遥测记录与特殊裁决分支处理）…async fn request_reviewer_approval( // 第二级入口：Guardian 优先，用户兜底——两级串行、不并行    self: &Arc<Self>, // 会话实例：两级裁决都要用它查策略/发弹窗    action: ApprovalAction, // 待审批的动作工单（命令/MCP/网络…）    ctx: &ApprovalContext, // 审批上下文：review 环境、取消信号、理由等) -> ApprovalResolution { // 返回"裁决+来源"二元组，供上层统一处理    if let Some(decision) = self.request_guardian_approval(action.clone(), ctx).await { // Guardian 启用且给出裁决 → 采用它的结果        ApprovalResolution { // Guardian 给出裁决 → 组装成带来源标记的结果            decision, // 返回最终裁决：Approved/ForSession/Denied…            source: ApprovalResolutionSource::Guardian, // 来源=自动审查（遥测映射成 AutomatedReviewer）        }    } else { // Guardian 未启用/弃权返回 None → 落到用户弹窗，这是最后防线        ApprovalResolution { // Guardian 给出裁决 → 组装成带来源标记的结果            decision: self.request_user_approval(&action, ctx).await, // 落到用户弹窗，拿到人的最终选择            source: ApprovalResolutionSource::User, // 来源标记为 User（遥测里就是"人做的决定"）        }    }}

pub(crate) enum ApprovalAction { // 所有需要审批的动作统一建模成这个枚举——一张"审批工单"    ExecCommand { // 跑 shell 命令：带环境、沙箱权限、可选的 execpolicy 修订提案        id: String, // 本次工具调用的唯一 id：弹窗/遥测都靠它关联        environment_id: String, // 在哪个执行环境里跑（本地/远程容器），审批记忆按环境隔离        command: Vec<String>, // 命令参数数组：弹窗展示 + Guardian 审查的对象        cwd: PathUri, // 工作目录：弹窗展示 + Guardian 判断路径风险        sandbox_permissions: SandboxPermissions, // 本次申请的沙箱权限级别（读/写/联网）        additional_permissions: Option<AdditionalPermissionProfile>, // 本次额外申请的权限（如出网）        justification: Option<String>, // 模型给出的"为什么需要这个权限"，会显示在弹窗里        tty: bool, // 是否需要 TTY：交互式命令审批时要提示用户        proposed_execpolicy_amendment: Option<ExecPolicyAmendment>, // 用户可顺手把这类命令永久放行    },    NetworkAccess { // 网络访问审批：host/port/协议齐全，供 Guardian 和 UI 展示目标        id: String, // 本次工具调用的唯一 id：弹窗/遥测都靠它关联        turn_id: String, // 所属 turn：遥测与事件流按它归组        environment_id: String, // 在哪个执行环境里跑（本地/远程容器），审批记忆按环境隔离        target: String, // "https://api.example.com:443" 这种人类可读的目标串        host: String, // 目标域名：审批键的核心字段        protocol: NetworkApprovalProtocol, // http/https/socks5：同域名不同协议分开审批        port: u16, // 目标端口：与 host+protocol 一起构成唯一审批键        trigger: Option<GuardianNetworkAccessTrigger>, // 是哪个命令触发了这次网络访问        command: Vec<String>, // 命令参数数组：弹窗展示 + Guardian 审查的对象        cwd: AbsolutePathBuf, // 命令的工作目录：Guardian 评估风险时参考    },}

pub enum ReviewDecision { // 审批的最终裁决：8 种，覆盖"放行/永久放行/改策略/拒绝/超时/中止"    Approved, // 本次放行，下次同类请求还要再问    ApprovedExecpolicyAmendment { // 放行 + 把 execpolicy 修订落盘，以后匹配的命令免审        proposed_execpolicy_amendment: ExecPolicyAmendment, // 要落盘的命令策略修订：以后匹配的命令免审    },    ApprovedForSession, // 本会话内同类请求自动放行（进 session 缓存）    ApprovedMcpPolicyAmendment, // MCP 工具：跨会话的策略级放行    NetworkPolicyAmendment { // 网络审批专属：持久化一条 allow/deny 域名规则        network_policy_amendment: NetworkPolicyAmendment, // 要落盘的域名规则（allow/deny）：跨会话生效    },    Denied { rejection: String }, // 拒绝但会话继续，模型可以换个办法    TimedOut, // Guardian 自动审查超时——按拒绝处理并给出专门提示    Abort, // 用户中止：整个 turn 停掉，等下一条指令}

pub(crate) async fn with_cached_approval<K, F, Fut>( // "始终允许"缓存包装器：先查 session 级审批记忆，命中就不弹窗    services: &SessionServices, // 会话服务：审批缓存和遥测都挂在它上面    tool_name: &str, // 工具名只用于埋点计数    keys: Vec<K>, // 一个请求可能有多个 key（apply_patch 一次改多文件）    fetch: F, // 真正去问 Guardian/用户的闭包，缓存未命中才执行) -> ReviewDecision // 返回最终裁决（可能来自缓存，也可能刚问过人）where // 泛型约束：key 可序列化、fetch 是异步闭包    K: Serialize, // key 序列化成 JSON 字符串当 map 的键——对任意类型通用的缓存    F: FnOnce() -> Fut, // fetch=真正去问 Guardian/用户的闭包，只在缓存未命中时执行    Fut: Future<Output = ReviewDecision>, // fetch 的返回必须是审批裁决{    if keys.is_empty() { // 防御：没有 key 就跳过缓存直接问，避免空集合 all() 恒真误命中        return fetch().await; // 无 key 可缓存 → 直接走完整审批链    }    let already_approved = { // 全部 key 都"本会话已放行"才算命中——部分命中也要重新问        let store = services.tool_approvals.lock().await; // 拿会话级审批缓存（只读锁）        keys.iter() // 逐个 key 查缓存            .all(|key| matches!(store.get(key), Some(ReviewDecision::ApprovedForSession))) // 全部 key 都"本会话已放行"才算命中——部分命中也要重新问    };    if already_approved { // 命中 → 直接返回，用户完全无感        return ReviewDecision::ApprovedForSession; // 缓存命中 → 直接返回，用户完全无感    }    let decision = fetch().await; // 未命中 → 走完整审批链（Hooks→Guardian→User）    services.session_telemetry.counter( // 埋点：每次真实走到弹窗都计数，按工具名+裁决结果分维度        "codex.approval.requested", /*inc*/ 1, // 计数器名：每次真实走到审批链都记一笔 &[("tool", tool_name), ("approved", decision.to_opaque_string())], // 维度：工具名+裁决结果，便于统计弹窗频率    );    if matches!(decision, ReviewDecision::ApprovedForSession) { // 用户选了"始终允许" → 每个 key 单独入库        let mut store = services.tool_approvals.lock().await; // 拿写锁：把"始终允许"记进缓存        for key in keys { // 逐个 key 入库（apply_patch 多文件时每个都单独记）            store.put(key, ReviewDecision::ApprovedForSession); // 存单 key：下次只碰其中一个文件也能命中        }    }    decision // 返回最终裁决：Approved/ForSession/Denied…}

let registration_id = Uuid::new_v4().to_string(); // 给这次"执行级网络审批"发一个唯一注册号let attribution_token = Uuid::new_v4().to_string(); // 归因 token：代理里的每个请求都能反查到是哪次调用发起的let execution_proxy = network // 从会话级代理派生出"本次命令专属"的执行代理    .for_execution( // 从会话级代理派生"本次命令专属"的执行代理        &environment_id, // 绑定环境：不同环境的网络策略互相隔离        &registration_id, // 绑定注册号：代理拦截请求时靠它找回主人调用        attribution_token, // 归因 token：每个出站连接都能反查到发起它的工具调用        environment_policy, // 环境网络策略（域名白名单等）挂到执行代理上        fallback_policy_decider, // 策略没覆盖到的请求 → 回调进审批流，而不是默认放行    )    .map_err(|err| { // 派生失败 = 本次命令的网络出口建不起来 → 直接拒绝执行，fail loud        ToolError::Codex(codex_protocol::error::CodexErr::Io(io::Error::other( // 包装成 IO 类错误：网络出口建不起来属于基础设施故障            format!("failed to create execution-scoped network proxy: {err}"), // 错误信息带上根因，方便排查        )))    })?; // ? 提前返回错误——代理没建好，命令绝不带病启动let cancellation_token = CancellationToken::new(); // 审批被拒/超时时的取消信号，会传给执行进程session.services.network_approval.register_call(ActiveNetworkApprovalCall { // 登记在册：代理拦截到请求时靠它找回"主人调用"    registration_id: registration_id.clone(), // 注册号：后续所有网络请求都挂在这个 id 下    turn_id: turn.sub_id.clone(), // 所属 turn：审批事件按 turn 归组展示    trigger, // 触发这次网络审批的工具调用上下文（命令、cwd）    tool_name, // 触发网络访问的工具名（unified_exec/mcp…）：遥测维度    command, // 原始命令文本：弹窗里让用户知道"谁在联网"    environment_id, // 环境 id：审批键的一部分，跨环境不共享记忆    permission_profile, // Managed/Unmanaged 决定能否走"问用户"流程    environments: environments.clone(), // 快照整个执行环境：Guardian 审查时按原环境评估    cancellation_token: cancellation_token.clone(), // 取消信号：审批被拒时用来掐断正在跑的请求}).await; // 登记完成：代理拦截到白名单外请求时就能找回这次调用的全部上下文Ok(Some(ActiveNetworkApproval { // 返回给 orchestrator：命令带着这个代理跑，网络出口被接管    registration_id: Some(registration_id), // 带注册号返回：命令结束后用它结算审批结果    cancellation_token, // 取消句柄交给 orchestrator：拒绝时由它触发进程取消    execution_proxy, // 执行代理本体：命令的出站流量全部穿过它}))

let key = HostApprovalKey::from_request(&request, protocol, environment_id.clone()); // host 小写化 + 协议/端口 → 唯一审批键{    let _commit_guard = self.session_policy_commit_lock.lock().await; // 先拿"策略提交锁"：查缓存和改缓存必须同序，防止持久化与内存状态错位    {        let denied_hosts = self.session_denied_hosts.lock().await; // 先查会话级拒绝记忆（只读锁）        if denied_hosts.contains(&key) { // 本会话被拒过的 host → 直接硬拒，不再问（拒绝是强信号）            return NetworkDecision::deny(REASON_NOT_ALLOWED); // 本会话拒过 → 硬拒，不再弹窗（拒绝是强信号）        }    }    let approved_hosts = self.session_approved_hosts.lock().await; // 再查会话级放行记忆    if approved_hosts.contains(&key) { // 本会话已放行过 → 秒过，零弹窗        return NetworkDecision::Allow; // 本会话已放行过 → 秒过，零弹窗    }}

let resolved = match approval_decision { // 把"人的裁决"翻译成代理能执行的放行语义（AllowOnce/AllowForSession/Deny）    ReviewDecision::Approved | ReviewDecision::ApprovedExecpolicyAmendment { .. } => { // "本次放行"或"命令策略级放行"        if self.session_denied_hosts.lock().await.contains(&key) { // 会话级拒绝记录优先：这次批了，deny 记忆也不作废            // …（把 policy_denial_message 记进 call outcome）…            PendingApprovalDecision::Deny // deny 记忆优先：这次批了，会话级拒绝也不作废        } else { // 没有 deny 记忆 → 正常放行            PendingApprovalDecision::AllowOnce // "本次放行"：只开这一次，下次同 host 还要再问        }    }    ReviewDecision::ApprovedForSession => { // "本会话始终允许"        if self.session_denied_hosts.lock().await.contains(&key) { // 同样先查 deny 记忆            // …（同上：deny 记忆优先）…            PendingApprovalDecision::Deny // deny 记忆优先：这次批了，会话级拒绝也不作废        } else { // 没有 deny 记忆 → 正常放行            self.session_approved_hosts.lock().await.insert(key.clone()); // "始终允许"→ 写入会话白名单，同 host 后续秒过            PendingApprovalDecision::AllowForSession // 写入白名单后放行：同 host 后续请求秒过        }    }

impl Drop for PendingHostApprovalOwner<'_> { // owner=审批代管人：它异常消失时，必须让所有等待者 fail-closed    fn drop(&mut self) { // owner 被销毁（panic/取消/超时）时自动执行——异常路径的兜底        if !self.completed { // 正常 complete() 过就跳过——这里只兜底 panic/取消/超时等异常路径            if self.cancellation.as_ref().and_then(NetworkRequestCancellation::reason) // 取出取消原因枚举 == Some(NetworkRequestCancellationReason::ProcessFinished) {                // 进程自然结束触发的清理不算"审查失败"：直接发布当前裁决，不额外记账                self.publish_and_remove(self.decision_on_drop); // 正常清理：发布当前裁决并摘除 pending，唤醒等待者                return; // 进程自然结束不算审查失败 → 不额外记账直接返回            }            // …（中间省略：断连超时记账——把"审批未完成请求就断开"写进 call outcome）…            self.cancel_execution_if_denied(self.decision_on_drop); // 默认裁决是 Deny → 顺手取消执行进程，别让它继续跑            self.publish_and_remove(self.decision_on_drop); // 唤醒等待者并摘除这一代 pending：新请求不能挂到旧审批上        }    }}

网络请求审批全路径（handle_inline_policy_request）

▼

▼

▼

▼

▼