@getmarrow/mcp 3.9.75 → 3.9.77

package/README.md

@@ -87,6 +87,18 @@ For most new installations, start with the universal installer instead:
 npx @getmarrow/install activate
 ```
 
+## Tool Profiles
+
+Ordinary setup does not require `MARROW_TOOL_PROFILE`. When the variable is unset, Marrow uses the `primary` profile and exposes exactly the 17 tools in [Primary MCP Tools](#primary-mcp-tools).
+
+- `MARROW_TOOL_PROFILE=primary` explicitly selects the same 17-tool primary surface.
+- `MARROW_TOOL_PROFILE=core` preserves the seven-tool runtime, think, commit, ask, status, auto, and handoff-status surface.
+- `MARROW_TOOL_PROFILE=full` exposes the complete advanced and legacy catalog for integrations that require it.
+
+An invalid value returns a bounded configuration error with the exact allowed values; it never falls back to `full`. Restart the MCP process after changing the profile.
+
+Local visibility does not grant paid access. Every tool call continues through Marrow's backend authentication, tenant, key-permission, plan, proof, and policy enforcement. MCP status responses include `mcp_tool_profile` with the configured and effective profile, visible tool names/count, and a backend primary-tool entitlement projection when fresh authenticated evidence is provided. Missing or cached entitlement evidence is labeled unavailable and cannot authorize a call.
+
 ## Keeping MCP Current
 
 Marrow's hosted API, website, and dashboard update automatically; local MCP hooks, configuration, and pinned package commands do not silently rewrite themselves. Keeping them current delivers new client-side features, compatibility improvements, and any published security fixes. During authenticated status/runtime activity, Marrow returns a `client_update` notice when the package is behind or unknown, and passive context shows the agent the exact update and verification commands.
@@ -104,7 +116,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.75
+## What's New in v3.9.77
+
+v3.9.77 makes `primary` the ordinary MCP profile when `MARROW_TOOL_PROFILE` is unset. The default surface now matches the 17 documented Primary MCP Tools, while explicit `core` preserves the seven-tool control loop and explicit `full` preserves the complete catalog. Invalid values fail with an exact bounded repair instead of broadening visibility. Status responses report the effective profile, visible names/count, and fresh backend-projected entitlement states when provided; local visibility and cached evidence never authorize access. The exact-version 11-tool control-path canary remains pinned to `full`.
+
+## Previous: 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.
 
@@ -193,7 +213,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 client-self-reported and does not certify observed coverage; the governed wrapper remains an explicit bounded fallback.
+In v3.9.62, the default surface was seven tools (runtime, think, commit, ask, status, auto, handoff status) and the prompt remained 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
 
@@ -247,7 +267,7 @@ The compact agent control path introduced in v3.9.57 remains the default:
 - `marrow_status`, `marrow_ask`, and `marrow_agent_runtime` use authenticated routes with bounded retries and typed failures;
 - transient read failures return an owner-only last-known brief when available, while cached guidance can never authorize high-risk work;
 - normal tool errors return structured `ok`, `error_code`, `exact_fix`, `stale_brief`, and `client_update` data instead of raw MCP `fetch failed` errors;
-- the default agent surface is seven tools: runtime, think, commit, ask, status, auto, and handoff status; set `MARROW_TOOL_PROFILE=full` only for legacy or advanced integrations;
+- the v3.9.58 default agent surface was seven tools: runtime, think, commit, ask, status, auto, and handoff status; `MARROW_TOOL_PROFILE=full` selected legacy or advanced integrations;
 - risky `marrow_auto` calls obtain a fresh runtime gate automatically and cannot self-close as successful without required proof;
 - `marrow_run` requires an explicit outcome and never invents proof or a successful result;
 - the package includes an exact-version control-path canary covering every route reported in the production incident.
@@ -353,7 +373,7 @@ Configured hooks can provide cooperative telemetry and context, but they are not
 
 `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:
 

package/dist/cli.js

@@ -544,6 +544,7 @@ if (process.argv[2] !== 'keys') {
                     drain_command: 'npx -y --package=@getmarrow/mcp@latest marrow-mcp drain-spool',
                     legacy_namespaces: spool.other_namespaces?.count || 0,
                 },
+                mcp_tool_profile: mcpToolProfileStatus(payload),
             };
         }
         // [FIX #9] Runtime validation helper for required string params
@@ -938,6 +939,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.',
@@ -1716,15 +1719,168 @@ if (process.argv[2] !== 'keys') {
             'marrow_auto',
             'marrow_handoff_status',
         ]);
