Integration companion - Agent Session Record

Companion draft, separately versioned. This document is non-normative with respect to the core format: a stream conforms to ASR whether or not any tool implements this companion. It uses “MUST” for requirements on tools that claim to implement it. Version: draft 0.1, for ASR format version 0.1.

This companion covers how sessions connect to commits, Git notes, and tools that export and discover sessions. These mechanisms are outside core conformance because they affect shared repositories and other people’s history.

Adoption levels

Level	What the harness does	What works
L0	Nothing. Third-party converters read its native logs.	Works today, without vendor help.
L1	Ships an export command and a discovery file (below).	Tools find and export sessions without reverse-engineering storage.
L2	Its native log is a conformant stream: the ASR envelope, with vendor record types and `_meta` for anything it does not normalize, at the destinations its registry entry documents (see Extensibility).	The harness writes records as the session happens, without conversion or a second log.

The `Agent-Session` trailer

A commit names the sessions that contributed to it with one Agent-Session trailer per session:

Fix empty input handling in parser

Agent-Session: claude-code:0f3c2a7e-91b4-4d6a-8c2e-5a7b3d1e9f04
Agent-Session-Url: https://sessions.example.com/s/0f3c2a7e
Agent-Session: goose:inst-4f9c2a:20261026_3

Rules:

The value of Agent-Session is a session reference in the core grammar (see Identity), optionally with a # record reference (for example the session’s vcs record for this commit). Nothing else follows the reference: no URL, no comment.
In a trailer, a tool MUST percent-encode every non-ASCII octet as well as the characters the core grammar requires, so that the value is printable ASCII. It SHOULD write the canonical form.
A commit MAY carry several Agent-Session trailers, one per session. A tool MUST NOT write the same session twice in one commit.
Agent-Session-Url is optional. Its value is an absolute URL where the session can be viewed. It MUST immediately follow the Agent-Session trailer for that session; readers associate the two because they are consecutive. A URL gives the session’s location rather than its identity and can move, expire or require access.
The trailer is written when the commit is made (for example by the agent’s commit command or a prepare-commit-msg hook). Code hosting services can rewrite messages on squash merges and drop trailers; the notes ref below can record links for commits that already exist.

Aliases

Several trailers in use today point to sessions or to other identifiers that can be resolved to sessions. Readers that build a commit-to-session index SHOULD recognize them, using each ID within the scope listed below.

