@deepstrike/sdk 0.1.15 → 0.2.0

package/dist/providers/qwen.js

@@ -5,16 +5,19 @@ import { OpenAIChatAdapter } from "./openai-chat.js";
 import { endpointProfiles } from "./profiles.js";
 const QWEN_BASE = endpointProfiles["qwen.dashscope"].baseURL;
 const QWEN_POLICIES = {
-    "qwen-max": { maxTurns: 25 },
-    "qwen-plus": { maxTurns: 20 },
-    "qwen-turbo": { maxTurns: 15 },
-    "qwq-plus": { maxTurns: 40 },
-    "qwq-32b": { maxTurns: 35 },
-    "qwen3-235b-a22b": { maxTurns: 35 },
-    "qwen3-72b": { maxTurns: 25 },
-    "qwen3-32b": { maxTurns: 20 },
-    "qwen3-14b": { maxTurns: 15 },
-    "qwen3-8b": { maxTurns: 15 },
+    "qwen3.7-max-preview": { maxTurns: 45 },
+    "qwen3.7-plus-preview": { maxTurns: 40 },
+    "qwen3.6-max-preview": { maxTurns: 40 },
+    "qwen3.6-plus": { maxTurns: 35 },
+    "qwen3.6-flash": { maxTurns: 20 },
+    "qwen3.6-35b-a3b": { maxTurns: 25 },
+    "qwen3.6-27b": { maxTurns: 25 },
+    "qwen3.5-plus": { maxTurns: 35 },
+    "qwen3.5-flash": { maxTurns: 20 },
+    "qwen3.5-397b-a17b": { maxTurns: 35 },
+    "qwen3.5-122b-a10b": { maxTurns: 25 },
+    "qwen3.5-35b-a3b": { maxTurns: 20 },
+    "qwen3.5-27b": { maxTurns: 20 },
 };
 export class QwenProvider {
     model;
@@ -23,7 +26,7 @@ export class QwenProvider {
     maxRetries;
     baseDelay;
     chat = new OpenAIChatAdapter();
-    constructor(apiKey, model = "qwen-max", retry = { maxRetries: 3, baseDelay: 1000 }, baseURL = QWEN_BASE) {
+    constructor(apiKey, model = "qwen3.6-plus", retry = { maxRetries: 3, baseDelay: 1000 }, baseURL = QWEN_BASE) {
         this.model = model;
         this.client = withServerRuntimeGuard(() => new OpenAI({ apiKey, baseURL }));
         this.circuit = new CircuitBreaker();
@@ -33,6 +36,17 @@ export class QwenProvider {
     runtimePolicy() {
         return QWEN_POLICIES[this.model] ?? {};
     }
+    peekProviderReplay(message) {
+        const fields = this.chat.peekReplayFields(message);
+        if (!fields || !("reasoning_content" in fields))
+            return undefined;
+        return { reasoning_content: String(fields.reasoning_content ?? "") };
+    }
+    seedProviderReplay(message, replay) {
+        if (replay.reasoning_content !== undefined) {
+            this.chat.rememberReplayFields(message, { reasoning_content: replay.reasoning_content });
+        }
+    }
     async complete(context, tools, extensions) {
         if (this.circuit.isOpen())
             throw new Error("Circuit breaker open");
@@ -66,6 +80,8 @@ export class QwenProvider {
         const msgs = this.chat.buildMessages(context);
         const toolCallBufs = {};
         const emittedToolCallIndexes = new Set();
+        let reasoningContent = "";
+        let finalText = "";
         const extraBody = this.thinkingExtraBody(extensions);
         const stream = await this.client.chat.completions.create({
             ...this.requestExtensions(extensions),
@@ -86,10 +102,14 @@ export class QwenProvider {
             if (!choice)
                 continue;
             const delta = choice.delta;
-            if (delta.reasoning_content)
+            if (delta.reasoning_content) {
+                reasoningContent += String(delta.reasoning_content);
                 yield { type: "thinking_delta", delta: delta.reasoning_content };
-            if (delta.content)
+            }
+            if (delta.content) {
+                finalText += String(delta.content);
                 yield { type: "text_delta", delta: delta.content };
+            }
             for (const tc of delta.tool_calls ?? []) {
                 const idx = tc.index;
                 if (!toolCallBufs[idx])
@@ -99,6 +119,10 @@ export class QwenProvider {
                 toolCallBufs[idx].argsBuf += tc.function?.arguments ?? "";
             }
             if (choice.finish_reason === "tool_calls") {
+                const toolCalls = Object.values(toolCallBufs).map(tb => ({
+                    id: tb.id, name: tb.name, arguments: tb.argsBuf || "{}",
+                }));
+                this.chat.rememberReplayFields({ content: finalText, toolCalls }, { reasoning_content: reasoningContent });
                 for (const [index, tb] of Object.entries(toolCallBufs)) {
                     const idx = Number(index);
                     if (emittedToolCallIndexes.has(idx))
@@ -115,6 +139,12 @@ export class QwenProvider {
                 }
             }
         }
+        const toolCalls = Object.values(toolCallBufs).map(tb => ({
+            id: tb.id, name: tb.name, arguments: tb.argsBuf || "{}",
+        }));
+        if (toolCalls.length || reasoningContent) {
+            this.chat.rememberReplayFields({ content: finalText, toolCalls }, { reasoning_content: reasoningContent });
+        }
         for (const [index, tb] of Object.entries(toolCallBufs)) {
             const idx = Number(index);
             if (emittedToolCallIndexes.has(idx))

package/dist/runtime/archive.d.ts

@@ -0,0 +1,15 @@
+import type { Message } from "../types.js";
+export interface ArchiveStore {
+    write(sessionId: string, seq: number, messages: Message[]): Promise<string>;
+    read(archiveRef: string): Promise<Message[]>;
+}
+export declare class NullArchiveStore implements ArchiveStore {
+    write(_sessionId: string, _seq: number, _messages: Message[]): Promise<string>;
+    read(_archiveRef: string): Promise<Message[]>;
+}
+export declare class FileArchiveStore implements ArchiveStore {
+    private readonly root;
+    constructor(root: string);
+    write(sessionId: string, seq: number, messages: Message[]): Promise<string>;
+    read(archiveRef: string): Promise<Message[]>;
+}

package/dist/runtime/archive.js

@@ -0,0 +1,35 @@
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+export class NullArchiveStore {
+    async write(_sessionId, _seq, _messages) {
+        return "";
+    }
+    async read(_archiveRef) {
+        throw new Error("NullArchiveStore does not store archives");
+    }
+}
+export class FileArchiveStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async write(sessionId, seq, messages) {
+        const dir = join(this.root, sessionId);
+        await mkdir(dir, { recursive: true });
+        const filePath = join(dir, `${seq}.jsonl`);
+        const lines = messages.map(msg => JSON.stringify(msg)).join("\n") + "\n";
+        await writeFile(filePath, lines, "utf8");
+        return filePath;
+    }
+    async read(archiveRef) {
+        const content = await readFile(archiveRef, "utf8");
+        const lines = content.split("\n");
+        const messages = [];
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            messages.push(JSON.parse(line));
+        }
+        return messages;
+    }
+}

package/dist/runtime/execution-plane.js

@@ -23,7 +23,7 @@ export class LocalExecutionPlane {
                 ctx.governance.setTime?.(BigInt(Date.now()));
                 const v = ctx.governance.evaluate(c.name, c.arguments);
                 if (v.kind === "deny") {
-                    yield { type: "error", message: `permission denied: ${c.name} — ${v.reason ?? ""}` };
+                    yield { type: "tool_denied", callId: c.id, toolName: c.name, reason: v.reason ?? "" };
                     yield { type: "tool_result", callId: c.id, name: c.name, content: `permission denied: ${v.reason ?? ""}`, isError: true };
                     continue;
                 }
@@ -96,9 +96,19 @@ export class LocalExecutionPlane {
             return { callId: call.id, output: `unknown tool: ${call.name}`, isError: true };
         try {
             const args = JSON.parse(call.arguments || "{}");
-            const err = validateToolArguments(registered.schema.parameters, args);
-            if (err)
-                return { callId: call.id, output: `invalid arguments: ${err}`, isError: true };
+            const originalArgsStr = JSON.stringify(args);
+            const validation = validateToolArguments(registered.schema.parameters, args);
+            if (validation.error)
+                return { callId: call.id, output: `invalid arguments: ${validation.error}`, isError: true };
+            if (validation.repaired) {
+                yield {
+                    type: "tool_argument_repaired",
+                    callId: call.id,
+                    name: call.name,
+                    originalArguments: originalArgsStr,
+                    repairedArguments: JSON.stringify(args),
+                };
+            }
             const output = await registered.execute(args);
             if (isAsyncIterable(output)) {
                 let combined = "";

package/dist/runtime/filtered-plane.d.ts

@@ -0,0 +1,14 @@
+import type { ToolCall, ToolSchema, StreamEvent } from "../types.js";
+import type { RegisteredTool } from "../tools/index.js";
+import type { ExecutionPlane, RunContext } from "./execution-plane.js";
+/** Wraps an execution plane, allowing only manifest-permitted tool IDs (+ meta-tools). */
+export declare class FilteredExecutionPlane implements ExecutionPlane {
+    private readonly inner;
+    private readonly permittedIds;
+    private readonly metaTools;
+    constructor(inner: ExecutionPlane, permittedIds: Set<string>, metaTools?: Set<string>);
+    register(...tools: RegisteredTool[]): this;
+    unregister(name: string): this;
+    schemas(): ToolSchema[];
+    executeAll(calls: ToolCall[], ctx: RunContext): AsyncIterable<StreamEvent>;
+}

package/dist/runtime/filtered-plane.js

@@ -0,0 +1,45 @@
+const DEFAULT_META_TOOLS = new Set(["skill", "memory", "knowledge", "update_plan"]);
+/** Wraps an execution plane, allowing only manifest-permitted tool IDs (+ meta-tools). */
+export class FilteredExecutionPlane {
+    inner;
+    permittedIds;
+    metaTools;
+    constructor(inner, permittedIds, metaTools = DEFAULT_META_TOOLS) {
+        this.inner = inner;
+        this.permittedIds = permittedIds;
+        this.metaTools = metaTools;
+    }
+    register(...tools) {
+        this.inner.register(...tools);
+        return this;
+    }
+    unregister(name) {
+        this.inner.unregister(name);
+        return this;
+    }
+    schemas() {
+        return this.inner.schemas().filter(s => this.permittedIds.has(s.name) || this.metaTools.has(s.name));
+    }
+    async *executeAll(calls, ctx) {
+        const permitted = [];
+        for (const call of calls) {
+            if (this.metaTools.has(call.name) || this.permittedIds.has(call.name)) {
+                permitted.push(call);
+                continue;
+            }
+            const reason = `capability not permitted for sub-agent: ${call.name}`;
+            yield { type: "tool_denied", callId: call.id, toolName: call.name, reason };
+            yield {
+                type: "tool_result",
+                callId: call.id,
+                name: call.name,
+                content: reason,
+                isError: true,
+                errorKind: "governance_denied",
+            };
+        }
+        if (permitted.length > 0) {
+            yield* this.inner.executeAll(permitted, ctx);
+        }
+    }
+}

package/dist/runtime/kernel-step.d.ts

@@ -0,0 +1,88 @@
+import type { Message, RenderedContext, TaskUpdate, ToolCall, ToolResult, ToolSchema } from "../types.js";
+import type { SkillMetadata } from "../skills/loader.js";
+import type { RollbackReason } from "./session-log.js";
+export declare const KERNEL_ABI_VERSION = 1;
+export interface KernelRuntimeHandle {
+    step(inputJson: string): string;
+    isTerminal(): boolean;
+    turn(): number;
+    recoveryContentBytes(): number;
+    render(): RenderedContext;
+    drainNewMessages(): Message[];
+    preservedRefs(): string[];
+}
+export interface KernelLoopResult {
+    termination: string;
+    turnsUsed: number;
+    totalTokensUsed: number;
+}
+export type MilestoneVerifierKind = {
+    kind: "machine_check";
+} | {
+    kind: "harness_eval";
+} | {
+    kind: "llm_judge";
+} | {
+    kind: "human_approval";
+} | {
+    kind: "external_command";
+    cmd: string;
+};
+export type KernelRunnerAction = {
+    kind: "call_provider";
+    context: RenderedContext;
+    tools: ToolSchema[];
+} | {
+    kind: "execute_tool";
+    calls: ToolCall[];
+} | {
+    kind: "evaluate_milestone";
+    phaseId: string;
+    criteria: string[];
+    verifier?: MilestoneVerifierKind;
+    requiredEvidence: string[];
+} | {
+    kind: "done";
+    result: KernelLoopResult;
+};
+export interface KernelObservation {
+    kind: string;
+    action?: string;
+    rho_after?: number;
+    sprint?: number;
+    summary?: string;
+    archived?: Message[];
+    turn?: number;
+    checkpoint_history_len?: number;
+    history_len?: number;
+    added?: string[];
+    removed?: string[];
+    change_kind?: string;
+    capability_id?: string;
+    version?: string;
+    mounted_by?: string;
+    mount_reason?: string;
+    phase_id?: string;
+    capabilities_unlocked?: string[];
+    evidence?: string[];
+    reason?: RollbackReason;
+    agent_id?: string;
+    parent_session_id?: string;
+    role?: string;
+    isolation?: string;
+    context_inheritance?: string;
+    permitted_capability_ids?: string[];
+}
+export declare function toolSchemaToKernel(schema: ToolSchema): Record<string, unknown>;
+export declare function skillMetadataToKernel(skill: SkillMetadata): Record<string, unknown>;
+export declare function messageToKernelMessage(message: Message): Record<string, unknown>;
+export declare function toolResultToKernel(result: ToolResult): Record<string, unknown>;
+export declare function taskUpdateToKernel(update: TaskUpdate): Record<string, unknown>;
+export declare function capabilityTool(schema: ToolSchema): Record<string, unknown>;
+export declare function capabilitySkill(skill: SkillMetadata): Record<string, unknown>;
+export declare function capabilityMarker(kind: string, id: string, description: string): Record<string, unknown>;
+export declare function capabilityCommandMount(capability: Record<string, unknown>, mountedBy?: string, mountReason?: string): Record<string, unknown>;
+export declare function capabilityCommandUnmount(capabilityKind: string, id: string): Record<string, unknown>;
+export declare function kernelApply(runtime: KernelRuntimeHandle, pending: KernelObservation[], event: Record<string, unknown>): KernelObservation[];
+export declare function kernelAction(runtime: KernelRuntimeHandle, pending: KernelObservation[], event: Record<string, unknown>): KernelRunnerAction;
+export declare function forceCompact(runtime: KernelRuntimeHandle, pending: KernelObservation[]): boolean;

package/dist/runtime/kernel-step.js

@@ -0,0 +1,262 @@
+export const KERNEL_ABI_VERSION = 1;
+function tryParseJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}
+export function toolSchemaToKernel(schema) {
+    return {
+        name: schema.name,
+        description: schema.description,
+        parameters: tryParseJson(schema.parameters) ?? {},
+    };
+}
+export function skillMetadataToKernel(skill) {
+    const out = {
+        name: skill.name,
+        description: skill.description,
+        estimated_tokens: skill.estimatedTokens ?? 0,
+    };
+    if (skill.whenToUse)
+        out.when_to_use = skill.whenToUse;
+    if (skill.effort !== undefined)
+        out.effort = skill.effort;
+    return out;
+}
+export function messageToKernelMessage(message) {
+    const out = {
+        role: message.role,
+        tool_calls: (message.toolCalls ?? []).map(tc => ({
+            id: tc.id,
+            name: tc.name,
+            arguments: tryParseJson(tc.arguments) ?? {},
+        })),
+    };
+    if (message.tokenCount !== undefined) {
+        out.token_count = message.tokenCount;
+    }
+    if (message.contentParts && message.contentParts.length > 0) {
+        out.content = message.contentParts.map(part => {
+            if (part.type === "text")
+                return { type: "text", text: part.text };
+            if (part.type === "tool_result") {
+                return {
+                    type: "tool_result",
+                    call_id: part.callId,
+                    output: part.output,
+                    is_error: part.isError,
+                };
+            }
+            if (part.type === "image") {
+                return {
+                    type: "image",
+                    url: part.url,
+                    data: part.data,
+                    media_type: part.mediaType,
+                    detail: part.detail,
+                };
+            }
+            if (part.type === "audio") {
+                return { type: "audio", data: part.data, media_type: part.mediaType };
+            }
+            return { type: "text", text: message.content };
+        });
+    }
+    else {
+        out.content = message.content;
+    }
+    return out;
+}
+export function toolResultToKernel(result) {
+    const out = {
+        call_id: result.callId,
+        output: result.output,
+        is_error: result.isError,
+        is_fatal: result.isFatal ?? false,
+        token_count: result.tokenCount ?? null,
+    };
+    if (result.errorKind !== undefined) {
+        out.error_kind = result.errorKind;
+    }
+    return out;
+}
+export function taskUpdateToKernel(update) {
+    return {
+        plan: update.plan,
+        current_step: update.currentStep,
+        progress: update.progress,
+        scratchpad: update.scratchpad,
+        blocked_on: update.blockedOn,
+        preserved_refs: update.preservedRefs,
+    };
+}
+export function capabilityTool(schema) {
+    return {
+        id: schema.name,
+        kind: "tool",
+        description: schema.description,
+        tool_schema: toolSchemaToKernel(schema),
+    };
+}
+export function capabilitySkill(skill) {
+    return {
+        id: skill.name,
+        kind: "skill",
+        description: skill.description,
+        skill: skillMetadataToKernel(skill),
+    };
+}
+export function capabilityMarker(kind, id, description) {
+    return { id, kind, description };
+}
+export function capabilityCommandMount(capability, mountedBy = "sdk:runtime", mountReason = "dynamic_register") {
+    return {
+        kind: "capability_command",
+        command: {
+            action: "mount",
+            capability,
+            mounted_by: mountedBy,
+            mount_reason: mountReason,
+        },
+    };
+}
+export function capabilityCommandUnmount(capabilityKind, id) {
+    return {
+        kind: "capability_command",
+        command: { action: "unmount", kind: capabilityKind, id },
+    };
+}
+function parseStep(raw) {
+    return JSON.parse(raw);
+}
+function kernelMessageToSdk(raw) {
+    const content = raw.content;
+    const message = {
+        role: raw.role,
+        content: typeof content === "string"
+            ? content
+            : Array.isArray(content)
+                ? content
+                    .filter((part) => {
+                    return typeof part === "object" && part !== null && part.type === "text";
+                })
+                    .map(part => String(part.text ?? ""))
+                    .join("")
+                : "",
+        toolCalls: (raw.tool_calls ?? []).map(tc => ({
+            id: String(tc.id ?? ""),
+            name: String(tc.name ?? ""),
+            arguments: JSON.stringify(tc.arguments ?? {}),
+        })),
+    };
+    if (typeof raw.token_count === "number") {
+        message.tokenCount = raw.token_count;
+    }
+    if (Array.isArray(content)) {
+        message.contentParts = content
+            .filter((part) => typeof part === "object" && part !== null)
+            .map(part => {
+            if (part.type === "text") {
+                return { type: "text", text: String(part.text ?? "") };
+            }
+            if (part.type === "tool_result") {
+                return {
+                    type: "tool_result",
+                    callId: String(part.call_id ?? ""),
+                    output: String(part.output ?? ""),
+                    isError: Boolean(part.is_error),
+                };
+            }
+            if (part.type === "image") {
+                return {
+                    type: "image",
+                    url: part.url,
+                    data: part.data,
+                    mediaType: part.media_type,
+                    detail: part.detail,
+                };
+            }
+            if (part.type === "audio") {
+                return {
+                    type: "audio",
+                    data: String(part.data ?? ""),
+                    mediaType: String(part.media_type ?? "audio/wav"),
+                };
+            }
+            return { type: "text", text: "" };
+        });
+    }
+    return message;
+}
+function renderedContextToSdk(raw) {
+    return {
+        systemText: String(raw.system_text ?? raw.systemText ?? ""),
+        turns: (raw.turns ?? []).map(kernelMessageToSdk),
+    };
+}
+function mapKernelAction(raw) {
+    switch (raw.kind) {
+        case "call_provider":
+            return {
+                kind: "call_provider",
+                context: renderedContextToSdk(raw.context ?? {}),
+                tools: (raw.tools ?? []).map(t => ({
+                    name: String(t.name ?? ""),
+                    description: String(t.description ?? ""),
+                    parameters: JSON.stringify(t.parameters ?? {}),
+                })),
+            };
+        case "execute_tool":
+            return {
+                kind: "execute_tool",
+                calls: (raw.calls ?? []).map(c => ({
+                    id: String(c.id ?? ""),
+                    name: String(c.name ?? ""),
+                    arguments: JSON.stringify(c.arguments ?? {}),
+                })),
+            };
+        case "evaluate_milestone":
+            return {
+                kind: "evaluate_milestone",
+                phaseId: String(raw.phase_id ?? ""),
+                criteria: raw.criteria ?? [],
+                verifier: raw.verifier,
+                requiredEvidence: raw.required_evidence ?? [],
+            };
+        case "done": {
+            const result = raw.result ?? {};
+            return {
+                kind: "done",
+                result: {
+                    termination: String(result.termination ?? "error"),
+                    turnsUsed: Number(result.turns_used ?? 0),
+                    totalTokensUsed: Number(result.total_tokens_used ?? 0),
+                },
+            };
+        }
+        default:
+            throw new Error(`unknown KernelAction kind: ${String(raw.kind)}`);
+    }
+}
+function stepInput(event) {
+    return JSON.stringify({ version: KERNEL_ABI_VERSION, event });
+}
+export function kernelApply(runtime, pending, event) {
+    const step = parseStep(runtime.step(stepInput(event)));
+    pending.push(...step.observations);
+    return step.observations;
+}
+export function kernelAction(runtime, pending, event) {
+    const step = parseStep(runtime.step(stepInput(event)));
+    pending.push(...step.observations);
+    const raw = step.actions[0];
+    if (!raw)
+        throw new Error("kernel transition must return one action");
+    return mapKernelAction(raw);
+}
+export function forceCompact(runtime, pending) {
+    return kernelApply(runtime, pending, { kind: "force_compact" }).some(o => o.kind === "compressed");
+}

package/dist/runtime/process-sandbox-plane.d.ts

@@ -1,6 +1,6 @@
 import { LocalExecutionPlane } from "./execution-plane.js";
 export interface SandboxOptions {
-    /** Working directory for all subprocesses. Isolated from the rest of the file system by convention. */
+    /** Working directory for all subprocesses. This is not an OS-enforced filesystem boundary. */
     sandboxDir: string;
     /** Env var names from the host environment to forward into subprocesses. Default: none. */
     allowedEnvKeys?: string[];
@@ -10,14 +10,14 @@ export interface SandboxOptions {
     maxOutputBytes?: number;
 }
 /**
- * ExecutionPlane that confines subprocess execution to a sandbox directory.
+ * ExecutionPlane that runs subprocesses with a sandbox directory as cwd.
  * Extends LocalExecutionPlane with two built-in tools:
  *  - `run_bash`  — executes a bash command inside sandboxDir.
  *  - `run_node`  — evaluates a Node.js script inside sandboxDir.
  *
  * All registered JS tools continue to run in-process (identical to LocalExecutionPlane).
- * The sandboxing guarantee is: subprocesses spawned by the built-in tools cannot reach
- * files outside sandboxDir unless the host OS allows it.
+ * Subprocesses are launched with a stripped environment and sandboxDir as cwd;
+ * this is execution hygiene, not an OS-enforced filesystem sandbox.
  */
 export declare class ProcessSandboxPlane extends LocalExecutionPlane {
     private readonly sandboxDir;

package/dist/runtime/process-sandbox-plane.js

@@ -3,14 +3,14 @@ import { mkdir } from "node:fs/promises";
 import { tool } from "../tools/index.js";
 import { LocalExecutionPlane } from "./execution-plane.js";
 /**
- * ExecutionPlane that confines subprocess execution to a sandbox directory.
+ * ExecutionPlane that runs subprocesses with a sandbox directory as cwd.
  * Extends LocalExecutionPlane with two built-in tools:
  *  - `run_bash`  — executes a bash command inside sandboxDir.
  *  - `run_node`  — evaluates a Node.js script inside sandboxDir.
  *
  * All registered JS tools continue to run in-process (identical to LocalExecutionPlane).
- * The sandboxing guarantee is: subprocesses spawned by the built-in tools cannot reach
- * files outside sandboxDir unless the host OS allows it.
+ * Subprocesses are launched with a stripped environment and sandboxDir as cwd;
+ * this is execution hygiene, not an OS-enforced filesystem sandbox.
  */
 export class ProcessSandboxPlane extends LocalExecutionPlane {
     sandboxDir;
@@ -77,7 +77,7 @@ export class ProcessSandboxPlane extends LocalExecutionPlane {
         });
     }
     makeBashTool() {
-        return tool("run_bash", "Run a bash command confined to the sandbox directory. Paths outside the sandbox are not accessible.", {
+        return tool("run_bash", "Run a bash command with the sandbox directory as cwd and a stripped environment. This is not an OS-enforced filesystem sandbox.", {
             type: "object",
             properties: {
                 command: { type: "string", description: "The bash command to execute." },
@@ -92,7 +92,7 @@ export class ProcessSandboxPlane extends LocalExecutionPlane {
         });
     }
     makeNodeTool() {
-        return tool("run_node", "Evaluate a Node.js script confined to the sandbox directory.", {
+        return tool("run_node", "Evaluate a Node.js script with the sandbox directory as cwd and a stripped environment.", {
             type: "object",
             properties: {
                 code: { type: "string", description: "The JavaScript code to evaluate." },