# Task Delta Behavior ## Purpose Pi Task Delta reports repository changes without placing its summary entries in model context. It measures one Pi task from `agent_start` through `agent_settled`, including retries and queued work. From the overlay, the user can explicitly request isolated model analysis of what changed and why one selected file likely changed. The compact view shows total files and lines: ```text 5 files changed +34 -329 (F6 for details) ``` Press `F6` to browse task history on the active session branch, initially selected on the newest task. Run `/git-summary` if the terminal does not send the function key. ## Installation Install the latest release from npm: ```bash pi install npm:pi-task-delta ``` Pin an exact release in managed configurations that require reproducible installs, for example `npm:pi-task-delta@0.3.4`. ## Diff overlay The overlay has three persistent panes: task history on the left, changed files in the middle, and the selected file's detail on the right. The divider labels all three panes, brackets the focused pane, and accents that column's border with the theme's warm heading color. A selected task or file uses the stronger selection background when its pane is focused and a subtler secondary background otherwise; selected-row text consistently uses the normal theme text color instead of changing with focus. The history retains the newest 200 valid summaries from the active session branch and displays each task's local `HH:MM` time, file count, insertions, and deletions. It opens on the newest task. Its top header centers `[ DIFF ]`, `[ EXPLANATION ]`, or `[ RATIONAL ]` to make the active detail view explicit. It shows added, deleted, and context lines with their old and new line numbers. Generated explanations and rationales wrap at word boundaries; only a single token wider than the detail pane is split. Unchanged regions outside each hunk are omitted; each hunk includes three surrounding context lines. Controls are focus-aware: - Left or Right: cycle focus through task history, changed files, and detail. - `Tab` or `Shift+Tab`: cycle focus forward or backward through the three panes. - Up or Down: select a task, select a file, or scroll detail according to the focused pane. - Page Up or Page Down: move the focused pane by one visible page. - Home or End: move the focused pane to its first or last item. - Selecting another task cancels active generation, selects that task's first changed file, and returns to `[ DIFF ]`. - `D`: show the selected file's stored diff. Switching to it cancels active model generation. - `E`: generate or show the most recent technical explanation of what changed for the selected file. - `W`: generate or show why the selected file likely changed. - `R`: explicitly regenerate whichever generated view is active with the currently configured model and effort. - Switching between `E`, `W`, and `D` cancels generation in the view being left. - The upper-right header identifies the model and effort that produced the visible analysis, while the bottom-right footer shows the currently configured model and effective effort. - Enter, Escape, `Ctrl+C`, or `F6`: close the overlay and cancel any active model request. The overlay uses up to 90% of the terminal height and adjusts its visible task, file, and detail rows when the terminal is resized. Long diff source lines are truncated instead of wrapped so one source line remains one overlay row; generated prose wraps within the detail pane. The component preserves the supplied terminal width. Very narrow terminals show a request to widen the terminal rather than rendering an invalid layout. Binary changes remain in the sidebar but do not show textual content. Mode-only changes report that no textual hunks are available. Entries created by versions before patch persistence remain readable and explain that no stored patch is available. ## File explanations Pressing `E` sends the selected file's stored task diff and aggregate metadata through Pi's effective provider for the configured explanation model, including native or custom providers. A Pi-style Braille spinner displays `Working...` with elapsed time, and available response text streams into the explanation pane as it arrives. The request is isolated: it does not include the conversation, create a user or assistant turn, or add the explanation to model context. Source content is treated as untrusted data, and the response is validated and normalized into concise sections covering what changed, behavioral impact, and notable risks. An explanation is generated only after explicit input. The response is cached by task summary, file, model, and effort as a separate custom entry in the local Pi session and restored with that session. It does not disappear when another task finishes. Changing the configured model or effort does not automatically trigger another request: reopening the file continues to show its most recently generated explanation and the upper-right `Produced by` label identifies how it was produced. The lower footer separately reflects the current configuration that `R` will use. Press `R` to generate a replacement view with the current configuration. Older generated versions remain in the append-only session data, while the overlay shows the newest one. Starting a different session does not make explanations from the old session available unless that session is resumed. The selected model provider receives the filename, line counts, and available stored diff, which may contain repository content. Binary, metadata-only, and omitted diffs can still be explained from their limited metadata, but the model cannot recover lines that were not stored. ## Why rationales Pressing `W` makes a separate, explicit model request. It receives only the bounded original task-starting text prompt, the selected file's metadata and stored diff, and bounded metadata for the task's changed-file list. It does not receive the rest of the conversation, attached image contents, tool calls, assistant responses, or unchanged repository files. The task request and repository data are treated as untrusted evidence rather than model instructions. The response is validated into four sections: stated intent from the supplied request, objective evidence from the changes, likely inferred rationale, and uncertainty. This distinction prevents an inference from being presented as known developer intent. If a restored legacy summary has no stored task request, the rationale explicitly reports that the request is unavailable and limits itself to the Git evidence. Task Delta stores a bounded copy of the task-starting text prompt in a hidden custom Pi session entry associated with the specific history task and Git summary hash. The entry is limited to 16 KiB, does not participate in model context, and follows the same session branch and deletion lifetime as the summary. Rationale responses are cached independently from technical explanations. Changing model settings preserves the visible rationale until `R` explicitly regenerates it. ## Analysis settings Run `/task-delta-settings` to configure explanation and rationale requests. The model setting defaults to **Current Pi model** and can instead be fixed to any model currently available through Pi's configured providers. The effort setting defaults to **Current Pi effort** and can instead be fixed to `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Pi clamps unsupported effort levels to the model's nearest supported level; the footer and cache use that effective effort. Press `S` to save changes or Escape to cancel them. Preferences apply globally across repositories and sessions. Legacy explanation entries without effort metadata are regenerated once under the newer cache identity. Preferences are stored in `~/.pi/agent/pi-task-delta.json`, or under the directory selected by `PI_CODING_AGENT_DIR`. The file contains only the model provider/id and effort preference; it does not contain API keys or other credentials. If a fixed model later becomes unavailable, model analysis asks the user to select another model. ## Snapshot behavior The extension creates a Git tree snapshot when a task starts and another snapshot after Pi finishes retries and queued work. It compares these trees to get the net task result. Each snapshot uses a temporary Git index. The extension does not change the repository index or working tree. The snapshot records current tracked and non-ignored untracked file content, including staged and unstaged changes. It does not record index-only state when the working content matches the baseline. The baseline contains changes that existed before the task. The final comparison excludes those unchanged baseline differences. A commit during the task does not remove a change from the summary. Patches are generated directly between blob object IDs from the immutable baseline and final trees. Patch extraction does not delay the next task's queued baseline snapshot. External diff drivers, text conversion, color output, ambient inter-hunk settings, submodule-ignore settings, and rename detection are disabled. Blob-based extraction avoids reusing filenames as pathspecs and preserves paths whose raw bytes are not valid UTF-8. The extension stores aggregate data and bounded patches as custom Pi entries. They render in the TUI but do not enter the model context. Stored patches allow the overlay to work after session restoration. Session entry types remain stable for backward compatibility; `/git-summary` and `F6` remain the command and shortcut for opening the history. ## Safety and limits - Snapshotting does not modify the real Git index or working tree. - The temporary index lives under Git's administrative directory, so a repository-local `TMPDIR` cannot be staged into a snapshot. - Snapshotting runs `git add -A` at each task boundary and can be slow in large repositories. - Git writes the snapshot trees and changed blobs as unreachable objects. Normal Git maintenance can remove them later. - The comparison reports net changes. Restoring the baseline content produces no summary. - Concurrent changes from another process can appear in the task result. - Renames appear as a deletion and an addition. - Submodules report the recorded commit change, not nested line counts. - General Git commands time out after 30 seconds and allow at most 10 MiB of output. - Patch collection has a five-second task budget and attempts at most 64 textual files. - Each explanation or rationale request includes at most 96 KiB of bounded input, is reduced for the selected model's context window, asks for at most 700 output tokens, and times out after 60 seconds. Rationale input budgets the task request, changed-file metadata, and selected diff within that shared limit. - A persisted explanation or rationale is limited to 32 KiB and remains outside model context. Restoration and live caching retain at most 4,096 generated analyses or 32 MiB per session branch. - The hidden task-request copy is limited to 16 KiB and remains outside model context except when the user explicitly presses `W` for the associated summary. - The history pane retains the latest 200 valid task summaries from the active session branch; switching branches rebuilds it from that branch only. - A stored patch is limited to 256 KiB after JSON encoding. - All stored patches for one task are limited to 1 MiB after JSON encoding. - A patch that exceeds a limit is omitted as a whole; aggregate file and line counts remain available. - Tabs and terminal control characters in paths or patch content are rendered as safe visible text. Repository content cannot inject terminal escape sequences through the overlay. ## Validation Run: ```bash npm run typecheck npm test ``` The regression test covers committed and uncommitted task changes, stored unified patches, explanation and rationale prompting, task-request association, explicit regeneration, streaming, cancellation, restoration, model/effort attribution, global settings persistence, literal pathspec filenames, patch parsing, terminal-control sanitization, binary and oversized patches, pre-existing changes, unborn repositories, index safety, overlapping task boundaries, compact rendering, task-history retention, three-pane focus and navigation, file navigation, narrow widths, shortcuts, commands, and overlays.