aegis-mcp-server 0.1.0

package/dist/services/policy-loader.d.ts

@@ -0,0 +1,56 @@
+/**
+ * PolicyLoader — Reads .agentpolicy/ files into process memory.
+ *
+ * Core of the zero-token-overhead design. All governance files are loaded
+ * into Node.js process memory on startup. The agent never sees these files —
+ * it only sees tool call results (allowed/blocked).
+ *
+ * Role resolution merges the skeleton fields (role.name, scope.primary_paths)
+ * with extension fields (paths.read/write, forbidden_actions) into a single
+ * ResolvedRole for fast enforcement lookups.
+ */
+import type { PolicyState, ResolvedRole, AegisMcpConfig } from '../types.js';
+export declare class PolicyLoader {
+    private config;
+    private state;
+    private watcher;
+    private onReload?;
+    constructor(config: AegisMcpConfig);
+    /**
+     * Load all policy files into memory. Call once on startup.
+     */
+    load(): Promise<PolicyState>;
+    /**
+     * Get current policy state. Throws if not loaded.
+     */
+    getState(): PolicyState;
+    /**
+     * Start watching .agentpolicy/ for changes and auto-reload.
+     */
+    startWatching(onReload?: () => void): void;
+    /**
+     * Stop watching and clean up.
+     */
+    stopWatching(): Promise<void>;
+    /**
+     * Get the resolved role for the configured agent, falling back to default.
+     */
+    getActiveRole(): ResolvedRole;
+    private resolvePolicyDir;
+    private loadJson;
+    private loadRoles;
+    /**
+     * Merge skeleton and extension fields into a single ResolvedRole.
+     *
+     * Skeleton: role.name, role.purpose, scope.primary_paths/secondary_paths/excluded_paths
+     * Extensions: paths.read/write, forbidden_actions, autonomy (flat string)
+     *
+     * For writable paths: scope.primary_paths takes precedence; paths.write used as fallback.
+     * For readable paths: paths.read used when present; otherwise derived from writable + secondary.
+     */
+    private resolveRole;
+    private handleChange;
+    private assertExists;
+    private log;
+}
+//# sourceMappingURL=policy-loader.d.ts.map

package/dist/services/policy-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-loader.d.ts","sourceRoot":"","sources":["../../src/services/policy-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EACV,WAAW,EAIX,YAAY,EACZ,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,qBAAa,YAAY;IAKX,OAAO,CAAC,MAAM;IAJ1B,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,QAAQ,CAAC,CAAa;gBAEV,MAAM,EAAE,cAAc;IAE1C;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC;IA4BlC;;OAEG;IACH,QAAQ,IAAI,WAAW;IAOvB;;OAEG;IACH,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI;IAgB1C;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAOnC;;OAEG;IACH,aAAa,IAAI,YAAY;IA8B7B,OAAO,CAAC,gBAAgB;YAOV,QAAQ;YAYR,SAAS;IAyBvB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;YA4CL,YAAY;YAYZ,YAAY;IAQ1B,OAAO,CAAC,GAAG;CAGZ"}

package/dist/services/policy-loader.js

