Agent integration — git-span docs

Once installed (see Getting started), the git-span plugin provides:

A touch hook — surfaces existing spans after supported reads and writes and repairs mechanically safe positional drift inline.
Static planning and lifecycle hooks — capture bounded pre-state for supported writes, deduplicate context, warm up the CLI, and clean up session state.
Four skills — git-span for declaration, inspection, and focused reconciliation; cover-commits for reviewing noted commits and consuming their notes after validated repairs; reconcile for multi-span triage; and hook-effect-analysis for measuring hook emissions.
An expert subagent where supported — Claude Code, Codex, and OpenCode ship one; Antigravity ships skills and hooks without a separate agent artifact.

The integrations use the same scriptable git span CLI available in a terminal or CI.

Touch hook

The touch pipeline observes supported file-affecting tools: Claude Code covers Read, Edit, Write, and Bash; Codex covers apply_patch and its shell/exec family; OpenCode covers bash, read, edit, write, and apply_patch; Antigravity covers run_command.

When a supported range intersects an existing anchor, the hook repairs mechanically safe positional drift and surfaces bounded context identifying the span, its anchors, and its why. Remaining semantic drift requires a decision about the coupled artifacts; see Reconcile drifted spans. Session deduplication suppresses context already shown with the same span status.

Shell attribution uses bounded literal command intent and post-state evidence. Static planning captures only the pre-state needed for supported operations. Unproven dynamic paths, unsupported syntax, and inconclusive failed writes stay silent. Failed commands can surface a write only when the supported parser provides decisive post-state evidence; interrupted calls suppress attribution.

A missing git span binary, timeout, failed scan, or unexpected CLI result injects nothing and does not block the tool.

Human edits, unsupported tools, and inactive hooks can bypass this coverage. Run explicit git span drift checks or use CI to verify existing spans across the repository.

Suppression

.span/.hookignore suppresses selected spans by path in touch context. It does not change CLI output or anchor resolution. A missing or unreadable file applies no suppression.

Codex specifics

Installing the plugin leaves hooks inactive until the user reviews and trusts them through /hooks; see Getting started. Hash-stable hook filenames preserve an existing trust decision across plugin upgrades.

Shell envelopes' workdir selects the effective repository for planning and attribution. Patch planning and post-tool handling preserve the affected ranges, including supported failure-event attribution. Context arrives through additionalContext.

OpenCode specifics

OpenCode loads the npm plugin in-process without a trust-review step. tool.execute.before captures shell and patch plans; tool.execute.after appends <git-span> context to tool output. Shell cwd frames and session lifecycle keep plans scoped to the correct repository and tool call.

Host-level failures such as invalid arguments, denied permission, or spawn errors never reach the after hook and receive no attribution. A numeric nonzero shell exit still reaches it, with exit-gated attribution; an exit: null result suppresses attribution like an interruption. The experimental execute tool is outside coverage. The plugin bounds its own CLI subprocesses because the host imposes no per-hook timeout.

Loading the plugin disables CLI update checks for the session. Set OPENCODE_GIT_SPAN_LOG_FILE to a path for JSONL hook diagnostics.

Antigravity specifics

Antigravity installs four skills and the workflow hooks without a marketplace or separate trust-review step. Empty PreToolUse responses mean denial on this host, so the retained pre-tool handlers return explicit allow decisions.

Only run_command has a pinned tool contract. Dedicated file-edit tools receive no touch attribution; explicit git span drift checks or CI verify their changes.

PostToolUse carries a step index rather than the original call or response. The plugin joins disk-backed pre-call state, queues rendered touch context, and delivers it after the invocation's tool batch as an ephemeral message. Successful calls provide no exit-code or response-derived read evidence. Failed calls never surface writes because there is no post-state evidence to verify.

The enforcement backstop

Touch hooks provide context during supported reads and writes. They do not check a complete changeset at commit, push, or status time. Human edits, inactive hooks, unsupported tools, and host-level failures can leave existing spans drifting. CI & git integration covers git span drift as the check before merge.