@yahyahammad/venastine 0.1.0 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +249 -93
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +280 -23
  12. package/agents/tui_commands.py +31 -21
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +256 -0
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1249 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +1735 -959
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +2566 -1353
  38. package/core/memory.py +482 -370
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +315 -167
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1672 -198
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +21 -14
  70. package/package.json +303 -73
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +149 -100
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +1082 -682
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +1338 -1005
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +374 -29
  118. package/tui/app.py +5281 -397
  119. package/tui/app.tcss +290 -9
  120. package/tui/commands.py +26 -61
  121. package/tui/diffs.py +286 -265
  122. package/tui/history.py +128 -0
  123. package/tui/hosted_driver.py +102 -0
  124. package/tui/markdown.py +1329 -0
  125. package/tui/meters.py +364 -0
  126. package/tui/screens.py +346 -92
  127. package/tui/themes.py +599 -366
  128. package/tui/widgets.py +2673 -116
  129. package/SECURITY.md +0 -88
  130. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -6,7 +6,9 @@ Shell execution tool (ROADMAP §7). Runs commands in the detected shell
6
6
  (security/sandbox.py).
7
7
 
8
8
  SANDBOX MODEL (ROADMAP_v2 §46 moved one tier of this):
9
- Almost everything runs in Docker. The one exception is HOST_READ --
9
+ Almost everything runs in a container -- Docker's, or Podman's when
10
+ Docker cannot run one (ROADMAP_v3 §49, SS22; the approval notice names
11
+ which). The one exception is HOST_READ --
10
12
  a read-only command from config.INERT_COMMANDS whose argument
11
13
  resolves OUTSIDE the workspace -- which runs as a host subprocess
12
14
  because the file it names is one no container can see. It always
@@ -23,7 +25,7 @@ SANDBOX MODEL (ROADMAP_v2 §46 moved one tier of this):
23
25
  approval answer (see security/sandbox.containment_for) and is
24
26
  reported to the model as `ran_on: "host"`.
25
27
 
26
- Non-inert commands go through Docker (strong isolation) or the
28
+ Non-inert commands go through the container (strong isolation) or the
27
29
  explicit subprocess fallback (weak isolation, requires
28
30
  ALLOW_INSECURE_SANDBOX_FALLBACK=True).
29
31
 
@@ -31,17 +33,26 @@ SANDBOX MODEL (ROADMAP_v2 §46 moved one tier of this):
31
33
  told where a command would run; the model never was, and it is the
32
34
  one that writes the user an answer about the output.
33
35
 
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).
36
+ APPROVAL MODEL (ROADMAP_v2 §28, amended by §48):
37
+ config.SHELL_APPROVAL_MODE is the gate -- "always", "tiered",
38
+ "contained" or "never" -- and it is the ONLY gate: there is no second
39
+ switch that can disagree with it (D14's one-way tightening for shell
40
+ lives in the agent's `approval_overrides`, which reach the same OR
41
+ below).
38
42
 
39
- Under "tiered", the command is classified ONCE
43
+ Under "tiered" and "contained", the command is classified ONCE
40
44
  (security/sandbox.classify_command) into a capability set, and the
41
45
  generic rule in security/capability.auto_approved decides. The same
42
46
  profile is then handed to run_sandboxed, so the thing that was
43
47
  approved is the thing that runs.
44
48
 
49
+ The two differ in one capability (§48, CE1/CE2). "tiered" asks about
50
+ anything that may run code, contained or not, so only INERT runs
51
+ unasked. "contained" is the rule "tiered" had before §48: a command
52
+ the container confines runs unasked unless it gets network. There is
53
+ no interpreter list behind either, and there must not be one -- see
54
+ classify_command's `runs_code`.
55
+
45
56
  What this replaced: a five-step ladder whose bottom four steps could
46
57
  only return False on the shipped config flags, making the whole check
47
58
  a pass-through for ToolApprovals.shell. Audit #157 is what that cost
@@ -65,23 +76,48 @@ import logging
65
76
  import os
66
77
  import re
67
78
  import shutil
79
+ from typing import Literal
68
80
 
69
- from pydantic import BaseModel, Field
81
+ from pydantic import BaseModel, Field, StrictBool
70
82
 
71
83
  import config
72
84
  from security import capability, posture
73
- from security.capability import UNAVAILABLE, UNCONTAINED, auto_approved
74
- from security.protected_paths import PROTECTED_SEGMENTS, protected_segment
85
+ from security.capability import (
86
+ UNAVAILABLE,
87
+ UNCONTAINED,
88
+ CommandProfile,
89
+ auto_approved,
90
+ )
91
+ from security.protected_paths import (
92
+ PROTECTED_SEGMENTS_FOLDED,
93
+ protected_segment,
94
+ )
75
95
  from security.sandbox import (
96
+ BACKEND_CONTAINER,
97
+ BACKEND_SSH,
98
+ BACKEND_WSL,
76
99
  HOST_READ,
77
100
  INERT,
101
+ SANDBOXED,
102
+ SANDBOXED_NET,
78
103
  SandboxUnavailable,
79
104
  _is_inert,
80
105
  classify_command,
81
106
  containment_for,
107
+ declared_backend,
108
+ declared_network,
109
+ declared_root,
82
110
  detect_shell,
83
111
  is_docker_available,
112
+ known_runtime,
84
113
  run_sandboxed,
114
+ ssh_enabled,
115
+ ssh_target,
116
+ ssh_unavailable_reason,
117
+ sudo_refusal,
118
+ wsl_distro,
119
+ wsl_enabled,
120
+ wsl_unavailable_reason,
85
121
  )
