@draht/coding-agent 2026.10.23 → 2026.10.31-1

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/CHANGELOG.md +21 -0
  2. package/README.md +10 -0
  3. package/dist/bundle/chunks/{anthropic-messages-VEMVBETR.js → anthropic-messages-CZYDBUW7.js} +1 -1
  4. package/dist/bundle/chunks/{azure-openai-responses-EXUP6SLM.js → azure-openai-responses-UKM4K3L6.js} +1 -1
  5. package/dist/bundle/chunks/bedrock-converse-stream.js +21 -21
  6. package/dist/bundle/chunks/chunk-2JZLKNZ4.js +3 -0
  7. package/dist/bundle/chunks/{chunk-FXLM6UQV.js → chunk-2TZWVGCR.js} +1 -1
  8. package/dist/bundle/chunks/{chunk-KVH4HR57.js → chunk-6WESOD4H.js} +1 -1
  9. package/dist/bundle/chunks/{chunk-RGI7SF5G.js → chunk-7ATV4EYW.js} +1 -1
  10. package/dist/bundle/chunks/{chunk-CHRFWNPF.js → chunk-AS6DCLAM.js} +105 -101
  11. package/dist/bundle/chunks/{chunk-57PET6SW.js → chunk-BL72B6LV.js} +1 -1
  12. package/dist/bundle/chunks/{chunk-CI37W6HM.js → chunk-C2XCXA6V.js} +1 -1
  13. package/dist/bundle/chunks/chunk-CLKG6K6Z.js +7 -0
  14. package/dist/bundle/chunks/{chunk-QG2WW2SA.js → chunk-CPFKZX4B.js} +1 -1
  15. package/dist/bundle/chunks/{chunk-AACPRSR2.js → chunk-E4VZJRJ2.js} +1 -1
  16. package/dist/bundle/chunks/chunk-GBFVS2SF.js +12 -0
  17. package/dist/bundle/chunks/{chunk-ITP6IDBA.js → chunk-GQXRTK54.js} +2 -2
  18. package/dist/bundle/chunks/{chunk-JRHPLIE5.js → chunk-H5BLLINF.js} +1 -1
  19. package/dist/bundle/chunks/{chunk-XB4F3WGD.js → chunk-IGO52ZOY.js} +10 -10
  20. package/dist/bundle/chunks/chunk-IT4RIOZD.js +2 -0
  21. package/dist/bundle/chunks/chunk-LO6CVU2L.js +6 -0
  22. package/dist/bundle/chunks/{chunk-DHZBWXZK.js → chunk-N3FZGIII.js} +1 -1
  23. package/dist/bundle/chunks/chunk-OCUU7HYF.js +2 -0
  24. package/dist/bundle/chunks/{chunk-DLVZ3EK7.js → chunk-PMDUR6B5.js} +8 -8
  25. package/dist/bundle/chunks/{chunk-2RI4GIFP.js → chunk-UCJ7FLSO.js} +3 -3
  26. package/dist/bundle/chunks/{chunk-KINQOWAP.js → chunk-WFHH5SX6.js} +1 -1
  27. package/dist/bundle/chunks/{chunk-CMKX4CSI.js → chunk-WYWBXNDO.js} +1 -1
  28. package/dist/bundle/chunks/{cli-LGOE6EXL.js → cli-HTUB6WOG.js} +1 -1
  29. package/dist/bundle/chunks/{cloudflare-workers-ai-system-one-47PK45EQ.js → cloudflare-workers-ai-system-one-V37VPUK4.js} +1 -1
  30. package/dist/bundle/chunks/{execute-ZVQ7ITER.js → execute-UUPNZJJG.js} +1 -1
  31. package/dist/bundle/chunks/{google-generative-ai-PBPH45HB.js → google-generative-ai-A2277FHU.js} +1 -1
  32. package/dist/bundle/chunks/{google-vertex-ZPCFQNU6.js → google-vertex-2KSVQZQN.js} +1 -1
  33. package/dist/bundle/chunks/https-proxy-agent-WQIRL24U.js +13 -0
  34. package/dist/bundle/chunks/lib-ULKZYRGD.js +9 -0
  35. package/dist/bundle/chunks/{llama-cpp-classify-MWIQKGBR.js → llama-cpp-classify-Y3DUSEM2.js} +1 -1
  36. package/dist/bundle/chunks/{mistral-conversations-7ODWQ37T.js → mistral-conversations-R2NJADHS.js} +1 -1
  37. package/dist/bundle/chunks/{multipart-parser-AZP5BX2W.js → multipart-parser-HMCXZ4BD.js} +1 -1
  38. package/dist/bundle/chunks/{node-BZAVEWJ3.js → node-DXZFQBEO.js} +1 -1
  39. package/dist/bundle/chunks/{node-C2JGH2OB.js → node-LBZLUIBE.js} +1 -1
  40. package/dist/bundle/chunks/{openai-codex-responses-7Y2SP2GS.js → openai-codex-responses-KJZDJELP.js} +1 -1
  41. package/dist/bundle/chunks/{openai-completions-QNWYJ4H4.js → openai-completions-RTWADJBP.js} +1 -1
  42. package/dist/bundle/chunks/{openai-decisions-4PKBAPR3.js → openai-decisions-JRN6M2KB.js} +1 -1
  43. package/dist/bundle/chunks/{openai-responses-73WU3TQM.js → openai-responses-B7ASLN2Z.js} +1 -1
  44. package/dist/bundle/chunks/{openrouter-images-IMWDSQ5F.js → openrouter-images-2XTVCXIC.js} +1 -1
  45. package/dist/bundle/chunks/{pi-messages-AMNZ7HKZ.js → pi-messages-7TX4RC24.js} +1 -1
  46. package/dist/bundle/chunks/{runtime-MZVF4MP6.js → runtime-IB3XQ7E3.js} +1 -1
  47. package/dist/bundle/chunks/{runtime-7BIFTREJ.js → runtime-LB35PK4J.js} +1 -1
  48. package/dist/bundle/chunks/{settings-manager-QF6DRH5C.js → settings-manager-YNY5F4RU.js} +1 -1
  49. package/dist/bundle/chunks/src-KDGO7EGF.js +4 -0
  50. package/dist/bundle/chunks/{typesafe-system-one-AXQRIVVX.js → typesafe-system-one-7BNMQFXE.js} +1 -1
  51. package/dist/bundle/chunks/virtual-modules-OFCQ5AEG.js +2 -0
  52. package/dist/bundle/cli-runtime.js +1 -1
  53. package/dist/bundle/index.js +1 -1
  54. package/dist/bundle/rpc-entry.js +1 -1
  55. package/dist/core/agent-session.d.ts.map +1 -1
  56. package/dist/core/agent-session.js +1 -0
  57. package/dist/core/agent-session.js.map +1 -1
  58. package/dist/core/builtins/budget-guidance.d.ts +2 -0
  59. package/dist/core/builtins/budget-guidance.d.ts.map +1 -0
  60. package/dist/core/builtins/budget-guidance.js +2 -0
  61. package/dist/core/builtins/budget-guidance.js.map +1 -0
  62. package/dist/core/builtins/budgets.d.ts +3 -0
  63. package/dist/core/builtins/budgets.d.ts.map +1 -0
  64. package/dist/core/builtins/budgets.js +272 -0
  65. package/dist/core/builtins/budgets.js.map +1 -0
  66. package/dist/core/builtins/index.d.ts.map +1 -1
  67. package/dist/core/builtins/index.js +2 -0
  68. package/dist/core/builtins/index.js.map +1 -1
  69. package/dist/core/builtins/subagent.d.ts +3 -1
  70. package/dist/core/builtins/subagent.d.ts.map +1 -1
  71. package/dist/core/builtins/subagent.js +6 -3
  72. package/dist/core/builtins/subagent.js.map +1 -1
  73. package/dist/core/extensions/loader.d.ts.map +1 -1
  74. package/dist/core/extensions/loader.js +32 -3
  75. package/dist/core/extensions/loader.js.map +1 -1
  76. package/dist/core/extensions/runner.d.ts.map +1 -1
  77. package/dist/core/extensions/runner.js +2 -2
  78. package/dist/core/extensions/runner.js.map +1 -1
  79. package/dist/core/extensions/types.d.ts +9 -1
  80. package/dist/core/extensions/types.d.ts.map +1 -1
  81. package/dist/core/extensions/types.js.map +1 -1
  82. package/dist/core/mcp-servers.d.ts +3 -0
  83. package/dist/core/mcp-servers.d.ts.map +1 -1
  84. package/dist/core/mcp-servers.js.map +1 -1
  85. package/dist/core/multi-agent/permission-gate.d.ts +37 -8
  86. package/dist/core/multi-agent/permission-gate.d.ts.map +1 -1
  87. package/dist/core/multi-agent/permission-gate.js +158 -17
  88. package/dist/core/multi-agent/permission-gate.js.map +1 -1
  89. package/dist/extensions/mcp/config.d.ts +3 -0
  90. package/dist/extensions/mcp/config.d.ts.map +1 -1
  91. package/dist/extensions/mcp/config.js.map +1 -1
  92. package/dist/extensions/mcp/index.d.ts.map +1 -1
  93. package/dist/extensions/mcp/index.js +29 -7
  94. package/dist/extensions/mcp/index.js.map +1 -1
  95. package/dist/extensions/mcp/tools.d.ts +3 -0
  96. package/dist/extensions/mcp/tools.d.ts.map +1 -1
  97. package/dist/extensions/mcp/tools.js +1 -1
  98. package/dist/extensions/mcp/tools.js.map +1 -1
  99. package/dist/hooks/checks/budget-command.md +22 -0
  100. package/dist/hooks/checks/budgets-cl100k.json.gz +0 -0
  101. package/dist/hooks/checks/budgets-runtime.LICENSE +95 -0
  102. package/dist/hooks/checks/budgets-runtime.cjs +3382 -0
  103. package/docs/budgets.md +122 -0
  104. package/docs/docs.json +4 -0
  105. package/docs/environment-variables.md +1 -1
  106. package/docs/extensions.md +3 -1
  107. package/docs/keybindings.md +1 -1
  108. package/docs/mcp.md +13 -1
  109. package/docs/slash-commands.md +1 -0
  110. package/eval/drahtbank/runtime-checks.d.mts +1 -1
  111. package/eval/drahtbank/runtime-checks.mjs +38 -4
  112. package/hooks/checks/budget-command.md +22 -0
  113. package/hooks/checks/budgets-cl100k.json.gz +0 -0
  114. package/hooks/checks/budgets-runtime.LICENSE +95 -0
  115. package/hooks/checks/budgets-runtime.cjs +3382 -0
  116. package/package.json +9 -9
  117. package/dist/bundle/chunks/chunk-6MSE6LZ3.js +0 -6
  118. package/dist/bundle/chunks/chunk-736QBNUZ.js +0 -12
  119. package/dist/bundle/chunks/chunk-LK54N67E.js +0 -7
  120. package/dist/bundle/chunks/chunk-SYRVFGYE.js +0 -2
  121. package/dist/bundle/chunks/chunk-TIA2T6EO.js +0 -3
  122. package/dist/bundle/chunks/chunk-YSIQCH4Z.js +0 -2
  123. package/dist/bundle/chunks/https-proxy-agent-O2PVUIOI.js +0 -13
  124. package/dist/bundle/chunks/lib-XOG5PI3Y.js +0 -9
  125. package/dist/bundle/chunks/src-TIBHS42X.js +0 -4
  126. package/dist/bundle/chunks/virtual-modules-Z4F3ZUX3.js +0 -2
  127. /package/dist/bundle/chunks/{chunk-UQSONZLL.js → chunk-DN7SM3LX.js} +0 -0
  128. /package/dist/bundle/chunks/{chunk-2MJ6J5N2.js → chunk-FOYIPAAD.js} +0 -0
  129. /package/dist/bundle/chunks/{chunk-ZZD35WKM.js → chunk-MOOADNVS.js} +0 -0
