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:
- Runtime Control Latch (
~/.ctxtop/runtime/<sessionId>.ctl): Live session states (PAUSED,STEP, orABORTED) take effect first before policy rules run. - Per-Detector & Habit Overrides (
detectorsandsemanticDetectors): Project<workspace>/.attention-horizon.jsonoverrides global~/.attention-horizon/config.json. Custom"off","warn", or"block"settings beat the active Flight Mode while Ring-0 safety rules stay on. - 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 daemonPOST /api/router/mode. On Google Antigravity, this pairs withhook_level(guard,advisory,off) indefault_flightcheck.jsonand one-turn chat prefixes (!,!force,!lock,#check). - Catalog Default Mode (
DETECTOR_CATALOG): Each detector's built-in default as either a blockingguardor a softadvisorytip.
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 GuardsDET-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 BreakersDET-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 HoldPreModelSwitch 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 FenceCLAUDE.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 Habitsdrip-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 ReadsDET-06 Duplicate-Read Guard |
Allowed | Tracked quietly | Shows duplicate-read savings tip | Folds 3rd+ unchanged reads into AST stubs and short line diffs |
Antigravity PreInvocationsrc/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-statuslineah_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:
- Hysteresis Lock (
HysteresisLock): WhenDET-04(3 tool errors in a row) orDET-05(edit flip-flops) trips during debugging,AUTO_PILOTpins your current model and sets effort to"high". That stops an agent from dropping to a weaker model before the bug is fixed. The lock clears oncecompleteActiveTask()passes, on chat rewind/fork, or viaPOST http://127.0.0.1:62935/api/router/unlock-hysteresis. - Interactive
"ask"Holds & Penalty Floors (DET-08): On Claude CodePreModelSwitchevents,AUTO_PILOTholds usepermissionDecision: "ask"(showing exactcoldWritePenaltyUSD,paybackWarmRequests,paybackTurns, andC_max) when your Claude binary supports it. Headless runs (-p/CLAUDE_HEADLESS) or"DET-08": "block"/autoPilotDecision: "deny"use"deny". Tiny hits underminSwitchPenaltyUSD($0.02) stay quiet. Allowed switches at or abovenotableAllowPenaltyUSD($0.02) show anotableAllowNote, and unknown non-Anthropic model IDs pass through with a soft note (unknownModel: true). - Post-Compact Queue & Dynamic
DET-09Thresholds (PostCompactMutationQueue): Mid-session changes toeffort,thinking,speed,system_prompt,mcp_tools, ormodelreset your warm cache whenttlRemainingSec > 0andcachedTokenssits abovecomputeDet09BreakEvenTokens()(ordet09MinCachedTokens). InAUTO_PILOT, Highbeam queues those shifts and applies them right after/compact(PostCompact) or once the 5-minute (300s) or 1-hour timer ends. - 3rd-Read AST Stubs & Delta Diffs: When an agent reads the same full file a third time in one session,
foldCodeToSignatureStub()andcomputeCompactLineDiff()swap duplicate text for short symbol lists or line diffs since the last read.
# 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):
- Context Truncation Crisis (
amputationCrisis): Active context passes140,000tokens, putting earlyAGENTS.mdrules at risk of server-side cutoff. - Warm Cache Loss (
DET-08): A mid-TTL switch where rebuilding your cache costs more than staying put. - Haiku 100k
5xPricing Cliff (DET-12): A Haiku session reaches the100,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):
"default": Uses the rule's catalog setting (guardoradvisory) and your activeflightMode."off": Turns the rule off (triggered: false, decision: "allow", overriddenByConfig: "off")."warn": Steps a blocking rule down to a soft tip (decision: "allow", blocked: false, advisory: true), adding[Advisory Override (DET-XX=warn)]."block": Steps any soft rule or habit up to a hard block (decision: "deny", blocked: true, advisory: false).
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.
# 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.
{
"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.
{
"hook_level": "guard",
"halt_cooldown_turns": 3,
"warm_cache_lock_tokens": 50000,
"cache_amputation_tokens": 140000
}
Setting flightMode: "AUTO_PILOT" in .attention-horizon.json overrides "hook_level": "advisory" to "guard" automatically. You can also toggle Flight Modes directly inside the Antigravity WebView HUD at http://127.0.0.1:62935.
# Switch live daemon router Flight Mode without restarting sessions:
curl -X POST http://127.0.0.1:62935/api/router/mode \
-H "Content-Type: application/json" \
-d '{"mode":"SILENT"}'
# Response: {"ok":true,"flightMode":"SILENT"}
# Manually release an active HysteresisLock triggered by DET-04 or DET-05:
curl -X POST http://127.0.0.1:62935/api/router/unlock-hysteresis
# Response: {"ok":true,"hysteresisUnlocked":true}
All loopback endpoints bind strictly to 127.0.0.1 with zero outbound network access. See MCP, HTTP Daemon & Micro-IPC for the full 28-route specification.