86
122
 
87
123
  logger = logging.getLogger(__name__)
@@ -150,13 +186,70 @@ class ShellParams(BaseModel):
150
186
  "the command is allowed or how it runs."
151
187
  ),
152
188
  )
189
+ requires_network: StrictBool = Field(
190
+ default=False,
191
+ description=(
192
+ "Whether this command needs to reach the network. Say true "
193
+ "for anything that downloads, installs, clones, publishes or "
194
+ "calls an API. WITHOUT IT THE COMMAND RUNS WITH NETWORKING "
195
+ "OFF and the connection simply fails -- the harness reads "
196
+ "your command as text and cannot tell that an inline script "
197
+ "or an interpreter you invoke wants egress, so it assumes "
198
+ "not. Saying true does not bypass approval; it tells the "
199
+ "user what they are being asked to allow."
200
+ ),
201
+ )
202
+ needs_root: StrictBool = Field(
203
+ default=False,
204
+ description=(
205
+ "Whether this command must run as root. The harness prefixes "
206
+ "sudo for you and supplies the password it holds for that "
207
+ "machine -- DO NOT write `sudo` in the command yourself, and "
208
+ "never put a password in it. The WHOLE command line runs as "
209
+ "root, redirects and pipes included. Only 'wsl' and 'ssh' can "
210
+ "do this: in the container you ALREADY are root, so drop the "
211
+ "flag there. A human is asked every single time, whatever the "
212
+ "approval mode, and the call is refused outright if no "
213
+ "password is stored for that machine -- the refusal says which "
214
+ "one to store. Leave it false unless the command genuinely "
215
+ "cannot work otherwise."
216
+ ),
217
+ )
218
+ backend: Literal["container", "wsl", "ssh"] = Field(
219
+ default="container",
220
+ description=(
221
+ "Where to run it. 'container' is the sandbox: a pinned Linux "
222
+ "image with only the workspace visible, no network unless you "
223
+ "ask, and memory, CPU and process limits. 'wsl' is the USER'S "
224
+ "OWN Windows machine with a Linux userland on it -- their real "
225
+ "home directory, their installed tools, the network always on, "
226
+ "no resource limits, and no isolation from this harness's own "
227
+ "files. Ask for it only when the work genuinely needs the "
228
+ "user's machine or a Linux toolchain the image does not have, "
229
+ "say so in the rationale, and expect to be asked: only a "
230
+ "read-only command whose arguments are all inside the "
231
+ "workspace runs there without a prompt. It may be turned off, "
232
+ "in which case the call is refused and says so. Use paths "
233
+ "RELATIVE to the workspace -- an absolute POSIX path is read "
234
+ "as leaving the workspace and always asks. "
235
+ "'ssh' is a DIFFERENT MACHINE -- the remote host the user "
236
+ "configured. Nothing runs there without asking, not even a "
237
+ "read-only command, because this harness cannot resolve a "
238
+ "path on a filesystem it cannot see. Its network is always "
239
+ "on and `requires_network` means nothing there. Note the "
240
+ "trap: `write` saves files LOCALLY, so a file you just wrote "
241
+ "does not exist on the remote -- send it through the command "
242
+ "itself, or do the work in the container."
243
+ ),
244
+ )
153
245
 
154
246
 
