@modootoday/pmcp 0.18.0 → 0.18.3
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.
- package/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +2 -2
- package/.mcp.json +1 -1
- package/CONTRIBUTING.md +80 -0
- package/README.md +100 -206
- package/SECURITY.md +17 -1
- package/dist/{apply-4IGTXOCQ.js → apply-S2QI72W3.js} +13 -13
- package/dist/{available-DBSIVVJ6.js → available-GFMTJW4E.js} +3 -3
- package/dist/{broadcast-3RY3OZGY.js → broadcast-CBMVOV3G.js} +4 -4
- package/dist/{chunk-SG5TPMKH.js → chunk-26WLNWDG.js} +2 -2
- package/dist/{chunk-4VCC2NXE.js → chunk-2RTRY45B.js} +2 -2
- package/dist/{chunk-3NYG4SGU.js → chunk-3MEYKFFO.js} +3 -3
- package/dist/{chunk-KMXRRSKT.js → chunk-4CRRLDDS.js} +1 -1
- package/dist/{chunk-ZH6R642Z.js → chunk-4GSGT55G.js} +2 -2
- package/dist/{chunk-EJBZGIDK.js → chunk-6BN35BHI.js} +3 -3
- package/dist/{chunk-T3LKX23M.js → chunk-7B6IC3F7.js} +3 -3
- package/dist/{chunk-25GHX674.js → chunk-7DEYLLIE.js} +9 -9
- package/dist/{chunk-ELAGZ635.js → chunk-7PTG42QU.js} +5 -5
- package/dist/chunk-AF2IBMWN.js +7 -0
- package/dist/{chunk-IGYRMM62.js → chunk-CKTN6LKP.js} +2 -2
- package/dist/{chunk-PLX3BOOS.js → chunk-E5XVSMBR.js} +2 -2
- package/dist/{chunk-Q65R3XKX.js → chunk-EAWPJHJ7.js} +2 -2
- package/dist/{chunk-7BLPN3W6.js → chunk-F5LEGPGP.js} +2 -2
- package/dist/{chunk-BBTBJCFA.js → chunk-F5WBMUOT.js} +2 -2
- package/dist/{chunk-YMHUM7AV.js → chunk-F5XMGOOX.js} +7 -1
- package/dist/{chunk-R4L6LJJ2.js → chunk-FX3LTTMB.js} +2 -2
- package/dist/{chunk-5QQWS4US.js → chunk-HEBCQTOD.js} +2 -2
- package/dist/{chunk-NZS5CD72.js → chunk-HEWZ6INU.js} +21 -5
- package/dist/{chunk-MWFOUBFC.js → chunk-HFE4QDJQ.js} +2 -2
- package/dist/{chunk-N5AQ3PP7.js → chunk-HQWVGU3W.js} +5 -5
- package/dist/{chunk-UOCLRM7P.js → chunk-IIBB37JE.js} +22 -22
- package/dist/{chunk-MPSQXSC6.js → chunk-ISZOLR3D.js} +5 -3
- package/dist/{chunk-J6QLLQVL.js → chunk-JM2KR2WJ.js} +5 -5
- package/dist/{chunk-CJTKR6K6.js → chunk-JZK7ZO7K.js} +2 -2
- package/dist/{chunk-RK4PYD7L.js → chunk-LBXO4VPG.js} +2 -2
- package/dist/{chunk-BVCTKPT3.js → chunk-LMUBBIE2.js} +2 -2
- package/dist/{chunk-Z4HRRXRF.js → chunk-LTZH5E3G.js} +6 -5
- package/dist/{chunk-MM2Y43LC.js → chunk-M455QSCW.js} +3 -3
- package/dist/{chunk-7GBYECSK.js → chunk-NLHLA2N5.js} +3 -3
- package/dist/{chunk-HDMBVLCZ.js → chunk-NWOV2E26.js} +2 -2
- package/dist/{chunk-PWSJJXLQ.js → chunk-QK4G7FCU.js} +8 -8
- package/dist/{chunk-47O3X4VS.js → chunk-QRCAGKC6.js} +1 -1
- package/dist/{chunk-665TA55Z.js → chunk-TAOOPXBV.js} +2 -2
- package/dist/{chunk-JUXNIXN4.js → chunk-TZORR6GZ.js} +2 -2
- package/dist/{chunk-LAZQBMAU.js → chunk-WM2RF2MI.js} +3 -3
- package/dist/{chunk-65ZHM5RH.js → chunk-XJUNAVU2.js} +9 -9
- package/dist/{chunk-TNCZ6444.js → chunk-Y2XASHVY.js} +2 -2
- package/dist/{cli-VYCQJZ5X.js → cli-MI4ZCAZ3.js} +9 -9
- package/dist/{cli-ZTCBSDW4.js → cli-ZN7ZVDEZ.js} +3 -3
- package/dist/cli.js +4 -4
- package/dist/{completion-E7RRG3ZT.js → completion-GYN7PX3T.js} +3 -3
- package/dist/{diagnostics-XXH4FLUG.js → diagnostics-WACXQ33W.js} +6 -6
- package/dist/{doctor-ZIOESU3N.js → doctor-VSQ72A6X.js} +13 -13
- package/dist/{entry-ZNFCTDVE.js → entry-VFEZC2XB.js} +10 -10
- package/dist/{exec-mcp-X6372BLE.js → exec-mcp-TOQEJFK3.js} +8 -8
- package/dist/{harness-F2XFDYXF.js → harness-XCEWFGCG.js} +5 -5
- package/dist/harness-launch-gate.js +4 -4
- package/dist/harness-worker.js +6 -6
- package/dist/hook-body.js +7 -6
- package/dist/{hooks-FYE2L5RW.js → hooks-32AFBC3Z.js} +3 -3
- package/dist/{host-X6BR6X4O.js → host-72OLHUX7.js} +20 -10
- package/dist/{host-GRY3VAHH.js → host-TE5PNDHJ.js} +7 -7
- package/dist/{host-run-GCA6H6SR.js → host-run-MXCH26ZD.js} +5 -5
- package/dist/http.js +5 -5
- package/dist/{import-mcp-2TTBPVLY.js → import-mcp-QWGZSIZR.js} +6 -6
- package/dist/index.d.ts +1 -1
- package/dist/index.js +18 -18
- package/dist/{init-627KFXTG.js → init-5M3XWOTJ.js} +2 -2
- package/dist/{install-GG7HHZK2.js → install-MQ7QSJQ7.js} +3 -3
- package/dist/{invoke-LW22Z6ET.js → invoke-SFSN4XT7.js} +8 -8
- package/dist/{list-MCP2FXUF.js → list-FB6RNYYB.js} +3 -3
- package/dist/{list-NGMSQ5SH.js → list-FGDUU5DL.js} +8 -8
- package/dist/{logout-6CSHUWWE.js → logout-KM5N5GOC.js} +7 -7
- package/dist/{logs-SPB6AANY.js → logs-TBUA4UWU.js} +4 -4
- package/dist/mailbox/index.js +4 -4
- package/dist/{mailbox-GDJ7BWQN.js → mailbox-5DWLH4W2.js} +3 -3
- package/dist/{mailbox-7BV54Q4R.js → mailbox-BMTZOSZ7.js} +4 -4
- package/dist/{mainline-JQTTYJMI.js → mainline-KAD2ERLP.js} +2 -2
- package/dist/{mcp-V23HC3LB.js → mcp-FJ2UQ4RH.js} +2 -2
- package/dist/{mcp-2DKVU3SW.js → mcp-ND6ZQWJE.js} +2 -2
- package/dist/{pause-FFAYRBWI.js → pause-7LILUVGL.js} +4 -4
- package/dist/{project-FY62G55N.js → project-LZKQUV2W.js} +4 -4
- package/dist/{reindex-Y27QJFDB.js → reindex-ZULHSQWY.js} +5 -5
- package/dist/{resume-UU4HZIUP.js → resume-26VFAAMH.js} +4 -4
- package/dist/{run-HALGEJNJ.js → run-X4663F4M.js} +4 -4
- package/dist/{run-OGA3P7FC.js → run-YEVGHGTN.js} +7 -7
- package/dist/{serve-NBKT5BKY.js → serve-S7MF42SS.js} +12 -12
- package/dist/{start-login-UIQYQBMC.js → start-login-GKFGTE2A.js} +7 -7
- package/dist/{status-NOOHW5WA.js → status-FYG6XYQ6.js} +7 -7
- package/dist/{status-VHODZPXB.js → status-RO55QPKV.js} +4 -4
- package/dist/{status-XQANBVXW.js → status-XG5GRWVU.js} +11 -11
- package/dist/stdio.js +7 -7
- package/dist/{sweep-64JDCGK6.js → sweep-35LGQTTO.js} +4 -4
- package/dist/{test-MKAXFJOL.js → test-KFDO6ROC.js} +7 -7
- package/dist/{tui-MWKAXE4K.js → tui-2MP7DRIX.js} +5 -5
- package/dist/{unbroadcast-KPUEFLZD.js → unbroadcast-5QNGAJR2.js} +4 -4
- package/dist/{validate-5GZ5YWNA.js → validate-AVM2VHMM.js} +4 -4
- package/dist/{worker-RQ575EJL.js → worker-3VS6RQEL.js} +8 -8
- package/docs/authoring.md +82 -0
- package/docs/browser-and-desktop.md +46 -0
- package/docs/commands.md +325 -0
- package/docs/compare.md +35 -0
- package/docs/compatibility.md +56 -0
- package/docs/embeddings.md +1 -1
- package/docs/getting-started.md +105 -0
- package/docs/git-workflow.md +60 -0
- package/docs/glossary.md +31 -0
- package/docs/hooks.md +264 -0
- package/docs/install.md +72 -0
- package/docs/known-issues.md +17 -0
- package/docs/library-skills.md +132 -0
- package/docs/mailbox.md +16 -5
- package/docs/project-configuration.md +51 -386
- package/docs/sessions.md +64 -0
- package/docs/skills.md +4 -45
- package/docs/terminal-harness.md +26 -21
- package/docs/terminal-workspace.md +4 -13
- package/docs/upgrading.md +23 -0
- package/gemini-extension.json +2 -2
- package/mcp.json +1 -1
- package/package.json +8 -7
- package/plugin.json +2 -2
- package/plugins/pmcp/.claude-plugin/plugin.json +2 -2
- package/plugins/pmcp/.mcp.json +1 -1
- package/plugins/pmcp/gemini-extension.json +2 -2
- package/plugins/pmcp/mcp.json +1 -1
- package/plugins/pmcp/mod/sessions/types.ts +1 -1
- package/plugins/pmcp/plugin.json +2 -2
- package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +8 -8
- package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +12 -11
- package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +10 -8
- package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +0 -4
- package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
- package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
- package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +19 -11
- package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +20 -28
- package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +16 -15
- package/schema/catalog-v1.json +36 -7
- package/schema/library.json +40 -8
- package/schema/marketplace-manifest.json +19 -5
- package/schema/plugin-manifest.json +6 -2
- package/schema/skill-frontmatter.json +33 -7
- package/schema/skill-metadata-core.json +26 -5
- package/skills/agent-assets-migrate/SKILL.md +8 -8
- package/skills/headless-agents-ci-scaffold/SKILL.md +12 -11
- package/skills/marketplace-plugin-scaffold/SKILL.md +10 -8
- package/skills/package-skill-catalog/SKILL.md +0 -4
- package/skills/pmcp-browser/SKILL.md +27 -0
- package/skills/pmcp-desktop/SKILL.md +25 -0
- package/skills/pmcp-project-init/SKILL.md +19 -11
- package/skills/pmcp-sessions-and-git/SKILL.md +20 -28
- package/skills/skill-package-scaffold/SKILL.md +16 -15
- package/CHANGELOG.md +0 -60
- package/dist/chunk-E7OOHLQR.js +0 -7
- package/docs/manual-library-skills.md +0 -74
|
@@ -1,7 +1,11 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pmcp.toml reference
|
|
2
2
|
|
|
3
3
|
[Back to the overview](../README.md)
|
|
4
4
|
|
|
5
|
+
Every table `pmcp.toml` accepts, with its keys and defaults. Task guides cover the larger
|
|
6
|
+
parts: [Hooks](hooks.md), [Run several agents](sessions.md), [Git workflow](git-workflow.md),
|
|
7
|
+
[Browser and desktop](browser-and-desktop.md) and [Library skills](library-skills.md).
|
|
8
|
+
|
|
5
9
|
## Project config
|
|
6
10
|
|
|
7
11
|
A `pmcp.toml` at or above the working directory sets the catalog once, so a
|
|
@@ -52,10 +56,10 @@ ignored.
|
|
|
52
56
|
| `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
|
|
53
57
|
| `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
|
|
54
58
|
| `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
|
|
55
|
-
| `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]` | [Hooks](
|
|
56
|
-
| `[[hooks.shell]]`, `[[hooks.edit]]` | [
|
|
59
|
+
| `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]` | [Hooks](hooks.md) |
|
|
60
|
+
| `[[hooks.shell]]`, `[[hooks.edit]]` | [Deprecated shell guards](hooks.md#deprecated-shell-guards) |
|
|
57
61
|
| `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]` | [Sessions](#sessions) |
|
|
58
|
-
| `[git]`, `[git.shared_checkout]`, `[git.worktrees]`, `[git.worktrees.sync]`, `[git.mainline]`, `[git.mainline.gate]`, `[git.mainline.deliver]`, `[git.mainline.sync]`, `[git.submodules]` | [Git workflow](
|
|
62
|
+
| `[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) |
|
|
59
63
|
| `[logging]`, `[logging.components]` | [Logging](#logging) |
|
|
60
64
|
| `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
|
|
61
65
|
| `[ui.claude]` | [Claude session panes](#claude-session-panes) |
|
|
@@ -146,12 +150,14 @@ overwritten. `doctor` calls no model: it reads `claude mcp list`,
|
|
|
146
150
|
## Sessions pmcp-pty hosts
|
|
147
151
|
|
|
148
152
|
`[host]` names the sessions pmcp-pty runs for this project and the few dialog
|
|
149
|
-
answers
|
|
153
|
+
answers you allow it to give. `pmcp project` writes them to
|
|
150
154
|
`.agents/pmcp-pty/host.json` (the sessions) and `.agents/pmcp-pty/policy.json`
|
|
151
155
|
(answers, `mcp_write`, roots), pinned in `pmcp.lock` like every output, and
|
|
152
156
|
`pmcp doctor` reports whether they match. pmcp.toml is writable by agents, so
|
|
153
|
-
neither file takes effect by being projected: pmcp-pty loads only a copy
|
|
154
|
-
|
|
157
|
+
neither file takes effect by being projected: pmcp-pty loads only a copy you
|
|
158
|
+
approved. Running the host (`pmcp harness host up`) needs Linux with a
|
|
159
|
+
user systemd manager; on macOS it refuses, and `pmcp tui` or a harness group is
|
|
160
|
+
the way to run sessions there.
|
|
155
161
|
|
|
156
162
|
```toml
|
|
157
163
|
[host]
|
|
@@ -184,7 +190,7 @@ review dialogs are never answered: a `[[host.answers]]` entry naming one is a
|
|
|
184
190
|
configuration error, and pmcp-pty refuses them whatever a policy says. Paths
|
|
185
191
|
stay project-relative, so the projected files hold no host path.
|
|
186
192
|
`[host.browser]` and `[[host.desktop.launch]]` widen
|
|
187
|
-
[pmcp-browser and pmcp-desktop](
|
|
193
|
+
[pmcp-browser and pmcp-desktop](browser-and-desktop.md) and act only
|
|
188
194
|
from the approved copy too; a launch entry that starts a browser is an error.
|
|
189
195
|
|
|
190
196
|
### Approving the host policy
|
|
@@ -215,45 +221,7 @@ owned by root.
|
|
|
215
221
|
|
|
216
222
|
## Browser and desktop for agents
|
|
217
223
|
|
|
218
|
-
|
|
219
|
-
desktop apps, not on a Linux server. Two MCP servers built from this
|
|
220
|
-
repository cover that ground for every runtime pmcp projects to:
|
|
221
|
-
|
|
222
|
-
- `pmcp-browser` (`crates/pmcp-plugin-browser-use`): an isolated Chromium,
|
|
223
|
-
headless, with a fresh profile per launch. It reaches public http(s) sites
|
|
224
|
-
only: every request goes through its own proxy, which refuses loopback,
|
|
225
|
-
private, link-local, metadata and CGNAT addresses and every port but 80 and 443. Local schemes such as `file:` are blocked in the page.
|
|
226
|
-
- `pmcp-desktop` (`crates/pmcp-plugin-computer-use`): an Xvfb desktop driven
|
|
227
|
-
through screenshots and XTEST input, for any X11 app.
|
|
228
|
-
|
|
229
|
-
Each runs in its own memory-capped systemd scope (2G and 512M by default),
|
|
230
|
-
and `pmcp-browser` allows two at a time on the host. Both have `doctor`
|
|
231
|
-
(read-only, with the exact fix) and `setup --plan`; root steps are printed,
|
|
232
|
-
never run. Both ship in the Linux platform package npm installs with PMCP
|
|
233
|
-
(glibc 2.35 or later), which does not put them on PATH. Declare them like
|
|
234
|
-
any MCP server with the bare name as `command`; `pmcp project` resolves it to
|
|
235
|
-
the installed binary, so pmcp.toml names no host path:
|
|
236
|
-
|
|
237
|
-
```toml
|
|
238
|
-
[mcp.pmcp-browser]
|
|
239
|
-
command = "pmcp-browser"
|
|
240
|
-
args = ["serve", "--approved", "<the directory pmcp harness host status reports>"]
|
|
241
|
-
|
|
242
|
-
[mcp.pmcp-desktop]
|
|
243
|
-
command = "pmcp-desktop"
|
|
244
|
-
args = ["serve", "--geometry", "1440x900x24"]
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
`pmcp doctor` reports where each resolved, or why not (no platform
|
|
248
|
-
package for this host, as on macOS); an unresolved name runs from PATH. An
|
|
249
|
-
absolute `command`, such as your own build, is kept as written.
|
|
250
|
-
|
|
251
|
-
The names avoid Claude Code's built-in `computer-use`. `--approved` is
|
|
252
|
-
optional: without it the browser is public-only and the desktop launches
|
|
253
|
-
nothing. `[host.browser] allow_private` and `[[host.desktop.launch]]` come
|
|
254
|
-
into force only through `pmcp harness host approve`. Running the browser
|
|
255
|
-
headed on the desktop's display also needs the managed Chromium policy that
|
|
256
|
-
`pmcp-browser setup --plan` prints for the operator to install.
|
|
224
|
+
pmcp-browser and pmcp-desktop, and how to declare them: [Browser and desktop](browser-and-desktop.md).
|
|
257
225
|
|
|
258
226
|
## Claude permission rules
|
|
259
227
|
|
|
@@ -304,13 +272,6 @@ the hook guards stay its enforcement.
|
|
|
304
272
|
|
|
305
273
|
## Unified project MCP configuration
|
|
306
274
|
|
|
307
|
-
Antigravity receives a native project plugin at .agents/plugins/pmcp-mcp with
|
|
308
|
-
plugin.json and mcp_config.json. Projection removes only lock-owned entries
|
|
309
|
-
from the earlier .agents/mcp_config.json artifact and backs up both layouts.
|
|
310
|
-
Antigravity's global mcp list does not enumerate project plugin servers;
|
|
311
|
-
validate the generated plugin with agy plugin validate.
|
|
312
|
-
Its HTTP entries use serverUrl, accepted by the installed plugin validator.
|
|
313
|
-
|
|
314
275
|
Declare each MCP server once in pmcp.toml. The projector writes the native
|
|
315
276
|
project files for all selected runtimes. A server can narrow its targets:
|
|
316
277
|
|
|
@@ -388,6 +349,15 @@ Configuration references: [Codex](https://developers.openai.com/codex/config-ref
|
|
|
388
349
|
[Gemini CLI](https://geminicli.com/docs/tools/mcp-server/),
|
|
389
350
|
and [Grok Build](https://docs.x.ai/build/features/mcp-servers).
|
|
390
351
|
|
|
352
|
+
### Antigravity
|
|
353
|
+
|
|
354
|
+
Antigravity receives a native project plugin at `.agents/plugins/pmcp-mcp` with
|
|
355
|
+
`plugin.json` and `mcp_config.json`. Projection removes only lock-owned entries
|
|
356
|
+
from the earlier `.agents/mcp_config.json` artifact and backs up both layouts.
|
|
357
|
+
Antigravity's global mcp list does not enumerate project plugin servers;
|
|
358
|
+
validate the generated plugin with `agy plugin validate`.
|
|
359
|
+
Its HTTP entries use `serverUrl`, accepted by the installed plugin validator.
|
|
360
|
+
|
|
391
361
|
## OpenCode project support
|
|
392
362
|
|
|
393
363
|
Add opencode to targets.tools to project MCP entries into the project-root
|
|
@@ -405,9 +375,8 @@ OpenCode; explicitly limit those servers to other targets when needed.
|
|
|
405
375
|
OpenCode discovers .agents/skills directly, so PMCP creates no skill copies or
|
|
406
376
|
links. For invocation=user, projection sets permission.skill.<name> to deny:
|
|
407
377
|
the model's skill list omits that name, while the native /<name> command still
|
|
408
|
-
loads its original SKILL.md and accepts user arguments
|
|
409
|
-
|
|
410
|
-
without an external model call. It controls automatic skill selection, not
|
|
378
|
+
loads its original SKILL.md and accepts user arguments (measured: see
|
|
379
|
+
[Compatibility](compatibility.md#installation-and-packaging)). It controls automatic skill selection, not
|
|
411
380
|
arbitrary file access. Native global skill discovery remains a user preference.
|
|
412
381
|
|
|
413
382
|
pmcp doctor checks opencode debug skill and opencode mcp list without calling
|
|
@@ -464,226 +433,35 @@ OAuth ownership and env_from behavior. Provider authentication remains native.
|
|
|
464
433
|
|
|
465
434
|
## Hooks
|
|
466
435
|
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
small loader) and `hook-body.mjs`, and registers `hook.mjs` in
|
|
470
|
-
`.claude/settings.json` and `.codex/hooks.json` for the events the declared
|
|
471
|
-
features use. Gemini, Antigravity, Grok and OpenCode are opt-in: name them in
|
|
472
|
-
`[hooks] targets` and pmcp registers the same hook in their files (see
|
|
473
|
-
[Runtime support](#runtime-support)). `pmcp.lock` pins the hash of `policy.json`; the hook refuses to
|
|
474
|
-
act on a policy that does not match it, so every policy change is a reviewed
|
|
475
|
-
projection. Codex shows changed entries under `/hooks` as needing review;
|
|
476
|
-
untrusted hooks do not run. Each Codex, Claude and Grok entry carries a
|
|
477
|
-
`statusMessage` such as `pmcp session start` or `pmcp before tool`: Codex
|
|
478
|
-
lists hooks under that name, and Claude and Grok show it while the hook runs.
|
|
479
|
-
Gemini entries keep their `name` (`pmcp-<event>`), which is part of the
|
|
480
|
-
identity Gemini trusts.
|
|
481
|
-
|
|
482
|
-
The hook keeps two per-user caches under `$XDG_CACHE_HOME/pmcp` (default
|
|
483
|
-
`~/.cache/pmcp`), never in the project: Node's compile cache for the body
|
|
484
|
-
(`hook-compile/`) and the last integrity verdict per `policy.json`
|
|
485
|
-
(`hook-verified.json`). A verdict is reused only while neither `policy.json`
|
|
486
|
-
nor `pmcp.lock` has been written since. Either cache can be missing or
|
|
487
|
-
unwritable without changing a decision; `PMCP_HOOK_COMPILE_CACHE=off` turns the
|
|
488
|
-
compile cache off.
|
|
489
|
-
|
|
490
|
-
Every feature is opt-in: a table that is missing turns its feature off, and a
|
|
491
|
-
declared table, even an empty one, turns it on. The exceptions are documented
|
|
492
|
-
where they apply: `[git]` features detect git (`enabled = "auto"`),
|
|
493
|
-
`[git.shared_checkout]` is on in any git checkout once the bundle exists, and
|
|
494
|
-
logging falls back to its defaults rather than to no logging. The bundle is
|
|
495
|
-
projected only when `[hooks]` declares guards or checks, a `[sessions.*]`
|
|
496
|
-
feature table is declared, `[git.shared_checkout]` or `[git.worktrees.sync]` is
|
|
497
|
-
declared, or `[git.mainline.deliver]` keeps `refuse_direct_push`.
|
|
498
|
-
|
|
499
|
-
### `[hooks]`
|
|
500
|
-
|
|
501
|
-
| Key | Type | Default | Meaning |
|
|
502
|
-
| -------------------- | ------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
503
|
-
| `targets` | list | `[targets] tools` limited to `claude`, `codex` | Runtimes that receive the hook bundle: `claude`, `codex`, `gemini`, `antigravity`, `grok`, `opencode`. The last four are used only when listed here. |
|
|
504
|
-
| `ask_fallback` | string | `"deny"` | What an ask becomes on a runtime without ask (Codex, Gemini, Antigravity, Grok, OpenCode): `deny`, `warn`, or `refuse` to make projection fail while any guard may ask. |
|
|
505
|
-
| `error_log` | bool or path | `true` | `true` writes JSONL logs under the state directory's `logs/`; a project-relative path writes one file there instead; `false` turns hook logging off. |
|
|
506
|
-
| `emergency_off_file` | path | none | While this file exists every guard passes. `~`, `$HOME/` and absolute paths are allowed; other paths are relative to the project. |
|
|
507
|
-
|
|
508
|
-
### `[hooks.guards.<group>.<name>]`
|
|
509
|
-
|
|
510
|
-
Each built-in guard is one table. `mode` is the only key the option-less
|
|
511
|
-
guards take; an unknown option is an error. Modes: `deny` and `ask` replace
|
|
512
|
-
the guard's verdict with that mode, `warn` turns the reason into context the
|
|
513
|
-
agent reads, `off` drops the guard, and `graded` keeps the guard's own split
|
|
514
|
-
between ask and deny.
|
|
515
|
-
|
|
516
|
-
| Table | Default mode | Modes | Refuses |
|
|
517
|
-
| ------------------------------------------ | ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
518
|
-
| `[hooks.guards.shell.in_place_edit]` | deny | deny, ask, warn, off | `sed -i`, `perl -i`, `awk -i inplace`: edits without a diff. |
|
|
519
|
-
| `[hooks.guards.shell.heredoc]` | deny | deny, ask, warn, off | Heredocs and here-strings, whose body the shell expands silently. |
|
|
520
|
-
| `[hooks.guards.shell.stdin_interpreter]` | ask | deny, ask, warn, off | An interpreter reading its program from stdin (`python3 -`, `cat x.py \| python3`). |
|
|
521
|
-
| `[hooks.guards.shell.compose_teardown]` | deny | deny, ask, warn, off | `docker compose down`, and `stop`, `rm` or `kill` with no service named: they hit every service. |
|
|
522
|
-
| `[hooks.guards.shell.secret_exfiltration]` | graded | deny, ask, warn, off, graded | Reading a credential asks; sending one over the network, or changing a live one, denies. |
|
|
523
|
-
| `[hooks.guards.shell.host_approval]` | deny | deny, ask, warn, off | `host approve`, and commands or edits touching the host approvals directory. On by itself when `[host]` is declared. |
|
|
524
|
-
| `[hooks.guards.git.push_without_verify]` | deny | deny, ask, warn, off | `git push --no-verify`. |
|
|
525
|
-
| `[hooks.guards.git.forced_branch_move]` | deny | deny, ask, warn, off | Forcing a branch that is checked out in another working tree. |
|
|
526
|
-
| `[hooks.guards.git.gate_bypass_env]` | deny | deny, ask, warn, off | Setting a named gate-bypass variable where it takes effect, and optionally `--no-verify` on any git command. |
|
|
527
|
-
| `[hooks.guards.git.stage_all]` | deny | deny, ask, warn, off | `git add -A`, `git add .`, `git commit -a` and similar; stage explicit paths. |
|
|
528
|
-
|
|
529
|
-
Options:
|
|
530
|
-
|
|
531
|
-
- `[hooks.guards.shell.secret_exfiltration]`: `extra_secret_paths` (list of
|
|
532
|
-
case-insensitive regular expressions, default `[]`), and
|
|
533
|
-
`[[hooks.guards.shell.secret_exfiltration.value_commands]]` entries for a
|
|
534
|
-
CLI that prints or publishes secret values: `binary` (required), `read`
|
|
535
|
-
(verbs that print a value, so reading asks) and `publish` (verbs that change
|
|
536
|
-
a live value, so they deny). Built in are `.env` files, `.dev.vars`, private
|
|
537
|
-
keys, `.npmrc`, `.netrc`, `auth.json` and service-account files; a file whose
|
|
538
|
-
name merely contains "secret" or "credential" is not one, so list such files
|
|
539
|
-
in `extra_secret_paths`. Only a file a command reads counts: a search
|
|
540
|
-
pattern, a sed or awk script, a jq filter or `-e` code that mentions `.env`
|
|
541
|
-
does not.
|
|
542
|
-
- `[hooks.guards.git.gate_bypass_env]`: `names` (variable names, default `[]`)
|
|
543
|
-
and `no_verify` (boolean, default `true`).
|
|
544
|
-
|
|
545
|
-
A mention is not a match: commands are parsed into steps, so
|
|
546
|
-
`git commit -m "never git push --no-verify"` and `echo 'cat <<EOF'` pass. A
|
|
547
|
-
command the parser cannot read is judged by a conservative pattern instead.
|
|
548
|
-
|
|
549
|
-
### `[[hooks.guards.custom]]`
|
|
550
|
-
|
|
551
|
-
A project script under `.agents/guards/` that decides like a built-in guard.
|
|
552
|
-
|
|
553
|
-
| Key | Type | Default | Meaning |
|
|
554
|
-
| ------------ | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
555
|
-
| `name` | string | required | `^[a-z0-9][a-z0-9-]*$`, unique across custom, shell and edit entries. |
|
|
556
|
-
| `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`. |
|
|
557
|
-
| `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. |
|
|
558
|
-
| `timeout_ms` | integer | `15000` | 100 to 60000. |
|
|
559
|
-
| `on` | string | `"before_shell"` | `before_shell` or `after_edit`. |
|
|
560
|
-
|
|
561
|
-
The script receives the JSON contract described under
|
|
562
|
-
[Operator shell guards](#operator-shell-guards). Custom guards have no `mode`.
|
|
563
|
-
|
|
564
|
-
### `[hooks.checks.after_edit]` and `[hooks.checks.on_stop]`
|
|
565
|
-
|
|
566
|
-
Checks report through context and never block; a check that cannot run is
|
|
567
|
-
logged and stays quiet.
|
|
568
|
-
|
|
569
|
-
| Table | Key | Type | Default | Meaning |
|
|
570
|
-
| --------------------------- | ------------------ | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
571
|
-
| `[hooks.checks.after_edit]` | `validator_glob` | glob | required | Validator scripts inside the project; after an edit, only the validators whose directory owns an edited path run. |
|
|
572
|
-
| | `command` | argv list | required | Must contain `{validator}`, replaced by the validator's path. Runs directly, never through a shell. |
|
|
573
|
-
| | `debounce_seconds` | number | `60` | One run per validator per window. |
|
|
574
|
-
| | `report` | string | `"context"` | The only value. |
|
|
575
|
-
| `[hooks.checks.on_stop]` | `project_check` | boolean | `true` | After a turn that edited files, run `pmcp project --check` and report drift. |
|
|
576
|
-
| | `report` | string | `"context"` | The only value. |
|
|
577
|
-
|
|
578
|
-
The stop check runs the checkout's own pmcp (`node_modules`), else the CLI that
|
|
579
|
-
last projected this checkout on this machine (recorded in the state directory
|
|
580
|
-
as `projector.json`), and only at the version `pmcp.lock` records. A pmcp on
|
|
581
|
-
`PATH` is never used. When none matches, the session hears
|
|
582
|
-
`projecting pmcp not available` once instead of a drift report.
|
|
583
|
-
|
|
584
|
-
### Runtime support
|
|
585
|
-
|
|
586
|
-
From the measured capability files in `docs/hooks/capabilities/` (Claude Code
|
|
587
|
-
2.1.303, Codex 0.163.0, including live sessions). `pmcp doctor` prints the same
|
|
588
|
-
table for your project, with Codex trust.
|
|
589
|
-
|
|
590
|
-
| Feature | Claude Code | Codex |
|
|
591
|
-
| ---------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------- |
|
|
592
|
-
| sessions registry, pause, leases, broadcast | measured | measured |
|
|
593
|
-
| `[sessions.roles.<name>]` | works; not live-measured | unsupported: Codex sends no `agent_type` |
|
|
594
|
-
| `[git.shared_checkout]`, `[git.worktrees.sync]`, `[git.mainline.deliver]` | measured | measured |
|
|
595
|
-
| heredoc, compose_teardown, push_without_verify, forced_branch_move, gate_bypass_env, stage_all | measured | measured |
|
|
596
|
-
| in_place_edit, stdin_interpreter, secret_exfiltration (ask) | ask not measured | ask lowered by `ask_fallback` |
|
|
597
|
-
| host_approval | works; not live-measured | works; not live-measured |
|
|
598
|
-
| `[hooks.checks.after_edit]` | measured | measured |
|
|
599
|
-
| `[hooks.checks.on_stop]` | measured, in the same turn | at the next prompt |
|
|
600
|
-
| `[[hooks.guards.custom]]` | not measured | not measured |
|
|
601
|
-
| `[ui.claude]` | Claude only | not applicable |
|
|
602
|
-
|
|
603
|
-
Codex limits that shape the projection:
|
|
604
|
-
|
|
605
|
-
- Codex has no ask. An ask becomes `ask_fallback` (`deny` by default).
|
|
606
|
-
- Codex sends no `agent_type`, so roles cannot apply there.
|
|
607
|
-
- Codex rejects context on Stop, so Stop notices are delivered at the next
|
|
608
|
-
prompt.
|
|
609
|
-
- Codex clamps a SessionEnd hook to 3 s; pmcp projects at most 3 s for it.
|
|
610
|
-
- Codex has no Notification event.
|
|
611
|
-
- Codex's own command filter rejects a fully quoted executable before any hook
|
|
612
|
-
runs; use the ordinary unquoted form.
|
|
613
|
-
|
|
614
|
-
Gemini CLI 0.63.0, Antigravity (`agy`) 1.4.2, Grok 1.0.62 and OpenCode 1.18.33
|
|
615
|
-
are opt-in `[hooks] targets`. The pmcp bundle ran live on each in the same
|
|
616
|
-
thirteen scenarios as Claude Code and Codex, judged from each runtime's own
|
|
617
|
-
transcript; the `live` block of each capability file names the runs. A context
|
|
618
|
-
a runtime does not deliver at an event is held and delivered at the next event
|
|
619
|
-
that does, and that was measured live too. On OpenCode, prompt context goes
|
|
620
|
-
into the system prompt, which OpenCode does not store, so its delivery is shown
|
|
621
|
-
by a probe rather than by the prompt scenario. agy runs prompt policies on
|
|
622
|
-
every turn: its counter resets per turn.
|
|
623
|
-
|
|
624
|
-
| Feature | Gemini | Antigravity | Grok | OpenCode |
|
|
625
|
-
| ------------------------------------------- | ---------------------------- | ----------------------------- | ---------------------------- | ---------------------------- |
|
|
626
|
-
| refusing a tool call (guards, pause, git) | measured deny | measured deny | measured deny | measured (thrown error) |
|
|
627
|
-
| context (broadcast, warnings) | start, prompt, after tool | first model call, Stop | tool events, Stop | start, prompt, after tool |
|
|
628
|
-
| `[sessions.registry]` | every event | tool events, first call, Stop | every event | every event |
|
|
629
|
-
| `[sessions.roles.<name>]` | unsupported: no `agent_type` | unsupported: no `agent_type` | unsupported: no `agent_type` | unsupported: no `agent_type` |
|
|
630
|
-
| ask (in_place_edit, stdin_interpreter, ...) | lowered by `ask_fallback` | lowered by `ask_fallback` | lowered by `ask_fallback` | lowered by `ask_fallback` |
|
|
631
|
-
| `[hooks.checks.on_stop]` | at the next delivering event | Stop continues once | in the same turn | at the next prompt |
|
|
632
|
-
| `[[hooks.guards.custom]]` | not measured | not measured | not measured | not measured |
|
|
633
|
-
|
|
634
|
-
Where each runtime's projection goes, and what it needs:
|
|
635
|
-
|
|
636
|
-
- Gemini: `.gemini/settings.json` `hooks`, timeouts in milliseconds. Gemini
|
|
637
|
-
ignores project settings in a folder the user has not trusted, and records
|
|
638
|
-
each new hook in `~/.gemini/trusted_hooks.json`; `pmcp doctor` reads both
|
|
639
|
-
and reports them, and never writes them. Trusting the folder is the user's
|
|
640
|
-
step in an interactive `gemini` session.
|
|
641
|
-
- Antigravity: one named set `pmcp` in `.agents/hooks.json`, beside the shell
|
|
642
|
-
adapter's `pmcp-shell`. agy denies a tool call whose hook names no decision,
|
|
643
|
-
so pmcp always writes one. agy has no session or prompt event: the first
|
|
644
|
-
model call of a conversation is the session start, the first of a later
|
|
645
|
-
turn the prompt. Whether that counter resets for a later prompt in an
|
|
646
|
-
interactive session is not measured. No trust step.
|
|
647
|
-
- Grok: grok also runs `.claude/settings.json` hooks, so with `claude` in
|
|
648
|
-
`[hooks] targets` pmcp writes only the Claude file and the hook recognises a
|
|
649
|
-
grok call by its payload; with Grok alone it writes `.grok/hooks/pmcp.json`.
|
|
650
|
-
Never both, or every check would run twice. Project hooks run only after
|
|
651
|
-
the user runs `/hooks-trust`; `pmcp doctor` reads
|
|
652
|
-
`~/.grok/trusted_folders.toml` without writing it.
|
|
653
|
-
- OpenCode: there are no shell hooks, so pmcp writes `.opencode/plugins/pmcp.js`,
|
|
654
|
-
a small plugin pinned in `pmcp.lock` that passes each call to the hook. A
|
|
655
|
-
refusal is thrown as an error; Stop (`session.idle`) only updates the
|
|
656
|
-
registry. No trust step.
|
|
657
|
-
|
|
658
|
-
`auth = "pmcp"` MCP servers project through `pmcp project exec-mcp` for every
|
|
659
|
-
runtime above.
|
|
436
|
+
Guards, checks and session bookkeeping for every targeted runtime, and which runtime supports
|
|
437
|
+
what: [Hooks](hooks.md).
|
|
660
438
|
|
|
661
439
|
## Sessions
|
|
662
440
|
|
|
663
441
|
Sessions coordinate agents working in one repository and its worktrees. State
|
|
664
442
|
lives in one directory shared by every checkout of the repository.
|
|
665
443
|
|
|
666
|
-
| `[sessions]` key | Type | Default | Meaning
|
|
667
|
-
| ---------------- | ------ | ----------------------------------------------------------- |
|
|
668
|
-
| `store` | string | `"files"` | The only store.
|
|
669
|
-
| `state_dir` | path | `$XDG_STATE_HOME/pmcp/projects/<id>` (`~/.local/state/...`) | `<id>` is the first 16 hex digits of the sha256 of the git common directory. `~`, `~/` and `$HOME/` expand to the home directory and a relative path is relative to the main checkout: the directory holding `pmcp.toml`, taken in the worktree of the git common directory, so the main checkout and every linked
|
|
444
|
+
| `[sessions]` key | Type | Default | Meaning |
|
|
445
|
+
| ---------------- | ------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
446
|
+
| `store` | string | `"files"` | The only store. |
|
|
447
|
+
| `state_dir` | path | `$XDG_STATE_HOME/pmcp/projects/<id>` (`~/.local/state/...`) | `<id>` is the first 16 hex digits of the sha256 of the git common directory. `~`, `~/` and `$HOME/` expand to the home directory and a relative path is relative to the main checkout: the directory holding `pmcp.toml`, taken in the worktree of the git common directory, so the main checkout and every linked worktree share one state. Outside git it is relative to the directory holding `pmcp.toml`. The hooks, the Claude Code session panes and the git commands resolve it the same way; so does `[git.mainline.gate] tree`. |
|
|
670
448
|
|
|
671
449
|
`store` and `state_dir` alone enable nothing; each feature has its own table:
|
|
672
450
|
|
|
673
|
-
| Table | Keys
|
|
674
|
-
| -------------------------- |
|
|
675
|
-
| `[sessions.registry]` | `liveness` (`"pid_heartbeat"`, the only value), `stale_minutes` (default `30`)
|
|
676
|
-
| `[sessions.pause]` | `mode` (`deny` default, `ask`, `warn`, `off`), `refuses` (`"mutating"`), `scripts` (regular expressions, default `[]`: a `node` script matching one also counts as mutating, e.g. your own
|
|
677
|
-
| `[sessions.broadcast]` | `keep` (default `10`), `deliver_on` (default `["session_start", "prompt", "before_tool"]`; also `after_tool`, `stop`)
|
|
678
|
-
| `[sessions.leases.<name>]` | `path` (string, shown in the message and used by git delivery), `blocks` (required list of argv prefixes)
|
|
679
|
-
| `[sessions.roles.<name>]` | `agent_type` (default `<name>`, also matches `plugin:<name>`), `allow_edits` (default `false`), `allow_commands` (list of argv prefixes, default `[]`)
|
|
451
|
+
| Table | Keys | Effect |
|
|
452
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
453
|
+
| `[sessions.registry]` | `liveness` (`"pid_heartbeat"`, the only value), `stale_minutes` (default `30`) | Records each session with its process and heartbeat; `pmcp sessions status` lists them. |
|
|
454
|
+
| `[sessions.pause]` | `mode` (`deny` default, `ask`, `warn`, `off`), `refuses` (`"mutating"`), `scripts` (regular expressions, default `[]`: a `node` script matching one also counts as mutating, e.g. your own delivery or sync script) | While `pmcp sessions pause` is in effect, edits and mutating commands are refused for every session but the one that paused; reading continues. |
|
|
455
|
+
| `[sessions.broadcast]` | `keep` (default `10`), `deliver_on` (default `["session_start", "prompt", "before_tool"]`; also `after_tool`, `stop`) | Delivers `pmcp sessions broadcast` text once to each session, as context on the listed events. |
|
|
456
|
+
| `[sessions.leases.<name>]` | `path` (string, shown in the message and used by git delivery), `blocks` (required list of argv prefixes) | While another session holds lease `<name>`, commands starting with a listed prefix are denied until its delivery finishes. |
|
|
457
|
+
| `[sessions.roles.<name>]` | `agent_type` (default `<name>`, also matches `plugin:<name>`), `allow_edits` (default `false`), `allow_commands` (list of argv prefixes, default `[]`) | A subagent of that type may edit only if allowed and run only the listed commands. Claude only. |
|
|
680
458
|
|
|
681
459
|
These tables have no `mode`, except pause. Without `[sessions.registry]` no
|
|
682
460
|
session is recorded, and `[ui.claude]` refuses to project.
|
|
683
461
|
|
|
684
462
|
### `[sessions.mailbox]`
|
|
685
463
|
|
|
686
|
-
Addressed messages between sessions and
|
|
464
|
+
Addressed messages between sessions, and between you and them. A missing table leaves
|
|
687
465
|
the mailbox off; a declared one, even empty, turns it on.
|
|
688
466
|
|
|
689
467
|
| Key | Type | Default | Meaning |
|
|
@@ -698,8 +476,9 @@ Each message is one file, `<state>/messages/<id>.json`, created atomically and
|
|
|
698
476
|
never rewritten: `id`, `from` (session and alias), `to`, `subject`, `body`,
|
|
699
477
|
`createdAt`, `expiresAt`, `replyTo`, `once`. `to` lists selectors: `all`,
|
|
700
478
|
`session:<id>` (a prefix of at least eight characters works), `alias:<name>`,
|
|
701
|
-
`role:<name>` (a `[sessions.roles]` name or the agent type), or `
|
|
702
|
-
(
|
|
479
|
+
`role:<name>` (a `[sessions.roles]` name or the agent type), or `worktree:<path>`
|
|
480
|
+
(a linked worktree's path, or its directory name; `desk:<path>` is an older
|
|
481
|
+
spelling that still works). A message to `all` reaches the
|
|
703
482
|
sessions that were running when it was sent; a session the registry records
|
|
704
483
|
later does not get earlier broadcasts. Delivery and acknowledgement are
|
|
705
484
|
empty markers under `<state>/inbox/<session>/`, so a message is never edited
|
|
@@ -714,7 +493,7 @@ acknowledgement. A message sent with `--once` says it is a one-time request,
|
|
|
714
493
|
so the recipient does not keep its instructions as standing rules.
|
|
715
494
|
|
|
716
495
|
```sh
|
|
717
|
-
pmcp sessions send --to alias:reviewer --to role:
|
|
496
|
+
pmcp sessions send --to alias:reviewer --to role:delivery --subject deploy --once "Hold the deploy until 14:00"
|
|
718
497
|
echo "longer body" | pmcp sessions send --to all -
|
|
719
498
|
pmcp sessions inbox [--session <id>] [--all] [--json]
|
|
720
499
|
pmcp sessions ack <id>... [--session <id>]
|
|
@@ -781,64 +560,13 @@ hook file only when a session starts.
|
|
|
781
560
|
With the mailbox on, `pmcp sessions broadcast` also sends its text as a
|
|
782
561
|
message to `all`, and the mailbox delivers it instead of
|
|
783
562
|
`[sessions.broadcast]`; `broadcast.json` and each session's `seenBroadcast`
|
|
784
|
-
are still written, so `pmcp sessions status`, the
|
|
785
|
-
Claude
|
|
563
|
+
are still written, so `pmcp sessions status`, the session list and the
|
|
564
|
+
Claude Code session panes read broadcasts as before. `unbroadcast` withdraws those
|
|
786
565
|
messages too.
|
|
787
566
|
|
|
788
567
|
## Git workflow
|
|
789
568
|
|
|
790
|
-
|
|
791
|
-
| ----------- | --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
792
|
-
| `enabled` | `"auto"`, true, false | `"auto"` | `auto` turns the git features on when the project is a git checkout; `false` turns all of them off. |
|
|
793
|
-
| `remote` | string | `origin` if present, else the first remote | |
|
|
794
|
-
| `mainline` | string or table | the remote's HEAD branch, else `main` | A string names the branch; a table (`[git.mainline]` with `branch`) also holds gate, deliver and sync. |
|
|
795
|
-
|
|
796
|
-
`[git.shared_checkout]` warns a session working in the main checkout of a
|
|
797
|
-
repository that also has worktrees (desks), tracks the files it edits there,
|
|
798
|
-
and names unlanded leftovers, because they block syncing the shared main for
|
|
799
|
-
everyone. Keys: `enabled` (`"auto"` default, following `[git] enabled`, or a
|
|
800
|
-
boolean), `warn_on_session`, `track_edits`, `warn_claimants` (booleans, default
|
|
801
|
-
`true`). It is on in any git checkout without a table, once something else
|
|
802
|
-
enables the hook bundle.
|
|
803
|
-
|
|
804
|
-
`[git.worktrees]` configures desks for `pmcp git worktree`:
|
|
805
|
-
|
|
806
|
-
| Key | Type | Default |
|
|
807
|
-
| ---------------- | --------- | -------------------------- |
|
|
808
|
-
| `root` | string | `".claude/worktrees"` |
|
|
809
|
-
| `branch_prefix` | string | `"worktree-"` |
|
|
810
|
-
| `alias_pattern` | regex | `"^[a-z][a-z0-9-]{1,30}$"` |
|
|
811
|
-
| `bootstrap` | argv list | none |
|
|
812
|
-
| `link_from_main` | list | `[]` |
|
|
813
|
-
|
|
814
|
-
`[git.worktrees.sync]` (opt-in) keeps each desk on the mainline when moving it
|
|
815
|
-
loses nothing: `on_session_start` (`"fetch_and_move"` default, `"move"`,
|
|
816
|
-
`"off"`), `between_prompts` (`"move_if_light"` default, `"off"`: move only when
|
|
817
|
-
no install is needed), `install_after_move` (`"off"` default, `"background"`,
|
|
818
|
-
`"foreground"`) and `notice_paths` (paths whose change is announced to the
|
|
819
|
-
session). Installs never block a session.
|
|
820
|
-
|
|
821
|
-
`[git.mainline.gate]`: `command` (argv; no gate when missing), `tree` (the
|
|
822
|
-
gate's worktree, default `<state dir>/gate/tree`; a relative path is relative to
|
|
823
|
-
the main checkout, like `state_dir`), `lock_wait_seconds`
|
|
824
|
-
(default `5400`).
|
|
825
|
-
|
|
826
|
-
`[git.mainline.deliver]` enables `pmcp git deliver`, which replays commits onto
|
|
827
|
-
the fetched mainline, runs the gate, and pushes one delivery at a time:
|
|
828
|
-
`attempts` (default `3`), `refuse_direct_push` (default `true`: a hook refuses
|
|
829
|
-
`git push` from any checkout of this repository, so the mainline moves only
|
|
830
|
-
through delivery), `during_pause` (`"refuse"` default or `"allow"`),
|
|
831
|
-
`lease_wait_seconds` (default `3600`) and `notify` (argv run after a
|
|
832
|
-
delivery).
|
|
833
|
-
|
|
834
|
-
`[git.mainline.sync]` enables `pmcp git sync`, which moves the main checkout to
|
|
835
|
-
the mainline: `install` (argv), `install_when_changed` (paths; when no
|
|
836
|
-
`[sessions.leases]` are declared, these become an implicit `lockfile` lease),
|
|
837
|
-
`keep_identical_files` and `refuse_with_unlanded` (booleans, default `true`).
|
|
838
|
-
|
|
839
|
-
`[git.submodules]`: `follow = "clean_pins"` (the default when the table is
|
|
840
|
-
present) moves submodules to the pinned commit when they are clean; `"off"`
|
|
841
|
-
leaves them. Without the table submodules are not followed.
|
|
569
|
+
Worktrees, delivery to the mainline and main checkout sync: [Git workflow](git-workflow.md).
|
|
842
570
|
|
|
843
571
|
## Logging
|
|
844
572
|
|
|
@@ -862,7 +590,7 @@ switches hook logging on or off. Read the logs with `pmcp logs`.
|
|
|
862
590
|
edited. It needs `[sessions.registry]`, and is written only when `claude` is
|
|
863
591
|
in `[targets] tools`. Without the table nothing is installed. `pmcp doctor`
|
|
864
592
|
shows the projected switches, or a failure until `pmcp project` writes them; it
|
|
865
|
-
cannot tell whether a running Claude Code loaded the
|
|
593
|
+
cannot tell whether a running Claude Code loaded the session panes.
|
|
866
594
|
|
|
867
595
|
## A complete example
|
|
868
596
|
|
|
@@ -918,7 +646,7 @@ publish = ["deploy", "secret put", "secret delete"]
|
|
|
918
646
|
[hooks.guards.git.stage_all]
|
|
919
647
|
|
|
920
648
|
[hooks.guards.git.gate_bypass_env]
|
|
921
|
-
names = ["ALLOW_DIRECT_PUSH", "
|
|
649
|
+
names = ["ALLOW_DIRECT_PUSH", "SKIP_GATE"]
|
|
922
650
|
|
|
923
651
|
[[hooks.guards.custom]]
|
|
924
652
|
name = "source-formatting"
|
|
@@ -949,7 +677,7 @@ max_delivered = 5
|
|
|
949
677
|
path = "package-lock.json"
|
|
950
678
|
blocks = [["npm", "install"], ["npm", "ci"], ["pmcp", "git", "deliver"]]
|
|
951
679
|
|
|
952
|
-
[sessions.roles.
|
|
680
|
+
[sessions.roles.delivery]
|
|
953
681
|
allow_commands = [["pmcp", "git", "deliver"], ["git", "log"], ["git", "status"]]
|
|
954
682
|
|
|
955
683
|
[git]
|
|
@@ -968,7 +696,7 @@ install = ["npm", "ci"]
|
|
|
968
696
|
install_when_changed = ["package-lock.json"]
|
|
969
697
|
|
|
970
698
|
[git.worktrees]
|
|
971
|
-
bootstrap = ["
|
|
699
|
+
bootstrap = ["sh", "scripts/setup-worktree.sh"]
|
|
972
700
|
link_from_main = [".env"]
|
|
973
701
|
|
|
974
702
|
[git.worktrees.sync]
|
|
@@ -992,69 +720,6 @@ source = { github = "example/team-marketplace" }
|
|
|
992
720
|
review = { targets = ["claude", "codex"] }
|
|
993
721
|
```
|
|
994
722
|
|
|
995
|
-
## Operator shell guards
|
|
996
|
-
|
|
997
|
-
Deprecated: `[[hooks.shell]]` and `[[hooks.edit]]` still work, and `pmcp project`
|
|
998
|
-
warns. Declare `[[hooks.guards.custom]]` instead, with `on = "before_shell"` or
|
|
999
|
-
`on = "after_edit"`, and list its runtimes in `[hooks] targets`: every runtime
|
|
1000
|
-
now has a hook bundle adapter, and this separate shell adapter will be removed
|
|
1001
|
-
in a later major release.
|
|
1002
|
-
|
|
1003
|
-
Declare a project-owned guard explicitly to project it into Codex, Gemini or
|
|
1004
|
-
Antigravity's native hooks. Without a declaration, pmcp generates no hooks.
|
|
1005
|
-
|
|
1006
|
-
```toml
|
|
1007
|
-
[[hooks.shell]]
|
|
1008
|
-
name = "shell-command-policy"
|
|
1009
|
-
command = ["node", ".agents/guards/shell-command-policy.mjs"]
|
|
1010
|
-
targets = ["codex", "gemini", "antigravity"]
|
|
1011
|
-
timeout_ms = 15000
|
|
1012
|
-
```
|
|
1013
|
-
|
|
1014
|
-
The guard script must exist under .agents/guards/ and cannot resolve outside
|
|
1015
|
-
that directory. It receives one JSON object on stdin containing runtime,
|
|
1016
|
-
event=before_shell, command and cwd. It returns a JSON object with
|
|
1017
|
-
decision=allow or decision=deny and an optional reason. Malformed responses,
|
|
1018
|
-
nonzero exits and timeouts deny the shell call. The guard receives PATH and
|
|
1019
|
-
LANG rather than the native CLI's credential environment. Non-shell tools are
|
|
1020
|
-
outside this contract.
|
|
1021
|
-
|
|
1022
|
-
Run pmcp project to write lock-owned adapter and policy artifacts under
|
|
1023
|
-
.agents/pmcp-hooks/, plus the native entries in .codex/hooks.json,
|
|
1024
|
-
.gemini/settings.json and .agents/hooks.json. Peer entries are retained.
|
|
1025
|
-
Edited owned hook entries refuse projection for review. Removing a declaration
|
|
1026
|
-
removes its generated entries and artifacts while preserving peer settings.
|
|
1027
|
-
Writes retain private backups; pmcp project --check only reports drift.
|
|
1028
|
-
|
|
1029
|
-
Guard, policy and adapter fingerprints bind the generated command. Changing
|
|
1030
|
-
guard code requires reprojection and native Codex hook review. Generated files
|
|
1031
|
-
contain no trust bypass. Grok can load Claude project hooks, so this first scope
|
|
1032
|
-
does not generate a second Grok guard. Hooks do not force pmcp catalog use,
|
|
1033
|
-
inject reminders or replace the runtime's execution sandbox.
|
|
1034
|
-
|
|
1035
|
-
## Operator edit guards
|
|
1036
|
-
|
|
1037
|
-
Codex edit guards run after apply_patch through native PostToolUse hooks:
|
|
1038
|
-
|
|
1039
|
-
```toml
|
|
1040
|
-
[[hooks.edit]]
|
|
1041
|
-
name = "edit-policy"
|
|
1042
|
-
command = ["node", ".agents/guards/edit-policy.mjs"]
|
|
1043
|
-
targets = ["codex"]
|
|
1044
|
-
timeout_ms = 15000
|
|
1045
|
-
```
|
|
1046
|
-
|
|
1047
|
-
The guard receives runtime=codex, event=after_edit, the patch in command and cwd.
|
|
1048
|
-
It returns the same allow/deny response as a shell guard. A denial becomes
|
|
1049
|
-
native blocking feedback with the reason; the completed file edit remains on disk
|
|
1050
|
-
for correction. Other tools do not invoke this guard. Edit targets currently
|
|
1051
|
-
support Codex only, and names must be unique across shell and edit declarations.
|
|
1052
|
-
|
|
1053
|
-
Run pmcp project after declaring or changing the guard, then review and trust
|
|
1054
|
-
the generated native definition in /hooks. Peer entries and shell guards are
|
|
1055
|
-
preserved. Fingerprints and failure handling follow the shell-guard contract.
|
|
1056
|
-
See the [native hooks documentation](https://learn.chatgpt.com/docs/hooks).
|
|
1057
|
-
|
|
1058
723
|
## Native memory metadata
|
|
1059
724
|
|
|
1060
725
|
```sh
|