@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/gateway/mcp/persisted-check-process.ts

@@ -0,0 +1,255 @@
+import { createHash } from 'crypto';
+import { existsSync } from 'fs';
+import { dirname, resolve } from 'path';
+import {
+  controllerCheckExecutionIdentity,
+  listControllerChecks,
+  snapshotControllerCheck,
+} from '../../../cli/controller/check-runner';
+import {
+  currentCliRuntimeTarget,
+  resolveCliChildInvocation,
+  type CliChildInvocation,
+  type CliChildInvocationOptions,
+  type CliRuntimeTarget,
+} from '../../../cli/runtime-invocation';
+import { readRuntimeGeneration, resolveControllerRuntimeSourceRoot } from '../../control-plane/runtime-generation';
+import {
+  checkRequiresDurableWorkflow,
+  claimsForCheck,
+  spawnManagedProcess,
+  toProcessClaims,
+  type CheckExecutionMode,
+  processCheckSemanticScopeKey,
+  type RunCheckFacadeInput,
+  type RunCheckFacadeResult,
+} from '../../execution/process-runtime';
+import { durationAwareInteractiveWaitMs } from '../../execution/process-runtime/interactive-admission';
+const PERSISTED_CHECK_SOURCE_ENTRY = 'src/runtime/execution/process-runtime/check-runner-sidecar.ts';
+
+export function resolvePersistedCheckCliInvocation(
+  cliEntry: string,
+  args: string[],
+  options: CliChildInvocationOptions = {},
+): CliChildInvocation {
+  return resolveCliChildInvocation(cliEntry, args, options);
+}
+
+export function resolveRuntimeCliTarget(controllerHome?: string): CliRuntimeTarget {
+  const moduleSourceRoot = resolve(import.meta.dir, '..', '..', '..', '..');
+  const sourceEntry = resolve(moduleSourceRoot, 'src', 'cli', 'index.ts');
+  const source = resolveControllerRuntimeSourceRoot({
+    explicitRoot: existsSync(sourceEntry) ? moduleSourceRoot : undefined,
+  });
+  const sourceMode = Boolean(source.root && existsSync(resolve(source.root, 'src', 'cli', 'index.ts')));
+  const runtimeEnv = { ...process.env };
+  if (sourceMode) {
+    delete runtimeEnv.FORGE_RUNTIME_EXECUTION;
+    delete runtimeEnv.FORGE_RUNTIME_CLI_ENTRY;
+  }
+  const generation = controllerHome ? readRuntimeGeneration(controllerHome) : undefined;
+  return currentCliRuntimeTarget({
+    env: runtimeEnv,
+    argv: sourceMode ? [] : process.argv,
+    moduleUrl: sourceMode ? undefined : import.meta.url,
+    sourceRoot: source.root,
+    cwd: source.root ?? moduleSourceRoot,
+    sourceRevision: generation?.source.releaseRevision
+      ?? generation?.source.commit
+      ?? process.env.FORGE_ACTIVE_RUNTIME_REVISION,
+  });
+}
+
+export function resolveRuntimeCliEntry(controllerHome?: string): string {
+  return resolveRuntimeCliTarget(controllerHome).entry;
+}
+
+export function persistedCheckSemanticScopeKey(
+  input: Pick<RunCheckFacadeInput, 'workId' | 'verificationBinding' | 'checkoutId'>,
+  reuseScope: 'repository' | 'checkout',
+): string {
+  return processCheckSemanticScopeKey(input, reuseScope);
+}
+
+export function resolvePersistedCheckRuntimeExecutable(
+  cliTarget: CliRuntimeTarget,
+  runtimeExecutable = process.execPath,
+  entryExists: (path: string) => boolean = existsSync,
+): string {
+  if (cliTarget.runtimeKind !== 'compiled_bun_release') return runtimeExecutable;
+  const checkRunner = resolve(dirname(runtimeExecutable), 'forge-check-runner');
+  if (!entryExists(checkRunner)) {
+    throw new Error(`PERSISTED_CHECK_RUNNER_MISSING: ${checkRunner}`);
+  }
+  return checkRunner;
+}
+
+export function resolvePersistedCheckProcessInvocation(
+  cliTarget: CliRuntimeTarget,
+  args: string[],
+  options: { runtimeExecutable?: string; entryExists?: (path: string) => boolean } = {},
+): CliChildInvocation {
+  const runtimeExecutable = options.runtimeExecutable ?? process.execPath;
+  const executable = resolvePersistedCheckRuntimeExecutable(cliTarget, runtimeExecutable, options.entryExists ?? existsSync);
+  if (cliTarget.runtimeKind === 'compiled_bun_release') {
+    return { executable, args };
+  }
+  const sourceEntry = resolve(cliTarget.cwd, PERSISTED_CHECK_SOURCE_ENTRY);
+  if (!(options.entryExists ?? existsSync)(sourceEntry)) {
+    throw new Error(`PERSISTED_CHECK_SOURCE_RUNNER_MISSING: ${sourceEntry}`);
+  }
+  return resolvePersistedCheckCliInvocation(sourceEntry, args, {
+    runtimeExecutable: executable,
+    runtimeKind: cliTarget.runtimeKind,
+    sourceRevision: cliTarget.sourceRevision,
+    immutable: false,
+    ...(cliTarget.runtimeKind === 'package_launcher' ? { launcherEntry: cliTarget.entry } : {}),
+  });
+}
+
+/**
+ * Run a registered check through Process Runtime while keeping check-runner
+ * evidence authoritative. The managed OS process invokes the same immutable
+ * forge CLI bundle with a hidden internal subcommand; that subcommand
+ * executes runControllerCheck, writes the Artifact atomically, mirrors bounded
+ * stdout/stderr, and exits with the exact check status.
+ */
+export async function runPersistedCheckViaProcessRuntime(
+  input: RunCheckFacadeInput,
+): Promise<RunCheckFacadeResult> {
+  const emptyEffects = {
+    executionJobCount: 0,
+    localJobCount: 0,
+    workerSpawnCount: 0,
+    projectionUpdateCount: 0,
+  };
+  const check = listControllerChecks(input.repoRoot).find((entry) => entry.id === input.checkId);
+  if (!check) {
+    return {
+      mode: 'durable',
+      checkId: input.checkId,
+      durable: {
+        reason: 'check_not_found_or_requires_registry_lookup',
+        suggestedOperation: 'list_checks then run_check with a known check_id',
+      },
+      durableSideEffects: emptyEffects,
+    };
+  }
+  if (input.forceDurable || checkRequiresDurableWorkflow(input.checkId, check)) {
+    return {
+      mode: 'durable',
+      checkId: input.checkId,
+      check,
+      durable: {
+        reason: 'multi_phase_or_release_check_requires_durable_workflow',
+        suggestedOperation: 'Claim the related WorkContract and run this check through an external Controller.',
+      },
+      durableSideEffects: emptyEffects,
+    };
+  }
+
+  const interactiveWaitMs = durationAwareInteractiveWaitMs(check.command, input.interactiveWaitMs);
+  const leaseWaitMs = input.leaseWaitMs;
+  const timeoutMs = Math.min(
+    check.timeoutMs,
+    typeof input.timeoutMs === 'number' && Number.isFinite(input.timeoutMs)
+      ? Math.max(1_000, Math.trunc(input.timeoutMs))
+      : check.timeoutMs,
+  );
+  if (!input.executionIdentity) {
+    throw new Error('EXECUTION_IDENTITY_REQUIRED: persisted run_check requires an immutable executionIdentity');
+  }
+  const executionIdentity = input.executionIdentity;
+  if (executionIdentity.repositoryId !== input.repoId) {
+    throw new Error(
+      `EXECUTION_IDENTITY_MISMATCH: check repo ${input.repoId} differs from identity ${executionIdentity.repositoryId}`,
+    );
+  }
+  if (input.checkoutId?.trim() && executionIdentity.checkoutId !== input.checkoutId.trim()) {
+    throw new Error(
+      `CHECKOUT_ROUTE_MISMATCH: check checkout ${input.checkoutId} differs from identity ${executionIdentity.checkoutId}`,
+    );
+  }
+  const claims = claimsForCheck(
+    input.checkId,
+    check.command,
+    executionIdentity.repositoryId,
+    executionIdentity.checkoutId,
+    check.effects,
+  );
+  const checkSnapshot = snapshotControllerCheck(input.repoRoot, input.checkId);
+  const checkFingerprint = createHash('sha256')
+    .update(JSON.stringify(checkSnapshot))
+    .digest('hex');
+  const semanticCheck = controllerCheckExecutionIdentity(
+    input.repoRoot,
+    input.checkId,
+    timeoutMs,
+    checkSnapshot,
+  );
+  const processCheckExecution = {
+    schemaVersion: 1 as const,
+    checkId: semanticCheck.checkId,
+    cacheKey: semanticCheck.cacheKey,
+    revision: semanticCheck.revision,
+    definitionDigest: semanticCheck.definitionDigest,
+    environmentFingerprint: semanticCheck.environmentFingerprint,
+    timeoutMs: semanticCheck.timeoutMs,
+    reuseScope: semanticCheck.reuseScope,
+    scopeKey: persistedCheckSemanticScopeKey(input, semanticCheck.reuseScope),
+  };
+  const cliTarget = resolveRuntimeCliTarget(input.controllerHome);
+  const checkArgs = [
+    '--repo',
+    executionIdentity.canonicalRoot,
+    '--check-id',
+    input.checkId,
+    '--timeout-ms',
+    String(timeoutMs),
+    '--expected-check-fingerprint',
+    checkFingerprint,
+  ];
+  const invocation = resolvePersistedCheckProcessInvocation(cliTarget, checkArgs);
+  const handle = await spawnManagedProcess({
+    controllerHome: input.controllerHome,
+    repoId: executionIdentity.repositoryId,
+    checkoutId: executionIdentity.checkoutId,
+    executionIdentity,
+    workId: input.workId,
+    commandId: input.commandId,
+    command: {
+      kind: 'argv',
+      executable: invocation.executable,
+      args: invocation.args,
+      cwd: executionIdentity.canonicalRoot,
+    },
+    interactiveWaitMs,
+    leaseWaitMs,
+    timeoutMs: timeoutMs + 5_000,
+    resourceClaims: toProcessClaims(claims),
+    checkExecution: processCheckExecution,
+    origin: {
+      surface: 'check',
+      toolName: 'run_check',
+      checkId: input.checkId,
+      requestId: input.requestId,
+      correlationId: input.workId,
+      executionSessionId: input.verificationBinding?.executionSessionId,
+      editSessionId: input.verificationBinding?.editSessionId,
+      editRevision: input.verificationBinding?.editRevision,
+      issueId: input.verificationBinding?.issueId,
+      taskId: input.verificationBinding?.taskId,
+    },
+    signal: input.signal,
+  });
+
+  const mode: CheckExecutionMode = handle.completed ? 'direct' : 'managed';
+  return {
+    mode,
+    checkId: input.checkId,
+    check,
+    process: handle,
+    ok: handle.completed ? handle.ok : undefined,
+    durableSideEffects: handle.durableSideEffects,
+  };
+}

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

