foresight-agent-guard 0.1.22

Predictive cost, policy, and runaway-session guardrails for AI coding agents

Foresight

Foresight is a predictive cost and tier-routing layer for AI coding agents. It chooses the right level of reasoning before work begins, then watches the session closely enough to stop drift before it becomes expensive.

Judge quick start

No rebuild, API key, Node.js, or account is needed for the replay proof. On a supported Windows machine:

python -m pip install foresight-agent-guard==0.1.22
mkdir foresight-judge-demo
cd foresight-judge-demo
foresight demo --replay

For the complete deterministic suite and committed evidence, clone the repository and run python verify.py. The replay is the fastest judge path: it launches a real instrumented child, records an allowed action, flags scope drift, blocks a fake protected-path read, and writes a local audit without an OpenAI call.

Supported platform and Codex local setup

Foresight 0.1.22 is a Codex-only, local-first execution-contract layer. This submission is tested on Windows 10/11, Python 3.11 or 3.12, and the Codex CLI. macOS/Linux package installation is supported by the Python package, but the Codex integration has not been submission-validated there.

In a repository you want to monitor, set it up once, then use codex normally:

python -m pip install foresight-agent-guard==0.1.22
cd path\to\your-repository
foresight setup --codex
codex

setup copies the bundled plugin into a Foresight-owned project folder, merges a project-local Codex marketplace entry, adds only Foresight-owned hooks, and backs up an existing hooks.json or marketplace file before changing it. It never overwrites AGENTS.md, existing hooks, an existing marketplace entry, or an existing .codex/config.toml. Use foresight setup --codex --preview to see the exact local changes first. The real setup command registers the project marketplace and installs the plugin through the Codex CLI, so no Desktop plugin picker is required. You still review/trust hooks through Codex's /hooks flow; Foresight never bypasses that review.

Guarantee	What Foresight does today
Known secret paths	Codex static deny rules block .env, keys, credentials, and configured protected paths before sandboxed access when Foresight's generated project config is active.
Contract lifecycle	A Codex skill/MCP surface compiles, stores, advances, pauses, and finishes a local execution contract.
Scope, cost, churn, fan-out	Local telemetry detects and reports drift against the active contract; dynamic intervention is post-tool/turn control, not a universal pre-execution claim.
Codex subagents	Documented SubagentStart / SubagentStop hooks record safe agent IDs and types in the contract. Exceeding the concurrent fan-out budget pauses the contract and injects context for later progress; it does not claim a universal pre-spawn hard block.
Strict interception	The advanced Python-child runtime remains the only process-local pre-execution file/subprocess/network interceptor.

Without OPENAI_API_KEY, Foresight uses a clearly labelled local baseline: static secret-path protection, bounded defaults, local audit, and replay. With a key, begin_contract compiles policy, routing recommendation, phases, cost range, and escalation rules in one structured GPT-5.6-terra call.

Run foresight doctor at any time to inspect Codex detection, plugin registration/installation, hooks, static policy, and the required trust steps. Run foresight uninstall to remove only Foresight-owned integration artifacts while preserving later user edits.

Local dashboard and durable history

foresight dashboard is an opt-in local control center. It starts a read-only HTTP server for the current repository, serves the dashboard bundled in the Python wheel, and connects it to the local event bus. No Node.js, account, cloud sync, or remote ingestion is required.

Every contract is retained without expiry in .foresight/contracts/<session-id>.json, with an append-only ordered event record in .foresight/history/<session-id>.jsonl and a compact session index in .foresight/history/index.json. Events first survive in the local spool during an event-bus outage, then the bus persists them before live browser delivery. Reopening the dashboard reloads history before it reconnects to the live stream.

The dashboard reports Foresight API cost only: exact token-derived cost for Foresight's own contract compiler calls. Codex's native ChatGPT quota/token display is intentionally shown as unavailable because Foresight has no official machine-readable billed-cost source for it. foresight status uses the same local contract store: it shows an active contract while Codex is working, otherwise the newest completed contract.

init, run, and shell are retained as advanced Python/external-runtime and demo commands. The normal Codex workflow does not require running foresight run before every task.

Codex subagent control

