@praneeth_54/agentdoctor 0.1.0-beta

package/dist/core/rules/ignore.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal gitignore-style pattern matching for .gitignore / .cursorignore.
+ * Supports common patterns used in agent ignore files — not a full gitignore clone.
+ */
+export interface IgnoreIndex {
+    gitignorePatterns: string[];
+    cursorignorePatterns: string[];
+    matchesGitignore(relativePath: string): boolean;
+    matchesCursorignore(relativePath: string): boolean;
+    /** Whether a path appears excluded for Cursor agent/indexing purposes. */
+    isExcludedForCursor(relativePath: string): boolean;
+}
+export declare function parseIgnoreFile(content: string): string[];
+/**
+ * Match a relative POSIX path against a single gitignore-like pattern.
+ * Negation (`!`) is not fully supported for re-inclusion of parent-excluded paths.
+ */
+export declare function matchIgnorePattern(relativePath: string, pattern: string): boolean;
+export declare function pathMatchesAny(relativePath: string, patterns: string[]): boolean;
+export declare function createIgnoreIndex(options: {
+    gitignorePatterns: string[];
+    cursorignorePatterns: string[];
+}): IgnoreIndex;

package/dist/core/rules/ignore.js

@@ -0,0 +1,97 @@
+/**
+ * Minimal gitignore-style pattern matching for .gitignore / .cursorignore.
+ * Supports common patterns used in agent ignore files — not a full gitignore clone.
+ */
+function normalizePattern(pattern) {
+    const trimmed = pattern.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+        return null;
+    }
+    return trimmed.replace(/\\ /g, " ");
+}
+export function parseIgnoreFile(content) {
+    return content
+        .split(/\r?\n/)
+        .map(normalizePattern)
+        .filter((p) => p !== null);
+}
+/**
+ * Match a relative POSIX path against a single gitignore-like pattern.
+ * Negation (`!`) is not fully supported for re-inclusion of parent-excluded paths.
+ */
+export function matchIgnorePattern(relativePath, pattern) {
+    let pat = pattern;
+    if (pat.startsWith("!")) {
+        pat = pat.slice(1);
+    }
+    const pathNorm = relativePath.replace(/^\/+/, "");
+    let matched = false;
+    if (pat.endsWith("/")) {
+        const dir = pat.slice(0, -1);
+        matched =
+            pathNorm === dir ||
+                pathNorm.startsWith(`${dir}/`) ||
+                globMatch(pathNorm, dir) ||
+                pathNorm.split("/").some((_, i, parts) => globMatch(parts.slice(0, i + 1).join("/"), dir));
+    }
+    else if (pat.startsWith("/")) {
+        matched = globMatch(pathNorm, pat.slice(1));
+    }
+    else if (pat.includes("/")) {
+        matched = globMatch(pathNorm, pat) || pathNorm.endsWith(`/${pat}`);
+    }
+    else {
+        const base = pathNorm.split("/").pop() ?? pathNorm;
+        matched = globMatch(base, pat) || globMatch(pathNorm, pat) || globMatch(pathNorm, `**/${pat}`);
+    }
+    return matched;
+}
+function globMatch(value, pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "\0")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]")
+        .replace(/\0/g, ".*");
+    return new RegExp(`^${escaped}$`).test(value);
+}
+export function pathMatchesAny(relativePath, patterns) {
+    let ignored = false;
+    for (const pattern of patterns) {
+        if (pattern.startsWith("!")) {
+            if (matchIgnorePattern(relativePath, pattern.slice(1))) {
+                ignored = false;
+            }
+        }
+        else if (matchIgnorePattern(relativePath, pattern)) {
+            ignored = true;
+        }
+    }
+    return ignored;
+}
+/** Cursor documents default ignore of .env* (see cursor.com/docs/reference/ignore-file). */
+const CURSOR_DEFAULT_ENV_PATTERNS = [".env", ".env.*", "**/.env", "**/.env.*"];
+export function createIgnoreIndex(options) {
+    const gitignorePatterns = options.gitignorePatterns;
+    const cursorignorePatterns = options.cursorignorePatterns;
+    return {
+        gitignorePatterns,
+        cursorignorePatterns,
+        matchesGitignore(relativePath) {
+            return pathMatchesAny(relativePath, gitignorePatterns);
+        },
+        matchesCursorignore(relativePath) {
+            return pathMatchesAny(relativePath, cursorignorePatterns);
+        },
+        isExcludedForCursor(relativePath) {
+            if (pathMatchesAny(relativePath, cursorignorePatterns)) {
+                return true;
+            }
+            if (pathMatchesAny(relativePath, gitignorePatterns)) {
+                return true;
+            }
+            // Documented default ignore list includes .env*
+            return pathMatchesAny(relativePath, CURSOR_DEFAULT_ENV_PATTERNS);
+        },
+    };
+}

