@yahyahammad/venastine 0.3.8 → 0.3.10

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 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -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 +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -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 +2756 -2715
  28. package/core/commands.py +464 -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 +274 -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 +467 -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 +114 -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 +780 -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 +314 -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 +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
package/README.md CHANGED
@@ -1,1034 +1,1043 @@
1
- ![Venastine Research Harness Screenshot](docs/assets/Venastine_Research_Harness_Demo_Photo.png)
2
-
3
- # Venastine Research Harness
4
-
5
- An agentic harness built from scratch — no LangChain, no agent framework — with two modes that share the same machinery:
6
-
7
- - **Chat** — a normal tool-using assistant loop.
8
- - **Research** — a ten-pass pipeline that writes an answer, then independently fact-checks and critiques its own claims, audits the assumptions hiding underneath them, scores every claim by a fixed formula rather than by asking the model how sure it is, and revises only what came back flagged.
9
-
10
- Works with Anthropic, any OpenAI-compatible provider (OpenAI, DeepSeek, Groq, Mistral, local endpoints), and Google Gemini.
11
-
12
- The design premise is that a model's own confidence is not evidence. Everything in the research pipeline exists to replace "the model said it was sure" with something you can audit: which claims were checked against sources, which critique survived, which assumptions were never stated, and which numbers produced the final tier.
13
-
14
- ---
15
-
16
- ## Try it online
17
-
18
- The same harness runs in your browser, nothing to install, on a [Hugging Face Space](https://huggingface.co/spaces/SolenopsisCampo/VenastineHarnessDemo) and a [ModelScope Studio](https://www.modelscope.ai/studios/Venastine-Research/VenastineHarnessDemo). Each tab gets its own session, deleted when the tab closes.
19
-
20
- - **Connect a model with a sign-in.** `/connect huggingface` and `/connect openrouter` work on both, and `/connect modelscope` (modelscope.ai) or `/connect modelscope-cn` (modelscope.cn) wherever the deployment can complete that site's sign-in. Requests use your own account's allowance, and the landing page links each provider's page for revoking access.
21
- - **The shared demo takes no pasted key**, and it does not offer the file and shell tools. A private duplicate of the Space in single-user mode takes both (set `VENASTINE_SINGLE_USER=1` in Hugging Face's duplicate dialog), and so does an install.
22
- - **It runs a commit of `main` that passed every CI check**, named in each page's footer: the Space is redeployed automatically once all of them pass, and the Studio by hand with the same checks. [PRIVACY.md](docs/PRIVACY.md#the-hosted-demo-roadmap_v3-79) says what a hosted session changes.
23
-
24
- ---
25
-
26
- ## Setup
27
-
28
- **Python 3.11 or newer**, for every local install. `mcp_client/client.py` uses `asyncio.timeout`, which is 3.11+, and 27 sites use runtime `X | Y` annotations (3.10+). `pyproject.toml` declares the floor, so an install refuses an older interpreter rather than failing later from inside the MCP connect path.
29
-
30
- ### Install directly from GitHub
31
-
32
- Requires **Python 3.11+**, including its `venv` module. Node, npm, Git, and
33
- administrator access are not needed. On Linux/macOS (Bash and curl):
34
-
35
- ```bash
36
- curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash
37
- ```
38
-
39
- On Windows (PowerShell):
40
-
41
- ```powershell
42
- irm https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.ps1 | iex
43
- ```
44
-
45
- You can also download and inspect the scripts before running them. They
46
- download the shared Python installer completely, then execute it. It resolves
47
- `main` to a full commit ID, downloads that source archive, and installs the
48
- runtime dependencies in an isolated environment. It does not install Python.
49
-
50
- The source lives under `~/.local/share/venastine/app`, with a `venastine`
51
- command in `~/.local/bin` (`venastine.cmd` on Windows). When that directory is
52
- not on your PATH yet, the installer puts it there for the terminals you open
53
- afterwards, the way npm's global commands already are. On Windows it appends
54
- it to your user PATH, and to the PowerShell window that ran the installer. On
55
- macOS and Linux it adds a marked block to your own shell's startup file —
56
- `~/.zshrc`, `~/.bashrc`, fish's `conf.d/venastine.fish`, or `~/.profile` for
57
- other shells, plus the bash login file you already have on macOS. Running it
58
- again adds nothing twice. To leave PATH alone, set
59
- `VENASTINE_NO_MODIFY_PATH=1` or pass `--no-modify-path`. If another
60
- `venastine` — an npm install, say — comes first on your PATH, the installer
61
- names it and prints this command's full path instead.
62
- Then, from your project directory, run `venastine --tui` and use `/connect`.
63
- `venastine --venastine-doctor` shows the installed version, commit, interpreter,
64
- and state paths. Credentials and conversation state follow the same rules
65
- as the npm installation below.
66
-
67
- Rerun the installer to update, after closing running Venastine sessions. It
68
- builds a fresh environment before replacing the active source and carries
69
- your `config.yaml` edits forward through the existing settings merger.
70
- Previous source trees (`previous-*`) stay under the install directory for
71
- recovery. Python environments stay in `~/.config/venastine/runtime/github-*`,
72
- inside the user tier the harness already protects from tool writes. Updates
73
- therefore use more disk space. An unrelated existing directory or command is
74
- never replaced.
75
-
76
- Choose a branch, tag, or full commit ID with `VENASTINE_REF`; choose locations
77
- with `VENASTINE_INSTALL_DIR` and `VENASTINE_BIN_DIR`, or a Python executable
78
- with `VENASTINE_PYTHON`; `VENASTINE_NO_MODIFY_PATH=1` leaves PATH alone. Set
79
- these before running either command. The default
80
- ref is `main`; older refs without `bin/venastine.py` cannot use this installer.
81
- The installer itself is downloaded from `main`, even when selecting another
82
- source ref. Bash also forwards options to the helper:
83
-
84
- ```bash
85
- curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash -s -- --ref main
86
- ```
87
-
88
- From a checkout, `python scripts/install.py --help` lists the same options
89
- without downloading or installing anything. To remove a GitHub installation,
90
- remove its command, install directory, the `github-*` runtime directories it
91
- created, and the PATH entry it added — from your user PATH on Windows, or the
92
- block between the `venastine GitHub installer` markers in your shell's startup
93
- file; other state in `~/.config/venastine` and artifacts in your projects
94
- remain separate.
95
-
96
- ### From npm
97
-
98
- ```bash
99
- npm install -g @yahyahammad/venastine
100
- venastine
101
- ```
102
-
103
- For the full TUI experience you can use:
104
- ```bash
105
- venastine --tui
106
- ```
107
-
108
-
109
- **npm handles the setup for you.** It delivers the harness as a folder of source — there is no bundled binary — and Python still runs it, so the only prerequisite you provide is an interpreter on PATH. Everything after that happens on first launch: the launcher finds a suitable Python, tells you which one and what it is about to install, and builds an isolated environment with the pinned dependencies once you agree. It asks every time it would install something, never installs during `npm install` itself, and refuses rather than proceeding when there is no terminal to ask in.
110
-
111
- Two things differ from a clone, both to make a command you run from anywhere behave sensibly:
112
-
113
- * **Credentials** fall back to `~/.config/venastine/providers.json` when the directory you are in has no `providers.json` of its own. A local one still wins, so per-project keys keep working.
114
- * **Conversation state** — `app.db` and the log — lives in `~/.config/venastine/`, so threads and memories follow you between directories instead of each folder getting its own silo. Research reports still land in `./output` beside the work that produced them, and the file-ops workspace stays in the current directory because it is a permission boundary. An existing `./app.db` always wins, so running the command inside a clone uses that clone's data.
115
-
116
- **Updating keeps your settings.** `npm update` replaces the package directory wholesale, `config.yaml` with it, so the launcher merges your own values back in before the harness starts and prints what it kept. Settings you never touched pick up the new version's defaults, and keys the new version adds arrive at theirs; a value the new version no longer accepts is dropped on its own and named, rather than costing you the rest. It works for values set with `/config` and for ones you edited in the file by hand, which is the only way to set a list like `ensemble_models`. The one case it cannot help with is an edit made after your last session and never launched before you updated -- npm has already replaced the file by the time anything of ours runs.
117
-
118
- `venastine --venastine-doctor` prints every one of those resolved paths, plus the interpreter and environment it found.
119
-
120
- ### From a clone
121
-
122
- ```bash
123
- pip install -r requirements.txt
124
- ```
125
-
126
- This is the contributor path and what the rest of this document assumes.
127
-
128
- `markitdown` is an optional extra (`pip install -e ".[documents]"`) — its only consumer is behind `read`/`write`/`edit`, which are denied by default and cannot be enabled at runtime. The PDF export path is likewise optional: `pip install -e ".[pdf]"`.
129
-
130
- ### Two credential stores, deliberately separate
131
-
132
- | What | Where | Managed by |
133
- |---|---|---|
134
- | **LLM provider keys** (Anthropic, OpenAI, Google, …) | `providers.json` | `credentials.py`, template at `providers.json.example` |
135
- | **Tool API keys** (GitHub token, NVD key, …) | `.env` | `env_secrets.py`, template at `.env.example` |
136
-
137
- ```bash
138
- cp providers.json.example providers.json # then add your provider's API key
139
- cp .env.example .env # then fill in only the keys your tools actually need
140
- ```
141
-
142
- Without the first file every model call fails — both shells say so at launch (#138). **In the TUI, `/connect` writes it for you**: `/connect` lists the providers it knows, `/connect <name>` asks for the key in a masked prompt and saves it (0600), and `/connect custom <NAME> <url>` adds any OpenAI-compatible endpoint. Three providers let you **sign in instead of pasting a key**, because their own documentation invites a third-party app to: `/connect huggingface` uses Hugging Face's device code flow (its [OAuth guide](https://huggingface.co/docs/hub/oauth) — a code to confirm on huggingface.co, with the `inference-api` scope only) through the project's own app, named by `hf_oauth_client_id` in `config.yaml`, and `/connect openrouter` uses [OpenRouter's PKCE flow](https://openrouter.ai/docs/guides/overview/auth/oauth), which shows a code to paste back and makes a key you can delete at openrouter.ai/keys. And `/connect chatgpt` signs in to a ChatGPT Plus or Pro plan through [OpenAI's Sign in with ChatGPT](https://developers.openai.com/siwc), which offers it to open-source apps running on your own machine: the page comes back to a one-shot listener on 127.0.0.1, so it works in a local install and never on a hosted one. Once you are signed in, `/model CHATGPT <model>` chats on the plan: the header says "Using ChatGPT plan" with a Manage usage link, and a usage limit stops and points there rather than retrying. Everything else is a pasted key. Either way the next turn uses the new key without a restart. **`/disconnect <name>` undoes it**: it asks first, then blanks the key (the entry's other settings stay for a later `/connect`) and says where to revoke the key itself, or signs out of the ChatGPT plan, revoking it at OpenAI; `--forget` also drops the plan's registration so the next sign-in can be another account. The selected model stays remembered, but the header says "Signed out | use /connect or add API key", including after a restart, so you can reconnect or choose another provider through OAuth or an API key.
143
-
144
- Both are gitignored. They are kept apart on purpose: provider keys are read by one module at model-call time, while tool keys are handed to code that talks to third parties. Mixing them would put every tool's secrets in reach of the credential path and vice versa. If it is ever unclear which file a new secret belongs in, it belongs in `.env` unless a model provider is going to authenticate with it.
145
-
146
- ---
147
-
148
- ## Running it
149
-
150
- **Run it from the directory you want to work in, not from the harness's own.** The directory you
151
- launch from is the *project* — workspace trust, `.venastine/`, `/init`'s destination and
152
- project-scoped memories all follow it — so launching from the install tree would make the harness
153
- its own project, and that is refused at startup (exit 2). Either of these is the answer:
154
-
155
- ```bash
156
- cd ~/my-project && python /path/to/venastine/main.py # the project is where you are
157
- AGENT_WORKSPACE=~/my-project python main.py # or name it, from anywhere
158
- ```
159
-
160
- ```yaml
161
- # or, in config.yaml, for a setup with no variable to set
162
- workspace_dir: ~/my-project
163
- workspace_is_project: true
164
- ```
165
-
166
- Working on the harness itself is `AGENT_WORKSPACE=./workspace`, which is the shipped layout and is
167
- exempt. `workspace_dir` alone is *not* a substitute for either route: it moves the workspace and
168
- leaves the project where it was, which is what `workspace_is_project` beside it is for.
169
-
170
- ```bash
171
- python main.py # chat, new thread
172
- python main.py --thread <uuid> # resume a thread
173
- python main.py --mode research "some query" # the ten-pass pipeline
174
- python main.py --provider OPENAI --model gpt-5.1 # override provider/model
175
- python main.py --tui # the full-screen interface
176
- ```
177
-
178
- The line-based CLI is the default and is never going away. The TUI is a nicer shell over the same code, and most of it is reachable from the CLI too: the CLI's `/help` lists its slash commands, then each TUI command it does not have yet and where to find it instead.
179
-
180
- Every launch flag is tabulated in the [CLI flag reference](#cli-flag-reference) below; every slash command under [The TUI](#the-tui), and the CLI's just below.
181
-
182
- A turn prints as it runs, one step at a time: the model's reasoning, what it said, and a line for each tool call as it starts. During a turn, Ctrl+C twice within two seconds stops it at the next safe point; the first press only says so, so a stray one costs nothing. At the prompt, Ctrl+C or Ctrl+D exits. The thread id is printed after the first response so you can resume later — and resuming **replays the conversation**, so you can see what you are picking up. Tool calls replay as one line each; their results do not, since a single research turn can carry hundreds of kilobytes of fetched pages.
183
-
184
- A line that starts with `/` is a command, as in the TUI, and never reaches the model; an unknown one is an error rather than a chat turn. The CLI has eighteen: `/help`, `/quit`, `/threads`, `/resume`, `/new`, `/goal`, `/agent`, `/skill`, `/grill-me`, `/effort`, `/model`, `/compact`, `/summary`, `/ref`, `/memories`, `/forget`, `/claims` and `/call`. They mean what the TUI's do: both shells read one catalog of commands, so a name, its arguments and its description cannot differ between them. `/threads` and `/ref` print a numbered list and ask for a number, or a thread id for one the list does not show. `/call` lists this conversation's tool calls, numbered, and `/call 3` shows the third in full: the whole command and what it returned, or a background session's output, or the run a subagent made. It is the CLI's version of ctrl+clicking a tool line in the TUI. `/model` here lasts for the session, since the CLI starts from `--model` or settings.json.
185
-
186
- ---
187
-
188
- ## How the research pipeline works
189
-
190
- One query goes in. Ten passes run, each in **its own fresh conversation** — they hand each other distilled JSON, never raw history, so a later pass cannot be talked into agreeing with an earlier one by reading how it argued.
191
-
192
- ```
193
- Pass 0 Plan what needs establishing, and what entities matter
194
- Pass 1 Generate the first full answer
195
- Pass 2 Extract break that answer into individually checkable claims
196
- D0 Route are there factual claims? (pure code)
197
- Pass 3a Ground check each factual claim against real sources
198
- Score Rate sources what each cited source is worth (pure code + embeddings)
199
- Pass 3b Critique attack each factual claim on its merits
200
- Pass 3c Completeness what did the answer never address at all?
201
- Pass 4 Assumptions what is being taken for granted and never stated?
202
- Pass 5 Tier score and tier every claim (pure code, no model)
203
- D1 Route which claims are flagged? (pure code)
204
- Pass 6a Revise rewrite only the flagged claims
205
- Pass 6b Re-validate re-ground and re-critique them
206
- D2 Route retries exhausted → fall back to UNVERIFIED (pure code)
207
- Pass 6c Annotate attach tier labels to claim text (templated, no model)
208
- Merge Assemble final claim set (pure code)
209
- Final Synthesise the report, written from the tiered claims
210
- ```
211
-
212
- **Six of those stages make no model call at all.** Pass 5, Pass 6c, D0, D1, D2 and the merge are ordinary Python. That is the point: the step that decides how confident to be is a formula you can read, not a judgement call the model gets to make about its own work.
213
-
214
- ### Confidence tiers
215
-
216
- Every claim comes out with a tier, a score, and the breakdown that produced it.
217
-
218
- | Tier | Meaning |
219
- |---|---|
220
- | **HIGH** | score ≥ 0.8 |
221
- | **MEDIUM** | score ≥ 0.55 |
222
- | **LOW** | score ≥ 0.3 |
223
- | **UNVERIFIED** | below 0.3 — **or any factual claim that could not be grounded, regardless of score** |
224
- | **UNVERIFIED_COVERAGE** | not a claim at all: something Pass 3c found the answer never addressed |
225
-
226
- For a factual claim the score is `0.5 × grounding + 0.35 × (1 − critic severity) − 0.15 per assumption flag`. Non-factual claims (opinion, projection, definition) are capped at 0.65 and can never reach HIGH, because there was nothing to ground them against.
227
-
228
- **A grounding is worth what its sources are worth.** The grounding term is scaled by the best source the claim has, scored as authority × relevance — so a claim supported by a primary source that plainly says it scores exactly what any grounded claim used to, and one whose only support is a social-media post or a content farm lands LOW and goes back through the revise loop to find something better. A source that is authoritative but does not discuss the claim counts for as little as a perfect match on a junk site; multiplying is the only shape that says both.
229
-
230
- Every number in the formula is tunable, from `settings.json`'s `confidence` and `source_scoring` sections or by editing the defaults at the top of `core/reasoning/confidence_scoring.py`. A value outside its range falls back to the default for that one constant and says so once — a mistyped weight should not refuse to start a ten-pass run, and should not silently discard the nine weights beside it that were right.
231
-
232
- A claim that stays flagged after two revise/re-validate rounds falls to UNVERIFIED rather than being quietly retried forever.
233
-
234
- ### What a source is worth, and how close it actually is
235
-
236
- Pass 3a used to hand back two numbers per cited source — how authoritative it is, and how well it
237
- matches the claim — and one model invented both. Nothing checked either, nothing consumed either,
238
- and no source text survived the pass, so nothing *could* have checked them. A real run on disk
239
- scored a Pinterest pin `similarity_score: 1.0` beside the Wikipedia article, on the same claim.
240
-
241
- **Authority is computed from the source, not asked for.** A domain class sets it — restricted
242
- registries (`.gov`, `.mil`, `.int`, `.edu`, and `gov.uk`/`ac.uk`-style second levels) at the top,
243
- then standards bodies and peer-reviewed publishers, down through news, preprint servers and generic
244
- hosts to blogs, forums, social media and content farms. Note that `.org` sits barely above `.com`:
245
- anyone can buy one, and treating it as trustworthy is the most common version of this mistake. The
246
- model may then adjust the computed number by at most ±0.15, and only with a stated reason — for
247
- what a domain cannot see, like a manufacturer's own spec sheet on an ordinary `.com`, or an opinion
248
- column on a masthead. An adjustment with no reason is discarded. Base, adjustment, reason and method
249
- are all recorded, so the score can be recomputed from the artifact.
250
-
251
- **Similarity is a cosine, when you configure an embedder.** `/embedder <PROVIDER> <model>` picks the
252
- model; the selection is probed rather than looked up in a table, so a provider without an embeddings
253
- endpoint or a chat slug passed by mistake fails at the prompt rather than three passes into a run.
254
- Each source's captured text is split into windows about the length of a claim and the best-matching
255
- one wins — embedding a 5000-character page whole averages twenty topics into one vector and makes
256
- every long source look equally irrelevant, which is the dilution the windows exist to remove. Raw
257
- cosine is not a 0–1 score (unrelated text sits near 0.1 on some models and above 0.7 on others), so
258
- a per-model band maps the useful range onto 0–1 and the raw cosine is recorded beside it.
259
-
260
- Without an embedder, every run says so in its first trace line and similarity stays the grounding
261
- model's own estimate — under an anchored rubric, and marked `similarity_method: "llm"` on every
262
- source, so no reader has to guess which numbers were measured. The model's estimate is recorded even
263
- when a cosine replaces it, so the two are comparable on every run.
264
-
265
- **The model's quote is checked against the page.** Pass 3a is asked for the verbatim span it relied
266
- on, and that span is looked for in the text the run actually retrieved. `quote_verified` has three
267
- answers: `true`, `false` — meaning the run fetched this page and the quoted words are not in it,
268
- which is a fabricated citation — and `null`, meaning there was nothing to check against, which is
269
- not the same thing.
270
-
271
- **Cited papers can be scored on their own standing.** With `scholar_lookup: true` in `config.yaml`,
272
- an arXiv or DOI URL is resolved against OpenAlex and scored on venue (peer-reviewed or preprint),
273
- citation standing, and author h-index. Citation standing is a percentile *within the paper's own
274
- field-and-year cohort*, measured by two counting queries rather than modelled — OpenAlex's own
275
- field-normalised metrics are null on preprints, and arXiv is where most cited preprints come from.
276
- A paper too young, or in a cohort too small, reports that and drops the term rather than scoring
277
- low; a retraction floors the source outright. It is **off by default**: it is the one network call
278
- this harness makes outside the tool layer, and an out-of-the-box run should make none you did not
279
- ask for.
280
-
281
- The knobs, under `confidence` and `source_scoring` in `settings.json`, each overriding a default in
282
- code:
283
-
284
- | Key | Default | Meaning |
285
- |---|---|---|
286
- | `confidence.source_quality_floor` | `0.25` | How little a grounding can be worth when its sources are weak — never zero, because a weak grounding still beats none |
287
- | `confidence.authority_full_credit` | `0.85` | Authority at or above which a source is not what limits the claim |
288
- | `confidence.grounding_weight_factor` | `0.5` | Weight of the grounding term |
289
- | `confidence.critic_weight_factor` | `0.35` | Weight of the critic term |
290
- | `confidence.assumption_flag_penalty` | `0.15` | Subtracted per assumption flag |
291
- | `confidence.disagreement_penalty_factor` | — | Retired in batch 232: still accepted, warns, and does nothing. A claim the ensemble disagrees about is checked instead of marked down |
292
- | `confidence.non_factual_score_cap` | `0.65` | Ceiling for claims that were never grounded |
293
- | `confidence.grounding_weights` | `1.0 / 0.5 / 0.0` | Per grounded / partial / ungrounded |
294
- | `confidence.tier_thresholds` | `0.8 / 0.55 / 0.3` | HIGH / MEDIUM / LOW; must stay ordered |
295
- | `source_scoring.window_chars` | `480` | Window size a source is chunked into |
296
- | `source_scoring.max_windows` | `24` | Windows scored per source |
297
- | `source_scoring.claim_min_chars` | `80` | Below this, a claim's entities are prepended to the query |
298
- | `source_scoring.similarity_floor` / `_ceiling` | per-model | Cosine band; unset means use the table for your embedder |
299
- | `source_scoring.authority_adjustment_cap` | `0.15` | How far the model may move a computed authority |
300
- | `source_scoring.domain_overrides` | `{}` | `{"host": score}` — how you add your own field's trusted domains |
301
- | `source_scoring.venue_weight` / `citation_weight` / `author_weight` | `0.4 / 0.4 / 0.2` | How a paper's score is composed |
302
- | `source_scoring.min_cohort_size` | `200` | Below this the cohort widens before a percentile is trusted |
303
- | `source_scoring.min_citation_age_days` | `60` | Below this, citation counts are noise and the term is dropped |
304
-
305
- A value outside its range falls back to the default for that one key and warns once per run, rather
306
- than refusing to start the run — unlike the compaction knobs above, where an incoherent value burns
307
- model calls on every turn. An *unknown* key still raises, as everywhere else in `settings.json`.
308
- `critic_model` and `embedder_model` are rejected there by name: both name a provider this harness
309
- sends research content to, and a project's `settings.json` outranks your own — use `/critic` and
310
- `/embedder`, or `config.yaml`.
311
-
312
- ### A pass that answers the wrong shape is corrected, then it stops the run
313
-
314
- Each pass is asked for a specific JSON structure, and each one is checked against that structure
315
- before anything is applied. A payload that parses but is not what the pass promised goes back to the
316
- model with the problem named — the same corrective turn a malformed one gets — and if it comes back
317
- wrong again the run fails, saying which pass and which field:
318
-
319
- ```
320
- Pass 3b: entry 0 has severity='0.0', which is string; expected number.
321
- Pass 2: expected a JSON array, got object. Return the array itself, not an object wrapping it.
322
- ```
323
-
324
- That matters more than it sounds. The failures worth preventing are not the loud ones: a model that
325
- answered about claim ids nobody issued used to produce a *finished* run whose trace said
326
- `Pass 3a: grounded 4 unique entities across 3 factual claim(s)` while grounding nothing, and then
327
- spent four more model calls concluding that nothing could be verified. Those counts are what the
328
- pass was **asked** about; the trace now reports what was actually applied — `grounded 2 of 3` — so a
329
- pass that half-worked says so.
330
-
331
- The run does not die over a single stray id: entries that resolve are applied, and only a payload
332
- where *nothing* matched is treated as a failure. Every number in `04_confidence.json`'s
333
- `score_breakdown` is one that was actually used, so the fields reconstruct the score they came with.
334
-
335
- ### Different models can check each other
336
-
337
- Set `CRITIC_MODEL` and passes 3a, 3b and 6c run on a *different* provider and model from the one that wrote the answer. A model checking its own output brings its own blind spots to the inspection.
338
-
339
- **Ensemble mode** extends the same idea to the answer itself. List `{provider_name, model}` pairs under `ensemble_models` in `config.yaml` (a settings.json key is deliberately absent — choosing providers multiplies spend, so it stays in the harness's own file) and Pass 1 runs once per entry, each candidate on its own provider and model. Fewer than two *distinct* pairs is refused: N copies of one model agree most confidently on that model's systematic errors, which is exactly where agreement has to mean something. Claims extracted from all candidates are pooled. A factual claim no more than half the candidates asserted is *contested*: it keeps the score its evidence earns and goes through the revise-and-revalidate passes to be checked, with the count in its feedback. Since batch 232; it used to be marked down instead, which no revision could undo. A candidate that fails mid-run is named and skipped; if only one survives, the run degrades to the ordinary single-response path rather than scoring an "ensemble of one". Artifacts come out as `01_candidate_1.md`, `01_candidate_2.md`, … numbered to match each claim's `asserted_by_candidates` tags.
340
-
341
- ### What you get out
342
-
343
- Every run writes `output/<run_id>/`:
344
-
345
- ```
346
- 00_plan.md 04_assumptions.json trace.md
347
- 01_raw_response.md 05_confidence.json report.md
348
- 02_claims.json 06_revisions.json report.pdf (if weasyprint installed)
349
- 03_grounding.json 07_review.json confidence_chart.svg
350
- 03_critic.json granted_calls.json sources/ code/
351
- 03_completeness.json pass_threads.json
352
- ```
353
-
354
- `sources/` holds what each cited page actually served: `index.json` lists every URL the run retrieved text from — with the tool, the timestamp, a content hash and the length — and one `<sha256>.txt` per document holds the text itself, redacted. That is what makes a similarity score checkable after the fact rather than a number you have to take on trust; set `persist_source_text: false` in `config.yaml` to keep the index and drop the text.
355
-
356
- In ensemble mode the Pass-1 slot is `01_candidate_1.md`, `01_candidate_2.md`, … — one file per surviving candidate, numbered to match the trace and each claim's `asserted_by_candidates` tags, since no single candidate is "the" response the claims came from.
357
-
358
- Runs are also persisted to the database, so a run that crashes halfway still leaves a record populated through its last completed pass — and so does one you kill with Ctrl+C.
359
-
360
- **Source use and publishing:** Fetched pages (`web_search`, `fetch_url`, `arxiv_search`, and MCP servers) are subject to their origin's terms, including `robots.txt` and Terms of Service — the harness does not bypass paywalls or ignore rate limits. `report.md` / `report.pdf` may quote third-party pages; do not republish them with large verbatim excerpts without rights — quote, paraphrase, and cite, and verify any claim that matters. See `PRIVACY.md` for what leaves your machine.
361
-
362
- ### Watching it happen
363
-
364
- A ten-pass run takes minutes. It reports as it goes, in both shells: pass boundaries, the tools each pass is calling, code-only stages, claim tiers as they land, retry rounds, and warnings.
365
-
366
- ```bash
367
- python main.py --mode research "does the claim about X hold up?"
368
- ```
369
-
370
- In the TUI, a sidebar tracks passes and a running tier tally; `/claims` or **ctrl+l** opens every claim with its tier, grounding status, assumption flags and score breakdown — during the run as well as after it.
371
-
372
- ### Having it review itself
373
-
374
- ```bash
375
- python main.py --mode research --review "some query"
376
- ```
377
-
378
- A reviewer agent reads the finished run and proposes corrections. **Each one is offered to you individually** — accept, reject, refine, or reject everything. Nothing is applied without your say-so, and there is deliberately no "accept all" button, because an injected instruction only needs one reflexive yes. If nothing can ask you (a piped or scripted run), the review still runs and still records what it found, but applies nothing.
379
-
380
- ---
381
-
382
- ## Security model
383
-
384
- The harness assumes the model is working with untrusted text — web pages it fetched, files it read, output from third-party MCP servers — and that any of it may be trying to steer the next tool call.
385
-
386
- ### Every tool says what a call to it may cost
387
-
388
- Approval answers *whether* a tool may run. It says nothing about how long it may run for, and until
389
- recently nothing else did either: a maths tool handed a large enough number simply never came back,
390
- taking the turn — or an unattended ten-pass run — with it.
391
-
392
- Each registered tool now declares one of three answers, and a tool registered without one fails at
393
- startup rather than at its first call:
394
-
395
- | | |
396
- |---|---|
397
- | **compute** | The six maths tools. Pure functions of their arguments with nothing to interrupt them from the inside, so they run in a separate process that can be stopped — 20 seconds by default, plus CPU and memory ceilings on Linux |
398
- | **io** | Anything that reads a file, fetches a page or talks to an MCP server. Each already carries its own limit: a request timeout, a size check before opening, a sandbox |
399
- | **human** | `ask_user` and `spawn_subagent`, which wait on a person or on a separately metered sub-run. A ten-minute pause here is the feature |
400
-
401
- The distinction between the first two is not bureaucratic. A timeout wrapped around a blocking read
402
- can only stop *waiting* — the work carries on — so declaring an operation bounded when it is not
403
- would produce a harness that reports timeouts that never happened. Compute tools get a bound that
404
- genuinely stops them; io tools have to already have one, and three that did not were fixed:
405
-
406
- ```
407
- before after
408
- edit (on a 30 MB file) 60.0 MB 0.0 MB rejected before opening, as `read` always did
409
- read_project_doc 60.0 MB 0.1 MB one page costs one page, not the whole document
410
- fetch_url unbounded capped streamed, so a hostile body stops at the cap
411
- ```
412
-
413
- When a compute tool does hit its limit, the model is told which tool and which limit, so it can ask
414
- for something smaller instead of retrying the same call:
415
-
416
- ```
417
- symbolic_math exceeded its 20s limit and was stopped. The inputs given are too
418
- large for this operation -- try smaller values.
419
- ```
420
-
421
- ### Access control: stricter always wins
422
-
423
- Two separate questions, asked in this order, and they never blend into one score:
424
-
425
- 1. **May this tool be called at all?** — a logical AND across the global config and every active layer (the current agent, each skill it activated). A tool disabled globally can never be re-enabled by anything else; that check runs first and unconditionally.
426
- 2. **Does this specific call need you to approve it?** — a logical OR across the same layers plus the tool's own dynamic check.
427
-
428
- Because approval ORs, an override can only ever *add* a prompt. There is no way to spell "this tool no longer needs approval" from an agent or skill definition — and since those can arrive with a repository you cloned, that asymmetry is the design rather than a gap.
429
-
430
- ### What needs approval by default
431
-
432
- | | |
433
- |---|---|
434
- | No approval | `web_search`, `fetch_url`, `arxiv_search`, `get_time`, the six maths tools (`symbolic_math`, `linear_algebra`, `probability_stats`, `discrete_math`, `logic`, `geometry`), `load_skill`, `pin`, `unpin`, `ask_user`, `todo_write`, `read_project_doc`, and the three that act on this conversation's own background sessions (`shell_sessions`, `shell_output`, `shell_kill`), and `shell_input` — typing into an interactive shell you already approved (a line naming a protected path still asks, and a Ctrl-C never does) |
435
- | Depends on the call | `read`, `view_image`, `write`, `edit` — decided per path, and all four are denied by default anyway. `view_image` is also only offered where the image can reach the model: a provider marked `accepts_images` in `providers.json`, outside a research pass |
436
- | Always | `shell` and the three that start a session (`shell_background`, `shell_monitor`, `shell_interactive`), `spawn_subagent`, `remember`, `write_project_doc`, and **every MCP tool** |
437
-
438
- Every registered tool appears in that table, and a test asserts it (audit #125): `ToolPermissions` and `ToolApprovals` are plain dataclasses, so "did the table keep up with the registry" is a question the suite can answer instead of a reader. `write_project_doc` is the one the omission mattered for — it is what `/init` uses to write documents into a repository, and §24's I1 gives it a fixed allowlist of document *names* with no path parameter precisely because it is dangerous enough to constrain.
439
-
440
- `ask_user` is ungated for a reason worth stating, since a table of default approvals is exactly where it belongs: an approval-gated tool is not *advertised* where nothing can ask, so gating the tool whose entire job is asking would make it invisible rather than deniable.
441
-
442
- `pin` and `remember` sit either side of the line that matters: pinning a message is thread-scoped and undoable (`unpin` releases it), while remembering something outlives the conversation and silently shapes ones you have not started yet.
443
-
444
- ### `shell` is classified, not just approved
445
-
446
- `shell` ships **disabled** (`tool_permissions.shell: false` in `config.yaml`) and cannot be enabled at runtime, so none of this applies to a default install. If you do enable it, the gate is `shell_approval_mode` in the same file:
447
-
448
- | mode | behaviour |
449
- |---|---|
450
- | `always` | every command is asked about, whatever it does |
451
- | `tiered` | **shipped.** The classifier decides — see below. Only a read-only command runs unasked; anything that can run code asks, even inside the container |
452
- | `contained` | anything the container confines runs unasked unless it needs network, code included; reads outside the workspace and network commands still ask. Flagged on the startup banner and the TUI badge |
453
- | `never` | nothing is ever asked about |
454
-
455
- There is deliberately no second switch: `tool_approvals` has no `shell` key, so nothing here can disagree with the mode. An agent's `approval_overrides` still reaches shell with the same one-way power -- an agent can demand approval for a command the mode would auto-approve, and can never wave one past a gate the mode set. An unknown mode string raises at startup rather than falling back to a default — one direction of that default asks about everything and the other about nothing, and a typo cannot pick.
456
-
457
- Under `tiered` and `contained`, each command is classified **once** into what it can do, and the same answer is read by the approval check and by the sandbox that runs it:
458
-
459
- | tier | what it is | where it runs | asked under `tiered`? | under `contained`? |
460
- |---|---|---|---|---|
461
- | `INERT` | read-only command, every argument inside the workspace | container (host when no container runtime is available) | no | no |
462
- | `HOST_READ` | read-only, but an argument reaches outside the workspace | host | **yes** | **yes** |
463
- | `SANDBOXED` | anything else, no network — it may run code | container | **yes** | no, if a container runtime (Docker or Podman) is confirmed up |
464
- | `SANDBOXED_NET` | **any** word is on the network allowlist (`curl`, `pip`, `git`, …) — first word only for an INERT command, which cannot chain | container, with network | **yes** | **yes** |
465
- | `UNKNOWN` | could not be characterised at all | — | **yes** | **yes** |
466
-
467
- Under `tiered` the auto-approved set is narrower than the `read` tool's, which is already unprompted inside the workspace. There is **no list of interpreters** behind that: `python -c` is the obvious case, but `pytest` runs a `conftest.py`, `make` runs a Makefile, and `"python"`, `python3.13` and `echo x | python` are all the same call to a shell, so every command that is not `INERT` is treated as able to run code. Under `contained` a `SANDBOXED` command runs unasked and can do anything code can do inside the container — corrupt the workspace, as `write` and `edit` already can, or read a `.venastine/` directory the workspace contains — bounded to 1 CPU, 2 GB, 200 processes, 120 seconds, no network and no host filesystem.
468
-
469
- **The argument rule does not parse, deliberately.** Every token after the first is read as a path and required to stay inside the workspace; a flag like `-la` passes only because it is *relative*, not because anything recognised it as a flag. Refusing to interpret shell syntax is what makes the check trustworthy — a classifier that parses is a shell parser, and a parser that is wrong auto-approves something dangerous. The cost is occasional false positives: `grep /etc/passwd notes.txt` searches for a string that looks like a path, and costs one prompt.
470
-
471
- **Quoted arguments are never inert.** The corollary of not parsing: the raw tokens have to be the real tokens. A quoted command is classified `SANDBOXED` and goes to a container, because the classifier splits on whitespace while the executor splits with `shlex` — and `shlex` strips quotes, so `cat "/etc/passwd"` read as one token *inside* the workspace and then ran as two tokens naming the host's file. Under `contained` with Docker this costs nothing: `cat "my notes.txt"` is still auto-approved, it simply runs in the container. Under `tiered` it asks, as every command that is not `INERT` does. Fixed in batch 37; `'single quotes'` and `--file="/etc/x"` did it too.
472
-
473
- **Escaped arguments are never inert either.** The same corollary, one character further, and it
474
- took a second batch to find: `shlex` consumes `\` exactly as it consumes quotes, so
475
- `cat \/etc\/passwd` read as one relative token inside the workspace and then ran as `/etc/passwd` on
476
- the host — measured on a POSIX host at the shipped default. With `\` rejected the character class is
477
- now **closed** under `shlex`, which consumes exactly whitespace, `'`, `"` and `\`: the classifier's
478
- tokens and the executor's are provably the same list. On Windows this costs a backslash path such
479
- as `cat sub\dir\notes.txt`, which moves to the container and fails there — use forward slashes.
480
-
481
- **These settings are read once, at startup.** Since batch 40 `SHELL_APPROVAL_MODE`, both fallback
482
- flags and `REDACT_TOOL_OUTPUTS` are bound into a frozen posture (`security/posture.py`) rather than
483
- consulted at each decision, so nothing running in-process can move them mid-session. If any of them
484
- is set to something weaker than the shipped default, the harness says so at launch — on stderr, in
485
- `app.log`, and as a badge in the TUI sidebar for as long as the session lasts.
486
-
487
- **An approved host read still reads the host.** `cat /etc/shadow` is asked about; if you say yes, it runs on the host, because that is what you approved. Routing it into a container would answer a different question than the one you were asked.
488
-
489
- **`never` is the old unbounded behaviour, kept on purpose.** In that mode `cat ~/.aws/credentials` runs on the host, unprompted, and its output goes into the model's context. It is reachable by writing the word `never` — which is the fix for [#157](https://github.com/YahyaHammad/Venastine-Research-Harness/issues/157): previously you reached it by switching off a field that read like "stop nagging me".
490
-
491
- `shell_approval_mode` is **rejected** in `.venastine/settings.json`, by name and with a reason. A project's settings beat your own, and a cloned repository must not be able to set this. Set it in `config.yaml`.
492
-
493
- If your workspace contains a `.venastine/` directory, it is bind-mounted **read-only** inside the container, so a sandboxed command cannot rewrite the context and MCP definitions that feed later prompts. This covers writes on the container path only, under Docker or Podman — not reads, and not the subprocess fallback.
494
-
495
- **The workspace may not be the harness.** The container mounts your workspace read-write, and a sandboxed command with no network is auto-approved inside it — so a workspace pointing at the harness's own directory would be unattended write access to the code about to run next. `AGENT_WORKSPACE` is refused at startup, and by the sandbox, when it *is* or sits *inside* the harness install tree or `~/.config/venastine/`. **Since batch 107 the implicit route is refused too**: with the variable unset the project is the directory you launched from, so launching from the install tree made the harness its own project -- the same state, reached by saying nothing instead of by saying it. The two artifact directories `workspace/` and `output/` stay usable, which is the shipped layout; everything else in the install tree is refused, including a module added in a later release — it is an allowlist, so it fails closed. When one of those trees is *nested inside* your workspace instead — a workspace set to your home directory, say — there is nothing to refuse, so it is bind-mounted read-only, along with `providers.json`, the conversation database and the log directory. The guard names the harness that is *running*, so pointing a globally-installed `venastine` at a development clone of its own source still works.
496
-
497
- **From approval to execution, one answer throughout.** The classification is computed once per call and the same profile is handed to both the approval check and the sandbox, so what was approved is what runs. **The container comes from Docker, or from Podman when Docker cannot run one** — probed once per process, Docker first. Podman is used only if it can enforce the memory, CPU and process limits below: a rootless Podman on cgroups v1, or without those controllers delegated to your user, accepts the flags and ignores them, so it is refused and the reason is logged and shown. An inert command runs in that container as a plain argument list with no shell, and on the host only when no runtime is available. Anything else shares the probe's answer between gate and runner: if a runtime was up when the call was approved but gone when it executes, and the only route left is the fallback, the call returns an error telling the model to retry rather than silently downgrading onto the host. With no container runtime available and `allow_insecure_sandbox_fallback: true` in `config.yaml`, non-inert commands fall back to a weakly-isolated host subprocess — prompted per run unless `auto_approve_sandbox_fallback: true` opts that prompt away. Inside the container the workspace is mounted at `/workspace` and output comes back truncated at 50,000 characters (`max_read_chars`); the container runs under a 120-second wall clock, 2048 MB of memory, a single CPU core and a 200-process cap, while the weak fallback enforces its own rlimits instead — 30 CPU-seconds and the same memory ceiling — **on Unix only**. `rlimit` does not exist on Windows, so there that route runs under the wall clock and nothing else, which is worth knowing before you turn it on: it is the route with no filesystem isolation, and on Windows it is also the route with no memory or CPU ceiling. **A third backend exists and ships off: WSL.** With `allow_wsl_backend: true`, `shell`, `shell_background` and `shell_monitor` take a `backend` field the agent sets per call, and `backend: "wsl"` runs the command in a WSL distribution (`wsl_distro`, or WSL's default) instead of the container. It is there for work that genuinely needs your machine or a Linux toolchain the image does not carry — and it gives up everything the container provides: your own files, the network always on, no memory or process limits, no read-only bind over `.venastine/`, and Windows interop that no argv or environment choice can switch off. So it is treated as uncontained for every tier: under `tiered` and `contained` only a read-only command whose arguments are all inside the workspace runs without a prompt, a command naming a protected path segment is refused outright rather than asked about, and the backend appears on the startup banner and the sidebar badge for as long as it is on. An interactive shell cannot run there yet. **A fourth backend exists and also ships off: SSH.** With `allow_ssh_backend: true` and a host configured (`ssh_host`, `ssh_user`, `ssh_remote_workspace` and a PINNED `ssh_host_key`), `backend: "ssh"` runs the command on that machine. It is the strictest of the four to use and the least protected to run on: **nothing there is auto-approved, not even a read-only command**, because the check that decides whether a command's arguments stay inside the workspace resolves them against this machine's filesystem and would be answering about the wrong one. Authentication is a key or a running `ssh-agent` and the harness never asks for or holds a passphrase; a host key that changes is refused rather than accepted; and two things are disclosed rather than fixed — ending a session does not kill the remote command (its in-guest `timeout` does), and `write` saves locally while the shell runs remotely. **The harness can hold the credentials those backends need, encrypted at rest.** `/secrets` in the TUI (or `--secrets` on the CLI) stores named values -- `ssh.<host>.key_passphrase`, `ssh.<host>.login` -- in `~/.config/venastine/secrets.json`, sealed with AES-256-GCM under a master passphrase you type once a session. That is what lets an encrypted SSH key or a password-authenticated host work at all: before it, an encrypted key with no agent simply failed. A stacked `publickey,password` host works too. Nothing is taken from the command line -- every value is read at a masked prompt, because an argv is readable by every process on the machine and lands in your shell history. The file is useless without the passphrase, so a shell command the agent runs reads ciphertext; the plaintext lives in process memory only and is dropped on `/secrets lock`, on quit, and on anything unexpected. A stored value never reaches the model: it is stripped from tool output whatever your redaction setting says. **A command can also be run as root, on those two backends and nowhere else.** A call may set `needs_root`; the harness then prefixes `sudo -k -S -p '' --` and supplies the password stored for that machine as `wsl.<distro>.sudo` or `ssh.<host>.sudo`, on the command's standard input and nowhere else -- never in an argv, an environment or a log, and the command behind `sudo` has its own stdin closed so it cannot read the password either. The container is refused because a command there already runs as root, and the host fallback because Windows elevation is a consent dialog rather than a password prompt. **You are asked every single time**, above both sandbox opt-ins and in every approval mode but `never` -- and the question is asked whether the call declares `needs_root` or merely writes `sudo` itself, so the declaration is not a thing to forget your way around. If no password is stored for that machine the call is refused outright and the refusal names the entry to create: the stored secret is what turns root on at all, and there is no separate switch for it. Two environment knobs affect the mechanics: `AGENT_SHELL` overrides the detected host shell (bash on Linux/macOS, PowerShell on Windows), and `AGENT_SANDBOX_IMAGE` swaps the default `docker.io/library/python:3.13-slim` image (fully qualified, so Podman resolves it without a short-name alias).
498
-
499
- ### "Headless" means *unable to ask*, not "not a GUI"
500
-
501
- When nothing can put a question in front of a human, approval-gated tools are **hidden from the model entirely** rather than offered and then denied. This is not cosmetic. A tool that is advertised and always refused gets chosen again and again, and the only trace is a denial string buried in a tool result — that exact bug shipped once here, in which `fetch_url` was registered, documented as working, and denied on every call for its whole life. Registering a tool without declaring its permissions now raises at import time instead.
502
-
503
- The rule that falls out of this: **inability to ask is never treated as permission to proceed.**
504
-
505
- Two consequences, both easier to get wrong than they look:
506
-
507
- - **A grant is an answer, so a granted tool stays visible.** "Nothing can ask" is not "nothing has answered" — a pre-flight grant answered the question before the call existed. Getting this wrong is what made `--grant-tools` do nothing on its own for three sections (see below).
508
- - **A headless run cannot spawn a subagent at all**, because spawning is itself approval-gated. That is also why a spawned subagent *keeps* its gated tools: the only runs that can spawn have a human reachable, and the child inherits that route. It is not a separate permission — it falls out of this rule.
509
-
510
- When a gated call *is* refused because nothing could ask, the model is told which of the two reasons applies: the tool is unavailable however it is called, or it needs approval **for these arguments** and may not for others. "Requires approval and was not given" invites a retry that cannot succeed, and the model spends its remaining steps discovering that.
511
-
512
- ### Content policy, on the way in and on the way out
513
-
514
- Symmetric, and applied centrally to every tool in every mode rather than by tools that opted in:
515
-
516
- - **Arguments are refused, not rewritten.** If a tool call carries something matching a credential pattern or a URL on the blocked-domain list, the call is refused. Silently rewriting an argument would run the tool with parameters neither you nor the model chose, and then report success.
517
- - **Results are redacted.** Anything key-shaped in a tool's output becomes `[REDACTED]` before it reaches the model, the transcript, the database **or the log file**. This recurses through nested structures — third-party MCP servers return arbitrary JSON, and that was once the one path nothing scanned — and it covers *every* key of a result, not a list of expected ones, because the two search tools returned theirs under a key the list did not name. The log was a fourth sink and an unlisted exception rather than an accepted one: a failing tool's traceback carries the request that produced it, which for an HTTP client is a URL with the key in its query string.
518
- - **URLs are checked before every request, including redirects.** `fetch_url` follows redirects by hand and re-checks each hop, so a public URL that redirects to a blocked domain or into your private network is refused *before* the request is issued. Addresses that are not publicly routable — loopback, private ranges, link-local, and the cloud metadata endpoint at `169.254.169.254` — are refused outright. The blocklist matches subdomains. **Known limitation:** the address check resolves and then hands the URL to the HTTP client, which resolves again, so a host whose DNS changes between the two is not covered.
519
- - **The scan fails closed.** Traversal is depth-bounded so a hostile structure cannot exhaust the stack, and hitting that bound redacts rather than passing the value through. A bound that emits unchecked data is just a documented bypass.
520
- - **Refusal reasons never quote the secret.** Explaining that a credential leaked, by printing it, would leak it into model context, the transcript and the database.
521
- - **Tool arguments are redacted before they are truncated** for display — truncating first can cut a key below the length its pattern needs to match, which turns a display feature into a disclosure.
522
-
523
- ### Project directories are untrusted until you say otherwise
524
-
525
- A repo you clone can carry project content the harness will load: `.venastine/` — agents, skills, `settings.json`, `mcp.json` — and a root `AGENTS.md`, which is the project context document. On first run in a directory you are shown what it contains and asked once — the file list, `settings.json` and `mcp.json` verbatim, the opening of `AGENTS.md`, and **every agent's and skill's description**, because all of those go into the system prompt of every run in the project the moment you say yes. A repo with an `AGENTS.md` and no `.venastine/` is asked about too; a repo with neither has nothing to trust and is silent. Until then that content is **absent, not loaded-and-disabled**. Trust is keyed to the resolved path *and* a content hash, so it does not silently carry over when the files change.
526
-
527
- ```bash
528
- python main.py --trust-project # for CI and scripts
529
- ```
530
-
531
- For MCP servers, agents and skills, precedence is **harness > user > project** — inverted from the usual "more specific wins", because here "more specific" means "arrived with someone else's repository".
532
-
533
- ### Granting tools to an unattended run
534
-
535
- A ten-pass research run has no human at the keyboard for minutes at a time. Two independent controls, both off by default:
536
-
537
- ```bash
538
- python main.py --mode research --grant "query" # pick from a list, interactively
539
- python main.py --mode research --grant-tools mcp__files__search "query"
540
- python main.py --mode research --attended "query" # approve every gated call as it happens
541
- ```
542
-
543
- The limits are the interesting part:
544
-
545
- - **A grant only covers tools with no per-call gate**, which in practice means MCP tools — literally so: **on a stock install with no MCP server connected, the picker is empty.** `shell` and the file tools decide case by case from the actual arguments, so granting the *name* would authorise a call you never saw; nobody ticking a checkbox labelled "shell" is agreeing to every command for the rest of the run. Those fall back to being asked. Everything else is either ungated already or excluded below.
546
- - **A grant is per tool, and shows you what each one says it does.** MCP exposes no read-only/write metadata, so nothing can tell you that one granted tool searches a library and another posts to a channel; showing its own description is the whole of informed consent here.
547
- - **Every tool declares how far approving its *name* goes**, and both places that can pre-grant — an unattended run, and the sign-off when the model spawns a subagent — read the same declaration. They used to keep separate lists, which is how the sign-off ended up offering the two tools below.
548
- - **`spawn_subagent` and `remember` can never be pre-granted, anywhere.** Approving a spawn *is* the sign-off for the child's entire tool set, so pre-granting it would compound one yes into unbounded delegated authority. A memory outlives the run. An *attended* run can still approve either one live — a per-call human decision, which is what the gate is for.
549
- - **`write_project_doc` can be signed off for one turn, but never pre-granted to an unattended run.** It resolves a document *name* to a path and overwrites it with no diff and no second question, and one of the files it can write is the project context injected into later sessions. A human answering about one named agent for one turn is consent; one tick covering ten unattended passes that are reading fetched web pages is not.
550
- - **A grant makes the tool visible to the model, not just permitted.** These are two different things and the difference was a real bug: gated tools are normally withheld from a run that has no way to ask about them, and until recently the grant was not consulted when deciding that — so `--grant-tools` *on its own* authorised a tool and then sent the model the same list as an unflagged run, while printing that it had authorised something. It only worked alongside `--attended`, which is not the mode any of this is for. A stale grant still cannot widen anything: what may be pre-granted is re-checked against the tool's own declaration at the point the list is built.
551
- - **Running out of grant budget degrades to asking, not to failing.** One budget is shared across all ten passes, and it does not retract a tool mid-run — the ceiling changes *when* you get asked, never what the model can see.
552
- - **Grants are never persistable, and the setting is rejected by name** so nobody "fixes" the omission. A persisted *mode* can only ever add prompts; a persisted *grant list* could only ever remove them — and `settings.json` is the one config file where a project's values beat yours.
553
-
554
- ### MCP servers: allowed by default, trusted by default never
555
-
556
- MCP tools can be called without you naming them, but every call is approved individually unless you add `"autoApprove": true` to that server. They are third-party code the model can reach, and config files grow entries that installers appended.
557
-
558
- ---
559
-
560
- ## Everything else
561
-
562
- ### Long conversations condense themselves
563
-
564
- Older turns are summarised automatically as a thread grows. **The archive is never edited** — the full history is always recoverable, and summaries are never written to disk as messages.
565
-
566
- Two summarisation strategies exist:
567
-
568
- - **`chain` (the default)** — each compaction summarises the *previous summary plus whatever followed it*. The input never grows past summary-plus-tail, so cost stays constant per compaction forever. The trade: loss compounds over a very long-lived thread, since a summary is being made of a summary.
569
- - **`rederive`** — each compaction summarises the *original messages*, so exactly one summarisation step ever sits between what you said and what the model sees. Fidelity-optimal; the cost is that the whole covered span is re-sent every time.
570
-
571
- Whichever you configure (`compaction.strategy` in settings.json), a span too large for one call falls back to chain with a warning, and one too large even for chain has its oldest material truncated — stated in both the instruction and the stored summary, never silently.
572
-
573
- `pin` keeps recent turns out of any summary (capped at half the compaction trigger per call — a pin is a permanent floor, so refusing beats trimming); `unpin` releases it again when pinned detail goes stale. `/compact` in the TUI triggers a compaction by hand. **When compaction runs depends on what the thread is**: a chat thread folds at a share of the model's context window (85% by default, so 850k on a 1M model and 170k on a 200k one); research passes and subagents compact only at a hard backstop just under that window, wherever they are resumed — spending a model call on a judgement nobody is watching is not worth it mid-run. The chat trigger used to be a flat 40k regardless of model, which meant a 1M-window thread was condensed at 4% of its window.
574
-
575
- The knobs, all under `compaction` in `settings.json`, each overriding a default in `config.yaml`:
576
-
577
- | Key | Default | Meaning |
578
- |---|---|---|
579
- | `trigger_tokens` | `40000` | Measured context size that fires automatic compaction |
580
- | `warning_margin_tokens` | `8000` | How far before the trigger you are warned — room to pin something or wrap up first |
581
- | `keep_recent_tokens` | `4000` | Most-recent tokens that always stay verbatim |
582
- | `keep_recent_turns` | `3` | Turn floor beside the token floor — whichever protects more wins, plus the current turn, which never folds |
583
- | `strength` | `3` | Target compression ratio, 1–5: keep ~40% at 1 down to ~5% at 5 |
584
- | `max_retries` | `2` | Corrective re-asks when a summary misses its target ratio |
585
- | `strategy` | `"chain"` | Or `"rederive"`, as above |
586
-
587
- `/trigger` and `/window` override those numbers, and they have different lifetimes on purpose. `/trigger` is for this session only: never written to disk, and `/model` clears it, so switching away and back gives you the derived value. `/window` is REMEMBERED — a context window is a fact about a deployment rather than a preference about a session, and one you must retype after every model switch is one nobody sets. It is kept per `(provider, model)`, for every pair you have answered for, and it outranks both what the provider reports and the built-in table. `/window off` restores the derived value. Both are bound to the `(provider, model)` they were set for, so an agent pinning its own model or a critic-routed pass uses that model's own value rather than a number tuned for a different one. `/compact --strength N` overrides strength for that one invocation and persists nothing; an unknown flag there is an error rather than an ignored typo, because compacting at the default while you believe you asked otherwise looks exactly like a compaction that obeyed you. The relationships between these values are validated rather than trusted — the warning margin must sit strictly below the trigger, and the keep-recent floor strictly below it too — so an incoherent set is refused at startup instead of firing compaction at nonsense times.
588
-
589
- A replayed thread always shows what you originally said, never the summary — the archive is what is replayed, so a compacted conversation reads back the way you had it.
590
-
591
- ### Durable memory
592
-
593
- `remember` saves a fact that outlives its thread, scoped to this project or to everything — **with your approval each time**, which is also why it is unreachable from any unattended research pass.
594
-
595
- ```bash
596
- python main.py --memories # list what's visible from here
597
- python main.py --forget <id> # delete one, by id
598
- ```
599
-
600
- Removal is by id, never by substring: a substring matching two memories would have to pick one, and picking silently deletes something you did not name. Injection is capped at 50 most-recent, and the model is told when it is seeing a truncated set.
601
-
602
- ### Agents and skills
603
-
604
- Markdown files with YAML frontmatter, discovered from three tiers (built-in, yours at `~/.config/venastine/`, the project's at `.venastine/`). Agents set a system prompt and a tool policy; skills pin a body of instructions into the session. `/agent`, `/skill`, `/goal`, `/grill-me`.
605
-
606
- A skill declaring `additional_tools` is stating a *need*, not granting anything — activation proceeds and tells you what is missing.
607
-
608
- An agent declares `spawnable` — whether the `spawn_subagent` tool can actually feed it. A task string in a fresh thread is all a spawn can pass, and an agent that needs a transcript, a thread or a finished research run cannot be given one; spawning it anyway produces a confident answer about nothing. Your own agents are not spawnable unless they say so.
609
-
610
- Eleven ship. Five are not spawnable, each because a real caller supplies something a task string cannot carry — `compactor` (a stretch of transcript), `initializer` (a document manifest), `pipeline-reviewer` (a finished research run), `grill-me` and `plan` (the live conversation). Six are:
611
-
612
- | agent | for | reach it with |
613
- |---|---|---|
614
- | `plan` | designing an approach before the work starts — reads what exists, names the decisions, says what would make the plan wrong | `/agent plan` |
615
- | `explore` | finding where something lives and how it is wired, in a codebase or in the literature, and reporting locations and evidence | `spawn_subagent`, or `/agent explore` |
616
- | `review` | reading a finished change or document against what it claims to do, and reporting defects with the evidence for each | `spawn_subagent`, or `/agent review` |
617
- | `build` | implementing a specified change from pointers — reads what exists, makes the smallest diff, reports what changed plus how it was verified | `spawn_subagent`, or `/agent build` |
618
- | `test` | verifying a change against its claim — reproduces, runs the checks, reports pass/fail with the exact command and what was not covered | `spawn_subagent`, or `/agent test` |
619
- | `writer` | turning notes, claims or sources into clear structured prose for a named audience — reports, READMEs, changelogs, decision records | `spawn_subagent`, or `/agent writer` |
620
- | `general` | scoping a task's intent, splitting it into self-contained sub-tasks, delegating to specialized subagents in parallel, synthesizing their answers | `spawn_subagent`, or `/agent general` |
621
-
622
- `build`, `test`, `writer`, `explore` and `review` are leaves: they take a task string as their entire input and cannot spawn further. `general` is the one spawnable branch — the spawning discipline lives there and nowhere else, so users who want a less constricted experience change one file or add their own. `plan` keeps its own spawning ability for interactive `/agent` use but is not itself spawnable.
623
-
624
- An agent can also name **which** agents it may spawn, with `spawn_targets`. `plan` is the shipped case: it may spawn `explore`, `review`, `writer` and `test`, and asking it for `build` or `general` is refused with a reason rather than quietly obeyed. That is the point of planning as its own turn — you read the plan and change your mind before anything is written. Say nothing and an agent may spawn anything spawnable, which is the default every definition had before the field existed; a list only ever narrows, and narrows again for anything it spawns in turn.
625
-
626
- `explore`, `review`, `build`, `test` and `writer` are **read-only or write-only by omission**: none of them lists `spawn_subagent`, `remember` or `write_project_doc`, so no configuration makes one reachable. `build` is the exception that proves the shape — it declares `write`/`edit` because implementing means writing, while the other four simply absent them. They all list tools (`read`, `shell`) which are [denied by default](#what-needs-approval-by-default) and cannot be enabled at runtime — so on a stock install `explore` works from `read_project_doc` and the three network tools, and all become code agents only where you have enabled file access in `config.yaml`. Approving a spawn of a leaf grants nothing standing: `shell` carries a per-call gate, so it is excluded from every grant path by name and each non-inert command still asks.
627
-
628
- Fourteen skills ship, under `security/`, `crypto/`, `math/`, `research/` and `software/` — methodologies for reviewing code, debugging, designing tests, designing experiments, statistical inference, reproducibility, evaluating sources, technical writing, numerical methods, formal specification, literature review, proof writing, cryptography verification and cybersecurity research.
629
-
630
- #### Writing your own
631
-
632
- Drop `.md` files into `~/.config/venastine/agents/` or `.../skills/` for yours, or into the project's `.venastine/agents/` once trusted. Skills may also sit in category folders — the folder is grouping metadata; the name stays global. Same-name collisions resolve harness > user > project, and a harness name can never be shadowed at all.
633
-
634
- Agent frontmatter fields:
635
-
636
- | Field | Type | Default | Meaning |
637
- |---|---|---|---|
638
- | `name` | string | *required* | Catalog identity, global across tiers |
639
- | `description` | string | `""` | One line into every system prompt — collapsed to a single line and capped at 300 characters (see below) |
640
- | `model`, `provider` | string | inherit session | Pin this agent's own model/provider; `/model` tells you when one is active |
641
- | `allowed_tools` | list | everything allowed | A whitelist that only ever narrows — nothing can widen it |
642
- | `approval_overrides` | mapping | `{}` | Can only ever *add* prompts, never remove one |
643
- | `use_project_context` | bool | `false` | Inject the project's root `AGENTS.md` into the system prompt |
644
- | `use_memory` | bool | `true` | Inject durable memories (plain chat counts as opted in) |
645
- | `max_steps` | int ≥ 1 | caller's ceiling | **Replaces** the caller's ceiling rather than narrowing it — a value above `MAX_ITERATIONS` raises it, making this the one frontmatter field that can widen anything; an invalid value is repaired to the default with a warning naming what it read |
646
- | `spawnable` | bool | `false` for your files | Whether `spawn_subagent` may feed this agent |
647
-
648
- Skill frontmatter fields: `name` (required), `description`, and `additional_tools` — a list of tool names stating what the skill's methodology *depends on*. It grants nothing: activation proceeds and tells you what is missing under the current agent.
649
-
650
- ### A description is text, and the prompt treats it as one line
651
-
652
- An agent's or a skill's `name` and `description` go straight into the system prompt, so they are collapsed to a single line and capped at 300 characters when the file is read. Without that, a description written as a multi-line YAML block escapes its bullet and renders as a section of the prompt in its own right — indistinguishable from one this harness wrote. The cap is generous next to real ones: the longest description shipped here is 171 characters.
653
-
654
- ### MCP servers
655
-
656
- Configured in `mcp.json`, at `~/.config/venastine/mcp.json` or `.venastine/mcp.json`. **The user-level one is created empty on startup if it is absent**, and the launch says where it is — two plausible homes and no way to tell from inside a session meant an edit could land in a file the harness never reads. `/init --config` creates an empty project one to fill in. Claude Code compatible, and unrecognised keys are ignored so a config shared with another client works as-is:
657
-
658
- ```json
659
- {"mcpServers": {"files": {"command": "npx", "args": ["-y", "@example/server"]}}}
660
- ```
661
-
662
- Tools are namespaced `mcp__<server>__<tool>`. A server that fails to connect is named and skipped, never fatal.
663
-
664
- Per-server entry fields:
665
-
666
- | Field | Transports | Meaning |
667
- |---|---|---|
668
- | `command`, `args` | stdio | Spawn this local process |
669
- | `env`, `cwd` | stdio | Extra environment variables; working directory |
670
- | `url` | http, sse | Remote endpoint |
671
- | `type` | http, sse | `"sse"` selects Server-Sent Events; a bare `url` without `type` is always streamable HTTP |
672
- | `headers` | http, sse | Extra HTTP headers — `Authorization` is where a hosted server's credential usually rides |
673
- | `autoApprove` (or `auto_approve`) | both | Skip per-call approval for this server's tools. Must be a real JSON boolean — the string `"false"` warns and stays gated |
674
- | `disabled` | both | Load nothing from this entry |
675
-
676
- The first connection to a **user-level** server asks once, showing the resolved command line or URL, whether it auto-approves, and the *names* of its env vars and headers — never their values. The acknowledgement is keyed to the entry's contents, so editing a server later re-asks; project-level servers ride the workspace trust prompt instead. Set `VENASTINE_MCP_ACK_FULL=1` to append the raw JSON entry to that prompt, for audits.
677
-
678
- ### The TUI
679
-
680
- Type `@` in a chat message to complete a file or folder from the project directory. Match by
681
- filename or relative path, use arrows to choose and Tab or Enter to insert. Names with spaces
682
- are quoted, such as `@"docs/my notes.md"`. A mention tells the agent what to inspect; it does
683
- not attach file contents. Normal file-access permissions still apply.
684
-
685
- The path list loads in the background at startup. Files created by the agent's `write` tool
686
- refresh it automatically; files you create yourself appear after restart. Ignored paths are
687
- hidden by default; `/mentions ignored on` includes them for this session, and `/mentions`
688
- shows the source and any limits. Git is optional: without a usable repository/binary, a
689
- fallback skips common build/cache directories. The panel labels that fallback. Up to 50,000
690
- paths are cached and 200 matches offered; narrow the query when a limit is shown.
691
-
692
- | Command | What it does |
693
- |---|---|
694
- | `/help` | List every registered command with its usage |
695
- | `/theme [name]` | Restyle panels, transcript roles and code blocks — not just borders. Bare shows the current theme and all fourteen names. **Remembered for the next launch**, unless `tui.theme` in settings.json has changed since |
696
- | `/effort [level\|auto]` | Switch reasoning effort, offering only levels this model accepts (Anthropic's are queried live). Session-only (`tui.effort` persists) |
697
- | `/thinking [on\|off]` | Show or hide reasoning inline for this session. Session-only (`tui.show_thinking` persists) |
698
- | `/model [[PROVIDER] name]` | Switch provider and/or model, and it is remembered for the next launch. Refuses mid-turn, warns on a missing key, revalidates effort against the new model, and notes if an active agent pins its own |
699
- | `/critic [[PROVIDER] name\|off]` | Route the grounding and critic passes (3a, 3b, 6b) to a different model than the generator, so it is not checking its own output for errors. Remembered across launches; not cleared by `/model`, since being a different model is the point. Bare reports what is in force and where it came from |
700
- | `/embedder [[PROVIDER] name\|off]` | Choose the embedding model that scores how close each source is to the claim it was cited for. The selection is **probed** — one embedding call checks the provider, the slug and the key, and reports the dimension — and only what worked is remembered. Without one, similarity stays the grounding model's own estimate and every run says so |
701
- | `/submodel [[PROVIDER] name\|off]` | Run spawned subagents on a different model than the session's, so a cheap child need not run on its parent's expensive model. An agent whose own file names a model or a provider keeps its pin, and the compactor, the pipeline reviewer and `/init`'s initializer keep the session model; the command names what it does not reach. Remembered across launches, never in settings.json, and named in the header while set. Also in the CLI |
702
- | `/research [--attended] [--review\|--no-review] [--grant[=a,b]] <query>` | Run the pipeline live from the TUI. Leading flags compose in any order before the query; bare `--grant` opens the picker, `--grant=a,b` names them (`--grant-tools=` works as an alias); without flags, `research.*` settings apply |
703
- | `/compact [--strength 1-5]` | Fold older turns now instead of waiting for the trigger. Recent turns keep exactly the protection an automatic compaction gives them |
704
- | `/trigger [tokens\|off]` | Override **when this chat compacts**, for this session only. An absolute prompt size (`80k`), not a margin below the window. A value below the warning margin or the keep-recent floor is refused naming it; a value below the thread's current size is accepted and says a fold is coming |
705
- | `/window [tokens\|off]` | Set this model's **context window** and remember it, per `(provider, model)` and across launches. It outranks both the provider's own answer and the built-in table, and it moves everything derived from the window: the chat compaction trigger, the research-pass backstop and the summarizer's input budget. Above what the provider reports it warns rather than refusing, because raising it is the point — a gateway or a self-hosted endpoint can report its own default rather than your deployment's |
706
- | `/config [key] [value]` | Browse and set the harness's own settings without leaving the session. Typing `/config ` lists all 133 of them in the same panel the slash commands use, with the values each one takes and the value in the file; completing a key then offers that key's values. A value you have already changed reads `pending restart` until you relaunch, and bare `/config` lists every one of them, old to new — so several settings can be changed in a row and applied together. Bare `/config <key>` explains one, including what outranks it — an environment variable, a `settings.json` key — and containers are listed but edited in the file. A write goes through the whole document's validation first, keeps every comment in `config.yaml`, and offers to relaunch, because values are read once at startup. The nine AUTHORITY keys ask first, naming what the key permits |
707
- | `/claims [run id]` | Open the claims view — tier, grounding status, assumption flags, score breakdown per claim — during a run or afterwards (**ctrl+l**) |
708
- | `/copy [last\|report\|claims\|conversation\|all] [--file <path>]` | Copy out of the session. Defaults to the last response; `conversation` is the exchange alone — your turns, the answers, the reasoning, the tool calls and the diffs; `all` is everything on screen (the harness's own lines included) plus report plus claims. Clipboard delivery cannot be confirmed, so `--file <path>` is the route that provably worked |
709
- | `/threads` | Conversations-only picker — research runs' internal threads excluded — most recently active first, capped at 200 with a notice (**ctrl+t**) |
710
- | `/resume <thread-id>` | Open any thread by id, however old |
711
- | `/new` | Start a fresh thread; created lazily on your next message, so `/new` twice leaves nothing behind |
712
- | `/kill [session-id]` | Stop a background session. Bare, it opens the picker **ctrl+b** opens; with an id it stops that one. Deliberately usable *while* sessions are blocking the prompt — it is the way out of that block, so it is the one command that never refuses for being busy |
713
- | `/agent [name\|default]` | Make an agent active for subsequent turns; `default` clears. Active skills are re-checked against the new agent's tool policy |
714
- | `/goal [text\|clear]` | Persistent objective for this thread — injected into every turn in either shell, mirrored in a banner |
715
- | `/grill-me` | One turn under the grill-me agent inside the current thread, reading the live history rather than a digest of it |
716
- | `/skill [name\|off <name>\|clear]` | Activate a skill — its full body pins into every subsequent turn until deactivated — report tools it needs but can't have, or deactivate one/all |
717
- | `/memories` | List durable memories visible from here, with ids for `/forget` |
718
- | `/forget <id>` | Delete one memory by id — never by substring |
719
- | `/summary` | Distil this conversation and show it. Describes; does **not** fold — that is `/compact` |
720
- | `/ref [--list\|--clear]` | Pick another conversation and attach its summary to this one as standing context; `--list` and `--clear` manage attachments |
721
- | `/init [--software\|--research] [--config]` | Scaffold the project documentation set; `--config` adds `.venastine/settings.json` and `mcp.json` with default values, and on its own is the whole command |
722
- | `/mentions [ignored on\|off]` | Show file mention status or include ignored paths for this session |
723
- | `/quit` | Leave the harness, on one invocation — a typed command is already deliberate. `/exit` and `/bye` are the same command under other names; type toward either and the suggestion list says so |
724
-
725
- Keys: **ctrl+c** twice quits — the first press arms it and the footer changes to say so, and it goes back to `Quit` after a couple of seconds; a **ctrl+c** over selected text copies instead and arms nothing, so nothing you copy can end the session. **ctrl+q** quits on a single press, from anywhere, including under a dialog · **ctrl+t** thread picker · **ctrl+l** claims view · **ctrl+j** (or **shift+enter**) newline in the prompt · **up/down** and **enter**/**tab** to pick a slash command, **escape** to dismiss the list · **ctrl+click** a URL in an answer — or in a tool line — to open it, or the name on a `spawn_subagent` line to read what that agent did, or the name on a `shell_background`, `shell_monitor` or `shell_interactive` line to read that session -- its command, why it was started, what it printed, and what became of it. A session the harness no longer holds (it aged out, or you restarted) opens the same way and shows what the agent was given, saying so; a live one refreshes as it writes. While sessions are running the sidebar lists them, and clicking a row opens it; **ctrl+g** lists the runs going on right now and opens one from the keyboard · **ctrl+b** stops a background session, and always asks which one rather than killing on a single press. While background sessions are running the prompt and most commands are refused — `ctrl+b`, `/kill`, answering a dialog and quitting stay usable, because they are the ways out.
726
-
727
- Answers are rendered rather than printed as their source: tables become grids, headings and `**bold**` take weight, `*emphasis*` and `~~strike~~` take their own marks, code fences are highlighted, and a list item that runs past the edge wraps **under its own text** instead of back to the margin. A line indented four spaces or more is left exactly as written, so a code sample keeps its operators and its `#` comments. What is deliberately not rendered: block quotes, horizontal rules, heading *levels* (a `#` and a `######` look the same), and anything at all inside a reasoning block. `/copy` always hands back the markdown the model wrote — the rendering is what the screen does, never what is stored.
728
-
729
- **A link can never hide where it goes.** `[the docs](https://example.com)` draws every character it was written with, and the only clickable thing on the row is the URL itself — so a model cannot present one destination and open another. Ctrl+click opens it, in `http`/`https` only, and only when the URL is plain ASCII: a lookalike address built from non-Latin characters still renders and still copies, but will not open on a click. Nor will an address that carries a username before its host — `https://accounts.google.com@else.example/x` goes to `else.example`, so the part you read as the destination has to *be* the destination — and nor will one the harness rewrote to hide a secret in it. The same is true of the `▸ fetch_url https://…` line: where that line shortens a long address, the click still opens the whole one, and the part shown always reaches the end of the site name, so what you can read is where you will land.
730
-
731
- The prompt box wraps and grows to four lines as you type, then drops back to one when you send, so a long question can be read back before it goes. A line that runs past the edge wraps on its own — `ctrl+j` is for a break you actually want. `shift+enter` does the same where your terminal can send it, which in practice means kitty, ghostty, WezTerm, or any terminal configured to emit a newline for that chord; elsewhere it arrives as a plain Enter and sends the message, so `ctrl+j` is the one to reach for.
732
-
733
- Type `/` and the commands appear above the prompt — name, description and flags, narrowing as you type and coming back if you delete. Arrow up and down to move the highlight — the list scrolls, so every matching command is reachable, not just the ones on screen; **enter** or **tab** fills the command in **without sending it**, so you can still add arguments, and a second **enter** runs it. **escape** puts the list away. The list is the same one `/help` prints, so nothing can go stale, and the panel's title says how many of the matches fit on screen.
734
-
735
- Three behaviours worth knowing: an unknown slash command is an error, never a chat turn — a mistyped command cannot silently burn a request. `/effort` and `/thinking` persist nothing, so make those stick through settings.json or launch flags; `/theme`, `/model`, `/critic` and `/embedder` are the exceptions — they are remembered for the next launch, in files of their own beside settings.json rather than by rewriting it. And the commands that spend money or swap models mid-session (`/compact`, `/summary`, `/research`, `/init`, `/model`, `/critic`, `/embedder`, `/grill-me`) refuse while a turn is still running rather than acting underneath it.
736
-
737
- When a subagent is spawned, you are asked which of its approval-gated tools it may use without asking again — per tool, all unticked by default. Running it with none selected is fine, and refusing the spawn entirely is a separate answer from granting it nothing. Before this, approving a spawn authorised the child's whole set.
738
-
739
- `/init` reads the project and writes its documentation set. A root `AGENTS.md` is the hub — the short, factual description this harness injects into every agent that opts into project context, and the filename other agent harnesses look for too — and it links out to the documents that hold the detail: `ARCHITECTURE`, `ROADMAP`, `DEVLOG`, `TECHNICAL_DEBT`, `DOCUMENTATION_STANDARDS`, `TEST_WRITING` and `BREAKING_CHANGES` for a codebase, or `RESEARCH_QUESTIONS`, `METHODOLOGY`, `SOURCES`, `FINDINGS`, `LIMITATIONS`, `EXPERIMENT_LOG` and `OPEN_QUESTIONS` for written work. It asks which kind you have — proposing an answer when there is something to go on, and asking outright when the folder is empty.
740
-
741
- Only `AGENTS.md` is written for you in full; the rest arrive as skeletons with real headings and a note in each saying what belongs in it and what does not. That is deliberate: a DEVLOG invented for a project with no history is fiction in a file that then gets committed and read as fact. Documents you already have are never touched, and regeneration revises your `AGENTS.md` rather than replacing it — you see a diff and approve it before anything is written. Everything `/init` writes is an ordinary committed file at the project root, so a repository shared without its `.venastine/` configuration is still a repository whose documentation makes sense. From the CLI it is `--init`, with `--software-project` / `--research-project` to skip the question.
742
-
743
- `/init --config` is the other half, and it is independent of the two above: it writes `.venastine/settings.json` and `.venastine/mcp.json`, and creates `.venastine/agents/` and `.venastine/skills/`. On its own it makes **no model call** and costs nothing — no document set, no question about which kind of project this is; combined (`/init --software --config`) it does both under one confirmation. An existing `settings.json` or `mcp.json` is never touched, per file, so a project with one and not the other gets the other. From the CLI it is `--init --project-config`.
744
-
745
- The settings file it writes is **every key with a shipped default, at that default** — because the file cannot explain itself. An unknown key raises at startup, so there is no comment syntax, no `$schema` line and no way to leave a key in the file but switched off; the scaffold is the schema. Six keys are deliberately left out, because something reads them by *presence* rather than by value, so writing their own default would decide rather than restate: `default_provider` and `default_model` (adding either discards a model you picked with `/model` in that project), `effort` (makes every launch probe the provider's effort table), `compaction.trigger_tokens` (disables the window-derived trigger, invisibly), `ensemble_mode` and `research.subagent_review` (both defer to `config.yaml` only while absent). Set any of those by hand and they work normally. Everything the scaffold does write changes nothing until you edit it — and because a project's `settings.json` beats yours by *presence*, the command tells you which of your own keys the new file has taken over before it asks to write it.
746
-
747
- `/summary` distils this conversation and shows it — it does **not** shorten what the model sees; that is `/compact`. `/ref` picks another conversation, summarises it, and attaches that summary to this one as standing context: you choose what crosses between threads, so nothing read or argued in one conversation can steer another without your say-so. `/ref --list` and `/ref --clear` are the way back out, and the summaries are labelled so the model knows they are not part of this conversation. From the CLI the same two are launch flags: `--summary <thread>` and a repeatable `--ref <thread>`.
748
-
749
- `/threads` lists your **conversations** — not the ~15 internal threads each research run creates, nor the one every automatic compaction makes — ordered by last activity, so the conversation you were just in stays on top. Each row leads with its first message so you can tell them apart. The list shows the 200 most recently active and says so when it truncates; `/resume <thread-id>` opens any thread by id, however old, and `/new` starts fresh, redrawing the window rather than leaving the previous conversation on screen beneath it. A run's own pass threads are recorded with the run (`output/<run_id>/pass_threads.json`) and can still be opened by id with `--thread`, if you want to see how a particular pass argued.
750
-
751
- `/model` switches provider and model, and the pair comes back at the next launch: it is saved in `~/.config/venastine/ui_preferences.json`, beside `settings.json` and never into it. Editing `default_provider` / `default_model` there still wins — the store records what the file said when you chose, so changing it (or adding it, or removing it) re-asserts the file — and `--provider` / `--model` pin one launch without disturbing what is remembered.
752
-
753
- `/copy` exists because Textual 1.0 cannot select text at all. Clipboard delivery uses an escape sequence that some multiplexers drop silently and **cannot be confirmed**, so `--file <path>` is the route that provably worked. Shift+drag usually bypasses the mouse capture and lets your terminal select natively.
754
-
755
- `/copy conversation` and `/copy all` are two targets on purpose. `all` is everything the session put on screen — `/help`'s output, the launch banner, `Resumed thread <uuid>.`, the replay marker — plus the research report and the claims, which is what you want when reconstructing what happened. `conversation` is the exchange with none of that.
756
-
757
- ### The CLI reads stdin exactly once
758
-
759
- Chat mode, the approval prompts, the trust prompt, `--init` and the MCP acknowledgement all read
760
- through **one** object. That sounds like an implementation detail and is not: before it, an approval
761
- prompt started a background reader that never stopped, so from the first gated tool call onwards
762
- chat's own `input()` lost every line to it and blocked forever — silently, and looking exactly like
763
- the model thinking. Recovery was Ctrl+C and `--thread <id>`.
764
-
765
- Two disciplines, because the two kinds of prompt want opposite things:
766
-
767
- | | drains stale input | deadline |
768
- |---|---|---|
769
- | the gated prompts — approvals, sign-offs, questions, review | **yes** | from the channel |
770
- | the chat prompt and the startup prompts | no | none |
771
-
772
- The drain is a safety rule: a line typed after a question timed out was answering *that* question,
773
- and letting it fall through would approve the next call on the strength of it. The chat prompt must
774
- *not* drain, for the mirror-image reason — a line typed while the model was still streaming is an
775
- answer to the prompt about to appear, and the terminal has been buffering it for you.
776
-
777
- **A deadline belongs to a run, not to a question.** An approval asked during an attended research run
778
- expires after `ATTENDED_APPROVAL_TIMEOUT_S` (600s) and denies that call, because there is a run
779
- waiting on the answer and it has to keep moving. `--init`'s prompts have no run behind them, so they
780
- wait as long as you need — and they do not print a `(600s)` they would not honour.
781
-
782
- `--help` and a mistyped flag now do nothing at all. They used to create a 77 KB six-table SQLite
783
- database and a log directory in whichever directory you ran them from, before argparse had seen a
784
- single flag.
785
-
786
- `--review` and `--no-review` in chat mode are refused rather than ignored, matching
787
- `--grant`/`--grant-tools`/`--attended`. Inside the TUI, use `/research --review <query>`.
788
-
789
- ### CLI flag reference
790
-
791
- Everything `python main.py` accepts. Wherever a value can come from more than one place, precedence is explicit flag > `settings.json` > built-in default.
792
-
793
- | Argument | Effect |
794
- |---|---|
795
- | `query` (positional) | Research mode: the question the pipeline runs on — required there. Chat mode: sent as the first message, then the interactive loop continues |
796
-
797
- | Flag | Effect |
798
- |---|---|
799
- | `--thread UUID` | Resume a stored conversation; what you said replays so you can see what you are picking up |
800
- | `--mode chat\|research` | Which loop to run. Chat is the default |
801
- | `--tui` | Launch the full-screen interface instead of the line-based CLI |
802
- | `--provider NAME` | Any entry from `providers.json` — `ANTHROPIC`, `OPENAI`, or an OpenAI-compatible endpoint you added |
803
- | `--model NAME` | Model id as the provider knows it |
804
- | `--effort LEVEL` | Reasoning effort for chat *and* research — typically `low`, `medium`, `high`; `xhigh`/`max` on models that offer them; `auto` sends no effort parameter at all. See [Reasoning effort](#reasoning-effort) below |
805
- | `--grant` | Research only. Pick approval-gated tools to pre-authorise, interactively — needs a terminal; a piped run prints the candidates instead. Empty unless an MCP server offers grantable tools |
806
- | `--grant-tools NAMES` | Research only. Same as `--grant`, but takes an explicit comma-separated list of tool names and works without a terminal |
807
- | `--attended` | Research only. Ask about every gated call as it happens; 600s with no answer denies that call and the run continues. Composes with grants — granted tools aren't asked about, everything else is |
808
- | `--review` / `--no-review` | Research only. Post-pipeline review on/off for this run; `--no-review` is the escape from a persisted setting |
809
- | `--memories` | List durable memories visible from this directory — id, scope, content — and exit |
810
- | `--forget ID` | Delete one memory by id — never by substring — and exit |
811
- | `--summary [THREAD]` | Print one thread's distilled summary and exit; falls back to `--thread`. A summary still current costs no model call — staleness is detected, not assumed |
812
- | `--ref THREAD` | Attach another thread's summary to this session at launch. Repeatable up to three; past the cap the extra reference is refused and named, not silently dropped |
813
- | `--trust-project` | Grant workspace trust non-interactively for scripts/CI, printing what it trusts as it does so |
814
- | `--init` | Generate this project's documentation set and exit. On a pipe there is no consent route, so it reports what it would write and writes nothing |
815
- | `--software-project` / `--research-project` | With `--init`: choose the document set without asking. At most one of the two |
816
- | `--project-config` | With `--init`: create `.venastine/settings.json` and `mcp.json` with default values, plus `agents/` and `skills/`. Without a document-set flag it is the whole command and makes no model call. Refused without `--init`, rather than ignored |
817
-
818
- **Combinations the parser refuses** (rather than ignoring):
819
-
820
- - `--mode research` without a positional query.
821
- - `--tui` with `--mode research` — use `/research` inside the TUI.
822
- - `--tui` with a positional query — start the TUI and type.
823
- - Any of `--grant`, `--grant-tools`, `--attended`, `--review`, `--no-review` outside research mode, including under `--tui`.
824
- - Both kind flags with `--init`.
825
-
826
- **Scripting notes.** Startup prompts degrade instead of hanging when stdin is not a terminal: project content is skipped with a notice unless `--trust-project`, newly seen user-level MCP servers are skipped and named, the grant picker prints its candidates instead of asking, the review records findings but applies nothing, and chat-mode approvals do not exist — gated tools stay hidden entirely. Exit codes: `0` success; `1` operational failure (a failed pipeline, a bad memory id, nothing to summarise); `2` argparse misuse. `--help` and a mistyped flag touch nothing at all — no database, no log directory.
827
-
828
- ### Reasoning effort
829
-
830
- Effort asks a reasoning model how long to think before answering. It rides every chat turn, every research pass, every JSON-retry correction, the reviewer and its re-synthesis — a retry is the same pass continuing, so it inherits the level rather than dropping it.
831
-
832
- Where a level comes from, in order: `--effort` > top-level `effort` in `settings.json` > `config.DEFAULT_EFFORT` (shipped `"high"`). Inside the TUI, `tui.effort` persists separately and wins there. `auto` is the off switch at either layer — with the default now high, `--effort auto` restores send-nothing behaviour.
833
-
834
- A level is validated against the model that will **receive** it, not the one it was chosen for:
835
-
836
- | Provider | Levels | Where the set comes from |
837
- |---|---|---|
838
- | Anthropic | `low`, `medium`, `high`, `xhigh`, `max` — whichever the model reports supported | Queried live from the Models API, so newly released Anthropic models need no entry anywhere |
839
- | OpenAI-compatible | `low`, `medium`, `high` assumed for unknown models | Static table (`config.MODEL_EFFORT_LEVELS`). Known non-reasoning models — gpt-4o family, gpt-3.5 — ship with *empty* lists, meaning "takes no effort parameter": a requested level is dropped cleanly instead of 400ing every call. An unlisted model gets the assumption plus a WARNING naming it |
840
- | Google | Levels map to integer thinking budgets, `low`→2,048 through `max`→dynamic | Mapped at the boundary and sent as `thinking_budget`. On since batch 172, when the `google-genai` pin moved to 2.29.0; an unlisted Gemini model gets the default level set plus a WARNING, like any other unlisted model |
841
-
842
- **Seeing the thinking is separate from doing it.** Effort is what makes the model reason; whether the API hands those thoughts back to the client is a different question, and the answer varies by provider. Reasoning streams into the transcript on **Anthropic** and on OpenAI-compatible providers that send it — DeepSeek, Qwen, Z.AI, OpenRouter. It is absent on **OpenAI**, whose Chat Completions endpoint returns no reasoning text at all, and on **Google**, whose request deliberately does not ask for thought summaries: those would be billed as extra output for something the model produces either way. On those two the turn still thinks; you just do not see it. `tui.show_thinking` and `/thinking` control the display, never the reasoning.
843
-
844
- A verification that *fails* — a network blip during the query — passes your level through unverified with a warning rather than silently downgrading a deliberate choice. `/effort` in the TUI offers only levels the mounted model accepts, and `/model` revalidates after a switch, since effort is per-model. An agent pinning its own provider/model wins over the session's choice for chat turns, and says so.
845
-
846
- ### Budgets and stop conditions
847
-
848
- There is **no default spend ceiling**. (That absence is also why compaction stopped being a flat number: the trigger was sized against a spend cap that no longer exists.) The cumulative input+output counter is a billing meter — the prompt is re-sent and re-billed on every step of a tool-using turn, so it grows quadratically in steps: correct as billing, meaningless as a size limit. A hard cap exists only if settings.json sets `max_token_budget` (billed tokens per run — one user turn, one research pass, one `/init`). Limits at the provider remain the stronger instrument: they see the same bill and cannot be forgotten by a code path.
849
-
850
- Three things can end a turn or pass early:
851
-
852
- | Stop reason | When |
853
- |---|---|
854
- | `complete` | The model answered without calling another tool |
855
- | `max_steps_reached` | Step ceiling hit — 50 by default; an agent's own `max_steps` replaces that number, in either direction |
856
- | `token_budget_exceeded` | Only when `max_token_budget` is configured: cumulative billed spend crossed it |
857
-
858
- The CLI names the figures behind an early stop — billed this turn, and the thread's measured context size — rather than a bare reason, because "budget exceeded" invites exactly the misreading that there is a size problem.
859
-
860
- Other ceilings worth knowing: the six maths tools run in killable subprocesses under a 20-second wall clock (`tool_compute_timeout_s`) and are told which tool and which limit stopped them; pre-granted tool calls cap at 150 per research run (`MAX_GRANTED_TOOL_CALLS`), degrading to asking when exhausted; subagent nesting stops at depth 2 (`SUBAGENT_MAX_DEPTH`) and at most three subagents of one turn run at once (`SUBAGENT_MAX_PARALLEL`), with anything beyond that running in waves; attended prompts expire after 600 seconds (`ATTENDED_APPROVAL_TIMEOUT_S`), denying that one call while the run continues.
861
-
862
- Subagents spawned in one model response run **concurrently**, up to `SUBAGENT_MAX_PARALLEL`. Their answers come back to the model in the order it asked for them however they finish, one approval question reaches you at a time, and the sidebar draws them as a tree rather than a chain. The database runs in SQLite's WAL mode to keep their writes from contending, which means `app.db` is accompanied by `app.db-wal` and `app.db-shm` while the harness is open — both are gitignored, and excluded from `git archive`, because a WAL file holds recently written messages.
863
-
864
- ### Logging
865
-
866
- Two sinks from startup: stderr, and a rotating file — `logs/app.log` in the working directory, 1 MB per file, three backups kept. `AGENT_LOG_LEVEL` sets verbosity (a name like `INFO` or a number like `20`; anything else prints a warning naming the value and runs at `INFO`, as an unwritable `AGENT_LOG_FILE` does) and `AGENT_LOG_FILE` moves the file, creating the parent directory if needed. The file formatter redacts secret-shaped strings on the way out — the same patterns tool outputs get — because a failing tool's traceback routinely carries the request that produced it, and for an HTTP client that is a URL with the key in it.
867
-
868
- In the TUI stderr is detached before the screen is taken (anything written there would paint over the rendered UI and vanish on the next repaint); the rotating file keeps everything, and WARNING-and-above is routed into the transcript so warnings stay visible where you are looking.
869
-
870
- ### Configuration reference
871
-
872
- | File | Holds | Notes |
873
- |---|---|---|
874
- | `providers.json` | LLM provider keys | gitignored; path movable with `AGENT_PROVIDERS_FILE` |
875
- | `.env` | tool API keys | gitignored |
876
- | `settings.json` | defaults and modes | unknown keys **raise**; user copy at `~/.config/venastine/settings.json`, project copy at `.venastine/settings.json` (loaded only when trusted). `/init --config` writes a project copy with every defaulted key in it |
877
- | `mcp.json` | MCP servers | unknown keys ignored; same two locations. `/init --config` writes an empty project copy |
878
- | `trusted_projects.json` | workspace-trust store | user-level (`~/.config/venastine/`); written by the trust prompt or `--trust-project`, keyed to resolved path + content hash |
879
- | `AGENTS.md` | project context for the model | project root; covered by workspace trust |
880
-
881
- Precedence for provider and model is CLI flag > `settings.json` > `config.yaml`. Two different merge orders, deliberately:
882
-
883
- - **Inside `settings.json`, project beats user** — this is the one file where "more specific wins" holds, which is exactly why the five authority-bearing keys below are rejected there by name. Nested objects merge key-by-key across tiers.
884
- - **MCP servers, agents and skills run harness > user > project**, inverted from the usual rule, because there "more specific" means "arrived with a repository you cloned".
885
-
886
- #### Every `settings.json` key
887
-
888
- An unknown key raises at startup, naming the file and the key — a typo must never read as a setting. `/init --config` writes a project `settings.json` containing every key below that has a shipped default, at that default, so you can edit rather than transcribe.
889
-
890
- | Key | Type | Default | Meaning |
891
- |---|---|---|---|
892
- | `default_provider` | string | `"ANTHROPIC"` | Used unless `--provider` overrides |
893
- | `default_model` | string | `claude-sonnet-5` | Used unless `--model` overrides |
894
- | `effort` | string | `"high"` | Reasoning effort for chat and research; `"auto"` clears even this. See [Reasoning effort](#reasoning-effort) |
895
- | `max_token_budget` | int \| null | null — uncapped | Per-run billed-spend ceiling. See [Budgets and stop conditions](#budgets-and-stop-conditions) |
896
- | `ensemble_mode` | bool | `false` | Master switch for ensemble Pass 1; the roster lives in `config.yaml` |
897
- | `ensemble_n` | int | — | Accepted with a warning; vestigial — the count now derives from the roster |
898
- | `compaction` | object | — | Seven keys tabulated in [the compaction section](#long-conversations-condense-themselves) above |
899
- | `tui.theme` | string | — | One of the fourteen theme names; validated at use and falls back rather than blocking startup. Outranked by a theme you picked with `/theme` — until you change this value, which re-asserts it |
900
- | `tui.animations` | bool | `true` | Master switch for the raven and transitions |
901
- | `tui.effort` | string | — | Persisted TUI effort level; beats top-level `effort` inside the TUI |
902
- | `tui.todo_position` | string | — | `top`, `bottom` or `side`; validated at load |
903
- | `tui.show_thinking` | bool | `true` | Render a turn's reasoning inline in the transcript. Off collapses it to an animated `thinking…` line. Absent on providers that return no reasoning — see below |
904
- | `research.approval_mode` | string | `"none"` | `"attended"` makes research runs ask about every gated call, as if launched with `--attended` |
905
- | `research.subagent_review` | bool | `false` | Review on by default, as if launched with `--review`; escaped per run with `--no-review` |
906
-
907
- Five keys are rejected **by name** — well-formed shapes that will never load, because a project tier that could set them would decide what runs without being asked:
908
-
909
- | Rejected key | Why |
910
- |---|---|
911
- | `shell_approval_mode` | Decides whether shell commands are asked about at all; set `shell_approval_mode` in `config.yaml` instead |
912
- | `ensemble_models` | A roster chooses which providers N research passes call, so a cloned repository could point them at endpoints you never configured and multiply the run's cost by the length of its list; set `ensemble_models` in `config.yaml` instead |
913
- | `critic_model` | Names a provider every claim is sent to; use `/critic`, which writes a user-tier store, or set `critic_model` in `config.yaml` |
914
- | `embedder_model` | Names a provider sent claim text and the text of every page a run fetched; use `/embedder`, or set `embedder_model` in `config.yaml` |
915
- | `research.granted_tools` | A persisted grant list could only ever *remove* prompts — standing authorisation carried by any repo you clone. Grants are per-run flags precisely so they cannot be |
916
-
917
- #### `config.yaml`-only settings
918
-
919
- Deliberately not settings.json keys: editing these means editing the harness's own file, which has exactly one location and no override variable, so nothing a cloned repository carries can reach them. `CONFIG_ARCHITECTURE.md` carries the argument for each.
920
-
921
- | Key | Default | Controls |
922
- |---|---|---|
923
- | `critic_model` | `null` | Routes passes 3a/3b/6c to a different `{provider_name, model}` |
924
- | `ensemble_models` (with `ensemble_mode`) | `null` (off) | Pass-1 roster; fewer than two distinct pairs is refused |
925
- | `default_effort` | `high` | Effort when neither flag nor settings speaks |
926
- | `model_effort_levels` | see file | Per-model level lists for non-Anthropic providers; an entry mapped to an *empty* list means "takes no effort parameter" and drops the level cleanly |
927
- | `google_thinking_budgets` | low→2,048 … max→dynamic | Google level→thinking-token map |
928
- | `models_rejecting_sampling_params` | current Anthropic models, and the two Gemini models that ignore them | The Anthropic models 400 on temperature/top_p/top_k and the Gemini ones ignore them; such parameters are dropped with a WARNING rather than sent. OpenAI's reasoning models are handled by effort, not by this list |
929
- | `model_context_windows` / `default_context_window` | 256k fallback | The **fallback** for the window, not the only source: Anthropic and Google report it on their model endpoints, and the OpenAI-compatible providers that carry it (Groq, Mistral, Together, OpenRouter) are read through one alias sniff. This table answers for the ones that report nothing (OpenAI, DeepSeek, Perplexity). Feeds the research-pass compaction backstop **and** the summarizer's one-call input budget; an unknown model warns once and assumes the default. Keys are stored normalized — no date suffix, no `vendor/` prefix |
930
- | `shell_approval_mode` | `tiered` | The shell gate: `always` / `tiered` / `never`; a bad value raises at import. Rejected in settings.json by name, see above |
931
- | `network_allowed_commands` | pip, curl, git, npm, … | Binaries granted network access inside the sandbox. Matched against **every** word of a command that needs a sandbox, so `cd x && pip install .` is recognised and asked about — and against the **first word only** of an inert one, which cannot chain, so `grep pip notes.txt` still runs unprompted. This list is a *lexical* test, so since ROADMAP_v3 §50 the agent can also declare `requires_network: true` on `shell`, `shell_background`, `shell_monitor` and `shell_interactive` for anything the word list cannot see — an inline script that opens a socket, say. The declaration only ever ADDS network access, and the command is then asked about wherever your approval mode would allow a prompt |
932
- | `inert_commands` | ls, cat, grep, wc, … | Read-only commands eligible to run unprompted under `tiered` — as a plain argument list in the container, or on the host only when no container runtime is available |
933
- | Sandbox bounds | image `docker.io/library/python:3.13-slim`; 120 s, 2048 MB, 1 CPU core, 200 pids — under Docker, or Podman when Docker cannot run the sandbox. The container's CPU control is a RATE (`--cpus 1`), so `sandbox_cpu_seconds` (30 CPU-s) is a budget the weak fallback enforces instead, and on Unix only | `sandbox_docker_image`, `sandbox_timeout_seconds`, `sandbox_memory_mb`, `sandbox_cpu_seconds`, `sandbox_max_pids` |
934
- | Background sessions | 3600 s cap; 4 live; 10 consecutive wakes; first 10,000 + last 190,000 characters of output kept, in memory only | `shell_session_timeout_cap_s`, `shell_session_max_live`, `shell_session_max_consecutive_wakes`, `shell_session_output_head_chars`, `shell_session_output_tail_chars` |
935
- | `allow_insecure_sandbox_fallback` / `auto_approve_sandbox_fallback` | `false` / `false` | Enable, then de-prompt, the weak host-subprocess fallback |
936
- | `allow_wsl_backend` / `wsl_distro` | `false` / `''` | Let the agent ask for a command to run in WSL, and which distribution. WSL is not a sandbox — see below |
937
- | `allow_ssh_backend` / `ssh_*` | `false` / `''` | Let the agent ask for a command to run on one configured remote host. Nothing runs there unasked; the host key is pinned and auth is key-or-agent only — see below |
938
- | `redact_tool_outputs` | `true` | Master switch for output redaction. Never affects input refusals, the depth-cap bound, or the log formatter's own guard |
939
- | `tool_compute_timeout_s` | 20 | Wall clock per maths-tool subprocess |
940
- | `max_granted_tool_calls` | 150 | Pre-granted calls per research run before it must ask again |
941
- | `attended_approval_timeout_s` | 600 | Attended prompt deadline; expiry denies that call while the run continues |
942
- | `subagent_review` | `false` | Shipped default for the post-pipeline review |
943
- | `max_review_findings` / `max_review_refinements` | 25 / 3 | Consent-fatigue caps on the review stage |
944
- | `max_pipeline_retries` / `max_json_retries` | 2 / 2 | Revise/re-validate rounds per claim; corrective attempts per malformed pass payload |
945
- | `max_iterations` | 50 | Step ceiling for a turn or pass absent an agent's own `max_steps` |
946
- | `subagent_max_depth` | 2 | `spawn_subagent` nesting limit |
947
- | `subagent_max_parallel` | 3 | How many subagents of one model response run at once; 1 makes them sequential again |
948
- | `pin_max_trigger_fraction` | 0.5 | Largest share of the trigger one pin may protect |
949
- | `compaction_trigger_fraction` | 0.90 | Share of the context window a thread may fill before it folds. Applied to the HEADROOM, which is clamped by the two keys below — so it is exact at 160k and up, and a floor beneath that |
950
- | `compaction_min_headroom_tokens` / `compaction_max_headroom_fraction` | 16,000 / 0.25 | Floor and cap on the room left between the trigger and the window. Nothing recovers from a prompt that overflows the window, and one capped read is 12,500 tokens, so a 64k model keeps 16,000 rather than the 6,553 a bare share leaves |
951
- | `max_injected_memories` / `max_injected_refs` / `max_todo_items` | 50 / 3 / 50 | Prompt-injection caps; refs and todos refuse past the cap rather than trimming silently |
952
- | `summary_target_chars` | 2000 | Size cap on whole-thread summaries injected via `/ref` |
953
- | `max_catalog_text_chars` | 300 | Cap on an agent/skill `name` + `description` entering system prompts |
954
- | `init_read_chars` / `init_max_steps` | 20,000 / 12 | `/init` per-read volume; step-ceiling fallback (the initializer agent's own frontmatter sets 12, which wins) |
955
- | `init_max_hub_chars` / `init_diff_shown_lines` | 1,000,000 / 2,000 | Largest existing `AGENTS.md` `/init` revises (above it, it stops before any model call); most diff lines it prints before asking |
956
- | `teardown_budget_s` | 10 | Shared wall clock for MCP shutdown; stragglers are named in a WARNING |
957
-
958
- #### Environment variables
959
-
960
- | Variable | Default | Controls |
961
- |---|---|---|
962
- | `AGENT_MODEL` | `claude-sonnet-5` | Built-in default model (`config.MODEL_NAME`) — still loses to settings.json and `--model` |
963
- | `AGENT_PROVIDERS_FILE` | `providers.json` | Credential-file location |
964
- | `APP_DB_PATH` | `app.db` | SQLite database path |
965
- | `AGENT_OUTPUT_DIR` | `./output` | Research artifacts root |
966
- | `AGENT_WORKSPACE` | `./workspace` | File-tools and sandbox workspace root. **When you set it, it is also the project**: workspace trust, `.venastine/`, `/init`'s destination, `output/` and project-scoped memories all follow it rather than the directory you launched from. Unset, the project is the launch directory — and launching from the harness's own install tree is refused (exit 2), because that would make the harness its own project. The `workspace_dir` key in `config.yaml` sets the workspace but **not** the project on its own -- the rule is the presence of this variable, never its value -- so the file's way of saying it is the `workspace_is_project` key beside it |
967
- | `AGENT_SHELL` | auto-detect | Host shell binary for the `shell` tool |
968
- | `AGENT_SANDBOX_IMAGE` | `docker.io/library/python:3.13-slim` | Sandbox container image, under Docker or Podman |
969
- | `AGENT_LOG_LEVEL` | `INFO` | Log verbosity — name or numeric level |
970
- | `AGENT_LOG_FILE` | `logs/app.log` | Rotating log location |
971
- | `VENASTINE_REDACT_OFF` | unset | Truthy value disables tool-output pattern redaction for one run. The environment can only ever weaken redaction, never restore it past the constant — and input refusals, the depth-cap bound and the log formatter's guard stay on regardless |
972
- | `VENASTINE_MCP_ACK_FULL` | unset | `=1` appends the raw mcp.json entry to a server's acknowledgement prompt |
973
-
974
- #### `providers.json` entries
975
-
976
- | Field | Meaning |
977
- |---|---|
978
- | `API_URL` | Endpoint base URL; empty for ANTHROPIC and GOOGLE, which use their SDKs' defaults |
979
- | `API_KEY` | The credential, stored directly |
980
- | `is_v1_compatible` | `true` routes the provider through the OpenAI-compatible translation |
981
- | `supports_stream_usage` | Promises streamed responses carry token usage. If a stream then ends with none, the harness **raises** rather than accounting zero tokens — a silent zero would disable the budget stop condition while looking healthy. Endpoints that don't return streaming usage ship with `false` |
982
- | `echoes_reasoning` | Opt in to sending this provider's own reasoning back on the next request (§44). Off everywhere by default: there is no standard for it the way there is for receiving reasoning — DeepSeek documents that `reasoning_content` must not be supplied on input and returns a 400, while OpenRouter accepts it for some models and ignores it for others. Anthropic needs no flag; its thinking blocks are signed and are echoed to the model that produced them automatically |
983
- | `accepts_images` | Opt in to delivering images that `view_image` attaches (ROADMAP_v3 §81). It must be JSON `true`; a quoted `"true"` does not count. It needs setting per endpoint because whether a request with an image succeeds depends on the endpoint and often the model, and sending one to a model without vision fails the request. The example sets it for ANTHROPIC and GOOGLE, the two providers where every chat model accepts images. For an OpenAI-compatible endpoint serving a vision model, add it yourself; the image then travels in a harness message after the tool results, because that API's tool messages carry text only. On GOOGLE the image travels the same way, after the function responses, and a GIF becomes a note there rather than an image. A provider without the flag gets a note saying the image was not sent, and `view_image` is not offered to it at all |
984
-
985
- `mcp.json` entries are tabulated under [MCP servers](#mcp-servers).
986
-
987
- ---
988
-
989
- ## Status
990
-
991
- **Built:** ROADMAP.md §1–§12 (§10's ensemble mode rebuilt by its revisit — diversity now comes from a roster of different models) and ROADMAP_v2.md §13 (streaming loop), §14 (config loader + workspace trust), §15 (permissions), §16 (TUI), §17 (MCP), §18 (agents), §19 (skills), §20 (post-pipeline review), §21a (compaction + `pin`), §21b (durable memory), §22 (live pipeline progress), §25 (authorised tool use in the pipeline), §26 (research legibility: per-pass tool calls, code-stage announcements, the claims view, role colour, `/copy`), §27 (thread legibility: transcript replay on resume, a conversations-only thread picker), §21c (session summaries and cross-thread referencing — §21 is now complete), §24 (`/init`), §23 (interactive tools: the response channel, per-tool subagent sign-off, `ask_user`, and the todo list), §28 (the shell capability classifier).
992
-
993
- **Remaining:** nothing in `ROADMAP.md` or `ROADMAP_v2.md`, and §10's revisit is now closed. `ROADMAP_v3.md` §49–§52, §54, §55, §58 and §61–§83 are built. The remaining sections are §53 (rolling network-I/O budgets), §56 (a decision-model shell classifier), §57 (`/submodel`), §59 (memory selection and agent cycling), and §60 (Unified Harness Protocol compliance), each specified and awaiting detailed design. §54 completes project file/folder mentions without loading contents; §58 supplies a short harness identity that follows the current model; §83's final live checks are confirmed, and the ChatGPT header distinguishes a selected provider from an active sign-in. TECHNICAL_DEBT.md items 9 and 10 are open. The two checks recorded against §10 are answered from the providers' documentation in `ROADMAP_v3.md` §87: the default `temperature` on OpenAI and Google is 1.0, and OpenAI's reasoning models refuse one whenever reasoning effort is not `none`, which the guard now follows.
994
-
995
- **Not finished, though: an audit is open.** Both roadmaps being built is not the same as the
996
- code being clean, and saying only the first would be the "built and runs are different claims"
997
- mistake this project keeps recording against itself. Audit Pass 1 is tracked in GitHub issues —
998
- **149 of 154 closed, 5 open**, those five being four `S3`s plus the `#15` tracker itself. Every
999
- `S1` (8 of them), `S2` (30) and `S4` (9) finding is closed, and 75 of 79 `S3`s are. It has been
1000
- worked in numbered fix batches — 32 so far, each recorded in `DEVLOG.md` and
1001
- `tests/BREAKING_CHANGES.md` with what was measured and what would break the fix.
1002
-
1003
- **#157 — `shell`'s unbounded auto-approval — is closed** by batch 8 and ROADMAP_v2 §28; the
1004
- classifier is described under *Security model* above. If you have a fork or a local config,
1005
- note that shell approval is governed solely by `shell_approval_mode` -- `tool_approvals`
1006
- deliberately has no `shell` key, so an old file carrying one is refused at startup
1007
- naming the key — see `tests/BREAKING_CHANGES.md` §24.
1008
-
1009
- Run the test suite with `pytest` — 8909 tests, fully offline, no API keys needed. The suite's own packages are `requirements-test.txt`, separate from `requirements.txt` since batch 136: they used to be in the shipped dependency list, so installing the harness also installed a test runner. It runs in parallel by default (`pytest-xdist`, 70% of your cores): **1:26 on a 16-core machine, against 9:06 single-process.** `pytest -n0` forces the old serial run, which is what you want under a debugger or when something is parsing the output. Four further tests are marked `integration` and excluded by default: three spawn a real stdio MCP server, the fourth runs an external program through the host fallback shell (`pytest -m integration`).
1010
-
1011
- ## Documentation
1012
-
1013
- This file is the user-facing one. For working on the code:
1014
-
1015
- - **[AGENTS.md](./AGENTS.md)** — the agent-context file, and the place to start. `CLAUDE.md` and `QWEN.md` are pointers to it so a tool looking for a particular filename finds one without the guidance being duplicated.
1016
- - **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — file-by-file contracts, what belongs where, and the known gotchas. Read before changing anything non-trivial, especially around persistence (`database.py` / `storage.py` / `core/memory.py` are three distinct and easily confused responsibilities).
1017
- - **[ROADMAP.md](./docs/ROADMAP.md)**, **[ROADMAP_v2.md](./docs/ROADMAP_v2.md)** and **[ROADMAP_v3.md](./docs/ROADMAP_v3.md)** — implementation specs plus the locked Design Decisions Record that most of the reasoning above traces back to. Section numbers run on across the three: v3 opens at §49.
1018
- - **[DEVLOG.md](./docs/DEVLOG.md)** — what was followed, what was deviated from, and why.
1019
-
1020
- ### Contributing and policies
1021
-
1022
- - **[CONTRIBUTING.md](./docs/CONTRIBUTING.md)** — inbound license (Apache-2.0 + DCO), the setup and test loop, the issue and PR format, and a table of which document to update for what.
1023
- - **[SECURITY.md](./docs/SECURITY.md)** — how to report a vulnerability privately, what is in and out of scope, and the coordinated-disclosure timeline. **Do not open a public issue for one.**
1024
- - **[PRIVACY.md](./docs/PRIVACY.md)** — what is stored locally, what leaves your machine, and how to delete it. No telemetry.
1025
- - **[CODE_OF_CONDUCT.md](./docs/CODE_OF_CONDUCT.md)** — Contributor Covenant 2.1, and the private channel for reporting a violation.
1026
- - **[THIRD_PARTY_NOTICES.md](./docs/THIRD_PARTY_NOTICES.md)** — the dependency license assessment: every declared direct dependency, its license, and its Apache-2.0 compatibility.
1027
-
1028
- ## License
1029
-
1030
- Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE). Copyright 2026 Yahya Hammad.
1031
-
1032
- No third-party source code is bundled here; dependencies are resolved from PyPI at install time
1033
- under their own licenses. [THIRD_PARTY_NOTICES.md](./docs/THIRD_PARTY_NOTICES.md) records the
1034
- assessment of each one, and of the third-party text the repository reproduces.
1
+ ![Venastine Research Harness Screenshot](docs/assets/Venastine_Research_Harness_Demo_Photo.png)
2
+
3
+ # Venastine Research Harness
4
+
5
+ An agentic harness built from scratch — no LangChain, no agent framework — with two modes that share the same machinery:
6
+
7
+ - **Chat** — a normal tool-using assistant loop.
8
+ - **Research** — a ten-pass pipeline that writes an answer, then independently fact-checks and critiques its own claims, audits the assumptions hiding underneath them, scores every claim by a fixed formula rather than by asking the model how sure it is, and revises only what came back flagged.
9
+
10
+ Works with Anthropic, any OpenAI-compatible provider (OpenAI, DeepSeek, Groq, Mistral, local endpoints), and Google Gemini.
11
+
12
+ The design premise is that a model's own confidence is not evidence. Everything in the research pipeline exists to replace "the model said it was sure" with something you can audit: which claims were checked against sources, which critique survived, which assumptions were never stated, and which numbers produced the final tier.
13
+
14
+ ---
15
+
16
+ ## Try it online
17
+
18
+ The same harness runs in your browser, nothing to install, on a [Hugging Face Space](https://huggingface.co/spaces/SolenopsisCampo/VenastineHarnessDemo) and a [ModelScope Studio](https://www.modelscope.ai/studios/Venastine-Research/VenastineHarnessDemo). Each tab gets its own session, deleted when the tab closes.
19
+
20
+ - **Connect a model with a sign-in.** `/connect huggingface` and `/connect openrouter` work on both, and `/connect modelscope` (modelscope.ai) or `/connect modelscope-cn` (modelscope.cn) wherever the deployment can complete that site's sign-in. Requests use your own account's allowance, and the landing page links each provider's page for revoking access.
21
+ - **The shared demo takes no pasted key**, and it does not offer the file and shell tools. A private duplicate of the Space in single-user mode takes both (set `VENASTINE_SINGLE_USER=1` in Hugging Face's duplicate dialog), and so does an install.
22
+ - **It runs a commit of `main` that passed every CI check**, named in each page's footer: the Space is redeployed automatically once all of them pass, and the Studio by hand with the same checks. [PRIVACY.md](docs/PRIVACY.md#the-hosted-demo-roadmap_v3-79) says what a hosted session changes.
23
+
24
+ ---
25
+
26
+ ## Setup
27
+
28
+ **Python 3.11 or newer**, for every local install. `mcp_client/client.py` uses `asyncio.timeout`, which is 3.11+, and 27 sites use runtime `X | Y` annotations (3.10+). `pyproject.toml` declares the floor, so an install refuses an older interpreter rather than failing later from inside the MCP connect path.
29
+
30
+ ### Install directly from GitHub
31
+
32
+ Requires **Python 3.11+**, including its `venv` module. Node, npm, Git, and
33
+ administrator access are not needed. On Linux/macOS (Bash and curl):
34
+
35
+ ```bash
36
+ curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash
37
+ ```
38
+
39
+ On Windows (PowerShell):
40
+
41
+ ```powershell
42
+ irm https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.ps1 | iex
43
+ ```
44
+
45
+ You can also download and inspect the scripts before running them. They
46
+ download the shared Python installer completely, then execute it. It resolves
47
+ `main` to a full commit ID, downloads that source archive, and installs the
48
+ runtime dependencies in an isolated environment. It does not install Python.
49
+ When `uv` is on your PATH, it installs them — copying files rather than linking
50
+ them out of its cache — and pip does otherwise, or if uv fails. With no Python
51
+ 3.11+ on your PATH, the scripts also ask uv for one it already has, and never
52
+ download one.
53
+
54
+ The source lives under `~/.local/share/venastine/app`, with a `venastine`
55
+ command in `~/.local/bin` (`venastine.cmd` on Windows). When that directory is
56
+ not on your PATH yet, the installer puts it there for the terminals you open
57
+ afterwards, the way npm's global commands already are. On Windows it appends
58
+ it to your user PATH, and to the PowerShell window that ran the installer. On
59
+ macOS and Linux it adds a marked block to your own shell's startup file —
60
+ `~/.zshrc`, `~/.bashrc`, fish's `conf.d/venastine.fish`, or `~/.profile` for
61
+ other shells, plus the bash login file you already have on macOS. Running it
62
+ again adds nothing twice. To leave PATH alone, set
63
+ `VENASTINE_NO_MODIFY_PATH=1` or pass `--no-modify-path`. If another
64
+ `venastine` — an npm install, say — comes first on your PATH, the installer
65
+ names it and prints this command's full path instead.
66
+ Then, from your project directory, run `venastine --tui` and use `/connect`.
67
+ `venastine --venastine-doctor` shows the installed version, commit, interpreter,
68
+ and state paths. Credentials and conversation state follow the same rules
69
+ as the npm installation below.
70
+
71
+ Rerun the installer to update, after closing running Venastine sessions. It
72
+ builds a fresh environment before replacing the active source and carries
73
+ your `config.yaml` edits forward through the existing settings merger.
74
+ Previous source trees (`previous-*`) stay under the install directory for
75
+ recovery. Python environments stay in `~/.config/venastine/runtime/github-*`,
76
+ inside the user tier the harness already protects from tool writes. Updates
77
+ therefore use more disk space. An unrelated existing directory or command is
78
+ never replaced.
79
+
80
+ Choose a branch, tag, or full commit ID with `VENASTINE_REF`; choose locations
81
+ with `VENASTINE_INSTALL_DIR` and `VENASTINE_BIN_DIR`, or a Python executable
82
+ with `VENASTINE_PYTHON`; `VENASTINE_NO_MODIFY_PATH=1` leaves PATH alone, and
83
+ `VENASTINE_NO_UV=1` installs with pip even when uv is on your PATH. Set
84
+ these before running either command. The default
85
+ ref is `main`; older refs without `bin/venastine.py` cannot use this installer.
86
+ The installer itself is downloaded from `main`, even when selecting another
87
+ source ref. Bash also forwards options to the helper:
88
+
89
+ ```bash
90
+ curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash -s -- --ref main
91
+ ```
92
+
93
+ From a checkout, `python scripts/install.py --help` lists the same options
94
+ without downloading or installing anything. To remove a GitHub installation,
95
+ remove its command, install directory, the `github-*` runtime directories it
96
+ created, and the PATH entry it added — from your user PATH on Windows, or the
97
+ block between the `venastine GitHub installer` markers in your shell's startup
98
+ file; other state in `~/.config/venastine` and artifacts in your projects
99
+ remain separate.
100
+
101
+ ### From npm
102
+
103
+ ```bash
104
+ npm install -g @yahyahammad/venastine
105
+ venastine
106
+ ```
107
+
108
+ For the full TUI experience you can use:
109
+ ```bash
110
+ venastine --tui
111
+ ```
112
+
113
+
114
+ **npm handles the setup for you.** It delivers the harness as a folder of source — there is no bundled binary — and Python still runs it, so the only prerequisite you provide is an interpreter on PATH. Everything after that happens on first launch: the launcher finds a suitable Python, tells you which one and what it is about to install, and builds an isolated environment with the pinned dependencies once you agree — with uv when it is on your PATH, as the GitHub installers do. It asks every time it would install something, never installs during `npm install` itself, and refuses rather than proceeding when there is no terminal to ask in.
115
+
116
+ Two things differ from a clone, both to make a command you run from anywhere behave sensibly:
117
+
118
+ * **Credentials** fall back to `~/.config/venastine/providers.json` when the directory you are in has no `providers.json` of its own. A local one still wins, so per-project keys keep working.
119
+ * **Conversation state** — `app.db` and the log — lives in `~/.config/venastine/`, so threads and memories follow you between directories instead of each folder getting its own silo. Research reports still land in `./output` beside the work that produced them, and the file-ops workspace stays in the current directory because it is a permission boundary. An existing `./app.db` always wins, so running the command inside a clone uses that clone's data.
120
+
121
+ **Updating keeps your settings.** `npm update` replaces the package directory wholesale, `config.yaml` with it, so the launcher merges your own values back in before the harness starts and prints what it kept. Settings you never touched pick up the new version's defaults, and keys the new version adds arrive at theirs; a value the new version no longer accepts is dropped on its own and named, rather than costing you the rest. It works for values set with `/config` and for ones you edited in the file by hand, which is the only way to set a list like `ensemble_models`. The one case it cannot help with is an edit made after your last session and never launched before you updated -- npm has already replaced the file by the time anything of ours runs.
122
+
123
+ `venastine --venastine-doctor` prints every one of those resolved paths, plus the interpreter and environment it found.
124
+
125
+ ### From a clone
126
+
127
+ ```bash
128
+ pip install -r requirements.txt
129
+ ```
130
+
131
+ This is the contributor path and what the rest of this document assumes.
132
+
133
+ `markitdown` is an optional extra (`pip install -e ".[documents]"`) — its only consumer is behind `read`/`write`/`edit`, which are denied by default and cannot be enabled at runtime. The PDF export path is likewise optional: `pip install -e ".[pdf]"`.
134
+
135
+ ### Two credential stores, deliberately separate
136
+
137
+ | What | Where | Managed by |
138
+ |---|---|---|
139
+ | **LLM provider keys** (Anthropic, OpenAI, Google, …) | `providers.json` | `credentials.py`, template at `providers.json.example` |
140
+ | **Tool API keys** (GitHub token, NVD key, …) | `.env` | `env_secrets.py`, template at `.env.example` |
141
+
142
+ ```bash
143
+ cp providers.json.example providers.json # then add your provider's API key
144
+ cp .env.example .env # then fill in only the keys your tools actually need
145
+ ```
146
+
147
+ Without the first file every model call fails — both shells say so at launch (#138). **In the TUI, `/connect` writes it for you**: `/connect` lists the providers it knows, `/connect <name>` asks for the key in a masked prompt and saves it (0600), and `/connect custom <NAME> <url>` adds any OpenAI-compatible endpoint. Three providers let you **sign in instead of pasting a key**, because their own documentation invites a third-party app to: `/connect huggingface` uses Hugging Face's device code flow (its [OAuth guide](https://huggingface.co/docs/hub/oauth) — a code to confirm on huggingface.co, with the `inference-api` scope only) through the project's own app, named by `hf_oauth_client_id` in `config.yaml`, and `/connect openrouter` uses [OpenRouter's PKCE flow](https://openrouter.ai/docs/guides/overview/auth/oauth), which shows a code to paste back and makes a key you can delete at openrouter.ai/keys. And `/connect chatgpt` signs in to a ChatGPT Plus or Pro plan through [OpenAI's Sign in with ChatGPT](https://developers.openai.com/siwc), which offers it to open-source apps running on your own machine: the page comes back to a one-shot listener on 127.0.0.1, so it works in a local install and never on a hosted one. Once you are signed in, `/model CHATGPT <model>` chats on the plan: the header says "Using ChatGPT plan" with a Manage usage link, and a usage limit stops and points there rather than retrying. Everything else is a pasted key. Either way the next turn uses the new key without a restart. **`/disconnect <name>` undoes it**: it asks first, then blanks the key (the entry's other settings stay for a later `/connect`) and says where to revoke the key itself, or signs out of the ChatGPT plan, revoking it at OpenAI; `--forget` also drops the plan's registration so the next sign-in can be another account. The selected model stays remembered, but the header says "Signed out | use /connect or add API key", including after a restart, so you can reconnect or choose another provider through OAuth or an API key.
148
+
149
+ Both are gitignored. They are kept apart on purpose: provider keys are read by one module at model-call time, while tool keys are handed to code that talks to third parties. Mixing them would put every tool's secrets in reach of the credential path and vice versa. If it is ever unclear which file a new secret belongs in, it belongs in `.env` unless a model provider is going to authenticate with it.
150
+
151
+ ---
152
+
153
+ ## Running it
154
+
155
+ **Run it from the directory you want to work in, not from the harness's own.** The directory you
156
+ launch from is the *project* — workspace trust, `.venastine/`, `/init`'s destination and
157
+ project-scoped memories all follow it — so launching from the install tree would make the harness
158
+ its own project, and that is refused at startup (exit 2). Either of these is the answer:
159
+
160
+ ```bash
161
+ cd ~/my-project && python /path/to/venastine/main.py # the project is where you are
162
+ AGENT_WORKSPACE=~/my-project python main.py # or name it, from anywhere
163
+ ```
164
+
165
+ ```yaml
166
+ # or, in config.yaml, for a setup with no variable to set
167
+ workspace_dir: ~/my-project
168
+ workspace_is_project: true
169
+ ```
170
+
171
+ Working on the harness itself is `AGENT_WORKSPACE=./workspace`, which is the shipped layout and is
172
+ exempt. `workspace_dir` alone is *not* a substitute for either route: it moves the workspace and
173
+ leaves the project where it was, which is what `workspace_is_project` beside it is for.
174
+
175
+ ```bash
176
+ python main.py # chat, new thread
177
+ python main.py --thread <uuid> # resume a thread
178
+ python main.py --mode research "some query" # the ten-pass pipeline
179
+ python main.py --provider OPENAI --model gpt-5.1 # override provider/model
180
+ python main.py --tui # the full-screen interface
181
+ ```
182
+
183
+ The line-based CLI is the default and is never going away. The TUI is a nicer shell over the same code, and most of it is reachable from the CLI too: the CLI's `/help` lists its slash commands, then each TUI command it does not have yet and where to find it instead.
184
+
185
+ Every launch flag is tabulated in the [CLI flag reference](#cli-flag-reference) below; every slash command under [The TUI](#the-tui), and the CLI's just below.
186
+
187
+ A turn prints as it runs, one step at a time: the model's reasoning, what it said, and a line for each tool call as it starts. During a turn, Ctrl+C twice within two seconds stops it at the next safe point; the first press only says so, so a stray one costs nothing. At the prompt, Ctrl+C or Ctrl+D exits. The thread id is printed after the first response so you can resume later — and resuming **replays the conversation**, so you can see what you are picking up. Tool calls replay as one line each; their results do not, since a single research turn can carry hundreds of kilobytes of fetched pages.
188
+
189
+ A line that starts with `/` is a command, as in the TUI, and never reaches the model; an unknown one is an error rather than a chat turn. The CLI has nineteen: `/help`, `/quit`, `/threads`, `/resume`, `/new`, `/goal`, `/agent`, `/skill`, `/grill-me`, `/effort`, `/model`, `/compact`, `/summary`, `/ref`, `/memories`, `/forget`, `/claims`, `/call` and `/network`. They mean what the TUI's do: both shells read one catalog of commands, so a name, its arguments and its description cannot differ between them. `/threads` and `/ref` print a numbered list and ask for a number, or a thread id for one the list does not show. `/call` lists this conversation's tool calls, numbered, and `/call 3` shows the third in full: the whole command and what it returned, or a background session's output, or the run a subagent made. It is the CLI's version of ctrl+clicking a tool line in the TUI. `/model` here lasts for the session, since the CLI starts from `--model` or settings.json.
190
+
191
+ ---
192
+
193
+ ## How the research pipeline works
194
+
195
+ One query goes in. Ten passes run, each in **its own fresh conversation** — they hand each other distilled JSON, never raw history, so a later pass cannot be talked into agreeing with an earlier one by reading how it argued.
196
+
197
+ ```
198
+ Pass 0 Plan what needs establishing, and what entities matter
199
+ Pass 1 Generate the first full answer
200
+ Pass 2 Extract break that answer into individually checkable claims
201
+ D0 Route are there factual claims? (pure code)
202
+ Pass 3a Ground check each factual claim against real sources
203
+ Score Rate sources what each cited source is worth (pure code + embeddings)
204
+ Pass 3b Critique attack each factual claim on its merits
205
+ Pass 3c Completeness what did the answer never address at all?
206
+ Pass 4 Assumptions what is being taken for granted and never stated?
207
+ Pass 5 Tier score and tier every claim (pure code, no model)
208
+ D1 Route which claims are flagged? (pure code)
209
+ Pass 6a Revise rewrite only the flagged claims
210
+ Pass 6b Re-validate re-ground and re-critique them
211
+ D2 Route retries exhausted → fall back to UNVERIFIED (pure code)
212
+ Pass 6c Annotate attach tier labels to claim text (templated, no model)
213
+ Merge Assemble final claim set (pure code)
214
+ Final Synthesise the report, written from the tiered claims
215
+ ```
216
+
217
+ **Six of those stages make no model call at all.** Pass 5, Pass 6c, D0, D1, D2 and the merge are ordinary Python. That is the point: the step that decides how confident to be is a formula you can read, not a judgement call the model gets to make about its own work.
218
+
219
+ ### Confidence tiers
220
+
221
+ Every claim comes out with a tier, a score, and the breakdown that produced it.
222
+
223
+ | Tier | Meaning |
224
+ |---|---|
225
+ | **HIGH** | score ≥ 0.8 |
226
+ | **MEDIUM** | score ≥ 0.55 |
227
+ | **LOW** | score ≥ 0.3 |
228
+ | **UNVERIFIED** | below 0.3 — **or any factual claim that could not be grounded, regardless of score** |
229
+ | **UNVERIFIED_COVERAGE** | not a claim at all: something Pass 3c found the answer never addressed |
230
+
231
+ For a factual claim the score is `0.5 × grounding + 0.35 × (1 − critic severity) − 0.15 per assumption flag`. Non-factual claims (opinion, projection, definition) are capped at 0.65 and can never reach HIGH, because there was nothing to ground them against.
232
+
233
+ **A grounding is worth what its sources are worth.** The grounding term is scaled by the best source the claim has, scored as authority × relevance — so a claim supported by a primary source that plainly says it scores exactly what any grounded claim used to, and one whose only support is a social-media post or a content farm lands LOW and goes back through the revise loop to find something better. A source that is authoritative but does not discuss the claim counts for as little as a perfect match on a junk site; multiplying is the only shape that says both.
234
+
235
+ Every number in the formula is tunable, from `settings.json`'s `confidence` and `source_scoring` sections or by editing the defaults at the top of `core/reasoning/confidence_scoring.py`. A value outside its range falls back to the default for that one constant and says so once — a mistyped weight should not refuse to start a ten-pass run, and should not silently discard the nine weights beside it that were right.
236
+
237
+ A claim that stays flagged after two revise/re-validate rounds falls to UNVERIFIED rather than being quietly retried forever.
238
+
239
+ ### What a source is worth, and how close it actually is
240
+
241
+ Pass 3a used to hand back two numbers per cited source — how authoritative it is, and how well it
242
+ matches the claim — and one model invented both. Nothing checked either, nothing consumed either,
243
+ and no source text survived the pass, so nothing *could* have checked them. A real run on disk
244
+ scored a Pinterest pin `similarity_score: 1.0` beside the Wikipedia article, on the same claim.
245
+
246
+ **Authority is computed from the source, not asked for.** A domain class sets it — restricted
247
+ registries (`.gov`, `.mil`, `.int`, `.edu`, and `gov.uk`/`ac.uk`-style second levels) at the top,
248
+ then standards bodies and peer-reviewed publishers, down through news, preprint servers and generic
249
+ hosts to blogs, forums, social media and content farms. Note that `.org` sits barely above `.com`:
250
+ anyone can buy one, and treating it as trustworthy is the most common version of this mistake. The
251
+ model may then adjust the computed number by at most ±0.15, and only with a stated reason — for
252
+ what a domain cannot see, like a manufacturer's own spec sheet on an ordinary `.com`, or an opinion
253
+ column on a masthead. An adjustment with no reason is discarded. Base, adjustment, reason and method
254
+ are all recorded, so the score can be recomputed from the artifact.
255
+
256
+ **Similarity is a cosine, when you configure an embedder.** `/embedder <PROVIDER> <model>` picks the
257
+ model; the selection is probed rather than looked up in a table, so a provider without an embeddings
258
+ endpoint or a chat slug passed by mistake fails at the prompt rather than three passes into a run.
259
+ Each source's captured text is split into windows about the length of a claim and the best-matching
260
+ one wins — embedding a 5000-character page whole averages twenty topics into one vector and makes
261
+ every long source look equally irrelevant, which is the dilution the windows exist to remove. Raw
262
+ cosine is not a 0–1 score (unrelated text sits near 0.1 on some models and above 0.7 on others), so
263
+ a per-model band maps the useful range onto 0–1 and the raw cosine is recorded beside it.
264
+
265
+ Without an embedder, every run says so in its first trace line and similarity stays the grounding
266
+ model's own estimate — under an anchored rubric, and marked `similarity_method: "llm"` on every
267
+ source, so no reader has to guess which numbers were measured. The model's estimate is recorded even
268
+ when a cosine replaces it, so the two are comparable on every run.
269
+
270
+ **The model's quote is checked against the page.** Pass 3a is asked for the verbatim span it relied
271
+ on, and that span is looked for in the text the run actually retrieved. `quote_verified` has three
272
+ answers: `true`, `false` — meaning the run fetched this page and the quoted words are not in it,
273
+ which is a fabricated citation — and `null`, meaning there was nothing to check against, which is
274
+ not the same thing.
275
+
276
+ **Cited papers can be scored on their own standing.** With `scholar_lookup: true` in `config.yaml`,
277
+ an arXiv or DOI URL is resolved against OpenAlex and scored on venue (peer-reviewed or preprint),
278
+ citation standing, and author h-index. Citation standing is a percentile *within the paper's own
279
+ field-and-year cohort*, measured by two counting queries rather than modelled — OpenAlex's own
280
+ field-normalised metrics are null on preprints, and arXiv is where most cited preprints come from.
281
+ A paper too young, or in a cohort too small, reports that and drops the term rather than scoring
282
+ low; a retraction floors the source outright. It is **off by default**: it is the one network call
283
+ this harness makes outside the tool layer, and an out-of-the-box run should make none you did not
284
+ ask for.
285
+
286
+ The knobs, under `confidence` and `source_scoring` in `settings.json`, each overriding a default in
287
+ code:
288
+
289
+ | Key | Default | Meaning |
290
+ |---|---|---|
291
+ | `confidence.source_quality_floor` | `0.25` | How little a grounding can be worth when its sources are weak — never zero, because a weak grounding still beats none |
292
+ | `confidence.authority_full_credit` | `0.85` | Authority at or above which a source is not what limits the claim |
293
+ | `confidence.grounding_weight_factor` | `0.5` | Weight of the grounding term |
294
+ | `confidence.critic_weight_factor` | `0.35` | Weight of the critic term |
295
+ | `confidence.assumption_flag_penalty` | `0.15` | Subtracted per assumption flag |
296
+ | `confidence.disagreement_penalty_factor` | — | Retired in batch 232: still accepted, warns, and does nothing. A claim the ensemble disagrees about is checked instead of marked down |
297
+ | `confidence.non_factual_score_cap` | `0.65` | Ceiling for claims that were never grounded |
298
+ | `confidence.grounding_weights` | `1.0 / 0.5 / 0.0` | Per grounded / partial / ungrounded |
299
+ | `confidence.tier_thresholds` | `0.8 / 0.55 / 0.3` | HIGH / MEDIUM / LOW; must stay ordered |
300
+ | `source_scoring.window_chars` | `480` | Window size a source is chunked into |
301
+ | `source_scoring.max_windows` | `24` | Windows scored per source |
302
+ | `source_scoring.claim_min_chars` | `80` | Below this, a claim's entities are prepended to the query |
303
+ | `source_scoring.similarity_floor` / `_ceiling` | per-model | Cosine band; unset means use the table for your embedder |
304
+ | `source_scoring.authority_adjustment_cap` | `0.15` | How far the model may move a computed authority |
305
+ | `source_scoring.domain_overrides` | `{}` | `{"host": score}` — how you add your own field's trusted domains |
306
+ | `source_scoring.venue_weight` / `citation_weight` / `author_weight` | `0.4 / 0.4 / 0.2` | How a paper's score is composed |
307
+ | `source_scoring.min_cohort_size` | `200` | Below this the cohort widens before a percentile is trusted |
308
+ | `source_scoring.min_citation_age_days` | `60` | Below this, citation counts are noise and the term is dropped |
309
+
310
+ A value outside its range falls back to the default for that one key and warns once per run, rather
311
+ than refusing to start the run — unlike the compaction knobs above, where an incoherent value burns
312
+ model calls on every turn. An *unknown* key still raises, as everywhere else in `settings.json`.
313
+ `critic_model` and `embedder_model` are rejected there by name: both name a provider this harness
314
+ sends research content to, and a project's `settings.json` outranks your own — use `/critic` and
315
+ `/embedder`, or `config.yaml`.
316
+
317
+ ### A pass that answers the wrong shape is corrected, then it stops the run
318
+
319
+ Each pass is asked for a specific JSON structure, and each one is checked against that structure
320
+ before anything is applied. A payload that parses but is not what the pass promised goes back to the
321
+ model with the problem named — the same corrective turn a malformed one gets — and if it comes back
322
+ wrong again the run fails, saying which pass and which field:
323
+
324
+ ```
325
+ Pass 3b: entry 0 has severity='0.0', which is string; expected number.
326
+ Pass 2: expected a JSON array, got object. Return the array itself, not an object wrapping it.
327
+ ```
328
+
329
+ That matters more than it sounds. The failures worth preventing are not the loud ones: a model that
330
+ answered about claim ids nobody issued used to produce a *finished* run whose trace said
331
+ `Pass 3a: grounded 4 unique entities across 3 factual claim(s)` while grounding nothing, and then
332
+ spent four more model calls concluding that nothing could be verified. Those counts are what the
333
+ pass was **asked** about; the trace now reports what was actually applied — `grounded 2 of 3` — so a
334
+ pass that half-worked says so.
335
+
336
+ The run does not die over a single stray id: entries that resolve are applied, and only a payload
337
+ where *nothing* matched is treated as a failure. Every number in `04_confidence.json`'s
338
+ `score_breakdown` is one that was actually used, so the fields reconstruct the score they came with.
339
+
340
+ ### Different models can check each other
341
+
342
+ Set `CRITIC_MODEL` and passes 3a, 3b and 6c run on a *different* provider and model from the one that wrote the answer. A model checking its own output brings its own blind spots to the inspection.
343
+
344
+ **Ensemble mode** extends the same idea to the answer itself. List `{provider_name, model}` pairs under `ensemble_models` in `config.yaml` (a settings.json key is deliberately absent — choosing providers multiplies spend, so it stays in the harness's own file) and Pass 1 runs once per entry, each candidate on its own provider and model. Fewer than two *distinct* pairs is refused: N copies of one model agree most confidently on that model's systematic errors, which is exactly where agreement has to mean something. Claims extracted from all candidates are pooled. A factual claim no more than half the candidates asserted is *contested*: it keeps the score its evidence earns and goes through the revise-and-revalidate passes to be checked, with the count in its feedback. Since batch 232; it used to be marked down instead, which no revision could undo. A candidate that fails mid-run is named and skipped; if only one survives, the run degrades to the ordinary single-response path rather than scoring an "ensemble of one". Artifacts come out as `01_candidate_1.md`, `01_candidate_2.md`, … numbered to match each claim's `asserted_by_candidates` tags.
345
+
346
+ ### What you get out
347
+
348
+ Every run writes `output/<run_id>/`:
349
+
350
+ ```
351
+ 00_plan.md 04_assumptions.json trace.md
352
+ 01_raw_response.md 05_confidence.json report.md
353
+ 02_claims.json 06_revisions.json report.pdf (if weasyprint installed)
354
+ 03_grounding.json 07_review.json confidence_chart.svg
355
+ 03_critic.json granted_calls.json sources/ code/
356
+ 03_completeness.json pass_threads.json
357
+ ```
358
+
359
+ `sources/` holds what each cited page actually served: `index.json` lists every URL the run retrieved text from — with the tool, the timestamp, a content hash and the length — and one `<sha256>.txt` per document holds the text itself, redacted. That is what makes a similarity score checkable after the fact rather than a number you have to take on trust; set `persist_source_text: false` in `config.yaml` to keep the index and drop the text.
360
+
361
+ In ensemble mode the Pass-1 slot is `01_candidate_1.md`, `01_candidate_2.md`, … — one file per surviving candidate, numbered to match the trace and each claim's `asserted_by_candidates` tags, since no single candidate is "the" response the claims came from.
362
+
363
+ Runs are also persisted to the database, so a run that crashes halfway still leaves a record populated through its last completed pass — and so does one you kill with Ctrl+C.
364
+
365
+ **Source use and publishing:** Fetched pages (`web_search`, `fetch_url`, `arxiv_search`, and MCP servers) are subject to their origin's terms, including `robots.txt` and Terms of Service — the harness does not bypass paywalls or ignore rate limits. `report.md` / `report.pdf` may quote third-party pages; do not republish them with large verbatim excerpts without rights — quote, paraphrase, and cite, and verify any claim that matters. See `PRIVACY.md` for what leaves your machine.
366
+
367
+ ### Watching it happen
368
+
369
+ A ten-pass run takes minutes. It reports as it goes, in both shells: pass boundaries, the tools each pass is calling, code-only stages, claim tiers as they land, retry rounds, and warnings.
370
+
371
+ ```bash
372
+ python main.py --mode research "does the claim about X hold up?"
373
+ ```
374
+
375
+ In the TUI, a sidebar tracks passes and a running tier tally; `/claims` or **ctrl+l** opens every claim with its tier, grounding status, assumption flags and score breakdown — during the run as well as after it.
376
+
377
+ ### Having it review itself
378
+
379
+ ```bash
380
+ python main.py --mode research --review "some query"
381
+ ```
382
+
383
+ A reviewer agent reads the finished run and proposes corrections. **Each one is offered to you individually** — accept, reject, refine, or reject everything. Nothing is applied without your say-so, and there is deliberately no "accept all" button, because an injected instruction only needs one reflexive yes. If nothing can ask you (a piped or scripted run), the review still runs and still records what it found, but applies nothing.
384
+
385
+ ---
386
+
387
+ ## Security model
388
+
389
+ The harness assumes the model is working with untrusted text — web pages it fetched, files it read, output from third-party MCP servers — and that any of it may be trying to steer the next tool call.
390
+
391
+ ### Every tool says what a call to it may cost
392
+
393
+ Approval answers *whether* a tool may run. It says nothing about how long it may run for, and until
394
+ recently nothing else did either: a maths tool handed a large enough number simply never came back,
395
+ taking the turn — or an unattended ten-pass run — with it.
396
+
397
+ Each registered tool now declares one of three answers, and a tool registered without one fails at
398
+ startup rather than at its first call:
399
+
400
+ | | |
401
+ |---|---|
402
+ | **compute** | The six maths tools. Pure functions of their arguments with nothing to interrupt them from the inside, so they run in a separate process that can be stopped — 20 seconds by default, plus CPU and memory ceilings on Linux |
403
+ | **io** | Anything that reads a file, fetches a page or talks to an MCP server. Each already carries its own limit: a request timeout, a size check before opening, a sandbox |
404
+ | **human** | `ask_user` and `spawn_subagent`, which wait on a person or on a separately metered sub-run. A ten-minute pause here is the feature |
405
+
406
+ The distinction between the first two is not bureaucratic. A timeout wrapped around a blocking read
407
+ can only stop *waiting* — the work carries on — so declaring an operation bounded when it is not
408
+ would produce a harness that reports timeouts that never happened. Compute tools get a bound that
409
+ genuinely stops them; io tools have to already have one, and three that did not were fixed:
410
+
411
+ ```
412
+ before after
413
+ edit (on a 30 MB file) 60.0 MB 0.0 MB rejected before opening, as `read` always did
414
+ read_project_doc 60.0 MB 0.1 MB one page costs one page, not the whole document
415
+ fetch_url unbounded capped streamed, so a hostile body stops at the cap
416
+ ```
417
+
418
+ When a compute tool does hit its limit, the model is told which tool and which limit, so it can ask
419
+ for something smaller instead of retrying the same call:
420
+
421
+ ```
422
+ symbolic_math exceeded its 20s limit and was stopped. The inputs given are too
423
+ large for this operation -- try smaller values.
424
+ ```
425
+
426
+ ### Access control: stricter always wins
427
+
428
+ Two separate questions, asked in this order, and they never blend into one score:
429
+
430
+ 1. **May this tool be called at all?** — a logical AND across the global config and every active layer (the current agent, each skill it activated). A tool disabled globally can never be re-enabled by anything else; that check runs first and unconditionally.
431
+ 2. **Does this specific call need you to approve it?** — a logical OR across the same layers plus the tool's own dynamic check.
432
+
433
+ Because approval ORs, an override can only ever *add* a prompt. There is no way to spell "this tool no longer needs approval" from an agent or skill definition — and since those can arrive with a repository you cloned, that asymmetry is the design rather than a gap.
434
+
435
+ ### What needs approval by default
436
+
437
+ | | |
438
+ |---|---|
439
+ | No approval | `web_search`, `fetch_url`, `arxiv_search`, `get_time`, the six maths tools (`symbolic_math`, `linear_algebra`, `probability_stats`, `discrete_math`, `logic`, `geometry`), `load_skill`, `pin`, `unpin`, `ask_user`, `todo_write`, `read_project_doc`, and the three that act on this conversation's own background sessions (`shell_sessions`, `shell_output`, `shell_kill`), and `shell_input` — typing into an interactive shell you already approved (a line naming a protected path still asks, and a Ctrl-C never does) |
440
+ | Depends on the call | `read`, `view_image`, `write`, `edit` — decided per path, and all four are denied by default anyway. `view_image` is also only offered where the image can reach the model: a provider marked `accepts_images` in `providers.json`, outside a research pass |
441
+ | Always | `shell` and the three that start a session (`shell_background`, `shell_monitor`, `shell_interactive`), `spawn_subagent`, `remember`, `write_project_doc`, and **every MCP tool** |
442
+
443
+ Every registered tool appears in that table, and a test asserts it (audit #125): `ToolPermissions` and `ToolApprovals` are plain dataclasses, so "did the table keep up with the registry" is a question the suite can answer instead of a reader. `write_project_doc` is the one the omission mattered for — it is what `/init` uses to write documents into a repository, and §24's I1 gives it a fixed allowlist of document *names* with no path parameter precisely because it is dangerous enough to constrain.
444
+
445
+ `ask_user` is ungated for a reason worth stating, since a table of default approvals is exactly where it belongs: an approval-gated tool is not *advertised* where nothing can ask, so gating the tool whose entire job is asking would make it invisible rather than deniable.
446
+
447
+ `pin` and `remember` sit either side of the line that matters: pinning a message is thread-scoped and undoable (`unpin` releases it), while remembering something outlives the conversation and silently shapes ones you have not started yet.
448
+
449
+ ### `shell` is classified, not just approved
450
+
451
+ `shell` ships **disabled** (`tool_permissions.shell: false` in `config.yaml`) and cannot be enabled at runtime, so none of this applies to a default install. If you do enable it, the gate is `shell_approval_mode` in the same file:
452
+
453
+ | mode | behaviour |
454
+ |---|---|
455
+ | `always` | every command is asked about, whatever it does |
456
+ | `tiered` | **shipped.** The classifier decides — see below. Only a read-only command runs unasked; anything that can run code asks, even inside the container |
457
+ | `contained` | anything the container confines runs unasked unless it needs network, code included; reads outside the workspace and network commands still ask. Flagged on the startup banner and the TUI badge |
458
+ | `never` | nothing is ever asked about |
459
+
460
+ There is deliberately no second switch: `tool_approvals` has no `shell` key, so nothing here can disagree with the mode. An agent's `approval_overrides` still reaches shell with the same one-way power -- an agent can demand approval for a command the mode would auto-approve, and can never wave one past a gate the mode set. An unknown mode string raises at startup rather than falling back to a default — one direction of that default asks about everything and the other about nothing, and a typo cannot pick.
461
+
462
+ Under `tiered` and `contained`, each command is classified **once** into what it can do, and the same answer is read by the approval check and by the sandbox that runs it:
463
+
464
+ | tier | what it is | where it runs | asked under `tiered`? | under `contained`? |
465
+ |---|---|---|---|---|
466
+ | `INERT` | read-only command, every argument inside the workspace | container (host when no container runtime is available) | no | no |
467
+ | `HOST_READ` | read-only, but an argument reaches outside the workspace | host | **yes** | **yes** |
468
+ | `SANDBOXED` | anything else, no network — it may run code | container | **yes** | no, if a container runtime (Docker or Podman) is confirmed up |
469
+ | `SANDBOXED_NET` | **any** word is on the network allowlist (`curl`, `pip`, `git`, …) — first word only for an INERT command, which cannot chain | container, with network | **yes** | **yes** |
470
+ | `UNKNOWN` | could not be characterised at all | — | **yes** | **yes** |
471
+
472
+ Under `tiered` the auto-approved set is narrower than the `read` tool's, which is already unprompted inside the workspace. There is **no list of interpreters** behind that: `python -c` is the obvious case, but `pytest` runs a `conftest.py`, `make` runs a Makefile, and `"python"`, `python3.13` and `echo x | python` are all the same call to a shell, so every command that is not `INERT` is treated as able to run code. Under `contained` a `SANDBOXED` command runs unasked and can do anything code can do inside the container — corrupt the workspace, as `write` and `edit` already can, or read a `.venastine/` directory the workspace contains — bounded to 1 CPU, 2 GB, 200 processes, 120 seconds, no network and no host filesystem.
473
+
474
+ **The argument rule does not parse, deliberately.** Every token after the first is read as a path and required to stay inside the workspace; a flag like `-la` passes only because it is *relative*, not because anything recognised it as a flag. Refusing to interpret shell syntax is what makes the check trustworthy — a classifier that parses is a shell parser, and a parser that is wrong auto-approves something dangerous. The cost is occasional false positives: `grep /etc/passwd notes.txt` searches for a string that looks like a path, and costs one prompt.
475
+
476
+ **Quoted arguments are never inert.** The corollary of not parsing: the raw tokens have to be the real tokens. A quoted command is classified `SANDBOXED` and goes to a container, because the classifier splits on whitespace while the executor splits with `shlex` — and `shlex` strips quotes, so `cat "/etc/passwd"` read as one token *inside* the workspace and then ran as two tokens naming the host's file. Under `contained` with Docker this costs nothing: `cat "my notes.txt"` is still auto-approved, it simply runs in the container. Under `tiered` it asks, as every command that is not `INERT` does. Fixed in batch 37; `'single quotes'` and `--file="/etc/x"` did it too.
477
+
478
+ **Escaped arguments are never inert either.** The same corollary, one character further, and it
479
+ took a second batch to find: `shlex` consumes `\` exactly as it consumes quotes, so
480
+ `cat \/etc\/passwd` read as one relative token inside the workspace and then ran as `/etc/passwd` on
481
+ the host — measured on a POSIX host at the shipped default. With `\` rejected the character class is
482
+ now **closed** under `shlex`, which consumes exactly whitespace, `'`, `"` and `\`: the classifier's
483
+ tokens and the executor's are provably the same list. On Windows this costs a backslash path such
484
+ as `cat sub\dir\notes.txt`, which moves to the container and fails there — use forward slashes.
485
+
486
+ **These settings are read once, at startup.** Since batch 40 `SHELL_APPROVAL_MODE`, both fallback
487
+ flags and `REDACT_TOOL_OUTPUTS` are bound into a frozen posture (`security/posture.py`) rather than
488
+ consulted at each decision, so nothing running in-process can move them mid-session. If any of them
489
+ is set to something weaker than the shipped default, the harness says so at launch — on stderr, in
490
+ `app.log`, and as a badge in the TUI sidebar for as long as the session lasts.
491
+
492
+ **An approved host read still reads the host.** `cat /etc/shadow` is asked about; if you say yes, it runs on the host, because that is what you approved. Routing it into a container would answer a different question than the one you were asked.
493
+
494
+ **`never` is the old unbounded behaviour, kept on purpose.** In that mode `cat ~/.aws/credentials` runs on the host, unprompted, and its output goes into the model's context. It is reachable by writing the word `never` — which is the fix for [#157](https://github.com/YahyaHammad/Venastine-Research-Harness/issues/157): previously you reached it by switching off a field that read like "stop nagging me".
495
+
496
+ `shell_approval_mode` is **rejected** in `.venastine/settings.json`, by name and with a reason. A project's settings beat your own, and a cloned repository must not be able to set this. Set it in `config.yaml`.
497
+
498
+ If your workspace contains a `.venastine/` directory, it is bind-mounted **read-only** inside the container, so a sandboxed command cannot rewrite the context and MCP definitions that feed later prompts. This covers writes on the container path only, under Docker or Podman — not reads, and not the subprocess fallback.
499
+
500
+ **The workspace may not be the harness.** The container mounts your workspace read-write, and a sandboxed command with no network is auto-approved inside it — so a workspace pointing at the harness's own directory would be unattended write access to the code about to run next. `AGENT_WORKSPACE` is refused at startup, and by the sandbox, when it *is* or sits *inside* the harness install tree or `~/.config/venastine/`. **Since batch 107 the implicit route is refused too**: with the variable unset the project is the directory you launched from, so launching from the install tree made the harness its own project -- the same state, reached by saying nothing instead of by saying it. The two artifact directories `workspace/` and `output/` stay usable, which is the shipped layout; everything else in the install tree is refused, including a module added in a later release — it is an allowlist, so it fails closed. When one of those trees is *nested inside* your workspace instead — a workspace set to your home directory, say — there is nothing to refuse, so it is bind-mounted read-only, along with `providers.json`, the conversation database and the log directory. The guard names the harness that is *running*, so pointing a globally-installed `venastine` at a development clone of its own source still works.
501
+
502
+ **From approval to execution, one answer throughout.** The classification is computed once per call and the same profile is handed to both the approval check and the sandbox, so what was approved is what runs. **The container comes from Docker, or from Podman when Docker cannot run one** — probed once per process, Docker first. Podman is used only if it can enforce the memory, CPU and process limits below: a rootless Podman on cgroups v1, or without those controllers delegated to your user, accepts the flags and ignores them, so it is refused and the reason is logged and shown. An inert command runs in that container as a plain argument list with no shell, and on the host only when no runtime is available. Anything else shares the probe's answer between gate and runner: if a runtime was up when the call was approved but gone when it executes, and the only route left is the fallback, the call returns an error telling the model to retry rather than silently downgrading onto the host. With no container runtime available and `allow_insecure_sandbox_fallback: true` in `config.yaml`, non-inert commands fall back to a weakly-isolated host subprocess — prompted per run unless `auto_approve_sandbox_fallback: true` opts that prompt away. Inside the container the workspace is mounted at `/workspace` and output comes back truncated at 50,000 characters (`max_read_chars`); the container runs under a 120-second wall clock, 2048 MB of memory, a single CPU core and a 200-process cap, while the weak fallback enforces its own rlimits instead — 30 CPU-seconds and the same memory ceiling — **on Unix only**. `rlimit` does not exist on Windows, so there that route runs under the wall clock and nothing else, which is worth knowing before you turn it on: it is the route with no filesystem isolation, and on Windows it is also the route with no memory or CPU ceiling. **A third backend exists and ships off: WSL.** With `allow_wsl_backend: true`, `shell`, `shell_background` and `shell_monitor` take a `backend` field the agent sets per call, and `backend: "wsl"` runs the command in a WSL distribution (`wsl_distro`, or WSL's default) instead of the container. It is there for work that genuinely needs your machine or a Linux toolchain the image does not carry — and it gives up everything the container provides: your own files, the network always on, no memory or process limits, no read-only bind over `.venastine/`, and Windows interop that no argv or environment choice can switch off. So it is treated as uncontained for every tier: under `tiered` and `contained` only a read-only command whose arguments are all inside the workspace runs without a prompt, a command naming a protected path segment is refused outright rather than asked about, and the backend appears on the startup banner and the sidebar badge for as long as it is on. An interactive shell cannot run there yet. **A fourth backend exists and also ships off: SSH.** With `allow_ssh_backend: true` and a host configured (`ssh_host`, `ssh_user`, `ssh_remote_workspace` and a PINNED `ssh_host_key`), `backend: "ssh"` runs the command on that machine. It is the strictest of the four to use and the least protected to run on: **nothing there is auto-approved, not even a read-only command**, because the check that decides whether a command's arguments stay inside the workspace resolves them against this machine's filesystem and would be answering about the wrong one. Authentication is a key or a running `ssh-agent` and the harness never asks for or holds a passphrase; a host key that changes is refused rather than accepted; and two things are disclosed rather than fixed — ending a session does not kill the remote command (its in-guest `timeout` does), and `write` saves locally while the shell runs remotely. **The harness can hold the credentials those backends need, encrypted at rest.** `/secrets` in the TUI (or `--secrets` on the CLI) stores named values -- `ssh.<host>.key_passphrase`, `ssh.<host>.login` -- in `~/.config/venastine/secrets.json`, sealed with AES-256-GCM under a master passphrase you type once a session. That is what lets an encrypted SSH key or a password-authenticated host work at all: before it, an encrypted key with no agent simply failed. A stacked `publickey,password` host works too. Nothing is taken from the command line -- every value is read at a masked prompt, because an argv is readable by every process on the machine and lands in your shell history. The file is useless without the passphrase, so a shell command the agent runs reads ciphertext; the plaintext lives in process memory only and is dropped on `/secrets lock`, on quit, and on anything unexpected. A stored value never reaches the model: it is stripped from tool output whatever your redaction setting says. **A command can also be run as root, on those two backends and nowhere else.** A call may set `needs_root`; the harness then prefixes `sudo -k -S -p '' --` and supplies the password stored for that machine as `wsl.<distro>.sudo` or `ssh.<host>.sudo`, on the command's standard input and nowhere else -- never in an argv, an environment or a log, and the command behind `sudo` has its own stdin closed so it cannot read the password either. The container is refused because a command there already runs as root, and the host fallback because Windows elevation is a consent dialog rather than a password prompt. **You are asked every single time**, above both sandbox opt-ins and in every approval mode but `never` -- and the question is asked whether the call declares `needs_root` or merely writes `sudo` itself, so the declaration is not a thing to forget your way around. If no password is stored for that machine the call is refused outright and the refusal names the entry to create: the stored secret is what turns root on at all, and there is no separate switch for it. Two environment knobs affect the mechanics: `AGENT_SHELL` overrides the detected host shell (bash on Linux/macOS, PowerShell on Windows), and `AGENT_SANDBOX_IMAGE` swaps the default `docker.io/library/python:3.13-slim` image (fully qualified, so Podman resolves it without a short-name alias).
503
+
504
+ ### "Headless" means *unable to ask*, not "not a GUI"
505
+
506
+ When nothing can put a question in front of a human, approval-gated tools are **hidden from the model entirely** rather than offered and then denied. This is not cosmetic. A tool that is advertised and always refused gets chosen again and again, and the only trace is a denial string buried in a tool result — that exact bug shipped once here, in which `fetch_url` was registered, documented as working, and denied on every call for its whole life. Registering a tool without declaring its permissions now raises at import time instead.
507
+
508
+ The rule that falls out of this: **inability to ask is never treated as permission to proceed.**
509
+
510
+ Two consequences, both easier to get wrong than they look:
511
+
512
+ - **A grant is an answer, so a granted tool stays visible.** "Nothing can ask" is not "nothing has answered" — a pre-flight grant answered the question before the call existed. Getting this wrong is what made `--grant-tools` do nothing on its own for three sections (see below).
513
+ - **A headless run cannot spawn a subagent at all**, because spawning is itself approval-gated. That is also why a spawned subagent *keeps* its gated tools: the only runs that can spawn have a human reachable, and the child inherits that route. It is not a separate permission — it falls out of this rule.
514
+
515
+ When a gated call *is* refused because nothing could ask, the model is told which of the two reasons applies: the tool is unavailable however it is called, or it needs approval **for these arguments** and may not for others. "Requires approval and was not given" invites a retry that cannot succeed, and the model spends its remaining steps discovering that.
516
+
517
+ ### Content policy, on the way in and on the way out
518
+
519
+ Symmetric, and applied centrally to every tool in every mode rather than by tools that opted in:
520
+
521
+ - **Arguments are refused, not rewritten.** If a tool call carries something matching a credential pattern or a URL on the blocked-domain list, the call is refused. Silently rewriting an argument would run the tool with parameters neither you nor the model chose, and then report success.
522
+ - **Results are redacted.** Anything key-shaped in a tool's output becomes `[REDACTED]` before it reaches the model, the transcript, the database **or the log file**. This recurses through nested structures — third-party MCP servers return arbitrary JSON, and that was once the one path nothing scanned — and it covers *every* key of a result, not a list of expected ones, because the two search tools returned theirs under a key the list did not name. The log was a fourth sink and an unlisted exception rather than an accepted one: a failing tool's traceback carries the request that produced it, which for an HTTP client is a URL with the key in its query string.
523
+ - **A fetched page is its text, and a PDF is read.** `fetch_url` returns a page's main content without the site's menus, banners and scripts, with links marked `[L1]`, `[L2]` and their URLs listed beside each page of text; a PDF's text comes back page by page, parsed in a separate process that a timeout stops. A long document is read 5,000 characters at a time by offset, to its end. An image or archive is refused with a reason. `fetch_max_html_mb` and `fetch_max_pdf_mb` in `config.yaml` bound the downloads (2 MB and 32 MB).
524
+ - **URLs are checked before every request, including redirects.** `fetch_url` follows redirects by hand and re-checks each hop, so a public URL that redirects to a blocked domain or into your private network is refused *before* the request is issued. Addresses that are not publicly routable — loopback, private ranges, link-local, and the cloud metadata endpoint at `169.254.169.254` — are refused outright. The blocklist matches subdomains. **Known limitation:** the address check resolves and then hands the URL to the HTTP client, which resolves again, so a host whose DNS changes between the two is not covered.
525
+ - **The scan fails closed.** Traversal is depth-bounded so a hostile structure cannot exhaust the stack, and hitting that bound redacts rather than passing the value through. A bound that emits unchecked data is just a documented bypass.
526
+ - **Refusal reasons never quote the secret.** Explaining that a credential leaked, by printing it, would leak it into model context, the transcript and the database.
527
+ - **Tool arguments are redacted before they are truncated** for display — truncating first can cut a key below the length its pattern needs to match, which turns a display feature into a disclosure.
528
+
529
+ ### Project directories are untrusted until you say otherwise
530
+
531
+ A repo you clone can carry project content the harness will load: `.venastine/` — agents, skills, `settings.json`, `mcp.json` — and a root `AGENTS.md`, which is the project context document. On first run in a directory you are shown what it contains and asked once — the file list, `settings.json` and `mcp.json` verbatim, the opening of `AGENTS.md`, and **every agent's and skill's description**, because all of those go into the system prompt of every run in the project the moment you say yes. A repo with an `AGENTS.md` and no `.venastine/` is asked about too; a repo with neither has nothing to trust and is silent. Until then that content is **absent, not loaded-and-disabled**. Trust is keyed to the resolved path *and* a content hash, so it does not silently carry over when the files change.
532
+
533
+ ```bash
534
+ python main.py --trust-project # for CI and scripts
535
+ ```
536
+
537
+ For MCP servers, agents and skills, precedence is **harness > user > project** — inverted from the usual "more specific wins", because here "more specific" means "arrived with someone else's repository".
538
+
539
+ ### Granting tools to an unattended run
540
+
541
+ A ten-pass research run has no human at the keyboard for minutes at a time. Two independent controls, both off by default:
542
+
543
+ ```bash
544
+ python main.py --mode research --grant "query" # pick from a list, interactively
545
+ python main.py --mode research --grant-tools mcp__files__search "query"
546
+ python main.py --mode research --attended "query" # approve every gated call as it happens
547
+ ```
548
+
549
+ The limits are the interesting part:
550
+
551
+ - **A grant only covers tools with no per-call gate**, which in practice means MCP tools — literally so: **on a stock install with no MCP server connected, the picker is empty.** `shell` and the file tools decide case by case from the actual arguments, so granting the *name* would authorise a call you never saw; nobody ticking a checkbox labelled "shell" is agreeing to every command for the rest of the run. Those fall back to being asked. Everything else is either ungated already or excluded below.
552
+ - **A grant is per tool, and shows you what each one says it does.** MCP exposes no read-only/write metadata, so nothing can tell you that one granted tool searches a library and another posts to a channel; showing its own description is the whole of informed consent here.
553
+ - **Every tool declares how far approving its *name* goes**, and both places that can pre-grant — an unattended run, and the sign-off when the model spawns a subagent — read the same declaration. They used to keep separate lists, which is how the sign-off ended up offering the two tools below.
554
+ - **`spawn_subagent` and `remember` can never be pre-granted, anywhere.** Approving a spawn *is* the sign-off for the child's entire tool set, so pre-granting it would compound one yes into unbounded delegated authority. A memory outlives the run. An *attended* run can still approve either one live — a per-call human decision, which is what the gate is for.
555
+ - **`write_project_doc` can be signed off for one turn, but never pre-granted to an unattended run.** It resolves a document *name* to a path and overwrites it with no diff and no second question, and one of the files it can write is the project context injected into later sessions. A human answering about one named agent for one turn is consent; one tick covering ten unattended passes that are reading fetched web pages is not.
556
+ - **A grant makes the tool visible to the model, not just permitted.** These are two different things and the difference was a real bug: gated tools are normally withheld from a run that has no way to ask about them, and until recently the grant was not consulted when deciding that — so `--grant-tools` *on its own* authorised a tool and then sent the model the same list as an unflagged run, while printing that it had authorised something. It only worked alongside `--attended`, which is not the mode any of this is for. A stale grant still cannot widen anything: what may be pre-granted is re-checked against the tool's own declaration at the point the list is built.
557
+ - **Running out of grant budget degrades to asking, not to failing.** One budget is shared across all ten passes, and it does not retract a tool mid-run — the ceiling changes *when* you get asked, never what the model can see.
558
+ - **Grants are never persistable, and the setting is rejected by name** so nobody "fixes" the omission. A persisted *mode* can only ever add prompts; a persisted *grant list* could only ever remove them — and `settings.json` is the one config file where a project's values beat yours.
559
+
560
+ ### MCP servers: allowed by default, trusted by default never
561
+
562
+ MCP tools can be called without you naming them, but every call is approved individually unless you add `"autoApprove": true` to that server. They are third-party code the model can reach, and config files grow entries that installers appended.
563
+
564
+ ---
565
+
566
+ ## Everything else
567
+
568
+ ### Long conversations condense themselves
569
+
570
+ Older turns are summarised automatically as a thread grows. **The archive is never edited** — the full history is always recoverable, and summaries are never written to disk as messages.
571
+
572
+ Two summarisation strategies exist:
573
+
574
+ - **`chain` (the default)** — each compaction summarises the *previous summary plus whatever followed it*. The input never grows past summary-plus-tail, so cost stays constant per compaction forever. The trade: loss compounds over a very long-lived thread, since a summary is being made of a summary.
575
+ - **`rederive`** — each compaction summarises the *original messages*, so exactly one summarisation step ever sits between what you said and what the model sees. Fidelity-optimal; the cost is that the whole covered span is re-sent every time.
576
+
577
+ Whichever you configure (`compaction.strategy` in settings.json), a span too large for one call falls back to chain with a warning, and one too large even for chain has its oldest material truncated — stated in both the instruction and the stored summary, never silently.
578
+
579
+ `pin` keeps recent turns out of any summary (capped at half the compaction trigger per call — a pin is a permanent floor, so refusing beats trimming); `unpin` releases it again when pinned detail goes stale. `/compact` in the TUI triggers a compaction by hand. **When compaction runs depends on what the thread is**: a chat thread folds at a share of the model's context window (85% by default, so 850k on a 1M model and 170k on a 200k one); research passes and subagents compact only at a hard backstop just under that window, wherever they are resumed — spending a model call on a judgement nobody is watching is not worth it mid-run. The chat trigger used to be a flat 40k regardless of model, which meant a 1M-window thread was condensed at 4% of its window.
580
+
581
+ The knobs, all under `compaction` in `settings.json`, each overriding a default in `config.yaml`:
582
+
583
+ | Key | Default | Meaning |
584
+ |---|---|---|
585
+ | `trigger_tokens` | `40000` | Measured context size that fires automatic compaction |
586
+ | `warning_margin_tokens` | `8000` | How far before the trigger you are warned — room to pin something or wrap up first |
587
+ | `keep_recent_tokens` | `4000` | Most-recent tokens that always stay verbatim |
588
+ | `keep_recent_turns` | `3` | Turn floor beside the token floor — whichever protects more wins, plus the current turn, which never folds |
589
+ | `strength` | `3` | Target compression ratio, 1–5: keep ~40% at 1 down to ~5% at 5 |
590
+ | `max_retries` | `2` | Corrective re-asks when a summary misses its target ratio |
591
+ | `strategy` | `"chain"` | Or `"rederive"`, as above |
592
+
593
+ `/trigger` and `/window` override those numbers, and they have different lifetimes on purpose. `/trigger` is for this session only: never written to disk, and `/model` clears it, so switching away and back gives you the derived value. `/window` is REMEMBERED — a context window is a fact about a deployment rather than a preference about a session, and one you must retype after every model switch is one nobody sets. It is kept per `(provider, model)`, for every pair you have answered for, and it outranks both what the provider reports and the built-in table. `/window off` restores the derived value. Both are bound to the `(provider, model)` they were set for, so an agent pinning its own model or a critic-routed pass uses that model's own value rather than a number tuned for a different one. `/compact --strength N` overrides strength for that one invocation and persists nothing; an unknown flag there is an error rather than an ignored typo, because compacting at the default while you believe you asked otherwise looks exactly like a compaction that obeyed you. The relationships between these values are validated rather than trusted — the warning margin must sit strictly below the trigger, and the keep-recent floor strictly below it too — so an incoherent set is refused at startup instead of firing compaction at nonsense times.
594
+
595
+ A replayed thread always shows what you originally said, never the summary — the archive is what is replayed, so a compacted conversation reads back the way you had it.
596
+
597
+ ### Durable memory
598
+
599
+ `remember` saves a fact that outlives its thread, scoped to this project or to everything — **with your approval each time**, which is also why it is unreachable from any unattended research pass.
600
+
601
+ ```bash
602
+ python main.py --memories # list what's visible from here
603
+ python main.py --forget <id> # delete one, by id
604
+ ```
605
+
606
+ Removal is by id, never by substring: a substring matching two memories would have to pick one, and picking silently deletes something you did not name. Injection is capped at 50 most-recent, and the model is told when it is seeing a truncated set.
607
+
608
+ ### Agents and skills
609
+
610
+ Markdown files with YAML frontmatter, discovered from three tiers (built-in, yours at `~/.config/venastine/`, the project's at `.venastine/`). Agents set a system prompt and a tool policy; skills pin a body of instructions into the session. `/agent`, `/skill`, `/goal`, `/grill-me`.
611
+
612
+ A skill declaring `additional_tools` is stating a *need*, not granting anything — activation proceeds and tells you what is missing.
613
+
614
+ An agent declares `spawnable` — whether the `spawn_subagent` tool can actually feed it. A task string in a fresh thread is all a spawn can pass, and an agent that needs a transcript, a thread or a finished research run cannot be given one; spawning it anyway produces a confident answer about nothing. Your own agents are not spawnable unless they say so.
615
+
616
+ Eleven ship. Five are not spawnable, each because a real caller supplies something a task string cannot carry — `compactor` (a stretch of transcript), `initializer` (a document manifest), `pipeline-reviewer` (a finished research run), `grill-me` and `plan` (the live conversation). Six are:
617
+
618
+ | agent | for | reach it with |
619
+ |---|---|---|
620
+ | `plan` | designing an approach before the work starts — reads what exists, names the decisions, says what would make the plan wrong | `/agent plan` |
621
+ | `explore` | finding where something lives and how it is wired, in a codebase or in the literature, and reporting locations and evidence | `spawn_subagent`, or `/agent explore` |
622
+ | `review` | reading a finished change or document against what it claims to do, and reporting defects with the evidence for each | `spawn_subagent`, or `/agent review` |
623
+ | `build` | implementing a specified change from pointers — reads what exists, makes the smallest diff, reports what changed plus how it was verified | `spawn_subagent`, or `/agent build` |
624
+ | `test` | verifying a change against its claim — reproduces, runs the checks, reports pass/fail with the exact command and what was not covered | `spawn_subagent`, or `/agent test` |
625
+ | `writer` | turning notes, claims or sources into clear structured prose for a named audience — reports, READMEs, changelogs, decision records | `spawn_subagent`, or `/agent writer` |
626
+ | `general` | scoping a task's intent, splitting it into self-contained sub-tasks, delegating to specialized subagents in parallel, synthesizing their answers | `spawn_subagent`, or `/agent general` |
627
+
628
+ `build`, `test`, `writer`, `explore` and `review` are leaves: they take a task string as their entire input and cannot spawn further. `general` is the one spawnable branch — the spawning discipline lives there and nowhere else, so users who want a less constricted experience change one file or add their own. `plan` keeps its own spawning ability for interactive `/agent` use but is not itself spawnable.
629
+
630
+ An agent can also name **which** agents it may spawn, with `spawn_targets`. `plan` is the shipped case: it may spawn `explore`, `review`, `writer` and `test`, and asking it for `build` or `general` is refused with a reason rather than quietly obeyed. That is the point of planning as its own turn — you read the plan and change your mind before anything is written. Say nothing and an agent may spawn anything spawnable, which is the default every definition had before the field existed; a list only ever narrows, and narrows again for anything it spawns in turn.
631
+
632
+ `explore`, `review`, `build`, `test` and `writer` are **read-only or write-only by omission**: none of them lists `spawn_subagent`, `remember` or `write_project_doc`, so no configuration makes one reachable. `build` is the exception that proves the shape — it declares `write`/`edit` because implementing means writing, while the other four simply absent them. They all list tools (`read`, `shell`) which are [denied by default](#what-needs-approval-by-default) and cannot be enabled at runtime — so on a stock install `explore` works from `read_project_doc` and the three network tools, and all become code agents only where you have enabled file access in `config.yaml`. Approving a spawn of a leaf grants nothing standing: `shell` carries a per-call gate, so it is excluded from every grant path by name and each non-inert command still asks.
633
+
634
+ Fourteen skills ship, under `security/`, `crypto/`, `math/`, `research/` and `software/` — methodologies for reviewing code, debugging, designing tests, designing experiments, statistical inference, reproducibility, evaluating sources, technical writing, numerical methods, formal specification, literature review, proof writing, cryptography verification and cybersecurity research.
635
+
636
+ #### Writing your own
637
+
638
+ Drop `.md` files into `~/.config/venastine/agents/` or `.../skills/` for yours, or into the project's `.venastine/agents/` once trusted. Skills may also sit in category folders — the folder is grouping metadata; the name stays global. Same-name collisions resolve harness > user > project, and a harness name can never be shadowed at all.
639
+
640
+ Agent frontmatter fields:
641
+
642
+ | Field | Type | Default | Meaning |
643
+ |---|---|---|---|
644
+ | `name` | string | *required* | Catalog identity, global across tiers |
645
+ | `description` | string | `""` | One line into every system prompt — collapsed to a single line and capped at 300 characters (see below) |
646
+ | `model`, `provider` | string | inherit session | Pin this agent's own model/provider; `/model` tells you when one is active |
647
+ | `allowed_tools` | list | everything allowed | A whitelist that only ever narrows — nothing can widen it |
648
+ | `approval_overrides` | mapping | `{}` | Can only ever *add* prompts, never remove one |
649
+ | `use_project_context` | bool | `false` | Inject the project's root `AGENTS.md` into the system prompt |
650
+ | `use_memory` | bool | `true` | Inject durable memories (plain chat counts as opted in) |
651
+ | `max_steps` | int ≥ 1 | caller's ceiling | **Replaces** the caller's ceiling rather than narrowing it — a value above `MAX_ITERATIONS` raises it, making this the one frontmatter field that can widen anything; an invalid value is repaired to the default with a warning naming what it read |
652
+ | `spawnable` | bool | `false` for your files | Whether `spawn_subagent` may feed this agent |
653
+
654
+ Skill frontmatter fields: `name` (required), `description`, and `additional_tools` — a list of tool names stating what the skill's methodology *depends on*. It grants nothing: activation proceeds and tells you what is missing under the current agent.
655
+
656
+ ### A description is text, and the prompt treats it as one line
657
+
658
+ An agent's or a skill's `name` and `description` go straight into the system prompt, so they are collapsed to a single line and capped at 300 characters when the file is read. Without that, a description written as a multi-line YAML block escapes its bullet and renders as a section of the prompt in its own right — indistinguishable from one this harness wrote. The cap is generous next to real ones: the longest description shipped here is 171 characters.
659
+
660
+ ### MCP servers
661
+
662
+ Configured in `mcp.json`, at `~/.config/venastine/mcp.json` or `.venastine/mcp.json`. **The user-level one is created empty on startup if it is absent**, and the launch says where it is — two plausible homes and no way to tell from inside a session meant an edit could land in a file the harness never reads. `/init --config` creates an empty project one to fill in. Claude Code compatible, and unrecognised keys are ignored so a config shared with another client works as-is:
663
+
664
+ ```json
665
+ {"mcpServers": {"files": {"command": "npx", "args": ["-y", "@example/server"]}}}
666
+ ```
667
+
668
+ Tools are namespaced `mcp__<server>__<tool>`. A server that fails to connect is named and skipped, never fatal.
669
+
670
+ Per-server entry fields:
671
+
672
+ | Field | Transports | Meaning |
673
+ |---|---|---|
674
+ | `command`, `args` | stdio | Spawn this local process |
675
+ | `env`, `cwd` | stdio | Extra environment variables; working directory |
676
+ | `url` | http, sse | Remote endpoint |
677
+ | `type` | http, sse | `"sse"` selects Server-Sent Events; a bare `url` without `type` is always streamable HTTP |
678
+ | `headers` | http, sse | Extra HTTP headers — `Authorization` is where a hosted server's credential usually rides |
679
+ | `autoApprove` (or `auto_approve`) | both | Skip per-call approval for this server's tools. Must be a real JSON boolean — the string `"false"` warns and stays gated |
680
+ | `disabled` | both | Load nothing from this entry |
681
+
682
+ The first connection to a **user-level** server asks once, showing the resolved command line or URL, whether it auto-approves, and the *names* of its env vars and headers — never their values. The acknowledgement is keyed to the entry's contents, so editing a server later re-asks; project-level servers ride the workspace trust prompt instead. Set `VENASTINE_MCP_ACK_FULL=1` to append the raw JSON entry to that prompt, for audits.
683
+
684
+ ### The TUI
685
+
686
+ Type `@` in a chat message to complete a file or folder from the project directory. Match by
687
+ filename or relative path, use arrows to choose and Tab or Enter to insert. Names with spaces
688
+ are quoted, such as `@"docs/my notes.md"`. A mention tells the agent what to inspect; it does
689
+ not attach file contents. Normal file-access permissions still apply.
690
+
691
+ The path list loads in the background at startup. Files created by the agent's `write` tool
692
+ refresh it automatically; files you create yourself appear after restart. Ignored paths are
693
+ hidden by default; `/mentions ignored on` includes them for this session, and `/mentions`
694
+ shows the source and any limits. Git is optional: without a usable repository/binary, a
695
+ fallback skips common build/cache directories. The panel labels that fallback. Up to 50,000
696
+ paths are cached and 200 matches offered; narrow the query when a limit is shown.
697
+
698
+ | Command | What it does |
699
+ |---|---|
700
+ | `/help` | List every registered command with its usage |
701
+ | `/theme [name]` | Restyle panels, transcript roles and code blocks — not just borders. Bare shows the current theme and all fourteen names. **Remembered for the next launch**, unless `tui.theme` in settings.json has changed since |
702
+ | `/effort [level\|auto]` | Switch reasoning effort, offering only levels this model accepts (Anthropic's are queried live). Session-only (`tui.effort` persists) |
703
+ | `/thinking [on\|off]` | Show or hide reasoning inline for this session. Session-only (`tui.show_thinking` persists) |
704
+ | `/model [[PROVIDER] name]` | Switch provider and/or model, and it is remembered for the next launch. Refuses mid-turn, warns on a missing key, revalidates effort against the new model, and notes if an active agent pins its own |
705
+ | `/critic [[PROVIDER] name\|off]` | Route the grounding and critic passes (3a, 3b, 6b) to a different model than the generator, so it is not checking its own output for errors. Remembered across launches; not cleared by `/model`, since being a different model is the point. Bare reports what is in force and where it came from |
706
+ | `/embedder [[PROVIDER] name\|off]` | Choose the embedding model that scores how close each source is to the claim it was cited for. The selection is **probed** — one embedding call checks the provider, the slug and the key, and reports the dimension — and only what worked is remembered. Without one, similarity stays the grounding model's own estimate and every run says so |
707
+ | `/submodel [[PROVIDER] name\|off]` | Run spawned subagents on a different model than the session's, so a cheap child need not run on its parent's expensive model. An agent whose own file names a model or a provider keeps its pin, and the compactor, the pipeline reviewer and `/init`'s initializer keep the session model; the command names what it does not reach. Remembered across launches, never in settings.json, and named in the header while set. Also in the CLI |
708
+ | `/research [--attended] [--review\|--no-review] [--grant[=a,b]] <query>` | Run the pipeline live from the TUI. Leading flags compose in any order before the query; bare `--grant` opens the picker, `--grant=a,b` names them (`--grant-tools=` works as an alias); without flags, `research.*` settings apply |
709
+ | `/compact [--strength 1-5]` | Fold older turns now instead of waiting for the trigger. Recent turns keep exactly the protection an automatic compaction gives them |
710
+ | `/trigger [tokens\|off]` | Override **when this chat compacts**, for this session only. An absolute prompt size (`80k`), not a margin below the window. A value below the warning margin or the keep-recent floor is refused naming it; a value below the thread's current size is accepted and says a fold is coming |
711
+ | `/window [tokens\|off]` | Set this model's **context window** and remember it, per `(provider, model)` and across launches. It outranks both the provider's own answer and the built-in table, and it moves everything derived from the window: the chat compaction trigger, the research-pass backstop and the summarizer's input budget. Above what the provider reports it warns rather than refusing, because raising it is the point — a gateway or a self-hosted endpoint can report its own default rather than your deployment's |
712
+ | `/network` | What each network meter has used against its ceiling over the rolling window, which part is an estimate, and when room returns. Every ceiling is off until you set one in `config.yaml`; see [Budgets and stop conditions](#budgets-and-stop-conditions) |
713
+ | `/config [key] [value]` | Browse and set the harness's own settings without leaving the session. Typing `/config ` lists all 133 of them in the same panel the slash commands use, with the values each one takes and the value in the file; completing a key then offers that key's values. A value you have already changed reads `pending restart` until you relaunch, and bare `/config` lists every one of them, old to new — so several settings can be changed in a row and applied together. Bare `/config <key>` explains one, including what outranks it — an environment variable, a `settings.json` key — and containers are listed but edited in the file. A write goes through the whole document's validation first, keeps every comment in `config.yaml`, and offers to relaunch, because values are read once at startup. The nine AUTHORITY keys ask first, naming what the key permits |
714
+ | `/claims [run id]` | Open the claims view — tier, grounding status, assumption flags, score breakdown per claim — during a run or afterwards (**ctrl+l**) |
715
+ | `/copy [last\|report\|claims\|conversation\|all] [--file <path>]` | Copy out of the session. Defaults to the last response; `conversation` is the exchange alone — your turns, the answers, the reasoning, the tool calls and the diffs; `all` is everything on screen (the harness's own lines included) plus report plus claims. Clipboard delivery cannot be confirmed, so `--file <path>` is the route that provably worked |
716
+ | `/threads` | Conversations-only picker — research runs' internal threads excluded — most recently active first, capped at 200 with a notice (**ctrl+t**) |
717
+ | `/resume <thread-id>` | Open any thread by id, however old |
718
+ | `/new` | Start a fresh thread; created lazily on your next message, so `/new` twice leaves nothing behind |
719
+ | `/kill [session-id]` | Stop a background session. Bare, it opens the picker **ctrl+b** opens; with an id it stops that one. Deliberately usable *while* sessions are blocking the prompt — it is the way out of that block, so it is the one command that never refuses for being busy |
720
+ | `/agent [name\|default]` | Make an agent active for subsequent turns; `default` clears. Active skills are re-checked against the new agent's tool policy |
721
+ | `/goal [text\|clear]` | Persistent objective for this thread — injected into every turn in either shell, mirrored in a banner |
722
+ | `/grill-me` | One turn under the grill-me agent inside the current thread, reading the live history rather than a digest of it |
723
+ | `/skill [name\|off <name>\|clear]` | Activate a skill — its full body pins into every subsequent turn until deactivated — report tools it needs but can't have, or deactivate one/all |
724
+ | `/memories` | List durable memories visible from here, with ids for `/forget` |
725
+ | `/forget [id]` | Alone, pick the memories to delete from a list, then confirm; with an id, delete that one at once — never by substring. The CLI needs the id |
726
+ | `/summary` | Distil this conversation and show it. Describes; does **not** fold — that is `/compact` |
727
+ | `/ref [--list\|--clear]` | Pick another conversation and attach its summary to this one as standing context; `--list` and `--clear` manage attachments |
728
+ | `/init [--software\|--research] [--config]` | Scaffold the project documentation set; `--config` adds `.venastine/settings.json` and `mcp.json` with default values, and on its own is the whole command |
729
+ | `/mentions [ignored on\|off]` | Show file mention status or include ignored paths for this session |
730
+ | `/quit` | Leave the harness, on one invocation — a typed command is already deliberate. `/exit` and `/bye` are the same command under other names; type toward either and the suggestion list says so |
731
+
732
+ Keys: **ctrl+c** twice quits — the first press arms it and the footer changes to say so, and it goes back to `Quit` after a couple of seconds; a **ctrl+c** over selected text copies instead and arms nothing, so nothing you copy can end the session. **ctrl+q** quits on a single press, from anywhere, including under a dialog · **ctrl+t** thread picker · **ctrl+l** claims view · **ctrl+j** (or **shift+enter**) newline in the prompt · **shift+tab** in the prompt switches to the next agent in `config.yaml`'s `agent_cycle` (default → plan → build as shipped) · **up/down** and **enter**/**tab** to pick a slash command, **escape** to dismiss the list · **ctrl+click** a URL in an answer — or in a tool line — to open it, or the name on a `spawn_subagent` line to read what that agent did, or the name on a `shell_background`, `shell_monitor` or `shell_interactive` line to read that session -- its command, why it was started, what it printed, and what became of it. A session the harness no longer holds (it aged out, or you restarted) opens the same way and shows what the agent was given, saying so; a live one refreshes as it writes. While sessions are running the sidebar lists them, and clicking a row opens it; **ctrl+g** lists the runs going on right now and opens one from the keyboard · **ctrl+b** stops a background session, and always asks which one rather than killing on a single press. While background sessions are running the prompt and most commands are refused — `ctrl+b`, `/kill`, answering a dialog and quitting stay usable, because they are the ways out.
733
+
734
+ Answers are rendered rather than printed as their source: tables become grids, headings and `**bold**` take weight, `*emphasis*` and `~~strike~~` take their own marks, code fences are highlighted, and a list item that runs past the edge wraps **under its own text** instead of back to the margin. A line indented four spaces or more is left exactly as written, so a code sample keeps its operators and its `#` comments. What is deliberately not rendered: block quotes, horizontal rules, heading *levels* (a `#` and a `######` look the same), and anything at all inside a reasoning block. `/copy` always hands back the markdown the model wrote — the rendering is what the screen does, never what is stored.
735
+
736
+ **A link can never hide where it goes.** `[the docs](https://example.com)` draws every character it was written with, and the only clickable thing on the row is the URL itself — so a model cannot present one destination and open another. Ctrl+click opens it, in `http`/`https` only, and only when the URL is plain ASCII: a lookalike address built from non-Latin characters still renders and still copies, but will not open on a click. Nor will an address that carries a username before its host — `https://accounts.google.com@else.example/x` goes to `else.example`, so the part you read as the destination has to *be* the destination — and nor will one the harness rewrote to hide a secret in it. The same is true of the `▸ fetch_url https://…` line: where that line shortens a long address, the click still opens the whole one, and the part shown always reaches the end of the site name, so what you can read is where you will land.
737
+
738
+ The prompt box wraps and grows to four lines as you type, then drops back to one when you send, so a long question can be read back before it goes. A line that runs past the edge wraps on its own — `ctrl+j` is for a break you actually want. `shift+enter` does the same where your terminal can send it, which in practice means kitty, ghostty, WezTerm, or any terminal configured to emit a newline for that chord; elsewhere it arrives as a plain Enter and sends the message, so `ctrl+j` is the one to reach for.
739
+
740
+ Type `/` and the commands appear above the prompt — name, description and flags, narrowing as you type and coming back if you delete. Arrow up and down to move the highlight — the list scrolls, so every matching command is reachable, not just the ones on screen; **enter** or **tab** fills the command in **without sending it**, so you can still add arguments, and a second **enter** runs it. **escape** puts the list away. The list is the same one `/help` prints, so nothing can go stale, and the panel's title says how many of the matches fit on screen.
741
+
742
+ Three behaviours worth knowing: an unknown slash command is an error, never a chat turn — a mistyped command cannot silently burn a request. `/effort` and `/thinking` persist nothing, so make those stick through settings.json or launch flags; `/theme`, `/model`, `/critic` and `/embedder` are the exceptions — they are remembered for the next launch, in files of their own beside settings.json rather than by rewriting it. And the commands that spend money or swap models mid-session (`/compact`, `/summary`, `/research`, `/init`, `/model`, `/critic`, `/embedder`, `/grill-me`) refuse while a turn is still running rather than acting underneath it.
743
+
744
+ When a subagent is spawned, you are asked which of its approval-gated tools it may use without asking again — per tool, all unticked by default. Running it with none selected is fine, and refusing the spawn entirely is a separate answer from granting it nothing. Before this, approving a spawn authorised the child's whole set.
745
+
746
+ `/init` reads the project and writes its documentation set. A root `AGENTS.md` is the hub — the short, factual description this harness injects into every agent that opts into project context, and the filename other agent harnesses look for too — and it links out to the documents that hold the detail: `ARCHITECTURE`, `ROADMAP`, `DEVLOG`, `TECHNICAL_DEBT`, `DOCUMENTATION_STANDARDS`, `TEST_WRITING` and `BREAKING_CHANGES` for a codebase, or `RESEARCH_QUESTIONS`, `METHODOLOGY`, `SOURCES`, `FINDINGS`, `LIMITATIONS`, `EXPERIMENT_LOG` and `OPEN_QUESTIONS` for written work. It asks which kind you have — proposing an answer when there is something to go on, and asking outright when the folder is empty.
747
+
748
+ Only `AGENTS.md` is written for you in full; the rest arrive as skeletons with real headings and a note in each saying what belongs in it and what does not. That is deliberate: a DEVLOG invented for a project with no history is fiction in a file that then gets committed and read as fact. Documents you already have are never touched, and regeneration revises your `AGENTS.md` rather than replacing it — you see a diff and approve it before anything is written. Everything `/init` writes is an ordinary committed file at the project root, so a repository shared without its `.venastine/` configuration is still a repository whose documentation makes sense. From the CLI it is `--init`, with `--software-project` / `--research-project` to skip the question.
749
+
750
+ `/init --config` is the other half, and it is independent of the two above: it writes `.venastine/settings.json` and `.venastine/mcp.json`, and creates `.venastine/agents/` and `.venastine/skills/`. On its own it makes **no model call** and costs nothing — no document set, no question about which kind of project this is; combined (`/init --software --config`) it does both under one confirmation. An existing `settings.json` or `mcp.json` is never touched, per file, so a project with one and not the other gets the other. From the CLI it is `--init --project-config`.
751
+
752
+ The settings file it writes is **every key with a shipped default, at that default** — because the file cannot explain itself. An unknown key raises at startup, so there is no comment syntax, no `$schema` line and no way to leave a key in the file but switched off; the scaffold is the schema. Six keys are deliberately left out, because something reads them by *presence* rather than by value, so writing their own default would decide rather than restate: `default_provider` and `default_model` (adding either discards a model you picked with `/model` in that project), `effort` (makes every launch probe the provider's effort table), `compaction.trigger_tokens` (disables the window-derived trigger, invisibly), `ensemble_mode` and `research.subagent_review` (both defer to `config.yaml` only while absent). Set any of those by hand and they work normally. Everything the scaffold does write changes nothing until you edit it — and because a project's `settings.json` beats yours by *presence*, the command tells you which of your own keys the new file has taken over before it asks to write it.
753
+
754
+ `/summary` distils this conversation and shows it — it does **not** shorten what the model sees; that is `/compact`. `/ref` picks another conversation, summarises it, and attaches that summary to this one as standing context: you choose what crosses between threads, so nothing read or argued in one conversation can steer another without your say-so. `/ref --list` and `/ref --clear` are the way back out, and the summaries are labelled so the model knows they are not part of this conversation. From the CLI the same two are launch flags: `--summary <thread>` and a repeatable `--ref <thread>`.
755
+
756
+ `/threads` lists your **conversations** — not the ~15 internal threads each research run creates, nor the one every automatic compaction makes — ordered by last activity, so the conversation you were just in stays on top. Each row leads with its first message so you can tell them apart. The list shows the 200 most recently active and says so when it truncates; `/resume <thread-id>` opens any thread by id, however old, and `/new` starts fresh, redrawing the window rather than leaving the previous conversation on screen beneath it. A run's own pass threads are recorded with the run (`output/<run_id>/pass_threads.json`) and can still be opened by id with `--thread`, if you want to see how a particular pass argued.
757
+
758
+ `/model` switches provider and model, and the pair comes back at the next launch: it is saved in `~/.config/venastine/ui_preferences.json`, beside `settings.json` and never into it. Editing `default_provider` / `default_model` there still wins — the store records what the file said when you chose, so changing it (or adding it, or removing it) re-asserts the file — and `--provider` / `--model` pin one launch without disturbing what is remembered.
759
+
760
+ `/copy` exists because Textual 1.0 cannot select text at all. Clipboard delivery uses an escape sequence that some multiplexers drop silently and **cannot be confirmed**, so `--file <path>` is the route that provably worked. Shift+drag usually bypasses the mouse capture and lets your terminal select natively.
761
+
762
+ `/copy conversation` and `/copy all` are two targets on purpose. `all` is everything the session put on screen — `/help`'s output, the launch banner, `Resumed thread <uuid>.`, the replay marker — plus the research report and the claims, which is what you want when reconstructing what happened. `conversation` is the exchange with none of that.
763
+
764
+ ### The CLI reads stdin exactly once
765
+
766
+ Chat mode, the approval prompts, the trust prompt, `--init` and the MCP acknowledgement all read
767
+ through **one** object. That sounds like an implementation detail and is not: before it, an approval
768
+ prompt started a background reader that never stopped, so from the first gated tool call onwards
769
+ chat's own `input()` lost every line to it and blocked forever — silently, and looking exactly like
770
+ the model thinking. Recovery was Ctrl+C and `--thread <id>`.
771
+
772
+ Two disciplines, because the two kinds of prompt want opposite things:
773
+
774
+ | | drains stale input | deadline |
775
+ |---|---|---|
776
+ | the gated prompts — approvals, sign-offs, questions, review | **yes** | from the channel |
777
+ | the chat prompt and the startup prompts | no | none |
778
+
779
+ The drain is a safety rule: a line typed after a question timed out was answering *that* question,
780
+ and letting it fall through would approve the next call on the strength of it. The chat prompt must
781
+ *not* drain, for the mirror-image reason — a line typed while the model was still streaming is an
782
+ answer to the prompt about to appear, and the terminal has been buffering it for you.
783
+
784
+ **A deadline belongs to a run, not to a question.** An approval asked during an attended research run
785
+ expires after `ATTENDED_APPROVAL_TIMEOUT_S` (600s) and denies that call, because there is a run
786
+ waiting on the answer and it has to keep moving. `--init`'s prompts have no run behind them, so they
787
+ wait as long as you need — and they do not print a `(600s)` they would not honour.
788
+
789
+ `--help` and a mistyped flag now do nothing at all. They used to create a 77 KB six-table SQLite
790
+ database and a log directory in whichever directory you ran them from, before argparse had seen a
791
+ single flag.
792
+
793
+ `--review` and `--no-review` in chat mode are refused rather than ignored, matching
794
+ `--grant`/`--grant-tools`/`--attended`. Inside the TUI, use `/research --review <query>`.
795
+
796
+ ### CLI flag reference
797
+
798
+ Everything `python main.py` accepts. Wherever a value can come from more than one place, precedence is explicit flag > `settings.json` > built-in default.
799
+
800
+ | Argument | Effect |
801
+ |---|---|
802
+ | `query` (positional) | Research mode: the question the pipeline runs on — required there. Chat mode: sent as the first message, then the interactive loop continues |
803
+
804
+ | Flag | Effect |
805
+ |---|---|
806
+ | `--thread UUID` | Resume a stored conversation; what you said replays so you can see what you are picking up |
807
+ | `--mode chat\|research` | Which loop to run. Chat is the default |
808
+ | `--tui` | Launch the full-screen interface instead of the line-based CLI |
809
+ | `--provider NAME` | Any entry from `providers.json` — `ANTHROPIC`, `OPENAI`, or an OpenAI-compatible endpoint you added |
810
+ | `--model NAME` | Model id as the provider knows it |
811
+ | `--effort LEVEL` | Reasoning effort for chat *and* research — typically `low`, `medium`, `high`; `xhigh`/`max` on models that offer them; `auto` sends no effort parameter at all. See [Reasoning effort](#reasoning-effort) below |
812
+ | `--grant` | Research only. Pick approval-gated tools to pre-authorise, interactively — needs a terminal; a piped run prints the candidates instead. Empty unless an MCP server offers grantable tools |
813
+ | `--grant-tools NAMES` | Research only. Same as `--grant`, but takes an explicit comma-separated list of tool names and works without a terminal |
814
+ | `--attended` | Research only. Ask about every gated call as it happens; 600s with no answer denies that call and the run continues. Composes with grants — granted tools aren't asked about, everything else is |
815
+ | `--review` / `--no-review` | Research only. Post-pipeline review on/off for this run; `--no-review` is the escape from a persisted setting |
816
+ | `--memories` | List durable memories visible from this directory — id, scope, content — and exit |
817
+ | `--forget ID` | Delete one memory by id — never by substring — and exit |
818
+ | `--summary [THREAD]` | Print one thread's distilled summary and exit; falls back to `--thread`. A summary still current costs no model call — staleness is detected, not assumed |
819
+ | `--ref THREAD` | Attach another thread's summary to this session at launch. Repeatable up to three; past the cap the extra reference is refused and named, not silently dropped |
820
+ | `--trust-project` | Grant workspace trust non-interactively for scripts/CI, printing what it trusts as it does so |
821
+ | `--init` | Generate this project's documentation set and exit. On a pipe there is no consent route, so it reports what it would write and writes nothing |
822
+ | `--software-project` / `--research-project` | With `--init`: choose the document set without asking. At most one of the two |
823
+ | `--project-config` | With `--init`: create `.venastine/settings.json` and `mcp.json` with default values, plus `agents/` and `skills/`. Without a document-set flag it is the whole command and makes no model call. Refused without `--init`, rather than ignored |
824
+
825
+ **Combinations the parser refuses** (rather than ignoring):
826
+
827
+ - `--mode research` without a positional query.
828
+ - `--tui` with `--mode research` — use `/research` inside the TUI.
829
+ - `--tui` with a positional query — start the TUI and type.
830
+ - Any of `--grant`, `--grant-tools`, `--attended`, `--review`, `--no-review` outside research mode, including under `--tui`.
831
+ - Both kind flags with `--init`.
832
+
833
+ **Scripting notes.** Startup prompts degrade instead of hanging when stdin is not a terminal: project content is skipped with a notice unless `--trust-project`, newly seen user-level MCP servers are skipped and named, the grant picker prints its candidates instead of asking, the review records findings but applies nothing, and chat-mode approvals do not exist — gated tools stay hidden entirely. Exit codes: `0` success; `1` operational failure (a failed pipeline, a bad memory id, nothing to summarise); `2` argparse misuse. `--help` and a mistyped flag touch nothing at all — no database, no log directory.
834
+
835
+ ### Reasoning effort
836
+
837
+ Effort asks a reasoning model how long to think before answering. It rides every chat turn, every research pass, every JSON-retry correction, the reviewer and its re-synthesis — a retry is the same pass continuing, so it inherits the level rather than dropping it.
838
+
839
+ Where a level comes from, in order: `--effort` > top-level `effort` in `settings.json` > `config.DEFAULT_EFFORT` (shipped `"high"`). Inside the TUI, `tui.effort` persists separately and wins there. `auto` is the off switch at either layer — with the default now high, `--effort auto` restores send-nothing behaviour.
840
+
841
+ A level is validated against the model that will **receive** it, not the one it was chosen for:
842
+
843
+ | Provider | Levels | Where the set comes from |
844
+ |---|---|---|
845
+ | Anthropic | `low`, `medium`, `high`, `xhigh`, `max` — whichever the model reports supported | Queried live from the Models API, so newly released Anthropic models need no entry anywhere |
846
+ | OpenAI-compatible | `low`, `medium`, `high` assumed for unknown models | Static table (`config.MODEL_EFFORT_LEVELS`). Known non-reasoning models — gpt-4o family, gpt-3.5 — ship with *empty* lists, meaning "takes no effort parameter": a requested level is dropped cleanly instead of 400ing every call. An unlisted model gets the assumption plus a WARNING naming it |
847
+ | Google | Levels map to integer thinking budgets, `low`→2,048 through `max`→dynamic | Mapped at the boundary and sent as `thinking_budget`. On since batch 172, when the `google-genai` pin moved to 2.29.0; an unlisted Gemini model gets the default level set plus a WARNING, like any other unlisted model |
848
+
849
+ **Seeing the thinking is separate from doing it.** Effort is what makes the model reason; whether the API hands those thoughts back to the client is a different question, and the answer varies by provider. Reasoning streams into the transcript on **Anthropic** and on OpenAI-compatible providers that send it — DeepSeek, Qwen, Z.AI, OpenRouter. It is absent on **OpenAI**, whose Chat Completions endpoint returns no reasoning text at all, and on **Google**, whose request deliberately does not ask for thought summaries: those would be billed as extra output for something the model produces either way. On those two the turn still thinks; you just do not see it. `tui.show_thinking` and `/thinking` control the display, never the reasoning.
850
+
851
+ A verification that *fails* — a network blip during the query — passes your level through unverified with a warning rather than silently downgrading a deliberate choice. `/effort` in the TUI offers only levels the mounted model accepts, and `/model` revalidates after a switch, since effort is per-model. An agent pinning its own provider/model wins over the session's choice for chat turns, and says so.
852
+
853
+ ### Budgets and stop conditions
854
+
855
+ There is **no default spend ceiling**. (That absence is also why compaction stopped being a flat number: the trigger was sized against a spend cap that no longer exists.) The cumulative input+output counter is a billing meter — the prompt is re-sent and re-billed on every step of a tool-using turn, so it grows quadratically in steps: correct as billing, meaningless as a size limit. A hard cap exists only if settings.json sets `max_token_budget` (billed tokens per run — one user turn, one research pass, one `/init`). Limits at the provider remain the stronger instrument: they see the same bill and cannot be forgotten by a code path.
856
+
857
+ Three things can end a turn or pass early:
858
+
859
+ | Stop reason | When |
860
+ |---|---|
861
+ | `complete` | The model answered without calling another tool |
862
+ | `max_steps_reached` | Step ceiling hit — 50 by default; an agent's own `max_steps` replaces that number, in either direction |
863
+ | `token_budget_exceeded` | Only when `max_token_budget` is configured: cumulative billed spend crossed it |
864
+
865
+ The CLI names the figures behind an early stop — billed this turn, and the thread's measured context size — rather than a bare reason, because "budget exceeded" invites exactly the misreading that there is a size problem.
866
+
867
+ Other ceilings worth knowing: the six maths tools run in killable subprocesses under a 20-second wall clock (`tool_compute_timeout_s`) and are told which tool and which limit stopped them; pre-granted tool calls cap at 150 per research run (`MAX_GRANTED_TOOL_CALLS`), degrading to asking when exhausted; subagent nesting stops at depth 2 (`SUBAGENT_MAX_DEPTH`) and at most three subagents of one turn run at once (`SUBAGENT_MAX_PARALLEL`), with anything beyond that running in waves; attended prompts expire after 600 seconds (`ATTENDED_APPROVAL_TIMEOUT_S`), denying that one call while the run continues.
868
+
869
+ Subagents spawned in one model response run **concurrently**, up to `SUBAGENT_MAX_PARALLEL`. Their answers come back to the model in the order it asked for them however they finish, one approval question reaches you at a time, and the sidebar draws them as a tree rather than a chain. The database runs in SQLite's WAL mode to keep their writes from contending, which means `app.db` is accompanied by `app.db-wal` and `app.db-shm` while the harness is open — both are gitignored, and excluded from `git archive`, because a WAL file holds recently written messages.
870
+
871
+ **Network limits are off by default.** For a metered connection, `config.yaml` can cap what the harness pulls and pushes over a rolling window, 24 hours unless you change it, with a separate ceiling in decimal megabytes for each of three kinds of traffic: the network tools, the model provider's API, and MCP servers reached over HTTP. A local Ollama or a local MCP server need not count against an allowance, so each is switched on by its own ceiling. A call that would pass its ceiling is refused with a reason that says when room returns; one already running is never cut off, so a meter can end up over by one response. Counts are kept in `~/.config/venastine/network.db`, shared by every harness process, written at most once a minute, and pruned as they leave the window. Shell commands, `stdio` MCP servers, sign-in traffic and TLS overhead are not counted, and `web_search`'s figure is an estimate (its client cannot be counted). `/network` shows the meters, and the sidebar shows them while any is on.
872
+
873
+ ### Logging
874
+
875
+ Two sinks from startup: stderr, and a rotating file — `logs/app.log` in the working directory, 1 MB per file, three backups kept. `AGENT_LOG_LEVEL` sets verbosity (a name like `INFO` or a number like `20`; anything else prints a warning naming the value and runs at `INFO`, as an unwritable `AGENT_LOG_FILE` does) and `AGENT_LOG_FILE` moves the file, creating the parent directory if needed. The file formatter redacts secret-shaped strings on the way out — the same patterns tool outputs get — because a failing tool's traceback routinely carries the request that produced it, and for an HTTP client that is a URL with the key in it.
876
+
877
+ In the TUI stderr is detached before the screen is taken (anything written there would paint over the rendered UI and vanish on the next repaint); the rotating file keeps everything, and WARNING-and-above is routed into the transcript so warnings stay visible where you are looking.
878
+
879
+ ### Configuration reference
880
+
881
+ | File | Holds | Notes |
882
+ |---|---|---|
883
+ | `providers.json` | LLM provider keys | gitignored; path movable with `AGENT_PROVIDERS_FILE` |
884
+ | `.env` | tool API keys | gitignored |
885
+ | `settings.json` | defaults and modes | unknown keys **raise**; user copy at `~/.config/venastine/settings.json`, project copy at `.venastine/settings.json` (loaded only when trusted). `/init --config` writes a project copy with every defaulted key in it |
886
+ | `mcp.json` | MCP servers | unknown keys ignored; same two locations. `/init --config` writes an empty project copy |
887
+ | `trusted_projects.json` | workspace-trust store | user-level (`~/.config/venastine/`); written by the trust prompt or `--trust-project`, keyed to resolved path + content hash |
888
+ | `AGENTS.md` | project context for the model | project root; covered by workspace trust |
889
+
890
+ Precedence for provider and model is CLI flag > `settings.json` > `config.yaml`. Two different merge orders, deliberately:
891
+
892
+ - **Inside `settings.json`, project beats user** — this is the one file where "more specific wins" holds, which is exactly why the five authority-bearing keys below are rejected there by name. Nested objects merge key-by-key across tiers.
893
+ - **MCP servers, agents and skills run harness > user > project**, inverted from the usual rule, because there "more specific" means "arrived with a repository you cloned".
894
+
895
+ #### Every `settings.json` key
896
+
897
+ An unknown key raises at startup, naming the file and the key — a typo must never read as a setting. `/init --config` writes a project `settings.json` containing every key below that has a shipped default, at that default, so you can edit rather than transcribe.
898
+
899
+ | Key | Type | Default | Meaning |
900
+ |---|---|---|---|
901
+ | `default_provider` | string | `"ANTHROPIC"` | Used unless `--provider` overrides |
902
+ | `default_model` | string | `claude-sonnet-5` | Used unless `--model` overrides |
903
+ | `effort` | string | `"high"` | Reasoning effort for chat and research; `"auto"` clears even this. See [Reasoning effort](#reasoning-effort) |
904
+ | `max_token_budget` | int \| null | null — uncapped | Per-run billed-spend ceiling. See [Budgets and stop conditions](#budgets-and-stop-conditions) |
905
+ | `ensemble_mode` | bool | `false` | Master switch for ensemble Pass 1; the roster lives in `config.yaml` |
906
+ | `ensemble_n` | int | — | Accepted with a warning; vestigial — the count now derives from the roster |
907
+ | `compaction` | object | — | Seven keys tabulated in [the compaction section](#long-conversations-condense-themselves) above |
908
+ | `tui.theme` | string | — | One of the fourteen theme names; validated at use and falls back rather than blocking startup. Outranked by a theme you picked with `/theme` — until you change this value, which re-asserts it |
909
+ | `tui.animations` | bool | `true` | Master switch for the raven and transitions |
910
+ | `tui.effort` | string | — | Persisted TUI effort level; beats top-level `effort` inside the TUI |
911
+ | `tui.todo_position` | string | — | `top`, `bottom` or `side`; validated at load |
912
+ | `tui.show_thinking` | bool | `true` | Render a turn's reasoning inline in the transcript. Off collapses it to an animated `thinking…` line. Absent on providers that return no reasoning — see below |
913
+ | `research.approval_mode` | string | `"none"` | `"attended"` makes research runs ask about every gated call, as if launched with `--attended` |
914
+ | `research.subagent_review` | bool | `false` | Review on by default, as if launched with `--review`; escaped per run with `--no-review` |
915
+
916
+ Five keys are rejected **by name** — well-formed shapes that will never load, because a project tier that could set them would decide what runs without being asked:
917
+
918
+ | Rejected key | Why |
919
+ |---|---|
920
+ | `shell_approval_mode` | Decides whether shell commands are asked about at all; set `shell_approval_mode` in `config.yaml` instead |
921
+ | `ensemble_models` | A roster chooses which providers N research passes call, so a cloned repository could point them at endpoints you never configured and multiply the run's cost by the length of its list; set `ensemble_models` in `config.yaml` instead |
922
+ | `critic_model` | Names a provider every claim is sent to; use `/critic`, which writes a user-tier store, or set `critic_model` in `config.yaml` |
923
+ | `embedder_model` | Names a provider sent claim text and the text of every page a run fetched; use `/embedder`, or set `embedder_model` in `config.yaml` |
924
+ | `research.granted_tools` | A persisted grant list could only ever *remove* prompts — standing authorisation carried by any repo you clone. Grants are per-run flags precisely so they cannot be |
925
+
926
+ #### `config.yaml`-only settings
927
+
928
+ Deliberately not settings.json keys: editing these means editing the harness's own file, which has exactly one location and no override variable, so nothing a cloned repository carries can reach them. `CONFIG_ARCHITECTURE.md` carries the argument for each.
929
+
930
+ | Key | Default | Controls |
931
+ |---|---|---|
932
+ | `critic_model` | `null` | Routes passes 3a/3b/6c to a different `{provider_name, model}` |
933
+ | `ensemble_models` (with `ensemble_mode`) | `null` (off) | Pass-1 roster; fewer than two distinct pairs is refused |
934
+ | `default_effort` | `high` | Effort when neither flag nor settings speaks |
935
+ | `model_effort_levels` | see file | Per-model level lists for non-Anthropic providers; an entry mapped to an *empty* list means "takes no effort parameter" and drops the level cleanly |
936
+ | `google_thinking_budgets` | low→2,048 … max→dynamic | Google level→thinking-token map |
937
+ | `models_rejecting_sampling_params` | current Anthropic models, and the two Gemini models that ignore them | The Anthropic models 400 on temperature/top_p/top_k and the Gemini ones ignore them; such parameters are dropped with a WARNING rather than sent. OpenAI's reasoning models are handled by effort, not by this list |
938
+ | `model_context_windows` / `default_context_window` | 256k fallback | The **fallback** for the window, not the only source: Anthropic and Google report it on their model endpoints, and the OpenAI-compatible providers that carry it (Groq, Mistral, Together, OpenRouter) are read through one alias sniff. This table answers for the ones that report nothing (OpenAI, DeepSeek, Perplexity). Feeds the research-pass compaction backstop **and** the summarizer's one-call input budget; an unknown model warns once and assumes the default. Keys are stored normalized — no date suffix, no `vendor/` prefix |
939
+ | `shell_approval_mode` | `tiered` | The shell gate: `always` / `tiered` / `never`; a bad value raises at import. Rejected in settings.json by name, see above |
940
+ | `network_allowed_commands` | pip, curl, git, npm, … | Binaries granted network access inside the sandbox. Matched against **every** word of a command that needs a sandbox, so `cd x && pip install .` is recognised and asked about — and against the **first word only** of an inert one, which cannot chain, so `grep pip notes.txt` still runs unprompted. This list is a *lexical* test, so since ROADMAP_v3 §50 the agent can also declare `requires_network: true` on `shell`, `shell_background`, `shell_monitor` and `shell_interactive` for anything the word list cannot see — an inline script that opens a socket, say. The declaration only ever ADDS network access, and the command is then asked about wherever your approval mode would allow a prompt |
941
+ | `inert_commands` | ls, cat, grep, wc, … | Read-only commands eligible to run unprompted under `tiered` — as a plain argument list in the container, or on the host only when no container runtime is available |
942
+ | Sandbox bounds | image `docker.io/library/python:3.13-slim`; 120 s, 2048 MB, 1 CPU core, 200 pids — under Docker, or Podman when Docker cannot run the sandbox. The container's CPU control is a RATE (`--cpus 1`), so `sandbox_cpu_seconds` (30 CPU-s) is a budget the weak fallback enforces instead, and on Unix only | `sandbox_docker_image`, `sandbox_timeout_seconds`, `sandbox_memory_mb`, `sandbox_cpu_seconds`, `sandbox_max_pids` |
943
+ | Background sessions | 3600 s cap; 4 live; 10 consecutive wakes; first 10,000 + last 190,000 characters of output kept, in memory only | `shell_session_timeout_cap_s`, `shell_session_max_live`, `shell_session_max_consecutive_wakes`, `shell_session_output_head_chars`, `shell_session_output_tail_chars` |
944
+ | `allow_insecure_sandbox_fallback` / `auto_approve_sandbox_fallback` | `false` / `false` | Enable, then de-prompt, the weak host-subprocess fallback |
945
+ | `allow_wsl_backend` / `wsl_distro` | `false` / `''` | Let the agent ask for a command to run in WSL, and which distribution. WSL is not a sandbox — see below |
946
+ | `allow_ssh_backend` / `ssh_*` | `false` / `''` | Let the agent ask for a command to run on one configured remote host. Nothing runs there unasked; the host key is pinned and auth is key-or-agent only — see below |
947
+ | `redact_tool_outputs` | `true` | Master switch for output redaction. Never affects input refusals, the depth-cap bound, or the log formatter's own guard |
948
+ | `tool_compute_timeout_s` | 20 | Wall clock per maths-tool subprocess |
949
+ | `max_granted_tool_calls` | 150 | Pre-granted calls per research run before it must ask again |
950
+ | `attended_approval_timeout_s` | 600 | Attended prompt deadline; expiry denies that call while the run continues |
951
+ | `subagent_review` | `false` | Shipped default for the post-pipeline review |
952
+ | `max_review_findings` / `max_review_refinements` | 25 / 3 | Consent-fatigue caps on the review stage |
953
+ | `max_pipeline_retries` / `max_json_retries` | 2 / 2 | Revise/re-validate rounds per claim; corrective attempts per malformed pass payload |
954
+ | `max_iterations` | 50 | Step ceiling for a turn or pass absent an agent's own `max_steps` |
955
+ | `subagent_max_depth` | 2 | `spawn_subagent` nesting limit |
956
+ | `subagent_max_parallel` | 3 | How many subagents of one model response run at once; 1 makes them sequential again |
957
+ | `pin_max_trigger_fraction` | 0.5 | Largest share of the trigger one pin may protect |
958
+ | `compaction_trigger_fraction` | 0.90 | Share of the context window a thread may fill before it folds. Applied to the HEADROOM, which is clamped by the two keys below — so it is exact at 160k and up, and a floor beneath that |
959
+ | `compaction_min_headroom_tokens` / `compaction_max_headroom_fraction` | 16,000 / 0.25 | Floor and cap on the room left between the trigger and the window. Nothing recovers from a prompt that overflows the window, and one capped read is 12,500 tokens, so a 64k model keeps 16,000 rather than the 6,553 a bare share leaves |
960
+ | `max_injected_memories` / `max_injected_refs` / `max_todo_items` | 50 / 3 / 50 | Prompt-injection caps; refs and todos refuse past the cap rather than trimming silently |
961
+ | `summary_target_chars` | 2000 | Size cap on whole-thread summaries injected via `/ref` |
962
+ | `max_catalog_text_chars` | 300 | Cap on an agent/skill `name` + `description` entering system prompts |
963
+ | `init_read_chars` / `init_max_steps` | 20,000 / 12 | `/init` per-read volume; step-ceiling fallback (the initializer agent's own frontmatter sets 12, which wins) |
964
+ | `init_max_hub_chars` / `init_diff_shown_lines` | 1,000,000 / 2,000 | Largest existing `AGENTS.md` `/init` revises (above it, it stops before any model call); most diff lines it prints before asking |
965
+ | `teardown_budget_s` | 10 | Shared wall clock for MCP shutdown; stragglers are named in a WARNING |
966
+
967
+ #### Environment variables
968
+
969
+ | Variable | Default | Controls |
970
+ |---|---|---|
971
+ | `AGENT_MODEL` | `claude-sonnet-5` | Built-in default model (`config.MODEL_NAME`) — still loses to settings.json and `--model` |
972
+ | `AGENT_PROVIDERS_FILE` | `providers.json` | Credential-file location |
973
+ | `APP_DB_PATH` | `app.db` | SQLite database path |
974
+ | `AGENT_OUTPUT_DIR` | `./output` | Research artifacts root |
975
+ | `AGENT_WORKSPACE` | `./workspace` | File-tools and sandbox workspace root. **When you set it, it is also the project**: workspace trust, `.venastine/`, `/init`'s destination, `output/` and project-scoped memories all follow it rather than the directory you launched from. Unset, the project is the launch directory — and launching from the harness's own install tree is refused (exit 2), because that would make the harness its own project. The `workspace_dir` key in `config.yaml` sets the workspace but **not** the project on its own -- the rule is the presence of this variable, never its value -- so the file's way of saying it is the `workspace_is_project` key beside it |
976
+ | `AGENT_SHELL` | auto-detect | Host shell binary for the `shell` tool |
977
+ | `AGENT_SANDBOX_IMAGE` | `docker.io/library/python:3.13-slim` | Sandbox container image, under Docker or Podman |
978
+ | `AGENT_LOG_LEVEL` | `INFO` | Log verbosity — name or numeric level |
979
+ | `AGENT_LOG_FILE` | `logs/app.log` | Rotating log location |
980
+ | `VENASTINE_REDACT_OFF` | unset | Truthy value disables tool-output pattern redaction for one run. The environment can only ever weaken redaction, never restore it past the constant — and input refusals, the depth-cap bound and the log formatter's guard stay on regardless |
981
+ | `VENASTINE_MCP_ACK_FULL` | unset | `=1` appends the raw mcp.json entry to a server's acknowledgement prompt |
982
+
983
+ #### `providers.json` entries
984
+
985
+ | Field | Meaning |
986
+ |---|---|
987
+ | `API_URL` | Endpoint base URL; empty for ANTHROPIC and GOOGLE, which use their SDKs' defaults |
988
+ | `API_KEY` | The credential, stored directly |
989
+ | `is_v1_compatible` | `true` routes the provider through the OpenAI-compatible translation |
990
+ | `supports_stream_usage` | Promises streamed responses carry token usage. If a stream then ends with none, the harness **raises** rather than accounting zero tokens — a silent zero would disable the budget stop condition while looking healthy. Endpoints that don't return streaming usage ship with `false` |
991
+ | `echoes_reasoning` | Opt in to sending this provider's own reasoning back on the next request (§44). Off everywhere by default: there is no standard for it the way there is for receiving reasoning — DeepSeek documents that `reasoning_content` must not be supplied on input and returns a 400, while OpenRouter accepts it for some models and ignores it for others. Anthropic needs no flag; its thinking blocks are signed and are echoed to the model that produced them automatically |
992
+ | `accepts_images` | Opt in to delivering images that `view_image` attaches (ROADMAP_v3 §81). It must be JSON `true`; a quoted `"true"` does not count. It needs setting per endpoint because whether a request with an image succeeds depends on the endpoint and often the model, and sending one to a model without vision fails the request. The example sets it for ANTHROPIC and GOOGLE, the two providers where every chat model accepts images. For an OpenAI-compatible endpoint serving a vision model, add it yourself; the image then travels in a harness message after the tool results, because that API's tool messages carry text only. On GOOGLE the image travels the same way, after the function responses, and a GIF becomes a note there rather than an image. A provider without the flag gets a note saying the image was not sent, and `view_image` is not offered to it at all |
993
+
994
+ `mcp.json` entries are tabulated under [MCP servers](#mcp-servers).
995
+
996
+ ---
997
+
998
+ ## Status
999
+
1000
+ **Built:** ROADMAP.md §1–§12 (§10's ensemble mode rebuilt by its revisit — diversity now comes from a roster of different models) and ROADMAP_v2.md §13 (streaming loop), §14 (config loader + workspace trust), §15 (permissions), §16 (TUI), §17 (MCP), §18 (agents), §19 (skills), §20 (post-pipeline review), §21a (compaction + `pin`), §21b (durable memory), §22 (live pipeline progress), §25 (authorised tool use in the pipeline), §26 (research legibility: per-pass tool calls, code-stage announcements, the claims view, role colour, `/copy`), §27 (thread legibility: transcript replay on resume, a conversations-only thread picker), §21c (session summaries and cross-thread referencing — §21 is now complete), §24 (`/init`), §23 (interactive tools: the response channel, per-tool subagent sign-off, `ask_user`, and the todo list), §28 (the shell capability classifier).
1001
+
1002
+ **Remaining:** nothing in `ROADMAP.md` or `ROADMAP_v2.md`, and §10's revisit is now closed. `ROADMAP_v3.md` §49–§52, §54, §55, §58 and §61–§83 are built. The remaining sections are §53 (rolling network-I/O budgets), §56 (a decision-model shell classifier), §57 (`/submodel`), §59 (memory selection and agent cycling), and §60 (Unified Harness Protocol compliance), each specified and awaiting detailed design. §54 completes project file/folder mentions without loading contents; §58 supplies a short harness identity that follows the current model; §83's final live checks are confirmed, and the ChatGPT header distinguishes a selected provider from an active sign-in. TECHNICAL_DEBT.md items 9 and 10 are open. The two checks recorded against §10 are answered from the providers' documentation in `ROADMAP_v3.md` §87: the default `temperature` on OpenAI and Google is 1.0, and OpenAI's reasoning models refuse one whenever reasoning effort is not `none`, which the guard now follows.
1003
+
1004
+ **Not finished, though: an audit is open.** Both roadmaps being built is not the same as the
1005
+ code being clean, and saying only the first would be the "built and runs are different claims"
1006
+ mistake this project keeps recording against itself. Audit Pass 1 is tracked in GitHub issues —
1007
+ **149 of 154 closed, 5 open**, those five being four `S3`s plus the `#15` tracker itself. Every
1008
+ `S1` (8 of them), `S2` (30) and `S4` (9) finding is closed, and 75 of 79 `S3`s are. It has been
1009
+ worked in numbered fix batches — 32 so far, each recorded in `DEVLOG.md` and
1010
+ `tests/BREAKING_CHANGES.md` with what was measured and what would break the fix.
1011
+
1012
+ **#157 — `shell`'s unbounded auto-approval — is closed** by batch 8 and ROADMAP_v2 §28; the
1013
+ classifier is described under *Security model* above. If you have a fork or a local config,
1014
+ note that shell approval is governed solely by `shell_approval_mode` -- `tool_approvals`
1015
+ deliberately has no `shell` key, so an old file carrying one is refused at startup
1016
+ naming the key — see `tests/BREAKING_CHANGES.md` §24.
1017
+
1018
+ Run the test suite with `pytest` — 9169 tests, fully offline, no API keys needed. The suite's own packages are `requirements-test.txt`, separate from `requirements.txt` since batch 136: they used to be in the shipped dependency list, so installing the harness also installed a test runner. It runs in parallel by default (`pytest-xdist`, 70% of your cores): **1:26 on a 16-core machine, against 9:06 single-process.** `pytest -n0` forces the old serial run, which is what you want under a debugger or when something is parsing the output. Eight further tests are marked `integration` and excluded by default: three spawn a real stdio MCP server, one runs an external program through the host fallback shell, one builds the hosted bundle's Docker image, and three run the installers' uv path against a real uv (`pytest -m integration`).
1019
+
1020
+ ## Documentation
1021
+
1022
+ This file is the user-facing one. For working on the code:
1023
+
1024
+ - **[AGENTS.md](./AGENTS.md)** — the agent-context file, and the place to start. `CLAUDE.md` and `QWEN.md` are pointers to it so a tool looking for a particular filename finds one without the guidance being duplicated.
1025
+ - **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — file-by-file contracts, what belongs where, and the known gotchas. Read before changing anything non-trivial, especially around persistence (`database.py` / `storage.py` / `core/memory.py` are three distinct and easily confused responsibilities).
1026
+ - **[ROADMAP.md](./docs/ROADMAP.md)**, **[ROADMAP_v2.md](./docs/ROADMAP_v2.md)** and **[ROADMAP_v3.md](./docs/ROADMAP_v3.md)** — implementation specs plus the locked Design Decisions Record that most of the reasoning above traces back to. Section numbers run on across the three: v3 opens at §49.
1027
+ - **[DEVLOG.md](./docs/DEVLOG.md)** — what was followed, what was deviated from, and why.
1028
+
1029
+ ### Contributing and policies
1030
+
1031
+ - **[CONTRIBUTING.md](./docs/CONTRIBUTING.md)** — inbound license (Apache-2.0 + DCO), the setup and test loop, the issue and PR format, and a table of which document to update for what.
1032
+ - **[SECURITY.md](./docs/SECURITY.md)** — how to report a vulnerability privately, what is in and out of scope, and the coordinated-disclosure timeline. **Do not open a public issue for one.**
1033
+ - **[PRIVACY.md](./docs/PRIVACY.md)** — what is stored locally, what leaves your machine, and how to delete it. No telemetry.
1034
+ - **[CODE_OF_CONDUCT.md](./docs/CODE_OF_CONDUCT.md)** — Contributor Covenant 2.1, and the private channel for reporting a violation.
1035
+ - **[THIRD_PARTY_NOTICES.md](./docs/THIRD_PARTY_NOTICES.md)** — the dependency license assessment: every declared direct dependency, its license, and its Apache-2.0 compatibility.
1036
+
1037
+ ## License
1038
+
1039
+ Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE). Copyright 2026 Yahya Hammad.
1040
+
1041
+ No third-party source code is bundled here; dependencies are resolved from PyPI at install time
1042
+ under their own licenses. [THIRD_PARTY_NOTICES.md](./docs/THIRD_PARTY_NOTICES.md) records the
1043
+ assessment of each one, and of the third-party text the repository reproduces.