@musashishao/folderforge 1.2.0

package/dist/tools/workspace-tools.js

@@ -0,0 +1,186 @@
+import { existsSync } from 'node:fs';
+import { defineTool } from './registry.js';
+import { detectCommands } from '../workspace/project-detector.js';
+import { onboardProject } from '../workspace/onboarding.js';
+import { TASK_PRESETS } from './index.js';
+export function workspaceTools() {
+    return [
+        defineTool({
+            name: 'workspace_activate',
+            description: 'Activate a local project as the active workspace.',
+            group: 'workspace',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { path: { type: 'string', description: 'Absolute path to the project folder.' } },
+                required: ['path'],
+            },
+            handler: async (args, ctx) => {
+                const info = ctx.container.workspace.activate(String(args.path));
+                ctx.container.audit.record({ type: 'workspace_activate', summary: info.projectRoot });
+                return { ok: true, data: info };
+            },
+        }),
+        defineTool({
+            name: 'workspace_list',
+            description: 'List all activated workspaces and which one is current.',
+            group: 'workspace',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_args, ctx) => ({
+                ok: true,
+                data: { workspaces: ctx.container.workspace.list() },
+            }),
+        }),
+        defineTool({
+            name: 'workspace_switch',
+            description: 'Switch the current workspace to another already-activated project. ' +
+                'Path-less tool calls then operate on this workspace.',
+            group: 'workspace',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { path: { type: 'string', description: 'Absolute path of an activated project.' } },
+                required: ['path'],
+            },
+            handler: async (args, ctx) => {
+                try {
+                    const info = ctx.container.workspace.setCurrent(String(args.path));
+                    ctx.container.audit.record({ type: 'workspace_activate', summary: `switch ${info.projectRoot}` });
+                    return { ok: true, data: info };
+                }
+                catch (err) {
+                    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+                }
+            },
+        }),
+        defineTool({
+            name: 'workspace_deactivate',
+            description: 'Deactivate a workspace. If it was current, the most recent remaining one becomes current.',
+            group: 'workspace',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { path: { type: 'string', description: 'Absolute path of the project to deactivate.' } },
+                required: ['path'],
+            },
+            handler: async (args, ctx) => {
+                const removed = ctx.container.workspace.deactivate(String(args.path));
+                return removed
+                    ? { ok: true, data: { deactivated: String(args.path), workspaces: ctx.container.workspace.list() } }
+                    : { ok: false, error: `Workspace was not active: ${String(args.path)}` };
+            },
+        }),
+        defineTool({
+            name: 'workspace_status',
+            description: 'Return the active workspace, policy mode, allowed directories, and enabled adapters.',
+            group: 'workspace',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_args, ctx) => {
+                const active = ctx.container.workspace.getActive();
+                return {
+                    ok: true,
+                    data: {
+                        active: Boolean(active),
+                        project: active,
+                        mode: ctx.container.policy.getMode(),
+                        allowedDirectories: ctx.config.workspace.allowedDirectories,
+                        adapters: ctx.container.adapters.status(),
+                    },
+                };
+            },
+        }),
+        defineTool({
+            name: 'workspace_onboard',
+            description: 'Scan the project and generate memory files (overview, commands, conventions, testing).',
+            group: 'workspace',
+            mutates: true,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_args, ctx) => {
+                const root = ctx.container.workspace.requireActive().projectRoot;
+                const memory = ctx.container.workspace.getMemory();
+                const result = onboardProject(root, memory);
+                return { ok: true, data: result };
+            },
+        }),
+        defineTool({
+            name: 'workspace_health',
+            description: 'Run health checks: folder, git, package manager, adapters, detected commands, policy.',
+            group: 'workspace',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_args, ctx) => {
+                const active = ctx.container.workspace.getActive();
+                const root = active?.projectRoot ?? ctx.projectRoot;
+                const cmds = active ? detectCommands(root) : { packageManager: null, scripts: {} };
+                const serena = await ctx.container.adapters.health('serena').catch(() => ({ enabled: false, ready: false }));
+                const playwright = await ctx.container.adapters
+                    .health('playwright')
+                    .catch(() => ({ enabled: false, ready: false }));
+                return {
+                    ok: true,
+                    data: {
+                        folderExists: existsSync(root),
+                        gitRepo: active?.git ?? false,
+                        packageManager: cmds.packageManager,
+                        commandsDetected: Object.keys(cmds.scripts),
+                        adapters: { serena, playwright },
+                        policyLoaded: true,
+                        mode: ctx.container.policy.getMode(),
+                    },
+                };
+            },
+        }),
+        defineTool({
+            name: 'workspace_route',
+            description: 'Switch the visible tool set to a task preset (explore, run_ui, fix_tests) ' +
+                'or pass reset=true / preset="all" to expose every tool again.',
+            group: 'workspace',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    preset: {
+                        type: 'string',
+                        description: 'Preset name: explore | run_ui | fix_tests | all',
+                        enum: [...Object.keys(TASK_PRESETS), 'all'],
+                    },
+                    reset: { type: 'boolean', description: 'Expose every tool again (same as preset=all).' },
+                },
+            },
+            handler: async (args, ctx) => {
+                const registry = ctx.container.registry;
+                if (!registry) {
+                    return { ok: false, error: 'Tool registry is not available for routing.' };
+                }
+                const presets = Object.keys(TASK_PRESETS);
+                const reset = args.reset === true || args.preset === 'all';
+                if (reset) {
+                    registry.setActive(null);
+                    ctx.container.audit.record({ type: 'workspace_route', summary: 'all' });
+                    return {
+                        ok: true,
+                        data: { preset: 'all', active: registry.listActive().map((t) => t.name) },
+                    };
+                }
+                const preset = args.preset === undefined ? undefined : String(args.preset);
+                if (!preset) {
+                    return {
+                        ok: true,
+                        data: { presets, hint: 'Pass preset=<name> to focus the tool set, or reset=true to show all.' },
+                    };
+                }
+                if (!presets.includes(preset)) {
+                    return { ok: false, error: `Unknown preset "${preset}". Available: ${presets.join(', ')}, all.` };
+                }
+                registry.setActive(TASK_PRESETS[preset]);
+                ctx.container.audit.record({ type: 'workspace_route', summary: preset });
+                return {
+                    ok: true,
+                    data: { preset, active: registry.listActive().map((t) => t.name) },
+                };
+            },
+        }),
+    ];
+}

