@crewhaus/runtime-core 0.7.0 → 0.8.1

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,10 +18,11 @@ 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";
24
- import { createRunContext, tagContent } from "@crewhaus/run-context";
25
+ import { DATA_LINEAGE_CAP, createRunContext, tagContent, } from "@crewhaus/run-context";
25
26
  import { createSessionStore, evictExpiredApprovals, generateApprovalId, hashApprovalInput, mergeSessionModels, resolveSessionPin, } from "@crewhaus/session-store";
26
27
  import { formatSkillsForPrompt } from "@crewhaus/skills-registry";
27
28
  import { expand as expandSlash } from "@crewhaus/slash-commands";
@@ -30,24 +31,31 @@ 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";
40
+ import { homeHeldBy } from "@crewhaus/tool-safety/fs";
38
41
  import { AUXILIARY_MODEL_ROLES, TraceEventBus, } from "@crewhaus/trace-event-bus";
39
42
  import { initialState, transition, } from "@crewhaus/turn-state-machine";
40
43
  import { zodToJsonSchema } from "zod-to-json-schema";
41
44
  import { createCliMarkdownRenderer, isCliMarkdownEnabled, } from "./cli-markdown";
42
45
  import { createMemoryEventLog, createMemorySessionStore } from "./ephemeral";
43
46
  import { FEEDBACK_EVENT_KIND, runExitRating } from "./exit-rating";
47
+ import { flattenUnionToObject } from "./flatten-union";
48
+ import { createFooterLineGuard, neutralizeFooterLines } from "./forged-footer";
44
49
  import { attachIncidentCollector } from "./incident-collector";
45
50
  import { LIST_TOOLS_NAME, buildListToolsTool } from "./list-tools";
46
51
  import { createSpanUnionTracker, modelLatencyMs } from "./model-latency";
47
52
  import { attachAdvisorPersistence, attachDefaultSubscribers, attachMcpStatsPersistence, attachRoutingPersistence, attachWatchmeCapture, } from "./observability";
53
+ import { placeRecordingCanonicalizer } from "./path-canonical";
48
54
  import { describeHintEvidence, isSyntheticMessage, latestHumanUserMessage, markSynthetic, messageText, preRoute, stripDirectiveFromMessage, } from "./pre-route";
49
55
  import { loadProjectMemory } from "./project-memory";
50
56
  import { createCliOutput, isSpinnerEnabled } from "./spinner";
57
+ import { credentialFileRoots, credentialFloorScope, relocatingFieldLeftOut, runtimeRecordRoots, runtimeStateRoots, } from "./state-roots";
58
+ import { checkServingToolLimits, unreportedToolLimitLines, } from "./tool-limit";
51
59
  /**
52
60
  * Slice-scope runtime: a multi-turn streaming chat loop with prompt
53
61
  * caching, tool execution, pre-turn context compaction, recovery taxonomy,
@@ -75,8 +83,9 @@ import { createCliOutput, isSpinnerEnabled } from "./spinner";
75
83
  * hit, a synthetic warning user message is appended (deduped per
76
84
  * signature) so the model can self-correct. Every tool result flows
77
85
  * 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
86
+ * persisted to `.crewhaus/tool-results/<runId>/<toolUseId>.txt` (or
87
+ * `<toolUseId>.<n>.txt` when an id-less provider's synthesised id repeats)
88
+ * and the model sees a preview pointing at the full file. Behind a
80
89
  * `streaming: true` option, the loop swaps to
81
90
  * `@crewhaus/streaming-tool-executor`, which dispatches tools mid-stream
82
91
  * via the SDK's `contentBlock` event.
@@ -179,37 +188,6 @@ function toAdvertisedTool(t) {
179
188
  justificationInjected: injected,
180
189
  };
181
190
  }
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
191
  // ---------------------------------------------------------------------------
214
192
  // v0.3.0 Goal 1 — the continuity seam (§2.3 requirements ledger, §2.5 mutable
215
193
  // tail region). All injected closures: runtime-core stays store-free; the
@@ -424,6 +402,7 @@ export { createEdgeAnthropicAdapter, classifyEdgeTool, EDGE_SAFE_TOOLS, HOST_ONL
424
402
  // own module (`./janitor`) but is re-exported here because emitted bundles
425
403
  // only import the package root.
426
404
  export { createJanitor } from "./janitor";
405
+ export { GATE_RESOLVE_SINK_ID, lineageEgressScreen, } from "./lineage-screen";
427
406
  export { JANITOR_BUILTIN_STEPS } from "./janitor";
428
407
  // Loop contract 0.4 (Batch C, item 4) — agent identity generation. Lives in
429
408
  // its own module (`./identity`) but is re-exported here because emitted
@@ -489,8 +468,11 @@ export async function findReplayableGrant(store, where) {
489
468
  }
490
469
  const now = where.now ?? Date.now();
491
470
  const maxAgeMs = where.maxAgeMs ?? REPLAYABLE_GRANT_MAX_AGE_MS;
471
+ // 0.7.1 — a grant made before MCP tools were renamed names the tool by its
472
+ // old `<server>__<tool>` spelling; it is the same tool.
473
+ const legacyToolName = legacyMcpToolName(where.toolName);
492
474
  const matches = all.filter((a) => {
493
- if (a.toolName !== where.toolName)
475
+ if (a.toolName !== where.toolName && a.toolName !== legacyToolName)
494
476
  return false;
495
477
  if (a.sessionId !== where.sessionId)
496
478
  return false;
@@ -525,6 +507,99 @@ export async function findReplayableGrant(store, where) {
525
507
  // trust the ordering of a store a caller injected.
526
508
  return [...matches].sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))[0];
527
509
  }
510
+ /**
511
+ * 0.7.1 — does the decision on `record` cover a call that now lands at
512
+ * `call`?
513
+ *
514
+ * An operator approves a call where it acts. The record is keyed on the
515
+ * input, and the same input can be made to act somewhere else: retarget a
516
+ * symlinked directory between park and resume — any allowed call in the
517
+ * resumed turn can — and a grant for `pub/link/x.md` would write wherever
518
+ * the link now points, a place the operator never saw and one an
519
+ * `alwaysAsk` rule may name. So the record carries the places the gate
520
+ * found when it parked, and decides the call only while it lands there.
521
+ *
522
+ * A record written before approvals were bound (no `places`: 0.7.0, or an
523
+ * earlier 0.7.1 build) showed its approver only the input as written, so
524
+ * the one place it can be said to cover is the one that input names on its
525
+ * face. It decides the call when every path lands exactly there — no
526
+ * symlink followed, nothing elsewhere — and otherwise the call is asked
527
+ * again: never run somewhere the approver could not have seen. A record
528
+ * whose `places` is not the shape written here (a foreign or hand-edited
529
+ * line) covers nothing.
530
+ *
531
+ * Binding is about where a call RUNS, so the gate asks this of a grant or a
532
+ * park it would re-use; a deny refuses the call wherever it lands.
533
+ */
534
+ export function landsWhereApproved(record, call) {
535
+ const recorded = record.places;
536
+ if (recorded === undefined)
537
+ return call.allAsWritten();
538
+ if (!Array.isArray(recorded))
539
+ return false;
540
+ const fresh = call.places();
541
+ if (recorded.length !== fresh.length)
542
+ return false;
543
+ return fresh.every((now, i) => {
544
+ const then = recorded[i];
545
+ if (typeof then !== "object" || then === null)
546
+ return false;
547
+ const { path: thenPath, at: thenAt } = then;
548
+ return (thenPath === now.path &&
549
+ Array.isArray(thenAt) &&
550
+ thenAt.length === now.at.length &&
551
+ now.at.every((place, j) => thenAt[j] === place));
552
+ });
553
+ }
554
+ /**
555
+ * 0.7.1 — the newest record for this call that was made where it now lands:
556
+ * same tool and input (`keys`), not yet spent, and covering its places. The
557
+ * store's `get` hands back only the newest record for the input; when that
558
+ * one was made for another place, an older one may still be this place's —
559
+ * a grant the operator made before a link moved away and back, or a park
560
+ * already waiting. `list` is optional on an injected store; without it (or
561
+ * when it fails) there is nothing more to find, and the call parks.
562
+ */
563
+ async function findApprovalForPlace(store, keys, call) {
564
+ if (typeof store.list !== "function")
565
+ return null;
566
+ let all;
567
+ try {
568
+ all = await store.list();
569
+ }
570
+ catch {
571
+ return null;
572
+ }
573
+ // Newest-touched first, as `get` chooses.
574
+ const touched = (a) => {
575
+ const at = Date.parse(a.decidedAt ?? a.createdAt);
576
+ return Number.isFinite(at) ? at : 0;
577
+ };
578
+ const matches = all.filter((a) => keys.some(([toolName, inputHash]) => a.toolName === toolName && a.inputHash === inputHash) &&
579
+ a.consumedAt === undefined &&
580
+ landsWhereApproved(a, call));
581
+ return [...matches].sort((a, b) => touched(b) - touched(a))[0] ?? null;
582
+ }
583
+ /** What a park asked in place of `record` keeps of it, for the card. */
584
+ function supersededBy(record) {
585
+ return {
586
+ id: record.id,
587
+ ...(record.decision !== undefined ? { decision: record.decision } : {}),
588
+ ...(Array.isArray(record.places) ? { places: record.places } : {}),
589
+ };
590
+ }
591
+ /** Where a call lands, for an operator reading why it was asked again. */
592
+ function describePlaces(places) {
593
+ if (places === undefined)
594
+ return "the input as written";
595
+ if (!Array.isArray(places))
596
+ return "an unreadable record";
597
+ if (places.length === 0)
598
+ return "no path";
599
+ return places
600
+ .map((p) => `${p.path} -> ${Array.isArray(p.at) ? p.at.join(" and ") : "?"}`)
601
+ .join("; ");
602
+ }
528
603
  // Ops item 31 — alert watchdog seams re-exported so the CLI/codegen can build
529
604
  // the durable + off-box alert sink (audit append + settings.json alert hook /
530
605
  // webhook) it passes as `RunChatLoopOptions.alertSink`.
@@ -591,6 +666,14 @@ export function sanitizeOrphanToolUses(messages) {
591
666
  }
592
667
  return { messages: out, removed };
593
668
  }
