codebase-snapshot 0.9.8 → 0.9.12

package/dist/mcp.d.cts

@@ -1,3 +1,4 @@
+export { G as GenerateSummary, W as WorkerResults, g as generateInWorker } from './generate-worker-D5Xgh27c.cjs';
 import { Readable, Writable } from 'node:stream';
 
 /**
@@ -187,7 +188,7 @@ interface ToolContext {
  * Client-facing hints.
  *
  * `readOnlyHint` is the one that changes behaviour rather than appearance: clients use it to
- * auto-approve a call. Six of the seven tools never touch the filesystem, so they are marked
+ * auto-approve a call. Seven of the eight tools never touch the filesystem, so they are marked
  * read-only and only `snapshot_generate` prompts.
  */
 interface ToolAnnotations {
@@ -297,6 +298,73 @@ declare function createMcpServer(options: McpServerOptions): McpServer;
 /** Every tool this server exposes, in the order a first-time caller should read them. */
 declare function buildTools(): McpTool[];
 
+/**
+ * Reads one file's section back out of a rendered part.
+ *
+ * `snapshot_read` must not open the working tree. The snapshot is the contract: sensitive files
+ * are excluded from it, secret-shaped strings inside ordinary files are redacted on the way in,
+ * and a large file is emitted as a bounded preview. Reading the source directly would hand the
+ * model the `.env` the snapshot deliberately skipped and the credential it masked — so the read
+ * goes through the artifact instead.
+ *
+ * The format it parses is written by `renderFileSection`, and the parser is deliberately tied to
+ * that shape rather than to a regex over the whole document: a file's *content* may legitimately
+ * contain a line that looks like `### FILE: something`, and only fence tracking tells the two
+ * apart. Content fences are four or more backticks (`fenceForContent` never emits three), which
+ * is what makes "the next line equal to this exact fence" an unambiguous terminator.
+ */
+interface PartSection {
+    /** The path as rendered in the `### FILE:` heading. */
+    path: string;
+    /** The `<a id="…">` anchor from the line above the heading, when present. */
+    anchor: string | null;
+    /** The file body, without its fence. Redacted and possibly a bounded preview. */
+    body: string;
+    /** `full`, `preview` or `signatures`. */
+    inclusion: string | null;
+    includedLines: number | null;
+}
+/** Splits a part into one section per emitted file. */
+declare function parsePartSections(partText: string): PartSection[];
+/**
+ * Finds the section for one file.
+ *
+ * The **anchor** is the identifier, not the heading. `anchorForPath` hashes the real
+ * `relativePath`, so it is exact and injective; the heading is the display form, and for a path
+ * with a control character (escaped as `\uXXXX`) or one longer than 300 characters (capped from
+ * the middle) it is not the path at all. The old fallback for those cases was the content
+ * SHA-256, which the part no longer carries — and which could never disambiguate two files with
+ * the same content, the exact case that needs it.
+ *
+ * The heading comparison is kept as a second chance, for a snapshot written before the anchor
+ * was read, or a part whose anchor line was edited by hand.
+ */
+declare function findSection(sections: readonly PartSection[], relativePath: string): PartSection | null;
+interface Window {
+    text: string;
+    fromLine: number;
+    returnedLines: number;
+    totalLines: number;
+    truncated: boolean;
+    nextFromLine: number | null;
+    /**
+     * True when `fromLine` is beyond the last line of the body.
+     *
+     * The start used to be clamped to the last line, so asking for line 9,000 of a 40-line file
+     * returned line 40 with a header that read `Lines 40–40 of 40` — a wrong answer dressed as a
+     * right one. The caller is told the request was out of range instead.
+     */
+    pastEnd: boolean;
+}
+/**
+ * Cuts a line window out of a body.
+ *
+ * Windows are the whole point of this module: a part holds hundreds of kilobytes, and the only
+ * safe default for a tool that returns content is "as little as answers the question". `next` is
+ * an explicit pointer rather than an instruction to keep reading, so an agent decides.
+ */
+declare function windowText(body: string, fromLine: number, lineCount: number): Window;
+
 declare function buildPrompts(): McpPrompt[];
 
 declare function buildResourceProvider(): ResourceProvider;
@@ -409,4 +477,4 @@ declare function validateArguments(schema: InputSchema, value: unknown): string[
  */
 declare function coerceNumericStrings(schema: InputSchema, value: JsonObject): JsonObject;
 
-export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments };
+export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type PartSection, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, type Window, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, findSection, inspectModernMeta, negotiateLegacyVersion, parsePartSections, runStdioServer, validateArguments, windowText };

