@modootoday/pmcp 0.17.4 → 0.18.2

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 (272) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +2 -2
  4. package/.mcp.json +1 -1
  5. package/CHANGELOG.md +152 -0
  6. package/CONTRIBUTING.md +71 -0
  7. package/README.md +98 -201
  8. package/SECURITY.md +17 -1
  9. package/dist/apply-JUTGS5WZ.js +242 -0
  10. package/dist/{attachment-tU5FZrgZ.d.ts → attachment-D84OGI6n.d.ts} +1 -1
  11. package/dist/available-DBSIVVJ6.js +73 -0
  12. package/dist/broadcast-CBMVOV3G.js +18 -0
  13. package/dist/chunk-26WLNWDG.js +93 -0
  14. package/dist/chunk-2FIV63WC.js +252 -0
  15. package/dist/chunk-2P4Z2NUX.js +28 -0
  16. package/dist/chunk-34DECPVC.js +22 -0
  17. package/dist/chunk-3FCFAQDG.js +42 -0
  18. package/dist/chunk-3IDXEV5E.js +1934 -0
  19. package/dist/chunk-3PW4FI7U.js +32 -0
  20. package/dist/chunk-3Y3HDMHA.js +108 -0
  21. package/dist/chunk-47O3X4VS.js +113 -0
  22. package/dist/chunk-4NDEP7HU.js +26 -0
  23. package/dist/chunk-5OMOPUE6.js +39 -0
  24. package/dist/chunk-5QQWS4US.js +53 -0
  25. package/dist/chunk-5ZABTVSW.js +48 -0
  26. package/dist/chunk-65KAQSJP.js +7 -0
  27. package/dist/chunk-6STKGOCW.js +27 -0
  28. package/dist/chunk-6WXMJOMI.js +9 -0
  29. package/dist/chunk-73AKO4UL.js +24 -0
  30. package/dist/chunk-7DLZC73N.js +29 -0
  31. package/dist/chunk-7GBYECSK.js +72 -0
  32. package/dist/chunk-7HFIGCSL.js +419 -0
  33. package/dist/chunk-7TD53M7L.js +13 -0
  34. package/dist/chunk-7UCZAN4J.js +778 -0
  35. package/dist/chunk-A4PKLESO.js +112 -0
  36. package/dist/chunk-A7VF7A35.js +1025 -0
  37. package/dist/chunk-ABTJQ4QV.js +74 -0
  38. package/dist/chunk-AJ4VXM2U.js +349 -0
  39. package/dist/chunk-BBTBJCFA.js +380 -0
  40. package/dist/chunk-BU65MNVU.js +13 -0
  41. package/dist/chunk-C4NHQGHL.js +142 -0
  42. package/dist/chunk-CJTKR6K6.js +1213 -0
  43. package/dist/chunk-D77IRGHO.js +1246 -0
  44. package/dist/chunk-DCU2EXQV.js +78 -0
  45. package/dist/chunk-DMZHQZ7P.js +104 -0
  46. package/dist/chunk-DZ2MRTYT.js +135 -0
  47. package/dist/chunk-E2YOZ2FF.js +207 -0
  48. package/dist/chunk-E3DQB5LS.js +48 -0
  49. package/dist/chunk-EATCUWGG.js +66 -0
  50. package/dist/chunk-EAWPJHJ7.js +155 -0
  51. package/dist/chunk-EIDIVIAD.js +33 -0
  52. package/dist/chunk-F5QYZK7E.js +396 -0
  53. package/dist/chunk-F5XMGOOX.js +28 -0
  54. package/dist/chunk-FENOGX3U.js +31 -0
  55. package/dist/chunk-GZHHEHKY.js +44 -0
  56. package/dist/chunk-HDMBVLCZ.js +53 -0
  57. package/dist/chunk-HQOB7OQS.js +81 -0
  58. package/dist/chunk-I2ZP2PSA.js +211 -0
  59. package/dist/chunk-IG33DXLT.js +151 -0
  60. package/dist/chunk-IJBSOWHK.js +86 -0
  61. package/dist/chunk-INT7QLEU.js +114 -0
  62. package/dist/chunk-J7UYNJCR.js +9 -0
  63. package/dist/chunk-JEL35P7S.js +53 -0
  64. package/dist/chunk-JGJ4INEN.js +32 -0
  65. package/dist/chunk-JS5RTH4I.js +84 -0
  66. package/dist/chunk-JWRZDYB5.js +59 -0
  67. package/dist/chunk-KMXRRSKT.js +660 -0
  68. package/dist/chunk-LBXO4VPG.js +73 -0
  69. package/dist/chunk-LLBPVZXM.js +67 -0
  70. package/dist/chunk-LLT5FQBE.js +57 -0
  71. package/dist/chunk-LMT3PPXJ.js +17 -0
  72. package/dist/chunk-LMUBBIE2.js +83 -0
  73. package/dist/chunk-LTZH5E3G.js +479 -0
  74. package/dist/chunk-LW4TG7EL.js +39 -0
  75. package/dist/chunk-MPSQXSC6.js +346 -0
  76. package/dist/chunk-MVFH26QT.js +97 -0
  77. package/dist/chunk-NLEXKE7U.js +67 -0
  78. package/dist/chunk-NQPURJT5.js +44 -0
  79. package/dist/chunk-NRBQK6UX.js +105 -0
  80. package/dist/chunk-OEH47H6A.js +48 -0
  81. package/dist/chunk-OG7QR2DP.js +75 -0
  82. package/dist/chunk-OPYFEHKG.js +52 -0
  83. package/dist/chunk-P4N7DBD5.js +83 -0
  84. package/dist/chunk-PAX3QXX2.js +140 -0
  85. package/dist/chunk-PKODFR5F.js +102 -0
  86. package/dist/chunk-PMJG2CXF.js +122 -0
  87. package/dist/chunk-Q5H3L6Y4.js +23 -0
  88. package/dist/chunk-QEF7EK3T.js +28 -0
  89. package/dist/chunk-QEW4J3IZ.js +74 -0
  90. package/dist/chunk-QPL7E2HW.js +464 -0
  91. package/dist/chunk-R2GPCZUX.js +22 -0
  92. package/dist/chunk-R5MT42JS.js +284 -0
  93. package/dist/chunk-RMATE45Z.js +197 -0
  94. package/dist/chunk-RPQOBHVU.js +87 -0
  95. package/dist/chunk-S3PIAMXV.js +230 -0
  96. package/dist/chunk-T3LKX23M.js +168 -0
  97. package/dist/chunk-T6GOWHK6.js +30 -0
  98. package/dist/chunk-TIA4SPU2.js +10 -0
  99. package/dist/chunk-TNCZ6444.js +57 -0
  100. package/dist/chunk-TVL5RTE6.js +269 -0
  101. package/dist/chunk-TXQ7L33K.js +45 -0
  102. package/dist/chunk-UPQTAHUK.js +189 -0
  103. package/dist/chunk-V4NPDK6X.js +14 -0
  104. package/dist/chunk-VJFEN6DJ.js +38 -0
  105. package/dist/chunk-VMHUEOT5.js +643 -0
  106. package/dist/chunk-VRPMYPZU.js +4985 -0
  107. package/dist/chunk-WIW772I3.js +25 -0
  108. package/dist/chunk-XELAZAIM.js +136 -0
  109. package/dist/chunk-XNML2KIC.js +23 -0
  110. package/dist/chunk-XP2U3LO3.js +30 -0
  111. package/dist/chunk-YGOWIJPE.js +51 -0
  112. package/dist/chunk-YIXDHQYE.js +11 -0
  113. package/dist/chunk-YSAWTGNA.js +117 -0
  114. package/dist/claude-U2JC2DNQ.js +77 -0
  115. package/dist/cli-MI4ZCAZ3.js +41 -0
  116. package/dist/cli-ZN7ZVDEZ.js +46 -0
  117. package/dist/cli.js +144 -16197
  118. package/dist/completion-ILSRB3LW.js +142 -0
  119. package/dist/config-DnpLL2kT.d.ts +46 -0
  120. package/dist/{service-qpCsOXkQ.d.ts → core-C1LPjxK6.d.ts} +2 -6
  121. package/dist/diagnostics-XKXVVQWH.js +93 -0
  122. package/dist/doctor-O2E63YGO.js +538 -0
  123. package/dist/entry-X6CSYQRQ.js +305 -0
  124. package/dist/exec-mcp-2PMWBPD7.js +365 -0
  125. package/dist/harness-L2KSI2ZB.js +177 -0
  126. package/dist/harness-egress-bridge.js +4 -4
  127. package/dist/harness-launch-gate.js +47 -940
  128. package/dist/harness-pane-runner.js +13 -80
  129. package/dist/harness-worker.js +21 -2703
  130. package/dist/hook-body.js +5222 -0
  131. package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
  132. package/dist/hook.js +26 -0
  133. package/dist/hooks-BHTA44X7.js +21 -0
  134. package/dist/host-UIZAXXQH.js +22 -0
  135. package/dist/host-UWK754BW.js +210 -0
  136. package/dist/host-run-BI2OTZDZ.js +307 -0
  137. package/dist/http.d.ts +5 -42
  138. package/dist/http.js +21 -2234
  139. package/dist/import-mcp-GPKJI7DI.js +400 -0
  140. package/dist/index.d.ts +146 -168
  141. package/dist/index.js +133 -4948
  142. package/dist/init-3C2Y7BNJ.js +14 -0
  143. package/dist/install-GG7HHZK2.js +796 -0
  144. package/dist/invoke-44CJRVMK.js +23 -0
  145. package/dist/list-MCP2FXUF.js +68 -0
  146. package/dist/list-WL6L4J5H.js +65 -0
  147. package/dist/load-BEUBABtB.d.ts +21 -0
  148. package/dist/logout-F5EJ5MOU.js +44 -0
  149. package/dist/logs-TBUA4UWU.js +107 -0
  150. package/dist/mailbox/index.d.ts +10 -5
  151. package/dist/mailbox/index.js +53 -1572
  152. package/dist/mailbox-BMTZOSZ7.js +285 -0
  153. package/dist/mailbox-GDJ7BWQN.js +189 -0
  154. package/dist/mainline-KAD2ERLP.js +639 -0
  155. package/dist/marketplace-G4VQET5W.js +191 -0
  156. package/dist/mcp-235QZN2A.js +15 -0
  157. package/dist/mcp-FJ2UQ4RH.js +193 -0
  158. package/dist/models-ISU4DCMA.js +32 -0
  159. package/dist/opencode-CN7JLQYO.js +60 -0
  160. package/dist/pause-7LILUVGL.js +18 -0
  161. package/dist/preview-DT7DWG5F.js +91 -0
  162. package/dist/project/hook-adapter.d.ts +5 -2
  163. package/dist/project/hook-adapter.js +41 -27
  164. package/dist/project-5YV5CUEG.js +70 -0
  165. package/dist/pty-XTJ4MIWK.js +94 -0
  166. package/dist/recovery-U6QB3PMT.js +100 -0
  167. package/dist/reindex-Y27QJFDB.js +22 -0
  168. package/dist/resume-26VFAAMH.js +18 -0
  169. package/dist/run-3AXTZSR7.js +126 -0
  170. package/dist/run-3SOVRQIA.js +19 -0
  171. package/dist/serve-DQMKTFIV.js +104 -0
  172. package/dist/session-XM2CR425.js +159 -0
  173. package/dist/setup-DTKZLZUT.js +18 -0
  174. package/dist/start-login-YTZV6KMF.js +416 -0
  175. package/dist/status-A2OUTNGK.js +9 -0
  176. package/dist/status-H2VAHIDV.js +10 -0
  177. package/dist/status-MROQ7WR7.js +43 -0
  178. package/dist/status-RO55QPKV.js +55 -0
  179. package/dist/status-UME2L33L.js +286 -0
  180. package/dist/stdio.d.ts +3 -13
  181. package/dist/stdio.js +16 -3186
  182. package/dist/sweep-35LGQTTO.js +18 -0
  183. package/dist/test-AGZOJLRZ.js +561 -0
  184. package/dist/tools-gpHNq9Dh.d.ts +328 -0
  185. package/dist/tui-G5LLWCSV.js +153 -0
  186. package/dist/unbroadcast-5QNGAJR2.js +18 -0
  187. package/dist/validate-IU52H2IC.js +46 -0
  188. package/dist/worker-QZ5T6LJD.js +80 -0
  189. package/dist/worktree-create-PZSRB7PH.js +89 -0
  190. package/dist/worktree-list-JYB6VXLW.js +51 -0
  191. package/dist/worktree-sync-UF5CXPWV.js +30 -0
  192. package/docs/authoring.md +82 -0
  193. package/docs/browser-and-desktop.md +46 -0
  194. package/docs/commands.md +325 -0
  195. package/docs/compare.md +35 -0
  196. package/docs/compatibility.md +55 -0
  197. package/docs/embeddings.md +1 -1
  198. package/docs/getting-started.md +105 -0
  199. package/docs/git-workflow.md +60 -0
  200. package/docs/glossary.md +31 -0
  201. package/docs/hooks/capabilities/antigravity.json +199 -0
  202. package/docs/hooks/capabilities/claude.json +179 -0
  203. package/docs/hooks/capabilities/codex.json +179 -0
  204. package/docs/hooks/capabilities/gemini.json +196 -0
  205. package/docs/hooks/capabilities/grok.json +192 -0
  206. package/docs/hooks/capabilities/opencode.json +184 -0
  207. package/docs/hooks.md +264 -0
  208. package/docs/install.md +72 -0
  209. package/docs/library-skills.md +132 -0
  210. package/docs/mailbox.md +16 -5
  211. package/docs/project-configuration.md +540 -58
  212. package/docs/sessions.md +64 -0
  213. package/docs/skills.md +4 -45
  214. package/docs/terminal-harness.md +92 -44
  215. package/docs/terminal-workspace.md +81 -169
  216. package/gemini-extension.json +2 -2
  217. package/mcp.json +1 -1
  218. package/package.json +16 -2
  219. package/plugin.json +2 -2
  220. package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
  221. package/plugins/pmcp/.mcp.json +1 -1
  222. package/plugins/pmcp/gemini-extension.json +2 -2
  223. package/plugins/pmcp/mcp.json +1 -1
  224. package/plugins/pmcp/mod/commands.ts +72 -0
  225. package/plugins/pmcp/mod/contract.d.ts +39 -0
  226. package/plugins/pmcp/mod/draw.tsx +216 -0
  227. package/plugins/pmcp/mod/guard.ts +42 -0
  228. package/plugins/pmcp/mod/hooks.json +4 -0
  229. package/plugins/pmcp/mod/host.ts +46 -0
  230. package/plugins/pmcp/mod/model.ts +144 -0
  231. package/plugins/pmcp/mod/reader/index.ts +18 -0
  232. package/plugins/pmcp/mod/reader/read.ts +76 -0
  233. package/plugins/pmcp/mod/reader/settings.ts +54 -0
  234. package/plugins/pmcp/mod/reader/types.ts +38 -0
  235. package/plugins/pmcp/mod/register.tsx +73 -0
  236. package/plugins/pmcp/mod/sessions/format.ts +91 -0
  237. package/plugins/pmcp/mod/sessions/types.ts +162 -0
  238. package/plugins/pmcp/mod/snapshot.ts +75 -0
  239. package/plugins/pmcp/mod/spinner.tsx +30 -0
  240. package/plugins/pmcp/mod/state.ts +28 -0
  241. package/plugins/pmcp/plugin.json +2 -2
  242. package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
  243. package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
  244. package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
  245. package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -15
  246. package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
  247. package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
  248. package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +153 -0
  249. package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +96 -0
  250. package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +89 -0
  251. package/schema/catalog-v1.json +187 -0
  252. package/schema/library.json +196 -0
  253. package/schema/marketplace-manifest.json +144 -0
  254. package/schema/plugin-manifest.json +59 -0
  255. package/schema/skill-frontmatter.json +170 -0
  256. package/schema/skill-metadata-core.json +131 -0
  257. package/skills/agent-assets-migrate/SKILL.md +96 -0
  258. package/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
  259. package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
  260. package/skills/package-skill-catalog/SKILL.md +51 -15
  261. package/skills/pmcp-browser/SKILL.md +27 -0
  262. package/skills/pmcp-desktop/SKILL.md +25 -0
  263. package/skills/pmcp-project-init/SKILL.md +153 -0
  264. package/skills/pmcp-sessions-and-git/SKILL.md +96 -0
  265. package/skills/skill-package-scaffold/SKILL.md +89 -0
  266. package/dist/config-BkSpjUG6.d.ts +0 -50
  267. package/dist/embed-DRROSD3F.d.ts +0 -53
  268. package/dist/hook-spec-CSJJySsH.d.ts +0 -11
  269. package/dist/server-VWSY3Shw.d.ts +0 -543
  270. package/dist/tui-worker.js +0 -6549
  271. package/docs/manual-library-skills.md +0 -74
  272. /package/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
