@crewhaus/runtime-core 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -5,11 +5,11 @@ import { createAbortTree } from "@crewhaus/abort-controller";
5
5
  import { EFFORT_THINKING_BUDGET_TOKENS, collectFinalMessage, consumeStream, } from "@crewhaus/adapter-anthropic";
6
6
  import { classifyBoundary, setDefaultBoundaryLlmClassifier } from "@crewhaus/boundary-classifier";
7
7
  import { wrap as wrapWithCircuitBreaker } from "@crewhaus/circuit-breaker";
8
- import { autoCompact } from "@crewhaus/compaction-autocompact";
8
+ import { autoCompact, planCompaction } from "@crewhaus/compaction-autocompact";
9
9
  import { DEFAULT_DEDUPE_THRESHOLD, curate as curateItems, } from "@crewhaus/compaction-curator";
10
10
  import { snip } from "@crewhaus/compaction-snip";
11
- import { DEFAULT_CAPABILITIES, DEFAULT_PRICING, computeCostMicros, createCostTracker, resolveCapabilities, resolvePricing, sumRoleCost, } from "@crewhaus/cost-tracker";
12
- import { classifyEgress, summarizeEgress, } from "@crewhaus/egress-classifier";
11
+ import { DEFAULT_CAPABILITIES, DEFAULT_PRICING, computeCostMicros, createCostTracker, providerToolLimit, resolveCapabilities, resolvePricing, sumRoleCost, } from "@crewhaus/cost-tracker";
12
+ import { MIN_MATCH_LENGTH, classifyEgress, summarizeEgress, } from "@crewhaus/egress-classifier";
13
13
  import { ConfigError, EXIT_CODES, RunFailedError, RuntimeError, isRunFailedError, } from "@crewhaus/errors";
14
14
  import { DEFAULT_ROOT_DIR, openEventLog } from "@crewhaus/event-log";
15
15
  import { aggregateDecisions, runHooks } from "@crewhaus/hooks-engine";
