clementine-agent 1.18.200 → 1.18.201

package/dist/agent/run-agent.js

@@ -97,6 +97,7 @@ export function invalidateMcpStatusEntry(name) {
 import { BASE_DIR, PKG_DIR, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY as CONFIG_ANTHROPIC_API_KEY, normalizeClaudeSdkOptionsForOneMillionContext, TOOL_OUTPUT_GUARD, } from '../config.js';
 import { buildGuardHooks } from './tool-output-guard.js';
 import { buildDedupHook } from './tool-call-dedup.js';
+import { buildSideEffectIdempotencyHook } from './side-effect-idempotency.js';
 import { buildChatStopHook } from './chat-stop-hook.js';
 import { buildAgentMap } from './agent-definitions.js';
 import { buildExecutionToolPolicy, } from './execution-policy.js';
@@ -449,6 +450,25 @@ export async function runAgent(prompt, opts) {
             });
         },
     });
+    // ── Side-effect idempotency hook (1.18.201) ────────────────────────
+    // Prevents exact duplicate high-confidence external mutations across
+    // context-overflow resumes/retries. This is intentionally narrow:
+    // confident email sends and CRM mutations only, keyed by stable identity
+    // fields. Unknown side effects remain event-log/audit data, not blocks.
+    const idempotency = buildSideEffectIdempotencyHook({
+        runId,
+        sessionKey: opts.sessionKey,
+        onDecision: (info) => {
+            if (info.decision !== 'block')
+                return;
+            writeEvent({
+                kind: 'error',
+                ts: new Date().toISOString(),
+                sessionId,
+                toolError: `_clementine_idempotency:block ${info.toolName} ${info.summary ?? ''}`.trim(),
+            });
+        },
+    });
     // ── Chat persistence Stop hook (1.18.184, source='chat' only) ─────
     // Keeps chat-initiated multi-step jobs running until they finish.
     // Inspects the model's last assistant message for continuation
@@ -480,6 +500,10 @@ export async function runAgent(prompt, opts) {
     // Merge hook maps from the modules. SDK accepts arrays of
     // HookCallbackMatcher per event; we concatenate.
     const mergedHooks = { ...guard.hooks };
+    for (const [evt, matchers] of Object.entries(idempotency.hooks)) {
+        const existing = mergedHooks[evt] ?? [];
+        mergedHooks[evt] = [...existing, ...matchers];
+    }
     for (const [evt, matchers] of Object.entries(dedup.hooks)) {
         const existing = mergedHooks[evt] ?? [];
         mergedHooks[evt] = [...existing, ...matchers];
@@ -831,6 +855,12 @@ export async function runAgent(prompt, opts) {
             warned: dedup.stats.warned,
             blocked: dedup.stats.blocked,
         } : undefined,
+        idempotency: idempotency.stats.guarded > 0 ? {
+            guarded: idempotency.stats.guarded,
+            blocked: idempotency.stats.blocked,
+            recorded: idempotency.stats.recorded,
+            failedNotRecorded: idempotency.stats.failedNotRecorded,
+        } : undefined,
     }, 'runAgent: query complete');
     // PRD §6 Phase 4e: subagent transcript backfill (Path C). The SDK persists
     // every subagent's full message stream to ~/.claude/projects/<encoded-cwd>/

package/dist/agent/side-effect-idempotency.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Cross-run idempotency guard for high-confidence external side effects.
+ *
+ * The classifier answers "is this mutating?". This module answers the
+ * narrower operational question: "is this the same external mutation we
+ * already saw succeed recently?" It intentionally fingerprints only calls
+ * with stable identity fields. Unknown or weakly-identified mutations are
+ * observed by the event log, not blocked.
+ */
+import type { HookCallbackMatcher, HookEvent } from '@anthropic-ai/claude-agent-sdk';
+export type IdempotencyKind = 'email_send' | 'crm_mutation';
+export interface SideEffectFingerprint {
+    kind: IdempotencyKind;
+    fingerprint: string;
+    ttlMs: number;
+    summary: string;
+    guidance: string;
+    details: Record<string, unknown>;
+}
+export interface SideEffectIdempotencyRecord {
+    version: 1;
+    ts: string;
+    runId: string;
+    sessionKey?: string;
+    toolName: string;
+    toolUseId?: string;
+    kind: IdempotencyKind;
+    fingerprint: string;
+    ttlMs: number;
+    summary: string;
+    details: Record<string, unknown>;
+    result: {
+        successReason: string;
+        statusCode?: number;
+        logId?: string;
+    };
+}
+export interface SideEffectIdempotencyStats {
+    inspected: number;
+    guarded: number;
+    blocked: number;
+    recorded: number;
+    skipped: number;
+    failedNotRecorded: number;
+}
+export interface SideEffectIdempotencyHookOptions {
+    runId: string;
+    sessionKey?: string;
+    baseDir?: string;
+    now?: () => number;
+    onDecision?: (info: {
+        decision: 'allow' | 'block' | 'record' | 'skip' | 'failed';
+        toolName: string;
+        kind?: IdempotencyKind;
+        fingerprint?: string;
+        summary?: string;
+        prior?: SideEffectIdempotencyRecord;
+        reason?: string;
+    }) => void;
+}
+export interface SideEffectIdempotencyHookHandles {
+    hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    stats: SideEffectIdempotencyStats;
+}
+export declare function buildSideEffectFingerprint(toolName: string, input: unknown): SideEffectFingerprint | null;
+export declare function readRecentSideEffectRecords(baseDir?: string, now?: number): SideEffectIdempotencyRecord[];
+export declare function appendSideEffectRecord(record: SideEffectIdempotencyRecord, baseDir?: string): void;
+export declare function findPriorSuccessfulSideEffect(fingerprint: SideEffectFingerprint, opts?: {
+    baseDir?: string;
+    now?: number;
+}): SideEffectIdempotencyRecord | null;
+export declare function buildSideEffectIdempotencyHook(opts: SideEffectIdempotencyHookOptions): SideEffectIdempotencyHookHandles;
+//# sourceMappingURL=side-effect-idempotency.d.ts.map

