@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/tool-system/builtin/agent.js

@@ -13,6 +13,7 @@ import { createTranscriptTranslator } from "./agent-transcript-translator.js";
 import { notificationQueue } from "./agent-notifications.js";
 import { nanoid } from "nanoid";
 import { logger } from "../../logging/logger.js";
+import { applyAgentProgressPhase, applyAgentProgressUsage, initialAgentProgress, reduceAgentProgress, } from "./agent-progress.js";
 /**
  * Invoke a stream callback that came from outside the engine's own
  * TurnLoop wrap (e.g. `subAgentSpawner.parentStream`, which is the
@@ -69,6 +70,8 @@ export function resolveAgentTypeOverrides(agentType, registry) {
         maxTurns: def.maxTurns,
         toolAllowlist: def.tools,
         skillAllowlist: namespacePluginSkills(def.skills, def.source, def.pluginName),
+        sandboxMode: def.sandbox,
+        mcpAllowlist: def.mcp,
         appendSystemPrompt: def.systemPrompt,
     };
 }
@@ -273,10 +276,34 @@ streamOverride) {
     if (usage)
         opts.recordBilledUsage?.(usage);
     const finalText = text || `Agent completed but produced no text output.`;
-    safeEmit(startEndSink, { type: "agent_end", agentId, name, description, text: finalText, agentType });
+    safeEmit(startEndSink, {
+        type: "agent_end",
+        agentId,
+        name,
+        description,
+        text: finalText,
+        agentType,
+    });
     emitSubAgentHook(opts.hooks, "subagent_finish", { agentId, description, text: finalText });
     return finalText;
 }
+function createAgentProgressTracker(agentId) {
+    let progress = initialAgentProgress();
+    return {
+        current: () => progress,
+        onEvent: (event) => {
+            progress = reduceAgentProgress(progress, event);
+            asyncAgentRegistry.updateProgress(agentId, progress);
+        },
+        onRuntime: (event) => {
+            progress =
+                event.type === "usage"
+                    ? applyAgentProgressUsage(progress, event.usage)
+                    : applyAgentProgressPhase(progress, event.phase, Date.now(), event.toolName);
+            asyncAgentRegistry.updateProgress(agentId, progress);
+        },
+    };
+}
 export async function agentTool(args, ctx) {
     const prompt = args.prompt;
     const description = args.description || "sub-agent";
@@ -329,10 +356,13 @@ export async function agentTool(args, ctx) {
     // through AgentCancel(agent_id).
     if (runInBackground) {
         if (asyncAgentRegistry.runningCount() >= MAX_BACKGROUND_AGENTS) {
-            return `Error: too many background agents running (limit ${MAX_BACKGROUND_AGENTS}). ` +
-                `Wait for some to finish or cancel one with AgentCancel(agent_id) before launching more.`;
+            return (`Error: too many background agents running (limit ${MAX_BACKGROUND_AGENTS}). ` +
+                `Wait for some to finish or cancel one with AgentCancel(agent_id) before launching more.`);
         }
         const controller = new AbortController();
+        const runtimeGeneration = asyncAgentRegistry.allocateRuntimeGeneration(agentId);
+        const progressTracker = createAgentProgressTracker(agentId);
+        let liveLease;
         asyncAgentRegistry.register({
             agentId,
             name,
@@ -341,6 +371,9 @@ export async function agentTool(args, ctx) {
             // Tag with the spawning session so the parent Engine.run waits only on
             // its own background agents (hasRunningForSession).
             sessionId: ctx?.sessionId,
+            childSessionId: agentId,
+            runtimeGeneration,
+            progress: progressTracker.current(),
             status: "running",
             startedAt: Date.now(),
             abort: () => controller.abort(),
@@ -371,15 +404,52 @@ export async function agentTool(args, ctx) {
             model: overrides.model,
             toolAllowlist: overrides.toolAllowlist,
             skillAllowlist: overrides.skillAllowlist,
+            sandboxMode: overrides.sandboxMode,
+            mcpAllowlist: overrides.mcpAllowlist,
             appendSystemPrompt: overrides.appendSystemPrompt,
             readOnlySession: overrides.resolvedType === "researcher" || overrides.resolvedType === "explorer",
             hooks: ctx?.hooks,
             recordBilledUsage: ctx?.recordBilledUsage,
+            runtimeGeneration,
+            bindLiveControl: (control, ownerToken) => {
+                const lease = asyncAgentRegistry.acquireWriterLease(control.childSessionId, control.runtimeGeneration, ownerToken);
+                if (!lease)
+                    return false;
+                if (!asyncAgentRegistry.bindLiveControl(agentId, control, lease)) {
+                    asyncAgentRegistry.releaseWriterLease(lease);
+                    return false;
+                }
+                liveLease = lease;
+                return lease;
+            },
+            closeLiveControl: (_control, lease) => {
+                if (lease)
+                    asyncAgentRegistry.closeDirectionIntake(agentId, lease);
+            },
+            onProgressEvent: progressTracker.onEvent,
+            onAgentProgress: progressTracker.onRuntime,
             signal: controller.signal,
         }, parentStream, // uiStream: agent_start/end → main feed
         transcriptSink)
             .then((text) => {
-            asyncAgentRegistry.markCompleted(agentId);
+            if (controller.signal.aborted) {
+                if (liveLease)
+                    asyncAgentRegistry.completeTerminal(agentId, "cancelled", liveLease);
+                else
+                    asyncAgentRegistry.markCancelled(agentId);
+                void ctx?.hooks?.emit("notification", {
+                    kind: "agent_cancelled",
+                    agentId,
+                    name,
+                    description,
+                });
+                return;
+            }
+            const transitioned = liveLease
+                ? asyncAgentRegistry.completeTerminal(agentId, "completed", liveLease)
+                : (asyncAgentRegistry.markCompleted(agentId), true);
+            if (!transitioned)
+                return;
             // External-readable copy of the result (tail / cross-session history).
             // Best-effort; never blocks the completion path.
             void writeAgentOutputFile(agentId, {
@@ -442,7 +512,10 @@ export async function agentTool(args, ctx) {
                 // User-initiated cancel: mark status but do NOT enqueue —
                 // the main agent doesn't need a follow-up turn. Dock still
                 // shows the "cancelled" badge for the fade window.
-                asyncAgentRegistry.markCancelled(agentId);
+                if (liveLease)
+                    asyncAgentRegistry.completeTerminal(agentId, "cancelled", liveLease);
+                else
+                    asyncAgentRegistry.markCancelled(agentId);
                 void ctx?.hooks?.emit("notification", {
                     kind: "agent_cancelled",
                     agentId,
@@ -451,7 +524,11 @@ export async function agentTool(args, ctx) {
                 });
                 return;
             }
-            asyncAgentRegistry.markFailed(agentId);
+            const transitioned = liveLease
+                ? asyncAgentRegistry.completeTerminal(agentId, "failed", liveLease)
+                : (asyncAgentRegistry.markFailed(agentId), true);
+            if (!transitioned)
+                return;
             void writeAgentOutputFile(agentId, {
                 status: "failed",
                 body: err.message,
@@ -535,6 +612,7 @@ function recordCompletedSyncAgent(opts) {
         sessionId: opts.parentSessionId,
         // agent_id === childSid: the resumable session lives at sessions/<agentId>/.
         childSessionId: opts.agentId,
+        runtimeGeneration: opts.runtimeGeneration,
         status: "completed",
         startedAt: now,
         finishedAt: now,
@@ -566,6 +644,10 @@ async function runSyncSubAgent(args) {
     // the background, so the finally block leaves the parent-abort listener with
     // the background handlers instead of removing it.
     let handedOff = false;
+    const childSessionId = resumeSessionId ?? agentId;
+    const runtimeGeneration = asyncAgentRegistry.allocateRuntimeGeneration(childSessionId);
+    const progressTracker = createAgentProgressTracker(agentId);
+    let liveBinding;
     // Run the agent, but don't necessarily await it to completion: race the run
     // against the auto-background timer. The run promise is shared between the
     // inline await and (if we hand off) the background completion handlers, so
@@ -580,11 +662,30 @@ async function runSyncSubAgent(args) {
         model: overrides.model,
         toolAllowlist: overrides.toolAllowlist,
         skillAllowlist: overrides.skillAllowlist,
+        sandboxMode: overrides.sandboxMode,
+        mcpAllowlist: overrides.mcpAllowlist,
         appendSystemPrompt: overrides.appendSystemPrompt,
         readOnlySession: overrides.resolvedType === "researcher" || overrides.resolvedType === "explorer",
         resumeSessionId,
         hooks: ctx?.hooks,
         recordBilledUsage: ctx?.recordBilledUsage,
+        runtimeGeneration,
+        bindLiveControl: (control, ownerToken) => {
+            const lease = asyncAgentRegistry.acquireWriterLease(control.childSessionId, control.runtimeGeneration, ownerToken);
+            if (!lease)
+                return false;
+            liveBinding = { control, lease };
+            return lease;
+        },
+        closeLiveControl: (_control, lease) => {
+            if (!lease)
+                return;
+            if (handedOff)
+                return asyncAgentRegistry.closeDirectionIntake(agentId, lease);
+            return asyncAgentRegistry.releaseWriterLease(lease);
+        },
+        onProgressEvent: progressTracker.onEvent,
+        onAgentProgress: progressTracker.onRuntime,
         signal: syncController.signal,
     });
     // Sentinel that the timer resolves with, so we can tell "agent finished" from
@@ -599,7 +700,12 @@ async function runSyncSubAgent(args) {
     try {
         // If there's no timer (threshold 0/∞ disabled), just await as before.
         const winner = timerPromise
-            ? await Promise.race([runPromise.then((t) => ({ ok: true, text: t })).catch((e) => ({ ok: false, err: e })), timerPromise])
+            ? await Promise.race([
+                runPromise
+                    .then((t) => ({ ok: true, text: t }))
+                    .catch((e) => ({ ok: false, err: e })),
+                timerPromise,
+            ])
             : { ok: true, text: await runPromise };
         if (winner === BG_HANDOFF) {
             // Threshold elapsed while the agent is STILL running. Detach it into the
@@ -616,6 +722,10 @@ async function runSyncSubAgent(args) {
                 hooks: ctx?.hooks,
                 parentSignal,
                 onParentAbort,
+                childSessionId,
+                runtimeGeneration,
+                liveBinding,
+                progress: progressTracker.current(),
                 // The agent_start fired in runSubAgent put the UI card into 'working'.
                 // runSubAgent's own agent_end (line ~299) only fires if spawn() RESOLVES;
                 // on failure/cancel it throws before that, so the card would hang
@@ -644,14 +754,26 @@ async function runSyncSubAgent(args) {
                 agentType: overrides.resolvedType,
                 description,
                 parentSessionId: ctx?.sessionId,
+                runtimeGeneration,
             });
             return winner.text;
         }
         throw winner.err;
     }
     catch (err) {
-        emitSubAgentHook(ctx?.hooks, "subagent_error", { agentId, description, error: err.message });
-        safeEmit(parentStream, { type: "agent_end", agentId, name, description, error: err.message, agentType: overrides.resolvedType });
+        emitSubAgentHook(ctx?.hooks, "subagent_error", {
+            agentId,
+            description,
+            error: err.message,
+        });
+        safeEmit(parentStream, {
+            type: "agent_end",
+            agentId,
+            name,
+            description,
+            error: err.message,
+            agentType: overrides.resolvedType,
+        });
         if (parentSignal?.aborted)
             return "Agent was aborted.";
         return `Agent error: ${err.message}`;
@@ -674,7 +796,7 @@ async function runSyncSubAgent(args) {
  * a running (then completed/failed) background agent. Never aborts the agent.
  */
 function handoffToBackground(runPromise, controller, meta) {
-    const { agentId, name, description, agentType, sessionId, hooks, uiStream } = meta;
+    const { agentId, name, description, agentType, sessionId, hooks, uiStream, childSessionId, runtimeGeneration, liveBinding, progress, } = meta;
     // The agent outlives the spawning turn now, so parent-turn abort must NOT
     // cascade to it (same contract as an explicit background agent). Detach the
     // parent listener; cancellation from here on goes through AgentCancel.
@@ -685,10 +807,21 @@ function handoffToBackground(runPromise, controller, meta) {
         agentType,
         description,
         sessionId,
+        childSessionId,
+        runtimeGeneration,
+        progress,
         status: "running",
         startedAt: Date.now(),
         abort: () => controller.abort(),
     });
