@maind-dev/mcp-bridge 0.104.0 → 0.106.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.
package/README.md CHANGED
@@ -171,15 +171,15 @@ names it:
171
171
  | Client | Channel | Where |
172
172
  |---|---|---|
173
173
  | Claude Code | hooks: session briefing with the full convention set, prompt and read context (see below); no `CLAUDE.md` block | `~/.claude/settings.json` — or the Claude Code plugin `maind` (`maind@maind`): with the plugin enabled, `install` writes no hooks there and no server into `~/.claude.json` |
174
- | Codex | `SessionStart` hook, its output as `additionalContext` | `config.toml` in Codex's home (`~/.codex/`, or `$CODEX_HOME`) |
174
+ | Codex | hooks, one entry per event: session briefing, prompt context, edit guards, turn end (see "Codex and GitHub Copilot") | `config.toml` in Codex's home (`~/.codex/`, or `$CODEX_HOME`) |
175
175
  | Devin Desktop | Claude Code's hooks (it loads `~/.claude/settings.json`) | — no own entry |
176
176
  | Cursor | `sessionStart` hook (a race Cursor confirms can drop its context — see "The team option") | `~/.cursor/hooks.json` |
177
- | GitHub Copilot (VS Code) | user instructions, `applyTo: "**"` | `~/.copilot/instructions/maind.instructions.md` |
177
+ | GitHub Copilot (VS Code, Copilot CLI) | hooks, one entry per event (see "Codex and GitHub Copilot"); user instructions, `applyTo: "**"` | `~/.copilot/hooks/maind.json`; `~/.copilot/instructions/maind.instructions.md` |
178
178
  | Cline | global rule (always active without frontmatter) | `<Documents>/Cline/Rules/maind.md` |
179
179
  | Continue | global rule, `alwaysApply: true` | `~/.continue/rules/maind.md` (or `$CONTINUE_GLOBAL_DIR/rules/`) |
180
180
  | Claude Desktop | the MCP `instructions` only | — |
181
181
 
182
- `--no-hook` leaves out every hook (Claude Code's, Cursor's, Codex's),
182
+ `--no-hook` leaves out every hook (Claude Code's, Cursor's, Codex's, Copilot's),
183
183
  `--no-rules` every rule file. `--no-preamble` is accepted for old scripts and
184
184
  does nothing. `install --hooks-only` sets up the channels an existing install is
185
185
  missing. Blocks an earlier install wrote into a repository stay effective until
@@ -369,7 +369,8 @@ prints what that host can take:
369
369
  | Claude Code (or a host we cannot identify) | Exactly what it got before — plain text at session start, `hookSpecificOutput` JSON elsewhere |
370
370
  | Cursor | One JSON object in Cursor's own shape, or nothing — never plain text. A refused `Write` is `permission: "deny"` with the reason for you and the agent; session-start text and context stay out (Cursor's own `sessionStart` hook — see above — carries the briefing there, and with the team option `AGENTS.md`) |
371
371
  | Devin Local | Claude Code's JSON where Devin documents it: `additionalContext` at `SessionStart`, `UserPromptSubmit` and `PostToolUse`, `decision: "block"` for a refusal. Nothing at `PreToolUse`, never plain text |
372
- | Codex (since 0.100.0) | Runs `on-session-briefing --host=codex` from its own `config.toml`; gets `{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": …}}` — never plain text, which Codex parses as JSON when it starts with `[`. Recognised by the `--host=codex` the installer writes, else by a Codex rollout transcript (`…/sessions/YYYY/MM/DD/rollout-….jsonl`) |
372
+ | Codex (since 0.100.0; every core hook since 0.105.0) | Runs `on-hook --host=codex …` from its own `config.toml`; gets exactly Claude Code's JSON shapes — `hookSpecificOutput.additionalContext`, the PreToolUse deny — and nothing more, because Codex rejects an output with an unknown field. Session-start text as JSON too: Codex parses plain text that starts with `[` as JSON. Recognised by the `--host=codex` the installer writes, else by a Codex rollout transcript (`…/sessions/YYYY/MM/DD/rollout-….jsonl`) |
373
+ | GitHub Copilot (since 0.105.0) | Runs `on-hook --host=copilot …` from `~/.copilot/hooks/maind.json`, in VS Code's agent and in the Copilot CLI. Every answer carries its context twice — in `hookSpecificOutput` (VS Code reads only that) and as a top-level `additionalContext` (the Copilot CLI reads that for SessionStart, prompts and PostToolUse) — so each reads it once. Recognised by `--host=copilot`, else by VS Code's transcript path (`…/GitHub.copilot-chat/transcripts/…`), `COPILOT_PROJECT_DIR`, or an ISO `timestamp` with `hook_event_name` |
373
374
 
