> ## Documentation Index
> Fetch the complete documentation index at: https://jonathansantilli-codegate-92.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Deep scan (Layer 3)

> How CodeGate's opt-in Layer 3 deep scan works: eligible resource discovery, per-resource consent, supported meta-agents, MCP tool-description analysis, and local instruction-file analysis.

Deep scan is an opt-in Layer 3 capability. It extends the offline static analysis in Layers 1 and 2 by analysing external resources referenced by project configurations and local instruction files using a selected meta-agent.

<Warning>
  Deep scan increases your exposure compared to a static-only scan. It may fetch remote metadata from external URLs and invoke a local AI tool. Run it only when you have reviewed the consent model and trust the installed meta-agent.
</Warning>

## Enabling deep scan

Pass `--deep` to `codegate scan`:

```bash theme={null}
codegate scan . --deep
```

To skip interactive consent prompts in a controlled environment, add `--force`:

```bash theme={null}
codegate scan . --deep --force
```

Without `--deep`, Layer 3 is never invoked. Layers 1 and 2 always run.

## What deep scan discovers

When `--deep` is enabled, CodeGate discovers two categories of candidates:

**External resources** — eligible URLs and remote endpoint references found in known AI tool config paths (MCP server metadata URLs, package registry endpoints, remote skill sources).

**Local instruction files** — eligible markdown and text files from the already-selected scan surface. This includes files such as `AGENTS.md`, `CODEX.md`, and discovered skill or rule markdown files.

If no eligible resources are found in either category, CodeGate reports that explicitly and exits deep mode cleanly without prompting.

Use `--include-user-scope` to extend resource discovery to user-level and home-directory AI tool config paths:

```bash theme={null}
codegate scan . --deep --include-user-scope
```

## Consent model

<Note>
  Deep scan is consent-driven. No network request or meta-agent command is executed without explicit per-resource approval.
</Note>

For each discovered candidate, the interactive flow is:

<Steps>
  <Step title="Resource presentation">
    CodeGate displays the resource identifier and a preview of the fetch or analysis action it will perform.
  </Step>

  <Step title="Meta-agent selection">
    CodeGate enumerates available meta-agents from installed tools and prompts you to select one. The default is the `tool_discovery.preferred_agent` value from config.
  </Step>

  <Step title="Command preview">
    CodeGate shows the exact meta-agent command it will run for this resource.
  </Step>

  <Step title="Approve or skip">
    You approve or skip. Skipped resources are recorded as `skipped_without_consent` outcomes and appear as `PARSE_ERROR` layer-3 findings in the report so the skip is auditable.
  </Step>
</Steps>

In non-interactive mode (for example, CI without a TTY), all deep-scan actions are skipped unless `--force` is provided.

## Supported meta-agents

| Key        | Tool        | Notes                                                                                                                              |
| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `claude`   | Claude Code | Supported for both external resource analysis and tool-less local text analysis.                                                   |
| `codex`    | Codex CLI   | Supported for external resource analysis. Not used for local text analysis (shell-less mode not yet proven).                       |
| `opencode` | OpenCode    | Supported for external resource analysis via generic stdin mode. Not used for local text analysis (tool-less mode not yet proven). |

Configure a preferred agent in `~/.codegate/config.json`:

```json theme={null}
{
  "tool_discovery": {
    "preferred_agent": "claude"
  }
}
```

## MCP tool-description analysis

When a project config references MCP servers, CodeGate may analyse their tool descriptions for prompt-injection patterns, consent-bypass text, and toxic data-flow indicators.

CodeGate does **not** execute untrusted MCP stdio command arrays during scanning. Local stdio server paths are treated as static metadata targets only — the command array is read but never run.

## Local instruction-file analysis

For files such as `AGENTS.md`, `CODEX.md`, and rule markdown discovered in the project tree, deep scan performs text-only analysis:

* CodeGate passes the file content and any URL strings it extracts as inert text to the meta-agent.
* Referenced URLs are passed as strings, not fetched.
* No code referenced inside the file is executed.

Claude Code is the only meta-agent currently used for local text analysis. It is invoked with `--tools=` (tool-less mode) so it cannot perform file operations or shell execution during the analysis.

Codex CLI and OpenCode are not used for local text analysis until a proven shell-less invocation mode is available for each.

## Failure modes

Layer 3 outcomes are normalised into findings rather than crashing the scan. Tracked outcome types:

| Outcome                    | Category           | Description                                             |
| -------------------------- | ------------------ | ------------------------------------------------------- |
| Consent skipped            | `PARSE_ERROR` / L3 | User skipped the resource at the consent prompt.        |
| Timeout                    | `PARSE_ERROR` / L3 | Meta-agent command timed out.                           |
| Auth failure               | `PARSE_ERROR` / L3 | Remote resource returned an authentication error.       |
| Network or command failure | `PARSE_ERROR` / L3 | Network error or non-zero meta-agent exit code.         |
| Response schema mismatch   | `PARSE_ERROR` / L3 | Meta-agent output could not be parsed as expected JSON. |

These findings appear in all output formats alongside findings from Layers 1 and 2.

## Data handling

* Layer 1 and Layer 2 scanning remains fully offline.
* Layer 3 sends only the minimum resource locator and analysis prompt needed for each resource.
* For local instruction files, only the file path, file content, and extracted URL strings are sent.
* Results are merged back into the local report as Layer 3 findings.