goatchain 0.0.24 → 0.0.26

package/dist/session/completion/types.d.ts

@@ -0,0 +1,53 @@
+import type { AgentLoopState } from '../../agent/types';
+import type { MessageContent } from '../../types';
+import type { TodoItem } from '../../tool/builtin/todoWrite';
+/**
+ * Result of a completion assessment.
+ *
+ * Returned by a `CompletionAssessor` to indicate whether the current task
+ * is complete or if the loop should continue with a follow-up message.
+ */
+export interface CompletionAssessment {
+    /** Whether the task is considered complete */
+    isComplete: boolean;
+    /** Human-readable reason for the assessment */
+    reason?: string;
+    /** Message to inject as a user message if !isComplete */
+    followUpMessage?: string;
+    /** Confidence score (0-1) for the assessment */
+    confidence?: number;
+}
+/**
+ * Context provided to completion assessors.
+ *
+ * Contains everything an assessor needs to judge whether the task is complete.
+ */
+export interface CompletionContext {
+    /** Current agent loop state (messages, response, iteration, etc.) */
+    state: AgentLoopState;
+    /** The original user input that started this session run */
+    originalInput: MessageContent;
+    /** Current todo items from TodoWriteTool (if available) */
+    todoItems?: TodoItem[];
+    /** Which follow-up round we are on (0 = first assessment) */
+    followUpRound: number;
+    /** Maximum follow-up rounds allowed */
+    maxFollowUpRounds: number;
+}
+/**
+ * Interface for completion assessment strategies.
+ *
+ * Implementations determine whether the agent's task is truly complete
+ * or if the loop should continue with additional instructions.
+ */
+export interface CompletionAssessor {
+    /** Name of this assessor (for logging and events) */
+    readonly name: string;
+    /**
+     * Assess whether the task is complete.
+     *
+     * @param context - Assessment context with state, todos, etc.
+     * @returns Assessment result indicating completion status
+     */
+    assess(context: CompletionContext): Promise<CompletionAssessment>;
+}

package/dist/session/executors/ToolExecutor.d.ts

@@ -1,4 +1,4 @@
-import type { ToolHooks } from '../../agent/hooks';
+import type { AgentHooks } from '../../agent/hooks';
 import type { AgentLoopState, ToolCallWithResult } from '../../agent/types';
 import type { ToolExecutionContext, ToolExecutionContextInput, ToolRegistry } from '../../tool';
 import type { AgentEvent, AgentLoopCheckpoint, CheckpointModelConfig, CheckpointRequestParams, ToolCall } from '../../types';