155
247
  TOOL_SCHEMA = {
156
248
  "name": "shell",
157
249
  "description": (
158
- "Execute a shell command. Commands run inside a Docker "
159
- "container with the workspace mounted at /workspace -- EXCEPT "
250
+ "Execute a shell command. Commands run inside a container "
251
+ "(Docker, or Podman where Docker cannot run one) with the "
252
+ "workspace mounted at /workspace -- EXCEPT "
160
253
  "a read-only command with an argument outside the workspace, "
161
254
  "which runs on the HOST with the user's own file access "
162
255
  "because the container cannot see those files. The result "
@@ -184,7 +277,31 @@ TOOL_SCHEMA = {
184
277
  # So an omission costs nothing and is VISIBLE: the prompt says
185
278
  # "(none given)", which is itself the observation. A silent gap would
186
279
  # not be.
187
- TOOL_SCHEMA["input_schema"]["required"] = ["command", "rationale"]
280
+ #
281
+ # `requires_network` (ROADMAP_v3 §50, NW1) is listed on the same terms
282
+ # and for the same reason: it is a thing the agent STATES, and a flag
283
+ # it is never asked for is one it will not set -- but it defaults to
284
+ # False, so a call that omits it runs with no network rather than
285
+ # failing validation after a human has already said yes.
286
+ #
287
+ # `backend` (ROADMAP_v3 §49, SS35) is NOT on the list, and the difference
288
+ # from `requires_network` is the direction its default fails in. An
289
+ # unstated `requires_network` runs a command that needed egress without
290
+ # it, so the command fails for a reason the model cannot see and the
291
+ # field has to be asked for. An unstated `backend` runs in the container,
292
+ # which is both the safe answer and the right one for almost every call --
293
+ # requiring it would make every command state the obvious in order to
294
+ # requiring it would make every command state the obvious in order to
295
+ # surface a field that matters for a handful.
296
+ #
297
+ # `needs_root` (slice 5b, SS67) is off the list for `backend`'s reason and
298
+ # not for `requires_network`'s. Unstated, the command runs unprivileged and
299
+ # fails with a permission error the model can READ and act on -- the
300
+ # visible direction. And unlike either of the others, forgetting it is not
301
+ # how root is reached by accident: a command that names `sudo` itself still
302
+ # meets a human, because the always-ask step reads the command text too.
303
+ TOOL_SCHEMA["input_schema"]["required"] = [
304
+ "command", "rationale", "requires_network"]
188
305
 
189
306
 
190
307
  # ---------------------------------------------------------------------------
@@ -192,14 +309,41 @@ TOOL_SCHEMA["input_schema"]["required"] = ["command", "rationale"]
192
309
  # ---------------------------------------------------------------------------
193
310
 
194
311
 
195
- def _profile_and_containment(command: str):
312
+ def _profile_and_containment(command: str, requires_network: bool = False,
313
+ backend: str = BACKEND_CONTAINER):
196
314
  """Classify *command* and work out what will contain it.
197
315
 
198
316
  One helper for both the gate and the prompt so they cannot describe
199
317
  the same call differently -- which is the failure #157 came from,
200
318
  with `_is_inert` consulted twice for two different questions.
319
+
320
+ *requires_network* is the agent's declaration (§50), already coerced
321
+ by `declared_network`. It reaches the classifier rather than being
322
+ applied afterwards, so the gate and the prompt read the one network
323
+ fact instead of each OR-ing the flag in for itself.
324
+
325
+ *backend* is the agent's other declaration (§49, SS35), coerced by
326
+ `declared_backend`. It does NOT reach the classifier: what a command
327
+ is ABLE to do is a fact about the command, and the same text has the
328
+ same capabilities wherever it runs. It reaches `containment_for`,
329
+ which is the half of the question that is about the machine -- and
330
+ the answer there is UNCONTAINED for every tier (SS1).
201
331
  """
202
- profile = classify_command(command, config.WORKSPACE_DIR)
332
+ profile = classify_command(command, config.WORKSPACE_DIR,
333
+ requires_network=requires_network)
334
+ # SS35. Asked first, because on this backend the runtime's answer is
335
+ # not part of the question: WSL is uncontained whether or not a
336
+ # container could have run the command, and probing Docker to decide
337
+ # that would be paying for an answer nobody reads.
338
+ if backend == BACKEND_WSL:
339
+ return profile, containment_for(profile, False, backend)
340
+ # SS46/SS48, for SS35's reason and one more: a remote host's
341
+ # containment does not depend on what this machine's Docker is doing
342
+ # either, and the classified tier is kept only so the NOTICE can still
343
+ # describe the command. Nothing downstream may act on it -- see the
344
+ # SSH step in `_shell_approval_check`.
345
+ if backend == BACKEND_SSH:
346
+ return profile, containment_for(profile, False, backend)
203
347
  # Docker is probed only when the answer depends on it. HOST_READ is
204
348
  # UNCONTAINED whatever Docker is doing -- it names a file outside
205
349
  # the workspace, which no container can show it -- so it still
@@ -238,9 +382,16 @@ def _command_touches_protected(command: str) -> str | None:
238
382
  parse. A token like ``.ven*/settings.json`` carries no literal
239
383
  segment and reaches no answer here (G2 -- a classifier that learned
240
384
  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.
385
+ the consumer is an always-ASK trigger and never a deny: under
386
+ `tiered`, what slips past a token check still lands in front of a
387
+ human with the full command text, because a spelling that could
388
+ expand into the segment is not INERT and so asks anyway.
389
+
390
+ That last clause was FALSE until §48 (CE1). A contained command was
391
+ auto-approved, so `cat .ven*/settings.json; true` and a `python -c`
392
+ that opens the file read it unasked, while this docstring said they
393
+ met a human. Under `contained` and `never` they still do not: the
394
+ ro mount stops a write there, and the read is documented risk.
244
395
  """
245
396
  if not isinstance(command, str):
246
397
  return None
@@ -250,7 +401,11 @@ def _command_touches_protected(command: str) -> str | None:
250
401
  candidates.append(token.split("=", 1)[1])
251
402
  for candidate in candidates:
252
403
  for part in re.split(r"[\\/]", candidate):
253
- if part in PROTECTED_SEGMENTS:
404
+ # Folded, like the resolved branch below it (batch 146).
405
+ # This is the branch for a token realpath cannot help with,
406
+ # so an exact-case compare here was the half of the fold
407
+ # that `protected_segment` could not reach.
408
+ if part.casefold() in PROTECTED_SEGMENTS_FOLDED:
254
409
  return part
255
410
  try:
256
411
  resolved = os.path.realpath(
@@ -263,31 +418,93 @@ def _command_touches_protected(command: str) -> str | None:
263
418
  return None
264
419
 
265
420
 
421
+ # The binaries that make a command somebody else's. `sudo` is the one
422
+ # slice 5b supplies a password for; the other three are here because they
423
+ # answer the same question -- "does this line try to become another user"
424
+ # -- and a step that knew only about `sudo` would auto-approve `doas` on
425
+ # the one backend where the measurement showed nothing asks.
426
+ _ROOT_BINARIES = frozenset({"sudo", "doas", "pkexec", "su"})
427
+
428
+
429
+ def _command_names_root(command) -> bool:
430
+ """Whether the command TEXT names an escalation binary (SS67).
431
+
432
+ RAW `.split()` tokens and a basename compare -- a token check, never a
433
+ parser (G2), exactly like `_command_touches_protected` beside it and
434
+ for the same trade. `echo sudo` asks, and that costs one prompt; what
435
+ it buys is that `sudo apt-get install` cannot be auto-approved on WSL
436
+ because the call left `needs_root` unset. That was MEASURED to be the
437
+ live behaviour before this slice: under AUTO_APPROVE_SANDBOX_FALLBACK
438
+ the fallback opt-in answered for the whole WSL backend.
439
+
440
+ What it deliberately does NOT do is decide anything about HOW the
441
+ command runs. It only ever ADDS a prompt -- the harness supplies a
442
+ password for `needs_root` and for nothing else -- so a spelling that
443
+ slips past this check reaches a `sudo` with no password and fails,
444
+ rather than reaching one with a password nobody approved.
445
+
446
+ Total, like everything else the gate calls: `params["command"]` is
447
+ whatever the model emitted.
448
+ """
449
+ if not isinstance(command, str):
450
+ return False
451
+ for token in command.split():
452
+ if re.split(r"[\\/]", token)[-1] in _ROOT_BINARIES:
453
+ return True
454
+ return False
455
+
456
+
266
457
  def _shell_approval_check(tool_name: str, params: dict) -> bool:
267
458
  """Whether this shell call needs a human to say yes (ROADMAP_v2 §28).
268
459
 
269
460
  Reads top to bottom as the policy it is:
270
461
 
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
462
+ 1. The mode answers outright unless it is "tiered".
463
+ 2. A command naming a protected path segment
276
464
  (security.protected_paths.PROTECTED_SEGMENTS) always asks --
277
465
  before the fallback opt-in and the capability rule can answer
278
466
  for it. The file tools DENY such a path outright; the shell
279
467
  only asks, because a command is free text and the token check
280
468
  refuses to parse it (G2), so what slips past the check still
281
- meets a human. Behind step 2 deliberately: mode "never" is a
469
+ meets a human. Behind step 1 deliberately: mode "never" is a
282
470
  documented opt-out of ALL approval, and it already answers
283
471
  "auto-approve" for a host read of /etc/shadow.
284
- 4. AUTO_APPROVE_SANDBOX_FALLBACK is applied HERE, visibly, rather
472
+ 2b. A call that will be REFUSED answers "no" rather than
473
+ "ask" (ROADMAP_v3 §49, SS37/SS40) -- the WSL backend turned
474
+ off, or a WSL command naming a protected segment. It reads
475
+ beside the UNAVAILABLE branch above and means the same
476
+ thing: there is nothing to approve, and asking would spend
477
+ a human decision on an outcome already fixed. `run` and the
478
+ session start handler refuse the same call, through the one
479
+ `uncontained_refusal`.
480
+ 2c. An SSH call ALWAYS asks (ROADMAP_v3 §49, SS48), read
481
+ above every opt-in below so that neither of them can answer
482
+ for a machine this process cannot inspect.
483
+ 2d. A ROOT call ALWAYS asks (slice 5b, SS65/SS67), in the same
484
+ position and for a measured version of the same reason: the
485
+ fallback opt-in already answers for the ENTIRE WSL backend,
486
+ so a root step below it would be dead code on the one
487
+ backend where root is most reachable. It fires on the
488
+ DECLARATION or on the command text naming an escalation
489
+ binary, because a model that types `sudo` itself never sets
490
+ the flag.
491
+ 3. AUTO_APPROVE_SANDBOX_FALLBACK is applied HERE, visibly, rather
285
492
  than passed into the generic rule to be honoured out of sight.
286
493
  It is the user's own opt-in to an isolation level the harness
287
494
  has already told them is weak -- and it sits BELOW the
288
495
  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.
496
+ directory the ro-mount exists to keep commands out of. Honoured
497
+ under `tiered` and `contained` alike (§48, CE5): it is written on
498
+ purpose and already flagged. Under `always` it is never reached,
499
+ because step 1 returned (CE6).
500
+ 4. The `contained` mode (§48, CE2) is the second visible opt-in, and
501
+ applied here for the same reason: a command the container
502
+ confines and that gets no network runs unasked. Below the
503
+ protected-segment check, so a literal `.venastine` token still
504
+ asks in that mode, and read off capabilities rather than the tier
505
+ label (G1), with `measured` first (G5).
506
+ 5. Otherwise the capability rule decides -- which, since §48 (CE1),
507
+ asks about anything that may run code, contained or not.
291
508
 
292
509
  The return is `not auto_approved(...)` -- this function answers "must
293
510
  someone be asked", the rule answers "is this covered". Two names for
@@ -295,10 +512,6 @@ def _shell_approval_check(tool_name: str, params: dict) -> bool:
295
512
  is a silent auto-approve, so the negation stays on one line where it
296
513
  can be read.
297
514
  """
298
- approvals = config.ToolApprovals()
299
- if getattr(approvals, tool_name, False):
300
- return True
301
-
302
515
  active = posture.current()
303
516
  mode = capability.validate_mode(active.shell_approval_mode,
304
517
  "config.SHELL_APPROVAL_MODE")
@@ -307,8 +520,19 @@ def _shell_approval_check(tool_name: str, params: dict) -> bool:
307
520
  if mode == capability.NEVER:
308
521
  return False
309
522
 
523
+ # TOTAL from here down (batch 146). Below the mode branches on
524
+ # purpose: `never` is a documented opt-out of ALL approval and answers
525
+ # without reading the params at all, so a guard above it would have
526
+ # changed what that opt-out means. From here the function reads six
527
+ # fields, and `params` is whatever the model emitted -- which for this
528
+ # shape means "not an object". ASK, like every other answer this
529
+ # function cannot settle.
530
+ if not isinstance(params, dict):
531
+ return True
310
532
  command = params.get("command", "")
311
- profile, containment = _profile_and_containment(command)
533
+ backend = declared_backend(params)
534
+ profile, containment = _profile_and_containment(
535
+ command, declared_network(params), backend)
312
536
 
313
537
  # No backend can run this, so there is nothing to approve. NOT the
314
538
  # same as auto_approved() answering False, which means ASK -- the two
@@ -324,12 +548,57 @@ def _shell_approval_check(tool_name: str, params: dict) -> bool:
324
548
  if containment == UNAVAILABLE:
325
549
  return False
326
550
 
327
- # Step 3: a protected segment always asks, whatever the sandbox says.
551
+ # SS40, and read beside the UNAVAILABLE branch above rather than with
552
+ # the protected-segment step below, because it is the same KIND of
553
+ # answer: this call is refused before it runs, so there is nothing to
554
+ # approve, and asking would spend a human decision on an outcome that
555
+ # is already fixed. Below the mode switch for the same reason
556
+ # UNAVAILABLE is -- `always` asks about everything, including calls
557
+ # that will not run, and that wart is one the gate already has.
558
+ # `declared_root` and NOT `_command_names_root`, and the asymmetry is
559
+ # the decision: the refusal is about a password THIS HARNESS would
560
+ # have to supply, which it only ever does for a declared call. A
561
+ # command that merely names `sudo` supplies its own or fails, and
562
+ # refusing it for want of a stored secret would break a passwordless
563
+ # setup that works today.
564
+ if uncontained_refusal(command, backend,
565
+ declared_root(params)) is not None:
566
+ return False
567
+
568
+ # SS48. NOTHING on the SSH route is auto-approved, and this is the one
569
+ # place that is decided -- an explicit step rather than a synthesized
570
+ # profile that happens to fail `auto_approved`, because the opt-ins
571
+ # below (the fallback's and `contained`'s) each answer BEFORE that
572
+ # rule is reached, and a profile tuned to lose the last test would
573
+ # still have to be tuned to lose those two. One line that cannot be
574
+ # got wrong beats three that agree today.
575
+ #
576
+ # Two independent reasons, either sufficient. `_within` resolves
577
+ # against the LOCAL filesystem, so on a remote it answers a true
578
+ # question about the wrong machine -- and SS45, one slice old, is what
579
+ # a path check that cannot resolve costs: it does not fail open
580
+ # loudly, it approves confidently. And SS51: ssh has no `execve` path,
581
+ # so the "argv with no shell" property that EP5 makes the INERT tier
582
+ # out of does not exist on this route at all.
583
+ #
584
+ # Below the mode switch, so `never` still means never (SS1) and
585
+ # `always` still asks -- this widens neither.
586
+ if backend == BACKEND_SSH:
587
+ return True
588
+
589
+ # SS65/SS67. Above both opt-ins below, and the OR is the whole point:
590
+ # `declared_root` alone would be a step the model can step around by
591
+ # writing `sudo` and leaving the flag off, which is exactly what the
592
+ # measurement found already running unasked.
593
+ if declared_root(params) or _command_names_root(command):
594
+ return True
595
+
596
+ # Step 2: a protected segment always asks, whatever the sandbox says.
328
597
  segment = _command_touches_protected(command)
329
598
  if segment is not None:
330
599
  return True
331
600
 
332
- # The pre-§28 steps 4 and 5, preserved exactly. For a non-inert tier,
601
+ # The pre-§28 fallback steps, preserved exactly. For a non-inert tier,
333
602
  # UNCONTAINED can only mean "Docker is down AND the insecure fallback
334
603
  # is enabled" -- that is what containment_for computed -- so this
335
604
  # reads the answer already in hand instead of re-deriving it from two
@@ -339,6 +608,15 @@ def _shell_approval_check(tool_name: str, params: dict) -> bool:
339
608
  and active.auto_approve_fallback):
340
609
  return False
341
610
 
611
+ # Step 4, §48 (CE2): the rule `tiered` had before §48, under the name
612
+ # that says what it trusts. `measured` first, for G5's reason -- the
613
+ # container must not argue an uncharacterised call through.
614
+ if (mode == capability.CONTAINED_MODE
615
+ and containment == capability.CONTAINED
616
+ and profile.measured
617
+ and not profile.network):
618
+ return False
619
+
342
620
  return not auto_approved(profile, containment)
343
621
 
344
622
 
@@ -352,13 +630,60 @@ def _shell_approval_notice(params: dict, _context=None) -> str:
352
630
  someone tells you the inert path is a host subprocess.
353
631
  """
354
632
  command = params.get("command", "")
355
- profile, containment = _profile_and_containment(command)
633
+ backend = declared_backend(params)
634
+ profile, containment = _profile_and_containment(
635
+ command, declared_network(params), backend)
636
+ # The runtime is read from the probe `_profile_and_containment` just
637
+ # ran, never re-probed: the person answering should see WHICH runtime
638
+ # isolates the command, since Podman and Docker are not the same
639
+ # product (ROADMAP_v3 §49, SS22).
356
640
  where = {
357
- "contained": "in a Docker container, workspace mounted at /workspace",
641
+ "contained": (f"in a {known_runtime().capitalize()} container, "
642
+ "workspace mounted at /workspace"),
358
643
  "uncontained": "on the HOST, with your own file access",
359
644
  "unavailable": "nowhere -- no sandbox backend is available",
360
645
  }.get(containment, containment)
646
+ # SS41. "uncontained" is true of WSL and nowhere near enough: the
647
+ # person answering has to know it is not a weaker container but their
648
+ # own machine, and that the two protections they may be picturing --
649
+ # the read-only mount over this harness's own files, and the memory
650
+ # and process limits -- are simply not there. Said here rather than
651
+ # only in the docs, because this prompt is where the decision is made.
652
+ if backend == BACKEND_WSL:
653
+ where = (f"in WSL ({wsl_distro() or 'default distribution'}) -- "
654
+ f"YOUR machine, not a sandbox: your own files, the "
655
+ f"network on, no memory or process limit, no read-only "
656
+ f"mount over this harness's own config, and it can start "
657
+ f"Windows programs with your full authority")
658
+ # SS48/SS55. The person answering has to know this is not their
659
+ # machine at all, and that two things they may be picturing are
660
+ # absent: any isolation, and any way for this harness to check what
661
+ # the command will touch. The remote is NAMED, because "uncontained"
662
+ # is equally true of the host fallback and means something different
663
+ # here -- and because a prompt that does not say which machine is
664
+ # about to run something is not a prompt anyone can answer.
665
+ if backend == BACKEND_SSH:
666
+ where = (f"on {ssh_target() or 'the configured remote host'} over "
667
+ f"SSH -- ANOTHER MACHINE, not a sandbox and not this "
668
+ f"one: no isolation, no memory or process limit, the "
669
+ f"network on, and nothing here can see its filesystem, "
670
+ f"so no argument of this command has been checked "
671
+ f"against anything")
361
672
  notice = f"{profile.tier}: {profile.reason}. Runs {where}."
673
+ # Slice 5b. The person is answering for a privilege level, not only a
674
+ # machine, and "uncontained" does not say which. Two sentences, because
675
+ # the two cases are genuinely different: one is the harness handing over
676
+ # a password it holds, the other is the command asking for root on its
677
+ # own with nothing behind it.
678
+ if declared_root(params):
679
+ notice += (" AS ROOT -- the whole command line runs under sudo, "
680
+ "with the password this harness holds for that machine. "
681
+ "Anything root can do there, this can do.")
682
+ elif _command_names_root(command):
683
+ notice += (" It names sudo (or su, doas, pkexec) itself, which is "
684
+ "why this is being asked about at all. The harness "
685
+ "supplies a password only for a call that declares "
686
+ "needs_root, so this one may simply fail.")
362
687
  binary = _resolved_binary(command) if containment == UNCONTAINED else ""
363
688
  if binary:
364
689
  notice += f" Binary resolves to {binary}."
@@ -371,6 +696,95 @@ def _shell_approval_notice(params: dict, _context=None) -> str:
371
696
  return notice
372
697
 
373
698
 
699
+
700
+ def interactive_profile(requires_network: bool = False) -> CommandProfile:
701
+ """What an interactive shell can do -- STATED, not derived (SS32).
702
+
703
+ `classify_command` reads a command's text. An interactive session has no
704
+ text to read: `cd`, an alias and a REPL mean what arrives later is not
705
+ an argv, and the first line is only the first line. So the capabilities
706
+ are declared at their upper bound -- it runs code, it writes -- and
707
+ `measured` is True because that IS the measurement: the answer does not
708
+ depend on parsing anything, which is exactly when a profile is allowed
709
+ to claim it was characterised (G5).
710
+
711
+ `escapes_workspace` is False because the container's filesystem is not
712
+ the host's, and SS28 admits no other route for this kind.
713
+ """
714
+ network = bool(requires_network)
715
+ return CommandProfile(
716
+ tier=SANDBOXED_NET if network else SANDBOXED,
717
+ measured=True,
718
+ escapes_workspace=False,
719
+ writes=True,
720
+ runs_code=True,
721
+ network=network,
722
+ reason=("an interactive shell in the container -- anything may be "
723
+ "typed into it" + (", and it was opened with network access"
724
+ if network else "")))
725
+
726
+
727
+ def _interactive_approval_check(tool_name: str, params: dict) -> bool:
728
+ """Whether OPENING an interactive shell needs a human yes (SS29, SS32).
729
+
730
+ NOT `_shell_approval_check`, and the difference is the point. That one
731
+ answers about the text it is handed; here the text is only the first
732
+ line of a session whose LATER lines are covered by the same yes. Asking
733
+ about the first line would mean `shell_interactive` with `pwd` was
734
+ auto-approved as a read and handed back a shell that can run anything --
735
+ the approval and the authority describing different calls, which is
736
+ #157's shape.
737
+
738
+ So the question is asked about what is actually being granted:
739
+ `interactive_profile`, through the same mode ladder and the same
740
+ `auto_approved` rule as every other shell call. Under `tiered` and
741
+ `contained` that always asks, because it always runs code (§48, CE1) --
742
+ and it asks through the rule rather than by hardcoding "always", so if
743
+ the rule ever changes this follows it instead of contradicting it.
744
+ """
745
+ active = posture.current()
746
+ mode = capability.validate_mode(active.shell_approval_mode,
747
+ "config.SHELL_APPROVAL_MODE")
748
+ if mode == capability.ALWAYS:
749
+ return True
750
+ if mode == capability.NEVER:
751
+ return False
752
+ profile = interactive_profile(declared_network(params))
753
+ containment = containment_for(profile, is_docker_available())
754
+ if containment == UNAVAILABLE:
755
+ # Nothing can run it, so there is nothing to approve;
756
+ # `start_interactive` refuses with the instructions. Same polarity
757
+ # note as `_shell_approval_check`'s.
758
+ return False
759
+ return not auto_approved(profile, containment)
760
+
761
+
762
+ def _interactive_approval_notice(params: dict, _context=None) -> str:
763
+ """What the person answering is being asked to allow.
764
+
765
+ It says the quiet part out loud (SS29): this yes is not for one command,
766
+ it is for the session. A prompt that described only the first line would
767
+ be telling the truth about the wrong thing.
768
+ """
769
+ network = declared_network(params)
770
+ profile = interactive_profile(network)
771
+ containment = containment_for(profile, is_docker_available())
772
+ where = ("in a container" if containment == capability.CONTAINED
773
+ else "with no container available")
774
+ first = params.get("command", "") if isinstance(params, dict) else ""
775
+ text = (f"Opens an interactive shell {where} and keeps it open. "
776
+ f"APPROVING THIS APPROVES EVERYTHING THE AGENT LATER TYPES INTO "
777
+ f"IT, not just the first line.")
778
+ if isinstance(first, str) and first.strip():
779
+ text += f" It starts by running: {first.strip()[:200]}"
780
+ if network:
781
+ text += " The call declared it needs the network, so egress is on."
782
+ segment = _command_touches_protected(first)
783
+ if segment is not None:
784
+ text += f" That first line names {segment}, which is protected."
785
+ return text
786
+
787
+
374
788
  def _resolved_binary(command) -> str:
375
789
  """The absolute path the first word will actually execute as, on a
376
790
  run that is about to happen on the HOST (§46, EP8).
@@ -407,6 +821,112 @@ def _resolved_binary(command) -> str:
407
821
  # ---------------------------------------------------------------------------
408
822
 
409
823
 
824
+ def uncontained_refusal(command: str, backend: str,
825
+ needs_root: bool = False) -> str | None:
826
+ """Why this call must not run at all, or None (§49).
827
+
828
+ `fallback_changed_refusal`'s shape, and ONE copy for the same reason:
829
+ the gate reads it to answer "there is nothing to approve", and `run`
830
+ and the session start handler read it to stop the call. Three sites
831
+ deciding this separately is the drift #157 came from.
832
+
833
+ Two refusals, and they say different things on purpose.
834
+
835
+ THE BACKEND IS OFF (SS35). Not "unavailable" -- a machine that has WSL
836
+ and is not allowed to use it, which a model told "no distro found"
837
+ would try to fix by asking the user to install one.
838
+
839
+ A PROTECTED SEGMENT (SS40). In the container `.venastine/` is mounted
840
+ read-only, so a write there fails with EROFS and a read is documented
841
+ risk; on WSL there is no mount at all, a write SUCCEEDS, and D17's
842
+ hash notices only at the next launch. So the shell's usual answer for
843
+ a protected segment -- always ask -- is the wrong one here, and this
844
+ is the file tools' answer instead: deny.
845
+
846
+ The token check is exactly sound where it bites. An INERT command
847
+ carries no metacharacters by construction, so `command.split()` IS the
848
+ argv that will run and a literal segment cannot hide behind quoting or
849
+ expansion. A non-inert command can hide one, and still meets a human
850
+ on top of this -- `runs_code` is True for every non-inert profile
851
+ (CE1), so it asks under `tiered` and, being UNCONTAINED here, under
852
+ `contained` too.
853
+
854
+ A THIRD refusal arrives with slice 5b, and it is read FIRST because it
855
+ is true of every backend including the container: a call that asked for
856
+ root and cannot have it. `sudo_refusal` owns that decision -- see there
857
+ for why the container is refused for already being root, and why no
858
+ stored password is a refusal rather than a prompt (SS68).
859
+ """
860
+ if needs_root:
861
+ refusal = sudo_refusal(backend)
862
+ if refusal is not None:
863
+ return refusal
864
+ if backend == BACKEND_SSH:
865
+ if not ssh_enabled():
866
+ return ssh_unavailable_reason()
867
+ segment = _command_touches_protected(command)
868
+ if segment is not None:
869
+ # SS54. SS40's answer, reached by a different road: WSL is
870
+ # refused because it demonstrably CAN write this harness's own
871
+ # authority files, and SSH is refused because nothing here can
872
+ # demonstrate that it cannot. `ssh localhost` is this machine,
873
+ # and a remote that mounts this one is not visible from here
874
+ # either -- so the question "is that path this harness's own?"
875
+ # has no answer, and an unanswerable question is not a yes.
876
+ return (
877
+ f"This command names {segment}/, and a command over SSH is "
878
+ f"refused rather than asked about when it does. This "
879
+ f"harness cannot tell whether the remote host is a "
880
+ f"different machine -- `ssh localhost` is this one, and a "
881
+ f"remote that mounts this one looks the same from here -- "
882
+ f"so it cannot tell whether that path is its own authority "
883
+ f"files. Run it in the container, or do the work somewhere "
884
+ f"inside the workspace.")
885
+ return None
886
+ if backend != BACKEND_WSL:
887
+ return None
888
+ if not wsl_enabled():
889
+ return wsl_unavailable_reason()
890
+ segment = _command_touches_protected(command)
891
+ if segment is not None:
892
+ return (
893
+ f"This command names {segment}/, and a command in WSL is "
894
+ f"refused rather than asked about when it does. In the "
895
+ f"container that directory is mounted read-only, so a write "
896
+ f"fails and a read is a documented risk you can accept. WSL "
897
+ f"mounts nothing: a write there would succeed against this "
898
+ f"harness's own authority files and would only be noticed at "
899
+ f"the next launch. Run it in the container, or do the work "
900
+ f"somewhere inside the workspace.")
901
+ return None
902
+
903
+
904
+ def fallback_changed_refusal(command: str, docker_up: bool) -> str | None:
905
+ """The TOCTOU safety net, or None: why a command approved while a
906
+ container runtime answered must not now run on the fallback.
907
+
908
+ If the approval check auto-approved because the runtime was available
909
+ at that time, but it is now down and the command would take the
910
+ fallback, the fallback would have required approval that was never
911
+ given. One copy for `run` and for the background-session start tools
912
+ (ROADMAP_v3 §49), which pass the same gate and the same probe.
913
+ """
914
+ if docker_up or _is_inert(command):
915
+ return None
916
+ # Read here rather than passed in from the approval check: §40 makes the
917
+ # two reads the SAME object for the life of the process, so re-reading
918
+ # cannot reintroduce the TOCTOU gap this exists to close. Before §40 it
919
+ # could have.
920
+ active = posture.current()
921
+ if active.allow_insecure_fallback and not active.auto_approve_fallback:
922
+ return ("Docker became unavailable after the approval check. "
923
+ "The insecure subprocess fallback requires explicit "
924
+ "per-run approval (AUTO_APPROVE_SANDBOX_FALLBACK is "
925
+ "False). Please retry — the approval prompt will "
926
+ "appear this time.")
927
+ return None
928
+
929
+
410
930
  def run(params: dict) -> dict:
411
931
  # `parsed.rationale` is deliberately never read below. It is shown
412
932
  # to a person and archived with the call; it has no part in what
@@ -416,43 +936,42 @@ def run(params: dict) -> dict:
416
936
  # Probe Docker once for this execution — the result is threaded
417
937
  # into run_sandboxed to eliminate the TOCTOU gap where Docker
418
938
  # 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
- }
939
+ # SS37/SS40/SS54, above the container probe: a call that asked for WSL
940
+ # or SSH and cannot have it is refused by name, and is never quietly
941
+ # served by a backend it did not ask for.
942
+ refusal = uncontained_refusal(parsed.command, parsed.backend,
943
+ parsed.needs_root)
944
+ if refusal is not None:
945
+ return {"error": refusal}
946
+
947
+ # Not probed for a WSL or SSH call, and not merely to save the 0.43s:
948
+ # the TOCTOU guard below is about a container runtime disappearing
949
+ # between the gate and the run and the command then taking the INSECURE
950
+ # FALLBACK. Neither can take it -- `_route` answers ROUTE_WSL/ROUTE_SSH
951
+ # or refuses (SS37) -- so running that guard here would refuse a call
952
+ # for a backend it was never going to touch.
953
+ docker_up = True if parsed.backend != BACKEND_CONTAINER \
954
+ else is_docker_available()
955
+
956
+ if parsed.backend == BACKEND_CONTAINER:
957
+ refusal = fallback_changed_refusal(parsed.command, docker_up)
958
+ if refusal is not None:
959
+ return {"error": refusal}
447
960
 
448
961
  try:
449
962
  return run_sandboxed(
450
963
  command=parsed.command,
451
964
  workspace_dir=config.WORKSPACE_DIR,
452
965
  docker_available=docker_up,
966
+ backend=parsed.backend,
967
+ needs_root=parsed.needs_root,
453
968
  # §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),
969
+ # routing cannot disagree with the decision to allow it --
970
+ # the declaration included (§50), read off the validated
971
+ # params here and off the raw ones at the gate, which is why
972
+ # `declared_network` accepts only literal True.
973
+ profile=classify_command(parsed.command, config.WORKSPACE_DIR,
974
+ requires_network=parsed.requires_network),
456
975
  )
457
976
  except SandboxUnavailable as e:
458
977
  return {"error": str(e)}