@modootoday/pmcp 0.17.3 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (246) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +1 -1
  4. package/CHANGELOG.md +60 -0
  5. package/README.md +29 -24
  6. package/dist/apply-4IGTXOCQ.js +242 -0
  7. package/dist/{attachment-tU5FZrgZ.d.ts → attachment-D84OGI6n.d.ts} +1 -1
  8. package/dist/available-DBSIVVJ6.js +73 -0
  9. package/dist/broadcast-3RY3OZGY.js +18 -0
  10. package/dist/chunk-25GHX674.js +1246 -0
  11. package/dist/chunk-2P4Z2NUX.js +28 -0
  12. package/dist/chunk-34DECPVC.js +22 -0
  13. package/dist/chunk-3NYG4SGU.js +45 -0
  14. package/dist/chunk-3PW4FI7U.js +32 -0
  15. package/dist/chunk-3Y3HDMHA.js +108 -0
  16. package/dist/chunk-47O3X4VS.js +113 -0
  17. package/dist/chunk-4NDEP7HU.js +26 -0
  18. package/dist/chunk-4VCC2NXE.js +104 -0
  19. package/dist/chunk-5OMOPUE6.js +39 -0
  20. package/dist/chunk-5QQWS4US.js +53 -0
  21. package/dist/chunk-5ZABTVSW.js +48 -0
  22. package/dist/chunk-65ZHM5RH.js +4985 -0
  23. package/dist/chunk-665TA55Z.js +419 -0
  24. package/dist/chunk-6STKGOCW.js +27 -0
  25. package/dist/chunk-6WXMJOMI.js +9 -0
  26. package/dist/chunk-73AKO4UL.js +24 -0
  27. package/dist/chunk-7BLPN3W6.js +31 -0
  28. package/dist/chunk-7DLZC73N.js +29 -0
  29. package/dist/chunk-7GBYECSK.js +72 -0
  30. package/dist/chunk-7TD53M7L.js +13 -0
  31. package/dist/chunk-A4PKLESO.js +112 -0
  32. package/dist/chunk-ABTJQ4QV.js +74 -0
  33. package/dist/chunk-BBTBJCFA.js +380 -0
  34. package/dist/chunk-BU65MNVU.js +13 -0
  35. package/dist/chunk-BVCTKPT3.js +83 -0
  36. package/dist/chunk-C4NHQGHL.js +142 -0
  37. package/dist/chunk-CJTKR6K6.js +1213 -0
  38. package/dist/chunk-DCU2EXQV.js +78 -0
  39. package/dist/chunk-DZ2MRTYT.js +135 -0
  40. package/dist/chunk-E2YOZ2FF.js +207 -0
  41. package/dist/chunk-E3DQB5LS.js +48 -0
  42. package/dist/chunk-E7OOHLQR.js +7 -0
  43. package/dist/chunk-EATCUWGG.js +66 -0
  44. package/dist/chunk-EIDIVIAD.js +33 -0
  45. package/dist/chunk-EJBZGIDK.js +1934 -0
  46. package/dist/chunk-ELAGZ635.js +252 -0
  47. package/dist/chunk-GZHHEHKY.js +44 -0
  48. package/dist/chunk-HDMBVLCZ.js +53 -0
  49. package/dist/chunk-HQOB7OQS.js +81 -0
  50. package/dist/chunk-IGYRMM62.js +28 -0
  51. package/dist/chunk-IJBSOWHK.js +86 -0
  52. package/dist/chunk-INT7QLEU.js +114 -0
  53. package/dist/chunk-J6QLLQVL.js +1025 -0
  54. package/dist/chunk-J7UYNJCR.js +9 -0
  55. package/dist/chunk-JEL35P7S.js +53 -0
  56. package/dist/chunk-JGJ4INEN.js +32 -0
  57. package/dist/chunk-JS5RTH4I.js +84 -0
  58. package/dist/chunk-JUXNIXN4.js +42 -0
  59. package/dist/chunk-JWRZDYB5.js +59 -0
  60. package/dist/chunk-KMXRRSKT.js +660 -0
  61. package/dist/chunk-LAZQBMAU.js +67 -0
  62. package/dist/chunk-LLBPVZXM.js +67 -0
  63. package/dist/chunk-LLT5FQBE.js +57 -0
  64. package/dist/chunk-LMT3PPXJ.js +17 -0
  65. package/dist/chunk-MM2Y43LC.js +87 -0
  66. package/dist/chunk-MPSQXSC6.js +346 -0
  67. package/dist/chunk-MVFH26QT.js +97 -0
  68. package/dist/chunk-MWFOUBFC.js +39 -0
  69. package/dist/chunk-N5AQ3PP7.js +211 -0
  70. package/dist/chunk-NQPURJT5.js +44 -0
  71. package/dist/chunk-NRBQK6UX.js +105 -0
  72. package/dist/chunk-NZS5CD72.js +333 -0
  73. package/dist/chunk-OEH47H6A.js +48 -0
  74. package/dist/chunk-OG7QR2DP.js +75 -0
  75. package/dist/chunk-OPYFEHKG.js +52 -0
  76. package/dist/chunk-P4N7DBD5.js +83 -0
  77. package/dist/chunk-PAX3QXX2.js +140 -0
  78. package/dist/chunk-PLX3BOOS.js +396 -0
  79. package/dist/chunk-PMJG2CXF.js +122 -0
  80. package/dist/chunk-PWSJJXLQ.js +643 -0
  81. package/dist/chunk-Q5H3L6Y4.js +23 -0
  82. package/dist/chunk-Q65R3XKX.js +155 -0
  83. package/dist/chunk-QEW4J3IZ.js +74 -0
  84. package/dist/chunk-QPL7E2HW.js +464 -0
  85. package/dist/chunk-R2GPCZUX.js +22 -0
  86. package/dist/chunk-R4L6LJJ2.js +778 -0
  87. package/dist/chunk-R5MT42JS.js +284 -0
  88. package/dist/chunk-RK4PYD7L.js +73 -0
  89. package/dist/chunk-RMATE45Z.js +197 -0
  90. package/dist/chunk-S3PIAMXV.js +230 -0
  91. package/dist/chunk-SG5TPMKH.js +93 -0
  92. package/dist/chunk-T3LKX23M.js +168 -0
  93. package/dist/chunk-T6GOWHK6.js +30 -0
  94. package/dist/chunk-TIA4SPU2.js +10 -0
  95. package/dist/chunk-TNCZ6444.js +57 -0
  96. package/dist/chunk-TVL5RTE6.js +269 -0
  97. package/dist/chunk-UOCLRM7P.js +151 -0
  98. package/dist/chunk-UPQTAHUK.js +189 -0
  99. package/dist/chunk-V4NPDK6X.js +14 -0
  100. package/dist/chunk-VJFEN6DJ.js +38 -0
  101. package/dist/chunk-WIW772I3.js +25 -0
  102. package/dist/chunk-XELAZAIM.js +136 -0
  103. package/dist/chunk-XNML2KIC.js +23 -0
  104. package/dist/chunk-XP2U3LO3.js +30 -0
  105. package/dist/chunk-YGOWIJPE.js +51 -0
  106. package/dist/chunk-YIXDHQYE.js +11 -0
  107. package/dist/chunk-YMHUM7AV.js +22 -0
  108. package/dist/chunk-YSAWTGNA.js +117 -0
  109. package/dist/chunk-Z4HRRXRF.js +478 -0
  110. package/dist/chunk-ZH6R642Z.js +102 -0
  111. package/dist/claude-U2JC2DNQ.js +77 -0
  112. package/dist/cli-VYCQJZ5X.js +41 -0
  113. package/dist/cli-ZTCBSDW4.js +46 -0
  114. package/dist/cli.js +144 -16160
  115. package/dist/completion-E7RRG3ZT.js +142 -0
  116. package/dist/config-DnpLL2kT.d.ts +46 -0
  117. package/dist/{service-qpCsOXkQ.d.ts → core-C1LPjxK6.d.ts} +2 -6
  118. package/dist/diagnostics-XXH4FLUG.js +93 -0
  119. package/dist/doctor-ZIOESU3N.js +538 -0
  120. package/dist/entry-ZNFCTDVE.js +305 -0
  121. package/dist/exec-mcp-X6372BLE.js +365 -0
  122. package/dist/harness-F2XFDYXF.js +177 -0
  123. package/dist/harness-egress-bridge.js +4 -4
  124. package/dist/harness-launch-gate.js +47 -940
  125. package/dist/harness-pane-runner.js +13 -80
  126. package/dist/harness-worker.js +21 -2703
  127. package/dist/hook-body.js +5221 -0
  128. package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
  129. package/dist/hook.js +26 -0
  130. package/dist/hooks-FYE2L5RW.js +21 -0
  131. package/dist/host-GRY3VAHH.js +22 -0
  132. package/dist/host-X6BR6X4O.js +200 -0
  133. package/dist/host-run-GCA6H6SR.js +307 -0
  134. package/dist/http.d.ts +5 -42
  135. package/dist/http.js +21 -2234
  136. package/dist/import-mcp-2TTBPVLY.js +400 -0
  137. package/dist/index.d.ts +146 -168
  138. package/dist/index.js +133 -4911
  139. package/dist/init-627KFXTG.js +14 -0
  140. package/dist/install-GG7HHZK2.js +796 -0
  141. package/dist/invoke-LW22Z6ET.js +23 -0
  142. package/dist/list-MCP2FXUF.js +68 -0
  143. package/dist/list-NGMSQ5SH.js +65 -0
  144. package/dist/load-BEUBABtB.d.ts +21 -0
  145. package/dist/logout-6CSHUWWE.js +44 -0
  146. package/dist/logs-SPB6AANY.js +107 -0
  147. package/dist/mailbox/index.d.ts +10 -5
  148. package/dist/mailbox/index.js +53 -1572
  149. package/dist/mailbox-7BV54Q4R.js +285 -0
  150. package/dist/mailbox-GDJ7BWQN.js +189 -0
  151. package/dist/mainline-JQTTYJMI.js +639 -0
  152. package/dist/marketplace-G4VQET5W.js +191 -0
  153. package/dist/mcp-2DKVU3SW.js +15 -0
  154. package/dist/mcp-V23HC3LB.js +193 -0
  155. package/dist/models-ISU4DCMA.js +32 -0
  156. package/dist/opencode-CN7JLQYO.js +60 -0
  157. package/dist/pause-FFAYRBWI.js +18 -0
  158. package/dist/preview-DT7DWG5F.js +91 -0
  159. package/dist/project/hook-adapter.d.ts +6 -3
  160. package/dist/project/hook-adapter.js +66 -35
  161. package/dist/project-FY62G55N.js +70 -0
  162. package/dist/pty-XTJ4MIWK.js +94 -0
  163. package/dist/recovery-U6QB3PMT.js +100 -0
  164. package/dist/reindex-Y27QJFDB.js +22 -0
  165. package/dist/resume-UU4HZIUP.js +18 -0
  166. package/dist/run-HALGEJNJ.js +19 -0
  167. package/dist/run-OGA3P7FC.js +126 -0
  168. package/dist/serve-NBKT5BKY.js +104 -0
  169. package/dist/session-XM2CR425.js +159 -0
  170. package/dist/setup-DTKZLZUT.js +18 -0
  171. package/dist/start-login-UIQYQBMC.js +416 -0
  172. package/dist/status-A2OUTNGK.js +9 -0
  173. package/dist/status-H2VAHIDV.js +10 -0
  174. package/dist/status-NOOHW5WA.js +43 -0
  175. package/dist/status-VHODZPXB.js +55 -0
  176. package/dist/status-XQANBVXW.js +286 -0
  177. package/dist/stdio.d.ts +3 -13
  178. package/dist/stdio.js +16 -3186
  179. package/dist/sweep-64JDCGK6.js +18 -0
  180. package/dist/test-MKAXFJOL.js +561 -0
  181. package/dist/tools-gpHNq9Dh.d.ts +328 -0
  182. package/dist/tui-MWKAXE4K.js +153 -0
  183. package/dist/unbroadcast-KPUEFLZD.js +18 -0
  184. package/dist/validate-5GZ5YWNA.js +46 -0
  185. package/dist/worker-RQ575EJL.js +80 -0
  186. package/dist/worktree-create-PZSRB7PH.js +89 -0
  187. package/dist/worktree-list-JYB6VXLW.js +51 -0
  188. package/dist/worktree-sync-UF5CXPWV.js +30 -0
  189. package/docs/hooks/capabilities/antigravity.json +199 -0
  190. package/docs/hooks/capabilities/claude.json +179 -0
  191. package/docs/hooks/capabilities/codex.json +179 -0
  192. package/docs/hooks/capabilities/gemini.json +196 -0
  193. package/docs/hooks/capabilities/grok.json +192 -0
  194. package/docs/hooks/capabilities/opencode.json +184 -0
  195. package/docs/project-configuration.md +844 -4
  196. package/docs/terminal-harness.md +71 -28
  197. package/docs/terminal-workspace.md +91 -170
  198. package/gemini-extension.json +1 -1
  199. package/package.json +13 -1
  200. package/plugin.json +1 -1
  201. package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
  202. package/plugins/pmcp/gemini-extension.json +1 -1
  203. package/plugins/pmcp/mod/commands.ts +72 -0
  204. package/plugins/pmcp/mod/contract.d.ts +39 -0
  205. package/plugins/pmcp/mod/draw.tsx +216 -0
  206. package/plugins/pmcp/mod/guard.ts +42 -0
  207. package/plugins/pmcp/mod/hooks.json +4 -0
  208. package/plugins/pmcp/mod/host.ts +46 -0
  209. package/plugins/pmcp/mod/model.ts +144 -0
  210. package/plugins/pmcp/mod/reader/index.ts +18 -0
  211. package/plugins/pmcp/mod/reader/read.ts +76 -0
  212. package/plugins/pmcp/mod/reader/settings.ts +54 -0
  213. package/plugins/pmcp/mod/reader/types.ts +38 -0
  214. package/plugins/pmcp/mod/register.tsx +73 -0
  215. package/plugins/pmcp/mod/sessions/format.ts +91 -0
  216. package/plugins/pmcp/mod/sessions/types.ts +162 -0
  217. package/plugins/pmcp/mod/snapshot.ts +75 -0
  218. package/plugins/pmcp/mod/spinner.tsx +30 -0
  219. package/plugins/pmcp/mod/state.ts +28 -0
  220. package/plugins/pmcp/plugin.json +1 -1
  221. package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
  222. package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +100 -0
  223. package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
  224. package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -11
  225. package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +145 -0
  226. package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +104 -0
  227. package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +88 -0
  228. package/schema/catalog-v1.json +158 -0
  229. package/schema/library.json +164 -0
  230. package/schema/marketplace-manifest.json +130 -0
  231. package/schema/plugin-manifest.json +55 -0
  232. package/schema/skill-frontmatter.json +144 -0
  233. package/schema/skill-metadata-core.json +110 -0
  234. package/skills/agent-assets-migrate/SKILL.md +96 -0
  235. package/skills/headless-agents-ci-scaffold/SKILL.md +100 -0
  236. package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
  237. package/skills/package-skill-catalog/SKILL.md +51 -11
  238. package/skills/pmcp-project-init/SKILL.md +145 -0
  239. package/skills/pmcp-sessions-and-git/SKILL.md +104 -0
  240. package/skills/skill-package-scaffold/SKILL.md +88 -0
  241. package/dist/config-BkSpjUG6.d.ts +0 -50
  242. package/dist/embed-DRROSD3F.d.ts +0 -53
  243. package/dist/hook-spec-PRSnYGLV.d.ts +0 -10
  244. package/dist/server-VWSY3Shw.d.ts +0 -543
  245. package/dist/tui-worker.js +0 -6549
  246. /package/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
