coder
diff --git a/‎docs/agents/index.mdx‎
Lines changed: 2 additions & 0 deletions b/‎docs/agents/index.mdx‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎docs/hooks/tools.mdx‎
Lines changed: 16 additions & 0 deletions b/‎docs/hooks/tools.mdx‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎src/common/utils/tools/toolDefinitions.test.ts‎
Lines changed: 41 additions & 0 deletions b/‎src/common/utils/tools/toolDefinitions.test.ts‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎src/common/utils/tools/toolDefinitions.ts‎
Lines changed: 102 additions & 0 deletions b/‎src/common/utils/tools/toolDefinitions.ts‎
Lines changed: 102 additions & 0 deletions
diff --git a/‎src/common/utils/tools/tools.ts‎
Lines changed: 2 additions & 0 deletions b/‎src/common/utils/tools/tools.ts‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎src/node/builtinAgents/plan.md‎
Lines changed: 2 additions & 0 deletions b/‎src/node/builtinAgents/plan.md‎
Lines changed: 2 additions & 0 deletions
@@ -364,6 +364,8 @@ tools:
     - image_.*
     # Plan should not apply sub-agent patches.
     - task_apply_git_patch
+    # Plan should not perform destructive workspace cleanup.
+    - task_workspace_lifecycle
     # Global config and catalog tools stay out of general-purpose agents
     - mux_agents_.*
     - agent_skill_write
 
@@ -716,6 +716,22 @@ If a value is too large for the environment, it may be omitted (not set). Mux al
 
 </details>
 
