@modootoday/pmcp 0.20.0 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +1 -1
  4. package/.mcp.json +1 -1
  5. package/dist/{apply-QJ6MGLBX.js → apply-6FLMTJDV.js} +57 -23
  6. package/dist/{available-HYSDAFYH.js → available-BFXLII4A.js} +7 -7
  7. package/dist/{broadcast-LYOA6BEW.js → broadcast-ZALGUJVR.js} +4 -4
  8. package/dist/chunk-2GI5RM3M.js +53 -0
  9. package/dist/{chunk-ICF2JZSN.js → chunk-2MAD4WNZ.js} +2 -2
  10. package/dist/{chunk-YDICIB2A.js → chunk-33KGCJB2.js} +2 -2
  11. package/dist/{chunk-FQAJSNNU.js → chunk-3X5JQYKN.js} +3 -3
  12. package/dist/{chunk-IQD4W53M.js → chunk-57Q75MS4.js} +18 -18
  13. package/dist/{chunk-EKPMVEIA.js → chunk-5FW7A6TG.js} +7 -4
  14. package/dist/chunk-5YCKFU5Q.js +1672 -0
  15. package/dist/{chunk-QYH2NR6G.js → chunk-7FV2LORT.js} +2 -2
  16. package/dist/{chunk-66F3HLW4.js → chunk-DEY23WTH.js} +122 -4
  17. package/dist/chunk-DJZPPCJP.js +274 -0
  18. package/dist/{chunk-MZEMLFFD.js → chunk-G6JXCUSK.js} +2 -2
  19. package/dist/{chunk-T6GOWHK6.js → chunk-GFOQDLPL.js} +6 -1
  20. package/dist/{chunk-OAIQ7A3R.js → chunk-GQP4GWU4.js} +5 -5
  21. package/dist/chunk-H4ZOKIER.js +7 -0
  22. package/dist/{chunk-RBNMNKNN.js → chunk-JQVSDPFL.js} +3 -3
  23. package/dist/{chunk-OG7QR2DP.js → chunk-KEHB4FZP.js} +17 -2
  24. package/dist/chunk-KUBHGVTD.js +126 -0
  25. package/dist/{chunk-IZABPDAO.js → chunk-KVNNVLJR.js} +2 -2
  26. package/dist/chunk-LFFIQBNY.js +115 -0
  27. package/dist/{chunk-PQTM27GU.js → chunk-MR5IBS6L.js} +6 -7
  28. package/dist/{chunk-M2RYXWX2.js → chunk-NHUMPEPV.js} +2 -2
  29. package/dist/{chunk-ONP6JRFZ.js → chunk-OFJIMBTL.js} +2 -2
  30. package/dist/{chunk-J6HNP6HA.js → chunk-OFPNCLG7.js} +2 -2
  31. package/dist/{chunk-FD6VGFYZ.js → chunk-OS5DF3LL.js} +207 -15
  32. package/dist/{chunk-L4MFGGSI.js → chunk-POTI2RJ6.js} +2 -2
  33. package/dist/{chunk-RMHZFWHF.js → chunk-R3MVL67T.js} +33 -33
  34. package/dist/{chunk-YN5GQCHN.js → chunk-RHJEGLYM.js} +6 -1
  35. package/dist/{chunk-4VK5G3SV.js → chunk-TBKVC2TA.js} +3 -5
  36. package/dist/{chunk-K2C3KFGB.js → chunk-UFWQTZDX.js} +29 -17
  37. package/dist/{chunk-JBHGJKSL.js → chunk-VBDDFO2V.js} +2 -2
  38. package/dist/{chunk-QOFSPFJ6.js → chunk-VUM6LO77.js} +3417 -3395
  39. package/dist/{chunk-CQZYQAAV.js → chunk-YLITJLTR.js} +3 -3
  40. package/dist/{chunk-O2JWF7ZM.js → chunk-Z4Q6RYJH.js} +2 -2
  41. package/dist/{chunk-QSIADSMQ.js → chunk-Z6WRFOFT.js} +3 -3
  42. package/dist/{chunk-5JPD6VIH.js → chunk-ZIJ5IUXH.js} +9 -3
  43. package/dist/{claude-GT2BPXEL.js → claude-XVLF4N4S.js} +3 -3
  44. package/dist/{cli-IV5DJCXU.js → cli-6FWRBCWM.js} +8 -8
  45. package/dist/{cli-6HTAJ54L.js → cli-RVPR3MH3.js} +7 -7
  46. package/dist/cli.js +11 -11
  47. package/dist/{completion-PPM7MEI2.js → completion-YTPHEVEW.js} +7 -7
  48. package/dist/{diagnostics-EWU2ROTG.js → diagnostics-IW54MLFK.js} +5 -6
  49. package/dist/{doctor-ZWZQMDKZ.js → doctor-EN4JPSKV.js} +35 -35
  50. package/dist/{entry-NDICBQ2F.js → entry-TQWSDTJ4.js} +14 -15
  51. package/dist/{exec-mcp-AG4G7SG7.js → exec-mcp-KKQ75N5O.js} +15 -13
  52. package/dist/{harness-JABSZCAA.js → harness-EB76F6BG.js} +6 -6
  53. package/dist/harness-launch-gate.js +3 -4
  54. package/dist/harness-worker.js +5 -6
  55. package/dist/hook-body.js +247 -86
  56. package/dist/{hook-spec-C7umArqw.d.ts → hook-spec-hZL4MSgi.d.ts} +8 -3
  57. package/dist/hooks-YWSHUNLM.js +24 -0
  58. package/dist/{host-2SZRMHZX.js → host-LSVITS6M.js} +6 -7
  59. package/dist/{host-BWZ5LA4Q.js → host-OGGADMBT.js} +17 -15
  60. package/dist/{host-run-SXLV4LHI.js → host-run-XO2TS4JC.js} +5 -7
  61. package/dist/http.js +1 -1
  62. package/dist/{import-mcp-2M7SZRVQ.js → import-mcp-BJDJTPVS.js} +14 -11
  63. package/dist/index.d.ts +11 -2
  64. package/dist/index.js +24 -24
  65. package/dist/{init-HOOIFBAD.js → init-773PTQM5.js} +3 -3
  66. package/dist/{install-HF6CROQP.js → install-7V6NIA7W.js} +4 -4
  67. package/dist/{invoke-JP4MILYY.js → invoke-Y7XH5S2L.js} +7 -8
  68. package/dist/{list-UBSBUZKS.js → list-5W65XVES.js} +20 -17
  69. package/dist/{logout-OO3DERRK.js → logout-XO6ALD45.js} +15 -12
  70. package/dist/{logs-K3QXKRD4.js → logs-74JGLQG6.js} +4 -4
  71. package/dist/{mailbox-DAJV6VAI.js → mailbox-VK5AVTHI.js} +7 -7
  72. package/dist/{mainline-6K5BA3WX.js → mainline-M2NSTAGC.js} +70 -24
  73. package/dist/{mcp-JXNTKRJG.js → mcp-R62ZNVGJ.js} +2 -2
  74. package/dist/{pause-GRVTSKOK.js → pause-CZ2OZYLC.js} +4 -4
  75. package/dist/project/hook-adapter.d.ts +1 -1
  76. package/dist/{project-M672MKQH.js → project-W5DQIZA6.js} +5 -5
  77. package/dist/{pty-LHKJKY2E.js → pty-CDLQ4NP2.js} +3 -3
  78. package/dist/report-Z3JV2PCT.js +105 -0
  79. package/dist/{resume-6DMPGG3N.js → resume-DFIHT2RO.js} +4 -4
  80. package/dist/{run-5W566T3V.js → run-OZLGSRHF.js} +14 -11
  81. package/dist/{run-ORBIERI3.js → run-WYJMTLX7.js} +4 -4
  82. package/dist/{serve-73SRPAV4.js → serve-DCQGAGB7.js} +3 -3
  83. package/dist/{session-XM2CR425.js → session-YZVX4NGN.js} +4 -4
  84. package/dist/{setup-ULKDPF5B.js → setup-D3KEJBGO.js} +4 -4
  85. package/dist/smoke-FQQJOQBD.js +16 -0
  86. package/dist/{start-login-BGFAMCZL.js → start-login-EKXM75XQ.js} +15 -12
  87. package/dist/{status-YCW6YJ3S.js → status-23UDIYYP.js} +39 -22
  88. package/dist/{status-YHXEAJ7U.js → status-3RTGDN2K.js} +10 -10
  89. package/dist/{status-73FEFQUQ.js → status-EDSEG32U.js} +15 -12
  90. package/dist/stdio.js +2 -2
  91. package/dist/{sweep-XF2HG3EO.js → sweep-EPJMEZR6.js} +4 -4
  92. package/dist/{test-IMNBXOYW.js → test-TM6PIZTV.js} +30 -20
  93. package/dist/{tui-5GDA22TB.js → tui-EQNJIDN5.js} +4 -4
  94. package/dist/{unbroadcast-XP3OCVN3.js → unbroadcast-NTOC3PY3.js} +4 -4
  95. package/dist/{worker-RV6NGSXT.js → worker-7X6WBPEI.js} +9 -10
  96. package/dist/{worktree-list-4PLE7K6L.js → worktree-list-EMKUMCTQ.js} +2 -2
  97. package/dist/{worktree-sync-GQVYAXGJ.js → worktree-sync-T6C5YEYS.js} +3 -3
  98. package/docs/commands.md +13 -6
  99. package/docs/git-workflow.md +28 -9
  100. package/docs/hooks.md +138 -10
  101. package/docs/project-configuration.md +27 -1
  102. package/docs/upgrading.md +42 -0
  103. package/gemini-extension.json +2 -2
  104. package/mcp.json +1 -1
  105. package/package.json +5 -5
  106. package/plugin.json +1 -1
  107. package/plugins/pmcp/.claude-plugin/plugin.json +1 -1
  108. package/plugins/pmcp/.mcp.json +1 -1
  109. package/plugins/pmcp/gemini-extension.json +2 -2
  110. package/plugins/pmcp/mcp.json +1 -1
  111. package/plugins/pmcp/mod/sessions/format.ts +2 -2
  112. package/plugins/pmcp/plugin.json +1 -1
  113. package/dist/chunk-7SDOSTW7.js +0 -130
  114. package/dist/chunk-AWZF72SH.js +0 -1025
  115. package/dist/chunk-FGYFA6JY.js +0 -7
  116. package/dist/chunk-ISNRDHSD.js +0 -74
  117. package/dist/chunk-QDY6BWE6.js +0 -396
  118. package/dist/hooks-YVQSDQV3.js +0 -21
