pi-crew 0.5.16 → 0.5.17

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## [0.5.17] — Security Hardening + ECC Patterns + Skill Review (2026-06-03)
+
+### Highlights
+- **3 CRITICAL security fixes**: path traversal, sandbox escape, executeUnchecked bypass
+- **3 HIGH security fixes**: allowPatterns bypass, safe-bash fallback message, mock mode
+- **3 MEDIUM security fixes**: home hooks visibility, API keys documentation, sync lock deprecation
+- **2 new features** from ECC/dmux patterns: seedPaths overlay + structured handoff template
+- **2 gap fills**: handoff parser + per-step seedPaths
+- **36 skills reviewed**: origin fields, broken refs fixed, verify-skill.ts updated
+- **1 bug fix**: adaptive-plan parser strips markdown code fences
+- **1 regression fix**: mock mode NODE_ENV gate reverted
+- **41 new tests** across 6 test files
+
+### Security Fixes
+
+#### CRITICAL
+1. `orchestrate.ts`: Path traversal — planPath validated with `resolveContainedPath()`
+2. `sandbox.ts`: Prototype pollution — `Object.freeze` on prototypes, `globalThis`/`global` in FORBIDDEN_PATTERNS
+3. `dynamic-script-runner.ts`: `executeUnchecked` → private, `__test_executeUnchecked` test-only export
+
+#### HIGH
+4. `safe-bash.ts`: allowPatterns validation rejects `/.*/` and permissive catch-all patterns
+5. `safe-bash-extension.ts`: Error message no longer suggests bypassing safe-bash
+6. `child-pi.ts`: Mock mode requires `PI_CREW_ALLOW_MOCK=1` (set in parent process only)
+
+#### MEDIUM
+7. `worktree-manager.ts`: `logInternalError` warning when home directory hooks accepted
+8. `child-pi.ts`: SECURITY WARNING JSDoc on API key allow-list trade-off
+9. `event-log.ts`: Expanded deprecation notice on `withEventLogLockSync` blocking behavior
+
+### Features (ECC/dmux patterns)
+
+- **seedPaths**: Overlay local/uncommitted files into worktrees via config (`worktree.seedPaths`) or per-step (`WorkflowStep.seedPaths`). Path traversal validation, dedup, recursive copy.
+- **Structured Handoff Template**: `HANDOFF_TEMPLATE` constant + `parseHandoffFromOutput()` parser. Agents receive handoff format instructions automatically.
+
+### Skill Review
+- All 36 skills: added `origin` YAML frontmatter field
+- Fixed `widget-rendering` wrong file path
+- Fixed `orchestration` + `detection-pipeline-design` broken cross-skill references
+- Fixed 4 skills with wrong `source/pi-mono/` paths
+- `verify-skill.ts` now validates `origin` field
+
+### Bug Fixes
+- `adaptive-plan.ts`: `stripCodeFence()` strips markdown code fences inside ADAPTIVE_PLAN markers — fixes planner output parsing for non-frontier models
+- Mock mode regression: reverted NODE_ENV gate, uses PI_CREW_ALLOW_MOCK only (child processes don't inherit NODE_ENV)
+
+### Stats
+- Test suite: 2698 pass + 1 skip, 0 fail (was 2657 in v0.5.16; +41 net)
+- TypeScript: 0 errors
+- New test files: 6 (worktree-seed-paths, task-handoff-template, task-handoff-parser, adaptive-plan +3 safe-bash tests)
+- Files touched: 50+
+- Security issues fixed: 9 (3 CRITICAL + 3 HIGH + 3 MEDIUM)
+- False positives verified: 2
+
 ## [0.5.16] — Rounds 22–31 Audit Fixes (2026-06-02)
 
 ### Highlights

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/skills/artifact-analysis-loop/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: artifact-analysis-loop
 description: "Systematic artifact examination for code, files, and binaries."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "analyze this artifact"
   - "examine file"

package/skills/async-worker-recovery/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: async-worker-recovery
 description: Background worker, heartbeat, stale-run, crash-recovery, and deadletter workflow. Use when debugging stuck/dead workers or changing async run reliability.
+origin: pi-crew
 triggers:
   - "worker crashed"
   - "stale run"

package/skills/child-pi-spawning/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: child-pi-spawning
 description: "Child Pi worker spawning, lifecycle callbacks, and failure modes."
+origin: pi-crew
 triggers:
   - "worker crashed"
   - "worker blink"

package/skills/context-artifact-hygiene/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: context-artifact-hygiene
 description: "Use when constructing worker prompts, reading artifacts/logs, summarizing runs, compacting context, or handing work between agents."
+origin: pi-crew
 triggers:
   - "construct prompt"
   - "read artifact"

package/skills/delegation-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: delegation-patterns
 description: "Subagent/team delegation workflow."
+origin: pi-crew
 triggers:
   - "delegate this"
   - "split this task"

package/skills/detection-pipeline-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: detection-pipeline-design
 description: "Design data pipelines for security monitoring and threat intelligence."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "build pipeline"
   - "design detection"
@@ -282,4 +283,4 @@ npx tsc --noEmit
 node --experimental-strip-types --test test/unit/detection-pipeline.test.ts
 ```
 
-*See also: `detection-signature-authoring` (in security-review) for detection rule patterns.*
+*See also: `security-review` skill for detection rule patterns and signature authoring guidance.*

package/skills/event-log-tracing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: event-log-tracing
 description: "Structured event logging for worker lifecycle, live agents, crash recovery."
+origin: pi-crew
 triggers:
   - "event log"
   - "trace events"

package/skills/git-master/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: git-master
 description: "Commit and release hygiene for safe version-control work."
+origin: pi-crew
 triggers:
   - "commit this"
   - "tag release"

package/skills/hunting-investigation-loop/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: hunting-investigation-loop
 description: "Active hypothesis-driven investigation and threat hunting."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "hunt for"
   - "find evidence of"

package/skills/incident-playbook-construction/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: incident-playbook-construction
 description: "Build structured incident response playbooks and runbooks."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "build playbook"
   - "create runbook"

package/skills/iterative-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: iterative-audit
 description: "Iterative multi-round codebase audit with diminishing-returns detection. Run 5-20+ rounds, each focusing on one specific area. Built from 19 rounds of dogfooding pi-crew on itself."
+origin: pi-crew
 triggers:
   - "audit this codebase"
   - "review everything"

package/skills/live-agent-lifecycle/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: live-agent-lifecycle
 description: "Live agent registration, workspace isolation, termination, and eviction workflow."
+origin: pi-crew
 triggers:
   - "register agent"
   - "terminate agent"

package/skills/mailbox-interactive/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: mailbox-interactive
 description: "Interactive waiting-task and mailbox workflow."
+origin: pi-crew
 triggers:
   - "respond to worker"
   - "nudge agent"

package/skills/model-routing-context/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: model-routing-context
 description: Model routing, parent context, thinking level, and prompt construction workflow. Use when changing model fallback, child Pi args, inherited context, task prompts, or compact-read behavior.
+origin: pi-crew
 triggers:
   - "change model"
   - "parent context"
@@ -15,7 +16,7 @@ Use this skill when working on model/context propagation.
 
 ## Source patterns distilled
 
-- Pi session context/model state: `source/pi-mono/packages/coding-agent/src/core/session-manager.ts`, `agent-session.ts`, compaction modules
+- Pi session context/model state: `source/pi/packages/coding-agent/src/core/session-manager.ts`, `agent-session.ts`, compaction modules
 - pi-crew model and prompt code: `src/runtime/model-fallback.ts`, `src/runtime/pi-args.ts`, `src/runtime/task-runner/prompt-builder.ts`, `src/runtime/task-output-context.ts`, `src/extension/team-tool/context.ts`
 
 ## Rules

package/skills/multi-perspective-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: multi-perspective-review
 description: "Multi-perspective code review with simpler-alternative pass."
+origin: pi-crew
 triggers:
   - "review this"
   - "look at this"

package/skills/observability-reliability/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: observability-reliability
 description: "Metrics, diagnostics, correlation, retry, deadletter, and recovery evidence workflow."
+origin: pi-crew
 triggers:
   - "add metrics"
   - "diagnose failure"

package/skills/orchestration/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: orchestration
 description: "Multi-phase orchestration for planners and executors."
+origin: pi-crew
 triggers:
   - "orchestrate this"
   - "coordinate tasks"
@@ -73,7 +74,7 @@ Maintain the original scope exactly. Không mở rộng scope vì "thấy thêm
 ### Step 3 — Dispatch phase
 
 - Launch all parallel subagents in one `team` call.
-- Each subagent receives a complete task packet (see `task-packet` skill).
+- Each subagent receives a complete task packet (see `requirements-to-task-packet` skill).
 - Set explicit file ownership per worker — no two workers touch the same file.
 - Use `workspaceMode: 'worktree'` when parallel edits risk conflict.
 

package/skills/ownership-session-security/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ownership-session-security
 description: "Session ownership and authorization workflow."
+origin: pi-crew
 triggers:
   - "cancel run"
   - "respond to task"

package/skills/pi-extension-lifecycle/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: pi-extension-lifecycle
 description: Pi extension lifecycle and registration patterns.
+origin: pi-crew
 triggers:
   - "add extension"
   - "register tools"
@@ -15,8 +16,8 @@ Use this skill when working on Pi extension registration or lifecycle behavior.
 
 ## Source patterns distilled
 
-- Pi core: `source/pi-mono/packages/coding-agent/src/core/extensions/types.ts`, `loader.ts`, `runner.ts`
-- Pi examples: `source/pi-mono/packages/coding-agent/examples/extensions/`
+- Pi core: `source/pi/packages/coding-agent/src/core/extensions/types.ts`, `loader.ts`, `runner.ts`
+- Pi examples: `source/pi/packages/coding-agent/examples/extensions/`
 - pi-crew extension entry: `src/extension/register.ts`, `src/extension/registration/*.ts`
 
 ## Rules

package/skills/post-mortem/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: post-mortem
 description: "Write engineering RCA record after bug is fixed."
+origin: pi-crew
 triggers:
   - "post-mortem"
   - "root cause"

package/skills/read-only-explorer/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: read-only-explorer
 description: "Read-only exploration and audit workflow."
+origin: pi-crew
 triggers:
   - "explore code"
   - "audit source"

package/skills/requirements-to-task-packet/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: requirements-to-task-packet
 description: "Use when a goal, issue, roadmap item, review finding, or user request must become actionable worker tasks."
+origin: pi-crew
 triggers:
   - "convert requirements"
   - "create task packet"

package/skills/resource-discovery-config/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: resource-discovery-config
 description: "pi-crew resource and configuration discovery workflow."
+origin: pi-crew
 triggers:
   - "discover agents"
   - "find teams"
@@ -15,7 +16,7 @@ Use this skill for pi-crew resource/config work.
 
 ## Source patterns distilled
 
-- Pi resource loader: `source/pi-mono/packages/coding-agent/src/core/resource-loader.ts`, extension `resources_discover` hook
+- Pi resource loader: `source/pi/packages/coding-agent/src/core/resource-loader.ts`, extension `resources_discover` hook
 - pi-crew discovery: `src/agents/discover-agents.ts`, `src/teams/discover-teams.ts`, `src/workflows/discover-workflows.ts`
 - Config: `src/config/config.ts`, `src/schema/config-schema.ts`, `schema.json`, `docs/resource-formats.md`
 

package/skills/runtime-state-reader/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: runtime-state-reader
 description: Safe read-only navigation of pi-crew run state.
+origin: pi-crew
 triggers:
   - "inspect manifest"
   - "read tasks"

package/skills/safe-bash/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: safe-bash
 description: "Safe shell-command workflow."
+origin: pi-crew
 triggers:
   - "run this command"
   - "execute bash"

package/skills/scrutinize/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: scrutinize
 description: "Outsider-perspective review questioning intent before tracing code."
+origin: pi-crew
 triggers:
   - "scrutinize this"
   - "question this"

package/skills/secure-agent-orchestration-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: secure-agent-orchestration-review
 description: "Use when reviewing delegation, skill loading, tool access, worker prompts, artifacts, runtime config, state, ownership, or subprocess execution."
+origin: pi-crew
 triggers:
   - "review delegation"
   - "check skill security"

package/skills/security-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: security-review
 description: "Security review patterns with audit and detection authoring."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "security review"
   - "vulnerability scan"

package/skills/state-mutation-locking/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: state-mutation-locking
 description: "Durable state mutation and locking workflow."
+origin: pi-crew
 triggers:
   - "modify manifest"
   - "update tasks"

package/skills/systematic-debugging/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: systematic-debugging
 description: "Four-phase debugging discipline with refuse gates."
+origin: pi-crew
 triggers:
   - "debug this"
   - "investigate"

package/skills/threat-hypothesis-framework/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: threat-hypothesis-framework
 description: "Structured investigation using testable hypotheses."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "hunt for"
   - "investigate"

package/skills/ui-render-performance/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ui-render-performance
 description: "Non-blocking Pi TUI render workflow."
+origin: pi-crew
 triggers:
   - "widget render"
   - "dashboard pane"
@@ -14,7 +15,7 @@ Use this skill for Pi/pi-crew TUI work.
 
 ## Source patterns distilled
 
-- Pi TUI is synchronous immediate-mode/string rendering: `source/pi-mono/packages/coding-agent/src/modes/interactive/interactive-mode.ts`
+- Pi TUI is synchronous immediate-mode/string rendering: `source/pi/packages/coding-agent/src/modes/interactive/interactive-mode.ts`
 - Pi extension examples use event-driven state updates, not render-time loading.
 - pi-crew UI: `src/extension/register.ts`, `src/ui/run-dashboard.ts`, `src/ui/run-snapshot-cache.ts`, `src/ui/crew-widget.ts`, `src/ui/powerbar-publisher.ts`, `src/ui/render-scheduler.ts`
 

package/skills/verification-before-done/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: verification-before-done
 description: "Evidence before claims."
+origin: pi-crew
 triggers:
   - "done"
   - "verify this"

package/skills/widget-rendering/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: widget-rendering
 description: "Pi TUI crew widget data sources, display priority, and rendering performance."
+origin: pi-crew
 triggers:
   - "empty agent"
   - "ghost run"
@@ -259,7 +260,7 @@ If ANY answer is NO → Stop. Fix widget rendering issues before proceeding.
 - `src/runtime/crew-agent-records.ts` — readCrewAgents, agents.json
 - `src/runtime/process-status.ts` — hasStaleAsyncProcess, isDisplayActiveRun
 - `src/runtime/background-runner.ts` — active run filtering with async PID check
-- `src/runtime/active-run-registry.ts` — purgeStaleActiveRunIndex
+- `src/state/active-run-registry.ts` — purgeStaleActiveRunIndex
 
 ---
 

package/skills/workspace-isolation/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: workspace-isolation
 description: "Workspace isolation boundaries."
+origin: pi-crew
 triggers:
   - "workspace isolation"
   - "cross-workspace access"

package/skills/worktree-isolation/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: worktree-isolation
 description: "Conflict-safe git worktree workflow."
+origin: pi-crew
 triggers:
   - "create worktree"
   - "parallel workers"

package/src/config/types.ts

@@ -81,6 +81,7 @@ export interface CrewWorktreeConfig {
 	setupHook?: string;
 	setupHookTimeoutMs?: number;
 	linkNodeModules?: boolean;
+	seedPaths?: string[];
 }
 
 export interface CrewUiConfig {

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

@@ -15,6 +15,7 @@ import {
 	parsePlanDocumentSimple,
 	type OrchestratedStep,
 } from "../plan-orchestrate.ts";
+import { resolveContainedPath } from "../../utils/safe-paths.ts";
 
 /**
  * Handle the orchestrate action.
@@ -38,10 +39,17 @@ export function handleOrchestrate(
 		);
 	}
 
-	// Resolve relative paths against ctx.cwd
-	const resolvedPath = path.isAbsolute(planPath)
-		? planPath
-		: path.resolve(ctx.cwd, planPath);
+	// Resolve and validate path stays within ctx.cwd (path-traversal protection)
+	let resolvedPath: string;
+	try {
+		resolvedPath = resolveContainedPath(ctx.cwd, planPath);
+	} catch {
+		return result(
+			`planPath must be within project directory: ${planPath}`,
+			{ action: "orchestrate", status: "error" },
+			true,
+		);
+	}
 
 	if (!fs.existsSync(resolvedPath)) {
 		return result(

package/src/runtime/adaptive-plan.ts

@@ -44,11 +44,27 @@ export function slug(value: string): string {
 	return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "task";
 }
 
+/** Strip surrounding markdown code fences if present. */
+function stripCodeFence(raw: string): string {
+	let s = raw.trim();
+	// Remove opening fence: ```json or ```
+	if (s.startsWith("```")) {
+		const firstNewline = s.indexOf("\n");
+		if (firstNewline >= 0) s = s.slice(firstNewline + 1);
+		else s = s.slice(3); // edge case: ``` alone on one line
+	}
+	// Remove closing fence
+	if (s.endsWith("```")) {
+		s = s.slice(0, -3);
+	}
+	return s.trim();
+}
+
 export function extractAdaptivePlanJson(text: string): string | undefined {
 	const markerMatch = text.match(/ADAPTIVE_PLAN_JSON_START\s*([\s\S]*?)\s*ADAPTIVE_PLAN_JSON_END/);
-	if (markerMatch?.[1]) return markerMatch[1];
+	if (markerMatch?.[1]) return stripCodeFence(markerMatch[1]);
 	const startIndex = text.indexOf("ADAPTIVE_PLAN_JSON_START");
-	if (startIndex >= 0) return text.slice(startIndex + "ADAPTIVE_PLAN_JSON_START".length).trim();
+	if (startIndex >= 0) return stripCodeFence(text.slice(startIndex + "ADAPTIVE_PLAN_JSON_START".length));
 	const fencedMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
 	return fencedMatch?.[1];
 }

package/src/runtime/child-pi.ts

@@ -181,6 +181,16 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): S
 	// 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.
