pi-crew 0.9.18 → 0.9.20

package/src/extension/team-tool/run.ts

@@ -1,6 +1,7 @@
 import { allAgents, discoverAgents } from "../../agents/discover-agents.ts";
 import { loadConfig } from "../../config/config.ts";
 import { PipelineRunner, type PipelineWorkflow } from "../../runtime/pipeline-runner.ts";
+import { sanitizeTaskText } from "../../runtime/task-packet.ts";
 // Heavy runtime — lazy-loaded to avoid 1.4s import cost at extension registration.
 import type { executeTeamRun as ExecuteTeamRunFn } from "../../runtime/team-runner.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
@@ -17,7 +18,7 @@ import { assertCleanLeader, findGitRoot } from "../../worktree/worktree-manager.
 const _typeCheck: typeof ExecuteTeamRunFn = null as never as typeof ExecuteTeamRunFn;
 
 import { logInternalError } from "../../utils/internal-error.ts";
-import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { resolveContainedPath, resolveRealContainedPath } from "../../utils/safe-paths.ts";
 
 let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
 async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
@@ -127,6 +128,76 @@ function scheduleBackgroundEarlyExitGuard(cwd: string, runId: string, pid: numbe
 	timer.unref();
 }
 
+/**
+ * Max analysis size in bytes — matches the `maxLength: 100_000` schema cap on
+ * the inline `analysis` param, so the file channel can't smuggle in a larger
+ * payload than the inline channel allows (prompt-size blowup guard).
+ */
+const MAX_ANALYSIS_BYTES = 100_000;
+
+/**
+ * Resolve the analysis channel (round-X Y1): inline `analysis` or `analysisPath` file.
+ *
+ * Called BEFORE `createRunManifest` so validation failures fail-fast and no orphan
+ * run state is left on disk. Sanitizes the parsed content with the same
+ * {@link sanitizeTaskText} machinery used in `buildTaskPacket` (SEC-007), since the
+ * resulting text is injected into worker prompts via standard sharedReads.
+ *
+ * Mutual exclusivity mirrors the `budgetTotal`/`budgetUnlimited` pattern in
+ * `goal.ts` — a cold-review #2 blocking fix pattern.
+ */
+function resolveAnalysisText(
+	params: TeamToolParamsValue,
+	cwd: string,
+): { text?: string; error?: string; source: "inline" | "path" | "none" } {
+	const hasInline = typeof params.analysis === "string" && params.analysis.length > 0;
+	const hasPath = typeof params.analysisPath === "string" && params.analysisPath.length > 0;
+
+	if (hasInline && hasPath) {
+		return {
+			error: "`analysis` and `analysisPath` are mutually exclusive. Set exactly one.",
+			source: "none",
+		};
+	}
+	if (!hasInline && !hasPath) return { source: "none" };
+
+	if (hasPath) {
+		let resolved: string;
+		try {
+			resolved = resolveContainedPath(cwd, params.analysisPath as string);
+		} catch {
+			return {
+				error: `analysisPath must be within project directory: ${params.analysisPath}`,
+				source: "none",
+			};
+		}
+		if (!fs.existsSync(resolved)) {
+			return {
+				error: `Analysis file not found: ${resolved}`,
+				source: "none",
+			};
+		}
+		// Size cap BEFORE reading: mirror the inline schema cap (maxLength 100_000)
+		// so a large file can't blow up worker prompts via the sharedReads channel.
+		const { size } = fs.statSync(resolved);
+		if (size > MAX_ANALYSIS_BYTES) {
+			return {
+				error: `Analysis file too large: ${size} bytes (max ${MAX_ANALYSIS_BYTES}). Trim the analysis or pass a summary inline.`,
+				source: "none",
+			};
+		}
+		const raw = fs.readFileSync(resolved, "utf-8");
+		const sanitized = sanitizeTaskText(raw);
+		if (!sanitized) return { source: "none" };
+		return { text: sanitized, source: "path" };
+	}
+
+	// hasInline
+	const sanitized = sanitizeTaskText(params.analysis as string);
+	if (!sanitized) return { source: "none" };
+	return { text: sanitized, source: "inline" };
+}
+
 export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
 	// CHAIN DISPATCH: runs before goal validation since a chain has no top-level
 	// goal. The injected handleRun reference breaks the run.ts ↔ chain-dispatch.ts
