iosm-cli 0.2.9 → 0.2.11

package/dist/core/agent-session.js

@@ -14,7 +14,7 @@
  */
 import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { isContextOverflow, modelsAreEqual, resetApiProviders, supportsXhigh } from "@mariozechner/pi-ai";
+import { completeSimple, isContextOverflow, modelsAreEqual, resetApiProviders, supportsXhigh } from "@mariozechner/pi-ai";
 import { getDocsPath, getSessionTracePath, isSessionTraceEnabled } from "../config.js";
 import { buildIosmRuntimeDirective, prepareIosmRuntimeContext } from "../iosm/runtime-context.js";
 import { theme } from "../modes/interactive/theme/theme.js";
@@ -28,6 +28,7 @@ import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { ExtensionRunner, wrapRegisteredTools, wrapToolsWithExtensions, } from "./extensions/index.js";
 import { INTERNAL_UI_META_CUSTOM_TYPE } from "./messages.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
+import { startBackgroundProcess } from "./background-processes.js";
 import { getLatestCompactionEntry } from "./session-manager.js";
 import { BUILTIN_SLASH_COMMANDS } from "./slash-commands.js";
 import { buildSystemPrompt } from "./system-prompt.js";
@@ -35,6 +36,7 @@ import { isReadOnlyProfileName } from "./agent-profiles.js";
 import { applyPostToolUseHooks, applyPreToolUseHooks, applyStopHooks, applyUserPromptSubmitHooks, emptyHooksConfig, } from "./hooks.js";
 import { extractTaskPlanFromAssistantMessage, formatTaskPlanMessageContent, taskPlanSignature, TASK_PLAN_CUSTOM_TYPE, } from "./task-plan.js";
 import { createAllTools, getAllowedFetchMethodsForProfile } from "./tools/index.js";
+import { ULTRATHINK_CHECKPOINT_COMPRESSION_SYSTEM_PROMPT, ULTRATHINK_MAX_CHECKPOINT_CHARS, ULTRATHINK_MAX_ITERATION_INPUT_TOKENS, ULTRATHINK_MAX_RUN_COST, ULTRATHINK_MAX_RUN_INPUT_TOKENS, ULTRATHINK_MAX_RUN_TOTAL_TOKENS, ULTRATHINK_STAGNATION_LIMIT, ULTRATHINK_VISIBLE_PROMPT_PREFIX, buildUltrathinkCheckpointCompressionPrompt, buildUltrathinkBudgetStatusLine, buildUltrathinkComplianceRepairPrompt, buildUltrathinkContextTail, buildUltrathinkEvidenceCatalog, buildUltrathinkIterationPrompt, buildUltrathinkToolGroundingPrompt, buildUltrathinkVisibleIterationPrompt, createInitialUltrathinkCheckpoint, evaluateUltrathinkEvidencePolicy, extractUltrathinkCheckpoint, extractUltrathinkIterationSummary, extractUltrathinkToolEvidence, findLastMeaningfulUserIntent, getUltrathinkPhase, hasUltrathinkEvidenceViolations, isUltrathinkStagnated, normalizeUltrathinkCheckpoint, parseUltrathinkCommand, resolveUltrathinkReadOnlyTools, shouldUltrathinkForceToolGrounding, truncateUltrathinkCheckpoint, ULTRATHINK_USAGE, } from "./ultrathink.js";
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
@@ -252,6 +254,16 @@ const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
 const MAX_PROMPT_PROTOCOL_AUTO_REPAIR_ATTEMPTS = 2;
 /** Thinking levels including xhigh (for supported models) */
 const THINKING_LEVELS_WITH_XHIGH = ["off", "minimal", "low", "medium", "high", "xhigh"];
