@hecer/yoke 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.15.0 — 2026-09-09
+
+### Added
+- Add opt-in federated Code Intelligence that composes Graft, Graphify and Serena behind one Yoke-controlled MCP facade with six stable tools for context, symbols, traces, impact and edit workflows.
+- Add pinned backend adapters, explicit coverage/provenance/freshness evidence, content-addressed workspace snapshots and bounded local policy checks.
+- Add isolated edit previews and guarded apply transactions with approval, snapshot freshness, exclusive locking and idempotency checks; Yoke's existing review, verify and commit gates remain authoritative.
+
+### Changed
+- Add `off`, `shadow` and `active` Code Intelligence modes to setup and retrofit. `off` preserves the legacy `codeGraph` path unchanged; `shadow` is read-only; `active` enables preview and approved edits.
+- Keep backend runtimes external and configurable instead of vendoring or silently installing them. Pin the validated integration targets to Graft `0.17.0`, Graphify `0.9.56` and Serena `1.7.1-dev`.
+- Add the [Code Intelligence guide](docs/CODE-INTELLIGENCE.md), including setup, backend requirements, safety boundaries, limitations and the Pi integration note.
+
+### Migration and validation limits
+- No migration is required. Existing projects remain on the legacy path until `yoke setup` or `yoke retrofit` is run with `--code-intelligence=shadow` or `--code-intelligence=active`.
+- Validated with the Code Intelligence contract/coordinator/snapshot/MCP tests, TypeScript lint/build, documentation metadata, package dry run and the facade MCP handshake. The full suite retains one pre-existing provider-process timing failure; it is reproduced independently and is not caused by this release.
+- This release does not claim that every language or backend is available in every environment. Backend failures are surfaced as partial coverage or an explicit unavailable capability, never silently treated as complete evidence.
+
 ## 1.14.0 — 2026-09-09
 
 ### Added

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
 
-<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.14.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
+<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.15.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
 
-<!-- yoke:version:start -->1.14.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->1258<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.15.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->1268<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->34<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini | Qwen | OpenCode | Kilo | Pi<!-- yoke:agents:end -->
 
