# Agent Context Filters

<TierCallout>
	Supported on [Enterprise](/pricing/plans/enterprise) plans. Configuring
	context filters requires administrator access.
</TierCallout>

<Callout type="note" title="Experimental">
	Context filters are an experimental feature. Their behavior and configuration
	may change in future releases.
</Callout>

Context filters are an admin-defined exclusion list for the agents that run inside [Deep Search](/deep-search) and [Agentic Batch Changes](/agentic-batch-changes). An excluded repository is invisible to the agent.

Two site configuration keys hold the rules, and both have the same shape:

- `experimentalFeatures.agents.contextFilters` applies to both agents. Put new rules here.
- `experimentalFeatures.deepSearch.contextFilters` is the older key that predates Agentic Batch Changes. See [Which key to use](#which-key-to-use).

## Why use context filters

- **Keep secrets out of the agent's context.** Nothing in an excluded repository is returned by the agent's tools, so the agent cannot quote it, summarize it, or forward it to a third-party model provider.
- **Reduce noise.** Forks, mirrors, and archived repositories can be hidden so the agent spends its research on code that matters.

## How context filters work

Filtering happens in the tools the agent uses to read repositories, before any content reaches the LLM, and does not rely on prompting, so the model cannot reason its way around the filters.

To the agent, an excluded repository is indistinguishable from one that does not exist. Agentic Batch Changes also refuses to run [coding agent steps](#coding-agent-steps) in an excluded repository.

## Configuring context filters

An administrator configures filters under **Administration → Configuration → Advanced configuration**, inside the `experimentalFeatures` block of the advanced configuration. Each entry in `exclude` is a rule with a `repoNamePatterns` list, and a repository is excluded if it matches any pattern of any rule.

```jsonc
"experimentalFeatures": {
  "agents.contextFilters": {
    "exclude": [
      // Hide an entire repository.
      { "repoNamePatterns": ["^github\\.com/acme/secrets$"] },
      // Hide every repository in an organization.
      { "repoNamePatterns": ["^github\\.com/acme-internal/"] }
    ]
  }
}
```

Config changes apply to the next agent run; no restart is required. `exclude` must contain at least one rule, and each rule's `repoNamePatterns` must list at least one pattern. To turn filtering off, remove the key; an empty `exclude` list is rejected. Saving an invalid pattern through the site admin UI is rejected. If an invalid pattern reaches the running configuration another way, for example through `SITE_CONFIG_FILE`, the agents block every repository until it is fixed rather than running with no filters.

### Which key to use

Rules from `agents.contextFilters` and `deepSearch.contextFilters` are combined into one list, and every agent applies the whole list. A rule in either key hides the same repositories from Deep Search, from the Agentic Batch Changes agent, and from its coding agent steps. There is no way to exclude a repository from one agent only.

Add new rules to `agents.contextFilters`. Rules you already have in `deepSearch.contextFilters` keep working and need no migration; if both keys are set, their rules are simply combined.

## Pattern syntax

`repoNamePatterns` takes a list of Go [RE2](https://github.com/google/re2/wiki/Syntax) regular expressions, matched against the full repository name, including the code host: `github.com/acme/backend`.

- **Patterns are unanchored.** `internal` matches `github.com/acme/internal-tools`. Use `^...$` when you mean the whole string: `^github\.com/acme/secrets$` leaves `github.com/acme/secrets-docs` visible, while `acme/secrets` hides both.
- **`.` matches any character except a newline, including `/`.** Escape it as `github\.com`. The pattern `a.b` also matches the repository `a/b`.
- **Backslashes must be doubled in JSON.** The regex `github\.com` is written `"github\\.com"`.
- **Repository names match case-insensitively.** `acme/Secrets` excludes `github.com/acme/secrets`.
- **RE2 does not support backreferences or lookaround assertions.** Patterns like `(a)\1` are rejected.
- **Patterns in a list are combined with OR.** `["^a$", "^b$"]` matches either.

## Agentic Batch Changes

The [Agentic Batch Changes](/agentic-batch-changes) agent applies the combined rules everywhere it reads code through Sourcegraph: when it researches with Deep Search, when it reads files, searches, and resolves repositories directly, and in the [Sourcegraph MCP](/api/mcp) tools available inside its coding agent steps. When the agent's batch spec is resolved into workspaces, excluded repositories are dropped, so the agent cannot change them even if its spec names them.

Workspace filtering applies only to batch specs the agent manages. A batch spec you write and run yourself keeps every workspace, including those in excluded repositories, but its coding agent steps are still subject to the check below.

### Coding agent steps

A [coding agent step](/agentic-batch-changes/configuration#coding-agent-steps) runs a coding agent on a full checkout of the repository, which the agent reads freely, so Sourcegraph refuses to run coding agent steps in an excluded repository. Context filters do not apply to `run` steps, whose scripts can read the whole checkout.

The check runs before the executor job for the repository starts, and only when a coding agent step would actually run: an execution whose coding agent steps are all skipped by an `if:` condition or served from the execution cache does not trigger it. When the check blocks an execution, the executor job never starts, so the `run` steps in that job do not run either. Coding agent steps in [changeset hooks](/agentic-batch-changes/configuration#changeset-hooks) are checked the same way.

A blocked repository fails its execution with this message, which the agent sees as well: "Coding agent steps cannot run in this repository because it is excluded by the agent context filters in the site configuration (experimentalFeatures.agents.contextFilters)." The message does not name the rule.

## Verifying a filter

Ask Deep Search a question that would require code from the excluded repository, and @-mention the repository directly. A working filter produces an answer that does not reference the repository's code, and the [list of sources](/deep-search) contains none of it. If you @-mention an excluded repository, Deep Search reports it as not found rather than acknowledging that it was excluded.

To see the coding agent step check, run a batch spec you wrote yourself, not one the agent manages, with a `codingAgent` step against the excluded repository. The execution fails with the message above.