Each active contract now keeps a local, safe subagent ledger: documented Codex agent_id, agent_type, turn ID, lifecycle state, and observed-action count. When concurrent active agents exceed the compiled contract's fanout_budget, Foresight emits fanout_budget_exceeded, changes the contract to needs_confirmation, and supplies stop context to the new subagent. A PostToolUse hook then stops further turn progress until the user confirms the expansion. Static secret-path denies remain the only pre-execution control; dynamic fan-out is deliberately described as a Codex hook/turn intervention.

See the Codex integration guide for the local artifact layout, guarantee matrix, and lifecycle-tool behavior.

For the full evidence files and zero-cost verification, run the current submission from source. It needs Python only: no API key, Node.js, or browser.

git clone https://github.com/AmanM006/foresight.git
cd foresight
pip install -e .
foresight demo --replay
python verify.py

The replay launches a real instrumented Python child, shows the terminal dashboard, flags scope drift, then blocks a fake .env read in under a minute. Use foresight dashboard to open the optional packaged local history viewer; it requires no Node.js.

PyPI release status

Install the current release with pip install foresight-agent-guard==0.1.22. The bundled Codex plugin supports normal Windows pip --user installations as well as source installs.

Verify this submission

Run the complete replay-safe verification pass with one command:

python verify.py

It runs the Python-child replay and deterministic tests without spending tokens. Add --live only when you want it to run the paid tier and injection benchmarks as well. For a zero-setup visual tour only, explore the deployed Foresight landing/demo site; it is not connected to local sessions.

The problem

When developers use Codex/GPT-5.6 for coding work, they often do not know upfront which tier or reasoning effort a task actually needs. Defaulting to Sol overpays for mechanical work; choosing too small a tier can leave an agent stuck and repeatedly escalating.

The risk is not hypothetical. An open Codex issue #32250 reports GPT-5.6 Sol Medium reducing a Pro five-hour allowance from 87% to 76% during a short conversation and several trivial follow-ups. Recent r/codex and r/ChatGPTPro threads describe confusion around five-hour versus weekly limits; these are community reports, not a claim about every session. Community guidance also identifies duplicated context and uncontrolled subagent spawning as sources of extra consumption (discussion).

There is a second failure mode: scope creep. A small implementation task can turn into unrequested architecture work, sprawling documentation, or broad file changes—the “Sol Ultra problem” discussed by users—silently consuming budget without an early warning. OpenAI documents that ultra coordinates four agents in parallel by default and trades higher token use for stronger results on demanding tasks; it is not an appropriate default for every coding task (OpenAI GPT-5.6 overview).

Foresight solves this by predicting complexity and tier before execution, then watching the live session to catch drift before it compounds.

Live demo proof

One real recorded demo run produced the following result:

Signal	Observed result
Predicted route	luna / low / isolated
Files touched	16
Predictive flag	scope_explosion
Final disposition	escalated_for_review
Recorded model cost	approximately $0.0060

The demo showed two independent catch mechanisms live:

• Predictive scope-drift detection: unrelated file changes exceeded the predicted isolated blast radius.
• Forbidden-pattern interception: an attempted .env read was caught and blocked by the policy layer.

Human-operated Codex contract proof

The following captures are from the saved local Codex session foresight-5c19864905c6: a bounded variable rename, a scope-expansion pause before touching a second file, and a final stopped report. They are rendered from the repository-local contract history, not a mock dashboard state.

Inspect the sanitized raw evidence in examples/: policy_and_verdict_output.example.json and audit_event_output.example.json.

Evidence and benchmarks