package/dist/core/rules/instructions/duplicate-content.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from "../types.js";
+export declare const duplicateContentRule: RuleDefinition;

package/dist/core/rules/instructions/duplicate-content.js

@@ -0,0 +1,99 @@
+import { THRESHOLDS } from "../thresholds.js";
+const COMPARE_KINDS = new Set([
+    "cursor-rule-mdc",
+    "cursor-legacy-cursorrules",
+    "agents-md",
+    "agents-override-md",
+    "claude-md",
+    "claude-local-md",
+    "claude-rule-md",
+]);
+function normalizeContent(text) {
+    return text
+        .replace(/\r\n/g, "\n")
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim()
+        .toLowerCase();
+}
+/** Strip simple MDC/YAML frontmatter for comparison. */
+function stripFrontmatter(text) {
+    if (!text.startsWith("---")) {
+        return text;
+    }
+    const end = text.indexOf("\n---", 3);
+    if (end === -1) {
+        return text;
+    }
+    return text.slice(end + 4);
+}
+export const duplicateContentRule = {
+    id: "instructions/duplicate-content",
+    title: "Duplicate agent instructions",
+    description: "Detects exact normalized duplicate instruction content across agent config files.",
+    category: "instructions",
+    severity: "info",
+    fixability: "review",
+    rationale: "Duplicated instructions across agents can drift over time; sharing a canonical source reduces maintenance.",
+    recommendation: "Prefer one canonical instruction file where tooling allows (for example CLAUDE.md importing AGENTS.md), accepting intentional duplication for cross-agent compatibility when needed.",
+    async check(context) {
+        const files = [];
+        const seenPaths = new Set();
+        for (const agent of context.agents) {
+            for (const file of agent.configFiles) {
+                if (!COMPARE_KINDS.has(file.kind) || file.empty || !file.readable) {
+                    continue;
+                }
+                if (seenPaths.has(file.relativePath)) {
+                    const existing = files.find((f) => f.path === file.relativePath);
+                    existing?.agents.push(agent.id);
+                    continue;
+                }
+                seenPaths.add(file.relativePath);
+                const cached = await context.textCache.read(file.relativePath);
+                if (!cached.text || cached.binary) {
+                    continue;
+                }
+                const normalized = normalizeContent(stripFrontmatter(cached.text));
+                if (normalized.length < THRESHOLDS.duplicateMinChars) {
+                    continue;
+                }
+                files.push({ path: file.relativePath, normalized, agents: [agent.id] });
+            }
+        }
+        const findings = [];
+        const reported = new Set();
+        for (let i = 0; i < files.length; i += 1) {
+            for (let j = i + 1; j < files.length; j += 1) {
+                const a = files[i];
+                const b = files[j];
+                if (!a || !b)
+                    continue;
+                if (a.normalized !== b.normalized) {
+                    continue;
+                }
+                const pairKey = [a.path, b.path].sort().join("|");
+                if (reported.has(pairKey)) {
+                    continue;
+                }
+                reported.add(pairKey);
+                const affected = context.agents
+                    .filter((agent) => agent.configPaths.includes(a.path) || agent.configPaths.includes(b.path))
+                    .map((agent) => agent.id);
+                findings.push({
+                    ruleId: "instructions/duplicate-content",
+                    category: "instructions",
+                    severity: "info",
+                    title: "Duplicate agent instructions",
+                    message: `${a.path} and ${b.path} contain identical normalized project instructions`,
+                    whyItMatters: "Duplication can be intentional for cross-agent compatibility, but identical copies often drift. Prefer a single canonical source when supported.",
+                    recommendation: "Keep shared guidance in one file and reference/import it from agent-specific files where the tool supports that.",
+                    affectedAgents: affected,
+                    evidence: { path: a.path, detail: `duplicate_of=${b.path}` },
+                    fixability: "review",
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/core/rules/instructions/empty-instructions.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from "../types.js";
+export declare const emptyInstructionsRule: RuleDefinition;

package/dist/core/rules/instructions/empty-instructions.js

@@ -0,0 +1,53 @@
+const EMPTYABLE_KINDS = new Set([
+    "cursor-rule-mdc",
+    "cursor-legacy-cursorrules",
+    "agents-md",
+    "agents-override-md",
+    "claude-md",
+    "claude-local-md",
+    "claude-rule-md",
+]);
+export const emptyInstructionsRule = {
+    id: "instructions/empty-instructions",
+    title: "Empty agent instruction file",
+    description: "Flags empty project instruction files that agents will skip or ignore.",
+    category: "instructions",
+    severity: "warning",
+    fixability: "review",
+    rationale: "Empty instruction files suggest incomplete setup and waste discovery attention.",
+    recommendation: "Add meaningful project guidance or remove the empty file.",
+    async check(context) {
+        const findings = [];
+        const seen = new Set();
+        for (const agent of context.agents) {
+            for (const file of agent.configFiles) {
+                if (!EMPTYABLE_KINDS.has(file.kind)) {
+                    continue;
+                }
+                if (!file.empty || !file.readable) {
+                    continue;
+                }
+                if (seen.has(file.relativePath)) {
+                    continue;
+                }
+                seen.add(file.relativePath);
+                const affected = context.agents
+                    .filter((a) => a.configPaths.includes(file.relativePath))
+                    .map((a) => a.id);
+                findings.push({
+                    ruleId: "instructions/empty-instructions",
+                    category: "instructions",
+                    severity: "warning",
+                    title: "Empty agent instruction file",
+                    message: `${file.relativePath} exists but is empty`,
+                    whyItMatters: "Empty instruction files do not guide agents (Codex skips empty AGENTS.md) and can indicate unfinished configuration.",
+                    recommendation: "Populate the file with concise project guidance or delete it.",
+                    affectedAgents: affected.length > 0 ? affected : [agent.id],
+                    evidence: { path: file.relativePath },
+                    fixability: "review",
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/core/rules/instructions/missing-path-reference.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from "../types.js";
+export declare const missingPathReferenceRule: RuleDefinition;

package/dist/core/rules/instructions/missing-path-reference.js

@@ -0,0 +1,131 @@
+import path from "node:path";
+import { pathExistsInsideRoot } from "../../../agents/inspect.js";
+import { isPathInsideRoot } from "../../../utils/path.js";
+const INSTRUCTION_KINDS = new Set([
+    "cursor-rule-mdc",
+    "cursor-legacy-cursorrules",
+    "agents-md",
+    "agents-override-md",
+    "claude-md",
+    "claude-local-md",
+    "claude-rule-md",
+]);
+/**
+ * Conservative local path extraction:
+ * - Markdown links: [text](relative/path.ext)
+ * - Backticked paths with separators or extensions
+ */
+function extractPathCandidates(text) {
+    const found = new Set();
+    for (const match of text.matchAll(/\[[^\]]*]\(([^)]+)\)/g)) {
+        const target = (match[1] ?? "").trim();
+        if (isConservativeLocalPath(target)) {
+            found.add(stripAnchor(target));
+        }
+    }
+    for (const match of text.matchAll(/`([^`]+)`/g)) {
+        const target = (match[1] ?? "").trim();
+        if (isConservativeLocalPath(target)) {
+            found.add(stripAnchor(target));
+        }
+    }
+    return [...found];
+}
+function stripAnchor(value) {
+    return value.split("#")[0] ?? value;
+}
+function isConservativeLocalPath(value) {
+    if (!value || value.length > 200)
+        return false;
+    if (/^(https?:|mailto:|file:)/i.test(value))
+        return false;
+    if (value.startsWith("#"))
+        return false;
+    if (value.includes("://"))
+        return false;
+    if (value.includes("\n") || value.includes(" "))
+        return false;
+    // Must look like a path: has / or a file extension
+    if (!value.includes("/") && !/\.[a-z0-9]{1,8}$/i.test(value))
+        return false;
+    // Reject shell-looking fragments
+    if (/[;&|$]/.test(value))
+        return false;
+    // Reject traversal escape attempts — still check but flag separately
+    return true;
+}
+export const missingPathReferenceRule = {
+    id: "instructions/missing-path-reference",
+    title: "Instruction references a missing path",
+    description: "Detects markdown/backtick local path references in instruction files that do not exist.",
+    category: "instructions",
+    severity: "warning",
+    fixability: "manual",
+    rationale: "Broken path references mislead agents and waste tool-call attempts.",
+    recommendation: "Update or remove the stale path reference.",
+    async check(context) {
+        const findings = [];
+        const seen = new Set();
+        for (const agent of context.agents) {
+            for (const file of agent.configFiles) {
+                if (!INSTRUCTION_KINDS.has(file.kind) || file.empty || !file.readable) {
+                    continue;
+                }
+                if (seen.has(file.relativePath)) {
+                    continue;
+                }
+                seen.add(file.relativePath);
+                const cached = await context.textCache.read(file.relativePath);
+                if (!cached.text || cached.binary) {
+                    continue;
+                }
+                const candidates = extractPathCandidates(cached.text);
+                for (const candidate of candidates) {
+                    // Resolve relative to instruction file directory, stay inside root
+                    const baseDir = path.posix.dirname(file.relativePath);
+                    const resolvedRelative = path.posix.normalize(baseDir === "." ? candidate : path.posix.join(baseDir, candidate));
+                    if (resolvedRelative.startsWith("../") || resolvedRelative === "..") {
+                        findings.push({
+                            ruleId: "instructions/missing-path-reference",
+                            category: "instructions",
+                            severity: "warning",
+                            title: "Instruction references a missing path",
+                            message: `${file.relativePath} references \`${candidate}\`, which escapes the repository root`,
+                            whyItMatters: "Path references outside the repository cannot be validated and may confuse agents.",
+                            recommendation: "Use repository-relative paths only.",
+                            affectedAgents: context.agents
+                                .filter((a) => a.configPaths.includes(file.relativePath))
+                                .map((a) => a.id),
+                            evidence: { path: file.relativePath, detail: `ref=${candidate}` },
+                            fixability: "manual",
+                        });
+                        continue;
+                    }
+                    const absolute = path.resolve(context.root, resolvedRelative);
+                    if (!isPathInsideRoot(context.root, absolute)) {
+                        continue;
+                    }
+                    const exists = await pathExistsInsideRoot(context.root, resolvedRelative);
+                    if (exists) {
+                        continue;
+                    }
+                    findings.push({
+                        ruleId: "instructions/missing-path-reference",
+                        category: "instructions",
+                        severity: "warning",
+                        title: "Instruction references a missing path",
+                        message: `${file.relativePath} references \`${candidate}\`, but that path does not exist`,
+                        whyItMatters: "Agents may follow documented paths that no longer exist, causing failed reads and wasted context.",
+                        recommendation: "Fix the path or remove the stale reference.",
+                        affectedAgents: context.agents
+                            .filter((a) => a.configPaths.includes(file.relativePath))
+                            .map((a) => a.id),
+                        evidence: { path: file.relativePath, detail: `missing=${resolvedRelative}` },
+                        fixability: "manual",
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};

package/dist/core/rules/mcp/mcp-rules.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDefinition } from "../types.js";
+export declare const malformedMcpRule: RuleDefinition;
+export declare const duplicateMcpServerRule: RuleDefinition;

package/dist/core/rules/mcp/mcp-rules.js

@@ -0,0 +1,83 @@
+export const malformedMcpRule = {
+    id: "mcp/malformed-config",
+    title: "Malformed MCP configuration",
+    description: "Flags MCP config files that exist but cannot be safely parsed.",
+    category: "mcp",
+    severity: "warning",
+    fixability: "manual",
+    rationale: "Broken MCP configuration prevents tools from loading and may hide security settings.",
+    recommendation: "Fix JSON/TOML syntax and validate against the agent’s MCP schema.",
+    async check(context) {
+        const findings = [];
+        const seen = new Set();
+        for (const server of context.mcpServers) {
+            if (!server.parseError) {
+                continue;
+            }
+            if (seen.has(server.sourcePath)) {
+                continue;
+            }
+            seen.add(server.sourcePath);
+            findings.push({
+                ruleId: "mcp/malformed-config",
+                category: "mcp",
+                severity: "warning",
+                title: "Malformed MCP configuration",
+                message: `${server.sourcePath} could not be parsed: ${server.parseError}`,
+                whyItMatters: "Agents will not load malformed MCP configuration, leaving expected tools unavailable.",
+                recommendation: "Correct the configuration syntax. Do not commit secrets into MCP env values.",
+                affectedAgents: [server.sourceAgent],
+                evidence: { path: server.sourcePath, detail: server.parseError },
+                fixability: "manual",
+            });
+        }
+        return findings;
+    },
+};
+export const duplicateMcpServerRule = {
+    id: "mcp/duplicate-server",
+    title: "Duplicate MCP server definition",
+    description: "Detects the same MCP server name defined more than once across project configs.",
+    category: "mcp",
+    severity: "info",
+    fixability: "review",
+    rationale: "Duplicate server names can make it unclear which configuration is active.",
+    recommendation: "Keep a single definition per server name per agent scope.",
+    async check(context) {
+        const findings = [];
+        const byKey = new Map();
+        for (const server of context.mcpServers) {
+            if (server.parseError || server.name.startsWith("(")) {
+                continue;
+            }
+            const key = `${server.sourceAgent}::${server.name}`;
+            const list = byKey.get(key) ?? [];
+            list.push(server);
+            byKey.set(key, list);
+        }
+        for (const [key, list] of byKey) {
+            if (list.length < 2) {
+                continue;
+            }
+            const first = list[0];
+            if (!first)
+                continue;
+            findings.push({
+                ruleId: "mcp/duplicate-server",
+                category: "mcp",
+                severity: "info",
+                title: "Duplicate MCP server definition",
+                message: `MCP server "${first.name}" is defined ${list.length} times for ${first.sourceAgent}`,
+                whyItMatters: "Duplicate names make it harder to reason about which MCP server configuration an agent will use.",
+                recommendation: "Deduplicate server entries so each name appears once per agent config scope.",
+                affectedAgents: [first.sourceAgent],
+                evidence: {
+                    path: first.sourcePath,
+                    detail: `key=${key}; paths=${list.map((s) => s.sourcePath).join(",")}`,
+                },
+                fixability: "review",
+            });
+        }
+        return findings;
+    },
+};

package/dist/core/rules/registry.d.ts

@@ -0,0 +1,6 @@
+import type { RuleDefinition } from "./types.js";
+/**
+ * Central rule registry. Add new rules by implementing RuleDefinition and appending here.
+ */
+export declare const ruleRegistry: readonly RuleDefinition[];
+export declare function getRuleById(id: string): RuleDefinition | undefined;

package/dist/core/rules/registry.js

@@ -0,0 +1,31 @@
+import { claudeBypassPermissionsRule } from "./security/claude-bypass-permissions.js";
+import { envFileExposureRule } from "./security/env-file-exposure.js";
+import { mcpBroadFilesystemRule } from "./security/mcp-broad-filesystem.js";
+import { privateKeyFileRule } from "./security/private-key-file.js";
+import { generatedDirectoryRule } from "./context/generated-directory.js";
+import { largeInstructionFileRule } from "./context/large-instruction-file.js";
+import { largeLogFileRule } from "./context/large-log-file.js";
+import { duplicateContentRule } from "./instructions/duplicate-content.js";
+import { emptyInstructionsRule } from "./instructions/empty-instructions.js";
+import { missingPathReferenceRule } from "./instructions/missing-path-reference.js";
+import { duplicateMcpServerRule, malformedMcpRule } from "./mcp/mcp-rules.js";
+/**
+ * Central rule registry. Add new rules by implementing RuleDefinition and appending here.
+ */
+export const ruleRegistry = [
+    envFileExposureRule,
+    privateKeyFileRule,
+    claudeBypassPermissionsRule,
+    mcpBroadFilesystemRule,
+    largeInstructionFileRule,
+    largeLogFileRule,
+    generatedDirectoryRule,
+    emptyInstructionsRule,
+    duplicateContentRule,
+    missingPathReferenceRule,
+    malformedMcpRule,
+    duplicateMcpServerRule,
+];
+export function getRuleById(id) {
+    return ruleRegistry.find((rule) => rule.id === id);
+}

package/dist/core/rules/run-rules.d.ts

@@ -0,0 +1,16 @@
+import type { Finding } from "../../types/index.js";
+import { summarizeFindings } from "./dedupe.js";
+import type { RuleContext, RuleDefinition } from "./types.js";
+export interface RunRulesOptions {
+    context: RuleContext;
+    rules?: readonly RuleDefinition[];
+    includeRules?: string[];
+    excludeRules?: string[];
+}
+export interface RunRulesResult {
+    findings: Finding[];
+    summary: ReturnType<typeof summarizeFindings>;
+    elapsedMs: number;
+    ruleErrors: string[];
+}
+export declare function runRules(options: RunRulesOptions): Promise<RunRulesResult>;

package/dist/core/rules/run-rules.js

@@ -0,0 +1,36 @@
+import { dedupeFindings, summarizeFindings } from "./dedupe.js";
+import { ruleRegistry } from "./registry.js";
+export async function runRules(options) {
+    const started = performance.now();
+    const rules = (options.rules ?? ruleRegistry).filter((rule) => {
+        if (options.includeRules && options.includeRules.length > 0) {
+            return options.includeRules.includes(rule.id);
+        }
+        if (options.excludeRules && options.excludeRules.length > 0) {
+            return !options.excludeRules.includes(rule.id);
+        }
+        return true;
+    });
+    const drafts = [];
+    const ruleErrors = [];
+    for (const rule of rules) {
+        try {
+            const results = await rule.check(options.context);
+            for (const draft of results) {
+                // Ensure ruleId matches registry entry
+                drafts.push({ ...draft, ruleId: rule.id });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ruleErrors.push(`Rule ${rule.id} failed: ${message}`);
+        }
+    }
+    const findings = dedupeFindings(drafts);
+    return {
+        findings,
+        summary: summarizeFindings(findings),
+        elapsedMs: Math.round(performance.now() - started),
+        ruleErrors,
+    };
+}

package/dist/core/rules/security/claude-bypass-permissions.d.ts

@@ -0,0 +1,7 @@
+import type { RuleDefinition } from "../types.js";
+/**
+ * Detects Claude Code `defaultMode: bypassPermissions` in project settings.
+ * Official docs warn this skips permission prompts and should only be used in
+ * isolated environments: https://code.claude.com/docs/en/permissions
+ */
+export declare const claudeBypassPermissionsRule: RuleDefinition;

package/dist/core/rules/security/claude-bypass-permissions.js

@@ -0,0 +1,52 @@
+/**
+ * Detects Claude Code `defaultMode: bypassPermissions` in project settings.
+ * Official docs warn this skips permission prompts and should only be used in
+ * isolated environments: https://code.claude.com/docs/en/permissions
+ */
+export const claudeBypassPermissionsRule = {
+    id: "security/claude-bypass-permissions",
+    title: "Claude Code bypassPermissions mode enabled",
+    description: "Flags project Claude Code settings that set defaultMode to bypassPermissions.",
+    category: "security",
+    severity: "warning",
+    affectedAgents: ["claude-code"],
+    fixability: "review",
+    rationale: "bypassPermissions skips interactive approval for many tool calls, increasing blast radius if the agent is prompted maliciously.",
+    recommendation: "Use default or acceptEdits mode for normal development. Reserve bypassPermissions for isolated containers/VMs only.",
+    async check(context) {
+        const claude = context.agents.find((a) => a.id === "claude-code");
+        if (!claude) {
+            return [];
+        }
+        const findings = [];
+        for (const file of claude.configFiles) {
+            if (file.kind !== "claude-settings" && file.kind !== "claude-settings-local") {
+                continue;
+            }
+            if (file.parseError || !file.readable || file.empty) {
+                continue;
+            }
+            const cached = await context.textCache.read(file.relativePath);
+            if (!cached.text) {
+                continue;
+            }
+            // Match JSON string values only — do not execute settings.
+            if (/"defaultMode"\s*:\s*"bypassPermissions"/.test(cached.text) ||
+                /"defaultMode"\s*:\s*"bypasspermissions"/i.test(cached.text)) {
+                findings.push({
+                    ruleId: "security/claude-bypass-permissions",
+                    category: "security",
+                    severity: "warning",
+                    title: "Claude Code bypassPermissions mode enabled",
+                    message: `${file.relativePath} sets defaultMode to bypassPermissions`,
+                    whyItMatters: "Official Claude Code docs state bypassPermissions skips permission prompts (with limited circuit breakers). This widens what an agent session can do without confirmation.",
+                    recommendation: "Change defaultMode to default (or acceptEdits if appropriate) unless this project runs only in a locked-down isolated environment.",
+                    affectedAgents: ["claude-code"],
+                    evidence: { path: file.relativePath },
+                    fixability: "review",
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/core/rules/security/env-file-exposure.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from "../types.js";
+export declare const envFileExposureRule: RuleDefinition;