package/dist/workspace/memory-store.js

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Ensure FolderForge's own state directory never pollutes the host project's
+ * git status. We drop a self-ignoring `.gitignore` (`*`) into `.folderforge/`,
+ * which makes git ignore the entire directory - including the `.gitignore`
+ * itself - so `git status` stays clean for the user's repository.
+ *
+ * Idempotent and safe to call on every workspace activation.
+ */
+export function ensureStateDirIgnored(projectRoot) {
+    const stateDir = join(projectRoot, '.folderforge');
+    if (!existsSync(stateDir)) {
+        mkdirSync(stateDir, { recursive: true });
+    }
+    const ignore = join(stateDir, '.gitignore');
+    if (!existsSync(ignore)) {
+        writeFileSync(ignore, '*\n', 'utf8');
+    }
+}
+/**
+ * Memory store backed by markdown files under .folderforge/memory/.
+ */
+export class MemoryStore {
+    dir;
+    constructor(projectRoot) {
+        this.dir = join(projectRoot, '.folderforge', 'memory');
+        if (!existsSync(this.dir)) {
+            mkdirSync(this.dir, { recursive: true });
+        }
+        // Keep FolderForge's state out of the user's git status.
+        ensureStateDirIgnored(projectRoot);
+    }
+    safeName(name) {
+        const base = name.endsWith('.md') ? name : `${name}.md`;
+        if (base.includes('/') || base.includes('..') || base.includes('\\')) {
+            throw new Error(`Invalid memory name: ${name}`);
+        }
+        return base;
+    }
+    list() {
+        if (!existsSync(this.dir))
+            return [];
+        return readdirSync(this.dir).filter((f) => f.endsWith('.md'));
+    }
+    read(name) {
+        const path = join(this.dir, this.safeName(name));
+        if (!existsSync(path))
+            throw new Error(`Memory not found: ${name}`);
+        return readFileSync(path, 'utf8');
+    }
+    write(name, content) {
+        const path = join(this.dir, this.safeName(name));
+        writeFileSync(path, content, 'utf8');
+        return path;
+    }
+    update(name, append) {
+        const file = this.safeName(name);
+        const path = join(this.dir, file);
+        const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+        writeFileSync(path, existing + (existing ? '\n' : '') + append, 'utf8');
+        return path;
+    }
+    dir_() {
+        return this.dir;
+    }
+}