package/dist/mcp.d.ts

@@ -1,3 +1,4 @@
+export { G as GenerateSummary, W as WorkerResults, g as generateInWorker } from './generate-worker-D5Xgh27c.js';
 import { Readable, Writable } from 'node:stream';
 
 /**
@@ -187,7 +188,7 @@ interface ToolContext {
  * Client-facing hints.
  *
  * `readOnlyHint` is the one that changes behaviour rather than appearance: clients use it to
- * auto-approve a call. Six of the seven tools never touch the filesystem, so they are marked
+ * auto-approve a call. Seven of the eight tools never touch the filesystem, so they are marked
  * read-only and only `snapshot_generate` prompts.
  */
 interface ToolAnnotations {
@@ -297,6 +298,73 @@ declare function createMcpServer(options: McpServerOptions): McpServer;
 /** Every tool this server exposes, in the order a first-time caller should read them. */
 declare function buildTools(): McpTool[];
 
+/**
+ * Reads one file's section back out of a rendered part.
+ *
+ * `snapshot_read` must not open the working tree. The snapshot is the contract: sensitive files
+ * are excluded from it, secret-shaped strings inside ordinary files are redacted on the way in,
+ * and a large file is emitted as a bounded preview. Reading the source directly would hand the
+ * model the `.env` the snapshot deliberately skipped and the credential it masked — so the read
+ * goes through the artifact instead.
+ *
+ * The format it parses is written by `renderFileSection`, and the parser is deliberately tied to
+ * that shape rather than to a regex over the whole document: a file's *content* may legitimately
+ * contain a line that looks like `### FILE: something`, and only fence tracking tells the two
+ * apart. Content fences are four or more backticks (`fenceForContent` never emits three), which
+ * is what makes "the next line equal to this exact fence" an unambiguous terminator.
+ */
+interface PartSection {
+    /** The path as rendered in the `### FILE:` heading. */
+    path: string;
+    /** The `<a id="…">` anchor from the line above the heading, when present. */
+    anchor: string | null;
+    /** The file body, without its fence. Redacted and possibly a bounded preview. */
+    body: string;
+    /** `full`, `preview` or `signatures`. */
+    inclusion: string | null;
+    includedLines: number | null;
+}
+/** Splits a part into one section per emitted file. */
+declare function parsePartSections(partText: string): PartSection[];
+/**
+ * Finds the section for one file.
+ *
+ * The **anchor** is the identifier, not the heading. `anchorForPath` hashes the real
+ * `relativePath`, so it is exact and injective; the heading is the display form, and for a path
+ * with a control character (escaped as `\uXXXX`) or one longer than 300 characters (capped from
+ * the middle) it is not the path at all. The old fallback for those cases was the content
+ * SHA-256, which the part no longer carries — and which could never disambiguate two files with
+ * the same content, the exact case that needs it.
+ *
+ * The heading comparison is kept as a second chance, for a snapshot written before the anchor
+ * was read, or a part whose anchor line was edited by hand.
+ */
+declare function findSection(sections: readonly PartSection[], relativePath: string): PartSection | null;
+interface Window {
+    text: string;
+    fromLine: number;
+    returnedLines: number;
+    totalLines: number;
+    truncated: boolean;
+    nextFromLine: number | null;
+    /**
+     * True when `fromLine` is beyond the last line of the body.
+     *
+     * The start used to be clamped to the last line, so asking for line 9,000 of a 40-line file
+     * returned line 40 with a header that read `Lines 40–40 of 40` — a wrong answer dressed as a
+     * right one. The caller is told the request was out of range instead.
+     */
+    pastEnd: boolean;
+}
+/**
+ * Cuts a line window out of a body.
+ *
+ * Windows are the whole point of this module: a part holds hundreds of kilobytes, and the only
+ * safe default for a tool that returns content is "as little as answers the question". `next` is
+ * an explicit pointer rather than an instruction to keep reading, so an agent decides.
+ */
+declare function windowText(body: string, fromLine: number, lineCount: number): Window;
+
 declare function buildPrompts(): McpPrompt[];
 
 declare function buildResourceProvider(): ResourceProvider;
@@ -409,4 +477,4 @@ declare function validateArguments(schema: InputSchema, value: unknown): string[
  */
 declare function coerceNumericStrings(schema: InputSchema, value: JsonObject): JsonObject;
 
-export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments };
+export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type PartSection, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, type Window, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, findSection, inspectModernMeta, negotiateLegacyVersion, parsePartSections, runStdioServer, validateArguments, windowText };

