Scope Guard

Intent-bound execution for safer AI-powered development and deployment, let coding agents move fast without letting them wander.

Comment

Scope Guard

Inspiration

Scope Guard came from a problem I have repeatedly faced while working with coding agents in real development environments.

I often manage several projects at the same time, sometimes on the same machine or server. Each project may have its own repository, database, service, port, environment variables, deployment configuration, and domain. When I ask a coding agent to work on one application, the task may sound simple:

Update this project, run the migration, restart the service, and verify the deployment.

The problem is that an agent does not always understand the operational boundaries that are obvious to the developer.

A command can be technically valid and still target the wrong service. A configuration change can fix one application while breaking another. A deployment script can restart a shared dependency, read an unrelated environment file, or modify a project that was never part of the original request.

I experienced this concern while working with projects such as RD Social and EngageFlow. Both applications had different responsibilities, but they could exist within the same broader infrastructure. Whenever I gave an agent access to help with deployment or debugging, I found myself repeatedly adding instructions such as:

Work only on RD Social. Do not modify EngageFlow. Do not restart unrelated services. Do not touch any other database or configuration.

That made me realize that the real issue was not simply sandboxing.

Traditional sandboxing asks:

What can the agent technically access?

The question I wanted Scope Guard to answer was:

Does this specific action belong to the task the developer actually approved?

That distinction became the foundation of the project.

What Scope Guard Does

Scope Guard is an intent-bound execution control plane for coding agents.

It converts a developer's natural-language task into a structured project boundary containing:

  • Allowed repositories and filesystem paths
  • Protected projects and configuration files
  • Approved services and containers
  • Databases
  • Ports and domains
  • Operations requiring human approval
  • Actions that must always be blocked

Once the boundary is approved, every proposed action is evaluated before it is executed.

Scope Guard can return one of several deterministic decisions:

  • ALLOW
  • ALLOW_WITH_APPROVAL
  • BLOCK_OUT_OF_SCOPE
  • BLOCK_PROTECTED_RESOURCE
  • BLOCK_DESTRUCTIVE
  • BLOCK_UNKNOWN_RESOURCE
  • BLOCK_SECRET_ACCESS
  • BLOCK_NETWORK_DESTINATION
  • BLOCK_POLICY_AMBIGUITY

The language model can interpret intent, propose a plan, explain risks, and suggest corrections, but it does not make the final security decision.

That responsibility belongs to a deterministic policy engine.

This separation was one of the most important design choices in the project:

GPT-5.6 helps Scope Guard understand the task. The policy engine decides what is permitted.

The Demonstration Scenario

I built the project around a synthetic shared-server scenario containing two applications:

RD Social

The target project that the agent is allowed to update and deploy.

EngageFlow

A separate protected project that must remain healthy and unchanged.

The developer submits the task:

Update and deploy RD Social, run its approved migration, restart its API, and verify its health without modifying EngageFlow.

GPT-5.6 interprets the request and produces a structured boundary and execution plan.

Codex then proposes the development and deployment actions.

During the demonstration, the agent attempts to restart the EngageFlow service. Scope Guard detects that the service belongs to a protected project and blocks the operation before execution.

The rejection includes:

  • The blocked command
  • The affected protected resource
  • The policy rule that was violated
  • A human-readable explanation
  • A structured machine-readable explanation
  • A suggested corrected action

The Codex workflow then receives that rejection context and revises the plan to restart the correct RD Social service.

The corrected operation proceeds through an approval gate.

Scope Guard creates a snapshot before the mutation, applies the approved change, runs health checks, and verifies that EngageFlow remained unchanged.

The demonstration also injects a deliberate RD Social failure. Scope Guard detects the failed health check, restores the target project's previous state, and verifies that the protected EngageFlow application was never modified during execution or rollback.

How I Built It

Scope Guard is implemented as a monorepo with a clear separation between the user interface, orchestration layer, policy engine, agent integrations, evaluation suite, and synthetic execution environment.

Frontend

I built the control plane using:

  • Next.js
  • TypeScript
  • Tailwind CSS
  • Typed API validation
  • Responsive layouts
  • Real-time execution events

The interface is intentionally designed as a developer operations dashboard rather than a generic chat application.

It includes six main product areas:

  1. Overview dashboard
  2. Environment inventory
  3. Guarded task creation
  4. Boundary review
  5. Live execution and approvals
  6. Reports and SentryBench results

The most important screen is the blocked-action view. It makes the reason for a policy rejection understandable without requiring the developer to inspect raw logs.

Backend

The orchestration layer is built with:

  • FastAPI
  • Python
  • Pydantic
  • Structured API contracts
  • Server-side event streaming
  • Typed task and policy models

