praxis-agent 0.46.2 → 0.46.4

package/README.md

@@ -153,6 +153,9 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   structured JSON/JSONL, context compaction, tool loops, and bounded execution.
 - **Built-in tools** — read, write, edit, glob, search, shell, notebook, PDF,
   image, web, scheduled prompts, workflows, and worktrees.
+- **Shell lifecycle** — foreground Bash allows up to 10 minutes and carries a
+  validated final working directory across calls in the same session without
+  leaking state across sessions or overriding an explicit `/cd`.
 - **Permission boundary** — local allow/ask/deny rules, safe and bare modes,
   searchable scoped-rule creation/removal, local/project/user atomic settings
   writes, tool-specific Bash/PowerShell/file/notebook/WebFetch/Skill approval

package/dist/platform/bounded-process-runner.d.ts

@@ -5,6 +5,7 @@ export interface ProcessResult {
     code: number;
     timedOut: boolean;
     truncated: boolean;
+    controlOutput?: string;
 }
 export interface BoundedProcessRunnerOptions {
     cwd: string;
@@ -18,6 +19,9 @@ export interface RunProcessOptions {
     signal?: AbortSignal;
     onOutput?: (output: string) => void | Promise<void>;
     env?: Readonly<Record<string, string>>;
+    controlOutputBytes?: number;
+    controlOutputFd?: number;
+    scriptInput?: string;
 }
 export declare function joinedProcessOutput(result: ProcessResult): string;
 export declare class BoundedProcessRunner {

package/dist/platform/bounded-process-runner.js

@@ -87,15 +87,35 @@ export class BoundedProcessRunner {
             const sensitiveValues = sensitiveEnvironmentValues(process.env);
             const longestSensitiveValueBytes = sensitiveValues.reduce((longest, value) => Math.max(longest, Buffer.byteLength(value)), 0);
             const rawOutputLimit = this.options.maxOutputBytes + Math.max(3, longestSensitiveValueBytes);
+            const controlOutputFd = options.controlOutputBytes === undefined
+                ? undefined
+                : (options.controlOutputFd ?? 3);
+            const scriptInputFd = options.scriptInput === undefined ? undefined : 4;
+            if (controlOutputFd !== undefined &&
+                scriptInputFd !== undefined &&
+                controlOutputFd === scriptInputFd) {
+                reject(new Error('Process control output and script input FDs conflict'));
+                return;
+            }
+            const highestFd = Math.max(2, controlOutputFd ?? 2, scriptInputFd ?? 2);
+            const stdio = Array.from({ length: highestFd + 1 }, () => 'ignore');
+            stdio[1] = 'pipe';
+            stdio[2] = 'pipe';
+            if (controlOutputFd !== undefined)
+                stdio[controlOutputFd] = 'pipe';
+            if (scriptInputFd !== undefined)
+                stdio[scriptInputFd] = 'pipe';
             const child = spawn(options.command, options.args, {
                 cwd: options.cwd ?? this.options.cwd,
                 detached: process.platform !== 'win32',
                 env: { ...sanitizeChildEnvironment(), ...options.env },
-                stdio: ['ignore', 'pipe', 'pipe'],
+                stdio,
             });
             const chunks = { stdout: [], stderr: [] };
             const combined = [];
             const retainedBytes = { stdout: 0, stderr: 0, combined: 0 };
+            const controlChunks = [];
+            let controlBytes = 0;
             let outputBytes = 0;
             let timedOut = false;
             let settled = false;
@@ -136,8 +156,41 @@ export class BoundedProcessRunner {
                 }
                 updateLiveOutput();
             };
+            if (!child.stdout || !child.stderr) {
+                reject(new Error('Process output streams were not created'));
+                return;
+            }
             child.stdout.on('data', (chunk) => retain('stdout', chunk));
             child.stderr.on('data', (chunk) => retain('stderr', chunk));
+            const controlStream = controlOutputFd === undefined ? undefined : child.stdio[controlOutputFd];
+            if (controlStream) {
+                controlStream.on('data', (chunk) => {
+                    const remaining = Math.max(0, (options.controlOutputBytes ?? 0) - controlBytes);
+                    if (remaining <= 0)
+                        return;
+                    const retained = chunk.subarray(0, remaining);
+                    controlChunks.push(retained);
+                    controlBytes += retained.length;
+                });
+                child.once('exit', () => {
+                    setImmediate(() => controlStream.destroy());
+                });
+            }
+            const scriptStream = scriptInputFd === undefined ? undefined : child.stdio[scriptInputFd];
+            if (scriptStream) {
+                scriptStream.on('error', () => {
+                    // The child process result remains authoritative if it exits before
+                    // consuming the complete script.
+                });
+                if (!('end' in scriptStream)) {
+                    reject(new Error('Process script input stream is not writable'));
+                    return;
+                }
+                scriptStream.end(options.scriptInput);
+                child.once('exit', () => {
+                    setImmediate(() => scriptStream.destroy());
+                });
+            }
             const kill = () => {
                 if (child.pid === undefined)
                     return;
@@ -200,6 +253,11 @@ export class BoundedProcessRunner {
                         code: code ?? 1,
                         timedOut,
                         truncated,
+                        ...(options.controlOutputBytes === undefined
+                            ? {}
+                            : {
+                                controlOutput: Buffer.concat(controlChunks).toString('utf8'),
+                            }),
                     });
                 }, reject);
             });