@@ -16,8 +16,80 @@ marketplaces = ["vendor/marketplace"]
16
16
 
17
17
  Paths resolve against the file's directory. Keys are `roots`, `scopes`,
18
18
  `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
19
+ the same meaning, and `builtin` (boolean, default on) for the bundled free
20
+ marketplace; an unknown key is an error. A flag replaces the file's list
20
21
  of its kind. `--config <file>` names another file and `--no-config` ignores it.
22
+ The nearest `pmcp.toml` is found by walking up from the working directory,
23
+ stopping at the directory that holds `.git`.
24
+
25
+ `[catalog.validation]` makes `pmcp validate` stricter than the Agent Skills
26
+ specification. Without it, only the specification is checked.
27
+
28
+ ```toml
29
+ [catalog.validation]
30
+ profile = "catalog-v1" # or "library"
31
+ deny_list = "private-terms.txt"
32
+ ```
33
+
34
+ | Key | Type | Default | Meaning |
35
+ | ----------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36
+ | `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. |
37
+ | `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. |
38
+
39
+ Both apply to named skill directories and, with no directory named, to every
40
+ skill the catalog reaches.
41
+
42
+ ## Table index
43
+
44
+ Every table pmcp reads, and where it is described. An unknown key inside one
45
+ of these tables is an error unless noted; an unknown top-level table is
46
+ ignored.
47
+
48
+ | Table | Section |
49
+ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
50
+ | `[catalog]`, `[catalog.validation]` | [Project config](#project-config) |
51
+ | `[embedding]`, `[embedding.encoder]` | [Embedding models](embeddings.md) |
52
+ | `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
53
+ | `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
54
+ | `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
55
+ | `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]` | [Hooks](#hooks) |
56
+ | `[[hooks.shell]]`, `[[hooks.edit]]` | [Operator shell guards](#operator-shell-guards) |
57
+ | `[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](#git-workflow) |
59
+ | `[logging]`, `[logging.components]` | [Logging](#logging) |
60
+ | `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
61
+ | `[ui.claude]` | [Claude session panes](#claude-session-panes) |
62
+ | `[tui]`, `[mailbox]` | [Terminal workspace](terminal-workspace.md) |
63
+ | `[host]`, `[[host.sessions]]`, `[[host.answers]]`, `[host.browser]`, `[host.desktop]`, `[[host.desktop.launch]]` | [Sessions pmcp-pty hosts](#sessions-pmcp-pty-hosts) |
64
+
65
+ ## Marketplaces
66
+
67
+ `[marketplaces.<name>]` declares a plugin marketplace once for catalog search
68
+ and for each agent tool:
69
+
70
+ ```toml
71
+ [marketplaces.team]
72
+ source = { path = "packages/marketplace" } # or { github = "owner/repo", ref = "main" } or { builtin = true }
73
+ catalog = true # searchable, like [catalog] marketplaces
74
+ [marketplaces.team.plugins]
75
+ review = { targets = ["claude", "codex"] }
76
+ ```
77
+
78
+ `pmcp project` writes `extraKnownMarketplaces` and `enabledPlugins` in
79
+ `.claude/settings.json`, and `[marketplaces.<name>]` and
80
+ `[plugins."<plugin>@<name>"]` in the pmcp block of `.codex/config.toml`. Local
81
+ sources are written as absolute paths. Codex reads the project file only in a
82
+ trusted project and installs plugins into user state, so `pmcp doctor` prints
83
+ `codex plugin add <plugin>@<name>` for each declared plugin Codex has not
84
+ installed and reports enabled plugins the file does not declare.
85
+ `[catalog] marketplaces` remains an alias.
86
+
87
+ A marketplace name and each plugin name match `^[a-z0-9][a-z0-9-]*$`. `source`
88
+ is required and holds exactly one of `path` (resolved against the toml
89
+ directory), `github` (`owner/repo`, with an optional `ref`) or `builtin = true`.
90
+ `catalog = true` needs a path or builtin source. Each plugin's `targets` is
91
+ required and lists `claude` and/or `codex`. Without the table no marketplace is
92
+ declared.
21
93
 
22
94
  ## Native files for each agent tool
23
95
 
@@ -34,10 +106,10 @@ described in [OpenCode project support](#opencode-project-support).
34
106
  tools = ["claude", "codex", "gemini", "grok", "antigravity"]
35
107
 
36
108
  [skills.deploy]
37
- invocation = "user" # the person starts it; the model is not offered it
109
+ invocation = "user" # the person starts it; the model is not offered it
38
110
 
39
111
  [agents.reviewer.claude]
40
- tools = "Read, Grep" # fields one tool reads stay out of agent.md
112
+ tools = "Read, Grep" # fields one tool reads stay out of agent.md
41
113
 
42
114
  [rules]
43
115
  root = "AGENTS.md"
@@ -55,6 +127,13 @@ pmcp project remove <name>
55
127
  pmcp doctor # ask each installed tool what it loads
56
128
  ```
57
129
 
130
+ | Table | Keys |
131
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
132
+ | `[targets]` | `tools`: list of `claude`, `codex`, `gemini`, `grok`, `antigravity`, `opencode`. Missing means nothing is projected. |
133
+ | `[skills.<name>]` | `invocation`: `"any"` (default) or `"user"`. |
134
+ | `[agents.<name>.<tool>]` | Any keys, merged over the agent's frontmatter; Claude keeps `name`, `description`, `tools`, `model`, `effort`, Gemini keeps `name`, `description`. |
135
+ | `[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. |
136
+
58
137
  Rules go to `.claude/rules/<dir>/`, never the top level, because Grok Build
59
138
  loads top-level `.claude/rules/*.md` in every session regardless of `paths:`.
60
139
  A server that names `${PROJECT_ROOT}` is launched through `sh`, which finds
@@ -64,6 +143,165 @@ overwritten. `doctor` calls no model: it reads `claude mcp list`,
64
143
  `codex mcp list`, `gemini skills list`, `gemini mcp list` and
65
144
  `grok inspect --json`, and skips a tool that is not installed.
66
145
 
146
+ ## Sessions pmcp-pty hosts
147
+
148
+ `[host]` names the sessions pmcp-pty runs for this project and the few dialog
149
+ answers the operator allows it to give. `pmcp project` writes them to
150
+ `.agents/pmcp-pty/host.json` (the sessions) and `.agents/pmcp-pty/policy.json`
151
+ (answers, `mcp_write`, roots), pinned in `pmcp.lock` like every output, and
152
+ `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 the
154
+ operator approved.
155
+
156
+ ```toml
157
+ [host]
158
+ roots = ["."] # every session cwd must be under one of these
159
+ mcp_write = false # pty_turn and pty_lease over pmcp harness mcp
160
+
161
+ [[host.sessions]]
162
+ name = "lead" # lowercase, digits and -; unique
163
+ runtime = "claude" # claude, codex, gemini, agy, grok or opencode
164
+ cwd = "." # inside the project
165
+ argv = ["claude"] # default: the runtime's name
166
+ labels = { task = "review" }
167
+ restart = "on-exit" # or "no" (default); max_restarts defaults to 3
168
+
169
+ [[host.answers]]
170
+ runtime = "gemini"
171
+ dialog = "tool-approval" # the dialog name pmcp-pty's profile reports
172
+ options = ["Allow once"] # option keys or labels
173
+
174
+ [host.browser]
175
+ allow_private = ["localhost:5173"] # host:port or host:*; pmcp-browser is public-only without it
176
+
177
+ [[host.desktop.launch]]
178
+ name = "terminal" # what pmcp-desktop's launch tool takes
179
+ argv = ["xterm"] # never a browser
180
+ ```
181
+
182
+ Login and authentication (`auth-*`), folder and workspace trust and hook
183
+ review dialogs are never answered: a `[[host.answers]]` entry naming one is a
184
+ configuration error, and pmcp-pty refuses them whatever a policy says. Paths
185
+ stay project-relative, so the projected files hold no host path.
186
+ `[host.browser]` and `[[host.desktop.launch]]` widen
187
+ [pmcp-browser and pmcp-desktop](#browser-and-desktop-for-agents) and act only
188
+ from the approved copy too; a launch entry that starts a browser is an error.
189
+
190
+ ### Approving the host policy
191
+
192
+ Run `pmcp harness host approve` in your own terminal after `pmcp project`. It
193
+ prints the sessions, the answer rules, `mcp_write` and one sha256 over both
194
+ projected files, and approves only when you type the first 8 hex digits of
195
+ that hash. The approved copy goes to
196
+ `$XDG_STATE_HOME/pmcp/host-approvals/<project id>/` (directory 0700, files
197
+ 0600; the `[sessions] state_dir` override does not apply), and
198
+ `pmcp-pty daemon --host <that directory>` loads only that copy, after checking
199
+ it still matches its own approval. A later projection that differs is
200
+ reported by `pmcp doctor` and `pmcp harness host status`, and the approved
201
+ copy stays in force until you approve again.
202
+
203
+ `approve` refuses without an interactive terminal, when `PMCP_PTY_*` or a
204
+ coding agent's session variables are set, and when an ancestor process is a
205
+ coding agent or pmcp-pty. With `[host]` declared, the `shell.host_approval`
206
+ guard (deny by default; set `[hooks.guards.shell] host_approval` to change it)
207
+ blocks agents' commands that run `host approve` or touch the approvals
208
+ directory, and their edits there.
209
+
210
+ These checks run as your own user, like the agents themselves. They stop an
211
+ accident and an agent that was told to approve; they are not a security
212
+ boundary, since any process running as you can write the approvals directory
213
+ directly. A real boundary needs the approvals stored under a different user or
214
+ owned by root.
215
+
216
+ ## Browser and desktop for agents
217
+
218
+ Claude Code and Codex offer browser and computer use only through their
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.
257
+
258
+ ## Claude permission rules
259
+
260
+ `[permissions.claude]` declares Claude Code permission rules. `pmcp project`
261
+ adds them to `permissions.allow`, `permissions.ask` and `permissions.deny` in
262
+ `.claude/settings.json` when `claude` is in `[targets] tools`:
263
+
264
+ ```toml
265
+ [permissions.claude]
266
+ ask = ["Read(.env)", "Read(**/*.bak.*)", "Bash(git push:*)", "Bash(git stash:*)"]
267
+ deny = ["WebFetch(domain:internal.example)"]
268
+ ```
269
+
270
+ | Table | Keys |
271
+ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
272
+ | `[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. |
273
+
274
+ Each rule is a Claude permission expression: a tool name (`Bash`, `Read`,
275
+ `Edit`, `Write`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Agent`, `Task`,
276
+ `Skill` and the other built-in tools), optionally followed by a specifier in
277
+ parentheses, or an MCP name such as `mcp__docs` or `mcp__docs__search`.
278
+ `WebFetch` takes `domain:<host>`; a `Bash` prefix `:*` must end the specifier.
279
+ pmcp checks only this structure. It never expands globs or rewrites paths, so
280
+ `Read(.env)` stays `Read(.env)`.
281
+
282
+ pmcp owns only the entries it inserted, and records them in `pmcp.lock`. A rule
283
+ that was already in the list is borrowed: it satisfies the declaration but
284
+ stays unmanaged and survives when the declaration goes. Entries pmcp did not
285
+ write are never removed or reordered, and `defaultMode` and every other
286
+ setting are left alone. A missing table declares nothing; an empty list, a
287
+ removed list or a removed table removes the entries pmcp owns in that list.
288
+
289
+ `pmcp project --check` reports `drift` for a declared rule that is missing and
290
+ for an owned rule that is no longer declared. It reports `conflict` when an
291
+ owned entry was edited or removed by hand, or when the list is not a list of
292
+ strings; `pmcp project` then refuses to write until the native file is
293
+ reviewed. `pmcp doctor` shows how many entries each list owns and borrows, or
294
+ `none declared`.
295
+
296
+ A declared rule that also sits unmanaged in another list, for example a hand
297
+ written `deny` for a rule declared in `ask`, is an `overlap`. Claude's own
298
+ precedence decides it, so `--check` and `doctor` show it as a warning and
299
+ nothing is removed or refused. `pmcp project` also refuses to write when
300
+ `.claude/settings.json` changed while it was planning; run it again.
301
+
302
+ Codex is never written: its native command rules are a separate feature, and
303
+ the hook guards stay its enforcement.
304
+
67
305
  ## Unified project MCP configuration
68
306
 
69
307
  Antigravity receives a native project plugin at .agents/plugins/pmcp-mcp with
@@ -101,7 +339,8 @@ timeout = 120000
101
339
  url means Streamable HTTP; Gemini receives httpUrl. Legacy SSE is not imported
102
340
  as HTTP. headers contains literal nonsecret headers, header_env maps header
103
341
  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.
342
+ token without writing its value. With auth = "native" (the default), each runtime
343
+ retains its own OAuth session.
105
344
  Antigravity HTTP header projection is not qualified and is rejected; explicitly
106
345
  limit those servers to supported targets. tools maps to Gemini includeTools and
107
346
  Codex enabled_tools; it is not a cross-runtime security boundary. Native timeout
@@ -181,8 +420,586 @@ See the [OpenCode MCP configuration](https://opencode.ai/docs/mcp-servers/),
181
420
  [Agent Skills](https://opencode.ai/docs/skills/) and
182
421
  [configuration precedence](https://opencode.ai/docs/config/).
183
422
 
423
+ ## Shared remote MCP authentication
424
+
425
+ Use `auth = "pmcp"` to let Claude, Codex, Gemini, Antigravity, Grok and
426
+ OpenCode share one remote MCP login (only the Claude and Codex entries have run
427
+ live):
428
+
429
+ ```toml
430
+ [mcp.remote]
431
+ url = "https://example.com/mcp"
432
+ auth = "pmcp"
433
+ targets = ["claude", "codex"]
434
+ ```
435
+
436
+ Run `pmcp project`, then `pmcp mcp login remote`. The projected stdio entries
437
+ run `pmcp project exec-mcp remote`; the proxy connects to the declared Streamable
438
+ HTTP endpoint. The login command prints an authorization URL without opening
439
+ a browser. Complete the loopback callback or paste the callback URL or code.
440
+ For a later completion, use `pmcp mcp login remote --no-wait`, then
441
+ `pmcp mcp login remote --code <callback-url-or-code>`. Issuers must support
442
+ PKCE S256 and dynamic client registration, or supply `--client-id` for a
443
+ pre-registered public client. Discovery follows the resource's OAuth metadata.
444
+
445
+ For bearer authentication, declare `bearer_token_env_var` and run login with
446
+ that variable set, or pass `--bearer-env <variable-name>`. The value is stored
447
+ privately and is never projected into runtime configuration or printed.
448
+ `pmcp mcp status remote` reports only credential presence, UTC expiry and scopes.
449
+ `pmcp mcp logout remote` clears the local credentials and requests remote
450
+ revocation when the issuer advertises it.
451
+
452
+ Credentials live in `$XDG_STATE_HOME/pmcp/credentials/<name>.json`, defaulting to
453
+ `~/.local/state/pmcp/credentials/`. Files use mode 0600 and the credential
454
+ directory uses mode 0700. Credentials are bound to the declared server URL.
455
+ Processes reread credentials under an OS lock before refreshing; refresh-token
456
+ rotation is stored atomically. This implementation requires the `flock` command.
457
+ An expired or revoked session reports an authentication error rather than
458
+ starting interactive login inside the MCP connection.
459
+
460
+ The CLI must be installed in the project or available as `pmcp` on PATH.
461
+ Codex receives environment-name references for `XDG_STATE_HOME` and any declared
462
+ header environment variables. `auth = "native"` preserves existing entries,
463
+ OAuth ownership and env_from behavior. Provider authentication remains native.
464
+
465
+ ## Hooks
466
+
467
+ `pmcp project` compiles `[hooks]`, `[sessions]`, `[git]` and `[logging]` into
468
+ `.agents/pmcp-hooks/policy.json`, copies the hook beside it as `hook.mjs` (a
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.
660
+
661
+ ## Sessions
662
+
663
+ Sessions coordinate agents working in one repository and its worktrees. State
664
+ lives in one directory shared by every checkout of the repository.
665
+
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 desk share one state. Outside git it is relative to the directory holding `pmcp.toml`. The hooks, the mod and the git commands resolve it the same way; so does `[git.mainline.gate] tree`. |
670
+
671
+ `store` and `state_dir` alone enable nothing; each feature has its own table:
672
+
673
+ | Table | Keys | Effect |
674
+ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
675
+ | `[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. |
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 land 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. |
677
+ | `[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. |
678
+ | `[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 it lands. |
679
+ | `[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
+
681
+ These tables have no `mode`, except pause. Without `[sessions.registry]` no
682
+ session is recorded, and `[ui.claude]` refuses to project.
683
+
684
+ ### `[sessions.mailbox]`
685
+
686
+ Addressed messages between sessions and the operator. A missing table leaves
687
+ the mailbox off; a declared one, even empty, turns it on.
688
+
689
+ | Key | Type | Default | Meaning |
690
+ | --------------- | ------ | ------- | --------------------------------------------------------------------------- |
691
+ | `enabled` | bool | `true` | `false` keeps the table but turns the mailbox off. |
692
+ | `ttl_minutes` | number | `1440` | Default lifetime of a message; `--ttl` overrides it per message. |
693
+ | `max_delivered` | number | `5` | At most this many new messages are shown at once, plus a count of the rest. |
694
+ | `audit` | bool | `true` | Append a line per sent, delivered, acked and expired event. |
695
+ | `wake` | bool | `false` | Wake idle recipients on every send, as `--wake` does for one message. |
696
+
697
+ Each message is one file, `<state>/messages/<id>.json`, created atomically and
698
+ never rewritten: `id`, `from` (session and alias), `to`, `subject`, `body`,
699
+ `createdAt`, `expiresAt`, `replyTo`, `once`. `to` lists selectors: `all`,
700
+ `session:<id>` (a prefix of at least eight characters works), `alias:<name>`,
701
+ `role:<name>` (a `[sessions.roles]` name or the agent type), or `desk:<path>`
702
+ (the desk's path, or its directory name). A message to `all` reaches the
703
+ sessions that were running when it was sent; a session the registry records
704
+ later does not get earlier broadcasts. Delivery and acknowledgement are
705
+ empty markers under `<state>/inbox/<session>/`, so a message is never edited
706
+ for them. `<state>/messages.jsonl` is the append-only audit.
707
+
708
+ The hooks deliver each unacknowledged message addressed to a session once,
709
+ through that runtime's context channel; on a runtime that does not show
710
+ context at an event, the notice is held for the next one that does. Later
711
+ events notice only messages that arrived since, with a count of earlier
712
+ unacknowledged ones. Delivery is recorded and never counts as an
713
+ acknowledgement. A message sent with `--once` says it is a one-time request,
714
+ so the recipient does not keep its instructions as standing rules.
715
+
716
+ ```sh
717
+ pmcp sessions send --to alias:reviewer --to role:lander --subject deploy --once "Hold the deploy until 14:00"
718
+ echo "longer body" | pmcp sessions send --to all -
719
+ pmcp sessions inbox [--session <id>] [--all] [--json]
720
+ pmcp sessions ack <id>... [--session <id>]
721
+ pmcp sessions reply <id> "Done"
722
+ pmcp sessions send --wake --to alias:reviewer "CI is green again"
723
+ pmcp sessions sweep
724
+ ```
725
+
726
+ A recipient that is idle sees mail only at its next event. With `--wake`, or
727
+ `wake = true` in the table, `send` and `reply` also start a turn in each idle
728
+ recipient whose runtime allows it, and the woken session's hooks then deliver
729
+ the mail as usual; the wake itself carries only a count, the subjects and one
730
+ exact command to run, `pmcp sessions inbox --session <id>`. Each attempt is an
731
+ audit line (`woken`, with the transport and channel), and `pmcp doctor` shows
732
+ each live session's last wake.
733
+
734
+ - Any runtime hosted by pmcp-pty: the session-start hook records the host's
735
+ socket, session and instance from `PMCP_PTY_*` when the host is the
736
+ runtime's parent or grandparent (a runtime started from a hosted session's
737
+ shell inherits the variables but is not recorded). `send --wake` asks the
738
+ host for one short `turn`; the host picks the channel (Claude inbox, OpenCode
739
+ server, Codex queue, Grok leader or a guarded screen write) and its receipt
740
+ is in `send --json`. A refused turn, such as one behind an open dialog,
741
+ leaves the mail for the next event. The same hooks report each turn's start
742
+ and end (with the last assistant message) and permission notices to the
743
+ host, which ends a turn on that before trusting the screen. A hosted
744
+ session gets mail only on the wake turn itself (a prompt starting
745
+ `pmcp mail:`): as context on other prompts the notice took over turns
746
+ pmcp-pty sent. The two items below are for sessions pmcp-pty does not host.
747
+ - Claude Code: through the session's documented
748
+ [cross-session inbox](https://code.claude.com/docs/en/cross-session-messaging),
749
+ found in `~/.claude/sessions/<pid>.json`, which pmcp only reads. The target's
750
+ own inbound controls apply: a session in `bypassPermissions` without
751
+ `crossSessionInbound = "accept"` holds the wake for approval, and a wake can
752
+ approve nothing.
753
+ - OpenCode: `POST /session/<id>/prompt_async` on the server the session runs
754
+ on, which the generated plugin records; HTTP basic auth from
755
+ `OPENCODE_SERVER_PASSWORD` (user `OPENCODE_SERVER_USERNAME`, default
756
+ `opencode`).
757
+ - Codex, Gemini, Antigravity and Grok outside pmcp-pty have no supported way to
758
+ start a turn in a running session; their mail waits for the next event.
759
+ `pmcp sessions status` and `pmcp doctor` show which live sessions can be
760
+ woken.
761
+
762
+ `--session <id>` acts as that session and `--by <name>` as a named sender
763
+ outside one; the notice a session receives spells out its commands with its
764
+ own `--session`. Those commands, and the wake text, say `pmcp` only when the
765
+ `pmcp` on PATH is the CLI that projects this checkout (its own install, else
766
+ the one that last projected it); otherwise they name that CLI as
767
+ `node '<path>/dist/cli.js'`, and `pmcp doctor` warns. Without either, a command run inside a runtime acts as that
768
+ runtime's session: the live session whose runtime process is its nearest
769
+ ancestor, else the id the runtime exposes to tool commands
770
+ (`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `ANTIGRAVITY_CONVERSATION_ID`,
771
+ `GROK_SESSION_ID`; Gemini and OpenCode expose none). When it cannot tell, it
772
+ warns and acts as `operator`. `sweep` also deletes expired messages and their
773
+ markers.
774
+
775
+ `pmcp sessions status` and `pmcp doctor` name live sessions that should be
776
+ restarted to get the current hooks: one started under an older (or untracked)
777
+ `policy.json`, which matters when new hook events were added, and a Codex
778
+ session started before `.codex/hooks.json` last changed, since Codex reads its
779
+ hook file only when a session starts.
780
+
781
+ With the mailbox on, `pmcp sessions broadcast` also sends its text as a
782
+ message to `all`, and the mailbox delivers it instead of
783
+ `[sessions.broadcast]`; `broadcast.json` and each session's `seenBroadcast`
784
+ are still written, so `pmcp sessions status`, the fleet snapshot and the
785
+ Claude status band read broadcasts as before. `unbroadcast` withdraws those
786
+ messages too.
787
+
788
+ ## Git workflow
789
+
790
+ | `[git]` key | Type | Default | Meaning |
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.
842
+
843
+ ## Logging
844
+
845
+ | `[logging]` key | Type | Default | Allowed |
846
+ | --------------- | ------ | ------------------------------------------------ | ----------------------------------------- |
847
+ | `level` | string | `"info"` | `error`, `warn`, `info`, `debug`, `trace` |
848
+ | `format` | string | `"jsonl"` | `jsonl` only |
849
+ | `max_file_mb` | number | `20` | greater than 0 |
850
+ | `keep_days` | number | `14` | greater than 0 |
851
+ | `redact` | list | `["secret_values", "prompt_text", "env_values"]` | any subset |
852
+ | `components` | table | `{}` | `<component> = "<level>"` |
853
+
854
+ The `PMCP_LOG` environment variable overrides the level. `[hooks] error_log`
855
+ switches hook logging on or off. Read the logs with `pmcp logs`.
856
+
857
+ ## Claude session panes
858
+
859
+ `[ui.claude]` installs the session panes into Claude Code: `sessions_pane`,
860
+ `status_band`, `commands` and `hold_foreign_edits`, all booleans defaulting to
861
+ `true`. `hold_foreign_edits` asks before editing a file another live session
862
+ edited. It needs `[sessions.registry]`, and is written only when `claude` is
863
+ in `[targets] tools`. Without the table nothing is installed. `pmcp doctor`
864
+ shows the projected switches, or a failure until `pmcp project` writes them; it
865
+ cannot tell whether a running Claude Code loaded the mod.
866
+
867
+ ## A complete example
868
+
869
+ A project with two runtimes, the full guard set, sessions, the git workflow and
870
+ a team marketplace:
871
+
872
+ ```toml
873
+ [catalog]
874
+ workspaces = [".", "packages/*"]
875
+
876
+ [targets]
877
+ tools = ["claude", "codex"]
878
+
879
+ [mcp.skills]
880
+ command = "node"
881
+ args = ["${PROJECT_ROOT}/node_modules/@modootoday/pmcp/dist/cli.js", "serve"]
882
+
883
+ [skills.deploy]
884
+ invocation = "user"
885
+
886
+ [agents.reviewer.claude]
887
+ tools = "Read, Grep, Glob"
888
+ model = "inherit"
889
+ effort = "high"
890
+
891
+ [hooks]
892
+ targets = ["claude", "codex"]
893
+ ask_fallback = "deny"
894
+
895
+ [hooks.guards.shell.in_place_edit]
896
+ mode = "ask"
897
+
898
+ [hooks.guards.shell.heredoc]
899
+
900
+ [hooks.guards.shell.stdin_interpreter]
901
+
902
+ [hooks.guards.shell.compose_teardown]
903
+
904
+ [hooks.guards.shell.host_approval]
905
+
906
+ [hooks.guards.shell.secret_exfiltration]
907
+ mode = "graded"
908
+
909
+ [[hooks.guards.shell.secret_exfiltration.value_commands]]
910
+ binary = "secrets-cli"
911
+ read = ["read", "env get"]
912
+ publish = ["deploy", "secret put", "secret delete"]
913
+
914
+ [hooks.guards.git.push_without_verify]
915
+
916
+ [hooks.guards.git.forced_branch_move]
917
+
918
+ [hooks.guards.git.stage_all]
919
+
920
+ [hooks.guards.git.gate_bypass_env]
921
+ names = ["ALLOW_DIRECT_PUSH", "GATE_LOCK_HELD"]
922
+
923
+ [[hooks.guards.custom]]
924
+ name = "source-formatting"
925
+ command = ["node", ".agents/guards/source-formatting.mjs"]
926
+ targets = ["codex"]
927
+ on = "after_edit"
928
+
929
+ [hooks.checks.after_edit]
930
+ validator_glob = ".agents/skills/*/scripts/validate.ts"
931
+ command = ["node", "{validator}"]
932
+
933
+ [hooks.checks.on_stop]
934
+
935
+ [sessions]
936
+ state_dir = ".pmcp-state"
937
+
938
+ [sessions.registry]
939
+
940
+ [sessions.pause]
941
+
942
+ [sessions.broadcast]
943
+
944
+ [sessions.mailbox]
945
+ ttl_minutes = 1440
946
+ max_delivered = 5
947
+
948
+ [sessions.leases.lockfile]
949
+ path = "package-lock.json"
950
+ blocks = [["npm", "install"], ["npm", "ci"], ["pmcp", "git", "deliver"]]
951
+
952
+ [sessions.roles.lander]
953
+ allow_commands = [["pmcp", "git", "deliver"], ["git", "log"], ["git", "status"]]
954
+
955
+ [git]
956
+ remote = "origin"
957
+
958
+ [git.mainline]
959
+ branch = "main"
960
+
961
+ [git.mainline.gate]
962
+ command = ["npm", "test"]
963
+
964
+ [git.mainline.deliver]
965
+
966
+ [git.mainline.sync]
967
+ install = ["npm", "ci"]
968
+ install_when_changed = ["package-lock.json"]
969
+
970
+ [git.worktrees]
971
+ bootstrap = ["node", "scripts/worktree-bootstrap.mjs"]
972
+ link_from_main = [".env"]
973
+
974
+ [git.worktrees.sync]
975
+ install_after_move = "background"
976
+ notice_paths = ["AGENTS.md", "pmcp.toml"]
977
+
978
+ [git.submodules]
979
+
980
+ [logging]
981
+ level = "warn"
982
+
983
+ [ui.claude]
984
+
985
+ [permissions.claude]
986
+ ask = ["Read(.env)", "Bash(git push:*)"]
987
+
988
+ [marketplaces.team]
989
+ source = { github = "example/team-marketplace" }
990
+
991
+ [marketplaces.team.plugins]
992
+ review = { targets = ["claude", "codex"] }
993
+ ```
994
+
184
995
  ## Operator shell guards
185
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
+
186
1003
  Declare a project-owned guard explicitly to project it into Codex, Gemini or
187
1004
  Antigravity's native hooks. Without a declaration, pmcp generates no hooks.
188
1005
 
@@ -215,6 +1032,29 @@ contain no trust bypass. Grok can load Claude project hooks, so this first scope
215
1032
  does not generate a second Grok guard. Hooks do not force pmcp catalog use,
216
1033
  inject reminders or replace the runtime's execution sandbox.
217
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
+
218
1058
  ## Native memory metadata
219
1059
 
220
1060
  ```sh