Agent Firewall

The agent-firewall policy evaluates extracted tool actions and returns a tool-phase decision. It supports glob-based allow/deny checks, per-request action caps, per-action counters, transaction thresholds, a suspicious-pattern kill switch, and optional PII scanning in tool-call arguments.

Phase and verdicts

• Phase: tool
• Possible verdicts: allow, block, escalate

Configuration

Use one declarative shape per policy block. The public schema treats the simple allow/deny shape and the expanded governance shape as distinct alternatives; do not mix them in the same agent-firewall block.

pack:
  name: agent-firewall-example
  version: 1.0.0
  enabled: true
policies:
  chain:
    - agent-firewall
policy:
  agent-firewall:
    tools:
      roles:
        analyst:
          allowed:
            - read_database
            - export_csv
          denied:
            - delete_database
    rate_limits:
      export_csv: 1
    transaction_limits:
      max_single_transaction: 5000.0
      max_daily_total: 20000.0
      require_approval_above: 1000.0
    kill_switches:
      halt_on_suspicious_pattern: true
      halt_on_pii_in_action: true

Supported fields

Field	Type	Default	Notes
allowed_tools	string[]	[*]	Simple shape only. Supports * glob matching.
blocked_tools	string[]	[]	Simple shape only. Supports * glob matching and takes precedence over allows.
max_actions_per_session	integer	disabled when omitted	Available in both shapes. Uses assistant-message count as the session proxy.
rate_limits.default	integer	—	Expanded shape only. Used as a fallback action-count cap for the current evaluation.
rate_limits.<action>	integer	—	Expanded shape only. Blocks when a specific extracted action appears more than the configured count.
transaction_limits.max_single_transaction	number	0.0	Expanded shape only.
transaction_limits.max_daily_total	number	0.0	Expanded shape only. Compared against total detected dollar amounts in the joined message text.
transaction_limits.require_approval_above	number	0.0	Expanded shape only. Returns escalate when a detected amount meets or exceeds the threshold.
tools.roles.<role>.allowed	string[]	[]	Expanded shape only. Supports * glob matching.
tools.roles.<role>.denied	string[]	[]	Expanded shape only. Supports * glob matching.
kill_switches.halt_on_suspicious_pattern	boolean	false	Expanded shape only. Blocks only when enabled and a suspicious tool pattern is detected.
kill_switches.halt_on_pii_in_action	boolean	false	Expanded shape only. Scans tool-call message content for PII.

How it works

1. The gateway extracts tool actions from the message set.
2. It resolves the current role from request/context headers when tools.roles is configured.
3. It blocks if kill_switches.halt_on_suspicious_pattern is enabled and a suspicious tool pattern is detected.
4. It enforces session or per-action caps using max_actions_per_session in the simple shape, or rate_limits in the expanded shape.
5. It checks detected dollar amounts against transaction_limits and can return escalate for approval thresholds.
6. It optionally scans tool-call argument content for PII when kill_switches.halt_on_pii_in_action is enabled.
7. It applies glob-aware blocked_tools, role denies, role allows, and allowed_tools checks.

Important behavior notes

• Tool patterns support * wildcards, including prefix, suffix, and infix patterns such as report_* or *_delete_*.
• monitoring and kill_switches.max_errors_before_halt are not used by this policy.
• rate_limits are evaluated against the current request's extracted actions, not a persisted RPM bucket.
• The policy returns escalate only for transaction_limits.require_approval_above.

Example scenarios

Block a dangerous tool

policy:
  agent-firewall:
    blocked_tools:
      - rm_rf

Require approval for large transfers

policy:
  agent-firewall:
    transaction_limits:
      require_approval_above: 1000.0

Scan tool arguments for PII

policy:
  agent-firewall:
    kill_switches:
      halt_on_pii_in_action: true

Best practices

• Prefer exact action names when possible; use narrow * patterns only where a tool family shares a stable naming convention.
• Prefer blocked_tools for immediately unsafe actions and tools.roles when you need role-aware controls.
• Treat max_actions_per_session and rate_limits as request/runtime safety caps, not durable rate limiting.
• Use require_approval_above for high-value transactions where human review is mandatory.

Next steps

• Prompt Injection policy — block malicious prompts before tool evaluation
• RBAC policy — identity and role controls alongside tool checks
• Policies overview — policy chain architecture