@yahyahammad/venastine 0.2.0 → 0.3.8

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.
Files changed (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
package/core/loop.py CHANGED
@@ -27,27 +27,48 @@ budget-truncated responses.
27
27
  """
28
28
 
29
29
  import logging
30
+ import queue
31
+ import threading
32
+
33
+ # §47 slice 8 (NA10). Threads rather than asyncio: `_run` is a synchronous
34
+ # generator and everything under it is blocking I/O, so a bounded pool is
35
+ # the change that fits what is already here. `copy_context` is what makes
36
+ # a submitted call carry the parent span batch 67 put on a ContextVar.
37
+ from concurrent.futures import ThreadPoolExecutor
38
+ from contextlib import nullcontext
39
+ from contextvars import copy_context
40
+ from dataclasses import dataclass, field
41
+ from datetime import UTC
30
42
  from typing import Optional
31
43
  from uuid import UUID
32
44
 
33
45
  import config
34
46
  import prompts.system_prompts as system_prompts
47
+ from core import agent_activity, interaction, provider_errors
48
+ from core.cancel import is_cancelled
35
49
  from core.client import (
36
- api_initialization, call_model_stream, context_window_for, effort_for,
37
50
  ModelResponse,
51
+ accepts_images,
52
+ api_initialization,
53
+ call_model_stream,
54
+ context_window_for,
55
+ effort_for,
38
56
  )
39
57
  from core.events import LoopEvent
40
- from core import interaction
41
58
  from core.memory import ConversationMemory
59
+ from safety.policy_enforcement import redact_diagnostic_text
60
+
42
61
  # §27 (T1). The loop is where a thread's kind is DECIDED -- it knows which
43
62
  # of its three entry points is running -- and storage.create_thread is
44
63
  # where it is stored. Nothing in between learns what a kind means.
45
64
  from storage import (
46
- THREAD_KIND_CHAT, THREAD_KIND_RESEARCH_PASS, THREAD_KIND_SUBAGENT,
65
+ THREAD_KIND_CHAT,
66
+ THREAD_KIND_RESEARCH_PASS,
67
+ THREAD_KIND_SUBAGENT,
47
68
  )
48
69
  from tools.base import GRANT_NEVER
49
- from tools.context import ToolContext, RunInfo
50
- from tools.registry import registry, ToolCallDenied
70
+ from tools.context import RunInfo, ToolContext
71
+ from tools.registry import ToolCallDenied, registry
51
72
 
52
73
  logger = logging.getLogger(__name__)
53
74
 
@@ -74,6 +95,25 @@ DEFAULT_PROVIDER = "ANTHROPIC"
74
95
  # logged -- the quiet invisibility this notice exists to prevent.
75
96
  _headless_notices_shown: set = set()
76
97
 
98
+ # ROADMAP_v3 §81 (IM6), on the headless notice's terms: a tool the user
99
+ # enabled and this run leaves out because no image could reach the model is
100
+ # named once, deduplicated on (provider, thread kind, hidden set) -- the three
101
+ # things the answer depends on, so a later run that differs in any of them
102
+ # still hears about its own.
103
+ _image_notices_shown: set = set()
104
+
105
+
106
+ def _images_deliverable(provider_name: str, memory) -> bool:
107
+ """Whether an image in a tool result can reach the model in this run
108
+ (IM6): the provider takes images, and the thread is not a research
109
+ pass. A property of WHAT THE THREAD IS, for
110
+ `_derived_compaction_mode`'s reason: a pass re-entered by a JSON retry
111
+ or the reviewer is still a pass. Its sources, claims and grounding are
112
+ all text, so a pass is never offered an image tool (§81 leaves the
113
+ pipeline out of scope)."""
114
+ kind = getattr(memory, "kind", THREAD_KIND_CHAT)
115
+ return kind != THREAD_KIND_RESEARCH_PASS and accepts_images(provider_name)
116
+
77
117
 
78
118
  def with_goal(system_prompt: str, memory: ConversationMemory) -> str:
79
119
  """Append a thread's persistent objective (§18 goal mode) to a system
@@ -86,6 +126,19 @@ def with_goal(system_prompt: str, memory: ConversationMemory) -> str:
86
126
  return f"{system_prompt}\n\n## Persistent objective\n{goal}"
87
127
 
88
128
 
129
+ def with_persona(system_prompt: str, model: str, provider_name: str) -> str:
130
+ """Append the live chat identity (ROADMAP_v3 §58, PR1-PR4).
131
+
132
+ Callers resolve agent overrides first. Kept outside with_catalogs so
133
+ research passes, the compactor and the reviewer retain their own
134
+ task-specific prompts.
135
+ """
136
+ return (
137
+ f"{system_prompt}\n\nYou are running in Venastine Research Harness, "
138
+ "a tool-using assistant with a separate multi-pass research mode. "
139
+ f"Your current model is {model} from {provider_name}.")
140
+
141
+
89
142
  def with_todos(system_prompt: str, memory: ConversationMemory) -> str:
90
143
  """Append §23's todo list to a prompt. No-op when the thread has none.
91
144
 
@@ -97,9 +150,9 @@ def with_todos(system_prompt: str, memory: ConversationMemory) -> str:
97
150
  function feeds pass_prompt(), so a checklist written in a chat session
98
151
  would land in all ten passes of a research run the user started
99
152
  separately -- §19's K6, FOURTH instance, after §21b's memories (M13) and
100
- §21c's refs (M19). Four copies of one warning is why the convergence of
101
- these four functions is now a recorded deferral rather than a docstring
102
- aside (J11).
153
+ §21c's refs (M19). Four copies of one warning made the convergence a
154
+ recorded deferral (J11); since batch 227 every tier is appended by
155
+ session_tiers, and SESSION_TIERS is the list the boundary test pins.
103
156
 
104
157
  THE MODEL IS TOLD IT OWNS THIS. Unlike a memory or a reference, which
105
158
  are context the model reads, the todo list is state the model WRITES --
@@ -127,11 +180,10 @@ def with_memories(system_prompt: str, agent=None) -> str:
127
180
  """Append §21b's durable-memory tier to a prompt. No-op when this run
128
181
  is opted out or nothing is in scope.
129
182
 
130
- Beside with_goal for the same reason: both shells assemble a plain-chat
131
- prompt themselves, so a single named function is what stops the CLI and
132
- the TUI drifting apart. §23's response channel is where all three of
133
- these (goal, skills, memories) should eventually converge into one
134
- assembly point rather than three parallel ones.
183
+ Beside with_goal for the same reason: a single named function is what
184
+ stops the CLI and the TUI drifting apart. Both reach it through
185
+ session_tiers now (batch 227), which applies it only when no agent
186
+ built the prompt -- an agent's memories arrive in system_prompt_for().
135
187
 
136
188
  MUST NOT move inside prompts.system_prompts.with_catalogs() -- that
137
189
  feeds pass_prompt(), so memories would land in all ten research passes.
@@ -198,6 +250,155 @@ def with_refs(system_prompt: str, memory: ConversationMemory) -> str:
198
250
  return f"{system_prompt}\n\n" + "\n".join(lines)
199
251
 
200
252
 
253
+ def with_file_mentions(system_prompt: str, memory: ConversationMemory, *,
254
+ text: str | None = None) -> str:
255
+ """§54 AT6/AT7: names from this user turn, never file contents.
256
+
257
+ Do not move into with_catalogs: research passes and internal tasks do
258
+ not inherit chat mentions. Reading still goes through the normal tool
259
+ permissions, including paths outside the file-tool workspace.
260
+ """
261
+ from core import config_loader
262
+ from core.file_mentions import mentions
263
+
264
+ root = config_loader.get_project_path()
265
+ if not root:
266
+ return system_prompt
267
+ if text is None:
268
+ latest = next((row for row in reversed(memory.messages)
269
+ if row.get("role") == "user" and not row.get("harness")), {})
270
+ text = latest.get("content", "")
271
+ paths = list(dict.fromkeys(item.path for item in mentions(text)))
272
+ if not paths:
273
+ return system_prompt
274
+ import json
275
+
276
+ fragment = (
277
+ "## File mentions in the current user turn\n\n"
278
+ "The user named these paths relative to project root " + json.dumps(root) + ". "
279
+ "Resolve them against that root when calling file tools; the tools' workspace may differ. "
280
+ "Read the named files with your tools as needed for the request; their contents "
281
+ "have NOT been loaded. A trailing / names a folder: inspect it as needed, "
282
+ "without assuming its files were included. Paths may have been deleted; "
283
+ "report a missing path rather than guessing its contents. These names grant "
284
+ "no additional file access; normal tool permissions and approvals apply.\n"
285
+ + "\n".join("- " + json.dumps(path, ensure_ascii=False) for path in paths))
286
+ return f"{system_prompt}\n\n{fragment}"
287
+
288
+
289
+ #: The tiers a conversation turn appends after its base prompt, in the
290
+ #: order `session_tiers` appends them (#9, J11, A80). Each is thread or
291
+ #: session state, so none may move inside
292
+ #: prompts.system_prompts.with_catalogs(), which feeds pass_prompt(): §19's
293
+ #: K6. The BASE is not a tier -- the persona and the catalogs, and for an
294
+ #: agent its body and the project hub, which system_prompt_for() composes.
295
+ #: tests/test_prompt_tier_boundary.py keeps a canary for every name here.
296
+ SESSION_TIERS = ("goal", "memories", "refs", "todos", "file_mentions",
297
+ "skill_bodies")
298
+
299
+
300
+ def session_tiers(system_prompt: str, memory: ConversationMemory, *,
301
+ agent_built: bool, mentions: bool = True,
302
+ mention_text: str | None = None, active_skills=()) -> str:
303
+ """Every session tier, in SESSION_TIERS' order: the ONE assembly a
304
+ conversation prompt takes, in either shell (#9, J11, A80).
305
+
306
+ Three call sites assembled this by hand -- a loop turn, a TUI turn and
307
+ the TUI's one-shot -- in the same order, with the memories guard
308
+ spelled three ways. They call this now, and the guard is one argument.
309
+
310
+ `agent_built` IS THE LOAD-BEARING DIFFERENCE, and the reason this takes
311
+ a flag rather than making every tier conditional alike. An agent's
312
+ prompt got its memories inside system_prompt_for() (§21b, M13), so
313
+ appending them here would duplicate them. Refs, the checklist and the
314
+ goal are thread state, not an agent's opt-in, so an agent-built prompt
315
+ needs them too, and system_prompt_for() has no memory to read them
316
+ from (§21c, M19). Making them conditional "like the line above" is the
317
+ edit that looks right and drops every attached reference.
318
+
319
+ `mentions` is off for an internal compaction or review turn: its
320
+ source material is not a person's file-mention request (§54 AT7).
321
+ `mention_text` is the one-shot's message, which is not written to the
322
+ thread until its worker runs.
323
+
324
+ Active skill bodies go LAST on purpose (§19 K1): an activated skill is
325
+ the most specific instruction the user has given, and should read as
326
+ governing what precedes it. The CLI's arrive through
327
+ `run_agent_conversation` and `wake_conversation` since ROADMAP_v3 §89.
328
+ """
329
+ from skills.manager import manager as skills
330
+
331
+ prompt = with_goal(system_prompt, memory)
332
+ if not agent_built:
333
+ prompt = with_memories(prompt)
334
+ prompt = with_refs(prompt, memory)
335
+ prompt = with_todos(prompt, memory)
336
+ if mentions:
337
+ prompt = with_file_mentions(prompt, memory, text=mention_text)
338
+ fragment = skills.prompt_fragment(list(active_skills or ()))
339
+ return f"{prompt}\n\n{fragment}" if fragment else prompt
340
+
341
+
342
+ @dataclass(frozen=True)
343
+ class AgentTurn:
344
+ """What a session's active agent makes of one conversation turn."""
345
+
346
+ model: str
347
+ provider_name: str
348
+ context: Optional[ToolContext]
349
+ # None runs the default prompt, which the loop builds itself.
350
+ system_prompt: Optional[str]
351
+ max_steps: int
352
+
353
+
354
+ def agent_turn(agent, model: str, provider_name: str, active_skills=(), *,
355
+ callable_only: bool = False, granted=None,
356
+ one_shot: bool = False) -> AgentTurn:
357
+ """§18's session-scoped agent, applied to one turn, for either shell.
358
+
359
+ An active agent supplies the system prompt, the ToolContext, and
360
+ model/provider/max_steps overrides; with none active the turn is the
361
+ default harness run (base + catalogs, built by the loop). The session
362
+ tiers are NOT added here -- `_conversation_prompt` adds them to
363
+ whichever prompt runs, which is what keeps a wake turn's prompt the
364
+ same as the turn it continues.
365
+
366
+ ONE COPY (ROADMAP_v3 §89). The TUI's chat turn built this inline, and
367
+ the CLI's `/agent` needs the same answer: an agent that pins a model
368
+ in one shell and not the other is two agents with one name.
369
+
370
+ `callable_only` / `granted` are `advertisement_facts`' (#68), so an
371
+ unattended CLI turn under an agent does not advertise gated tools it
372
+ cannot call -- the TUI always has a channel and passes neither.
373
+
374
+ `one_shot` is §18's /grill-me: ONE turn in the session's thread under
375
+ the agent's prompt, and nothing else of the agent's -- the session's
376
+ model and provider, no ToolContext, the default step budget. That is
377
+ the TUI's `run_one_shot` assembly, kept as it was and now shared.
378
+ """
379
+ if agent is None:
380
+ return AgentTurn(model, provider_name, None, None,
381
+ config.MAX_ITERATIONS)
382
+ from agents.manager import manager
383
+
384
+ if one_shot:
385
+ prompt = manager.system_prompt_for(
386
+ agent, with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
387
+ list(active_skills or ()),
388
+ callable_only=callable_only, granted=granted)
389
+ return AgentTurn(model, provider_name, None, prompt,
390
+ config.MAX_ITERATIONS)
391
+ context = manager.active_context(agent)
392
+ model = agent.model or model
393
+ provider_name = agent.provider or provider_name
394
+ prompt = manager.system_prompt_for(
395
+ agent, with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
396
+ list(active_skills or ()), context=context,
397
+ callable_only=callable_only, granted=granted)
398
+ return AgentTurn(model, provider_name, context, prompt,
399
+ agent.max_steps or config.MAX_ITERATIONS)
400
+
401
+
201
402
  def attach_ref(memory: ConversationMemory, thread_id, summary: str,
202
403
  label: str = "") -> tuple:
203
404
  """Attach one thread's summary to `memory`'s thread. Returns (ok, message).
@@ -217,7 +418,7 @@ def attach_ref(memory: ConversationMemory, thread_id, summary: str,
217
418
  about the same source, and two entries for one thread would spend the cap
218
419
  on a duplicate.
219
420
  """
220
- from datetime import datetime, timezone
421
+ from datetime import datetime
221
422
 
222
423
  refs = [dict(r) for r in (memory.extra.get("refs") or [])]
223
424
  key = str(thread_id)
@@ -232,7 +433,7 @@ def attach_ref(memory: ConversationMemory, thread_id, summary: str,
232
433
  "thread_id": key,
233
434
  "summary": summary,
234
435
  "label": label,
235
- "attached_at": datetime.now(timezone.utc).isoformat(),
436
+ "attached_at": datetime.now(UTC).isoformat(),
236
437
  }
237
438
  if existing is not None:
238
439
  refs[refs.index(existing)] = entry
@@ -388,7 +589,31 @@ def _obtain_approval(response_channel, tool_name: str, params: dict,
388
589
  kind = registry.request_kind(tool_name)
389
590
  payload = {"tool_name": tool_name, "params": params,
390
591
  "rationale": rationale, "headline": headline}
592
+ # §47. WHICH run is asking, read off the span that is open rather
593
+ # than threaded through four layers -- the same ContextVar slice 1
594
+ # put the parent link on, asked one question over.
595
+ #
596
+ # None at depth 0, and that is the right SCOPE rather than a gap:
597
+ # the asking run is then the conversation on screen, which needs no
598
+ # label. A nested one does, because its approvals surface on the
599
+ # parent's screen and "Allow shell?" said only which tool.
600
+ #
601
+ # `asking_agent`, NOT `agent`: spawn_subagent's own request_payload
602
+ # carries an `agent` key meaning the agent about to be SPAWNED.
603
+ # Two different agents, one key, and the sign-off screen would
604
+ # have named the wrong one.
391
605
  payload.update(request_payload or {})
606
+ # AFTER the tool's own payload, deliberately, and this is the half
607
+ # that took a mutation to notice. Written before it, a tool
608
+ # declaring `asking_agent` in its request_payload would silently
609
+ # replace this -- an agent-supplied claim overwriting a harness
610
+ # fact, which is the exact inversion §42's RA6 orders the modal to
611
+ # prevent. Nothing declares that key today; the point is that
612
+ # nothing CAN.
613
+ asking = agent_activity.current()
614
+ if asking is not None:
615
+ payload["asking_agent"] = asking.name
616
+ payload["asking_depth"] = asking.depth
392
617
  answer = interaction.ask(response_channel, interaction.Request(
393
618
  kind=kind, payload=payload, notice=notice))
394
619
  if kind == interaction.SUBAGENT_SIGNOFF:
@@ -576,7 +801,7 @@ def _maybe_compact(memory, model, provider_name, notices, mode,
576
801
  yield LoopEvent(notice=notices[-1])
577
802
 
578
803
 
579
- def run_to_completion(gen) -> ModelResponse:
804
+ def run_to_completion(gen, observe=None) -> ModelResponse:
580
805
  """Consumes a _run() generator fully, discarding intermediate events,
581
806
  and returns the final ModelResponse — this is what keeps
582
807
  run_agent_conversation() and continue_conversation(), the two public
@@ -587,9 +812,20 @@ def run_to_completion(gen) -> ModelResponse:
587
812
  its own value -- stream_deep_research_mode(), whose response carries
588
813
  `thread_id` attached after the loop finished -- needs the other
589
814
  question asked, and `tests/conftest.drain` is where that lives now
590
- that the pass wrapper is gone."""
815
+ that the pass wrapper is gone.
816
+
817
+ `observe` (ROADMAP_v3 §86, A81) is handed every event as it is drawn,
818
+ the terminal one included, so a caller that wants the answer
819
+ synchronously can still draw the turn while it runs. The CLI is that
820
+ caller: it prints each step as it finishes, the way the replay of the
821
+ thread will. Discarding stays the default, and nothing here protects
822
+ the turn from the observer -- one that raises abandons the generator
823
+ exactly as an exception in any consumer would, so the observer is the
824
+ one that must not."""
591
825
  final = None
592
826
  for event in gen:
827
+ if observe is not None:
828
+ observe(event)
593
829
  if event.final_response is not None:
594
830
  final = event.final_response
595
831
  if final is None:
@@ -616,10 +852,844 @@ def _resolve_spend_cap(max_total_tokens) -> Optional[int]:
616
852
  return max_total_tokens
617
853
 
618
854
 
855
+
856
+ @dataclass
857
+ class _CallOutcome:
858
+ """What deciding and dispatching ONE tool call produced (§47 slice 8).
859
+
860
+ Returned rather than written straight into the turn's own lists,
861
+ because NA11 orders a parallel batch's effects by the MODEL'S call
862
+ order and a batch finishes in whatever order it finishes. So a call
863
+ collects what it would have appended, and `_settle_one` appends it at
864
+ the call's turn. For a lone sequential call that turn is immediately,
865
+ which is what keeps the single-call path byte-identical.
866
+
867
+ `result` is what the model is told. `granted` is §25's pre-authorized
868
+ call record and `notices` are §23's shell-facing lines, each a list
869
+ because a call contributes zero or one of the first and zero or more
870
+ of the second.
871
+ """
872
+
873
+ result: object
874
+ granted: list = field(default_factory=list)
875
+ notices: list = field(default_factory=list)
876
+
877
+
878
+ #: NA9's gate for a call with no siblings. A lone call cannot contend with
879
+ #: anything, so it takes no lock -- which is what makes "the sequential
880
+ #: path is unchanged" a structural claim rather than a measured one.
881
+ _NO_GATE = nullcontext()
882
+
883
+ #: NA12's second lock, and it guards a WINDOW rather than an object.
884
+ #:
885
+ #: §23's sign-off memo is a check-then-act: `recall_signoff` says nobody
886
+ #: has answered about this subject, the human is asked, `remember_signoff`
887
+ #: records the answer. Sequentially that is why three spawns of one agent
888
+ #: ask ONCE. Concurrently all three recall before any remembers, and the
889
+ #: user is asked three times about the same agent -- a regression in the
890
+ #: number of questions, which is the thing §25 R11 and §23 J8 are both
891
+ #: about.
892
+ #:
893
+ #: Guarding the dict instead would not close it: no single mutation is
894
+ #: racy, the WINDOW between the read and the write is. Module-level rather
895
+ #: than per-run, because the runs it serialises are siblings in different
896
+ #: frames with no shared object between them but this one.
897
+ #:
898
+ #: RELEASED BEFORE dispatch, always. That is what keeps it a plain Lock: a
899
+ #: child's own gate acquisitions all happen inside its dispatch, by which
900
+ #: time its parent has let go, so nothing re-enters. It is also the outer
901
+ #: of this project's two ask-side locks -- gate, then
902
+ #: core.interaction's -- and the order is never the other way, because
903
+ #: nothing holding the interaction lock reaches back into a gate.
904
+ _GATE_LOCK = threading.Lock()
905
+
906
+
907
+ def _parallel_groups(calls) -> list:
908
+ """Partition one response's calls into consecutive runs (NA9).
909
+
910
+ A group is either several calls whose ToolSpec declares `parallel`, or
911
+ exactly one call of anything else. CONSECUTIVE, and that is the
912
+ decision rather than an implementation detail: NA9 keeps every
913
+ non-parallel call in its original position, so two spawns either side
914
+ of a `shell` cannot be grouped without moving the shell relative to
915
+ them.
916
+
917
+ Asked of the registry, never matched by name, so this file stays free
918
+ of the knowledge that spawn_subagent is the special one -- the same
919
+ trade `grant_scope`, `request_kind` and `opens_thread` already make.
920
+ """
921
+ groups: list = []
922
+ for call in calls:
923
+ # `groups[-1][-1]` rather than a flag, so the question asked is
924
+ # "may this join what is already open" -- and a group is never
925
+ # empty, so there is no length to check.
926
+ if (registry.parallel(call.name)
927
+ and groups
928
+ and registry.parallel(groups[-1][-1].name)):
929
+ groups[-1].append(call)
930
+ else:
931
+ groups.append([call])
932
+ return groups
933
+
934
+
935
+
936
+ def _dispatch_one(call, *, context, run_info, response_channel, memory,
937
+ activity, cancel=None, gate=_NO_GATE):
938
+ """Decide, ask about and dispatch ONE tool call.
939
+
940
+ A GENERATOR that yields the call's own narration -- the permission
941
+ request and any approval notice -- and RETURNS a `_CallOutcome`. Two
942
+ drivers share it and that is the point of the shape: `_run` does
943
+ `yield from` for a lone call, and `_dispatch_parallel`'s worker steps
944
+ it by hand and pushes each event onto a conduit. One copy of the
945
+ decision, so there is still exactly one place that decides whether a
946
+ call is authorized and exactly one call to `registry.dispatch`.
947
+
948
+ `gate` is NA12's window lock, supplied only when this call has
949
+ siblings. See `_GATE_LOCK`.
950
+
951
+ THE AUTHORIZATION IS THIS FUNCTION'S LOCAL, which is strictly stronger
952
+ than the loop-body local it replaces. `authorized_call` used to be
953
+ correct because of WHERE it was declared -- one indent out and it
954
+ covered every later call in the turn -- and the id, rather than a
955
+ bool, is what made that mistake fail closed instead of open. A
956
+ function whose whole scope is one call cannot express the mistake at
957
+ all: there is no enclosing iteration to hoist out of. The id stays
958
+ anyway, because it is also what tells `dispatch()` which call the
959
+ loop answered, and because a fail-closed shape is worth keeping when
960
+ it costs nothing.
961
+ """
962
+ granted: list = []
963
+ collected: list = []
964
+
965
+ # Single source of truth with dispatch(): approval_needed()
966
+ # ORs the tool's own path/command-dependent approval_check
967
+ # with the config/context requirement (§15). Both callers
968
+ # go through it so they cannot diverge — a path-dependent
969
+ # tool must yield permission_request so the TUI user can
970
+ # approve, not be silently denied by one check while the
971
+ # other reports no approval needed.
972
+ #
973
+ # There is no separate allowed_tools membership test here
974
+ # any more: dispatch() calls is_tool_allowed(name, context),
975
+ # which raises ToolCallDenied with a message distinguishing
976
+ # a context restriction from a global policy denial.
977
+ needs_approval = registry.approval_needed(
978
+ call.name, call.input, context)
979
+ # Reachability before approval. Asking first meant a
980
+ # context-excluded tool prompted the user, who clicked
981
+ # Allow, and was then denied anyway -- and headless, it
982
+ # reported "requires approval and was not given", telling
983
+ # the model to retry with approval when the actionable
984
+ # answer is "not available in this context". dispatch()
985
+ # still enforces the denial; this only stops asking a
986
+ # question whose answer cannot matter.
987
+ if needs_approval and not registry.is_allowed(call.name, context):
988
+ needs_approval = False
989
+ # §32 A7 (#70): the same rule for a refusal only the
990
+ # TOOL can see. spawn_subagent's unknown-agent and
991
+ # depth-limit checks lived inside run(), so both
992
+ # prompted first and errored second -- and for an
993
+ # unknown name the question had an empty notice and an
994
+ # empty candidate list, i.e. nothing to tick. The
995
+ # call is refused by dispatch with the tool's own
996
+ # reason; this only stops ASKING first. It also keeps
997
+ # J8's memo from being keyed on
998
+ # (spawn_subagent, None) -- a subject of None is the
999
+ # absence of the very thing the key exists to
1000
+ # distinguish.
1001
+ if needs_approval and registry.refusal_reason(
1002
+ call.name, call.input, context):
1003
+ needs_approval = False
1004
+ # §33 W3 (#37): the same rule for a call whose arguments
1005
+ # never parsed. Approving it could not make it runnable,
1006
+ # so the question has no answer that changes anything --
1007
+ # and headless it would report "requires approval and was
1008
+ # not given", which is A7's exact wrong-cause failure.
1009
+ if needs_approval and call.parse_error is not None:
1010
+ needs_approval = False
1011
+ # §18 sign-off (S1), narrowed by §25 (R2): a tool whose
1012
+ # grant_scope is "run" is asked about once per run, not
1013
+ # once per call. The loop names no tool -- it asks the
1014
+ # registry, the same way it asks whether approval is
1015
+ # needed at all.
1016
+ #
1017
+ # THREE conditions, and the last two are the §25 change:
1018
+ #
1019
+ # registry.grantable -- a tool deciding approval from its
1020
+ # PARAMS was never consented to by name. Before this,
1021
+ # a signed-off subagent could run any shell command for
1022
+ # the rest of the turn on the strength of one prompt
1023
+ # that said "shell". Re-checked here rather than
1024
+ # trusted from the set, so a stale or hand-built grant
1025
+ # cannot widen anything.
1026
+ #
1027
+ # grant_budget.take() -- pre-flight authorization trades
1028
+ # a per-call decision for one up-front decision, and
1029
+ # gives up the natural bound on how many times the
1030
+ # tool runs. Exhaustion falls back to ASKING, not to
1031
+ # failing: supervised runs continue, headless ones deny
1032
+ # exactly as they would for any gated tool.
1033
+ #
1034
+ # §23 AC1b: the memo is keyed by (tool, SUBJECT), not by
1035
+ # tool name alone. A subagent sign-off answers about one
1036
+ # agent's candidate list, so reusing it for a different
1037
+ # agent would grant a set nobody was shown -- which is
1038
+ # what the name-only version did: approving a spawn of `a`
1039
+ # silently covered a later spawn of `b` in the same turn.
1040
+ # Tools with no subject (every other one) memo under None
1041
+ # and behave exactly as before.
1042
+ # Batch 60. THIS CALL'S authorization decision, and the
1043
+ # error that stands in for it.
1044
+ #
1045
+ # THE ID, NOT A BOOLEAN, and that is the whole point of the
1046
+ # shape. `authorized` began as a bool whose correctness
1047
+ # rested on WHERE it was declared -- one indent level in and
1048
+ # it covers one call, one level out and it covers every
1049
+ # later call in the turn, which is the exact widening §25
1050
+ # R11 refuses to make even for the one tool whose grant
1051
+ # scope IS the run. That version was measured: hoisting it
1052
+ # out of the per-call loop survived the entire suite, because
1053
+ # no path currently reaches dispatch with a stale flag that
1054
+ # changes anything. Correct, and undefended.
1055
+ #
1056
+ # §47 SLICE 8 MADE THE SCOPE STRUCTURAL. The per-call body is
1057
+ # this function now, so there is no enclosing iteration left
1058
+ # to hoist out of -- the widening the paragraph above defends
1059
+ # against can no longer be WRITTEN here, rather than being
1060
+ # merely absent. That is why the AST guard in
1061
+ # tests/test_grants.py moved with the body instead of being
1062
+ # deleted: what it pins is now "one call per frame, and the
1063
+ # frame is what dispatch is told about".
1064
+ #
1065
+ # A call id cannot be hoisted into a lie, and the id stays for
1066
+ # that reason plus one more: it is also how dispatch() learns
1067
+ # WHICH call the loop answered. Handed a stale one, the
1068
+ # comparison at the dispatch site fails and the call is DENIED
1069
+ # -- the mistake fails closed instead of failing open. It rests
1070
+ # on ids being distinct within a response, which is not a new
1071
+ # assumption: add_tool_result pairs every tool_result to its
1072
+ # tool_use by that same id (M4/D20), and a thread whose ids
1073
+ # collide is already unresumable.
1074
+ #
1075
+ # Set in exactly two places -- the memo/grant hit below and
1076
+ # the fresh approval further down -- and read in exactly
1077
+ # one, the single dispatch() call at the end of this block.
1078
+ authorized_call = None
1079
+ denial = None
1080
+ request_payload = registry.request_payload(
1081
+ call.name, call.input, context)
1082
+ subject = request_payload.get("subject")
1083
+ # NA12's window opens HERE and closes before dispatch. Everything
1084
+ # inside is the sign-off's check-then-act: what has already been
1085
+ # answered about this subject, the question if nothing has, and the
1086
+ # record of the answer. A sibling that arrives mid-window waits, and
1087
+ # then finds the memo -- which is what keeps three spawns of one
1088
+ # agent at ONE question, exactly as they were sequentially.
1089
+ #
1090
+ # `gate` is a no-op for a lone call, so this costs the sequential
1091
+ # path nothing and cannot be held across a suspension there. On the
1092
+ # parallel path the frame that yields is the DRIVER, not this
1093
+ # generator: the worker steps it and pushes, so a permission request
1094
+ # still reaches the transcript before the modal it announces, with
1095
+ # no lock held across anybody's `yield`.
1096
+ with gate:
1097
+ remembered, signoff = run_info.recall_signoff(
1098
+ call.name, subject)
1099
+ # grant_policy on a NAME-LEVEL grant only -- R13's literal
1100
+ # claim is that approving the NAME never carries the
1101
+ # authority for a GRANT_NEVER tool, on either path, and
1102
+ # until now no path enforced it. Batch 6 declared the
1103
+ # policy and taught the two functions that decide what
1104
+ # may be OFFERED to read it; this is the reader that
1105
+ # decides whether a grant already in hand APPLIES.
1106
+ # `spawn_subagent` was covered only because R14's
1107
+ # subject condition happens to catch it; `remember`
1108
+ # carries no subject, so a grant naming it dispatched a
1109
+ # durable cross-session write with no prompt -- M17's
1110
+ # scenario through the one door R13 left unlocked.
1111
+ #
1112
+ # IT MUST NOT REACH THE SIGN-OFF MEMO, and that is not a
1113
+ # nicety: `spawn_subagent` is GRANT_NEVER, so testing
1114
+ # the policy unconditionally here stops §23's memo
1115
+ # applying and the same agent is asked about twice in
1116
+ # one turn. R13 is about what approving a NAME buys; a
1117
+ # memo is an answer somebody gave about this subject,
1118
+ # which J8 and R14 govern instead. recall_signoff
1119
+ # already separates them by what it returns -- the memo
1120
+ # always carries a subset, the grant carries None.
1121
+ answered_by_name = signoff is None
1122
+ if (needs_approval
1123
+ and remembered
1124
+ and registry.grantable(call.name)
1125
+ and not (answered_by_name
1126
+ and registry.grant_policy(call.name)
1127
+ == GRANT_NEVER)
1128
+ and (run_info.grant_budget is None
1129
+ or run_info.grant_budget.take())):
1130
+ needs_approval = False
1131
+ # Batch 60. The half that was missing: the loop
1132
+ # decided this call needs no fresh answer, and until now
1133
+ # it did not tell dispatch(), which re-checks approval on
1134
+ # its own and denied every call this branch let through.
1135
+ # A second spawn of one agent, a subagent calling a tool
1136
+ # it was signed off for, and a --grant-tools name in an
1137
+ # unattended run were all refused with "requires approval
1138
+ # and was not given" and no prompt.
1139
+ authorized_call = call.id
1140
+ granted.append(
1141
+ {"tool": call.name, "params": call.input})
1142
+ # §21, and the reason this batch adds a notice at all:
1143
+ # a gated call proceeding with NO modal is the intended
1144
+ # behaviour (§25 R11 -- re-asking about the same tool
1145
+ # seconds later is noise), and it is also exactly what
1146
+ # the bug looked like from the outside. Silence was
1147
+ # indistinguishable from the bug.
1148
+ #
1149
+ # DELIBERATELY NOT in _ONCE_PER_RUN_NOTICES. That list
1150
+ # is for a STANDING CONDITION re-emitted on every step;
1151
+ # this fires only when a call actually reuses an answer,
1152
+ # which is an event -- the same reading that lets a
1153
+ # compaction that HAPPENED repeat once per compaction.
1154
+ # Once per run would go quiet again from the third spawn
1155
+ # onward, which is the silence that started this.
1156
+ #
1157
+ # Two texts, discriminated by `answered_by_name`, which
1158
+ # is already computed above: one sentence cannot honestly
1159
+ # cover both. A memo is something the user answered
1160
+ # minutes ago in this turn; a grant is something they
1161
+ # decided before the run existed, possibly on a command
1162
+ # line, and telling them they "answered earlier" would
1163
+ # describe a moment that never happened.
1164
+ collected.append({
1165
+ "kind": "approval_reused",
1166
+ "text": (
1167
+ "%s is running on the authorization granted "
1168
+ "before this run started." % call.name
1169
+ if answered_by_name else
1170
+ "Reusing your approval for %s, given earlier in "
1171
+ "this turn." % (subject or call.name)),
1172
+ })
1173
+ yield LoopEvent(notice=collected[-1])
1174
+ else:
1175
+ # Not reused: nothing is carried into dispatch unless
1176
+ # this call's own answer supplies it below.
1177
+ signoff = None
1178
+ if needs_approval:
1179
+ notice = registry.approval_notice(
1180
+ call.name, call.input, context)
1181
+ # §42 (RA5). The agent's own stated reason, asked
1182
+ # of the registry so the loop names no key -- the
1183
+ # same way it asks what KIND of question a tool
1184
+ # needs and whether it needs one at all. The VALUE
1185
+ # travels rather than the key, because the two
1186
+ # shells that render it are a Textual screen that
1187
+ # imports nothing from this package and a `print`
1188
+ # in main.py.
1189
+ rationale = registry.rationale_for(
1190
+ call.name, call.input)
1191
+ # §46 (EP2). The SUBJECT of the question, resolved
1192
+ # the same way and travelling the same route: for
1193
+ # `shell` it is the command, and a shell that shows
1194
+ # it must not have to know that. Every other tool
1195
+ # answers None and its prompt is unchanged.
1196
+ headline = registry.headline_for(
1197
+ call.name, call.input)
1198
+ yield LoopEvent(permission_request={
1199
+ "tool_name": call.name, "params": call.input,
1200
+ "notice": notice,
1201
+ "rationale": rationale,
1202
+ "headline": headline,
1203
+ })
1204
+ approved, signoff = _obtain_approval(
1205
+ response_channel, call.name, call.input, notice,
1206
+ request_payload, rationale=rationale,
1207
+ headline=headline)
1208
+ if approved:
1209
+ authorized_call = call.id
1210
+ # §25 R11: run-scope is a shortcut for a chat turn,
1211
+ # where re-asking about the same tool seconds later
1212
+ # is noise. A provider that declines it is saying
1213
+ # its whole purpose is per-call supervision --
1214
+ # attended mode -- and one yes must not silently
1215
+ # cover later calls there.
1216
+ #
1217
+ # This is ALSO the only thing that carries an answer
1218
+ # between calls in a turn, and it is asked of the
1219
+ # registry rather than assumed: `spawn_subagent` is
1220
+ # the sole tool declaring grant_scope "run", so
1221
+ # `shell`, `write` and `edit` are re-asked per call
1222
+ # however many times one turn calls them.
1223
+ if (registry.grant_scope(call.name) == "run"
1224
+ and (response_channel is None
1225
+ or response_channel.honour_run_scope)):
1226
+ run_info.remember_signoff(
1227
+ call.name, subject, signoff)
1228
+ else:
1229
+ denial = _denial_reason(
1230
+ call.name, response_channel, context)
1231
+ elif call.parse_error is not None:
1232
+ # §33 W1 (#37). The loop is the only layer that can
1233
+ # see this: dispatch() takes (name, params, context)
1234
+ # and the failure is a fact about the wire, not about
1235
+ # the params -- {} is a perfectly good empty dict by
1236
+ # the time it gets there.
1237
+ #
1238
+ # RETURNED as the tool's result, not raised, for
1239
+ # A10's reason: the model is told its arguments did not
1240
+ # arrive and can reissue the call, which is the whole
1241
+ # difference between losing one step and losing a
1242
+ # ten-pass run.
1243
+ denial = call.parse_error
1244
+
1245
+ # ONE dispatch call site (batch 60). There were two,
1246
+ # identical but for the two arguments that carry
1247
+ # authorization, and the one reached by an already-answered
1248
+ # call was the one that omitted them -- so every call this
1249
+ # loop decided was authorized got denied by dispatch's own
1250
+ # re-check. Two sites that must agree is the defect; one
1251
+ # site is the fix, and no future edit can teach them to
1252
+ # disagree again.
1253
+ #
1254
+ # dispatch() STILL RE-CHECKS, and must: it is a public
1255
+ # entry point and the fail-closed backstop. What changed is
1256
+ # that the loop now answers it.
1257
+ #
1258
+ # The callback is CONDITIONAL, and the condition is an
1259
+ # identity check rather than a truth test: this call, not
1260
+ # some call. See the declaration above for why the id and
1261
+ # not a flag.
1262
+ #
1263
+ # DELETING the condition -- `lambda n, p: True` outright --
1264
+ # is the one mutation here that no behaviour can catch, and
1265
+ # it is caught in tests/test_grants.py by reading this
1266
+ # source instead. Nothing can reach this line gated and
1267
+ # un-authorized today, because the three other reasons
1268
+ # `needs_approval` is turned off above are each
1269
+ # short-circuited INSIDE dispatch before its gate
1270
+ # (is_allowed raises, refusal_check returns, and a
1271
+ # parse_error never gets here at all). A fourth reason added
1272
+ # later would otherwise silently become "approve
1273
+ # everything", with every test still green.
1274
+ #
1275
+ # `signoff` needs no condition -- the memo branch above nulls
1276
+ # it on every path that is not a hit, so it is already None
1277
+ # everywhere it should be.
1278
+ if denial is not None:
1279
+ result = {"error": denial}
1280
+ else:
1281
+ try:
1282
+ result = registry.dispatch(
1283
+ call.name, call.input, context=context,
1284
+ # §47. The id the parent's MessageLog row
1285
+ # already stores for this call, so a child
1286
+ # thread can record which LINE made it --
1287
+ # one turn can spawn three, and a name is
1288
+ # not enough to tell them apart.
1289
+ call_id=call.id,
1290
+ approval_callback=(
1291
+ (lambda n, p: True)
1292
+ if authorized_call == call.id else None),
1293
+ parent_run=run_info,
1294
+ response_channel=response_channel,
1295
+ signoff=signoff,
1296
+ memory=memory,
1297
+ activity=activity,
1298
+ # §61 CN7. A child run is this run continuing, so it is
1299
+ # handed the same switch -- the argument that
1300
+ # `response_channel` and `activity` beside it already
1301
+ # make, for the same reason.
1302
+ cancel=cancel,
1303
+ )
1304
+ except ToolCallDenied as e:
1305
+ result = {"error": str(e)}
1306
+ except ValueError:
1307
+ # Batch 147. THE OTHER EXCEPTION dispatch() RAISES ON PURPOSE.
1308
+ #
1309
+ # Its unknown-tool guard is a ValueError and not a
1310
+ # ToolCallDenied, deliberately: the two types separate "you
1311
+ # misnamed it" from "policy blocks you", and that file frames
1312
+ # the first as a caller bug. It is -- but the caller here is a
1313
+ # language model, so the bug arrives the way a model's bugs
1314
+ # arrive: a name it invented, a name whose MCP server went
1315
+ # away between turns while its schemas are still in the
1316
+ # model's context (registry.unregister()), or a name a prompt
1317
+ # catalog advertises and nothing registered.
1318
+ #
1319
+ # Uncontained, that cost the whole turn AND left the thread
1320
+ # unresumable: D20 has already persisted the assistant row
1321
+ # carrying the `tool_use`, nothing writes a `tool_result`, and
1322
+ # M4's pairing is broken with nothing in core/compaction.py or
1323
+ # core/memory.py that repairs it -- `_settle_one`'s own words
1324
+ # for that state are "an unresumable thread". Reported as this
1325
+ # call's error instead, for the reason the parse_error branch
1326
+ # above gives in full: the model is told what went wrong and
1327
+ # can reissue, which is the difference between losing one step
1328
+ # and losing a ten-pass run.
1329
+ #
1330
+ # `is_registered` RATHER THAN THE MESSAGE is what makes this
1331
+ # specific. A bare `except Exception` would stop dispatch()
1332
+ # being the fail-closed backstop it is documented as -- a real
1333
+ # failure in the approval machinery would come back to the
1334
+ # model as a tool error and vanish -- and matching on the text
1335
+ # would be a parser where a token check will do (G2). The
1336
+ # question is asked of the registry, which is the only thing
1337
+ # that knows the answer, and a ValueError for a name that IS
1338
+ # registered re-raises exactly as it did before.
1339
+ #
1340
+ # A re-registration between the raise and this line answers
1341
+ # True and re-raises, i.e. degrades to the behaviour this
1342
+ # replaces. That is the safe direction and it is why the
1343
+ # check is not a cached snapshot.
1344
+ if registry.is_registered(call.name):
1345
+ raise
1346
+ logger.warning(
1347
+ "model called %r, which is not a registered tool; "
1348
+ "reporting that to it as this call's error", call.name)
1349
+ result = {"error": (
1350
+ f"There is no tool named {call.name} in this run, so the "
1351
+ f"call could not be made. Use one of the tools listed in "
1352
+ f"this request.")}
1353
+ # The NAME is the only thing echoed, and it is already in
1354
+ # the thread: D20 persisted the model's own `tool_use` block
1355
+ # before any of this. Nothing of the exception goes back,
1356
+ # which matters here more than it looks: an error result the
1357
+ # LOOP builds -- a denial, a parse error, this -- does not
1358
+ # pass through `check_output_policy`, while every result
1359
+ # dispatch() returns does, including its own error results
1360
+ # (tests/test_tool_failure_containment.py pins that). So this
1361
+ # is one of the few result strings in the system that no
1362
+ # redactor will ever see.
1363
+ return _CallOutcome(
1364
+ result=result, granted=granted, notices=collected)
1365
+
1366
+
1367
+ def _dispatch_parallel(calls, *, context, run_info, response_channel,
1368
+ memory, activity, cancel=None):
1369
+ """Run several calls of one response at once (NA9, NA10, NA15).
1370
+
1371
+ A GENERATOR yielding every worker's narration as it arrives, and
1372
+ RETURNING [(call, _CallOutcome)] in the model's original call order.
1373
+
1374
+ THREADS, NOT ASYNCIO. `_run` is a synchronous generator and everything
1375
+ under it is blocking I/O -- a provider call, a modal a human is
1376
+ looking at, a SQLite write. Converting that to coroutines is a rewrite
1377
+ of every layer; a bounded pool is the change that fits what is already
1378
+ here.
1379
+
1380
+ EVERY FUTURE CARRIES `contextvars.copy_context()`, which is what makes
1381
+ the child's span see its real parent. Batch 67 chose a ContextVar for
1382
+ the parent link over a parameter partly for this: a var is per-context,
1383
+ so a copied context travels with the submitted call, while a plain
1384
+ module global would be wrong the moment two children ran.
1385
+
1386
+ THE CONDUIT IS HOW A WORKER NARRATES, and it is the fifth blocker N8
1387
+ named -- "a synchronous generator with no yield point inside
1388
+ dispatch()". A worker thread cannot yield out of this generator. What
1389
+ it can do is put the event on a queue that THIS frame, which is still
1390
+ inside `_run`'s body and can still yield, drains as the events arrive.
1391
+ So narration stays live: a permission request from one child reaches
1392
+ the transcript while its siblings are still running.
1393
+
1394
+ Note what this does NOT do. It does not forward a CHILD'S events --
1395
+ §18/D6 keeps a child's stream out of its parent, and
1396
+ core/agent_activity.py exists because of it. The events on this queue
1397
+ are the PARENT'S own, about its own tool calls, which it would have
1398
+ yielded itself had it not handed the work to a thread.
1399
+
1400
+ UNBOUNDED QUEUE, deliberately: a worker must never block on the
1401
+ conduit. A bounded one would make a slow consumer able to stall a run,
1402
+ which inverts who is waiting for whom. The bound that matters is on
1403
+ the POOL.
1404
+
1405
+ A worker signals its own end rather than being polled for it, so this
1406
+ drains exactly and never sleeps. If a call hangs, this frame waits
1407
+ forever -- which is what a hanging sequential tool already does, so
1408
+ the shape adds no new way to wedge.
1409
+ """
1410
+ conduit: queue.Queue = queue.Queue()
1411
+ # `[(call, outcome_or_None, exception_or_None)]`, in the order the
1412
+ # futures were submitted, which is the order the MODEL asked (NA11).
1413
+ #
1414
+ # A LIST RATHER THAN A DICT KEYED BY `call.id`, which is what this was
1415
+ # until batch 76's review round. The id is the PROVIDER'S, and
1416
+ # core/client.py's v1-compatible branch defaults a tool-call fragment's
1417
+ # id to "" and fills it only if a delta carries one -- the same branch
1418
+ # that accumulates `function.name` across deltas because some providers
1419
+ # split it, so a provider being sloppy here is the case this code is
1420
+ # written for. Two spawns arriving with one id made a dict hand every
1421
+ # call in the batch the last-finishing worker's outcome: the model told
1422
+ # one child's answer for a different child's call, which is the exact
1423
+ # thing NA11 exists to prevent. Positions cannot collide, so ordering
1424
+ # is now structural rather than a lookup.
1425
+ settled_calls: list = []
1426
+
1427
+ def _work(call):
1428
+ """Drive one call's generator, pushing what it would have yielded."""
1429
+ gen = _dispatch_one(
1430
+ call, context=context, run_info=run_info,
1431
+ response_channel=response_channel, memory=memory,
1432
+ activity=activity, cancel=cancel, gate=_GATE_LOCK)
1433
+ try:
1434
+ while True:
1435
+ conduit.put(("event", next(gen)))
1436
+ except StopIteration as stop:
1437
+ return stop.value
1438
+ finally:
1439
+ # Runs on the return path and on the raising one, so the
1440
+ # drain below always terminates. A worker that died still
1441
+ # reports that it is done.
1442
+ conduit.put(("done", None))
1443
+
1444
+ workers = max(1, min(len(calls), config.SUBAGENT_MAX_PARALLEL))
1445
+ abandoned = False
1446
+ with ThreadPoolExecutor(max_workers=workers,
1447
+ thread_name_prefix="venastine-call") as pool:
1448
+ futures = []
1449
+ for call in calls:
1450
+ futures.append(
1451
+ (call, pool.submit(copy_context().run, _work, call)))
1452
+ outstanding = len(calls)
1453
+ # ABANDONED MID-BATCH, the window #215 names (batch 221). A
1454
+ # consumer that goes away at one of these yields -- the TUI closes
1455
+ # its generator on shutdown -- used to take every finished call's
1456
+ # outcome with it: D20 had written their `tool_use` blocks, the
1457
+ # tools had run, and no row answered them. So the GeneratorExit is
1458
+ # held while the workers finish, which the pool's own exit already
1459
+ # waited for, and every outcome is recorded in the model's order
1460
+ # below before it is raised again. NA11 is untouched: nothing is
1461
+ # recorded out of order, only no longer dropped.
1462
+ try:
1463
+ while outstanding:
1464
+ kind, payload = conduit.get()
1465
+ if kind == "done":
1466
+ outstanding -= 1
1467
+ else:
1468
+ yield payload
1469
+ except GeneratorExit:
1470
+ abandoned = True
1471
+ for call, future in futures:
1472
+ try:
1473
+ settled_calls.append((call, future.result(), None))
1474
+ except Exception as e: # noqa: BLE001 -- NA14, see below
1475
+ settled_calls.append((call, None, e))
1476
+
1477
+ # NA14. A RAISING SIBLING BECOMES ITS OWN RESULT, and this is a
1478
+ # deliberate behaviour change scoped to a parallel batch.
1479
+ #
1480
+ # Sequentially an exception out of a tool leaves `_run` and ends the
1481
+ # turn; §16 AC3 pins that this must not kill the app (`test_tui.py`),
1482
+ # and a lone call keeps exactly that. In a batch it would discard the
1483
+ # finished work of every sibling -- runs that cost a model call each
1484
+ # and whose answers are already in hand -- so the raise is converted
1485
+ # to this call's error result and the turn goes on.
1486
+ #
1487
+ # A BACKSTOP RATHER THAN THE USUAL PATH. `dispatch()` already turns a
1488
+ # handler's exception into an error result, and BOTH exceptions it
1489
+ # raises on purpose -- ToolCallDenied and the unknown-tool ValueError
1490
+ # -- are caught inside `_dispatch_one`. What reaches here is a failure
1491
+ # in the approval machinery itself. Logged with the traceback for
1492
+ # dispatch()'s reason -- a real bug must stay findable -- and reported
1493
+ # to the model in the shape it already understands.
1494
+ #
1495
+ # THIS COMMENT USED TO NAME THE UNKNOWN TOOL, and could not be reached
1496
+ # by it (batch 147): `registry.parallel()` answers False for a name it
1497
+ # does not hold, so `_parallel_groups` always put an unknown call in a
1498
+ # group of ONE, and a group of one takes the sequential branch. The
1499
+ # containment it described was in the wrong function for the failure
1500
+ # it named -- so the failure ended the turn and this backstop never
1501
+ # saw it. Both halves are fixed: `_dispatch_one` contains it for both
1502
+ # drivers, and the sentence above no longer claims a case this cannot
1503
+ # see.
1504
+ ordered = []
1505
+ for call, outcome, failure in settled_calls:
1506
+ if failure is not None:
1507
+ logger.exception(
1508
+ "parallel tool call %s (%s) raised; reporting it as that "
1509
+ "call's error and continuing with its siblings",
1510
+ call.id, call.name, exc_info=failure)
1511
+ ordered.append((call, _CallOutcome(
1512
+ result={"error": "%s failed: %s" % (
1513
+ call.name, failure)})))
1514
+ else:
1515
+ ordered.append((call, outcome))
1516
+ if abandoned:
1517
+ # Recorded, never announced: there is nobody left to announce to,
1518
+ # and a generator that yields after GeneratorExit is a
1519
+ # RuntimeError. A failure to record is logged rather than raised,
1520
+ # so it cannot replace the close the consumer asked for.
1521
+ for call, outcome in ordered:
1522
+ try:
1523
+ _settle_one(call, outcome, memory, [], [])
1524
+ except Exception: # noqa: BLE001 -- see above
1525
+ logger.exception("Could not record %s's result while the "
1526
+ "batch was being closed", call.id)
1527
+ raise GeneratorExit
1528
+ return ordered
1529
+
1530
+
1531
+ def _settle_one(call, outcome, memory, granted_calls, notices) -> list:
1532
+ """Record ONE finished call, at its turn in call order, and return the
1533
+ events that announce it.
1534
+
1535
+ Split out of the per-call body so both drivers reach it identically,
1536
+ and so everything that touches `memory` or the turn's shared lists
1537
+ happens on the generator's own thread in the model's own order (NA11).
1538
+ A reordered turn is a thread that will not resume: `add_tool_result`
1539
+ pairs each result to its `tool_use` by id (M4/D20).
1540
+
1541
+ A FUNCTION, NOT A GENERATOR, since batch 221 (#215). As a generator it
1542
+ yielded between one call's row and the next one's, so a batch closed
1543
+ at its first `tool_result` lost the rows of every call after it, and
1544
+ `_dispatch_parallel` had nothing to record its finished calls with
1545
+ once its own consumer had gone. Returning the events lets the batch
1546
+ record every result before announcing any, and lets the abandoned path
1547
+ record without announcing at all.
1548
+ """
1549
+ granted_calls.extend(outcome.granted)
1550
+ notices.extend(outcome.notices)
1551
+ result = outcome.result
1552
+ events = []
1553
+
1554
+ # §23 slice 2 (J10). A tool may attach a `notice` to its
1555
+ # result for the shell to show; it is forwarded as a
1556
+ # LoopEvent and REMOVED from what the model sees.
1557
+ #
1558
+ # Generic on purpose. The alternative was for the loop to
1559
+ # notice that `todo_write` had just run, which puts a tool
1560
+ # name in this file -- exactly what ToolSpec.grant_scope and
1561
+ # ToolSpec.request_kind exist to avoid. Any later tool that
1562
+ # wants to say something mid-turn gets this route free.
1563
+ #
1564
+ # POPPED, not copied: a notice is plumbing for the shell, and
1565
+ # leaving it in the result would send the TUI panel's trigger
1566
+ # to the model as if it were part of the tool's answer.
1567
+ if isinstance(result, dict) and "notice" in result:
1568
+ notice = result.pop("notice")
1569
+ if isinstance(notice, dict) and notice.get("kind"):
1570
+ events.append(LoopEvent(notice=notice))
1571
+ else:
1572
+ # A malformed notice is a bug in the tool, not a
1573
+ # reason to fail the call -- the result is still
1574
+ # good. Logged rather than raised, and the key is
1575
+ # gone either way so it cannot reach the model.
1576
+ logger.warning(
1577
+ "%s returned a malformed notice; dropping it: %r",
1578
+ call.name, notice)
1579
+
1580
+ # Persist BEFORE emitting (#42). A generator only advances
1581
+ # while someone iterates it, so emitting first made the row
1582
+ # depend on a consumer continuing to read -- and an
1583
+ # abandoned generator left the `tool_use` D20 already wrote
1584
+ # with no matching `tool_result`, which is M4's pairing
1585
+ # broken from the other side and an unresumable thread.
1586
+ # Same rule §22 gives _Progress.checkpoint() for trace
1587
+ # lines. The event carries nothing the persist needs, so
1588
+ # the order is free.
1589
+ memory.add_tool_result(call.id, result)
1590
+ events.append(LoopEvent(tool_result={"id": call.id, "result": result}))
1591
+ return events
1592
+
1593
+
1594
+ def _finish_cancelled(memory, response, *, partial_text, unrun, reason,
1595
+ granted_calls, notices, totals):
1596
+ """Everything a cancelled turn leaves behind, in ONE place (§61 CN3).
1597
+
1598
+ Three sites reach it -- the step boundary, a stream cut part way
1599
+ through, and the gap between two tool groups -- and they differ only
1600
+ in what they have in hand. Writing the terminal event at each would
1601
+ be three chances to forget one of the three things below, and the
1602
+ last of them is what keeps the thread resumable.
1603
+
1604
+ `partial_text` is the accumulated deltas when the stream was cut, and
1605
+ None otherwise. It is the only case that PERSISTS, because it is the
1606
+ only one holding an assistant turn D20 has not already written. Empty
1607
+ text persists nothing: a turn stopped before its first token said
1608
+ nothing, and an empty assistant row is one every later request has to
1609
+ carry.
1610
+
1611
+ `unrun` is every tool call of this response that will not get a
1612
+ result. #42 is the same lesson from the other side -- a `tool_use`
1613
+ persisted with no matching `tool_result` is M4's pairing broken and
1614
+ an UNRESUMABLE thread -- so a cancelled turn answers every call the
1615
+ model made, including the ones it declined to run. The answer is an
1616
+ `error`, which is the shape a denied call already takes.
1617
+
1618
+ CN5: a SYNTHESISED response reports an EMPTY usage dict, not zeros.
1619
+ The provider sends usage with its final message and a cut stream has
1620
+ none, so the honest statement is "not measured" -- and the two stay
1621
+ distinguishable, since `"input_tokens" in usage` is False here and
1622
+ True for a step that genuinely cost nothing. A zero would be the
1623
+ instrument that lies, which batches 118 and 119 each paid for once.
1624
+
1625
+ CANCELLED IS NOT FAILED. Nothing here calls `mark_turn_failed`: the
1626
+ frame above draws exactly that distinction for an abandoned
1627
+ generator, and §60's UH6 records UHP arriving at it independently.
1628
+ """
1629
+ if partial_text is not None:
1630
+ response = ModelResponse(text=partial_text, usage={})
1631
+ if partial_text:
1632
+ memory.add_assistant_message(response)
1633
+ elif response is None:
1634
+ response = ModelResponse(text="", usage={})
1635
+ for call in unrun:
1636
+ result = {"error": reason}
1637
+ memory.add_tool_result(call.id, result)
1638
+ yield LoopEvent(tool_result={"id": call.id, "result": result})
1639
+ response.stop_reason = "cancelled"
1640
+ response.granted_calls = granted_calls
1641
+ response.notices = notices
1642
+ (response.turn_billed_tokens, response.turn_new_tokens,
1643
+ response.turn_output_tokens) = totals
1644
+ yield LoopEvent(final_response=response, stop_reason="cancelled")
1645
+
1646
+
619
1647
  class RunAgentLoop:
620
1648
 
621
1649
  @staticmethod
622
- def _run(
1650
+ def _run(memory: ConversationMemory, *args, **kwargs):
1651
+ """The loop, recording on the thread why a run that raised failed.
1652
+
1653
+ Batch 91. A thin frame around `_run_steps`, which IS the loop and
1654
+ whose docstring documents every argument. `yield from` forwards each
1655
+ event and the return value unchanged, so nothing driving `_run` can
1656
+ tell the frame is there -- and nothing about the exception changes
1657
+ either: core/events.py has no error variant on purpose, and it still
1658
+ propagates to whoever drains this, exactly as it did.
1659
+
1660
+ Without it a run that failed left nothing behind in its thread --
1661
+ D20 persists an assistant turn only once a call returns -- so a
1662
+ subagent whose first call failed replayed as its task and nothing
1663
+ else. One frame covers every caller: a TUI turn, a CLI turn, a
1664
+ spawned subagent, a one-shot, a research pass.
1665
+
1666
+ `Exception`, not `BaseException`: a GeneratorExit is an ABANDONED
1667
+ generator (#42, a TUI quitting mid-turn), not a failed run, and
1668
+ recording it would stamp a failure on a turn nobody saw fail.
1669
+ Recording must never replace the error it records, so its own
1670
+ failure is warned and swallowed.
1671
+ """
1672
+ try:
1673
+ return (yield from RunAgentLoop._run_steps(memory, *args, **kwargs))
1674
+ except Exception as error:
1675
+ try:
1676
+ # THE DURABLE SINK, so the vocabulary matters most
1677
+ # here (batch 144). `API_URL` is user-supplied
1678
+ # through `save_credentials(api_url=...)`, an httpx error
1679
+ # names the URL it failed on, and this row lands in
1680
+ # `MessageLog.error` in app.db -- which `docs/PRIVACY.md`
1681
+ # says is deleted by wiping the database, not one thread.
1682
+ # `redact_secrets` alone would keep a URL's userinfo.
1683
+ memory.mark_turn_failed(
1684
+ redact_diagnostic_text(provider_errors.describe(error)))
1685
+ except Exception: # noqa: BLE001 -- see the docstring
1686
+ logger.warning(
1687
+ "Could not record this run's failure on its thread.",
1688
+ exc_info=True)
1689
+ raise
1690
+
1691
+ @staticmethod
1692
+ def _run_steps(
623
1693
  memory: ConversationMemory,
624
1694
  system_prompt: str,
625
1695
  provider_name: str,
@@ -634,6 +1704,7 @@ class RunAgentLoop:
634
1704
  grant_budget=None,
635
1705
  compaction_mode: Optional[str] = None,
636
1706
  activity=None,
1707
+ cancel=None,
637
1708
  ):
638
1709
  """Generator yielding LoopEvent objects as the loop progresses.
639
1710
 
@@ -675,6 +1746,16 @@ class RunAgentLoop:
675
1746
  caller silently ran on the chat trigger: a pass's JSON retry and
676
1747
  the §20 reviewer evaluated a threshold their own threads were
677
1748
  never meant to answer to.
1749
+
1750
+ cancel (§61): an optional core.cancel.CancelToken. None -- every
1751
+ caller that has not opted in, which is every caller predating
1752
+ §61 -- means nothing can stop this run, exactly as before. Set,
1753
+ it is read at the three sites inside this function that CN2
1754
+ names (the fourth is the shell's own drain), and the run then
1755
+ ENDS on `stop_reason: "cancelled"` rather than raising. It must
1756
+ not raise: the frame above records a failure on the thread for
1757
+ any exception that is not a GeneratorExit, and a person changing
1758
+ their mind is not a failed run.
678
1759
  """
679
1760
  # §29/#45 belt. `_run` is a generator, so this fires on the first
680
1761
  # next() -- which for every production caller is immediate, since
@@ -740,7 +1821,8 @@ class RunAgentLoop:
740
1821
  run_info = RunInfo(
741
1822
  model=model, provider_name=provider_name, effort=effort,
742
1823
  granted_tools=set(granted_tools or ()),
743
- grant_budget=grant_budget)
1824
+ grant_budget=grant_budget,
1825
+ images=_images_deliverable(provider_name, memory))
744
1826
  headless = response_channel is None
745
1827
  # The BUDGET is deliberately not consulted here. Advertisement is
746
1828
  # decided once per step; R6 makes exhaustion fall back to asking
@@ -750,10 +1832,25 @@ class RunAgentLoop:
750
1832
  # a reason it cannot observe, and the model would read that as the
751
1833
  # tool having ceased to exist.
752
1834
  tool_schemas = registry.schemas(
753
- context, callable_only=headless, granted=run_info.granted_tools)
1835
+ context, callable_only=headless, granted=run_info.granted_tools,
1836
+ images=run_info.images)
1837
+ if not run_info.images:
1838
+ unoffered = tuple(sorted(registry.image_hidden(
1839
+ context, granted=run_info.granted_tools)))
1840
+ key = (provider_name, getattr(memory, "kind", THREAD_KIND_CHAT),
1841
+ unoffered)
1842
+ if unoffered and key not in _image_notices_shown:
1843
+ _image_notices_shown.add(key)
1844
+ logger.warning(
1845
+ "Not advertising %s: an image in its result could not "
1846
+ "reach the model in this run (provider %s is not marked "
1847
+ "`accepts_images` in providers.json, or this is a "
1848
+ "research pass).",
1849
+ ", ".join(unoffered), provider_name)
754
1850
  if headless:
755
1851
  hidden = tuple(sorted(registry.headless_hidden(
756
- context, granted=run_info.granted_tools)))
1852
+ context, granted=run_info.granted_tools,
1853
+ images=run_info.images)))
757
1854
  if hidden and hidden not in _headless_notices_shown:
