@danielblomma/cortex-mcp 2.4.0 → 2.4.1

package/scaffold/mcp/dist/core/validators/engine.js

@@ -0,0 +1,120 @@
+const registry = new Map();
+const genericRegistry = new Map();
+export function registerValidator(def) {
+    registry.set(def.policyId, def);
+}
+export function getValidator(policyId) {
+    return registry.get(policyId);
+}
+export function getRegisteredPolicyIds() {
+    return [...registry.keys()];
+}
+export function registerGenericEvaluator(def) {
+    genericRegistry.set(def.type, def);
+}
+export function getGenericEvaluator(type) {
+    return genericRegistry.get(type);
+}
+export function getRegisteredEvaluatorTypes() {
+    return [...genericRegistry.keys()];
+}
+function resolvePolicySeverity(policy, fallback) {
+    if (!policy.severity)
+        return fallback;
+    return policy.severity === "block" ? "error" : policy.severity;
+}
+/**
+ * Run validators for every enforced policy. Dispatch order per policy:
+ *   1. If the policy has a `type`, look it up in the generic evaluator
+ *      registry (cortex-web custom rules use this path).
+ *   2. Otherwise, look up a name-based validator by policy id
+ *      (predefined rules shipped with the plugin use this path).
+ *   3. If neither path yields an implementation, emit a warning so the
+ *      gap is visible instead of silent.
+ *
+ * Accepts either `Set<string>` (legacy id-only callers) or an array of
+ * `EnforcedPolicy` objects carrying `type` + `config` from the
+ * cortex-web policy sync. Set inputs are normalized to entries with
+ * null type/config, so they always route to the name-based registry.
+ */
+export async function runValidators(enforced, ctx, validatorConfigs) {
+    const policies = enforced instanceof Set
+        ? [...enforced].map((id) => ({ id }))
+        : enforced;
+    const results = [];
+    for (const policy of policies) {
+        if (policy.type) {
+            const evaluator = genericRegistry.get(policy.type);
+            if (!evaluator) {
+                results.push({
+                    policy_id: policy.id,
+                    pass: false,
+                    severity: "warning",
+                    message: `No evaluator registered for type "${policy.type}"`,
+                    detail: "This policy declares a generic evaluator type that is not " +
+                        "implemented in this version of the enterprise plugin. " +
+                        "Upgrade the plugin or change the rule type.",
+                });
+                continue;
+            }
+            try {
+                const result = await evaluator.check(ctx, policy.config ?? {});
+                results.push({
+                    policy_id: policy.id,
+                    pass: result.pass,
+                    severity: resolvePolicySeverity(policy, result.severity),
+                    message: result.message,
+                    detail: result.detail,
+                });
+            }
+            catch (err) {
+                results.push({
+                    policy_id: policy.id,
+                    pass: false,
+                    severity: "error",
+                    message: `Evaluator error: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+            continue;
+        }
+        const def = registry.get(policy.id);
+        if (!def) {
+            results.push({
+                policy_id: policy.id,
+                pass: false,
+                severity: "warning",
+                message: "No validator implementation registered for this policy",
+                detail: "This policy is enforced but the server-side check is missing. " +
+                    "Either install an enterprise plugin that provides it, or disable " +
+                    "enforcement in the policy dashboard.",
+            });
+            continue;
+        }
+        const options = validatorConfigs[policy.id] ?? {};
+        try {
+            const result = await def.check(ctx, options);
+            results.push({
+                policy_id: policy.id,
+                pass: result.pass,
+                severity: resolvePolicySeverity(policy, result.severity),
+                message: result.message,
+                detail: result.detail,
+            });
+        }
+        catch (err) {
+            results.push({
+                policy_id: policy.id,
+                pass: false,
+                severity: "error",
+                message: `Validator error: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    const summary = {
+        total: results.length,
+        passed: results.filter((r) => r.pass).length,
+        failed: results.filter((r) => !r.pass && r.severity === "error").length,
+        warnings: results.filter((r) => !r.pass && r.severity === "warning").length,
+    };
+    return { results, summary };
+}

package/scaffold/mcp/dist/core/validators/evaluators/code_comments.js

@@ -0,0 +1,236 @@
+import { statSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { registerGenericEvaluator, } from "../engine.js";
+const LANGUAGES = [
+    {
+        name: "TypeScript/JavaScript",
+        extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+        functionPatterns: [
+            /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*(\w+)\s*(?:<[^>]*>)?\s*\(/,
+            /^\s*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*(?::\s*[\w<>,\s[\]|&]+)?\s*=\s*(?:async\s*)?(?:<[^>]*>)?\s*\([^)]*\)\s*(?::\s*[\w<>,\s[\]|&]+\s*)?=>/,
+            /^\s*(?:public|private|protected)?\s*(?:static\s+)?(?:readonly\s+)?(?:async\s+)?(?:\*\s*)?(\w+)\s*(?:<[^>]*>)?\s*\([^)]*\)\s*(?::\s*[\w<>,\s[\]|&]+\s*)?\{/,
+        ],
+        lineCommentPrefix: "//",
+        blockCommentStart: "/*",
+        blockCommentEnd: "*/",
+        endStyle: "braces",
+    },
+    {
+        name: "Python",
+        extensions: [".py"],
+        functionPatterns: [
+            /^(\s*)(?:async\s+)?def\s+(\w+)\s*\(/,
+        ],
+        lineCommentPrefix: "#",
+        blockCommentStart: "",
+        blockCommentEnd: "",
+        endStyle: "indent",
+        allowsDocstring: true,
+    },
+    {
+        name: "Go",
+        extensions: [".go"],
+        functionPatterns: [
+            /^func\s+(?:\([^)]+\)\s+)?(\w+)\s*\(/,
+        ],
+        lineCommentPrefix: "//",
+        blockCommentStart: "/*",
+        blockCommentEnd: "*/",
+        endStyle: "braces",
+    },
+    {
+        name: "Rust",
+        extensions: [".rs"],
+        functionPatterns: [
+            /^\s*(?:pub(?:\s*\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(?:extern\s+(?:"[^"]*"\s+)?)?fn\s+(\w+)/,
+        ],
+        lineCommentPrefix: "//",
+        blockCommentStart: "/*",
+        blockCommentEnd: "*/",
+        endStyle: "braces",
+    },
+    {
+        name: "C#",
+        extensions: [".cs"],
+        functionPatterns: [
+            // Require at least one access/modifier keyword so we don't match
+            // arbitrary `name(args)` calls. Return type is optional to also
+            // match constructors.
+            /^\s*(?:(?:public|private|protected|internal|static|async|override|virtual|sealed|abstract|new|partial)\s+)+(?:[\w<>\[\],?\s]+?\s+)?(\w+)\s*\([^)]*\)\s*(?:\{|where|:|=>|$)/,
+        ],
+        lineCommentPrefix: "//",
+        blockCommentStart: "/*",
+        blockCommentEnd: "*/",
+        endStyle: "braces",
+    },
+    {
+        name: "Java",
+        extensions: [".java"],
+        functionPatterns: [
+            /^\s*(?:(?:public|private|protected|static|final|abstract|synchronized|native)\s+)+(?:[\w<>\[\],?\s]+?\s+)?(\w+)\s*\([^)]*\)\s*(?:\{|throws|$)/,
+        ],
+        lineCommentPrefix: "//",
+        blockCommentStart: "/*",
+        blockCommentEnd: "*/",
+        endStyle: "braces",
+    },
+];
+function pickLanguage(file) {
+    const lower = file.toLowerCase();
+    for (const lang of LANGUAGES) {
+        if (lang.extensions.some((ext) => lower.endsWith(ext))) {
+            return lang;
+        }
+    }
+    return null;
+}
+// Scan for a preceding comment within `lookback` non-blank lines above
+// `startLine` (exclusive). Returns true if a comment is found.
+function hasPrecedingComment(lines, startLine, lang, lookback) {
+    let checked = 0;
+    for (let i = startLine - 1; i >= 0 && checked < lookback; i -= 1) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "")
+            continue;
+        checked += 1;
+        if (trimmed.startsWith(lang.lineCommentPrefix))
+            return true;
+        if (lang.blockCommentStart) {
+            if (trimmed.endsWith(lang.blockCommentEnd))
+                return true;
+            if (trimmed.startsWith(lang.blockCommentStart))
+                return true;
+        }
+        // First non-blank non-comment line above → no leading comment.
+        return false;
+    }
+    return false;
+}
+function isDocstringLine(line) {
+    const t = line.trim();
+    return t.startsWith('"""') || t.startsWith("'''") || t.startsWith('"') || t.startsWith("'");
+}
+// Walk forward from `startLine` (the function declaration line) and return
+// the (exclusive) end-of-function line. Handles both brace and indent
+// styles. Naive — comments/strings may contain braces and skew the
+// counter; acceptable tradeoff without per-language AST parsing.
+function findFunctionEnd(lines, startLine, lang, indentMatch) {
+    if (lang.endStyle === "indent") {
+        const baseIndent = (indentMatch ?? "").length;
+        for (let i = startLine + 1; i < lines.length; i += 1) {
+            const line = lines[i];
+            if (line.trim() === "")
+                continue;
+            const indent = line.length - line.trimStart().length;
+            if (indent <= baseIndent)
+                return i;
+        }
+        return lines.length;
+    }
+    // Braces
+    let depth = 0;
+    let seenOpen = false;
+    for (let i = startLine; i < lines.length; i += 1) {
+        const line = lines[i];
+        for (let j = 0; j < line.length; j += 1) {
+            const c = line[j];
+            if (c === "{") {
+                depth += 1;
+                seenOpen = true;
+            }
+            else if (c === "}") {
+                depth -= 1;
+                if (seenOpen && depth === 0)
+                    return i + 1;
+            }
+        }
+    }
+    return lines.length;
+}
+function scanFile(content, file, lang, minLines) {
+    const lines = content.split("\n");
+    const hits = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        for (const pattern of lang.functionPatterns) {
+            const m = line.match(pattern);
+            if (!m)
+                continue;
+            // For Python, capture group 1 is indent, 2 is name; for others, 1 is name.
+            const name = lang.endStyle === "indent" ? m[2] ?? "<anonymous>" : m[1] ?? "<anonymous>";
+            const indent = lang.endStyle === "indent" ? m[1] ?? "" : undefined;
+            const endLine = findFunctionEnd(lines, i, lang, indent);
+            const funcLineCount = endLine - i;
+            if (funcLineCount < minLines)
+                break;
+            if (hasPrecedingComment(lines, i, lang, 3))
+                break;
+            if (lang.allowsDocstring && lines[i + 1] && isDocstringLine(lines[i + 1]))
+                break;
+            hits.push({ file, line: i + 1, name, lineCount: funcLineCount });
+            break; // one match per line is enough
+        }
+    }
+    return hits;
+}
+registerGenericEvaluator({
+    type: "code_comments",
+    async check(ctx, config) {
+        const files = ctx.changedFiles ?? [];
+        if (files.length === 0) {
+            return { pass: true, severity: "info", message: "No changed files to scan" };
+        }
+        const minLines = typeof config.min_lines === "number" && config.min_lines > 0 ? config.min_lines : 15;
+        const severity = config.severity === "error" || config.severity === "warning" || config.severity === "info"
+            ? config.severity
+            : "warning";
+        const allowlist = Array.isArray(config.allowlist_paths)
+            ? config.allowlist_paths.filter((p) => typeof p === "string")
+            : ["tests/", "test/", "__tests__/", "fixtures/", "docs/"];
+        const maxBytes = typeof config.max_scan_bytes === "number" ? config.max_scan_bytes : 2_000_000;
+        // Optional language filter (by name, case-insensitive). Absent = all.
+        const wantedLanguages = Array.isArray(config.languages)
+            ? new Set(config.languages.filter((l) => typeof l === "string").map((l) => l.toLowerCase()))
+            : null;
+        const allHits = [];
+        let scanned = 0;
+        for (const file of files) {
+            if (allowlist.some((p) => file.includes(p)))
+                continue;
+            const lang = pickLanguage(file);
+            if (!lang)
+                continue;
+            if (wantedLanguages && !wantedLanguages.has(lang.name.toLowerCase()))
+                continue;
+            const abs = join(ctx.projectRoot, file);
+            try {
+                const stat = statSync(abs);
+                if (stat.size > maxBytes)
+                    continue;
+                const content = readFileSync(abs, "utf8");
+                scanned += 1;
+                allHits.push(...scanFile(content, file, lang, minLines));
+            }
+            catch {
+                // unreadable — skip
+            }
+        }
+        if (allHits.length === 0) {
+            return {
+                pass: true,
+                severity: "info",
+                message: `No undocumented functions (${minLines}+ lines) in ${scanned} changed file${scanned === 1 ? "" : "s"}`,
+            };
+        }
+        const detail = allHits
+            .slice(0, 30)
+            .map((h) => `${h.file}:${h.line} — ${h.name} (${h.lineCount} lines)`)
+            .join("\n") + (allHits.length > 30 ? `\n... and ${allHits.length - 30} more` : "");
+        return {
+            pass: false,
+            severity,
+            message: `${allHits.length} function${allHits.length === 1 ? "" : "s"} of ${minLines}+ lines without preceding comment`,
+            detail,
+        };
+    },
+});

package/scaffold/mcp/dist/core/validators/evaluators/regex.js

@@ -0,0 +1,116 @@
+import { statSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { registerGenericEvaluator, } from "../engine.js";
+const BINARY_SNIFF_BYTES = 512;
+const DEFAULT_MAX_BYTES = 2_000_000;
+const SEVERITIES = new Set(["error", "warning", "info"]);
+function parseConfig(raw) {
+    const pattern = raw.pattern;
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        return { error: "config.pattern must be a non-empty string" };
+    }
+    try {
+        new RegExp(pattern, typeof raw.flags === "string" ? raw.flags : undefined);
+    }
+    catch (err) {
+        return { error: `config.pattern is not a valid regex: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const severity = raw.severity;
+    if (severity !== undefined && (typeof severity !== "string" || !SEVERITIES.has(severity))) {
+        return { error: 'config.severity must be one of "error", "warning", "info"' };
+    }
+    if (raw.file_pattern !== undefined && typeof raw.file_pattern !== "string") {
+        return { error: "config.file_pattern must be a string" };
+    }
+    if (raw.file_pattern) {
+        try {
+            new RegExp(raw.file_pattern);
+        }
+        catch (err) {
+            return { error: `config.file_pattern is not a valid regex: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    return {
+        pattern,
+        flags: typeof raw.flags === "string" ? raw.flags : undefined,
+        file_pattern: typeof raw.file_pattern === "string" ? raw.file_pattern : undefined,
+        severity: severity,
+        message: typeof raw.message === "string" ? raw.message : undefined,
+        max_matches_per_file: typeof raw.max_matches_per_file === "number" ? raw.max_matches_per_file : undefined,
+        max_scan_bytes: typeof raw.max_scan_bytes === "number" ? raw.max_scan_bytes : undefined,
+        allowlist_paths: Array.isArray(raw.allowlist_paths)
+            ? raw.allowlist_paths.filter((p) => typeof p === "string")
+            : undefined,
+    };
+}
+registerGenericEvaluator({
+    type: "regex",
+    async check(ctx, rawConfig) {
+        const parsed = parseConfig(rawConfig);
+        if ("error" in parsed) {
+            return { pass: false, severity: "error", message: `Invalid regex config: ${parsed.error}` };
+        }
+        const files = ctx.changedFiles ?? [];
+        if (files.length === 0) {
+            return { pass: true, severity: "info", message: "No changed files to scan" };
+        }
+        const severity = parsed.severity ?? "warning";
+        const allowlist = parsed.allowlist_paths ?? ["tests/", "test/", "__tests__/", "fixtures/", "docs/"];
+        const maxBytes = parsed.max_scan_bytes ?? DEFAULT_MAX_BYTES;
+        const maxMatches = parsed.max_matches_per_file ?? 20;
+        // A regex used purely to filter file paths should be anchored by the
+        // caller if needed; we compile as-is to give them full control.
+        const fileRe = parsed.file_pattern ? new RegExp(parsed.file_pattern) : null;
+        const contentRe = new RegExp(parsed.pattern, parsed.flags);
+        const hits = [];
+        let scanned = 0;
+        for (const file of files) {
+            if (allowlist.some((p) => file.includes(p)))
+                continue;
+            if (fileRe && !fileRe.test(file))
+                continue;
+            const abs = join(ctx.projectRoot, file);
+            try {
+                const stat = statSync(abs);
+                if (stat.size > maxBytes)
+                    continue;
+                const buf = readFileSync(abs);
+                const sniff = buf.subarray(0, Math.min(buf.length, BINARY_SNIFF_BYTES));
+                if (sniff.includes(0))
+                    continue;
+                const content = buf.toString("utf8");
+                scanned += 1;
+                const lines = content.split("\n");
+                let fileMatches = 0;
+                for (let i = 0; i < lines.length; i += 1) {
+                    // Compile a per-line test with the `g` flag stripped so we don't
+                    // hop across repeated state; callers supply single-line patterns.
+                    const lineRe = new RegExp(contentRe.source, (contentRe.flags || "").replace(/g/g, ""));
+                    if (lineRe.test(lines[i])) {
+                        hits.push(`${file}:${i + 1}`);
+                        fileMatches += 1;
+                        if (fileMatches >= maxMatches)
+                            break;
+                    }
+                }
+            }
+            catch {
+                // Unreadable file — skip
+            }
+        }
+        if (hits.length === 0) {
+            return {
+                pass: true,
+                severity: "info",
+                message: `No regex matches in ${scanned} changed file${scanned === 1 ? "" : "s"}`,
+            };
+        }
+        const messageStem = parsed.message ?? "Pattern match";
+        return {
+            pass: false,
+            severity,
+            message: `${messageStem}: ${hits.length} match${hits.length === 1 ? "" : "es"} in ${scanned} file${scanned === 1 ? "" : "s"}`,
+            detail: hits.slice(0, 30).join("\n") + (hits.length > 30 ? `\n... and ${hits.length - 30} more` : ""),
+        };
+    },
+});

package/scaffold/mcp/dist/core/workflow/artifact-io.js

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import * as yaml from "js-yaml";
+import { runStateSchema, stageArtifactFrontmatterSchema, } from "./schemas.js";
+/**
+ * Filesystem layout for one workflow run:
+ *
+ *   <cwd>/.agents/<task-id>/
+ *     plan.md
+ *     review.md
+ *     ...
+ *     state.json
+ *
+ * All paths in this module are relative to the project's <cwd>. The caller
+ * is responsible for choosing cwd; we never assume process.cwd() here so
+ * tests can target a tmp directory.
+ */
+export const AGENTS_DIR = ".agents";
+export const STATE_FILENAME = "state.json";
+export function runDir(cwd, taskId) {
+    return join(cwd, AGENTS_DIR, taskId);
+}
+export function stateFilePath(cwd, taskId) {
+    return join(runDir(cwd, taskId), STATE_FILENAME);
+}
+export function artifactPath(cwd, taskId, artifactName) {
+    return join(runDir(cwd, taskId), artifactName);
+}
+const FRONTMATTER_OPEN = /^---\s*\r?\n/;
+const FRONTMATTER_CLOSE = /\r?\n---\s*\r?\n/;
+export function parseStageArtifact(text) {
+    if (!FRONTMATTER_OPEN.test(text)) {
+        throw new Error("Stage artifact is missing YAML frontmatter (--- ... ---)");
+    }
+    const afterOpen = text.replace(FRONTMATTER_OPEN, "");
+    const closeMatch = afterOpen.match(FRONTMATTER_CLOSE);
+    if (!closeMatch || closeMatch.index === undefined) {
+        throw new Error("Stage artifact frontmatter is not terminated (--- ... ---)");
+    }
+    const yamlText = afterOpen.slice(0, closeMatch.index);
+    const body = afterOpen
+        .slice(closeMatch.index + closeMatch[0].length)
+        .replace(/^\s+/, "")
+        .replace(/\s+$/, "");
+    let raw;
+    try {
+        raw = yaml.load(yamlText);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse stage artifact frontmatter as YAML: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = stageArtifactFrontmatterSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Stage artifact frontmatter does not match schema: ${parsed.error.message}`);
+    }
+    return { frontmatter: parsed.data, body };
+}
+export function readStageArtifact(cwd, taskId, artifactName) {
+    const path = artifactPath(cwd, taskId, artifactName);
+    const text = readFileSync(path, "utf8");
+    return parseStageArtifact(text);
+}
+export function renderStageArtifact(frontmatter, body) {
+    const yamlText = yaml.dump(frontmatter, {
+        lineWidth: 100,
+        noRefs: true,
+        sortKeys: false,
+    });
+    const trimmedBody = body.trim();
+    return `---\n${yamlText}---\n\n${trimmedBody}\n`;
+}
+export function writeStageArtifact(cwd, taskId, artifactName, frontmatter, body) {
+    const dir = runDir(cwd, taskId);
+    mkdirSync(dir, { recursive: true });
+    const path = artifactPath(cwd, taskId, artifactName);
+    writeFileSync(path, renderStageArtifact(frontmatter, body), "utf8");
+    return path;
+}
+export function readRunState(cwd, taskId) {
+    const path = stateFilePath(cwd, taskId);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse run state at ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = runStateSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Run state at ${path} does not match schema: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+export function writeRunState(cwd, state) {
+    const validated = runStateSchema.parse(state);
+    const dir = runDir(cwd, validated.task_id);
+    mkdirSync(dir, { recursive: true });
+    const path = stateFilePath(cwd, validated.task_id);
+    writeFileSync(path, JSON.stringify(validated, null, 2) + "\n", "utf8");
+    return path;
+}

package/scaffold/mcp/dist/core/workflow/capabilities.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+/**
+ * Capability registry for the harness. A capability is a least-privilege
+ * profile referenced by a workflow stage's `capability` field. The
+ * pre-tool-use hook reads the active stage's capability and uses it to
+ * gate the agent's tool calls.
+ *
+ * The capability defines:
+ *   - read_globs    paths the agent may read (empty = no restriction)
+ *   - write_globs   paths the agent may modify (empty = read-only)
+ *   - tools_allowed which tool names the agent may call (empty = all)
+ *
+ * Glob patterns use minimatch syntax. The harness ships a default set
+ * keyed by the names referenced in default-workflows.ts; orgs can ship
+ * additional capabilities later via cortex-web sync.
+ */
+const slugSchema = z
+    .string()
+    .min(1)
+    .max(80)
+    .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$/);
+export const capabilityDefinitionSchema = z.object({
+    name: slugSchema,
+    description: z.string().min(1).max(500),
+    read_globs: z.array(z.string().min(1)).default([]),
+    write_globs: z.array(z.string().min(1)).default([]),
+    tools_allowed: z.array(z.string().min(1)).default([]),
+});
+/**
+ * Default capability profiles that ship with Cortex. Names match the
+ * `capability` fields referenced by SECURE_BUILD_WORKFLOW.
+ *
+ * tools_allowed is intentionally empty for most profiles to mean
+ * "no per-tool restriction beyond what the file globs already imply".
+ * The hook layer checks file paths first, tool name second.
+ */
+export const DEFAULT_CAPABILITIES = {
+    planner: {
+        name: "planner",
+        description: "Read-only profile for stages that produce planning artifacts. " +
+            "Can read the whole repo and call context tools, cannot modify any files.",
+        read_globs: ["**"],
+        write_globs: [],
+        tools_allowed: [],
+    },
+    reviewer: {
+        name: "reviewer",
+        description: "Read-only profile for review stages. Same access as planner; the " +
+            "review artifact itself is written by the harness, not by an Edit tool.",
+        read_globs: ["**"],
+        write_globs: [],
+        tools_allowed: [],
+    },
+    builder: {
+        name: "builder",
+        description: "Build profile. May edit source and test files but not config, " +
+            "lockfiles, CI workflows, or anything outside the obvious app surface.",
+        read_globs: ["**"],
+        write_globs: ["src/**", "tests/**", "test/**", "lib/**", "app/**", "components/**"],
+        tools_allowed: [],
+    },
+    tester: {
+        name: "tester",
+        description: "Mutation/test profile. Read-only on production code, may edit only " +
+            "test files. Used by mutation-testing or coverage-improvement stages.",
+        read_globs: ["**"],
+        write_globs: ["tests/**", "test/**", "**/*.test.ts", "**/*.test.tsx", "**/*.test.mjs", "**/*.spec.ts"],
+        tools_allowed: [],
+    },
+    "security-reviewer": {
+        name: "security-reviewer",
+        description: "Security review profile. Read-only across the repo. Produces a " +
+            "report artifact; no source modifications allowed.",
+        read_globs: ["**"],
+        write_globs: [],
+        tools_allowed: [],
+    },
+    human: {
+        name: "human",
+        description: "Sentinel capability for human approval stages. The harness does not " +
+            "invoke an agent for this stage; the human writes the artifact directly. " +
+            "If a tool call somehow reaches the hook under this capability, it is " +
+            "blocked because no automation should be running.",
+        read_globs: [],
+        write_globs: [],
+        tools_allowed: [],
+    },
+};