hx-cli 0.2.9__tar.gz → 0.2.10__tar.gz

{hx_cli-0.2.9 → hx_cli-0.2.10}/CHANGELOG.md

@@ -28,6 +28,22 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.10] - 2026-09-29
+
+### Fixed
+
+- `AGENTS.md` at the repository root now applies when HX is started in a
+  subdirectory, followed by each `AGENTS.md` down to that directory.
+- Subagents started with `Task` now follow `~/.hx/AGENTS.md` and the project's
+  `AGENTS.md`, as the main session does.
+- A saved `/effort` level shows on the status bar from the first screen of every
+  new session, not only after `/effort` is run again.
+- `ctrl+l` switches the model and saves it for later sessions, as `/model` does;
+  it used to relabel the status bar only.
+- `/model`, `ctrl+l` and `/effort` open with the cursor on the choice in force.
+
+---
+
 ## [0.2.9] - 2026-09-27
 
 ### Added
@@ -742,7 +758,8 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.9...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.10...HEAD
+[0.2.10]: https://github.com/aletisunil/hx/compare/v0.2.9...v0.2.10
 [0.2.9]: https://github.com/aletisunil/hx/compare/v0.2.8...v0.2.9
 [0.2.8]: https://github.com/aletisunil/hx/compare/v0.2.7...v0.2.8
 [0.2.7]: https://github.com/aletisunil/hx/compare/v0.2.6...v0.2.7

