avtc-pi-featyard 1.1.0

package/src/events/event-deps.ts

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * EventDeps — the bag of domain singletons passed to event routers.
+ *
+ * Holds the already-constructed domain objects that the event routers in events/
+ * delegate to: the handler as single source of truth, and the guardrails,
+ * compaction, session-lifecycle, agent-lifecycle, and kanban turn-handler
+ * domain objects. The cross-cutting helpers (expandSkillCommand,
+ * applyModelOverrideForPhase, getAutoAgentCallback, etc.) are consumed by the
+ * domain-object constructors in index.ts, not by the routers, so they are not
+ * part of this bag.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { KanbanTurnHandlers } from "../kanban/kanban-turn-handlers.js";
+import type { IAgentLifecycle, ICompaction, IGuardrails, ISessionLifecycle } from "../shared/workflow-types.js";
+import type { FeatureSession } from "../state/feature-session.js";
+
+/** Constructed domain singletons consumed by the event routers. */
+export interface EventDeps {
+  pi: ExtensionAPI;
+  handler: FeatureSession;
+  guardrails: IGuardrails;
+  compaction: ICompaction;
+  /** Session-lifecycle domain object (session_start/session_tree bodies). */
+  lifecycle: ISessionLifecycle;
+  /** Agent-lifecycle domain object (agent_start/agent_end bodies). */
+  agentLifecycle: IAgentLifecycle;
+  /** Kanban turn-handler domain object (turn_start/turn_end bodies). */
+  kanbanTurn: KanbanTurnHandlers;
+}

package/src/events/index.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * events/index.ts — the single manifest for all pi.on event registration.
+ *
+ * Consolidates the reactive pi.on handlers behind one entry point
+ * (registerAllEvents), replacing the register calls that were inline in src/index.ts.
+ * Registration order is preserved (handlers fire in registration order).
+ *
+ * The three homes for featyard entry points:
+ *   tools/  = native tool registrations (the agent calls these — pull model)
+ *   events/ = reactive pi.on handlers (pi emits these — push model) ← THIS FOLDER
+ *   domain/ = the actual logic (state, gating, phases, kanban, ...)
+ *
+ * All pi.on handlers are now registered via this manifest EXCEPT a small number
+ * of deliberate domain co-handlers that register their own pi.on because the
+ * event IS their domain concern (not featyard core routing):
+ *   - worktrees/worktree-interception.ts: tool_call (path-rewrite) + before_agent_start (CWD)
+ *   - kanban/kanban-events.ts: tool_result (auto-agent heartbeat)
+ * These are called from events/index.ts (registerWorktreeInterception) or from
+ * kanbanExtension (registerKanbanEvents) and are documented here as the
+ * deliberate exceptions to single-manifest registration.
+ */
+
+import { registerWorktreeInterception } from "../git/worktrees/worktree-interception.js";
+import { registerAgentEnd } from "./agent/agent-end.js";
+import { registerAgentSettled } from "./agent/agent-settled.js";
+import { registerAgentStart } from "./agent/agent-start.js";
+import { registerTurnEnd } from "./agent/turn-end.js";
+import { registerTurnStart } from "./agent/turn-start.js";
+import type { EventDeps } from "./event-deps.js";
+import { registerInput } from "./input/input.js";
+import { registerContext } from "./session/context.js";
+import { registerModelSelect } from "./session/model-select.js";
+import { registerSessionCompact } from "./session/session-compact.js";
+import { registerSessionShutdown } from "./session/session-shutdown.js";
+import { registerSessionStart } from "./session/session-start.js";
+import { registerSessionTree } from "./session/session-tree.js";
+import { registerToolCall } from "./tool/tool-call.js";
+import { registerToolResult } from "./tool/tool-result.js";
+
+/**
+ * Register all featyard pi.on event handlers. Called once from the composition root
+ * (src/index.ts) after the domain singletons are constructed. Handlers fire in
+ * registration order.
+ */
+export function registerAllEvents(deps: EventDeps): void {
+  const { pi, handler, guardrails, compaction, lifecycle, agentLifecycle, kanbanTurn } = deps;
+
+  // input → skill detection + phase movement + activation (events/input/input.ts)
+  registerInput(pi, handler);
+
+  // tool_call (worktree path-rewrite) + before_agent_start (CWD rewrite) — worktrees/
+  registerWorktreeInterception(pi, { handler });
+
+  // tool_call (per-tool gating) + tool_result (warnings/recording) — events/tool/
+  registerToolCall(pi, guardrails, handler);
+  registerToolResult(pi, guardrails, handler);
+
+  // context → {{PI_FY_*}} substitution in <skill> blocks — events/session/
+  registerContext(pi);
+
+  // model_select → capture active model for kanban title/topic generation — events/session/
+  registerModelSelect(pi);
+
+  // session_start (kanban branch + state feature bind/resume/reset) — events/session/
+  registerSessionStart(pi, lifecycle);
+
+  // session_tree (restore workflow from session branch) — events/session/
+  registerSessionTree(pi, lifecycle);
+
+  // session_compact (deliver stored compaction follow-up) — events/session/
+  registerSessionCompact(pi, compaction);
+
+  // session_shutdown (clear pending follow-up + stop archive timer) — events/session/
+  registerSessionShutdown(pi, compaction);
+
+  // fy:reset command + globalThis workflow-monitor bridge are wired separately from
+  // index.ts (registerSessionLifecycleCommands + wireSessionLifecycleBridge); the
+  // session_start/session_tree pi.on registrations live here.
+
+  // agent_start (reset tracking + re-arm finish guardrail) + agent_end (clear + finish-done + notify) + agent_settled (deferred phase-transition followUp drain) — events/agent/
+  registerAgentStart(pi, agentLifecycle);
+  registerAgentEnd(pi, agentLifecycle);
+  registerAgentSettled(pi, agentLifecycle);
+
+  // turn_start (grace pause + auto-agent unblock) + turn_end (model capture + grace resume) — events/agent/
+  registerTurnStart(pi, kanbanTurn);
+  registerTurnEnd(pi, kanbanTurn);
+}