@@ -0,0 +1,122 @@
1
+ # Token budgets
2
+
3
+ The coding agent, draht-claude, and draht-codex share per-file token limits that
4
+ encourage readable, cohesive code and concise documentation. Budgets are opt-in:
5
+ they apply only in Git repositories that contain `.draht/budgets.json`. Chat
6
+ responses have no budget.
7
+
8
+ Limits are ceilings: aim for the smallest clear solution, not a filled allowance.
9
+ Document contracts, setup, and non-obvious decisions; avoid restating code or
10
+ keeping status diaries. Do not minify code or split files arbitrarily to fit.
11
+ These are size guardrails, not quality scores.
12
+
13
+ ## Setup
14
+
15
+ Run `/budget` in draht, `/draht:budget` in Claude Code, or `$draht:budget` in
16
+ Codex. The agent proposes defaults, asks for missing choices, and writes only
17
+ `.draht/budgets.json` at the repository root:
18
+
19
+ ```json
20
+ {
21
+ "maxFileTokens": 5000,
22
+ "maxDocFileTokens": 1500,
23
+ "maxOversizedGrowthTokens": 250,
24
+ "maxCodeTokens": null,
25
+ "maxDocTokens": null,
26
+ "exclude": ["packages/*/dist/", "*.generated.ts"]
27
+ }
28
+ ```
29
+
30
+ These are the defaults, apart from the example `exclude` patterns. File limits
31
+ are positive integers. `maxOversizedGrowthTokens` is how far a file that was
32
+ already over its limit when the task started may grow; `0` freezes such files.
33
+ The optional task totals cap changed tokens across the task; `null` leaves them
34
+ unlimited. `"enabled": false` turns budgets off at the next new task.
35
+
36
+ ## What is measured
37
+
38
+ Tokens use the bundled `cl100k_base` encoding from pinned
39
+ [gpt-tokenizer](https://github.com/niieani/gpt-tokenizer), counted offline. The
40
+ active model does not change the count.
41
+
42
+ The budget covers text files that Git tracks, plus untracked files that
43
+ `.gitignore` does not exclude. Markdown, MDX, reStructuredText, AsciiDoc, and
44
+ `.txt` files use the documentation limit, except `CMakeLists.txt` and pip
45
+ requirement lists; everything else, tests included, is code. Source files with
46
+ invalid UTF-8 are decoded lossily and still counted.
47
+
48
+ Never measured:
49
+
50
+ - lockfiles such as `bun.lock`, `package-lock.json`, `go.sum`, and `Cargo.lock`
51
+ - `CHANGELOG.md` files
52
+ - credential files such as `.env*`, `.npmrc`, `*.pem`, and SSH keys, which are
53
+ never copied into the ledger
54
+ - files marked `linguist-generated` in the `.gitattributes` committed at task start
55
+ - paths matching `exclude`: a pattern without `/` matches a name at any depth, one
56
+ with `/` is relative to the repository root, and a trailing `/` matches a
57
+ directory; `*`, `?`, and `**` are supported
58
+ - files outside the repository, ignored files, binary files, symlinks, and nested
59
+ repositories
60
+
61
+ Writes to unmeasured files pass unchecked, whether they come from edit tools or
62
+ the shell. A file that Git starts ignoring during a task, or that a nested
63
+ repository takes over, does not count while it stays out; when it returns, it
64
+ is measured against its starting content again.
65
+
66
+ A change costs the tokens in its added lines plus the tokens in its deleted
67
+ lines, measured against the task's starting snapshot. Replacing a 100-token block
68
+ with an 80-token block costs 180 tokens; unchanged lines are free, and redrafts
69
+ do not add up. Diffs with more than 4,096 line edits are charged as whole-file
70
+ replacements. A moved file is measured against the deleted file it shares the
71
+ most lines with, when at least half of its content is unchanged, so moving a
72
+ file costs only its edits and keeps its limit.
73
+
74
+ ## Tasks
75
+
76
+ The first budget event in a configured repository starts a task. Its snapshot
77
+ includes existing changes, and its settings stay fixed until a new task.
78
+ Commits, restarts, new prompts, and pulls do not reset it; pulled changes count
79
+ as changes, so start a new task after pulling.
80
+
81
+ The main agent, subagents, and linked worktrees of the repository share one
82
+ task. A removed worktree's changes still count toward task totals, but its file
83
+ limits no longer apply.
84
+
85
+ Only the user starts a new task: `/budget new` in draht, or `/draht:budget new`
86
+ and `$draht:budget new` submitted as the whole prompt in the plugins. Agents
87
+ cannot reset the task. Edits to `.draht/budgets.json`, including an agent's,
88
+ apply only from the next new task, so review the file before starting one.
89
+
90
+ ## Enforcement
91
+
92
+ Edit tools are checked before they run; a change that creates or enlarges an
93
+ excess is refused, while changes that leave the excess the same size or reduce
94
+ it proceed. Audits after tools and before completion catch shell writes; plugins
95
+ audit after their project checks, so formatter output counts. An excess blocks
96
+ completion for three repair attempts per prompt; after that the run ends with
97
+ the excess reported. Audits never roll files back.
98
+
99
+ When a check cannot run, for example because `.draht/budgets.json` is invalid or
100
+ the ledger is damaged, tools keep working and completion is reported as
101
+ unchecked. Fix the configuration or start a new task.
102
+
103
+ These gates are not a sandbox: code running in the repository can still edit
104
+ the ledger. Plugin enforcement requires the host to run trusted hooks.
105
+
106
+ ## Ledger and CLI
107
+
108
+ The ledger lives in the Git common directory: `draht-budgets/` holds the task
109
+ and content snapshots, `draht-budgets.task` records the active task, and
110
+ `draht-budgets.lock` serializes access. Per-worktree caches of file metadata
111
+ and token counts keep checks fast; a new task replaces the stored snapshots and
112
+ caches. Native draht runs checks in a child process, so they never block the
113
+ session.
114
+
115
+ Run the packaged CLI from the project directory:
116
+
117
+ ```sh
118
+ node /path/to/plugin/scripts/budgets-runtime.cjs status
119
+ node /path/to/plugin/scripts/budgets-runtime.cjs config
120
+ ```
121
+
122
+ `config` validates `.draht/budgets.json` without starting or changing a task.
package/docs/docs.json CHANGED
@@ -92,6 +92,10 @@
92
92
  "title": "Configure draht",
93
93
  "path": "configuration.md"
94
94
  },