+const BUILTIN_TOOL_REQUIRED_PERMISSIONS = {
+    bash: "danger-full-access",
+    edit: "workspace-write",
+    write: "workspace-write",
+    fetch: "read-only",
+    web_search: "read-only",
+    git_write: "workspace-write",
+    fs_ops: "workspace-write",
+    db_run: "workspace-write",
+};
 // ============================================================================
 // AgentSession Class
 // ============================================================================
@@ -291,6 +303,7 @@ export class AgentSession {
         this._toolRegistry = new Map();
         this._toolPromptSnippets = new Map();
         this._toolPromptGuidelines = new Map();
+        this._toolRequiredPermissions = new Map();
         this._subagentStartMeta = new Map();
         // Base system prompt (without extension appends) - used to apply fresh appends each turn
         this._baseSystemPrompt = "";
@@ -299,6 +312,7 @@ export class AgentSession {
         this._pendingHookNotices = [];
         this._sessionTraceEnabled = isSessionTraceEnabled();
         this._protocolAutoRepairActive = false;
+        this._ultrathinkActive = false;
         // Track last assistant message for auto-compaction check
         this._lastAssistantMessage = undefined;
         this._lastTaskPlanSignature = undefined;
@@ -1002,6 +1016,32 @@ export class AgentSession {
         }
         return Array.from(unique);
     }
+    _summarizeToolPermissionInput(input) {
+        let preview = "{}";
+        try {
+            preview = JSON.stringify(input);
+        }
+        catch {
+            preview = "{...}";
+        }
+        if (preview.length > 200) {
+            preview = `${preview.slice(0, 197)}...`;
+        }
+        return preview;
+    }
+    async _evaluateToolPermission(request) {
+        const normalizedRequest = {
+            ...request,
+            requiredPermission: request.requiredPermission ?? this._toolRequiredPermissions.get(request.toolName) ?? undefined,
+            toolSource: request.toolSource ?? "builtin",
+        };
+        const hookResult = applyPreToolUseHooks(this._hooksConfig, normalizedRequest);
+        this._queueHookNotices("PreToolUse", hookResult.notices);
+        if (!hookResult.allowed) {
+            throw new Error(hookResult.message ?? "Tool blocked by PreToolUse hook.");
+        }
+        return this._toolPermissionHandler ? this._toolPermissionHandler(normalizedRequest) : true;
+    }
     _rebuildSystemPrompt(toolNames) {
         const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
         const toolSnippets = {};
@@ -1033,15 +1073,35 @@ export class AgentSession {
                 return true;
             return this._iosmAutopilotEnabled ? isIosmPlaybook : isAgentsPlaybook;
         });
+        const promptContextOptions = {
+            enableContextDedupe: this.settingsManager.getPromptContextEnableDedupe(),
+            maxContextCharsPerFile: this.settingsManager.getPromptContextMaxCharsPerFile(),
+            maxTotalContextChars: this.settingsManager.getPromptContextMaxTotalChars(),
+            enableGitSnapshotContext: this.settingsManager.getPromptContextEnableGitSnapshotContext(),
+        };
         return buildSystemPrompt({
             cwd: this._cwd,
             skills: loadedSkills,
             contextFiles: loadedContextFiles,
+            contextProcessing: promptContextOptions,
             customPrompt: loaderSystemPrompt,
             appendSystemPrompt,
             selectedTools: validToolNames,
             toolSnippets,
             promptGuidelines,
+            onContextProcessed: (stats) => {
+                this._appendSessionTrace({
+                    type: "system_prompt_context_compose",
+                    context_before_chars: stats.contextBeforeChars,
+                    context_after_chars: stats.contextAfterChars,
+                    dedupe_hits: stats.dedupeHits,
+                    truncated_files: stats.truncatedFiles,
+                    dropped_files: stats.droppedFiles,
+                    included_files: stats.includedFiles,
+                    total_files: stats.totalFiles,
+                    git_snapshot_included: stats.gitSnapshotIncluded,
+                });
+            },
         });
     }
     // =========================================================================