package/dist/workspace/onboarding.js

@@ -0,0 +1,46 @@
+import { detectProject, detectCommands } from './project-detector.js';
+const TEMPLATE = (info, cmds) => {
+    const overview = `# Project Overview: ${info.name}
+
+- Root: ${info.projectRoot}
+- Languages: ${info.languageHints.join(', ') || 'unknown'}
+- Package managers: ${info.packageManagers.join(', ') || 'unknown'}
+- Git: ${info.git ? 'yes' : 'no'}
+
+_This file was generated by FolderForge onboarding. Edit freely._
+`;
+    const commands = `# Commands
+
+- Package manager: ${cmds.packageManager ?? 'unknown'}
+- Test framework: ${cmds.testFramework ?? 'unknown'}
+
+| Task | Command |
+| --- | --- |
+${Object.entries(cmds.scripts)
+        .map(([k, v]) => `| ${k} | \`${v}\` |`)
+        .join('\n') || '| (none detected) | |'}
+`;
+    const conventions = `# Coding Conventions
+
+- Detected languages: ${info.languageHints.join(', ') || 'unknown'}
+- Add team conventions here (formatting, imports, naming, error handling).
+`;
+    const testing = `# Testing Strategy
+
+- Framework: ${cmds.testFramework ?? 'unknown'}
+- Run with: \`${cmds.scripts.test ?? 'TBD'}\`
+- Describe coverage expectations and CI here.
+`;
+    return { overview, commands, conventions, testing };
+};
+export function onboardProject(root, memory) {
+    const project = detectProject(root);
+    const commands = detectCommands(root);
+    const t = TEMPLATE(project, commands);
+    const written = [];
+    written.push(memory.write('project_overview.md', t.overview));
+    written.push(memory.write('commands.md', t.commands));
+    written.push(memory.write('coding_conventions.md', t.conventions));
+    written.push(memory.write('testing_strategy.md', t.testing));
+    return { project, commands, writtenMemories: written };
+}

