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.

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.

Enabling deep scan

Pass --deep to codegate scan:

codegate scan . --deep

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

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:

codegate scan . --deep --include-user-scope

Consent model

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

For each discovered candidate, the interactive flow is:

1. Resource presentation

   CodeGate displays the resource identifier and a preview of the fetch or analysis action it will perform.

2. 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.

3. Command preview

   CodeGate shows the exact meta-agent command it will run for this resource.

4. 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.

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:

{
  "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.