Policy Rules
Control what tools Claude can use with allow/deny/hold rules managed entirely from the chat prompt
Policy Rules
Policy rules control what tools Claude can use. Rules are evaluated before intent plans - a denied tool stays denied even if it appears in the plan. All policy changes are human-only: Claude can read policy through MCP but cannot update it.
How Rules Work
- Matching deny rules override matching approval and allow rules.
- Matching approval rules override matching allow rules.
- The default decision applies only when no statement matches.
- New rules are appended. Adding an allow rule does not cancel an existing deny or hold.
Rule Effects
| Effect | Keyword | What happens |
|---|---|---|
| Allow | allow | Tool call proceeds |
| Deny | deny, block | Tool call is blocked before execution |
| Hold | hold, require_approval, ask before | Local rule requests approval through Claude Code's native UI after the other checks pass |
An organization policy is checked separately before the local policy. Its block cannot be overridden by a local allow. An organization hold can request approval from another member through the backend and require a retry after approval. This is separate from the native prompt used by a local hold.
Adding Rules
Use /armorclaude:armor policy add to stage a rule change. All changes go through a stage → confirm workflow:
/armorclaude:armor policy add deny WebFetchArmorClaude responds with a diff showing what will change. Then confirm:
/armorclaude:armor yesMultiple Rules at Once
Comma-separate different effects:
/armorclaude:armor policy add allow Read and Grep, deny Write, hold BashThis stages the rules in one proposal. Confirm with /armorclaude:armor yes.
Use Canonical Tool Names
Use exact tool names such as Read, Grep, Glob, WebFetch, WebSearch, Bash, Write, Edit, and Agent in copyable rule commands. Natural-language aliases are not handled consistently by every parser path.
Simple tool lists can be staged directly. Complex conditions or shell-program requests can create a draft instead. Read the response: if it returns a draft ID, run policy stage <draft-id> before confirming. Unsupported tool labels can be rejected.
Setting the Default Decision
The default decision applies when no rule matches a tool call:
/armorclaude:armor policy default denyOptions: allow, deny, hold.
Removing Rules
Remove by rule ID (shown in /armorclaude:armor policy list):
/armorclaude:armor policy remove policy1Reset to no statements and a default deny decision:
/armorclaude:armor policy resetBoth go through the stage → confirm workflow.
Policy Templates
Stage a pre-built policy, then confirm it. Templates also include architect, quality-guardian, velocity-machine, and night-owl:
/armorclaude:armor policy template balanced| Template | Description |
|---|---|
all-allow | Captures intent without blocking missing plans, drift, expiry, or proof failures |
strict-read-only | Only Read/Grep/Glob allowed. Everything else denied |
balanced | Read allowed. Bash/Write/Edit require approval |
lockdown | All tools require approval. Nothing auto-allowed |
Conditions on Tool Arguments
Use the supported condition fields below to restrict shell commands, file paths, hosts, or MCP servers. The command policy add deny * for payment data does not create a supported data-class restriction.
The plugin detects some PCI and PAYMENT metadata, but that metadata is not an enforced condition in the local policy IR. PHI and PII detection is not implemented by this classifier. Do not treat these labels as a data-loss-prevention control.
The Stage → Confirm Workflow
Every policy change is staged before it applies. This prevents accidental changes:
- You type a command (e.g.,
/armorclaude:armor policy add deny Bash) - ArmorClaude stages the proposal and shows a diff
- You review and either confirm or cancel:
| Action | Command |
|---|---|
| Apply staged change | /armorclaude:armor yes or /armorclaude:armor policy confirm |
| Apply by proposal ID | /armorclaude:armor policy confirm pol_abc12345 |
| Discard staged change | /armorclaude:armor no or /armorclaude:armor policy cancel |
Staged proposals expire after 30 minutes if not confirmed. A successful local confirmation can also stage a backend proposal. Confirm that proposal in the dashboard under Policies before relying on it in a new connected session. A failed crypto-binding request can leave the active policy unchanged; inspect the response and policy list.
Proposals include a base version check. If someone else changes the policy between the stage and the confirm, the confirm is rejected to prevent conflicts.
Draft Workflow (Advanced)
For complex policy edits, use the draft workflow:
Validate Pasted JSON
/armorclaude:armor policy draft validate {"schemaVersion":"armor.policy.v1",...}Validates the JSON against the policy schema and creates a draft with a draft_XXXXXXXX ID.
Edit an Existing Draft
/armorclaude:armor policy draft edit draft_abc12345 {"schemaVersion":"armor.policy.v1",...}Replaces the draft's JSON with new validated content.
Revise a Draft
/armorclaude:armor policy revise draft_abc12345 "remove stmt_2"Applies a deterministic edit to a draft (e.g., removing a statement).
Stage a Draft
/armorclaude:armor policy stage draft_abc12345Stages a validated draft for confirmation.
Policy IR Format
Policies use the armor.policy.v1 schema internally:
{
"schemaVersion": "armor.policy.v1",
"kind": "PolicyProfile",
"metadata": { "name": "my-policy", "description": "..." },
"defaults": {
"decision": "deny",
"conflictResolution": "deny_overrides"
},
"statements": [
{
"id": "stmt_1",
"effect": "permit",
"principal": { "type": "agent", "id": "claude-code" },
"action": { "type": "tool", "eq": "Read" },
"resource": { "type": "workspace", "scope": "current" },
"conditions": []
}
]
}Statement Fields
| Field | Description |
|---|---|
id | Unique identifier (e.g., stmt_1) |
effect | permit, forbid, or require_approval |
principal | Who the rule applies to (agent, user, org, role) |
action | Tool matcher - eq for exact, in for list |
resource | Scope (workspace, file, directory, network) |
conditions | Additional constraints (see below) |
Condition Operators
| Operator | Example | Description |
|---|---|---|
eq | bash.program eq "curl" | Exact match |
in | tool.name in ["Read", "Grep"] | Value in list |
not_in | bash.program not_in ["rm", "curl"] | Value not in list |
matches | file.path matches "\.secret$" | JavaScript regular expression |
not_matches | file.path not_matches "\.log$" | Negative regular expression |
starts_with | file.path starts_with "/etc" | Prefix match |
within_workspace | file.path within_workspace true | Lexical path check relative to the workspace |
Condition Fields
| Field | Description |
|---|---|
tool.name | Claude Code tool name |
bash.program | Program being run in Bash (e.g., curl, rm) |
bash.raw | Raw bash command string |
bash.hasWriteRedirection | Whether command writes to files |
file.path | File path being accessed |
network.host | Network host being contacted |
mcp.server | MCP server name |
Viewing and Exporting Policy
| Command | What it shows |
|---|---|
/armorclaude:armor policy list | Human-readable summary with rule IDs |
/armorclaude:armor policy view | Raw policy JSON |
/armorclaude:armor policy export | Full policy state JSON (including version history) |
Crypto Policy Binding
When connected to the ArmorIQ backend, policies are cryptographically bound using Merkle trees. After changing policy, ArmorClaude automatically reissues the crypto binding. To manually rebind:
/armorclaude:armor policy rebindThis ensures the policy hash in the signed intent token matches the active policy.
Where Policies are Stored
Policies persist across sessions in the plugin data directory:
cat ~/.claude/plugins/data/armorclaude-armoriq/policy.jsonSee Configuration for the data directory and its fallback. Policy files survive restarts, plugin updates, and reinstalls unless you explicitly remove the data directory. At the start of a connected session, a confirmed active dashboard policy can replace the local policy.