package/dist/sandbox/claude-sandbox-runtime.d.ts

@@ -21,6 +21,7 @@ export interface SandboxBackend {
 export interface SandboxCommandInput {
     command: string;
     dangerouslyDisableSandbox?: boolean;
+    executionCommand?: string;
 }
 export declare class ClaudeSandboxRuntime {
     private readonly backend;

package/dist/sandbox/claude-sandbox-runtime.js

@@ -136,7 +136,7 @@ export class ClaudeSandboxRuntime {
             throw new Error('Sandbox has not been initialized');
         if (!this.shouldUseSandbox(input))
             return input.command;
-        return this.backend.wrapWithSandbox(input.command, options.shell, undefined, options.signal, {
+        return this.backend.wrapWithSandbox(input.executionCommand ?? input.command, options.shell, undefined, options.signal, {
             ...(options.commandId ? { commandId: options.commandId } : {}),
             commandText: input.command,
         });

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

@@ -26,6 +26,7 @@ export interface BashSandboxRuntime {
     wrapCommand(input: {
         command: string;
         dangerouslyDisableSandbox?: boolean;
+        executionCommand?: string;
     }, options?: {
         shell?: string;
         signal?: AbortSignal;
@@ -43,6 +44,7 @@ export declare class LocalToolRegistry implements ToolRegistry {
     private readonly maxOutputBytes;
     private readonly maxFileBytes;
     private readonly maxShellTimeoutMs;
+    private readonly maxSearchTimeoutMs;
     private readonly processRunner;
     private readonly enableReportFindings;
     private readonly environment;
@@ -50,11 +52,14 @@ export declare class LocalToolRegistry implements ToolRegistry {
     private readonly sandbox;
     private readonly homeDirectory;
     private readonly configRoot;
+    private readonly sessionCwds;
     private readonly protectedWriteReason;
+    private readonly mutationTargetExisted;
     constructor(options: LocalToolRegistryOptions);
     private assertProtectedWritePath;
     private assertProtectedBashCommand;
     private currentCwd;
+    private currentBashCwd;
     definitions(): readonly ModelToolDefinition[];
     schedulingPolicy(call: ModelToolCall): {
         concurrency: "concurrent";
@@ -78,7 +83,9 @@ export declare class LocalToolRegistry implements ToolRegistry {
     private workspacePath;
     private filePath;
     private resolvePath;
+    private pathExists;
     private assertStablePath;
+    private assertStableCreationParent;
     private globRoot;
     private wasSuccessfullyRead;
     private read;

package/dist/tools/local-tools.js

@@ -1,4 +1,5 @@
 import { constants } from 'node:fs';
+import { randomBytes, randomInt } from 'node:crypto';
 import { mkdir, mkdtemp, open, realpath, stat, writeFile, } from 'node:fs/promises';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
@@ -247,6 +248,20 @@ function stringInput(input, name, allowEmpty = false) {
     }
     return value;
 }
+function stripShellControlTrace(content, token) {
+    if (!content.includes(token))
+        return content;
+    return content
+        .split('\n')
+        .filter((line) => !line.includes(token))
+        .join('\n');
+}
+function commandShellSyntaxArguments(command) {
+    const args = [...commandShellArguments(command)];
+    const commandIndex = args.indexOf('-c');
+    args.splice(commandIndex, 0, '-n');
+    return args;
+}
 function optionalString(input, name) {
     const value = input[name];
     if (value === undefined)
@@ -480,6 +495,14 @@ function formatKilobytes(bytes) {
     const value = bytes / 1024;
     return `${value < 10 ? value.toFixed(1) : Math.round(value)}KB`.replace('.0KB', 'KB');
 }
+function newlineStyle(content) {
+    return content.match(/\r\n|\n|\r/u)?.[0];
+}
+function normalizeNewlines(content, style) {
+    if (style === undefined)
+        return content;
+    return content.replace(/\r\n|\n|\r/gu, style);
+}
 function parsePdfPages(value) {
     const match = /^(\d+)(?:-(\d+))?$/u.exec(value);
     if (!match)
@@ -506,6 +529,7 @@ export class LocalToolRegistry {
     maxOutputBytes;
     maxFileBytes;
     maxShellTimeoutMs;
+    maxSearchTimeoutMs;
     processRunner;
     enableReportFindings;
     environment;
@@ -513,7 +537,9 @@ export class LocalToolRegistry {
     sandbox;
     homeDirectory;
     configRoot;
+    sessionCwds = new Map();
     protectedWriteReason;
+    mutationTargetExisted = new WeakMap();
     constructor(options) {
         this.cwd = resolve(options.cwd);
         this.cwdProvider = options.cwdProvider;
@@ -524,7 +550,8 @@ export class LocalToolRegistry {
         this.additionalReadDirectories = (options.additionalReadDirectories ?? []).map((directory) => resolve(directory));
         this.maxOutputBytes = options.maxOutputBytes ?? 128 * 1024;
         this.maxFileBytes = options.maxFileBytes ?? 10 * 1024 * 1024;
-        this.maxShellTimeoutMs = options.maxShellTimeoutMs ?? 120_000;
+        this.maxShellTimeoutMs = options.maxShellTimeoutMs ?? 600_000;
+        this.maxSearchTimeoutMs = options.maxShellTimeoutMs ?? 120_000;
         this.enableReportFindings = options.enableReportFindings ?? false;
         this.environment = options.environment;
         this.sessionEnvironment = options.sessionEnvironment;
@@ -551,7 +578,7 @@ export class LocalToolRegistry {
         }
     }
     assertProtectedBashCommand(command, context) {
-        const cwd = this.currentCwd(context);
+        const cwd = this.currentBashCwd(context);
         const protectedWrite = context?.preToolUseAllowed
             ? (filePath) => {
                 const reason = this.protectedWriteReason(filePath);
@@ -576,6 +603,18 @@ export class LocalToolRegistry {
     currentCwd(context) {
         return resolve(context?.cwd || this.cwdProvider?.() || this.cwd);
     }
+    currentBashCwd(context) {
+        const hostCwd = this.currentCwd(context);
+        if (context?.sessionId) {
+            const sessionCwd = this.sessionCwds.get(context.sessionId);
+            if (sessionCwd) {
+                if (sessionCwd.hostCwd === hostCwd)
+                    return sessionCwd.cwd;
+                this.sessionCwds.delete(context.sessionId);
+            }
+        }
+        return hostCwd;
+    }
     definitions() {
         const definitions = this.enableReportFindings
             ? [...TOOL_DEFINITIONS, REPORT_FINDINGS_DEFINITION]
@@ -646,28 +685,48 @@ export class LocalToolRegistry {
                     },
                 };
             }
-            case 'Write':
-                return {
+            case 'Write': {
+                const filePath = await this.filePath(stringInput(call.input, 'file_path'), true, false, context);
+                this.assertProtectedWritePath(filePath);
+                const targetExisted = await this.pathExists(filePath);
+                if (targetExisted &&
+                    !(await this.wasSuccessfullyRead(filePath, context.messages ?? [], context))) {
+                    throw new Error('<tool_use_error>File has not been read yet. Read it first before writing to it.</tool_use_error>');
+                }
+                const prepared = {
                     ...call,
                     input: {
-                        file_path: await this.filePath(stringInput(call.input, 'file_path'), true, false, context),
+                        file_path: filePath,
                         content: stringInput(call.input, 'content', true),
                     },
                 };
+                this.mutationTargetExisted.set(prepared, targetExisted);
+                return prepared;
+            }
             case 'Edit': {
                 const replaceAll = call.input.replace_all;
                 if (replaceAll !== undefined && typeof replaceAll !== 'boolean') {
                     throw new Error('replace_all must be a boolean');
                 }
-                return {
+                const oldString = stringInput(call.input, 'old_string', true);
+                const filePath = await this.filePath(stringInput(call.input, 'file_path'), oldString === '', false, context);
+                this.assertProtectedWritePath(filePath);
+                const targetExisted = await this.pathExists(filePath);
+                if (targetExisted &&
+                    !(await this.wasSuccessfullyRead(filePath, context.messages ?? [], context))) {
+                    throw new Error('<tool_use_error>File has not been read yet. Read it first before writing to it.</tool_use_error>');
+                }
+                const prepared = {
                     ...call,
                     input: {
-                        file_path: await this.filePath(stringInput(call.input, 'file_path'), false, false, context),
-                        old_string: stringInput(call.input, 'old_string'),
+                        file_path: filePath,
+                        old_string: oldString,
                         new_string: stringInput(call.input, 'new_string', true),
                         replace_all: replaceAll ?? false,
                     },
                 };
+                this.mutationTargetExisted.set(prepared, targetExisted);
+                return prepared;
             }
             case 'NotebookEdit': {
                 const requestedPath = stringInput(call.input, 'notebook_path');
@@ -759,17 +818,24 @@ export class LocalToolRegistry {
     async execute(call, context) {
         if (context.signal?.aborted)
             throw abortError();
+        const approvedTargetExisted = this.mutationTargetExisted.get(call);
         const prepared = await this.prepare(call, context);
         if (JSON.stringify(prepared.input) !== JSON.stringify(call.input)) {
             throw new Error('Tool input changed after permission approval');
         }
+        const executionTargetExisted = this.mutationTargetExisted.get(prepared);
+        if (approvedTargetExisted !== undefined &&
+            executionTargetExisted !== approvedTargetExisted) {
+            throw new Error('Tool input changed after permission approval');
+        }
+        const targetExisted = approvedTargetExisted ?? executionTargetExisted;
         switch (prepared.name) {
             case 'Read':
                 return this.read(prepared, context);
             case 'Write':
-                return this.write(prepared);
+                return this.write(prepared, context, targetExisted);
             case 'Edit':
-                return this.edit(prepared);
+                return this.edit(prepared, targetExisted);
             case 'NotebookEdit':
                 return this.notebookEdit(prepared);
             case 'Glob':
@@ -864,11 +930,28 @@ export class LocalToolRegistry {
             return join(parent, basename(candidate));
         }
     }
+    async pathExists(filePath) {
+        try {
+            await stat(filePath);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
     async assertStablePath(filePath) {
         if ((await realpath(filePath)) !== filePath) {
             throw new Error('Tool input changed after permission approval');
         }
     }
+    async assertStableCreationParent(filePath) {
+        const parent = dirname(filePath);
+        if ((await realpath(parent)) !== parent) {
+            throw new Error('Tool input changed after permission approval');
+        }
+    }
     async globRoot(requestedPath, context) {
         const displayedPath = isAbsolute(requestedPath)
             ? resolve(requestedPath)
@@ -1053,21 +1136,19 @@ export class LocalToolRegistry {
         await mkdir(parent, { recursive: true });
         return mkdtemp(join(parent, 'pdf-'));
     }
-    async write(call) {
+    async write(call, context, preparedTargetExisted) {
         const filePath = stringInput(call.input, 'file_path');
         this.assertProtectedWritePath(filePath);
-        const content = stringInput(call.input, 'content', true);
-        if (Buffer.byteLength(content) > this.maxFileBytes) {
-            throw new Error(`Content exceeds ${this.maxFileBytes} byte write limit`);
-        }
+        const requestedContent = stringInput(call.input, 'content', true);
         let handle;
         let newFile = false;
-        try {
-            handle = await open(filePath, constants.O_RDWR | constants.O_NOFOLLOW);
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT')
-                throw error;
+        const hasRead = await this.wasSuccessfullyRead(filePath, context.messages ?? [], context);
+        const targetExisted = preparedTargetExisted ?? (await this.pathExists(filePath));
+        if (!targetExisted) {
+            if (Buffer.byteLength(requestedContent) > this.maxFileBytes) {
+                throw new Error(`Content exceeds ${this.maxFileBytes} byte write limit`);
+            }
+            await this.assertStableCreationParent(filePath);
             try {
                 handle = await open(filePath, constants.O_RDWR |
                     constants.O_CREAT |
@@ -1076,19 +1157,40 @@ export class LocalToolRegistry {
                 newFile = true;
             }
             catch (createError) {
-                if (createError.code !== 'EEXIST') {
-                    throw createError;
+                if (createError.code === 'EEXIST') {
+                    throw new Error('<tool_use_error>File has not been read yet. Read it first before writing to it.</tool_use_error>');
                 }
+                throw createError;
+            }
+        }
+        else {
+            if (!hasRead) {
+                throw new Error('<tool_use_error>File has not been read yet. Read it first before writing to it.</tool_use_error>');
+            }
+            try {
                 handle = await open(filePath, constants.O_RDWR | constants.O_NOFOLLOW);
             }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    throw new Error('Tool input changed after permission approval');
+                }
+                throw error;
+            }
         }
         try {
             await this.assertStablePath(filePath);
             const metadata = await handle.stat();
             if (!metadata.isFile())
                 throw new Error(`Not a file: ${filePath}`);
+            if (!newFile && metadata.size > this.maxFileBytes) {
+                throw new Error(`File exceeds ${this.maxFileBytes} byte write limit`);
+            }
             const preContent = newFile ? '' : await handle.readFile('utf8');
+            const content = normalizeNewlines(requestedContent, newlineStyle(preContent));
             const encoded = Buffer.from(content);
+            if (encoded.length > this.maxFileBytes) {
+                throw new Error(`Content exceeds ${this.maxFileBytes} byte write limit`);
+            }
             const { linesAdded, linesRemoved } = countLineChanges(preContent, content, preContent === '' ? { newFile: true } : undefined);
             await handle.write(encoded, 0, encoded.length, 0);
             await handle.truncate(encoded.length);
@@ -1098,28 +1200,84 @@ export class LocalToolRegistry {
                 isError: false,
                 linesAdded,
                 linesRemoved,
+                nativeToolUseResult: { filePath, content },
             };
         }
         finally {
             await handle.close();
         }
     }
-    async edit(call) {
+    async edit(call, preparedTargetExisted) {
         const filePath = stringInput(call.input, 'file_path');
         this.assertProtectedWritePath(filePath);
-        const oldString = stringInput(call.input, 'old_string');
+        const oldString = stringInput(call.input, 'old_string', true);
         const newString = stringInput(call.input, 'new_string', true);
-        const handle = await open(filePath, constants.O_RDWR | constants.O_NOFOLLOW);
+        if (oldString === '' && Buffer.byteLength(newString) > this.maxFileBytes) {
+            throw new Error(`Content exceeds ${this.maxFileBytes} byte write limit`);
+        }
+        let handle;
+        let newFile = false;
+        if (oldString === '') {
+            const targetExisted = preparedTargetExisted ?? (await this.pathExists(filePath));
+            if (targetExisted) {
+                handle = await open(filePath, constants.O_RDWR | constants.O_NOFOLLOW);
+            }
+            else {
+                await this.assertStableCreationParent(filePath);
+                try {
+                    handle = await open(filePath, constants.O_RDWR |
+                        constants.O_CREAT |
+                        constants.O_EXCL |
+                        constants.O_NOFOLLOW, 0o666);
+                    newFile = true;
+                }
+                catch (error) {
+                    if (error.code === 'EEXIST') {
+                        throw new Error('Tool input changed after permission approval');
+                    }
+                    throw error;
+                }
+            }
+        }
+        else {
+            handle = await open(filePath, constants.O_RDWR | constants.O_NOFOLLOW);
+        }
         try {
             await this.assertStablePath(filePath);
             const metadata = await handle.stat();
             if (!metadata.isFile())
                 throw new Error(`Not a file: ${filePath}`);
+            if (newFile) {
+                const content = newString;
+                const encoded = Buffer.from(content);
+                if (encoded.length > this.maxFileBytes) {
+                    throw new Error(`Content exceeds ${this.maxFileBytes} byte write limit`);
+                }
+                const { linesAdded, linesRemoved } = countLineChanges('', content, {
+                    newFile: true,
+                });
+                await handle.write(encoded, 0, encoded.length, 0);
+                await handle.truncate(encoded.length);
+                await handle.sync();
+                return {
+                    content: `Replaced 1 occurrence(s)`,
+                    isError: false,
+                    linesAdded,
+                    linesRemoved,
+                    nativeToolUseResult: { filePath, content },
+                };
+            }
+            if (oldString === '') {
+                throw new Error('Edit with an empty old_string is only valid for creating a missing file');
+            }
             if (metadata.size > this.maxFileBytes) {
                 throw new Error(`File exceeds ${this.maxFileBytes} byte edit limit`);
             }
             const source = await handle.readFile('utf8');
-            const occurrences = source.split(oldString).length - 1;
+            const style = newlineStyle(source);
+            const normalizedOldString = normalizeNewlines(oldString, style);
+            const normalizedNewString = normalizeNewlines(newString, style);
+            const occurrences = source.split(normalizedOldString).length - 1;
             if (occurrences === 0)
                 throw new Error('old_string was not found');
             if (call.input.replace_all !== true && occurrences !== 1) {
@@ -1128,13 +1286,14 @@ export class LocalToolRegistry {
             const replacementCount = call.input.replace_all === true ? occurrences : 1;
             const outputBytes = Buffer.byteLength(source) +
                 replacementCount *
-                    (Buffer.byteLength(newString) - Buffer.byteLength(oldString));
+                    (Buffer.byteLength(normalizedNewString) -
+                        Buffer.byteLength(normalizedOldString));
             if (outputBytes > this.maxFileBytes) {
                 throw new Error(`Edited content exceeds ${this.maxFileBytes} bytes`);
             }
             const output = call.input.replace_all === true
-                ? source.replaceAll(oldString, newString)
-                : source.replace(oldString, newString);
+                ? source.replaceAll(normalizedOldString, normalizedNewString)
+                : source.replace(normalizedOldString, normalizedNewString);
             const { linesAdded, linesRemoved } = countLineChanges(source, output);
             const encoded = Buffer.from(output);
             await handle.write(encoded, 0, encoded.length, 0);
@@ -1145,6 +1304,7 @@ export class LocalToolRegistry {
                 isError: false,
                 linesAdded,
                 linesRemoved,
+                nativeToolUseResult: { filePath, content: output },
             };
         }
         finally {
@@ -1191,7 +1351,7 @@ export class LocalToolRegistry {
     async glob(call, context) {
         const requestedPath = call.input.path === undefined ? '.' : stringInput(call.input, 'path');
         const root = await this.globRoot(requestedPath, context);
-        const timeoutSignal = AbortSignal.timeout(this.maxShellTimeoutMs);
+        const timeoutSignal = AbortSignal.timeout(this.maxSearchTimeoutMs);
         const searchSignal = context.signal
             ? AbortSignal.any([context.signal, timeoutSignal])
             : timeoutSignal;
@@ -1215,7 +1375,7 @@ export class LocalToolRegistry {
                 throw abortError();
             if (timeoutSignal.aborted) {
                 return {
-                    content: `Search timed out after ${this.maxShellTimeoutMs}ms`,
+                    content: `Search timed out after ${this.maxSearchTimeoutMs}ms`,
                     isError: true,
                 };
             }
@@ -1240,14 +1400,14 @@ export class LocalToolRegistry {
         const result = await this.processRunner.run({
             command: 'rg',
             args,
-            timeoutMs: this.maxShellTimeoutMs,
+            timeoutMs: this.maxSearchTimeoutMs,
             cwd: this.currentCwd(context),
             ...(this.environment ? { env: this.environment } : {}),
             ...(context.signal ? { signal: context.signal } : {}),
         });
         if (result.timedOut) {
             return {
-                content: `Search timed out after ${this.maxShellTimeoutMs}ms`,
+                content: `Search timed out after ${this.maxSearchTimeoutMs}ms`,
                 isError: true,
             };
         }
@@ -1274,39 +1434,131 @@ export class LocalToolRegistry {
         };
         const sandboxed = this.sandbox?.shouldUseSandbox(sandboxPolicyInput) ?? false;
         const shell = commandShell();
+        let cwdToken;
+        let sandboxCommandAttempted = false;
         let result;
         try {
             const sessionEnvironment = context.sessionId
                 ? await this.sessionEnvironment?.(context.sessionId)
                 : undefined;
-            const command = sandboxed
-                ? await this.sandbox?.wrapCommand(sandboxPolicyInput, {
-                    shell,
+            const processEnvironment = this.environment || sessionEnvironment
+                ? { env: { ...this.environment, ...sessionEnvironment } }
+                : {};
+            let executionTimeout = timeout;
+            let syntaxTimeoutResult;
+            if (context.sessionId) {
+                const syntaxStartedAt = Date.now();
+                const syntaxResult = await this.processRunner.run({
+                    command: shell,
+                    args: commandShellSyntaxArguments(rawCommand),
+                    timeoutMs: timeout,
+                    cwd: this.currentBashCwd(context),
+                    ...processEnvironment,
                     ...(context.signal ? { signal: context.signal } : {}),
-                    commandId: call.id,
-                })
+                });
+                executionTimeout = Math.max(1, timeout - (Date.now() - syntaxStartedAt));
+                if (syntaxResult.timedOut) {
+                    syntaxTimeoutResult = syntaxResult;
+                }
+                else if (syntaxResult.code === 0) {
+                    cwdToken = randomBytes(16).toString('hex');
+                }
+            }
+            const controlOutputFd = cwdToken ? randomInt(5, 10) : undefined;
+            const statusVariable = cwdToken
+                ? `_praxis_exit_status_${cwdToken}`
+                : undefined;
+            const trapStatusVariable = cwdToken
+                ? `_praxis_trap_status_${cwdToken}`
+                : undefined;
+            const cwdReportCommand = cwdToken && controlOutputFd
+                ? `{ printf "%s%s\\0" "${cwdToken}" "$(pwd -P 2>/dev/null)" >&${controlOutputFd}; } 2>/dev/null`
+                : undefined;
+            const executionCommand = cwdToken && trapStatusVariable && cwdReportCommand
+                ? `if [ -n "\${ZSH_VERSION-}" ]; then 0=${JSON.stringify(shell)}; fi
+trap '${trapStatusVariable}=$?; ${cwdReportCommand}; exit "$${trapStatusVariable}"' EXIT
+${rawCommand}
+${statusVariable}=$?
+${cwdReportCommand}
+exit "$${statusVariable}"`
                 : rawCommand;
-            result = await this.processRunner.run({
-                command: shell,
-                args: commandShellArguments(command ?? rawCommand),
-                timeoutMs: timeout,
-                cwd: this.currentCwd(context),
-                ...(this.environment || sessionEnvironment
-                    ? { env: { ...this.environment, ...sessionEnvironment } }
-                    : {}),
-                ...(context.signal ? { signal: context.signal } : {}),
-            });
+            const scriptLoaderCommand = 'eval "$(cat <&4)"';
+            if (syntaxTimeoutResult) {
+                result = syntaxTimeoutResult;
+            }
+            else {
+                let command;
+                if (sandboxed) {
+                    sandboxCommandAttempted = true;
+                    command = await this.sandbox?.wrapCommand(cwdToken
+                        ? { ...sandboxPolicyInput, executionCommand: scriptLoaderCommand }
+                        : sandboxPolicyInput, {
+                        shell,
+                        ...(context.signal ? { signal: context.signal } : {}),
+                        commandId: call.id,
+                    });
+                }
+                else {
+                    command = cwdToken ? scriptLoaderCommand : rawCommand;
+                }
+                result = await this.processRunner.run({
+                    command: shell,
+                    args: commandShellArguments(command ?? rawCommand),
+                    timeoutMs: executionTimeout,
+                    cwd: this.currentBashCwd(context),
+                    ...processEnvironment,
+                    ...(context.signal ? { signal: context.signal } : {}),
+                    ...(cwdToken && controlOutputFd
+                        ? {
+                            controlOutputBytes: 8192,
+                            controlOutputFd,
+                            scriptInput: executionCommand,
+                        }
+                        : {}),
+                });
+            }
         }
         finally {
-            if (sandboxed)
+            if (sandboxCommandAttempted)
                 this.sandbox?.cleanupAfterCommand();
         }
-        if (sandboxed && this.sandbox) {
+        if (cwdToken) {
+            result = {
+                ...result,
+                stdout: stripShellControlTrace(result.stdout, cwdToken),
+                stderr: stripShellControlTrace(result.stderr, cwdToken),
+                output: stripShellControlTrace(result.output, cwdToken),
+            };
+        }
+        if (sandboxCommandAttempted && this.sandbox) {
             result = {
                 ...result,
                 stderr: this.sandbox.annotateStderr(call.id, result.stderr),
             };
         }
+        if (cwdToken && !result.timedOut && result.controlOutput) {
+            const controlRecord = result.controlOutput.startsWith(cwdToken)
+                ? result.controlOutput.slice(cwdToken.length)
+                : undefined;
+            const terminator = controlRecord?.indexOf('\0') ?? -1;
+            const record = controlRecord && terminator > 0
+                ? controlRecord.slice(0, terminator)
+                : undefined;
+            if (record) {
+                try {
+                    const canonicalCwd = await realpath(record);
+                    if ((await stat(canonicalCwd)).isDirectory() && context.sessionId) {
+                        this.sessionCwds.set(context.sessionId, {
+                            cwd: canonicalCwd,
+                            hostCwd: resolve(context.cwd || this.cwdProvider?.() || this.cwd),
+                        });
+                    }
+                }
+                catch {
+                    // A command may remove or replace its final directory. Keep prior state.
+                }
+            }
+        }
         if (result.timedOut) {
             return {
                 content: `Command timed out after ${timeout}ms`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.46.2",
+  "version": "0.46.4",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",