clementine-agent 1.18.201 → 1.18.202

package/dist/agent/chat-stop-hook.d.ts

@@ -40,12 +40,16 @@
  * `StopHookInput` shape including the `stop_hook_active` guard.
  */
 import type { HookCallbackMatcher, HookEvent } from '@anthropic-ai/claude-agent-sdk';
+import type { LiveRunState } from './run-state.js';
 export interface StopHookOptions {
     /** Stable run identifier for telemetry. */
     runId: string;
     /** Optional abort signal to honor — if it fires, the hook will
      *  never re-block. User-initiated stops always win. */
     abortSignal?: AbortSignal;
+    /** Live hook-fed run state. When present, Stop can require a final
+     *  Completed/Pending manifest after external side effects. */
+    runState?: LiveRunState;
     /** Optional callback fired on every decision. Useful for the
      *  dashboard "What Clementine sees this turn" panel. */
     onDecision?: (info: {
@@ -62,6 +66,10 @@ export interface StopHookStats {
     passed: number;
     /** Stop events where we re-prompted the model to continue. */
     continued: number;
+    /** Stop events blocked because live RunState showed unfinished todos. */
+    todoContinued: number;
+    /** Stop events blocked because side effects were not acknowledged. */
+    manifestRequired: number;
 }
 export interface StopHookHandles {
     /** Hook map suitable for SDK `query({ options: { hooks } })`. */

package/dist/agent/chat-stop-hook.js

@@ -40,6 +40,7 @@
  * `StopHookInput` shape including the `stop_hook_active` guard.
  */
 import pino from 'pino';
+import { hasCompletedManifest, summarizeRunStateForManifest } from './run-state.js';
 const logger = pino({ name: 'clementine.chat-stop-hook' });
 /**
  * Phrases in the last assistant message that signal "more work to do."
@@ -67,7 +68,7 @@ const CONTINUATION_SIGNALS = [
  * Build a Stop hook for a chat-initiated agentic run.
  */
 export function buildChatStopHook(opts) {
-    const stats = { inspected: 0, passed: 0, continued: 0 };
+    const stats = { inspected: 0, passed: 0, continued: 0, todoContinued: 0, manifestRequired: 0 };
     const stopHook = async (input) => {
         if (input.hook_event_name !== 'Stop')
             return {};
@@ -112,6 +113,51 @@ export function buildChatStopHook(opts) {
             });
             return {};
         }
+        const unfinishedTodos = opts.runState?.todo
+            ? opts.runState.todo.pending + opts.runState.todo.inProgress
+            : 0;
+        if (unfinishedTodos > 0) {
+            stats.todoContinued += 1;
+            const reason = `TodoWrite still shows ${unfinishedTodos} unfinished item(s). ` +
+                'Keep working until the todo list is complete, or explain the blocker and include a concise Completed/Pending manifest before ending.';
+            logger.info({
+                runId: opts.runId,
+                unfinishedTodos,
+                lastMessagePreview,
+            }, 'Stop hook re-prompting model because live RunState has unfinished todos');
+            opts.onDecision?.({
+                decision: 'continue',
+                reason,
+                lastMessagePreview,
+                stopHookActive: false,
+            });
+            return {
+                decision: 'block',
+                reason,
+            };
+        }
+        const successfulSideEffects = opts.runState?.successfulSideEffects.length ?? 0;
+        if (successfulSideEffects > 0 && !hasCompletedManifest(lastMsg)) {
+            stats.manifestRequired += 1;
+            const reason = `You completed ${successfulSideEffects} external side effect(s), but your final message does not include the required ` +
+                '`✅ **Completed**` manifest. Confirm what was done before ending.\n\n' +
+                summarizeRunStateForManifest(opts.runState);
+            logger.info({
+                runId: opts.runId,
+                successfulSideEffects,
+                lastMessagePreview,
+            }, 'Stop hook requiring completion manifest for successful side effects');
+            opts.onDecision?.({
+                decision: 'continue',
+                reason,
+                lastMessagePreview,
+                stopHookActive: false,
+            });
+            return {
+                decision: 'block',
+                reason,
+            };
+        }
         // ── Detection: did the model say it would continue? ──────────
         const continuationMatched = CONTINUATION_SIGNALS.some((rx) => rx.test(lastMsg));
         if (!continuationMatched) {

package/dist/agent/run-agent.js

@@ -99,6 +99,7 @@ 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 { buildRunStateHooks } from './run-state.js';
 import { buildAgentMap } from './agent-definitions.js';
 import { buildExecutionToolPolicy, } from './execution-policy.js';
 const MCP_SERVER_SCRIPT = path.join(PKG_DIR, 'dist', 'tools', 'mcp-server.js');
@@ -469,6 +470,13 @@ export async function runAgent(prompt, opts) {
             });
         },
     });
+    // ── Live RunState hook (1.18.202) ─────────────────────────────────
+    // Hook-fed active-run state for Stop decisions. Durable history remains
+    // EventLog; this cache exists only while a run is active.
+    const runState = buildRunStateHooks({
+        runId,
+        sessionKey: opts.sessionKey,
+    });
     // ── 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
@@ -484,6 +492,7 @@ export async function runAgent(prompt, opts) {
         ? buildChatStopHook({
             runId,
             ...(opts.abortSignal ? { abortSignal: opts.abortSignal } : {}),
+            runState: runState.state,
             onDecision: (info) => {
                 if (info.decision !== 'continue')
                     return;
@@ -504,6 +513,10 @@ export async function runAgent(prompt, opts) {
         const existing = mergedHooks[evt] ?? [];
         mergedHooks[evt] = [...existing, ...matchers];
     }
+    for (const [evt, matchers] of Object.entries(runState.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];
@@ -861,6 +874,13 @@ export async function runAgent(prompt, opts) {
             recorded: idempotency.stats.recorded,
             failedNotRecorded: idempotency.stats.failedNotRecorded,
         } : undefined,
+        runState: runState.stats.inspected > 0 ? {
+            inspected: runState.stats.inspected,
+            sideEffects: runState.stats.sideEffects,
+            todosUpdated: runState.stats.todosUpdated,
+            successfulSideEffects: runState.state.successfulSideEffects.length,
+            failedSideEffects: runState.state.failedSideEffects.length,
+        } : 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/run-state.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Live per-run state fed by SDK hooks.
+ *
+ * Event logs are the durable source of truth. RunState is the hot-path cache:
+ * enough structured state for Stop hooks to make one good decision before the
+ * run ends, without reading JSONL from disk or expanding prompts.
+ */
+import type { HookCallbackMatcher, HookEvent } from '@anthropic-ai/claude-agent-sdk';
+export interface RunStateSideEffect {
+    toolName: string;
+    toolUseId?: string;
+    summary: string;
+    kind: 'side_effect' | 'unknown';
+    successful: boolean;
+    successReason?: string;
+    statusCode?: number;
+    ts: string;
+}
+export interface RunStateTodoSnapshot {
+    total: number;
+    pending: number;
+    inProgress: number;
+    completed: number;
+}
+export interface LiveRunState {
+    runId: string;
+    sessionKey?: string;
+    startedAt: number;
+    lastUpdatedAt: number;
+    readOnlyToolCalls: number;
+    unknownToolCalls: number;
+    totalToolCalls: number;
+    successfulSideEffects: RunStateSideEffect[];
+    failedSideEffects: RunStateSideEffect[];
+    todo?: RunStateTodoSnapshot;
+    ended?: {
+        reason?: string;
+        endedAt: number;
+    };
+}
+export interface RunStateStats {
+    inspected: number;
+    sideEffects: number;
+    todosUpdated: number;
+}
+export interface RunStateHookOptions {
+    runId: string;
+    sessionKey?: string;
+    now?: () => number;
+}
+export interface RunStateHookHandles {
+    state: LiveRunState;
+    hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    stats: RunStateStats;
+}
+export declare function getRunState(runId: string): LiveRunState | undefined;
+export declare function clearRunState(runId: string): void;
+export declare function buildRunStateHooks(opts: RunStateHookOptions): RunStateHookHandles;
+export declare function hasCompletedManifest(text: string): boolean;
+export declare function summarizeRunStateForManifest(state: LiveRunState): string;
+//# sourceMappingURL=run-state.d.ts.map

package/dist/agent/run-state.js

@@ -0,0 +1,164 @@
+/**
+ * Live per-run state fed by SDK hooks.
+ *
+ * Event logs are the durable source of truth. RunState is the hot-path cache:
+ * enough structured state for Stop hooks to make one good decision before the
+ * run ends, without reading JSONL from disk or expanding prompts.
+ */
+import { classifyToolCall, isToolResultSuccessful } from './side-effect-classifier.js';
+import { buildSideEffectFingerprint } from './side-effect-idempotency.js';
+const LIVE_RUNS = new Map();
+function nowIso(now) {
+    return new Date(now()).toISOString();
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function summarizeToolCall(toolName, input) {
+    const fp = buildSideEffectFingerprint(toolName, input);
+    if (fp)
+        return fp.summary;
+    if (toolName === 'Bash') {
+        const command = asRecord(input)?.command;
+        if (typeof command === 'string' && command.trim()) {
+            const preview = command.trim().replace(/\s+/g, ' ').slice(0, 96);
+            return `Bash mutation: ${preview}`;
+        }
+    }
+    return toolName;
+}
+function readTodoSnapshot(input) {
+    const rec = asRecord(input);
+    const todos = rec?.todos;
+    if (!Array.isArray(todos))
+        return undefined;
+    let pending = 0;
+    let inProgress = 0;
+    let completed = 0;
+    for (const item of todos) {
+        const status = asRecord(item)?.status;
+        if (status === 'completed')
+            completed += 1;
+        else if (status === 'in_progress')
+            inProgress += 1;
+        else
+            pending += 1;
+    }
+    return {
+        total: todos.length,
+        pending,
+        inProgress,
+        completed,
+    };
+}
+export function getRunState(runId) {
+    return LIVE_RUNS.get(runId);
+}
+export function clearRunState(runId) {
+    LIVE_RUNS.delete(runId);
+}
+export function buildRunStateHooks(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const state = {
+        runId: opts.runId,
+        ...(opts.sessionKey ? { sessionKey: opts.sessionKey } : {}),
+        startedAt: now(),
+        lastUpdatedAt: now(),
+        readOnlyToolCalls: 0,
+        unknownToolCalls: 0,
+        totalToolCalls: 0,
+        successfulSideEffects: [],
+        failedSideEffects: [],
+    };
+    const stats = { inspected: 0, sideEffects: 0, todosUpdated: 0 };
+    LIVE_RUNS.set(opts.runId, state);
+    const postToolUse = async (input) => {
+        if (input.hook_event_name !== 'PostToolUse')
+            return {};
+        const evt = input;
+        const toolName = String(evt.tool_name ?? 'unknown');
+        stats.inspected += 1;
+        state.totalToolCalls += 1;
+        state.lastUpdatedAt = now();
+        if (toolName === 'TodoWrite') {
+            const snapshot = readTodoSnapshot(evt.tool_input);
+            if (snapshot) {
+                state.todo = snapshot;
+                stats.todosUpdated += 1;
+            }
+            return {};
+        }
+        const inputRecord = asRecord(evt.tool_input);
+        const verdict = classifyToolCall(toolName, inputRecord);
+        if (verdict.kind === 'read_only') {
+            state.readOnlyToolCalls += 1;
+            return {};
+        }
+        if (verdict.kind === 'unknown') {
+            state.unknownToolCalls += 1;
+            return {};
+        }
+        const result = isToolResultSuccessful(evt.tool_response, false);
+        const sideEffect = {
+            toolName,
+            toolUseId: evt.tool_use_id,
+            summary: summarizeToolCall(toolName, evt.tool_input),
+            kind: 'side_effect',
+            successful: result.successful,
+            ...(result.successful ? { successReason: result.reason } : {}),
+            ...(result.statusCode !== undefined ? { statusCode: result.statusCode } : {}),
+            ts: nowIso(now),
+        };
+        stats.sideEffects += 1;
+        if (result.successful)
+            state.successfulSideEffects.push(sideEffect);
+        else
+            state.failedSideEffects.push(sideEffect);
+        return {};
+    };
+    const sessionEnd = async (input) => {
+        if (input.hook_event_name !== 'SessionEnd')
+            return {};
+        const evt = input;
+        state.ended = { reason: String(evt.reason ?? ''), endedAt: now() };
+        // Keep the state object alive for closures that already hold it, but drop
+        // the global index to prevent stale cross-run reads.
+        LIVE_RUNS.delete(opts.runId);
+        return {};
+    };
+    return {
+        state,
+        hooks: {
+            PostToolUse: [{ hooks: [postToolUse] }],
+            SessionEnd: [{ hooks: [sessionEnd] }],
+        },
+        stats,
+    };
+}
+export function hasCompletedManifest(text) {
+    return /✅\s*\*\*Completed\*\*/.test(text);
+}
+export function summarizeRunStateForManifest(state) {
+    const groups = new Map();
+    for (const effect of state.successfulSideEffects) {
+        const key = effect.summary;
+        groups.set(key, (groups.get(key) ?? 0) + 1);
+    }
+    const completed = Array.from(groups.entries())
+        .slice(0, 5)
+        .map(([summary, count]) => `- ${count > 1 ? `${count}x ` : ''}${summary}`)
+        .join('\n') || '- No side effects recorded';
+    const pending = state.todo && (state.todo.pending + state.todo.inProgress) > 0
+        ? `- TodoWrite: ${state.todo.pending + state.todo.inProgress} unfinished item(s)`
+        : '- None known';
+    return [
+        'Use this concise manifest before ending:',
+        '',
+        '✅ **Completed**',
+        completed,
+        '',
+        '⚠️ **Pending**',
+        pending,
+    ].join('\n');
+}
+//# sourceMappingURL=run-state.js.map

package/package.json

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