ArmorClaudeConcepts

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:

HookWhenWhat ArmorClaude Does
SessionStartSession opensInitialize, show enforcement status
UserPromptSubmitUser sends a promptProcess /armorclaude:armor commands, inject plan directive
UserPromptExpansionClaude expands a commandRecord confirmed slash-command activity
PreToolUseBefore any tool runsEnforce: check plan, policy, token, MCP server
PostToolUseAfter tool succeedsSend audit log to backend
PostToolUseFailureAfter tool failsSend failure audit log
StopEnd of a turnRefresh tokens near expiry and capture transcript model calls
SessionEndSession closesAttempt 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-process

The 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:

  1. ArmorClaude blocks the call and surfaces it through Claude Code's native tool approval UI
  2. The user can approve the one-time call
  3. 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:

  1. Claude calls register_intent_plan with its tool list
  2. ArmorClaude sends the plan to the backend's token endpoint
  3. Backend returns a signed intent token with a requested validity of 1 hour
  4. Each tool call is validated against the plan embedded in the token
  5. 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:

  1. Policy statements are hashed into a Merkle tree
  2. The policy hash is included in the signed intent token
  3. At enforcement time, the hash is verified to ensure the policy hasn't been tampered with
  4. 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:

EngineDescriptionWhen to use
local (default)Policy evaluated in-process by the pluginSingle user, low latency
opaPolicy delegated to an OPA PDP serverFleet-wide enforcement, central policy management

Inspect engine selection instructions with:

/armorclaude:armor settings enforcement opa

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

ModeA call your policy blocks or holdsWhat the chat shows
Quiet (the default)Runs, and is listed under Would have blocked on the Monitor pageNothing from ArmorIQ
Show in chatRuns, and is listed on the Monitor pageOne line on that call: ArmorIQ would block this call in Enforce (<reason>). Monitor let it run.
BlockA blocked call stops and a held call asks for approvalThe 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 plans
  • policy_read - Policy reading (read-only)
  • trust_revoke / trust_reanchor / trust_delegate - Trust operations
  • ExitPlanMode - Plan mode approval
  • ToolSearch / 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:

FileWhatLifecycle
runtime.jsonSessions, tokens, plans, discovered tools, trust opsRemoved at session end, after 24h inactivity, or one hour after token expiry
policy.jsonPolicy rules + version historyPersistent
pending-plan.<sessionId>.json, pending-plan.jsonPlan awaiting an applicable enforcement-path hookRemoved when consumed
policy-pending.jsonStaged policy proposal (awaiting /armorclaude:armor yes)Expires after 30 minutes
policy-drafts.jsonDraft policies in progressUntil 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.

On this page