package/src/events/input/input.ts

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * input event router — detect featyard skill invocations and route them to
+ * the right domain action: feature activation, phase pointer advance, or review
+ * loop counter increment.
+ *
+ * Explicit skill invocation is respected: jumping forward sets the phase pointer
+ * (jumped phases fold to done via derivation). Recovery from an unintended jump
+ * is via fy-reset or invoking another skill. Injected followUp messages
+ * (event.source === "extension") are skipped so they don't re-trigger tracking.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { log } from "../../log.js";
+import { syncEnvVarsFromState } from "../../phases/env-sync.js";
+import type { Phase } from "../../phases/phase-progression.js";
+import { parseSkillName } from "../../phases/phase-progression.js";
+import { applyModelOverride } from "../../phases/phase-transitions.js";
+import { expandSkillCommand } from "../../prompts/skill-block-builder.js";
+import { startReviewIteration } from "../../review/review-counter.js";
+import {
+  NO_AGENT_NAME,
+  NO_FEATURE_STATE_OVERRIDE,
+  resolveLoopIndex,
+  substituteTemplates,
+} from "../../shared/workflow-refs.js";
+import { activateFromDesignSkill, activateFromPlanSkill } from "../../state/feature-activation.js";
+import type { FeatureSession } from "../../state/feature-session.js";
+import { featureSlugFromDesignDoc, featureSlugFromPlanDoc } from "../../state/feature-state.js";
+import { persistState } from "../../state/state-persistence.js";
+import { NO_FEATURE_STATE, updateWidget } from "../../ui/featyard-widget.js";
+
+export function registerInput(pi: ExtensionAPI, handler: FeatureSession): void {
+  pi.on("input", async (event, ctx: ExtensionContext) => {
+    if (event.source === "extension") return;
+    const text = event.text;
+
+    /** Helper: track input text, persist, and apply model override if phase advanced */
+    async function processInputText(): Promise<boolean> {
+      const changed = handler.processSkillInput(text);
+      if (changed) {
+        persistState(pi, handler);
+        updateWidget(handler, NO_FEATURE_STATE);
+        // Phase advanced — apply model override
+        const phaseAfter = handler.getWorkflowState()?.currentPhase;
+        if (phaseAfter) {
+          await applyModelOverride(pi, ctx, phaseAfter, resolveLoopIndex(phaseAfter));
+        }
+      }
+      return changed;
+    }
+
+    /**
+     * Finalize this input: apply tracking side-effects, then take over expansion of
+     * our own skills. pi's _expandSkillCommand would otherwise wrap our skills with a
+     * generic "References are relative to <skillDir>" line — misleading for our skills,
+     * which reference project-root paths (docs/, .featyard/), never skill-relative ones.
+     * Transforming to the already-expanded <skill> block (with {{PI_FY_*}} placeholders
+     * substituted) makes pi's _expandSkillCommand and expandPromptTemplate no-ops
+     * (the text no longer starts with "/"), so pi processes our block unchanged.
+     * Unknown/non-skills return undefined so pi processes them normally.
+     */
+    async function proceed(): Promise<{ action: "transform"; text: string } | undefined> {
+      await processInputText();
+      const expanded = expandSkillCommand(
+        text,
+        (t) => substituteTemplates(t, NO_FEATURE_STATE_OVERRIDE, NO_AGENT_NAME).text,
+      );
+      if (expanded !== text) {
+        return { action: "transform", text: expanded };
+      }
+      // Not one of our skills — let pi process normally
+    }
+
+    // Track last skill invoked from input text
+    const invokedSkill = parseSkillName(text);
+    if (invokedSkill) {
+      log.info(`[workflow] input: tracked skill from input text: ${invokedSkill}`);
+    }
+
+    // Update executionMode when user invokes fy-implement
+    if (invokedSkill === "fy-implement") {
+      if (!handler.getActiveFeatureSlug()) {
+        const planSlug = featureSlugFromPlanDoc(text);
+        if (planSlug) {
+          const pathMatch = text.match(/(\S+-task-plan\.md)/);
+          const planPath = pathMatch?.[1] ?? "";
+          activateFromPlanSkill(ctx, handler, planSlug, planPath);
+          log.info(`Created/loaded feature state for ${planSlug} from skill invocation`);
+          persistState(pi, handler);
+          updateWidget(handler, NO_FEATURE_STATE);
+        }
+      }
+    }
+
+    // fy-plan / fy-design invoked with a design-doc path and no active
+    // feature: activate an existing feature, or create+kanban-link one from the
+    // design doc. Mirrors the fy-implement path above (plan-doc source),
+    // generalized to a design-doc slug source. Activating at invocation time (not
+    // just on plan-doc write) ensures skill placeholders resolve and the feature
+    // is visible/usable for phase_ready.
+    if (invokedSkill === "fy-plan" || invokedSkill === "fy-design") {
+      if (!handler.getActiveFeatureSlug()) {
+        const designSlug = featureSlugFromDesignDoc(text);
+        if (designSlug) {
+          const pathMatch = text.match(/(\S+-design\.md)/);
+          const designPath = pathMatch?.[1] ?? "";
+          const targetPhase: Phase = invokedSkill === "fy-plan" ? "plan" : "design";
+          await activateFromDesignSkill(ctx, handler, designSlug, designPath, targetPhase);
+          log.info(`Activated/created feature state for ${designSlug} from ${invokedSkill} skill invocation`);
+          persistState(pi, handler);
+          updateWidget(handler, NO_FEATURE_STATE);
+        }
+      }
+    }
+
+    // Manual review skill invocation — increment the review loop counter so the
+    // substitution pipeline resolves the correct iteration context. This mirrors
+    // the code-driven path (phase_ready) via the shared startReviewIteration helper.
+    // Injected followUp messages are skipped (event.source === "extension"), so this
+    // never double-counts with the phase_ready path.
+    if (invokedSkill === "fy-design-review" || invokedSkill === "fy-plan-review") {
+      const activeSlug = handler.getActiveFeatureSlug();
+      if (activeSlug) {
+        const phase = invokedSkill === "fy-design-review" ? "design" : "plan";
+        // startReviewIteration loads+increments+saves the review counter (side effect).
+        startReviewIteration(handler, activeSlug, phase, NO_FEATURE_STATE_OVERRIDE);
+        syncEnvVarsFromState(handler);
+        updateWidget(handler, NO_FEATURE_STATE);
+        log.info(`[workflow] input: manual ${invokedSkill} invocation incremented review counter for ${activeSlug}`);
+      }
+    }
+
+    // Respect explicit skill invocation: proceed() runs processInputText(), which
+    // calls PhaseProgression.onInputText() — that advances the pointer to the invoked
+    // skill's phase (jumped phases fold to done via derivation) and guards
+    // FRESH_START_BLOCKED when no workflow is active. No blocking dialog — recovery
+    // from an unintended jump is via fy-reset or invoking another skill.
+    return proceed();
+  });
+}

