Policy file reference

The runtime reads ${PLUGIN_DATA}/policy.json. If it is absent, the packaged default requests enforce mode, permits capability tiers through payment_execute, and sets no unit prices, caps, explicit denies or session mappings. Licensing still controls the effective mode. A corrupt file causes a recorded fail-open.

A paid operator can set teamPolicyFile or the AGENTGUARD_PLUGIN_POLICY environment variable. Relative paths resolve from PLUGIN_DATA; the environment variable takes precedence. Shared top-level fields replace matching local fields rather than merging nested rules. A local license key is preserved. Free sessions use the personal rules. Burn keeps its separate policy.

Tip

Use identifiers and regular expressions, not document content, prompts or provider credentials. licenseKey is the sole credential exception. Protect policy files from agent modification when they serve as organizational controls.

Root fields

Field	Value and behavior
version	Required integer 1. Other values are invalid.
tenantId	Tenant identifier used in actor scope and cap keys. Default local.
mode	enforce or shadow; omitted means enforce is requested. A usable paid license is required for enforcement.
hookBudgetMs	Positive safe integer for the warm response budget. Default 250. Values above 1900 are capped; invalid values use the default. Cold startup stays at 1500.
licenseKey	License key saved locally by the activation helper. AGENTGUARD_LICENSE_KEY overrides it. Never copy it into a shared policy or receipt.
teamPolicyFile	Paid shared policy path. A relative path starts at PLUGIN_DATA. AGENTGUARD_PLUGIN_POLICY overrides this selection.
defaultMatterId	Default identifier for actor.taskId. A session’s matterId overrides it.
maxCapability	Highest permitted capability tier. Omission adds no ceiling; the packaged default is payment_execute.
allowedTools	Array of tool-name regular expressions. Omission allows tools past this check; an empty array matches nothing. Global and session allowlists both apply.
deniedTools	Array of explicit tool-name deny patterns. Default empty. Independent of costs and allowlists.
ethicalWall	Array of tool-name deny patterns recorded as ethical_wall. Default empty. Does not inspect document content or infer conflicts.
paymentPattern	Case-insensitive expression tested against the provider and tool or model name. Default payment|pay_|charge|transfer|checkout|purchase. A match claims at least payment_initiate.
toolRules	Ordered array of tool rules. Later matching rules replace values they explicitly supply.
caps	Array of spend caps. Matching global and session caps apply together; the most restrictive exceeded action wins.
sessions	Object keyed by actual host session ID. Unknown session IDs use the root rules.

Tool patterns are case-insensitive JavaScript regular expressions. Anchor an exact tool name with ^ and $. Patterns have a 512-character limit. A matching deny or wall remains a restriction even when a monetary cap would allow the call. In shadow mode these checks record what would happen without denying the tool.

Tool rules

Field	Value and behavior
pattern	Required tool-name regular expression, up to 512 characters. Applies to the full name, such as mcp__documents__save_document.
capability	Capability classification for matching calls. Rules cannot lower the built-in classification of a file write or payment-like call.
requiredCapability	Minimum capability claim required by the Spend policy evaluator for matching calls.
unitCostCents	Non-negative safe integer charged once per allowed or shadow call for cap accounting. Default 0. Operator-configured units, not observed provider charges.

Unpriced tools cost zero in this ledger. The accounting uses a synthetic input-token unit in the Spend pricing path; those token counts are not measured model usage. A configured cap cannot limit unknown third-party charges.

Caps

Field	Value and behavior
window	Required: per_call, per_minute, per_hour, per_day or per_month. Fixed windows; the month is a 30-day interval.
amountCents	Required non-negative safe integer. Exceeded when projected configured spend is greater than this amount.
action	block, shadow or allow. Default block. The plugin does not accept the SDK’s downgrade action.
selector	Optional object of exact actor-field matches. Every supplied field must match. Omission shares the cap across the tenant scope.
reason	Optional short identifier forwarded as cap metadata. The displayed reason is a stable policy reason code.

Selector fields

Field	Source and limits
tenantId	The root tenant identifier, default local.
agentId	Host agent_id, then the session’s configured agent ID, then its session ID.
taskId	The session’s matterId or root defaultMatterId.
sessionId	Actual host session ID. Every session-level cap is automatically scoped to its session.
provider	The MCP server segment of mcp__server__tool, or codex for a local tool. The tool segment becomes the model name.
userId, teamId	Accepted by validation, but current plugin calls do not populate them. A selector requiring them does not match.

Selector values must be strings. workflowId is not an accepted plugin cap selector. Identical selector and window combinations share spend.

Session fields

Field	Value and behavior
matterId	Sets actor.taskId for this session, overriding defaultMatterId.
agentId	Operator mapping used when the host does not supply agent_id.
allowedTools	Additional allowlist. A tool must match this list and any root allowlist.
deniedTools	Additional explicit denies. Root denies still apply.
ethicalWall	Additional tool-name wall. Root wall patterns still apply.
maxCapability	Additional tier ceiling. Cannot loosen a more restrictive root ceiling.
caps	Additional caps with the same fields as root caps. The runtime adds the actual session ID to each selector.

Sessions do not override the root mode, license, tool rules or payment pattern. Unknown fields are not a way to add a feature.

Example: a matter budget and an ethical wall

Synthetic identifiers and illustrative amounts. The document save costs two configured cents, the matter cap is 500 cents per day, and the session cap is 50 cents per day. In free mode the same rules produce signed shadow decisions without blocking.

policy.json

{
  "version": 1,
  "tenantId": "example-firm",
  "mode": "enforce",
  "hookBudgetMs": 250,
  "defaultMatterId": "matter-example",
  "maxCapability": "data_write",
  "allowedTools": [
    "^mcp__documents__(search_documents|read_document|save_document)$",
    "^mcp__agentguard__(get_status|list_decisions|verify_chain|export_receipts)$",
    "^update_plan$"
  ],
  "deniedTools": ["^Bash$"],
  "ethicalWall": ["^mcp__restricted_matter__.*$"],
  "toolRules": [
    { "pattern": "^mcp__documents__save_document$", "capability": "data_write", "unitCostCents": 2 }
  ],
  "caps": [
    { "selector": { "taskId": "matter-example" }, "window": "per_day", "amountCents": 500, "action": "block" }
  ],
  "sessions": {
    "session-example": {
      "matterId": "matter-example",
      "agentId": "reviewer-example",
      "ethicalWall": ["^mcp__other_matter__.*$"],
      "caps": [{ "window": "per_day", "amountCents": 50, "action": "block" }]
    }
  }
}

For a read-only review, set that session’s maxCapability to read_only and limit its allowedTools to document reads, planning and the AgentGuard read-only tools. An ethical wall is a list of tool-name patterns, not a content classifier or a conflicts database. Pair it with service-side permissions.