ArmorClaudeGetting Started

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

  1. Matching deny rules override matching approval and allow rules.
  2. Matching approval rules override matching allow rules.
  3. The default decision applies only when no statement matches.
  4. New rules are appended. Adding an allow rule does not cancel an existing deny or hold.

Rule Effects

EffectKeywordWhat happens
AllowallowTool call proceeds
Denydeny, blockTool call is blocked before execution
Holdhold, require_approval, ask beforeLocal 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 WebFetch

ArmorClaude responds with a diff showing what will change. Then confirm:

/armorclaude:armor yes

Multiple Rules at Once

Comma-separate different effects:

/armorclaude:armor policy add allow Read and Grep, deny Write, hold Bash

This 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 deny

Options: allow, deny, hold.

Removing Rules

Remove by rule ID (shown in /armorclaude:armor policy list):

/armorclaude:armor policy remove policy1

Reset to no statements and a default deny decision:

/armorclaude:armor policy reset

Both 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
TemplateDescription
all-allowCaptures intent without blocking missing plans, drift, expiry, or proof failures
strict-read-onlyOnly Read/Grep/Glob allowed. Everything else denied
balancedRead allowed. Bash/Write/Edit require approval
lockdownAll 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:

  1. You type a command (e.g., /armorclaude:armor policy add deny Bash)
  2. ArmorClaude stages the proposal and shows a diff
  3. You review and either confirm or cancel:
ActionCommand
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_abc12345

Stages 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

FieldDescription
idUnique identifier (e.g., stmt_1)
effectpermit, forbid, or require_approval
principalWho the rule applies to (agent, user, org, role)
actionTool matcher - eq for exact, in for list
resourceScope (workspace, file, directory, network)
conditionsAdditional constraints (see below)

Condition Operators

OperatorExampleDescription
eqbash.program eq "curl"Exact match
intool.name in ["Read", "Grep"]Value in list
not_inbash.program not_in ["rm", "curl"]Value not in list
matchesfile.path matches "\.secret$"JavaScript regular expression
not_matchesfile.path not_matches "\.log$"Negative regular expression
starts_withfile.path starts_with "/etc"Prefix match
within_workspacefile.path within_workspace trueLexical path check relative to the workspace

Condition Fields

FieldDescription
tool.nameClaude Code tool name
bash.programProgram being run in Bash (e.g., curl, rm)
bash.rawRaw bash command string
bash.hasWriteRedirectionWhether command writes to files
file.pathFile path being accessed
network.hostNetwork host being contacted
mcp.serverMCP server name

Viewing and Exporting Policy

CommandWhat it shows
/armorclaude:armor policy listHuman-readable summary with rule IDs
/armorclaude:armor policy viewRaw policy JSON
/armorclaude:armor policy exportFull 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 rebind

This 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.json

See 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.

On this page