clementine-agent 1.18.206 → 1.18.208

package/dist/agent/run-agent.js

@@ -428,8 +428,25 @@ export async function runAgent(prompt, opts) {
                     },
                 });
             },
+            onLargeWrite: (info) => {
+                writeEvent({
+                    kind: 'tool_result',
+                    ts: new Date().toISOString(),
+                    sessionId,
+                    toolUseId: info.toolUseId,
+                    toolResult: {
+                        successful: true,
+                        _clementine_large_write_guard: true,
+                        tool: info.toolName,
+                        filePath: info.filePath,
+                        contentBytes: info.contentBytes,
+                        ...(info.archivePath ? { archivePath: info.archivePath } : {}),
+                        message: 'Large Write content restored after placeholder Write to protect parent context.',
+                    },
+                });
+            },
         })
-        : { hooks: {}, stats: { inspected: 0, compressed: 0, ceilingHits: 0, bytesShed: 0, compactions: 0 } };
+        : { hooks: {}, stats: { inspected: 0, compressed: 0, ceilingHits: 0, bytesShed: 0, compactions: 0, largeWrites: 0 } };
     // ── Tool-call dedup hook (1.18.173) ─────────────────────────────────
     // Breaks the "re-fetch after compaction" loop that crashed the
     // imessage-triage cron on 2026-05-11 (4× identical tool calls →