The backend manages:

  • Task creation
  • Environment inventory
  • Boundary generation
  • Boundary approval
  • Agent action proposals
  • Policy evaluation
  • Human approvals
  • Execution events
  • Snapshots
  • Validation
  • Rollback
  • Reports

GPT-5.6

I integrated GPT-5.6 as the planning and interpretation layer.

It receives:

  • The developer's task
  • The available infrastructure inventory
  • Resource relationships
  • Existing constraints
  • Supported operations

It returns structured information including:

  • Interpreted intent
  • Target project
  • Allowed resources
  • Protected resources
  • Proposed steps
  • Risk summary
  • Validation plan
  • Rollback plan
  • Confidence

All model output is validated against strict schemas before it can enter the execution workflow.

GPT-5.6 is never treated as the final authority. A plausible explanation from the model cannot override a deterministic block.

Codex

Codex played two roles in the project.

First, I used Codex extensively to accelerate the implementation itself. It helped scaffold the monorepo, build the policy engine, create the synthetic environment, write tests, refine the frontend, improve documentation, and repeatedly verify the full workflow.

Second, Scope Guard includes a Codex integration layer that can receive coding-agent proposals and pass them through the policy engine.

The guarded flow is:

Codex proposes an action
→ Scope Guard parses the action
→ Resources are identified
→ The deterministic policy evaluates the action
→ The action is allowed, blocked, or sent for approval
→ Rejection context is returned to Codex
→ Codex revises the plan

This allows the agent to remain useful without allowing it to silently expand its own permissions.

Synthetic Docker Environment

I did not test Scope Guard against my live projects.

Instead, I created a Docker-only synthetic environment that models the operational relationship between RD Social and EngageFlow.

The environment runs with:

  • Non-root users
  • No host Docker socket
  • No privileged containers
  • Restricted mounts
  • No production credentials
  • No access to real databases
  • No connection to production infrastructure

The runner operates as UID 10001, with zero effective Linux capabilities and NoNewPrivs enabled.

This was important because a project about agent safety should also demonstrate disciplined isolation during its own development.

Deterministic Enforcement

One of the biggest challenges was avoiding security theatre.

It would have been easy to ask a language model whether a command looked safe and display its answer. That would create an attractive demonstration, but it would not create an enforceable boundary.

I therefore separated the system into distinct stages:

Parsing
→ Resource extraction
→ Risk classification
→ Policy evaluation
→ Approval
→ Execution

The command-analysis layer identifies:

  • Filesystem paths
  • Relative path escapes
  • Service names
  • Database names
  • Ports
  • Domains
  • Environment files
  • Network destinations
  • Destructive shell operations
  • Secret access patterns

The policy engine then compares those resources against the approved boundary manifest.

Unknown resources are denied by default.

The language model can suggest that an action is safe, but the policy engine can still block it.

Snapshots, Validation, and Rollback

Blocking unsafe actions is only part of the problem.

A valid in-scope action can still fail.

Before a mutating action, Scope Guard records:

  • Relevant file hashes
  • Repository state
  • Service state
  • Health-check state
  • Migration state
  • Protected-resource integrity state

After execution, it validates both sides of the boundary.

For the target project, it checks whether the expected deployment succeeded.

For the protected project, it verifies that:

  • Files remained unchanged
  • Service health remained stable
  • Configuration remained intact
  • No unauthorized operation occurred

If the target validation fails, Scope Guard performs a target-only rollback and verifies the environment again.

This made rollback a controlled part of the execution transaction rather than an afterthought.

Auditability

Every significant workflow event is recorded in a chronological audit timeline.

Examples include:

  • Task received
  • Inventory loaded
  • Boundary proposed
  • Boundary approved
  • Snapshot created
  • Action proposed
  • Policy decision made
  • Protected action blocked
  • Corrected action received
  • Approval granted
  • Execution completed
  • Health check failed
  • Rollback started
  • Previous state restored
  • Protected resources verified

The audit events are hash-chained, making accidental or unauthorized modifications to the event sequence detectable.

Scope Guard also generates downloadable execution reports containing:

  • Target resources changed
  • Protected resources preserved
  • Actions blocked
  • Approvals required
  • Validation results
  • Rollback outcome
  • Audit-chain status

SentryBench

I created a dedicated evaluation suite called SentryBench to test the policy engine beyond the main demonstration.

It contains 32 scenarios across four categories:

Safe in-scope operations

Examples include editing RD Social files, running its tests, and restarting its approved service.

Cross-project operations

Examples include restarting EngageFlow, accessing its database, or modifying its environment variables.

Destructive operations

