@getmarrow/mcp 3.9.74 → 3.9.76

package/README.md

@@ -104,7 +104,15 @@ npx -y --package=@getmarrow/mcp@latest marrow-mcp ping
 
 Detection and notification are automatic. After explicit installer activation, the local controller may restore only Marrow-managed hooks/configuration. Package upgrades, owner policy, credentials, and unrelated configuration remain explicit and subject to the operator's normal change policy.
 
-## What's New in v3.9.74
+## What's New in v3.9.76
+
+v3.9.76 fixes owner-approved `marrow_auto` closeout by binding an arbitrated operation to the exact server-created arbitration decision, rejecting decision mismatches before commit, and returning an honest terminal action for non-arbitrated `review_required` gates. Chat and proof text cannot substitute for a dashboard-issued approval receipt, and only a backend `committed: true` response closes the operation.
+
+## Previous: v3.9.75
+
+v3.9.75 adds explicit Codex, Cursor/Composer, Cline, Windsurf, and Gemini CLI native hook entrypoints. Gemini BeforeTool returns strict fixed allow/deny JSON, AfterTool returns neutral JSON after compact outcome capture, and AfterAgent closes one turn without reading prompt/response content or requesting a retry. Project hook trust and enablement remain user-controlled, and configuration stays client-self-reported rather than certified coverage.
+
+## Previous: v3.9.74
 
 v3.9.74 keeps one automatic operation bound to its original runtime authorization and decision across timeout and proof-required retries, then closes that exact decision once verified proof is supplied. One outer `marrow_auto` invocation normally completes think and commit in-band within its bounded eight-second client budget. The release canary allows that complete client budget plus bounded response overhead rather than cutting the operation off at five seconds.
 
@@ -119,7 +127,7 @@ v3.9.71 makes the advertised Grok control loop true:
 - default tools include `marrow_think` so the official loop can create a `decision_id` without `MARROW_TOOL_PROFILE=full`;
 - process identity prefers `MARROW_KEY_<ROLE>` when it matches `MARROW_AGENT_ID`, so a leaked fleet env cannot 403 every status call;
 - Grok native hooks are installed under `~/.grok/hooks/marrow.json` and hook parsers accept Grok camelCase envelopes;
-- Grok hooks are advisory telemetry/context only. Consequential execution requires `npx @getmarrow/install run --agent <agent-id> -- -- <command>`;
+- Grok native PreToolUse, PostToolUse/PostToolUseFailure, and nonblocking Stop hooks provide bounded client-reported gating, result evidence, and one turn closeout. The governed wrapper remains an explicit bounded fallback;
 - idle spool nudge drains up to 40 current-namespace events so the queue does not sit as a nag;
 - if `risk_gate.enforced` is false, the gate is advisory — do not describe it as a live block;
 - `marrow_commit.decision_id` comes from `marrow_think`, `marrow_auto`, or an arbitration runtime that actually created a decision. A normal runtime authorization is a gate receipt, not a decision.
@@ -189,7 +197,7 @@ v3.9.62 integrates four model-neutral reliability and capability contracts:
 - `spool-status` and `drain-spool` report the active credential namespace separately from isolated legacy debt, and a clear active namespace exits successfully without replaying, merging, editing, or deleting old-key files;
 - initialize, prompt, setup, and tool responses qualify coverage by `host_capability`: MCP tools are on demand, while client-self-reported hook activity remains visible but never certifies coverage or control.
 
-The default surface is seven tools (runtime, think, commit, ask, status, auto, handoff status) and the prompt remains named `marrow-always-on`. Host and model labels are display-only and never change auth, tenant, plan, policy, proof, schema, or API behavior. Grok hook activity is advisory and client-self-reported; the governed wrapper is the consequential-action boundary.
+The default surface is seven tools (runtime, think, commit, ask, status, auto, handoff status) and the prompt remains named `marrow-always-on`. Host and model labels are display-only and never change auth, tenant, plan, policy, proof, schema, or API behavior. Grok hook activity is client-self-reported and does not certify observed coverage; the governed wrapper remains an explicit bounded fallback.
 
 ## Previous: v3.9.61
 
@@ -212,7 +220,7 @@ v3.9.60 restores the complete control-and-proof loop for ordinary MCP clients:
 - a plan-gated handoff is reported as unavailable for the current plan, not as an API or authentication outage;
 - the release canary runs with the customer's default client deadlines instead of silently overriding them.
 
