Policies
A policy is a list of allow and deny rules for what an agent may do. It covers which tools the agent calls, which files it reads or writes, and which subagents and skills it uses. Attach policies to an agent or to a channel record. Unlike hooks, an enforced policy fails closed. If the check fails, the action is refused.
import { defineAgent, definePolicy } from "broods";
export const workspaceGuard = definePolicy({
name: "workspace-guard",
mode: "enforce",
rules: [
{ id: "allow-read", effect: "allow", actions: ["workspace.read"] },
{
id: "deny-secrets",
effect: "deny",
actions: ["workspace.read", "workspace.write"],
resources: { filePaths: ["secrets/"] },
},
{
id: "deny-rm-rf",
effect: "deny",
actions: ["workspace.exec"],
resources: { toolNames: ["bash"] },
conditions: [
{
attribute: "tool.input.command",
operator: "contains",
value: "rm -rf",
},
],
},
{
id: "allow-bash",
effect: "allow",
actions: ["workspace.exec"],
resources: { toolNames: ["bash"] },
},
],
});
export const agent = defineAgent({
name: "agent",
policies: [workspaceGuard],
});
How rules are evaluated
- A
denyrule beats anallowrule. - In
enforcemode, an action with no matchingallowrule is denied. Allow what you want explicitly. - Each policy carries its own
mode:audit, the default, records every decision and blocks nothing. Use it to roll out a rule and watch what it would do.enforceblocks denied actions, and blocks when the policy engine cannot be reached.
- Several policies on one agent can mix modes, so a new rule can watch while an established one enforces.
- Attaching no policies means no checks at all.
Actions
| Action | Covers |
|---|---|
tool.call | Any tool call, including MCP and provider tools |
workspace.read | read, glob, grep |
workspace.write | write, edit |
workspace.exec | bash |
subagent.run | Starting a subagent |
skill.load | Loading a skill |
agent.invoke | Starting a turn from a channel. See channel records. |
Selecting resources
resources narrows a rule with any of toolNames, mcpIds, filePaths, workspaceIds, workspaceNames, skillPaths, subagentIds.
toolNamesare the names the model sees, such asbash,read,googleSearch, or<server>__<tool>for MCP tools.filePathsare workspace-relative prefixes. Writesecrets/, not/workspace/secrets.bashhas no file path. Scope shell commands withtoolNamesand conditions.- A deny on
filePaths: ["secrets/"]also refuses agreporglobrooted above it, including the workspace root, since that search would read the denied files. Search a subdirectory instead. An allow rule does not get that reach.
Conditions
conditions match attributes of the request with an operator and value. Useful attributes:
| Attribute | Value |
|---|---|
toolName, mcpId | The tool and MCP server being called |
tool.input.<field> | A field of the tool input, such as tool.input.command |
tool.inputKeys | Sorted list of input field names |
filePath | The resolved workspace path |
project, stage, agentId | Where the run is |
channel, channelId, threadId | Which chat it came from |
userId, userName, userRoles | Who sent it. userRoles comes from tagRoles on a channel record. |
sandboxPermissionMode | The sandbox's permissionMode |
The full schema, including every operator, is PolicyDocument in the API reference.
Changing and deleting policies
- A policy reference that does not resolve, such as a typo or a deleted policy, makes the agent refuse every action until you fix it.
broods deploywarns when an agent names a policy the deploy does not declare. - Deleting a policy is refused while a saved agent config or channel record lists it.
broods deploy --prunefails for the same reason and names what still uses it.
The policy-enforcement-lambda demo is a runnable example.
Policies decide what an agent does. To limit what a person or tool can do to your account through the API, use roles.