codegate-ai 0.5.0 → 0.6.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/jonathansantilli/codegate/actions/workflows/ci.yml/badge.svg)](https://github.com/jonathansantilli/codegate/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/jonathansantilli/codegate/actions/workflows/codeql.yml/badge.svg)](https://github.com/jonathansantilli/codegate/actions/workflows/codeql.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg?url=https://deepwiki.com/jonathansantilli/codegate)](https://deepwiki.com/jonathansantilli/codegate)
 [![npm version](https://img.shields.io/npm/v/codegate-ai)](https://www.npmjs.com/package/codegate-ai)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
@@ -70,6 +71,21 @@ npm install -g codegate-ai
 codegate scan .
 ```
 
+Recommended first run:
+
+```bash
+codegate init
+```
+
+Why run `init`:
+
+- Creates `~/.codegate/config.json` so your behavior is explicit and easy to tune.
+- Makes it straightforward to set preferences like `scan_user_scope`, output format, thresholds, and tool discovery options.
+
+If you skip `init`, CodeGate still works with built-in defaults. Nothing breaks.
+
+See the [Configuration](#configuration) section for full settings and examples.
+
 ## System Capabilities
 
 1. Multi-layer analysis pipeline:
@@ -187,6 +203,7 @@ Behavior:
 Wrapper flags (consumed by CodeGate, not forwarded):
 
 - `--cg-force`
+- `--cg-deep`
 - `--cg-no-tui`
 - `--cg-include-user-scope`
 - `--cg-format <type>`
@@ -197,8 +214,10 @@ Examples:
 ```bash
 codegate skills add https://github.com/vercel-labs/skills --skill find-skills
 codegate skills add https://github.com/owner/repo --skill security-review --cg-force
+codegate skills add https://github.com/owner/repo --skill security-review --cg-deep
 codegate clawhub install security-auditor
 codegate clawhub install security-auditor --version 1.0.0
+codegate clawhub install security-auditor --cg-deep
 codegate clawhub search security
 ```
 

package/dist/cli.js

@@ -68,6 +68,51 @@ function mapAcquisitionFailure(status, error) {
         error: error ?? "tool description acquisition failed",
     };
 }
+async function runMetaAgentCommandWithSandbox(context) {
+    const commandResult = await runSandboxCommand({
+        command: context.command.command,
+        args: context.command.args,
+        cwd: context.command.cwd,
+        timeoutMs: context.command.timeoutMs,
+    });
+    return {
+        command: context.command,
+        code: commandResult.code,
+        stdout: commandResult.stdout,
+        stderr: commandResult.stderr,
+    };
+}
+function resolveInteractiveCallback(input) {
+    if (!input.enabled) {
+        return undefined;
+    }
+    return input.provided ?? input.fallback;
+}
+function buildWrapperScanBridgeDeps(deps) {
+    const isTTY = deps.isTTY();
+    return {
+        prepareScanDiscovery: deps.prepareScanDiscovery,
+        discoverDeepResources: deps.discoverDeepResources,
+        discoverLocalTextTargets: deps.discoverLocalTextTargets,
+        requestDeepScanConsent: resolveInteractiveCallback({
+            enabled: true,
+            provided: deps.requestDeepScanConsent,
+            fallback: isTTY ? promptDeepScanConsent : undefined,
+        }),
+        requestDeepAgentSelection: resolveInteractiveCallback({
+            enabled: true,
+            provided: deps.requestDeepAgentSelection,
+            fallback: isTTY ? promptDeepAgentSelection : undefined,
+        }),
+        requestMetaAgentCommandConsent: resolveInteractiveCallback({
+            enabled: true,
+            provided: deps.requestMetaAgentCommandConsent,
+            fallback: isTTY ? promptMetaAgentCommandConsent : undefined,
+        }),
+        runMetaAgentCommand: deps.runMetaAgentCommand ?? runMetaAgentCommandWithSandbox,
+        executeDeepResource: deps.executeDeepResource,
+    };
+}
 async function promptRunWarningConsent(context) {
     const rl = createInterface({
         input: process.stdin,
@@ -247,38 +292,28 @@ function addScanCommand(program, version, deps) {
                 prepareScanDiscovery: deps.prepareScanDiscovery,
                 discoverDeepResources: deps.discoverDeepResources,
                 discoverLocalTextTargets: deps.discoverLocalTextTargets,
-                requestDeepScanConsent: promptCallbacksEnabled
-                    ? (deps.requestDeepScanConsent ??
-                        (interactivePromptsEnabled ? promptDeepScanConsent : undefined))
-                    : undefined,
-                requestDeepAgentSelection: promptCallbacksEnabled
-                    ? (deps.requestDeepAgentSelection ??
-                        (interactivePromptsEnabled ? promptDeepAgentSelection : undefined))
-                    : undefined,
-                requestMetaAgentCommandConsent: promptCallbacksEnabled
-                    ? (deps.requestMetaAgentCommandConsent ??
-                        (interactivePromptsEnabled ? promptMetaAgentCommandConsent : undefined))
-                    : undefined,
+                requestDeepScanConsent: resolveInteractiveCallback({
+                    enabled: promptCallbacksEnabled,
+                    provided: deps.requestDeepScanConsent,
+                    fallback: interactivePromptsEnabled ? promptDeepScanConsent : undefined,
+                }),
+                requestDeepAgentSelection: resolveInteractiveCallback({
+                    enabled: promptCallbacksEnabled,
+                    provided: deps.requestDeepAgentSelection,
+                    fallback: interactivePromptsEnabled ? promptDeepAgentSelection : undefined,
+                }),
+                requestMetaAgentCommandConsent: resolveInteractiveCallback({
+                    enabled: promptCallbacksEnabled,
+                    provided: deps.requestMetaAgentCommandConsent,
+                    fallback: interactivePromptsEnabled ? promptMetaAgentCommandConsent : undefined,
+                }),
                 executeDeepResource: deps.executeDeepResource,
-                runMetaAgentCommand: deps.runMetaAgentCommand ??
-                    (async (context) => {
-                        const commandResult = await runSandboxCommand({
-                            command: context.command.command,
-                            args: context.command.args,
-                            cwd: context.command.cwd,
-                            timeoutMs: context.command.timeoutMs,
-                        });
-                        return {
-                            command: context.command,
-                            code: commandResult.code,
-                            stdout: commandResult.stdout,
-                            stderr: commandResult.stderr,
-                        };
-                    }),
-                requestRemediationConsent: promptCallbacksEnabled
-                    ? (deps.requestRemediationConsent ??
-                        (interactivePromptsEnabled ? promptRemediationConsent : undefined))
-                    : undefined,
+                runMetaAgentCommand: deps.runMetaAgentCommand ?? runMetaAgentCommandWithSandbox,
+                requestRemediationConsent: resolveInteractiveCallback({
+                    enabled: promptCallbacksEnabled,
+                    provided: deps.requestRemediationConsent,
+                    fallback: interactivePromptsEnabled ? promptRemediationConsent : undefined,
+                }),
                 runRemediation: deps.runRemediation,
                 stdout: deps.stdout,
                 stderr: deps.stderr,
@@ -378,6 +413,7 @@ function addSkillsCommand(program, version, deps) {
         .addHelpText("after", renderExampleHelp([
         "codegate skills add vercel-labs/skills --skill find-skills",
         "codegate skills add https://github.com/owner/repo --skill security-review",
+        "codegate skills add owner/repo --skill demo --cg-deep",
         "codegate skills find security",
         "codegate skills add owner/repo --skill demo --cg-force",
     ]))
@@ -390,6 +426,7 @@ function addSkillsCommand(program, version, deps) {
                     pathExists: deps.pathExists,
                     resolveConfig: deps.resolveConfig,
                     runScan: deps.runScan,
+                    ...buildWrapperScanBridgeDeps(deps),
                     resolveScanTarget: deps.resolveScanTarget,
                     requestSkillSelection: deps.requestSkillSelection,
                     requestWarningProceed: deps.requestRunWarningConsent,
@@ -420,6 +457,7 @@ function addClawhubCommand(program, version, deps) {
         .addHelpText("after", renderExampleHelp([
         "codegate clawhub install security-auditor",
         "codegate clawhub install security-auditor --version 1.0.0",
+        "codegate clawhub install security-auditor --cg-deep",
         "codegate clawhub search security",
         "codegate clawhub install security-auditor --cg-force",
     ]))
@@ -432,6 +470,7 @@ function addClawhubCommand(program, version, deps) {
                     pathExists: deps.pathExists,
                     resolveConfig: deps.resolveConfig,
                     runScan: deps.runScan,
+                    ...buildWrapperScanBridgeDeps(deps),
                     resolveScanTarget: deps.resolveScanTarget,
                     requestWarningProceed: deps.requestRunWarningConsent,
                     launchClawhub: deps.launchClawhub ?? ((args, cwd) => launchClawhubPassthrough(args, cwd)),

package/dist/commands/clawhub-wrapper.d.ts

@@ -1,13 +1,14 @@
 import { type CodeGateConfig, type OutputFormat, type ResolveConfigOptions } from "../config.js";
 import { type ResolvedScanTarget } from "../scan-target.js";
 import type { CodeGateReport } from "../types/report.js";
-import type { ScanRunnerInput } from "./scan-command.js";
+import { type ScanAnalysisDeps, type ScanRunnerInput } from "./scan-command.js";
 interface SourceDetectionContext {
     cwd: string;
     pathExists: (path: string) => boolean;
 }
 export interface ClawhubWrapperRuntimeOptions {
     force: boolean;
+    deep: boolean;
     noTui: boolean;
     includeUserScope: boolean;
     format?: OutputFormat;
@@ -38,6 +39,14 @@ export interface ClawhubWrapperDeps {
     pathExists?: (path: string) => boolean;
     resolveConfig: (options: ResolveConfigOptions) => CodeGateConfig;
     runScan: (input: ScanRunnerInput) => Promise<CodeGateReport>;
+    prepareScanDiscovery?: ScanAnalysisDeps["prepareScanDiscovery"];
+    discoverDeepResources?: ScanAnalysisDeps["discoverDeepResources"];
+    discoverLocalTextTargets?: ScanAnalysisDeps["discoverLocalTextTargets"];
+    requestDeepScanConsent?: ScanAnalysisDeps["requestDeepScanConsent"];
+    requestDeepAgentSelection?: ScanAnalysisDeps["requestDeepAgentSelection"];
+    requestMetaAgentCommandConsent?: ScanAnalysisDeps["requestMetaAgentCommandConsent"];
+    runMetaAgentCommand?: ScanAnalysisDeps["runMetaAgentCommand"];
+    executeDeepResource?: ScanAnalysisDeps["executeDeepResource"];
     resolveScanTarget?: (input: {
         rawTarget: string;
         cwd: string;

package/dist/commands/clawhub-wrapper.js

@@ -3,9 +3,9 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { applyConfigPolicy, OUTPUT_FORMATS, } from "../config.js";
-import { reorderRequestedTargetFindings } from "../report/requested-target-findings.js";
+import { OUTPUT_FORMATS, } from "../config.js";
 import { resolveScanTarget } from "../scan-target.js";
+import { runScanAnalysis } from "./scan-command.js";
 import { renderByFormat, summarizeRequestedTargetFindings } from "./scan-command/helpers.js";
 const CLAWHUB_GLOBAL_OPTIONS_WITH_VALUE = new Set(["--workdir", "--dir", "--site", "--registry"]);
 const CLAWHUB_INSTALL_OPTIONS_WITH_VALUE = new Set(["--version"]);
@@ -381,6 +381,7 @@ async function stageClawhubTargetDefault(input, deps) {
 export function parseClawhubInvocation(rawArgs, context) {
     const wrapper = {
         force: false,
+        deep: false,
         noTui: false,
         includeUserScope: false,
         format: undefined,
@@ -400,6 +401,10 @@ export function parseClawhubInvocation(rawArgs, context) {
             wrapper.force = true;
             continue;
         }
+        if (token === "--cg-deep") {
+            wrapper.deep = true;
+            continue;
+        }
         if (token === "--cg-no-tui") {
             wrapper.noTui = true;
             continue;
@@ -527,41 +532,55 @@ export async function executeClawhubWrapper(input, deps) {
         const config = parsed.wrapper.includeUserScope
             ? { ...baseConfig, scan_user_scope: true }
             : baseConfig;
-        let report = await deps.runScan({
+        const { report, deepScanNotes } = await runScanAnalysis({
             version: input.version,
             scanTarget: resolvedTarget.scanTarget,
+            displayTarget: resolvedTarget.displayTarget,
+            explicitCandidates: resolvedTarget.explicitCandidates,
             config,
-            flags: {
+            options: {
                 noTui,
                 format: parsed.wrapper.format,
                 force: parsed.wrapper.force,
                 includeUserScope: parsed.wrapper.includeUserScope,
+                deep: parsed.wrapper.deep,
             },
-            discoveryContext: undefined,
+        }, {
+            isTTY: deps.isTTY,
+            runScan: deps.runScan,
+            prepareScanDiscovery: deps.prepareScanDiscovery,
+            discoverDeepResources: deps.discoverDeepResources,
+            discoverLocalTextTargets: deps.discoverLocalTextTargets,
+            requestDeepScanConsent: interactivePromptsEnabled ? deps.requestDeepScanConsent : undefined,
+            requestDeepAgentSelection: interactivePromptsEnabled
+                ? deps.requestDeepAgentSelection
+                : undefined,
+            requestMetaAgentCommandConsent: interactivePromptsEnabled
+                ? deps.requestMetaAgentCommandConsent
+                : undefined,
+            runMetaAgentCommand: deps.runMetaAgentCommand,
+            executeDeepResource: deps.executeDeepResource,
         });
-        if (resolvedTarget.displayTarget && resolvedTarget.displayTarget !== report.scan_target) {
-            report = {
-                ...report,
-                scan_target: resolvedTarget.displayTarget,
-            };
-        }
-        report = applyConfigPolicy(report, config);
-        report = reorderRequestedTargetFindings(report, resolvedTarget.displayTarget);
         const shouldUseTui = config.tui.enabled && isTTY && deps.renderTui !== undefined && noTui !== true;
         const targetSummaryNote = config.output_format === "terminal"
             ? summarizeRequestedTargetFindings(report, resolvedTarget.displayTarget)
             : null;
+        const scanNotes = config.output_format === "terminal"
+            ? targetSummaryNote
+                ? [...deepScanNotes, targetSummaryNote]
+                : deepScanNotes
+            : [];
         if (shouldUseTui) {
             deps.renderTui?.({
                 view: "dashboard",
                 report,
-                notices: targetSummaryNote ? [targetSummaryNote] : undefined,
+                notices: scanNotes.length > 0 ? scanNotes : undefined,
             });
             deps.renderTui?.({ view: "summary", report });
         }
         else {
-            if (targetSummaryNote) {
-                deps.stdout(targetSummaryNote);
+            for (const note of scanNotes) {
+                deps.stdout(note);
             }
             deps.stdout(renderByFormat(config.output_format, report));
         }

package/dist/commands/scan-command.d.ts

@@ -88,4 +88,13 @@ export interface ExecuteScanCommandDeps {
         notices?: string[];
     }) => void;
 }
+type ScanAnalysisDepKeys = "isTTY" | "runScan" | "prepareScanDiscovery" | "discoverDeepResources" | "discoverLocalTextTargets" | "requestDeepScanConsent" | "requestDeepAgentSelection" | "requestMetaAgentCommandConsent" | "runMetaAgentCommand" | "executeDeepResource";
+export type ScanAnalysisDeps = Pick<ExecuteScanCommandDeps, ScanAnalysisDepKeys>;
+export type ScanAnalysisInput = Omit<ExecuteScanCommandInput, "cwd">;
+export interface ScanAnalysisResult {
+    report: CodeGateReport;
+    deepScanNotes: string[];
+}
+export declare function runScanAnalysis(input: ScanAnalysisInput, deps: ScanAnalysisDeps): Promise<ScanAnalysisResult>;
 export declare function executeScanCommand(input: ExecuteScanCommandInput, deps: ExecuteScanCommandDeps): Promise<void>;
+export {};

package/dist/commands/scan-command.js

@@ -68,229 +68,249 @@ function deepAgentOptions(report, config) {
         return order.indexOf(left.id) - order.indexOf(right.id);
     });
 }
-export async function executeScanCommand(input, deps) {
-    try {
-        const interactivePromptsEnabled = deps.isTTY() && input.options.noTui !== true;
-        const discoveryContext = deps.prepareScanDiscovery
-            ? await deps.prepareScanDiscovery(input.scanTarget, input.config, {
-                explicitCandidates: input.explicitCandidates,
-            })
-            : undefined;
-        let report = await deps.runScan({
-            version: input.version,
-            scanTarget: input.scanTarget,
-            config: input.config,
-            flags: input.options,
-            discoveryContext,
-        });
-        if (input.displayTarget && input.displayTarget !== report.scan_target) {
-            report = {
-                ...report,
-                scan_target: input.displayTarget,
-            };
+export async function runScanAnalysis(input, deps) {
+    const interactivePromptsEnabled = deps.isTTY() && input.options.noTui !== true;
+    const discoveryContext = deps.prepareScanDiscovery
+        ? await deps.prepareScanDiscovery(input.scanTarget, input.config, {
+            explicitCandidates: input.explicitCandidates,
+        })
+        : undefined;
+    let report = await deps.runScan({
+        version: input.version,
+        scanTarget: input.scanTarget,
+        config: input.config,
+        flags: input.options,
+        discoveryContext,
+    });
+    if (input.displayTarget && input.displayTarget !== report.scan_target) {
+        report = {
+            ...report,
+            scan_target: input.displayTarget,
+        };
+    }
+    const deepScanNotes = [];
+    if (input.options.deep) {
+        const discoverResources = deps.discoverDeepResources ?? (async () => []);
+        const discoverLocalTextTargets = deps.discoverLocalTextTargets ?? (async () => []);
+        const resources = await discoverResources(input.scanTarget, input.config, discoveryContext);
+        const localTextTargets = await discoverLocalTextTargets(input.scanTarget, input.config, discoveryContext);
+        const optionsForAgent = deepAgentOptions(report, input.config);
+        let selectedAgent = null;
+        if ((resources.length > 0 || localTextTargets.length > 0) && optionsForAgent.length > 0) {
+            if (input.options.force || !interactivePromptsEnabled) {
+                selectedAgent = optionsForAgent[0] ?? null;
+            }
+            else if (deps.requestDeepAgentSelection) {
+                selectedAgent = await deps.requestDeepAgentSelection(optionsForAgent);
+            }
         }
-        const deepScanNotes = [];
-        if (input.options.deep) {
-            const discoverResources = deps.discoverDeepResources ?? (async () => []);
-            const discoverLocalTextTargets = deps.discoverLocalTextTargets ?? (async () => []);
-            const resources = await discoverResources(input.scanTarget, input.config, discoveryContext);
-            const localTextTargets = await discoverLocalTextTargets(input.scanTarget, input.config, discoveryContext);
-            const optionsForAgent = deepAgentOptions(report, input.config);
-            let selectedAgent = null;
-            if ((resources.length > 0 || localTextTargets.length > 0) && optionsForAgent.length > 0) {
-                if (input.options.force || !interactivePromptsEnabled) {
-                    selectedAgent = optionsForAgent[0] ?? null;
-                }
-                else if (deps.requestDeepAgentSelection) {
-                    selectedAgent = await deps.requestDeepAgentSelection(optionsForAgent);
-                }
+        if (resources.length === 0 && localTextTargets.length === 0) {
+            deepScanNotes.push(...noEligibleDeepResourceNotes());
+        }
+        else {
+            if (selectedAgent) {
+                deepScanNotes.push(`Deep scan meta-agent selected: ${selectedAgent.label} (${selectedAgent.binary})`);
             }
-            if (resources.length === 0 && localTextTargets.length === 0) {
-                deepScanNotes.push(...noEligibleDeepResourceNotes());
+            else if (optionsForAgent.length > 0) {
+                deepScanNotes.push("Deep scan meta-agent skipped. Running deterministic Layer 3 checks only.");
             }
             else {
-                if (selectedAgent) {
-                    deepScanNotes.push(`Deep scan meta-agent selected: ${selectedAgent.label} (${selectedAgent.binary})`);
-                }
-                else if (optionsForAgent.length > 0) {
-                    deepScanNotes.push("Deep scan meta-agent skipped. Running deterministic Layer 3 checks only.");
-                }
-                else {
-                    deepScanNotes.push("No supported deep-scan agent detected (Claude Code, Codex CLI, or OpenCode). Running deterministic Layer 3 checks only.");
+                deepScanNotes.push("No supported deep-scan agent detected (Claude Code, Codex CLI, or OpenCode). Running deterministic Layer 3 checks only.");
+            }
+            if (resources.length > 0) {
+                if (!deps.executeDeepResource) {
+                    throw new Error("Deep resource executor not configured");
                 }
-                if (resources.length > 0) {
-                    if (!deps.executeDeepResource) {
-                        throw new Error("Deep resource executor not configured");
+                let resourcesWithFetchedMetadata = 0;
+                let executedMetaAgentCommands = 0;
+                const outcomes = await runDeepScanWithConsent(resources, async (resource) => {
+                    if (input.options.force) {
+                        return true;
                     }
-                    let resourcesWithFetchedMetadata = 0;
-                    let executedMetaAgentCommands = 0;
-                    const outcomes = await runDeepScanWithConsent(resources, async (resource) => {
-                        if (input.options.force) {
-                            return true;
-                        }
-                        if (deps.requestDeepScanConsent) {
-                            return await deps.requestDeepScanConsent(resource);
-                        }
-                        return false;
-                    }, async (resource) => {
-                        const fetched = await deps.executeDeepResource(resource);
-                        if (fetched.status !== "ok" || !selectedAgent) {
-                            return fetched;
-                        }
-                        resourcesWithFetchedMetadata += 1;
-                        const prompt = buildSecurityAnalysisPrompt({
-                            resourceId: resource.id,
-                            resourceSummary: metadataSummary(fetched.metadata),
-                        });
-                        const command = buildMetaAgentCommand({
-                            tool: selectedAgent.metaTool,
-                            prompt,
-                            workingDirectory: input.scanTarget,
-                            binaryPath: selectedAgent.binary,
-                        });
-                        const commandContext = {
-                            resource,
-                            agent: selectedAgent,
-                            command,
+                    if (deps.requestDeepScanConsent) {
+                        return await deps.requestDeepScanConsent(resource);
+                    }
+                    return false;
+                }, async (resource) => {
+                    const fetched = await deps.executeDeepResource(resource);
+                    if (fetched.status !== "ok" || !selectedAgent) {
+                        return fetched;
+                    }
+                    resourcesWithFetchedMetadata += 1;
+                    const prompt = buildSecurityAnalysisPrompt({
+                        resourceId: resource.id,
+                        resourceSummary: metadataSummary(fetched.metadata),
+                    });
+                    const command = buildMetaAgentCommand({
+                        tool: selectedAgent.metaTool,
+                        prompt,
+                        workingDirectory: input.scanTarget,
+                        binaryPath: selectedAgent.binary,
+                    });
+                    const commandContext = {
+                        resource,
+                        agent: selectedAgent,
+                        command,
+                    };
+                    const approvedCommand = input.options.force ||
+                        (deps.requestMetaAgentCommandConsent
+                            ? await deps.requestMetaAgentCommandConsent(commandContext)
+                            : false);
+                    if (!approvedCommand) {
+                        return {
+                            ...fetched,
+                            metadata: withMetaAgentFinding(fetched.metadata, {
+                                id: `layer3-meta-agent-skipped-${resource.id}`,
+                                severity: "INFO",
+                                description: `Deep scan meta-agent command skipped for ${resource.id}`,
+                            }),
                         };
-                        const approvedCommand = input.options.force ||
-                            (deps.requestMetaAgentCommandConsent
-                                ? await deps.requestMetaAgentCommandConsent(commandContext)
-                                : false);
-                        if (!approvedCommand) {
-                            return {
-                                ...fetched,
-                                metadata: withMetaAgentFinding(fetched.metadata, {
-                                    id: `layer3-meta-agent-skipped-${resource.id}`,
-                                    severity: "INFO",
-                                    description: `Deep scan meta-agent command skipped for ${resource.id}`,
-                                }),
-                            };
-                        }
-                        if (!deps.runMetaAgentCommand) {
-                            throw new Error("Meta-agent command runner not configured");
-                        }
-                        executedMetaAgentCommands += 1;
-                        const commandResult = await deps.runMetaAgentCommand(commandContext);
-                        if (commandResult.code !== 0) {
-                            return {
-                                ...fetched,
-                                metadata: withMetaAgentFinding(fetched.metadata, {
-                                    id: `layer3-meta-agent-command-error-${resource.id}`,
-                                    severity: "LOW",
-                                    description: `Deep scan meta-agent command failed for ${resource.id}`,
-                                    evidence: commandResult.stderr || `exit code: ${commandResult.code}`,
-                                }),
-                            };
-                        }
-                        const parsedOutput = parseMetaAgentOutput(commandResult.stdout);
-                        if (parsedOutput === null) {
-                            return {
-                                ...fetched,
-                                metadata: withMetaAgentFinding(fetched.metadata, {
-                                    id: `layer3-meta-agent-parse-error-${resource.id}`,
-                                    severity: "LOW",
-                                    description: `Deep scan meta-agent output was not valid JSON for ${resource.id}`,
-                                    evidence: commandResult.stdout.slice(0, 400),
-                                }),
-                            };
-                        }
-                        const normalizedOutput = Array.isArray(parsedOutput)
-                            ? { findings: parsedOutput }
-                            : parsedOutput;
+                    }
+                    if (!deps.runMetaAgentCommand) {
+                        throw new Error("Meta-agent command runner not configured");
+                    }
+                    executedMetaAgentCommands += 1;
+                    const commandResult = await deps.runMetaAgentCommand(commandContext);
+                    if (commandResult.code !== 0) {
                         return {
                             ...fetched,
-                            metadata: mergeMetaAgentMetadata(fetched.metadata, normalizedOutput),
+                            metadata: withMetaAgentFinding(fetched.metadata, {
+                                id: `layer3-meta-agent-command-error-${resource.id}`,
+                                severity: "LOW",
+                                description: `Deep scan meta-agent command failed for ${resource.id}`,
+                                evidence: commandResult.stderr || `exit code: ${commandResult.code}`,
+                            }),
                         };
-                    });
-                    const layer3Findings = layer3OutcomesToFindings(outcomes, {
-                        unicodeAnalysis: input.config.unicode_analysis,
-                    });
-                    report = mergeLayer3Findings(report, layer3Findings);
-                    if (selectedAgent) {
-                        if (resourcesWithFetchedMetadata === 0) {
-                            deepScanNotes.push("Selected meta-agent was not executed because no approved resources returned metadata successfully.");
-                        }
-                        else if (executedMetaAgentCommands === 0) {
-                            deepScanNotes.push("Selected meta-agent was not executed because meta-agent command execution was not approved.");
-                        }
-                        else {
-                            const suffix = executedMetaAgentCommands === 1 ? "" : "s";
-                            deepScanNotes.push(`Deep scan meta-agent executed for ${executedMetaAgentCommands} resource${suffix}.`);
-                        }
                     }
-                }
-                if (localTextTargets.length > 0) {
-                    if (!selectedAgent) {
-                        deepScanNotes.push("Local instruction-file analysis skipped because no meta-agent was selected.");
+                    const parsedOutput = parseMetaAgentOutput(commandResult.stdout);
+                    if (parsedOutput === null) {
+                        return {
+                            ...fetched,
+                            metadata: withMetaAgentFinding(fetched.metadata, {
+                                id: `layer3-meta-agent-parse-error-${resource.id}`,
+                                severity: "LOW",
+                                description: `Deep scan meta-agent output was not valid JSON for ${resource.id}`,
+                                evidence: commandResult.stdout.slice(0, 400),
+                            }),
+                        };
+                    }
+                    const normalizedOutput = Array.isArray(parsedOutput)
+                        ? { findings: parsedOutput }
+                        : parsedOutput;
+                    return {
+                        ...fetched,
+                        metadata: mergeMetaAgentMetadata(fetched.metadata, normalizedOutput),
+                    };
+                });
+                const layer3Findings = layer3OutcomesToFindings(outcomes, {
+                    unicodeAnalysis: input.config.unicode_analysis,
+                });
+                report = mergeLayer3Findings(report, layer3Findings);
+                if (selectedAgent) {
+                    if (resourcesWithFetchedMetadata === 0) {
+                        deepScanNotes.push("Selected meta-agent was not executed because no approved resources returned metadata successfully.");
                     }
-                    else if (!supportsToollessLocalTextAnalysis(selectedAgent.metaTool)) {
-                        deepScanNotes.push("Local instruction-file analysis was skipped because the selected agent does not support tool-less analysis.");
+                    else if (executedMetaAgentCommands === 0) {
+                        deepScanNotes.push("Selected meta-agent was not executed because meta-agent command execution was not approved.");
                     }
                     else {
-                        // Local instruction files are analyzed as inert text only; referenced URLs stay as evidence, not inputs.
-                        if (!deps.runMetaAgentCommand) {
-                            throw new Error("Meta-agent command runner not configured");
-                        }
-                        const isolatedWorkingDirectory = mkdtempSync(join(tmpdir(), "codegate-local-analysis-"));
-                        let executedLocalAnalyses = 0;
-                        try {
-                            for (const target of localTextTargets) {
-                                const prompt = buildLocalTextAnalysisPrompt({
-                                    filePath: target.reportPath,
-                                    textContent: buildPromptEvidenceText(target.textContent),
-                                    referencedUrls: target.referencedUrls,
-                                });
-                                const command = buildMetaAgentCommand({
-                                    tool: selectedAgent.metaTool,
-                                    prompt,
-                                    workingDirectory: isolatedWorkingDirectory,
-                                    binaryPath: selectedAgent.binary,
-                                });
-                                command.timeoutMs = 60_000;
-                                const commandContext = {
-                                    localFile: target,
-                                    agent: selectedAgent,
-                                    command,
-                                };
-                                const approvedCommand = input.options.force ||
-                                    (deps.requestMetaAgentCommandConsent
-                                        ? await deps.requestMetaAgentCommandConsent(commandContext)
-                                        : false);
-                                if (!approvedCommand) {
-                                    continue;
-                                }
-                                executedLocalAnalyses += 1;
-                                const commandResult = await deps.runMetaAgentCommand(commandContext);
-                                if (commandResult.code !== 0) {
-                                    deepScanNotes.push(`Local instruction-file analysis failed for ${target.reportPath}: ${commandResult.stderr || `exit code: ${commandResult.code}`}`);
-                                    continue;
-                                }
-                                const parsedOutput = parseMetaAgentOutput(commandResult.stdout);
-                                if (parsedOutput === null) {
-                                    deepScanNotes.push(`Local instruction-file analysis returned invalid JSON for ${target.reportPath}.`);
-                                    continue;
-                                }
-                                const normalizedOutput = Array.isArray(parsedOutput)
-                                    ? { findings: parsedOutput }
-                                    : parsedOutput;
-                                const localFindings = parseLocalTextFindings(target.reportPath, normalizedOutput);
-                                report = mergeLayer3Findings(report, localFindings);
+                        const suffix = executedMetaAgentCommands === 1 ? "" : "s";
+                        deepScanNotes.push(`Deep scan meta-agent executed for ${executedMetaAgentCommands} resource${suffix}.`);
+                    }
+                }
+            }
+            if (localTextTargets.length > 0) {
+                if (!selectedAgent) {
+                    deepScanNotes.push("Local instruction-file analysis skipped because no meta-agent was selected.");
+                }
+                else if (!supportsToollessLocalTextAnalysis(selectedAgent.metaTool)) {
+                    deepScanNotes.push("Local instruction-file analysis was skipped because the selected agent does not support tool-less analysis.");
+                }
+                else {
+                    // Local instruction files are analyzed as inert text only; referenced URLs stay as evidence, not inputs.
+                    if (!deps.runMetaAgentCommand) {
+                        throw new Error("Meta-agent command runner not configured");
+                    }
+                    const isolatedWorkingDirectory = mkdtempSync(join(tmpdir(), "codegate-local-analysis-"));
+                    let executedLocalAnalyses = 0;
+                    try {
+                        for (const target of localTextTargets) {
+                            const prompt = buildLocalTextAnalysisPrompt({
+                                filePath: target.reportPath,
+                                textContent: buildPromptEvidenceText(target.textContent),
+                                referencedUrls: target.referencedUrls,
+                            });
+                            const command = buildMetaAgentCommand({
+                                tool: selectedAgent.metaTool,
+                                prompt,
+                                workingDirectory: isolatedWorkingDirectory,
+                                binaryPath: selectedAgent.binary,
+                            });
+                            command.timeoutMs = 60_000;
+                            const commandContext = {
+                                localFile: target,
+                                agent: selectedAgent,
+                                command,
+                            };
+                            const approvedCommand = input.options.force ||
+                                (deps.requestMetaAgentCommandConsent
+                                    ? await deps.requestMetaAgentCommandConsent(commandContext)
+                                    : false);
+                            if (!approvedCommand) {
+                                continue;
                             }
-                        }
-                        finally {
-                            rmSync(isolatedWorkingDirectory, { recursive: true, force: true });
-                        }
-                        if (executedLocalAnalyses > 0) {
-                            const suffix = executedLocalAnalyses === 1 ? "" : "s";
-                            deepScanNotes.push(`Local instruction-file analysis executed for ${executedLocalAnalyses} file${suffix}.`);
+                            executedLocalAnalyses += 1;
+                            const commandResult = await deps.runMetaAgentCommand(commandContext);
+                            if (commandResult.code !== 0) {
+                                deepScanNotes.push(`Local instruction-file analysis failed for ${target.reportPath}: ${commandResult.stderr || `exit code: ${commandResult.code}`}`);
+                                continue;
+                            }
+                            const parsedOutput = parseMetaAgentOutput(commandResult.stdout);
+                            if (parsedOutput === null) {
+                                deepScanNotes.push(`Local instruction-file analysis returned invalid JSON for ${target.reportPath}.`);
+                                continue;
+                            }
+                            const normalizedOutput = Array.isArray(parsedOutput)
+                                ? { findings: parsedOutput }
+                                : parsedOutput;
+                            const localFindings = parseLocalTextFindings(target.reportPath, normalizedOutput);
+                            report = mergeLayer3Findings(report, localFindings);
                         }
                     }
+                    finally {
+                        rmSync(isolatedWorkingDirectory, { recursive: true, force: true });
+                    }
+                    if (executedLocalAnalyses > 0) {
+                        const suffix = executedLocalAnalyses === 1 ? "" : "s";
+                        deepScanNotes.push(`Local instruction-file analysis executed for ${executedLocalAnalyses} file${suffix}.`);
+                    }
                 }
             }
         }
-        report = applyConfigPolicy(report, input.config);
-        report = reorderRequestedTargetFindings(report, input.displayTarget);
+    }
+    report = applyConfigPolicy(report, input.config);
+    report = reorderRequestedTargetFindings(report, input.displayTarget);
+    return {
+        report,
+        deepScanNotes,
+    };
+}
+export async function executeScanCommand(input, deps) {
+    try {
+        const interactivePromptsEnabled = deps.isTTY() && input.options.noTui !== true;
+        const { report: analyzedReport, deepScanNotes } = await runScanAnalysis(input, {
+            isTTY: deps.isTTY,
+            runScan: deps.runScan,
+            prepareScanDiscovery: deps.prepareScanDiscovery,
+            discoverDeepResources: deps.discoverDeepResources,
+            discoverLocalTextTargets: deps.discoverLocalTextTargets,
+            requestDeepScanConsent: deps.requestDeepScanConsent,
+            requestDeepAgentSelection: deps.requestDeepAgentSelection,
+            requestMetaAgentCommandConsent: deps.requestMetaAgentCommandConsent,
+            runMetaAgentCommand: deps.runMetaAgentCommand,
+            executeDeepResource: deps.executeDeepResource,
+        });
+        let report = analyzedReport;
         const remediationRequested = input.options.remediate ||
             input.options.fixSafe ||
             input.options.dryRun ||
@@ -378,7 +398,11 @@ export async function executeScanCommand(input, deps) {
         const targetSummaryNote = input.config.output_format === "terminal"
             ? summarizeRequestedTargetFindings(report, input.displayTarget)
             : null;
-        const scanNotes = targetSummaryNote ? [...deepScanNotes, targetSummaryNote] : deepScanNotes;
+        const scanNotes = input.config.output_format === "terminal"
+            ? targetSummaryNote
+                ? [...deepScanNotes, targetSummaryNote]
+                : deepScanNotes
+            : [];
         if (shouldUseTui) {
             deps.renderTui?.({ view: "dashboard", report, notices: scanNotes });
             deps.renderTui?.({ view: "summary", report });

package/dist/commands/skills-wrapper.d.ts

@@ -1,9 +1,10 @@
 import { type CodeGateConfig, type OutputFormat, type ResolveConfigOptions } from "../config.js";
 import { type ResolvedScanTarget } from "../scan-target.js";
-import type { ScanRunnerInput } from "./scan-command.js";
+import { type ScanAnalysisDeps, type ScanRunnerInput } from "./scan-command.js";
 import type { CodeGateReport } from "../types/report.js";
 export interface SkillsWrapperRuntimeOptions {
     force: boolean;
+    deep: boolean;
     noTui: boolean;
     includeUserScope: boolean;
     format?: OutputFormat;
@@ -34,6 +35,14 @@ export interface SkillsWrapperDeps {
     pathExists?: (path: string) => boolean;
     resolveConfig: (options: ResolveConfigOptions) => CodeGateConfig;
     runScan: (input: ScanRunnerInput) => Promise<CodeGateReport>;
+    prepareScanDiscovery?: ScanAnalysisDeps["prepareScanDiscovery"];
+    discoverDeepResources?: ScanAnalysisDeps["discoverDeepResources"];
+    discoverLocalTextTargets?: ScanAnalysisDeps["discoverLocalTextTargets"];
+    requestDeepScanConsent?: ScanAnalysisDeps["requestDeepScanConsent"];
+    requestDeepAgentSelection?: ScanAnalysisDeps["requestDeepAgentSelection"];
+    requestMetaAgentCommandConsent?: ScanAnalysisDeps["requestMetaAgentCommandConsent"];
+    runMetaAgentCommand?: ScanAnalysisDeps["runMetaAgentCommand"];
+    executeDeepResource?: ScanAnalysisDeps["executeDeepResource"];
     resolveScanTarget?: (input: {
         rawTarget: string;
         cwd: string;

package/dist/commands/skills-wrapper.js

@@ -2,10 +2,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { resolve } from "node:path";
-import { applyConfigPolicy, OUTPUT_FORMATS, } from "../config.js";
+import { OUTPUT_FORMATS, } from "../config.js";
 import { renderByFormat, summarizeRequestedTargetFindings } from "./scan-command/helpers.js";
-import { reorderRequestedTargetFindings } from "../report/requested-target-findings.js";
 import { resolveScanTarget } from "../scan-target.js";
+import { runScanAnalysis } from "./scan-command.js";
 function parseWrapperOptionValue(args, index, flag) {
     const current = args[index] ?? "";
     const withEquals = `${flag}=`;
@@ -177,6 +177,7 @@ function findAddSubcommandIndex(args, context) {
 export function parseSkillsInvocation(rawArgs, context) {
     const wrapper = {
         force: false,
+        deep: false,
         noTui: false,
         includeUserScope: false,
         format: undefined,
@@ -196,6 +197,10 @@ export function parseSkillsInvocation(rawArgs, context) {
             wrapper.force = true;
             continue;
         }
+        if (token === "--cg-deep") {
+            wrapper.deep = true;
+            continue;
+        }
         if (token === "--cg-no-tui") {
             wrapper.noTui = true;
             continue;
@@ -320,42 +325,56 @@ export async function executeSkillsWrapper(input, deps) {
         const config = parsed.wrapper.includeUserScope
             ? { ...baseConfig, scan_user_scope: true }
             : baseConfig;
-        let report = await deps.runScan({
+        const { report, deepScanNotes } = await runScanAnalysis({
             version: input.version,
             scanTarget: resolvedTarget.scanTarget,
+            displayTarget: resolvedTarget.displayTarget,
+            explicitCandidates: resolvedTarget.explicitCandidates,
             config,
-            flags: {
+            options: {
                 noTui,
                 format: parsed.wrapper.format,
                 force: parsed.wrapper.force,
                 includeUserScope: parsed.wrapper.includeUserScope,
                 skill: preferredSkill,
+                deep: parsed.wrapper.deep,
             },
-            discoveryContext: undefined,
+        }, {
+            isTTY: deps.isTTY,
+            runScan: deps.runScan,
+            prepareScanDiscovery: deps.prepareScanDiscovery,
+            discoverDeepResources: deps.discoverDeepResources,
+            discoverLocalTextTargets: deps.discoverLocalTextTargets,
+            requestDeepScanConsent: interactivePromptsEnabled ? deps.requestDeepScanConsent : undefined,
+            requestDeepAgentSelection: interactivePromptsEnabled
+                ? deps.requestDeepAgentSelection
+                : undefined,
+            requestMetaAgentCommandConsent: interactivePromptsEnabled
+                ? deps.requestMetaAgentCommandConsent
+                : undefined,
+            runMetaAgentCommand: deps.runMetaAgentCommand,
+            executeDeepResource: deps.executeDeepResource,
         });
-        if (resolvedTarget.displayTarget && resolvedTarget.displayTarget !== report.scan_target) {
-            report = {
-                ...report,
-                scan_target: resolvedTarget.displayTarget,
-            };
-        }
-        report = applyConfigPolicy(report, config);
-        report = reorderRequestedTargetFindings(report, resolvedTarget.displayTarget);
         const shouldUseTui = config.tui.enabled && isTTY && deps.renderTui !== undefined && noTui !== true;
         const targetSummaryNote = config.output_format === "terminal"
             ? summarizeRequestedTargetFindings(report, resolvedTarget.displayTarget)
             : null;
+        const scanNotes = config.output_format === "terminal"
+            ? targetSummaryNote
+                ? [...deepScanNotes, targetSummaryNote]
+                : deepScanNotes
+            : [];
         if (shouldUseTui) {
             deps.renderTui?.({
                 view: "dashboard",
                 report,
-                notices: targetSummaryNote ? [targetSummaryNote] : undefined,
+                notices: scanNotes.length > 0 ? scanNotes : undefined,
             });
             deps.renderTui?.({ view: "summary", report });
         }
         else {
-            if (targetSummaryNote) {
-                deps.stdout(targetSummaryNote);
+            for (const note of scanNotes) {
+                deps.stdout(note);
             }
             deps.stdout(renderByFormat(config.output_format, report));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codegate-ai",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pre-flight security scanner for AI coding tool configurations.",
   "license": "MIT",
   "type": "module",