Examples include recursive deletion, unrelated database operations, secret access, and unsafe configuration changes.

Ambiguous operations

Examples include generic service names, unknown paths, shared resources, and attempted workspace escapes.

The current evaluation result is:

32 / 32 expected policy decisions passed
Average policy decision latency: approximately 0.34 ms

I also added regression tests to ensure the main guarded execution story continues to work as the policy system evolves.

Challenges I Faced

Building without weakening the security model

The hardest design challenge was deciding where AI reasoning should stop and deterministic enforcement should begin.

GPT-5.6 is excellent at understanding intent and explaining complex situations, but infrastructure permissions should not depend entirely on probabilistic output.

The final architecture uses AI for interpretation and correction while preserving deterministic enforcement.

Keeping the project generic while demonstrating a real story

A completely generic infrastructure-security platform would have been too broad for the hackathon.

A hard-coded demonstration would have been easier but less credible.

I addressed this by using a concrete RD Social and EngageFlow scenario while designing the internal models around typed resources, actions, manifests, and decisions.

Simulating realistic infrastructure safely

I wanted the system to execute real operations, detect failures, and perform rollback, but I did not want the hackathon project to touch production systems.

The Docker environment had to behave realistically enough to demonstrate the workflow while remaining disposable and isolated.

WSL and Docker stability

I built the project on a Windows PC using Ubuntu through WSL2. During development, Docker Desktop integration and browser automation occasionally destabilized the WSL session.

This forced me to improve container cleanup, browser-test isolation, resource controls, and documentation around WSL recovery.

Those interruptions were frustrating, but they reinforced one of the central lessons behind Scope Guard: powerful automation must operate within explicit resource boundaries.

Designing a clear user experience

Security tools often expose raw policy logs and expect the developer to interpret them.

I wanted Scope Guard to explain:

  • What the agent attempted
  • What resource was affected
  • Why it was blocked
  • Which rule made the decision
  • What the corrected action should be

Making those decisions understandable was as important as implementing the underlying policy engine.

What I Learned

The most important lesson was that agent safety is not only about restricting access.

An agent may have legitimate access to a workspace and still perform the wrong operation.

The missing layer is task-specific authorization.

I also learned that language models and deterministic systems are strongest when they are given different responsibilities:

  • GPT-5.6 interprets intent and explains risk.
  • Codex performs development work and revises plans.
  • The policy engine enforces boundaries.
  • The human approves sensitive operations.
  • The sandbox limits the execution environment.
  • Validation and rollback verify the outcome.

No single layer is sufficient on its own.

I also gained a deeper appreciation for evaluation. Building SentryBench forced me to define what “safe” actually meant in measurable terms rather than relying on an impressive demonstration alone.

Accomplishments I Am Proud Of

I am particularly proud that Scope Guard is not only a visual prototype.

The project includes:

  • A real deterministic policy engine
  • A structured GPT-5.6 planning adapter
  • A live Codex proposal integration
  • Human approval gates
  • A Docker-based synthetic shared-server environment
  • Real blocked-action handling
  • Failure injection
  • Target-only rollback
  • Protected-resource integrity verification
  • Hash-chained audit events
  • Downloadable reports
  • A responsive six-route control plane
  • Desktop and mobile browser verification
  • 32 SentryBench scenarios
  • Comprehensive backend and frontend testing

The complete verification suite currently includes:

  • Ruff passing
  • Strict MyPy passing
  • 30 backend tests passing
  • Frontend tests passing
  • ESLint passing
  • TypeScript passing
  • Next.js production build passing
  • Docker Compose validation passing
  • Playwright verification across all six routes
  • Successful full signature scenario
  • Successful rollback with EngageFlow remaining healthy and unchanged

What Comes Next

Scope Guard currently demonstrates the core safety loop in a controlled environment.

The next stage is to expand it into a broader agent-safety platform with:

  • Generic caller-defined resource manifests
  • GitHub and CI/CD integrations
  • Remote runner support
  • Kubernetes resource boundaries
  • Cloud deployment policies
  • Organisation-level policy packs
  • Durable audit storage
  • Signed audit records
  • Team-based approval workflows
  • Fine-grained API keys and quotas
  • Additional coding-agent integrations
  • Policy simulation before execution
  • Historical risk analytics

I also see Scope Guard evolving into a standard safety layer that sits between coding agents and developer infrastructure.

As agents become more capable, the important question will no longer be whether they can perform an operation.

It will be whether that operation belongs to the task, respects the intended project boundary, and can be safely reversed.

That is the problem Scope Guard is designed to solve.

Let coding agents move fast without letting them wander.

Share this project:

Updates