Pi Agent 与 Claude 互联时如何隔离账号权限边界？

Pi Agent 与 Claude Code 互联时，最重要的原则是把对方发来的消息视为“不可信 Peer 输入”，而不是用户授权。pi-claude-link 通过本地 Unix Socket 实现双向消息，Socket 权限为 0600、目录权限为 0700，能隔离其他系统用户，却不能隔离同一用户账号下的进程。要建立可靠边界，还必须限制入站消息、工具权限、项目目录、凭据和外部输入来源。

互联改变了什么

没有互联时，Pi 与 Claude Code 各自接收用户输入并执行工具。启用双向通信后，一个 Agent 的输出可以成为另一个 Agent 的新输入，空闲会话可能立即启动，忙碌会话也可能被中途引导。

这条链路带来协作效率，也增加了一条间接控制路径：

用户 → Pi → 跨会话消息 → Claude → 文件与 Shell 工具
用户 → Claude → 跨会话消息 → Pi → 扩展与本地工具

如果接收方把 Peer 消息当作用户批准，发送方就可能间接获得接收方的更高权限。

项目声明的信任模型

pi-claude-link 的安全文档明确说明：

• 安全边界是操作系统用户，而不是单个 Agent 会话。
• 同一用户运行的任意进程都可能访问本地通信端点。
• 跨 Agent 消息是 Peer 输入，不具备用户授权地位。
• 发送者的名称和 from 字段仅用于显示与路由，没有经过身份认证。
• 不应把外部自动化输入直接接到这条链路。

这些限制不是实现缺陷的简单列表，而是部署时必须接受并补足的边界。

第一层：操作系统账号隔离

0600 Socket 和 0700 目录可以阻止其他普通用户访问，但同一账号下的编辑器插件、构建脚本、浏览器工具和恶意程序仍处在同一信任域。

如果两个 Agent 的数据敏感度不同，应使用独立系统账号、容器或虚拟机。例如工作项目使用受管账号运行 Claude Code，个人 Pi 环境运行在另一个账号中。跨边界协作通过受控文件或审查后的补丁完成，而不是共享本地 Socket。

第二层：入站消息审批

Claude 侧可以将 crossSessionInbound 设置为 hold，让每条入站消息等待人工批准：

{
  "crossSessionInbound": "hold"
}

对于开启自动批准、拥有生产凭据或能够运行危险命令的会话，hold 应是默认选择。accept 适合隔离良好、任务边界明确的临时环境；refuse 则完全关闭入站消息。

审批时不能只看发送者显示名，因为该字段未认证。应阅读完整任务内容，并确认它符合当前会话目标。

第三层：工具最小权限

接收 Peer 消息的 Agent 不应同时拥有不受限 Shell、全盘读写和生产网络访问。按任务拆分工具：

任务	建议开放	建议关闭
代码解释	项目只读、搜索	写入、网络、部署
代码审查	差异读取、测试只读报告	直接合并、推送
生成补丁	隔离工作树写入、测试	主分支、生产凭据
发布部署	人工批准后的专用命令	任意 Shell 和任意目标

权限应由操作系统、容器和工具配置强制执行，不能只依赖提示词。

第四层：项目目录隔离

Pi 和 Claude 不要同时写入同一工作树。两个 Agent 可能基于不同文件状态生成修改，彼此覆盖或把未提交内容当成自己的成果。

推荐为每个执行任务建立独立 Git 工作树或临时副本。Peer 消息只传递任务 ID、提交 ID 和必要上下文，最终通过补丁、提交或明确的工件交接。

第五层：凭据隔离

Agent 子进程通常继承启动环境。即使任务与云平台无关，环境变量中也可能存在 API Key、SSH Agent、数据库密码和包仓库令牌。

启动互联会话前应：

• 构造最小环境变量集合。
• 使用独立的低权限 API Key。
• 限制 SSH Agent 转发和云凭据缓存。
• 避免把个人订阅 Token 交给第三方扩展。
• 为测试环境使用短期、可撤销凭据。

Peer 消息不能成为读取或发送凭据的理由。

不要依赖发送者名称做授权

项目文档指出，from 和显示名由发送方提供，仅用于路由与展示。一个同用户进程可能注册与可信会话相似的名称。

