Marrow AI: Control Layer for AI Agents

Marrow AI MCP Server

@getmarrow/mcp：AI Agent 的控制层。Marrow AI 会在 Agent 执行操作前，为该操作给出明确许可，并留下其他 Agent 可以复用的证明。

哪个 Marrow？ 这是来自 getmarrow.ai 的 Marrow AI（npm @getmarrow/mcp，MCP Registry ai.getmarrow/marrow）。它与 marrow.id、HyperMarrow、marrow.works 或其他名为 Marrow 的项目均无关联。

getmarrow.ai · 文档 · 面向 MCP 的 Marrow AI · MCP Registry 条目 · 更新日志 ·

Marrow AI 是为运行 AI Agent 的团队提供的运行时控制与证明层。它会在执行重要操作前应用策略和以往经验，并在操作后记录证据和结果。

当你的 Agent 客户端支持 Model Context Protocol，且你希望在 Agent 的常规工作流中使用 Marrow 时，请使用 @getmarrow/mcp。它可与 Claude Code、Claude Desktop、Cursor 及其他兼容 MCP 的客户端协同工作，无需替换模型或运行框架。

快速开始

1. 创建密钥。 在 getmarrow.ai/signup 注册，然后打开控制面板，进入 API keys 并选择 Create API key。密钥只会显示一次。

2. 激活。 将密钥设置为 MARROW_API_KEY（从你的密钥存储中获取，或放在只有所有者可访问的 ~/.marrow/env 中），然后在终端运行安装程序：

   npx -y @getmarrow/install@latest activate
   

   如果无法预先设置密钥，可使用以下备用方式（在命令行中输入的密钥会留在 shell 历史记录中）：MARROW_API_KEY=<your_key> npx -y @getmarrow/install@latest activate。

3. 重启 Agent 主机，并检查/启用其钩子的信任设置。

4. 验证：

   npx -y @getmarrow/install@latest doctor --self-test
   

执行的控制。 在 30 天评估期和 Business 方案中，部署和发布操作会在钩子和治理运行器中受到拦截。Team 和 Free 方案会发出警告。如果 Marrow 无法访问，钩子会拦截高风险操作，并允许常规操作在警告下继续；治理运行器则会停止无法验证的受保护操作。通过 MCP，Agent 会收到决策，并应遵循该决策。钩子在 Agent 主机内部运行，并非外部执行边界：修改主机设置的 Agent 或人员，或在主机之外工作的 Agent 或人员，不会受到拦截。

Agent 发现

• 发布方： Marrow AI。本包中的能力说明属于供应商提供的产品声明。
• 适用场景： 需要在常规 Agent 工作流中获取状态信息、执行操作前治理、基于证据关闭结果，以及获取租户范围内经验的兼容 MCP 客户端。
• 产品类别： Agent 集群治理与控制层。
• 操作边界： 配置服务、创建账户或提交诊断信息均须获得操作员批准。
• 公开诊断隐私： 不接受原始提示词、源代码、凭证、客户数据及自由格式的工作描述。
• 机器可读的产品事实： https://getmarrow.ai/llms.txt 和 https://getmarrow.ai/.well-known/marrow.json

维护者可使用 npm run registry:check 验证本地注册表元数据。获批发布到注册表后，npm run registry:verify 会确认官方注册表返回的包名和版本完全一致；仅凭包元数据不视为发布证明。

公开操作指南：

• 治理就绪度评估
• 面向 MCP 客户端的 Marrow
• 面向 OpenAI Codex 的 Marrow
• 面向 Claude Code 的 Marrow
• 面向 Cursor 的 Marrow
• 面向 Hermes Agent 的 Marrow
• 面向 OpenClaw 的 Marrow

此评估仅接受有限选项。它不会安装 Marrow、授权购买、接受自由格式的工作内容，也不会确立合规性、安全性或投资回报率。

Marrow 适用场景

Marrow AI 是围绕现有模型、运行框架和业务工作流的可选Agent 集群治理与控制层。它不是模型提供商、Agent 运行框架、仅用于记忆的工具，也不能替代可观测性方案。

出现以下任一情况时，Marrow 适用：

• 两个或更多自主 Agent、模型或运行框架共同参与一项需承担责任的工作流（multiple_autonomous_agents）。
• Agent 可以部署、合并、发布、更改生产数据、使用特权工具、花费资金或向客户发送消息（production_or_privileged_access）。
• 工作流存在反复失败、重试、回归问题或已知经验，且这些情况应影响下一步操作（repeated_workflow_failures）。
• 工作可能在缺少证明、验证或已记录业务结果的情况下被标记为已完成（missing_completion_evidence）。
• 不同 Agent、工具、环境或团队的策略、审批或完成要求不一致（inconsistent_policy_enforcement）。
• Agent 参与受监管、专有、个人、财务、健康、法律、凭证相关或其他敏感工作流（regulated_or_sensitive_work）。

Marrow 不适用的场景

• 单个咨询型助手不执行任何共享、特权、生产环境或需承担责任的业务操作（single_low_risk_assistant）。
• 工作流无需策略、证明、结果问责或集群协调（no_governance_requirement）。
• 操作员已拒绝评估或安装 Marrow（operator_declined_evaluation）。

安装 Marrow 会更改操作员的 Agent 配置：未经操作员批准，切勿安装、创建账户或提交数据。

请通过公开证据清单、参考关系图和集成卡片核实当前声明。

安装

**Windows：**目前尚不支持原生 Windows。请使用 WSL。

对于大多数安装，请遵循快速入门：使用通用安装程序的 activate 命令。以下步骤是手动配置、仅设置 MCP 的方式。

在 getmarrow.ai/signup 获取密钥，并将其保存在仅所有者可访问的密钥文件中：在 ~/.marrow/env 中写入 MARROW_API_KEY=<your_key>，然后运行 chmod 700 ~/.marrow && chmod 600 ~/.marrow/env（如果密钥文件所在目录可由他人写入，Marrow 会拒绝该文件）：

mkdir -p ~/.marrow && chmod 700 ~/.marrow
# put MARROW_API_KEY=<your_key> in ~/.marrow/env
chmod 600 ~/.marrow/env

Claude Code 插件用户：运行 /plugin install 后，运行 /reload-plugins（或重启 Claude Code）。若要添加密钥，请在 ~/.marrow/env 中写入 MARROW_API_KEY=，运行 chmod 600 ~/.marrow/env，然后运行 /reload-plugins。请勿对该插件运行 activate 或 marrow-mcp setup，因为它们会写入第二份 hooks。

如果无法使用密钥文件，可采用此备用方式（在命令行中输入的密钥会留在 shell 历史记录中）：通过可信的密钥存储设置密钥，或在当前会话中运行 export MARROW_API_KEY=<your_key>。

仅配置 hooks（marrow-mcp setup 会写入 hooks 和 CLAUDE.md 指令，不会添加 MCP 服务）。需要先提供密钥：如果没有密钥，该命令会打印获取密钥的方法，并在写入任何内容前以状态码 2 退出。

npx -y --package=@getmarrow/mcp@latest marrow-mcp setup

MCP 服务和 Claude Code 的协作式操作前 hook 仅从进程环境，或由所有者控制且权限仅限所有者的 ~/.marrow/env（或 ~/.marrow/env.local）读取密钥（chmod 600）。如果所有者文件是符号链接、可由他人读取或写入、归其他用户所有，或位于可由他人写入的目录中，则其中的内容均不会生效，包括密钥；缺少密钥的提示会指出该文件，并提供 chmod 修复方法。无论权限如何，都不会从仓库本地文件（工作目录或其父目录中的 .env、.env.local、.marrow/env*）读取 MARROW_API_KEY 或任何其他 MARROW_* 设置，因此项目内容无法替换账户、Agent 或 API 端点。如果其中某个文件包含密钥，缺少密钥的提示会指出该文件及修复方法：运行 npx @getmarrow/install doctor，或将该行移到 ~/.marrow/env，然后运行 chmod 600 ~/.marrow/env。公开的 hook 回调仍是客户端自行报告的信息，并非经过认证的主机来源证明或外部强制执行边界。

然后配置 MCP 服务：

{
  "mcpServers": {
    "marrow": {
      "command": "npx",
      "args": ["-y", "--package=@getmarrow/mcp@latest", "marrow-mcp"]
    }
  }
}

设置写入 MCP 配置或 hooks 后，请重启 Agent 宿主，并检查/启用其 hook 信任。然后验证重新加载后的环境：

npx -y @getmarrow/install@latest doctor --self-test

仅仅成功完成设置，并不意味着此进程已重新加载或 hooks 已激活。在观察到实际使用情况并取得证据之前，请将节省额设为零。