Trailer	Written by	Value	ID scope	Resolution
`Agent-Logs-Url`	GitHub Copilot coding agent	URL of the session’s logs on GitHub	A hosted agent session (the UUID in the URL)	Direct session alias. Access-controlled; not present after a squash merge.
`Copilot-Session`	Copilot CLI	A session UUID	The cloud session ID, not the local session ID that resumes the session (copilot-cli #4130)	Direct alias of the cloud session. It maps to a local `copilot-cli` stream only through the vendor’s own mapping.
`Claude-Session`	Claude Code cloud and remote sessions	`https://claude.ai/code/session_<id>`	A cloud session	Direct alias of the cloud session. Often private and short-lived.
`Entire-Checkpoint`	Entire	A 12-hex or ULID checkpoint ID	An Entire checkpoint stored in Git	Not a session alias: resolve the checkpoint to its sessions first (see the Entire companion).

These trailers identify actors or tools, not sessions, and MUST NOT be treated as session references: Co-authored-by, Assisted-by (the Linux kernel’s AGENT_NAME:MODEL_VERSION [TOOL…] form), and Made-with.

The notes ref

For commits that already exist or whose trailers were lost, refs/notes/agent-sessions holds a note listing session references and digests. It never holds transcripts.

{
  "agentSessionNotes": "0.1",
  "sessions": [
    {
      "session": "claude-code:0f3c2a7e-91b4-4d6a-8c2e-5a7b3d1e9f04",
      "records": ["r20"],
      "digest": {
        "alg": "sha256",
        "value": "3f7a1c2e9b8d4f6a0e5c1b7d9a3f2e6c8b4d0a1f7e3c9b5d2a6f8e0c4b1d7a39"
      },
      "recordCount": 212
    }
  ]
}

Field	Meaning
`agentSessionNotes`	The version of this note format.
`sessions[].session`	A session reference, without a `#` part.
`sessions[].records`	References to the records in that session that relate to this commit (for example its `vcs` record). A `pr_link` record links a session to a pull request, not to a commit, and is not listed here.
`sessions[].digest`, `recordCount`	The stream digest and record count of the captured stream the note was written from. A digest identifies one captured prefix of the stream, not the session as a whole.
`sessions[].url`	Optional locator, as `Agent-Session-Url`.

Rules:

A note MUST NOT contain transcript content, prompts, paths, or digests of low-entropy values (see Privacy).
When several tools add sessions to one commit’s note, the result is the union of their sessions entries, merged by session reference.
Git does not push or fetch notes by default, and does not carry notes across rebases unless notes.rewriteRef includes the ref. A tool MAY configure notes.rewriteRef for refs/notes/agent-sessions, with the user’s consent.

Design note. Git AI moved transcripts out of its notes ref so that they could never leak into pushed history, and enterprise push policies have rejected unexpected notes refs. This ref carries references only, for the same reasons.

Export command

An L1 harness provides:

<agent> sessions export --format agent-session
    [--session <sessionId>]...
    [--since <RFC 3339 timestamp>]
    [--content-level full|redacted|metadata]
    [--output <directory>]
    [--include-native]

With exactly one --session and no --output, the command writes that session’s stream to standard output.
With --output, it writes a bundle directory (see Physical format) holding the selected sessions, or all sessions changed since --since.
Native files are included only with --include-native.
A no-op export preserves bytes, including observedAt. An append preserves every prior line, ID and seq. Later growth can append a full replacement under ASR-511. Source rewrites, deleted positions or transcript growth after a snapshot tail require a new capture. Stable source identities keep their IDs; seq is local to the selected capture. The manifest selects one capture per session; consumers explicitly choose which capture to use across bundles (ASR-033).
The command exits with status 0 on success and non-zero on failure, writing diagnostics to standard error.

Export cost and copies

Report whole-archive throughput separately from selected-session latency. Count decoded source bytes and compressed bytes separately. State retained identity-index size, peak memory and temporary disk use. For a no-op export, report source reads as well as converted bytes; zero conversion does not mean zero I/O. Separate setup and source loading from conversion when measurements permit it. Consumers totaling usage or cost MUST deduplicate copied records through lineage (ASR-417). Joining a side table by a copied run ID does not establish which session owns its facts (ASR-427).

Discovery file

A harness declares its sessions to other tools with a JSON file at $XDG_CONFIG_HOME/agent-sessions/sources/<agent>.json (~/.config/agent-sessions/sources/<agent>.json when XDG_CONFIG_HOME is unset; on Windows, %APPDATA%\agent-sessions\sources\<agent>.json).

{
  "agent": "goose",
  "namespace": "inst-4f9c2a",
  "exportCommand": [
    "goose",
    "sessions",
    "export",
    "--format",
    "agent-session"
  ],
  "nativePaths": ["~/.local/share/goose/sessions/sessions.db"],
  "formatVersions": ["0.1"],
  "supportsDeletionHook": false
}

Field	Type	Meaning
`agent`	string	The agent name (short or reverse-DNS). Required.
`namespace`	string	The installation namespace, for agents whose session IDs need one (see Identity). Producers that generate a namespace persist it here.
`exportCommand`	string[]	The export command as an array containing the command and its arguments.
`nativePaths`	string[]	Glob patterns for native session storage, with `~` for the home directory.
`formatVersions`	string[]	ASR format versions the export command can write.
`supportsDeletionHook`	boolean	Whether the harness can notify consumers before it deletes sessions (for example before a retention sweep).
`_meta`	object	Vendor data.

Tools MUST NOT run exportCommand without the user’s consent for that source (ASR-565). A discovery file is a claim by whoever wrote it; tools SHOULD check that the command is the harness the user installed. Publishing a session reference in Git history tells everyone who can read the repository that a session exists, which agent ran it, and sometimes where it can be viewed. History cannot be fully retracted once pushed. A tool that writes Agent-Session trailers or pushes notes:

MUST keep trailer writing or note pushing disabled until the user enables it, per repository or in user configuration.
MUST show the user what it will add before the first publication in a repository.
MUST ask for explicit confirmation when the repository’s remote is public.
MUST NOT put transcripts, prompts, paths or low-entropy digests in trailers or notes.
MUST let the user disable trailer writing or note pushing, and SHOULD say plainly that the tool cannot withdraw references already pushed.

Acquisition and qualification

A database capture includes its committed journal state. For SQLite, read a consistent transaction that includes the write-ahead log (WAL), or acquire the complete quiescent file set. Copying only the main file can omit committed sessions. Read-only SQL does not guarantee that the side files used to coordinate access remain unchanged. Record whether acquisition was live, quiescent or copied, and which consistency boundary it provides. Independent databases do not imply an atomic bundle snapshot. Keep installation namespaces in saved exporter configuration or accept them from the caller. Carry that configuration with archived stores. Do not derive a namespace from a path or create a new one for each output directory. Nested native containers use the encoding the agent’s registry entry documents. Report inputs that cannot be attributed to a session in the export report or receipt, with a reason and a count. A broken alias, an incomplete file or an archive without a header is an input; it is not necessarily a distinct missing session. Do not add a field to the core manifest for these counts. Qualify producers against a tagged release of the validator. Record the tag and the validator’s stamp in the qualification report. Do not change the oracle (the reference the checks are judged against) during a qualification run, and repeat the affected checks when the oracle’s bytes change.

Observer coverage and privacy

Publish a policy for source fields that says which callbacks and payload members are kept, omitted or transformed. Covering every event and covering every payload member are different claims. An allowlist can retain event metadata while excluding arbitrary prompts, paths, native payloads and tool output. Record the actual agent version, hook protocol and launch mode. A valid stream does not show that every callback was delivered or that the stream is safe to share. Declare events when callbacks may go unobserved. Use a gap for an observed omission and a count only when measured. Pending means unresolved in the capture, not necessarily pending in the application. Callbacks that run before an action do not prove its outcome. A containing session is not necessarily the immediate spawner. Privacy tests must search superseded snapshots, decoded replacement chunks, opaque payloads, native evidence, JSON-text fallbacks and blobs for known synthetic secrets. Test before and after snapshot replacement. The privacy policy still applies when a fallback preserves all source data. Keep acquisition and privacy tests separate from the validator’s post-export fixtures. The validator cannot detect a number rounded before it was written to the stream or recognize every secret it has not been told to look for.

Producer regression cases

Use synthetic cases for integers above u64 and below i64, decimal and exponent spellings, and literal keys that resemble parser tags. Check that numeric tokens are preserved exactly before conversion and in text or blob destinations. Include a committed SQLite WAL update absent from the main file, a store containing both events and current rows with a changed request card, and a partial selection of Mux data before indexing calls. Keep the selected effective row distinct from unselected audit evidence. Belonging to the same agent family does not establish that another agent’s mapping or release meets the qualification requirements.

​Adoption levels

​The Agent-Session trailer

​Aliases

​The notes ref

​Export command

​Export cost and copies

​Discovery file

​Consent

​Acquisition and qualification

​Observer coverage and privacy

​Producer regression cases