package/src/events/session/context.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * context event router — substitutes {{PI_FY_*}} placeholders inside <skill> XML
+ * blocks in user messages before each LLM call.
+ *
+ * Only substitutes inside <skill>...</skill> blocks — user text outside skill
+ * blocks is left untouched. Scans ALL user messages (not just recent) because
+ * the placeholder persists in the agent's state across turns and transformContext
+ * only mutates a clone.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { NO_AGENT_NAME, NO_FEATURE_STATE_OVERRIDE, substituteTemplates } from "../../shared/workflow-refs.js";
+
+/** Regex that matches <skill ...> ... </skill> blocks (including multi-line content). */
+const SKILL_BLOCK_RE = /(<skill[^>]*>[\s\S]*?<\/skill>)/g;
+
+export function registerContext(pi: ExtensionAPI): void {
+  pi.on("context", async (event, _ctx) => {
+    const messages = event.messages;
+    let modified = false;
+
+    for (let i = 0; i < messages.length; i++) {
+      const msg = messages[i];
+      if (msg.role !== "user") continue;
+
+      // Handle both string content and array content (pi 0.73+ uses arrays)
+      if (typeof msg.content === "string") {
+        if (!msg.content.includes("{{PI_FY_")) continue;
+        const substituted = substituteInSkillBlocks(msg.content);
+        if (substituted !== msg.content) {
+          messages[i] = { ...msg, content: substituted };
+          modified = true;
+        }
+      } else if (Array.isArray(msg.content)) {
+        let partsModified = false;
+        const newParts = msg.content.map((part) => {
+          if (part.type === "text" && part.text.includes("{{PI_FY_")) {
+            const substituted = substituteInSkillBlocks(part.text);
+            if (substituted !== part.text) {
+              partsModified = true;
+              return { ...part, text: substituted };
+            }
+          }
+          return part;
+        });
+        if (partsModified) {
+          messages[i] = { ...msg, content: newParts };
+          modified = true;
+        }
+      }
+    }
+
+    if (modified) {
+      return { messages };
+    }
+    return undefined;
+  });
+}
+
+/** Substitute {{PI_FY_*}} placeholders only within <skill> XML blocks. */
+function substituteInSkillBlocks(text: string): string {
+  return text.replace(SKILL_BLOCK_RE, (block) => {
+    return substituteTemplates(block, NO_FEATURE_STATE_OVERRIDE, NO_AGENT_NAME).text;
+  });
+}