+    if (liveBinding &&
+        !asyncAgentRegistry.bindLiveControl(agentId, liveBinding.control, liveBinding.lease)) {
+        logger.warn("agent_live_control.handoff_bind_failed", {
+            agentId,
+            childSessionId,
+            runtimeGeneration,
+        });
+    }
     // Tell the UI this agent is now running in the BACKGROUND (still working,
     // just detached from the parent turn). Without this the card's only signals
     // are agent_start (looks foreground) and the eventual agent_end — so during
@@ -701,7 +834,21 @@ function handoffToBackground(runPromise, controller, meta) {
     ensureAgentHeartbeat();
     runPromise
         .then((text) => {
-        asyncAgentRegistry.markCompleted(agentId);
+        if (controller.signal.aborted) {
+            if (liveBinding) {
+                asyncAgentRegistry.completeTerminal(agentId, "cancelled", liveBinding.lease);
+            }
+            else {
+                asyncAgentRegistry.markCancelled(agentId);
+            }
+            void hooks?.emit("notification", { kind: "agent_cancelled", agentId, name, description });
+            return;
+        }
+        const transitioned = liveBinding
+            ? asyncAgentRegistry.completeTerminal(agentId, "completed", liveBinding.lease)
+            : (asyncAgentRegistry.markCompleted(agentId), true);
+        if (!transitioned)
+            return;
         void writeAgentOutputFile(agentId, {
             status: "completed",
             body: text,
@@ -710,24 +857,53 @@ function handoffToBackground(runPromise, controller, meta) {
             onError: (m, meta) => logger.warn(m, meta),
         });
         if (sessionId) {
-            notificationQueue.enqueue({ agentId, name, description, status: "completed", finalText: text, enqueuedAt: Date.now() }, sessionId);
+            notificationQueue.enqueue({
+                agentId,
+                name,
+                description,
+                status: "completed",
+                finalText: text,
+                enqueuedAt: Date.now(),
+            }, sessionId);
         }
         else {
             logger.warn("agent_completion_without_session", { agentId, name, status: "completed" });
         }
-        void hooks?.emit("notification", { kind: "agent_completed", agentId, name, description, finalText: text });
+        void hooks?.emit("notification", {
+            kind: "agent_completed",
+            agentId,
+            name,
+            description,
+            finalText: text,
+        });
     })
         .catch((err) => {
         // runSubAgent threw before its success agent_end, so the UI card is still
         // 'working'. Close it out with a terminal agent_end{error} (mirrors the
         // synchronous catch at the agentTool level).
-        safeEmit(uiStream, { type: "agent_end", agentId, name, description, error: err.message, agentType });
+        safeEmit(uiStream, {
+            type: "agent_end",
+            agentId,
+            name,
+            description,
+            error: err.message,
+            agentType,
+        });
         if (controller.signal.aborted) {
-            asyncAgentRegistry.markCancelled(agentId);
+            if (liveBinding) {
+                asyncAgentRegistry.completeTerminal(agentId, "cancelled", liveBinding.lease);
+            }
+            else {
+                asyncAgentRegistry.markCancelled(agentId);
+            }
             void hooks?.emit("notification", { kind: "agent_cancelled", agentId, name, description });
             return;
         }
-        asyncAgentRegistry.markFailed(agentId);
+        const transitioned = liveBinding
+            ? asyncAgentRegistry.completeTerminal(agentId, "failed", liveBinding.lease)
+            : (asyncAgentRegistry.markFailed(agentId), true);
+        if (!transitioned)
+            return;
         void writeAgentOutputFile(agentId, {
             status: "failed",
             body: err.message,
@@ -736,12 +912,25 @@ function handoffToBackground(runPromise, controller, meta) {
             onError: (m, meta) => logger.warn(m, meta),
         });
         if (sessionId) {
-            notificationQueue.enqueue({ agentId, name, description, status: "failed", error: err.message, enqueuedAt: Date.now() }, sessionId);
+            notificationQueue.enqueue({
+                agentId,
+                name,
+                description,
+                status: "failed",
+                error: err.message,
+                enqueuedAt: Date.now(),
+            }, sessionId);
         }
         else {
             logger.warn("agent_completion_without_session", { agentId, name, status: "failed" });
         }
-        void hooks?.emit("notification", { kind: "agent_failed", agentId, name, description, error: err.message });
+        void hooks?.emit("notification", {
+            kind: "agent_failed",
+            agentId,
+            name,
+            description,
+            error: err.message,
+        });
     });
 }
 // ─── AgentStatus / AgentCancel — companions to run_in_background ─
@@ -784,13 +973,17 @@ export async function agentStatusTool(args, ctx) {
         return list
             .map((e) => {
             const dur = ((e.finishedAt ?? Date.now()) - e.startedAt) / 1000;
-            return `${e.agentId} [${e.status}] ${e.description} (${dur.toFixed(1)}s)`;
+            const progress = e.status === "running" && e.progress ? ` — ${e.progress.summary}` : "";
+            return `${e.agentId} [${e.status}] ${e.description}${progress} (${dur.toFixed(1)}s)`;
         })
             .join("\n");
     }
     const e = asyncAgentRegistry.get(agentId);
     if (!e)
         return `Error: agent_id "${agentId}" not found.`;
+    if (ctx?.sessionId && e.sessionId !== ctx.sessionId) {
+        return `Error: agent_id "${agentId}" is not in this session.`;
+    }
     const dur = ((e.finishedAt ?? Date.now()) - e.startedAt) / 1000;
     const lines = [
         `agent_id: ${e.agentId}`,
@@ -808,6 +1001,9 @@ export async function agentStatusTool(args, ctx) {
         lines.push("", "(cancelled — no result delivered)");
     }
     else if (e.status === "running") {
+        if (e.progress) {
+            lines.push(`phase:    ${e.progress.phase}`, `progress: ${e.progress.summary}`, `tokens:   ${e.progress.tokens.total}`, `observed: ${e.progress.observedAt}`);
+        }
         lines.push("", "(still running — call AgentStatus again later)");
     }
     return lines.join("\n");
@@ -838,9 +1034,7 @@ export async function agentCancelTool(args) {
         return `Agent ${agentId} is already ${e.status}; nothing to cancel.`;
     }
     const ok = asyncAgentRegistry.cancel(agentId);
-    return ok
-        ? `Agent ${agentId} cancelled.`
-        : `Failed to cancel agent ${agentId}.`;
+    return ok ? `Agent ${agentId} cancelled.` : `Failed to cancel agent ${agentId}.`;
 }
 // ─── AgentSendInput — continue a previously-spawned sub-agent ────
 export const agentSendInputToolDef = {
@@ -870,24 +1064,47 @@ export const agentSendInputToolDef = {
                 description: "The follow-up instruction. The agent already remembers its earlier work — " +
                     "send only what's new (feedback, the next step, a question).",
             },
+            delivery: {
+                type: "string",
+                enum: ["next-safe-point", "interrupt-and-redrive"],
+                description: "For a running child: queue at the next complete model/tool boundary (default), " +
+                    "or cooperatively interrupt the active batch and serially redrive the same runtime.",
+            },
         },
+        additionalProperties: false,
         required: ["agent_id", "prompt"],
     },
 };
 export async function agentSendInputTool(args, ctx) {
+    const allowedKeys = new Set(["agent_id", "prompt", "delivery", "__signal"]);
+    if (Object.keys(args).some((key) => !allowedKeys.has(key))) {
+        return "Error: invalid-request: AgentSendInput accepts only agent_id, prompt, and delivery.";
+    }
     const agentId = args.agent_id?.trim();
     const prompt = args.prompt;
+    const rawDelivery = args.delivery;
     if (!agentId)
         return "Error: agent_id is required.";
     if (!prompt)
         return "Error: prompt is required.";
+    if (rawDelivery !== undefined &&
+        rawDelivery !== "next-safe-point" &&
+        rawDelivery !== "interrupt-and-redrive") {
+        return "Error: invalid delivery. Expected next-safe-point or interrupt-and-redrive.";
+    }
+    const delivery = rawDelivery ?? "next-safe-point";
     if (!ctx?.subAgentSpawner) {
         return "Error: Agent tool is not configured (no subAgentSpawner in ctx).";
     }
     // Same flat-hierarchy rule as Agent: a sub-agent cannot continue (or spawn)
     // another sub-agent. Layered with the NESTED_AGENT_TOOLS strip in engine.ts.
     if (ctx.isSubAgent === true) {
-        return "Error: nested agents are not supported. Sub-agents cannot send input to other sub-agents. Complete the task directly using your available tools.";
+        return JSON.stringify({
+            status: "rejected",
+            reason: "not-direct-parent",
+            rejectedAt: Date.now(),
+            message: "Nested agents are not supported. Sub-agents cannot send input to other sub-agents.",
+        });
     }
     const spawner = ctx.subAgentSpawner;
     const parentSignal = args.__signal;
@@ -910,17 +1127,41 @@ export async function agentSendInputTool(args, ctx) {
             `It may never have run or its session was cleaned up. ` +
             `Re-spawn with Agent(...) and a complete task description.`);
     }
