@gotgenes/pi-autoformat 0.1.0 → 4.0.3

package/docs/plans/0002-richer-tui-formatter-summaries.md

@@ -0,0 +1,220 @@
+---
+issue: 1
+issue_title: "Add richer TUI formatter summaries"
+---
+
+# Plan: Richer TUI Formatter Summaries (Issue #1)
+
+## Problem Statement
+
+Formatter activity is reported through transient `ctx.ui.notify` toasts.
+Successes pop up and disappear; failures pop up and disappear.
+The user has no ambient indicator that "formatters ran in the background", and a failure that the user would like to revisit later can be missed if a notification is dismissed.
+
+The issue asks for richer, more scannable summaries — especially when several files or chains run in one flush — while keeping the surface low-key on the happy path and more prominent (but still non-urgent) on the failure path.
+
+## Goals
+
+- Use `ctx.ui.setStatus` to render a persistent, low-prominence summary in the footer/status bar after each prompt-end flush, so the user sees "this happened in the background" without a toast.
+- On failure, keep `ctx.ui.notify(..., "warning")` so the failure catches the eye once, **and** leave an error-colored footer status so the user can come back to it later in the session.
+- Make per-chain and per-file breakdowns more scannable when multiple files or chains run in a single flush.
+- Preserve the existing non-interactive behavior (`console.log` / `console.warn`) unchanged.
+- Preserve the existing `hideSummariesInTui` semantics: when `true`, success summaries are suppressed from the TUI; failures still surface.
+
+This change is **not** breaking at the config layer — no new config keys, no schema change.
+It does change the TUI surface used for success summaries (from notify to setStatus), which is a user-visible behavior change but not a config-breaking one.
+
+## Non-Goals
+
+- A `setWidget` block above the editor with a full per-file table.
+  The user's framing — "enough feedback to say this happened in the background" — does not justify the screen real estate.
+  We can revisit if feedback shows the footer is too thin.
+- Adding a `summarySurface` config key (notify | widget | status | none).
+  Premature; one good default beats a knob.
+  Re-open if multiple users disagree with the chosen surface.
+- Persisting summaries across sessions.
+  Status is cleared on `session_shutdown` per Pi conventions.
+- Restructuring `PromptAutoformatterResult` or the executor.
+  This plan is purely a reporting-layer change inside `src/extension.ts`.
+- Changing failure prominence beyond keeping today's `notify(warning)` plus the new persistent footer entry.
+- Theme overrides or custom color names beyond the standard `success | warning | error | dim | accent` foreground colors already used by example extensions.
+
+## Background
+
+Relevant existing pieces:
+
+- `src/extension.ts`
+  - `defaultReportFlushResult(result, { config, ctx })` — currently the only sink for formatter summaries.
+    Sends multi-line text to `ctx.ui.notify` (success or warning) on TUI, or `console.log` / `console.warn` otherwise.
+  - `summarizeFailures`, `summarizeFallbackUsages`, `collectAllFiles`, `summarizeSuccessPaths`, `formatterLabel` — pure helpers that turn a `PromptAutoformatterResult` into lines.
+    These are reusable as-is.
+  - `reportMessage(ctx, message, type)` — routes to `notify` when `ctx.hasUI`, otherwise to `console.warn`/`console.log`.
+- `src/formatter-config.ts` — `hideSummariesInTui: boolean` (default `false`).
+  Currently consulted only for the success branch in `defaultReportFlushResult`.
+- Pi extension API surface (from `pi-mono/packages/coding-agent/src/core/extensions/types.ts`):
+  - `ctx.ui.notify(message, type?)` — transient toast.
+  - `ctx.ui.setStatus(key, text | undefined)` — persistent footer/status text; pass `undefined` to clear.
+  - `ctx.ui.theme.fg("success" | "warning" | "error" | "dim" | "accent", text)` — themed foreground color, used by the `status-line.ts` example extension.
+  - `setWidget` and `custom` exist but are out of scope (see Non-Goals).
+- Lifecycle:
+  `session_start` → many `tool_call`/`tool_result` pairs → `agent_end` (the prompt-end flush we report on) → eventually `session_shutdown`.
+  Multiple flushes happen per session in interactive use.
+
+## Design Overview
+
+### Reporting flow
+
+1. Per flush, `defaultReportFlushResult` builds two views from the existing helpers:
+   - **success view** — chain count, file count, fallback-usage suffix.
+   - **failure view** — failed batch count and per-batch lines.
+2. On TUI (`ctx.hasUI === true`):
+   - If the result has zero groups, clear the status (`setStatus("autoformat", undefined)`) and return.
+     A no-op flush should not leave a stale "Autoformatted 3 files" line in the footer.
+   - If only successes:
+     - When `hideSummariesInTui` is `true`, clear the status and return.
+     - Otherwise call `setStatus("autoformat", themedSuccessLine)`.
+       Do **not** call `notify`.
+   - If any failures:
+     - Call `setStatus("autoformat", themedFailureLine)` so the user can come back to it.
+     - Call `notify(failureBlock, "warning")` once with the existing multi-line block (failed batch count + per-batch lines), so the failure catches the eye.
+3. On non-TUI (`ctx.hasUI === false`):
+   - Keep today's `console.log` / `console.warn` output verbatim.
+   - Do not call `setStatus` (it's a no-op without a UI but adds noise to mocks).
+
+### Status text format
+
+Single line, themed, ASCII-only by default to stay readable in minimal terminals.
+Dim parens carry low-priority detail.
+
+```text
+✓ autoformat: 3 files (biome, prettier)
+✓ autoformat: 1 file (biome)
+✗ autoformat: 1 batch failed (biome) — 2 ok
+```
+
+- `✓` rendered via `theme.fg("success", "✓")`; the "autoformat:" label via `theme.fg("dim", ...)`.
+- `✗` rendered via `theme.fg("error", "✗")`; the failure clause via `theme.fg("error", ...)`.
+- Formatter names in the success line are deduplicated and ordered by first appearance across `result.groups[].runs[].formatterName`.
+- Fallback usages append `(fallback after X)` only when present, reusing `formatterLabel`.
+- The line is intentionally short (~one terminal row).
+  Per-file breakdown stays in the failure notify block, which already lists files per failed batch.
+
+### Lifecycle hooks
+
+- `session_start`: clear `setStatus("autoformat", undefined)` so a fresh session does not inherit a stale status from a previous run rendered in the same UI.
+- `session_shutdown`: clear status before tearing the session down, alongside the existing `unsubscribeEventBus`.
+
+These are small additions to existing handlers in `createAutoformatExtension`.
+
+### Status key
+
+Use `"autoformat"` as the `setStatus` key.
+Single key per extension, reused across flushes (each call replaces the previous value).
+Documented in `docs/configuration.md` as informational so users writing custom themes know it exists.
+
+### Types
+
+No public type changes.
+Internally, introduce a small helper so the TUI/non-TUI branches share one source of truth:
+
+```typescript
+type FlushSummary = {
+  groupCount: number;
+  fileCount: number;
+  formatterNames: string[];
+  failureBatchCount: number;
+  failureLines: string[];
+  fallbackUsages: string[];
+};
+
+function summarizeFlush(result: PromptAutoformatterResult): FlushSummary;
+```
+
+`defaultReportFlushResult` becomes a thin dispatcher that builds a `FlushSummary` once, then renders for TUI vs non-TUI.
+
+### Edge cases
+
+- **Empty flush** (`result.groups.length === 0`): clear status; emit nothing on non-TUI (today's behavior).
+- **All-fallback-skipped chains** are already filtered upstream (`flushPrompt` drops empty groups), so they cannot produce a phantom status line.
+- **Mixed success and failure**: the status reflects failure (error-colored), success counts shown after an em dash; notify fires for failures only.
+- **Theme without color** / non-color terminals: `theme.fg` is theme-aware and the example extensions rely on it; we trust it to degrade.
+- **No `theme` available**: defensively, fall back to plain text if `ctx.ui.theme` is undefined (matches our existing duck-typed `ExtensionContextLike`).
+- **Repeated flushes**: each call to `setStatus("autoformat", ...)` replaces the previous value, so the footer always reflects the latest flush.
+
+## Module-Level Changes
+
+- `src/extension.ts`
+  - Extend `ExtensionContextLike.ui` to include optional `setStatus(key: string, text: string | undefined): void` and an optional `theme` shape with `fg(name: string, text: string): string`.
+    Both optional so existing tests using minimal stub UIs do not need to change unless they assert on status behavior.
+  - Add `summarizeFlush(result)` helper consolidating today's per-piece helpers.
+  - Add `formatStatusLine(summary, { theme })` helper returning a single string.
+  - Rewrite `defaultReportFlushResult` to:
+    1. Compute `FlushSummary`.
+    2. Branch on `ctx.hasUI`.
+    3. On TUI: empty → clear; success → `setStatus`; failure → `setStatus` + `notify`.
+    4. On non-TUI: existing `console.log` / `console.warn` paths, unchanged.
+  - In `createAutoformatExtension`:
+    - On `session_start`, after `reportConfigIssues`, call `clearAutoformatStatus(ctx)`.
+    - On `session_shutdown`, before `state = undefined`, call `clearAutoformatStatus(ctx)`.
+    - `clearAutoformatStatus` is a 3-line helper guarded by `ctx.hasUI` and `ctx.ui.setStatus`.
+- `test/extension.test.ts`
+  - New tests for the rewritten `defaultReportFlushResult` (see TDD Order).
+  - Existing notify-based assertions for success summaries change to assert on `setStatus`; failure-path assertions still expect `notify(warning)` and additionally assert `setStatus` with error styling.
+- `docs/configuration.md`
+  - Update the `hideSummariesInTui` section to reflect the new surface ("suppresses the persistent footer status on success; failures still surface via notification + status").
+- `README.md`
+  - One-paragraph update to the formatter-feedback section: footer status on success, notification + status on failure.
+- No changes to:
+  - `src/config-loader.ts`, `src/formatter-config.ts`, `schemas/pi-autoformat.schema.json` — no config additions.
+  - `src/prompt-autoformatter.ts`, `src/formatter-executor.ts` — reporting-layer-only change.
+
+## TDD Order
+
+1. **test: cover empty-flush status clearing**
+   - In `test/extension.test.ts`, add a test that calls `defaultReportFlushResult` with `{ groups: [] }` on a TUI ctx and asserts `setStatus("autoformat", undefined)` is called and `notify` is not.
+   - Commit: `test: cover empty-flush autoformat status clearing`.
+2. **feat: route success summaries through setStatus**
+   - Implement `summarizeFlush`, `formatStatusLine`, and the success branch of the new `defaultReportFlushResult` (TUI path) so the empty-flush test plus a new "single chain, multi-file success" test pass.
+   - Assert `setStatus` is called with a string containing "autoformat" and the file count; assert `notify` is **not** called.
+   - Commit: `feat: render formatter success summaries in the footer status`.
+3. **feat: surface failures via setStatus and notify together**
+   - Add a "one failed batch + one successful batch" test asserting both `setStatus` (error styling) and `notify(..., "warning")` are called, and the notify body still contains the per-batch failure lines.
+   - Commit: `feat: keep failure notifications and add persistent failure status`.
+4. **feat: honor hideSummariesInTui for the new status surface**
+   - Add tests covering `hideSummariesInTui: true` for success-only (clears status, no notify) and for failure (status + notify still fire).
+   - Commit: `feat: respect hideSummariesInTui for footer status`.
+5. **feat: clear autoformat status on session_start and session_shutdown**
+   - Add lifecycle tests that drive the extension through `session_start` and `session_shutdown` and assert `setStatus("autoformat", undefined)` is invoked at each.
+   - Commit: `feat: clear autoformat status on session lifecycle boundaries`.
+6. **test: preserve non-interactive console output**
+   - Add or update tests that assert non-TUI flushes still go through `console.log` / `console.warn` and never call `setStatus`.
+   - Commit: `test: lock in non-interactive autoformat reporting behavior`.
+7. **docs: align configuration and README with the new surface**
+   - Update `docs/configuration.md` (`hideSummariesInTui` section) and `README.md`.
+   - Commit: `docs: describe footer-status formatter summaries`.
+
+## Risks and Mitigations
+
+- **Risk: status surface surprises users who relied on success toasts.**
+  Mitigation: failures still toast; success toasts were already opt-out via `hideSummariesInTui`, and the issue explicitly flags small-success notifications as noise.
+  Document the change in `docs/configuration.md` and `README.md` in step 7.
+- **Risk: stale status from a previous flush on session reuse.**
+  Mitigation: clear on `session_start` and `session_shutdown`; each new flush overwrites the same `"autoformat"` key.
+- **Risk: `setStatus` not present on older Pi runtimes.**
+  Mitigation: feature-detect (`typeof ctx.ui.setStatus === "function"`) before calling; fall back to today's `notify(info)` if unavailable.
+  This is a small `if` branch, not a new mechanism.
+- **Risk: theme color not available.**
+  Mitigation: feature-detect `ctx.ui.theme?.fg`; fall back to plain `"✓ autoformat: …"` text.
+- **Risk: footer line clashes with other extensions writing to the footer.**
+  Mitigation: use a distinct key (`"autoformat"`); Pi's `setStatus` is keyed precisely so multiple extensions can coexist.
+- **Risk: confusing behavior when `hideSummariesInTui` was understood as "no toasts".**
+  Mitigation: docs update clarifies it now means "no success summary in TUI, regardless of surface".
+
+## Open Questions
+
+- Should we add an opt-in `setWidget` block (above editor) for users who want the per-file breakdown ambient instead of buried in a notify body?
+  Defer until someone asks for it.
+- Should `hideSummariesInTui` be renamed to `quietSuccess` or similar now that the surface changed?
+  Defer; keep the name and update its doc.
+- Should non-interactive mode also become quieter (e.g. drop success lines)?
+  Out of scope; the issue is specifically about the TUI.

package/docs/plans/0003-additional-pi-mutation-tools.md

@@ -0,0 +1,273 @@
+---
+issue: 3
+issue_title: "Post-v1: support additional Pi mutation tools"
+---
+
+# Plan: Additional Pi Mutation Tools (Issue #3)
+
+## Problem Statement
+
+The v1 extension only enqueues touched files for two tool names: Pi's built-in `write` and `edit`.
+Any other tool that mutates files — whether provided by another Pi extension, an MCP server, or a future built-in — flows through the `tool_result` event without being recognized, so its outputs are never formatted.
+
+Issue #3 asks us to "support additional Pi mutation tools" without broadening to heuristic file scanning, and to "design a clean touched-file reporting interface for custom tools."
+
+## Goals
+
+- Recognize mutations performed by **non-built-in** tools (extension- or MCP-provided) and feed the resulting paths into the existing prompt-end batching pipeline.
+- Provide a low-cost integration path for other extensions: declarative config for the common case, and a small event-bus contract for the dynamic case.
+- Keep behavior explicit, opt-in, and predictable.
+  No inference, no whole-repo scans.
+- Reuse the existing `MutationSourceHandler` plumbing, scope filtering, dedupe, and reporting paths unchanged.
+
+## Non-Goals
+
+- Tracking shell-driven mutations.
+  That is Issue #4 and has its own plan (`0004-shell-driven-mutation-coverage.md`).
+  The two efforts share the same `TouchedFilesQueue` but are independent.
+- Adding a stable, versioned public TypeScript API for cross-extension use.
+  We expose only the existing `pi.events` channel; everything else stays internal.
+- Inferring mutation intent from tool names, schemas, or output content.
+  All recognition is opt-in and explicit.
+- Strict-mode failure semantics (Issue #6).
+
+## Background
+
+What we know from `pi-mono` (verified against `packages/coding-agent/src/core/extensions/types.ts` and `event-bus.ts` at the current `main`):
+
+- The complete set of **built-in** Pi tools is `bash | read | edit | write | grep | find | ls`.
+  Of those, only `bash`, `edit`, and `write` mutate files. `edit` and `write` are already covered; `bash` is reserved for Issue #4. **There are no additional built-in mutation tools to wire up.**
+- Extensions can register arbitrary tools via `pi.registerTool()`.
+  Their results arrive as `CustomToolResultEvent` through the same `tool_result` event we already subscribe to, with the shape:
+
+  ```ts
+  {
+    type: "tool_result";
+    toolName: string;                 // arbitrary
+    input: Record<string, unknown>;   // tool's args
+    details: unknown;                 // tool-specific payload
+    content: (TextContent | ImageContent)[];
+    isError: boolean;
+  }
+  ```
+
+  So extension-provided mutation tools already flow past our `tool_result` handler — we just don't recognize their names or know which input field carries the path(s).
+- Pi exposes a shared `pi.events: EventBus` with a stable `emit(channel, data)` / `on(channel, handler)` shape.
+  This means we can subscribe to a documented channel without coordinating any new public API on Pi's side.
+
+The extension architecture is already compatible with new mutation sources — `TouchedFilesQueue` accepts a list of `MutationSourceHandler`s and applies scope filtering and dedupe centrally.
+The work is in *declaration* and *subscription*.
+
+Relevant existing pieces:
+
+- `src/touched-files-queue.ts` — `MutationSourceHandler` registry, central path normalization and scope filtering.
+- `src/extension.ts` — assembles the handler list inside `createDefaultAutoformatter` and wires the `tool_result` event.
+- `src/formatter-config.ts` / `src/config-loader.ts` — config shape and precedence.
+- `src/shell-mutation-detector.ts` — example of a config-driven handler factory; the new work mirrors its structure.
+
+## Design Overview
+
+Two complementary, independent mutation sources.
+Either can be used without the other.
+Both feed the existing `TouchedFilesQueue` through new `MutationSourceHandler`s, so scope filtering, dedupe, and prompt-end batching are unchanged.
+
+### Source 1: Config-declared custom tools (default off, primary path)
+
+Users declare which non-built-in tools mutate files and where the path(s) live in the `input` payload:
+
+```jsonc
+{
+  "customMutationTools": [
+    { "toolName": "mcp_files_write", "pathField": "path" },
+    { "toolName": "mcp_files_move", "pathField": "destination" },
+    { "toolName": "codemod_apply",  "pathFields": ["target", "extraTargets"] }
+  ]
+}
+```
+
+Field semantics:
+
+- `toolName` (string, required): exact match against `event.toolName`.
+- `pathField` (string, optional): single dotted path into `event.input`.
+  Resolves nested fields, e.g. `"args.path"`.
+- `pathFields` (string[], optional): multiple dotted paths.
+- For both forms, the resolved value may be a string or a string array; string arrays are flattened.
+  Non-string scalars (numbers, booleans, null) are ignored. `pathField` and `pathFields` differ only in arity, not in value handling — a tool whose field is sometimes a string and sometimes a string array should not require switching keys. *(Refined during test-first implementation: the original draft made `pathField` string-only, which would have forced users to switch to `pathFields` for any tool with a variadic field.
+  Unifying value handling removes that foot-gun.)*
+- Exactly one of `pathField` / `pathFields` is required.
+  Specifying both is a config validation error.
+
+Recognition rules:
+
+- Only act on `tool_result` events whose `isError === false`.
+- Built-in tool names (`bash`, `edit`, `write`, `read`, `grep`, `find`, `ls`) are rejected at config load with a validation issue. `edit` and `write` are already covered; the others are not mutating tools and declaring them would be a configuration mistake.
+- Duplicate `toolName` entries are an error at config load.
+- Per-handler output is fed into the queue, which applies the standard `formatScope` filter and dedupe.
+  No new path-handling logic is added.
+
+This covers the common, declarative case (MCP file servers, simple codemod tools, "rename" tools, etc.) without code changes.
+
+### Source 2: EventBus channel (opt-in, dynamic case)
+
+For tools that compute touched paths dynamically — codegen that emits N files, batch operations, tools whose `input` does not contain the written paths — extensions can emit on a documented channel:
+
+```ts
+// In another extension:
+pi.events.emit("autoformat:touched", { path: "src/generated/api.ts" });
+// or:
+pi.events.emit("autoformat:touched", {
+  paths: ["src/a.ts", "src/b.ts"]
+});
+```
+
+Channel contract:
+
+- Channel name: `autoformat:touched`.
+- Payload: `{ path: string }` or `{ paths: string[] }`.
+  Other shapes are ignored silently (no warnings — this channel is best-effort and we must not log on every emission from misconfigured peers).
+- Paths follow the same normalization and scope rules as every other source.
+  Out-of-scope paths are dropped silently.
+- Emissions are accepted at any time during a session; queued paths are flushed at the next prompt-end (consistent with the default timing model).
+
+Subscribing is feature-flagged in config (default on once the feature ships) so users can disable it if a peer extension misbehaves:
+
+```jsonc
+{
+  "eventBusMutationChannel": {
+    "enabled": true,
+    "channel": "autoformat:touched"
+  }
+}
+```
+
+Defaulting to *on* is acceptable here because the channel is a no-op unless a peer extension actually emits on it.
+The `channel` override exists for testing and for the rare case of a name collision.
+
+## Configuration
+
+New top-level keys, both extension-owned (per AGENTS.md):
+
+```jsonc
+{
+  "customMutationTools": [],
+  "eventBusMutationChannel": {
+    "enabled": true,
+    "channel": "autoformat:touched"
+  }
+}
+```
+
+Precedence: project overrides global (existing behavior).
+For `customMutationTools`, project replaces global wholesale (consistent with how arrays are currently merged elsewhere — confirm and document).
+
+Aligned updates required (per AGENTS.md):
+
+- `schemas/pi-autoformat.schema.json`
+- `docs/configuration.md`
+- `README.md`
+- TypeScript config types in `src/formatter-config.ts`
+- Loader and validation in `src/config-loader.ts`
+
+## Code Changes
+
+1. **Config**
+   - Extend `UserFormatterConfig` and `AutoformatConfig` in `src/formatter-config.ts` with `customMutationTools` and `eventBusMutationChannel`.
+   - Defaults: empty array, channel enabled with the documented name.
+   - Loader validation in `src/config-loader.ts`:
+     - Reject built-in tool names.
+     - Reject duplicate `toolName` entries.
+     - Require exactly one of `pathField` / `pathFields`.
+     - Validate dotted-path strings are non-empty.
+
+2. **New module: `src/custom-mutation-tools.ts`**
+   - Pure function `extractPathsFromInput(input, fieldSpec)` that resolves dotted paths and flattens string arrays.
+   - Factory `createCustomToolHandler(spec): MutationSourceHandler`.
+   - Factory `createCustomToolHandlers(specs[]): MutationSourceHandler[]`.
+   - No I/O; fully unit-testable.
+
+3. **Extension wiring (`src/extension.ts`)**
+   - In `createDefaultAutoformatter`, append handlers from `createCustomToolHandlers(config.customMutationTools)` to the existing handler list, after `writeOrEditHandler` and before the bash detector.
+   - Order is irrelevant for correctness (queue dedupes) but stable ordering keeps tests deterministic.
+
+4. **EventBus subscription**
+   - Accept the `EventBus` (or a small adapter) through `ExtensionApiLike` so it can be stubbed in tests.
+     Today `ExtensionApiLike` only exposes `on` for the lifecycle events; we add an optional `events` field and tolerate its absence.
+   - At session start, if `eventBusMutationChannel.enabled`, subscribe to the configured channel and forward valid payloads via `autoformatter.addTouchedPath(...)`.
+     Unsubscribe on `session_shutdown`.
+   - Payload validation lives in a small pure helper for testing (`parseTouchedPayload(unknown): string[]`).
+
+5. **No changes** to `formatter-executor`, `prompt-autoformatter`, or reporting.
+   Both new sources surface through the existing prompt-end summary.
+
+## Testing
+
+Per AGENTS.md, focused tests:
+
+- `extractPathsFromInput`
+  - top-level string field → `[value]`
+  - nested dotted path resolves
+  - missing field → `[]`
+  - non-string value → `[]` (no coercion)
+  - `pathFields` with a string-array value flattens
+  - `pathFields` with mixed string + string-array entries flatten
+- `createCustomToolHandler`
+  - matching `toolName` produces paths
+  - non-matching `toolName` produces `[]`
+  - errored tool result is not handled (handler is wired only to successful results in the extension layer; assert at the wiring level)
+- Config loader
+  - rejects built-in tool names with a clear validation issue
+  - rejects duplicate `toolName`
+  - rejects entries with both / neither of `pathField`/`pathFields`
+  - rejects empty / non-string dotted paths
+  - project `customMutationTools` replaces global (does not merge)
+  - defaults: empty array, channel enabled
+- `parseTouchedPayload`
+  - `{ path: "x" }` → `["x"]`
+  - `{ paths: ["a", "b"] }` → `["a", "b"]`
+  - `{ paths: ["a", 1, null] }` → `["a"]` (drops non-strings)
+  - unknown shape → `[]`
+  - non-object → `[]`
+- Extension integration (`extension.test.ts` style)
+  - declared custom tool's `tool_result` event populates touched files and triggers prompt-end formatting
+  - paths outside `formatScope` are dropped (delegated to existing queue behavior; one regression test is enough)
+  - EventBus emission feeds the queue and survives across multiple prompts
+  - disabling `eventBusMutationChannel.enabled` prevents subscription
+  - missing `pi.events` does not throw (graceful degrade)
+
+## Rollout
+
+1. Land config schema + loader validation with empty defaults; no behavior change.
+2. Land `extractPathsFromInput` and `createCustomToolHandler` with unit tests.
+3. Wire custom-tool handlers into `createDefaultAutoformatter`.
+4. Add EventBus subscription, gated on the new config flag and on `pi.events` being present.
+5. Documentation pass: `docs/configuration.md`, `README.md`, schema, and a short "integration guide for other extensions" snippet covering both sources.
+6. Update `docs/plans/0001-initial-implementation-plan.md` to reference the new mutation sources.
+
+## Open Questions
+
+- Do we want to expose **details-based** extraction in addition to `input`-based (e.g., `detailsField`)? Some custom tools may report written paths in `event.details` rather than `event.input`.
+  Likely yes, but the schema would mirror `pathField`/`pathFields`.
+  Defer unless a real consumer needs it; easy to add later.
+- Should the EventBus payload also accept `{ paths: string }` (singular in the plural key)? Probably no — keep the contract strict and documented.
+- Should we provide a tiny "testing helper" module that other extensions can import to construct valid payloads? Out of scope for this issue; the contract is small enough to inline.
+
+## Explicitly Deferred
+
+- **Programmatic registration API** (e.g., `pi-autoformat.registerMutationSource(handler)`).
+  The EventBus channel covers the dynamic case without locking us into a stable TypeScript API surface.
+  We can add a typed wrapper module later if real-world usage shows it is needed.
+- **Tool-name pattern matching** (regex / glob over `toolName`).
+  The current MCP naming conventions are stable enough that exact match is sufficient.
+  Patterns can be added without breaking the existing schema.
+- **Auto-discovery from tool schemas.** Several MCP tools advertise a `path: string` parameter, and we could heuristically opt them in.
+  This is exactly the "implicit, surprising" behavior AGENTS.md warns against; keep declarations explicit.
+
+## Checkpoints / Commits
+
+Following Conventional Commits:
+
+- `feat(config): add customMutationTools and eventBusMutationChannel schema`
+- `feat: extract touched paths from declared custom tool inputs`
+- `feat: subscribe to autoformat:touched event-bus channel`
+- `docs: document custom mutation tool integration`
+- `test: cover custom mutation tool handlers and event-bus subscription`