@yahyahammad/venastine 0.1.0

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 (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
@@ -0,0 +1,461 @@
1
+ """
2
+ tools/builtin/shell.py
3
+
4
+ Shell execution tool (ROADMAP §7). Runs commands in the detected shell
5
+ (bash on Linux/macOS, PowerShell on Windows) through the sandbox module
6
+ (security/sandbox.py).
7
+
8
+ SANDBOX MODEL (ROADMAP_v2 §46 moved one tier of this):
9
+ Almost everything runs in Docker. The one exception is HOST_READ --
10
+ a read-only command from config.INERT_COMMANDS whose argument
11
+ resolves OUTSIDE the workspace -- which runs as a host subprocess
12
+ because the file it names is one no container can see. It always
13
+ requires approval, and the prompt names the resolved binary.
14
+
15
+ INERT (every argument inside the workspace) used to take that same
16
+ host path, on the argument that a read-only command needs no
17
+ isolation. §46 (EP5) moved it into the container: it is the tier the
18
+ gate AUTO-APPROVES, and on Windows `ls`/`cat`/`grep` have no native
19
+ binary, so the host path was resolving them off the user's PATH and
20
+ executing whichever POSIX toolchain some other product had installed.
21
+ Inside the container they are the pinned image's coreutils. It falls
22
+ back to the host when Docker is down, which changes nothing about the
23
+ approval answer (see security/sandbox.containment_for) and is
24
+ reported to the model as `ran_on: "host"`.
25
+
26
+ Non-inert commands go through Docker (strong isolation) or the
27
+ explicit subprocess fallback (weak isolation, requires
28
+ ALLOW_INSECURE_SANDBOX_FALLBACK=True).
29
+
30
+ EVERY result carries `ran_on` and `tier` (EP4). The human was always
31
+ told where a command would run; the model never was, and it is the
32
+ one that writes the user an answer about the output.
33
+
34
+ APPROVAL MODEL (ROADMAP_v2 §28):
35
+ config.SHELL_APPROVAL_MODE is the gate -- "always", "tiered" or
36
+ "never" -- and ToolApprovals.shell is the RATCHET above it: True
37
+ forces "always", and can never loosen (D14).
38
+
39
+ Under "tiered", the command is classified ONCE
40
+ (security/sandbox.classify_command) into a capability set, and the
41
+ generic rule in security/capability.auto_approved decides. The same
42
+ profile is then handed to run_sandboxed, so the thing that was
43
+ approved is the thing that runs.
44
+
45
+ What this replaced: a five-step ladder whose bottom four steps could
46
+ only return False on the shipped config flags, making the whole check
47
+ a pass-through for ToolApprovals.shell. Audit #157 is what that cost
48
+ -- `cat ~/.aws/credentials` classified as "inert", ran on the HOST,
49
+ and was never asked about.
50
+
51
+ TOCTOU safety: run() probes Docker once and passes the result to
52
+ run_sandboxed(). If Docker was available during approval but is now
53
+ down, and the fallback would have required approval, run() returns
54
+ an error instead of silently downgrading.
55
+
56
+ FILE ACCESS:
57
+ The sandbox restricts filesystem access to the workspace (Docker
58
+ volume mount / fallback cwd). Output files generated by sandboxed
59
+ commands appear in the workspace seamlessly.
60
+ """
61
+
62
+ from __future__ import annotations
63
+
64
+ import logging
65
+ import os
66
+ import re
67
+ import shutil
68
+
69
+ from pydantic import BaseModel, Field
70
+
71
+ import config
72
+ from security import capability, posture
73
+ from security.capability import UNAVAILABLE, UNCONTAINED, auto_approved
74
+ from security.protected_paths import PROTECTED_SEGMENTS, protected_segment
75
+ from security.sandbox import (
76
+ HOST_READ,
77
+ INERT,
78
+ SandboxUnavailable,
79
+ _is_inert,
80
+ classify_command,
81
+ containment_for,
82
+ detect_shell,
83
+ is_docker_available,
84
+ run_sandboxed,
85
+ )
86
+
87
+ logger = logging.getLogger(__name__)
88
+
89
+ # Validated at IMPORT, so a typo in a security setting is a startup
90
+ # failure rather than a policy that quietly means something else. Same
91
+ # posture as D24's assert_permissions_declared, applied to a value.
92
+ #
93
+ # It used to say "re-checked per call as well, because a test or a runtime
94
+ # edit can change it after this line has run", and that sentence described
95
+ # a test seam and an attack in the same breath: `config.SHELL_APPROVAL_MODE
96
+ # = "never"` was one attribute assignment, from anywhere in the process,
97
+ # and the gate followed it. §40 (UN1) binds the value once into
98
+ # `security.posture`, and `_shell_approval_check` reads it from there.
99
+ #
100
+ # THIS line still reads `config` directly, and deliberately (UN2). It
101
+ # validates the CONSTANT A HUMAN WROTE -- a typo check, not a decision --
102
+ # and it runs at import, which is before `main()` has folded in the
103
+ # command line. Reading the posture here would mark it bound and make
104
+ # `apply_cli()` raise on every launch, because importing this module is
105
+ # how the registry is built. The rule the guard enforces: **no module may
106
+ # read the posture at import time**, pinned by
107
+ # test_posture.py::test_no_module_reads_the_posture_at_import.
108
+ capability.validate_mode(config.SHELL_APPROVAL_MODE,
109
+ "config.SHELL_APPROVAL_MODE")
110
+
111
+ # Compute the shell name once at import time to avoid blocking on
112
+ # subprocess probes every time the schema is accessed. On Windows this
113
+ # probes pwsh/powershell; a failure falls back to a static label.
114
+ try:
115
+ _SHELL_DISPLAY = detect_shell()
116
+ except Exception:
117
+ _SHELL_DISPLAY = "auto-detected"
118
+
119
+
120
+ # ---------------------------------------------------------------------------
121
+ # ---- Schema ---------------------------------------------------------------
122
+ # ---------------------------------------------------------------------------
123
+
124
+ class ShellParams(BaseModel):
125
+ command: str = Field(
126
+ ...,
127
+ min_length=1,
128
+ description=(
129
+ "Shell command to execute. WHERE it runs depends on its "
130
+ "arguments, and the result tells you which happened: read "
131
+ "`ran_on` before drawing any conclusion about the machine "
132
+ "you are on. A read-only command (ls, cat, grep, etc.) "
133
+ "whose arguments all resolve INSIDE the workspace runs in "
134
+ "the container. The same command with an argument OUTSIDE "
135
+ "the workspace runs ON THE HOST, with the user's own file "
136
+ "access and the host's own PATH -- it is not sandboxed, and "
137
+ "what it reads is the real machine, not the container. "
138
+ "Everything else runs in the container, with the workspace "
139
+ f"mounted at /workspace. Interpreted by {_SHELL_DISPLAY}."
140
+ ),
141
+ )
142
+ rationale: str = Field(
143
+ default="",
144
+ description=(
145
+ "Why you are running this command, right now, in a sentence "
146
+ "or two. Say what you are trying to learn or change and "
147
+ "what it is for -- not what the command does, which the "
148
+ "reader can see. This is shown to the user on the approval "
149
+ "prompt and recorded with the call; it never affects whether "
150
+ "the command is allowed or how it runs."
151
+ ),
152
+ )
153
+
154
+
155
+ TOOL_SCHEMA = {
156
+ "name": "shell",
157
+ "description": (
158
+ "Execute a shell command. Commands run inside a Docker "
159
+ "container with the workspace mounted at /workspace -- EXCEPT "
160
+ "a read-only command with an argument outside the workspace, "
161
+ "which runs on the HOST with the user's own file access "
162
+ "because the container cannot see those files. The result "
163
+ "carries `ran_on` ('container' or 'host') and `tier`; a "
164
+ "command that ran on the host tells you about the user's real "
165
+ "machine, so do not describe its output as the sandbox's. "
166
+ f"Shell: {_SHELL_DISPLAY}. Output is truncated at "
167
+ f"{config.MAX_READ_CHARS} characters."
168
+ ),
169
+ "input_schema": ShellParams.model_json_schema(),
170
+ }
171
+
172
+ # §42 (RA4). ADVERTISED as required, TOLERATED when absent -- and the
173
+ # asymmetry is deliberate rather than an oversight to tidy up.
174
+ #
175
+ # The schema is what the model reads, so `required` is where the ask
176
+ # belongs: a rationale nobody asks for is supplied inconsistently, and
177
+ # a drift signal with unknown coverage is not a signal. But
178
+ # `ShellParams` keeps its default, because approval is obtained BEFORE
179
+ # dispatch: a hard requirement would show the user a modal, take their
180
+ # yes, and only then fail validation. That is the burn-a-turn class --
181
+ # a human decision spent on an outcome already fixed -- and §32 A7
182
+ # rejected it for a condition the tool could see, which this is.
183
+ #
184
+ # So an omission costs nothing and is VISIBLE: the prompt says
185
+ # "(none given)", which is itself the observation. A silent gap would
186
+ # not be.
187
+ TOOL_SCHEMA["input_schema"]["required"] = ["command", "rationale"]
188
+
189
+
190
+ # ---------------------------------------------------------------------------
191
+ # ---- Approval check -------------------------------------------------------
192
+ # ---------------------------------------------------------------------------
193
+
194
+
195
+ def _profile_and_containment(command: str):
196
+ """Classify *command* and work out what will contain it.
197
+
198
+ One helper for both the gate and the prompt so they cannot describe
199
+ the same call differently -- which is the failure #157 came from,
200
+ with `_is_inert` consulted twice for two different questions.
201
+ """
202
+ profile = classify_command(command, config.WORKSPACE_DIR)
203
+ # Docker is probed only when the answer depends on it. HOST_READ is
204
+ # UNCONTAINED whatever Docker is doing -- it names a file outside
205
+ # the workspace, which no container can show it -- so it still
206
+ # returns without paying for a `docker info` that costs up to its
207
+ # 10s timeout on an unresponsive daemon.
208
+ #
209
+ # INERT no longer qualifies (§46, EP5): it runs in the container
210
+ # when there is one, so its containment now depends on the probe.
211
+ # The cost is bounded rather than per-call -- `is_docker_available`
212
+ # is lru_cached for the process, measured at 0.43s once.
213
+ if profile.tier == HOST_READ:
214
+ return profile, containment_for(profile, docker_available=False)
215
+ return profile, containment_for(profile, is_docker_available())
216
+
217
+
218
+ def _command_touches_protected(command: str) -> str | None:
219
+ """The protected segment a command's tokens name, or None.
220
+
221
+ Raw whitespace-split tokens, per Q1/Q5: for an INERT command
222
+ ``command.split()`` IS the executed argument list, and EP5 runs that
223
+ tier as argv with NO shell -- so there is no glob or variable
224
+ expansion between this check and what executes, and a token check is
225
+ sound exactly where it matters. A token counts when the segment
226
+ appears as a component of its TEXT -- or of the tail after its first
227
+ ``=``, the one split _escapes_workspace permits itself (hole 1:
228
+ ``--path=.venastine/settings.json`` reads whole as one component
229
+ glued to a flag) -- or of its realpath against WORKSPACE_DIR, which
230
+ catches `..` travel, an absolute path from anywhere, and a
231
+ case-spelling Windows realpath normalises.
232
+
233
+ Totality is the approval gate's, and this runs inside it (Q3): a
234
+ non-string command answers None, and a token whose realpath cannot
235
+ RESOLVE answers None for that token -- the tier machinery fails
236
+ closed on exactly those values, so an unresolvable reference is
237
+ already on a path that asks. What this deliberately does NOT do is
238
+ parse. A token like ``.ven*/settings.json`` carries no literal
239
+ segment and reaches no answer here (G2 -- a classifier that learned
240
+ shell syntax would be a parser whose bugs auto-approve). That is why
241
+ the consumer is an always-ASK trigger and never a deny: what slips
242
+ past a token check still lands in front of a human with the full
243
+ command text.
244
+ """
245
+ if not isinstance(command, str):
246
+ return None
247
+ for token in command.split():
248
+ candidates = [token]
249
+ if "=" in token:
250
+ candidates.append(token.split("=", 1)[1])
251
+ for candidate in candidates:
252
+ for part in re.split(r"[\\/]", candidate):
253
+ if part in PROTECTED_SEGMENTS:
254
+ return part
255
+ try:
256
+ resolved = os.path.realpath(
257
+ os.path.join(config.WORKSPACE_DIR, candidate))
258
+ except (OSError, ValueError):
259
+ continue
260
+ segment = protected_segment(resolved)
261
+ if segment is not None:
262
+ return segment
263
+ return None
264
+
265
+
266
+ def _shell_approval_check(tool_name: str, params: dict) -> bool:
267
+ """Whether this shell call needs a human to say yes (ROADMAP_v2 §28).
268
+
269
+ Reads top to bottom as the policy it is:
270
+
271
+ 1. ToolApprovals.shell is the RATCHET. True forces "always",
272
+ whatever the mode says, so a config or an agent override can
273
+ still only tighten (D14).
274
+ 2. The mode answers outright unless it is "tiered".
275
+ 3. A command naming a protected path segment
276
+ (security.protected_paths.PROTECTED_SEGMENTS) always asks --
277
+ before the fallback opt-in and the capability rule can answer
278
+ for it. The file tools DENY such a path outright; the shell
279
+ only asks, because a command is free text and the token check
280
+ refuses to parse it (G2), so what slips past the check still
281
+ meets a human. Behind step 2 deliberately: mode "never" is a
282
+ documented opt-out of ALL approval, and it already answers
283
+ "auto-approve" for a host read of /etc/shadow.
284
+ 4. AUTO_APPROVE_SANDBOX_FALLBACK is applied HERE, visibly, rather
285
+ than passed into the generic rule to be honoured out of sight.
286
+ It is the user's own opt-in to an isolation level the harness
287
+ has already told them is weak -- and it sits BELOW the
288
+ protected-segment check, so one opt-in cannot cover the
289
+ directory the ro-mount exists to keep commands out of.
290
+ 5. Otherwise the capability rule decides.
291
+
292
+ The return is `not auto_approved(...)` -- this function answers "must
293
+ someone be asked", the rule answers "is this covered". Two names for
294
+ opposite polarities of one question, and inverting them by accident
295
+ is a silent auto-approve, so the negation stays on one line where it
296
+ can be read.
297
+ """
298
+ approvals = config.ToolApprovals()
299
+ if getattr(approvals, tool_name, False):
300
+ return True
301
+
302
+ active = posture.current()
303
+ mode = capability.validate_mode(active.shell_approval_mode,
304
+ "config.SHELL_APPROVAL_MODE")
305
+ if mode == capability.ALWAYS:
306
+ return True
307
+ if mode == capability.NEVER:
308
+ return False
309
+
310
+ command = params.get("command", "")
311
+ profile, containment = _profile_and_containment(command)
312
+
313
+ # No backend can run this, so there is nothing to approve. NOT the
314
+ # same as auto_approved() answering False, which means ASK -- the two
315
+ # polarities meet here and only here. run_sandboxed still raises
316
+ # SandboxUnavailable with the instructions; asking first would spend
317
+ # a human decision on an outcome that is already fixed, which is the
318
+ # burn-a-turn class, and it is what the pre-§28 check did too.
319
+ #
320
+ # Read above the fallback branch, which it can never co-occur with --
321
+ # UNCONTAINED and UNAVAILABLE are different answers -- so moving it
322
+ # changes nothing there and lets the protected-segment check sit
323
+ # before both.
324
+ if containment == UNAVAILABLE:
325
+ return False
326
+
327
+ # Step 3: a protected segment always asks, whatever the sandbox says.
328
+ segment = _command_touches_protected(command)
329
+ if segment is not None:
330
+ return True
331
+
332
+ # The pre-§28 steps 4 and 5, preserved exactly. For a non-inert tier,
333
+ # UNCONTAINED can only mean "Docker is down AND the insecure fallback
334
+ # is enabled" -- that is what containment_for computed -- so this
335
+ # reads the answer already in hand instead of re-deriving it from two
336
+ # more config reads and a second Docker probe.
337
+ if (profile.tier not in (INERT, HOST_READ)
338
+ and containment == UNCONTAINED
339
+ and active.auto_approve_fallback):
340
+ return False
341
+
342
+ return not auto_approved(profile, containment)
343
+
344
+
345
+ def _shell_approval_notice(params: dict, _context=None) -> str:
346
+ """What the person answering the prompt is being asked to allow.
347
+
348
+ Wired through ToolSpec.approval_notice, which core/loop.py already
349
+ renders above the params. The command is right there in the params,
350
+ so what this adds is the part the command text does NOT show: where
351
+ it will run. "cat /etc/shadow" does not look like a host read until
352
+ someone tells you the inert path is a host subprocess.
353
+ """
354
+ command = params.get("command", "")
355
+ profile, containment = _profile_and_containment(command)
356
+ where = {
357
+ "contained": "in a Docker container, workspace mounted at /workspace",
358
+ "uncontained": "on the HOST, with your own file access",
359
+ "unavailable": "nowhere -- no sandbox backend is available",
360
+ }.get(containment, containment)
361
+ notice = f"{profile.tier}: {profile.reason}. Runs {where}."
362
+ binary = _resolved_binary(command) if containment == UNCONTAINED else ""
363
+ if binary:
364
+ notice += f" Binary resolves to {binary}."
365
+ segment = _command_touches_protected(command)
366
+ if segment is not None:
367
+ # Why an INERT read is prompting at all: the tier alone would
368
+ # look like a false positive to the person answering.
369
+ notice += (f" It names {segment}/, a protected path that always "
370
+ "requires approval.")
371
+ return notice
372
+
373
+
374
+ def _resolved_binary(command) -> str:
375
+ """The absolute path the first word will actually execute as, on a
376
+ run that is about to happen on the HOST (§46, EP8).
377
+
378
+ Named on the prompt because "runs on the host" understates it on
379
+ Windows. `ls`, `cat` and `grep` have no native Windows binary, so
380
+ the inert path resolves them off the user's PATH -- and on the
381
+ machine where this was found, `cat` was
382
+ `...\\AppData\\Local\\hermes\\git\\usr\\bin\\cat.exe`, a POSIX
383
+ toolchain shipped by unrelated software. `_is_inert` rejects a
384
+ path-qualified binary (`./ls`) precisely so a planted one cannot be
385
+ NAMED; PATH lookup reaches the same place from the other side, and
386
+ the harness does not get to choose what is on it.
387
+
388
+ Disclosure, not enforcement: the containment argument that lets
389
+ this path run at all is unchanged, and HOST_READ always asks a
390
+ human anyway. What changes is that the human is told which
391
+ executable they are approving.
392
+
393
+ Total, like everything else the gate calls: `command` arrives from
394
+ `registry.approval_needed` as whatever the model emitted, and
395
+ `shutil.which` on a non-string raises.
396
+ """
397
+ if not isinstance(command, str) or not command.strip():
398
+ return ""
399
+ try:
400
+ return shutil.which(command.split()[0]) or ""
401
+ except (OSError, ValueError):
402
+ return ""
403
+
404
+
405
+ # ---------------------------------------------------------------------------
406
+ # ---- Tool handler ---------------------------------------------------------
407
+ # ---------------------------------------------------------------------------
408
+
409
+
410
+ def run(params: dict) -> dict:
411
+ # `parsed.rationale` is deliberately never read below. It is shown
412
+ # to a person and archived with the call; it has no part in what
413
+ # runs or in whether it is allowed to (§42, RA2).
414
+ parsed = ShellParams(**params)
415
+
416
+ # Probe Docker once for this execution — the result is threaded
417
+ # into run_sandboxed to eliminate the TOCTOU gap where Docker
418
+ # status changes between the approval check and execution.
419
+ docker_up = is_docker_available()
420
+
421
+ # TOCTOU safety net: if the approval check auto-approved because
422
+ # Docker was available at that time, but Docker is now down and
423
+ # we'd use the fallback, check whether the fallback would have
424
+ # required approval that was never given.
425
+ if not docker_up and not _is_inert(parsed.command):
426
+ approvals = config.ToolApprovals()
427
+ base_needs_approval = getattr(approvals, "shell", False)
428
+ # Read here rather than passed in from the approval check: §40
429
+ # makes the two reads the SAME object for the life of the process,
430
+ # so re-reading cannot reintroduce the TOCTOU gap this block
431
+ # exists to close. Before §40 it could have.
432
+ active = posture.current()
433
+ if (
434
+ not base_needs_approval
435
+ and active.allow_insecure_fallback
436
+ and not active.auto_approve_fallback
437
+ ):
438
+ return {
439
+ "error": (
440
+ "Docker became unavailable after the approval check. "
441
+ "The insecure subprocess fallback requires explicit "
442
+ "per-run approval (AUTO_APPROVE_SANDBOX_FALLBACK is "
443
+ "False). Please retry — the approval prompt will "
444
+ "appear this time."
445
+ ),
446
+ }
447
+
448
+ try:
449
+ return run_sandboxed(
450
+ command=parsed.command,
451
+ workspace_dir=config.WORKSPACE_DIR,
452
+ docker_available=docker_up,
453
+ # §28: the SAME classification the approval check made, so
454
+ # routing cannot disagree with the decision to allow it.
455
+ profile=classify_command(parsed.command, config.WORKSPACE_DIR),
456
+ )
457
+ except SandboxUnavailable as e:
458
+ return {"error": str(e)}
459
+ except Exception as e:
460
+ logger.exception("shell tool failed")
461
+ return {"error": f"Shell execution failed: {e}"}
@@ -0,0 +1,119 @@
1
+ """
2
+ tools/builtin/symbolic_math.py
3
+
4
+ Algebra, calculus, trigonometry, and arithmetic -- all of these operate on
5
+ the same substrate (a single SymPy expression), so they share one tool
6
+ rather than being split further. Everything stays exact/symbolic (e.g.
7
+ Rational(1,3) not 0.333...) except the explicit "evaluate" operation,
8
+ which forces a numeric approximation.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from typing import Literal, Optional
14
+
15
+ import sympy
16
+ from pydantic import BaseModel, Field
17
+
18
+ from tools.builtin._math_common import safe_parse, serialize, MathParseError
19
+
20
+ _OPERATIONS = Literal[
21
+ "evaluate", "simplify", "expand", "factor",
22
+ "solve", "differentiate", "integrate", "limit", "series",
23
+ ]
24
+
25
+
26
+ class SymbolicMathParams(BaseModel):
27
+ operation: _OPERATIONS = Field(..., description="Which operation to perform")
28
+ expression: str = Field(
29
+ ...,
30
+ description=(
31
+ "The math expression using standard notation, e.g. "
32
+ "'x**2 + 3*x - 4', 'sin(x)*cos(x)', or 'x**2 - 4 = 0' for solve."
33
+ ),
34
+ )
35
+ variable: str = Field("x", description="The variable to solve for / differentiate / integrate / expand around")
36
+ equations: Optional[list[str]] = Field(
37
+ None, description="For 'solve' with a system: additional equations alongside `expression`"
38
+ )
39
+ order: int = Field(1, ge=1, description="Order of differentiation, or number of terms for series expansion")
40
+ lower_bound: Optional[str] = Field(None, description="Lower bound for a definite integral")
41
+ upper_bound: Optional[str] = Field(None, description="Upper bound for a definite integral")
42
+ point: Optional[str] = Field(None, description="Point to evaluate a limit or series expansion at, e.g. '0' or 'oo'")
43
+ direction: Literal["+", "-", "+-"] = Field("+", description="Direction for limit evaluation")
44
+ precision: int = Field(15, ge=1, le=50, description="Significant digits for the 'evaluate' operation")
45
+
46
+
47
+ TOOL_SCHEMA = {
48
+ "name": "symbolic_math",
49
+ "description": (
50
+ "Perform exact symbolic algebra, calculus, and trigonometry: "
51
+ "simplify, expand, factor, solve equations (single or systems), "
52
+ "differentiate, integrate (definite or indefinite), evaluate "
53
+ "limits, expand series, or numerically evaluate an expression. "
54
+ "Results are exact (e.g. fractions, symbolic constants) unless "
55
+ "'evaluate' is used."
56
+ ),
57
+ "input_schema": SymbolicMathParams.model_json_schema(),
58
+ }
59
+
60
+
61
+ def run(params: dict) -> dict:
62
+ parsed = SymbolicMathParams(**params)
63
+
64
+ try:
65
+ var = sympy.Symbol(parsed.variable)
66
+ expr = safe_parse(parsed.expression, symbols=[parsed.variable])
67
+ op = parsed.operation
68
+
69
+ if op == "evaluate":
70
+ result = expr.evalf(parsed.precision)
71
+
72
+ elif op == "simplify":
73
+ result = sympy.simplify(expr)
74
+
75
+ elif op == "expand":
76
+ result = sympy.expand(expr)
77
+
78
+ elif op == "factor":
79
+ result = sympy.factor(expr)
80
+
81
+ elif op == "differentiate":
82
+ result = sympy.diff(expr, var, parsed.order)
83
+
84
+ elif op == "integrate":
85
+ if parsed.lower_bound is not None and parsed.upper_bound is not None:
86
+ lo = safe_parse(parsed.lower_bound)
87
+ hi = safe_parse(parsed.upper_bound)
88
+ result = sympy.integrate(expr, (var, lo, hi))
89
+ else:
90
+ result = sympy.integrate(expr, var)
91
+
92
+ elif op == "limit":
93
+ point = safe_parse(parsed.point) if parsed.point is not None else 0
94
+ result = sympy.limit(expr, var, point, dir=parsed.direction)
95
+
96
+ elif op == "series":
97
+ point = safe_parse(parsed.point) if parsed.point is not None else 0
98
+ result = expr.series(var, point, parsed.order).removeO()
99
+
100
+ elif op == "solve":
101
+ if parsed.equations:
102
+ extra = [safe_parse(e, symbols=[parsed.variable]) for e in parsed.equations]
103
+ all_exprs = [expr] + extra
104
+ symbols_found = sorted(
105
+ set().union(*[e.free_symbols for e in all_exprs]), key=str
106
+ )
107
+ result = sympy.solve(all_exprs, symbols_found)
108
+ else:
109
+ result = sympy.solve(expr, var)
110
+
111
+ else:
112
+ return {"error": f"Unknown operation: {op}"}
113
+
114
+ except MathParseError as e:
115
+ return {"error": str(e)}
116
+ except Exception as e:
117
+ return {"error": f"Computation failed: {e}"}
118
+
119
+ return {"result": serialize(result), "operation": op}