@yahyahammad/venastine 0.1.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 (130) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +249 -93
  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 +280 -23
  12. package/agents/tui_commands.py +31 -21
  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 +256 -0
  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 +1249 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +1735 -959
  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 +2566 -1353
  38. package/core/memory.py +482 -370
  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 +315 -167
  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 +1672 -198
  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 +21 -14
  70. package/package.json +303 -73
  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 +149 -100
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +1082 -682
  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 +1338 -1005
  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 +374 -29
  118. package/tui/app.py +5281 -397
  119. package/tui/app.tcss +290 -9
  120. package/tui/commands.py +26 -61
  121. package/tui/diffs.py +286 -265
  122. package/tui/history.py +128 -0
  123. package/tui/hosted_driver.py +102 -0
  124. package/tui/markdown.py +1329 -0
  125. package/tui/meters.py +364 -0
  126. package/tui/screens.py +346 -92
  127. package/tui/themes.py +599 -366
  128. package/tui/widgets.py +2673 -116
  129. package/SECURITY.md +0 -88
  130. package/THIRD_PARTY_NOTICES.md +0 -100
package/tools/registry.py CHANGED
@@ -21,34 +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
- from agents import subagent_tool
47
76
 
48
77
  logger = logging.getLogger(__name__)
49
78
 
50
79
  if TYPE_CHECKING: # pragma: no cover - typing only
51
- from tools.context import ToolContext, RunInfo
80
+ from tools.context import RunInfo, ToolContext
52
81
 
53
82
  # Handler parameter names dispatch() will inject, by signature inspection
54
83
  # (ROADMAP_v2 §18). A tool handler that declares one of these receives the
@@ -68,6 +97,27 @@ _INJECTABLE_PARAMS = (
68
97
  # comment above anticipated a third name arriving without touching
69
98
  # dispatch() again; this is it.
70
99
  "memory",
100
+ # Batch 59: the core/agent_activity.py sink, for spawn_subagent. A
101
+ # shell watching the agent stack has to learn about a run that
102
+ # happens INSIDE a tool call, which is the one place a LoopEvent
103
+ # cannot reach -- see that module for why. Injected rather than
104
+ # threaded through params because it is a run-scoped value, exactly
105
+ # like response_channel beside it.
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",
71
121
  )
72
122
 
73
123
 
@@ -111,14 +161,24 @@ class ToolRegistry:
111
161
  self._tools.pop(tool_name, None)
112
162
  self._injectable.pop(tool_name, None)
113
163
 
114
- def _advertised(self, name: str, spec, context) -> bool:
164
+ def _advertised(self, name: str, spec, context,
165
+ images: bool = False) -> bool:
115
166
  """The two §15 filters, shared by schemas() and
116
167
  headless_hidden(): policy allowability plus the tool's own
117
- "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."""
118
176
  if not is_tool_allowed(name, context):
119
177
  return False
120
178
  if spec.available_check is not None and not spec.available_check():
121
179
  return False
180
+ if spec.returns_images and not images:
181
+ return False
122
182
  return True
123
183
 
124
184
  def _answered_by_grant(self, tool_name: str, granted) -> bool:
@@ -178,6 +238,7 @@ class ToolRegistry:
178
238
  self, tool_name: str, context: Optional["ToolContext"] = None,
179
239
  callable_only: bool = False,
180
240
  granted: Optional[set] = None,
241
+ images: bool = False,
181
242
  ) -> bool:
182
243
  """Whether schemas() would advertise this tool right now.
183
244
 
@@ -205,7 +266,7 @@ class ToolRegistry:
205
266
  spec = self._tools.get(tool_name)
206
267
  if spec is None:
207
268
  return False
208
- if not self._advertised(tool_name, spec, context):
269
+ if not self._advertised(tool_name, spec, context, images):
209
270
  return False
210
271
  return not (callable_only
211
272
  and self.approval_needed(tool_name, {}, context)
@@ -215,6 +276,7 @@ class ToolRegistry:
215
276
  self, context: Optional["ToolContext"] = None,
216
277
  callable_only: bool = False,
217
278
  granted: Optional[set] = None,
279
+ images: bool = False,
218
280
  ) -> list[dict]:
219
281
  """What gets sent to the LLM's `tools` parameter each call.
220
282
 
@@ -241,6 +303,9 @@ class ToolRegistry:
241
303
  * granted (§25 R15) -- names a pre-flight grant already answered
242
304
  for. Those stay advertised even with no channel, because the
243
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.
244
309
 
245
310
  WHAT callable_only GUARANTEES, stated because the converse does not
246
311
  hold and #158 is what assuming it costs: it means SOME call shape
@@ -255,11 +320,12 @@ class ToolRegistry:
255
320
  """
256
321
  return [spec.schema for name, spec in self._tools.items()
257
322
  if self.is_advertised(name, context, callable_only,
258
- granted)]
323
+ granted, images)]
259
324
 
260
325
  def headless_hidden(
261
326
  self, context: Optional["ToolContext"] = None,
262
327
  granted: Optional[set] = None,
328
+ images: bool = False,
263
329
  ) -> list[str]:
264
330
  """Names that would be advertised with a response_channel but