@@ -234,11 +305,18 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 						role: params.role ?? "agent",
 						task: "{goal}",
 						model: params.model,
+						reads: params.analysis || params.analysisPath ? ["analysis.md"] : undefined,
 					},
 				],
 			}
 		: workflows.find((item) => item.name === workflowName);
 	if (!baseWorkflow) return result(`Workflow '${workflowName}' not found.`, { action: "run", status: "error" }, true);
+
+	// ANALYSIS CHANNEL (round-X Y1): resolve analysis text from inline or file BEFORE
+	// createRunManifest so validation errors fail-fast (no orphan run state).
+	const analysisParam = resolveAnalysisText(params, resolvedCtx.cwd);
+	if (analysisParam.error) return result(analysisParam.error, { action: "run", status: "error" }, true);
+
 	// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { expandParallelResearchWorkflow }` above (issue #28, RFC 17). At call time the module body has fully evaluated, so the dynamic import returns a live binding. Multi-line form breaks scripts/check-lazy-imports.mjs (which does `lines[lineNum - 2]`), so keep destructuring + await import on one line.
 	const { expandParallelResearchWorkflow: expandParallelResearch } = await import("../../runtime/parallel-research.ts");
 	const workflow = directAgent ? baseWorkflow : expandParallelResearch(baseWorkflow, resolvedCtx.cwd);
@@ -276,6 +354,11 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	if (!directAgent && workflow.source === "builtin" && isGoalWrapEnabled(resolvedCtx.cwd, workflow.name)) {
 		const decision = shouldGoalWrap(resolvedCtx.cwd, workflow);
 		if (decision.enabled) {
+			if (analysisParam.text) {
+				console.warn(
+					`[team-tool.run] analysis param is ignored by goal-wrapped run (workflow=${workflow.name}). The analysis artifact will not be written.`,
+				);
+			}
 			return await startGoalWrappedRun(params, ctx, workflow, goal);
 		}
 		// goal-wrap disabled for this workflow — fall through silently to normal
@@ -364,10 +447,23 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		content: `${goal}\n`,
 		producer: "team-tool",
 	});
+	// ANALYSIS CHANNEL (round-X Y1): if analysis was provided, persist as a shared artifact
+	// so workflow steps declaring reads: analysis.md receive it via the standard
+	// dependency-context injection (collectDependencyOutputContext → renderDependencyOutputContext).
+	const analysisArtifacts = analysisParam.text
+		? [
+				writeArtifact(paths.artifactsRoot, {
+					kind: "prompt",
+					relativePath: "shared/analysis.md",
+					content: `${analysisParam.text}\n`,
+					producer: "team-tool",
+				}),
+			]
+		: [];
 	const updatedManifest = {
 		...manifest,
 		...(skillOverride !== undefined ? { skillOverride } : {}),
-		artifacts: [goalArtifact],
+		artifacts: [goalArtifact, ...analysisArtifacts],
 		summary: "Run manifest created; worker execution is not implemented yet.",
 	};
 	atomicWriteJson(paths.manifestPath, updatedManifest);

package/src/runtime/child-pi.ts

@@ -7,7 +7,7 @@ import { DEFAULT_CHILD_PI } from "../config/defaults.ts";
 import { registerChildProcess, unregisterChildProcess } from "../extension/crew-cleanup.ts";
 import type { WorkerExitStatus } from "../state/types.ts";
 import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
