Guardrails tiers
This page tells you why Guardrails blocked an action, who decides which rules apply, and where to send feedback when something is blocked by mistake. It covers principles only, not each rule in detail.
What Guardrails does
Guardrails is a safety layer for using Claude Code on real source code. It keeps secrets and personal data from reaching the model, keeps data from being pushed out, and records a masked log of every decision. Your day-to-day way of working doesn't change.
Guardrails checks at four points. When you submit a prompt, it can block or record. When an agent is about to call a tool, it can block, ask you, or record. When the tool finishes, it masks sensitive content in the result before the result reaches the model. At session start and end, it only records.
Three components, no new service
Rules are data. They live in a policy package and aren't hard-coded, and the shared engine doesn't know any pattern in advance.
A policy is a resource on Tara. It's a kit that declares metadata.forge.guardrails, so it also goes through checks, review, signing, yanking, and version locking like any other resource. That part is covered in Version locking and digital signatures.
The hook server runs inside Phillip, on your machine. Claude Code calls it through managed settings. It downloads the policy from Tara, then decides and writes the log locally. Only a machine administrator can install it, with sudo ph guardrails install.
Three policy tiers
The platform tier is the floor. PhillipCLI platform staff write it, and it applies to every machine that has Guardrails installed. The organization tier is set by the organization's Admins, and applies to all of the organization's projects. The project tier is set by the Project admin and applies to one project. It is attached to the project's phillip.lock.
The core principle is that each tier can only tighten the tier above it. The platform sets the floor, and an organization or project adds its own extra rules without anyone's review. To loosen a rule, you must request a separate exception (an allow rule), approved by platform staff and recorded in the audit log, with a reason and an expiry date. You can see the three tiers and what is in effect in the Portal under Settings, Guardrails policy. Policies are kit packages you publish like any other resource, with metadata.forge.guardrails.level set to platform, organization or project (a project policy also names its project in project). The older value company still loads: it means platform in the official catalog and organization anywhere else.
Swipe sideways to see the whole diagram.
How the tiers combine
The hook server collects the rules from every tier that applies to the project you're working on, drops the rules that an unexpired exception waives, and then takes the strictest action in this order: block, ask, mask, record.
This way a project policy never removes a platform rule. If you remove the project policy from phillip.lock, you lose only the extra tightening. The baseline stays, and the removal must go through code review.
Who approves which policy
A policy that only tightens needs no review and goes live as soon as it passes the automated checks:
- Platform: only platform staff publish it, into the official catalog (
aiforge/). - Organization: an Owner or Admin of the organization publishes it, whatever the organization's publish role is.
- Project: the Project admin of that project, or an Owner or Admin of the organization, publishes it.
A package with any allow rule loosens the floor, so it is an exception. It waits in the Platform review queue (Settings, Platform review), only platform staff can approve it, and Tara writes an audit entry both when it is submitted and when it is decided. Nobody can approve their own submission.
During checks, Tara classifies each package as tightening or loosening on its own. Authors can't approve their own submissions. Before submitting, check a policy package with this command.
ph guardrails check ./kit-project-policyTo use a project's policy in a repository, bind the folder to the project with ph project use <key>. This writes .phillip/project.json, which you commit so the whole team uses the same project. Phillip then loads the project tier together with the organization and platform tiers. Check which project a folder uses with ph project current.
What happens when the system fails?
Guardrails fails closed. If the hook server stops, or has never loaded a valid platform policy, Claude Code blocks prompts and tool calls instead of letting them through. If a project policy can't be verified, for example because of a bad signature or because it was yanked, it blocks only within that project. Every policy package goes through the same signature and revocation-list checks as other resources.
Logs and data
The log runs on your machine and has secrets masked. See more on the Audit page. Each time Guardrails blocks, asks, or masks, it sends Ryoma a metadata-only event that has the rule ID, decision, severity, repo, and task ID, with no content. Details are in Data collected. The organization's detailed log store, also masked, is off by default until the legal department approves it.
What to do when you're blocked
The block message has a rule ID and a reason. Read the reason first, because in most cases the action really shouldn't be done and you only need to change your approach. If you think the rule blocked by mistake, send feedback with the rule ID.
ph guardrails feedback <rule-id> --note "Why this is legitimate"Feedback is masked before it's sent and reaches Security within a few minutes. Fixing a rule means releasing a new version of the policy package, and your machine loads the new version within about 15 minutes. If you need a temporary exception for a project, ask the lead to write an expiring exception in the project policy. The specific steps are in When Guardrails blocks you.
What Guardrails can't do
Guardrails can't stop someone with machine administrator rights from deliberately bypassing it. That belongs to device management, firewalls, and internal rules.
The hook server runs with the user's permissions. Guardrails has self-protection and reports when the hook server isn't running (see ph guardrails status and ph forge doctor), but it can't replace a firewall or proxy. Recognizing network destinations in shell commands is also only a guess, not a real network barrier.