package/docs/hooks.md CHANGED
@@ -104,18 +104,128 @@ command the parser cannot read is judged by a conservative pattern instead.
104
104
 
105
105
  ## `[[hooks.guards.custom]]`
106
106
 
107
- A project script under `.agents/guards/` that decides like a built-in guard.
107
+ A project command that decides like a built-in guard: a script under
108
+ `.agents/guards/`, or an installed program pinned by its version.
109
+
110
+ | Key | Type | Default | Meaning |
111
+ | ------------ | --------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
112
+ | `name` | string | required | `^[a-z0-9][a-z0-9-]*$`, unique across custom, shell and edit entries. |
113
+ | `command` | argv list | required | Without `version`, the first or second element is the script, which must exist inside `.agents/guards/`; its sha256 is pinned in `policy.json`. With `version`, the first element is the program, found on `PATH`. |
114
+ | `version` | string | none | The version an installed program reports: `pmcp project`, `pmcp project --check` and `pmcp doctor` run `<program> --version` and refuse when the output does not contain it as a whole token (`1.2.3` matches `tool v1.2.3`, not `1.2.30`). A script under `.agents/guards/` cannot take one. |
115
+ | `targets` | list | required | Any `[hooks] targets` runtime. A runtime in `[hooks] targets` runs it in the hook bundle; otherwise Codex, Gemini and Antigravity use the shell adapter, and Claude, Grok and OpenCode are an error. |
116
+ | `timeout_ms` | integer | `15000` | 100 to 60000. |
117
+ | `on` | string | `"before_shell"` | `before_shell`, `after_edit`, `prompt`, `stop` or `session_start`. |
118
+ | `mode` | string | `"deny"` | `deny`, `ask`, `warn`, `observe` or `off`, as for a built-in guard. |
119
+
120
+ What a refusal (`mode = "deny"`) does depends on the event and the runtime; pmcp
121
+ renders it as each runtime's hooks can take it, and where one cannot, the reason
122
+ goes nowhere:
123
+
124
+ | `on` | Claude Code | Codex | Gemini, OpenCode | Antigravity | Grok |
125
+ | --------------- | ------------------------------------ | ------------------------------------ | --------------------- | ---------------------------------- | ----------------------------------------------- |
126
+ | `before_shell` | refuses the call (`ask` asks) | refuses the call | refuses the call | refuses the call | refuses the call |
127
+ | `after_edit` | the reason as feedback | the reason as feedback | the reason as context | nothing | the reason as context |
128
+ | `prompt` | blocks the prompt, with the reason | blocks the prompt, with the reason | the reason as context | the reason as a message | nothing |
129
+ | `stop` | keeps the turn going with the reason | keeps the turn going with the reason | nothing | continues the turn with the reason | the reason as context, which continues the turn |
130
+ | `session_start` | the reason as context | the reason as context | the reason as context | the reason as a message | the reason as context at its next tool call |
131
+
132
+ With `mode = "warn"` the reason reaches every runtime as context, at that event
133
+ or, where the runtime takes none there, at the next event that carries context.
134
+ A session cannot be refused at its start, so on `session_start` the modes
135
+ `deny` and `ask` act as `warn`. `ask` asks only in Claude Code; elsewhere
136
+ `[hooks] ask_fallback` decides. A turn kept going by `stop` is not kept going
137
+ again by the stop that ends it.
138
+
139
+ ### The guard contract, `pmcp.guard.v1`
140
+
141
+ The command gets one JSON object on stdin:
142
+
143
+ ```json
144
+ {
145
+ "protocol": "pmcp.guard.v1",
146
+ "runtime": "claude",
147
+ "event": "before_shell",
148
+ "session": "<session id>",
149
+ "command": "<the shell command, or empty>",
150
+ "cwd": "<the session's directory>",
151
+ "paths": ["<the edited paths, after_edit>"],
152
+ "prompt": "<the prompt text, on prompt only>"
153
+ }
154
+ ```
155
+
156
+ It runs in the project root with only `PATH` and `LANG`, and answers on stdout
157
+ with one JSON object and exit 0:
108
158
 
