@yahyahammad/venastine 0.3.8 → 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 (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2715 -2715
  28. package/core/commands.py +460 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +234 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +458 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +108 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +733 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +295 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
@@ -1,237 +1,237 @@
1
- """
2
- security/permissions.py
3
-
4
- POLICY, not mechanism: "may this tool be called at all?" and "does this
5
- call need a human to approve it?". tools/registry.py owns dispatch
6
- mechanics and is the only caller; tool modules never import this.
7
-
8
- ROADMAP_v2 §15 adds the "stricter wins" rule (D14). Every currently
9
- active layer is consulted -- the global config dataclasses, plus an
10
- optional ToolContext contributed by the active agent (§18) and the skills
11
- it has activated (§19):
12
-
13
- * allow/deny is a logical AND -- a tool is available only if global
14
- policy allows it AND every layer that expresses an opinion allows it.
15
- A globally-disabled tool can never be re-enabled by a context; that
16
- check runs first and unconditionally.
17
- * approval is a logical OR -- approval is required if the global
18
- setting says so, OR the context says so, OR (in the registry) the
19
- tool's own dynamic approval_check says so. A context can therefore
20
- tighten a lenient default but can never loosen a strict one.
21
-
22
- ToolContext is imported for typing only. security/ must not gain a
23
- runtime dependency on tools/ -- the real direction is tools -> security,
24
- and inverting it would create a cycle the moment tools/context.py grows
25
- an import of its own.
26
- """
27
-
28
- from collections.abc import Iterable
29
- from typing import TYPE_CHECKING, Optional
30
-
31
- import config
32
- from security import hosted
33
-
34
- if TYPE_CHECKING: # pragma: no cover - typing only, never imported at runtime
35
- from tools.context import ToolContext
36
-
37
-
38
- # The tools whose approval is decided by `shell_approval_mode` and nothing
39
- # else, so they have a `tool_permissions` field and no `tool_approvals` one.
40
- # `shell` since §28 (G3): a field there was the ratchet, and every answer it
41
- # could give is one the mode already names. The two background-session start
42
- # tools since ROADMAP_v3 §49 (SS16), because they run a command through the
43
- # same gate -- a second switch over it would be G3's ratchet again.
44
- #
45
- # A set named here rather than `name == "shell"` inline, so the exemption
46
- # has one spelling that tests can hold against the registry: an import-time
47
- # check in tools/registry.py requires every name here to be registered with
48
- # shell's own approval check, so the exemption cannot outlive the gate it is
49
- # an exemption FOR.
50
- APPROVAL_BY_SHELL_MODE = frozenset({"shell", "shell_background",
51
- "shell_monitor",
52
- "shell_interactive"})
53
-
54
-
55
- def _default_for_unknown_tool(tool_name: str) -> bool:
56
- """Explicit, named default for tools with no declared field, rather
57
- than letting getattr's fallback decide by omission.
58
-
59
- config.ToolPermissions is a static dataclass with one field per known
60
- tool. MCP tools (§17) are named at connection time
61
- (`mcp__<server>__<tool>`) and can never have a pre-declared field, so
62
- a bare `getattr(..., False)` would deny every one of them forever.
63
- They are allowed here because their real control point is the
64
- server-level trust gate in §17. Anything else unknown is denied --
65
- and for statically registered tools, omission is caught outright by
66
- assert_permissions_declared() at import time (D24), so this branch
67
- should be unreachable for them.
68
- """
69
- return tool_name.startswith("mcp__")
70
-
71
-
72
- def _default_for_unknown_approval(tool_name: str) -> bool:
73
- """Approval counterpart to _default_for_unknown_tool.
74
-
75
- MCP tools default to REQUIRING approval (§17 decision D). They are
76
- allowed by default but not trusted by default, and those are different
77
- questions: an MCP server is third-party code that the model can reach
78
- without the user ever naming it. The project tier is trust-gated
79
- (D17), but a user-level mcp.json auto-connects, and config files grow
80
- entries that installers appended.
81
-
82
- Everything else unknown defaults to not requiring approval, matching
83
- the previous getattr fallback.
84
- """
85
- return tool_name.startswith("mcp__")
86
-
87
-
88
- # Base approval defaults for tools that cannot have a declared field --
89
- # populated at connection time from each MCP server's `autoApprove`.
90
- #
91
- # This exists because the per-server opt-out CANNOT be expressed as a
92
- # ToolSpec.approval_check: registry.approval_needed() ORs those in, and OR
93
- # can only ever tighten. Varying the BASE DEFAULT instead keeps D14's
94
- # one-way ratchet exactly intact -- a context override can still force
95
- # approval back on for an auto-approved server, but nothing can wave a
96
- # call past a gate a stricter layer set.
97
- _dynamic_approval_defaults: dict = {}
98
-
99
-
100
- def set_dynamic_approval_default(tool_name: str, required: bool) -> None:
101
- """Declare the base approval default for a dynamically-named tool."""
102
- _dynamic_approval_defaults[tool_name] = bool(required)
103
-
104
-
105
- def clear_dynamic_approval_defaults(*names: str) -> None:
106
- """Drop defaults for tools that no longer exist. Idempotent, because
107
- disconnect handling can run more than once for the same server. With
108
- no arguments, drops all of them.
109
-
110
- Names are EXACT. This took a PREFIX until §14-§18 review finding f8,
111
- which is the same over-match hazard `mcp__<server>__<tool>` has one
112
- layer up and for the same reason -- neither `__` in a server name nor
113
- `__` in a tool name is illegal. Clearing "mcp__fs__read" by prefix
114
- also cleared "mcp__fs__read_file", silently returning a live tool to
115
- the approval-required default (or, for an auto-approved server, to
116
- requiring approval it was configured not to need).
117
- """
118
- if not names:
119
- _dynamic_approval_defaults.clear()
120
- return
121
- for name in names:
122
- _dynamic_approval_defaults.pop(name, None)
123
-
124
-
125
- def is_tool_allowed(
126
- tool_name: str, context: Optional["ToolContext"] = None
127
- ) -> bool:
128
- """Should this tool be callable at all, given current policy?
129
-
130
- Logical AND across layers. The global check is unconditional and
131
- happens first: no agent or skill context can re-enable a tool that
132
- config has disabled.
133
- """
134
- permissions = config.ToolPermissions()
135
- if not getattr(permissions, tool_name, _default_for_unknown_tool(tool_name)):
136
- return False
137
- # ROADMAP_v3 §79 (HD4). A shared hosted deployment refuses the tools
138
- # that reach the container itself, whatever config.yaml says: every
139
- # visitor shares that container and one Unix user. Second to the global
140
- # check and before any context, for the same reason that check is
141
- # first -- no agent or skill may re-enable what this layer refuses.
142
- # HD11 adds the math tools, unless the bridge verified their confinement.
143
- if tool_name in hosted.refused_tools():
144
- return False
145
- if context is not None and context.allowed_tools is not None:
146
- return tool_name in context.allowed_tools
147
- return True
148
-
149
-
150
- def requires_approval(
151
- tool_name: str, params: dict, context: Optional["ToolContext"] = None
152
- ) -> bool:
153
- """Does this specific call need a human to approve it before running?
154
-
155
- Logical OR across layers, which is what makes approval_overrides a
156
- one-way ratchet: a context entry can ADD an approval requirement, but
157
- an entry of `False` is indistinguishable from the key being absent
158
- and can never remove one. That asymmetry is D14's intent -- do not
159
- "fix" it into a three-state override, or an agent definition (which
160
- may come from a merely-trusted project directory) could wave a call
161
- past a gate the global config deliberately set.
162
-
163
- Note this function covers the global + context layers only. The
164
- tool's own dynamic approval_check is OR'd in by
165
- ToolRegistry.approval_needed(), which is the single source of truth
166
- both dispatch() and the loop's permission bridge call.
167
- """
168
- approvals = config.ToolApprovals()
169
- if hasattr(approvals, tool_name):
170
- tool_level = getattr(approvals, tool_name)
171
- else:
172
- # No declared field: a dynamically-named tool (§17). Its base
173
- # default is whatever was registered for it, falling back to the
174
- # named default rather than to bare False.
175
- tool_level = _dynamic_approval_defaults.get(
176
- tool_name, _default_for_unknown_approval(tool_name)
177
- )
178
- context_level = (
179
- context.approval_overrides.get(tool_name, False)
180
- if context is not None
181
- else False
182
- )
183
- # bool(), because the signature says so and an override is only typed
184
- # where a definition is PARSED (§67 A28): a ToolContext built in code
185
- # with {"web_search": "false"} returned the string 'false' (batch 220,
186
- # #250). Truthiness is unchanged -- that string still TIGHTENS, which is
187
- # the ratchet above working, not a leak -- only the type is.
188
- return bool(tool_level or context_level)
189
-
190
-
191
- def assert_permissions_declared(tool_names: Iterable[str]) -> None:
192
- """D24: every statically registered tool must have a declared permission
193
- field, and -- with one deliberate exception -- a declared approval
194
- field. Raises rather than warning, because the failure
195
- this guards against is invisible at runtime.
196
-
197
- The precedent is `fetch_url`: registered, documented as working, and
198
- denied on every call for its entire life because nobody added the
199
- field. Nothing logged and nothing raised -- the schema was still
200
- advertised to the model, so it kept choosing the tool, and the only
201
- trace was a denial string inside a tool result it then worked around.
202
- Making omission MEANINGFUL for MCP tools (see
203
- _default_for_unknown_tool) is exactly what makes it important that
204
- omission is never accidental for built-in ones.
205
-
206
- The exception is APPROVAL_BY_SHELL_MODE in approvals: those tools'
207
- approval is governed solely by `shell_approval_mode`, and a second
208
- switch there could only force `always` -- exactly what the mode already
209
- says. A test pins the set as the SOLE exemption, and tools/registry.py
210
- requires each name in it to carry shell's own approval check, so a
211
- future omission cannot ride in on it.
212
-
213
- Dynamically-named `mcp__*` tools are exempt by design; they can never
214
- have a declared field. Call this after static registration only.
215
- """
216
- permissions = config.ToolPermissions()
217
- approvals = config.ToolApprovals()
218
- missing = [
219
- name
220
- for name in tool_names
221
- if not name.startswith("mcp__")
222
- and not (hasattr(permissions, name)
223
- and (name in APPROVAL_BY_SHELL_MODE
224
- or hasattr(approvals, name)))
225
- ]
226
- if missing:
227
- raise RuntimeError(
228
- "Tools are registered with no declared permission/approval "
229
- f"field, so they would be silently denied forever: {sorted(missing)}. "
230
- "Add a bool field for each to ToolPermissionsModel and -- "
231
- f"except {sorted(APPROVAL_BY_SHELL_MODE)}, whose approval lives "
232
- "solely in shell_approval_mode -- to ToolApprovalsModel in "
233
- "config_schema.py, and a key for each to tool_permissions "
234
- "(and, with the same exception, tool_approvals) in config.yaml "
235
- "(ROADMAP_v2 §15, D24). The field names live in Python so this "
236
- "check stays a build-time one; the values live in the YAML."
237
- )
1
+ """
2
+ security/permissions.py
3
+
4
+ POLICY, not mechanism: "may this tool be called at all?" and "does this
5
+ call need a human to approve it?". tools/registry.py owns dispatch
6
+ mechanics and is the only caller; tool modules never import this.
7
+
8
+ ROADMAP_v2 §15 adds the "stricter wins" rule (D14). Every currently
9
+ active layer is consulted -- the global config dataclasses, plus an
10
+ optional ToolContext contributed by the active agent (§18) and the skills
11
+ it has activated (§19):
12
+
13
+ * allow/deny is a logical AND -- a tool is available only if global
14
+ policy allows it AND every layer that expresses an opinion allows it.
15
+ A globally-disabled tool can never be re-enabled by a context; that
16
+ check runs first and unconditionally.
17
+ * approval is a logical OR -- approval is required if the global
18
+ setting says so, OR the context says so, OR (in the registry) the
19
+ tool's own dynamic approval_check says so. A context can therefore
20
+ tighten a lenient default but can never loosen a strict one.
21
+
22
+ ToolContext is imported for typing only. security/ must not gain a
23
+ runtime dependency on tools/ -- the real direction is tools -> security,
24
+ and inverting it would create a cycle the moment tools/context.py grows
25
+ an import of its own.
26
+ """
27
+
28
+ from collections.abc import Iterable
29
+ from typing import TYPE_CHECKING, Optional
30
+
31
+ import config
32
+ from security import hosted
33
+
34
+ if TYPE_CHECKING: # pragma: no cover - typing only, never imported at runtime
35
+ from tools.context import ToolContext
36
+
37
+
38
+ # The tools whose approval is decided by `shell_approval_mode` and nothing
39
+ # else, so they have a `tool_permissions` field and no `tool_approvals` one.
40
+ # `shell` since §28 (G3): a field there was the ratchet, and every answer it
41
+ # could give is one the mode already names. The two background-session start
42
+ # tools since ROADMAP_v3 §49 (SS16), because they run a command through the
43
+ # same gate -- a second switch over it would be G3's ratchet again.
44
+ #
45
+ # A set named here rather than `name == "shell"` inline, so the exemption
46
+ # has one spelling that tests can hold against the registry: an import-time
47
+ # check in tools/registry.py requires every name here to be registered with
48
+ # shell's own approval check, so the exemption cannot outlive the gate it is
49
+ # an exemption FOR.
50
+ APPROVAL_BY_SHELL_MODE = frozenset({"shell", "shell_background",
51
+ "shell_monitor",
52
+ "shell_interactive"})
53
+
54
+
55
+ def _default_for_unknown_tool(tool_name: str) -> bool:
56
+ """Explicit, named default for tools with no declared field, rather
57
+ than letting getattr's fallback decide by omission.
58
+
59
+ config.ToolPermissions is a static dataclass with one field per known
60
+ tool. MCP tools (§17) are named at connection time
61
+ (`mcp__<server>__<tool>`) and can never have a pre-declared field, so
62
+ a bare `getattr(..., False)` would deny every one of them forever.
63
+ They are allowed here because their real control point is the
64
+ server-level trust gate in §17. Anything else unknown is denied --
65
+ and for statically registered tools, omission is caught outright by
66
+ assert_permissions_declared() at import time (D24), so this branch
67
+ should be unreachable for them.
68
+ """
69
+ return tool_name.startswith("mcp__")
70
+
71
+
72
+ def _default_for_unknown_approval(tool_name: str) -> bool:
73
+ """Approval counterpart to _default_for_unknown_tool.
74
+
75
+ MCP tools default to REQUIRING approval (§17 decision D). They are
76
+ allowed by default but not trusted by default, and those are different
77
+ questions: an MCP server is third-party code that the model can reach
78
+ without the user ever naming it. The project tier is trust-gated
79
+ (D17), but a user-level mcp.json auto-connects, and config files grow
80
+ entries that installers appended.
81
+
82
+ Everything else unknown defaults to not requiring approval, matching
83
+ the previous getattr fallback.
84
+ """
85
+ return tool_name.startswith("mcp__")
86
+
87
+
88
+ # Base approval defaults for tools that cannot have a declared field --
89
+ # populated at connection time from each MCP server's `autoApprove`.
90
+ #
91
+ # This exists because the per-server opt-out CANNOT be expressed as a
92
+ # ToolSpec.approval_check: registry.approval_needed() ORs those in, and OR
93
+ # can only ever tighten. Varying the BASE DEFAULT instead keeps D14's
94
+ # one-way ratchet exactly intact -- a context override can still force
95
+ # approval back on for an auto-approved server, but nothing can wave a
96
+ # call past a gate a stricter layer set.
97
+ _dynamic_approval_defaults: dict = {}
98
+
99
+
100
+ def set_dynamic_approval_default(tool_name: str, required: bool) -> None:
101
+ """Declare the base approval default for a dynamically-named tool."""
102
+ _dynamic_approval_defaults[tool_name] = bool(required)
103
+
104
+
105
+ def clear_dynamic_approval_defaults(*names: str) -> None:
106
+ """Drop defaults for tools that no longer exist. Idempotent, because
107
+ disconnect handling can run more than once for the same server. With
108
+ no arguments, drops all of them.
109
+
110
+ Names are EXACT. This took a PREFIX until §14-§18 review finding f8,
111
+ which is the same over-match hazard `mcp__<server>__<tool>` has one
112
+ layer up and for the same reason -- neither `__` in a server name nor
113
+ `__` in a tool name is illegal. Clearing "mcp__fs__read" by prefix
114
+ also cleared "mcp__fs__read_file", silently returning a live tool to
115
+ the approval-required default (or, for an auto-approved server, to
116
+ requiring approval it was configured not to need).
117
+ """
118
+ if not names:
119
+ _dynamic_approval_defaults.clear()
120
+ return
121
+ for name in names:
122
+ _dynamic_approval_defaults.pop(name, None)
123
+
124
+
125
+ def is_tool_allowed(
126
+ tool_name: str, context: Optional["ToolContext"] = None
127
+ ) -> bool:
128
+ """Should this tool be callable at all, given current policy?
129
+
130
+ Logical AND across layers. The global check is unconditional and
131
+ happens first: no agent or skill context can re-enable a tool that
132
+ config has disabled.
133
+ """
134
+ permissions = config.ToolPermissions()
135
+ if not getattr(permissions, tool_name, _default_for_unknown_tool(tool_name)):
136
+ return False
137
+ # ROADMAP_v3 §79 (HD4). A shared hosted deployment refuses the tools
138
+ # that reach the container itself, whatever config.yaml says: every
139
+ # visitor shares that container and one Unix user. Second to the global
140
+ # check and before any context, for the same reason that check is
141
+ # first -- no agent or skill may re-enable what this layer refuses.
142
+ # HD11 adds the math tools, unless the bridge verified their confinement.
143
+ if tool_name in hosted.refused_tools():
144
+ return False
145
+ if context is not None and context.allowed_tools is not None:
146
+ return tool_name in context.allowed_tools
147
+ return True
148
+
149
+
150
+ def requires_approval(
151
+ tool_name: str, params: dict, context: Optional["ToolContext"] = None
152
+ ) -> bool:
153
+ """Does this specific call need a human to approve it before running?
154
+
155
+ Logical OR across layers, which is what makes approval_overrides a
156
+ one-way ratchet: a context entry can ADD an approval requirement, but
157
+ an entry of `False` is indistinguishable from the key being absent
158
+ and can never remove one. That asymmetry is D14's intent -- do not
159
+ "fix" it into a three-state override, or an agent definition (which
160
+ may come from a merely-trusted project directory) could wave a call
161
+ past a gate the global config deliberately set.
162
+
163
+ Note this function covers the global + context layers only. The
164
+ tool's own dynamic approval_check is OR'd in by
165
+ ToolRegistry.approval_needed(), which is the single source of truth
166
+ both dispatch() and the loop's permission bridge call.
167
+ """
168
+ approvals = config.ToolApprovals()
169
+ if hasattr(approvals, tool_name):
170
+ tool_level = getattr(approvals, tool_name)
171
+ else:
172
+ # No declared field: a dynamically-named tool (§17). Its base
173
+ # default is whatever was registered for it, falling back to the
174
+ # named default rather than to bare False.
175
+ tool_level = _dynamic_approval_defaults.get(
176
+ tool_name, _default_for_unknown_approval(tool_name)
177
+ )
178
+ context_level = (
179
+ context.approval_overrides.get(tool_name, False)
180
+ if context is not None
181
+ else False
182
+ )
183
+ # bool(), because the signature says so and an override is only typed
184
+ # where a definition is PARSED (§67 A28): a ToolContext built in code
185
+ # with {"web_search": "false"} returned the string 'false' (batch 220,
186
+ # #250). Truthiness is unchanged -- that string still TIGHTENS, which is
187
+ # the ratchet above working, not a leak -- only the type is.
188
+ return bool(tool_level or context_level)
189
+
190
+
191
+ def assert_permissions_declared(tool_names: Iterable[str]) -> None:
192
+ """D24: every statically registered tool must have a declared permission
193
+ field, and -- with one deliberate exception -- a declared approval
194
+ field. Raises rather than warning, because the failure
195
+ this guards against is invisible at runtime.
196
+
197
+ The precedent is `fetch_url`: registered, documented as working, and
198
+ denied on every call for its entire life because nobody added the
199
+ field. Nothing logged and nothing raised -- the schema was still
200
+ advertised to the model, so it kept choosing the tool, and the only
201
+ trace was a denial string inside a tool result it then worked around.
202
+ Making omission MEANINGFUL for MCP tools (see
203
+ _default_for_unknown_tool) is exactly what makes it important that
204
+ omission is never accidental for built-in ones.
205
+
206
+ The exception is APPROVAL_BY_SHELL_MODE in approvals: those tools'
207
+ approval is governed solely by `shell_approval_mode`, and a second
208
+ switch there could only force `always` -- exactly what the mode already
209
+ says. A test pins the set as the SOLE exemption, and tools/registry.py
210
+ requires each name in it to carry shell's own approval check, so a
211
+ future omission cannot ride in on it.
212
+
213
+ Dynamically-named `mcp__*` tools are exempt by design; they can never
214
+ have a declared field. Call this after static registration only.
215
+ """
216
+ permissions = config.ToolPermissions()
217
+ approvals = config.ToolApprovals()
218
+ missing = [
219
+ name
220
+ for name in tool_names
221
+ if not name.startswith("mcp__")
222
+ and not (hasattr(permissions, name)
223
+ and (name in APPROVAL_BY_SHELL_MODE
224
+ or hasattr(approvals, name)))
225
+ ]
226
+ if missing:
227
+ raise RuntimeError(
228
+ "Tools are registered with no declared permission/approval "
229
+ f"field, so they would be silently denied forever: {sorted(missing)}. "
230
+ "Add a bool field for each to ToolPermissionsModel and -- "
231
+ f"except {sorted(APPROVAL_BY_SHELL_MODE)}, whose approval lives "
232
+ "solely in shell_approval_mode -- to ToolApprovalsModel in "
233
+ "config_schema.py, and a key for each to tool_permissions "
234
+ "(and, with the same exception, tool_approvals) in config.yaml "
235
+ "(ROADMAP_v2 §15, D24). The field names live in Python so this "
236
+ "check stays a build-time one; the values live in the YAML."
237
+ )