{hx_cli-0.2.9 → hx_cli-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.9
+Version: 0.2.10
 Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://hx.sunilaleti.dev
 Project-URL: Documentation, https://hx.sunilaleti.dev
@@ -762,7 +762,7 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | `./.hx/mcp.json` | project MCP servers |
 | `./.hx/system-prompt.md`, `./.hx/system-prompt-append.md` | project prompt overrides |
 | `./.hx/skills/`, `./.hx/agents/` | project skills and agents |
-| `./AGENTS.md` | project instructions, loaded into every session |
+| `AGENTS.md` | project instructions: the repository root's, then each one down to where HX started |
 
 `AGENTS.md` is the place for things a newcomer would get wrong: how to run the
 tests, conventions, what not to touch. `/init` writes a first draft. It is
@@ -774,6 +774,13 @@ loaded first and the project's `AGENTS.md` after it, so where the two disagree
 the project has the last word. The first session creates it empty, ready to
 fill in; empty, it adds nothing. `hx prompt` and `/prompt` list each one in force.
 
+Started below the repository root - in `services/billing`, say - HX still loads
+the root's `AGENTS.md`, then every `AGENTS.md` on the way down to that directory,
+the nearest last, so a package can refine the repository's rules. A submodule
+counts as part of the repository around it. Nothing above the repository root is
+read; outside a repository only the current directory is.
+Subagents run under the same files as the session that started them.
+
 ---
 
 ## Safety

{hx_cli-0.2.9 → hx_cli-0.2.10}/README.md

@@ -722,7 +722,7 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | `./.hx/mcp.json` | project MCP servers |
 | `./.hx/system-prompt.md`, `./.hx/system-prompt-append.md` | project prompt overrides |
 | `./.hx/skills/`, `./.hx/agents/` | project skills and agents |
-| `./AGENTS.md` | project instructions, loaded into every session |
+| `AGENTS.md` | project instructions: the repository root's, then each one down to where HX started |
 
 `AGENTS.md` is the place for things a newcomer would get wrong: how to run the
 tests, conventions, what not to touch. `/init` writes a first draft. It is
@@ -734,6 +734,13 @@ loaded first and the project's `AGENTS.md` after it, so where the two disagree
 the project has the last word. The first session creates it empty, ready to
 fill in; empty, it adds nothing. `hx prompt` and `/prompt` list each one in force.
 
+Started below the repository root - in `services/billing`, say - HX still loads
+the root's `AGENTS.md`, then every `AGENTS.md` on the way down to that directory,
+the nearest last, so a package can refine the repository's rules. A submodule
+counts as part of the repository around it. Nothing above the repository root is
+read; outside a repository only the current directory is.
+Subagents run under the same files as the session that started them.
+
 ---
 
 ## Safety

{hx_cli-0.2.9 → hx_cli-0.2.10}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - an agent harness for the terminal."""
 
-__version__ = "0.2.9"
+__version__ = "0.2.10"
 
 __all__ = ["__version__"]

{hx_cli-0.2.9 → hx_cli-0.2.10}/src/hx/agents/subagent.py

@@ -59,6 +59,7 @@ class SubagentRunner:
         parent_session_id: str | None = None,
         parent_usage: object | None = None,
         hooks: HookEngine | None = None,
+        project_context: str | None = None,
     ) -> None:
         self.definitions = definitions
         self.provider = provider
@@ -72,6 +73,10 @@ class SubagentRunner:
         self.hooks = hooks
         """Shared with the parent: a hook that guards Bash must guard a subagent's
         Bash too, or the guard is one delegation away from being bypassed."""
+        self.project_context = project_context
+        """The parent's project preamble, AGENTS.md included. A subagent edits the
+        same project under the same rules; without it "never add unit tests" is
+        one delegation away from being ignored."""
         self._active: dict[str, str] = {}
 
     async def run(self, agent_type: str, prompt: str, description: str) -> SubagentResult:
@@ -160,6 +165,7 @@ class SubagentRunner:
             bus=self.bus,
             settings=self.settings,
             model_info=self.models.get_or_default(model) if self.models else None,
+            project_context=self.project_context,
             hooks=self.hooks,
         )
         loop.origin = f"{definition.name} subagent"

{hx_cli-0.2.9 → hx_cli-0.2.10}/src/hx/cli.py

@@ -436,6 +436,7 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
         keep_recent_turns=settings.context.keep_recent_turns,
     )
     instructions = load_instructions(settings.cwd)
+    project_context = build_project_context(settings.cwd, instructions)
 
     checkpoints = CheckpointStore(session, session_checkpoints_dir(session.meta.session_id))
     tools = build_default_registry(shell, jobs, tracker, todos, bus_holder, auth, checkpoints)
@@ -464,6 +465,7 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
         parent_session_id=session.meta.session_id,
         parent_usage=session.usage,
         hooks=hooks,
+        project_context=project_context,
     )
     tools.register(TaskTool(subagents))
 
@@ -484,7 +486,7 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
         settings=settings,
         model_info=model_info,
         skills_index=build_index(list(skills.values())) or None,
-        project_context=build_project_context(settings.cwd, instructions),
+        project_context=project_context,
         instructions=instructions,
         hooks=hooks,
     )

{hx_cli-0.2.9 → hx_cli-0.2.10}/src/hx/core/context.py

@@ -10,7 +10,8 @@ Layout, in order::
     [1] system prompt          static for the session
     [2] tool schemas           deterministic sort: builtins, then mcp__* alphabetical
     [3] skills index           name + description only (progressive disclosure)
-    [4] project context        cwd, git branch, top-level listing, ~/.hx/AGENTS.md, AGENTS.md
+    [4] project context        cwd, git branch, top-level listing, ~/.hx/AGENTS.md,
+                               each AGENTS.md from the repository root down to cwd
     --- breakpoint A (static) ---
     [5] conversation history
     --- breakpoint B (rolling, before the last few turns) ---
@@ -250,20 +251,26 @@ class Instructions:
 def load_instructions(cwd: Path) -> list[Instructions]:
     """Every AGENTS.md in force, least specific first.
 
-    ``~/.hx/AGENTS.md`` follows the user into every project; the project's own
-    ``AGENTS.md`` comes after it, so where the two disagree the more specific
-    one has the last word. A blank or unreadable file is skipped, and running
-    from inside ``$HX_HOME`` - where both paths name the same file - loads it once.
+    ``~/.hx/AGENTS.md`` follows the user into every project; then each
+    ``AGENTS.md`` from the repository root down to ``cwd``. Where two disagree
+    the more specific one comes later and has the last word. A blank or
+    unreadable file is skipped, and a path reached twice - running from inside
+    ``$HX_HOME``, say - is loaded once.
     """
-    from hx.paths import project_instructions_file, tilde, user_instructions_file
+    from hx.paths import project_instructions_files, project_root, tilde, user_instructions_file
 
     user = user_instructions_file()
+    here = cwd.resolve()
+    root = project_root(here)
+    base = root or here
+    candidates = [(f"User instructions ({tilde(user)})", user)]
+    for path in project_instructions_files(here, root):
+        where = path.relative_to(base).as_posix()
+        candidates.append((f"Project instructions ({where})", path))
+
     found: list[Instructions] = []
     seen: set[Path] = set()
-    for heading, path in (
-        (f"User instructions ({tilde(user)})", user),
-        ("Project instructions (AGENTS.md)", project_instructions_file(cwd)),
-    ):
+    for heading, path in candidates:
         body = _read_prompt_file(path)
         if not body or path.resolve() in seen:
             continue
@@ -272,6 +279,17 @@ def load_instructions(cwd: Path) -> list[Instructions]:
     return found
 
 
+INSTRUCTIONS_PREAMBLE = (
+    "The sections below are AGENTS.md files: standing instructions from the user "
+    "and this project, already loaded in full - there is no need to read them "
+    "again. Follow them over your own defaults and habits. Where two disagree, "
+    "the later, more specific one wins."
+)
+"""Said once, ahead of the files. Without it a rule like "no unit tests" reads
+as background next to a request to make something "well covered", and the
+model re-reads the file it was already given to find out whether it counts."""
+
+
 def build_project_context(cwd: Path, instructions: list[Instructions] | None = None) -> str:
     """Static per-session project preamble: cwd, git branch, listing, AGENTS.md contents.
 
@@ -291,8 +309,11 @@ def build_project_context(cwd: Path, instructions: list[Instructions] | None = N
     if entries:
         lines.append("Top level: " + ", ".join(entries[:60]))
 
-    for loaded in load_instructions(cwd) if instructions is None else instructions:
-        lines.append(f"\n# {loaded.heading}\n\n{loaded.text}")
+    loaded = load_instructions(cwd) if instructions is None else instructions
+    if loaded:
+        lines.append(f"\n{INSTRUCTIONS_PREAMBLE}")
+    for entry in loaded:
+        lines.append(f"\n# {entry.heading}\n\n{entry.text}")
 
     return "\n".join(lines)
 

{hx_cli-0.2.9 → hx_cli-0.2.10}/src/hx/paths.py

@@ -217,9 +217,50 @@ def user_instructions_file() -> Path:
     return user_home() / "AGENTS.md"
 
 
-def project_instructions_file(cwd: Path | None = None) -> Path:
-    """The project's ``AGENTS.md``, at the root of the working directory."""
-    return (cwd or Path.cwd()) / "AGENTS.md"
+def project_root(cwd: Path | None = None) -> Path | None:
+    """The repository ``cwd`` sits in: the nearest directory holding ``.git``.
+
+    ``.git`` is a directory in a clone and a file in a worktree or submodule.
+    A submodule is part of the repository around it, so the walk carries on
+    past one to the superproject. ``None`` outside a repository.
+    """
+    start = (cwd or Path.cwd()).resolve()
+    submodule: Path | None = None
+    for directory in (start, *start.parents):
+        marker = directory / ".git"
+        if marker.is_dir() or (marker.is_file() and not _is_submodule(marker)):
+            return directory
+        if marker.is_file() and submodule is None:
+            submodule = directory
+    return submodule
+
+
+def _is_submodule(marker: Path) -> bool:
+    """Whether a ``.git`` file points into a superproject's ``.git/modules``."""
+    try:
+        text = marker.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return False
+    return text.startswith("gitdir:") and "/modules/" in text.replace("\\", "/")
+
+
+def project_instructions_files(cwd: Path, root: Path | None) -> list[Path]:
+    """Every ``AGENTS.md`` that governs ``cwd``, least specific first.
+
+    From the repository root down to ``cwd``, one candidate per directory, so
+    starting HX in ``src/app`` still finds the root's file - and ``src/app``'s
+    own, which comes last and so has the last word. Outside a repository only
+    ``cwd`` itself is looked at: walking up from an arbitrary directory would
+    pick up whatever happens to sit in its parents.
+
+    ``root`` is :func:`project_root` of ``cwd``, passed in because the caller
+    needs it too and finding it walks the file system.
+    """
+    here = cwd.resolve()
+    if root is None:
+        return [here / "AGENTS.md"]
+    chain = [here, *here.parents]
+    return [directory / "AGENTS.md" for directory in reversed(chain[: chain.index(root) + 1])]
 
 
 def ensure_user_dirs() -> None:

{hx_cli-0.2.9 → hx_cli-0.2.10}/src/hx/tui/commands.py

@@ -107,7 +107,10 @@ async def cmd_model(ctx: CommandContext, args: str) -> None:
     from hx.providers.models import ModelRegistry
     from hx.tui.views.pickers import ModelPicker
 
-    registry: ModelRegistry = ctx.app.models
+    registry: ModelRegistry | None = ctx.app.models
+    if registry is None:
+        ctx.app.notice("No model registry is loaded.", "warning")
+        return
     models = _reachable(ctx, registry.all())
     if not models:
         # A recorded failure replaces the remedy rather than trailing it:
@@ -780,7 +783,9 @@ async def cmd_mode(ctx: CommandContext, args: str) -> None:
 
 
 INIT_PROMPT = """\
-Write an AGENTS.md for this project, at its root.
+Write an AGENTS.md in {directory}, the directory HX was started in. Any AGENTS.md
+between the repository root and there is loaded before it, so leave out what
+those already say.
 
 Read enough of the codebase to be accurate. Cover: what the project is, how to
 build, test and lint it, the layout of the source tree, and any conventions a
@@ -792,7 +797,7 @@ If AGENTS.md already exists, improve it rather than replacing it wholesale."""
 
 async def cmd_init(ctx: CommandContext, args: str) -> None:
     """``/init`` - generate an AGENTS.md describing this project."""
-    await ctx.app.submit_to_model(INIT_PROMPT)
+    await ctx.app.submit_to_model(INIT_PROMPT.format(directory=ctx.settings.cwd))
 
 
 async def cmd_configure(ctx: CommandContext, args: str) -> None:

{hx_cli-0.2.9 → hx_cli-0.2.10}/src/hx/tui/runtime.py

@@ -785,17 +785,9 @@ class HXSession:
             await self._run_command(f"/{chosen}")
 
     async def _open_models(self) -> None:
-        from hx.tui.views.pickers import ModelPicker
-
-        registry = self.extra.get("models")
-        if registry is None:
-            self._notice("no model registry is loaded", "warning")
-            return
-        current = getattr(getattr(self.loop, "model_info", None), "id", "") or ""
-        chosen = await self.ask(ModelPicker(list(registry.all()), current))
-        if chosen:
-            self.view.dock.status.set_model(chosen)
-            self._notice(f"model set to {chosen}")
+        # The same path as `/model`: a picker that only relabelled the status
+        # bar left the session on the old model and the choice unsaved.
+        await self._run_command("/model")
 
     def _commands(self) -> list[Any]:
         return list(self.commands.all()) if self.commands is not None else []
@@ -963,7 +955,8 @@ class HXSession:
             asyncio.create_task(self._open_commands())  # noqa: RUF006
             return
         if name == "ctrl+l":
-            asyncio.create_task(self._open_models())  # noqa: RUF006
+            # Tracked like a typed `/model`, so an interrupt cancels it too.
+            self._side = asyncio.create_task(self._open_models())
             return
         # Only here, on the way to the prompt: nothing else binds shift+enter,
         # so an approval or a picker has to keep the enter it was sent. Not
@@ -1334,8 +1327,13 @@ class HXSession:
         )
         model = getattr(self.loop, "model_info", None)
         if model is not None:
-            status.set_model(getattr(model, "id", "") or "")
+            model_id = getattr(model, "id", "") or ""
+            status.set_model(model_id, subscription=bool(getattr(model, "is_subscription", False)))
             status.set_context(0, getattr(model, "context_window", 0) or 0)
+            # The saved effort is in force from the first turn; a bar that only
+            # shows it once /effort is run again reads as the choice not sticking.
+            if self.models is not None:
+                status.set_effort(self.models.displayed_effort(model_id))
 
 
 async def run_session(

{hx_cli-0.2.9 → hx_cli-0.2.10}/src/hx/tui/views/pickers.py

@@ -61,6 +61,13 @@ class Picker(Widget, Framed):
         two-hundred model catalogue, with two thirds of a tall window empty
         underneath."""
         self._refresh()
+        # Open on what is already in force, so enter alone keeps it and the
+        # arrow and the ✓ do not point at different rows.
+        current = self.current_value()
+        self.selected = next(
+            (index for index, (value, _cells) in enumerate(self._rows) if value == current),
+            0,
+        )
 
     # -- the room this has to work with ------------------------------------
 
@@ -260,7 +267,11 @@ class ModelPicker(Picker):
         # The same matcher `/model <query>` uses, so typing here narrows
         # exactly the way typing there does.
         matches = match_models(self.models, query)
-        return [(model.id, self._cells(model)) for model in matches[: self.LIMIT]]
+        shown = matches[: self.LIMIT]
+        # The model in force stays listed however far down it sorts, or the
+        # picker opens on some other row with no ✓ anywhere.
+        shown += [model for model in matches[self.LIMIT :] if model.id == self.current]
+        return [(model.id, self._cells(model)) for model in shown]
 
     def _cells(self, model: Any) -> list[str]:
         mode = str(model.cache_mode)
@@ -310,7 +321,15 @@ class EffortPicker(Picker):
         super().__init__()
 
     def current_value(self) -> str | None:
-        return self.current or DEFAULT_EFFORT_ROW
+        if self.current is None:
+            return DEFAULT_EFFORT_ROW
+        if self.current in self.info.reasoning_levels:
+            return self.current
+        # Clamped for this model: the level it actually runs at is the one in
+        # force, and a row that matches nothing would open on "default".
+        from hx.providers.codex_catalogue import resolve_effort
+
+        return resolve_effort(self.current, self.info)
 
     def rows(self, query: str) -> list[tuple[str, list[str]]]:
         default_level = self.info.default_reasoning_level or "the model's default"

{hx_cli-0.2.9 → hx_cli-0.2.10}/tests/e2e/test_commands.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import json
 import re
+import time
 
 from tests.e2e.conftest import HX, SANDBOX, SANDBOX_STATUS
 from tests.e2e.stub import GPT5, Stub, call, say
@@ -86,6 +88,77 @@ def test_model_picker_switches_the_model(hx: HX, stub: Stub) -> None:
     assert stub.requests[0].model == GPT5
 
 
+def test_ctrl_l_switches_the_model_and_remembers_it(hx: HX, stub: Stub) -> None:
+    """ctrl+l opens the model picker on the model in force; choosing another routes the next
+    turn to it and saves it for the next session, exactly as /model does."""
+    stub.script(say("Answered by GPT-5."))
+    term = hx.tui()
+    term.press("ctrl+l")
+    screen = term.wait_for("Select model")
+    term.snapshot("ctrl+l model picker")
+    assert re.search(r"→ ✓ anthropic/claude-sonnet-4\.5\s", screen), "opens on the current model"
+
+    term.type("gpt")
+    term.wait_for(lambda s: "deepseek" not in s)
+    term.press("enter")
+    term.wait_for("Model set to openai/gpt-5")
+    term.submit("who are you?")
+    term.wait_for("Answered by GPT-5.")
+    assert stub.requests[0].model == GPT5
+    saved = json.loads((hx.hx_home / "settings.json").read_text())
+    assert saved["models"]["model"] == GPT5
+
+
+def test_effort_carries_into_every_new_session(hx: HX) -> None:
+    """A saved reasoning effort is in force - and on the status bar - from the first screen of
+    a new session, through /clear and a restart; the picker opens on it, and a new pick
+    replaces it for the sessions after."""
+    codex = "openai-codex/gpt-5.6-terra"
+    (hx.hx_home / "auth.json").write_text(
+        json.dumps(
+            {
+                "openai-codex": {
+                    "type": "oauth",
+                    "access": "e2e-access",
+                    "refresh": "e2e-refresh",
+                    "expires": time.time() + 30 * 86_400,
+                    "account_id": "acct-e2e",
+                }
+            }
+        )
+    )
+    (hx.hx_home / "auth.json").chmod(0o600)
+    # Fresh, so nothing reaches for the real Codex catalogue at startup.
+    (hx.hx_home / "models.json").write_text(json.dumps({"fetched_at": time.time(), "models": []}))
+    (hx.hx_home / "settings.json").write_text(json.dumps({"models": {"reasoning_effort": "high"}}))
+    env = {"HX_MODEL": codex}
+
+    term = hx.tui(env=env)
+    term.wait_for(lambda s: s.splitlines()[-1].rstrip().endswith("gpt-5.6-terra (sub) · high"))
+    term.snapshot("a new session starts at the saved effort")
+
+    term.submit("/effort")
+    screen = term.wait_for("Reasoning effort for gpt-5.6-terra")
+    term.snapshot("/effort opens on the level in force")
+    assert re.search(r"→ ✓ high\s*$", screen, re.MULTILINE)
+    term.press("down")
+    term.press("enter")
+    term.wait_for("Reasoning effort set to xhigh.")
+    assert term.lines()[-1].rstrip().endswith("gpt-5.6-terra (sub) · xhigh")
+    saved = json.loads((hx.hx_home / "settings.json").read_text())
+    assert saved["models"]["reasoning_effort"] == "xhigh"
+
+    term.submit("/clear")
+    term.wait_for(lambda s: "Reasoning effort set" not in s)
+    assert term.lines()[-1].rstrip().endswith("gpt-5.6-terra (sub) · xhigh")
+    term.press("ctrl+d")
+    term.wait_exit()
+
+    again = hx.tui(env=env)
+    again.wait_for(lambda s: s.splitlines()[-1].rstrip().endswith("gpt-5.6-terra (sub) · xhigh"))
+    again.snapshot("the next session starts at the new effort")
+
+
 def test_ctrl_p_palette_runs_a_command(hx: HX) -> None:
     """ctrl+p opens the palette; filtering and enter runs the command."""
     term = hx.tui(rows=40)

{hx_cli-0.2.9 → hx_cli-0.2.10}/tests/e2e/test_extend.py

@@ -7,7 +7,7 @@ import os
 import sys
 from pathlib import Path
 
-from tests.e2e.conftest import HX
+from tests.e2e.conftest import HX, git
 from tests.e2e.stub import GPT5, SONNET, Stub, call, say
 
 ECHO_SERVER = Path(__file__).parent / "fixtures" / "echo_server.py"
@@ -105,6 +105,55 @@ def test_blank_unreadable_and_shared_agents_md_are_harmless(hx: HX, stub: Stub)
     assert "# Project instructions" not in system
 
 
+def test_agents_md_governs_a_session_started_deep_in_the_repo_and_its_subagents(
+    hx: HX, stub: Stub
+) -> None:
+    """Started in a package two levels below the repository root, HX still loads the root's
+    AGENTS.md, then the package's own after it, and nothing from outside the repository; a
+    subagent the model delegates the work to is held to the same rules."""
+    git(hx.project, "init", "-q")
+    write(hx.project.parent / "AGENTS.md", "OUTSIDE-RULE: not this repository's.\n")
+    write(hx.project / "AGENTS.md", "ROOT-RULE: never create unit tests; verify end to end.\n")
+    write(hx.project / "services" / "AGENTS.md", "")
+    write(hx.project / "services" / "billing" / "AGENTS.md", "PKG-RULE: money is integer cents.\n")
+    pricing = write(
+        hx.project / "services" / "billing" / "pricing.py",
+        "def subtotal(items):\n    return sum(i['cents'] * i['qty'] for i in items)\n",
+    )
+    stub.script(
+        call(
+            "Task",
+            subagent_type="general",
+            prompt="Add apply_discount(total, percent) to pricing.py.",
+            description="add discount",
+        ),
+        call("Read", file_path=str(pricing)),
+        say("REPORT: added apply_discount; no test files, per AGENTS.md."),
+        say("Done, no test files added."),
+    )
+    result = hx.run(
+        "-p", "add a discount helper", "--mode", "bypass", cwd=pricing.parent, check=True
+    )
+    assert result.stdout.strip() == "Done, no test files added."
+
+    parent, child, child_after_read, _parent_after = stub.requests
+    for request in (parent, child, child_after_read):
+        system = request.system
+        assert "OUTSIDE-RULE" not in system
+        root = system.index("# Project instructions (AGENTS.md)")
+        package = system.index("# Project instructions (services/billing/AGENTS.md)")
+        assert root < system.index("ROOT-RULE: never create unit tests") < package
+        assert package < system.index("PKG-RULE: money is integer cents.")
+        assert "Project instructions (services/AGENTS.md)" not in system, "blank is skipped"
+        assert system.count("Follow them over your own defaults") == 1
+    assert child.system.startswith("Carry out the task"), "the subagent keeps its own prompt"
+
+    listed = hx.run("prompt", cwd=pricing.parent, check=True).stderr
+    assert f"[instructions] {hx.project / 'AGENTS.md'}\n" in listed
+    assert f"[instructions] {pricing.parent / 'AGENTS.md'}\n" in listed
+    assert str(hx.project.parent / "AGENTS.md") not in listed
+
+
 def test_skill_is_indexed_then_loaded(hx: HX, stub: Stub) -> None:
     """Only a skill's name and description are sent up front; calling Skill loads its body."""
     write(