Diff entrypoints and command routing
Overview
The diff mod is packaged as a Claude plugin by mods/…/plugin.json, which names the plugin diff and describes the /diff pane behavior users see. Runtime hook loading starts at mods/…/hooks.json: it declares ./register.ts as the only hook module, so mods/…/register.ts is the orchestrator for every user-facing entry into the diff subsystem. mods/…/README.md is the behavioral contract for that orchestrator: /diff toggles the pane or dialog, first edits may open it automatically, open panes refresh after edits and shell commands, and an ask button can attach one file's hunks to the next prompt.
mods/…/register.ts binds the engine during session.start. The bind helper wraps $ into a Host object, records the session start time from $.session.usage().startedAt when isRecord accepts that usage object, stores the session cwd for later git processes, and calls $.command.register(COMMAND_SPEC). COMMAND_SPEC comes from mods/…/command-spec.ts and uses Names.COMMAND_NAME (diff) plus Names.COMMAND_DESCRIPTION (Toggle the diff panel showing uncommitted changes). If command registration is refused with the built-in ownership message matched by mods/…/builtin-holds-pattern.ts, register.ts leaves host unset and the plugin stands down; if another registration error occurs, it writes Names.registerFailedTextOf(...) to $.ui.log so the transcript says the panel is unavailable.
The main /diff route is the command.run hook in mods/…/register.ts filtered to { command: 'diff' }. It drops overlapping toggles with the isToggling guard, pins a git backend on first open, and then uses PaneToggle.paneToggleOf to choose open, close, or too-narrow from the current pane belief and the command presentation. Opening calls openPane, which may fetch diff data before seating a docked pane, opens pane id Names.PANE_ID (diff) with title Names.PANE_TITLE (Diff), and returns transcript text from the name constants: Diff panel shown, Diff panel hidden, Diff dialog dismissed, Nothing here can draw the diff panel yet; it opens as soon as something can, Resize your terminal to at least 110 columns to show the diff panel, or the git/no-repository messages. Once a docked pane is placed, register.ts registers DOCKED_COMMAND_SPEC from mods/…/docked-command-spec.ts, which is the same command spec with immediate: true so /diff can close the docked pane even during an active turn. Inline/dialog usage keeps the normal, non-immediate spec because that dialog takes keyboard focus.
Other user-facing routes in mods/…/register.ts feed the same pane state. ui.render for PromptHint records viewport width and fullscreen/docked capability, which gates automatic first-edit opens. ui.render for Pane resolves engine UI primitives, verifies requestId === Names.PANE_ID, marks an awaited open as shown, updates placement and body dimensions, and delegates drawing/actions to Views.paneView. ui.close either backs an inline dialog out of detail view or records a person close and persists Names.STORE_OPEN_KEY (open) as false for docked panes. ui.scroll owns docked pane body/list scrolling. ui.focus is filtered by Names.PLUGIN_NAMES (diff and cc-plugin-diff) so focus events stamped with either plugin name can keep the inline dialog's selected file centered.
Edits and commands enter through the tool.call hook in mods/…/register.ts, filtered to the tool constants in mods/…/editing-tools.ts (Edit, Write, NotebookEdit) and mods/…/shell-tools.ts (Bash, PowerShell). afterTool increments the landed-change counter for successful edits or shell calls that mods/…/may-have-written.ts does not mark read-only. Landed changes refresh an already seen pane; a main-loop edit with no agentId can trigger the first automatic open, while any later landed change can retry an automatic open that previously found nothing to show. /clear and /resume are also routed through command.run in register.ts: after the underlying command completes, they unpin repository state, clear ask state and queued refresh state, reset the model, and either keep an open pane across /clear with a fresh read or close/reopen for restored /resume turns.
The ask route starts in pane actions inside mods/…/register.ts: toggleAsk calls Ask.armedAskOf from mods/…/armed-ask-of.ts, which turns one file path plus its hunks into an ArmedAsk with a provenance line and unified hunk text capped at Limits.MAX_LINES_PER_FILE. The selected path is stored in model.armedPath, and $.ui.status tells the user that the file will ride the next prompt. On prompt.submit, register.ts computes remaining prompt-context room, calls Ask.fittedAskTextOf from mods/…/fitted-ask-text-of.ts, and appends the ask text to e.context if it fits. If it does not fit even past the first hunk line, the ask is dropped, the status explains that the diff did not fit, and the prompt continues without extra context. When an ask is attached and the prompt is accepted, Record.recorderOf(...).asked() logs diff_selection_attach, then the ask is disarmed so it is one-shot.
Small helper modules under this doc's scope keep the routes defensive and user-facing text stable. mods/…/message-of.ts converts any caught value to text before regex matching built-in command ownership or printing registration errors. mods/…/is-record.ts is used in register.ts and in the direct dependency mods/…/open-outcome-of.ts to safely inspect engine-returned objects such as session usage and $.ui.open results. mods/diff/hooks/names/** centralizes command names, pane IDs, store keys, plugin names, and transcript/status strings so tests can assert exact built-in-compatible wording.
The bootstrap tests under mods/diff/tests/** are broad, but the routing coverage is concentrated in mods/…/register.test.ts, mods/…/fitted-ask-text-of.test.ts, and fixtures such as mods/…/diff.ts, mods/…/dialog-diff.ts, mods/…/diff-at.ts, mods/…/read-only-answer.ts, mods/…/typed-prompt-of.ts, and mods/…/unsaid-hint.ts. Those tests assert that startup runs no git, built-in /diff ownership makes the plugin idle, docked opens re-register /diff as immediate, too-narrow/fullscreen/dialog command presentations produce the expected answers, read-only shell commands do not refresh, automatic opens are gated by viewport and checkpointing, no-surface opens are kept until drawn, and ask context is attached or dropped according to prompt room.
Coverage/routing
mods/diff/.claude-plugin/**: plugin metadata; currently plugin.json names/describes the plugin.- mods/…/README.md: user-facing behavior and hook/event contract for the diff pane.
- mods/…/hooks.json: hook loader entry that points at register.ts.
- mods/…/index.ts: barrel export for the diff hook package, including register.js and helper modules.
- mods/…/register.ts: central hook registration and routing for
/diff, render/close/scroll/focus events, edit/shell refresh triggers,/clear,/resume, and prompt ask attachment. mods/diff/hooks/command-spec/**:/diffcommand specs, including the docked immediate variant.mods/diff/hooks/ask/**: armed ask shape, ask text construction, and prompt-context fitting/cut note.mods/diff/hooks/message-of/**: caught-value-to-message helper used by registration/probe error handling.mods/diff/hooks/names/**: command/pane/store identifiers and exact user-facing strings.mods/diff/hooks/is-record/**: object-shape guard used before reading engine-returned records.mods/diff/tests/**: tests and fixtures that exercise the routing, command presentation, automatic open, refresh trigger, and ask flows.
Coupling
- If
Names.COMMAND_NAMEin mods/…/command-name.ts changes, update the literal filters in mods/…/register.ts and the test fixtures in mods/…/diff.ts, mods/…/dialog-diff.ts, and mods/…/diff-at.ts; the engine dispatchescommand.runby command name, andCOMMAND_SPECalone does not retarget the hook filter. - If pane id or plugin stamp values change in mods/…/pane-id.ts or mods/…/plugin-names.ts, verify mods/…/register.ts render/close/scroll/focus filters and tests that press
ask:<path>; pane rendering is selected byrequestId, while inline dialog focus events are accepted only for those plugin names. - If the engine changes
$.ui.openreturn shape, update mods/…/open-outcome-of.ts and theopenPanebranches in mods/…/register.ts;no-surfaceopens are intentionally kept and later marked shown, while other unplaced opens are withdrawn and closed. - If command presentation fields change, update
togglePanein mods/…/register.ts and fixtures such as mods/…/diff.ts;/diffusespresentation.isFullscreenandpresentation.columnsto choose docked pane vs inline dialog and to enforce the 110-column minimum. - If tool result semantics change, update mods/…/may-have-written.ts together with
afterToolin mods/…/register.ts; the plugin treats missingisReadOnlyas maybe-writing and will refresh on failed/interrupted shell calls unless the result is denied or explicitly read-only. - If prompt context limits or ask formatting change, update mods/…/armed-ask-of.ts, mods/…/fitted-ask-text-of.ts, and the
prompt.submithook in mods/…/register.ts together; the hook subtracts existing context length before fitting the ask text, and the helper returnsundefinedwhen there is not enough room for a useful body. - If
$.session.usage()stops returningstartedAtas a plain object field, adjuststartedAtOfin mods/…/register.ts; it depends on mods/…/is-record.ts before readingstartedAt, and that timestamp separates session changes from pre-session changes.
Risks
- mods/…/register.ts has many interacting asynchronous gates (
isToggling,probing,isRefreshing,isRefreshQueued,isOpenAskKept,awaited,pin.epoch, andpersonCloses). If one branch stops checking the epoch or close count, a stale automatic open can seat a pane after/clear,/resume, or a person close. mods/…/register.test.ts carries many regression cases for these races, and history shows repeated routing fixes around automatic open/read timing, including2287e5d,92ec78f, and7974a70. - mods/…/register.ts relies on exact built-in-compatible engine wording for standing down (
Names.BUILTIN_HOLDS_PATTERN) and for awaited no-surface opens viaopenOutcomeOf. If the engine changes these strings without updating mods/…/builtin-holds-pattern.ts or mods/…/open-outcome-of.ts, the plugin may either log an alarming registration failure while the built-in owns/diff, or withdraw a pane that should wait for a future surface. - mods/…/docked-command-spec.ts intentionally changes
/difftoimmediate: trueonly after a docked pane is placed. If that registration moves earlier or starts applying to inline dialogs,/diffcan run during turns when permission prompts need the keyboard; if it is omitted, users cannot close an auto-opened docked pane until the turn ends. mods/…/register.test.ts has an explicit "once docked" assertion for this transition. - mods/…/fitted-ask-text-of.ts counts JavaScript string lengths against
Limits.PROMPT_CONTEXT_MAX_CHARS, not tokens or display cells. If prompt context accounting changes elsewhere, this helper can either drop useful asks too aggressively or attach text that the engine later rejects; keep the fitting tests in mods/…/fitted-ask-text-of.test.ts aligned with the engine's context contract.