@yahyahammad/venastine 0.3.8 → 0.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,464 +1,464 @@
1
- """
2
- tools/builtin/project_docs.py
3
-
4
- ROADMAP_v2 §24: the two narrowly-scoped file tools `/init` runs on --
5
- `read_project_doc` (I2) and `write_project_doc` (I1).
6
-
7
- WHY NOT `read` AND `write`. Both are `False` in config.ToolPermissions, and
8
- that is not a default anyone can change: is_tool_allowed() reads the
9
- dataclass directly, settings.json has no `permissions` section (and
10
- _KNOWN_SETTINGS *raises* on an unknown key), and D14 forbids a ToolContext
11
- widening anything -- the global check runs first and unconditionally. So
12
- registry.dispatch("write", ...) raises ToolCallDenied BEFORE the
13
- approval_callback is ever consulted, for every user, out of the box.
14
-
15
- The two ways out were flipping those globals or scoping new tools. Flipping
16
- `write` hands the model unprompted write access anywhere inside
17
- WORKSPACE_DIR permanently, and flipping `read` hands every agent and all ten
18
- research passes file-read access by default -- a standing posture change to
19
- serve one command. These tools instead do exactly what /init needs and
20
- nothing else, so §24 adds no capability that outlives it.
21
-
22
- BOTH TOOLS LIVE IN ONE MODULE because they resolve paths against the same
23
- root. A second copy of that resolver is precisely how the two would drift
24
- apart -- the project's "fix at the producer" rule, applied before the bug.
25
-
26
- CONSEQUENCE, NAMED RATHER THAN DISCOVERED: a registered tool with permission
27
- True is advertised to EVERY run, not only to /init's. The initializer agent's
28
- `allowed_tools` narrows that agent; it does not stop plain chat or a research
29
- pass from calling `read_project_doc`. That is why the readable set here is
30
- DOCUMENTATION, not "text files": a doc/manifest allowlist plus a hard deny of
31
- `.venastine/`, `.git/`, `.env*` and `providers.json` means the most a
32
- prompt-injected research pass gains is the project's own README. Widening
33
- this to source files would quietly turn it into `read` with no approval gate.
34
-
35
- THE FIVE BUILD MANIFESTS, AND WHY THEY ARE ROOT-ONLY (#94). `setup.py`,
36
- `setup.cfg`, `Gemfile`, `pom.xml` and `build.gradle` were on neither list
37
- while `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `Makefile`
38
- and `Dockerfile` were on the first -- an incomplete enumeration rather than
39
- a judgement, and `requirements.txt` got in by accident through `.txt`. The
40
- manifest /init shows its agent advertised all of them as readable, so the
41
- agent spent steps out of a budget of twelve discovering that six were not.
42
-
43
- They are added BY EXACT NAME. That is what keeps the paragraph above true:
44
- `.py` never enters `_DOC_EXTENSIONS`, so `main.py`, `config.py` and
45
- `credentials.py` stay refused, and this is five filenames rather than a
46
- class of file. Driven, not assumed, before the decision was taken.
47
-
48
- They are also the first entries that match at the project ROOT only.
49
- Everything in `_DOC_FILENAMES` matches on basename at any depth, which is
50
- right for `packages/foo/package.json` in a monorepo and wrong for
51
- `src/vendor/setup.py` -- a vendored tree is where unreviewed third-party
52
- source lives, and it is the one place these five are not this project's own
53
- statement about itself.
54
-
55
- THE RESIDUAL THAT WAS STATED HERE IS CLOSED, and what is left of the
56
- paragraph is the part that was always the point. `check_output_policy` scans
57
- every value (#47), so `sk-ant-...`, `ghp_...`, `AKIA...` and a PEM header
58
- are redacted out of a result. A plaintext `<password>` element, a Gradle
59
- `password "..."` and a `user:token@host` URL were NOT, and those are the
60
- credential shapes that occur in exactly these five files -- so they were
61
- filed against the REDACTOR rather than fixed here, because a pattern added
62
- there redacts content out of every tool result in the harness and one added
63
- here would serve one tool.
64
-
65
- That filing is #167, closed 2026-08-23: `safety/policy_enforcement.py` now
66
- carries `_URL_USERINFO_RE`, `_XML_PASSWORD_RE` and `_ASSIGNMENT_RE`, whose
67
- `[ \t]` alternative is there for Gradle's space form specifically. All
68
- three shapes are redacted out of a `read_project_doc` result today, driven
69
- on all four file types, with a credential-free document passing through
70
- byte-identical as the control. This paragraph went on claiming the leak for
71
- seven weeks after the leak was fixed, which is why it now names the issue
72
- and the patterns: a security residual that reads as OPEN costs every later
73
- reader what it cost the reader who re-measured it (batch 146).
74
- """
75
-
76
- from __future__ import annotations
77
-
78
- import logging
79
- import os
80
- from typing import Optional
81
-
82
- import config
83
- from core import config_loader, workspace_trust
84
- from json_store import write_text_atomic
85
- from security import protected_paths
86
-
87
- logger = logging.getLogger(__name__)
88
-
89
- # Documentation and manifests. Deliberately NOT a general text-file list --
90
- # see the module docstring's consequence note.
91
- _DOC_EXTENSIONS = frozenset({".md", ".markdown", ".rst", ".txt"})
92
- _DOC_FILENAMES = frozenset({
93
- "pyproject.toml", "package.json", "cargo.toml", "go.mod",
94
- "makefile", "dockerfile", "license", "licence", "changelog", "notice",
95
- })
96
-
97
- # Build manifests, readable at the PROJECT ROOT ONLY -- see the docstring.
98
- # A nested copy is somebody else's source; the root copy is this project's
99
- # own statement about what it is.
100
- _ROOT_ONLY_FILENAMES = frozenset({
101
- "setup.py", "setup.cfg", "gemfile", "pom.xml", "build.gradle",
102
- })
103
-
104
- # Denied whatever the extension says. `.venastine/` can hold mcp.json and
105
- # settings.json; providers.json is where API keys live. check_output_policy
106
- # would redact a leaked key from the result, but a backstop is not a reason
107
- # to hand it the chance.
108
- #
109
- # `.venastine` is spelled ONCE, in security.protected_paths.PROTECTED_SEGMENTS
110
- # -- the same segment the file tools hard-refuse and the shell's approval
111
- # check always asks about -- and unioned in here rather than re-spelled, so
112
- # the one fact cannot drift between its three consumers.
113
- _DENIED_SEGMENTS = (protected_paths.PROTECTED_SEGMENTS
114
- | {".git", "node_modules", ".venv", "venv",
115
- "__pycache__", ".pytest_cache"})
116
-
117
- #: And compared the way the FILESYSTEM will compare them (batch 146),
118
- #: through the one spelling of the fold that `protected_segment` uses. This
119
- #: set unioned the segment list in and then compared it case-sensitively,
120
- #: so the two consumers of one fact disagreed about the only thing left to
121
- #: disagree about. `.VENASTINE/agents/foo.md` was a readable `.md`.
122
- _DENIED_FOLDED = protected_paths.folded_segments(_DENIED_SEGMENTS)
123
- _DENIED_FILENAMES = frozenset({"providers.json"})
124
-
125
- #: Re-exported so callers name one constant. The name lives in
126
- #: core/workspace_trust because the load-bearing fact about it is that a
127
- #: grant covers it (§44).
128
- HUB_FILENAME = workspace_trust.PROJECT_CONTEXT_FILENAME
129
-
130
-
131
- def _project_root() -> Optional[str]:
132
- """The resolved project path, or None when no session has been
133
- initialized. None is "there is no project", not "guess one" -- the same
134
- convention get_agents() and memories/manager.py follow."""
135
- return config_loader.get_project_path()
136
-
137
-
138
- def doc_path(project_path: str, name: str) -> str:
139
- """Where a document in the set lives. DERIVED FROM ITS NAME, never taken
140
- from a path parameter (I1).
141
-
142
- ONE JOIN SINCE §44, where this used to branch. I9 put the hub inside
143
- `.venastine/` so that the one file every agent reads sat inside the
144
- trust boundary. §44 keeps the boundary and moves the file: AGENTS.md is
145
- an ordinary committed root document, and workspace_trust.content_files()
146
- covers it explicitly. What that buys is a project you can share without
147
- your configuration and still have it make sense to whoever cloned it --
148
- where a hub in `.venastine/` meant sharing the repo without that
149
- directory shipped a set of documents pointing at a file that was not
150
- there.
151
-
152
- The function survives the simplification because the confinement is
153
- what it is FOR: a name from a fixed allowlist, resolved under the
154
- project, with no path parameter anywhere in the tool that calls it.
155
- """
156
- return os.path.join(project_path, name)
157
-
158
-
159
- def _resolve_in_project(root: str, user_path: str) -> Optional[str]:
160
- """Resolve *user_path* under *root* and return it only if it really
161
- lands inside.
162
-
163
- realpath BEFORE the containment test, so '..' segments and a symlink
164
- pointing outside the project are both caught -- file_ops' rule, and the
165
- reason it is a rule: a path that merely looks contained is not.
166
- """
167
- resolved = os.path.realpath(os.path.join(root, user_path))
168
- if resolved != root and not resolved.startswith(root + os.sep):
169
- return None
170
- return resolved
171
-
172
-
173
- def _is_readable_doc(root: str, resolved: str) -> bool:
174
- rel = os.path.relpath(resolved, root)
175
- parts = rel.split(os.sep)
176
- if any(segment.casefold() in _DENIED_FOLDED for segment in parts):
177
- return False
178
- name = os.path.basename(resolved).lower()
179
- if name in _DENIED_FILENAMES or name.startswith(".env"):
180
- return False
181
- if name in _DOC_FILENAMES:
182
- return True
183
- if name in _ROOT_ONLY_FILENAMES:
184
- # `parts` is the path relative to the project root, so a length of
185
- # one IS "at the root". Checked against the split rather than the
186
- # string, because os.altsep exists.
187
- return len(parts) == 1
188
- return os.path.splitext(name)[1] in _DOC_EXTENSIONS
189
-
190
-
191
- def is_readable_doc(project_path: str, user_path: str) -> bool:
192
- """This tool's own test, in public, for /init's manifest (#94).
193
-
194
- The manifest prints "Paths below are exactly what read_project_doc
195
- expects" over its listing, and used to decide what to list with a
196
- parallel test of its own. Nothing kept the two in step and they
197
- disagreed in both directions: six advertised paths the tool refused,
198
- and four it accepted that never appeared -- including every `.txt`
199
- document in a project, invisible because the manifest tested extensions
200
- and this module tests these.
201
-
202
- Exported rather than reimplemented, so the sentence is true by
203
- construction. The read path is unchanged: `read_run` still resolves and
204
- re-tests for itself, because a listing is not an authorization.
205
- """
206
- root = os.path.realpath(project_path)
207
- resolved = _resolve_in_project(root, user_path)
208
- return resolved is not None and _is_readable_doc(root, resolved)
209
-
210
-
211
- # ===========================================================================
212
- # ---- READ -----------------------------------------------------------------
213
- # ===========================================================================
214
-
215
- READ_TOOL_SCHEMA = {
216
- "name": "read_project_doc",
217
- "description": (
218
- "Read one of this project's documentation or manifest files, by the "
219
- "relative path given in the file listing you were shown. Markdown, "
220
- "text and manifest files only, and only within the project "
221
- f"directory. Returns at most {config.INIT_READ_CHARS} characters per "
222
- "call; use offset to continue through a longer file."
223
- ),
224
- "input_schema": {
225
- "type": "object",
226
- "properties": {
227
- "path": {
228
- "type": "string",
229
- "description": "Path relative to the project root, exactly "
230
- "as it appears in the file listing.",
231
- },
232
- "offset": {
233
- "type": "integer",
234
- "description": "Characters to skip before reading. Use the "
235
- "value suggested by a truncated response to "
236
- "read the next part of a long file.",
237
- },
238
- },
239
- "required": ["path"],
240
- },
241
- }
242
-
243
-
244
- def _skip(handle, offset: int) -> None:
245
- """Advance `offset` characters without holding them.
246
-
247
- f.seek() on a text stream takes an opaque cookie, not a character
248
- count, so an offset cannot simply be jumped to. Reading forward in
249
- bounded pieces keeps the memory ceiling at one piece instead of the
250
- whole prefix, which is the property #55 is about -- the cost is
251
- proportional to the offset, but the MEMORY is not.
252
- """
253
- remaining = offset
254
- while remaining > 0:
255
- piece = handle.read(min(remaining, config.INIT_READ_CHARS))
256
- if not piece:
257
- return
258
- remaining -= len(piece)
259
-
260
-
261
- def read_run(params: dict) -> dict:
262
- # params.get throughout, not params[]. tools/base.py carries the one
263
- # copy of why, under "WHAT A CALLABLE REGISTERED BELOW MAY RAISE": a
264
- # handler's exception IS contained, so the reason this is right is that
265
- # an error dict the model can read beats the generic wrapper it would
266
- # get -- not the turn-ending raise six comments in this directory used
267
- # to claim (batch 146).
268
- root = _project_root()
269
- if root is None:
270
- return {"error": "read_project_doc: no project directory has been "
271
- "resolved, so there is nothing to read."}
272
-
273
- user_path = (params.get("path") or "").strip()
274
- if not user_path:
275
- return {"error": "read_project_doc requires 'path'."}
276
-
277
- resolved = _resolve_in_project(root, user_path)
278
- if resolved is None:
279
- return {"error": f"read_project_doc: {user_path!r} resolves outside "
280
- f"the project directory."}
281
- if not _is_readable_doc(root, resolved):
282
- return {"error": f"read_project_doc: {user_path!r} is not a readable "
283
- f"project document. Documentation and manifest "
284
- f"files only."}
285
- if not os.path.isfile(resolved):
286
- return {"error": f"read_project_doc: no such file: {user_path}"}
287
-
288
- offset = params.get("offset") or 0
289
- if not isinstance(offset, int) or offset < 0:
290
- offset = 0
291
-
292
- # ROADMAP_v2 §31 (H7), #55. This used to be f.read() followed by
293
- # text[offset:offset + INIT_READ_CHARS], so returning 20,000
294
- # characters of a 30 MB document cost 60 MB of peak traced memory --
295
- # and cost it AGAIN on every page, because each call re-read the
296
- # whole file to slice a different part of it.
297
- #
298
- # A getsize guard like read_run's would be the obvious copy, and it
299
- # is the wrong one here: refusing a large document is not what this
300
- # tool is for -- I7 chose INIT_READ_CHARS deliberately so /init could
301
- # page through exactly such a document. Seeking to the offset bounds
302
- # the read AND removes the re-read, which a size check would not.
303
- #
304
- # One extra character is read to answer `truncated` without a second
305
- # pass. seek() counts characters in text mode only for utf-8-sig-free
306
- # streams, so the offset is walked rather than jumped: correctness
307
- # over cleverness, and it still holds one chunk rather than the file.
308
- try:
309
- with open(resolved, encoding="utf-8", errors="replace") as f:
310
- _skip(f, offset)
311
- chunk = f.read(config.INIT_READ_CHARS)
312
- more = f.read(1) != ""
313
- except OSError as e:
314
- logger.warning("read_project_doc failed for %s: %s", user_path, e)
315
- return {"error": f"Could not read {user_path}: {e}"}
316
-
317
- result = {"path": user_path, "content": chunk, "truncated": more}
318
- if result["truncated"]:
319
- # The continuation offset is IN the message, not merely implied by
320
- # the numbers. A model that has to compute where to resume usually
321
- # re-reads from zero and spends the budget twice.
322
- #
323
- # §31 (H7) dropped the total. It used to read `of {len(text)}`,
324
- # and len(text) was the whole file -- the very read this section
325
- # removed. A total could be faked from os.path.getsize, but that
326
- # is BYTES and this count is CHARACTERS, so on any document with
327
- # a non-ASCII character it would be a number that looks exact and
328
- # is not. Saying less is the honest option; the part that was
329
- # load-bearing -- where to resume -- is untouched.
330
- end = offset + len(chunk)
331
- result["message"] = (
332
- f"Read characters {offset}-{end}. "
333
- f"Call again with offset={end} to continue.")
334
- return result
335
-
336
-
337
- # ===========================================================================
338
- # ---- WRITE ----------------------------------------------------------------
339
- # ===========================================================================
340
-
341
- WRITE_TOOL_SCHEMA = {
342
- "name": "write_project_doc",
343
- "description": (
344
- "Write one of this project's standard documentation files. Takes the "
345
- "document's NAME, not a path -- the location is derived, so this "
346
- "cannot write anywhere else. Overwrites the named file, so the caller "
347
- "is expected to have shown the user what changes."
348
- ),
349
- "input_schema": {
350
- "type": "object",
351
- "properties": {
352
- "name": {
353
- "type": "string",
354
- "description": "One of the project's standard document names, "
355
- "e.g. AGENTS.md or ARCHITECTURE.md.",
356
- },
357
- "content": {
358
- "type": "string",
359
- "description": "Full markdown body of the document.",
360
- },
361
- },
362
- "required": ["name", "content"],
363
- },
364
- }
365
-
366
-
367
- def _known_doc_names() -> frozenset:
368
- """The allowlist IS the confinement (I1), so it is read from the one
369
- place that defines the sets rather than restated here. Imported lazily:
370
- tools/registry.py imports this module at import time, and project_init
371
- imports config, which would close a cycle."""
372
- from project_init.doc_sets import all_document_names
373
- return all_document_names()
374
-
375
-
376
- def approval_notice(params: dict, context) -> str:
377
- """What the approval prompt shows.
378
-
379
- The gate is only worth having if the prompt says what it is gating
380
- (remember.py's rule). Here that is the destination and the size --
381
- the content itself has already been shown as a diff by the caller,
382
- and repeating several kilobytes of markdown inside a modal would bury
383
- the one line that says which file is about to change.
384
- """
385
- root = _project_root()
386
- name = params.get("name") or HUB_FILENAME
387
- size = len(params.get("content") or "")
388
- if not root:
389
- return f"Create {name} ({size} characters)."
390
-
391
- # RESOLVED, so the consent can never name a file the bytes will not
392
- # land on (batch 146). `_project_root()` is already a realpath, so for
393
- # an ordinary document this is the same string the join produced and
394
- # the prompt is unchanged; where it differs, the difference IS the
395
- # thing the person needs to see.
396
- resolved = _resolve_in_project(root, name)
397
- if resolved is None:
398
- return (f"REFUSE {doc_path(root, name)} ({size} characters): that "
399
- f"name resolves outside the project, so write_project_doc "
400
- f"will not write it.")
401
- verb = "Overwrite" if os.path.exists(resolved) else "Create"
402
- return f"{verb} {resolved} ({size} characters)."
403
-
404
-
405
- def write_run(params: dict) -> dict:
406
- root = _project_root()
407
- if root is None:
408
- return {"error": "write_project_doc: no project directory has been "
409
- "resolved, so there is nowhere to write."}
410
-
411
- name = (params.get("name") or "").strip()
412
- known = _known_doc_names()
413
- if name not in known:
414
- # Not coerced to the hub, and not accepted as a path. An
415
- # unrecognised name is the one case where this tool could become a
416
- # general writer, so it fails loudly and lists what it accepts.
417
- return {"error": f"write_project_doc: {name!r} is not one of this "
418
- f"project's standard documents. Expected one of: "
419
- f"{', '.join(sorted(known))}."}
420
-
421
- content = params.get("content")
422
- if not isinstance(content, str) or not content.strip():
423
- return {"error": "write_project_doc requires non-empty 'content'."}
424
-
425
- encoded = content.encode("utf-8")
426
- if len(encoded) > config.MAX_FILE_SIZE_BYTES:
427
- return {"error": f"Content size ({len(encoded)} bytes) exceeds the "
428
- f"maximum writable size "
429
- f"({config.MAX_FILE_SIZE_BYTES} bytes)."}
430
-
431
- # RESOLVED BEFORE WRITING, which the read path has always done and this
432
- # one did not (batch 146). The module's invariant is that the
433
- # destination is derived from a name "so it cannot be aimed elsewhere",
434
- # and a document name that is a LINK aims it elsewhere: a cloned project
435
- # carrying `ARCHITECTURE.md -> ~/.bashrc` took the bytes to the link
436
- # target, under a consent that named the in-project path. git stores
437
- # symlinks natively, so the layout needs no privilege to arrive.
438
- #
439
- # An error rather than a coercion, in the sense the unknown-name branch
440
- # above means: a name that leaves the project is not one of this
441
- # project's documents.
442
- destination = doc_path(root, name)
443
- resolved = _resolve_in_project(root, name)
444
- if resolved is None:
445
- logger.warning("write_project_doc refused %s: resolves outside the "
446
- "project", destination)
447
- return {"error": f"write_project_doc: {name!r} resolves outside the "
448
- f"project directory, so it is not one of this "
449
- f"project's documents."}
450
-
451
- try:
452
- # REPLACES THE NAME RATHER THAN WRITING THROUGH IT, which closes the
453
- # half `realpath` cannot see: a hardlink is not a link to anything,
454
- # so the resolution above admits one. And `newline=""`, so the bytes
455
- # the model supplied are the bytes that land -- this tool is the one
456
- # write path in the harness reachable with no config edit, and its
457
- # whole purpose is to overwrite a document in place, under an
458
- # approval that was shown a diff of the lines that changed.
459
- write_text_atomic(resolved, content)
460
- except OSError as e:
461
- logger.warning("write_project_doc failed for %s: %s", resolved, e)
462
- return {"error": f"Could not write {resolved}: {e}"}
463
-
464
- return {"result": f"Wrote {len(content)} characters to {resolved}"}
1
+ """
2
+ tools/builtin/project_docs.py
3
+
4
+ ROADMAP_v2 §24: the two narrowly-scoped file tools `/init` runs on --
5
+ `read_project_doc` (I2) and `write_project_doc` (I1).
6
+
7
+ WHY NOT `read` AND `write`. Both are `False` in config.ToolPermissions, and
8
+ that is not a default anyone can change: is_tool_allowed() reads the
9
+ dataclass directly, settings.json has no `permissions` section (and
10
+ _KNOWN_SETTINGS *raises* on an unknown key), and D14 forbids a ToolContext
11
+ widening anything -- the global check runs first and unconditionally. So
12
+ registry.dispatch("write", ...) raises ToolCallDenied BEFORE the
13
+ approval_callback is ever consulted, for every user, out of the box.
14
+
15
+ The two ways out were flipping those globals or scoping new tools. Flipping
16
+ `write` hands the model unprompted write access anywhere inside
17
+ WORKSPACE_DIR permanently, and flipping `read` hands every agent and all ten
18
+ research passes file-read access by default -- a standing posture change to
19
+ serve one command. These tools instead do exactly what /init needs and
20
+ nothing else, so §24 adds no capability that outlives it.
21
+
22
+ BOTH TOOLS LIVE IN ONE MODULE because they resolve paths against the same
23
+ root. A second copy of that resolver is precisely how the two would drift
24
+ apart -- the project's "fix at the producer" rule, applied before the bug.
25
+
26
+ CONSEQUENCE, NAMED RATHER THAN DISCOVERED: a registered tool with permission
27
+ True is advertised to EVERY run, not only to /init's. The initializer agent's
28
+ `allowed_tools` narrows that agent; it does not stop plain chat or a research
29
+ pass from calling `read_project_doc`. That is why the readable set here is
30
+ DOCUMENTATION, not "text files": a doc/manifest allowlist plus a hard deny of
31
+ `.venastine/`, `.git/`, `.env*` and `providers.json` means the most a
32
+ prompt-injected research pass gains is the project's own README. Widening
33
+ this to source files would quietly turn it into `read` with no approval gate.
34
+
35
+ THE FIVE BUILD MANIFESTS, AND WHY THEY ARE ROOT-ONLY (#94). `setup.py`,
36
+ `setup.cfg`, `Gemfile`, `pom.xml` and `build.gradle` were on neither list
37
+ while `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `Makefile`
38
+ and `Dockerfile` were on the first -- an incomplete enumeration rather than
39
+ a judgement, and `requirements.txt` got in by accident through `.txt`. The
40
+ manifest /init shows its agent advertised all of them as readable, so the
41
+ agent spent steps out of a budget of twelve discovering that six were not.
42
+
43
+ They are added BY EXACT NAME. That is what keeps the paragraph above true:
44
+ `.py` never enters `_DOC_EXTENSIONS`, so `main.py`, `config.py` and
45
+ `credentials.py` stay refused, and this is five filenames rather than a
46
+ class of file. Driven, not assumed, before the decision was taken.
47
+
48
+ They are also the first entries that match at the project ROOT only.
49
+ Everything in `_DOC_FILENAMES` matches on basename at any depth, which is
50
+ right for `packages/foo/package.json` in a monorepo and wrong for
51
+ `src/vendor/setup.py` -- a vendored tree is where unreviewed third-party
52
+ source lives, and it is the one place these five are not this project's own
53
+ statement about itself.
54
+
55
+ THE RESIDUAL THAT WAS STATED HERE IS CLOSED, and what is left of the
56
+ paragraph is the part that was always the point. `check_output_policy` scans
57
+ every value (#47), so `sk-ant-...`, `ghp_...`, `AKIA...` and a PEM header
58
+ are redacted out of a result. A plaintext `<password>` element, a Gradle
59
+ `password "..."` and a `user:token@host` URL were NOT, and those are the
60
+ credential shapes that occur in exactly these five files -- so they were
61
+ filed against the REDACTOR rather than fixed here, because a pattern added
62
+ there redacts content out of every tool result in the harness and one added
63
+ here would serve one tool.
64
+
65
+ That filing is #167, closed 2026-08-23: `safety/policy_enforcement.py` now
66
+ carries `_URL_USERINFO_RE`, `_XML_PASSWORD_RE` and `_ASSIGNMENT_RE`, whose
67
+ `[ \t]` alternative is there for Gradle's space form specifically. All
68
+ three shapes are redacted out of a `read_project_doc` result today, driven
69
+ on all four file types, with a credential-free document passing through
70
+ byte-identical as the control. This paragraph went on claiming the leak for
71
+ seven weeks after the leak was fixed, which is why it now names the issue
72
+ and the patterns: a security residual that reads as OPEN costs every later
73
+ reader what it cost the reader who re-measured it (batch 146).
74
+ """
75
+
76
+ from __future__ import annotations
77
+
78
+ import logging
79
+ import os
80
+ from typing import Optional
81
+
82
+ import config
83
+ from core import config_loader, workspace_trust
84
+ from json_store import write_text_atomic
85
+ from security import protected_paths
86
+
87
+ logger = logging.getLogger(__name__)
88
+
89
+ # Documentation and manifests. Deliberately NOT a general text-file list --
90
+ # see the module docstring's consequence note.
91
+ _DOC_EXTENSIONS = frozenset({".md", ".markdown", ".rst", ".txt"})
92
+ _DOC_FILENAMES = frozenset({
93
+ "pyproject.toml", "package.json", "cargo.toml", "go.mod",
94
+ "makefile", "dockerfile", "license", "licence", "changelog", "notice",
95
+ })
96
+
97
+ # Build manifests, readable at the PROJECT ROOT ONLY -- see the docstring.
98
+ # A nested copy is somebody else's source; the root copy is this project's
99
+ # own statement about what it is.
100
+ _ROOT_ONLY_FILENAMES = frozenset({
101
+ "setup.py", "setup.cfg", "gemfile", "pom.xml", "build.gradle",
102
+ })
103
+
104
+ # Denied whatever the extension says. `.venastine/` can hold mcp.json and
105
+ # settings.json; providers.json is where API keys live. check_output_policy
106
+ # would redact a leaked key from the result, but a backstop is not a reason
107
+ # to hand it the chance.
108
+ #
109
+ # `.venastine` is spelled ONCE, in security.protected_paths.PROTECTED_SEGMENTS
110
+ # -- the same segment the file tools hard-refuse and the shell's approval
111
+ # check always asks about -- and unioned in here rather than re-spelled, so
112
+ # the one fact cannot drift between its three consumers.
113
+ _DENIED_SEGMENTS = (protected_paths.PROTECTED_SEGMENTS
114
+ | {".git", "node_modules", ".venv", "venv",
115
+ "__pycache__", ".pytest_cache"})
116
+
117
+ #: And compared the way the FILESYSTEM will compare them (batch 146),
118
+ #: through the one spelling of the fold that `protected_segment` uses. This
119
+ #: set unioned the segment list in and then compared it case-sensitively,
120
+ #: so the two consumers of one fact disagreed about the only thing left to
121
+ #: disagree about. `.VENASTINE/agents/foo.md` was a readable `.md`.
122
+ _DENIED_FOLDED = protected_paths.folded_segments(_DENIED_SEGMENTS)
123
+ _DENIED_FILENAMES = frozenset({"providers.json"})
124
+
125
+ #: Re-exported so callers name one constant. The name lives in
126
+ #: core/workspace_trust because the load-bearing fact about it is that a
127
+ #: grant covers it (§44).
128
+ HUB_FILENAME = workspace_trust.PROJECT_CONTEXT_FILENAME
129
+
130
+
131
+ def _project_root() -> Optional[str]:
132
+ """The resolved project path, or None when no session has been
133
+ initialized. None is "there is no project", not "guess one" -- the same
134
+ convention get_agents() and memories/manager.py follow."""
135
+ return config_loader.get_project_path()
136
+
137
+
138
+ def doc_path(project_path: str, name: str) -> str:
139
+ """Where a document in the set lives. DERIVED FROM ITS NAME, never taken
140
+ from a path parameter (I1).
141
+
142
+ ONE JOIN SINCE §44, where this used to branch. I9 put the hub inside
143
+ `.venastine/` so that the one file every agent reads sat inside the
144
+ trust boundary. §44 keeps the boundary and moves the file: AGENTS.md is
145
+ an ordinary committed root document, and workspace_trust.content_files()
146
+ covers it explicitly. What that buys is a project you can share without
147
+ your configuration and still have it make sense to whoever cloned it --
148
+ where a hub in `.venastine/` meant sharing the repo without that
149
+ directory shipped a set of documents pointing at a file that was not
150
+ there.
151
+
152
+ The function survives the simplification because the confinement is
153
+ what it is FOR: a name from a fixed allowlist, resolved under the
154
+ project, with no path parameter anywhere in the tool that calls it.
155
+ """
156
+ return os.path.join(project_path, name)
157
+
158
+
159
+ def _resolve_in_project(root: str, user_path: str) -> Optional[str]:
160
+ """Resolve *user_path* under *root* and return it only if it really
161
+ lands inside.
162
+
163
+ realpath BEFORE the containment test, so '..' segments and a symlink
164
+ pointing outside the project are both caught -- file_ops' rule, and the
165
+ reason it is a rule: a path that merely looks contained is not.
166
+ """
167
+ resolved = os.path.realpath(os.path.join(root, user_path))
168
+ if resolved != root and not resolved.startswith(root + os.sep):
169
+ return None
170
+ return resolved
171
+
172
+
173
+ def _is_readable_doc(root: str, resolved: str) -> bool:
174
+ rel = os.path.relpath(resolved, root)
175
+ parts = rel.split(os.sep)
176
+ if any(segment.casefold() in _DENIED_FOLDED for segment in parts):
177
+ return False
178
+ name = os.path.basename(resolved).lower()
179
+ if name in _DENIED_FILENAMES or name.startswith(".env"):
180
+ return False
181
+ if name in _DOC_FILENAMES:
182
+ return True
183
+ if name in _ROOT_ONLY_FILENAMES:
184
+ # `parts` is the path relative to the project root, so a length of
185
+ # one IS "at the root". Checked against the split rather than the
186
+ # string, because os.altsep exists.
187
+ return len(parts) == 1
188
+ return os.path.splitext(name)[1] in _DOC_EXTENSIONS
189
+
190
+
191
+ def is_readable_doc(project_path: str, user_path: str) -> bool:
192
+ """This tool's own test, in public, for /init's manifest (#94).
193
+
194
+ The manifest prints "Paths below are exactly what read_project_doc
195
+ expects" over its listing, and used to decide what to list with a
196
+ parallel test of its own. Nothing kept the two in step and they
197
+ disagreed in both directions: six advertised paths the tool refused,
198
+ and four it accepted that never appeared -- including every `.txt`
199
+ document in a project, invisible because the manifest tested extensions
200
+ and this module tests these.
201
+
202
+ Exported rather than reimplemented, so the sentence is true by
203
+ construction. The read path is unchanged: `read_run` still resolves and
204
+ re-tests for itself, because a listing is not an authorization.
205
+ """
206
+ root = os.path.realpath(project_path)
207
+ resolved = _resolve_in_project(root, user_path)
208
+ return resolved is not None and _is_readable_doc(root, resolved)
209
+
210
+
211
+ # ===========================================================================
212
+ # ---- READ -----------------------------------------------------------------
213
+ # ===========================================================================
214
+
215
+ READ_TOOL_SCHEMA = {
216
+ "name": "read_project_doc",
217
+ "description": (
218
+ "Read one of this project's documentation or manifest files, by the "
219
+ "relative path given in the file listing you were shown. Markdown, "
220
+ "text and manifest files only, and only within the project "
221
+ f"directory. Returns at most {config.INIT_READ_CHARS} characters per "
222
+ "call; use offset to continue through a longer file."
223
+ ),
224
+ "input_schema": {
225
+ "type": "object",
226
+ "properties": {
227
+ "path": {
228
+ "type": "string",
229
+ "description": "Path relative to the project root, exactly "
230
+ "as it appears in the file listing.",
231
+ },
232
+ "offset": {
233
+ "type": "integer",
234
+ "description": "Characters to skip before reading. Use the "
235
+ "value suggested by a truncated response to "
236
+ "read the next part of a long file.",
237
+ },
238
+ },
239
+ "required": ["path"],
240
+ },
241
+ }
242
+
243
+
244
+ def _skip(handle, offset: int) -> None:
245
+ """Advance `offset` characters without holding them.
246
+
247
+ f.seek() on a text stream takes an opaque cookie, not a character
248
+ count, so an offset cannot simply be jumped to. Reading forward in
249
+ bounded pieces keeps the memory ceiling at one piece instead of the
250
+ whole prefix, which is the property #55 is about -- the cost is
251
+ proportional to the offset, but the MEMORY is not.
252
+ """
253
+ remaining = offset
254
+ while remaining > 0:
255
+ piece = handle.read(min(remaining, config.INIT_READ_CHARS))
256
+ if not piece:
257
+ return
258
+ remaining -= len(piece)
259
+
260
+
261
+ def read_run(params: dict) -> dict:
262
+ # params.get throughout, not params[]. tools/base.py carries the one
263
+ # copy of why, under "WHAT A CALLABLE REGISTERED BELOW MAY RAISE": a
264
+ # handler's exception IS contained, so the reason this is right is that
265
+ # an error dict the model can read beats the generic wrapper it would
266
+ # get -- not the turn-ending raise six comments in this directory used
267
+ # to claim (batch 146).
268
+ root = _project_root()
269
+ if root is None:
270
+ return {"error": "read_project_doc: no project directory has been "
271
+ "resolved, so there is nothing to read."}
272
+
273
+ user_path = (params.get("path") or "").strip()
274
+ if not user_path:
275
+ return {"error": "read_project_doc requires 'path'."}
276
+
277
+ resolved = _resolve_in_project(root, user_path)
278
+ if resolved is None:
279
+ return {"error": f"read_project_doc: {user_path!r} resolves outside "
280
+ f"the project directory."}
281
+ if not _is_readable_doc(root, resolved):
282
+ return {"error": f"read_project_doc: {user_path!r} is not a readable "
283
+ f"project document. Documentation and manifest "
284
+ f"files only."}
285
+ if not os.path.isfile(resolved):
286
+ return {"error": f"read_project_doc: no such file: {user_path}"}
287
+
288
+ offset = params.get("offset") or 0
289
+ if not isinstance(offset, int) or offset < 0:
290
+ offset = 0
291
+
292
+ # ROADMAP_v2 §31 (H7), #55. This used to be f.read() followed by
293
+ # text[offset:offset + INIT_READ_CHARS], so returning 20,000
294
+ # characters of a 30 MB document cost 60 MB of peak traced memory --
295
+ # and cost it AGAIN on every page, because each call re-read the
296
+ # whole file to slice a different part of it.
297
+ #
298
+ # A getsize guard like read_run's would be the obvious copy, and it
299
+ # is the wrong one here: refusing a large document is not what this
300
+ # tool is for -- I7 chose INIT_READ_CHARS deliberately so /init could
301
+ # page through exactly such a document. Seeking to the offset bounds
302
+ # the read AND removes the re-read, which a size check would not.
303
+ #
304
+ # One extra character is read to answer `truncated` without a second
305
+ # pass. seek() counts characters in text mode only for utf-8-sig-free
306
+ # streams, so the offset is walked rather than jumped: correctness
307
+ # over cleverness, and it still holds one chunk rather than the file.
308
+ try:
309
+ with open(resolved, encoding="utf-8", errors="replace") as f:
310
+ _skip(f, offset)
311
+ chunk = f.read(config.INIT_READ_CHARS)
312
+ more = f.read(1) != ""
313
+ except OSError as e:
314
+ logger.warning("read_project_doc failed for %s: %s", user_path, e)
315
+ return {"error": f"Could not read {user_path}: {e}"}
316
+
317
+ result = {"path": user_path, "content": chunk, "truncated": more}
318
+ if result["truncated"]:
319
+ # The continuation offset is IN the message, not merely implied by
320
+ # the numbers. A model that has to compute where to resume usually
321
+ # re-reads from zero and spends the budget twice.
322
+ #
323
+ # §31 (H7) dropped the total. It used to read `of {len(text)}`,
324
+ # and len(text) was the whole file -- the very read this section
325
+ # removed. A total could be faked from os.path.getsize, but that
326
+ # is BYTES and this count is CHARACTERS, so on any document with
327
+ # a non-ASCII character it would be a number that looks exact and
328
+ # is not. Saying less is the honest option; the part that was
329
+ # load-bearing -- where to resume -- is untouched.
330
+ end = offset + len(chunk)
331
+ result["message"] = (
332
+ f"Read characters {offset}-{end}. "
333
+ f"Call again with offset={end} to continue.")
334
+ return result
335
+
336
+
337
+ # ===========================================================================
338
+ # ---- WRITE ----------------------------------------------------------------
339
+ # ===========================================================================
340
+
341
+ WRITE_TOOL_SCHEMA = {
342
+ "name": "write_project_doc",
343
+ "description": (
344
+ "Write one of this project's standard documentation files. Takes the "
345
+ "document's NAME, not a path -- the location is derived, so this "
346
+ "cannot write anywhere else. Overwrites the named file, so the caller "
347
+ "is expected to have shown the user what changes."
348
+ ),
349
+ "input_schema": {
350
+ "type": "object",
351
+ "properties": {
352
+ "name": {
353
+ "type": "string",
354
+ "description": "One of the project's standard document names, "
355
+ "e.g. AGENTS.md or ARCHITECTURE.md.",
356
+ },
357
+ "content": {
358
+ "type": "string",
359
+ "description": "Full markdown body of the document.",
360
+ },
361
+ },
362
+ "required": ["name", "content"],
363
+ },
364
+ }
365
+
366
+
367
+ def _known_doc_names() -> frozenset:
368
+ """The allowlist IS the confinement (I1), so it is read from the one
369
+ place that defines the sets rather than restated here. Imported lazily:
370
+ tools/registry.py imports this module at import time, and project_init
371
+ imports config, which would close a cycle."""
372
+ from project_init.doc_sets import all_document_names
373
+ return all_document_names()
374
+
375
+
376
+ def approval_notice(params: dict, context) -> str:
377
+ """What the approval prompt shows.
378
+
379
+ The gate is only worth having if the prompt says what it is gating
380
+ (remember.py's rule). Here that is the destination and the size --
381
+ the content itself has already been shown as a diff by the caller,
382
+ and repeating several kilobytes of markdown inside a modal would bury
383
+ the one line that says which file is about to change.
384
+ """
385
+ root = _project_root()
386
+ name = params.get("name") or HUB_FILENAME
387
+ size = len(params.get("content") or "")
388
+ if not root:
389
+ return f"Create {name} ({size} characters)."
390
+
391
+ # RESOLVED, so the consent can never name a file the bytes will not
392
+ # land on (batch 146). `_project_root()` is already a realpath, so for
393
+ # an ordinary document this is the same string the join produced and
394
+ # the prompt is unchanged; where it differs, the difference IS the
395
+ # thing the person needs to see.
396
+ resolved = _resolve_in_project(root, name)
397
+ if resolved is None:
398
+ return (f"REFUSE {doc_path(root, name)} ({size} characters): that "
399
+ f"name resolves outside the project, so write_project_doc "
400
+ f"will not write it.")
401
+ verb = "Overwrite" if os.path.exists(resolved) else "Create"
402
+ return f"{verb} {resolved} ({size} characters)."
403
+
404
+
405
+ def write_run(params: dict) -> dict:
406
+ root = _project_root()
407
+ if root is None:
408
+ return {"error": "write_project_doc: no project directory has been "
409
+ "resolved, so there is nowhere to write."}
410
+
411
+ name = (params.get("name") or "").strip()
412
+ known = _known_doc_names()
413
+ if name not in known:
414
+ # Not coerced to the hub, and not accepted as a path. An
415
+ # unrecognised name is the one case where this tool could become a
416
+ # general writer, so it fails loudly and lists what it accepts.
417
+ return {"error": f"write_project_doc: {name!r} is not one of this "
418
+ f"project's standard documents. Expected one of: "
419
+ f"{', '.join(sorted(known))}."}
420
+
421
+ content = params.get("content")
422
+ if not isinstance(content, str) or not content.strip():
423
+ return {"error": "write_project_doc requires non-empty 'content'."}
424
+
425
+ encoded = content.encode("utf-8")
426
+ if len(encoded) > config.MAX_FILE_SIZE_BYTES:
427
+ return {"error": f"Content size ({len(encoded)} bytes) exceeds the "
428
+ f"maximum writable size "
429
+ f"({config.MAX_FILE_SIZE_BYTES} bytes)."}
430
+
431
+ # RESOLVED BEFORE WRITING, which the read path has always done and this
432
+ # one did not (batch 146). The module's invariant is that the
433
+ # destination is derived from a name "so it cannot be aimed elsewhere",
434
+ # and a document name that is a LINK aims it elsewhere: a cloned project
435
+ # carrying `ARCHITECTURE.md -> ~/.bashrc` took the bytes to the link
436
+ # target, under a consent that named the in-project path. git stores
437
+ # symlinks natively, so the layout needs no privilege to arrive.
438
+ #
439
+ # An error rather than a coercion, in the sense the unknown-name branch
440
+ # above means: a name that leaves the project is not one of this
441
+ # project's documents.
442
+ destination = doc_path(root, name)
443
+ resolved = _resolve_in_project(root, name)
444
+ if resolved is None:
445
+ logger.warning("write_project_doc refused %s: resolves outside the "
446
+ "project", destination)
447
+ return {"error": f"write_project_doc: {name!r} resolves outside the "
448
+ f"project directory, so it is not one of this "
449
+ f"project's documents."}
450
+
451
+ try:
452
+ # REPLACES THE NAME RATHER THAN WRITING THROUGH IT, which closes the
453
+ # half `realpath` cannot see: a hardlink is not a link to anything,
454
+ # so the resolution above admits one. And `newline=""`, so the bytes
455
+ # the model supplied are the bytes that land -- this tool is the one
456
+ # write path in the harness reachable with no config edit, and its
457
+ # whole purpose is to overwrite a document in place, under an
458
+ # approval that was shown a diff of the lines that changed.
459
+ write_text_atomic(resolved, content)
460
+ except OSError as e:
461
+ logger.warning("write_project_doc failed for %s: %s", resolved, e)
462
+ return {"error": f"Could not write {resolved}: {e}"}
463
+
464
+ return {"result": f"Wrote {len(content)} characters to {resolved}"}