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

[zaferulgur]

Deep Code Source-Free Mutation Callback Proposal

Status: upstream-ready design; not a shipped or qualified GitVia adapter
Reviewed: 2026-09-09

Verified upstream boundary

The installed @vegamo/deepcode-cli release remains 0.3.1. The maintained
lessweb/deepcode-cli main branch resolved to
4023a59eea58a992552c6ff17d9a6139a9f6d093 during this review. Its Core runtime
still invokes internal onBeforeFileMutation(filePath) and
onAfterFileMutation(filePath) callbacks from direct mutation handlers. The
public notify setting remains task-completion-only and cannot identify the
file or tool call that performed an edit.

GitVia must not use task-duration correlation, private Deep Code file-history
repositories, transcript databases, prompt text, model output, or a patched
installed bundle. Those approaches create false positives or an unsupported
maintenance and privacy boundary.

Proposed supported contract

Deep Code should expose an optional executable setting named
fileMutationNotify. Core should invoke it asynchronously after its own
before/after checkpoints, with 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
}

The callback must not contain source, patches, prompts, tool arguments, tool
results, tokens, credentials, or model response text. path must be relative
to the declared project root after Deep Code's own containment check. IDs are
opaque correlation values and should be bounded to 256 bytes. The complete
payload should be bounded to 16 KiB.

The before event must run immediately before the direct file mutation. The
after event must run only after the final saved bytes exist. A failure event
must close an admitted before event without claiming an edit. Callback failure
must be visible in Deep Code diagnostics but must not block or change the user's
edit result. A short timeout and a bounded single FIFO worker prevent process
fan-out; no per-repository daemon is required.

GitVia consumption

Once this contract is released upstream, GitVia can install a reviewed command
that maps the three phases to its existing adapter before, adapter after,
and adapter fail interface. GitVia computes saved-byte hashes locally, joins
the callback to the OS-observed transition, stores only source-free
fingerprints/ranges, and preserves unmatched or ambiguous writes as unknown.
The VS Code companion must be tested separately even if it shares Core.

Acceptance matrix

An adapter may move from os-git-only only after all of these pass on a pinned
released version:

1. Five isolated CLI direct-write/edit runs produce exact signed envelopes.
2. Five isolated VS Code companion direct-write/edit runs do the same.
3. A failed/cancelled mutation produces no AI line credit.
4. Shell/MCP/external-process writes remain unknown unless their own explicit
   contract supplies a path and matching lifecycle.
5. Concurrent human modification between before and after never becomes exact
   AI credit; proved lineage may be hybrid, otherwise unknown.
6. Callback timeout, malformed input, queue overflow, disabled configuration,
   and process-launch failure appear in loss counters.
7. Persisted GitVia state, support bundles, reports, and process arguments
   contain no source or prompt text.
8. Idle/resource measurements retain the one-resident, zero-polling, and
   working-set targets.

Until upstream accepts and releases an equivalent contract, Deep Code remains a
mandatory Tier-1 release blocker and OS/Git-only in the product matrix.