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
| Outcome | What you see | Meaning |
|---|---|---|
| Block | The action is refused, with a rule name and a reason | The action violates a rule, so the agent doesn't run it |
| Ask | Claude Code shows a confirmation box | The action is risky, and you decide whether to allow it |
| Mask | Part of the content is replaced with a mask | Guardrails 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
Read the message. It gives the rule id (
id) and the reason.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.
Check Guardrails status on your machine:
bashph guardrails statusThe command tells you whether the hook server is running, which policies apply, and the managed configuration.
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:
bashph 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:
ph guardrails audit --days 7 # counts by rule
ph guardrails audit --rule <rule id> --samples 5 # with a few masked context samplesThis 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.