Show HN: 为 Claude Code 智能体设立“警察部门”

背景

随着 AI 编码助手（如 Claude Code）能力的增强，它们不再仅仅是代码补全工具，而是能够读取文件、执行 Shell 命令并动态生成子智能体（subagents）的自主代理。这种能力虽然强大，但也带来了显著的安全与可观测性挑战。

在现有的工作流中，开发者通常只能通过滚动查看对话转录文本来了解智能体实际做了什么。然而，这种事后审查存在两个致命缺陷：

1. 被拒绝的操作不可见：Claude Code 会在用户层面拦截被拒绝的请求（如权限不足），这些操作根本不会出现在对话转录中，导致开发者无法知晓智能体曾尝试执行哪些敏感操作。
2. 信息碎片化：当智能体生成多个子智能体时，追踪每个子智能体的具体行为变得极其复杂。

为了解决这一“黑盒”问题，开发者推出了一款名为 agent-pd 的工具。它并非试图阻止智能体的行为（那是防火墙或沙箱的工作），而是作为一个“执法记录仪”和“警察扫描仪”，忠实记录每一个工具调用和权限事件，并提供确定性检测器来识别违规操作。

核心内容

agent-pd 是一个基于 Python 的工具，旨在为 Claude Code 提供全面的审计与监控能力。其核心设计理念是“记录一切，事后分析”，而非实时阻断。

1. 工作原理：Hook 与审计日志

agent-pd 通过安装一个全局 Hook 来工作。该 Hook 注册在 ~/.claude/settings.json 中，监听以下事件：

• PostToolUse：工具调用后
• PermissionDenied：权限被拒绝时
• SubagentStart / SubagentStop：子智能体启动与结束

每当触发上述事件，Hook 会将标准化的、哈希链式（hash-chained）的一条记录追加到每个会话的审计日志文件（.jsonl 格式）中。

• 零阻塞：Hook 设计为“愚蠢且崩溃安全”的记录器，始终返回退出码 0，确保不会阻塞 Claude Code 的正常执行，也不会丢失任何事件。
• 完整性：日志包含被拒绝的调用，这是仅解析转录文本无法获取的关键信息。

2. 六大确定性检测器

agent-pd 内置了六个确定性的检测规则，用于分析审计日志。这些检测器运行成本为零（不消耗 LLM Token），完全基于 Python 逻辑：

1. Denied calls：被拒绝的调用尝试。
2. Out-of-scope：访问项目范围之外的文件（如 /tmp 或系统目录）。
3. Credential access：访问敏感凭证文件（如 ~/.ssh/id_rsa）。
4. Permission bypass：尝试绕过权限限制（如使用 sudo 或执行 curl | sh 等高危命令）。
5. Self-permissioning：智能体修改自身配置文件以获取额外权限。
6. Disallowed tools：使用了未在声明允许列表中的工具。
7. Off-task work：偏离了智能体简报（brief）中指定的任务范围（此功能可选通过 LLM 增强）。

3. 核心 CLI 功能

• pd list：列出所有会话。会话不以 UUID 标识，而是显示项目目录、最后活跃时间及首个用户提示词（作为标题），便于人工识别。
• pd report：生成法医式的违规报告。针对最近一次会话，输出违规严重程度、置信度及引用证据。
• pd watch：实时“警察扫描仪”。像 tail -f 一样流式输出新活动。支持 --all 合并多个会话的监控，支持 --replay 回放历史 backlog。
• pd verify：验证审计日志的哈希链完整性，检测日志是否被篡改或截断。
• pd judge（可选）：集成 Anthropic SDK，利用 LLM 进行更复杂的语义分析（如判断是否偏离任务），但这需要消耗 Token。

4. 架构与安全设计

• Tamper-evident（防篡改）：审计日志采用哈希链结构，确保任何对日志的修改都能被检测到。
• 非沙箱：文档明确指出，agent-pd 不是沙箱。如果需要阻止动作，仍需依赖 Claude Code 的权限提示或操作系统沙箱。agent-pd 的作用是“提高标准”并提供事后追责能力。
• 子智能体支持：不仅监控主智能体，还通过 Hook 事件验证并监控由 Claude Code 动态 Workflow 工具生成的子智能体。

关键要点

• 填补监控空白：传统转录日志无法捕获被拒绝的操作，agent-pd 通过底层 Hook 捕获所有事件（包括被拒绝的），提供了完整的行为视图。
• 零 Token 成本检测：核心的六项违规检测完全基于 Python 逻辑，不依赖大模型推理，因此运行速度快且无额外 API 费用。
• 会话语义化标识：通过从日志中提取项目目录和首个提示词，使 pd list 的输出对人类友好，解决了 UUID 难以记忆的问题，且支持对现有会话进行回溯分析。
• 实时与离线兼备：pd watch 提供实时流式监控，pd report 提供离线法医式分析，两者结合覆盖了即时响应与事后审计两种场景。
• 防篡改审计：哈希链日志结构确保了审计记录的真实性，配合可选的离线追加只写存储（append-only sink），进一步增强了证据的可信度。
• 演示真实性：项目提供的 Demo 脚本（examples/demo-sessions.sh）展示了真实引擎在三个并发会话、多个子智能体环境下的表现，包括真实的违规标记（如 sudo 提权、SSH 密钥访问、自我权限提升等）。

意义与影响

agent-pd 的出现标志着 AI 智能体开发从“功能优先”向“安全与可观测性优先”的转变。

1. 建立信任机制：在企业级或生产环境中，允许 AI 智能体执行 Shell 命令和读写文件是高风险行为。agent-pd 提供了一种低成本、高透明度的审计方案，使得开发者和管理员能够确信智能体的行为在可控范围内，从而增强对 AI 代理的信任。
2. 细化安全边界：现有的安全控制往往过于粗放（如完全禁止 Shell 访问）。agent-pd 允许更细粒度的策略：允许智能体工作，但实时监控其是否越界、是否尝试提权或访问敏感数据。这种“监控而非阻断”的模式更适合需要高度自主性的 AI 编码助手。
3. 标准化 Agent 审计：通过提供结构化的日志格式和标准化的检测器，agent-pd 为 AI 智能体的行为审计建立了一种事实上的标准。它展示了如何将传统的系统安全概念（如审计日志、哈希校验、权限最小化）应用于 LLM 代理工作流。
4. 开发者体验提升：对于开发者而言，pd watch 和 pd report 极大地降低了调试和审查 AI 行为的认知负荷。不再需要手动在冗长的转录文本中搜索可疑命令，而是可以直接查看结构化的违规报告。

总之，agent-pd 是 AI 安全工程领域的一个实用主义创新。它承认了 AI 智能体的自主性需求，同时通过技术手段解决了由此带来的不可见性和潜在风险，为构建更可靠、更透明的 AI 辅助开发工作流提供了重要基础设施。