feat: add TaskContext and TaskPermissions for Phase 3a task isolation

Introduces the foundation for isolated task execution (Phase 3a of #12330):

- TaskContext: immutable snapshot of mode, API config, and workspace for
  each task, replacing runtime reads from shared ClineProvider state
- TaskPermissions: fine-grained permission boundaries (file patterns,
  command restrictions, read-only mode, tool allowlists) that the
  orchestrator can attach when spawning subtasks
- TaskContextBuilder: factory functions to build TaskContext from provider
  state and to derive child contexts with merged permissions
- Task constructor now accepts optional taskContext, using it for mode
  and API config initialization instead of provider.getState()
- delegateParentAndOpenChild builds and passes a TaskContext to child tasks
- Permission merging follows most-restrictive-wins semantics

This is a pure refactor with no behavioral change -- tasks still execute
sequentially, but they now carry their own isolated context. Enforcement
of permission boundaries is deferred to Phase 3b/3d.

Ref: #12330

Author: roomote

packages/types/src/__tests__/task-context.spec.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest"
+
+import {
+	taskPermissionsSchema,
+	taskContextSchema,
+	mergePermissions,
+	type TaskPermissions,
+	type TaskContext,
+} from "../task-context.js"
+
+describe("TaskPermissions schema", () => {
+	it("accepts empty object", () => {
+		const result = taskPermissionsSchema.parse({})
+		expect(result).toEqual({})
+	})
+
+	it("accepts full permissions object", () => {
+		const permissions: TaskPermissions = {
+			fileReadPatterns: ["docs/**", "src/**"],
+			fileWritePatterns: ["docs/**"],
+			allowedCommands: ["npm test"],
+			blockedCommands: ["rm -rf"],
+			readOnly: true,
+			allowedTools: ["read_file", "list_files"],
+		}
+		const result = taskPermissionsSchema.parse(permissions)
+		expect(result).toEqual(permissions)
+	})
+
+	it("accepts partial permissions", () => {
+		const result = taskPermissionsSchema.parse({ readOnly: true })
+		expect(result).toEqual({ readOnly: true })
+	})
+
+	it("rejects invalid types", () => {
+		expect(() => taskPermissionsSchema.parse({ readOnly: "yes" })).toThrow()
+		expect(() => taskPermissionsSchema.parse({ fileReadPatterns: "docs/**" })).toThrow()
+	})
+})
+
+describe("TaskContext schema", () => {
+	it("accepts minimal context", () => {
+		const context: TaskContext = { mode: "code" }
+		const result = taskContextSchema.parse(context)
+		expect(result.mode).toBe("code")
+	})
+
+	it("accepts full context", () => {
+		const context: TaskContext = {
+			mode: "architect",
+			apiConfigName: "gpt-4",
+			permissions: {
+				readOnly: true,
+				fileReadPatterns: ["docs/**"],
+			},
+			inheritSkills: true,
+			skillOverrides: ["custom-skill"],
+			workspacePath: "/workspace/project",
+			parentTaskId: "parent-123",
+			rootTaskId: "root-456",
+		}
+		const result = taskContextSchema.parse(context)
+		expect(result).toEqual(context)
+	})
+
+	it("rejects missing mode", () => {
+		expect(() => taskContextSchema.parse({})).toThrow()
+	})
+})
+
+describe("mergePermissions", () => {
+	it("returns undefined when both are undefined", () => {
+		expect(mergePermissions(undefined, undefined)).toBeUndefined()
+	})
+
+	it("returns child when parent is undefined", () => {
+		const child: TaskPermissions = { readOnly: true }
+		expect(mergePermissions(undefined, child)).toEqual(child)
+	})
+
+	it("returns parent when child is undefined", () => {
+		const parent: TaskPermissions = { readOnly: true }
+		expect(mergePermissions(parent, undefined)).toEqual(parent)
+	})
+
+	it("merges readOnly with OR logic", () => {
+		expect(mergePermissions({ readOnly: true }, { readOnly: false })).toMatchObject({ readOnly: true })
+		expect(mergePermissions({ readOnly: false }, { readOnly: true })).toMatchObject({ readOnly: true })
+		expect(mergePermissions({ readOnly: false }, { readOnly: false })).toMatchObject({})
+	})
+
+	it("intersects fileWritePatterns", () => {
+		const parent: TaskPermissions = { fileWritePatterns: ["docs/**", "src/**", "package.json"] }
+		const child: TaskPermissions = { fileWritePatterns: ["docs/**", "package.json"] }
+		const result = mergePermissions(parent, child)
+		expect(result?.fileWritePatterns).toEqual(["docs/**", "package.json"])
+	})
+
+	it("intersects allowedTools", () => {
+		const parent: TaskPermissions = { allowedTools: ["read_file", "list_files", "search_files"] }
+		const child: TaskPermissions = { allowedTools: ["read_file", "search_files", "write_to_file"] }
+		const result = mergePermissions(parent, child)
+		expect(result?.allowedTools).toEqual(["read_file", "search_files"])
+	})
+
+	it("unions blockedCommands", () => {
+		const parent: TaskPermissions = { blockedCommands: ["rm -rf"] }
+		const child: TaskPermissions = { blockedCommands: ["git push", "rm -rf"] }
+		const result = mergePermissions(parent, child)
+		expect(result?.blockedCommands).toEqual(["rm -rf", "git push"])
+	})
+
+	it("returns defined array when only one side specifies it", () => {
+		const parent: TaskPermissions = { fileReadPatterns: ["docs/**"] }
+		const child: TaskPermissions = {}
+		const result = mergePermissions(parent, child)
+		expect(result?.fileReadPatterns).toEqual(["docs/**"])
+	})
+
+	it("returns empty array when intersection is empty", () => {
+		const parent: TaskPermissions = { allowedTools: ["read_file"] }
+		const child: TaskPermissions = { allowedTools: ["write_to_file"] }
+		const result = mergePermissions(parent, child)
+		expect(result?.allowedTools).toEqual([])
+	})
+})

packages/types/src/index.ts

@@ -20,6 +20,7 @@ export * from "./mode.js"
 export * from "./model.js"
 export * from "./provider-settings.js"
 export * from "./task.js"
+export * from "./task-context.js"
 export * from "./todo.js"
 export * from "./skills.js"
 export * from "./terminal.js"

packages/types/src/task-context.ts

@@ -0,0 +1,227 @@
+import { z } from "zod"
+
+/**
+ * TaskPermissions defines fine-grained permission boundaries for a subtask.
+ *
+ * These permissions allow the orchestrator (or parent task) to restrict what
+ * a child task can do, making parallel execution safer by preventing
+ * unintended side effects across task boundaries.
+ *
+ * ## Design Notes
+ *
+ * Phase 3a introduces the types and plumbing. Enforcement is deferred to
+ * Phase 3b (read-only parallelism) and Phase 3d (write parallelism).
+ *
+ * The permission model is intentionally additive: if no permissions are
+ * specified, the task inherits full capabilities from its mode. Permissions
+ * can only *restrict*, never *expand* beyond what the mode allows.
+ */
+export const taskPermissionsSchema = z.object({
+	/**
+	 * Glob patterns restricting which files the task may read.
+	 * If empty or undefined, the task can read any file (subject to mode restrictions).
+	 * Examples: ["docs/**", "src/utils/**"]
+	 */
+	fileReadPatterns: z.array(z.string()).optional(),
+
+	/**
+	 * Glob patterns restricting which files the task may write/edit.
+	 * If empty or undefined, the task can write any file (subject to mode restrictions).
+	 * Examples: ["docs/**", "package.json"]
+	 */
+	fileWritePatterns: z.array(z.string()).optional(),
+
+	/**
+	 * Allowlist of shell commands the task may execute.
+	 * If empty or undefined, the task can execute any command (subject to mode restrictions).
+	 * Matched as prefixes against the command string.
+	 * Examples: ["npm test", "npx vitest", "git status"]
+	 */
+	allowedCommands: z.array(z.string()).optional(),
+
+	/**
+	 * Blocklist of shell commands the task may NOT execute.
+	 * Takes precedence over allowedCommands.
+	 * Examples: ["rm -rf", "git push"]
+	 */
+	blockedCommands: z.array(z.string()).optional(),
+
+	/**
+	 * Whether the task is restricted to read-only operations.
+	 * When true, the task cannot use write tools (write_to_file, apply_diff,
+	 * execute_command, etc.). This is the primary mechanism for Phase 3b
+	 * read-only parallelism.
+	 */
+	readOnly: z.boolean().optional(),
+
+	/**
+	 * Explicit list of tool names the task is allowed to use.
+	 * If empty or undefined, all tools available to the mode are allowed.
+	 * Examples: ["read_file", "list_files", "search_files"]
+	 */
+	allowedTools: z.array(z.string()).optional(),
+})
+
+export type TaskPermissions = z.infer<typeof taskPermissionsSchema>
+
+/**
+ * TaskContext encapsulates all per-task configuration that a Task needs
+ * to operate independently of the ClineProvider's shared mutable state.
+ *
+ * ## Purpose
+ *
+ * Today, Task reads mode, API config, and other settings from the provider
+ * via `provider.getState()` at construction time and during execution.
+ * This couples Task execution to the provider's current state, which
+ * prevents multiple tasks from running concurrently (since they'd all
+ * read/write the same shared state).
+ *
+ * TaskContext captures a snapshot of everything a Task needs at creation
+ * time, so the Task can operate with its own isolated configuration.
+ *
+ * ## Lifecycle
+ *
+ * 1. Built by the parent (orchestrator or provider) when creating a subtask
+ * 2. Passed to the Task constructor as an immutable snapshot
+ * 3. The Task uses this context instead of reaching back to the provider
+ *    for mode/config/permissions during execution
+ *
+ * ## Phase 3a Scope
+ *
+ * In Phase 3a, TaskContext is optional -- tasks that don't receive one
+ * fall back to the existing provider.getState() behavior. This ensures
+ * full backward compatibility while enabling incremental adoption.
+ */
+export const taskContextSchema = z.object({
+	/**
+	 * The mode slug for this task (e.g., "code", "architect", "ask").
+	 * Snapshot at task creation time -- does not change if the provider's
+	 * mode changes later.
+	 */
+	mode: z.string(),
+
+	/**
+	 * The API configuration profile name for this task.
+	 * Allows subtasks to use different models (including local ones)
+	 * from the parent task.
+	 */
+	apiConfigName: z.string().optional(),
+
+	/**
+	 * Permission boundaries for this task.
+	 * If undefined, the task inherits full capabilities from its mode.
+	 */
+	permissions: taskPermissionsSchema.optional(),
+
+	/**
+	 * Whether this task should inherit skills from the parent.
+	 * Defaults to true if not specified.
+	 */
+	inheritSkills: z.boolean().optional(),
+
+	/**
+	 * Additional skill overrides for this task.
+	 * These are merged with (or replace) inherited skills depending
+	 * on the inheritSkills setting.
+	 */
+	skillOverrides: z.array(z.string()).optional(),
+
+	/**
+	 * The workspace path for this task.
+	 * Allows subtasks to operate in different workspace roots.
+	 */
+	workspacePath: z.string().optional(),
+
+	/**
+	 * ID of the parent task that created this context.
+	 * Used for lineage tracking and result aggregation.
+	 */
+	parentTaskId: z.string().optional(),
+
+	/**
+	 * ID of the root task in the delegation chain.
+	 * Used for hierarchical task management.
+	 */
+	rootTaskId: z.string().optional(),
+})
+
+export type TaskContext = z.infer<typeof taskContextSchema>
+
+/**
+ * Merge two TaskPermissions objects, producing the most restrictive
+ * combination. This is used when a parent task's permissions should
+ * further constrain a child task's permissions.
+ *
+ * Rules:
+ * - readOnly: true if either is true
+ * - allowedTools: intersection if both specified, otherwise the one that's specified
+ * - fileReadPatterns / fileWritePatterns: intersection if both specified
+ * - allowedCommands: intersection if both specified
+ * - blockedCommands: union (all blocked commands from both)
+ */
+export function mergePermissions(
+	parent: TaskPermissions | undefined,
+	child: TaskPermissions | undefined,
+): TaskPermissions | undefined {
+	if (!parent && !child) {
+		return undefined
+	}
+
+	if (!parent) {
+		return child
+	}
+
+	if (!child) {
+		return parent
+	}
+
+	return {
+		readOnly: parent.readOnly || child.readOnly || undefined,
+
+		fileReadPatterns: intersectArrays(parent.fileReadPatterns, child.fileReadPatterns),
+
+		fileWritePatterns: intersectArrays(parent.fileWritePatterns, child.fileWritePatterns),
+
+		allowedCommands: intersectArrays(parent.allowedCommands, child.allowedCommands),
+
+		blockedCommands: unionArrays(parent.blockedCommands, child.blockedCommands),
+
+		allowedTools: intersectArrays(parent.allowedTools, child.allowedTools),
+	}
+}
+
+/** Return intersection of two optional arrays, or the defined one if only one exists. */
+function intersectArrays(a: string[] | undefined, b: string[] | undefined): string[] | undefined {
+	if (!a && !b) {
+		return undefined
+	}
+
+	if (!a) {
+		return b
+	}
+
+	if (!b) {
+		return a
+	}
+
+	const setB = new Set(b)
+	const result = a.filter((item) => setB.has(item))
+	return result.length > 0 ? result : []
+}
+
+/** Return union of two optional arrays. */
+function unionArrays(a: string[] | undefined, b: string[] | undefined): string[] | undefined {
+	if (!a && !b) {
+		return undefined
+	}
+
+	if (!a) {
+		return b
+	}
+
+	if (!b) {
+		return a
+	}
+
+	return Array.from(new Set([...a, ...b]))
+}

packages/types/src/task.ts

@@ -5,6 +5,7 @@ import type { RooCodeSettings } from "./global-settings.js"
 import type { ClineMessage, QueuedMessage, TokenUsage } from "./message.js"
 import type { ToolUsage, ToolName } from "./tool.js"
 import type { TodoItem } from "./todo.js"
+import type { TaskContext } from "./task-context.js"
 
 /**
  * TaskProviderLike
@@ -94,6 +95,12 @@ export interface CreateTaskOptions {
 	/** Whether to start the task loop immediately (default: true).
 	 *  When false, the caller must invoke `task.start()` manually. */
 	startTask?: boolean
+	/**
+	 * Optional isolated task context containing mode, API config, and permissions.
+	 * When provided, the task uses this context instead of reading from the provider.
+	 * Phase 3a foundation for concurrent task execution.
+	 */
+	taskContext?: TaskContext
 }
 
 export enum TaskStatus {