@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -1,26 +1,73 @@
 import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import { FORGE_INSTANCE_SCOPE_KEY } from '../../../src/cli/repositories/controller-home';
 import type { MultiRepositoryMcpToolContext } from '../multi-repository';
 import { buildWorkspaceAuthStatus, prepareWorkspaceAuthLogin, summarizePluginForLowInterception } from '../../../src/runtime/safe-tooling';
 import {
   assistantPluginScope,
-  controllerPluginRepository,
   getAssistantPluginManifest,
+  getControllerPluginManifest,
   listAssistantPluginManifests,
+  listControllerPluginManifests,
 } from '../../../src/runtime/plugins/store';
 import { executeAssistantPluginActionApplication } from '../../../src/runtime/plugins/action-application';
 import { mcpPluginExecutionOrigin } from '../../../src/runtime/plugins/execution-origin';
 import type { AssistantPluginManifest } from '../../../src/runtime/plugins/types';
 import { result, resultWithPluginArtifactImages } from './result-adapter';
+import { boundedRuntimeResult } from './bounded-result-runtime';
 import { selected } from './shared-adapter';
 
-function pluginRepository(
+type PluginTransportScope =
+  | { kind: 'controller' }
+  | { kind: 'repository'; repository: ReturnType<typeof selected> };
+
+function explicitRepositoryContextRequested(args: Record<string, unknown>): boolean {
+  return (typeof args.repo_id === 'string' && Boolean(args.repo_id.trim()))
+    || (typeof args.checkout_id === 'string' && Boolean(args.checkout_id.trim()));
+}
+
+function pluginTransportScope(
   ctx: MultiRepositoryMcpToolContext,
   args: Record<string, unknown>,
   pluginId: string,
-) {
-  return assistantPluginScope(pluginId, ctx.controllerHome) === 'controller'
-    ? controllerPluginRepository(ctx.controllerHome)
-    : selected(ctx, args);
+): PluginTransportScope {
+  const explicitRepoId = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
+  if (explicitRepoId === '__controller__') {
+    throw new Error('PLUGIN_CONTROLLER_REPOSITORY_SENTINEL_RETIRED: controller-scoped plugins no longer use a synthetic repository id');
+  }
+  const scope = assistantPluginScope(pluginId, ctx.controllerHome);
+  if (scope === 'controller') return { kind: 'controller' };
+  if (scope === 'controller_with_repository_overlay') {
+    return explicitRepositoryContextRequested(args)
+      ? { kind: 'repository', repository: selected(ctx, args) }
+      : { kind: 'controller' };
+  }
+  return { kind: 'repository', repository: selected(ctx, args) };
+}
+
+function pluginManifestForScope(
+  ctx: MultiRepositoryMcpToolContext,
+  scope: PluginTransportScope,
+  pluginId: string,
+): AssistantPluginManifest {
+  return scope.kind === 'controller'
+    ? getControllerPluginManifest(ctx.controllerHome, pluginId)
+    : getAssistantPluginManifest(ctx.controllerHome, scope.repository, pluginId);
+}
+
+function pluginScopeLabel(scope: PluginTransportScope): 'controller' | 'repository' {
+  return scope.kind;
+}
+
+function detailArgumentsForScope(
+  scope: PluginTransportScope,
+  pluginId: string,
+  actionId?: string,
+): Record<string, unknown> {
+  return {
+    ...(scope.kind === 'repository' ? { repo_id: scope.repository.repoId } : {}),
+    capability_id: actionId ? `plugin.${pluginId}.${actionId}` : `plugin.${pluginId}`,
+    detail_level: 'detail',
+  };
 }
 
 function summarizePlugin(manifest: AssistantPluginManifest): Record<string, unknown> {
@@ -93,20 +140,17 @@ export async function callPluginAdapter(
 ): Promise<CallToolResult | undefined> {
   switch (name) {
     case 'list_plugins': {
-      const controllerRepository = controllerPluginRepository(ctx.controllerHome);
-      const controllerPlugins = listAssistantPluginManifests(ctx.controllerHome, controllerRepository, {
+      const controllerPlugins = listControllerPluginManifests(ctx.controllerHome, {
         forceRefresh: true,
       }).map(summarizePlugin);
       let repositoryPlugins: ReturnType<typeof summarizePlugin>[] = [];
       let repositoryId: string | undefined;
-      try {
+      if (explicitRepositoryContextRequested(args)) {
         const repository = selected(ctx, args);
         repositoryId = repository.repoId;
         repositoryPlugins = listAssistantPluginManifests(ctx.controllerHome, repository, {
           forceRefresh: true,
         }).map(summarizePlugin);
-      } catch (error) {
-        if (typeof args.repo_id === 'string' && args.repo_id.trim()) throw error;
       }
       return result({
         scope: repositoryPlugins.length > 0 ? 'combined' : 'controller',
@@ -117,16 +161,16 @@ export async function callPluginAdapter(
     }
     case 'get_plugin': {
       const pluginId = String(args.plugin_id ?? '').trim();
-      const repository = pluginRepository(ctx, args, pluginId);
+      const scope = pluginTransportScope(ctx, args, pluginId);
       return result({
-        scope: repository.repoId === '__controller__' ? 'controller' : 'repository',
-        plugin: summarizePlugin(getAssistantPluginManifest(ctx.controllerHome, repository, pluginId)),
+        scope: pluginScopeLabel(scope),
+        plugin: summarizePlugin(pluginManifestForScope(ctx, scope, pluginId)),
       });
     }
     case 'plugin_action_execute': {
       const pluginId = String(args.plugin_id ?? '').trim();
       const workId = typeof args.work_id === 'string' && args.work_id.trim() ? args.work_id.trim() : undefined;
-      const repository = pluginRepository(ctx, args, pluginId);
+      const scope = pluginTransportScope(ctx, args, pluginId);
       const workRepository = workId ? selected(ctx, args) : undefined;
       const actionId = String(args.action_id ?? '').trim();
       const requestId = String(args.request_id ?? '').trim();
@@ -148,14 +192,25 @@ export async function callPluginAdapter(
       };
       const application = await executeAssistantPluginActionApplication({
         controllerHome: ctx.controllerHome,
-        repository,
+        scope: scope.kind === 'controller'
+          ? { kind: 'controller' }
+          : { kind: 'repository', repository: scope.repository },
         request,
-        interactiveWaitMs: typeof args.interactive_wait_ms === 'number' ? args.interactive_wait_ms : 750,
-        wait: args.wait === true,
+        interactiveWaitMs: args.apply_mode === 'async' ? 0 : (typeof args.interactive_wait_ms === 'number' ? args.interactive_wait_ms : 750),
+        wait: args.apply_mode === 'async' ? false : args.wait === true,
         waitMs: typeof args.wait_ms === 'number' ? args.wait_ms : 15_000,
       });
 
       if (application.kind === 'direct_read') {
+        const resultScopeRepoId = scope.kind === 'repository' ? scope.repository.repoId : FORGE_INSTANCE_SCOPE_KEY;
+        const boundedPluginResult = boundedRuntimeResult({
+          controllerHome: ctx.controllerHome,
+          repoId: resultScopeRepoId,
+          sessionId: ctx.sessionId,
+          principalId: ctx.principalId,
+          controllerInstanceId: ctx.controllerInstanceId,
+          workId,
+        }, application.result);
         const value = {
           accepted: true,
           direct: true,
@@ -166,22 +221,37 @@ export async function callPluginAdapter(
             risk: application.action.risk,
             confirmation: application.action.confirmation,
           },
-          scope: repository.repoId === '__controller__' ? 'controller' : 'repository',
-          result: application.result,
+          scope: pluginScopeLabel(scope),
+          requestId: application.receipt.requestId,
+          observationReceiptId: application.receipt.receiptId,
+          evidenceRef: application.receipt.receiptId,
+          resultDigest: application.receipt.resultDigest,
+          result: boundedPluginResult.value,
           detail: {
             tool: 'rh_context',
             arguments: {
-              ...(repository.repoId === '__controller__' ? {} : { repo_id: repository.repoId }),
-              capability_id: `plugin.${pluginId}.${actionId}`,
-              detail_level: 'detail',
+              ...detailArgumentsForScope(scope, pluginId, actionId),
             },
           },
-          next: 'Continue with the returned bounded result; use rh_context capability detail only when the typed action schema/policy is needed.',
+          next: 'Continue with the returned bounded result. The compact observationReceiptId/evidenceRef may support model-selected learning without creating Work or effect replay state; use rh_context capability detail only when the typed action schema/policy is needed.',
         };
-        return resultWithPluginArtifactImages(value, ctx.controllerHome, repository.repoId, application.result);
+        return resultWithPluginArtifactImages(
+          value,
+          ctx.controllerHome,
+          resultScopeRepoId,
+          application.result,
+        );
       }
 
       if (application.kind === 'direct_non_persistent') {
+        const boundedPluginResult = boundedRuntimeResult({
+          controllerHome: ctx.controllerHome,
+          repoId: scope.kind === 'repository' ? scope.repository.repoId : FORGE_INSTANCE_SCOPE_KEY,
+          sessionId: ctx.sessionId,
+          principalId: ctx.principalId,
+          controllerInstanceId: ctx.controllerInstanceId,
+          workId,
+        }, application.result);
         return result({
           accepted: true,
           direct: true,
@@ -194,27 +264,25 @@ export async function callPluginAdapter(
             risk: application.action.risk,
             confirmation: application.action.confirmation,
           },
-          scope: repository.repoId === '__controller__' ? 'controller' : 'repository',
+          scope: pluginScopeLabel(scope),
           requestId,
-          result: application.result,
+          result: boundedPluginResult.value,
           detail: {
             tool: 'rh_context',
             arguments: {
-              ...(repository.repoId === '__controller__' ? {} : { repo_id: repository.repoId }),
-              capability_id: `plugin.${pluginId}.${actionId}`,
-              detail_level: 'detail',
+              ...detailArgumentsForScope(scope, pluginId, actionId),
             },
           },
           next: 'This protected action completed inline without durable replay state. Use the returned result only for the immediate next protected action.',
         });
       }
 
-      if (application.kind === 'lightweight_running') {
+      if (application.kind === 'managed_running') {
         return result({
           accepted: true,
           direct: false,
-          durable: false,
-          mode: 'lightweight_process',
+          durable: true,
+          mode: 'process_managed',
           plugin: summarizePluginActionReceipt(application.manifest),
           action: application.action ? {
             actionId: application.action.actionId,
@@ -222,21 +290,22 @@ export async function callPluginAdapter(
             confirmation: application.action.confirmation,
             requiredConfirmationText: application.action.requiredConfirmationText,
           } : { actionId },
-          scope: 'repository',
+          scope: pluginScopeLabel(scope),
           requestId,
           process: application.process,
           resultRef: { kind: 'process_logs', processId: application.process.processId },
-          next: 'The typed plugin action is isolated from the Canonical Runtime. Use process_wait on processId; after completion, call plugin_action_execute again with the same request_id to retrieve the deduplicated structured receipt.',
+          observation: { status: 'in_progress', outcome: 'unknown_until_process_terminal', retryPolicy: 'reattach_same_request_id' },
+          next: 'Execution is durably detached from this MCP stream. Observe processId/resultRef; after terminal completion, call plugin_action_execute with the same request_id to retrieve the deduplicated structured receipt. Never redispatch with a new request id because observation was interrupted.',
         });
       }
 
-      if (application.kind === 'lightweight_failed') {
+      if (application.kind === 'managed_failed') {
         const handle = application.process;
         return result({
           accepted: true,
           direct: false,
-          durable: false,
-          mode: 'lightweight_process',
+          durable: true,
+          mode: 'process_managed',
           requestId,
           process: handle,
           error: {
@@ -260,7 +329,7 @@ export async function callPluginAdapter(
           confirmation: submitted.action.confirmation,
           requiredConfirmationText: submitted.action.requiredConfirmationText,
         },
-        scope: repository.repoId === '__controller__' ? 'controller' : 'repository',
+        scope: pluginScopeLabel(scope),
         receiptId: submitted.receipt.receiptId,
         requestId: submitted.receipt.requestId,
         ...(submitted.receipt.workId ? { workId: submitted.receipt.workId } : {}),
@@ -269,14 +338,17 @@ export async function callPluginAdapter(
         detail: {
           tool: 'rh_context',
           arguments: {
-            ...(repository.repoId === '__controller__' ? {} : { repo_id: repository.repoId }),
-            capability_id: `plugin.${pluginId}.${actionId}`,
-            detail_level: 'detail',
+            ...detailArgumentsForScope(scope, pluginId, actionId),
           },
         },
         next: 'Continue with the returned bounded plugin result; use rh_context capability detail only when the typed action schema/policy is needed.',
       };
-      return resultWithPluginArtifactImages(value, ctx.controllerHome, repository.repoId, compactResult);
+      return resultWithPluginArtifactImages(
+        value,
+        ctx.controllerHome,
+        scope.kind === 'repository' ? scope.repository.repoId : FORGE_INSTANCE_SCOPE_KEY,
+        compactResult,
+      );
     }
     case 'workspace_auth_status': {
       const repository = selected(ctx, args);
@@ -292,8 +364,8 @@ export async function callPluginAdapter(
     }
     case 'toolchain_plugin_summary': {
       const pluginId = String(args.plugin_id ?? '').trim();
-      const repository = pluginRepository(ctx, args, pluginId);
-      const manifest = getAssistantPluginManifest(ctx.controllerHome, repository, pluginId);
+      const scope = pluginTransportScope(ctx, args, pluginId);
+      const manifest = pluginManifestForScope(ctx, scope, pluginId);
       return result({
         plugin: summarizePluginForLowInterception(manifest),
         nonOpaque: true,

package/adapters/mcp/runtime-gateway/process-tools.ts

@@ -11,11 +11,20 @@ import type { McpToolDefinition, CallToolResult } from '../../../packages/protoc
 import type { MultiRepositoryMcpToolContext } from '../multi-repository';
 import {
   cancelRepositoryCommandProcess,
+  executeHostCommand,
   getRepositoryCommandProcess,
   readRepositoryCommandProcessLogs,
   waitRepositoryCommandProcess,
 } from '../../../src/runtime/execution/process-runtime';
 import { redactSensitiveText, redactSensitiveValue } from '../../../src/runtime/evidence/sensitive-output';
+import { getProcessRecord } from '../../../src/runtime/execution/process-runtime/store';
+import { forgeInstanceIdFor, readProcessHandleIndexEntry } from '../../../src/runtime/execution/process-runtime/handle-index';
+import { isForgeInstanceProcessScopeKey, isRepositoryProcessScopeKey, processScopeKeyForHandle } from '../../../src/runtime/execution/process-runtime/process-scope';
+import { reconcileTerminalWorkVerifications } from '../../../src/runtime/control-plane/execution/work-verification-service';
+import type { WorkHandleState } from '../../../src/runtime/control-plane/execution/work-handle-store';
+import { findControlPlaneRecordsByKey } from '../../../src/runtime/control-plane/persistence/sqlite-store';
+import { sanitizeFileComponent } from '../../../src/runtime/shared/json-files';
+import { selected, stringList } from './shared-adapter';
 
 function definition(
   name: string,
@@ -40,7 +49,7 @@ function definition(
 
 const repoIdProp = {
   type: 'string',
-  description: 'Repository or ephemeral workspace scope id returned by the originating command. Process must belong to this scope.',
+  description: 'Optional repository or ephemeral workspace scope id returned by the originating command. When omitted, the process handle resolves its own recorded execution target.',
 };
 const processIdProp = {
   type: 'string',
@@ -48,6 +57,23 @@ const processIdProp = {
 };
 
 export const processToolDefinitions: McpToolDefinition[] = [
+  definition(
+    'process_exec',
+    'Execute one command on the Forge instance itself: cwd is an execution argument and no repository, checkout, or Work is required. Requires an explicit broad `process:exec` canonical Grant for this ForgeInstance; Forge does not parse the command to prove path safety. Returns a process handle; attach with process_get/process_wait/process_logs/process_cancel using the handle only.',
+    {
+      command: { type: 'array', items: { type: 'string' }, maxItems: 512, description: 'Typed argv command; command[0] is the executable. Mutually exclusive with shell_command.' },
+      shell_command: { type: 'string', maxLength: 32_000, description: 'Explicit broad shell form. Mutually exclusive with command. Never parsed for path safety.' },
+      cwd: { type: 'string', description: 'Optional absolute working directory. With work_id and no cwd, Forge uses that Work handle\'s exact workspace/worktree as a convenience default; this never grants permission and explicit authorized cwd may be elsewhere.' },
+      timeout_ms: { type: 'number' },
+      interactive_wait_ms: { type: 'number' },
+      max_output_bytes: { type: 'number' },
+      request_id: { type: 'string', description: 'Stable invocation id. A retry with the same id attaches to the existing process instead of re-executing.' },
+      work_id: { type: 'string', description: 'Optional Work provenance; Work is never required to run a host command.' },
+    },
+    [],
+    false,
+    true,
+  ),
   definition(
     'run_check',
     'Run one focused repository check, or launch one resource-compatible check wave, through Process Runtime. Use check_id for the existing single-check behavior or check_ids for a batch; do not send both. Batch mode validates the existing check-scheduling resource model and starts every check in one compatible wave concurrently without waiting for completion or creating a second scheduler. Cross-wave, invalid, release, and multi-phase batches fail closed. Long ordinary checks return managed handles; attach only at a real dependency boundary.',
@@ -74,7 +100,7 @@ export const processToolDefinitions: McpToolDefinition[] = [
       repo_id: repoIdProp,
       process_id: processIdProp,
     },
-    ['repo_id', 'process_id'],
+    ['process_id'],
     true,
   ),
   definition(
@@ -85,7 +111,7 @@ export const processToolDefinitions: McpToolDefinition[] = [
       process_id: processIdProp,
       timeout_ms: { type: 'number', description: 'Max wait milliseconds (default 15000).' },
     },
-    ['repo_id', 'process_id'],
+    ['process_id'],
     true,
   ),
   definition(
@@ -96,7 +122,7 @@ export const processToolDefinitions: McpToolDefinition[] = [
       process_id: processIdProp,
       max_bytes: { type: 'number', description: 'Max tail bytes per stream (default 32KiB).' },
     },
-    ['repo_id', 'process_id'],
+    ['process_id'],
     true,
   ),
   definition(
@@ -106,7 +132,7 @@ export const processToolDefinitions: McpToolDefinition[] = [
       repo_id: repoIdProp,
       process_id: processIdProp,
     },
-    ['repo_id', 'process_id'],
+    ['process_id'],
     false,
     true,
   ),
@@ -114,6 +140,33 @@ export const processToolDefinitions: McpToolDefinition[] = [
 
 const processToolNames = new Set(processToolDefinitions.map((tool) => tool.name));
 const processAttachmentToolNames = new Set(['process_get', 'process_wait', 'process_logs', 'process_cancel']);
+
+function reconcileAttachedWorkVerification(
+  ctx: MultiRepositoryMcpToolContext,
+  repoId: string,
+  processId: string,
+  handle: { completed?: boolean; workId?: string },
+): Record<string, unknown> | undefined {
+  if (handle.completed !== true || !handle.workId) return undefined;
+  const record = getProcessRecord(ctx.controllerHome, repoId, processId);
+  if (record?.origin?.workVerificationSnapshot !== true) return undefined;
+  try {
+    const repository = selected(ctx, { repo_id: repoId, checkout_id: record.checkoutId });
+    const reconciled = reconcileTerminalWorkVerifications({
+      controllerHome: ctx.controllerHome,
+      repository,
+      workId: handle.workId,
+    });
+    return {
+      workId: handle.workId,
+      processId,
+      status: reconciled.reconciledProcessIds.includes(processId) ? 'reconciled' : 'already_current_or_non_authoritative',
+      reconciledProcessIds: reconciled.reconciledProcessIds,
+    };
+  } catch {
+    return { workId: handle.workId, processId, status: 'non_authoritative' };
+  }
+}
 // A long-lived MCP wait can monopolize shared Runtime request/transport capacity
 // even though the underlying Process wait is asynchronous. Keep public waits
 // short and return a normal running snapshot; the Process continues unchanged
@@ -162,21 +215,58 @@ function failure(error: unknown): CallToolResult {
 function requireRepoAndProcess(
   ctx: MultiRepositoryMcpToolContext,
   args: Record<string, unknown>,
-): { repoId: string; processId: string } {
+): { repoId?: string; processId: string; handle: NonNullable<ReturnType<typeof getRepositoryCommandProcess>> } {
   const repoId = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
   const processId = typeof args.process_id === 'string' ? args.process_id.trim() : '';
-  if (!repoId) throw new Error('REPOSITORY_ID_REQUIRED: repo_id is required for process tools');
   if (!processId) throw new Error('PROCESS_ID_REQUIRED: process_id is required for process tools');
+  assertProcessHandleAccess(ctx, processId);
 
-  // The Process handle is the scope authority. Ephemeral workspace targets are
-  // intentionally not registered in Repository Registry, so requiring a live
-  // repository record here would make their returned managed handles impossible
-  // to resume. Exact repo/workspace scope + process id still fails closed.
-  const handle = getRepositoryCommandProcess(ctx.controllerHome, repoId, processId);
+  // The Process handle is the scope authority. An explicit repo_id is validated
+  // against the handle's recorded target; when it is omitted the handle index
+  // resolves the target so attachment never needs placement replay. Ephemeral
+  // workspace targets are intentionally not registered in Repository Registry,
+  // so requiring a live repository record here would make their returned
+  // managed handles impossible to resume.
+  const recordedScopeKey = processScopeKeyForHandle(ctx.controllerHome, processId);
+  // A ForgeInstance-scoped handle keeps its instance target even when a client
+  // always sends repo_id; the index remains the target authority.
+  const effectiveScopeKey = recordedScopeKey && isForgeInstanceProcessScopeKey(recordedScopeKey)
+    ? recordedScopeKey
+    : (repoId || recordedScopeKey);
+  const handle = getRepositoryCommandProcess(ctx.controllerHome, effectiveScopeKey, processId);
   if (!handle) {
-    throw new Error(`PROCESS_NOT_FOUND: process ${processId} is not registered under repo ${repoId}`);
+    throw new Error(repoId
+      ? `PROCESS_NOT_FOUND: process ${processId} is not registered under repo ${repoId}`
+      : `PROCESS_NOT_FOUND: ${processId}`);
+  }
+  const resolvedScopeKey = recordedScopeKey && isForgeInstanceProcessScopeKey(recordedScopeKey) ? recordedScopeKey : (repoId || recordedScopeKey);
+  const resolvedRepoId = resolvedScopeKey && isRepositoryProcessScopeKey(resolvedScopeKey) ? resolvedScopeKey : undefined;
+  return { repoId: resolvedRepoId || undefined, processId, handle };
+}
+
+/**
+ * A process handle id locates a record; it never authorizes attachment by
+ * itself. Instance-level handles are principal-bound and ForgeInstance-bound,
+ * and a recorded repository principal is enforced when the caller presents one.
+ */
+function assertProcessHandleAccess(ctx: MultiRepositoryMcpToolContext, processId: string): void {
+  const entry = readProcessHandleIndexEntry(ctx.controllerHome, processId);
+  if (!entry) return;
+  const caller = ctx.principalId?.trim();
+  const recorded = entry.principalId?.trim();
+  if (entry.target.scope === 'forge_instance') {
+    const servingInstance = forgeInstanceIdFor(ctx.controllerHome);
+    if (entry.target.forgeInstanceId && servingInstance && entry.target.forgeInstanceId !== servingInstance) {
+      throw new Error(`PROCESS_HANDLE_INSTANCE_MISMATCH: process ${processId} belongs to ForgeInstance ${entry.target.forgeInstanceId}`);
+    }
+    if (!recorded) throw new Error(`PROCESS_HANDLE_PRINCIPAL_UNBOUND: process ${processId} has no recorded principal`);
+    if (!caller) throw new Error(`PROCESS_HANDLE_PRINCIPAL_REQUIRED: process ${processId} requires an authenticated principal`);
+    if (recorded !== caller) throw new Error(`PROCESS_HANDLE_PRINCIPAL_MISMATCH: process ${processId} is owned by another principal`);
+    return;
+  }
+  if (recorded && caller && recorded !== caller) {
+    throw new Error(`PROCESS_HANDLE_PRINCIPAL_MISMATCH: process ${processId} is owned by another principal`);
   }
-  return { repoId, processId };
 }
 
 function handleToPayload(handle: NonNullable<ReturnType<typeof getRepositoryCommandProcess>>): Record<string, unknown> {
@@ -214,19 +304,23 @@ export async function callProcessTool(
   name: string,
   args: Record<string, unknown>,
 ): Promise<CallToolResult | undefined> {
+  if (name === 'process_exec') return callProcessExecTool(ctx, args);
   // run_check shares this module's public schema, but its execution authority is
   // the Gateway check facade in router.ts. Only attachment/lifecycle operations
   // consume an existing process_id here.
   if (!processAttachmentToolNames.has(name)) return undefined;
   try {
-    const { repoId, processId } = requireRepoAndProcess(ctx, args);
+    const { repoId, processId, handle: attachedHandle } = requireRepoAndProcess(ctx, args);
+    const scopePayload = repoId ? { repoId } : {};
     switch (name) {
       case 'process_get': {
-        const handle = getRepositoryCommandProcess(ctx.controllerHome, repoId, processId);
-        if (!handle) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
+        const workVerificationReconciliation = repoId
+          ? reconcileAttachedWorkVerification(ctx, repoId, processId, attachedHandle)
+          : undefined;
         return result({
-          repoId,
-          process: handleToPayload(handle),
+          ...scopePayload,
+          process: handleToPayload(attachedHandle),
+          ...(workVerificationReconciliation ? { workVerificationReconciliation } : {}),
         });
       }
       case 'process_wait': {
@@ -241,9 +335,13 @@ export async function callProcessTool(
         const handle = await waitRepositoryCommandProcess(ctx.controllerHome, repoId, processId, {
           timeoutMs: Math.min(requestedWaitMs, attachBudgetMs),
         });
+        const workVerificationReconciliation = repoId
+          ? reconcileAttachedWorkVerification(ctx, repoId, processId, handle)
+          : undefined;
         return result({
-          repoId,
+          ...scopePayload,
           process: handleToPayload(handle),
+          ...(workVerificationReconciliation ? { workVerificationReconciliation } : {}),
           synchronization: handle.completed === true ? 'terminal_result_available' : 'continue_independent_work',
           waitedMs: Date.now() - startedAt,
           requestedWaitMs,
@@ -258,7 +356,7 @@ export async function callProcessTool(
         const logs = readRepositoryCommandProcessLogs(ctx.controllerHome, repoId, processId, maxBytes);
         if (!logs) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
         return result({
-          repoId,
+          ...scopePayload,
           processId,
           stdout: logs.stdout,
           stderr: logs.stderr,
@@ -271,7 +369,7 @@ export async function callProcessTool(
       case 'process_cancel': {
         const handle = await cancelRepositoryCommandProcess(ctx.controllerHome, repoId, processId);
         return result({
-          repoId,
+          ...scopePayload,
           process: handleToPayload(handle),
           cancelled: handle.cancelled === true || handle.status === 'cancelled' || handle.status === 'completed_unknown',
         });
@@ -284,6 +382,76 @@ export async function callProcessTool(
   }
 }
 
+/**
+ * `process_exec` — the canonical host-local command lane.
+ *
+ * Repo-less by construction: the Forge instance is the target and `cwd` is an
+ * execution argument. Authorization is one explicit canonical `process:exec`
+ * Grant for this instance, enforced in the lane before any spawn.
+ */
+function workDefaultCommandCwd(ctx: MultiRepositoryMcpToolContext, workId: string): string | undefined {
+  if (!workId) return undefined;
+  const matches = findControlPlaneRecordsByKey<WorkHandleState>(ctx.controllerHome, {
+    namespace: 'execution_work_handle',
+    key: sanitizeFileComponent(workId),
+    limit: 2,
+  });
+  if (matches.length > 1) {
+    throw new Error(`WORK_EXECUTION_PLACEMENT_AMBIGUOUS: ${workId} resolves to multiple execution handles`);
+  }
+  const handle = matches[0]?.value;
+  if (!handle) return undefined;
+  if (handle.workId !== workId) throw new Error(`WORK_EXECUTION_PLACEMENT_IDENTITY_MISMATCH: ${workId}`);
+  const workspace = handle.worktreePath?.trim();
+  return workspace || undefined;
+}
+
+async function callProcessExecTool(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+): Promise<CallToolResult> {
+  try {
+    const command = stringList(args.command);
+    const shellCommand = typeof args.shell_command === 'string' && args.shell_command.trim()
+      ? args.shell_command
+      : undefined;
+    if (command.length > 0 && shellCommand) {
+      throw new Error('HOST_COMMAND_AMBIGUOUS: provide exactly one of command or shell_command');
+    }
+    if (command.length === 0 && !shellCommand) {
+      throw new Error('HOST_COMMAND_REQUIRED: provide command (argv) or shell_command');
+    }
+    const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+    const workId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+    const explicitCwd = typeof args.cwd === 'string' ? args.cwd.trim() : '';
+    const cwd = explicitCwd || workDefaultCommandCwd(ctx, workId) || '';
+    const executed = await executeHostCommand({
+      controllerHome: ctx.controllerHome,
+      principalId: ctx.principalId ?? '',
+      ...(command.length > 0 ? { command } : {}),
+      ...(shellCommand ? { shellCommand } : {}),
+      cwd,
+      ...(typeof args.timeout_ms === 'number' ? { timeoutMs: args.timeout_ms } : {}),
+      ...(typeof args.interactive_wait_ms === 'number' ? { interactiveWaitMs: args.interactive_wait_ms } : {}),
+      ...(typeof args.max_output_bytes === 'number' ? { maxOutputBytes: args.max_output_bytes } : {}),
+      ...(requestId ? { commandId: requestId } : {}),
+      ...(workId ? { workId } : {}),
+    });
+    return result({
+      process: handleToPayload(executed.handle),
+      target: {
+        scope: 'forge_instance',
+        forgeInstanceId: executed.target.forgeInstanceId,
+        cwd: executed.target.cwd,
+      },
+      authorization: { capability: 'process:exec', grantId: executed.target.grantId },
+      executionMetrics: executed.metrics,
+    });
+  } catch (error) {
+    return failure(error);
+  }
+}
+
 export function isProcessTool(name: string): boolean {
   return processToolNames.has(name);
 }