bonsai3 / Documentation
Policy guide

Writing policies

Use custom policies to give agents guidance for specific tasks or block actions across your organization’s projects.

Create a custom policy

  1. In the dashboard, open Policies → New policy.
  2. Enter a name and choose an effect: Steer supplies guidance, Block returns a denial, and Permit records an explicit allow. When policies overlap, block wins over steer, and steer wins over permit.
  3. Enter one condition per line. Any one condition can make the policy match. The preview uses case-insensitive substring matching, so use specific phrases or filenames that will appear in the intent or tool arguments.
  4. Select Tasks to check task intent, including MCP security_context lookups. Select Tool calls to check a tool’s name and arguments when the agent harness sends a pre-tool request.
  5. Enter concrete guidance for a steer policy, then select Save. New manual policies apply immediately. To change one later, use Edit → Save draft → Publish draft.

Examples you can copy

Enter each listed condition on its own line.

Steer: secure account exports

Policy name
Secure account exports
Effect and timing
Steer · Tasks
Conditions
account export
export account data
Guidance
Authorize exports on the server, scope records to the authenticated tenant, and include only fields the requester is allowed to see.

Try the MCP intent “Build an account export endpoint.” The result should include this policy and its guidance.

Block: protect production configuration

Policy name
Protect production configuration
Effect and timing
Block · Tool calls
Conditions
production.env
Guidance
Leave blank.

In a test workspace, send a pre-tool check for a file operation with production.env in its arguments. The decision should be block; the harness must enforce it before execution.

Permit: document a routine review

Policy name
Permit public changelog review
Effect and timing
Permit · Tasks
Conditions
review the public changelog
Guidance
Leave blank.

Try the matching phrase as an MCP intent and check that the policy appears in the result. The default is already permit when no policy matches; this rule makes the explicit allow visible in the result and audit record.

Check what matched

Try one matching intent and one unrelated intent. In each response, inspect matched_policies. Open Decision activity to see the outcomes. Built-in standard policies can match alongside your custom policies, and edits do not affect decisions until you publish the draft.