109
- | Key | Type | Default | Meaning |
110
- | ------------ | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
111
- | `name` | string | required | `^[a-z0-9][a-z0-9-]*$`, unique across custom, shell and edit entries. |
112
- | `command` | argv list | required | The first or second element is the script, which must exist inside `.agents/guards/`; its sha256 is pinned in `policy.json`. |
113
- | `targets` | list | required | Any `[hooks] targets` runtime. A runtime in `[hooks] targets` runs it in the hook bundle; otherwise Codex, Gemini and Antigravity use the shell adapter, and Claude, Grok and OpenCode are an error. |
114
- | `timeout_ms` | integer | `15000` | 100 to 60000. |
115
- | `on` | string | `"before_shell"` | `before_shell` or `after_edit`. |
159
+ ```json
160
+ {
161
+ "decision": "deny",
162
+ "reason": "why",
163
+ "findings": [{ "path": "src/a.ts", "line": 3, "message": "what is wrong" }]
164
+ }
165
+ ```
116
166
 
117
- The script receives the JSON contract described under
118
- [Deprecated shell guards](#deprecated-shell-guards). Custom guards have no `mode`.
167
+ `decision` is `allow` or `deny`; `reason` and `findings` are optional, and
168
+ `protocol`, when echoed, must be `pmcp.guard.v1`. Each finding needs `message`
169
+ and may give `path` and `line` (a whole number from 1). Up to 20 findings are
170
+ added to a refusal's reason, one `path:line: message` line each, and findings
171
+ with `allow` reach the session as a note; either way the guard log records how
172
+ many there were. Any other reply, a nonzero exit, or running past `timeout_ms`
173
+ is a failed guard, which refuses. A guard written for the earlier contract, which
174
+ had no `protocol`, `session`, `prompt` or `findings`, keeps working unchanged.
175
+
176
+ `mode` means what it does for a built-in guard: the script runs and its refusal
177
+ is a deny, an ask, a note in the session's context (`warn`), or only a log line
178
+ (`observe`); `off` does not run it. The guard log records the script's own
179
+ verdict as `raw` in every mode. Only the hook bundle applies a mode: a runtime
180
+ the shell adapter serves (Codex, Gemini or Antigravity outside `[hooks]
181
+ targets`) can only refuse, so a mode other than `deny` there is a configuration
182
+ error naming the guard, the mode and the runtime. The same holds for `on` other
183
+ than `before_shell` or `after_edit` and for an installed program with `version`:
184
+ the shell adapter runs neither, and keeps the earlier contract below.
185
+
186
+ A command that needs to end a session's turn with a check of its own (tests, a
187
+ linter, a generated-file check) is a custom guard with `on = "stop"` and
188
+ `mode = "warn"`.
189
+
190
+ ## `[hooks.report]`
191
+
192
+ Read by [`pmcp hooks report`](commands.md#hooks) alone; it changes nothing in the
193
+ hooks.
194
+
195
+ | Key | Type | Default | Meaning |
196
+ | ------------------ | ---- | ------- | --------------------------------------------------------------------------------- |
197
+ | `exclude_sessions` | list | `[]` | Regexes; guard log lines of a session id matching one are left out of the report. |
198
+
199
+ ## `[hooks.test]`
200
+
201
+ | Key | Type | Default | Meaning |
202
+ | ---------- | ---- | ------- | --------------------------------------------------------------------------------------------- |
203
+ | `fixtures` | path | none | The cases `pmcp project --check --smoke` runs; relative to the directory holding `pmcp.toml`. |
204
+
205
+ A fixtures file is JSON: `{cases, failure?}`. Each case is
206
+ `{name, guard, command, cwd?, expect}`, where `guard` is the guard the case is
207
+ about (`shell.heredoc`, `custom.<name>`), `cwd = "linked-worktree"` runs it from a
208
+ scratch repository with a branch checked out in a linked worktree, and `expect`
209
+ is `allow`, `deny` or `ask` for every runtime, or a table of runtime to one of
210
+ them (a runtime left out does not run the case). `failure`, when present, must
211
+ equal the projected `[hooks.failure]` (`{timeoutMs, retry, pass}`).
212
+
213
+ `pmcp hooks test --fixtures <file>` and `pmcp project --check --smoke` run each
214
+ case through the projected `.agents/pmcp-hooks/hook.mjs`, once per `[hooks]
215
+ targets` runtime that answers a shell call, with that runtime's own payload. The
216
+ command is classified by the guards, never run; state goes to a throwaway
217
+ `XDG_STATE_HOME`, and `GIT_*` variables are removed, so a run from inside a git
218
+ hook does not look at the repository being committed. Findings:
219
+
220
+ - a decision that differs from `expect`, or a hook that fails or times out;
221
+ - coverage: every guard that can refuse (`deny`, `ask` or `graded`, including
222
+ custom guards on `before_shell`) needs, per runtime, one case it refuses and
223
+ one it lets through;
224
+ - `[hooks.failure]` differing from the fixtures' `failure`;
225
+ - a target whose native hook entry is missing, and a run in which no case ran.
226
+
227
+ `hooks test --fixtures` exits 0 with no finding and 1 otherwise; `project --check
228
+ --smoke` exits 2 on a finding, as for drift.
119
229
 
120
230
  ## `[hooks.failure]`
121
231
 
@@ -166,6 +276,24 @@ as `projector.json`), and only at the version `pmcp.lock` records. A pmcp on
166
276
  `PATH` is never used. When none matches, the session hears
