@harms-haus/pi-workflows 1.0.0

package/docs/hook-lifecycle.md

@@ -0,0 +1,380 @@
+# Hook Lifecycle
+
+The pi-workflows extension registers **4 hook functions** on pi framework lifecycle events. Each hook receives the current [`WorkflowState`](#hookstatemutation-and-workflowstate) and the loaded [`WorkflowDefinition`](configuration-reference.md) map, then either mutates state, injects messages, or returns control signals back to the framework.
+
+For the overall extension architecture, see [architecture.md](architecture.md). For state semantics and the `resolveActive` / `isActive` helpers, see [state-management.md](state-management.md).
+
+---
+
+## Registration
+
+All four hooks are wired in [`src/index.ts`](../src/index.ts) via `pi.on()`:
+
+| Framework Event      | Hook Function            | Called When                                      |
+| -------------------- | ------------------------ | ------------------------------------------------ |
+| `session_start`      | `updateStatus`           | Session loaded or created                        |
+| `session_tree`       | `updateStatus`           | Session branch changed                           |
+| `turn_end`           | `updateStatus`           | Agent turn completed                             |
+| `tool_call`          | `handleToolCall`         | Agent requests a tool invocation                 |
+| `before_agent_start` | `handleBeforeAgentStart` | Before the agent begins a new turn               |
+| `agent_end`          | `handleAgentEnd`         | Agent stops (completion, error, or interruption) |
+
+`session_start` and `session_tree` also handle definition loading and state reconstruction before calling `updateStatus`.
+
+---
+
+## updateStatus
+
+```ts
+function updateStatus(
+  ctx: { ui: { setStatus: (key: string, text: string | undefined) => void } },
+  state: WorkflowState | null,
+  definitions: Record<string, WorkflowDefinition>,
+): void;
+```
+
+**Called on:** `session_start`, `session_tree`, `turn_end`
+
+### Logic
+
+1. **Early-return conditions** → calls `ctx.ui.setStatus("workflow", undefined)` to clear the status bar and returns immediately if any of these conditions are met:
+   - `!state` (null state)
+   - `!state.active` (inactive state)
+   - `state.currentPath.length === 0` (empty path)
+   - `!(state.currentPath[0].workflowKey in definitions)` (missing root definition)
+
+2. **Build status parts array** → starts with the top-level workflow name.
+
+3. **Loop through `currentPath` segments** → for each segment, looks up its definition and phase entry:
+   - For `SubworkflowReference` entries: adds `{name} [current/total]` (no emoji)
+   - For `PhaseDefinition` entries: adds `{emoji} {name} [current/total]`
+
+4. **Bounds check** → if any segment's `phaseIndex` is out of bounds (>= phases.length), clears status bar and returns.
+
+5. **Format and set** → joins all parts with `>` and calls `ctx.ui.setStatus("workflow", statusString)`.
+
+### Status Format
+
+All status strings use `>` as the segment separator. Every level in the path — including subworkflow containers — shows its own `[N/M]` progress counter. Emojis appear only on concrete `PhaseDefinition` entries; subworkflow levels (`SubworkflowReference`) show name + progress without an emoji.
+
+**Linear workflow** (`currentPath.length === 1`):
+
+```
+{workflowName} > {phaseEmoji} {phaseName} [{current}/{total}]
+```
+
+Example: `CI/CD Pipeline > 📋 Planning [1/3]`
+
+**Nested workflow** (`currentPath.length === 2`) — shows the subworkflow container with its own progress, then the inner phase:
+
+```
+{workflowName} > {subworkflowName} [{subCurrent}/{subTotal}] > {phaseEmoji} {phaseName} [{current}/{total}]
+```
+
+Example: `Release Pipeline > Code Review [2/3] > 🔍 Static Analysis [1/2]`
+
+**Deep nesting** (`currentPath.length > 2`) — each subworkflow level repeats the `{name} [N/M]` pattern, terminated by the leaf phase with its emoji:
+
+```
+{workflowName} > {sub1} [N/M] > {sub2} [N/M] > {phaseEmoji} {phaseName} [N/M]
+```
+
+Example: `RPIR Development > Implementation [3/5] > Testing [2/2] > 🧪 Unit Tests [1/4]`
+
+Progress numbers are 1-indexed (`phaseIndex + 1`). Each level's total comes from the corresponding workflow definition's `phases.length`.
+
+---
+
+## handleToolCall
+
+```ts
+function handleToolCall(
+  event: ToolCallEvent,
+  state: WorkflowState | null,
+  definitions: Record<string, WorkflowDefinition>,
+): { block: true; reason: string } | void;
+```
+
+**Called on:** `tool_call`
+
+Returns `{ block: true; reason: string }` to block the tool call, or `void` (undefined) to allow it.
+
+### Decision Flow
+
+```
+state is null or inactive → allow (return void)
+  │
+  ▼
+resolveActive fails → allow
+  │
+  ▼
+toolName === "workflow_step" → always allow
+  │
+  ▼
+phase.tools is undefined → allow (no restrictions for this phase)
+  │
+  ▼
+phase.tools.blacklist is set AND toolName is in blockedTools → BLOCK
+  │
+  ▼
+phase.tools.whitelist is set AND toolName is NOT in whitelist → BLOCK
+  │
+  ▼
+otherwise → allow
+```
+
+Key behaviors:
+
+- **`workflow_step` is always allowed** regardless of blacklist/whitelist. This ensures the agent can always advance phases.
+- If a phase has no `tools` property, all tools are permitted.
+- Exactly one of `blacklist` or `whitelist` may be set per phase (mutually exclusive).
+
+### Block Reason Template
+
+When a tool is blocked, the reason string is generated from the definition's `blockReasonTemplate` (or the built-in default). Available template variables:
+
+| Variable         | Description                            |
+| ---------------- | -------------------------------------- |
+| `{workflowName}` | Human-readable workflow name           |
+| `{phaseName}`    | Current phase name                     |
+| `{toolName}`     | The tool that was blocked              |
+| `{allowedTools}` | Human-readable list of permitted tools |
+
+**Default template:**
+
+```
+[workflow] The tool "{toolName}" is blocked during the {phaseName} phase.
+Refer to the current phase instructions for allowed tools and approaches.
+When finished, call workflow_step to advance to the next phase.
+```
+
+When the block comes from a blacklist, `{allowedTools}` resolves to `"all except: "` + the joined blacklist. When from a whitelist, it resolves to the joined whitelist.
+
+---
+
+## handleBeforeAgentStart
+
+```ts
+function handleBeforeAgentStart(
+  state: WorkflowState | null,
+  definitions: Record<string, WorkflowDefinition>,
+): { message: { customType: string; content: string; display: boolean } } | void;
+```
+
+**Called on:** `before_agent_start`
+
+### Logic
+
+1. If state is inactive or null, or `resolveActive` fails → return `void` (no injection).
+2. Otherwise, calls [`buildContextPrompt(active)`](#buildcontextprompt-details) to generate the full context string.
+3. Returns a hidden message with `customType: "workflow:context"` and `display: false`.
+
+The returned message is injected into the conversation before the agent begins its turn. Because `display: false`, the user does not see it, but the agent reads it as context.
+
+### buildContextPrompt Details
+
+The prompt is assembled from these sections in order:
+
+| Section                | Source                                           | Notes                                           |
+| ---------------------- | ------------------------------------------------ | ----------------------------------------------- |
+| **Header line**        | `[Workflow path: {breadcrumb} ▸ {emoji} {name}]` | Breadcrumb from `active.breadcrumb`             |
+| **Role instruction**   | `definition.roleInstruction` or default          | Template-resolved with workflow/phase variables |
+| **Task details**       | `taskDescription`, `taskId`                      | From `state`                                    |
+| **Current phase**      | Emoji + name                                     | From `active.currentPhase`                      |
+| **Progress**           | `globalStepCount` and `phaseIndex`/total         | Format varies for linear vs nested              |
+| **Phase instructions** | `currentPhase.instructions`                      | Template-resolved                               |
+| **Profiles**           | `availableProfiles` + all workflow profiles      | Lists per-phase and global profiles             |
+| **Advance reminder**   | `definition.advanceReminder` or default          | Reminds agent to call `workflow_step`           |
+
+**Default role instruction:**
+
+> You are the ORCHESTRATOR for this workflow. You must NOT use the edit or write tools directly. All implementation work must be delegated to subagents via the delegate_to_subagents tool. Follow the phase instructions precisely.
+
+**Default advance reminder:**
+
+> When you finish this phase, call the workflow_step tool with action='next' to advance to the next phase. If you need to restart the current scope from the beginning, use action='loop'.
+
+Template variables available to `roleInstruction`, `instructions`, and `advanceReminder`:
+
+`{workflowName}`, `{workflowKey}`, `{description}`, `{taskId}`, `{phaseId}`, `{phaseName}`, `{previousPhaseName}`, `{nextPhaseName}`, `{blockedToolsList}`, `{toolName}`, `{breadcrumbPath}`, `{globalStepCount}`
+
+---
+
+## handleAgentEnd
+
+```ts
+function handleAgentEnd(
+  pi: ExtensionAPI,
+  state: WorkflowState | null,
+  definitions: Record<string, WorkflowDefinition>,
+  ctx: ExtensionContext,
+  event: AgentEndEvent,
+): HookStateMutation;
+```
+
+**Called on:** `agent_end`
+
+This hook has three distinct code paths. It returns a [`HookStateMutation`](#hookstatemutation-interface) to tell `index.ts` how to update module state.
+
+### Case A — Workflow just completed (DONE)
+
+**Condition:** `state` exists, `state.active === false`, `state.completionNotified === false`.
+
+There are two sub-cases:
+
+#### Normal completion (`state.cancelled === false`)
+
+1. Looks up the definition via `state.workflowKey`.
+2. Resolves the `completionMessage` template (or default) with variables: `{workflowName}`, `{taskDescription}`, `{taskId}`, `{phaseCount}`.
+3. Sends a visible message via `pi.sendMessage` with `customType: "workflow:complete"`, `display: true`, `triggerTurn: false`.
+4. Sets `state.completionNotified = true`.
+5. Clears the status bar.
+6. Returns `{ unload: true, persist: true }`.
+
+**Default completion message:**
+
+```
+✅ **{workflowName} Complete**
+
+**Task:** {taskDescription}
+**Task ID:** {taskId}
+**Phases completed:** {phaseCount}
+```
+
+#### Cancellation (`state.cancelled === true`)
+
+Same flow as normal completion, but resolves `completionMessage` if set, otherwise falls back to `DEFAULT_CANCELLED_MESSAGE` (not `DEFAULT_COMPLETION_MESSAGE`). Returns `{ unload: true, persist: false }` (no persistence of cancelled state).
+
+> **Note:** There is no separate `cancelledMessage` field on `WorkflowDefinition`. The cancellation path reuses `completionMessage` with `DEFAULT_CANCELLED_MESSAGE` as fallback. Additionally, the `/cancel-workflow` command (`src/command.ts`) sends a hardcoded message with no template resolution and unloads state immediately, so this hook branch only fires when cancelled state is reached through other paths (e.g., session resume).
+
+**Default cancelled message:**
+
+```
+❌ **{workflowName} Cancelled**
+
+**Task:** {taskDescription}
+**Task ID:** {taskId}
+```
+
+### Case B — Workflow still active (agent stopped mid-workflow)
+
+**Condition:** `state.active === true`.
+
+1. Checks [`wasAborted(event.messages)`](#wasaborted-check) — if the user interrupted the agent, returns `{ unload: false, persist: false }` (no enforcement).
+2. Resolves the active workflow. If resolution fails, returns no-op.
+3. Resolves the `notDoneReminder` template (or default) with variables: `{workflowName}`, `{phaseName}`, `{phaseEmoji}`, `{phaseInstructions}`, `{taskDescription}`, `{taskId}`, `{workflowKey}`.
+4. Delegates to `startCountdown(pi, ctx, reminder)`, which behaves differently based on `ctx.hasUI`:
+   - **With UI** — displays a `workflow-countdown` widget above the editor and uses `timerManager.startInterval(1000, ...)` to tick down from 3 seconds, updating the widget each second. When the countdown reaches zero, calls `timerManager.clearAll()`, removes the widget, and injects the reminder via `pi.sendUserMessage(reminder)`.
+   - **Without UI** — sends an immediate `pi.sendMessage` with `customType: "workflow:countdown"`, `display: true`, `triggerTurn: false`, then uses `timerManager.startTimeout(3000, ...)` to inject the reminder after 3 seconds.
+   In both paths, if the user started typing during the grace period, the `pi.sendUserMessage` call is caught and silently ignored. All timer handles are tracked by the [`TimerManager`](../src/TimerManager.ts) singleton (`timerManager`), which prevents stale callbacks and allows clean cancellation via `timerManager.clearAll()`.
+5. Returns `{ unload: false, persist: false }`.
+
+**Default not-done reminder:**
+
+```
+⚠️ The {workflowName} is still active. Current phase: {phaseEmoji} {phaseName}.
+
+You must NOT stop yet. The workflow requires you to complete the current phase
+and call workflow_step to advance.
+
+Current phase instructions:
+{phaseInstructions}
+
+Continue working on the current phase and call workflow_step when done.
+```
+
+### Case C — Already notified or no state
+
+**Condition:** State is null, or `completionNotified === true`, or any other unhandled case.
+
+Returns `{ unload: false, persist: false }` — a no-op.
+
+### wasAborted Check
+
+The `wasAborted` helper walks `event.messages` in reverse to find the last assistant message. If that message has `stopReason === "aborted"`, the agent was interrupted by the user. This prevents the auto-continue countdown from firing when the user deliberately stopped the agent.
+
+---
+
+## HookStateMutation Interface
+
+```ts
+interface HookStateMutation {
+  /** If true, set module state to null (unload workflow). */
+  unload: boolean;
+  /** If set, replace module state with this value (mutated copy). */
+  state?: WorkflowState;
+  /** If true, persist the current state via pi.appendEntry. */
+  persist: boolean;
+}
+```
+
+Returned by `handleAgentEnd` and consumed by `index.ts` in the `agent_end` handler:
+
+```ts
+const mutation = handleAgentEnd(pi, state, definitions, ctx, event);
+if (mutation.unload) {
+  state = null; // Unload: clear module state
+} else if (mutation.state) {
+  state = mutation.state; // Replace: use the returned state
+}
+if (mutation.persist && state) {
+  persistState(pi, state); // Persist: write to session entry log
+}
+```
+
+### Mutation Semantics by Case
+
+| Case                     | `unload` | `state` | `persist` | Effect                               |
+| ------------------------ | -------- | ------- | --------- | ------------------------------------ |
+| No-op                    | `false`  | —       | `false`   | No changes                           |
+| Normal completion        | `true`   | —       | `true`    | State persisted, then unloaded       |
+| Cancellation             | `true`   | —       | `false`   | State discarded, unloaded            |
+| Still active / countdown | `false`  | —       | `false`   | No state change; auto-continue fires |
+
+---
+
+## Message Custom Types
+
+The hooks produce three distinct `customType` values, each with a registered renderer in [`src/renderers.ts`](../src/renderers.ts):
+
+| Custom Type          | Produced By               | `display` | `triggerTurn` | Rendered Appearance                          |
+| -------------------- | ------------------------- | --------- | ------------- | -------------------------------------------- |
+| `workflow:context`   | `handleBeforeAgentStart`  | `false`   | —             | `🔄 [Workflow Context injected]` (dim)       |
+| `workflow:complete`  | `handleAgentEnd` (Case A) | `true`    | `false`       | Bold success/completion message in green     |
+| `workflow:countdown` | `handleAgentEnd` (Case B) | `true`    | `false`       | `⏳ Auto-continuing workflow in 3s...` (dim) |
+
+### Renderer Details
+
+Each custom type has a dedicated renderer registered via `pi.registerMessageRenderer`:
+
+- **`workflow:context`** — Renders a minimal dim accent line. Because `display: false`, this message is hidden from the user's main conversation view; the renderer produces a subtle indicator only.
+- **`workflow:complete`** — Renders the full completion or cancellation message in bold green (`theme.fg("success", ...)`).
+- **`workflow:countdown`** — Renders the countdown timer text in accent color with dim styling, showing the user they have a grace period to interrupt.
+
+---
+
+## Hook Interaction Flow
+
+The following timeline shows how the hooks interact during a typical workflow run:
+
+```
+1. session_start / session_tree
+   └─ loadWorkflows() → reconstructState() → updateStatus()
+
+2. [Each agent turn]
+   ├─ before_agent_start
+   │  └─ handleBeforeAgentStart() → injects workflow:context message
+   ├─ [agent runs, may call tools]
+   │  └─ tool_call (per tool)
+   │     └─ handleToolCall() → may block with reason
+   └─ agent_end
+      └─ handleAgentEnd() → HookStateMutation
+         ├─ Case A: DONE → workflow:complete message, unload
+         ├─ Case B: still active → workflow:countdown, 3s auto-continue
+         └─ Case C: no-op
+
+3. turn_end
+   └─ updateStatus() → refreshes status bar with current phase
+```
+
+Each hook reads state immutably (except `handleAgentEnd`, which may set `completionNotified`). All state mutations flow back through `index.ts` via the `HookStateMutation` return value — hooks never call `setState` directly.