-    // Concurrency guard: a sub-agent that's still running (e.g. it auto-moved to
-    // the background and hasn't finished) owns its child session. Resuming now
-    // would build a SECOND child Engine that resumes the SAME session and appends
-    // to the SAME transcript concurrently — sub-agents have no per-session
-    // `active` lock (the protocol layer's serialization only covers top-level
-    // sessions), so the two writers interleave and can corrupt the transcript.
-    // Refuse until it finishes (or is cancelled).
+    // A running target owns its transcript writer lease. This branch is route-only:
+    // registry validation + the bound live runtime enqueue the direction envelope;
+    // it must never construct/resume a second child Engine.
     if (entry?.status === "running") {
-        return (`Error: sub-agent "${agentId}" is still running. ` +
-            `Wait for it to finish (poll with AgentStatus), or cancel it with ` +
-            `AgentCancel, before sending it more input.`);
+        const ack = await asyncAgentRegistry.routeDirection({
+            callerSessionId: ctx.sessionId ?? "",
+            callerIsSubAgent: false,
+            agentId,
+            prompt,
+            delivery,
+        });
+        return JSON.stringify(ack);
+    }
+    if (entry?.status === "cancelling" || asyncAgentRegistry.getWriterLease(resumeSessionId)) {
+        return `Error: sub-agent "${agentId}" is still cancelling; wait for its previous runtime to fully exit.`;
+    }
+    const callerSessionId = ctx.sessionId ?? "";
+    if (entry) {
+        if (!callerSessionId || entry.sessionId !== callerSessionId) {
+            return `Error: caller is not the direct parent of sub-agent "${agentId}" (not in this session).`;
+        }
+    }
+    else {
+        const persistedParent = spawner.getSessionParentId?.(resumeSessionId);
+        if (!callerSessionId || persistedParent === undefined || persistedParent === null) {
+            return `Error: cannot verify the direct parent of sub-agent "${agentId}"; continuation is denied.`;
+        }
+        if (persistedParent !== callerSessionId) {
+            return `Error: caller is not the direct parent of sub-agent "${agentId}" (not in this session).`;
+        }
+    }
+    if (delivery === "interrupt-and-redrive") {
+        return (`Error: sub-agent "${agentId}" is no longer running; ` +
+            `interrupt-and-redrive cannot interrupt a terminal target. ` +
+            `Omit delivery to use the existing transcript continuation path.`);
     }
     const name = entry?.name;
     const description = entry?.description ?? "sub-agent continuation";

