DSH plugin deliverables: present, PresentedFile and diffs

A DSH plugin's "deliverables" are really two independent channels: files the model explicitly declares through present, and files actually changed during the turn. The first comes from a tool call; the second comes from comparing git worktree snapshots at turn start and turn end, with paths git cannot cover filled in by whole-file captures around each file-tool edit. Both are announced by log-only events, but the crucial difference is that the summary itself is not in the log — the Host serves it while the session is alive. That explains a familiar surprise: after a Host restart, earlier turns in a reopened conversation have no change cards.

DSH plugin deliverable channels: declaration and change

Bottom line: present covers "what I delivered," workspace/changes covers "what this turn modified," and neither substitutes for the other.

1. Both are read-only: clients read and render them at turn end; the server never uses them to alter model context.
2. They do not overlap: a declared but unmodified file appears only in presented; a modified but undeclared file appears only in the change summary.
3. Do not treat the event as data: workspace/changes carries only turn; ask the Host for the summary.

DSH plugin PresentedFile: present lands in the event

Bottom line: each successful present appends one event with turn, call id and files; content stays at the source path.

interface PresentedFile {
  path: string          // absolute or relative to the session cwd
  description?: string
}

1. Write timing: the event is appended only when the present call's final result succeeds.
2. Content is not moved: the declaration registers a path; the file stays where it is.
3. One call, one event: { turn, callId, files }, with callId identifying the model's tool call.
4. Good fits: reports, screenshots, exported tables — "please look at this artifact."
5. Bad fits: use the change summary for "which files I modified," not present.

DSH plugin change sources: git snapshots plus whole-file captures

Bottom line: with git, compare turn-start and turn-end worktrees; without it, use before/after file-tool captures, then merge.

1. Git path: compare turn-start and turn-end worktree snapshots for changed files and line counts.
2. Non-git path: whole-file captures before and after each file-tool edit fill the gap.
3. Display label: relative inside the working directory, ../ above it, ~ under home, otherwise absolute, always slash-separated.
4. Special markers: binary when git reports binary or a capture side holds a NUL byte; oversized when one side exceeds maxFileBytes.
5. Caps: files sorts by display and caps at maxFiles, while total, added and deleted still count every file.
6. Snapshot ids: snapshot.before and snapshot.after are git tree ids, absent when no snapshot was taken.

DSH plugin summary access: summary and diff

Bottom line: ask the Host by event seq; diffs are computed per file index and disappear when the session is released.

const summary = ctx.workspaceChanges.summary(sessionId, seq)
const diff = await ctx.workspaceChanges.diff(sessionId, seq, index, signal)

1. Summary conditions: the session is alive and this Host recorded the event; otherwise undefined.
2. Diff inputs: event seq plus the file's index in files, returning text, binary or oversized.
3. Text shape: hunks in file order, empty when both sides match; coarse becomes true when comparison exceeds the timeout and every line shows as replaced.
4. Binary and oversized: no line content, only path and display.
5. Failure semantics: snapshot read failures on a live session throw rather than returning an empty diff.

DSH plugin event boundaries: not in model requests, summaries are not durable

Bottom line: neither event enters model requests, and summary availability depends on the Host — a design boundary, not a bug.

1. Invisible to the model: deliverables/presented and workspace/changes never enter model requests.
2. Rendered at turn end: the Web deliverables plugin renders both channels together.
3. Restart boundary: after a Host restart, earlier turns lose their change cards because summaries were never persisted.
4. Same-turn supersession: later events replace earlier ones and clients keep the latest.
5. Need durability? Copy the summary into your own storage, such as a StorageBackend.

DSH plugin deliverable troubleshooting

Bottom line: separate not recorded, recorded but empty, and gone after restart.

1. Declared but not shown — check that present's final result succeeded; failures append nothing.
2. Files changed but the list is empty — confirm changes happened in the top-level turn and check maxFiles.
3. Line counts missing — the file was marked binary or oversized.
4. Summary is undefined — the session was released or this Host never recorded the event.
5. Everything shows as replaced — coarse is true because comparison exceeded diffTimeoutMs.
6. Repair status, stated honestly: the two channels, field definitions, summary serving and restart boundary follow the official Deliverables page and the two package READMEs; configuration keys are defined by those packages.

Sources: Deliverables, tool-present README, workspace-changes README.