@@ -17,7 +17,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Tests](https://img.shields.io/badge/tests-1258%20defined-blue.svg)
+![Tests](https://img.shields.io/badge/tests-1268%20defined-blue.svg)
 ![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Qwen%20%7C%20OpenCode%20%7C%20Kilo%20%7C%20Pi-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
@@ -27,7 +27,7 @@
 
 > **TL;DR** — `yoke setup .` asks six questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. Add `--parallel=N` for dependency-aware workers, or declare a reference and add `--quality` for a bounded critic/repair gauntlet. If any blocking gate is red, nothing is committed. Proof lives in `.yoke/proof/<story>/`.
 
-**New in 1.13.0:** first-class [OpenCode, Kilo and Pi integrations](docs/HARNESSES.md), including native headless invocation, provider/model/variant routing, retrofit artifacts, role configuration and provider telemetry. [Qwen Code hardening and explicit DeepSeek/Kimi API model profiles](docs/QWEN-MODEL-SUPPORT.md) remain available. Since 1.10.0, Yoke also includes [dashboard search, filters and period comparisons](docs/DASHBOARD-EVOLUTION.md), [batch task assessments with separate planning models](docs/CAPABILITY-ROUTING.md), and [Windows sandbox preflight and process supervision](docs/WINDOWS-RUNNER-VALIDATION.md). Existing routing settings remain authoritative. See the [changelog](CHANGELOG.md) and the [harness integration guide](docs/HARNESSES.md) for limitations and setup.
+**New in 1.15.0:** federated [Code Intelligence](docs/CODE-INTELLIGENCE.md) composes Graft, Graphify and Serena behind one Yoke-controlled MCP surface, with structural and semantic evidence, content-addressed snapshots, partial-coverage reporting and isolated edit previews. It is opt-in: use `off` for the unchanged legacy path, `shadow` for read-only canaries, or `active` for previews and approved edits. The [1.14.0 dashboard overhaul](docs/DASHBOARD-OVERHAUL.md) and first-class [OpenCode, Kilo and Pi integrations](docs/HARNESSES.md) remain available. See the [changelog](CHANGELOG.md) and [Code Intelligence guide](docs/CODE-INTELLIGENCE.md) for setup and limitations.
 
 OpenCode, Kilo and Pi are real CLI integrations, not bundled runtimes or credentials. OpenCode/Kilo use their JSON headless modes and local MCP configuration; Pi uses JSONL and explicit tool allowlists, but has no native MCP, sub-agent or plan layer. Read the [integration guide](docs/HARNESSES.md) before selecting a permission profile.
 
@@ -208,10 +208,11 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 | `yoke projects add\|list\|remove` | Register a project, list registrations or remove a reference by ID | `0` · `2` invalid/unavailable |
 | `yoke check [dir] [--json] [--requirement=] [--protect [--refresh]]` | Execute acceptance checks or explicitly pin their infrastructure | `0` passed/pinned · `1` failed · `2` unverified/unavailable |
 | `yoke goal set\|run\|resume\|pause\|status\|handoff\|budget [dir]` | Durable objectives, provider handoff, protected checks and checkpoint budgets | run/resume: `0` complete · `1` unfinished · `2` unavailable |
-| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--decision-policy=] [--loop\|--no-loop] [--routing\|--no-routing] [--model-provider=deepseek,kimi]` | Shared setup for all seven harnesses; optional DeepSeek/Kimi API profiles run through Qwen | `0` · `1` invalid setup |
+| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--code-intelligence=off\|shadow\|active] [--decision-policy=] [--loop\|--no-loop] [--routing\|--no-routing] [--model-provider=deepseek,kimi]` | Shared setup for all seven harnesses; optional federated code intelligence and DeepSeek/Kimi API profiles | `0` · `1` invalid setup |
+| `yoke code-intelligence-server [--workspace=] [--mode=off\|shadow\|active]` | Serve the single Yoke-controlled MCP facade for federated code intelligence | `0` · `1` invalid/unavailable |
 | `yoke validate [canonDir]` | Validate the canon (schema, frontmatter, templates) | `0` valid · `1` errors |
 | `yoke new <dir> [--idea=] [--agent=] [--runner=] [--loop]` | Greenfield bootstrap: git init → scaffold → retrofit → context → PRD (drafted from `--idea`) → committed | `0` · `1` usage / non-empty dir / draft failed (scaffold survives) · `2` draft agent unavailable |
-| `yoke retrofit [dir] [--agent=claude,codex,gemini,qwen,opencode,kilo,pi\|all] [--code-graph=graphify\|serena] [--loop]` | Install/update the harness for the selected agents, non-destructively | `0` |
+| `yoke retrofit [dir] [--agent=claude,codex,gemini,qwen,opencode,kilo,pi\|all] [--code-graph=graphify\|serena] [--code-intelligence=off\|shadow\|active] [--loop]` | Install/update the harness for the selected agents, non-destructively | `0` |
 | `yoke prd draft [dir] --idea= [--runner=] [--force]` | Idea → 5–12 stories with testable acceptance criteria | `0` · `1` invalid/guarded · `2` agent unavailable |
 | `yoke prd check [dir]` | PRD lint gate (schema, dependencies, cycles, duplicate ids, acceptance) | `0` valid · `1` violations |
 | `yoke change add\|status [dir] [--idea=]` | Queue a change at any time; the loop turns it into append-only stories at the next safe boundary | `0` · `1` invalid inbox/request |
@@ -852,7 +853,7 @@ Yoke's guardrails are **mechanical, not advisory** — the loop blocks on a dirt
 
 ## 🧠 Choose your code-graph
 
-`yoke retrofit --code-graph=graphify|serena` (default `graphify`, remembered per project). The `yoke-retrofit` skill asks and recommends based on the project.
+`yoke retrofit --code-graph=graphify|serena` (default `graphify`, remembered per project) selects the legacy single graph. For complete code intelligence, enable the federated facade with `yoke retrofit --code-intelligence=active` (or `shadow` for a read-only canary). See the [Code Intelligence guide](docs/CODE-INTELLIGENCE.md).
 
 | | **graphify** | **Serena** |
 |---|---|---|
@@ -862,6 +863,8 @@ Yoke's guardrails are **mechanical, not advisory** — the loop blocks on a dirt
 | Best for | rapid exploration / migration / onboarding | systematic refactoring in typed codebases |
 | Caveat | heuristic edges; static index can go stale | one language server per language |
 
+The federated mode composes both structural and semantic evidence and adds Graphify's architecture/document graph. It exposes one Yoke-controlled MCP surface, content-addressed snapshots, partial-coverage reporting and isolated edit previews; the legacy `codeGraph` setting remains valid and unchanged when code intelligence is `off`.
+
 ## 🪙 Token efficiency
 
 Yoke attacks tokens on two complementary surfaces:
@@ -903,6 +906,7 @@ canon/            # the source of truth — harness-agnostic
   AGENTS.md  skills/  policy/  loop/  tools/  manifest.yaml
 src/
   canon/          # manifest schema + validator (yoke validate)
+  code-intelligence/ # federated MCP facade, adapters, snapshots and guarded edits
   change/         # append-only change inbox · planning · independent coverage review
   retrofit/       # detect · plan · apply · planners (all seven harnesses) · tools
   loop/           # prd · gates · runner · verify · git/worktree · loop · run-command · lock · cleanup
@@ -925,7 +929,7 @@ release provenance.
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (1258 tests)
+npm test          # vitest (1268 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/dist/cli.js

@@ -22,6 +22,7 @@ import { runUpgrade } from './update/upgrade.js';
 import { AGENT_LIST, isSupportedAgent, SUPPORTED_AGENTS } from './agents/catalog.js';
 import { printAudit, runAudit } from './audit/command.js';
 import { runSetup } from './setup/command.js';
+import { runCodeIntelligenceServer } from './code-intelligence/mcp-server.js';
 import { pendingChanges, queueChange } from './change/inbox.js';
 import { answerPendingDecision, answeredDecisionResumeIsValid, clearDecisionResume, decisionProcessingExists, decisionResumeMatchesCurrent, finalizeCommittedDecisionResume, formatPendingDecision, readDecisionResume, readPendingDecision, writeDecisionResume, } from './loop/decision.js';
 export { runRetrofit } from './retrofit/command.js';
@@ -104,6 +105,8 @@ export function parseQualityFlags(args) {
 export function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
+        case 'code-intelligence-server':
+            return runCodeIntelligenceServer(rest).then(() => 0).catch(error => { console.error(`Code intelligence server: ${error.message}`); return 2; });
         case 'setup': {
             const targetDir = rest.find(a => !a.startsWith('-')) ?? '.';
             const valid = [...SUPPORTED_AGENTS];
@@ -130,6 +133,11 @@ export function main(argv) {
                 console.error(`Invalid --code-graph value: ${graphArg}`);
                 return 1;
             }
+            const intelligenceArg = rest.find(a => a.startsWith('--code-intelligence='))?.slice('--code-intelligence='.length);
+            if (intelligenceArg && !['off', 'shadow', 'active'].includes(intelligenceArg)) {
+                console.error(`Invalid --code-intelligence value: ${intelligenceArg}`);
+                return 1;
+            }
             const policyArg = rest.find(a => a.startsWith('--decision-policy='))?.slice('--decision-policy='.length);
             if (policyArg && policyArg !== 'auto' && policyArg !== 'critical') {
                 console.error(`Invalid --decision-policy value: ${policyArg}`);
@@ -152,6 +160,7 @@ export function main(argv) {
                 modelProviders: modelProviders,
                 host: hostArg, agents, runner: runnerArg,
                 codeGraph: graphArg,
+                codeIntelligence: intelligenceArg,
                 loop, routing, decisionPolicy: policyArg,
                 routingStrategy: routingStrategy,
                 routingPreset: rest.includes('--routing-preset'),
@@ -291,7 +300,12 @@ export function main(argv) {
                 console.error(`Invalid --code-graph value: ${cgArg} (expected graphify|serena)`);
                 return 1;
             }
-            return runRetrofit(targetDir, { loop, agents, codeGraph });
+            const ciArg = rest.find(a => a.startsWith('--code-intelligence='))?.slice('--code-intelligence='.length);
+            if (ciArg && !['off', 'shadow', 'active'].includes(ciArg)) {
+                console.error(`Invalid --code-intelligence value: ${ciArg} (expected off|shadow|active)`);
+                return 1;
+            }
+            return runRetrofit(targetDir, { loop, agents, codeGraph, codeIntelligence: ciArg });
         }
         case 'change': {
             const sub = rest[0];
@@ -657,7 +671,7 @@ export function main(argv) {
             return runUpgrade();
         default:
             console.log('Project workflows: yoke check [dir] [--json|--protect] | goal set|run|resume|pause|status|handoff|budget [dir] | projects add|list|remove | dashboard [dir] [--port=N]');
-            console.log(`usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=${AGENT_LIST}|all] [--code-graph=graphify|serena] [--loop] | change <add|status> [dir] | prd <draft|check|assess> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] [--reviewer=<${AGENT_LIST}>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>] | upgrade>`);
+            console.log(`usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=${AGENT_LIST}|all] [--code-graph=graphify|serena] [--code-intelligence=off|shadow|active] [--loop] | change <add|status> [dir] | code-intelligence-server --workspace=<dir> --mode=<mode> | prd <draft|check|assess> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] | design-scan [dir] | flow-smoke [dir] | upgrade>`);
             return cmd ? 1 : 0;
     }
 }

package/dist/code-intelligence/adapters/graft.js

@@ -0,0 +1,11 @@
+import { McpBackendAdapter } from './mcp.js';
+export const GRAFT_VERSION = '0.17.0';
+export function createGraftAdapter(cwd, override) {
+    return new McpBackendAdapter({
+        name: 'graft', version: GRAFT_VERSION, cwd, command: override?.command ?? 'graft', args: override?.args ?? ['mcp'], framing: 'line', semantic: false, documents: false,
+        aliases: { context: 'graft_find_code', trace: 'graft_trace_calls', file: 'graft_file_api', freshness: 'graft_check_freshness', repo_map: 'graft_repo_map' },
+    });
+}
+export function graftCall(kind, args) {
+    return { tool: kind, arguments: args };
+}

package/dist/code-intelligence/adapters/graphify.js

@@ -0,0 +1,8 @@
+import { McpBackendAdapter } from './mcp.js';
+export const GRAPHIFY_VERSION = '0.9.56';
+export function createGraphifyAdapter(cwd, override) {
+    return new McpBackendAdapter({
+        name: 'graphify', version: GRAPHIFY_VERSION, cwd, command: override?.command ?? 'python', args: override?.args ?? ['-m', 'graphify.serve'], framing: 'content-length', semantic: false, documents: true,
+        aliases: { context: 'query_graph', symbol: 'get_node', neighbors: 'get_neighbors', trace: 'shortest_path', impact: 'get_pr_impact' },
+    });
+}

package/dist/code-intelligence/adapters/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './mcp.js';
+export * from './graft.js';
+export * from './graphify.js';
+export * from './serena.js';

package/dist/code-intelligence/adapters/mcp.js

@@ -0,0 +1,37 @@
+import { McpStdioClient } from '../mcp-client.js';
+function valueFromResult(value) {
+    if (!value || typeof value !== 'object')
+        return value;
+    if (value.structuredContent !== undefined)
+        return value.structuredContent;
+    const text = Array.isArray(value.content) ? value.content.find((item) => item?.type === 'text')?.text : undefined;
+    if (typeof text !== 'string')
+        return value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { text };
+    }
+}
+export class McpBackendAdapter {
+    name;
+    version;
+    semantic;
+    documents;
+    client;
+    aliases;
+    constructor(options) {
+        this.name = options.name;
+        this.version = options.version;
+        this.semantic = options.semantic;
+        this.documents = options.documents;
+        this.aliases = options.aliases;
+        this.client = new McpStdioClient(options.command, options.args, options.cwd, options.framing);
+    }
+    async call(request, timeoutMs) {
+        const tool = this.aliases[request.tool] ?? request.tool;
+        return valueFromResult(await this.client.call(tool, request.arguments, timeoutMs));
+    }
+    close() { return this.client.close(); }
+}

package/dist/code-intelligence/adapters/serena.js

@@ -0,0 +1,11 @@
+import { McpBackendAdapter } from './mcp.js';
+export const SERENA_VERSION = '1.7.1-dev';
+export function createSerenaAdapter(cwd, override) {
+    return new McpBackendAdapter({
+        name: 'serena-lsp', version: SERENA_VERSION, cwd, command: override?.command ?? 'serena', args: override?.args ?? ['start-mcp-server', '--project-from-cwd', '--context', 'codex'], framing: 'content-length', semantic: true, documents: false,
+        aliases: {
+            symbol: 'find_symbol', references: 'find_referencing_symbols', implementations: 'find_implementations', overview: 'get_symbols_overview', diagnostics: 'get_diagnostics_for_file',
+            rename: 'rename_symbol', replace_symbol_body: 'replace_symbol_body', insert_before_symbol: 'insert_before_symbol', insert_after_symbol: 'insert_after_symbol', safe_delete: 'safe_delete_symbol',
+        },
+    });
+}

package/dist/code-intelligence/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/code-intelligence/contracts.js

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+export const CodeIntelligenceModeSchema = z.enum(['off', 'shadow', 'active']);
+export const BackendNameSchema = z.enum(['graft', 'graphify', 'serena-lsp', 'serena-jetbrains', 'yoke']);
+export const StatusSchema = z.enum(['success', 'partial', 'blocked', 'error']);
+export const ResolutionSchema = z.enum(['resolved', 'unresolved', 'ambiguous', 'not_applicable']);
+export const FreshnessSchema = z.enum(['current', 'stale', 'unknown']);
+export const ProvenanceSchema = z.object({
+    backend: BackendNameSchema,
+    version: z.string().min(1),
+    source_path: z.string().nullable(),
+    content_hash: z.string().nullable(),
+    byte_range: z.object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() }).nullable(),
+    origin: z.enum(['parser', 'resolver', 'lsp', 'ide', 'llm', 'manual']),
+    resolution: ResolutionSchema,
+    freshness: FreshnessSchema,
+});
+export const CoverageSchema = z.object({
+    backends_requested: z.array(BackendNameSchema),
+    backends_used: z.array(BackendNameSchema),
+    backends_missing: z.array(BackendNameSchema),
+    structural: z.enum(['complete', 'partial', 'unavailable']),
+    semantic: z.enum(['complete', 'partial', 'unavailable']),
+    documents: z.enum(['complete', 'partial', 'unavailable']),
+});
+export const MetricsSchema = z.object({
+    latency_ms: z.number().nonnegative(),
+    result_tokens: z.number().int().nonnegative(),
+    token_count_kind: z.enum(['exact', 'estimated']),
+    returned_bytes: z.number().int().nonnegative(),
+});
+export const ErrorSchema = z.object({
+    code: z.enum([
+        'INVALID_ARGUMENT', 'WORKSPACE_DENIED', 'CAPABILITY_UNAVAILABLE', 'SNAPSHOT_STALE',
+        'AMBIGUOUS_SYMBOL', 'BACKEND_TIMEOUT', 'BACKEND_UNAVAILABLE', 'BUDGET_EXCEEDED',
+        'APPROVAL_REQUIRED', 'PLAN_EXPIRED', 'SCOPE_VIOLATION', 'VALIDATION_FAILED',
+        'WRITE_CONFLICT', 'IDEMPOTENCY_CONFLICT', 'INTERNAL_ERROR',
+    ]),
+    message: z.string().min(1),
+    backend: BackendNameSchema.optional(),
+});
+export const ItemSchema = z.object({
+    item_id: z.string().min(1),
+    kind: z.enum(['symbol', 'code', 'document', 'memory', 'summary']),
+    path: z.string().nullable(),
+    excerpt: z.string().max(12000),
+    evidence_ids: z.array(z.string().min(1)),
+    rank: z.number().nonnegative(),
+});
+export const SymbolSchema = z.object({
+    symbol_id: z.string().min(1),
+    name: z.string().min(1),
+    path: z.string().nullable(),
+    kind: z.string().min(1),
+    signature: z.string().nullable(),
+    evidence_ids: z.array(z.string().min(1)),
+});
+export const ReferenceSchema = z.object({
+    symbol_id: z.string().min(1),
+    path: z.string().nullable(),
+    line: z.number().int().positive().nullable(),
+    excerpt: z.string().max(4000),
+    evidence_ids: z.array(z.string().min(1)),
+});
+export const DiagnosticSchema = z.object({
+    path: z.string().nullable(),
+    line: z.number().int().positive().nullable(),
+    severity: z.enum(['error', 'warning', 'info', 'unknown']),
+    message: z.string().max(4000),
+    evidence_ids: z.array(z.string().min(1)),
+});
+export const EdgeSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    relation: z.enum(['calls', 'references', 'imports', 'implements', 'extends', 'docs', 'rationale_for', 'related_to']),
+    evidence_ids: z.array(z.string().min(1)),
+});
+export const ResponseBaseSchema = z.object({
+    schema_version: z.literal('0.1.0'),
+    request_id: z.string().min(1),
+    workspace_id: z.string().min(1),
+    snapshot_id: z.string().min(1),
+    status: StatusSchema,
+    coverage: CoverageSchema,
+    provenance: z.array(ProvenanceSchema),
+    warnings: z.array(z.string()),
+    metrics: MetricsSchema,
+    artifact_uri: z.string().nullable(),
+    error: ErrorSchema.nullable(),
+});
+const BudgetSchema = z.object({
+    token_budget: z.number().int().min(128).max(16000).default(2400),
+    timeout_ms: z.number().int().min(100).max(60000).default(5000),
+});
+export const ContextInputSchema = z.object({
+    workspace_id: z.string().min(1), query: z.string().min(1).max(20000), snapshot_id: z.string().min(1).optional(),
+    mode: z.enum(['orient', 'locate', 'explain']).default('orient'), paths: z.array(z.string().min(1)).max(32).default([]),
+    include_docs: z.boolean().default(false), ...BudgetSchema.shape,
+});
+export const SymbolInputSchema = z.object({
+    workspace_id: z.string().min(1), snapshot_id: z.string().min(1), symbol_id: z.string().min(1).optional(),
+    query: z.string().min(1).optional(), path: z.string().min(1).optional(),
+    include: z.array(z.enum(['definition', 'references', 'implementations', 'diagnostics'])).default(['definition']), ...BudgetSchema.shape,
+}).refine(v => Boolean(v.symbol_id) !== Boolean(v.query), 'exactly one of symbol_id or query is required');
+export const TraceInputSchema = z.object({
+    workspace_id: z.string().min(1), snapshot_id: z.string().min(1), symbol_id: z.string().min(1),
+    direction: z.enum(['in', 'out']), relations: z.array(z.enum(['calls', 'references', 'imports', 'implements', 'extends'])).min(1),
+    max_depth: z.number().int().min(1).max(6).default(2), max_nodes: z.number().int().min(1).max(2000).default(200),
+    require_resolved: z.boolean().default(false), timeout_ms: z.number().int().min(100).max(60000).default(5000),
+});
+const TargetSchema = z.union([z.object({ path: z.string().min(1) }), z.object({ symbol_id: z.string().min(1) })]);
+export const ImpactInputSchema = z.object({
+    workspace_id: z.string().min(1), snapshot_id: z.string().min(1), targets: z.array(TargetSchema).max(50).optional(),
+    plan_id: z.string().min(1).optional(), include_docs: z.boolean().default(true), require_semantic: z.boolean().default(true),
+    max_depth: z.number().int().min(1).max(6).default(3), timeout_ms: z.number().int().min(100).max(60000).default(10000),
+}).refine(v => Boolean(v.targets) !== Boolean(v.plan_id), 'exactly one of targets or plan_id is required');
+const OperationSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('rename'), symbol_id: z.string().min(1), new_name: z.string().regex(/^[A-Za-z_$][\w$]*$/) }),
+    z.object({ kind: z.literal('replace_symbol_body'), symbol_id: z.string().min(1), content: z.string().max(500000) }),
+    z.object({ kind: z.literal('insert_before_symbol'), symbol_id: z.string().min(1), content: z.string().max(500000) }),
+    z.object({ kind: z.literal('insert_after_symbol'), symbol_id: z.string().min(1), content: z.string().max(500000) }),
+    z.object({ kind: z.literal('safe_delete'), symbol_id: z.string().min(1) }),
+]);
+export const EditPreviewInputSchema = z.object({
+    workspace_id: z.string().min(1), snapshot_id: z.string().min(1), operations: z.array(OperationSchema).min(1).max(20),
+    validation_profile: z.enum(['default', 'extended']), timeout_ms: z.number().int().min(100).max(600000).default(120000),
+});
+export const EditApplyInputSchema = z.object({
+    workspace_id: z.string().min(1), plan_id: z.string().min(1), expected_snapshot_id: z.string().min(1),
+    idempotency_key: z.string().min(8).max(128),
+});
+export const TOOL_NAMES = ['code_context', 'code_symbol', 'code_trace', 'code_impact', 'code_edit_preview', 'code_edit_apply'];
+export const TOOL_DEFINITIONS = TOOL_NAMES.map(name => ({
+    name,
+    description: `Yoke-controlled ${name.replace('code_', '').replace('_', ' ')} with snapshot-bound evidence.`,
+    inputSchema: { type: 'object', additionalProperties: false },
+    annotations: { openWorldHint: false, destructiveHint: name === 'code_edit_apply', readOnlyHint: name !== 'code_edit_preview' && name !== 'code_edit_apply', idempotentHint: name !== 'code_edit_apply' },
+}));