@moretea-labs/forge 1.8.1 → 1.8.2

package/adapters/mcp/access-mode.ts

@@ -6,12 +6,6 @@ import {
   type McpLocalConfig,
   writeMcpServiceLocalConfig,
 } from './auth';
-import type { McpToolset } from './types';
-import {
-  migrateControllerToolsetConfig,
-  normalizeConfiguredMcpToolset,
-  resolveControllerToolsetSelection,
-} from './toolset-selection';
 import {
   isAccessMode,
   type AccessMode,
@@ -20,28 +14,23 @@ import {
 export type ControllerAccessConfigSource =
   | 'controller_home.access_mode'
   | 'repo_local_fallback.access_mode'
-  | 'controller_home.legacy_toolset'
-  | 'repo_local_fallback.legacy_toolset'
   | 'default';
 
 export interface ControllerAccessState {
   configuredAccessMode: AccessMode;
   effectiveAccessMode: AccessMode;
-  /** Selected schema profile; access mode never changes this value. */
-  effectiveToolset: McpToolset;
+  /** The complete MCP capability registry is always available. */
+  effectiveToolset: 'full';
   source: ControllerAccessConfigSource;
   lastAppliedAt?: string;
   exposureRevision: number;
   configPathSource: 'controller_home' | 'repo_local_fallback' | 'default';
-  legacyToolset?: McpToolset;
   schemaStableAcrossAccessModes: true;
 }
 
 export interface ResolveControllerAccessStateInput {
   controllerHome: string;
   repoRoot?: string;
-  toolsetOverride?: McpToolset;
-  toolsetLocked?: boolean;
 }
 
 export interface PersistControllerAccessModeResult {
@@ -50,21 +39,22 @@ export interface PersistControllerAccessModeResult {
   state: ControllerAccessState;
 }
 
-export function accessModeForLegacyToolset(toolset: McpToolset): AccessMode {
-  return toolset === 'core' ? 'request' : 'full_access';
-}
-
-/** Retained for compatibility only; access mode no longer changes schema. */
-export function legacyToolsetForAccessMode(_mode: AccessMode): McpToolset {
-  return 'core';
-}
-
 function configLocation(controllerHome: string, repoRoot?: string): 'controller_home' | 'repo_local_fallback' | 'default' {
   if (existsSync(mcpControllerHomeLocalConfigPath(controllerHome))) return 'controller_home';
   if (repoRoot && existsSync(mcpLocalConfigPath(repoRoot))) return 'repo_local_fallback';
   return 'default';
 }
 
+/** One-way interpretation of old persisted permissions, not a toolset selector. */
+export function configuredControllerAccessMode(config: McpLocalConfig | null | undefined): AccessMode {
+  if (isAccessMode(config?.accessMode)) return config.accessMode;
+  // Historically, core without an explicit accessMode meant Request, not Full Access.
+  // Preserve that permission until the next canonical config write retires toolset.
+  return (config as { toolset?: unknown } | null | undefined)?.toolset === 'core'
+    ? 'request'
+    : 'full_access';
+}
+
 function normalizedRevision(value: unknown): number {
   if (typeof value !== 'number' || !Number.isFinite(value)) return 0;
   return Math.max(0, Math.trunc(value));
@@ -77,27 +67,18 @@ export function resolveControllerAccessState(input: ResolveControllerAccessState
     ? config.accessModeUpdatedAt
     : undefined;
   const exposureRevision = normalizedRevision(config?.accessModeRevision);
-  const rawLegacyToolset = normalizeConfiguredMcpToolset(config?.toolset);
-  const selectedToolset = resolveControllerToolsetSelection(config, input.toolsetOverride);
-  const configuredAccessMode = isAccessMode(config?.accessMode)
-    ? config.accessMode
-    : rawLegacyToolset
-      ? accessModeForLegacyToolset(rawLegacyToolset)
-      : 'full_access';
+  const configuredAccessMode = configuredControllerAccessMode(config);
   const source: ControllerAccessConfigSource = isAccessMode(config?.accessMode)
     ? (location === 'controller_home' ? 'controller_home.access_mode' : 'repo_local_fallback.access_mode')
-    : rawLegacyToolset
-      ? (location === 'controller_home' ? 'controller_home.legacy_toolset' : 'repo_local_fallback.legacy_toolset')
-      : 'default';
+    : 'default';
   return {
     configuredAccessMode,
     effectiveAccessMode: configuredAccessMode,
-    effectiveToolset: selectedToolset.toolset,
+    effectiveToolset: 'full',
     source,
     lastAppliedAt,
     exposureRevision,
     configPathSource: location,
-    legacyToolset: rawLegacyToolset,
     schemaStableAcrossAccessModes: true,
   };
 }
@@ -110,7 +91,6 @@ export function persistControllerAccessMode(
   const existing = loadMcpServiceLocalConfig(controllerHome, repoRoot) ?? {};
   const accessModeUpdatedAt = new Date().toISOString();
   const accessModeRevision = normalizedRevision(existing.accessModeRevision) + 1;
-  const migratedToolset = migrateControllerToolsetConfig(existing);
   const config: McpLocalConfig = {
     ...existing,
     version: Math.max(existing.version ?? 1, 2),
@@ -118,11 +98,10 @@ export function persistControllerAccessMode(
     accessMode: mode,
     accessModeUpdatedAt,
     accessModeRevision,
-    // Access changes preserve an explicit profile and migrate the old implicit
-    // Advanced label to Core; they never expand or shrink schema themselves.
-    toolset: migratedToolset.toolset,
-    toolsetExplicit: migratedToolset.toolsetExplicit,
   };
+  // Stored legacy profile values are not part of the one-surface contract.
+  delete (config as Record<string, unknown>).toolset;
+  delete (config as Record<string, unknown>).toolsetExplicit;
   const configPath = writeMcpServiceLocalConfig(controllerHome, config);
   return {
     configPath,

package/adapters/mcp/auth.ts

@@ -3,7 +3,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { resolveControllerHome } from '../../src/cli/repositories/controller-home';
 import type { AccessMode } from '../../src/runtime/control-plane/governance/access-policy';
-import type { McpToolset } from './types';
 
 export interface McpLocalConfig {
   version?: number;
@@ -29,9 +28,6 @@ export interface McpLocalConfig {
     localEndpoint?: string;
   };
   profile?: string;
-  toolset?: 'facade' | 'core' | 'advanced' | 'full';
-  /** Compatibility marker retained for previously persisted toolset choices. */
-  toolsetExplicit?: boolean;
   accessMode?: AccessMode;
   accessModeUpdatedAt?: string;
   accessModeRevision?: number;
@@ -90,10 +86,10 @@ export interface McpRuntimeState {
     forgeVersion?: string;
     toolSurfaceFingerprint?: string;
     runtimeToolSurfaceFingerprint?: string;
-    toolset?: 'facade' | 'core' | 'advanced' | 'full';
+    toolset?: 'full';
     configuredAccessMode?: AccessMode;
     effectiveAccessMode?: AccessMode;
-    effectiveToolset?: McpToolset;
+    effectiveToolset?: 'full';
     accessModeSource?: string;
     accessModeLastAppliedAt?: string;
     exposureRevision?: number;

package/adapters/mcp/instructions.ts

@@ -12,13 +12,13 @@ export function mcpServerInstructions(profile: McpProfileName): string {
       'Use the shortest valid execution path. Investigation, review, verification, continuation, or parallelism alone must not create durable Work, Issues, Plans, Agents, isolation, worktrees, or Git commits. Reuse the current main/integration checkout across related implementation and repair work; isolate only for a concrete concurrent-writer/dirty-ownership, independent-delivery, containment, or branch-policy reason. Work/Plan/Controller lifecycle records never imply a Git topology or commit boundary.',
       'Engineering receipts are optional structured context: never invent Project Contract, Context Closure, Product DoD, design, critique, semantic-tool, validation, journey, or review receipt ids from prose. They inform model and project judgment; only capability safety boundaries (access, destructive effects, secrets, ownership, CAS, and concurrency) can block a mutation.',
       'Context Closure returned by rh_context.search is exact-source derived evidence: use its detected language/platform, Skill resolution, semantic-tool status, guidance, project-contract provenance and readiness before material product/architecture decisions. Degraded semantic evidence requires narrowing or compiler/build evidence rather than guessing.',
-      'For bounded implementation, start with rh_context(operation=search, retrieval_mode=implementation) as the default code retrieval router when the exact path is unknown, then repeat it with exact paths, symbols, tests, relationships, or impact domains whenever more evidence can materially improve correctness. Its current raw snippets and file SHA identities are valid implementation evidence; ChatGPT alone decides semantic sufficiency. For cross-cutting state/time/schema/cache/API/event/concurrency changes, ChatGPT should select relevant impact_domains so Forge expands those evidence dimensions mechanically; Forge never infers that the selected domains are semantically complete. Use retrieval_mode=plan|debug|review when the task intentionally needs a broader evidence surface. Do not fall back to shell grep unless retrieval is unavailable or raw Git semantics are explicitly needed. The low-level search_repository handler is compatibility/internal surface, not a second default search path. Prefer repository_command_execute for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration. Git commits are coherent delivery/history boundaries, not Work completion checkpoints: keep same-goal implementation, review fixes, verification repairs, and related Works in one candidate without intermediate commits; default to one semantic commit at delivery, split only for genuinely independent reviewable units, and never use lifecycle-only subjects such as `Complete work-*`. Ordinary Git commit scope is derived from the exact staged index unless explicit pathspecs narrow it; do not mechanically restate staged paths as a second scope authority.',
+      'For bounded implementation, the model selects rh_context semantic retrieval, execute_command terminal search, or exact file reads according to the evidence required; no mandatory retrieval router or tool sequence is imposed. If rh_context is used, follow with exact paths, symbols, tests, relationships, or impact domains only when that materially improves correctness. Its current raw snippets and file SHA identities are valid implementation evidence; ChatGPT alone decides semantic sufficiency. For cross-cutting state/time/schema/cache/API/event/concurrency changes, ChatGPT should select relevant impact_domains so Forge expands those evidence dimensions mechanically; Forge never infers that the selected domains are semantically complete. Use retrieval_mode=plan|debug|review when the task intentionally needs a broader evidence surface. ChatGPT chooses semantic source retrieval or direct terminal search according to what the task actually requires; Forge does not rank tools as a workflow policy. The low-level search_repository handler is an internal compatibility surface. Use execute_command for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration. Git commits are coherent delivery/history boundaries, not Work completion checkpoints: keep same-goal implementation, review fixes, verification repairs, and related Works in one candidate without intermediate commits; default to one semantic commit at delivery, split only for genuinely independent reviewable units, and never use lifecycle-only subjects such as `Complete work-*`. Ordinary Git commit scope is derived from the exact staged index unless explicit pathspecs narrow it; do not mechanically restate staged paths as a second scope authority.',
       'Do not preflight unrelated Git history, prior Work, plugins, permissions, TCC, browser mode, maintenance, or recovery state. Inspect them only when the requested operation depends on them or a real failure points there.',
       'Self-learning is model-driven, not phrase-driven. Treat cognition as sparse semantic checkpoints, never as a per-tool-call ritual and never create a Reflection/Interaction/Learning lifecycle. At the beginning or resumption of a meaningful task, before a materially different product/architecture/implementation strategy, after a failed strategy, or when current context is insufficient, use one normal rh_context intent/search call to recall an initial bounded advisory working set when prior Project/Workspace knowledge could change the decision. Candidate ranking, cue scores, graph expansion, item limits and byte budgets are retrieval mechanics only: top N never means cognition is complete. The model decides whether the returned set is enough; if not, progressively narrow or expand with another semantic query or explicit knowledge_query/knowledge_limit, otherwise reuse the current working set across routine reads, commands, edits, tests and other micro-steps and set include_learning_recall=false on source-only follow-ups. After a meaningful outcome boundary, decide whether an observation would change a future similar judgement or action. Emit zero learning when it would not. For ordinary successful work, prefer attaching one optional cognition_settlement to the successful tool call that closes that meaningful outcome; it can carry model-authored learning_signals and exact-memory learning_feedback and Forge settles them mechanically after the primary tool result. Do not attach cognition_settlement to routine micro-steps merely because the field exists. Use rh_work learning_record/learning_feedback when there is no natural successful tool boundary, when an explicit standalone learning action is clearer, or when a selected learning batch exceeds one transport envelope. User corrections, discovered root causes, successful shorter paths, review reversals, stable architecture/product/UX patterns and execution outcomes may all become learning when the model judges them reusable. Distill observations into semantic deltas rather than copying source prose: prefer a Project-specific lesson about how to judge/do the work, and write Workspace guidance only when the model explicitly judges the abstraction genuinely cross-project. Forge never decides that from kind, keywords, failure count, repetition count, confidence threshold, or execution codes. learning_signals kind is descriptive open vocabulary; the per-call array bound is only a transport envelope, not an interaction quota, so submit further learning_record batches when the model selected more reusable knowledge than one envelope carries. Forge may associate/consolidate representations and usage mechanically but must not invent a higher-level lesson or cross-scope generalization. Work-bound Controller rounds keep assistant_context_usage as the exact used/rejected feedback channel. Outside Work, do not manufacture a usage lifecycle merely to count feedback. When recalled memory materially helps or is rejected, use learning_feedback with its exact memory address and model-authored irrelevant/stale/contradicted classification. A new correction/contradiction/other learning signal requires genuinely new reusable semantic knowledge, not merely that an old memory was used.',
       'Minimize mechanically redundant MCP round trips. For an ongoing Forge-controlled task, prefer one rh_status(summary) as the initial controller snapshot: it includes bounded readiness, repository identity, top active Work, active Plans, and pending handoffs. Do not immediately follow it with rh_work(plan_list) or rh_context(list/get) unless the next decision needs details that the snapshot does not contain. Use rh_context(work_id=..., detail_level=summary) for one Work, and request detail/raw or capability hydration only when that extra evidence can change the decision.',
       'Run independent reads, searches, diagnostics, checks, repositories, checkouts, and tasks concurrently by default. Serialize only on a real dependency or Resource Claim conflict, and reuse existing projections, process handles, and check evidence instead of repeating successful observations.',
       'Validation must be proportional to the change: cheap patch-safety checks belong to every coherent edit batch, focused tests run after that batch is stable, and expensive full-suite checks belong at candidate/release or explicitly high-risk boundaries. When a Direct Edit batch is stable, repository_safe_patch_apply may receive explicit check_ids to start revision-bound validation; omit check_ids during intermediate edits. Long checks return managed Processes: continue independent read/review work. Do not call process_wait while useful independent work remains. Use process_get only when a non-blocking observation can change the next decision; when the exact check result becomes a dependency, attach with process_wait (or validation_only with the returned edit-session/validation ids). An attach is transport-bounded: if it returns a running handle, resume useful work and attach again only at a later real dependency boundary, never as periodic polling. Do not perform maintenance or deep runtime diagnosis before ordinary work unless execution is actually blocked.',
-      'repository_safe_patch_apply returns bounded edit-session diff evidence for semantic review. Review that evidence directly instead of issuing a mandatory follow-up diff/status call; expand it only when truncated or semantically ambiguous. Its typed operation contract is strict: use type=create only for a path that does not exist, and use write/replace/insert/prepend/append/delete only for existing targets; never reinterpret a missing write target as create. Whole-file source replacement is valid when it is an explicit scoped write against the exact expected file SHA/fingerprint; stale-source and dirty-ownership fences must remain authoritative. Do not bypass those fences with arbitrary shell redirection merely because a deterministic rewrite is convenient. After a bounded successful change, finish the requested delivery directly. Avoid additional investigation whose result cannot change implementation or acceptance, and do not invoke hidden atomic compatibility tools merely because they exist in the full profile.',
+      'repository_safe_patch_apply returns bounded edit-session diff evidence for semantic review. Review that evidence directly instead of issuing a mandatory follow-up diff/status call; expand it only when truncated or semantically ambiguous. Its typed operation contract is strict: use type=create only for a path that does not exist, and use write/replace/insert/prepend/append/delete only for existing targets; never reinterpret a missing write target as create. Whole-file source replacement is valid when it is an explicit scoped write against the exact expected file SHA/fingerprint; stale-source and dirty-ownership fences must remain authoritative. Do not bypass those fences with arbitrary shell redirection merely because a deterministic rewrite is convenient. After a bounded successful change, finish the requested delivery directly. Avoid additional investigation whose result cannot change implementation or acceptance, and do not invoke redundant atomic compatibility tools merely because they remain registered.',
     ].join(' ');
   }
   if (profile === 'orchestrator') {

package/adapters/mcp/multi-repository.ts

@@ -2,8 +2,7 @@ import { loadMcpLocalConfig, loadMcpServiceLocalConfig } from './auth';
 import { getMcpPolicy, parseMcpProfile } from './policy';
 import { buildMcpToolDefinitions, callMcpTool, type CallToolResult, type McpToolContext, type McpToolDefinition } from './tool-mapping/tools';
 import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENT_TIMEOUT_MS, normalizeAgentTimeoutMs } from '../../src/cli/controller/runtime-config';
-import type { McpAgentRunnerName, McpToolset } from './types';
-import { configuredControllerToolset } from './toolset-selection';
+import type { McpAgentRunnerName } from './types';
 import { realpathSync } from 'fs';
 import { resolve } from 'path';
 import { ensureRepoPreferredControllerHome } from '../../src/cli/repositories/controller-home';
@@ -28,7 +27,6 @@ export interface McpServerOptions {
   devRunnerAgents?: string;
   devRunnerTimeoutMs?: number;
   devRunnerMaxTimeoutMs?: number;
-  toolset?: McpToolset | string;
   sessionId?: string;
   principalId?: string;
   controllerType?: McpToolContext['controllerType'];
@@ -42,8 +40,7 @@ export interface McpServerOptions {
 export interface MultiRepositoryMcpToolContext extends McpToolContext {
   controllerHome: string;
   explicitRepository?: RepositoryRecord;
-  toolset: McpToolset;
-  toolsetLocked: boolean;
+  toolset: 'full';
   runtimeSourceRoot?: string;
 }
 
@@ -66,14 +63,6 @@ const REPOSITORY_LOCKED_TOOLS = new Set([
 ]);
 
 
-export function parseMcpToolset(value: unknown, profile: string): McpToolset {
-  if (profile !== 'controller') return 'full';
-  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
-  if (!normalized) return 'advanced';
-  if (normalized === 'facade' || normalized === 'core' || normalized === 'advanced' || normalized === 'full') return normalized;
-  throw new Error(`invalid MCP toolset "${String(value)}" (expected: facade, core, advanced, or full)`);
-}
-
 function repositoryForExplicitPath(path: string, controllerHome: string): RepositoryRecord | undefined {
   const selectedPath = (() => {
     try { return realpathSync(path); } catch { return resolve(path); }
@@ -284,8 +273,7 @@ export function repositoryScopedToolArgs(
   // checkout after validating the authenticated principal instead of inheriting
   // the repository's currently active checkout.
   const workOwnedCheckoutResolution = [
-    'repository_command_preview',
-    'repository_command_execute',
+    'execute_command',
     'repository_safe_patch_apply',
   ].includes(name)
     && typeof input.work_id === 'string'
@@ -333,24 +321,14 @@ export function createMcpToolContext(opts: McpServerOptions): MultiRepositoryMcp
     : undefined;
   const policyRoot = explicitRepository?.canonicalRoot ?? controllerHome;
   const policy = runtimePolicy(policyRoot, { ...opts, controllerHome });
-  const config = policy.profile === 'controller'
-    ? loadMcpServiceLocalConfig(controllerHome, explicitRepository?.canonicalRoot)
-    : loadMcpLocalConfig(policyRoot);
-  const toolsetOverride = opts.toolset ?? process.env.FORGE_MCP_TOOLSET;
-  const configuredToolset = policy.profile === 'controller'
-    ? configuredControllerToolset(config)
-    : config?.toolset;
-  const toolset = parseMcpToolset(
-    toolsetOverride ?? configuredToolset,
-    policy.profile,
-  );
+  // All Forge capabilities share one public MCP tool registry.
+  // Host authorization remains independent of tool discovery.
   return {
     controllerHome,
     explicitRepository,
     repoRoot: policyRoot,
     policy,
-    toolset,
-    toolsetLocked: toolsetOverride !== undefined || configuredToolset !== undefined,
+    toolset: 'full',
     enableChatgptBrowser: opts.enableChatgptBrowser === true,
     sessionId: opts.sessionId,
     principalId: opts.principalId,
@@ -402,6 +380,7 @@ export async function callMultiRepositoryTool(
       controllerInstanceId: ctx.controllerInstanceId,
       repoId: repository.repoId,
       checkoutId: repository.activeCheckoutId,
+      publishedToolNames: ctx.publishedToolNames,
     };
     const invoke = async () => await callMcpTool(scopedContext, name, scopedArgs) as ToolResult;
     const result = REPOSITORY_LOCKED_TOOLS.has(name)

package/adapters/mcp/runtime-gateway/context-adapter.ts

@@ -1,20 +1,20 @@
 import { createHash } from "crypto";
-import { existsSync } from "fs";
-import { join } from "path";
 import { defaultSemanticProviderRegistry, type SemanticNavigationKind, type SemanticNavigationRequest } from "../../../src/runtime/context/semantic-navigation";
+import { isIncidentalSemanticDependencyProbe } from "../../../src/runtime/context/semantic-navigation-contract";
 import { buildContextClosureReceipt } from "../../../src/runtime/context/context-closure";
-import { codegraphRepositoryCacheRoot } from "../../../src/runtime/context/codegraph-cache-boundary";
+import { readWorkHandle } from "../../../src/runtime/control-plane/execution/work-handle-store";
 import type { MultiRepositoryMcpToolContext } from "../multi-repository";
 import { result } from "./result-adapter";
 import { boundedRuntimeResult } from "./bounded-result-runtime";
 import { selected } from "./shared-adapter";
 import { resolveMcpPath } from "../paths";
 import { freshGitIdentity } from "../../../src/cli/repository/inspector";
-import { repositoryCheckoutLifecycle, repositorySummary, resolveRepositorySelection } from "../../../src/cli/repositories/registry";
+import { repositorySummary, resolveRepositorySelection } from "../../../src/cli/repositories/registry";
 import { getExecutionJob, listExecutionJobs } from "../../../src/runtime/execution/jobs/store";
 import { isManagedProcessActive, listProcessRecords, listRecoverableProcessRecords, processRuntimeResourceDiagnostics } from "../../../src/runtime/execution/process-runtime";
 import { CONTROLLER_CONTEXT_IMPACT_DOMAINS, type ControllerContextImpactDomain } from "../../../src/cli/controller/context/types";
 import { buildControllerContextPackInSidecar } from "../../../src/runtime/context/context-pack-process";
+import { isCodeShapedTerm } from "../../../src/cli/controller/context/query-planning";
 import { listControllerChecks } from "../../../src/cli/controller/check-runner";
 import { getAssistantPluginManifest, getControllerPluginManifest, listAssistantPluginManifests, listControllerPluginManifests } from "../../../src/runtime/plugins/store";
 import { allowedFacadeOperations, buildFacadeResult, listCapabilityDescriptors, getCapabilityDescriptor, getCoreCapabilityExecutionSchema, getPluginActionCapabilitySchema, searchCapabilityDescriptors, summarizeCapabilityGroups, listHandoffAttentionItems, listHandoffItems, normalizeCheckIds, summarizeHandoffItem, buildWorkContinuationSnapshot, getPlanContract, planSemanticView, FACADE_TOOLS } from "../../../src/runtime/control-plane/facade";
@@ -280,6 +280,7 @@ interface RhContextSemanticNavigationProjection {
   providers: unknown[];
   policyDeniedLocations: number;
   policyDeniedReads: number;
+  materialPolicyDeniedReads: number;
   policyDeniedReadSamples: string[];
   requestTruncated: boolean;
   freshness: 'not_requested' | 'changed_during_query' | 'current_at_query';
@@ -300,6 +301,7 @@ async function rhContextSemanticNavigation(
   let anyLocationTruncated = false;
   let policyDeniedLocations = 0;
   let policyDeniedReads = 0;
+  let materialPolicyDeniedReads = 0;
   const policyDeniedReadSamples = new Set<string>();
   const semanticAccessScope = createHash('sha256')
     .update(JSON.stringify({ profile: policy.profile, readGlobs: policy.readGlobs, denyGlobs: policy.denyGlobs }))
@@ -347,6 +349,7 @@ async function rhContextSemanticNavigation(
     const decision = resolveMcpPath(repoRoot, relativePath, policy, 'read');
     if (decision.ok) return true;
     policyDeniedReads += 1;
+    if (!isIncidentalSemanticDependencyProbe(relativePath)) materialPolicyDeniedReads += 1;
     if (policyDeniedReadSamples.size < 20) policyDeniedReadSamples.add(relativePath);
     return false;
   };
@@ -372,6 +375,7 @@ async function rhContextSemanticNavigation(
     const semantic = outcome.result;
     const sidecarDeniedReads = Math.max(0, Number(semantic.policyDeniedReads ?? 0));
     policyDeniedReads += sidecarDeniedReads;
+    materialPolicyDeniedReads += Math.max(0, Number(semantic.materialPolicyDeniedReads ?? sidecarDeniedReads));
     const sidecarDeniedSamples = semantic.details?.policyDeniedReadSamples;
     if (Array.isArray(sidecarDeniedSamples)) {
       for (const sample of sidecarDeniedSamples) {
@@ -385,6 +389,11 @@ async function rhContextSemanticNavigation(
       policyDeniedLocations += 1;
       return false;
     });
+    // With no resolved requested relationship, even dependency-only denied reads
+    // may conceal material evidence. Preserve admission blocking for this case.
+    if (allowedLocations.length === 0 && sidecarDeniedReads > 0 && Number(semantic.materialPolicyDeniedReads ?? sidecarDeniedReads) === 0) {
+      materialPolicyDeniedReads += sidecarDeniedReads;
+    }
     const truncated = allowedLocations.length > RH_CONTEXT_SEMANTIC_LOCATION_LIMIT;
     anyLocationTruncated ||= truncated;
     results.push({
@@ -398,6 +407,7 @@ async function rhContextSemanticNavigation(
       returnedLocations: Math.min(allowedLocations.length, RH_CONTEXT_SEMANTIC_LOCATION_LIMIT),
       truncated,
       policyDeniedReads: semantic.policyDeniedReads ?? 0,
+      materialPolicyDeniedReads: semantic.materialPolicyDeniedReads ?? semantic.policyDeniedReads ?? 0,
       ...(semantic.details ?? {}),
     });
   }
@@ -426,7 +436,7 @@ async function rhContextSemanticNavigation(
   }
 
   const requestTruncated = raw.length > RH_CONTEXT_SEMANTIC_QUERY_LIMIT;
-  const incomplete = requestTruncated || anyLocationTruncated || policyDeniedLocations > 0 || policyDeniedReads > 0 || errors.length > 0 || sourceChangedDuringQuery;
+  const incomplete = requestTruncated || anyLocationTruncated || policyDeniedLocations > 0 || materialPolicyDeniedReads > 0 || errors.length > 0 || sourceChangedDuringQuery;
   const languages = new Set(results.map((entry) => String(entry.language ?? '')).filter(Boolean));
   const singleLanguage = languages.size === 1 ? [...languages][0] : undefined;
   const scope = singleLanguage === 'typescript'
@@ -446,6 +456,7 @@ async function rhContextSemanticNavigation(
     providers: defaultSemanticProviderRegistry.list(),
     policyDeniedLocations,
     policyDeniedReads,
+    materialPolicyDeniedReads,
     policyDeniedReadSamples: Array.from(policyDeniedReadSamples),
     requestTruncated,
     freshness: raw.length === 0 ? 'not_requested' : sourceChangedDuringQuery ? 'changed_during_query' : 'current_at_query',
@@ -467,35 +478,59 @@ async function rhContextSemanticNavigation(
   };
 }
 
-function codegraphIndexExists(controllerHome: string, root: string): boolean {
-  return existsSync(join(codegraphRepositoryCacheRoot(controllerHome, root), 'codegraph.db'))
-    || existsSync(join(root, '.codegraph', 'codegraph.db'));
-}
-
 /**
- * Managed worktrees borrow one repository baseline CodeGraph from a non-worktree
- * checkout. Dirty worktree bytes remain a raw/lexical overlay; they never create
- * a second structural-index authority merely because execution is isolated.
- * Repo-local `.codegraph` is retained only as a legacy-readable fallback.
+ * Work-specific source evidence uses the exact registered physical placement.
+ * Work semantic identity stays in Kernel; Repository Registry owns checkout
+ * resolution. This projection neither creates source state nor chooses a
+ * different checkout when the exact Work target has disappeared.
  */
-export function resolveStructuralIndexRoot(
-  controllerHome: string,
-  repository: ReturnType<typeof resolveRepositorySelection>,
-): string | undefined {
-  const active = repository.checkouts.find((checkout) => checkout.checkoutId === repository.activeCheckoutId);
-  const nonWorktreeRoots = repository.checkouts
-    .filter((checkout) => checkout.checkoutId !== repository.activeCheckoutId && checkout.worktree !== true && repositoryCheckoutLifecycle(checkout) === 'active')
-    .map((checkout) => checkout.canonicalRoot);
-  const candidates = active?.worktree === true
-    ? [...nonWorktreeRoots, repository.canonicalRoot]
-    : [repository.canonicalRoot, ...nonWorktreeRoots];
-  return [...new Set(candidates)].find((root) => codegraphIndexExists(controllerHome, root));
+function selectContextSourceRepository(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+  operation: string,
+): ReturnType<typeof selected> {
+  const workId = operation === 'search' && typeof args.query === 'string' && args.query.trim()
+    && typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  if (!workId) return selected(ctx, args);
+  const repository = selected(ctx, { ...args, checkout_id: undefined });
+  const work = getWorkContract({ controllerHome: ctx.controllerHome, repoId: repository.repoId }, workId);
+  if (!work) throw new Error(`CONTEXT_WORK_NOT_FOUND: ${workId}`);
+  if (work.repoId && work.repoId !== repository.repoId) {
+    throw new Error(`CONTEXT_WORK_REPOSITORY_MISMATCH: ${workId}`);
+  }
+  const handle = readWorkHandle(ctx.controllerHome, repository.repoId, workId);
+  const workCheckoutId = handle?.checkoutId?.trim()
+    || work.executionPlacement?.checkoutId?.trim()
+    || work.checkoutId?.trim();
+  // Pure semantic Work has no physical source. Keep explicitly elected
+  // repository context for this case instead of inventing source placement.
+  if (!workCheckoutId) return selected(ctx, args);
+  const requestedCheckoutId = typeof args.checkout_id === 'string' ? args.checkout_id.trim() : '';
+  if (requestedCheckoutId && requestedCheckoutId !== workCheckoutId) {
+    throw new Error(`CONTEXT_WORK_CHECKOUT_MISMATCH: ${workId}`);
+  }
+  if (handle?.state === 'cleaned' || handle?.state === 'failed') {
+    throw new Error(`CONTEXT_WORK_CHECKOUT_RETIRED: ${workId}`);
+  }
+  let selectedCheckout: ReturnType<typeof selected>;
+  try {
+    selectedCheckout = selected(ctx, { ...args, repo_id: repository.repoId, checkout_id: workCheckoutId });
+  } catch {
+    throw new Error(`CONTEXT_WORK_CHECKOUT_UNAVAILABLE: ${workId}`);
+  }
+  if (selectedCheckout.activeCheckoutId !== workCheckoutId) {
+    throw new Error(`CONTEXT_WORK_CHECKOUT_MISMATCH: ${workId}`);
+  }
+  if (handle?.expectedHead && freshGitIdentity(selectedCheckout.canonicalRoot).head !== handle.expectedHead) {
+    throw new Error(`CONTEXT_WORK_SOURCE_REVISION_MISMATCH: ${workId}`);
+  }
+  return selectedCheckout;
 }
 
 export async function callContextAdapter(ctx: MultiRepositoryMcpToolContext, name: string, args: Record<string, unknown>): Promise<CallToolResult | undefined> {
   if (name !== 'rh_context') return undefined;
-    const repository = selected(ctx, args);
     const operation = String(args.operation ?? 'get');
+    const repository = selectContextSourceRepository(ctx, args, operation);
     if (!allowedFacadeOperations('rh_context').includes(operation)) {
       return invalidFacadeOperation('rh_context', operation);
     }
@@ -543,11 +578,10 @@ export async function callContextAdapter(ctx: MultiRepositoryMcpToolContext, nam
         : 'implementation';
       const impactDomains = list(args.impact_domains)
         .filter((domain): domain is ControllerContextImpactDomain => CONTROLLER_CONTEXT_IMPACT_DOMAINS.includes(domain as ControllerContextImpactDomain));
+      // CodeGraph is opt-in. Ordinary source location never starts a graph index.
       const structuralContext = args.structural_context === 'off' || args.structural_context === 'auto' || args.structural_context === 'required'
         ? args.structural_context
-        : retrievalMode === 'plan' || retrievalMode === 'debug'
-          ? 'required'
-          : 'auto';
+        : 'off';
       const requestedCheckIds = list(args.requested_check_ids);
       // Source retrieval is the default Context responsibility. Check
       // readiness is only meaningful when the controller has named the
@@ -562,23 +596,26 @@ export async function callContextAdapter(ctx: MultiRepositoryMcpToolContext, nam
             checkoutId: repository.activeCheckoutId,
           })
         : undefined;
+      // GPT supplies repository-language code hints for natural-language intents.
+      // Forge only searches those literal terms; it does not translate or infer semantics.
+      const codeSearchTerms = list(args.search_terms).filter((term) => term.length <= 160).slice(0, 8);
+      const exactCodeQuery = !/\s/u.test(retrievalQuery) && isCodeShapedTerm(retrievalQuery);
       const pack = await buildControllerContextPackInSidecar({
         repoRoot: repository.canonicalRoot,
         policy: ctx.policy,
         options: {
         description: retrievalQuery,
-        // Short code-like queries remain useful exact lexical needles. Long
-        // semantic prompts are already tokenized from description; adding the
-        // whole prompt as an exact needle prevents batch-search early exit and
-        // forces a full bounded repository scan for a phrase that will not match.
-        searchTerms: retrievalQuery.length <= 160 ? [retrievalQuery] : undefined,
+        // Only an actual single code identifier is an implicit exact needle.
+        // Prose (including mixed-language queries) stays in description; the
+        // model supplies matching source-language hints through search_terms.
+        searchTerms: codeSearchTerms.length ? codeSearchTerms
+          : exactCodeQuery ? [retrievalQuery] : undefined,
         knownPaths: list(args.known_paths),
         includeGlobs: list(args.include_globs),
         excludeGlobs: list(args.exclude_globs),
         maxFiles: typeof args.max_files === 'number' ? args.max_files : undefined,
         maxSnippets: typeof args.max_snippets === 'number' ? args.max_snippets : undefined,
         structuralContext,
-        structuralIndexRoot: structuralContext === 'off' ? undefined : resolveStructuralIndexRoot(ctx.controllerHome, repository),
         retrievalMode,
         impactDomains,
           session: rhContextReadSessionId(ctx)
@@ -602,7 +639,7 @@ export async function callContextAdapter(ctx: MultiRepositoryMcpToolContext, nam
       const semanticReasonCodes = Array.from(new Set([
         ...semanticNavigation.errors.map((entry) => `semantic.${String(entry.code ?? 'provider_error').toLowerCase()}`),
         ...(semanticNavigation.requestTruncated ? ['semantic.request_truncated'] : []),
-        ...(semanticNavigation.policyDeniedLocations > 0 || semanticNavigation.policyDeniedReads > 0 ? ['semantic.policy_denied'] : []),
+        ...(semanticNavigation.policyDeniedLocations > 0 || semanticNavigation.materialPolicyDeniedReads > 0 ? ['semantic.policy_denied'] : []),
         ...(semanticNavigation.freshness === 'changed_during_query' ? ['semantic.source_changed_during_query'] : []),
         ...(semanticNavigation.requested > 0 && semanticNavigation.staticClosure.status !== 'complete_for_requested_symbols' ? ['semantic.static_closure_incomplete'] : []),
       ]));
@@ -680,7 +717,7 @@ export async function callContextAdapter(ctx: MultiRepositoryMcpToolContext, nam
           } : {}),
           retrievalPolicy: {
             defaultBackend: 'bounded_lexical',
-            structuralBackend: 'codegraph',
+            structuralBackend: 'retired',
             rawReadTool: 'read_repository_file',
             shellSearchFallbackOnly: true,
             executionReadiness: 'requested_check_ids_only',
@@ -801,11 +838,13 @@ export async function callContextAdapter(ctx: MultiRepositoryMcpToolContext, nam
       const learningRecall = args.include_learning_recall === false
         ? undefined
         : rhContextLearningRecall(ctx, repository, capabilityIntentQuery);
-      const manifestOptions = { preferStored: true };
+      // Intent-ranked capability discovery must reflect the executable plugin contract.
+      // Persisted manifests are status projections and may outlive a source release that moved an action.
+      const manifestOptions = { preferStored: false };
       const repositoryManifests = listAssistantPluginManifests(ctx.controllerHome, repository, manifestOptions);
       const controllerManifests = listControllerPluginManifests(ctx.controllerHome, manifestOptions);
       const manifests = [...new Map(
-        [...repositoryManifests, ...controllerManifests].map((manifest) => [manifest.pluginId, manifest] as const),
+        [...controllerManifests, ...repositoryManifests].map((manifest) => [manifest.pluginId, manifest] as const),
       ).values()];
       const matches = searchCapabilityDescriptors(capabilityIntentQuery, manifests, 12)
         .map((match) => ({

package/adapters/mcp/runtime-gateway/context-pack-sidecar.ts

@@ -5,7 +5,6 @@ import type { McpPolicy, McpProfileName } from '../types';
 import { buildControllerContextPackAsync } from '../../../src/cli/controller/context-pack';
 import type { ControllerContextPackOptions } from '../../../src/cli/controller/context/types';
 import { PROCESS_RUNTIME_RELEASE_CANARY_ARG } from '../../../src/runtime/execution/process-runtime/canary';
-import { closeCodeGraphReadProviderSessions } from '../../../src/runtime/context/codegraph-read-provider';
 
 interface ContextPackEnvelope {
   schemaVersion: 1;
@@ -65,20 +64,13 @@ export async function runContextPackSidecar(
   if (envelope.schemaVersion !== 1 || typeof envelope.repoRoot !== 'string' || !envelope.repoRoot.trim()) {
     throw new Error('CONTEXT_PACK_REQUEST_INVALID');
   }
-  try {
-    const pack = await buildControllerContextPackAsync(
-      resolve(envelope.repoRoot),
-      policy(envelope.policy),
-      envelope.options && typeof envelope.options === 'object' ? envelope.options : {},
-    );
-    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, pack })}\n`);
-    return 0;
-  } finally {
-    // The Context Pack async path may reuse a CodeGraph session for progressive
-    // waves. This process is intentionally disposable, so do not inherit the
-    // normal 30-second provider idle lifetime.
-    await closeCodeGraphReadProviderSessions();
-  }
+  const pack = await buildControllerContextPackAsync(
+    resolve(envelope.repoRoot),
+    policy(envelope.policy),
+    envelope.options && typeof envelope.options === 'object' ? envelope.options : {},
+  );
+  process.stdout.write(`${JSON.stringify({ schemaVersion: 1, pack })}\n`);
+  return 0;
 }
 
 if (import.meta.main) {