167
277
  `projecting pmcp not available` once instead of a drift report.
168
278
 
279
+ ## Native hook entries pmcp does not own
280
+
281
+ Hook entries a project or a tool wrote itself run beside pmcp's, and a broken one
282
+ fails every call it matches. `pmcp project --check` (exit 2) and `pmcp doctor`
283
+ check each such entry in `.claude/settings.json`, `.claude/settings.local.json`,
284
+ `.codex/hooks.json`, and the `hooks/hooks.json` (or the manifest's `hooks` path)
285
+ of each plugin whose `.claude-plugin/plugin.json` is tracked by git. Entries that
286
+ run `.agents/pmcp-hooks/` are pmcp's and are not checked here.
287
+
288
+ The command's first simple command is read, never run. A leading `NAME=value`
289
+ is skipped; `$CLAUDE_PROJECT_DIR` is the project root, `${CLAUDE_PLUGIN_ROOT}` the
290
+ plugin's directory (an error outside a plugin), and `~` and `$HOME` the home
291
+ directory. A program run directly must be an existing file that is executable
292
+ and starts with `#!`; a script given to an interpreter (`node`, `bun`, `deno`,
293
+ `tsx`, `python`, `python3`, `bash`, `sh`, `zsh`, `dash`, `ruby`, `perl`) must
294
+ exist. A bare program name found on `PATH`, inline code (`node -e`) and a path
295
+ built from another variable are not checked.
296
+
169
297
  ## Runtime support
170
298
 
171
299
  From the measured capability files in `docs/hooks/capabilities/` (Claude Code
@@ -58,7 +58,8 @@ ignored.
58
58
  | `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
59
59
  | `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
60
60
  | `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
61
- | `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]` | [Hooks](hooks.md) |
61
+ | `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]`, `[hooks.failure]`, `[hooks.report]`, `[hooks.test]` | [Hooks](hooks.md) |
62
+ | `[budget]` | [Budget](#budget) |
62
63
  | `[[hooks.shell]]`, `[[hooks.edit]]` | [Deprecated shell guards](hooks.md#deprecated-shell-guards) |
63
64
  | `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]` | [Sessions](#sessions) |
64
65
  | `[git]`, `[git.shared_checkout]`, `[git.worktrees]`, `[git.worktrees.sync]`, `[git.mainline]`, `[git.mainline.gate]`, `[git.mainline.deliver]`, `[git.mainline.sync]`, `[git.submodules]` | [Git workflow](git-workflow.md) |
@@ -579,6 +580,31 @@ messages too.
579
580
 
580
581
  Worktrees, delivery to the mainline and main checkout sync: [Git workflow](git-workflow.md).
581
582
 
583
+ ## Budget
584
+
585
+ `[budget]` sets limits on what every agent session loads and on paths the
586
+ project keeps out of its tree. `pmcp project --check` exits 2 when one is
587
+ exceeded, naming each, and `pmcp status` shows the measurements beside the
588
+ limits (its JSON gains `budget: {rows, problems}`, and an exceeded limit counts
589
+ as drift). Every key is optional; nothing is checked without the table.
590
+
591
+ | Key | Type | Meaning |
592
+ | --------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
593
+ | `root_bytes` | integer | Largest size of each of `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` at the root that is a file (a symbolic link to another is not measured twice). |
594
+ | `root_lines` | integer | Largest line count of the same files. |
595
+ | `package_bytes` | integer | Largest size of each tracked `AGENTS.md` below the root, and of each `[rules.packages] file`. |
596
+ | `skills_max` | integer | Most skills under `.agents/skills` (each a folder with a `SKILL.md`), the skills every runtime is offered. |
597
+ | `forbid_paths` | glob list | Tracked paths that must not exist: `*` within a segment, `**` across segments, `?` one character; a glob naming a directory covers everything below it (`docs/adr`). |
598
+
599
+ ```toml
600
+ [budget]
601
+ root_bytes = 16000
602
+ root_lines = 300
603
+ package_bytes = 8000
604
+ skills_max = 40
605
+ forbid_paths = [".spec/**", "docs/adr"]
606
+ ```
607
+
582
608
  ## Logging
583
609
 
584
610
  | `[logging]` key | Type | Default | Allowed |
package/docs/upgrading.md CHANGED
@@ -5,6 +5,48 @@
5
5
  What to do when a release changes something you rely on. Each release's notes on GitHub
6
6
  Releases list its breaking changes and link here.
7
7
 
8
+ ## From 0.20 to 0.21
9
+
10
+ **Session records are written to `sessions/` alone.** 0.20 also wrote each record to the
11
+ deprecated `fleet/` in the state directory; 0.21 stops. A tool that still reads `fleet/`
12
+ must read `sessions/<session>.json` instead. pmcp still reads `fleet/`, and of two copies
13
+ uses the one updated last, so a hook bundle from before 0.20 sharing the state directory
14
+ keeps being followed until `pmcp project` runs there again.
15
+
16
+ **`pmcp project --check` also fails on a broken hook entry pmcp does not own.** A command
17
+ in `.claude/settings*.json`, `.codex/hooks.json` or a tracked plugin's `hooks.json` that
18
+ names a missing script, or a script run directly that is not executable or has no `#!`
19
+ line, now makes `--check` exit 2 and `pmcp doctor` report a failure. Fix the entry, or the
20
+ script; [Hooks](hooks.md#native-hook-entries-pmcp-does-not-own) lists what is checked.
21
+
22
+ The rest is new, not removed:
23
+
24
+ - A commit that only moves submodule pins, each to a commit the mainline's pin already
25
+ equals or contains, now counts as delivered. `pmcp git deliver` skips it, and
26
+ `pmcp git sync` and worktree sync move past it instead of refusing.
27
+ - `[git.mainline.sync] after_deliver = "always"` also syncs the main checkout after a
28
+ delivery run in a linked worktree; `"off"` turns the sync after a delivery off. The
29
+ default `"from_main"` is 0.20's behaviour.
30
+ - With `gate = "pre-push"` the push output streams to the terminal as it comes; the gate
31
+ log still keeps all of it.
32
+ - The `pmcp git deliver --json` receipt gains `sync`, the main checkout's sync after the
33
+ delivery, and `replayed`, the tip of the last replay.
34
+ - `pmcp git deliver --no-push` replays and gates, then stops. See
35
+ [Git workflow](git-workflow.md).
36
+ - `[[hooks.guards.custom]]` takes `mode` like a built-in guard (the default `deny` is
37
+ 0.20's behaviour), `on = "prompt"`, `"stop"` or `"session_start"`, and an installed
38
+ program pinned by `version` instead of a script. Its request gains `protocol`
39
+ (`pmcp.guard.v1`), `session` and, on `prompt`, `prompt`; its reply may add `findings`.
40
+ A guard that reads only the earlier fields keeps working. See
41
+ [Hooks](hooks.md#hooksguardscustom).
42
+ - `pmcp hooks report` summarises the guard log; `[hooks.report] exclude_sessions` leaves
43
+ sessions out.
44
+ - `pmcp hooks test --fixtures <file>`, and `pmcp project --check --smoke` with
45
+ `[hooks.test] fixtures`, run cases through the projected hooks.
46
+ - `[budget]` limits the root and package instruction files, the skills and the tracked
47
+ paths; `pmcp project --check` enforces it and `pmcp status` shows it. See
48
+ [Budget](project-configuration.md#budget).
49
+
8
50
  ## From 0.19 to 0.20
9
51
 
10
52
  0.20 removes defaults that suited one kind of project rather than pmcp's users in general.
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "pmcp",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "mcpServers": {
5
5
  "pmcp": {
6
6
  "type": "stdio",
7
7
  "command": "npx",
8
- "args": ["-y", "@modootoday/pmcp@0.20.0", "serve"]
8
+ "args": ["-y", "@modootoday/pmcp@0.21.0", "serve"]
9
9
  }
10
10
  }
11
11
  }
package/mcp.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "pmcp": {
5
5
  "type": "stdio",
6
6
  "command": "npx",
7
- "args": ["-y", "@modootoday/pmcp@0.20.0", "serve"]
7
+ "args": ["-y", "@modootoday/pmcp@0.21.0", "serve"]
8
8
  }
9
9
  }
10
10
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@modootoday/pmcp",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "license": "Elastic-2.0",
5
5
  "author": "modootoday",
6
6
  "description": "Use the skills your packages already ship, and keep your AI tools' project configuration in one place.",
@@ -136,9 +136,9 @@
136
136
  "bun": ">=1.3.0"
137
137
  },
138
138
  "optionalDependencies": {
139
- "@modootoday/pmcp-linux-x64": "0.20.0",
140
- "@modootoday/pmcp-linux-arm64": "0.20.0",
141
- "@modootoday/pmcp-darwin-x64": "0.20.0",
142
- "@modootoday/pmcp-darwin-arm64": "0.20.0"
139
+ "@modootoday/pmcp-linux-x64": "0.21.0",
140
+ "@modootoday/pmcp-linux-arm64": "0.21.0",
141
+ "@modootoday/pmcp-darwin-x64": "0.21.0",
142
+ "@modootoday/pmcp-darwin-arm64": "0.21.0"
143
143
  }
144
144
  }
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "pmcp",
4
- "version": "0.20.0",
4
+ "version": "0.21.0",
5
5
  "description": "Find package skills and use native runtime project configuration.",