+			 */
 			// Model provider API keys (explicit list — do NOT use wildcards)
 			"MINIMAX_API_KEY",
 			"MINIMAX_GROUP_ID",
@@ -405,14 +415,16 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	if (depth.blocked) return { exitCode: 1, stdout: "", stderr: `pi-crew depth guard blocked child worker: depth ${depth.depth} >= max ${depth.maxDepth}` };
 	const mock = process.env.PI_TEAMS_MOCK_CHILD_PI;
 	if (mock) {
-		// SECURITY: Log mock mode activation prominently for audit trail
-		console.warn(`[⚠️ PI_CREW_MOCK_MODE] Mock mode active: ${mock} — NOT running real agents!`);
-		// SECURITY FIX: Require PI_CREW_ALLOW_MOCK alongside PI_TEAMS_MOCK_CHILD_PI
+		// SECURITY: Require explicit PI_CREW_ALLOW_MOCK=1 to activate mock mode.
+		// PI_CREW_ALLOW_MOCK must be set in the parent process env (not by child hooks)
+		// since sanitizeEnvSecrets only passes PI_CREW_* vars from the parent.
+		// Setup hooks cannot inject PI_CREW_ALLOW_MOCK into the parent's env.
 		const allowMock = process.env.PI_CREW_ALLOW_MOCK === "1" || process.env.PI_CREW_ALLOW_MOCK === "true";
 		if (!allowMock) {
-			console.error(`[🚨 PI_CREW_MOCK_MODE] SECURITY: PI_TEAMS_MOCK_CHILD_PI is set but PI_CREW_ALLOW_MOCK is not "1". Ignoring mock request for safety.`);
-			return { exitCode: 1, stdout: "", stderr: "Mock mode requires PI_CREW_ALLOW_MOCK=1 alongside PI_TEAMS_MOCK_CHILD_PI" };
+			return { exitCode: 1, stdout: "", stderr: "Mock mode requires PI_CREW_ALLOW_MOCK=1" };
 		}
+		// SECURITY: Log mock mode activation prominently for audit trail
+		console.warn(`Mock mode active: ${mock} — NOT running real agents!`);
 		if (mock === "success") {
 			const stdout = `[MOCK] Success for ${input.agent.name}\n`;
 			observeStdoutChunk(input, stdout);

package/src/runtime/dynamic-script-runner.ts

@@ -444,8 +444,9 @@ export class DynamicScriptRunner {
 	/**
 	 * Execute a script without validation (assumes pre-validated).
 	 * Use with caution - prefer execute() for untrusted scripts.
+	 * @internal TEST ONLY — do not use in production code
 	 */
-	executeUnchecked(code: string, timeout?: number): ScriptExecutionResult {
+	private executeUnchecked(code: string, timeout?: number): ScriptExecutionResult {
 		const startTime = Date.now();
 
 		try {
@@ -480,3 +481,15 @@ export class DynamicScriptRunner {
 export function createScriptRunner(options?: DynamicScriptOptions): DynamicScriptRunner {
 	return new DynamicScriptRunner(options);
 }
+
+/**
+ * @internal TEST ONLY — do not use in production code.
+ * Exposes DynamicScriptRunner.executeUnchecked for unit testing.
+ */
+export function __test_executeUnchecked(
+	runner: DynamicScriptRunner,
+	code: string,
+	timeout?: number,
+): ScriptExecutionResult {
+	return (runner as unknown as { executeUnchecked: (code: string, timeout?: number) => ScriptExecutionResult }).executeUnchecked(code, timeout);
+}

package/src/runtime/sandbox.ts

@@ -18,6 +18,9 @@ const FORBIDDEN_PATTERNS = [
 	/__dirname/,                       // __dirname reference
 	/__filename/,                      // __filename reference
 	/\bdefine\s*\(/,                  // AMD define
+	// Global escape vectors
+	/\bglobalThis\b/,                 // globalThis reference
+	/\bglobal\b/,                      // global reference (Node.js)
 ] as const;
 
 /**
@@ -119,6 +122,11 @@ export class WorkflowSandbox {
 			safeGlobals[key] = value;
 		}
 
+		// Freeze prototypes before passing to sandbox context to prevent
+		// prototype pollution from sandboxed code escaping the sandbox.
+		Object.freeze(Object.prototype);
+		Object.freeze(Array.prototype);
+
 		// Context isolation - explicitly list allowed globals
 		const contextGlobals: Record<string, unknown> = {
 			...safeGlobals,

package/src/runtime/task-packet.ts

@@ -128,6 +128,130 @@ export function validateTaskPacket(packet: TaskPacket): TaskPacketValidationResu
 	return { valid: errors.length === 0, errors };
 }
 
+/**
+ * Structured handoff template for task completion reports.
+ * Distilled from ECC dmux-workflows pattern — workers use this format
+ * so verifiers and downstream consumers can parse output predictably.
+ */
+export const HANDOFF_TEMPLATE = [
+	"## Handoff",
+	"",
+	"### Summary",
+	"<!-- 2-3 sentences describing what was done -->",
+	"",
+	"### Files Changed",
+	"<!-- List each file changed with brief description -->",
+	"<!-- - path/to/file.ts: description -->",
+	"",
+	"### Tests / Verification",
+	"<!-- What tests pass? What was manually verified? -->",
+	"",
+	"### Follow-ups",
+	"<!-- Any remaining issues or next steps -->",
+].join("\n");
+
+export interface ParsedHandoff {
+	summary: string[];
+	filesChanged: string[];
+	tests: string[];
+	followups: string[];
+}
+
+/**
+ * Extract text between a ### heading and the next ### heading or end of text.
+ */
+function extractSection(content: string, heading: string): string {
+	const lines = content.split("\n");
+	const headingMarker = `### ${heading}`;
+	const startIndex = lines.findIndex((line) => line.trim() === headingMarker);
+	if (startIndex === -1) return "";
+
+	const collected: string[] = [];
+	for (let i = startIndex + 1; i < lines.length; i++) {
+		const trimmed = lines[i].trim();
+		if (trimmed.startsWith("### ") || trimmed.startsWith("## ")) break;
+		// Stop at paragraph text (non-bullet, non-comment, non-empty) that follows
+		// a blank line — signals end of subsection content.
+		if (
+			trimmed.length > 0 &&
+			!trimmed.startsWith("- ") &&
+			!trimmed.startsWith("<!--") &&
+			i > startIndex + 1 &&
+			lines[i - 1].trim() === "" &&
+			collected.some((l) => l.trim().length > 0)
+		) {
+			break;
+		}
+		collected.push(lines[i]);
+	}
+
+	return collected.join("\n").trim();
+}
+
+/**
+ * Parse bullet list items from a section, stripping leading "- " and backtick wrapping.
+ */
+function parseBullets(section: string): string[] {
+	if (!section) return [];
+	return section
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.startsWith("- "))
+		.map((line) => {
+			let item = line.replace(/^- /, "").trim();
+			// Strip surrounding backticks
+			if (item.startsWith("`") && item.endsWith("`") && item.length >= 2) {
+				item = item.slice(1, -1);
+			}
+			return item;
+		});
+}
+
+/**
+ * Parse a handoff section that may contain bullets AND free-text paragraphs.
+ * Returns all non-empty lines as individual items (bullets get their marker stripped).
+ */
+function parseMixedContent(section: string): string[] {
+	if (!section) return [];
+	return section
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0 && !line.startsWith("<!--")) // skip HTML comments
+		.map((line) => {
+			if (line.startsWith("- ")) return line.slice(2).trim();
+			return line;
+		})
+		.map((item) => {
+			// Strip surrounding backticks
+			if (item.startsWith("`") && item.endsWith("`") && item.length >= 2) {
+				return item.slice(1, -1);
+			}
+			return item;
+		});
+}
+
+/**
+ * Parse structured handoff data from agent output text.
+ * Looks for the "## Handoff" heading and extracts subsections.
+ * Returns empty arrays for sections not found.
+ */
+export function parseHandoffFromOutput(output: string): ParsedHandoff {
+	if (!output || typeof output !== "string") {
+		return { summary: [], filesChanged: [], tests: [], followups: [] };
+	}
+
+	// Find the handoff section — look for ## Handoff
+	const handoffIndex = output.indexOf("## Handoff");
+	const content = handoffIndex >= 0 ? output.slice(handoffIndex) : output;
+
+	return {
+		summary: parseMixedContent(extractSection(content, "Summary")),
+		filesChanged: parseMixedContent(extractSection(content, "Files Changed")),
+		tests: parseMixedContent(extractSection(content, "Tests / Verification")),
+		followups: parseMixedContent(extractSection(content, "Follow-ups")),
+	};
+}
+
 export function renderTaskPacket(packet: TaskPacket): string {
 	return [
 		"# Task Packet",

package/src/runtime/task-runner/prompt-builder.ts

@@ -3,7 +3,7 @@ import type { TeamRunManifest, TeamTaskState, TaskOutputSchema } from "../../sta
 import type { WorkflowStep } from "../../workflows/workflow-config.ts";
 import { buildMemoryBlock } from "../agent-memory.ts";
 import { permissionForRole } from "../role-permission.ts";
-import { renderTaskPacket } from "../task-packet.ts";
+import { renderTaskPacket, HANDOFF_TEMPLATE } from "../task-packet.ts";
 import { buildWorkspaceTree } from "../workspace-tree.ts";
 
 /**
@@ -132,6 +132,9 @@ export async function renderTaskPrompt(manifest: TeamRunManifest, step: Workflow
 		task.taskPacket?.outputSchema ? renderOutputSchemaBlock(task.taskPacket.outputSchema) : "",
 		"Task:",
 		step.task.replaceAll("{goal}", manifest.goal),
+		"",
+		"When your task is complete, structure your final output using this handoff template:",
+		HANDOFF_TEMPLATE,
 	].join("\n");
 
 	const full = [stablePrefix, "", dynamicSuffix].join("\n");

package/src/runtime/task-runner.ts

@@ -156,7 +156,7 @@ export async function runTeamTask(
 	let streamBridge: ReturnType<typeof registerStreamBridge> | undefined;
 	try {
 		streamBridge = registerStreamBridge(manifest.runId);
-		const workspace = prepareTaskWorkspace(manifest, input.task);
+		const workspace = prepareTaskWorkspace(manifest, input.task, input.step.seedPaths);
 		const worktree =
 			workspace.worktreePath && workspace.branch
 				? {

package/src/schema/config-schema.ts

@@ -56,6 +56,7 @@ export const PiTeamsWorktreeConfigSchema = Type.Object({
 	setupHook: Type.Optional(Type.String({ minLength: 1 })),
 	setupHookTimeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
 	linkNodeModules: Type.Optional(Type.Boolean()),
+	seedPaths: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
 }, { additionalProperties: false });
 
 export const AgentOverrideSchema = Type.Object({

package/src/state/event-log.ts

@@ -66,6 +66,13 @@ let appendCounter = 0;
  *
  *  @deprecated Prefer `appendEventAsync()` for callers in async contexts. The sync lock
  *  uses `sleepSync` which blocks the event loop and prevents AbortSignal handlers from firing.
+ *
+ *  SECURITY WARNING: This function uses `sleepSync` in its lock-acquire retry loop, which
+ *  blocks the Node.js event loop for up to 120s. During that time, AbortSignal handlers
+ *  cannot fire, SIGTERM handlers are delayed, and the process appears unresponsive to
+ *  orchestrator health checks. Known callers include `appendEvent` (sync path),
+ *  `flushOneEventLogBuffer`, and `state/mailbox.ts`. Prefer the async alternative
+ *  (`appendEventAsync`) for all new code.
  */
 export function withEventLogLockSync<T>(eventsPath: string, fn: () => T): T {
 	// Ensure parent directory exists before attempting lock

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

@@ -84,7 +84,7 @@ export default function safeBashExtension(pi: ExtensionAPI): void {
 					content: [
 						{
 							type: "text" as const,
-							text: `🚫 ${danger}\n\nIf you need to run this command, use the regular 'bash' tool instead, but be careful!`,
+							text: `🚫 ${danger}\n\nCommand blocked by safety policy. If this is a false positive, ask the user for confirmation or use force: true with explicit user approval.`,
 						},
 					],
 				};

package/src/tools/safe-bash.ts

@@ -4,6 +4,8 @@
  * Uses linear-time scanning to prevent ReDoS attacks
  */
 
+import { logInternalError } from "../utils/internal-error.ts";
+
 
 // Backward-compatible pattern array (kept for getPatterns API)
 // IMPORTANT: Line 8 (rm pattern with nested quantifiers) has been replaced
@@ -162,6 +164,14 @@ export function isDangerous(command: string, options: SafeBashOptions = {}): str
 
 	if (!enabled) return null;
 
+	// Reject overly permissive allowPatterns that would bypass all safety
+	for (const pattern of allowPatterns) {
+		if (pattern.source === ".*" || (pattern.test("") && pattern.test("rm -rf /"))) {
+			logInternalError("safe-bash.permissive-allow-pattern", new Error(`allowPattern rejects nothing: ${pattern}`));
+			throw new Error(`Overly permissive allowPattern rejected: ${pattern}. Use specific patterns only.`);
+		}
+	}
+
 	// Normalize: remove line continuations, collapse whitespace
 	const normalized = command.replace(/\\\n/g, " ").replace(/\s+/g, " ").trim();
 

package/src/workflows/workflow-config.ts

@@ -14,6 +14,9 @@ export interface WorkflowStep {
 	progress?: boolean;
 	worktree?: boolean;
 	verify?: boolean;
+	/** Per-step files to overlay into the worktree (in addition to global worktree.seedPaths).
+	 * Useful when only certain steps need access to local drafts or scripts. */
+	seedPaths?: string[];
 }
 
 export interface WorkflowConfig {

package/src/worktree/worktree-manager.ts

@@ -116,6 +116,11 @@ function runSetupHook(manifest: TeamRunManifest, task: TeamTaskState, repoRoot:
 		logInternalError("worktree.setupHook.rejected", new Error("hook path not allowed: " + rawHookPath), `cwd=${manifest.cwd}`);
 		return [];
 	}
+	// SECURITY WARNING: Home directory hooks (~/.pi/hooks/) are user-writable and not project-scoped.
+	// A rogue npm postinstall script could place malicious hooks there. Log for visibility.
+	if (path.isAbsolute(rawHookPath)) {
+		logInternalError("worktree.setupHook.homeHook", new Error("Home directory hook used — ensure ~/.pi/hooks/ is trusted"), `hookPath=${rawHookPath}`);
+	}
 	const hookPath = path.isAbsolute(rawHookPath) ? rawHookPath : path.resolve(repoRoot, rawHookPath);
 	// SECURITY: Verify the resolved hook path is contained within the real repoRoot.
 	// This prevents symlink-based escape where repoRoot is a symlink.
@@ -201,7 +206,64 @@ function pruneStaleWorktrees(repoRoot: string): void {
 	catch { /* best-effort */ }
 }
 
-export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskState): PreparedTaskWorkspace {
+/**
+ * Normalize and validate seed paths — ensure all paths stay within repoRoot.
+ * Rejects path traversal (../) and absolute paths.
+ */
+export function normalizeSeedPaths(seedPaths: string[], repoRoot: string): string[] {
+	const resolvedRepoRoot = path.resolve(repoRoot);
+	const entries = Array.isArray(seedPaths) ? seedPaths : [];
+	const seen = new Set<string>();
+	const normalized: string[] = [];
+
+	for (const entry of entries) {
+		if (typeof entry !== "string" || entry.trim().length === 0) continue;
+
+		const absolutePath = path.resolve(resolvedRepoRoot, entry);
+		const relativePath = path.relative(resolvedRepoRoot, absolutePath);
+
+		if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+			throw new Error(`seedPaths entries must stay inside repoRoot: ${entry}`);
+		}
+
+		const normalizedPath = relativePath.split(path.sep).join("/");
+		if (seen.has(normalizedPath)) continue;
+		seen.add(normalizedPath);
+		normalized.push(normalizedPath);
+	}
+
+	return normalized;
+}
+
+/**
+ * Overlay seed paths from repoRoot into worktreePath.
+ * Copies files and directories, creating parent dirs as needed.
+ * Skips non-existent sources with logInternalError (non-fatal).
+ */
+export function overlaySeedPaths(repoRoot: string, worktreePath: string, seedPaths: string[]): void {
+	const normalized = normalizeSeedPaths(seedPaths, repoRoot);
+
+	for (const seedPath of normalized) {
+		const sourcePath = path.join(repoRoot, seedPath);
+		const destinationPath = path.join(worktreePath, seedPath);
+
+		if (!fs.existsSync(sourcePath)) {
+			logInternalError("worktree.seedPaths.missing", new Error(`Seed path does not exist: ${seedPath}`));
+			continue;
+		}
+
+		fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+		fs.rmSync(destinationPath, { force: true, recursive: true });
+		fs.cpSync(sourcePath, destinationPath, {
+			dereference: false,
+			force: true,
+			preserveTimestamps: true,
+			recursive: true,
+		});
+	}
+}
+
+export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskState, stepSeedPaths?: string[]): PreparedTaskWorkspace {
 	if (manifest.workspaceMode !== "worktree") return { cwd: task.cwd };
 	const repoRoot = findGitRoot(manifest.cwd);
 	const loadedConfig = loadConfig(manifest.cwd);
@@ -220,6 +282,12 @@ export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskSt
 		if (currentBranch !== branch) {
 			throw new Error(`Existing worktree branch mismatch at ${worktreePath}: expected '${branch}', got '${currentBranch}'.`);
 		}
+		// Overlay seed paths from config + step-level seedPaths (reused worktree)
+		const globalSeedPaths = loadedConfig.config.worktree?.seedPaths ?? [];
+		const mergedReused = normalizeSeedPaths([...globalSeedPaths, ...(stepSeedPaths ?? [])], repoRoot);
+		if (mergedReused.length > 0) {
+			overlaySeedPaths(repoRoot, worktreePath, mergedReused);
+		}
 		return { cwd: worktreePath, worktreePath, branch, reused: true };
 	}
 	pruneStaleWorktrees(repoRoot);
@@ -242,6 +310,12 @@ export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskSt
 	}
 	const syntheticPaths = runSetupHook(manifest, task, repoRoot, worktreePath, branch);
 	const nodeModulesLinked = loadedConfig.config.worktree?.linkNodeModules === true ? linkNodeModulesIfPresent(repoRoot, worktreePath) : false;
+	// Overlay seed paths from config + step-level seedPaths
+	const globalSeedPaths = loadedConfig.config.worktree?.seedPaths ?? [];
+	const merged = normalizeSeedPaths([...globalSeedPaths, ...(stepSeedPaths ?? [])], repoRoot);
+	if (merged.length > 0) {
+		overlaySeedPaths(repoRoot, worktreePath, merged);
+	}
 	return { cwd: worktreePath, worktreePath, branch, reused: false, nodeModulesLinked, syntheticPaths };
 }