-import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
+import { buildScopedAllowList, sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { redactJsonLine, redactSecretString } from "../utils/redaction.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
@@ -254,7 +254,53 @@ export interface ChildPiRunResult {
 	intermediateFindings?: string;
 }
 
-export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): SpawnOptions {
+// Base allowlist of non-provider env vars always passed to child workers.
+// Provider API keys are injected dynamically via buildScopedAllowList() only
+// when a model is assigned to the task (per-task key scoping).
+const BASE_ALLOWLIST: string[] = [
+	"PATH",
+	"HOME",
+	"USER",
+	"SHELL",
+	"TERM",
+	"LANG",
+	"LC_ALL",
+	"LC_COLLATE",
+	"LC_CTYPE",
+	"LC_MESSAGES",
+	"LC_MONETARY",
+	"LC_NUMERIC",
+	"LC_TIME",
+	"XDG_CONFIG_HOME",
+	"XDG_DATA_HOME",
+	"XDG_CACHE_HOME",
+	"XDG_RUNTIME_DIR",
+	// Windows essentials — see WINDOWS_ESSENTIAL_ENV_VARS (src/utils/env-allowlist.ts).
+	...WINDOWS_ESSENTIAL_ENV_VARS,
+	"NVM_BIN",
+	"NVM_DIR",
+	"NVM_INC",
+	"NODE_DISABLE_COLORS",
+	"NODE_EXTRA_CA_CERTS",
+	"NPM_CONFIG_REGISTRY",
+	"NPM_CONFIG_USERCONFIG",
+	"NPM_CONFIG_GLOBALCONFIG",
+	"PI_CREW_DEPTH",
+	"PI_CREW_MAX_DEPTH",
+	"PI_CREW_INHERIT_PROJECT_CONTEXT",
+	"PI_CREW_INHERIT_SKILLS",
+	"PI_CREW_KIND",
+	"PI_CREW_PARENT_PID",
+	"PI_TEAMS_DEPTH",
+	"PI_TEAMS_MAX_DEPTH",
+	"PI_TEAMS_INHERIT_PROJECT_CONTEXT",
+	"PI_TEAMS_INHERIT_SKILLS",
+	"PI_TEAMS_PI_BIN",
+	"PI_TEAMS_MOCK_CHILD_PI",
+	"PI_CREW_ALLOW_MOCK",
+];
+
+export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv, model?: string): SpawnOptions {
 	// SECURITY FIX (Issue #1): Validate cwd before passing to spawn.
 	// If cwd comes from an untrusted source (user input, workspace config), a malicious cwd
 	// could cause the child process to operate in an attacker-controlled directory,
@@ -284,81 +330,12 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): S
 	// IMPORTANT: preserve model provider API keys — they are needed by the child Pi to call the LLM.
 	// Also preserve essential non-secret vars (PATH, HOME, USER, etc.) so the child process can function.
 	// Bug #12 fix: essential env vars (PATH, HOME, etc.) are always preserved so child can find npm/node.