package/src/events/session/model-select.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * model_select event router — capture the active model + registry whenever the
+ * model changes, so kanban title/topic generation can call the LLM later.
+ *
+ * Routes to the shared captureModel helper (kanban/model-capture.ts), writing into
+ * the singleton _kanbanModelRef that title/topic generation reads.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { _kanbanModelRef } from "../../kanban/kanban-bridge.js";
+import { captureModel } from "../../kanban/model-capture.js";
+
+export function registerModelSelect(pi: ExtensionAPI): void {
+  pi.on("model_select", (_event, extensionCtx) => {
+    captureModel(_kanbanModelRef, extensionCtx);
+  });
+}

package/src/events/session/session-compact.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * session_compact event router — deliver the stored compaction follow-up (new-phase
+ * skill / task confirmation / todo details) after the context is compacted, or
+ * delegate to the subagent-compact path. Clears any pending deferred follow-up first
+ * (a newer compaction supersedes a prior one).
+ *
+ * Body lives in the compaction domain object (ICompaction.onSessionCompact).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ICompaction } from "../../shared/workflow-types.js";
+
+export function registerSessionCompact(pi: ExtensionAPI, compaction: ICompaction): void {
+  pi.on("session_compact", async (event) => {
+    await compaction.onSessionCompact(event);
+  });
+}