265
331
  are dropped by schemas(callable_only=True) -- i.e. advertised yet
@@ -280,8 +346,28 @@ class ToolRegistry:
280
346
  # disagrees with itself.
281
347
  return [
282
348
  name for name in self._tools
283
- if self.is_advertised(name, context, False, granted)
284
- 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)
285
371
  ]
286
372
 
287
373
  def approval_needed(
@@ -486,6 +572,103 @@ class ToolRegistry:
486
572
  key = self.rationale_param(tool_name)
487
573
  return param_digest(params, omit=(key,) if key else ())
488
574
 
575
+ def call_links(self, tool_name: str, params) -> tuple:
576
+ """The untruncated values behind that summary (batch 65).
577
+
578
+ `call_digest` caps a value at 60 characters, which is shorter
579
+ than most real URLs, so the transcript resolves a truncated
580
+ span against these to arm a ctrl+click. Redacted, and with any
581
+ value the redactor rewrote dropped -- `redacted_values` says
582
+ why a target may never come from the raw params.
583
+
584
+ THE SAME `omit`, which is the whole reason this sits here
585
+ rather than being called direct (Section 42, RA3): the two
586
+ halves describe one call, and a candidate drawn from a
587
+ parameter the line does not show is a target no span could
588
+ resolve to.
589
+ """
590
+ key = self.rationale_param(tool_name)
591
+ return redacted_values(params, omit=(key,) if key else ())
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
+
489
672
  def request_kind(self, tool_name: str) -> str:
490
673
  """Which kind of question approving this tool asks (§23).
491
674
 
@@ -573,6 +756,9 @@ class ToolRegistry:
573
756
  response_channel=None,
574
757
  signoff=None,
575
758
  memory=None,
759
+ activity=None,
760
+ call_id=None,
761
+ cancel=None,
576
762
  ) -> dict:
577
763
  # Unknown-tool guard: ValueError, deliberately NOT ToolCallDenied.
578
764
  # The two exception types separate "you misnamed it" from "policy
@@ -610,7 +796,33 @@ class ToolRegistry:
610
796
  if refused is not None:
611
797
  logger.info("%s refused before approval: %s",
612
798
  tool_name, refused)
613
- 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})
614
826
 
615
827
  spec = self._tools[tool_name]
616
828
 
@@ -645,6 +857,9 @@ class ToolRegistry:
645
857
  "response_channel": response_channel,
646
858
  "signoff": signoff,
647
859
  "memory": memory,
860
+ "activity": activity,
861
+ "call_id": call_id,
862
+ "cancel": cancel,
648
863
  }
649
864
  injected = {p: available[p] for p in self._injectable.get(tool_name, ())}
650
865
  try:
@@ -659,8 +874,12 @@ class ToolRegistry:
659
874
  # The branch is HERE, inside the containment try and at the
660
875
  # one place a handler is ever invoked, rather than inside the
661
876
  # six tools. A tool that isolated itself could not be called
662
- # 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
663
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.)
664
883
  #
665
884
  # `injected` is not passed: nothing in _INJECTABLE_PARAMS
666
885
  # survives a process boundary, and assert_budget_declared
@@ -758,13 +977,55 @@ registry.register(ToolSpec("geometry", geometry.TOOL_SCHEMA, geometry.run, grant
758
977
  # pre-approval, so no human is asked a question the tool would refuse
759
978
  # anyway. The handlers re-test -- the refusal_check is the
760
979
  # prompt-suppression half, not the enforcement.
761
- 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))
762
- 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))
763
- 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))
764
987
  # §28: approval_notice carries the capability profile into the prompt.
765
988
  # The command text is already in the params; what it does not show is
766
989
  # WHERE it runs, and "cat /etc/shadow" does not look like a host read.
767
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))
768
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))
769
1030
  registry.register(ToolSpec("pin", pin.TOOL_SCHEMA, pin.run, available_check=pin.available, grant_policy=GRANT_ANYWHERE, budget=BUDGET_IO))
770
1031
  # §21/D26 restored (#89): the mirror of pin. Same gating posture (ungated,
@@ -832,6 +1093,18 @@ registry.register(ToolSpec(
832
1093
  # names the destination and the size. That is the per-call consent a
833
1094
  # gate is for, which is also why --attended was never the mode at
834
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.
835
1108
  grant_policy=GRANT_SIGNOFF_ONLY,
836
1109
  budget=BUDGET_IO))
837
1110
  registry.register(ToolSpec(
@@ -871,8 +1144,80 @@ registry.register(ToolSpec(
871
1144
  # which agent they are authorising.
872
1145
  grant_policy=GRANT_NEVER,
873
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,
874
1166
  ))
875
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)
876
1221
  # D24: fail loudly at import if any statically registered tool has no
877
1222
  # declared permission/approval field. Runs here rather than in
878
1223
  # security/permissions.py because that file must not import the registry