+        const PRIMARY_TOOL_NAMES = new Set([
+            'marrow_agent_runtime',
+            'marrow_arbitrate',
+            'marrow_coordinate',
+            'marrow_replay_compare',
+            'marrow_decision_brief',
+            'marrow_think',
+            'marrow_commit',
+            'marrow_workflow_gate',
+            'marrow_completion_contracts',
+            'marrow_evaluate_completion_contract',
+            'marrow_agent_status',
+            'marrow_value_report',
+            'marrow_buyer_proof',
+            'marrow_governance_timeline',
+            'marrow_decision_trace',
+            'marrow_fleet_lessons',
+            'marrow_model_usage',
+        ]);
+        function activeToolProfile() {
+            const configured = process.env.MARROW_TOOL_PROFILE;
+            if (configured === undefined || configured === 'primary')
+                return 'primary';
+            if (configured === 'core' || configured === 'full')
+                return configured;
+            throw new Error('Invalid MARROW_TOOL_PROFILE value. Set MARROW_TOOL_PROFILE=primary, core, or full, '
+                + 'or unset it for primary; then restart MCP.');
+        }
+        function toolsForProfile(profile) {
+            if (profile === 'full')
+                return TOOLS;
+            const visibleNames = profile === 'primary' ? PRIMARY_TOOL_NAMES : CORE_TOOL_NAMES;
+            return TOOLS.filter((tool) => visibleNames.has(tool.name));
+        }
         function advertisedTools() {
-            return process.env.MARROW_TOOL_PROFILE === 'full'
-                ? TOOLS
-                : TOOLS.filter((tool) => CORE_TOOL_NAMES.has(tool.name));
+            return toolsForProfile(activeToolProfile());
         }
         function toolAllowedByActiveProfile(toolName) {
-            return process.env.MARROW_TOOL_PROFILE === 'full'
-                ? Boolean(toolName && TOOLS.some((tool) => tool.name === toolName))
-                : Boolean(toolName && CORE_TOOL_NAMES.has(toolName));
+            return Boolean(toolName && toolsForProfile(activeToolProfile()).some((tool) => tool.name === toolName));
+        }
+        function recordValue(value) {
+            return value && typeof value === 'object' && !Array.isArray(value)
+                ? value
+                : null;
+        }
+        function nonNegativeInteger(value) {
+            return Number.isInteger(value) && Number(value) >= 0;
+        }
+        function validatedPrimaryToolAvailability(value) {
+            const projection = recordValue(value);
+            const evidence = recordValue(projection?.entitlement_evidence);
+            const counts = recordValue(projection?.counts);
+            const tools = projection?.tools;
+            const expectedNames = [...PRIMARY_TOOL_NAMES];
+            if (!projection
+                || projection.profile !== 'primary'
+                || (projection.current_plan !== null && typeof projection.current_plan !== 'string')
+                || typeof projection.owner_management_url !== 'string'
+                || !evidence
+                || (evidence.state !== 'available' && evidence.state !== 'unavailable')
+                || typeof evidence.source !== 'string'
+                || typeof evidence.authoritative !== 'boolean'
+                || evidence.authorizing !== false
+                || !counts
+                || !nonNegativeInteger(counts.total)
+                || !nonNegativeInteger(counts.entitled)
+                || !nonNegativeInteger(counts.upgrade_required)
+                || !nonNegativeInteger(counts.unavailable)
+                || counts.total !== expectedNames.length
+                || counts.entitled + counts.upgrade_required + counts.unavailable !== counts.total
+                || !Array.isArray(tools)
+                || tools.length !== expectedNames.length) {
+                return null;
+            }
+            if ((evidence.state === 'available' && evidence.authoritative !== true)
+                || (evidence.state === 'unavailable' && evidence.authoritative !== false)) {
+                return null;
+            }
+            const derivedCounts = { entitled: 0, upgrade_required: 0, unavailable: 0 };
+            for (let index = 0; index < tools.length; index++) {
+                const tool = recordValue(tools[index]);
+                const state = tool?.state;
+                if (!tool
+                    || tool.name !== expectedNames[index]
+                    || (state !== 'entitled' && state !== 'upgrade_required' && state !== 'unavailable')
+                    || typeof tool.always_available !== 'boolean'
+                    || (tool.plan_feature !== null && typeof tool.plan_feature !== 'string')
+                    || (tool.minimum_plan !== null && typeof tool.minimum_plan !== 'string')
+                    || typeof tool.owner_management_url !== 'string') {
+                    return null;
+                }
+                derivedCounts[state]++;
+            }
+            if (derivedCounts.entitled !== counts.entitled
+                || derivedCounts.upgrade_required !== counts.upgrade_required
+                || derivedCounts.unavailable !== counts.unavailable) {
+                return null;
+            }
+            return {
+                projection,
+                evidenceState: evidence.state,
+            };
+        }
+        function backendPrimaryToolAvailability(value) {
+            const payload = recordValue(value);
+            if (!payload)
+                return null;
+            const data = recordValue(payload.data);
+            const status = recordValue(payload.status);
+            const entitlements = recordValue(payload.entitlements);
+            const entitlementProjection = recordValue(payload.entitlement_projection);
+            const statusEntitlements = recordValue(status?.entitlements);
+            const statusProjection = recordValue(status?.entitlement_projection);
+            const candidates = [
+                payload.primary_tool_availability,
+                data?.primary_tool_availability,
+                status?.primary_tool_availability,
+                entitlements?.primary_tool_availability,
+                entitlementProjection?.primary_tool_availability,
+                statusEntitlements?.primary_tool_availability,
+                statusProjection?.primary_tool_availability,
+            ];
+            for (const candidate of candidates) {
+                const validated = validatedPrimaryToolAvailability(candidate);
+                if (validated)
+                    return validated;
+            }
+            return null;
+        }
+        function mcpToolProfileStatus(value) {
+            const profile = activeToolProfile();
+            const visibleToolNames = toolsForProfile(profile).map((tool) => tool.name);
+            const payload = recordValue(value);
+            const cachedOrStale = payload?.cached === true
+                || payload?.stale === true
+                || payload?.status_freshness === 'stale';
+            const backendProjection = cachedOrStale ? null : backendPrimaryToolAvailability(payload);
+            const backendProjectionAvailable = backendProjection?.evidenceState === 'available';
+            return {
+                configured_profile: process.env.MARROW_TOOL_PROFILE ?? 'unset',
+                effective_profile: profile,
+                visible_tool_count: visibleToolNames.length,
+                visible_tool_names: visibleToolNames,
+                local_visibility_grants_entitlement: false,
+                backend_entitlement_projection: {
+                    evidence_state: backendProjectionAvailable ? 'available' : 'unavailable',
+                    source: cachedOrStale
+                        ? 'cached_or_stale_status'
+                        : backendProjection
+                            ? 'authenticated_backend'
+                            : 'backend_projection_not_provided',
+                    authorizes_calls: false,
+                    primary_tool_availability: backendProjectionAvailable ? backendProjection.projection : null,
+                },
+            };
+        }
+        function withMcpToolProfileStatus(value) {
+            const payload = recordValue(value) || { data: value };
+            return {
+                ...payload,
+                mcp_tool_profile: mcpToolProfileStatus(payload),
+            };
         }
         // Request handler
         async function handleRequest(req) {
@@ -1845,7 +2001,10 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                     const toolName = params?.name;
                     const args = (params?.arguments || {});
                     if (!toolAllowedByActiveProfile(toolName)) {
-                        error(id, -32601, 'Tool is not available in the active Marrow tool profile. Set MARROW_TOOL_PROFILE=full and restart MCP for advanced operator tools.');
+                        const repair = toolName && PRIMARY_TOOL_NAMES.has(toolName)
+                            ? 'Unset MARROW_TOOL_PROFILE or set MARROW_TOOL_PROFILE=primary, then restart MCP.'
+                            : 'Set MARROW_TOOL_PROFILE=full, then restart MCP for the complete advanced/legacy catalog.';
+                        error(id, -32601, `Tool is not available in the active Marrow tool profile. ${repair}`);
                         return;
                     }
                     if (toolName === 'marrow_orient') {
@@ -2018,6 +2177,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,
@@ -2025,6 +2190,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,
@@ -2080,11 +2247,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,
@@ -2093,11 +2264,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),
@@ -2286,13 +2461,24 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         return;
                     }
                     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, local_control: (0, control_state_1.localControlEvidence)(Boolean(API_KEY)) }, null, 2) }] });