669
+ /**
670
+ * A line the runtime wrote to a session log: `appendEvent`'s version and an
671
+ * object payload. The readers that rebuild a run count only these, so anything
672
+ * else in the file changes nothing about the replay.
673
+ */
674
+ function isRuntimeLogLine(ev) {
675
+ return ev.version === 1 && typeof ev.payload === "object" && ev.payload !== null;
676
+ }
594
677
  /**
595
678
  * Walk an `EventLog` and reconstruct the SDK message history. Only
596
679
  * `user_message` and `assistant_message` events contribute — `tool_use`
@@ -614,6 +697,8 @@ export async function replayMessageHistory(log) {
614
697
  // surface user/assistant events at depth 0.
615
698
  let depth = 0;
616
699
  for await (const ev of log.read()) {
700
+ if (!isRuntimeLogLine(ev))
701
+ continue;
617
702
  if (ev.kind === "a2a_turn_start" || ev.kind === "sub_agent_start") {
618
703
  depth += 1;
619
704
  continue;
@@ -656,6 +741,75 @@ export async function replayMessageHistory(log) {
656
741
  // request. Drop such orphans so `--resume` self-heals. No-op on healthy logs.
657
742
  return sanitizeOrphanToolUses(messages).messages;
658
743
  }
744
+ /**
745
+ * The egress check reads a run's lineage, and a run resumed from its log should
746
+ * read the same lineage it had. Each tool result is tagged at `tool`, including
747
+ * one from a tool that sets `classifyOutput: false`, so a verbatim copy of it
748
+ * meets the egress check as a tool result does within one run. Oldest first, so
749
+ * the lineage cap keeps the newest, and only the newest `DATA_LINEAGE_CAP`
750
+ * results, since a long session replays its whole history; a result gives at
751
+ * least one piece unless it is too short to match. What the caller tagged
752
+ * before the run, such as the message that started it, is newer than anything
753
+ * replayed and stays newest.
754
+ */
755
+ function tagReplayedToolResults(runContext, messages) {
756
+ const replayed = [];
757
+ for (const message of messages) {
758
+ if (message.role !== "user" || typeof message.content === "string")
759
+ continue;
760
+ for (const block of message.content) {
761
+ if (block.type !== "tool_result")
762
+ continue;
763
+ const content = block.content;
764
+ const text = typeof content === "string"
765
+ ? content
766
+ : (content ?? []).map((part) => (part.type === "text" ? part.text : "")).join("\n");
767
+ if (text.length > 0)
768
+ replayed.push(text);
769
+ }
770
+ }
771
+ const held = [...(runContext.dataLineage ?? [])];
772
+ for (const text of replayed.slice(-DATA_LINEAGE_CAP))
773
+ tagContent(runContext, text, "tool");
774
+ const lineage = runContext.dataLineage;
775
+ if (lineage === undefined)
776
+ return;
777
+ for (const [piece, origin] of held) {
778
+ lineage.delete(piece);
779
+ lineage.set(piece, origin);
780
+ }
781
+ while (lineage.size > DATA_LINEAGE_CAP) {
782
+ const oldest = lineage.keys().next().value;
783
+ if (oldest === undefined)
784
+ break;
785
+ lineage.delete(oldest);
786
+ }
787
+ }
788
+ /**
789
+ * 0.8.0 (design/0.8.0-provability-release.md §5.3) — how many turns a
790
+ * replayed transcript (`replayMessageHistory`) already holds: its user
791
+ * messages that opened one, the ones `runContext.turnNumber` counted when
792
+ * they ran. A runtime-injected message (a retry nudge, a cascade correction,
793
+ * a continue prompt — still marked synthetic after the replay) opens none,
794
+ * nor does the carrier of a batch of tool results; a directive-only input
795
+ * never reaches the replay (it ran no turn). Nested transcripts (a peer's, a
796
+ * sub-agent's) are already outside it.
797
+ */
798
+ function openedTurnCount(messages) {
799
+ let opened = 0;
800
+ for (const message of messages) {
801
+ if (message.role !== "user" || isSyntheticMessage(message))
802
+ continue;
803
+ const content = message.content;
804
+ if (typeof content !== "string" &&
805
+ content.length > 0 &&
806
+ content.every((block) => block.type === "tool_result")) {
807
+ continue;
808
+ }
809
+ opened += 1;
810
+ }
811
+ return opened;
812
+ }
659
813
  export async function attachRunEventSink(runContext, opts = {}) {
660
814
  const rootDir = resolveSessionRootDir(opts.sessionRootDir);
661
815
  const log = await openEventLog(runContext.sessionId, { rootDir });
@@ -689,16 +843,10 @@ export function resolveToolResultRoot() {
689
843
  return currentTenantContext()?.tenant.toolResultRoot;
690
844
  }
691
845
  /**
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.
846
+ * The names that were model-destination sinks before tools could say so
847
+ * themselves. They stay dynamic whatever a tool of that name declares, so
848
+ * the declaration can only add sinks to the block tier, never take one out
849
+ * (see {@link defaultSinkScope}).
702
850
  */
703
851
  const MODEL_DESTINATION_SINKS = new Set([
704
852
  "Fetch",
@@ -707,19 +855,77 @@ const MODEL_DESTINATION_SINKS = new Set([
707
855
  "EvmSendTransaction",
708
856
  ]);
709
857
  /**
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.
858
+ * 0.7.1 — the tool-name fields of a `pre-tool` / `post-tool` hook payload.
859
+ * `name` is the registered name; an MCP tool also carries `legacyName`, the
860
+ * `<server>__<tool>` spelling it had before 0.7.1. A hook matcher accepts
861
+ * either spelling, but a script that reads `name` from its stdin and compares
862
+ * it cannot know about the rename, and a guard that stops matching is a
863
+ * guard that silently stops guarding — so it gets a stable field to compare.
864
+ */
865
+ function hookToolName(name) {
866
+ const legacyName = legacyMcpToolName(name);
867
+ return legacyName !== undefined ? { name, legacyName } : { name };
868
+ }
869
+ /**
870
+ * 0.7.1 — re-key a tool-name map (rate limits) written with the pre-0.7.1
871
+ * MCP spelling `<server>__<tool>` onto the registered `mcp__<server>__<tool>`
872
+ * name. A key that already names a tool, `"*"`, or an old spelling whose new
873
+ * name the map also carries is left alone. Returns the input by reference
874
+ * when nothing moved.
875
+ */
876
+ export function rekeyLegacyMcpToolKeys(map, toolNames) {
877
+ if (map === undefined)
878
+ return undefined;
879
+ const byLegacy = new Map();
880
+ for (const name of toolNames) {
881
+ const legacy = legacyMcpToolName(name);
882
+ if (legacy !== undefined)
883
+ byLegacy.set(legacy, name);
884
+ }
885
+ if (byLegacy.size === 0)
886
+ return map;
887
+ let moved = false;
888
+ const out = {};
889
+ for (const [key, value] of Object.entries(map)) {
890
+ const registered = key === "*" || toolNames.has(key) ? undefined : byLegacy.get(key);
891
+ if (registered !== undefined && !Object.hasOwn(map, registered)) {
892
+ out[registered] = value;
893
+ moved = true;
894
+ }
895
+ else {
896
+ out[key] = value;
897
+ }
898
+ }
899
+ return moved ? out : map;
900
+ }
901
+ /**
902
+ * Default egress sink-scope.
903
+ *
904
+ * A sink whose DESTINATION the (prompt-injectable) model chooses is dynamic
905
+ * even when the spec declares the tool: an attacker who steers the model
906
+ * picks where the data goes, so content from a non-user origin reaching it
907
+ * must reach the egress BLOCK tier, not merely warn (#144). Which tools those
908
+ * are is read from the tool itself: an external tool whose `operativeArgs`
909
+ * include a `url` or a `recipient` (`hasModelChosenDestination`) — Fetch,
910
+ * HttpRequest, HttpBatch, WebhookPost, EmailSend, OpenExternal, the RPC
911
+ * readers, … (permission-integration#5). Runtime-joined MCP sinks (`mcp__*`)
912
+ * are dynamic too.
913
+ *
914
+ * A fixed-destination sink stays `"external-configured"` (warn): `SendMessage`
915
+ * replies to the operator's channel, `WebSearch` and `ImageGenerate` call a
916
+ * fixed provider, a code host is reached at its configured origin. The
917
+ * names that were dynamic before tools declared their destinations (Fetch,
918
+ * WebFetch, Navigate, EvmSendTransaction) stay dynamic, so a caller that
919
+ * passes only a name gets the 0.7.0 answer. Override per deployment with
920
+ * `runChatLoop({ resolveSinkScope })`.
717
921
  */
718
- export function defaultSinkScope(toolName) {
922
+ export function defaultSinkScope(toolName, tool) {
719
923
  if (toolName.startsWith("mcp__"))
720
924
  return "external-dynamic";
721
925
  if (MODEL_DESTINATION_SINKS.has(toolName))
722
926
  return "external-dynamic";
927
+ if (tool !== undefined && hasModelChosenDestination(tool))
928
+ return "external-dynamic";
723
929
  return "external-configured";
724
930
  }
725
931
  /**
@@ -751,6 +957,30 @@ function bestEffortWireModelId(modelString) {
751
957
  return modelString;
752
958
  }
753
959
  }
960
+ /**
961
+ * 0.7.1 — every model string the run was configured with, for the bridge's
962
+ * `specModels` (the Task tool's allow-list for a `.crewhaus/sub-agents`
963
+ * definition's models). Exact strings, in first-seen order, no duplicates.
964
+ */
965
+ export function specModelsOf(opts) {
966
+ const out = new Set([opts.model]);
967
+ for (const m of opts.modelFallbacks ?? [])
968
+ out.add(m);
969
+ if (opts.modelTiers !== undefined) {
970
+ out.add(opts.modelTiers.fast);
971
+ out.add(opts.modelTiers.default);
972
+ }
973
+ for (const c of opts.modelPool?.candidates ?? []) {
974
+ out.add(c.model);
975
+ for (const m of c.fallbacks ?? [])
976
+ out.add(m);
977
+ }
978
+ if (opts.compactionModel !== undefined)
979
+ out.add(opts.compactionModel);
980
+ if (opts.budget?.onExceed.kind === "degrade")
981
+ out.add(opts.budget.onExceed.model);
982
+ return [...out];
983
+ }
754
984
  /**
755
985
  * A short, stable fingerprint of a `model_pool` config, stamped on every
756
986
  * `model_route` event as `policyVersion` so a learned decision can be tied back
@@ -906,33 +1136,300 @@ export function buildTimeoutFailureReport(timeout) {
906
1136
  exitCode: EXIT_CODES.timeout,
907
1137
  };
908
1138
  }
1139
+ /**
1140
+ * provider-limits#0 — act on a boot tool-limit verdict: no model can take the
1141
+ * run's tools → a `ConfigError` before any model call; some model cannot →
1142
+ * one `[tools]` line per model on stderr, beside the `[failover]` and
1143
+ * `[model_pool]` boot lines. A daemon runs one loop per message, so each
1144
+ * line is written once per process (`unreportedToolLimitLines`).
1145
+ */
1146
+ function reportToolLimits(verdict) {
1147
+ if (verdict.fatal !== undefined)
1148
+ throw new ConfigError(verdict.fatal);
1149
+ for (const line of unreportedToolLimitLines(verdict.warnings)) {
1150
+ process.stderr.write(`[tools] ${line}\n`);
1151
+ }
1152
+ }
1153
+ /** One `[workspace]` line on stderr when the working directory holds the home directory, once per process. */
1154
+ function reportWorkspaceHoldsHome() {
1155
+ const cwd = process.cwd();
1156
+ if (homeHeldBy(cwd, process.env) === undefined)
1157
+ return;
1158
+ const line = `this harness runs in ${cwd}, which holds your home directory. A harness's tools work inside its directory, so give it a directory of its own.`;
1159
+ for (const fresh of unreportedToolLimitLines([line]))
1160
+ process.stderr.write(`[workspace] ${fresh}\n`);
1161
+ }
909
1162
  /**
910
1163
  * Item 3 (G32) — merge plugin-contributed tools into the run's advertised tool
911
1164
  * 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.
1165
+ * can augment the catalog but never silently shadow a built-in; nor can it
1166
+ * take a name in `reserved` — the tools the loop adds itself (`ListTools`,
1167
+ * and `Consult` / `Escalate`), which would otherwise give way to it. Returns
1168
+ * the `base` array unchanged (same reference) when there are no plugin tools,
1169
+ * so a run without the `plugins` option is byte-identical to a pre-G32
1170
+ * runtime.
915
1171
  */
916
- function mergeEffectiveTools(base, pluginTools) {
1172
+ function mergeEffectiveTools(base, pluginTools, reserved = new Set()) {
917
1173
  if (pluginTools === undefined || pluginTools.length === 0)
918
1174
  return base;
919
1175
  const byName = new Set(base.map((t) => t.name));
920
1176
  const merged = [...base];
921
1177
  for (const tool of pluginTools) {
922
- if (byName.has(tool.name))
923
- continue; // first-party wins the collision
1178
+ if (byName.has(tool.name) || reserved.has(tool.name))
1179
+ continue; // first-party wins
924
1180
  byName.add(tool.name);
925
1181
  merged.push(tool);
926
1182
  }
927
1183
  return merged;
928
1184
  }
1185
+ /**
1186
+ * Does `limits` set a limit for `toolName` itself? Own keys only: a tool may
1187
+ * be named after an Object.prototype member (`toString`, `constructor`),
1188
+ * which a plain `rate_limits` object inherits but never sets.
1189
+ */
1190
+ function ownLimit(limits, toolName) {
1191
+ return Object.hasOwn(limits, toolName) && limits[toolName] !== undefined;
1192
+ }
1193
+ /** A transcript `tool_result` block's text: a string as is, the text blocks of an array joined. */
1194
+ function gateResultText(content) {
1195
+ if (typeof content === "string")
1196
+ return content;
1197
+ if (!Array.isArray(content))
1198
+ return "";
1199
+ const texts = [];
1200
+ for (const block of content) {
1201
+ if (typeof block !== "object" || block === null)
1202
+ continue;
1203
+ const b = block;
1204
+ if (b["type"] === "text" && typeof b["text"] === "string")
1205
+ texts.push(b["text"]);
1206
+ }
1207
+ return texts.join("\n");
1208
+ }
1209
+ /**
1210
+ * §5.4 — a claimless final message that hands the reader an earlier answer
1211
+ * again: "See above.", "As I said before.", "Same as my previous answer.".
1212
+ * Where that earlier answer was rejected, its ✗ stands with it.
1213
+ */
1214
+ 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;
1215
+ /** The verbs an agent announces a tool call with, as a bare verb ("I can look …", "Step 1: fetch …"). */
1216
+ 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";
1217
+ /**
1218
+ * The verbs "I can …" offers a tool call with ("I can look that up."): the
1219
+ * fetch-style ones only. "I can see / confirm / verify / find / review /
1220
+ * help / do / take …" opens what the agent says it knows ("I can confirm
1221
+ * your refund has been processed."), and is read as written.
1222
+ */
1223
+ 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";
1224
+ /** The same verbs as a gerund opener ("Fetching the policy page."). */
1225
+ 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";
1226
+ /**
1227
+ * §5.4 — a sentence that only says what the agent is about to do, whatever
1228
+ * its wording: "Let me fetch the refund policy page first.", "I'll save the
1229
+ * note to your notes file now.", "Fetching the refund policy page.", "One
1230
+ * moment while I look that up.", "Give me a second to check.", "I can look
1231
+ * that up.", "Step 1: fetch the policy page." — an acknowledgement before it
1232
+ * included ("Okay,", "Sure —", "Great question —", "To answer that,").
1233
+ * Printed before a tool call, it is narration, not an answer the reader is
1234
+ * handed. A gerund opener announces only while no verb of its own follows:
1235
+ * "Processing the refund takes a few days." states something.
1236
+ */
1237
+ const NARRATION = new RegExp([
1238
+ "^(?:(?: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",
1239
+ "|to (?:answer|check|confirm|find|look|do|help|get|figure|see|verify)\\b[^,.!?—–]{0,40})",
1240
+ "(?:\\s*[,!:—–-]\\s*|\\s+)){0,2}",
1241
+ "(?: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",
1242
+ "|i need to|i want to|i'd (?:like|need|want) to",
1243
+ `|i can (?:${FETCH_VERB})\\b`,
1244
+ "|i'm (?:now |first |just )?\\w+ing|i am (?:now |first |just )?\\w+ing",
1245
+ "|(?:just )?(?:one|a) (?:moment|sec(?:ond)?|minute)|give me (?:a|one) (?:moment|sec(?:ond)?|minute)",
1246
+ "|hold on|hang on|bear with me|stand by",
1247
+ `|step \\d+[:.)]\\s+(?:${ACTION_VERB})`,
1248
+ `|(?: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`,
1249
+ ].join(""), "i");
1250
+ /**
1251
+ * A word that makes what follows a narration opener a statement: a finite
1252
+ * "be" / "have" / "do", a modal, a negation's contraction, or a verb a
1253
+ * statement of fact is made with ("Of course, I'll note that refunds are not
1254
+ * allowed.", "Let me record that your plan costs $49 per month."). Narration
1255
+ * that only announces a call carries none of these: "Let me fetch the refund
1256
+ * policy page first." Third-person and past forms only, never a base verb
1257
+ * ("Let me take a look.", "I'll have a look."), and not "may", which is a
1258
+ * month as often ("Let me pull up your May invoice."). The list is closed on
1259
+ * purpose — a word it misses is caught by the clause rules below or graded
1260
+ * as written.
1261
+ */
1262
+ 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;
1263
+ /** "that" opening a clause with its own subject ("I'll note that the window …"), not "look that up". */
1264
+ 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;
1265
+ /** An embedded question: what follows it asks, and asserts nothing ("Let me check whether the refund has gone through."). */
1266
+ const ASKS = /\b(?:if|whether|what|which|where|when|how|who|whom)\b/i;
1267
+ /** Where a clause of its own may begin: a comma, colon or semicolon before a space, or a dash. */
1268
+ const CLAUSE_BREAK = /[,;:](?=\s)|\s[-–—]\s|[—–]/;
1269
+ /** A clause after a break that adds nothing a reader could check ("…, please.", "— one moment."). */
1270
+ 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;
1271
+ /** A clause after a break that goes on announcing a call ("…, then save a note."). */
1272
+ 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");
1273
+ /** Does `words` assert something, outside an embedded question it may end in? */
1274
+ function asserts(words) {
1275
+ const asked = ASKS.exec(words);
1276
+ const said = asked === null ? words : words.slice(0, asked.index);
1277
+ return STATES.test(said) || THAT_CLAUSE.test(said);
1278
+ }
1279
+ /**
1280
+ * Does a narration sentence state something beyond its announcement? What
1281
+ * follows the opener {@link NARRATION} matched is read clause by clause:
1282
+ * the announcement's own clause states something when it asserts
1283
+ * ({@link asserts}); every clause after a break ({@link CLAUSE_BREAK}) does
1284
+ * unless it is an afterthought, goes on announcing, or is narration itself.
1285
+ * "Hold on, refunds are not allowed on sale items.", "Looking at your
1286
+ * account, your refund went through yesterday." and "Pulling up your order
1287
+ * — it shipped Tuesday via UPS." state something; "Let me check the policy
1288
+ * page, then save a note." does not.
1289
+ */
1290
+ function statesSomething(plain, openerEnd) {
1291
+ const clauses = plain.slice(openerEnd).split(CLAUSE_BREAK);
1292
+ if (asserts(clauses[0] ?? ""))
1293
+ return true;
1294
+ for (const raw of clauses.slice(1)) {
1295
+ const clause = raw
1296
+ .trim()
1297
+ .replace(/[.!?…]+$/, "")
1298
+ .trim();
1299
+ if (clause === "" || AFTERTHOUGHT.test(clause))
1300
+ continue;
1301
+ if (asserts(clause))
1302
+ return true;
1303
+ if (ANNOUNCES_MORE.test(clause))
1304
+ continue;
1305
+ const opener = NARRATION.exec(clause);
1306
+ if (opener === null || statesSomething(clause, opener[0].length))
1307
+ return true;
1308
+ }
1309
+ return false;
1310
+ }
1311
+ /** A figure as written: a run of digits with its inner separators ("4512", "10:30", "1,284.50", "2025-01-31"). */
1312
+ const FIGURE = /\d+(?:[.,:/-]\d+)*/g;
1313
+ /**
1314
+ * A figure that names a thing rather than measures one: a label before it
1315
+ * ("section 4", "order #4512", "ticket 88", "v2") or a year ("the 2025
1316
+ * terms"). Narration that names one is still narration.
1317
+ */
1318
+ 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;
1319
+ /** Is the figure at `index` in `sentence` a name ({@link NAMING_LABEL}, a year)? */
1320
+ function namesAThing(sentence, figure, index) {
1321
+ return (/^(?:19|20)\d\d$/.test(figure) ||
1322
+ NAMING_LABEL.test(sentence.slice(Math.max(0, index - 16), index)));
1323
+ }
1324
+ /**
1325
+ * The figures `text` holds, each as written and each run of up to four of
1326
+ * its parts ("10:30:00" holds "10:30" and "30"): a narration's figure is
1327
+ * echoed when it is one of them. Built once, in one pass, so a long input or
1328
+ * tool call costs a set lookup per figure, not a scan.
1329
+ */
1330
+ function figuresIn(text, into = new Set()) {
1331
+ const out = into;
1332
+ for (const [figure] of text.matchAll(FIGURE)) {
1333
+ out.add(figure);
1334
+ // Digit runs at the even indexes, the separators between them at the odd.
1335
+ const parts = figure.split(/([.,:/-])/);
1336
+ for (let from = 0; from < parts.length; from += 2) {
1337
+ let window = parts[from] ?? "";
1338
+ out.add(window);
1339
+ for (let to = from + 2; to < parts.length && to < from + 8; to += 2) {
1340
+ window += `${parts[to - 1] ?? ""}${parts[to] ?? ""}`;
1341
+ out.add(window);
1342
+ }
1343
+ }
1344
+ }
1345
+ return out;
1346
+ }
1347
+ /**
1348
+ * The figures a tool call's input carries as values of their own: a number,
1349
+ * a string that is one figure ("10:30", "4512"), or a string with no space
1350
+ * in it (an id, a time, a URL or a path: "https://…/orders/4512"). A figure
1351
+ * inside free text the call is handed (a note's `text`, a message's
1352
+ * `body`) is the agent's own writing, not the call's argument: "I'll save a
1353
+ * note that the window is 30 days." with `{text: "Refund window: 30 days"}`
1354
+ * is graded. Walked to a bounded depth and breadth.
1355
+ */
1356
+ function callFigures(input, into, depth = 0) {
1357
+ if (depth > 8)
1358
+ return;
1359
+ if (typeof input === "number" && Number.isFinite(input)) {
1360
+ figuresIn(String(input), into);
1361
+ return;
1362
+ }
1363
+ if (typeof input === "string") {
1364
+ if (input.length <= 2048 && !/\s/.test(input.trim()))
1365
+ figuresIn(input, into);
1366
+ return;
1367
+ }
1368
+ if (typeof input !== "object" || input === null)
1369
+ return;
1370
+ const values = Array.isArray(input) ? input : Object.values(input);
1371
+ for (const value of values.slice(0, 256))
1372
+ callFigures(value, into, depth + 1);
1373
+ }
1374
+ /**
1375
+ * `text` with its narration sentences ({@link NARRATION}) taken out and the
1376
+ * rest exactly as written — its lines too, so a definition line stays one.
1377
+ * A sentence ends at a terminator that whitespace or the end follows, so a
1378
+ * URL's dots or a decimal point do not cut it in two. A narration sentence
1379
+ * with a marker in it stays, as does one with a figure the agent brings
1380
+ * itself ("Let me note: the window is 30 days.", "I'll double-check the
1381
+ * 30-day window."): that is a claim the reader was handed. A figure that
1382
+ * names a thing ({@link namesAThing}: "section 4", "the 2025 terms"), or
1383
+ * that `echo` holds ({@link figuresIn} the turn's own input, and the input
1384
+ * of the tool calls the narration announces) is the reader's or the call's,
1385
+ * not the agent's: "Let me book the 10:30 slot.", "Let me fetch
1386
+ * https://…/policy/2024." stay narration. None of that exempts a sentence
1387
+ * that states something past its announcement ({@link statesSomething}):
1388
+ * "Let me confirm — yes, the refund window is 30 days." is graded however
1389
+ * often the reader asked about 30 days.
1390
+ *
1391
+ * A sentence starts on a character that is no terminator, so a line of
1392
+ * terminators is never re-read from inside (each start position used to
1393
+ * walk the whole run again: quadratic on a long one); a run that opens a
1394
+ * line is kept as written.
1395
+ */
1396
+ function withoutNarration(text, echo) {
1397
+ return text
1398
+ .replace(/[^\n.!?…]+(?:[.!?…]+(?=[^\s.!?…])[^\n.!?…]*)*(?:[.!?…]+|$)/gm, (sentence) => {
1399
+ const plain = sentence
1400
+ .trim()
1401
+ .replace(/^[*_>#\s-]+/, "")
1402
+ .replace(/’/g, "'");
1403
+ if (plain === "" || plain.includes("["))
1404
+ return sentence;
1405
+ const opener = NARRATION.exec(plain);
1406
+ if (opener === null || statesSomething(plain, opener[0].length))
1407
+ return sentence;
1408
+ for (const found of plain.matchAll(FIGURE)) {
1409
+ const figure = found[0];
1410
+ if (!namesAThing(plain, figure, found.index) && !echo.some((held) => held.has(figure))) {
1411
+ return sentence;
1412
+ }
1413
+ }
1414
+ return "";
1415
+ })
1416
+ .replace(/[ \t]+$/gm, "")
1417
+ .trim();
1418
+ }
929
1419
  export async function runChatLoop(opts) {
1420
+ // A `channel` or `managed` run answers people other than its operator, so it
1421
+ // and the loops it starts (a sub-agent, a consult) share one scope, and each
1422
+ // keeps the credential files from its tools (`./state-roots`).
1423
+ if ((opts.sessionTarget === "channel" || opts.sessionTarget === "managed") &&
1424
+ credentialFloorScope.getStore() !== true) {
1425
+ return credentialFloorScope.run(true, () => runChatLoop(opts));
1426
+ }
930
1427
  // Item 3 (G32) — resolve the advertised tool set ONCE, up front, folding in
931
1428
  // any plugin-contributed tools so the tool-capable-model feature gate and the
932
1429
  // per-turn advertisement below read the same list.
933
1430
  // 0.6.0 — then the hybrid-strategy tools (`Consult` / `Escalate`) the
934
1431
  // composition root registered, same first-party-wins posture.
935
- const mergedTools = mergeEffectiveTools(mergeEffectiveTools(opts.tools ?? [], opts.plugins?.tools), opts.hybridTools);
1432
+ const mergedTools = mergeEffectiveTools(mergeEffectiveTools(opts.tools ?? [], opts.plugins?.tools, new Set(LOOP_TOOL_NAMES)), opts.hybridTools);
936
1433
  // #405 — the runtime's own toolset-introspection tool rides every
937
1434
  // TOOL-CARRYING loop. Late-bound: it is part of the list it reports, so it
938
1435
  // reads the advertised summaries assigned after that list is built below.
@@ -1037,6 +1534,44 @@ export async function runChatLoop(opts) {
1037
1534
  if (effectiveTools.length > 0 && adapter.features.tool_use === false) {
1038
1535
  throw new ConfigError(`model "${opts.model}" (provider ${providerId}) does not support tool use — remove tools or pick a tool-capable model`);
1039
1536
  }
1537
+ // provider-limits#0 — the same fail-early rule for the tool COUNT: OpenAI
1538
+ // (and Azure OpenAI, Groq) refuse more than 128 tools on one request,
1539
+ // Gemini more than 512, and they refuse every request of the run. The list
1540
+ // is final here (builtins, loop tools, MCP, plugin and hybrid tools), so
1541
+ // this is the check `--model` overrides and MCP servers cannot slip past.
1542
+ // A pool is checked per candidate below, once each candidate's subset is
1543
+ // known.
1544
+ if (opts.modelPool === undefined) {
1545
+ const count = effectiveTools.length;
1546
+ const serving = opts.modelTiers !== undefined
1547
+ ? ["fast", "default"].map((tier) => {
1548
+ const model = opts.modelTiers[tier];
1549
+ return {
1550
+ model,
1551
+ toolCount: count,
1552
+ role: "serves",
1553
+ label: `model_tiers.${tier} "${model}"`,
1554
+ whenOver: `the run starts, and every turn routed to the ${tier} tier fails`,
1555
+ };
1556
+ })
1557
+ : [opts.model, ...modelFallbacks].map((model, i) => ({
1558
+ model,
1559
+ toolCount: count,
1560
+ role: "serves",
1561
+ label: i === 0 ? `model "${model}"` : `model_fallbacks[${i - 1}] "${model}"`,
1562
+ whenOver: "the run starts because another model in the chain can serve",
1563
+ }));
1564
+ if (opts.budget?.onExceed.kind === "degrade") {
1565
+ serving.push({
1566
+ model: opts.budget.onExceed.model,
1567
+ toolCount: count,
1568
+ role: "degrade",
1569
+ label: `budget degrade model "${opts.budget.onExceed.model}"`,
1570
+ whenOver: "a budget degrade to it would fail every call",
1571
+ });
1572
+ }
1573
+ reportToolLimits(checkServingToolLimits(serving, process.env));
1574
+ }
1040
1575
  let compactionAdapter;
1041
1576
  let compactionWireModelId;
1042
1577
  if (opts._compactionAdapter !== undefined) {
@@ -1171,7 +1706,82 @@ export async function runChatLoop(opts) {
1171
1706
  if (opts.sideCalls?.committee !== undefined && opts.singleTurn !== true) {
1172
1707
  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
1708
  }
1709
+ reportWorkspaceHoldsHome();
1174
1710
  const sessionRootDir = resolveSessionRootDir(opts.sessionRootDir);
1711
+ // 0.8.0 (design §1 principle 1, §5.2) — the session logs, the spilled
1712
+ // tool results and the proof bundles this run's gates read as evidence: no
1713
+ // tool call the agent makes may write there, whatever a rule says
1714
+ // (permission-engine's runtime-state floor, `./state-roots`).
1715
+ const protectedRoots = runtimeStateRoots(sessionRootDir, currentTenantContext()?.tenant);
1716
+ const credentialRoots = credentialFloorScope.getStore() === true ? credentialFileRoots() : undefined;
1717
+ const recordRoots = runtimeRecordRoots(sessionRootDir, currentTenantContext()?.tenant);
1718
+ /**
1719
+ * The floor's reading of a call: where it WRITES. Two kinds of field are
1720
+ * left out, field by field:
1721
+ *
1722
+ * - one declared `relocates` that names a store the tool works in through
1723
+ * its own format inside the run's record (EmitTraceEvent's namespaced
1724
+ * `custom.*` lines) or in the gate record that is its own store
1725
+ * (DatasetPut's versions, EvalBaselinePin's pins), or one it reads whole
1726
+ * (IncidentBundle's sessions). A store anywhere else is read as any path
1727
+ * is (`relocatingFieldLeftOut`, `./state-roots`);
1728
+ * - one declared `source` holds where the tool takes a value FROM (the
1729
+ * files IndexBuild indexes, the file DatasetPut reads, the reference
1730
+ * EnvFileUpsert copies a secret out of): reading a spilled output or a
1731
+ * session log forges nothing, and the runtime itself points the model
1732
+ * at a spill (`[truncated, full output at …]`), so a copy, an index or
1733
+ * an import of one is no write into the record (§1 principle 3: the
1734
+ * floor must not refuse what a harness without the block could do).
1735
+ *
1736
+ * - one declared `reads` (or `readsWhen`, when the call names the field
1737
+ * it names) the tool only reads, writing where another field says:
1738
+ * CopyPath's and ArchiveCreate's `source`, ArchiveExtract's `archive`,
1739
+ * an importer's `file`. A backup of `.crewhaus` copies the record; it
1740
+ * writes none of it. MovePath's `source` is not one: a move takes it
1741
+ * away.
1742
+ *
1743
+ * Every other operative value counts — a secret reference's file included
1744
+ * (SecretRotate's `ref` names the file it writes). `undefined` ⇒ the
1745
+ * call's operative values as they are (a tool with neither kind of field).
1746
+ *
1747
+ * A tool that declares `[]` says no argument decides where it acts: what it
1748
+ * carries is text (a memory, a plan step, a clipboard's contents), so the
1749
+ * floor reads none of it as a path. One that declares nothing (an MCP or
1750
+ * plugin tool) says nothing, and the floor reads every string it carries.
1751
+ */
1752
+ const floorValuesOf = (tool, parsedInput) => {
1753
+ const args = tool.operativeArgs;
1754
+ if (args !== undefined && args.length === 0)
1755
+ return [];
1756
+ const named = (name) => {
1757
+ if (typeof parsedInput !== "object" || parsedInput === null)
1758
+ return false;
1759
+ const value = parsedInput[name];
1760
+ return value !== undefined && value !== null && value !== "";
1761
+ };
1762
+ const skipped = (arg) => (arg.relocates === true &&
1763
+ relocatingFieldLeftOut(arg, parsedInput, recordRoots, protectedRoots)) ||
1764
+ arg.source === true ||
1765
+ arg.reads === true ||
1766
+ (arg.readsWhen !== undefined && named(arg.readsWhen));
1767
+ if (args === undefined || !args.some(skipped))
1768
+ return undefined;
1769
+ const written = args.filter((arg) => !skipped(arg));
1770
+ if (written.length === 0)
1771
+ return [];
1772
+ return (operativeValuesFor({ ...tool, operativeArgs: written }, parsedInput, {
1773
+ canonicalizePath: placeRecordingCanonicalizer().canonicalizePath,
1774
+ }) ?? []);
1775
+ };
1776
+ /**
1777
+ * `floorValues` as a gate hands them to the engine: `floorValuesOf` for a call
1778
+ * that writes, and for a tool that declares `[]` whatever it does, since the
1779
+ * engine reads that empty list as "this call carries text" when it looks for a
1780
+ * credential file.
1781
+ */
1782
+ const gateFloorValues = (tool, parsedInput) => tool.readOnly && tool.operativeArgs?.length !== 0
1783
+ ? undefined
1784
+ : floorValuesOf(tool, parsedInput);
1175
1785
  const sessionStore = persistSession
1176
1786
  ? createSessionStore({ rootDir: sessionRootDir })
1177
1787
  : createMemorySessionStore();
@@ -1594,6 +2204,14 @@ export async function runChatLoop(opts) {
1594
2204
  // the cap bounds the conversation rather than one resumed run. Stays 0
1595
2205
  // under the default `run` scope.
1596
2206
  let resumedCostUsdMicros = 0;
2207
+ // 0.8.0 (design §5.3) — the turns the resumed session already ran. The
2208
+ // run's own counter (`runContext.turnNumber`) restarts at 0 on every run,
2209
+ // and every channel message after a thread's first, every managed
2210
+ // `runs.continue` and every `--resume` is a new run; a proof bundle is
2211
+ // filed per SESSION turn (`<sessionId>/turn-<n>.json`, the audit artifact),
2212
+ // so the gate numbers its turns from here (`provabilityTurn`). Nothing else
2213
+ // reads it: the run-local counter keeps its meaning everywhere else.
2214
+ let resumedTurns = 0;
1597
2215
  const budgetSessionScoped = opts.budget?.scope === "session";
1598
2216
  if (opts.resume) {
1599
2217
  const existing = await sessionStore.get(opts.resume.sessionId);
@@ -1605,6 +2223,7 @@ export async function runChatLoop(opts) {
1605
2223
  resumedPin = existing.pin;
1606
2224
  const replayLog = await openEventLog(sessionId, { rootDir: sessionRootDir });
1607
2225
  resumedMessages = await replayMessageHistory(replayLog);
2226
+ resumedTurns = openedTurnCount(resumedMessages);
1608
2227
  // One pass gathers both resume-time reads: the continuity ledger seed
1609
2228
  // (conditional) and the LAST recorded toolset (#405 — unconditional, so
1610
2229
  // the marker below can tell a resumed session its capabilities changed
@@ -1616,6 +2235,8 @@ export async function runChatLoop(opts) {
1616
2235
  // must not be mistaken for this context's previous one.
1617
2236
  let nestDepth = 0;
1618
2237
  for await (const ev of replayLog.read()) {
2238
+ if (!isRuntimeLogLine(ev))
2239
+ continue;
1619
2240
  if (ev.kind === "a2a_turn_start" || ev.kind === "sub_agent_start") {
1620
2241
  nestDepth += 1;
1621
2242
  continue;
@@ -1659,6 +2280,8 @@ export async function runChatLoop(opts) {
1659
2280
  if (!wantLedger || ev.kind !== "context_evicted")
1660
2281
  continue;
1661
2282
  const p = ev.payload;
2283
+ if (p.synthetic === true)
2284
+ continue;
1662
2285
  if (p.role === "user" && typeof p.text === "string") {
1663
2286
  resumedLedgerSeed.push({
1664
2287
  role: "user",
@@ -1700,6 +2323,8 @@ export async function runChatLoop(opts) {
1700
2323
  return createRunContext({ runId, sessionId, eventBus });
1701
2324
  })()
1702
2325
  : createRunContext({ sessionId }));
2326
+ if (resumedMessages !== undefined)
2327
+ tagReplayedToolResults(runContext, resumedMessages);
1703
2328
  // G01 — surface the max-tokens lift once, at boot (see `effectiveMaxTokens`).
1704
2329
  if (effectiveMaxTokens !== maxTokens) {
1705
2330
  runContext.logger.info("thinking budget >= max_tokens — lifting the per-request ceiling", {
@@ -1978,18 +2603,30 @@ export async function runChatLoop(opts) {
1978
2603
  const mdRenderer = isCliMarkdownEnabled()
1979
2604
  ? createCliMarkdownRenderer({ write: (s) => out.write(s) })
1980
2605
  : undefined;
2606
+ const printText = (chunk) => {
2607
+ if (mdRenderer)
2608
+ mdRenderer.push(chunk);
2609
+ else
2610
+ out.write(chunk);
2611
+ };
2612
+ // 0.8.0 (design §1 principle 2, §5.4) — under `provability:` a line of the
2613
+ // answer shaped like the gate's footer streams with a mark saying the model
2614
+ // wrote it (`./forged-footer`): the one verdict line the reader sees is the
2615
+ // gate's. Without the block the text streams exactly as before.
2616
+ const footerGuard = opts.provability !== undefined ? createFooterLineGuard(printText) : undefined;
1981
2617
  const writeText = (chunk) => {
1982
2618
  // First real assistant text ends the "thinking" wait; clear the spinner
1983
2619
  // (idempotent on later chunks) before the answer streams.
1984
2620
  out.spinner.stop();
1985
- if (mdRenderer)
1986
- mdRenderer.push(chunk);
2621
+ if (footerGuard !== undefined)
2622
+ footerGuard.push(chunk);
1987
2623
  else
1988
- out.write(chunk);
2624
+ printText(chunk);
1989
2625
  };
1990
2626
  const endTurn = () => {
1991
2627
  // Covers the no-text/no-tool case where the spinner is still up.
1992
2628
  out.spinner.stop();
2629
+ footerGuard?.end();
1993
2630
  if (mdRenderer)
1994
2631
  mdRenderer.end();
1995
2632
  out.write("\n");
@@ -2059,6 +2696,33 @@ export async function runChatLoop(opts) {
2059
2696
  }));
2060
2697
  }
2061
2698
  const armIdOf = (candidate) => poolCandidateConfigs.get(candidate)?.profile ?? candidate.modelString;
2699
+ // provider-limits#0 — each pool candidate against its provider's
2700
+ // per-request tool limit, counted on the subset IT is advertised. One over
2701
+ // its limit is left out of routing (the `tool-limit` eligibility exclusion
2702
+ // in preRoute); a pool none of whose candidates can accept its tools
2703
+ // cannot make one call, and stops here.
2704
+ if (poolRouter !== undefined) {
2705
+ const serving = [];
2706
+ for (const [candidate, ad] of candidateAdvertisements) {
2707
+ serving.push({
2708
+ model: candidate.modelString,
2709
+ toolCount: ad.names.size,
2710
+ role: "serves",
2711
+ label: `model_pool candidate "${armIdOf(candidate)}"`,
2712
+ whenOver: "routing leaves it out",
2713
+ });
2714
+ }
2715
+ if (budgetDegradeRung !== undefined && !candidateAdvertisements.has(budgetDegradeRung)) {
2716
+ serving.push({
2717
+ model: budgetDegradeRung.modelString,
2718
+ toolCount: effectiveTools.length,
2719
+ role: "degrade",
2720
+ label: `budget degrade model "${budgetDegradeRung.modelString}"`,
2721
+ whenOver: "a budget degrade to it would fail every call",
2722
+ });
2723
+ }
2724
+ reportToolLimits(checkServingToolLimits(serving, process.env));
2725
+ }
2062
2726
  {
2063
2727
  const currentToolNames = [...effectiveTools.map((t) => t.name)].sort();
2064
2728
  const prior = resumedToolNames === undefined ? undefined : [...resumedToolNames].sort();
@@ -2290,8 +2954,8 @@ export async function runChatLoop(opts) {
2290
2954
  // -------------------------------------------------------------------------
2291
2955
  const continuity = opts.continuity;
2292
2956
  const continuityLedgerEnabled = continuity !== undefined && continuity.ledger !== false;
2293
- // The in-run requirements ledger: evicted USER messages, oldest-first,
2294
- // verbatim. `ledgerTruncated` flags that oldest entries were dropped at
2957
+ // The in-run requirements ledger: evicted USER messages the runtime did not
2958
+ // write, oldest-first, verbatim. `ledgerTruncated` flags that oldest entries were dropped at
2295
2959
  // the CONTINUITY_LEDGER_MAX_CHARS cap so the rendered block says so.
2296
2960
  const ledgerEntries = [];
2297
2961
  let ledgerTruncated = false;
@@ -2330,19 +2994,23 @@ export async function runChatLoop(opts) {
2330
2994
  * text-bearing record is appended verbatim to the session event log as
2331
2995
  * `context_evicted` (zero model trust — the recall integration comes in a
2332
2996
  * later PR); user records additionally fold into the in-run ledger for
2333
- * per-call reinjection.
2997
+ * per-call reinjection. A turn the runtime wrote (a grader's correction, a
2998
+ * retry or loop nudge) is logged with `synthetic: true` and stays out of the
2999
+ * ledger.
2334
3000
  */
2335
3001
  const externalizeEvicted = async (evicted) => {
2336
3002
  if (!continuityLedgerEnabled)
2337
3003
  return;
2338
3004
  for (const message of evicted) {
3005
+ const runtimeAuthored = isSyntheticMessage(message);
2339
3006
  for (const entry of extractEvictedEntries(message)) {
2340
3007
  await logEvent("context_evicted", {
2341
3008
  role: entry.role,
2342
3009
  text: entry.text,
2343
3010
  ...(entry.turnNumber !== undefined ? { turnNumber: entry.turnNumber } : {}),
3011
+ ...(runtimeAuthored ? { synthetic: true } : {}),
2344
3012
  });
2345
- if (entry.role === "user")
3013
+ if (entry.role === "user" && !runtimeAuthored)
2346
3014
  foldLedgerEntry(entry);
2347
3015
  }
2348
3016
  }
@@ -2520,6 +3188,18 @@ export async function runChatLoop(opts) {
2520
3188
  }
2521
3189
  : undefined;
2522
3190
  const bridgeContinuitySeam = opts.continuity !== undefined ? { loadPlan: opts.continuity.loadPlan } : undefined;
3191
+ // - provability: READ-ONLY (0.8.0 §8). The floor and the skill text cross;
3192
+ // the verifier, the retry policy and the bundle store stay parent-side,
3193
+ // so only this loop's final text is ever gated.
3194
+ const bridgeProvabilitySeam = opts.provability !== undefined
3195
+ ? {
3196
+ level: opts.provability.level,
3197
+ ...(opts.provability.skill !== undefined ? { skill: opts.provability.skill } : {}),
3198
+ }
3199
+ : undefined;
3200
+ // 0.7.1 — the models this run may name, so a sub-agent read from disk can
3201
+ // run on the parent's fallback or tier model, and on nothing unnamed.
3202
+ const bridgeSpecModels = specModelsOf(opts);
2523
3203
  // M3.1 — auto-load project memory files (AGENTS.md / CLAUDE.md /
2524
3204
  // CODE-COMPANION.md / AGENT.md) from cwd at session start. Follows the
2525
3205
  // vendor-neutral agents.md convention; compatible with Claude Code's
@@ -2564,11 +3244,11 @@ export async function runChatLoop(opts) {
2564
3244
  const seed = opts.memory.recallSeed ?? opts.instructions;
2565
3245
  const k = opts.memory.recallK ?? 5;
2566
3246
  // 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).
3247
+ // tool output from an earlier session; `renderRecalledMemory` classifies
3248
+ // each line at TrustOrigin "memory" (redacting a malicious one),
3249
+ // lineage-tags the admitted lines, and neutralizes breakout delimiters.
2570
3250
  const lines = await opts.memory.recall(seed, k);
2571
- const text = await renderRecalledMemory(lines);
3251
+ const text = await renderRecalledMemory(lines, runContext);
2572
3252
  if (text !== undefined) {
2573
3253
  memoryRecallBlock = [{ type: "text", text, cache_control: { type: "ephemeral" } }];
2574
3254
  out.write(`[memory] recalled ${lines.length} memory(ies) into the prompt\n`);
@@ -2603,7 +3283,7 @@ export async function runChatLoop(opts) {
2603
3283
  const k = opts.memory?.recallK ?? 5;
2604
3284
  try {
2605
3285
  const lines = await recall(query, k);
2606
- const text = await renderRecalledMemory(lines);
3286
+ const text = await renderRecalledMemory(lines, runContext);
2607
3287
  volatileRecallBlocks = text !== undefined ? [{ type: "text", text }] : [];
2608
3288
  if (lines.length > 0) {
2609
3289
  out.write(`[memory] refreshed ${lines.length} recalled memory(ies) for this turn\n`);
@@ -2718,6 +3398,11 @@ export async function runChatLoop(opts) {
2718
3398
  // #400 — approval ids this RUN has already replayed. Claimed synchronously
2719
3399
  // so two concurrent tool calls cannot both spend one one-shot grant.
2720
3400
  const replayedApprovalIds = new Set();
3401
+ // Grants an approved call holds between the gate that honoured them and the
3402
+ // last gate that can still refuse it, the rate gate, after which it spends
3403
+ // them. A parallel call must not run under one meanwhile, as a spent grant
3404
+ // would not let it.
3405
+ const grantsInFlight = new Set();
2721
3406
  const justificationInjectedTools = new Set(advertisedTools
2722
3407
  .filter(({ advertised }) => advertised.justificationInjected)
2723
3408
  .map(({ tool }) => tool.name));
@@ -2735,7 +3420,12 @@ export async function runChatLoop(opts) {
2735
3420
  // gates the acquire call site: tools outside the map (no named entry, no
2736
3421
  // `"*"`) are not rate-gated at all — the limiter itself is fail-closed on
2737
3422
  // unknown keys, so the guard is what keeps unlisted tools ungated.
2738
- const rateLimitEntries = Object.entries(opts.rateLimits ?? {});
3423
+ // 0.7.1 — MCP tools are registered as `mcp__<server>__<tool>`; a limit a
3424
+ // spec wrote against the old `<server>__<tool>` spelling is re-keyed onto
3425
+ // the registered name so it keeps applying.
3426
+ const toolNamesAtStart = new Set(tools.map((t) => t.name));
3427
+ const runRateLimits = rekeyLegacyMcpToolKeys(opts.rateLimits, toolNamesAtStart);
3428
+ const rateLimitEntries = Object.entries(runRateLimits ?? {});
2739
3429
  let toolRateLimiter;
2740
3430
  if (rateLimitEntries.length > 0) {
2741
3431
  const buckets = new Map();
@@ -2748,8 +3438,8 @@ export async function runChatLoop(opts) {
2748
3438
  }
2749
3439
  toolRateLimiter = createRateLimiter({ buckets });
2750
3440
  }
2751
- const hasToolRateBucket = (toolName) => opts.rateLimits !== undefined &&
2752
- (opts.rateLimits[toolName] !== undefined || opts.rateLimits["*"] !== undefined);
3441
+ const hasToolRateBucket = (toolName) => runRateLimits !== undefined &&
3442
+ (ownLimit(runRateLimits, toolName) || ownLimit(runRateLimits, "*"));
2753
3443
  // -------------------------------------------------------------------------
2754
3444
  // 0.6.0 §4.4 — the per-candidate plan table. One plan per enabled pool
2755
3445
  // candidate (plus the degrade rung when it sits outside the roster), built
@@ -2795,7 +3485,8 @@ export async function runChatLoop(opts) {
2795
3485
  };
2796
3486
  const deny = cfg?.permissions?.deny ?? [];
2797
3487
  const ask = cfg?.permissions?.ask ?? [];
2798
- const rateEntries = Object.entries(cfg?.rateLimits ?? {});
3488
+ const planRateLimits = rekeyLegacyMcpToolKeys(cfg?.rateLimits, toolNamesAtStart);
3489
+ const rateEntries = Object.entries(planRateLimits ?? {});
2799
3490
  const armId = fromPool ? (cfg.profile ?? cfg.model) : (candidate?.modelString ?? opts.model);
2800
3491
  let planLimiter;
2801
3492
  if (rateEntries.length > 0) {
@@ -2812,7 +3503,6 @@ export async function runChatLoop(opts) {
2812
3503
  }
2813
3504
  planLimiter = createRateLimiter({ buckets });
2814
3505
  }
2815
- const planRateLimits = cfg?.rateLimits;
2816
3506
  const names = new Set(planAdvertised.map(({ tool }) => tool.name));
2817
3507
  return {
2818
3508
  armId,
@@ -2840,8 +3530,16 @@ export async function runChatLoop(opts) {
2840
3530
  permissionRules: fromPool ? narrowRuleSet(permissionRules, deny, ask) : permissionRules,
2841
3531
  ...(planLimiter !== undefined ? { toolRateLimiter: planLimiter } : {}),
2842
3532
  hasToolRateBucket: (toolName) => planRateLimits !== undefined &&
2843
- (planRateLimits[toolName] !== undefined || planRateLimits["*"] !== undefined),
2844
- ...(cfg?.toolConfigs !== undefined ? { toolConfigs: cfg.toolConfigs } : {}),
3533
+ (ownLimit(planRateLimits, toolName) || ownLimit(planRateLimits, "*")),
3534
+ // `$VAR` values in a candidate's tool_config are read from the
3535
+ // environment here, when the loop starts, as the boot registrations
3536
+ // read theirs — never compiled into the bundle. An unset one fails
3537
+ // the start and names the variable.
3538
+ ...(cfg?.toolConfigs !== undefined
3539
+ ? {
3540
+ toolConfigs: resolveToolConfigEnv(cfg.toolConfigs, `model_pool candidate ${cfg.profile ?? candidate?.modelString ?? opts.model} tool_config`, process.env).value,
3541
+ }
3542
+ : {}),
2845
3543
  ...(cfg?.overlay !== undefined
2846
3544
  ? { overlayBlock: { type: "text", text: cfg.overlay } }
2847
3545
  : {}),
@@ -3275,7 +3973,7 @@ export async function runChatLoop(opts) {
3275
3973
  // the prior turn in some streaming scenarios).
3276
3974
  const post = await fireHook("post-tool", {
3277
3975
  id: tu.id,
3278
- name: tu.name,
3976
+ ...hookToolName(tu.name),
3279
3977
  isError: result.is_error === true,
3280
3978
  });
3281
3979
  if (!post.allowed) {
@@ -3314,7 +4012,11 @@ export async function runChatLoop(opts) {
3314
4012
  }
3315
4013
  // Section 11 — pre-tool hook: short-circuit with the hook's reason
3316
4014
  // when any matching hook returns deny/block.
3317
- const preHook = await fireHook("pre-tool", { id: tu.id, name: tu.name, input: tu.input });
4015
+ const preHook = await fireHook("pre-tool", {
4016
+ id: tu.id,
4017
+ ...hookToolName(tu.name),
4018
+ input: tu.input,
4019
+ });
3318
4020
  if (!preHook.allowed) {
3319
4021
  return finish({
3320
4022
  type: "tool_result",
@@ -3330,17 +4032,64 @@ export async function runChatLoop(opts) {
3330
4032
  // this; surfaces that record what the model DID keep `tu.input`. See the
3331
4033
  // `justificationInjectedTools` comment at loop start for the full split.
3332
4034
  let operativeInput = operativeToolInput(tu.name, tu.input);
4035
+ // 0.7.1 — rules are checked against the call the tool will RUN: the
4036
+ // input parsed by the tool's own schema (unknown keys stripped, defaults
4037
+ // filled in) and the tool's declared operative values canonicalised
4038
+ // (paths resolved against the workspace, URLs parsed). Matching the raw
4039
+ // input let a decoy key, an extra argument, an omitted default, a `..` or
4040
+ // a symlinked directory walk past a rule. An input the schema rejects
4041
+ // could not run anyway, so it is denied here with the schema's message,
4042
+ // before any approval is asked for. Paths are resolved against the
4043
+ // current working directory, the root every workspace tool resolves
4044
+ // against when it runs.
4045
+ //
4046
+ // The canonicaliser also keeps a record of every path it read and where
4047
+ // each one landed: a headless approval is bound to it (see
4048
+ // `landsWhereApproved`).
4049
+ //
4050
+ // The tool's `tool_config` block on the serving candidate is the one it
4051
+ // will run with: a code host reads from it which API a call that names
4052
+ // none goes to, so a rule written on that host meets the call.
4053
+ const gateView = placeRecordingCanonicalizer();
4054
+ const gateToolConfig = toolConfigFor(servingPlan.toolConfigs, tu.name);
4055
+ const subject = preparePermissionSubject(tool, operativeInput, {
4056
+ canonicalizePath: gateView.canonicalizePath,
4057
+ readProgramPath: gateView.readProgramPath,
4058
+ ...(gateToolConfig !== undefined ? { toolConfig: gateToolConfig } : {}),
4059
+ });
4060
+ if (!subject.ok) {
4061
+ // Not a permission decision: no rule was consulted, and the call fails
4062
+ // the way a malformed call always has — an `is_error` tool result, with
4063
+ // `tool_call_end` recording it. Publishing it as a `permission_decision`
4064
+ // deny would count every malformed call as a policy denial (eval
4065
+ // safety_violations, the deny alerts and SLOs).
4066
+ return finish({
4067
+ type: "tool_result",
4068
+ tool_use_id: tu.id,
4069
+ content: subject.reason,
4070
+ is_error: true,
4071
+ });
4072
+ }
3333
4073
  // 0.6.0 §4.4 — the SERVING candidate's rule set: the run's rules narrowed
3334
4074
  // by the profile's `permissions.deny` / `.ask` through `narrowRuleSet`
3335
4075
  // (a decision-level meet — a profile can only tighten). The primary plan
3336
4076
  // carries the run's rules by reference, so a single-model run is unchanged.
4077
+ const floorValues = gateFloorValues(tool, subject.input);
3337
4078
  const decisionDetails = evaluateWithReason({
3338
4079
  toolName: tu.name,
3339
- input: operativeInput,
4080
+ input: subject.input,
4081
+ ...(subject.operativeValues !== undefined
4082
+ ? { operativeValues: subject.operativeValues }
4083
+ : {}),
4084
+ ...(floorValues !== undefined ? { floorValues } : {}),
3340
4085
  readOnly: tool.readOnly,
3341
4086
  destructive: tool.destructive,
3342
4087
  requiresSandbox: tool.requiresSandbox,
3343
- }, permissionMode, servingPlan.permissionRules, { sandboxAvailable: opts.sandboxAvailable === true });
4088
+ }, permissionMode, servingPlan.permissionRules, {
4089
+ sandboxAvailable: opts.sandboxAvailable === true,
4090
+ protectedRoots,
4091
+ ...(credentialRoots !== undefined ? { credentialRoots } : {}),
4092
+ });
3344
4093
  const decision = decisionDetails.decision;
3345
4094
  bus.publish({
3346
4095
  ...bus.envelope(),
@@ -3353,6 +4102,26 @@ export async function runChatLoop(opts) {
3353
4102
  });
3354
4103
  let approved = decision === "allow";
3355
4104
  let denialMessage;
4105
+ // The store grant this call runs under, spent once it has passed every
4106
+ // check below that can refuse it; `release` lets it go unspent.
4107
+ let heldGrant;
4108
+ // Held synchronously, so a parallel identical call cannot run under it too.
4109
+ const holdGrant = (grant, store) => {
4110
+ grantsInFlight.add(grant.id);
4111
+ return {
4112
+ approvalId: grant.id,
4113
+ spend: async () => {
4114
+ await store.persist({ ...grant, consumedAt: new Date().toISOString() });
4115
+ grantsInFlight.delete(grant.id);
4116
+ },
4117
+ // A refused call can be retried, and the same refusal answers it
4118
+ // without a new card for the operator.
4119
+ release: () => {
4120
+ grantsInFlight.delete(grant.id);
4121
+ replayedApprovalIds.delete(grant.id);
4122
+ },
4123
+ };
4124
+ };
3356
4125
  if (decision === "deny") {
3357
4126
  denialMessage = decisionDetails.reason ?? "tool denied by permission policy";
3358
4127
  }
@@ -3373,6 +4142,36 @@ export async function runChatLoop(opts) {
3373
4142
  // below so the approving operator SEES the justification.
3374
4143
  const inputHash = hashApprovalInput(tu.name, operativeInput);
3375
4144
  let existing = await approvals.store.get(tu.name, inputHash);
4145
+ // 0.7.1 — an approval parked before MCP tools were renamed is keyed on
4146
+ // the old `<server>__<tool>` spelling, and the operator may already
4147
+ // have granted it. Honour it (or re-use it while still pending)
4148
+ // rather than parking the same call again under a new id.
4149
+ const legacyToolName = legacyMcpToolName(tu.name);
4150
+ const approvalKeys = [[tu.name, inputHash]];
4151
+ if (legacyToolName !== undefined) {
4152
+ approvalKeys.push([legacyToolName, hashApprovalInput(legacyToolName, operativeInput)]);
4153
+ }
4154
+ if (existing === null && legacyToolName !== undefined) {
4155
+ existing = await approvals.store.get(legacyToolName, hashApprovalInput(legacyToolName, operativeInput));
4156
+ }
4157
+ // 0.7.1 — A GRANT COVERS THE PLACE IT WAS MADE FOR. The record is
4158
+ // keyed on the input, but a symlink moved since the park (by any
4159
+ // allowed call in the resumed turn) sends the same input somewhere
4160
+ // else. A grant, or a park to re-use, made where the call no longer
4161
+ // lands decides nothing here, and the newest record made where it
4162
+ // does land, if any, takes its place; otherwise the call is asked
4163
+ // again below. A DENY is honoured wherever the call lands: it can
4164
+ // only refuse, so asking again would add a prompt (and a chance of a
4165
+ // mistaken grant) for an action the operator already turned down.
4166
+ let movedFrom;
4167
+ if (existing !== null &&
4168
+ existing.decision !== "deny" &&
4169
+ !landsWhereApproved(existing, gateView)) {
4170
+ movedFrom = existing;
4171
+ existing = await findApprovalForPlace(approvals.store, approvalKeys, gateView);
4172
+ }
4173
+ if (existing?.decision === "grant" && grantsInFlight.has(existing.id))
4174
+ existing = null;
3376
4175
  // #400 — THE RESUMED CALL IS NOT THE PARKED CALL.
3377
4176
  //
3378
4177
  // A grant is keyed on whole-input equality, which silently assumes the
@@ -3395,6 +4194,7 @@ export async function runChatLoop(opts) {
3395
4194
  // card, and that action is what executes. Honouring the grant for the
3396
4195
  // regenerated input instead would let a re-worded `place_call` dial a
3397
4196
  // different number under an approval for the first.
4197
+ let replaySubject;
3398
4198
  if (existing === null) {
3399
4199
  const replay = await findReplayableGrant(approvals.store, {
3400
4200
  toolName: tu.name,
@@ -3408,10 +4208,30 @@ export async function runChatLoop(opts) {
3408
4208
  // calls both find the same unconsumed grant and both execute. The
3409
4209
  // set is per-run and in-process, which is where that race is;
3410
4210
  // across processes the store's `consumedAt` remains the authority.
3411
- if (replay !== undefined && !replayedApprovalIds.has(replay.id)) {
3412
- replayedApprovalIds.add(replay.id);
3413
- replayedFrom = replay;
3414
- existing = replay;
4211
+ //
4212
+ // 0.7.1 — and bound like the exact match: the APPROVED input must
4213
+ // still land where it did when the operator approved it. Read here,
4214
+ // once, and re-checked against policy below from this same reading.
4215
+ if (replay !== undefined &&
4216
+ !replayedApprovalIds.has(replay.id) &&
4217
+ !grantsInFlight.has(replay.id)) {
4218
+ const replayView = placeRecordingCanonicalizer();
4219
+ const subjectOfReplay = preparePermissionSubject(tool, operativeToolInput(tu.name, replay.input), {
4220
+ canonicalizePath: replayView.canonicalizePath,
4221
+ readProgramPath: replayView.readProgramPath,
4222
+ ...(gateToolConfig !== undefined ? { toolConfig: gateToolConfig } : {}),
4223
+ });
4224
+ // An approved input that no longer parses is denied by the
4225
+ // re-check below, as before; it has no place to compare.
4226
+ if (!subjectOfReplay.ok || landsWhereApproved(replay, replayView)) {
4227
+ replayedApprovalIds.add(replay.id);
4228
+ replayedFrom = replay;
4229
+ replaySubject = subjectOfReplay;
4230
+ existing = replay;
4231
+ }
4232
+ else {
4233
+ movedFrom ??= replay;
4234
+ }
3415
4235
  }
3416
4236
  }
3417
4237
  if (existing?.decision === "grant") {
@@ -3438,13 +4258,36 @@ export async function runChatLoop(opts) {
3438
4258
  // §10.1 — approval replay across candidates uses the SERVING
3439
4259
  // candidate's rule set: a grant parked while the strong arm
3440
4260
  // 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 });
4261
+ // 0.7.1 — the recheck, like the first check, reads the PARSED
4262
+ // approved input and its canonical operative values; an approved
4263
+ // input that no longer parses is a denial, never a run.
4264
+ const approvedView = placeRecordingCanonicalizer();
4265
+ const approvedSubject = replaySubject ??
4266
+ preparePermissionSubject(tool, approvedOperative, {
4267
+ canonicalizePath: approvedView.canonicalizePath,
4268
+ readProgramPath: approvedView.readProgramPath,
4269
+ ...(gateToolConfig !== undefined ? { toolConfig: gateToolConfig } : {}),
4270
+ });
4271
+ const approvedFloor = approvedSubject.ok
4272
+ ? gateFloorValues(tool, approvedSubject.input)
4273
+ : undefined;
4274
+ const recheck = approvedSubject.ok
4275
+ ? evaluateWithReason({
4276
+ toolName: tu.name,
4277
+ input: approvedSubject.input,
4278
+ ...(approvedSubject.operativeValues !== undefined
4279
+ ? { operativeValues: approvedSubject.operativeValues }
4280
+ : {}),
4281
+ ...(approvedFloor !== undefined ? { floorValues: approvedFloor } : {}),
4282
+ readOnly: tool.readOnly,
4283
+ destructive: tool.destructive,
4284
+ requiresSandbox: tool.requiresSandbox,
4285
+ }, permissionMode, servingPlan.permissionRules, {
4286
+ sandboxAvailable: opts.sandboxAvailable === true,
4287
+ protectedRoots,
4288
+ ...(credentialRoots !== undefined ? { credentialRoots } : {}),
4289
+ })
4290
+ : { decision: "deny", reason: approvedSubject.reason };
3448
4291
  if (recheck.decision === "deny") {
3449
4292
  approved = false;
3450
4293
  denialMessage =
@@ -3462,7 +4305,7 @@ export async function runChatLoop(opts) {
3462
4305
  // actually RUN, so re-fire it against the substituted input.
3463
4306
  const replayHook = await fireHook("pre-tool", {
3464
4307
  id: tu.id,
3465
- name: tu.name,
4308
+ ...hookToolName(tu.name),
3466
4309
  input: tu.input,
3467
4310
  });
3468
4311
  if (!replayHook.allowed) {
@@ -3474,12 +4317,12 @@ export async function runChatLoop(opts) {
3474
4317
  }
3475
4318
  if (approved) {
3476
4319
  // Consume only once the call is really going to run: a replay the
3477
- // policy or a hook then refused must leave the operator's grant
3478
- // unspent, or they have to approve the same action twice.
3479
- await approvals.store.persist({
3480
- ...existing,
3481
- consumedAt: new Date().toISOString(),
3482
- });
4320
+ // policy or a hook then refused, and a call the justification
4321
+ // check below refuses, must leave the operator's grant unspent, or
4322
+ // they have to approve the same action twice. The egress check
4323
+ // records a match on this call and lets it go out as approved.
4324
+ // Held synchronously, as the replay claim above is held.
4325
+ heldGrant = holdGrant(existing, approvals.store);
3483
4326
  }
3484
4327
  if (replayedFrom !== undefined && approved) {
3485
4328
  bus.publish({
@@ -3527,6 +4370,10 @@ export async function runChatLoop(opts) {
3527
4370
  toolName: tu.name,
3528
4371
  inputHash,
3529
4372
  input: tu.input,
4373
+ // 0.7.1 — what this park covers: where the call lands now, and
4374
+ // the approval it asks in place of, so a card can say both.
4375
+ places: gateView.places(),
4376
+ ...(movedFrom !== undefined ? { supersedes: supersededBy(movedFrom) } : {}),
3530
4377
  runId: bus.runId,
3531
4378
  sessionId,
3532
4379
  surface: approvalSurface,
@@ -3553,11 +4400,17 @@ export async function runChatLoop(opts) {
3553
4400
  approvalId: pending.id,
3554
4401
  toolName: tu.name,
3555
4402
  surface: approvalSurface,
4403
+ ...(movedFrom !== undefined ? { supersedes: movedFrom.id } : {}),
3556
4404
  });
4405
+ // Asked again because the call moved: say where it was approved
4406
+ // and where it lands now, so the operator decides on the new place.
4407
+ const moved = movedFrom === undefined
4408
+ ? ""
4409
+ : `; 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
4410
  throw new RunFailedError({
3558
4411
  class: "approval_pending",
3559
4412
  title: "awaiting tool approval",
3560
- detail: `\`${tu.name}\` requires approval on a non-interactive surface (${approvalSurface}); the run is parked as approval ${pending.id}`,
4413
+ detail: `\`${tu.name}\` requires approval on a non-interactive surface (${approvalSurface})${moved}; the run is parked as approval ${pending.id}`,
3561
4414
  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
4415
  exitCode: EXIT_CODES.approval_pending,
3563
4416
  });
@@ -3588,6 +4441,45 @@ export async function runChatLoop(opts) {
3588
4441
  ...callAttribution,
3589
4442
  });
3590
4443
  }
4444
+ /**
4445
+ * A call a rule allows may be the one a person approved on a parked
4446
+ * approval: `--always` and Slack's "Always allow" save a settings rule
4447
+ * beside the grant, and that rule decides the resumed call before the
4448
+ * store is asked. The grant for this exact call, made where it lands and
4449
+ * not yet spent, is held as the ask branch holds it, so the call goes out
4450
+ * as approved and the grant is spent once. Any later call under the rule
4451
+ * alone meets every check as any call does. The egress check asks for it
4452
+ * only when its verdict for the call is `block`, where a held grant changes
4453
+ * the outcome. A lookup that fails finds no grant: the call meets the
4454
+ * egress check as any call a rule allows does.
4455
+ */
4456
+ const holdRuleAllowedGrant = async () => {
4457
+ if (decision !== "allow" || approvals === undefined)
4458
+ return;
4459
+ let grant = null;
4460
+ try {
4461
+ grant = await approvals.store.get(tu.name, hashApprovalInput(tu.name, operativeInput));
4462
+ const legacyToolName = legacyMcpToolName(tu.name);
4463
+ if (grant === null && legacyToolName !== undefined) {
4464
+ grant = await approvals.store.get(legacyToolName, hashApprovalInput(legacyToolName, operativeInput));
4465
+ }
4466
+ }
4467
+ catch (err) {
4468
+ runContext.logger.warn("approval lookup failed", {
4469
+ toolUseId: tu.id,
4470
+ toolName: tu.name,
4471
+ error: err.message,
4472
+ });
4473
+ grant = null;
4474
+ }
4475
+ if (grant !== null &&
4476
+ grant.decision === "grant" &&
4477
+ grant.consumedAt === undefined &&
4478
+ !grantsInFlight.has(grant.id) &&
4479
+ landsWhereApproved(grant, gateView)) {
4480
+ heldGrant = holdGrant(grant, approvals.store);
4481
+ }
4482
+ };
3591
4483
  if (!approved) {
3592
4484
  return finish({
3593
4485
  type: "tool_result",
@@ -3673,6 +4565,7 @@ export async function runChatLoop(opts) {
3673
4565
  }
3674
4566
  }
3675
4567
  if (!verdict.allow) {
4568
+ heldGrant?.release();
3676
4569
  return finish({
3677
4570
  type: "tool_result",
3678
4571
  tool_use_id: tu.id,
@@ -3688,16 +4581,16 @@ export async function runChatLoop(opts) {
3688
4581
  // we deny the call before it fires. `warn` logs but proceeds.
3689
4582
  //
3690
4583
  // 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.
4584
+ // (#144): runtime-joined MCP sinks and tools that send to a destination
4585
+ // the model chose default to `"external-dynamic"` (block non-user-origin
4586
+ // content); other spec-declared sinks stay `"external-configured"`
4587
+ // (warn). Callers can override via `opts.resolveSinkScope`.
3695
4588
  if (tool.scope === "external") {
3696
4589
  // (#386) — scan the OPERATIVE payload: for injected-justification
3697
4590
  // tools this is what `executeTool` actually transmits to the sink.
3698
4591
  const payload = JSON.stringify(operativeInput ?? null);
3699
- const sinkScope = (opts.resolveSinkScope ?? defaultSinkScope)(tu.name);
3700
- const egress = await classifyEgress(payload, runContext, {
4592
+ const sinkScope = (opts.resolveSinkScope ?? defaultSinkScope)(tu.name, tool);
4593
+ const classified = await classifyEgress(payload, runContext, {
3701
4594
  sinkId: tu.name,
3702
4595
  sinkScope,
3703
4596
  // FR-006: forward the caller-selected matcher when present. Absent
@@ -3706,6 +4599,21 @@ export async function runChatLoop(opts) {
3706
4599
  // below are byte-for-byte unchanged.
3707
4600
  ...(opts.egressMatcher !== undefined ? { matcher: opts.egressMatcher } : {}),
3708
4601
  });
4602
+ // An ordinary call, whose verdict is `pass` or `warn`, reads no approval.
4603
+ if (classified.verdict === "block" && heldGrant === undefined) {
4604
+ await holdRuleAllowedGrant();
4605
+ }
4606
+ // A call that runs under a grant a person gave on a parked approval goes
4607
+ // out as approved: for this call alone a `block` is a `warn`, and its
4608
+ // records name the approval. A live approval, and every other call in the
4609
+ // run, keep the policy's verdict.
4610
+ const approvedOver = classified.verdict === "block" && heldGrant !== undefined
4611
+ ? heldGrant.approvalId
4612
+ : undefined;
4613
+ const egress = approvedOver !== undefined ? { ...classified, verdict: "warn" } : classified;
4614
+ const approvedReason = approvedOver !== undefined
4615
+ ? `approval ${approvedOver} granted by a person: sent as approved`
4616
+ : undefined;
3709
4617
  const egressOutcome = egress.verdict === "pass"
3710
4618
  ? "egress-passed"
3711
4619
  : egress.verdict === "warn"
@@ -3718,7 +4626,11 @@ export async function runChatLoop(opts) {
3718
4626
  decision: egress.verdict === "block" ? "deny" : "allow",
3719
4627
  mode: permissionMode,
3720
4628
  outcome: egressOutcome,
3721
- ...(egress.originsFound.length > 0 ? { reason: `egress: ${summarizeEgress(egress)}` } : {}),
4629
+ ...(egress.originsFound.length > 0
4630
+ ? {
4631
+ reason: `egress: ${summarizeEgress(egress)}${approvedReason !== undefined ? `; ${approvedReason}` : ""}`,
4632
+ }
4633
+ : {}),
3722
4634
  ...callAttribution,
3723
4635
  });
3724
4636
  if (egress.verdict !== "pass") {
@@ -3728,6 +4640,7 @@ export async function runChatLoop(opts) {
3728
4640
  verdict: egress.verdict,
3729
4641
  originsFound: egress.originsFound,
3730
4642
  matchCount: egress.matchCount,
4643
+ ...(approvedOver !== undefined ? { approvalId: approvedOver } : {}),
3731
4644
  });
3732
4645
  // Item 20 — emit the durable `egress_decision` audit record for every
3733
4646
  // non-pass verdict so egress history is triageable offline (the
@@ -3748,6 +4661,9 @@ export async function runChatLoop(opts) {
3748
4661
  verdict: egress.verdict,
3749
4662
  originsFound: egress.originsFound,
3750
4663
  matchCount: egress.matchCount,
4664
+ ...(approvedOver !== undefined
4665
+ ? { approvalId: approvedOver, reason: approvedReason }
4666
+ : {}),
3751
4667
  },
3752
4668
  });
3753
4669
  }
@@ -3761,6 +4677,7 @@ export async function runChatLoop(opts) {
3761
4677
  }
3762
4678
  }
3763
4679
  if (egress.verdict === "block") {
4680
+ heldGrant?.release();
3764
4681
  return finish({
3765
4682
  type: "tool_result",
3766
4683
  tool_use_id: tu.id,
@@ -3793,6 +4710,7 @@ export async function runChatLoop(opts) {
3793
4710
  }
3794
4711
  }
3795
4712
  catch (err) {
4713
+ heldGrant?.release();
3796
4714
  runContext.logger.warn("tool rate limit exhausted", {
3797
4715
  toolUseId: tu.id,
3798
4716
  toolName: tu.name,
@@ -3806,6 +4724,9 @@ export async function runChatLoop(opts) {
3806
4724
  });
3807
4725
  }
3808
4726
  }
4727
+ // The call has passed every gate that can refuse it, so the grant it runs
4728
+ // under is spent here; a call a gate above refused left it unspent.
4729
+ await heldGrant?.spend();
3809
4730
  const toolAbort = turnAbort.child();
3810
4731
  // Build the bridge for this call. Built on EVERY run (#160 follow-up):
3811
4732
  // it carries `runContext`, which Pillar-3 boundary-site tools (tool-mcp,
@@ -3838,6 +4759,12 @@ export async function runChatLoop(opts) {
3838
4759
  const bridge = {
3839
4760
  runContext,
3840
4761
  eventLog,
4762
+ // 0.8.0 — the runtime-state roots, for the tools that write beneath a
4763
+ // directory they name and must not reach one (see RuntimeBridge).
4764
+ ...(protectedRoots.length > 0 ? { protectedRoots } : {}),
4765
+ // The files a `channel` or `managed` run keeps from its tools, for the tools
4766
+ // RuntimeBridge names.
4767
+ ...(credentialRoots !== undefined ? { credentialRoots } : {}),
3841
4768
  permissionMode,
3842
4769
  permissionRules: servingPlan.permissionRules,
3843
4770
  tools: bridgeTools,
@@ -3868,6 +4795,8 @@ export async function runChatLoop(opts) {
3868
4795
  ...(skills.length > 0 ? { skills } : {}),
3869
4796
  ...(opts.failureTaxonomy !== undefined ? { failureTaxonomy: opts.failureTaxonomy } : {}),
3870
4797
  ...(bridgeContinuitySeam !== undefined ? { continuity: bridgeContinuitySeam } : {}),
4798
+ // 0.8.0 §8 — the read-only provability seam (projected above).
4799
+ ...(bridgeProvabilitySeam !== undefined ? { provability: bridgeProvabilitySeam } : {}),
3871
4800
  // Loop contract 0.4 (G11) — the approval seam, so a Task child's
3872
4801
  // headless `ask` parks against the SAME store the parent parks against
3873
4802
  // instead of collapsing to a denial. `askMode` is spread only when the
@@ -3875,6 +4804,19 @@ export async function runChatLoop(opts) {
3875
4804
  // `"pause"` default — identical resolution, no double-defaulting.
3876
4805
  ...(opts.askMode !== undefined ? { askMode: opts.askMode } : {}),
3877
4806
  ...(opts.approvals !== undefined ? { approvals: opts.approvals } : {}),
4807
+ // 0.7.1 — a Task child runs against this process's sandbox backend, so
4808
+ // it passes the sandbox floor exactly when this loop does.
4809
+ ...(opts.sandboxAvailable === true ? { sandboxAvailable: true } : {}),
4810
+ // 0.7.1 — and judges a justification-gated call with this loop's judge,
4811
+ // writing its verdicts and egress warnings to this loop's audit log.
4812
+ ...(opts.justificationJudge !== undefined
4813
+ ? { justificationJudge: opts.justificationJudge }
4814
+ : {}),
4815
+ ...(opts.justificationAuditSink !== undefined
4816
+ ? { justificationAuditSink: opts.justificationAuditSink }
4817
+ : {}),
4818
+ ...(opts.egressAuditSink !== undefined ? { egressAuditSink: opts.egressAuditSink } : {}),
4819
+ specModels: bridgeSpecModels,
3878
4820
  };
3879
4821
  // Spin "running <tool>…" for exactly the execution window — started after
3880
4822
  // every gate (permission/justification/egress) so it never overlaps the
@@ -3929,10 +4871,14 @@ export async function runChatLoop(opts) {
3929
4871
  ...(toolResultRoot !== undefined ? { rootDir: toolResultRoot } : {}),
3930
4872
  });
3931
4873
  if (stored.persisted) {
3932
- runContext.logger.info("tool result persisted", {
4874
+ // A retried call whose bytes were already on disk wrote nothing.
4875
+ runContext.logger.info(stored.reused === true ? "tool result already persisted" : "tool result persisted", { toolUseId: tu.id, toolName: tu.name, fullPath: stored.fullPath });
4876
+ }
4877
+ else if (stored.unsaved !== undefined) {
4878
+ runContext.logger.warn("tool result could not be persisted; the model sees the preview", {
3933
4879
  toolUseId: tu.id,
3934
4880
  toolName: tu.name,
3935
- fullPath: stored.fullPath,
4881
+ reason: stored.unsaved,
3936
4882
  });
3937
4883
  }
3938
4884
  // Section 18 — post-tool prompt-injection classifier. Runs after the
@@ -4078,10 +5024,12 @@ export async function runChatLoop(opts) {
4078
5024
  return `[${parts.join(", ")}, ${totalChars} chars]`;
4079
5025
  }
4080
5026
  /**
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.
5027
+ * Run a list of tool calls honouring the orchestrator's partition, group
5028
+ * by group in the order the model issued them: a run of concurrency-safe
5029
+ * calls in parallel (up to `maxConcurrentTools`), every other call alone.
5030
+ * A read issued after a write therefore sees the write. Results are
5031
+ * returned in the original `toolUses` order so they line up with the
5032
+ * assistant turn's tool_use blocks.
4085
5033
  */
4086
5034
  async function runToolBatch(toolUses) {
4087
5035
  // Pass the full catalog so per-call classifiers (Task) can resolve a
@@ -4095,30 +5043,32 @@ export async function runChatLoop(opts) {
4095
5043
  ]);
4096
5044
  const maxConcurrentTools = opts.maxConcurrentTools ?? DEFAULT_MAX_CONCURRENT_TOOLS;
4097
5045
  runContext.logger.debug("tool partition", {
4098
- concurrent: partition.concurrent.map((b) => b.length),
4099
- serial: partition.serial.length,
5046
+ // In order: a number is a concurrent group of that many calls, "S" one
5047
+ // serial call.
5048
+ groups: partition.groups.map((g) => (g.kind === "serial" ? "S" : g.calls.length)),
4100
5049
  maxConcurrentTools,
4101
5050
  });
4102
5051
  // Map each tool_use's identity to its slot in the original order so
4103
5052
  // results can be placed back in order regardless of the
4104
5053
  // concurrent/serial execution shape. `partitionToolCalls` is total —
4105
- // every input block lands in exactly one partition bucket — and
5054
+ // every input block lands in exactly one group — and
4106
5055
  // `executeOneToolUse` always resolves to a result, so every slot is
4107
5056
  // filled; there is no missing-result case to defend against.
4108
5057
  const indexByBlock = new Map();
4109
5058
  toolUses.forEach((tu, idx) => indexByBlock.set(tu, idx));
4110
5059
  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) => {
5060
+ for (const group of partition.groups) {
5061
+ if (group.kind === "serial") {
5062
+ // biome-ignore lint/style/noNonNullAssertion: every block came from toolUses, so its index is registered.
5063
+ results[indexByBlock.get(group.call)] = await executeOneToolUse(group.call);
5064
+ continue;
5065
+ }
5066
+ const settled = await mapWithConcurrency(group.calls, maxConcurrentTools, (tu) => executeOneToolUse(tu));
5067
+ group.calls.forEach((tu, i) => {
4114
5068
  // biome-ignore lint/style/noNonNullAssertion: every block came from toolUses, so its index is registered.
4115
5069
  results[indexByBlock.get(tu)] = settled[i];
4116
5070
  });
4117
5071
  }
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
5072
  return results;
4123
5073
  }
4124
5074
  function evaluateToolLoop() {
@@ -4754,11 +5704,20 @@ export async function runChatLoop(opts) {
4754
5704
  const contextWindow = cfg?.capabilities?.contextWindow ?? table?.contextWindow;
4755
5705
  const maxOutputTokens = cfg?.capabilities?.maxOutputTokens ?? table?.maxOutputTokens;
4756
5706
  const breakerState = c.breaker?.state();
5707
+ const toolLimit = providerToolLimit(c.modelString, process.env);
4757
5708
  return {
4758
5709
  armId: armIdOf(c),
4759
5710
  modelString: c.modelString,
4760
5711
  tags: c.tags,
4761
5712
  ...(breakerState !== undefined ? { breakerState } : {}),
5713
+ ...(toolLimit !== undefined
5714
+ ? {
5715
+ toolLimit: {
5716
+ toolCount: plan.advertisedNames.size,
5717
+ maxTools: toolLimit.maxTools,
5718
+ },
5719
+ }
5720
+ : {}),
4762
5721
  capabilities: {
4763
5722
  features: plan.features,
4764
5723
  ...(contextWindow !== undefined ? { contextWindow } : {}),
@@ -5718,6 +6677,7 @@ export async function runChatLoop(opts) {
5718
6677
  messages,
5719
6678
  adapter: compactionAdapter,
5720
6679
  model: compactionWireModelId,
6680
+ contextLimit,
5721
6681
  snipKeepHead,
5722
6682
  snipKeepTail,
5723
6683
  logger: runContext.logger,
@@ -5732,10 +6692,9 @@ export async function runChatLoop(opts) {
5732
6692
  : {}),
5733
6693
  }).finally(() => out.spinner.stop());
5734
6694
  // §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;
6695
+ // reactive path always ends in autocompact's [marker, summary,
6696
+ // final user turn]; the summary is the second message).
6697
+ const reactiveSummary = summaryTextOf(compacted);
5739
6698
  messages.length = 0;
5740
6699
  messages.push(...compacted);
5741
6700
  await logEvent("compaction", {
@@ -6036,6 +6995,7 @@ export async function runChatLoop(opts) {
6036
6995
  };
6037
6996
  async function runEvaluatedTurn(messages) {
6038
6997
  const evaluation = opts.evaluation;
6998
+ const provability = opts.provability;
6039
6999
  const cascade = resolveCascade();
6040
7000
  const turnStartMs = performance.now();
6041
7001
  // The pre-draft snapshot is a COPY of the messages, not a length: the
@@ -6048,59 +7008,177 @@ export async function runChatLoop(opts) {
6048
7008
  // successful observations so the grade can be stamped on them; without
6049
7009
  // a judge the line count is unchanged and nothing is deferred.
6050
7010
  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;
7011
+ // 0.8.0 (design/0.8.0-provability-release.md §5.1) — provability FIRST
7012
+ // (it is free and deterministic), then the judge (which may spend). Under
7013
+ // `provability:` every attempt this turn produces — the first, an
7014
+ // evaluation retry, a cascade escalation — is verified BEFORE the judge
7015
+ // grades it: a failing verdict retries, halts or escalates without a
7016
+ // judge call, and the judge grades only an answer the gate accepted (or
7017
+ // ran out of retries on). The ladder is the turn's (`runProvableTurn`
7018
+ // opened it); each gate keeps its own `maxRetries`, and both draw on one
7019
+ // `max_escalations`.
7020
+ const ladder = provability === undefined ? undefined : (activeLadder ?? newProvabilityLadder());
7021
+ /** The turn's escalations: the ladder's under `provability:`, so both gates count them. */
7022
+ const turnEscalations = ladder ?? { escalations: 0 };
7023
+ /**
7024
+ * The rung the turn was handed to — by a provability escalation, by the
7025
+ * cascade's, or by the judge share serving the strong rung directly. A
7026
+ * later re-run of THIS turn stays on it instead of going back to the
7027
+ * router (the escalated answer is the one being corrected).
7028
+ */
7029
+ let heldRung;
7030
+ const heldRungTurn = (rung) => ({
7031
+ force: rung,
7032
+ forceReason: `the turn stays on ${armIdOf(rung)}, the rung it was escalated to`,
7033
+ role: "escalation",
7034
+ stage: "escalate",
7035
+ strategy: "cascade",
7036
+ defer: cascade !== undefined || deferForGrade,
7037
+ });
7038
+ /** An attempt handed back to the call site — with its proof footer under `provability:`. */
7039
+ const served = (a) => provability === undefined || ladder === undefined ? a : finishGated(provability, ladder, a);
6079
7040
  /** Fold a non-cascade attempt's deferred lines with the grade it earned (none ⇒ the §6.3 gate). */
6080
7041
  const foldGraded = (a, quality) => {
6081
7042
  for (const { turn, obs } of a.observations) {
6082
7043
  recordPoolOutcome(turn, quality !== undefined ? { ...obs, quality } : obs);
6083
7044
  }
6084
7045
  };
6085
- const maxRetries = Math.max(0, Math.floor(evaluation.maxRetries));
7046
+ // §6.2 — past the judge share a cascade serves the strong rung DIRECTLY:
7047
+ // the draft it cannot afford to grade is not drafted, the judge is not
7048
+ // skipped silently — the route reason and the stage cause both say why.
7049
+ const judgeShareServes = cascade !== undefined && forcedRunCandidate === undefined && judgeShareExhausted();
7050
+ let attempt;
7051
+ if (judgeShareServes && cascade !== undefined) {
7052
+ attempt = await runEscalationStage(messages, cascade.target, "judge_share_exhausted", "judge_share_exhausted", true);
7053
+ heldRung = cascade.target;
7054
+ }
7055
+ else {
7056
+ attempt =
7057
+ forcedRunCandidate !== undefined
7058
+ ? await runEscalationStage(messages, forcedRunCandidate, "retry_previous", `forced onto ${armIdOf(forcedRunCandidate)} (forcedCandidate)`, cascade !== undefined || deferForGrade)
7059
+ : await runOneTurn(messages, cascade !== undefined
7060
+ ? { role: "draft", stage: "draft", strategy: "cascade", defer: true }
7061
+ : deferForGrade
7062
+ ? { defer: true }
7063
+ : {});
7064
+ }
6086
7065
  const stages = [];
6087
7066
  let current;
6088
7067
  if (cascade !== undefined) {
6089
7068
  current = {
6090
- stage: "draft",
6091
- attributedTo: "draft",
7069
+ stage: judgeShareServes ? "escalate" : "draft",
7070
+ attributedTo: judgeShareServes ? "escalation" : "draft",
6092
7071
  observations: attempt.observations,
6093
7072
  costUsd: attempt.costUsd,
6094
7073
  };
6095
7074
  stages.push(current);
6096
7075
  }
6097
- let escalations = 0;
6098
- const gradedStages = () => stages.filter((st) => st.score !== undefined);
6099
- for (let retryIndex = 0;; retryIndex += 1) {
6100
- // A turn the abort tree stopped (SIGINT, turn/model-call/run timer)
6101
- // did not COMPLETE — grading its partial output would be noise, and
6102
- // a retry would fight the very signal that stopped it.
6103
- if (turnAbort.signal.aborted || runAbort.signal.aborted) {
7076
+ /** A provability retry: the turn again, in the lane its current attempt ran in. */
7077
+ const rerunTurn = async () => {
7078
+ if (heldRung !== undefined)
7079
+ return runOneTurn(messages, heldRungTurn(heldRung));
7080
+ if (forcedRunCandidate !== undefined) {
7081
+ return runEscalationStage(messages, forcedRunCandidate, "retry_previous", `forced onto ${armIdOf(forcedRunCandidate)} (forcedCandidate)`, cascade !== undefined || deferForGrade);
7082
+ }
7083
+ if (cascade !== undefined) {
7084
+ return runOneTurn(messages, {
7085
+ role: "draft",
7086
+ stage: "draft",
7087
+ strategy: "cascade",
7088
+ defer: true,
7089
+ });
7090
+ }
7091
+ return runOneTurn(messages, deferForGrade ? { defer: true } : {});
7092
+ };
7093
+ /**
7094
+ * §5.1 — the provability ladder over `attempt`, before any judge call.
7095
+ * `"stands"`: the answer goes on (to the judge, when there is one) — it
7096
+ * passed, failed under `note`, ran out of retries, or had no rung to
7097
+ * escalate to. `"stopped"`: the abort tree stopped the turn while the
7098
+ * gate worked, and the attempt is handed back as it is. A retry or an
7099
+ * escalation re-runs the turn right here; the rejected answer never
7100
+ * reaches the judge, and its deferred routing lines fold ungraded (the
7101
+ * §6.3 gate). A `halt` folds what the turn holds and throws the
7102
+ * classified stop.
7103
+ */
7104
+ const provabilityFirst = async () => {
7105
+ if (provability === undefined || ladder === undefined)
7106
+ return "stands";
7107
+ for (;;) {
7108
+ const step = await provabilityPass(provability, ladder, messages, attempt, current?.stage ?? (heldRung !== undefined ? "escalate" : undefined));
7109
+ if (step.kind === "stopped")
7110
+ return "stopped";
7111
+ if (step.kind === "stands")
7112
+ return step.aborted ? "stopped" : "stands";
7113
+ if (step.kind === "halt") {
7114
+ if (cascade !== undefined) {
7115
+ flushCascade(stages, { success: false }, performance.now() - turnStartMs);
7116
+ }
7117
+ else {
7118
+ foldGraded(attempt);
7119
+ }
7120
+ return haltOnProvability(provability, step);
7121
+ }
7122
+ const rejected = attempt;
7123
+ const rejectedStage = current;
7124
+ ladder.reruns += 1;
7125
+ if (step.kind === "escalate") {
7126
+ turnEscalations.escalations += 1;
7127
+ const escalated = await escalateOnProvability(messages, step, cascade !== undefined || deferForGrade);
7128
+ // The rung unavailable: the verified answer stands with its failing
7129
+ // verdict (note semantics) and goes on to the judge.
7130
+ if (escalated === undefined)
7131
+ return "stands";
7132
+ attempt = escalated;
7133
+ heldRung = step.target;
7134
+ if (cascade !== undefined) {
7135
+ current = {
7136
+ stage: "escalate",
7137
+ attributedTo: "escalation",
7138
+ observations: attempt.observations,
7139
+ costUsd: attempt.costUsd,
7140
+ };
7141
+ stages.push(current);
7142
+ }
7143
+ }
7144
+ else {
7145
+ messages.push(markSynthetic({ role: "user", content: step.nudge }));
7146
+ await logEvent("user_message", { content: step.nudge, synthetic: true });
7147
+ attempt = await rerunTurn();
7148
+ if (current !== undefined)
7149
+ current.costUsd += attempt.costUsd;
7150
+ }
7151
+ // The rejected answer's lines fold ungraded; its stage keeps its
7152
+ // spend (the strategy line counts it) and, on a retry, takes the new
7153
+ // attempt's lines.
7154
+ foldGraded(rejected);
7155
+ if (rejectedStage !== undefined) {
7156
+ rejectedStage.observations = rejectedStage === current ? attempt.observations : [];
7157
+ }
7158
+ }
7159
+ };
7160
+ if (judgeShareServes) {
7161
+ // 0.8.0 §5.1 — what the judge share cannot afford to grade, the free
7162
+ // gate still verifies.
7163
+ await provabilityFirst();
7164
+ // §6.3 — folded through the same quality gate as every cascade line:
7165
+ // the calls are un-judged, so under `in_loop` the strong arm is counted
7166
+ // `ungraded` rather than credited a perfect 1.0 for the rest of the
7167
+ // run; no strategy line (there is no final quality to fold).
7168
+ flushCascade(stages, { success: true }, performance.now() - turnStartMs);
7169
+ return served(attempt);
7170
+ }
7171
+ if (evaluation === undefined) {
7172
+ await provabilityFirst();
7173
+ return served(attempt);
7174
+ }
7175
+ const maxRetries = Math.max(0, Math.floor(evaluation.maxRetries));
7176
+ const gradedStages = () => stages.filter((st) => st.score !== undefined);
7177
+ for (let retryIndex = 0;; retryIndex += 1) {
7178
+ // A turn the abort tree stopped (SIGINT, turn/model-call/run timer)
7179
+ // did not COMPLETE — grading its partial output would be noise, and
7180
+ // a retry would fight the very signal that stopped it.
7181
+ if (turnAbort.signal.aborted || runAbort.signal.aborted) {
6104
7182
  // An abort is not a judge outage: the deferred lines fold without a
6105
7183
  // quality (exactly what an un-deferred call would have recorded —
6106
7184
  // under `in_loop` the §6.3 gate counts them `ungraded`).
@@ -6110,7 +7188,19 @@ export async function runChatLoop(opts) {
6110
7188
  else {
6111
7189
  foldGraded(attempt);
6112
7190
  }
6113
- return attempt;
7191
+ return served(attempt);
7192
+ }
7193
+ // 0.8.0 §5.1 — the free gate before the judge: a failing verdict is
7194
+ // retried, escalated or halted here, without a judge call. A stop that
7195
+ // lands while it works hands the attempt back ungraded, as above.
7196
+ if ((await provabilityFirst()) === "stopped") {
7197
+ if (cascade !== undefined) {
7198
+ flushCascade(stages, { success: false }, performance.now() - turnStartMs);
7199
+ }
7200
+ else {
7201
+ foldGraded(attempt);
7202
+ }
7203
+ return served(attempt);
6114
7204
  }
6115
7205
  let graded;
6116
7206
  out.spinner.start("evaluating");
@@ -6152,7 +7242,7 @@ export async function runChatLoop(opts) {
6152
7242
  // strategy line is withheld (see `flushCascade`).
6153
7243
  flushCascade(gradedStages(), { success: true }, performance.now() - turnStartMs);
6154
7244
  }
6155
- return attempt;
7245
+ return served(attempt);
6156
7246
  }
6157
7247
  finally {
6158
7248
  out.spinner.stop();
@@ -6177,7 +7267,7 @@ export async function runChatLoop(opts) {
6177
7267
  const willEscalate = verdict === "fail" &&
6178
7268
  evaluation.onFail === "escalate" &&
6179
7269
  cascade !== undefined &&
6180
- escalations < cascade.maxEscalations;
7270
+ turnEscalations.escalations < cascade.maxEscalations;
6181
7271
  bus.publish({
6182
7272
  ...bus.envelope(),
6183
7273
  kind: "eval_graded",
@@ -6215,11 +7305,11 @@ export async function runChatLoop(opts) {
6215
7305
  return attempt;
6216
7306
  };
6217
7307
  if (verdict === "pass" || evaluation.onFail === "note")
6218
- return standing();
7308
+ return served(standing());
6219
7309
  // `escalate` without a pool has nothing to escalate to (warned once at
6220
7310
  // resolve time): the verdict stands, note semantics.
6221
7311
  if (evaluation.onFail === "escalate" && cascade === undefined)
6222
- return standing();
7312
+ return served(standing());
6223
7313
  const rationaleNote = rationale !== undefined && rationale.trim().length > 0 ? ` — ${rationale.trim()}` : "";
6224
7314
  if (evaluation.onFail === "halt") {
6225
7315
  const detail = `the ${evaluation.graderType} grader scored the final answer ${score.toFixed(2)}, below the required ${evaluation.threshold} threshold${rationaleNote}`;
@@ -6258,9 +7348,9 @@ export async function runChatLoop(opts) {
6258
7348
  outcome: "skipped",
6259
7349
  cause: "max_escalations",
6260
7350
  });
6261
- return standing();
7351
+ return served(standing());
6262
7352
  }
6263
- escalations += 1;
7353
+ turnEscalations.escalations += 1;
6264
7354
  // The transcript as graded — restored should the escalation rung be
6265
7355
  // unavailable (§7.13: the draft answer stands).
6266
7356
  const draftTranscript = messages.slice();
@@ -6301,21 +7391,27 @@ export async function runChatLoop(opts) {
6301
7391
  const message = err instanceof Error ? err.message : String(err);
6302
7392
  runContext.logger.warn("cascade: escalation rung unavailable — the draft answer stands with its failing grade (note semantics)", { escalateTo: cascade.target.modelString, message });
6303
7393
  messages.splice(0, messages.length, ...draftTranscript);
6304
- return standing();
7394
+ return served(standing());
6305
7395
  }
6306
7396
  stage.observations = attempt.observations;
6307
7397
  stage.costUsd = attempt.costUsd;
6308
7398
  stages.push(stage);
6309
7399
  current = stage;
7400
+ // A provability retry of the escalated answer stays on the rung.
7401
+ heldRung = cascade.target;
6310
7402
  continue;
6311
7403
  }
6312
7404
  // onFail: "retry" — bounded by the resolved cap; when spent, the last
6313
7405
  // attempt stands (the failing eval_graded trail tells the story).
6314
7406
  if (retryIndex >= maxRetries)
6315
- return attempt;
7407
+ return served(attempt);
6316
7408
  messages.push(markSynthetic({ role: "user", content: correction }));
6317
7409
  await logEvent("user_message", { content: correction, synthetic: true });
6318
- attempt = await runOneTurn(messages, deferForGrade ? { defer: true } : {});
7410
+ // An answer a provability escalation produced is corrected on its rung.
7411
+ attempt =
7412
+ heldRung !== undefined
7413
+ ? await runOneTurn(messages, heldRungTurn(heldRung))
7414
+ : await runOneTurn(messages, deferForGrade ? { defer: true } : {});
6319
7415
  }
6320
7416
  }
6321
7417
  /**
@@ -6379,7 +7475,9 @@ export async function runChatLoop(opts) {
6379
7475
  const block = { type: "text", text: verdict.text, citations: null };
6380
7476
  messages.push({ role: "assistant", content: [block] });
6381
7477
  await logEvent("assistant_message", { content: [block] });
6382
- out.write(`agent> ${verdict.text}\n`);
7478
+ // §5.4 — printed as the stream prints an answer: no footer-shaped line of
7479
+ // it passes for the gate's verdict under `provability:`.
7480
+ out.write(`agent> ${opts.provability !== undefined ? neutralizeFooterLines(verdict.text) : verdict.text}\n`);
6383
7481
  lastResponseWireModel = verdict.winner.model;
6384
7482
  await recordServedModel(verdict.winner.model);
6385
7483
  publishStage({
@@ -6392,6 +7490,874 @@ export async function runChatLoop(opts) {
6392
7490
  });
6393
7491
  return { terminalContent: [block], usage: verdict.usage };
6394
7492
  }
7493
+ // -------------------------------------------------------------------------
7494
+ // 0.8.0 (design/0.8.0-provability-release.md §5.1, §5.3, §5.4) — the
7495
+ // provability gate. §5.1 orders the two gates: provability FIRST (it is
7496
+ // free and deterministic), then `evaluation:` (which may spend). So the
7497
+ // evaluated turn above runs the ladder on every attempt BEFORE its judge
7498
+ // (`provabilityFirst`): a failing verdict retries, halts or escalates
7499
+ // without a judge call, a re-run the judge asks for is verified again
7500
+ // first, an escalated answer goes on to the judge like any other, and both
7501
+ // gates draw on one `max_escalations`. `runProvableTurn` verifies what no
7502
+ // evaluated turn produced: a committee verdict. The verifier is injected
7503
+ // (`@crewhaus/evaluation-service` builds it); runtime-core only decides what
7504
+ // a verdict does, and builds the fail-open bundle when the verifier throws.
7505
+ // -------------------------------------------------------------------------
7506
+ let warnedProvabilityEscalateWithoutPool = false;
7507
+ /**
7508
+ * §5.1 — `on_fail: escalate`: the roster arm a failing verdict hands the
7509
+ * turn to — `escalateTo` (a spec model string, `$profile` or tag; the
7510
+ * compiler already folded `strategy.cascade.escalate_to` into it, the pool's
7511
+ * own cascade target is the fallback for a hand-wired caller), else the
7512
+ * pool's strongest candidate. Without a pool there is nothing to escalate
7513
+ * to: warned once per run, and the verdict stands (note semantics) — how
7514
+ * `resolveCascade` treats `evaluation.on_fail: escalate`.
7515
+ */
7516
+ const resolveProvabilityEscalation = (provability) => {
7517
+ if (poolRouter === undefined) {
7518
+ if (!warnedProvabilityEscalateWithoutPool) {
7519
+ warnedProvabilityEscalateWithoutPool = true;
7520
+ 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)");
7521
+ }
7522
+ return undefined;
7523
+ }
7524
+ const declared = provability.escalateTo ?? opts.modelPool?.strategy?.cascade?.escalateTo;
7525
+ const resolved = declared !== undefined ? resolveRosterArm(declared) : undefined;
7526
+ if (declared !== undefined && resolved === undefined) {
7527
+ runContext.logger.warn("provability.escalateTo names no roster arm — escalating to the strongest candidate", { escalateTo: declared });
7528
+ }
7529
+ return resolved ?? poolRouter.escalation();
7530
+ };
7531
+ /** A thrown value's name and message, whatever was thrown. */
7532
+ const describeThrown = (err, fallbackName) => {
7533
+ const errObj = (typeof err === "object" && err !== null ? err : {});
7534
+ return {
7535
+ name: typeof errObj.name === "string" ? errObj.name : fallbackName,
7536
+ message: typeof errObj.message === "string" ? errObj.message : String(err),
7537
+ };
7538
+ };
7539
+ /**
7540
+ * A verifier result is only trusted as a verdict when every field the gate
7541
+ * reads is there and well-typed: the summary the `provability_graded` line,
7542
+ * the event-log twin and the audit record carry (all required fields of
7543
+ * `ProvabilityGradedEvent`), and each claim's `bindings` the halt detail
7544
+ * tallies. Anything less — a bare `{ verdict, claims }`, a NaN score, a
7545
+ * claim without bindings — is not a verdict to act on: it fails open as
7546
+ * `unverified`, exactly like a verifier that threw (a halt on it would
7547
+ * print `undefined/NaN claims` or crash on `claim.bindings`).
7548
+ */
7549
+ const isGradedBundle = (value) => {
7550
+ if (typeof value !== "object" || value === null)
7551
+ return false;
7552
+ const bundle = value;
7553
+ const finite = (v) => typeof v === "number" && Number.isFinite(v);
7554
+ const isObject = (v) => typeof v === "object" && v !== null;
7555
+ return ((bundle.verdict === "pass" || bundle.verdict === "fail" || bundle.verdict === "unverified") &&
7556
+ isProvabilityLevel(bundle.level) &&
7557
+ (bundle.achieved === "none" || isProvabilityLevel(bundle.achieved)) &&
7558
+ finite(bundle.score) &&
7559
+ finite(bundle.threshold) &&
7560
+ finite(bundle.claimCount) &&
7561
+ finite(bundle.met) &&
7562
+ finite(bundle.unmet) &&
7563
+ finite(bundle.assumptions) &&
7564
+ (bundle.assumptionsRefused === undefined || finite(bundle.assumptionsRefused)) &&
7565
+ (bundle.judgeModel === undefined || typeof bundle.judgeModel === "string") &&
7566
+ (bundle.spentUsdMicros === undefined || finite(bundle.spentUsdMicros)) &&
7567
+ typeof bundle.bundleHash === "string" &&
7568
+ Array.isArray(bundle.claims) &&
7569
+ bundle.claims.every((claim) => isObject(claim) &&
7570
+ Array.isArray(claim.bindings) &&
7571
+ claim.bindings.every(isObject)));
7572
+ };
7573
+ /**
7574
+ * §5.1 — the classified terminal stop of `on_fail: halt`, mirroring the
7575
+ * evaluation halt: class `"provability"`, exit {@link EXIT_CODES.provability}.
7576
+ * The detail names the score, every refused assumption and the reasons the
7577
+ * unmet claims fell short (stable `UnmetReason` tokens, tallied), so the
7578
+ * operator reads why without opening the bundle — and where the bundle is.
7579
+ */
7580
+ const provabilityFailureReport = (bundle, bundlePath) => {
7581
+ const counted = Math.max(0, bundle.claimCount - bundle.assumptions);
7582
+ const parts = [
7583
+ `${bundle.met}/${counted} ${counted === 1 ? "claim" : "claims"} met the ${bundle.level} floor (threshold ${bundle.threshold})`,
7584
+ ];
7585
+ const refused = bundle.assumptionsRefused ?? 0;
7586
+ if (refused > 0) {
7587
+ parts.push(`${refused} declared ${refused === 1 ? "assumption was" : "assumptions were"} refused`);
7588
+ }
7589
+ const tally = new Map();
7590
+ for (const claim of bundle.claims) {
7591
+ for (const reason of claimReasons(claim))
7592
+ tally.set(reason, (tally.get(reason) ?? 0) + 1);
7593
+ }
7594
+ if (tally.size > 0) {
7595
+ const reasons = [...tally].map(([reason, n]) => (n > 1 ? `${reason} ×${n}` : reason));
7596
+ parts.push(`unmet: ${reasons.join(", ")}`);
7597
+ }
7598
+ if (bundlePath !== undefined)
7599
+ parts.push(`proof bundle: ${bundlePath}`);
7600
+ return {
7601
+ class: "provability",
7602
+ title: "provability gate failed",
7603
+ detail: parts.join("; "),
7604
+ remediation: "cite the evidence each claim rests on, lower provability.threshold, or soften provability.on_fail to retry/note",
7605
+ exitCode: EXIT_CODES.provability,
7606
+ };
7607
+ };
7608
+ const newProvabilityLadder = () => ({
7609
+ passes: 0,
7610
+ reruns: 0,
7611
+ escalations: 0,
7612
+ });
7613
+ /**
7614
+ * The ladder of the turn in flight: `runProvableTurn` opens it, and an
7615
+ * evaluated turn inside verifies its attempts against the same one, so a
7616
+ * committee verdict's retry that falls back to the evaluated turn does not
7617
+ * start the counts over.
7618
+ */
7619
+ let activeLadder;
7620
+ /** A non-finite cap would make the retry ladder unbounded; 0 is the only safe reading of a value nobody meant. */
7621
+ const provabilityRetryCap = (provability) => Number.isFinite(provability.maxRetries) ? Math.max(0, Math.floor(provability.maxRetries)) : 0;
7622
+ /**
7623
+ * §5.1 — the escalations one turn may make: the evaluation cascade's
7624
+ * `max_escalations` when there is a cascade (both gates draw on it), else
7625
+ * the pool's own (`strategy.max_escalations`, default 1). A non-finite
7626
+ * value reads as 0, as the retry cap does.
7627
+ */
7628
+ const turnEscalationCap = () => {
7629
+ const cap = resolveCascade()?.maxEscalations ?? Math.floor(opts.modelPool?.strategy?.maxEscalations ?? 1);
7630
+ return Number.isFinite(cap) ? Math.max(0, cap) : 0;
7631
+ };
7632
+ /**
7633
+ * §5.3, §8 — a bundle path as the run's LIVE surfaces show it (the trace
7634
+ * event a `runs.subscribe` stream carries, the halt detail a gateway
7635
+ * returns): through the gate's display rule, the footer's (relative to
7636
+ * the tenant's root inside a tenant scope, else the workspace), so a
7637
+ * tenant is never told the server's directory layout above its root. The
7638
+ * durable event-log line keeps the path as persisted. No rule → as given;
7639
+ * a rule that throws → no path at all.
7640
+ */
7641
+ const shownBundlePath = (provability, bundlePath) => {
7642
+ if (bundlePath === undefined || provability.displayPath === undefined)
7643
+ return bundlePath;
7644
+ try {
7645
+ const shown = provability.displayPath(bundlePath);
7646
+ return typeof shown === "string" && shown.length > 0 ? shown : undefined;
7647
+ }
7648
+ catch (err) {
7649
+ runContext.logger.warn("provability: showing the bundle path failed — it is left out", {
7650
+ message: describeThrown(err, "Error").message,
7651
+ });
7652
+ return undefined;
7653
+ }
7654
+ };
7655
+ /** The standing pass's rendering, or undefined (`render: none`, no renderer, empty). */
7656
+ const renderStanding = (provability, bundle, bundlePath) => {
7657
+ if (provability.render === "none" || provability.renderBundle === undefined)
7658
+ return undefined;
7659
+ let rendered;
7660
+ try {
7661
+ rendered = provability.renderBundle(bundle, bundlePath);
7662
+ }
7663
+ catch (err) {
7664
+ runContext.logger.warn("provability: rendering the proof bundle failed — no footer", {
7665
+ message: describeThrown(err, "Error").message,
7666
+ });
7667
+ return undefined;
7668
+ }
7669
+ // trimEnd, not a regex: a footer is printed on its own line, and a
7670
+ // `\s+$` pattern backtracks quadratically over a long whitespace run.
7671
+ const trimmed = typeof rendered === "string" ? rendered.trimEnd() : "";
7672
+ return trimmed.length > 0 ? trimmed : undefined;
7673
+ };
7674
+ /**
7675
+ * §5.4 — does the reader read this turn as it streams? The REPL prints
7676
+ * every attempt as it is made, and so does any run whose footer goes to the
7677
+ * stream (the cli); a run that hands its text back (`"reply"` on a channel
7678
+ * bot, `"none"` on the gateway) serves the final answer alone, and its
7679
+ * output is an operator's log.
7680
+ */
7681
+ const streamsTheTurn = (provability) => provability.streamed ??
7682
+ (opts.singleTurn !== true || (provability.footerTarget ?? "stream") === "stream");
7683
+ /**
7684
+ * The text the turn in flight has printed so far, as the gate grades it in
7685
+ * a claimless final message's place: every assistant message's text since
7686
+ * the turn's own input — the last user message that is neither
7687
+ * runtime-injected (a retry nudge, a correction) nor a tool result — and
7688
+ * since the last attempt a failing pass graded (`rejectedThrough`), joined
7689
+ * as paragraphs. A rejected attempt was graded once, and where it
7690
+ * streamed its ✗ is already under it: grading it again would fail every
7691
+ * honest retraction after it ("I'm not able to confirm that."), unless
7692
+ * the final message points back at it (`POINTS_BACK`: "See above."),
7693
+ * when it is the answer the reader is handed again. In the messages
7694
+ * before the final one, a sentence that only says what the agent is about
7695
+ * to do (`NARRATION`: "Let me fetch the policy page first.") is no claim
7696
+ * the reader was handed, and is left out.
7697
+ *
7698
+ * The final message is the transcript's last one. An empty one is still
7699
+ * final: a model that ends its turn on an empty `end_turn` after a tool
7700
+ * call commits no message at all (the last is the tool results' carrier),
7701
+ * or a blank text block. Either way every assistant message before it
7702
+ * printed ahead of a tool call, and is read for narration — never graded
7703
+ * whole as though it were the answer (I11).
7704
+ */
7705
+ const streamedTurnText = (messages, rejectedThrough) => {
7706
+ const texts = [];
7707
+ let pointsBack = false;
7708
+ /** The turn's own input: a figure the reader handed the agent is no claim of the agent's. */
7709
+ const input = latestHumanUserMessage(messages);
7710
+ const handed = figuresIn(input !== undefined ? messageText(input) : "");
7711
+ for (let i = messages.length - 1; i >= 0; i -= 1) {
7712
+ const message = messages[i];
7713
+ if (message === rejectedThrough && !pointsBack)
7714
+ break;
7715
+ if (message.role === "user") {
7716
+ const carriesResults = Array.isArray(message.content) &&
7717
+ message.content.some((block) => block.type === "tool_result");
7718
+ if (!isSyntheticMessage(message) && !carriesResults)
7719
+ break;
7720
+ continue;
7721
+ }
7722
+ const blocks = typeof message.content === "string" ? [] : message.content;
7723
+ const text = typeof message.content === "string"
7724
+ ? message.content
7725
+ : blocks
7726
+ .filter((block) => block.type === "text")
7727
+ .map((block) => block.text)
7728
+ .join("");
7729
+ if (i === messages.length - 1) {
7730
+ pointsBack = POINTS_BACK.test(text);
7731
+ if (text.trim() !== "")
7732
+ texts.unshift(text);
7733
+ continue;
7734
+ }
7735
+ if (text.trim() === "")
7736
+ continue;
7737
+ // What the narration announces: the input of the calls this message makes.
7738
+ const calls = new Set();
7739
+ for (const block of blocks) {
7740
+ if (block.type === "tool_use")
7741
+ callFigures(block.input, calls);
7742
+ }
7743
+ const said = withoutNarration(text, [handed, calls]);
7744
+ if (said !== "")
7745
+ texts.unshift(said);
7746
+ }
7747
+ return texts.join("\n\n");
7748
+ };
7749
+ /**
7750
+ * §5.4 — a failing pass the gate is about to re-run: where the reader has
7751
+ * already seen the rejected attempt stream past (`streamsTheTurn`, a
7752
+ * footer that goes to the output), its ✗ footer is written under it now,
7753
+ * so no answer the reader saw stands unmarked above the next one. The
7754
+ * standing pass renders as before; this bundle is never rendered twice
7755
+ * (`ladder.marked`).
7756
+ */
7757
+ const markRejected = (provability, ladder, bundle, bundlePath) => {
7758
+ const target = provability.footerTarget ?? "stream";
7759
+ if (target === "none" || !streamsTheTurn(provability))
7760
+ return;
7761
+ const footer = renderStanding(provability, bundle, bundlePath);
7762
+ if (footer === undefined)
7763
+ return;
7764
+ out.write(`${footer}\n`);
7765
+ ladder.marked = bundle;
7766
+ };
7767
+ /** The retry nudge; a composer that throws or says nothing still leaves the verdict. */
7768
+ const composeNudge = (provability, bundle) => {
7769
+ try {
7770
+ const nudge = provability.nudge(bundle);
7771
+ if (typeof nudge === "string" && nudge.trim().length > 0)
7772
+ return nudge;
7773
+ }
7774
+ catch (err) {
7775
+ runContext.logger.warn("provability: composing the retry nudge failed — nudging with the score alone", {
7776
+ message: describeThrown(err, "Error").message,
7777
+ });
7778
+ }
7779
+ const counted = Math.max(0, bundle.claimCount - bundle.assumptions);
7780
+ 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.`;
7781
+ };
7782
+ /**
7783
+ * Whether the abort tree has stopped this turn. A stopped turn did not
7784
+ * complete inside its window: it is never retried or escalated, and a
7785
+ * verdict that had not settled when it stopped is discarded (the turn
7786
+ * stands un-verified). When a fired wall-clock limit is what stopped it, the stop
7787
+ * is classified exactly as `runOneTurn` classifies one (G10): terminal
7788
+ * for the run deadline in any mode and for every limit on the
7789
+ * single-turn path (the turn IS the run) — `throwTimeout`, class
7790
+ * `"timeout"` — so neither a slow verifier nor a slow evaluation judge
7791
+ * can turn a timed-out run into a served, un-verified answer, and
7792
+ * `on_fail: halt` cannot be skipped by running out the clock. A REPL
7793
+ * turn/model-call timeout, a SIGINT or a host abort is not terminal: the
7794
+ * caller hands the turn back. `firedInGate` — the abort landed during
7795
+ * the gate's own work, where no `runOneTurn` was running to write the
7796
+ * REPL's named timeout `error` line, so the gate writes it.
7797
+ */
7798
+ const stoppedByAbort = async (firedInGate) => {
7799
+ if (!turnAbort.signal.aborted && !runAbort.signal.aborted)
7800
+ return false;
7801
+ const timedOut = timeoutAbortReason(turnAbort.signal) ?? timeoutAbortReason(runAbort.signal);
7802
+ if (timedOut !== undefined) {
7803
+ if (timedOut.crewhausTimeout === "run" || opts.singleTurn === true) {
7804
+ await throwTimeout(timedOut);
7805
+ }
7806
+ if (firedInGate) {
7807
+ await logEvent("error", {
7808
+ name: timedOut.crewhausTimeout === "turn" ? "TurnTimeout" : "ModelCallTimeout",
7809
+ message: `turn aborted: the configured ${TIMEOUT_SPEC_KEYS[timedOut.crewhausTimeout]} (${timedOut.limitMs}ms) elapsed`,
7810
+ });
7811
+ }
7812
+ }
7813
+ return true;
7814
+ };
7815
+ /**
7816
+ * Did the OUTSIDE WORLD hand the run `url` whole, and nothing else put the
7817
+ * tagged content it carries there? Only then does a HEAD to it carry
7818
+ * nothing new back, and a lineage match on it is let through (§6.1, §10;
7819
+ * Pillar 3). `egress` is what the screen's classification found. Both must
7820
+ * hold:
7821
+ *
7822
+ * 1. a non-error result of an OUTSIDE READER holds the URL verbatim — a
7823
+ * tool that crosses the network (`ioCapability: "network"`) and writes
7824
+ * nothing (`readOnly`), or an MCP server (`mcp__*`, whose flags a spec
7825
+ * can only tighten, so none is ever `readOnly`): a search hit, a
7826
+ * fetched page's own address, an MCP server's answer. Its request
7827
+ * passed the egress fabric, and its answer is the outside world's.
7828
+ * `scope` is no test of that: a
7829
+ * local process tool is `external` too (GitCommit, GitDiff, Bash,
7830
+ * Format), and its result is text the model wrote — a commit message,
7831
+ * the diff of a file it edited — so a secret the model composed into a
7832
+ * URL comes back "handed" (the laundering the round-2 review found
7833
+ * through GitCommit, as round 1's did through UrlNormalize). A tool
7834
+ * that writes can echo what it sent, wherever it sent it;
7835
+ * 2. every tagged string the URL carries came in only inside results that
7836
+ * hand the URL whole: no other tool result holds it, and it was tagged
7837
+ * as a tool's or an MCP server's answer. A secret a tool read sits in
7838
+ * that tool's result without the URL, so a reader that hands back a
7839
+ * file or a record the model wrote the URL into (an MCP filesystem
7840
+ * read) still hands nothing new: the secret came from elsewhere.
7841
+ * Content tagged from memory, a skill, a channel, a sub-agent or a
7842
+ * consult is never excused, and nor is a match the plain substring
7843
+ * reading cannot account for (a decoded view's, a custom matcher's).
7844
+ */
7845
+ const handedByBoundary = (messages, url, egress) => {
7846
+ const readerCall = new Map();
7847
+ const results = [];
7848
+ for (const message of messages) {
7849
+ if (!Array.isArray(message.content))
7850
+ continue;
7851
+ for (const block of message.content) {
7852
+ if (typeof block !== "object" || block === null)
7853
+ continue;
7854
+ const b = block;
7855
+ if (b["type"] === "tool_use" && typeof b["id"] === "string") {
7856
+ const name = typeof b["name"] === "string" ? b["name"] : "";
7857
+ const tool = toolByName.get(name);
7858
+ // An MCP server's answer is the outside world's whatever its flags
7859
+ // say: a spec's MCP tool is never `readOnly` (its flags can only
7860
+ // tighten), so reading it by the flag counted no search hit an MCP
7861
+ // server returned. Condition 2 is what refuses a server that echoes
7862
+ // what the model wrote. A local process tool never hands anything.
7863
+ const outside = tool?.ioCapability !== "process" &&
7864
+ (name.startsWith("mcp__") ||
7865
+ (tool?.readOnly === true && tool.ioCapability === "network"));
7866
+ readerCall.set(b["id"], outside);
7867
+ }
7868
+ else if (b["type"] === "tool_result" && typeof b["tool_use_id"] === "string") {
7869
+ const text = gateResultText(b["content"]);
7870
+ const reader = readerCall.get(b["tool_use_id"]) === true && b["is_error"] !== true;
7871
+ results.push({ text, handed: reader && text.includes(url) });
7872
+ }
7873
+ }
7874
+ }
7875
+ // 1 — handed whole by an outside reader.
7876
+ if (!results.some((r) => r.handed))
7877
+ return false;
7878
+ // 2 — what the URL carries, as the plain substring reading finds it.
7879
+ const carried = [];
7880
+ let found = 0;
7881
+ for (const [tagged, origin] of runContext.dataLineage ?? []) {
7882
+ if (tagged.length < MIN_MATCH_LENGTH || !url.includes(tagged))
7883
+ continue;
7884
+ found += 1;
7885
+ if (origin === "user")
7886
+ continue;
7887
+ if (origin !== "tool" && origin !== "mcp")
7888
+ return false;
7889
+ carried.push(tagged);
7890
+ }
7891
+ if (carried.length === 0 || egress.matchCount > found)
7892
+ return false;
7893
+ return carried.every((tagged) => results.some((r) => r.handed && r.text.includes(tagged)) &&
7894
+ results.every((r) => r.handed || !r.text.includes(tagged)));
7895
+ };
7896
+ /**
7897
+ * Pillar 3 sink-side fabric (design §6.1, §10) — the gate's own egress:
7898
+ * a `sources.resolve: head` request to a URL the model wrote. It is
7899
+ * classified like an external tool call to a destination the model chose
7900
+ * (`external-dynamic`, the run's egress matcher): content a boundary
7901
+ * tagged from a non-user origin — a secret a tool read — refuses the
7902
+ * request, and the verifier sends nothing. One `permission_decision`
7903
+ * trace event per screen, as on the tool path; the durable
7904
+ * `egress_decision` record is the verifier's, which also knows what the
7905
+ * request came to. A URL an outside reader's result handed the run
7906
+ * VERBATIM (a search hit, a fetched page's own address), carrying nothing
7907
+ * that reached the run any other way ({@link handedByBoundary}), carries
7908
+ * nothing new back to its host, so a match on it is let through, and the
7909
+ * event says why: refusing it would fail an honest citation of a search
7910
+ * result. Built per verification over the transcript it reads.
7911
+ */
7912
+ const gateEgressScreen = (messages) => async (payload, sinkId) => {
7913
+ const egress = await classifyEgress(payload, runContext, {
7914
+ sinkId,
7915
+ sinkScope: "external-dynamic",
7916
+ ...(opts.egressMatcher !== undefined ? { matcher: opts.egressMatcher } : {}),
7917
+ });
7918
+ const handed = egress.verdict === "block" && handedByBoundary(messages, payload, egress);
7919
+ const verdict = handed ? "pass" : egress.verdict;
7920
+ bus.publish({
7921
+ ...bus.envelope(),
7922
+ kind: "permission_decision",
7923
+ toolName: sinkId,
7924
+ decision: verdict === "block" ? "deny" : "allow",
7925
+ mode: permissionMode,
7926
+ outcome: verdict === "pass"
7927
+ ? "egress-passed"
7928
+ : verdict === "warn"
7929
+ ? "egress-warned"
7930
+ : "egress-blocked",
7931
+ ...(egress.originsFound.length > 0
7932
+ ? {
7933
+ reason: handed
7934
+ ? `egress: the URL was handed to the run verbatim (${summarizeEgress(egress)})`
7935
+ : `egress: ${summarizeEgress(egress)}`,
7936
+ }
7937
+ : {}),
7938
+ });
7939
+ if (verdict !== "pass") {
7940
+ runContext.logger.warn("egress classification non-clean", {
7941
+ sinkId,
7942
+ verdict,
7943
+ originsFound: egress.originsFound,
7944
+ matchCount: egress.matchCount,
7945
+ });
7946
+ }
7947
+ return {
7948
+ verdict,
7949
+ sinkScope: egress.sinkScope,
7950
+ originsFound: egress.originsFound,
7951
+ matchCount: egress.matchCount,
7952
+ };
7953
+ };
7954
+ /**
7955
+ * 0.8.0 (design §5.1, §5.3) — ONE verification pass over a completed
7956
+ * attempt, recorded, and what its verdict asks for. The caller acts on the
7957
+ * step: it owns the attempt, the transcript and the routing lines a re-run
7958
+ * touches.
7959
+ *
7960
+ * 1. a turn the abort tree stopped did not complete — it is handed back
7961
+ * un-verified, exactly as the evaluation loop hands one back
7962
+ * un-graded, unless a fired wall-clock limit makes the stop terminal
7963
+ * (G10: the run deadline anywhere, any limit on the single-turn path),
7964
+ * which throws the classified `timeout` stop as `runOneTurn` does. The
7965
+ * same check runs again when `verify` settles and once the pass is
7966
+ * recorded, so a limit that fires WHILE the gate works is classified
7967
+ * too;
7968
+ * 2. `verify` — a THROW is grading-infrastructure failure, not a verdict:
7969
+ * logged (a warning + an `error` event-log line), and the bundle is
7970
+ * `unverifiedBundle(…)` so no surface prints a ✓; the answer stands;
7971
+ * 3. `persist` (failure warned, never fatal), under the SESSION's turn
7972
+ * number (`resumedTurns` + the run's own), so a resumed session's turn
7973
+ * never files over an earlier turn's bundle (§5.3);
7974
+ * 4. one `provability_graded` trace event + event-log line, the
7975
+ * `provability_evaluated` audit record when the sink is wired, and
7976
+ * `onBundle`;
7977
+ * 5. the verdict: pass / unverified / `note` → stands; `halt` → the
7978
+ * caller's classified stop; `retry` → the nudge composed from the
7979
+ * bundle, for the caller to re-run the turn with; `escalate` → the same
7980
+ * nudge and the rung (an unavailable rung leaves the answer standing,
7981
+ * note semantics; a rung the abort tree stopped before it ran is
7982
+ * recorded as `model_stage{escalate, skipped, cause: "aborted"}`, and
7983
+ * is named `escalatedTo` only when that announcement went out before
7984
+ * the stop; a turn that already made `max_escalations` escalations is
7985
+ * recorded as `skipped, cause: "max_escalations"`, as the cascade's
7986
+ * is). Both re-runs count against `maxRetries`; spent, the last answer
7987
+ * stands and the failing event trail tells the story.
7988
+ */
7989
+ async function provabilityPass(provability, ladder, messages, attempt, stage) {
7990
+ const maxRetries = provabilityRetryCap(provability);
7991
+ // 1 — an aborted turn never completed: verifying its partial output
7992
+ // would be noise, and a retry would fight the very signal that stopped
7993
+ // it. The stop landed in the turn (whose `runOneTurn` writes the REPL's
7994
+ // timeout line when it fired there), not in the gate.
7995
+ if (await stoppedByAbort(false))
7996
+ return { kind: "stopped" };
7997
+ const retryIndex = ladder.passes;
7998
+ const turnNumber = resumedTurns + runContext.turnNumber;
7999
+ const servedModel = attempt.servedModel ?? lastResponseWireModel;
8000
+ // 2 — verify.
8001
+ let verified;
8002
+ let verifyFailure;
8003
+ const finalText = terminalText(attempt.terminalContent);
8004
+ const verifyText = (text) => provability.verify({
8005
+ finalText: text,
8006
+ messages,
8007
+ isSynthetic: isSyntheticMessage,
8008
+ usage: attempt.usage,
8009
+ // A waiver judge meters itself on THIS bus (role "judge"), so its
8010
+ // spend lands in the run's budget like the quality judge's.
8011
+ bus,
8012
+ ...(servedModel !== undefined ? { servedModel } : {}),
8013
+ ...(attempt.profile !== undefined ? { profile: attempt.profile } : {}),
8014
+ ...(stage !== undefined ? { stage } : {}),
8015
+ turnNumber,
8016
+ retryIndex,
8017
+ // The session whose event log holds the evidence — on `--resume`
8018
+ // the resumed one. The loop's resolved id: boot binds the run
8019
+ // context to it (a caller-built context naming another session is
8020
+ // refused), so this always equals `runContext.sessionId`.
8021
+ sessionId,
8022
+ signal: turnAbort.signal,
8023
+ // The waiver judge stops asking once the share is spent (§6.2), and
8024
+ // a HEAD the verifier sends is screened and audited like any egress
8025
+ // (§6.1, §10).
8026
+ ...(opts.budget !== undefined ? { judgeShareExhausted } : {}),
8027
+ ...(opts.egressAuditSink !== undefined ? { egressAuditSink: opts.egressAuditSink } : {}),
8028
+ screenEgress: gateEgressScreen(messages),
8029
+ });
8030
+ out.spinner.start("verifying");
8031
+ try {
8032
+ verified = await verifyText(finalText);
8033
+ // §5.4 — where the turn streams to its reader, a final message that
8034
+ // states nothing ("Done.", "See above.") is not the answer the reader
8035
+ // holds: what the turn printed above it is. Its vacuous pass would put
8036
+ // a ✓ under claims nobody graded — a claim made before a tool call, a
8037
+ // rejected attempt the next one points back at — so that text is
8038
+ // graded instead. A final message that makes a claim is the answer,
8039
+ // graded alone, as on every surface.
8040
+ const shown = streamsTheTurn(provability)
8041
+ ? streamedTurnText(messages, ladder.rejectedThrough)
8042
+ : undefined;
8043
+ if (shown !== undefined &&
8044
+ shown.trim() !== "" &&
8045
+ shown !== finalText &&
8046
+ isGradedBundle(verified) &&
8047
+ verified.verdict === "pass" &&
8048
+ verified.claimCount === 0) {
8049
+ verified = await verifyText(shown);
8050
+ }
8051
+ }
8052
+ catch (err) {
8053
+ verifyFailure = { error: err };
8054
+ }
8055
+ finally {
8056
+ out.spinner.stop();
8057
+ }
8058
+ // A verdict — or a throw — that settles after the abort tree fired
8059
+ // belongs to a turn that did not complete inside its window. It is
8060
+ // neither recorded nor acted on: a verifier that ignores the signal
8061
+ // would otherwise retry an aborted turn (a nudge nothing answers) or
8062
+ // reclassify a timed-out run as a provability halt, and a verifier
8063
+ // that stopped BECAUSE of the abort is the abort, not an outage.
8064
+ if (await stoppedByAbort(true))
8065
+ return { kind: "stopped" };
8066
+ ladder.passes += 1;
8067
+ let bundle;
8068
+ if (verifyFailure === undefined && isGradedBundle(verified)) {
8069
+ bundle = verified;
8070
+ }
8071
+ else {
8072
+ // A THROW — or a result that is not a well-formed bundle — is
8073
+ // grading-INFRASTRUCTURE failure, not a verdict: fail open.
8074
+ const err = verifyFailure !== undefined
8075
+ ? verifyFailure.error
8076
+ : new Error("the verifier returned no proof bundle");
8077
+ const { name, message } = describeThrown(err, "ProvabilityError");
8078
+ runContext.logger.warn("provability: verifier threw — the answer stands unverified", {
8079
+ name,
8080
+ message,
8081
+ });
8082
+ await logEvent("error", { name, message: `provability verifier failed: ${message}` });
8083
+ bundle = unverifiedBundle(provability, err, retryIndex);
8084
+ }
8085
+ // 3 — persist.
8086
+ let bundlePath;
8087
+ if (provability.persist !== undefined) {
8088
+ try {
8089
+ bundlePath = await provability.persist(bundle, { sessionId, turnNumber });
8090
+ }
8091
+ catch (err) {
8092
+ runContext.logger.warn("provability: persisting the proof bundle failed — the verdict stands", {
8093
+ turnNumber,
8094
+ retryIndex,
8095
+ message: describeThrown(err, "Error").message,
8096
+ });
8097
+ }
8098
+ }
8099
+ // Decided BEFORE the publish so a failing pass names the rung it hands
8100
+ // the turn to (`escalatedTo`), as the evaluation cascade's does.
8101
+ const failing = bundle.verdict === "fail";
8102
+ // What this pass graded is graded: a later claimless message's streamed
8103
+ // text starts after it (`streamedTurnText`).
8104
+ if (failing)
8105
+ ladder.rejectedThrough = messages[messages.length - 1];
8106
+ const spent = ladder.reruns >= maxRetries;
8107
+ if (failing && provability.onFail === "escalate" && ladder.escalation === undefined) {
8108
+ ladder.escalation = { target: resolveProvabilityEscalation(provability) };
8109
+ }
8110
+ const rung = failing && provability.onFail === "escalate" && !spent
8111
+ ? ladder.escalation?.target
8112
+ : undefined;
8113
+ // §5.1 — `escalate` shares the cascade's `max_escalations`: a turn that
8114
+ // has made them all keeps its answer, as the cascade's last rung does.
8115
+ const capped = rung !== undefined && ladder.escalations >= turnEscalationCap();
8116
+ /** The rung this failing pass hands the turn to, the abort tree aside. */
8117
+ const wantedRung = capped ? undefined : rung;
8118
+ // Announced only while the abort tree is quiet: a timer that fired
8119
+ // while the bundle was persisted means the rung will never run (the
8120
+ // abort check below returns or throws first), and the durable line must
8121
+ // not name an escalation that did not happen.
8122
+ const escalateTo = wantedRung !== undefined && !turnAbort.signal.aborted && !runAbort.signal.aborted
8123
+ ? wantedRung
8124
+ : undefined;
8125
+ // 4 — publish. The gate's own pass counter is authoritative for
8126
+ // `retryIndex` (a verifier that ignores the one it was handed cannot
8127
+ // make two passes read as the original answer).
8128
+ const summary = { ...summarizeBundle(bundle), retryIndex };
8129
+ const shownPath = shownBundlePath(provability, bundlePath);
8130
+ bus.publish({
8131
+ ...bus.envelope(),
8132
+ kind: "provability_graded",
8133
+ ...summary,
8134
+ maxRetries,
8135
+ ...(shownPath !== undefined ? { bundlePath: shownPath } : {}),
8136
+ ...(escalateTo !== undefined ? { escalatedTo: escalateTo.modelString } : {}),
8137
+ });
8138
+ // The durable twin (event-log kind `provability_graded`): the trace
8139
+ // line minus its envelope, plus the session turn it graded, with the
8140
+ // bundle path as persisted.
8141
+ await logEvent("provability_graded", {
8142
+ ...summary,
8143
+ maxRetries,
8144
+ turnNumber,
8145
+ ...(bundlePath !== undefined ? { bundlePath } : {}),
8146
+ ...(escalateTo !== undefined ? { escalatedTo: escalateTo.modelString } : {}),
8147
+ });
8148
+ // §5.3 — the hash-chained audit record beside the justification gate's,
8149
+ // best-effort but surfaced exactly like that path: a full audit disk
8150
+ // must not crash a governed run.
8151
+ if (opts.justificationAuditSink !== undefined) {
8152
+ try {
8153
+ await opts.justificationAuditSink.append({
8154
+ kind: "provability_evaluated",
8155
+ payload: { ...summary, turnNumber, sessionId },
8156
+ });
8157
+ }
8158
+ catch (err) {
8159
+ runContext.logger.warn("provability audit append failed", {
8160
+ turnNumber,
8161
+ retryIndex,
8162
+ error: describeThrown(err, "Error").message,
8163
+ });
8164
+ }
8165
+ }
8166
+ if (provability.onBundle !== undefined) {
8167
+ try {
8168
+ provability.onBundle(bundle, bundlePath);
8169
+ }
8170
+ catch (err) {
8171
+ runContext.logger.warn("provability: the onBundle observer threw — ignored", {
8172
+ message: describeThrown(err, "Error").message,
8173
+ });
8174
+ }
8175
+ }
8176
+ // A rung the recorded failing pass wanted but the abort tree stopped
8177
+ // first never runs: say so on the routing record, as the cascade's
8178
+ // `max_escalations` skip does — before the abort check below can throw.
8179
+ // When the abort landed during the event-log line or the audit append
8180
+ // this also retracts the `escalatedTo` those lines already carry; a
8181
+ // `model_stage{started}` or this `skipped` always follows one.
8182
+ if (wantedRung !== undefined && (turnAbort.signal.aborted || runAbort.signal.aborted)) {
8183
+ publishStage({
8184
+ stage: "escalate",
8185
+ strategy: "cascade",
8186
+ role: "escalation",
8187
+ candidate: wantedRung,
8188
+ outcome: "skipped",
8189
+ cause: "aborted",
8190
+ });
8191
+ }
8192
+ if (capped && rung !== undefined) {
8193
+ publishStage({
8194
+ stage: "escalate",
8195
+ strategy: "cascade",
8196
+ role: "escalation",
8197
+ candidate: rung,
8198
+ outcome: "skipped",
8199
+ cause: "max_escalations",
8200
+ });
8201
+ }
8202
+ // 5 — the verdict. A stop that landed while the pass was being
8203
+ // recorded (persist, the event-log line, the audit append): a terminal
8204
+ // timeout throws here whatever the verdict; any other abort leaves the
8205
+ // recorded verdict standing but never re-runs the turn on a signal
8206
+ // that is already aborted.
8207
+ const stopped = await stoppedByAbort(true);
8208
+ ladder.standing = { attempt, bundle, ...(bundlePath !== undefined ? { bundlePath } : {}) };
8209
+ if (!failing || provability.onFail === "note")
8210
+ return { kind: "stands", aborted: stopped };
8211
+ if (provability.onFail === "halt") {
8212
+ return { kind: "halt", bundle, ...(bundlePath !== undefined ? { bundlePath } : {}) };
8213
+ }
8214
+ // `escalate` without a pool (warned once at resolve time): note semantics.
8215
+ if (provability.onFail === "escalate" && ladder.escalation?.target === undefined) {
8216
+ return { kind: "stands", aborted: stopped };
8217
+ }
8218
+ if (spent || stopped || capped)
8219
+ return { kind: "stands", aborted: stopped };
8220
+ const nudge = composeNudge(provability, bundle);
8221
+ markRejected(provability, ladder, bundle, bundlePath);
8222
+ if (escalateTo !== undefined)
8223
+ return { kind: "escalate", nudge, target: escalateTo };
8224
+ return { kind: "retry", nudge };
8225
+ }
8226
+ /**
8227
+ * §5.1 — the classified terminal stop of `on_fail: halt` (class
8228
+ * `"provability"`, exit {@link EXIT_CODES.provability}), the ✗ footer
8229
+ * first: a halted run returns no reply to carry it, so it goes to the
8230
+ * output whatever `footerTarget` says — unless the caller carries the
8231
+ * bundle itself (`"none"`). The detail names the bundle the way the
8232
+ * run's live surfaces show it.
8233
+ */
8234
+ const haltOnProvability = async (provability, halted) => {
8235
+ const report = provabilityFailureReport(halted.bundle, shownBundlePath(provability, halted.bundlePath));
8236
+ if ((provability.footerTarget ?? "stream") !== "none") {
8237
+ const footer = renderStanding(provability, halted.bundle, halted.bundlePath);
8238
+ if (footer !== undefined)
8239
+ out.write(`${footer}\n`);
8240
+ }
8241
+ await publishRunFailed(report);
8242
+ throw new RunFailedError(report);
8243
+ };
8244
+ /**
8245
+ * §5.1 — `escalate`: the nudge, then the turn on the rung (`defer` as the
8246
+ * caller folds the attempt's routing lines). An unavailable rung leaves
8247
+ * the answer standing with its failing verdict (note semantics) and
8248
+ * withdraws the nudge from the live transcript: `undefined`. A classified
8249
+ * halt or an abort on the rung is terminal for the RUN and propagates, as
8250
+ * it does out of the cascade.
8251
+ */
8252
+ const escalateOnProvability = async (messages, step, defer) => {
8253
+ // The transcript as verified — restored should the rung be unavailable.
8254
+ const verifiedTranscript = messages.slice();
8255
+ messages.push(markSynthetic({ role: "user", content: step.nudge }));
8256
+ await logEvent("user_message", { content: step.nudge, synthetic: true });
8257
+ try {
8258
+ return await runEscalationStage(messages, step.target, undefined, "provability: escalated after a failing verdict", defer, true);
8259
+ }
8260
+ catch (err) {
8261
+ if (isAbortError(err) || isRunFailedError(err))
8262
+ throw err;
8263
+ 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 });
8264
+ // Withdrawn from the LIVE transcript only: the nudge's synthetic
8265
+ // `user_message` line is already on disk, so a `--resume` replays
8266
+ // it ahead of the next input — the same live/resume divergence as
8267
+ // the cascade's withdrawn correction above, which a replay-side
8268
+ // withdrawal marker would fix for both at once.
8269
+ messages.splice(0, messages.length, ...verifiedTranscript);
8270
+ return undefined;
8271
+ }
8272
+ };
8273
+ /**
8274
+ * §5.4 — a gated attempt handed back to its call site. The STANDING pass
8275
+ * is rendered, and only when it graded this very attempt (one the abort
8276
+ * tree stopped before its pass was recorded shows nothing). A rejected
8277
+ * attempt the reader never saw is never shown; one the reader saw stream
8278
+ * past already carries its ✗ (`markRejected`), and an escalation that could
8279
+ * not run leaves that same verdict standing, which is not written twice.
8280
+ * `footerTarget: "stream"` writes it to the run's output after the answer,
8281
+ * on its own line; `"reply"` hands it back as `footer` for the caller to
8282
+ * append to the text the run returns; `"none"` renders nothing (the caller
8283
+ * carries the bundle itself, as the managed gateway's `proof` field does).
8284
+ * It never enters `messages`: the model must not read its own footer next
8285
+ * turn.
8286
+ */
8287
+ const finishGated = (provability, ladder, attempt) => {
8288
+ const target = provability.footerTarget ?? "stream";
8289
+ const standing = ladder.standing;
8290
+ const footer = target !== "none" &&
8291
+ standing !== undefined &&
8292
+ standing.attempt === attempt &&
8293
+ standing.bundle !== ladder.marked
8294
+ ? renderStanding(provability, standing.bundle, standing.bundlePath)
8295
+ : undefined;
8296
+ if (footer === undefined)
8297
+ return { ...attempt, gated: true };
8298
+ if (target === "reply")
8299
+ return { ...attempt, footer, gated: true };
8300
+ out.write(`${footer}\n`);
8301
+ return { ...attempt, gated: true };
8302
+ };
8303
+ /**
8304
+ * 0.8.0 (design §5.1) — one COMPLETED turn through the provability gate.
8305
+ * `inner` is what the call site ran before the gate existed
8306
+ * (`runCommitteeOrTurn` on the single-turn path, `runEvaluatedTurn` on the
8307
+ * REPL). Without `opts.provability` this IS `inner(messages)`.
8308
+ *
8309
+ * The evaluated turn runs the ladder itself, on every attempt and before
8310
+ * every grade (provability first, §5.1), and comes back `gated`; it is
8311
+ * handed on as it is. What this verifies is the one answer no evaluated
8312
+ * turn produced — a committee verdict — pass by pass (`provabilityPass`):
8313
+ * a retry runs `inner` again, an escalation runs the turn on the rung,
8314
+ * and a halt is the classified stop. A stop the abort tree made inside
8315
+ * `inner` hands the turn back un-verified, or throws the classified
8316
+ * timeout (G10), before anything else.
8317
+ */
8318
+ async function runProvableTurn(messages, inner) {
8319
+ const provability = opts.provability;
8320
+ if (provability === undefined)
8321
+ return inner(messages);
8322
+ const ladder = newProvabilityLadder();
8323
+ activeLadder = ladder;
8324
+ try {
8325
+ let attempt = await inner(messages);
8326
+ /** The cascade stage of the attempt being verified: set when it came off the escalation rung. */
8327
+ let stage;
8328
+ for (;;) {
8329
+ if (await stoppedByAbort(false))
8330
+ return attempt;
8331
+ if (attempt.gated === true)
8332
+ return attempt;
8333
+ const step = await provabilityPass(provability, ladder, messages, attempt, stage);
8334
+ if (step.kind === "stopped")
8335
+ return attempt;
8336
+ if (step.kind === "stands")
8337
+ return finishGated(provability, ladder, attempt);
8338
+ if (step.kind === "halt")
8339
+ return await haltOnProvability(provability, step);
8340
+ ladder.reruns += 1;
8341
+ if (step.kind === "escalate") {
8342
+ ladder.escalations += 1;
8343
+ const escalated = await escalateOnProvability(messages, step, false);
8344
+ if (escalated === undefined)
8345
+ return finishGated(provability, ladder, attempt);
8346
+ attempt = escalated;
8347
+ stage = "escalate";
8348
+ continue;
8349
+ }
8350
+ // onFail: "retry".
8351
+ messages.push(markSynthetic({ role: "user", content: step.nudge }));
8352
+ await logEvent("user_message", { content: step.nudge, synthetic: true });
8353
+ attempt = await inner(messages);
8354
+ stage = undefined;
8355
+ }
8356
+ }
8357
+ finally {
8358
+ activeLadder = undefined;
8359
+ }
8360
+ }
6395
8361
  // Single-shot path used by the workflow target and (Section 12) the
6396
8362
  // channel-bot session router. Runs one user→assistant turn (with the tool
6397
8363
  // inner-loop until Done), persists the transcript, returns the terminal
@@ -6488,16 +8454,31 @@ export async function runChatLoop(opts) {
6488
8454
  armTurnTimer();
6489
8455
  // 0.6.0 §7.8 — the shadow re-runs exactly what the primary answered.
6490
8456
  const shadowSeed = [...messages];
6491
- const { terminalContent } = await runCommitteeOrTurn(messages);
8457
+ // 0.8.0 §5.1 — the provability gate wraps the (committee or evaluated)
8458
+ // turn; without `opts.provability` it is exactly `runCommitteeOrTurn`.
8459
+ const { terminalContent, footer } = await runProvableTurn(messages, runCommitteeOrTurn);
6492
8460
  clearTurnTimer();
6493
- maybeScheduleShadow(shadowSeed, terminalText(terminalContent));
8461
+ const answer = terminalText(terminalContent);
8462
+ maybeScheduleShadow(shadowSeed, answer);
6494
8463
  bus.publish({
6495
8464
  ...bus.envelope(),
6496
8465
  kind: "turn_end",
6497
8466
  turn: runContext.turnNumber,
6498
8467
  durationMs: performance.now() - t0SingleTurn,
6499
8468
  });
6500
- return terminalText(terminalContent);
8469
+ // §5.4 — `footerTarget: "reply"`: the proof footer travels in the text
8470
+ // the run RETURNS (what a channel bot sends, what the gateway answers),
8471
+ // after a blank line — never in `messages`, so the transcript the model
8472
+ // reads next turn holds the answer alone. An empty answer carries the
8473
+ // footer alone (no leading blank line). Under `provability:` the text
8474
+ // served is the answer with every footer-shaped line of it marked as
8475
+ // the model's (`./forged-footer`, §1 principle 2): whatever `render`
8476
+ // and the target say, no line the model wrote passes for the verdict.
8477
+ // The transcript and the shadow keep its own words.
8478
+ const served = opts.provability !== undefined ? neutralizeFooterLines(answer) : answer;
8479
+ if (footer === undefined)
8480
+ return served;
8481
+ return served === "" ? footer : `${served}\n\n${footer}`;
6501
8482
  }
6502
8483
  finally {
6503
8484
  // 0.6.0 §7.8 — the single turn IS the run. A per-message host
@@ -6777,7 +8758,13 @@ export async function runChatLoop(opts) {
6777
8758
  try {
6778
8759
  // 0.6.0 §7.8 — the shadow re-runs exactly what the primary answered.
6779
8760
  const shadowSeed = [...messages];
6780
- const { terminalContent } = await runEvaluatedTurn(messages);
8761
+ // 0.8.0 §5.1 — the provability gate wraps the evaluated turn; without
8762
+ // `opts.provability` it is exactly `runEvaluatedTurn`. The REPL
8763
+ // returns no per-turn reply, so a `footerTarget: "reply"` footer has
8764
+ // nothing to ride on and is written to the output like `"stream"`.
8765
+ const { terminalContent, footer } = await runProvableTurn(messages, runEvaluatedTurn);
8766
+ if (footer !== undefined)
8767
+ out.write(`${footer}\n`);
6781
8768
  // Item 1 — the exit rating prompt's "worth rating" floor: count only
6782
8769
  // turns that ended in a real assistant answer.
6783
8770
  if (terminalText(terminalContent).trim() !== "")
@@ -7089,20 +9076,97 @@ async function curateActiveContext(messages, snipKeepHead, snipKeepTail, cfg) {
7089
9076
  return { messages: out, before, after, dropped: before - after, bytesSaved, embedded };
7090
9077
  }
7091
9078
  /**
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.
9079
+ * Item 2 / G21 — render the recalled-memory system block for both recall
9080
+ * modes (#53). Pillar 3: every line is classified at TrustOrigin `"memory"`
9081
+ * BEFORE it reaches the system prompt, because a fact, wiki article, or
9082
+ * session summary written in an earlier session may have absorbed attacker
9083
+ * text, and the system region has no post-tool classifier behind it. A
9084
+ * malicious line is replaced by the redaction notice; a suspicious one is kept
9085
+ * and logged. The admitted lines are then classified together, so an injection
9086
+ * split across two of them is redacted too (see `redactSplitInjections`); each
9087
+ * line still admitted is lineage-tagged for the egress fabric. Each line then
9088
+ * has any
9089
+ * `</recalled_memory>` breakout delimiter neutralized. A classifier rejection
9090
+ * propagates, so both callers fail closed. Returns `undefined` when there is
9091
+ * nothing to recall.
7098
9092
  */
7099
- async function renderRecalledMemory(lines) {
9093
+ async function renderRecalledMemory(lines, runContext) {
7100
9094
  if (lines.length === 0)
7101
9095
  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;
9096
+ const rendered = [...lines];
9097
+ const admitted = [];
9098
+ for (const [i, line] of lines.entries()) {
9099
+ const boundary = await classifyBoundary(line, { origin: "memory" });
9100
+ const rules = [...new Set(boundary.verdict.hits.map((h) => h.rule))];
9101
+ if (boundary.action === "redact") {
9102
+ runContext.logger.warn("recalled memory line redacted (prompt injection detected)", {
9103
+ rules,
9104
+ });
9105
+ rendered[i] = boundary.redacted ?? "";
9106
+ continue;
9107
+ }
9108
+ if (boundary.action === "warn") {
9109
+ runContext.logger.warn("suspicious recalled memory line kept", { rules });
9110
+ }
9111
+ admitted.push(i);
9112
+ }
9113
+ const split = await redactSplitInjections(admitted.map((i) => lines[i]), runContext);
9114
+ admitted.forEach((i, j) => {
9115
+ const notice = split.get(j);
9116
+ if (notice !== undefined)
9117
+ rendered[i] = notice;
9118
+ else
9119
+ tagContent(runContext, lines[i], "memory");
9120
+ });
9121
+ const body = rendered.map((l) => `- ${escapeBoundaryDelimiter(l, "recalled_memory")}`).join("\n");
9122
+ return `<recalled_memory>\nRelevant facts remembered from earlier sessions:\n${body}\n</recalled_memory>`;
9123
+ }
9124
+ /**
9125
+ * Pillar 3 — an injection split across recalled lines. Each of `lines` passed
9126
+ * classification on its own, but an attacker who can plant two memories that
9127
+ * recall side by side can split one phrase between them ("… ignore previous" /
9128
+ * "instructions and …"): each half classifies clean, and the model still reads
9129
+ * one sentence. So the lines are also classified joined with "\n" at
9130
+ * TrustOrigin `"memory"`. The raw join, not the rendered block, because the
9131
+ * block's `- ` bullets break the detector's phrase rules without breaking the
9132
+ * sentence for the model. When the join is malicious, each adjacent pair is
9133
+ * classified and both lines of a malicious pair are redacted. When no pair
9134
+ * reproduces the verdict, or the lines left still join malicious (a split over
9135
+ * three lines, or weak hits that only add up across the block), every line is
9136
+ * redacted: fail closed. Returns the redaction notice for each line to redact,
9137
+ * by index into `lines`; a classifier rejection propagates.
9138
+ */
9139
+ async function redactSplitInjections(lines, runContext) {
9140
+ const redacted = new Map();
9141
+ if (lines.length < 2)
9142
+ return redacted;
9143
+ const joined = await classifyBoundary(lines.join("\n"), { origin: "memory" });
9144
+ if (joined.action !== "redact")
9145
+ return redacted;
9146
+ for (let i = 0; i + 1 < lines.length; i++) {
9147
+ const pair = await classifyBoundary(`${lines[i]}\n${lines[i + 1]}`, { origin: "memory" });
9148
+ if (pair.action !== "redact")
9149
+ continue;
9150
+ runContext.logger.warn("recalled memory lines redacted (prompt injection split across lines)", {
9151
+ rules: [...new Set(pair.verdict.hits.map((h) => h.rule))],
9152
+ });
9153
+ redacted.set(i, pair.redacted ?? "");
9154
+ redacted.set(i + 1, pair.redacted ?? "");
9155
+ }
9156
+ const left = lines.filter((_, i) => !redacted.has(i));
9157
+ const residual = redacted.size === 0
9158
+ ? joined
9159
+ : left.length > 1
9160
+ ? await classifyBoundary(left.join("\n"), { origin: "memory" })
9161
+ : undefined;
9162
+ if (residual?.action === "redact") {
9163
+ 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))] });
9164
+ for (let i = 0; i < lines.length; i++) {
9165
+ if (!redacted.has(i))
9166
+ redacted.set(i, residual.redacted ?? "");
9167
+ }
9168
+ }
9169
+ return redacted;
7106
9170
  }
7107
9171
  /**
7108
9172
  * Item 9 / G79 — stamp ONE message-level cache breakpoint so the settled
@@ -7252,18 +9316,16 @@ async function maybeCompact(args, onCompaction) {
7252
9316
  return snipped;
7253
9317
  }
7254
9318
  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 } : {}),
9319
+ const after = await summarizeHistory({
9320
+ snipped,
9321
+ adapter,
9322
+ model,
9323
+ contextLimit,
9324
+ ...(onEvict !== undefined ? { onEvict } : {}),
9325
+ ...(getLedgerText !== undefined ? { getLedgerText } : {}),
7264
9326
  ...(bus !== undefined ? { bus } : {}),
7265
- ...(compactionSpecModel !== undefined ? { specModel: compactionSpecModel } : {}),
7266
- ...(compactionParams !== undefined ? { params: compactionParams } : {}),
9327
+ ...(compactionSpecModel !== undefined ? { compactionSpecModel } : {}),
9328
+ ...(compactionParams !== undefined ? { compactionParams } : {}),
7267
9329
  });
7268
9330
  if (onCompaction !== undefined) {
7269
9331
  const summary = summaryTextOf(after);
@@ -7283,24 +9345,71 @@ async function maybeCompact(args, onCompaction) {
7283
9345
  * largest blob).
7284
9346
  */
7285
9347
  async function forceCompact(args) {
7286
- const { messages, adapter, model, snipKeepHead, snipKeepTail, logger, onEvict, getLedgerText, bus, compactionSpecModel, compactionParams, } = args;
9348
+ const { messages, adapter, model, contextLimit, snipKeepHead, snipKeepTail, logger, onEvict, getLedgerText, bus, compactionSpecModel, compactionParams, } = args;
7287
9349
  const snipped = snip(messages, snipKeepHead, snipKeepTail);
7288
9350
  // §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).
9351
+ // the snip diff first, then what autocompact is about to replace
9352
+ // (disjoint sets, so no record is written twice).
7291
9353
  if (onEvict !== undefined) {
7292
9354
  const evicted = snippedAway(messages, snipped);
7293
9355
  if (evicted.length > 0)
7294
9356
  await onEvict(evicted);
7295
9357
  }
7296
9358
  logger.info("reactive snip applied", { before: messages.length, after: snipped.length });
7297
- if (onEvict !== undefined && snipped.length > 0)
7298
- await onEvict(snipped);
9359
+ return await summarizeHistory({
9360
+ snipped,
9361
+ adapter,
9362
+ model,
9363
+ contextLimit,
9364
+ ...(onEvict !== undefined ? { onEvict } : {}),
9365
+ ...(getLedgerText !== undefined ? { getLedgerText } : {}),
9366
+ ...(bus !== undefined ? { bus } : {}),
9367
+ ...(compactionSpecModel !== undefined ? { compactionSpecModel } : {}),
9368
+ ...(compactionParams !== undefined ? { compactionParams } : {}),
9369
+ });
9370
+ }
9371
+ /**
9372
+ * The pending user message survives compaction verbatim only while it is at
9373
+ * most this share of the context limit, so keeping it can never push the
9374
+ * compacted history back over the trigger threshold.
9375
+ */
9376
+ const KEEP_PENDING_CONTEXT_SHARE = 0.25;
9377
+ /**
9378
+ * The autocompact step shared by the pre-turn ladder and the reactive path.
9379
+ *
9380
+ * autoCompact ends the history on a user turn — the pending user message
9381
+ * kept verbatim, or a continuation notice — because current Claude models
9382
+ * reject a trailing assistant turn as prefill. This wrapper keeps the
9383
+ * runtime's two contracts intact around that:
9384
+ * - §2.3 externalize-before-drop: exactly `plan.toSummarize` is evicted,
9385
+ * before the summarizer call, so a kept message is never ALSO copied into
9386
+ * the requirements ledger. `planCompaction` is pure, so this plan and the
9387
+ * one autoCompact computes agree given the same `keepPendingMaxTokens`.
9388
+ * - §7.2.1 human-text routing: the marker and the continuation notice are
9389
+ * runtime-injected, so they are marked synthetic. A kept message is the
9390
+ * original object and keeps whatever mark it already had.
9391
+ */
9392
+ async function summarizeHistory(args) {
9393
+ const { snipped, adapter, model, contextLimit, onEvict, getLedgerText } = args;
9394
+ const keepPendingMaxTokens = Math.floor(contextLimit * KEEP_PENDING_CONTEXT_SHARE);
9395
+ const plan = planCompaction(snipped, { keepPendingMaxTokens });
9396
+ // §2.3 — externalize what the summary replaces before the summarizer
9397
+ // call, so the records survive even a summarizer failure. The ledger
9398
+ // anchor is read afterwards so this step's evictions are part of it.
9399
+ if (onEvict !== undefined && plan.toSummarize.length > 0)
9400
+ await onEvict(plan.toSummarize);
7299
9401
  const ledgerText = getLedgerText?.();
7300
- return await autoCompact(snipped, adapter, model, {
9402
+ const after = await autoCompact(snipped, adapter, model, {
9403
+ keepPendingMaxTokens,
7301
9404
  ...(ledgerText !== undefined ? { ledgerText } : {}),
7302
- ...(bus !== undefined ? { bus } : {}),
7303
- ...(compactionSpecModel !== undefined ? { specModel: compactionSpecModel } : {}),
7304
- ...(compactionParams !== undefined ? { params: compactionParams } : {}),
9405
+ ...(args.bus !== undefined ? { bus: args.bus } : {}),
9406
+ ...(args.compactionSpecModel !== undefined ? { specModel: args.compactionSpecModel } : {}),
9407
+ ...(args.compactionParams !== undefined ? { params: args.compactionParams } : {}),
7305
9408
  });
9409
+ const [marker, , final] = after;
9410
+ if (marker !== undefined)
9411
+ markSynthetic(marker);
9412
+ if (final !== undefined && final !== plan.kept)
9413
+ markSynthetic(final);
9414
+ return after;
7306
9415
  }