@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.
- package/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +2 -2
- package/.mcp.json +1 -1
- package/CHANGELOG.md +152 -0
- package/CONTRIBUTING.md +71 -0
- package/README.md +98 -201
- package/SECURITY.md +17 -1
- package/dist/apply-JUTGS5WZ.js +242 -0
- package/dist/{attachment-tU5FZrgZ.d.ts → attachment-D84OGI6n.d.ts} +1 -1
- package/dist/available-DBSIVVJ6.js +73 -0
- package/dist/broadcast-CBMVOV3G.js +18 -0
- package/dist/chunk-26WLNWDG.js +93 -0
- package/dist/chunk-2FIV63WC.js +252 -0
- package/dist/chunk-2P4Z2NUX.js +28 -0
- package/dist/chunk-34DECPVC.js +22 -0
- package/dist/chunk-3FCFAQDG.js +42 -0
- package/dist/chunk-3IDXEV5E.js +1934 -0
- package/dist/chunk-3PW4FI7U.js +32 -0
- package/dist/chunk-3Y3HDMHA.js +108 -0
- package/dist/chunk-47O3X4VS.js +113 -0
- package/dist/chunk-4NDEP7HU.js +26 -0
- package/dist/chunk-5OMOPUE6.js +39 -0
- package/dist/chunk-5QQWS4US.js +53 -0
- package/dist/chunk-5ZABTVSW.js +48 -0
- package/dist/chunk-65KAQSJP.js +7 -0
- package/dist/chunk-6STKGOCW.js +27 -0
- package/dist/chunk-6WXMJOMI.js +9 -0
- package/dist/chunk-73AKO4UL.js +24 -0
- package/dist/chunk-7DLZC73N.js +29 -0
- package/dist/chunk-7GBYECSK.js +72 -0
- package/dist/chunk-7HFIGCSL.js +419 -0
- package/dist/chunk-7TD53M7L.js +13 -0
- package/dist/chunk-7UCZAN4J.js +778 -0
- package/dist/chunk-A4PKLESO.js +112 -0
- package/dist/chunk-A7VF7A35.js +1025 -0
- package/dist/chunk-ABTJQ4QV.js +74 -0
- package/dist/chunk-AJ4VXM2U.js +349 -0
- package/dist/chunk-BBTBJCFA.js +380 -0
- package/dist/chunk-BU65MNVU.js +13 -0
- package/dist/chunk-C4NHQGHL.js +142 -0
- package/dist/chunk-CJTKR6K6.js +1213 -0
- package/dist/chunk-D77IRGHO.js +1246 -0
- package/dist/chunk-DCU2EXQV.js +78 -0
- package/dist/chunk-DMZHQZ7P.js +104 -0
- package/dist/chunk-DZ2MRTYT.js +135 -0
- package/dist/chunk-E2YOZ2FF.js +207 -0
- package/dist/chunk-E3DQB5LS.js +48 -0
- package/dist/chunk-EATCUWGG.js +66 -0
- package/dist/chunk-EAWPJHJ7.js +155 -0
- package/dist/chunk-EIDIVIAD.js +33 -0
- package/dist/chunk-F5QYZK7E.js +396 -0
- package/dist/chunk-F5XMGOOX.js +28 -0
- package/dist/chunk-FENOGX3U.js +31 -0
- package/dist/chunk-GZHHEHKY.js +44 -0
- package/dist/chunk-HDMBVLCZ.js +53 -0
- package/dist/chunk-HQOB7OQS.js +81 -0
- package/dist/chunk-I2ZP2PSA.js +211 -0
- package/dist/chunk-IG33DXLT.js +151 -0
- package/dist/chunk-IJBSOWHK.js +86 -0
- package/dist/chunk-INT7QLEU.js +114 -0
- package/dist/chunk-J7UYNJCR.js +9 -0
- package/dist/chunk-JEL35P7S.js +53 -0
- package/dist/chunk-JGJ4INEN.js +32 -0
- package/dist/chunk-JS5RTH4I.js +84 -0
- package/dist/chunk-JWRZDYB5.js +59 -0
- package/dist/chunk-KMXRRSKT.js +660 -0
- package/dist/chunk-LBXO4VPG.js +73 -0
- package/dist/chunk-LLBPVZXM.js +67 -0
- package/dist/chunk-LLT5FQBE.js +57 -0
- package/dist/chunk-LMT3PPXJ.js +17 -0
- package/dist/chunk-LMUBBIE2.js +83 -0
- package/dist/chunk-LTZH5E3G.js +479 -0
- package/dist/chunk-LW4TG7EL.js +39 -0
- package/dist/chunk-MPSQXSC6.js +346 -0
- package/dist/chunk-MVFH26QT.js +97 -0
- package/dist/chunk-NLEXKE7U.js +67 -0
- package/dist/chunk-NQPURJT5.js +44 -0
- package/dist/chunk-NRBQK6UX.js +105 -0
- package/dist/chunk-OEH47H6A.js +48 -0
- package/dist/chunk-OG7QR2DP.js +75 -0
- package/dist/chunk-OPYFEHKG.js +52 -0
- package/dist/chunk-P4N7DBD5.js +83 -0
- package/dist/chunk-PAX3QXX2.js +140 -0
- package/dist/chunk-PKODFR5F.js +102 -0
- package/dist/chunk-PMJG2CXF.js +122 -0
- package/dist/chunk-Q5H3L6Y4.js +23 -0
- package/dist/chunk-QEF7EK3T.js +28 -0
- package/dist/chunk-QEW4J3IZ.js +74 -0
- package/dist/chunk-QPL7E2HW.js +464 -0
- package/dist/chunk-R2GPCZUX.js +22 -0
- package/dist/chunk-R5MT42JS.js +284 -0
- package/dist/chunk-RMATE45Z.js +197 -0
- package/dist/chunk-RPQOBHVU.js +87 -0
- package/dist/chunk-S3PIAMXV.js +230 -0
- package/dist/chunk-T3LKX23M.js +168 -0
- package/dist/chunk-T6GOWHK6.js +30 -0
- package/dist/chunk-TIA4SPU2.js +10 -0
- package/dist/chunk-TNCZ6444.js +57 -0
- package/dist/chunk-TVL5RTE6.js +269 -0
- package/dist/chunk-TXQ7L33K.js +45 -0
- package/dist/chunk-UPQTAHUK.js +189 -0
- package/dist/chunk-V4NPDK6X.js +14 -0
- package/dist/chunk-VJFEN6DJ.js +38 -0
- package/dist/chunk-VMHUEOT5.js +643 -0
- package/dist/chunk-VRPMYPZU.js +4985 -0
- package/dist/chunk-WIW772I3.js +25 -0
- package/dist/chunk-XELAZAIM.js +136 -0
- package/dist/chunk-XNML2KIC.js +23 -0
- package/dist/chunk-XP2U3LO3.js +30 -0
- package/dist/chunk-YGOWIJPE.js +51 -0
- package/dist/chunk-YIXDHQYE.js +11 -0
- package/dist/chunk-YSAWTGNA.js +117 -0
- package/dist/claude-U2JC2DNQ.js +77 -0
- package/dist/cli-MI4ZCAZ3.js +41 -0
- package/dist/cli-ZN7ZVDEZ.js +46 -0
- package/dist/cli.js +144 -16197
- package/dist/completion-ILSRB3LW.js +142 -0
- package/dist/config-DnpLL2kT.d.ts +46 -0
- package/dist/{service-qpCsOXkQ.d.ts → core-C1LPjxK6.d.ts} +2 -6
- package/dist/diagnostics-XKXVVQWH.js +93 -0
- package/dist/doctor-O2E63YGO.js +538 -0
- package/dist/entry-X6CSYQRQ.js +305 -0
- package/dist/exec-mcp-2PMWBPD7.js +365 -0
- package/dist/harness-L2KSI2ZB.js +177 -0
- package/dist/harness-egress-bridge.js +4 -4
- package/dist/harness-launch-gate.js +47 -940
- package/dist/harness-pane-runner.js +13 -80
- package/dist/harness-worker.js +21 -2703
- package/dist/hook-body.js +5222 -0
- package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
- package/dist/hook.js +26 -0
- package/dist/hooks-BHTA44X7.js +21 -0
- package/dist/host-UIZAXXQH.js +22 -0
- package/dist/host-UWK754BW.js +210 -0
- package/dist/host-run-BI2OTZDZ.js +307 -0
- package/dist/http.d.ts +5 -42
- package/dist/http.js +21 -2234
- package/dist/import-mcp-GPKJI7DI.js +400 -0
- package/dist/index.d.ts +146 -168
- package/dist/index.js +133 -4948
- package/dist/init-3C2Y7BNJ.js +14 -0
- package/dist/install-GG7HHZK2.js +796 -0
- package/dist/invoke-44CJRVMK.js +23 -0
- package/dist/list-MCP2FXUF.js +68 -0
- package/dist/list-WL6L4J5H.js +65 -0
- package/dist/load-BEUBABtB.d.ts +21 -0
- package/dist/logout-F5EJ5MOU.js +44 -0
- package/dist/logs-TBUA4UWU.js +107 -0
- package/dist/mailbox/index.d.ts +10 -5
- package/dist/mailbox/index.js +53 -1572
- package/dist/mailbox-BMTZOSZ7.js +285 -0
- package/dist/mailbox-GDJ7BWQN.js +189 -0
- package/dist/mainline-KAD2ERLP.js +639 -0
- package/dist/marketplace-G4VQET5W.js +191 -0
- package/dist/mcp-235QZN2A.js +15 -0
- package/dist/mcp-FJ2UQ4RH.js +193 -0
- package/dist/models-ISU4DCMA.js +32 -0
- package/dist/opencode-CN7JLQYO.js +60 -0
- package/dist/pause-7LILUVGL.js +18 -0
- package/dist/preview-DT7DWG5F.js +91 -0
- package/dist/project/hook-adapter.d.ts +5 -2
- package/dist/project/hook-adapter.js +41 -27
- package/dist/project-5YV5CUEG.js +70 -0
- package/dist/pty-XTJ4MIWK.js +94 -0
- package/dist/recovery-U6QB3PMT.js +100 -0
- package/dist/reindex-Y27QJFDB.js +22 -0
- package/dist/resume-26VFAAMH.js +18 -0
- package/dist/run-3AXTZSR7.js +126 -0
- package/dist/run-3SOVRQIA.js +19 -0
- package/dist/serve-DQMKTFIV.js +104 -0
- package/dist/session-XM2CR425.js +159 -0
- package/dist/setup-DTKZLZUT.js +18 -0
- package/dist/start-login-YTZV6KMF.js +416 -0
- package/dist/status-A2OUTNGK.js +9 -0
- package/dist/status-H2VAHIDV.js +10 -0
- package/dist/status-MROQ7WR7.js +43 -0
- package/dist/status-RO55QPKV.js +55 -0
- package/dist/status-UME2L33L.js +286 -0
- package/dist/stdio.d.ts +3 -13
- package/dist/stdio.js +16 -3186
- package/dist/sweep-35LGQTTO.js +18 -0
- package/dist/test-AGZOJLRZ.js +561 -0
- package/dist/tools-gpHNq9Dh.d.ts +328 -0
- package/dist/tui-G5LLWCSV.js +153 -0
- package/dist/unbroadcast-5QNGAJR2.js +18 -0
- package/dist/validate-IU52H2IC.js +46 -0
- package/dist/worker-QZ5T6LJD.js +80 -0
- package/dist/worktree-create-PZSRB7PH.js +89 -0
- package/dist/worktree-list-JYB6VXLW.js +51 -0
- package/dist/worktree-sync-UF5CXPWV.js +30 -0
- package/docs/authoring.md +82 -0
- package/docs/browser-and-desktop.md +46 -0
- package/docs/commands.md +325 -0
- package/docs/compare.md +35 -0
- package/docs/compatibility.md +55 -0
- package/docs/embeddings.md +1 -1
- package/docs/getting-started.md +105 -0
- package/docs/git-workflow.md +60 -0
- package/docs/glossary.md +31 -0
- package/docs/hooks/capabilities/antigravity.json +199 -0
- package/docs/hooks/capabilities/claude.json +179 -0
- package/docs/hooks/capabilities/codex.json +179 -0
- package/docs/hooks/capabilities/gemini.json +196 -0
- package/docs/hooks/capabilities/grok.json +192 -0
- package/docs/hooks/capabilities/opencode.json +184 -0
- package/docs/hooks.md +264 -0
- package/docs/install.md +72 -0
- package/docs/library-skills.md +132 -0
- package/docs/mailbox.md +16 -5
- package/docs/project-configuration.md +540 -58
- package/docs/sessions.md +64 -0
- package/docs/skills.md +4 -45
- package/docs/terminal-harness.md +92 -44
- package/docs/terminal-workspace.md +81 -169
- package/gemini-extension.json +2 -2
- package/mcp.json +1 -1
- package/package.json +16 -2
- package/plugin.json +2 -2
- package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
- package/plugins/pmcp/.mcp.json +1 -1
- package/plugins/pmcp/gemini-extension.json +2 -2
- package/plugins/pmcp/mcp.json +1 -1
- package/plugins/pmcp/mod/commands.ts +72 -0
- package/plugins/pmcp/mod/contract.d.ts +39 -0
- package/plugins/pmcp/mod/draw.tsx +216 -0
- package/plugins/pmcp/mod/guard.ts +42 -0
- package/plugins/pmcp/mod/hooks.json +4 -0
- package/plugins/pmcp/mod/host.ts +46 -0
- package/plugins/pmcp/mod/model.ts +144 -0
- package/plugins/pmcp/mod/reader/index.ts +18 -0
- package/plugins/pmcp/mod/reader/read.ts +76 -0
- package/plugins/pmcp/mod/reader/settings.ts +54 -0
- package/plugins/pmcp/mod/reader/types.ts +38 -0
- package/plugins/pmcp/mod/register.tsx +73 -0
- package/plugins/pmcp/mod/sessions/format.ts +91 -0
- package/plugins/pmcp/mod/sessions/types.ts +162 -0
- package/plugins/pmcp/mod/snapshot.ts +75 -0
- package/plugins/pmcp/mod/spinner.tsx +30 -0
- package/plugins/pmcp/mod/state.ts +28 -0
- package/plugins/pmcp/plugin.json +2 -2
- package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
- package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
- package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -15
- package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
- package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
- package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +153 -0
- package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +96 -0
- package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +89 -0
- package/schema/catalog-v1.json +187 -0
- package/schema/library.json +196 -0
- package/schema/marketplace-manifest.json +144 -0
- package/schema/plugin-manifest.json +59 -0
- package/schema/skill-frontmatter.json +170 -0
- package/schema/skill-metadata-core.json +131 -0
- package/skills/agent-assets-migrate/SKILL.md +96 -0
- package/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
- package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/skills/package-skill-catalog/SKILL.md +51 -15
- package/skills/pmcp-browser/SKILL.md +27 -0
- package/skills/pmcp-desktop/SKILL.md +25 -0
- package/skills/pmcp-project-init/SKILL.md +153 -0
- package/skills/pmcp-sessions-and-git/SKILL.md +96 -0
- package/skills/skill-package-scaffold/SKILL.md +89 -0
- package/dist/config-BkSpjUG6.d.ts +0 -50
- package/dist/embed-DRROSD3F.d.ts +0 -53
- package/dist/hook-spec-CSJJySsH.d.ts +0 -11
- package/dist/server-VWSY3Shw.d.ts +0 -543
- package/dist/tui-worker.js +0 -6549
- package/docs/manual-library-skills.md +0 -74
- /package/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
{
|
|
2
|
+
"runtime": "grok",
|
|
3
|
+
"version": "1.0.50",
|
|
4
|
+
"measuredAt": "2026-10-20T01:05:00Z",
|
|
5
|
+
"configuration": {
|
|
6
|
+
"hooks": "merged from ~/.grok/hooks/*.json, ~/.claude/settings.json (+ .local), ~/.cursor/hooks.json, <project>/.grok/hooks/*.json, <project>/.claude/settings.json (+ .local), <project>/.cursor/hooks.json, [[hooks.<Event>]] in ~/.grok/config.toml, managed/requirements toml, plugins",
|
|
7
|
+
"double_hooks": "measured: all three sources fire together. Each PreToolUse dispatched 4 hooks: global/settings (the user's ~/.claude/settings.json Bash hook, run for both shell calls, not for the write), project/settings (project .claude/settings.json) and project/probe (.grok/hooks, two handlers). Every recorded event appears once from .grok/hooks and once from .claude/settings.json. A pmcp projection that writes Claude hooks into .claude/settings.json and grok hooks into .grok/hooks would run each check twice; the adapter must project into one of them (or disable compat with [compat.claude] hooks = false, a user-level setting).",
|
|
8
|
+
"hook_env": "measured: a .claude/settings.json hook runs with CLAUDE_PROJECT_DIR and GROK_WORKSPACE_ROOT set to the project root and PWD at the project root, so a Claude projection's $CLAUDE_PROJECT_DIR command resolves under grok",
|
|
9
|
+
"trust": "measured: before trust, projectTrusted false and no project hook ran; after /hooks-trust, grok inspect lists 30 .grok/hooks handlers and 15 .claude handlers and they run headless. Trust is folder-wide (MCP, LSP, instructions, skills).",
|
|
10
|
+
"headless": "grok -p '<prompt>' --output-format json -> {text, stopReason, sessionId, usage, num_turns}; --permission-mode dontAsk with --allow rules ran the allowed tools without prompts",
|
|
11
|
+
"mcp": "documented: [mcp_servers.<name>] in <repo-root>/.grok/config.toml or <cwd>/.grok/config.toml (command or url), trust-gated; tools <server>__<tool> via search_tool/use_tool. Not exercised."
|
|
12
|
+
},
|
|
13
|
+
"events": {
|
|
14
|
+
"session_start": {
|
|
15
|
+
"native": "SessionStart",
|
|
16
|
+
"fires": true,
|
|
17
|
+
"fields": [
|
|
18
|
+
"hookEventName",
|
|
19
|
+
"sessionId",
|
|
20
|
+
"cwd",
|
|
21
|
+
"workspaceRoot",
|
|
22
|
+
"timestamp",
|
|
23
|
+
"transcriptPath",
|
|
24
|
+
"permissionMode",
|
|
25
|
+
"source",
|
|
26
|
+
"and snake_case twins"
|
|
27
|
+
]
|
|
28
|
+
},
|
|
29
|
+
"prompt": {
|
|
30
|
+
"native": "UserPromptSubmit",
|
|
31
|
+
"fires": true
|
|
32
|
+
},
|
|
33
|
+
"before_tool": {
|
|
34
|
+
"native": "PreToolUse",
|
|
35
|
+
"fires": true,
|
|
36
|
+
"fields": [
|
|
37
|
+
"hookEventName",
|
|
38
|
+
"sessionId",
|
|
39
|
+
"cwd",
|
|
40
|
+
"workspaceRoot",
|
|
41
|
+
"timestamp",
|
|
42
|
+
"transcriptPath",
|
|
43
|
+
"permissionMode",
|
|
44
|
+
"toolName",
|
|
45
|
+
"toolUseId",
|
|
46
|
+
"toolInput",
|
|
47
|
+
"toolInputTruncated",
|
|
48
|
+
"hook_event_name",
|
|
49
|
+
"session_id",
|
|
50
|
+
"transcript_path",
|
|
51
|
+
"permission_mode",
|
|
52
|
+
"tool_name",
|
|
53
|
+
"tool_input",
|
|
54
|
+
"tool_use_id"
|
|
55
|
+
]
|
|
56
|
+
},
|
|
57
|
+
"after_tool": {
|
|
58
|
+
"native": "PostToolUse",
|
|
59
|
+
"fires": true,
|
|
60
|
+
"notes": "not for the denied call"
|
|
61
|
+
},
|
|
62
|
+
"stop": {
|
|
63
|
+
"native": "Stop",
|
|
64
|
+
"fires": true,
|
|
65
|
+
"fields": ["... common", "reason", "stopHookActive", "stop_hook_active"]
|
|
66
|
+
},
|
|
67
|
+
"session_end": {
|
|
68
|
+
"native": "SessionEnd",
|
|
69
|
+
"fires": true,
|
|
70
|
+
"fields": ["... common", "reason (shutdown)"]
|
|
71
|
+
},
|
|
72
|
+
"other_documented": "PostToolUseFailure, PermissionDenied, StopFailure, StopCancelled, Notification, SubagentStart, SubagentStop, PreCompact, PostCompact (not triggered in this run)",
|
|
73
|
+
"notification": {
|
|
74
|
+
"native": "Notification",
|
|
75
|
+
"fires": false,
|
|
76
|
+
"notes": "documented, not triggered"
|
|
77
|
+
}
|
|
78
|
+
},
|
|
79
|
+
"tools": {
|
|
80
|
+
"shell": {
|
|
81
|
+
"tool_name": "run_terminal_command (matcher alias Bash)",
|
|
82
|
+
"input": "tool_input.command, tool_input.description"
|
|
83
|
+
},
|
|
84
|
+
"edit": {
|
|
85
|
+
"tool_name": "write (matcher alias Write); search_replace for edits (documented)",
|
|
86
|
+
"input": "tool_input.file_path, tool_input.content"
|
|
87
|
+
}
|
|
88
|
+
},
|
|
89
|
+
"outputs": {
|
|
90
|
+
"deny": {
|
|
91
|
+
"event": "before_tool",
|
|
92
|
+
"support": "measured",
|
|
93
|
+
"shape": "hookSpecificOutput.permissionDecision deny + permissionDecisionReason; the tool result reads 'Hook denied: <reason>' and the model reports it"
|
|
94
|
+
},
|
|
95
|
+
"context": {
|
|
96
|
+
"support": "measured",
|
|
97
|
+
"delivered": ["before_tool", "after_tool", "stop"],
|
|
98
|
+
"not_delivered": ["session_start", "prompt"],
|
|
99
|
+
"shape": "hookSpecificOutput.additionalContext; before_tool context arrives after the call ran, with its results",
|
|
100
|
+
"native_delivered": ["before_tool", "after_tool", "stop"],
|
|
101
|
+
"deferred": {
|
|
102
|
+
"session_start": "before_tool; V2 grok-context-start-fcfd44d1",
|
|
103
|
+
"prompt": "before_tool; V2 grok-context-prompt-6c279a76"
|
|
104
|
+
}
|
|
105
|
+
},
|
|
106
|
+
"stop_context": {
|
|
107
|
+
"support": "measured",
|
|
108
|
+
"notes": "additionalContext on Stop continues the turn, as on Claude: 9 Stop events in one run until --max-turns 10. Policies may return Stop context only when stop_hook_active is false."
|
|
109
|
+
},
|
|
110
|
+
"ask": {
|
|
111
|
+
"support": "documented",
|
|
112
|
+
"notes": "decision ask reaches the permission prompt; dontAsk turns it into a deny"
|
|
113
|
+
},
|
|
114
|
+
"failure": {
|
|
115
|
+
"support": "documented",
|
|
116
|
+
"notes": "hook failures fail open; only an explicit deny blocks"
|
|
117
|
+
}
|
|
118
|
+
},
|
|
119
|
+
"fields_absent": [
|
|
120
|
+
"promptId (documented, absent in this headless run)",
|
|
121
|
+
"agent_type"
|
|
122
|
+
],
|
|
123
|
+
"timeouts": "default 5 s; 600 s for Stop, SubagentStop and PostToolUse gates",
|
|
124
|
+
"trust": "folder trust (~/.grok/trusted_folders.toml) required for any project hook, including .claude/settings.json; user-level ~/.claude/settings.json hooks run without it",
|
|
125
|
+
"live": {
|
|
126
|
+
"version": "1.0.62",
|
|
127
|
+
"measuredAt": "2026-10-20T03:50:35.533Z",
|
|
128
|
+
"implementationCommits": ["cfcdf5a", "35f3c77"],
|
|
129
|
+
"deny": {
|
|
130
|
+
"support": "measured",
|
|
131
|
+
"scenarios": [
|
|
132
|
+
"grok-heredoc-0a303279",
|
|
133
|
+
"grok-stage-all-a0ae281d",
|
|
134
|
+
"grok-pause-cc959085",
|
|
135
|
+
"grok-lease-677333e4"
|
|
136
|
+
]
|
|
137
|
+
},
|
|
138
|
+
"context": {
|
|
139
|
+
"support": "measured",
|
|
140
|
+
"scenarios": {
|
|
141
|
+
"context-start": "grok-context-start-fcfd44d1",
|
|
142
|
+
"context-prompt": "grok-context-prompt-6c279a76",
|
|
143
|
+
"context-before": "grok-context-before-8db85a8c",
|
|
144
|
+
"broadcast": "grok-broadcast-c9f5d420"
|
|
145
|
+
},
|
|
146
|
+
"notes": "pause, broadcast and shared_checkout notices reached the model; held context arrived at the next delivering event"
|
|
147
|
+
},
|
|
148
|
+
"workflow": {
|
|
149
|
+
"support": "measured",
|
|
150
|
+
"scenarios": [
|
|
151
|
+
"grok-worktree-create-53b690da",
|
|
152
|
+
"grok-worktree-sync-18990306",
|
|
153
|
+
"grok-deliver-86fb266a",
|
|
154
|
+
"grok-deliver-race-e292c85c",
|
|
155
|
+
"grok-git-sync-adeae993"
|
|
156
|
+
]
|
|
157
|
+
},
|
|
158
|
+
"cost": [
|
|
159
|
+
{
|
|
160
|
+
"event": "before_tool",
|
|
161
|
+
"addedMs": 28.8
|
|
162
|
+
},
|
|
163
|
+
{
|
|
164
|
+
"event": "prompt",
|
|
165
|
+
"addedMs": 20.8
|
|
166
|
+
}
|
|
167
|
+
],
|
|
168
|
+
"single_dispatch": {
|
|
169
|
+
"support": "measured",
|
|
170
|
+
"notes": "With claude and grok targeted, pmcp projects only .claude/settings.json; every V2 grok run logged each hook once as runtime grok",
|
|
171
|
+
"scenarios": [
|
|
172
|
+
"grok-heredoc-0a303279",
|
|
173
|
+
"grok-stage-all-a0ae281d",
|
|
174
|
+
"grok-context-start-fcfd44d1",
|
|
175
|
+
"grok-context-prompt-6c279a76",
|
|
176
|
+
"grok-context-before-8db85a8c",
|
|
177
|
+
"grok-pause-cc959085",
|
|
178
|
+
"grok-lease-677333e4",
|
|
179
|
+
"grok-broadcast-c9f5d420",
|
|
180
|
+
"grok-worktree-create-53b690da",
|
|
181
|
+
"grok-worktree-sync-18990306",
|
|
182
|
+
"grok-deliver-86fb266a",
|
|
183
|
+
"grok-deliver-race-e292c85c",
|
|
184
|
+
"grok-git-sync-adeae993"
|
|
185
|
+
]
|
|
186
|
+
},
|
|
187
|
+
"scenarios": {
|
|
188
|
+
"passed": 13,
|
|
189
|
+
"failed": []
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
{
|
|
2
|
+
"runtime": "opencode",
|
|
3
|
+
"version": "1.18.33",
|
|
4
|
+
"measuredAt": "2026-10-20T01:10:00Z",
|
|
5
|
+
"configuration": {
|
|
6
|
+
"hooks": "no shell-command hooks. Extension surface is a JS/TS plugin: project .opencode/plugin/*.{ts,js} or .opencode/plugins/, global ~/.config/opencode/plugin(s)/, or npm packages in opencode.json \"plugin\". A plugin is an async function receiving {client, project, worktree, directory, experimental_workspace, serverUrl, $ (Bun shell)} and returning a Hooks object. The probe also saw 45 plugin.added events for built-in plugins.",
|
|
7
|
+
"trust": "measured: none; the project plugin loaded in a fresh directory",
|
|
8
|
+
"headless": "measured: opencode run '<prompt>' --format json < /dev/null emits one JSON event per line (tool parts with state {status, input, output|error}, text parts). Default permissions ran bash and write without a prompt (permission.ask never fired).",
|
|
9
|
+
"mcp": "documented: \"mcp\" in opencode.json (project or ~/.config/opencode); pmcp already projects it. Not exercised."
|
|
10
|
+
},
|
|
11
|
+
"events": {
|
|
12
|
+
"plugin_init": {
|
|
13
|
+
"native": "plugin function call",
|
|
14
|
+
"fires": true,
|
|
15
|
+
"fields": [
|
|
16
|
+
"client",
|
|
17
|
+
"project",
|
|
18
|
+
"worktree",
|
|
19
|
+
"directory",
|
|
20
|
+
"experimental_workspace",
|
|
21
|
+
"serverUrl",
|
|
22
|
+
"$"
|
|
23
|
+
]
|
|
24
|
+
},
|
|
25
|
+
"prompt": {
|
|
26
|
+
"native": "chat.message",
|
|
27
|
+
"fires": true,
|
|
28
|
+
"fields": ["input.sessionID", "output.message", "output.parts"]
|
|
29
|
+
},
|
|
30
|
+
"system": {
|
|
31
|
+
"native": "experimental.chat.system.transform",
|
|
32
|
+
"fires": true,
|
|
33
|
+
"notes": "before every model call (5 times)"
|
|
34
|
+
},
|
|
35
|
+
"before_tool": {
|
|
36
|
+
"native": "tool.execute.before",
|
|
37
|
+
"fires": true,
|
|
38
|
+
"fields": [
|
|
39
|
+
"input.tool",
|
|
40
|
+
"input.sessionID",
|
|
41
|
+
"input.callID",
|
|
42
|
+
"output.args (mutable)"
|
|
43
|
+
]
|
|
44
|
+
},
|
|
45
|
+
"after_tool": {
|
|
46
|
+
"native": "tool.execute.after",
|
|
47
|
+
"fires": true,
|
|
48
|
+
"fields": [
|
|
49
|
+
"input.tool",
|
|
50
|
+
"input.sessionID",
|
|
51
|
+
"input.callID",
|
|
52
|
+
"input.args",
|
|
53
|
+
"output.title",
|
|
54
|
+
"output.output (mutable)",
|
|
55
|
+
"output.metadata"
|
|
56
|
+
],
|
|
57
|
+
"notes": "not for the refused call"
|
|
58
|
+
},
|
|
59
|
+
"permission": {
|
|
60
|
+
"native": "permission.ask",
|
|
61
|
+
"fires": "not in this run (no permission prompt)"
|
|
62
|
+
},
|
|
63
|
+
"session_start": {
|
|
64
|
+
"native": "event session.created",
|
|
65
|
+
"fires": true
|
|
66
|
+
},
|
|
67
|
+
"stop": {
|
|
68
|
+
"native": "event session.idle (and session.status idle)",
|
|
69
|
+
"fires": true,
|
|
70
|
+
"notes": "an event only; nothing can hold the turn open. pmcp maps it to stop for the registry"
|
|
71
|
+
},
|
|
72
|
+
"file_edit": {
|
|
73
|
+
"native": "event file.edited",
|
|
74
|
+
"fires": true
|
|
75
|
+
},
|
|
76
|
+
"session_end": {
|
|
77
|
+
"native": null,
|
|
78
|
+
"fires": false,
|
|
79
|
+
"notes": "no dedicated event; dispose() on plugin shutdown"
|
|
80
|
+
},
|
|
81
|
+
"notification": {
|
|
82
|
+
"native": null,
|
|
83
|
+
"fires": false
|
|
84
|
+
}
|
|
85
|
+
},
|
|
86
|
+
"tools": {
|
|
87
|
+
"shell": {
|
|
88
|
+
"tool_name": "bash",
|
|
89
|
+
"input": "args.command"
|
|
90
|
+
},
|
|
91
|
+
"edit": {
|
|
92
|
+
"tool_name": "write (edit, patch documented)",
|
|
93
|
+
"input": "args.filePath, args.content"
|
|
94
|
+
}
|
|
95
|
+
},
|
|
96
|
+
"outputs": {
|
|
97
|
+
"deny": {
|
|
98
|
+
"event": "before_tool",
|
|
99
|
+
"support": "measured",
|
|
100
|
+
"shape": "throw new Error(reason) in tool.execute.before; the tool part ends status error with the message, and the model reads it"
|
|
101
|
+
},
|
|
102
|
+
"context": {
|
|
103
|
+
"support": "measured",
|
|
104
|
+
"delivered": ["session_start", "prompt", "after_tool"],
|
|
105
|
+
"notes": "the model quoted the system token and both after-tool tokens; a before-tool note has no channel except mutating args",
|
|
106
|
+
"native_delivered": [
|
|
107
|
+
"system (experimental.chat.system.transform output.system.push)",
|
|
108
|
+
"after_tool (append to output.output)"
|
|
109
|
+
],
|
|
110
|
+
"deferred": {
|
|
111
|
+
"before_tool": "after_tool (appended to the tool output); V2 opencode-context-before-cc5abe06"
|
|
112
|
+
}
|
|
113
|
+
},
|
|
114
|
+
"stop_context": {
|
|
115
|
+
"support": "unsupported",
|
|
116
|
+
"notes": "no blocking stop hook; session.idle is observe-only"
|
|
117
|
+
},
|
|
118
|
+
"shell_hook": {
|
|
119
|
+
"support": "measured",
|
|
120
|
+
"notes": "the plugin spawned a hook recorder from tool.execute.before three times (status 0, stdout '{}'). A pmcp adapter can be a small generated plugin that spawns hook.mjs with a normalized payload and maps a deny to a throw."
|
|
121
|
+
}
|
|
122
|
+
},
|
|
123
|
+
"fields_absent": [
|
|
124
|
+
"cwd per call (plugin context.directory instead)",
|
|
125
|
+
"transcript path",
|
|
126
|
+
"turn id",
|
|
127
|
+
"agent_type"
|
|
128
|
+
],
|
|
129
|
+
"timeouts": "none documented; plugin hooks are awaited in-process",
|
|
130
|
+
"trust": "none for project plugins",
|
|
131
|
+
"live": {
|
|
132
|
+
"version": "1.18.33",
|
|
133
|
+
"measuredAt": "2026-10-20T04:09:02.251Z",
|
|
134
|
+
"implementationCommits": ["cfcdf5a", "35f3c77"],
|
|
135
|
+
"deny": {
|
|
136
|
+
"support": "measured",
|
|
137
|
+
"scenarios": [
|
|
138
|
+
"opencode-heredoc-ae7c72b4",
|
|
139
|
+
"opencode-stage-all-1f03dfa7",
|
|
140
|
+
"opencode-pause-69d76efd",
|
|
141
|
+
"opencode-lease-848c6985"
|
|
142
|
+
]
|
|
143
|
+
},
|
|
144
|
+
"context": {
|
|
145
|
+
"support": "measured",
|
|
146
|
+
"scenarios": {
|
|
147
|
+
"context-start": "opencode-context-start-5d6b3d08",
|
|
148
|
+
"context-prompt": null,
|
|
149
|
+
"context-before": "opencode-context-before-cc5abe06",
|
|
150
|
+
"broadcast": "opencode-broadcast-3c5d63c7"
|
|
151
|
+
},
|
|
152
|
+
"notes": "pause, broadcast and shared_checkout notices reached the model; held context arrived at the next delivering event"
|
|
153
|
+
},
|
|
154
|
+
"workflow": {
|
|
155
|
+
"support": "measured",
|
|
156
|
+
"scenarios": [
|
|
157
|
+
"opencode-worktree-create-e471494b",
|
|
158
|
+
"opencode-worktree-sync-9d07d8bb",
|
|
159
|
+
"opencode-deliver-8fe00875",
|
|
160
|
+
"opencode-deliver-race-acb9ab49",
|
|
161
|
+
"opencode-git-sync-35481ffa"
|
|
162
|
+
]
|
|
163
|
+
},
|
|
164
|
+
"cost": [
|
|
165
|
+
{
|
|
166
|
+
"event": "before_tool",
|
|
167
|
+
"addedMs": 25.7
|
|
168
|
+
},
|
|
169
|
+
{
|
|
170
|
+
"event": "prompt",
|
|
171
|
+
"addedMs": 24.5
|
|
172
|
+
}
|
|
173
|
+
],
|
|
174
|
+
"prompt_context": {
|
|
175
|
+
"support": "limit",
|
|
176
|
+
"notes": "opencode stores no system prompt; context-prompt cannot show delivery. The plugin fix 35f3c77 is shown live by the system probes: before it the main model replied NONE, after it the model repeated the token.",
|
|
177
|
+
"run": "opencode-context-prompt-ccfc54b7"
|
|
178
|
+
},
|
|
179
|
+
"scenarios": {
|
|
180
|
+
"passed": 12,
|
|
181
|
+
"failed": ["context-prompt"]
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
}
|
package/docs/hooks.md
ADDED
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
# Hooks
|
|
2
|
+
|
|
3
|
+
[Back to the overview](../README.md)
|
|
4
|
+
|
|
5
|
+
`[hooks]` in `pmcp.toml` compiles guards, checks and session bookkeeping into one hook bundle that
|
|
6
|
+
every targeted runtime runs on its tool calls. The other tables are in the
|
|
7
|
+
[pmcp.toml reference](project-configuration.md).
|
|
8
|
+
|
|
9
|
+
`pmcp project` compiles `[hooks]`, `[sessions]`, `[git]` and `[logging]` into
|
|
10
|
+
`.agents/pmcp-hooks/policy.json`, copies the hook beside it as `hook.mjs` (a
|
|
11
|
+
small loader) and `hook-body.mjs`, and registers `hook.mjs` in
|
|
12
|
+
`.claude/settings.json` and `.codex/hooks.json` for the events the declared
|
|
13
|
+
features use. Gemini, Antigravity, Grok and OpenCode are opt-in: name them in
|
|
14
|
+
`[hooks] targets` and pmcp registers the same hook in their files (see
|
|
15
|
+
[Runtime support](#runtime-support)). `pmcp.lock` pins the hash of `policy.json`; the hook refuses to
|
|
16
|
+
act on a policy that does not match it, so every policy change is a reviewed
|
|
17
|
+
projection. Codex shows changed entries under `/hooks` as needing review;
|
|
18
|
+
untrusted hooks do not run. Each Codex, Claude and Grok entry carries a
|
|
19
|
+
`statusMessage` such as `pmcp session start` or `pmcp before tool`: Codex
|
|
20
|
+
lists hooks under that name, and Claude and Grok show it while the hook runs.
|
|
21
|
+
Gemini entries keep their `name` (`pmcp-<event>`), which is part of the
|
|
22
|
+
identity Gemini trusts.
|
|
23
|
+
|
|
24
|
+
The hook keeps two per-user caches under `$XDG_CACHE_HOME/pmcp` (default
|
|
25
|
+
`~/.cache/pmcp`), never in the project: Node's compile cache for the body
|
|
26
|
+
(`hook-compile/`) and the last integrity verdict per `policy.json`
|
|
27
|
+
(`hook-verified.json`). A verdict is reused only while neither `policy.json`
|
|
28
|
+
nor `pmcp.lock` has been written since. Either cache can be missing or
|
|
29
|
+
unwritable without changing a decision; `PMCP_HOOK_COMPILE_CACHE=off` turns the
|
|
30
|
+
compile cache off.
|
|
31
|
+
|
|
32
|
+
Every feature is opt-in: a table that is missing turns its feature off, and a
|
|
33
|
+
declared table, even an empty one, turns it on. The exceptions are documented
|
|
34
|
+
where they apply: `[git]` features detect git (`enabled = "auto"`),
|
|
35
|
+
`[git.shared_checkout]` is on in any git checkout once the bundle exists, and
|
|
36
|
+
logging falls back to its defaults rather than to no logging. The bundle is
|
|
37
|
+
projected only when `[hooks]` declares guards or checks, a `[sessions.*]`
|
|
38
|
+
feature table is declared, `[git.shared_checkout]` or `[git.worktrees.sync]` is
|
|
39
|
+
declared, or `[git.mainline.deliver]` keeps `refuse_direct_push`.
|
|
40
|
+
|
|
41
|
+
## `[hooks]`
|
|
42
|
+
|
|
43
|
+
| Key | Type | Default | Meaning |
|
|
44
|
+
| -------------------- | ------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
45
|
+
| `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. |
|
|
46
|
+
| `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. |
|
|
47
|
+
| `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. |
|
|
48
|
+
| `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. |
|
|
49
|
+
|
|
50
|
+
## `[hooks.guards.<group>.<name>]`
|
|
51
|
+
|
|
52
|
+
Each built-in guard is one table. `mode` is the only key the option-less
|
|
53
|
+
guards take; an unknown option is an error. Modes: `deny` and `ask` replace
|
|
54
|
+
the guard's verdict with that mode, `warn` turns the reason into context the
|
|
55
|
+
agent reads, `off` drops the guard, and `graded` keeps the guard's own split
|
|
56
|
+
between ask and deny.
|
|
57
|
+
|
|
58
|
+
| Table | Default mode | Modes | Refuses |
|
|
59
|
+
| ------------------------------------------ | ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `[hooks.guards.shell.in_place_edit]` | deny | deny, ask, warn, off | `sed -i`, `perl -i`, `awk -i inplace`: edits without a diff. |
|
|
61
|
+
| `[hooks.guards.shell.heredoc]` | deny | deny, ask, warn, off | Heredocs and here-strings, whose body the shell expands silently. |
|
|
62
|
+
| `[hooks.guards.shell.stdin_interpreter]` | ask | deny, ask, warn, off | An interpreter reading its program from stdin (`python3 -`, `cat x.py \| python3`). |
|
|
63
|
+
| `[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. |
|
|
64
|
+
| `[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. |
|
|
65
|
+
| `[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. |
|
|
66
|
+
| `[hooks.guards.git.push_without_verify]` | deny | deny, ask, warn, off | `git push --no-verify`. |
|
|
67
|
+
| `[hooks.guards.git.forced_branch_move]` | deny | deny, ask, warn, off | Forcing a branch that is checked out in another working tree. |
|
|
68
|
+
| `[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. |
|
|
69
|
+
| `[hooks.guards.git.stage_all]` | deny | deny, ask, warn, off | `git add -A`, `git add .`, `git commit -a` and similar; stage explicit paths. |
|
|
70
|
+
|
|
71
|
+
Options:
|
|
72
|
+
|
|
73
|
+
- `[hooks.guards.shell.secret_exfiltration]`: `extra_secret_paths` (list of
|
|
74
|
+
case-insensitive regular expressions, default `[]`), and
|
|
75
|
+
`[[hooks.guards.shell.secret_exfiltration.value_commands]]` entries for a
|
|
76
|
+
CLI that prints or publishes secret values: `binary` (required), `read`
|
|
77
|
+
(verbs that print a value, so reading asks) and `publish` (verbs that change
|
|
78
|
+
a live value, so they deny). Built in are `.env` files, `.dev.vars`, private
|
|
79
|
+
keys, `.npmrc`, `.netrc`, `auth.json` and service-account files; a file whose
|
|
80
|
+
name merely contains "secret" or "credential" is not one, so list such files
|
|
81
|
+
in `extra_secret_paths`. Only a file a command reads counts: a search
|
|
82
|
+
pattern, a sed or awk script, a jq filter or `-e` code that mentions `.env`
|
|
83
|
+
does not.
|
|
84
|
+
- `[hooks.guards.git.gate_bypass_env]`: `names` (variable names, default `[]`)
|
|
85
|
+
and `no_verify` (boolean, default `true`).
|
|
86
|
+
|
|
87
|
+
A mention is not a match: commands are parsed into steps, so
|
|
88
|
+
`git commit -m "never git push --no-verify"` and `echo 'cat <<EOF'` pass. A
|
|
89
|
+
command the parser cannot read is judged by a conservative pattern instead.
|
|
90
|
+
|
|
91
|
+
## `[[hooks.guards.custom]]`
|
|
92
|
+
|
|
93
|
+
A project script under `.agents/guards/` that decides like a built-in guard.
|
|
94
|
+
|
|
95
|
+
| Key | Type | Default | Meaning |
|
|
96
|
+
| ------------ | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
97
|
+
| `name` | string | required | `^[a-z0-9][a-z0-9-]*$`, unique across custom, shell and edit entries. |
|
|
98
|
+
| `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`. |
|
|
99
|
+
| `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. |
|
|
100
|
+
| `timeout_ms` | integer | `15000` | 100 to 60000. |
|
|
101
|
+
| `on` | string | `"before_shell"` | `before_shell` or `after_edit`. |
|
|
102
|
+
|
|
103
|
+
The script receives the JSON contract described under
|
|
104
|
+
[Deprecated shell guards](#deprecated-shell-guards). Custom guards have no `mode`.
|
|
105
|
+
|
|
106
|
+
## `[hooks.checks.after_edit]` and `[hooks.checks.on_stop]`
|
|
107
|
+
|
|
108
|
+
Checks report through context and never block; a check that cannot run is
|
|
109
|
+
logged and stays quiet.
|
|
110
|
+
|
|
111
|
+
| Table | Key | Type | Default | Meaning |
|
|
112
|
+
| --------------------------- | ------------------ | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
113
|
+
| `[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. |
|
|
114
|
+
| | `command` | argv list | required | Must contain `{validator}`, replaced by the validator's path. Runs directly, never through a shell. |
|
|
115
|
+
| | `debounce_seconds` | number | `60` | One run per validator per window. |
|
|
116
|
+
| | `report` | string | `"context"` | The only value. |
|
|
117
|
+
| `[hooks.checks.on_stop]` | `project_check` | boolean | `true` | After a turn that edited files, run `pmcp project --check` and report drift. |
|
|
118
|
+
| | `report` | string | `"context"` | The only value. |
|
|
119
|
+
|
|
120
|
+
The stop check runs the checkout's own pmcp (`node_modules`), else the CLI that
|
|
121
|
+
last projected this checkout on this machine (recorded in the state directory
|
|
122
|
+
as `projector.json`), and only at the version `pmcp.lock` records. A pmcp on
|
|
123
|
+
`PATH` is never used. When none matches, the session hears
|
|
124
|
+
`projecting pmcp not available` once instead of a drift report.
|
|
125
|
+
|
|
126
|
+
## Runtime support
|
|
127
|
+
|
|
128
|
+
From the measured capability files in `docs/hooks/capabilities/` (Claude Code
|
|
129
|
+
2.1.303, Codex 0.163.0, including live sessions). `pmcp doctor` prints the same
|
|
130
|
+
table for your project, with Codex trust.
|
|
131
|
+
|
|
132
|
+
| Feature | Claude Code | Codex |
|
|
133
|
+
| ---------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------- |
|
|
134
|
+
| sessions registry, pause, leases, broadcast | measured | measured |
|
|
135
|
+
| `[sessions.roles.<name>]` | works; not live-measured | unsupported: Codex sends no `agent_type` |
|
|
136
|
+
| `[git.shared_checkout]`, `[git.worktrees.sync]`, `[git.mainline.deliver]` | measured | measured |
|
|
137
|
+
| heredoc, compose_teardown, push_without_verify, forced_branch_move, gate_bypass_env, stage_all | measured | measured |
|
|
138
|
+
| in_place_edit, stdin_interpreter, secret_exfiltration (ask) | ask not measured | ask lowered by `ask_fallback` |
|
|
139
|
+
| host_approval | works; not live-measured | works; not live-measured |
|
|
140
|
+
| `[hooks.checks.after_edit]` | measured | measured |
|
|
141
|
+
| `[hooks.checks.on_stop]` | measured, in the same turn | at the next prompt |
|
|
142
|
+
| `[[hooks.guards.custom]]` | not measured | not measured |
|
|
143
|
+
| `[ui.claude]` | Claude only | not applicable |
|
|
144
|
+
|
|
145
|
+
Codex limits that shape the projection:
|
|
146
|
+
|
|
147
|
+
- Codex has no ask. An ask becomes `ask_fallback` (`deny` by default).
|
|
148
|
+
- Codex sends no `agent_type`, so roles cannot apply there.
|
|
149
|
+
- Codex rejects context on Stop, so Stop notices are delivered at the next
|
|
150
|
+
prompt.
|
|
151
|
+
- Codex clamps a SessionEnd hook to 3 s; pmcp projects at most 3 s for it.
|
|
152
|
+
- Codex has no Notification event.
|
|
153
|
+
- Codex's own command filter rejects a fully quoted executable before any hook
|
|
154
|
+
runs; use the ordinary unquoted form.
|
|
155
|
+
|
|
156
|
+
Gemini CLI 0.63.0, Antigravity (`agy`) 1.4.2, Grok 1.0.62 and OpenCode 1.18.33
|
|
157
|
+
are opt-in `[hooks] targets`. The pmcp bundle ran live on each in the same
|
|
158
|
+
thirteen scenarios as Claude Code and Codex, judged from each runtime's own
|
|
159
|
+
transcript; the `live` block of each capability file names the runs. A context
|
|
160
|
+
a runtime does not deliver at an event is held and delivered at the next event
|
|
161
|
+
that does, and that was measured live too. On OpenCode, prompt context goes
|
|
162
|
+
into the system prompt, which OpenCode does not store, so its delivery is shown
|
|
163
|
+
by a probe rather than by the prompt scenario. agy runs prompt policies on
|
|
164
|
+
every turn: its counter resets per turn.
|
|
165
|
+
|
|
166
|
+
| Feature | Gemini | Antigravity | Grok | OpenCode |
|
|
167
|
+
| ------------------------------------------- | ---------------------------- | ----------------------------- | ---------------------------- | ---------------------------- |
|
|
168
|
+
| refusing a tool call (guards, pause, git) | measured deny | measured deny | measured deny | measured (thrown error) |
|
|
169
|
+
| context (broadcast, warnings) | start, prompt, after tool | first model call, Stop | tool events, Stop | start, prompt, after tool |
|
|
170
|
+
| `[sessions.registry]` | every event | tool events, first call, Stop | every event | every event |
|
|
171
|
+
| `[sessions.roles.<name>]` | unsupported: no `agent_type` | unsupported: no `agent_type` | unsupported: no `agent_type` | unsupported: no `agent_type` |
|
|
172
|
+
| ask (in_place_edit, stdin_interpreter, ...) | lowered by `ask_fallback` | lowered by `ask_fallback` | lowered by `ask_fallback` | lowered by `ask_fallback` |
|
|
173
|
+
| `[hooks.checks.on_stop]` | at the next delivering event | Stop continues once | in the same turn | at the next prompt |
|
|
174
|
+
| `[[hooks.guards.custom]]` | not measured | not measured | not measured | not measured |
|
|
175
|
+
|
|
176
|
+
Where each runtime's projection goes, and what it needs:
|
|
177
|
+
|
|
178
|
+
- Gemini: `.gemini/settings.json` `hooks`, timeouts in milliseconds. Gemini
|
|
179
|
+
ignores project settings in a folder the user has not trusted, and records
|
|
180
|
+
each new hook in `~/.gemini/trusted_hooks.json`; `pmcp doctor` reads both
|
|
181
|
+
and reports them, and never writes them. Trusting the folder is the user's
|
|
182
|
+
step in an interactive `gemini` session.
|
|
183
|
+
- Antigravity: one named set `pmcp` in `.agents/hooks.json`, beside the shell
|
|
184
|
+
adapter's `pmcp-shell`. agy denies a tool call whose hook names no decision,
|
|
185
|
+
so pmcp always writes one. agy has no session or prompt event: the first
|
|
186
|
+
model call of a conversation is the session start, the first of a later
|
|
187
|
+
turn the prompt. Whether that counter resets for a later prompt in an
|
|
188
|
+
interactive session is not measured. No trust step.
|
|
189
|
+
- Grok: grok also runs `.claude/settings.json` hooks, so with `claude` in
|
|
190
|
+
`[hooks] targets` pmcp writes only the Claude file and the hook recognises a
|
|
191
|
+
grok call by its payload; with Grok alone it writes `.grok/hooks/pmcp.json`.
|
|
192
|
+
Never both, or every check would run twice. Project hooks run only after
|
|
193
|
+
the user runs `/hooks-trust`; `pmcp doctor` reads
|
|
194
|
+
`~/.grok/trusted_folders.toml` without writing it.
|
|
195
|
+
- OpenCode: there are no shell hooks, so pmcp writes `.opencode/plugins/pmcp.js`,
|
|
196
|
+
a small plugin pinned in `pmcp.lock` that passes each call to the hook. A
|
|
197
|
+
refusal is thrown as an error; Stop (`session.idle`) only updates the
|
|
198
|
+
registry. No trust step.
|
|
199
|
+
|
|
200
|
+
`auth = "pmcp"` MCP servers project through `pmcp project exec-mcp` for every
|
|
201
|
+
runtime above.
|
|
202
|
+
|
|
203
|
+
## Deprecated shell guards
|
|
204
|
+
|
|
205
|
+
Deprecated: `[[hooks.shell]]` and `[[hooks.edit]]` still work, and `pmcp project`
|
|
206
|
+
warns. Declare `[[hooks.guards.custom]]` instead, with `on = "before_shell"` or
|
|
207
|
+
`on = "after_edit"`, and list its runtimes in `[hooks] targets`: every runtime
|
|
208
|
+
now has a hook bundle adapter, and this separate shell adapter will be removed
|
|
209
|
+
in a later major release.
|
|
210
|
+
|
|
211
|
+
Declare a project-owned guard explicitly to project it into Codex, Gemini or
|
|
212
|
+
Antigravity's native hooks. Without a declaration, pmcp generates no hooks.
|
|
213
|
+
|
|
214
|
+
```toml
|
|
215
|
+
[[hooks.shell]]
|
|
216
|
+
name = "shell-command-policy"
|
|
217
|
+
command = ["node", ".agents/guards/shell-command-policy.mjs"]
|
|
218
|
+
targets = ["codex", "gemini", "antigravity"]
|
|
219
|
+
timeout_ms = 15000
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
The guard script must exist under .agents/guards/ and cannot resolve outside
|
|
223
|
+
that directory. It receives one JSON object on stdin containing runtime,
|
|
224
|
+
event=before_shell, command and cwd. It returns a JSON object with
|
|
225
|
+
decision=allow or decision=deny and an optional reason. Malformed responses,
|
|
226
|
+
nonzero exits and timeouts deny the shell call. The guard receives PATH and
|
|
227
|
+
LANG rather than the native CLI's credential environment. Non-shell tools are
|
|
228
|
+
outside this contract.
|
|
229
|
+
|
|
230
|
+
Run pmcp project to write lock-owned adapter and policy artifacts under
|
|
231
|
+
.agents/pmcp-hooks/, plus the native entries in .codex/hooks.json,
|
|
232
|
+
.gemini/settings.json and .agents/hooks.json. Peer entries are retained.
|
|
233
|
+
Edited owned hook entries refuse projection for review. Removing a declaration
|
|
234
|
+
removes its generated entries and artifacts while preserving peer settings.
|
|
235
|
+
Writes retain private backups; pmcp project --check only reports drift.
|
|
236
|
+
|
|
237
|
+
Guard, policy and adapter fingerprints bind the generated command. Changing
|
|
238
|
+
guard code requires reprojection and native Codex hook review. Generated files
|
|
239
|
+
contain no trust bypass. Grok can load Claude project hooks, so this first scope
|
|
240
|
+
does not generate a second Grok guard. Hooks do not force pmcp catalog use,
|
|
241
|
+
inject reminders or replace the runtime's execution sandbox.
|
|
242
|
+
|
|
243
|
+
## Deprecated edit guards
|
|
244
|
+
|
|
245
|
+
Codex edit guards run after apply_patch through native PostToolUse hooks:
|
|
246
|
+
|
|
247
|
+
```toml
|
|
248
|
+
[[hooks.edit]]
|
|
249
|
+
name = "edit-policy"
|
|
250
|
+
command = ["node", ".agents/guards/edit-policy.mjs"]
|
|
251
|
+
targets = ["codex"]
|
|
252
|
+
timeout_ms = 15000
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
The guard receives runtime=codex, event=after_edit, the patch in command and cwd.
|
|
256
|
+
It returns the same allow/deny response as a shell guard. A denial becomes
|
|
257
|
+
native blocking feedback with the reason; the completed file edit remains on disk
|
|
258
|
+
for correction. Other tools do not invoke this guard. Edit targets currently
|
|
259
|
+
support Codex only, and names must be unique across shell and edit declarations.
|
|
260
|
+
|
|
261
|
+
Run pmcp project after declaring or changing the guard, then review and trust
|
|
262
|
+
the generated native definition in /hooks. Peer entries and shell guards are
|
|
263
|
+
preserved. Fingerprints and failure handling follow the shell-guard contract.
|
|
264
|
+
See the [native hooks documentation](https://learn.chatgpt.com/docs/hooks).
|