agent-scope

Scoped write access for AI coding agents.

Stop Claude, Cursor, Codex, and other coding agents from silently changing code outside their intended task boundary. Give them broad read access, narrow write access, and enforce approval for protected modules.

npm install -g @floomhq/agent-scope

Demo

The problem

You ask an agent to "fix the settings page." It changes:

• apps/web/settings/page.tsx ✅ intended
• packages/auth/session.ts ❌ silently broken
• package-lock.json ⚠️ unexpected side effect
• Some random utility file ❌ now broken

agent-scope makes this visible, preventable, and fixable before it hits production.

Philosophy: boundary guard, not correctness oracle

agent-scope solves a specific problem: cross-module contamination. It does not try to prove your code is correct — your tests do that.

| Layer | Responsibility | Example | |-------|---------------|---------| | agent-scope | Which files can change? | Block auth, billing, migrations unless approved | | tests / typecheck / lint | Did the code break? | Sidebar buttons still work after top-bar fix | | human review | Should this change exist at all? | Approve a protected-file change with justification |

This separation is intentional. A tool that tries to do everything becomes a cop. A tool that does one thing well becomes a guardrail.

The solution

# agent.scope.yml
version: "0.1"
mode: strict

task:
  id: "email-settings-v2"
  title: "Add onboarding email settings"

scope:
  read:
    - "**/*"
  write:
    - "apps/web/settings/**"
    - "packages/email/**"
  protected:
    - "packages/auth/**"
    - "packages/billing/**"
    - "db/migrations/**"
  approval_required:
    - "package.json"
    - "pnpm-lock.yaml"

The agent can read the whole repo for context, but can only write what you scoped. Touch a protected file and the check fails.

Quick start

# 1. Initialize a scope file
agent-scope init

# 2. Guided setup (recommended)
agent-scope init --interactive

# 3. Edit agent.scope.yml to define boundaries

# 4. Make changes, then validate
agent-scope check

# 5. See your current scope and status
agent-scope status

# 6. If the agent needs to touch a protected file
agent-scope request packages/auth/session.ts \
  --reason "Need session field for notification preference" \
  --required-by "apps/web/settings/page.tsx"

# 7. Approve the expansion
agent-scope approve packages/auth/session.ts

CLI commands

| Command | Description | |---------|-------------| | agent-scope init | Create agent.scope.yml and .agent-scope/ | | agent-scope init --interactive | Guided setup with prompts | | agent-scope check | Validate current git diff against scope | | agent-scope check --with-diff | Validate + show actual diff per file | | agent-scope run | Validate scope, then run checks.before_done | | agent-scope run <cmd> | Validate scope, then run a custom command | | agent-scope status | Show task, scope, approvals, and pending requests | | agent-scope scope | Display the full scope configuration | | agent-scope request <path...> | Create a scope expansion request | | agent-scope approve <path> | Approve a file or path for the current task | | agent-scope unapprove <path> | Remove an approval | | agent-scope pending | List pending scope expansion requests | | agent-scope approvals | List current approvals |

Check options

agent-scope check --base origin/main    # diff against a base branch
agent-scope check --staged              # only staged changes
agent-scope check --unstaged            # only unstaged changes
agent-scope check --json                # JSON output for CI/scripts
agent-scope check --run-checks          # also execute checks.before_done
agent-scope check --with-diff           # show git diff for each file

Handling real-world scenarios

"I fixed the top bar, but the sidebar buttons broke"

Both files are in your write scope, so agent-scope check passes. This is correct — scope guards boundaries, tests guard correctness.

Your checks.before_done should catch this:

checks:
  before_done:
    - "pnpm test components/sidebar"
    - "pnpm test components/top-bar"
    - "pnpm typecheck"

If sidebar tests fail after a top-bar change, the agent sees the failure and must fix it before finishing. agent-scope run enforces this gate.

"I need to change a protected file because my allowed file depends on it"

This is a legitimate scope expansion. Document the dependency chain:

agent-scope request packages/auth/session.ts \
  --reason "Add email preference to session payload" \
  --required-by "apps/web/settings/page.tsx"

The --required-by flag records which allowed file necessitates the protected change. This makes human review much faster.

"How do I know the protected-file change is safe?"

Use check --with-diff:

agent-scope check --with-diff

This shows the actual diff for every file. An import addition looks very different from rewriting auth logic. Review the diff, then approve or request.

"The agent keeps requesting scope expansions for tiny changes"

Make your write scope broader for safe areas, or narrow your protected scope to only the truly sensitive files. Example:

# Too restrictive — every utility change needs approval
write:
  - "apps/web/settings/**"

# Better — utilities are safe to touch
write:
  - "apps/web/settings/**"
  - "packages/shared/utils/**"
  - "packages/ui/**"

Enforcement model

A file change can be in one of five states:

| State | Rule | |-------|------| | allowed | Matches scope.write | | protected | Matches scope.protected; blocked unless explicitly approved | | approval_required | Matches scope.approval_required; requires approval | | approved | Explicitly approved via agent-scope approve | | blocked | Everything else in strict mode |

Priority order:

protected > approved > approval_required > write > blocked

Modes

Strict (default): only scope.write files are allowed. Everything else is blocked.

Warn: out-of-scope files become warnings (exit 0), but protected paths are still blocked.

CI / GitHub Action

Add .github/workflows/agent-scope.yml:

name: Agent Scope
on:
  pull_request:
jobs:
  scope:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm install -g @floomhq/agent-scope
      - run: agent-scope check --base origin/${{ github.base_ref }}

Claude Code / Cursor / Codex integration

Hook command

agent-scope check --json

Example JSON output:

{
  "status": "blocked",
  "task_id": "email-settings-v2",
  "violations": [
    {
      "file": "packages/auth/session.ts",
      "reason": "protected path",
      "action": "request_scope_expansion"
    }
  ]
}

Pre-commit hook

#!/bin/sh
agent-scope run

If scope is violated, the commit is blocked. If clean, your tests run automatically.

Requesting scope expansion

When an agent realizes it needs to touch a protected file:

agent-scope request packages/auth/session.ts \
  --reason "Need session field for notification preference" \
  --required-by "apps/web/settings/page.tsx" \
  --risk-level high \
  --agent-summary "The settings page needs access to user email preference." \
  --suggested-checks "pnpm test packages/auth,pnpm typecheck"

This creates .agent-scope/requests/2026-06-10-email-settings-v2.yml with full context for human review.

Exit codes

| Code | Meaning | |------|---------| | 0 | Clean | | 1 | Violation or approval required | | 2 | Invalid config / error |

Installation

npm install -g @floomhq/agent-scope

Or use with npx:

npx @floomhq/agent-scope check

Requires Node.js >= 20.

Monorepo example

version: "0.1"
mode: strict

task:
  id: "settings-email-v1"
  title: "Add onboarding email settings"

scope:
  read:
    - "**/*"
  write:
    - "apps/web/settings/**"
    - "packages/email/**"
    - ".agent-scope/**"
  protected:
    - "packages/auth/**"
    - "packages/billing/**"
    - "db/migrations/**"
    - "infra/**"
    - ".env*"
  approval_required:
    - "package.json"
    - "pnpm-lock.yaml"
    - "yarn.lock"
    - "turbo.json"
    - "next.config.*"

checks:
  before_done:
    - "pnpm typecheck"
    - "pnpm test"

Contributing

See CONTRIBUTING.md.

License

MIT © Federico De Ponte