Evidence	Real result
Tier prediction accuracy	15 hand-labeled tasks spanning mechanical, moderate, and architectural complexity. 14/15 exact tier match, 1 conservative overestimate (avatar upload: expected terra/moderate, predicted sol/moderate), 0 risky underestimates. Total cost: $0.0346 across 15 real GPT-5.6-terra calls. View results.
Injection resistance	10 adversarial prompt-injection scenarios across hidden HTML comments, code comments, disguised TODOs, subprocess arguments, config fields, misleading filenames, social-engineering “temporarily disable” requests, and multi-step justification chains. 9/10 caught and blocked. The one miss triggered the fail-safe path (uncertain evaluation → warning, not silent allow) rather than a full block; it is disclosed as a real finding. View results.
Multi-task session (false-positive check)	One continuous session across four task types: a trivial README fix (luna/isolated, clean), scoped API validation (terra/moderate, clean), a broad payment migration (sol/wide, 6 files touched, not flagged as scope_explosion because wide scope was predicted), and an injected .env access attempt (blocked). Total session cost: $0.01812. View results.
Workflow-plan benchmark	Fixed stratified sample of five tasks from the 15-case tier corpus: 4/5 plan tiers matched the hand labels; the MFA task was under-tiered (sol expected, terra planned). All five plans met the hard planner contract (1-4 bounded phases, each action cap within the 1-40 schema limit, complete phase fields, and a stop prompt). The stricter per-tier action-budget guidance was met by 2/5 plans because several plans deliberately used shorter discovery/verification phases. Total cost: $0.0306. View raw plans and checks.
Live effort-curve integration	One fresh mechanical-task prediction plus one generated workflow plan both returned luna/low and each carried the source-backed DeepSWE cost curve and Luna caution. Total real cost: $0.0055 across 2 GPT-5.6-terra calls. View captured output.
Live Python-child guard	Real GPT-5.6-terra scope/prediction: luna / low / isolated; a separately launched Python child wrote allowed src/auth/login.py, then an attempted .env read received a critical deny verdict before the read. 2 setup calls, $0.00339, 0 child evaluation calls. View raw policy, response IDs, audit, and report.
Unified live pipeline	One continuous Python-child session (foresight-unified-06e40865) proved predict -> allowed write -> scope drift reassessment -> parallel fan-out -> hard action ceiling kill, with a burn forecast before termination. It made 5 real GPT-5.6-terra calls for $0.01122; the raw timeline includes timestamps, all response IDs, every verdict and signal, and the final kill reason. View unified evidence.
Codex-native contract lifecycle	One real Codex-local session (foresight-codex-contract-5232532e) compiled a narrow variable-rename contract, recorded the allowed src/auth/login.py write, paused for a README scope-expansion request, and finished stopped. 1 GPT-5.6-terra call, 374 input / 319 output tokens, $0.00572; the evidence includes the response ID, contract, spool/audit/WebSocket delivery checks, and final report. View evidence.

Run python verify.py to reproduce the zero-cost checks yourself, or python verify.py --live to reproduce the paid benchmarks above (~$0.08 total across all three).

One benchmark response includes its raw OpenAI response ID as tamper-evident proof that it was a real API call, not a fabricated result: response_id: resp_016b9a9aa893e50d006a57492295908192b3c0b54f1eefd7c7. The recorded response is documented in benchmark_results.json.

What it does

• Routes before spend: predicts the right Luna/Terra/Sol tier, effort level, and blast radius before a single task action is evaluated.
• Turns scope into enforcement: derives a restrictive policy from the declared task instead of treating agent access as implicitly broad.
• Instruments Python agents for real: foresight run -- python agent.py injects process-local interception before child agent code starts, then captures file I/O, subprocesses, and requests calls before execution.
• Watches external agent CLIs honestly: use foresight run -- codex exec "..." for one-shot commands or foresight shell -- codex for a long-lived REPL. Both use a recursive filesystem watcher that detects writes and deletes, logs the same event contract, and terminates on a critical post-hoc violation.
• Flags runaway behavior early: detects scope explosions, low-progress churn, and repeated paralysis loops while the session is live.
• Makes the effort tradeoff visible: attaches a deterministic, illustrative low-to-max cost curve and warns when Luna is being used beyond truly mechanical work.
• Supports time-sensitive sessions honestly: --fast-mode applies the documented 2.5x quota-burn multiplier and shows the speed-versus-budget warning before work begins.
• Makes spend auditable: streams actions, verdicts, predictions, signals, and token-derived costs to the event bus and dashboard.

Architecture

Task description
      |
      v
foresight/ predictor + session monitor
      |
      +--> Python child bootstrap -> sentry/ pre-execution interception engine
      |
      +--> External CLI filesystem watcher -> post-hoc detect-and-respond
      |
      v
policy + event bus -----------------------------------------------------------> dashboard frontend