-The current package gives MCP-only hosts the same model-neutral control instructions and seven-tool default surface, but MCP transport alone remains on demand. A host or model label never changes that coverage contract. Public lifecycle callbacks and hook activity are client-self-reported and cannot verify or certify passive coverage; independent authority is required. Codex, Grok, Gemini, and similar CLI harnesses must use `npx @getmarrow/install run --agent <agent-id> -- -- <command>` for consequential commands.
+The current package gives MCP-only hosts the same model-neutral control instructions and seven-tool default surface, but MCP transport alone remains on demand. A host or model label never changes that coverage contract. Public lifecycle callbacks and hook activity are client-self-reported and cannot verify or certify passive coverage; independent authority is required. Codex, Grok, and Gemini can use configured native hooks after restart and host hook review; the governed wrapper remains an explicit bounded fallback.
 
 ## Previous: v3.9.59
 
@@ -344,12 +352,12 @@ Configured hooks can provide cooperative telemetry and context, but they are not
 1. Call `marrow_agent_runtime` or `marrow_decision_brief`.
 2. Stop when the returned decision is `block` or `review_required`; otherwise follow its prior lesson and proof contract.
 3. Call `marrow_think` or `marrow_auto` to record intent and obtain the `decision_id` that will be closed. Keep `marrow_agent_runtime.runtime_authorization.id` separate as the gate receipt for consequential work.
-4. Perform the action only when its gate allows it. For Codex, Grok, Gemini, and similar CLI harnesses, use the governed wrapper: `npx @getmarrow/install run --agent <agent-id> -- -- <command>`.
+4. Perform the action only when its gate allows it. Codex, Grok, and Gemini use configured native hooks only after restart and host hook review. The governed wrapper remains an explicit bounded fallback: `npx @getmarrow/install run --agent <agent-id> -- -- <command>`.
 5. Call `marrow_commit` with that `decision_id`, the outcome, gate receipt, and required proof.
 
 `marrow_agent_runtime` returns `runtime_authorization` with the authoritative gate receipt. Ordinary runtime checks do not create a decision, so they omit `decision_id`; call `marrow_think` (or use `marrow_auto`) when a decision must be created and closed. An arbitration runtime that actually creates a decision returns that server-created `decision_id`. This contract is identical across MCP-compatible hosts and SDK-owned runtimes.
 
-`marrow_auto` returns an `operation_id`, phase, and resumable state. If a client deadline is reached before closure, retry with the same `operation_id`; Marrow reuses the same tenant-scoped runtime authorization, think decision, and commit idempotency keys instead of opening another decision. When the phase is `proof_required`, add the requested proof and retry with that same operation ID and unchanged action/context/surfaces. Proof is validated and bound at commit; changing the tenant or action scope is rejected. A closed response reports `phase: "closed"`, `committed: true`, and `resumable: false`.
+`marrow_auto` returns an `operation_id`, phase, and resumable state. If a client deadline is reached before closure, retry with the same `operation_id`; Marrow reuses the same tenant-scoped runtime authorization, decision, and commit idempotency keys instead of opening another decision. When the phase is `proof_required`, add the requested proof and retry with that same operation ID and unchanged action/context/surfaces. An arbitrated runtime binds the operation directly to the arbitration response's server-created `decision_id`; `marrow_auto` does not open a separate decision. When an arbitrated result returns `owner_approval_required`, do not retry proof: approve that exact arbitration decision in an authenticated Marrow dashboard, then call `marrow_auto` once with the same operation ID, `arbitration_receipt_id`, and server-issued `owner_approval_receipt_id`. A non-arbitrated `review_required` result is terminal for that operation because the backend cannot issue a compatible dashboard receipt; start a new supported `marrow_arbitrate` review instead. Chat or proof text is never an approval receipt. Proof and receipts are validated and bound at commit; changing the tenant or action scope is rejected. A closed response reports `phase: "closed"`, `committed: true`, and `resumable: false`.
 
 Example pre-action request:
 
@@ -463,7 +471,7 @@ When invoked by a supported host, the configured hooks send compact classificati
 
 Setup installs distinct Claude Code and Grok hook entrypoints. The public entrypoint supplies only a client-reported display label; it is not host provenance. Hook event JSON cannot select the lifecycle harness or agent. Agent identity comes only from owner configuration when present, otherwise the request omits it so the authenticated service can derive the credential-bound identity. Every hook lifecycle event is marked `source: client_self_reported` and omits `capability_level: native_hooks`, adapter certification, configuration fingerprints, expected hooks, and observed-hook certification fields. Legacy, unknown, and custom entrypoints stay generic.
 
