Troubleshooting

"ArmorClaude intent plan missing for this session"

Cause: Claude did not call register_intent_plan before using a tool. This happens when the plan expired or the session just started.

Fix: Re-prompt. Claude will register a new plan.

"ArmorIQ intent token expired"

Cause: The intent token TTL (10 minutes) expired before Claude finished executing. Most prompts finish well within this window, but very long multi-step plans with extended thinking time can hit it.

Fix: Restart your prompt - Claude will register a fresh plan. The plugin auto-refreshes tokens at the turn boundary, so this should rarely surface in practice.

If you need to extend the TTL for a long-running workflow, edit scripts/lib/config.mjs in the plugin install dir and raise validitySeconds above the current 600s default - for example 900 (15 min).

"ArmorClaude intent drift: tool not in plan"

Cause: Claude tried to use a tool it did not declare in its plan.

Fix: This is working correctly. Intent drift detection is blocking an unplanned tool. Claude should re-register a plan that includes the tool, which it usually does automatically on retry.

"Policy denied path /steps/[0]/tool"

Cause: The backend's OPA policy is denying tool calls at token issuance time. This happens when your ArmorIQ tenant has blocking policies with no allow-rules.

Fix: Configure allow-rules in your ArmorIQ tenant dashboard at https://platform.armoriq.ai. The plugin no longer exposes a runtime toggle to disable CSRG verification - it's always-on once an API key is set.

Hook errors on session start

Cause: Plugin dependencies corrupted or partially installed.

Fix:

cd ~/.claude/plugins/marketplaces/armoriq
rm -rf node_modules
npm install --omit=dev

Then restart Claude Code.

"Plugin not found in marketplace" on install

Cause: The armoriq/armorClaude GitHub repo is private and your machine does not have access.

Fix: Either make the repo public (recommended for open distribution) or authenticate with gh auth login using an account with org access.

Policy commands do not show feedback

Cause: In Claude Desktop, the UserPromptSubmit hook results may not always surface visually on the first try.

Fix: The policy IS being set correctly (test with Policy list). If the first response does not show confirmation, the rule is still active.

Token says "Token valid 60s" but expires too fast

Cause: Older version of ArmorClaude with 60-second default TTL.

Fix: Update the plugin:

claude plugin update armorclaude

The latest version defaults to 600 seconds (10 minutes).

Plugin works in CLI but not Desktop

Cause: Desktop may have a cached older version of plugin files.

Fix: Restart Claude Desktop completely (Cmd+Q on macOS, not just close the window), then reopen.

"armoriq: command not found" after install

Cause: Global npm install failed (permissions issue).

Fix:

npx @armoriq/sdk-dev login

Or fix permissions:

sudo npm install -g @armoriq/sdk-dev

Debug Mode

To see what ArmorClaude is doing:

export ARMORCLAUDE_DEBUG=true
claude

Debug output goes to stderr. You will see hook events, plan registration details, policy evaluation results, and backend API calls.