6
6
  "author": { "name": "modootoday" },
7
7
  "license": "Elastic-2.0",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pmcp",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "description": "Find package skills and use native runtime project configuration.",
5
5
  "author": { "name": "modootoday" },
6
6
  "license": "Elastic-2.0",
@@ -3,7 +3,7 @@
3
3
  "pmcp": {
4
4
  "type": "stdio",
5
5
  "command": "npx",
6
- "args": ["-y", "@modootoday/pmcp@0.20.0", "serve"]
6
+ "args": ["-y", "@modootoday/pmcp@0.21.0", "serve"]
7
7
  }
8
8
  }
9
9
  }
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "pmcp",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "mcpServers": {
5
5
  "pmcp": {
6
6
  "type": "stdio",
7
7
  "command": "npx",
8
- "args": ["-y", "@modootoday/pmcp@0.20.0", "serve"]
8
+ "args": ["-y", "@modootoday/pmcp@0.21.0", "serve"]
9
9
  }
10
10
  }
11
11
  }
@@ -4,7 +4,7 @@
4
4
  "pmcp": {
5
5
  "type": "stdio",
6
6
  "command": "npx",
7
- "args": ["-y", "@modootoday/pmcp@0.20.0", "serve"]
7
+ "args": ["-y", "@modootoday/pmcp@0.21.0", "serve"]
8
8
  }
