@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/plugins/store.ts

@@ -9,6 +9,12 @@ import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/
 import { createFirstPartyPluginAdapterMap } from './first-party-registry';
 import { getExternalPluginAdapter, listExternalPluginAdapters } from './external-adapter';
 import { AssistantPluginError, toAssistantPluginError } from './errors';
+import {
+  findActivePluginCapabilityAuthorization,
+  pluginCapabilityAuthorizationOwnerScope,
+  recordPluginCapabilityAuthorization,
+  type PluginCapabilityAuthorizationGrant,
+} from './capability-authorization-grants';
 import { markControllerContextProjectionDirty } from '../projections/controller-context';
 import { classifyRepositoryCommand } from '../../cli/repositories/command-classifier';
 import {
@@ -24,6 +30,7 @@ import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
   AssistantPluginActionRequest,
+  AssistantPluginAuthorizationContext,
   AssistantPluginManifest,
   AssistantPluginRegistryIndex,
   AssistantPluginRegistryIndexEntry,
@@ -44,7 +51,8 @@ export function assistantPluginScope(pluginId: string, controllerHome?: string):
   return PLUGIN_ADAPTERS.get(pluginId)?.scope ?? (controllerHome ? getExternalPluginAdapter(controllerHome, pluginId)?.scope : undefined);
 }
 