-	const filteredEnv = sanitizeEnvSecrets(env, {
-		allowList: [
-			/*
-			 * SECURITY WARNING: All model provider API keys below are passed to EVERY child worker.
-			 * If any child is compromised (e.g. via prompt injection), all listed keys are exposed.
-			 * This is a deliberate trade-off: multi-provider setups require the child Pi process to
-			 * authenticate with whichever provider the model routes to. Reducing keys per-child
-			 * would break multi-provider functionality. Mitigations:
-			 *   - sanitizeEnvSecrets strips all env vars NOT on this list.
-			 *   - Do NOT add wildcards ("*_API_KEY") — only explicit, intended provider keys.
-			 *   - Consider per-task key scoping if the architecture allows it in the future.
-			 *
-			 * MAINTENANCE REQUIREMENT: When new secret env vars are added to the Pi ecosystem,
-			 * they MUST be explicitly added to this allowlist to be passed to child processes.
-			 * A CI check should fail if a secret-like env var (matching patterns like *_API_KEY,
-			 * *_TOKEN, *_SECRET) is detected in the codebase but not present in this list.
-			 */
-			// NOTE: Model provider API keys are NOT needed here — child Pi uses the same
-			// config file as parent Pi. Passing keys via env is a security risk.
-			"PATH",
-			"HOME",
-			"USER",
-			"SHELL",
-			"TERM",
-			"LANG",
-			// FIX: Replaced broad wildcards (LC_*, XDG_*, NVM_*, NODE_*, npm_*) with
-			// specific names. Previously NPM_TOKEN, NODE_ENV=production, NVM_RC_VERSION
-			// all leaked through wildcards.
-			"LC_ALL",
-			"LC_COLLATE",
-			"LC_CTYPE",
-			"LC_MESSAGES",
-			"LC_MONETARY",
-			"LC_NUMERIC",
-			"LC_TIME",
-			"XDG_CONFIG_HOME",
-			"XDG_DATA_HOME",
-			"XDG_CACHE_HOME",
-			"XDG_RUNTIME_DIR",
-			// Windows essentials — see WINDOWS_ESSENTIAL_ENV_VARS (src/utils/env-allowlist.ts).
-			...WINDOWS_ESSENTIAL_ENV_VARS,
-			"NVM_BIN",
-			"NVM_DIR",
-			"NVM_INC",
-			// NODE_PATH is intentionally omitted from the allowlist.
-			// NODE_PATH can reveal user environment information (e.g., NVM paths under $HOME)
-			// and the validation at lines 286-298 only filters to standard system prefixes.
-			// Removing it entirely is cleaner than best-effort filtering.
-			"NODE_DISABLE_COLORS",
-			"NODE_EXTRA_CA_CERTS",
-			"NPM_CONFIG_REGISTRY",
-			"NPM_CONFIG_USERCONFIG",
-			"NPM_CONFIG_GLOBALCONFIG",
-			// FIX: Replace PI_CREW_*/PI_TEAMS_* wildcards with explicit list of
-			// safe vars. Wildcards are fragile — any new secret var would leak.
-			// Only non-secret execution-control vars that children legitimately need.
-			"PI_CREW_DEPTH",
-			"PI_CREW_MAX_DEPTH",
-			"PI_CREW_INHERIT_PROJECT_CONTEXT",
-			"PI_CREW_INHERIT_SKILLS",
-			// PI_CREW_KIND marks this process as a crew sub-agent (vs the user's main session).
-			// doctor --zombies matches it to safely list orphaned sub-agents only.
-			"PI_CREW_KIND",
-			// PI_CREW_PARENT_PID is needed by child-pi's parent-guard (uses
-			// process.kill(pid, 0) liveness check). The PID is not a secret.
-			"PI_CREW_PARENT_PID",
-			"PI_TEAMS_DEPTH",
-			"PI_TEAMS_MAX_DEPTH",
-			"PI_TEAMS_INHERIT_PROJECT_CONTEXT",
-			"PI_TEAMS_INHERIT_SKILLS",
-			"PI_TEAMS_PI_BIN",
-			"PI_TEAMS_MOCK_CHILD_PI",
-			"PI_CREW_ALLOW_MOCK",
-		],
-	});
+	//
+	// PER-TASK KEY SCOPING: when a model is provided, only the env keys for that
+	// provider are injected (via buildScopedAllowList). When no model is given,
+	// only BASE_ALLOWLIST system vars pass through — no provider keys leak.
+	const allowList = model ? buildScopedAllowList(BASE_ALLOWLIST, [model]) : BASE_ALLOWLIST;
+	const filteredEnv = sanitizeEnvSecrets(env, { allowList });
 	// FIX: Removed delete workarounds — with explicit allowlist, these vars
 	// are no longer auto-leaked. The wildcard approach was fragile.
 