package/dist/workspace/project-detector.js

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function detectProject(root) {
+    const languageHints = new Set();
+    const packageManagers = new Set();
+    const checks = [
+        ['package.json', () => languageHints.add('typescript')],
+        ['tsconfig.json', () => languageHints.add('typescript')],
+        ['pyproject.toml', () => languageHints.add('python')],
+        ['requirements.txt', () => languageHints.add('python')],
+        ['go.mod', () => languageHints.add('go')],
+        ['Cargo.toml', () => languageHints.add('rust')],
+        ['composer.json', () => languageHints.add('php')],
+        ['pom.xml', () => languageHints.add('java')],
+        ['build.gradle', () => languageHints.add('java')],
+    ];
+    for (const [file, fn] of checks) {
+        if (existsSync(join(root, file)))
+            fn();
+    }
+    if (existsSync(join(root, 'pnpm-lock.yaml')))
+        packageManagers.add('pnpm');
+    else if (existsSync(join(root, 'yarn.lock')))
+        packageManagers.add('yarn');
+    else if (existsSync(join(root, 'package-lock.json')))
+        packageManagers.add('npm');
+    else if (existsSync(join(root, 'package.json')))
+        packageManagers.add('npm');
+    if (existsSync(join(root, 'pyproject.toml')))
+        packageManagers.add('pip');
+    if (existsSync(join(root, 'go.mod')))
+        packageManagers.add('go');
+    if (existsSync(join(root, 'Cargo.toml')))
+        packageManagers.add('cargo');
+    return {
+        projectRoot: root,
+        name: basename(root),
+        languageHints: [...languageHints],
+        packageManagers: [...packageManagers],
+        git: existsSync(join(root, '.git')),
+    };
+}
+export function detectCommands(root) {
+    const pkg = readJson(join(root, 'package.json'));
+    if (pkg && typeof pkg.scripts === 'object' && pkg.scripts) {
+        const scripts = pkg.scripts;
+        let pm = 'npm';
+        if (existsSync(join(root, 'pnpm-lock.yaml')))
+            pm = 'pnpm';
+        else if (existsSync(join(root, 'yarn.lock')))
+            pm = 'yarn';
+        const norm = {};
+        for (const key of ['dev', 'start', 'test', 'build', 'lint', 'typecheck']) {
+            if (scripts[key])
+                norm[key] = `${pm} run ${key}`;
+        }
+        let testFramework;
+        const deps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+        };
+        if (deps?.vitest)
+            testFramework = 'vitest';
+        else if (deps?.jest)
+            testFramework = 'jest';
+        else if (deps?.mocha)
+            testFramework = 'mocha';
+        return { packageManager: pm, scripts: norm, ...(testFramework ? { testFramework } : {}) };
+    }
+    if (existsSync(join(root, 'pyproject.toml')) || existsSync(join(root, 'requirements.txt'))) {
+        return {
+            packageManager: 'pip',
+            scripts: { test: 'pytest', lint: 'ruff check .', typecheck: 'mypy .' },
+            testFramework: 'pytest',
+        };
+    }
+    if (existsSync(join(root, 'go.mod'))) {
+        return { packageManager: 'go', scripts: { test: 'go test ./...', build: 'go build ./...' }, testFramework: 'go test' };
+    }
+    if (existsSync(join(root, 'Cargo.toml'))) {
+        return { packageManager: 'cargo', scripts: { test: 'cargo test', build: 'cargo build' }, testFramework: 'cargo test' };
+    }
+    if (existsSync(join(root, 'Makefile'))) {
+        return { packageManager: 'make', scripts: { test: 'make test', build: 'make build' } };
+    }
+    return { packageManager: null, scripts: {} };
+}

package/dist/workspace/workspace-manager.js

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { detectProject } from './project-detector.js';
+import { MemoryStore } from './memory-store.js';
+import { logger } from '../core/logger.js';
+/**
+ * Tracks one or more activated projects and which one is "current".
+ *
+ * Multi-project support: several workspaces can be active at once (keyed by
+ * absolute root). `current` points at the workspace that path-less tool calls
+ * operate on; switch it with {@link setCurrent}. The single-project API
+ * (`activate`, `getActive`, `requireActive`, `projectRoot`, `getMemory`) is
+ * preserved and always refers to the current workspace.
+ */
+export class WorkspaceManager {
+    allowedDirectories;
+    sessions = new Map();
+    current = null;
+    constructor(allowedDirectories) {
+        this.allowedDirectories = allowedDirectories;
+    }
+    assertAllowed(abs) {
+        const allowed = this.allowedDirectories.some((d) => abs === resolve(d) || abs.startsWith(resolve(d)));
+        if (!allowed) {
+            throw new Error(`Project path is not within allowed directories: ${abs}`);
+        }
+    }
+    /**
+     * Activate a project and make it the current workspace. If it was already
+     * activated, this simply re-selects it as current.
+     */
+    activate(path) {
+        const abs = resolve(path);
+        if (!existsSync(abs)) {
+            throw new Error(`Project path does not exist: ${abs}`);
+        }
+        this.assertAllowed(abs);
+        let session = this.sessions.get(abs);
+        if (!session) {
+            session = { info: detectProject(abs), memory: new MemoryStore(abs), root: abs, activatedAt: Date.now() };
+            this.sessions.set(abs, session);
+            logger.info({ project: session.info.name, root: abs }, 'Workspace activated');
+        }
+        this.current = abs;
+        return session.info;
+    }
+    /** Switch the current workspace to an already-activated project. */
+    setCurrent(path) {
+        const abs = resolve(path);
+        const session = this.sessions.get(abs);
+        if (!session) {
+            throw new Error(`Workspace not activated: ${abs}. Call workspace_activate first.`);
+        }
+        this.current = abs;
+        logger.info({ project: session.info.name, root: abs }, 'Current workspace switched');
+        return session.info;
+    }
+    /** Deactivate a workspace. If it was current, current falls back to most recent. */
+    deactivate(path) {
+        const abs = resolve(path);
+        const existed = this.sessions.delete(abs);
+        if (this.current === abs) {
+            const remaining = [...this.sessions.values()].sort((a, b) => b.activatedAt - a.activatedAt);
+            this.current = remaining[0]?.root ?? null;
+        }
+        return existed;
+    }
+    /** All activated workspaces, with a flag for the current one. */
+    list() {
+        return [...this.sessions.values()].map((s) => ({
+            ...s.info,
+            root: s.root,
+            current: s.root === this.current,
+        }));
+    }
+    currentSession() {
+        return this.current ? this.sessions.get(this.current) ?? null : null;
+    }
+    getActive() {
+        return this.currentSession()?.info ?? null;
+    }
+    requireActive() {
+        const s = this.currentSession();
+        if (!s)
+            throw new Error('No active workspace. Call workspace_activate first.');
+        return s.info;
+    }
+    projectRoot() {
+        return this.currentSession()?.info.projectRoot ?? null;
+    }
+    getMemory() {
+        const s = this.currentSession();
+        if (!s)
+            throw new Error('No active workspace memory store.');
+        return s.memory;
+    }
+    /** Memory store for a specific activated workspace (defaults to current). */
+    getMemoryFor(path) {
+        if (!path)
+            return this.getMemory();
+        const s = this.sessions.get(resolve(path));
+        if (!s)
+            throw new Error(`Workspace not activated: ${resolve(path)}`);
+        return s.memory;
+    }
+}