-const PLUGIN_MANIFEST_CACHE_TTL_MS = 5_000;
+const PLUGIN_MANIFEST_LIVE_CACHE_TTL_MS = 5_000;
+const PLUGIN_MANIFEST_STORED_CACHE_TTL_MS = Number.POSITIVE_INFINITY;
 
 
 interface PluginManifestCacheEntry<T> {
@@ -83,6 +91,7 @@ export function controllerPluginRepository(controllerHome: string): RepositoryRe
 
 function adapterMatchesRepository(adapter: AssistantPluginAdapter, repository: RepositoryRecord): boolean {
   const scope = adapter.scope ?? 'repository';
+  if (scope === 'controller_with_repository_overlay') return true;
   return repository.repoId === CONTROLLER_SCOPE_REPO_ID ? scope === 'controller' : scope === 'repository';
 }
 
@@ -101,10 +110,11 @@ function itemCacheKey(controllerHome: string, repoId: string, pluginId: string,
 function readPluginManifestCache<T>(
   cache: Map<string, PluginManifestCacheEntry<T>>,
   key: string,
+  maxAgeMs = PLUGIN_MANIFEST_LIVE_CACHE_TTL_MS,
 ): T | undefined {
   const cached = cache.get(key);
   if (!cached) return undefined;
-  if (Date.now() - cached.createdAt > PLUGIN_MANIFEST_CACHE_TTL_MS) {
+  if (Number.isFinite(maxAgeMs) && Date.now() - cached.createdAt > maxAgeMs) {
     cache.delete(key);
     return undefined;
   }
@@ -231,8 +241,11 @@ function cachedManifestForRepository(
   repoId: string,
   pluginId: string,
 ): AssistantPluginManifest | undefined {
-  return readPluginManifestCache(pluginManifestItemCache, itemCacheKey(controllerHome, repoId, pluginId, true))
-    ?? readPluginManifestCache(pluginManifestItemCache, itemCacheKey(controllerHome, repoId, pluginId, false));
+  return readPluginManifestCache(
+    pluginManifestItemCache,
+    itemCacheKey(controllerHome, repoId, pluginId, true),
+    PLUGIN_MANIFEST_STORED_CACHE_TTL_MS,
+  ) ?? readPluginManifestCache(pluginManifestItemCache, itemCacheKey(controllerHome, repoId, pluginId, false));
 }
 
 function computeManifest(
@@ -244,7 +257,12 @@ function computeManifest(
   const adapter = resolvedAdapter ?? resolvePluginAdapter(controllerHome, pluginId);
   if (!adapter || !adapterMatchesRepository(adapter, repository)) throw new Error(`PLUGIN_NOT_FOUND: ${pluginId}`);
   const previous = readStoredManifest(controllerHome, repository.repoId, pluginId);
-  const built = adapter.buildManifest(previous?.revision ?? 0, previous?.updatedAt, repository.canonicalRoot);
+  const built = adapter.buildManifest(previous?.revision ?? 0, previous?.updatedAt, repository.canonicalRoot, {
+    controllerHome,
+    repoId: repository.repoId,
+    repoRoot: repository.canonicalRoot,
+    controllerScoped: repository.repoId === CONTROLLER_SCOPE_REPO_ID,
+  });
   const changed = !previous || fingerprintManifest(previous) !== fingerprintManifest(built);
   return {
     ...built,
@@ -356,27 +374,63 @@ function enforceConfirmation(action: AssistantPluginActionDescriptor, request: A
   }
 }
 
+export interface PluginActionAuthorizationEvidence {
+  source: 'none' | 'host_permission_model' | 'capability_grant' | 'strong_confirmation';
+  reusable: boolean;
+  capabilityId?: string;
+  target?: { kind: string; id: string };
+  grantId?: string;
+  established?: boolean;
+  lookupError?: string;
+  persistenceError?: string;
+}
+
 function actionForManifest(manifest: AssistantPluginManifest, actionId: string): AssistantPluginActionDescriptor {
   const action = manifest.actions.find((entry) => entry.actionId === actionId);
   if (!action) throw new Error(`PLUGIN_ACTION_NOT_FOUND: ${manifest.pluginId}/${actionId}`);
   return action;
 }
 
-const STANDING_GRANT_SAFE_ACTIONS = new Set([
-  'gmail/create_draft',
-  'gmail/archive_message',
-  'gmail/mark_message_read',
-  'gmail/mark_message_unread',
-  'google_tasks/create_task',
-]);
+function reusableCapabilityId(manifest: AssistantPluginManifest, action: AssistantPluginActionDescriptor): string {
+  const matches = manifest.capabilities
+    .filter((capability) => capability.actions.includes(action.actionId))
+    .map((capability) => capability.capabilityId)
+    .filter(Boolean)
+    .sort();
+  // Overlapping capability groups are ambiguous privilege boundaries. Fall back
+  // to action-local reuse instead of silently choosing a broader capability.
+  return matches.length === 1 ? matches[0]! : `action:${action.actionId}`;
+}
 
-function denyAutomatedWrite(manifest: AssistantPluginManifest, action: AssistantPluginActionDescriptor, origin: AssistantPluginActionExecutionInput['origin']): void {
-  if (origin.surface === 'standing-grant') {
-    const key = `${manifest.pluginId}/${action.actionId}`;
-    if (STANDING_GRANT_SAFE_ACTIONS.has(key) && action.confirmation !== 'strong_confirmation') return;
-    throw new Error(`STANDING_GRANT_ACTION_NOT_ALLOWED: ${key}`);
+const INTERACTIVE_PLUGIN_AUTHORIZATION_SURFACES = new Set(['mcp', 'local-ui', 'chatgpt-action']);
+
+function originMayEstablishCapabilityAuthorization(origin: AssistantPluginActionExecutionInput['origin']): boolean {
+  return INTERACTIVE_PLUGIN_AUTHORIZATION_SURFACES.has(origin.surface);
+}
+
+function authorizationTargetSummary(context: AssistantPluginAuthorizationContext): { kind: string; id: string } {
+  return { kind: context.target.kind, id: context.target.id };
+}
+
+function authorizationError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.slice(0, 500);
+}
+
+function initialAuthorizationEvidence(
+  manifest: AssistantPluginManifest,
+  action: AssistantPluginActionDescriptor,
+): PluginActionAuthorizationEvidence {
+  if (action.confirmation === 'none') return { source: 'none', reusable: false };
+  const capabilityId = reusableCapabilityId(manifest, action);
+  if (action.confirmation === 'strong_confirmation') {
+    return { source: 'strong_confirmation', reusable: false, capabilityId };
   }
-  if (!['schedule', 'reconciliation', 'system', 'assistant-routine'].includes(origin.surface)) return;
+  return { source: 'host_permission_model', reusable: false, capabilityId };
+}
+
+function denyAutomatedWrite(manifest: AssistantPluginManifest, action: AssistantPluginActionDescriptor, origin: AssistantPluginActionExecutionInput['origin']): void {
+  if (!['schedule', 'reconciliation', 'system'].includes(origin.surface)) return;
   if (action.readOnly) return;
   throw new Error(`EXTERNAL_EFFECT_AUTHORIZATION_REQUIRED: ${manifest.pluginId}/${action.actionId} cannot run from ${origin.surface}`);
 }
@@ -406,7 +460,14 @@ export function listAssistantPluginManifests(
   const preferStored = options.preferStored === true && options.forceRefresh !== true;
   const cacheKey = listCacheKey(controllerHome, repository.repoId, preferStored);
   if (options.forceRefresh !== true) {
-    const cached = readPluginManifestCache(pluginManifestListCache, cacheKey);
+    // Stored manifests are persisted snapshots. Their freshness is governed by
+    // explicit registry/config mutation invalidation, not a wall-clock trust
+    // window. Live execution manifests retain the short identity-validation TTL.
+    const cached = readPluginManifestCache(
+      pluginManifestListCache,
+      cacheKey,
+      preferStored ? PLUGIN_MANIFEST_STORED_CACHE_TTL_MS : PLUGIN_MANIFEST_LIVE_CACHE_TTL_MS,
+    );
     if (cached) return cached;
   }
   const manifests = listAssistantPluginIds(controllerHome, repository)
@@ -544,6 +605,7 @@ export interface PluginActionReceipt {
   createdAt: string;
   workId?: string;
   origin?: { surface: string; actor?: string; correlationId?: string };
+  authorization?: PluginActionAuthorizationEvidence;
   result?: Record<string, unknown>;
   error?: { code: string; message: string };
 }
@@ -692,12 +754,73 @@ function remoteEffectWorkForPluginAction(
     throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_CHECKS_PRESENT: ${workId} declares repository checks and cannot be completed by a plugin receipt alone`);
   }
   if (isTerminalWorkContractStatus(work.status)) {
-    if (work.status === 'completed' && receiptId && work.completionReceipt?.receiptId === receiptId) return work;
+    const receiptAlreadyBound = Boolean(receiptId) && (
+      work.completionReceipt?.receiptId === receiptId
+      || work.evidenceRefs.some((evidence) => evidence.evidenceId === receiptId)
+    );
+    if (work.status === 'completed' && receiptAlreadyBound) return work;
     throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_TERMINAL: ${workId} is ${work.status}`);
   }
   return work;
 }
 
+function attributedWorkForPluginAction(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  action: AssistantPluginActionDescriptor,
+  request: AssistantPluginActionRequest,
+): WorkContract | undefined {
+  const workId = request.workId?.trim();
+  if (!workId || action.risk === 'remote_write') return undefined;
+  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+  if (!work) throw new Error(`WORK_PLUGIN_ATTRIBUTION_NOT_FOUND: ${workId}`);
+  if (isTerminalWorkContractStatus(work.status)) {
+    throw new Error(`WORK_PLUGIN_ATTRIBUTION_TERMINAL: ${workId} is ${work.status}`);
+  }
+  return work;
+}
+
+export function finalizeRemoteEffectWorkFromActionReceipt(
+  controllerHome: string,
+  repoId: string,
+  workId: string,
+): WorkContract {
+  const work = getWorkContract({ controllerHome, repoId }, workId);
+  if (!work) throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_NOT_FOUND: ${workId}`);
+  if (work.workKind !== 'remote_effect') {
+    throw new Error(`WORK_REMOTE_EFFECT_FINALIZE_KIND_MISMATCH: ${workId} is ${work.workKind}, expected remote_effect`);
+  }
+  if (work.status === 'completed' && work.completionReceipt?.source === 'remote_effect') return work;
+  if (isTerminalWorkContractStatus(work.status)) {
+    throw new Error(`WORK_REMOTE_EFFECT_FINALIZE_TERMINAL: ${workId} is ${work.status}`);
+  }
+  const receipt = work.evidenceRefs
+    .map((evidence) => evidence.evidenceId ? readPluginActionReceipt(controllerHome, repoId, evidence.evidenceId) : undefined)
+    .find((candidate) => candidate?.workId === workId && candidate.status === 'succeeded');
+  if (!receipt) {
+    throw new Error(`WORK_REMOTE_EFFECT_FINALIZE_RECEIPT_REQUIRED: ${workId} has no successful durable plugin action receipt`);
+  }
+  const remoteReceipt: RemoteEffectCompletionReceipt = {
+    schemaVersion: 1,
+    receiptId: receipt.receiptId,
+    source: 'remote_effect',
+    workId,
+    pluginId: receipt.pluginId,
+    actionId: receipt.actionId,
+    requestId: receipt.requestId,
+    semanticKey: receipt.semanticKey,
+    resultDigest: createHash('sha256').update(JSON.stringify(receipt.result ?? null)).digest('hex'),
+    recordedAt: new Date().toISOString(),
+  };
+  return recordWorkCompletionReceipt(
+    { controllerHome, repoId },
+    workId,
+    remoteReceipt,
+    'completed_remote',
+    'remote_effect',
+  );
+}
+
 function bindRemoteEffectReceiptToWork(
   controllerHome: string,
   repository: RepositoryRecord,
@@ -709,15 +832,17 @@ function bindRemoteEffectReceiptToWork(
   if (receipt.status !== 'succeeded') return remoteEffectWorkForPluginAction(controllerHome, repository, action, request);
   const work = remoteEffectWorkForPluginAction(controllerHome, repository, action, request, receipt.receiptId);
   if (!work) return undefined;
-  if (work.status === 'completed' && work.completionReceipt?.receiptId === receipt.receiptId) return work;
+  if (work.status === 'completed') return work;
+  let updated = work;
   if (!work.evidenceRefs.some((evidence) => evidence.evidenceId === receipt.receiptId)) {
-    appendWorkEvidence({ controllerHome, repoId: repository.repoId }, work.workId, {
+    updated = appendWorkEvidence({ controllerHome, repoId: repository.repoId }, work.workId, {
       evidenceId: receipt.receiptId,
       title: 'typed remote plugin effect completed',
       summary: `${receipt.pluginId}/${receipt.actionId} completed with durable receipt ${receipt.receiptId}.`,
       detailLevel: 'summary',
     });
   }
+  if (action.remoteEffectWorkCompletion !== 'terminal') return updated;
   const remoteReceipt: RemoteEffectCompletionReceipt = {
     schemaVersion: 1,
     receiptId: receipt.receiptId,
@@ -785,8 +910,11 @@ export async function submitAssistantPluginAction(
   deduplicated: boolean;
   result?: Record<string, unknown>;
   receipt: PluginActionReceipt;
+  authorization?: PluginActionAuthorizationEvidence;
   workId?: string;
 }> {
+  const adapter = resolvePluginAdapter(controllerHome, request.pluginId);
+  if (!adapter) throw new Error(`PLUGIN_NOT_FOUND: ${request.pluginId}`);
   const manifest = getAssistantPluginManifest(controllerHome, repository, request.pluginId);
   const action = actionForManifest(manifest, request.actionId);
   if (!manifest.enabled && action.actionId !== 'configure') {
@@ -812,7 +940,7 @@ export async function submitAssistantPluginAction(
     if (request.workId && existing.workId !== request.workId) {
       throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_CONFLICT: ${request.requestId} already belongs to Work ${existing.workId ?? 'none'}`);
     }
-    if (request.workId) bindRemoteEffectReceiptToWork(controllerHome, repository, action, request, existing);
+    if (request.workId && action.risk === 'remote_write') bindRemoteEffectReceiptToWork(controllerHome, repository, action, request, existing);
     return {
       manifest,
       action,
@@ -820,19 +948,29 @@ export async function submitAssistantPluginAction(
       deduplicated: true,
       result: existing.result,
       receipt: existing,
+      authorization: existing.authorization,
       workId: existing.workId,
     };
   }
 
   const createdAt = new Date().toISOString();
   const receiptId = `PLG-${Date.now()}-${createHash('sha256').update(request.requestId).digest('hex').slice(0, 8)}`;
-  const boundRemoteWork = remoteEffectWorkForPluginAction(controllerHome, repository, action, request);
+  const capabilityId = reusableCapabilityId(manifest, action);
+  let authorization = initialAuthorizationEvidence(manifest, action);
+  let authorizationContext: AssistantPluginAuthorizationContext | undefined;
+  let activeAuthorizationGrant: PluginCapabilityAuthorizationGrant | undefined;
   const requiresLocalEffectWork = localSystemActionRequiresWork(
     repository,
     request.pluginId,
     request.actionId,
     normalizedArgs,
   );
+  const boundRemoteWork = action.risk === 'remote_write'
+    ? remoteEffectWorkForPluginAction(controllerHome, repository, action, request)
+    : undefined;
+  const attributedWork = !requiresLocalEffectWork
+    ? attributedWorkForPluginAction(controllerHome, repository, action, request)
+    : undefined;
   const acceptedWork = requiresLocalEffectWork
     ? acceptSubmittedWorkContract(controllerHome, {
         requestId: request.requestId,
@@ -885,10 +1023,63 @@ export async function submitAssistantPluginAction(
       receiptId,
       risk: action.risk,
       confirmation: action.confirmation,
+      capabilityId,
+      authorizationReuseSupported: action.confirmation === 'authorization' && Boolean(adapter.resolveAuthorizationContext),
     },
   });
 
   try {
+    if (action.confirmation === 'authorization'
+      && adapter.resolveAuthorizationContext
+      && originMayEstablishCapabilityAuthorization(request.origin)) {
+      authorizationContext = await adapter.resolveAuthorizationContext({
+        controllerHome,
+        repoId: repository.repoId,
+        repoRoot: repository.canonicalRoot,
+        pluginId: request.pluginId,
+        actionId: request.actionId,
+        requestId: request.requestId,
+        args: normalizedArgs,
+        origin: request.origin,
+        jobId: receiptId,
+        timeoutMs: request.timeoutMs,
+        signal: request.signal,
+      });
+      if (authorizationContext) {
+        authorization = {
+          source: 'host_permission_model',
+          reusable: false,
+          capabilityId,
+          target: authorizationTargetSummary(authorizationContext),
+        };
+        try {
+          activeAuthorizationGrant = findActivePluginCapabilityAuthorization(controllerHome, {
+            ownerScope: pluginCapabilityAuthorizationOwnerScope(request.origin),
+            repoId: repository.repoId,
+            pluginId: request.pluginId,
+            capabilityId,
+            target: authorizationContext.target,
+            scopes: action.scopes,
+            risk: action.risk,
+          });
+          if (activeAuthorizationGrant) {
+            authorization = {
+              source: 'capability_grant',
+              reusable: true,
+              capabilityId,
+              target: authorizationTargetSummary(authorizationContext),
+              grantId: activeAuthorizationGrant.grantId,
+            };
+          }
+        } catch (error) {
+          authorization = {
+            ...authorization,
+            lookupError: authorizationError(error),
+          };
+        }
+      }
+    }
+
     const result = await executeAssistantPluginAction({
       controllerHome,
       repoId: repository.repoId,
@@ -905,15 +1096,49 @@ export async function submitAssistantPluginAction(
         ? Date.now() + Math.max(1, Math.trunc(request.timeoutMs))
         : undefined,
     });
+    if (action.confirmation === 'authorization'
+      && authorizationContext
+      && !activeAuthorizationGrant
+      && originMayEstablishCapabilityAuthorization(request.origin)) {
+      try {
+        const grant = recordPluginCapabilityAuthorization(controllerHome, {
+          ownerScope: pluginCapabilityAuthorizationOwnerScope(request.origin),
+          repoId: repository.repoId,
+          pluginId: request.pluginId,
+          capabilityId,
+          target: authorizationContext.target,
+          scopes: action.scopes,
+          riskCeiling: action.risk,
+          expiresInMinutes: authorizationContext.expiresInMinutes,
+        });
+        authorization = {
+          source: 'host_permission_model',
+          reusable: true,
+          capabilityId,
+          target: authorizationTargetSummary(authorizationContext),
+          grantId: grant.grantId,
+          established: true,
+          ...(authorization.lookupError ? { lookupError: authorization.lookupError } : {}),
+        };
+      } catch (error) {
+        authorization = {
+          ...authorization,
+          reusable: false,
+          persistenceError: authorizationError(error),
+        };
+      }
+    }
+
     let resultWithLineage = result;
     if (boundRemoteWork) {
+      const terminalRemoteEffect = action.remoteEffectWorkCompletion === 'terminal';
       resultWithLineage = {
         ...result,
         work: {
           workId: boundRemoteWork.workId,
           workKind: 'remote_effect',
-          completionOutcome: 'completed_remote',
-          status: 'completed',
+          ...(terminalRemoteEffect ? { completionOutcome: 'completed_remote' as const } : {}),
+          status: terminalRemoteEffect ? 'completed' : 'running',
         },
       };
     }
@@ -961,8 +1186,15 @@ export async function submitAssistantPluginAction(
       semanticKey: key,
       status: 'succeeded',
       createdAt,
-      ...(acceptedWork ? { workId: acceptedWork.workId } : boundRemoteWork ? { workId: boundRemoteWork.workId } : {}),
+      ...(acceptedWork
+        ? { workId: acceptedWork.workId }
+        : boundRemoteWork
+          ? { workId: boundRemoteWork.workId }
+          : attributedWork
+            ? { workId: attributedWork.workId }
+            : {}),
       origin: request.origin,
+      authorization,
       result: resultWithLineage,
     };
     writeJsonAtomic(pluginActionReceiptPath(controllerHome, repository.repoId, receiptId), receipt);
@@ -982,7 +1214,8 @@ export async function submitAssistantPluginAction(
       deduplicated: false,
       result: resultWithLineage,
       receipt,
-      workId: acceptedWork?.workId ?? boundRemoteWork?.workId,
+      authorization,
+      workId: acceptedWork?.workId ?? boundRemoteWork?.workId ?? attributedWork?.workId,
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1018,8 +1251,15 @@ export async function submitAssistantPluginAction(
       semanticKey: key,
       status: 'failed',
       createdAt,
-      ...(acceptedWork ? { workId: acceptedWork.workId } : boundRemoteWork ? { workId: boundRemoteWork.workId } : {}),
+      ...(acceptedWork
+        ? { workId: acceptedWork.workId }
+        : boundRemoteWork
+          ? { workId: boundRemoteWork.workId }
+          : attributedWork
+            ? { workId: attributedWork.workId }
+            : {}),
       origin: request.origin,
+      authorization,
       error: { code, message },
     };
     writeJsonAtomic(pluginActionReceiptPath(controllerHome, repository.repoId, receiptId), receipt);

package/src/runtime/plugins/types.ts

@@ -4,8 +4,24 @@ export type AssistantPluginLifecycleState = 'enabled' | 'disabled' | 'degraded'
 export type AssistantPluginHealthState = 'ready' | 'disabled' | 'degraded' | 'error';
 export type AssistantPluginActionRisk = 'readonly' | 'workspace_write' | 'remote_write' | 'destructive';
 export type AssistantPluginActionConfirmation = 'none' | 'authorization' | 'strong_confirmation';
+export type AssistantPluginForegroundEffect = 'none' | 'possible' | 'required';
 export type AssistantPluginResource = 'repo-state' | 'workspace' | 'remote' | 'git-refs' | 'provider-state';
 
+export interface AssistantPluginAuthorizationTarget {
+  /** Stable provider resource class, for example ios-physical-device. */
+  kind: string;
+  /** Stable exact provider identity. Ephemeral request/session ids must never be used here. */
+  id: string;
+  /** Optional provider identity fence. A changed fingerprint invalidates reuse. */
+  identityFingerprint?: string;
+}
+
+export interface AssistantPluginAuthorizationContext {
+  target: AssistantPluginAuthorizationTarget;
+  /** Optional grant lifetime. The grant authority applies its own upper bound. */
+  expiresInMinutes?: number;
+}
+
 export interface AssistantPluginPermissionScope {
   scope: string;
   mode: 'read' | 'write';
@@ -38,6 +54,14 @@ export interface AssistantPluginActionDescriptor {
   defaultTimeoutMs: number;
   cancellable: boolean;
   idempotent: boolean;
+  /**
+   * Successful remote-write actions normally append a durable Work receipt only.
+   * Set terminal only when this action itself is authoritative semantic completion
+   * for a bound remote_effect Work.
+   */
+  remoteEffectWorkCompletion?: 'intermediate' | 'terminal';
+  executionMode?: 'runtime' | 'lightweight_process';
+  foregroundEffect?: AssistantPluginForegroundEffect;
   scopes: string[];
   resourceClaims: AssistantPluginActionResourceClaim[];
   argumentsSchema: Record<string, unknown>;
@@ -128,12 +152,21 @@ export interface AssistantPluginActionExecutionInput {
   providerIdentityPrevalidated?: boolean;
 }
 
-export type AssistantPluginScope = 'repository' | 'controller';
+export type AssistantPluginScope = 'repository' | 'controller' | 'controller_with_repository_overlay';
+
+export interface AssistantPluginBuildContext {
+  controllerHome: string;
+  repoId: string;
+  repoRoot: string;
+  controllerScoped: boolean;
+}
 
 export interface AssistantPluginAdapter {
   pluginId: string;
   scope?: AssistantPluginScope;
-  buildManifest(previousRevision?: number, previousUpdatedAt?: string, repoRoot?: string): AssistantPluginManifest;
+  buildManifest(previousRevision?: number, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest;
+  /** Resolve an exact stable resource identity for reusable authorization-class actions. */
+  resolveAuthorizationContext?(input: AssistantPluginActionExecutionInput): Promise<AssistantPluginAuthorizationContext | undefined>;
   executeAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>>;
   /** Defaults to true. External providers can defer routine health refresh until the normal manifest cache expires. */
   shouldRefreshManifestAfterAction?(actionId: string): boolean;