@@ -900,10 +877,14 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			const child = spawn(
 				spawnSpec.command,
 				spawnSpec.args,
-				buildChildPiSpawnOptions(input.cwd, {
-					...process.env,
-					...built.env,
-				}),
+				buildChildPiSpawnOptions(
+					input.cwd,
+					{
+						...process.env,
+						...built.env,
+					},
+					input.model,
+				),
 			);
 			if (child.pid) {
 				activeChildProcesses.set(child.pid, child);

package/src/runtime/cross-extension-rpc.ts

@@ -1,4 +1,5 @@
 import * as crypto from "node:crypto";
+import { isHmacEnabled, extractSignaturePayload, verifyRpcSignature } from "../extension/rpc-hmac.ts";
 
 export interface EventBus {
 	on(event: string, handler: (data: unknown) => void): () => void;
@@ -47,6 +48,25 @@ function handleRpc<P extends { requestId: string }>(
 		if (!/^[a-zA-Z0-9_-]+$/.test(params.requestId)) {
 			throw new Error("Security: invalid requestId format");
 		}
+		// SECURITY: HMAC signature verification (when enabled).
+		if (isHmacEnabled()) {
+			const sigPayload = extractSignaturePayload(params);
+			if (!sigPayload) {
+				throw new Error("[pi-crew HMAC] Missing HMAC signature in RPC request.");
+			}
+			// Strip HMAC fields before verification (HMAC was signed over original params)
+			const originalParams = { ...params };
+			delete (originalParams as Record<string, unknown>).hmacVersion;
+			delete (originalParams as Record<string, unknown>).hmacOrigin;
+			delete (originalParams as Record<string, unknown>).hmacTimestamp;
+			delete (originalParams as Record<string, unknown>).hmacChannel;
+			delete (originalParams as Record<string, unknown>).hmacNonce;
+			delete (originalParams as Record<string, unknown>).hmacSignature;
+			const verification = verifyRpcSignature(sigPayload, originalParams);
+			if (!verification.valid) {
+				throw new Error(`[pi-crew HMAC] ${verification.reason}`);
+			}
+		}
 		try {
 			const data = await fn(params);
 			const reply: { success: true; data?: unknown } = { success: true };
@@ -72,9 +92,8 @@ export function registerCrewRpcHandlers(deps: RpcDeps): RpcHandle {
 	// operations that create or terminate child processes. Any subscriber on
 	// the shared event bus can emit these events. In a multi-extension
 	// environment, this means a malicious extension could spawn/stop agents.
-	// Mitigation (H-2): require an unguessable per-process token in addition to
-	// the legacy `source` identifier. Log all invocations for audit. A full fix
-	// still requires event-bus-level origin signing.
+	// Mitigations: HMAC origin signing (see rpc-hmac.ts) + per-process token
+	// (H-2) + legacy `source` identifier.
 	const CREW_RPC_SOURCE = "pi-crew";
 	const EXPECTED_TOKEN = getCrewRpcToken();
 

package/src/schema/team-tool-schema.ts

@@ -264,6 +264,19 @@ export const TeamToolParams = Type.Object({
 		// "description-only schema" strict-provider check.
 		Type.Any(),
 	),
+	analysis: Type.Optional(
+		Type.String({
+			maxLength: 100_000,
+			description:
+				"Inline analysis/context notes from the calling session. Persisted to artifacts/{runId}/shared/analysis.md (audit trail) and auto-injected into any workflow step declaring reads: analysis.md (e.g. builtin 'plan-execute'). Mutually exclusive with analysisPath. Ignored by goal-wrapped runs and chain dispatch in v1.",
+		}),
+	),
+	analysisPath: Type.Optional(
+		Type.String({
+			description:
+				"Path to an existing markdown analysis file (resolved within cwd). Copied into shared/analysis.md. Mutually exclusive with analysis.",
+		}),
+	),
 	focus: Type.Optional(
 		Type.String({
 			description:
@@ -385,4 +398,12 @@ export interface TeamToolParamsValue {
 	tokenBudget?: number;
 	/** Typed workflow arguments for .dwf.ts scripts, accessible via ctx.args<T>() (round-14 P1-5). */
 	args?: unknown;
+	/** Inline analysis/context notes from the calling session. Persisted to
+	 *  artifacts/{runId}/shared/analysis.md (audit trail) and auto-injected into
+	 *  any workflow step declaring reads: analysis.md (e.g. builtin 'plan-execute').
+	 *  Mutually exclusive with `analysisPath`. */
+	analysis?: string;
+	/** Path to an existing analysis file resolved within `cwd`. Copied into
+	 *  shared/analysis.md. Mutually exclusive with `analysis`. */
+	analysisPath?: string;
 }

package/src/tools/safe-bash-extension.ts

@@ -14,7 +14,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createBashTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { isDangerous } from "./safe-bash.ts";
+import { checkCommand } from "./safe-bash.ts";
 
 export default function safeBashExtension(pi: ExtensionAPI): void {
 	const cwd = process.cwd();
@@ -35,7 +35,7 @@ export default function safeBashExtension(pi: ExtensionAPI): void {
 			),
 		}),
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const danger = isDangerous(params.command);
+			const danger = checkCommand(params.command);
 			if (danger) {
 				return {
 					details: {},

package/src/tools/safe-bash.ts

@@ -403,3 +403,103 @@ export const SAFE_BASH_PRESETS = {
 		allowPatterns: [],
 	},
 };
+
+/**
+ * === Whitelist Mode (opt-in, additive) ===
+ *
+ * A deny-by-default mode that checks the first token of a command against an
+ * explicit allowlist of read-only utilities. Enabled via
+ * `PI_CREW_SAFE_BASH_MODE=whitelist`. When NOT enabled, the legacy blacklist
+ * `isDangerous()` path is used unchanged.
+ */
+
+/** Commands permitted under whitelist mode (read-only utilities only). */
+const WHITELISTED_COMMANDS = new Set<string>([
+	"ls",
+	"cat",
+	"head",
+	"tail",
+	"wc",
+	"grep",
+	"find",
+	"echo",
+	"pwd",
+	"date",
+	"whoami",
+	"uname",
+	"df",
+	"du",
+	"file",
+	"stat",
+]);
+
+/**
+ * Shell operators/metacharacters that could chain or substitute a command past
+ * the first token. Their presence anywhere in the raw command causes the
+ * whitelist check to reject, so e.g. `ls; rm file` cannot smuggle `rm` through
+ * under a permitted first token.
+ */
+const SHELL_METACHARACTER_RE = /[|;&`()<>]|\$\(/;
+
+/**
+ * Simple shell tokenizer: extract the first token (command name) of a command,
+ * respecting single and double quotes. Leading whitespace is skipped. Quote
+ * characters are not included in the returned token (`"ls"` → `ls`). An
+ * UNMATCHED quote is treated as malformed input and returns an empty string,
+ * causing `isAllowedWhitelist()` to reject the command (unmatched quotes can
+ * indicate malformed injection attempts).
+ */
+function shellFirstToken(command: string): string {
+	let i = 0;
+	const len = command.length;
+	while (i < len && /\s/.test(command[i])) i++;
+	let token = "";
+	while (i < len) {
+		const ch = command[i];
+		if (/\s/.test(ch)) break;
+		if (ch === "'" || ch === '"') {
+			const quote = ch;
+			i++;
+			while (i < len && command[i] !== quote) {
+				token += command[i];
+				i++;
+			}
+			// Unmatched quote → malformed input, reject by returning empty string.
+			if (i >= len) return "";
+			i++; // skip closing quote
+			continue;
+		}
+		token += ch;
+		i++;
+	}
+	return token;
+}
+
+/**
+ * Whitelist check (deny-by-default). Returns true only when the command's first
+ * token is in the allowlist AND no shell operators/metacharacters are present.
+ * Quoted first tokens (e.g. `"ls" -la`) are resolved before checking.
+ */
+export function isAllowedWhitelist(command: string): boolean {
+	if (command.trim() === "") return false;
+	if (SHELL_METACHARACTER_RE.test(command)) return false;
+	const firstToken = shellFirstToken(command);
+	if (firstToken === "") return false;
+	return WHITELISTED_COMMANDS.has(firstToken);
+}
+
+/** Current safe-bash mode, controlled by the `PI_CREW_SAFE_BASH_MODE` env var. */
+export function getSafeBashMode(): "blacklist" | "whitelist" {
+	return process.env.PI_CREW_SAFE_BASH_MODE === "whitelist" ? "whitelist" : "blacklist";
+}
+
+/**
+ * Unified command check that dispatches on the active mode.
+ * @returns Error message if the command should be blocked, null if allowed.
+ */
+export function checkCommand(command: string, options: SafeBashOptions = {}): string | null {
+	if (getSafeBashMode() === "whitelist") {
+		return isAllowedWhitelist(command) ? null : "Command blocked by safe_bash whitelist: command not in allowlist";
+	}
+	return isDangerous(command, options);
+}

package/src/utils/env-filter.ts

@@ -21,10 +21,59 @@ const KNOWN_PROVIDER_KEYS = new Set([
 	"ZERODEV_API_KEY",
 ]);
 
+// Map from provider prefix (lowercase) to env var names.
+// Used by providerEnvKeys() to scope API keys per task.
+const PROVIDER_ENV_KEY_MAP: Record<string, string[]> = {
+	minimax: ["MINIMAX_API_KEY", "MINIMAX_GROUP_ID"],
+	openai: ["OPENAI_API_KEY", "OPENAI_ORG_ID"],
+	anthropic: ["ANTHROPIC_API_KEY"],
+	google: ["GOOGLE_API_KEY", "GOOGLE_GENERATIVE_LANGUAGE_API_KEY"],
+	gemini: ["GOOGLE_API_KEY", "GOOGLE_GENERATIVE_LANGUAGE_API_KEY"],
+	azure: ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"],
+	"azure-openai": ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"],
+	aws: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+	bedrock: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+	zai: ["ZEU_API_KEY"],
+	zerodev: ["ZERODEV_API_KEY"],
+};
+
 function isKnownProviderKey(key: string): boolean {
 	return KNOWN_PROVIDER_KEYS.has(key);
 }
 
+/**
+ * Extract provider prefix from a model ID string and return the corresponding
+ * env var names. Returns empty array for unknown/custom providers or invalid input.
+ *
+ * @param modelId - Model in "provider/modelId" format (e.g. "openai/gpt-4o")
+ * @returns Array of env var names needed for this provider
+ */
+export function providerEnvKeys(modelId: string | undefined): string[] {
+	if (!modelId) return [];
+	const separatorIndex = modelId.indexOf("/");
+	if (separatorIndex <= 0) return [];
+	const provider = modelId.substring(0, separatorIndex).toLowerCase();
+	return PROVIDER_ENV_KEY_MAP[provider] ?? [];
+}
+
+/**
+ * Build a scoped allowlist that includes system vars + only the provider keys
+ * relevant to the assigned model (and its fallback chain).
+ *
+ * @param baseAllowList - Non-provider system vars to always include
+ * @param models - Model IDs to include provider keys for (primary + fallbacks)
+ * @returns Combined allowlist with scoped provider keys
+ */
+export function buildScopedAllowList(baseAllowList: string[], models: (string | undefined)[]): string[] {
+	const providerKeys = new Set<string>();
+	for (const model of models) {
+		for (const key of providerEnvKeys(model)) {
+			providerKeys.add(key);
+		}
+	}
+	return [...baseAllowList, ...providerKeys];
+}
+
 export interface SanitizeEnvOptions {
 	/** Allow-list of env var names to preserve. Supports trailing glob, e.g. `"PI_*"`. */
 	allowList?: string[];

package/workflows/plan-execute.workflow.md

@@ -0,0 +1,30 @@
+---
+name: plan-execute
+description: Plan and execute a goal already analyzed by the calling session (no explore step)
+topology: sequential
+---
+
+## plan
+role: planner
+output: plan.md
+reads: analysis.md
+
+Create a concise implementation plan for: {goal}
+
+The calling session has already analyzed the problem. Its analysis is provided
+as shared context (analysis.md). Build directly on that analysis; only re-verify
+file paths and facts you need. Do not redo full discovery.
+
+## execute
+role: executor
+dependsOn: plan
+
+Implement the plan for: {goal}
+
+## verify
+role: verifier
+dependsOn: execute
+verify: true
+
+Verify completion for: {goal}
+Run tests ONCE (cache to .crew/cache/), read changed files from executor context. Cross-reference test output with the changes. Do NOT re-run tests. Give PASS or FAIL with specific test evidence.