@getmarrow/mcp 3.9.48 → 3.9.50

package/README.md

@@ -82,26 +82,40 @@ Then configure the MCP server:
 For most new installations, start with the universal installer instead:
 
 ```bash
-npx @getmarrow/install --yes
+npx @getmarrow/install activate
 ```
 
-## What's New in v3.9.48
+## What's New in v3.9.50
 
-v3.9.48 moves session orientation onto Marrow's canonical `/v1/agent/runtime` contract. Agent-bound keys now receive before-action warnings without depending on retired broad-scope orient or pattern routes. It preserves the machine-readable governance-fit contract introduced in v3.9.47 and the always-on lifecycle introduced in v3.9.44:
+v3.9.50 makes native passive-hook coverage verifiable. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`/`PostToolUseFailure`, and `Stop` attach bounded evidence for the hook that actually ran, the native-hook capability level, the adapter version, and a one-way fingerprint of the exact installed hook contract:
+
+- agents and owners can distinguish “MCP configured” from “pre-action, result, and session hooks actually observed”;
+- `PreToolUse` requests the Marrow runtime gate before matched actions and maps `block` to deny and `review_required` to operator review;
+- matching `PreToolUse` and result hooks share Claude Code's tool-use correlation while the session shares one workflow identity;
+- generic integration events cannot claim native-hook coverage unless the native adapter supplies that evidence;
+- retries preserve correlation and capability evidence in the owner-only durable spool;
+- configuration drift can be diagnosed without sending configuration contents;
+- missing outcome closure remains visible rather than treating tool or session exit as business success;
+- existing MCP tools and lifecycle inputs remain compatible.
+
+It preserves `marrow_arbitrate` from v3.9.49, the session-orientation hardening introduced in v3.9.48, and the always-on lifecycle introduced in v3.9.44:
 
 - `server.json` and `mcpName` identify the stdio server, required secret, source repository, and package version for registry consumers;
 - GitHub, npm, and MCP registry surfaces use separate signed discovery placements;
 - package language consistently describes agent governance, runtime control, proof, and fleet intelligence;
 - bounded positive and negative recommendation criteria stop agents from forcing Marrow into irrelevant workflows;
 - current evidence, integration paths, and published references are linked from one review-dated contract;
-- `UserPromptSubmit` obtains relevant before-action guidance without storing raw prompt text;
-- `PostToolUse` records compact success/failure lifecycle receipts;
+- `UserPromptSubmit` obtains relevant task guidance without storing raw prompt text;
+- `PreToolUse` checks matched tool actions before execution without sending raw tool input;
+- `PostToolUse` and `PostToolUseFailure` record compact result receipts;
 - `Stop` keeps unfinished outcomes visible instead of silently treating a session exit as success;
 - transient lifecycle delivery failures use an owner-only, bounded local spool with stable event IDs;
 - `marrow_decision_trace` explains the tenant-scoped path from prior failure and lesson through gate, proof, workflow, and outcome.
 
 Existing MCP tools and stable context API names remain compatible. Authentication, policy, proof, and validation failures are surfaced rather than retried as network failures.
 
+Coverage percentages are produced only when Marrow has exact observed receipts. An installed config without observed hooks is shown as warming up or degraded, with `npx @getmarrow/install --repair` as the bounded repair path.
+
 ## Governed Action Flow
 
 Before deploys, merges, publishes, migrations, credential changes, financial operations, or customer-impacting work:
@@ -157,6 +171,43 @@ Example closeout:
 
 High-risk work can be allowed, warned, held for review, or blocked according to account policy. Low-risk work can use passive guidance and bounded cached state where the runtime contract permits it.
 
+When two or more agents disagree on the next action, call `marrow_arbitrate`
+before either proposal executes. It uses the same `/v1/agent/runtime` control
+plane and returns `selected`, `synthesized`, `review_required`, or `blocked`
+with a durable tenant-scoped receipt explaining the policy, evidence, authority,
+risk, and dissent behind the result.
+
+```json
+{
+  "tool": "marrow_arbitrate",
+  "arguments": {
+    "objective": "Release the audited backend change safely",
+    "ownerIntent": "Production deploys require independent audit proof",
+    "proposals": [
+      {
+        "proposal_id": "deploy-now",
+        "agent_id": "jarvis",
+        "action": "Deploy the tested commit now",
+        "risk_level": "high"
+      },
+      {
+        "proposal_id": "audit-first",
+        "agent_id": "barvis",
+        "action": "Audit the exact commit, then release only if it passes"
+      }
+    ]
+  }
+}
+```
+
+Marrow resolves agent roles from the account rather than trusting caller claims.
+Evidence references must be opaque identifiers; do not send raw prompts, logs,
+URLs, paths, credentials, or customer content. The arbitration response owns the
+`decision_id`, gate receipt, and arbitration receipt used at commit. A
+`review_required` result must be approved from an authenticated Marrow dashboard
+session; pass its short-lived, single-use `owner_approval_receipt_id` to
+`marrow_commit`. An agent cannot authorize itself with a proof field.
+
 ## Passive Use
 
 `npx @getmarrow/mcp setup` installs supported prompt, tool-result, and session-stop hooks so the agent can receive before-action context, record meaningful tool outcomes, and keep unfinished closure visible without the owner repeatedly prompting it to use Marrow.
@@ -176,6 +227,7 @@ Status diagnostics distinguish missing keys, invalid keys, wrong bound-agent ide
 | Tool | Purpose |
 | --- | --- |
 | `marrow_agent_runtime` | One-call pre-action status, policy gate, relevant lessons, proof requirements, and exact next action |
+| `marrow_arbitrate` | Resolve conflicting agent proposals before execution and return an explainable arbitration receipt |
 | `marrow_decision_brief` | Compact operating brief for meaningful work |
 | `marrow_think` | Record intent and retrieve relevant governance intelligence |
 | `marrow_commit` | Close an action with outcome, receipt, and proof |

package/dist/cli.js

@@ -14,6 +14,7 @@ const index_1 = require("./index");
 const hook_1 = require("./hook");
 const hook_context_1 = require("./hook-context");
 const hook_session_1 = require("./hook-session");
+const hook_pre_action_1 = require("./hook-pre-action");
 const env_1 = require("./env");
 const redact_1 = require("./redact");
 // Parse CLI args
@@ -34,6 +35,9 @@ function parseArgs() {
         if (args[i] === 'context-hook' || args[i] === '--context-hook') {
             result.contextHook = true;
         }
+        if (args[i] === 'pre-action-hook' || args[i] === '--pre-action-hook') {
+            result.preActionHook = true;
+        }
         if (args[i] === 'session-hook' || args[i] === '--session-hook') {
             result.sessionHook = true;
         }
@@ -115,6 +119,13 @@ ${MARROW_BLOCK_END}`;
     else {
         process.stdout.write('UserPromptSubmit hook already installed — Marrow context and passive decision briefs are injected on matching prompts.\n');
     }
