---
title: Tool Runtime Policy
created: 2026-04-21
updated: 2026-05-02
type: concept
tags: [tool, runtime, agent, backend, config]
sources: [packages/backend/src/modules/netaclaw/tools/manifest.ts, packages/backend/src/modules/netaclaw/tools/runtime_policy.ts, packages/backend/src/modules/netaclaw/tools/presentation.ts, packages/backend/src/modules/netaclaw/service/tool_resolver.ts, packages/backend/src/modules/netaclaw/subagent/process_protocol.ts, packages/frontend/src/modules/agent/tools/runtime-policy.ts]
---

# Tool Runtime Policy

Tool Runtime Policy 是工具重构后新增的运行时策略层。它解决的问题是：工具不仅要知道“是否启用”，还要知道“在当前 Agent、当前子进程、当前 workspace/policy 下到底能不能执行，以及应该在哪里执行”。

它连接 [[tool-system]]、[[tool-governance]]、[[subagent-session]] 和 [[agent-runtime]]。

2026-05-02 后还要区分 [[tool-operations]]：Runtime Policy 决定工具在 worker 视角是本地、主进程代理还是禁用；Operations 决定某个已构建工具的文件系统、进程和搜索调用如何落地。当前实现仍保持工具粒度 route，不把每个 file/process 方法拆成独立权限。

## 三层模型

```text
Tool Catalog / DB Governance
  -> Tool Manifest
  -> Runtime Policy Projection
```

### 1. Catalog / DB Governance

这一层负责工具是否存在、全局是否启用、Agent 是否覆盖、Prompt Hint 如何写入。详见 [[tool-governance]]。

### 2. Tool Manifest

`tools/manifest.ts` 将工具转成稳定画像：

- `kind`: `builtin`、`memory`、`skill`、`delegation`、`admin`、`custom`
- `executionMode`: `parallel` 或 `sequential`
- `supportedInWorker`
- `workerRoutingHint`: `local`、`main-process-proxy`、`disabled`
- `requiresShell`
- `requiresWrite`
- `requiresSkillScope`

这些字段是子 Agent worker 和前端诊断展示的共同语言。

### 3. Runtime Policy Projection

`tools/runtime_policy.ts` 根据 manifest、enabled tool names、disabled reasons、worker policy 推导最终状态：

| 状态 | 含义 |
| --- | --- |
| `worker-local` | 子进程可以本地执行 |
| `main-process-proxied` | 子进程请求父进程代理执行 |
| `disabled-in-worker` | 当前 worker 策略下不能执行 |
| `not-selected` | 没有被选入当前子 Agent 工具集 |

前端再映射为路由：

- `worker-local`
- `main-process-proxy`
- `disabled`

## Worker Policy 自动推导

`buildSubprocessWorkerPolicy` 会从当前 session 和工具 manifest 推导 worker 策略：

- `workspaceRoots`: 来自 `sessionCwd` 和额外 workspace roots，去重后传给 worker。
- `allowShell`: 只有工具确实需要 shell，且策略允许时才为 true。
- `readonly`: 如果没有写工具需求，默认只读；写工具需要显式允许。

这使子 Agent 不需要默认拥有完整宿主进程权限。

## 阻断原因

常见 `blockedReason` 包括：

| 原因 | 含义 |
| --- | --- |
| `workspace_root_required` | 工具需要 workspace root，但当前 session 没有 cwd/root |
| `shell_disabled_by_policy` | `bash` 等 shell 工具被策略禁用 |
| `write_blocked_by_readonly_policy` | 写入类工具被 readonly 策略阻止 |
| `requires_main_process_proxy` | 工具需要主进程代理 |
| `unsupported_in_worker` | 工具没有 worker 支持 |
| `not_selected_for_subagent` | 未被选入子 Agent 工具集 |

这些原因应该在工具管理页、Agent 编辑页、子 Agent 批次详情里使用同一套中文展示。

## 当前内置路由

| 工具类别 | 工具 | 默认路由 |
| --- | --- | --- |
| Worker 本地 | `bash`、`read_file`、`list_dir`、`find_files`、`grep` | `worker-local` |
| 主进程代理 | `write_file`、`edit`、`patch`、`read_skill`、`read_skill_file`、`skill_manage`、`execute_skill`、`memory_save`、`memory_recall` | `main-process-proxy` |
| 强顺序工具 | `edit`、`patch`、`write_file`、`delegate_task`、`delegate_parallel`、`clarify`、`escalate` | `sequential` |

治理层可以通过 `workerRoutingStrategy` 强制覆盖：

- `auto`
- `force-local`
- `force-main-process-proxy`
- `force-disabled`

## 前端一致性要求

这次重构的目标之一是让三处页面一致：

- 工具管理页显示全局治理、核心工具、是否可关闭、运行时画像。
- Agent 编辑页显示当前 Agent 的局部启停、子 Agent 允许工具、有效 runtime profile。
- 对话页显示实际运行时的子 Agent 工具路由和 blocked reason。

这些页面不应各自重新推导规则，而应消费后端 `runtimeDiagnostic` / projection。

## 2026-04-23 动态路由与静态画像的区别

近期实现里，Tool Runtime Policy 需要同时解释两种结果：

- `manifest` / `effectiveRuntimeProfile`：偏静态画像，描述工具理论上支持什么、通常需要什么权限。
- `toolRuntimeRoutes`：偏动态结果，描述在当前 session cwd、workspace roots、allowShell、readonly、selected tools 条件下，这次运行究竟走哪条路。

因此：

- 工具管理页更适合看“画像”和“全局风险”。
- Agent 编辑页更适合看“该 Agent 保存后会生效什么画像”。
- 对话页和子 Agent 批次更适合看“本次任务真正请求到的路由结果”。

如果出现“Agent 编辑页显示允许，但运行时还是 blocked”，优先检查动态 `toolRuntimeRoutes`，不要只盯着静态 manifest。

## Operations 不是 Runtime Policy

[[tool-operations]] 新增后，容易混淆两条线：

- `toolRuntimeRoutes` 是“这个工具在本次策略下能不能进 worker / 是否代理”的决策结果。
- `ToolOperations` 是“工具实例内部调用文件、搜索、进程时走哪个后端”的执行依赖。

例如 `bash` 可以被 Runtime Policy 判定为 `worker-local`，但其具体执行仍由注入的 `ProcessOperations.exec()` 完成；测试环境可以替换为 mock process operations，而不需要改 policy。

## 相关页面

- [[tool-governance]]
- [[tool-system]]
- [[tool-operations]]
- [[subagent-session]]
- [[agent-runtime]]
- [[frontend-architecture]]