package/src/events/session/session-shutdown.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * session_shutdown event router — clear session-scoped state on teardown.
+ *
+ * Coordinates two shutdown concerns: clear any pending deferred compaction
+ * follow-up (compaction domain object, so a deferred inject never fires into a
+ * dead session) and stop the featyard artifact archive timer (best-effort).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ICompaction } from "../../shared/workflow-types.js";
+import { clearPostTurnFollowUp } from "../../state/post-turn-dispatch.js";
+
+export function registerSessionShutdown(pi: ExtensionAPI, compaction: ICompaction): void {
+  pi.on("session_shutdown", () => {
+    compaction.onSessionShutdown();
+    clearPostTurnFollowUp();
+    const bridge = globalThis.__piWorkflowMonitor;
+    if (bridge?.archiveTimer) {
+      clearInterval(bridge.archiveTimer);
+      bridge.archiveTimer = undefined;
+    }
+  });
+}

package/src/events/session/session-start.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * session_start event router — coordinates the kanban + state branches of the
+ * session_start reaction (both fire on every session_start; kanban branch first,
+ * then state branch).
+ *
+ * Kanban branch: refresh the stashed command context, capture the active model,
+ * and pause an orphaned auto-agent if an external session replacement (manual
+ * /new, /resume, /fork, /reload) left it pinned to a dead runner.
+ *
+ * State branch: bind/resume/reset the active feature per the session reason
+ * (reload/startup/resume/fork/new + PI_FY_FEATURE binding), via the session-lifecycle
+ * domain object (ISessionLifecycle.onSessionStart).
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { pauseOrphanedAutoAgent } from "../../kanban/auto-agent/auto-agent-pause.js";
+import { _kanbanModelRef } from "../../kanban/kanban-bridge.js";
+import { captureModel } from "../../kanban/model-capture.js";
+import type { ISessionLifecycle } from "../../shared/workflow-types.js";
+
+export function registerSessionStart(pi: ExtensionAPI, lifecycle: ISessionLifecycle): void {
+  pi.on("session_start", async (event, extensionCtx: ExtensionContext) => {
+    // --- kanban branch ---
+    globalThis.__piCtx?.refresh(extensionCtx as unknown as ExtensionCommandContext);
+    captureModel(_kanbanModelRef, extensionCtx);
+
+    // Detect external (non-auto-agent) session replacement that orphans the agent.
+    // new/resume/fork/reload each dispose the prior runner; startup is the initial load
+    // (the agent is never running then). autoAgentInitiatingReplacement marks the
+    // agent's own newSession/switchSession calls so they aren't mistaken for external.
+    const reason = ((event as unknown as Record<string, unknown>).reason as string | undefined) ?? "startup";
+    const isExternalReplacement =
+      (reason === "new" || reason === "resume" || reason === "fork" || reason === "reload") &&
+      globalThis.__piKanban?.autoAgentInitiatingReplacement !== true;
+    if (isExternalReplacement) {
+      pauseOrphanedAutoAgent(() => globalThis.__piWorkflowMonitor?.requestWidgetUpdate?.());
+    }
+
+    // --- state branch ---
+    await lifecycle.onSessionStart(event, extensionCtx);
+  });
+}

package/src/events/session/session-tree.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * session_tree event router — restore workflow state from the session branch
+ * (resume/fork entry), clearing if no state entry is found, via the session-lifecycle
+ * domain object (ISessionLifecycle.onSessionTree).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ISessionLifecycle } from "../../shared/workflow-types.js";
+
+export function registerSessionTree(pi: ExtensionAPI, lifecycle: ISessionLifecycle): void {
+  pi.on("session_tree", async (_event, ctx: ExtensionContext) => {
+    await lifecycle.onSessionTree(ctx);
+  });
+}