374
375
  Whether the context reaches the model in Devin Local is **not measured**. To
375
376
  keep every hook silent there, set `MAIND_DEVIN_HOOK_OUTPUT=off`, or
@@ -387,35 +388,97 @@ own on that file stays as it is and is named with its replacement. `doctor`
387
388
  reports an old `cat` (`hook-hosts`, a warning when Cursor is installed), and
388
389
  the session-start line names the command while Cursor is installed.
389
390
 
390
- ## Codex: conventions at session start
391
+ ## Codex and GitHub Copilot: the core hooks (since 0.105.0)
391
392
 
392
- Codex has hooks (learn.chatgpt.com/docs/hooks). Since **0.100.0** `install`
393
- adds, where Codex is installed (or with `--client codex`):
393
+ Codex (learn.chatgpt.com/docs/hooks) and GitHub Copilot — VS Code's agent and
394
+ the Copilot CLI, which both read `~/.copilot/hooks/*.json` — run hook commands
395
+ on the events Claude Code has, with Claude Code's snake_case payload. So
396
+ `install` gives them the core hooks, where Codex or Copilot is installed (or
397
+ with `--client codex` / `--client copilot`): **one entry per event**, carrying
398
+ the hooks you agreed to — consent is still asked per hook.
394
399
 
395
400
  ```toml
401
+ # ~/.codex/config.toml (an excerpt)
396
402
  [features]
397
403
  hooks = true
398
404
 
399
405
  [[hooks.SessionStart]]
400
406
  [[hooks.SessionStart.hooks]]
401
407
  type = "command"
402
- command = "<bridge> on-session-briefing --host=codex"
403
- timeout = 10
408
+ command = "<bridge> on-hook --host=codex on-session-reminder on-session-start on-session-briefing"
409
+ timeout = 20
404
410
  additionalContextLimit = 4000
411
+
412
+ [[hooks.PostToolUse]]
413
+ matcher = "apply_patch"
414
+ [[hooks.PostToolUse.hooks]]
415
+ type = "command"
416
+ command = "<bridge> on-hook --host=codex on-write-health"
417
+ timeout = 10
418
+ ```
419
+
420
+ ```json
421
+ // ~/.copilot/hooks/maind.json (an excerpt)
422
+ {
423
+ "version": 1,
424
+ "hooks": {
425
+ "PreToolUse": [
426
+ { "type": "command", "command": "<bridge> on-hook --host=copilot on-tool-use on-file-write on-file-edit on-repo-health on-read-context || true", "timeout": 30 }
427
+ ]
428
+ }
429
+ }
405
430
  ```
406
431
 
407
- - **What.** The same block the Claude Code session-start hook prints —
408
- `[maind] Session briefing …`, project conventions first —, as
409
- `hookSpecificOutput.additionalContext`. `additionalContextLimit` lifts Codex's
410
- default (~2,500 tokens; above it Codex replaces the text by a file and a
411
- preview) for this one handler.
432
+ - **One entry per event, not per hook.** VS Code's agent ignores matchers and
433
+ runs an event's commands one after another; six bridge processes before and
434
+ after every tool call would cost a third of a second per call. Codex asks
435
+ you to trust each new entry once (`/hooks`). `on-hook` reads the payload
436
+ once and runs the named hooks in one process; a hook that fails costs only
437
+ its own answer.
438
+ - **Matchers** only where every hook of the entry is about files: Codex
439
+ `apply_patch` (its exact tool name; `Edit` and `Write` are aliases), Copilot
440
+ `Edit|Write` / `Read` in the Copilot CLI's Claude names. VS Code ignores
441
+ them — every file hook reads the call itself.
442
+ - **File acts in each host's vocabulary.** Codex edits through `apply_patch`
443
+ with the patch text in `tool_input.command`; the hooks read only its
444
+ file-header lines (`*** Add File:` is a new file, `*** Update File:` an
445
+ edit). VS Code: `create_file`, `replace_string_in_file`,
446
+ `multi_replace_string_in_file`, `insert_edit_into_file`, `apply_patch`,
447
+ `read_file` with `filePath`. The Copilot CLI: Claude's names with `path`.
448
+ - **Fail-open.** Every Copilot command ends in `|| true` (PowerShell:
449
+ `; exit 0`): in the Copilot CLI a PreToolUse command that exits non-zero
450
+ denies the tool call, and a moved bridge must not do that.
412
451
  - **Trust.** Codex runs a new hook only after you trust it: open `/hooks` in