@@ -0,0 +1,202 @@
+/**
+ * PolicyLoader — Reads .agentpolicy/ files into process memory.
+ *
+ * Core of the zero-token-overhead design. All governance files are loaded
+ * into Node.js process memory on startup. The agent never sees these files —
+ * it only sees tool call results (allowed/blocked).
+ *
+ * Role resolution merges the skeleton fields (role.name, scope.primary_paths)
+ * with extension fields (paths.read/write, forbidden_actions) into a single
+ * ResolvedRole for fast enforcement lookups.
+ */
+import { readFile, readdir, access } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { watch } from 'chokidar';
+export class PolicyLoader {
+    config;
+    state = null;
+    watcher = null;
+    onReload;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Load all policy files into memory. Call once on startup.
+     */
+    async load() {
+        const policyDir = this.resolvePolicyDir();
+        await this.assertExists(policyDir, 'Policy directory');
+        const constitution = await this.loadJson(join(policyDir, 'constitution.json'), 'constitution.json');
+        const governance = await this.loadJson(join(policyDir, 'governance.json'), 'governance.json');
+        const roles = await this.loadRoles(join(policyDir, 'roles'));
+        this.state = {
+            constitution,
+            governance,
+            roles,
+            projectRoot: this.config.projectRoot,
+            policyDir,
+        };
+        this.log(`Policy loaded: ${roles.size} role(s)`);
+        return this.state;
+    }
+    /**
+     * Get current policy state. Throws if not loaded.
+     */
+    getState() {
+        if (!this.state) {
+            throw new Error('Policy not loaded. Call load() first.');
+        }
+        return this.state;
+    }
+    /**
+     * Start watching .agentpolicy/ for changes and auto-reload.
+     */
+    startWatching(onReload) {
+        this.onReload = onReload;
+        const policyDir = this.resolvePolicyDir();
+        this.watcher = watch(policyDir, {
+            ignoreInitial: true,
+            awaitWriteFinish: { stabilityThreshold: 300 },
+        });
+        this.watcher.on('change', (path) => this.handleChange(path));
+        this.watcher.on('add', (path) => this.handleChange(path));
+        this.watcher.on('unlink', (path) => this.handleChange(path));
+        this.log('Watching policy directory for changes');
+    }
+    /**
+     * Stop watching and clean up.
+     */
+    async stopWatching() {
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    /**
+     * Get the resolved role for the configured agent, falling back to default.
+     */
+    getActiveRole() {
+        const state = this.getState();
+        const roleId = this.config.role;
+        const role = state.roles.get(roleId);
+        if (role)
+            return role;
+        const defaultRole = state.roles.get('default');
+        if (defaultRole) {
+            this.log(`Role "${roleId}" not found, using default`);
+            return defaultRole;
+        }
+        // Synthesize a permissive default if no role files exist
+        this.log('No role files found, using synthesized permissive default');
+        return {
+            id: 'default',
+            name: 'default',
+            purpose: 'Synthesized default role — no role files found',
+            writable_paths: ['**/*'],
+            secondary_paths: [],
+            excluded_paths: [],
+            readable_paths: ['**/*'],
+            autonomy: 'advisory',
+            forbidden_actions: [],
+        };
+    }
+    // ─── Private ────────────────────────────────────────────────────────────────
+    resolvePolicyDir() {
+        return join(this.config.projectRoot, this.config.policyDir ?? '.agentpolicy');
+    }
+    async loadJson(path, label) {
+        await this.assertExists(path, label);
+        const raw = await readFile(path, 'utf-8');
+        try {
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`Failed to parse ${label}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async loadRoles(rolesDir) {
+        const roles = new Map();
+        try {
+            await access(rolesDir);
+        }
+        catch {
+            return roles;
+        }
+        const entries = await readdir(rolesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith('.json'))
+                continue;
+            const roleId = basename(entry.name, '.json');
+            const raw = await this.loadJson(join(rolesDir, entry.name), `roles/${entry.name}`);
+            roles.set(roleId, this.resolveRole(roleId, raw));
+        }
+        return roles;
+    }
+    /**
+     * Merge skeleton and extension fields into a single ResolvedRole.
+     *
+     * Skeleton: role.name, role.purpose, scope.primary_paths/secondary_paths/excluded_paths
+     * Extensions: paths.read/write, forbidden_actions, autonomy (flat string)
+     *
+     * For writable paths: scope.primary_paths takes precedence; paths.write used as fallback.
+     * For readable paths: paths.read used when present; otherwise derived from writable + secondary.
+     */
+    resolveRole(id, raw) {
+        // Role identity — skeleton nested object, or flat string + description
+        const name = typeof raw.role === 'object' ? raw.role.name : String(raw.role);
+        const purpose = typeof raw.role === 'object'
+            ? raw.role.purpose
+            : (raw.description ?? '');
+        // Writable paths — skeleton primary_paths, or extension paths.write
+        const writable_paths = raw.scope?.primary_paths?.length
+            ? raw.scope.primary_paths
+            : (raw.paths?.write ?? []);
+        // Secondary paths
+        const secondary_paths = raw.scope?.secondary_paths ?? [];
+        // Excluded paths
+        const excluded_paths = raw.scope?.excluded_paths ?? [];
+        // Readable paths — extension paths.read, or all writable + secondary
+        const readable_paths = raw.paths?.read?.length
+            ? raw.paths.read
+            : [...writable_paths, ...secondary_paths];
+        // Autonomy — flat extension string or skeleton override
+        const autonomy = raw.autonomy
+            ? String(raw.autonomy)
+            : 'advisory';
+        // Forbidden actions
+        const forbidden_actions = raw.forbidden_actions ?? [];
+        return {
+            id,
+            name,
+            purpose,
+            writable_paths,
+            secondary_paths,
+            excluded_paths,
+            readable_paths,
+            autonomy,
+            forbidden_actions,
+        };
+    }
+    async handleChange(path) {
+        this.log(`Policy file changed: ${path}`);
+        try {
+            await this.load();
+            this.onReload?.();
+        }
+        catch (err) {
+            this.log(`Failed to reload policy: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async assertExists(path, label) {
+        try {
+            await access(path);
+        }
+        catch {
+            throw new Error(`${label} not found at: ${path}`);
+        }
+    }
+    log(message) {
+        process.stderr.write(`[aegis-mcp] ${message}\n`);
+    }
+}
+//# sourceMappingURL=policy-loader.js.map

package/dist/services/policy-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-loader.js","sourceRoot":"","sources":["../../src/services/policy-loader.ts"],"names":[],"mappings":"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"}

package/dist/tools/file-tools.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Governed File Tools — MCP tool registrations for file operations.
+ *
+ * These are the tools agents call instead of raw file system access.
+ * Every call is validated against the loaded policy before execution.
+ * The agent never sees the policy — only the verdict.
+ *
+ * Tools:
+ *   aegis_check_permissions  — Pre-check before writing (saves wasted generation)
+ *   aegis_write_file         — Governed write with path + content validation
+ *   aegis_read_file          — Governed read with path validation
+ *   aegis_delete_file        — Governed delete (uses write permissions)
+ *   aegis_execute            — Governed command execution
+ *   aegis_complete_task      — Task completion with quality gate validation
+ *   aegis_policy_summary     — Minimal role/permissions summary (~200 tokens)
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { EnforcementEngine } from '../services/enforcement-engine.js';
+import type { PolicyState, ResolvedRole } from '../types.js';
+export declare function registerTools(server: McpServer, getEngine: () => EnforcementEngine, getState: () => PolicyState, getRole: () => ResolvedRole): void;
+//# sourceMappingURL=file-tools.d.ts.map

package/dist/tools/file-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-tools.d.ts","sourceRoot":"","sources":["../../src/tools/file-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,MAAM,iBAAiB,EAClC,QAAQ,EAAE,MAAM,WAAW,EAC3B,OAAO,EAAE,MAAM,YAAY,GAC1B,IAAI,CAiYN"}

package/dist/tools/file-tools.js

@@ -0,0 +1,369 @@
+/**
+ * Governed File Tools — MCP tool registrations for file operations.
+ *
+ * These are the tools agents call instead of raw file system access.
+ * Every call is validated against the loaded policy before execution.
+ * The agent never sees the policy — only the verdict.
+ *
+ * Tools:
+ *   aegis_check_permissions  — Pre-check before writing (saves wasted generation)
+ *   aegis_write_file         — Governed write with path + content validation
+ *   aegis_read_file          — Governed read with path validation
+ *   aegis_delete_file        — Governed delete (uses write permissions)
+ *   aegis_execute            — Governed command execution
+ *   aegis_complete_task      — Task completion with quality gate validation
+ *   aegis_policy_summary     — Minimal role/permissions summary (~200 tokens)
+ */
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { dirname, join, isAbsolute } from 'node:path';
+import { execSync } from 'node:child_process';
+import { z } from 'zod';
+export function registerTools(server, getEngine, getState, getRole) {
+    // ─── aegis_check_permissions ──────────────────────────────────────────────
+    server.registerTool('aegis_check_permissions', {
+        title: 'Check Permissions',
+        description: `Check if an operation is allowed on a path before attempting it. Use this to pre-validate before writing or reading files — saves you from composing content that would be blocked.
+
+Args:
+  - path (string): Target file path relative to project root
+  - operation ('read' | 'write' | 'delete'): The operation to check
+
+Returns:
+  { "allowed": true } or { "allowed": false, "reason": "..." }`,
+        inputSchema: {
+            path: z.string().describe('Target file path relative to project root'),
+            operation: z.enum(['read', 'write', 'delete']).describe('Operation to check'),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ path, operation }) => {
+        const engine = getEngine();
+        const verdict = operation === 'read'
+            ? engine.validateRead(path)
+            : engine.validateWrite(path);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(verdict.allowed
+                        ? { allowed: true }
+                        : { allowed: false, reason: verdict.reason }),
+                }],
+        };
+    });
+    // ─── aegis_write_file ─────────────────────────────────────────────────────
+    server.registerTool('aegis_write_file', {
+        title: 'Write File (Governed)',
+        description: `Write content to a file with governance enforcement. Path is validated against your role's permissions and governance boundaries. Content is scanned for sensitive patterns. If the write violates policy, it is blocked and you receive the specific reason.
+
+Args:
+  - path (string): File path relative to project root
+  - content (string): File content to write
+
+Returns:
+  { "status": "success", "path": "..." } or { "status": "blocked", "reason": "..." }`,
+        inputSchema: {
+            path: z.string().describe('File path relative to project root'),
+            content: z.string().describe('File content to write'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ path, content }) => {
+        const engine = getEngine();
+        const state = getState();
+        const role = getRole();
+        // Validate path permissions
+        const pathVerdict = engine.validateWrite(path);
+        if (!pathVerdict.allowed) {
+            await logBlocked(engine, role, path, 'write', pathVerdict.reason);
+            return blocked(pathVerdict.reason);
+        }
+        // Scan content for sensitive patterns
+        const contentVerdict = engine.scanContent(content, path);
+        if (!contentVerdict.allowed) {
+            await logBlocked(engine, role, path, 'write (sensitive content)', contentVerdict.reason);
+            return blocked(contentVerdict.reason);
+        }
+        // Write the file
+        const absPath = toAbsolute(path, state.projectRoot);
+        await mkdir(dirname(absPath), { recursive: true });
+        await writeFile(absPath, content, 'utf-8');
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ status: 'success', path }),
+                }],
+        };
+    });
+    // ─── aegis_read_file ──────────────────────────────────────────────────────
+    server.registerTool('aegis_read_file', {
+        title: 'Read File (Governed)',
+        description: `Read the contents of a file with governance enforcement. Path is validated against your role's read permissions. If the read violates policy, it is blocked.
+
+Args:
+  - path (string): File path relative to project root
+
+Returns:
+  File content as text, or { "status": "blocked", "reason": "..." }`,
+        inputSchema: {
+            path: z.string().describe('File path relative to project root'),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ path }) => {
+        const engine = getEngine();
+        const state = getState();
+        const verdict = engine.validateRead(path);
+        if (!verdict.allowed) {
+            return blocked(verdict.reason);
+        }
+        const absPath = toAbsolute(path, state.projectRoot);
+        const content = await readFile(absPath, 'utf-8');
+        return {
+            content: [{
+                    type: 'text',
+                    text: content,
+                }],
+        };
+    });
+    // ─── aegis_delete_file ────────────────────────────────────────────────────
+    server.registerTool('aegis_delete_file', {
+        title: 'Delete File (Governed)',
+        description: `Delete a file with governance enforcement. Write permissions are required. If the delete violates policy, it is blocked.
+
+Args:
+  - path (string): File path relative to project root
+
+Returns:
+  { "status": "success", "path": "..." } or { "status": "blocked", "reason": "..." }`,
+        inputSchema: {
+            path: z.string().describe('File path relative to project root'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ path }) => {
+        const engine = getEngine();
+        const state = getState();
+        const role = getRole();
+        const verdict = engine.validateWrite(path);
+        if (!verdict.allowed) {
+            await logBlocked(engine, role, path, 'delete', verdict.reason);
+            return blocked(verdict.reason);
+        }
+        const absPath = toAbsolute(path, state.projectRoot);
+        await unlink(absPath);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ status: 'success', path }),
+                }],
+        };
+    });
+    // ─── aegis_execute ────────────────────────────────────────────────────────
+    server.registerTool('aegis_execute', {
+        title: 'Execute Command (Governed)',
+        description: `Execute a shell command in the project directory. Currently validates that the command runs within the project root. Future versions will enforce command-level permissions.
+
+Args:
+  - command (string): Shell command to execute
+  - cwd (string, optional): Working directory (defaults to project root)
+
+Returns:
+  { "status": "success", "stdout": "...", "stderr": "..." } or { "status": "error", ... }`,
+        inputSchema: {
+            command: z.string().describe('Shell command to execute'),
+            cwd: z.string().optional().describe('Working directory (defaults to project root)'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ command, cwd }) => {
+        const state = getState();
+        try {
+            const result = execSync(command, {
+                cwd: cwd ?? state.projectRoot,
+                encoding: 'utf-8',
+                timeout: 60_000,
+                maxBuffer: 1024 * 1024 * 10,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ status: 'success', stdout: result, stderr: '' }),
+                    }],
+            };
+        }
+        catch (err) {
+            const execErr = err;
+            return {
+                isError: true,
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            status: 'error',
+                            stdout: execErr.stdout ?? '',
+                            stderr: execErr.stderr ?? execErr.message ?? 'Unknown error',
+                        }),
+                    }],
+            };
+        }
+    });
+    // ─── aegis_complete_task ──────────────────────────────────────────────────
+    server.registerTool('aegis_complete_task', {
+        title: 'Complete Task',
+        description: `Signal task completion and run required quality gates. Maps the governance quality_gate.pre_commit flags to build_commands and runs each required check. Returns pass/fail with details.
+
+Args:
+  - task_id (string): Identifier for the task being completed
+  - summary (string): Brief summary of what was accomplished
+
+Returns:
+  { "status": "passed", "gates_run": [...] } or { "status": "failed", "failures": [...] }`,
+        inputSchema: {
+            task_id: z.string().describe('Task identifier'),
+            summary: z.string().describe('Summary of completed work'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ task_id, summary }) => {
+        const engine = getEngine();
+        const state = getState();
+        const gates = engine.getQualityGateCommands();
+        if (gates.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            status: 'passed',
+                            task_id,
+                            summary,
+                            gates_run: [],
+                            message: 'No quality gates configured with matching build commands.',
+                        }),
+                    }],
+            };
+        }
+        const results = [];
+        for (const gate of gates) {
+            try {
+                const output = execSync(gate.command, {
+                    cwd: state.projectRoot,
+                    encoding: 'utf-8',
+                    timeout: 120_000,
+                });
+                results.push({ name: gate.name, passed: true, output: output.slice(0, 500) });
+            }
+            catch (err) {
+                const execErr = err;
+                results.push({
+                    name: gate.name,
+                    passed: false,
+                    output: (execErr.stderr ?? execErr.message ?? 'Failed').slice(0, 500),
+                });
+            }
+        }
+        const allPassed = results.every((r) => r.passed);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: allPassed ? 'passed' : 'failed',
+                        task_id,
+                        summary,
+                        gates_run: results,
+                    }),
+                }],
+        };
+    });
+    // ─── aegis_policy_summary ─────────────────────────────────────────────────
+    server.registerTool('aegis_policy_summary', {
+        title: 'Policy Summary',
+        description: `Get a minimal summary of your current role and permissions. Returns your role name, writable paths, excluded paths, forbidden actions, and key governance rules — just enough to understand your boundaries without loading full policy files.
+
+Returns:
+  { "role": "...", "writable_paths": [...], "forbidden_actions": [...], ... }`,
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        const role = getRole();
+        const state = getState();
+        const protocol = state.governance.override_protocol;
+        const summary = {
+            role: role.id,
+            role_name: role.name,
+            purpose: role.purpose,
+            autonomy: role.autonomy,
+            writable_paths: role.writable_paths,
+            secondary_paths: role.secondary_paths,
+            excluded_paths: role.excluded_paths,
+            readable_paths: role.readable_paths,
+            forbidden_actions: role.forbidden_actions,
+            governance_forbidden_paths: state.governance.permissions.boundaries.forbidden ?? [],
+            override_behavior: protocol?.behavior ?? 'warn_confirm_and_log',
+            immutable_policies: protocol?.immutable_policies ?? [],
+            quality_gates: {
+                must_pass_tests: state.governance.quality_gate.pre_commit.must_pass_tests ?? false,
+                must_pass_lint: state.governance.quality_gate.pre_commit.must_pass_lint ?? false,
+                must_pass_typecheck: state.governance.quality_gate.pre_commit.must_pass_typecheck ?? false,
+            },
+        };
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(summary),
+                }],
+        };
+    });
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function toAbsolute(path, projectRoot) {
+    return isAbsolute(path) ? path : join(projectRoot, path);
+}
+function blocked(reason) {
+    return {
+        isError: true,
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ status: 'blocked', reason }),
+            }],
+    };
+}
+async function logBlocked(engine, role, path, operation, reason) {
+    await engine.logOverride({
+        timestamp: new Date().toISOString(),
+        policy_violated: reason,
+        policy_text: reason,
+        action_requested: `${operation}: ${path}`,
+        human_confirmed: false,
+        agent_role: role.id,
+        rationale: 'Blocked by enforcement layer',
+    });
+}
+//# sourceMappingURL=file-tools.js.map