package/dist/tool-system/builtin/background-jobs.d.ts

@@ -44,12 +44,39 @@ export interface BackgroundJobEntry {
     ccSessionId?: string;
     /** Files the external agent changed (parsed from its transcript, #6). */
     changedFiles?: string[];
-    /** Working directory for jobs that operate on the filesystem, e.g. DriveAgent. */
+    /** Directory in which the external job was launched. This is an audit/listing
+     *  snapshot, not necessarily the workspace the job ultimately writes. */
+    launchCwd?: string;
+    /** @deprecated Back-compatible serialized alias of launchCwd. */
     cwd?: string;
+    /** Normalized snapshot of the declared effective workspace cwd. Preserved
+     *  separately from its resolved root for mixed git-resolution fallback. */
+    effectiveWorkspaceCwd?: string;
+    /** Canonical source workspace before per-run isolation. Unlike
+     * effectiveWorkspaceRoot, this remains the main checkout for linked
+     * worktrees so later writers targeting that checkout can auto-isolate too. */
+    workspaceRoot?: string;
+    /** Canonical conflict identity: git worktree root when resolvable, otherwise
+     *  the normalized effective workspace cwd. */
+    effectiveWorkspaceRoot?: string;
+    /** Git common dir identifies the main repository shared by linked worktrees.
+     *  Conflict checks deliberately compare worktree roots, so separate
+     *  worktrees of the same repository remain isolated. */
+    gitCommonDir?: string;
+    /** Whether effectiveWorkspaceRoot came from git or the cwd fallback. */
+    effectiveWorkspaceKind?: "git-worktree" | "cwd";
     /** DriveAgent prompt summary, separate from the UI-oriented description. */
     promptSummary?: string;
     /** External CLI kind for DriveAgent jobs. */
     cli?: ExternalCliKind;
+    /** DriveAgent workspace lifecycle metadata. */
+    isolation?: "current" | "worktree" | "none";
+    worktreePath?: string;
+    worktreeBranch?: string;
+    worktreeBaseRef?: string;
+    worktreeCleanup?: "auto" | "keep" | "detach" | "discard";
+    worktreeBranchPrefix?: string;
+    worktreeLifecycle?: "running" | "kept" | "detached" | "discarded" | "cleanup-failed";
     /** Client message that launched this external job. */
     originClientMessageId?: string;
     /** Optional cancellation hook for jobs backed by a live process. It may
@@ -63,12 +90,27 @@ export interface BackgroundJobOutcome {
     finalText?: string;
     ccSessionId?: string;
     changedFiles?: string[];
+    worktreeLifecycle?: "running" | "kept" | "detached" | "discarded" | "cleanup-failed";
 }
 export interface BackgroundJobStartOptions {
     kind?: BackgroundJobKind;
+    /** Preferred name for the external process's launch directory. */
+    launchCwd?: string;
+    /** @deprecated Back-compatible alias for launchCwd. */
     cwd?: string;
+    /** Optional host-declared workspace the job is expected to write. Defaults
+     *  to launchCwd. This avoids guessing later shell `cd` commands. */
+    effectiveWorkspaceCwd?: string;
+    /** Source workspace before a job-specific worktree was created. */
+    workspaceRoot?: string;
     promptSummary?: string;
     cli?: ExternalCliKind;
+    isolation?: "current" | "worktree" | "none";
+    worktreePath?: string;
+    worktreeBranch?: string;
+    worktreeBaseRef?: string;
+    worktreeCleanup?: "auto" | "keep" | "detach" | "discard";
+    worktreeBranchPrefix?: string;
     originClientMessageId?: string;
     abort?: () => void | BackgroundJobOutcome | Promise<void | BackgroundJobOutcome>;
 }
