packages/plugins/sdk/src/protocol.ts

@@ -379,6 +379,13 @@ export interface PluginEnvironmentLease {
 
 export interface PluginEnvironmentAcquireLeaseParams extends PluginEnvironmentDriverBaseParams {
   runId: string;
+  /**
+   * UUID of the agent the run is being acquired for. Omitted only for ad-hoc
+   * invocations (e.g. operator-initiated environment test probes) where no
+   * agent context exists. Plugins should treat undefined as "no per-agent
+   * partitioning available" and fall back to environment-level behavior.
+   */
+  agentId?: string;
   workspaceMode?: string;
   requestedCwd?: string;
 }
@@ -386,6 +393,14 @@ export interface PluginEnvironmentAcquireLeaseParams extends PluginEnvironmentDr
 export interface PluginEnvironmentResumeLeaseParams extends PluginEnvironmentDriverBaseParams {
   providerLeaseId: string;
   leaseMetadata?: Record<string, unknown>;
+  /**
+   * UUID of the agent the run is being resumed for. Symmetric with
+   * `PluginEnvironmentAcquireLeaseParams.agentId`. Plugins can compare this
+   * to the agentId they stored in `leaseMetadata` at acquire time; if it
+   * doesn't match, return `{ providerLeaseId: null, metadata: { expired: true } }`
+   * to force the host to create a fresh lease for the current agent.
+   */
+  agentId?: string;
 }
 
 export interface PluginEnvironmentReleaseLeaseParams extends PluginEnvironmentDriverBaseParams {

server/src/__tests__/heartbeat-plugin-environment.test.ts

@@ -209,6 +209,7 @@ describeEmbeddedPostgres("heartbeat plugin environments", () => {
       issueId: null,
       config: { template: "base" },
       runId: run!.id,
+      agentId,
       workspaceMode: "shared_workspace",
     });
     await vi.waitFor(() => {
@@ -426,6 +427,7 @@ describeEmbeddedPostgres("heartbeat plugin environments", () => {
       issueId,
       config: { template: "new" },
       runId: run!.id,
+      agentId,
       workspaceMode: "shared_workspace",
     });
   }, 15_000);

server/src/routes/agents.ts

@@ -319,6 +319,7 @@ export function agentRoutes(
         companyId: input.companyId,
         environment,
         issueId: null,
+        agentId: null,
         heartbeatRunId: null,
         persistedExecutionWorkspace: null,
       });

server/src/services/environment-run-orchestrator.ts

@@ -206,6 +206,7 @@ export function environmentRunOrchestrator(
     companyId: string;
     environment: Environment;
     issueId: string | null;
+    agentId: string;
     heartbeatRunId: string;
     persistedExecutionWorkspace: Pick<ExecutionWorkspace, "id" | "mode"> | null;
   }): Promise<EnvironmentRuntimeLeaseRecord> {
@@ -280,6 +281,7 @@ export function environmentRunOrchestrator(
       companyId: input.companyId,
       environment,
       issueId: input.issueId,
+      agentId: input.agentId,
       heartbeatRunId: input.heartbeatRunId,
       persistedExecutionWorkspace: input.persistedExecutionWorkspace,
     });

server/src/services/environment-runtime.ts

@@ -103,6 +103,14 @@ export interface EnvironmentDriverAcquireInput {
   companyId: string;
   environment: Environment;
   issueId: string | null;
+  /**
+   * UUID of the owning agent. Null for ad-hoc invocations (e.g.
+   * operator-initiated `Test` probes) that are not tied to a specific agent.
+   * Threaded through to plugin-backed sandbox providers so they can scope
+   * lease state (PVCs, subdirs, etc.) per-agent without needing to look it
+   * up via callback.
+   */
+  agentId: string | null;
   /**
    * UUID of the owning heartbeat run, or null for ad-hoc invocations
    * (e.g. operator-initiated `Test` probes) that are not tied to a run.
@@ -468,6 +476,7 @@ function createSandboxEnvironmentDriver(
                 config: workerConfig,
                 providerLeaseId: reusableLease.providerLeaseId,
                 leaseMetadata: reusableLease.metadata ?? undefined,
+                ...(input.agentId ? { agentId: input.agentId } : {}),
               },
               resolvePluginSandboxRpcTimeoutMs(workerConfig),
             ).then((resumed) =>
@@ -489,6 +498,7 @@ function createSandboxEnvironmentDriver(
             // UUID so providers that validate or persist the runId still see
             // a well-formed identifier.
             runId: input.heartbeatRunId ?? randomUUID(),
+            ...(input.agentId ? { agentId: input.agentId } : {}),
             workspaceMode: input.executionWorkspaceMode ?? undefined,
           },
           resolvePluginSandboxRpcTimeoutMs(workerConfig),
@@ -897,6 +907,7 @@ function createPluginEnvironmentDriver(
         issueId: input.issueId,
         config: parsed.config.driverConfig,
         runId: input.heartbeatRunId ?? randomUUID(),
+        ...(input.agentId ? { agentId: input.agentId } : {}),
         workspaceMode: input.executionWorkspaceMode ?? undefined,
       });
 
@@ -1110,6 +1121,11 @@ export function environmentRuntimeService(
       companyId: string;
       environment: Environment;
       issueId: string | null;
+      /**
+       * UUID of the owning agent. Null for ad-hoc invocations (e.g.
+       * operator-initiated `Test` probes).
+       */
+      agentId: string | null;
       /** Null for ad-hoc invocations (e.g. operator-initiated `Test` probes). */
       heartbeatRunId: string | null;
       persistedExecutionWorkspace: Pick<ExecutionWorkspace, "id" | "mode"> | null;
@@ -1126,6 +1142,7 @@ export function environmentRuntimeService(
         companyId: input.companyId,
         environment: input.environment,
         issueId: input.issueId,
+        agentId: input.agentId,
         heartbeatRunId: input.heartbeatRunId,
         executionWorkspaceId: leaseContext.executionWorkspaceId,
         executionWorkspaceMode: leaseContext.executionWorkspaceMode,