thearchitectit/agent-guardrails-template/tool-permissions

Tool Permission Control

The pi-guardrails extension enforces tool-level permissions. Before any tool call executes, the permission handler checks whether the tool is allowed, requires confirmation, or is blocked.

Automatic Enforcement

The permission handler runs on every tool_call event before execution:

• auto: Tool executes immediately (no confirmation needed)
• ask: Tool execution is paused and you must ask the user for approval
• blocked: Tool execution is refused with reason

Default Permission Matrix

When You Need Confirmation

If a tool is set to ask level:

1. Stop before executing the tool
2. Explain to the user what the tool will do
3. Ask "Should I proceed with [tool] to [action]?"
4. Wait for explicit approval
5. Execute only after approval — do not assume consent

Session Overrides

Permissions can be adjusted within a session via guardrail_mcp with action set_permission:

action: set_permission
toolName: bash
level: auto
reason: User approved bash for this task

This sets the override for the remainder of the session only.

Configuration

Permissions are configured in .pi-guardrails.json:

{
  "toolPermissions": {
    "defaultLevel": "auto",
    "tools": {
      "bash": "ask",
      "write": "auto",
      "edit": "auto",
      "read": "auto"
    }
  }
}

Organization and team policies can override these defaults — see [[policy-config]].

What To Do When Blocked

1. Do not retry the blocked tool call
2. Inform the user which tool was blocked and why
3. Suggest an alternative approach that uses allowed tools
4. If the block seems incorrect, suggest the user update their permission configuration

References

• [[policy-config]] — How permission policies cascade from org → team → project
• [[guardrails-core]] — Core guardrail tools overview