@@ -1066,6 +1126,22 @@ export class AgentSession {
             source: inputSource,
             imageCount: options?.images?.length ?? 0,
         });
+        if (!options?.skipUltrathinkCommand) {
+            const ultrathinkParseResult = parseUltrathinkCommand(text);
+            if (ultrathinkParseResult?.kind === "error") {
+                throw new Error(`${ultrathinkParseResult.error}\n\n${ultrathinkParseResult.usage}`);
+            }
+            if (ultrathinkParseResult?.kind === "command") {
+                await this._runUltrathinkCommand(ultrathinkParseResult.command, { source: inputSource });
+                this._appendSessionTrace({
+                    type: "prompt_handled_by_command",
+                    text,
+                    command: "ultrathink",
+                    iterations: ultrathinkParseResult.command.iterations,
+                });
+                return;
+            }
+        }
         // Handle extension commands first (execute immediately, even during streaming)
         // Extension commands manage their own LLM interaction via iosm.sendMessage()
         if (expandPromptTemplates && text.startsWith("/")) {
@@ -1313,6 +1389,289 @@ export class AgentSession {
             }
         }
     }
+    async _runUltrathinkCommand(command, options) {
+        if (this.isStreaming) {
+            throw new Error("Cannot start /ultrathink while the agent is processing another request.");
+        }
+        if (this.isCompacting) {
+            throw new Error("Cannot start /ultrathink while compaction is running.");
+        }
+        if (this._ultrathinkActive) {
+            throw new Error("An /ultrathink run is already in progress.");
+        }
+        if (!this.model) {
+            throw new Error("No model selected.\n\n" +
+                `Use /login or set an API key environment variable. See ${join(getDocsPath(), "providers.md")}\n\n` +
+                "Then use /model to select a model.");
+        }
+        const apiKey = await this._modelRegistry.getApiKey(this.model);
+        if (!apiKey) {
+            const isOAuth = this._modelRegistry.isUsingOAuth(this.model);
+            if (isOAuth) {
+                throw new Error(`Authentication failed for "${this.model.provider}". ` +
+                    `Credentials may have expired or network is unavailable. ` +
+                    `Run '/login ${this.model.provider}' to re-authenticate.`);
+            }
+            throw new Error(`No API key found for ${this.model.provider}.\n\n` +
+                `Use /login or set an API key environment variable. See ${join(getDocsPath(), "providers.md")}`);
+        }
+        const objective = command.query?.trim() || findLastMeaningfulUserIntent(this.messages);
+        if (!objective) {
+            throw new Error([
+                "Cannot infer an objective for /ultrathink from session context.",
+                "Provide a query explicitly or send a regular user request first.",
+                "",
+                ULTRATHINK_USAGE,
+            ].join("\n"));
+        }
+        const originalTools = this.getActiveToolNames();
+        const availableToolNames = this.getAllTools().map((tool) => tool.name);
+        const readOnlyTools = resolveUltrathinkReadOnlyTools(availableToolNames);
+        if (readOnlyTools.length === 0) {
+            throw new Error([
+                "Cannot start /ultrathink: no read-only tools are currently active.",
+                "Enable at least one analysis tool (for example read/rg/find/semantic_search/fetch/git_read) and retry.",
+            ].join("\n"));
+        }
+        const contextTail = buildUltrathinkContextTail(this.messages);
+        let checkpoint = createInitialUltrathinkCheckpoint(objective);
+        let previousSummary;
+        let accumulatedInputTokens = 0;
+        let accumulatedTotalTokens = 0;
+        let accumulatedCost = 0;
+        let stagnationCount = 0;
+        let targetIterations = command.iterations;
+        let enforceEvidencePolicy = true;
+        const evidenceById = new Map();
+        const mergeEvidence = (messages) => {
+            const evidence = extractUltrathinkToolEvidence(messages);
+            for (const entry of evidence) {
+                evidenceById.set(entry.toolCallId, entry);
+            }
+            return evidence.length;
+        };
+        const registerUsage = (assistantMessage) => {
+            const usage = assistantMessage?.usage;
+            const inputTokens = Number(usage?.input ?? 0);
+            const totalTokens = Number(usage?.totalTokens ?? inputTokens + Number(usage?.output ?? 0));
+            const costTotal = Number(usage?.cost?.total ?? 0);
+            accumulatedInputTokens += inputTokens;
+            accumulatedTotalTokens += totalTokens;
+            accumulatedCost += costTotal;
+            return { inputTokens, totalTokens, costTotal };
+        };
+        const exceedsBudget = (iterationInputTokens) => iterationInputTokens > ULTRATHINK_MAX_ITERATION_INPUT_TOKENS ||
+            accumulatedInputTokens > ULTRATHINK_MAX_RUN_INPUT_TOKENS ||
+            accumulatedTotalTokens > ULTRATHINK_MAX_RUN_TOTAL_TOKENS ||
+            accumulatedCost > ULTRATHINK_MAX_RUN_COST;
+        const runUltrathinkInternalPrompt = async (rawPrompt, displayText) => {
+            this._appendCustomMessageLocally({
+                customType: INTERNAL_UI_META_CUSTOM_TYPE,
+                content: "",
+                display: false,
+                details: {
+                    kind: "orchestration_context",
+                    rawPrompt,
+                    displayText,
+                },
+            });
+            const messageCountBefore = this.messages.length;
+            await this.prompt(rawPrompt, {
+                expandPromptTemplates: false,
+                skipIosmAutopilot: true,
+                skipOrchestrationDirective: true,
+                skipUltrathinkCommand: true,
+                source: options.source,
+            });
+            return this.messages.slice(messageCountBefore);
+        };
+        this._ultrathinkActive = true;
+        this.setActiveToolsByName(readOnlyTools);
+        try {
+            for (let iteration = 1; iteration <= targetIterations; iteration++) {
+                const phase = iteration === targetIterations ? "Synthesis" : getUltrathinkPhase(iteration, targetIterations);
+                const evidenceCatalog = buildUltrathinkEvidenceCatalog([...evidenceById.values()]);
+                const budgetStatus = buildUltrathinkBudgetStatusLine({
+                    accumulatedInputTokens,
+                    accumulatedTotalTokens,
+                    accumulatedCost,
+                });
+                const iterationPrompt = buildUltrathinkIterationPrompt({
+                    iteration,
+                    totalIterations: targetIterations,
+                    phase,
+                    objective,
+                    checkpoint,
+                    previousSummary,
+                    contextTail: iteration === 1 ? contextTail : undefined,
+                    evidenceCatalog,
+                    budgetStatus,
+                });
+                const visibleIterationPrompt = buildUltrathinkVisibleIterationPrompt({
+                    iteration,
+                    totalIterations: targetIterations,
+                    phase,
+                    objective,
+                });
+                const iterationMessages = await runUltrathinkInternalPrompt(iterationPrompt, visibleIterationPrompt);
+                let toolChecksThisIteration = mergeEvidence(iterationMessages);
+                let assistantMessage = this._findLastAssistantMessage();
+                let assistantText = this.getLastAssistantText() ?? "";
+                let iterationUsage = registerUsage(assistantMessage);
+                let iterationInputTokens = iterationUsage.inputTokens;
+                const evaluatePolicy = () => evaluateUltrathinkEvidencePolicy({
+                    text: assistantText,
+                    phase,
+                    toolChecksThisIteration,
+                    knownEvidenceIds: [...evidenceById.keys()],
+                });
+                const shouldGround = shouldUltrathinkForceToolGrounding({
+                    phase,
+                    cumulativeEvidenceCount: evidenceById.size,
+                    toolChecksThisIteration,
+                });
+                if (shouldGround) {
+                    const groundingPrompt = buildUltrathinkToolGroundingPrompt({
+                        iteration,
+                        totalIterations: targetIterations,
+                        phase,
+                        objective,
+                        checkpoint,
+                        availableReadOnlyTools: readOnlyTools,
+                        evidenceCatalog: buildUltrathinkEvidenceCatalog([...evidenceById.values()]),
+                    });
+                    const groundingDisplayText = `${ULTRATHINK_VISIBLE_PROMPT_PREFIX} ${iteration}/${targetIterations} (${phase}) grounding retry. Performing live workspace probes with read-only tools.`;
+                    const groundingMessages = await runUltrathinkInternalPrompt(groundingPrompt, groundingDisplayText);
+                    toolChecksThisIteration += mergeEvidence(groundingMessages);
+                    assistantMessage = this._findLastAssistantMessage();
+                    assistantText = this.getLastAssistantText() ?? "";
+                    iterationUsage = registerUsage(assistantMessage);
+                    iterationInputTokens += iterationUsage.inputTokens;
+                }
+                if (enforceEvidencePolicy) {
+                    let evidencePolicy = evaluatePolicy();
+                    if (hasUltrathinkEvidenceViolations(evidencePolicy)) {
+                        const policyIssues = [];
+                        if (evidencePolicy.missingEvidenceForNumbers) {
+                            policyIssues.push("Quantitative claims are missing `[evidence:<toolCallId>]` tags.");
+                        }
+                        if (evidencePolicy.invalidEvidenceTags.length > 0) {
+                            policyIssues.push(`Unknown evidence tags: ${evidencePolicy.invalidEvidenceTags.join(", ")}`);
+                        }
+                        if (evidencePolicy.needsNoNewEvidenceMarker && !evidencePolicy.hasNoNewEvidenceMarker) {
+                            policyIssues.push("Verify/Synthesis response with no new tool checks must include [NO_NEW_EVIDENCE_OK].");
+                        }
+                        const repairPrompt = buildUltrathinkComplianceRepairPrompt({
+                            iteration,
+                            totalIterations: targetIterations,
+                            phase,
+                            objective,
+                            originalResponse: assistantText,
+                            issues: policyIssues,
+                            checkpoint,
+                            evidenceCatalog: buildUltrathinkEvidenceCatalog([...evidenceById.values()]),
+                        });
+                        const repairDisplayText = `${ULTRATHINK_VISIBLE_PROMPT_PREFIX} ${iteration}/${targetIterations} (${phase}) policy repair. Normalizing evidence links and checkpoint format.`;
+                        const repairMessages = await runUltrathinkInternalPrompt(repairPrompt, repairDisplayText);
+                        toolChecksThisIteration += mergeEvidence(repairMessages);
+                        assistantMessage = this._findLastAssistantMessage();
+                        assistantText = this.getLastAssistantText() ?? "";
+                        iterationUsage = registerUsage(assistantMessage);
+                        iterationInputTokens += iterationUsage.inputTokens;
+                        evidencePolicy = evaluatePolicy();
+                        if (hasUltrathinkEvidenceViolations(evidencePolicy)) {
+                            // Do not fail the entire run; keep the latest usable answer and finish gracefully.
+                            enforceEvidencePolicy = false;
+                            if (iteration < targetIterations) {
+                                targetIterations = Math.min(targetIterations, iteration + 1);
+                            }
+                        }
+                    }
+                }
+                previousSummary = extractUltrathinkIterationSummary(assistantText);
+                const checkpointBeforeIteration = checkpoint;
+                const extractedCheckpoint = extractUltrathinkCheckpoint(assistantText);
+                if (extractedCheckpoint && extractedCheckpoint.trim()) {
+                    checkpoint = normalizeUltrathinkCheckpoint(extractedCheckpoint, objective);
+                }
+                if (checkpoint.length > ULTRATHINK_MAX_CHECKPOINT_CHARS) {
+                    checkpoint = await this._compressUltrathinkCheckpoint(checkpoint, objective, apiKey);
+                }
+                const stagnated = isUltrathinkStagnated({
+                    previousCheckpoint: checkpointBeforeIteration,
+                    nextCheckpoint: checkpoint,
+                    toolChecksThisIteration,
+                });
+                if (stagnated && iteration < targetIterations) {
+                    stagnationCount += 1;
+                    if (stagnationCount >= ULTRATHINK_STAGNATION_LIMIT) {
+                        targetIterations = Math.min(targetIterations, iteration + 1);
+                    }
+                }
+                else {
+                    stagnationCount = 0;
+                }
+                if (iteration < targetIterations && exceedsBudget(iterationInputTokens)) {
+                    targetIterations = Math.min(targetIterations, iteration + 1);
+                }
+            }
+        }
+        finally {
+            this._ultrathinkActive = false;
+            const currentTools = this.getActiveToolNames();
+            const shouldRestore = currentTools.length !== originalTools.length ||
+                currentTools.some((toolName, index) => toolName !== originalTools[index]);
+            if (shouldRestore) {
+                this.setActiveToolsByName(originalTools);
+            }
+        }
+    }
+    async _compressUltrathinkCheckpoint(checkpoint, objective, apiKey) {
+        const model = this.model;
+        const fallback = truncateUltrathinkCheckpoint(normalizeUltrathinkCheckpoint(checkpoint, objective), ULTRATHINK_MAX_CHECKPOINT_CHARS);
+        if (!model)
+            return fallback;
+        const reserveTokens = this.settingsManager.getCompactionReserveTokens();
+        const maxTokens = Math.max(256, Math.min(2048, Math.floor(reserveTokens * 0.4)));
+        try {
+            const response = await completeSimple(model, {
+                systemPrompt: ULTRATHINK_CHECKPOINT_COMPRESSION_SYSTEM_PROMPT,
+                messages: [
+                    {
+                        role: "user",
+                        content: [
+                            {
+                                type: "text",
+                                text: buildUltrathinkCheckpointCompressionPrompt({
+                                    objective,
+                                    checkpoint,
+                                    maxChars: ULTRATHINK_MAX_CHECKPOINT_CHARS,
+                                }),
+                            },
+                        ],
+                        timestamp: Date.now(),
+                    },
+                ],
+            }, model.reasoning
+                ? { maxTokens, apiKey, reasoning: "high" }
+                : { maxTokens, apiKey });
+            if (response.stopReason === "error") {
+                return fallback;
+            }
+            const text = response.content
+                .filter((part) => part.type === "text")
+                .map((part) => part.text)
+                .join("\n")
+                .trim();
+            if (!text) {
+                return fallback;
+            }
+            return truncateUltrathinkCheckpoint(normalizeUltrathinkCheckpoint(text, objective), ULTRATHINK_MAX_CHECKPOINT_CHARS);
+        }
+        catch {
+            return fallback;
+        }
+    }
     /**
      * Try to execute an extension command. Returns true if command was found and executed.
      */