+    const preActionHookInstall = (0, hook_pre_action_1.installPreActionHook)(process.cwd());
+    if (preActionHookInstall.installed) {
+        process.stdout.write('Installed PreToolUse hook — Marrow now checks each matched action before execution.\n');
+    }
+    else {
+        process.stdout.write('PreToolUse hook already installed — matched actions are checked before execution.\n');
+    }
     const sessionHookInstall = (0, hook_session_1.installSessionEndHook)(process.cwd());
     if (sessionHookInstall.installed) {
         process.stdout.write('Installed Stop hook — unfinished outcomes remain visible for reconciliation.\n');
@@ -230,6 +241,9 @@ if (process.argv[2] !== 'keys') {
     else if (cliArgs.contextHook) {
         void (0, hook_context_1.runContextHookCommand)();
     }
+    else if (cliArgs.preActionHook) {
+        void (0, hook_pre_action_1.runPreActionHookCommand)();
+    }
     else if (cliArgs.sessionHook) {
         void (0, hook_session_1.runSessionHookCommand)();
     }
@@ -262,26 +276,6 @@ if (process.argv[2] !== 'keys') {
         let thinkCallCount = 0;
         let orientCallCount = 0;
         let initialized = false;
-        const pendingDecisions = new Map();
-        const PENDING_TTL_MS = 30 * 60 * 1000; // 30 min TTL
-        function actionHash(action) {
-            const normalized = action.toLowerCase().trim().replace(/\s+/g, ' ');
-            let h = 5381;
-            for (let i = 0; i < normalized.length; i++) {
-                h = ((h << 5) + h) ^ normalized.charCodeAt(i);
-                h = h >>> 0;
-            }
-            return h.toString(36) + '_' + normalized.slice(0, 32);
-        }
-        // [FIX #11] Actually call cleanupPending to prevent unbounded map growth
-        function cleanupPending() {
-            const now = Date.now();
-            for (const [key, val] of pendingDecisions) {
-                if (now - val.timestamp > PENDING_TTL_MS) {
-                    pendingDecisions.delete(key);
-                }
-            }
-        }
         function formatWarningActionably(w) {
             const pct = Math.round(w.failureRate * 100);
             return `⚠️ ${w.type} has ${pct}% failure rate — check what went wrong last time before proceeding`;
@@ -594,6 +588,8 @@ if (process.argv[2] !== 'keys') {
                             description: 'Optional required proof pack for gated work: summary, checks, outcome, blockers, commits_prs_shas, rollback_target, handoff_result_file, deployment_and_smoke.',
                         },
                         gate_receipt_id: { type: 'string', description: 'Receipt id from marrow_agent_runtime.gate_receipt.id for risky work.' },
+                        arbitration_receipt_id: { type: 'string', description: 'Required for arbitrated work: use marrow_arbitrate.arbitration.receipt_id from the same runtime response.' },
+                        owner_approval_receipt_id: { type: 'string', description: 'Single-use owner approval receipt issued by authenticated dashboard review for review_required arbitration.' },
                         action: { type: 'string', description: 'Optional original action. If provided and gate_receipt_id is omitted, MCP can fetch a matching runtime gate receipt before commit.' },
                         type: { type: 'string', description: 'Optional original action type for auto gate lookup, e.g. deploy, publish, merge, handoff, implementation.' },
                         surfaces: { type: 'array', items: { type: 'string' }, description: 'Optional surfaces for auto gate receipt, e.g. github, cloudflare, npm, production.' },
@@ -1025,6 +1021,61 @@ if (process.argv[2] !== 'keys') {
                     required: ['action'],
                 },
             },
+            {
+                name: 'marrow_arbitrate',
+                description: 'Resolve conflicting next-step proposals from two or more tenant agents before execution. ' +
+                    'Uses the existing Marrow runtime gate and returns a durable arbitration receipt with the selected, ' +
+                    'synthesized, review-required, or blocked action and exactly why it changed.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        objective: { type: 'string', description: 'The shared owner or workflow objective.' },
+                        ownerIntent: { type: 'string', description: 'Optional bounded owner intent used for deterministic alignment.' },
+                        conflictType: {
+                            type: 'string',
+                            enum: ['action_conflict', 'policy_conflict', 'evidence_conflict', 'authority_conflict', 'risk_conflict'],
+                        },
+                        proposals: {
+                            type: 'array',
+                            minItems: 2,
+                            maxItems: 8,
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    proposal_id: { type: 'string', description: 'Stable opaque proposal id.' },
+                                    agent_id: { type: 'string', description: 'Existing agent id in this Marrow account.' },
+                                    action: { type: 'string', description: 'Proposed next action.' },
+                                    rationale: { type: 'string', description: 'Optional concise rationale; redacted before transport.' },
+                                    confidence: { type: 'number', minimum: 0, maximum: 1 },
+                                    risk_level: { type: 'string', enum: ['low', 'medium', 'high'] },
+                                    requires_owner_approval: { type: 'boolean' },
+                                    evidence: {
+                                        type: 'array',
+                                        maxItems: 8,
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                kind: { type: 'string' },
+                                                reference: { type: 'string', description: 'Opaque identifier only; no URL, path, or raw evidence.' },
+                                            },
+                                            required: ['kind', 'reference'],
+                                        },
+                                    },
+                                },
+                                required: ['proposal_id', 'agent_id', 'action'],
+                            },
+                        },
+                        action: { type: 'string', description: 'Optional runtime action label.' },
+                        type: { type: 'string', description: 'Optional runtime action type. Defaults to coordination.' },
+                        agentId: { type: 'string', description: 'Requesting agent id. Defaults to MARROW_AGENT_ID.' },
+                        sessionId: { type: 'string', description: 'Optional workflow session id.' },
+                        surfaces: { type: 'array', items: { type: 'string' } },
+                        context: { type: 'object', description: 'Optional non-sensitive runtime metadata.' },
+                        proof: { type: 'object', description: 'Optional proof already available to the runtime gate.' },
+                    },
+                    required: ['objective', 'proposals'],
+                },
+            },
             {
                 name: 'marrow_governance_control_plane',
                 description: 'Return Marrow control-plane proof: governance, runtime gates, proof packs, fleet intelligence, supported harnesses, and exact next action.',
@@ -1319,7 +1370,7 @@ if (process.argv[2] !== 'keys') {
                     success(id, {
                         protocolVersion: '2024-11-05',
                         capabilities: { tools: {}, prompts: {} },
-                        serverInfo: { name: 'marrow', version: '3.9.48' },
+                        serverInfo: { name: 'marrow', version: '3.9.50' },
                     });
                     // Auto-enroll: emit enrollment notification on connection
                     if (AUTO_ENROLL) {
@@ -1502,6 +1553,8 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                             caused_by: args.caused_by,
                             proof: args.proof,
                             gate_receipt_id: args.gate_receipt_id,
+                            arbitration_receipt_id: args.arbitration_receipt_id,
+                            owner_approval_receipt_id: args.owner_approval_receipt_id,
                             action: args.action,
                             type: args.type,
                             surfaces: args.surfaces,
@@ -1590,8 +1643,6 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         const outcome = args.outcome;
                         const outcomeSuccess = args.success ?? true;
                         const type = args.type || 'general';
-                        // [FIX #11] Cleanup pending decisions on each auto call
-                        cleanupPending();
                         // [FIX #8] Include pending flag so agent knows logging is deferred
                         const response = {
                             action,
@@ -1845,6 +1896,29 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
                         return;
                     }
+                    if (toolName === 'marrow_arbitrate') {
+                        const result = await (0, index_1.marrowArbitrate)(API_KEY, BASE_URL, {
+                            objective: (0, redact_1.redactSensitiveText)(args.objective),
+                            owner_intent: typeof args.ownerIntent === 'string' ? (0, redact_1.redactSensitiveText)(args.ownerIntent) : undefined,
+                            conflict_type: args.conflictType,
+                            proposals: Array.isArray(args.proposals)
+                                ? args.proposals
+                                : [],
+                            action: typeof args.action === 'string' ? (0, redact_1.redactSensitiveText)(args.action) : undefined,
+                            type: args.type,
+                            agent_id: args.agentId || AGENT_ID,
+                            session_id: args.sessionId || SESSION_ID,
+                            surfaces: Array.isArray(args.surfaces) ? args.surfaces : undefined,
+                            context: args.context && typeof args.context === 'object' && !Array.isArray(args.context)
+                                ? (0, redact_1.redactSensitiveValue)(args.context)
+                                : undefined,
+                            proof: args.proof && typeof args.proof === 'object' && !Array.isArray(args.proof)
+                                ? (0, redact_1.redactSensitiveValue)(args.proof)
+                                : undefined,
+                        }, SESSION_ID, FLEET_AGENT_ID);
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        return;
+                    }
                     if (toolName === 'marrow_governance_control_plane') {
                         const result = await (0, index_1.marrowGovernanceControlPlane)(API_KEY, BASE_URL, SESSION_ID, FLEET_AGENT_ID);
                         success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });