Control

Shadow Mode

Shadow Mode lets you run Hivenora in your production environment and observe what it would have done — without blocking any agent actions. Use it to validate your policies and understand agent behavior before enabling enforcement.

What Shadow Mode does

When an agent is in Shadow Mode:

Hivenora evaluates the action exactly as it would in enforcement mode.
The evaluation result is recorded in the activity log and Flight Recorder.
The effective_decision is always allow — the action proceeds regardless of what the policy would have decided.
The shadow_result field in the response shows what the actual decision would have been.

Shadow Mode evaluation:

Agent submits action
        │
        ▼
Hivenora evaluates
(intent check, blast radius, policy match)
        │
        ▼
Evaluation result: REQUIRE APPROVAL

        │
        ▼ Shadow Mode — does not enforce

Effective decision: ALLOW  ◄── agent proceeds
Shadow result: REQUIRE APPROVAL  ◄── recorded for review

Shadow Mode response

A typical Shadow Mode evaluate() response:

json

{
  "request_id": "01927a3b-e4f6-7abc-8def-123456789012",
  "decision": "require_approval",
  "effective_decision": "allow",
  "shadow_mode": true,
  "shadow_result": {
    "decision": "require_approval",
    "blast_radius": "critical",
    "reasons": ["Blast radius classified CRITICAL"]
  },
  "blast_radius": "critical",
  "intent_mismatch": true,
  "reasons": ["Blast radius classified CRITICAL — exceeds autonomous action threshold"]
}

Key fields:

shadow_mode: true — always present when the agent is in shadow mode
effective_decision: "allow" — always allow in shadow mode
decision — what Hivenora would have decided in enforcement mode
shadow_result — the full enforcement-mode result for review

Shadow Mode SDK behavior

The SDK returns the response exactly as described above. Your application code sees result.isAllowed === true even when the policy would have blocked — this is intentional. Shadow Mode does not require any application code changes.

typescript

const result = await hivenora.evaluate({
  action: "crm.delete_contacts",
  intent: "Clean old test contacts",
  context: { recordsAffected: 4821, environment: "production" },
});

// In Shadow Mode:
result.shadowMode          // true
result.effectiveDecision   // "allow"
result.decision            // "require_approval" (what would have happened)
result.isAllowed           // true (shadow always allows)

// Agent proceeds — but the evaluation is recorded for review
await deleteContacts();

Security note. Shadow Mode is a deliberate configuration applied per agent in the Control Room. The agent cannot self-declare Shadow Mode — enforcement mode is read from the agent's server-side configuration, not from the client request.

Shadow Report

Open the Shadow Report in the Control Room to see an aggregate view of shadow evaluations:

Total actions observed vs. total that would have been blocked
Total that would have required approval
Breakdown by decision type and blast radius level
Individual events in the activity log with shadow decisions marked

Use this data to tune your policies before enabling enforcement. When you are confident in the policy configuration, switch the agent from Shadow to Enforce mode in the Agents panel.

Recommended adoption path

Register your agent and create an API key.
Set the agent to Shadow Mode in the Control Room → Agents.
Integrate the SDK. Deploy to production.
Run your normal workload for 1–2 weeks.
Review the Shadow Report. Identify policies that are too broad or too narrow.
Adjust policies. Review again.
Switch the agent to Enforce Mode.
Monitor the Activity feed and Approvals queue.

← SDK Reference Security Model →