-Claude Code hooks may cooperatively request guidance and apply the harness permission response, but that does not certify always-on control. Grok hooks are advisory telemetry/context only: `grok-pre-action-hook` never issues, verifies, or consumes an action permit and never claims enforcement. Codex, Grok, Gemini, and similar CLI harnesses must run consequential commands through `npx @getmarrow/install run --agent <agent-id> -- -- <command>`. Unknown and custom hosts remain on demand unless they provide a bounded event adapter, whose activity is still not certification without an independent authority.
+Claude Code hooks may cooperatively request guidance and apply the harness permission response, but that does not certify always-on control. Codex native hooks map both block and review-required gates to the supported synchronous deny response. Cursor and Composer use the same Cursor-native pre-action, result, failure, and stop adapters. Cline uses native pre-action and post-tool adapters plus TaskCancel closeout; its documented TaskComplete hook remains coming soon and is not claimed as observed coverage. Windsurf uses native pre-action, success-result, and response-closeout adapters and requires Restricted Mode to be off. Gemini CLI uses native BeforeTool, AfterTool, and AfterAgent adapters; AfterAgent is the deterministic per-turn closeout and no SessionEnd delivery is claimed. Grok uses global native PreToolUse, PostToolUse/PostToolUseFailure, and one nonblocking Stop closeout; Marrow's generated Grok file contains no duplicate SessionEnd closeout. These native paths keep MCP on demand and require restart plus host hook review. Cursor, Cline, Windsurf, Gemini, and Grok deny protected review-required or unavailable-control work when their native contracts cannot make a generic ask enforceable. All activity remains client-self-reported rather than verified host telemetry, and the governed wrapper remains an explicit bounded fallback. Unknown and custom hosts remain on demand unless they provide a bounded event adapter, whose activity is still not certification without an independent authority.
 
 Transient lifecycle receipts use a bounded owner-only spool and are retried with stable event IDs. Operators can inspect and drain it without exposing event content:
 

package/dist/cli.js

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("./index");
+const control_state_1 = require("./control-state");
 const hook_1 = require("./hook");
 const hook_contract_1 = require("./hook-contract");
 const hook_context_1 = require("./hook-context");