95
+ {
96
+ "title": "Set Token Budgets",
97
+ "path": "budgets.md"
98
+ },
95
99
  {
96
100
  "title": "Create Prompt Templates",
97
101
  "path": "prompt-templates.md"
@@ -102,7 +102,7 @@ These variables are read by draht itself:
102
102
  | `DRAHT_SHARE_VIEWER_URL` | Base URL of a share viewer for `/share`; when unset, `/share` prints the gist URL |
103
103
  | `DRAHT_RADIUS_GATEWAY` | Not consulted by the builtin Radius model provider (which always uses `https://radius.pi.dev`, or a per-provider `baseUrl` from provider config) or by `/bug`; currently has no effect on behavior |
104
104
  | `DRAHT_BUG_REPORT_GATEWAY` | Override the `/bug` upload destination; default is `https://radius.draht.dev` |
105
- | `DRAHT_PERMISSION_MODE` | Initial permission mode of the session: `ask`, `auto` (when unset or blank), or `yolo`, in any letter case; any other value, the old name `default` included, starts the session in `ask` with a warning. `/permissions`, `/yolo`, and [`app.permissions.cycle`](keybindings.md#models-and-thinking) change it afterwards; a mode chosen that way outlasts `/new`, `/resume`, `/fork`, and `/reload` when it asks more than the starting mode. A session the gateway starts or resumes receives the gateway daemon's value, except `yolo`, which crosses only when the daemon's `DRAHT_RESUME_ENV_ALLOW` lists the variable. Polyphase children receive the session's current mode in this variable; see [Orchestrate Agents with Polyphase](polyphase.md#permissions) |
105
+ | `DRAHT_PERMISSION_MODE` | Initial permission mode of the session: `supervised` (`ask`, and every file change asks), `ask`, `auto` (when unset or blank), or `yolo`, in any letter case; any other value, the old name `default` included, starts the session in `ask` with a warning. `/permissions`, `/yolo`, and [`app.permissions.cycle`](keybindings.md#models-and-thinking) change it afterwards; a mode chosen that way outlasts `/new`, `/resume`, `/fork`, and `/reload` when it asks more than the starting mode. A session the gateway starts or resumes receives the gateway daemon's value, except `yolo`, which crosses only when the daemon's `DRAHT_RESUME_ENV_ALLOW` lists the variable. Polyphase children receive the session's current mode in this variable; see [Orchestrate Agents with Polyphase](polyphase.md#permissions) |
106
106
  | `DRAHT_NO_ATTACHABLE` | Set to `1`/`true`/`yes` to stop sessions from registering an attach socket; overridden by `--attachable` |
107
107
  | `DRAHT_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
108
108
  | `DRAHT_CLIPBOARD_OSC52` | Set to `1` to also send copied text to the terminal with OSC 52 after the local clipboard write, as draht does over SSH. Use it when a remote client reaches draht without SSH variables, such as a multiplexer attached from another machine or a remote IDE daemon |
@@ -294,6 +294,8 @@ pi.on("tool_call", async (event, ctx) => {
294
294
  });
295
295
  ```
296
296
 
297
+ draht's own permission gate runs a call to a tool with `readOnlyHint: true` without asking (in the `ask` and `supervised` modes, only one that also declares `openWorldHint: false`, since a tool that reaches the web can carry what it read out), when no rule in `permissions.yml` matches it, no argument of the call names a path outside the project, and the hint comes from outside the project: from a built-in tool, or from an extension loaded with `-e`, by the SDK, or from the user's own extensions and packages. Tools of a project's extensions still ask, and so does a tool that also declares `destructiveHint: true`. An extension that relays another source's hints, as the MCP support relays a server's, sets `annotationsScope` to that source's scope: `"user"`, `"project"`, or `"temporary"`. The gate ignores the hints when `annotationsScope` is `"project"`, so the field can lower trust but never raise it. `pi.getAllTools()` reports `annotationsScope` with the annotations.
298
+
297
299
  A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure, namespace, and prompt guidelines. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. The default system prompt leaves hidden tools out of its tool list and rules, and names no tool in the skills hint when the file reader is hidden, so the orchestrating tool should present their guidelines itself. `codemode` uses only this hook, `exposure`, `reachesTools`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
298
300
 
299
301
  A tool that reaches other tools declares which ones a call may reach with `reachesTools(input)`: `"all"`, or the words of the input that may name them, where a word refers to every tool or namespace whose name it contains. `codemode` returns `"all"` for scripts that search or list tools and the words of the script otherwise; `tool_search` always returns `"all"`. Extensions that register tools late use it from their `tool_call` handler to finish registering the tools a call needs before it runs, as the MCP extension does for servers that are still connecting. The MCP extension also activates `codemode` or `tool_search` for MCP tools only when the tool of that name declares `reachesTools`.
@@ -325,7 +327,7 @@ pi.unregisterMcpServer("jira");
325
327
 
326
328
  Servers registered while the extension loads connect when the session starts, together with the `mcp.json` servers; servers registered later connect right away, and `pi.unregisterMcpServer()` closes the connection and makes the server's tools unreachable. Registrations are not saved: register again on every load, for example based on the extension's own settings. A server in `mcp.json` with the same name takes precedence, and `/mcp` shows the override. Registering the same name again replaces the extension's earlier registration; names registered by another extension, invalid names, and invalid configs throw.
327
329
 
328
- The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `pi.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
330
+ The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `pi.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes. Each registered server carries the `extensionScope` of the extension that registered it, which its tools' `annotationsScope` takes, so the permission gate trusts a registered server's read-only hints as far as it trusts the extension.
329
331
 
330
332
  <a id="extensioncontext"></a>
331
333
  <a id="extensioncommandcontext"></a>
@@ -160,7 +160,7 @@ During `/login`, `app.login.copyUrl` copies the original URL without the line br
160
160
  | `app.model.cycleBackward` | `shift+ctrl+p` (`alt+p` on Windows and WSL) | Cycle to previous model |
161
161
  | `app.models.save` | `ctrl+s` | Save the selected default model or scoped model configuration to settings |
162
162
  | `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
163
- | `app.permissions.cycle` | `alt+m`, `ctrl+q` (`alt+m` on Windows and WSL) | Switch the permission mode between `auto` and `ask`; from `yolo`, back to `auto` |
163
+ | `app.permissions.cycle` | `alt+m`, `ctrl+q` (`alt+m` on Windows and WSL) | Switch the permission mode between `auto` and `ask`; from `yolo`, back to `auto`; from `supervised`, to `ask` |
164
164
  | `app.context.cycle` | `ctrl+shift+l` | Cycle supported context-window sizes for the current model |
165
165
  | `app.thinking.save` | `ctrl+s` | Save current thinking level to settings |
166
166
  | `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
package/docs/mcp.md CHANGED
@@ -266,7 +266,19 @@ Reading and listing resources is retried once after a transient HTTP error (408,
266
266
 
267
267
  Every MCP call passes through draht's tool pipeline. Extension `tool_call` and `tool_result` handlers, including permission gates, therefore apply to MCP tools. Calls made from codemode scripts carry the codemode call ID as `parentToolCallId`.
268
268
 
269
- `pi.getAllTools()` reports the annotations declared by each server: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. Permission extensions can use these hints to decide which calls require confirmation (see [Tool exposure](extensions.md#tool-exposure)). Resource tools are marked read-only.
269
+ `pi.getAllTools()` reports the annotations declared by each server: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. Permission extensions can use these hints to decide which calls require confirmation (see [Tool exposure](extensions.md#tool-exposure)). Resource tools are marked read-only. `annotationsScope` names where the hints come from: `user` for a server in the global `mcp.json`, `project` for one in the project's, and the registering extension's scope for a registered server. The resource tools take the least trusted scope of the servers they reach.
270
+
271
+ In the `ask` and `auto` permission modes, draht's permission gate asks before an MCP call unless a rule in `permissions.yml` allows it or the tool is read-only. A rule's `tool` accepts `*` for any run of characters and `?` for one, so one rule covers all tools of a server:
272
+
273
+ ```yaml
274
+ rules:
275
+ - tool: "mcp__docs__*"
276
+ action: allow
277
+ ```
278
+
279
+ The glob matches tool names, in which every character but letters, digits, and `_` becomes `_`, and ignores letter case: `mcp__docs__*` also covers servers named `Docs`, `docs-`, or `docs__admin`.
280
+
281
+ Without a matching rule, a tool whose server declares `readOnlyHint: true` runs without asking if, in the `ask` and `supervised` modes, it also declares `openWorldHint: false`, the server is in the global `mcp.json` or registered by an extension from outside the project, and no argument of the call names a path outside the project: an absolute path, one under `~`, a `file:` URL, or one climbing out with `..`. The hints are not verified, so tools of a server in the project's `mcp.json` still ask, and so do the resource tools while such a server has resources. The resource tools declare no `openWorldHint`, so they ask in `ask` and `supervised` mode.
270
282
 
271
283
  ## Extensions and SDK
272
284
 
@@ -47,6 +47,7 @@ Review a session before exporting or sharing it. Sessions can contain prompts, t
47
47
  | Command | Description |
48
48
  |---|---|
49
49
  | `/trust` | Save a project trust decision for future draht processes |
50
+ | [`/budget [configure\|status\|new]`](budgets.md) | Configure the repository's token budgets, show usage, or start a new budget task |
50
51
  | `/reload` | Reload keybindings, extensions, skills, templates, themes, and context files |
51
52
  | `/hotkeys` | Show active keyboard shortcuts |
52
53
  | `/changelog` | Show changelog entries |
@@ -12,4 +12,4 @@ export interface RuntimeReport {
12
12
  }
13
13
  export const RUNTIME_CHECKS: RuntimeProof[];
14
14
  export function assessRuntimeChecks(value: unknown, packageRoot: string): RuntimeAssessment;
15
- export function runRuntimeChecks(output: string, options?: {root?: string; timeoutMs?: number}): RuntimeReport;
15
+ export function runRuntimeChecks(output: string, options?: {root?: string; timeoutMs?: number}): Promise<RuntimeReport>;
@@ -1,4 +1,4 @@
1
- import { execFileSync, spawnSync } from "node:child_process";
1
+ import { execFileSync, spawn } from "node:child_process";
2
2
  import { createHash } from "node:crypto";
3
3
  import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
4
4
  import { createRequire } from "node:module";
@@ -117,11 +117,45 @@ export function assessRuntimeChecks(value, packageRoot) {
117
117
  return { complete, passed: errors.length === 0, tests, results, errors };
118
118
  }
119
119
 
120
+ /**
121
+ * spawnSync's result shape without blocking the event loop: a Vitest worker that blocks for 60s
122
+ * cannot answer its RPC heartbeat, and the run fails with "Timeout calling onTaskUpdate".
123
+ */
124
+ function runProcess(command, args, { cwd, env, timeoutMs, maxBuffer }) {
125
+ return new Promise((resolveProcess) => {
126
+ const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
127
+ const output = { stdout: "", stderr: "" };
128
+ let error = null, settled = false;
129
+ const stop = (reason) => {
130
+ error ??= reason;
131
+ child.kill("SIGKILL");
132
+ };
133
+ const timer = setTimeout(() => stop(Object.assign(new Error(`spawn ${command} ETIMEDOUT`), { code: "ETIMEDOUT" })), timeoutMs);
134
+ const finish = (status, signal) => {
135
+ if (settled) return;
136
+ settled = true;
137
+ clearTimeout(timer);
138
+ resolveProcess({ status, signal, error, stdout: output.stdout, stderr: output.stderr });
139
+ };
140
+ for (const name of ["stdout", "stderr"]) {
141
+ child[name].setEncoding("utf8").on("data", (chunk) => {
142
+ output[name] += chunk;
143
+ if (output[name].length > maxBuffer) stop(new Error(`${name} maxBuffer length exceeded`));
144
+ });
145
+ }
146
+ child.on("error", (spawnError) => {
147
+ error ??= spawnError;
148
+ if (child.pid === undefined) finish(null, null);
149
+ });
150
+ child.on("close", finish);
151
+ });
152
+ }
153
+
120
154
  function snapshot(root) {
121
155
  return Object.fromEntries(SOURCE_PATHS.map(path => [path, hash(readFileSync(join(root, path)))]));
122
156
  }
123
157
 
124
- export function runRuntimeChecks(output, options = {}) {
158
+ export async function runRuntimeChecks(output, options = {}) {
125
159
  const root = resolve(options.root ?? ROOT), packageRoot = join(root, "packages/coding-agent");
126
160
  output = resolve(output);
127
161
  const timeoutMs = options.timeoutMs ?? 180_000;
@@ -144,7 +178,7 @@ export function runRuntimeChecks(output, options = {}) {
144
178
  const command = [process.execPath, ...args];
145
179
  Object.assign(env, { DRAHT_OFFLINE: "1", DRAHT_PACKAGE_DIR: packageRoot, DRAHT_CODING_AGENT_DIR: join(output, "agent-home") });
146
180
  const startedAt = new Date().toISOString(), started = performance.now();
147
- const processResult = spawnSync(process.execPath, args, { cwd: packageRoot, env, encoding: "utf8", timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 16 * 1024 * 1024 });
181
+ const processResult = await runProcess(process.execPath, args, { cwd: packageRoot, env, timeoutMs, maxBuffer: 16 * 1024 * 1024 });
148
182
  const elapsedMs = Math.round(performance.now() - started);
149
183
  const stdout = processResult.stdout ?? "", stderr = processResult.stderr ?? "";
150
184
  writeFileSync(join(output, "stdout.txt"), stdout);
@@ -179,7 +213,7 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
179
213
  console.log("Usage: node runtime-checks.mjs <empty-output-directory> [--repo <path>]");
180
214
  } else {
181
215
  if (rest.length && (rest.length !== 2 || rest[0] !== "--repo" || !rest[1])) throw new Error("Expected optional --repo <path>");
182
- const report = runRuntimeChecks(output, { root: rest[1] });
216
+ const report = await runRuntimeChecks(output, { root: rest[1] });
183
217
  console.log(JSON.stringify({ lane: report.lane, complete: report.complete, passed: report.passed, tests: report.tests, report: join(resolve(output), "report.json") }));
184
218
  process.exitCode = report.passed ? 0 : 1;
185
219
  }
@@ -0,0 +1,22 @@
1
+ ---
2
+ description: Configure repository code and documentation budgets, inspect usage, or start a new task
3
+ argument-hint: "[configure|status|new]"
4
+ allowed-tools: Bash, Read, Write, Edit
5
+ ---
6
+
7
+ # /budget
8
+
9
+ Request: $ARGUMENTS
10
+
11
+ Budgets are opt-in: they apply only in repositories with `.draht/budgets.json`. Run `node "<BUDGET_RUNTIME>" <action>` from the current session's project directory, not the plugin directory. Its actions are `config` and `status`.
12
+
13
+ - **status**: run `status`, report its result, and stop without editing configuration.
14
+ - **new**: only the user can start a new task, by submitting this command with `new` as the whole prompt; the budget hook then resets the task. If the context confirms "Budget task reset by the user's command", run `status` and report the new limits. Otherwise say that no reset happened.
15
+ - **No argument or configure**: guide the configuration workflow below. Treat additional settings in the request as choices already given.
16
+
17
+ 1. Run `config`. Its JSON contains `configPath`, `exists`, `enabled`, `limits`, and `exclude`, resolved from the current Git working tree; `exists: false` means budgets are off in this repository. Read the existing file when present. If validation fails, report the exact error and offer corrected JSON. Without a Git working tree, explain the requirement and stop; do not initialize one.
18
+ 2. Briefly show the current settings. Ask one compact question for choices still missing; honor existing settings and choices already supplied. Offer defaults of 5,000 tokens per code file and 1,500 per documentation file, 250 tokens of growth per task for files already over their limit, and both task totals disabled. Lockfiles, `CHANGELOG.md`, and files marked `linguist-generated` in `.gitattributes` are never measured; ask which other generated paths belong in `exclude`. Ask about task totals only if the user wants them. These are local content tokens, not model billing or chat limits.
19
+ 3. Once choices are clear, write only `configPath` with `enabled`, `maxFileTokens`, `maxDocFileTokens`, `maxCodeTokens`, `maxDocTokens`, `maxOversizedGrowthTokens`, and `exclude`. File limits are positive safe integers and the growth allowance is a non-negative one; task limits accept positive safe integers or `null` to disable. `exclude` holds glob patterns: one without `/` matches a name at any depth, one with `/` is relative to the repository root, and a trailing `/` matches everything below a directory. Create `.draht/` if needed.
20
+ 4. Run `config` again to validate the saved file. Report the path and selected settings. A repository without an active task starts one at the next prompt; an active task keeps its settings until the user starts a new one. Never reset the task automatically, and never edit or delete the budget files under `.git`.
21
+
22
+ This workflow edits only `.draht/budgets.json`: no source refactoring, other configuration, documentation, or commits.
@@ -0,0 +1,95 @@
1
+ gpt-tokenizer
2
+ MIT License
3
+
4
+ Copyright (c) 2023-2024 Bazyli Brzoska
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
23
+
24
+
25
+ diff
26
+ BSD 3-Clause License
27
+
28
+ Copyright (c) 2009-2015, Kevin Decker <kpdecker@gmail.com>
29
+ All rights reserved.
30
+
31
+ Redistribution and use in source and binary forms, with or without
32
+ modification, are permitted provided that the following conditions are met:
33
+
34
+ 1. Redistributions of source code must retain the above copyright notice, this
35
+ list of conditions and the following disclaimer.
36
+
37
+ 2. Redistributions in binary form must reproduce the above copyright notice,
38
+ this list of conditions and the following disclaimer in the documentation
39
+ and/or other materials provided with the distribution.
40
+
41
+ 3. Neither the name of the copyright holder nor the names of its
42
+ contributors may be used to endorse or promote products derived from
43
+ this software without specific prior written permission.
44
+
45
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
46
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
47
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
48
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
49
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
50
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
51
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
52
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
53
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
54
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
55
+
56
+
57
+ UNICODE LICENSE V3
58
+
59
+ COPYRIGHT AND PERMISSION NOTICE
60
+
61
+ Copyright © 1991-2026 Unicode, Inc.
62
+
63
+ NOTICE TO USER: Carefully read the following legal agreement. BY
64
+ DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
65
+ SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
66
+ TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
67
+ DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
68
+
69
+ Permission is hereby granted, free of charge, to any person obtaining a
70
+ copy of data files and any associated documentation (the "Data Files") or
71
+ software and any associated documentation (the "Software") to deal in the
72
+ Data Files or Software without restriction, including without limitation
73
+ the rights to use, copy, modify, merge, publish, distribute, and/or sell
74
+ copies of the Data Files or Software, and to permit persons to whom the
75
+ Data Files or Software are furnished to do so, provided that either (a)
76
+ this copyright and permission notice appear with all copies of the Data
77
+ Files or Software, or (b) this copyright and permission notice appear in
78
+ associated Documentation.
79
+
80
+ THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
81
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
82
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
83
+ THIRD PARTY RIGHTS.
84
+
85
+ IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
86
+ BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
87
+ OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
88
+ WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
89
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
90
+ FILES OR SOFTWARE.
91
+
92
+ Except as contained in this notice, the name of a copyright holder shall
93
+ not be used in advertising or otherwise to promote the sale, use or other
94
+ dealings in these Data Files or Software without prior written
95
+ authorization of the copyright holder.