+                        const result = await withControlDeadline(async (signal) => {
+                            const [analyticsStatus, context] = await Promise.all([
+                                (0, index_1.marrowAgentStatus)(API_KEY, BASE_URL, args.period || '7d', args.agentId || FLEET_AGENT_ID, SESSION_ID, FLEET_AGENT_ID, signal),
+                                (0, index_1.marrowAgentContext)(API_KEY, BASE_URL, SESSION_ID, FLEET_AGENT_ID, signal)
+                                    .catch(() => null),
+                            ]);
+                            const contextProjection = recordValue(context)?.primary_tool_availability;
+                            return {
+                                ...analyticsStatus,
+                                ...(contextProjection === undefined ? {} : { primary_tool_availability: contextProjection }),
+                            };
+                        }, { cacheAware: false, toolName: 'marrow_agent_status' });
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(withMcpToolProfileStatus({ ...result, local_control: (0, control_state_1.localControlEvidence)(Boolean(API_KEY)) }), null, 2) }] });
                         return;
                     }
                     if (toolName === 'marrow_runtime_status') {
                         const result = await withControlDeadline((signal) => (0, index_1.marrowRuntimeStatus)(API_KEY, BASE_URL, args.fast !== false, SESSION_ID, FLEET_AGENT_ID, signal), { cacheAware: false, toolName: 'marrow_runtime_status' });
-                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(withMcpToolProfileStatus(result), null, 2) }] });
                         return;
                     }
                     if (toolName === 'marrow_value_report') {