A .agentignore for Your Agent: What to Hide and Leave Visible

Design the file as two sections that are read together by the wrapper. The allowlist is what the agent is hired to do. The denylist is everything that must never enter context or get written, even if it sits under an allowed path.

Two cautions are worth folding into this table. First, a lockfile can be committed but still excluded from agent context, because it is large and mostly noise; the AI-era ignore guide recommends exactly this split. Second, ignore mechanisms are not interchangeable. Git has three layers (.gitignore, .git/info/exclude, and a global exclude file), each with different scope, and there is a diagnostic (git check-ignore -v) that tells you which rule fired (Git ignore methods). Reuse that thinking for .agentignore: one file for the team, plus a local override for paths only you want hidden.

An example file:

# .agentignore
[allow]
src/
lib/
tests/
docs/
README.md
AGENTS.md
.env.example
config/*.example.*

[deny]
.env
.env.*
!.env.example
*.pem
*.key
*credentials*.json
secrets/
node_modules/
vendor/
dist/
build/
coverage/
.git/
scratch/
tmp/
*.log

The subtle part is !.env.example under deny, which un-hides the template that the allow list also names. Section order and negation rules must be written down, not inferred. Better yet, make the wrapper refuse to start when the two sections disagree rather than silently picking a winner.

Every agent exposes a small set of tools: read a file, write a file, glob, grep, run a shell command. The wrapper sits between the model and those tools and has one job: take the requested path or command, turn it into a real absolute path, apply the lists, and return a refusal if the check fails. Sibling tools need the same treatment as read_file; a grep with a --path flag is a read in disguise, and a shell string with cat ../.env is a read with extra steps.

The skeleton looks like this:

from pathlib import Path, PurePosixPath
import os, re, shlex, logging

ROOT = Path("/workspace/project").resolve()
ALLOW = ("src", "lib", "tests", "docs", "README.md", "AGENTS.md", ".env.example")
DENY  = (".env", ".env.local", "secrets", "node_modules", "vendor", "dist",
         "build", "coverage", ".git", "scratch", "tmp")

def real(path: str) -> Path:
    # Join to root first, then resolve: this collapses "..", symlinks and case.
    return (ROOT / path).resolve()

def rel(path: Path) -> PurePosixPath:
    return PurePosixPath(path.relative_to(ROOT).as_posix())

def is_denied(relpath):
    parts = relpath.parts
    return any(p in DENY or relpath.name == p or relpath.name.endswith(".log")
               or relpath.suffix in (".pem", ".key") for p in parts)

def check(path: str, write: bool = False):
    target = real(path)
    if ROOT not in target.parents and target != ROOT:
        return refuse(path, "outside repository root")
    r = rel(target)
    if is_denied(r):
        return refuse(path, "denylist")
    first = r.parts[0] if r.parts else ""
    if not (first in ALLOW or str(r) in ALLOW):
        return refuse(path, "not in allowlist")
    return target

Two details make this robust. Resolve before you compare, because src/../.env looks like a child of src and a symlink named src/config.json may point at ~/.ssh/id_rsa; a wrapper that checks the string has already lost. And write a refusal path that returns a structured error, not an exception, so the agent sees "denied by policy for path X" instead of a stack trace and learns to abandon that route rather than retry variants forever.

The shell tool is the leaky end. You cannot reliably parse arbitrary shell into path sets. Sensible options are: run shell inside a container that only has allowed paths mounted, or refuse shell for tasks the code path policy is meant to protect and expose a small typed command set (run_tests, run_build) that internally calls the same check function. The tool-level allowlist and denylist design is the same pattern described for endpoint agents, where approval applies to the specific tool action, not just the agent's name (Backslash Security on allowlist and denylist policy).

If you run more than one model behind the same agent, the policy should live in the wrapper, not in each model's prompt. Quanta Inference (https://quantaintelligence.ai/inference) exposes text, image, video, audio and embedding models behind one OpenAI-compatible key, which means the wrapper's path check stays identical while you swap models underneath.

Imagine an agent asked to fix a failing test in tests/checkout.test.ts. It reads src/checkout.ts, runs the test suite, sees a red assertion, and tries three paths to make it pass. The table shows what each policy permits.

Take the third row in detail. If the wrapper compares request strings against prefixes, tests/../../.env starts with tests/, so a naive check says yes. Once you resolve it, the real path is /workspace/project/.env, the denylist fires, and the model gets a refusal. The fourth row is the one most teams miss: if the agent has write access to tests/, it can create a symlink in an allowed directory that points at anything, then read through it. Resolving the final target catches this because Path.resolve() follows symlinks before your rules are applied.

The fifth row is the honest one. Path policy cannot decide intent; deleting or skipping a failing test to get green is a behavioral failure that looks like a normal allowed write. Path policy narrows the blast radius. It does not replace a review gate before merge. Keep agent work on a branch and require human review of the diff, which is the same pattern used for Git-native agent workflows where agent changes open a pull request, not a push to main (GitAgent patterns).

A refusal that vanishes is a refusal you will debug twice. Write one structured log line per check with: timestamp, tool name, requested path, resolved path (relative to root), decision, and matched rule. Keep it append-only, and rotate it like any other sensitive log because the requested path itself can reveal intent (an agent probing .env.production tells you something).

What to actually read in the log, week one:

• Denied reads on .env* and key files. One denial is the agent hitting noise. Repeated denials across sessions mean your task instruction is under-specified. Tell it where config comes from (.env.example) in the rules file, but do not remove the check.
• Traversal patterns. A rise in ../ denials is a hint a tool is handing the agent absolute paths it did not expect, or a task is failing silently.
• Refused writes to tests or CI files. If the deny list is over-broad, the agent will report "cannot fix test." Widen deliberately, on a branch, with a reason. If the agent tries to weaken a test, the deny list is doing its job.
• Volume, not just errors. If thousands of files under node_modules are still being resolved before the deny fires, your glob tool is doing the walk. Refuse the directory prefix in glob before it expands, not after.

Pair the log with an audit posture. Regulated teams already track whether an action was blocked before execution or merely logged, and a policy left in "audit" that records but never blocks is just documentation that happens to be verbose (BeyondTrust). Treat the first week as audit; treat the second as enforcement.

Write tests for the wrapper, not the model. The model is not the unit under test; the check function is. A minimal suite:

import pytest
from guard import check, Refused

@pytest.mark.parametrize("path", [
    "src/index.ts", "tests/a.test.ts", "docs/setup.md", ".env.example",
])
def test_allowed(path):
    check(path)

@pytest.mark.parametrize("path", [
    ".env", "src/../.env", "tests/../../etc/passwd",
    ".git/config", "node_modules/x/index.js", "dist/app.js",
    "/etc/passwd", "\\..\\..\\.env", "src/%2e%2e/.env",
])
def test_refused(path):
    with pytest.raises(Refused):
        check(path)

def test_symlink_escape(tmp_path):
    link = tmp_path / "tests" / "k"
    link.symlink_to("/etc/passwd")
    with pytest.raises(Refused):
        check(str(link.relative_to(tmp_path)))

Add these beyond the obvious:

Run the suite in CI. If someone adds a new tool (patch_file, apply_diff, fetch_url) it must call check; a test that enumerates registered tools and asserts each one calls the guard catches the next tool someone forgets.

Repository scoping is the minimum, not the ceiling. Once paths are controlled, the next questions are usually "who owns this agent" and "what does it produce." A guard belongs to a tool wrapper you control; the model route belongs to whoever runs the agent. Quanta Inference (https://quantaintelligence.ai/inference) is one option for the model side: a single key across text, image, video, audio and embedding models, priced in US dollars, so a wrapper can switch models without rewriting policy. Teams that want the work delivered rather than glued together can put a Quanta Expert (https://quantaintelligence.ai/agents) on the task and hand the agent a job description instead of a prompt file.

The decision rule this article argues for: if a boundary matters when the wrong thing happens, put it in code that resolves the path, checks the lists and logs the refusal. If it only matters when the work is wrong, put it in the prompt. Very few boundaries belong in the second bucket.