@@ -2466,11 +2825,18 @@ export class AgentSession {
     _refreshToolRegistry(options) {
         const previousRegistryNames = new Set(this._toolRegistry.keys());
         const previousActiveToolNames = this.getActiveToolNames();
+        const enforceExtensionToolPermissions = this.settingsManager.getPermissionExtensionToolEnforcement();
         const registeredTools = this._extensionRunner?.getAllRegisteredTools() ?? [];
         const allCustomTools = [
             ...registeredTools,
             ...this._customTools.map((def) => ({ definition: def, extensionPath: "<sdk>" })),
         ];
+        const requiredPermissionEntries = Object.entries(BUILTIN_TOOL_REQUIRED_PERMISSIONS).map(([name, permission]) => [name, permission]);
+        this._toolRequiredPermissions = new Map(requiredPermissionEntries);
+        for (const registeredTool of allCustomTools) {
+            const existing = this._toolRequiredPermissions.get(registeredTool.definition.name);
+            this._toolRequiredPermissions.set(registeredTool.definition.name, registeredTool.definition.requiredPermission ?? existing);
+        }
         this._toolPromptSnippets = new Map(allCustomTools
             .map((registeredTool) => {
             const snippet = this._normalizePromptSnippet(registeredTool.definition.promptSnippet ?? registeredTool.definition.description);
@@ -2484,7 +2850,24 @@ export class AgentSession {
         })
             .filter((entry) => entry !== undefined));
         const wrappedExtensionTools = this._extensionRunner
-            ? wrapRegisteredTools(allCustomTools, this._extensionRunner)
+            ? wrapRegisteredTools(allCustomTools, this._extensionRunner, (registeredTool) => {
+                const toolSource = registeredTool.extensionPath === "<sdk>" ? "custom" : "extension";
+                return {
+                    toolSource,
+                    permissionPolicy: {
+                        enabled: enforceExtensionToolPermissions && toolSource === "extension",
+                        guard: async (request) => this._evaluateToolPermission(request),
+                        createRequest: ({ toolName, params, requiredPermission, toolSource: source }) => ({
+                            toolName,
+                            cwd: this._cwd,
+                            input: params,
+                            summary: `Extension tool ${toolName} ${this._summarizeToolPermissionInput(params)}`,
+                            requiredPermission,
+                            toolSource: source,
+                        }),
+                    },
+                };
+            })
             : [];
         const toolRegistry = new Map(this._baseToolRegistry);
         for (const tool of wrappedExtensionTools) {
@@ -2517,46 +2900,26 @@ export class AgentSession {
     _buildRuntime(options) {
         const autoResizeImages = this.settingsManager.getImageAutoResize();
         const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
-        const evaluatePreToolHooks = (request) => {
-            const hookResult = applyPreToolUseHooks(this._hooksConfig, request);
-            this._queueHookNotices("PreToolUse", hookResult.notices);
-            if (!hookResult.allowed) {
-                throw new Error(hookResult.message ?? "Tool blocked by PreToolUse hook.");
-            }
-            return true;
-        };
         const baseTools = this._baseToolsOverride
             ? this._baseToolsOverride
             : createAllTools(this._cwd, {
                 read: { autoResizeImages },
                 bash: {
                     commandPrefix: shellCommandPrefix,
-                    permissionGuard: async (request) => {
-                        evaluatePreToolHooks(request);
-                        return this._toolPermissionHandler ? this._toolPermissionHandler(request) : true;
-                    },
+                    permissionGuard: async (request) => this._evaluateToolPermission(request),
                 },
                 edit: {
-                    permissionGuard: async (request) => {
-                        evaluatePreToolHooks(request);
-                        return this._toolPermissionHandler ? this._toolPermissionHandler(request) : true;
-                    },
+                    permissionGuard: async (request) => this._evaluateToolPermission(request),
                 },
                 write: {
-                    permissionGuard: async (request) => {
-                        evaluatePreToolHooks(request);
-                        return this._toolPermissionHandler ? this._toolPermissionHandler(request) : true;
-                    },
+                    permissionGuard: async (request) => this._evaluateToolPermission(request),
                 },
                 semantic: {
                     authStorage: this._modelRegistry.authStorage,
                 },
                 fetch: {
                     resolveAllowedMethods: () => getAllowedFetchMethodsForProfile(this._profileName),
-                    permissionGuard: async (request) => {
-                        evaluatePreToolHooks(request);
-                        return this._toolPermissionHandler ? this._toolPermissionHandler(request) : true;
-                    },
+                    permissionGuard: async (request) => this._evaluateToolPermission(request),
                 },
                 webSearch: {
                     resolveRuntimeConfig: () => ({
@@ -2569,33 +2932,21 @@ export class AgentSession {
                     }),
                     resolveTavilyApiKey: () => this.settingsManager.getWebSearchTavilyApiKey(),
                     resolveSearxngBaseUrl: () => this.settingsManager.getWebSearchSearxngUrl(),
-                    permissionGuard: async (request) => {
-                        evaluatePreToolHooks(request);
-                        return this._toolPermissionHandler ? this._toolPermissionHandler(request) : true;
-                    },
+                    permissionGuard: async (request) => this._evaluateToolPermission(request),
                 },
                 gitWrite: {
                     resolveRuntimeConfig: () => ({
                         networkEnabled: this.settingsManager.getGithubToolsNetworkEnabled(),
                     }),
                     resolveGithubToken: () => this.settingsManager.getGithubToolsToken(),
-                    permissionGuard: async (request) => {
-                        evaluatePreToolHooks(request);
-                        return this._toolPermissionHandler ? this._toolPermissionHandler(request) : true;
-                    },
+                    permissionGuard: async (request) => this._evaluateToolPermission(request),
                 },
                 fsOps: {
-                    permissionGuard: async (request) => {
-                        evaluatePreToolHooks(request);
-                        return this._toolPermissionHandler ? this._toolPermissionHandler(request) : true;
-                    },
+                    permissionGuard: async (request) => this._evaluateToolPermission(request),
                 },
                 dbRun: {
                     resolveRuntimeConfig: () => this.settingsManager.getDbToolsSettings(),
-                    permissionGuard: async (request) => {
-                        evaluatePreToolHooks(request);
-                        return this._toolPermissionHandler ? this._toolPermissionHandler(request) : true;
-                    },
+                    permissionGuard: async (request) => this._evaluateToolPermission(request),
                 },
             });
         this._baseToolRegistry = new Map(Object.entries(baseTools).map(([name, tool]) => [name, tool]));
@@ -2801,16 +3152,39 @@ export class AgentSession {
         const prefix = this.settingsManager.getShellCommandPrefix();
         const resolvedCommand = prefix ? `${prefix}\n${command}` : command;
         try {
-            const result = options?.operations
-                ? await executeBashWithOperations(resolvedCommand, this._cwd, options.operations, {
-                    onChunk,
-                    signal: this._bashAbortController.signal,
-                })
-                : await executeBashCommand(resolvedCommand, {
+            let result;
+            if (options?.runInBackground) {
+                if (options.operations) {
+                    throw new Error("Background bash is not supported with custom execution operations.");
+                }
+                const background = startBackgroundProcess({
+                    rootCwd: this._cwd,
                     cwd: this._cwd,
-                    onChunk,
-                    signal: this._bashAbortController.signal,
+                    command: resolvedCommand,
+                    source: "interactive",
                 });
+                result = {
+                    output: `Started background process ${background.id} (pid ${background.pid}). Use /bg status ${background.id}, /bg logs ${background.id}, or /bg stop ${background.id}.`,
+                    exitCode: undefined,
+                    cancelled: false,
+                    truncated: false,
+                    backgroundTaskId: background.id,
+                    backgroundStatusPath: background.metaPath,
+                    backgroundLogPath: background.logPath,
+                };
+            }
+            else {
+                result = options?.operations
+                    ? await executeBashWithOperations(resolvedCommand, this._cwd, options.operations, {
+                        onChunk,
+                        signal: this._bashAbortController.signal,
+                    })
+                    : await executeBashCommand(resolvedCommand, {
+                        cwd: this._cwd,
+                        onChunk,
+                        signal: this._bashAbortController.signal,
+                    });
+            }
             this.recordBashResult(command, result, options);
             this._appendSessionTrace({
                 type: "bash_end",
@@ -2818,6 +3192,7 @@ export class AgentSession {
                 exitCode: result.exitCode,
                 cancelled: result.cancelled,
                 truncated: result.truncated,
+                backgroundTaskId: result.backgroundTaskId ?? null,
             });
             return result;
         }