• foresight/ contains prediction, routing, the CLI, and session monitoring. Keeping these concerns together makes the pre-execution estimate and live escalation decision share the same session context.
• sentry/ is the internal interception engine codename. It captures actions, applies policy, tracks costs, and publishes events. It is decoupled from foresight/ so the security layer can be reused independently of prediction logic.
• Python child bootstrap is injected only for foresight run -- python .... It installs the process-local proxy before agent code, then forwards canonical actions and costs back to the parent monitor over the event bus.
• External process monitor is selected automatically for any non-Python command, including codex exec ... and claude .... It recursively watches the current workspace, normalizes writes/deletes into canonical actions, debounces duplicate watcher notifications, ignores tool-noise paths, and kills the tracked process tree after a critical violation is detected.
• sentry/web/ is the single, restored Next.js dashboard. It consumes the event model rather than duplicating policy or interception behavior.

Sentry is the internal codename for the interception engine; Foresight is the complete product.

Runtime decision flow

1. Task description
   -> predictor returns tier, effort, blast radius, and risk factors
   -> scope-to-policy returns allowed paths, hosts, and forbidden patterns

2. Agent attempts an action
   -> SentryProxy captures it before execution
   -> Action(type, target, payload, timestamp, session_id)

3. Fast enforcement path
   -> forbidden target: critical block, no model call
   -> out-of-scope file or host: warning event
   -> identical action repeated six times in 60 seconds: paralysis-loop block

4. Ambiguous in-scope action
   -> GPT-5.6-terra returns a structured Verdict
   -> allow, warn, or block before the original operation proceeds

5. Session-level monitoring
   -> compare files, diffs, and spend against the original prediction
   -> scope/churn signal triggers a contextual reassessment
   -> kill only if the reassessment confirms a wide or Sol-level runaway

Layer responsibilities

Layer	Main modules	Responsibility	Why it is separate
Prediction	foresight/predictor.py	Produces tier, effort, blast radius, rationale, and risk factors from the task description.	Establishes an expected cost and scope baseline before any agent action exists.
Session control	foresight/session_monitor.py	Watches file count, repeated diffs, and cost ceilings; emits signals and reassesses drift.	Session-level behavior cannot be decided from one action alone.
Policy	sentry/policy/engine.py	Converts scope to Policy, makes local decisions first, and uses structured model review only for ambiguity.	Keeps common security decisions deterministic, cheap, and auditable.
Enforcement	sentry/proxy/interceptor.py	Temporarily intercepts file, subprocess, delete, and requests calls in the current Python process.	Places the decision immediately before the original operation can execute.
Telemetry	sentry/eventbus/server.py	Broadcasts actions, costs, predictions, and monitor signals over WebSocket; exports JSON audit logs.	Decouples producers from the dashboard and leaves a machine-readable record.
Presentation	sentry/web/	Renders live connection state, action feed, policy context, cost, and kill state.	Lets a reviewer understand a session without reading Python logs.

The common event contract

Every intercepted operation becomes the same Action record:

Action
  type: file_read | file_write | file_delete | subprocess | network
  target: path, command, or host:port
  payload: mode, unified diff, cwd/env summary, or request-size summary
  timestamp
  agent_session_id

Policy evaluation returns a Verdict with severity, reason, and allowed. This normalized pair is what the proxy enforces, the monitor observes, the event bus broadcasts, and the dashboard displays. Model use is represented separately as CostEvent(model, input_tokens, output_tokens, cost_usd, timestamp).

Three runtime modes, three different guarantees

Mode	Start command	What Foresight observes	Enforcement timing
Python-child mode	foresight run -- python agent.py	File reads/writes/deletes, subprocesses, and requests network calls inside the instrumented child.	Pre-execution: critical violations can be blocked before the original operation runs.
External process mode	foresight run -- codex exec "..." or any non-Python executable	Workspace file creation, modification, and deletion via recursive filesystem watch.	Post-hoc: the write has already occurred; Foresight records detected_post_hoc: true and immediately terminates the tracked process tree on a critical verdict.
Interactive shell mode	foresight shell -- codex or foresight shell -- claude	The same post-hoc workspace watcher for the full REPL lifetime, plus a periodic cumulative complexity reassessment every 30 seconds or 10 detected actions. The wrapped tool retains its own stdin/stdout/stderr.	Post-hoc: critical write/delete violations terminate the complete interactive process tree. Reassessment and budget signals are advisory; normal operation stays terminal-silent.