@@ -83,13 +125,24 @@ declare class BackgroundJobRegistry {
     get(jobId: string): BackgroundJobEntry | undefined;
     /** Persist artifacts discovered while a running job is winding down. */
     recordArtifacts(jobId: string, artifacts: Pick<BackgroundJobOutcome, "ccSessionId" | "changedFiles">): void;
+    /** Update retained DriveAgent lifecycle state after an explicit cleanup. */
+    recordWorktreeLifecycle(jobId: string, lifecycle: NonNullable<BackgroundJobEntry["worktreeLifecycle"]>, note?: string): boolean;
     cancel(jobId: string, outcome?: Omit<BackgroundJobOutcome, "status">): Promise<boolean>;
     /** True while any running/cancelling job spawned by `sessionId` remains. */
     hasRunningForSession(sessionId: string): boolean;
     /** Running jobs spawned by `sessionId`. Feeds the goal judge's task list. */
     listRunningForSession(sessionId: string): BackgroundJobEntry[];
-    /** Running jobs, across all sessions, that are operating in the same cwd. */
+    /** Running jobs, across all sessions, in the same effective workspace.
+     *
+     * Git paths compare by canonical worktree root, so sibling launch directories
+     * collide while distinct linked worktrees do not. A declared
+     * effectiveWorkspaceCwd takes precedence over launchCwd. If either side could
+     * not be resolved through git, exact launch-cwd matching remains the
+     * conservative back-compatible fallback. */
     listRunningByCwd(cwd: string): BackgroundJobEntry[];
+    /** Running and retained terminal jobs in the effective workspace containing
+     *  cwd. Used by DriveAgentJobs' cross-session cwd filter. */
+    listByWorkspaceCwd(cwd: string): BackgroundJobEntry[];
     /** All jobs (running + retained terminal) for `sessionId`. Feeds the panel. */
     listForSession(sessionId: string): BackgroundJobEntry[];
     /** All jobs (running + retained terminal) across sessions. Feeds all-scope UI. */