@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/tools/registry.py CHANGED
@@ -21,35 +21,63 @@ ROADMAP_v2 §15:
21
21
 
22
22
  import inspect
23
23
  import logging
24
+ from typing import TYPE_CHECKING, Optional
24
25
 
25
26
  import config
26
- from typing import Optional, TYPE_CHECKING
27
-
28
- from tools.base import (
29
- BUDGET_COMPUTE, BUDGET_HUMAN, BUDGET_IO,
30
- GRANT_ANYWHERE, GRANT_NEVER, GRANT_SIGNOFF_ONLY, ToolSpec,
31
- assert_budget_declared, assert_grant_policy_declared,
27
+ from agents import subagent_tool
28
+ from safety.policy_enforcement import (
29
+ check_input_policy,
30
+ check_output_policy,
31
+ param_digest,
32
+ redacted_values,
33
+ )
34
+ from security.permissions import (
35
+ APPROVAL_BY_SHELL_MODE,
36
+ assert_permissions_declared,
37
+ is_tool_allowed,
38
+ requires_approval,
32
39
  )
33
40
  from tools import isolation
34
- from tools.builtin import (
35
- web_search, fetch_url, get_time, arxiv,
36
- symbolic_math, linear_algebra, probability_stats, discrete_math, logic, geometry,
37
- file_ops, shell, load_skill, pin, remember, project_docs,
38
- ask_user, todo,
41
+ from tools.base import (
42
+ BUDGET_COMPUTE,
43
+ BUDGET_HUMAN,
44
+ BUDGET_IO,
45
+ GRANT_ANYWHERE,
46
+ GRANT_NEVER,
47
+ GRANT_SIGNOFF_ONLY,
48
+ OPENS_CALL,
49
+ OPENS_SESSION,
50
+ OPENS_THREAD,
51
+ ToolSpec,
52
+ assert_budget_declared,
53
+ assert_grant_policy_declared,
39
54
  )
40
- from security.permissions import (
41
- assert_permissions_declared, is_tool_allowed, requires_approval,
55
+ from tools.builtin import (
56
+ arxiv,
57
+ ask_user,
58
+ discrete_math,
59
+ fetch_url,
60
+ file_ops,
61
+ geometry,
62
+ get_time,
63
+ linear_algebra,
64
+ load_skill,
65
+ logic,
66
+ pin,
67
+ probability_stats,
68
+ project_docs,
69
+ remember,
70
+ shell,
71
+ shell_sessions,
72
+ symbolic_math,
73
+ todo,
74
+ web_search,
42
75
  )
43
- from safety.policy_enforcement import (check_input_policy,
44
- check_output_policy,
45
- param_digest,
46
- redacted_values)
47
- from agents import subagent_tool
48
76
 
49
77
  logger = logging.getLogger(__name__)
50
78
 
51
79
  if TYPE_CHECKING: # pragma: no cover - typing only
52
- from tools.context import ToolContext, RunInfo
80
+ from tools.context import RunInfo, ToolContext
53
81
 
54
82
  # Handler parameter names dispatch() will inject, by signature inspection
55
83
  # (ROADMAP_v2 §18). A tool handler that declares one of these receives the
@@ -76,6 +104,20 @@ _INJECTABLE_PARAMS = (
76
104
  # threaded through params because it is a run-scoped value, exactly
77
105
  # like response_channel beside it.
78
106
  "activity",
107
+ # ROADMAP_v3 §61 (CN7): the turn's CancelToken, for spawn_subagent. A
108
+ # child run is the parent's turn continuing, so stopping the parent
109
+ # stops it -- and the only way a value reaches a run that happens
110
+ # INSIDE a tool call is this list, which is `activity`'s own argument
111
+ # one line up.
112
+ "cancel",
113
+ # ROADMAP_v2 §47: the model's own id for THIS call. A tool that
114
+ # creates something durable can then record which call created it,
115
+ # which is what lets one line in a transcript find one row in the
116
+ # database when a turn made three of them. Injected rather than put
117
+ # in params, twice over: params are the MODEL'S, parsed from its
118
+ # tool call, and a model that could write its own call id could
119
+ # claim a line it did not make.
120
+ "call_id",
79
121
  )
80
122
 
81
123
 
@@ -119,14 +161,24 @@ class ToolRegistry:
119
161
  self._tools.pop(tool_name, None)
120
162
  self._injectable.pop(tool_name, None)
121
163
 
122
- def _advertised(self, name: str, spec, context) -> bool:
164
+ def _advertised(self, name: str, spec, context,
165
+ images: bool = False) -> bool:
123
166
  """The two §15 filters, shared by schemas() and
124
167
  headless_hidden(): policy allowability plus the tool's own
125
- "nothing to act on" signal."""
168
+ "nothing to act on" signal -- and, since ROADMAP_v3 §81 (IM6), a
169
+ third: a tool whose result carries an image is offered only where
170
+ the caller says images can be delivered.
171
+
172
+ `images` DEFAULTS FALSE, so a caller that never heard of images
173
+ hides such a tool rather than offering one whose result the model
174
+ could not see. The loop is the one caller that knows the answer,
175
+ and it passes it."""
126
176
  if not is_tool_allowed(name, context):
127
177
  return False
128
178
  if spec.available_check is not None and not spec.available_check():
129
179
  return False
180
+ if spec.returns_images and not images:
181
+ return False
130
182
  return True
131
183
 
132
184
  def _answered_by_grant(self, tool_name: str, granted) -> bool:
@@ -186,6 +238,7 @@ class ToolRegistry:
186
238
  self, tool_name: str, context: Optional["ToolContext"] = None,
187
239
  callable_only: bool = False,
188
240
  granted: Optional[set] = None,
241
+ images: bool = False,
189
242
  ) -> bool:
190
243
  """Whether schemas() would advertise this tool right now.
191
244
 
@@ -213,7 +266,7 @@ class ToolRegistry:
213
266
  spec = self._tools.get(tool_name)
214
267
  if spec is None:
215
268
  return False
216
- if not self._advertised(tool_name, spec, context):
269
+ if not self._advertised(tool_name, spec, context, images):
217
270
  return False
218
271
  return not (callable_only
219
272
  and self.approval_needed(tool_name, {}, context)
@@ -223,6 +276,7 @@ class ToolRegistry:
223
276
  self, context: Optional["ToolContext"] = None,
224
277
  callable_only: bool = False,
225
278
  granted: Optional[set] = None,
279
+ images: bool = False,
226
280
  ) -> list[dict]:
227
281
  """What gets sent to the LLM's `tools` parameter each call.
228
282
 
@@ -249,6 +303,9 @@ class ToolRegistry:
249
303
  * granted (§25 R15) -- names a pre-flight grant already answered
250
304
  for. Those stay advertised even with no channel, because the
251
305
  approval question HAS an answer; see _answered_by_grant.
306
+ * images (ROADMAP_v3 §81, IM6) -- whether an image in a tool
307
+ result can reach the model in this run. A tool that declares
308
+ `returns_images` is dropped when it cannot; see _advertised.
252
309
 
253
310
  WHAT callable_only GUARANTEES, stated because the converse does not
254
311
  hold and #158 is what assuming it costs: it means SOME call shape
@@ -263,11 +320,12 @@ class ToolRegistry:
263
320
  """
264
321
  return [spec.schema for name, spec in self._tools.items()
265
322
  if self.is_advertised(name, context, callable_only,
266
- granted)]
323
+ granted, images)]
267
324
 
268
325
  def headless_hidden(
269
326
  self, context: Optional["ToolContext"] = None,
270
327
  granted: Optional[set] = None,
328
+ images: bool = False,
271
329
  ) -> list[str]:
272
330
  """Names that would be advertised with a response_channel but
273
331
  are dropped by schemas(callable_only=True) -- i.e. advertised yet
@@ -288,8 +346,28 @@ class ToolRegistry:
288
346
  # disagrees with itself.
289
347
  return [
290
348
  name for name in self._tools
291
- if self.is_advertised(name, context, False, granted)
292
- and not self.is_advertised(name, context, True, granted)
349
+ if self.is_advertised(name, context, False, granted, images)
350
+ and not self.is_advertised(name, context, True, granted, images)
351
+ ]
352
+
353
+ def image_hidden(
354
+ self, context: Optional["ToolContext"] = None,
355
+ granted: Optional[set] = None,
356
+ ) -> list[str]:
357
+ """ROADMAP_v3 §81 (IM6). Names that would be advertised if images
358
+ could be delivered, and are dropped because they cannot. The loop
359
+ logs exactly this list, once, for headless_hidden()'s reason: a
360
+ tool the user enabled and the model never sees is named and
361
+ explained, not silently absent.
362
+
363
+ Written as the two calls it means, like headless_hidden() above,
364
+ so the list and the schemas can only disagree if is_advertised
365
+ disagrees with itself.
366
+ """
367
+ return [
368
+ name for name in self._tools
369
+ if self.is_advertised(name, context, False, granted, True)
370
+ and not self.is_advertised(name, context, False, granted, False)
293
371
  ]
294
372
 
295
373
  def approval_needed(
@@ -512,6 +590,85 @@ class ToolRegistry:
512
590
  key = self.rationale_param(tool_name)
513
591
  return redacted_values(params, omit=(key,) if key else ())
514
592
 
593
+ def opens_thread(self, tool_name: str) -> bool:
594
+ """Whether a call to this tool creates a thread of its own (§47).
595
+
596
+ Mechanism, not policy, exactly like request_kind below: a reader
597
+ asks rather than knowing that spawn_subagent is special. Two
598
+ consumers -- core/replay.py, deciding what a stored tool line
599
+ carries, and the TUI, deciding which live line to arm -- and one
600
+ declaration between them.
601
+
602
+ False for an unknown tool, which is what an MCP tool registered
603
+ at runtime is until it says otherwise.
604
+ """
605
+ spec = self._tools.get(tool_name)
606
+ return bool(spec is not None and spec.opens_thread)
607
+
608
+ def opens_session(self, tool_name: str) -> bool:
609
+ """Whether a call to this tool starts a background session (§49,
610
+ SS14). `opens_thread`'s sibling, and False for an unknown tool for
611
+ the same reason."""
612
+ spec = self._tools.get(tool_name)
613
+ return bool(spec is not None and spec.opens_session)
614
+
615
+ def opens(self, tool_name: str) -> tuple:
616
+ """What a call to this tool OPENS: `("thread",)`, `("session",)` or
617
+ `("call",)` (§47, extended by §49 SS14, widened by §55 TR7).
618
+
619
+ THE ONE QUESTION A CONSUMER ASKS, and the reason the two flags above
620
+ are not read directly outside this class. core/replay.py and the TUI
621
+ each decide what a tool line carries; before this they asked
622
+ `opens_thread` and would each have had to grow the same second
623
+ branch, which is how the live line and the replayed one come to
624
+ disagree about what is clickable -- the exact divergence
625
+ `opens_thread`'s own docstring exists to prevent, one kind over.
626
+
627
+ THERE IS NO LONGER AN EMPTY ANSWER, and the contract that replaced
628
+ it is the one thing to read here before changing a caller. Until
629
+ §55 this returned `()` for a line that opened nothing, and the two
630
+ consumers paired that falsy tuple with a call id as their gate:
631
+ `opens and call_id`. TR7 makes every call openable -- its own
632
+ params and its own result, which is the half of a tool call nothing
633
+ rendered -- so the kind is always present and THE CALL ID IS THE
634
+ ONLY GATE. A call the model made without an id cannot be looked up
635
+ in the archive and is the one unarmed line.
636
+
637
+ OPENS_CALL IS ANSWERED WITHOUT A REGISTRY LOOKUP, deliberately.
638
+ `opens_thread` and `opens_session` are False for a tool this
639
+ registry has never seen -- which is what an MCP tool registered at
640
+ runtime is until it says otherwise, and what a tool removed between
641
+ a thread being written and being replayed is for ever. Neither of
642
+ those is a reason to hide a stored result: the archive holds the
643
+ call and its result whatever this process knows about the tool, so
644
+ the fallback is a property of the ARCHIVE rather than of the
645
+ registry, and asking would only teach it to lie about old threads.
646
+
647
+ A tuple rather than a string because the two consumers carry
648
+ `(kind, call id)` into style metadata as one unit, and because the
649
+ shape outlived the falsy contract that first chose it.
650
+ """
651
+ if self.opens_thread(tool_name):
652
+ return (OPENS_THREAD,)
653
+ if self.opens_session(tool_name):
654
+ return (OPENS_SESSION,)
655
+ return (OPENS_CALL,)
656
+
657
+ def parallel(self, tool_name: str) -> bool:
658
+ """Whether several calls to this tool in one response may run at
659
+ the same time (§47 slice 8, NA9).
660
+
661
+ Mechanism, not policy, in `opens_thread`'s exact shape and for its
662
+ reason: core/loop.py partitions a response by asking, so the file
663
+ that decides what runs concurrently names no tool.
664
+
665
+ False for an unknown tool, which is what an MCP tool registered at
666
+ runtime is until it says otherwise -- and the answer that keeps a
667
+ stranger's tool sequential, which is the safe one here.
668
+ """
669
+ spec = self._tools.get(tool_name)
670
+ return bool(spec is not None and spec.parallel)
671
+
515
672
  def request_kind(self, tool_name: str) -> str:
516
673
  """Which kind of question approving this tool asks (§23).
517
674
 
@@ -600,6 +757,8 @@ class ToolRegistry:
600
757
  signoff=None,
601
758
  memory=None,
602
759
  activity=None,
760
+ call_id=None,
761
+ cancel=None,
603
762
  ) -> dict:
604
763
  # Unknown-tool guard: ValueError, deliberately NOT ToolCallDenied.
605
764
  # The two exception types separate "you misnamed it" from "policy
@@ -637,7 +796,33 @@ class ToolRegistry:
637
796
  if refused is not None:
638
797
  logger.info("%s refused before approval: %s",
639
798
  tool_name, refused)
640
- return {"error": refused}
799
+ # THROUGH THE REDACTOR, like every other result (batch 156,
800
+ # A60). This was the one `return` in this function that did
801
+ # not, and it is a result path: the success path, the
802
+ # handler-exception path and the depth cap all pass the call
803
+ # below, and this one went straight out.
804
+ #
805
+ # IT WAS NOT A THEORETICAL HOLE. Measured (batch 156) through
806
+ # this very function: `spawn_subagent` with an `agent_name` of
807
+ # `ghp_` plus 36 characters came back as "Unknown agent:
808
+ # '<the whole token>' is not one of this harness's agents" --
809
+ # the full credential, to the model and to the transcript,
810
+ # from a value the model chose. And the harness has a scanner
811
+ # for exactly that input: `check_input_policy` BELOW refuses
812
+ # the same params with "an argument contains what looks like
813
+ # a credential". The refusal returned above it, so both
814
+ # scanners were skipped on one path -- §25 (R5) exists
815
+ # because "the parameters were chosen by a model reading an
816
+ # attacker's web page", and this is where that argument was
817
+ # not being applied.
818
+ #
819
+ # THE SINK AND NOT THE PRODUCER, which is the same split the
820
+ # handler containment two inches below uses: a refusal string
821
+ # is written by whichever tool owns the gate, and this is the
822
+ # one place that covers the next one. `tools/base.py` still
823
+ # asks producers not to echo a value, for a reason that
824
+ # survives this change and is stated there.
825
+ return check_output_policy(tool_name, {"error": refused})
641
826
 