758
1855
  _headless_notices_shown.add(hidden)
759
1856
  logger.warning(
@@ -798,17 +1895,135 @@ class RunAgentLoop:
798
1895
 
799
1896
  response = None
800
1897
  for _ in range(max_steps):
1898
+ # §61 CN2, the step boundary -- and ABOVE the reset below,
1899
+ # which is the whole reason it sits here rather than at the
1900
+ # foot of the body. The response it reads is the PREVIOUS
1901
+ # step's: already counted, already persisted, and the last
1902
+ # thing the model actually said. That is the shape
1903
+ # "max_steps exhausted" already has at the end of this loop.
1904
+ # Below the reset it would read None on every iteration and
1905
+ # report an empty answer for a turn that had produced
1906
+ # several.
1907
+ if is_cancelled(cancel):
1908
+ yield from _finish_cancelled(
1909
+ memory, response, partial_text=None, unrun=(),
1910
+ reason=cancel.reason, granted_calls=granted_calls,
1911
+ notices=notices,
1912
+ totals=(total_tokens_used, turn_new_tokens,
1913
+ turn_output_tokens))
1914
+ return
801
1915
  response = None
802
- for token in call_model_stream(
803
- client, provider_name, model, memory.messages,
804
- system_prompt, tool_schemas, temperature, effort,
805
- ):
806
- if token.text_delta:
807
- yield LoopEvent(token_delta=token.text_delta)
808
- if token.thinking_delta:
809
- yield LoopEvent(thinking_delta=token.thinking_delta)
810
- if token.final_response is not None:
811
- response = token.final_response
1916
+ # Batch 91. ONE model call, attempted up to
1917
+ # 1 + MODEL_CALL_MAX_RETRIES times. The SDKs retry a request that
1918
+ # fails before its stream opens; an error sent INSIDE a stream
1919
+ # that opened with 200 is raised straight up by both, and that is
1920
+ # how OpenRouter reports an overloaded upstream. Which failures
1921
+ # qualify is core/provider_errors.py's question.
1922
+ #
1923
+ # `shown` was the boundary until batch 113 (TECHNICAL_DEBT 25).
1924
+ # It read "a RichLog row cannot be taken back", which was true
1925
+ # of the transcript as it stood: a retry after a delta would
1926
+ # have drawn the answer a second time under the half already on
1927
+ # screen, so a DRAWN run was refused the retry a reader most
1928
+ # wanted. Batch 112 made a row retractable -- `_replay()` draws
1929
+ # the transcript from `_entries` -- so the loop now says what
1930
+ # happened and the drawing surface takes its own rows back.
1931
+ #
1932
+ # `shown` survives with a different job: it is no longer "may we
1933
+ # retry" but "is there anything to retract", which is the only
1934
+ # question left for it to answer.
1935
+ #
1936
+ # Below the wrappers that write the user message, so a retry
1937
+ # never writes it twice; and before the accounting, so only the
1938
+ # attempt that succeeded is counted or persisted (D20). A failed
1939
+ # stream reports no usage to count in any case.
1940
+ retry = 0
1941
+ # §61 CN4. The deltas are accumulated HERE because no
1942
+ # provider branch can supply them after a cut: the Anthropic
1943
+ # one builds its text from `stream.get_final_message()`,
1944
+ # which a stream broken off part way never produces. Reset
1945
+ # per ATTEMPT, beside `shown`, so a retry that retracts what
1946
+ # was drawn does not also keep it.
1947
+ cut_short = False
1948
+ while True:
1949
+ shown = False
1950
+ partial = []
1951
+ try:
1952
+ for token in call_model_stream(
1953
+ client, provider_name, model, memory.messages,
1954
+ system_prompt, tool_schemas, temperature, effort,
1955
+ ):
1956
+ if token.final_response is not None:
1957
+ response = token.final_response
1958
+ # §61 CN2, and guarded on `response is None`
1959
+ # rather than placed by line order, because
1960
+ # placement alone was not enough: a cancel
1961
+ # arriving in the gap before the final-response
1962
+ # token still cut a call that had already been
1963
+ # made and paid for, and its usage went with it.
1964
+ # A step holding a complete response is
1965
+ # FINISHED -- it is accounted and persisted
1966
+ # exactly as always, and the stop lands at the
1967
+ # next site instead.
1968
+ if response is None and is_cancelled(cancel):
1969
+ cut_short = True
1970
+ break
1971
+ if token.text_delta:
1972
+ shown = True
1973
+ partial.append(token.text_delta)
1974
+ yield LoopEvent(token_delta=token.text_delta)
1975
+ if token.thinking_delta:
1976
+ shown = True
1977
+ yield LoopEvent(thinking_delta=token.thinking_delta)
1978
+ break
1979
+ except Exception as e: # noqa: BLE001 -- re-raised unless it qualifies
1980
+ retry += 1
1981
+ if (retry > config.MODEL_CALL_MAX_RETRIES
1982
+ or not provider_errors.is_transient(e)):
1983
+ raise
1984
+ response = None
1985
+ delay = provider_errors.backoff_delay(
1986
+ retry, config.MODEL_CALL_RETRY_BASE_DELAY_S,
1987
+ provider_errors.retry_after_s(e))
1988
+ attempts = config.MODEL_CALL_MAX_RETRIES + 1
1989
+ logger.warning(
1990
+ "Model call to %s/%s failed (%s); retrying in %.0fs, "
1991
+ "attempt %d of %d.",
1992
+ provider_name, model, provider_errors.describe(e),
1993
+ delay, retry + 1, attempts)
1994
+ if shown:
1995
+ # Batch 113. BEFORE the wait, not after it: the
1996
+ # reader is about to watch a part-written answer
1997
+ # disappear and then several seconds of nothing,
1998
+ # and the sentence explaining that is worth more
1999
+ # while it is happening than once it is over.
2000
+ #
2001
+ # Only when something was drawn. An attempt that
2002
+ # streamed nothing has nothing to take back, and
2003
+ # the warning above is already the record of it.
2004
+ yield LoopEvent(retract={
2005
+ "text": "the answer was interrupted (%s); "
2006
+ "retrying, attempt %d of %d"
2007
+ % (provider_errors.describe(e),
2008
+ retry + 1, attempts),
2009
+ "attempt": retry + 1,
2010
+ "attempts": attempts,
2011
+ })
2012
+ provider_errors.wait(delay)
2013
+
2014
+ # §61 CN2/CN4. Leaving the `for` above closed the
2015
+ # provider stream: every branch yields from inside its own
2016
+ # context manager, so the connection is already released by
2017
+ # the time this runs. What is left to decide is the
2018
+ # half-answer, and CN4 keeps it.
2019
+ if cut_short:
2020
+ yield from _finish_cancelled(
2021
+ memory, None, partial_text="".join(partial), unrun=(),
2022
+ reason=cancel.reason, granted_calls=granted_calls,
2023
+ notices=notices,
2024
+ totals=(total_tokens_used, turn_new_tokens,
2025
+ turn_output_tokens))
2026
+ return
812
2027
 
813
2028
  if response is None:
814
2029
  raise RuntimeError(
@@ -856,355 +2071,63 @@ class RunAgentLoop:
856
2071
  )
857
2072
  return
858
2073
 
859
- for call in response.tool_calls:
860
- yield LoopEvent(tool_call_start={
861
- "id": call.id, "name": call.name, "input": call.input,
862
- })
863
-
864
- # Single source of truth with dispatch(): approval_needed()
865
- # ORs the tool's own path/command-dependent approval_check
866
- # with the config/context requirement (§15). Both callers
867
- # go through it so they cannot diverge — a path-dependent
868
- # tool must yield permission_request so the TUI user can
869
- # approve, not be silently denied by one check while the
870
- # other reports no approval needed.
871
- #
872
- # There is no separate allowed_tools membership test here
873
- # any more: dispatch() calls is_tool_allowed(name, context),
874
- # which raises ToolCallDenied with a message distinguishing
875
- # a context restriction from a global policy denial.
876
- needs_approval = registry.approval_needed(
877
- call.name, call.input, context)
878
- # Reachability before approval. Asking first meant a
879
- # context-excluded tool prompted the user, who clicked
880
- # Allow, and was then denied anyway -- and headless, it
881
- # reported "requires approval and was not given", telling
882
- # the model to retry with approval when the actionable
883
- # answer is "not available in this context". dispatch()
884
- # still enforces the denial; this only stops asking a
885
- # question whose answer cannot matter.
886
- if needs_approval and not registry.is_allowed(call.name, context):
887
- needs_approval = False
888
- # §32 A7 (#70): the same rule for a refusal only the
889
- # TOOL can see. spawn_subagent's unknown-agent and
890
- # depth-limit checks lived inside run(), so both
891
- # prompted first and errored second -- and for an
892
- # unknown name the question had an empty notice and an
893
- # empty candidate list, i.e. nothing to tick. The
894
- # call is refused by dispatch with the tool's own
895
- # reason; this only stops ASKING first. It also keeps
896
- # J8's memo from being keyed on
897
- # (spawn_subagent, None) -- a subject of None is the
898
- # absence of the very thing the key exists to
899
- # distinguish.
900
- if needs_approval and registry.refusal_reason(
901
- call.name, call.input, context):
902
- needs_approval = False
903
- # §33 W3 (#37): the same rule for a call whose arguments
904
- # never parsed. Approving it could not make it runnable,
905
- # so the question has no answer that changes anything --
906
- # and headless it would report "requires approval and was
907
- # not given", which is A7's exact wrong-cause failure.
908
- if needs_approval and call.parse_error is not None:
909
- needs_approval = False
910
- # §18 sign-off (S1), narrowed by §25 (R2): a tool whose
911
- # grant_scope is "run" is asked about once per run, not
912
- # once per call. The loop names no tool -- it asks the
913
- # registry, the same way it asks whether approval is
914
- # needed at all.
915
- #
916
- # THREE conditions, and the last two are the §25 change:
917
- #
918
- # registry.grantable -- a tool deciding approval from its
919
- # PARAMS was never consented to by name. Before this,
920
- # a signed-off subagent could run any shell command for
921
- # the rest of the turn on the strength of one prompt
922
- # that said "shell". Re-checked here rather than
923
- # trusted from the set, so a stale or hand-built grant
924
- # cannot widen anything.
925
- #
926
- # grant_budget.take() -- pre-flight authorization trades
927
- # a per-call decision for one up-front decision, and
928
- # gives up the natural bound on how many times the
929
- # tool runs. Exhaustion falls back to ASKING, not to
930
- # failing: supervised runs continue, headless ones deny
931
- # exactly as they would for any gated tool.
932
- #
933
- # §23 AC1b: the memo is keyed by (tool, SUBJECT), not by
934
- # tool name alone. A subagent sign-off answers about one
935
- # agent's candidate list, so reusing it for a different
936
- # agent would grant a set nobody was shown -- which is
937
- # what the name-only version did: approving a spawn of `a`
938
- # silently covered a later spawn of `b` in the same turn.
939
- # Tools with no subject (every other one) memo under None
940
- # and behave exactly as before.
941
- # Batch 60. THIS CALL'S authorization decision, and the
942
- # error that stands in for it.
943
- #
944
- # THE ID, NOT A BOOLEAN, and that is the whole point of the
945
- # shape. `authorized` began as a bool whose correctness
946
- # rested on WHERE it was declared -- one indent level in and
947
- # it covers one call, one level out and it covers every
948
- # later call in the turn, which is the exact widening §25
949
- # R11 refuses to make even for the one tool whose grant
950
- # scope IS the run. That version was measured: hoisting it
951
- # out of `for call in response.tool_calls:` survived the
952
- # entire suite, because no path currently reaches dispatch
953
- # with a stale flag that changes anything. Correct, and
954
- # undefended.
955
- #
956
- # A call id cannot be hoisted into a lie. Moved out of the
957
- # loop it holds the PREVIOUS call's id, the comparison at
958
- # the dispatch site fails, and the call is DENIED -- the
959
- # mistake fails closed instead of failing open. It rests on
960
- # ids being distinct within a response, which is not a new
961
- # assumption: add_tool_result pairs every tool_result to its
962
- # tool_use by that same id (M4/D20), and a thread whose ids
963
- # collide is already unresumable.
964
- #
965
- # Set in exactly two places -- the memo/grant hit below and
966
- # the fresh approval further down -- and read in exactly
967
- # one, the single dispatch() call at the end of this block.
968
- authorized_call = None
969
- denial = None
970
- request_payload = registry.request_payload(
971
- call.name, call.input, context)
972
- subject = request_payload.get("subject")
973
- remembered, signoff = run_info.recall_signoff(
974
- call.name, subject)
975
- # grant_policy on a NAME-LEVEL grant only -- R13's literal
976
- # claim is that approving the NAME never carries the
977
- # authority for a GRANT_NEVER tool, on either path, and
978
- # until now no path enforced it. Batch 6 declared the
979
- # policy and taught the two functions that decide what
980
- # may be OFFERED to read it; this is the reader that
981
- # decides whether a grant already in hand APPLIES.
982
- # `spawn_subagent` was covered only because R14's
983
- # subject condition happens to catch it; `remember`
984
- # carries no subject, so a grant naming it dispatched a
985
- # durable cross-session write with no prompt -- M17's
986
- # scenario through the one door R13 left unlocked.
987
- #
988
- # IT MUST NOT REACH THE SIGN-OFF MEMO, and that is not a
989
- # nicety: `spawn_subagent` is GRANT_NEVER, so testing
990
- # the policy unconditionally here stops §23's memo
991
- # applying and the same agent is asked about twice in
992
- # one turn. R13 is about what approving a NAME buys; a
993
- # memo is an answer somebody gave about this subject,
994
- # which J8 and R14 govern instead. recall_signoff
995
- # already separates them by what it returns -- the memo
996
- # always carries a subset, the grant carries None.
997
- answered_by_name = signoff is None
998
- if (needs_approval
999
- and remembered
1000
- and registry.grantable(call.name)
1001
- and not (answered_by_name
1002
- and registry.grant_policy(call.name)
1003
- == GRANT_NEVER)
1004
- and (run_info.grant_budget is None
1005
- or run_info.grant_budget.take())):
1006
- needs_approval = False
1007
- # Batch 60. The half that was missing: the loop
1008
- # decided this call needs no fresh answer, and until now
1009
- # it did not tell dispatch(), which re-checks approval on
1010
- # its own and denied every call this branch let through.
1011
- # A second spawn of one agent, a subagent calling a tool
1012
- # it was signed off for, and a --grant-tools name in an
1013
- # unattended run were all refused with "requires approval
1014
- # and was not given" and no prompt.
1015
- authorized_call = call.id
1016
- granted_calls.append(
1017
- {"tool": call.name, "params": call.input})
1018
- # §21, and the reason this batch adds a notice at all:
1019
- # a gated call proceeding with NO modal is the intended
1020
- # behaviour (§25 R11 -- re-asking about the same tool
1021
- # seconds later is noise), and it is also exactly what
1022
- # the bug looked like from the outside. Silence was
1023
- # indistinguishable from the bug.
1024
- #
1025
- # DELIBERATELY NOT in _ONCE_PER_RUN_NOTICES. That list
1026
- # is for a STANDING CONDITION re-emitted on every step;
1027
- # this fires only when a call actually reuses an answer,
1028
- # which is an event -- the same reading that lets a
1029
- # compaction that HAPPENED repeat once per compaction.
1030
- # Once per run would go quiet again from the third spawn
1031
- # onward, which is the silence that started this.
1032
- #
1033
- # Two texts, discriminated by `answered_by_name`, which
1034
- # is already computed above: one sentence cannot honestly
1035
- # cover both. A memo is something the user answered
1036
- # minutes ago in this turn; a grant is something they
1037
- # decided before the run existed, possibly on a command
1038
- # line, and telling them they "answered earlier" would
1039
- # describe a moment that never happened.
1040
- notices.append({
1041
- "kind": "approval_reused",
1042
- "text": (
1043
- "%s is running on the authorization granted "
1044
- "before this run started." % call.name
1045
- if answered_by_name else
1046
- "Reusing your approval for %s, given earlier in "
1047
- "this turn." % (subject or call.name)),
1048
- })
1049
- yield LoopEvent(notice=notices[-1])
1050
- else:
1051
- # Not reused: nothing is carried into dispatch unless
1052
- # this call's own answer supplies it below.
1053
- signoff = None
1054
- if needs_approval:
1055
- notice = registry.approval_notice(
1056
- call.name, call.input, context)
1057
- # §42 (RA5). The agent's own stated reason, asked
1058
- # of the registry so the loop names no key -- the
1059
- # same way it asks what KIND of question a tool
1060
- # needs and whether it needs one at all. The VALUE
1061
- # travels rather than the key, because the two
1062
- # shells that render it are a Textual screen that
1063
- # imports nothing from this package and a `print`
1064
- # in main.py.
1065
- rationale = registry.rationale_for(
1066
- call.name, call.input)
1067
- # §46 (EP2). The SUBJECT of the question, resolved
1068
- # the same way and travelling the same route: for
1069
- # `shell` it is the command, and a shell that shows
1070
- # it must not have to know that. Every other tool
1071
- # answers None and its prompt is unchanged.
1072
- headline = registry.headline_for(
1073
- call.name, call.input)
1074
- yield LoopEvent(permission_request={
1075
- "tool_name": call.name, "params": call.input,
1076
- "notice": notice,
1077
- "rationale": rationale,
1078
- "headline": headline,
2074
+ # NA9. The response is partitioned before anything runs: a run of
2075
+ # calls whose ToolSpec declares `parallel` goes together, and every
2076
+ # other call is a group of one in its original position. A response
2077
+ # with nothing parallel in it therefore takes the same path it
2078
+ # always did, one group of one at a time.
2079
+ groups = _parallel_groups(response.tool_calls)
2080
+ for index, group in enumerate(groups):
2081
+ # §61 CN2/CN6. BETWEEN groups, never inside one. A call
2082
+ # already running finishes and settles: nothing here has
2083
+ # the power to kill a tool, and a cancel that threw away
2084
+ # a completed call's result would discard work already
2085
+ # done. Every group NOT reached still needs its rows --
2086
+ # #42's lesson from the other side -- which is what
2087
+ # `unrun` carries.
2088
+ if is_cancelled(cancel):
2089
+ yield from _finish_cancelled(
2090
+ memory, response, partial_text=None,
2091
+ unrun=[c for rest in groups[index:] for c in rest],
2092
+ reason=cancel.reason, granted_calls=granted_calls,
2093
+ notices=notices,
2094
+ totals=(total_tokens_used, turn_new_tokens,
2095
+ turn_output_tokens))
2096
+ return
2097
+ # In call order, and BEFORE anything is submitted, so a batch
2098
+ # announces its whole membership at once rather than in
2099
+ # whatever order three threads happen to reach their first
2100
+ # line. Hoisted out of `_dispatch_one` for exactly that: the
2101
+ # start of a call is a fact the frame that ordered it knows.
2102
+ for call in group:
2103
+ yield LoopEvent(tool_call_start={
2104
+ "id": call.id, "name": call.name, "input": call.input,
1079
2105
  })
1080
- approved, signoff = _obtain_approval(
1081
- response_channel, call.name, call.input, notice,
1082
- request_payload, rationale=rationale,
1083
- headline=headline)
1084
- if approved:
1085
- authorized_call = call.id
1086
- # §25 R11: run-scope is a shortcut for a chat turn,
1087
- # where re-asking about the same tool seconds later
1088
- # is noise. A provider that declines it is saying
1089
- # its whole purpose is per-call supervision --
1090
- # attended mode -- and one yes must not silently
1091
- # cover later calls there.
1092
- #
1093
- # This is ALSO the only thing that carries an answer
1094
- # between calls in a turn, and it is asked of the
1095
- # registry rather than assumed: `spawn_subagent` is
1096
- # the sole tool declaring grant_scope "run", so
1097
- # `shell`, `write` and `edit` are re-asked per call
1098
- # however many times one turn calls them.
1099
- if (registry.grant_scope(call.name) == "run"
1100
- and (response_channel is None
1101
- or response_channel.honour_run_scope)):
1102
- run_info.remember_signoff(
1103
- call.name, subject, signoff)
1104
- else:
1105
- denial = _denial_reason(
1106
- call.name, response_channel, context)
1107
- elif call.parse_error is not None:
1108
- # §33 W1 (#37). The loop is the only layer that can
1109
- # see this: dispatch() takes (name, params, context)
1110
- # and the failure is a fact about the wire, not about
1111
- # the params -- {} is a perfectly good empty dict by
1112
- # the time it gets there.
1113
- #
1114
- # RETURNED as the tool's result, not raised, for
1115
- # A10's reason: the model is told its arguments did not
1116
- # arrive and can reissue the call, which is the whole
1117
- # difference between losing one step and losing a
1118
- # ten-pass run.
1119
- denial = call.parse_error
1120
-
1121
- # ONE dispatch call site (batch 60). There were two,
1122
- # identical but for the two arguments that carry
1123
- # authorization, and the one reached by an already-answered
1124
- # call was the one that omitted them -- so every call this
1125
- # loop decided was authorized got denied by dispatch's own
1126
- # re-check. Two sites that must agree is the defect; one
1127
- # site is the fix, and no future edit can teach them to
1128
- # disagree again.
1129
- #
1130
- # dispatch() STILL RE-CHECKS, and must: it is a public
1131
- # entry point and the fail-closed backstop. What changed is
1132
- # that the loop now answers it.
1133
- #
1134
- # The callback is CONDITIONAL, and the condition is an
1135
- # identity check rather than a truth test: this call, not
1136
- # some call. See the declaration above for why the id and
1137
- # not a flag.
1138
- #
1139
- # DELETING the condition -- `lambda n, p: True` outright --
1140
- # is the one mutation here that no behaviour can catch, and
1141
- # it is caught in tests/test_grants.py by reading this
1142
- # source instead. Nothing can reach this line gated and
1143
- # un-authorized today, because the three other reasons
1144
- # `needs_approval` is turned off above are each
1145
- # short-circuited INSIDE dispatch before its gate
1146
- # (is_allowed raises, refusal_check returns, and a
1147
- # parse_error never gets here at all). A fourth reason added
1148
- # later would otherwise silently become "approve
1149
- # everything", with every test still green.
1150
- #
1151
- # `signoff` needs no condition -- the memo branch above nulls
1152
- # it on every path that is not a hit, so it is already None
1153
- # everywhere it should be.
1154
- if denial is not None:
1155
- result = {"error": denial}
2106
+
2107
+ if len(group) == 1:
2108
+ # No siblings, no gate, no thread. Byte-identical to the
2109
+ # pre-slice-8 path, which is what makes every existing
2110
+ # test of this loop a test of the sequential branch.
2111
+ settled = [(group[0], (yield from _dispatch_one(
2112
+ group[0], context=context, run_info=run_info,
2113
+ response_channel=response_channel, memory=memory,
2114
+ activity=activity, cancel=cancel)))]
1156
2115
  else:
1157
- try:
1158
- result = registry.dispatch(
1159
- call.name, call.input, context=context,
1160
- approval_callback=(
1161
- (lambda n, p: True)
1162
- if authorized_call == call.id else None),
1163
- parent_run=run_info,
1164
- response_channel=response_channel,
1165
- signoff=signoff,
1166
- memory=memory,
1167
- activity=activity,
1168
- )
1169
- except ToolCallDenied as e:
1170
- result = {"error": str(e)}
1171
- # §23 slice 2 (J10). A tool may attach a `notice` to its
1172
- # result for the shell to show; it is forwarded as a
1173
- # LoopEvent and REMOVED from what the model sees.
1174
- #
1175
- # Generic on purpose. The alternative was for the loop to
1176
- # notice that `todo_write` had just run, which puts a tool
1177
- # name in this file -- exactly what ToolSpec.grant_scope and
1178
- # ToolSpec.request_kind exist to avoid. Any later tool that
1179
- # wants to say something mid-turn gets this route free.
1180
- #
1181
- # POPPED, not copied: a notice is plumbing for the shell, and
1182
- # leaving it in the result would send the TUI panel's trigger
1183
- # to the model as if it were part of the tool's answer.
1184
- if isinstance(result, dict) and "notice" in result:
1185
- notice = result.pop("notice")
1186
- if isinstance(notice, dict) and notice.get("kind"):
1187
- yield LoopEvent(notice=notice)
1188
- else:
1189
- # A malformed notice is a bug in the tool, not a
1190
- # reason to fail the call -- the result is still
1191
- # good. Logged rather than raised, and the key is
1192
- # gone either way so it cannot reach the model.
1193
- logger.warning(
1194
- "%s returned a malformed notice; dropping it: %r",
1195
- call.name, notice)
1196
-
1197
- # Persist BEFORE emitting (#42). A generator only advances
1198
- # while someone iterates it, so emitting first made the row
1199
- # depend on a consumer continuing to read -- and an
1200
- # abandoned generator left the `tool_use` D20 already wrote
1201
- # with no matching `tool_result`, which is M4's pairing
1202
- # broken from the other side and an unresumable thread.
1203
- # Same rule §22 gives _Progress.checkpoint() for trace
1204
- # lines. The event carries nothing the persist needs, so
1205
- # the order is free.
1206
- memory.add_tool_result(call.id, result)
1207
- yield LoopEvent(tool_result={"id": call.id, "result": result})
2116
+ settled = yield from _dispatch_parallel(
2117
+ group, context=context, run_info=run_info,
2118
+ response_channel=response_channel, memory=memory,
2119
+ activity=activity, cancel=cancel)
2120
+
2121
+ # NA11. In the MODEL'S order, whatever order they finished in
2122
+ # -- and EVERY row of the group recorded before ANY event is
2123
+ # announced (#215, batch 221). #42's persist-before-emit
2124
+ # held per call and not per group: a consumer gone at the
2125
+ # first call's `tool_result` left the later calls' tools run
2126
+ # and their rows never written.
2127
+ announced = [event for call, outcome in settled
2128
+ for event in _settle_one(call, outcome, memory,
2129
+ granted_calls, notices)]
2130
+ yield from announced
1208
2131
 
1209
2132
  # The mid-turn valve (M3). A single turn can add far more than
1210
2133
  # any buffer covers -- MAX_READ_CHARS alone is ~12.5k tokens
@@ -1256,6 +2179,12 @@ class RunAgentLoop:
1256
2179
  authorization=None,
1257
2180
  thread_kind: str = THREAD_KIND_CHAT,
1258
2181
  activity=None,
2182
+ thread_parent: Optional[UUID] = None,
2183
+ thread_parent_call: Optional[str] = None,
2184
+ thread_agent: Optional[str] = None,
2185
+ cancel=None,
2186
+ observe=None,
2187
+ active_skills=(),
1259
2188
  ) -> ModelResponse:
1260
2189
  """Regular conversation — full tool set, default system prompt,
1261
2190
  one continuous thread. Pass thread_id to resume an existing
@@ -1295,39 +2224,48 @@ class RunAgentLoop:
1295
2224
  that are not a human conversation -- spawn_subagent, §20's reviewer
1296
2225
  and §21a's compactor -- pass THREAD_KIND_SUBAGENT, which is what
1297
2226
  keeps their threads out of the picker. Ignored when thread_id is
1298
- given: resuming does not reclassify."""
2227
+ given: resuming does not reclassify.
2228
+
2229
+ thread_parent / thread_parent_call / thread_agent (§47) record
2230
+ WHO created this thread, on the same terms: forwarded to the new
2231
+ thread, ignored on a resume. They are what makes a spawned run
2232
+ reachable afterwards -- without them a `▸ spawn_subagent` line
2233
+ describes a conversation nothing can find. Only the callers that
2234
+ know they are creating a child pass them.
2235
+
2236
+ observe (ROADMAP_v3 §86) is `run_to_completion`'s: handed every
2237
+ event as the turn runs. The CLI passes one to print the turn live.
2238
+
2239
+ active_skills (§89) are the session's `/skill` activations: marked
2240
+ in the default prompt's catalog and their bodies pinned last by
2241
+ session_tiers (§19 K1). The TUI builds its own prompt and passes
2242
+ none here; the CLI passes its session's."""
1299
2243
  if authorization is not None and granted_tools is not None:
1300
2244
  raise ValueError(
1301
2245
  "run_agent_conversation: pass authorization= or "
1302
2246
  "granted_tools=, not both -- they set the same underlying "
1303
2247
  "argument, so one would silently win."
1304
2248
  )
1305
- memory = ConversationMemory(thread_id=thread_id, kind=thread_kind)
2249
+ memory = ConversationMemory(
2250
+ thread_id=thread_id, kind=thread_kind,
2251
+ parent_thread_id=thread_parent,
2252
+ parent_call_id=thread_parent_call, agent_name=thread_agent)
2253
+ # §47. THE EARLIEST MOMENT THE ID EXISTS, which is what makes a
2254
+ # RUNNING child openable rather than only a finished one. The
2255
+ # span was opened by the caller before this function was called
2256
+ # -- the handler brackets the call, the thread is created inside
2257
+ # it -- so the sink learned a name and a depth and had no address
2258
+ # for them. A no-op when no span is open, which is every
2259
+ # top-level conversation, so this needs no branch.
2260
+ agent_activity.bind(activity, memory.thread_id)
1306
2261
  memory.add_user_message(user_goal)
1307
- # #68, and this branch is the one an unattended CLI run takes.
1308
- _callable_only, _granted = advertisement_facts(
1309
- authorization, response_channel, granted_tools)
1310
- prompt = with_goal(
1311
- system_prompt
1312
- if system_prompt is not None
1313
- else system_prompts.with_catalogs(
1314
- DEFAULT_SYSTEM_PROMPT, callable_only=_callable_only,
1315
- granted=_granted),
1316
- memory,
1317
- )
1318
- # §21b (M13). Only when there is no agent-built prompt: an agent
1319
- # run got its memories inside system_prompt_for(), and appending
1320
- # again here would duplicate them. `agent=None` is what makes a
1321
- # plain chat turn count as opted in -- see memories.manager.
1322
- if system_prompt is None:
1323
- prompt = with_memories(prompt)
1324
- # §21c. UNCONDITIONAL, unlike memories above: a reference belongs to
1325
- # the thread, not to an agent, so an agent-built prompt needs it too --
1326
- # and system_prompt_for() has no memory to read it from.
1327
- prompt = with_refs(prompt, memory)
1328
- # §23 slice 2. Unconditional too, and for with_refs' reason: a
1329
- # checklist is thread state, so an agent-built prompt needs it.
1330
- prompt = with_todos(prompt, memory)
2262
+ # ROADMAP_v3 §49: shared with wake_conversation, so a turn a
2263
+ # background session starts runs under the same prompt tiers.
2264
+ prompt = RunAgentLoop._conversation_prompt(
2265
+ memory, system_prompt, model=model, provider_name=provider_name,
2266
+ authorization=authorization,
2267
+ response_channel=response_channel, granted_tools=granted_tools,
2268
+ active_skills=active_skills)
1331
2269
  auth_kwargs = (
1332
2270
  _authorization_kwargs(authorization) if authorization is not None
1333
2271
  else {"granted_tools": granted_tools}
@@ -1353,8 +2291,9 @@ class RunAgentLoop:
1353
2291
  max_steps, _resolve_spend_cap(max_total_tokens),
1354
2292
  temperature=temperature, effort=effort,
1355
2293
  response_channel=response_channel, activity=activity,
2294
+ cancel=cancel,
1356
2295
  **auth_kwargs,
1357
- ))
2296
+ ), observe)
1358
2297
  response.thread_id = memory.thread_id
