How ArmorClaude Works
Architecture, intent enforcement, drift detection, trust operations, and the hook system
How ArmorClaude Works
ArmorClaude is a Claude Code plugin that intercepts every tool call via lifecycle hooks. Intent enforcement depends on the active policy and login state. Read tools pass through policy checks without requiring a plan. A policy with default allow and only permit statements, including the fresh-install all-allow policy, records intent without blocking missing plans or drift. An empty default-deny policy does not qualify.
Architecture
User Prompt
|
v
UserPromptSubmit Hook
/armorclaude:armor commands → policy response
Other prompts → inject directive: "register your plan first"
|
v
Claude calls register_intent_plan MCP tool
Plan validated + stored (local or signed JWT)
|
v
Claude calls a tool (Read, Write, Bash, etc.)
|
v
PreToolUse Hook (ENFORCEMENT)
Organization policy check
Read tools: local policy check, no intent-plan requirement
Other tools: local policy, trust and applicable intent checks
Declared input arguments are advisory by default
|
ALLOW or DENY
|
v
PostToolUse Hook
Audit row queued for ArmorIQ (when signed in)Hook Events
ArmorClaude registers 8 lifecycle hooks with Claude Code:
| Hook | When | What ArmorClaude Does |
|---|---|---|
| SessionStart | Session opens | Initialize, show enforcement status |
| UserPromptSubmit | User sends a prompt | Process /armorclaude:armor commands, inject plan directive |
| UserPromptExpansion | Claude expands a command | Record confirmed slash-command activity |
| PreToolUse | Before any tool runs | Enforce: check plan, policy, token, MCP server |
| PostToolUse | After tool succeeds | Send audit log to backend |
| PostToolUseFailure | After tool fails | Send failure audit log |
| Stop | End of a turn | Refresh tokens near expiry and capture transcript model calls |
| SessionEnd | Session closes | Attempt token revocation, remove runtime session state, and close session telemetry |
Daemon Architecture
The hook router tries a long-lived daemon first and falls back to in-process handling if the daemon is unavailable:
Hook event → hook-router.mjs
-> Try daemon socket
-> Fall back to in-processThe daemon is a long-lived Node.js process that keeps SDK clients warm, batches audit logs, and avoids cold-start overhead per hook event.
Intent Drift Detection
When intent enforcement is active, ArmorClaude blocks a tool that is not in its registered plan:
ArmorClaude intent drift: tool not in plan (Bash)This prevents prompt injection from silently steering Claude into unauthorized tool use. Claude sees the denial and either re-registers a new plan that includes the tool, or tells the user it cannot perform that action.
Parameter Enforcement
Plan step arguments can describe expected inputs, but the current configuration sets strictParamCheck: false. Local parameter matching is advisory, so these inputs are not a guarantee that a changed parameter will be blocked. Policy conditions and backend checks are separate controls. Use policy rules to constrain commands, file paths, or hosts.
MCP Server Trust
By default, ArmorClaude requests approval for tools from unknown MCP servers (mcpDenyByDefault). When an unknown server's tool is called:
- ArmorClaude blocks the call and surfaces it through Claude Code's native tool approval UI
- The user can approve the one-time call
- For persistent trust, use
/armorclaude:armor mcp approve <server>
Approved and denied servers persist across sessions.
Token Lifecycle
When signed in, ArmorClaude requests a signed intent token from the ArmorIQ backend:
- Claude calls
register_intent_planwith its tool list - ArmorClaude sends the plan to the backend's token endpoint
- Backend returns a signed intent token with a requested validity of 1 hour
- Each tool call is validated against the plan embedded in the token
- ArmorClaude attempts refresh near expiry during tool checks and at turn boundaries
Without a usable login, plans are stored locally and intent requirements are disabled in monitor mode. Local policy rules still apply. A policy with default allow and only permit statements also captures intent without enforcing missing plans, drift, or token expiry. Reset produces an empty default-deny policy, so it does not enable this exemption.
Trust Operations
Trust operations modify the active intent token without starting from scratch. These are available as MCP tools:
Revoke
Requests revocation of the active token through the backend. Use when the plan has gone wrong. Propagation time depends on the backend and enforcement points; the plugin does not guarantee a fixed fleet-wide deadline.
Re-anchor
Updates the plan without revoking the token. Signs a delta linking the old plan hash to the new one, preserving the tamper-evident lineage in the audit log.
Delegate
Issues a subtree-bounded child token with a Merkle inclusion proof. A sub-agent receives authority confined to a specific part of the plan (e.g., /steps/[1]).
Crypto Policy Binding (CSRG)
When a usable profile key is present, ArmorClaude binds policies using Merkle trees:
- Policy statements are hashed into a Merkle tree
- The policy hash is included in the signed intent token
- At enforcement time, the hash is verified to ensure the policy hasn't been tampered with
- After any policy change, the crypto binding is automatically reissued
Policy binding is separate from CSRG step verification. In this dev configuration, remote step verification is disabled outside local mock mode.
Enforcement Engines
ArmorClaude supports two enforcement engines:
| Engine | Description | When to use |
|---|---|---|
| local (default) | Policy evaluated in-process by the plugin | Single user, low latency |
| opa | Policy delegated to an OPA PDP server | Fleet-wide enforcement, central policy management |
Inspect engine selection instructions with:
/armorclaude:armor settings enforcement opaThe command prints instructions; it does not change the running engine. Set ARMORCLAUDE_ENFORCEMENT_ENGINE=opa and ARMORCLAUDE_OPA_PDP_URL, then restart Claude Code.
Workspace Mode
A signed-in ArmorClaude follows the mode your workspace picks under Tool calls in the chat on the Monitor page of the Tools console. ArmorClaude reads the mode when a session starts, so a change applies from the next session.
| Mode | A call your policy blocks or holds | What the chat shows |
|---|---|---|
| Quiet (the default) | Runs, and is listed under Would have blocked on the Monitor page | Nothing from ArmorIQ |
| Show in chat | Runs, and is listed on the Monitor page | One line on that call: ArmorIQ would block this call in Enforce (<reason>). Monitor let it run. |
| Block | A blocked call stops and a held call asks for approval | The block reason or the approval prompt |
In Quiet and Show in chat nothing is blocked and no intent plan is required. Your policy still runs on every call, which is how the Monitor page knows what Block would have done.
A workspace admin can give one teammate their own mode in the Teammates card on the Monitor page, for example to try Show in chat before the whole workspace does. It applies to sessions signed in as that teammate, and everyone else follows the workspace. Members who are not admins see the modes but cannot change them.
To make one machine block whatever the workspace says, set ARMORIQ_ORG_MODE=enforce.
ArmorClaude 0.2.21 and older
Older versions do not read the workspace mode. While the workspace is in Quiet or Show in chat, ArmorIQ sends them an allow-all policy in place of yours. They run every call and show nothing in the chat, and the Monitor page still lists what your policy would have blocked. Update to 0.2.22 or later for Show in chat.
Fail-Closed
When the workspace is in Block, any of these causes a tool call to be blocked:
- No intent plan registered when the active policy requires it
- Tool not in plan (intent drift)
- Policy rule denies the tool
- Intent token expired
- MCP server explicitly denied
- Internal hook error
While signed in, ArmorClaude queues enforcement audit rows for the backend. Delivery is best-effort. Without a usable login, no production audit upload takes place. Local policy denies and approval requirements still apply in monitor mode.
Whitelisted Tools
These tools are never blocked (they are needed for ArmorClaude to function):
register_intent_plan- Claude needs this to declare planspolicy_read- Policy reading (read-only)trust_revoke/trust_reanchor/trust_delegate- Trust operationsExitPlanMode- Plan mode approvalToolSearch/TodoWrite/ListMcpResourcesTool/ReadMcpResourceTool- Claude Code internals with no side effects
State Management
The daemon maintains in-memory state, with files as the durable backing store. Telemetry also uses bounded obs-journal/ and obs-spool/ queues for replay and background delivery:
| File | What | Lifecycle |
|---|---|---|
runtime.json | Sessions, tokens, plans, discovered tools, trust ops | Removed at session end, after 24h inactivity, or one hour after token expiry |
policy.json | Policy rules + version history | Persistent |
pending-plan.<sessionId>.json, pending-plan.json | Plan awaiting an applicable enforcement-path hook | Removed when consumed |
policy-pending.json | Staged policy proposal (awaiting /armorclaude:armor yes) | Expires after 30 minutes |
policy-drafts.json | Draft policies in progress | Until staged or discarded |
Files live in the active variant's data directory. That is ~/.claude/plugins/data/armorclaude-armoriq/.
Intent Capture
ArmorClaude captures the intent Claude declares during its normal work. It records that intent and checks tool calls against the captured intent and active policies. ArmorClaude does not create the intent or run a separate planning model. Capturing, checking, and requesting signed tokens still take processing time.