Skip to content

When Guardrails blocks you ​

When Guardrails blocks an action by the agent, this page helps you understand what happened, see the reason, and send feedback if the block was a false positive. The page covers principles only. It doesn't list specific rules.

What does Guardrails do? ​

Guardrails is a safety layer that your organization sets up and that runs on your machine. It sits between Claude Code and what the agent wants to do, so secrets don't reach the model and data doesn't leave. Your day-to-day way of working doesn't change, and Guardrails doesn't replace your organization's firewall or other controls.

Rules live in policy packages on Tara. Like every resource, they're reviewed, signed, and can be yanked. Policies apply in tiers: the platform sets the baseline, and organizations and projects can tighten it for their own scope. See Guardrails tiers.

The three outcomes ​

OutcomeWhat you seeMeaning
BlockThe action is refused, with a rule name and a reasonThe action violates a rule, so the agent doesn't run it
AskClaude Code shows a confirmation boxThe action is risky, and you decide whether to allow it
MaskPart of the content is replaced with a maskGuardrails detected sensitive information, such as a secret key or an identification number, and masked it before it reaches the model or the log

A block doesn't always mean you did something wrong. Sometimes a rule blocks by mistake, and sometimes the agent picked an approach it didn't need.

What to do when you're blocked ​

  1. Read the message. It gives the rule id (id) and the reason.

  2. Look for another safe way to reach the same goal and ask the agent to take that approach, such as using sample data instead of real data.

  3. Check Guardrails status on your machine:

    bash
    ph guardrails status

    The command tells you whether the hook server is running, which policies apply, and the managed configuration.

  4. If you believe the rule blocked by mistake, send feedback. The owning team reviews it and fixes the rule with a new version of the policy package:

    bash
    ph guardrails feedback <rule id> --note "Why I think this is a false positive"

    Secrets in the note are masked before it's sent, but you should still describe the context and not paste real data.

See the detailed reason on your machine ​

To find out how many times a rule blocked and in what context, use the audit log on your machine:

bash
ph guardrails audit --days 7                  # counts by rule
ph guardrails audit --rule <rule id> --samples 5   # with a few masked context samples

This log lives on your machine and has secrets masked. Through Ryoma, your organization receives only counts by rule and project, with no content. The detailed audit store for the security team works only when your organization turns it on separately. See Data collected.

Don't try to turn off or bypass Guardrails

If you need an exception, ask through your team lead so the organization's or project's policy is updated through the proper process. When the hook server isn't running or no valid policy is present, Guardrails blocks to stay safe (fail-closed). In that case, run ph guardrails status and tell the operations team. See Troubleshooting.

Read more ​