@@ -1,7 +1,11 @@
1
- # Project configuration
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
@@ -16,8 +20,80 @@ marketplaces = ["vendor/marketplace"]
16
20
 
17
21
  Paths resolve against the file's directory. Keys are `roots`, `scopes`,
18
22
  `workspaces`, `packages` and `marketplaces`, each a list mirroring the flag of
19
- the same meaning; an unknown key is an error. A flag replaces the file's list
23
+ the same meaning, and `builtin` (boolean, default on) for the bundled free
24
+ marketplace; an unknown key is an error. A flag replaces the file's list
20
25
  of its kind. `--config <file>` names another file and `--no-config` ignores it.
26
+ The nearest `pmcp.toml` is found by walking up from the working directory,
27
+ stopping at the directory that holds `.git`.
28
+
29
+ `[catalog.validation]` makes `pmcp validate` stricter than the Agent Skills
30
+ specification. Without it, only the specification is checked.
31
+
32
+ ```toml
33
+ [catalog.validation]
34
+ profile = "catalog-v1" # or "library"
35
+ deny_list = "private-terms.txt"
36
+ ```
37
+
38
+ | Key | Type | Default | Meaning |
39
+ | ----------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
+ | `profile` | string | none | `catalog-v1`: the marketplace catalog rules (metadata, tier, trigger wording, ASCII in the open tier, locales); the marketplace's tier applies, else the skill's own `metadata.tier`, else `open`. `library`: the manual library skill metadata schema. |
41
+ | `deny_list` | path | none | A file of terms, one per line (`#` starts a comment), that no file of a skill may contain, compared without case. Relative to `pmcp.toml`. A finding names the list line, never the term. A missing file is an error. |
42
+
43
+ Both apply to named skill directories and, with no directory named, to every
44
+ skill the catalog reaches.
45
+
46
+ ## Table index
47
+
48
+ Every table pmcp reads, and where it is described. An unknown key inside one
49
+ of these tables is an error unless noted; an unknown top-level table is
50
+ ignored.
51
+
52
+ | Table | Section |
53
+ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
54
+ | `[catalog]`, `[catalog.validation]` | [Project config](#project-config) |
55
+ | `[embedding]`, `[embedding.encoder]` | [Embedding models](embeddings.md) |
56
+ | `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
57
+ | `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
58
+ | `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
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) |
61
+ | `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]` | [Sessions](#sessions) |
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) |
63
+ | `[logging]`, `[logging.components]` | [Logging](#logging) |
64
+ | `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
65
+ | `[ui.claude]` | [Claude session panes](#claude-session-panes) |
66
+ | `[tui]`, `[mailbox]` | [Terminal workspace](terminal-workspace.md) |
67
+ | `[host]`, `[[host.sessions]]`, `[[host.answers]]`, `[host.browser]`, `[host.desktop]`, `[[host.desktop.launch]]` | [Sessions pmcp-pty hosts](#sessions-pmcp-pty-hosts) |
68
+
69
+ ## Marketplaces
70
+
71
+ `[marketplaces.<name>]` declares a plugin marketplace once for catalog search
72
+ and for each agent tool:
73
+
74
+ ```toml
75
+ [marketplaces.team]
76
+ source = { path = "packages/marketplace" } # or { github = "owner/repo", ref = "main" } or { builtin = true }
77
+ catalog = true # searchable, like [catalog] marketplaces
78
+ [marketplaces.team.plugins]
79
+ review = { targets = ["claude", "codex"] }
80
+ ```
81
+
82
+ `pmcp project` writes `extraKnownMarketplaces` and `enabledPlugins` in
83
+ `.claude/settings.json`, and `[marketplaces.<name>]` and
84
+ `[plugins."<plugin>@<name>"]` in the pmcp block of `.codex/config.toml`. Local
85
+ sources are written as absolute paths. Codex reads the project file only in a
86
+ trusted project and installs plugins into user state, so `pmcp doctor` prints
87
+ `codex plugin add <plugin>@<name>` for each declared plugin Codex has not
88
+ installed and reports enabled plugins the file does not declare.
89
+ `[catalog] marketplaces` remains an alias.
90
+
91
+ A marketplace name and each plugin name match `^[a-z0-9][a-z0-9-]*$`. `source`
92
+ is required and holds exactly one of `path` (resolved against the toml
93
+ directory), `github` (`owner/repo`, with an optional `ref`) or `builtin = true`.
94
+ `catalog = true` needs a path or builtin source. Each plugin's `targets` is
95
+ required and lists `claude` and/or `codex`. Without the table no marketplace is
96
+ declared.
21
97
 
22
98
  ## Native files for each agent tool
23
99
 
@@ -34,10 +110,10 @@ described in [OpenCode project support](#opencode-project-support).
34
110
  tools = ["claude", "codex", "gemini", "grok", "antigravity"]
35
111
 
36
112
  [skills.deploy]
37
- invocation = "user" # the person starts it; the model is not offered it
113
+ invocation = "user" # the person starts it; the model is not offered it
38
114
 
39
115
  [agents.reviewer.claude]
40
- tools = "Read, Grep" # fields one tool reads stay out of agent.md
116
+ tools = "Read, Grep" # fields one tool reads stay out of agent.md
41
117
 
42
118
  [rules]
43
119
  root = "AGENTS.md"
@@ -55,6 +131,13 @@ pmcp project remove <name>
55
131
  pmcp doctor # ask each installed tool what it loads
56
132
  ```
57
133
 
134
+ | Table | Keys |
135
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
136
+ | `[targets]` | `tools`: list of `claude`, `codex`, `gemini`, `grok`, `antigravity`, `opencode`. Missing means nothing is projected. |
137
+ | `[skills.<name>]` | `invocation`: `"any"` (default) or `"user"`. |
138
+ | `[agents.<name>.<tool>]` | Any keys, merged over the agent's frontmatter; Claude keeps `name`, `description`, `tools`, `model`, `effort`, Gemini keeps `name`, `description`. |
139
+ | `[rules.packages]` | `file` (required): the file name each package keeps its rules in; every tracked `<package>/<file>` is linked as `.claude/rules/<dir>/<name>.md`. `dir` (default `"pkg"`, not `"pmcp"`). `strip` (default `[]`): leading path segments dropped when deriving `<name>`. Written only for Claude. |
140
+
58
141
  Rules go to `.claude/rules/<dir>/`, never the top level, because Grok Build
59
142
  loads top-level `.claude/rules/*.md` in every session regardless of `paths:`.
60
143
  A server that names `${PROJECT_ROOT}` is launched through `sh`, which finds
@@ -64,14 +147,130 @@ overwritten. `doctor` calls no model: it reads `claude mcp list`,
64
147
  `codex mcp list`, `gemini skills list`, `gemini mcp list` and
65
148
  `grok inspect --json`, and skips a tool that is not installed.
66
149
 
67
- ## Unified project MCP configuration
150
+ ## Sessions pmcp-pty hosts
68
151
 
69
- Antigravity receives a native project plugin at .agents/plugins/pmcp-mcp with
70
- plugin.json and mcp_config.json. Projection removes only lock-owned entries
71
- from the earlier .agents/mcp_config.json artifact and backs up both layouts.
72
- Antigravity's global mcp list does not enumerate project plugin servers;
73
- validate the generated plugin with agy plugin validate.
74
- Its HTTP entries use serverUrl, accepted by the installed plugin validator.
152
+ `[host]` names the sessions pmcp-pty runs for this project and the few dialog
153
+ answers you allow it to give. `pmcp project` writes them to
154
+ `.agents/pmcp-pty/host.json` (the sessions) and `.agents/pmcp-pty/policy.json`
155
+ (answers, `mcp_write`, roots), pinned in `pmcp.lock` like every output, and
156
+ `pmcp doctor` reports whether they match. pmcp.toml is writable by agents, so
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.
161
+
162
+ ```toml
163
+ [host]
164
+ roots = ["."] # every session cwd must be under one of these
165
+ mcp_write = false # pty_turn and pty_lease over pmcp harness mcp
166
+
167
+ [[host.sessions]]
168
+ name = "lead" # lowercase, digits and -; unique
169
+ runtime = "claude" # claude, codex, gemini, agy, grok or opencode
170
+ cwd = "." # inside the project
171
+ argv = ["claude"] # default: the runtime's name
172
+ labels = { task = "review" }
173
+ restart = "on-exit" # or "no" (default); max_restarts defaults to 3
174
+
175
+ [[host.answers]]
176
+ runtime = "gemini"
177
+ dialog = "tool-approval" # the dialog name pmcp-pty's profile reports
178
+ options = ["Allow once"] # option keys or labels
179
+
180
+ [host.browser]
181
+ allow_private = ["localhost:5173"] # host:port or host:*; pmcp-browser is public-only without it
182
+
183
+ [[host.desktop.launch]]
184
+ name = "terminal" # what pmcp-desktop's launch tool takes
185
+ argv = ["xterm"] # never a browser
186
+ ```
187
+
188
+ Login and authentication (`auth-*`), folder and workspace trust and hook
189
+ review dialogs are never answered: a `[[host.answers]]` entry naming one is a
190
+ configuration error, and pmcp-pty refuses them whatever a policy says. Paths
191
+ stay project-relative, so the projected files hold no host path.
192
+ `[host.browser]` and `[[host.desktop.launch]]` widen
193
+ [pmcp-browser and pmcp-desktop](browser-and-desktop.md) and act only
194
+ from the approved copy too; a launch entry that starts a browser is an error.
195
+
196
+ ### Approving the host policy
197
+
198
+ Run `pmcp harness host approve` in your own terminal after `pmcp project`. It
199
+ prints the sessions, the answer rules, `mcp_write` and one sha256 over both
200
+ projected files, and approves only when you type the first 8 hex digits of
201
+ that hash. The approved copy goes to
202
+ `$XDG_STATE_HOME/pmcp/host-approvals/<project id>/` (directory 0700, files
203
+ 0600; the `[sessions] state_dir` override does not apply), and
204
+ `pmcp-pty daemon --host <that directory>` loads only that copy, after checking
205
+ it still matches its own approval. A later projection that differs is
206
+ reported by `pmcp doctor` and `pmcp harness host status`, and the approved
207
+ copy stays in force until you approve again.
208
+
209
+ `approve` refuses without an interactive terminal, when `PMCP_PTY_*` or a
210
+ coding agent's session variables are set, and when an ancestor process is a
211
+ coding agent or pmcp-pty. With `[host]` declared, the `shell.host_approval`
212
+ guard (deny by default; set `[hooks.guards.shell] host_approval` to change it)
213
+ blocks agents' commands that run `host approve` or touch the approvals
214
+ directory, and their edits there.
215
+
216
+ These checks run as your own user, like the agents themselves. They stop an
217
+ accident and an agent that was told to approve; they are not a security
218
+ boundary, since any process running as you can write the approvals directory
219
+ directly. A real boundary needs the approvals stored under a different user or
220
+ owned by root.
221
+
222
+ ## Browser and desktop for agents
223
+
224
+ pmcp-browser and pmcp-desktop, and how to declare them: [Browser and desktop](browser-and-desktop.md).
225
+
226
+ ## Claude permission rules
227
+
228
+ `[permissions.claude]` declares Claude Code permission rules. `pmcp project`
229
+ adds them to `permissions.allow`, `permissions.ask` and `permissions.deny` in
230
+ `.claude/settings.json` when `claude` is in `[targets] tools`:
231
+
232
+ ```toml
233
+ [permissions.claude]
234
+ ask = ["Read(.env)", "Read(**/*.bak.*)", "Bash(git push:*)", "Bash(git stash:*)"]
235
+ deny = ["WebFetch(domain:internal.example)"]
236
+ ```
237
+
238
+ | Table | Keys |
239
+ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
240
+ | `[permissions.claude]` | `allow`, `ask`, `deny`: lists of native Claude rules, kept verbatim. Repeats within a list are dropped; one rule in two lists is an error. No other key. |
241
+
242
+ Each rule is a Claude permission expression: a tool name (`Bash`, `Read`,
243
+ `Edit`, `Write`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Agent`, `Task`,
244
+ `Skill` and the other built-in tools), optionally followed by a specifier in
245
+ parentheses, or an MCP name such as `mcp__docs` or `mcp__docs__search`.
246
+ `WebFetch` takes `domain:<host>`; a `Bash` prefix `:*` must end the specifier.
247
+ pmcp checks only this structure. It never expands globs or rewrites paths, so
248
+ `Read(.env)` stays `Read(.env)`.
249
+
250
+ pmcp owns only the entries it inserted, and records them in `pmcp.lock`. A rule
251
+ that was already in the list is borrowed: it satisfies the declaration but
252
+ stays unmanaged and survives when the declaration goes. Entries pmcp did not
253
+ write are never removed or reordered, and `defaultMode` and every other
254
+ setting are left alone. A missing table declares nothing; an empty list, a
255
+ removed list or a removed table removes the entries pmcp owns in that list.
256
+
257
+ `pmcp project --check` reports `drift` for a declared rule that is missing and
258
+ for an owned rule that is no longer declared. It reports `conflict` when an
259
+ owned entry was edited or removed by hand, or when the list is not a list of
260
+ strings; `pmcp project` then refuses to write until the native file is
261
+ reviewed. `pmcp doctor` shows how many entries each list owns and borrows, or
262
+ `none declared`.
263
+
264
+ A declared rule that also sits unmanaged in another list, for example a hand
265
+ written `deny` for a rule declared in `ask`, is an `overlap`. Claude's own
266
+ precedence decides it, so `--check` and `doctor` show it as a warning and
267
+ nothing is removed or refused. `pmcp project` also refuses to write when
268
+ `.claude/settings.json` changed while it was planning; run it again.
269
+
270
+ Codex is never written: its native command rules are a separate feature, and
271
+ the hook guards stay its enforcement.
272
+
273
+ ## Unified project MCP configuration
75
274
 
76
275
  Declare each MCP server once in pmcp.toml. The projector writes the native
77
276
  project files for all selected runtimes. A server can narrow its targets:
@@ -101,7 +300,8 @@ timeout = 120000
101
300
  url means Streamable HTTP; Gemini receives httpUrl. Legacy SSE is not imported
102
301
  as HTTP. headers contains literal nonsecret headers, header_env maps header
103
302
  names to environment variable names, and bearer_token_env_var references a
104
- token without writing its value. Each runtime retains its own OAuth session.
303
+ token without writing its value. With auth = "native" (the default), each runtime
304
+ retains its own OAuth session.
105
305
  Antigravity HTTP header projection is not qualified and is rejected; explicitly
106
306
  limit those servers to supported targets. tools maps to Gemini includeTools and
107
307
  Codex enabled_tools; it is not a cross-runtime security boundary. Native timeout
@@ -149,6 +349,15 @@ Configuration references: [Codex](https://developers.openai.com/codex/config-ref
149
349
  [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/),
150
350
  and [Grok Build](https://docs.x.ai/build/features/mcp-servers).
151
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
+
152
361
  ## OpenCode project support
153
362
 
154
363
  Add opencode to targets.tools to project MCP entries into the project-root
@@ -166,9 +375,8 @@ OpenCode; explicitly limit those servers to other targets when needed.
166
375
  OpenCode discovers .agents/skills directly, so PMCP creates no skill copies or
167
376
  links. For invocation=user, projection sets permission.skill.<name> to deny:
168
377
  the model's skill list omits that name, while the native /<name> command still
169
- loads its original SKILL.md and accepts user arguments. This was qualified with
170
- OpenCode 1.18.33 using isolated native CLI calls and local scripted responses,
171
- 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
172
380
  arbitrary file access. Native global skill discovery remains a user preference.
173
381
 
174
382
  pmcp doctor checks opencode debug skill and opencode mcp list without calling
@@ -181,62 +389,336 @@ See the [OpenCode MCP configuration](https://opencode.ai/docs/mcp-servers/),
181
389
  [Agent Skills](https://opencode.ai/docs/skills/) and
182
390
  [configuration precedence](https://opencode.ai/docs/config/).
183
391
 
184
- ## Operator shell guards
392
+ ## Shared remote MCP authentication
185
393
 
186
- Declare a project-owned guard explicitly to project it into Codex, Gemini or
187
- Antigravity's native hooks. Without a declaration, pmcp generates no hooks.
394
+ Use `auth = "pmcp"` to let Claude, Codex, Gemini, Antigravity, Grok and
395
+ OpenCode share one remote MCP login (only the Claude and Codex entries have run
396
+ live):
188
397
 
189
398
  ```toml
190
- [[hooks.shell]]
191
- name = "shell-command-policy"
192
- command = ["node", ".agents/guards/shell-command-policy.mjs"]
193
- targets = ["codex", "gemini", "antigravity"]
194
- timeout_ms = 15000
399
+ [mcp.remote]
400
+ url = "https://example.com/mcp"
401
+ auth = "pmcp"
402
+ targets = ["claude", "codex"]
195
403
  ```
196
404
 
197
- The guard script must exist under .agents/guards/ and cannot resolve outside
198
- that directory. It receives one JSON object on stdin containing runtime,
199
- event=before_shell, command and cwd. It returns a JSON object with
200
- decision=allow or decision=deny and an optional reason. Malformed responses,
201
- nonzero exits and timeouts deny the shell call. The guard receives PATH and
202
- LANG rather than the native CLI's credential environment. Non-shell tools are
203
- outside this contract.
405
+ Run `pmcp project`, then `pmcp mcp login remote`. The projected stdio entries
406
+ run `pmcp project exec-mcp remote`; the proxy connects to the declared Streamable
407
+ HTTP endpoint. The login command prints an authorization URL without opening
408
+ a browser. Complete the loopback callback or paste the callback URL or code.
409
+ For a later completion, use `pmcp mcp login remote --no-wait`, then
410
+ `pmcp mcp login remote --code <callback-url-or-code>`. Issuers must support
411
+ PKCE S256 and dynamic client registration, or supply `--client-id` for a
412
+ pre-registered public client. Discovery follows the resource's OAuth metadata.
413
+
414
+ For bearer authentication, declare `bearer_token_env_var` and run login with
415
+ that variable set, or pass `--bearer-env <variable-name>`. The value is stored
416
+ privately and is never projected into runtime configuration or printed.
417
+ `pmcp mcp status remote` reports only credential presence, UTC expiry and scopes.
418
+ `pmcp mcp logout remote` clears the local credentials and requests remote
419
+ revocation when the issuer advertises it.
420
+
421
+ Credentials live in `$XDG_STATE_HOME/pmcp/credentials/<name>.json`, defaulting to
422
+ `~/.local/state/pmcp/credentials/`. Files use mode 0600 and the credential
423
+ directory uses mode 0700. Credentials are bound to the declared server URL.
424
+ Processes reread credentials under an OS lock before refreshing; refresh-token
425
+ rotation is stored atomically. This implementation requires the `flock` command.
426
+ An expired or revoked session reports an authentication error rather than
427
+ starting interactive login inside the MCP connection.
428
+
429
+ The CLI must be installed in the project or available as `pmcp` on PATH.
430
+ Codex receives environment-name references for `XDG_STATE_HOME` and any declared
431
+ header environment variables. `auth = "native"` preserves existing entries,
432
+ OAuth ownership and env_from behavior. Provider authentication remains native.
433
+
434
+ ## Hooks
435
+
436
+ Guards, checks and session bookkeeping for every targeted runtime, and which runtime supports
437
+ what: [Hooks](hooks.md).
438
+
439
+ ## Sessions
440
+
441
+ Sessions coordinate agents working in one repository and its worktrees. State
442
+ lives in one directory shared by every checkout of the repository.
443
+
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`. |
448
+
449
+ `store` and `state_dir` alone enable nothing; each feature has its own table:
450
+
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. |
458
+
459
+ These tables have no `mode`, except pause. Without `[sessions.registry]` no
460
+ session is recorded, and `[ui.claude]` refuses to project.
461
+
462
+ ### `[sessions.mailbox]`
463
+
464
+ Addressed messages between sessions, and between you and them. A missing table leaves
465
+ the mailbox off; a declared one, even empty, turns it on.
466
+
467
+ | Key | Type | Default | Meaning |
468
+ | --------------- | ------ | ------- | --------------------------------------------------------------------------- |
469
+ | `enabled` | bool | `true` | `false` keeps the table but turns the mailbox off. |
470
+ | `ttl_minutes` | number | `1440` | Default lifetime of a message; `--ttl` overrides it per message. |
471
+ | `max_delivered` | number | `5` | At most this many new messages are shown at once, plus a count of the rest. |
472
+ | `audit` | bool | `true` | Append a line per sent, delivered, acked and expired event. |
473
+ | `wake` | bool | `false` | Wake idle recipients on every send, as `--wake` does for one message. |
474
+
475
+ Each message is one file, `<state>/messages/<id>.json`, created atomically and
476
+ never rewritten: `id`, `from` (session and alias), `to`, `subject`, `body`,
477
+ `createdAt`, `expiresAt`, `replyTo`, `once`. `to` lists selectors: `all`,
478
+ `session:<id>` (a prefix of at least eight characters works), `alias:<name>`,
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
482
+ sessions that were running when it was sent; a session the registry records
483
+ later does not get earlier broadcasts. Delivery and acknowledgement are
484
+ empty markers under `<state>/inbox/<session>/`, so a message is never edited
485
+ for them. `<state>/messages.jsonl` is the append-only audit.
486
+
487
+ The hooks deliver each unacknowledged message addressed to a session once,
488
+ through that runtime's context channel; on a runtime that does not show
489
+ context at an event, the notice is held for the next one that does. Later
490
+ events notice only messages that arrived since, with a count of earlier
491
+ unacknowledged ones. Delivery is recorded and never counts as an
492
+ acknowledgement. A message sent with `--once` says it is a one-time request,
493
+ so the recipient does not keep its instructions as standing rules.
204
494
 
205
- Run pmcp project to write lock-owned adapter and policy artifacts under
206
- .agents/pmcp-hooks/, plus the native entries in .codex/hooks.json,
207
- .gemini/settings.json and .agents/hooks.json. Peer entries are retained.
208
- Edited owned hook entries refuse projection for review. Removing a declaration
209
- removes its generated entries and artifacts while preserving peer settings.
210
- Writes retain private backups; pmcp project --check only reports drift.
495
+ ```sh
496
+ pmcp sessions send --to alias:reviewer --to role:delivery --subject deploy --once "Hold the deploy until 14:00"
497
+ echo "longer body" | pmcp sessions send --to all -
498
+ pmcp sessions inbox [--session <id>] [--all] [--json]
499
+ pmcp sessions ack <id>... [--session <id>]
500
+ pmcp sessions reply <id> "Done"
501
+ pmcp sessions send --wake --to alias:reviewer "CI is green again"
502
+ pmcp sessions sweep
503
+ ```
211
504
 
212
- Guard, policy and adapter fingerprints bind the generated command. Changing
213
- guard code requires reprojection and native Codex hook review. Generated files
214
- contain no trust bypass. Grok can load Claude project hooks, so this first scope
215
- does not generate a second Grok guard. Hooks do not force pmcp catalog use,
216
- inject reminders or replace the runtime's execution sandbox.
505
+ A recipient that is idle sees mail only at its next event. With `--wake`, or
506
+ `wake = true` in the table, `send` and `reply` also start a turn in each idle
507
+ recipient whose runtime allows it, and the woken session's hooks then deliver
508
+ the mail as usual; the wake itself carries only a count, the subjects and one
509
+ exact command to run, `pmcp sessions inbox --session <id>`. Each attempt is an
510
+ audit line (`woken`, with the transport and channel), and `pmcp doctor` shows
511
+ each live session's last wake.
512
+
513
+ - Any runtime hosted by pmcp-pty: the session-start hook records the host's
514
+ socket, session and instance from `PMCP_PTY_*` when the host is the
515
+ runtime's parent or grandparent (a runtime started from a hosted session's
516
+ shell inherits the variables but is not recorded). `send --wake` asks the
517
+ host for one short `turn`; the host picks the channel (Claude inbox, OpenCode
518
+ server, Codex queue, Grok leader or a guarded screen write) and its receipt
519
+ is in `send --json`. A refused turn, such as one behind an open dialog,
520
+ leaves the mail for the next event. The same hooks report each turn's start
521
+ and end (with the last assistant message) and permission notices to the
522
+ host, which ends a turn on that before trusting the screen. A hosted
523
+ session gets mail only on the wake turn itself (a prompt starting
524
+ `pmcp mail:`): as context on other prompts the notice took over turns
525
+ pmcp-pty sent. The two items below are for sessions pmcp-pty does not host.
526
+ - Claude Code: through the session's documented
527
+ [cross-session inbox](https://code.claude.com/docs/en/cross-session-messaging),
528
+ found in `~/.claude/sessions/<pid>.json`, which pmcp only reads. The target's
529
+ own inbound controls apply: a session in `bypassPermissions` without
530
+ `crossSessionInbound = "accept"` holds the wake for approval, and a wake can
531
+ approve nothing.
532
+ - OpenCode: `POST /session/<id>/prompt_async` on the server the session runs
533
+ on, which the generated plugin records; HTTP basic auth from
534
+ `OPENCODE_SERVER_PASSWORD` (user `OPENCODE_SERVER_USERNAME`, default
535
+ `opencode`).
536
+ - Codex, Gemini, Antigravity and Grok outside pmcp-pty have no supported way to
537
+ start a turn in a running session; their mail waits for the next event.
538
+ `pmcp sessions status` and `pmcp doctor` show which live sessions can be
539
+ woken.
540
+
541
+ `--session <id>` acts as that session and `--by <name>` as a named sender
542
+ outside one; the notice a session receives spells out its commands with its
543
+ own `--session`. Those commands, and the wake text, say `pmcp` only when the
544
+ `pmcp` on PATH is the CLI that projects this checkout (its own install, else
545
+ the one that last projected it); otherwise they name that CLI as
546
+ `node '<path>/dist/cli.js'`, and `pmcp doctor` warns. Without either, a command run inside a runtime acts as that
547
+ runtime's session: the live session whose runtime process is its nearest
548
+ ancestor, else the id the runtime exposes to tool commands
549
+ (`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `ANTIGRAVITY_CONVERSATION_ID`,
550
+ `GROK_SESSION_ID`; Gemini and OpenCode expose none). When it cannot tell, it
551
+ warns and acts as `operator`. `sweep` also deletes expired messages and their
552
+ markers.
553
+
554
+ `pmcp sessions status` and `pmcp doctor` name live sessions that should be
555
+ restarted to get the current hooks: one started under an older (or untracked)
556
+ `policy.json`, which matters when new hook events were added, and a Codex
557
+ session started before `.codex/hooks.json` last changed, since Codex reads its
558
+ hook file only when a session starts.
559
+
560
+ With the mailbox on, `pmcp sessions broadcast` also sends its text as a
561
+ message to `all`, and the mailbox delivers it instead of
562
+ `[sessions.broadcast]`; `broadcast.json` and each session's `seenBroadcast`
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
565
+ messages too.
566
+
567
+ ## Git workflow
568
+
569
+ Worktrees, delivery to the mainline and main checkout sync: [Git workflow](git-workflow.md).
570
+
571
+ ## Logging
572
+
573
+ | `[logging]` key | Type | Default | Allowed |
574
+ | --------------- | ------ | ------------------------------------------------ | ----------------------------------------- |
575
+ | `level` | string | `"info"` | `error`, `warn`, `info`, `debug`, `trace` |
576
+ | `format` | string | `"jsonl"` | `jsonl` only |
577
+ | `max_file_mb` | number | `20` | greater than 0 |
578
+ | `keep_days` | number | `14` | greater than 0 |
579
+ | `redact` | list | `["secret_values", "prompt_text", "env_values"]` | any subset |
580
+ | `components` | table | `{}` | `<component> = "<level>"` |
581
+
582
+ The `PMCP_LOG` environment variable overrides the level. `[hooks] error_log`
583
+ switches hook logging on or off. Read the logs with `pmcp logs`.
584
+
585
+ ## Claude session panes
586
+
587
+ `[ui.claude]` installs the session panes into Claude Code: `sessions_pane`,
588
+ `status_band`, `commands` and `hold_foreign_edits`, all booleans defaulting to
589
+ `true`. `hold_foreign_edits` asks before editing a file another live session
590
+ edited. It needs `[sessions.registry]`, and is written only when `claude` is
591
+ in `[targets] tools`. Without the table nothing is installed. `pmcp doctor`
592
+ shows the projected switches, or a failure until `pmcp project` writes them; it
593
+ cannot tell whether a running Claude Code loaded the session panes.
594
+
595
+ ## A complete example
596
+
597
+ A project with two runtimes, the full guard set, sessions, the git workflow and
598
+ a team marketplace:
217
599
 
218
- ## Operator edit guards
600
+ ```toml
601
+ [catalog]
602
+ workspaces = [".", "packages/*"]
219
603
 
220
- Codex edit guards run after apply_patch through native PostToolUse hooks:
604
+ [targets]
605
+ tools = ["claude", "codex"]
221
606
 
222
- ```toml
223
- [[hooks.edit]]
224
- name = "edit-policy"
225
- command = ["node", ".agents/guards/edit-policy.mjs"]
607
+ [mcp.skills]
608
+ command = "node"
609
+ args = ["${PROJECT_ROOT}/node_modules/@modootoday/pmcp/dist/cli.js", "serve"]
610
+
611
+ [skills.deploy]
612
+ invocation = "user"
613
+
614
+ [agents.reviewer.claude]
615
+ tools = "Read, Grep, Glob"
616
+ model = "inherit"
617
+ effort = "high"
618
+
619
+ [hooks]
620
+ targets = ["claude", "codex"]
621
+ ask_fallback = "deny"
622
+
623
+ [hooks.guards.shell.in_place_edit]
624
+ mode = "ask"
625
+
626
+ [hooks.guards.shell.heredoc]
627
+
628
+ [hooks.guards.shell.stdin_interpreter]
629
+
630
+ [hooks.guards.shell.compose_teardown]
631
+
632
+ [hooks.guards.shell.host_approval]
633
+
634
+ [hooks.guards.shell.secret_exfiltration]
635
+ mode = "graded"
636
+
637
+ [[hooks.guards.shell.secret_exfiltration.value_commands]]
638
+ binary = "secrets-cli"
639
+ read = ["read", "env get"]
640
+ publish = ["deploy", "secret put", "secret delete"]
641
+
642
+ [hooks.guards.git.push_without_verify]
643
+
644
+ [hooks.guards.git.forced_branch_move]
645
+
646
+ [hooks.guards.git.stage_all]
647
+
648
+ [hooks.guards.git.gate_bypass_env]
649
+ names = ["ALLOW_DIRECT_PUSH", "SKIP_GATE"]
650
+
651
+ [[hooks.guards.custom]]
652
+ name = "source-formatting"
653
+ command = ["node", ".agents/guards/source-formatting.mjs"]
226
654
  targets = ["codex"]
227
- timeout_ms = 15000
228
- ```
655
+ on = "after_edit"
656
+
657
+ [hooks.checks.after_edit]
658
+ validator_glob = ".agents/skills/*/scripts/validate.ts"
659
+ command = ["node", "{validator}"]
660
+
661
+ [hooks.checks.on_stop]
229
662
 
230
- The guard receives runtime=codex, event=after_edit, the patch in command and cwd.
231
- It returns the same allow/deny response as a shell guard. A denial becomes
232
- native blocking feedback with the reason; the completed file edit remains on disk
233
- for correction. Other tools do not invoke this guard. Edit targets currently
234
- support Codex only, and names must be unique across shell and edit declarations.
663
+ [sessions]
664
+ state_dir = ".pmcp-state"
235
665
 
236
- Run pmcp project after declaring or changing the guard, then review and trust
237
- the generated native definition in /hooks. Peer entries and shell guards are
238
- preserved. Fingerprints and failure handling follow the shell-guard contract.
239
- See the [native hooks documentation](https://learn.chatgpt.com/docs/hooks).
666
+ [sessions.registry]
667
+
668
+ [sessions.pause]
669
+
670
+ [sessions.broadcast]
671
+
672
+ [sessions.mailbox]
673
+ ttl_minutes = 1440
674
+ max_delivered = 5
675
+
676
+ [sessions.leases.lockfile]
677
+ path = "package-lock.json"
678
+ blocks = [["npm", "install"], ["npm", "ci"], ["pmcp", "git", "deliver"]]
679
+
680
+ [sessions.roles.delivery]
681
+ allow_commands = [["pmcp", "git", "deliver"], ["git", "log"], ["git", "status"]]
682
+
683
+ [git]
684
+ remote = "origin"
685
+
686
+ [git.mainline]
687
+ branch = "main"
688
+
689
+ [git.mainline.gate]
690
+ command = ["npm", "test"]
691
+
692
+ [git.mainline.deliver]
693
+
694
+ [git.mainline.sync]
695
+ install = ["npm", "ci"]
696
+ install_when_changed = ["package-lock.json"]
697
+
698
+ [git.worktrees]
699
+ bootstrap = ["sh", "scripts/setup-worktree.sh"]
700
+ link_from_main = [".env"]
701
+
702
+ [git.worktrees.sync]
703
+ install_after_move = "background"
704
+ notice_paths = ["AGENTS.md", "pmcp.toml"]
705
+
706
+ [git.submodules]
707
+
708
+ [logging]
709
+ level = "warn"
710
+
711
+ [ui.claude]
712
+
713
+ [permissions.claude]
714
+ ask = ["Read(.env)", "Bash(git push:*)"]
715
+
716
+ [marketplaces.team]
717
+ source = { github = "example/team-marketplace" }
718
+
719
+ [marketplaces.team.plugins]
720
+ review = { targets = ["claude", "codex"] }
721
+ ```
240
722
 
241
723
  ## Native memory metadata
242
724