pi-crew 0.9.62 → 0.9.64

package/src/agents/agent-config.ts

@@ -60,6 +60,10 @@ export interface AgentConfig {
 	fallbackModels?: string[];
 	thinking?: string;
 	tools?: string[];
+	/** Phase 1 scratchpad opt-in (execute tool). `false` wins over a
+	 * role default (F6 kill-switch); read-only roles are gated out regardless
+	 * (S-6) by `isScratchpadEnabledForRole`. Parsed from frontmatter `scratchpad:`. */
+	scratchpad?: boolean;
 	extensions?: string[];
 	/**
 	 * F1 (v0.7.9): extension denylist (case-insensitive plain names). Applied

package/src/agents/agent-serializer.ts

@@ -15,6 +15,7 @@ export function serializeAgent(agent: AgentConfig): string {
 		line("fallbackModels", agent.fallbackModels),
 		line("thinking", agent.thinking),
 		line("tools", agent.tools),
+		line("scratchpad", agent.scratchpad),
 		agent.extensions !== undefined ? (line("extensions", agent.extensions) ?? "extensions:") : undefined,
 		line("skills", agent.skills),
 		line("systemPromptMode", agent.systemPromptMode),

package/src/agents/discover-agents.ts

@@ -427,6 +427,14 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 			fallbackModels: parseCsv(frontmatter.fallbackModels),
 			thinking: frontmatter.thinking === "false" ? undefined : frontmatter.thinking || undefined,
 			tools: parseToolsField(frontmatter.tools),
+			// Phase 1 scratchpad opt-in (Q3: pi ignores unknown frontmatter keys; pi-crew
+			// is the sole consumer in the worker path — task arrives via -p, agent file
+			// is not re-read by pi). 3-STATE parse (NOT `=== "true"` like
+			// inheritProjectContext): omitted/malformed → undefined so the F6 kill-switch
+			// (`agent.scratchpad === false`) only fires on an EXPLICIT `scratchpad: false`,
+			// not on every agent without the key (which would wrongly kill role
+			// default-on). Only the literal "true"/"false" are honored.
+			scratchpad: frontmatter.scratchpad === "true" ? true : frontmatter.scratchpad === "false" ? false : undefined,
 			// SEC-1: Strip extensions/excludeExtensions for untrusted project-sourced
 			// agents (RCE prevention). Both `project` (.crew/agents/) and
 			// `project-pi` (.pi/agents/) are repo-adjacent / untrusted sources —

package/src/config/role-tools.ts

@@ -3,11 +3,17 @@
  * Uses the excludeTools option from pi v0.77.0.
  */
 
+import { permissionForRole } from "../runtime/role-permission.ts";
+
 export interface RoleToolConfig {
 	/** Explicit list of tools to use (if undefined, use all default tools) */
 	tools?: string[];
 	/** Tools to exclude from the default set */
 	excludeTools?: string[];
+	/** Phase 1 scratchpad: opt-in the persistent Bun-free JS evaluator (execute tool)
+	 * for this role. Only effective on WRITE roles — read-only roles are gated
+	 * out by `isScratchpadEnabledForRole` (S-6, privilege-elevation guard). */
+	scratchpad?: boolean;
 }
 
 export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
@@ -44,9 +50,11 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
-	// Executor - Full access (default)
+	// Executor - Full access (default). Phase 1 scratchpad-enabled (stateful
+	// evaluator compounds intermediate results across execute calls).
 	executor: {
 		// No restrictions - full tool access
+		scratchpad: true,
 	},
 
 	// Reviewer - Read and review, no write
@@ -78,12 +86,16 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	verifier: {
 		tools: ["read", "grep", "find", "ls", "bash"],
 		excludeTools: ["edit", "write", "web"],
+		// Phase 1 scratchpad: multi-cell test/verify flows reuse parsed state.
+		scratchpad: true,
 	},
 
 	// Test Engineer - Can write tests (F1: hyphenated key)
 	"test-engineer": {
 		tools: ["read", "edit", "write", "bash", "ls"],
 		excludeTools: ["web"],
+		// Phase 1 scratchpad: build/run test suites with state across cells.
+		scratchpad: true,
 	},
 };
 
@@ -116,3 +128,39 @@ export function getRestrictedRoles(): string[] {
 		.filter(([, config]) => config.tools !== undefined || config.excludeTools !== undefined)
 		.map(([role]) => role);
 }
+
+/** Agent frontmatter shape consumed by the scratchpad opt-in check. */
+export interface ScratchpadAgentOption {
+	scratchpad?: boolean;
+}
+
+/**
+ * Phase 1: is the scratchpad (execute tool) enabled for this role/agent?
+ *
+ * Decision order (load-bearing — do not reorder):
+ *  1. S-6 (SECURITY, privilege-elevation guard): read-only roles NEVER enable,
+ *     regardless of any agent frontmatter opt-in. A `scratchpad: true` on a
+ *     read-only role (e.g. security-reviewer, whose tool-set is read/grep/find
+ *     with NO bash) would grant full-trust JS execution (fs/network/env/
+ *     child_process) inside a role designed to have no execution — a real
+ *     elevation. `permissionForRole` is default-deny (unknown → read_only), so
+ *     typos/underscore/case-drift cannot bypass this.
+ *  2. F6 (kill-switch): `agent.scratchpad === false` WINS over the role default,
+ *     giving an emergency off-switch for an experimental full-trust feature.
+ *  3. agent explicit opt-in (`scratchpad: true`) OR role default (`scratchpad:
+ *     true` in ROLE_TOOL_CONFIGS).
+ *
+ * F10: `permissionForRole` and `getToolConfig` both expect HYPHENATED role
+ * strings (runtime convention); a raw underscore role would default-deny
+ * wrongly, so normalize FIRST.
+ */
+export function isScratchpadEnabledForRole(role: string, agent?: ScratchpadAgentOption): boolean {
+	// F10: normalize underscore→hyphen before every downstream lookup.
+	const normalized = role.includes("_") ? role.replaceAll("_", "-") : role;
+	// S-6 (điều kiện tiên quyết): read-only gate trước mọi agent flag.
+	if (permissionForRole(normalized) === "read_only") return false;
+	// F6: explicit-false agent override (kill-switch) wins over role default.
+	if (agent?.scratchpad === false) return false;
+	// agent explicit opt-in OR role default.
+	return agent?.scratchpad === true || getToolConfig(normalized).scratchpad === true;
+}

package/src/prompt/prompt-runtime.ts

@@ -4,6 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { startChildBrokerClient } from "../runtime/broker/crew-broker-child.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { registerScratchpadLifecycle } from "./scratchpad-lifecycle.ts";
 
 export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
 export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
@@ -377,4 +378,9 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 		if (rewritten === event.systemPrompt) return;
 		return { systemPrompt: rewritten };
 	});
+
+	// ── Phase 1 scratchpad (T6): conditional `execute` tool + EngineManager
+	// lifecycle. Registers nothing when PI_CREW_SCRATCHPAD !== "1" (D3) and
+	// only flushes+kills the engine on session_shutdown reason "quit" (F3).
+	registerScratchpadLifecycle(pi);
 }