@yahyahammad/venastine 0.2.0 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
package/config.yaml ADDED
@@ -0,0 +1,1090 @@
1
+ # Venastine harness configuration.
2
+ #
3
+ # Every tunable value the harness has. `config.py` reads this file once at
4
+ # import through `config_schema.py` and publishes the values as module
5
+ # attributes, so the names here are the lower-cased form of the constants the
6
+ # code uses: `max_tokens` is `config.MAX_TOKENS`.
7
+ #
8
+ # WHY THE HISTORY IS NOT IN HERE. Each of these numbers was argued, several
9
+ # were reversed once, and the arguments run to hundreds of lines -- they live
10
+ # in CONFIG_ARCHITECTURE.md, section by section, under the name used here.
11
+ # Read it before changing a value. The comments below say what a value DOES;
12
+ # that document says why it is what it is.
13
+ #
14
+ # THREE THINGS TO KNOW BEFORE EDITING.
15
+ #
16
+ # 1. This file ships with the harness and has exactly ONE location, beside
17
+ # config.py. There is no user-level or project-level copy and no
18
+ # environment variable that redirects it. That absence is deliberate and
19
+ # is a security property rather than an oversight: settings.json refuses
20
+ # shell_approval_mode, ensemble_models, critic_model and embedder_model by
21
+ # name precisely because a project's settings.json beats the user's and
22
+ # arrives with a directory you cloned.
23
+ #
24
+ # 2. Keys marked AUTHORITY decide what this harness may do to its host, or
25
+ # name a provider it sends your research content to. Nothing UNATTENDED
26
+ # can change them -- not a tool call, not a settings file, not an
27
+ # environment variable. This file is the only route and it needs a
28
+ # human: `/config` writes one, but only after saying what the key
29
+ # permits and asking (batch 84).
30
+ #
31
+ # 3. Values are read ONCE, at startup. Editing this file while the harness is
32
+ # running changes nothing until the next launch.
33
+ #
34
+ # A missing key, an unknown key, a duplicated key or a value of the wrong
35
+ # type is a startup error naming the key. There are no defaults behind this
36
+ # file.
37
+
38
+ # ======================================================================
39
+ # Model and loop
40
+ # ======================================================================
41
+
42
+ # The model every path uses when nothing more specific speaks.
43
+ # --model > settings.json default_model > this. AGENT_MODEL overrides.
44
+ model_name: claude-sonnet-5
45
+
46
+ # Per-call OUTPUT ceiling, sent as max_tokens / max_output_tokens /
47
+ # max_completion_tokens. On current Anthropic models it bounds thinking
48
+ # and response text together, so effort spends from the same budget.
49
+ max_tokens: 16000
50
+
51
+ # The default step ceiling: every chat turn, every research pass, and any
52
+ # agent whose frontmatter names no max_steps or names an invalid one.
53
+ max_iterations: 50
54
+
55
+ # How many more times ONE model call is attempted when the provider fails in
56
+ # a way that can pass: a dropped connection, a 408/409/429/5xx, or an error
57
+ # sent inside a stream that had already opened. Total attempts per call is
58
+ # this plus one. The openai and anthropic SDKs still retry a request that
59
+ # fails before its stream opens, inside each attempt. 0 turns this off.
60
+ model_call_max_retries: 2
61
+
62
+ # Seconds before the first of those retries. Each later retry waits twice as
63
+ # long, with up to 25% jitter either way; a server's retry-after can make a
64
+ # wait longer, never shorter, capped at 60s.
65
+ model_call_retry_base_delay_s: 3.0
66
+
67
+ # ======================================================================
68
+ # Subagents
69
+ # ======================================================================
70
+
71
+ # How deep spawn_subagent may nest, checked against
72
+ # ToolContext.subagent_depth.
73
+ subagent_max_depth: 2
74
+
75
+ # How many calls of one response may run at once, for tools whose ToolSpec
76
+ # declares `parallel`. A ceiling, not a target: more calls run in waves of
77
+ # this size. 1 makes the parallel path behave exactly like the sequential
78
+ # one, which is the escape hatch if concurrency is ever suspect.
79
+ subagent_max_parallel: 3
80
+
81
+ # ======================================================================
82
+ # Deep research pipeline
83
+ # ======================================================================
84
+
85
+ # Revise/re-validate loop iterations per claim before the pipeline falls
86
+ # back.
87
+ max_pipeline_retries: 2
88
+
89
+ # Corrective follow-up attempts when a pass returns malformed JSON.
90
+ # Total attempts per pass is this plus one.
91
+ max_json_retries: 2
92
+
93
+ # ======================================================================
94
+ # Ensemble mode
95
+ # ======================================================================
96
+
97
+ # Run Pass 1 once per `ensemble_models` entry. A settings.json
98
+ # `ensemble_mode` outranks this; the roster below has no settings key.
99
+ ensemble_mode: false
100
+
101
+ # AUTHORITY -- no settings.json key exists at any tier, because a roster chooses
102
+ # which providers N research passes call. N is its length and is never
103
+ # configured separately. Fewer than two DISTINCT (provider_name, model)
104
+ # pairs is refused: one model cannot disagree with itself.
105
+ # null, with ensemble_mode false, is the shipped configuration. Example:
106
+ # ensemble_models:
107
+ # - {provider_name: ANTHROPIC, model: claude-opus-5}
108
+ # - {provider_name: OPENAI, model: gpt-5.1}
109
+ ensemble_models: null
110
+
111
+ # ======================================================================
112
+ # Sampling-parameter support
113
+ # ======================================================================
114
+
115
+ # Models that reject temperature / top_p / top_k outright, or ignore them.
116
+ # core/client.py omits those parameters entirely for anything listed, with a
117
+ # WARNING. Steering on these happens through prompting and
118
+ # model_effort_levels instead.
119
+ #
120
+ # The two gemini names IGNORE the parameters (ROADMAP_v3 §87): no error and
121
+ # no effect. Google says every later Gemini will do the same, then refuse
122
+ # them with a 400, so a new Gemini model belongs here when it ships. OpenAI's
123
+ # reasoning models are not listed: core/client.py drops the parameters on
124
+ # OPENAI whenever a reasoning effort other than "none" is sent, which is
125
+ # OpenAI's own rule and needs no model names.
126
+ #
127
+ # On ANTHROPIC every model drops them since batch 234 (API version
128
+ # 2026-10-21 refuses them on all of them), so the claude names below matter
129
+ # for Claude reached through an OpenAI-compatible gateway, by its bare name.
130
+ models_rejecting_sampling_params:
131
+ - claude-fable-5
132
+ - claude-fable-5-1
133
+ - claude-haiku-5-5
134
+ - claude-mythos-5
135
+ - claude-mythos-5-1
136
+ - claude-opus-4-7
137
+ - claude-opus-4-8
138
+ - claude-opus-5
139
+ - claude-opus-5-5
140
+ - claude-sonnet-5
141
+ - claude-sonnet-5-5
142
+ - gemini-3.5-flash-lite
143
+ - gemini-3.6-flash
144
+
145
+ # ======================================================================
146
+ # Critic and embedder routing
147
+ # ======================================================================
148
+
149
+ # AUTHORITY -- names a provider every claim is sent to. `/critic` writes a
150
+ # user-tier store that OUTRANKS this, and settings.json rejects the key by
151
+ # name at every tier. null means no special routing.
152
+ critic_model: null
153
+
154
+ # AUTHORITY -- names a provider that receives claim text and the text of every
155
+ # page a run fetched. `/embedder` outranks this. null means no special
156
+ # routing.
157
+ embedder_model: null
158
+
159
+ # Per-embedder similarity floor and ceiling, matched by model-name PREFIX
160
+ # (the longest matching prefix wins).
161
+ similarity_calibration:
162
+ text-embedding-3:
163
+ floor: 0.1
164
+ ceiling: 0.65
165
+ text-embedding-ada:
166
+ floor: 0.7
167
+ ceiling: 0.92
168
+ e5-:
169
+ floor: 0.7
170
+ ceiling: 0.92
171
+ multilingual-e5:
172
+ floor: 0.7
173
+ ceiling: 0.92
174
+ bge-:
175
+ floor: 0.55
176
+ ceiling: 0.85
177
+ gte-:
178
+ floor: 0.55
179
+ ceiling: 0.88
180
+ nomic-embed:
181
+ floor: 0.4
182
+ ceiling: 0.8
183
+ embed-english:
184
+ floor: 0.25
185
+ ceiling: 0.8
186
+ voyage:
187
+ floor: 0.35
188
+ ceiling: 0.85
189
+ gemini-embedding:
190
+ floor: 0.35
191
+ ceiling: 0.85
192
+
193
+ # For an embedder that matches no prefix above.
194
+ default_similarity_calibration:
195
+ floor: 0.25
196
+ ceiling: 0.85
197
+
198
+ # The query/passage prefixes asymmetric embedders need, matched by
199
+ # model-name prefix. An embedder absent from here is sent bare text.
200
+ embedder_prefixes:
201
+ e5-:
202
+ query: 'query: '
203
+ passage: 'passage: '
204
+ multilingual-e5:
205
+ query: 'query: '
206
+ passage: 'passage: '
207
+ bge-:
208
+ query: 'Represent this sentence for searching relevant passages: '
209
+ passage: ''
210
+ gte-:
211
+ query: ''
212
+ passage: ''
213
+ nomic-embed:
214
+ query: 'search_query: '
215
+ passage: 'search_document: '
216
+ gemini-embedding:
217
+ query_task_type: RETRIEVAL_QUERY
218
+ passage_task_type: RETRIEVAL_DOCUMENT
219
+ text-embedding-004:
220
+ query_task_type: RETRIEVAL_QUERY
221
+ passage_task_type: RETRIEVAL_DOCUMENT
222
+
223
+ # ======================================================================
224
+ # Source authority: domain classes
225
+ # ======================================================================
226
+
227
+ # Class name -> authority score. The second table, below, maps hosts onto
228
+ # these names, so a score is changed in one place.
229
+ domain_authority_classes:
230
+ restricted_registry: 0.9 # .gov .mil .int .edu, gov.uk, ac.uk...
231
+ intergovernmental: 0.9 # WHO, UN, World Bank, OECD, EU
232
+ standards_body: 0.88 # IETF, W3C, ISO, NIST, IEC
233
+ peer_reviewed_publisher: 0.85
234
+ established_news: 0.65
235
+ preprint_server: 0.6 # not peer reviewed; §45 SQ5 refines this
236
+ reference_tertiary: 0.55 # encyclopaedias -- a pointer to a source
237
+ generic_org: 0.55 # an unrestricted registry, small bump
238
+ generic_commercial: 0.45
239
+ blog_platform: 0.3
240
+ forum_qa: 0.25
241
+ social_media: 0.15
242
+ content_farm: 0.1
243
+
244
+ # The score for a host that matches no suffix below; its class reads
245
+ # "unknown".
246
+ default_domain_authority: 0.45
247
+
248
+ # Host suffix -> a class name from the table above. The `<kind>.<cc>`
249
+ # second-level forms are derived in source_scoring.py, not listed here.
250
+ domain_authority_suffixes:
251
+
252
+ # Restricted registries. The bare TLDs; the `<kind>.<cc>`
253
+ # second-level forms are derived in source_scoring.py rather than
254
+ # listed.
255
+ gov: restricted_registry
256
+ mil: restricted_registry
257
+ int: restricted_registry
258
+ edu: restricted_registry
259
+
260
+ # Intergovernmental bodies, whose hosts are ordinary .org/.int
261
+ # names.
262
+ who.int: intergovernmental
263
+ un.org: intergovernmental
264
+ europa.eu: intergovernmental
265
+ oecd.org: intergovernmental
266
+ imf.org: intergovernmental
267
+ worldbank.org: intergovernmental
268
+ iaea.org: intergovernmental
269
+
270
+ # Standards bodies.
271
+ ietf.org: standards_body
272
+ rfc-editor.org: standards_body
273
+ w3.org: standards_body
274
+ iso.org: standards_body
275
+ iec.ch: standards_body
276
+ ieee.org: standards_body
277
+ unicode.org: standards_body
278
+ ecma-international.org: standards_body
279
+
280
+ # Peer-reviewed publishers and indexes.
281
+ nature.com: peer_reviewed_publisher
282
+ science.org: peer_reviewed_publisher
283
+ sciencemag.org: peer_reviewed_publisher
284
+ nejm.org: peer_reviewed_publisher
285
+ thelancet.com: peer_reviewed_publisher
286
+ bmj.com: peer_reviewed_publisher
287
+ cell.com: peer_reviewed_publisher
288
+ pnas.org: peer_reviewed_publisher
289
+ sciencedirect.com: peer_reviewed_publisher
290
+ springer.com: peer_reviewed_publisher
291
+ link.springer.com: peer_reviewed_publisher
292
+ onlinelibrary.wiley.com: peer_reviewed_publisher
293
+ wiley.com: peer_reviewed_publisher
294
+ tandfonline.com: peer_reviewed_publisher
295
+ sagepub.com: peer_reviewed_publisher
296
+ acm.org: peer_reviewed_publisher
297
+ aps.org: peer_reviewed_publisher
298
+ acs.org: peer_reviewed_publisher
299
+ plos.org: peer_reviewed_publisher
300
+ frontiersin.org: peer_reviewed_publisher
301
+ mdpi.com: peer_reviewed_publisher
302
+ jstor.org: peer_reviewed_publisher
303
+ pubmed.ncbi.nlm.nih.gov: peer_reviewed_publisher
304
+
305
+ # Preprint servers and repositories -- not peer reviewed.
306
+ arxiv.org: preprint_server
307
+ biorxiv.org: preprint_server
308
+ medrxiv.org: preprint_server
309
+ chemrxiv.org: preprint_server
310
+ ssrn.com: preprint_server
311
+ papers.ssrn.com: preprint_server
312
+ osf.io: preprint_server
313
+ researchsquare.com: preprint_server
314
+ semanticscholar.org: preprint_server
315
+
316
+ # News organisations with a correction policy and a masthead.
317
+ # An ALLOWLIST, because "news site" is not a property of a
318
+ # domain suffix and the alternative is scoring every .com that
319
+ # publishes articles.
320
+ reuters.com: established_news
321
+ apnews.com: established_news
322
+ bbc.com: established_news
323
+ bbc.co.uk: established_news
324
+ ft.com: established_news
325
+ economist.com: established_news
326
+ nytimes.com: established_news
327
+ washingtonpost.com: established_news
328
+ wsj.com: established_news
329
+ theguardian.com: established_news
330
+ npr.org: established_news
331
+ pbs.org: established_news
332
+ bloomberg.com: established_news
333
+ nikkei.com: established_news
334
+ afp.com: established_news
335
+ dw.com: established_news
336
+
337
+ # Tertiary references -- they summarise sources rather than
338
+ # being one.
339
+ wikipedia.org: reference_tertiary
340
+ wikimedia.org: reference_tertiary
341
+ wiktionary.org: reference_tertiary
342
+ britannica.com: reference_tertiary
343
+ org: generic_org
344
+
345
+ # Blog and newsletter platforms: the host says nothing about
346
+ # the author.
347
+ medium.com: blog_platform
348
+ substack.com: blog_platform
349
+ wordpress.com: blog_platform
350
+ blogspot.com: blog_platform
351
+ blogger.com: blog_platform
352
+ tumblr.com: blog_platform
353
+ wixsite.com: blog_platform
354
+ ghost.io: blog_platform
355
+ reddit.com: forum_qa
356
+ quora.com: forum_qa
357
+
358
+ # Forums and Q&A. Often correct, never attributable.
359
+ stackexchange.com: forum_qa
360
+ stackoverflow.com: forum_qa
361
+ news.ycombinator.com: forum_qa
362
+ 4chan.org: content_farm
363
+
364
+ # Social media. Speculation and unattributed claims travel here
365
+ # fastest, which is the whole reason a claim needs grounding
366
+ # elsewhere.
367
+ x.com: social_media
368
+ twitter.com: social_media
369
+ facebook.com: social_media
370
+ instagram.com: social_media
371
+ tiktok.com: social_media
372
+ threads.net: social_media
373
+ linkedin.com: social_media
374
+ mastodon.social: social_media
375
+ bsky.app: social_media
376
+ youtube.com: social_media
377
+ vk.com: social_media
378
+ weibo.com: social_media
379
+ t.me: social_media
380
+
381
+ # Aggregators that republish without attribution, and image
382
+ # boards with no text to ground anything in. The measured
383
+ # case: a Pinterest pin scored similarity 1.0 on a Nobel
384
+ # Prize claim.
385
+ pinterest.com: content_farm
386
+ answers.com: content_farm
387
+ ehow.com: content_farm
388
+ scribd.com: content_farm
389
+ coursehero.com: content_farm
390
+ chegg.com: content_farm
391
+
392
+ # How far a stated reason may move a source's authority score, in either
393
+ # direction.
394
+ authority_adjustment_cap: 0.15
395
+
396
+ # ======================================================================
397
+ # The sources/ artifact
398
+ # ======================================================================
399
+
400
+ # Whether the sources/ artifact keeps the fetched page text alongside the
401
+ # scores, or the scores alone.
402
+ persist_source_text: true
403
+
404
+ # ======================================================================
405
+ # Scholarly authority (OpenAlex)
406
+ # ======================================================================
407
+
408
+ # Whether the OpenAlex lookup runs at all. Off ships no outbound
409
+ # scholarly requests.
410
+ scholar_lookup: false
411
+
412
+ # The OpenAlex base URL.
413
+ scholar_api_url: https://api.openalex.org
414
+
415
+ # Per-request timeout, in seconds.
416
+ scholar_timeout_s: 8.0
417
+
418
+ # Retries per request; total attempts is this plus one.
419
+ scholar_max_retries: 2
420
+
421
+ # How long a lookup is cached in-process, in seconds.
422
+ scholar_cache_ttl_s: 900
423
+
424
+ # Sent as OpenAlex's `mailto` parameter when non-empty, which is their
425
+ # polite-pool convention. Blank sends no address and is the shipped value:
426
+ # an address here leaves the machine on every lookup.
427
+ scholar_mailto: ''
428
+
429
+ # The three weights below split one score and a settings.json
430
+ # `source_scoring` block can override each. They are expected to sum to 1.
431
+ scholar_venue_weight: 0.4
432
+ scholar_citation_weight: 0.4
433
+ scholar_author_weight: 0.2
434
+
435
+ # OpenAlex location type -> venue credit. `unknown` is the fallback for an
436
+ # unrecognised type, and a work with no location at all takes
437
+ # `repository`.
438
+ scholar_venue_credit:
439
+ journal: 1.0
440
+ conference: 1.0
441
+ book series: 0.85
442
+ repository: 0.55 # arXiv, bioRxiv, institutional repositories
443
+ unknown: 0.6
444
+
445
+ # The h-index at which author credit saturates.
446
+ scholar_h_saturation: 60
447
+
448
+ # Below this many works in a field-year cohort, the citation percentile is
449
+ # not trusted.
450
+ scholar_min_cohort_size: 200
451
+
452
+ # A work younger than this has not had time to accrue citations, so the
453
+ # citation term is not held against it.
454
+ scholar_min_citation_age_days: 60
455
+
456
+ # The authority a retracted work is given outright, whatever else it
457
+ # scores.
458
+ scholar_retracted_authority: 0.05
459
+
460
+ # ======================================================================
461
+ # Reasoning effort
462
+ # ======================================================================
463
+
464
+ # Reasoning effort when nothing more specific speaks: --effort >
465
+ # settings.json `effort` > this, with settings.json `tui.effort` winning
466
+ # inside the TUI. null sends no effort at all.
467
+ default_effort: high
468
+
469
+ # Known effort levels per model, for providers whose API exposes no
470
+ # capability query. An EMPTY list means the model accepts none, which is
471
+ # different from being absent -- absent falls through to the list below.
472
+ model_effort_levels:
473
+ gpt-4o: []
474
+ gpt-4o-mini: []
475
+ gpt-4.1: []
476
+ gpt-4.1-mini: []
477
+ gpt-4.1-nano: []
478
+ gpt-3.5-turbo: []
479
+
480
+ # Used for a model with no entry above.
481
+ default_effort_levels:
482
+ - low
483
+ - medium
484
+ - high
485
+ - xhigh
486
+ - max
487
+ - ultra
488
+
489
+ # Effort level -> Google thinking_budget in tokens. -1 hands the choice to
490
+ # the model.
491
+ google_thinking_budgets:
492
+ low: 2048
493
+ medium: 8192
494
+ high: 16384
495
+ xhigh: 24576
496
+ ultra: 32768
497
+ max: -1
498
+
499
+ # ======================================================================
500
+ # Database
501
+ # ======================================================================
502
+
503
+ # The SQLite file behind the conversation database. APP_DB_PATH overrides;
504
+ # the npm launcher points it at ~/.config/venastine so state is global
505
+ # while artifacts stay local.
506
+ db_path: app.db
507
+
508
+ # ======================================================================
509
+ # File-ops workspace
510
+ # ======================================================================
511
+
512
+ # The file tools' read-write root, and a PERMISSION BOUNDARY: file_ops
513
+ # auto-approves writes inside it. AGENT_WORKSPACE overrides, and naming it
514
+ # also makes the resolved workspace the project path -- so pointing it at a
515
+ # home directory would auto-approve writes there for every project. Writing
516
+ # the path HERE moves the workspace alone; the key below moves the project
517
+ # with it.
518
+ workspace_dir: ./workspace
519
+
520
+ # Whether that workspace is also the PROJECT: what workspace trust asks about,
521
+ # which .venastine/ supplies settings and agents, where /init scaffolds, and
522
+ # what project-scoped memories belong to. Naming AGENT_WORKSPACE has always
523
+ # done this; the key is the same statement made in the file, for the reader
524
+ # who has no variable to set. Either route suffices, and neither is needed to
525
+ # work inside a project you launched from -- that is already the project.
526
+ workspace_is_project: false
527
+
528
+ # Hard reject before opening, in both directions (25 MB).
529
+ max_file_size_bytes: 25000000
530
+
531
+ # Per-read line ceiling. A larger `count` is clamped, with a note in the
532
+ # result rather than silently.
533
+ max_read_lines: 500
534
+
535
+ # Per-read character ceiling, the truncation point for sandboxed stdout and
536
+ # stderr, and the bound on an MCP tool's whole result.
537
+ max_read_chars: 50000
538
+
539
+ # ROADMAP_v3 §81 (IM7). The largest image `view_image` attaches, in bytes of
540
+ # the file (3.75 MiB). Base64 inflates it by 4/3, so the encoded payload stays
541
+ # under 5 MiB -- the smallest per-image limit of the wires that carry it --
542
+ # and the image is resent with every request for as long as it stays in view.
543
+ max_image_bytes: 3932160
544
+
545
+ # ======================================================================
546
+ # /init
547
+ # ======================================================================
548
+
549
+ # The agent /init runs.
550
+ initializer_agent: initializer
551
+
552
+ # Most characters read_project_doc returns per file.
553
+ init_read_chars: 20000
554
+
555
+ # Step ceiling for the /init run when its agent names none.
556
+ init_max_steps: 12
557
+
558
+ # Largest existing AGENTS.md /init will revise, in characters. Above it
559
+ # /init stops before any model call: the reply replaces the whole file.
560
+ init_max_hub_chars: 1000000
561
+
562
+ # Most lines of the proposed diff /init prints before asking.
563
+ init_diff_shown_lines: 2000
564
+
565
+ # ======================================================================
566
+ # MCP teardown
567
+ # ======================================================================
568
+
569
+ # Seconds allowed for MCP session teardown at shutdown before the harness
570
+ # stops waiting.
571
+ teardown_budget_s: 10.0
572
+
573
+ # ======================================================================
574
+ # MCP results
575
+ # ======================================================================
576
+
577
+ # Largest single server-sent event, in bytes, a Streamable HTTP ("http")
578
+ # MCP server may stream back. A bigger one fails that tool call with an
579
+ # error naming the limit; the session survives. An answer sent as plain
580
+ # JSON is not an event and is not bounded by this. Legacy "sse" servers
581
+ # keep the MCP SDK's own 1 MiB, which it gives no way to change. 16 MiB.
582
+ # What reaches the model is bounded separately, by max_read_chars.
583
+ mcp_max_event_bytes: 16777216
584
+
585
+ # ======================================================================
586
+ # Shell and sandbox
587
+ # ======================================================================
588
+
589
+ # The shell the sandbox runs commands through. EMPTY means auto-detect,
590
+ # which is the shipped value. AGENT_SHELL overrides.
591
+ shell_binary: ''
592
+
593
+ # AUTHORITY -- part of the frozen security posture. Enables the weak
594
+ # host-subprocess backend, which is unbounded code on the host. Bound once
595
+ # at first read and frozen, so no tool call, settings file, environment
596
+ # variable or slash command can move it.
597
+ allow_insecure_sandbox_fallback: false
598
+
599
+ # AUTHORITY -- runs that fallback with no per-run prompt. The pair above and
600
+ # here reads as worse than either alone. Honoured under `tiered` and
601
+ # `contained`; under `always` every command still asks, this one included.
602
+ auto_approve_sandbox_fallback: false
603
+
604
+ # AUTHORITY -- part of the frozen security posture. Lets the agent ask
605
+ # for a command to run in WSL (ROADMAP_v3 §49, slice 3). It is NOT a
606
+ # weaker container: a command there reaches this harness's own
607
+ # config.yaml and ~/.config, gets no memory, CPU or process limit, and
608
+ # can start Windows programs with your full authority -- Windows
609
+ # interop is a kernel feature there and survives an emptied
610
+ # environment. Only a read-only command whose every argument is inside
611
+ # the workspace runs there without asking; everything else meets a
612
+ # prompt under `tiered` and `contained` alike. Shown on the startup
613
+ # banner and the TUI badge whenever it is on.
614
+ allow_wsl_backend: false
615
+
616
+ # Which WSL distribution the backend runs in. EMPTY means the first one
617
+ # `wsl.exe -l -q` lists, which is WSL's own default. A name that is not
618
+ # installed is refused with the installed names, rather than passed to
619
+ # `wsl.exe` -- which answers an unknown distro by exiting 4294967295
620
+ # and writing its complaint to stdout in UTF-16, so the failure would
621
+ # read as the command's rather than the configuration's.
622
+ wsl_distro: ''
623
+
624
+ # AUTHORITY -- part of the frozen security posture. Lets the agent ask
625
+ # for a command to run on the remote host configured below (ROADMAP_v3
626
+ # §49, slice 4). A remote host is not a sandbox and not a weaker one: it
627
+ # is a machine this harness cannot look at. It gets no memory, CPU or
628
+ # process limit -- those belong to the remote -- and the credentials it
629
+ # uses are ones you issued, not ones this harness controls.
630
+ # NOTHING runs there without asking you first, not even a read-only
631
+ # command: "inside the workspace" is a question about a filesystem this
632
+ # process cannot resolve, so it is not asked. Shown on the startup
633
+ # banner and the TUI badge whenever it is on.
634
+ allow_ssh_backend: false
635
+
636
+ # The one remote host the SSH backend reaches. The agent asks for
637
+ # `backend: "ssh"` and gets THIS host; it never names a host itself,
638
+ # for the reason `wsl_distro` is not the agent's either -- which machine
639
+ # this harness may reach is your question, and which command needs it is
640
+ # the agent's.
641
+ ssh_host: ''
642
+ ssh_user: ''
643
+ ssh_port: 22
644
+
645
+ # The private key to authenticate with. EMPTY offers whatever a running
646
+ # ssh-agent holds. This harness NEVER asks for, holds or stores a
647
+ # passphrase: if the key is encrypted, load it into an agent with
648
+ # `ssh-add` first. Measured, and the reason the backend passes
649
+ # BatchMode=yes: without it, an encrypted key with no agent makes ssh
650
+ # wait forever for a passphrase on a terminal this process does not own.
651
+ ssh_identity_file: ''
652
+
653
+ # Where a command runs on the remote. REQUIRED when the backend is on,
654
+ # and deliberately not defaulted to the login home: a command that runs
655
+ # somewhere nobody named is the failure this backend is most able to
656
+ # cause, and nothing here can see where it landed.
657
+ ssh_remote_workspace: ''
658
+
659
+ # The remote's host key, PINNED. Run `ssh-keyscan -p <port> <host>` and
660
+ # paste its output here (the `#` banner line is ignored). A host whose
661
+ # key does not match this is refused -- not prompted about, because a
662
+ # prompt on first use is a question a headless run has nobody to ask,
663
+ # and because a key that CHANGES is exactly the case worth refusing.
664
+ ssh_host_key: ''
665
+
666
+ # Which `ssh` program to run. EMPTY prefers the operating system's own
667
+ # (%SYSTEMROOT%\System32\OpenSSH\ssh.exe on Windows) and falls back to
668
+ # PATH. Not PATH first: on the machine this was built, PATH resolves to
669
+ # a git-for-Windows build while the OS ships its own, and the two report
670
+ # different text for the same failure.
671
+ ssh_binary: ''
672
+
673
+ # AUTHORITY -- THE gate for shell approval, and part of the frozen posture.
674
+ # always -- every command asks
675
+ # tiered -- read-only commands from inert_commands, every argument
676
+ # inside the workspace, run unprompted; every other command
677
+ # asks, including anything that can run code
678
+ # contained -- anything that runs in the container without network runs
679
+ # unprompted, code included; reads outside the workspace and
680
+ # network commands still ask
681
+ # never -- nothing asks
682
+ # An unknown value raises at startup rather than falling back, because one
683
+ # direction of a fallback asks about everything and the other about
684
+ # nothing, and a typo cannot pick. Rejected by name from settings.json at
685
+ # every tier: a cloned repo could otherwise set `never`.
686
+ # Shell approval is governed solely here: `tool_approvals` deliberately has
687
+ # no `shell` key, so there is no second switch that can disagree with this.
688
+ shell_approval_mode: tiered
689
+
690
+ # The image sandboxed commands run in, under Docker or Podman (whichever
691
+ # runs the sandbox -- ROADMAP_v3 §49, SS22). Fully qualified so Podman
692
+ # resolves it without a short-name alias (SS23). AGENT_SANDBOX_IMAGE
693
+ # overrides.
694
+ sandbox_docker_image: docker.io/library/python:3.13-slim
695
+
696
+ # Wall-clock ceiling for one sandboxed command.
697
+ sandbox_timeout_seconds: 120
698
+
699
+ # Memory ceiling for the sandbox, in MB.
700
+ sandbox_memory_mb: 2048
701
+
702
+ # CPU-time ceiling for the sandbox, in seconds.
703
+ sandbox_cpu_seconds: 30
704
+
705
+ # Process ceiling for the sandbox.
706
+ sandbox_max_pids: 200
707
+
708
+ # Background and monitor shell sessions (ROADMAP_v3 §49, SS12-SS13).
709
+ #
710
+ # The longest a session may run. An agent asking for more is started with
711
+ # this and told so -- never refused.
712
+ shell_session_timeout_cap_s: 3600
713
+
714
+ # How long an INTERACTIVE shell may sit with nothing typed into it
715
+ # before it is closed (ROADMAP_v3 §49, SS25). Unlike a background
716
+ # command, an interactive session does not block your prompt, so this is
717
+ # the only thing that stops a forgotten shell holding a container open
718
+ # until its timeout cap. Measured from the last input, not the last
719
+ # output: a program printing to itself is still one nobody is using.
720
+ shell_session_idle_timeout_s: 600
721
+
722
+ # How many sessions of any kind may be live at once, counted across the
723
+ # main agent and every subagent. Each is its own container under the
724
+ # memory ceiling above. An interactive shell counts here -- it holds a
725
+ # container like any other -- even though it does not block your prompt.
726
+ shell_session_max_live: 4
727
+
728
+ # How many times in a row finished sessions may wake the agent with no
729
+ # message from you. Past it, waking stops, the prompt unblocks, and the
730
+ # results wait for your next message.
731
+ shell_session_max_consecutive_wakes: 10
732
+
733
+ # How much of a session's output is kept, in memory only and never on
734
+ # disk: its first characters and its most recent ones. The middle is
735
+ # dropped, and the agent is told where.
736
+ shell_session_output_head_chars: 10000
737
+ shell_session_output_tail_chars: 190000
738
+
739
+ # ======================================================================
740
+ # Output redaction and tool isolation
741
+ # ======================================================================
742
+
743
+ # AUTHORITY -- the master switch for pattern-based redaction of everything
744
+ # leaving a tool, and part of the frozen posture. There is deliberately no
745
+ # settings.json key. VENASTINE_REDACT_OFF can only ever turn redaction
746
+ # OFF for a run, never on, and is bound at the same moment as this.
747
+ redact_tool_outputs: true
748
+
749
+ # Wall clock for one BUDGET_COMPUTE tool call, and the CPU ceiling handed
750
+ # to the isolated child process that runs it.
751
+ tool_compute_timeout_s: 20
752
+
753
+ # First words that make a sandboxed command need the network. Anything not
754
+ # listed runs with networking off.
755
+ network_allowed_commands:
756
+ - pip
757
+ - pip3
758
+ - curl
759
+ - wget
760
+ - git
761
+ - npm
762
+ - yarn
763
+ - pnpm
764
+ - apt
765
+ - apt-get
766
+ - yum
767
+ - dnf
768
+ - brew
769
+ - cargo
770
+
771
+ # Read-only inspection commands eligible for the auto-approved inert tier
772
+ # under `shell_approval_mode: tiered`. Sound as a bare token list only
773
+ # because that tier executes argv with no shell, so the tokens ARE the
774
+ # arguments.
775
+ #
776
+ # WHAT BELONGS HERE, after batch 117 found two things that did not. A
777
+ # command qualifies only if it cannot write, and "cannot write" has to hold
778
+ # for its ARGUMENTS as well as its name:
779
+ #
780
+ # * A writing FLAG is guarded by `_DANGEROUS_FLAGS` in security/sandbox.py
781
+ # -- `tree -o FILE` and `date -s TIME` were inert with no entry there
782
+ # until batch 117, so the tier reported `writes=False` about a write.
783
+ # * A writing POSITIONAL cannot be guarded at all. `uniq IN OUT` writes to
784
+ # its second argument with no flag to catch, so `uniq` was REMOVED from
785
+ # this list rather than given an entry that could not work. Teaching the
786
+ # classifier which positions are outputs would make it a shell parser,
787
+ # which security/sandbox.py's own G2 argument forbids.
788
+ #
789
+ # The bound that still held throughout: `_escapes_workspace` reads every
790
+ # token after the first as a path, so a write aimed outside the workspace
791
+ # was refused regardless. What was wrong was the profile's claim, not the
792
+ # containment.
793
+ inert_commands:
794
+ - ls
795
+ - cat
796
+ - pwd
797
+ - echo
798
+ - grep
799
+ - wc
800
+ - head
801
+ - tail
802
+ - date
803
+ - whoami
804
+ - uname
805
+ - which
806
+ - where
807
+ - type
808
+ - file
809
+ - stat
810
+ - du
811
+ - df
812
+ - tree
813
+ - diff
814
+ - md5sum
815
+ - sha256sum
816
+
817
+ # ======================================================================
818
+ # Research grants and review
819
+ # ======================================================================
820
+
821
+ # Ceiling on granted tool calls in one run, across every grant.
822
+ max_granted_tool_calls: 150
823
+
824
+ # How long an attended approval waits for an answer before giving up on
825
+ # it.
826
+ attended_approval_timeout_s: 600
827
+
828
+ # Whether a finished research run is reviewed. A settings.json
829
+ # `research.subagent_review` outranks this; --no-review escapes it for one
830
+ # run.
831
+ subagent_review: false
832
+
833
+ # Findings kept from one review; the rest are dropped with a warning.
834
+ max_review_findings: 25
835
+
836
+ # Rounds a single finding may be refined before it is recorded as
837
+ # rejected.
838
+ max_review_refinements: 3
839
+
840
+ # ======================================================================
841
+ # Compaction
842
+ # ======================================================================
843
+
844
+ # How much of the model's context window a thread may fill before
845
+ # compaction folds it. What the fraction really names is the HEADROOM --
846
+ # the remainder, which the step after the trigger fires has to fit inside,
847
+ # because nothing in the harness recovers from a prompt that overflows the
848
+ # window. A bare share gets that wrong at both ends of the roster: 0.10 of
849
+ # 1M is 100k and 0.10 of 64k is 6.4k, while ONE capped tool read is 12,500
850
+ # proxy tokens. Hence the two clamps below.
851
+ compaction_trigger_fraction: 0.90
852
+
853
+ # The headroom never shrinks below this, however small the window. Sized
854
+ # from max_read_chars (50,000 chars = 12,500 proxy tokens, the largest a
855
+ # single bounded read can return) plus the assistant turn that asked for
856
+ # it. Binds under a ~160k window and nowhere above one, so a 262k or 1M
857
+ # thread gets exactly the fraction above and a 64k thread keeps a usable
858
+ # margin instead of 6.4k.
859
+ compaction_min_headroom_tokens: 16000
860
+
861
+ # ...and never grows past this share of the window, which is what stops
862
+ # the floor above from eating a small window whole -- 16k of a 32k window
863
+ # is half of it. This is the clamp that keeps the trigger positive and
864
+ # above keep_recent_tokens at the bottom of the range.
865
+ compaction_max_headroom_fraction: 0.25
866
+
867
+ # The trigger used when NO MODEL IS IN SCOPE. A settings.json
868
+ # `compaction.trigger_tokens` overrides it.
869
+ compaction_trigger_tokens: 40000
870
+
871
+ # The early warning fires this many tokens BEFORE the trigger. Must stay
872
+ # strictly below the trigger, or the warning arrives after the thing it
873
+ # warns about; the loader refuses a pair that cannot work.
874
+ compaction_warning_margin_tokens: 8000
875
+
876
+ # Recent conversation held out of a fold verbatim.
877
+ compaction_keep_recent_tokens: 4000
878
+
879
+ # Recent turns held out of a fold verbatim, whichever bound binds first.
880
+ compaction_keep_recent_turns: 3
881
+
882
+ # The share of the trigger that pinned content may occupy, so a pin cannot
883
+ # force permanent compaction.
884
+ pin_max_trigger_fraction: 0.5
885
+
886
+ # Default fold strength: one of the keys of `compaction_target_ratios`.
887
+ compaction_strength: 3
888
+
889
+ # Attempts at one fold before it is abandoned.
890
+ compaction_max_retries: 2
891
+
892
+ # Strength -> the fraction of the original character count a fold aims
893
+ # for. INTEGER keys, and they are the closed set a settings.json
894
+ # `compaction.strength` is checked against.
895
+ compaction_target_ratios:
896
+ 1: 0.4
897
+ 2: 0.25
898
+ 3: 0.15
899
+ 4: 0.1
900
+ 5: 0.05
901
+
902
+ # How far over target a fold may land before it is retried.
903
+ compaction_ratio_tolerance: 0.5
904
+
905
+ # Default strategy.
906
+ # chain -- fold the previous summary together with the new span
907
+ # rederive -- re-summarise the whole thread from the archive
908
+ compaction_strategy: chain
909
+
910
+ # The closed vocabulary `compaction_strategy` and any settings.json
911
+ # `compaction.strategy` are checked against.
912
+ compaction_strategies:
913
+ - rederive
914
+ - chain
915
+
916
+ # Memories injected into a prompt at once. 0 disables the `remember` tool
917
+ # rather than injecting nothing.
918
+ max_injected_memories: 50
919
+
920
+ # ======================================================================
921
+ # Catalog text
922
+ # ======================================================================
923
+
924
+ # Cap on a skill's or agent's `name` and `description` -- the two strings
925
+ # that reach every run's system prompt from a .md file with no tool call
926
+ # and no further consent. The newline collapse that comes with it matters
927
+ # more than the number.
928
+ max_catalog_text_chars: 300
929
+
930
+ # ======================================================================
931
+ # Summaries, references and the checklist
932
+ # ======================================================================
933
+
934
+ # The agent that does the summarising, for both folds and /summary.
935
+ compactor_agent: compactor
936
+
937
+ # How long a whole-thread summary may be, in characters. ABSOLUTE rather
938
+ # than a ratio: this summary is injected into every turn of a REFERENCING
939
+ # thread, where nothing it replaces bounds it.
940
+ summary_target_chars: 2000
941
+
942
+ # Referenced threads attachable to one thread at once. REFUSES rather than
943
+ # dropping the oldest, because a reference is something a person named.
944
+ max_injected_refs: 3
945
+
946
+ # The checklist vocabulary, and the enum in todo_write's own schema. A
947
+ # plain list rather than an enum so a list stored under an older
948
+ # vocabulary reads back as data instead of raising.
949
+ todo_statuses:
950
+ - pending
951
+ - in_progress
952
+ - completed
953
+
954
+ # Checklist ceiling. REFUSES rather than truncating: a list silently cut
955
+ # would leave the model believing it had recorded work it has forgotten.
956
+ max_todo_items: 50
957
+
958
+ # Research passes compact only this far from the model's actual context
959
+ # window -- a safety net against a hard provider error mid-pipeline, not a
960
+ # working-set policy.
961
+ compaction_pipeline_backstop_tokens: 20000
962
+
963
+ # ======================================================================
964
+ # Context windows
965
+ # ======================================================================
966
+
967
+ # Model -> input window, in tokens. A FALLBACK now, not the only source:
968
+ # core/client.py queries the provider where the SDK exposes it, and
969
+ # core/model_windows.py holds the user's own `/window` answer, which
970
+ # outranks both. A miss here warns once per model.
971
+ model_context_windows:
972
+ claude-opus-5: 1000000
973
+ claude-sonnet-5: 1000000
974
+ claude-fable-5: 1000000
975
+ claude-opus-4-8: 1000000
976
+ claude-opus-4-7: 1000000
977
+ claude-opus-4-6: 1000000
978
+ claude-sonnet-4-6: 1000000
979
+ claude-haiku-4-5: 200000
980
+ gpt-5.1: 400000
981
+ gemini-2.5-pro: 1000000
982
+ qwen3.8-max-preview: 983616
983
+
984
+ # For a model absent from the table above and unqueryable. Logged at
985
+ # WARNING once per model, because a wrong window now decides when every
986
+ # thread folds.
987
+ default_context_window: 256000
988
+
989
+ # ======================================================================
990
+ # Connecting a model
991
+ # ======================================================================
992
+
993
+ # The Hugging Face OAuth app /connect huggingface signs in through, by its
994
+ # client id -- a PUBLIC value, not a secret. This one is the project's own
995
+ # app, registered without a secret, with the device code flow and the scopes
996
+ # `openid profile inference-api` (ROADMAP_v3 §79, HD5). Another app's id
997
+ # signs in through that app instead; empty hides the sign-in and leaves a
998
+ # pasted token working.
999
+ hf_oauth_client_id: "3a823316-767d-4abe-8e55-6c0354ce2c27"
1000
+
1001
+ # ======================================================================
1002
+ # Tool permissions and approvals
1003
+ # ======================================================================
1004
+
1005
+ # AUTHORITY -- whether each registered tool may be called AT ALL.
1006
+ # is_tool_allowed() reads this before any context or approval logic and a
1007
+ # tool context can never widen it, so a false here cannot be re-enabled at
1008
+ # runtime by an agent, a skill or a settings file -- only by editing this
1009
+ # file. read / view_image / write / edit / shell ship false for that reason,
1010
+ # and so do the five background-session tools after shell: a session is a
1011
+ # shell command that keeps running, and enabling one without the others is
1012
+ # allowed but rarely useful. view_image follows read because it reads a file
1013
+ # off disk the same way; it also needs a provider marked `accepts_images` in
1014
+ # providers.json before it is offered at all (ROADMAP_v3 §81, IM6).
1015
+ # Every registered tool must appear in BOTH tables or the harness refuses
1016
+ # to start (D24).
1017
+ tool_permissions:
1018
+ web_search: true
1019
+ fetch_url: true
1020
+ get_time: true
1021
+ arxiv_search: true
1022
+ symbolic_math: true
1023
+ linear_algebra: true
1024
+ probability_stats: true
1025
+ discrete_math: true
1026
+ logic: true
1027
+ geometry: true
1028
+ read: false
1029
+ view_image: false
1030
+ write: false
1031
+ edit: false
1032
+ shell: false
1033
+ shell_background: false
1034
+ shell_monitor: false
1035
+ shell_interactive: false
1036
+ shell_input: false
1037
+ shell_sessions: false
1038
+ shell_output: false
1039
+ shell_kill: false
1040
+ load_skill: true
1041
+ spawn_subagent: true
1042
+ pin: true
1043
+ unpin: true
1044
+ remember: true
1045
+ read_project_doc: true
1046
+ write_project_doc: true
1047
+ ask_user: true
1048
+ todo_write: true
1049
+
1050
+ # AUTHORITY -- whether each tool needs a human yes before it runs. Approval ORs
1051
+ # across every layer, so a true here is a one-way ratchet that can only
1052
+ # add prompts. `shell`, `shell_background`, `shell_monitor` and
1053
+ # `shell_interactive` are deliberately absent: their approval is governed
1054
+ # solely by `shell_approval_mode` above -- there is no second switch, so
1055
+ # there is nothing here that can disagree with it. Listing, reading and
1056
+ # stopping a session ask nothing: they act only on this conversation's own
1057
+ # sessions. `shell_input` is here and ships false because approving the
1058
+ # shell approved what you type into it (SS29) -- set it true to be asked
1059
+ # about every line instead.
1060
+ # A tool gated here is not merely denied where nothing can ask -- it stops
1061
+ # being advertised at all, which is why ask_user, pin and todo_write are
1062
+ # ungated.
1063
+ tool_approvals:
1064
+ web_search: false
1065
+ fetch_url: false
1066
+ get_time: false
1067
+ arxiv_search: false
1068
+ symbolic_math: false
1069
+ linear_algebra: false
1070
+ probability_stats: false
1071
+ discrete_math: false
1072
+ logic: false
1073
+ geometry: false
1074
+ read: false
1075
+ view_image: false
1076
+ write: false
1077
+ edit: false
1078
+ shell_input: false
1079
+ shell_sessions: false
1080
+ shell_output: false
1081
+ shell_kill: false
1082
+ load_skill: false
1083
+ spawn_subagent: true
1084
+ pin: false
1085
+ unpin: false
1086
+ remember: true
1087
+ read_project_doc: false
1088
+ write_project_doc: true
1089
+ ask_user: false
1090
+ todo_write: false