package/src/events/tool/tool-call.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * tool_call event router — dispatch each tool to its focused domain method,
+ * then own the shared coordination glue (persist + widget refresh).
+ *
+ * Per-tool gating logic lives in the guardrails domain object (onBashCall,
+ * onWriteEditCall, onPhaseReadyCall, onTaskReadyAdvanceCall), each returning a
+ * ToolCallDecision ({ block?, changed? }). The router owns the toolName
+ * dispatch, applies the block decision, and persists + refreshes the widget
+ * when state changed.
+ *
+ * Note: worktree path-rewriting for write/edit paths is handled by a separate
+ * pi.on("tool_call") handler in worktrees/worktree-interception.ts (worktree-
+ * domain guardrail), which runs alongside this one.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { IGuardrails, ToolCallDecision } from "../../shared/workflow-types.js";
+import type { FeatureSession } from "../../state/feature-session.js";
+import { persistState } from "../../state/state-persistence.js";
+import { NO_FEATURE_STATE, updateWidget } from "../../ui/featyard-widget.js";
+
+const ALLOW: ToolCallDecision = {};
+
+export function registerToolCall(pi: ExtensionAPI, guardrails: IGuardrails, handler: FeatureSession): void {
+  pi.on("tool_call", async (event, ctx) => {
+    let decision: ToolCallDecision = ALLOW;
+
+    switch (event.toolName) {
+      case "bash":
+        decision = await guardrails.onBashCall(event, ctx);
+        break;
+      case "write":
+      case "edit":
+        decision = await guardrails.onWriteEditCall(event, ctx);
+        break;
+      case "phase_ready":
+        decision = guardrails.onPhaseReadyCall(event);
+        break;
+      case "task_ready_advance":
+        decision = guardrails.onTaskReadyAdvanceCall(event);
+        break;
+    }
+
+    if (decision.block) {
+      return { block: true, reason: decision.block };
+    }
+
+    if (decision.changed) {
+      persistState(pi, handler);
+      updateWidget(handler, NO_FEATURE_STATE);
+    }
+
+    return undefined;
+  });
+}

package/src/events/tool/tool-result.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * tool_result event router — dispatch each tool to its focused domain method,
+ * then own the shared coordination glue (persist + widget refresh + warning
+ * injection).
+ *
+ * Per-tool logic lives in the guardrails domain object (onReadResult,
+ * onWriteEditResult, onBashResult), each returning a ToolResultAdvisory
+ * ({ warnings, changed? }). The router owns the toolName dispatch, persists +
+ * refreshes the widget when state changed, and assembles the content
+ * (prepending pending warnings to the tool output).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { IGuardrails, ToolResultAdvisory } from "../../shared/workflow-types.js";
+import type { FeatureSession } from "../../state/feature-session.js";
+import { persistState } from "../../state/state-persistence.js";
+import { NO_FEATURE_STATE, updateWidget } from "../../ui/featyard-widget.js";
+
+const EMPTY_ADVISORY: ToolResultAdvisory = { warnings: [] };
+
+export function registerToolResult(pi: ExtensionAPI, guardrails: IGuardrails, handler: FeatureSession): void {
+  pi.on("tool_result", async (event) => {
+    let advisory: ToolResultAdvisory = EMPTY_ADVISORY;
+
+    switch (event.toolName) {
+      case "read":
+        advisory = guardrails.onReadResult(event);
+        break;
+      case "write":
+      case "edit":
+        advisory = guardrails.onWriteEditResult(event.toolCallId);
+        break;
+      case "bash":
+        advisory = guardrails.onBashResult(event, event.toolCallId);
+        break;
+    }
+
+    if (advisory.changed) {
+      persistState(pi, handler);
+    }
+
+    updateWidget(handler, NO_FEATURE_STATE);
+
+    if (advisory.warnings.length > 0) {
+      return {
+        content: [{ type: "text", text: advisory.warnings.join("\n\n") }, ...event.content],
+      };
+    }
+    return undefined;
+  });
+}