shraga 0.1.111 → 0.1.113

package/src/server/engine/claude-code.ts

@@ -8,7 +8,12 @@ import { listSkills } from '../skills.ts';
 import { loadAgents } from '../agents.ts';
 import { registerProactiveMessage } from '../slack/sessions.ts';
 import { registerPoll } from '../polls.ts';
-import { getSession, setSessionModel, getSessionModel, type ConvMessage } from '../sessions.ts';
+import { getSession, setSessionModel, getSessionModel, setClaudeResume, type ConvMessage } from '../sessions.ts';
+import {
+  isResumeEnabled, decideClaudeTurn, claudeConfigDir, findClaudeTranscript, shortHash, sectionHashes, speakerKey,
+  sectionsAfterSubmit, isResumeFailure, conversationSummaryKey, buildContextDelta, buildResumePrompt, renderConvMessage,
+  type TurnPath, type ClaudeResumeState,
+} from './claude-resume.ts';
 import { DEFAULT_MODEL } from '../directives.ts';
 import { resolveModelSwitch, MODEL_ALIASES } from '../model-aliases.ts';
 import type { WsEvent, AskQuestion, QuestionAnswers, QuestionHandler } from '../claude.ts';
@@ -18,6 +23,8 @@ import { APP_ROOT } from '../paths.ts';
 import { writeMcpConfigFile } from './mcp-config-file.ts';
 import { claudeUsageFor } from '../claude-usage.ts';
 import { claudeAccountDir, applyClaudeAccount, claudeAccountRef, type ClaudeAccountRef } from '../claude-account.ts';
+import { buildAgentEnv, builtinTools, filterMcpServers, allowsEscalate, allowsInternalToken, SENSITIVE_PATH_PATTERNS } from '../security/enforce.ts';
+import { escalateMcpServer } from '../security/escalate.ts';
 const IMMUTABLE_SYSTEM_PROMPT = readFileSync(path.resolve(import.meta.dirname, '../../../defaults/system-prompt.md'), 'utf-8');
 const DEFAULT_USER_PROMPT = `You are a helpful assistant with access to MCP tools.`;
 const DEFAULT_ALLOWED_TOOLS = ['Read', 'Edit', 'Bash', 'WebSearch', 'Glob', 'LS', 'ToolSearch'];
@@ -27,10 +34,6 @@ const HISTORY_LIMIT = 50;
 
 const NO_INTERACTIVE_ANSWER = 'No interactive channel is available to answer right now. Use your best judgement to proceed, and surface these options to the user in your reply so they can redirect if needed.';
 
