@yahyahammad/venastine 0.2.0 → 0.3.9

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 (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -8,11 +8,11 @@ from __future__ import annotations
8
8
  import logging
9
9
  from typing import Optional
10
10
 
11
- from pydantic import BaseModel, Field, field_validator
12
11
  from ddgs import DDGS
12
+ from pydantic import BaseModel, Field, field_validator
13
13
 
14
14
  from safety.policy_enforcement import is_url_permitted
15
- from tools.builtin._net_common import TTLCache
15
+ from tools.builtin._net_common import MAX_URL_CHARS, ThirdPartyText, TTLCache
16
16
 
17
17
  logger = logging.getLogger(__name__)
18
18
 
@@ -22,6 +22,15 @@ logger = logging.getLogger(__name__)
22
22
  class WebSearchParams(BaseModel):
23
23
  query: str = Field(..., description="Search query", min_length=1, max_length=400)
24
24
  num_results: int = Field(5, ge=1, le=10, description="Number of results to return")
25
+ page: int = Field(
26
+ 1,
27
+ ge=1,
28
+ description=(
29
+ "Which page of results to return (1-based). Use the page named "
30
+ "in a result's message to see further results for the same "
31
+ "query."
32
+ ),
33
+ )
25
34
 
26
35
  @field_validator("query")
27
36
  @classmethod
@@ -51,6 +60,19 @@ class SearchResult(BaseModel):
51
60
  snippet: str
52
61
  published: Optional[str] = None # ddgs's text search doesn't return a
53
62
  # publish date, so this stays None here
63
+ # ROADMAP_v3 §51 (PG8). Whether MAX_SNIPPET_CHARS cut this one, and
64
+ # where the rest is. Before §51 a cut snippet and a short one were
65
+ # indistinguishable, so "the source does not mention X" and "the first
66
+ # 300 characters do not mention X" read the same to the model.
67
+ snippet_truncated: bool = False
68
+ # Batch 156 (PG8's shape, one field over). The snippet had a cap and a
69
+ # flag and the title beside it had neither, so a 5,000-character title
70
+ # went to the model whole while the snippet under it was cut to 300 --
71
+ # measured, in the same result. FLAG AND NO ROUTE, which is the
72
+ # asymmetry `arxiv.py` already argues for the same field: a title past
73
+ # the cap is a malformed result rather than a long one, and the route
74
+ # to the page is the `url` sitting next to it either way.
75
+ title_truncated: bool = False
54
76
 
55
77
 
56
78
  class WebSearchError(Exception):
@@ -62,6 +84,20 @@ class WebSearchError(Exception):
62
84
  # ---- Policy / tuning knobs -------------------------------------------------
63
85
 
64
86
  MAX_SNIPPET_CHARS = 300
87
+
88
+ # Batch 156. 300 is the number `arxiv.py` settled for the same kind of
89
+ # value, measured there over sixty real entries whose longest title was
90
+ # 188 characters. NOT imported from it: two constants with one reason each
91
+ # is the choice `_MAX_AUTHORS` already argues for one file over, and these
92
+ # two bound titles from two different providers.
93
+ #
94
+ # No equivalent measurement was taken for web titles in this batch, and
95
+ # saying so is the honest version. What justifies the number here is that
96
+ # it is the one already settled for a title, and a title is the same kind
97
+ # of value whichever provider hands it over; the HTML spec puts no bound on
98
+ # `<title>` at all.
99
+ MAX_TITLE_CHARS = 300
100
+
65
101
  REQUEST_TIMEOUT_S = 8.0
66
102
  MAX_RETRIES = 2
67
103
  CACHE_TTL_S = 300
@@ -73,45 +109,168 @@ _cache = TTLCache(CACHE_TTL_S)
73
109
 
74
110
  # ---- Provider call ----------------------------------------------------------
75
111
 
76
- def _call_ddgs(query: str, num_results: int) -> list[dict]:
112
+ def _call_ddgs(query: str, num_results: int, page: int = 1) -> list[dict]:
77
113
  """
78
114
  The one function that actually talks to DuckDuckGo. DDGS() is
79
115
  instantiated fresh per call (cheap) and used as a context manager so
80
116
  its underlying HTTP session gets cleaned up automatically afterward.
117
+
118
+ `page` is ROADMAP_v3 §51 (PG3's sibling). The record assumed this tool
119
+ had no paging to expose and only a snippet cap to fix; MEASURED (batch
120
+ 105), `ddgs 9.14.4` takes `page: int = 1` on its search path and
121
+ accepted it live. So the provider implemented paging here too, and this
122
+ tool was spending the parameter on a default.
123
+
124
+ ALSO MEASURED, and the reason the message this feeds is worded the way
125
+ it is: page 2 of a live query OVERLAPPED page 1 by one result. DuckDuckGo's
126
+ paging is not a clean partition the way arXiv's `start` is (measured the
127
+ same day: zero overlap), so a page here is "more results", not "the next
128
+ five distinct results", and nothing downstream may assume otherwise.
81
129
  """
82
130
  with DDGS(timeout=REQUEST_TIMEOUT_S) as ddgs_client:
83
- return ddgs_client.text(query, max_results=num_results)
131
+ return ddgs_client.text(query, max_results=num_results, page=page)
84
132
 
85
133
 
86
134
  def _normalize(raw: list[dict]) -> list[SearchResult]:
135
+ """DDGS's rows as `SearchResult`s, redacted and bounded (§73).
136
+
137
+ EVERY STRING IN HERE WAS WRITTEN BY SOMEBODY ELSE, which is the rule
138
+ PG8/#131 states and the reason all of it goes through one helper now.
139
+ Two things were wrong at once and they interact, so fixing either alone
140
+ would have been worse than fixing neither:
141
+
142
+ REDACT ABOVE THE CUT (RB1, A59). The snippet was cut to 300 characters
143
+ and `registry.dispatch` redacted the piece that was kept. Measured
144
+ (batch 156), a `ghp_` token straddling that cut survived post-hoc
145
+ redaction at 36 of the 39 offsets it could straddle -- the kept prefix
146
+ is not the token, the dropped suffix is gone, and `param_digest`'s
147
+ docstring had already written down why ("truncating first cuts a
148
+ credential below the 20 characters its pattern needs").
149
+
150
+ AND THE CUTS THAT DID NOT EXIST YET. The title had no bound at all, so
151
+ adding one without the ordering above would have MANUFACTURED a second
152
+ straddle site in the field being repaired. Every new cap here is a new
153
+ cut, and every cut needs the redaction above it.
154
+
155
+ TOTAL OVER WHATEVER DDGS RETURNED (A61), which is the half no report
156
+ named. `r.get("title", "(untitled)")` substitutes only for an ABSENT
157
+ key, and `{"title": null}` is a present one -- the lesson
158
+ `tools/base.py` states for tool arguments, arriving from the provider
159
+ end. Measured, a single row with `title: null` raised `ValidationError`
160
+ out of here, which `run` caught as a failed attempt, RETRIED TWICE,
161
+ and then reported as "search failed after 3 attempts" -- ten good
162
+ results lost to one malformed one, plus two pointless re-queries.
163
+ `arxiv._parse_atom_feed` had the identical defect and fixed it in batch
164
+ 117 ("SKIPPED, NOT RAISED ... Raising here aborted the whole search
165
+ over one malformed entry"); the cure was one file over the whole time.
166
+ """
167
+ third = ThirdPartyText("web_search")
87
168
  out: list[SearchResult] = []
88
169
  for r in raw:
89
- url = r.get("href", "")
170
+ if not isinstance(r, dict):
171
+ logger.warning(
172
+ "web_search skipped a result: the provider returned a %s "
173
+ "where a row was expected.", type(r).__name__)
174
+ continue
175
+
176
+ url, withheld = third.url(r.get("href"))
177
+ if withheld:
178
+ # NOT SILENT (#49). The length is the fact; the URL is not
179
+ # echoed, because a URL is one of the things the redactor is
180
+ # looking for userinfo inside.
181
+ logger.warning(
182
+ "web_search dropped a result: its URL is longer than the "
183
+ "%d characters fetch_url accepts, so it is a route this "
184
+ "harness would refuse to take.", MAX_URL_CHARS)
185
+ if url is None:
186
+ # A result is a (title, url, snippet) triple whose url is how
187
+ # the model reaches it. With the url gone there is nothing to
188
+ # cite and nothing to fetch, so this is the same call the
189
+ # policy filter below already makes -- and it is the call
190
+ # `_parse_atom_feed` makes for an entry with no id.
191
+ continue
192
+
90
193
  # `resolve=False` on purpose. This filters results; it does not
91
194
  # fetch them, and a DNS lookup per hit is real latency for a check
92
195
  # whose only failure mode is showing the model a URL that fetch_url
93
- # will refuse anyway. An IP LITERAL is still checked -- a result
196
+ # will refuse anyway. An IP LITERAL is still checked, in every
197
+ # spelling the platform's resolver reads as a number -- a result
94
198
  # pointing straight at 169.254.169.254 is dropped here rather than
95
199
  # offered and then denied (#54).
200
+ #
201
+ # "EVERY SPELLING" SINCE BATCH 213 (#207, register item 53). Batch
202
+ # 156 narrowed this comment to dotted and bracketed literals,
203
+ # because `http://2130706433/`, `http://0x7f.0.0.1/` and
204
+ # `http://0x7F000001/` -- all 127.0.0.1 -- passed: `ipaddress`
205
+ # parses none of them. is_url_permitted now asks the resolver with
206
+ # AI_NUMERICHOST, which reads numbers and looks nothing up, so they
207
+ # are dropped here as fetch_url would refuse them.
208
+ #
209
+ # ABOVE THE POLICY CHECK AND BELOW THE BOUND, deliberately: the
210
+ # string checked here is the string the model is offered, so a
211
+ # redaction that rewrote the host cannot slip past the check that
212
+ # was run on the host before it.
96
213
  if is_url_permitted(url, resolve=False):
97
214
  continue
98
215
 
99
- snippet = (r.get("body") or "")[:MAX_SNIPPET_CHARS]
216
+ title, title_truncated = third.text(r.get("title"), MAX_TITLE_CHARS)
217
+ if title is None:
218
+ title = "(untitled)"
219
+ snippet, snippet_truncated = third.text(
220
+ r.get("body"), MAX_SNIPPET_CHARS)
221
+ if snippet is None:
222
+ snippet = ""
100
223
 
101
224
  out.append(
102
225
  SearchResult(
103
- title=r.get("title", "(untitled)"),
226
+ title=title,
104
227
  url=url,
105
228
  snippet=snippet,
106
229
  published=None,
230
+ snippet_truncated=snippet_truncated,
231
+ title_truncated=title_truncated,
107
232
  )
108
233
  )
234
+ third.report()
109
235
  return out
110
236
 
111
237
 
238
+ def _kept(results: list, asked: int) -> list:
239
+ """`results`, cut to the number the caller asked for (A62).
240
+
241
+ THE SCHEMA ALREADY PROMISED THIS and nothing enforced it.
242
+ `num_results` is advertised `le=10` and passed to the provider as
243
+ `max_results`, and a provider is free to ignore it -- measured (batch
244
+ 156), a call asking for 5 returned every one of 5,000 rows it was
245
+ handed. So this is a documented bound being kept rather than a new
246
+ policy, and it is the LIST axis of the same question batch 156 asked
247
+ of each value: per-value caps multiplied by an unbounded row count are
248
+ not a bound.
249
+
250
+ `_call_ddgs` is where the finding wanted a byte ceiling, and it cannot
251
+ have one: the library buffers the response and owns the socket, so
252
+ nothing above it sees bytes. What this layer CAN bound is what it
253
+ keeps, which is the quantity that reaches the model.
254
+
255
+ NO FLAG, deliberately, where every other cut in this batch gets one.
256
+ Nothing is being withheld from the caller: it asked for `asked`
257
+ results and it is getting `asked` results. The over-delivery is a
258
+ provider fact rather than a truncation, so it goes to the log, where
259
+ the person debugging a provider can see it.
260
+ """
261
+ if len(results) > asked:
262
+ logger.warning(
263
+ "web_search kept %d of %d results: the provider returned more "
264
+ "than the %d asked for.", asked, len(results), asked)
265
+ return results[:asked]
266
+
267
+
112
268
  def run(params: dict) -> dict:
113
269
  parsed = WebSearchParams(**params)
114
- cache_key = f"{parsed.query}|{parsed.num_results}"
270
+ # §51 (PG9). `page` is part of the key for the reason `start` is on the
271
+ # arXiv side: it changes the response, so a key without it serves page 1
272
+ # to every request for page 2 and does it silently.
273
+ cache_key = f"{parsed.query}|{parsed.num_results}|{parsed.page}"
115
274
 
116
275
  results = _cache.get(cache_key)
117
276
  if results is not None:
@@ -121,8 +280,8 @@ def run(params: dict) -> dict:
121
280
  results = []
122
281
  for attempt in range(MAX_RETRIES + 1):
123
282
  try:
124
- raw = _call_ddgs(parsed.query, parsed.num_results)
125
- results = _normalize(raw)
283
+ raw = _call_ddgs(parsed.query, parsed.num_results, parsed.page)
284
+ results = _kept(_normalize(raw), parsed.num_results)
126
285
  _cache.set(cache_key, results)
127
286
  break
128
287
  except Exception as e: # Simpler to try again then elaborate on every error type
@@ -143,9 +302,28 @@ def run(params: dict) -> dict:
143
302
  }