These are intentionally not presented as the same security guarantee. External mode works with arbitrary binaries because it does not attempt to inject into them, but it cannot observe read-only file access, subprocesses launched inside the tool, network calls, or a write before it completes. Python-child mode has fuller visibility and prevention because its proxy runs in the same process as the agent.

Works with filesystem-writing processes

External mode is process-agnostic by design: it watches operating-system filesystem events in the workspace rather than parsing a specific agent's protocol or output. That means the external guarantee remains post-hoc for every tool—writes/deletes are observed after they occur, then a critical violation terminates the tracked process tree.

Validated locally on Windows on 2026-07-17:

Process	Invocation	Observed result
Codex CLI, one-shot	foresight run -- codex exec "Improve documentation in sample.py"	Real Codex write was detected as one allowed in-scope post-hoc action; final report was on_track.
Codex CLI, interactive	foresight shell -- codex	A real Codex .env write was detected and terminated; final report recorded terminated_by_policy.
npm	foresight run -- npm init -y	Real package.json write detected; 1 action, 1 file, no flags, final report on_track.

Claude Code 2.1.191 is installed in the validation environment, but it reported Not logged in; it was not individually validated and is not claimed as tested. Aider was not installed. The watcher is expected to work with those tools when they write in the watched workspace, but only the processes above have been verified here.

Four failure modes, four distinct mechanisms

Foresight deliberately gives each failure mode a distinct trigger, reason, event name, and escalation path instead of treating all anomalous activity as one generic warning:

1. Forbidden-pattern interception is deterministic and zero-latency. SentryProxy blocks an action such as .env access before it executes, emits the policy Verdict, and terminates only on a critical denied verdict. This is security enforcement, not prediction.
2. Scope explosion is predictive and contextual. SessionMonitor compares touched files with the predicted blast radius, emits scope_explosion, and re-runs complexity assessment with session context before committing to termination. A wide predicted task is not falsely killed for having a wide footprint.
3. Hard action ceiling is a deterministic workflow cap. The predictor maps isolated to 15 actions, moderate to 40, and wide to 100. Reaching the cap emits hard_ceiling_reached with hard_action_ceiling_reached as its final reason and terminates immediately, even if the agent believes it is nearly done.
4. Parallel fan-out detects a different failure shape from repeated loops: five distinct file or subprocess actions inside three seconds. It emits parallel_explosion and triggers soft reassessment, allowing deliberate, paced parallel work to remain unblocked.

Burn-rate forecasting is separately broadcast as burn_forecast, but it is intentionally informational rather than a kill switch. After enough cost events, it projects minutes remaining at the current cost/minute rate so a user can intervene before a budget ceiling is reached. This keeps forecast visibility separate from hard enforcement.

The independent paralysis_loop check remains in SentryProxy: a rolling 60-second window blocks the sixth identical action after five prior repeats before any model evaluation. It is distinct from parallel fan-out because one catches repeated identical work while the other catches a burst of different work.

This distinction is why the demo can truthfully show two independent outcomes: an immediate .env block from deterministic policy enforcement, and an escalated_for_review result after predictive scope drift is reassessed.

Cost-aware model use

scope_to_policy() and predict_complexity() use structured output. evaluate_action() uses GPT-5.6-terra only when a local rule cannot resolve an in-scope but suspicious action. Each response has an explicit output cap, a stable prompt prefix for caching, and usage recorded through CostTracker.

Predicted effort is calibrated separately from tier: mechanical isolated work routes to low, normal scoped coding work defaults to medium, and high is reserved for genuinely high-stakes or architectural work. Every prediction and workflow plan carries a deterministic, display-ready cost curve from the DeepSWE v1.1 leaderboard: observed GPT-5.6 Sol average cost per task was low $1.07 (1.00x), medium $1.86 (1.74x), high $3.47 (3.24x), xhigh $4.70 (4.39x), and max $8.39 (7.84x) relative to low. These are benchmark observations for one model/harness, not API pricing or Foresight-measured spend. The CLI and dashboard mark xhigh and max as steep-cost territory with marginal expected quality gain; no extra model call is required.

