@yahyahammad/venastine 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
package/README.md ADDED
@@ -0,0 +1,878 @@
1
+ # Venastine Research Harness
2
+
3
+ An agentic harness built from scratch — no LangChain, no agent framework — with two modes that share the same machinery:
4
+
5
+ - **Chat** — a normal tool-using assistant loop.
6
+ - **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.
7
+
8
+ Works with Anthropic, any OpenAI-compatible provider (OpenAI, DeepSeek, Groq, Mistral, local endpoints), and Google Gemini.
9
+
10
+ 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.
11
+
12
+ ---
13
+
14
+ ## Setup
15
+
16
+ **Python 3.11 or newer**, either way in. `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.
17
+
18
+ ### From npm
19
+
20
+ ```bash
21
+ npm install -g @yahyahammad/venastine
22
+ venastine
23
+ ```
24
+
25
+ **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.
26
+
27
+ Two things differ from a clone, both to make a command you run from anywhere behave sensibly:
28
+
29
+ * **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.
30
+ * **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.
31
+
32
+ `venastine --venastine-doctor` prints every one of those resolved paths, plus the interpreter and environment it found.
33
+
34
+ ### From a clone
35
+
36
+ ```bash
37
+ pip install -r requirements.txt
38
+ ```
39
+
40
+ This is the contributor path and what the rest of this document assumes.
41
+
42
+ `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]"`.
43
+
44
+ ### Two credential stores, deliberately separate
45
+
46
+ | What | Where | Managed by |
47
+ |---|---|---|
48
+ | **LLM provider keys** (Anthropic, OpenAI, Google, …) | `providers.json` | `credentials.py`, template at `providers.json.example` |
49
+ | **Tool API keys** (GitHub token, NVD key, …) | `.env` | `env_secrets.py`, template at `.env.example` |
50
+
51
+ ```bash
52
+ cp providers.json.example providers.json # then add your provider's API key
53
+ cp .env.example .env # then fill in only the keys your tools actually need
54
+ ```
55
+
56
+ Without the first file every model call fails — both shells say so at launch (#138), but creating it is the one setup step they cannot do for you.
57
+
58
+ 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.
59
+
60
+ ---
61
+
62
+ ## Running it
63
+
64
+ ```bash
65
+ python main.py # chat, new thread
66
+ python main.py --thread <uuid> # resume a thread
67
+ python main.py --mode research "some query" # the ten-pass pipeline
68
+ python main.py --provider OPENAI --model gpt-5.1 # override provider/model
69
+ python main.py --tui # the full-screen interface
70
+ ```
71
+
72
+ The line-based CLI is the default and is never going away — every feature is reachable from it. The TUI is a nicer shell over the same code.
73
+
74
+ Every launch flag is tabulated in the [CLI flag reference](#cli-flag-reference) below; every slash command under [The TUI](#the-tui).
75
+
76
+ 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.
77
+
78
+ ---
79
+
80
+ ## How the research pipeline works
81
+
82
+ 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.
83
+
84
+ ```
85
+ Pass 0 Plan what needs establishing, and what entities matter
86
+ Pass 1 Generate the first full answer
87
+ Pass 2 Extract break that answer into individually checkable claims
88
+ D0 Route are there factual claims? (pure code)
89
+ Pass 3a Ground check each factual claim against real sources
90
+ Score Rate sources what each cited source is worth (pure code + embeddings)
91
+ Pass 3b Critique attack each factual claim on its merits
92
+ Pass 3c Completeness what did the answer never address at all?
93
+ Pass 4 Assumptions what is being taken for granted and never stated?
94
+ Pass 5 Tier score and tier every claim (pure code, no model)
95
+ D1 Route which claims are flagged? (pure code)
96
+ Pass 6a Revise rewrite only the flagged claims
97
+ Pass 6b Re-validate re-ground and re-critique them
98
+ D2 Route retries exhausted → fall back to UNVERIFIED (pure code)
99
+ Pass 6c Annotate attach tier labels to claim text (templated, no model)
100
+ Merge Assemble final claim set (pure code)
101
+ Final Synthesise the report, written from the tiered claims
102
+ ```
103
+
104
+ **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.
105
+
106
+ ### Confidence tiers
107
+
108
+ Every claim comes out with a tier, a score, and the breakdown that produced it.
109
+
110
+ | Tier | Meaning |
111
+ |---|---|
112
+ | **HIGH** | score ≥ 0.8 |
113
+ | **MEDIUM** | score ≥ 0.55 |
114
+ | **LOW** | score ≥ 0.3 |
115
+ | **UNVERIFIED** | below 0.3 — **or any factual claim that could not be grounded, regardless of score** |
116
+ | **UNVERIFIED_COVERAGE** | not a claim at all: something Pass 3c found the answer never addressed |
117
+
118
+ 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.
119
+
120
+ **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.
121
+
122
+ 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.
123
+
124
+ A claim that stays flagged after two revise/re-validate rounds falls to UNVERIFIED rather than being quietly retried forever.
125
+
126
+ ### What a source is worth, and how close it actually is
127
+
128
+ Pass 3a used to hand back two numbers per cited source — how authoritative it is, and how well it
129
+ matches the claim — and one model invented both. Nothing checked either, nothing consumed either,
130
+ and no source text survived the pass, so nothing *could* have checked them. A real run on disk
131
+ scored a Pinterest pin `similarity_score: 1.0` beside the Wikipedia article, on the same claim.
132
+
133
+ **Authority is computed from the source, not asked for.** A domain class sets it — restricted
134
+ registries (`.gov`, `.mil`, `.int`, `.edu`, and `gov.uk`/`ac.uk`-style second levels) at the top,
135
+ then standards bodies and peer-reviewed publishers, down through news, preprint servers and generic
136
+ hosts to blogs, forums, social media and content farms. Note that `.org` sits barely above `.com`:
137
+ anyone can buy one, and treating it as trustworthy is the most common version of this mistake. The
138
+ model may then adjust the computed number by at most ±0.15, and only with a stated reason — for
139
+ what a domain cannot see, like a manufacturer's own spec sheet on an ordinary `.com`, or an opinion
140
+ column on a masthead. An adjustment with no reason is discarded. Base, adjustment, reason and method
141
+ are all recorded, so the score can be recomputed from the artifact.
142
+
143
+ **Similarity is a cosine, when you configure an embedder.** `/embedder <PROVIDER> <model>` picks the
144
+ model; the selection is probed rather than looked up in a table, so a provider without an embeddings
145
+ endpoint or a chat slug passed by mistake fails at the prompt rather than three passes into a run.
146
+ Each source's captured text is split into windows about the length of a claim and the best-matching
147
+ one wins — embedding a 5000-character page whole averages twenty topics into one vector and makes
148
+ every long source look equally irrelevant, which is the dilution the windows exist to remove. Raw
149
+ cosine is not a 0–1 score (unrelated text sits near 0.1 on some models and above 0.7 on others), so
150
+ a per-model band maps the useful range onto 0–1 and the raw cosine is recorded beside it.
151
+
152
+ Without an embedder, every run says so in its first trace line and similarity stays the grounding
153
+ model's own estimate — under an anchored rubric, and marked `similarity_method: "llm"` on every
154
+ source, so no reader has to guess which numbers were measured. The model's estimate is recorded even
155
+ when a cosine replaces it, so the two are comparable on every run.
156
+
157
+ **The model's quote is checked against the page.** Pass 3a is asked for the verbatim span it relied
158
+ on, and that span is looked for in the text the run actually retrieved. `quote_verified` has three
159
+ answers: `true`, `false` — meaning the run fetched this page and the quoted words are not in it,
160
+ which is a fabricated citation — and `null`, meaning there was nothing to check against, which is
161
+ not the same thing.
162
+
163
+ **Cited papers can be scored on their own standing.** With `SCHOLAR_LOOKUP = True` in `config.py`,
164
+ an arXiv or DOI URL is resolved against OpenAlex and scored on venue (peer-reviewed or preprint),
165
+ citation standing, and author h-index. Citation standing is a percentile *within the paper's own
166
+ field-and-year cohort*, measured by two counting queries rather than modelled — OpenAlex's own
167
+ field-normalised metrics are null on preprints, and arXiv is where most cited preprints come from.
168
+ A paper too young, or in a cohort too small, reports that and drops the term rather than scoring
169
+ low; a retraction floors the source outright. It is **off by default**: it is the one network call
170
+ this harness makes outside the tool layer, and an out-of-the-box run should make none you did not
171
+ ask for.
172
+
173
+ The knobs, under `confidence` and `source_scoring` in `settings.json`, each overriding a default in
174
+ code:
175
+
176
+ | Key | Default | Meaning |
177
+ |---|---|---|
178
+ | `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 |
179
+ | `confidence.authority_full_credit` | `0.85` | Authority at or above which a source is not what limits the claim |
180
+ | `confidence.grounding_weight_factor` | `0.5` | Weight of the grounding term |
181
+ | `confidence.critic_weight_factor` | `0.35` | Weight of the critic term |
182
+ | `confidence.assumption_flag_penalty` | `0.15` | Subtracted per assumption flag |
183
+ | `confidence.disagreement_penalty_factor` | `0.15` | Subtracted in proportion to cross-candidate dissent |
184
+ | `confidence.non_factual_score_cap` | `0.65` | Ceiling for claims that were never grounded |
185
+ | `confidence.grounding_weights` | `1.0 / 0.5 / 0.0` | Per grounded / partial / ungrounded |
186
+ | `confidence.tier_thresholds` | `0.8 / 0.55 / 0.3` | HIGH / MEDIUM / LOW; must stay ordered |
187
+ | `source_scoring.window_chars` | `480` | Window size a source is chunked into |
188
+ | `source_scoring.max_windows` | `24` | Windows scored per source |
189
+ | `source_scoring.claim_min_chars` | `80` | Below this, a claim's entities are prepended to the query |
190
+ | `source_scoring.similarity_floor` / `_ceiling` | per-model | Cosine band; unset means use the table for your embedder |
191
+ | `source_scoring.authority_adjustment_cap` | `0.15` | How far the model may move a computed authority |
192
+ | `source_scoring.domain_overrides` | `{}` | `{"host": score}` — how you add your own field's trusted domains |
193
+ | `source_scoring.venue_weight` / `citation_weight` / `author_weight` | `0.4 / 0.4 / 0.2` | How a paper's score is composed |
194
+ | `source_scoring.min_cohort_size` | `200` | Below this the cohort widens before a percentile is trusted |
195
+ | `source_scoring.min_citation_age_days` | `60` | Below this, citation counts are noise and the term is dropped |
196
+
197
+ A value outside its range falls back to the default for that one key and warns once per run, rather
198
+ than refusing to start the run — unlike the compaction knobs above, where an incoherent value burns
199
+ model calls on every turn. An *unknown* key still raises, as everywhere else in `settings.json`.
200
+ `critic_model` and `embedder_model` are rejected there by name: both name a provider this harness
201
+ sends research content to, and a project's `settings.json` outranks your own — use `/critic` and
202
+ `/embedder`, or `config.py`.
203
+
204
+ ### A pass that answers the wrong shape is corrected, then it stops the run
205
+
206
+ Each pass is asked for a specific JSON structure, and each one is checked against that structure
207
+ before anything is applied. A payload that parses but is not what the pass promised goes back to the
208
+ model with the problem named — the same corrective turn a malformed one gets — and if it comes back
209
+ wrong again the run fails, saying which pass and which field:
210
+
211
+ ```
212
+ Pass 3b: entry 0 has severity='0.0', which is string; expected number.
213
+ Pass 2: expected a JSON array, got object. Return the array itself, not an object wrapping it.
214
+ ```
215
+
216
+ That matters more than it sounds. The failures worth preventing are not the loud ones: a model that
217
+ answered about claim ids nobody issued used to produce a *finished* run whose trace said
218
+ `Pass 3a: grounded 4 unique entities across 3 factual claim(s)` while grounding nothing, and then
219
+ spent four more model calls concluding that nothing could be verified. Those counts are what the
220
+ pass was **asked** about; the trace now reports what was actually applied — `grounded 2 of 3` — so a
221
+ pass that half-worked says so.
222
+
223
+ The run does not die over a single stray id: entries that resolve are applied, and only a payload
224
+ where *nothing* matched is treated as a failure. Every number in `04_confidence.json`'s
225
+ `score_breakdown` is one that was actually used, so the fields reconstruct the score they came with.
226
+
227
+ ### Different models can check each other
228
+
229
+ 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.
230
+
231
+ **Ensemble mode** extends the same idea to the answer itself. List `{provider_name, model}` pairs in `ENSEMBLE_MODELS` in `config.py` (a settings.json key is deliberately absent — choosing providers multiplies spend, so it stays in code you own) 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, and factual claims take a disagreement penalty of `0.15 × (1 − consistency)` before tiering — unanimity costs nothing, dissent demotes. 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.
232
+
233
+ ### What you get out
234
+
235
+ Every run writes `output/<run_id>/`:
236
+
237
+ ```
238
+ 00_plan.md 04_assumptions.json trace.md
239
+ 01_raw_response.md 05_confidence.json report.md
240
+ 02_claims.json 06_revisions.json report.pdf (if weasyprint installed)
241
+ 03_grounding.json 07_review.json confidence_chart.png
242
+ 03_critic.json granted_calls.json sources/ code/
243
+ 03_completeness.json pass_threads.json
244
+ ```
245
+
246
+ `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.py` to keep the index and drop the text.
247
+
248
+ 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.
249
+
250
+ 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.
251
+
252
+ **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.
253
+
254
+ ### Watching it happen
255
+
256
+ 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.
257
+
258
+ ```bash
259
+ python main.py --mode research "does the claim about X hold up?"
260
+ ```
261
+
262
+ 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.
263
+
264
+ ### Having it review itself
265
+
266
+ ```bash
267
+ python main.py --mode research --review "some query"
268
+ ```
269
+
270
+ 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.
271
+
272
+ ---
273
+
274
+ ## Security model
275
+
276
+ 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.
277
+
278
+ ### Every tool says what a call to it may cost
279
+
280
+ Approval answers *whether* a tool may run. It says nothing about how long it may run for, and until
281
+ recently nothing else did either: a maths tool handed a large enough number simply never came back,
282
+ taking the turn — or an unattended ten-pass run — with it.
283
+
284
+ Each registered tool now declares one of three answers, and a tool registered without one fails at
285
+ startup rather than at its first call:
286
+
287
+ | | |
288
+ |---|---|
289
+ | **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 — 15 seconds by default, plus CPU and memory ceilings on Linux |
290
+ | **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 |
291
+ | **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 |
292
+
293
+ The distinction between the first two is not bureaucratic. A timeout wrapped around a blocking read
294
+ can only stop *waiting* — the work carries on — so declaring an operation bounded when it is not
295
+ would produce a harness that reports timeouts that never happened. Compute tools get a bound that
296
+ genuinely stops them; io tools have to already have one, and three that did not were fixed:
297
+
298
+ ```
299
+ before after
300
+ edit (on a 30 MB file) 60.0 MB 0.0 MB rejected before opening, as `read` always did
301
+ read_project_doc 60.0 MB 0.1 MB one page costs one page, not the whole document
302
+ fetch_url unbounded capped streamed, so a hostile body stops at the cap
303
+ ```
304
+
305
+ When a compute tool does hit its limit, the model is told which tool and which limit, so it can ask
306
+ for something smaller instead of retrying the same call:
307
+
308
+ ```
309
+ symbolic_math exceeded its 15s limit and was stopped. The inputs given are too
310
+ large for this operation -- try smaller values.
311
+ ```
312
+
313
+ ### Access control: stricter always wins
314
+
315
+ Two separate questions, asked in this order, and they never blend into one score:
316
+
317
+ 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.
318
+ 2. **Does this specific call need you to approve it?** — a logical OR across the same layers plus the tool's own dynamic check.
319
+
320
+ 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.
321
+
322
+ ### What needs approval by default
323
+
324
+ | | |
325
+ |---|---|
326
+ | 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` |
327
+ | Depends on the call | `read`, `write`, `edit` — decided per path, and all three are denied by default anyway |
328
+ | Always | `shell`, `spawn_subagent`, `remember`, `write_project_doc`, and **every MCP tool** |
329
+
330
+ 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.
331
+
332
+ `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.
333
+
334
+ `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.
335
+
336
+ ### `shell` is classified, not just approved
337
+
338
+ `shell` ships **disabled** (`ToolPermissions.shell = False`) and cannot be enabled at runtime, so none of this applies to a default install. If you do enable it, the gate is `config.SHELL_APPROVAL_MODE`:
339
+
340
+ | mode | behaviour |
341
+ |---|---|
342
+ | `always` | every command is asked about, whatever it does |
343
+ | `tiered` | **shipped.** The classifier decides — see below |
344
+ | `never` | nothing is ever asked about |
345
+
346
+ `ToolApprovals.shell` is **not** the gate; it is the ratchet. It ships `False`, and setting it `True` forces `always` regardless of the mode. An agent's `approval_overrides` reaches the same place with the same one-way power: these can tighten and never loosen. 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.
347
+
348
+ Under `tiered`, 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:
349
+
350
+ | tier | what it is | where it runs | asked? |
351
+ |---|---|---|---|
352
+ | `INERT` | read-only command, every argument inside the workspace | host | no |
353
+ | `HOST_READ` | read-only, but an argument reaches outside the workspace | host | **yes** |
354
+ | `SANDBOXED` | anything else, no network | container | no, if Docker is confirmed up |
355
+ | `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** |
356
+ | `UNKNOWN` | could not be characterised at all | — | **yes** |
357
+
358
+ The auto-approved set is narrower than the `read` tool's, which is already unprompted inside the workspace. A `SANDBOXED` command can do what `write` and `edit` can already do without asking — corrupt the workspace — bounded to 1 CPU, 1 GB, 200 processes, 60 seconds, no network and no host filesystem.
359
+
360
+ **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.
361
+
362
+ **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 Docker this costs nothing: `cat "my notes.txt"` is still auto-approved, it simply runs in the container. Fixed in batch 37; `'single quotes'` and `--file="/etc/x"` did it too.
363
+
364
+ **Escaped arguments are never inert either.** The same corollary, one character further, and it
365
+ took a second batch to find: `shlex` consumes `\` exactly as it consumes quotes, so
366
+ `cat \/etc\/passwd` read as one relative token inside the workspace and then ran as `/etc/passwd` on
367
+ the host — measured on a POSIX host at the shipped default. With `\` rejected the character class is
368
+ now **closed** under `shlex`, which consumes exactly whitespace, `'`, `"` and `\`: the classifier's
369
+ tokens and the executor's are provably the same list. On Windows this costs a backslash path such
370
+ as `cat sub\dir\notes.txt`, which moves to the container and fails there — use forward slashes.
371
+
372
+ **These settings are read once, at startup.** Since batch 40 `SHELL_APPROVAL_MODE`, both fallback
373
+ flags and `REDACT_TOOL_OUTPUTS` are bound into a frozen posture (`security/posture.py`) rather than
374
+ consulted at each decision, so nothing running in-process can move them mid-session. If any of them
375
+ is set to something weaker than the shipped default, the harness says so at launch — on stderr, in
376
+ `app.log`, and as a badge in the TUI sidebar for as long as the session lasts.
377
+
378
+ **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.
379
+
380
+ **`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".
381
+
382
+ `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.py`.
383
+
384
+ 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 Docker path only — not reads, and not the subprocess fallback.
385
+
386
+ **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/`. 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.
387
+
388
+ **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. Inert commands never touch Docker — they are plain subprocesses on the host. Anything else probes Docker once per call and shares the result between gate and runner: if Docker was up when the call was approved but down 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 Docker unavailable and `ALLOW_INSECURE_SANDBOX_FALLBACK = True` in `config.py`, 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 60-second wall clock, 1024 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. 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 `python:3.13-slim` image.
389
+
390
+ ### "Headless" means *unable to ask*, not "not a GUI"
391
+
392
+ 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.
393
+
394
+ The rule that falls out of this: **inability to ask is never treated as permission to proceed.**
395
+
396
+ Two consequences, both easier to get wrong than they look:
397
+
398
+ - **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).
399
+ - **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.
400
+
401
+ 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.
402
+
403
+ ### Content policy, on the way in and on the way out
404
+
405
+ Symmetric, and applied centrally to every tool in every mode rather than by tools that opted in:
406
+
407
+ - **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.
408
+ - **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.
409
+ - **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.
410
+ - **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.
411
+ - **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.
412
+ - **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.
413
+
414
+ ### Project directories are untrusted until you say otherwise
415
+
416
+ 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.
417
+
418
+ ```bash
419
+ python main.py --trust-project # for CI and scripts
420
+ ```
421
+
422
+ 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".
423
+
424
+ ### Granting tools to an unattended run
425
+
426
+ A ten-pass research run has no human at the keyboard for minutes at a time. Two independent controls, both off by default:
427
+
428
+ ```bash
429
+ python main.py --mode research --grant "query" # pick from a list, interactively
430
+ python main.py --mode research --grant-tools mcp__files__search "query"
431
+ python main.py --mode research --attended "query" # approve every gated call as it happens
432
+ ```
433
+
434
+ The limits are the interesting part:
435
+
436
+ - **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.
437
+ - **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.
438
+ - **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.
439
+ - **`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.
440
+ - **`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.
441
+ - **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.
442
+ - **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.
443
+ - **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.
444
+
445
+ ### MCP servers: allowed by default, trusted by default never
446
+
447
+ 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.
448
+
449
+ ---
450
+
451
+ ## Everything else
452
+
453
+ ### Long conversations condense themselves
454
+
455
+ 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.
456
+
457
+ Two summarisation strategies exist:
458
+
459
+ - **`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.
460
+ - **`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.
461
+
462
+ 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.
463
+
464
+ `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.
465
+
466
+ The knobs, all under `compaction` in `settings.json`, each overriding a default in `config.py`:
467
+
468
+ | Key | Default | Meaning |
469
+ |---|---|---|
470
+ | `trigger_tokens` | `40000` | Measured context size that fires automatic compaction |
471
+ | `warning_margin_tokens` | `8000` | How far before the trigger you are warned — room to pin something or wrap up first |
472
+ | `keep_recent_tokens` | `4000` | Most-recent tokens that always stay verbatim |
473
+ | `keep_recent_turns` | `3` | Turn floor beside the token floor — whichever protects more wins, plus the current turn, which never folds |
474
+ | `strength` | `3` | Target compression ratio, 1–5: keep ~40% at 1 down to ~5% at 5 |
475
+ | `max_retries` | `2` | Corrective re-asks when a summary misses its target ratio |
476
+ | `strategy` | `"chain"` | Or `"rederive"`, as above |
477
+
478
+ `/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.
479
+
480
+ 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.
481
+
482
+ ### Durable memory
483
+
484
+ `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.
485
+
486
+ ```bash
487
+ python main.py --memories # list what's visible from here
488
+ python main.py --forget <id> # delete one, by id
489
+ ```
490
+
491
+ 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.
492
+
493
+ ### Agents and skills
494
+
495
+ 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`.
496
+
497
+ A skill declaring `additional_tools` is stating a *need*, not granting anything — activation proceeds and tells you what is missing.
498
+
499
+ 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.
500
+
501
+ Seven 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). Two are:
502
+
503
+ | agent | for | reach it with |
504
+ |---|---|---|
505
+ | `plan` | designing an approach before the work starts — reads what exists, names the decisions, says what would make the plan wrong | `/agent plan` |
506
+ | `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` |
507
+ | `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` |
508
+
509
+ `explore` and `review` are **read-only by omission**: `write`, `edit`, `write_project_doc` and `remember` are simply absent from their tool lists, so no configuration makes one reachable. They do list `read` and `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 both become code agents only where you have enabled file access in `config.py`. Approving a spawn of either 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.
510
+
511
+ 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.
512
+
513
+ #### Writing your own
514
+
515
+ 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.
516
+
517
+ Agent frontmatter fields:
518
+
519
+ | Field | Type | Default | Meaning |
520
+ |---|---|---|---|
521
+ | `name` | string | *required* | Catalog identity, global across tiers |
522
+ | `description` | string | `""` | One line into every system prompt — collapsed to a single line and capped at 300 characters (see below) |
523
+ | `model`, `provider` | string | inherit session | Pin this agent's own model/provider; `/model` tells you when one is active |
524
+ | `allowed_tools` | list | everything allowed | A whitelist that only ever narrows — nothing can widen it |
525
+ | `approval_overrides` | mapping | `{}` | Can only ever *add* prompts, never remove one |
526
+ | `use_project_context` | bool | `false` | Inject the project's root `AGENTS.md` into the system prompt |
527
+ | `use_memory` | bool | `true` | Inject durable memories (plain chat counts as opted in) |
528
+ | `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 |
529
+ | `spawnable` | bool | `false` for your files | Whether `spawn_subagent` may feed this agent |
530
+
531
+ 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.
532
+
533
+ ### A description is text, and the prompt treats it as one line
534
+
535
+ 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.
536
+
537
+ ### MCP servers
538
+
539
+ Configured in `mcp.json`, at `~/.config/venastine/mcp.json` or `.venastine/mcp.json` — `/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:
540
+
541
+ ```json
542
+ {"mcpServers": {"files": {"command": "npx", "args": ["-y", "@example/server"]}}}
543
+ ```
544
+
545
+ Tools are namespaced `mcp__<server>__<tool>`. A server that fails to connect is named and skipped, never fatal.
546
+
547
+ Per-server entry fields:
548
+
549
+ | Field | Transports | Meaning |
550
+ |---|---|---|
551
+ | `command`, `args` | stdio | Spawn this local process |
552
+ | `env`, `cwd` | stdio | Extra environment variables; working directory |
553
+ | `url` | http, sse | Remote endpoint |
554
+ | `type` | http, sse | `"sse"` selects Server-Sent Events; a bare `url` without `type` is always streamable HTTP |
555
+ | `headers` | http, sse | Extra HTTP headers — `Authorization` is where a hosted server's credential usually rides |
556
+ | `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 |
557
+ | `disabled` | both | Load nothing from this entry |
558
+
559
+ 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.
560
+
561
+ ### The TUI
562
+
563
+ | Command | What it does |
564
+ |---|---|
565
+ | `/help` | List every registered command with its usage |
566
+ | `/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 |
567
+ | `/effort [level\|auto]` | Switch reasoning effort, offering only levels this model accepts (Anthropic's are queried live). Session-only (`tui.effort` persists) |
568
+ | `/thinking [on\|off]` | Show or hide reasoning inline for this session. Session-only (`tui.show_thinking` persists) |
569
+ | `/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 |
570
+ | `/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 |
571
+ | `/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 |
572
+ | `/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 |
573
+ | `/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 |
574
+ | `/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 |
575
+ | `/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 |
576
+ | `/claims [run id]` | Open the claims view — tier, grounding status, assumption flags, score breakdown per claim — during a run or afterwards (**ctrl+l**) |
577
+ | `/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 |
578
+ | `/threads` | Conversations-only picker — research runs' internal threads excluded — most recently active first, capped at 200 with a notice (**ctrl+t**) |
579
+ | `/resume <thread-id>` | Open any thread by id, however old |
580
+ | `/new` | Start a fresh thread; created lazily on your next message, so `/new` twice leaves nothing behind |
581
+ | `/agent [name\|default]` | Make an agent active for subsequent turns; `default` clears. Active skills are re-checked against the new agent's tool policy |
582
+ | `/goal [text\|clear]` | Persistent objective for this thread — injected into every turn in either shell, mirrored in a banner |
583
+ | `/grill-me` | One turn under the grill-me agent inside the current thread, reading the live history rather than a digest of it |
584
+ | `/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 |
585
+ | `/memories` | List durable memories visible from here, with ids for `/forget` |
586
+ | `/forget <id>` | Delete one memory by id — never by substring |
587
+ | `/summary` | Distil this conversation and show it. Describes; does **not** fold — that is `/compact` |
588
+ | `/ref [--list\|--clear]` | Pick another conversation and attach its summary to this one as standing context; `--list` and `--clear` manage attachments |
589
+ | `/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 |
590
+
591
+ Keys: **ctrl+c** quit · **ctrl+t** thread picker · **ctrl+l** claims view.
592
+
593
+ 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.
594
+
595
+ 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.
596
+
597
+ `/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.
598
+
599
+ 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.
600
+
601
+ `/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`.
602
+
603
+ 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.py` 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.
604
+
605
+ `/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>`.
606
+
607
+ `/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.
608
+
609
+ `/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.
610
+
611
+ `/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.
612
+
613
+ `/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.
614
+
615
+ ### The CLI reads stdin exactly once
616
+
617
+ Chat mode, the approval prompts, the trust prompt, `--init` and the MCP acknowledgement all read
618
+ through **one** object. That sounds like an implementation detail and is not: before it, an approval
619
+ prompt started a background reader that never stopped, so from the first gated tool call onwards
620
+ chat's own `input()` lost every line to it and blocked forever — silently, and looking exactly like
621
+ the model thinking. Recovery was Ctrl+C and `--thread <id>`.
622
+
623
+ Two disciplines, because the two kinds of prompt want opposite things:
624
+
625
+ | | drains stale input | deadline |
626
+ |---|---|---|
627
+ | the gated prompts — approvals, sign-offs, questions, review | **yes** | from the channel |
628
+ | the chat prompt and the startup prompts | no | none |
629
+
630
+ The drain is a safety rule: a line typed after a question timed out was answering *that* question,
631
+ and letting it fall through would approve the next call on the strength of it. The chat prompt must
632
+ *not* drain, for the mirror-image reason — a line typed while the model was still streaming is an
633
+ answer to the prompt about to appear, and the terminal has been buffering it for you.
634
+
635
+ **A deadline belongs to a run, not to a question.** An approval asked during an attended research run
636
+ expires after `ATTENDED_APPROVAL_TIMEOUT_S` (600s) and denies that call, because there is a run
637
+ waiting on the answer and it has to keep moving. `--init`'s prompts have no run behind them, so they
638
+ wait as long as you need — and they do not print a `(600s)` they would not honour.
639
+
640
+ `--help` and a mistyped flag now do nothing at all. They used to create a 77 KB six-table SQLite
641
+ database and a log directory in whichever directory you ran them from, before argparse had seen a
642
+ single flag.
643
+
644
+ `--review` and `--no-review` in chat mode are refused rather than ignored, matching
645
+ `--grant`/`--grant-tools`/`--attended`. Inside the TUI, use `/research --review <query>`.
646
+
647
+ ### CLI flag reference
648
+
649
+ Everything `python main.py` accepts. Wherever a value can come from more than one place, precedence is explicit flag > `settings.json` > built-in default.
650
+
651
+ | Argument | Effect |
652
+ |---|---|
653
+ | `query` (positional) | Research mode: the question the pipeline runs on — required there. Chat mode: sent as the first message, then the interactive loop continues |
654
+
655
+ | Flag | Effect |
656
+ |---|---|
657
+ | `--thread UUID` | Resume a stored conversation; what you said replays so you can see what you are picking up |
658
+ | `--mode chat\|research` | Which loop to run. Chat is the default |
659
+ | `--tui` | Launch the full-screen interface instead of the line-based CLI |
660
+ | `--provider NAME` | Any entry from `providers.json` — `ANTHROPIC`, `OPENAI`, or an OpenAI-compatible endpoint you added |
661
+ | `--model NAME` | Model id as the provider knows it |
662
+ | `--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 |
663
+ | `--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 |
664
+ | `--grant-tools NAMES` | Research only. Same as `--grant`, but takes an explicit comma-separated list of tool names and works without a terminal |
665
+ | `--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 |
666
+ | `--review` / `--no-review` | Research only. Post-pipeline review on/off for this run; `--no-review` is the escape from a persisted setting |
667
+ | `--memories` | List durable memories visible from this directory — id, scope, content — and exit |
668
+ | `--forget ID` | Delete one memory by id — never by substring — and exit |
669
+ | `--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 |
670
+ | `--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 |
671
+ | `--trust-project` | Grant workspace trust non-interactively for scripts/CI, printing what it trusts as it does so |
672
+ | `--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 |
673
+ | `--software-project` / `--research-project` | With `--init`: choose the document set without asking. At most one of the two |
674
+ | `--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 |
675
+
676
+ **Combinations the parser refuses** (rather than ignoring):
677
+
678
+ - `--mode research` without a positional query.
679
+ - `--tui` with `--mode research` — use `/research` inside the TUI.
680
+ - `--tui` with a positional query — start the TUI and type.
681
+ - Any of `--grant`, `--grant-tools`, `--attended`, `--review`, `--no-review` outside research mode, including under `--tui`.
682
+ - Both kind flags with `--init`.
683
+
684
+ **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.
685
+
686
+ ### Reasoning effort
687
+
688
+ 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.
689
+
690
+ 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.
691
+
692
+ A level is validated against the model that will **receive** it, not the one it was chosen for:
693
+
694
+ | Provider | Levels | Where the set comes from |
695
+ |---|---|---|
696
+ | 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 |
697
+ | 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 |
698
+ | Google | Levels map to integer thinking budgets, `low`→2,048 through `max`→dynamic | Mapped at the boundary. The pinned `google-genai` has no budget field, so Google currently reports no levels and effort drops regardless of the default |
699
+
700
+ **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.
701
+
702
+ 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.
703
+
704
+ ### Budgets and stop conditions
705
+
706
+ 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.
707
+
708
+ Three things can end a turn or pass early:
709
+
710
+ | Stop reason | When |
711
+ |---|---|
712
+ | `complete` | The model answered without calling another tool |
713
+ | `max_steps_reached` | Step ceiling hit — 50 by default; an agent's own `max_steps` replaces that number, in either direction |
714
+ | `token_budget_exceeded` | Only when `max_token_budget` is configured: cumulative billed spend crossed it |
715
+
716
+ 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.
717
+
718
+ Other ceilings worth knowing: the six maths tools run in killable subprocesses under a 15-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`); attended prompts expire after 600 seconds (`ATTENDED_APPROVAL_TIMEOUT_S`), denying that one call while the run continues.
719
+
720
+ ### Logging
721
+
722
+ 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`; garbage is a startup error rather than a silent fallback) 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.
723
+
724
+ 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.
725
+
726
+ ### Configuration reference
727
+
728
+ | File | Holds | Notes |
729
+ |---|---|---|
730
+ | `providers.json` | LLM provider keys | gitignored; path movable with `AGENT_PROVIDERS_FILE` |
731
+ | `.env` | tool API keys | gitignored |
732
+ | `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 |
733
+ | `mcp.json` | MCP servers | unknown keys ignored; same two locations. `/init --config` writes an empty project copy |
734
+ | `trusted_projects.json` | workspace-trust store | user-level (`~/.config/venastine/`); written by the trust prompt or `--trust-project`, keyed to resolved path + content hash |
735
+ | `AGENTS.md` | project context for the model | project root; covered by workspace trust |
736
+
737
+ Precedence for provider and model is CLI flag > `settings.json` > `config.py`. Two different merge orders, deliberately:
738
+
739
+ - **Inside `settings.json`, project beats user** — this is the one file where "more specific wins" holds, which is exactly why the two authority-bearing keys below are rejected there by name. Nested objects merge key-by-key across tiers.
740
+ - **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".
741
+
742
+ #### Every `settings.json` key
743
+
744
+ 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.
745
+
746
+ | Key | Type | Default | Meaning |
747
+ |---|---|---|---|
748
+ | `default_provider` | string | `"ANTHROPIC"` | Used unless `--provider` overrides |
749
+ | `default_model` | string | `claude-sonnet-5` | Used unless `--model` overrides |
750
+ | `effort` | string | `"high"` | Reasoning effort for chat and research; `"auto"` clears even this. See [Reasoning effort](#reasoning-effort) |
751
+ | `max_token_budget` | int \| null | null — uncapped | Per-run billed-spend ceiling. See [Budgets and stop conditions](#budgets-and-stop-conditions) |
752
+ | `ensemble_mode` | bool | `false` | Master switch for ensemble Pass 1; the roster lives in `config.py` |
753
+ | `ensemble_n` | int | — | Accepted with a warning; vestigial — the count now derives from the roster |
754
+ | `compaction` | object | — | Seven keys tabulated in [the compaction section](#long-conversations-condense-themselves) above |
755
+ | `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 |
756
+ | `tui.animations` | bool | `true` | Master switch for the raven and transitions |
757
+ | `tui.effort` | string | — | Persisted TUI effort level; beats top-level `effort` inside the TUI |
758
+ | `tui.todo_position` | string | — | `top`, `bottom` or `side`; validated at load |
759
+ | `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 |
760
+ | `research.approval_mode` | string | `"none"` | `"attended"` makes research runs ask about every gated call, as if launched with `--attended` |
761
+ | `research.subagent_review` | bool | `false` | Review on by default, as if launched with `--review`; escaped per run with `--no-review` |
762
+
763
+ Two 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:
764
+
765
+ | Rejected key | Why |
766
+ |---|---|
767
+ | `shell_approval_mode` | Decides whether shell commands are asked about at all; set `SHELL_APPROVAL_MODE` in `config.py` instead |
768
+ | `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 |
769
+
770
+ #### `config.py`-only settings
771
+
772
+ Deliberately not settings.json keys: editing these means editing the file in your checkout, so nothing a cloned repository carries can reach them.
773
+
774
+ | Constant | Default | Controls |
775
+ |---|---|---|
776
+ | `CRITIC_MODEL` | `None` | Routes passes 3a/3b/6c to a different `{provider_name, model}` |
777
+ | `ENSEMBLE_MODELS` (with `ENSEMBLE_MODE`) | `None` (off) | Pass-1 roster; fewer than two distinct pairs is refused |
778
+ | `DEFAULT_EFFORT` | `"high"` | Effort when neither flag nor settings speaks |
779
+ | `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 |
780
+ | `GOOGLE_THINKING_BUDGETS` | low→2,048 … max→dynamic | Google level→thinking-token map |
781
+ | `MODELS_REJECTING_SAMPLING_PARAMS` | current Anthropic models | These 400 on temperature/top_p/top_k; such parameters are dropped with a WARNING rather than sent |
782
+ | `MODEL_CONTEXT_WINDOWS` / `DEFAULT_CONTEXT_WINDOW` | 200k 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 |
783
+ | `SHELL_APPROVAL_MODE` | `"tiered"` | The shell gate: `always` / `tiered` / `never`; a bad value raises at import. Rejected in settings.json by name, see above |
784
+ | `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 |
785
+ | `INERT_COMMANDS` | ls, cat, grep, wc, … | Read-only commands that run as plain host subprocesses, skipping Docker entirely |
786
+ | Sandbox bounds | image `python:3.13-slim`; 60 s, 1024 MB, 30 CPU-s, 200 pids | `SANDBOX_DOCKER_IMAGE`, `SANDBOX_TIMEOUT_SECONDS`, `SANDBOX_MEMORY_MB`, `SANDBOX_CPU_SECONDS`, `SANDBOX_MAX_PIDS` |
787
+ | `ALLOW_INSECURE_SANDBOX_FALLBACK` / `AUTO_APPROVE_SANDBOX_FALLBACK` | `False` / `False` | Enable, then de-prompt, the weak host-subprocess fallback |
788
+ | `REDACT_TOOL_OUTPUTS` | `True` | Master switch for output redaction. Never affects input refusals, the depth-cap bound, or the log formatter's own guard |
789
+ | `TOOL_COMPUTE_TIMEOUT_S` | 15 | Wall clock per maths-tool subprocess |
790
+ | `MAX_GRANTED_TOOL_CALLS` | 150 | Pre-granted calls per research run before it must ask again |
791
+ | `ATTENDED_APPROVAL_TIMEOUT_S` | 600 | Attended prompt deadline; expiry denies that call while the run continues |
792
+ | `SUBAGENT_REVIEW` | `False` | Shipped default for the post-pipeline review |
793
+ | `MAX_REVIEW_FINDINGS` / `MAX_REVIEW_REFINEMENTS` | 25 / 3 | Consent-fatigue caps on the review stage |
794
+ | `MAX_PIPELINE_RETRIES` / `MAX_JSON_RETRIES` | 2 / 2 | Revise/re-validate rounds per claim; corrective attempts per malformed pass payload |
795
+ | `MAX_ITERATIONS` | 50 | Step ceiling for a turn or pass absent an agent's own `max_steps` |
796
+ | `SUBAGENT_MAX_DEPTH` | 2 | `spawn_subagent` nesting limit |
797
+ | `PIN_MAX_TRIGGER_FRACTION` | 0.5 | Largest share of the trigger one pin may protect |
798
+ | `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 |
799
+ | `SUMMARY_TARGET_CHARS` | 2000 | Size cap on whole-thread summaries injected via `/ref` |
800
+ | `MAX_CATALOG_TEXT_CHARS` | 300 | Cap on an agent/skill `name` + `description` entering system prompts |
801
+ | `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) |
802
+ | `TEARDOWN_BUDGET_S` | 10 | Shared wall clock for MCP shutdown; stragglers are named in a WARNING |
803
+
804
+ #### Environment variables
805
+
806
+ | Variable | Default | Controls |
807
+ |---|---|---|
808
+ | `AGENT_MODEL` | `claude-sonnet-5` | Built-in default model (`config.MODEL_NAME`) — still loses to settings.json and `--model` |
809
+ | `AGENT_PROVIDERS_FILE` | `providers.json` | Credential-file location |
810
+ | `APP_DB_PATH` | `app.db` | SQLite database path |
811
+ | `AGENT_OUTPUT_DIR` | `./output` | Research artifacts root |
812
+ | `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 |
813
+ | `AGENT_SHELL` | auto-detect | Host shell binary for the `shell` tool |
814
+ | `AGENT_SANDBOX_IMAGE` | `python:3.13-slim` | Sandbox container image |
815
+ | `AGENT_LOG_LEVEL` | `INFO` | Log verbosity — name or numeric level |
816
+ | `AGENT_LOG_FILE` | `logs/app.log` | Rotating log location |
817
+ | `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 |
818
+ | `VENASTINE_MCP_ACK_FULL` | unset | `=1` appends the raw mcp.json entry to a server's acknowledgement prompt |
819
+
820
+ #### `providers.json` entries
821
+
822
+ | Field | Meaning |
823
+ |---|---|
824
+ | `API_URL` | Endpoint base URL; empty for ANTHROPIC and GOOGLE, which use their SDKs' defaults |
825
+ | `API_KEY` | The credential, stored directly |
826
+ | `is_v1_compatible` | `true` routes the provider through the OpenAI-compatible translation |
827
+ | `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` |
828
+ | `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 |
829
+
830
+ `mcp.json` entries are tabulated under [MCP servers](#mcp-servers).
831
+
832
+ ---
833
+
834
+ ## Status
835
+
836
+ **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).
837
+
838
+ **Remaining:** nothing in either roadmap, and §10's revisit is now closed. TECHNICAL_DEBT.md items 9 and 10 are open, and two live checks are recorded against §10 (see DEVLOG) that cannot be settled offline: the default `temperature` on OpenAI and Google, and whether OpenAI's reasoning models belong in `config.MODELS_REJECTING_SAMPLING_PARAMS`.
839
+
840
+ **Not finished, though: an audit is open.** Both roadmaps being built is not the same as the
841
+ code being clean, and saying only the first would be the "built and runs are different claims"
842
+ mistake this project keeps recording against itself. Audit Pass 1 is tracked in GitHub issues —
843
+ **149 of 154 closed, 5 open**, those five being four `S3`s plus the `#15` tracker itself. Every
844
+ `S1` (8 of them), `S2` (30) and `S4` (9) finding is closed, and 75 of 79 `S3`s are. It has been
845
+ worked in numbered fix batches — 32 so far, each recorded in `DEVLOG.md` and
846
+ `tests/BREAKING_CHANGES.md` with what was measured and what would break the fix.
847
+
848
+ **#157 — `shell`'s unbounded auto-approval — is closed** by batch 8 and ROADMAP_v2 §28; the
849
+ classifier is described under *Security model* above. If you have a fork or a local `config.py`,
850
+ note that `ToolApprovals.shell` now ships `False` and `SHELL_APPROVAL_MODE` is the gate — see
851
+ `tests/BREAKING_CHANGES.md` §24.
852
+
853
+ Run the test suite with `pytest` — 3510 tests, fully offline, no API keys needed. One further test is marked `integration` and excluded by default; it spawns a real stdio MCP server (`pytest -m integration`).
854
+
855
+ ## Documentation
856
+
857
+ This file is the user-facing one. For working on the code:
858
+
859
+ - **[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.
860
+ - **[ARCHITECTURE.md](./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).
861
+ - **[ROADMAP.md](./ROADMAP.md)** and **[ROADMAP_v2.md](./ROADMAP_v2.md)** — implementation specs plus the locked Design Decisions Record that most of the reasoning above traces back to.
862
+ - **[DEVLOG.md](./DEVLOG.md)** — what was followed, what was deviated from, and why.
863
+
864
+ ### Contributing and policies
865
+
866
+ - **[CONTRIBUTING.md](./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.
867
+ - **[SECURITY.md](./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.**
868
+ - **[PRIVACY.md](./PRIVACY.md)** — what is stored locally, what leaves your machine, and how to delete it. No telemetry.
869
+ - **[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)** — Contributor Covenant 2.1, and the private channel for reporting a violation.
870
+ - **[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)** — the dependency license assessment: every declared direct dependency, its license, and its Apache-2.0 compatibility.
871
+
872
+ ## License
873
+
874
+ Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE). Copyright 2026 Yahya Hammad.
875
+
876
+ No third-party source code is bundled here; dependencies are resolved from PyPI at install time
877
+ under their own licenses. [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) records the
878
+ assessment of each one, and of the third-party text the repository reproduces.