642
827
  spec = self._tools[tool_name]
643
828
 
@@ -673,6 +858,8 @@ class ToolRegistry:
673
858
  "signoff": signoff,
674
859
  "memory": memory,
675
860
  "activity": activity,
861
+ "call_id": call_id,
862
+ "cancel": cancel,
676
863
  }
677
864
  injected = {p: available[p] for p in self._injectable.get(tool_name, ())}
678
865
  try:
@@ -687,8 +874,12 @@ class ToolRegistry:
687
874
  # The branch is HERE, inside the containment try and at the
688
875
  # one place a handler is ever invoked, rather than inside the
689
876
  # six tools. A tool that isolated itself could not be called
690
- # plainly by a test, and the 123 tests in test_math_tools.py
877
+ # plainly by a test, and every test in test_math_tools.py
691
878
  # would then be measuring the transport instead of the maths.
879
+ # (The count that used to stand here said 123 and was 131 by
880
+ # the time anyone checked, and 141 after batch 131 -- the
881
+ # ARGUMENT never needed the number, which is why it is gone
882
+ # rather than corrected.)
692
883
  #
693
884
  # `injected` is not passed: nothing in _INJECTABLE_PARAMS
694
885
  # survives a process boundary, and assert_budget_declared
@@ -786,13 +977,55 @@ registry.register(ToolSpec("geometry", geometry.TOOL_SCHEMA, geometry.run, grant
786
977
  # pre-approval, so no human is asked a question the tool would refuse
787
978
  # anyway. The handlers re-test -- the refusal_check is the
788
979
  # prompt-suppression half, not the enforcement.
789
- registry.register(ToolSpec("read", file_ops.READ_TOOL_SCHEMA, file_ops.read_run, approval_check=file_ops._file_approval_check, refusal_check=file_ops._protected_refusal, grant_policy=GRANT_NEVER, budget=BUDGET_IO))
790
- registry.register(ToolSpec("write", file_ops.WRITE_TOOL_SCHEMA, file_ops.write_run, approval_check=file_ops._file_approval_check, refusal_check=file_ops._protected_refusal, grant_policy=GRANT_NEVER, budget=BUDGET_IO))
791
- registry.register(ToolSpec("edit", file_ops.EDIT_TOOL_SCHEMA, file_ops.edit_run, approval_check=file_ops._file_approval_check, refusal_check=file_ops._protected_refusal, grant_policy=GRANT_NEVER, budget=BUDGET_IO))
980
+ registry.register(ToolSpec("read", file_ops.READ_TOOL_SCHEMA, file_ops.read_run, approval_check=file_ops._file_approval_check, refusal_check=file_ops._refusal_for("read"), grant_policy=GRANT_NEVER, budget=BUDGET_IO))
981
+ # ROADMAP_v3 §81 (IM1, IM6). `read`'s path rules exactly -- the same approval
982
+ # check and the same refusal shape -- plus `returns_images`, which keeps it
983
+ # off the schema list wherever the image could not reach the model.
984
+ registry.register(ToolSpec("view_image", file_ops.VIEW_IMAGE_TOOL_SCHEMA, file_ops.view_image_run, approval_check=file_ops._file_approval_check, refusal_check=file_ops._refusal_for("view_image"), grant_policy=GRANT_NEVER, budget=BUDGET_IO, returns_images=True))
985
+ registry.register(ToolSpec("write", file_ops.WRITE_TOOL_SCHEMA, file_ops.write_run, approval_check=file_ops._file_approval_check, refusal_check=file_ops._refusal_for("write"), grant_policy=GRANT_NEVER, budget=BUDGET_IO))
986
+ registry.register(ToolSpec("edit", file_ops.EDIT_TOOL_SCHEMA, file_ops.edit_run, approval_check=file_ops._file_approval_check, refusal_check=file_ops._refusal_for("edit"), grant_policy=GRANT_NEVER, budget=BUDGET_IO))
792
987
  # §28: approval_notice carries the capability profile into the prompt.
793
988
  # The command text is already in the params; what it does not show is
794
989
  # WHERE it runs, and "cat /etc/shadow" does not look like a host read.
795
990
  registry.register(ToolSpec("shell", shell.TOOL_SCHEMA, shell.run, approval_check=shell._shell_approval_check, approval_notice=shell._shell_approval_notice, grant_policy=GRANT_NEVER, budget=BUDGET_IO, rationale_param="rationale", headline_param="command"))
991
+ # ROADMAP_v3 §49 (SS11, SS16, SS17). Five tools over background and monitor
992
+ # sessions, and the two that START one are `shell` with a lifetime: the same
993
+ # approval_check OBJECT, because a session runs a command and a second gate
994
+ # over it would be the ratchet G3 removed -- _assert_shell_mode_exemption
995
+ # below requires that identity, which is what ties the missing
996
+ # `tool_approvals` field to the gate that replaces it.
997
+ #
998
+ # available_check rather than a permission: all seven are hidden wherever
999
+ # nothing will wake the run when a session reports (a research pass, any run
1000
+ # outside a chat turn or a subagent). A start is refused there too, by
1001
+ # refusal_check before any approval prompt and again in the handler -- but
1002
+ # advertising a tool that can only be refused is the D24 defect, and under
1003
+ # `shell_approval_mode: never` nothing else would stop a pass calling it.
1004
+ # SS14: the three START tools open a session, so their lines are the ones a
1005
+ # reader can click. `shell_output`, `shell_kill` and `shell_input` name a
1006
+ # session they did not create -- arming those would put the same target on
1007
+ # four lines, and on twenty for an interactive session that is typed into
1008
+ # twenty times, which makes "the line that started it" stop meaning
1009
+ # anything.
1010
+ registry.register(ToolSpec("shell_background", shell_sessions.BACKGROUND_TOOL_SCHEMA, shell_sessions.background_run, approval_check=shell._shell_approval_check, approval_notice=shell_sessions.background_notice, refusal_check=shell_sessions.background_refusal, available_check=shell_sessions.available, grant_policy=GRANT_NEVER, budget=BUDGET_IO, rationale_param="rationale", headline_param="command", opens_session=True))
1011
+ registry.register(ToolSpec("shell_monitor", shell_sessions.MONITOR_TOOL_SCHEMA, shell_sessions.monitor_run, approval_check=shell._shell_approval_check, approval_notice=shell_sessions.monitor_notice, refusal_check=shell_sessions.monitor_refusal, available_check=shell_sessions.available, grant_policy=GRANT_NEVER, budget=BUDGET_IO, rationale_param="rationale", headline_param="command", opens_session=True))
1012
+ # Slice 2. Its gate is NOT shell's: `_interactive_approval_check` asks
1013
+ # about the session being opened rather than about its first line, because
1014
+ # the yes covers every line that follows (SS29, SS32). The assert below
1015
+ # holds it to that function by identity, exactly as it holds the three
1016
+ # above to theirs.
1017
+ registry.register(ToolSpec("shell_interactive", shell_sessions.INTERACTIVE_TOOL_SCHEMA, shell_sessions.interactive_run, approval_check=shell._interactive_approval_check, approval_notice=shell_sessions.interactive_notice, refusal_check=shell_sessions.interactive_refusal, available_check=shell_sessions.available, grant_policy=GRANT_NEVER, budget=BUDGET_IO, rationale_param="rationale", headline_param="command", opens_session=True))
1018
+ # Typing into a session is NOT a start, so `opens_session` is False: one
1019
+ # session would otherwise be the target of every line sent to it, which is
1020
+ # the same reason `shell_output` and `shell_kill` are not armed. It keeps
1021
+ # an approval_check because SS29's exception -- a line naming a protected
1022
+ # segment -- still asks, and a control key never does (SS30).
1023
+ registry.register(ToolSpec("shell_input", shell_sessions.INPUT_TOOL_SCHEMA, shell_sessions.input_run, approval_check=shell_sessions.input_approval_check, approval_notice=shell_sessions.input_notice, refusal_check=shell_sessions.input_refusal, available_check=shell_sessions.available, grant_policy=GRANT_NEVER, budget=BUDGET_IO, headline_param="text"))
1024
+ # Reading and stopping need no approval (SS11): they act only on sessions
1025
+ # this conversation started, which someone already approved.
1026
+ registry.register(ToolSpec("shell_sessions", shell_sessions.SESSIONS_TOOL_SCHEMA, shell_sessions.sessions_run, available_check=shell_sessions.available, grant_policy=GRANT_ANYWHERE, budget=BUDGET_IO))
1027
+ registry.register(ToolSpec("shell_output", shell_sessions.OUTPUT_TOOL_SCHEMA, shell_sessions.output_run, available_check=shell_sessions.available, grant_policy=GRANT_ANYWHERE, budget=BUDGET_IO))
1028
+ registry.register(ToolSpec("shell_kill", shell_sessions.KILL_TOOL_SCHEMA, shell_sessions.kill_run, available_check=shell_sessions.available, grant_policy=GRANT_ANYWHERE, budget=BUDGET_IO))
796
1029
  registry.register(ToolSpec("load_skill", load_skill.TOOL_SCHEMA, load_skill.run, available_check=load_skill.has_skills, grant_policy=GRANT_ANYWHERE, budget=BUDGET_IO))
797
1030
  registry.register(ToolSpec("pin", pin.TOOL_SCHEMA, pin.run, available_check=pin.available, grant_policy=GRANT_ANYWHERE, budget=BUDGET_IO))
798
1031
  # §21/D26 restored (#89): the mirror of pin. Same gating posture (ungated,
@@ -860,6 +1093,18 @@ registry.register(ToolSpec(
860
1093
  # names the destination and the size. That is the per-call consent a
861
1094
  # gate is for, which is also why --attended was never the mode at
862
1095
  # issue in #133.
1096
+ #
1097
+ # OFFERED TO NOTHING THAT SHIPS, measured in batch 139 and ruled
1098
+ # deliberate (TECHNICAL_DEBT 83). This is the only
1099
+ # GRANT_SIGNOFF_ONLY registration in the registry, and no agent in
1100
+ # agents/builtin/ declares `write_project_doc` -- so the policy
1101
+ # value above is correct and has no shipped instance. The sign-off
1102
+ # picker is for operator-configured installs: an agent that
1103
+ # declines to narrow `allowed_tools`, or one naming a gated tool
1104
+ # outright. Do not "fix" this by adding the tool to a shipped
1105
+ # agent -- `writer` is the only plausible candidate and its own
1106
+ # file refuses write capability in two places, so that is a
1107
+ # decision reversal and wants its own batch.
863
1108
  grant_policy=GRANT_SIGNOFF_ONLY,
864
1109
  budget=BUDGET_IO))
865
1110
  registry.register(ToolSpec(
@@ -899,8 +1144,80 @@ registry.register(ToolSpec(
899
1144
  # which agent they are authorising.
900
1145
  grant_policy=GRANT_NEVER,
901
1146
  budget=BUDGET_HUMAN,
1147
+ # TECHNICAL_DEBT 13, batch 110. The asymmetry `load_skill` did not
1148
+ # have: with no spawnable agent discovered, this tool's only possible
1149
+ # answer is `Unknown agent`, and until batch 51 shipped two of them
1150
+ # that was every default install. See has_agents for why it reads the
1151
+ # catalog function rather than the roster.
1152
+ available_check=subagent_tool.has_agents,
1153
+ # §47. The only tool that does, so far: the child runs in a thread
1154
+ # of its own, which is what makes `▸ spawn_subagent` a line a
1155
+ # reader can open.
1156
+ opens_thread=True,
1157
+ # §47 slice 8 (NA9). The only tool that declares it, and the reason
1158
+ # the slice exists: a model emitting three spawns in one response
1159
+ # meant three runs one after another, so the parallelism a subagent
1160
+ # swarm is FOR was spent. Safe to declare because everything the
1161
+ # child's run touches was made concurrency-safe first -- the budget's
1162
+ # lock, the serialised question, the per-future authorization -- which
1163
+ # is why this one field is the last line of the section rather than
1164
+ # the first.
1165
+ parallel=True,
902
1166
  ))
903
1167
 
1168
+ # WHICH gate each shell-mode-exempt tool must carry, by identity. A mapping
1169
+ # rather than the single name this started as, because slice 2 added a tool
1170
+ # whose gate is deliberately a different function: `shell_interactive` is
1171
+ # governed by `shell_approval_mode` like the rest, but asks its question
1172
+ # about the SESSION rather than about one command (SS29, SS32). Naming the
1173
+ # expected gate per tool keeps the check as strict as identity ever was and
1174
+ # makes it stricter in one way -- a name added to APPROVAL_BY_SHELL_MODE
1175
+ # with no entry here now fails, where before any shell gate would have done.
1176
+ _SHELL_MODE_GATES = {
1177
+ "shell": shell._shell_approval_check,
1178
+ "shell_background": shell._shell_approval_check,
1179
+ "shell_monitor": shell._shell_approval_check,
1180
+ "shell_interactive": shell._interactive_approval_check,
1181
+ }
1182
+
1183
+
1184
+ def _assert_shell_mode_exemption(tools: dict) -> None:
1185
+ """SS16: every tool exempt from `tool_approvals` carries the shell gate.
1186
+
1187
+ `security.permissions.APPROVAL_BY_SHELL_MODE` is a HOLE in D24's
1188
+ import-time check -- the names in it may omit an approvals field -- and
1189
+ the whole argument for the hole is that `shell_approval_mode` decides
1190
+ their approval instead. That argument is true only while they actually
1191
+ go through that gate, so the exemption is tied to it by IDENTITY here
1192
+ rather than by trusting the registration to have done it: a tool that
1193
+ lost its approval_check, or was given one of its own, would otherwise
1194
+ be a command-running tool with no approval question anywhere and
1195
+ nothing to say so. Raises for D24's reason -- the failure it guards
1196
+ against is invisible at runtime.
1197
+ """
1198
+ broken = []
1199
+ for name in sorted(APPROVAL_BY_SHELL_MODE):
1200
+ spec = tools.get(name)
1201
+ expected = _SHELL_MODE_GATES.get(name)
1202
+ if spec is None:
1203
+ broken.append(f"{name} is not registered")
1204
+ elif expected is None:
1205
+ broken.append(f"{name} has no declared gate in "
1206
+ f"_SHELL_MODE_GATES")
1207
+ elif spec.approval_check is not expected:
1208
+ broken.append(f"{name} does not use {expected.__name__}")
1209
+ if broken:
1210
+ raise RuntimeError(
1211
+ "These tools are exempt from tool_approvals because "
1212
+ "shell_approval_mode is supposed to gate them, and it does not: "
1213
+ f"{broken}. Either register them with the gate "
1214
+ "_SHELL_MODE_GATES names, or take them out of "
1215
+ "security.permissions.APPROVAL_BY_SHELL_MODE and give them a "
1216
+ "tool_approvals field (ROADMAP_v3 §49, SS16)."
1217
+ )
1218
+
1219
+
1220
+ _assert_shell_mode_exemption(registry._tools)
904
1221
  # D24: fail loudly at import if any statically registered tool has no
905
1222
  # declared permission/approval field. Runs here rather than in
906
1223
  # security/permissions.py because that file must not import the registry