@@ -29,14 +29,14 @@ export declare class ToolExecutor {
     constructor(options: ToolExecutorOptions);
     private _log;
     createToolExecutionContext(state: AgentLoopState, signal?: AbortSignal, toolCallId?: string, toolName?: string): ToolExecutionContext;
-    executeToolCall(tc: ToolCallWithResult, ctx: ToolExecutionContext, signal?: AbortSignal, hooks?: ToolHooks, preToolUseResult?: {
+    executeToolCall(tc: ToolCallWithResult, ctx: ToolExecutionContext, signal?: AbortSignal, hooks?: AgentHooks, permissionRequestResult?: {
         allow: boolean;
         modifiedToolCall?: ToolCall;
-    }): Promise<AgentEvent>;
+    }, skipPreToolUseHook?: boolean): Promise<AgentEvent>;
     handleToolCalls(state: AgentLoopState, toolContext: ToolExecutionContext, options?: {
         signal?: AbortSignal;
         toolContextInput?: ToolExecutionContextInput;
-        hooks?: ToolHooks;
+        hooks?: AgentHooks;
         checkpointModelConfig?: CheckpointModelConfig;
         requestParams?: CheckpointRequestParams;
     }): AsyncIterable<AgentEvent>;

package/dist/session/session.d.ts

@@ -63,6 +63,7 @@ export declare class Session extends EventEmitter {
     private readonly _requestParams?;
     private readonly _emitSessionCreatedEvent;
     private _sessionCreatedEventEmitted;
+    private _sessionStartHookEmitted;
     private _abortController;
     private readonly _enableLogging;
     private _checkpointOriginalMessages?;
@@ -163,8 +164,16 @@ export declare class Session extends EventEmitter {
      * Check if there's an assistant message containing the tool call
      */
     private hasAssistantToolCallMessage;
+    /**
+     * Get current todo items from the TodoWriteTool (if registered).
+     * Used to populate state.metadata._todoItems for middleware access.
+     * @internal
+     */
+    private _getTodoItems;
     private handleFinalResponse;
     private _finalizeRun;
+    private _executeStopHook;
+    private getStopReasonForModelResponse;
     /**
      * Get preview of the last message (truncated for display)
      *

package/dist/state/types.d.ts

@@ -81,9 +81,10 @@ export interface CompressionState {
      */
     compressedRange?: {
         /**
-         * Index after first turn ends (messages before this are kept).
+         * Index where summarization starts (first non-system message).
+         * Messages before this index (system messages) are always kept.
          */
-        firstTurnEnd: number;
+        summarizeStart: number;
         /**
          * Index where protected turns start (messages from this onward are kept).
          */

package/dist/subagent/index.d.ts

@@ -7,3 +7,4 @@
 export * from './bash-validator';
 export * from './explore';
 export * from './parallel-task-coordinator';
+export * from './self-reflection-critic';

package/dist/subagent/self-reflection-critic.d.ts

@@ -0,0 +1,35 @@
+import type { SubagentDefinition } from '../tool/builtin/task';
+/**
+ * System prompt for the Self-Reflection Critic subagent.
+ *
+ * This prompt defines the critic's role as the user's proxy / critical
+ * reviewer. It instructs the model to:
+ * 1. Act on behalf of the user
+ * 2. Search the codebase to verify the agent's claims
+ * 3. Identify potential issues, edge cases, and missing requirements
+ * 4. Generate follow-up questions the user would ask
+ * 5. Call the ReflectionDecision tool with its final verdict
+ * 6. Be progressively more lenient in later rounds to prevent infinite loops
+ */
+export declare function buildCriticSystemPrompt(cwd: string, now?: Date): string;
+export declare const criticSystemPrompt: string;
+/**
+ * Self-Reflection Critic Subagent Definition
+ *
+ * A read-only reviewer agent that acts as the user's proxy.
+ * It verifies the main agent's work by searching the codebase,
+ * checking for issues, and generating follow-up questions the
+ * user would ask.
+ *
+ * Uses the ReflectionDecision tool to record a structured verdict.
+ *
+ * @example
+ * ```typescript
+ * Task({
+ *   subagent_type: 'SelfReflectionCritic',
+ *   description: 'Review agent work',
+ *   prompt: '## Original User Request\n...\n## Agent Response\n...'
+ * })
+ * ```
+ */
+export declare const selfReflectionCriticAgent: SubagentDefinition;

package/dist/tool/builtin/bash.d.ts

@@ -2,6 +2,7 @@ import type { ChildProcess } from 'node:child_process';
 import type { CallToolResult, ToolInputSchema } from '../../types';
 import type { ToolExecutionContext } from '../types';
 import { BaseTool } from '../base';
+import { type ReadOnlyPathEntry } from './pathProtection';
 /**
  * Information about a tracked background process
  */
@@ -95,9 +96,12 @@ export declare class BashTool extends BaseTool {
     private cwd;
     /** Shell to use for command execution */
     private shell;
+    /** Optional read-only path rules */
+    private readOnlyPaths?;
     constructor(options?: {
         cwd?: string;
         shell?: string;
+        readOnlyPaths?: ReadOnlyPathEntry[];
     });
     /**
      * Set the current working directory
@@ -107,6 +111,14 @@ export declare class BashTool extends BaseTool {
      * Get the current working directory
      */
     getCwd(): string;
+    /**
+     * Set read-only paths for write-like shell commands.
+     */
+    setReadOnlyPaths(paths: ReadonlyArray<ReadOnlyPathEntry> | undefined): void;
+    /**
+     * Get configured read-only paths.
+     */
+    getReadOnlyPaths(): ReadonlyArray<ReadOnlyPathEntry> | undefined;
     /**
      * Execute a bash command
      *
@@ -123,6 +135,18 @@ export declare class BashTool extends BaseTool {
      * Validate and parse arguments
      */
     private validateArgs;
+    /**
+     * Validate read-only path policy for write-like shell commands.
+     *
+     * This is intentionally heuristic: commands that appear read-only are skipped.
+     * For write-like commands, we block when:
+     * 1) effective cwd is under a protected path, or
+     * 2) command text explicitly references a protected path.
+     */
+    private validateReadOnlyPathPolicy;
+    private findReferencedReadOnlyRule;
+    private buildCommandPathCandidates;
+    private commandMentionsPath;
     /**
      * Execute command synchronously with timeout
      */

package/dist/tool/builtin/edit.d.ts

@@ -1,6 +1,7 @@
 import type { CallToolResult, ToolInputSchema } from '../../types';
 import type { ToolExecutionContext } from '../types';
 import { BaseTool } from '../base';
+import { type ReadOnlyPathEntry } from './pathProtection';
 /**
  * Result of an edit operation
  */
@@ -61,10 +62,13 @@ export declare class EditTool extends BaseTool {
     private fileBlacklist?;
     /** Disable file blacklist checks */
     private disableBlacklist;
+    /** Optional read-only path rules */
+    private readOnlyPaths?;
     constructor(options?: {
         cwd?: string;
         fileBlacklist?: string[];
         disableBlacklist?: boolean;
+        readOnlyPaths?: ReadOnlyPathEntry[];
     });
     /**
      * Set the current working directory
@@ -74,6 +78,14 @@ export declare class EditTool extends BaseTool {
      * Get the current working directory
      */
     getCwd(): string;
+    /**
+     * Set read-only paths for file operations.
+     */
+    setReadOnlyPaths(paths: ReadonlyArray<ReadOnlyPathEntry> | undefined): void;
+    /**
+     * Get configured read-only paths.
+     */
+    getReadOnlyPaths(): ReadonlyArray<ReadOnlyPathEntry> | undefined;
     /**
      * Execute file edit
      *

package/dist/tool/builtin/index.d.ts

@@ -20,8 +20,8 @@ export { TodoPlanTool } from './todoPlan';
 export type { TodoPlanArgs, TodoPlanResult } from './todoPlan';
 export { TodoWriteTool } from './todoWrite';
 export type { TodoItem, TodoStatus, TodoWriteArgs, TodoWriteResult } from './todoWrite';
-export { WebFetchTool } from './webFetch';
-export type { FetchFormat, WebFetchArgs, WebFetchResult } from './webFetch';
+export { softWrapLines, WebFetchTool } from './webFetch';
+export type { DeliveryMode, FetchFormat, WebFetchArgs, WebFetchResult } from './webFetch';
 export { WebSearchTool } from './webSearch';
 export type { SearchResultItem, WebSearchArgs, WebSearchResult } from './webSearch';
 export { WriteTool } from './write';

package/dist/tool/builtin/pathProtection.d.ts

@@ -0,0 +1,25 @@
+export interface ReadOnlyPathRule {
+    path: string;
+    reason?: string;
+}
+export type ReadOnlyPathEntry = string | ReadOnlyPathRule;
+export interface ResolvedReadOnlyPathRule {
+    path: string;
+    reason?: string;
+    absolutePath: string;
+}
+export interface ReadOnlyPathCheckOptions {
+    cwd?: string;
+    readOnlyPaths?: ReadonlyArray<ReadOnlyPathEntry>;
+    originalPath?: string;
+    action?: string;
+}
+export interface ReadOnlyPathCheckResult {
+    isBlocked: boolean;
+    rule?: ResolvedReadOnlyPathRule;
+    message?: string;
+}
+export declare function resolveReadOnlyPathRules(readOnlyPaths: ReadonlyArray<ReadOnlyPathEntry> | undefined, cwd?: string): ResolvedReadOnlyPathRule[];
+export declare function findMatchingReadOnlyPath(targetPath: string, rules: ReadonlyArray<ResolvedReadOnlyPathRule>): ResolvedReadOnlyPathRule | undefined;
+export declare function formatReadOnlyPathError(displayPath: string, rule?: Pick<ResolvedReadOnlyPathRule, 'path' | 'absolutePath' | 'reason'>, action?: string): string;
+export declare function checkReadOnlyPath(targetPath: string, options?: ReadOnlyPathCheckOptions): Promise<ReadOnlyPathCheckResult>;

package/dist/tool/builtin/read.d.ts

@@ -2,62 +2,33 @@ import type { CallToolResult, ToolInputSchema } from '../../types';
 import type { ConversionMetadata } from '../converters/types';
 import type { ToolExecutionContext } from '../types';
 import { BaseTool } from '../base';
-/**
- * Result of a file read operation
- */
+/** Result of a file read operation (text path) */
 export interface ReadResult {
-    /** File content with line numbers */
     content: string;
-    /** Total number of lines in file */
     totalLines: number;
-    /** Number of lines returned */
     linesReturned: number;
-    /** Starting line number (1-based) */
     startLine: number;
-    /** Whether any lines were truncated */
+    /** Whether any individual line was truncated (per-line length limit) */
     truncated: boolean;
-    /** Whether the content was truncated due to character limit */
-    contentTruncated?: boolean;
-    /** Total characters in full content (before truncation) */
-    totalChars?: number;
-    /** Actual characters returned (after truncation) */
-    charsReturned?: number;
-    /** File size in bytes */
+    /** Whether output was truncated because byte budget was exceeded */
+    truncatedByBytes?: boolean;
     fileSize: number;
-    /** Whether this is a binary/image file */
     isBinary: boolean;
-    /** MIME type if detected */
     mimeType?: string;
-    /** Conversion metadata if file was converted from binary format */
     conversionMetadata?: ConversionMetadata;
-    /** Whether binary content was suppressed */
-    binaryContentSuppressed?: boolean;
-    /** Reason binary content was suppressed */
-    binaryContentReason?: string;
 }
-/**
- * Arguments for the Read tool
- */
+/** Arguments accepted by the Read tool */
 export interface ReadArgs {
-    /** The path to the file to read (absolute or relative to cwd) */
-    file_path: string;
-    /** The line number to start reading from (1-based) */
+    file_path?: string;
+    file_id?: string;
     offset?: number;
-    /** The number of lines to read */
     limit?: number;
-    /** Enable automatic conversion of binary files to Markdown (default: true) */
-    enable_conversion?: boolean;
-    /** Conversion options for binary files */
-    conversion_options?: Record<string, unknown>;
-    /** Allow raw binary (base64) output for binary files (default: false) */
-    allow_binary_content?: boolean;
+    start_line?: number;
+    end_line?: number;
 }
 /**
  * Tool for reading files from the filesystem.
  *
- * This tool reads files with line number formatting, supporting
- * offset/limit for large files and detecting binary content.
- *
  * @example
  * ```typescript
  * const readTool = new ReadTool()
@@ -67,106 +38,92 @@ export interface ReadArgs {
  *   limit: 50
  * })
  * ```
- *
- * @example Restrict reads to a specific directory
- * ```typescript
- * const readTool = new ReadTool({
- *   cwd: '/app/output',
- *   restrictToDirectory: true
- * })
- * // All paths will be resolved relative to /app/output
- * // Absolute paths and path traversal (../) will be blocked
- * ```
  */
 export declare class ReadTool extends BaseTool {
     readonly name = "Read";
-    /** Current working directory for resolving relative paths */
     private _cwd;
-    /** Allowed directory for file operations (if set, restricts reads to this directory) */
     private _allowedDirectory?;
-    /** Optional file blacklist override */
     private _fileBlacklist?;
-    /** Disable file blacklist checks */
     private _disableBlacklist;
-    /** Binary file processor for converting documents to Markdown */
     private _processor;
+    private _converterAllowList;
+    private _supportsVision;
+    private _supportsPdfs;
     constructor(options?: {
         cwd?: string;
-        /** If set, restricts all file reads to this directory. Paths outside will be rejected. */
         allowedDirectory?: string;
-        /** Optional file blacklist override (defaults to built-in blacklist). */
         fileBlacklist?: string[];
-        /** Disable file blacklist checks entirely. */
         disableBlacklist?: boolean;
-        /** Enable/disable binary file conversion (default: true) */
         enableConversion?: boolean;
-        /** Custom binary file processor */
         processor?: any;
+        /**
+         * Extensions allowed through the converter pipeline (e.g. `['.docx', '.pptx']`).
+         * Binary files whose extension is NOT in this list will skip conversion and
+         * return a binary-info result suggesting to use the Bash tool instead.
+         *
+         * @default ['.docx', '.pptx', '.pages', '.numbers', '.key']
+         */
+        converterAllowList?: string[];
+        /**
+         * Model capabilities that determine how binary files are handled.
+         *
+         * - `vision` – whether the model can understand images (default: `false`)
+         * - `pdfs`   – whether the model can read PDFs natively (default: `false`)
+         *
+         * When a capability is `false` the Read tool will **not** return native
+         * (base64) content for that file type.  Instead it returns a short message
+         * explaining the file cannot be read by the current model, or attempts
+         * automatic conversion to Markdown (for PDFs).
+         */
+        modelCapabilities?: {
+            vision?: boolean;
+            pdfs?: boolean;
+        };
     });
-    private createDefaultProcessor;
-    /**
-     * Dynamic description that includes allowed directory info if configured
-     */
     get description(): string;
-    /**
-     * Dynamic parameters that include allowed directory info if configured
-     */
     get parameters(): ToolInputSchema;
-    /**
-     * Set the current working directory
-     */
     setCwd(cwd: string): void;
-    /**
-     * Get the current working directory
-     */
     getCwd(): string;
-    /**
-     * Set the allowed directory for file operations
-     */
     setAllowedDirectory(dir: string | undefined): void;
-    /**
-     * Get the allowed directory for file operations
-     */
     getAllowedDirectory(): string | undefined;
-    private isWithinDirectory;
     /**
-     * Execute file read
-     *
-     * @param args - Read arguments
-     * @param _ctx - Tool execution context (required, includes sessionId)
-     * @returns MCP-compliant CallToolResult with file content
+     * Replace the converter allow-list at runtime.
+     * Pass extensions with or without leading dot (e.g. `'.xlsx'` or `'xlsx'`).
      */
-    execute(args: Record<string, unknown>, _ctx: ToolExecutionContext): Promise<CallToolResult>;
+    setConverterAllowList(extensions: string[]): void;
+    /** Return a copy of the current converter allow-list. */
+    getConverterAllowList(): string[];
     /**
-     * Validate and parse arguments
-     */
-    private validateArgs;
-    /**
-     * Handle image file (metadata only)
-     */
-    private handleImageFile;
-    /**
-     * Handle binary file (non-image)
-     */
-    private handleBinaryFile;
-    /**
-     * Handle binary file with conversion to Markdown
-     */
-    private handleBinaryFileWithConversion;
-    /**
-     * Handle Jupyter notebook file
-     */
-    private handleJupyterNotebook;
-    /**
-     * Handle text file
-     */
-    private handleTextFile;
-    /**
-     * Format output with line numbers and apply offset/limit
+     * Update model capabilities at runtime (e.g. when the user switches models).
+     *
+     * @example
+     * ```typescript
+     * readTool.setModelCapabilities({ vision: false, pdfs: false })
+     * ```
      */
-    private formatOutput;
+    setModelCapabilities(caps: {
+        vision?: boolean;
+        pdfs?: boolean;
+    }): void;
+    /** Return the current model capability flags. */
+    getModelCapabilities(): {
+        vision: boolean;
+        pdfs: boolean;
+    };
+    execute(args: Record<string, unknown>, ctx: ToolExecutionContext): Promise<CallToolResult>;
+    private _validateArgs;
+    private _isWithin;
+    private _checkSymlinkEscape;
+    /** Read a text file, return byte-budgeted line-numbered output. */
+    private _readText;
+    /** Read a Jupyter notebook, flatten cells into lines, then format. */
+    private _readNotebook;
     /**
-     * Format file size for display
+     * Handle a binary file that is not an image or PDF.
+     * Try to convert via processor; on failure return an info result with
+     * file type & size so the model knows what it's dealing with.
      */
-    private formatSize;
+    private _readBinary;
+    private _wrapText;
+    private _createDefaultProcessor;
 }

package/dist/tool/builtin/task.d.ts

@@ -14,6 +14,14 @@ export interface SubagentDefinition {
     accessPolicy: ToolAccessPolicy;
     /** System prompt for this subagent (optional) */
     systemPrompt?: string;
+    /**
+     * Extra tools to inject into this subagent (not sourced from global registry).
+     *
+     * Use this for subagent-specific tools that should not be registered
+     * globally. The middleware will add these tools to the subagent's registry
+     * after filtering global tools by the access policy.
+     */
+    extraTools?: import('../base').BaseTool[];
     /** Additional metadata (extensible for future use) */
     [key: string]: unknown;
 }

package/dist/tool/builtin/webFetch.d.ts

@@ -3,6 +3,8 @@ import type { ToolExecutionContext } from '../types';
 import { BaseTool } from '../base';
 /** Output format for web fetch */
 export type FetchFormat = 'markdown' | 'html' | 'json' | 'text';
+/** Delivery mode: inline (small content) or blob (large content stored to disk) */
+export type DeliveryMode = 'inline' | 'blob';
 /**
  * Result of a web fetch operation
  */
@@ -13,7 +15,7 @@ export interface WebFetchResult {
     url: string;
     /** The output format used */
     format: FetchFormat;
-    /** The content text */
+    /** The content text (full for inline, preview for blob) */
     content: string;
     /** Original content length in characters */
     contentLength: number;
@@ -27,6 +29,16 @@ export interface WebFetchResult {
     truncated: boolean;
     /** Error message if fetch failed */
     error?: string;
+    /** Delivery mode: "inline" or "blob" */
+    delivery?: DeliveryMode;
+    /** Session blob file_id (only when delivery is "blob") */
+    file_id?: string;
+    /** Total line count in blob (only when delivery is "blob") */
+    lineCount?: number;
+    /** SHA-256 hash of full content (only when delivery is "blob") */
+    sha256?: string;
+    /** Instructions for reading the full blob content (only when delivery is "blob") */
+    readInstructions?: string;
 }
 /**
  * Arguments for the WebFetch tool
@@ -45,6 +57,12 @@ export interface WebFetchArgs {
     /** Whether to use Jina Reader as fallback if direct fetch fails. Defaults to true (programmatic use only). */
     use_jina_fallback?: boolean;
 }
+/**
+ * Break lines longer than `maxLen` at word boundaries.
+ * Preserves content inside fenced code blocks (```) to avoid breaking
+ * indentation-sensitive code.
+ */
+export declare function softWrapLines(text: string, maxLen?: number): string;
 /**
  * Tool for fetching and converting web content.
  *
@@ -64,7 +82,7 @@ export interface WebFetchArgs {
  */
 export declare class WebFetchTool extends BaseTool {
     readonly name = "WebFetch";
-    readonly description = "Fetches content from a specified URL and converts it to various formats.\n\nUsage notes:\n- Takes a URL as input\n- Supports multiple output formats: markdown (recommended), html, json, text\n- Markdown format is recommended for LLM processing\n- The URL must be a fully-formed valid URL\n- Supports custom HTTP headers (programmatic use only)\n- Content length can be limited with max_length parameter (default: 5000)\n- Pagination supported with start_index parameter\n- Hard limit: 10MB to prevent OOM\n- Private IP addresses are blocked for security\n- 30 second timeout, maximum 5 redirects\n- Automatically falls back to Jina Reader (r.jina.ai) if direct fetch fails (cannot be disabled)";
+    readonly description = "Fetches content from a specified URL and converts it to various formats.\n\nUsage notes:\n- Takes a URL as input\n- Supports multiple output formats: markdown (recommended), html, json, text\n- Markdown format is recommended for LLM processing\n- The URL must be a fully-formed valid URL\n- Supports custom HTTP headers (programmatic use only)\n- Content length can be limited with max_length parameter (default: 5000)\n- Pagination supported with start_index parameter\n- Hard limit: 10MB to prevent OOM\n- Private IP addresses are blocked for security\n- 30 second timeout, maximum 5 redirects\n- Automatically falls back to Jina Reader (r.jina.ai) if direct fetch fails (cannot be disabled)\n- For large pages: content is automatically saved to a session blob and returned with a file_id. Use the Read tool with that file_id and start_line/end_line to access the full content in chunks of ~200 lines.";
     readonly parameters: ToolInputSchema;
     readonly riskLevel = "medium";
     private turndownService;
@@ -73,10 +91,15 @@ export declare class WebFetchTool extends BaseTool {
      * Execute web fetch
      *
      * @param args - WebFetch arguments
-     * @param _ctx - Tool execution context
+     * @param ctx - Tool execution context
      * @returns MCP-compliant CallToolResult with fetched content
      */
-    execute(args: Record<string, unknown>, _ctx: ToolExecutionContext): Promise<CallToolResult>;
+    execute(args: Record<string, unknown>, ctx: ToolExecutionContext): Promise<CallToolResult>;
+    /**
+     * Attempt to soft-wrap content and write to a session blob.
+     * Returns a CallToolResult with the blob reference on success, or null on failure.
+     */
+    private tryWriteBlob;
     /**
      * Validate and parse arguments
      */

package/dist/tool/builtin/write.d.ts

@@ -1,6 +1,7 @@
 import type { CallToolResult, ToolInputSchema } from '../../types';
 import type { ToolExecutionContext } from '../types';
 import { BaseTool } from '../base';
+import { type ReadOnlyPathEntry } from './pathProtection';
 /**
  * Result of a write operation
  */
@@ -11,6 +12,8 @@ export interface WriteResult {
     filePath: string;
     /** Number of bytes written */
     bytesWritten: number;
+    /** Number of lines written */
+    linesWritten: number;
     /** Whether an existing file was overwritten */
     overwritten: boolean;
     /** Optional revert payload for undo/redo */
@@ -68,6 +71,8 @@ export declare class WriteTool extends BaseTool {
     private _fileBlacklist?;
     /** Disable file blacklist checks */
     private _disableBlacklist;
+    /** Optional read-only path rules */
+    private _readOnlyPaths?;
     constructor(options?: {
         cwd?: string;
         /** If set, restricts all file writes to this directory. Paths outside will be rejected. */
@@ -76,6 +81,8 @@ export declare class WriteTool extends BaseTool {
         fileBlacklist?: string[];
         /** Disable file blacklist checks entirely. */
         disableBlacklist?: boolean;
+        /** Optional read-only path list. Writes into these paths will be rejected. */
+        readOnlyPaths?: ReadOnlyPathEntry[];
     });
     /**
      * Dynamic description that includes allowed directory info if configured
@@ -101,6 +108,14 @@ export declare class WriteTool extends BaseTool {
      * Get the allowed directory for file operations
      */
     getAllowedDirectory(): string | undefined;
+    /**
+     * Set read-only paths for file operations.
+     */
+    setReadOnlyPaths(paths: ReadonlyArray<ReadOnlyPathEntry> | undefined): void;
+    /**
+     * Get configured read-only paths.
+     */
+    getReadOnlyPaths(): ReadonlyArray<ReadOnlyPathEntry> | undefined;
     /**
      * Execute file write
      *