spl-lang 0.1.1 → 0.2.0

package/README.md

@@ -19,13 +19,13 @@ Requires Node 20+ and an authenticated GitHub Copilot.
 ```
 spl <script.spl> [--log-level error|info|debug] [--silent] [--model <id>]
                  [--store <file.json> | --store-module <module>]
-                 [--timeout <s>] [--cwd <dir>] [--check]
+                 [--timeout <s>] [--cwd <dir>] [--mcp <file.json>] [--check]
 spl login          # GitHub device flow: prints a code, you confirm it in the browser
 spl logout         # removes the credentials saved by `spl login`
 ```
 
 * stdout: the value of `success` or a top-level `return` (strings raw, everything else as JSON) or the failure payload.
-* stderr: logs, including model and reasoning effort of every LLM call.
+* stderr: logs, including full LLM requests and raw responses (`[llm]`) and executed statement traces with line numbers (`[deterministic]`) at every non-silent log level (`error`, `info`, `debug`). Model and reasoning effort are included at `info` and `debug`. Logs may contain sensitive data; use `--silent` to suppress them.
 * Exit code: `0` success, `1` uncaught failure, `2` syntax/usage error.
 
 `spl login` does nothing if the runtime is already authenticated (an earlier login, a Copilot CLI / `gh` login or
@@ -94,17 +94,57 @@ Decisions worth knowing (the PRD leaves them open):
 ## Restrictions
 
 Two layers: the LLM is told about active restrictions in the prompt, and the runtime enforces them. The LLM only gets
-the five runtime tools (`read_file`, `write_file`, `web_fetch`, `web_search`, `shell`); every call is checked against
+the five runtime tools (`read_file`, `write_file`, `web_fetch`, `web_search`, `shell`) plus configured MCP tools; every call is checked against
 the active `restrict` scopes and any other Copilot permission request is rejected. A violation raises a
 `restriction_violation` failure (catchable with `try/except`).
 
 * Paths are canonicalized (symlinks resolved, `..` removed) relative to `--cwd` before the check.
 * `net` matches exact hosts (and `*.example.com` wildcards); redirects are re-checked on every hop. `web_search`
   needs `html.duckduckgo.com` to be allowed.
-* `exec` matches the executable name. While any restriction is active, `shell` accepts only simple commands (no
-  `&|;<>` redirects, substitution or chaining) so the check is exact; path-like and URL arguments are also checked
-  against `fs`/`net`. This is best effort for programs that touch files or the network on their own.
+* `exec` matches the executable name. Executables in pipelines and chains are checked against `restrict exec`,
+  and path-like and URL arguments and redirection targets are checked against `fs`/`net`. This is best effort for
+  programs that touch files or the network on their own.
 * Nested restrictions of one kind intersect and can never widen.
+* Clauses can be combined: `restrict './src', net 'example.com', exec 'git', mcp 'docs/search' { ... }`.
+  Repeating a kind intersects its clauses, just like nesting.
+* `mcp` allows configured servers (`'docs'` or `'docs/*'`) or individual tools (`'docs/search'`).
+  Selectors are case-sensitive; nested scopes cannot widen the configuration's tool allowlist.
+
+On Windows, `dir` switches such as `/s`, `/b` and `/a:-d` are recognized as options,
+not filesystem paths. Paths and redirection targets remain subject to filesystem restrictions.
+
+## MCP tools
+
+Pass `--mcp .vscode/mcp.json` to load MCP servers in VS Code's JSON format:
+
+See the [MCP configuration reference](../docs/cli.html#mcp) for HTTP/SSE and stdio examples,
+all supported fields, authentication, variable expansion and validation commands.
+Remote servers must explicitly set `"type": "http"` or `"type": "sse"`; omitting it defaults to stdio.
+
+```json
+{
+  "servers": {
+    "docs": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/tools/docs-server.js"],
+      "tools": ["search"]
+    }
+  }
+}
+```
+
+The LLM can call these tools during `?`, `think`, and tool-backed calls. Stdio servers support `command`,
+`args`, `env`, and `cwd`; `http`/`sse` servers use `url` and optional `headers`. All support optional `tools`
+(`["*"]` or omitted means all, `[]` disables the server) and `timeout` in milliseconds.
+`${workspaceFolder}` expands to `--cwd`; `${env:NAME}` expands environment variables. Server working
+directories default to `--cwd`; relative server `cwd` values resolve against it. The config filename is
+relative to the invoking directory. `--check` also validates this config without starting servers.
+Interactive `inputs`, unsupported fields/variables, JSON comments and trailing commas are rejected.
+
+Only configured, scope-allowed MCP tools are exposed and approved. Trust your MCP servers: `restrict mcp`
+controls tool access, not a server's internal filesystem/network operations. Other restriction kinds do
+not sandbox MCP server processes or their configured connections.
 
 ## Reproducibility
 
@@ -125,6 +165,7 @@ syntax is checked by `tests/examples.test.ts`; `triage-issues` is also run on Co
 | Script | Shows |
 |--------|-------|
 | `commit-message.spl` | `shell` under `restrict exec 'git'`, validation helper, retry loop |
+| `mcp.spl` | MCP search via `--mcp`, combined filesystem/exec/MCP restrictions |
 | `triage-issues.spl` | `fmt='object'` + `assert` validation with feedback retries, aggregation, summary |
 | `extract-invoice.spl` | structured extraction cross-checked with arithmetic before it is accepted |
 | `code-review.spl` | `think` then structure, `restrict` on read and on write, `fail` as a CI gate |

package/dist/ast.d.ts

@@ -83,7 +83,7 @@ export interface ThinkMods {
     show?: boolean;
 }
 export type ToolName = 'read_file' | 'write_file' | 'web_fetch' | 'web_search' | 'shell';
-export type RestrictKind = 'fs' | 'net' | 'exec';
+export type RestrictKind = 'fs' | 'net' | 'exec' | 'mcp';
 export type AssignTarget = {
     t: 'name';
     name: string;
@@ -162,8 +162,10 @@ export type Stmt = Base & ({
     body: Stmt[];
 } | {
     t: 'restrict';
-    kind: RestrictKind;
-    arg: Expr;
+    clauses: {
+        kind: RestrictKind;
+        arg: Expr;
+    }[];
     body: Stmt[];
 });
 export interface Directives {

package/dist/cli.js

@@ -10,6 +10,7 @@ import { parse } from './parser.js';
 import { run } from './interpreter.js';
 import { JsonFileStore, MemoryStore, loadStoreModule } from './store.js';
 import { toJson } from './values.js';
+import { loadMcpConfig } from './mcp.js';
 const HELP = `spl - Semantic Prompt Language interpreter
 
 Usage: spl <script.spl> [options]
@@ -18,13 +19,15 @@ Usage: spl <script.spl> [options]
 
 Options:
   --log-level <level>     error | info | debug (default: info). Logs go to stderr.
+                          All levels include LLM transcripts and [deterministic] statement traces.
   --silent                suppress all logs; only the result is printed
   --model <id>            model override (takes precedence over @{model=...})
+  --mcp <file.json>       MCP servers in VS Code mcp.json format
   --store <file.json>     persist top-level variables in a JSON file
   --store-module <path>   custom variable store: module exporting createStore() -> { load(), save(vars) }
   --timeout <seconds>     per LLM call timeout (default: 300)
   --cwd <dir>             base directory for relative paths and restrictions (default: current directory)
-  --check                 parse the script and exit
+  --check                 validate script syntax and any --mcp config without executing
   -v, --version           print version
   -h, --help              print this help
 
@@ -72,6 +75,7 @@ async function main() {
                 'log-level': { type: 'string' },
                 silent: { type: 'boolean' },
                 model: { type: 'string' },
+                mcp: { type: 'string' },
                 store: { type: 'string' },
                 'store-module': { type: 'string' },
                 timeout: { type: 'string' },
@@ -130,6 +134,13 @@ async function main() {
         }
         throw e;
     }
+    let mcpServers;
+    try {
+        mcpServers = values.mcp ? loadMcpConfig(values.mcp, cwd) : undefined;
+    }
+    catch (e) {
+        return usageError(e.message);
+    }
     if (values.check)
         return 0;
     let store;
@@ -139,7 +150,7 @@ async function main() {
     catch (e) {
         return usageError(e.message);
     }
-    const backend = new CopilotBackend({ logger, cwd, timeoutMs: timeoutSec * 1000 });
+    const backend = new CopilotBackend({ logger, cwd, timeoutMs: timeoutSec * 1000, mcpServers });
     try {
         const result = await run(program, { backend, logger, store, cwd, model: values.model });
         if (result.status === 'failure') {

package/dist/copilot.d.ts

@@ -3,10 +3,12 @@ import { Failure } from './errors.js';
 import { type LlmBackend, type LlmRequest, type LlmResponse } from './llm.js';
 import type { Logger } from './logger.js';
 import type { Restrictions } from './restrict.js';
+import { type McpServers } from './mcp.js';
 export interface CopilotBackendOptions {
     logger: Logger;
     cwd: string;
     timeoutMs: number;
+    mcpServers?: McpServers;
 }
 export declare class CopilotBackend implements LlmBackend {
     private readonly opts;
@@ -23,7 +25,7 @@ export declare class CopilotBackend implements LlmBackend {
     close(): Promise<void>;
 }
 /**
- * Hard enforcement at the permission layer. Only the five runtime tools are exposed to the model, so any
- * other request is denied; requests that would violate a restriction are additionally reported as violations.
+ * Only runtime tools and explicitly configured MCP tools are approved.
+ * Requests that violate a restriction are additionally reported as violations.
  */
-export declare function decidePermission(r: PermissionRequest, restrictions: Restrictions, block: (f: Failure) => void): PermissionRequestResult;
+export declare function decidePermission(r: PermissionRequest, restrictions: Restrictions, block: (f: Failure) => void, mcpServers?: McpServers): PermissionRequestResult;

package/dist/copilot.js

@@ -3,10 +3,11 @@ import { loadToken } from './auth.js';
 import { Failure } from './errors.js';
 import { LlmError } from './llm.js';
 import { TOOL_SPECS } from './tools.js';
+import { configuredMcpTool, filterMcpServers } from './mcp.js';
 const SYSTEM_MESSAGE = [
     'You are the execution engine of an automated script. Your reply is stored in a variable and used by the program.',
     'Reply with exactly what was asked for: no preamble, no sign-off, no commentary.',
-    'Use the provided tools (read_file, write_file, web_fetch, web_search, shell) only when the task needs them. No other tools exist.',
+    'Use the provided runtime tools and configured MCP tools only when the task needs them.',
 ].join(' ');
 const TOOL_NAMES = Object.keys(TOOL_SPECS);
 export class CopilotBackend {
@@ -100,13 +101,15 @@ export class CopilotBackend {
                 },
             });
         });
+        const mcpServers = filterMcpServers(this.opts.mcpServers ?? {}, req.restrictions);
         const baseConfig = {
             model: req.model,
             tools,
-            availableTools: TOOL_NAMES,
+            availableTools: [...TOOL_NAMES, ...Object.keys(mcpServers).map((name) => `mcp:${name}-*`)],
+            mcpServers,
             systemMessage: { mode: 'append', content: SYSTEM_MESSAGE },
             workingDirectory: this.opts.cwd,
-            onPermissionRequest: (r) => decidePermission(r, req.restrictions, block),
+            onPermissionRequest: (r) => decidePermission(r, req.restrictions, block, mcpServers),
         };
         try {
             try {
@@ -160,11 +163,17 @@ export class CopilotBackend {
     }
 }
 /**
- * Hard enforcement at the permission layer. Only the five runtime tools are exposed to the model, so any
- * other request is denied; requests that would violate a restriction are additionally reported as violations.
+ * Only runtime tools and explicitly configured MCP tools are approved.
+ * Requests that violate a restriction are additionally reported as violations.
  */
-export function decidePermission(r, restrictions, block) {
+export function decidePermission(r, restrictions, block, mcpServers = {}) {
     try {
+        if (r.kind === 'mcp') {
+            restrictions.checkMcp(r.serverName, r.toolName);
+            if (configuredMcpTool(mcpServers, r.serverName, r.toolName))
+                return { kind: 'approve-once' };
+            return { kind: 'reject', feedback: 'MCP server/tool is not enabled by --mcp configuration.' };
+        }
         if (r.kind === 'custom-tool' && TOOL_NAMES.includes(r.toolName)) {
             return { kind: 'approve-once' }; // the tool itself performs the restriction checks
         }
@@ -188,5 +197,5 @@ export function decidePermission(r, restrictions, block) {
             return { kind: 'reject', feedback: JSON.stringify(e.payload()) };
         }
     }
-    return { kind: 'reject', feedback: 'Only the read_file, write_file, web_fetch, web_search and shell tools may be used.' };
+    return { kind: 'reject', feedback: 'Only runtime tools and configured MCP tools may be used.' };
 }

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { run, type RunOptions, type RunResult } from './interpreter.js';
 export { Failure, SplSyntaxError, type FailurePayload, type StatusCode } from './errors.js';
 export { Logger, type LogLevel } from './logger.js';
 export { CopilotBackend } from './copilot.js';
+export { loadMcpConfig, type McpServers } from './mcp.js';
 export { login, logout, authStatus, AuthError } from './auth.js';
 export { JsonFileStore, MemoryStore, loadStoreModule, type VariableStore } from './store.js';
 export type { LlmBackend, LlmRequest, LlmResponse } from './llm.js';

package/dist/index.js

@@ -3,5 +3,6 @@ export { run } from './interpreter.js';
 export { Failure, SplSyntaxError } from './errors.js';
 export { Logger } from './logger.js';
 export { CopilotBackend } from './copilot.js';
+export { loadMcpConfig } from './mcp.js';
 export { login, logout, authStatus, AuthError } from './auth.js';
 export { JsonFileStore, MemoryStore, loadStoreModule } from './store.js';

package/dist/interpreter.js

@@ -86,6 +86,7 @@ class Interpreter {
     }
     async execStmt(s, env) {
         try {
+            this.opts.logger.deterministic(`line ${s.line} (${s.t}): ${this.program.lines[s.line - 1]?.trim() ?? ''}`);
             return await this.execStmtInner(s, env);
         }
         catch (e) {
@@ -189,11 +190,13 @@ class Interpreter {
                 }
             }
             case 'restrict': {
-                const restriction = makeRestriction(s.kind, await this.eval(s.arg, env), this.cwd);
                 const saved = this.restrictions;
-                this.restrictions = saved.with(restriction);
-                this.opts.logger.debug(`restrict ${s.kind}: ${restriction.values.join(', ')}`);
                 try {
+                    for (const clause of s.clauses) {
+                        const restriction = makeRestriction(clause.kind, await this.eval(clause.arg, env), this.cwd);
+                        this.restrictions = this.restrictions.with(restriction);
+                        this.opts.logger.debug(`restrict ${clause.kind}: ${restriction.values.join(', ')}`);
+                    }
                     return await this.execBlock(s.body, env);
                 }
                 finally {
@@ -499,12 +502,12 @@ class Interpreter {
             tools: new ToolHost(this.restrictions, this.cwd),
             pinned: c.pinned,
         };
-        logger.debug(`llm request (${c.kind}):\n${req.prompt}`);
+        logger.llm(`llm request (${c.kind}):\n${req.prompt}`);
         const started = Date.now();
         try {
             const res = await backend.call(req);
             logger.info(`llm ${c.kind} call: ${JSON.stringify(res.effective)} (${Date.now() - started} ms)`);
-            logger.debug(`llm response:\n${res.text}`);
+            logger.llm(`llm response:\n${res.text}`);
             return res.text.trim();
         }
         catch (e) {

package/dist/logger.d.ts

@@ -9,4 +9,7 @@ export declare class Logger {
     warn(msg: string): void;
     info(msg: string): void;
     debug(msg: string): void;
+    /** LLM transcripts are visible at every non-silent level, without labeling them as errors. */
+    llm(msg: string): void;
+    deterministic(msg: string): void;
 }

package/dist/logger.js

@@ -24,4 +24,11 @@ export class Logger {
     debug(msg) {
         this.emit('debug', 'debug', msg);
     }
+    /** LLM transcripts are visible at every non-silent level, without labeling them as errors. */
+    llm(msg) {
+        this.emit('error', 'llm', msg);
+    }
+    deterministic(msg) {
+        this.emit('error', 'deterministic', msg);
+    }
 }

package/dist/mcp.d.ts

@@ -0,0 +1,7 @@
+import type { MCPServerConfig } from '@github/copilot-sdk';
+import type { Restrictions } from './restrict.js';
+export type McpServers = Record<string, MCPServerConfig>;
+/** Loads the supported VS Code mcp.json subset; never executes commands or connects to servers. */
+export declare function loadMcpConfig(file: string, cwd: string): McpServers;
+export declare function filterMcpServers(servers: McpServers, restrictions: Restrictions): McpServers;
+export declare function configuredMcpTool(servers: McpServers, server: string, tool: string): boolean;

package/dist/mcp.js

@@ -0,0 +1,108 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Loads the supported VS Code mcp.json subset; never executes commands or connects to servers. */
+export function loadMcpConfig(file, cwd) {
+    const fail = (message) => { throw new Error(`MCP config '${file}': ${message}`); };
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        return fail(`cannot read JSON: ${e.message}`);
+    }
+    if (!object(config) || !object(config.servers))
+        return fail("expected an object with a 'servers' object");
+    if (config.inputs !== undefined)
+        return fail("'inputs' are not supported; use environment variables instead");
+    const expand = (value) => value.replace(/\$\{([^}]+)\}/g, (_, key) => {
+        if (key === 'workspaceFolder')
+            return cwd;
+        if (key.startsWith('env:')) {
+            const name = key.slice(4);
+            const value = process.env[name];
+            if (value !== undefined)
+                return value;
+            return fail(`environment variable '${name}' is not set`);
+        }
+        return fail(`unsupported variable '\${${key}}'`);
+    });
+    const strings = (value, field) => {
+        if (value === undefined)
+            return undefined;
+        if (!object(value))
+            return fail(`${field} must be an object of strings`);
+        const entries = Object.entries(value).map(([key, val]) => {
+            if (typeof val !== 'string')
+                return fail(`${field}.${key} must be a string`);
+            return [key, expand(val)];
+        });
+        return Object.fromEntries(entries);
+    };
+    const servers = Object.create(null);
+    for (const [name, raw] of Object.entries(config.servers)) {
+        if (!/^[A-Za-z0-9_.-]+$/.test(name))
+            return fail(`invalid server name '${name}'`);
+        if (!object(raw))
+            return fail(`server '${name}' must be an object`);
+        const type = raw.type ?? 'stdio';
+        const local = type === 'stdio';
+        if (!local && type !== 'http' && type !== 'sse')
+            return fail(`server '${name}' has unsupported type '${String(type)}'`);
+        const fields = local ? ['type', 'command', 'args', 'env', 'cwd', 'tools', 'timeout'] : ['type', 'url', 'headers', 'tools', 'timeout'];
+        for (const field of Object.keys(raw)) {
+            if (!fields.includes(field))
+                return fail(`server '${name}' has unsupported field '${field}'`);
+        }
+        if (raw.tools !== undefined && (!Array.isArray(raw.tools) || raw.tools.some((t) => typeof t !== 'string' || !/^(?:\*|[A-Za-z0-9_.-]+)$/.test(t)))) {
+            return fail(`server '${name}': tools must be an array of tool names or '*'`);
+        }
+        if (raw.timeout !== undefined && (typeof raw.timeout !== 'number' || !Number.isFinite(raw.timeout) || raw.timeout <= 0)) {
+            return fail(`server '${name}': timeout must be a positive number of milliseconds`);
+        }
+        const common = { tools: raw.tools, timeout: raw.timeout };
+        if (local) {
+            if (typeof raw.command !== 'string' || raw.command.trim() === '')
+                return fail(`server '${name}': command must be a non-empty string`);
+            if (raw.args !== undefined && (!Array.isArray(raw.args) || raw.args.some((v) => typeof v !== 'string'))) {
+                return fail(`server '${name}': args must be an array of strings`);
+            }
+            if (raw.cwd !== undefined && typeof raw.cwd !== 'string')
+                return fail(`server '${name}': cwd must be a string`);
+            servers[name] = {
+                ...common, type: 'stdio', command: expand(raw.command),
+                args: raw.args?.map(expand),
+                env: strings(raw.env, `${name}.env`),
+                workingDirectory: raw.cwd === undefined ? cwd : path.resolve(cwd, expand(raw.cwd)),
+            };
+        }
+        else {
+            if (typeof raw.url !== 'string')
+                return fail(`server '${name}': url must be a string`);
+            const url = expand(raw.url);
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                return fail(`server '${name}': invalid URL`);
+            }
+            if (!['http:', 'https:'].includes(parsed.protocol))
+                return fail(`server '${name}': URL must use http or https`);
+            servers[name] = { ...common, type, url, headers: strings(raw.headers, `${name}.headers`) };
+        }
+    }
+    return servers;
+}
+export function filterMcpServers(servers, restrictions) {
+    return Object.fromEntries(Object.entries(servers).flatMap(([name, config]) => {
+        const tools = restrictions.mcpTools(name, config.tools);
+        return tools.length ? [[name, { ...config, tools }]] : [];
+    }));
+}
+export function configuredMcpTool(servers, server, tool) {
+    if (!Object.hasOwn(servers, server))
+        return false;
+    const tools = servers[server].tools;
+    return tools === undefined || tools.includes('*') || tools.includes(tool);
+}

package/dist/parser.js

@@ -355,14 +355,21 @@ class Parser {
     parseRestrict() {
         const line = this.tok.line;
         this.next();
-        let kind = 'fs';
-        const t = this.tok;
-        if (t.type === 'name' && (t.value === 'fs' || t.value === 'net' || t.value === 'exec')) {
-            kind = t.value;
+        const clauses = [];
+        for (;;) {
+            let kind = 'fs';
+            const t = this.tok;
+            if (t.type === 'name' && (t.value === 'fs' || t.value === 'net' || t.value === 'exec' || t.value === 'mcp')) {
+                kind = t.value;
+                this.next();
+            }
+            clauses.push({ kind, arg: this.parseExpr() });
+            if (!this.isOp(','))
+                break;
             this.next();
+            this.skipNl();
         }
-        const arg = this.parseExpr();
-        return { t: 'restrict', line, kind, arg, body: this.parseBlock() };
+        return { t: 'restrict', line, clauses, body: this.parseBlock() };
     }
     parseSimpleStatement() {
         const line = this.tok.line;

package/dist/restrict.d.ts

@@ -20,6 +20,9 @@ export declare class Restrictions {
     checkUrl(url: string): URL;
     checkHost(host: string): void;
     checkExec(name: string): void;
+    checkMcp(server: string, tool: string): void;
+    /** Narrows configured tools before the SDK starts servers or advertises their tools. */
+    mcpTools(server: string, configured?: readonly string[]): string[];
     /** Human-readable guidance for the LLM (the first enforcement layer). */
     guidance(): string[];
 }

package/dist/restrict.js

@@ -127,6 +127,24 @@ export class Restrictions {
             }
         }
     }
+    checkMcp(server, tool) {
+        for (const r of this.list) {
+            if (r.kind === 'mcp' && !r.values.some((v) => v === server || v === `${server}/*` || v === `${server}/${tool}`)) {
+                throw violation(`MCP tool '${server}/${tool}' blocked: allowed MCP servers/tools are ${r.values.join(', ')}`);
+            }
+        }
+    }
+    /** Narrows configured tools before the SDK starts servers or advertises their tools. */
+    mcpTools(server, configured = ['*']) {
+        let tools = [...configured];
+        for (const r of this.list) {
+            if (r.kind !== 'mcp' || r.values.includes(server) || r.values.includes(`${server}/*`))
+                continue;
+            const allowed = r.values.filter((v) => v.startsWith(`${server}/`)).map((v) => v.slice(server.length + 1));
+            tools = tools.includes('*') ? allowed : tools.filter((t) => allowed.includes(t));
+        }
+        return [...new Set(tools)];
+    }
     /** Human-readable guidance for the LLM (the first enforcement layer). */
     guidance() {
         return this.list.map((r) => {
@@ -134,7 +152,9 @@ export class Restrictions {
                 return `File system: you may read and write only inside: ${r.values.join(', ')}. Any other path will be blocked.`;
             if (r.kind === 'net')
                 return `Network: you may only access these hosts: ${r.values.join(', ')}. Any other host will be blocked.`;
-            return `Shell: you may only run these executables: ${r.values.join(', ')}, one simple command at a time (no pipes, redirects or chaining). Anything else will be blocked.`;
+            if (r.kind === 'mcp')
+                return `MCP: you may only call these servers/tools: ${r.values.join(', ')}. Anything else will be blocked.`;
+            return `Shell: you may only run these executables: ${r.values.join(', ')}. Anything else will be blocked.`;
         });
     }
 }
@@ -154,5 +174,11 @@ export function makeRestriction(kind, raw, cwd) {
         return { kind, values: [...new Set(items.map((i) => canonicalPath(i, cwd)))] };
     if (kind === 'net')
         return { kind, values: [...new Set(items.map(normalizeHost))] };
+    if (kind === 'mcp') {
+        if (items.some((v) => !/^[A-Za-z0-9_.-]+(?:\/(?:[A-Za-z0-9_.-]+|\*))?$/.test(v))) {
+            throw new Failure('runtime_error', 'restrict mcp expects server names or server/tool selectors');
+        }
+        return { kind, values: [...new Set(items)] };
+    }
     return { kind, values: [...new Set(items.map(normalizeExec))] };
 }

package/dist/tools.d.ts

@@ -12,6 +12,10 @@ export interface ToolSpec {
 export declare const TOOL_SPECS: Record<ToolName, ToolSpec>;
 /** Splits a simple command line, honoring '...' and "..." quoting. No escapes, no expansion. */
 export declare function splitCommand(command: string): string[];
+/** Splits a command string by chain/pipeline separators (&&, ||, |, ;, &, \n) outside quotes. */
+export declare function splitChainedCommands(command: string): string[];
+/** Finds nested $(...) or `...` command substitutions outside single quotes. */
+export declare function extractSubstitutions(command: string): string[];
 export interface SearchResult {
     title: string;
     url: string;
@@ -34,5 +38,7 @@ export declare class ToolHost {
     /** Searches DuckDuckGo's HTML endpoint (no API key); it is a network call, so `restrict net` applies to it. */
     private webSearch;
     private shell;
+    private checkCommandRestrictions;
+    private checkSubcommand;
     private run;
 }

package/dist/tools.js

@@ -6,8 +6,6 @@ const MAX_TEXT = 200_000;
 const SHELL_TIMEOUT_MS = 120_000;
 const FETCH_TIMEOUT_MS = 30_000;
 const MAX_REDIRECTS = 5;
-/** Characters that let a command chain, redirect or substitute; rejected while any restriction is active. */
-const SHELL_META = /[&|;<>`$()\r\n^%!]/;
 export const TOOL_SPECS = {
     read_file: {
         name: 'read_file',
@@ -86,6 +84,127 @@ export function splitCommand(command) {
         args.push(cur);
     return args;
 }
+function findMatchingParen(str, openIndex) {
+    let depth = 0;
+    for (let i = openIndex; i < str.length; i++) {
+        if (str[i] === '(')
+            depth++;
+        else if (str[i] === ')') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** Splits a command string by chain/pipeline separators (&&, ||, |, ;, &, \n) outside quotes. */
+export function splitChainedCommands(command) {
+    const subcmds = [];
+    let cur = '';
+    let quote;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote)
+                quote = undefined;
+            cur += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            cur += ch;
+        }
+        else if (ch === '\n' || ch === ';') {
+            if (cur.trim())
+                subcmds.push(cur.trim());
+            cur = '';
+        }
+        else if (ch === '&' && command[i + 1] === '&') {
+            if (cur.trim())
+                subcmds.push(cur.trim());
+            cur = '';
+            i++;
+        }
+        else if (ch === '|' && command[i + 1] === '|') {
+            if (cur.trim())
+                subcmds.push(cur.trim());
+            cur = '';
+            i++;
+        }
+        else if (ch === '|') {
+            if (cur.trim())
+                subcmds.push(cur.trim());
+            cur = '';
+        }
+        else if (ch === '&') {
+            const prevNonSpace = cur.trimEnd().slice(-1);
+            if (prevNonSpace === '>') {
+                cur += ch;
+            }
+            else {
+                if (cur.trim())
+                    subcmds.push(cur.trim());
+                cur = '';
+            }
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (quote)
+        throw new Failure('restriction_violation', 'shell command rejected: unterminated quote');
+    if (cur.trim())
+        subcmds.push(cur.trim());
+    return subcmds;
+}
+/** Finds nested $(...) or `...` command substitutions outside single quotes. */
+export function extractSubstitutions(command) {
+    const subs = [];
+    let quote;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote === "'") {
+            if (ch === "'")
+                quote = undefined;
+        }
+        else if (quote === '"') {
+            if (ch === '"') {
+                quote = undefined;
+            }
+            else if (ch === '`') {
+                const end = command.indexOf('`', i + 1);
+                if (end !== -1) {
+                    subs.push(command.slice(i + 1, end));
+                    i = end;
+                }
+            }
+            else if (ch === '$' && command[i + 1] === '(') {
+                const end = findMatchingParen(command, i + 1);
+                if (end !== -1) {
+                    subs.push(command.slice(i + 2, end));
+                    i = end;
+                }
+            }
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+        }
+        else if (ch === '`') {
+            const end = command.indexOf('`', i + 1);
+            if (end !== -1) {
+                subs.push(command.slice(i + 1, end));
+                i = end;
+            }
+        }
+        else if (ch === '$' && command[i + 1] === '(') {
+            const end = findMatchingParen(command, i + 1);
+            if (end !== -1) {
+                subs.push(command.slice(i + 2, end));
+                i = end;
+            }
+        }
+    }
+    return subs;
+}
 const SEARCH_ENDPOINT = 'https://html.duckduckgo.com/html/';
 const MAX_SEARCH_RESULTS = 10;
 const decodeEntities = (s) => s
@@ -121,6 +240,10 @@ export function parseSearchResults(html) {
 }
 const looksLikeUrl = (s) => /^[a-z][a-z0-9+.-]*:\/\//i.test(s);
 const looksLikePath = (s) => /[\\/]/.test(s) || s.startsWith('.') || s.startsWith('~') || /^[a-z]:/i.test(s);
+function isDirSwitch(executable, arg) {
+    return process.platform === 'win32' && executable.toLowerCase() === 'dir'
+        && /^\/(?:-?[bcdlnpqrswx4]|[aot](?::[a-z-]+)?)$/i.test(arg);
+}
 /**
  * Executes the built-in tools. Every call is checked against the active restrictions,
  * whether it comes from the script itself or from the LLM.
@@ -209,17 +332,77 @@ export class ToolHost {
         return results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}${r.snippet ? `\n   ${r.snippet}` : ''}`).join('\n');
     }
     async shell(command) {
-        if (!this.restrictions.active)
-            return this.run(command, { shell: true });
-        // With any restriction active only plain commands are accepted, so the checks below are exact.
-        if (SHELL_META.test(command)) {
-            throw new Failure('restriction_violation', 'shell command rejected: chaining, redirection and substitution are not allowed inside a restrict block');
+        if (!command || command.trim() === '')
+            throw new Failure('tool_error', 'shell: empty command');
+        if (this.restrictions.active) {
+            try {
+                this.checkCommandRestrictions(command);
+            }
+            catch (e) {
+                if (e instanceof Failure && e.statusCode === 'restriction_violation') {
+                    throw new Failure('restriction_violation', `${e.reason} (shell command: ${JSON.stringify(command)})`);
+                }
+                throw e;
+            }
         }
-        const argv = splitCommand(command);
-        if (argv.length === 0)
+        return this.run(command, { shell: true });
+    }
+    checkCommandRestrictions(command) {
+        const subcmds = splitChainedCommands(command);
+        if (subcmds.length === 0)
             throw new Failure('tool_error', 'shell: empty command');
-        this.restrictions.checkExec(argv[0]);
-        for (const arg of argv.slice(1)) {
+        for (const sub of subcmds) {
+            this.checkSubcommand(sub);
+        }
+        for (const sub of extractSubstitutions(command)) {
+            this.checkCommandRestrictions(sub);
+        }
+    }
+    checkSubcommand(subcmd) {
+        const argv = splitCommand(subcmd);
+        if (argv.length === 0)
+            return;
+        let execIdx = 0;
+        while (execIdx < argv.length && /^[a-zA-Z_][a-zA-Z0-9_]*=/.test(argv[execIdx])) {
+            execIdx++;
+        }
+        if (execIdx >= argv.length)
+            return;
+        const exe = argv[execIdx].replace(/^[()]+/, '').replace(/[()]+$/, '');
+        if (exe)
+            this.restrictions.checkExec(exe);
+        for (let i = execIdx + 1; i < argv.length; i++) {
+            const arg = argv[i];
+            if (arg === '>' || arg === '>>' || arg === '1>' || arg === '2>') {
+                const target = argv[++i];
+                if (target && !target.startsWith('&') && this.restrictions.has('fs')) {
+                    this.restrictions.checkPath(target, 'write');
+                }
+                continue;
+            }
+            if (arg === '<' || arg === '0<') {
+                const target = argv[++i];
+                if (target && this.restrictions.has('fs')) {
+                    this.restrictions.checkPath(target, 'read');
+                }
+                continue;
+            }
+            if (/^[0-9]?>+/.test(arg)) {
+                const target = arg.replace(/^[0-9]?>+/, '');
+                if (target && !target.startsWith('&') && this.restrictions.has('fs')) {
+                    this.restrictions.checkPath(target, 'write');
+                }
+                continue;
+            }
+            if (/^[0-9]?<+/.test(arg)) {
+                const target = arg.replace(/^[0-9]?<+/, '');
+                if (target && this.restrictions.has('fs')) {
+                    this.restrictions.checkPath(target, 'read');
+                }
+                continue;
+            }
+            if (isDirSwitch(exe, arg))
+                continue;
             const value = arg.startsWith('-') && arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : arg;
             if (looksLikeUrl(value)) {
                 if (this.restrictions.has('net'))
@@ -229,14 +412,6 @@ export class ToolHost {
                 this.restrictions.checkPath(value, 'read');
             }
         }
-        if (argv.some((a) => a.includes('"'))) {
-            throw new Failure('restriction_violation', 'shell command rejected: embedded double quotes are not allowed inside a restrict block');
-        }
-        if (process.platform === 'win32') {
-            // .cmd shims (npm, ...) need a shell on Windows; metacharacters were already rejected.
-            return this.run(argv.map((a) => (/\s/.test(a) || a === '' ? `"${a}"` : a)).join(' '), { shell: true });
-        }
-        return this.run(argv[0], { shell: false, args: argv.slice(1) });
     }
     run(command, opts) {
         return new Promise((resolve, reject) => {

package/docs/syntax.ebnf

@@ -35,7 +35,8 @@ fail_stmt      = "fail" , expr ;
 success_stmt   = "success" , [ expr ] ;
 
 constraint_stmt = ( "enforce" | "forbid" ) , expr , block ;
-restrict_stmt   = "restrict" , [ "fs" | "net" | "exec" ] , expr , block ;  (* default kind: fs *)
+restrict_stmt   = "restrict" , restrict_clause , { "," , restrict_clause } , block ;
+restrict_clause = [ "fs" | "net" | "exec" | "mcp" ] , expr ;  (* default kind: fs; clauses intersect *)
 
 (* Expressions, lowest to highest precedence *)
 expr           = or_expr , [ "if" , or_expr , "else" , expr ] ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spl-lang",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Semantic Prompt Language: a Python-like language with LLM calls built into the syntax",
   "type": "module",
   "main": "./dist/index.js",