frappe-builder 1.1.0-dev.13 → 1.1.0-dev.17

package/extensions/agent-chain.ts

@@ -0,0 +1,248 @@
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendFileSync } from "node:fs";
+import { db } from "../state/db.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_DIR = resolve(__dirname, "../agents");
+const CHAIN_EVENTS_PATH = join(".fb", "chain_events.jsonl");
+const STEP_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes per step
+const ARTIFACT_MIN_BYTES = 100;
+const PREV_ARTIFACT_MAX_CHARS = 4096;
+
+interface ChainStep {
+  phase: string;
+  specialist: string;
+  artifactFile: string; // relative to artifactDir
+  tools: string[];
+}
+
+export const CHAIN_STEPS: ChainStep[] = [
+  {
+    phase: "requirements",
+    specialist: "frappe-ba",
+    artifactFile: "planning-artifacts/requirements.md",
+    tools: ["Read", "Write", "get_frappe_docs"],
+  },
+  {
+    phase: "architecture",
+    specialist: "frappe-architect",
+    artifactFile: "planning-artifacts/architecture.md",
+    tools: ["Read", "Write", "get_frappe_docs"],
+  },
+  {
+    phase: "planning",
+    specialist: "frappe-planner",
+    artifactFile: "planning-artifacts/plan.md",
+    tools: ["Read", "Write", "create_component"],
+  },
+  {
+    phase: "implementation",
+    specialist: "frappe-dev",
+    artifactFile: "implementation-artifacts/sprint-status.yaml",
+    tools: ["Read", "Write", "Edit", "Bash", "create_component", "complete_component", "bench_execute"],
+  },
+  {
+    phase: "testing",
+    specialist: "frappe-qa",
+    artifactFile: "implementation-artifacts/test-report.md",
+    tools: ["Read", "Write", "Bash", "bench_execute"],
+  },
+  {
+    phase: "documentation",
+    specialist: "frappe-docs",
+    artifactFile: "implementation-artifacts/docs.md",
+    tools: ["Read", "Write"],
+  },
+];
+
+const PHASE_TASKS: Record<string, string> = {
+  requirements:
+    "Analyse the feature description and produce requirements.md covering DocTypes, roles, process flows, and acceptance criteria.",
+  architecture:
+    "Design the Frappe-native technical solution based on the requirements above. Produce architecture.md covering DocType schemas, relationships, server logic, and permissions.",
+  planning:
+    "Break the architecture into ordered implementation components. Produce plan.md, then call create_component for every component listed.",
+  implementation:
+    "Implement every component from the plan in order. Call complete_component after each one passes tests.",
+  testing:
+    "Run the full test suite, verify all acceptance criteria, check the permission matrix, and produce test-report.md with Result: PASS.",
+  documentation:
+    "Document the implemented feature — DocType fields, hooks, docstrings, and changelog entry — and produce docs.md.",
+};
+
+function appendChainEvent(entry: Record<string, unknown>): void {
+  try {
+    mkdirSync(".fb", { recursive: true });
+    appendFileSync(CHAIN_EVENTS_PATH, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n", "utf-8");
+  } catch { /* non-fatal */ }
+}
+
+function readArtifact(artifactDir: string, artifactFile: string): string | null {
+  try {
+    const content = readFileSync(join(artifactDir, artifactFile), "utf-8");
+    return content.slice(0, PREV_ARTIFACT_MAX_CHARS);
+  } catch {
+    return null;
+  }
+}
+
+function verifyArtifact(artifactDir: string, artifactFile: string): boolean {
+  try {
+    const content = readFileSync(join(artifactDir, artifactFile), "utf-8");
+    return content.length >= ARTIFACT_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}
+
+function buildTaskPrompt(
+  step: ChainStep,
+  featureId: string,
+  featureName: string,
+  artifactDir: string,
+  prevArtifact: string | null,
+): string {
+  const prevSection = prevArtifact
+    ? `## Previous Phase Output\n\`\`\`\n${prevArtifact}\n\`\`\`\n\n`
+    : "";
+
+  return [
+    `Feature: "${featureName}" (ID: ${featureId})`,
+    `Artifact directory: ${artifactDir}`,
+    "",
+    prevSection,
+    `## Your Task`,
+    PHASE_TASKS[step.phase],
+    "",
+    `Write your output to: ${join(artifactDir, step.artifactFile)}`,
+    `Do not stop until the artifact file exists with substantive content.`,
+  ].join("\n");
+}
+
+function runSubprocess(
+  step: ChainStep,
+  taskPrompt: string,
+): Promise<{ exitCode: number; stderr: string }> {
+  return new Promise((resolvePromise) => {
+    const agentFile = join(AGENTS_DIR, `${step.specialist}.md`);
+    let systemPrompt = "";
+    try {
+      systemPrompt = readFileSync(agentFile, "utf-8");
+    } catch {
+      systemPrompt = `You are ${step.specialist}, a Frappe specialist. ${PHASE_TASKS[step.phase]}`;
+    }
+
+    const args = [
+      "--mode", "json",
+      "-p",
+      "--no-extensions",
+      "--tools", step.tools.join(","),
+      "--append-system-prompt", systemPrompt,
+      taskPrompt,
+    ];
+
+    const proc = spawn("pi", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env },
+    });
+
+    const stderrChunks: string[] = [];
+    proc.stderr?.setEncoding("utf-8");
+    proc.stderr?.on("data", (chunk: string) => stderrChunks.push(chunk));
+
+    // Hard timeout per step
+    const timer = setTimeout(() => proc.kill("SIGTERM"), STEP_TIMEOUT_MS);
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      resolvePromise({
+        exitCode: code ?? 1,
+        stderr: stderrChunks.slice(-20).join("").slice(-2000),
+      });
+    });
+  });
+}
+
+function updateDb(featureId: string, phase: string, chainStep: string | null): void {
+  try {
+    db.transaction(() => {
+      db.prepare("UPDATE sessions SET chain_step = ? WHERE is_active = 1").run(chainStep);
+      db.prepare("UPDATE features SET current_phase = ? WHERE feature_id = ?").run(phase, featureId);
+    })();
+  } catch { /* non-fatal — chain continues */ }
+}
+
+/**
+ * Runs the full agent chain for a feature. Fire-and-forget: called via setImmediate from startFeature.
+ * Each phase spawns an isolated pi subprocess with a specialist system prompt.
+ * Artifacts are passed between phases via files in artifactDir.
+ */
+export async function spawnChain(
+  featureId: string,
+  featureName: string,
+  artifactDir: string,
+): Promise<void> {
+  appendChainEvent({ featureId, featureName, status: "chain_started" });
+
+  let prevArtifact: string | null = null;
+
+  for (const step of CHAIN_STEPS) {
+    // Update state: chain is now on this phase
+    updateDb(featureId, step.phase, step.phase);
+    appendChainEvent({ featureId, phase: step.phase, status: "started" });
+
+    // Ensure artifact subdirs exist
+    const planningDir = join(artifactDir, "planning-artifacts");
+    const implDir = join(artifactDir, "implementation-artifacts");
+    mkdirSync(planningDir, { recursive: true });
+    mkdirSync(implDir, { recursive: true });
+
+    const taskPrompt = buildTaskPrompt(step, featureId, featureName, artifactDir, prevArtifact);
+
+    // Run subprocess — retry once if artifact missing despite exit 0
+    let result = await runSubprocess(step, taskPrompt);
+    const artifactOk = verifyArtifact(artifactDir, step.artifactFile);
+
+    if (result.exitCode === 0 && !artifactOk) {
+      // Retry with explicit nudge
+      const retryPrompt = taskPrompt +
+        `\n\nWARNING: Your artifact was not detected at ${join(artifactDir, step.artifactFile)}. ` +
+        `You MUST write this file before exiting.`;
+      result = await runSubprocess(step, retryPrompt);
+    }
+
+    if (result.exitCode !== 0 || !verifyArtifact(artifactDir, step.artifactFile)) {
+      // Chain failed — write error file and update state
+      const errorContent = [
+        `# Chain Error`,
+        `Phase: ${step.phase}`,
+        `Exit code: ${result.exitCode}`,
+        `Artifact expected: ${join(artifactDir, step.artifactFile)}`,
+        `Artifact found: ${verifyArtifact(artifactDir, step.artifactFile)}`,
+        ``,
+        `## Stderr (last 2000 chars)`,
+        result.stderr,
+      ].join("\n");
+
+      try {
+        writeFileSync(join(artifactDir, "chain_error.md"), errorContent, "utf-8");
+      } catch { /* non-fatal */ }
+
+      updateDb(featureId, "chain_failed", null);
+      appendChainEvent({ featureId, phase: step.phase, status: "failed", exitCode: result.exitCode });
+      return;
+    }
+
+    appendChainEvent({ featureId, phase: step.phase, status: "complete" });
+
+    // Pass this phase's artifact to the next phase
+    prevArtifact = readArtifact(artifactDir, step.artifactFile);
+  }
+
+  // All steps complete
+  updateDb(featureId, "done", null);
+  appendChainEvent({ featureId, status: "chain_complete" });
+}

