P0 人类审批插件 — 高风险工具执行前等待人类确认(HITL)。
拦截 before_tool 事件,对指定工具(默认 "shell")的非白名单命令
广播 {:approval_required, approval_map} 事件并阻止工具执行。
审批信息直接以 map 形式内嵌在事件 payload 中,无需独立 struct:
%{
id: "a1b2c3d4",
tool: "shell",
args: %{"command" => "rm /tmp/test"},
session_id: "...",
hint: "请回复「确认执行:rm /tmp/test」...",
requested_at: 1_700_000_000_000
}两种审批模式(共存)
模式 A — 外部 API 审批(管理后台推荐)
HumanApproval 拦截 {:before_tool, "shell", args}
│ 广播 {:approval_required, approval_map}
│ block_tool → Agent 回到 idle
│
外部系统收到事件,管理员审批
│
向 Pipeline 发送 {:tool_approved, approval_id} 事件
└── 放行 → 命令进入 pending_approvals,下次 before_tool 自动通过模式 B — 用户 re-prompt 审批(Bot 对话场景)
用户: "帮我删除 /tmp/test"
│ block_tool,hint 提示用户回复确认前缀
│
用户: "确认执行:rm /tmp/test"
│ before_prompt 识别 confirm_prefix → 命令进入 pending_approvals
│ 下次 before_tool 自动放行配置
{CMDC.Plugin.Builtin.HumanApproval,
require_approval_for: ["shell"], # 需要审批的工具名列表
safe_commands: [ # 免审批命令(正则或字符串前缀)
~r/^curl\s/,
~r/^ls(\s|$)/,
~r/^pwd$/,
"echo "
],
confirm_prefix: "确认执行:", # 模式 B 的确认前缀
timeout_ms: 120_000 # 审批超时(默认 2 分钟,0 表示不超时)
}