Tool Policy

Weave uses an abstract tool policy system to control what agents can do. Instead of listing specific tool names, you declare permissions for five high-level capabilities. Adapters then map these abstract capabilities to the concrete tools available in each harness.

All tool policy in Weave is expressed using five abstract capabilities:

These capabilities are harness-agnostic. The engine evaluates policy using only these five keys. Adapters translate them into concrete tool allow/deny/prompt decisions for the specific harness they target.

Each capability can be set to one of three values:

• allow - Grant the capability without prompting
• deny - Block the capability entirely
• ask - Require user approval before granting (default)

When a capability is not explicitly declared in a tool_policy block, it defaults to ask. This ensures that agents never silently gain permissions you did not configure.

If you omit the entire tool_policy block, all five capabilities default to ask.

Tool policy is declared in the tool_policy block of an agent or category definition:

agents:
  researcher:
    prompt: You are a research assistant.
    tool_policy:
      read: allow
      write: deny
      execute: deny
      delegate: deny
      network: allow

In this example:

• The agent can read files and make network requests without prompting
• It cannot write files, execute commands, or spawn sub-agents
• Any capability not listed (none in this case) would default to ask

You can declare only the capabilities you want to change from the default:

agents:
  writer:
    prompt: You are a documentation writer.
    tool_policy:
      read: allow
      write: allow

Here, read and write are set to allow, while execute, delegate, and network default to ask.

Categories can declare tool policy that applies to all agents in that category:

categories:
  research:
    tool_policy:
      read: allow
      network: allow
      execute: deny

Agents in the research category inherit this policy. Generated shuttle-{category} agents also inherit their category’s tool policy.

The engine evaluates tool policy before passing agents to an adapter. The adapter receives:

1. Effective tool policy - A fully-resolved policy with all five capabilities explicitly set (no missing values)
2. Raw tool policy - The original declared policy from your config (may be partial or undefined)

The adapter uses the effective policy to determine which tools to enable, disable, or gate behind user prompts. The raw policy is available for harness-specific translation logic.

For example, an adapter might map:

• read: allow to enabling read_file, list_directory, grep, etc.
• execute: deny to disabling bash, shell, run_command, etc.
• network: ask to prompting before allowing fetch, http_request, websocket, etc.

The exact mapping depends on the harness and adapter implementation. The engine never hard-codes concrete tool names.

Internally, the engine produces an EffectiveToolPolicy for every agent. This is a fully-resolved policy where all five capabilities have explicit values:

type EffectiveToolPolicy = {
  read:     "allow" | "deny" | "ask";
  write:    "allow" | "deny" | "ask";
  execute:  "allow" | "deny" | "ask";
  delegate: "allow" | "deny" | "ask";
  network:  "allow" | "deny" | "ask";
};

The engine computes this by taking your declared policy and filling in ask for any missing capabilities. Adapters receive this complete policy and can apply it directly without re-implementing default-filling logic.

agents:
  auditor:
    prompt: You audit code for security issues.
    tool_policy:
      read: allow
      write: deny
      execute: deny
      delegate: deny
      network: deny

This agent can only read files. All other capabilities are blocked.

agents:
  assistant:
    prompt: You help with general tasks.
    tool_policy:
      read: ask
      write: ask
      execute: ask

This agent prompts before reading, writing, or executing. delegate and network default to ask as well, so all capabilities require approval.

agents:
  builder:
    prompt: You build and test software.
    tool_policy:
      read: allow
      write: allow
      execute: allow
      delegate: deny
      network: allow

This agent can read, write, execute, and make network requests without prompting. It cannot spawn sub-agents.

• Agents - How agents are composed and configured
• Categories - How categories inherit and apply tool policy
• Adapters - How adapters translate abstract policy to concrete tools
• DSL Configuration - Full DSL syntax reference