context-loader 1.2.0__tar.gz → 1.3.1__tar.gz

{context_loader-1.2.0 → context_loader-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: context-loader
-Version: 1.2.0
+Version: 1.3.1
 Summary: Render deterministic local Git context for any executor
 License:                                  Apache License
                                     Version 2.0, January 2004
@@ -219,14 +219,14 @@ Python standard library.
 
 ## Open-source quick start
 
-Current stable release: **1.2.0**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
+Current stable release: **1.3.1**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
 
 ```bash
-uv tool install 'context-loader==1.2.0'
+uv tool install 'context-loader==1.3.1'
 ```
 
 ```bash
-pip install 'context-loader==1.2.0'
+pip install 'context-loader==1.3.1'
 ```
 
 ```bash
@@ -239,21 +239,21 @@ project-context --repo /path/to/repo --format json
 
 ## Install
 
-Source version: `1.2.0`. Install its matching published release or an exact source commit.
+Source version: `1.3.1`. Install its matching published release or an exact source commit.
 
 Install via `uv`:
 
 ```bash
-uv tool install 'context-loader==1.2.0'
+uv tool install 'context-loader==1.3.1'
 ```
 
 Install via `pip`:
 
 ```bash
-pip install 'context-loader==1.2.0'
+pip install 'context-loader==1.3.1'
 ```
 
-For development or source-based installs tracking current repository (`1.2.0`):
+For development or source-based installs tracking current repository (`1.3.1`):
 
 ```bash
 uv tool install git+https://github.com/xuanheng-tech/context-loader.git
@@ -264,8 +264,8 @@ The repository also retains `./project-context` as a direct development entry po
 ### Distributions
 
 The sole distribution is **`context-loader`**, containing the `context_loader` runtime
-and the `project-context` console script. Version `1.0.0` breaks the CLI name and Markdown
-heading contract. The JSON schema is unchanged. Terminal and any executor call this same
+and the `project-context` console script. Version `1.0.0` broke the CLI name and Markdown
+heading contract while leaving the then-current JSON schema unchanged. Terminal and any executor call this same
 entry point with explicit repository and focus arguments; no provider adapter or private
 session state is involved.
 
@@ -338,16 +338,17 @@ The output has no generated timestamp, AI summary, architecture inference, or di
 ## JSON Output
 
 `--format json` writes exactly one separator-compact UTF-8 JSON document plus one trailing newline
-to stdout. Keys are serialized in sorted order with `ensure_ascii=False`. `--format json-compact`
-uses the identical serialization; only the field set differs, as described under “Compact model
-consumption”. The declared contract for `--format json` is:
+to stdout, within the JSON document bound under “Limits”. Keys are serialized in sorted order
+with `ensure_ascii=False`. `--format json-compact` uses the identical serialization; only the field
+set differs, as described under “Compact model consumption”. The declared contract for
+`--format json` is:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 3,
   "tool": {
     "name": "context-loader",
-    "version": "1.2.0"
+    "version": "1.3.1"
   },
   "repository": {
     "requested_path": "/canonical/requested/path",
@@ -377,6 +378,11 @@ consumption”. The declared contract for `--format json` is:
   "context": "the same assembled Markdown context",
   "context_sha256": "sha256-hex",
   "statuses": [],
+  "nested_context": {
+    "files": ["docs/AGENTS.md"],
+    "list_truncated": false,
+    "scan_truncated": false
+  },
   "warnings": []
 }
 ```
@@ -389,31 +395,65 @@ context, in assembly order, after the existing newline normalization and truncat
 distinguishes `repository` from `global`; version 1.0.0's fixed root-file selection currently emits
 only `repository` sources and does not add any global-file discovery.
 
-`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown: skipped or absent sources, truncated sources, unreadable directory-tree entries, sections omitted under the global output budget, and truncated working-tree or declared-command listings. Each entry has stable `code`, `subject_kind`, and `subject` fields. `sources`, `context`, and `schema_version` remain unchanged; callers can ignore `statuses` safely.
+`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown — plus the nested-context truncation flags, which exist only in machine form: skipped or absent sources, truncated sources, unreadable directory-tree entries, sections omitted under the global output budget, truncated working-tree or declared-command listings, and truncated nested-`AGENTS.md` presence reports. Each entry has stable `code`, `subject_kind`, and `subject` fields. The two `nested_agents_*` codes mirror the `nested_context` truncation booleans for consumers that branch only on `statuses`; the full `nested_context` object remains a first-class field, never folded into `statuses`. Callers can ignore `statuses` safely.
 
 The optional `selection` object is present only on a rendered `AGENTS.md` source. Its section entries
 contain heading, heading level, and fixed selection reasons; it never contains the original focus or
-target path. Existing source fields and schema version 1 remain unchanged.
+target path. Existing per-source fields remain unchanged; the document's exact key
+set (now including `nested_context`) is named by its `schema_version`, described below.
+
+`nested_context` is always present and existence-only: `files` lists repository-relative paths of
+non-directory `AGENTS.md` entries under subdirectories, found by a bounded scan that enumerates
+directory entries, never opens or reads a candidate file and never traverses a symlink; it carries
+no sizes, no mtimes and no contents. A symlinked (even dangling) `AGENTS.md` is listed, because its
+existence comes from the directory entry itself; the scan never resolves what it points at. Any
+`.git`, `.venv`, `venv`, `node_modules` or `site-packages` directory is skipped at every depth:
+package-manager and interpreter-managed trees are not authored repository instructions.
+`list_truncated` means more matching entries exist beyond the report caps: 32 paths, and a 4 KiB
+budget metered on the emitted array itself — each path's escaped, JSON-serialized string plus its
+separator, with the array's brackets charged to the first entry — so the emitted array never costs
+more than the budget it declares. Because quoting is counted, an array already near the cap can
+report one path fewer than an older release did, and then says so through `list_truncated`.
+`scan_truncated` means the depth (4) or directory-count (2,000) budget was reached, or a directory
+or entry could not be read, so absence of a path is not proof of absence of the file. Nested paths
+are sanitized with the same escaping the Markdown uses for repository-derived text, so a nested name
+the filesystem could not decode never breaks the document;
+see “Limits” for the root paths that are emitted verbatim. The corresponding
+`nested_agents_list_truncated` and `nested_agents_scan_truncated` status entries mirror both flags.
+Presence is not instruction: whether a nested file applies, and its text, remain the caller's
+judgment; Markdown output is unchanged.
 
 ### Compact model consumption (`--format json-compact`)
 
-`--format json-compact` emits a `schema_version` 2 document: exactly the version-1 document with
+`--format json-compact` emits a `schema_version` 4 document: exactly the version-3 document with
 `sources[*].content` omitted. Every other field — `context`, `context_sha256`, `statuses`,
-`warnings`, `tool`, `repository`, and each source's `ordinal`, `kind`, `scope`, `path`,
-`content_sha256` and optional `selection` — is identical to `--format json` for the same arguments.
+`nested_context`, `warnings`, `tool`, `repository`, and each source's `ordinal`, `kind`, `scope`,
+`path`, `content_sha256` and optional `selection` — is identical to `--format json` for the same
+arguments.
+`sources` is provenance and index metadata, not the place a body must be fetched from: every omitted
+body is already inside `context` verbatim, so consumers should read `context` for rule text and
+reopen a source file only when the rendered body was truncated or selected away — never to recover a
+body that the document already carried.
 The projection exists because the selected source bodies already occur verbatim inside `context`,
 so carrying them again in `sources` duplicates a large share of the document bytes (measured up to
 ~44% on real worktrees, scaling with how much of `context` those bodies occupy) for a model
 consumer without adding information. Nothing is lost: each omitted body remains inside `context`,
 `content_sha256` still fingerprints that rendered body, and `path` plus `canonical_root` locate the
 underlying file for a bounded manual re-read (whose raw bytes may differ from the rendered body as
-defined above). `schema_version` is an exact document selector, not an upgrade marker: version 2 is
-a field-set projection of version 1, so consumers must branch on the value and must not apply
-`>=`-superset reasoning. Default Markdown and `--format json` output bytes, exit codes and
-determinism are unchanged.
-
-The JSON schema version and package version are independent: `--format json` currently emits
-`schema_version` `1` and `--format json-compact` emits `2`, while `tool.version` is `1.2.0`.
+defined above). `schema_version` is an exact document selector, not an upgrade marker: version 4 is
+a field-set projection of version 3, so consumers must branch on the value and must not apply
+`>=`-superset reasoning. Introducing this compact format does
+not otherwise change default Markdown bytes, exit codes or determinism.
+
+One historical exception is acknowledged: releases 1.0.0 and 1.1.0 both emitted `schema_version` 1
+although 1.1.0 added the top-level `statuses` key. From release 1.2.0 onward each emitted number
+names exactly one key set, and the `nested_context` renumber below enforces that rule going forward.
+
+The JSON schema version and package version are independent: this build emits `schema_version` `3`
+for `--format json` and `4` for `--format json-compact`, while `tool.version` is `1.3.1`. Version 1
+and 2 are the exact shapes already published in release 1.2.0 and are never reused: because
+`nested_context` changes the default document's key set, version 3 names the current full-document
+key set and version 4 names the compact projection.
 Callers must depend only on fields declared above.
 The document contains no generated time or random identifier, so unchanged input produces identical
 JSON bytes. On failure, stdout remains empty and stderr contains only a short diagnostic.
@@ -428,7 +468,9 @@ Resolving an instruction hierarchy stays with the calling agent harness. That in
 shared or user-level instruction file outside the repository, nested or scoped `AGENTS.md` files
 under subdirectories, and any include or import directive written inside an instruction file:
 such a directive is transported as literal text and is never followed. `--path` selects sections
-of the repository-root `AGENTS.md` only; it never changes which files are read.
+of the repository-root `AGENTS.md` only; it never changes which files are read. The JSON-only
+`nested_context` field reports the existence of nested `AGENTS.md` paths without reading them;
+deciding whether any of them applies stays with the calling agent harness exactly as before.
 
 A successful run therefore proves that the bounded root context was collected and rendered. It
 does not prove that every instruction applicable to a task has been loaded.
@@ -461,7 +503,23 @@ scan that ends before EOF still reports the characters it could not select.
 
 ## Limits
 
-- Final stdout: 98,304 bytes
+Final output bounds differ per format. The two stdout bounds below are enforced on the bytes written
+to stdout and the nested report cap on the bytes the document emits for that array; every other
+bullet is a per-component, read or capture bound, as each one states:
+
+- Markdown stdout: 98,304 bytes. A section that cannot fit is replaced by an omission notice, and so
+  is every later section, so the limit holds without cutting a section mid-body.
+- JSON and JSON-compact stdout: 8,388,608 bytes (8 MiB) for the serialized document, including its
+  trailing newline. This bound is fail-closed: if a repository's evidence cannot fit, the tool exits
+  1, writes nothing to stdout and prints `error: JSON output exceeded the 8388608 byte document
+  limit`. It never emits a truncated document. The component budgets below keep legitimate
+  documents far inside it — the largest escape-dense repository audited for this release emitted
+  263 KiB, of which 248 KiB was escaped `statuses` subjects — so it is a final backstop rather
+  than an expected truncation point.
+- Component budgets below are metered on the Markdown `context` content, and that same string is the
+  JSON `context` value; because JSON escaping expands quotes, backslashes and control characters,
+  the serialized bytes can be several times larger. The JSON document also repeats the source
+  bodies, so no single component figure bounds JSON stdout.
 - `AGENTS.md`: 256-KiB bounded source scan; selected source plus selection audit remains at most
   16 KiB, including a 4-KiB maximum small head
 - `README.md`: 16 KiB
@@ -469,8 +527,14 @@ scan that ends before EOF still reports the characters it could not select.
 - All entry-file bodies: 24 KiB
 - Declared commands: 8 KiB
 - Directory tree: 12 KiB, 300 entries, and depth 2
+- Nested `AGENTS.md` presence scan: depth 4, 2,000 directories, at most 32 reported paths and
+  a 4 KiB budget metered on the emitted array; file contents are never read
 - Working-tree changes: 100 paths and 4 KiB
 - Recent commits: 8
+- JSON-only listings have no byte budget of their own: `statuses` subjects are escaped names bounded
+  by the entry counts above, while `repository` and `sources[*].path` are emitted verbatim, so a
+  repository root the filesystem could not decode makes the machine formats exit 1 where Markdown
+  still renders
 - Git subprocess output: 16 MiB (bounded while reading)
 - Candidate file validation: 16 MiB hard read bound
 
@@ -507,7 +571,8 @@ or candidate-file content.
 
 ## Not Included
 
-Version 1.0.0 does not provide AI summaries, project-type detection, nested `AGENTS.md` handling,
+Version 1.3.1 does not provide AI summaries, project-type detection, loading or transport of
+nested `AGENTS.md` contents (the JSON `nested_context` field reports bounded existence only),
 Memory retrieval, semantic ranking, ignore-rule parsing, plugins, profiles, caches, databases,
 network services, MCP, daemons, GUIs, CI/CD, telemetry, or automatic updates.
 
@@ -521,8 +586,9 @@ just check
 
 ## Version maintenance
 
-The versions in `pyproject.toml` and `context_loader/__init__.py`, the matching `CHANGELOG.md`
-section, required tests, and the README current-stable declaration plus `context-loader==X.Y.Z`
+The versions in `pyproject.toml` and `context_loader/__init__.py`, the `tool_version` in
+`tool_cli_contract.json`, the matching `CHANGELOG.md` section, required tests, and the README
+current-stable declaration plus `context-loader==X.Y.Z`
 install pins must change in the same release-preparation batch. `CHANGELOG.md` is the
 authoritative version-change record. `scripts/release.py` rejects README stable/install
 pins that disagree with the intended package version; historical changelog entries are

{context_loader-1.2.0 → context_loader-1.3.1}/README.md

@@ -8,14 +8,14 @@ Python standard library.
 
 ## Open-source quick start
 
-Current stable release: **1.2.0**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
+Current stable release: **1.3.1**. Local CLI for coding-agent workflows; renders deterministic Markdown or JSON.
 
 ```bash
-uv tool install 'context-loader==1.2.0'
+uv tool install 'context-loader==1.3.1'
 ```
 
 ```bash
-pip install 'context-loader==1.2.0'
+pip install 'context-loader==1.3.1'
 ```
 
 ```bash
@@ -28,21 +28,21 @@ project-context --repo /path/to/repo --format json
 
 ## Install
 
-Source version: `1.2.0`. Install its matching published release or an exact source commit.
+Source version: `1.3.1`. Install its matching published release or an exact source commit.
 
 Install via `uv`:
 
 ```bash
-uv tool install 'context-loader==1.2.0'
+uv tool install 'context-loader==1.3.1'
 ```
 
 Install via `pip`:
 
 ```bash
-pip install 'context-loader==1.2.0'
+pip install 'context-loader==1.3.1'
 ```
 
-For development or source-based installs tracking current repository (`1.2.0`):
+For development or source-based installs tracking current repository (`1.3.1`):
 
 ```bash
 uv tool install git+https://github.com/xuanheng-tech/context-loader.git
@@ -53,8 +53,8 @@ The repository also retains `./project-context` as a direct development entry po
 ### Distributions
 
 The sole distribution is **`context-loader`**, containing the `context_loader` runtime
-and the `project-context` console script. Version `1.0.0` breaks the CLI name and Markdown
-heading contract. The JSON schema is unchanged. Terminal and any executor call this same
+and the `project-context` console script. Version `1.0.0` broke the CLI name and Markdown
+heading contract while leaving the then-current JSON schema unchanged. Terminal and any executor call this same
 entry point with explicit repository and focus arguments; no provider adapter or private
 session state is involved.
 
@@ -127,16 +127,17 @@ The output has no generated timestamp, AI summary, architecture inference, or di
 ## JSON Output
 
 `--format json` writes exactly one separator-compact UTF-8 JSON document plus one trailing newline
-to stdout. Keys are serialized in sorted order with `ensure_ascii=False`. `--format json-compact`
-uses the identical serialization; only the field set differs, as described under “Compact model
-consumption”. The declared contract for `--format json` is:
+to stdout, within the JSON document bound under “Limits”. Keys are serialized in sorted order
+with `ensure_ascii=False`. `--format json-compact` uses the identical serialization; only the field
+set differs, as described under “Compact model consumption”. The declared contract for
+`--format json` is:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 3,
   "tool": {
     "name": "context-loader",
-    "version": "1.2.0"
+    "version": "1.3.1"
   },
   "repository": {
     "requested_path": "/canonical/requested/path",
@@ -166,6 +167,11 @@ consumption”. The declared contract for `--format json` is:
   "context": "the same assembled Markdown context",
   "context_sha256": "sha256-hex",
   "statuses": [],
+  "nested_context": {
+    "files": ["docs/AGENTS.md"],
+    "list_truncated": false,
+    "scan_truncated": false
+  },
   "warnings": []
 }
 ```
@@ -178,31 +184,65 @@ context, in assembly order, after the existing newline normalization and truncat
 distinguishes `repository` from `global`; version 1.0.0's fixed root-file selection currently emits
 only `repository` sources and does not add any global-file discovery.
 
-`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown: skipped or absent sources, truncated sources, unreadable directory-tree entries, sections omitted under the global output budget, and truncated working-tree or declared-command listings. Each entry has stable `code`, `subject_kind`, and `subject` fields. `sources`, `context`, and `schema_version` remain unchanged; callers can ignore `statuses` safely.
+`statuses` lists machine-readable collection and render conditions that previously appeared only inside `context` Markdown — plus the nested-context truncation flags, which exist only in machine form: skipped or absent sources, truncated sources, unreadable directory-tree entries, sections omitted under the global output budget, truncated working-tree or declared-command listings, and truncated nested-`AGENTS.md` presence reports. Each entry has stable `code`, `subject_kind`, and `subject` fields. The two `nested_agents_*` codes mirror the `nested_context` truncation booleans for consumers that branch only on `statuses`; the full `nested_context` object remains a first-class field, never folded into `statuses`. Callers can ignore `statuses` safely.
 
 The optional `selection` object is present only on a rendered `AGENTS.md` source. Its section entries
 contain heading, heading level, and fixed selection reasons; it never contains the original focus or
-target path. Existing source fields and schema version 1 remain unchanged.
+target path. Existing per-source fields remain unchanged; the document's exact key
+set (now including `nested_context`) is named by its `schema_version`, described below.
+
+`nested_context` is always present and existence-only: `files` lists repository-relative paths of
+non-directory `AGENTS.md` entries under subdirectories, found by a bounded scan that enumerates
+directory entries, never opens or reads a candidate file and never traverses a symlink; it carries
+no sizes, no mtimes and no contents. A symlinked (even dangling) `AGENTS.md` is listed, because its
+existence comes from the directory entry itself; the scan never resolves what it points at. Any
+`.git`, `.venv`, `venv`, `node_modules` or `site-packages` directory is skipped at every depth:
+package-manager and interpreter-managed trees are not authored repository instructions.
+`list_truncated` means more matching entries exist beyond the report caps: 32 paths, and a 4 KiB
+budget metered on the emitted array itself — each path's escaped, JSON-serialized string plus its
+separator, with the array's brackets charged to the first entry — so the emitted array never costs
+more than the budget it declares. Because quoting is counted, an array already near the cap can
+report one path fewer than an older release did, and then says so through `list_truncated`.
+`scan_truncated` means the depth (4) or directory-count (2,000) budget was reached, or a directory
+or entry could not be read, so absence of a path is not proof of absence of the file. Nested paths
+are sanitized with the same escaping the Markdown uses for repository-derived text, so a nested name
+the filesystem could not decode never breaks the document;
+see “Limits” for the root paths that are emitted verbatim. The corresponding
+`nested_agents_list_truncated` and `nested_agents_scan_truncated` status entries mirror both flags.
+Presence is not instruction: whether a nested file applies, and its text, remain the caller's
+judgment; Markdown output is unchanged.
 
 ### Compact model consumption (`--format json-compact`)
 
-`--format json-compact` emits a `schema_version` 2 document: exactly the version-1 document with
+`--format json-compact` emits a `schema_version` 4 document: exactly the version-3 document with
 `sources[*].content` omitted. Every other field — `context`, `context_sha256`, `statuses`,
-`warnings`, `tool`, `repository`, and each source's `ordinal`, `kind`, `scope`, `path`,
-`content_sha256` and optional `selection` — is identical to `--format json` for the same arguments.
+`nested_context`, `warnings`, `tool`, `repository`, and each source's `ordinal`, `kind`, `scope`,
+`path`, `content_sha256` and optional `selection` — is identical to `--format json` for the same
+arguments.
+`sources` is provenance and index metadata, not the place a body must be fetched from: every omitted
+body is already inside `context` verbatim, so consumers should read `context` for rule text and
+reopen a source file only when the rendered body was truncated or selected away — never to recover a
+body that the document already carried.
 The projection exists because the selected source bodies already occur verbatim inside `context`,
 so carrying them again in `sources` duplicates a large share of the document bytes (measured up to
 ~44% on real worktrees, scaling with how much of `context` those bodies occupy) for a model
 consumer without adding information. Nothing is lost: each omitted body remains inside `context`,
 `content_sha256` still fingerprints that rendered body, and `path` plus `canonical_root` locate the
 underlying file for a bounded manual re-read (whose raw bytes may differ from the rendered body as
-defined above). `schema_version` is an exact document selector, not an upgrade marker: version 2 is
-a field-set projection of version 1, so consumers must branch on the value and must not apply
-`>=`-superset reasoning. Default Markdown and `--format json` output bytes, exit codes and
-determinism are unchanged.
-
-The JSON schema version and package version are independent: `--format json` currently emits
-`schema_version` `1` and `--format json-compact` emits `2`, while `tool.version` is `1.2.0`.
+defined above). `schema_version` is an exact document selector, not an upgrade marker: version 4 is
+a field-set projection of version 3, so consumers must branch on the value and must not apply
+`>=`-superset reasoning. Introducing this compact format does
+not otherwise change default Markdown bytes, exit codes or determinism.
+
+One historical exception is acknowledged: releases 1.0.0 and 1.1.0 both emitted `schema_version` 1
+although 1.1.0 added the top-level `statuses` key. From release 1.2.0 onward each emitted number
+names exactly one key set, and the `nested_context` renumber below enforces that rule going forward.
+
+The JSON schema version and package version are independent: this build emits `schema_version` `3`
+for `--format json` and `4` for `--format json-compact`, while `tool.version` is `1.3.1`. Version 1
+and 2 are the exact shapes already published in release 1.2.0 and are never reused: because
+`nested_context` changes the default document's key set, version 3 names the current full-document
+key set and version 4 names the compact projection.
 Callers must depend only on fields declared above.
 The document contains no generated time or random identifier, so unchanged input produces identical
 JSON bytes. On failure, stdout remains empty and stderr contains only a short diagnostic.
@@ -217,7 +257,9 @@ Resolving an instruction hierarchy stays with the calling agent harness. That in
 shared or user-level instruction file outside the repository, nested or scoped `AGENTS.md` files
 under subdirectories, and any include or import directive written inside an instruction file:
 such a directive is transported as literal text and is never followed. `--path` selects sections
-of the repository-root `AGENTS.md` only; it never changes which files are read.
+of the repository-root `AGENTS.md` only; it never changes which files are read. The JSON-only
+`nested_context` field reports the existence of nested `AGENTS.md` paths without reading them;
+deciding whether any of them applies stays with the calling agent harness exactly as before.
 
 A successful run therefore proves that the bounded root context was collected and rendered. It
 does not prove that every instruction applicable to a task has been loaded.
@@ -250,7 +292,23 @@ scan that ends before EOF still reports the characters it could not select.
 
 ## Limits
 
-- Final stdout: 98,304 bytes
+Final output bounds differ per format. The two stdout bounds below are enforced on the bytes written
+to stdout and the nested report cap on the bytes the document emits for that array; every other
+bullet is a per-component, read or capture bound, as each one states:
+
+- Markdown stdout: 98,304 bytes. A section that cannot fit is replaced by an omission notice, and so
+  is every later section, so the limit holds without cutting a section mid-body.
+- JSON and JSON-compact stdout: 8,388,608 bytes (8 MiB) for the serialized document, including its
+  trailing newline. This bound is fail-closed: if a repository's evidence cannot fit, the tool exits
+  1, writes nothing to stdout and prints `error: JSON output exceeded the 8388608 byte document
+  limit`. It never emits a truncated document. The component budgets below keep legitimate
+  documents far inside it — the largest escape-dense repository audited for this release emitted
+  263 KiB, of which 248 KiB was escaped `statuses` subjects — so it is a final backstop rather
+  than an expected truncation point.
+- Component budgets below are metered on the Markdown `context` content, and that same string is the
+  JSON `context` value; because JSON escaping expands quotes, backslashes and control characters,
+  the serialized bytes can be several times larger. The JSON document also repeats the source
+  bodies, so no single component figure bounds JSON stdout.
 - `AGENTS.md`: 256-KiB bounded source scan; selected source plus selection audit remains at most
   16 KiB, including a 4-KiB maximum small head
 - `README.md`: 16 KiB
@@ -258,8 +316,14 @@ scan that ends before EOF still reports the characters it could not select.
 - All entry-file bodies: 24 KiB
 - Declared commands: 8 KiB
 - Directory tree: 12 KiB, 300 entries, and depth 2
+- Nested `AGENTS.md` presence scan: depth 4, 2,000 directories, at most 32 reported paths and
+  a 4 KiB budget metered on the emitted array; file contents are never read
 - Working-tree changes: 100 paths and 4 KiB
 - Recent commits: 8
+- JSON-only listings have no byte budget of their own: `statuses` subjects are escaped names bounded
+  by the entry counts above, while `repository` and `sources[*].path` are emitted verbatim, so a
+  repository root the filesystem could not decode makes the machine formats exit 1 where Markdown
+  still renders
 - Git subprocess output: 16 MiB (bounded while reading)
 - Candidate file validation: 16 MiB hard read bound
 
@@ -296,7 +360,8 @@ or candidate-file content.
 
 ## Not Included
 
-Version 1.0.0 does not provide AI summaries, project-type detection, nested `AGENTS.md` handling,
+Version 1.3.1 does not provide AI summaries, project-type detection, loading or transport of
+nested `AGENTS.md` contents (the JSON `nested_context` field reports bounded existence only),
 Memory retrieval, semantic ranking, ignore-rule parsing, plugins, profiles, caches, databases,
 network services, MCP, daemons, GUIs, CI/CD, telemetry, or automatic updates.
 
@@ -310,8 +375,9 @@ just check
 
 ## Version maintenance
 
-The versions in `pyproject.toml` and `context_loader/__init__.py`, the matching `CHANGELOG.md`
-section, required tests, and the README current-stable declaration plus `context-loader==X.Y.Z`
+The versions in `pyproject.toml` and `context_loader/__init__.py`, the `tool_version` in
+`tool_cli_contract.json`, the matching `CHANGELOG.md` section, required tests, and the README
+current-stable declaration plus `context-loader==X.Y.Z`
 install pins must change in the same release-preparation batch. `CHANGELOG.md` is the
 authoritative version-change record. `scripts/release.py` rejects README stable/install
 pins that disagree with the intended package version; historical changelog entries are

{context_loader-1.2.0 → context_loader-1.3.1}/context_loader/__init__.py

@@ -1,3 +1,3 @@
 """Project Context Loader."""
 
-__version__ = "1.2.0"
+__version__ = "1.3.1"

{context_loader-1.2.0 → context_loader-1.3.1}/context_loader/application.py

@@ -20,14 +20,22 @@ from .collect import (
     AgentsSelectionAudit,
     AgentsSelectionInputError,
     CollectedFile,
+    NestedContextPresence,
     ProjectContext,
     collect_project_context,
+    display_text,
 )
 from .git import ContextLoaderError, collect_repository
 from .render import render_markdown_with_details, rendered_source_contents
 
-JSON_SCHEMA_VERSION = 1
-COMPACT_JSON_SCHEMA_VERSION = 2
+# Each value names one exact document shape and is never reused: 1 and 2 are the
+# shapes published in release 1.2.0, so adding the nested_context object to both
+# formats moved the default document to 3 and the compact projection to 4.
+JSON_SCHEMA_VERSION = 3
+COMPACT_JSON_SCHEMA_VERSION = 4
+# Both machine formats share this final bound on the serialized document: output is
+# either valid JSON within it or a fail-closed error, never a truncated document.
+JSON_OUTPUT_LIMIT_BYTES = 8 * 1024 * 1024
 TOOL_NAME = "context-loader"
 
 _STATUS_CODE_BY_MESSAGE = {
@@ -81,6 +89,7 @@ class ProjectContextResult:
     context_sha256: str
     warnings: tuple[str, ...]
     statuses: tuple[ContextStatus, ...]
+    nested_context: NestedContextPresence
 
 
 def _text_sha256(content: str) -> str:
@@ -185,11 +194,16 @@ def _build_statuses(
     for entry in project.directory_tree.entries:
         if entry.kind == "unreadable_directory":
             subject = entry.path if entry.path else "."
-            statuses.append(_status("unreadable", "tree_entry", subject))
+            statuses.append(_status("unreadable", "tree_entry", display_text(subject)))
 
     for title in omitted_sections:
         statuses.append(_status("section_omitted", "section", title))
 
+    if project.nested_context.list_truncated:
+        statuses.append(_status("nested_agents_list_truncated", "nested_context", "AGENTS.md"))
+    if project.nested_context.scan_truncated:
+        statuses.append(_status("nested_agents_scan_truncated", "nested_context", "AGENTS.md"))
+
     deduped: list[ContextStatus] = []
     seen: set[tuple[str, str, str]] = set()
     for status in statuses:
@@ -239,6 +253,7 @@ def load_project_context(
         context_sha256=hashlib.sha256(rendered.output).hexdigest(),
         warnings=(),
         statuses=statuses,
+        nested_context=project.nested_context,
     )
 
 
@@ -294,6 +309,9 @@ def render_json(result: ProjectContextResult, *, compact: bool = False) -> bytes
     ``compact`` projects away the duplicated source bodies only at this
     boundary: statuses and context were computed from the full model at load
     time, so both documents agree on everything except ``sources[*].content``.
+
+    The bound is on the final serialized document: a repository whose evidence
+    cannot fit fails closed with no output rather than emitting a partial file.
     """
     document = {
         "schema_version": (COMPACT_JSON_SCHEMA_VERSION if compact else result.schema_version),
@@ -309,6 +327,13 @@ def render_json(result: ProjectContextResult, *, compact: bool = False) -> bytes
             _source_document(source, include_content=not compact) for source in result.sources
         ],
         "statuses": [_status_document(status) for status in result.statuses],
+        "nested_context": {
+            # Filesystem names arrive undecoded (surrogate-escaped); sanitize exactly like
+            # tree/change paths so no raw byte can reach the UTF-8 document.
+            "files": [display_text(path) for path in result.nested_context.files],
+            "list_truncated": result.nested_context.list_truncated,
+            "scan_truncated": result.nested_context.scan_truncated,
+        },
         "context": result.context,
         "context_sha256": result.context_sha256,
         "warnings": list(result.warnings),
@@ -319,4 +344,9 @@ def render_json(result: ProjectContextResult, *, compact: bool = False) -> bytes
         sort_keys=True,
         separators=(",", ":"),
     )
-    return f"{serialized}\n".encode()
+    encoded = f"{serialized}\n".encode()
+    if len(encoded) > JSON_OUTPUT_LIMIT_BYTES:
+        raise ContextLoaderError(
+            f"JSON output exceeded the {JSON_OUTPUT_LIMIT_BYTES} byte document limit"
+        )
+    return encoded

{context_loader-1.2.0 → context_loader-1.3.1}/context_loader/cli.py

@@ -39,8 +39,8 @@ def _parser() -> argparse.ArgumentParser:
         choices=("markdown", "json", "json-compact"),
         default="markdown",
         help=(
-            "output format (default: markdown); json-compact emits schema "
-            "version 2 without duplicated source bodies"
+            "output format (default: markdown); json-compact omits the "
+            "duplicated source bodies (see README, Compact model consumption)"
         ),
     )
     return parser

{context_loader-1.2.0 → context_loader-1.3.1}/context_loader/collect.py

@@ -26,6 +26,13 @@ DECLARED_COMMANDS_LIMIT_BYTES = 8 * 1024
 DIRECTORY_TREE_LIMIT_BYTES = 12 * 1024
 DIRECTORY_TREE_MAX_ITEMS = 300
 DIRECTORY_TREE_MAX_DEPTH = 2
+NESTED_AGENTS_MAX_DEPTH = 4
+NESTED_AGENTS_MAX_DIRECTORIES = 2_000
+NESTED_AGENTS_MAX_FILES = 32
+NESTED_AGENTS_MAX_LIST_BYTES = 4 * 1024
+NESTED_AGENTS_EXCLUDED_DIRECTORIES = frozenset(
+    {".git", ".venv", "node_modules", "site-packages", "venv"}
+)
 FILE_SCAN_LIMIT_BYTES = 16 * 1024 * 1024
 MAX_FILE_SCAN_BYTES = FILE_SCAN_LIMIT_BYTES
 TRUNCATION_MARKER = "… truncated by context-loader …"
@@ -190,6 +197,15 @@ class DirectoryTree:
     truncated: bool = False
 
 
+@dataclass(frozen=True, slots=True)
+class NestedContextPresence:
+    """Existence-only index of nested AGENTS.md files; their contents are never read."""
+
+    files: tuple[str, ...]
+    list_truncated: bool = False
+    scan_truncated: bool = False
+
+
 @dataclass(frozen=True, slots=True)
 class ProjectContext:
     instructions: CollectedFile
@@ -197,6 +213,7 @@ class ProjectContext:
     entry_files: tuple[CollectedFile, ...]
     commands: tuple[DeclaredCommand, ...]
     directory_tree: DirectoryTree
+    nested_context: NestedContextPresence
 
 
 @dataclass(frozen=True, slots=True)
@@ -975,6 +992,117 @@ def _collect_directory_tree(root: Path) -> DirectoryTree:
     return DirectoryTree(tuple(collected), truncated)
 
 
+def display_text(value: str) -> str:
+    r"""Render one filesystem or Git string as printable, encodable ASCII-safe text.
+
+    Backticks, lone surrogates produced by ``surrogateescape`` decoding, and every
+    other non-printable codepoint become ``\xNN``/``\uNNNN``/``\UNNNNNNNN`` escapes so
+    the character can cross the JSON and Markdown serialization boundaries intact.
+    """
+    rendered: list[str] = []
+    for character in value:
+        codepoint = ord(character)
+        if character == "`":
+            rendered.append(r"\x60")
+        elif 0xDC80 <= codepoint <= 0xDCFF:
+            rendered.append(f"\\x{codepoint - 0xDC00:02x}")
+        elif character.isprintable():
+            rendered.append(character)
+        elif codepoint <= 0xFF:
+            rendered.append(f"\\x{codepoint:02x}")
+        elif codepoint <= 0xFFFF:
+            rendered.append(f"\\u{codepoint:04x}")
+        else:
+            rendered.append(f"\\U{codepoint:08x}")
+    return "".join(rendered)
+
+
+def serialized_display_length(value: str) -> int:
+    """Return the UTF-8 byte size of ``value`` once escaped and JSON-serialized.
+
+    This is the exact bytes one ``nested_context`` entry costs, quotes included, so the
+    report budget is metered on emitted output rather than on raw path bytes.
+    """
+    return len(json.dumps(display_text(value), ensure_ascii=False).encode("utf-8"))
+
+
+def collect_nested_agents_presence(repository: Path) -> NestedContextPresence:
+    """List nested AGENTS.md paths under a bounded, contents-blind directory scan.
+
+    The scan reads directory entries only: it never opens a candidate file, never
+    traverses a symlink, and reports truncation honestly so presence claims stay
+    auditable. Any non-directory entry named AGENTS.md is listed, including
+    symlinked ones, because existence comes from enumeration alone; entry types
+    are never resolved beyond directory-vs-not, and contents remain the caller's
+    responsibility to read.
+    """
+    files: list[str] = []
+    reported_bytes = 0
+    state = {"list_truncated": False, "scan_truncated": False, "directories": 0}
+
+    def walk(directory_descriptor: int, prefix: str, depth: int) -> None:
+        nonlocal reported_bytes
+        if depth > NESTED_AGENTS_MAX_DEPTH or state["directories"] >= NESTED_AGENTS_MAX_DIRECTORIES:
+            state["scan_truncated"] = True
+            return
+        state["directories"] += 1
+        try:
+            with os.scandir(directory_descriptor) as iterator:
+                entries = sorted(iterator, key=lambda entry: entry.name)
+        except OSError:
+            state["scan_truncated"] = True
+            return
+        subdirectories: list[str] = []
+        for entry in entries:
+            try:
+                is_directory = entry.is_dir(follow_symlinks=False)
+            except OSError:
+                state["scan_truncated"] = True
+                continue
+            path = f"{prefix}/{entry.name}" if prefix else entry.name
+            if is_directory:
+                if entry.name not in NESTED_AGENTS_EXCLUDED_DIRECTORIES:
+                    subdirectories.append(path)
+                continue
+            if entry.name != "AGENTS.md" or not prefix:
+                continue
+            if len(files) >= NESTED_AGENTS_MAX_FILES:
+                state["list_truncated"] = True
+                continue
+            # Charge the array's two bracket bytes to the first entry, so the budget
+            # covers everything this list makes the document emit.
+            name_bytes = serialized_display_length(path) + (1 if files else 2)
+            if reported_bytes + name_bytes > NESTED_AGENTS_MAX_LIST_BYTES:
+                state["list_truncated"] = True
+                continue
+            reported_bytes += name_bytes
+            files.append(path)
+        for path in subdirectories:
+            flags = os.O_RDONLY | os.O_CLOEXEC | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0)
+            try:
+                child_descriptor = os.open(
+                    path.rsplit("/", 1)[-1], flags, dir_fd=directory_descriptor
+                )
+            except OSError:
+                state["scan_truncated"] = True
+                continue
+            try:
+                walk(child_descriptor, path, depth + 1)
+            finally:
+                os.close(child_descriptor)
+
+    flags = os.O_RDONLY | os.O_CLOEXEC | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        root_descriptor = os.open(repository, flags)
+    except OSError:
+        return NestedContextPresence((), False, True)
+    try:
+        walk(root_descriptor, "", 0)
+    finally:
+        os.close(root_descriptor)
+    return NestedContextPresence(tuple(files), state["list_truncated"], state["scan_truncated"])
+
+
 def collect_project_context(
     repository: Path,
     *,
@@ -1001,4 +1129,5 @@ def collect_project_context(
         entry_files=entry_files,
         commands=_collect_commands(entry_files),
         directory_tree=_collect_directory_tree(repository),
+        nested_context=collect_nested_agents_presence(repository),
     )

{context_loader-1.2.0 → context_loader-1.3.1}/context_loader/render.py

@@ -19,6 +19,7 @@ from .collect import (
     DirectoryTree,
     ProjectContext,
     TreeEntry,
+    display_text,
     render_agents_selection_audit,
 )
 from .git import RecentCommit, RepositoryState
@@ -39,30 +40,11 @@ class MarkdownRender:
     commands_truncated: bool
 
 
-def _display(value: str) -> str:
-    rendered: list[str] = []
-    for character in value:
-        codepoint = ord(character)
-        if character == "`":
-            rendered.append(r"\x60")
-        elif 0xDC80 <= codepoint <= 0xDCFF:
-            rendered.append(f"\\x{codepoint - 0xDC00:02x}")
-        elif character.isprintable():
-            rendered.append(character)
-        elif codepoint <= 0xFF:
-            rendered.append(f"\\x{codepoint:02x}")
-        elif codepoint <= 0xFFFF:
-            rendered.append(f"\\u{codepoint:04x}")
-        else:
-            rendered.append(f"\\U{codepoint:08x}")
-    return "".join(rendered)
-
-
 def _display_limited(value: str, limit: int) -> str | None:
     rendered: list[str] = []
     used = 0
     for character in value:
-        piece = _display(character)
+        piece = display_text(character)
         size = len(piece.encode())
         if used + size > limit:
             return None
@@ -121,7 +103,7 @@ def _change_lines(state: RepositoryState) -> tuple[list[str], bool]:
     for change in state.changes:
         if len(lines) == MAX_CHANGE_ENTRIES:
             return lines, True
-        line = f"- `{change.status} {_display(change.path)}`"
+        line = f"- `{change.status} {display_text(change.path)}`"
         line_bytes = len(f"{line}\n".encode())
         if used_bytes + line_bytes > MAX_CHANGE_MARKDOWN_BYTES:
             return lines, True
@@ -134,10 +116,10 @@ def _render_git_state(state: RepositoryState) -> str:
     lines = [
         "## Git State",
         "",
-        f"- Branch: `{_display(state.branch)}`",
-        f"- HEAD: `{_display(state.head)}`",
-        f"- Upstream: `{_display(state.upstream)}`",
-        f"- Ahead / behind: `{_display(state.ahead_behind)}`",
+        f"- Branch: `{display_text(state.branch)}`",
+        f"- HEAD: `{display_text(state.head)}`",
+        f"- Upstream: `{display_text(state.upstream)}`",
+        f"- Ahead / behind: `{display_text(state.ahead_behind)}`",
         f"- Worktree: `{state.worktree}`",
         "",
         "### Working Tree Changes",
@@ -170,10 +152,10 @@ def _command_line(command: DeclaredCommand) -> str:
     if command.parse_error:
         return f"- `{command.source}`: unable to parse command declarations."
     assert command.invocation is not None
-    invocation = _display(command.invocation)
+    invocation = display_text(command.invocation)
     if command.target is None:
         return f"- `{invocation}`"
-    return f"- `{invocation}` → `{_display(command.target)}`"
+    return f"- `{invocation}` → `{display_text(command.target)}`"
 
 
 def _bounded_lines(
@@ -262,7 +244,7 @@ def _render_recent_commits(commits: tuple[RecentCommit, ...]) -> str | None:
 
 
 def _tree_line(entry: TreeEntry) -> str:
-    path = _display(entry.path)
+    path = display_text(entry.path)
     if entry.kind == "directory":
         return f"{path}/"
     if entry.kind == "symlink":
@@ -295,7 +277,7 @@ def render_markdown_with_details(state: RepositoryState, project: ProjectContext
             "# Project Context",
             "",
             f"- Schema: `{SCHEMA}`",
-            f"- Repository: `{_display(os.fspath(state.repository))}`",
+            f"- Repository: `{display_text(os.fspath(state.repository))}`",
         )
     )
     commands_section, commands_truncated = _render_commands(project.commands)

{context_loader-1.2.0 → context_loader-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "context-loader"
-version = "1.2.0"
+version = "1.3.1"
 description = "Render deterministic local Git context for any executor"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{context_loader-1.2.0 → context_loader-1.3.1}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "context-loader"
-version = "1.2.0"
+version = "1.3.1"
 description = "Render deterministic local Git context for any executor"
 license = { file = "LICENSE" }
 readme = "README.md"

{context_loader-1.2.0 → context_loader-1.3.1}/tool_cli_contract.json

@@ -46,5 +46,5 @@
   ],
   "schema_version": 1,
   "tool_name": "context-loader",
-  "tool_version": "1.2.0"
+  "tool_version": "1.3.1"
 }