9
9
  }
10
10
  }
@@ -4,8 +4,8 @@ import type { Broadcast, Lease, Pause, SessionRecord } from "./types";
4
4
 
5
5
  export const STATE_FILES = {
6
6
  records: "sessions",
7
- // The records' former directory. Deprecated: 0.20 still writes every record there too and
8
- // reads it when sessions/ lacks one; 0.21 stops writing it.
7
+ // The records' former directory. Deprecated: read beside sessions/ but no longer written; a
8
+ // pmcp before 0.20 sharing the state directory still writes there.
9
9
  legacyRecords: "fleet",
10
10
  pause: "pause.json",
11
11
  broadcast: "broadcast.json",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "pmcp",
4
- "version": "0.20.0",
4
+ "version": "0.21.0",
5
5
  "description": "Find package skills and use native runtime project configuration.",
6
6
  "author": { "name": "modootoday" },
7
7
  "license": "Elastic-2.0",
@@ -1,130 +0,0 @@
1
- import {
2
- missingBinary,
3
- nativeBinary,
4
- readLock
5
- } from "./chunk-66F3HLW4.js";
6
- import {
7
- VERSION
8
- } from "./chunk-FGYFA6JY.js";
9
- import {
10
- pickEnv
11
- } from "./chunk-J6KL3COD.js";
12
-
13
- // src/project/host.ts
14
- import { createHash } from "crypto";
15
- import { existsSync, readFileSync } from "fs";
16
- import { join } from "path";
17
- var HOST_DIRECTORY = ".agents/pmcp-pty";
18
- var HOST_MANIFEST = `${HOST_DIRECTORY}/host.json`;
19
- var HOST_POLICY = `${HOST_DIRECTORY}/policy.json`;
20
- function hostPolicy(host) {
21
- const browser = host.browser.allowPrivate;
22
- const launch = host.desktop.launch;
23
- return {
24
- version: 1,
25
- mcp_write: host.mcpWrite,
26
- roots: host.roots,
27
- allow: host.answers.map((a) => ({
28
- profile: a.runtime,
29
- dialog: a.dialog,
30
- options: a.options
31
- })),
32
- ...browser.length > 0 ? { browser: { allow_private: browser } } : {},
33
- ...launch.length > 0 ? { desktop: { launch } } : {}
34
- };
35
- }
36
- function hostManifest(host) {
37
- return {
38
- version: 1,
39
- sessions: host.sessions.map((s) => ({
40
- name: s.name,
41
- profile: s.runtime,
42
- cwd: s.cwd,
43
- argv: s.argv,
44
- labels: { ...s.labels, "pmcp.host": s.name },
45
- restart: s.restart,
46
- max_restarts: s.maxRestarts,
47
- delivery_setup: true,
48
- // Only when declared, so an approval made before env existed stays valid.
49
- ...s.env.length > 0 ? { env: s.env } : {}
50
- }))
51
- };
52
- }
53
- var json = (value) => `${JSON.stringify(value, null, 2)}
54
- `;
55
- function hostOutputs(spec) {
56
- if (!spec.host) return [];
57
- return [
58
- {
59
- kind: "file",
60
- path: HOST_MANIFEST,
61
- content: json(hostManifest(spec.host))
62
- },
63
- { kind: "file", path: HOST_POLICY, content: json(hostPolicy(spec.host)) }
64
- ];
65
- }
66
- function ptyBinary(env) {
67
- return nativeBinary("pmcp-pty", "PMCP_PTY_BIN", env);
68
- }
69
- function ptyBinaryDoctor(env) {
70
- const found = ptyBinary(env);
71
- return found ? { tool: "project", check: "pmcp-pty binary", status: "ok", detail: found } : {
72
- tool: "project",
73
- check: "pmcp-pty binary",
74
- status: "warn",
75
- detail: missingBinary("pmcp-pty", "PMCP_PTY_BIN", VERSION)
76
- };
77
- }
78
- function hostEnvDoctor(spec, env) {
79
- return (spec.host?.sessions ?? []).filter((s) => s.env.length > 0).map((s) => {
80
- const { missing } = pickEnv(s.env, env);
81
- return missing.length === 0 ? {
82
- tool: "project",
83
- check: `host env (${s.name})`,
84
- status: "ok",
85
- detail: `set: ${s.env.join(", ")}`
86
- } : {
87
- tool: "project",
88
- check: `host env (${s.name})`,
89
- status: "warn",
90
- detail: `not set: ${missing.join(", ")}; host up refuses ${s.name} until they are`
91
- };
92
- });
93
- }
94
- var sha256 = (text) => createHash("sha256").update(text).digest("hex");
95
- function hostDoctor(spec) {
96
- if (!spec.host) return [];
97
- const lock = new Map(readLock(spec.root).map((e) => [e.path, e]));
98
- const bad = [HOST_MANIFEST, HOST_POLICY].filter((path) => {
99
- const file = join(spec.root, path);
100
- if (!existsSync(file)) return true;
101
- const entry = lock.get(path);
102
- return entry?.sha256 !== sha256(readFileSync(file, "utf8"));
103
- });
104
- const { sessions, answers, mcpWrite } = spec.host;
105
- const summary = `${sessions.length} session(s), ${answers.length} answer rule(s), mcp_write ${mcpWrite}`;
106
- return [
107
- bad.length === 0 ? {
108
- tool: "project",
109
- check: "pmcp-pty host projected",
110
- status: "ok",
111
- detail: summary
112
- } : {
113
- tool: "project",
114
- check: "pmcp-pty host projected",
115
- status: "fail",
116
- detail: `run pmcp project: ${bad.join(", ")}`
117
- }
118
- ];
119
- }
120
-
121
- export {
122
- HOST_MANIFEST,
123
- HOST_POLICY,
124
- hostOutputs,
125
- ptyBinary,
126
- ptyBinaryDoctor,
127
- hostEnvDoctor,
128
- hostDoctor
129
- };
130
- //# sourceMappingURL=chunk-7SDOSTW7.js.map