因此，不要编写“来自 reviewer 的消息可以自动执行”这类规则。授权应绑定本地不可伪造的上下文，例如人工审批、受控进程启动、固定 Socket 所有者或隔离环境中的能力令牌。

防止 Prompt Injection 横向移动

Pi 可能读取仓库文档、网页、Issue 或构建输出，其中的恶意文本可以诱导 Pi 向 Claude 发送危险指令。Claude 也可能把类似内容再传回 Pi，形成跨会话放大。

应在消息中明确标注来源，并让接收方把其视为数据：

{
  "origin": "peer",
  "task": "review diff only",
  "authority": "none",
  "content": "..."
}

真正的安全控制仍应在工具边界。模型即使误判内容，也无法越过只读目录和禁用网络等限制。

不要连接外部自动化输入

安全文档明确建议不要把 Webhook、队列、抓取内容或邮件直接接入扩展。否则任何能影响这些输入的人，都可能把指令送进拥有本地工具权限的 Agent。

如果业务确实需要自动化，应增加独立网关：

1. 验证发送者和请求签名。
2. 把外部内容规范化为受限任务类型。
3. 拒绝任意提示和任意 Shell 参数。
4. 在隔离环境中执行。
5. 高风险动作等待人工批准。
6. 记录审计事件和结果。

消息协议需要限制什么

• 最大消息大小，防止上下文和内存耗尽。
• 最大等待时间，避免 ask 永久阻塞。
• 每个发送者的速率和并发上限。
• 最大往返次数，防止两个 Agent 无限对话。
• 允许的消息类型和字段。
• 任务 ID 与去重键，避免重复执行。

错误和超时应终止当前委派，不应自动把完整任务重新发送多次。

调试日志也可能越界

项目支持将调试日志写入临时目录。开启调试前，应确认日志不会包含提示、源码、账号标识或凭据，并检查文件权限与清理周期。

共享机器上的临时目录不是秘密存储。生产使用应默认关闭详细日志，必要时写入受保护目录并统一脱敏。

建立单向责任模型

最容易治理的协作方式是一方负责计划与审查，另一方负责封闭执行。例如 Pi 只发送“审查这个补丁”的只读任务，Claude 返回结构化发现；或 Claude 提交明确补丁任务，Pi 在隔离工作树中修改并返回真实差异。

不要让双方都拥有无边界的计划、委派、写入和发布能力。每次任务应只有一个最终责任 Agent。

推荐部署配置

1. 先在无敏感凭据的临时仓库启用互联。
2. Claude 侧设置 crossSessionInbound: "hold"。
3. 两边使用只读工具完成第一轮测试。
4. 为写入任务创建独立工作树。
5. 限制网络、环境变量、并发和委派深度。
6. 只有在审计通过后才开放有限写入。
7. 生产操作继续保留独立人工门禁。

如何验证边界有效

• 伪造可信显示名，确认不会自动获批。
• 发送要求读取项目外文件的消息，确认被拒绝。
• 发送要求泄露环境变量的消息，确认工具无法执行。
• 模拟重复、超长和循环消息，确认触发限制。
• 结束会话后检查 Socket 与注册文件是否清理。
• 让两个会话并发修改，确认工作树彼此隔离。
• 检查日志中没有源码、Token 和敏感提示。

常见问题

Unix Socket 是本地的，是否天然安全

不是。它减少了网络暴露，但同一操作系统用户的进程仍能接触该边界。

收到 Claude 发来的消息能否直接执行

不应默认执行。它是 Peer 输入，不代表用户批准，应结合入站门禁和工具权限判断。

显示名能否证明消息来自指定 Agent

不能。项目明确说明显示身份是建议性字段，并未认证。

可以把邮件和 Webhook 转发给互联 Agent 吗

不应直接转发。外部输入需要签名验证、任务白名单、沙箱和人工门禁。

总结

Pi Agent 与 Claude 互联的安全边界不是“两个会话”，而是操作系统用户和双方实际拥有的工具权限。0600 Socket、0700 目录和 Peer 标记是良好基础，但仍要使用入站 hold、独立工作树、最小环境变量、凭据隔离和外部输入网关。最关键的是：跨 Agent 消息永远不等于用户授权，发送者显示名也不能成为权限依据。