1359
2298
  return response
1360
2299
 
@@ -1406,42 +2345,65 @@ class RunAgentLoop:
1406
2345
  and never raw history, which is what stops a later pass reading how
1407
2346
  an earlier one argued. What was missing is the thread saying so, so
1408
2347
  that ~15 threads per run stop being offered as conversations.
2348
+
2349
+ §47: the span brackets the WHOLE generator, which is why it is the
2350
+ outermost thing in the body. A pass is a run in its own right and
2351
+ takes minutes; a row that appeared only at the end would describe
2352
+ something already over. It closes on GeneratorExit too, which is
2353
+ the abandonment case §22 records above -- a TUI quitting mid-run
2354
+ must not leave the pass on screen.
1409
2355
  """
1410
- memory = ConversationMemory(kind=THREAD_KIND_RESEARCH_PASS)
1411
- memory.add_user_message(pass_input)
1412
- # #68. The catalogs are decided from the SAME bundle the tool
1413
- # schemas are decided from a few frames down, so a pass cannot
1414
- # be told to spawn a subagent it will not be given.
1415
- _callable_only, _granted = advertisement_facts(authorization)
1416
- system_prompt = system_prompts.pass_prompt(
1417
- pass_id, callable_only=_callable_only, granted=_granted)
1418
- response = None
1419
- for event in RunAgentLoop._run(
1420
- memory, system_prompt, provider_name, model, context,
1421
- max_steps, _resolve_spend_cap(max_total_tokens),
1422
- temperature=temperature, effort=effort,
1423
- # §21 M6. A pass is headless and unattended and already returns
1424
- # a distillation, so routine compaction here would spend on a
1425
- # judgment call nobody is watching. The backstop still fires
1426
- # near the model's real context window, because the
1427
- # alternative there is a hard provider error mid-pipeline.
1428
- compaction_mode="backstop",
1429
- activity=activity,
1430
- **_authorization_kwargs(authorization),
1431
- ):
1432
- if event.final_response is not None:
1433
- response = event.final_response
1434
- yield event
1435
- if response is None:
1436
- # Same contract as run_to_completion's RuntimeError, and for
1437
- # the same reason: a loop that ended without a final response
1438
- # has a bug, and returning None would push the failure into
1439
- # whichever pass dereferences .text first.
1440
- raise RuntimeError(
1441
- "Generator completed without yielding a final_response"
1442
- )
1443
- response.thread_id = memory.thread_id
1444
- return response
2356
+ # Depth derived from the context the pass starts at rather than
2357
+ # written as a 1: `_compactor_depth`'s rule, one entry point over.
2358
+ depth = (context.subagent_depth if context is not None else 0) + 1
2359
+ with agent_activity.span(activity, pass_id, depth):
2360
+ memory = ConversationMemory(
2361
+ kind=THREAD_KIND_RESEARCH_PASS,
2362
+ # §47. No parent THREAD: a pass is a child of the RUN, and
2363
+ # a run is not a conversation. §27's T2 already indexes
2364
+ # them on `PipelineRun.pass_threads`, the run's own
2365
+ # object, so a second index here would be two records of
2366
+ # one edge -- the producer/consumer shape this project
2367
+ # keeps finding.
2368
+ agent_name=pass_id)
2369
+ # The address, at the earliest moment it exists, so a pass is
2370
+ # openable WHILE it runs rather than once the report lands.
2371
+ agent_activity.bind(activity, memory.thread_id)
2372
+ memory.add_user_message(pass_input)
2373
+ # #68. The catalogs are decided from the SAME bundle the tool
2374
+ # schemas are decided from a few frames down, so a pass cannot
2375
+ # be told to spawn a subagent it will not be given.
2376
+ _callable_only, _granted = advertisement_facts(authorization)
2377
+ system_prompt = system_prompts.pass_prompt(
2378
+ pass_id, callable_only=_callable_only, granted=_granted)
2379
+ response = None
2380
+ for event in RunAgentLoop._run(
2381
+ memory, system_prompt, provider_name, model, context,
2382
+ max_steps, _resolve_spend_cap(max_total_tokens),
2383
+ temperature=temperature, effort=effort,
2384
+ # §21 M6. A pass is headless and unattended and already
2385
+ # returns a distillation, so routine compaction here would
2386
+ # spend on a judgment call nobody is watching. The
2387
+ # backstop still fires near the model's real context
2388
+ # window, because the alternative there is a hard provider
2389
+ # error mid-pipeline.
2390
+ compaction_mode="backstop",
2391
+ activity=activity,
2392
+ **_authorization_kwargs(authorization),
2393
+ ):
2394
+ if event.final_response is not None:
2395
+ response = event.final_response
2396
+ yield event
2397
+ if response is None:
2398
+ # Same contract as run_to_completion's RuntimeError, and
2399
+ # for the same reason: a loop that ended without a final
2400
+ # response has a bug, and returning None would push the
2401
+ # failure into whichever pass dereferences .text first.
2402
+ raise RuntimeError(
2403
+ "Generator completed without yielding a final_response"
2404
+ )
2405
+ response.thread_id = memory.thread_id
2406
+ return response
1445
2407
 
1446
2408
  @staticmethod
1447
2409
  def continue_conversation(
@@ -1488,3 +2450,117 @@ class RunAgentLoop:
1488
2450
  ))
1489
2451
  response.thread_id = thread_id
1490
2452
  return response
2453
+
2454
+ @staticmethod
2455
+ def _conversation_prompt(memory, system_prompt, *, model, provider_name,
2456
+ authorization=None,
2457
+ response_channel=None, granted_tools=None,
2458
+ active_skills=()) -> str:
2459
+ """The system prompt a conversation turn runs under -- ONE copy, for a
2460
+ turn the user started and a turn a background session's result
2461
+ started (ROADMAP_v3 §49), so a wake turn cannot run under a prompt
2462
+ missing the goal, the references or the checklist a user's turn has.
2463
+
2464
+ Moved out of run_agent_conversation unchanged; its comments there
2465
+ record why each tier is conditional or not.
2466
+ """
2467
+ # #68, and this branch is the one an unattended CLI run takes.
2468
+ _callable_only, _granted = advertisement_facts(
2469
+ authorization, response_channel, granted_tools)
2470
+ base = (system_prompt if system_prompt is not None
2471
+ else system_prompts.with_catalogs(
2472
+ with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
2473
+ list(active_skills or ()) or None,
2474
+ callable_only=_callable_only,
2475
+ granted=_granted))
2476
+ # A system_prompt handed in is an agent's, built by
2477
+ # system_prompt_for(); see session_tiers for why that decides the
2478
+ # memories. §54 AT7: internal compaction and review also use this
2479
+ # wrapper, and their source is not a person's file mention.
2480
+ return session_tiers(base, memory,
2481
+ agent_built=system_prompt is not None,
2482
+ mentions=memory.kind == THREAD_KIND_CHAT,
2483
+ active_skills=active_skills)
2484
+
2485
+ @staticmethod
2486
+ def wake_conversation(
2487
+ thread_id: UUID,
2488
+ text: str,
2489
+ harness: dict,
2490
+ model: str,
2491
+ provider_name: str = DEFAULT_PROVIDER,
2492
+ max_steps: int = config.MAX_ITERATIONS,
2493
+ max_total_tokens: Optional[int] = _SPEND_UNSET,
2494
+ temperature: Optional[float] = None,
2495
+ effort: Optional[str] = None,
2496
+ context: Optional[ToolContext] = None,
2497
+ system_prompt: Optional[str] = None,
2498
+ response_channel=None,
2499
+ granted_tools: Optional[set] = None,
2500
+ authorization=None,
2501
+ activity=None,
2502
+ cancel=None,
2503
+ observe=None,
2504
+ active_skills=(),
2505
+ ) -> ModelResponse:
2506
+ """A turn started by the HARNESS in an existing thread: a background
2507
+ session's result, delivered as a harness-written user row
2508
+ (ROADMAP_v3 §49, SS5). Drained, like the two wrappers above -- the
2509
+ subagent asleep in its spawn and the CLI's wait loop call it; the
2510
+ TUI builds its own generator, as it does for a user's turn.
2511
+
2512
+ `run_agent_conversation`'s arguments, less what only a NEW thread
2513
+ needs (kind, lineage) and plus the row: a wake runs with the same
2514
+ channel, grant, authorization, activity and CANCEL as the run whose
2515
+ session it reports, because it IS that run continuing. `cancel` was
2516
+ the one member of that list the signature omitted, and because
2517
+ `agents/subagent_tool.py` builds ONE `common` dict for the child's
2518
+ first turn and every wake after it -- deliberately, so the two
2519
+ cannot drift -- §61's CN7 adding `cancel` to that dict meant every
2520
+ subagent wake turn raised `TypeError` before anything else
2521
+ happened, 100% of the time, discarding a full agent run that had
2522
+ already been paid for in model calls (batch 133). `authorization` is
2523
+ what the CLI's chat loop carries -- without it a wake turn would
2524
+ run with no way to ask a human, so every gated call in it would be
2525
+ denied for a reason that is about the harness rather than the
2526
+ request, which is the silent-stripping failure §25 records.
2527
+
2528
+ `observe` is `run_agent_conversation`'s (§86): the CLI's wait loop
2529
+ prints a wake turn live exactly as it prints the user's own.
2530
+
2531
+ NOT a second `_run`. tests/test_grants.py walks this module for
2532
+ exactly one function by that name, and this is a wrapper over it.
2533
+ """
2534
+ if authorization is not None and granted_tools is not None:
2535
+ raise ValueError(
2536
+ "wake_conversation: pass authorization= or granted_tools=, "
2537
+ "not both -- they set the same underlying argument, so one "
2538
+ "would silently win."
2539
+ )
2540
+ memory = ConversationMemory(thread_id=thread_id)
2541
+ agent_activity.bind(activity, memory.thread_id)
2542
+ memory.add_harness_message(text, harness)
2543
+ prompt = RunAgentLoop._conversation_prompt(
2544
+ memory, system_prompt, model=model, provider_name=provider_name,
2545
+ authorization=authorization,
2546
+ response_channel=response_channel, granted_tools=granted_tools,
2547
+ active_skills=active_skills)
2548
+ auth_kwargs = (
2549
+ _authorization_kwargs(authorization) if authorization is not None
2550
+ else {"granted_tools": granted_tools}
2551
+ )
2552
+ # The explicit argument wins, and the key is popped unconditionally
2553
+ # -- run_agent_conversation's reasoning, unchanged.
2554
+ bundled_channel = auth_kwargs.pop("response_channel", None)
2555
+ response_channel = response_channel or bundled_channel
2556
+ response = run_to_completion(RunAgentLoop._run(
2557
+ memory, prompt,
2558
+ provider_name, model, context,
2559
+ max_steps, _resolve_spend_cap(max_total_tokens),
2560
+ temperature=temperature, effort=effort,
2561
+ response_channel=response_channel, activity=activity,
2562
+ cancel=cancel,
2563
+ **auth_kwargs,
2564
+ ), observe)
2565
+ response.thread_id = memory.thread_id
2566
+ return response