+<details>
+<summary>task_workspace_lifecycle (8)</summary>
+
+| Env var                                                     | JSON path                                      | Type    | Description                                                                                                                                                                                     |
+| ----------------------------------------------------------- | ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MUX_TOOL_INPUT_ACKNOWLEDGED_UNTRACKED_PATHS_<KEY>_<INDEX>` | `acknowledged_untracked_paths[<KEY>][<INDEX>]` | string  | Archive-only confirmations keyed by resolved workspaceId. Use only paths returned by a previous requires_confirmation result.                                                                   |
+| `MUX_TOOL_INPUT_ACKNOWLEDGED_UNTRACKED_PATHS_<KEY>_COUNT`   | `acknowledged_untracked_paths[<KEY>].length`   | number  | Number of elements in acknowledged_untracked_paths[&lt;KEY&gt;] (Archive-only confirmations keyed by resolved workspaceId. Use only paths returned by a previous requires_confirmation result.) |
+| `MUX_TOOL_INPUT_ACTION`                                     | `action`                                       | enum    | Lifecycle action to perform: "archive" is the safe default, "delete_worktree" reclaims disk after archive, and "remove" irreversibly deletes archived workspace metadata/session state.         |
+| `MUX_TOOL_INPUT_FORCE`                                      | `force`                                        | boolean | Only applies to remove. Does not bypass ownership, active-turn, archive, or archive-confirmation safety checks.                                                                                 |
+| `MUX_TOOL_INPUT_INTERRUPT_ACTIVE`                           | `interrupt_active`                             | boolean | When true, interrupt active workspace turns for the target before performing an otherwise-eligible lifecycle action. Defaults to false.                                                         |
+| `MUX_TOOL_INPUT_TARGETS_<INDEX>_TASK_ID`                    | `targets[<INDEX>].taskId`                      | string  | —                                                                                                                                                                                               |
+| `MUX_TOOL_INPUT_TARGETS_<INDEX>_WORKSPACE_ID`               | `targets[<INDEX>].workspaceId`                 | string  | —                                                                                                                                                                                               |
+| `MUX_TOOL_INPUT_TARGETS_COUNT`                              | `targets.length`                               | number  | Number of elements in targets (Parent-owned workspace-turn targets. Provide exactly one of taskId (wst\_...) or workspaceId for each target.)                                                   |
+
+</details>
+
 <details>
 <summary>todo_write (3)</summary>
 
 
@@ -5,6 +5,7 @@ import {
   getAvailableTools,
   supportsGoogleNativeToolsWithFunctionTools,
   TaskToolArgsSchema,
+  TaskWorkspaceLifecycleToolArgsSchema,
   TOOL_DEFINITIONS,
   WorkflowRunToolArgsSchema,
 } from "./toolDefinitions";
@@ -151,6 +152,46 @@ describe("TOOL_DEFINITIONS", () => {
     ).toBe(false);
   });
 
+  it("validates task workspace lifecycle targets and optional nulls", () => {
+    expect(
+      TaskWorkspaceLifecycleToolArgsSchema.safeParse({
+        action: "archive",
+        targets: [{ taskId: "wst_child" }],
+        interrupt_active: null,
+        force: null,
+        acknowledged_untracked_paths: null,
+      }).success
+    ).toBe(true);
+
+    expect(
+      TaskWorkspaceLifecycleToolArgsSchema.safeParse({
+        action: "delete_worktree",
+        targets: [{ workspaceId: "child-workspace" }],
+      }).success
+    ).toBe(true);
+
+    expect(
+      TaskWorkspaceLifecycleToolArgsSchema.safeParse({
+        action: "remove",
+        targets: [{ taskId: "wst_child", workspaceId: "child-workspace" }],
+      }).success
+    ).toBe(false);
+
+    expect(
+      TaskWorkspaceLifecycleToolArgsSchema.safeParse({
+        action: "archive",
+        targets: [{}],
+      }).success
+    ).toBe(false);
+
+    expect(
+      TaskWorkspaceLifecycleToolArgsSchema.safeParse({
+        action: "destroy",
+        targets: [{ workspaceId: "child-workspace" }],
+      }).success
+    ).toBe(false);
+  });
+
   it("requires workspaceId for existing workspace task targets", () => {
     expect(
       TaskToolArgsSchema.safeParse({
 
@@ -1022,6 +1022,97 @@ export const TaskTerminateToolResultSchema = z
   })
   .strict();
 
+// -----------------------------------------------------------------------------
+// task_workspace_lifecycle (parent-owned workspace cleanup)
+// -----------------------------------------------------------------------------
+
+export const TaskWorkspaceLifecycleActionSchema = z.enum(["archive", "delete_worktree", "remove"]);
+
+export const TaskWorkspaceLifecycleTargetSchema = z
+  .object({
+    taskId: z.string().min(1).nullish(),
+    workspaceId: z.string().min(1).nullish(),
+  })
+  .strict()
+  .superRefine((target, ctx) => {
+    const hasTaskId = target.taskId != null && target.taskId.trim().length > 0;
+    const hasWorkspaceId = target.workspaceId != null && target.workspaceId.trim().length > 0;
+    if (hasTaskId === hasWorkspaceId) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Provide exactly one of taskId or workspaceId",
+        path: ["taskId"],
+      });
+    }
+  });
+
+export const TaskWorkspaceLifecycleToolArgsSchema = z
+  .object({
+    action: TaskWorkspaceLifecycleActionSchema.describe(
+      'Lifecycle action to perform: "archive" is the safe default, "delete_worktree" reclaims disk after archive, and "remove" irreversibly deletes archived workspace metadata/session state.'
+    ),
+    targets: z
+      .array(TaskWorkspaceLifecycleTargetSchema)
+      .min(1)
+      .describe(
+        "Parent-owned workspace-turn targets. Provide exactly one of taskId (wst_...) or workspaceId for each target."
+      ),
+    interrupt_active: z
+      .boolean()
+      .nullish()
+      .describe(
+        "When true, interrupt active workspace turns for the target before performing an otherwise-eligible lifecycle action. Defaults to false."
+      ),
+    force: z
+      .boolean()
+      .nullish()
+      .describe(
+        "Only applies to remove. Does not bypass ownership, active-turn, archive, or archive-confirmation safety checks."
+      ),
+    acknowledged_untracked_paths: z
+      .record(z.string(), z.array(z.string()))
+      .nullish()
+      .describe(
+        "Archive-only confirmations keyed by resolved workspaceId. Use only paths returned by a previous requires_confirmation result."
+      ),
+  })
+  .strict();
+
+const TaskWorkspaceLifecycleBaseResultSchema = z.object({
+  action: TaskWorkspaceLifecycleActionSchema,
+  taskId: z.string().optional(),
+  workspaceId: z.string().optional(),
+  paths: z.array(z.string()).optional(),
+  activeTaskIds: z.array(z.string()).optional(),
+  note: z.string().optional(),
+  error: z.string().optional(),
+});
+
+export const TaskWorkspaceLifecycleToolTargetResultSchema = z.discriminatedUnion("status", [
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("archived") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("already_archived") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("deleted_worktree") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({
+    status: z.literal("already_transcript_only"),
+  }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("removed") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("already_removed") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("requires_archive") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({
+    status: z.literal("requires_confirmation"),
+  }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("active") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("not_found") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("invalid_scope") }).strict(),
+  TaskWorkspaceLifecycleBaseResultSchema.extend({ status: z.literal("error") }).strict(),
+]);
+
+export const TaskWorkspaceLifecycleToolResultSchema = z
+  .object({
+    results: z.array(TaskWorkspaceLifecycleToolTargetResultSchema),
+  })
+  .strict();
+
 // -----------------------------------------------------------------------------
 // task_list (list descendant sub-agent tasks)
 // -----------------------------------------------------------------------------
@@ -1920,6 +2011,14 @@ export const TOOL_DEFINITIONS = {
       "For workflow runs (wfr_... IDs), this interrupts the run instead: durable state is preserved and the run can be resumed later with workflow_resume.",
     schema: TaskTerminateToolArgsSchema,
   },
+  task_workspace_lifecycle: {
+    description:
+      'Archive, delete the managed worktree for, or remove full workspaces that the current workspace created via task(kind="workspace"). ' +
+      "This tool is scoped by durable workspace-turn ownership records; it cannot act on arbitrary user workspaces. " +
+      'Use action="archive" as the safe default when child work is complete. Use delete_worktree only after archive to reclaim disk while preserving transcript metadata. ' +
+      "Use remove only for irreversible cleanup of already archived owned workspaces. Active workspace turns are refused unless interrupt_active is true, and force never bypasses ownership, archive, or confirmation checks.",
+    schema: TaskWorkspaceLifecycleToolArgsSchema,
+  },
   task_list: {
     description:
       "List descendant tasks for the current workspace, including status + metadata. " +
@@ -2702,6 +2801,7 @@ export type BridgeableToolName =
   | "task_apply_git_patch"
   | "task_list"
   | "task_terminate"
+  | "task_workspace_lifecycle"
   | "heartbeat"
   | "memory";
 
@@ -2728,6 +2828,7 @@ export const RESULT_SCHEMAS: Record<BridgeableToolName, z.ZodType> = {
   task_apply_git_patch: TaskApplyGitPatchToolResultSchema,
   task_list: TaskListToolResultSchema,
   task_terminate: TaskTerminateToolResultSchema,
+  task_workspace_lifecycle: TaskWorkspaceLifecycleToolResultSchema,
   heartbeat: HeartbeatToolResultSchema,
   memory: MemoryToolResultSchema,
 };
@@ -2834,6 +2935,7 @@ export function getAvailableTools(
     "task_await",
     "task_apply_git_patch",
     "task_terminate",
+    "task_workspace_lifecycle",
     "task_list",
     ...(enableDynamicWorkflows ? ["workflow_run", "workflow_resume"] : []),
     ...(enableAgentReport ? ["agent_report"] : []),
 
@@ -30,6 +30,7 @@ import { createTaskTool } from "@/node/services/tools/task";
 import { createTaskApplyGitPatchTool } from "@/node/services/tools/task_apply_git_patch";
 import { createTaskAwaitTool } from "@/node/services/tools/task_await";
 import { createTaskTerminateTool } from "@/node/services/tools/task_terminate";
+import { createTaskWorkspaceLifecycleTool } from "@/node/services/tools/task_workspace_lifecycle";
 import { createTaskListTool } from "@/node/services/tools/task_list";
 import { createAgentSkillReadTool } from "@/node/services/tools/agent_skill_read";
 import { createAgentSkillReadFileTool } from "@/node/services/tools/agent_skill_read_file";
@@ -538,6 +539,7 @@ export async function getToolsForModel(
     task_await: wrap(createTaskAwaitTool(config)),
     task_apply_git_patch: wrap(createTaskApplyGitPatchTool(config)),
     task_terminate: wrap(createTaskTerminateTool(config)),
+    task_workspace_lifecycle: wrap(createTaskWorkspaceLifecycleTool(config)),
     task_list: wrap(createTaskListTool(config)),
 
     // Bash execution (foreground/background). Manage background output via task_await/task_list/task_terminate.
 
@@ -19,6 +19,8 @@ tools:
     - image_.*
     # Plan should not apply sub-agent patches.
     - task_apply_git_patch
+    # Plan should not perform destructive workspace cleanup.
+    - task_workspace_lifecycle
     # Global config and catalog tools stay out of general-purpose agents
     - mux_agents_.*
     - agent_skill_write