package/dist/mcp.js

@@ -1,4 +1,2 @@
-export { ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments } from './chunk-RQKXZOD7.js';
-import './chunk-C24OAT6T.js';
-//# sourceMappingURL=mcp.js.map
-//# sourceMappingURL=mcp.js.map
+export { ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, findSection, inspectModernMeta, negotiateLegacyVersion, parsePartSections, runStdioServer, validateArguments, windowText } from './chunk-5OR3WVPW.js';
+export { generateInWorker } from './chunk-3H45YMBG.js';

package/dist/{types-Ca4PmkiQ.d.cts → types-CTewen3J.d.cts}

@@ -21,7 +21,7 @@ type TextEncoding = "utf-8" | "utf-8-lossy" | "utf-16le" | "utf-16be";
  * `full`    – the complete file body was emitted.
  * `preview` – the body was truncated (by lines and/or bytes) before emission.
  */
-type InclusionMode = "full" | "preview";
+type InclusionMode = "full" | "preview" | "signatures";
 interface SourceSummary {
     directives: string[];
     imports: string[];
@@ -88,7 +88,15 @@ type SkipReason = "binary" | "read-error" | "not-file"
  * expected — which used to be recorded as the generic `not-file`, implying the path was a
  * socket or a FIFO rather than a repository whose contents are simply somebody else's.
  */
- | "nested-repository";
+ | "nested-repository"
+/**
+ * Not in the set that `--changed-since` or `--staged` asked for.
+ *
+ * Deliberately distinct from `excluded`, which means the user's own glob rejected the path.
+ * Here the file is perfectly includable and simply did not change; reporting it as
+ * `excluded` would send a reader looking for an exclude pattern they never wrote.
+ */
+ | "unchanged";
 interface SkipRecord {
     /** Path as it may be shown in an artifact: secret spans are masked. */
     path: string;
@@ -144,6 +152,23 @@ interface PartMetadata {
     filename: string;
     /** Exact UTF-8 byte length of the emitted part file. */
     byteSize: number;
+    /**
+     * Estimated tokens in this part.
+     *
+     * `byteSize` answers "will this fit the byte budget"; this answers the question a caller
+     * actually has, which is "will this fit my context window". An estimate, and labelled as
+     * one: `estimateTokens` documents exactly what it counts.
+     */
+    estimatedTokens: number;
+    /**
+     * The byte budget this part was partitioned against.
+     *
+     * With per-layer budgets a snapshot has several budgets at once, so "within budget"
+     * cannot be answered without knowing which one applied. Verification compared every
+     * part against the *largest* budget in the run, which passed a part that was over its
+     * own.
+     */
+    budgetBytes: number;
     sha256: string;
     lines: number;
     fileCount: number;
@@ -198,6 +223,14 @@ interface ManifestTotals {
     skippedFiles: number;
     totalSourceBytes: number;
     totalContentBytes: number;
+    /**
+     * Estimated tokens in the emitted parts.
+     *
+     * Optional because a manifest written before this was recorded has no such key. The number
+     * is an estimate — see `estimateTokens` for the method — and it exists because the snapshot
+     * is pasted into a context window, which is measured in tokens rather than bytes.
+     */
+    estimatedTokens?: number;
     partCount: number;
     warningCount: number;
     /**
@@ -256,13 +289,34 @@ interface ManifestConfigSnapshot {
     /** Digest of the effective settings; see `configDigest`. */
     digest?: string;
     maxPartBytes: number;
+    /**
+     * The token ceiling the run was given, or `undefined` when only bytes were named.
+     *
+     * Recorded so the manifest states the budget the user chose rather than only the byte
+     * value it was converted to.
+     */
+    maxPartTokens?: number;
     largeFileBytes: number;
     previewHeadLines: number;
     previewTailLines: number;
     includeMonolith: boolean;
+    /**
+     * The ceiling above which the monolith is not written; `null` for no ceiling.
+     *
+     * Optional because a manifest written before this was recorded has no such key.
+     */
+    maxMonolithBytes?: number | null;
     includeSensitiveFiles: boolean;
     /** How files were discovered; `undefined` on manifests written before this was recorded. */
     discovery?: DiscoveryMode;
+    /** The changed-files scope the snapshot was taken over, when one was used. */
+    changedSince?: string;
+    staged?: boolean;
+    withDependents?: boolean;
+    /** True when bodies were replaced by signatures. */
+    skeleton?: boolean;
+    /** True when `reports/audit.sarif` was written. */
+    sarif?: boolean;
     artifacts: ResolvedArtifacts;
     include: string[];
     preset: string;
@@ -315,6 +369,14 @@ interface Manifest {
     artifacts: {
         fullJson: ManifestArtifact | null;
         fullMarkdown: ManifestArtifact | null;
+        /**
+         * `reports/audit.sarif`, when `--sarif` asked for it.
+         *
+         * Optional because most runs do not write one, and a manifest written before this
+         * existed has no such key at all — the two are indistinguishable to a reader, which is
+         * why the presence of the file is also recorded in `config`.
+         */
+        sarif?: ManifestArtifact;
     };
     layers: Record<string, number>;
     kinds: Record<string, number>;
@@ -382,6 +444,15 @@ interface SnapshotConfig {
     tmpDir?: string;
     /** Raw bytes, or a human-readable size (`"120k"`, `"1.5mb"`). */
     maxPartBytes?: ByteSize;
+    /**
+     * A per-part ceiling in *tokens* rather than bytes.
+     *
+     * The snapshot is pasted into a context window, and a context window is measured in tokens;
+     * bytes are what the partitioner writes. Naming a token budget sets `maxPartBytes` to the
+     * byte count that corresponds to it, so the byte bound — the thing the partitioner actually
+     * enforces — never stops being true. The smaller of the two ceilings wins.
+     */
+    maxPartTokens?: ByteSize;
     largeFileBytes?: ByteSize;
     previewHeadLines?: number;
     previewTailLines?: number;
@@ -393,6 +464,31 @@ interface SnapshotConfig {
     include?: string[];
     /** Force a preset by name instead of auto-detecting one. */
     preset?: string;
+    /**
+     * Only include files changed since this git ref.
+     *
+     * The pull-request case: the diff is small and the repository is not. Unchanged files are
+     * recorded in `skipped[]` with reason `unchanged`, so the manifest accounts for them.
+     */
+    changedSince?: string;
+    /** Only include files staged for the next commit. */
+    staged?: boolean;
+    /**
+     * Emit signatures instead of bodies for TypeScript and TSX files.
+     *
+     * Matches `inclusionMode: "signatures"` on the entries it applies to, so a reader can tell a
+     * compressed file from a whole one without diffing it against the source.
+     */
+    skeleton?: boolean;
+    /** Also write `reports/audit.sarif` so a CI security gate can read the findings. */
+    sarif?: boolean;
+    /**
+     * With `changedSince` or `staged`, also include the files that import a changed one.
+     *
+     * A one-hop closure: the file you changed and the files that reference it are the context
+     * needed to change it safely.
+     */
+    withDependents?: boolean;
     /** Switch individual snapshot artifacts off. Everything is on by default. */
     artifacts?: ArtifactSelection;
     /**
@@ -418,6 +514,8 @@ interface ResolvedSnapshotConfig {
     outDir: string;
     tmpDir: string;
     maxPartBytes: number;
+    /** The token ceiling the user asked for, before it was turned into `maxPartBytes`. */
+    maxPartTokens?: number;
     largeFileBytes: number;
     previewHeadLines: number;
     previewTailLines: number;
@@ -430,6 +528,21 @@ interface ResolvedSnapshotConfig {
      * reader treats `undefined` as `auto`, so the effective mode is never guessed twice.
      */
     discovery?: DiscoveryMode;
+    /** Only files changed since this git ref; `undefined` scans everything. */
+    changedSince?: string;
+    /** Only files staged for the next commit. */
+    staged?: boolean;
+    /** Emit signatures instead of bodies for TypeScript and TSX files. */
+    skeleton?: boolean;
+    /**
+     * Also write `reports/audit.sarif`, the findings in SARIF 2.1.0.
+     *
+     * For a CI security gate: GitHub Code Scanning reads SARIF, and a markdown report it cannot
+     * ingest is a finding nobody's build can act on.
+     */
+    sarif?: boolean;
+    /** Also include the files that import a changed one. */
+    withDependents?: boolean;
     /** Empty means "no allow-list"; every discovered file is a candidate. */
     include: string[];
     /** The preset that was resolved (detected or forced). */

package/dist/{types-Ca4PmkiQ.d.ts → types-CTewen3J.d.ts}

@@ -21,7 +21,7 @@ type TextEncoding = "utf-8" | "utf-8-lossy" | "utf-16le" | "utf-16be";
  * `full`    – the complete file body was emitted.
  * `preview` – the body was truncated (by lines and/or bytes) before emission.
  */
-type InclusionMode = "full" | "preview";
+type InclusionMode = "full" | "preview" | "signatures";
 interface SourceSummary {
     directives: string[];
     imports: string[];
@@ -88,7 +88,15 @@ type SkipReason = "binary" | "read-error" | "not-file"
  * expected — which used to be recorded as the generic `not-file`, implying the path was a
  * socket or a FIFO rather than a repository whose contents are simply somebody else's.
  */
- | "nested-repository";
+ | "nested-repository"
+/**
+ * Not in the set that `--changed-since` or `--staged` asked for.
+ *
+ * Deliberately distinct from `excluded`, which means the user's own glob rejected the path.
+ * Here the file is perfectly includable and simply did not change; reporting it as
+ * `excluded` would send a reader looking for an exclude pattern they never wrote.
+ */
+ | "unchanged";
 interface SkipRecord {
     /** Path as it may be shown in an artifact: secret spans are masked. */
     path: string;
@@ -144,6 +152,23 @@ interface PartMetadata {
     filename: string;
     /** Exact UTF-8 byte length of the emitted part file. */
     byteSize: number;
+    /**
+     * Estimated tokens in this part.
+     *
+     * `byteSize` answers "will this fit the byte budget"; this answers the question a caller
+     * actually has, which is "will this fit my context window". An estimate, and labelled as
+     * one: `estimateTokens` documents exactly what it counts.
+     */
+    estimatedTokens: number;
+    /**
+     * The byte budget this part was partitioned against.
+     *
+     * With per-layer budgets a snapshot has several budgets at once, so "within budget"
+     * cannot be answered without knowing which one applied. Verification compared every
+     * part against the *largest* budget in the run, which passed a part that was over its
+     * own.
+     */
+    budgetBytes: number;
     sha256: string;
     lines: number;
     fileCount: number;
@@ -198,6 +223,14 @@ interface ManifestTotals {
     skippedFiles: number;
     totalSourceBytes: number;
     totalContentBytes: number;
+    /**
+     * Estimated tokens in the emitted parts.
+     *
+     * Optional because a manifest written before this was recorded has no such key. The number
+     * is an estimate — see `estimateTokens` for the method — and it exists because the snapshot
+     * is pasted into a context window, which is measured in tokens rather than bytes.
+     */
+    estimatedTokens?: number;
     partCount: number;
     warningCount: number;
     /**
@@ -256,13 +289,34 @@ interface ManifestConfigSnapshot {
     /** Digest of the effective settings; see `configDigest`. */
     digest?: string;
     maxPartBytes: number;
+    /**
+     * The token ceiling the run was given, or `undefined` when only bytes were named.
+     *
+     * Recorded so the manifest states the budget the user chose rather than only the byte
+     * value it was converted to.
+     */
+    maxPartTokens?: number;
     largeFileBytes: number;
     previewHeadLines: number;
     previewTailLines: number;
     includeMonolith: boolean;
+    /**
+     * The ceiling above which the monolith is not written; `null` for no ceiling.
+     *
+     * Optional because a manifest written before this was recorded has no such key.
+     */
+    maxMonolithBytes?: number | null;
     includeSensitiveFiles: boolean;
     /** How files were discovered; `undefined` on manifests written before this was recorded. */
     discovery?: DiscoveryMode;
+    /** The changed-files scope the snapshot was taken over, when one was used. */
+    changedSince?: string;
+    staged?: boolean;
+    withDependents?: boolean;
+    /** True when bodies were replaced by signatures. */
+    skeleton?: boolean;
+    /** True when `reports/audit.sarif` was written. */
+    sarif?: boolean;
     artifacts: ResolvedArtifacts;
     include: string[];
     preset: string;
@@ -315,6 +369,14 @@ interface Manifest {
     artifacts: {
         fullJson: ManifestArtifact | null;
         fullMarkdown: ManifestArtifact | null;
+        /**
+         * `reports/audit.sarif`, when `--sarif` asked for it.
+         *
+         * Optional because most runs do not write one, and a manifest written before this
+         * existed has no such key at all — the two are indistinguishable to a reader, which is
+         * why the presence of the file is also recorded in `config`.
+         */
+        sarif?: ManifestArtifact;
     };
     layers: Record<string, number>;
     kinds: Record<string, number>;
@@ -382,6 +444,15 @@ interface SnapshotConfig {
     tmpDir?: string;
     /** Raw bytes, or a human-readable size (`"120k"`, `"1.5mb"`). */
     maxPartBytes?: ByteSize;
+    /**
+     * A per-part ceiling in *tokens* rather than bytes.
+     *
+     * The snapshot is pasted into a context window, and a context window is measured in tokens;
+     * bytes are what the partitioner writes. Naming a token budget sets `maxPartBytes` to the
+     * byte count that corresponds to it, so the byte bound — the thing the partitioner actually
+     * enforces — never stops being true. The smaller of the two ceilings wins.
+     */
+    maxPartTokens?: ByteSize;
     largeFileBytes?: ByteSize;
     previewHeadLines?: number;
     previewTailLines?: number;
@@ -393,6 +464,31 @@ interface SnapshotConfig {
     include?: string[];
     /** Force a preset by name instead of auto-detecting one. */
     preset?: string;
+    /**
+     * Only include files changed since this git ref.
+     *
+     * The pull-request case: the diff is small and the repository is not. Unchanged files are
+     * recorded in `skipped[]` with reason `unchanged`, so the manifest accounts for them.
+     */
+    changedSince?: string;
+    /** Only include files staged for the next commit. */
+    staged?: boolean;
+    /**
+     * Emit signatures instead of bodies for TypeScript and TSX files.
+     *
+     * Matches `inclusionMode: "signatures"` on the entries it applies to, so a reader can tell a
+     * compressed file from a whole one without diffing it against the source.
+     */
+    skeleton?: boolean;
+    /** Also write `reports/audit.sarif` so a CI security gate can read the findings. */
+    sarif?: boolean;
+    /**
+     * With `changedSince` or `staged`, also include the files that import a changed one.
+     *
+     * A one-hop closure: the file you changed and the files that reference it are the context
+     * needed to change it safely.
+     */
+    withDependents?: boolean;
     /** Switch individual snapshot artifacts off. Everything is on by default. */
     artifacts?: ArtifactSelection;
     /**
@@ -418,6 +514,8 @@ interface ResolvedSnapshotConfig {
     outDir: string;
     tmpDir: string;
     maxPartBytes: number;
+    /** The token ceiling the user asked for, before it was turned into `maxPartBytes`. */
+    maxPartTokens?: number;
     largeFileBytes: number;
     previewHeadLines: number;
     previewTailLines: number;
@@ -430,6 +528,21 @@ interface ResolvedSnapshotConfig {
      * reader treats `undefined` as `auto`, so the effective mode is never guessed twice.
      */
     discovery?: DiscoveryMode;
+    /** Only files changed since this git ref; `undefined` scans everything. */
+    changedSince?: string;
+    /** Only files staged for the next commit. */
+    staged?: boolean;
+    /** Emit signatures instead of bodies for TypeScript and TSX files. */
+    skeleton?: boolean;
+    /**
+     * Also write `reports/audit.sarif`, the findings in SARIF 2.1.0.
+     *
+     * For a CI security gate: GitHub Code Scanning reads SARIF, and a markdown report it cannot
+     * ingest is a finding nobody's build can act on.
+     */
+    sarif?: boolean;
+    /** Also include the files that import a changed one. */
+    withDependents?: boolean;
     /** Empty means "no allow-list"; every discovered file is a candidate. */
     include: string[];
     /** The preset that was resolved (detected or forced). */

package/docs/agent.md

@@ -115,7 +115,7 @@ devDependency and the `.gitignore` entries for the snapshot directory, and nothi
 
 ## When the client speaks MCP
 
-`codebase-snapshot mcp` serves the repository to a Model Context Protocol client over stdio: seven
+`codebase-snapshot mcp` serves the repository to a Model Context Protocol client over stdio: eight
 tools, `snapshot://` resources and two prompts. Prefer it over shelling out when the agent already
 has an MCP connection, for two reasons that are properties of the design rather than of the wiring: