@gotgenes/pi-autoformat 0.1.0 → 4.0.3

package/docs/plans/0022-pi-coding-agent-types.md

@@ -0,0 +1,201 @@
+---
+issue: 22
+issue_title: "Depend on @mariozechner/pi-coding-agent for runtime types instead of duck-typing"
+---
+
+# Plan: Adopt `@mariozechner/pi-coding-agent` Types (Issue #22)
+
+## Problem Statement
+
+`src/extension.ts` declares the entire Pi runtime API surface as duck-typed `*Like` aliases (`ExtensionApiLike`, `ExtensionContextLike`, `ExtensionUILike`, `ToolResultEventLike`, `ToolCallEventLike`, `TextContentLike`, `ThemeColorName`).
+Pi already publishes the real shapes via `@mariozechner/pi-coding-agent`, but we have no Pi dependency in `package.json`, so the duck-typed surface is what TypeScript checks against.
+
+That looseness shipped a real bug: our `theme?: { fg(...): string }` shape happily accepted plain arrow-function stubs in tests, which hid the `this`-binding regression in `themed()` for an entire release cycle until a user surfaced it (retro `0016`, fixes `6a6ec16` / `6ba7576`).
+Anchoring against Pi's real types — especially the `Theme` class — would have caught the bug at compile time.
+
+This is a typing-only refactor: no behavior change, no public-config change, no schema change.
+
+## Goals
+
+- Add `@mariozechner/pi-coding-agent@^0.72.0` to `devDependencies` (types-only; Pi loads us at runtime).
+- Replace every `*Like` alias in `src/extension.ts` with the corresponding real export from `@mariozechner/pi-coding-agent`.
+- Type the public entrypoint and `pi.on(...)` handlers with the real `ExtensionAPI`, `ExtensionContext`, `ToolCallEvent`, and `ToolResultEvent` so a class-based `Theme` substitute is required at the boundary.
+- Update test stubs (`test/extension.test.ts`, others as needed) so they compile against the real types and continue to exercise the behavior we already cover.
+- Keep the diff zero-runtime-weight: no `dependencies`, no new imports of values from `@mariozechner/pi-coding-agent` (types only).
+
+This change is **not** breaking from the consumer's perspective — Pi already injects these shapes at runtime.
+It is, however, a build-time tightening: a future incompatible Pi release will fail our build until the dep is bumped.
+
+## Non-Goals
+
+- Adding `@mariozechner/pi-coding-agent` to `dependencies` or `peerDependencies`.
+  Pi is the loader, not a consumer of our package.
+- Behavior changes to formatter dispatch, status reporting, or config loading.
+- Touching `src/config-loader.ts`, `src/formatter-config.ts`, `src/prompt-autoformatter.ts`, etc. — none of them reference the Pi runtime API.
+- Pinning Pi tighter than the issue suggests; `^0.72.0` stays.
+- Updating `schemas/pi-autoformat.schema.json`, `docs/configuration.md`, `README.md`, or `docs/plans/`.
+  None reference the duck-typed shapes.
+- Adopting Pi's `isBashToolResult` / `isEditToolResult` / `isWriteToolResult` type guards as the dispatch mechanism.
+  Our existing `toolName === "bash"` / `"edit"` / `"write"` string checks are equivalent and out of scope; introducing new dispatch utilities is a separate change.
+
+## Background
+
+Relevant pieces in this repo:
+
+- `src/extension.ts` declares (around lines 35–100):
+  - `NotificationType` — kept (it's our own narrow alias for the literal union, not duck-typing).
+  - `ThemeColorName` — superseded by `ThemeColor` (re-exported from Pi's main entrypoint).
+  - `ExtensionUILike` — superseded by `ExtensionUIContext`.
+  - `ExtensionContextLike` — superseded by `ExtensionContext`.
+  - `TextContentLike` — Pi exports `TextContent` (and `ToolResultEventBase.content` is `(TextContent | ImageContent)[]`).
+  - `ToolCallEventLike` / `ToolResultEventLike` — Pi exports `ToolCallEvent` / `ToolResultEvent` as discriminated unions over `toolName`.
+  - `ExtensionApiLike` — Pi exports `ExtensionAPI`. Note Pi's `events` channel is **not** part of `ExtensionAPI` today; we currently piggyback via an optional `events?` property.
+- `src/extension.ts` uses internal helpers (`setAutoformatStatus`, `reportMessage`, `formatStatusLine`, `defaultReportFlushResult`, `subscribeToEventBus`, `runFormatter`, …) that read only `ctx.cwd`, `ctx.hasUI`, `ctx.ui.notify`, `ctx.ui.setStatus`, and `ctx.ui.theme`.
+- `test/extension.test.ts` builds lightweight `TestContext` objects with exactly those fields plus a `theme.fg` stub.
+  Real `ExtensionContext` requires `sessionManager`, `modelRegistry`, `model`, `signal`, `isIdle()`, `abort()`, `hasPendingMessages()`, `shutdown()`, `getContextUsage()`, `compact()`, `getSystemPrompt()` — none of which our extension touches.
+- `test/extension.test.ts` already has one `class StubTheme` (the regression test for `6a6ec16`) that demonstrates the class-based stub pattern.
+
+Pi's exports we will pull in (all `import type`, all from the main `@mariozechner/pi-coding-agent` entrypoint):
+
+- `ExtensionAPI`
+- `ExtensionContext`
+- `ExtensionUIContext`
+- `ToolCallEvent`
+- `ToolResultEvent`
+- `TextContent`
+- `Theme`, `ThemeColor`
+
+## Design Overview
+
+### Boundary policy (decided via `ask-user`)
+
+The public entrypoint `autoformatExtension(pi: ExtensionAPI)` and every `pi.on(...)` handler use **real** Pi types.
+That alone is enough to force test stubs to substitute a real `Theme` (or class-based equivalent) for `ctx.ui.theme`, which is the property that hid the regression.
+
+Internal helpers narrow their `ctx` parameter to the subset they actually consume:
+
+```typescript
+type AutoformatExtensionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "ui">;
+```
+
+This keeps test setup cheap (no need to fabricate `sessionManager`, `modelRegistry`, etc.) while still anchoring `ui` to Pi's real `ExtensionUIContext`.
+A handler registered through `pi.on("agent_end", handler)` receives a full `ExtensionContext`; passing it to `setAutoformatStatus(ctx)` is a structural-narrowing pass-through, not a cast.
+
+### Event-bus channel
+
+Our optional `pi.events?.on(...)` access is **not** part of Pi's `ExtensionAPI` today.
+We preserve the runtime feature by extending the locally-imported `ExtensionAPI` with an optional `events` member through intersection at the `subscribeToEventBus` call site, not by re-declaring the whole API:
+
+```typescript
+type ExtensionAPIWithEvents = ExtensionAPI & {
+  events?: {
+    on(channel: string, handler: (data: unknown) => void): () => void;
+  };
+};
+```
+
+This is the only documented place where we widen Pi's surface.
+If/when Pi adds `events` to `ExtensionAPI` proper, deleting this alias is a one-line change.
+
+### Tool-event handling
+
+`ToolResultEvent` is a discriminated union (`BashToolResultEvent | EditToolResultEvent | WriteToolResultEvent | …`).
+Our existing dispatch already keys on `event.toolName === "bash" | "edit" | "write" | "custom_*"`, which TypeScript narrows naturally — no new type guards required.
+`event.content` is typed `(TextContent | ImageContent)[]`; `extractToolOutputText` already filters by `typeof item.text === "string"`, which works unchanged for both branches.
+
+### Test stubs
+
+`test/extension.test.ts` `TestContext` and `createContext` change:
+
+- `TestContext` becomes `Pick<ExtensionContext, "cwd" | "hasUI"> & { ui: Pick<ExtensionUIContext, "notify" | "setStatus"> & { theme?: Theme } }` (minimal surface required by the helpers under test).
+- `createContext`'s default `theme` becomes a single shared class-based stub (`StubTheme` from the existing regression test, hoisted to a test util) so plain-arrow-function themes are not accepted anywhere.
+- `TestPi.on` is typed as `ExtensionAPI["on"]`; callers narrow per event name.
+- `TestPi.events` is typed against the local `ExtensionAPIWithEvents["events"]`.
+
+### Edge cases
+
+- **`ctx.ui.theme` is optional in Pi's types.** All call sites already null-check it; no behavior change.
+- **Tests that emit synthetic tool events** currently build object literals matching `ToolResultEventLike`. Real `ToolResultEvent`'s discriminated branches require concrete `details` and full `content` typing.
+  We satisfy them with `as ToolResultEvent` casts at the test boundary (the events do not originate from real Pi at runtime in tests, and the cast is one-place per emit), or — preferred — `satisfies` checks against `Partial<BashToolResultEvent>` etc. where the field set is already complete.
+  Choose the lighter option per call site; the goal is "tests still compile and still cover the same paths."
+
+## Module-Level Changes
+
+### `package.json`
+
+- Add `"@mariozechner/pi-coding-agent": "^0.72.0"` to `devDependencies`.
+- No other field changes.
+
+### `src/extension.ts`
+
+- Remove `ThemeColorName`, `ExtensionUILike`, `ExtensionContextLike`, `TextContentLike`, `ToolResultEventLike`, `ToolCallEventLike` (~25 lines).
+- Add `import type { ExtensionAPI, ExtensionContext, ExtensionUIContext, ToolCallEvent, ToolResultEvent, Theme, ThemeColor } from "@mariozechner/pi-coding-agent";` (only the symbols actually referenced).
+- Introduce local narrow aliases:
+  - `type AutoformatExtensionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "ui">;`
+  - `type ExtensionAPIWithEvents = ExtensionAPI & { events?: { on(channel: string, handler: (data: unknown) => void): () => void } };`
+- Replace `ExtensionApiLike` with `ExtensionAPI` at the public entrypoint, and `ExtensionAPIWithEvents` only at `subscribeToEventBus`.
+- Replace `ExtensionContextLike` with `AutoformatExtensionContext` on internal helpers; the top-level `pi.on(...)` handlers receive the real `ExtensionContext`.
+- Replace `ThemeColorName` parameter types with `ThemeColor`.
+- Re-export `ExtensionApiLike` is removed (`export type { ExtensionApiLike }`); replace with `export type { ExtensionAPI }` re-export from Pi if any consumer needs it. (Internal-only today; verify with a `rg` before deleting.)
+
+### `test/extension.test.ts`
+
+- Drop the local `Handler`, `EventName`, `TestContext` definitions in favor of:
+  - `EventName` keyed on Pi's `ExtensionEvent` literal subset we use.
+  - `TestContext` narrowed via `Pick<ExtensionContext, ...>` (see Design).
+- Hoist `StubTheme` to module scope and reuse it as the default `createContext` theme.
+- Replace remaining `theme: { fg: (_name, text) => text }` literals with `theme: new StubTheme()`.
+- Cast or `satisfies`-check synthetic events against `ToolResultEvent` / `ToolCallEvent` at emit sites.
+- Update the `import type { ExtensionApiLike }` line to whatever the new export name is (if exported).
+
+### `test/acceptance.test.ts`
+
+- Audit for any duck-typed shape; today it does not reference `*Like` aliases (`grep` returned no hits), so the change is likely no-op.
+  Re-check after `src/extension.ts` lands.
+
+### Other tests
+
+- `rg -l "Like\b" test/` to be sure nothing else duck-types Pi shapes.
+  Update if found.
+
+### Docs
+
+- No changes to `docs/configuration.md`, `README.md`, `schemas/pi-autoformat.schema.json` (verified — none reference the duck-typed shapes).
+
+## TDD Order
+
+This is a typing-only refactor, so the "red" step is **a failing `tsc`/`vitest` typecheck**, not a failing runtime assertion.
+Every cycle ends with `pnpm test` and `pnpm exec tsc --noEmit` (or whatever typecheck script lands as part of step 1).
+
+1. **chore: add `@mariozechner/pi-coding-agent` devDependency.** Install via `pnpm add -D @mariozechner/pi-coding-agent@^0.72.0`. Verify `pnpm test` still passes (no source changes yet). Commit: `chore: add pi-coding-agent for runtime types`.
+
+2. **test: prove a plain-function `theme.fg` stub will fail to typecheck once we adopt real types.** Add a single isolated typecheck-only test (e.g. `test/types/theme-stub.test-d.ts` using `expectTypeOf` or a `// @ts-expect-error` block in a new TS file under `test/`) that asserts `{ fg: (_n, t) => t }` is **not** assignable to `Theme`.
+   This is currently `// @ts-expect-error` against the duck type (so it red-flags) — it goes green in step 4. Commit: `test: pin Theme stub-shape expectations`.
+
+3. **feat: replace `*Like` aliases in `src/extension.ts` with real Pi types.** Import real types, introduce `AutoformatExtensionContext` and `ExtensionAPIWithEvents`, swap every signature.
+   Tests will fail to compile here; that's expected.
+   Do **not** touch test files yet — this commit captures the boundary-changing diff in isolation.
+   *(Tip: temporarily skip `pnpm test` in this commit if needed; mark in commit body. Or fold steps 3+4 into one commit if a half-broken intermediate offends — author's call.)* Commit: `refactor: import Pi types from pi-coding-agent`.
+
+4. **test: update test stubs to satisfy real Pi types.** Hoist `StubTheme`, narrow `TestContext`, cast synthetic events, etc.
+   `pnpm test` and typecheck both green. Step 2's expectation flips from `@ts-expect-error` to a positive assertion. Commit: `test: adopt class-based Theme stubs and Pi event types`.
+
+5. **chore: verify lint / docs alignment.** Run `pnpm run lint` and `pnpm run lint:md`. No expected changes; confirm `schemas/pi-autoformat.schema.json`, `docs/configuration.md`, `README.md` untouched. If any drift, address in a single follow-up commit. Commit (only if needed): `docs: align after Pi types adoption`.
+
+If steps 3 and 4 must be merged to keep CI green at every commit, do so and label the merged commit `refactor: adopt pi-coding-agent types` — but prefer the split when feasible because the test-stub diff is mechanical and noisy.
+
+## Risks and Mitigations
+
+- **Risk: future Pi release breaks our build.** Mitigation: `^0.72.0` range + Renovate/Dependabot bump.
+  Build-time breakage is the desired tradeoff vs the runtime bug we just shipped.
+- **Risk: real `ExtensionContext` requires fields we never use, churning every test stub.** Mitigation: narrow internal helpers to `Pick<ExtensionContext, "cwd" | "hasUI" | "ui">` (decision recorded above).
+- **Risk: discriminated-union `ToolResultEvent` rejects our synthetic test events.** Mitigation: cast at emit sites; the test-side narrowing has no production value beyond "compiles."
+- **Risk: `pi.events` is not in Pi's `ExtensionAPI`, so the real type loses the channel we depend on.** Mitigation: local `ExtensionAPIWithEvents` intersection alias, scoped to `subscribeToEventBus`, with a TODO comment to delete once Pi exposes it natively.
+- **Risk: `export type { ExtensionApiLike }` is re-exported and consumed downstream.** Mitigation: `rg "ExtensionApiLike"` before deletion; if external consumers exist (none expected — this is an extension package), preserve as a deprecated alias for one release.
+- **Risk: pnpm install pulls a large transitive tree.** Mitigation: it's a `devDependency`, not shipped; verify with `pnpm why`.
+
+## Open Questions
+
+- Should we adopt Pi's `isBashToolResult` / `isEditToolResult` / `isWriteToolResult` type guards in `src/extension.ts` instead of `event.toolName === "..."` string checks? Out of scope for this plan; revisit if the dispatch grows or a guard would simplify a future change.
+- Should the local `ExtensionAPIWithEvents` alias migrate into a shared `src/pi-types.ts` module if other modules ever need it? Defer — only one call site uses it today.
+- Should we narrow `TextContent` further (e.g. require `type === "text"`)? Defer — the existing runtime check on `typeof item.text === "string"` is already the contract; tightening the type adds no value.

package/docs/plans/0027-format-before-agent-exit-follow-up-turn.md

@@ -0,0 +1,355 @@
+---
+issue: 27
+issue_title: "Format before agent exit and give the agent a follow-up turn"
+---
+
+# Format before agent exit and give the agent a follow-up turn
+
+## Problem Statement
+
+Autoformatting currently runs at `agent_end`, after the agent has fully exited its turn loop.
+This causes two problems:
+
+1. The agent discovers dirty state (formatting diffs) it did not produce on its next invocation, leading to confusion or unnecessary corrective actions.
+2. In commit-and-push workflows like `/ship-issue`, the agent commits its work before formatting runs, so the pushed commit contains unformatted code.
+
+Both stem from the agent never getting a chance to observe or react to formatting changes.
+
+Additionally, formatter *failures* (syntax errors, missing config) are currently reported only to the human via `ui.notify`.
+The agent cannot see or fix these issues, even though it is often best positioned to do so.
+
+Finally, the `formatMode` config field offers three timing modes (`"tool"`, `"prompt"`, `"session"`), but only `"prompt"` is meaningfully useful:
+
+- `"tool"` formats after every tool call — nearly identical to per-turn (93% of turns have one tool call) and actively harmful in multi-tool turns where formatting between edits can corrupt subsequent `oldText` matches.
+- `"session"` formats at session shutdown, when the agent is completely gone and cannot react.
+
+Since nobody outside the project uses this extension yet, we can make a clean break.
+
+## Goals
+
+1. Remove the `formatMode` config field entirely. The runtime always uses prompt-end timing (the previous `"prompt"` behavior). The loader tolerates the legacy key, emits a config issue, and discards the value.
+2. After formatting runs at `agent_end`, give the agent one follow-up turn via `pi.sendMessage({ triggerTurn: true })` so it can see which files changed and react.
+3. Include formatter failure details (stderr, exit code) in the follow-up message so the agent can attempt to fix issues.
+4. Prevent infinite loops: at most one follow-up per user prompt.
+5. Expose the follow-up behavior as a new boolean config field (`notifyAgent`), defaulting to `false`.
+6. Skip the follow-up turn when the flush produced no groups (nothing to report).
+
+## Non-Goals
+
+1. Byte-level diffing to detect whether the formatter actually changed file content.
+   The initial implementation triggers the follow-up whenever the flush produces non-empty groups.
+2. Customizing the follow-up message template via config.
+3. Making `notifyAgent: true` the default (defer until real-world feedback).
+
+## Background
+
+### Relevant modules
+
+| Module | Role |
+| --- | --- |
+| `src/extension.ts` | Extension entrypoint. Registers lifecycle handlers (`session_start`, `tool_result`, `agent_end`, `session_shutdown`). Owns `queueFlush()` and result reporting. Has `formatMode` branching in `tool_result` and `agent_end` handlers. |
+| `src/formatter-config.ts` | Defines `FormatMode` type, `AutoformatConfig`, `UserFormatterConfig`, defaults, `createFormatterConfig()`. |
+| `src/config-loader.ts` | Loads/merges global+project config, validates `formatMode` values, produces `LoadConfigResult`. |
+| `src/prompt-autoformatter.ts` | `PromptAutoformatter` class. Tracks touched files, runs formatter chains, returns `PromptAutoformatterResult`. |
+| `src/formatter-executor.ts` | `BatchRun` type — includes `stdout`, `stderr`, `exitCode` for each formatter invocation. |
+| `schemas/pi-autoformat.schema.json` | JSON Schema for config validation. Includes `formatMode` enum. |
+| `docs/configuration.md` | User-facing config documentation. Documents `formatMode` and its three values. |
+| `test/extension.test.ts` | Extension lifecycle tests with `TestPi` harness. Tests for `"tool"`, `"prompt"`, `"session"` modes. |
+| `test/config-loader.test.ts` | Config validation and merge tests. |
+
+### Pi extension API surface
+
+```typescript
+// Current flush trigger
+pi.on("agent_end", handler)
+
+// New — triggers a follow-up agent turn
+pi.sendMessage<T>(
+  message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
+  options?: {
+    triggerTurn?: boolean;
+    deliverAs?: "steer" | "followUp" | "nextTurn";
+  }
+): void;
+```
+
+`pi.sendMessage` is on the `ExtensionAPI` object (the `pi` closure variable), not on the per-event `ExtensionContext`.
+No new wiring is needed.
+
+### Session data insights
+
+Analysis of ~1,900 assistant turns:
+
+- 93.4% contain exactly one tool call (sequential across turns, not batched within).
+- Average mutation-turn streak: 4.6 turns.
+- `formatMode: "tool"` would fire nearly as often as per-turn, with negligible batching benefit and real risk of corrupting multi-tool edits.
+
+## Design Overview
+
+### Removing `formatMode`
+
+Per AGENTS.md deprecation policy: accept the legacy key, emit a single non-fatal config issue describing the removal, and discard the value.
+
+Concrete changes:
+
+1. Drop `FormatMode` type from `src/formatter-config.ts`.
+2. Drop `formatMode` from `AutoformatConfig`, `UserFormatterConfig`, `DEFAULT_FORMATTER_CONFIG`, and `createFormatterConfig()`.
+3. Drop `formatMode` from `schemas/pi-autoformat.schema.json`.
+4. Drop `formatMode` from `docs/configuration.md`.
+5. In `src/config-loader.ts`: when `formatMode` key is present in user config, emit a config issue (`formatMode has been removed; prompt-end formatting is now the only mode.`) and discard.
+6. In `src/extension.ts`: remove all `formatMode` branching. The `tool_result` handler no longer conditionally flushes. The `agent_end` handler always flushes. The `session_shutdown` handler no longer conditionally flushes (it still cleans up state).
+7. Remove tests for `"tool"` and `"session"` mode behaviors; add a test for the legacy-key config issue.
+
+### Sequence with `notifyAgent: true`
+
+```text
+Turn N:   agent makes final edits
+Turn N+1: agent says "Done!" → agent_end fires
+            ↓
+          flush formatter (batched, always prompt-end)
+            ↓
+          flush produced groups?
+            ├─ no  → done, no follow-up
+            └─ yes → compose message (successes + failures)
+                     pi.sendMessage({ customType: "autoformat-notify", ... },
+                                    { triggerTurn: true })
+            ↓
+Turn N+2: agent sees notification, can react (commit, fix failures, acknowledge)
+            ↓
+          agent_end fires again
+            ↓
+          flush (any new touched files from Turn N+2?)
+            ├─ groups → format them, but do NOT send another follow-up (loop guard)
+            └─ empty  → done
+```
+
+### Loop guard
+
+A `followUpPending` flag on `SessionState` prevents unbounded re-triggering:
+
+1. On `agent_end` entry: read `followUpPending` into a local, then set it to `false`.
+2. After flush: if result has groups AND the locally-read value was `false`, send the message and set `followUpPending = true`.
+3. Effect: first `agent_end` → format + notify. Second `agent_end` → format if needed, no notify.
+
+The flag resets naturally because step 1 always clears it on entry.
+
+### Follow-up message content
+
+The message body combines successes and failures into one agent-readable block:
+
+```text
+[autoformat] Formatted 3 file(s): src/foo.ts, src/bar.ts, README.md
+
+Failures:
+  prettier (exit 2) on src/broken.ts:
+    stderr: SyntaxError: Unexpected token at line 42
+```
+
+Specifics:
+
+- File list truncated at 10, with "… and N more" suffix.
+- Failure details include `stderr` (trimmed by the existing `formatterOutput` config limits).
+- `stdout` included only when `formatterOutput.onFailure` is `"both"`.
+- When all runs succeeded, the failures section is omitted.
+- When all runs failed (no successes), the success line is omitted.
+- `customType` is `"autoformat-notify"` for identification in session logs and potential custom rendering.
+
+### Config shape
+
+```typescript
+// UserFormatterConfig (optional)
+notifyAgent?: boolean;
+
+// AutoformatConfig (resolved)
+notifyAgent: boolean;  // default: false
+```
+
+### `TestPi` harness changes
+
+Add `sendMessage` capture to `TestPi`:
+
+```typescript
+readonly sentMessages: Array<{
+  message: { customType?: string; content?: string };
+  options?: { triggerTurn?: boolean };
+}> = [];
+
+readonly sendMessage = ((message: unknown, options?: unknown) => {
+  this.sentMessages.push({ message, options });
+}) as ExtensionAPI["sendMessage"];
+```
+
+## Module-Level Changes
+
+### `src/formatter-config.ts`
+
+1. Remove `FormatMode` type.
+2. Remove `formatMode` from `UserFormatterConfig`, `AutoformatConfig`, `DEFAULT_FORMATTER_CONFIG`.
+3. Remove `formatMode` from `createFormatterConfig()`.
+4. Add `notifyAgent?: boolean` to `UserFormatterConfig`.
+5. Add `notifyAgent: boolean` to `AutoformatConfig` (default: `false`).
+6. Wire `notifyAgent` through `createFormatterConfig()`.
+
+### `src/config-loader.ts`
+
+1. Remove `validateFormatMode()`.
+2. When `formatMode` key is present, emit a config issue and discard.
+3. Add `notifyAgent` boolean validation.
+4. Wire `notifyAgent` through `mergeUserConfigs()`.
+
+### `schemas/pi-autoformat.schema.json`
+
+1. Remove `formatMode` property.
+2. Add `notifyAgent` boolean property.
+
+### `src/extension.ts`
+
+1. Remove `formatMode` branching from `tool_result` handler (no more conditional flush).
+2. Remove `formatMode !== "prompt"` guard from `agent_end` handler (always flush).
+3. Remove `formatMode === "session"` conditional from `session_shutdown` handler.
+4. Add `followUpPending: boolean` to `SessionState`.
+5. Extract `buildNotifyMessageContent(result, config): string | undefined` helper.
+6. In `agent_end` handler: after flush, conditionally call `pi.sendMessage`.
+
+### `docs/configuration.md`
+
+1. Remove `formatMode` section.
+2. Add `notifyAgent` section.
+
+### `README.md`
+
+1. Remove any `formatMode` references.
+2. Add `notifyAgent` mention.
+
+### `test/extension.test.ts`
+
+1. Remove tests for `"tool"` mode and `"session"` mode behavior.
+2. Remove `formatMode` parameter from `createLoadResult()` helper.
+3. Extend `TestPi` with `sendMessage` capture.
+4. Add follow-up turn tests.
+
+### `test/config-loader.test.ts`
+
+1. Remove `formatMode` validation tests (valid values, invalid values).
+2. Add test for legacy `formatMode` key producing a config issue.
+3. Add `notifyAgent` validation tests.
+
+## TDD Order
+
+### 1. Remove `formatMode` from config types and defaults
+
+- **Test surface:** `test/formatter-config.test.ts` or `test/config-loader.test.ts`.
+- **Covers:** `FormatMode` type removed; `createFormatterConfig()` no longer accepts or produces `formatMode`; existing tests that reference `formatMode` are updated or removed.
+- **Commit:** `feat!: remove formatMode config field (#27)`
+
+### 2. Legacy `formatMode` key tolerance in config loader
+
+- **Test surface:** `test/config-loader.test.ts`.
+- **Covers:** Config containing `formatMode: "prompt"` (or any value) is accepted without error but emits a config issue. The value is discarded.
+- **Commit:** `feat: emit config issue for legacy formatMode key (#27)`
+
+### 3. Remove `formatMode` from JSON schema
+
+- **Test surface:** `test/schema.test.ts`.
+- **Covers:** Schema no longer includes `formatMode`. Configs with `formatMode` pass validation (via `additionalProperties` tolerance or explicit handling).
+- **Commit:** `feat!: remove formatMode from config schema (#27)`
+
+### 4. Remove `formatMode` branching from extension runtime
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** Remove `"tool"` and `"session"` mode tests. `tool_result` handler no longer flushes. `agent_end` always flushes. `session_shutdown` no longer conditionally flushes. Update `createLoadResult()` helper to drop the `formatMode` parameter.
+- **Commit:** `feat!: always use prompt-end formatting (#27)`
+
+### 5. `notifyAgent` config field — types, defaults, schema, loader
+
+- **Test surface:** `test/config-loader.test.ts`, `test/schema.test.ts`.
+- **Covers:** Defaults to `false`; user-supplied `true` preserved; schema accepts boolean; non-boolean rejected.
+- **Commit:** `feat: add notifyAgent config field (#27)`
+
+### 6. Notification message builder
+
+- **Test surface:** `test/extension.test.ts` (or extracted `test/notify-message.test.ts`).
+- **Covers:** Message text with 1 file, 3 files, 11 files (truncation at 10), 0 groups (returns `undefined`). Message with mixed success/failure including stderr. Message with all-failures (no success line).
+- **Commit:** `feat: add buildNotifyMessageContent helper (#27)`
+
+### 7. `TestPi` harness — add `sendMessage` capture
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** Refactor only — `TestPi` records `sendMessage` calls. No behavioral change to existing tests.
+- **Commit:** `test: extend TestPi with sendMessage capture (#27)`
+
+### 8. Follow-up turn on successful flush
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** `notifyAgent: true` + flush with successful groups → `pi.sendMessage` called once with `{ triggerTurn: true }`, `customType: "autoformat-notify"`, and message containing file names.
+- **Commit:** `feat: send follow-up turn after formatting (#27)`
+
+### 9. Follow-up includes failure details
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** Flush with mixed success/failure → follow-up message includes stderr and exit code for failed runs.
+- **Commit:** `feat: include formatter failures in follow-up message (#27)`
+
+### 10. No follow-up on empty flush
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** Empty flush → `sendMessage` not called.
+- **Commit:** `test: no follow-up on empty flush (#27)`
+
+### 11. No follow-up when `notifyAgent` is `false`
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** Default config → `sendMessage` not called even with successful groups.
+- **Commit:** `test: notifyAgent false suppresses follow-up (#27)`
+
+### 12. Loop guard — at most one follow-up per user prompt
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** Simulate two consecutive `agent_end` events. `sendMessage` called exactly once.
+- **Commit:** `test: follow-up turn loop guard (#27)`
+
+### 13. Follow-up resets across user prompts
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** After a full cycle (agent_end → follow-up → agent_end), a new agent_end with fresh tool results triggers a new follow-up.
+- **Commit:** `test: follow-up resets across prompts (#27)`
+
+### 14. Documentation
+
+- **Test surface:** Manual review.
+- **Covers:** `docs/configuration.md` (remove `formatMode`, add `notifyAgent`), `README.md`, schema description.
+- **Commit:** `docs: document notifyAgent and remove formatMode docs (#27)`
+
+## Risks and Mitigations
+
+### Infinite follow-up loop
+
+The `followUpPending` flag ensures at most one follow-up per user prompt.
+Even if the follow-up turn triggers new edits, the second `agent_end` formats them but does not re-trigger.
+
+### `sendMessage` in non-interactive mode
+
+`pi.sendMessage` is on `ExtensionAPI`, which is always present.
+In RPC/print mode, `triggerTurn` may be a no-op.
+The extension sends the message regardless and lets Pi decide delivery.
+If problematic, a follow-up can add a `ctx.hasUI` guard.
+
+### Extra token cost
+
+The follow-up turn requires one LLM call.
+Usually a short response.
+The feature is opt-in (`notifyAgent: false`), so cost-sensitive users are unaffected.
+
+### Agent makes new edits during follow-up
+
+Expected and handled: the second `agent_end` runs the formatter on new touched files.
+The loop guard prevents a third follow-up.
+
+## Open Questions
+
+1. Should `notifyAgent` eventually default to `true`?
+   Defer until real-world feedback confirms reliability and acceptable token cost.
+2. Should the follow-up turn be skipped when formatting produced no byte-level changes?
+   Defer — requires reading files before/after, adding I/O overhead.
+3. Should the follow-up message include a diff summary (lines changed)?
+   Defer — file names and failure details are sufficient for the agent to decide whether to act.