144
303
 
145
304
  if not results:
305
+ if parsed.page > 1:
306
+ return {
307
+ "results": [], "result_count": 0, "page": parsed.page,
308
+ "message": (
309
+ f"No results on page {parsed.page}. The provider "
310
+ f"returned nothing further for this query."
311
+ ),
312
+ }
146
313
  return {"results": [], "result_count": 0, "message": "No results found."}
147
314
 
148
- return {
315
+ out = {
149
316
  "results": [r.model_dump() for r in results],
150
317
  "result_count": len(results),
151
- }
318
+ "page": parsed.page,
319
+ }
320
+ # PG4. DuckDuckGo reports no total, so the honest message names the next
321
+ # page without claiming how many there are -- and says the pages overlap,
322
+ # because measured they do. A full page is the only signal that more may
323
+ # exist; a short one is where the provider stopped.
324
+ if len(results) >= parsed.num_results:
325
+ out["message"] = (
326
+ f"Page {parsed.page}. Use page={parsed.page + 1} for more "
327
+ f"results; pages may overlap by a result or two."
328
+ )
329
+ return out
package/tools/context.py CHANGED
@@ -1,136 +1,159 @@
1
- """
2
- tools/context.py
3
-
4
- ROADMAP_v2 §15. `ToolContext` is the per-run bundle of tool restrictions
5
- contributed by whatever is currently active above the global policy --
6
- an agent (§18), the skills it has activated (§19), or a subagent's
7
- inherited scope. It is data only: the "stricter wins" composition rule
8
- (D14) lives in security/permissions.py, not here.
9
-
10
- Deliberately a leaf module with no project imports. security/permissions.py
11
- type-hints against it under TYPE_CHECKING only, so the existing
12
- `tools -> security` dependency direction is never inverted at runtime.
13
-
14
- A `None` context means "no layer above global policy has an opinion",
15
- which is the state every current production caller is in until §18 lands.
16
- """
17
-
18
- from dataclasses import dataclass, field
19
- from typing import Optional
20
-
21
-
22
- @dataclass
23
- class ToolContext:
24
- """One active restriction layer.
25
-
26
- allowed_tools: None means this layer expresses NO opinion (not "no
27
- tools"). A set restricts to exactly those names. Composition is
28
- intersection -- a layer can only ever narrow what is available,
29
- never widen it past the global policy (D14).
30
- approval_overrides: name -> bool. Only `True` is meaningful: approval
31
- is OR'd across layers, so an entry can add an approval
32
- requirement but can never remove one. See requires_approval().
33
- subagent_depth: incremented by §18's spawn_subagent each time it
34
- builds a child context; the nesting limit is checked against it.
35
- """
36
-
37
- allowed_tools: Optional[set[str]] = None
38
- approval_overrides: dict[str, bool] = field(default_factory=dict)
39
- subagent_depth: int = 0
40
-
41
-
42
- @dataclass
43
- class RunInfo:
44
- """Identity of the enclosing run, for context-aware tool handlers that
45
- spawn further runs (§18's spawn_subagent inherits model / provider /
46
- effort when the agent definition names none of its own).
47
-
48
- Carries no policy -- deliberately separate from ToolContext so a
49
- handler's signature cannot confuse inheritance with restriction.
50
- """
51
-
52
- model: str
53
- provider_name: str
54
- effort: Optional[str] = None
55
- # Tools already signed off for the rest of THIS run (§18 subagent
56
- # sign-off, S1). A RunInfo is built once per _run() call and _run() is
57
- # called once per turn, so run-scope is turn-scope -- which is the
58
- # granularity the sign-off was specified at: approving a spawn covers
59
- # every subagent in that turn, including nested ones, and nothing
60
- # beyond it.
61
- #
62
- # A GRANT, not a policy override. It records that the user answered
63
- # the approval question early, exactly as an approval_callback
64
- # returning True does; it is deliberately not an approval_overrides
65
- # entry, because those OR and can therefore only ever tighten (D14).
66
- granted_tools: set = field(default_factory=set)
67
- # §25: the ceiling on how many granted calls may proceed without being
68
- # asked about. A core.approval.GrantBudget, or None for no ceiling.
69
- #
70
- # Typed as object so this module stays a leaf with no project imports
71
- # (see the module docstring) -- the same reason ToolContext is
72
- # type-hinted from security/permissions.py under TYPE_CHECKING only.
73
- # One budget instance is SHARED by every pass of a pipeline run; a
74
- # per-pass budget would multiply the ceiling by the pass count while
75
- # reading as if it enforced one.
76
- grant_budget: Optional[object] = None
77
- # ROADMAP_v2 §23 (AC1b). Sign-off answers already given in this run,
78
- # keyed by (tool name, SUBJECT). A subject is whatever the question was
79
- # about -- for spawn_subagent, the agent's name -- and is None for every
80
- # tool whose approval is a plain yes/no.
81
- #
82
- # Separate from granted_tools because the two carry different things: a
83
- # granted TOOL is a name approved with no further detail, while a
84
- # sign-off carries the SUBSET the child may use. Merging them would
85
- # force a set to hold both a name and a name-plus-subset.
86
- signoffs: dict = field(default_factory=dict)
87
-
88
- def remember_signoff(self, tool_name: str, subject, subset) -> None:
89
- """Record an answer so the rest of this run need not re-ask.
90
-
91
- A subset of None means the answer carried no detail -- a plain
92
- approval -- and lands in granted_tools exactly as it did before
93
- §23. Anything else is keyed by subject, because the answer was
94
- about that subject and means nothing for another one.
95
- """
96
- if subset is None:
97
- self.granted_tools.add(tool_name)
98
- else:
99
- self.signoffs[(tool_name, subject)] = set(subset)
100
-
101
- def recall_signoff(self, tool_name: str, subject) -> tuple:
102
- """(remembered, subset) for a call this run may already have
103
- answered.
104
-
105
- The subject-keyed memo is checked FIRST. A tool can appear in both
106
- (a pipeline grant names it, and a sign-off answered about one
107
- subject), and the specific answer is the one the user actually
108
- gave about this subject.
109
-
110
- R14: a grant BY NAME may not answer a question that carries a
111
- SUBJECT. J8 rebuilt the memo around (tool, subject) because
112
- approving a spawn of agent `a` had silently covered a later spawn
113
- of `b`; the grant branch below kept answering both, because it
114
- never looked at the subject at all:
115
-
116
- granted_tools={'spawn_subagent'}
117
- recall_signoff('spawn_subagent', 'agent-a') -> (True, None)
118
- recall_signoff('spawn_subagent', 'agent-b') -> (True, None)
119
- recall_signoff('spawn_subagent', <anything>) -> (True, None)
120
-
121
- -- J8's pre-fix behaviour, reached through the grant rather than
122
- the memo. A name-level answer is about the TOOL; a subject-carrying
123
- question is about one agent, and the two are not the same consent.
124
-
125
- Belt and braces after R13 made spawn_subagent GRANT_NEVER, since
126
- that is the only tool supplying a subject today: this holds for a
127
- hand-built or stale RunInfo, and for any later tool that carries
128
- one. `subject is None` for every other tool, so nothing else
129
- changes behaviour.
130
- """
131
- key = (tool_name, subject)
132
- if key in self.signoffs:
133
- return True, self.signoffs[key]
134
- if subject is None and tool_name in self.granted_tools:
135
- return True, None
136
- return False, None
1
+ """
2
+ tools/context.py
3
+
4
+ ROADMAP_v2 §15. `ToolContext` is the per-run bundle of tool restrictions
5
+ contributed by whatever is currently active above the global policy --
6
+ an agent (§18), the skills it has activated (§19), or a subagent's
7
+ inherited scope. It is data only: the "stricter wins" composition rule
8
+ (D14) lives in security/permissions.py, not here.
9
+
10
+ Deliberately a leaf module with no project imports. security/permissions.py
11
+ type-hints against it under TYPE_CHECKING only, so the existing
12
+ `tools -> security` dependency direction is never inverted at runtime.
13
+
14
+ A `None` context means "no layer above global policy has an opinion",
15
+ which is the state every current production caller is in until §18 lands.
16
+ """
17
+
18
+ from dataclasses import dataclass, field
19
+ from typing import Optional
20
+
21
+
22
+ @dataclass
23
+ class ToolContext:
24
+ """One active restriction layer.
25
+
26
+ allowed_tools: None means this layer expresses NO opinion (not "no
27
+ tools"). A set restricts to exactly those names. Composition is
28
+ intersection -- a layer can only ever narrow what is available,
29
+ never widen it past the global policy (D14).
30
+ approval_overrides: name -> bool. Only `True` is meaningful: approval
31
+ is OR'd across layers, so an entry can add an approval
32
+ requirement but can never remove one. See requires_approval().
33
+ subagent_depth: incremented by §18's spawn_subagent each time it
34
+ builds a child context; the nesting limit is checked against it.
35
+ spawn_targets: None means this layer expresses NO opinion about WHICH
36
+ agents may be spawned -- not "none of them", exactly as for
37
+ allowed_tools above. A set restricts spawn_subagent to those
38
+ agent names, and composes the same way: intersection, so a layer
39
+ can only ever narrow the roster it inherited.
40
+
41
+ SEPARATE FROM allowed_tools because they answer different
42
+ questions. `allowed_tools` decides whether this run may spawn AT
43
+ ALL; this decides who it may spawn, and the two failure modes are
44
+ not the same one. C6 caps a child's tools by intersecting them
45
+ with the parent's, which turns "a parent that should not delegate
46
+ this work" into "a child that quietly cannot do it" -- `plan`
47
+ spawning `build` returned a build with no `write` or `edit` and
48
+ no way for either side to tell. An agent that must not delegate
49
+ a kind of work should be refused, not narrowed.
50
+ """
51
+
52
+ allowed_tools: Optional[set[str]] = None
53
+ approval_overrides: dict[str, bool] = field(default_factory=dict)
54
+ subagent_depth: int = 0
55
+ spawn_targets: Optional[set[str]] = None
56
+
57
+
58
+ @dataclass
59
+ class RunInfo:
60
+ """Identity of the enclosing run, for context-aware tool handlers that
61
+ spawn further runs (§18's spawn_subagent inherits model / provider /
62
+ effort when the agent definition names none of its own).
63
+
64
+ Carries no policy -- deliberately separate from ToolContext so a
65
+ handler's signature cannot confuse inheritance with restriction.
66
+ """
67
+
68
+ model: str
69
+ provider_name: str
70
+ effort: Optional[str] = None
71
+ # Tools already signed off for the rest of THIS run (§18 subagent
72
+ # sign-off, S1). A RunInfo is built once per _run() call and _run() is
73
+ # called once per turn, so run-scope is turn-scope -- which is the
74
+ # granularity the sign-off was specified at: approving a spawn covers
75
+ # every subagent in that turn, including nested ones, and nothing
76
+ # beyond it.
77
+ #
78
+ # A GRANT, not a policy override. It records that the user answered
79
+ # the approval question early, exactly as an approval_callback
80
+ # returning True does; it is deliberately not an approval_overrides
81
+ # entry, because those OR and can therefore only ever tighten (D14).
82
+ granted_tools: set = field(default_factory=set)
83
+ # §25: the ceiling on how many granted calls may proceed without being
84
+ # asked about. A core.approval.GrantBudget, or None for no ceiling.
85
+ #
86
+ # Typed as object so this module stays a leaf with no project imports
87
+ # (see the module docstring) -- the same reason ToolContext is
88
+ # type-hinted from security/permissions.py under TYPE_CHECKING only.
89
+ # One budget instance is SHARED by every pass of a pipeline run; a
90
+ # per-pass budget would multiply the ceiling by the pass count while
91
+ # reading as if it enforced one.
92
+ grant_budget: Optional[object] = None
93
+ # ROADMAP_v2 §23 (AC1b). Sign-off answers already given in this run,
94
+ # keyed by (tool name, SUBJECT). A subject is whatever the question was
95
+ # about -- for spawn_subagent, the agent's name -- and is None for every
96
+ # tool whose approval is a plain yes/no.
97
+ #
98
+ # Separate from granted_tools because the two carry different things: a
99
+ # granted TOOL is a name approved with no further detail, while a
100
+ # sign-off carries the SUBSET the child may use. Merging them would
101
+ # force a set to hold both a name and a name-plus-subset.
102
+ signoffs: dict = field(default_factory=dict)
103
+ # ROADMAP_v3 §81 (IM6). Whether an image in a tool result can reach the
104
+ # model in this run: the provider is marked `accepts_images` and the
105
+ # thread is not a research pass. Computed ONCE, by the loop, and read
106
+ # twice -- by the schema list, to leave `view_image` out, and by the
107
+ # handler, to refuse a call made anyway -- so the two cannot disagree.
108
+ # False by default: a RunInfo built anywhere else delivers no images.
109
+ images: bool = False
110
+
111
+ def remember_signoff(self, tool_name: str, subject, subset) -> None:
112
+ """Record an answer so the rest of this run need not re-ask.
113
+
114
+ A subset of None means the answer carried no detail -- a plain
115
+ approval -- and lands in granted_tools exactly as it did before
116
+ §23. Anything else is keyed by subject, because the answer was
117
+ about that subject and means nothing for another one.
118
+ """
119
+ if subset is None:
120
+ self.granted_tools.add(tool_name)
121
+ else:
122
+ self.signoffs[(tool_name, subject)] = set(subset)
123
+
124
+ def recall_signoff(self, tool_name: str, subject) -> tuple:
125
+ """(remembered, subset) for a call this run may already have
126
+ answered.
127
+
128
+ The subject-keyed memo is checked FIRST. A tool can appear in both
129
+ (a pipeline grant names it, and a sign-off answered about one
130
+ subject), and the specific answer is the one the user actually
131
+ gave about this subject.
132
+
133
+ R14: a grant BY NAME may not answer a question that carries a
134
+ SUBJECT. J8 rebuilt the memo around (tool, subject) because
135
+ approving a spawn of agent `a` had silently covered a later spawn
136
+ of `b`; the grant branch below kept answering both, because it
137
+ never looked at the subject at all:
138
+
139
+ granted_tools={'spawn_subagent'}
140
+ recall_signoff('spawn_subagent', 'agent-a') -> (True, None)
141
+ recall_signoff('spawn_subagent', 'agent-b') -> (True, None)
142
+ recall_signoff('spawn_subagent', <anything>) -> (True, None)
143
+
144
+ -- J8's pre-fix behaviour, reached through the grant rather than
145
+ the memo. A name-level answer is about the TOOL; a subject-carrying
146
+ question is about one agent, and the two are not the same consent.
147
+
148
+ Belt and braces after R13 made spawn_subagent GRANT_NEVER, since
149
+ that is the only tool supplying a subject today: this holds for a
150
+ hand-built or stale RunInfo, and for any later tool that carries
151
+ one. `subject is None` for every other tool, so nothing else
152
+ changes behaviour.
153
+ """
154
+ key = (tool_name, subject)
155
+ if key in self.signoffs:
156
+ return True, self.signoffs[key]
157
+ if subject is None and tool_name in self.granted_tools:
158
+ return True, None
159
+ return False, None