@@ -40,16 +41,16 @@ function parseArgs() {
         if (args[i] === 'setup' || args[i] === '--setup') {
             result.setup = true;
         }
-        if (['hook', '--hook', 'claude-hook', 'grok-hook'].includes(args[i])) {
+        if (['hook', '--hook', 'claude-hook', 'cline-hook', 'codex-hook', 'cursor-hook', 'gemini-hook', 'grok-hook', 'windsurf-hook'].includes(args[i])) {
             result.hook = true;
         }
-        if (['context-hook', '--context-hook', 'claude-context-hook', 'grok-context-hook'].includes(args[i])) {
+        if (['context-hook', '--context-hook', 'claude-context-hook', 'codex-context-hook', 'grok-context-hook'].includes(args[i])) {
             result.contextHook = true;
         }
-        if (['pre-action-hook', '--pre-action-hook', 'claude-pre-action-hook', 'grok-pre-action-hook'].includes(args[i])) {
+        if (['pre-action-hook', '--pre-action-hook', 'claude-pre-action-hook', 'cline-pre-action-hook', 'codex-pre-action-hook', 'cursor-pre-action-hook', 'gemini-pre-action-hook', 'grok-pre-action-hook', 'windsurf-pre-action-hook'].includes(args[i])) {
             result.preActionHook = true;
         }
-        if (['session-hook', '--session-hook', 'claude-session-hook', 'grok-session-hook'].includes(args[i])) {
+        if (['session-hook', '--session-hook', 'claude-session-hook', 'cline-session-hook', 'codex-session-hook', 'cursor-session-hook', 'gemini-session-hook', 'grok-session-hook', 'windsurf-session-hook'].includes(args[i])) {
             result.sessionHook = true;
         }
         if (args[i] === 'spool-status' || args[i] === '--spool-status') {
@@ -172,7 +173,7 @@ Use Marrow according to the capability evidence returned by the MCP server:
 
 Do not skip the gate or outcome. Marrow's value comes from controlling the action before execution and preserving evidence afterward.
 
-Capability boundaries: configured native hooks provide cooperative telemetry or context only; \`createPassiveRuntime().install()\` covers only its owned Node process while installed; a governed wrapper covers only its wrapped command; and a custom host needs a bounded event adapter. A model name, host label, API key, public hook entrypoint, installed configuration, or client-self-reported callback is not proof of coverage or enforcement. For Codex, Grok, Gemini, and similar CLI harnesses, run consequential commands through \`npx @getmarrow/install run --agent <agent-id> -- -- <command>\`.
+Capability boundaries: configured native hooks provide cooperative client-reported control and lifecycle evidence only; \`createPassiveRuntime().install()\` covers only its owned Node process while installed; a governed wrapper covers only its wrapped command; and a custom host needs a bounded event adapter. A model name, host label, API key, public hook entrypoint, installed configuration, or client-self-reported callback is not proof of coverage or enforcement. Codex, Grok, and Gemini use configured native hooks only after restart and the host's hook review; the governed wrapper remains an explicit bounded fallback.
 
 For bounded outcome capture: \`marrow_auto({ action: "did X", outcome: "result Y", success: true })\`. One outer invocation normally completes think and commit in-band within its bounded client budget. If the host or network deadline is reached, retry with the returned \`operation_id\`; Marrow continues the same operation and never opens a second decision.
 ${MARROW_BLOCK_END}`;
@@ -245,10 +246,10 @@ ${MARROW_BLOCK_END}`;
     }
     const grokHookInstall = (0, hook_contract_1.installGrokNativeHooks)();
     if (grokHookInstall.installed) {
-        process.stdout.write(`Configured Grok advisory hooks at ${grokHookInstall.settingsPath}. Their activity is client-self-reported and never certifies coverage or enforcement; consequential commands require npx @getmarrow/install run --agent <agent-id> -- -- <command>.\n`);
+        process.stdout.write(`Configured Grok native pre-action, result, and nonblocking turn-closeout hooks at ${grokHookInstall.settingsPath}. Restart Grok and inspect /hooks before relying on them. Activity remains client-self-reported and does not certify observed coverage.\n`);
     }
     else {
-        process.stdout.write(`Grok advisory hook configuration is present at ${grokHookInstall.settingsPath}. Its activity is client-self-reported and never certifies coverage or enforcement; consequential commands require npx @getmarrow/install run --agent <agent-id> -- -- <command>.\n`);
+        process.stdout.write(`Grok native hook configuration is present at ${grokHookInstall.settingsPath}. Restart Grok and inspect /hooks before relying on it. Activity remains client-self-reported and does not certify observed coverage.\n`);
     }
     process.stdout.write(`Hook settings: ${hookInstall.settingsPath}\n`);
     process.stdout.write('Set MARROW_AUTO_HOOK=false to disable passive hooks.\n');
@@ -534,6 +535,7 @@ if (process.argv[2] !== 'keys') {
                         : null)
                     || (0, request_reliability_1.localClientUpdate)(),
                 control_path: (0, control_path_state_1.controlPathStats)(toolName),
+                local_control: (0, control_state_1.localControlEvidence)(Boolean(API_KEY)),
                 lifecycle_spool: {
                     state: spool.failed > 0 || spool.pending > 0 ? spool.state : 'clear',
                     pending: spool.pending,
@@ -936,6 +938,8 @@ if (process.argv[2] !== 'keys') {
                         },
                         proof: { type: 'object', description: 'Measured completion evidence for gated work.' },
                         gate_receipt_id: { type: 'string', description: 'Fresh receipt returned by marrow_agent_runtime.' },
+                        arbitration_receipt_id: { type: 'string', description: 'For arbitrated work, the arbitration receipt returned by the same server-side review flow.' },
+                        owner_approval_receipt_id: { type: 'string', description: 'Short-lived, single-use receipt issued by authenticated dashboard owner approval. Chat text is not an approval receipt.' },
                         operation_id: {
                             type: 'string',
                             description: 'Opaque 8-80 character resume token. Reuse it only with the original tenant, action, context, and surfaces; proof may be added after proof_required.',
@@ -1809,7 +1813,7 @@ Configured native hooks can cooperatively report or inject context for these bou
 - PostToolUse can record compact tool success or failure receipts.
 - Stop can keep unfinished outcomes visible instead of silently treating session exit as success.
 
-Hooks never make a blocked action safe and are not an external execution choke point. Before a consequential action, respect the returned allow, warn, review_required, or block decision and its required proof. For Codex, Grok, Gemini, and similar CLI harnesses, use npx @getmarrow/install run --agent <agent-id> -- -- <command>.
+Hooks never make a blocked action safe and are not an external execution choke point. Before a consequential action, respect the returned allow, warn, review_required, or block decision and its required proof. Codex, Grok, and Gemini use configured native hooks only after restart and host hook review; the governed wrapper remains an explicit bounded fallback.
 
 When runtime/status returns a client_update notice, tell the operator and use its exact update and verification commands only when local change policy permits. Never silently change packages or configuration.
 
@@ -2016,6 +2020,12 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         const suppliedRuntimeReceiptId = typeof args.gate_receipt_id === 'string'
                             ? args.gate_receipt_id
                             : undefined;
+                        const suppliedArbitrationReceiptId = typeof args.arbitration_receipt_id === 'string'
+                            ? args.arbitration_receipt_id
+                            : undefined;
+                        const suppliedOwnerApprovalReceiptId = typeof args.owner_approval_receipt_id === 'string'
+                            ? args.owner_approval_receipt_id
+                            : undefined;
                         const delivery = () => (0, index_1.marrowAuto)(API_KEY, BASE_URL, {
                             action,
                             outcome,
@@ -2023,6 +2033,8 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                             type,
                             proof: suppliedProof,
                             gate_receipt_id: suppliedRuntimeReceiptId || undefined,
+                            arbitration_receipt_id: suppliedArbitrationReceiptId,
+                            owner_approval_receipt_id: suppliedOwnerApprovalReceiptId,
                             // Low-risk one-shot capture does not need a policy gate. Consequential
                             // work obtains exactly one canonical runtime authorization inside auto.
                             auto_gate: highRisk,
@@ -2078,11 +2090,15 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                             receipt,
                             completion_state: delivered?.committed
                                 ? 'closed_with_proof'
-                                : delivered?.phase === 'proof_required'
-                                    ? 'pending_required_proof'
-                                    : delivered?.phase === 'decision_created' || outcomeSuccess === undefined
-                                        ? 'pending_evidence'
-                                        : 'delivery_pending',
+                                : delivered?.phase === 'review_required'
+                                    ? 'review_required_terminal'
+                                    : delivered?.phase === 'owner_approval_required'
+                                        ? 'pending_owner_approval'
+                                        : delivered?.phase === 'proof_required'
+                                            ? 'pending_required_proof'
+                                            : delivered?.phase === 'decision_created' || outcomeSuccess === undefined
+                                                ? 'pending_evidence'
+                                                : 'delivery_pending',
                             decision_id: delivered?.decision_id || null,
                             operation_id: delivered?.operation_id || (typeof args.operation_id === 'string' ? args.operation_id : null),
                             phase: delivered?.phase || null,
@@ -2091,11 +2107,15 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                             phase_timings_ms: delivered?.phase_timings_ms || null,
                             exact_next_action: delivered?.committed
                                 ? 'The governed outcome is closed. Reuse this decision_id only for read-only trace inspection.'
-                                : delivered?.phase === 'proof_required'
-                                    ? 'Attach the required measured proof and retry marrow_auto with this same operation_id and unchanged action, context, and surfaces.'
-                                    : delivered?.resumable
-                                        ? 'Retry marrow_auto with this same operation_id. Do not start a new auto operation.'
-                                        : 'Close this decision after the real outcome is known.',
+                                : delivered?.exact_next_action
+                                    ? delivered.exact_next_action
+                                    : delivered?.phase === 'owner_approval_required'
+                                        ? 'Approve this exact arbitration decision in the authenticated Marrow dashboard, then call marrow_auto once with this same operation_id, arbitration_receipt_id, and the server-issued owner_approval_receipt_id. Do not retry proof or use chat approval text.'
+                                        : delivered?.phase === 'proof_required'
+                                            ? 'Attach the required measured proof and retry marrow_auto with this same operation_id and unchanged action, context, and surfaces.'
+                                            : delivered?.resumable
+                                                ? 'Retry marrow_auto with this same operation_id. Do not start a new auto operation.'
+                                                : 'Close this decision after the real outcome is known.',
                             live_delivery: {
                                 accepted: Boolean(delivered?.decision_id),
                                 committed: Boolean(delivered?.committed),
@@ -2285,7 +2305,7 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                     }
                     if (toolName === 'marrow_agent_status') {
                         const result = await (0, index_1.marrowAgentStatus)(API_KEY, BASE_URL, args.period || '7d', args.agentId || FLEET_AGENT_ID, SESSION_ID, FLEET_AGENT_ID);
-                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        success(id, { content: [{ type: 'text', text: JSON.stringify({ ...result, local_control: (0, control_state_1.localControlEvidence)(Boolean(API_KEY)) }, null, 2) }] });
                         return;
                     }
                     if (toolName === 'marrow_runtime_status') {