package/docs/adapters.md

@@ -0,0 +1,76 @@
+# Adapters (child MCP servers)
+
+FolderForge can proxy other MCP servers so the agent sees one unified tool
+surface. Adapters are configured under `adapters` in the config and managed by
+`src/adapters/child-mcp/registry.ts` (spawning) and `client.ts` (the MCP client
+that talks to each child over stdio).
+
+## Configuration
+
+```yaml
+adapters:
+  serena:
+    enabled: false
+    command: serena
+    args: []
+  playwright:
+    enabled: true
+    command: npx
+    args: ["-y", "@playwright/mcp@latest"]
+  desktopCommander:
+    enabled: false
+    command: npx
+    args: ["-y", "@wonderwhy-er/desktop-commander@latest"]
+```
+
+Each adapter (`AdapterDef`) has:
+
+- `enabled` - whether to spawn it on startup;
+- `command` / `args` - how to launch the child server;
+- `env` - optional extra environment (subject to secret redaction).
+
+## Lifecycle
+
+1. On startup, `ChildMcpRegistry` reads enabled adapters from config.
+2. Adapters start **lazily** - the child process is spawned on first use (or first
+   tool discovery), not eagerly, to avoid paying their cost when unused.
+3. The child's tools are discovered via `tools/list`, **namespaced** with the
+   adapter name and a `__` separator (e.g. `serena__find_symbol`), and
+   re-exported through the main registry.
+4. Calls are still wrapped by the FolderForge policy + audit pipeline before
+   being forwarded to the child.
+5. On shutdown, `stopAll()` terminates every spawned child.
+
+## Tool namespacing
+
+Every proxied tool is exposed as `<adapter>__<childToolName>`:
+
+| Adapter | Example namespaced tools |
+| --- | --- |
+| `serena` | `serena__find_symbol`, `serena__find_referencing_symbols` |
+| `playwright` | `playwright__browser_navigate`, `playwright__browser_snapshot` |
+| `desktopCommander` | `desktopCommander__<tool>` |
+
+The separator is the `NS_SEP` constant in `src/tools/adapter-tools.ts`. Proxied
+tools default to `MEDIUM` risk and `mutates: true`, so policy mode and the
+approval list still gate them.
+
+## Provided integrations
+
+| Adapter | Purpose | Tool prefix |
+| --- | --- | --- |
+| Serena | Semantic code intelligence (symbols, references) | `serena__*` |
+| Playwright | Browser automation and inspection | `playwright__*` |
+| Desktop Commander | Extended local desktop control (optional) | `desktopCommander__*` |
+
+## Writing a new adapter
+
+1. Add an `AdapterDef` entry to `AdaptersConfig` in `src/core/types.ts`.
+2. Provide a default in `src/core/config.ts`.
+3. Add its name to `ADAPTER_NAMES` in `src/tools/adapter-tools.ts` and to
+   `AdapterName` in `src/adapters/child-mcp/registry.ts` so its tools are
+   discovered, namespaced, and proxied.
+
+Because every proxied call passes through `PolicyEngine.evaluate`, child tools
+inherit the same risk classification, approval, and audit guarantees as native
+tools - decide their risk in `TOOL_RISK` (`src/policy/risk.ts`).

