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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: context-loader
-Version: 1.2.0
+Version: 1.3.0
 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.0**. 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.0'
 ```
 
 ```bash
-pip install 'context-loader==1.2.0'
+pip install 'context-loader==1.3.0'
 ```
 
 ```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.0`. 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.0'
 ```
 
 Install via `pip`:
 
 ```bash
-pip install 'context-loader==1.2.0'
+pip install 'context-loader==1.3.0'
 ```
 
-For development or source-based installs tracking current repository (`1.2.0`):
+For development or source-based installs tracking current repository (`1.3.0`):
 
 ```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.
 
@@ -344,10 +344,10 @@ 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.0"
   },
   "repository": {
     "requested_path": "/canonical/requested/path",
@@ -377,6 +377,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 +394,60 @@ 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 4 KiB of
+path bytes); `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.
+Paths are sanitized with the same escaping the Markdown uses for repository-derived text, so the
+document is always valid UTF-8. 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.0`. 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 +462,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.
@@ -469,6 +505,8 @@ 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, and at most 32 reported paths;
+  file contents are never read
 - Working-tree changes: 100 paths and 4 KiB
 - Recent commits: 8
 - Git subprocess output: 16 MiB (bounded while reading)
@@ -507,7 +545,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.0 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 +560,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.0}/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.0**. 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.0'
 ```
 
 ```bash
-pip install 'context-loader==1.2.0'
+pip install 'context-loader==1.3.0'
 ```
 
 ```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.0`. 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.0'
 ```
 
 Install via `pip`:
 
 ```bash
-pip install 'context-loader==1.2.0'
+pip install 'context-loader==1.3.0'
 ```
 
-For development or source-based installs tracking current repository (`1.2.0`):
+For development or source-based installs tracking current repository (`1.3.0`):
 
 ```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.
 
@@ -133,10 +133,10 @@ 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.0"
   },
   "repository": {
     "requested_path": "/canonical/requested/path",
@@ -166,6 +166,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 +183,60 @@ 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 4 KiB of
+path bytes); `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.
+Paths are sanitized with the same escaping the Markdown uses for repository-derived text, so the
+document is always valid UTF-8. 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.0`. 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 +251,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.
@@ -258,6 +294,8 @@ 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, and at most 32 reported paths;
+  file contents are never read
 - Working-tree changes: 100 paths and 4 KiB
 - Recent commits: 8
 - Git subprocess output: 16 MiB (bounded while reading)
@@ -296,7 +334,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.0 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 +349,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.0}/context_loader/__init__.py

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

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

@@ -20,14 +20,18 @@ from .collect import (
     AgentsSelectionAudit,
     AgentsSelectionInputError,
     CollectedFile,
+    NestedContextPresence,
     ProjectContext,
     collect_project_context,
 )
 from .git import ContextLoaderError, collect_repository
-from .render import render_markdown_with_details, rendered_source_contents
+from .render import _display, 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
 TOOL_NAME = "context-loader"
 
 _STATUS_CODE_BY_MESSAGE = {
@@ -81,6 +85,7 @@ class ProjectContextResult:
     context_sha256: str
     warnings: tuple[str, ...]
     statuses: tuple[ContextStatus, ...]
+    nested_context: NestedContextPresence
 
 
 def _text_sha256(content: str) -> str:
@@ -185,11 +190,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(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 +249,7 @@ def load_project_context(
         context_sha256=hashlib.sha256(rendered.output).hexdigest(),
         warnings=(),
         statuses=statuses,
+        nested_context=project.nested_context,
     )
 
 
@@ -309,6 +320,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(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),

{context_loader-1.2.0 → context_loader-1.3.0}/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.0}/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,82 @@ def _collect_directory_tree(root: Path) -> DirectoryTree:
     return DirectoryTree(tuple(collected), truncated)
 
 
+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
+            name_bytes = len(path.encode("utf-8", errors="surrogateescape"))
+            name_bytes += 1 if files else 0
+            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 +1094,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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "context-loader"
-version = "1.2.0"
+version = "1.3.0"
 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.0}/pyproject.toml.orig

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

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

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