@@ -854,12 +871,13 @@ export async function runAgent(prompt, opts) {
         finalTextChars: finalText.length,
         // 1.18.169 — tool-output guard summary, surfaced for observability.
         // Non-zero `compressed` means the guard kept the SDK from thrashing.
-        guard: guard.stats.inspected > 0 ? {
+        guard: (guard.stats.inspected > 0 || guard.stats.largeWrites > 0) ? {
             inspected: guard.stats.inspected,
             compressed: guard.stats.compressed,
             bytesShed: guard.stats.bytesShed,
             compactions: guard.stats.compactions,
             ceilingHits: guard.stats.ceilingHits,
+            largeWrites: guard.stats.largeWrites,
         } : undefined,
         // 1.18.173 — tool-call dedup summary. Non-zero warned/blocked means
         // the model tried to re-fetch identical data (typically a

package/dist/agent/run-summary.js

@@ -198,6 +198,12 @@ export function extractRecipients(input) {
 function extractSubject(input) {
     return firstString(input.subject, input.title);
 }
+function extractFilePath(input, raw) {
+    return firstString(input.file_path, input.filePath, input.path, input.target_path, input.targetPath)
+        ?? (raw && typeof raw === 'object'
+            ? firstString(raw.filePath, raw.file_path, raw.path)
+            : undefined);
+}
 function extractProviderLogId(raw) {
     if (!raw || typeof raw !== 'object')
         return undefined;
@@ -305,9 +311,11 @@ export function formatOverflowRecoveryMessage(summary) {
 function formatDetailedCall(call) {
     const recipients = extractRecipients(call.input);
     const subject = extractSubject(call.input);
+    const filePath = extractFilePath(call.input, call.result?.raw);
     const logId = call.result ? extractProviderLogId(call.result.raw) : undefined;
     const parts = [
         toolKindLabel(call.toolName),
+        filePath ? `file ${filePath}` : undefined,
         recipients.length ? `to ${recipients.join(', ')}` : undefined,
         subject ? `subject "${subject}"` : undefined,
         call.result ? statusPhrase(call) : 'started, no confirmation',

package/dist/agent/tool-output-guard.d.ts

@@ -1,6 +1,7 @@
 /**
- * tool-output-guard — PostToolUse hook that bounds per-call tool output size
- * so the SDK's auto-compactor can never thrash on a runaway MCP result.
+ * tool-output-guard — SDK hooks that bound per-call tool output size and
+ * out-of-band very large artifact writes so the SDK's auto-compactor can
+ * never thrash on runaway MCP results or generated files.
  *
  * Why this exists
  * ───────────────
@@ -20,8 +21,10 @@
  *
  * The fix is the canonical Anthropic primitive: a `PostToolUse` hook that
  * returns `hookSpecificOutput.updatedToolOutput` to replace the result
- * before it reaches the model. From sdk.d.ts:1979 — "Replaces the tool
- * output before it is sent to the model."
+ * before it reaches the model. A companion `PreToolUse` hook handles large
+ * `Write` inputs by swapping the native call to a small placeholder; the
+ * `PostToolUse` hook then restores the real artifact on disk after the
+ * placeholder write succeeds.
  *
  * Design properties
  * ─────────────────
@@ -70,6 +73,8 @@ export interface GuardRunStats {
     bytesShed: number;
     /** Number of SDK auto-compactions observed for this run. */
     compactions: number;
+    /** Large file writes completed out-of-band before reaching the SDK context. */
+    largeWrites: number;
 }
 /**
  * Approximate the byte size of a tool_response as it will appear in the
@@ -138,6 +143,15 @@ export interface GuardHookOptions {
         ceilingHit: boolean;
         archivePath: string | null;
     }) => void;
+    /** Optional callback fired when a large Write input is completed
+     *  out-of-band by the guard before the native Write tool runs. */
+    onLargeWrite?: (info: {
+        toolName: string;
+        toolUseId: string;
+        filePath: string;
+        contentBytes: number;
+        archivePath: string | null;
+    }) => void;
     /** Optional source of the current cumulative context-usage ratio
      *  (cache_read + input) / window. Returns a number in [0,1]. The
      *  guard calls this once per tool result to adapt the cap. When

package/dist/agent/tool-output-guard.js

@@ -1,6 +1,7 @@
 /**
- * tool-output-guard — PostToolUse hook that bounds per-call tool output size
- * so the SDK's auto-compactor can never thrash on a runaway MCP result.
+ * tool-output-guard — SDK hooks that bound per-call tool output size and
+ * out-of-band very large artifact writes so the SDK's auto-compactor can
+ * never thrash on runaway MCP results or generated files.
  *
  * Why this exists
  * ───────────────
@@ -20,8 +21,10 @@
  *
  * The fix is the canonical Anthropic primitive: a `PostToolUse` hook that
  * returns `hookSpecificOutput.updatedToolOutput` to replace the result
- * before it reaches the model. From sdk.d.ts:1979 — "Replaces the tool
- * output before it is sent to the model."
+ * before it reaches the model. A companion `PreToolUse` hook handles large
+ * `Write` inputs by swapping the native call to a small placeholder; the
+ * `PostToolUse` hook then restores the real artifact on disk after the
+ * placeholder write succeeds.
  *
  * Design properties
  * ─────────────────
@@ -45,7 +48,7 @@
  * continues. Telemetry must never break execution.
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import pino from 'pino';
 import { BASE_DIR, TOOL_OUTPUT_GUARD } from '../config.js';
 const logger = pino({ name: 'clementine.tool-output-guard' });
@@ -60,7 +63,7 @@ export function defaultGuardConfig() {
     };
 }
 function freshStats() {
-    return { inspected: 0, compressed: 0, ceilingHits: 0, bytesShed: 0, compactions: 0 };
+    return { inspected: 0, compressed: 0, ceilingHits: 0, bytesShed: 0, compactions: 0, largeWrites: 0 };
 }
 // ── Size estimation ───────────────────────────────────────────────────
 /**
@@ -97,6 +100,26 @@ const VERBOSE_FIELDS = [
     'body', 'html', 'html_body', 'htmlBody', 'bodyHtml', 'content', 'text', 'snippet',
     'message', 'transcript', 'raw', 'rawBody', 'rawMessage', 'contentText', 'plainText',
 ];
+const LARGE_WRITE_INPUT_BYTES = 8_000;
+const LARGE_WRITE_PLACEHOLDER = '[Clementine large-write guard placeholder: full content is restored after native Write succeeds.]';
+function writeArchiveFile(baseDir, runId, toolUseId, toolName, suffix, payload) {
+    try {
+        const dir = join(baseDir, 'tool-archive', runId);
+        mkdirSync(dir, { recursive: true });
+        const safeName = toolName.replace(/[^a-zA-Z0-9_-]+/g, '_').slice(0, 80);
+        const safeSuffix = suffix.replace(/[^a-zA-Z0-9_-]+/g, '_').slice(0, 30);
+        const file = join(dir, `${safeName}__${toolUseId}${safeSuffix ? `__${safeSuffix}` : ''}.json`);
+        const body = typeof payload === 'string'
+            ? payload
+            : JSON.stringify(payload, null, 2);
+        writeFileSync(file, body, 'utf8');
+        return file;
+    }
+    catch (err) {
+        logger.debug({ err, toolName, runId }, 'tool-output-guard: archive write failed (non-fatal)');
+        return null;
+    }
+}
 /** First attempt: trim the list inside the response down to head + tail items. */
 function tryListShrink(value, ctx) {
     if (Array.isArray(value)) {
@@ -280,21 +303,7 @@ function formatBytes(n) {
  *  Returns the absolute path, or null on any failure (archive is opt-in
  *  convenience — never blocks compression). */
 function archivePayload(baseDir, runId, toolUseId, toolName, payload) {
-    try {
-        const dir = join(baseDir, 'tool-archive', runId);
-        mkdirSync(dir, { recursive: true });
-        const safeName = toolName.replace(/[^a-zA-Z0-9_-]+/g, '_').slice(0, 80);
-        const file = join(dir, `${safeName}__${toolUseId}.json`);
-        const body = typeof payload === 'string'
-            ? payload
-            : JSON.stringify(payload, null, 2);
-        writeFileSync(file, body, 'utf8');
-        return file;
-    }
-    catch (err) {
-        logger.debug({ err, toolName, runId }, 'tool-output-guard: archive write failed (non-fatal)');
-        return null;
-    }
+    return writeArchiveFile(baseDir, runId, toolUseId, toolName, '', payload);
 }
 // ── Adaptive cap computation ──────────────────────────────────────────
 /**
@@ -375,6 +384,26 @@ export function compressToolOutput(_toolName, rawOutput, ctx) {
         passthrough: false,
     };
 }
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function largeWriteInput(input) {
+    const obj = asRecord(input);
+    const filePath = typeof obj.file_path === 'string' ? obj.file_path.trim() : '';
+    const content = typeof obj.content === 'string' ? obj.content : '';
+    if (!filePath || !content || !isAbsolute(filePath))
+        return null;
+    const contentBytes = estimateBytes(content);
+    if (contentBytes <= LARGE_WRITE_INPUT_BYTES)
+        return null;
+    return { filePath, content, contentBytes };
+}
+function writeLargeFileOutOfBand(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, 'utf8');
+}
 /**
  * Build the hook handles that runAgent will hand to the SDK.
  *
@@ -391,6 +420,52 @@ export function buildGuardHooks(opts) {
         return { hooks: {}, stats };
     }
     const config = opts.config ?? defaultGuardConfig();
+    const pendingLargeWrites = new Map();
+    const preToolUse = async (input, toolUseID) => {
+        if (input.hook_event_name !== 'PreToolUse') {
+            return {};
+        }
+        const evt = input;
+        const toolName = String(evt.tool_name ?? 'unknown');
+        if (toolName !== 'Write')
+            return {};
+        const toolUseId = String(toolUseID ?? evt.tool_use_id ?? 'unknown');
+        const large = largeWriteInput(evt.tool_input);
+        if (!large)
+            return {};
+        const archivePath = writeArchiveFile(opts.archiveBaseDir ?? BASE_DIR, opts.runId, toolUseId, toolName, 'input', evt.tool_input);
+        pendingLargeWrites.set(toolUseId, {
+            filePath: large.filePath,
+            content: large.content,
+            contentBytes: large.contentBytes,
+            archivePath,
+        });
+        stats.bytesShed += Math.max(0, large.contentBytes - 400);
+        logger.info({
+            toolName,
+            toolUseId,
+            filePath: large.filePath,
+            contentBytes: large.contentBytes,
+            archivePath,
+        }, 'tool-output-guard: staged large Write with placeholder input');
+        const reason = [
+            `Clementine large-write guard staged ${formatBytes(large.contentBytes)} for ${large.filePath}.`,
+            archivePath ? `Full original Write input archived at ${archivePath}.` : undefined,
+            'The native Write will use a small placeholder, then Clementine will restore the full content after the write succeeds. Continue with the remaining requested steps after this tool result.',
+        ].filter(Boolean).join(' ');
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'allow',
+                permissionDecisionReason: reason,
+                additionalContext: reason,
+                updatedInput: {
+                    file_path: large.filePath,
+                    content: LARGE_WRITE_PLACEHOLDER,
+                },
+            },
+        };
+    };
     const postToolUse = async (input, toolUseID) => {
         // We only react to PostToolUse — the hook list is keyed by event,
         // but the callback signature is shared, so guard the cast.
@@ -402,6 +477,65 @@ export function buildGuardHooks(opts) {
         const toolUseId = String(toolUseID ?? evt.tool_use_id ?? 'unknown');
         const rawOutput = evt.tool_response;
         stats.inspected += 1;
+        const pendingLargeWrite = toolName === 'Write' ? pendingLargeWrites.get(toolUseId) : undefined;
+        if (pendingLargeWrite) {
+            pendingLargeWrites.delete(toolUseId);
+            try {
+                writeLargeFileOutOfBand(pendingLargeWrite.filePath, pendingLargeWrite.content);
+            }
+            catch (err) {
+                logger.warn({
+                    err,
+                    toolName,
+                    toolUseId,
+                    filePath: pendingLargeWrite.filePath,
+                    contentBytes: pendingLargeWrite.contentBytes,
+                    archivePath: pendingLargeWrite.archivePath,
+                }, 'tool-output-guard: failed to restore large Write content after placeholder write');
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: 'PostToolUse',
+                        additionalContext: [
+                            `Clementine could not restore the staged ${formatBytes(pendingLargeWrite.contentBytes)} Write content to ${pendingLargeWrite.filePath}.`,
+                            pendingLargeWrite.archivePath ? `The original input is archived at ${pendingLargeWrite.archivePath}.` : undefined,
+                            'Retry by writing the file in a smaller way or ask the owner for the archive path.',
+                        ].filter(Boolean).join(' '),
+                    },
+                };
+            }
+            stats.largeWrites += 1;
+            logger.info({
+                toolName,
+                toolUseId,
+                filePath: pendingLargeWrite.filePath,
+                contentBytes: pendingLargeWrite.contentBytes,
+                archivePath: pendingLargeWrite.archivePath,
+            }, 'tool-output-guard: restored large Write content after placeholder write');
+            if (opts.onLargeWrite) {
+                try {
+                    opts.onLargeWrite({
+                        toolName,
+                        toolUseId,
+                        filePath: pendingLargeWrite.filePath,
+                        contentBytes: pendingLargeWrite.contentBytes,
+                        archivePath: pendingLargeWrite.archivePath,
+                    });
+                }
+                catch { /* best-effort */ }
+            }
+            const restoredMessage = [
+                `File created successfully at: ${pendingLargeWrite.filePath}`,
+                `(Clementine restored ${formatBytes(pendingLargeWrite.contentBytes)} of large generated content after native Write used a placeholder to protect context.)`,
+                pendingLargeWrite.archivePath ? `Original Write input archived at: ${pendingLargeWrite.archivePath}` : undefined,
+            ].filter(Boolean).join(' ');
+            return {
+                hookSpecificOutput: {
+                    hookEventName: 'PostToolUse',
+                    additionalContext: `The full file content is present at ${pendingLargeWrite.filePath}. Do not rewrite it; continue with verification, deployment, or the next requested step.`,
+                    updatedToolOutput: restoredMessage,
+                },
+            };
+        }
         const usageRatio = Math.max(opts.usageRatio ? safeRatio(opts.usageRatio) : 0, stats.compactions > 0 ? 0.75 : 0);
         const { softCap } = resolveCap(toolName, config, usageRatio);
         const originalBytes = estimateBytes(rawOutput);
@@ -474,6 +608,7 @@ export function buildGuardHooks(opts) {
     };
     return {
         hooks: {
+            PreToolUse: [{ hooks: [preToolUse] }],
             PostToolUse: [{ hooks: [postToolUse] }],
             PreCompact: [{ hooks: [preCompact] }],
             PostCompact: [{ hooks: [postCompact] }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.206",
+  "version": "1.18.208",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",