@geraldmaron/construct 1.4.0 → 1.4.2

package/lib/mcp/server.mjs

@@ -18,6 +18,9 @@ import { loadConstructEnv, prepareConstructEnv } from '../runtime-env.mjs';
 import { getInstalledVersion } from '../version.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } from '../telemetry/otel-tracer.mjs';
+import { TOOL_SAFETY, DEFAULT_OUTPUT_SCHEMA } from './tool-safety.mjs';
+import { ToolRateLimiter, ToolRateLimited } from './tool-rate-limit.mjs';
+import { appendAuditRecord } from '../audit-trail.mjs';
 
 // Apply config.env values to process.env, letting config.env win over shell env
 // so telemetry/OpenRouter credentials are always correct regardless of host env.
@@ -63,6 +66,8 @@ import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe, exec
 import { authorArtifact } from './tools/artifact-author.mjs';
 import { findTool } from './tools/find-tool.mjs';
 import { recoverToolName, recordToolNameMiss, isGatewayName } from './tool-recovery.mjs';
+import { assertCoreSubsetOfCatalog } from './tool-surface-parity.mjs';
+import { enableSecretAuditTrail } from '../providers/secret-audit-wiring.mjs';
 import { buildOrchestrationReadiness } from '../orchestration/readiness.mjs';
 
 const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -125,12 +130,25 @@ server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
 
 // The full construct-mcp tool catalog. Only a curated core is exposed flat in
 // ListTools; the long tail is reachable through the construct_call meta-tool, so