-const SENSITIVE_PATTERNS = [
-  /\.env($|\.)/i, /secrets?\//i, /credentials/i, /\.pem$/i, /\.key$/i,
-  /service.account.*\.json/i, /\/\.claude\/credentials/i,
-];
 const SENSITIVE_BASH_PATTERNS = [
   /\.env\b/i, /\bprintenv\b/i, /\b(env|set)\s*\|/i, /\bsecrets?\//i,
   /credentials/i, /service.account/i, /\.(pem|key)\b/i,
@@ -58,7 +61,7 @@ type DenyResult = { behavior: 'deny'; message: string };
 function checkSensitiveAccess(toolName: string, input: Record<string, unknown>): DenyResult | null {
   const filePath = (input.file_path ?? input.path ?? '') as string;
   if ((toolName === 'Read' || toolName === 'Edit' || toolName === 'Write') && filePath) {
-    if (SENSITIVE_PATTERNS.some(p => p.test(filePath))) {
+    if (SENSITIVE_PATH_PATTERNS.some(p => p.test(filePath))) {
       console.log(`[security] Blocked ${toolName} on sensitive file: ${filePath}`);
       return { behavior: 'deny', message: 'Access to sensitive files (.env, secrets, credentials) is blocked.' };
     }
@@ -95,15 +98,8 @@ function buildHistoryPrompt(conv: ConvMessage[], contextBlock: string, userPromp
   const parts: string[] = [];
   if (summary) parts.push(`<conversation_summary>\n${summary}\n</conversation_summary>`);
   for (const m of recent) {
-    const role = m.role === 'user' ? 'User' : 'Assistant';
-    const texts = m.blocks
-      .filter((b) => b.type === 'text' || b.type === 'context')
-      .map((b) => {
-        if (b.type === 'context') return `[${(b as any).label}]: ${(b as any).text}`;
-        return (b as { type: 'text'; text: string }).text;
-      })
-      .filter(Boolean);
-    if (texts.length) parts.push(`${role}: ${texts.join('\n')}`);
+    const line = renderConvMessage(m);
+    if (line) parts.push(line);
   }
 
   if (parts.length) {
@@ -117,10 +113,11 @@ function buildHistoryPrompt(conv: ConvMessage[], contextBlock: string, userPromp
  * Log prompt-cache effectiveness from the SDK result `usage`. The hit rate is
  * cache_read / (cache_read + cache_creation + uncached input) — a low rate over
  * many turns points to a silent prefix invalidator or sessions spread past the
- * 5-min cache TTL. Note: cross-turn history is re-sent uncached (single-shot
- * prompt per query, no SDK resume) — so hit rate tracks tool density per turn.
+ * 5-min cache TTL. `path` says how the prompt was built — `fresh` (history re-sent in one message),
+ * `resume` (SDK session resumed, only the new message sent) or `fallback:<reason>` (resume enabled but a
+ * fresh query ran) — so journal lines can be A/B-compared per path.
  */
-function logCacheUsage(usage: any, model: string): void {
+function logCacheUsage(usage: any, model: string, path: TurnPath): void {
   if (!usage) return;
   const read = usage.cache_read_input_tokens ?? 0;
   const created = usage.cache_creation_input_tokens ?? 0;
@@ -128,9 +125,47 @@ function logCacheUsage(usage: any, model: string): void {
   const totalIn = read + created + fresh;
   if (totalIn === 0) return;
   const hitRate = ((read / totalIn) * 100).toFixed(1);
-  console.log(`[claude] Cache: hit=${hitRate}% read=${read} write=${created} uncached=${fresh} out=${usage.output_tokens ?? 0} model=${model}`);
+  console.log(`[claude] Cache: hit=${hitRate}% read=${read} write=${created} uncached=${fresh} out=${usage.output_tokens ?? 0} model=${model} path=${path}`);
+}
+
+/** How one query attempt is built. `persist` is set when resume is enabled: after a query that produced
+ *  output, the CC session id + these facts are saved so the next turn can resume. */
+interface RunPlan {
+  path: TurnPath;
+  prompt: string;
+  accountDir: string | null;
+  resumeId?: string;
+  persist?: Omit<ClaudeResumeState, 'claudeSessionId' | 'model' | 'interruptedBy'>;
+  /** Resume only: section hashes to store once the prompt is submitted (see sectionsAfterSubmit). */
+  submitSections?: Record<string, string>;
+}
+
+/** Exit promises of CLI processes still running, per shraga session. A turn that took over a session (external
+ *  steer) can start while the aborted run's CLI is still exiting; resuming then would put two writers on one
+ *  transcript. */
+const liveCli = new Map<string, Set<Promise<void>>>();
+
+function trackCliExit(sessionId: string | undefined, child: { once: (event: string, fn: () => void) => unknown }): void {
+  if (!sessionId) return;
+  const set = liveCli.get(sessionId) ?? new Set();
+  liveCli.set(sessionId, set);
+  const exited = new Promise<void>((resolve) => { child.once('exit', resolve); child.once('error', resolve); });
+  set.add(exited);
+  void exited.then(() => { set.delete(exited); if (!set.size && liveCli.get(sessionId) === set) liveCli.delete(sessionId); });
+}
+
+/** true once every CLI process of the session has exited, false if one is still alive after `ms`. */
+async function cliExited(sessionId: string, ms: number): Promise<boolean> {
+  const set = liveCli.get(sessionId);
+  if (!set?.size) return true;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((r) => { timer = setTimeout(() => r(false), ms); });
+  try { return await Promise.race([Promise.all(set).then(() => true), timeout]); } finally { clearTimeout(timer); }
 }
 
+/** Events that prove a resumed query actually runs; until one arrives the attempt can still be retried fresh unseen. */
+const LIVE_EVENTS = new Set<WsEvent['type']>(['text_delta', 'thinking_delta', 'tool_use', 'tool_use_input', 'tool_result', 'tool_result_image', 'done']);
+
 /** SDK spawn hook: same call the SDK would make, plus `detached` (own process group). See the
  *  call site for why. Shape mirrors the SDK's own spawnLocalProcess return. */
 function spawnDetached(cfg: { command: string; args: string[]; cwd?: string; env: Record<string, string | undefined>; signal?: AbortSignal }) {
@@ -205,6 +240,7 @@ async function* buildLegacyImagePrompt(text: string, images: string[], sessionId
 
 export class ClaudeCodeEngine implements AgentEngine {
   readonly name = 'claude-code';
+  readonly enforcesProfile = true;
 
   getModels(): EngineModel[] {
     return [
@@ -221,15 +257,82 @@ export class ClaudeCodeEngine implements AgentEngine {
     ];
   }
 
+  /** How long a resume-enabled turn waits for an earlier CLI process on the session to exit before going fresh. */
+  static cliExitWaitMs = 5_000;
+
   async *stream(opts: EngineStreamOpts): AsyncGenerator<WsEvent> {
+    let cliAlive = false;
+    if (opts.sessionId && isResumeEnabled(opts.directives, opts.config) && !(await cliExited(opts.sessionId, ClaudeCodeEngine.cliExitWaitMs))) {
+      cliAlive = true;
+      console.warn(`[claude] An earlier CLI process on session=${opts.sessionId} is still running after ${ClaudeCodeEngine.cliExitWaitMs}ms — not resuming its transcript`);
+    }
+    const plan = this.plan(opts, cliAlive);
+    if (plan.path !== 'resume') { yield* this.run(opts, plan); return; }
+    // Hold non-output events (init's model_resolved / switch notice) until the resumed query proves it
+    // runs, so a failed resume can be retried fresh with nothing duplicated on the user's side.
+    const attempt = this.run(opts, plan);
+    const held: WsEvent[] = [];
+    let live = false;
+    let r: IteratorResult<WsEvent, 'resume-failed' | void>;
+    try {
+      while (!(r = await attempt.next()).done) {
+        if (!live && !LIVE_EVENTS.has(r.value.type)) { held.push(r.value); continue; }
+        if (!live) { live = true; yield* held; }
+        yield r.value;
+      }
+    } finally {
+      await attempt.return(undefined);
+    }
+    if (r.value !== 'resume-failed') { if (!live) yield* held; return; }
+    console.warn(`[claude] Resume of ${plan.resumeId} failed before any output — retrying fresh in the same turn (session=${opts.sessionId})`);
+    setClaudeResume(opts.sessionId, undefined);
+    yield* this.run(opts, this.freshPlan(opts, plan.accountDir, 'fallback:resume-failed', plan.persist));
+  }
+
+  private freshPlan(opts: EngineStreamOpts, accountDir: string | null, path: TurnPath, persist?: RunPlan['persist']): RunPlan {
+    return {
+      path, accountDir,
+      prompt: buildHistoryPrompt(opts.conversation, opts.contextBlock, opts.prompt),
+      ...(persist ? { persist: { ...persist, sections: sectionHashes(opts.contextSections ?? { context: opts.contextBlock }), startedAt: Date.now() } } : {}),
+    };
+  }
+
+  /** Resume vs fresh, and why — see claude-resume.ts. */
+  private plan(opts: EngineStreamOpts, cliAlive: boolean): RunPlan {
+    const accountDir = claudeAccountDir(opts.userEmail);
+    if (!isResumeEnabled(opts.directives, opts.config)) return this.freshPlan(opts, accountDir, 'fresh');
+    const configDir = claudeConfigDir(accountDir);
+    const configDirHash = shortHash(configDir);
+    const state = opts.sessionId ? getSession(opts.sessionId)?.claudeResume : undefined;
+    const speaker = speakerKey(opts.uid, opts.userEmail);
+    const persist = { configDirHash, speaker, markId: opts.conversation.at(-1)?.id, summaryKey: conversationSummaryKey(opts.conversation), sections: {}, startedAt: Date.now() };
+    const decision = decideClaudeTurn({
+      enabled: true, state, conversation: opts.conversation, configDirHash, speaker, cliAlive, conversationReset: opts.conversationReset,
+      hasTranscript: (id) => !!findClaudeTranscript(id, configDir),
+    });
+    if (decision.path !== 'resume' || !state) return this.freshPlan(opts, accountDir, decision.path, persist);
+    const sections = opts.contextSections ?? { context: opts.contextBlock };
+    const hashes = sectionHashes(sections);
+    return {
+      path: 'resume', accountDir, resumeId: state.claudeSessionId,
+      prompt: buildResumePrompt(opts.prompt, decision.unseen, buildContextDelta(state.sections, sections)),
+      persist: { ...persist, sections: hashes, startedAt: state.startedAt },
+      submitSections: sectionsAfterSubmit(state.sections, hashes),
+    };
+  }
+
+  private async *run(opts: EngineStreamOpts, plan: RunPlan): AsyncGenerator<WsEvent, 'resume-failed' | void> {
     const { config, directives } = opts;
     const cwd = APP_ROOT;
 
-    const fullPrompt = buildHistoryPrompt(opts.conversation, opts.contextBlock, opts.prompt);
+    const fullPrompt = plan.prompt;
     const permMode = opts.onPermissionRequest ? 'default' : (config.permissionMode ?? 'acceptEdits');
 
-    const sdkEnv: Record<string, string> = {};
-    for (const [k, v] of Object.entries(process.env)) {
+    // SECURITY_ENFORCE: the effective profile at spawn decides env/tools/MCPs; the per-call gate re-reads it (enforce.ts).
+    const guard = opts.security;
+    const eff = guard?.current();
+    const sdkEnv: Record<string, string> = eff ? buildAgentEnv(process.env, eff.profile) : {};
+    if (!eff) for (const [k, v] of Object.entries(process.env)) {
       if (v !== undefined) sdkEnv[k] = v;
     }
     // Injected for the agent's own tools/scripts. Each is written under both the canonical
@@ -251,7 +354,7 @@ export class ClaudeCodeEngine implements AgentEngine {
     // regardless of settingSources; headless they are auth stubs or self-recursion. Our MCPs come from mcp-config.
     setIfBlank('ENABLE_CLAUDEAI_MCP_SERVERS', 'false');
     // Per-user subscription (workspace/users/<contactId>/.claude): run on that login, never the box's credentials.
-    const accountDir = claudeAccountDir(opts.userEmail);
+    const accountDir = plan.accountDir;
     if (accountDir) applyClaudeAccount(sdkEnv, accountDir);
     // Which login this run is on (email/plan, never a token) — read lazily from the login's local
     // files, only once init proves the run is on a subscription login (see init below).
@@ -259,14 +362,24 @@ export class ClaudeCodeEngine implements AgentEngine {
     const accountRef = () => (accountRefP ??= claudeAccountRef(accountDir));
     let runAccount: ClaudeAccountRef | undefined;
     let sawInit = false;
+    // Did THIS attempt produce model output? Gates both the resume-failure retry and saving the session id
+    // (a resume that died on "No conversation found" can report a session id it never wrote a turn to).
+    let sawOutput = false;
+    let initModel: string | undefined;
     sdkEnv.INTERNAL_API_TOKEN = signInternalToken(opts.uid, opts.userEmail || 'unknown');
 
+    if (eff && !allowsInternalToken(eff.profile)) delete sdkEnv.INTERNAL_API_TOKEN;
+
     const baseAllowed = config.allowedTools ?? DEFAULT_ALLOWED_TOOLS;
-    const allowedTools = baseAllowed.includes('ToolSearch') ? baseAllowed : [...baseAllowed, 'ToolSearch'];
+    const withToolSearch = baseAllowed.includes('ToolSearch') ? baseAllowed : [...baseAllowed, 'ToolSearch'];
+    // Enforced: built-in tool AVAILABILITY is the profile's (tools outside it are not in the model's context), and
+    // auto-approval never widens it.
+    const available = eff ? builtinTools(eff.profile) : 'all';
+    const allowedTools = available === 'all' ? withToolSearch : withToolSearch.filter((t) => available.includes(t));
     const maxTurns = directives.turns ?? config.maxTurns ?? 50;
 
     const options: Record<string, unknown> = {
-      tools: { type: 'preset', preset: 'claude_code' },
+      tools: available === 'all' ? { type: 'preset', preset: 'claude_code' } : available,
       env: sdkEnv,
       allowedTools,
       cwd,
@@ -286,15 +399,24 @@ export class ClaudeCodeEngine implements AgentEngine {
       skills: listSkills(),
       disallowedTools: ['Skill'],
       agents: loadAgents(),
-      hooks: buildHooks({ exemptBashCommand: opts.foregroundBashCommand }),
+      // Enforced: the profile gate runs FIRST on every tool call — hooks fire even for auto-approved `allowedTools`,
+      // which never reach canUseTool.
+      hooks: ((h) => (guard ? { ...h, PreToolUse: [{ hooks: [guard.hook()] }, ...(h.PreToolUse ?? [])] } : h))(buildHooks({ exemptBashCommand: opts.foregroundBashCommand })),
     };
 
     const userHandler = opts.onPermissionRequest;
     const destructiveHandler = opts.onDestructiveApproval;
     const questionHandler = opts.onUserQuestion;
     options['canUseTool'] = async (toolName: string, input: Record<string, unknown>) => {
-      const denied = checkSensitiveAccess(toolName, input);
+      // Enforced: TurnGuard owns the file-path deny (tightened list); the legacy path list stays flag-OFF behavior only.
+      const denied = guard && toolName !== 'Bash' ? null : checkSensitiveAccess(toolName, input);
       if (denied) return denied;
+      // Enforced: the profile gate (re-reads the session floor) runs before ANY handler below, so an
+      // `onPermissionRequest: allow` call site can never override a profile deny.
+      if (guard) {
+        const gate = guard.check(toolName, input, cwd);
+        if (!gate.allow) return { behavior: 'deny' as const, message: gate.message };
+      }
       if (toolName === 'AskUserQuestion') {
         const questions = (input.questions ?? []) as AskQuestion[];
         const answers = questionHandler
@@ -357,24 +479,42 @@ export class ClaudeCodeEngine implements AgentEngine {
     const addonSuffix = getPromptSuffix(opts.turnHints);
     options['systemPrompt'] = `${IMMUTABLE_SYSTEM_PROMPT}\n\n${userPrompt}${addonSuffix ? `\n\n${addonSuffix}` : ''}`;
     if (opts.abortController) options['abortController'] = opts.abortController;
+    if (plan.resumeId) options['resume'] = plan.resumeId;
     // Spawn the CLI in its OWN process group. The service manager signals the whole JOB on restart
     // (`launchctl kickstart -k`, `systemctl restart`), so an inherited process group means the child
     // dies instantly with SIGTERM — surfacing mid-reply as `exited with code 143` and making the
     // server's 90s drain (gracefulShutdown) protect nothing: it only ever waited for a turn that was
     // already dead. Detached, the signal reaches the server alone and the drain can finish the turn.
     // Teardown is unaffected: the SDK still kills the child on abort/close and on process exit.
-    options['spawnClaudeCodeProcess'] = spawnDetached;
+    options['spawnClaudeCodeProcess'] = (cfg: Parameters<typeof spawnDetached>[0]) => {
+      const child = spawnDetached(cfg);
+      trackCliExit(opts.sessionId, child);
+      return child;
+    };
 
     // Passed as a FILE, never as `options.mcpServers` — the SDK would put the whole config (every MCP
     // server's credentials) on the CLI's argv, where `ps` / `/proc` / journald expose it. See
     // writeMcpConfigFile. Setting both would re-add the argv copy, so it's one or the other.
     let mcpConfigFile: { path: string; cleanup: () => void } | undefined;
-    if (opts.mcpServers && Object.keys(opts.mcpServers).length > 0) {
-      mcpConfigFile = writeMcpConfigFile(opts.mcpServers);
+    // Enforced: servers outside profile.mcps never reach the file, so the CLI never starts them.
+    const mcpServers = eff ? filterMcpServers(opts.mcpServers, eff.profile) : opts.mcpServers;
+    if (mcpServers && Object.keys(mcpServers).length > 0) {
+      mcpConfigFile = writeMcpConfigFile(mcpServers);
       options['extraArgs'] = { ...(options['extraArgs'] as Record<string, string> | undefined), 'mcp-config': mcpConfigFile.path };
     }
+    // `escalate` is an in-process SDK server (no credentials): `options.mcpServers` hands the CLI only its name.
+    if (guard && eff && allowsEscalate(eff.profile)) {
+      const { principal } = guard.options;
+      const lastUser = opts.conversation.findLast((m) => m.role === 'user');
+      const excerpt = lastUser?.blocks.map((b) => (b.type === 'text' ? b.text : '')).filter(Boolean).join('\n') || opts.prompt;
+      const server = escalateMcpServer({
+        principal, role: () => guard.current().role, sessionId: opts.sessionId, excerpt,
+        channel: [principal.kind, principal.attrs.lane, opts.context?.source].filter(Boolean).join(':'),
+      });
+      options['mcpServers'] = { [server.name]: server };
+    }
 
-    const mcpNames = opts.mcpServers ? Object.keys(opts.mcpServers) : [];
+    const mcpNames = mcpServers ? Object.keys(mcpServers) : [];
     const activeModel = (options['model'] as string) || 'default';
     const directivesTag = Object.keys(directives).length ? ` directives=${JSON.stringify(directives)}` : '';
     console.log(`[claude] Starting query user=${opts.uid} session=${opts.sessionId ?? 'new'} model=${activeModel} perms=${config.permissionMode} mcps=[${mcpNames.join(',')}]${directivesTag} cwd=${cwd}`);
@@ -391,6 +531,8 @@ export class ClaudeCodeEngine implements AgentEngine {
         : fullPrompt;
 
     const q = query({ prompt, options: options as any });
+    // The CLI writes this prompt to the transcript before any output: from here a cancel can't un-deliver it.
+    if (plan.submitSections && opts.sessionId) setClaudeResume(opts.sessionId, undefined, { sections: plan.submitSections });
 
     let lastSessionId = '';
     let messageCount = 0;
@@ -449,6 +591,7 @@ export class ClaudeCodeEngine implements AgentEngine {
           // default only counts when the SDK says it resolved a login, not an API key.
           if ((authSource ?? (accountDir ? 'subscription' : undefined)) === 'subscription') runAccount = await accountRef();
           if (m.model) {
+            initModel = m.model;
             console.log(`[claude] Init model=${m.model}${m.model !== options['model'] ? ` (requested ${options['model']})` : ''}`);
             // If the user explicitly asked to switch models via a [directive], announce the change
             // inline so the response confirms the switch took effect.
@@ -494,7 +637,7 @@ export class ClaudeCodeEngine implements AgentEngine {
           const raw = m.subtype ?? 'unknown';
           const sub = raw === 'error_max_turns' || (raw === 'end_turn' && sdkTurns >= maxTurns) ? 'max_turns_reached' : raw;
           console.log(`[claude] Result: subtype=${m.subtype}→${sub} session=${lastSessionId} turns=${sdkTurns}/${maxTurns} cost=$${m.total_cost_usd?.toFixed(4) ?? '?'} msgs=${messageCount} deltas=${textDeltaCount} (${elapsed()})`);
-          logCacheUsage(m.usage, activeModel);
+          logCacheUsage(m.usage, activeModel, plan.path);
           if (outstandingTasks.size > 0) {
             if (!waitingForBg) {
               waitingForBg = true; clearBgTimer();
@@ -514,6 +657,12 @@ export class ClaudeCodeEngine implements AgentEngine {
           // `error_max_turns` also sets is_error but is a benign stop reason we already model.
           if ((m.is_error || m.api_error_status) && sub !== 'max_turns_reached') {
             const detail = typeof m.result === 'string' && m.result ? m.result : `api_error_status=${m.api_error_status ?? '?'}`;
+            // The CLI's reason ("No conversation found with session ID …") rides in `errors`, not `result`.
+            const reasons = Array.isArray(m.errors) && m.errors.length ? m.errors.join('; ') : detail;
+            if (plan.resumeId && !sawOutput && isResumeFailure(reasons)) {
+              console.error(`[claude] Resume error result (subtype=${raw}) — ${reasons}`);
+              return 'resume-failed';
+            }
             // A usage/rate-limit failure is about ONE login's quota — name it, or a routed user's own
             // exhausted Pro plan reads as the shared agent subscription being out.
             const limitHit = m.api_error_status === 429 || /\b(usage|rate.?limit(ed)?|hit your limit)\b/i.test(detail);
@@ -532,10 +681,12 @@ export class ClaudeCodeEngine implements AgentEngine {
         if (m.type === 'stream_event') {
           const event = m.event;
           if (event?.type === 'content_block_delta' && event.delta?.type === 'thinking_delta') {
+            sawOutput = true;
             yield { type: 'thinking_delta', text: event.delta.thinking };
           }
           if (event?.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
             textDeltaCount++;
+            sawOutput = true;
             yield { type: 'text_delta', text: event.delta.text };
           }
           if (event?.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
@@ -557,6 +708,7 @@ export class ClaudeCodeEngine implements AgentEngine {
 
         if (m.type === 'assistant' && Array.isArray(m.message?.content)) {
           turnCount++;
+          sawOutput = true;
           for (const block of m.message.content) {
             if (block.type === 'tool_use') {
               pendingToolUses.set(block.id, { tool: block.name, input: block.input });
@@ -645,6 +797,7 @@ export class ClaudeCodeEngine implements AgentEngine {
         return;
       }
       console.error(`[claude] Error after ${messageCount} msgs (${elapsed()}):`, err.message || err);
+      if (plan.resumeId && !sawOutput && isResumeFailure(err.message || String(err))) return 'resume-failed';
       yield { type: 'error', message: err.message || String(err) };
       return;
     } finally {
@@ -652,6 +805,11 @@ export class ClaudeCodeEngine implements AgentEngine {
       // The CLI has read the file by now (it loads MCP config at startup); holding it any longer just
       // widens the window in which the credentials sit on disk.
       mcpConfigFile?.cleanup();
+      // Save the mapping once this attempt really ran a turn (incl. an aborted one — the transcript holds it).
+      if (plan.persist && opts.sessionId && lastSessionId && sawOutput) {
+        setClaudeResume(opts.sessionId, { ...plan.persist, claudeSessionId: lastSessionId, ...(initModel ? { model: initModel } : {}) });
+        if (plan.resumeId && plan.resumeId !== lastSessionId) console.warn(`[claude] Resume returned a new session id ${lastSessionId} (was ${plan.resumeId})`);
+      }
     }
 
     const inferredReason = turnCount >= maxTurns ? 'max_turns_reached' : 'end_turn';

package/src/server/engine/claude-resume.ts

@@ -0,0 +1,205 @@
+/**
+ * Opt-in SDK session resume for the claude-code engine — the pure half (decision + prompt building),
+ * kept free of SDK/IO wiring so every fallback reason is unit-testable.
+ *
+ * Fresh turn (today's path): ONE user message = contextBlock + <conversation_history> + new message, so
+ * the whole history is re-written to prompt cache every turn. Resume turn: `resume: <claudeSessionId>`
+ * and send only the new message; the stable context went in once on the session's fresh query, and
+ * whatever CHANGED since (context sections, messages other channels appended) plus the current speaker's
+ * `user` section rides AFTER the user text so the cached transcript prefix stays byte-identical. Only one
+ * speaker's turns ever share a CC session (speaker-change).
+ *
+ * Flag: `directives.resume` (per conversation: `[resume:on]` or PUT /api/sessions/:id/directives) over
+ * `agent-config.json` `sdkResume` (global, re-read every turn). Default OFF.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import type { ConvMessage } from '../sessions.ts';
+import type { Directives } from '../directives.ts';
+import type { AgentSettings } from '../shraga-config.ts';
+
+/** Persisted on SessionMeta.claudeResume — the facts needed to decide whether the stored CC session
+ *  may be resumed. Hashes, not content: this lives in the 9 MB sessions index. */
+export interface ClaudeResumeState {
+  /** Claude Code session id (SDK init/result `session_id`); resume keeps it stable across turns. */
+  claudeSessionId: string;
+  /** Hash of the CLAUDE_CONFIG_DIR the transcript was written under (per-user login or box default). */
+  configDirHash: string;
+  /** speakerKey() of the person whose turns this CC session holds. Another speaker never resumes it: the
+   *  transcript carries this speaker's private user context (learnings/corrections). */
+  speaker?: string;
+  /** Model the last turn resolved (informational — CC resumes across models; only the cache is per-model). */
+  model?: string;
+  /** When this CC session was started (first fresh query). */
+  startedAt: number;
+  /** Id of the last conversation message at the start of the last turn; messages after it are what CC hasn't seen. */
+  markId?: string;
+  /** Identity of the newest shraga summary / compact marker when the state was saved. */
+  summaryKey: string;
+  /** Section name → hash of the context CC has already been given. */
+  sections: Record<string, string>;
+  /** Set by the core when another engine ran a turn on this session (its turns aren't in the CC transcript). */
+  interruptedBy?: string;
+}
+
+export type TurnPath = 'resume' | 'fresh' | `fallback:${string}`;
+
+/** Unseen out-of-band text above this size means resume would re-send a history anyway — go fresh. */
+export const MAX_UNSEEN_CHARS = 30_000;
+
+export function isResumeEnabled(directives: Directives, config: AgentSettings): boolean {
+  // The per-session directives endpoint stores passthrough values opaquely, so accept string forms too.
+  const v = (directives.resume ?? config.sdkResume) as unknown;
+  return v === true || v === 'on' || v === 'true';
+}
+
+export function shortHash(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+/** Who is speaking, as a hash (the sessions index must not gain raw emails). */
+export function speakerKey(uid: string, email?: string): string {
+  return shortHash(`${uid}\n${email?.trim().toLowerCase() ?? ''}`);
+}
+
+/** Errors that mean THIS resume can't run (the stored transcript is gone/unreadable) — worth one fresh retry.
+ *  Anything else (quota, auth, API, process crash) would fail a fresh query the same way: surface it as-is. */
+export function isResumeFailure(text: string): boolean {
+  return /No conversation found|\b(session|transcript)\b.{0,60}\b(not found|missing|corrupt|invalid)\b/i.test(text);
+}
+
+/** Where the CLI keeps transcripts for a run: the routed per-user login, else the process's config dir. */
+export function claudeConfigDir(accountDir: string | null | undefined): string {
+  return accountDir || process.env.CLAUDE_CONFIG_DIR?.trim() || path.join(homedir(), '.claude');
+}
+
+/** `<configDir>/projects/<cwd-slug>/<id>.jsonl`, found by scan rather than by re-deriving the CLI's slug
+ *  rule (a wrong guess would silently turn every resume into a fallback). */
+export function findClaudeTranscript(sessionId: string, configDir: string): string | null {
+  const projects = path.join(configDir, 'projects');
+  if (!existsSync(projects)) return null;
+  for (const dir of readdirSync(projects, { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue;
+    const file = path.join(projects, dir.name, `${sessionId}.jsonl`);
+    if (existsSync(file)) return file;
+  }
+  return null;
+}
+
+/** One conversation message as history text — shared by the fresh history prompt and the resume tail. */
+export function renderConvMessage(m: ConvMessage): string | null {
+  const texts = m.blocks
+    .filter((b) => b.type === 'text' || b.type === 'context')
+    .map((b) => (b.type === 'context' ? `[${b.label}]: ${b.text}` : (b as { text: string }).text))
+    .filter(Boolean);
+  return texts.length ? `${m.role === 'user' ? 'User' : 'Assistant'}: ${texts.join('\n')}` : null;
+}
+
+/** Changes whenever maybeCompact writes a summary or /compact adds a marker (applyCompactMarkers
+ *  turns the latter into a synthetic leading message). */
+export function conversationSummaryKey(conv: ConvMessage[]): string {
+  for (let i = conv.length - 1; i >= 0; i--) {
+    const s = conv[i].blocks.find((b) => b.type === 'summary') as { compactedCount: number } | undefined;
+    if (s) return `summary:${s.compactedCount}`;
+  }
+  const first = conv[0];
+  if (first?.id === 'compact-summary') return `marker:${shortHash(renderConvMessage(first) ?? '')}`;
+  return '';
+}
+
+/**
+ * Messages CC has not seen: everything after the mark, minus the previous turn's own reply (the first
+ * message, when it is the assistant's) and this turn's prompt (the last, when it is a user message —
+ * every channel appends it before streaming). null = the mark is gone (history was rewritten).
+ */
+export function unseenMessages(conv: ConvMessage[], markId: string | undefined): ConvMessage[] | null {
+  if (!markId) return null;
+  const idx = conv.findLastIndex((m) => m.id === markId);
+  if (idx < 0) return null;
+  const after = conv.slice(idx + 1);
+  if (after[0]?.role === 'assistant') after.shift();
+  if (after.at(-1)?.role === 'user') after.pop();
+  return after;
+}
+
+export interface TurnDecisionInput {
+  enabled: boolean;
+  state?: ClaudeResumeState;
+  conversation: ConvMessage[];
+  configDirHash: string;
+  speaker: string;
+  /** A CLI process from an earlier run on this session is still alive (e.g. the run a steer took over). */
+  cliAlive?: boolean;
+  conversationReset?: boolean;
+  hasTranscript: (claudeSessionId: string) => boolean;
+}
+
+export function decideClaudeTurn(i: TurnDecisionInput): { path: TurnPath; unseen: ConvMessage[] } {
+  const fallback = (reason: string) => ({ path: `fallback:${reason}` as TurnPath, unseen: [] });
+  if (!i.enabled) return { path: 'fresh', unseen: [] };
+  const s = i.state;
+  if (!s?.claudeSessionId) return fallback('no-session');
+  // Two CLI processes appending to one transcript can interleave it; the takeover turn starts its own.
+  if (i.cliAlive) return fallback('concurrent-run');
+  if (s.speaker !== i.speaker) return fallback('speaker-change');
+  if (s.interruptedBy) return fallback('engine-switch');
+  if (s.configDirHash !== i.configDirHash) return fallback('account-change');
+  if (i.conversationReset) return fallback('reset');
+  if (s.summaryKey !== conversationSummaryKey(i.conversation)) return fallback('summary');
+  const unseen = unseenMessages(i.conversation, s.markId);
+  if (!unseen) return fallback('history-diverged');
+  if (unseen.reduce((n, m) => n + (renderConvMessage(m)?.length ?? 0), 0) > MAX_UNSEEN_CHARS) return fallback('drift');
+  // Checked last (filesystem): the CLI's periodic cleanup (cleanupPeriodDays) or a moved config dir
+  // deletes transcripts under sessions we still hold — catch it before spawning a doomed resume.
+  if (!i.hasTranscript(s.claudeSessionId)) return fallback('transcript-missing');
+  return { path: 'resume', unseen };
+}
+
+export function sectionHashes(sections: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(sections)) if (v) out[k] = shortHash(v);
+  return out;
+}
+
+/** Re-sent on every resume turn regardless of hashes: who is speaking (identity + role) must never depend on
+ *  bookkeeping about what an earlier, possibly cancelled, turn managed to deliver. Small. */
+export const ALWAYS_SENT_SECTIONS = ['user'];
+
+/** Hash marking a section whose delivery is unknown — never equals a real hash, so the next turn re-sends it. */
+const UNKNOWN = '?';
+
+/**
+ * Section hashes to store the moment a resume prompt is SUBMITTED. The CLI writes the prompt to the
+ * transcript before any output, so a turn cancelled early may or may not have delivered its delta. Unchanged
+ * sections are known either way; changed, new and removed ones are marked unknown and re-sent next turn.
+ */
+export function sectionsAfterSubmit(prev: Record<string, string>, next: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const k of new Set([...Object.keys(prev), ...Object.keys(next)])) out[k] = prev[k] === next[k] ? prev[k] : UNKNOWN;
+  return out;
+}
+
+/** The context sections that changed since CC last saw them (new or edited) plus ALWAYS_SENT_SECTIONS, and a
+ *  note for sections that no longer apply. '' when there is nothing to send. */
+export function buildContextDelta(prev: Record<string, string>, sections: Record<string, string>): string {
+  const changed = Object.entries(sections).filter(([k, v]) => v && (ALWAYS_SENT_SECTIONS.includes(k) || prev[k] !== shortHash(v)));
+  const removed = Object.keys(prev).filter((k) => !sections[k]);
+  if (!changed.length && !removed.length) return '';
+  return [
+    '<context_update>',
+    'Current context for this turn. Each section below replaces its earlier version.',
+    ...changed.map(([k, v]) => `<section name="${k}">\n${v}\n</section>`),
+    ...(removed.length ? [`No longer applicable: ${removed.join(', ')}`] : []),
+    '</context_update>',
+  ].join('\n');
+}
+
+export function buildResumePrompt(prompt: string, unseen: ConvMessage[], delta: string): string {
+  const lines = unseen.map(renderConvMessage).filter(Boolean);
+  const unseenBlock = lines.length
+    ? `<messages_since_last_turn>\nAdded to this conversation since your last reply (other participants, channel context, notices):\n${lines.join('\n\n')}\n</messages_since_last_turn>`
+    : '';
+  return [prompt, unseenBlock, delta].filter(Boolean).join('\n\n');
+}

package/src/server/engine/types.ts

@@ -3,6 +3,7 @@ import type { WsEvent, AttachmentMeta, PermissionHandler, QuestionHandler } from
 import type { ConvMessage } from '../sessions.ts';
 import type { Directives } from '../directives.ts';
 import type { AgentSettings } from '../shraga-config.ts';
+import type { TurnGuard } from '../security/enforce.ts';
 
 export interface EngineStreamOpts {
   /** The user's effective prompt (after directive stripping, slash command expansion, skill/workspace mentions) */
@@ -11,6 +12,9 @@ export interface EngineStreamOpts {
   conversation: ConvMessage[];
   /** Contextual blocks to prepend (user block, skills, workspace tree, etc.) */
   contextBlock: string;
+  /** The same context split into named sections (in contextBlock order), so an engine that keeps
+   *  state across turns can send only what changed. Joined with '\n' they equal contextBlock. */
+  contextSections?: Record<string, string>;
 
   attachments?: AttachmentMeta[];
   images?: string[];
@@ -32,6 +36,9 @@ export interface EngineStreamOpts {
   /** True when the conversation was truncated (user replayed/edited a message) — engines with cached state should reset. */
   conversationReset?: boolean;
   context?: Record<string, string>;
+  /** SECURITY_ENFORCE only: the turn's security context. The engine derives tools/MCP/env from its effective
+   *  profile and gates every tool call through it. Absent (flag off) ⇒ today's behavior, untouched. */
+  security?: TurnGuard;
 
   directives: Directives;
   config: AgentSettings;
@@ -39,6 +46,9 @@ export interface EngineStreamOpts {
 
 export interface AgentEngine {
   readonly name: string;
+  /** True if the engine applies `EngineStreamOpts.security` (profile tools/MCP/env + per-call gate). Under
+   *  SECURITY_ENFORCE an engine without it may only run turns whose effective profile is unrestricted. */
+  readonly enforcesProfile?: boolean;
   stream(opts: EngineStreamOpts): AsyncGenerator<WsEvent>;
   /** Return model options for the UI picker (only called when engine is available) */
   getModels(): EngineModel[];