413
- Codex once. The report row says so.
414
- - **Append-only.** Every other key, table and hook stays; `[features] hooks =
415
- false` (or the old `codex_hooks = false`) is your "no" and is reported, never
416
- flipped. The file goes through the same parse/stringify as the MCP entry —
417
- keys and values stay, comments do not. A handler already there, in
418
- `config.toml` or `hooks.json`, counts as wired.
452
+ Codex once. VS Code needs `chat.useHooks` (on by default; an organisation
453
+ can turn it off with the `ChatHooks` policy); the Copilot CLI reads the file
454
+ at its next start.
455
+ - **Append-only, idempotent per hook.** Every other key, table and hook stays
456
+ — in `config.toml` byte for byte (comments and layout included), in
457
+ `maind.json` every entry that is not ours. A hook whose subcommand a command
458
+ of its event already carries — in `config.toml` or `hooks.json`, in any file
459
+ in `~/.copilot/hooks` — counts as wired; the `on-session-briefing
460
+ --host=codex` entry of 0.100–0.104 included, so an upgrade adds the rest
461
+ beside it. `[features] hooks = false` is your "no" and is reported, never
462
+ flipped.
463
+ - **Once, not twice.** VS Code runs Claude Code's hooks from
464
+ `~/.claude/settings.json` too when you turn on `chat.useClaudeHooks` (off by
465
+ default). A hook that finds itself there, without `--host=copilot`, stands
466
+ down for every hook `maind.json` already runs.
467
+
468
+ What does not exist there is not wired — the report names it as a `gap(…)`
469
+ row, and `doctor` lists it:
470
+
471
+ | Hook | Codex | Copilot |
472
+ |---|---|---|
473
+ | `on-read-context` | **not wired** — Codex has no file-read tool; it reads through the shell (`Bash`) | VS Code `read_file`, the CLI `view` |
474
+ | `on-prompt-context` | yes | VS Code yes; the Copilot CLI documents command-hook output on a prompt as dropped |
475
+ | `on-file-write`, `on-file-edit`, `on-repo-health`, `on-write-health` | edits through `apply_patch`; a file a shell command writes passes no file hook | yes |
476
+ | `on-tool-use` | counts calls; the token advisory reads Claude Code transcripts only | the same |
477
+ | `on-session-end` | closes the turn's counters, sends the Tier-3 metrics; analytics and cost slices come from `maind sessions backfill`, not from the hook | closes the counters, sends the metrics; Copilot's transcripts are not analysed |
478
+ | The guard pack | stands down outside Claude Code | the same |
479
+
480
+ `doctor --remove-phantoms` takes out of `config.toml` exactly what `install`
481
+ put in — every maind handler, of any event, and a marked `[features] hooks`.
419
482
 
420
483
  ## User-level rule files: Copilot, Cline, Continue
421
484
 
@@ -483,8 +546,9 @@ SessionStart hook names the migration once per repository.
483
546
  - `doctor --migrate-repo-blocks` lists the blocks and the user-level channels
484
547
  that carry the same content, and changes nothing.
485
548
  - `doctor --migrate-repo-blocks --yes` sets those channels up first (Claude
486
- Code's reminder and briefing hooks unless the plugin carries them, Cursor's
487
- and Codex's hooks, the rule files — for the clients installed here) and stops
549
+ Code's reminder and briefing hooks unless the plugin carries them, Cursor's,
550
+ Codex's and Copilot's hooks, the rule files — for the clients installed
551
+ here) and stops
488
552
  without removing anything if one fails; then it removes exactly the listed
489
553
  blocks. Only lines between maind markers go (and the blank line the installer
490
554
  put before them); every other byte stays, with its own line endings. A file