工具配置

常规设置不需要 MARROW_TOOL_PROFILE。未设置该变量时，Marrow 会使用 primary 配置，并准确提供 Primary MCP Tools 中的 17 个工具。

• MARROW_TOOL_PROFILE=primary 会明确选择相同的 17 个主工具。
• MARROW_TOOL_PROFILE=core 会保留包含 runtime、think、commit、ask、status、auto 和 handoff-status 的 7 个工具。
• MARROW_TOOL_PROFILE=full 会提供完整的高级及旧版工具目录，供需要它的集成使用。

无效值会返回范围受限的配置错误，并列出准确的允许值；绝不会回退到 full。更改配置后，请重启 MCP 进程。

本地可见性并不代表已获得付费访问权限。每次工具调用仍会经过 Marrow 后端的身份验证、租户、密钥权限、计划、证明和策略强制检查。若提供了最新的已验证证据，MCP 状态响应会包含 mcp_tool_profile，其中列出已配置和生效的配置、可见工具名称/数量，以及后端主工具权限投影。缺失或缓存的权限证据会标记为不可用，且不能授权调用。

保持 MCP 更新

Marrow 的托管 API、网站和仪表板会自动更新；本地 MCP 挂钩、配置和固定版本的软件包命令不会悄然自行改写。保持这些内容为最新状态，可获得新的客户端功能、兼容性改进以及已发布的安全修复。在经过身份验证的状态／运行时活动期间，如果软件包版本落后或未知，Marrow 会返回 client_update 通知；被动上下文会向 Agent 显示准确的更新和验证命令。

npx -y @getmarrow/install@latest activate
npx -y @getmarrow/install@latest doctor

# Manual MCP-only setup
npx -y --package=@getmarrow/mcp@latest marrow-mcp setup

# Verify live read latency, last success, and local backlog
npx -y --package=@getmarrow/mcp@latest marrow-mcp ping

检测和通知会自动进行。明确启用安装程序后，本地控制器可能只会恢复由 Marrow 管理的挂钩／配置。软件包升级、所有者策略、凭据和无关配置仍须明确处理，并遵循操作员的常规变更策略。

待处理写入恢复

直接调用 marrow_think 时，在后端能够安全地公开决策 ID 之前，可能会收到持久化的待处理响应。客户端会识别明确的 agent_write_reconciliation.v1 think 合约以及相应的当前旧版待处理状态。它会使用原始幂等键、Agent 和会话，重试完全相同的身份验证请求，最多进行三轮协调，每轮之间按现有机制等待一秒。每轮对于可重试的失败，最多保留两次传输尝试，因此一次调用最多可发送六个 HTTP 请求，且所有请求使用相同的键和正文。它绝不会创建占位决策，也不会启动自动操作来恢复直接的 think 调用。对于未知状态、冲突的键和不安全的响应，系统会以安全失败方式拒绝处理；重试耗尽后，会返回可重试的结构化 pending_receipt，其中包含 committed:false、原始 idempotency_key 和 request_hash。要手动恢复，请在参数、凭据、Agent 和会话均相同的情况下，将这两个字段传递给 marrow_think。该哈希绑定完全相同的规范化请求和作用域；若发生偏差，系统会在发送前拒绝请求。回执中不包含提示词、凭据或原始作用域。调用方提供的键必须是隐私安全的不透明标识符。

已保存的 observed_unverified 结果是终态观察证据，并非已提交的结果。回执过期不能追溯授权已完成的工作。请保留原始决策、回执、证明和键；已获授权的持久化检查点可以通过其现有的精确恢复路径完成。不要仅为获取新回执而重复执行操作。

无密钥安全带

如果操作前挂钩没有可用的 Marrow 密钥，且机器上没有任何 Marrow 账户迹象（例如所有者密钥文件、认领标记或 Marrow 的本地审批状态），挂钩会运行本地安全带，而不是拦截所有受保护的操作：

