Feature request: source-free per-file mutation callback for provenance integrations #339

Motivation

The public notify setting reports task completion, but does not identify the file mutation or tool call that made an edit. A supported, source-free callback from the direct file-mutation path would let external integrations correlate an edit with a saved file transition without reading prompts, transcripts, model output, or private file-history data.

Proposed contract

Please consider an optional executable setting, for example fileMutationNotify, invoked for direct write/edit/apply-patch mutations. The callback could receive a bounded JSON object on standard input:

{
  "schema_version": 1,
  "phase": "before|after|failure",
  "project_root": "/absolute/worktree",
  "path": "relative/file.txt",
  "session_id": "opaque-session-id",
  "tool_call_id": "opaque-call-id",
  "tool": "write|edit|apply_patch",
  "success": true
}

Suggested semantics:

• Emit before immediately before the direct mutation and after only once the final saved bytes exist.
• Emit failure for an admitted mutation that fails or is cancelled, so consumers do not infer a successful edit.
• Keep path relative to project_root after Deep Code's own path-containment check. Use bounded opaque correlation IDs; a 256-byte limit per ID and a 16-KiB payload limit would be sufficient for this use case.
• Exclude source text, patches, prompts, tool arguments/results, credentials, and model response text.
• Run callbacks asynchronously with a short timeout and bounded queue. Report callback failures in diagnostics without blocking or changing the user's edit result.
• Document which CLI and VS Code companion edit paths invoke the callback. Shell, MCP, and external-process writes should not be presented as direct Deep Code mutations unless they have their own explicit lifecycle evidence.

A small test fixture covering direct edits, failure/cancellation, concurrent edits, timeout, and queue overflow would make the contract easier for downstream integrations to qualify. This is a feature request, not a claim that the callback is currently available.