-// the serialized tool surface stays small on every host and model. The 71-tool
-// flat surface alone (~10.6k tokens) overran a 32k local-model window.
+// the serialized tool surface stays small on every host and model. The 75-tool
+// flat surface alone (~14.8k tokens) overran a 32k local-model window.
+
+// Every tool def gains a declared outputSchema and a safety block (class, fs/
+// network/process scope) from TOOL_SAFETY. A tool missing from that table throws
+// here rather than shipping unclassified — see lib/mcp/tool-safety.mjs.
+
+function withSafetyEnvelope(def) {
+  const safety = TOOL_SAFETY[def.name];
+  if (!safety) {
+    throw new Error(`tool-safety: "${def.name}" has no safety classification — add one to lib/mcp/tool-safety.mjs`);
+  }
+  return { ...def, outputSchema: def.outputSchema ?? DEFAULT_OUTPUT_SCHEMA, safety };
+}
 
 const ALL_TOOL_DEFS = [
     {
       name: 'agent_health',
+      outputSchema: { type: 'object' },
       description: 'Returns agent health summaries from the most recent performance review.',
       inputSchema: {
         type: 'object',
@@ -144,6 +162,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'summarize_diff',
+      outputSchema: { type: 'object' },
       description: 'Summarizes the git diff between the current state and a base ref.',
       inputSchema: {
         type: 'object',
@@ -161,6 +180,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'scan_file',
+      outputSchema: { type: 'object' },
       description: 'Scans a file for secrets and code quality issues.',
       inputSchema: {
         type: 'object',
@@ -175,6 +195,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'extract_document_text',
+      outputSchema: { type: 'object' },
       description: 'Extracts readable text from a local document path. Uses node-native extractors (unpdf/mammoth) first; escalates to the docling Python sidecar or whisper.cpp when needed (same pipeline as `construct ingest`). Supports PDF, DOCX, XLSX, PPTX, HTML, plain text, email, and transcripts.',
       inputSchema: {
         type: 'object',
@@ -193,6 +214,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'ingest_document',
+      outputSchema: { type: 'object' },
       description: 'Converts a local document into a normalized markdown file, placing it into an indexed project path by default.',
       inputSchema: {
         type: 'object',
@@ -227,6 +249,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'infer_document_schema',
+      outputSchema: { type: 'object' },
       description: 'Infers a structured field schema from a local document using AI. Returns field names, types, formats, examples, and confidence. Supports all document types handled by extract_document_text. Pass multiple file_paths to get a reconciled unified schema across documents.',
       inputSchema: {
         type: 'object',
@@ -265,6 +288,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'list_schema_artifacts',
+      outputSchema: { type: 'object' },
       description: 'Lists all inferred schema artifacts (.schema.json files) in the project.',
       inputSchema: {
         type: 'object',
@@ -278,6 +302,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'storage_status',
+      outputSchema: { type: 'object' },
       description: 'Returns SQL, local vector index, and ingested-artifact status for the current project.',
       inputSchema: {
         type: 'object',
@@ -367,6 +392,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'project_context',
+      outputSchema: { type: 'object' },
       description: 'Returns project context: .cx/context.md content, recent commits, and working tree status.',
       inputSchema: {
         type: 'object',
@@ -380,6 +406,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'get_skill',
+      outputSchema: { type: 'object' },
       description: 'Reads a specific skill playbook from the Construct knowledge base (e.g. "docs/adr-workflow", "roles/engineer", "architecture/security-arch").',
       inputSchema: {
         type: 'object',
@@ -391,6 +418,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'orchestration_policy',
+      outputSchema: { type: 'object' },
       description: 'Classifies a request into intent, execution track, specialists, approval boundaries, and the contract chain that applies. The contractChain field names the typed producer→consumer handoffs expected for this dispatch plan. When `candidates` is supplied, also returns `contextPackets` keyed by specialist with the role-filtered artifact bundle each specialist should receive (omitted artifacts include the reason they were dropped).',
       inputSchema: {
         type: 'object',
@@ -442,6 +470,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'list_skills',
+      outputSchema: { type: 'object' },
       description: 'Lists all available categories and playbooks in the Construct knowledge base.',
       inputSchema: {
         type: 'object',
@@ -450,6 +479,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'worker_run',
+      outputSchema: { type: 'object' },
       description: 'Runs a bounded shell command via the worker plane: timeout, path-policy denial, restricted env, stdout/stderr artifacts under `.cx/runtime/worker/<jobId>.{stdout,stderr}.log`. When `graphId` + `nodeId` are supplied, an evidence record is appended to that task graph node so it can transition to `done`. Emits `worker.started` / `worker.completed` / `evidence.recorded` trace events correlated by `traceId`.',
       inputSchema: {
         type: 'object',
@@ -475,6 +505,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'broker_check',
+      outputSchema: { type: 'object' },
       description: 'Queries the MCP broker policy gate for a pending action without executing it. Agents call this BEFORE attempting a high-risk action so the response (allowed / approvalRequired / reason / source) can be surfaced to the user in the agent\'s voice rather than triggering a denial after the fact. In solo mode the broker is off by default — returns `brokerActive: false` with `allowed: true` so the call is cheap and agents don\'t waste tokens on an inactive gate. Always emits a `tool.called` trace event for audit-trail parity. Reads specialists/org fence rules in team / enterprise mode.',
       inputSchema: {
         type: 'object',
@@ -491,6 +522,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'agent_contract',
+      outputSchema: { type: 'object' },
       description: 'Looks up explicit agent-to-agent service contracts (from specialists/org). Specialists should call this at the start of a handoff to see the expected input shape, preconditions, and what postconditions they must satisfy. Use without args to get all contracts; pass producer/consumer to narrow; pass id for a specific contract.',
       inputSchema: {
         type: 'object',
@@ -503,6 +535,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'find_tool',
+      outputSchema: { type: 'object' },
       description: 'Find Construct tools by intent when you do not know the exact name. Describe what you want to do; returns the best-matching tools with their input schemas, ranked by hybrid semantic + lexical relevance. Then invoke a result via the `call` gateway (or directly if it is a flat tool).',
       inputSchema: {
         type: 'object',
@@ -515,6 +548,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'get_template',
+      outputSchema: { type: 'object' },
       description: 'Reads a doc template by name (e.g. "prd", "meta-prd", "prfaq", "evidence-brief", "adr", "runbook"). Resolves .cx/templates/docs/{name}.md first, then templates/docs/{name}.md.',
       inputSchema: {
         type: 'object',
@@ -526,11 +560,14 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'list_templates',
+      outputSchema: { type: 'object' },
       description: 'Lists shipped and project-override doc templates.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
       name: 'search_skills',
+      outputSchema: { type: 'object' },
+      category: 'retrieval',
       description: 'Searches for a pattern within the Construct knowledge base skills.',
       inputSchema: {
         type: 'object',
@@ -542,11 +579,13 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'list_teams',
+      outputSchema: { type: 'object' },
       description: 'Lists all available Construct team templates with members, focus, and promotion gates.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
       name: 'suggest_skills',
+      outputSchema: { type: 'object' },
       description: 'Rank skills from the central catalog for a natural-language intent. Optional specialistId filters entitlement metadata.',
       inputSchema: {
         type: 'object',
@@ -560,6 +599,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'cx_trace',
+      outputSchema: { type: 'object' },
       description: 'Records an agent trace for observability. Call at the start of every significant task with your agent name and the user goal.',
       inputSchema: {
         type: 'object',
@@ -577,6 +617,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'cx_score',
+      outputSchema: { type: 'object' },
       description: 'Attaches a quality score to a trace. Call after producing a significant deliverable.',
       inputSchema: {
         type: 'object',
@@ -591,6 +632,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'cx_trace_update',
+      outputSchema: { type: 'object' },
       description: 'Updates an existing trace with output and metadata. Use when a trace was created early but the result becomes available later.',
       inputSchema: {
         type: 'object',
@@ -604,6 +646,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'session_list',
+      outputSchema: { type: 'object' },
       description: 'List construct sessions for the current project. Returns distilled session index entries with id, project, status, and summary.',
       inputSchema: {
         type: 'object',
@@ -616,6 +659,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'session_load',
+      outputSchema: { type: 'object' },
       description: 'Load a full distilled session record by ID. Returns summary, decisions, files changed, open questions, and task snapshot.',
       inputSchema: {
         type: 'object',
@@ -628,6 +672,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'session_search',
+      outputSchema: { type: 'object' },
       description: 'Search sessions by keyword in summary or project name.',
       inputSchema: {
         type: 'object',
@@ -640,6 +685,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'session_save',
+      outputSchema: { type: 'object' },
       description: 'Update the active session with distilled context: summary, decisions, files changed, open questions, task snapshot.',
       inputSchema: {
         type: 'object',
@@ -658,6 +704,8 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'memory_search',
+      outputSchema: { type: 'object' },
+      category: 'retrieval',
       description: 'Search the observation store for patterns, decisions, and insights learned by specialists across sessions. Returns semantically matched observations scoped by role, category, or project.',
       inputSchema: {
         type: 'object',
@@ -673,6 +721,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'memory_add_observations',
+      outputSchema: { type: 'object' },
       description: 'Record observations (patterns, insights, decisions, anti-patterns) that specialists discover during work. These are indexed for semantic search and surface in future sessions.',
       inputSchema: {
         type: 'object',
@@ -699,6 +748,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'memory_create_entities',
+      outputSchema: { type: 'object' },
       description: 'Track recurring entities (components, services, APIs, dependencies) that specialists encounter. Enables "what do we know about X?" queries.',
       inputSchema: {
         type: 'object',
@@ -723,6 +773,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'memory_recent',
+      outputSchema: { type: 'object' },
       description: 'Returns the most recent observations for the current project, deduplicated by (role, summary). Use this when the session-start hint indicates prior observations are available — fetch them on demand instead of paying for them every session.',
       inputSchema: {
         type: 'object',
@@ -735,6 +786,8 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'rovo_search',
+      outputSchema: { type: 'object' },
+      category: 'retrieval',
       description: 'Cross-system semantic search via Atlassian Rovo. Searches Jira, Confluence, and other accessible sources. Returns excerpts with source attribution. Does NOT store results in the observation store. Use for broad queries across all sources, not just focal projects.',
       inputSchema: {
         type: 'object',
@@ -748,6 +801,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'efficiency_snapshot',
+      outputSchema: { type: 'object' },
       description: 'Returns the read-efficiency snapshot for the current session — repeated reads, large reads, hot-spot files, and recommendations. Use this when investigating why a session feels slow or to surface optimization opportunities.',
       inputSchema: {
         type: 'object',
@@ -758,6 +812,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'session_usage',
+      outputSchema: { type: 'object' },
       description: 'Returns locally recorded interaction token and cost usage for the current Construct session.',
       inputSchema: {
         type: 'object',
@@ -769,6 +824,8 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'provider_fetch',
+      outputSchema: { type: 'object' },
+      category: 'retrieval',
       description: 'Look up current data for a configured repo, project, or team. This is an internal lookup against sources the operator has already authorized (set in config.env). Call this immediately — no user approval needed — whenever the user asks about a specific repo, project, or team name (e.g. "what is project iverson", "cloud-reliability status", "PLAT issues"). Pass the user\'s query and the tool resolves the right source automatically. Returns repo metadata, README, docs, open PRs, issues, and recent commits, then stores them as observations.',
       inputSchema: {
         type: 'object',
@@ -783,6 +840,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'scope_show',
+      outputSchema: { type: 'object' },
       description: 'Return the active Construct scope (id, displayName, roles, departments, intake taxonomy, doc templates). Use when a specialist needs to know which role set, classification taxonomy, or doc templates apply before drafting work.',
       inputSchema: {
         type: 'object',
@@ -794,11 +852,13 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'scope_list',
+      outputSchema: { type: 'object' },
       description: 'List the curated org scope catalog (rnd, operations, creative, research) with role/department counts. Use to discover which scopes are available before suggesting `construct scope set`.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
       name: 'scope_drafts',
+      outputSchema: { type: 'object' },
       description: 'List in-progress draft scopes under `.cx/scopes/draft-*` and any user-defined custom scope at `.cx/scope.json`. Use to see what scope work is pending before scaffolding another draft.',
       inputSchema: {
         type: 'object',
@@ -807,6 +867,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'scope_health',
+      outputSchema: { type: 'object' },
       description: 'Per-scope health rollup over a window: observation count, per-role outcome runs and success rates. Use to check whether a scope is producing data before recommending changes or archive.',
       inputSchema: {
         type: 'object',
@@ -819,6 +880,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'outcomes_summary',
+      outputSchema: { type: 'object' },
       description: 'Read `.cx/outcomes/_summary.json` (per-role success rate, 30-day trend). Pass `aggregate=true` to rebuild the summary from JSONL outcome files first. Use to ground tiebreakers and improvement suggestions in real specialist performance.',
       inputSchema: {
         type: 'object',
@@ -830,6 +892,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'outcomes_record',
+      outputSchema: { type: 'object' },
       description: 'Append a specialist outcome line to `.cx/outcomes/<role>.jsonl` (writes durable state — requires `confirm=true`). Use when a specialist wants to self-report success/failure outside the automatic agent-tracker path.',
       inputSchema: {
         type: 'object',
@@ -850,6 +913,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'knowledge_add',
+      outputSchema: { type: 'object' },
       description: 'Persist a research finding as `.cx/knowledge/external/research/<slug>.md` with research-specific frontmatter (topic, confidence, sources, expiresAt, scope). Writes durable state — requires `confirm=true`. `confidence=confirmed` requires at least one source.',
       inputSchema: {
         type: 'object',
@@ -880,6 +944,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'scope_create',
+      outputSchema: { type: 'object' },
       description: 'Scaffold a draft org scope under `.cx/scopes/draft-<id>/` (requirements.md + scope.json + persona stubs + department charters). Writes durable state — requires `confirm=true`. For curated catalog work, follow `docs/guides/concepts/scope-lifecycle.md` after creation.',
       inputSchema: {
         type: 'object',
@@ -911,6 +976,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'scope_archive',
+      outputSchema: { type: 'object' },
       description: 'Archive a curated scope: moves `specialists/org/scopes/<id>.json` and its intake table into `archive/scopes/<id>/` with an archive note. Destructive — requires `confirm=true` and a substantive `reason` (>=8 chars). Observations and outcomes are preserved.',
       inputSchema: {
         type: 'object',
@@ -924,11 +990,14 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'sandbox_list',
+      outputSchema: { type: 'object' },
       description: 'List Construct sandboxes under `~/.cx/sandboxes/` (id, path, createdAt). Use to find an isolated environment for QA or dry-runs without polluting the active project.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
       name: 'knowledge_graph_ask',
+      outputSchema: { type: 'object' },
+      category: 'retrieval',
       description: 'GraphRAG-style global query over the entity graph in `.cx/observations/`. Detects communities via label propagation, ranks them by BM25 against the query, and returns each top community with its central members and extractive summary. Use for "tell me about how X relates across the project" questions that pure semantic retrieval handles poorly.',
       inputSchema: {
         type: 'object',
@@ -945,6 +1014,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'learning_status',
+      outputSchema: { type: 'object' },
       description: 'One-shot mirror of `npm run learning:status`: active scope, observation counts (last 24h + total), research finding count, per-role outcome rollup. Use to answer "is Construct learning?" without spawning a shell.',
       inputSchema: {
         type: 'object',
@@ -953,6 +1023,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'document_export',
+      outputSchema: { type: 'object' },
       description: 'Convert a markdown file into a distributable document — PDF, DOCX, legacy DOC (LibreOffice), deck HTML, PPTX, HTML, RTF, ODT, EPUB, LaTeX, plain text, or Markdown — via Pandoc and Typst (PDF engine) plus optional pptxgenjs/LibreOffice, per ADR-0024. Engines are optional dependencies discovered at runtime — the tool returns a structured "install <binary>" error when tooling is absent, never crashes. Use `detect_only=true` to check availability without running an export.',
       inputSchema: {
         type: 'object',
@@ -968,6 +1039,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'publish_detect',
+      outputSchema: { type: 'object' },
       description: 'Detect availability of publish pipeline tooling: Pandoc/Typst export, pandoc-ext/diagram figures, and VHS terminal demos.',
       inputSchema: {
         type: 'object',
@@ -980,6 +1052,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'publish_run',
+      outputSchema: { type: 'object' },
       description: 'Run the publish pipeline: export markdown with optional figure filter and optional demo recordings. Use dry_run=true to probe tooling only.',
       inputSchema: {
         type: 'object',
@@ -1000,6 +1073,8 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'knowledge_search',
+      outputSchema: { type: 'object' },
+      category: 'retrieval',
       description: 'Search Construct\'s own documentation, knowledge base, and distilled embed observations. Call this immediately — no approval needed — when the user asks what Construct is, how a feature works, what commands exist, or anything about Construct\'s architecture or configuration. Also searches embed observations from GitHub, Jira, and other configured sources. Returns relevant excerpts with source file and heading.',
       inputSchema: {
         type: 'object',
@@ -1014,6 +1089,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_init',
+      outputSchema: { type: 'object' },
       description: 'Initialize a new workflow for the current project. Creates plan.md state if not already present and returns the initial workflow envelope.',
       inputSchema: {
         type: 'object',
@@ -1026,6 +1102,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_add_task',
+      outputSchema: { type: 'object' },
       description: 'Add a task to the current workflow. Pass `request` for intent-based routing (the classifier picks track + specialist) or pass explicit task fields (`key`, `title`, etc.) for manual entry.',
       inputSchema: {
         type: 'object',
@@ -1052,6 +1129,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_update_task',
+      outputSchema: { type: 'object' },
       description: 'Update fields on an existing workflow task. Requires the task `key`. Only fields supplied are changed.',
       inputSchema: {
         type: 'object',
@@ -1072,6 +1150,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_needs_main_input',
+      outputSchema: { type: 'object' },
       description: 'Mark a workflow task as blocked pending user input. Sets status to blocked_needs_user and writes a packet describing the blocker for the orchestrator to surface.',
       inputSchema: {
         type: 'object',
@@ -1087,6 +1166,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_validate',
+      outputSchema: { type: 'object' },
       description: 'Validate the current workflow state against the schema and run consistency checks (no orphan tasks, no circular dependencies, every owner resolves to a known persona).',
       inputSchema: {
         type: 'object',
@@ -1097,6 +1177,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_status',
+      outputSchema: { type: 'object' },
       description: 'Return the full workflow snapshot for the current project: tasks, summary, alignment health, and the public-health surface used by the dashboard.',
       inputSchema: {
         type: 'object',
@@ -1107,6 +1188,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_contract_validate',
+      outputSchema: { type: 'object' },
       description: 'Validate a producer→consumer handoff against specialists/org. Required when a specialist hands off to another role: enforces input.mustContain, output schema, disk-artifact postconditions, and binary postconditions per producer (rubber-stamp prevention, post-hoc threat-model prevention, etc.). Self-enforcing: a producer with binary rules MUST pass `packet`, or the call itself is a contract violation.',
       inputSchema: {
         type: 'object',
@@ -1123,6 +1205,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_import_plan',
+      outputSchema: { type: 'object' },
       description: 'Bulk-add tasks from a markdown plan to the current workflow. Parses headings and bullet structure to extract task titles, owners, and acceptance criteria.',
       inputSchema: {
         type: 'object',
@@ -1142,6 +1225,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'cx_trace_telemetry',
+      outputSchema: { type: 'object' },
       description: 'Record a single CX telemetry trace for an agent invocation. Use to log start/end, model used, token cost, and outcome verdict for performance review.',
       inputSchema: {
         type: 'object',
@@ -1155,6 +1239,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'artifact_workflow',
+      outputSchema: { type: 'object' },
       description: 'Plan a manifest-backed document artifact workflow and return a truthful provenance report. It separates planned steps from locally executed validation/export and never claims a host-planned specialist review or rewrite was completed. Durable local export requires approval_mode=allow-durable-write.',
       inputSchema: {
         type: 'object',
@@ -1172,6 +1257,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'author_artifact',
+      outputSchema: { type: 'object' },
       description: 'Materialize a typed Construct artifact you have drafted (prd, prd-platform, prd-business, meta-prd, adr, rfc, research-brief, evidence-brief, runbook) to disk and run the release gate. YOU draft the full markdown — start with a single # title and include the type\'s required ## sections (call get_template first for the shape) — and pass it as draft_markdown; the canonical file is written and the gate verdict + errors are returned so you can fix and re-call. This is the Construct author→materialize→validate pass for supported hosts.',
       inputSchema: {
         type: 'object',
@@ -1185,6 +1271,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'model_resolve',
+      outputSchema: { type: 'object' },
       description: 'Resolve which model an embedded Construct workflow should use given the host/IDE provider context. Precedence: host model → same-provider-family fallback → Construct tier default → structured config error. Never reads or returns credential values (requiresCredential is a boolean) and never claims unverified provider health. Read-only; performs no writes.',
       inputSchema: {
         type: 'object',
@@ -1201,6 +1288,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'triage_recommend',
+      outputSchema: { type: 'object' },
       description: 'Classify an artifact and return a role-aware plan (primary owner, role chain with rationale, suggested skills, evidence requirements, expected outputs, approval requirements, risks, next steps, canExecute) WITHOUT enqueuing or executing. Classification confidence is reported distinctly from any generation confidence. Read-only; performs no durable write.',
       inputSchema: {
         type: 'object',
@@ -1218,6 +1306,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'workflow_invoke',
+      outputSchema: { type: 'object' },
       description: 'Invoke a named Construct workflow (roles/skills) non-interactively and return a provenanced execution plan: selected roles, rationale, applied skills, resolved model, evidence requirements, output contract, risks, and a traceId. Construct returns the orchestration plan; the host runtime performs specialist reasoning. Durable writes occur ONLY when approval_mode is allow-durable-write; proposal-only and requires-human-approval perform no durable writes.',
       inputSchema: {
         type: 'object',
@@ -1239,6 +1328,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'capability_describe',
+      outputSchema: { type: 'object' },
       description: 'Describe what this Construct install can do: versions, contract interfaces (CLI/MCP/SDK), roles, skills, workflows, schemas, models/providers, policies, telemetry posture, and plugins. Read-only and secret-free — provider entries carry env-key names and a configured boolean only, never credential values. Reads live registries so the published contract cannot drift from reality.',
       inputSchema: {
         type: 'object',
@@ -1249,6 +1339,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'construct_execution_resolve',
+      outputSchema: { type: 'object' },
       description: 'Resolve the execution-capability contract for an embedded workflow BEFORE/at workflow start: returns executionMode (construct-orchestrated | construct-prompt-only | host-direct | same-family-fallback), constructCapabilitiesActive (subset of personas/skills/workflow-routing/prompt-envelope), degraded + machine-readable degradationReason, requestedStrategy vs effectiveStrategy, and the resolved provider/model. Descriptive, not enforced: reports what Construct planned and can resolve a model for, never an observation that the host ran personas (see the semantics field). Read-only and secret-free.',
       inputSchema: {
         type: 'object',
@@ -1267,6 +1358,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'orchestration_run',
+      outputSchema: { type: 'object' },
       description: 'EXECUTE a real multi-specialist orchestration run and return per-specialist output — the executing counterpart to workflow_invoke (which only plans). For MCP hosts with no subagent primitive (VS Code/Copilot, Cursor), this is how you actually run a specialist chain: the engine owns orchestration, this tool is the thin client (ADR-0022). Solo runs execute in-process — no daemon, no port, no token; a remote/team orchestration service is opt-in via CONSTRUCT_ORCHESTRATION_URL. Real specialist output requires the `provider` worker backend (a provider key configured); the default `inline` backend prepares tasks only.',
       inputSchema: {
         type: 'object',
@@ -1288,6 +1380,8 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'web_search',
+      outputSchema: { type: 'object' },
+      category: 'retrieval',
       description: 'Search the PUBLIC WEB and return CITED results — the only search surface that reaches the open web, kept distinct from knowledge_search / provider_fetch / repo search so it is never conflated or faked. Requires a governed provider (WEB_SEARCH_URL); without one it returns a typed degradation (capability-unavailable) and zero results, never source/repo results dressed as web. Every result carries a verifiable URL, a claim-relative class, and an Admiralty grade with derived confidence (ADR-0017; high reserved for A1/A2/B1).',
       inputSchema: {
         type: 'object',
@@ -1301,6 +1395,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'orchestration_status',
+      outputSchema: { type: 'object' },
       description: 'Inspect orchestration runs on the local Construct daemon: pass run_id for the full record (status, per-task status/executor/output/error), or omit it for a list of recent runs. Fails fast if the daemon is unreachable.',
       inputSchema: {
         type: 'object',
@@ -1312,6 +1407,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'orchestration_readiness',
+      outputSchema: { type: 'object' },
       description: 'Report whether this MCP session has the required Construct orchestration tools attached and reachable now. Returns a pass/fail verdict, typed reasonCode, one next step, required/observed/missing tools, and a redacted diagnostic bundle for support.',
       inputSchema: {
         type: 'object',
@@ -1326,7 +1422,7 @@ const ALL_TOOL_DEFS = [
         },
       },
     },
-];
+].map(withSafetyEnvelope);
 
 // Curated flat core: high-frequency, low-arg tools the orchestrator and the
 // built-in Build/Plan agents actually reach for. Everything else collapses
@@ -1334,21 +1430,28 @@ const ALL_TOOL_DEFS = [
 // host/model; the long tail is reachable, just not front-loaded.
 
 const CORE_TOOL_NAMES = new Set([
-  'orchestration_policy', 'get_skill', 'get_template', 'search_skills', 'knowledge_search',
+  'orchestration_policy', 'orchestration_run', 'get_skill', 'get_template', 'search_skills', 'knowledge_search',
   'memory_search', 'project_context', 'summarize_diff', 'find_tool',
   'author_artifact', 'document_export', 'publish_run', 'artifact_workflow',
   'workflow_invoke', 'triage_recommend', 'orchestration_readiness',
 ]);
 
-const LONG_TAIL_DEFS = ALL_TOOL_DEFS.filter((t) => !CORE_TOOL_NAMES.has(t.name));
 const KNOWN_TOOL_NAMES = new Set(ALL_TOOL_DEFS.map((t) => t.name));
 
+// The core/long-tail split is hand-maintained beside the catalog; a typo in a
+// core name would silently drop a tool from both the flat surface and the gateway
+// enum. Fail fast at module load against the catalog as the single source of truth.
+
+assertCoreSubsetOfCatalog(CORE_TOOL_NAMES, KNOWN_TOOL_NAMES);
+
+const LONG_TAIL_DEFS = ALL_TOOL_DEFS.filter((t) => !CORE_TOOL_NAMES.has(t.name));
+
 // One dispatcher for the long tail. `tool` is constrained to an enum of valid
 // names (≈1 token each — kills hallucinated names, the key small-model lever),
 // and the description carries a compact one-line catalog instead of ~10k of full
 // schemas. Dispatch reuses the same handlers via dispatchToolByName.
 
-const CONSTRUCT_CALL_TOOL = {
+const CONSTRUCT_CALL_TOOL = withSafetyEnvelope({
   name: 'call',
   description:
     'Invoke any non-core Construct tool by name: provide `tool` and `args`. '
@@ -1363,7 +1466,7 @@ const CONSTRUCT_CALL_TOOL = {
     },
     required: ['tool'],
   },
-};
+});
 
 export function exposedTools() {
   return [...ALL_TOOL_DEFS.filter((t) => CORE_TOOL_NAMES.has(t.name)), CONSTRUCT_CALL_TOOL];
@@ -1543,14 +1646,33 @@ async function resolveUnknownToolName(name, args = {}) {
   return { error: `Unknown tool: ${name}. Core tools are flat; invoke any other tool via { name: 'call', arguments: { tool: '<name>', args: {…} } }.` };
 }
 
+// Solo mode never instantiates lib/mcp/broker.mjs's Broker (role/policy-based,
+// wired only for team/enterprise), so the live dispatch path otherwise has no
+// rate bound and no audit trail in the default deployment. windowMs 0 disables,
+// mirroring the CONSTRUCT_MCP_TOOL_TIMEOUT_MS override convention below.
+
+const toolRateLimiter = new ToolRateLimiter({
+  windowMs: (() => {
+    const raw = Number(process.env.CONSTRUCT_MCP_TOOL_RATE_WINDOW_MS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : undefined;
+  })(),
+});
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
+  const callStart = Date.now();
 
   // Extract W3C traceparent from params._meta (SEP-414 propagation). Tracing
   // must never break dispatch — a malformed _meta should not fail the call.
   let parentCtx = {};
   try { parentCtx = await extractTraceContext(request.params?._meta || {}); } catch { /* tracing optional */ }
-  void parentCtx;
+
+  // The `call` gateway's own class would conflate every long-tail tool's budget
+  // into one bucket; rate-limit and audit-log the real underlying tool instead.
+
+  const innerTool = name === 'call' && typeof args?.tool === 'string' && !isGatewayName(args.tool) ? args.tool : null;
+  const auditedTool = innerTool ?? name;
+  const safetyClass = TOOL_SAFETY[auditedTool]?.class ?? 'read';
 
   // Bound every tool call. A tool that stalls (a stuck external extractor, a slow
   // model load, a wedged subprocess) must surface a clean timeout error to the
@@ -1561,38 +1683,84 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return Number.isFinite(raw) && raw >= 0 ? raw : 120_000;
   })();
 
-  const dispatch = (async () => {
-    let result;
-    try {
-      result = await dispatchToolByName(name, args);
-    } catch (err) {
-      result = { error: err.message ?? String(err) };
-    }
-    return result;
-  })();
-
   let toolResult;
-  if (!TOOL_TIMEOUT_MS) {
-    toolResult = await dispatch;
-  } else {
-    let timer;
-    const timeout = new Promise((_, reject) => {
-      timer = setTimeout(
-        () => reject(new Error(`tool ${name} timed out after ${Math.round(TOOL_TIMEOUT_MS / 1000)}s`)),
-        TOOL_TIMEOUT_MS,
-      );
-    });
-    try {
-      toolResult = await Promise.race([dispatch, timeout]);
-    } catch (err) {
-      toolResult = { error: err.message ?? String(err) };
-    } finally {
-      clearTimeout(timer);
-    }
+  try {
+    toolRateLimiter.check(auditedTool, safetyClass);
+
+    // A GenAI span per dispatch records the real underlying tool, its safety
+    // class, and the serialized result size (a token proxy) for every call, so
+    // per-tool calls/latency/errors are measured. Tracing never fails the call:
+    // on any dispatch error the inner catch resolves to an { error } object, so
+    // the span closes OK and the client still gets a structured error payload.
+
+    toolResult = await withGenAiSpan(
+      `execute_tool ${auditedTool}`,
+      { [GenAiAttrs.TOOL_NAME]: auditedTool, 'construct.tool.safety_class': safetyClass, [GenAiAttrs.MCP_METHOD]: 'tools/call' },
+      async (span) => {
+        const dispatch = (async () => {
+          let result;
+          try {
+            result = await dispatchToolByName(name, args);
+          } catch (err) {
+            result = { error: err.message ?? String(err) };
+          }
+          return result;
+        })();
+
+        let out;
+        if (!TOOL_TIMEOUT_MS) {
+          out = await dispatch;
+        } else {
+          let timer;
+          const timeout = new Promise((_, reject) => {
+            timer = setTimeout(
+              () => reject(new Error(`tool ${name} timed out after ${Math.round(TOOL_TIMEOUT_MS / 1000)}s`)),
+              TOOL_TIMEOUT_MS,
+            );
+          });
+          try {
+            out = await Promise.race([dispatch, timeout]);
+          } catch (err) {
+            out = { error: err.message ?? String(err) };
+          } finally {
+            clearTimeout(timer);
+          }
+        }
+
+        const isError = Boolean(out && typeof out === 'object' && 'error' in out);
+        span.setAttribute('construct.tool.result_bytes', JSON.stringify(out ?? null).length);
+        span.setAttribute('construct.tool.ok', !isError);
+        return out;
+      },
+      parentCtx,
+    );
+  } catch (err) {
+    if (err instanceof ToolRateLimited) toolResult = { error: err.message };
+    else throw err;
   }
 
+  // Value-free: tool name and safety class only, never call args or result
+  // content. Logging must never break dispatch, matching the tracing guard above.
+
+  try {
+    appendAuditRecord({
+      ts: new Date().toISOString(),
+      agent: 'mcp-server',
+      tool: auditedTool,
+      target: safetyClass,
+      ok: !(toolResult && typeof toolResult === 'object' && 'error' in toolResult),
+      duration_ms: Date.now() - callStart,
+    });
+  } catch { /* audit trail unavailable must not fail the call */ }
+
+  // Every tool now declares an outputSchema (see withSafetyEnvelope); the MCP SDK
+  // client validates that declaration against the response and rejects a tool
+  // call whose result omits structuredContent. toolResult is always a JSON object
+  // across every dispatch branch, so it satisfies each tool's schema directly.
+
   return {
     content: [{ type: 'text', text: JSON.stringify(toolResult, null, 2) }],
+    structuredContent: toolResult,
   };
 });
 
@@ -1619,6 +1787,12 @@ const argv1Real = (() => { try { return realpathSync(process.argv[1]); } catch {
 if (fileURLToPath(import.meta.url) === argv1Real) {
   console.error('[construct-mcp] server started');
 
+  // Orchestration and provider-backed tools resolve credentials in the server's
+  // own process; wiring the sink at the entry records those op reads on the same
+  // trail as the CLI. Scoped to the server entry so importing this module for a
+  // test never installs the process-global sink.
+  enableSecretAuditTrail();
+
   // A long-running stdio server must survive a single malformed request: a
   // background rejection from one ingest (e.g. a broken docling sidecar that
   // settles late) must not terminate the process and close the client