hx-cli 0.2.16__tar.gz → 0.2.17__tar.gz

{hx_cli-0.2.16 → hx_cli-0.2.17}/CHANGELOG.md

@@ -28,6 +28,49 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.17] - 2026-10-18
+
+### Security
+
+- The API keys HX itself signs in with (`HX_OPENROUTER_API_KEY`, `OPENROUTER_API_KEY`, and the
+  Tavily and Devin keys) are no longer passed to the commands it runs. An auto-approved `env`
+  used to put them straight into the model's context.
+- `xxd -r`, `xxd in out`, `uniq in out` and `sort --compress-program` now ask before they run.
+  They write files or run a program, but they were auto-approved as read-only commands.
+- A long option cut short now counts as the full option, as getopt_long and git read it.
+  `sort --compress=sh`, `sort --out=f`, `git grep --open-files-in=sh` and `git branch --del`
+  were auto-approved as read-only. So were `xxd in -p` and macOS `uniq in -c`, which write a
+  file named after the flag.
+
+### Fixed
+
+- A command that reads stdin (`cat`, `read`, `ssh host ls`) no longer breaks the shell. It used
+  to swallow every later command, which then reported success without running. Commands now
+  get end-of-file on stdin, and a command with an unclosed quote fails on its own.
+- Background jobs no longer read from the terminal, so a dev server cannot take keystrokes
+  from the prompt.
+- Background jobs get `HX=1` and `TERM=dumb`, the same as other commands. A tool that colours
+  its output for a real terminal used to write escape codes into the job's log.
+- Non-ASCII command output no longer shows `�` where a read split a character.
+- An edit to a CRLF file keeps CRLF on every line. Each edit used to rewrite the whole file
+  with LF, and the diff did not show it. `old_string` with plain newlines now matches there.
+- A hashline replacement that ends with a newline no longer adds a blank line after it.
+- Edit and Write keep a file's mode, so a script stays executable, and write through a
+  symlink instead of replacing it with a regular file.
+- With `--cwd`, or `hx resume` from another directory, the approval shows the diff of the
+  file the edit will change. It used to read a relative path from the shell's directory.
+- An edit's `+N -M` and its diff now include changed lines that start with `--` or `++`,
+  such as SQL comments.
+- "Always allow" on a command HX cannot split into parts, such as a heredoc with an
+  apostrophe, is now honoured in later sessions instead of asking again.
+- Counts of one read in the singular: "read 1 line", "1 result", "1 match", "1 tool".
+- Write reports the number of lines the way Read numbers them. A file ending in a newline
+  was reported one line longer.
+- The status bar shortens a long project path from its start, so the project's name and
+  branch stay visible. Before the first request, the cache field reads "no cache".
+
+---
+
 ## [0.2.16] - 2026-10-13
 
 ### Fixed
@@ -915,7 +958,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.16...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.17...HEAD
+[0.2.17]: https://github.com/aletisunil/hx/compare/v0.2.16...v0.2.17
 [0.2.16]: https://github.com/aletisunil/hx/compare/v0.2.15...v0.2.16
 [0.2.15]: https://github.com/aletisunil/hx/compare/v0.2.14...v0.2.15
 [0.2.14]: https://github.com/aletisunil/hx/compare/v0.2.13...v0.2.14

