@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/coding-tools.js

@@ -0,0 +1,875 @@
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { andorraCreateReadTool, andorraCreateWriteTool, andorraCreateEditTool, andorraCreateFindTool, andorraCreateGrepTool, andorraCreateLsTool, andorraCreateBashTool, andorraCreatePowerShellTool, } from '../vendor/engine/runtime/coding-agent/core/tools/index.js';
+import { andorraGetToolPath } from '../vendor/engine/runtime/coding-agent/utils/tools-manager.js';
+import { defaultShellKind, runShell, runNativeProcess } from './shell.js';
+import { commandTimingSummary } from './command-metrics.js';
+import { runPooledPowerShell } from './powershell-pool.js';
+import { getQaProcessManager } from './qa/runtime/ProcessManager.js';
+import { clipText } from './text.js';
+import { matchesFileRead, storeFileRead } from './file-read-state.js';
+import { FileReadRequiredError } from './tool-errors.js';
+import { permissionMode } from './permissions.js';
+import { withGrepRegex } from './grep-regex.js';
+const execFileAsync = promisify(execFile);
+const excluded = new Set(['.git', 'node_modules', '.andorracode']);
+const MAX_MODEL_OUTPUT = 24_000;
+/** Lines returned by one Read call: both the default and the accepted maximum for `limit`. */
+const READ_MAX_LINES = 2000;
+/** A single line longer than this is truncated, so one minified line cannot fill the window. */
+const READ_MAX_LINE_CHARS = 2000;
+const SEARCH_FILE_LIMIT = 262_144;
+const SEARCH_SCAN_LIMIT = 16 * 1024 * 1024;
+const sandboxFields = {
+    sandbox_permissions: { type: 'string', enum: ['use_default', 'require_escalated'], description: 'Use the workspace sandbox by default; require_escalated requests host/network access with approval.' },
+    justification: { type: 'string', description: 'Required explanation for an explicit escalation request.' },
+};
+async function shellPermission(policy, name, args, context) {
+    const requested = args.sandbox_permissions ?? 'use_default';
+    if (requested !== 'use_default' && requested !== 'require_escalated')
+        throw new Error('sandbox_permissions must be use_default or require_escalated');
+    if (args.justification !== undefined)
+        stringArg(args, 'justification', true);
+    if (requested === 'require_escalated' && (typeof args.justification !== 'string' || !args.justification.trim()))
+        throw new Error('Escalation requires a nonempty justification');
+    const mode = permissionMode(context);
+    let explicitlyApproved = false;
+    if (!mode || mode === 'full-access' || requested === 'require_escalated') {
+        await policy.authorize(name, { ...args, warning: 'UNSANDBOXED: entire host and network access.' }, {
+            ...context, approve: async (...approval) => {
+                const approved = await context.approve(...approval);
+                if (approved === true)
+                    explicitlyApproved = true;
+                return approved;
+            },
+        });
+    }
+    // Evaluate synchronously at spawn, after filesystem/launcher discovery awaits.
+    // Only a real per-call user grant can preserve unsandboxed execution when a
+    // previously automatic Full Access grant has since been revoked.
+    return () => {
+        const live = permissionMode(context);
+        if (explicitlyApproved)
+            return undefined;
+        // A later Full Access selection cannot create an unaudited host grant.
+        // Keep an initially restricted call restricted; a subsequent call can
+        // acquire Full Access through authorize and its journal events.
+        if (mode && mode !== 'full-access' && live === 'full-access')
+            return mode === 'read-only' ? 'read-only' : 'workspace-write';
+        if (!live || live === 'full-access')
+            return undefined;
+        return live === 'read-only' ? 'read-only' : 'workspace-write';
+    };
+}
+function nativeObservation(text, shell = false) {
+    if (text.length <= MAX_MODEL_OUTPUT)
+        return text;
+    let tail = text.slice(shell ? -23_000 : -1_000);
+    if (/^[\uDC00-\uDFFF]/u.test(tail))
+        tail = tail.slice(1);
+    const notice = '\n[Output clipped to fit the agent context; narrow the command/query or use Read with offset/limit.]\n';
+    return shell ? notice + tail : clipText(text, 22_000) + notice + tail;
+}
+function validateArguments(args, schema) {
+    const properties = schema.properties;
+    for (const key of Object.keys(args))
+        if (!(key in properties))
+            throw new Error(`Unknown argument: ${key}`);
+    for (const key of (schema.required ?? []))
+        if (!(key in args))
+            throw new Error(`Missing argument: ${key}`);
+    for (const [key, value] of Object.entries(args)) {
+        const type = properties[key]?.type;
+        if (type === 'string' && (typeof value !== 'string' || value.includes('\0')))
+            throw new Error(`${key} must be a string without NUL bytes`);
+        if (type === 'boolean' && typeof value !== 'boolean')
+            throw new Error(`${key} must be a boolean`);
+        if (type === 'number' && (typeof value !== 'number' || !Number.isSafeInteger(value) || value < (key === 'context' ? 0 : 1)))
+            throw new Error(`${key} must be a ${key === 'context' ? 'nonnegative' : 'positive'} safe integer`);
+    }
+    if ('path' in args && (typeof args.path !== 'string' || !args.path))
+        throw new Error('path must be nonempty');
+    if ('edits' in args && (!Array.isArray(args.edits) || !args.edits.length || args.edits.some(edit => !edit || typeof edit.oldText !== 'string' || !edit.oldText || typeof edit.newText !== 'string' || edit.oldText.includes('\0') || edit.newText.includes('\0'))))
+        throw new Error('edits must contain nonempty oldText and string newText replacements');
+}
+const stringArg = (args, key, optional = false) => {
+    const value = args[key];
+    if (value === undefined && optional)
+        return undefined;
+    if (typeof value !== 'string' || (!optional && !value.length) || value.includes('\0'))
+        throw new Error(`${key} must be ${optional ? 'a string' : 'a nonempty string'} without NUL bytes`);
+    return value;
+};
+const intArg = (args, key, options = {}) => {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < (options.min ?? 0) || value > (options.max ?? Number.MAX_SAFE_INTEGER))
+        throw new Error(`${key} must be an integer from ${options.min ?? 0} to ${options.max ?? Number.MAX_SAFE_INTEGER}`);
+    return value;
+};
+const boolArg = (args, key) => {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new Error(`${key} must be a boolean`);
+    return value;
+};
+/**
+ * Key for the per-context file-read state.
+ *
+ * Exported so other producers of the same state (the CodeGraph complete-source seed) store
+ * entries under the key the canonical tools look up. It must be applied to a path normalized
+ * the same way the policy's safePath normalizes it, or the entries never match.
+ */
+export function stateKey(resolved) {
+    const key = path.resolve(resolved);
+    return process.platform === 'win32' ? key.toLowerCase() : key;
+}
+function state(context) {
+    context.toolState ??= { fileReads: new Map() };
+    return context.toolState;
+}
+async function remember(context, resolved, content, complete, source) {
+    const info = await stat(resolved).catch(() => undefined);
+    storeFileRead(state(context), stateKey(resolved), {
+        path: resolved, content, complete,
+        sizeBytes: info?.size ?? Buffer.byteLength(content),
+        ...(info ? { mtimeMs: info.mtimeMs } : {}),
+        source,
+    });
+}
+async function rememberReadRange(context, resolved, content, start, end, lineCount) {
+    const key = stateKey(resolved);
+    const prior = state(context).fileReads.get(key);
+    // Successful mutations and complete CodeGraph source are also full snapshots.
+    // A narrow Read of identical content must not revoke their existing coverage.
+    // Changed bytes invalidate all prior ranges, regardless of snapshot origin.
+    const ranges = prior && matchesFileRead(prior, content) ? (prior.complete ? [{ start: 1, end: lineCount }] : [...(prior.ranges ?? [])]) : [];
+    if (lineCount === 0) {
+        await remember(context, resolved, content, true, 'Read');
+        return;
+    }
+    if (end >= start)
+        ranges.push({ start, end });
+    ranges.sort((a, b) => a.start - b.start || a.end - b.end);
+    const merged = [];
+    for (const range of ranges) {
+        const last = merged.at(-1);
+        if (last && range.start <= last.end + 1)
+            last.end = Math.max(last.end, range.end);
+        else
+            merged.push({ ...range });
+    }
+    const complete = merged.length === 1 && merged[0].start === 1 && merged[0].end >= lineCount;
+    const info = await stat(resolved).catch(() => undefined);
+    storeFileRead(state(context), key, {
+        path: resolved, content, complete,
+        sizeBytes: info?.size ?? Buffer.byteLength(content),
+        ...(info ? { mtimeMs: info.mtimeMs } : {}),
+        ...(complete ? {} : { ranges: merged, lineCount }),
+        source: 'Read',
+    });
+}
+/** First unread stretch of the file, for a partial observation. */
+function firstUnreadRange(previous) {
+    if (previous.complete)
+        return undefined;
+    const ranges = [...(previous.ranges ?? [])].sort((a, b) => a.start - b.start);
+    let next = 1;
+    for (const range of ranges) {
+        if (range.start > next)
+            break;
+        next = Math.max(next, range.end + 1);
+    }
+    const following = ranges.find(range => range.start > next);
+    const end = following ? following.start - 1 : previous.lineCount ?? next;
+    return { start: next, end };
+}
+async function requireFreshRead(policy, context, resolved, action) {
+    const previous = state(context).fileReads.get(stateKey(resolved));
+    if (!previous?.complete) {
+        // A suggested offset is only meaningful for the content the model last saw. Re-read first so
+        // a file that changed (or shrank) since that page cannot send the model past its end.
+        if (!previous)
+            throw new FileReadRequiredError(`${action} requires a complete Read (or complete CodeGraph source) of the existing file first. Read ${path.relative(context.workspace, resolved) || resolved} before modifying it.`);
+        if (!matchesFileRead(previous, await policy.read(context, resolved))) {
+            throw new FileReadRequiredError(`${action} refused a stale file: it changed since the last Read/CodeGraph snapshot. Read it again before modifying.`);
+        }
+        const unread = firstUnreadRange(previous);
+        const remaining = unread
+            ? ` ${unread.start === unread.end ? `Line ${unread.start} has` : `Lines ${unread.start}-${unread.end} have`} not been read yet; continue with Read offset=${unread.start}.`
+            : '';
+        throw new FileReadRequiredError(`${action} requires a complete Read (or complete CodeGraph source) of the existing file first. Read ${path.relative(context.workspace, resolved) || resolved} before modifying it.${remaining}`);
+    }
+    const current = await policy.read(context, resolved);
+    if (!matchesFileRead(previous, current))
+        throw new FileReadRequiredError(`${action} refused a stale file: it changed since the last Read/CodeGraph snapshot. Read it again before modifying.`);
+    return current;
+}
+function zTool(name, description, parameters, executionMode, execute) {
+    return { name, description, parameters, executionMode, execute };
+}
+export function createCodingTools(policy) {
+    function bound(context, beforeApproval) {
+        const { workspace, signal } = context;
+        const safe = (name, missing = false) => policy.safePath(context, name, missing);
+        const access = async (name) => { await safe(name); };
+        const read = (name) => policy.read(context, name);
+        const write = async (name, content, expected) => {
+            if (Buffer.byteLength(content) > policy.fileLimit)
+                throw new Error('Content exceeds write limit');
+            await policy.atomicWrite(context, name, content, expected);
+        };
+        let original;
+        return {
+            read: andorraCreateReadTool(workspace, { operations: { access, readFile: async (name) => Buffer.from(await read(name)) } }),
+            write: andorraCreateWriteTool(workspace, { operations: {
+                    mkdir: async (name) => { await safe(name, true); }, writeFile: write,
+                } }),
+            edit: andorraCreateEditTool(workspace, { operations: {
+                    access, readFile: async (name) => {
+                        original = await read(name);
+                        if (beforeApproval !== undefined && original !== beforeApproval)
+                            throw new Error('File changed while awaiting approval; retry');
+                        return Buffer.from(original);
+                    },
+                    writeFile: (name, content) => write(name, content, original),
+                } }),
+            ls: andorraCreateLsTool(workspace, { operations: {
+                    exists: async (name) => { await safe(name); return true; },
+                    stat: async (name) => stat(await safe(name)),
+                    readdir: async (name) => (await readdir(await safe(name), { withFileTypes: true })).filter(entry => !entry.isSymbolicLink() && !excluded.has(entry.name)).map(entry => entry.name),
+                } }),
+            find: andorraCreateFindTool(workspace, { operations: {
+                    exists: async (name) => { await safe(name); return true; },
+                    glob: async (pattern, cwd, options) => {
+                        const matches = [];
+                        const root = await safe(cwd);
+                        for await (const name of policy.files(context, root)) {
+                            signal.throwIfAborted();
+                            const relative = path.relative(root, name).split(path.sep).join('/');
+                            if (path.matchesGlob(relative, pattern) || (!pattern.includes('/') && path.matchesGlob(path.basename(relative), pattern)))
+                                matches.push(name);
+                            if (matches.length >= options.limit)
+                                break;
+                        }
+                        return matches;
+                    },
+                } }),
+            grep: andorraCreateGrepTool(workspace, { operations: {
+                    isDirectory: async (name) => (await stat(await safe(name))).isDirectory(), readFile: read,
+                } }),
+        };
+    }
+    const Read = zTool('Read', `Read a UTF-8 workspace file up to 8 MiB with compact line numbers. One call returns at most ${READ_MAX_LINES} lines: for a longer file, continue with the offset the result reports until you have read the whole file. A complete Read — every line, across calls — is remembered so Write/Edit can reject stale or unseen existing files; do not re-read unchanged files after a successful mutation.`, { type: 'object', properties: {
+            file_path: { type: 'string', description: 'Workspace-relative or absolute path inside the workspace' },
+            offset: { type: 'integer', minimum: 0, description: '1-based starting line; 0 is accepted as line 1' },
+            limit: { type: 'integer', minimum: 1, maximum: READ_MAX_LINES, description: `Maximum lines to return, at most ${READ_MAX_LINES}` },
+        }, required: ['file_path'], additionalProperties: false }, 'parallel', async (args, context) => {
+        if (Object.keys(args).some(key => !['file_path', 'offset', 'limit'].includes(key)))
+            throw new Error('Unknown Read argument');
+        const filePath = stringArg(args, 'file_path');
+        const offset = intArg(args, 'offset', { min: 0, max: Number.MAX_SAFE_INTEGER });
+        const limit = intArg(args, 'limit', { min: 1, max: READ_MAX_LINES }) ?? READ_MAX_LINES;
+        const resolved = await policy.safePath(context, filePath);
+        const content = await policy.read(context, resolved);
+        const lines = content.split('\n');
+        if (content.endsWith('\n') || content === '')
+            lines.pop();
+        const first = Math.max(1, offset ?? 1);
+        if (!lines.length) {
+            await rememberReadRange(context, resolved, content, 1, 0, 0);
+            return '[Empty file]';
+        }
+        if (first > lines.length)
+            throw new Error(`Offset ${first} is beyond end of file (${lines.length} lines total)`);
+        const lastRequested = Math.min(lines.length, first + limit - 1);
+        // The runtime clips every tool result at MAX_MODEL_OUTPUT before the model sees it, so a
+        // page that overflows would lose its tail and the continuation footer while still being
+        // recorded as read. Stop on the last whole line that fits, and record only that line.
+        const budget = MAX_MODEL_OUTPUT - 200;
+        let rendered = '';
+        let emittedLast = first - 1;
+        for (let line = first; line <= lastRequested; line++) {
+            const body = lines[line - 1] ?? '';
+            const shown = body.length > READ_MAX_LINE_CHARS ? `${body.slice(0, READ_MAX_LINE_CHARS)}... (line truncated to ${READ_MAX_LINE_CHARS} chars)` : body;
+            const next = `${line}\t${shown}${line < lastRequested ? '\n' : ''}`;
+            if (rendered.length + next.length > budget)
+                break;
+            rendered += next;
+            emittedLast = line;
+        }
+        if (emittedLast < first) {
+            // A truncated line always fits this budget, so this is a defensive guard, not a path.
+            rendered = `${first}\t${(lines[first - 1] ?? '').slice(0, READ_MAX_LINE_CHARS)}`;
+            emittedLast = first;
+        }
+        await rememberReadRange(context, resolved, content, first, emittedLast, lines.length);
+        if (emittedLast < lines.length)
+            rendered += `\n[Showing lines ${first}-${emittedLast} of ${lines.length}. Use offset=${emittedLast + 1} to continue.]`;
+        return rendered;
+    });
+    const Write = zTool('Write', 'Create a new file or completely replace an existing file. Existing files must first be fully Read (or supplied completely by CodeGraph) and must still match that snapshot. Prefer Edit for partial changes.', { type: 'object', properties: {
+            file_path: { type: 'string', description: 'Workspace-relative or absolute path inside the workspace' },
+            content: { type: 'string', description: 'Complete replacement file content' },
+        }, required: ['file_path', 'content'], additionalProperties: false }, 'sequential', async (args, context) => {
+        if (Object.keys(args).some(key => !['file_path', 'content'].includes(key)))
+            throw new Error('Unknown Write argument');
+        const filePath = stringArg(args, 'file_path'), content = stringArg(args, 'content', true) ?? '';
+        if (Buffer.byteLength(content) > policy.fileLimit)
+            throw new Error('Content exceeds write limit');
+        const resolved = await policy.safePath(context, filePath, true);
+        const existing = await stat(resolved).catch((error) => { if (error.code !== 'ENOENT')
+            throw error; return undefined; });
+        const before = existing ? await requireFreshRead(policy, context, resolved, 'Write') : undefined;
+        await policy.authorize('Write', args, context);
+        if (existing)
+            await requireFreshRead(policy, context, resolved, 'Write');
+        await policy.atomicWrite(context, resolved, content, before);
+        await remember(context, resolved, content, true, 'mutation');
+        return `${existing ? 'Updated' : 'Created'} ${path.relative(context.workspace, resolved) || resolved} (${Buffer.byteLength(content)} bytes). File state is current; no Read-back is needed.`;
+    });
+    const Edit = zTool('Edit', 'Replace one exact old_string with new_string in a file. Copy old_string from observed current source; include only enough context to make it unique. Use replace_all only for an intentional repeated replacement. Existing files must be fully Read or completely supplied by CodeGraph and must still be fresh. Failed matching leaves the file unchanged: inspect the reported area before retrying.', { type: 'object', properties: {
+            file_path: { type: 'string', description: 'Workspace-relative or absolute path inside the workspace' },
+            edits: { type: 'array', minItems: 1, items: { type: 'object', properties: {
+                        old_string: { type: 'string' }, new_string: { type: 'string' },
+                    }, required: ['old_string', 'new_string'], additionalProperties: false }, description: 'Multiple exact replacements, all matched against the original file' },
+            old_string: { type: 'string', description: 'Single exact text to replace' },
+            new_string: { type: 'string', description: 'Replacement for old_string' },
+            replace_all: { type: 'boolean', description: 'Replace every exact old_string occurrence; valid only with old_string/new_string' },
+        }, required: ['file_path'], additionalProperties: false }, 'sequential', async (args, context) => {
+        if (Object.keys(args).some(key => !['file_path', 'edits', 'old_string', 'new_string', 'replace_all'].includes(key)))
+            throw new Error('Unknown Edit argument');
+        const filePath = stringArg(args, 'file_path');
+        const resolved = await policy.safePath(context, filePath);
+        const before = await requireFreshRead(policy, context, resolved, 'Edit');
+        const replaceAll = boolArg(args, 'replace_all') ?? false;
+        const rawEdits = args.edits;
+        const singleOld = args.old_string, singleNew = args.new_string;
+        if (rawEdits !== undefined && (singleOld !== undefined || singleNew !== undefined || replaceAll))
+            throw new Error('Use either edits[] or old_string/new_string, not both');
+        if (replaceAll) {
+            if (typeof singleOld !== 'string' || !singleOld || typeof singleNew !== 'string')
+                throw new Error('replace_all requires nonempty old_string and string new_string');
+            const count = before.split(singleOld).length - 1;
+            if (!count)
+                throw new Error('old_string was not found');
+            const updated = before.split(singleOld).join(singleNew);
+            await policy.authorize('Edit', args, context);
+            await requireFreshRead(policy, context, resolved, 'Edit');
+            await policy.atomicWrite(context, resolved, updated, before);
+            await remember(context, resolved, updated, true, 'mutation');
+            return `Replaced ${count} occurrence(s) in ${path.relative(context.workspace, resolved) || resolved}. File state is current; no Read-back is needed.`;
+        }
+        // Models sometimes send `edits` as a JSON string, or a single edit object where the
+        // contract asks for a one-element array, so coerce before validating. The engine edit
+        // adapter tolerated both; dropping the tolerance would turn recoverable calls into
+        // hard failures on a path that previously worked.
+        const coerceEdits = (value) => {
+            let parsed = value;
+            if (typeof parsed === 'string') {
+                try {
+                    parsed = JSON.parse(parsed);
+                }
+                catch {
+                    return undefined;
+                }
+            }
+            if (Array.isArray(parsed))
+                return parsed;
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const single = parsed;
+                const isEdit = (typeof single.old_string === 'string' && typeof single.new_string === 'string')
+                    || (typeof single.oldText === 'string' && typeof single.newText === 'string');
+                return isEdit ? [single] : undefined;
+            }
+            return undefined;
+        };
+        const editField = (item, canonical, legacy) => {
+            if (typeof item[canonical] === 'string')
+                return item[canonical];
+            if (typeof item[legacy] === 'string')
+                return item[legacy];
+            return undefined;
+        };
+        let edits;
+        const rawList = rawEdits === undefined ? undefined : coerceEdits(rawEdits);
+        if (rawEdits !== undefined && rawList === undefined)
+            throw new Error('edits must be an array of old_string/new_string replacements');
+        if (rawList !== undefined) {
+            if (!rawList.length)
+                throw new Error('edits must contain old_string/new_string replacements');
+            edits = rawList.map(item => {
+                if (!item || typeof item !== 'object' || Array.isArray(item))
+                    throw new Error('edits must contain old_string/new_string replacements');
+                const oldText = editField(item, 'old_string', 'oldText');
+                const newText = editField(item, 'new_string', 'newText');
+                if (!oldText || newText === undefined)
+                    throw new Error('edits must contain old_string/new_string replacements');
+                return { oldText, newText };
+            });
+        }
+        else {
+            if (typeof singleOld !== 'string' || !singleOld || typeof singleNew !== 'string')
+                throw new Error('Edit requires edits[] or old_string/new_string');
+            edits = [{ oldText: singleOld, newText: singleNew }];
+        }
+        await policy.authorize('Edit', args, context);
+        const current = bound(context, before).edit;
+        let result;
+        try {
+            result = await current.execute(randomUUID(), { path: resolved, edits }, context.signal);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !/Could not find|Found \d+ occurrences|overlap/i.test(error.message))
+                throw error;
+            // Matcher failures occur before the native atomic write. Do not imply
+            // partial batch progress, or echo the entire generated patch as feedback.
+            const failedIndex = Number(error.message.match(/edits\[(\d+)\]/)?.[1] ?? 0);
+            const failed = edits[failedIndex];
+            const lines = before.split(/\r?\n/);
+            const anchors = (failed?.oldText ?? '').split(/\r?\n/).map(line => line.trim()).filter(line => line.length >= 8).slice(0, 4);
+            const location = lines.findIndex(line => anchors.some(anchor => line.includes(anchor)));
+            const first = location < 0 ? 1 : Math.max(1, location - 2);
+            const excerpt = lines.slice(first - 1, first + 5).map((line, index) => `${first + index}\t${clipText(line, 220)}`).join('\n');
+            const unchanged = await policy.read(context, resolved) === before;
+            throw new Error(`${clipText(error.message, 300)}\n${unchanged ? 'File unchanged; no replacements were applied.' : 'File state changed externally; Read current source before editing.'} ${edits.length > 1 ? 'Legacy batches are atomic: a failed match cancels every replacement. ' : ''}Use one small replacement copied from current source. Read offset=${first}, limit=12 to inspect ${location < 0 ? 'the file; no supplied anchor matched' : 'near a matching anchor'}.\n${excerpt}`);
+        }
+        const updated = await policy.read(context, resolved);
+        await remember(context, resolved, updated, true, 'mutation');
+        const upstream = result.content.filter(part => part.type === 'text').map(part => part.text).join('\n');
+        return nativeObservation(upstream || `Successfully replaced ${edits.length} block(s) in ${path.relative(context.workspace, resolved) || resolved}. File state is current; no Read-back is needed.`);
+    });
+    // Advertise the focused single replacement contract. Older saved calls
+    // retain batch compatibility, validated separately after normalization.
+    Edit.validationParameters = Edit.parameters;
+    const { edits: _legacyEdits, ...singleProperties } = Edit.parameters.properties;
+    Edit.parameters = { ...Edit.parameters, properties: singleProperties, required: ['file_path', 'old_string', 'new_string'] };
+    Edit.prepareArguments = value => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error('Edit arguments must be an object');
+        const args = { ...value };
+        if (args.edits === undefined)
+            return args;
+        let edits = args.edits;
+        if (typeof edits === 'string') {
+            try {
+                edits = JSON.parse(edits);
+            }
+            catch {
+                throw new Error('edits must contain valid JSON replacements');
+            }
+        }
+        if (edits && typeof edits === 'object' && !Array.isArray(edits))
+            edits = [edits];
+        if (!Array.isArray(edits))
+            throw new Error('edits must contain an array of replacements');
+        args.edits = edits.map(edit => {
+            if (!edit || typeof edit !== 'object' || Array.isArray(edit))
+                throw new Error('Each edit must be an object');
+            const item = edit;
+            const { oldText: _old, newText: _new, ...canonical } = item;
+            return {
+                ...canonical,
+                ...(item.old_string === undefined && typeof item.oldText === 'string' ? { old_string: item.oldText } : {}),
+                ...(item.new_string === undefined && typeof item.newText === 'string' ? { new_string: item.newText } : {}),
+            };
+        });
+        return args;
+    };
+    const Glob = zTool('Glob', 'Find files by glob pattern inside the workspace. This replaces Andorra list_files and Pi find/ls with one bounded discovery tool.', { type: 'object', properties: {
+            pattern: { type: 'string', description: 'Glob pattern such as **/*.ts or src/**/*.spec.ts' },
+            path: { type: 'string', description: 'Directory inside the workspace; defaults to .' },
+            head_limit: { type: 'integer', minimum: 1, maximum: 1000, description: 'Maximum paths; default 100' },
+        }, required: ['pattern'], additionalProperties: false }, 'parallel', async (args, context) => {
+        if (Object.keys(args).some(key => !['pattern', 'path', 'head_limit'].includes(key)))
+            throw new Error('Unknown Glob argument');
+        const pattern = stringArg(args, 'pattern'), searchPath = stringArg(args, 'path', true) ?? '.';
+        const limit = intArg(args, 'head_limit', { min: 1, max: 1000 }) ?? 100;
+        const resolved = await policy.safePath(context, searchPath);
+        const current = bound(context).find;
+        const result = await current.execute(randomUUID(), { pattern, path: resolved, limit }, context.signal);
+        return nativeObservation(result.content.filter(part => part.type === 'text').map(part => part.text).join('\n'));
+    });
+    const Grep = zTool('Grep', 'Search file contents with file-name, count or content results. Restricted modes use bounded native searches with interruptible JavaScript single-line regular expressions (5-second search budget), glob filters, context lines and offsets; type, multiline and only-matching options require unrestricted ripgrep.', { type: 'object', properties: {
+            pattern: { type: 'string', description: 'Regular expression to search for' },
+            path: { type: 'string', description: 'File or directory inside the workspace; defaults to .' },
+            glob: { type: 'string', description: 'Optional glob filter such as *.{ts,tsx}' },
+            output_mode: { type: 'string', enum: ['content', 'files_with_matches', 'count'], description: 'Default files_with_matches' },
+            '-B': { type: 'integer', minimum: 0, maximum: 100 },
+            '-A': { type: 'integer', minimum: 0, maximum: 100 },
+            '-C': { type: 'integer', minimum: 0, maximum: 100 },
+            context: { type: 'integer', minimum: 0, maximum: 100 },
+            '-n': { type: 'boolean' },
+            '-i': { type: 'boolean' },
+            '-o': { type: 'boolean' },
+            type: { type: 'string', description: 'ripgrep file type such as ts, js, py, rust, go' },
+            head_limit: { type: 'integer', minimum: 0, maximum: 2000, description: 'Default 250; 0 requests the bounded maximum' },
+            offset: { type: 'integer', minimum: 0, maximum: 100000 },
+            multiline: { type: 'boolean' },
+        }, required: ['pattern'], additionalProperties: false }, 'parallel', async (args, context) => {
+        const allowed = ['pattern', 'path', 'glob', 'output_mode', '-B', '-A', '-C', 'context', '-n', '-i', '-o', 'type', 'head_limit', 'offset', 'multiline'];
+        if (Object.keys(args).some(key => !allowed.includes(key)))
+            throw new Error('Unknown Grep argument');
+        const pattern = stringArg(args, 'pattern'), searchPath = stringArg(args, 'path', true) ?? '.';
+        const glob = stringArg(args, 'glob', true), type = stringArg(args, 'type', true);
+        const mode = args.output_mode ?? 'files_with_matches';
+        if (!['content', 'files_with_matches', 'count'].includes(String(mode)))
+            throw new Error('output_mode must be content, files_with_matches or count');
+        const before = intArg(args, '-B', { min: 0, max: 100 }), after = intArg(args, '-A', { min: 0, max: 100 });
+        const around = intArg(args, 'context', { min: 0, max: 100 }) ?? intArg(args, '-C', { min: 0, max: 100 });
+        const lineNumbers = boolArg(args, '-n') ?? true, ignoreCase = boolArg(args, '-i') ?? false, only = boolArg(args, '-o') ?? false, multiline = boolArg(args, 'multiline') ?? false;
+        const requestedLimit = intArg(args, 'head_limit', { min: 0, max: 2000 });
+        const limit = requestedLimit === 0 ? 2000 : requestedLimit ?? 250;
+        const offset = intArg(args, 'offset', { min: 0, max: 100000 }) ?? 0;
+        const resolved = await policy.safePath(context, searchPath);
+        // Resolving rg probes PATH by executing it. Restricted searches must never
+        // enter that resolver (or a vendor helper that downloads/spawns binaries).
+        const restricted = context.pinFilePaths || (permissionMode(context) !== undefined && permissionMode(context) !== 'full-access');
+        const rg = restricted ? null : andorraGetToolPath('rg');
+        if (!rg) {
+            if (type || multiline || only)
+                throw new Error(restricted
+                    ? 'This Grep option requires ripgrep, which is unavailable to restricted searches. Use glob and a single-line pattern instead.'
+                    : 'This Grep mode requires ripgrep (rg), which is not available. Use content mode with a narrower pattern/path or install ripgrep.');
+            return withGrepRegex(pattern, (ignoreCase ? 'i' : '') + (mode === 'count' ? 'g' : ''), context.signal, async (scan, searchSignal) => {
+                const searchContext = { ...context, signal: searchSignal };
+                const info = await stat(resolved);
+                searchSignal.throwIfAborted();
+                const candidates = [];
+                if (info.isFile())
+                    candidates.push(resolved);
+                else
+                    for await (const candidate of policy.files(searchContext, resolved)) {
+                        searchSignal.throwIfAborted();
+                        candidates.push(candidate);
+                    }
+                const rows = [];
+                let scannedFiles = 0, scannedBytes = 0;
+                let scanNotice = '';
+                const contextBefore = around ?? before ?? 0, contextAfter = around ?? after ?? 0;
+                for (const candidate of candidates) {
+                    searchSignal.throwIfAborted();
+                    const relative = path.relative(resolved, candidate).split(path.sep).join('/') || path.basename(candidate);
+                    if (glob && !path.matchesGlob(relative, glob) && !path.matchesGlob(path.basename(relative), glob))
+                        continue;
+                    if (++scannedFiles > 1000) {
+                        scanNotice = '\n[Search file limit reached; narrow the path/glob.]';
+                        break;
+                    }
+                    let source;
+                    try {
+                        // Discovery is not a snapshot: builds/cleanup can remove or revoke a
+                        // candidate before either stat or read. Skip it just like a failed read.
+                        const candidateInfo = await stat(candidate);
+                        searchSignal.throwIfAborted();
+                        if (candidateInfo.size > SEARCH_FILE_LIMIT)
+                            continue;
+                        if ((scannedBytes += candidateInfo.size) > SEARCH_SCAN_LIMIT) {
+                            scanNotice = '\n[Search byte limit reached at 16 MiB; narrow the path/glob.]';
+                            break;
+                        }
+                        source = await policy.read(searchContext, candidate);
+                    }
+                    catch {
+                        searchSignal.throwIfAborted();
+                        continue;
+                    }
+                    searchSignal.throwIfAborted();
+                    const lines = source.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
+                    let matches = 0;
+                    for (const match of await scan(lines, mode === 'count')) {
+                        const index = match.index;
+                        matches += match.count;
+                        if (mode === 'files_with_matches') {
+                            rows.push(relative);
+                            break;
+                        }
+                        if (mode === 'count')
+                            continue;
+                        const start = Math.max(0, index - contextBefore), end = Math.min(lines.length - 1, index + contextAfter);
+                        for (let cursor = start; cursor <= end; cursor++) {
+                            const marker = cursor === index ? ':' : '-';
+                            rows.push(lineNumbers ? `${relative}${marker}${cursor + 1}${marker}${clipText(lines[cursor], 800)}` : `${relative}${marker}${clipText(lines[cursor], 800)}`);
+                        }
+                        if (rows.length >= offset + limit)
+                            break;
+                    }
+                    if (mode === 'count' && matches)
+                        rows.push(`${relative}:${matches}`);
+                    if (rows.length >= offset + limit)
+                        break;
+                }
+                const selected = rows.slice(offset, offset + limit);
+                return nativeObservation((selected.length ? selected.join('\n') : 'No matches') + scanNotice + `\n[Grep ${mode} fallback: ${selected.length} returned; ${restricted ? 'native restricted search' : 'ripgrep unavailable'}]`);
+            });
+        }
+        const cwd = await policy.safePath(context, '.');
+        const target = path.relative(cwd, resolved) || '.';
+        const rgArgs = ['--color=never', '--hidden', '--glob', '!.git/**', '--glob', '!node_modules/**', '--glob', '!.andorracode/**'];
+        if (ignoreCase)
+            rgArgs.push('--ignore-case');
+        if (glob)
+            rgArgs.push('--glob', glob);
+        if (type)
+            rgArgs.push('--type', type);
+        if (multiline)
+            rgArgs.push('--multiline', '--multiline-dotall');
+        if (mode === 'files_with_matches')
+            rgArgs.push('--files-with-matches');
+        else if (mode === 'count')
+            rgArgs.push('--count-matches');
+        else {
+            if (lineNumbers)
+                rgArgs.push('--line-number');
+            if (only)
+                rgArgs.push('--only-matching');
+            if (around !== undefined)
+                rgArgs.push('--context', String(around));
+            else {
+                if (before !== undefined)
+                    rgArgs.push('--before-context', String(before));
+                if (after !== undefined)
+                    rgArgs.push('--after-context', String(after));
+            }
+        }
+        rgArgs.push('--', pattern, target);
+        const started = Date.now();
+        let stdout = '';
+        try {
+            const result = await execFileAsync(rg, rgArgs, { cwd, encoding: 'utf8', signal: context.signal, windowsHide: true, timeout: 30_000, maxBuffer: 2_000_000 });
+            stdout = String(result.stdout ?? '');
+        }
+        catch (error) {
+            context.signal.throwIfAborted();
+            const failure = error;
+            if (Number(failure.code) === 1)
+                stdout = String(failure.stdout ?? '');
+            else
+                throw new Error(`Grep failed: ${String(failure.stderr ?? failure.message).trim().slice(0, 1000)}`);
+        }
+        const all = stdout.split(/\r?\n/).filter(Boolean);
+        const selected = all.slice(offset, offset + limit).map(line => line.length > 800 ? clipText(line, 800) + ' [line clipped]' : line);
+        const truncated = offset + selected.length < all.length || stdout.length > 24_000;
+        const body = selected.join('\n') || 'No matches';
+        const meta = `[Grep ${mode}: ${selected.length} returned${offset ? `, offset ${offset}` : ''}${truncated ? ', more available/refine pattern' : ''}; ${Date.now() - started}ms]`;
+        return nativeObservation(`${body}\n${meta}`);
+    });
+    const canonicalShell = (name, kind) => {
+        const actual = kind === 'powershell' ? 'PowerShell' : 'Bash';
+        const syntax = kind === 'powershell'
+            ? 'PowerShell syntax; use & before a quoted executable path. No cmd.exe substitution. Do not pipe a running child into Select-Object -First: it terminates the pipeline before the child completes and can cause exit 4294967295. Host output is already tail-bounded; use Select-Object -Last if further filtering is needed. Prefer file-written scripts over nested quoting for multiline Python/JavaScript. Prefer direct invocation (& $exe @args) for child processes: Windows PowerShell Start-Process -ArgumentList flattens arrays and can split a multi-word argument unless it is quoted manually.'
+            : 'Bash syntax (Git Bash on Windows).';
+        const tool = zTool(name, `Execute a foreground ${actual} command in the workspace. The working directory is the workspace; ${syntax} Output is tail-bounded. Commands follow the current workspace permissions. Restricted modes use the Codex OS sandbox and block network/outside writes; explicit escalation requires justification and approval. Credential environment variables are excluded; credential files remain accessible. This uses the compact command/timeout/description contract while retaining Pi/Andorra process-tree cleanup. Background execution is not exposed.`, { type: 'object', properties: {
+                command: { type: 'string', description: 'Command to execute' },
+                timeout: { type: 'integer', minimum: 1, maximum: 600000, description: 'Timeout in milliseconds; default 30000' },
+                description: { type: 'string', description: 'Short active-voice description of what the command does' },
+                ...sandboxFields,
+            }, required: ['command'], additionalProperties: false }, 'sequential', async (args, context) => {
+            if (Object.keys(args).some(key => !['command', 'timeout', 'description', 'sandbox_permissions', 'justification'].includes(key)))
+                throw new Error(`Unknown ${name} argument`);
+            const command = stringArg(args, 'command'), timeout = intArg(args, 'timeout', { min: 1, max: 600000 }) ?? 30000;
+            if (args.description !== undefined)
+                stringArg(args, 'description', true);
+            const launchPolicy = await shellPermission(policy, name, args, context);
+            const cwd = await policy.safePath(context, '.');
+            const operations = { exec: async (value, directory, options) => {
+                    try {
+                        await runShell(value, directory, timeout, context.signal, kind, options.onData, undefined, launchPolicy);
+                        return { exitCode: 0 };
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        const code = /^Exit code: (\d+)\n/.exec(message);
+                        if (code)
+                            return { exitCode: Number(code[1]) };
+                        throw error;
+                    }
+                } };
+            const current = kind === 'powershell'
+                ? andorraCreatePowerShellTool(cwd, { operations, persistOutput: false, exposeSessionEnvironment: false })
+                : andorraCreateBashTool(cwd, { operations, persistOutput: false, exposeSessionEnvironment: false });
+            try {
+                const result = await current.execute(randomUUID(), { command, timeout: timeout / 1000 }, context.signal);
+                return nativeObservation(result.content.filter(part => part.type === 'text').map(part => part.text).join('\n'), true);
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.length > MAX_MODEL_OUTPUT)
+                    throw new Error(nativeObservation(error.message, true));
+                throw error;
+            }
+        });
+        // The vendored shell throws on any exit other than 0, so a return is a clean exit.
+        return { ...tool, exitZeroOnReturn: true };
+    };
+    // Keep imported Pi spellings executable for old tests/configuration, but never
+    // advertise them to providers. capabilityTools maps legacy graph allowlists to
+    // the canonical surface above.
+    const definitions = [andorraCreateReadTool('.'), andorraCreateWriteTool('.'), andorraCreateEditTool('.'), andorraCreateLsTool('.'), andorraCreateFindTool('.'), andorraCreateGrepTool('.')];
+    const legacyNative = definitions.map(definition => ({
+        name: definition.name,
+        providerVisible: false,
+        prepareArguments: definition.prepareArguments,
+        executionMode: definition.name === 'write' || definition.name === 'edit' ? 'sequential' : 'parallel',
+        // Preserve the Andorra wording over the imported Pi descriptions: the read tool must
+        // not advertise image attachments, and traversal/limits are workspace-bounded.
+        description: `${(definition.name === 'read' ? 'Read UTF-8 text files. Binary files and image attachments are unsupported. Output is bounded; use offset (1-based line number) and limit to read specific portions of large files.' : definition.description).replace('Respects .gitignore.', definition.name === 'find' ? 'Uses a bounded workspace traversal (1,000 results, depth 20).' : 'Respects .gitignore.')} Workspace-only; .git, node_modules and .andorracode are excluded from directory traversal. Text reads/writes have an 8 MiB file limit; observations remain bounded.`,
+        parameters: definition.parameters,
+        execute: async (args, context) => {
+            if (definition.prepareArguments)
+                args = definition.prepareArguments(args);
+            validateArguments(args, definition.parameters);
+            context.signal.throwIfAborted();
+            if (definition.name === 'grep' && (context.pinFilePaths || (permissionMode(context) !== undefined && permissionMode(context) !== 'full-access'))) {
+                const pattern = stringArg(args, 'pattern');
+                return Grep.execute({
+                    pattern: args.literal ? pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') : pattern,
+                    ...(args.path !== undefined ? { path: args.path } : {}),
+                    ...(args.glob !== undefined ? { glob: args.glob } : {}),
+                    ...(args.ignoreCase !== undefined ? { '-i': args.ignoreCase } : {}),
+                    ...(args.context !== undefined ? { context: args.context } : {}),
+                    ...(args.limit !== undefined ? { head_limit: args.limit } : {}),
+                    output_mode: 'content',
+                }, context);
+            }
+            const mutation = definition.name === 'write' || definition.name === 'edit';
+            const resolvedPath = await policy.safePath(context, typeof args.path === 'string' ? args.path : '.', definition.name === 'write');
+            const beforeApproval = definition.name === 'edit' ? await policy.read(context, resolvedPath) : undefined;
+            if (mutation)
+                await policy.authorize(definition.name, args, context);
+            const current = bound(context, beforeApproval)[definition.name];
+            const result = await current.execute(randomUUID(), { ...args, path: resolvedPath }, context.signal);
+            return nativeObservation(result.content.filter(part => part.type === 'text').map(part => part.text).join('\n'));
+        },
+    }));
+    const legacyShell = ['powershell', 'bash', 'shell'].map(name => {
+        const kind = name === 'shell' ? defaultShellKind : name;
+        const actual = kind === 'powershell' ? 'PowerShell (PowerShell syntax)' : kind === 'bash' ? 'Bash' : '/bin/sh';
+        return {
+            name, providerVisible: false, executionMode: 'sequential',
+            // 'shell' prints its own `Exit code:` line; the vendored powershell/bash throw on a non-zero exit.
+            exitZeroOnReturn: name !== 'shell',
+            description: `Legacy compatibility shell using ${actual}.`,
+            parameters: { type: 'object', properties: { command: { type: 'string' }, timeout_ms: { type: 'integer', minimum: 1, maximum: 120000 }, ...sandboxFields }, required: ['command'], additionalProperties: false },
+            execute: async (args, context) => {
+                if (Object.keys(args).some(key => !['command', 'timeout_ms', 'sandbox_permissions', 'justification'].includes(key)))
+                    throw new Error('Unknown shell argument');
+                if (typeof args.command !== 'string' || !args.command || args.command.includes('\0'))
+                    throw new Error('command must be a nonempty string without NUL bytes');
+                const timeout = args.timeout_ms ?? 30000;
+                if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout < 1 || timeout > 120000)
+                    throw new Error('timeout_ms must be an integer from 1 to 120000');
+                const launchPolicy = await shellPermission(policy, name, args, context);
+                const cwd = await policy.safePath(context, '.');
+                // Preserve the legacy observation formats: 'shell' keeps the runShell observation,
+                // while explicit 'powershell'/'bash' use native tail truncation and errors.
+                if (name === 'shell')
+                    return nativeObservation(await runShell(args.command, cwd, timeout, context.signal, kind, undefined, undefined, launchPolicy), true);
+                const operations = { exec: async (value, directory, options) => {
+                        try {
+                            await runShell(value, directory, timeout, context.signal, kind, options.onData, undefined, launchPolicy);
+                            return { exitCode: 0 };
+                        }
+                        catch (error) {
+                            const message = error instanceof Error ? error.message : String(error);
+                            const code = /^Exit code: (\d+)\n/.exec(message);
+                            if (code)
+                                return { exitCode: Number(code[1]) };
+                            throw error;
+                        }
+                    } };
+                const current = kind === 'powershell'
+                    ? andorraCreatePowerShellTool(cwd, { operations, persistOutput: false, exposeSessionEnvironment: false })
+                    : andorraCreateBashTool(cwd, { operations, persistOutput: false, exposeSessionEnvironment: false });
+                try {
+                    const result = await current.execute(randomUUID(), { command: args.command, timeout: timeout / 1000 }, context.signal);
+                    return nativeObservation(result.content.filter(part => part.type === 'text').map(part => part.text).join('\n'), true);
+                }
+                catch (error) {
+                    if (error instanceof Error && error.message.length > 24_000)
+                        throw new Error(nativeObservation(error.message, true));
+                    throw error;
+                }
+            },
+        };
+    });
+    const NativeExec = zTool('NativeExec', 'Run a supported native executable with an argument array, without a PowerShell/Bash startup. Use for simple git/node/rg commands. Does not interpret shell syntax: no pipes, redirects, or shell expansion. Runs foreground with the same approvals, workspace and cancellation policy as the shell.', { type: 'object', properties: {
+            program: { type: 'string', enum: ['git', 'node', 'rg'] },
+            args: { type: 'array', items: { type: 'string' }, maxItems: 128 },
+            timeout: { type: 'integer', minimum: 1, maximum: 600000 },
+            ...sandboxFields,
+        }, required: ['program', 'args'], additionalProperties: false }, 'sequential', async (args, context) => {
+        const program = stringArg(args, 'program');
+        if (!['git', 'node', 'rg'].includes(program))
+            throw new Error('Unsupported native program');
+        const argv = args.args;
+        if (!Array.isArray(argv) || argv.length > 128 || argv.some(arg => typeof arg !== 'string' || arg.length > 4096 || arg.includes('\0'))) {
+            throw new Error('args must be an array of at most 128 strings (4096 chars each, no NUL)');
+        }
+        const timeout = intArg(args, 'timeout', { min: 1, max: 600000 }) ?? 30000;
+        const launchPolicy = await shellPermission(policy, 'NativeExec', args, context);
+        const cwd = await policy.safePath(context, '.');
+        const executable = program === 'node' ? process.execPath : program === 'git' ? 'git' : andorraGetToolPath('rg');
+        if (!executable)
+            throw new Error('Native executable is not installed');
+        return nativeObservation(await runNativeProcess(executable, argv, cwd, timeout, context.signal, launchPolicy), true);
+    });
+    const AsyncProcess = zTool('AsyncProcess', 'Start a shell command in the background and return immediately; inspect status/logs, wait for completion without polling, or stop it. Use for independent builds, test suites, and dev servers so other agent work can continue. Each job has a generated ID. Jobs are killed when the owning CLI exits. Full Access or explicit escalation is required to start; sandbox restrictions are never bypassed.', { type: 'object', properties: {
+            action: { type: 'string', enum: ['start', 'status', 'logs', 'wait', 'stop'] },
+            command: { type: 'string', description: 'Shell command; only for start' },
+            id: { type: 'string', description: 'Job ID returned by start; required otherwise' },
+            timeout: { type: 'integer', minimum: 1, maximum: 600000, description: 'Maximum wait in milliseconds; does not kill unfinished jobs' },
+            ...sandboxFields,
+        }, required: ['action'], additionalProperties: false }, 'sequential', async (args, context) => {
+        const action = stringArg(args, 'action');
+        if (!['start', 'status', 'logs', 'wait', 'stop'].includes(action))
+            throw new Error('Unknown async process action');
+        const manager = getQaProcessManager(await policy.safePath(context, '.'));
+        if (action === 'start') {
+            const command = stringArg(args, 'command');
+            if (command.length > 32000)
+                throw new Error('Command is too long');
+            const launchPolicy = await shellPermission(policy, 'AsyncProcess', args, context);
+            const id = `agent-${randomUUID()}`;
+            return JSON.stringify(await manager.start({ id, command, launchPolicy, signal: context.signal }));
+        }
+        const id = stringArg(args, 'id');
+        if (!/^agent-[a-f0-9-]{36}$/.test(id))
+            throw new Error('Invalid agent job id');
+        const job = manager.get(id);
+        if (!job)
+            throw new Error('No such agent job in this workspace');
+        if (action === 'status')
+            return JSON.stringify(job);
+        if (action === 'logs')
+            return JSON.stringify({ ...job, tail: manager.logs(id) });
+        if (action === 'wait') {
+            const timeout = intArg(args, 'timeout', { min: 1, max: 600000 }) ?? 10000;
+            return JSON.stringify(await manager.wait(id, timeout, context.signal));
+        }
+        if (action === 'stop') {
+            await manager.stop(id);
+            return JSON.stringify({ id, stopped: true });
+        }
+        throw new Error('Invalid action');
+    });
+    const PowerShellFast = zTool('PowerShellFast', 'Windows only: run short, noninteractive PowerShell commands in a reused interpreter. Do not consume stdin, spawn background children, rely on runspace state or call exit. For those use PowerShell or AsyncProcess. Full Access or explicit escalation is required.', { type: 'object', properties: {
+            command: { type: 'string' },
+            timeout: { type: 'integer', minimum: 1, maximum: 600000 },
+            ...sandboxFields,
+        }, required: ['command'], additionalProperties: false }, 'sequential', async (args, context) => {
+        const command = stringArg(args, 'command');
+        const timeout = intArg(args, 'timeout', { min: 1, max: 600000 }) ?? 30000;
+        const launchPolicy = await shellPermission(policy, 'PowerShellFast', args, context);
+        const cwd = await policy.safePath(context, '.');
+        return nativeObservation(await runPooledPowerShell(command, cwd, timeout, context.signal, launchPolicy), true);
+    });
+    const ShellMetrics = zTool('ShellMetrics', 'Return bounded per-process command timing statistics (p50/p95/p99), startup/validation, execution, first-output and cleanup phases without leaking command arguments.', { type: 'object', properties: {}, additionalProperties: false }, 'parallel', async () => JSON.stringify(commandTimingSummary()));
+    const platformShell = process.platform === 'win32' ? canonicalShell('PowerShell', 'powershell') : canonicalShell('Bash', 'bash');
+    return [Read, Write, Edit, Glob, Grep, platformShell, NativeExec, AsyncProcess, ...(process.platform === 'win32' ? [PowerShellFast] : []), ShellMetrics, ...legacyNative, ...legacyShell];
+}