package/docs/architecture.md

@@ -0,0 +1,66 @@
+# Architecture
+
+FolderForge is an MCP-native control plane that sits between an AI
+coding agent and a local development workspace. It exposes a single, curated set
+of tools over the Model Context Protocol and wraps every call in a policy +
+audit pipeline.
+
+## High-level flow
+
+```
+agent (Claude Desktop / Codex / ...)
+        |  JSON-RPC (MCP)
+        v
+ transport (stdio | streamable http)      src/server/transports/*
+        |
+        v
+   MCP Server                              src/server/mcp-server.ts
+        |  tools/list  -> registry.listActive()
+        |  tools/call  -> registry.call()
+        v
+  ToolRegistry  --------------------------- src/tools/registry.ts
+        |  classify risk -> PolicyEngine.evaluate()
+        |  audit.record()
+        v
+  PolicyEngine  --------------------------- src/policy/policy-engine.ts
+   (path / command / secret / approvals)
+        |  allow | deny | approval
+        v
+  Tool handler (file/git/shell/...)        src/tools/*-tools.ts
+        |
+        v
+  Container services                        src/core/container.ts
+   (workspace, processes, db, adapters, audit)
+```
+
+A second, independent HTTP server serves the local dashboard
+(`src/dashboard/server.ts`), which reads the same `Container` to render status,
+audit, processes, and approvals.
+
+## Modules
+
+| Area | Path | Responsibility |
+| --- | --- | --- |
+| Entrypoint | `src/main.ts` | Parse args, `loadConfig`, build `Container` + registry, start server + dashboard |
+| Config | `src/core/config.ts` | Defaults + YAML merge + path normalization |
+| Container | `src/core/container.ts` | Dependency container shared by all handlers |
+| Registry | `src/tools/registry.ts` | Tool catalog, active subset, policy + audit pipeline |
+| Server | `src/server/mcp-server.ts` | MCP `tools/list` and `tools/call` handlers |
+| Transports | `src/server/transports/*` | stdio and Streamable HTTP binding |
+| Policy | `src/policy/*` | Path, command, secret policies; risk; approvals |
+| Audit | `src/audit/*` | Append-only JSONL log + ring buffer |
+| Managers | `src/managers/*` | Long-running processes, DB connections |
+| Workspace | `src/workspace/*` | Project detection, activation, memory store |
+| Adapters | `src/adapters/child-mcp/*` | Proxy child MCP servers (Serena, Playwright) |
+| Dashboard | `src/dashboard/*` | Local read/approve control plane UI |
+
+## Design principles
+
+- **stdout is sacred.** On the stdio transport, stdout carries the JSON-RPC
+  channel only. All logs go to stderr (`src/core/logger.ts`).
+- **One decision point.** Every mutation flows through `PolicyEngine.evaluate`.
+  Tools never bypass it.
+- **Curated surface.** The registry can expose a routed subset
+  (`TASK_PRESETS`) so agents see a focused tool list instead of everything.
+- **Fail safe.** Unknown tools, denied paths, and CRITICAL commands return a
+  structured error rather than throwing across the protocol boundary.