package/extensions/frappe-session.ts

@@ -290,6 +290,11 @@ export async function handleSessionStart(): Promise<string> {
 
     // Specialist auto-load on session resume (Story 3.4)
     // AGENTS.md base identity (Nexus) is loaded natively by pi from project root.
+    if (ctx.phase === "chain_running") {
+      // Agent chain is running as a background subprocess — no specialist injection.
+      // Use get_project_status to monitor chain progress.
+      return `${stateBlock}\n\nAgent chain is running. Use get_project_status to monitor progress.`;
+    }
     if (ctx.phase !== "idle") {
       try {
         const specCtx = buildStateContext(null, "session_start");

package/extensions/frappe-state.ts

@@ -8,6 +8,28 @@ import { loadCredentials } from "../config/loader.js";
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default function (pi: any) {
   pi.on("after_tool_call", handleAfterToolCall);
+
+  // Session-end guard: warn the agent about untracked features before shutdown.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("session_shutdown", (_event: any, ctx: any) => {
+    try {
+      const orphans = db
+        .prepare(
+          `SELECT feature_id, name, mode FROM features
+           WHERE current_phase != 'idle' AND progress_total = 0`
+        )
+        .all() as Array<{ feature_id: string; name: string; mode: string }>;
+
+      if (orphans.length > 0) {
+        const list = orphans.map((f) => `  • ${f.name} [${f.feature_id}] (${f.mode})`).join("\n");
+        const warning = `\n⚠ Session ending with ${orphans.length} feature(s) that have no components tracked:\n${list}\n\nCall create_component() + complete_component() before the next session to preserve work history.`;
+        try {
+          ctx.ui.setStatus("frappe-builder", `⚠ ${orphans.length} untracked feature(s) — run create_component`);
+        } catch { /* non-fatal */ }
+        console.error(warning);
+      }
+    } catch { /* non-fatal — never block shutdown */ }
+  });
 }
 
 /** Reads current_phase and feature_id from the active session. */
@@ -64,14 +86,16 @@ function isSpawnAgentResult(value: unknown): value is { status: string; skill: s
 }
 
 /** Type guard for the return value of startFeature(). */
-function isStartFeatureResult(value: unknown): value is { mode: string; feature_id: string } {
+function isStartFeatureResult(value: unknown): value is { mode: string; feature_id: string; current_phase: string } {
   return (
     typeof value === "object" &&
     value !== null &&
     "mode" in value &&
     "feature_id" in value &&
+    "current_phase" in value &&
     typeof (value as Record<string, unknown>).mode === "string" &&
-    typeof (value as Record<string, unknown>).feature_id === "string"
+    typeof (value as Record<string, unknown>).feature_id === "string" &&
+    typeof (value as Record<string, unknown>).current_phase === "string"
   );
 }
 
@@ -154,13 +178,21 @@ export async function handleAfterToolCall(
           // non-JSON result — skip phase transition silently
         }
         if (isStartFeatureResult(parsed)) {
-          const newPhase = parsed.mode === "quick" ? "implementation" : "requirements";
-          applyPhaseTransition(parsed.feature_id, newPhase);
+          // Full mode: chain running as background subprocess — inject status banner
+          if (parsed.current_phase === "chain_running") {
+            const banner: TextContent = {
+              type: "text",
+              text: `\n\nAgent chain started for "${parsed.feature_id}" (full mode).\n` +
+                    `Each phase runs as an isolated subprocess. Monitor progress with get_project_status.\n` +
+                    `The chain will advance through: requirements → architecture → planning → implementation → testing → documentation.`,
+            };
+            return { content: [...context.result.content, banner] };
+          }
 
-          // Specialist auto-load after phase transition (Story 3.4) — non-fatal
+          // Quick mode: specialist auto-load after phase transition (Story 3.4) — non-fatal
           try {
             const specCtx = buildStateContext(parsed.feature_id, toolName);
-            const specialistBlock = loadSpecialist(newPhase, specCtx);
+            const specialistBlock = loadSpecialist(parsed.current_phase, specCtx);
             if (specialistBlock) {
               const specialistContent: TextContent = {
                 type: "text",
@@ -170,7 +202,6 @@ export async function handleAfterToolCall(
             }
           } catch (specialistErr) {
             console.error(`[frappe-state] specialist load failed: ${specialistErr}`);
-            // non-fatal — session continues without specialist block
           }
         }
       }

package/extensions/frappe-ui.ts

@@ -1,59 +1,126 @@
 import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
 import { db, getCurrentPhase } from "../state/db.js";
+import { loadConfig } from "../config/loader.js";
+import { DEFAULT_PERMISSION_MODE } from "../config/defaults.js";
 
-interface FooterState {
+interface DashboardState {
   projectId: string | null;
   featureName: string | null;
+  featureMode: string | null;
   componentId: string | null;
+  phase: string;
+  chainStep: string | null;
+  progressDone: number;
+  progressTotal: number;
+  permissionMode: string;
 }
 
-function readFooterState(): FooterState {
+// Keep FooterState alias so existing tests compile without changes.
+type FooterState = Pick<DashboardState, "projectId" | "featureName" | "componentId">;
+
+function readDashboardState(): DashboardState {
   try {
     const session = db
       .prepare(
-        `SELECT s.project_id, f.name AS feature_name, s.component_id
+        `SELECT s.project_id, s.current_phase, s.component_id, s.chain_step,
+                f.name AS feature_name, f.mode AS feature_mode,
+                f.progress_done, f.progress_total
          FROM sessions s
          LEFT JOIN features f ON f.feature_id = s.feature_id
          WHERE s.is_active = 1 LIMIT 1`
       )
       .get() as
-      | { project_id: string | null; feature_name: string | null; component_id: string | null }
+      | {
+          project_id: string | null;
+          current_phase: string;
+          component_id: string | null;
+          chain_step: string | null;
+          feature_name: string | null;
+          feature_mode: string | null;
+          progress_done: number | null;
+          progress_total: number | null;
+        }
       | undefined;
 
+    const permissionMode = (() => {
+      try { return loadConfig().permissionMode ?? DEFAULT_PERMISSION_MODE; } catch { return DEFAULT_PERMISSION_MODE; }
+    })();
+
     return {
       projectId: session?.project_id ?? null,
       featureName: session?.feature_name ?? null,
+      featureMode: session?.feature_mode ?? null,
       componentId: session?.component_id ?? null,
+      phase: session?.current_phase ?? "idle",
+      chainStep: session?.chain_step ?? null,
+      progressDone: session?.progress_done ?? 0,
+      progressTotal: session?.progress_total ?? 0,
+      permissionMode,
     };
   } catch {
-    return { projectId: null, featureName: null, componentId: null };
+    return { projectId: null, featureName: null, featureMode: null, componentId: null, phase: "idle", chainStep: null, progressDone: 0, progressTotal: 0, permissionMode: DEFAULT_PERMISSION_MODE };
   }
 }
 
 /**
- * Pure formatting function — no I/O, no side effects.
+ * Formats dashboard state as a string[] for ctx.ui.setWidget().
  * Exported for unit testing.
  */
-export function formatFooter(state: FooterState): string {
+export function formatDashboard(state: DashboardState): string[] {
   if (!state.projectId) {
-    return `No active project`;
+    return ["frappe-builder  |  No active project"];
   }
-  if (!state.featureName) {
-    return `Project: ${state.projectId} | No active feature`;
+
+  const parts: string[] = [`Project: ${state.projectId}`];
+
+  if (state.featureName) {
+    const modeTag = state.featureMode ? ` [${state.featureMode}]` : "";
+    parts.push(`Feature: ${state.featureName}${modeTag}`);
+  } else {
+    parts.push("No active feature");
   }
-  if (!state.componentId) {
-    return `Project: ${state.projectId} | Feature: ${state.featureName}`;
+
+  if (state.componentId) {
+    parts.push(`Component: ${state.componentId}`);
   }
+
+  if (state.phase === "chain_running") {
+    parts.push(`Phase: chain:${state.chainStep ?? "starting"}`);
+  } else {
+    parts.push(`Phase: ${state.phase}`);
+  }
+
+  if (state.progressTotal > 0) {
+    parts.push(`${state.progressDone}/${state.progressTotal} components`);
+  }
+
+  parts.push(`Mode: ${state.permissionMode}`);
+
+  return [`frappe-builder  |  ${parts.join("  |  ")}`];
+}
+
+/**
+ * Legacy single-line footer format — kept for backward-compat with existing tests.
+ * Exported for unit testing.
+ */
+export function formatFooter(state: FooterState): string {
+  if (!state.projectId) return "No active project";
+  if (!state.featureName) return `Project: ${state.projectId} | No active feature`;
+  if (!state.componentId) return `Project: ${state.projectId} | Feature: ${state.featureName}`;
   return `Project: ${state.projectId} | Feature: ${state.featureName} | Component: ${state.componentId}`;
 }
 
-function renderFooter(): void {
+function renderWidget(ctx: unknown): void {
   try {
-    const state = readFooterState();
-    const line = formatFooter(state);
-    process.stderr.write(`\r\x1b[2K[frappe-builder] ${line}\n`);
+    const lines = formatDashboard(readDashboardState());
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (ctx as any).ui.setWidget("frappe-builder", lines, { placement: "aboveEditor" });
   } catch {
-    // Silently swallow all rendering errors — footer is non-critical
+    // Fallback: write to stderr if widget API unavailable
+    try {
+      const state = readDashboardState();
+      process.stderr.write(`\r\x1b[2K[frappe-builder] ${formatDashboard(state).join(" ")}\n`);
+    } catch { /* non-critical */ }
   }
 }
 
@@ -85,7 +152,6 @@ export async function handleAfterToolCall(
   _context: AfterToolCallContext,
   _signal?: AbortSignal
 ): Promise<AfterToolCallResult | undefined> {
-  renderFooter();
   return undefined;
 }
 
@@ -93,33 +159,26 @@ export async function handleAfterToolCall(
 export default function (pi: any) {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   pi.on("session_start", (_event: any, ctx: any) => {
-    try {
-      ctx.ui.setStatus("frappe-builder", formatFooter(readFooterState()));
-    } catch {
-      renderFooter();
-    }
+    renderWidget(ctx);
   });
 
   // Announcement hook — fires before FSM guard in frappe-workflow.ts (FR25)
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   pi.on("tool_call", (event: any, ctx: any) => {
     try {
-      const phase = getCurrentPhase();
-      ctx.ui.setStatus("frappe-builder", `→ Calling ${event.toolName ?? ""} [${phase}]`);
+      const state = readDashboardState();
+      const lines = formatDashboard(state);
+      const callLine = `→ ${event.toolName ?? "tool"} [${state.phase}]`;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (ctx as any).ui.setWidget("frappe-builder", [...lines, callLine], { placement: "aboveEditor" });
     } catch {
       handleBeforeToolCall(event.toolName ?? "");
     }
   });
 
-  // "tool_result" is the pi-coding-agent ExtensionAPI event name for after-tool hooks.
-  // Using ctx.ui.setStatus() injects into pi's native footer row instead of writing
-  // raw bytes to stderr (which pi's TUI redraws over).
+  // "tool_result" fires after each tool completes — update the persistent widget.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   pi.on("tool_result", (_event: any, ctx: any) => {
-    try {
-      ctx.ui.setStatus("frappe-builder", formatFooter(readFooterState()));
-    } catch {
-      renderFooter();
-    }
+    renderWidget(ctx);
   });
 }

package/extensions/frappe-workflow.ts

@@ -1,6 +1,22 @@
 import { getCurrentPhase, db } from "../state/db.js";
 import { isToolAllowedInPhase, getValidPhase, type Phase } from "../state/fsm.js";
 import { appendEntry } from "../state/journal.js";
+import { loadConfig } from "../config/loader.js";
+import { type PermissionMode, DEFAULT_PERMISSION_MODE } from "../config/defaults.js";
+
+// Re-export for use in tests and other modules
+export type { PermissionMode };
+
+/**
+ * Tools that mutate files, run shell commands, or write state.
+ * These are subject to default-mode confirmation and plan-mode blocking.
+ */
+export const WRITE_TOOLS = new Set([
+  "Write", "Edit", "NotebookEdit",
+  "Bash",
+  "scaffold_doctype", "bench_execute",
+  "create_component", "complete_component",
+]);
 
 interface BlockedResponse {
   blocked: true;
@@ -35,7 +51,7 @@ function buildBlockedResponse(
  * Never throws — always returns a value or undefined.
  */
 // Tools valid in all phases — never blocked by the phase guard (FR34)
-const ALWAYS_ALLOWED_TOOLS = ["invoke_debugger", "end_debug", "spawn_agent", "get_frappe_docs", "get_audit_log"];
+const ALWAYS_ALLOWED_TOOLS = ["invoke_debugger", "end_debug", "spawn_agent", "get_frappe_docs", "get_audit_log", "get_project_status"];
 
 export function beforeToolCall(
   toolName: string,
@@ -74,13 +90,75 @@ export function beforeToolCall(
   return undefined; // allow
 }
 
+/**
+ * Checks the active permission mode for write tools.
+ * - auto: always allowed
+ * - plan: always blocked with dry-run message
+ * - default: prompts via ctx.ui.input(); falls through if unavailable
+ *
+ * Returns a blocked response to halt execution, or undefined to allow.
+ * Never throws.
+ */
+export async function checkPermissionMode(
+  toolName: string,
+  mode: PermissionMode,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ctx?: any,
+): Promise<BlockedResponse | undefined> {
+  if (!WRITE_TOOLS.has(toolName)) return undefined;
+  if (mode === "auto") return undefined;
+
+  if (mode === "plan") {
+    return {
+      blocked: true,
+      tool: toolName,
+      current_phase: getCurrentPhase() as Phase,
+      valid_phase: "any",
+      message: `[plan mode] ${toolName} is a write operation — dry-run only. Switch to default or auto mode to execute.`,
+    };
+  }
+
+  // default mode: prompt via ctx.ui.input()
+  if (ctx) {
+    try {
+      const answer: string = await ctx.ui.input(`Allow ${toolName}? (yes/no)`);
+      if (!["yes", "y"].includes(answer?.toLowerCase?.() ?? "")) {
+        return {
+          blocked: true,
+          tool: toolName,
+          current_phase: getCurrentPhase() as Phase,
+          valid_phase: "any",
+          message: `${toolName} blocked by user.`,
+        };
+      }
+    } catch {
+      // ctx.ui.input unavailable — fail open (allow)
+    }
+  }
+
+  return undefined;
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default function (pi: any) {
-  pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }) => {
-    const result = beforeToolCall(event.toolName ?? "", event.input ?? {});
-    if (result) {
-      return { block: true, reason: result.message };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("tool_call", async (event: { toolName?: string; input?: Record<string, unknown> }, ctx: any) => {
+    const toolName = event.toolName ?? "";
+
+    // Phase guard
+    const phaseResult = beforeToolCall(toolName, event.input ?? {});
+    if (phaseResult) {
+      return { block: true, reason: phaseResult.message };
     }
+
+    // Permission mode guard (Story 9.2–9.4)
+    const config = loadConfig();
+    const mode: PermissionMode = config.permissionMode ?? DEFAULT_PERMISSION_MODE;
+    const permResult = await checkPermissionMode(toolName, mode, ctx);
+    if (permResult) {
+      return { block: true, reason: permResult.message };
+    }
+
     return undefined;
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-builder",
-  "version": "1.1.0-dev.13",
+  "version": "1.1.0-dev.17",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
   "bin": {