@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/base.py CHANGED
@@ -1,305 +1,465 @@
1
- from dataclasses import dataclass
2
- from typing import Callable, Iterable, Optional
3
-
4
-
5
- # ROADMAP_v2 §25 (R13). How far approving a tool BY NAME goes -- the
6
- # question asked before any call exists, by the §18 subagent sign-off and
7
- # by the §25 pipeline grant.
8
- #
9
- # Three values rather than two booleans. Booleans can express "an
10
- # unattended pipeline run may pre-grant this, but a human answering in the
11
- # moment may not", which is incoherent -- the pipeline is strictly
12
- # stricter than the sign-off, so the answers form an order.
13
- GRANT_ANYWHERE = "anywhere"
14
- GRANT_SIGNOFF_ONLY = "signoff_only"
15
- GRANT_NEVER = "never"
16
-
17
- GRANT_POLICIES = frozenset({GRANT_ANYWHERE, GRANT_SIGNOFF_ONLY, GRANT_NEVER})
18
-
19
-
20
- # ROADMAP_v2 §31 (H1). What a call to this tool is allowed to COST, and
21
- # therefore which mechanism bounds it. Asked once, at registration, for
22
- # the same reason grant_policy is: the answer is a property of the tool,
23
- # and a layer that infers it from a name or a module is a second source
24
- # of truth that drifts the moment a tool is added.
25
- #
26
- # BUDGET_COMPUTE A pure function of its params. Nothing bounds it from
27
- # the INSIDE -- sympy has no interruption points -- so
28
- # dispatch runs it in a killable subprocess under
29
- # config.TOOL_COMPUTE_TIMEOUT_S (H2).
30
- # BUDGET_IO Carries its own bound already: a request timeout, a
31
- # size check before opening, a sandbox, or an operation
32
- # bounded by construction. NOT wrapped by dispatch,
33
- # because an outer clock over a blocking read can only
34
- # stop WAITING -- mcp_client says so about its own
35
- # backstop, and a mechanism that reports a timeout while
36
- # the work continues is worse than none (H7).
37
- # BUDGET_HUMAN Blocks on a person, or on a sub-run metered
38
- # separately. ask_user waits up to
39
- # ATTENDED_APPROVAL_TIMEOUT_S; spawn_subagent is bounded
40
- # by the child's max_steps and the token budget. A
41
- # compute clock over either would be a bug, not a
42
- # tightening (H8).
43
- BUDGET_COMPUTE = "compute"
44
- BUDGET_IO = "io"
45
- BUDGET_HUMAN = "human"
46
-
47
- BUDGETS = frozenset({BUDGET_COMPUTE, BUDGET_IO, BUDGET_HUMAN})
48
-
49
-
50
- @dataclass
51
- class ToolSpec:
52
- name: str # Tool name
53
- schema: dict # Tool schema
54
- handler: Callable[[dict], dict] # The actual function the tool runs
55
- # Optional path-dependent approval policy. When present, its result is
56
- # OR'd with the generic requires_approval() lookup by
57
- # registry.approval_needed(). Signature: (tool_name, params) -> bool.
58
- # Used by file_ops to auto-approve within WORKSPACE_DIR and require
59
- # user approval outside it, and by shell for Docker-availability.
60
- #
61
- # ROADMAP_v2 §15 changed this from a REPLACEMENT for requires_approval
62
- # to one term of an OR. Before, defining an approval_check made a tool
63
- # invisible to config/context-level approval settings entirely, which
64
- # would have silently voided agent approval_overrides for read/write/
65
- # edit/shell -- the four tools where per-agent tightening matters most.
66
- approval_check: Optional[Callable[[str, dict], bool]] = None
67
- # Optional "is this tool meaningful right now?" predicate, consulted by
68
- # registry.schemas() when deciding what to advertise to the model.
69
- # Signature: () -> bool. Distinct from permissions: the tool is allowed,
70
- # it just has nothing to act on yet (load_skill with an empty catalog).
71
- # Not consulted by dispatch() -- a tool declaring itself unavailable is
72
- # expected to return a clean error if called anyway, and a second denial
73
- # path would only add a worse message.
74
- available_check: Optional[Callable[[], bool]] = None
75
- # Optional "once approved in this run, don't ask again" marker. Only
76
- # "run" is defined; None (the default) means every call is asked about
77
- # independently, which is the existing behaviour for every builtin.
78
- #
79
- # Exists so §18's subagent sign-off is a property of spawn_subagent
80
- # rather than a tool name hard-coded into core/loop.py -- the loop asks
81
- # the registry what a tool's grant scope is, the same way it asks
82
- # whether approval is needed at all. §23's response channel reuses it.
83
- grant_scope: Optional[str] = None
84
- # ROADMAP_v2 §23. Which KIND of question approving this tool asks.
85
- # "approval" (the default) is a yes/no; spawn_subagent sets
86
- # "subagent_signoff", whose answer is the SUBSET of tools the child may
87
- # then use without asking again.
88
- #
89
- # A property of the tool rather than a name hard-coded into
90
- # core/loop.py, for exactly the reason grant_scope is: the loop asks
91
- # the registry what shape of question a tool needs, the same way it
92
- # asks whether it needs one at all.
93
- request_kind: str = "approval"
94
- # Optional extra fields for that question's payload, when the answer
95
- # depends on something only the tool knows. Signature:
96
- # (params, context) -> dict. spawn_subagent uses it to carry the
97
- # candidate tool list, which is agents/manager.py's knowledge and must
98
- # not become the loop's. Mirrors approval_notice exactly.
99
- request_payload: Optional[Callable[[dict, object], dict]] = None
100
- # ROADMAP_v2 §32 (A7). Optional "I would refuse this call anyway"
101
- # pre-flight. Signature: (params, context) -> Optional[str], the
102
- # refusal reason or None. Returning a reason does NOT deny the
103
- # call -- the handler still runs and still refuses; it tells the
104
- # loop not to ASK first.
105
- #
106
- # core/loop.py already establishes this ordering for the case it
107
- # can see on its own: "a context-excluded tool reports the context
108
- # denial instead of prompting and then being denied anyway". That
109
- # reasoning is not specific to contexts, but the loop cannot apply
110
- # it to a condition only the tool knows -- spawn_subagent's
111
- # unknown-agent and depth-limit checks live inside run(), so both
112
- # prompted first and errored second. An unknown name produced a
113
- # sign-off modal with an EMPTY notice and an EMPTY candidate list:
114
- # a question with nothing in it.
115
- #
116
- # A property of the tool rather than a name hard-coded into the
117
- # loop, for exactly the reason grant_scope and request_kind are.
118
- refusal_check: Optional[Callable[[dict, object], Optional[str]]] = None
119
- # Optional extra text shown in the approval prompt, above the params.
120
- # Signature: (params, context) -> str. Lets a tool explain what
121
- # approving actually authorises when the params alone don't say --
122
- # spawn_subagent uses it to list the tools the subagent would then be
123
- # able to run without asking again. Keeps that knowledge in the tool
124
- # instead of teaching the TUI about agents.
125
- approval_notice: Optional[Callable[[dict, object], str]] = None
126
- # ROADMAP_v2 §25 (R13). One of GRANT_ANYWHERE / GRANT_SIGNOFF_ONLY /
127
- # GRANT_NEVER, above.
128
- #
129
- # DISTINCT from registry.grantable(), which is mechanical: does this
130
- # tool decide approval from its PARAMS, in which case a name-level
131
- # answer was never about the call that happens. This field is policy:
132
- # given that consent by name is meaningful, is ONE TICK BEFORE ANY
133
- # CALL EXISTS an acceptable answer, and does that depend on whether a
134
- # human is present? Both callers check both.
135
- #
136
- # None means UNDECLARED, not a default. Omission has to be a
137
- # detectable mistake rather than an inherited answer -- this field
138
- # exists because the previous shape was a denylist in ONE consumer's
139
- # module, so a tool registered after it was written was offered for a
140
- # grant without anybody being asked. That is what happened to
141
- # write_project_doc between §24 and #133.
142
- #
143
- # assert_grant_policy_declared() below makes omission fatal at import,
144
- # the same trade D24 made for permissions.
145
- grant_policy: Optional[str] = None
146
- # ROADMAP_v2 §31 (H1). One of BUDGET_COMPUTE / BUDGET_IO /
147
- # BUDGET_HUMAN, above.
148
- #
149
- # None means UNDECLARED, not a default -- grant_policy's rule one
150
- # question over, for grant_policy's reason. Before §31 every bound in
151
- # the tool layer was per-tool and voluntary: three network tools each
152
- # set their own REQUEST_TIMEOUT_S, `shell` inherited the sandbox's,
153
- # and MCP tools got a two-layer clock in mcp_client -- while the six
154
- # math tools, the only ones that can burn a core indefinitely, had
155
- # none at all (#57). A default here would recreate exactly that, and
156
- # silently: an unwrapped tool looks identical to a correctly bounded
157
- # one from every layer above.
158
- #
159
- # assert_budget_declared() below makes omission fatal at import.
160
- budget: Optional[str] = None
161
- # ROADMAP_v2 §42 (RA2). Which parameter, if any, carries the
162
- # AGENT'S OWN STATED REASON for making this call. `shell` sets
163
- # "rationale"; every other tool leaves it None.
164
- #
165
- # DISPLAY ONLY, and that is the whole contract. The named param is
166
- # rendered on the approval prompt and skipped by the transcript
167
- # digest, and it reaches NOTHING else: not
168
- # `_shell_approval_check`, not `classify_command`, not
169
- # `run_sandboxed`. A self-reported reason is unverifiable by
170
- # construction -- a hijacked agent writes a reassuring one -- so
171
- # letting it touch a decision would be strictly worse than not
172
- # having it. Its value is longitudinal: a thread's worth of stated
173
- # reasons, archived beside the calls, is a drift signal no single
174
- # prompt can give. test_rationale.py pins the invariance by
175
- # asserting on the arguments the classifier RECEIVES, not on the
176
- # decision it returns -- an outcome check would pass for a tool
177
- # that read the field and happened to agree.
178
- #
179
- # NO IMPORT-TIME GUARD, unlike grant_policy and budget. For those,
180
- # None is an unanswered question and silence is the failure; here
181
- # None is the correct answer for every tool but one, so a
182
- # declaration requirement would be noise on twenty-two of them.
183
- rationale_param: Optional[str] = None
184
- # ROADMAP_v2 §46 (EP2). Which parameter, if any, is the SUBJECT of
185
- # the approval question -- the one thing a person must read before
186
- # answering. `shell` sets "command"; every other tool leaves it
187
- # None and its modal is unchanged.
188
- #
189
- # Mechanism, not policy, in the shape rationale_param established
190
- # directly above: the consumer asks the registry rather than testing
191
- # for the literal name `shell`, so no tool name enters core/loop.py
192
- # or tui/screens.py. Two consumers need it -- the TUI modal, which
193
- # PINS it outside the scroll region, and the CLI prompt, which
194
- # leads with it.
195
- #
196
- # DISPLAY ONLY, exactly like rationale_param, and for a different
197
- # reason: this value is ALSO in `params`, which the prompt renders
198
- # whole. Nothing may read it to decide anything, because the thing
199
- # that decides is `classify_command`, and a second reader of the
200
- # same field is how the two came to disagree in #157.
201
- #
202
- # Why it is not just `params["command"]` at the render site: a
203
- # screen that knows a parameter name knows a tool, and the modal is
204
- # shared by web_search, spawn_subagent, the MCP tools and /init's
205
- # confirm. EP1 pins the SUBJECT of the question, whatever the tool
206
- # says that is.
207
- #
208
- # NO IMPORT-TIME GUARD, for rationale_param's reason: None is the
209
- # correct answer for every tool but one.
210
- headline_param: Optional[str] = None
211
-
212
-
213
- def assert_grant_policy_declared(tools: Iterable[str], specs=None) -> None:
214
- """R13: every statically registered tool must declare a grant policy,
215
- and it must be one of the three defined values.
216
-
217
- Raises rather than warning, for D24's reason: the failure this guards
218
- against is invisible at runtime. A tool with no declaration resolves
219
- to GRANT_NEVER (registry.grant_policy), so forgetting the field would
220
- silently drop a tool out of both grant paths with nothing logged --
221
- and a MISSPELLED value would do the same while looking answered,
222
- which is worse. Both are caught here instead.
223
-
224
- The precedent is `fetch_url` under D24: registered, documented as
225
- working, and denied on every call for its entire life because nobody
226
- added a field. The equivalent mistake here is quieter still, because
227
- a tool that is never offered for a grant simply prompts per call --
228
- correct-looking behaviour that hides an unanswered policy question.
229
-
230
- Dynamically-named `mcp__*` tools are exempt by design; they are named
231
- at connection time and can never carry a static declaration.
232
- `mcp_client/registration.py` passes one explicitly anyway, so the
233
- fallback is documentation rather than the live path.
234
- """
235
- specs = specs if specs is not None else tools
236
- undeclared, invalid = [], []
237
- for name in tools:
238
- if name.startswith("mcp__"):
239
- continue
240
- spec = specs.get(name) if hasattr(specs, "get") else None
241
- policy = getattr(spec, "grant_policy", None)
242
- if policy is None:
243
- undeclared.append(name)
244
- elif policy not in GRANT_POLICIES:
245
- invalid.append(f"{name}={policy!r}")
246
- if undeclared or invalid:
247
- raise RuntimeError(
248
- "Tools are registered without a usable grant policy, so the "
249
- "question of whether one tick before any call exists may "
250
- "authorise them was never answered: "
251
- f"undeclared={sorted(undeclared)} invalid={sorted(invalid)}. "
252
- f"Set ToolSpec.grant_policy to one of {sorted(GRANT_POLICIES)} "
253
- "(ROADMAP_v2 §25, R13)."
254
- )
255
-
256
-
257
- def assert_budget_declared(tools: Iterable[str], specs=None,
258
- injectable=None) -> None:
259
- """H1: every statically registered tool must declare a cost class, it
260
- must be one of the three defined values, and a BUDGET_COMPUTE tool
261
- must not also declare an injection.
262
-
263
- Raises rather than warning, and the argument is the one above it,
264
- unchanged: the failure is invisible at runtime. An undeclared tool is
265
- simply not wrapped, which from every layer above looks exactly like a
266
- tool that is correctly bounded somewhere else -- and that is the state
267
- #57 found, where dispatch called every handler directly and nothing
268
- anywhere recorded whether that was intended.
269
-
270
- The third check is not a style rule. BUDGET_COMPUTE is not merely a
271
- policy: it routes the call through a PROCESS boundary, and nothing in
272
- _INJECTABLE_PARAMS survives one. A live ConversationMemory or a
273
- response_channel cannot be pickled, so a tool declaring both would
274
- fail at its first call rather than here. The two fields are checked
275
- together because neither is wrong on its own.
276
-
277
- Dynamically-named `mcp__*` tools are exempt, as they are for
278
- grant_policy and for the same reason -- they are named at connection
279
- time. Their bound is mcp_client's own two-layer clock, and
280
- registration.py passes BUDGET_IO explicitly to say so.
281
- """
282
- specs = specs if specs is not None else tools
283
- injectable = injectable or {}
284
- undeclared, invalid, contradictory = [], [], []
285
- for name in tools:
286
- if name.startswith("mcp__"):
287
- continue
288
- spec = specs.get(name) if hasattr(specs, "get") else None
289
- budget = getattr(spec, "budget", None)
290
- if budget is None:
291
- undeclared.append(name)
292
- elif budget not in BUDGETS:
293
- invalid.append(f"{name}={budget!r}")
294
- elif budget == BUDGET_COMPUTE and injectable.get(name):
295
- contradictory.append(
296
- f"{name} injects {sorted(injectable[name])}")
297
- if undeclared or invalid or contradictory:
298
- raise RuntimeError(
299
- "Tools are registered without a usable cost class, so what a "
300
- "call to them is allowed to cost was never answered: "
301
- f"undeclared={sorted(undeclared)} invalid={sorted(invalid)} "
302
- f"compute-with-injection={sorted(contradictory)}. "
303
- f"Set ToolSpec.budget to one of {sorted(BUDGETS)} "
304
- "(ROADMAP_v2 §31, H1)."
305
- )
1
+ from collections.abc import Callable, Iterable
2
+ from dataclasses import dataclass
3
+ from typing import Optional
4
+
5
+ from pydantic import ValidationError
6
+
7
+ # ROADMAP_v2 §25 (R13). How far approving a tool BY NAME goes -- the
8
+ # question asked before any call exists, by the §18 subagent sign-off and
9
+ # by the §25 pipeline grant.
10
+ #
11
+ # Three values rather than two booleans. Booleans can express "an
12
+ # unattended pipeline run may pre-grant this, but a human answering in the
13
+ # moment may not", which is incoherent -- the pipeline is strictly
14
+ # stricter than the sign-off, so the answers form an order.
15
+ GRANT_ANYWHERE = "anywhere"
16
+ GRANT_SIGNOFF_ONLY = "signoff_only"
17
+ GRANT_NEVER = "never"
18
+
19
+ GRANT_POLICIES = frozenset({GRANT_ANYWHERE, GRANT_SIGNOFF_ONLY, GRANT_NEVER})
20
+
21
+
22
+ # ROADMAP_v2 §47, extended by ROADMAP_v3 §49 (SS14) and again by §55
23
+ # (TR7). What a tool call's line in the transcript OPENS, as
24
+ # `registry.opens()` answers it.
25
+ #
26
+ # Named here beside the flags they are derived from, so the two consumers
27
+ # that carry the answer -- core/replay.py into a stored line, tui/ into a
28
+ # live one -- compare against a constant rather than against a literal
29
+ # each spelled in its own file.
30
+ #
31
+ # OPENS_CALL IS THE FALLBACK AND IS NOT DERIVED FROM A FLAG (§55, TR7).
32
+ # The other two are declared per tool because only some tools start a run
33
+ # or a session; EVERY call has itself, so there is nothing for a ToolSpec
34
+ # to declare and no tool that can decline. That is why `registry.opens()`
35
+ # no longer has an empty answer -- see its docstring for what replaced the
36
+ # falsy-tuple contract.
37
+ OPENS_THREAD = "thread"
38
+ OPENS_SESSION = "session"
39
+ OPENS_CALL = "call"
40
+
41
+
42
+ # ROADMAP_v2 §31 (H1). What a call to this tool is allowed to COST, and
43
+ # therefore which mechanism bounds it. Asked once, at registration, for
44
+ # the same reason grant_policy is: the answer is a property of the tool,
45
+ # and a layer that infers it from a name or a module is a second source
46
+ # of truth that drifts the moment a tool is added.
47
+ #
48
+ # BUDGET_COMPUTE A pure function of its params. Nothing bounds it from
49
+ # the INSIDE -- sympy has no interruption points -- so
50
+ # dispatch runs it in a killable subprocess under
51
+ # config.TOOL_COMPUTE_TIMEOUT_S (H2).
52
+ # BUDGET_IO Carries its own bound already: a request timeout, a
53
+ # size check before opening, a sandbox, or an operation
54
+ # bounded by construction. NOT wrapped by dispatch,
55
+ # because an outer clock over a blocking read can only
56
+ # stop WAITING -- mcp_client says so about its own
57
+ # backstop, and a mechanism that reports a timeout while
58
+ # the work continues is worse than none (H7).
59
+ # BUDGET_HUMAN Blocks on a person, or on a sub-run metered
60
+ # separately. ask_user waits up to
61
+ # ATTENDED_APPROVAL_TIMEOUT_S; spawn_subagent is bounded
62
+ # by the child's max_steps and the token budget. A
63
+ # compute clock over either would be a bug, not a
64
+ # tightening (H8).
65
+ BUDGET_COMPUTE = "compute"
66
+ BUDGET_IO = "io"
67
+ BUDGET_HUMAN = "human"
68
+
69
+ BUDGETS = frozenset({BUDGET_COMPUTE, BUDGET_IO, BUDGET_HUMAN})
70
+
71
+
72
+ # ===========================================================================
73
+ # WHAT A CALLABLE REGISTERED BELOW MAY RAISE -- stated ONCE, here, because it
74
+ # was stated six times elsewhere and all six copies were wrong (batch 146).
75
+ #
76
+ # NO PROVIDER VALIDATES TOOL INPUTS AGAINST THE SCHEMA. `params` is whatever
77
+ # the model emitted: a key may be missing, misspelled, or present with a
78
+ # value of the wrong type. `{"path": null}` is a well-formed JSON object, so
79
+ # the arguments layer passes it and `params.get("path", "")` returns None
80
+ # rather than the default -- the key IS there.
81
+ #
82
+ # A HANDLER'S exception is contained. tools/registry.py wraps the handler
83
+ # call "on purpose", under a comment naming the failure that bought it ("a
84
+ # raising tool used to take the whole run down with it"), and returns
85
+ # `{"error": "<tool> failed: ..."}`. So a bare KeyError in a `run()` has not
86
+ # ended a turn since that landed, and six comments in tools/builtin/ saying
87
+ # it "escapes the loop's ToolCallDenied handler and aborts the whole turn"
88
+ # were describing a tree that no longer existed. The practice they defend is
89
+ # still right, for a reason that survives the containment: an error dict the
90
+ # model can READ beats a generic wrapper it cannot act on, which is what the
91
+ # unknown-name branch in load_skill already does two lines from its comment.
92
+ #
93
+ # A GATE'S exception is NOT contained, and that is the half nobody wrote
94
+ # down. `approval_check` and `refusal_check` run ABOVE the handler boundary;
95
+ # core/loop.py calls `approval_needed` and `refusal_reason` with no `try`,
96
+ # and the `try` around `dispatch()` catches only ToolCallDenied. Sequentially
97
+ # the exception leaves `_run` and ends the turn; in a research pass it
98
+ # propagates into the pipeline handler that records a durable
99
+ # `status='failed'`; in a PARALLEL batch the identical input becomes one
100
+ # call's error result. So the same malformed argument kills a turn alone and
101
+ # is recoverable beside siblings.
102
+ #
103
+ # THEREFORE: a gate must be TOTAL over any JSON object. shell.py has said so
104
+ # at its own gate for a long time -- "Total, like everything else the gate
105
+ # calls: `params['command']` is whatever the model emitted" -- and batch 146
106
+ # found file_ops' two gates were the one exception in the tree, reaching
107
+ # `os.path.join(WORKSPACE_ROOT, None)` before any prompt and any handler.
108
+ #
109
+ # AND A REFUSAL MUST NOT ECHO A VALUE. `invalid_params` below renders the
110
+ # field and the problem and never the value, which is the shape
111
+ # shell_sessions chose first.
112
+ #
113
+ # THE REASON CHANGED IN BATCH 156 AND THE RULE DID NOT. As first written
114
+ # this said the refusal path "is the one result path that does NOT pass
115
+ # through the output redactor", which was true and is the hole batch 156
116
+ # closed in tools/registry.py -- measured, a `ghp_` token the model put in
117
+ # an `agent_name` came back whole. So the sentence that made this rule
118
+ # load-bearing is gone, and the rule stays, because the redactor it now
119
+ # passes through is a PATTERN GUESS rather than a decision procedure:
120
+ # register item 52 measured sixteen of twenty-two credential shapes
121
+ # surviving it, and batch 156 re-confirmed five of those (`github_pat_`,
122
+ # `gho_`, `sk-proj-`, `npm_`, a `Bearer` header) against a `ghp_` control
123
+ # it does catch. A refusal that does not echo cannot leak what no pattern
124
+ # knows; one that echoes is covered only for the shapes somebody thought
125
+ # of. That is defence in depth rather than a belt the registry made
126
+ # redundant -- and it is cheaper here than anywhere else, because the field
127
+ # name is what makes a refusal actionable and the value never was.
128
+ # ===========================================================================
129
+
130
+ def invalid_params(tool_name: str, model, params) -> Optional[str]:
131
+ """Why `params` would not validate against `model`, in one line, or None.
132
+
133
+ For a `refusal_check`, which is what makes a mistyped argument a refusal
134
+ the model can correct instead of an exception above the containment. The
135
+ handler's own `model(**params)` stays where it is: this is the
136
+ pre-approval answer, and base.py's rule for the segment guards applies
137
+ here too -- the check above is not the enforcement.
138
+
139
+ `err['loc']` and `err['msg']` only. `str(e)` would carry `input_value`,
140
+ and the block above says why that matters: this string becomes the tool
141
+ result without passing the redactor.
142
+ """
143
+ if not isinstance(params, dict):
144
+ return f"Invalid arguments for {tool_name}: expected an object."
145
+ try:
146
+ model(**params)
147
+ except ValidationError as e:
148
+ problems = "; ".join(
149
+ f"{'.'.join(str(part) for part in err['loc']) or 'arguments'}: "
150
+ f"{err['msg']}" for err in e.errors())
151
+ return f"Invalid arguments for {tool_name}: {problems}."
152
+ return None
153
+
154
+
155
+ @dataclass
156
+ class ToolSpec:
157
+ name: str # Tool name
158
+ schema: dict # Tool schema
159
+ handler: Callable[[dict], dict] # The actual function the tool runs
160
+ # Optional path-dependent approval policy. When present, its result is
161
+ # OR'd with the generic requires_approval() lookup by
162
+ # registry.approval_needed(). Signature: (tool_name, params) -> bool.
163
+ # Used by file_ops to auto-approve within WORKSPACE_DIR and require
164
+ # user approval outside it, and by shell for Docker-availability.
165
+ #
166
+ # ROADMAP_v2 §15 changed this from a REPLACEMENT for requires_approval
167
+ # to one term of an OR. Before, defining an approval_check made a tool
168
+ # invisible to config/context-level approval settings entirely, which
169
+ # would have silently voided agent approval_overrides for read/write/
170
+ # edit/shell -- the four tools where per-agent tightening matters most.
171
+ #
172
+ # TOTAL over any JSON object -- see "WHAT A CALLABLE REGISTERED BELOW MAY
173
+ # RAISE" at the top of this file. A predicate that cannot answer should
174
+ # answer True: ASKING is the fail-closed direction for this one.
175
+ approval_check: Optional[Callable[[str, dict], bool]] = None
176
+ # Optional "is this tool meaningful right now?" predicate, consulted by
177
+ # registry.schemas() when deciding what to advertise to the model.
178
+ # Signature: () -> bool. Distinct from permissions: the tool is allowed,
179
+ # it just has nothing to act on yet (load_skill with an empty catalog).
180
+ # Not consulted by dispatch() -- a tool declaring itself unavailable is
181
+ # expected to return a clean error if called anyway, and a second denial
182
+ # path would only add a worse message.
183
+ available_check: Optional[Callable[[], bool]] = None
184
+ # Optional "once approved in this run, don't ask again" marker. Only
185
+ # "run" is defined; None (the default) means every call is asked about
186
+ # independently, which is the existing behaviour for every builtin.
187
+ #
188
+ # Exists so §18's subagent sign-off is a property of spawn_subagent
189
+ # rather than a tool name hard-coded into core/loop.py -- the loop asks
190
+ # the registry what a tool's grant scope is, the same way it asks
191
+ # whether approval is needed at all. §23's response channel reuses it.
192
+ grant_scope: Optional[str] = None
193
+ # ROADMAP_v2 §23. Which KIND of question approving this tool asks.
194
+ # "approval" (the default) is a yes/no; spawn_subagent sets
195
+ # "subagent_signoff", whose answer is the SUBSET of tools the child may
196
+ # then use without asking again.
197
+ #
198
+ # A property of the tool rather than a name hard-coded into
199
+ # core/loop.py, for exactly the reason grant_scope is: the loop asks
200
+ # the registry what shape of question a tool needs, the same way it
201
+ # asks whether it needs one at all.
202
+ request_kind: str = "approval"
203
+ # Optional extra fields for that question's payload, when the answer
204
+ # depends on something only the tool knows. Signature:
205
+ # (params, context) -> dict. spawn_subagent uses it to carry the
206
+ # candidate tool list, which is agents/manager.py's knowledge and must
207
+ # not become the loop's. Mirrors approval_notice exactly.
208
+ request_payload: Optional[Callable[[dict, object], dict]] = None
209
+ # ROADMAP_v2 §32 (A7). Optional "I would refuse this call anyway"
210
+ # pre-flight. Signature: (params, context) -> Optional[str], the
211
+ # refusal reason or None. Returning a reason does NOT deny the
212
+ # call -- the handler still runs and still refuses; it tells the
213
+ # loop not to ASK first.
214
+ #
215
+ # core/loop.py already establishes this ordering for the case it
216
+ # can see on its own: "a context-excluded tool reports the context
217
+ # denial instead of prompting and then being denied anyway". That
218
+ # reasoning is not specific to contexts, but the loop cannot apply
219
+ # it to a condition only the tool knows -- spawn_subagent's
220
+ # unknown-agent and depth-limit checks live inside run(), so both
221
+ # prompted first and errored second. An unknown name produced a
222
+ # sign-off modal with an EMPTY notice and an EMPTY candidate list:
223
+ # a question with nothing in it.
224
+ #
225
+ # A property of the tool rather than a name hard-coded into the
226
+ # loop, for exactly the reason grant_scope and request_kind are.
227
+ #
228
+ # TOTAL over any JSON object, like approval_check above it -- see "WHAT A
229
+ # CALLABLE REGISTERED BELOW MAY RAISE" at the top of this file, which is
230
+ # the one copy of why, and `invalid_params` beside it, which is the one
231
+ # copy of how.
232
+ refusal_check: Optional[Callable[[dict, object], Optional[str]]] = None
233
+ # Optional extra text shown in the approval prompt, above the params.
234
+ # Signature: (params, context) -> str. Lets a tool explain what
235
+ # approving actually authorises when the params alone don't say --
236
+ # spawn_subagent uses it to list the tools the subagent would then be
237
+ # able to run without asking again. Keeps that knowledge in the tool
238
+ # instead of teaching the TUI about agents.
239
+ approval_notice: Optional[Callable[[dict, object], str]] = None
240
+ # ROADMAP_v2 §25 (R13). One of GRANT_ANYWHERE / GRANT_SIGNOFF_ONLY /
241
+ # GRANT_NEVER, above.
242
+ #
243
+ # DISTINCT from registry.grantable(), which is mechanical: does this
244
+ # tool decide approval from its PARAMS, in which case a name-level
245
+ # answer was never about the call that happens. This field is policy:
246
+ # given that consent by name is meaningful, is ONE TICK BEFORE ANY
247
+ # CALL EXISTS an acceptable answer, and does that depend on whether a
248
+ # human is present? Both callers check both.
249
+ #
250
+ # None means UNDECLARED, not a default. Omission has to be a
251
+ # detectable mistake rather than an inherited answer -- this field
252
+ # exists because the previous shape was a denylist in ONE consumer's
253
+ # module, so a tool registered after it was written was offered for a
254
+ # grant without anybody being asked. That is what happened to
255
+ # write_project_doc between §24 and #133.
256
+ #
257
+ # assert_grant_policy_declared() below makes omission fatal at import,
258
+ # the same trade D24 made for permissions.
259
+ grant_policy: Optional[str] = None
260
+ # ROADMAP_v2 §47. Whether a call to this tool creates a conversation
261
+ # thread of its own, which is what makes the line that called it
262
+ # something a reader can OPEN.
263
+ #
264
+ # DECLARED HERE rather than by naming `spawn_subagent` at each reader,
265
+ # for grant_policy's reason (R13): two consumers ask this -- core/replay.py
266
+ # and the TUI -- and a string in two places is how they come to
267
+ # disagree about which lines are openable. Defaulted to False, unlike
268
+ # grant_policy, because the safe answer here is "this line opens
269
+ # nothing" and a tool that forgot to say so simply is not clickable.
270
+ opens_thread: bool = False
271
+ # ROADMAP_v3 §49 (SS14). Whether a call to this tool starts a background
272
+ # SESSION, which is the other thing a tool-call line can open.
273
+ #
274
+ # A SECOND FLAG rather than a widened `opens_thread`, because the two
275
+ # answer different questions at press time: a thread is replayed from
276
+ # the archive and a session is read from the manager or rebuilt from
277
+ # the wake rows it wrote. `registry.opens()` is what consumers ask --
278
+ # one question, one answer, so no reader has to know that two flags
279
+ # exist. Defaulted False for `opens_thread`'s reason.
280
+ opens_session: bool = False
281
+ # ROADMAP_v2 §47 slice 8 (NA9). Whether several calls to this tool in
282
+ # ONE model response may run at the same time.
283
+ #
284
+ # DECLARED HERE for `opens_thread`'s reason, one question over: the
285
+ # loop partitions a response by asking, so no tool name appears in
286
+ # core/loop.py -- the same argument grant_scope and request_kind
287
+ # already make. Defaulted to False because the safe answer is "run
288
+ # this one at a time": a tool that has not been examined for thread
289
+ # safety must not be made concurrent by having forgotten to say so.
290
+ #
291
+ # `spawn_subagent` is the only tool that sets it, and NA9's partition
292
+ # keeps every other call strictly sequential in its original position.
293
+ parallel: bool = False
294
+ # ROADMAP_v2 §31 (H1). One of BUDGET_COMPUTE / BUDGET_IO /
295
+ # BUDGET_HUMAN, above.
296
+ #
297
+ # None means UNDECLARED, not a default -- grant_policy's rule one
298
+ # question over, for grant_policy's reason. Before §31 every bound in
299
+ # the tool layer was per-tool and voluntary: three network tools each
300
+ # set their own REQUEST_TIMEOUT_S, `shell` inherited the sandbox's,
301
+ # and MCP tools got a two-layer clock in mcp_client -- while the six
302
+ # math tools, the only ones that can burn a core indefinitely, had
303
+ # none at all (#57). A default here would recreate exactly that, and
304
+ # silently: an unwrapped tool looks identical to a correctly bounded
305
+ # one from every layer above.
306
+ #
307
+ # assert_budget_declared() below makes omission fatal at import.
308
+ budget: Optional[str] = None
309
+ # ROADMAP_v2 §42 (RA2). Which parameter, if any, carries the
310
+ # AGENT'S OWN STATED REASON for making this call. `shell` sets
311
+ # "rationale"; every other tool leaves it None.
312
+ #
313
+ # DISPLAY ONLY, and that is the whole contract. The named param is
314
+ # rendered on the approval prompt and skipped by the transcript
315
+ # digest, and it reaches NOTHING else: not
316
+ # `_shell_approval_check`, not `classify_command`, not
317
+ # `run_sandboxed`. A self-reported reason is unverifiable by
318
+ # construction -- a hijacked agent writes a reassuring one -- so
319
+ # letting it touch a decision would be strictly worse than not
320
+ # having it. Its value is longitudinal: a thread's worth of stated
321
+ # reasons, archived beside the calls, is a drift signal no single
322
+ # prompt can give. test_rationale.py pins the invariance by
323
+ # asserting on the arguments the classifier RECEIVES, not on the
324
+ # decision it returns -- an outcome check would pass for a tool
325
+ # that read the field and happened to agree.
326
+ #
327
+ # NO IMPORT-TIME GUARD, unlike grant_policy and budget. For those,
328
+ # None is an unanswered question and silence is the failure; here
329
+ # None is the correct answer for every tool but one, so a
330
+ # declaration requirement would be noise on twenty-two of them.
331
+ rationale_param: Optional[str] = None
332
+ # ROADMAP_v2 §46 (EP2). Which parameter, if any, is the SUBJECT of
333
+ # the approval question -- the one thing a person must read before
334
+ # answering. `shell` sets "command"; every other tool leaves it
335
+ # None and its modal is unchanged.
336
+ #
337
+ # Mechanism, not policy, in the shape rationale_param established
338
+ # directly above: the consumer asks the registry rather than testing
339
+ # for the literal name `shell`, so no tool name enters core/loop.py
340
+ # or tui/screens.py. Two consumers need it -- the TUI modal, which
341
+ # PINS it outside the scroll region, and the CLI prompt, which
342
+ # leads with it.
343
+ #
344
+ # DISPLAY ONLY, exactly like rationale_param, and for a different
345
+ # reason: this value is ALSO in `params`, which the prompt renders
346
+ # whole. Nothing may read it to decide anything, because the thing
347
+ # that decides is `classify_command`, and a second reader of the
348
+ # same field is how the two came to disagree in #157.
349
+ #
350
+ # Why it is not just `params["command"]` at the render site: a
351
+ # screen that knows a parameter name knows a tool, and the modal is
352
+ # shared by web_search, spawn_subagent, the MCP tools and /init's
353
+ # confirm. EP1 pins the SUBJECT of the question, whatever the tool
354
+ # says that is.
355
+ #
356
+ # NO IMPORT-TIME GUARD, for rationale_param's reason: None is the
357
+ # correct answer for every tool but one.
358
+ headline_param: Optional[str] = None
359
+ # ROADMAP_v3 §81 (IM6). Whether this tool's result carries an IMAGE --
360
+ # which reaches the model only from a provider marked `accepts_images`,
361
+ # and never in a research pass. registry.schemas() drops such a tool
362
+ # unless its caller says images can be delivered in this run.
363
+ #
364
+ # NOT an available_check: that predicate takes no arguments, and this
365
+ # answer depends on the RUN -- its provider and what its thread is --
366
+ # which only the loop holds. DECLARED HERE for `opens_thread`'s reason:
367
+ # the loop asks the registry, so no tool name appears in core/loop.py.
368
+ # Defaulted False, because a tool that returns text is offered wherever
369
+ # it always was.
370
+ returns_images: bool = False
371
+
372
+
373
+ def assert_grant_policy_declared(tools: Iterable[str], specs=None) -> None:
374
+ """R13: every statically registered tool must declare a grant policy,
375
+ and it must be one of the three defined values.
376
+
377
+ Raises rather than warning, for D24's reason: the failure this guards
378
+ against is invisible at runtime. A tool with no declaration resolves
379
+ to GRANT_NEVER (registry.grant_policy), so forgetting the field would
380
+ silently drop a tool out of both grant paths with nothing logged --
381
+ and a MISSPELLED value would do the same while looking answered,
382
+ which is worse. Both are caught here instead.
383
+
384
+ The precedent is `fetch_url` under D24: registered, documented as
385
+ working, and denied on every call for its entire life because nobody
386
+ added a field. The equivalent mistake here is quieter still, because
387
+ a tool that is never offered for a grant simply prompts per call --
388
+ correct-looking behaviour that hides an unanswered policy question.
389
+
390
+ Dynamically-named `mcp__*` tools are exempt by design; they are named
391
+ at connection time and can never carry a static declaration.
392
+ `mcp_client/registration.py` passes one explicitly anyway, so the
393
+ fallback is documentation rather than the live path.
394
+ """
395
+ specs = specs if specs is not None else tools
396
+ undeclared, invalid = [], []
397
+ for name in tools:
398
+ if name.startswith("mcp__"):
399
+ continue
400
+ spec = specs.get(name) if hasattr(specs, "get") else None
401
+ policy = getattr(spec, "grant_policy", None)
402
+ if policy is None:
403
+ undeclared.append(name)
404
+ elif policy not in GRANT_POLICIES:
405
+ invalid.append(f"{name}={policy!r}")
406
+ if undeclared or invalid:
407
+ raise RuntimeError(
408
+ "Tools are registered without a usable grant policy, so the "
409
+ "question of whether one tick before any call exists may "
410
+ "authorise them was never answered: "
411
+ f"undeclared={sorted(undeclared)} invalid={sorted(invalid)}. "
412
+ f"Set ToolSpec.grant_policy to one of {sorted(GRANT_POLICIES)} "
413
+ "(ROADMAP_v2 §25, R13)."
414
+ )
415
+
416
+
417
+ def assert_budget_declared(tools: Iterable[str], specs=None,
418
+ injectable=None) -> None:
419
+ """H1: every statically registered tool must declare a cost class, it
420
+ must be one of the three defined values, and a BUDGET_COMPUTE tool
421
+ must not also declare an injection.
422
+
423
+ Raises rather than warning, and the argument is the one above it,
424
+ unchanged: the failure is invisible at runtime. An undeclared tool is
425
+ simply not wrapped, which from every layer above looks exactly like a
426
+ tool that is correctly bounded somewhere else -- and that is the state
427
+ #57 found, where dispatch called every handler directly and nothing
428
+ anywhere recorded whether that was intended.
429
+
430
+ The third check is not a style rule. BUDGET_COMPUTE is not merely a
431
+ policy: it routes the call through a PROCESS boundary, and nothing in
432
+ _INJECTABLE_PARAMS survives one. A live ConversationMemory or a
433
+ response_channel cannot be pickled, so a tool declaring both would
434
+ fail at its first call rather than here. The two fields are checked
435
+ together because neither is wrong on its own.
436
+
437
+ Dynamically-named `mcp__*` tools are exempt, as they are for
438
+ grant_policy and for the same reason -- they are named at connection
439
+ time. Their bound is mcp_client's own two-layer clock, and
440
+ registration.py passes BUDGET_IO explicitly to say so.
441
+ """
442
+ specs = specs if specs is not None else tools
443
+ injectable = injectable or {}
444
+ undeclared, invalid, contradictory = [], [], []
445
+ for name in tools:
446
+ if name.startswith("mcp__"):
447
+ continue
448
+ spec = specs.get(name) if hasattr(specs, "get") else None
449
+ budget = getattr(spec, "budget", None)
450
+ if budget is None:
451
+ undeclared.append(name)
452
+ elif budget not in BUDGETS:
453
+ invalid.append(f"{name}={budget!r}")
454
+ elif budget == BUDGET_COMPUTE and injectable.get(name):
455
+ contradictory.append(
456
+ f"{name} injects {sorted(injectable[name])}")
457
+ if undeclared or invalid or contradictory:
458
+ raise RuntimeError(
459
+ "Tools are registered without a usable cost class, so what a "
460
+ "call to them is allowed to cost was never answered: "
461
+ f"undeclared={sorted(undeclared)} invalid={sorted(invalid)} "
462
+ f"compute-with-injection={sorted(contradictory)}. "
463
+ f"Set ToolSpec.budget to one of {sorted(BUDGETS)} "
464
+ "(ROADMAP_v2 §31, H1)."
465
+ )