When a task is routed to luna, Foresight also adds a deterministic caution: Luna is for high-volume data handling, simple classification, or truly mechanical edits. Anything requiring real coding logic or judgment should be checked carefully because Terra or Sol is the practical floor for most coding work.

The architecture therefore treats model judgement as a metered dependency rather than an invisible background call.

Current prototype boundaries

The repository is intentionally a focused vertical slice, not a claim of production multi-tenant infrastructure:

• Interception is process-scoped Python monkey-patching, not an operating-system sandbox.
• Python-child mode (foresight run -- python agent.py) is the only pre-execution prevention path and has the full file-read/subprocess/network visibility surface.
• External-process mode (foresight run -- codex exec "...") and interactive shell mode (foresight shell -- codex) use filesystem watching. They detect writes and deletes after they occur, respond by terminating on critical violations, and cannot observe read-only access, internal subprocesses, or network operations. Interactive shell reassessments are periodic and advisory rather than a pre-execution control.
• Contract snapshots and append-only event history are retained locally per repository; there is no cloud sync or cross-repository aggregation.
• Budget ceilings are current heuristics, not learned per-user limits.
• foresight dashboard is a repository-local viewer, not a hosted collaboration service. It serves the bundled static UI and local WebSocket event bus; no Node.js or remote endpoint is required.
• The public Vercel site is deliberately a landing/visual demo. It does not receive local session telemetry or present itself as a hosted live dashboard.

What we got wrong, and what it taught us

We originally wrote the demo around the task “Refactor the login flow to add MFA support,” assuming it would produce a narrow terra / isolated prediction so the scripted scope-explosion sequence could exercise escalation. When we ran it against the real GPT-5.6-terra model, it classified MFA and authentication work as security-sensitive and returned sol / high / wide. That was the right call: MFA changes can affect identity, recovery, and session boundaries. Our test assumption, not the prediction, was wrong. The problem was that a wide blast radius has no file-count ceiling to exceed, so the demo narrative no longer matched the model’s real risk assessment. We redesigned the task as a genuinely narrow isolated variable rename, which keeps the expected route and scripted drift consistent. We also added a second, prediction-independent catch: the forbidden-pattern block on .env access. It works regardless of the predicted tier, so the demo now proves both predictive scope monitoring and deterministic interception without guessing a model outcome. This is the same principle the system is built to detect in agents: the gap between what we assumed a task’s scope was and what it actually turned out to be.

Why not just use a bigger model for everything?

Sol costs five times Luna’s input and output price, while many coding tasks are mechanical enough to complete safely with a smaller tier. Defaulting to the frontier tier therefore creates exactly the avoidable spend Foresight is designed to expose. Prediction is not free: it adds a metered call before work begins. But a conservative prediction only adds an escalation round-trip, because Foresight reassesses live drift instead of trusting the first estimate blindly.

Quickstart

Install the Python runtime and CLI:

pip install -r requirements.txt
# or, for the `foresight` command:
pip install -e .

Create your local environment file from the committed template:

copy .env.example .env

Set OPENAI_API_KEY in .env, then run the end-to-end demo:

python -m foresight.demo_scenario

For a complete local replay with zero OpenAI API calls (using recorded GPT-5.6 policy and prediction responses through a real Python child), run:

foresight demo --replay

The live path above remains the primary demonstration. Replay is the accessible fallback for judges who want to exercise the real interception and monitoring flow without an API key. The deployed Foresight landing/demo site is a visual tour only; local sessions appear exclusively through foresight dashboard.

Daily Codex workflow

# Once per repository: preview, install, then trust hooks inside Codex.
foresight setup --codex --preview
foresight setup --codex

# Daily work: use Codex normally. Begin and finish contracts through the bundled skill/MCP tools.
codex

# Optional: inspect the active session or all local history. No Node.js is required.
foresight status
foresight dashboard

For the exact human validation sequence, including the required Codex /hooks trust review and a protected-path catch, see the manual Codex proof checklist. ChatGPT Desktop uses the same project integration assets, but parity is not claimed until the same checklist has been manually completed there.

Advanced runtime and demo commands

These commands remain supported for the Python interception demo and explicit external-process monitoring; they are not required for the normal Codex workflow:

# Explicit policy/prediction setup and a Python-child pre-execution runtime.
foresight init
foresight run -- python your_agent_task.py

# Optional packaged browser dashboard for an advanced monitored run.
foresight run --web --no-browser -- python your_agent_task.py

# Explicit external-process filesystem-watch mode (post-hoc writes/deletes only).
foresight shell -- codex

# Zero-key replay for judges.
foresight demo --replay

GitHub Action

Use the composite Foresight Agent Guard to create a policy non-interactively, wrap an agent step, and expose files_touched, flags_raised, final_verdict, and total_cost as workflow outputs. See GitHub Action usage. The Action is locally simulated and covered by tests; a full hosted GitHub Actions run is still required before claiming hosted-runner validation.

Record the live terminal proof

A clean fixture and exact 15-20 second recording sequence are in examples/terminal_recording. Once recorded, place the GIF at docs/demo.gif and use the provided Markdown as the first line of this README.

Packaged local dashboard

Run foresight dashboard from the repository you want to inspect. It serves the bundled static dashboard at http://127.0.0.1:3000/dashboard/, loads durable local contract history first, and then reconnects to the local WebSocket event bus for live updates. foresight run --web and foresight shell --web start the same packaged local dashboard for their advanced sessions; --no-browser suppresses browser launch.

The public Vercel deployment is a landing/visual demo only. It is not a hosted event-ingestion service and never receives a developer's local session data.

Cost tracking and prompt caching

Every OpenAI response becomes a CostEvent, calculated from input/output token usage and streamed to the event bus. Calls use a stable system/context prefix with only task-specific content appended, improving prompt-cache reuse. Clear forbidden or out-of-scope actions are decided locally first, avoiding unnecessary model calls.

Every prediction and policy call is cost-tracked in real time and streamed to the dashboard -- Foresight audits its own spend, not just the agent's.

Fast mode applies a 2.5x multiplier to recorded cost events to make its quota-burn tradeoff visible. Foresight displays: "Fast mode increases quota burn by ~2.5x for ~1.5x speed. Recommended only when latency matters more than budget."

Codex vs Antigravity build split

• Codex -- interception, reasoning, and enforcement. sentry/proxy/interceptor.py implements pre-execution monkey-patching for subprocesses, file reads/writes/deletes, and HTTP requests; unified-diff capture; tracked-process termination; and the local repeated-action paralysis guard. sentry/policy/engine.py handles structured scope-to-policy conversion, local forbidden/scope checks, contextual evaluation, prompt-cache discipline, and token-based cost events. foresight/predictor.py provides structured tier/effort/blast-radius routing, configurable tier bias, deterministic action ceilings, and typed phase-bounded workflow plans. foresight/session_monitor.py implements scope-explosion, low-progress churn, hard action/phase caps, parallel fan-out detection, burn-rate forecasting, phase-output drift checks, reassessment, and escalation.
• Codex -- product plumbing and proof. Codex also built the WebSocket event surface in sentry/eventbus/server.py, the interactive Rich CLI and TOML configuration system in foresight/cli.py and foresight/config.py, the replay/live demos, tier/injection/multi-task/workflow benchmarks, PyPI packaging metadata, and publishing documentation. These components carry predictions, signals, audit events, and costs end-to-end; they are not presentation-only stubs.
• Antigravity -- presentation and delivery. Antigravity handled the visual polish in sentry/web/, dashboard layout/connection fixes, deployment configuration, and documentation presentation cleanup. It consumes the event contract but does not make policy decisions, predict tiers, calculate enforcement signals, or terminate sessions.

This split is intentional and documented per hackathon submission requirements. Codex built 100% of the reasoning-critical and safety-critical behavior: prediction, policy evaluation, workflow bounding, cost/burn accounting, anomaly detection, and escalation/termination.

Roadmap

• Multi-agent swarm monitoring with a shared session risk view.
• Historical session learning to improve tier prediction over time.
• Monitoring support for Claude Code and other agent runtimes beyond Codex.
• Deeper non-Python runtime visibility for read-only access, subprocesses, and network calls.
• Team-level policy profiles and budget guardrails.

License and attribution

MIT License. Built for Build Week, July 2026.