@@ -0,0 +1,230 @@
+/**
+ * Repository-scoped Managed Process lifecycle MCP tools.
+ *
+ * process_get / process_wait / process_logs / process_cancel
+ *
+ * These tools attach to an existing Process Runtime handle — they never
+ * re-execute the original command.
+ */
+
+import type { McpToolDefinition, CallToolResult } from '../../../cli/mcp/tools';
+import type { MultiRepositoryMcpToolContext } from '../../../cli/mcp/multi-repository';
+import { getRepository } from '../../../cli/repositories/registry';
+import {
+  cancelProcess,
+  getProcessHandle,
+  readProcessLogs,
+  waitForProcess,
+} from '../../execution/process-runtime';
+import { getProcessRecord } from '../../execution/process-runtime/store';
+import { redactSensitiveText, redactSensitiveValue } from '../../evidence/sensitive-output';
+
+function definition(
+  name: string,
+  description: string,
+  properties: Record<string, unknown>,
+  required: string[] = [],
+  readOnlyHint = false,
+  destructiveHint = false,
+): McpToolDefinition {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: 'object',
+      properties,
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint, openWorldHint: false, destructiveHint },
+  };
+}
+
+const repoIdProp = {
+  type: 'string',
+  description: 'Stable repository id. Process must belong to this repository.',
+};
+const processIdProp = {
+  type: 'string',
+  description: 'Managed process id returned by Process Runtime (e.g. from run_check / repository_command).',
+};
+
+export const processToolDefinitions: McpToolDefinition[] = [
+  definition(
+    'process_get',
+    'Get the current status of a managed process without re-executing the command. Readonly.',
+    {
+      repo_id: repoIdProp,
+      process_id: processIdProp,
+    },
+    ['repo_id', 'process_id'],
+    true,
+  ),
+  definition(
+    'process_wait',
+    'Wait for a managed process to complete or until timeout_ms. Does not re-execute the command. Readonly attach/poll.',
+    {
+      repo_id: repoIdProp,
+      process_id: processIdProp,
+      timeout_ms: { type: 'number', description: 'Max wait milliseconds (default 15000).' },
+    },
+    ['repo_id', 'process_id'],
+    true,
+  ),
+  definition(
+    'process_logs',
+    'Read a bounded tail of managed process stdout/stderr. Never loads unbounded logs. Readonly.',
+    {
+      repo_id: repoIdProp,
+      process_id: processIdProp,
+      max_bytes: { type: 'number', description: 'Max tail bytes per stream (default 32KiB).' },
+    },
+    ['repo_id', 'process_id'],
+    true,
+  ),
+  definition(
+    'process_cancel',
+    'Cancel a managed process. Requires verified PID identity (start time + executable fingerprint). Untrusted PIDs are refused. Classified as workspace-write / process-control.',
+    {
+      repo_id: repoIdProp,
+      process_id: processIdProp,
+    },
+    ['repo_id', 'process_id'],
+    false,
+    true,
+  ),
+];
+
+const processToolNames = new Set(processToolDefinitions.map((tool) => tool.name));
+
+function result(value: Record<string, unknown>, isError = false): CallToolResult {
+  const safe = redactSensitiveValue(value).value;
+  return {
+    content: [{ type: 'text', text: JSON.stringify(safe, null, 2) }],
+    structuredContent: safe,
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+function failure(error: unknown): CallToolResult {
+  const message = redactSensitiveText(error instanceof Error ? error.message : String(error)).text;
+  const code = message.includes(':') ? message.slice(0, message.indexOf(':')) : 'PROCESS_TOOL_FAILED';
+  return result({ error: { code, message } }, true);
+}
+
+function requireRepoAndProcess(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+): { repoId: string; processId: string } {
+  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');
+
+  // Force repo scope: repository must exist under this controller home.
+  const repository = getRepository(repoId, ctx.controllerHome);
+  if (!repository) {
+    throw new Error(`REPOSITORY_NOT_FOUND: ${repoId}`);
+  }
+
+  // Process must belong to the requested repo.
+  const record = getProcessRecord(ctx.controllerHome, repoId, processId);
+  if (!record) {
+    throw new Error(`PROCESS_NOT_FOUND: process ${processId} is not registered under repo ${repoId}`);
+  }
+  if (record.repoId !== repoId) {
+    throw new Error(`PROCESS_REPO_MISMATCH: process ${processId} belongs to ${record.repoId}, not ${repoId}`);
+  }
+  return { repoId, processId };
+}
+
+function handleToPayload(handle: NonNullable<ReturnType<typeof getProcessHandle>>): Record<string, unknown> {
+  return {
+    processId: handle.processId,
+    workId: handle.workId,
+    commandId: handle.commandId,
+    status: handle.status,
+    contractStatus: handle.contractStatus,
+    route: handle.route,
+    pid: handle.pid,
+    startedAt: handle.startedAt,
+    interactiveWaitMs: handle.interactiveWaitMs,
+    timeoutMs: handle.timeoutMs,
+    completed: handle.completed === true,
+    ok: handle.ok,
+    exitCode: handle.exitCode,
+    timedOut: handle.timedOut,
+    cancelled: handle.cancelled,
+    stdout: handle.stdout,
+    stderr: handle.stderr,
+    stdoutTail: handle.stdoutTail,
+    stderrTail: handle.stderrTail,
+    durableSideEffects: handle.durableSideEffects,
+  };
+}
+
+export async function callProcessTool(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (!processToolNames.has(name)) return undefined;
+  try {
+    const { repoId, processId } = requireRepoAndProcess(ctx, args);
+    switch (name) {
+      case 'process_get': {
+        const handle = getProcessHandle(ctx.controllerHome, repoId, processId);
+        if (!handle) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
+        return result({
+          repoId,
+          process: handleToPayload(handle),
+        });
+      }
+      case 'process_wait': {
+        const timeoutMs = typeof args.timeout_ms === 'number' && Number.isFinite(args.timeout_ms)
+          ? Math.max(1, Math.trunc(args.timeout_ms))
+          : 15_000;
+        const handle = await waitForProcess(ctx.controllerHome, repoId, processId, { timeoutMs });
+        return result({
+          repoId,
+          process: handleToPayload(handle),
+          waitedMs: timeoutMs,
+          reExecuted: false,
+        });
+      }
+      case 'process_logs': {
+        const maxBytes = typeof args.max_bytes === 'number' && Number.isFinite(args.max_bytes)
+          ? Math.max(256, Math.trunc(args.max_bytes))
+          : 32 * 1024;
+        const logs = readProcessLogs(ctx.controllerHome, repoId, processId, maxBytes);
+        if (!logs) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
+        return result({
+          repoId,
+          processId,
+          stdout: logs.stdout,
+          stderr: logs.stderr,
+          stdoutBytes: logs.stdoutBytes,
+          stderrBytes: logs.stderrBytes,
+          truncated: logs.truncated,
+          maxBytes,
+        });
+      }
+      case 'process_cancel': {
+        const handle = await cancelProcess(ctx.controllerHome, repoId, processId);
+        return result({
+          repoId,
+          process: handleToPayload(handle),
+          cancelled: handle.cancelled === true || handle.status === 'cancelled' || handle.status === 'completed_unknown',
+        });
+      }
+      default:
+        return undefined;
+    }
+  } catch (error) {
+    return failure(error);
+  }
+}
+
+export function isProcessTool(name: string): boolean {
+  return processToolNames.has(name);
+}

package/src/runtime/gateway/mcp/resource-policy.ts

@@ -0,0 +1,195 @@
+import type { ResourceClaimSpec } from '../../execution/jobs/types';
+import { ephemeralWorkspaceCoordinates } from '../../../cli/repositories/ephemeral-workspace';
+import {
+  claimsForCheck,
+  claimsForRepositoryCommand,
+  claimHeavyCheck,
+  claimWorkspaceRead,
+  claimBuildCacheWrite,
+} from '../../execution/process-runtime/resource-claims';
+
+const READ_ONLY_TOOLS = new Set([
+  'controller_capabilities',
+  'controller_ready',
+  'controller_context',
+  'controller_context_pack',
+  'project_snapshot',
+  'get_project_state',
+  'get_project_governance',
+  'get_project_progress',
+  'get_project_board',
+  'get_task_progress_detail',
+  'get_issue',
+  'list_issues',
+  'list_task_runs',
+  'list_edit_sessions',
+  'list_checks',
+  'search_repository',
+  'read_repository_file',
+  'github_status',
+  'repository_get',
+  'repository_list',
+  'repository_workbench',
+  'repository_runtime_snapshot',
+  'list_schedules',
+  'repository_command_preview',
+  'get_local_job',
+  'get_local_job_output',
+  'local_bridge_status',
+  'get_task_run',
+  'get_task_run_events',
+  'get_task_run_log',
+  'get_task_diff',
+  'get_worklog_timeline',
+  'list_campaigns',
+  'get_campaign',
+  'get_campaign_review_packet',
+  'capability_recovery_probe',
+  'capability_recovery_plan',
+  'runtime_maintenance_status',
+  'goal_list',
+  'goal_get',
+  'goal_status',
+  'goal_handoff_packet_get',
+  'provider_list',
+  'provider_health',
+  'provider_config_status',
+  'executor_route_preview',
+  'repair_plan',
+  'workspace_auth_status',
+  'workspace_auth_login_prepare',
+  'external_filesystem_targets_list',
+  'external_filesystem_grant_preview',
+  'external_filesystem_text_snapshot',
+]);
+const REPO_STATE_TOOLS = new Set([
+  'create_issue', 'update_issue', 'plan_issue', 'append_task', 'split_task', 'supersede_task',
+  'set_task_dependencies', 'update_task', 'record_task_verification', 'accept_verified_task',
+  'write_prd', 'write_prd_from_idea', 'write_sprint', 'write_checklist_sprint', 'write_plan',
+  'record_candidate_finding', 'repository_register', 'repository_refresh', 'repository_validate',
+  'repository_update', 'repository_disable', 'repository_remove', 'create_edit_savepoint',
+  'begin_edit_session', 'set_current_issue', 'archive_issue', 'restore_issue', 'reconcile_project_governance',
+  'create_campaign', 'add_campaign_task', 'pause_campaign', 'resume_campaign', 'cancel_campaign',
+  'submit_campaign_review', 'accept_campaign', 'reconcile_campaign',
+  'capability_recovery_apply', 'runtime_maintenance_apply', 'external_filesystem_grant_apply',
+  'goal_create', 'goal_start', 'goal_continue', 'goal_stop', 'goal_finalize', 'goal_tick_once',
+  'goal_handoff_packet_create', 'executor_dispatch', 'repair_continue',
+]);
+const CHECK_TOOLS = new Set(['run_check', 'verify_edit_session']);
+const INTEGRATION_TOOLS = new Set(['integrate_task_run', 'finish_edit_session']);
+const REMOTE_TOOLS = new Set(['publish_issue_to_github', 'refresh_github_issue', 'close_github_issue', 'configure_github_plugin']);
+const AGENT_TOOLS = new Set(['dispatch_task', 'launch_issue', 'dispatch_ready_tasks', 'retry_task_run', 'quick_agent_session']);
+const WORKSPACE_WRITE_TOOLS = new Set([
+  'apply_patch', 'apply_edit_operations', 'rollback_edit_session', 'finalize_edit_session',
+  'repository_command_execute',
+]);
+const DURABLE_WORK_TOOLS = new Set(['work_execute', 'work_validate', 'work_finalize']);
+
+function operationPaths(args: Record<string, unknown>): string[] {
+  const paths = new Set<string>();
+  const allowed = args.allowed_paths;
+  if (Array.isArray(allowed)) for (const value of allowed) if (typeof value === 'string' && value.trim()) paths.add(value.trim());
+  const operations = args.operations;
+  if (Array.isArray(operations)) {
+    for (const operation of operations) {
+      if (operation && typeof operation === 'object') {
+        const path = (operation as Record<string, unknown>).path;
+        if (typeof path === 'string' && path.trim()) paths.add(path.trim());
+      }
+    }
+  }
+  const path = args.path;
+  if (typeof path === 'string' && path.trim()) paths.add(path.trim());
+  return [...paths];
+}
+
+function isolatedWorktreeKey(args: Record<string, unknown>): string {
+  const issueId = typeof args.issue_id === 'string' ? args.issue_id.trim() : '';
+  const taskId = typeof args.task_id === 'string' ? args.task_id.trim() : '';
+  const runId = typeof args.run_id === 'string' ? args.run_id.trim() : '';
+  const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+  const identity = (issueId && taskId ? `${issueId}-${taskId}` : runId || taskId || issueId || requestId || 'isolated')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-');
+  return identity || 'isolated';
+}
+
+export function claimsForMcpOperation(name: string, args: Record<string, unknown>, repoId: string, checkoutId?: string): ResourceClaimSpec[] {
+  if (READ_ONLY_TOOLS.has(name)) return [];
+  if (name === 'create_campaign') return [
+    { resourceKey: 'repo-state', mode: 'write' },
+    { resourceKey: `git-refs:${repoId}`, mode: 'exclusive' },
+  ];
+  if (REPO_STATE_TOOLS.has(name)) return [{ resourceKey: 'repo-state', mode: 'write' }];
+  // run_check: only true heavy/release checks take exclusive heavy-check lock.
+  // Ordinary typecheck / lint / package scripts use fine-grained claims.
+  if (name === 'run_check') {
+    const checkId = String(args.check_id ?? args.checkId ?? '').trim();
+    if (!checkId) return [claimWorkspaceRead(checkoutId), claimBuildCacheWrite(repoId)];
+    return claimsForCheck(checkId, undefined, repoId, checkoutId);
+  }
+  // verify/finish edit may run multiple checks — keep exclusive to avoid parallel mutate+verify races.
+  if (name === 'verify_edit_session') return [claimHeavyCheck(repoId)];
+  if (name === 'finish_edit_session') return [
+    claimHeavyCheck(repoId),
+    { resourceKey: `integration:${repoId}`, mode: 'exclusive' },
+    { resourceKey: `workspace:${checkoutId ?? 'active'}`, mode: 'write' },
+    { resourceKey: `git-refs:${repoId}`, mode: 'exclusive' },
+  ];
+  if (CHECK_TOOLS.has(name)) return claimsForCheck(String(args.check_id ?? name), undefined, repoId, checkoutId);
+  if (INTEGRATION_TOOLS.has(name)) return [
+    { resourceKey: `integration:${repoId}`, mode: 'exclusive' },
+    { resourceKey: `workspace:${checkoutId ?? 'active'}`, mode: 'write' },
+    { resourceKey: `git-refs:${repoId}`, mode: 'exclusive' },
+  ];
+  if (REMOTE_TOOLS.has(name)) return [{ resourceKey: `remote:${repoId}`, mode: 'exclusive' }];
+  if (AGENT_TOOLS.has(name)) {
+    if (args.agent === 'github-copilot') return [{ resourceKey: `remote:${repoId}`, mode: 'exclusive' }];
+    // Parent Execution Job only accepts the child Agent Run. Workspace/worktree
+    // write ownership belongs to the child Run, not the short-lived parent Job.
+    const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+    const dispatchKey = isolatedWorktreeKey(args) || requestId || name;
+    return [{ resourceKey: `agent-dispatch:${repoId}:${dispatchKey}`, mode: 'write' }];
+  }
+  if (DURABLE_WORK_TOOLS.has(name)) {
+    const workId = typeof args.work_id === 'string' && args.work_id.trim()
+      ? args.work_id.trim()
+      : 'unresolved';
+    const claims: ResourceClaimSpec[] = [
+      { resourceKey: `work:${repoId}:${workId}`, mode: 'exclusive' },
+    ];
+    if (name === 'work_validate') claims.push(claimHeavyCheck(repoId));
+    if (name === 'work_finalize') claims.push(
+      { resourceKey: `integration:${repoId}`, mode: 'exclusive' },
+      { resourceKey: `git-refs:${repoId}`, mode: 'exclusive' },
+    );
+    return claims;
+  }
+  if (name === 'repository_command_execute' && args.command !== undefined) {
+    const workspaceRoot = typeof args.workspace_root === 'string' ? args.workspace_root.trim() : '';
+    const workspace = workspaceRoot ? ephemeralWorkspaceCoordinates(workspaceRoot) : undefined;
+    return claimsForRepositoryCommand(
+      args.command as string | string[],
+      workspace?.workspaceId ?? repoId,
+      workspace?.checkoutId ?? checkoutId,
+      typeof args.default_branch === 'string' ? args.default_branch : undefined,
+    );
+  }
+  if (WORKSPACE_WRITE_TOOLS.has(name)) {
+    const paths = operationPaths(args);
+    if (paths.length > 0) {
+      return paths.map((path) => ({
+        resourceKey: `path:${checkoutId ?? 'active'}:${path.replace(/^\.\//, '')}`,
+        mode: 'write' as const,
+      }));
+    }
+    return [{ resourceKey: `workspace:${checkoutId ?? 'active'}`, mode: 'write' }];
+  }
+  const paths = operationPaths(args);
+  if (paths.length > 0) {
+    return paths.map((path) => ({
+      resourceKey: `path:${checkoutId ?? 'active'}:${path.replace(/^\.\//, '')}`,
+      mode: 'write' as const,
+    }));
+  }
+  return [];
+}