@@ -18,6 +18,7 @@ import { createFailoverChain, createPolicyRouter, createTierRouter, parseModelSt
18
18
  import { BUILTIN_DEFAULT_RULES, emptyRuleSet, evaluateJustification, evaluateWithReason, loadSettingsRules, ruleBasedJustificationJudge, } from "@crewhaus/permission-engine";
19
19
  import { manage as manageCacheMarkers } from "@crewhaus/prompt-cache-manager";
20
20
  import { buildRedactionNotice, classifyText, llmClassifierEnabled, } from "@crewhaus/prompt-injection-detector";
21
+ import { claimReasons, isProvabilityLevel, summarizeBundle, unverifiedBundle, } from "@crewhaus/provability";
21
22
  import { createRateLimiter } from "@crewhaus/rate-limiter";
22
23
  import { BUILTIN_FAILURE_CLASSES, advanceState, initialRecoveryState, recover, } from "@crewhaus/recovery-engine";
23
24
  import { SHADOW_LANE_PRIMARY_ARM, SHADOW_LANE_SHADOW_ARM, computeReward, freezeScoreboard, openScoreboard, readRouteFreeze, readRoutingPriorsRaw, routingPriorsPath, shadowLaneQuality, shadowRouteKey, } from "@crewhaus/routing-store";
@@ -30,8 +31,9 @@ import { executeStreaming } from "@crewhaus/streaming-tool-executor";
30
31
  import { narrowRuleSet } from "@crewhaus/sub-agent-permission-inheritance";
31
32
  import { currentTenantContext } from "@crewhaus/tenancy";
32
33
  import { TokenBudget, estimateTokens } from "@crewhaus/token-budget";
33
- import { stripJustificationField, withJustificationField } from "@crewhaus/tool-catalog";
34
- import { executeTool } from "@crewhaus/tool-executor";
34
+ import { hasModelChosenDestination, legacyMcpToolName, stripJustificationField, withJustificationField, } from "@crewhaus/tool-catalog";
35
+ import { LOOP_TOOL_NAMES, resolveToolConfigEnv } from "@crewhaus/tool-categories";
36
+ import { executeTool, operativeValuesFor, preparePermissionSubject } from "@crewhaus/tool-executor";
35
37
  import { detectLoop } from "@crewhaus/tool-loop-detection";
36
38
  import { partitionToolCalls } from "@crewhaus/tool-orchestrator";
37
39
  import { storeAndPreview } from "@crewhaus/tool-result-store";
@@ -41,13 +43,18 @@ import { zodToJsonSchema } from "zod-to-json-schema";
41
43
  import { createCliMarkdownRenderer, isCliMarkdownEnabled, } from "./cli-markdown";
42
44
  import { createMemoryEventLog, createMemorySessionStore } from "./ephemeral";
43
45
  import { FEEDBACK_EVENT_KIND, runExitRating } from "./exit-rating";
46
+ import { flattenUnionToObject } from "./flatten-union";
47
+ import { createFooterLineGuard, neutralizeFooterLines } from "./forged-footer";
44
48
  import { attachIncidentCollector } from "./incident-collector";
45
49
  import { LIST_TOOLS_NAME, buildListToolsTool } from "./list-tools";
46
50
  import { createSpanUnionTracker, modelLatencyMs } from "./model-latency";
47
51
  import { attachAdvisorPersistence, attachDefaultSubscribers, attachMcpStatsPersistence, attachRoutingPersistence, attachWatchmeCapture, } from "./observability";
52
+ import { placeRecordingCanonicalizer } from "./path-canonical";
48
53
  import { describeHintEvidence, isSyntheticMessage, latestHumanUserMessage, markSynthetic, messageText, preRoute, stripDirectiveFromMessage, } from "./pre-route";
49
54
  import { loadProjectMemory } from "./project-memory";
50
55
  import { createCliOutput, isSpinnerEnabled } from "./spinner";
56
+ import { runtimeStateRoots } from "./state-roots";
57
+ import { checkServingToolLimits, unreportedToolLimitLines, } from "./tool-limit";
51
58
  /**
52
59
  * Slice-scope runtime: a multi-turn streaming chat loop with prompt
53
60
  * caching, tool execution, pre-turn context compaction, recovery taxonomy,
@@ -75,8 +82,9 @@ import { createCliOutput, isSpinnerEnabled } from "./spinner";
75
82
  * hit, a synthetic warning user message is appended (deduped per
76
83
  * signature) so the model can self-correct. Every tool result flows
77
84
  * through `@crewhaus/tool-result-store` — outputs over 10 KB are
78
- * persisted to `.crewhaus/tool-results/<runId>/<toolUseId>.txt` and the
79
- * model sees a preview pointing at the full file. Behind a
85
+ * persisted to `.crewhaus/tool-results/<runId>/<toolUseId>.txt` (or
86
+ * `<toolUseId>.<n>.txt` when an id-less provider's synthesised id repeats)
87
+ * and the model sees a preview pointing at the full file. Behind a
80
88
  * `streaming: true` option, the loop swaps to
81
89
  * `@crewhaus/streaming-tool-executor`, which dispatches tools mid-stream
82
90
  * via the SDK's `contentBlock` event.
@@ -179,37 +187,6 @@ function toAdvertisedTool(t) {
179
187
  justificationInjected: injected,
180
188
  };
181
189
  }
182
- // Merge a top-level union of object branches into a single object schema.
183
- // Anthropic forbids a top-level `anyOf`, but a nested `anyOf` on an individual
184
- // property is fine — so each property becomes the union of its per-branch
185
- // shapes, and `required` is the intersection across branches (in practice the
186
- // shared discriminator). The tool's own zod schema still validates the real
187
- // input at execute time, so the looser model-facing schema loses no safety.
188
- function flattenUnionToObject(branches, baseProps) {
189
- const perKey = new Map();
190
- const requiredSets = [];
191
- for (const b of branches) {
192
- for (const [k, v] of Object.entries(b.properties ?? {})) {
193
- const seen = perKey.get(k) ?? [];
194
- if (!seen.some((e) => JSON.stringify(e) === JSON.stringify(v)))
195
- seen.push(v);
196
- perKey.set(k, seen);
197
- }
198
- requiredSets.push(Array.isArray(b.required) ? b.required : []);
199
- }
200
- const properties = { ...(baseProps ?? {}) };
201
- for (const [k, variants] of perKey) {
202
- properties[k] = variants.length === 1 ? variants[0] : { anyOf: variants };
203
- }
204
- const required = requiredSets.length > 0
205
- ? requiredSets.reduce((acc, r) => acc.filter((x) => r.includes(x)))
206
- : [];
207
- return {
208
- type: "object",
209
- properties,
210
- ...(required.length > 0 ? { required } : {}),
211
- };
212
- }
213
190
  // ---------------------------------------------------------------------------
214
191
  // v0.3.0 Goal 1 — the continuity seam (§2.3 requirements ledger, §2.5 mutable
215
192
  // tail region). All injected closures: runtime-core stays store-free; the
@@ -424,6 +401,7 @@ export { createEdgeAnthropicAdapter, classifyEdgeTool, EDGE_SAFE_TOOLS, HOST_ONL
424
401
  // own module (`./janitor`) but is re-exported here because emitted bundles
425
402
  // only import the package root.
426
403
  export { createJanitor } from "./janitor";
404
+ export { GATE_RESOLVE_SINK_ID, lineageEgressScreen, } from "./lineage-screen";
427
405
  export { JANITOR_BUILTIN_STEPS } from "./janitor";
428
406
  // Loop contract 0.4 (Batch C, item 4) — agent identity generation. Lives in
429
407
  // its own module (`./identity`) but is re-exported here because emitted
@@ -489,8 +467,11 @@ export async function findReplayableGrant(store, where) {
489
467
  }
490
468
  const now = where.now ?? Date.now();
491
469
  const maxAgeMs = where.maxAgeMs ?? REPLAYABLE_GRANT_MAX_AGE_MS;
470
+ // 0.7.1 — a grant made before MCP tools were renamed names the tool by its
471
+ // old `<server>__<tool>` spelling; it is the same tool.
472
+ const legacyToolName = legacyMcpToolName(where.toolName);
492
473
  const matches = all.filter((a) => {
493
- if (a.toolName !== where.toolName)
474
+ if (a.toolName !== where.toolName && a.toolName !== legacyToolName)
494
475
  return false;
495
476
  if (a.sessionId !== where.sessionId)
496
477
  return false;
@@ -525,6 +506,99 @@ export async function findReplayableGrant(store, where) {
525
506
  // trust the ordering of a store a caller injected.
526
507
  return [...matches].sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))[0];
527
508
  }
509
+ /**
510
+ * 0.7.1 — does the decision on `record` cover a call that now lands at
511
+ * `call`?
512
+ *
513
+ * An operator approves a call where it acts. The record is keyed on the
514
+ * input, and the same input can be made to act somewhere else: retarget a
515
+ * symlinked directory between park and resume — any allowed call in the
516
+ * resumed turn can — and a grant for `pub/link/x.md` would write wherever
517
+ * the link now points, a place the operator never saw and one an
518
+ * `alwaysAsk` rule may name. So the record carries the places the gate
519
+ * found when it parked, and decides the call only while it lands there.
520
+ *
521
+ * A record written before approvals were bound (no `places`: 0.7.0, or an
522
+ * earlier 0.7.1 build) showed its approver only the input as written, so
523
+ * the one place it can be said to cover is the one that input names on its
524
+ * face. It decides the call when every path lands exactly there — no
525
+ * symlink followed, nothing elsewhere — and otherwise the call is asked
526
+ * again: never run somewhere the approver could not have seen. A record
527
+ * whose `places` is not the shape written here (a foreign or hand-edited
528
+ * line) covers nothing.
529
+ *
530
+ * Binding is about where a call RUNS, so the gate asks this of a grant or a
531
+ * park it would re-use; a deny refuses the call wherever it lands.
532
+ */
533
+ export function landsWhereApproved(record, call) {
534
+ const recorded = record.places;
535
+ if (recorded === undefined)
536
+ return call.allAsWritten();
537
+ if (!Array.isArray(recorded))
538
+ return false;
539
+ const fresh = call.places();
540
+ if (recorded.length !== fresh.length)
541
+ return false;
542
+ return fresh.every((now, i) => {
543
+ const then = recorded[i];
544
+ if (typeof then !== "object" || then === null)
545
+ return false;
546
+ const { path: thenPath, at: thenAt } = then;
547
+ return (thenPath === now.path &&
548
+ Array.isArray(thenAt) &&
549
+ thenAt.length === now.at.length &&
550
+ now.at.every((place, j) => thenAt[j] === place));
551
+ });
552
+ }
553
+ /**
554
+ * 0.7.1 — the newest record for this call that was made where it now lands:
555
+ * same tool and input (`keys`), not yet spent, and covering its places. The
556
+ * store's `get` hands back only the newest record for the input; when that
557
+ * one was made for another place, an older one may still be this place's —
558
+ * a grant the operator made before a link moved away and back, or a park
559
+ * already waiting. `list` is optional on an injected store; without it (or
560
+ * when it fails) there is nothing more to find, and the call parks.
561
+ */
562
+ async function findApprovalForPlace(store, keys, call) {
563
+ if (typeof store.list !== "function")
564
+ return null;
565
+ let all;
566
+ try {
567
+ all = await store.list();
568
+ }
569
+ catch {
570
+ return null;
571
+ }
572
+ // Newest-touched first, as `get` chooses.
573
+ const touched = (a) => {
574
+ const at = Date.parse(a.decidedAt ?? a.createdAt);
575
+ return Number.isFinite(at) ? at : 0;
576
+ };
577
+ const matches = all.filter((a) => keys.some(([toolName, inputHash]) => a.toolName === toolName && a.inputHash === inputHash) &&
578
+ a.consumedAt === undefined &&
579
+ landsWhereApproved(a, call));
580
+ return [...matches].sort((a, b) => touched(b) - touched(a))[0] ?? null;
581
+ }
582
+ /** What a park asked in place of `record` keeps of it, for the card. */
583
+ function supersededBy(record) {
584
+ return {
585
+ id: record.id,
586
+ ...(record.decision !== undefined ? { decision: record.decision } : {}),
587
+ ...(Array.isArray(record.places) ? { places: record.places } : {}),
588
+ };
589
+ }
590
+ /** Where a call lands, for an operator reading why it was asked again. */
591
+ function describePlaces(places) {
592
+ if (places === undefined)
593
+ return "the input as written";
594
+ if (!Array.isArray(places))
595
+ return "an unreadable record";
596
+ if (places.length === 0)
597
+ return "no path";
598
+ return places
599
+ .map((p) => `${p.path} -> ${Array.isArray(p.at) ? p.at.join(" and ") : "?"}`)
600
+ .join("; ");
601
+ }
528
602
  // Ops item 31 — alert watchdog seams re-exported so the CLI/codegen can build
529
603
  // the durable + off-box alert sink (audit append + settings.json alert hook /
530
604
  // webhook) it passes as `RunChatLoopOptions.alertSink`.
@@ -656,6 +730,31 @@ export async function replayMessageHistory(log) {
656
730
  // request. Drop such orphans so `--resume` self-heals. No-op on healthy logs.
657
731
  return sanitizeOrphanToolUses(messages).messages;
658
732
  }
733
+ /**
734
+ * 0.8.0 (design/0.8.0-provability-release.md §5.3) — how many turns a
735
+ * replayed transcript (`replayMessageHistory`) already holds: its user
736
+ * messages that opened one, the ones `runContext.turnNumber` counted when
737
+ * they ran. A runtime-injected message (a retry nudge, a cascade correction,
738
+ * a continue prompt — still marked synthetic after the replay) opens none,
739
+ * nor does the carrier of a batch of tool results; a directive-only input
740
+ * never reaches the replay (it ran no turn). Nested transcripts (a peer's, a
741
+ * sub-agent's) are already outside it.
742
+ */
743
+ function openedTurnCount(messages) {
744
+ let opened = 0;
745
+ for (const message of messages) {
746
+ if (message.role !== "user" || isSyntheticMessage(message))
747
+ continue;
748
+ const content = message.content;
749
+ if (typeof content !== "string" &&
750
+ content.length > 0 &&
751
+ content.every((block) => block.type === "tool_result")) {
752
+ continue;
753
+ }
754
+ opened += 1;
755
+ }
756
+ return opened;
757
+ }
659
758
  export async function attachRunEventSink(runContext, opts = {}) {
660
759
  const rootDir = resolveSessionRootDir(opts.sessionRootDir);
661
760
  const log = await openEventLog(runContext.sessionId, { rootDir });
@@ -689,16 +788,10 @@ export function resolveToolResultRoot() {
689
788
  return currentTenantContext()?.tenant.toolResultRoot;
690
789
  }
691
790
  /**
692
- * Sinks whose DESTINATION is chosen at runtime by the (prompt-injectable)
693
- * model — a fetched/navigated URL, an on-chain recipient — are effectively
694
- * dynamic even though they are spec-declared built-in tools: an attacker who
695
- * steers the model picks where the data goes. So non-user cross-origin content
696
- * reaching them must reach the egress BLOCK tier, not merely warn. Fixed-
697
- * destination sinks are intentionally NOT here: `SendMessage` replies to the
698
- * operator-configured channel, `WebSearch`/`ImageGenerate` hit a fixed provider
699
- * API — classifying those dynamic would block legitimate replies, so they stay
700
- * `"external-configured"` (warn) and can be tightened per-deployment via the
701
- * `resolveSinkScope` override or the spec's egress policy.
791
+ * The names that were model-destination sinks before tools could say so
792
+ * themselves. They stay dynamic whatever a tool of that name declares, so
793
+ * the declaration can only add sinks to the block tier, never take one out
794
+ * (see {@link defaultSinkScope}).
702
795
  */
703
796
  const MODEL_DESTINATION_SINKS = new Set([
704
797
  "Fetch",
@@ -707,19 +800,77 @@ const MODEL_DESTINATION_SINKS = new Set([
707
800
  "EvmSendTransaction",
708
801
  ]);
709
802
  /**
710
- * Default egress sink-scope. Runtime-joined MCP sinks (`mcp__*`) are the
711
- * canonical dynamically-discovered external sink, and the model-destination
712
- * built-ins above are dynamic by virtue of their model-chosen target — both
713
- * classify as `"external-dynamic"` so the egress block tier is reachable for
714
- * non-user-origin payloads (#144). Other spec-declared built-in sinks stay
715
- * `"external-configured"` (warn). Override via `runChatLoop({ resolveSinkScope })`
716
- * to mark federation-joined or other runtime sinks dynamic too.
803
+ * 0.7.1 — the tool-name fields of a `pre-tool` / `post-tool` hook payload.
804
+ * `name` is the registered name; an MCP tool also carries `legacyName`, the
805
+ * `<server>__<tool>` spelling it had before 0.7.1. A hook matcher accepts
806
+ * either spelling, but a script that reads `name` from its stdin and compares
807
+ * it cannot know about the rename, and a guard that stops matching is a
808
+ * guard that silently stops guarding — so it gets a stable field to compare.
809
+ */
810
+ function hookToolName(name) {
811
+ const legacyName = legacyMcpToolName(name);
812
+ return legacyName !== undefined ? { name, legacyName } : { name };
813
+ }
814
+ /**
815
+ * 0.7.1 — re-key a tool-name map (rate limits) written with the pre-0.7.1
816
+ * MCP spelling `<server>__<tool>` onto the registered `mcp__<server>__<tool>`
817
+ * name. A key that already names a tool, `"*"`, or an old spelling whose new
818
+ * name the map also carries is left alone. Returns the input by reference
819
+ * when nothing moved.
820
+ */
821
+ export function rekeyLegacyMcpToolKeys(map, toolNames) {
822
+ if (map === undefined)
823
+ return undefined;
824
+ const byLegacy = new Map();
825
+ for (const name of toolNames) {
826
+ const legacy = legacyMcpToolName(name);
827
+ if (legacy !== undefined)
828
+ byLegacy.set(legacy, name);
829
+ }
830
+ if (byLegacy.size === 0)
831
+ return map;
832
+ let moved = false;
833
+ const out = {};
834
+ for (const [key, value] of Object.entries(map)) {
835
+ const registered = key === "*" || toolNames.has(key) ? undefined : byLegacy.get(key);
836
+ if (registered !== undefined && !Object.hasOwn(map, registered)) {
837
+ out[registered] = value;
838
+ moved = true;
839
+ }
840
+ else {
841
+ out[key] = value;
842
+ }
843
+ }
844
+ return moved ? out : map;
845
+ }
846
+ /**
847
+ * Default egress sink-scope.
848
+ *
849
+ * A sink whose DESTINATION the (prompt-injectable) model chooses is dynamic
850
+ * even when the spec declares the tool: an attacker who steers the model
851
+ * picks where the data goes, so content from a non-user origin reaching it
852
+ * must reach the egress BLOCK tier, not merely warn (#144). Which tools those
853
+ * are is read from the tool itself: an external tool whose `operativeArgs`
854
+ * include a `url` or a `recipient` (`hasModelChosenDestination`) — Fetch,
855
+ * HttpRequest, HttpBatch, WebhookPost, EmailSend, OpenExternal, the RPC
856
+ * readers, … (permission-integration#5). Runtime-joined MCP sinks (`mcp__*`)
857
+ * are dynamic too.
858
+ *
859
+ * A fixed-destination sink stays `"external-configured"` (warn): `SendMessage`
860
+ * replies to the operator's channel, `WebSearch` and `ImageGenerate` call a
861
+ * fixed provider, a code host is reached at its configured origin. The
862
+ * names that were dynamic before tools declared their destinations (Fetch,
863
+ * WebFetch, Navigate, EvmSendTransaction) stay dynamic, so a caller that
864
+ * passes only a name gets the 0.7.0 answer. Override per deployment with
865
+ * `runChatLoop({ resolveSinkScope })`.
717
866
  */
718
- export function defaultSinkScope(toolName) {
867
+ export function defaultSinkScope(toolName, tool) {
719
868
  if (toolName.startsWith("mcp__"))
720
869
  return "external-dynamic";
721
870
  if (MODEL_DESTINATION_SINKS.has(toolName))
722
871
  return "external-dynamic";
872
+ if (tool !== undefined && hasModelChosenDestination(tool))
873
+ return "external-dynamic";
723
874
  return "external-configured";
724
875
  }
725
876
  /**
@@ -751,6 +902,30 @@ function bestEffortWireModelId(modelString) {
751
902
  return modelString;
752
903
  }
753
904
  }
905
+ /**
906
+ * 0.7.1 — every model string the run was configured with, for the bridge's
907
+ * `specModels` (the Task tool's allow-list for a `.crewhaus/sub-agents`
908
+ * definition's models). Exact strings, in first-seen order, no duplicates.
909
+ */
910
+ export function specModelsOf(opts) {
911
+ const out = new Set([opts.model]);
912
+ for (const m of opts.modelFallbacks ?? [])
913
+ out.add(m);
914
+ if (opts.modelTiers !== undefined) {
915
+ out.add(opts.modelTiers.fast);
916
+ out.add(opts.modelTiers.default);
917
+ }
918
+ for (const c of opts.modelPool?.candidates ?? []) {
919
+ out.add(c.model);
920
+ for (const m of c.fallbacks ?? [])
921
+ out.add(m);
922
+ }
923
+ if (opts.compactionModel !== undefined)
924
+ out.add(opts.compactionModel);
925
+ if (opts.budget?.onExceed.kind === "degrade")
926
+ out.add(opts.budget.onExceed.model);
927
+ return [...out];
928
+ }
754
929
  /**
755
930
  * A short, stable fingerprint of a `model_pool` config, stamped on every
756
931
  * `model_route` event as `policyVersion` so a learned decision can be tied back
@@ -906,33 +1081,284 @@ export function buildTimeoutFailureReport(timeout) {
906
1081
  exitCode: EXIT_CODES.timeout,
907
1082
  };
908
1083
  }
1084
+ /**
1085
+ * provider-limits#0 — act on a boot tool-limit verdict: no model can take the
1086
+ * run's tools → a `ConfigError` before any model call; some model cannot →
1087
+ * one `[tools]` line per model on stderr, beside the `[failover]` and
1088
+ * `[model_pool]` boot lines. A daemon runs one loop per message, so each
1089
+ * line is written once per process (`unreportedToolLimitLines`).
1090
+ */
1091
+ function reportToolLimits(verdict) {
1092
+ if (verdict.fatal !== undefined)
1093
+ throw new ConfigError(verdict.fatal);
1094
+ for (const line of unreportedToolLimitLines(verdict.warnings)) {
1095
+ process.stderr.write(`[tools] ${line}\n`);
1096
+ }
1097
+ }
909
1098
  /**
910
1099
  * Item 3 (G32) — merge plugin-contributed tools into the run's advertised tool
911
1100
  * set. First-party `base` tools WIN any name collision, so an activated plugin
912
- * can augment the catalog but never silently shadow a built-in. Returns the
913
- * `base` array unchanged (same reference) when there are no plugin tools, so a
914
- * run without the `plugins` option is byte-identical to a pre-G32 runtime.
1101
+ * can augment the catalog but never silently shadow a built-in; nor can it
1102
+ * take a name in `reserved` — the tools the loop adds itself (`ListTools`,
1103
+ * and `Consult` / `Escalate`), which would otherwise give way to it. Returns
1104
+ * the `base` array unchanged (same reference) when there are no plugin tools,
1105
+ * so a run without the `plugins` option is byte-identical to a pre-G32
1106
+ * runtime.
915
1107
  */
916
- function mergeEffectiveTools(base, pluginTools) {
1108
+ function mergeEffectiveTools(base, pluginTools, reserved = new Set()) {
917
1109
  if (pluginTools === undefined || pluginTools.length === 0)
918
1110
  return base;
919
1111
  const byName = new Set(base.map((t) => t.name));
920
1112
  const merged = [...base];
921
1113
  for (const tool of pluginTools) {
922
- if (byName.has(tool.name))
923
- continue; // first-party wins the collision
1114
+ if (byName.has(tool.name) || reserved.has(tool.name))
1115
+ continue; // first-party wins
924
1116
  byName.add(tool.name);
925
1117
  merged.push(tool);
926
1118
  }
927
1119
  return merged;
928
1120
  }
1121
+ /**
1122
+ * Does `limits` set a limit for `toolName` itself? Own keys only: a tool may
1123
+ * be named after an Object.prototype member (`toString`, `constructor`),
1124
+ * which a plain `rate_limits` object inherits but never sets.
1125
+ */
1126
+ function ownLimit(limits, toolName) {
1127
+ return Object.hasOwn(limits, toolName) && limits[toolName] !== undefined;
1128
+ }
1129
+ /** A transcript `tool_result` block's text: a string as is, the text blocks of an array joined. */
1130
+ function gateResultText(content) {
1131
+ if (typeof content === "string")
1132
+ return content;
1133
+ if (!Array.isArray(content))
1134
+ return "";
1135
+ const texts = [];
1136
+ for (const block of content) {
1137
+ if (typeof block !== "object" || block === null)
1138
+ continue;
1139
+ const b = block;
1140
+ if (b["type"] === "text" && typeof b["text"] === "string")
1141
+ texts.push(b["text"]);
1142
+ }
1143
+ return texts.join("\n");
1144
+ }
1145
+ /**
1146
+ * §5.4 — a claimless final message that hands the reader an earlier answer
1147
+ * again: "See above.", "As I said before.", "Same as my previous answer.".
1148
+ * Where that earlier answer was rejected, its ✗ stands with it.
1149
+ */
1150
+ const POINTS_BACK = /\b(?:see|as|per)\s+(?:above|before|earlier|(?:my|the)\s+(?:previous|last|earlier|above)\s+(?:answer|reply|message|response))\b|\bas\s+(?:i\s+)?(?:said|stated|mentioned|noted)\b|\b(?:same|unchanged)\s+(?:as\s+)?(?:above|before)\b|^\s*(?:↑+|\^+)\s*$/i;
1151
+ /** The verbs an agent announces a tool call with, as a bare verb ("I can look …", "Step 1: fetch …"). */
1152
+ const ACTION_VERB = "look|check|fetch|pull|search|find|get|read|open|load|query|call|run|grab|retrieve|verify|confirm|review|scan|browse|consult|research|investigate|book|save|write|create|send|update|cancel|schedule|submit|place|add|remove|delete|download|upload|process|prepare|draft|dig|try|start|contact|ping|help|take|see|do";
1153
+ /**
1154
+ * The verbs "I can …" offers a tool call with ("I can look that up."): the
1155
+ * fetch-style ones only. "I can see / confirm / verify / find / review /
1156
+ * help / do / take …" opens what the agent says it knows ("I can confirm
1157
+ * your refund has been processed."), and is read as written.
1158
+ */
1159
+ const FETCH_VERB = "look|check|fetch|pull|search|get|grab|retrieve|dig|query|load|open|read|browse|scan|run|try|book|save|draft|prepare|send|schedule|cancel|update|add|remove|create|write|submit|place|start|contact|ping|download|upload";
1160
+ /** The same verbs as a gerund opener ("Fetching the policy page."). */
1161
+ const ACTION_GERUND = "looking|checking|double-checking|fetching|pulling|searching|finding|getting|reading|opening|loading|querying|calling|running|grabbing|retrieving|verifying|confirming|reviewing|scanning|browsing|consulting|researching|investigating|booking|saving|writing|creating|sending|updating|cancel(?:l)?ing|scheduling|submitting|placing|adding|removing|deleting|downloading|uploading|processing|preparing|drafting|digging|trying|starting|contacting|pinging|working";
1162
+ /**
1163
+ * §5.4 — a sentence that only says what the agent is about to do, whatever
1164
+ * its wording: "Let me fetch the refund policy page first.", "I'll save the
1165
+ * note to your notes file now.", "Fetching the refund policy page.", "One
1166
+ * moment while I look that up.", "Give me a second to check.", "I can look
1167
+ * that up.", "Step 1: fetch the policy page." — an acknowledgement before it
1168
+ * included ("Okay,", "Sure —", "Great question —", "To answer that,").
1169
+ * Printed before a tool call, it is narration, not an answer the reader is
1170
+ * handed. A gerund opener announces only while no verb of its own follows:
1171
+ * "Processing the refund takes a few days." states something.
1172
+ */
1173
+ const NARRATION = new RegExp([
1174
+ "^(?:(?:ok(?:ay)?|now|next|first|then|alright|all right|sure|great|perfect|right|got it|understood|of course|certainly|absolutely|no problem|sounds good|thanks|thank you|good question|great question|happy to help",
1175
+ "|to (?:answer|check|confirm|find|look|do|help|get|figure|see|verify)\\b[^,.!?—–]{0,40})",
1176
+ "(?:\\s*[,!:—–-]\\s*|\\s+)){0,2}",
1177
+ "(?:let me|let's|let us|allow me to|i'll|i will|i'm going to|i am going to|i'm gonna|i'm about to|i am about to",
1178
+ "|i need to|i want to|i'd (?:like|need|want) to",
1179
+ `|i can (?:${FETCH_VERB})\\b`,
1180
+ "|i'm (?:now |first |just )?\\w+ing|i am (?:now |first |just )?\\w+ing",
1181
+ "|(?:just )?(?:one|a) (?:moment|sec(?:ond)?|minute)|give me (?:a|one) (?:moment|sec(?:ond)?|minute)",
1182
+ "|hold on|hang on|bear with me|stand by",
1183
+ `|step \\d+[:.)]\\s+(?:${ACTION_VERB})`,
1184
+ `|(?:now |first |just )?(?:${ACTION_GERUND})\\s+(?:the|your|my|our|a|an|that|this|these|those|it|them|for|up|into|through|over|on|in|at|now|with|out|back|again|some|all)\\b(?!.*\\b(?:is|are|was|were|isn't|aren't|wasn't|weren't|has|have|had|hasn't|haven't|takes?|took|costs?|requires?|means?|needs?|will|would|can|could|should|must|may|might|does|doesn't|did|didn't|gets?|got|makes?|made|includes?|lasts?|shows?|says?|said|returns?|returned)\\b))\\b`,
1185
+ ].join(""), "i");
1186
+ /**
1187
+ * A word that makes what follows a narration opener a statement: a finite
1188
+ * "be" / "have" / "do", a modal, a negation's contraction, or a verb a
1189
+ * statement of fact is made with ("Of course, I'll note that refunds are not
1190
+ * allowed.", "Let me record that your plan costs $49 per month."). Narration
1191
+ * that only announces a call carries none of these: "Let me fetch the refund
1192
+ * policy page first." Third-person and past forms only, never a base verb
1193
+ * ("Let me take a look.", "I'll have a look."), and not "may", which is a
1194
+ * month as often ("Let me pull up your May invoice."). The list is closed on
1195
+ * purpose — a word it misses is caught by the clause rules below or graded
1196
+ * as written.
1197
+ */
1198
+ const STATES = /\b(?:is|are|was|were|isn't|aren't|wasn't|weren't|am|been|has|had|hasn't|haven't|hadn't|does|did|doesn't|don't|didn't|won't|can't|cannot|couldn't|shouldn't|wouldn't|will|would|can|could|should|must|might|shall|(?:it|that|there|here|this|what|who|he|she)'s|\w+'(?:re|ve)|takes|took|costs|requires|means|needs|gets|got|makes|made|includes|lasts|shows|says|said|told|returns|returned|covers|renews|went|came|became|began|owes|equals|totals|remains|seems|appears|looks like|expires|expired|applies|allows|contains|qualifies)\b/i;
1199
+ /** "that" opening a clause with its own subject ("I'll note that the window …"), not "look that up". */
1200
+ const THAT_CLAUSE = /\bthat\s+(?:the|your|my|our|their|his|her|its|it|they|we|you|he|she|there|everything|nothing|all|each|every|no|refunds?|orders?)\b/i;
1201
+ /** An embedded question: what follows it asks, and asserts nothing ("Let me check whether the refund has gone through."). */
1202
+ const ASKS = /\b(?:if|whether|what|which|where|when|how|who|whom)\b/i;
1203
+ /** Where a clause of its own may begin: a comma, colon or semicolon before a space, or a dash. */
1204
+ const CLAUSE_BREAK = /[,;:](?=\s)|\s[-–—]\s|[—–]/;
1205
+ /** A clause after a break that adds nothing a reader could check ("…, please.", "— one moment."). */
1206
+ const AFTERTHOUGHT = /^(?:please|thanks|thank you|for you|now|first|then|again|real quick|quickly|right away|right now|in a (?:moment|sec(?:ond)?|minute)|if (?:that's|that is) (?:ok(?:ay)?|alright|all right|fine)|if you don't mind|if that works|one (?:moment|sec(?:ond)?|minute)|just a (?:moment|sec(?:ond)?|minute)|bear with me|hang on|hold on)$/i;
1207
+ /** A clause after a break that goes on announcing a call ("…, then save a note."). */
1208
+ const ANNOUNCES_MORE = new RegExp(`^(?:and |then |and then |or |so |before |after that )?(?:i'll |i will |i can |let me )?(?:${ACTION_VERB})\\b`, "i");
1209
+ /** Does `words` assert something, outside an embedded question it may end in? */
1210
+ function asserts(words) {
1211
+ const asked = ASKS.exec(words);
1212
+ const said = asked === null ? words : words.slice(0, asked.index);
1213
+ return STATES.test(said) || THAT_CLAUSE.test(said);
1214
+ }
1215
+ /**
1216
+ * Does a narration sentence state something beyond its announcement? What
1217
+ * follows the opener {@link NARRATION} matched is read clause by clause:
1218
+ * the announcement's own clause states something when it asserts
1219
+ * ({@link asserts}); every clause after a break ({@link CLAUSE_BREAK}) does
1220
+ * unless it is an afterthought, goes on announcing, or is narration itself.
1221
+ * "Hold on, refunds are not allowed on sale items.", "Looking at your
1222
+ * account, your refund went through yesterday." and "Pulling up your order
1223
+ * — it shipped Tuesday via UPS." state something; "Let me check the policy
1224
+ * page, then save a note." does not.
1225
+ */
1226
+ function statesSomething(plain, openerEnd) {
1227
+ const clauses = plain.slice(openerEnd).split(CLAUSE_BREAK);
1228
+ if (asserts(clauses[0] ?? ""))
1229
+ return true;
1230
+ for (const raw of clauses.slice(1)) {
1231
+ const clause = raw
1232
+ .trim()
1233
+ .replace(/[.!?…]+$/, "")
1234
+ .trim();
1235
+ if (clause === "" || AFTERTHOUGHT.test(clause))
1236
+ continue;
1237
+ if (asserts(clause))
1238
+ return true;
1239
+ if (ANNOUNCES_MORE.test(clause))
1240
+ continue;
1241
+ const opener = NARRATION.exec(clause);
1242
+ if (opener === null || statesSomething(clause, opener[0].length))
1243
+ return true;
1244
+ }
1245
+ return false;
1246
+ }
1247
+ /** A figure as written: a run of digits with its inner separators ("4512", "10:30", "1,284.50", "2025-01-31"). */
1248
+ const FIGURE = /\d+(?:[.,:/-]\d+)*/g;
1249
+ /**
1250
+ * A figure that names a thing rather than measures one: a label before it
1251
+ * ("section 4", "order #4512", "ticket 88", "v2") or a year ("the 2025
1252
+ * terms"). Narration that names one is still narration.
1253
+ */
1254
+ const NAMING_LABEL = /(?:#|\b(?:section|order|ticket|case|invoice|item|step|page|chapter|part|line|row|issue|pr|no\.|number|id|version|v|room|seat|flight|gate|account|ref|reference|clause|article|rule|question|q)\s*)$/i;
1255
+ /** Is the figure at `index` in `sentence` a name ({@link NAMING_LABEL}, a year)? */
1256
+ function namesAThing(sentence, figure, index) {
1257
+ return (/^(?:19|20)\d\d$/.test(figure) ||
1258
+ NAMING_LABEL.test(sentence.slice(Math.max(0, index - 16), index)));
1259
+ }
1260
+ /**
1261
+ * The figures `text` holds, each as written and each run of up to four of
1262
+ * its parts ("10:30:00" holds "10:30" and "30"): a narration's figure is
1263
+ * echoed when it is one of them. Built once, in one pass, so a long input or
1264
+ * tool call costs a set lookup per figure, not a scan.
1265
+ */
1266
+ function figuresIn(text, into = new Set()) {
1267
+ const out = into;
1268
+ for (const [figure] of text.matchAll(FIGURE)) {
1269
+ out.add(figure);
1270
+ // Digit runs at the even indexes, the separators between them at the odd.
1271
+ const parts = figure.split(/([.,:/-])/);
1272
+ for (let from = 0; from < parts.length; from += 2) {
1273
+ let window = parts[from] ?? "";
1274
+ out.add(window);
1275
+ for (let to = from + 2; to < parts.length && to < from + 8; to += 2) {
1276
+ window += `${parts[to - 1] ?? ""}${parts[to] ?? ""}`;
1277
+ out.add(window);
1278
+ }
1279
+ }
1280
+ }
1281
+ return out;
1282
+ }
1283
+ /**
1284
+ * The figures a tool call's input carries as values of their own: a number,
1285
+ * a string that is one figure ("10:30", "4512"), or a string with no space
1286
+ * in it (an id, a time, a URL or a path: "https://…/orders/4512"). A figure
1287
+ * inside free text the call is handed (a note's `text`, a message's
1288
+ * `body`) is the agent's own writing, not the call's argument: "I'll save a
1289
+ * note that the window is 30 days." with `{text: "Refund window: 30 days"}`
1290
+ * is graded. Walked to a bounded depth and breadth.
1291
+ */
1292
+ function callFigures(input, into, depth = 0) {
1293
+ if (depth > 8)
1294
+ return;
1295
+ if (typeof input === "number" && Number.isFinite(input)) {
1296
+ figuresIn(String(input), into);
1297
+ return;
1298
+ }
1299
+ if (typeof input === "string") {
1300
+ if (input.length <= 2048 && !/\s/.test(input.trim()))
1301
+ figuresIn(input, into);
1302
+ return;
1303
+ }
1304
+ if (typeof input !== "object" || input === null)
1305
+ return;
1306
+ const values = Array.isArray(input) ? input : Object.values(input);
1307
+ for (const value of values.slice(0, 256))
1308
+ callFigures(value, into, depth + 1);
1309
+ }
1310
+ /**
1311
+ * `text` with its narration sentences ({@link NARRATION}) taken out and the
1312
+ * rest exactly as written — its lines too, so a definition line stays one.
1313
+ * A sentence ends at a terminator that whitespace or the end follows, so a
1314
+ * URL's dots or a decimal point do not cut it in two. A narration sentence
1315
+ * with a marker in it stays, as does one with a figure the agent brings
1316
+ * itself ("Let me note: the window is 30 days.", "I'll double-check the
1317
+ * 30-day window."): that is a claim the reader was handed. A figure that
1318
+ * names a thing ({@link namesAThing}: "section 4", "the 2025 terms"), or
1319
+ * that `echo` holds ({@link figuresIn} the turn's own input, and the input
1320
+ * of the tool calls the narration announces) is the reader's or the call's,
1321
+ * not the agent's: "Let me book the 10:30 slot.", "Let me fetch
1322
+ * https://…/policy/2024." stay narration. None of that exempts a sentence
1323
+ * that states something past its announcement ({@link statesSomething}):
1324
+ * "Let me confirm — yes, the refund window is 30 days." is graded however
1325
+ * often the reader asked about 30 days.
1326
+ *
1327
+ * A sentence starts on a character that is no terminator, so a line of
1328
+ * terminators is never re-read from inside (each start position used to
1329
+ * walk the whole run again: quadratic on a long one); a run that opens a
1330
+ * line is kept as written.
1331
+ */
1332
+ function withoutNarration(text, echo) {
1333
+ return text
1334
+ .replace(/[^\n.!?…]+(?:[.!?…]+(?=[^\s.!?…])[^\n.!?…]*)*(?:[.!?…]+|$)/gm, (sentence) => {
1335
+ const plain = sentence
1336
+ .trim()
1337
+ .replace(/^[*_>#\s-]+/, "")
1338
+ .replace(/’/g, "'");
1339
+ if (plain === "" || plain.includes("["))
1340
+ return sentence;
1341
+ const opener = NARRATION.exec(plain);
1342
+ if (opener === null || statesSomething(plain, opener[0].length))
1343
+ return sentence;
1344
+ for (const found of plain.matchAll(FIGURE)) {
1345
+ const figure = found[0];
1346
+ if (!namesAThing(plain, figure, found.index) && !echo.some((held) => held.has(figure))) {
1347
+ return sentence;
1348
+ }
1349
+ }
1350
+ return "";
1351
+ })
1352
+ .replace(/[ \t]+$/gm, "")
1353
+ .trim();
1354
+ }
929
1355
  export async function runChatLoop(opts) {
930
1356
  // Item 3 (G32) — resolve the advertised tool set ONCE, up front, folding in
931
1357
  // any plugin-contributed tools so the tool-capable-model feature gate and the
932
1358
  // per-turn advertisement below read the same list.
933
1359
  // 0.6.0 — then the hybrid-strategy tools (`Consult` / `Escalate`) the
934
1360
  // composition root registered, same first-party-wins posture.
935
- const mergedTools = mergeEffectiveTools(mergeEffectiveTools(opts.tools ?? [], opts.plugins?.tools), opts.hybridTools);
1361
+ const mergedTools = mergeEffectiveTools(mergeEffectiveTools(opts.tools ?? [], opts.plugins?.tools, new Set(LOOP_TOOL_NAMES)), opts.hybridTools);
936
1362
  // #405 — the runtime's own toolset-introspection tool rides every
937
1363
  // TOOL-CARRYING loop. Late-bound: it is part of the list it reports, so it
938
1364
  // reads the advertised summaries assigned after that list is built below.
@@ -1037,6 +1463,44 @@ export async function runChatLoop(opts) {
1037
1463
  if (effectiveTools.length > 0 && adapter.features.tool_use === false) {
1038
1464
  throw new ConfigError(`model "${opts.model}" (provider ${providerId}) does not support tool use — remove tools or pick a tool-capable model`);
1039
1465
  }
1466
+ // provider-limits#0 — the same fail-early rule for the tool COUNT: OpenAI
1467
+ // (and Azure OpenAI, Groq) refuse more than 128 tools on one request,
1468
+ // Gemini more than 512, and they refuse every request of the run. The list
1469
+ // is final here (builtins, loop tools, MCP, plugin and hybrid tools), so
1470
+ // this is the check `--model` overrides and MCP servers cannot slip past.
1471
+ // A pool is checked per candidate below, once each candidate's subset is
1472
+ // known.
1473
+ if (opts.modelPool === undefined) {
1474
+ const count = effectiveTools.length;
1475
+ const serving = opts.modelTiers !== undefined
1476
+ ? ["fast", "default"].map((tier) => {
1477
+ const model = opts.modelTiers[tier];
1478
+ return {
1479
+ model,
1480
+ toolCount: count,
1481
+ role: "serves",
1482
+ label: `model_tiers.${tier} "${model}"`,
1483
+ whenOver: `the run starts, and every turn routed to the ${tier} tier fails`,
1484
+ };
1485
+ })
1486
+ : [opts.model, ...modelFallbacks].map((model, i) => ({
1487
+ model,
1488
+ toolCount: count,
1489
+ role: "serves",
1490
+ label: i === 0 ? `model "${model}"` : `model_fallbacks[${i - 1}] "${model}"`,
1491
+ whenOver: "the run starts because another model in the chain can serve",
1492
+ }));
1493
+ if (opts.budget?.onExceed.kind === "degrade") {
1494
+ serving.push({
1495
+ model: opts.budget.onExceed.model,
1496
+ toolCount: count,
1497
+ role: "degrade",
1498
+ label: `budget degrade model "${opts.budget.onExceed.model}"`,
1499
+ whenOver: "a budget degrade to it would fail every call",
1500
+ });
1501
+ }
1502
+ reportToolLimits(checkServingToolLimits(serving, process.env));
1503
+ }
1040
1504
  let compactionAdapter;
1041
1505
  let compactionWireModelId;
1042
1506
  if (opts._compactionAdapter !== undefined) {
@@ -1172,6 +1636,58 @@ export async function runChatLoop(opts) {
1172
1636
  throw new RuntimeError("runChatLoop: `sideCalls.committee` is legal in singleTurn mode only (a workflow step, a graph node, a crew role) — a REPL or per-message turn is one the user is waiting on");
1173
1637
  }
1174
1638
  const sessionRootDir = resolveSessionRootDir(opts.sessionRootDir);
1639
+ // 0.8.0 (design §1 principle 1, §5.2) — the session logs, the spilled
1640
+ // tool results and the proof bundles this run's gates read as evidence: no
1641
+ // tool call the agent makes may write there, whatever a rule says
1642
+ // (permission-engine's runtime-state floor, `./state-roots`).
1643
+ const protectedRoots = runtimeStateRoots(sessionRootDir, currentTenantContext()?.tenant);
1644
+ /**
1645
+ * The floor's reading of a call: where it WRITES. Two kinds of field are
1646
+ * left out, field by field:
1647
+ *
1648
+ * - one declared `relocates` names the store a tool works in through its
1649
+ * own format (EmitTraceEvent's namespaced `custom.*` lines,
1650
+ * IncidentBundle's sessions it reads whole), not a file the call names;
1651
+ * - one declared `source` holds where the tool takes a value FROM (the
1652
+ * files IndexBuild indexes, the file DatasetPut reads, the reference
1653
+ * EnvFileUpsert copies a secret out of): reading a spilled output or a
1654
+ * session log forges nothing, and the runtime itself points the model
1655
+ * at a spill (`[truncated, full output at …]`), so a copy, an index or
1656
+ * an import of one is no write into the record (§1 principle 3: the
1657
+ * floor must not refuse what a harness without the block could do).
1658
+ *
1659
+ * - one declared `reads` (or `readsWhen`, when the call names the field
1660
+ * it names) the tool only reads, writing where another field says:
1661
+ * CopyPath's and ArchiveCreate's `source`, ArchiveExtract's `archive`,
1662
+ * an importer's `file`. A backup of `.crewhaus` copies the record; it
1663
+ * writes none of it. MovePath's `source` is not one: a move takes it
1664
+ * away.
1665
+ *
1666
+ * Every other operative value counts — a secret reference's file included
1667
+ * (SecretRotate's `ref` names the file it writes). `undefined` ⇒ the
1668
+ * call's operative values as they are (a tool with neither kind of field).
1669
+ */
1670
+ const floorValuesOf = (tool, parsedInput) => {
1671
+ const args = tool.operativeArgs;
1672
+ const named = (name) => {
1673
+ if (typeof parsedInput !== "object" || parsedInput === null)
1674
+ return false;
1675
+ const value = parsedInput[name];
1676
+ return value !== undefined && value !== null && value !== "";
1677
+ };
1678
+ const skipped = (arg) => arg.relocates === true ||
1679
+ arg.source === true ||
1680
+ arg.reads === true ||
1681
+ (arg.readsWhen !== undefined && named(arg.readsWhen));
1682
+ if (args === undefined || !args.some(skipped))
1683
+ return undefined;
1684
+ const written = args.filter((arg) => !skipped(arg));
1685
+ if (written.length === 0)
1686
+ return [];
1687
+ return (operativeValuesFor({ ...tool, operativeArgs: written }, parsedInput, {
1688
+ canonicalizePath: placeRecordingCanonicalizer().canonicalizePath,
1689
+ }) ?? []);
1690
+ };
1175
1691
  const sessionStore = persistSession
1176
1692
  ? createSessionStore({ rootDir: sessionRootDir })
1177
1693
  : createMemorySessionStore();
@@ -1594,6 +2110,14 @@ export async function runChatLoop(opts) {
1594
2110
  // the cap bounds the conversation rather than one resumed run. Stays 0
1595
2111
  // under the default `run` scope.
1596
2112
  let resumedCostUsdMicros = 0;
2113
+ // 0.8.0 (design §5.3) — the turns the resumed session already ran. The
2114
+ // run's own counter (`runContext.turnNumber`) restarts at 0 on every run,
2115
+ // and every channel message after a thread's first, every managed
2116
+ // `runs.continue` and every `--resume` is a new run; a proof bundle is
2117
+ // filed per SESSION turn (`<sessionId>/turn-<n>.json`, the audit artifact),
2118
+ // so the gate numbers its turns from here (`provabilityTurn`). Nothing else
2119
+ // reads it: the run-local counter keeps its meaning everywhere else.
2120
+ let resumedTurns = 0;
1597
2121
  const budgetSessionScoped = opts.budget?.scope === "session";
1598
2122
  if (opts.resume) {
1599
2123
  const existing = await sessionStore.get(opts.resume.sessionId);
@@ -1605,6 +2129,7 @@ export async function runChatLoop(opts) {
1605
2129
  resumedPin = existing.pin;
1606
2130
  const replayLog = await openEventLog(sessionId, { rootDir: sessionRootDir });
1607
2131
  resumedMessages = await replayMessageHistory(replayLog);
2132
+ resumedTurns = openedTurnCount(resumedMessages);
1608
2133
  // One pass gathers both resume-time reads: the continuity ledger seed
1609
2134
  // (conditional) and the LAST recorded toolset (#405 — unconditional, so
1610
2135
  // the marker below can tell a resumed session its capabilities changed
@@ -1978,18 +2503,30 @@ export async function runChatLoop(opts) {
1978
2503
  const mdRenderer = isCliMarkdownEnabled()
1979
2504
  ? createCliMarkdownRenderer({ write: (s) => out.write(s) })
1980
2505
  : undefined;
2506
+ const printText = (chunk) => {
2507
+ if (mdRenderer)
2508
+ mdRenderer.push(chunk);
2509
+ else
2510
+ out.write(chunk);
2511
+ };
2512
+ // 0.8.0 (design §1 principle 2, §5.4) — under `provability:` a line of the
2513
+ // answer shaped like the gate's footer streams with a mark saying the model
2514
+ // wrote it (`./forged-footer`): the one verdict line the reader sees is the
2515
+ // gate's. Without the block the text streams exactly as before.
2516
+ const footerGuard = opts.provability !== undefined ? createFooterLineGuard(printText) : undefined;
1981
2517
  const writeText = (chunk) => {
1982
2518
  // First real assistant text ends the "thinking" wait; clear the spinner
1983
2519
  // (idempotent on later chunks) before the answer streams.
1984
2520
  out.spinner.stop();
1985
- if (mdRenderer)
1986
- mdRenderer.push(chunk);
2521
+ if (footerGuard !== undefined)
2522
+ footerGuard.push(chunk);
1987
2523
  else
1988
- out.write(chunk);
2524
+ printText(chunk);
1989
2525
  };
1990
2526
  const endTurn = () => {
1991
2527
  // Covers the no-text/no-tool case where the spinner is still up.
1992
2528
  out.spinner.stop();
2529
+ footerGuard?.end();
1993
2530
  if (mdRenderer)
1994
2531
  mdRenderer.end();
1995
2532
  out.write("\n");
@@ -2059,6 +2596,33 @@ export async function runChatLoop(opts) {
2059
2596
  }));
2060
2597
  }
2061
2598
  const armIdOf = (candidate) => poolCandidateConfigs.get(candidate)?.profile ?? candidate.modelString;
2599
+ // provider-limits#0 — each pool candidate against its provider's
2600
+ // per-request tool limit, counted on the subset IT is advertised. One over
2601
+ // its limit is left out of routing (the `tool-limit` eligibility exclusion
2602
+ // in preRoute); a pool none of whose candidates can accept its tools
2603
+ // cannot make one call, and stops here.
2604
+ if (poolRouter !== undefined) {
2605
+ const serving = [];
2606
+ for (const [candidate, ad] of candidateAdvertisements) {
2607
+ serving.push({
2608
+ model: candidate.modelString,
2609
+ toolCount: ad.names.size,
2610
+ role: "serves",
2611
+ label: `model_pool candidate "${armIdOf(candidate)}"`,
2612
+ whenOver: "routing leaves it out",
2613
+ });
2614
+ }
2615
+ if (budgetDegradeRung !== undefined && !candidateAdvertisements.has(budgetDegradeRung)) {
2616
+ serving.push({
2617
+ model: budgetDegradeRung.modelString,
2618
+ toolCount: effectiveTools.length,
2619
+ role: "degrade",
2620
+ label: `budget degrade model "${budgetDegradeRung.modelString}"`,
2621
+ whenOver: "a budget degrade to it would fail every call",
2622
+ });
2623
+ }
2624
+ reportToolLimits(checkServingToolLimits(serving, process.env));
2625
+ }
2062
2626
  {
2063
2627
  const currentToolNames = [...effectiveTools.map((t) => t.name)].sort();
2064
2628
  const prior = resumedToolNames === undefined ? undefined : [...resumedToolNames].sort();
@@ -2520,6 +3084,18 @@ export async function runChatLoop(opts) {
2520
3084
  }
2521
3085
  : undefined;
2522
3086
  const bridgeContinuitySeam = opts.continuity !== undefined ? { loadPlan: opts.continuity.loadPlan } : undefined;
3087
+ // - provability: READ-ONLY (0.8.0 §8). The floor and the skill text cross;
3088
+ // the verifier, the retry policy and the bundle store stay parent-side,
3089
+ // so only this loop's final text is ever gated.
3090
+ const bridgeProvabilitySeam = opts.provability !== undefined
3091
+ ? {
3092
+ level: opts.provability.level,
3093
+ ...(opts.provability.skill !== undefined ? { skill: opts.provability.skill } : {}),
3094
+ }
3095
+ : undefined;
3096
+ // 0.7.1 — the models this run may name, so a sub-agent read from disk can
3097
+ // run on the parent's fallback or tier model, and on nothing unnamed.
3098
+ const bridgeSpecModels = specModelsOf(opts);
2523
3099
  // M3.1 — auto-load project memory files (AGENTS.md / CLAUDE.md /
2524
3100
  // CODE-COMPANION.md / AGENT.md) from cwd at session start. Follows the
2525
3101
  // vendor-neutral agents.md convention; compatible with Claude Code's
@@ -2564,11 +3140,11 @@ export async function runChatLoop(opts) {
2564
3140
  const seed = opts.memory.recallSeed ?? opts.instructions;
2565
3141
  const k = opts.memory.recallK ?? 5;
2566
3142
  // Pillar 3 — a recalled memory can embed content shaped by untrusted
2567
- // tool output from an earlier session; `renderRecalledMemory` applies
2568
- // the same delimiter-safety + boundary-classification defenses the
2569
- // security fabric uses for every other prompt-bound source (#53).
3143
+ // tool output from an earlier session; `renderRecalledMemory` classifies
3144
+ // each line at TrustOrigin "memory" (redacting a malicious one),
3145
+ // lineage-tags the admitted lines, and neutralizes breakout delimiters.
2570
3146
  const lines = await opts.memory.recall(seed, k);
2571
- const text = await renderRecalledMemory(lines);
3147
+ const text = await renderRecalledMemory(lines, runContext);
2572
3148
  if (text !== undefined) {
2573
3149
  memoryRecallBlock = [{ type: "text", text, cache_control: { type: "ephemeral" } }];
2574
3150
  out.write(`[memory] recalled ${lines.length} memory(ies) into the prompt\n`);
@@ -2603,7 +3179,7 @@ export async function runChatLoop(opts) {
2603
3179
  const k = opts.memory?.recallK ?? 5;
2604
3180
  try {
2605
3181
  const lines = await recall(query, k);
2606
- const text = await renderRecalledMemory(lines);
3182
+ const text = await renderRecalledMemory(lines, runContext);
2607
3183
  volatileRecallBlocks = text !== undefined ? [{ type: "text", text }] : [];
2608
3184
  if (lines.length > 0) {
2609
3185
  out.write(`[memory] refreshed ${lines.length} recalled memory(ies) for this turn\n`);
@@ -2735,7 +3311,12 @@ export async function runChatLoop(opts) {
2735
3311
  // gates the acquire call site: tools outside the map (no named entry, no
2736
3312
  // `"*"`) are not rate-gated at all — the limiter itself is fail-closed on
2737
3313
  // unknown keys, so the guard is what keeps unlisted tools ungated.
2738
- const rateLimitEntries = Object.entries(opts.rateLimits ?? {});
3314
+ // 0.7.1 — MCP tools are registered as `mcp__<server>__<tool>`; a limit a
3315
+ // spec wrote against the old `<server>__<tool>` spelling is re-keyed onto
3316
+ // the registered name so it keeps applying.
3317
+ const toolNamesAtStart = new Set(tools.map((t) => t.name));
3318
+ const runRateLimits = rekeyLegacyMcpToolKeys(opts.rateLimits, toolNamesAtStart);
3319
+ const rateLimitEntries = Object.entries(runRateLimits ?? {});
2739
3320
  let toolRateLimiter;
2740
3321
  if (rateLimitEntries.length > 0) {
2741
3322
  const buckets = new Map();
@@ -2748,8 +3329,8 @@ export async function runChatLoop(opts) {
2748
3329
  }
2749
3330
  toolRateLimiter = createRateLimiter({ buckets });
2750
3331
  }
2751
- const hasToolRateBucket = (toolName) => opts.rateLimits !== undefined &&
2752
- (opts.rateLimits[toolName] !== undefined || opts.rateLimits["*"] !== undefined);
3332
+ const hasToolRateBucket = (toolName) => runRateLimits !== undefined &&
3333
+ (ownLimit(runRateLimits, toolName) || ownLimit(runRateLimits, "*"));
2753
3334
  // -------------------------------------------------------------------------
2754
3335
  // 0.6.0 §4.4 — the per-candidate plan table. One plan per enabled pool
2755
3336
  // candidate (plus the degrade rung when it sits outside the roster), built
@@ -2795,7 +3376,8 @@ export async function runChatLoop(opts) {
2795
3376
  };
2796
3377
  const deny = cfg?.permissions?.deny ?? [];
2797
3378
  const ask = cfg?.permissions?.ask ?? [];
2798
- const rateEntries = Object.entries(cfg?.rateLimits ?? {});
3379
+ const planRateLimits = rekeyLegacyMcpToolKeys(cfg?.rateLimits, toolNamesAtStart);
3380
+ const rateEntries = Object.entries(planRateLimits ?? {});
2799
3381
  const armId = fromPool ? (cfg.profile ?? cfg.model) : (candidate?.modelString ?? opts.model);
2800
3382
  let planLimiter;
2801
3383
  if (rateEntries.length > 0) {
@@ -2812,7 +3394,6 @@ export async function runChatLoop(opts) {
2812
3394
  }
2813
3395
  planLimiter = createRateLimiter({ buckets });
2814
3396
  }
2815
- const planRateLimits = cfg?.rateLimits;
2816
3397
  const names = new Set(planAdvertised.map(({ tool }) => tool.name));
2817
3398
  return {
2818
3399
  armId,
@@ -2840,8 +3421,16 @@ export async function runChatLoop(opts) {
2840
3421
  permissionRules: fromPool ? narrowRuleSet(permissionRules, deny, ask) : permissionRules,
2841
3422
  ...(planLimiter !== undefined ? { toolRateLimiter: planLimiter } : {}),
2842
3423
  hasToolRateBucket: (toolName) => planRateLimits !== undefined &&
2843
- (planRateLimits[toolName] !== undefined || planRateLimits["*"] !== undefined),
2844
- ...(cfg?.toolConfigs !== undefined ? { toolConfigs: cfg.toolConfigs } : {}),
3424
+ (ownLimit(planRateLimits, toolName) || ownLimit(planRateLimits, "*")),
3425
+ // `$VAR` values in a candidate's tool_config are read from the
3426
+ // environment here, when the loop starts, as the boot registrations
3427
+ // read theirs — never compiled into the bundle. An unset one fails
3428
+ // the start and names the variable.
3429
+ ...(cfg?.toolConfigs !== undefined
3430
+ ? {
3431
+ toolConfigs: resolveToolConfigEnv(cfg.toolConfigs, `model_pool candidate ${cfg.profile ?? candidate?.modelString ?? opts.model} tool_config`, process.env).value,
3432
+ }
3433
+ : {}),
2845
3434
  ...(cfg?.overlay !== undefined
2846
3435
  ? { overlayBlock: { type: "text", text: cfg.overlay } }
2847
3436
  : {}),
@@ -3275,7 +3864,7 @@ export async function runChatLoop(opts) {
3275
3864
  // the prior turn in some streaming scenarios).
3276
3865
  const post = await fireHook("post-tool", {
3277
3866
  id: tu.id,
3278
- name: tu.name,
3867
+ ...hookToolName(tu.name),
3279
3868
  isError: result.is_error === true,
3280
3869
  });
3281
3870
  if (!post.allowed) {
@@ -3314,7 +3903,11 @@ export async function runChatLoop(opts) {
3314
3903
  }
3315
3904
  // Section 11 — pre-tool hook: short-circuit with the hook's reason
3316
3905
  // when any matching hook returns deny/block.
3317
- const preHook = await fireHook("pre-tool", { id: tu.id, name: tu.name, input: tu.input });
3906
+ const preHook = await fireHook("pre-tool", {
3907
+ id: tu.id,
3908
+ ...hookToolName(tu.name),
3909
+ input: tu.input,
3910
+ });
3318
3911
  if (!preHook.allowed) {
3319
3912
  return finish({
3320
3913
  type: "tool_result",
@@ -3330,17 +3923,60 @@ export async function runChatLoop(opts) {
3330
3923
  // this; surfaces that record what the model DID keep `tu.input`. See the
3331
3924
  // `justificationInjectedTools` comment at loop start for the full split.
3332
3925
  let operativeInput = operativeToolInput(tu.name, tu.input);
3926
+ // 0.7.1 — rules are checked against the call the tool will RUN: the
3927
+ // input parsed by the tool's own schema (unknown keys stripped, defaults
3928
+ // filled in) and the tool's declared operative values canonicalised
3929
+ // (paths resolved against the workspace, URLs parsed). Matching the raw
3930
+ // input let a decoy key, an extra argument, an omitted default, a `..` or
3931
+ // a symlinked directory walk past a rule. An input the schema rejects
3932
+ // could not run anyway, so it is denied here with the schema's message,
3933
+ // before any approval is asked for. Paths are resolved against the
3934
+ // current working directory, the root every workspace tool resolves
3935
+ // against when it runs.
3936
+ //
3937
+ // The canonicaliser also keeps a record of every path it read and where
3938
+ // each one landed: a headless approval is bound to it (see
3939
+ // `landsWhereApproved`).
3940
+ //
3941
+ // The tool's `tool_config` block on the serving candidate is the one it
3942
+ // will run with: a code host reads from it which API a call that names
3943
+ // none goes to, so a rule written on that host meets the call.
3944
+ const gateView = placeRecordingCanonicalizer();
3945
+ const gateToolConfig = toolConfigFor(servingPlan.toolConfigs, tu.name);
3946
+ const subject = preparePermissionSubject(tool, operativeInput, {
3947
+ canonicalizePath: gateView.canonicalizePath,
3948
+ readProgramPath: gateView.readProgramPath,
3949
+ ...(gateToolConfig !== undefined ? { toolConfig: gateToolConfig } : {}),
3950
+ });
3951
+ if (!subject.ok) {
3952
+ // Not a permission decision: no rule was consulted, and the call fails
3953
+ // the way a malformed call always has — an `is_error` tool result, with
3954
+ // `tool_call_end` recording it. Publishing it as a `permission_decision`
3955
+ // deny would count every malformed call as a policy denial (eval
3956
+ // safety_violations, the deny alerts and SLOs).
3957
+ return finish({
3958
+ type: "tool_result",
3959
+ tool_use_id: tu.id,
3960
+ content: subject.reason,
3961
+ is_error: true,
3962
+ });
3963
+ }
3333
3964
  // 0.6.0 §4.4 — the SERVING candidate's rule set: the run's rules narrowed
3334
3965
  // by the profile's `permissions.deny` / `.ask` through `narrowRuleSet`
3335
3966
  // (a decision-level meet — a profile can only tighten). The primary plan
3336
3967
  // carries the run's rules by reference, so a single-model run is unchanged.
3968
+ const floorValues = tool.readOnly ? undefined : floorValuesOf(tool, subject.input);
3337
3969
  const decisionDetails = evaluateWithReason({
3338
3970
  toolName: tu.name,
3339
- input: operativeInput,
3971
+ input: subject.input,
3972
+ ...(subject.operativeValues !== undefined
3973
+ ? { operativeValues: subject.operativeValues }
3974
+ : {}),
3975
+ ...(floorValues !== undefined ? { floorValues } : {}),
3340
3976
  readOnly: tool.readOnly,
3341
3977
  destructive: tool.destructive,
3342
3978
  requiresSandbox: tool.requiresSandbox,
3343
- }, permissionMode, servingPlan.permissionRules, { sandboxAvailable: opts.sandboxAvailable === true });
3979
+ }, permissionMode, servingPlan.permissionRules, { sandboxAvailable: opts.sandboxAvailable === true, protectedRoots });
3344
3980
  const decision = decisionDetails.decision;
3345
3981
  bus.publish({
3346
3982
  ...bus.envelope(),
@@ -3373,6 +4009,34 @@ export async function runChatLoop(opts) {
3373
4009
  // below so the approving operator SEES the justification.
3374
4010
  const inputHash = hashApprovalInput(tu.name, operativeInput);
3375
4011
  let existing = await approvals.store.get(tu.name, inputHash);
4012
+ // 0.7.1 — an approval parked before MCP tools were renamed is keyed on
4013
+ // the old `<server>__<tool>` spelling, and the operator may already
4014
+ // have granted it. Honour it (or re-use it while still pending)
4015
+ // rather than parking the same call again under a new id.
4016
+ const legacyToolName = legacyMcpToolName(tu.name);
4017
+ const approvalKeys = [[tu.name, inputHash]];
4018
+ if (legacyToolName !== undefined) {
4019
+ approvalKeys.push([legacyToolName, hashApprovalInput(legacyToolName, operativeInput)]);
4020
+ }
4021
+ if (existing === null && legacyToolName !== undefined) {
4022
+ existing = await approvals.store.get(legacyToolName, hashApprovalInput(legacyToolName, operativeInput));
4023
+ }
4024
+ // 0.7.1 — A GRANT COVERS THE PLACE IT WAS MADE FOR. The record is
4025
+ // keyed on the input, but a symlink moved since the park (by any
4026
+ // allowed call in the resumed turn) sends the same input somewhere
4027
+ // else. A grant, or a park to re-use, made where the call no longer
4028
+ // lands decides nothing here, and the newest record made where it
4029
+ // does land, if any, takes its place; otherwise the call is asked
4030
+ // again below. A DENY is honoured wherever the call lands: it can
4031
+ // only refuse, so asking again would add a prompt (and a chance of a
4032
+ // mistaken grant) for an action the operator already turned down.
4033
+ let movedFrom;
4034
+ if (existing !== null &&
4035
+ existing.decision !== "deny" &&
4036
+ !landsWhereApproved(existing, gateView)) {
4037
+ movedFrom = existing;
4038
+ existing = await findApprovalForPlace(approvals.store, approvalKeys, gateView);
4039
+ }
3376
4040
  // #400 — THE RESUMED CALL IS NOT THE PARKED CALL.
3377
4041
  //
3378
4042
  // A grant is keyed on whole-input equality, which silently assumes the
@@ -3395,6 +4059,7 @@ export async function runChatLoop(opts) {
3395
4059
  // card, and that action is what executes. Honouring the grant for the
3396
4060
  // regenerated input instead would let a re-worded `place_call` dial a
3397
4061
  // different number under an approval for the first.
4062
+ let replaySubject;
3398
4063
  if (existing === null) {
3399
4064
  const replay = await findReplayableGrant(approvals.store, {
3400
4065
  toolName: tu.name,
@@ -3408,10 +4073,28 @@ export async function runChatLoop(opts) {
3408
4073
  // calls both find the same unconsumed grant and both execute. The
3409
4074
  // set is per-run and in-process, which is where that race is;
3410
4075
  // across processes the store's `consumedAt` remains the authority.
4076
+ //
4077
+ // 0.7.1 — and bound like the exact match: the APPROVED input must
4078
+ // still land where it did when the operator approved it. Read here,
4079
+ // once, and re-checked against policy below from this same reading.
3411
4080
  if (replay !== undefined && !replayedApprovalIds.has(replay.id)) {
3412
- replayedApprovalIds.add(replay.id);
3413
- replayedFrom = replay;
3414
- existing = replay;
4081
+ const replayView = placeRecordingCanonicalizer();
4082
+ const subjectOfReplay = preparePermissionSubject(tool, operativeToolInput(tu.name, replay.input), {
4083
+ canonicalizePath: replayView.canonicalizePath,
4084
+ readProgramPath: replayView.readProgramPath,
4085
+ ...(gateToolConfig !== undefined ? { toolConfig: gateToolConfig } : {}),
4086
+ });
4087
+ // An approved input that no longer parses is denied by the
4088
+ // re-check below, as before; it has no place to compare.
4089
+ if (!subjectOfReplay.ok || landsWhereApproved(replay, replayView)) {
4090
+ replayedApprovalIds.add(replay.id);
4091
+ replayedFrom = replay;
4092
+ replaySubject = subjectOfReplay;
4093
+ existing = replay;
4094
+ }
4095
+ else {
4096
+ movedFrom ??= replay;
4097
+ }
3415
4098
  }
3416
4099
  }
3417
4100
  if (existing?.decision === "grant") {
@@ -3438,13 +4121,32 @@ export async function runChatLoop(opts) {
3438
4121
  // §10.1 — approval replay across candidates uses the SERVING
3439
4122
  // candidate's rule set: a grant parked while the strong arm
3440
4123
  // served does not run under a narrower arm's denies.
3441
- const recheck = evaluateWithReason({
3442
- toolName: tu.name,
3443
- input: approvedOperative,
3444
- readOnly: tool.readOnly,
3445
- destructive: tool.destructive,
3446
- requiresSandbox: tool.requiresSandbox,
3447
- }, permissionMode, servingPlan.permissionRules, { sandboxAvailable: opts.sandboxAvailable === true });
4124
+ // 0.7.1 — the recheck, like the first check, reads the PARSED
4125
+ // approved input and its canonical operative values; an approved
4126
+ // input that no longer parses is a denial, never a run.
4127
+ const approvedView = placeRecordingCanonicalizer();
4128
+ const approvedSubject = replaySubject ??
4129
+ preparePermissionSubject(tool, approvedOperative, {
4130
+ canonicalizePath: approvedView.canonicalizePath,
4131
+ readProgramPath: approvedView.readProgramPath,
4132
+ ...(gateToolConfig !== undefined ? { toolConfig: gateToolConfig } : {}),
4133
+ });
4134
+ const approvedFloor = approvedSubject.ok && !tool.readOnly
4135
+ ? floorValuesOf(tool, approvedSubject.input)
4136
+ : undefined;
4137
+ const recheck = approvedSubject.ok
4138
+ ? evaluateWithReason({
4139
+ toolName: tu.name,
4140
+ input: approvedSubject.input,
4141
+ ...(approvedSubject.operativeValues !== undefined
4142
+ ? { operativeValues: approvedSubject.operativeValues }
4143
+ : {}),
4144
+ ...(approvedFloor !== undefined ? { floorValues: approvedFloor } : {}),
4145
+ readOnly: tool.readOnly,
4146
+ destructive: tool.destructive,
4147
+ requiresSandbox: tool.requiresSandbox,
4148
+ }, permissionMode, servingPlan.permissionRules, { sandboxAvailable: opts.sandboxAvailable === true, protectedRoots })
4149
+ : { decision: "deny", reason: approvedSubject.reason };
3448
4150
  if (recheck.decision === "deny") {
3449
4151
  approved = false;
3450
4152
  denialMessage =
@@ -3462,7 +4164,7 @@ export async function runChatLoop(opts) {
3462
4164
  // actually RUN, so re-fire it against the substituted input.
3463
4165
  const replayHook = await fireHook("pre-tool", {
3464
4166
  id: tu.id,
3465
- name: tu.name,
4167
+ ...hookToolName(tu.name),
3466
4168
  input: tu.input,
3467
4169
  });
3468
4170
  if (!replayHook.allowed) {
@@ -3527,6 +4229,10 @@ export async function runChatLoop(opts) {
3527
4229
  toolName: tu.name,
3528
4230
  inputHash,
3529
4231
  input: tu.input,
4232
+ // 0.7.1 — what this park covers: where the call lands now, and
4233
+ // the approval it asks in place of, so a card can say both.
4234
+ places: gateView.places(),
4235
+ ...(movedFrom !== undefined ? { supersedes: supersededBy(movedFrom) } : {}),
3530
4236
  runId: bus.runId,
3531
4237
  sessionId,
3532
4238
  surface: approvalSurface,
@@ -3553,11 +4259,17 @@ export async function runChatLoop(opts) {
3553
4259
  approvalId: pending.id,
3554
4260
  toolName: tu.name,
3555
4261
  surface: approvalSurface,
4262
+ ...(movedFrom !== undefined ? { supersedes: movedFrom.id } : {}),
3556
4263
  });
4264
+ // Asked again because the call moved: say where it was approved
4265
+ // and where it lands now, so the operator decides on the new place.
4266
+ const moved = movedFrom === undefined
4267
+ ? ""
4268
+ : `; approval ${movedFrom.id} was ${movedFrom.decision === "grant" ? "granted" : "requested"} for ${describePlaces(movedFrom.places)}, and the call now lands at ${describePlaces(gateView.places())}, so it is asked again`;
3557
4269
  throw new RunFailedError({
3558
4270
  class: "approval_pending",
3559
4271
  title: "awaiting tool approval",
3560
- detail: `\`${tu.name}\` requires approval on a non-interactive surface (${approvalSurface}); the run is parked as approval ${pending.id}`,
4272
+ detail: `\`${tu.name}\` requires approval on a non-interactive surface (${approvalSurface})${moved}; the run is parked as approval ${pending.id}`,
3561
4273
  remediation: `grant or deny approval ${pending.id} out of band (e.g. \`crewhaus approvals grant ${pending.id}\`; add \`--always\` to allow \`${tu.name}\` from now on), then rerun`,
3562
4274
  exitCode: EXIT_CODES.approval_pending,
3563
4275
  });
@@ -3688,15 +4400,15 @@ export async function runChatLoop(opts) {
3688
4400
  // we deny the call before it fires. `warn` logs but proceeds.
3689
4401
  //
3690
4402
  // Resolve the sink-scope so the egress block tier is actually reachable
3691
- // (#144): runtime-joined MCP sinks default to `"external-dynamic"` (block
3692
- // non-user-origin content), while spec-declared sinks stay
3693
- // `"external-configured"` (warn). Callers can override via
3694
- // `opts.resolveSinkScope` to mark federation-joined or other dynamic sinks.
4403
+ // (#144): runtime-joined MCP sinks and tools that send to a destination
4404
+ // the model chose default to `"external-dynamic"` (block non-user-origin
4405
+ // content); other spec-declared sinks stay `"external-configured"`
4406
+ // (warn). Callers can override via `opts.resolveSinkScope`.
3695
4407
  if (tool.scope === "external") {
3696
4408
  // (#386) — scan the OPERATIVE payload: for injected-justification
3697
4409
  // tools this is what `executeTool` actually transmits to the sink.
3698
4410
  const payload = JSON.stringify(operativeInput ?? null);
3699
- const sinkScope = (opts.resolveSinkScope ?? defaultSinkScope)(tu.name);
4411
+ const sinkScope = (opts.resolveSinkScope ?? defaultSinkScope)(tu.name, tool);
3700
4412
  const egress = await classifyEgress(payload, runContext, {
3701
4413
  sinkId: tu.name,
3702
4414
  sinkScope,
@@ -3838,6 +4550,9 @@ export async function runChatLoop(opts) {
3838
4550
  const bridge = {
3839
4551
  runContext,
3840
4552
  eventLog,
4553
+ // 0.8.0 — the runtime-state roots, for the tools that write beneath a
4554
+ // directory they name and must not reach one (see RuntimeBridge).
4555
+ ...(protectedRoots.length > 0 ? { protectedRoots } : {}),
3841
4556
  permissionMode,
3842
4557
  permissionRules: servingPlan.permissionRules,
3843
4558
  tools: bridgeTools,
@@ -3868,6 +4583,8 @@ export async function runChatLoop(opts) {
3868
4583
  ...(skills.length > 0 ? { skills } : {}),
3869
4584
  ...(opts.failureTaxonomy !== undefined ? { failureTaxonomy: opts.failureTaxonomy } : {}),
3870
4585
  ...(bridgeContinuitySeam !== undefined ? { continuity: bridgeContinuitySeam } : {}),
4586
+ // 0.8.0 §8 — the read-only provability seam (projected above).
4587
+ ...(bridgeProvabilitySeam !== undefined ? { provability: bridgeProvabilitySeam } : {}),
3871
4588
  // Loop contract 0.4 (G11) — the approval seam, so a Task child's
3872
4589
  // headless `ask` parks against the SAME store the parent parks against
3873
4590
  // instead of collapsing to a denial. `askMode` is spread only when the
@@ -3875,6 +4592,19 @@ export async function runChatLoop(opts) {
3875
4592
  // `"pause"` default — identical resolution, no double-defaulting.
3876
4593
  ...(opts.askMode !== undefined ? { askMode: opts.askMode } : {}),
3877
4594
  ...(opts.approvals !== undefined ? { approvals: opts.approvals } : {}),
4595
+ // 0.7.1 — a Task child runs against this process's sandbox backend, so
4596
+ // it passes the sandbox floor exactly when this loop does.
4597
+ ...(opts.sandboxAvailable === true ? { sandboxAvailable: true } : {}),
4598
+ // 0.7.1 — and judges a justification-gated call with this loop's judge,
4599
+ // writing its verdicts and egress warnings to this loop's audit log.
4600
+ ...(opts.justificationJudge !== undefined
4601
+ ? { justificationJudge: opts.justificationJudge }
4602
+ : {}),
4603
+ ...(opts.justificationAuditSink !== undefined
4604
+ ? { justificationAuditSink: opts.justificationAuditSink }
4605
+ : {}),
4606
+ ...(opts.egressAuditSink !== undefined ? { egressAuditSink: opts.egressAuditSink } : {}),
4607
+ specModels: bridgeSpecModels,
3878
4608
  };
3879
4609
  // Spin "running <tool>…" for exactly the execution window — started after
3880
4610
  // every gate (permission/justification/egress) so it never overlaps the
@@ -3929,10 +4659,14 @@ export async function runChatLoop(opts) {
3929
4659
  ...(toolResultRoot !== undefined ? { rootDir: toolResultRoot } : {}),
3930
4660
  });
3931
4661
  if (stored.persisted) {
3932
- runContext.logger.info("tool result persisted", {
4662
+ // A retried call whose bytes were already on disk wrote nothing.
4663
+ runContext.logger.info(stored.reused === true ? "tool result already persisted" : "tool result persisted", { toolUseId: tu.id, toolName: tu.name, fullPath: stored.fullPath });
4664
+ }
4665
+ else if (stored.unsaved !== undefined) {
4666
+ runContext.logger.warn("tool result could not be persisted; the model sees the preview", {
3933
4667
  toolUseId: tu.id,
3934
4668
  toolName: tu.name,
3935
- fullPath: stored.fullPath,
4669
+ reason: stored.unsaved,
3936
4670
  });
3937
4671
  }
3938
4672
  // Section 18 — post-tool prompt-injection classifier. Runs after the
@@ -4078,10 +4812,12 @@ export async function runChatLoop(opts) {
4078
4812
  return `[${parts.join(", ")}, ${totalChars} chars]`;
4079
4813
  }
4080
4814
  /**
4081
- * Run a list of tool calls honouring the orchestrator's partition:
4082
- * concurrent-safe batches via `Promise.all`, then serial calls one at
4083
- * a time. Results are returned in the original `toolUses` order so
4084
- * they line up with the assistant turn's tool_use blocks.
4815
+ * Run a list of tool calls honouring the orchestrator's partition, group
4816
+ * by group in the order the model issued them: a run of concurrency-safe
4817
+ * calls in parallel (up to `maxConcurrentTools`), every other call alone.
4818
+ * A read issued after a write therefore sees the write. Results are
4819
+ * returned in the original `toolUses` order so they line up with the
4820
+ * assistant turn's tool_use blocks.
4085
4821
  */
4086
4822
  async function runToolBatch(toolUses) {
4087
4823
  // Pass the full catalog so per-call classifiers (Task) can resolve a
@@ -4095,30 +4831,32 @@ export async function runChatLoop(opts) {
4095
4831
  ]);
4096
4832
  const maxConcurrentTools = opts.maxConcurrentTools ?? DEFAULT_MAX_CONCURRENT_TOOLS;
4097
4833
  runContext.logger.debug("tool partition", {
4098
- concurrent: partition.concurrent.map((b) => b.length),
4099
- serial: partition.serial.length,
4834
+ // In order: a number is a concurrent group of that many calls, "S" one
4835
+ // serial call.
4836
+ groups: partition.groups.map((g) => (g.kind === "serial" ? "S" : g.calls.length)),
4100
4837
  maxConcurrentTools,
4101
4838
  });
4102
4839
  // Map each tool_use's identity to its slot in the original order so
4103
4840
  // results can be placed back in order regardless of the
4104
4841
  // concurrent/serial execution shape. `partitionToolCalls` is total —
4105
- // every input block lands in exactly one partition bucket — and
4842
+ // every input block lands in exactly one group — and
4106
4843
  // `executeOneToolUse` always resolves to a result, so every slot is
4107
4844
  // filled; there is no missing-result case to defend against.
4108
4845
  const indexByBlock = new Map();
4109
4846
  toolUses.forEach((tu, idx) => indexByBlock.set(tu, idx));
4110
4847
  const results = new Array(toolUses.length);
4111
- for (const batch of partition.concurrent) {
4112
- const settled = await mapWithConcurrency(batch, maxConcurrentTools, (tu) => executeOneToolUse(tu));
4113
- batch.forEach((tu, i) => {
4848
+ for (const group of partition.groups) {
4849
+ if (group.kind === "serial") {
4850
+ // biome-ignore lint/style/noNonNullAssertion: every block came from toolUses, so its index is registered.
4851
+ results[indexByBlock.get(group.call)] = await executeOneToolUse(group.call);
4852
+ continue;
4853
+ }
4854
+ const settled = await mapWithConcurrency(group.calls, maxConcurrentTools, (tu) => executeOneToolUse(tu));
4855
+ group.calls.forEach((tu, i) => {
4114
4856
  // biome-ignore lint/style/noNonNullAssertion: every block came from toolUses, so its index is registered.
4115
4857
  results[indexByBlock.get(tu)] = settled[i];
4116
4858
  });
4117
4859
  }
4118
- for (const tu of partition.serial) {
4119
- // biome-ignore lint/style/noNonNullAssertion: every block came from toolUses, so its index is registered.
4120
- results[indexByBlock.get(tu)] = await executeOneToolUse(tu);
4121
- }
4122
4860
  return results;
4123
4861
  }
4124
4862
  function evaluateToolLoop() {
@@ -4754,11 +5492,20 @@ export async function runChatLoop(opts) {
4754
5492
  const contextWindow = cfg?.capabilities?.contextWindow ?? table?.contextWindow;
4755
5493
  const maxOutputTokens = cfg?.capabilities?.maxOutputTokens ?? table?.maxOutputTokens;
4756
5494
  const breakerState = c.breaker?.state();
5495
+ const toolLimit = providerToolLimit(c.modelString, process.env);
4757
5496
  return {
4758
5497
  armId: armIdOf(c),
4759
5498
  modelString: c.modelString,
4760
5499
  tags: c.tags,
4761
5500
  ...(breakerState !== undefined ? { breakerState } : {}),
5501
+ ...(toolLimit !== undefined
5502
+ ? {
5503
+ toolLimit: {
5504
+ toolCount: plan.advertisedNames.size,
5505
+ maxTools: toolLimit.maxTools,
5506
+ },
5507
+ }
5508
+ : {}),
4762
5509
  capabilities: {
4763
5510
  features: plan.features,
4764
5511
  ...(contextWindow !== undefined ? { contextWindow } : {}),
@@ -5718,6 +6465,7 @@ export async function runChatLoop(opts) {
5718
6465
  messages,
5719
6466
  adapter: compactionAdapter,
5720
6467
  model: compactionWireModelId,
6468
+ contextLimit,
5721
6469
  snipKeepHead,
5722
6470
  snipKeepTail,
5723
6471
  logger: runContext.logger,
@@ -5732,10 +6480,9 @@ export async function runChatLoop(opts) {
5732
6480
  : {}),
5733
6481
  }).finally(() => out.spinner.stop());
5734
6482
  // §2.3 — persist the summary text alongside the counts (the
5735
- // reactive path always ends in autocompact's [marker, summary]).
5736
- const reactiveSummary = compacted.length === 2 && typeof compacted[1]?.content === "string"
5737
- ? compacted[1].content
5738
- : undefined;
6483
+ // reactive path always ends in autocompact's [marker, summary,
6484
+ // final user turn]; the summary is the second message).
6485
+ const reactiveSummary = summaryTextOf(compacted);
5739
6486
  messages.length = 0;
5740
6487
  messages.push(...compacted);
5741
6488
  await logEvent("compaction", {
@@ -6036,6 +6783,7 @@ export async function runChatLoop(opts) {
6036
6783
  };
6037
6784
  async function runEvaluatedTurn(messages) {
6038
6785
  const evaluation = opts.evaluation;
6786
+ const provability = opts.provability;
6039
6787
  const cascade = resolveCascade();
6040
6788
  const turnStartMs = performance.now();
6041
6789
  // The pre-draft snapshot is a COPY of the messages, not a length: the
@@ -6048,53 +6796,171 @@ export async function runChatLoop(opts) {
6048
6796
  // successful observations so the grade can be stamped on them; without
6049
6797
  // a judge the line count is unchanged and nothing is deferred.
6050
6798
  const deferForGrade = qualityIntoReward && evaluation !== undefined;
6051
- // §6.2 — past the judge share a cascade serves the strong rung DIRECTLY:
6052
- // the draft it cannot afford to grade is not drafted, the judge is not
6053
- // skipped silently — the route reason and the stage cause both say why.
6054
- if (cascade !== undefined && forcedRunCandidate === undefined && judgeShareExhausted()) {
6055
- const served = await runEscalationStage(messages, cascade.target, "judge_share_exhausted", "judge_share_exhausted", true);
6056
- // §6.3 — folded through the same quality gate as every cascade line:
6057
- // the calls are un-judged, so under `in_loop` the strong arm is counted
6058
- // `ungraded` rather than credited a perfect 1.0 for the rest of the
6059
- // run; no strategy line (there is no final quality to fold).
6060
- flushCascade([
6061
- {
6062
- stage: "escalate",
6063
- attributedTo: "escalation",
6064
- observations: served.observations,
6065
- costUsd: served.costUsd,
6066
- },
6067
- ], { success: true }, performance.now() - turnStartMs);
6068
- return served;
6069
- }
6070
- let attempt = forcedRunCandidate !== undefined
6071
- ? await runEscalationStage(messages, forcedRunCandidate, "retry_previous", `forced onto ${armIdOf(forcedRunCandidate)} (forcedCandidate)`, cascade !== undefined || deferForGrade)
6072
- : await runOneTurn(messages, cascade !== undefined
6073
- ? { role: "draft", stage: "draft", strategy: "cascade", defer: true }
6074
- : deferForGrade
6075
- ? { defer: true }
6076
- : {});
6077
- if (evaluation === undefined)
6078
- return attempt;
6799
+ // 0.8.0 (design/0.8.0-provability-release.md §5.1) — provability FIRST
6800
+ // (it is free and deterministic), then the judge (which may spend). Under
6801
+ // `provability:` every attempt this turn produces — the first, an
6802
+ // evaluation retry, a cascade escalation — is verified BEFORE the judge
6803
+ // grades it: a failing verdict retries, halts or escalates without a
6804
+ // judge call, and the judge grades only an answer the gate accepted (or
6805
+ // ran out of retries on). The ladder is the turn's (`runProvableTurn`
6806
+ // opened it); each gate keeps its own `maxRetries`, and both draw on one
6807
+ // `max_escalations`.
6808
+ const ladder = provability === undefined ? undefined : (activeLadder ?? newProvabilityLadder());
6809
+ /** The turn's escalations: the ladder's under `provability:`, so both gates count them. */
6810
+ const turnEscalations = ladder ?? { escalations: 0 };
6811
+ /**
6812
+ * The rung the turn was handed to — by a provability escalation, by the
6813
+ * cascade's, or by the judge share serving the strong rung directly. A
6814
+ * later re-run of THIS turn stays on it instead of going back to the
6815
+ * router (the escalated answer is the one being corrected).
6816
+ */
6817
+ let heldRung;
6818
+ const heldRungTurn = (rung) => ({
6819
+ force: rung,
6820
+ forceReason: `the turn stays on ${armIdOf(rung)}, the rung it was escalated to`,
6821
+ role: "escalation",
6822
+ stage: "escalate",
6823
+ strategy: "cascade",
6824
+ defer: cascade !== undefined || deferForGrade,
6825
+ });
6826
+ /** An attempt handed back to the call site — with its proof footer under `provability:`. */
6827
+ const served = (a) => provability === undefined || ladder === undefined ? a : finishGated(provability, ladder, a);
6079
6828
  /** Fold a non-cascade attempt's deferred lines with the grade it earned (none ⇒ the §6.3 gate). */
6080
6829
  const foldGraded = (a, quality) => {
6081
6830
  for (const { turn, obs } of a.observations) {
6082
6831
  recordPoolOutcome(turn, quality !== undefined ? { ...obs, quality } : obs);
6083
6832
  }
6084
6833
  };
6085
- const maxRetries = Math.max(0, Math.floor(evaluation.maxRetries));
6834
+ // §6.2 — past the judge share a cascade serves the strong rung DIRECTLY:
6835
+ // the draft it cannot afford to grade is not drafted, the judge is not
6836
+ // skipped silently — the route reason and the stage cause both say why.
6837
+ const judgeShareServes = cascade !== undefined && forcedRunCandidate === undefined && judgeShareExhausted();
6838
+ let attempt;
6839
+ if (judgeShareServes && cascade !== undefined) {
6840
+ attempt = await runEscalationStage(messages, cascade.target, "judge_share_exhausted", "judge_share_exhausted", true);
6841
+ heldRung = cascade.target;
6842
+ }
6843
+ else {
6844
+ attempt =
6845
+ forcedRunCandidate !== undefined
6846
+ ? await runEscalationStage(messages, forcedRunCandidate, "retry_previous", `forced onto ${armIdOf(forcedRunCandidate)} (forcedCandidate)`, cascade !== undefined || deferForGrade)
6847
+ : await runOneTurn(messages, cascade !== undefined
6848
+ ? { role: "draft", stage: "draft", strategy: "cascade", defer: true }
6849
+ : deferForGrade
6850
+ ? { defer: true }
6851
+ : {});
6852
+ }
6086
6853
  const stages = [];
6087
6854
  let current;
6088
6855
  if (cascade !== undefined) {
6089
6856
  current = {
6090
- stage: "draft",
6091
- attributedTo: "draft",
6857
+ stage: judgeShareServes ? "escalate" : "draft",
6858
+ attributedTo: judgeShareServes ? "escalation" : "draft",
6092
6859
  observations: attempt.observations,
6093
6860
  costUsd: attempt.costUsd,
6094
6861
  };
6095
6862
  stages.push(current);
6096
6863
  }
6097
- let escalations = 0;
6864
+ /** A provability retry: the turn again, in the lane its current attempt ran in. */
6865
+ const rerunTurn = async () => {
6866
+ if (heldRung !== undefined)
6867
+ return runOneTurn(messages, heldRungTurn(heldRung));
6868
+ if (forcedRunCandidate !== undefined) {
6869
+ return runEscalationStage(messages, forcedRunCandidate, "retry_previous", `forced onto ${armIdOf(forcedRunCandidate)} (forcedCandidate)`, cascade !== undefined || deferForGrade);
6870
+ }
6871
+ if (cascade !== undefined) {
6872
+ return runOneTurn(messages, {
6873
+ role: "draft",
6874
+ stage: "draft",
6875
+ strategy: "cascade",
6876
+ defer: true,
6877
+ });
6878
+ }
6879
+ return runOneTurn(messages, deferForGrade ? { defer: true } : {});
6880
+ };
6881
+ /**
6882
+ * §5.1 — the provability ladder over `attempt`, before any judge call.
6883
+ * `"stands"`: the answer goes on (to the judge, when there is one) — it
6884
+ * passed, failed under `note`, ran out of retries, or had no rung to
6885
+ * escalate to. `"stopped"`: the abort tree stopped the turn while the
6886
+ * gate worked, and the attempt is handed back as it is. A retry or an
6887
+ * escalation re-runs the turn right here; the rejected answer never
6888
+ * reaches the judge, and its deferred routing lines fold ungraded (the
6889
+ * §6.3 gate). A `halt` folds what the turn holds and throws the
6890
+ * classified stop.
6891
+ */
6892
+ const provabilityFirst = async () => {
6893
+ if (provability === undefined || ladder === undefined)
6894
+ return "stands";
6895
+ for (;;) {
6896
+ const step = await provabilityPass(provability, ladder, messages, attempt, current?.stage ?? (heldRung !== undefined ? "escalate" : undefined));
6897
+ if (step.kind === "stopped")
6898
+ return "stopped";
6899
+ if (step.kind === "stands")
6900
+ return step.aborted ? "stopped" : "stands";
6901
+ if (step.kind === "halt") {
6902
+ if (cascade !== undefined) {
6903
+ flushCascade(stages, { success: false }, performance.now() - turnStartMs);
6904
+ }
6905
+ else {
6906
+ foldGraded(attempt);
6907
+ }
6908
+ return haltOnProvability(provability, step);
6909
+ }
6910
+ const rejected = attempt;
6911
+ const rejectedStage = current;
6912
+ ladder.reruns += 1;
6913
+ if (step.kind === "escalate") {
6914
+ turnEscalations.escalations += 1;
6915
+ const escalated = await escalateOnProvability(messages, step, cascade !== undefined || deferForGrade);
6916
+ // The rung unavailable: the verified answer stands with its failing
6917
+ // verdict (note semantics) and goes on to the judge.
6918
+ if (escalated === undefined)
6919
+ return "stands";
6920
+ attempt = escalated;
6921
+ heldRung = step.target;
6922
+ if (cascade !== undefined) {
6923
+ current = {
6924
+ stage: "escalate",
6925
+ attributedTo: "escalation",
6926
+ observations: attempt.observations,
6927
+ costUsd: attempt.costUsd,
6928
+ };
6929
+ stages.push(current);
6930
+ }
6931
+ }
6932
+ else {
6933
+ messages.push(markSynthetic({ role: "user", content: step.nudge }));
6934
+ await logEvent("user_message", { content: step.nudge, synthetic: true });
6935
+ attempt = await rerunTurn();
6936
+ if (current !== undefined)
6937
+ current.costUsd += attempt.costUsd;
6938
+ }
6939
+ // The rejected answer's lines fold ungraded; its stage keeps its
6940
+ // spend (the strategy line counts it) and, on a retry, takes the new
6941
+ // attempt's lines.
6942
+ foldGraded(rejected);
6943
+ if (rejectedStage !== undefined) {
6944
+ rejectedStage.observations = rejectedStage === current ? attempt.observations : [];
6945
+ }
6946
+ }
6947
+ };
6948
+ if (judgeShareServes) {
6949
+ // 0.8.0 §5.1 — what the judge share cannot afford to grade, the free
6950
+ // gate still verifies.
6951
+ await provabilityFirst();
6952
+ // §6.3 — folded through the same quality gate as every cascade line:
6953
+ // the calls are un-judged, so under `in_loop` the strong arm is counted
6954
+ // `ungraded` rather than credited a perfect 1.0 for the rest of the
6955
+ // run; no strategy line (there is no final quality to fold).
6956
+ flushCascade(stages, { success: true }, performance.now() - turnStartMs);
6957
+ return served(attempt);
6958
+ }
6959
+ if (evaluation === undefined) {
6960
+ await provabilityFirst();
6961
+ return served(attempt);
6962
+ }
6963
+ const maxRetries = Math.max(0, Math.floor(evaluation.maxRetries));
6098
6964
  const gradedStages = () => stages.filter((st) => st.score !== undefined);
6099
6965
  for (let retryIndex = 0;; retryIndex += 1) {
6100
6966
  // A turn the abort tree stopped (SIGINT, turn/model-call/run timer)
@@ -6110,7 +6976,19 @@ export async function runChatLoop(opts) {
6110
6976
  else {
6111
6977
  foldGraded(attempt);
6112
6978
  }
6113
- return attempt;
6979
+ return served(attempt);
6980
+ }
6981
+ // 0.8.0 §5.1 — the free gate before the judge: a failing verdict is
6982
+ // retried, escalated or halted here, without a judge call. A stop that
6983
+ // lands while it works hands the attempt back ungraded, as above.
6984
+ if ((await provabilityFirst()) === "stopped") {
6985
+ if (cascade !== undefined) {
6986
+ flushCascade(stages, { success: false }, performance.now() - turnStartMs);
6987
+ }
6988
+ else {
6989
+ foldGraded(attempt);
6990
+ }
6991
+ return served(attempt);
6114
6992
  }
6115
6993
  let graded;
6116
6994
  out.spinner.start("evaluating");
@@ -6152,7 +7030,7 @@ export async function runChatLoop(opts) {
6152
7030
  // strategy line is withheld (see `flushCascade`).
6153
7031
  flushCascade(gradedStages(), { success: true }, performance.now() - turnStartMs);
6154
7032
  }
6155
- return attempt;
7033
+ return served(attempt);
6156
7034
  }
6157
7035
  finally {
6158
7036
  out.spinner.stop();
@@ -6177,7 +7055,7 @@ export async function runChatLoop(opts) {
6177
7055
  const willEscalate = verdict === "fail" &&
6178
7056
  evaluation.onFail === "escalate" &&
6179
7057
  cascade !== undefined &&
6180
- escalations < cascade.maxEscalations;
7058
+ turnEscalations.escalations < cascade.maxEscalations;
6181
7059
  bus.publish({
6182
7060
  ...bus.envelope(),
6183
7061
  kind: "eval_graded",
@@ -6215,11 +7093,11 @@ export async function runChatLoop(opts) {
6215
7093
  return attempt;
6216
7094
  };
6217
7095
  if (verdict === "pass" || evaluation.onFail === "note")
6218
- return standing();
7096
+ return served(standing());
6219
7097
  // `escalate` without a pool has nothing to escalate to (warned once at
6220
7098
  // resolve time): the verdict stands, note semantics.
6221
7099
  if (evaluation.onFail === "escalate" && cascade === undefined)
6222
- return standing();
7100
+ return served(standing());
6223
7101
  const rationaleNote = rationale !== undefined && rationale.trim().length > 0 ? ` — ${rationale.trim()}` : "";
6224
7102
  if (evaluation.onFail === "halt") {
6225
7103
  const detail = `the ${evaluation.graderType} grader scored the final answer ${score.toFixed(2)}, below the required ${evaluation.threshold} threshold${rationaleNote}`;
@@ -6258,9 +7136,9 @@ export async function runChatLoop(opts) {
6258
7136
  outcome: "skipped",
6259
7137
  cause: "max_escalations",
6260
7138
  });
6261
- return standing();
7139
+ return served(standing());
6262
7140
  }
6263
- escalations += 1;
7141
+ turnEscalations.escalations += 1;
6264
7142
  // The transcript as graded — restored should the escalation rung be
6265
7143
  // unavailable (§7.13: the draft answer stands).
6266
7144
  const draftTranscript = messages.slice();
@@ -6301,21 +7179,27 @@ export async function runChatLoop(opts) {
6301
7179
  const message = err instanceof Error ? err.message : String(err);
6302
7180
  runContext.logger.warn("cascade: escalation rung unavailable — the draft answer stands with its failing grade (note semantics)", { escalateTo: cascade.target.modelString, message });
6303
7181
  messages.splice(0, messages.length, ...draftTranscript);
6304
- return standing();
7182
+ return served(standing());
6305
7183
  }
6306
7184
  stage.observations = attempt.observations;
6307
7185
  stage.costUsd = attempt.costUsd;
6308
7186
  stages.push(stage);
6309
7187
  current = stage;
7188
+ // A provability retry of the escalated answer stays on the rung.
7189
+ heldRung = cascade.target;
6310
7190
  continue;
6311
7191
  }
6312
7192
  // onFail: "retry" — bounded by the resolved cap; when spent, the last
6313
7193
  // attempt stands (the failing eval_graded trail tells the story).
6314
7194
  if (retryIndex >= maxRetries)
6315
- return attempt;
7195
+ return served(attempt);
6316
7196
  messages.push(markSynthetic({ role: "user", content: correction }));
6317
7197
  await logEvent("user_message", { content: correction, synthetic: true });
6318
- attempt = await runOneTurn(messages, deferForGrade ? { defer: true } : {});
7198
+ // An answer a provability escalation produced is corrected on its rung.
7199
+ attempt =
7200
+ heldRung !== undefined
7201
+ ? await runOneTurn(messages, heldRungTurn(heldRung))
7202
+ : await runOneTurn(messages, deferForGrade ? { defer: true } : {});
6319
7203
  }
6320
7204
  }
6321
7205
  /**
@@ -6379,7 +7263,9 @@ export async function runChatLoop(opts) {
6379
7263
  const block = { type: "text", text: verdict.text, citations: null };
6380
7264
  messages.push({ role: "assistant", content: [block] });
6381
7265
  await logEvent("assistant_message", { content: [block] });
6382
- out.write(`agent> ${verdict.text}\n`);
7266
+ // §5.4 — printed as the stream prints an answer: no footer-shaped line of
7267
+ // it passes for the gate's verdict under `provability:`.
7268
+ out.write(`agent> ${opts.provability !== undefined ? neutralizeFooterLines(verdict.text) : verdict.text}\n`);
6383
7269
  lastResponseWireModel = verdict.winner.model;
6384
7270
  await recordServedModel(verdict.winner.model);
6385
7271
  publishStage({
@@ -6392,6 +7278,874 @@ export async function runChatLoop(opts) {
6392
7278
  });
6393
7279
  return { terminalContent: [block], usage: verdict.usage };
6394
7280
  }
7281
+ // -------------------------------------------------------------------------
7282
+ // 0.8.0 (design/0.8.0-provability-release.md §5.1, §5.3, §5.4) — the
7283
+ // provability gate. §5.1 orders the two gates: provability FIRST (it is
7284
+ // free and deterministic), then `evaluation:` (which may spend). So the
7285
+ // evaluated turn above runs the ladder on every attempt BEFORE its judge
7286
+ // (`provabilityFirst`): a failing verdict retries, halts or escalates
7287
+ // without a judge call, a re-run the judge asks for is verified again
7288
+ // first, an escalated answer goes on to the judge like any other, and both
7289
+ // gates draw on one `max_escalations`. `runProvableTurn` verifies what no
7290
+ // evaluated turn produced: a committee verdict. The verifier is injected
7291
+ // (`@crewhaus/evaluation-service` builds it); runtime-core only decides what
7292
+ // a verdict does, and builds the fail-open bundle when the verifier throws.
7293
+ // -------------------------------------------------------------------------
7294
+ let warnedProvabilityEscalateWithoutPool = false;
7295
+ /**
7296
+ * §5.1 — `on_fail: escalate`: the roster arm a failing verdict hands the
7297
+ * turn to — `escalateTo` (a spec model string, `$profile` or tag; the
7298
+ * compiler already folded `strategy.cascade.escalate_to` into it, the pool's
7299
+ * own cascade target is the fallback for a hand-wired caller), else the
7300
+ * pool's strongest candidate. Without a pool there is nothing to escalate
7301
+ * to: warned once per run, and the verdict stands (note semantics) — how
7302
+ * `resolveCascade` treats `evaluation.on_fail: escalate`.
7303
+ */
7304
+ const resolveProvabilityEscalation = (provability) => {
7305
+ if (poolRouter === undefined) {
7306
+ if (!warnedProvabilityEscalateWithoutPool) {
7307
+ warnedProvabilityEscalateWithoutPool = true;
7308
+ runContext.logger.warn("provability.on_fail: escalate needs a model_pool to escalate to — no pool is active, so a failing verdict leaves the answer standing (note semantics)");
7309
+ }
7310
+ return undefined;
7311
+ }
7312
+ const declared = provability.escalateTo ?? opts.modelPool?.strategy?.cascade?.escalateTo;
7313
+ const resolved = declared !== undefined ? resolveRosterArm(declared) : undefined;
7314
+ if (declared !== undefined && resolved === undefined) {
7315
+ runContext.logger.warn("provability.escalateTo names no roster arm — escalating to the strongest candidate", { escalateTo: declared });
7316
+ }
7317
+ return resolved ?? poolRouter.escalation();
7318
+ };
7319
+ /** A thrown value's name and message, whatever was thrown. */
7320
+ const describeThrown = (err, fallbackName) => {
7321
+ const errObj = (typeof err === "object" && err !== null ? err : {});
7322
+ return {
7323
+ name: typeof errObj.name === "string" ? errObj.name : fallbackName,
7324
+ message: typeof errObj.message === "string" ? errObj.message : String(err),
7325
+ };
7326
+ };
7327
+ /**
7328
+ * A verifier result is only trusted as a verdict when every field the gate
7329
+ * reads is there and well-typed: the summary the `provability_graded` line,
7330
+ * the event-log twin and the audit record carry (all required fields of
7331
+ * `ProvabilityGradedEvent`), and each claim's `bindings` the halt detail
7332
+ * tallies. Anything less — a bare `{ verdict, claims }`, a NaN score, a
7333
+ * claim without bindings — is not a verdict to act on: it fails open as
7334
+ * `unverified`, exactly like a verifier that threw (a halt on it would
7335
+ * print `undefined/NaN claims` or crash on `claim.bindings`).
7336
+ */
7337
+ const isGradedBundle = (value) => {
7338
+ if (typeof value !== "object" || value === null)
7339
+ return false;
7340
+ const bundle = value;
7341
+ const finite = (v) => typeof v === "number" && Number.isFinite(v);
7342
+ const isObject = (v) => typeof v === "object" && v !== null;
7343
+ return ((bundle.verdict === "pass" || bundle.verdict === "fail" || bundle.verdict === "unverified") &&
7344
+ isProvabilityLevel(bundle.level) &&
7345
+ (bundle.achieved === "none" || isProvabilityLevel(bundle.achieved)) &&
7346
+ finite(bundle.score) &&
7347
+ finite(bundle.threshold) &&
7348
+ finite(bundle.claimCount) &&
7349
+ finite(bundle.met) &&
7350
+ finite(bundle.unmet) &&
7351
+ finite(bundle.assumptions) &&
7352
+ (bundle.assumptionsRefused === undefined || finite(bundle.assumptionsRefused)) &&
7353
+ (bundle.judgeModel === undefined || typeof bundle.judgeModel === "string") &&
7354
+ (bundle.spentUsdMicros === undefined || finite(bundle.spentUsdMicros)) &&
7355
+ typeof bundle.bundleHash === "string" &&
7356
+ Array.isArray(bundle.claims) &&
7357
+ bundle.claims.every((claim) => isObject(claim) &&
7358
+ Array.isArray(claim.bindings) &&
7359
+ claim.bindings.every(isObject)));
7360
+ };
7361
+ /**
7362
+ * §5.1 — the classified terminal stop of `on_fail: halt`, mirroring the
7363
+ * evaluation halt: class `"provability"`, exit {@link EXIT_CODES.provability}.
7364
+ * The detail names the score, every refused assumption and the reasons the
7365
+ * unmet claims fell short (stable `UnmetReason` tokens, tallied), so the
7366
+ * operator reads why without opening the bundle — and where the bundle is.
7367
+ */
7368
+ const provabilityFailureReport = (bundle, bundlePath) => {
7369
+ const counted = Math.max(0, bundle.claimCount - bundle.assumptions);
7370
+ const parts = [
7371
+ `${bundle.met}/${counted} ${counted === 1 ? "claim" : "claims"} met the ${bundle.level} floor (threshold ${bundle.threshold})`,
7372
+ ];
7373
+ const refused = bundle.assumptionsRefused ?? 0;
7374
+ if (refused > 0) {
7375
+ parts.push(`${refused} declared ${refused === 1 ? "assumption was" : "assumptions were"} refused`);
7376
+ }
7377
+ const tally = new Map();
7378
+ for (const claim of bundle.claims) {
7379
+ for (const reason of claimReasons(claim))
7380
+ tally.set(reason, (tally.get(reason) ?? 0) + 1);
7381
+ }
7382
+ if (tally.size > 0) {
7383
+ const reasons = [...tally].map(([reason, n]) => (n > 1 ? `${reason} ×${n}` : reason));
7384
+ parts.push(`unmet: ${reasons.join(", ")}`);
7385
+ }
7386
+ if (bundlePath !== undefined)
7387
+ parts.push(`proof bundle: ${bundlePath}`);
7388
+ return {
7389
+ class: "provability",
7390
+ title: "provability gate failed",
7391
+ detail: parts.join("; "),
7392
+ remediation: "cite the evidence each claim rests on, lower provability.threshold, or soften provability.on_fail to retry/note",
7393
+ exitCode: EXIT_CODES.provability,
7394
+ };
7395
+ };
7396
+ const newProvabilityLadder = () => ({
7397
+ passes: 0,
7398
+ reruns: 0,
7399
+ escalations: 0,
7400
+ });
7401
+ /**
7402
+ * The ladder of the turn in flight: `runProvableTurn` opens it, and an
7403
+ * evaluated turn inside verifies its attempts against the same one, so a
7404
+ * committee verdict's retry that falls back to the evaluated turn does not
7405
+ * start the counts over.
7406
+ */
7407
+ let activeLadder;
7408
+ /** A non-finite cap would make the retry ladder unbounded; 0 is the only safe reading of a value nobody meant. */
7409
+ const provabilityRetryCap = (provability) => Number.isFinite(provability.maxRetries) ? Math.max(0, Math.floor(provability.maxRetries)) : 0;
7410
+ /**
7411
+ * §5.1 — the escalations one turn may make: the evaluation cascade's
7412
+ * `max_escalations` when there is a cascade (both gates draw on it), else
7413
+ * the pool's own (`strategy.max_escalations`, default 1). A non-finite
7414
+ * value reads as 0, as the retry cap does.
7415
+ */
7416
+ const turnEscalationCap = () => {
7417
+ const cap = resolveCascade()?.maxEscalations ?? Math.floor(opts.modelPool?.strategy?.maxEscalations ?? 1);
7418
+ return Number.isFinite(cap) ? Math.max(0, cap) : 0;
7419
+ };
7420
+ /**
7421
+ * §5.3, §8 — a bundle path as the run's LIVE surfaces show it (the trace
7422
+ * event a `runs.subscribe` stream carries, the halt detail a gateway
7423
+ * returns): through the gate's display rule, the footer's (relative to
7424
+ * the tenant's root inside a tenant scope, else the workspace), so a
7425
+ * tenant is never told the server's directory layout above its root. The
7426
+ * durable event-log line keeps the path as persisted. No rule → as given;
7427
+ * a rule that throws → no path at all.
7428
+ */
7429
+ const shownBundlePath = (provability, bundlePath) => {
7430
+ if (bundlePath === undefined || provability.displayPath === undefined)
7431
+ return bundlePath;
7432
+ try {
7433
+ const shown = provability.displayPath(bundlePath);
7434
+ return typeof shown === "string" && shown.length > 0 ? shown : undefined;
7435
+ }
7436
+ catch (err) {
7437
+ runContext.logger.warn("provability: showing the bundle path failed — it is left out", {
7438
+ message: describeThrown(err, "Error").message,
7439
+ });
7440
+ return undefined;
7441
+ }
7442
+ };
7443
+ /** The standing pass's rendering, or undefined (`render: none`, no renderer, empty). */
7444
+ const renderStanding = (provability, bundle, bundlePath) => {
7445
+ if (provability.render === "none" || provability.renderBundle === undefined)
7446
+ return undefined;
7447
+ let rendered;
7448
+ try {
7449
+ rendered = provability.renderBundle(bundle, bundlePath);
7450
+ }
7451
+ catch (err) {
7452
+ runContext.logger.warn("provability: rendering the proof bundle failed — no footer", {
7453
+ message: describeThrown(err, "Error").message,
7454
+ });
7455
+ return undefined;
7456
+ }
7457
+ // trimEnd, not a regex: a footer is printed on its own line, and a
7458
+ // `\s+$` pattern backtracks quadratically over a long whitespace run.
7459
+ const trimmed = typeof rendered === "string" ? rendered.trimEnd() : "";
7460
+ return trimmed.length > 0 ? trimmed : undefined;
7461
+ };
7462
+ /**
7463
+ * §5.4 — does the reader read this turn as it streams? The REPL prints
7464
+ * every attempt as it is made, and so does any run whose footer goes to the
7465
+ * stream (the cli); a run that hands its text back (`"reply"` on a channel
7466
+ * bot, `"none"` on the gateway) serves the final answer alone, and its
7467
+ * output is an operator's log.
7468
+ */
7469
+ const streamsTheTurn = (provability) => provability.streamed ??
7470
+ (opts.singleTurn !== true || (provability.footerTarget ?? "stream") === "stream");
7471
+ /**
7472
+ * The text the turn in flight has printed so far, as the gate grades it in
7473
+ * a claimless final message's place: every assistant message's text since
7474
+ * the turn's own input — the last user message that is neither
7475
+ * runtime-injected (a retry nudge, a correction) nor a tool result — and
7476
+ * since the last attempt a failing pass graded (`rejectedThrough`), joined
7477
+ * as paragraphs. A rejected attempt was graded once, and where it
7478
+ * streamed its ✗ is already under it: grading it again would fail every
7479
+ * honest retraction after it ("I'm not able to confirm that."), unless
7480
+ * the final message points back at it (`POINTS_BACK`: "See above."),
7481
+ * when it is the answer the reader is handed again. In the messages
7482
+ * before the final one, a sentence that only says what the agent is about
7483
+ * to do (`NARRATION`: "Let me fetch the policy page first.") is no claim
7484
+ * the reader was handed, and is left out.
7485
+ *
7486
+ * The final message is the transcript's last one. An empty one is still
7487
+ * final: a model that ends its turn on an empty `end_turn` after a tool
7488
+ * call commits no message at all (the last is the tool results' carrier),
7489
+ * or a blank text block. Either way every assistant message before it
7490
+ * printed ahead of a tool call, and is read for narration — never graded
7491
+ * whole as though it were the answer (I11).
7492
+ */
7493
+ const streamedTurnText = (messages, rejectedThrough) => {
7494
+ const texts = [];
7495
+ let pointsBack = false;
7496
+ /** The turn's own input: a figure the reader handed the agent is no claim of the agent's. */
7497
+ const input = latestHumanUserMessage(messages);
7498
+ const handed = figuresIn(input !== undefined ? messageText(input) : "");
7499
+ for (let i = messages.length - 1; i >= 0; i -= 1) {
7500
+ const message = messages[i];
7501
+ if (message === rejectedThrough && !pointsBack)
7502
+ break;
7503
+ if (message.role === "user") {
7504
+ const carriesResults = Array.isArray(message.content) &&
7505
+ message.content.some((block) => block.type === "tool_result");
7506
+ if (!isSyntheticMessage(message) && !carriesResults)
7507
+ break;
7508
+ continue;
7509
+ }
7510
+ const blocks = typeof message.content === "string" ? [] : message.content;
7511
+ const text = typeof message.content === "string"
7512
+ ? message.content
7513
+ : blocks
7514
+ .filter((block) => block.type === "text")
7515
+ .map((block) => block.text)
7516
+ .join("");
7517
+ if (i === messages.length - 1) {
7518
+ pointsBack = POINTS_BACK.test(text);
7519
+ if (text.trim() !== "")
7520
+ texts.unshift(text);
7521
+ continue;
7522
+ }
7523
+ if (text.trim() === "")
7524
+ continue;
7525
+ // What the narration announces: the input of the calls this message makes.
7526
+ const calls = new Set();
7527
+ for (const block of blocks) {
7528
+ if (block.type === "tool_use")
7529
+ callFigures(block.input, calls);
7530
+ }
7531
+ const said = withoutNarration(text, [handed, calls]);
7532
+ if (said !== "")
7533
+ texts.unshift(said);
7534
+ }
7535
+ return texts.join("\n\n");
7536
+ };
7537
+ /**
7538
+ * §5.4 — a failing pass the gate is about to re-run: where the reader has
7539
+ * already seen the rejected attempt stream past (`streamsTheTurn`, a
7540
+ * footer that goes to the output), its ✗ footer is written under it now,
7541
+ * so no answer the reader saw stands unmarked above the next one. The
7542
+ * standing pass renders as before; this bundle is never rendered twice
7543
+ * (`ladder.marked`).
7544
+ */
7545
+ const markRejected = (provability, ladder, bundle, bundlePath) => {
7546
+ const target = provability.footerTarget ?? "stream";
7547
+ if (target === "none" || !streamsTheTurn(provability))
7548
+ return;
7549
+ const footer = renderStanding(provability, bundle, bundlePath);
7550
+ if (footer === undefined)
7551
+ return;
7552
+ out.write(`${footer}\n`);
7553
+ ladder.marked = bundle;
7554
+ };
7555
+ /** The retry nudge; a composer that throws or says nothing still leaves the verdict. */
7556
+ const composeNudge = (provability, bundle) => {
7557
+ try {
7558
+ const nudge = provability.nudge(bundle);
7559
+ if (typeof nudge === "string" && nudge.trim().length > 0)
7560
+ return nudge;
7561
+ }
7562
+ catch (err) {
7563
+ runContext.logger.warn("provability: composing the retry nudge failed — nudging with the score alone", {
7564
+ message: describeThrown(err, "Error").message,
7565
+ });
7566
+ }
7567
+ const counted = Math.max(0, bundle.claimCount - bundle.assumptions);
7568
+ return `[provability failed: ${bundle.met}/${counted} claims met the ${bundle.level} floor, threshold ${bundle.threshold}]\nCite the evidence each claim rests on, then give the corrected answer in full.`;
7569
+ };
7570
+ /**
7571
+ * Whether the abort tree has stopped this turn. A stopped turn did not
7572
+ * complete inside its window: it is never retried or escalated, and a
7573
+ * verdict that had not settled when it stopped is discarded (the turn
7574
+ * stands un-verified). When a fired wall-clock limit is what stopped it, the stop
7575
+ * is classified exactly as `runOneTurn` classifies one (G10): terminal
7576
+ * for the run deadline in any mode and for every limit on the
7577
+ * single-turn path (the turn IS the run) — `throwTimeout`, class
7578
+ * `"timeout"` — so neither a slow verifier nor a slow evaluation judge
7579
+ * can turn a timed-out run into a served, un-verified answer, and
7580
+ * `on_fail: halt` cannot be skipped by running out the clock. A REPL
7581
+ * turn/model-call timeout, a SIGINT or a host abort is not terminal: the
7582
+ * caller hands the turn back. `firedInGate` — the abort landed during
7583
+ * the gate's own work, where no `runOneTurn` was running to write the
7584
+ * REPL's named timeout `error` line, so the gate writes it.
7585
+ */
7586
+ const stoppedByAbort = async (firedInGate) => {
7587
+ if (!turnAbort.signal.aborted && !runAbort.signal.aborted)
7588
+ return false;
7589
+ const timedOut = timeoutAbortReason(turnAbort.signal) ?? timeoutAbortReason(runAbort.signal);
7590
+ if (timedOut !== undefined) {
7591
+ if (timedOut.crewhausTimeout === "run" || opts.singleTurn === true) {
7592
+ await throwTimeout(timedOut);
7593
+ }
7594
+ if (firedInGate) {
7595
+ await logEvent("error", {
7596
+ name: timedOut.crewhausTimeout === "turn" ? "TurnTimeout" : "ModelCallTimeout",
7597
+ message: `turn aborted: the configured ${TIMEOUT_SPEC_KEYS[timedOut.crewhausTimeout]} (${timedOut.limitMs}ms) elapsed`,
7598
+ });
7599
+ }
7600
+ }
7601
+ return true;
7602
+ };
7603
+ /**
7604
+ * Did the OUTSIDE WORLD hand the run `url` whole, and nothing else put the
7605
+ * tagged content it carries there? Only then does a HEAD to it carry
7606
+ * nothing new back, and a lineage match on it is let through (§6.1, §10;
7607
+ * Pillar 3). `egress` is what the screen's classification found. Both must
7608
+ * hold:
7609
+ *
7610
+ * 1. a non-error result of an OUTSIDE READER holds the URL verbatim — a
7611
+ * tool that crosses the network (`ioCapability: "network"`) and writes
7612
+ * nothing (`readOnly`), or an MCP server (`mcp__*`, whose flags a spec
7613
+ * can only tighten, so none is ever `readOnly`): a search hit, a
7614
+ * fetched page's own address, an MCP server's answer. Its request
7615
+ * passed the egress fabric, and its answer is the outside world's.
7616
+ * `scope` is no test of that: a
7617
+ * local process tool is `external` too (GitCommit, GitDiff, Bash,
7618
+ * Format), and its result is text the model wrote — a commit message,
7619
+ * the diff of a file it edited — so a secret the model composed into a
7620
+ * URL comes back "handed" (the laundering the round-2 review found
7621
+ * through GitCommit, as round 1's did through UrlNormalize). A tool
7622
+ * that writes can echo what it sent, wherever it sent it;
7623
+ * 2. every tagged string the URL carries came in only inside results that
7624
+ * hand the URL whole: no other tool result holds it, and it was tagged
7625
+ * as a tool's or an MCP server's answer. A secret a tool read sits in
7626
+ * that tool's result without the URL, so a reader that hands back a
7627
+ * file or a record the model wrote the URL into (an MCP filesystem
7628
+ * read) still hands nothing new: the secret came from elsewhere.
7629
+ * Content tagged from memory, a skill, a channel, a sub-agent or a
7630
+ * consult is never excused, and nor is a match the plain substring
7631
+ * reading cannot account for (a decoded view's, a custom matcher's).
7632
+ */
7633
+ const handedByBoundary = (messages, url, egress) => {
7634
+ const readerCall = new Map();
7635
+ const results = [];
7636
+ for (const message of messages) {
7637
+ if (!Array.isArray(message.content))
7638
+ continue;
7639
+ for (const block of message.content) {
7640
+ if (typeof block !== "object" || block === null)
7641
+ continue;
7642
+ const b = block;
7643
+ if (b["type"] === "tool_use" && typeof b["id"] === "string") {
7644
+ const name = typeof b["name"] === "string" ? b["name"] : "";
7645
+ const tool = toolByName.get(name);
7646
+ // An MCP server's answer is the outside world's whatever its flags
7647
+ // say: a spec's MCP tool is never `readOnly` (its flags can only
7648
+ // tighten), so reading it by the flag counted no search hit an MCP
7649
+ // server returned. Condition 2 is what refuses a server that echoes
7650
+ // what the model wrote. A local process tool never hands anything.
7651
+ const outside = tool?.ioCapability !== "process" &&
7652
+ (name.startsWith("mcp__") ||
7653
+ (tool?.readOnly === true && tool.ioCapability === "network"));
7654
+ readerCall.set(b["id"], outside);
7655
+ }
7656
+ else if (b["type"] === "tool_result" && typeof b["tool_use_id"] === "string") {
7657
+ const text = gateResultText(b["content"]);
7658
+ const reader = readerCall.get(b["tool_use_id"]) === true && b["is_error"] !== true;
7659
+ results.push({ text, handed: reader && text.includes(url) });
7660
+ }
7661
+ }
7662
+ }
7663
+ // 1 — handed whole by an outside reader.
7664
+ if (!results.some((r) => r.handed))
7665
+ return false;
7666
+ // 2 — what the URL carries, as the plain substring reading finds it.
7667
+ const carried = [];
7668
+ let found = 0;
7669
+ for (const [tagged, origin] of runContext.dataLineage ?? []) {
7670
+ if (tagged.length < MIN_MATCH_LENGTH || !url.includes(tagged))
7671
+ continue;
7672
+ found += 1;
7673
+ if (origin === "user")
7674
+ continue;
7675
+ if (origin !== "tool" && origin !== "mcp")
7676
+ return false;
7677
+ carried.push(tagged);
7678
+ }
7679
+ if (carried.length === 0 || egress.matchCount > found)
7680
+ return false;
7681
+ return carried.every((tagged) => results.some((r) => r.handed && r.text.includes(tagged)) &&
7682
+ results.every((r) => r.handed || !r.text.includes(tagged)));
7683
+ };
7684
+ /**
7685
+ * Pillar 3 sink-side fabric (design §6.1, §10) — the gate's own egress:
7686
+ * a `sources.resolve: head` request to a URL the model wrote. It is
7687
+ * classified like an external tool call to a destination the model chose
7688
+ * (`external-dynamic`, the run's egress matcher): content a boundary
7689
+ * tagged from a non-user origin — a secret a tool read — refuses the
7690
+ * request, and the verifier sends nothing. One `permission_decision`
7691
+ * trace event per screen, as on the tool path; the durable
7692
+ * `egress_decision` record is the verifier's, which also knows what the
7693
+ * request came to. A URL an outside reader's result handed the run
7694
+ * VERBATIM (a search hit, a fetched page's own address), carrying nothing
7695
+ * that reached the run any other way ({@link handedByBoundary}), carries
7696
+ * nothing new back to its host, so a match on it is let through, and the
7697
+ * event says why: refusing it would fail an honest citation of a search
7698
+ * result. Built per verification over the transcript it reads.
7699
+ */
7700
+ const gateEgressScreen = (messages) => async (payload, sinkId) => {
7701
+ const egress = await classifyEgress(payload, runContext, {
7702
+ sinkId,
7703
+ sinkScope: "external-dynamic",
7704
+ ...(opts.egressMatcher !== undefined ? { matcher: opts.egressMatcher } : {}),
7705
+ });
7706
+ const handed = egress.verdict === "block" && handedByBoundary(messages, payload, egress);
7707
+ const verdict = handed ? "pass" : egress.verdict;
7708
+ bus.publish({
7709
+ ...bus.envelope(),
7710
+ kind: "permission_decision",
7711
+ toolName: sinkId,
7712
+ decision: verdict === "block" ? "deny" : "allow",
7713
+ mode: permissionMode,
7714
+ outcome: verdict === "pass"
7715
+ ? "egress-passed"
7716
+ : verdict === "warn"
7717
+ ? "egress-warned"
7718
+ : "egress-blocked",
7719
+ ...(egress.originsFound.length > 0
7720
+ ? {
7721
+ reason: handed
7722
+ ? `egress: the URL was handed to the run verbatim (${summarizeEgress(egress)})`
7723
+ : `egress: ${summarizeEgress(egress)}`,
7724
+ }
7725
+ : {}),
7726
+ });
7727
+ if (verdict !== "pass") {
7728
+ runContext.logger.warn("egress classification non-clean", {
7729
+ sinkId,
7730
+ verdict,
7731
+ originsFound: egress.originsFound,
7732
+ matchCount: egress.matchCount,
7733
+ });
7734
+ }
7735
+ return {
7736
+ verdict,
7737
+ sinkScope: egress.sinkScope,
7738
+ originsFound: egress.originsFound,
7739
+ matchCount: egress.matchCount,
7740
+ };
7741
+ };
7742
+ /**
7743
+ * 0.8.0 (design §5.1, §5.3) — ONE verification pass over a completed
7744
+ * attempt, recorded, and what its verdict asks for. The caller acts on the
7745
+ * step: it owns the attempt, the transcript and the routing lines a re-run
7746
+ * touches.
7747
+ *
7748
+ * 1. a turn the abort tree stopped did not complete — it is handed back
7749
+ * un-verified, exactly as the evaluation loop hands one back
7750
+ * un-graded, unless a fired wall-clock limit makes the stop terminal
7751
+ * (G10: the run deadline anywhere, any limit on the single-turn path),
7752
+ * which throws the classified `timeout` stop as `runOneTurn` does. The
7753
+ * same check runs again when `verify` settles and once the pass is
7754
+ * recorded, so a limit that fires WHILE the gate works is classified
7755
+ * too;
7756
+ * 2. `verify` — a THROW is grading-infrastructure failure, not a verdict:
7757
+ * logged (a warning + an `error` event-log line), and the bundle is
7758
+ * `unverifiedBundle(…)` so no surface prints a ✓; the answer stands;
7759
+ * 3. `persist` (failure warned, never fatal), under the SESSION's turn
7760
+ * number (`resumedTurns` + the run's own), so a resumed session's turn
7761
+ * never files over an earlier turn's bundle (§5.3);
7762
+ * 4. one `provability_graded` trace event + event-log line, the
7763
+ * `provability_evaluated` audit record when the sink is wired, and
7764
+ * `onBundle`;
7765
+ * 5. the verdict: pass / unverified / `note` → stands; `halt` → the
7766
+ * caller's classified stop; `retry` → the nudge composed from the
7767
+ * bundle, for the caller to re-run the turn with; `escalate` → the same
7768
+ * nudge and the rung (an unavailable rung leaves the answer standing,
7769
+ * note semantics; a rung the abort tree stopped before it ran is
7770
+ * recorded as `model_stage{escalate, skipped, cause: "aborted"}`, and
7771
+ * is named `escalatedTo` only when that announcement went out before
7772
+ * the stop; a turn that already made `max_escalations` escalations is
7773
+ * recorded as `skipped, cause: "max_escalations"`, as the cascade's
7774
+ * is). Both re-runs count against `maxRetries`; spent, the last answer
7775
+ * stands and the failing event trail tells the story.
7776
+ */
7777
+ async function provabilityPass(provability, ladder, messages, attempt, stage) {
7778
+ const maxRetries = provabilityRetryCap(provability);
7779
+ // 1 — an aborted turn never completed: verifying its partial output
7780
+ // would be noise, and a retry would fight the very signal that stopped
7781
+ // it. The stop landed in the turn (whose `runOneTurn` writes the REPL's
7782
+ // timeout line when it fired there), not in the gate.
7783
+ if (await stoppedByAbort(false))
7784
+ return { kind: "stopped" };
7785
+ const retryIndex = ladder.passes;
7786
+ const turnNumber = resumedTurns + runContext.turnNumber;
7787
+ const servedModel = attempt.servedModel ?? lastResponseWireModel;
7788
+ // 2 — verify.
7789
+ let verified;
7790
+ let verifyFailure;
7791
+ const finalText = terminalText(attempt.terminalContent);
7792
+ const verifyText = (text) => provability.verify({
7793
+ finalText: text,
7794
+ messages,
7795
+ isSynthetic: isSyntheticMessage,
7796
+ usage: attempt.usage,
7797
+ // A waiver judge meters itself on THIS bus (role "judge"), so its
7798
+ // spend lands in the run's budget like the quality judge's.
7799
+ bus,
7800
+ ...(servedModel !== undefined ? { servedModel } : {}),
7801
+ ...(attempt.profile !== undefined ? { profile: attempt.profile } : {}),
7802
+ ...(stage !== undefined ? { stage } : {}),
7803
+ turnNumber,
7804
+ retryIndex,
7805
+ // The session whose event log holds the evidence — on `--resume`
7806
+ // the resumed one. The loop's resolved id: boot binds the run
7807
+ // context to it (a caller-built context naming another session is
7808
+ // refused), so this always equals `runContext.sessionId`.
7809
+ sessionId,
7810
+ signal: turnAbort.signal,
7811
+ // The waiver judge stops asking once the share is spent (§6.2), and
7812
+ // a HEAD the verifier sends is screened and audited like any egress
7813
+ // (§6.1, §10).
7814
+ ...(opts.budget !== undefined ? { judgeShareExhausted } : {}),
7815
+ ...(opts.egressAuditSink !== undefined ? { egressAuditSink: opts.egressAuditSink } : {}),
7816
+ screenEgress: gateEgressScreen(messages),
7817
+ });
7818
+ out.spinner.start("verifying");
7819
+ try {
7820
+ verified = await verifyText(finalText);
7821
+ // §5.4 — where the turn streams to its reader, a final message that
7822
+ // states nothing ("Done.", "See above.") is not the answer the reader
7823
+ // holds: what the turn printed above it is. Its vacuous pass would put
7824
+ // a ✓ under claims nobody graded — a claim made before a tool call, a
7825
+ // rejected attempt the next one points back at — so that text is
7826
+ // graded instead. A final message that makes a claim is the answer,
7827
+ // graded alone, as on every surface.
7828
+ const shown = streamsTheTurn(provability)
7829
+ ? streamedTurnText(messages, ladder.rejectedThrough)
7830
+ : undefined;
7831
+ if (shown !== undefined &&
7832
+ shown.trim() !== "" &&
7833
+ shown !== finalText &&
7834
+ isGradedBundle(verified) &&
7835
+ verified.verdict === "pass" &&
7836
+ verified.claimCount === 0) {
7837
+ verified = await verifyText(shown);
7838
+ }
7839
+ }
7840
+ catch (err) {
7841
+ verifyFailure = { error: err };
7842
+ }
7843
+ finally {
7844
+ out.spinner.stop();
7845
+ }
7846
+ // A verdict — or a throw — that settles after the abort tree fired
7847
+ // belongs to a turn that did not complete inside its window. It is
7848
+ // neither recorded nor acted on: a verifier that ignores the signal
7849
+ // would otherwise retry an aborted turn (a nudge nothing answers) or
7850
+ // reclassify a timed-out run as a provability halt, and a verifier
7851
+ // that stopped BECAUSE of the abort is the abort, not an outage.
7852
+ if (await stoppedByAbort(true))
7853
+ return { kind: "stopped" };
7854
+ ladder.passes += 1;
7855
+ let bundle;
7856
+ if (verifyFailure === undefined && isGradedBundle(verified)) {
7857
+ bundle = verified;
7858
+ }
7859
+ else {
7860
+ // A THROW — or a result that is not a well-formed bundle — is
7861
+ // grading-INFRASTRUCTURE failure, not a verdict: fail open.
7862
+ const err = verifyFailure !== undefined
7863
+ ? verifyFailure.error
7864
+ : new Error("the verifier returned no proof bundle");
7865
+ const { name, message } = describeThrown(err, "ProvabilityError");
7866
+ runContext.logger.warn("provability: verifier threw — the answer stands unverified", {
7867
+ name,
7868
+ message,
7869
+ });
7870
+ await logEvent("error", { name, message: `provability verifier failed: ${message}` });
7871
+ bundle = unverifiedBundle(provability, err, retryIndex);
7872
+ }
7873
+ // 3 — persist.
7874
+ let bundlePath;
7875
+ if (provability.persist !== undefined) {
7876
+ try {
7877
+ bundlePath = await provability.persist(bundle, { sessionId, turnNumber });
7878
+ }
7879
+ catch (err) {
7880
+ runContext.logger.warn("provability: persisting the proof bundle failed — the verdict stands", {
7881
+ turnNumber,
7882
+ retryIndex,
7883
+ message: describeThrown(err, "Error").message,
7884
+ });
7885
+ }
7886
+ }
7887
+ // Decided BEFORE the publish so a failing pass names the rung it hands
7888
+ // the turn to (`escalatedTo`), as the evaluation cascade's does.
7889
+ const failing = bundle.verdict === "fail";
7890
+ // What this pass graded is graded: a later claimless message's streamed
7891
+ // text starts after it (`streamedTurnText`).
7892
+ if (failing)
7893
+ ladder.rejectedThrough = messages[messages.length - 1];
7894
+ const spent = ladder.reruns >= maxRetries;
7895
+ if (failing && provability.onFail === "escalate" && ladder.escalation === undefined) {
7896
+ ladder.escalation = { target: resolveProvabilityEscalation(provability) };
7897
+ }
7898
+ const rung = failing && provability.onFail === "escalate" && !spent
7899
+ ? ladder.escalation?.target
7900
+ : undefined;
7901
+ // §5.1 — `escalate` shares the cascade's `max_escalations`: a turn that
7902
+ // has made them all keeps its answer, as the cascade's last rung does.
7903
+ const capped = rung !== undefined && ladder.escalations >= turnEscalationCap();
7904
+ /** The rung this failing pass hands the turn to, the abort tree aside. */
7905
+ const wantedRung = capped ? undefined : rung;
7906
+ // Announced only while the abort tree is quiet: a timer that fired
7907
+ // while the bundle was persisted means the rung will never run (the
7908
+ // abort check below returns or throws first), and the durable line must
7909
+ // not name an escalation that did not happen.
7910
+ const escalateTo = wantedRung !== undefined && !turnAbort.signal.aborted && !runAbort.signal.aborted
7911
+ ? wantedRung
7912
+ : undefined;
7913
+ // 4 — publish. The gate's own pass counter is authoritative for
7914
+ // `retryIndex` (a verifier that ignores the one it was handed cannot
7915
+ // make two passes read as the original answer).
7916
+ const summary = { ...summarizeBundle(bundle), retryIndex };
7917
+ const shownPath = shownBundlePath(provability, bundlePath);
7918
+ bus.publish({
7919
+ ...bus.envelope(),
7920
+ kind: "provability_graded",
7921
+ ...summary,
7922
+ maxRetries,
7923
+ ...(shownPath !== undefined ? { bundlePath: shownPath } : {}),
7924
+ ...(escalateTo !== undefined ? { escalatedTo: escalateTo.modelString } : {}),
7925
+ });
7926
+ // The durable twin (event-log kind `provability_graded`): the trace
7927
+ // line minus its envelope, plus the session turn it graded, with the
7928
+ // bundle path as persisted.
7929
+ await logEvent("provability_graded", {
7930
+ ...summary,
7931
+ maxRetries,
7932
+ turnNumber,
7933
+ ...(bundlePath !== undefined ? { bundlePath } : {}),
7934
+ ...(escalateTo !== undefined ? { escalatedTo: escalateTo.modelString } : {}),
7935
+ });
7936
+ // §5.3 — the hash-chained audit record beside the justification gate's,
7937
+ // best-effort but surfaced exactly like that path: a full audit disk
7938
+ // must not crash a governed run.
7939
+ if (opts.justificationAuditSink !== undefined) {
7940
+ try {
7941
+ await opts.justificationAuditSink.append({
7942
+ kind: "provability_evaluated",
7943
+ payload: { ...summary, turnNumber, sessionId },
7944
+ });
7945
+ }
7946
+ catch (err) {
7947
+ runContext.logger.warn("provability audit append failed", {
7948
+ turnNumber,
7949
+ retryIndex,
7950
+ error: describeThrown(err, "Error").message,
7951
+ });
7952
+ }
7953
+ }
7954
+ if (provability.onBundle !== undefined) {
7955
+ try {
7956
+ provability.onBundle(bundle, bundlePath);
7957
+ }
7958
+ catch (err) {
7959
+ runContext.logger.warn("provability: the onBundle observer threw — ignored", {
7960
+ message: describeThrown(err, "Error").message,
7961
+ });
7962
+ }
7963
+ }
7964
+ // A rung the recorded failing pass wanted but the abort tree stopped
7965
+ // first never runs: say so on the routing record, as the cascade's
7966
+ // `max_escalations` skip does — before the abort check below can throw.
7967
+ // When the abort landed during the event-log line or the audit append
7968
+ // this also retracts the `escalatedTo` those lines already carry; a
7969
+ // `model_stage{started}` or this `skipped` always follows one.
7970
+ if (wantedRung !== undefined && (turnAbort.signal.aborted || runAbort.signal.aborted)) {
7971
+ publishStage({
7972
+ stage: "escalate",
7973
+ strategy: "cascade",
7974
+ role: "escalation",
7975
+ candidate: wantedRung,
7976
+ outcome: "skipped",
7977
+ cause: "aborted",
7978
+ });
7979
+ }
7980
+ if (capped && rung !== undefined) {
7981
+ publishStage({
7982
+ stage: "escalate",
7983
+ strategy: "cascade",
7984
+ role: "escalation",
7985
+ candidate: rung,
7986
+ outcome: "skipped",
7987
+ cause: "max_escalations",
7988
+ });
7989
+ }
7990
+ // 5 — the verdict. A stop that landed while the pass was being
7991
+ // recorded (persist, the event-log line, the audit append): a terminal
7992
+ // timeout throws here whatever the verdict; any other abort leaves the
7993
+ // recorded verdict standing but never re-runs the turn on a signal
7994
+ // that is already aborted.
7995
+ const stopped = await stoppedByAbort(true);
7996
+ ladder.standing = { attempt, bundle, ...(bundlePath !== undefined ? { bundlePath } : {}) };
7997
+ if (!failing || provability.onFail === "note")
7998
+ return { kind: "stands", aborted: stopped };
7999
+ if (provability.onFail === "halt") {
8000
+ return { kind: "halt", bundle, ...(bundlePath !== undefined ? { bundlePath } : {}) };
8001
+ }
8002
+ // `escalate` without a pool (warned once at resolve time): note semantics.
8003
+ if (provability.onFail === "escalate" && ladder.escalation?.target === undefined) {
8004
+ return { kind: "stands", aborted: stopped };
8005
+ }
8006
+ if (spent || stopped || capped)
8007
+ return { kind: "stands", aborted: stopped };
8008
+ const nudge = composeNudge(provability, bundle);
8009
+ markRejected(provability, ladder, bundle, bundlePath);
8010
+ if (escalateTo !== undefined)
8011
+ return { kind: "escalate", nudge, target: escalateTo };
8012
+ return { kind: "retry", nudge };
8013
+ }
8014
+ /**
8015
+ * §5.1 — the classified terminal stop of `on_fail: halt` (class
8016
+ * `"provability"`, exit {@link EXIT_CODES.provability}), the ✗ footer
8017
+ * first: a halted run returns no reply to carry it, so it goes to the
8018
+ * output whatever `footerTarget` says — unless the caller carries the
8019
+ * bundle itself (`"none"`). The detail names the bundle the way the
8020
+ * run's live surfaces show it.
8021
+ */
8022
+ const haltOnProvability = async (provability, halted) => {
8023
+ const report = provabilityFailureReport(halted.bundle, shownBundlePath(provability, halted.bundlePath));
8024
+ if ((provability.footerTarget ?? "stream") !== "none") {
8025
+ const footer = renderStanding(provability, halted.bundle, halted.bundlePath);
8026
+ if (footer !== undefined)
8027
+ out.write(`${footer}\n`);
8028
+ }
8029
+ await publishRunFailed(report);
8030
+ throw new RunFailedError(report);
8031
+ };
8032
+ /**
8033
+ * §5.1 — `escalate`: the nudge, then the turn on the rung (`defer` as the
8034
+ * caller folds the attempt's routing lines). An unavailable rung leaves
8035
+ * the answer standing with its failing verdict (note semantics) and
8036
+ * withdraws the nudge from the live transcript: `undefined`. A classified
8037
+ * halt or an abort on the rung is terminal for the RUN and propagates, as
8038
+ * it does out of the cascade.
8039
+ */
8040
+ const escalateOnProvability = async (messages, step, defer) => {
8041
+ // The transcript as verified — restored should the rung be unavailable.
8042
+ const verifiedTranscript = messages.slice();
8043
+ messages.push(markSynthetic({ role: "user", content: step.nudge }));
8044
+ await logEvent("user_message", { content: step.nudge, synthetic: true });
8045
+ try {
8046
+ return await runEscalationStage(messages, step.target, undefined, "provability: escalated after a failing verdict", defer, true);
8047
+ }
8048
+ catch (err) {
8049
+ if (isAbortError(err) || isRunFailedError(err))
8050
+ throw err;
8051
+ runContext.logger.warn("provability: escalation rung unavailable — the answer stands with its failing verdict (note semantics)", { escalateTo: step.target.modelString, message: describeThrown(err, "Error").message });
8052
+ // Withdrawn from the LIVE transcript only: the nudge's synthetic
8053
+ // `user_message` line is already on disk, so a `--resume` replays
8054
+ // it ahead of the next input — the same live/resume divergence as
8055
+ // the cascade's withdrawn correction above, which a replay-side
8056
+ // withdrawal marker would fix for both at once.
8057
+ messages.splice(0, messages.length, ...verifiedTranscript);
8058
+ return undefined;
8059
+ }
8060
+ };
8061
+ /**
8062
+ * §5.4 — a gated attempt handed back to its call site. The STANDING pass
8063
+ * is rendered, and only when it graded this very attempt (one the abort
8064
+ * tree stopped before its pass was recorded shows nothing). A rejected
8065
+ * attempt the reader never saw is never shown; one the reader saw stream
8066
+ * past already carries its ✗ (`markRejected`), and an escalation that could
8067
+ * not run leaves that same verdict standing, which is not written twice.
8068
+ * `footerTarget: "stream"` writes it to the run's output after the answer,
8069
+ * on its own line; `"reply"` hands it back as `footer` for the caller to
8070
+ * append to the text the run returns; `"none"` renders nothing (the caller
8071
+ * carries the bundle itself, as the managed gateway's `proof` field does).
8072
+ * It never enters `messages`: the model must not read its own footer next
8073
+ * turn.
8074
+ */
8075
+ const finishGated = (provability, ladder, attempt) => {
8076
+ const target = provability.footerTarget ?? "stream";
8077
+ const standing = ladder.standing;
8078
+ const footer = target !== "none" &&
8079
+ standing !== undefined &&
8080
+ standing.attempt === attempt &&
8081
+ standing.bundle !== ladder.marked
8082
+ ? renderStanding(provability, standing.bundle, standing.bundlePath)
8083
+ : undefined;
8084
+ if (footer === undefined)
8085
+ return { ...attempt, gated: true };
8086
+ if (target === "reply")
8087
+ return { ...attempt, footer, gated: true };
8088
+ out.write(`${footer}\n`);
8089
+ return { ...attempt, gated: true };
8090
+ };
8091
+ /**
8092
+ * 0.8.0 (design §5.1) — one COMPLETED turn through the provability gate.
8093
+ * `inner` is what the call site ran before the gate existed
8094
+ * (`runCommitteeOrTurn` on the single-turn path, `runEvaluatedTurn` on the
8095
+ * REPL). Without `opts.provability` this IS `inner(messages)`.
8096
+ *
8097
+ * The evaluated turn runs the ladder itself, on every attempt and before
8098
+ * every grade (provability first, §5.1), and comes back `gated`; it is
8099
+ * handed on as it is. What this verifies is the one answer no evaluated
8100
+ * turn produced — a committee verdict — pass by pass (`provabilityPass`):
8101
+ * a retry runs `inner` again, an escalation runs the turn on the rung,
8102
+ * and a halt is the classified stop. A stop the abort tree made inside
8103
+ * `inner` hands the turn back un-verified, or throws the classified
8104
+ * timeout (G10), before anything else.
8105
+ */
8106
+ async function runProvableTurn(messages, inner) {
8107
+ const provability = opts.provability;
8108
+ if (provability === undefined)
8109
+ return inner(messages);
8110
+ const ladder = newProvabilityLadder();
8111
+ activeLadder = ladder;
8112
+ try {
8113
+ let attempt = await inner(messages);
8114
+ /** The cascade stage of the attempt being verified: set when it came off the escalation rung. */
8115
+ let stage;
8116
+ for (;;) {
8117
+ if (await stoppedByAbort(false))
8118
+ return attempt;
8119
+ if (attempt.gated === true)
8120
+ return attempt;
8121
+ const step = await provabilityPass(provability, ladder, messages, attempt, stage);
8122
+ if (step.kind === "stopped")
8123
+ return attempt;
8124
+ if (step.kind === "stands")
8125
+ return finishGated(provability, ladder, attempt);
8126
+ if (step.kind === "halt")
8127
+ return await haltOnProvability(provability, step);
8128
+ ladder.reruns += 1;
8129
+ if (step.kind === "escalate") {
8130
+ ladder.escalations += 1;
8131
+ const escalated = await escalateOnProvability(messages, step, false);
8132
+ if (escalated === undefined)
8133
+ return finishGated(provability, ladder, attempt);
8134
+ attempt = escalated;
8135
+ stage = "escalate";
8136
+ continue;
8137
+ }
8138
+ // onFail: "retry".
8139
+ messages.push(markSynthetic({ role: "user", content: step.nudge }));
8140
+ await logEvent("user_message", { content: step.nudge, synthetic: true });
8141
+ attempt = await inner(messages);
8142
+ stage = undefined;
8143
+ }
8144
+ }
8145
+ finally {
8146
+ activeLadder = undefined;
8147
+ }
8148
+ }
6395
8149
  // Single-shot path used by the workflow target and (Section 12) the
6396
8150
  // channel-bot session router. Runs one user→assistant turn (with the tool
6397
8151
  // inner-loop until Done), persists the transcript, returns the terminal
@@ -6488,16 +8242,31 @@ export async function runChatLoop(opts) {
6488
8242
  armTurnTimer();
6489
8243
  // 0.6.0 §7.8 — the shadow re-runs exactly what the primary answered.
6490
8244
  const shadowSeed = [...messages];
6491
- const { terminalContent } = await runCommitteeOrTurn(messages);
8245
+ // 0.8.0 §5.1 — the provability gate wraps the (committee or evaluated)
8246
+ // turn; without `opts.provability` it is exactly `runCommitteeOrTurn`.
8247
+ const { terminalContent, footer } = await runProvableTurn(messages, runCommitteeOrTurn);
6492
8248
  clearTurnTimer();
6493
- maybeScheduleShadow(shadowSeed, terminalText(terminalContent));
8249
+ const answer = terminalText(terminalContent);
8250
+ maybeScheduleShadow(shadowSeed, answer);
6494
8251
  bus.publish({
6495
8252
  ...bus.envelope(),
6496
8253
  kind: "turn_end",
6497
8254
  turn: runContext.turnNumber,
6498
8255
  durationMs: performance.now() - t0SingleTurn,
6499
8256
  });
6500
- return terminalText(terminalContent);
8257
+ // §5.4 — `footerTarget: "reply"`: the proof footer travels in the text
8258
+ // the run RETURNS (what a channel bot sends, what the gateway answers),
8259
+ // after a blank line — never in `messages`, so the transcript the model
8260
+ // reads next turn holds the answer alone. An empty answer carries the
8261
+ // footer alone (no leading blank line). Under `provability:` the text
8262
+ // served is the answer with every footer-shaped line of it marked as
8263
+ // the model's (`./forged-footer`, §1 principle 2): whatever `render`
8264
+ // and the target say, no line the model wrote passes for the verdict.
8265
+ // The transcript and the shadow keep its own words.
8266
+ const served = opts.provability !== undefined ? neutralizeFooterLines(answer) : answer;
8267
+ if (footer === undefined)
8268
+ return served;
8269
+ return served === "" ? footer : `${served}\n\n${footer}`;
6501
8270
  }
6502
8271
  finally {
6503
8272
  // 0.6.0 §7.8 — the single turn IS the run. A per-message host
@@ -6777,7 +8546,13 @@ export async function runChatLoop(opts) {
6777
8546
  try {
6778
8547
  // 0.6.0 §7.8 — the shadow re-runs exactly what the primary answered.
6779
8548
  const shadowSeed = [...messages];
6780
- const { terminalContent } = await runEvaluatedTurn(messages);
8549
+ // 0.8.0 §5.1 — the provability gate wraps the evaluated turn; without
8550
+ // `opts.provability` it is exactly `runEvaluatedTurn`. The REPL
8551
+ // returns no per-turn reply, so a `footerTarget: "reply"` footer has
8552
+ // nothing to ride on and is written to the output like `"stream"`.
8553
+ const { terminalContent, footer } = await runProvableTurn(messages, runEvaluatedTurn);
8554
+ if (footer !== undefined)
8555
+ out.write(`${footer}\n`);
6781
8556
  // Item 1 — the exit rating prompt's "worth rating" floor: count only
6782
8557
  // turns that ended in a real assistant answer.
6783
8558
  if (terminalText(terminalContent).trim() !== "")
@@ -7089,20 +8864,97 @@ async function curateActiveContext(messages, snipKeepHead, snipKeepTail, cfg) {
7089
8864
  return { messages: out, before, after, dropped: before - after, bytesSaved, embedded };
7090
8865
  }
7091
8866
  /**
7092
- * Item 2 / G21 — render the recalled-memory system block body with the SAME
7093
- * two defenses the session-start recall uses (#53): neutralize any
7094
- * `</recalled_memory>` breakout delimiter inside a recalled line, and run the
7095
- * assembled block through `classifyBoundary` with origin `"user"` (recalled
7096
- * lines may embed content shaped by untrusted tool output in an earlier
7097
- * session). Returns `undefined` when there is nothing to recall.
8867
+ * Item 2 / G21 — render the recalled-memory system block for both recall
8868
+ * modes (#53). Pillar 3: every line is classified at TrustOrigin `"memory"`
8869
+ * BEFORE it reaches the system prompt, because a fact, wiki article, or
8870
+ * session summary written in an earlier session may have absorbed attacker
8871
+ * text, and the system region has no post-tool classifier behind it. A
8872
+ * malicious line is replaced by the redaction notice; a suspicious one is kept
8873
+ * and logged. The admitted lines are then classified together, so an injection
8874
+ * split across two of them is redacted too (see `redactSplitInjections`); each
8875
+ * line still admitted is lineage-tagged for the egress fabric. Each line then
8876
+ * has any
8877
+ * `</recalled_memory>` breakout delimiter neutralized. A classifier rejection
8878
+ * propagates, so both callers fail closed. Returns `undefined` when there is
8879
+ * nothing to recall.
7098
8880
  */
7099
- async function renderRecalledMemory(lines) {
8881
+ async function renderRecalledMemory(lines, runContext) {
7100
8882
  if (lines.length === 0)
7101
8883
  return undefined;
7102
- const body = lines.map((l) => `- ${escapeBoundaryDelimiter(l, "recalled_memory")}`).join("\n");
7103
- const text = `<recalled_memory>\nRelevant facts remembered from earlier sessions:\n${body}\n</recalled_memory>`;
7104
- await classifyBoundary(text, { origin: "user" }).catch(() => undefined);
7105
- return text;
8884
+ const rendered = [...lines];
8885
+ const admitted = [];
8886
+ for (const [i, line] of lines.entries()) {
8887
+ const boundary = await classifyBoundary(line, { origin: "memory" });
8888
+ const rules = [...new Set(boundary.verdict.hits.map((h) => h.rule))];
8889
+ if (boundary.action === "redact") {
8890
+ runContext.logger.warn("recalled memory line redacted (prompt injection detected)", {
8891
+ rules,
8892
+ });
8893
+ rendered[i] = boundary.redacted ?? "";
8894
+ continue;
8895
+ }
8896
+ if (boundary.action === "warn") {
8897
+ runContext.logger.warn("suspicious recalled memory line kept", { rules });
8898
+ }
8899
+ admitted.push(i);
8900
+ }
8901
+ const split = await redactSplitInjections(admitted.map((i) => lines[i]), runContext);
8902
+ admitted.forEach((i, j) => {
8903
+ const notice = split.get(j);
8904
+ if (notice !== undefined)
8905
+ rendered[i] = notice;
8906
+ else
8907
+ tagContent(runContext, lines[i], "memory");
8908
+ });
8909
+ const body = rendered.map((l) => `- ${escapeBoundaryDelimiter(l, "recalled_memory")}`).join("\n");
8910
+ return `<recalled_memory>\nRelevant facts remembered from earlier sessions:\n${body}\n</recalled_memory>`;
8911
+ }
8912
+ /**
8913
+ * Pillar 3 — an injection split across recalled lines. Each of `lines` passed
8914
+ * classification on its own, but an attacker who can plant two memories that
8915
+ * recall side by side can split one phrase between them ("… ignore previous" /
8916
+ * "instructions and …"): each half classifies clean, and the model still reads
8917
+ * one sentence. So the lines are also classified joined with "\n" at
8918
+ * TrustOrigin `"memory"`. The raw join, not the rendered block, because the
8919
+ * block's `- ` bullets break the detector's phrase rules without breaking the
8920
+ * sentence for the model. When the join is malicious, each adjacent pair is
8921
+ * classified and both lines of a malicious pair are redacted. When no pair
8922
+ * reproduces the verdict, or the lines left still join malicious (a split over
8923
+ * three lines, or weak hits that only add up across the block), every line is
8924
+ * redacted: fail closed. Returns the redaction notice for each line to redact,
8925
+ * by index into `lines`; a classifier rejection propagates.
8926
+ */
8927
+ async function redactSplitInjections(lines, runContext) {
8928
+ const redacted = new Map();
8929
+ if (lines.length < 2)
8930
+ return redacted;
8931
+ const joined = await classifyBoundary(lines.join("\n"), { origin: "memory" });
8932
+ if (joined.action !== "redact")
8933
+ return redacted;
8934
+ for (let i = 0; i + 1 < lines.length; i++) {
8935
+ const pair = await classifyBoundary(`${lines[i]}\n${lines[i + 1]}`, { origin: "memory" });
8936
+ if (pair.action !== "redact")
8937
+ continue;
8938
+ runContext.logger.warn("recalled memory lines redacted (prompt injection split across lines)", {
8939
+ rules: [...new Set(pair.verdict.hits.map((h) => h.rule))],
8940
+ });
8941
+ redacted.set(i, pair.redacted ?? "");
8942
+ redacted.set(i + 1, pair.redacted ?? "");
8943
+ }
8944
+ const left = lines.filter((_, i) => !redacted.has(i));
8945
+ const residual = redacted.size === 0
8946
+ ? joined
8947
+ : left.length > 1
8948
+ ? await classifyBoundary(left.join("\n"), { origin: "memory" })
8949
+ : undefined;
8950
+ if (residual?.action === "redact") {
8951
+ runContext.logger.warn("recalled memory lines redacted (prompt injection across lines not localized to a pair)", { rules: [...new Set(residual.verdict.hits.map((h) => h.rule))] });
8952
+ for (let i = 0; i < lines.length; i++) {
8953
+ if (!redacted.has(i))
8954
+ redacted.set(i, residual.redacted ?? "");
8955
+ }
8956
+ }
8957
+ return redacted;
7106
8958
  }
7107
8959
  /**
7108
8960
  * Item 9 / G79 — stamp ONE message-level cache breakpoint so the settled
@@ -7252,18 +9104,16 @@ async function maybeCompact(args, onCompaction) {
7252
9104
  return snipped;
7253
9105
  }
7254
9106
  logger.info("autocompact triggered", { tokensAfterSnip: effectiveTokens(snipped) });
7255
- // §2.3 — autocompact replaces the ENTIRE history; externalize all of it
7256
- // before the summarizer model call so the records survive even a
7257
- // summarizer failure. The ledger anchor is read afterwards so this
7258
- // step's evictions are part of it.
7259
- if (onEvict !== undefined && snipped.length > 0)
7260
- await onEvict(snipped);
7261
- const ledgerText = getLedgerText?.();
7262
- const after = await autoCompact(snipped, adapter, model, {
7263
- ...(ledgerText !== undefined ? { ledgerText } : {}),
9107
+ const after = await summarizeHistory({
9108
+ snipped,
9109
+ adapter,
9110
+ model,
9111
+ contextLimit,
9112
+ ...(onEvict !== undefined ? { onEvict } : {}),
9113
+ ...(getLedgerText !== undefined ? { getLedgerText } : {}),
7264
9114
  ...(bus !== undefined ? { bus } : {}),
7265
- ...(compactionSpecModel !== undefined ? { specModel: compactionSpecModel } : {}),
7266
- ...(compactionParams !== undefined ? { params: compactionParams } : {}),
9115
+ ...(compactionSpecModel !== undefined ? { compactionSpecModel } : {}),
9116
+ ...(compactionParams !== undefined ? { compactionParams } : {}),
7267
9117
  });
7268
9118
  if (onCompaction !== undefined) {
7269
9119
  const summary = summaryTextOf(after);
@@ -7283,24 +9133,71 @@ async function maybeCompact(args, onCompaction) {
7283
9133
  * largest blob).
7284
9134
  */
7285
9135
  async function forceCompact(args) {
7286
- const { messages, adapter, model, snipKeepHead, snipKeepTail, logger, onEvict, getLedgerText, bus, compactionSpecModel, compactionParams, } = args;
9136
+ const { messages, adapter, model, contextLimit, snipKeepHead, snipKeepTail, logger, onEvict, getLedgerText, bus, compactionSpecModel, compactionParams, } = args;
7287
9137
  const snipped = snip(messages, snipKeepHead, snipKeepTail);
7288
9138
  // §2.3 — same externalize-before-drop contract as the pre-turn ladder:
7289
- // the snip diff first, then the full remaining history autocompact is
7290
- // about to replace (disjoint sets, so no record is written twice).
9139
+ // the snip diff first, then what autocompact is about to replace
9140
+ // (disjoint sets, so no record is written twice).
7291
9141
  if (onEvict !== undefined) {
7292
9142
  const evicted = snippedAway(messages, snipped);
7293
9143
  if (evicted.length > 0)
7294
9144
  await onEvict(evicted);
7295
9145
  }
7296
9146
  logger.info("reactive snip applied", { before: messages.length, after: snipped.length });
7297
- if (onEvict !== undefined && snipped.length > 0)
7298
- await onEvict(snipped);
9147
+ return await summarizeHistory({
9148
+ snipped,
9149
+ adapter,
9150
+ model,
9151
+ contextLimit,
9152
+ ...(onEvict !== undefined ? { onEvict } : {}),
9153
+ ...(getLedgerText !== undefined ? { getLedgerText } : {}),
9154
+ ...(bus !== undefined ? { bus } : {}),
9155
+ ...(compactionSpecModel !== undefined ? { compactionSpecModel } : {}),
9156
+ ...(compactionParams !== undefined ? { compactionParams } : {}),
9157
+ });
9158
+ }
9159
+ /**
9160
+ * The pending user message survives compaction verbatim only while it is at
9161
+ * most this share of the context limit, so keeping it can never push the
9162
+ * compacted history back over the trigger threshold.
9163
+ */
9164
+ const KEEP_PENDING_CONTEXT_SHARE = 0.25;
9165
+ /**
9166
+ * The autocompact step shared by the pre-turn ladder and the reactive path.
9167
+ *
9168
+ * autoCompact ends the history on a user turn — the pending user message
9169
+ * kept verbatim, or a continuation notice — because current Claude models
9170
+ * reject a trailing assistant turn as prefill. This wrapper keeps the
9171
+ * runtime's two contracts intact around that:
9172
+ * - §2.3 externalize-before-drop: exactly `plan.toSummarize` is evicted,
9173
+ * before the summarizer call, so a kept message is never ALSO copied into
9174
+ * the requirements ledger. `planCompaction` is pure, so this plan and the
9175
+ * one autoCompact computes agree given the same `keepPendingMaxTokens`.
9176
+ * - §7.2.1 human-text routing: the marker and the continuation notice are
9177
+ * runtime-injected, so they are marked synthetic. A kept message is the
9178
+ * original object and keeps whatever mark it already had.
9179
+ */
9180
+ async function summarizeHistory(args) {
9181
+ const { snipped, adapter, model, contextLimit, onEvict, getLedgerText } = args;
9182
+ const keepPendingMaxTokens = Math.floor(contextLimit * KEEP_PENDING_CONTEXT_SHARE);
9183
+ const plan = planCompaction(snipped, { keepPendingMaxTokens });
9184
+ // §2.3 — externalize what the summary replaces before the summarizer
9185
+ // call, so the records survive even a summarizer failure. The ledger
9186
+ // anchor is read afterwards so this step's evictions are part of it.
9187
+ if (onEvict !== undefined && plan.toSummarize.length > 0)
9188
+ await onEvict(plan.toSummarize);
7299
9189
  const ledgerText = getLedgerText?.();
7300
- return await autoCompact(snipped, adapter, model, {
9190
+ const after = await autoCompact(snipped, adapter, model, {
9191
+ keepPendingMaxTokens,
7301
9192
  ...(ledgerText !== undefined ? { ledgerText } : {}),
7302
- ...(bus !== undefined ? { bus } : {}),
7303
- ...(compactionSpecModel !== undefined ? { specModel: compactionSpecModel } : {}),
7304
- ...(compactionParams !== undefined ? { params: compactionParams } : {}),
9193
+ ...(args.bus !== undefined ? { bus: args.bus } : {}),
9194
+ ...(args.compactionSpecModel !== undefined ? { specModel: args.compactionSpecModel } : {}),
9195
+ ...(args.compactionParams !== undefined ? { params: args.compactionParams } : {}),
7305
9196
  });
9197
+ const [marker, , final] = after;
9198
+ if (marker !== undefined)
9199
+ markSynthetic(marker);
9200
+ if (final !== undefined && final !== plan.kept)
9201
+ markSynthetic(final);
9202
+ return after;
7306
9203
  }