@namzu/sdk 43.0.0 → 44.0.0

package/dist/runtime/query/executor.js

@@ -6,6 +6,7 @@ import { ProbeVetoError } from '../../probe/errors.js';
 import { probe as defaultProbeRegistry } from '../../probe/registry.js';
 import { SKILL_TOOL_NAME } from '../../tools/builtins/skill.js';
 import { createFileReadTracker } from '../../tools/file-read-tracker.js';
+import { pathOutsideRoots, toolRoots } from '../../tools/paths.js';
 import { createToolMessage, } from '../../types/message/index.js';
 import { abortReasonText } from '../../utils/abort.js';
 import { awaitWithAbort } from '../../utils/await-with-abort.js';
@@ -206,7 +207,7 @@ export class ToolExecutor {
     constructor(config, activityStore, emitEvent, log, probes = defaultProbeRegistry) {
         assertMaxToolCalls(config.maxToolCalls);
         if (config.maxToolCalls !== undefined) {
-            this.toolCallBudget = new ToolCallBudget(config.maxToolCalls, config.runId, emitEvent, config.readToolCallBudgetEvents);
+            this.toolCallBudget = new ToolCallBudget(config.maxToolCalls, config.turnId, emitEvent, config.readToolCallBudgetRecords);
         }
         this.fileReadTracker = config.fileReadTracker ?? createFileReadTracker();
         this.config = config;
@@ -222,14 +223,14 @@ export class ToolExecutor {
         this.config = { ...this.config, sandbox };
     }
     /**
-     * Rebuild this run's observation ledger from history a resume restored.
+     * Rebuild this turn's observation ledger from history a resume restored.
      *
      * Once, and only from a history that has already been repaired — the ledger
      * has to describe what the model is about to be shown, not what was
      * checkpointed before the repair removed an abandoned call. `sandboxed` is
-     * passed rather than read off this executor's config because a resumed run
+     * passed rather than read off this executor's config because a resumed turn
      * restores its history before it acquires a sandbox, so the config does not
-     * know yet what the run's tool paths will be keyed on.
+     * know yet what the turn's tool paths will be keyed on.
      *
      * Awaited, and the only filesystem work anywhere in this feature: the seed
      * has to write its entries under the keys the mutation tools will look them
@@ -248,7 +249,7 @@ export class ToolExecutor {
             sandboxed,
         });
         this.log.info('Rebuilt the file observation ledger from restored history', {
-            [NAMZU.RUN_ID]: this.config.runId,
+            [NAMZU.TURN_ID]: this.config.turnId,
             'namzu.files.witnessed': report.pathsWitnessed,
             'namzu.files.seen': report.pathsSeen,
             'namzu.files.replayed_units': report.unitsReplayed,
@@ -270,10 +271,10 @@ export class ToolExecutor {
      * Narrow what this turn may call, or clear the narrowing.
      *
      * Re-set each turn by the orchestrator for the same reason the parent span
-     * is: `prepareStep` can hand a different list to every step, and the run's
+     * is: `prepareStep` can hand a different list to every step, and the turn's
      * own `allowedTools` is only the default when a step names none.
      *
-     * Without this the executor could only ever see the RUN-level list, so a
+     * Without this the executor could only ever see the TURN-level list, so a
      * per-step narrowing reached the request that was sent and nothing else —
      * the model was shown fewer tools and could still call all of them.
      */
@@ -382,7 +383,7 @@ export class ToolExecutor {
         const configured = this.config.permissionMode;
         return typeof configured === 'function' ? configured() : configured;
     }
-    /** Evaluate the run's operator policy against one already-prepared value. */
+    /** Evaluate the turn's operator policy against one already-prepared value. */
     evaluatePreparedAuthorization(toolName, input) {
         return this.config.authorizationGate?.evaluate({
             toolName,
@@ -398,10 +399,57 @@ export class ToolExecutor {
     async prepareBatchForReview(response) {
         assertUniqueToolCallIds(response.message.toolCalls ?? []);
         const calls = new Map();
+        const escalations = new Map();
         for (const toolCall of response.message.toolCalls ?? []) {
-            calls.set(toolCall.id, await prepareDirectCall(this.admissionHost(), toolCall));
+            const call = await prepareDirectCall(this.admissionHost(), toolCall);
+            calls.set(toolCall.id, call);
+            const escalation = await this.escalationOf(call);
+            if (escalation)
+                escalations.set(toolCall.id, escalation);
         }
-        return this.publishPreparedBatch(calls);
+        return this.publishPreparedBatch(calls, escalations);
+    }
+    /**
+     * What a prepared call reaches past the turn's boundary, decided on the
+     * value that will execute — after repairs and pre-tool hooks, so a hook
+     * that rewrites a path is reviewed under the path it wrote.
+     *
+     * Each half is computed only when the turn asked for it; with neither,
+     * this is `undefined` for every call and the tools refuse as they always
+     * have. Paths are looked at only without a sandbox: inside one the tools
+     * resolve against the sandbox's own root, and a host path outside the
+     * roots is not mounted there to be approved. The escape is looked at only
+     * WITH one, since without one there is nothing to escape.
+     */
+    async escalationOf(call) {
+        if (call.kind === 'synthetic')
+            return undefined;
+        const tool = this.config.tools.get(call.toolName);
+        if (!tool || call.input === null || typeof call.input !== 'object')
+            return undefined;
+        const input = call.input;
+        const sandboxed = this.config.sandbox !== undefined;
+        let outsidePaths;
+        if (this.config.outsideRootAccess === 'review' &&
+            !sandboxed &&
+            tool.pathArgument !== undefined) {
+            const value = input[tool.pathArgument];
+            if (typeof value === 'string') {
+                const outside = await pathOutsideRoots(toolRoots(this.config), value);
+                if (outside !== undefined)
+                    outsidePaths = [outside];
+            }
+        }
+        const sandboxEscape = this.config.sandboxEscape === 'review' &&
+            sandboxed &&
+            tool.sandboxEscapeArgument !== undefined &&
+            input[tool.sandboxEscapeArgument] === true;
+        if (!outsidePaths && !sandboxEscape)
+            return undefined;
+        return {
+            ...(outsidePaths ? { outsidePaths } : {}),
+            ...(sandboxEscape ? { sandboxEscape: true } : {}),
+        };
     }
     /** Re-prepare only calls whose raw input a reviewer actually changed. */
     async reprepareBatchForReview(response, previous, changedCallIds) {
@@ -410,24 +458,36 @@ export class ToolExecutor {
             throw new Error('Prepared tool batch is not owned by this executor.');
         }
         const calls = new Map(previous.calls);
+        const escalations = new Map(previous.escalations);
         for (const toolCall of response.message.toolCalls ?? []) {
             if (changedCallIds.has(toolCall.id)) {
-                calls.set(toolCall.id, await prepareDirectCall(this.admissionHost(), toolCall));
+                const call = await prepareDirectCall(this.admissionHost(), toolCall);
+                calls.set(toolCall.id, call);
+                const escalation = await this.escalationOf(call);
+                if (escalation)
+                    escalations.set(toolCall.id, escalation);
+                else
+                    escalations.delete(toolCall.id);
             }
         }
-        return this.publishPreparedBatch(calls);
+        return this.publishPreparedBatch(calls, escalations);
     }
-    publishPreparedBatch(calls) {
+    publishPreparedBatch(calls, escalations) {
         const reviewCalls = [...calls.values()]
             .filter((call) => call.kind !== 'synthetic')
-            .map((call) => ({
-            id: call.toolCall.id,
-            name: call.toolName,
-            input: call.input,
-        }));
+            .map((call) => {
+            const escalation = escalations.get(call.toolCall.id);
+            return {
+                id: call.toolCall.id,
+                name: call.toolName,
+                input: call.input,
+                ...(escalation ? { escalation } : {}),
+            };
+        });
         const batch = Object.freeze({
             reviewCalls: Object.freeze(reviewCalls),
             calls: new Map(calls),
+            escalations: new Map(escalations),
         });
         this.preparedBatches.add(batch);
         return batch;
@@ -467,7 +527,7 @@ export class ToolExecutor {
     }
     async runBatch(toolCalls, denials, prior, preparedBatch) {
         this.log.debug('Executing tool batch', {
-            [NAMZU.RUN_ID]: this.config.runId,
+            [NAMZU.TURN_ID]: this.config.turnId,
             'namzu.runtime.tool_count': toolCalls.length,
             'namzu.runtime.denied_count': denials?.size ?? 0,
             'namzu.runtime.recovered_count': prior?.size ?? 0,
@@ -482,12 +542,12 @@ export class ToolExecutor {
         };
         const baseContext = this.buildToolContext(recordObservation);
         // A model response is the ownership boundary for concurrent siblings.
-        // Scope the first call id to its durable run: custom providers are not
+        // Scope the first call id to its durable turn: custom providers are not
         // required to make call ids globally unique, so the raw id alone could
-        // collide with a later run retained by a host-side activity monitor.
+        // collide with a later turn retained by a host-side activity monitor.
         const firstToolUseId = toolCalls[0]?.id;
         const toolBatchId = firstToolUseId
-            ? JSON.stringify([String(baseContext.runId), firstToolUseId])
+            ? JSON.stringify([String(baseContext.turnId), firstToolUseId])
             : undefined;
         // Respect each tool's `concurrencySafe` flag. Read-only tools
         // (ls/grep/glob/…) run in parallel; tools that mutate shared state
@@ -560,14 +620,22 @@ export class ToolExecutor {
             // side by side needs to know whose progress this is.
             const progress = new ToolProgressPublisher(this.emitEvent, {
                 type: 'tool_progress',
-                runId: this.config.runId,
+                turnId: this.config.turnId,
                 toolUseId: toolCall.id,
                 toolName: toolCall.function.name,
             });
+            // Reached only by a call that was not denied, and a call carrying an
+            // escalation cannot skip review (`runToolReview` routes it to a
+            // decision, and refuses an escape the decision did not confirm), so
+            // this grants what a reviewer approved for THIS call and nothing
+            // more. A batch executed without a preparation carries none.
+            const escalation = preparedBatch?.escalations.get(toolCall.id);
             const ctx = {
                 ...baseContext,
                 toolUseId: toolCall.id,
                 ...(toolBatchId ? { toolBatchId } : {}),
+                ...(escalation?.outsidePaths ? { approvedPaths: escalation.outsidePaths } : {}),
+                ...(escalation?.sandboxEscape ? { sandboxEscapeApproved: true } : {}),
                 source: { kind: 'direct' },
                 // Overridden per call, so a nested dispatch can name the call
                 // that made it. The base context has no `toolUseId`, and a
@@ -626,7 +694,7 @@ export class ToolExecutor {
             };
             await this.emitEvent({
                 type: 'tool_completed',
-                runId: this.config.runId,
+                turnId: this.config.turnId,
                 toolUseId: toolCall.id,
                 toolName,
                 result: message,
@@ -644,7 +712,7 @@ export class ToolExecutor {
      * Run a tool on behalf of another tool, and put it on the record.
      *
      * These used to go straight to `registry.execute`, so they reached the
-     * permission gate and reached the event stream not at all — a run whose
+     * permission gate and reached the event stream not at all — a turn whose
      * transcript showed one `run_code` call and nothing about the eleven
      * writes it performed is a transcript nobody can audit.
      *
@@ -697,14 +765,14 @@ export class ToolExecutor {
             : { kind: 'direct' };
         const progress = new ToolProgressPublisher(this.emitEvent, {
             type: 'tool_progress',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: nestedId,
             toolName: name,
         });
         if (preparedCall.kind === 'synthetic') {
             await this.emitEvent({
                 type: 'tool_executing',
-                runId: this.config.runId,
+                turnId: this.config.turnId,
                 toolUseId: nestedId,
                 toolName: name,
                 input: preparedInput,
@@ -713,7 +781,7 @@ export class ToolExecutor {
             await progress.close();
             await this.emitEvent({
                 type: 'tool_completed',
-                runId: this.config.runId,
+                turnId: this.config.turnId,
                 toolUseId: nestedId,
                 toolName: name,
                 result: preparedCall.message,
@@ -737,7 +805,7 @@ export class ToolExecutor {
                 : `Blocked by the authorization gate: this nested call requires an explicit allow rule because an operator review cannot be opened from inside another tool. ${gateResult.reason}`;
             const output = deniedToolOutput(name, reason);
             // Same fail-closed durability rule as a direct gate denial: if the
-            // configured run store cannot record the refusal, do not quietly carry
+            // configured session log cannot record the refusal, do not quietly carry
             // on with an unaudited execution.
             if (!this.config.recordAudit) {
                 throw new Error(`Nested tool "${name}" was refused, but no durable audit recorder is configured.`);
@@ -750,7 +818,7 @@ export class ToolExecutor {
             await progress.close();
             await this.emitEvent({
                 type: 'tool_executing',
-                runId: this.config.runId,
+                turnId: this.config.turnId,
                 toolUseId: nestedId,
                 toolName: name,
                 input: preparedInput,
@@ -758,7 +826,7 @@ export class ToolExecutor {
             });
             await this.emitEvent({
                 type: 'tool_completed',
-                runId: this.config.runId,
+                turnId: this.config.turnId,
                 toolUseId: nestedId,
                 toolName: name,
                 result: output,
@@ -769,8 +837,13 @@ export class ToolExecutor {
             });
             return { success: false, output: '', error: reason };
         }
-        const { toolBatchId: directBatch, ...contextWithoutDirectBatch } = context;
+        // A review approved the PARENT's escalation, as the parent's input
+        // showed it. A nested call is a different call nobody reviewed, so it
+        // inherits neither the parent's approved paths nor its sandbox escape.
+        const { toolBatchId: directBatch, approvedPaths: parentPaths, sandboxEscapeApproved: parentEscape, ...contextWithoutDirectBatch } = context;
         void directBatch;
+        void parentPaths;
+        void parentEscape;
         const childContext = {
             ...contextWithoutDirectBatch,
             abortSignal: signal,
@@ -787,7 +860,7 @@ export class ToolExecutor {
         };
         await this.emitEvent({
             type: 'tool_executing',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: nestedId,
             toolName: name,
             input: preparedInput,
@@ -795,12 +868,13 @@ export class ToolExecutor {
         });
         const vetoOutcome = this.probes.queryVeto({
             type: 'tool_executing',
-            runId: this.config.runId,
+            sessionId: this.config.sessionId,
+            turnId: this.config.turnId,
             toolUseId: nestedId,
             toolName: name,
             input: preparedInput,
             ...(via ? { via } : {}),
-        }, buildProbeContext({ runId: this.config.runId }));
+        }, buildProbeContext({ sessionId: this.config.sessionId, turnId: this.config.turnId }));
         if (vetoOutcome.action === 'deny') {
             const probeName = vetoOutcome.probeName ?? 'unnamed';
             const reason = vetoOutcome.reason ?? 'no reason provided';
@@ -808,7 +882,7 @@ export class ToolExecutor {
             await progress.close();
             await this.emitEvent({
                 type: 'tool_completed',
-                runId: this.config.runId,
+                turnId: this.config.turnId,
                 toolUseId: nestedId,
                 toolName: name,
                 result: `Error: ${message}`,
@@ -840,7 +914,7 @@ export class ToolExecutor {
             retainedPreviewChars: this.config.retainedToolPreviewChars,
             spillDir: this.outputDirectory(),
             onError: (message) => this.log.warn('Failed to spill oversized nested tool output', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: name,
                 'exception.message': message,
             }),
@@ -857,7 +931,7 @@ export class ToolExecutor {
             };
         await this.emitEvent({
             type: 'tool_completed',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: nestedId,
             toolName: name,
             result: budgeted.output,
@@ -871,7 +945,8 @@ export class ToolExecutor {
             ...(via ? { via } : {}),
         });
         recordObservation({
-            runId: this.config.runId,
+            sessionId: this.config.sessionId,
+            turnId: this.config.turnId,
             toolUseId: nestedId,
             toolName: name,
             input: preparedInput,
@@ -899,7 +974,8 @@ export class ToolExecutor {
     }
     buildToolContext(recordObservation = () => { }) {
         const context = {
-            runId: this.config.runId,
+            sessionId: this.config.sessionId,
+            turnId: this.config.turnId,
             workingDirectory: this.config.workingDirectory,
             ...(this.config.additionalDirectories?.length
                 ? { additionalDirectories: this.config.additionalDirectories }
@@ -909,13 +985,14 @@ export class ToolExecutor {
             log: (level, message) => this.log[level](message),
             permissionContext: {
                 mode: this.batchMode ?? this.resolvePermissionMode(),
-                runId: this.config.runId,
+                sessionId: this.config.sessionId,
+                turnId: this.config.turnId,
                 workingDirectory: this.config.workingDirectory,
             },
             invocationState: this.config.invocationState,
-            captureRunEvidence: this.config.captureRunEvidence,
+            captureSessionEvidence: this.config.captureSessionEvidence,
             toolRegistry: this.config.tools,
-            // The step's list wins where it has one; the run's is the default.
+            // The step's list wins where it has one; the turn's is the default.
             // Same precedence the request already uses when it decides which
             // schemas to send, so the menu and the kitchen agree.
             allowedTools: this.effectiveAllowedTools(),
@@ -925,10 +1002,10 @@ export class ToolExecutor {
                 this.skillScope = { ...scope, adoptedInBatch: this.batchCounter };
             },
             maxToolOutputChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
-            // The run's screens, defaulted HERE rather than on the registry: a
+            // The turn's screens, defaulted HERE rather than on the registry: a
             // host builds the registry and hands it over, so a registry-side
             // default is the host's to write and the shipped one reaches
-            // nobody. `[]` survives the `??` and is how a run says "none".
+            // nobody. `[]` survives the `??` and is how a turn says "none".
             toolResultGuardrails: this.config.toolResultGuardrails ?? DEFAULT_TOOL_RESULT_GUARDRAILS,
             ...(this.config.skills ? { skills: this.config.skills } : {}),
             ...(this.config.web ? { web: this.config.web } : {}),
@@ -943,9 +1020,9 @@ export class ToolExecutor {
             dispatchTool: (name, input, options) => this.dispatchNested(name, input, context, recordObservation, undefined, options),
             sandbox: this.config.sandbox,
             fileReadTracker: this.fileReadTracker,
-            // Bound to this run, once. Binding here rather than passing the
+            // Bound to this turn, once. Binding here rather than passing the
             // owner from the tool is what makes the scoping structural: there
-            // is no argument a tool could pass to reach another run's jobs.
+            // is no argument a tool could pass to reach another turn's jobs.
             //
             // The registry's process substrate is the HOST. It must not coexist
             // with a Sandbox in one tool context: handing both to every tool lets
@@ -960,7 +1037,7 @@ export class ToolExecutor {
             ...(this.config.backgroundJobs &&
                 (!this.config.sandbox || this.config.sandbox.spawnDetached !== undefined)
                 ? {
-                    backgroundJobs: bindOwner(this.config.backgroundJobs, this.config.backgroundJobOwner ?? this.config.runId, {
+                    backgroundJobs: bindOwner(this.config.backgroundJobs, this.config.backgroundJobOwner ?? this.config.turnId, {
                         workingDirectory: this.config.workingDirectory,
                         env: this.config.env,
                         ...(this.config.sandbox?.spawnDetached
@@ -1006,14 +1083,14 @@ export class ToolExecutor {
                 const message = truncatedToolInputMessage(toolName);
                 await this.emitEvent({
                     type: 'tool_executing',
-                    runId: this.config.runId,
+                    turnId: this.config.turnId,
                     toolUseId: toolCall.id,
                     toolName,
                     input: {},
                 });
                 await this.emitEvent({
                     type: 'tool_completed',
-                    runId: this.config.runId,
+                    turnId: this.config.turnId,
                     toolUseId: toolCall.id,
                     toolName,
                     result: message,
@@ -1050,14 +1127,14 @@ export class ToolExecutor {
                 const message = resolved.message;
                 await this.emitEvent({
                     type: 'tool_executing',
-                    runId: this.config.runId,
+                    turnId: this.config.turnId,
                     toolUseId: toolCall.id,
                     toolName,
                     input: {},
                 });
                 await this.emitEvent({
                     type: 'tool_completed',
-                    runId: this.config.runId,
+                    turnId: this.config.turnId,
                     toolUseId: toolCall.id,
                     toolName,
                     result: message,
@@ -1099,24 +1176,25 @@ export class ToolExecutor {
         }
         await this.emitEvent({
             type: 'tool_executing',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: toolCall.id,
             toolName,
             input,
         });
         const vetoOutcome = this.probes.queryVeto({
             type: 'tool_executing',
-            runId: this.config.runId,
+            sessionId: this.config.sessionId,
+            turnId: this.config.turnId,
             toolUseId: toolCall.id,
             toolName,
             input,
-        }, buildProbeContext({ runId: this.config.runId }));
+        }, buildProbeContext({ sessionId: this.config.sessionId, turnId: this.config.turnId }));
         if (vetoOutcome.action === 'deny') {
             const probeName = vetoOutcome.probeName ?? 'unnamed';
             const reason = vetoOutcome.reason ?? 'no reason provided';
             const veto = new ProbeVetoError(probeName, reason, 'tool_executing');
             this.log.warn('Tool call denied by probe', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'namzu.runtime.probe_name': probeName,
                 'namzu.runtime.reason': reason,
@@ -1128,7 +1206,7 @@ export class ToolExecutor {
             // Emit the terminal event with isError so UI cards finalize.
             await this.emitEvent({
                 type: 'tool_completed',
-                runId: this.config.runId,
+                turnId: this.config.turnId,
                 toolUseId: toolCall.id,
                 toolName,
                 result: `Error: ${veto.message}`,
@@ -1148,7 +1226,7 @@ export class ToolExecutor {
                 // model read a SUCCESSFUL result whose body begins "Error: …"
                 // and the failure-recovery path it was trained on never
                 // fired. The persisted step recorded a literal
-                // `isError: false`, so the run record contradicted its own
+                // `isError: false`, so the turn record contradicted its own
                 // event stream. And compaction's guard against clearing error
                 // results silently excluded vetoed ones.
                 isError: true,
@@ -1159,7 +1237,7 @@ export class ToolExecutor {
         }
         const startMs = Date.now();
         // an unhandled throw from `tools.execute(...)` used to
-        // propagate up to `result.ts` as `run_failed` without emitting a
+        // propagate up to `result.ts` as `turn_failed` without emitting a
         // terminal `tool_completed`, leaving UI cards stuck in `executing`.
         // Wrap so any throw materialises as an error result.
         // Typed as the full ToolResult, not a narrowed literal: the narrow
@@ -1215,7 +1293,7 @@ export class ToolExecutor {
             // the first retry draws from `[0, initialDelayMs]`.
             const delayMs = backoffWithJitter(attempt - 1, backoff);
             this.log.info('Retrying a failed tool call', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'namzu.retry.attempt': attempt,
                 'namzu.runtime.budget': budget,
@@ -1290,7 +1368,7 @@ export class ToolExecutor {
             retainedPreviewChars: this.config.retainedToolPreviewChars,
             spillDir: this.outputDirectory(),
             onError: (message) => this.log.warn('Failed to retain original tool output', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'exception.message': message,
             }),
@@ -1299,7 +1377,7 @@ export class ToolExecutor {
             maxToolOutputChars > 0 &&
             budgeted.originalLength > maxToolOutputChars) {
             this.log.warn('Tool output exceeded the model-visible budget', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'namzu.runtime.original_length': budgeted.originalLength,
                 'namzu.runtime.spill_path': budgeted.spillPath,
@@ -1322,7 +1400,7 @@ export class ToolExecutor {
         }
         if (result.success) {
             this.log.debug('Tool executed successfully', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'namzu.duration_ms': durationMs,
                 'namzu.runtime.output_length': output.length,
@@ -1330,7 +1408,7 @@ export class ToolExecutor {
         }
         else {
             this.log.warn('Tool execution failed', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'namzu.duration_ms': durationMs,
                 'exception.message': postOverride ? output : (result.error ?? 'unknown'),
@@ -1351,7 +1429,7 @@ export class ToolExecutor {
         await settleProgress();
         await this.emitEvent({
             type: 'tool_completed',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: toolCall.id,
             toolName,
             result: output,
@@ -1368,7 +1446,8 @@ export class ToolExecutor {
             ...(budgeted.spillIntegrity ? { outputSpillIntegrity: budgeted.spillIntegrity } : {}),
         });
         recordObservation({
-            runId: this.config.runId,
+            sessionId: this.config.sessionId,
+            turnId: this.config.turnId,
             toolUseId: toolCall.id,
             toolName,
             input,
@@ -1392,7 +1471,7 @@ export class ToolExecutor {
         };
     }
     /**
-     * Run a tool under a deadline, with the run abort folded in.
+     * Run a tool under a deadline, with the turn abort folded in.
      *
      * `ToolContext.abortSignal` existed but was produced and consumed by
      * nothing: a Stop tore down the model stream and then parked inside
@@ -1409,7 +1488,7 @@ export class ToolExecutor {
      *
      * A timeout is reported as a normal failed result, not a throw: the
      * model sees "this timed out" as a `tool_result` and can route around
-     * it. A throw would end the run over one slow tool.
+     * it. A throw would end the turn over one slow tool.
      */
     async executeWithDeadline(toolName, input, toolContext, prepared) {
         const timeoutMs = this.config.tools.get(toolName)?.timeoutMs ??
@@ -1475,7 +1554,7 @@ export class ToolExecutor {
                         : `Tool "${toolName}" was cancelled.`,
                 };
             }
-            const inheritedCapture = toolContext.captureRunEvidence;
+            const inheritedCapture = toolContext.captureSessionEvidence;
             const scopedCapture = inheritedCapture
                 ? async (maxReadBytes, signal) => {
                     const combined = signal
@@ -1488,7 +1567,7 @@ export class ToolExecutor {
             const context = {
                 ...toolContext,
                 abortSignal: controller.signal,
-                ...(scopedCapture ? { captureRunEvidence: scopedCapture } : {}),
+                ...(scopedCapture ? { captureSessionEvidence: scopedCapture } : {}),
                 ...(scopedDispatch ? { dispatchTool: scopedDispatch } : {}),
             };
             const execution = prepared
@@ -1500,7 +1579,7 @@ export class ToolExecutor {
             const outcome = await Promise.race(expired ? [execution, expired, aborted] : [execution, aborted]);
             if (outcome === 'timeout') {
                 this.log.warn('Tool timed out', {
-                    [NAMZU.RUN_ID]: this.config.runId,
+                    [NAMZU.TURN_ID]: this.config.turnId,
                     [GENAI.TOOL_NAME]: toolName,
                     'namzu.runtime.timeout_ms': timeoutMs,
                 });
@@ -1558,7 +1637,7 @@ export class ToolExecutor {
      * `setSandbox()` now finishes against the config it STARTED with rather
      * than against the new one. Distinguishing the two readings needs
      * `setSandbox` to be called from a hook awaited in the middle of one
-     * admission — its only call site is the run's sandbox acquisition,
+     * admission — its only call site is the turn's sandbox acquisition,
      * before the loop, so nothing in this tree can tell them apart.
      */
     admissionHost() {
@@ -1638,7 +1717,7 @@ export class ToolExecutor {
      * One execution attempt, with a throw materialized as an error result.
      *
      * an unhandled throw from `tools.execute(...)` used to
-     * propagate up to `result.ts` as `run_failed` without emitting a
+     * propagate up to `result.ts` as `turn_failed` without emitting a
      * terminal `tool_completed`, leaving UI cards stuck in `executing`.
      *
      * The return is the full `ToolResult`, not a narrowed literal: the
@@ -1653,7 +1732,7 @@ export class ToolExecutor {
         catch (err) {
             const message = toErrorMessage(err);
             this.log.warn('Tool execution threw', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'exception.message': message,
             });
@@ -1670,7 +1749,8 @@ export class ToolExecutor {
         let results;
         try {
             results = await this.config.pluginManager.executeHooks('post_tool_use', {
-                runId: this.config.runId,
+                sessionId: this.config.sessionId,
+                turnId: this.config.turnId,
                 toolName,
                 toolInput: input,
                 toolResult,
@@ -1751,7 +1831,7 @@ export class ToolExecutor {
         }
         const output = deniedToolOutput(toolName, reason);
         this.log.info('Tool call denied — synthesizing tool_result', {
-            [NAMZU.RUN_ID]: this.config.runId,
+            [NAMZU.TURN_ID]: this.config.turnId,
             [GENAI.TOOL_NAME]: toolName,
             'namzu.runtime.tool_use_id': toolCall.id,
             'namzu.runtime.reason': reason,
@@ -1769,14 +1849,14 @@ export class ToolExecutor {
         }
         await this.emitEvent({
             type: 'tool_executing',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: toolCall.id,
             toolName,
             input,
         });
         await this.emitEvent({
             type: 'tool_completed',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: toolCall.id,
             toolName,
             result: output,
@@ -1788,7 +1868,7 @@ export class ToolExecutor {
         const reason = abortReasonText(this.config.abortSignal.reason);
         return this.recordSyntheticHookOutcome(toolCallId, toolName, input, {
             kind: 'error',
-            output: `Tool "${toolName}" was not started because the run was cancelled${reason ? `: ${reason}` : '.'}`,
+            output: `Tool "${toolName}" was not started because the turn was cancelled${reason ? `: ${reason}` : '.'}`,
         });
     }
     async recordSyntheticHookOutcome(toolCallId, toolName, input, outcome) {
@@ -1810,14 +1890,14 @@ export class ToolExecutor {
         }
         await this.emitEvent({
             type: 'tool_executing',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: toolCallId,
             toolName,
             input,
         });
         await this.emitEvent({
             type: 'tool_completed',
-            runId: this.config.runId,
+            turnId: this.config.turnId,
             toolUseId: toolCallId,
             toolName,
             result: outcome.output,
@@ -1849,11 +1929,11 @@ export class ToolExecutor {
             ? content
             : content.flatMap((block) => (block.type === 'text' ? [block.text] : [])).join('\n');
         const notice = richWithheld
-            ? `[rich content withheld: ${size} base64 chars exceeds this run's ${cap} cap] ${describeDroppedContent(content) ?? ''}`
+            ? `[rich content withheld: ${size} base64 chars exceeds this turn's ${cap} cap] ${describeDroppedContent(content) ?? ''}`
             : undefined;
         if (richWithheld) {
             this.log.warn('Tool result content exceeded the rich-content budget', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'namzu.runtime.content_bytes': size,
                 'namzu.runtime.cap': cap,
@@ -1873,14 +1953,14 @@ export class ToolExecutor {
                     ? join(this.outputDirectory(), 'content')
                     : undefined,
                 onError: (message) => this.log.warn('Failed to spill oversized model tool content', {
-                    [NAMZU.RUN_ID]: this.config.runId,
+                    [NAMZU.TURN_ID]: this.config.turnId,
                     [GENAI.TOOL_NAME]: toolName,
                     'exception.message': message,
                 }),
             });
         if (budgeted.truncated && budgeted !== host.budgeted) {
             this.log.warn('Model tool text exceeded the model-visible budget', {
-                [NAMZU.RUN_ID]: this.config.runId,
+                [NAMZU.TURN_ID]: this.config.turnId,
                 [GENAI.TOOL_NAME]: toolName,
                 'namzu.runtime.original_length': budgeted.originalLength,
                 'namzu.runtime.spill_path': budgeted.spillPath,