Foundations

Flight Modes & Enforcement Levels

Highbeam separates tracking from blocking. A clear priority stack lets you tune alerts from quiet local tracking to automatic cache and loop locks while keeping Ring-0 safety guards active.

1. The Three-Layer Enforcement Hierarchy

Every hook event (PreInvocation, PreToolUse, PreModelSwitch, and PostToolUse) runs as local JavaScript (rule engine under 1 ms; each hook call adds Node startup) inside horizonConfig.mjs, circuitBreakers.mjs, cacheGravityRouter.mjs, and pre_invocation.mjs with zero LLM judge calls.

To pick a verdict (allow, soft advisory warn, interactive ask, or hard deny), Highbeam checks four layers from highest to lowest priority:

  1. Runtime Control Latch (~/.ctxtop/runtime/<sessionId>.ctl): Live session states (PAUSED, STEP, or ABORTED) take effect first before policy rules run.
  2. Per-Detector & Habit Overrides (detectors and semanticDetectors): Project <workspace>/.attention-horizon.json overrides global ~/.attention-horizon/config.json. Custom "off", "warn", or "block" settings beat the active Flight Mode while Ring-0 safety rules stay on.
  3. Top-Level Flight Mode & Host Router Level: Read from flightMode (OFF, SILENT, COACH, AUTO_PILOT) in .attention-horizon.json, V8 Mod state (ah_flight_mode), or daemon POST /api/router/mode. On Google Antigravity, this pairs with hook_level (guard, advisory, off) in default_flightcheck.json and one-turn chat prefixes (!, !force, !lock, #check).
  4. Catalog Default Mode (DETECTOR_CATALOG): Each detector's built-in default as either a blocking guard or a soft advisory tip.
Highbeam Enforcement Precedence Pipeline LAYER 1 (HIGHEST) Runtime .ctl Latch PAUSED / STEP / ABORTED ~/.ctxtop/runtime/*.ctl Halts before tool hooks LAYER 2 Explicit Overrides off | warn | block project > global JSON Survives SILENT / OFF LAYER 3 Flight Mode + Host OFF | SILENT | COACH AUTO_PILOT (Pro check) + hook_level & prefixes LAYER 4 (BASE) Catalog Default DETECTOR_CATALOG guard | advisory Fallback when "default" Resolved Hook Verdict: allow advisory warn ask confirm deny / halt
Highest priority wins, with one firm rule: Ring-0 safety guards stay active unless explicitly turned off in local config where allowed.

2. The Four Flight Modes (OFF, SILENT, COACH, AUTO_PILOT)

Highbeam cleans up flightMode case, hyphens, and spaces in normalizeConfiguredFlightMode() (horizonConfig.mjs) and normalizeFlightMode() (circuitBreakers.mjs). Common aliases work too: DISABLED maps to OFF, QUIET and MUTE map to SILENT, and AUTOPILOT and AUTO map to AUTO_PILOT. Unknown values fall back safely to COACH.

Subsystem / Rule OFF SILENT COACH Default AUTO_PILOT Pro
Ring-0 Security Guards
DET-01, DET-02, DET-18, DET-19
On (blocks unsafe shell, secret reads, bad settings, and prompt injection) On (Ring-0 checks stay active; scanWorkspaceSettings runs) On On
Core Circuit Breakers
DET-03..05, DET-07, DET-12, DET-20
Runs catalog defaults unless overridden Runs catalog defaults with no chat tips On (lockfile ask, 3-strike loop stop, Haiku cliff, file locks) On + locks model and effort when DET-04 or DET-05 trips
DET-08 Warm KV-Cache Switch Hold
PreModelSwitch when cached > C* / C_max
Off (allow) Off (allow) Soft tip suggesting an Explore subagent on claude-haiku-5-5 (allow), plus notableAllowNote at >= $0.02 Active hold using "ask" ("deny" in headless runs or DET-08: "block") when hit is >= $0.02 and H_post < paybackTurns
DET-09 Warm Prefix Fence
CLAUDE.md, AGENTS.md, .mcp.json, effort/thinking
Off unless overridden Off unless overridden Queues in PostCompactMutationQueue and warns (allow) above computeDet09BreakEvenTokens Holds warm-cache rule edits and effort/thinking/speed shifts until PostCompact or TTL == 0s
Semantic Habits
drip-feed, vague-prompt-rubric (DET-14), effort-overkill
Muted Muted Soft 1-line tips (allow) Steps drip-feed (>=4 edits in <90s) up to ask and Turn-1 blind multi-edit to deny
Repeated Full-File Reads
DET-06 Duplicate-Read Guard
Allowed Tracked quietly Shows duplicate-read savings tip Folds 3rd+ unchanged reads into AST stubs and short line diffs
Antigravity PreInvocation
src/hooks/pre_invocation.mjs
Returns {} right away (skips check) Hides scorecard; still runs DET-18 check Uses your hook_level (guard or advisory) Forces hookLevel = "guard"
Telemetry & ah-statusline
ah_live_state_<sessionId>.json
Safety checks only Full stats, status bar, and 30-day Saved Quota Ledger Full stats, status bar, and Saved Quota Ledger Full stats, status bar, and Saved Quota Ledger

Pro Entitlement Check & Safe Fallback

In hooks/handlers/pre-tool-use.mjs, setting flightMode: "AUTO_PILOT" checks requireProFeature("auto_pilot_locks") against your offline Ed25519 key (~/.ctxtop/license.json) or 14-day local trial (npx highbeam-cli license trial). If neither is found, Highbeam drops back to "COACH" in memory so hooks never crash or block your editor, and shows what Auto would have saved. The trial unlocks Auto but does not turn it on: run npx highbeam-cli mode auto. npx highbeam-cli mode shows the configured and running mode; when the trial ends, Auto pauses until you activate Pro.

3. AUTO_PILOT Escalations & Hysteresis Lock

Built into src/core-isomorphic/coach/cacheGravityRouter.mjs, AUTO_PILOT adds four smart safeguards across turns:

Example · Opus 4.7 -> Sonnet 4.6 Switch with 64,000 Warm Cached Tokens (C* = 26,667)
# In COACH mode (non-blocking advisory):
verdict: {
  decision: "allow",
  advisory: true,
  detectorId: "DET-08",
  cStar: 26667,
  cachedTokens: 64000,
  message: "[DET-08 Warm KV-Cache Hold] Prefix (64k > C* 26.7k) is warm ($0.50/MTok reads vs $3.75/MTok cold write). Delegate read-only lookup to Explore subagent on claude-haiku-5-5 (<2k context, 12-turn / 40k-token cap)."
}

# In AUTO_PILOT mode (interactive PreModelSwitch defaults to "ask"; headless uses "deny"):
verdict: {
  decision: "ask",
  blocked: true,
  detectorId: "DET-08",
  coldWritePenaltyUSD: 0.214,
  paybackWarmRequests: 14.2,
  reason: "[DET-08 Warm KV-Cache Hold] Switching from claude-opus-4-7 to claude-sonnet-4-6 with 64,000 warm cached tokens exceeds horizon break-even C_max and incurs +$0.2140 cold 1.25x prefix rewrite penalty."
}

4. Antigravity Router Levels (hook_level), Cooldowns & Chat Prefixes

On Google Antigravity, Highbeam checks user prompts in PreInvocation (src/hooks/pre_invocation.mjs) using settings from config/default_flightcheck.json and ~/.gemini/flightcheck/config.json. The hook_level setting controls how router stops work:

hook_level Router Behavior 3-Turn Cooldown (halt_cooldown_turns: 3)
"guard" Default Stops vague or risky prompts with the 4-Line Scorecard (Context Health, Cache Window, Risk Signal, Recommended Action). In COACH (the default flight mode) only a 3-strike error loop, an explicit #check, or a detector you set to block stops a prompt; every other state shows the scorecard as a message. AUTO_PILOT stops on all of them. After one stop for a given state, repeats within 3 turns step down to a soft { systemMessage } so you never get stuck in nag loops.
"advisory" Never stops a prompt. Every router state adds { systemMessage } quietly as a tip. Always soft until set back to "guard" (or overridden by flightMode: "AUTO_PILOT").
"off" Skips Antigravity PreInvocation checks while PreToolUse Ring-0 safety guards stay on. Not used.

Cooldown Exemptions (Context & Billing Crises)

Three urgent limits carry exemptFromCooldown: true and always fire right away in "guard" mode even inside the 3-turn cooldown (as a message in COACH, as a stop in AUTO_PILOT):

  1. Context Truncation Crisis (amputationCrisis): Active context passes 140,000 tokens, putting early AGENTS.md rules at risk of server-side cutoff.
  2. Warm Cache Loss (DET-08): A mid-TTL switch where rebuilding your cache costs more than staying put.
  3. Haiku 100k 5x Pricing Cliff (DET-12): A Haiku session reaches the 100,000-token price jump.

In-Chat One-Turn Prompt Prefixes

Prefix Scope Behavior
! <prompt> or !force <prompt> Current turn only Skips the PreInvocation scorecard stop (ALLOW_SILENT). Ring-0 PreToolUse safety guards stay on.
!lock <prompt> Active task / session Pins your current model and effort level so router tips do not nudge you down mid-task.
#check <prompt> Current turn only Runs the full 4-Line Scorecard check even when context stats look green.

5. Per-Detector & Habit Overrides (default | off | warn | block)

When global Flight Modes feel too broad, applyDetectorOverride() in src/core-isomorphic/config/horizonConfig.mjs lets you tune any detector (DET-01..DET-20) or habit rule (formatter-bypass, drip-feed, vague-prompt-rubric, effort-overkill, post-commit-handoff, vision-screenshot-coach, micro-skills, relay-breaker):

Surgical Profiles: Explicit Overrides Survive SILENT and OFF

Inside isCoachAdvisorySuppressed() (circuitBreakers.mjs), SILENT and OFF mute rules left at "default", but any rule set to "warn" or "block" in .attention-horizon.json still runs. Teams can run quiet SILENT tracking while still blocking costly cold-cache model switches.

Terminal · Surgical SILENT Profile + Strict FinOps Overrides
# Quiet all default chat coaching while strictly blocking cold-cache switches:
npx highbeam-cli config set DET-08 block
npx highbeam-cli config set vague-prompt-rubric warn
npx highbeam-cli config show --json

# Revert all custom per-detector overrides back to "default":
npx highbeam-cli config reset

6. Switching Modes Across Surfaces

Switch Flight Modes or router levels statically in JSON config files, interactively via the CLI, or live over the loopback daemon API.

<workspace>/.attention-horizon.json (or ~/.attention-horizon/config.json)
{
  "schemaVersion": "1.0.0",
  "flightMode": "COACH",
  "detectors": {
    "DET-08": "block"
  },
  "semanticDetectors": {
    "drip-feed": "warn",
    "vague-prompt-rubric": "default"
  }
}

Inside Claude Code, run /horizon to inspect ah_flight_mode, or manage per-detector rules directly with npx highbeam-cli config set <ID|slug> <default|off|warn|block>. See the full config schema for all threshold keys.