package/dist/agent/side-effect-idempotency.js

@@ -0,0 +1,505 @@
+/**
+ * Cross-run idempotency guard for high-confidence external side effects.
+ *
+ * The classifier answers "is this mutating?". This module answers the
+ * narrower operational question: "is this the same external mutation we
+ * already saw succeed recently?" It intentionally fingerprints only calls
+ * with stable identity fields. Unknown or weakly-identified mutations are
+ * observed by the event log, not blocked.
+ */
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { BASE_DIR } from '../config.js';
+import { isToolResultSuccessful, normalizedToolResultPayload } from './side-effect-classifier.js';
+const logger = pino({ name: 'clementine.side-effect-idempotency' });
+const EMAIL_SEND_TTL_MS = 24 * 60 * 60 * 1000;
+const CRM_MUTATION_TTL_MS = 60 * 60 * 1000;
+const MAX_STORE_BYTES = 2_000_000;
+const MAX_STORE_LINES = 5000;
+const EMAIL_ADDRESS_RE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+const EMAIL_BODY_KEYS = ['body', 'htmlBody', 'bodyHtml', 'html', 'text', 'plainText', 'message', 'content'];
+const EMAIL_SUBJECT_KEYS = ['subject', 'title'];
+const EMAIL_TO_KEYS = ['to', 'toEmail', 'to_email', 'recipient', 'recipients', 'toRecipients', 'to_recipients'];
+const EMAIL_CC_KEYS = ['cc', 'ccRecipients', 'cc_recipients'];
+const EMAIL_BCC_KEYS = ['bcc', 'bccRecipients', 'bcc_recipients'];
+const CRM_PROVIDER_TOKENS = new Set([
+    'crm',
+    'salesforce',
+    'sfdc',
+    'hubspot',
+    'pipedrive',
+    'zoho',
+    'dynamics',
+]);
+const CRM_MUTATION_TOKENS = new Set(['create', 'update', 'upsert', 'delete', 'insert', 'set']);
+const CRM_OBJECT_KEYS = ['object', 'objectName', 'object_name', 'sobject', 'sObject', 's_object', 'entity', 'module'];
+const CRM_RECORD_ID_KEYS = ['recordId', 'record_id', 'id', 'contactId', 'contact_id', 'leadId', 'lead_id', 'accountId', 'account_id', 'externalId', 'external_id'];
+const CRM_FIELD_KEYS = ['fields', 'values', 'data', 'properties', 'record', 'payload', 'input'];
+function activeBaseDir(baseDir) {
+    return baseDir ?? process.env.CLEMENTINE_HOME ?? BASE_DIR;
+}
+function storePath(baseDir) {
+    return path.join(activeBaseDir(baseDir), 'idempotency', 'recent-side-effects.jsonl');
+}
+function stableJson(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            const out = {};
+            for (const k of Object.keys(v).sort()) {
+                out[k] = v[k];
+            }
+            return out;
+        }
+        return v;
+    });
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function shortHash(value, chars = 20) {
+    return sha256(value).slice(0, chars);
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function tokensForToolName(toolName) {
+    return toolName
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function findFirstStringByKey(input, keys, depth = 0) {
+    if (depth > 4)
+        return undefined;
+    if (!input || typeof input !== 'object')
+        return undefined;
+    const obj = input;
+    const lowerMap = new Map(Object.keys(obj).map((k) => [k.toLowerCase(), k]));
+    for (const key of keys) {
+        const actual = lowerMap.get(key.toLowerCase());
+        const value = actual ? obj[actual] : undefined;
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    for (const value of Object.values(obj)) {
+        if (value && typeof value === 'object') {
+            const found = findFirstStringByKey(value, keys, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+function findFirstValueByKey(input, keys, depth = 0) {
+    if (depth > 4)
+        return undefined;
+    if (!input || typeof input !== 'object')
+        return undefined;
+    const obj = input;
+    const lowerMap = new Map(Object.keys(obj).map((k) => [k.toLowerCase(), k]));
+    for (const key of keys) {
+        const actual = lowerMap.get(key.toLowerCase());
+        if (actual && obj[actual] != null)
+            return obj[actual];
+    }
+    for (const value of Object.values(obj)) {
+        if (value && typeof value === 'object') {
+            const found = findFirstValueByKey(value, keys, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
+function collectEmails(value, out = new Set(), depth = 0) {
+    if (depth > 6 || value == null)
+        return out;
+    if (typeof value === 'string') {
+        const matches = value.match(EMAIL_ADDRESS_RE) ?? [];
+        for (const m of matches)
+            out.add(m.toLowerCase());
+        return out;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectEmails(item, out, depth + 1);
+        return out;
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        for (const key of ['email', 'address', 'emailAddress']) {
+            if (key in obj)
+                collectEmails(obj[key], out, depth + 1);
+        }
+        for (const nested of Object.values(obj)) {
+            if (nested && typeof nested === 'object')
+                collectEmails(nested, out, depth + 1);
+        }
+    }
+    return out;
+}
+function emailsForKeys(input, keys) {
+    const value = findFirstValueByKey(input, keys);
+    return Array.from(collectEmails(value)).sort();
+}
+function normalizeWhitespace(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function preview(value, max = 80) {
+    const normalized = normalizeWhitespace(value);
+    return normalized.length > max ? `${normalized.slice(0, max - 1)}...` : normalized;
+}
+function isEmailSendTool(toolName) {
+    const tokens = tokensForToolName(toolName);
+    const hasSend = tokens.includes('send') || /send_?email/i.test(toolName);
+    const hasEmailSurface = tokens.some((t) => t === 'email' || t === 'mail' || t === 'gmail' || t === 'outlook');
+    return hasSend && hasEmailSurface;
+}
+function buildEmailFingerprint(toolName, input) {
+    if (!isEmailSendTool(toolName))
+        return null;
+    const to = emailsForKeys(input, EMAIL_TO_KEYS);
+    const cc = emailsForKeys(input, EMAIL_CC_KEYS);
+    const bcc = emailsForKeys(input, EMAIL_BCC_KEYS);
+    const subject = findFirstStringByKey(input, EMAIL_SUBJECT_KEYS);
+    const body = findFirstStringByKey(input, EMAIL_BODY_KEYS);
+    if (to.length === 0 || !subject || !body)
+        return null;
+    const normalizedSubject = normalizeWhitespace(subject).toLowerCase();
+    // Collapse whitespace before hashing so harmless HTML/plain-text wrapping
+    // changes don't evade duplicate-send protection.
+    const bodyHash = shortHash(normalizeWhitespace(body));
+    const identity = {
+        kind: 'email_send',
+        to,
+        cc,
+        bcc,
+        subject: normalizedSubject,
+        bodyHash,
+    };
+    const recipientText = to.length <= 3 ? to.join(', ') : `${to.slice(0, 3).join(', ')} +${to.length - 3} more`;
+    return {
+        kind: 'email_send',
+        fingerprint: `email_send:${shortHash(stableJson(identity), 32)}`,
+        ttlMs: EMAIL_SEND_TTL_MS,
+        summary: `email send to ${recipientText} ("${preview(subject, 72)}")`,
+        guidance: `This email send to ${recipientText} was already accepted by the provider. Do not retry it. Continue with remaining follow-up work such as CRM stamping, task creation, or a concise status update.`,
+        details: {
+            to,
+            ...(cc.length ? { cc } : {}),
+            ...(bcc.length ? { bcc } : {}),
+            subject: normalizeWhitespace(subject),
+            bodyHash,
+        },
+    };
+}
+function isCrmMutationTool(toolName) {
+    const tokens = tokensForToolName(toolName);
+    return tokens.some((t) => CRM_PROVIDER_TOKENS.has(t))
+        && tokens.some((t) => CRM_MUTATION_TOKENS.has(t));
+}
+function mutationVerb(toolName) {
+    return tokensForToolName(toolName).find((t) => CRM_MUTATION_TOKENS.has(t));
+}
+function pickCrmFields(input) {
+    const fromKnownKey = findFirstValueByKey(input, CRM_FIELD_KEYS);
+    if (fromKnownKey !== undefined)
+        return fromKnownKey;
+    const shallow = {};
+    for (const [k, v] of Object.entries(input)) {
+        if ([...CRM_OBJECT_KEYS, ...CRM_RECORD_ID_KEYS].some((known) => known.toLowerCase() === k.toLowerCase()))
+            continue;
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || v == null)
+            shallow[k] = v;
+    }
+    return shallow;
+}
+function buildCrmFingerprint(toolName, input) {
+    if (!isCrmMutationTool(toolName))
+        return null;
+    const verb = mutationVerb(toolName);
+    const objectName = findFirstStringByKey(input, CRM_OBJECT_KEYS);
+    const recordId = findFirstStringByKey(input, CRM_RECORD_ID_KEYS);
+    const fields = pickCrmFields(input);
+    if (!verb || !objectName)
+        return null;
+    if (verb !== 'create' && !recordId)
+        return null;
+    const fieldsHash = shortHash(stableJson(fields ?? {}));
+    const identity = {
+        kind: 'crm_mutation',
+        verb,
+        objectName: objectName.toLowerCase(),
+        recordId: recordId?.toLowerCase() ?? null,
+        fieldsHash,
+    };
+    const target = `${objectName}${recordId ? ` ${recordId}` : ''}`;
+    return {
+        kind: 'crm_mutation',
+        fingerprint: `crm_mutation:${shortHash(stableJson(identity), 32)}`,
+        ttlMs: CRM_MUTATION_TTL_MS,
+        summary: `CRM ${verb} on ${target}`,
+        guidance: `This CRM ${verb} already succeeded for ${target}. Do not retry the same mutation. Continue with the remaining records or report completion/pending work.`,
+        details: {
+            verb,
+            objectName,
+            ...(recordId ? { recordId } : {}),
+            fieldsHash,
+        },
+    };
+}
+function buildSfBashFingerprint(input) {
+    const command = typeof input.command === 'string' ? input.command.trim() : '';
+    // Narrow first pass: only Salesforce CLI data mutations with exact command
+    // identity. Known gaps to evaluate later: legacy
+    // `sfdx force:data:record:*`, `sf apex run`, direct REST/curl calls, and
+    // custom Python sender scripts. Those need per-pattern confidence before
+    // they can safely block across runs.
+    if (!/\b(?:sf|sfdx)\s+data\s+(?:update|delete|create|upsert)\b/i.test(command))
+        return null;
+    const normalizedCommand = normalizeWhitespace(command);
+    return {
+        kind: 'crm_mutation',
+        fingerprint: `crm_mutation:${shortHash(`bash:${normalizedCommand}`, 32)}`,
+        ttlMs: CRM_MUTATION_TTL_MS,
+        summary: `CRM CLI mutation (${preview(normalizedCommand, 88)})`,
+        guidance: `This CRM CLI mutation already succeeded recently. Do not retry the same command. Continue with remaining records or report completion/pending work.`,
+        details: {
+            verb: 'cli',
+            commandHash: shortHash(normalizedCommand),
+            commandPreview: preview(normalizedCommand, 160),
+        },
+    };
+}
+export function buildSideEffectFingerprint(toolName, input) {
+    const rec = asRecord(input);
+    if (!rec)
+        return null;
+    // Fingerprints intentionally omit agent identity. Idempotency is scoped to
+    // the external operation: if two agents try the same send/update, the
+    // second should continue the workflow instead of duplicating the effect.
+    if (toolName === 'Bash')
+        return buildSfBashFingerprint(rec);
+    return buildEmailFingerprint(toolName, rec) ?? buildCrmFingerprint(toolName, rec);
+}
+function parseRecord(line) {
+    try {
+        const raw = JSON.parse(line);
+        if (raw.version !== 1 || !raw.fingerprint || !raw.kind || !raw.ts || !raw.runId)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function readRecentSideEffectRecords(baseDir, now = Date.now()) {
+    const file = storePath(baseDir);
+    if (!existsSync(file))
+        return [];
+    try {
+        const lines = readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+        const records = lines.map(parseRecord).filter((r) => r !== null);
+        return records.filter((r) => now - Date.parse(r.ts) <= r.ttlMs);
+    }
+    catch {
+        return [];
+    }
+}
+function maybePruneStore(baseDir, now = Date.now()) {
+    const file = storePath(baseDir);
+    if (!existsSync(file))
+        return;
+    try {
+        const st = statSync(file);
+        if (st.size <= MAX_STORE_BYTES)
+            return;
+        const recent = readRecentSideEffectRecords(baseDir, now).slice(-MAX_STORE_LINES);
+        writeFileSync(file, recent.map((r) => JSON.stringify(r)).join('\n') + (recent.length ? '\n' : ''));
+    }
+    catch {
+        // non-critical
+    }
+}
+export function appendSideEffectRecord(record, baseDir) {
+    const file = storePath(baseDir);
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        // Records are small JSONL rows; appendFileSync keeps each write atomic in
+        // practice for this size, and malformed lines are ignored on read.
+        appendFileSync(file, JSON.stringify(record) + '\n');
+        maybePruneStore(baseDir, Date.parse(record.ts));
+    }
+    catch (err) {
+        logger.warn({ err, kind: record.kind, runId: record.runId }, 'Failed to append side-effect idempotency record');
+    }
+}
+export function findPriorSuccessfulSideEffect(fingerprint, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const records = readRecentSideEffectRecords(opts.baseDir, now);
+    for (let i = records.length - 1; i >= 0; i -= 1) {
+        const rec = records[i];
+        if (rec.fingerprint === fingerprint.fingerprint && now - Date.parse(rec.ts) <= fingerprint.ttlMs) {
+            return rec;
+        }
+    }
+    return null;
+}
+function findLogId(value, depth = 0) {
+    if (depth > 5 || value == null)
+        return undefined;
+    if (typeof value !== 'object')
+        return undefined;
+    const obj = value;
+    for (const key of ['logId', 'log_id', 'requestId', 'request_id', 'id']) {
+        const raw = obj[key];
+        if (typeof raw === 'string' && raw.trim())
+            return raw.trim();
+    }
+    for (const nested of Object.values(obj)) {
+        const found = findLogId(nested, depth + 1);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function duplicateReason(fingerprint, prior, now) {
+    const ageMinutes = Math.max(0, Math.round((now - Date.parse(prior.ts)) / 60_000));
+    return JSON.stringify({
+        successful: false,
+        blocked_by: 'idempotency_guard',
+        operation_already_succeeded: true,
+        error: 'duplicate-of-prior-call',
+        operation: fingerprint.summary,
+        prior_call: {
+            ts: prior.ts,
+            runId: prior.runId,
+            toolName: prior.toolName,
+            status_code: prior.result.statusCode,
+            log_id: prior.result.logId,
+        },
+        guidance: `${fingerprint.guidance} Prior success was ${ageMinutes} minute(s) ago.`,
+    });
+}
+export function buildSideEffectIdempotencyHook(opts) {
+    const stats = {
+        inspected: 0,
+        guarded: 0,
+        blocked: 0,
+        recorded: 0,
+        skipped: 0,
+        failedNotRecorded: 0,
+    };
+    const now = opts.now ?? (() => Date.now());
+    const preToolUse = async (input) => {
+        if (input.hook_event_name !== 'PreToolUse')
+            return {};
+        const evt = input;
+        const toolName = String(evt.tool_name ?? 'unknown');
+        stats.inspected += 1;
+        const fingerprint = buildSideEffectFingerprint(toolName, evt.tool_input);
+        if (!fingerprint) {
+            stats.skipped += 1;
+            opts.onDecision?.({ decision: 'skip', toolName, reason: 'no-confident-fingerprint' });
+            return {};
+        }
+        stats.guarded += 1;
+        const ts = now();
+        const prior = findPriorSuccessfulSideEffect(fingerprint, { baseDir: opts.baseDir, now: ts });
+        if (!prior) {
+            opts.onDecision?.({
+                decision: 'allow',
+                toolName,
+                kind: fingerprint.kind,
+                fingerprint: fingerprint.fingerprint,
+                summary: fingerprint.summary,
+            });
+            return {};
+        }
+        stats.blocked += 1;
+        logger.warn({
+            runId: opts.runId,
+            toolName,
+            kind: fingerprint.kind,
+            priorRunId: prior.runId,
+            summary: fingerprint.summary,
+        }, 'side-effect-idempotency: blocking duplicate successful side effect');
+        opts.onDecision?.({
+            decision: 'block',
+            toolName,
+            kind: fingerprint.kind,
+            fingerprint: fingerprint.fingerprint,
+            summary: fingerprint.summary,
+            prior,
+        });
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'deny',
+                permissionDecisionReason: duplicateReason(fingerprint, prior, ts),
+            },
+        };
+    };
+    const postToolUse = async (input) => {
+        if (input.hook_event_name !== 'PostToolUse')
+            return {};
+        const evt = input;
+        const toolName = String(evt.tool_name ?? 'unknown');
+        const fingerprint = buildSideEffectFingerprint(toolName, evt.tool_input);
+        if (!fingerprint)
+            return {};
+        const result = isToolResultSuccessful(evt.tool_response, false);
+        if (!result.successful) {
+            stats.failedNotRecorded += 1;
+            opts.onDecision?.({
+                decision: 'failed',
+                toolName,
+                kind: fingerprint.kind,
+                fingerprint: fingerprint.fingerprint,
+                summary: fingerprint.summary,
+                reason: result.reason,
+            });
+            return {};
+        }
+        const payload = normalizedToolResultPayload(evt.tool_response);
+        const record = {
+            version: 1,
+            ts: new Date(now()).toISOString(),
+            runId: opts.runId,
+            ...(opts.sessionKey ? { sessionKey: opts.sessionKey } : {}),
+            toolName,
+            toolUseId: evt.tool_use_id,
+            kind: fingerprint.kind,
+            fingerprint: fingerprint.fingerprint,
+            ttlMs: fingerprint.ttlMs,
+            summary: fingerprint.summary,
+            details: fingerprint.details,
+            result: {
+                successReason: result.reason,
+                ...(result.statusCode !== undefined ? { statusCode: result.statusCode } : {}),
+                ...(findLogId(payload) ? { logId: findLogId(payload) } : {}),
+            },
+        };
+        appendSideEffectRecord(record, opts.baseDir);
+        stats.recorded += 1;
+        opts.onDecision?.({
+            decision: 'record',
+            toolName,
+            kind: fingerprint.kind,
+            fingerprint: fingerprint.fingerprint,
+            summary: fingerprint.summary,
+        });
+        return {};
+    };
+    return {
+        hooks: {
+            PreToolUse: [{ hooks: [preToolUse] }],
+            PostToolUse: [{ hooks: [postToolUse] }],
+        },
+        stats,
+    };
+}
+//# sourceMappingURL=side-effect-idempotency.js.map

package/dist/channels/discord-utils.d.ts

@@ -45,6 +45,7 @@ export declare class DiscordStreamingMessage {
     setToolStatus(status: string): void;
     update(text: string): Promise<void>;
     finalize(text: string): Promise<void>;
+    discard(): Promise<void>;
     /** Format elapsed milliseconds as human-readable duration. */
     private formatElapsed;
     private flush;

package/dist/channels/discord-utils.js

@@ -270,6 +270,20 @@ export class DiscordStreamingMessage {
             catch { /* best-effort */ }
         }
     }
+    async discard() {
+        this.isFinal = true;
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.progressTimer) {
+            clearInterval(this.progressTimer);
+            this.progressTimer = null;
+        }
+        if (this.message) {
+            await this.message.delete().catch(() => { });
+        }
+    }
     /** Format elapsed milliseconds as human-readable duration. */
     formatElapsed(ms) {
         const s = Math.floor(ms / 1000);

package/dist/channels/discord.js

@@ -12,6 +12,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { chunkText, DiscordStreamingMessage, friendlyToolName, formatCronEmbed, rehydrateStatusEmbed, setSavedStatusEmbed, } from './discord-utils.js';
 import { DISCORD_TOKEN, DISCORD_OWNER_ID, DISCORD_WATCHED_CHANNELS, MODELS, ASSISTANT_NAME, OWNER_NAME, PKG_DIR, VAULT_DIR, BASE_DIR, DEFAULT_MODEL_TIER, } from '../config.js';
+import { isSilentGatewayResponse } from '../gateway/router.js';
 import { findProjectByName, getLinkedProjects } from '../agent/assistant.js';
 import { detectApprovalReply } from '../agent/local-turn.js';
 import { normalizeToolsetName } from '../agent/toolsets.js';
@@ -776,6 +777,11 @@ export async function startDiscord(gateway, heartbeat, cronScheduler, dispatcher
                 const streamer = new DiscordStreamingMessage(message.channel);
                 await streamer.start();
                 const response = await heartbeat.runManual();
+                if (isSilentGatewayResponse(response)) {
+                    await streamer.discard();
+                    updatePresence(sessionKey);
+                    return;
+                }
                 await streamer.finalize(response);
                 // Inject into DM session so follow-up conversation has context
                 gateway.injectContext(sessionKey, '!heartbeat', response);
@@ -832,6 +838,11 @@ export async function startDiscord(gateway, heartbeat, cronScheduler, dispatcher
                     const streamer = new DiscordStreamingMessage(message.channel);
                     await streamer.start();
                     const response = await cronScheduler.runManual(jobName);
+                    if (isSilentGatewayResponse(response)) {
+                        await streamer.discard();
+                        updatePresence(sessionKey);
+                        return;
+                    }
                     await streamer.finalize(response);
                     // Inject into DM session so follow-up conversation has context
                     gateway.injectContext(sessionKey, `!cron run ${jobName}`, response);
@@ -875,6 +886,11 @@ export async function startDiscord(gateway, heartbeat, cronScheduler, dispatcher
                     const streamer = new DiscordStreamingMessage(message.channel);
                     await streamer.start();
                     const response = await cronScheduler.runWorkflow(wfName, inputs);
+                    if (isSilentGatewayResponse(response)) {
+                        await streamer.discard();
+                        updatePresence(sessionKey);
+                        return;
+                    }
                     await streamer.finalize(response);
                     gateway.injectContext(sessionKey, `!workflow run ${wfName}`, response);
                     return;
@@ -1149,6 +1165,11 @@ export async function startDiscord(gateway, heartbeat, cronScheduler, dispatcher
             await streamer.start();
             try {
                 const response = await gateway.handleMessage(sessionKey, effectiveText, (t) => streamer.update(t), oneOffModel, oneOffMaxTurns, (toolName, toolInput) => { streamer.setToolStatus(friendlyToolName(toolName, toolInput)); return Promise.resolve(); }, (status) => { streamer.setToolStatus(status); return Promise.resolve(); });
+                if (isSilentGatewayResponse(response)) {
+                    await streamer.discard();
+                    updatePresence(sessionKey);
+                    return;
+                }
                 await streamer.finalize(response);
                 updatePresence(sessionKey);
                 // Track bot message for feedback reactions
@@ -1761,6 +1782,11 @@ export async function startDiscord(gateway, heartbeat, cronScheduler, dispatcher
             await streamer.start();
             try {
                 const response = await gateway.handleMessage(sessionKey, agentMessage, (t) => streamer.update(t));
+                if (isSilentGatewayResponse(response)) {
+                    await streamer.discard();
+                    updatePresence(sessionKey);
+                    return;
+                }
                 await streamer.finalize(response);
             }
             catch (err) {

package/dist/channels/slack-utils.d.ts

@@ -32,6 +32,7 @@ export declare class SlackStreamingMessage {
     setToolStatus(status: string): void;
     update(text: string): Promise<void>;
     finalize(text: string): Promise<void>;
+    discard(): Promise<void>;
     /** Format elapsed milliseconds as human-readable duration. */
     private formatElapsed;
     private flush;

package/dist/channels/slack-utils.js

@@ -131,6 +131,20 @@ export class SlackStreamingMessage {
             await sendChunkedSlack(this.client, this.channel, text, this.threadTs);
         }
     }
+    async discard() {
+        this.isFinal = true;
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.progressTimer) {
+            clearInterval(this.progressTimer);
+            this.progressTimer = null;
+        }
+        if (this.ts) {
+            await this.client.chat.delete({ channel: this.channel, ts: this.ts }).catch(() => { });
+        }
+    }
     /** Format elapsed milliseconds as human-readable duration. */
     formatElapsed(ms) {
         const s = Math.floor(ms / 1000);

package/dist/channels/slack.js

@@ -7,6 +7,7 @@
 import { App } from '@slack/bolt';
 import pino from 'pino';
 import { SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_OWNER_USER_ID, VAULT_DIR, } from '../config.js';
+import { isSilentGatewayResponse } from '../gateway/router.js';
 import { mdToSlack, sendChunkedSlack, SlackStreamingMessage } from './slack-utils.js';
 import { friendlyToolName } from './discord-utils.js';
 const logger = pino({ name: 'clementine.slack' });
@@ -124,6 +125,10 @@ export async function startSlack(gateway, dispatcher, slackBotManager) {
                 const response = await gateway.handleMessage(sessionKey, text, (t) => streamer.update(t), undefined, // model
                 undefined, // maxTurns
                 async (toolName, toolInput) => { streamer.setToolStatus(friendlyToolName(toolName, toolInput)); }, async (status) => { streamer.setToolStatus(status); });
+                if (isSilentGatewayResponse(response)) {
+                    await streamer.discard();
+                    return;
+                }
                 await streamer.finalize(response);
                 // Track bot message for feedback reactions
                 if (streamer.messageTs) {

package/dist/channels/telegram.js

@@ -7,6 +7,7 @@
 import { Bot } from 'grammy';
 import pino from 'pino';
 import { TELEGRAM_BOT_TOKEN, TELEGRAM_OWNER_ID, } from '../config.js';
+import { isSilentGatewayResponse } from '../gateway/router.js';
 import { detectApprovalReply } from '../agent/local-turn.js';
 const logger = pino({ name: 'clementine.telegram' });
 const STREAM_UPDATE_INTERVAL = 1500; // ms
@@ -98,6 +99,12 @@ class TelegramStreamingMessage {
             await sendChunked(this.bot, this.chatId, text);
         }
     }
+    async discard() {
+        this.isFinal = true;
+        if (this.messageId !== null) {
+            await this.bot.api.deleteMessage(this.chatId, this.messageId).catch(() => { });
+        }
+    }
     async flush() {
         if (this.messageId === null || !this.pendingText || this.isFinal)
             return;
@@ -154,6 +161,10 @@ export async function startTelegram(gateway, dispatcher) {
         await streamer.start();
         try {
             const response = await gateway.handleMessage(sessionKey, text, (t) => streamer.update(t), undefined, undefined, async (toolName) => { streamer.setStatus(`using ${toolName}...`); }, async (status) => { streamer.setStatus(status); });
+            if (isSilentGatewayResponse(response)) {
+                await streamer.discard();
+                return;
+            }
             await streamer.finalize(response);
         }
         catch (err) {
@@ -180,6 +191,10 @@ export async function startTelegram(gateway, dispatcher) {
         await streamer.start();
         try {
             const response = await gateway.handleMessage(sessionKey, text, (t) => streamer.update(t), undefined, undefined, async (toolName) => { streamer.setStatus(`using ${toolName}...`); }, async (status) => { streamer.setStatus(status); });
+            if (isSilentGatewayResponse(response)) {
+                await streamer.discard();
+                return;
+            }
             await streamer.finalize(response);
         }
         catch (err) {
@@ -209,6 +224,10 @@ export async function startTelegram(gateway, dispatcher) {
         await streamer.start();
         try {
             const response = await gateway.handleMessage(sessionKey, text, (t) => streamer.update(t), undefined, undefined, async (toolName) => { streamer.setStatus(`using ${toolName}...`); }, async (status) => { streamer.setStatus(status); });
+            if (isSilentGatewayResponse(response)) {
+                await streamer.discard();
+                return;
+            }
             await streamer.finalize(response);
         }
         catch (err) {

package/dist/gateway/router.d.ts

@@ -35,6 +35,8 @@ export declare function runAgentResultIndicatesContextOverflow(result: {
     text?: string;
 }): boolean;
 export type ChatErrorKind = 'rate_limit' | 'one_million_context' | 'context_overflow' | 'auth' | 'billing' | 'transient' | 'unknown';
+export declare const SILENT_GATEWAY_RESPONSE = "__clementine_silent_response__";
+export declare function isSilentGatewayResponse(text: string): boolean;
 export declare function classifyChatError(err: unknown): ChatErrorKind;
 /** Detect auth-like errors in response text that the SDK returned as "successful" results. */
 export declare function looksLikeAuthError(text: string): boolean;

package/dist/gateway/router.js

@@ -190,6 +190,10 @@ export function runAgentResultIndicatesContextOverflow(result) {
     return /^Autocompact is thrashing:\s*the context refilled to the limit/i.test(text)
         || /^rapid_refill_breaker\b/i.test(text);
 }
+export const SILENT_GATEWAY_RESPONSE = '__clementine_silent_response__';
+export function isSilentGatewayResponse(text) {
+    return text === SILENT_GATEWAY_RESPONSE;
+}
 export function classifyChatError(err) {
     const msg = String(err);
     if (isCreditBalanceError(msg))
@@ -1671,7 +1675,9 @@ export class Gateway {
         let aborted = false;
         const ac = s?.abortController;
         if (ac && !ac.signal.aborted) {
-            ac.abort();
+            if (s)
+                s.suppressAbortResponseFor = ac.signal;
+            ac.abort('user-stop');
             aborted = true;
         }
         if (s?.teamTaskControllers?.size) {
@@ -1700,6 +1706,7 @@ export class Gateway {
             if (s.abortController && !s.abortController.signal.aborted) {
                 const partial = s.lastStreamedText ?? '';
                 s.pendingInterrupt = { partial, interruptedAt: Date.now() };
+                s.suppressAbortResponseFor = s.abortController.signal;
                 logger.info({ sessionKey, partialLen: partial.length }, 'New message arrived — interrupting in-flight query');
                 // Pass a reason string so assistant.ts can distinguish this from a
                 // timeout abort and show the right final message.
@@ -1997,6 +2004,7 @@ export class Gateway {
             if (recentContext.responseText) {
                 const current = this.sessions.get(sessionKey);
                 if (current?.abortController && !current.abortController.signal.aborted) {
+                    current.suppressAbortResponseFor = current.abortController.signal;
                     current.abortController.abort('replaced-by-recent-context');
                     logger.info({ sessionKey }, 'Interrupted active chat for recent operational context response');
                 }
@@ -2857,13 +2865,18 @@ export class Gateway {
                     clearTimeout(chatTimer);
                     if (hardWallTimer)
                         clearTimeout(hardWallTimer);
-                    {
-                        const cs = this.sessions.get(sessionKey);
-                        if (cs)
-                            delete cs.abortController;
+                    const cs = this.sessions.get(sessionKey);
+                    const suppressAbortResponse = cs?.suppressAbortResponseFor === chatAc.signal
+                        || chatAc.signal.reason === 'interrupted-by-new-message'
+                        || chatAc.signal.reason === 'replaced-by-recent-context'
+                        || chatAc.signal.reason === 'user-stop';
+                    if (cs) {
+                        delete cs.abortController;
+                        if (cs.suppressAbortResponseFor === chatAc.signal)
+                            delete cs.suppressAbortResponseFor;
                     }
                     if (chatAc.signal.aborted) {
-                        return "Stopped. What would you like to do instead?";
+                        return suppressAbortResponse ? SILENT_GATEWAY_RESPONSE : "Stopped. What would you like to do instead?";
                     }
                     const errKind = classifyChatError(err);
                     logger.error({ err, sessionKey, errKind }, `Chat error (${errKind}) from ${sessionKey}`);

package/package.json

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