{hx_cli-0.2.16 → hx_cli-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.16
+Version: 0.2.17
 Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://hx.sunilaleti.dev
 Project-URL: Documentation, https://hx.sunilaleti.dev
@@ -871,6 +871,9 @@ temp dir, credential paths (`~/.ssh`, `~/.aws`, and HX's own `auth.json`) are
 unreadable and unwritable - even inside the project, and even before they
 exist - and outbound network is off. If neither backend is present the
 status bar says `no-sandbox` rather than implying protection that is not there.
+The API keys HX signs in with (`HX_OPENROUTER_API_KEY`, `OPENROUTER_API_KEY`,
+and the Tavily and Devin keys) are removed from the environment of every
+command it runs.
 
 Modes cycle with shift+tab: `plan` (read-only — mutating tools are not even
 offered to the model), `default`, `acceptEdits`, `bypass`.

{hx_cli-0.2.16 → hx_cli-0.2.17}/README.md

@@ -830,6 +830,9 @@ temp dir, credential paths (`~/.ssh`, `~/.aws`, and HX's own `auth.json`) are
 unreadable and unwritable - even inside the project, and even before they
 exist - and outbound network is off. If neither backend is present the
 status bar says `no-sandbox` rather than implying protection that is not there.
+The API keys HX signs in with (`HX_OPENROUTER_API_KEY`, `OPENROUTER_API_KEY`,
+and the Tavily and Devin keys) are removed from the environment of every
+command it runs.
 
 Modes cycle with shift+tab: `plan` (read-only — mutating tools are not even
 offered to the model), `default`, `acceptEdits`, `bypass`.

{hx_cli-0.2.16 → hx_cli-0.2.17}/src/hx/__init__.py

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

{hx_cli-0.2.16 → hx_cli-0.2.17}/src/hx/cli.py

@@ -27,6 +27,7 @@ from typing import Any
 
 from hx import __version__
 from hx.paths import auth_file
+from hx.text import count
 
 USAGE = """\
 hx - an agent harness for the terminal
@@ -1033,7 +1034,9 @@ def run_mcp_command(args: list[str]) -> int:
                 print(f"{status.name:<20} {status.error} - run `hx mcp login {status.name}`")
                 continue
             mark = "ok" if status.connected else "unavailable"
-            detail = f" - {status.error}" if status.error else f" ({status.tool_count} tools)"
+            detail = (
+                f" - {status.error}" if status.error else f" ({count(status.tool_count, 'tool')})"
+            )
             print(f"{status.name:<20} {mark}{detail}")
         return 0
 
@@ -1118,7 +1121,7 @@ def _mcp_login(config: Any) -> int:
 
     status = asyncio.run(_probe_servers([config]))[0]
     if status.connected:
-        print(f"Signed in to {config.name}: {status.tool_count} tools available.")
+        print(f"Signed in to {config.name}: {count(status.tool_count, 'tool')} available.")
         return 0
     print(f"Signed in, but {config.name} is still unavailable: {status.error}", file=sys.stderr)
     return 1

{hx_cli-0.2.16 → hx_cli-0.2.17}/src/hx/core/loop.py

@@ -52,10 +52,12 @@ from hx.core.session import Environment
 from hx.core.usage import TurnUsage, compute_cost
 from hx.hooks.spec import HookOutcome
 from hx.providers.base import ProviderError, ProviderRequest, StreamDelta, StreamEnd
+from hx.text import count
 from hx.tools.base import ToolContext, ToolResult
 
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable, Sequence
+    from pathlib import Path
 
     from hx.config import Settings
     from hx.core.compaction import Compactor
@@ -877,7 +879,7 @@ class AgentLoop:
         from hx.permissions.engine import PermissionRequest
 
         tool = self.tools.get(call.name)
-        detail, detail_kind = _permission_detail(call)
+        detail, detail_kind = _permission_detail(call, self.settings.cwd)
         request = PermissionRequest(
             tool_name=call.name,
             specifier=tool.permission_specifier(call.input),
@@ -1032,7 +1034,7 @@ def _parse_tool_input(raw: str | None) -> dict[str, Any]:
     return parsed if isinstance(parsed, dict) else {}
 
 
-def _permission_detail(call: ToolUseBlock) -> tuple[str, str]:
+def _permission_detail(call: ToolUseBlock, cwd: Path) -> tuple[str, str]:
     """What the approval shows, and what kind of thing it is.
 
     For an edit this previews the change against the file on disk, so the user
@@ -1042,18 +1044,29 @@ def _permission_detail(call: ToolUseBlock) -> tuple[str, str]:
     the text meant a file whose first line was ``---`` - YAML front matter, a
     markdown rule - was treated as a diff and run through a painter that
     strips exactly those lines, leaving the user approving a blank space.
+
+    The path is resolved against the session's directory, the way the tool
+    resolves it. HX never changes its own working directory, so under
+    ``--cwd`` - or a session resumed from somewhere else - a relative path
+    read from the process directory previewed a different file, or none, and
+    the user approved "no change" for an edit that changed something.
     """
     if call.name == "Bash":
         return str(call.input.get("command", "")), "command"
 
     if call.name in {"Edit", "Write"} and (raw_path := call.input.get("file_path")):
-        from pathlib import Path
-
-        from hx.tools.edit import apply_hashline, parse_edits, parse_hashline, unified_diff
+        from hx.tools.edit import (
+            apply_edits,
+            apply_hashline,
+            parse_edits,
+            parse_hashline,
+            unified_diff,
+        )
+        from hx.tools.read import read_exact, resolve_path
 
-        path = Path(str(raw_path))
+        path = resolve_path(str(raw_path), cwd)
         try:
-            before = path.read_text(encoding="utf-8") if path.is_file() else ""
+            before = read_exact(path) if path.is_file() else ""
             if call.name == "Write":
                 after = str(call.input.get("content", ""))
             elif call.input.get("hashline"):
@@ -1062,11 +1075,7 @@ def _permission_detail(call: ToolUseBlock) -> tuple[str, str]:
                 # filename and the user approves an edit they never saw.
                 after = apply_hashline(before, parse_hashline(call.input))
             else:
-                after = before
-                for edit in parse_edits(call.input):
-                    after = after.replace(
-                        edit.old_string, edit.new_string, -1 if edit.replace_all else 1
-                    )
+                after = apply_edits(before, parse_edits(call.input))
             diff = unified_diff(before, after, str(path))
             return (diff, "diff") if diff else (f"{path} (no change)", "text")
         except Exception:
@@ -1103,7 +1112,7 @@ scroll is a prompt they stop reading."""
 
 def _one_value(value: Any, limit: int) -> str:
     if isinstance(value, list):
-        return f"[{len(value)} items]"
+        return f"[{count(len(value), 'item')}]"
     if isinstance(value, dict):
         return "{…}"
     if isinstance(value, str) and len(value) > limit:

{hx_cli-0.2.16 → hx_cli-0.2.17}/src/hx/permissions/engine.py

@@ -144,6 +144,12 @@ class PermissionEngine:
         if request.tool_name == "Bash" and request.specifier:
             parsed = parse(request.specifier)
             if parsed.unparseable:
+                # A rule holding the whole command verbatim grants exactly what it
+                # names, so it covers what cannot be decomposed - it is what "always
+                # allow" saves for such a command. Returning before looking made
+                # that saved rule ask again in every later session. Ask still wins.
+                if not self._match(request, Decision.ASK) and (exact := self._exact_allow(request)):
+                    return PermissionOutcome(Decision.ALLOW, "matched an allow rule", exact)
                 return PermissionOutcome(
                     Decision.ASK,
                     "command could not be decomposed; approving it blind is not safe",
@@ -219,11 +225,11 @@ class PermissionEngine:
             return None
 
         # A rule holding the whole command verbatim: exact, so it grants no more
-        # than the string it names. This is what covers a command that cannot be
-        # decomposed, and what keeps hand-written full-command rules working.
-        for rule in candidates:
-            if rule.specifier == request.specifier:
-                return rule
+        # than the string it names. This is what keeps hand-written full-command
+        # rules working; :meth:`evaluate` also consults it for a command that
+        # cannot be decomposed.
+        if exact := self._exact_allow(request):
+            return exact
 
         parsed = parse(request.specifier)
         if not parsed.segments or parsed.unparseable:
@@ -244,6 +250,26 @@ class PermissionEngine:
             first = first or covering
         return first
 
+    def _exact_allow(self, request: PermissionRequest) -> Rule | None:
+        """An allow rule whose specifier is this request's, character for character.
+
+        Compared stripped, as both sides are by the time they mean anything: a
+        rule's specifier is stripped as it is parsed, and Bash strips a command
+        before running it.
+        """
+        specifier = (request.specifier or "").strip()
+        return next(
+            (
+                rule
+                for rule in self.rules
+                if rule.decision is Decision.ALLOW
+                and rule.tool in {request.tool_name, "*"}
+                and rule.specifier is not None
+                and rule.specifier == specifier
+            ),
+            None,
+        )
+
     def _match_allow_each(
         self,
         request: PermissionRequest,

{hx_cli-0.2.16 → hx_cli-0.2.17}/src/hx/permissions/parser.py

@@ -132,18 +132,37 @@ MUTATING_FLAGS: dict[str, frozenset[str]] = {
         {"-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprintf", "-fls"}
     ),
     "fd": frozenset({"-x", "--exec", "-X", "--exec-batch"}),
-    "sort": frozenset({"-o", "--output"}),
+    "sort": frozenset({"-o", "--output", "--compress-program"}),
     "tree": frozenset({"-o"}),
     "date": frozenset({"-s", "--set"}),
     "rg": frozenset({"--pre"}),
     "yq": frozenset({"-i", "--inplace"}),
+    # Any word starting -r reverts: xxd reads `-r`, `-rp` and `-revert` alike.
+    "xxd": frozenset({"-r"}),
 }
 """Flags that turn a read-only command into a writing or executing one.
 
 ``sed`` edits in place under ``-i``, ``find`` runs arbitrary programs under
-``-exec`` and unlinks under ``-delete``, ``sort -o`` overwrites its own input.
-Treating the executable name alone as read-only allowed all three through
-unprompted.
+``-exec`` and unlinks under ``-delete``, ``sort -o`` overwrites its own input,
+``sort --compress-program`` runs whatever it names and ``xxd -r`` turns a hex
+dump back into bytes - into a file, given one. Treating the executable name
+alone as read-only allowed them all through unprompted.
+"""
+
+OUTPUT_OPERAND_COMMANDS: dict[str, frozenset[str]] = {
+    # uniq [OPTION]... [INPUT [OUTPUT]]
+    "uniq": frozenset({"-f", "--skip-fields", "-s", "--skip-chars", "-w", "--check-chars"}),
+    # xxd [options] [infile [outfile]]
+    "xxd": frozenset(
+        {"-c", "-cols", "-g", "-groupsize", "-l", "-len", "-n", "-name", "-o", "-offset"}
+        | {"-s", "-seek", "-R"}
+    ),
+}
+"""Commands that write a file named by their second operand, with no flag at all.
+
+``uniq in out`` and ``xxd in out`` overwrite ``out``. The value is the options
+that take a separate argument, so ``uniq -f 1 in`` is read as one operand, not
+two.
 """
 
 GIT_READ_ONLY_SUBCOMMANDS = frozenset(
@@ -602,6 +621,8 @@ def is_read_only(segment: CommandSegment) -> bool:
         return not _env_runs_a_command(segment.args)
     if segment.executable in PROGRAM_TEXT_COMMANDS and _program_text_writes(segment):
         return False
+    if segment.executable in OUTPUT_OPERAND_COMMANDS and _names_an_output(segment):
+        return False
     return not _has_flag(
         segment.args,
         MUTATING_FLAGS.get(segment.executable, frozenset()),
@@ -640,6 +661,31 @@ grounds to call the command read-only: ``awk -f prog.awk`` runs whatever
 """
 
 
+def _names_an_output(segment: CommandSegment) -> bool:
+    """True when the command was given an output file as its second operand.
+
+    Counting errs towards two: an option this does not know to take a value
+    makes its value look like an operand, which prompts - never the reverse.
+    Options end at the first operand, as for xxd and BSD uniq: there ``xxd in
+    -p`` and ``uniq in -c`` write files named ``-p`` and ``-c``. GNU uniq reads
+    that ``-c`` as an option, and the command only prompts where it need not.
+    """
+    takes_value = OUTPUT_OPERAND_COMMANDS[segment.executable]
+    operands = 0
+    options_done = False
+    args = iter(segment.args)
+    for arg in args:
+        if not options_done and arg == "--":
+            options_done = True
+        elif not options_done and arg.startswith("-") and arg != "-":
+            if arg in takes_value:
+                next(args, None)
+        else:
+            operands += 1
+            options_done = True
+    return operands >= 2
+
+
 def _program_text_writes(segment: CommandSegment) -> bool:
     """True when the program handed to ``awk``/``sed`` can write or execute."""
     if _has_option(segment.args, PROGRAM_FILE_OPTIONS[segment.executable]):
@@ -710,13 +756,15 @@ def _split_option(arg: str, options: tuple[str, ...]) -> tuple[str, str | None]
     Three spellings reach the same option and a shell accepts all three:
     separate (``-e`` then the script), ``=``-attached (``--expression=…``) and,
     for short options, packed into the same word (``-e'w out'``). Missing the
-    last one let a writing script through unread.
+    last one let a writing script through unread. A long option may also be cut
+    short (``--expr=…``) - see :func:`_abbreviates`.
     """
     if arg in options:
         return arg, None
     name, sep, value = arg.partition("=")
-    if sep and name in options:
-        return name, value
+    option = next((o for o in options if name == o or _abbreviates(name, o)), None)
+    if option is not None:
+        return option, value if sep else None
     if len(arg) > 2 and arg.startswith("-") and not arg.startswith("--") and arg[:2] in options:
         return arg[:2], arg[2:]
     return None
@@ -745,12 +793,14 @@ def _option_values(args: tuple[str, ...], options: tuple[str, ...]) -> list[str]
     return values
 
 
-ATTACHED_VALUE_COMMANDS = frozenset({"date"})
+ATTACHED_VALUE_COMMANDS = frozenset({"date", "xxd"})
 """Commands whose short options swallow the rest of their word as a value.
 
 ``date -Iseconds`` is one option and its argument, not a cluster of five, so
 only its first letter may be read as a flag - otherwise the ``s`` of
 ``seconds`` matches ``date -s`` and a pure formatting call prompts every time.
+``xxd`` reads only the start of each word as well: ``-groupsize`` is not a
+``-r`` for the r inside it.
 """
 
 
@@ -764,7 +814,8 @@ def _has_flag(
     clustered (``sed -ni``). Only two-character flags take part in the attached
     and clustered readings - ``find``'s options are single-dash words, and
     scanning ``-depth`` for the letters of ``-delete`` would refuse commands that
-    write nothing.
+    write nothing. A long flag also matches when cut short, as
+    :func:`_abbreviates` describes.
 
     ``cluster_first_only`` narrows the clustered reading to the first letter, for
     commands where the rest of the word is that option's value rather than more
@@ -775,7 +826,8 @@ def _has_flag(
     for arg in args:
         if arg == "--":
             break  # everything after this is an operand, not an option
-        if arg.split("=", 1)[0] in flags:
+        name = arg.split("=", 1)[0]
+        if name in flags or any(_abbreviates(name, flag) for flag in flags):
             return True
         if not arg.startswith("-") or arg.startswith("--"):
             continue
@@ -787,6 +839,20 @@ def _has_flag(
     return False
 
 
+def _abbreviates(name: str, option: str) -> bool:
+    """True when ``name`` is the long ``option`` cut short: ``--compress`` for
+    ``--compress-program``.
+
+    getopt_long and git's option parser take any unambiguous prefix of a long
+    option as the option itself, so matching only the full spelling let ``sort
+    --compress=sh`` and ``git grep --open-files-in=sh`` run a program unprompted.
+    Every prefix counts, ambiguous or not: an ambiguous one is an error, and one
+    that is itself another whole option only prompts where it need not - never
+    the reverse.
+    """
+    return len(name) > 2 and name.startswith("--") and option.startswith(name) and name != option
+
+
 def _leading_letters(text: str) -> str:
     """The run of option letters at the head of a cluster - ``i`` of ``-i.bak``."""
     end = 0

hx_cli-0.2.17/src/hx/text.py

@@ -0,0 +1,12 @@
+"""Wording shared by the tools, the TUI and the CLI."""
+
+from __future__ import annotations
+
+
+def count(number: int, singular: str, plural: str | None = None) -> str:
+    """``1 line``, ``2 lines``: a number with its noun agreeing.
+
+    ``plural`` is for the nouns an ``s`` does not make plural - ``match``.
+    """
+    noun = singular if number == 1 else (plural or f"{singular}s")
+    return f"{number} {noun}"

{hx_cli-0.2.16 → hx_cli-0.2.17}/src/hx/tools/anchors.py

@@ -112,13 +112,12 @@ def resolve(lines: list[str], anchor: str) -> int:
     return matches[0]
 
 
-def replace_span(lines: list[str], start: int, end: int, replacement: str) -> list[str]:
-    """Replace ``lines[start:end + 1]`` with ``replacement`` split into lines.
+def replace_span(lines: list[str], start: int, end: int, replacement: list[str]) -> list[str]:
+    """Replace ``lines[start:end + 1]`` with the ``replacement`` lines.
 
     An empty replacement deletes the span rather than inserting a blank line.
     """
-    new_lines = replacement.split("\n") if replacement else []
-    return lines[:start] + new_lines + lines[end + 1 :]
+    return lines[:start] + replacement + lines[end + 1 :]
 
 
 class AnchorError(Exception):

{hx_cli-0.2.16 → hx_cli-0.2.17}/src/hx/tools/bash.py

@@ -9,9 +9,11 @@ policy requires :meth:`PersistentShell.restart`.
 from __future__ import annotations
 
 import asyncio
+import codecs
 import contextlib
 import os
 import secrets
+import shlex
 import signal
 import time
 import uuid
@@ -20,6 +22,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from hx.auth.resolve import PROVIDER_ENV
+from hx.text import count
 from hx.tools.base import Tool, ToolContext, ToolError, ToolResult
 from hx.tools.output import cap_output, summarize_for_ui
 
@@ -34,6 +38,20 @@ MAX_TIMEOUT = 600.0
 READ_CHUNK = 4096
 
 
+def command_environment(extra: dict[str, str] | None = None) -> dict[str, str]:
+    """The environment a command runs with: HX's own, minus HX's credentials.
+
+    The keys HX signs in with are HX's, not the project's. Inherited, they were
+    one auto-approved ``env`` away from the model's context - and from there one
+    request away from anywhere - which made denying ``~/.hx/auth.json`` to the
+    sandbox beside the point. Every variable HX reads a credential from is
+    withheld, the unprefixed fallbacks included.
+    """
+    withheld = {name for names in PROVIDER_ENV.values() for name in names}
+    inherited = {key: value for key, value in os.environ.items() if key not in withheld}
+    return {**inherited, **(extra or {})}
+
+
 @dataclass(slots=True)
 class ShellResult:
     stdout: str
@@ -61,7 +79,7 @@ class PersistentShell:
     ) -> None:
         self._cwd = cwd
         self.shell = shell or os.environ.get("SHELL") or "/bin/bash"
-        self.env = {**os.environ, **(env or {}), "HX": "1", "TERM": "dumb"}
+        self.env = command_environment({**(env or {}), "HX": "1", "TERM": "dumb"})
         self.sandbox = sandbox
         self._process: asyncio.subprocess.Process | None = None
         self._sentinel = f"__HX_DONE_{secrets.token_hex(8)}__"
@@ -121,11 +139,31 @@ class PersistentShell:
 
             # stderr is merged into stdout so the model sees what a user would.
             #
+            # The command reaches the shell as one single-quoted word handed to
+            # `eval`, with stdin from /dev/null. Written bare, it shared the
+            # shell's stdin with the control channel: a command that read it -
+            # `cat`, `read`, `ssh host ls` - ate the trailer below, and `cat`
+            # echoed it back, so the call "finished" while cat went on
+            # swallowing every later command. Evaluated, it still runs in this
+            # shell, so cd and exports persist; and an unclosed quote ends with
+            # the word instead of running on into the next command.
+            #
+            # Inline, not read back from a temp file. Reading it back needed
+            # `cat`, found on the session's PATH, so `PATH=/nonexistent` or a
+            # function named `cat` broke every later command - the one that
+            # would repair it included - while each reported success. And the
+            # file sat in $TMPDIR, which the sandbox lets commands write, so a
+            # job could change what ran after it was approved. Only builtins
+            # run here: `eval`, the redirect and `printf`.
+            #
             # The trailer carries the working directory as well as the status,
             # because a `cd` is the main thing that persists between calls and
             # nothing outside the shell could otherwise see it. `$PWD` is last
             # so a directory with spaces in it needs no quoting to parse.
-            payload = f'{command}\nprintf \'\\n%s %s %s\\n\' {self._sentinel} "$?" "$PWD"\n'
+            payload = (
+                f"eval {shlex.quote(command)} </dev/null\n"
+                f'printf \'\\n%s %s %s\\n\' {self._sentinel} "$?" "$PWD"\n'
+            )
             self._process.stdin.write(payload.encode())
             await self._process.stdin.drain()
 
@@ -156,6 +194,9 @@ class PersistentShell:
     async def _read_until_sentinel(self, timeout_seconds: float) -> AsyncIterator[str]:
         assert self._process is not None and self._process.stdout is not None
         stdout = self._process.stdout
+        # Incremental, so a character split across two reads is decoded whole
+        # rather than as two replacement characters.
+        decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
         buffer = ""
         deadline = time.monotonic() + timeout_seconds
 
@@ -173,11 +214,12 @@ class PersistentShell:
                 self._exit_code = (
                     self._process.returncode if self._process.returncode is not None else 1
                 )
+                buffer += decoder.decode(b"", final=True)
                 if buffer:
                     yield buffer
                 return
 
-            buffer += data.decode(errors="replace")
+            buffer += decoder.decode(data)
             if self._sentinel in buffer:
                 head, _, tail = buffer.partition(self._sentinel)
                 self._exit_code, self._cwd = _parse_trailer(tail, self._cwd)
@@ -286,8 +328,16 @@ class BackgroundJobs:
         self.log_dir = log_dir
         self._jobs: dict[str, BackgroundJob] = {}
 
-    async def start(self, command: str, cwd: Path, sandbox: Any | None = None) -> str:
-        """Returns a job id the model can poll."""
+    async def start(
+        self, command: str, cwd: Path, env: dict[str, str], sandbox: Any | None = None
+    ) -> str:
+        """Returns a job id the model can poll.
+
+        ``env`` is the persistent shell's, so a command sees the same ``HX`` and
+        ``TERM`` whichever way it runs: with the terminal's own ``TERM``, a tool
+        coloured its output in the background and wrote the escapes into the
+        log the model reads back.
+        """
         job_id = f"bg_{uuid.uuid4().hex[:8]}"
         self.log_dir.mkdir(parents=True, exist_ok=True)
         log_path = self.log_dir / f"{job_id}.log"
@@ -300,12 +350,18 @@ class BackgroundJobs:
         # the subprocess, so holding the parent's copy keeps one open per job
         # for the life of the session and buys nothing - the log is read back
         # by path.
+        #
+        # stdin is /dev/null, not HX's own: inherited, it is the terminal the
+        # prompt reads from, and a dev server with keyboard shortcuts would
+        # take keystrokes meant for HX - or put the terminal into raw mode.
         with log_path.open("wb") as handle:
             process = await asyncio.create_subprocess_exec(
                 *argv,
+                stdin=asyncio.subprocess.DEVNULL,
                 stdout=handle,
                 stderr=asyncio.subprocess.STDOUT,
                 cwd=cwd,
+                env=env,
                 start_new_session=True,
             )
         self._jobs[job_id] = BackgroundJob(job_id, command, process, log_path)
@@ -424,7 +480,9 @@ class BashTool(Tool):
             # The shell's directory, not the session's: `cd build && make` in
             # one call then a background `./run` in the next has to mean the
             # same thing it would in a terminal.
-            job_id = await self.jobs.start(command, self.shell.cwd, self.shell.sandbox)
+            job_id = await self.jobs.start(
+                command, self.shell.cwd, self.shell.env, self.shell.sandbox
+            )
             return ToolResult(
                 content=(
                     f"Started background job {job_id}.\n"
@@ -543,7 +601,7 @@ class BashOutputTool(Tool):
         return ToolResult(
             content=body,
             spilled_path=capped.spilled_path,
-            summary=f"{next_line} lines, {'running' if status['running'] else 'finished'}",
+            summary=f"{count(next_line, 'line')}, {'running' if status['running'] else 'finished'}",
             metadata={"next_line": next_line, **status},
         )