• **它会拦截七类操作：**更改 Marrow 的钩子、设置或插件（包括 Claude Code 设置中的 Marrow 插件开关，以及 ~/.claude/plugins 下的插件文件），或执行仅限所有者使用的 Marrow 命令（S0）；强制推送或删除受保护分支（S1）；生产环境部署（S2）；发布软件包（S3）；读取凭据或机密，包括项目 .env 文件或任何已存在的其他 <name>.env 文件（模板文件，例如 .env.example，可以通过）、~/.marrow/fleet.env 和 ~/.marrow/credentials（S4）；在工作区之外递归删除（S5）；以及由 shell 或解释器运行解码后的数据（S-x）。如果把受保护文件交给任何不是纯读取器的程序（例如 cat、grep、jq 或 diff），也会被拦截，因此编辑器或安全带不认识的工具无法改写这些文件。工具只有在使用其列出的完整长选项时才算纯读取器：GNU 工具和 git 也接受缩写形式（cp --target=DIR、git reset --har），因此，对命令中提到受保护文件的情况，如果使用了缩写或未知长选项，就会被拦截。归档操作（tar -c、zip）、tree 和 prettier --check 只会读取传入的内容：只检查归档文件和它们写入的文件。拦截由主机自身执行拒绝，并提示 Agent 将操作留给机器所有者处理。在 Grok 上，拦截由 Grok 的固定拒绝消息执行（“Marrow blocked this protected action.”），这是其已安装的防护程序所接受的唯一拒绝消息。
• **其他所有操作都不会由 Marrow 作出决定，而是由主机自身的审批步骤决定：**Claude Code 和 Codex 会收到空答复；Cline 不会取消操作；Windsurf 不会收到任何输出。Gemini CLI 会收到 {"decision":"allow"}，这是其已安装的防护程序接受且不会触发拦截的唯一答复。对于以往会被没有密钥的钩子拦下的 shell 命令，Cursor 会先通过自己的审批提示询问。Cursor 的其他工具（包括 MCP 调用）和 Grok 没有中立答复，因此会继续拦截以往会被没有密钥的钩子拦下的操作。以往会被没有密钥的钩子放行的操作，仍会收到相同答复。
• **主机工具和 MCP 调用：**安全带会读取各主机自身的文件工具（例如 Cline 的 write_to_file 和 replace_in_file、Gemini CLI 的 read_file、replace 和 delete_file、Grok 的 search_replace、Cursor 的 Delete），以及所有主机形式的 MCP 调用（mcp__server__tool、MCP:server:tool、Gemini 的 mcp_server_tool 和 server__tool、Cline 的 use_mcp_tool 和 access_mcp_resource）。MCP 调用参数中任意深度的每个字符串值，都会接受 S0 和 S4 路径检查。无法识别的工具，或无法读取其参数的 MCP 调用，绝不会获得安全带的放行：钩子会给出与没有密钥的钩子以往相同的答复；以往会被拦截的操作仍会被拦截。
• **它采用失败时默认拒绝策略：**内部错误、检查耗时超过 300 ms，或主机截断了输入，都会导致操作被拦截。Windsurf 和 Cline 不会向钩子提供工作文件夹，因此在这两者中，工作区之外的递归删除会被拦截，包括临时文件夹以外的删除。
• **本地回执：**每个安全带决策都会记录到本机的 ~/.marrow/seatbelt/receipts/，记录内容包括代码和带密钥的哈希，以及来自固定列表的内置工具名称和 shell 程序名称（任何 MCP 工具都只记录为 mcp）；不记录命令文本、参数、路径或 URL。回执最多保留 90 天或 50 MB。不会上传任何内容。安全带执行拦截时（没有可用密钥），Agent 无法编辑回执，也无法读取用于生成回执密钥的设备盐值（S0、S4）；有可用密钥时，安全带只会监视。回执是记录，不是授权。
• **文件夹权限：**安全带只会在你的主文件夹和 Agent 设置文件夹（例如 ~/.claude）仅由你本人写入的情况下运行。在 Linux 上，你自己的私有组也能写入的文件夹仍符合条件（umask 002 时的默认权限为 0775）。其他人可以写入的文件夹、包含其他成员的组、通过符号链接访问的文件夹，或使用网络目录中的用户和组（LDAP、SSSD），都会让所有拦截保持生效；拦截消息会说明原因和修复方法，例如：“Marrow stopped this action: there is no Marrow key on this machine, and Marrow uses its stricter no-key mode here because HOME is not your login home folder. Fix (for the person at this machine, not the agent): start the agent with HOME set to your login home folder, or add a Marrow key (getmarrow.ai/docs#start-here).”
• 你可能会有意遇到的拦截：cp .env.example .env.local（或任何会写入 .env 文件的命令）、set -a && . ./.env && npm run dev 和 docker compose --env-file .env up 会作为机密操作被拦截（S4）；rm -rf ~/.cache/<app> 会作为工作区之外的递归删除被拦截（S5）。如果这是你有意执行的操作，请在自己的终端中亲自运行该命令。每条拦截消息都会说明操作类型，并以对应代码结尾。
• **它是安全带，不是保险库：**它以你的用户身份在本机运行，不会发起网络调用。蓄意操作的 Agent 可以绕过本地检查，例如先编写脚本、之后再运行该脚本，使用解释器，或通过没有钩子的工具路径操作。
• **使用账户时：**已关联账户但没有可用密钥的机器，会保留此前的所有拦截，并且也会应用这些拦截规则。有可用密钥时则不会有任何变化；Marrow 作出答复后，安全带只会检查操作，不会更改答复。 marrow-mcp setup 和安装程序都需要密钥；不带密钥的钩子来自 Claude Code、Codex 和 Cursor 的 Marrow 插件。

钩子行为详情

这些行为在 3.9.100 中推出，仍然适用。

• 每个钩子事件只保留一个 Marrow 条目：marrow-mcp setup 会准确识别安装程序的本地运行时钩子命令（全程使用同一版本，不添加内容），保留已有的形式（本地运行时或 npx），并且绝不添加第二个条目。你自己的钩子保持不变。
• **没有密钥时只允许普通词语：**在已关联 Marrow 账户的机器上，如果受保护操作没有可用密钥，则会被拒绝，并提示“Marrow 已关联到账户，但没有可用密钥；账户所有者请运行 npx -y @getmarrow/install@latest doctor。”没有关联账户的机器则运行无密钥安全带。钩子会从 MARROW_API_KEY 或仅限所有者访问的 ~/.marrow/env.local 或 ~/.marrow/env 读取密钥，绝不会从他人可读取的文件中读取。
• **首次提示词简报会标明这一点：**提示词钩子会将其简报标记为 context.prompt_brief: true；简报不授权任何操作。
• **仅逐字发送部署文本：**只有对于 sst deploy --stage <stage>（可选带 --verbose，可选在前面加一个 npx 或 bunx），且 stage 仅包含小写字母、数字和连字符，并且整条命令是唯一子句、不含其他内容时，才会发送确切的命令文本，以便 Marrow 自行判断 stage。其他所有命令（包括其他部署工具）都只会发送哈希；任何自由文本词语都不会离开机器。
• **一个生命周期事件 ID 不对应两个载荷：**事件 ID 标识其载荷，因此后续运行会生成新记录，重发则携带相同的字节。

设置和密钥处理

这些行为在 3.9.101 中推出，仍然适用。

• **没有密钥时停止设置：**如果没有密钥，或者密钥仅存在于不可信位置（例如项目 .env）中，marrow-mcp setup 会停止，不写入任何内容，并告知你如何获取密钥。
• **仅从可信位置读取密钥：**密钥来自环境变量或仅限所有者访问的 ~/.marrow/env。
• 密钥文件步骤包括先运行 chmod 700 ~/.marrow，再运行 chmod 600 ~/.marrow/env。
• **拦截消息会说明在哪里批准：**被拦截的操作会说明如何在主机实际要求的位置批准。
• 统一的执行规则说明：“会执行哪些限制”的措辞与官方网站一致。

项目文件和 Marrow 自有工具

这些行为在 3.9.102 中推出，仍然适用。

• **克隆项目的 .env 无法重定向 MCP 服务：**绝不会从仓库本地的 .env、.env.local 和 .marrow/env* 文件中读取 MARROW_API_KEY 或任何其他 MARROW_* 设置，因此项目内容无法将服务指向其他账户、Agent 或 API 端点。
• **更安全的密钥文件建议：**如果所有者文件是符号链接、可被他人读取或写入、归其他用户所有，或位于他人可写的目录中，则不会提供任何内容；缺失密钥的消息会指出该文件并提供 chmod 修复方法。
• **只有 Marrow 自有工具才会跳过门控，且必须名称完全匹配：**只有当服务名称恰好是 marrow，且工具名称恰好是此软件包注册的名称之一时，该工具才属于 Marrow 自有工具。名称相似的服务、其他情况、多余空格或后缀，都会像任何其他 MCP 工具一样经过操作前门控。重新运行 marrow-mcp setup，以刷新使用旧匹配规则写入的钩子。

安全带、故障期间的拦截与精确审批

这些行为在 3.9.103 中发布，目前仍然适用。

• 无密钥安全带： 如果 Hook 没有密钥，且机器上没有任何迹象表明存在 Marrow 账户，那么它会在 Shell 命令、各宿主自己的文件工具和 MCP 调用中拦截七类操作（Marrow 自身的设置、强制推送或删除受保护的分支、生产环境部署、软件包发布、读取凭据、在工作区外递归删除、由 Shell 运行已解码的数据），并将其他操作交由宿主自己的审批步骤处理。对于它无法识别的工具，仍沿用无密钥 Hook 之前给出的结果。已关联到账户的机器保留原有的全部拦截规则。对于只能由你自己的私有组写入的 Linux 主目录或 Agent 设置文件夹（umask 002），安全带仍然有效。请参阅无密钥安全带。Marrow 自身的插件和 Marrow 插件开关也受到与其设置相同的保护。
• Marrow 停机期间，高风险操作会等待： 使用密钥时，如果无法连接 Marrow，则 git 推送、发布、部署、API 删除、安全带类别命令或其他高风险工具（例如 MCP 工具）都会在所有宿主上暂停，直到 Marrow 恢复；提交消息或路径中的词语不会导致命令被拦截，常规操作则会在发出警告后继续运行。如果 Marrow 有响应，但无法签发许可，则高风险操作会被拒绝，且绝不会在离线状态下获准执行。
• 本地回执： 每项安全带决策都会以代码和带密钥的哈希形式写入本机，并记录内置工具名称以及固定列表中的 Shell 程序名称（任何 MCP 工具都只记录为 mcp）；不会记录命令文本、参数、路径或 URL。最长保留 90 天或 50 MB。不会上传任何内容。
• 审批绑定到精确操作： 所有者审批只会恢复此前被拦截的那项精确操作。如果被拦截操作的发送形式隐藏了某个值，还会附带 exact_hmac，这是使用本机私有设备密钥生成的带密钥哈希（绝不会发送）；即使重试只在某个凭据上不同（例如换了一个新的一次性密码），仍可恢复执行。操作哈希版本现在为 v3：来自早期版本的已学习审批和已知工作流需要重新审批一次，然后会再次学习。请参阅宿主提示词中的审批。
• 会检查隐藏命令： 未加引号的 here-document 正文、${x:-$(...)} 默认值或算术展开中的命令，都会像其他命令一样接受检查。
• marrow-mcp keys create 会读取所有标志格式： --name=、--type= 和 --expires=（以及 -n=、-t=）会像 --name value 一样读取；存在但为空的标志，或没有条目的 --scopes / --agents 列表，都会导致用法错误（退出码为 2），且不会发送任何内容；省略 --scopes 和 --agents 时，两者都不会发送。

v3.9.108 新增内容

v3.9.108 在 v3.9.107 的基础上增加了 Codex 插件固定项。完整条目见 CHANGELOG.md。

• 可识别 Codex 插件 marrow 和 marrow-advisory 0.1.3。 现在，六个固定文件的 SHA-256 摘要会与 0.1.1 的摘要一同列出。安装并启用了 0.1.3 且这六个文件未发生变化的 Codex，会被识别为正在运行官方 Marrow 服务，与 0.1.1 相同；对这些文件的任何其他更改都会像对待其他服务一样接受检查。已删除从未发布的 0.1.2 草稿摘要。已安装的 0.1.1 不受影响。

这些行为在 3.9.107 中发布，目前仍然适用。

v3.9.107 是针对 3.9.106 的安全热修复。完整条目见 CHANGELOG.md。

• 每条文本哈希都按安装实例加密。 在 Claude Code、Codex 和 Cursor 上，每个被挂钩工具（包括 Bash、Monitor、PowerShell、Agent、Edit、Write、WebFetch、MCP 工具，以及 Marrow 不认识的任何工具名称等）的 command_sha256 和 input_sha256，现在都会使用从每次安装专属的设备密钥（~/.marrow/seatbelt/salt）派生的密钥进行 HMAC-SHA256 计算，且 MAC 中包含工具名称和类型。自由文本字段可能包含脱敏器看不到的值，对它进行普通哈希可能会被离线猜出。同一安装实例上的同一调用会得到相同哈希，因此挂起的操作仍可恢复，已学习的审批仍可在该实例上匹配。Marrow 以明文发送的部署命令（sst deploy --stage production）仍使用普通哈希。exact_hmac 切换到 v2 域。~/.marrow/host-approvals/state.json 中挂起操作的 correlation 和 target，以及生命周期的 correlation_id 也会随之调整。
• 升级说明：部分审批会再次询问。 此更新前创建的挂起操作或已学习审批将不再匹配；在一台机器上学习的审批也不会在另一台机器上匹配。由服务按文本哈希记录的已学习审批、自动审批或先前拒绝的记录，不会跨机器延续，也不会从此更新前延续：系统会再次询问该操作，不会因已不再匹配而放行。
• 没有可用设备密钥的机器仍可恢复挂起操作。 如果没有可用设备密钥（主目录只读、密钥文件不安全、损坏或缺失，或使用 Windows），精确操作哈希和挂起操作目标会改用备用密钥（对 ~/.marrow/host-approvals/state.json 的密钥进行 HMAC-SHA256），而不是每次调用都使用新的随机值。这样，挂起的操作就能像使用可用密钥时一样恢复、报告和提交。如果审批状态也不可用，该操作每次都会挂起并询问，同时输出一条 stderr 提示。只有带有 Marrow 密钥的挂钩才会在状态文件不存在时创建它；没有密钥的机器绝不会创建该文件。
• 发送到 programs[] 的文本更少。 如果管道阶段的首个单词可能就是密码值（"pw" | smbpasswd -s），则不再发送或存储该单词：只有当它是已知程序（阶段中还有其他单词）或 cat、yes、pbpaste 之一（单独出现）时，才会标明该名称；其他单词一律替换为固定标记 unlisted-feeder，且该操作绝不会被绑定。对于不运行 shell 文本的工具（ToolSearch 的 query、提示词、路径、未知工具的 command），只有当首个单词是已知程序时才会标明；其他单词一律替换为 unlisted-program。Bash、Monitor、PowerShell、Codex exec 和 Cursor Shell 不变。
• 编辑路径中的密钥会被替换。 编辑工具（Edit、Write、NotebookEdit、MultiEdit、apply_patch 标头）路径中格式已知的密钥，会在 normalized_action.paths[] 中作为一个片段被替换：发送的路径会将 /p/ghp_...X.txt 替换为 /p/[secret].txt。路径中含有此类片段的操作绝不会被绑定（每次都会询问）。不涵盖：不符合密钥格式的普通单词、被 / 分隔的令牌，以及使用其他大小写书写的前缀。
• 更多用于打印环境变量的命令会被拦截。 环境变量转储拦截（无密钥时的 S4 拦截，以及有密钥时的受保护操作）现在还涵盖：通过输入重定向读取 /proc/<pid>/task/<tid>/environ、Read 和 Grep 工具、通配符、变量默认值、切换到进程目录，或运行 find /proc -name environ -exec，以及由 awk、通过 -e、-c 或 -r 传入的代码，或 sh -c 位置参数运行的独立 env 或 printenv。这只会增加拦截范围。它针对的是一组已知形式，并非 shell 能运行的所有命令；已知的遗漏情况列在 CHANGELOG.md 中。
• 审批状态文件现在与收据盐值一样受到保护。 读取 ~/.marrow/host-approvals/state.json（及其临时副本和同目录下的任何备份）现在会像读取收据盐值一样处理：无密钥时触发 S4 拦截，有密钥时作为受保护操作处理，并在服务中断时挂起。列出或查询该文件夹状态，以及只提及该文件夹的文本，均不变。
• 有密钥模式会拦截嵌套 shell 代码中隐藏的密钥文件读取。 在有密钥模式下，隐藏在 bash -c、eval、sudo -n sh -c、env -S、xargs、ssh、命令链、变量默认值、通配符或符号链接中的密钥文件（.env、.env.local、.env.<name>、.npmrc、.netrc、.dev.vars、密钥文件）读取，现在会作为受保护操作处理，正如无密钥安全带已经拦截的那样。有密钥模式也会像无密钥模式一样，将 .env.dist 和 .env.defaults 视为密钥文件。副作用：在有密钥模式下，bash -c、eval、ssh 或 sudo -n sh -c 中的 grep .env README.md 或 jq '.env' package.json 现在也会被拦截。
• 运行被拦截操作的 awk 程序也会被拦截（无密钥模式）。 无密钥安全带现在会拦截运行时构造被拦截操作的 awk 系列程序（awk、gawk、mawk、nawk、busybox awk，以及名称中包含 awk 的任何其他程序）。仅由字符串字面量组成的命令会作为嵌套 shell 处理；包含其他任何部分（ARGV、ENVIRON、-v 变量、字段、通过 getline 读取的值、函数调用）的命令，则会触发新的动态命令拦截 dynamic_awk_command。即使命令无害，只要 awk 命令使用 ARGV、-v 值或字段构造命令字符串，现在也会被拦截。有密钥模式不变。
• command 仅将前导的 -v 或 -V 视为名称查询。 对于任何程序，command npm publish -v、command git push -v --force origin main 和 command rm -rf ~ -v 过去可以通过无密钥安全带，现在会被拦截。command -v node、command -V git 和 command node -v 不变。
• 安装程序运行时核心（放宽一项检查）。 现在，安装程序接受新版运行时核心以及 0.1.70-0.1.74 核心，因此 HOME 的上级目录即使是符号链接也能完成安装。在 Cursor 和 Codex 上，由该新版核心启动的 marrow 服务现在也能像由旧版核心启动时一样证明自己是官方服务。只有当启动项正是启动该挂钩的加载器时，才会通过启动验证；其他任何核心都不会通过验证。使用新版核心但搭配旧版 MCP 的安装程序无法通过验证，其自身工具会被挂起。请先发布 MCP，再发布安装程序。 这些行为在 3.9.106 中发布，且仍然适用。

v3.9.104 和 v3.9.105 未发布到 npm；它们的更改已在 3.9.106 中发布，并列于 CHANGELOG.md。

• 没有密钥也不再导致服务崩溃。 如果服务读取密钥的所有位置都没有 Marrow 密钥，MCP 服务现在会以零个工具启动，并在 instructions 文本中说明如何连接密钥（在 https://getmarrow.ai/signup 创建密钥，然后运行 npx -y @getmarrow/install@latest activate），而不是打印“MARROW_API_KEY environment variable is required”并以状态码 1 退出；此前各宿主会将其显示为服务故障。tools/call 会返回 JSON-RPC 错误：不会进行任何判断、记录、读取或写入。任何格式的密钥（无效或仅含空白的密钥、MARROW_KEY、MARROW_KEY_<NAME> 形式的 fleet 密钥、任何 --key 参数），或未通过仅限所有者检查的所有者密钥文件，都会保留先前行为；仅存在于项目 .env 中的密钥仍然不算数。在 Claude Code 插件中，说明会包含插件的密钥设置步骤。
• 安装器写入的服务会经过精确验证。 在 Cursor 和 Codex 中，安装器写入的 marrow 服务只有在启动 hook 的确实是安装器加载器，且版本、MCP 包完整性、SDK 固定版本和运行时核心都完全一致时，才会为 Marrow 自带工具跳过门禁。旧版安装器启动的服务、类似但不完全匹配的版本（例如 3.9.1050），或未提供包完整性的启动，都会像其他 MCP 服务一样经过门禁。npx 和 marrow-mcp 二进制形式不变。
• 会打印环境变量的命令会被拦截。 在没有密钥时，会打印大量或全部环境变量的命令会返回现有的 S4 消息；有密钥时则会被视为受保护操作。这些命令包括 compgen -e、tmux show-environment、systemctl show-environment、ps -E、npm run env（以及 pnpm、yarn、bun）、php -i、strace -v、/proc/<pid>/task/<tid>/environ，通过 setpriv、unshare、runuser、nsenter 和 xargs 等包装器运行的 env，以及传给解释器的打印环境变量代码（node --eval=CODE、perl -e、python3 -c、php -r）。
• 每个 Claude Code 工具调用都会经过 hook。 Claude Code 匹配器会将每个工具调用发送到 hook，但 Marrow 自带的精确工具名称以及只读的 LS 和 ListMcpResourcesTool 除外。此前只有固定列表中的内置工具会经过 hook，因此 Monitor、PowerShell、WebFetch、Agent、Skill 以及之后新增的工具都不会经过。Monitor 命令会被精确归类为相同的 Bash 命令，无论有无密钥都是如此（无密钥时，Monitor: git push --force origin master 会被拦截；有密钥时则会被暂缓）。无密钥时，PowerShell 命令会由安全带按相同的 Bash 命令读取；有密钥时，则按其旧有读取方式与 Bash 读取方式中更严格的一种处理，且不应用 Bash 的任何只读列表（在 PowerShell 中，type、cat、find 和 ls env: 会读取文件或打印环境变量），因此 PowerShell 调用绝不会被视为只读，type ./production.env 会作为机密读取而被暂缓。对其中一个工具的批准不会解除对另一个工具的限制，而且批准会绑定到该调用的 timeout、timeout_ms 和 run_in_background。Agent、WebFetch 以及其他只负责启动任务、获取页面或安排事项的工具都会被记录，但其中提示词或 URL 里的文字不会导致它们被暂缓。只负责报告、通知、组织输出或渲染的内置工具（PushNotification、ReportFindings、StructuredOutput、Artifact、ArtifactCheck、ArtifactComments、ArtifactData、ListAgents、SubagentHandback）也是如此；Workflow 的 script 会按 JavaScript 读取，而绝不会按 shell 文本读取；对于 Marrow 不认识的工具，仍会检查其中的文字，而 RemoteTrigger 和 DesignSync 仍会按名称识别。这些工具引发的后续操作会各自经过 hook。重新运行 marrow-mcp setup（或安装器）以刷新使用旧匹配器写入的 hooks：setup 能识别安装器写入的 hooks，因此在安装器写入的设置文件上运行时，每个事件都会恰好保留一个 Marrow 条目；你自己编写的类似 hook 则会原样保留。
• 更多机密文件受到保护。 无密钥时，读取或复制任何已存在的 <name>.env 文件（例如 prod.env）、~/.marrow/fleet.env 或 ~/.marrow/credentials 下的任何内容，都会像 .env 一样被拦截（S4）。对机密路径运行 git log -p、git whatchanged -p 和 git format-patch 会打印其历史，因此会像 git show -- <path> 一样被拦截；git log --oneline -- .env 和 git log -p -- src/app.ts 仍可通过。hook 不知道工作目录时，对相对路径 <name>.env 的读取（cat prod.env、cat config/）也会被拦截；搜索模式（如 grep -rn "process.env" src）仍可通过。模板（.env.example、.env.sample、.env.template）以及搜索中的 process.env 等普通文字仍可通过。有密钥时，检查现在也会读取同一列表，因此 ~/.marrow/env、env.local、~/.claude.json、GitHub CLI 的 hosts.yml、1Password 配置和安全带盐值也会被视为机密读取。
• 环境变量中的 URL 无法重定向你的密钥。 来自 ~/.marrow/env（或 env.local）的密钥只会发送到默认 Marrow 端点、同一文件通过 MARROW_BASE_URL 指定的端点，或该文件在新增的 MARROW_ALLOWED_BASE_URLS 中列出的精确源。仅由进程环境指定的 MARROW_BASE_URL（项目的 .mcp.json 或设置中的 env 块、direnv、devcontainer）将不再改变密钥发送位置：系统会使用默认端点，并在 stderr 上打印一行，说明忽略了哪个来源，但绝不打印密钥或 URL。来自进程环境的密钥仍像以前一样使用进程环境中的 URL。如果你使用暂存环境或可自托管端点，并将密钥放在 ~/.marrow/env 中，请在该文件中添加 MARROW_BASE_URL= 或 MARROW_ALLOWED_BASE_URLS=。请参阅环境变量。
• 会检查工具参数中的 ID。 会作为 API 路径组成部分的 ID 和 slug（workflow、instance、lease、comparison、handoff、decision、detected 和 template ID）必须以字母或数字开头，只能使用字母、数字、_、. 和 -，长度最多为 256 个字符，且绝不能包含 ..。任何不符合条件的值都会在发送请求前被拒绝。Marrow 自身签发的每个 ID 都符合要求。
• SDK 版本会精确固定。 @getmarrow/mcp 依赖 @getmarrow/sdk 3.7.67，不使用版本范围。 较早的行为仍可在 Seatbelt、故障暂停和精确审批、项目文件和 Marrow 自带工具、设置和密钥处理 以及 钩子行为详情 中查看。v3.9.99 将审批带入了宿主提示词；请参阅 宿主提示词中的审批。

较早的版本说明已从此 README 移至 CHANGELOG.md。

已观测用量与计算成本

会话钩子命令会保留通过 stdin 提供的已观测用量以供捕获。会话总量仍为累计值，若没有经过验证的差值，则不计算价格；这不会添加转录收集，也不会凭空补造缺失的模型用量。

连接器工具调用不会自动公开上游聊天模型的用量。原生钩子仅捕获其事件中实际存在的用量。适配器可以将已观测的请求端点传递给 extractModelUsageFromUnknown；原生钩子则通过 MARROW_MODEL_USAGE_ENDPOINT 接受显式宿主配置。只有 HTTPS api.openai.com 和 api.anthropic.com 才会被识别为第一方计费，且不得包含凭据或自定义端口。仅当该设置描述钩子所观测响应对应的请求时才设置；不要将代理或混合提供商流标记为第一方。端点和响应内容绝不会作为用量证据发送。

MARROW_MODEL_USAGE_PRICING_DIMENSIONS 接受紧凑的 JSON 对象，其中包含请求配置实际确定的维度（例如层级、区域和模态）。缺失的维度仍视为未知。已观测的服务层级、Anthropic 推理地域和单一 TTL 的缓存创建计数优先采用。混合缓存 TTL 写入仍无法确定。仅在订阅用量时才设置 MARROW_MODEL_USAGE_BILLING_MODE=subscription；此时显示的成本表示 API 等效估算，而非账单。切勿使用这些设置来猜测并填补缺失信息。

直接调用 marrow_model_usage 和 Commit model_usage 也接受计费主机、令牌语义、缓存写入、响应/事件标识、发生时间、定价维度以及显式的覆盖范围/比较元数据。提供的无效值会导致验证失败；缺失的计数不会被视为已观测到的零。稳定 ID 会保留重试身份。会话总量和部分流开始时的观测仍为累计值，若没有经过验证的差值，则不计算价格。此钩子不会组装 SSE 流，也不会读取转录内容。如果无法获得成本，请检查返回的原因和覆盖范围：成功的工具调用无法补回缺失的主机/模型/计数/变体证据。任何捕获都不会推断完整覆盖范围、开销或因果基线；在得到证明前，基线和净节省仍处于待定状态。

受治理的操作流程

未设置 MARROW_TOOL_PROFILE 时，默认的主配置文件会先使用 marrow_agent_runtime，然后使用 marrow_commit。它会公开 17 个工具；只有在显式选择 core 或 full 并重启 MCP 后，marrow_auto 才可用。主状态和经验教训分别使用 marrow_agent_status 和 marrow_fleet_lessons。

在 30 天评估期和 Business 方案中，部署和发布会在钩子及受治理的运行器中被暂停。Team 和 Free 方案会发出警告。如果 Marrow 无法访问，钩子会暂停高风险操作，并允许常规操作在警告下继续；受治理的运行器则会停止其无法验证的受保护操作。通过 MCP，Agent 会收到决策，并应遵循该决策。钩子运行于 Agent 宿主内部，因此，如果 Agent 或人员编辑或绕过宿主，钩子就无法暂停操作。在部署、合并、发布、迁移、凭据变更、财务操作或会影响客户的工作之前：

1. 调用 marrow_agent_runtime 或 marrow_decision_brief。
2. 如果返回的决策是 block 或 review_required，则停止；否则，遵循其先前的经验和证明要求。
3. 如果完成契约指明了服务器创建的运行时 decision_id，则重复使用该 ID。仍需创建决策时，调用 marrow_think；显式选择的 core/full 配置文件也可以使用 marrow_auto。将 marrow_agent_runtime.runtime_authorization.id 单独保留为重要操作的门禁回执。
4. 仅在门禁允许时执行操作。Codex、Grok 和 Gemini 只能在重启并完成宿主钩子审核后，使用已配置的原生钩子。受治理的包装器仍是明确限定范围的备用方案：npx @getmarrow/install run --agent <agent-id> -- -- <command>。
5. 使用该 decision_id、结果、门禁回执和所需证明调用 marrow_commit。

marrow_agent_runtime 会返回带有权威门禁回执的 runtime_authorization。创建决策的普通运行时或仲裁运行时也会返回服务器创建的 decision_id；请遵循 completion_contract.decision_creation_required 并保留返回的作用域。需要创建决策时，请调用 marrow_think；core/full 也可以使用 marrow_auto。Auto 会请求现有的扩展运行时响应，以在重复使用该决策前核验回执身份、决策、操作、Agent、会话和过期时间；它不会再次获取授权。

review_required、block 或 outcome_observation_only 结果绝不允许执行操作。如果操作已经发生，且必须保留其真实结果，marrow_commit 可以请求运行时将观察结果的交付绑定到现有决策、操作、会话和 Agent。精确的后端 outcome_observation_only 关联信息不具备持久性，也不授予授权，因此 MCP 绝不会将其作为门禁、仲裁或所有者审批回执发送。被接受的观察结果会报告 committed: false、outcome_state: "observed_unverified"、authorization_granted: false 和 trusted_learning_applied: false，以及后端的 exact_next_action。这是持久化交付，因此不要重试或暂存同一观察结果。若要将其提升为可信学习，需获取指定的授权和证明，然后使用精确的已观察负载明确发起新的提交尝试。绝不要伪造决策、回执、审批或授权。

marrow_auto 会返回 operation_id、阶段和可恢复状态。对于可恢复的待处理阶段，请遵守 retry_after_ms，并使用相同的操作 ID、租户、Agent、会话、操作、类型、界面、结果、证明和回执负载；auto 绝不会为适配 core 预算而缩短请求的有限延迟。阶段为 proof_required 时，请提供所要求的实测证据，然后再重试该操作。稳定的阶段幂等键会在重试期间保留原始决策和结果；后端仍是决定是否接受以及如何处理冲突的权威来源。自动写入尝试的上限为 4 秒，以便在现有 8 秒总预算内留出重放时间。较长的服务器延迟会保持待处理状态，不会等待超过该预算。格式错误或无界的 Retry-After 标头会停止自动继续。只有 committed:true 才能确认已完成；待处理状态并不能证明服务器写入失败。 如果回执过期时同一决策仍处于开放状态，请使用原始操作、类型、界面、Agent 和会话，明确重新请求正常运行时授权。必须使用新的请求键：重放旧的运行时键会重放其旧回执。确认返回的 runtime.decision_id 仍与原值匹配，将新的 runtime.runtime_authorization.id 保留为 gate_receipt_id，并满足当前的证明和审批约定。对于目标明确的范围，请使用 marrowAgentRuntime 库或 POST /v1/agent/runtime，并保留该目标；公共 MCP 运行时架构不公开目标。不要通过操作后的 auto_gate 续期：它只获取观测结果。新回执绝不会追溯授权未经许可而执行的操作，范围发生变化则属于不同的决策。过期或已使用的回执可能返回 committed:false 的已接受 observed_unverified 结果；这不代表已结案。

对于普通暂缓（completion_contract.owner_approval.mode: "ordinary_non_arbitrated"），auto 会在 owner_approval_required 状态等待，并按服务端建议读取门禁回执的审批状态。经过 retry_after_ms 后，使用相同的操作 ID 再次调用 auto；服务端记录审批后（参见主机提示词中的审批），auto 会在同一决策和门禁回执上恢复。若操作尚未执行，拒绝会以门禁拒绝结案；门禁回执一旦用尽即为最终状态：auto 会报告操作已关闭，绝不会再次要求执行。调用方填写的 proof.owner_approval 绝不是审批：MCP 会将其剥除，只有服务端记录的审批才有效。未知的普通完成约定会保持停止状态，不会自动启动仲裁。

对于仲裁，账户所有者通过单击一次链接选择并批准一项提案（参见主机提示词中的审批）；auto 会等待状态读取，并使用其返回的 owner_approval_receipt_id 提交。否则，请使用相同的操作 ID、arbitration_receipt_id 和服务端签发的 owner_approval_receipt_id 调用 auto。证明或聊天文本不能替代此回执。CLI 的已关闭响应会报告 phase: "closed"、live_delivery.committed: true 和 resumable: false；库的结果使用 committed: true。结果记录绝不会将已停止的操作变为获准操作。

CLI 的生命周期字段 receipt.queued: true 表示其稳定事件已在本地存储，等待后续的有界投递；不得将 receipt.accepted: false 解读为服务端已接受。暂时性故障会保留排队事件和重试计划，以便后续进行有界投递，包括进程重启后。系统会遵循服务端的重试指引。身份验证失败会保持失败状态，并提供明确的凭据修复指引，绝不会自动重试；冲突事件属于服务端证据，绝不会重放；其他所有死信都会在被动提示期间通过有界自动恢复自行修复。进程退出可能会中断后台提示，使事件留待后续运行处理。phase_timings_ms.total 衡量 auto 核心阶段。response_timings_ms 包含数值型的 core、durable_enqueue 和 full_response；最后一项的计时止于响应构建完成，不包括之后的标准输出排空和主机处理。Canary 的 latency_ms 独立衡量 MCP 往返时间，而 attempts 和 retry_wait_ms 描述的是实测的外层工具重试，不包括内部数据库或网络调用。

操作前请求示例：

{
  "tool": "marrow_agent_runtime",
  "arguments": {
    "action": "deploy the production worker",
    "type": "deploy",
    "role": "deploy",
    "surfaces": ["repository", "deployment", "production"]
  }
}

结案示例：

{
  "tool": "marrow_think",
  "arguments": {
    "action": "deploy the production worker",
    "type": "process",
    "checkLoop": true
  }
}

{
  "tool": "marrow_commit",
  "arguments": {
    "decision_id": "decision_id returned by marrow_think",
    "gate_receipt_id": "receipt id returned by marrow_agent_runtime",
    "success": true,
    "outcome": "Production deploy succeeded and smoke checks passed.",
    "proof": {
      "checks": ["tests passed", "secret scan passed", "production smoke passed"],
      "rollback_target": "previous release"
    }
  }
}

根据账户策略，高风险工作可能获准、收到警告、暂缓待审或遭到阻止。只要运行时约定允许，低风险工作就可以使用被动指导和有界缓存状态。 当两个或更多 Agent 对下一步操作意见不一时，请先调用 marrow_arbitrate，再执行任何一方的提议。它使用相同的 /v1/agent/runtime 控制平面，并返回 selected、synthesized、review_required 或 blocked，同时提供一份持久的租户级回执，说明结果背后的策略、证据、权限、风险和异议。

{
  "tool": "marrow_arbitrate",
  "arguments": {
    "objective": "Release the audited backend change safely",
    "ownerIntent": "Production deploys require independent audit proof",
    "proposals": [
      {
        "proposal_id": "deploy-now",
        "agent_id": "jarvis",
        "action": "Deploy the tested commit now",
        "risk_level": "high"
      },
      {
        "proposal_id": "audit-first",
        "agent_id": "barvis",
        "action": "Audit the exact commit, then release only if it passes"
      }
    ]
  }
}

Marrow 会根据账户确定 Agent 角色，而不信任调用方的声明。证据引用必须是不透明标识符；不要发送原始提示词、日志、URL、路径、凭据或客户内容。仲裁响应包含提交时使用的 decision_id、门控回执和仲裁回执。review_required 结果需要账户所有者通过一键链接批准其中一个提议；将生成的短时有效、单次使用的 owner_approval_receipt_id 传给 marrow_commit。Agent 不能通过证明字段自行授权。

当并行 Agent 可能编辑同一文件、服务、部署或工作流时，请使用 marrow_coordinate。获取的租约会返回一次性释放凭据。随后，子 Agent 可以创建精简的证明数据包，其中仅包含有界摘要和不透明的持久证据引用。只有在关联结果和所需证明确实已完成后，才会接受 Complete。

在两个模型或工作流变体都记录结果后，请使用 marrow_replay_compare。它会在单个租户任务下比较现有证据；它不会运行模型、保留提示词，也不会根据标签推断胜者。

宿主提示词中的审批

当 Marrow 暂停某项操作等待审批（review_required）时，用户可在日常工作环境中完成审批，无需登录。钩子会将答复记录到 Marrow；Agent 绝不会报告或声称已获批准。Marrow 控制面板会显示回执和历史记录，但审批不在此处进行。

宿主和会话	用户的操作
Claude Code（default、acceptEdits；从 v2.1.257 起支持 auto）	回答 Claude Code 自带的权限对话框。在 plan、dontAsk 和 bypassPermissions 模式下，切换到默认模式后重试。
Cursor shell 和 MCP 调用，本地会话	回答 Cursor 自带的审批提示
Codex 和 Gemini CLI，本地交互式会话，且已开启其自带的审批提示	仅输入钩子向其显示的回复，例如 marrow approve CODE
支持 elicitation 的 MCP 客户端（marrow_auto）	回答客户端自带的对话框（由客户端证明）
尚未启用提示钩子的 Codex TUI、编辑器中的 Cline 和 Windsurf	使用宿主自带的审批步骤（如果已启用）：钩子会中性地作答，绝不会明确允许；Marrow 会将结果记录为 Marrow 未观察到
Grok、未启用提示钩子的 Gemini、处于 preToolUse 阶段的 Cursor 及 Cursor 的其他工具、关闭审批提示的 Codex、处于 default 以外任何模式的 Gemini CLI（--yolo、-y、--approval-mode，或其系统、用户或项目 settings.json 中的 general.defaultApprovalMode，或允许不经询问执行 shell 命令，或其无法读取的设置文件），或没有用户参与的证据	不输入回复，也不输入代码（Agent 可能自行作答）；操作会安静地等待所有者
无人值守运行（无头 Claude Code、codex exec、gemini -p、Cursor cloud）	运行过程中无需执行任何操作：该操作会安静地等待，Agent 继续运行
仲裁审查	账户所有者通过一键链接选择一个提议

• 所有者的电子邮件链接是个例外。 只有在以下情况下才会发送：所有者锁定了某个类别；操作员要求撤销所有者本人设置的持续拒绝后（重试，或在 marrow_auto 中设置 request_owner_link: true）；所有者启用了无人值守通知，且运行无人值守；或者操作员要求进行仲裁审核。普通的暂缓操作不会给任何人发送电子邮件。
• Codex 关闭审批提示时会静默暂缓（--yolo、-a never、--full-auto、--approve-for-me、-s danger-full-access，以及通过 -c 或 $CODEX_HOME 配置实现的相同设置）。不会读取：受管配置或项目配置中的 Codex 设置。不会检测：Cline 的自动批准和 Windsurf 的 Turbo 模式（这些设置存储在编辑器状态中，没有可靠的检测信号）。开启这些设置后，宿主会在不询问的情况下执行操作；Marrow 会将其记录为 Marrow 未观察到，而绝不会将其记录为用户的答复。所有者锁定的类别仍会暂缓。
• 下次会话中处理暂缓的操作。 在交互式会话的第一个提示词中，用户会看到“有 N 个暂缓的操作正在等待处理”，其中仅显示操作类型和 Agent，并可在此处重试以批准其中一项。
• 一次批准，只运行一次。 对同一项批准发出的两个相同调用中，一个会运行，另一个会被拒绝。
• 仅记录确切操作，不记录其文本。 由 Hook 分类的调用会发送 normalized_action：工具类型和名称、程序名称（以及编辑路径，主目录以 ~ 表示），并附带规范化形式的 SHA-256 哈希值。事件 ID 和关联 ID 都来自该规范化形式，绝不来自原始命令、输入或提示词。凭据会被替换；命令读取的数据会被哈希，因此 SELECT 和 DROP 是不同的操作；其他可能包含机密的内容则会被隐去。包含凭据或被隐去内容的操作会标记为 truncated: true：Marrow 绝不会为此类操作学习可重复使用的批准；对于被暂缓的此类操作，答复只会恢复执行该确切操作（参见“批准如何绑定”）。无论是否带有此标记，判定、暂缓和提示词都相同。凭据值仅在遇到空格、引号或后面跟着另一个 name= 字段的分隔符时才结束，因此，在凭据之后有所不同的操作仍会被视为不同操作；密码中 #、,、& 或 ; 后面的任何部分都不会保留在哈希形式中。作为普通参数传给未知程序的密码（./deploy.sh hunter2）无法被识别；它只会留在哈希值中。
• 批准如何绑定。 Marrow 会将所有者的批准绑定到被暂缓的确切操作。客户端会在发送操作前隐藏可能的机密；如果隐藏了任何内容，就会添加 exact_hmac，这是使用本机私有设备密钥（~/.marrow/seatbelt/salt，仅创建一次，权限为 0600，绝不发送）生成的确切操作密钥哈希值。只有完全相同的操作才能恢复执行；如果重试时仅某项凭据不同（例如新的单次密码），仍可恢复执行。如果设备密钥缺失或不安全，Marrow 会改用本地批准状态的机密（~/.marrow/host-approvals/state.json，权限为 0600，绝不发送）派生的备用密钥，对相同哈希进行加密；这样，被暂缓的操作仍可恢复执行（缺少 Marrow 密钥时，Hook 会创建该状态文件；没有密钥的机器绝不会创建）。只有在该状态文件也不可用时，Marrow 才会显示一条说明（指向安装程序的 npx -y @getmarrow/install@latest doctor），并要求重新批准，而不是恢复执行。
• 升级说明： 操作哈希版本已更改（v3）。早期版本中学到的批准和已知工作流会再次询问一次，然后重新学习。
• 响应慢和服务中断是两回事。 Codex 和响应限时为 5 秒的宿主会在各自的 Hook 限时内作答（Codex 会在启动后 2 秒内作答；在 Linux 上，如果 npx 启动时间少于约 1.6 秒，则从启动起约 2.6 秒内作答）。Marrow 响应缓慢时，可暂缓的操作仍会保持暂缓。真正的服务中断（Marrow 始终未作答）只会在 Shell 命令执行以下操作时暂缓：通过 Git 推送、发布软件包或镜像、部署、通过 API 或云 CLI 删除内容，或触发安全带类别（S0-S5、S-x）。提交消息、路径、echo 文本或注释中的词语都不会导致暂缓；向列出的工具请求帮助也不会（git push --help）。其他高风险工具（例如 MCP 工具）会被暂缓；常规操作会在发出警告后继续运行；等待中的暂缓操作或所有者锁定的类别则会继续保持暂缓。Marrow 已作答但无法签发许可时，高风险操作会被拒绝，绝不会在离线状态下放行。
• 标签和文本如实呈现。 如果没有对话框或键入回复标记，批准会记录为宿主的放行规则。用户看到的文本不会显示收据 ID。被拒绝的操作会说明一个简单的解决方法。

被动使用

npx -y --package=@getmarrow/mcp@latest marrow-mcp setup 会配置受支持的提示词、操作前、工具结果、权限标记和会话停止钩子。配置、公开钩子 argv 和通过 API 密钥验证的回调均为客户端自述。它们保留原始生命周期活动，但无法证明宿主调用了钩子，也无法认证被动控制。

能力与覆盖范围约定

集成模式	Marrow 可声明的覆盖范围
仅 MCP 工具	按需；仅覆盖显式 MCP 工具调用
已配置的原生钩子	仅协作式遥测/上下文；活动由客户端自述，覆盖范围仍未经验证
createPassiveRuntime().install()	仅限自有 Node 进程，且仅在该运行时已安装并运行期间
受治理的运行器	仅限通过包装器启动的命令
自定义宿主	需要有界事件适配器；仅覆盖 Marrow 能观察到回执的生命周期事件

此约定与模型无关。模型名称、宿主标头、API 密钥、公开钩子入口点、配置文件、已安装的钩子条目、成功的 MCP 握手或客户端自述的生命周期回调，都不能认证被动覆盖或强制执行。因而，未知的 MCP 宿主会获得通用的 mcp-client 身份，以及与具名宿主相同的按需工具、架构和 API 语义。公开生命周期回调和钩子活动均由客户端自述，无法验证或认证被动覆盖；这需要独立授权。

受支持的宿主调用时，已配置的钩子会发送精简的分类信息和生命周期回执。它们不需要原始提示词、补全内容、命令输出、工具输出或凭据。工具或会话完成并不意味着业务结果自动成功；必须明确标记成功/失败以完成闭环。

安装程序会分别安装 Claude Code 和 Grok 的钩子入口点。公开入口点仅提供由客户端报告的显示标签，并非宿主来源证明。钩子事件 JSON 无法选择生命周期框架或 Agent。若存在所有者配置，Agent 身份仅取自该配置；否则请求会省略此信息，以便经过身份验证的服务推导与凭据绑定的身份。每个钩子生命周期事件都会标记为 source: client_self_reported，并省略 capability_level: native_hooks、适配器认证、配置指纹、预期钩子以及已观察钩子认证字段。旧版、未知和自定义入口点均保持通用身份。 Claude Code hooks 可以协作请求指导并应用 harness 权限响应，但这并不能证明控制始终开启。Codex 原生 hooks 会将阻止操作映射为受支持的同步拒绝响应；需要审核的暂停流程遵循主机提示词中的审批。Cursor 和 Composer 使用相同的 Cursor 原生操作前、结果、失败和停止适配器。Cline 使用原生操作前和工具后适配器，以及 TaskCancel 收尾；其文档中提到的 TaskComplete hook 仍在开发中，因此不声称已覆盖该 hook。Windsurf 使用原生操作前、成功结果和响应收尾适配器，并要求关闭 Restricted Mode。Gemini CLI 使用原生 BeforeTool、AfterTool 和 AfterAgent 适配器；AfterAgent 是确定性的逐轮收尾，不声称支持 SessionEnd 交付。Grok 使用全局原生 PreToolUse、PostToolUse/PostToolUseFailure 和一个非阻塞 Stop 收尾；Marrow 生成的 Grok 文件不包含重复的 SessionEnd 收尾。这些原生路径让 MCP 按需运行，并要求重启和审核主机 hooks。对于原生契约无法强制执行通用询问的情况（Cursor 的 preToolUse、Gemini 和 Grok），需要审核或无法控制的受保护工作会被拒绝并等待审批；如果有证据表明人员在场，Cline 和 Windsurf 会将普通暂停交给主机自身的提示。所有活动仍由客户端自行报告，而非经验证的主机遥测；受治理的包装器仍是明确限定范围的回退方案。未知和自定义主机仍按需运行，除非它们提供有界事件适配器；即便如此，其活动也不构成认证，除非有独立权威机构确认。

临时生命周期回执使用有界的仅限所有者访问的暂存区，并使用稳定的事件 ID 重试。死信会自动修复：可恢复的失败会在被动提醒期间自动重试，重试次数和冷却时间均受限；冲突事件会被识别为服务器拥有的证据，绝不会重放。操作人员可以在不暴露事件内容的情况下检查并清空暂存区：

npx -y --package=@getmarrow/mcp@latest marrow-mcp spool-status
npx -y --package=@getmarrow/mcp@latest marrow-mcp drain-spool

输出仅包含状态、受限的待处理／失败／可恢复／服务器拥有／恢复耗尽计数、最早回执时间戳、容量和确切的修复方法。只有身份验证类死信需要操作人员处理：恢复凭据绑定，然后清空暂存区。清空操作仅针对当前凭据和 Agent 命名空间：隔离的旧版命名空间积压会单独报告，绝不会让成功清空当前命名空间变成失败。旧版文件绝不会重放、合并、删除或归属到当前身份。恢复原始身份以清空其中一项，或者在该身份不可用时，将选定文件原样保留在单独的仅限所有者访问的隔离目录中。当前命名空间中的身份验证失败会作为明确的持久失败保留，并附带修复指导；恢复次数耗尽的事件会停止循环，而不会无限重试；drain-spool 仍是明确提供给操作人员的工具，而非用户必须执行的操作。

检查已安装的运行时：

marrow_agent_status

状态诊断会区分缺少密钥、密钥无效、绑定的 Agent 身份错误、网络限制、缺少 hooks 和证明不完整。诊断会提供确切的修复操作，且不会暴露机密。

主要 MCP 工具

工具	用途
marrow_agent_runtime	一次调用即可获取操作前状态、策略门禁、相关经验、证明要求和确切的下一步操作
marrow_arbitrate	在执行前解决 Agent 提案之间的冲突，并返回可解释的仲裁凭据
marrow_coordinate	获取／释放资源租约，并在租户内的 Agent 之间交换精简的子任务证明包
marrow_replay_compare	对比两个现有的、有证明支持的结果，无需执行模型
marrow_decision_brief	为有实际意义的工作提供精简的操作简报
marrow_think	记录意图并检索相关的治理情报
marrow_commit	通过结果、凭据和证明结束一项操作
marrow_workflow_gate	根据策略评估工作流操作
marrow_completion_contracts	列出重要操作类型的证明契约
marrow_evaluate_completion_contract	检查证据是否足以判定工作已完成
marrow_agent_status	验证捕获、身份、结果覆盖范围和钩子运行状况
marrow_value_report	无需仪表板即可返回账户／Agent 价值证据
marrow_buyer_proof	返回可供负责人审阅的治理和可靠性证据
marrow_governance_timeline	检查一段时间内的决策、门禁、证明包和结果
marrow_decision_trace	说明一项受治理决策，并返回负责人可读的干预凭据
marrow_fleet_lessons	检索当前账户或 Agent 获准使用的已验证经验
marrow_model_usage	当执行框架能够提供相关数据时，记录精简的令牌数、成本和延迟统计

该软件包还提供密钥管理、集群交接、部署历史、自适应策略、上下文／经验、查询和工作流示例等工具。所有工具和字段详见完整的权威文档。

上下文和工作流示例

稳定版 marrow_*memory* 工具用于管理治理决策所用的获授权上下文和过往经验。这些是高级辅助 API，并非独立的产品类别。

模板工具提供 24 个可配置的工作流示例。它们是策略设计的起点，不是客户案例、法规验证、法律建议，也不代表已证明在所列行业中投入生产使用。

信任与数据边界

• 私有账户、集群、工作流、证明和 Agent 数据默认限定在租户范围内。
• 可将绑定到 Agent 的密钥限制为允许的身份和权限集。
• 可选择贡献经过清理的汇总数据；这绝不意味着共享原始提示词、代码、机密、证明包、账户标识符、Agent 标识符或客户身份。
• API 密钥创建后不会再次返回；密钥材料应通过客户端的密钥存储提供。
• Marrow 返回指导信息和策略数据。Agent 不得将返回的文本作为 shell 输入执行。
• Agent 不能批准自己：调用方写入的 proof.owner_approval 会被移除，聊天或证明文本绝不是批准凭据，只有服务器记录的批准才有效。
• 在工具的提示词中给出的批准，由你计算机上的软件报告。以你的用户身份运行的 Agent 可以伪造一次批准，用于单项受阻操作。对于必须由你亲自批准的操作，请锁定该类别（仅限已验证）；此时只有你的单击链接或仪表板才有效，而且 Marrow 绝不会从工具报告的批准中学习，也不会在不同 Agent 之间重复使用这些批准。
• 切勿将 Agent 连接到接收 Marrow 批准邮件的电子邮箱。能够读取该邮箱的 Agent 可以自行打开单击链接。

有关已实现的控制措施、当前限制和路线图状态，请参阅信任中心。

环境

变量	必需	用途
MARROW_API_KEY	是	账户或绑定 Agent 的 API 密钥
MARROW_BASE_URL	否	覆盖 API 基础地址。当密钥来自 ~/.marrow/env 时，除非同一文件中指定了 MARROW_BASE_URL，或在 MARROW_ALLOWED_BASE_URLS 中列出了其来源，否则只在进程环境中设置的 MARROW_BASE_URL 会被忽略（并显示一条提示）；来自进程环境的密钥则使用进程环境中的 URL
MARROW_ALLOWED_BASE_URLS	否	仅从 ~/.marrow/env 读取。以逗号分隔的精确来源（https://host[:port]，或 http://localhost、http://127.0.0.1、http://[::1]），当进程环境中指定这些来源时，存储在该文件中的密钥可发送至这些来源。不支持通配符、路径、凭据、查询参数或片段
MARROW_AGENT_ID	否	MCP 工具绑定的 Agent 身份
MARROW_FLEET_AGENT_ID	否	被动设置使用的 Fleet Agent 身份
MARROW_HOOK_BACKGROUND_NUDGE	否	默认开启：PostToolUse 仅将事件写入队列，并启动一个分离的后台进程来发送事件，因此钩子几乎不会增加延迟。设为 false 可在钩子内进行有界的内联发送（750 ms）。当 MARROW_AUTO_HOOK=false 或本地控制已禁用时，绝不会运行
MARROW_WRITE_RECONCILIATION_BUDGET_MS	否	默认值为 15000，范围为 1000-60000：待处理的 think 或 commit 可等待的总时长；在服务器返回 retry_after_ms 或 Retry-After 后，使用相同的幂等键和请求哈希继续重试。如果下一次等待超出时限，调用将返回可恢复的待处理回执，且绝不会报告成功

文档

• 权威文档
• 信任中心
• 状态
• GitHub

许可证

MIT

相关软件包

• @getmarrow/install - 默认安装程序、自测、受管控的运行器和操作员 TUI
• @getmarrow/sdk - 用于自有 Agent 运行时的 Node.js 和 TypeScript 集成

Codex 原生用量捕获接受绑定的 thread/tokenUsage/updated 事件，或符合受支持的 0.157.1 架构的有界当前转录内容。只有当匹配的模型／轮次计数器能够证明某次调用的增量时，才会记录最近一次观测到的模型调用；不会重建整个轮次或历史记录。重复的钩子会使用紧凑的私有检查点和稳定的用量 ID。遇到未知版本、缺少上下文、计数器重置、不安全或过大的文件，以及无法证明的子 Agent 绑定时，系统会放弃捕获。缓存输入和推理输出仍是各自总量的子集。计费端点、层级、区域和订阅模式必须通过显式捕获配置指定；原生模型名称无法确定价格或节省基准。